@mhmo91/schmancy 0.9.12 → 0.9.14

package/src/overlay/overlay.types.ts

@@ -0,0 +1,146 @@
+import type { TemplateResult } from 'lit'
+import type { Observable } from 'rxjs'
+import type { ComponentType } from '../area/router.types'
+import type { THistoryStrategy } from '../area/router.types'
+
+/**
+ * What the caller is showing. Flat union — `typeof`-discriminated at runtime.
+ * Reuses area's `ComponentType` (class | tag name | HTMLElement | lazy loader)
+ * and adds Lit `TemplateResult` for inline templates.
+ *
+ * The common case is one positional arg: `show(MyEditor)`, `show(html\`...\`)`,
+ * `show(el)`, `show('my-tag')`, `show(lazy(() => import('./x')))`.
+ */
+export type Content = ComponentType | TemplateResult
+
+/**
+ * Anchor hint for positioning. When provided, the layout engine tries to
+ * anchor the overlay near this point via Floating UI / CSS Anchor Positioning.
+ * Falls back to centered / sheet if the anchored position can't fit.
+ *
+ * `MouseEvent | TouchEvent` — idiomatic: pass the event that triggered the show.
+ * `HTMLElement` — anchor to the element's bounding box (menus, tooltips).
+ * `{ x, y }` — explicit coordinates (rare; for programmatic positioning).
+ */
+export type Anchor = MouseEvent | HTMLElement | { x: number; y: number }
+
+/**
+ * How the overlay should behave. All optional; the system handles every
+ * layout decision itself.
+ */
+export interface ShowOptions {
+	/** Props to merge into the mounted component. Only meaningful when
+	 *  `content` is a class, tag, or lazy loader. */
+	props?: Record<string, unknown>
+
+	/** Anchor hint — triggers anchored layout (the novel default) when passed.
+	 *  Pass the MouseEvent that opened the overlay. */
+	anchor?: Anchor
+
+	/** Default `true`. `false` blocks Esc / backdrop click / swipe / popstate.
+	 *  Programmatic dismiss (sub.unsubscribe / dismissAll) always works. */
+	dismissable?: boolean
+
+	/** Default `false`. Keep DOM between successive shows with the same
+	 *  content — reuse cached mount instead of reconstructing. */
+	persist?: boolean
+
+	/** Standard web-platform cancellation input. Composes with fetch,
+	 *  addEventListener, getUserMedia, etc. When signal aborts, overlay
+	 *  dismisses (same as unsubscribe). */
+	signal?: AbortSignal
+
+	/** Rare escape hatch. Defaults: `false` for anchored, `true` for
+	 *  centered/sheet. Setting `modal: true` on an anchored overlay forces
+	 *  <dialog>.showModal() semantics (focus trap + background inert) —
+	 *  use for destructive-confirm menus. */
+	modal?: boolean
+
+	/** Default `'push'`. Same vocabulary as `area.push()`.
+	 *  - `'push'` — new history entry; back dismisses, forward re-opens.
+	 *  - `'replace'` — replace current entry; back skips the overlay.
+	 *  - `'silent'` — no history; for tooltips / transient / ephemeral UI. */
+	historyStrategy?: THistoryStrategy
+}
+
+/**
+ * Resolved layout. Pure output of the dispatch engine; callers never pick.
+ * - `'centered'`  — native <dialog>.showModal(), focus-trapped.
+ * - `'anchored'`  — popover="auto" + CSS Anchor Positioning / Floating UI,
+ *                    non-modal, background stays interactive.
+ * - `'sheet'`     — native <dialog>.showModal() as a bottom sheet,
+ *                    swipe-to-dismiss, safe-area aware.
+ */
+export type OverlayLayout = 'centered' | 'anchored' | 'sheet'
+
+/**
+ * Read-only snapshot of an active overlay. Emitted as part of the
+ * `openOverlays$` stream for stack introspection.
+ */
+export interface OverlayEntry {
+	/** Internal id (auto-generated uuid). Exposed for debugging / devtools.
+	 *  Not a public identifier — callers use the Subscription for identity. */
+	readonly id: string
+	/** The mounted `<schmancy-overlay>` element. Escape hatch for DOM access. */
+	readonly element: HTMLElement
+	/** Current layout, chosen by the dispatch engine. */
+	readonly layout: OverlayLayout
+}
+
+/**
+ * Reason the overlay closed. Emitted on the internal close-event `detail`
+ * for consumers who need to distinguish user-dismiss from programmatic
+ * dismiss from form submission.
+ */
+export type CloseReason =
+	| 'structured'      // content dispatched CustomEvent('close', { detail })
+	| 'native-submit'   // <form method="dialog"> committed a returnValue
+	| 'escape'          // user pressed Escape
+	| 'backdrop'        // user clicked outside the overlay
+	| 'swipe'           // user swiped a bottom sheet down
+	| 'popstate'        // user hit back button / hardware back
+	| 'light-dismiss'   // popover light-dismiss (clicked outside anchored overlay)
+	| 'programmatic'    // sub.unsubscribe() / dismissAll()
+	| 'abort'           // AbortSignal aborted
+
+/**
+ * Options for confirm() / danger() / ask() sugar.
+ */
+export interface OverlayConfirmOptions {
+	title?: string
+	subtitle?: string
+	message?: string
+	/** Default `'Confirm'`. */
+	confirmText?: string
+	/** Default `'Cancel'`. */
+	cancelText?: string
+	/** `'danger'` flips the confirm button to destructive styling and
+	 *  sets `role="alertdialog"`. */
+	variant?: 'default' | 'danger'
+	/** Anchor hint — same semantics as `show()`. */
+	anchor?: Anchor
+	/** Standard cancellation input. */
+	signal?: AbortSignal
+}
+
+/**
+ * Options for prompt() sugar.
+ */
+export interface OverlayPromptOptions extends OverlayConfirmOptions {
+	label?: string
+	defaultValue?: string
+	placeholder?: string
+	inputType?: 'text' | 'email' | 'number' | 'password' | 'url' | 'tel'
+	/** Optional HTML5 validation pattern applied to the input. */
+	pattern?: string
+	required?: boolean
+}
+
+/**
+ * Signature of the primary verb — declared here for consumption by the
+ * service and the skill docs. Cold Observable; subscription IS the lifecycle.
+ */
+export type ShowFn = <T = void>(
+	content: Content,
+	options?: ShowOptions,
+) => Observable<T | undefined>

