@mhmo91/schmancy 0.9.13 → 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/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 };

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

@@ -0,0 +1,25 @@
+import { Observable } from 'rxjs';
+import type { OverlayEntry } from './overlay.types';
+/** Public read-only stream of the current stack. Emits on every push/pop. */
+export declare const stack$: Observable<readonly OverlayEntry[]>;
+/** Synchronous snapshot. Use only when a component can't subscribe. */
+export declare function currentStack(): readonly OverlayEntry[];
+/** Append an entry (top of stack). */
+export declare function pushEntry(entry: OverlayEntry): void;
+/** Remove by id. No-op if the id is not in the stack. */
+export declare function removeEntry(id: string): void;
+/** Clear the entire stack. Used by dismissAll(). */
+export declare function clearStack(): void;
+/** Top entry (LIFO). Undefined when stack is empty. */
+export declare function topEntry(): OverlayEntry | undefined;
+export declare function markModal(id: string, hostContainer: HTMLElement): void;
+export declare function unmarkModal(id: string): void;
+/**
+ * Returns an Observable of `tagName` elements currently in the stack.
+ * The overlayEvents public helper composes `fromEvent` over this stream
+ * via switchMap to tap events without owning the overlay lifecycle.
+ *
+ * Stays alive across open/close cycles — the caller owns completion via
+ * `takeUntil(this.disconnecting)`, matching the house rxjs convention.
+ */
+export declare function elementsByTag$(tagName: string): Observable<readonly HTMLElement[]>;

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

@@ -0,0 +1,122 @@
+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' | 'native-submit' | 'escape' | 'backdrop' | 'swipe' | 'popstate' | 'light-dismiss' | 'programmatic' | 'abort';
+/**
+ * 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>;