kerfjs 5.0.0-beta.13 → 5.0.0-beta.131

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (94) hide show
  1. package/CHANGELOG.md +3384 -108
  2. package/README.md +101 -37
  3. package/ai/cursorrules +127 -68
  4. package/ai/manifest.json +36 -7
  5. package/ai/skill.md +167 -86
  6. package/ai/ui-skill.md +18 -0
  7. package/dist/actions.d.ts +1 -1
  8. package/dist/actions.js +10 -6
  9. package/dist/actions.js.map +1 -1
  10. package/dist/array-signal.js +1 -1
  11. package/dist/async.d.ts +7 -3
  12. package/dist/async.js +39 -22
  13. package/dist/async.js.map +1 -1
  14. package/dist/attach.js +1 -66
  15. package/dist/attach.js.map +1 -1
  16. package/dist/{chunk-GY4XV2UV.js → chunk-4TX6YJDM.js} +10 -3
  17. package/dist/chunk-4TX6YJDM.js.map +1 -0
  18. package/dist/{chunk-SVATPF5R.js → chunk-5QDM6HPD.js} +637 -277
  19. package/dist/chunk-5QDM6HPD.js.map +1 -0
  20. package/dist/{chunk-QIP723L4.js → chunk-5WRGJZV6.js} +3 -2
  21. package/dist/chunk-5WRGJZV6.js.map +1 -0
  22. package/dist/chunk-AP2FT33F.js +87 -0
  23. package/dist/chunk-AP2FT33F.js.map +1 -0
  24. package/dist/chunk-BTOKH5FA.js +70 -0
  25. package/dist/chunk-BTOKH5FA.js.map +1 -0
  26. package/dist/{chunk-ZDCJZCNO.js → chunk-GGADRIQO.js} +168 -97
  27. package/dist/chunk-GGADRIQO.js.map +1 -0
  28. package/dist/chunk-KOEGJCIS.js +65 -0
  29. package/dist/chunk-KOEGJCIS.js.map +1 -0
  30. package/dist/{chunk-HW7KSM2Y.js → chunk-KUHXPPJ4.js} +1 -1
  31. package/dist/chunk-KUHXPPJ4.js.map +1 -0
  32. package/dist/{chunk-UZJ6I4T6.js → chunk-MK42GLPV.js} +1 -1
  33. package/dist/chunk-MK42GLPV.js.map +1 -0
  34. package/dist/chunk-N4VHHOCM.js +27 -0
  35. package/dist/chunk-N4VHHOCM.js.map +1 -0
  36. package/dist/{chunk-V46JKE44.js → chunk-NRPLVJVR.js} +43 -14
  37. package/dist/chunk-NRPLVJVR.js.map +1 -0
  38. package/dist/{chunk-LVH3GC6B.js → chunk-QOAB2ESQ.js} +3 -3
  39. package/dist/chunk-QOAB2ESQ.js.map +1 -0
  40. package/dist/{chunk-KZJXHFIB.js → chunk-V322Z7FX.js} +5 -5
  41. package/dist/chunk-V322Z7FX.js.map +1 -0
  42. package/dist/{delegate-CL9VTZFb.d.ts → delegate--CrfgYtC.d.ts} +0 -34
  43. package/dist/dev.d.ts +46 -15
  44. package/dist/dev.js +185 -40
  45. package/dist/dev.js.map +1 -1
  46. package/dist/html.js +20 -8
  47. package/dist/html.js.map +1 -1
  48. package/dist/index.d.ts +98 -13
  49. package/dist/index.js +49 -21
  50. package/dist/index.js.map +1 -1
  51. package/dist/jsx-runtime.d.ts +25 -10
  52. package/dist/jsx-runtime.js +1 -1
  53. package/dist/list.d.ts +7 -3
  54. package/dist/list.js +236 -78
  55. package/dist/list.js.map +1 -1
  56. package/dist/overlay.d.ts +287 -142
  57. package/dist/overlay.js +1040 -369
  58. package/dist/overlay.js.map +1 -1
  59. package/dist/remount.js +2 -2
  60. package/dist/remount.js.map +1 -1
  61. package/dist/router.d.ts +22 -6
  62. package/dist/router.js +58 -19
  63. package/dist/router.js.map +1 -1
  64. package/dist/scope.d.ts +45 -8
  65. package/dist/scope.js +69 -30
  66. package/dist/scope.js.map +1 -1
  67. package/dist/testing.js +1 -1
  68. package/dist/timing.d.ts +17 -7
  69. package/dist/timing.js +8 -3
  70. package/dist/timing.js.map +1 -1
  71. package/llms.txt +17 -6
  72. package/package.json +48 -12
  73. package/setup/apply.mjs +202 -0
  74. package/setup/cli.mjs +95 -0
  75. package/setup/common.mjs +91 -0
  76. package/setup/detect.mjs +274 -0
  77. package/setup/index.d.mts +39 -0
  78. package/setup/index.mjs +1290 -0
  79. package/setup/jsonc.mjs +201 -0
  80. package/setup/state.schema.json +57 -0
  81. package/setup/ui-baseline.mjs +210 -0
  82. package/dist/chunk-GY4XV2UV.js.map +0 -1
  83. package/dist/chunk-HW7KSM2Y.js.map +0 -1
  84. package/dist/chunk-KPXIOG2C.js +0 -54
  85. package/dist/chunk-KPXIOG2C.js.map +0 -1
  86. package/dist/chunk-KZJXHFIB.js.map +0 -1
  87. package/dist/chunk-LVH3GC6B.js.map +0 -1
  88. package/dist/chunk-QIP723L4.js.map +0 -1
  89. package/dist/chunk-SVATPF5R.js.map +0 -1
  90. package/dist/chunk-U6FK33SG.js +0 -20
  91. package/dist/chunk-U6FK33SG.js.map +0 -1
  92. package/dist/chunk-UZJ6I4T6.js.map +0 -1
  93. package/dist/chunk-V46JKE44.js.map +0 -1
  94. package/dist/chunk-ZDCJZCNO.js.map +0 -1