package/src/sheet/sheet.service.ts

@@ -232,4 +232,14 @@ class BottomSheetService {
 	}
 
 }
+
+/**
+ * Bottom / side sheet service. Mounts any element as a sheet with a chosen
+ * position (see `SchmancySheetPosition` enum).
+ *
+ * @service
+ * @summary Imperative bottom / side sheet surface.
+ * @method open({ component, position? }) - Mount an element as a sheet.
+ * @method dismiss(id?) - Dismiss a sheet by id, or the topmost.
+ */
 export const sheet = new BottomSheetService()

package/src/theme/theme.service.ts

@@ -514,7 +514,17 @@ class ThemeService {
   }
 }
 
-// Export singleton instance
+/**
+ * Theme singleton. Reads and mutates the active theme (scheme, source color,
+ * locale); persists the user's scheme choice. Components subscribe via
+ * `theme.theme$` for changes.
+ *
+ * @service
+ * @summary Theme service — active scheme, source color, locale.
+ * @method next({ scheme?, source?, locale? }) - Update theme state.
+ * @method theme$ - Observable<TSchmancyTheme>; emits on every theme change.
+ * @method toggle() - Toggle between light and dark schemes.
+ */
 export const theme = ThemeService.getInstance()
 export const schmancyTheme = theme // Alias for convenience
 export default theme

package/types/src/agent/agent-bundle.test.d.ts

@@ -0,0 +1 @@
+import './agent-entry';

package/types/src/agent/agent-entry.d.ts

