@frame-kit/ui-ng 0.0.3 → 0.0.4

package/services/overlay-orchestrator/README.md

@@ -1,184 +0,0 @@
-# OverlayOrchestrator
-
-A centralized service for managing overlay interactions (dialogs, drawers, popovers, navigation panels, tooltips) using a priority-based stack. Prevents UI conflicts like drawers staying open behind dialogs, or menus persisting when modals appear.
-
----
-
-## Initialization
-
-The `OverlayOrchestrator` is provided at the root level (`providedIn: 'root'`). No setup is needed — inject it wherever you need overlay coordination.
-
-```ts
-import { OverlayOrchestrator, OVERLAY_PRIORITY } from '@frame-kit/ui-ng';
-```
-
-### Built-in Integration
-
-`DialogService` and `DrawerService` automatically register with the orchestrator. Opening a dialog auto-closes any open drawer or popover. Opening a drawer auto-closes any open popover. No consumer code is needed for these — it works out of the box.
-
-### Registering Custom Overlays
-
-For overlays not managed by `DialogService` or `DrawerService` (e.g., custom popovers, app navigation panels, kebab menus), register them manually:
-
-```ts
-@Component({ ... })
-export class MyComponent {
-  private readonly orchestrator = inject(OverlayOrchestrator);
-  private overlayId: string | null = null;
-
-  open(): void {
-    // Register with a priority — closes all lower-priority overlays
-    this.overlayId = this.orchestrator.register({
-      priority: OVERLAY_PRIORITY.POPOVER,
-      type: "my-popover",
-      close: () => this.close(),
-    });
-  }
-
-  close(): void {
-    if (this.overlayId) {
-      this.orchestrator.unregister(this.overlayId);
-      this.overlayId = null;
-    }
-
-    // ... your close logic
-  }
-}
-```
-
-### Registering App Navigation
-
-The app shell sidebar should register at the highest priority so it always opens on top:
-
-```ts
-@Component({ ... })
-export class AppShellComponent {
-  private readonly orchestrator = inject(OverlayOrchestrator);
-  private navOverlayId: string | null = null;
-
-  openNav(): void {
-    this.navOverlayId = this.orchestrator.register({
-      priority: OVERLAY_PRIORITY.NAVIGATION,
-      type: "navigation",
-      close: () => this.closeNav(),
-    });
-  }
-
-  closeNav(): void {
-    if (this.navOverlayId) {
-      this.orchestrator.unregister(this.navOverlayId);
-      this.navOverlayId = null;
-    }
-
-    // ... your close logic
-  }
-}
-```
-
-### Guarding Before Opening
-
-Check if a higher-priority overlay is already open before opening yours:
-
-```ts
-if (!this.orchestrator.hasOverlayAtOrAbove(OVERLAY_PRIORITY.DIALOG)) {
-  this.openDrawer();
-}
-```
-
----
-
-## API
-
-### OverlayOrchestrator (Injectable)
-
-#### Methods
-
-| Method                | Signature                                     | Description                                                                    |
-| --------------------- | --------------------------------------------- | ------------------------------------------------------------------------------ |
-| `register`            | `(entry: Omit<OverlayEntry, 'id'>) => string` | Register an overlay. Auto-closes lower-priority overlays. Returns a unique ID. |
-| `unregister`          | `(id: string) => void`                        | Remove an overlay by ID. Call when the overlay closes.                         |
-| `closeAll`            | `() => void`                                  | Close all overlays, lowest priority first.                                     |
-| `closeAtOrBelow`      | `(priority: number) => void`                  | Close all overlays at or below the given priority.                             |
-| `hasOverlayAtOrAbove` | `(priority: number) => boolean`               | Check if any overlay at or above a priority is open.                           |
-| `hasOverlayOfType`    | `(type: string) => boolean`                   | Check if any overlay of a given type is open.                                  |
-
-#### Signals (Reactive)
-
-| Signal             | Type                           | Description                        |
-| ------------------ | ------------------------------ | ---------------------------------- |
-| `hasActiveOverlay` | `Signal<boolean>`              | Whether any overlay is open.       |
-| `topOverlay`       | `Signal<OverlayEntry \| null>` | The highest-priority open overlay. |
-| `count`            | `Signal<number>`               | Number of active overlays.         |
-
----
-
-## Priority Levels
-
-Default priority constants are provided via `OVERLAY_PRIORITY`. You can use any number — these are conventions, not constraints.
-
-```ts
-import { OVERLAY_PRIORITY } from '@frame-kit/ui-ng';
-
-OVERLAY_PRIORITY.TOOLTIP; // 0  — tooltips, inline hints
-OVERLAY_PRIORITY.POPOVER; // 10 — dropdown menus, kebab menus
-OVERLAY_PRIORITY.DRAWER; // 20 — side panels, detail drawers
-OVERLAY_PRIORITY.DIALOG; // 30 — modal dialogs, confirmations
-OVERLAY_PRIORITY.NAVIGATION; // 40 — app-level navigation sidebar
-```
-
-### Custom Priorities
-
-Use any number to fine-tune behavior:
-
-```ts
-// A toast notification that sits between popover and drawer
-orchestrator.register({
-  priority: 15,
-  type: 'toast',
-  close: () => this.dismissToast(),
-});
-```
-
----
-
-## OverlayEntry Interface
-
-```ts
-interface OverlayEntry {
-  id: string; // Auto-generated unique ID
-  priority: number; // Higher = stays open longer
-  type: string; // Label for debugging/querying
-  close: () => void; // Called by orchestrator to close
-}
-```
-
----
-
-## Behavior Rules
-
-1. **Opening a new overlay closes all overlays with LOWER priority.**
-   - Opening a dialog (30) closes drawers (20), popovers (10), tooltips (0).
-   - Opening a drawer (20) closes popovers (10) and tooltips (0).
-   - Opening the nav (40) does not close dialogs (30) — they have lower priority.
-
-2. **Overlays with EQUAL or HIGHER priority are left open.**
-   - Opening a second dialog does not close the first dialog.
-   - Opening the nav while a dialog is open leaves the dialog open.
-
-3. **Unregistration is the consumer's responsibility.**
-   - The orchestrator calls `close()` on entries to request closure.
-   - The consumer must call `unregister(id)` when the overlay actually closes.
-   - `DialogService` and `DrawerService` handle this automatically.
-
-4. **Priority is set per instance, not per type.**
-   - The same component can register at different priorities depending on context.
-   - A critical confirmation dialog could register at 35 to stay above normal dialogs.
-
----
-
-## Import
-
-```ts
-import { OverlayOrchestrator, OVERLAY_PRIORITY } from '@frame-kit/ui-ng';
-import type { OverlayEntry } from '@frame-kit/ui-ng';
-```

