kerfjs 4.2.0 → 4.3.0

package/dist/overlay.d.ts

@@ -39,128 +39,6 @@ declare function positionAnchored(el: HTMLElement, anchor: Element, options?: An
  */
 declare function autoReposition(el: HTMLElement, anchor: Element, options?: AnchorPositionOptions): () => void;
 
-/**
- * `toast()` for `kerfjs/overlay` — a non-modal, auto-dismissing notification that
- * stacks in a shared body-level region. Split out of `overlay.ts` (KF-513) since
- * it's a distinct transient-UI concern from the modal dialogs; re-exported from
- * `overlay.ts` so the public `kerfjs/overlay` surface is unchanged. Structural
- * only — kerf ships no CSS; you style the region / toast / animations.
- */
-
-/** Content for a {@link toast}: text, `SafeHtml`, or a render function. */
-type ToastContent = string | SafeHtml | (() => MountResult);
-/** Accent variant for a {@link toast} — mapped to a `${className}--${variant}` class. */
-type ToastVariant = 'info' | 'success' | 'warning';
-/** Options for {@link toast}. */
-interface ToastOptions {
-    /** Where toasts stack. Default: a lazily-created `<div class="kerf-toasts">` on `document.body`. */
-    container?: Element;
-    /** Class on the toast element. Default `'kerf-toast'`. */
-    className?: string;
-    /** Auto-dismiss after this many ms. `0` keeps it until dismissed by hand. Default `4000`. */
-    duration?: number;
-    /** ARIA role. Default `'status'`. */
-    role?: string;
-    /**
-     * `'stack'` (default) shows toasts stacked in the region; `'replace'` dismisses
-     * the region's current toast(s) first (collapse-to-latest for a rapid sequence).
-     */
-    mode?: 'stack' | 'replace';
-    /**
-     * How `mode: 'replace'` drops the prior toast(s): `'fade'` (default) runs their
-     * full exit transition (nice for a STACKING region), or `'instant'` removes them
-     * synchronously with no exit — what a single, exactly-centered toast slot wants,
-     * so the outgoing and incoming messages never cross-fade in the same spot.
-     */
-    collapse?: 'fade' | 'instant';
-    /** Accent variant — adds a `${className}--${variant}` class (kerf ships no CSS; you style it). */
-    variant?: ToastVariant;
-    /** Class added on the next animation frame after mount, so a CSS **entrance** transition can run. */
-    enterClass?: string;
-    /**
-     * Class added when dismissing, so CSS owns the **exit**. On dismiss the
-     * `enterClass` (if any) is also REMOVED, so `exitClass` doesn't have to
-     * out-specify it — and a symmetric single-class fade (entrance = add
-     * `enterClass`, exit = remove it) works by setting only `enterClass` +
-     * `exitDuration`. The node is removed `exitDuration` ms later.
-     */
-    exitClass?: string;
-    /** ms to wait before removing the node on dismiss — applies when `exitClass` is set OR when it's > 0 (to let a removed `enterClass` transition out). Default `0`. */
-    exitDuration?: number;
-}
-/** Handle returned by {@link toast}. */
-interface ToastHandle {
-    /** The toast element — inspect it, or run your own entrance/exit transitions. */
-    el: HTMLElement;
-    /**
-     * Dismiss it early. Default runs the `exitClass` transition (removed after
-     * `exitDuration`); pass `{ instant: true }` to remove it **synchronously** with
-     * no exit — for an action button that immediately shows a replacement toast in a
-     * single centered slot (no cross-fade). Idempotent.
-     */
-    dismiss(options?: {
-        instant?: boolean;
-    }): void;
-}
-/**
- * Show a non-modal, auto-dismissing notification. Stacks in a shared body-level
- * region (or your `container`). Returns a {@link ToastHandle} (`{ el, dismiss }`)
- * so you can run entrance/exit transitions, wire an action button, or inspect the
- * node. `mode: 'replace'` collapses a rapid sequence to the latest; `variant`
- * adds an accent class; `enterClass`/`exitClass` let CSS own the animation.
- */
-declare function toast(content: ToastContent, options?: ToastOptions): ToastHandle;
-
-/** A user-initiated dismissal trigger. */
-type DismissTrigger = 'escape' | 'backdrop' | 'outside';
-/** Content for an overlay: static `SafeHtml`, or a render function `mount()` drives reactively. */
-type OverlayContent = SafeHtml | (() => MountResult);
-/** Options for {@link overlay}. */
-interface OverlayOptions {
-    /** Where to append the overlay wrapper. Default `document.body`. */
-    container?: Element;
-    /** Class on the wrapper element (you style it — kerf ships no CSS). Default `'kerf-overlay'`. */
-    className?: string;
-    /**
-     * Which user actions dismiss the overlay. Default `['escape', 'backdrop']`.
-     * `'backdrop'` = a click on the wrapper itself (not its content); `'outside'`
-     * = a click anywhere outside the wrapper (for anchored popovers). `false`
-     * disables user dismissal (close it programmatically).
-     */
-    dismiss?: DismissTrigger | DismissTrigger[] | false;
-    /**
-     * Where focus lands on open: a selector, `true` (first focusable element, or
-     * the wrapper if none), or `false` (leave focus alone). Default `true`.
-     */
-    initialFocus?: string | boolean;
-    /**
-     * Trap Tab / Shift+Tab within the overlay while open and mark it
-     * `role="dialog"` / `aria-modal="true"`. Default `true`. Set `false` for a
-     * non-modal popover.
-     */
-    trap?: boolean;
-    /** ARIA role for the wrapper when `trap` is on. Default `'dialog'`. */
-    role?: string;
-    /** Called on any user-initiated dismissal (before `close()` runs). */
-    onDismiss?: () => void;
-    /** For `'outside'` dismissal: clicks on these elements do NOT count as outside (e.g. the trigger button). */
-    outsideIgnore?: Element | readonly Element[];
-}
-/** Handle returned by {@link overlay}. Holds no framework state — it's a closure. */
-interface OverlayHandle {
-    /** The wrapper element (mounted into, appended to `container`). */
-    el: HTMLElement;
-    /** Tear down: dispose the mount, remove listeners + the node, restore focus, resolve `result`. Idempotent. */
-    close(result?: unknown): void;
-    /** Resolves with the value passed to `close()` (or `undefined` on user dismissal). */
-    result: Promise<unknown>;
-}
-/**
- * Open an overlay: append a wrapper to `container`, `mount()` `content` inside
- * it, wire the requested dismissals + (optionally) a focus trap, and return a
- * handle. See {@link OverlayOptions}.
- */
-declare function overlay(content: OverlayContent, options?: OverlayOptions): OverlayHandle;
 /**
  * Wiring slots passed to a {@link ConfirmOptions.render} — spread `ok` / `cancel`
  * onto your own clickable elements so `confirm()` still resolves them (they are
@@ -188,6 +66,8 @@ interface ConfirmOptions {
     cancelText?: string;
     /** Add a `kerf-confirm--danger` class to the wrapper for destructive actions. */
     danger?: boolean;
+    /** Host the dialog in the browser top layer (`<dialog>.showModal()`) where supported. See {@link OverlayOptions.native}. */
+    native?: boolean;
     /**
      * Bring your own markup (design-system dialogs): return the full dialog body,
      * spreading the provided `ok`/`cancel` wiring onto your buttons. Overrides the
@@ -229,6 +109,8 @@ interface PromptOptions {
     cancelText?: string;
     /** Block OK while this returns an error string; the message shows inline. */
     validate?: FieldValidator;
+    /** Host the dialog in the browser top layer (`<dialog>.showModal()`) where supported. See {@link OverlayOptions.native}. */
+    native?: boolean;
     /**
      * Bring your own markup: return the full dialog body, spreading the provided
      * `input` (the text field), `ok`/`cancel` (buttons), and optional `error` (the
@@ -303,6 +185,8 @@ interface FormOptions {
     okText?: string;
     /** Cancel button label. Default `'Cancel'`. */
     cancelText?: string;
+    /** Host the dialog in the browser top layer (`<dialog>.showModal()`) where supported. See {@link OverlayOptions.native}. */
+    native?: boolean;
     /**
      * Bring your own markup: return the full form body, laying out `slots.fields`
      * (each with `input`/`error` wiring to spread) and the `ok`/`cancel` buttons.
@@ -345,6 +229,8 @@ interface ChoiceOptions<R> {
     title?: string;
     /** The value resolved when **Enter** is pressed anywhere in the dialog (the default action). */
     defaultValue?: R;
+    /** Host the dialog in the browser top layer (`<dialog>.showModal()`) where supported. See {@link OverlayOptions.native}. */
+    native?: boolean;
     /** Bring your own markup: return the full body, spreading each `slots.actions[i]` onto your buttons. */
     render?: (slots: ChoiceRenderSlots) => OverlayContent;
 }