@@ -0,0 +1,4 @@
+import '../index';
+import './schmancy-skill';
+export { $dialog, $notify, sheet, SchmancySheetPosition, schmancyContentDrawer, theme, area, lazy, createContext, select, selectItem, } from '../index';
+export { $LitElement } from '../../mixins/index';

package/types/src/agent/helpers.d.ts

@@ -0,0 +1,87 @@
+import manifest from 'virtual:schmancy-manifest';
+export type Manifest = typeof manifest;
+export type ElementEntry = {
+    kind: 'class';
+    name: string;
+    tagName?: string;
+    description?: string;
+    summary?: string;
+    attributes?: Array<{
+        name: string;
+        description?: string;
+        type?: {
+            text?: string;
+        };
+        default?: string;
+        values?: string[];
+    }>;
+    events?: Array<{
+        name: string;
+        description?: string;
+        type?: {
+            text?: string;
+        };
+    }>;
+    slots?: Array<{
+        name: string;
+        description?: string;
+    }>;
+    cssProperties?: Array<{
+        name: string;
+        description?: string;
+    }>;
+    cssParts?: Array<{
+        name: string;
+        description?: string;
+    }>;
+    whenToUse?: string;
+    platformPrimitive?: {
+        tag: string;
+        mode?: string;
+        note?: string;
+    };
+    contexts?: {
+        provides?: string[];
+        consumes?: string[];
+    };
+};
+export type ServiceEntry = {
+    kind: 'variable';
+    name: string;
+    description?: string;
+    summary?: string;
+    service: true;
+    methods?: Array<{
+        signature: string;
+        summary?: string;
+    }>;
+};
+export declare function help(tag?: string): unknown;
+export declare function tokens(): string[];
+export declare function platformPrimitive(tag: string): ElementEntry['platformPrimitive'] | null;
+export declare function registeredTags(): string[];
+export declare function a11yAudit(): Array<{
+    tag: string;
+    role: string | null;
+    ariaLabel: string | null;
+    hasShadowRoot: boolean;
+    formAssociated: boolean;
+}>;
+export type Capabilities = {
+    popover: boolean;
+    declarativeShadowDom: boolean;
+    scopedRegistries: boolean;
+    trustedTypes: boolean;
+    cssRegisteredProperties: boolean;
+    elementInternalsAria: boolean;
+    formAssociated: boolean;
+    adoptedStyleSheets: boolean;
+};
+/**
+ * Runtime feature probe. Tells an agent which platform capabilities the
+ * current sandbox exposes, so it can adapt without assuming the sandbox CSP
+ * or browser version. Every check is feature-detect, not UA-sniff.
+ */
+export declare function capabilities(): Capabilities;
+export declare function manifestUrl(): string;
+export { manifest };

package/types/src/agent/index.d.ts

@@ -0,0 +1 @@
+export * from './schmancy-skill';

package/types/src/agent/schmancy-skill.d.ts

@@ -0,0 +1,33 @@
+import { a11yAudit, capabilities, help, manifest, platformPrimitive, registeredTags, tokens } from './helpers';
+declare global {
+    interface Window {
+        schmancy?: {
+            manifest: typeof manifest;
+            manifestUrl: string;
+            help: typeof help;
+            tokens: typeof tokens;
+            platformPrimitive: typeof platformPrimitive;
+            registeredTags: typeof registeredTags;
+            a11yAudit: typeof a11yAudit;
+            capabilities: typeof capabilities;
+        };
+    }
+}
+declare const SchmancySkill_base: CustomElementConstructor & import("../../mixins/constructor").Constructor<import("lit").LitElement> & import("../../mixins/constructor").Constructor<import("../../mixins/baseElement").IBaseMixin>;
+/**
+ * Self-describing runtime helper. Drop `<schmancy-skill></schmancy-skill>`
+ * once on a page and `window.schmancy.help('schmancy-button')` returns the
+ * machine-readable entry for any tag. Renders nothing.
+ *
+ * @element schmancy-skill
+ */
+export declare class SchmancySkill extends SchmancySkill_base {
+    connectedCallback(): void;
+    render(): import("lit-html").TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'schmancy-skill': SchmancySkill;
+    }
+}
+export {};