package/types/frame-kit-ui-ng-services-overlay-orchestrator.d.ts

@@ -1,96 +0,0 @@
-import * as _angular_core from '@angular/core';
-
-/**
- * Default priority levels for common overlay types.
- * Higher number = higher priority = stays open when lower-priority overlays open.
- *
- * Consumers can use any number — these are conventions, not constraints.
- */
-declare const OVERLAY_PRIORITY: {
-    /** Tooltips, inline popovers */
-    readonly TOOLTIP: 0;
-    /** Dropdown menus, kebab menus, popovers */
-    readonly POPOVER: 10;
-    /** Side panels, detail drawers */
-    readonly DRAWER: 20;
-    /** Modal dialogs, confirmations */
-    readonly DIALOG: 30;
-    /** App-level navigation (sidebar, mobile nav) */
-    readonly NAVIGATION: 40;
-};
-interface OverlayEntry {
-    /** Unique identifier for this overlay instance */
-    id: string;
-    /** Priority level — higher stays open, lower gets closed */
-    priority: number;
-    /** Overlay type label (for debugging/logging) */
-    type: string;
-    /** Called by the orchestrator to close this overlay */
-    close: () => void;
-}
-
-/**
- * Centralized overlay orchestrator.
- *
- * Tracks all open overlays (dialogs, drawers, popovers, navigation, tooltips)
- * in a priority-based stack. When a new overlay opens:
- *
- * - All overlays with LOWER priority are closed automatically.
- * - Overlays with EQUAL or HIGHER priority are left open.
- *
- * This prevents UI conflicts like drawers staying open behind dialogs,
- * or kebab menus persisting when a modal pops up.
- *
- * @example
- * ```ts
- * const id = orchestrator.register({
- *   priority: OVERLAY_PRIORITY.DRAWER,
- *   type: 'drawer',
- *   close: () => drawerRef.close(),
- * });
- *
- * // Later, when the overlay closes:
- * orchestrator.unregister(id);
- * ```
- */
-declare class OverlayOrchestrator {
-    private readonly entries;
-    /** Whether any overlay is currently open. */
-    readonly hasActiveOverlay: _angular_core.Signal<boolean>;
-    /** The topmost (highest priority) overlay. */
-    readonly topOverlay: _angular_core.Signal<OverlayEntry | null>;
-    /** Current number of active overlays. */
-    readonly count: _angular_core.Signal<number>;
-    /**
-     * Register an overlay and close all overlays with lower priority.
-     *
-     * @returns The unique overlay ID — pass this to `unregister()` when closing.
-     */
-    register(entry: Omit<OverlayEntry, 'id'>): string;
-    /**
-     * Unregister an overlay by ID. Call this when the overlay closes.
-     */
-    unregister(id: string): void;
-    /**
-     * Check if an overlay with the given priority or higher is currently open.
-     * Useful for guards that want to prevent opening lower-priority overlays.
-     */
-    hasOverlayAtOrAbove(priority: number): boolean;
-    /**
-     * Check if any overlay of a specific type is open.
-     */
-    hasOverlayOfType(type: string): boolean;
-    /**
-     * Close all overlays. Closes from lowest to highest priority.
-     */
-    closeAll(): void;
-    /**
-     * Close all overlays at or below the given priority.
-     */
-    closeAtOrBelow(priority: number): void;
-    static ɵfac: _angular_core.ɵɵFactoryDeclaration<OverlayOrchestrator, never>;
-    static ɵprov: _angular_core.ɵɵInjectableDeclaration<OverlayOrchestrator>;
-}
-
-export { OVERLAY_PRIORITY, OverlayOrchestrator };
-export type { OverlayEntry };