@flexzap/overlay

Flexible and reusable overlay components for Angular applications. Part of the FlexZap Library ecosystem.

Installation

npm install @flexzap/overlay

Peer Dependencies

This library requires the following peer dependencies:

npm install @angular/common@^21.0.0 @angular/core@^21.0.0

Usage

Basic Implementation

import { Component } from '@angular/core';
import { ZapTooltip } from '@flexzap/overlay';

@Component({
  imports: [ZapTooltip],
  template: `
    <button (mouseenter)="isVisible = true" (mouseleave)="isVisible = false">
      Hover Me
      <zap-tooltip [visible]="isVisible" [position]="'top'"> Tooltip Content </zap-tooltip>
    </button>
  `
})
export class MyComponent {
  isVisible = false;
}

Directive Implementation (Recommended)

The ZapTooltipBind directive simplifies usage by automatically handling hover events for sibling tooltips.

import { Component } from '@angular/core';
import { ZapTooltip, ZapTooltipBind } from '@flexzap/overlay';

@Component({
  imports: [ZapTooltip, ZapTooltipBind],
  template: `
    <button>
      <span ZapTooltipBind>Hover Me</span>
      <zap-tooltip [position]="'right'"> Tooltip Content </zap-tooltip>
    </button>
  `
})
export class MyComponent {}

API Reference

ZapTooltip Component

A lightweight tooltip component that positions itself relative to its container.

Inputs

| Property | Type | Default | Description | | ---------- | ---------------------------------------- | ------------ | ----------------------------------------------------- | | position | 'top' \| 'right' \| 'bottom' \| 'left' | Required | Sets the position of the tooltip relative to the host | | visible | boolean | false | Controls the visibility of the tooltip |

ZapTooltipBind Directive

A helper directive that binds hover events (mouseenter, mouseleave) to toggle the visibility of sibling zap-tooltip components.

Selector: [ZapTooltipBind]

ZapModalShell Component

A modal shell component that displays content over a backdrop. It handles closing interactions (Escape key, close button, backdrop click) by emitting a close event, allowing the parent to control visibility state.

Inputs

| Property | Type | Default | Description | | --------- | --------- | ------------ | ------------------------------------------ | | visible | boolean | Required | Controls the visibility of the modal shell |

Outputs

| Property | Type | Description | | -------- | ------ | ------------------------------------------------------------------------------------ | | close | void | Emits when the modal requests to close (e.g. Escape key, close icon, backdrop click) |

Example Usage

@Component({
  imports: [ZapModalShell, ZapButton],
  template: `
    <zap-button (clicked)="showModal.set(true)">Open Modal</zap-button>

    <zap-modal-shell [visible]="showModal()" (close)="showModal.set(false)">
      <h2>My Modal</h2>
      <p>Content goes here.</p>
    </zap-modal-shell>
  `
})
export class MyComponent {
  showModal = signal(false);
}

Styling

The component uses SCSS for styling. You can customize the appearance by overriding the default styles:

zap-tooltip {
  // Custom tooltip styles
  --zap-tooltip-bg-color: #333;
  --zap-tooltip-text-color: #fff;
}

Testing

This library uses Jest for unit testing with zoneless Angular configuration.

Running Tests

# From the monorepo root
npm run overlay:test            # Run all unit tests with coverage
npm run overlay:test:watch      # Run tests in watch mode (no coverage)

Development

Building the Library

# From the monorepo root
npm run overlay:build       # Build the library
ng build @flexzap/overlay   # Build directly using CLI

Code Scaffolding

To generate new components within this library:

ng generate component [component-name] --project @flexzap/overlay

Publishing

Build for Publication

# From the monorepo root
npm run overlay:build

Publish to NPM

cd dist/flexzap/overlay
npm publish --access public

Contributing

This library is part of the FlexZap Library monorepo. Please refer to the main repository for contribution guidelines.

License

MIT License - see the LICENSE file for details.