package/types/src/area/area.service.d.ts

@@ -130,5 +130,16 @@ declare class AreaService implements AreaSubscription {
      */
     getRoute(areaName: string): ActiveRoute | undefined;
 }
+/**
+ * Area router singleton. Drives named `<schmancy-area>` outlets in the DOM
+ * — imperative push / pop, URL-synced, state-restoring. Pair with
+ * `lazy(() => import('./view'))` for code-split routes.
+ *
+ * @service
+ * @summary Imperative outlet-based router for `<schmancy-area>` elements.
+ * @method push({ area, component, params?, state? }) - Navigate an area to a component.
+ * @method pop(areaName) - Pop the top entry off an area's stack.
+ * @method current$(areaName) - Observable of the active route state for an area.
+ */
 export declare const area: AreaService;
 export default area;

package/types/src/content-drawer/drawer.service.d.ts

@@ -36,5 +36,14 @@ declare class DrawerService {
      */
     push(options: DrawerPushOptions): void;
 }
+/**
+ * Content-drawer service. Mounts any element inside the right-hand content
+ * drawer of a `<schmancy-content-drawer>` layout.
+ *
+ * @service
+ * @summary Imperative content-drawer (right-side navigation panel).
+ * @method render({ component, ...options }) - Mount an element in the drawer.
+ * @method close() - Close the drawer.
+ */
 export declare const schmancyContentDrawer: DrawerService;
 export {};

package/types/src/dialog/dialog-service.d.ts

