kerfjs 4.2.0-beta.2 → 4.2.0-beta.4

package/dist/overlay.d.ts

@@ -53,6 +53,19 @@ interface OverlayHandle {
  * 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
+ * `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`. */
@@ -67,12 +80,19 @@ interface ConfirmOptions {
     cancelText?: string;
     /** Add a `kerf-confirm--danger` class to the wrapper for destructive actions. */
     danger?: 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).
+ * auto-escaped (rendered through the JSX runtime). Pass `render` for your own markup.
  */
 declare function confirm(message: string, options?: ConfirmOptions): Promise<boolean>;
 /**
@@ -101,13 +121,34 @@ interface PromptOptions {
     cancelText?: string;
     /** Block OK while this returns an error string; the message shows inline. */
     validate?: FieldValidator;
+    /**
+     * 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.
+ * (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}. */
@@ -125,6 +166,23 @@ interface FormField {
     /** 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`. */
@@ -137,6 +195,14 @@ interface FormOptions {
     okText?: string;
     /** Cancel button label. Default `'Cancel'`. */
     cancelText?: string;
+    /**
+     * 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
@@ -146,8 +212,71 @@ interface FormOptions {
  * the title are auto-escaped through the JSX runtime.
  */
 declare function form(fields: readonly FormField[], options?: FormOptions): Promise<Record<string, string> | null>;
-/** Vertical placement of a {@link popover} relative to its anchor. */
+/** 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;
+    /** 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>;
+/** Vertical placement relative to an anchor (used by {@link popover}, {@link positionAnchored}, {@link tooltip}). */
 type PopoverPlacement = 'bottom' | 'top';
+/** Placement options for {@link positionAnchored} / {@link autoReposition}. */
+interface AnchorPositionOptions {
+    /** Preferred side of the anchor; flips to the other side if it would overflow the viewport. Default `'bottom'`. */
+    placement?: PopoverPlacement;
+    /** Horizontal edge to line up with the anchor: `'start'` (left edges) or `'end'` (right edges). Default `'start'`. */
+    align?: 'start' | 'end';
+    /** Gap in px between the anchor and the element. Default `4`. */
+    gap?: number;
+}
+/**
+ * One-shot: position `el` relative to `anchor` — below by default, flipping above
+ * if it would overflow the viewport, aligned to a horizontal edge and clamped into
+ * view. Sets `el.style` `position: fixed`, `margin: 0`, `left`, and `top` (fixed so
+ * `left`/`top` are viewport coordinates, matching `getBoundingClientRect`). This is
+ * `popover()`'s placement core, usable on any element (an inline hint, a tooltip) —
+ * no overlay lifecycle. Pair with {@link autoReposition} to keep it glued while open.
+ */
+declare function positionAnchored(el: HTMLElement, anchor: Element, options?: AnchorPositionOptions): void;
+/**
+ * Keep `el` positioned against `anchor` (via {@link positionAnchored}) as the page
+ * scrolls or resizes. Positions once immediately, then re-runs on `scroll`
+ * (capture phase — catches scrolls in any inner container, not just `window`) and
+ * `resize`. Returns a disposer that removes the listeners.
+ */
+declare function autoReposition(el: HTMLElement, anchor: Element, options?: AnchorPositionOptions): () => void;
 /** Options for {@link popover}. */
 interface PopoverOptions {
     /** Where to append the popover wrapper. Default `document.body`. */
@@ -182,8 +311,34 @@ interface PopoverOptions {
  * listeners. `position: fixed` is set inline (you style everything else).
  */
 declare function popover(anchor: Element, content: OverlayContent, options?: PopoverOptions): OverlayHandle;
+/** Content for a {@link tooltip}: text (auto-escaped), `SafeHtml`, or a render function. */
+type TooltipContent = string | SafeHtml | (() => MountResult);
+/** Options for {@link tooltip}. */
+interface TooltipOptions extends AnchorPositionOptions {
+    /** Where to append the tooltip wrapper. Default `document.body`. */
+    container?: Element;
+    /** Class on the wrapper. Default `'kerf-tooltip'`. */
+    className?: string;
+    /** Delay in ms before showing after hover/focus enters. Default `400`. */
+    delay?: number;
+    /** Delay in ms before hiding after hover/focus leaves. Default `100`. */
+    hideDelay?: number;
+    /** ARIA role on the wrapper. Default `'tooltip'`. */
+    role?: string;
+}
+/**
+ * A hover/focus-triggered, non-modal, auto-hiding tooltip anchored to `anchor`.
+ * Shows after `delay` on `pointerenter`/`focus`, hides after `hideDelay` on
+ * `pointerleave`/`blur`, and positions itself with {@link autoReposition} (above
+ * the anchor by default). Unlike {@link popover} there is no click-dismiss model —
+ * it follows the pointer/focus. Returns a disposer that removes the anchor
+ * listeners and hides any shown tooltip. Structural only (kerf ships no CSS).
+ */
+declare function tooltip(anchor: Element, content: TooltipContent, options?: TooltipOptions): () => void;
 /** 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`. */
@@ -194,11 +349,47 @@ interface ToastOptions {
     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 (running the `exitClass` transition if set). Idempotent. */
+    dismiss(): void;
 }
 /**
  * Show a non-modal, auto-dismissing notification. Stacks in a shared body-level
- * region (or your `container`). Returns a `() => void` that dismisses it early.
+ * 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): () => void;
+declare function toast(content: ToastContent, options?: ToastOptions): ToastHandle;
 
-export { type ConfirmOptions, type DismissTrigger, type FieldValidator, type FormField, type FormOptions, type OverlayContent, type OverlayHandle, type OverlayOptions, type PopoverOptions, type PopoverPlacement, type PromptOptions, type ToastContent, type ToastOptions, confirm, form, overlay, popover, prompt, toast };
+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 };