package/dist/overlay.d.ts CHANGED
@@ -3,71 +3,26 @@ import { M as MountResult } from './mount-Bo2qOx25.js';
3
3
  import '@preact/signals-core';
4
4
  import './bindings-CYwoJpQb.js';
5
5
 
6
- /**
7
- * Anchored positioning primitives for `kerfjs/overlay` — position an element
8
- * relative to an anchor, with viewport flip + clamp. These are standalone: they
9
- * take any element and have no overlay lifecycle, so `popover()` / `tooltip()`
10
- * build on them but you can also position your own element (an inline hint, a
11
- * custom menu). Re-exported from `src/overlay.ts` so the public `kerfjs/overlay`
12
- * surface is unchanged (KF-511 split out of overlay.ts's dialog + toast code).
13
- */
14
- /** Vertical placement relative to an anchor (used by `popover`, {@link positionAnchored}, `tooltip`). */
15
- type PopoverPlacement = 'bottom' | 'top';
16
- /** Placement options for {@link positionAnchored} / {@link autoReposition}. */
17
- interface AnchorPositionOptions {
18
- /** Preferred side of the anchor; flips to the other side if it would overflow the viewport. Default `'bottom'`. */
19
- placement?: PopoverPlacement;
20
- /** Horizontal edge to line up with the anchor: `'start'` (left edges) or `'end'` (right edges). Default `'start'`. */
21
- align?: 'start' | 'end';
22
- /** Gap in px between the anchor and the element. Default `4`. */
23
- gap?: number;
24
- }
25
- /**
26
- * One-shot: position `el` relative to `anchor` — below by default, flipping above
27
- * if it would overflow the viewport, aligned to a horizontal edge and clamped into
28
- * view. Sets `el.style` `position: fixed`, `margin: 0`, `left`, and `top` (fixed so
29
- * `left`/`top` are viewport coordinates, matching `getBoundingClientRect`). This is
30
- * `popover()`'s placement core, usable on any element (an inline hint, a tooltip) —
31
- * no overlay lifecycle. Pair with {@link autoReposition} to keep it glued while open.
32
- */
33
- declare function positionAnchored(el: HTMLElement, anchor: Element, options?: AnchorPositionOptions): void;
34
- /**
35
- * Keep `el` positioned against `anchor` (via {@link positionAnchored}) as the page
36
- * scrolls or resizes. Positions once immediately, then re-runs on `scroll`
37
- * (capture phase — catches scrolls in any inner container, not just `window`) and
38
- * `resize`. Returns a disposer that removes the listeners.
39
- */
40
- declare function autoReposition(el: HTMLElement, anchor: Element, options?: AnchorPositionOptions): () => void;
41
-
42
- /**
43
- * Internal overlay / popover / tooltip lifecycle implementation.
44
- *
45
- * Every real kerf app hand-rolls this: `toElement → body.appendChild → mount →
46
- * wire dismissal → remove`, plus the fiddly parts (Escape, backdrop / outside
47
- * click, focus trap, restoring focus on close). `window.confirm` is a no-op in
48
- * Tauri WKWebViews, so a hand-built overlay is mandatory there. This subpath
49
- * blesses the pattern as three functions over `mount()` — `overlay()`, and the
50
- * `confirm()` / `toast()` conveniences built on it. No per-instance framework
51
- * state: each call owns its DOM + listeners in a closure and returns a handle.
52
- *
53
- * import { overlay, confirm, toast } from 'kerfjs/overlay';
54
- *
55
- * const ok = await confirm('Delete this file?', { danger: true });
56
- * toast('Saved');
57
- * const dialog = overlay(<Settings />, { dismiss: ['escape', 'backdrop'] });
58
- * // …later: dialog.close(); or await dialog.result;
59
- *
60
- * Structural only — kerf ships no CSS. The wrapper gets your `className`; style
61
- * the backdrop / centering / animation yourself.
62
- */
63
-
64
6
  /** A user-initiated dismissal trigger. */