@@ -67,7 +67,17 @@ export declare class DialogService {
     private getDefaultPosition;
 }
 /**
- * Global dialog utility
+ * Global dialog utility. Imperative modal API — open any element as a dialog,
+ * or use the built-in `confirm` / `ask` / `danger` prompts. Returns Promises
+ * that resolve when the user picks an action.
+ *
+ * @service
+ * @summary Imperative modal dialogs and built-in confirm/ask/danger prompts.
+ * @method confirm(options: DialogOptions) - Built-in confirm prompt. Returns Promise<boolean>.
+ * @method ask(message, event?) - One-line yes/no prompt anchored to the triggering event.
+ * @method danger(options) - Destructive-action confirm styled with the error palette.
+ * @method component(element, options?) - Open any element as a modal.
+ * @method dismiss(id?) - Dismiss a dialog by id, or the topmost dialog.
  */
 export declare const $dialog: {
     confirm: (options: DialogOptions) => Promise<boolean>;

package/types/src/notification/notification-service.d.ts

@@ -64,7 +64,17 @@ export declare class NotificationService {
     persistent(message: string, options?: Partial<Omit<NotificationOptions, 'message' | 'duration'>>): string;
 }
 /**
- * Global notification utility - provides a quick way to show notifications
+ * Global notification (toast) utility. Fire-and-forget API for success,
+ * error, info, and warning toasts, plus a low-level `show` for custom
+ * notifications.
+ *
+ * @service
+ * @summary Toast notifications — success, error, info, warning.
+ * @method show(options: NotificationOptions) - Low-level; show any NotificationOptions.
+ * @method success(message, options?) - Green success toast.
+ * @method error(message, options?) - Red error toast.
+ * @method info(message, options?) - Blue informational toast.
+ * @method warning(message, options?) - Amber warning toast.
  */
 export declare const $notify: {
     /**

package/types/src/overlay/index.d.ts

@@ -0,0 +1,5 @@
+export * from './overlay.component';
+export * from './overlay.confirm-body';
+export * from './overlay.service';
+export type { Anchor, CloseReason, Content, OverlayConfirmOptions, OverlayEntry, OverlayLayout, OverlayPromptOptions, ShowFn, ShowOptions, } from './overlay.types';
+export { lazy } from '../area/lazy';

package/types/src/overlay/overlay.animations.d.ts

@@ -0,0 +1,26 @@
+import type { OverlayLayout } from './overlay.types';
+/**
+ * WAAPI keyframes + options per layout + direction.
+ *
+ * One animation vocabulary — no per-element bespoke keyframes. Aligns
+ * with the `animation` skill (spring physics presets). Honors
+ * `prefers-reduced-motion` by collapsing transforms to opacity-only.
+ *
+ * Returns `null` when reduced-motion is active and only opacity change
+ * is needed — the caller sets style directly.
+ */
+/**
+ * Shape matches both DOM `AnimationEffectTiming` and
+ * `KeyframeAnimationOptions` so it passes structural checks in both
+ * older and newer `lib.dom.d.ts` vintages.
+ */
+export interface AnimationSpec {
+    keyframes: Keyframe[];
+    options: {
+        duration: number;
+        easing: string;
+        fill?: FillMode;
+    };
+}
+export declare function backdropAnimation(direction: 'in' | 'out'): AnimationSpec;
+export declare function surfaceAnimation(layout: OverlayLayout, direction: 'in' | 'out'): AnimationSpec;

package/types/src/overlay/overlay.component.d.ts

@@ -0,0 +1,48 @@
+import { type TemplateResult } from 'lit';
+import type { CloseReason, Content, OverlayLayout, ShowOptions } from './overlay.types';
+declare const SchmancyOverlay_base: CustomElementConstructor & import("@mixins/index").Constructor<import("lit").LitElement> & import("@mixins/index").Constructor<import("@mixins/index").IBaseMixin>;
+/**
+ * The single overlay element. Hosts a native `<dialog>` in its shadow
+ * root for centered/sheet layouts; for anchored, we stay modeless by
+ * using `<dialog>` with .show() (non-modal) + explicit positioning.
+ *
+ * Public lifecycle: the service calls `open()` to mount content and
+ * animate in, `close(reason)` to animate out and dismiss. The element
+ * dispatches `overlay-close` when closed; the service listens and
+ * resolves the caller's Observable.
+ */
+export declare class SchmancyOverlay extends SchmancyOverlay_base {
+    layout: OverlayLayout;
+    dismissable: boolean;
+    modal: boolean;
+    private _dialog;
+    private _surface;
+    /** Close trigger for the service; emits the reason + detail payload. */
+    private readonly _closed$;
+    private _mounted;
+    private _closing;
+    /** Service subscribes to this to know when the overlay dismissed. */
+    get closed$(): import('rxjs').Observable<{
+        reason: CloseReason;
+        result?: unknown;
+    }>;
+    /**
+     * Mount content and animate in. Called by the service after the
+     * element is attached to the DOM. Returns a promise that resolves
+     * when the entrance animation completes.
+     */
+    open(content: Content, options: ShowOptions): Promise<void>;
+    /** Play exit animations then close the native dialog. */
+    close(reason: CloseReason, result?: unknown): Promise<void>;
+    private wireCloseTriggers;
+    private positionAnchored;
+    private playEnterAnimations;
+    private playExitAnimations;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'schmancy-overlay': SchmancyOverlay;
+    }
+}
+export {};

package/types/src/overlay/overlay.confirm-body.d.ts

@@ -0,0 +1,42 @@
+import { type TemplateResult } from 'lit';
+declare const SchmancyOverlayPromptBody_base: CustomElementConstructor & import("@mixins/index").Constructor<import("lit").LitElement> & import("@mixins/index").Constructor<import("@mixins/index").IBaseMixin>;
+/**
+ * Internal body component used by the `confirm()` / `prompt()` sugar.
+ *
+ * Minimal, dependency-free — plain HTML buttons / input so this file
+ * doesn't need to import schmancy-form / schmancy-button (avoids the
+ * risk of circular module graphs during early imports of $overlay).
+ *
+ * Emits a `close` CustomEvent with the typed result; the overlay picks
+ * that up as the primary return channel. For custom-styled confirms,
+ * callers pass their own component to `show()`.
+ */
+export declare class SchmancyOverlayPromptBody extends SchmancyOverlayPromptBody_base {
+    heading?: string;
+    subtitle?: string;
+    message?: string;
+    confirmText: string;
+    cancelText: string;
+    variant: 'default' | 'danger';
+    /** Presence of `mode` switches between confirm (boolean) and prompt (string). */
+    mode: 'confirm' | 'prompt';
+    label?: string;
+    defaultValue: string;
+    placeholder?: string;
+    inputType: string;
+    pattern?: string;
+    required: boolean;
+    private _input?;
+    firstUpdated(): void;
+    private dismiss;
+    private handleCancel;
+    private handleConfirm;
+    private handleSubmit;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'schmancy-overlay-prompt-body': SchmancyOverlayPromptBody;
+    }
+}
+export {};

