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/ai/cursorrules
CHANGED
|
@@ -1,18 +1,23 @@
|
|
|
1
|
-
<!-- kerf-skill-version: 1.
|
|
1
|
+
<!-- kerf-skill-version: 1.27.0 -->
|
|
2
|
+
|
|
2
3
|
# kerf.cursorrules — rules for building apps with kerf
|
|
4
|
+
|
|
3
5
|
#
|
|
6
|
+
|
|
4
7
|
# Drop this file into your project as `.cursorrules` (Cursor will pick it
|
|
8
|
+
|
|
5
9
|
# up automatically) when you're using kerf (https://github.com/brianwestphal/kerf).
|
|
10
|
+
|
|
6
11
|
# These rules condense `docs/ai/usage-guide.md` into the form Cursor parses.
|
|
7
12
|
|
|
8
|
-
You are writing a UI in kerf — a ~
|
|
13
|
+
You are writing a UI in kerf — a ~15 KB reactive framework (still ~15 KB with `arraySignal`): signals + DOM morphing + JSX → HTML strings. No virtual DOM, no compiler, no scheduler.
|
|
9
14
|
|
|
10
15
|
## Setup
|
|
11
16
|
|
|
12
17
|
- Install with `npm install kerfjs`.
|
|
13
18
|
- `tsconfig.json`: `"jsx": "react-jsx"`, `"jsxImportSource": "kerfjs"`.
|
|
14
19
|
- Vite / esbuild need no extra config.
|
|
15
|
-
- **Dev diagnostics are opt-in by import, and only an APP installs them.** kerf does not infer dev mode. In the app entry add `if (import.meta.env.DEV) await import('kerfjs/dev');` (Vite) or `if (process.env.NODE_ENV !== 'production') await import('kerfjs/dev');` (webpack/Node). That enables the read-only store `get()` snapshot, the throwing dangerous-URL screen, and makes the `KERF_DEV_WARN_*` family available; omitting it is production shape and sheds ~4.7 KB min+gzip because the condition folds away and the chunk is never emitted. Put it FIRST if relying on the untracked-signal
|
|
20
|
+
- **Dev diagnostics are opt-in by import, and only an APP installs them.** kerf does not infer dev mode. In the app entry add `if (import.meta.env.DEV) await import('kerfjs/dev');` (Vite) or `if (process.env.NODE_ENV !== 'production') await import('kerfjs/dev');` (webpack/Node). That enables the read-only store `get()` snapshot, the throwing dangerous-URL screen, and makes the `KERF_DEV_WARN_*` family available; omitting it is production shape and sheds ~4.7 KB min+gzip because the condition folds away and the chunk is never emitted. Put it (and any `enableWarnings()` call) FIRST if relying on the untracked-signal, delegate-in-effect, or rebuilt-listeners warnings — `signal()`, `effect()`, and `mount()` decide those at creation time, so anything created earlier stays uncovered.
|
|
16
21
|
- **Switch individual warnings on with `enableWarnings()`**, which is the only switch that works in a browser (no `process` object there, and a bundler `define` cannot reach the read): `const dev = await import('kerfjs/dev'); dev.enableWarnings({ staleBinding: true, narrowSet: true, invariants: 'throw' });`. The `KERF_DEV_WARN_*` env vars do the same for Node/SSR/CI; an explicit call wins either way.
|
|
17
22
|
- **A component package must NEVER import `kerfjs/dev`.** The hooks are process-global, so installing them is the consuming app's decision — a library that does it forces the diagnostics (and the chunk) on every consumer. Put the import in your demo page or test harness instead.
|
|
18
23
|
- Recommended: also install `eslint-plugin-kerfjs` (`npm install --save-dev eslint-plugin-kerfjs`) and add `kerfjs.configs.recommended` to the project's eslint config. It enforces five of the hard rules below (no inline JSX event handlers, require `data-key` in `each()`, capture `delegate()` disposers, no nested `mount()`, prefer module JSX augmentation) at edit time so violations surface as IDE squiggles before any code runs.
|
|
@@ -28,79 +33,107 @@ the complete layer is intentional. Reuse these primitives before creating
|
|
|
28
33
|
parallel local ones; keep domain state, commands, routing, and tab/menu policy
|
|
29
34
|
in the app.
|
|
30
35
|
|
|
31
|
-
Use
|
|
32
|
-
`data-*` metadata.
|
|
36
|
+
Use ListItem/ListActionRow/ListHeader `rootAttributes` only for application
|
|
37
|
+
`data-*` metadata. ListActionRow `trailingActionAttributes` and ListHeader
|
|
33
38
|
`triggerAttributes` additionally support native popover target/action and
|
|
34
39
|
`aria-controls`/`aria-haspopup`. Do not use these slots to override action,
|
|
35
40
|
item identity, selection, disclosure, naming, disabled, icon, or role
|
|
36
41
|
semantics; one `role="menuitem"` does not make a complete menu widget.
|
|
37
|
-
`
|
|
42
|
+
`ListItem.trailing` is dormant. Use `ListActionRow` for sibling primary and
|
|
38
43
|
trailing native buttons, and keep its `label`, `icon`, and
|
|
39
44
|
`trailingActionIcon` SafeHtml slots free of controls.
|
|
40
45
|
|
|
41
46
|
Wire emitted `data-action` hooks at the mount root and retain disposers.
|
|
42
47
|
`wireResizableRegions()` and `wireTabBars()` are eventful helpers and return
|
|
43
|
-
disposers. Compose `
|
|
48
|
+
disposers. Compose `TabBarItem` inside controlled `TabBar`; `wireTabBars()` supplies
|
|
44
49
|
horizontal edge autoscroll while dragging. Apply reorder reports
|
|
45
50
|
with `reorderTabs()`, and keep order, selection, close policy, routing, panels,
|
|
46
|
-
and persistence in the host.
|
|
51
|
+
and persistence in the host. Toolbars draw no divider by default; call
|
|
52
|
+
`wireScrollDividers()` once at the app root so panes and tab bars show scroll
|
|
53
|
+
dividers only while content is scrolled beneath or beyond them. Icons/spinners are decorative unless
|
|
47
54
|
labeled, and assertive banners are only for urgent interruption.
|
|
48
55
|
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
56
|
+
Components own their styles; configure, never override. Set how a component
|
|
57
|
+
looks and sits through its typed props (size, density, inset, presentation,
|
|
58
|
+
`dividerSides`, `ToolbarConfig`, `PaneConfig`, …); never write application
|
|
59
|
+
CSS that selects a `.kui-*` class, a `[data-component]` root, a `wa-*` element
|
|
60
|
+
a Kerf component renders, or its `::part()`s, and never add padding, margin,
|
|
61
|
+
width, or height around a component to size or space it (it owns its 8px
|
|
62
|
+
inset — adding more double-insets). A missing prop is a component gap to
|
|
63
|
+
report upstream, not a reason to override. The opinionated semantic ramps
|
|
64
|
+
match Hot Sheet 2 and Web Awesome: override `--kui-color-*` globally or
|
|
65
|
+
component properties such as `--kui-state-banner-background` at a tone or
|
|
66
|
+
instance boundary, for theming only.
|
|
67
|
+
|
|
68
|
+
Scope a subtree to the light or dark palette with a component's
|
|
69
|
+
`scheme="light" | "dark"` prop or Kerf's `.kui-light` / `.kui-dark` /
|
|
70
|
+
`.kui-invert` classes; they need no Web Awesome CSS. Only with the optional
|
|
71
|
+
Web Awesome integration: import the CSS-only `@kerfjs/ui/webawesome.css` theme
|
|
72
|
+
once, then only each Web Awesome component module the app renders. The theme
|
|
73
|
+
registers no component JavaScript and remains overridable through later or
|
|
74
|
+
scoped `--wa-*` values.
|
|
58
75
|
|
|
59
76
|
`Select` is pure markup until the app explicitly imports
|
|
60
77
|
`@kerfjs/ui/select/register`. Do that once in the application entry that uses
|
|
61
78
|
Select; never hide registration inside a component. Web Awesome is an optional
|
|
62
|
-
peer
|
|
79
|
+
peer that only the `@kerfjs/ui/webawesome.css` theme touches. More detail ships at
|
|
63
80
|
`node_modules/@kerfjs/ui/ai/skill.md`.
|
|
64
81
|
|
|
65
82
|
## Public API — one import path
|
|
66
83
|
|
|
67
84
|
```ts
|
|
68
85
|
import {
|
|
69
|
-
signal,
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
86
|
+
signal,
|
|
87
|
+
computed,
|
|
88
|
+
effect,
|
|
89
|
+
batch,
|
|
90
|
+
selector,
|
|
91
|
+
setSelector, // reactivity
|
|
92
|
+
defineStore,
|
|
93
|
+
resetAllStores, // stores
|
|
94
|
+
mount,
|
|
95
|
+
morph,
|
|
96
|
+
each, // render (reactive + one-shot) + keyed list
|
|
97
|
+
delegate,
|
|
98
|
+
delegateCapture, // events
|
|
99
|
+
toElement, // direct JSX → DOM Element (or DocumentFragment for multi-root)
|
|
100
|
+
SafeHtml,
|
|
101
|
+
isSafeHtml,
|
|
102
|
+
raw,
|
|
103
|
+
Fragment,
|
|
104
|
+
type JSXChildren,
|
|
105
|
+
} from "kerfjs";
|
|
76
106
|
|
|
77
107
|
// Optional, only when you need granular collection updates:
|
|
78
|
-
import { arraySignal } from
|
|
108
|
+
import { arraySignal } from "kerfjs/array-signal";
|
|
79
109
|
|
|
80
110
|
// Development diagnostics — gate with YOUR build's dev flag, in YOUR code.
|
|
81
|
-
if (import.meta.env.DEV) await import(
|
|
111
|
+
if (import.meta.env.DEV) await import("kerfjs/dev");
|
|
82
112
|
```
|
|
83
113
|
|
|
84
|
-
| Export
|
|
85
|
-
|
|
|
86
|
-
| `signal(initial)`
|
|
87
|
-
| `computed(fn)`
|
|
88
|
-
| `effect(fn)`
|
|
89
|
-
| `batch(fn)`
|
|
90
|
-
| `
|
|
91
|
-
| `
|
|
92
|
-
| `
|
|
93
|
-
| `
|
|
94
|
-
| `
|
|
95
|
-
| `
|
|
96
|
-
| `
|
|
97
|
-
| `
|
|
98
|
-
| `
|
|
99
|
-
| `
|
|
100
|
-
| `
|
|
101
|
-
| `
|
|
102
|
-
| `
|
|
103
|
-
|
|
|
114
|
+
| Export | Use |
|
|
115
|
+
| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
116
|
+
| `signal(initial)` | atomic reactive state; read/write via `.value` |
|
|
117
|
+
| `computed(fn)` | derived value (read-only) |
|
|
118
|
+
| `effect(fn)` | side effect that re-runs on signal change |
|
|
119
|
+
| `batch(fn)` | coalesce multiple writes into one re-run |
|
|
120
|
+
| `selector(source)` | keyed equality at O(1) per change: `selector(selectedId)(row.id).value` is true for the selected row; one subscription instead of one per row |
|
|
121
|
+
| `setSelector(source)` | membership in a `ReadonlySet` signal; a write notifies only the added/removed members (multi-select, expanded rows) |
|
|
122
|
+
| `defineStore({initial, actions})` | named multi-consumer state |
|
|
123
|
+
| `resetAllStores()` | reset every store (test teardown) |
|
|
124
|
+
| `mount(el, render)` | bind reactive render to a DOM element; returns a disposer |
|
|
125
|
+
| `morph(liveRoot, template)` | one-shot reconcile against an already-populated element (SSR hydration, page-refresh diffs). Template can be `Element`, `SafeHtml`, or HTML string |
|
|
126
|
+
| `each(items, render, cacheKey?)` | keyed list iteration; per-row memoization on object identity (+ optional cacheKey — a passive comparator for external state). Distinct from `data-key` on the rendered element |
|
|
127
|
+
| `each(items, render, { cacheKey, key })` | same, options form. **`key` gives the list a stable identity** — required whenever a _conditional_ list can render before this one, else kerf rebuilds this list and its rows lose focus/scroll/IME. A keyed list takes no positional slot, so keying the conditional list usually fixes its siblings too |
|
|
128
|
+
| `delegate(root, type, sel, h)` | one listener at the root, walks `closest(selector)` from target |
|
|
129
|
+
| `delegateCapture(root, type, sel, h, opts?)` | capture-phase escape hatch; `closest()` walk-up by default (same as `delegate`); pass `{ match: 'direct' }` for strict `target.matches()` |
|
|
130
|
+
| `attr(name, value)` | pre-computed `AttrSpec<N,V>` — `.selector` for `delegate()`, `.attrs` to spread into JSX (rename-safe) |
|
|
131
|
+
| `attr(name)` | dynamic factory — `attr<N,V=string>(name)` returns `(value: V) => { readonly [name]: V }`; both generics off → N inferred, V defaults to string; specify both to constrain values |
|
|
132
|
+
| `toElement(jsx)` | parse JSX into a DOM node (SVG-aware). Single-root → `Element`; multi-root (`<><svg/> label</>`, two icons side by side) → `DocumentFragment` that `appendChild`/`replaceChildren`/`append` inlines into the parent. |
|
|
133
|
+
| `raw(html)` | inject pre-escaped HTML |
|
|
134
|
+
| `JSXChildren` | recursive type for general-purpose component `children`: SafeHtml, primitives, read-only signals, nullish/boolean empty values, and readonly arrays at any depth. Use a narrower union for semantically restricted slots |
|
|
135
|
+
| `arraySignal(initial?)` | granular keyed-list signal at `kerfjs/array-signal` subpath; `each()` reconciles in O(patches) |
|
|
136
|
+
| `` html`…` `` | tagged template at `kerfjs/html` subpath — JSX-identical runtime semantics with NO build step (CDN/importmap projects). Real HTML attribute names (`class`, not `className`); holes only in text positions or as a COMPLETE attribute value (`attr=${v}` / `attr="${v}"`) |
|
|
104
137
|
|
|
105
138
|
## Hard rules — get these right on the first try
|
|
106
139
|
|
|
@@ -109,9 +142,9 @@ if (import.meta.env.DEV) await import('kerfjs/dev');
|
|
|
109
142
|
3. **Escape hatches:** `data-morph-skip` (element + subtree preserved verbatim — for Monaco / xterm / D3); `data-morph-skip-children` (attrs morph, subtree preserved — for client-hydrated slots whose host classes change); `data-morph-preserve` (element survives the trailing-removal pass — for imperatively-injected nodes like autoplay videos).
|
|
110
143
|
4. **Never `addEventListener` inside a `mount()`-managed tree** unless under `data-morph-skip`. A morph re-render may discard the node. Use `delegate` / `delegateCapture` instead.
|
|
111
144
|
5. **Capture the `delegate()` / `delegateCapture()` disposer** whenever the registration's scope is shorter than the page. Both helpers return `() => void`; the listener closure pins `rootEl`, `handler`, and everything the handler closes over (stores, signals, app state). Discarding the disposer on a transient root (modal, route view, mount swap, dynamic widget) leaks the listener AND the app graph it captures; re-mount cycles stack listeners linearly. `mount()`'s own disposer does NOT remove delegates for you. Safe to discard only when the registration is truly page-lifetime (root is `document.body` or equivalent, attached once at startup, never torn down).
|
|
112
|
-
6. **One `mount()` per root.** Don't nest. Compose with plain functions that return JSX.
|
|
145
|
+
6. **One `mount()` per root.** Don't nest. Compose with plain functions that return JSX. One exception: a modal `<dialog>` of your own that anchors kerf `popover()` / `tooltip()` surfaces must contain `<div data-kerf-overlay-host data-morph-skip></div>` — kerf renders those surfaces into it (inside the modal, so they are not inert) and that slot is the one allowed nested-mount boundary. Dialogs `kerfjs/overlay` opens get a slot automatically.
|
|
113
146
|
7. **No `<MyComponent />` semantics with hooks.** Components are plain functions returning JSX. State lives in module-scope signals or stores, never in component closures.
|
|
114
|
-
8. **Values bind, structure re-renders.** For a value hole, pass the signal/computed ITSELF (`<span>{count}</span>`, `class={sig}`) — kerf updates that one node directly, no render re-run. Read `.value` only when the JSX
|
|
147
|
+
8. **Values bind, structure re-renders.** For a value hole, pass the signal/computed ITSELF (`<span>{count}</span>`, `class={sig}`) — kerf updates that one node directly, no render re-run. Read `.value` only when the JSX _structure_ depends on the signal — and then the read must happen INSIDE the render function to be tracked: `const x = count.value; mount(el, () => <span>{x}</span>)` will NOT re-render. Bind a STABLE signal/computed instance per hole (a `computed` that switches internally), never `class={cond ? sigA : sigB}` — switching instances can go silently stale (`enableWarnings({ staleBinding: true })` (or `KERF_DEV_WARN_STALE_BINDING=1` under Node) detects it). Endpoint: a render reading NO `.value` runs exactly once — a fully bound mount never re-renders; `enableWarnings({ valueOnlyRerender: true })` (or `KERF_DEV_WARN_VALUE_ONLY_RERENDER=1` under Node) flags re-renders that could have been bindings.
|
|
115
148
|
9. **Store actions receive `(set, get)`, not `(state)`.** `set(next)` replaces state; mutating `get()` does nothing.
|
|
116
149
|
10. **Use `data-action` attributes, not inline `onClick`.** Inline handlers are NOT supported by the JSX → string runtime; delegate from the root instead.
|
|
117
150
|
11. **`arraySignal` is opt-in for long keyed lists** where most updates are pointwise (single-row edits, append-to-end). For short lists / filter+sort pipelines, plain `signal` + `each(items.value, ...)` is simpler and equally fast.
|
|
@@ -124,22 +157,26 @@ if (import.meta.env.DEV) await import('kerfjs/dev');
|
|
|
124
157
|
When deciding which primitive to reach for, work down the axes:
|
|
125
158
|
|
|
126
159
|
**Events.**
|
|
160
|
+
|
|
127
161
|
- Originates inside the mount tree → `delegate(rootEl, type, sel, handler)`. Originates outside (window-level keyboard, online/offline, beforeunload) → native `window.addEventListener` at module top-level.
|
|
128
162
|
- Gesture that needs to follow an element after press (drag, draw, resize) → at the start event, `el.setPointerCapture(e.pointerId)`. Subsequent `pointermove` / `pointerup` redirect to the captured element and `delegate(rootEl, 'pointermove', '[data-card]', …)` still picks them up. Don't reach for `window.addEventListener` for in-mount-tree gestures.
|
|
129
163
|
- Well-known non-bubbler (`focus`, `blur`, `scroll`, `load`, `error`, `mouseenter`, `mouseleave`) → still `delegate()`; it auto-promotes to capture. Custom non-bubblers or capture-phase interception → `delegateCapture()` (also `closest()`-matched by default). Need strict element-match? Add `{ match: 'direct' }` on either helper.
|
|
130
164
|
|
|
131
165
|
**Lists.**
|
|
166
|
+
|
|
132
167
|
- Items change across renders (todos, chat messages, table rows) → `each(items, render)`.
|
|
133
168
|
- Static structural enumeration whose row render reads signals → `STATIC.map(item => <jsx/>)`. Inner `each(item.children, …)` still gets keyed reconcile.
|
|
134
169
|
- Long list with point-wise mutations → `arraySignal` + `each(arraySig, render)` for O(patches) updates.
|
|
135
170
|
|
|
136
171
|
**Side effects / imperative DOM.**
|
|
172
|
+
|
|
137
173
|
- Library-owned subtree survives across renders → `data-morph-skip` on host.
|
|
138
174
|
- Host attributes morph but subtree preserved → `data-morph-skip-children`.
|
|
139
175
|
- Imperatively-injected element survives the trailing-removal pass → `data-morph-preserve`.
|
|
140
176
|
- Focused input / contenteditable caret survives re-renders → automatic; no opt-in.
|
|
141
177
|
|
|
142
178
|
**Raw HTML.**
|
|
179
|
+
|
|
143
180
|
- User-controlled HTML → sanitize first (DOMPurify) then `raw(sanitized)`.
|
|
144
181
|
- Author-controlled trusted HTML → `raw(html)` directly.
|
|
145
182
|
- Dangerous URLs (`javascript:`/`vbscript:`/script-executing `data:`) on `href`/`src`/`xlink:href`/`formaction`/`action`/`data` are dropped — kerf THROWS in dev, WARNS + drops in prod. Sanitize user URLs upstream; wrap an intentional trusted one in `raw(url)` to bypass the screen in both modes. The `javascript:` no-op placeholders (`javascript:void(0)`, `javascript:;`, …) are allowed — they're the placeholder-link idiom, matched whole so nothing can ride along.
|
|
@@ -152,20 +189,27 @@ When deciding which primitive to reach for, work down the axes:
|
|
|
152
189
|
// updates that one node directly with no render re-run; read `.value` only
|
|
153
190
|
// when the JSX STRUCTURE depends on the signal (conditionals, list shape).
|
|
154
191
|
const count = signal(0);
|
|
155
|
-
const ACTIONS = { inc: attr(
|
|
192
|
+
const ACTIONS = { inc: attr("data-action", "inc") } as const satisfies Record<
|
|
193
|
+
string,
|
|
194
|
+
AttrSpec<"data-action">
|
|
195
|
+
>;
|
|
156
196
|
|
|
157
|
-
mount(document.getElementById(
|
|
197
|
+
mount(document.getElementById("app")!, () => (
|
|
158
198
|
<div>
|
|
159
199
|
<button {...ACTIONS.inc.attrs}>+</button>
|
|
160
200
|
<span>{count}</span>
|
|
161
201
|
</div>
|
|
162
202
|
));
|
|
163
|
-
delegate(rootEl,
|
|
203
|
+
delegate(rootEl, "click", ACTIONS.inc.selector, () => {
|
|
204
|
+
count.value += 1;
|
|
205
|
+
});
|
|
164
206
|
|
|
165
207
|
// Keyed list with per-item memoization
|
|
166
208
|
mount(listEl, () => (
|
|
167
209
|
<ul>
|
|
168
|
-
{each(rows.value, (row) =>
|
|
210
|
+
{each(rows.value, (row) => (
|
|
211
|
+
<li data-key={row.id}>{row.label}</li>
|
|
212
|
+
))}
|
|
169
213
|
</ul>
|
|
170
214
|
));
|
|
171
215
|
|
|
@@ -173,22 +217,28 @@ mount(listEl, () => (
|
|
|
173
217
|
const cart = defineStore({
|
|
174
218
|
initial: () => ({ items: [] as string[] }),
|
|
175
219
|
actions: (set, get) => ({
|
|
176
|
-
add:
|
|
177
|
-
clear: ()
|
|
220
|
+
add: (id: string) => set({ items: [...get().items, id] }),
|
|
221
|
+
clear: () => set({ items: [] }),
|
|
178
222
|
}),
|
|
179
223
|
});
|
|
180
224
|
|
|
181
225
|
// One-shot reconcile against existing DOM (no signals)
|
|
182
|
-
|
|
226
|
+
// the template describes liveCard's CHILDREN; liveCard's own attributes are untouched
|
|
227
|
+
morph(liveCard, '<h2 class="card-title">…</h2><p>…</p>');
|
|
183
228
|
|
|
184
229
|
// No build step (CDN / importmap): the html tagged template instead of JSX.
|
|
185
230
|
// Same runtime semantics as JSX; write real HTML attribute names; a hole must
|
|
186
231
|
// be a text position or a COMPLETE attribute value (partial values throw).
|
|
187
|
-
import { html } from
|
|
188
|
-
mount(
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
232
|
+
import { html } from "kerfjs/html";
|
|
233
|
+
mount(
|
|
234
|
+
rootEl,
|
|
235
|
+
() => html`
|
|
236
|
+
<div class="${cls}">Count: ${count}</div>
|
|
237
|
+
<ul>
|
|
238
|
+
${each(rows.value, (row) => html`<li data-key="${row.id}">${row.label}</li>`)}
|
|
239
|
+
</ul>
|
|
240
|
+
`,
|
|
241
|
+
);
|
|
192
242
|
|
|
193
243
|
// Fine-grained binding (opt-in): pass the signal/computed ITSELF into a hole
|
|
194
244
|
// so a change updates ONLY that node (no render re-run, no reconcile). For a
|
|
@@ -197,11 +247,20 @@ mount(rootEl, () => html`
|
|
|
197
247
|
const selectedId = signal<number | null>(null);
|
|
198
248
|
mount(listEl, () => (
|
|
199
249
|
<ul>
|
|
200
|
-
{each(
|
|
201
|
-
|
|
202
|
-
|
|
250
|
+
{each(
|
|
251
|
+
rows.value,
|
|
252
|
+
(row) => (
|
|
253
|
+
<li class={computed(() => (row.id === selectedId.value ? "sel" : ""))}>
|
|
254
|
+
{row.label}
|
|
255
|
+
</li>
|
|
256
|
+
),
|
|
257
|
+
(row) => row.id,
|
|
258
|
+
)}
|
|
203
259
|
</ul>
|
|
204
260
|
));
|
|
261
|
+
// Large list: `const isSelected = selector(selectedId)` (from "kerfjs") and
|
|
262
|
+
// `computed(() => (isSelected(row.id).value ? "sel" : ""))` — one subscription
|
|
263
|
+
// to selectedId instead of one per row, so a selection flip is O(1).
|
|
205
264
|
```
|
|
206
265
|
|
|
207
266
|
## Common errors → fixes
|
|
@@ -215,13 +274,13 @@ mount(listEl, () => (
|
|
|
215
274
|
- SVG renders as broken / namespaceless markup → use `mount` (HTML path) or `toElement` (SVG-aware), not `innerHTML`.
|
|
216
275
|
- Library widget destroyed on every render → wrap host in `data-morph-skip`; mount the library imperatively after first render.
|
|
217
276
|
- `each(): row render at index N produced K top-level elements` → wrap multiple roots in one parent.
|
|
218
|
-
- Drag/drop / state change has no visible effect, only stuff
|
|
219
|
-
- Row-enter CSS animation no longer replays when only a row's
|
|
277
|
+
- Drag/drop / state change has no visible effect, only stuff _outside_ `each()` updates → you used `each(STATIC_ARRAY, …)` whose row render reads signals. Replace the outer with `STATIC_ARRAY.map(...)`; keep inner `each()` for the dynamic sub-list. See Hard Rule 14.
|
|
278
|
+
- Row-enter CSS animation no longer replays when only a row's _content_ changed (kerf ≥ 0.15.0) → 0.15.0+ morphs a same-identity, same-position row _in place_ instead of recreating its node, so a mount-keyed `@keyframes` never re-triggers on a content-only update (≤ 0.14.x recreated the node, so it fired; the intentional flip side is that focus, scroll, IME, and in-progress transitions now survive). Key the animation on a state-class toggle, not element creation; to force a remount, churn the row's identity (new object ref / `data-key`).
|
|
220
279
|
- Want a hot spot to update without re-running the whole render → fine-grained binding: pass the signal/`computed` ITSELF into the attr/text hole (`class={computed(() => …)}`), not `.value`. Use `computed()` not a bare `() => …` (memoization keeps a shared-signal flip to ~O(changed nodes)). Opt-in per hole. Limit: a bound hole depending on the row's OWN mutated data goes stale on a granular in-place update — use plain interpolation there.
|
|
221
|
-
-
|
|
280
|
+
- ` html` ``: partial attribute values are not supported → in `kerfjs/html` templates a hole must be the COMPLETE attribute value. Replace `class="a ${b}"` with a pre-built string (`` class="${`a ${b}`}" ``) or, for a bound attribute, `class="${computed(() => `a ${b.value}`)}"`.
|
|
222
281
|
- An `each()` list's rows lose focus / scroll / typing state when an unrelated conditional list above them appears or disappears (kerf warns in dev) → lists without a key are identified by position among the render's `each()` calls, so adding/removing one above shifts this list's identity and kerf rebuilds it. Give the lists stable keys: `each(items, render, { key: 'results' })`; keying just the conditional list is usually enough.
|
|
223
282
|
- Keyed `each()` list suddenly renders zero rows — only its `<!--kf-list:N-->` marker — with no errors, and it never recovers (kerfjs ≤ 2.0.1) → a conditionally-rendered sibling BEFORE the list (possibly higher in the tree, e.g. an error banner) was removed that render; older kerfjs rebuilt the shifted list container from the template, permanently detaching the list's internal binding. Upgrade kerfjs (fixed after 2.0.1 — the morph now moves the shifted container up in place, keeping node identity). On older versions, keep the structure before the list stable: wrap the conditional in an always-present container (`<div class="banners">{cond ? <div/> : ''}</div>`).
|
|
224
|
-
- A numbered / zebra-striped / "N of M" `each()` list shows the wrong number on rows that MOVED (reorder, or non-tail insert/remove), while unmoved rows look right → the render fn's `index` argument is NOT part of the memo key (only item identity + `cacheKey` + content version are), so a row that keeps identity but changes position keeps HTML rendered at its old index. Fold the index into the memo key: `each(items, (it, i) => …, { cacheKey: (_, i) => i })` (add `key` if used). Opt-in dev warn: `KERF_DEV_WARN_STALE_INDEX=1
|
|
283
|
+
- A numbered / zebra-striped / "N of M" `each()` list shows the wrong number on rows that MOVED (reorder, or non-tail insert/remove), while unmoved rows look right → the render fn's `index` argument is NOT part of the memo key (only item identity + `cacheKey` + content version are), so a row that keeps identity but changes position keeps HTML rendered at its old index. Fold the index into the memo key: `each(items, (it, i) => …, { cacheKey: (_, i) => i })` (add `key` if used). Opt-in dev warn: `enableWarnings({ staleIndex: true })` (or `KERF_DEV_WARN_STALE_INDEX=1` under Node).
|
|
225
284
|
|
|
226
285
|
## Server / SSR
|
|
227
286
|
|
package/ai/manifest.json
CHANGED
|
@@ -1,13 +1,13 @@
|
|
|
1
1
|
{
|
|
2
|
-
"kerfjsVersion": "5.0.0-beta.
|
|
2
|
+
"kerfjsVersion": "5.0.0-beta.130",
|
|
3
3
|
"files": [
|
|
4
4
|
{
|
|
5
5
|
"name": "skill",
|
|
6
6
|
"source": "kerf.claude-skill.md",
|
|
7
7
|
"bundle": "ai/skill.md",
|
|
8
8
|
"dest": ".claude/skills/kerf-app/SKILL.md",
|
|
9
|
-
"version": "1.
|
|
10
|
-
"sha256": "
|
|
9
|
+
"version": "1.31.0",
|
|
10
|
+
"sha256": "9880f36aa1994da1b02c35fed72079d2484c0f384f68e22ae47d0634b233a1cb",
|
|
11
11
|
"history": {
|
|
12
12
|
"1.0.0": "bef982cb743fd4c73e666ee5cf774112e57c93ebb13b24bbacbf08577db0930a",
|
|
13
13
|
"1.1.0": "f2aadb21e33dd389028951ae1ecbd9f8ba68648b3c5beba43fb4dfa2ab29f195",
|
|
@@ -36,7 +36,28 @@
|
|
|
36
36
|
"1.19.0": "bbbe87446cc4e1be250d27152adfd385431f4498cde320534f65f10f853ab7f9",
|
|
37
37
|
"1.20.0": "aa88ccdbf969624bbc6cefadba76ada1f090fae436597a7bab564e24c467287f",
|
|
38
38
|
"1.21.0": "265b747eeb9c3d445c60d66a1109eec42705075b7cd154d107bd79d543c1e7e5",
|
|
39
|
-
"1.22.0": "
|
|
39
|
+
"1.22.0": "dc99b0ca5e911be11cbfa2ae515c0e161a414a5185895069535c41ba56664e70",
|
|
40
|
+
"1.23.0": "28b82b4d31b98814c8fbbe1cb0bcf716192deb494c020b9af41a30830e6a0007",
|
|
41
|
+
"1.23.1": "e21d7db1097ad95c11af9248ad17d514716bebc5646becf57d19a7598d6e382c",
|
|
42
|
+
"1.24.0": "f74616ec20120fa97ec2ff7e92971f5721ee8dcb0b5b7da2dd2604bb87002b69",
|
|
43
|
+
"1.25.0": "bc2622cb12b382118e44aa50d1afb058252e0caf85b7c0ced4433bc0ca76f7c1",
|
|
44
|
+
"1.26.0": "64a86a36399d12e5803a050c116d32d8762608d91ec9222670592ff471bc64b8",
|
|
45
|
+
"1.27.0": "7cc6a566cbe08023079731b98166e3c5e49160a8844358f928acf3ee0654092c",
|
|
46
|
+
"1.28.0": "95a803e82a234dda363f468511bf64247c89798c1af8a1c62d082b40627f41aa",
|
|
47
|
+
"1.29.0": "1816494efdc7e3b15d9c5213988477f68f82c5c2a2e4a685956500845ae5cc90",
|
|
48
|
+
"1.30.0": "2e78139920bbb6e6fd1e396cd6ed3edf772cfdbd2f0eb84d0c3077f9cd2035c6",
|
|
49
|
+
"1.31.0": "9880f36aa1994da1b02c35fed72079d2484c0f384f68e22ae47d0634b233a1cb"
|
|
50
|
+
}
|
|
51
|
+
},
|
|
52
|
+
{
|
|
53
|
+
"name": "ui-skill",
|
|
54
|
+
"source": "kerf.ui-skill.md",
|
|
55
|
+
"bundle": "ai/ui-skill.md",
|
|
56
|
+
"dest": ".claude/skills/kerf-ui/SKILL.md",
|
|
57
|
+
"version": "1.0.0",
|
|
58
|
+
"sha256": "ee6e0e1d4028c37c3cc868ec12459e23cfa42c9dcaac791011c656984ae19310",
|
|
59
|
+
"history": {
|
|
60
|
+
"1.0.0": "ee6e0e1d4028c37c3cc868ec12459e23cfa42c9dcaac791011c656984ae19310"
|
|
40
61
|
}
|
|
41
62
|
},
|
|
42
63
|
{
|
|
@@ -44,8 +65,8 @@
|
|
|
44
65
|
"source": "kerf.cursorrules",
|
|
45
66
|
"bundle": "ai/cursorrules",
|
|
46
67
|
"dest": ".cursorrules",
|
|
47
|
-
"version": "1.
|
|
48
|
-
"sha256": "
|
|
68
|
+
"version": "1.27.0",
|
|
69
|
+
"sha256": "e8d8a56ed88ee427c2edc9ddfb4358780e19ea70c0feeae4e052d8b7c4520aae",
|
|
49
70
|
"history": {
|
|
50
71
|
"1.0.0": "98f7faff2b7585ef9cc511add42ea5d9bf0cbae8307b066af090e9281136d2ab",
|
|
51
72
|
"1.1.0": "a2ec8c221dc694c98b81009cd2d99f9159a45fda94585de2f54471b227099eda",
|
|
@@ -72,7 +93,15 @@
|
|
|
72
93
|
"1.17.0": "6ad51fb0eec468f584346d1d7b4d1c2eca2cb52b04891b38ba44e93b57eb9e1c",
|
|
73
94
|
"1.18.0": "de3eea1bc181da629694d19a0817d252a868e4704437fbdd9e923856b8a0890a",
|
|
74
95
|
"1.19.0": "c5b91e449f6feccaa36a04cb7f8550d3e414eb2795ea6c5dccdf6071206b3261",
|
|
75
|
-
"1.20.0": "
|
|
96
|
+
"1.20.0": "5e7b8d8ddc41f60220961417c9ae01c193fae045378a10a3e9c96a0e3cf10a03",
|
|
97
|
+
"1.21.0": "a1b663b44650b1a04f89c60b26b002322fc6789650291477e14e13329c3ce25f",
|
|
98
|
+
"1.21.1": "9b3eb825a7bec05bb6f0138f77b45fadf896b83020178c34c5a2f531c38f4dee",
|
|
99
|
+
"1.22.0": "3515c663e908b2d6dc9a2a9cf42f2a5bf9a5b3a10c79d43e30cc8427e2ce209d",
|
|
100
|
+
"1.23.0": "dad6f677c85bf01760da6694afb7ead1439f0e1f0298ba8dac65de44ba031848",
|
|
101
|
+
"1.24.0": "9578b5141b417b10560a426086c0f8dad3bd6a302f2856bea4808be7d02ef0d3",
|
|
102
|
+
"1.25.0": "c52120502cc76fa5c6588a551b1d7f8097e2f6cd8a496d30a8bad0e103ea37db",
|
|
103
|
+
"1.26.0": "a583bad7217181229f7bc7047a472f87867738d9514f926dc9805b7e2443d8c2",
|
|
104
|
+
"1.27.0": "e8d8a56ed88ee427c2edc9ddfb4358780e19ea70c0feeae4e052d8b7c4520aae"
|
|
76
105
|
}
|
|
77
106
|
}
|
|
78
107
|
]
|