kerfjs 5.0.0-beta.13 → 5.0.0-beta.130
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.
- package/CHANGELOG.md +3370 -108
- package/README.md +101 -37
- package/ai/cursorrules +127 -68
- package/ai/manifest.json +36 -7
- package/ai/skill.md +167 -86
- package/ai/ui-skill.md +18 -0
- package/dist/actions.d.ts +1 -1
- package/dist/actions.js +10 -6
- package/dist/actions.js.map +1 -1
- package/dist/array-signal.js +1 -1
- package/dist/async.d.ts +7 -3
- package/dist/async.js +39 -22
- package/dist/async.js.map +1 -1
- package/dist/attach.js +1 -66
- package/dist/attach.js.map +1 -1
- package/dist/{chunk-GY4XV2UV.js → chunk-4TX6YJDM.js} +10 -3
- package/dist/chunk-4TX6YJDM.js.map +1 -0
- package/dist/{chunk-SVATPF5R.js → chunk-5QDM6HPD.js} +637 -277
- package/dist/chunk-5QDM6HPD.js.map +1 -0
- package/dist/{chunk-QIP723L4.js → chunk-5WRGJZV6.js} +3 -2
- package/dist/chunk-5WRGJZV6.js.map +1 -0
- package/dist/chunk-AP2FT33F.js +87 -0
- package/dist/chunk-AP2FT33F.js.map +1 -0
- package/dist/chunk-BTOKH5FA.js +70 -0
- package/dist/chunk-BTOKH5FA.js.map +1 -0
- package/dist/{chunk-ZDCJZCNO.js → chunk-GGADRIQO.js} +168 -97
- package/dist/chunk-GGADRIQO.js.map +1 -0
- package/dist/chunk-KOEGJCIS.js +65 -0
- package/dist/chunk-KOEGJCIS.js.map +1 -0
- package/dist/{chunk-HW7KSM2Y.js → chunk-KUHXPPJ4.js} +1 -1
- package/dist/chunk-KUHXPPJ4.js.map +1 -0
- package/dist/{chunk-UZJ6I4T6.js → chunk-MK42GLPV.js} +1 -1
- package/dist/chunk-MK42GLPV.js.map +1 -0
- package/dist/chunk-N4VHHOCM.js +27 -0
- package/dist/chunk-N4VHHOCM.js.map +1 -0
- package/dist/{chunk-V46JKE44.js → chunk-NRPLVJVR.js} +43 -14
- package/dist/chunk-NRPLVJVR.js.map +1 -0
- package/dist/{chunk-LVH3GC6B.js → chunk-QOAB2ESQ.js} +3 -3
- package/dist/chunk-QOAB2ESQ.js.map +1 -0
- package/dist/{chunk-KZJXHFIB.js → chunk-V322Z7FX.js} +5 -5
- package/dist/chunk-V322Z7FX.js.map +1 -0
- package/dist/{delegate-CL9VTZFb.d.ts → delegate--CrfgYtC.d.ts} +0 -34
- package/dist/dev.d.ts +46 -15
- package/dist/dev.js +185 -40
- package/dist/dev.js.map +1 -1
- package/dist/html.js +20 -8
- package/dist/html.js.map +1 -1
- package/dist/index.d.ts +98 -13
- package/dist/index.js +49 -21
- package/dist/index.js.map +1 -1
- package/dist/jsx-runtime.d.ts +25 -10
- package/dist/jsx-runtime.js +1 -1
- package/dist/list.d.ts +7 -3
- package/dist/list.js +236 -78
- package/dist/list.js.map +1 -1
- package/dist/overlay.d.ts +287 -142
- package/dist/overlay.js +1039 -369
- package/dist/overlay.js.map +1 -1
- package/dist/remount.js +2 -2
- package/dist/remount.js.map +1 -1
- package/dist/router.d.ts +22 -6
- package/dist/router.js +58 -19
- package/dist/router.js.map +1 -1
- package/dist/scope.d.ts +45 -8
- package/dist/scope.js +69 -30
- package/dist/scope.js.map +1 -1
- package/dist/testing.js +1 -1
- package/dist/timing.d.ts +17 -7
- package/dist/timing.js +8 -3
- package/dist/timing.js.map +1 -1
- package/llms.txt +17 -6
- package/package.json +48 -12
- package/setup/apply.mjs +202 -0
- package/setup/cli.mjs +95 -0
- package/setup/common.mjs +77 -0
- package/setup/detect.mjs +274 -0
- package/setup/index.d.mts +39 -0
- package/setup/index.mjs +1226 -0
- package/setup/jsonc.mjs +201 -0
- package/setup/state.schema.json +57 -0
- package/setup/ui-baseline.mjs +210 -0
- package/dist/chunk-GY4XV2UV.js.map +0 -1
- package/dist/chunk-HW7KSM2Y.js.map +0 -1
- package/dist/chunk-KPXIOG2C.js +0 -54
- package/dist/chunk-KPXIOG2C.js.map +0 -1
- package/dist/chunk-KZJXHFIB.js.map +0 -1
- package/dist/chunk-LVH3GC6B.js.map +0 -1
- package/dist/chunk-QIP723L4.js.map +0 -1
- package/dist/chunk-SVATPF5R.js.map +0 -1
- package/dist/chunk-U6FK33SG.js +0 -20
- package/dist/chunk-U6FK33SG.js.map +0 -1
- package/dist/chunk-UZJ6I4T6.js.map +0 -1
- package/dist/chunk-V46JKE44.js.map +0 -1
- 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
|
-
/**
|
|
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
|
-
/**
|
|
121
|
-
|
|
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
|
|
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
|
|
166
|
+
ok: Record<`data-${string}`, string>;
|
|
230
167
|
/** Spread onto the cancel control. */
|
|
231
|
-
cancel: Record
|
|
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
|
-
/**
|
|
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
|
|
276
|
-
ok: Record
|
|
277
|
-
cancel: Record
|
|
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
|
|
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
|
|
302
|
-
cancel: Record
|
|
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
|
-
|
|
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 };
|