package/types/src/overlay/overlay.gestures.d.ts

@@ -0,0 +1,39 @@
+import { Observable } from 'rxjs';
+/**
+ * Swipe-to-dismiss gesture for sheet-layout overlays.
+ *
+ * RxJS-native (rxjs skill principle 3: every async source is an Observable).
+ * Returns an Observable that emits `'dismiss'` when the gesture passes the
+ * distance/velocity threshold. Caller maps emissions to teardown.
+ *
+ * Thresholds are policy constants, not magic numbers.
+ */
+/** Distance beyond which the gesture dismisses, in px. */
+export declare const DISMISS_DISTANCE_PX = 80;
+/** Distance beyond which the gesture dismisses, as a fraction of sheet height. */
+export declare const DISMISS_DISTANCE_FRACTION = 0.3;
+/** Velocity beyond which the gesture dismisses, in px per ms. */
+export declare const DISMISS_VELOCITY_PX_PER_MS = 0.5;
+/** Drag only starts if touchstart is within this top-px band (unless a drag handle is used). */
+export declare const DRAG_START_TOP_PX = 40;
+/** Snap-back spring duration when gesture doesn't pass threshold. */
+export declare const SNAP_BACK_MS = 300;
+export interface SwipeInputs {
+    /** The surface element to track gestures on. */
+    surface: HTMLElement;
+    /** Optional drag handle. When provided, drag can start from anywhere on
+     *  the handle; without it, drag must start in the top DRAG_START_TOP_PX band. */
+    dragHandle?: HTMLElement | null;
+    /** Completes the gesture stream (component disconnect / layout change). */
+    until$: Observable<unknown>;
+}
+/**
+ * Returns an Observable that emits exactly once when the user commits to
+ * dismissing the sheet (threshold passed). The gesture is owned by the
+ * caller — teardown fires on unsubscribe.
+ *
+ * During an in-progress drag, the surface's `transform` is updated
+ * directly for 1:1 tracking. On release-but-not-dismissed, the surface
+ * snaps back via a CSS transition.
+ */
+export declare function swipeToDismiss$(inputs: SwipeInputs): Observable<'dismiss'>;

package/types/src/overlay/overlay.layout.d.ts

@@ -0,0 +1,48 @@
+import type { Anchor, OverlayLayout } from './overlay.types';
+/**
+ * Layout dispatch engine — pure function of (anchor, content, viewport).
+ * No DOM access, no side effects — testable with synthetic inputs.
+ *
+ * Thresholds are policy constants, not magic numbers. Changes are visible
+ * as named-constant diffs, not hidden in inline literals (state skill:
+ * "thresholds ARE the policy").
+ */
+/** Below this viewport width, every overlay becomes a bottom sheet. */
+export declare const NARROW_VIEWPORT_PX = 640;
+/** Content taller than this fraction of viewport height → sheet. */
+export declare const TALL_CONTENT_FRACTION = 0.8;
+/** Content wider than this fraction of viewport width → sheet. */
+export declare const WIDE_CONTENT_FRACTION = 0.9;
+/** Floating UI / CSS anchor-positioning safety padding. */
+export declare const ANCHOR_FIT_PADDING_PX = 16;
+export interface LayoutInputs {
+    anchor?: Anchor;
+    content: {
+        width: number;
+        height: number;
+    };
+    viewport: {
+        width: number;
+        height: number;
+        /** `matchMedia('(pointer: coarse)').matches` at call time. */
+        isCoarsePointer: boolean;
+    };
+}
+/**
+ * Priority order:
+ *   1. viewport / content forces sheet
+ *   2. anchor provided → anchored (the novel default)
+ *   3. fallback → centered
+ *
+ * Floating UI's `flip` + `shift` + `size` middleware handles "anchor
+ * doesn't fit initially" — it returns a fitting position rather than
+ * rejecting. So step 2 does NOT branch on "does the anchor fit?";
+ * Floating UI's output IS the answer. If content is genuinely too
+ * large for any anchored position, step 1 already routed to sheet.
+ */
+export declare function resolveLayout(inputs: LayoutInputs): OverlayLayout;
+/**
+ * Read the current viewport + pointer inputs. Separated so tests can
+ * substitute synthetic inputs and the `resolveLayout` fn stays pure.
+ */
+export declare function readViewport(): LayoutInputs['viewport'];