65
7
  type DismissTrigger = 'escape' | 'backdrop' | 'outside';
66
8
  /** Content for an overlay: static `SafeHtml`, or a render function `mount()` drives reactively. */
67
9
  type OverlayContent = SafeHtml | (() => MountResult);
10
+ /**
11
+ * How an overlay is presented. `'modal'` (the default) adds nothing.
12
+ * `'bottom-sheet'` marks the wrapper `data-presentation="bottom-sheet"` and,
13
+ * while open, publishes the virtual keyboard's overlap as the inline custom
14
+ * property `--kerf-keyboard-inset`. kerf ships no CSS: the bottom-edge
15
+ * geometry, safe-area padding, and motion are the app's (or `@kerfjs/ui`'s).
16
+ */
17
+ type OverlayPresentation = 'modal' | 'bottom-sheet';
68
18
  /** Options for {@link overlay}. */
69
19
  interface OverlayOptions {
70
- /** Where to append the overlay wrapper. Default `document.body`. */
20
+ /**
21
+ * Where to append the overlay wrapper. Default `document.body`. A container
22
+ * inside an open modal `<dialog>` (including one slotted into a shadow-root
23
+ * modal such as Web Awesome's `wa-dialog`) is already interactive, so the
24
+ * surface is not lifted, and it closes when that dialog closes.
25
+ */
71
26
  container?: Element;
72
27
  /** Class on the wrapper element (you style it — kerf ships no CSS). Default `'kerf-overlay'`. */
73
28
  className?: string;
@@ -112,13 +67,51 @@ interface OverlayOptions {
112
67
  * the DOM. Default `false`.
113
68
  */
114
69
  native?: boolean;
70
+ /**
71
+ * `'bottom-sheet'` marks the wrapper `data-presentation="bottom-sheet"` (on
72
+ * both the plain `<div>` and the `native` `<dialog>` / `[popover]` hosts) and,
73
+ * while the overlay is open, follows `visualViewport` to publish the virtual
74
+ * keyboard's overlap as `--kerf-keyboard-inset: <px>` on the wrapper (removed
75
+ * when there is none, while pinch-zoomed, and on close). Style the sheet with
76
+ * those hooks — rest it on the bottom edge and add
77
+ * `max(env(safe-area-inset-bottom), var(--kerf-keyboard-inset, 0px))` to its
78
+ * block-end padding. kerf
79
+ * sets no geometry of its own. Default `'modal'` (nothing added).
80
+ */
81
+ presentation?: OverlayPresentation;
82
+ /**
83
+ * Class added when the overlay closes, so CSS owns the **exit** (mirrors
84
+ * `toast()`'s `exitClass`). Everything else happens at once — `result`
85
+ * settles, the overlay leaves the stack, a native host leaves the top layer,
86
+ * the wrapper turns `inert`, focus is restored — and only the node's removal
87
+ * waits: until the CSS animations / transitions then running in the wrapper
88
+ * finish, or `exitDuration` ms pass, whichever is first. Skipped under
89
+ * `prefers-reduced-motion: reduce`. A closed native `<dialog>` / `[popover]`
90
+ * is `display: none` unless your CSS keeps it shown during the exit.
91
+ */
92
+ exitClass?: string;
93
+ /**
94
+ * The exit's hard cap in ms (see `exitClass`). Also opts into an exit on its
95
+ * own — e.g. a native `<dialog>`'s `display` / `overlay` `allow-discrete`
96
+ * transition. Default `0`.
97
+ */
98
+ exitDuration?: number;
99
+ }
100
+ /** Options for {@link OverlayHandle.close}. */
101
+ interface OverlayCloseOptions {
102
+ /** Skip the exit and remove the node now — or end an exit already running. */
103
+ instant?: boolean;
115
104
  }
116
105
  /** Handle returned by {@link overlay}. Holds no framework state — it's a closure. */
117
106
  interface OverlayHandle {
118
107
  /** The wrapper element (mounted into, appended to `container`). */
119
108
  el: HTMLElement;
120
- /** Tear down: dispose the mount, remove listeners + the node, restore focus, resolve `result`. Idempotent. */
121
- close(result?: unknown): void;
109
+ /**
110
+ * Tear down: dispose the mount, remove listeners, restore focus, resolve
111
+ * `result`, and remove the node — after the exit, when one is configured
112
+ * (`{ instant: true }` skips or ends it). Idempotent.
113
+ */
114
+ close(result?: unknown, options?: OverlayCloseOptions): void;
122
115
  /** Resolves with the value passed to `close()` (or `undefined` on user dismissal). */
123
116
  result: Promise<unknown>;
124
117
  }
@@ -127,78 +120,16 @@ interface OverlayHandle {
127
120
  * it, wire the requested dismissals + (optionally) a focus trap, and return a
128
121
  * handle. Concurrent fallback overlays dismiss from the top down. See
129
122
  * {@link OverlayOptions}.
123
+ *
124
+ * Construction is transactional: a malformed `initialFocus` selector throws a
125
+ * descriptive error before anything is touched, and if a later setup phase
126
+ * throws (the content's first render, `showModal()` / `showPopover()`), every
127
+ * piece already installed — wrapper node, mount, listeners, fallback-stack
128
+ * entry, top-layer state, moved focus — is rolled back before the original
129
+ * error is rethrown.
130
130
  */
131
131
  declare function overlay(content: OverlayContent, options?: OverlayOptions): OverlayHandle;
132
132
 
133
- /** Options for {@link popover}. */
134
- interface PopoverOptions {
135
- /** Where to append the popover wrapper. Default `document.body`. */
136
- container?: Element;
137
- /** Class on the wrapper. Default `'kerf-popover'`. */
138
- className?: string;
139
- /** Preferred side of the anchor. Flips to the other side if it would overflow the viewport. Default `'bottom'`. */
140
- placement?: PopoverPlacement;
141
- /** Horizontal edge to line up with the anchor: `'start'` (left edges) or `'end'` (right edges). Default `'start'`. */
142
- align?: 'start' | 'end';
143
- /** Gap in px between the anchor and the popover. Default `4`. */
144
- gap?: number;
145
- /**
146
- * Which user actions dismiss the popover. Default `['outside']` (a click
147
- * outside the popover, the anchor exempt). Pass `false` to close only via `close()`.
148
- */
149
- dismiss?: DismissTrigger | DismissTrigger[] | false;
150
- /** Focus behavior on open. Default `false` (non-modal — leave focus alone). */
151
- initialFocus?: string | boolean;
152
- /** Extra elements (besides the anchor) whose clicks do NOT count as outside. */
153
- outsideIgnore?: Element | readonly Element[];
154
- /** Called on any user-initiated dismissal. */
155
- onDismiss?: () => void;
156
- /**
157
- * Host the popover in the browser top layer (the Popover API — `[popover]` +
158
- * `showPopover()`) where supported, so it stacks above any `z-index` without a
159
- * z-index war. Falls back to today's plain `<div>` where unsupported. kerf keeps
160
- * owning positioning + its own dismiss wiring; the popover is `popover="manual"`.
161
- * See {@link OverlayOptions.native}. Default `false`.
162
- */
163
- native?: boolean;
164
- }
165
- /**
166
- * Anchored, non-modal overlay: positions `content` relative to `anchor` (below by
167
- * default, flipping above if it would overflow, and clamped horizontally to the
168
- * viewport) and repositions on scroll / resize while open. A thin wrapper over
169
- * {@link overlay} with non-modal defaults — `trap: false`, `dismiss: ['outside']`,
170
- * and the anchor added to `outsideIgnore` so the trigger click doesn't self-close.
171
- * Returns the same {@link OverlayHandle}; `close()` also drops the reposition
172
- * listeners. `position: fixed` is set inline (you style everything else).
173
- */
174
- declare function popover(anchor: Element, content: OverlayContent, options?: PopoverOptions): OverlayHandle;
175
- /** Content for a {@link tooltip}: text (auto-escaped), `SafeHtml`, or a render function. */
176
- type TooltipContent = string | SafeHtml | (() => MountResult);
177
- /** Options for {@link tooltip}. */
178
- interface TooltipOptions extends AnchorPositionOptions {
179
- /** Where to append the tooltip wrapper. Default `document.body`. */
180
- container?: Element;
181
- /** Class on the wrapper. Default `'kerf-tooltip'`. */
182
- className?: string;
183
- /** Delay in ms before showing after hover/focus enters. Default `400`. */
184
- delay?: number;
185
- /** Delay in ms before hiding after hover/focus leaves. Default `100`. */
186
- hideDelay?: number;
187
- /** ARIA role on the wrapper. Default `'tooltip'`. */
188
- role?: string;
189
- /** Host the tooltip in the browser top layer (the Popover API) where supported. See {@link OverlayOptions.native}. Default `false`. */
190
- native?: boolean;
191
- }
192
- /**
193
- * A hover/focus-triggered, non-modal, auto-hiding tooltip anchored to `anchor`.
194
- * Shows after `delay` on `pointerenter`/`focus`, hides after `hideDelay` on
195
- * `pointerleave`/`blur`, and positions itself with {@link autoReposition} (above
196
- * the anchor by default). Unlike {@link popover} there is no click-dismiss model —
197
- * it follows the pointer/focus. Returns a disposer that removes the anchor
198
- * listeners and hides any shown tooltip. Structural only (kerf ships no CSS).
199
- */
200
- declare function tooltip(anchor: Element, content: TooltipContent, options?: TooltipOptions): () => void;
201
-
202
133
  /** One choosable action in a {@link choice} dialog. */
203
134
  interface ChoiceAction<R> {
204
135
  value: R;
@@ -208,7 +139,7 @@ interface ChoiceAction<R> {
208
139
  /** Wiring slots for a {@link ChoiceOptions.render}. */
209
140
  interface ChoiceRenderSlots {
210
141
  message: string;
211
- actions: Array<Record<string, string>>;
142
+ actions: Array<Record<`data-${string}`, string>>;
212
143
  }
213
144
  /** Options for {@link choice}. */
214
145
  interface ChoiceOptions<R> {
@@ -217,6 +148,12 @@ interface ChoiceOptions<R> {
217
148
  title?: string;
218
149
  defaultValue?: R;
219
150
  native?: boolean;
151
+ /** `'bottom-sheet'` presents the dialog as a bottom sheet (see `OverlayOptions.presentation`). Default `'modal'`. */
152
+ presentation?: OverlayPresentation;
153
+ /** Class added on close so CSS owns the exit; the node is removed after it (see `OverlayOptions.exitClass`). The promise settles at once. */
154
+ exitClass?: string;
155
+ /** The exit's hard cap in ms (see `OverlayOptions.exitDuration`). Default `0`. */
156
+ exitDuration?: number;
220
157
  render?: (slots: ChoiceRenderSlots) => OverlayContent;
221
158
  }
222
159
  /** The N-way sibling of {@link confirm}. */
@@ -226,9 +163,9 @@ declare function choice<R>(message: string, actions: ReadonlyArray<ChoiceAction<
226
163
  interface ConfirmRenderSlots {
227
164
  message: string;
228
165
  /** Spread onto the confirm control. */
229
- ok: Record<string, string>;
166
+ ok: Record<`data-${string}`, string>;
230
167
  /** Spread onto the cancel control. */
231
- cancel: Record<string, string>;
168
+ cancel: Record<`data-${string}`, string>;
232
169
  }
233
170
  /** Options for {@link confirm}. */
234
171
  interface ConfirmOptions {
@@ -246,15 +183,25 @@ interface ConfirmOptions {
246
183
  danger?: boolean;
247
184
  /** Host the dialog in the browser top layer where supported. */
248
185
  native?: boolean;
186
+ /** `'bottom-sheet'` presents the dialog as a bottom sheet (see `OverlayOptions.presentation`). Default `'modal'`. */
187
+ presentation?: OverlayPresentation;
188
+ /** Class added on close so CSS owns the exit; the node is removed after it (see `OverlayOptions.exitClass`). The promise settles at once. */
189
+ exitClass?: string;
190
+ /** The exit's hard cap in ms (see `OverlayOptions.exitDuration`). Default `0`. */
191
+ exitDuration?: number;
249
192
  /** Bring your own body while retaining kerf's dialog wiring. */
250
193
  render?: (slots: ConfirmRenderSlots) => OverlayContent;
251
194
  }
252
195
  /** A promise-based `window.confirm` replacement. */
253
196
  declare function confirm(message: string, options?: ConfirmOptions): Promise<boolean>;
254
197
 
255
- /** Validate a single field's value. */
198
+ /**
199
+ * Validate a single field's value, synchronously: return a non-empty message
200
+ * to block OK, anything else to accept. A validator that throws is treated as
201
+ * a programming error — the dialog closes and the returned promise rejects
202
+ * with that error.
203
+ */
256
204
  type FieldValidator = (value: string) => string | null | undefined | void;
257
- /** Options for {@link prompt}. */
258
205
  interface PromptOptions {
259
206
  container?: Element;
260
207
  className?: string;
@@ -266,15 +213,21 @@ interface PromptOptions {
266
213
  cancelText?: string;
267
214
  validate?: FieldValidator;
268
215
  native?: boolean;
216
+ /** `'bottom-sheet'` presents the dialog as a bottom sheet (see `OverlayOptions.presentation`). Default `'modal'`. */
217
+ presentation?: OverlayPresentation;
218
+ /** Class added on close so CSS owns the exit; the node is removed after it (see `OverlayOptions.exitClass`). The promise settles at once. */
219
+ exitClass?: string;
220
+ /** The exit's hard cap in ms (see `OverlayOptions.exitDuration`). Default `0`. */
221
+ exitDuration?: number;
269
222
  render?: (slots: PromptRenderSlots) => OverlayContent;
270
223
  }
271
224
  /** Wiring slots for a {@link PromptOptions.render}. */
272
225
  interface PromptRenderSlots {
273
226
  message: string;
274
227
  input: Record<string, string>;
275
- error: Record<string, string>;
276
- ok: Record<string, string>;
277
- cancel: Record<string, string>;
228
+ error: Record<`data-${string}`, string>;
229
+ ok: Record<`data-${string}`, string>;
230
+ cancel: Record<`data-${string}`, string>;
278
231
  }
279
232
  /** A promise-based `window.prompt` replacement. */
280
233
  declare function prompt(message: string, options?: PromptOptions): Promise<string | null>;
@@ -293,13 +246,13 @@ interface FormRenderField {
293
246
  name: string;
294
247
  label: string;
295
248
  input: Record<string, string>;
296
- error: Record<string, string>;
249
+ error: Record<`data-${string}`, string>;
297
250
  }
298
251
  /** Wiring slots for a {@link FormOptions.render}. */
299
252
  interface FormRenderSlots {
300
253
  fields: FormRenderField[];
301
- ok: Record<string, string>;
302
- cancel: Record<string, string>;
254
+ ok: Record<`data-${string}`, string>;
255
+ cancel: Record<`data-${string}`, string>;
303
256
  }
304
257
  /** Options for {@link form}. */
305
258
  interface FormOptions {
@@ -309,11 +262,165 @@ interface FormOptions {
309
262
  okText?: string;
310
263
  cancelText?: string;
311
264
  native?: boolean;
265
+ /** `'bottom-sheet'` presents the dialog as a bottom sheet (see `OverlayOptions.presentation`). Default `'modal'`. */
266
+ presentation?: OverlayPresentation;
267
+ /** Class added on close so CSS owns the exit; the node is removed after it (see `OverlayOptions.exitClass`). The promise settles at once. */
268
+ exitClass?: string;
269
+ /** The exit's hard cap in ms (see `OverlayOptions.exitDuration`). Default `0`. */
270
+ exitDuration?: number;
312
271
  render?: (slots: FormRenderSlots) => OverlayContent;
313
272
  }
314
273
  /** A promise-based multi-field dialog. */
315
274
  declare function form(fields: readonly FormField[], options?: FormOptions): Promise<Record<string, string> | null>;
316
275
 
276
+ /**
277
+ * Anchored positioning primitives for `kerfjs/overlay` — position an element
278
+ * relative to an anchor, with viewport flip + clamp. These are standalone: they
279
+ * take any element and have no overlay lifecycle, so `popover()` / `tooltip()`
280
+ * build on them but you can also position your own element (an inline hint, a
281
+ * custom menu). Re-exported from `src/overlay.ts` so the public `kerfjs/overlay`
282
+ * surface is unchanged (KF-511 split out of overlay.ts's dialog + toast code).
283
+ */
284
+ /** Vertical placement relative to an anchor (used by `popover`, {@link positionAnchored}, `tooltip`). */
285
+ type PopoverPlacement = 'bottom' | 'top';
286
+ /** Placement options for {@link positionAnchored} / {@link autoReposition}. */
287
+ interface AnchorPositionOptions {
288
+ /** Preferred side of the anchor; flips to the other side if it would overflow the viewport. Default `'bottom'`. */
289
+ placement?: PopoverPlacement;
290
+ /** Horizontal edge to line up with the anchor: `'start'` (left edges) or `'end'` (right edges). Default `'start'`. */
291
+ align?: 'start' | 'end';
292
+ /** Gap in px between the anchor and the element. Default `4`. */
293
+ gap?: number;
294
+ /**
295
+ * Gutter in px kept between the element and the viewport edges: the
296
+ * horizontal clamp stops this far inside the left and right edges, and a
297
+ * side fits only when the element ends this far inside the top or bottom
298
+ * edge. Default `0` (the bare viewport edge).
299
+ */
300
+ viewportMargin?: number;
301
+ /**
302
+ * The element's height can shrink (it scrolls its overflow). When neither
303
+ * side has room for its full height, it takes the side with more room, and
304
+ * that room — from the gap to the viewport margin, in `el`'s CSS px — is
305
+ * published on `el` as the `--kerf-anchor-available-height` custom property
306
+ * on every reposition. Cap the element with it, for example
307
+ * `max-height: var(--kerf-anchor-available-height); overflow: auto`. The
308
+ * height measured for that choice honors the element's own `max-height`
309
+ * (read without the published property, so `max-height: min(300px,
310
+ * var(--kerf-anchor-available-height))` counts as a 300px cap), so an
311
+ * app-capped element that fits the preferred side stays there. A relative
312
+ * cap (`60%`, `calc()`, `min()`, `clamp()`) is resolved against the
313
+ * element's fixed-position containing block (normally the viewport), and a
314
+ * `max-height` transition on the element neither skews that read nor runs
315
+ * because of it. While an animation or transition is already driving
316
+ * `max-height` (an expand-from-0 entrance, a `@keyframes` animation), the
317
+ * cap is the value it is headed to, and it is left running. An above
318
+ * placement is pinned by its bottom edge (`bottom`, with `top: auto`), so
319
+ * the element grows and shrinks upward, away from the anchor, as its height
320
+ * changes between repositions; a below placement sets `top` with
321
+ * `bottom: auto`. Default `false`.
322
+ */
323
+ fitHeight?: boolean;
324
+ }
325
+ /**
326
+ * One-shot: position `el` relative to `anchor` — below by default, flipping above
327
+ * if it would overflow the viewport, aligned to a horizontal edge and clamped into
328
+ * view. Sets `el.style` `position: fixed`, `margin: 0`, `left`, and `top` (fixed so
329
+ * `left`/`top` are viewport coordinates, matching `getBoundingClientRect`). When an
330
+ * ancestor makes itself the containing block for fixed descendants (a
331
+ * `transform`, `filter`, `perspective`, or `contain` on a wrapping `<dialog>`),
332
+ * `left`/`top` are translated (and unscaled) into that box's coordinates so `el`
333
+ * still lands next to the anchor. `viewportMargin` keeps a gutter from the
334
+ * viewport edges; `fitHeight` publishes the room on the chosen side so CSS can
335
+ * cap a scrolling element to it, and pins an above placement by `bottom`
336
+ * (with `top: auto`) so the element grows upward from the anchor. This is
337
+ * `popover()`'s placement core, usable on any element (an inline hint, a tooltip) —
338
+ * no overlay lifecycle. Pair with {@link autoReposition} to keep it glued while open.
339
+ */
340
+ declare function positionAnchored(el: HTMLElement, anchor: Element, options?: AnchorPositionOptions): void;
341
+ /**
342
+ * Keep `el` positioned against `anchor` (via {@link positionAnchored}) as the page
343
+ * scrolls or resizes. Positions once immediately, then re-runs on `scroll`
344
+ * (capture phase — catches scrolls in any inner container, not just `window`),
345
+ * `resize`, and, where `ResizeObserver` exists, whenever the anchor's or `el`'s
346
+ * own size changes — a field that grows a line as it fills, or an end-aligned
347
+ * or above-placed surface whose content grows — so `el` stays lined up with
348
+ * the anchor edge it hangs from. A size change that `el`'s own repositioning
349
+ * caused (a published `fitHeight` cap, a shrink-to-fit width near the viewport
350
+ * edge) is not acted on again, so positioning can never feed itself. Returns
351
+ * a disposer that removes the listeners and the observer.
352
+ */
353
+ declare function autoReposition(el: HTMLElement, anchor: Element, options?: AnchorPositionOptions): () => void;
354
+
355
+ /** Options for {@link popover}. */
356
+ interface PopoverOptions {
357
+ /**
358
+ * Where to append the popover wrapper. Default: when `anchor` sits inside an
359
+ * open modal `<dialog>`, that dialog's `[data-kerf-overlay-host]` element (a
360
+ * dialog kerf opened gets one automatically), so the popover is part of the
361
+ * modal subtree and stays interactive; otherwise `document.body`. A modal
362
+ * `<dialog>` in a shadow root counts when `anchor` is slotted into it (Web
363
+ * Awesome's `wa-dialog` / `wa-drawer`): the slot is created on demand in the
364
+ * shadow host's light DOM. A popover inside a modal closes when that dialog
365
+ * closes.
366
+ */
367
+ container?: Element;
368
+ /** Class on the wrapper. Default `'kerf-popover'`. */
369
+ className?: string;
370
+ /** Preferred side of the anchor. Flips to the other side if it would overflow the viewport. Default `'bottom'`. */
371
+ placement?: PopoverPlacement;
372
+ /** Horizontal edge to line up with the anchor: `'start'` (left edges) or `'end'` (right edges). Default `'start'`. */
373
+ align?: 'start' | 'end';
374
+ /** Gap in px between the anchor and the popover. Default `4`. */
375
+ gap?: number;
376
+ /** Gutter in px kept from the viewport edges. See `AnchorPositionOptions.viewportMargin`. Default `0`. */
377
+ viewportMargin?: number;
378
+ /**
379
+ * Fit a scrolling popover to the room beside the anchor: take the roomier
380
+ * side when neither fits and publish that room as
381
+ * `--kerf-anchor-available-height`. See `AnchorPositionOptions.fitHeight`.
382
+ * Default `false`.
383
+ */
384
+ fitHeight?: boolean;
385
+ /**
386
+ * Which user actions dismiss the popover. Default `['outside']` (a click
387
+ * outside the popover, the anchor exempt). Pass `false` to close only via `close()`.
388
+ */
389
+ dismiss?: DismissTrigger | DismissTrigger[] | false;
390
+ /** Focus behavior on open. Default `false` (non-modal — leave focus alone). */
391
+ initialFocus?: string | boolean;
392
+ /** Extra elements (besides the anchor) whose clicks do NOT count as outside. */
393
+ outsideIgnore?: Element | readonly Element[];
394
+ /** Called on any user-initiated dismissal. */
395
+ onDismiss?: () => void;
396
+ /**
397
+ * Host the popover in the browser top layer (the Popover API — `[popover]` +
398
+ * `showPopover()`) where supported, so it stacks above any `z-index` without a
399
+ * z-index war. Falls back to today's plain `<div>` where unsupported. kerf keeps
400
+ * owning positioning + its own dismiss wiring; the popover is `popover="manual"`.
401
+ * See {@link OverlayOptions.native}. Default `false`.
402
+ */
403
+ native?: boolean;
404
+ /**
405
+ * Class added when the popover closes, so CSS owns its **exit**. See
406
+ * {@link OverlayOptions.exitClass}: `close()` and a user dismissal play it;
407
+ * the teardown when the anchor leaves the document is instant.
408
+ */
409
+ exitClass?: string;
410
+ /** The exit's hard cap in ms. See {@link OverlayOptions.exitDuration}. Default `0`. */
411
+ exitDuration?: number;
412
+ }
413
+ /**
414
+ * Anchored, non-modal overlay: positions `content` relative to `anchor` (below by
415
+ * default, flipping above if it would overflow, and clamped horizontally to the
416
+ * viewport) and repositions on scroll / resize while open. A thin wrapper over
417
+ * {@link overlay} with non-modal defaults — `trap: false`, `dismiss: ['outside']`,
418
+ * and the anchor added to `outsideIgnore` so the trigger click doesn't self-close.
419
+ * Returns the same {@link OverlayHandle}; `close()` also drops the reposition
420
+ * listeners. `position: fixed` is set inline (you style everything else).
421
+ */
422
+ declare function popover(anchor: Element, content: OverlayContent, options?: PopoverOptions): OverlayHandle;
423
+
317
424
  /**
318
425
  * `toast()` for `kerfjs/overlay` — a non-modal, auto-dismissing notification that
319
426
  * stacks in a shared body-level region. Split out of `overlay.ts` (KF-513) since
@@ -386,4 +493,42 @@ interface ToastHandle {
386
493
  */
387
494
  declare function toast(content: ToastContent, options?: ToastOptions): ToastHandle;
388
495
 
389
- 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 };
496
+ /** Content for a {@link tooltip}: text (auto-escaped), `SafeHtml`, or a render function. */
497
+ type TooltipContent = string | SafeHtml | (() => MountResult);
498
+ /** Options for {@link tooltip}. */
499
+ interface TooltipOptions extends AnchorPositionOptions {
500
+ /** Where to append the tooltip wrapper. Default: the anchor's modal-dialog host slot (see {@link PopoverOptions.container}), else `document.body`. */
501
+ container?: Element;
502
+ /** Class on the wrapper. Default `'kerf-tooltip'`. */
503
+ className?: string;
504
+ /** Delay in ms before showing after hover/focus enters. Default `400`. */
505
+ delay?: number;
506
+ /** Delay in ms before hiding after hover/focus leaves. Default `100`. */
507
+ hideDelay?: number;
508
+ /** ARIA role on the wrapper. Default `'tooltip'`. */
509
+ role?: string;
510
+ /** Host the tooltip in the browser top layer (the Popover API) where supported. See {@link OverlayOptions.native}. Default `false`. */
511
+ native?: boolean;
512
+ /**
513
+ * Class added when the tooltip hides, so CSS owns its **exit**. See
514
+ * {@link OverlayOptions.exitClass}: the hide after `hideDelay` plays it;
515
+ * the anchor leaving the document and the disposer hide instantly. Showing
516
+ * again while the previous tooltip is still exiting removes that leaving
517
+ * node at once and opens a fresh one, so an anchor never has two.
518
+ */
519
+ exitClass?: string;
520
+ /** The exit's hard cap in ms. See {@link OverlayOptions.exitDuration}. Default `0`. */
521
+ exitDuration?: number;
522
+ }
523
+ /**
524
+ * A hover/focus-triggered, non-modal, auto-hiding tooltip anchored to `anchor`.
525
+ * Shows after `delay` on `pointerenter`/`focus`, hides after `hideDelay` on
526
+ * `pointerleave`/`blur`, and positions itself with {@link autoReposition} (above
527
+ * the anchor by default). Unlike {@link popover} there is no click-dismiss model —
528
+ * it follows the pointer/focus. Returns a disposer that removes the anchor
529
+ * listeners and hides any shown tooltip at once (ending a running exit, too).
530
+ * Structural only (kerf ships no CSS).
531
+ */
532
+ declare function tooltip(anchor: Element, content: TooltipContent, options?: TooltipOptions): () => void;
533
+
534
+ 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 OverlayCloseOptions, type OverlayContent, type OverlayHandle, type OverlayOptions, type OverlayPresentation, 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 };