@@ -359,6 +245,168 @@ interface ChoiceOptions<R> {
  */
 declare function choice<R>(message: string, actions: ReadonlyArray<ChoiceAction<R>>, options?: ChoiceOptions<R>): Promise<R | null>;
 
+/**
+ * `toast()` for `kerfjs/overlay` — a non-modal, auto-dismissing notification that
+ * stacks in a shared body-level region. Split out of `overlay.ts` (KF-513) since
+ * it's a distinct transient-UI concern from the modal dialogs; re-exported from
+ * `overlay.ts` so the public `kerfjs/overlay` surface is unchanged. Structural
+ * only — kerf ships no CSS; you style the region / toast / animations.
+ */
+
+/** Content for a {@link toast}: text, `SafeHtml`, or a render function. */
+type ToastContent = string | SafeHtml | (() => MountResult);
+/** Accent variant for a {@link toast} — mapped to a `${className}--${variant}` class. */
+type ToastVariant = 'info' | 'success' | 'warning';
+/** Options for {@link toast}. */
+interface ToastOptions {
+    /** Where toasts stack. Default: a lazily-created `<div class="kerf-toasts">` on `document.body`. */
+    container?: Element;
+    /** Class on the toast element. Default `'kerf-toast'`. */
+    className?: string;
+    /** Auto-dismiss after this many ms. `0` keeps it until dismissed by hand. Default `4000`. */
+    duration?: number;
+    /** ARIA role. Default `'status'`. */
+    role?: string;
+    /**
+     * `'stack'` (default) shows toasts stacked in the region; `'replace'` dismisses
+     * the region's current toast(s) first (collapse-to-latest for a rapid sequence).
+     */
+    mode?: 'stack' | 'replace';
+    /**
+     * How `mode: 'replace'` drops the prior toast(s): `'fade'` (default) runs their
+     * full exit transition (nice for a STACKING region), or `'instant'` removes them
+     * synchronously with no exit — what a single, exactly-centered toast slot wants,
+     * so the outgoing and incoming messages never cross-fade in the same spot.
+     */
+    collapse?: 'fade' | 'instant';
+    /** Accent variant — adds a `${className}--${variant}` class (kerf ships no CSS; you style it). */
+    variant?: ToastVariant;
+    /** Class added on the next animation frame after mount, so a CSS **entrance** transition can run. */
+    enterClass?: string;
+    /**
+     * Class added when dismissing, so CSS owns the **exit**. On dismiss the
+     * `enterClass` (if any) is also REMOVED, so `exitClass` doesn't have to
+     * out-specify it — and a symmetric single-class fade (entrance = add
+     * `enterClass`, exit = remove it) works by setting only `enterClass` +
+     * `exitDuration`. The node is removed `exitDuration` ms later.
+     */
+    exitClass?: string;
+    /** ms to wait before removing the node on dismiss — applies when `exitClass` is set OR when it's > 0 (to let a removed `enterClass` transition out). Default `0`. */
+    exitDuration?: number;
+}
+/** Handle returned by {@link toast}. */
+interface ToastHandle {
+    /** The toast element — inspect it, or run your own entrance/exit transitions. */
+    el: HTMLElement;
+    /**
+     * Dismiss it early. Default runs the `exitClass` transition (removed after
+     * `exitDuration`); pass `{ instant: true }` to remove it **synchronously** with
+     * no exit — for an action button that immediately shows a replacement toast in a
+     * single centered slot (no cross-fade). Idempotent.
+     */
+    dismiss(options?: {
+        instant?: boolean;
+    }): void;
+}
+/**
+ * Show a non-modal, auto-dismissing notification. Stacks in a shared body-level
+ * region (or your `container`). Returns a {@link ToastHandle} (`{ el, dismiss }`)
+ * so you can run entrance/exit transitions, wire an action button, or inspect the
+ * node. `mode: 'replace'` collapses a rapid sequence to the latest; `variant`
+ * adds an accent class; `enterClass`/`exitClass` let CSS own the animation.
+ */
+declare function toast(content: ToastContent, options?: ToastOptions): ToastHandle;
+
+/**
+ * `kerfjs/overlay` — the modal / overlay + dismiss manager.
+ *
+ * Every real kerf app hand-rolls this: `toElement → body.appendChild → mount →
+ * wire dismissal → remove`, plus the fiddly parts (Escape, backdrop / outside
+ * click, focus trap, restoring focus on close). `window.confirm` is a no-op in
+ * Tauri WKWebViews, so a hand-built overlay is mandatory there. This subpath
+ * blesses the pattern as three functions over `mount()` — `overlay()`, and the
+ * `confirm()` / `toast()` conveniences built on it. No per-instance framework
+ * state: each call owns its DOM + listeners in a closure and returns a handle.
+ *
+ *   import { overlay, confirm, toast } from 'kerfjs/overlay';
+ *
+ *   const ok = await confirm('Delete this file?', { danger: true });
+ *   toast('Saved');
+ *   const dialog = overlay(<Settings />, { dismiss: ['escape', 'backdrop'] });
+ *   // …later: dialog.close();  or  await dialog.result;
+ *
+ * Structural only — kerf ships no CSS. The wrapper gets your `className`; style
+ * the backdrop / centering / animation yourself.
+ */
+
+/** A user-initiated dismissal trigger. */
+type DismissTrigger = 'escape' | 'backdrop' | 'outside';
+/** Content for an overlay: static `SafeHtml`, or a render function `mount()` drives reactively. */
+type OverlayContent = SafeHtml | (() => MountResult);
+/** Options for {@link overlay}. */
+interface OverlayOptions {
+    /** Where to append the overlay wrapper. Default `document.body`. */
+    container?: Element;
+    /** Class on the wrapper element (you style it — kerf ships no CSS). Default `'kerf-overlay'`. */
+    className?: string;
+    /**
+     * Which user actions dismiss the overlay. Default `['escape', 'backdrop']`.
+     * `'backdrop'` = a click on the wrapper itself (not its content); `'outside'`
+     * = a click anywhere outside the wrapper (for anchored popovers). `false`
+     * disables user dismissal (close it programmatically).
+     */
+    dismiss?: DismissTrigger | DismissTrigger[] | false;
+    /**
+     * Where focus lands on open: a selector, `true` (first focusable element, or
+     * the wrapper if none), or `false` (leave focus alone). Default `true`.
+     */
+    initialFocus?: string | boolean;
+    /**
+     * Trap Tab / Shift+Tab within the overlay while open and mark it
+     * `role="dialog"` / `aria-modal="true"`. Default `true`. Set `false` for a
+     * non-modal popover.
+     */
+    trap?: boolean;
+    /** ARIA role for the wrapper when `trap` is on. Default `'dialog'`. */
+    role?: string;
+    /** Called on any user-initiated dismissal (before `close()` runs). */
+    onDismiss?: () => void;
+    /** For `'outside'` dismissal: clicks on these elements do NOT count as outside (e.g. the trigger button). */
+    outsideIgnore?: Element | readonly Element[];
+    /**
+     * Opt into the browser **top layer** (`docs/19-native-overlay-backing.md`).
+     * When `true` and the engine supports it, a modal overlay (`trap: true`) is
+     * hosted in a `<dialog>` opened with `.showModal()` — real inerting of the rest
+     * of the document + guaranteed stacking above any `z-index` — and a non-modal
+     * one (`trap: false`) uses the Popover API (`[popover]` + `showPopover()`).
+     * Feature-detected; falls back to today's plain `<div>` where unsupported.
+     *
+     * The `render` slot + promise API are unchanged — kerf just hosts your markup
+     * in a `<dialog>` / `[popover]` instead of a `<div>`. Two caveats: native
+     * `<dialog>` / `[popover]` carry **UA default styles** (a `::backdrop`,
+     * centering, border, padding) that kerf does not reset — style the element (and
+     * its `::backdrop`) via `className`; and `container` is effectively a **no-op**
+     * for visual position, since the top layer ignores where the element lives in
+     * the DOM. Default `false`.
+     */
+    native?: boolean;
+}
+/** Handle returned by {@link overlay}. Holds no framework state — it's a closure. */
+interface OverlayHandle {
+    /** The wrapper element (mounted into, appended to `container`). */
+    el: HTMLElement;
+    /** Tear down: dispose the mount, remove listeners + the node, restore focus, resolve `result`. Idempotent. */
+    close(result?: unknown): void;
+    /** Resolves with the value passed to `close()` (or `undefined` on user dismissal). */
+    result: Promise<unknown>;
+}
+/**
+ * Open an overlay: append a wrapper to `container`, `mount()` `content` inside
+ * it, wire the requested dismissals + (optionally) a focus trap, and return a
+ * handle. See {@link OverlayOptions}.
+ */
+declare function overlay(content: OverlayContent, options?: OverlayOptions): OverlayHandle;
+
 /** Options for {@link popover}. */
 interface PopoverOptions {
     /** Where to append the popover wrapper. Default `document.body`. */
@@ -382,6 +430,14 @@ interface PopoverOptions {
     outsideIgnore?: Element | readonly Element[];
     /** Called on any user-initiated dismissal. */
     onDismiss?: () => void;
+    /**
+     * Host the popover in the browser top layer (the Popover API — `[popover]` +
+     * `showPopover()`) where supported, so it stacks above any `z-index` without a
+     * z-index war. Falls back to today's plain `<div>` where unsupported. kerf keeps
+     * owning positioning + its own dismiss wiring; the popover is `popover="manual"`.
+     * See {@link OverlayOptions.native}. Default `false`.
+     */
+    native?: boolean;
 }
 /**
  * Anchored, non-modal overlay: positions `content` relative to `anchor` (below by
@@ -407,6 +463,8 @@ interface TooltipOptions extends AnchorPositionOptions {
     hideDelay?: number;
     /** ARIA role on the wrapper. Default `'tooltip'`. */
     role?: string;
+    /** Host the tooltip in the browser top layer (the Popover API) where supported. See {@link OverlayOptions.native}. Default `false`. */
+    native?: boolean;
 }
 /**
  * A hover/focus-triggered, non-modal, auto-hiding tooltip anchored to `anchor`.