package/types/src/overlay/overlay.service.d.ts

@@ -0,0 +1,62 @@
+import { Observable } from 'rxjs';
+import type { CloseReason, OverlayConfirmOptions, Content, OverlayEntry, OverlayPromptOptions, ShowOptions } from './overlay.types';
+/**
+ * Public read-only stream of the current overlay stack. Subscribe to
+ * observe stack changes — e.g. to update a breadcrumb, show a "close
+ * all" button, or gate another action while any overlay is open.
+ *
+ * Emits synchronously with the current snapshot on subscribe. Never
+ * completes — the caller owns teardown via `takeUntil(this.disconnecting)`.
+ */
+export declare const openOverlays$: Observable<readonly OverlayEntry[]>;
+/**
+ * Open an overlay containing `content`. Returns a cold Observable — the
+ * overlay mounts on subscribe and dismisses on unsubscribe. Emits at
+ * most one value (the result from content's `close` event) then completes.
+ *
+ * The subscription IS the overlay lifecycle. `takeUntil(this.disconnecting)`
+ * on the caller's side means the overlay auto-dismisses when the caller
+ * unmounts — no handles to track, no leaks.
+ *
+ * **Anchored is the novel default.** When triggered by a user event, pass
+ * it as `anchor` — the overlay blooms from the point of attention. Falls
+ * back to centered or sheet when the viewport / content makes that the
+ * better layout (see overlay.layout.ts).
+ *
+ * @example
+ * show(MyEditor, { props: { id }, anchor: event })
+ *   .pipe(takeUntil(this.disconnecting))
+ *   .subscribe(saved => saved && this.store.persist(saved))
+ */
+export declare function show<T = void>(content: Content, options?: ShowOptions): Observable<T | undefined>;
+/**
+ * Yes/no confirmation dialog. Returns a Promise that resolves with the
+ * user's choice. `variant: 'danger'` flips to destructive styling and
+ * `role="alertdialog"`.
+ */
+export declare function confirm(options?: OverlayConfirmOptions): Promise<boolean>;
+/**
+ * Input prompt dialog. Returns the entered string, or `null` if the user
+ * cancels or dismisses.
+ */
+export declare function prompt(options?: OverlayPromptOptions): Promise<string | null>;
+/**
+ * Subscribe to custom events emitted from any currently-open overlay
+ * whose content matches `tagName`. Inspired by `area.on(name)` — keyed
+ * by tag name (stable across HMR / lazy chunks) rather than a uid or
+ * class reference.
+ *
+ * The returned Observable never completes on its own — the caller owns
+ * teardown via `takeUntil(this.disconnecting)`. During gaps where no
+ * matching overlay is open, no events are emitted; when an instance
+ * mounts, events flow.
+ *
+ * Stacked instances of the same content merge their event streams.
+ */
+export declare function overlayEvents<E extends Event = CustomEvent>(tagName: string, eventName: string): Observable<E>;
+/**
+ * Close every currently-open overlay. LIFO order. Imperative — use for
+ * app-level flows like logout or route reset.
+ */
+export declare function dismissAll(): void;
+export type { CloseReason };