kerfjs 4.4.0 → 5.0.0-beta.3

package/dist/overlay.d.ts

@@ -40,285 +40,7 @@ declare function positionAnchored(el: HTMLElement, anchor: Element, options?: An
 declare function autoReposition(el: HTMLElement, anchor: Element, options?: AnchorPositionOptions): () => void;
 
 /**
- * Wiring slots passed to a {@link ConfirmOptions.render} — spread `ok` / `cancel`
- * onto your own clickable elements so `confirm()` still resolves them (they are
- * `data-confirm` attribute bags). `message` is the raw message (escape it by
- * interpolating through JSX).
- */
-interface ConfirmRenderSlots {
-    message: string;
-    /** Spread onto the confirm control. */
-    ok: Record<string, string>;
-    /** Spread onto the cancel control. */
-    cancel: Record<string, string>;
-}
-/** Options for {@link confirm}. */
-interface ConfirmOptions {
-    /** Where to append the overlay. Default `document.body`. */
-    container?: Element;
-    /** Wrapper class. Default `'kerf-overlay'`. */
-    className?: string;
-    /** Optional heading above the message. */
-    title?: string;
-    /** Confirm button label. Default `'OK'`. */
-    okText?: string;
-    /** Cancel button label. Default `'Cancel'`. */
-    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
-     * default two-button markup; `confirm()` keeps owning dismiss / focus-trap /
-     * focus-restore and still resolves `true`/`false` for OK/Cancel/dismissal.
-     */
-    render?: (slots: ConfirmRenderSlots) => OverlayContent;
-}
-/**
- * A promise-based `window.confirm` replacement (that global is a no-op in Tauri
- * webviews). Renders a two-button dialog and resolves `true` for OK, `false`
- * for Cancel or any dismissal (Escape / backdrop). Message + labels are
- * auto-escaped (rendered through the JSX runtime). Pass `render` for your own markup.
- */
-declare function confirm(message: string, options?: ConfirmOptions): Promise<boolean>;
-/**
- * Validate a single field's value. Return a non-empty error string to BLOCK
- * submission (shown inline next to the field); return `undefined`/`null`/`''` to
- * allow it.
- */
-type FieldValidator = (value: string) => string | null | undefined | void;
-/** Options for {@link prompt}. */
-interface PromptOptions {
-    /** Where to append the overlay. Default `document.body`. */
-    container?: Element;
-    /** Wrapper class. Default `'kerf-overlay'`. */
-    className?: string;
-    /** Optional heading above the message. */
-    title?: string;
-    /** Pre-filled input value. Default `''`. */
-    defaultValue?: string;
-    /** Input placeholder. */
-    placeholder?: string;
-    /** `type` attribute of the input (`'text'`, `'email'`, `'password'`, …). Default `'text'`. */
-    inputType?: string;
-    /** Confirm button label. Default `'OK'`. */
-    okText?: string;
-    /** Cancel button label. Default `'Cancel'`. */
-    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
-     * inline-error slot) wiring. `prompt()` still reads the input, runs `validate`,
-     * submits on Enter, and owns dismiss / focus. If you omit the `error` slot,
-     * `validate` simply re-focuses the input without an inline message.
-     */
-    render?: (slots: PromptRenderSlots) => OverlayContent;
-}
-/** Wiring slots for a {@link PromptOptions.render} — spread each onto your own markup. */
-interface PromptRenderSlots {
-    message: string;
-    /** Spread onto your `<input>` — carries the marker, `type`, `value`, and `placeholder`. */
-    input: Record<string, string>;
-    /** Spread onto your inline-error element (optional). */
-    error: Record<string, string>;
-    /** Spread onto the confirm control. */
-    ok: Record<string, string>;
-    /** Spread onto the cancel control. */
-    cancel: Record<string, string>;
-}
-/**
- * A promise-based `window.prompt` replacement (that global is a no-op in Tauri
- * webviews). Renders a one-field dialog and resolves the entered **string** on OK
- * (an empty string is a valid result) or `null` on Cancel / dismissal. Enter in
- * the input submits. `message`, the default value, and labels are auto-escaped
- * (rendered through the JSX runtime). Optional `validate` blocks OK inline. Pass
- * `render` for your own markup.
- */
-declare function prompt(message: string, options?: PromptOptions): Promise<string | null>;
-/** A single field in a {@link form}. */
-interface FormField {
-    /** Field name — the key in the resolved record (and the input's `name`). */
-    name: string;
-    /** Label shown above the input. Defaults to `name`. */
-    label?: string;
-    /** Pre-filled value. Default `''`. */
-    defaultValue?: string;
-    /** Input placeholder. */
-    placeholder?: string;
-    /** `type` attribute of the input. Default `'text'`. */
-    type?: string;
-    /** Block OK while this returns an error string; the message shows inline for this field. */
-    validate?: FieldValidator;
-}
-/** One field's wiring in a {@link FormRenderSlots} — spread `input`/`error` onto your markup. */
-interface FormRenderField {
-    name: string;
-    label: string;
-    /** Spread onto your `<input>` — carries the marker, `name`, `type`, `value`, `placeholder`. */
-    input: Record<string, string>;
-    /** Spread onto your inline-error element (optional). */
-    error: Record<string, string>;
-}
-/** Wiring slots for a {@link FormOptions.render}. */
-interface FormRenderSlots {
-    fields: FormRenderField[];
-    /** Spread onto the confirm control. */
-    ok: Record<string, string>;
-    /** Spread onto the cancel control. */
-    cancel: Record<string, string>;
-}
-/** Options for {@link form}. */
-interface FormOptions {
-    /** Where to append the overlay. Default `document.body`. */
-    container?: Element;
-    /** Wrapper class. Default `'kerf-overlay'`. */
-    className?: string;
-    /** Optional heading above the fields. */
-    title?: string;
-    /** Confirm button label. Default `'OK'`. */
-    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.
-     * `form()` still reads each input, runs per-field `validate`, focuses the first
-     * invalid field, submits on Enter, and owns dismiss / focus. Omit a field's
-     * `error` slot to skip its inline message.
-     */
-    render?: (slots: FormRenderSlots) => OverlayContent;
-}
-/**
- * A promise-based multi-field dialog — the two-or-three-input sibling of
- * {@link prompt}. Renders one labeled input per {@link FormField} and resolves a
- * `Record<name, value>` on OK (after every field's `validate` passes) or `null`
- * on Cancel / dismissal. Enter in any field submits. All labels, defaults, and
- * the title are auto-escaped through the JSX runtime.
- */
-declare function form(fields: readonly FormField[], options?: FormOptions): Promise<Record<string, string> | null>;
-/** One choosable action in a {@link choice} dialog. */
-interface ChoiceAction<R> {
-    /** The value this action resolves. */
-    value: R;
-    /** Button label (auto-escaped). */
-    label: string;
-    /** Extra class on this action's button. */
-    className?: string;
-}
-/** Wiring slots for a {@link ChoiceOptions.render} — spread `actions[i]` onto your i-th button. */
-interface ChoiceRenderSlots {
-    message: string;
-    /** One attribute bag per action (in order) — spread onto that action's control. */
-    actions: Array<Record<string, string>>;
-}
-/** Options for {@link choice}. */
-interface ChoiceOptions<R> {
-    /** Where to append the overlay. Default `document.body`. */
-    container?: Element;
-    /** Wrapper class. Default `'kerf-overlay'`. */
-    className?: string;
-    /** Optional heading above the message. */
-    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;
-}
-/**
- * The **N-way** sibling of {@link confirm}: renders one button per {@link ChoiceAction}
- * and resolves that action's `value` on click, or `null` on Cancel / dismissal.
- * Pass `defaultValue` to make **Enter** (anywhere in the dialog) resolve a default
- * action — the "global Enter-to-confirm" model — without you having to hold the
- * overlay handle. `message` + labels are auto-escaped; pass `render` for your own
- * markup. kerf owns dismiss / focus-trap / focus-restore. For fully bespoke
- * keyboard/close control, drive {@link overlay} directly.
- */
-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.
+ * Internal overlay / popover / tooltip lifecycle implementation.
  *
  * Every real kerf app hand-rolls this: `toElement → body.appendChild → mount →
  * wire dismissal → remove`, plus the fiddly parts (Escape, backdrop / outside
@@ -403,7 +125,8 @@ interface OverlayHandle {
 /**
  * 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}.
+ * handle. Concurrent fallback overlays dismiss from the top down. See
+ * {@link OverlayOptions}.
  */
 declare function overlay(content: OverlayContent, options?: OverlayOptions): OverlayHandle;
 
@@ -476,4 +199,191 @@ interface TooltipOptions extends AnchorPositionOptions {
  */
 declare function tooltip(anchor: Element, content: TooltipContent, options?: TooltipOptions): () => void;
 
+/** One choosable action in a {@link choice} dialog. */
+interface ChoiceAction<R> {
+    value: R;
+    label: string;
+    className?: string;
+}
+/** Wiring slots for a {@link ChoiceOptions.render}. */
+interface ChoiceRenderSlots {
+    message: string;
+    actions: Array<Record<string, string>>;
+}
+/** Options for {@link choice}. */
+interface ChoiceOptions<R> {
+    container?: Element;
+    className?: string;
+    title?: string;
+    defaultValue?: R;
+    native?: boolean;
+    render?: (slots: ChoiceRenderSlots) => OverlayContent;
+}
+/** The N-way sibling of {@link confirm}. */
+declare function choice<R>(message: string, actions: ReadonlyArray<ChoiceAction<R>>, options?: ChoiceOptions<R>): Promise<R | null>;
+
+/** Wiring slots passed to a {@link ConfirmOptions.render}. */
+interface ConfirmRenderSlots {
+    message: string;
+    /** Spread onto the confirm control. */
+    ok: Record<string, string>;
+    /** Spread onto the cancel control. */
+    cancel: Record<string, string>;
+}
+/** Options for {@link confirm}. */
+interface ConfirmOptions {
+    /** Where to append the overlay. Default `document.body`. */
+    container?: Element;
+    /** Wrapper class. Default `'kerf-overlay'`. */
+    className?: string;
+    /** Optional heading above the message. */
+    title?: string;
+    /** Confirm button label. Default `'OK'`. */
+    okText?: string;
+    /** Cancel button label. Default `'Cancel'`. */
+    cancelText?: string;
+    /** Add a `kerf-confirm--danger` class to the wrapper for destructive actions. */
+    danger?: boolean;
+    /** Host the dialog in the browser top layer where supported. */
+    native?: boolean;
+    /** Bring your own body while retaining kerf's dialog wiring. */
+    render?: (slots: ConfirmRenderSlots) => OverlayContent;
+}
+/** A promise-based `window.confirm` replacement. */
+declare function confirm(message: string, options?: ConfirmOptions): Promise<boolean>;
+
+/** Validate a single field's value. */
+type FieldValidator = (value: string) => string | null | undefined | void;
+/** Options for {@link prompt}. */
+interface PromptOptions {
+    container?: Element;
+    className?: string;
+    title?: string;
+    defaultValue?: string;
+    placeholder?: string;
+    inputType?: string;
+    okText?: string;
+    cancelText?: string;
+    validate?: FieldValidator;
+    native?: boolean;
+    render?: (slots: PromptRenderSlots) => OverlayContent;
+}
+/** Wiring slots for a {@link PromptOptions.render}. */
+interface PromptRenderSlots {
+    message: string;
+    input: Record<string, string>;
+    error: Record<string, string>;
+    ok: Record<string, string>;
+    cancel: Record<string, string>;
+}
+/** A promise-based `window.prompt` replacement. */
+declare function prompt(message: string, options?: PromptOptions): Promise<string | null>;
+
+/** A single field in a {@link form}. */
+interface FormField {
+    name: string;
+    label?: string;
+    defaultValue?: string;
+    placeholder?: string;
+    type?: string;
+    validate?: FieldValidator;
+}
+/** One field's wiring in a {@link FormRenderSlots}. */
+interface FormRenderField {
+    name: string;
+    label: string;
+    input: Record<string, string>;
+    error: Record<string, string>;
+}
+/** Wiring slots for a {@link FormOptions.render}. */
+interface FormRenderSlots {
+    fields: FormRenderField[];
+    ok: Record<string, string>;
+    cancel: Record<string, string>;
+}
+/** Options for {@link form}. */
+interface FormOptions {
+    container?: Element;
+    className?: string;
+    title?: string;
+    okText?: string;
+    cancelText?: string;
+    native?: boolean;
+    render?: (slots: FormRenderSlots) => OverlayContent;
+}
+/** A promise-based multi-field dialog. */
+declare function form(fields: readonly FormField[], options?: FormOptions): Promise<Record<string, string> | 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}: an escaped text string, trusted `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;
+
 export { type AnchorPositionOptions, type ChoiceAction, type ChoiceOptions, type ChoiceRenderSlots, type ConfirmOptions, type ConfirmRenderSlots, type DismissTrigger, type FieldValidator, type FormField, type FormOptions, type FormRenderField, type FormRenderSlots, type OverlayContent, type OverlayHandle, type OverlayOptions, type PopoverOptions, type PopoverPlacement, type PromptOptions, type PromptRenderSlots, type ToastContent, type ToastHandle, type ToastOptions, type ToastVariant, type TooltipContent, type TooltipOptions, autoReposition, choice, confirm, form, overlay, popover, positionAnchored, prompt, toast, tooltip };