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/README.md
CHANGED
|
@@ -12,14 +12,14 @@
|
|
|
12
12
|
|
|
13
13
|
<p align="center">
|
|
14
14
|
<a href="https://www.npmjs.com/package/kerfjs"><img src="https://img.shields.io/npm/v/kerfjs.svg" alt="npm version" /></a>
|
|
15
|
-
<img src="https://img.shields.io/badge/min%2Bgzip-~
|
|
15
|
+
<img src="https://img.shields.io/badge/min%2Bgzip-~15%20KB-brightgreen.svg" alt="~15 KB minified and gzipped" />
|
|
16
16
|
<img src="https://img.shields.io/npm/l/kerfjs.svg" alt="MIT license" />
|
|
17
17
|
<img src="https://img.shields.io/badge/types-included-3178c6.svg" alt="TypeScript types included" />
|
|
18
18
|
</p>
|
|
19
19
|
|
|
20
20
|
---
|
|
21
21
|
|
|
22
|
-
> ~
|
|
22
|
+
> ~15 KB. No virtual DOM. No compiler. No magic.
|
|
23
23
|
> Reactive UI that touches only the bytes that changed.
|
|
24
24
|
|
|
25
25
|
```ts
|
|
@@ -31,14 +31,17 @@ const app = document.getElementById('app')!;
|
|
|
31
31
|
mount(app, () => (
|
|
32
32
|
<div>
|
|
33
33
|
<button data-action="inc">+</button>
|
|
34
|
-
<span>{count
|
|
34
|
+
<span>{count}</span>
|
|
35
35
|
</div>
|
|
36
36
|
));
|
|
37
37
|
|
|
38
38
|
delegate(app, 'click', '[data-action="inc"]', () => count.value++);
|
|
39
39
|
```
|
|
40
40
|
|
|
41
|
-
That's it. Your JSX renders to HTML strings,
|
|
41
|
+
That's it. Your JSX renders to HTML strings, and handing the signal itself to
|
|
42
|
+
the text hole binds that one node directly. Structural reads still re-run the
|
|
43
|
+
render, where kerf's native diff applies the minimum DOM mutations needed to
|
|
44
|
+
make the live tree match.
|
|
42
45
|
|
|
43
46
|
Here's the whole development loop — write a component, run the dev server, click around, edit, watch the browser pick it up:
|
|
44
47
|
|
|
@@ -51,25 +54,47 @@ Here's the whole development loop — write a component, run the dev server, cli
|
|
|
51
54
|
npm install kerfjs
|
|
52
55
|
```
|
|
53
56
|
|
|
57
|
+
Kerf runs in modern browsers (ES2022). The published package, including the
|
|
58
|
+
`kerfjs setup` CLI and server-side `toString()` rendering, needs Node.js 18 or
|
|
59
|
+
newer (`engines.node`); contributing to this repository (building, testing,
|
|
60
|
+
the documentation site) needs Node.js 22.12+.
|
|
61
|
+
|
|
62
|
+
For an existing project, install the AI guidance, strict TypeScript/ESLint
|
|
63
|
+
feedback, and package scripts with a reviewed dry run:
|
|
64
|
+
|
|
65
|
+
```bash
|
|
66
|
+
npx kerfjs setup # inspect a value-level plan
|
|
67
|
+
npx kerfjs setup --write --yes # apply it
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
The command detects core versus `@kerfjs/ui`, supports deterministic npm,
|
|
71
|
+
pnpm, and Yarn workspace selection plus manager-correct offline installs, and
|
|
72
|
+
never adds UI to a core-only project. See
|
|
73
|
+
[`docs/24-ai-first-setup.md`](./docs/24-ai-first-setup.md).
|
|
74
|
+
|
|
54
75
|
```jsonc
|
|
55
76
|
// tsconfig.json — point JSX at kerf
|
|
56
77
|
{ "compilerOptions": { "jsx": "react-jsx", "jsxImportSource": "kerfjs" } }
|
|
57
78
|
```
|
|
58
79
|
|
|
59
80
|
Write plain `.tsx` and build with your existing esbuild / Vite / tsup — no extra plugin. New here? Read the [5-minute orientation](https://github.com/brianwestphal/kerf/blob/main/docs/orientation.md), or open a [complete example](https://brianwestphal.github.io/kerf/examples/complete/).
|
|
81
|
+
|
|
60
82
|
## Why Kerf
|
|
61
83
|
|
|
62
|
-
1. **~
|
|
84
|
+
1. **~15 KB in the browser.** ~15 KB minified + gzipped including `@preact/signals-core` (~16 KB with `arraySignal`). The optional setup CLI has its own npm dependencies; they stay out of the browser bundle. No virtual DOM, no scheduler, no concurrent-mode machinery. On the official [krausest benchmark](https://krausest.github.io/js-framework-benchmark/current.html) kerf sits in the same cluster as Vue, Lit, and vanjs; Solid's compiler leads the update-path benchmarks, which kerf doesn't try to match by design — no compiler.
|
|
63
85
|
|
|
64
|
-
2. **No virtual DOM, no compiler.** JSX → HTML strings → native diff. DevTools shows the real DOM because it
|
|
86
|
+
2. **No virtual DOM, no compiler.** JSX → HTML strings → native diff. DevTools shows the real DOM because it _is_ the DOM.
|
|
65
87
|
|
|
66
|
-
3. **Values bind, structure re-renders.** Hand a signal
|
|
88
|
+
3. **Values bind, structure re-renders.** Hand a signal _itself_ into a JSX hole — `class={selectedId}` — and kerf binds that one node: on change, only that attribute updates, with no render re-run and no list reconcile. Moving selection between rows in a 10,000-row table touches at most the old and new row classes. ([more →](#fine-grained-updates-bind-a-signal-into-a-hole))
|
|
67
89
|
|
|
68
90
|
4. **Focus, selection, and listeners survive re-renders — even mid-list.** The reconciler morphs instead of rebuilding, so caret position, IME composition, scroll, and delegated listeners survive every update; keyed rows are patched in place rather than recreated.
|
|
69
91
|
|
|
70
|
-
5. **
|
|
92
|
+
5. **A first-party UI layer when you want one.** `@kerfjs/ui` adds accessible components, responsive application layouts, typed CSS values, and explicit wiring helpers without changing kerf's stateless component model. It is separately installable and tree-shakeable, so the core stays the core. ([tour →](#first-party-ui-separately-installable))
|
|
93
|
+
|
|
94
|
+
6. **Safe by default.** Text and attributes are HTML-escaped automatically, URL attributes are scheme-screened (`javascript:` dropped), and inline `on*` handlers are rejected outright — so untrusted data stays inert. `raw()` is the explicit, auditable opt-out.
|
|
95
|
+
|
|
96
|
+
**Plus, nothing you don't ask for:** JSX typed against the HTML standard (not React's props) · a small public API with no hooks, lifecycle, or per-instance state · tree-shakeable companion subpaths (`router`, `list`, `overlay`, `async`, …) that stay out of the core until imported · an [ESLint plugin](https://brianwestphal.github.io/kerf/docs/eslint-plugin/) + opt-in dev warnings + `create-kerf-component` scaffold · plain TS/JSX/ESM that drops into esbuild / Vite / tsup — or **no** build at all via the `html` tagged template.
|
|
71
97
|
|
|
72
|
-
**Plus, nothing you don't ask for:** JSX typed against the HTML standard (not React's props) · a ~18-export API with no hooks, lifecycle, or per-instance state · **nine** tree-shakeable companion subpaths (`router`, `list`, `overlay`, `async`, …) that stay out of the core until imported · an [ESLint plugin](https://brianwestphal.github.io/kerf/docs/eslint-plugin/) + opt-in dev warnings + `create-kerf-component` scaffold · plain TS/JSX/ESM that drops into esbuild / Vite / tsup — or **no** build at all via the `html` tagged template.
|
|
73
98
|
## When to use Kerf
|
|
74
99
|
|
|
75
100
|
- **Hybrid desktop apps (Tauri / Electron)** — small bundle, predictable diff, debuggable runtime; ideal for the embedded webview.
|
|
@@ -82,9 +107,9 @@ Write plain `.tsx` and build with your existing esbuild / Vite / tsup — no ext
|
|
|
82
107
|
### When to reach for something else
|
|
83
108
|
|
|
84
109
|
- Need a full ecosystem (router + forms + data + SSR streaming) → **Next.js / Remix / SolidStart**.
|
|
85
|
-
- Building a deeply
|
|
110
|
+
- Building a deeply componentized design-system app → **React / Solid / Svelte**.
|
|
86
111
|
- Need React Native / cross-platform mobile → **React** (Kerf + Tauri/Electron also covers many of these cases).
|
|
87
|
-
- Building a static site → **Astro** (we use it for
|
|
112
|
+
- Building a static site → **Astro** (we use it for _this_ project's site).
|
|
88
113
|
- Already invested in a framework where switching cost outweighs the bundle size gain.
|
|
89
114
|
|
|
90
115
|
## Quick tour
|
|
@@ -144,7 +169,7 @@ delegate(root, 'click', REMOVE.selector, (_e, btn) => { /* … */ }); // in dele
|
|
|
144
169
|
|
|
145
170
|
### Fine-grained updates: bind a signal into a hole
|
|
146
171
|
|
|
147
|
-
Inside a `mount()`, hand a signal
|
|
172
|
+
Inside a `mount()`, hand a signal _itself_ (not its `.value`) into an attribute or text position and kerf wires that hole straight to the signal — the render function never re-runs and the list reconciler never walks:
|
|
148
173
|
|
|
149
174
|
```ts
|
|
150
175
|
const status = signal('idle');
|
|
@@ -160,7 +185,7 @@ status.value = 'saving'; // updates the class + the text node directly — n
|
|
|
160
185
|
|
|
161
186
|
The headline use is external state driving a hot spot: a `selectedId` moving between rows inside a 10,000-row `each()` list updates at most the old and new row class attributes, with no reconcile. Works in static content and inside `each()` rows (a row's binding is torn down with the row); outside a `mount()` (SSR / `SafeHtml.toString()`) a bound signal just snapshots its current value.
|
|
162
187
|
|
|
163
|
-
This is kerf's guiding idiom —
|
|
188
|
+
This is kerf's guiding idiom — _values bind, structure re-renders_: pass the signal itself wherever a hole is just a value, and read `.value` in the render function only where the JSX structure depends on it. A render that reads no `.value` runs exactly once; from then on every update is a direct write to the node it concerns. See [`docs/2-reactivity.md`](./docs/2-reactivity.md) §2.9.
|
|
164
189
|
|
|
165
190
|
### Long keyed lists: `arraySignal`
|
|
166
191
|
|
|
@@ -187,14 +212,15 @@ The class lives in its own subpath so apps that don't need it shed ~1 KB. Reads
|
|
|
187
212
|
`mount()` wraps `effect()` so the render re-runs on signal changes. Sometimes you have a freshly-built template and an already-populated element and you just want to reconcile them once — no subscription, no re-render loop. That's `morph`:
|
|
188
213
|
|
|
189
214
|
```ts
|
|
190
|
-
import { morph, raw } from
|
|
215
|
+
import { morph, raw } from "kerfjs";
|
|
191
216
|
|
|
192
|
-
|
|
193
|
-
morph(liveCard,
|
|
194
|
-
morph(liveCard,
|
|
217
|
+
// `template` describes liveCard's CHILDREN; liveCard's own attributes are untouched
|
|
218
|
+
morph(liveCard, freshlyBuiltCardEl); // Element template: its child nodes are used
|
|
219
|
+
morph(liveCard, '<h2 class="card-title">…</h2><p>…</p>'); // raw HTML string
|
|
220
|
+
morph(liveCard, raw(htmlFromServer)); // SafeHtml
|
|
195
221
|
```
|
|
196
222
|
|
|
197
|
-
Same algorithm `mount()` uses internally — `data-morph-skip`, `data-morph-skip-children`, `data-morph-preserve`, focused-input value + selection preservation, the
|
|
223
|
+
Same algorithm `mount()` uses internally — `data-morph-skip`, `data-morph-skip-children`, `data-morph-preserve`, focused-input value + selection preservation, the user-agent-owned `open` rule (`<details>`, `<dialog>`, custom elements) all carry over. Only the live root's children are reconciled — the root's own attributes are never touched. Use it for SSR-fragment hydration, page-refresh diffs, third-party widget remounts. See [`docs/4-render.md`](./docs/4-render.md) §4.4.3.
|
|
198
224
|
|
|
199
225
|
### No build step at all: the `html` tagged template
|
|
200
226
|
|
|
@@ -202,22 +228,27 @@ Same algorithm `mount()` uses internally — `data-morph-skip`, `data-morph-skip
|
|
|
202
228
|
|
|
203
229
|
```html
|
|
204
230
|
<script type="module">
|
|
205
|
-
import { signal, mount, each } from
|
|
206
|
-
import { html } from
|
|
207
|
-
|
|
208
|
-
const items = signal([{ id: 1, label:
|
|
209
|
-
|
|
210
|
-
mount(
|
|
211
|
-
|
|
212
|
-
|
|
231
|
+
import { signal, mount, each } from "https://esm.sh/kerfjs@5";
|
|
232
|
+
import { html } from "https://esm.sh/kerfjs@5/html";
|
|
233
|
+
|
|
234
|
+
const items = signal([{ id: 1, label: "no build step" }]);
|
|
235
|
+
|
|
236
|
+
mount(
|
|
237
|
+
document.getElementById("app"),
|
|
238
|
+
() => html`
|
|
239
|
+
<ul>
|
|
240
|
+
${each(items.value, (i) => html`<li id="${i.id}">${i.label}</li>`)}
|
|
241
|
+
</ul>
|
|
242
|
+
`,
|
|
243
|
+
);
|
|
213
244
|
</script>
|
|
214
245
|
```
|
|
215
246
|
|
|
216
|
-
Nothing is self-hosted — `kerfjs` is on npm, so every ESM CDN (esm.sh, jsDelivr, unpkg) mirrors it automatically. esm.sh works with a direct import as shown; jsDelivr / unpkg want an importmap so the internal `@preact/signals-core` import resolves. Pin to a major (`@
|
|
247
|
+
Nothing is self-hosted — `kerfjs` is on npm, so every ESM CDN (esm.sh, jsDelivr, unpkg) mirrors it automatically. esm.sh works with a direct import as shown; jsDelivr / unpkg want an importmap so the internal `@preact/signals-core` import resolves. Pin to a major (`@5`, as shown) rather than floating on `latest`, or an exact version (`@5.0.0`) for full reproducibility. Attribute names are written verbatim (`class`, not `className`), and holes are only legal in text positions or as a complete attribute value — anything ambiguous throws with an actionable message. See [`docs/6-jsx-runtime.md`](./docs/6-jsx-runtime.md) §6.11 (§6.11.1 for the full CDN / importmap recipes) — or the [live-poll example](https://brianwestphal.github.io/kerf/examples/complete/live-poll/), a complete app served exactly as authored: no bundler ever touches it.
|
|
217
248
|
|
|
218
249
|
### Batteries when you need them: the companion subpaths
|
|
219
250
|
|
|
220
|
-
The core stays tiny because the patterns every real app rebuilds live in optional, tree-shakeable subpaths — a modal you'd otherwise hand-roll (`kerfjs/overlay`), an async-state container with the stale-response race already solved (`kerfjs/async`), a debounce that composes inside the reactive graph (`kerfjs/timing`),
|
|
251
|
+
The core stays tiny because the patterns every real app rebuilds live in optional, tree-shakeable subpaths — a modal you'd otherwise hand-roll (`kerfjs/overlay`), an async-state container with the stale-response race already solved (`kerfjs/async`), a debounce that composes inside the reactive graph (`kerfjs/timing`), and disposer groups with or without a DOM owner (`kerfjs/scope`). The largest is `kerfjs/list` — a keyed list that mounts each row individually (so a signal one row reads updates just that row) and virtualizes a long viewport, with fixed, app-declared, or measured row heights:
|
|
221
252
|
|
|
222
253
|
```ts
|
|
223
254
|
import { bindList, observeRowHeights } from 'kerfjs/list';
|
|
@@ -238,7 +269,7 @@ const list = bindList(scrollEl, messages, {
|
|
|
238
269
|
observeRowHeights(list); // one ResizeObserver → kerf anchor-corrects scroll
|
|
239
270
|
```
|
|
240
271
|
|
|
241
|
-
And a whole client-side router in one call — `kerfjs/router`, the "postcard router." A route table, a keyed `outlet()`, and automatic `<a href>` interception; the
|
|
272
|
+
And a whole client-side router in one call — `kerfjs/router`, the "postcard router." A route table, a keyed `outlet()`, and automatic `<a href>` interception; the _core_ stays router-free (this is opt-in):
|
|
242
273
|
|
|
243
274
|
```ts
|
|
244
275
|
import { createRouter } from 'kerfjs/router';
|
|
@@ -258,13 +289,45 @@ mount(app, () => <div><nav>{/* <a href> links, auto-intercepted */}</nav>{router
|
|
|
258
289
|
|
|
259
290
|
Each subpath adds nothing to the main barrel until it's imported. See [`docs/8-api-reference.md`](./docs/8-api-reference.md) for the full list (`list`, `router`, `overlay`, `scope`, `async`, `timing`, `remount`, `attach`, `actions`).
|
|
260
291
|
|
|
292
|
+
### First-party UI, separately installable
|
|
293
|
+
|
|
294
|
+
`@kerfjs/ui` is the optional component layer for applications that want a
|
|
295
|
+
coherent interface vocabulary without switching frameworks. Components return
|
|
296
|
+
Kerf `SafeHtml`; the application still owns state and wires behavior explicitly.
|
|
297
|
+
Component subpaths pull in only their reachable CSS, while responsive app
|
|
298
|
+
layouts, typed CSS-value builders, Web Awesome adapters, and the checked
|
|
299
|
+
component catalog stay opt-in.
|
|
300
|
+
|
|
301
|
+
```bash
|
|
302
|
+
npm install kerfjs @kerfjs/ui
|
|
303
|
+
```
|
|
304
|
+
|
|
305
|
+
```tsx
|
|
306
|
+
import { mount } from "kerfjs";
|
|
307
|
+
import { ListItem } from "@kerfjs/ui/list-item";
|
|
308
|
+
import { Toolbar } from "@kerfjs/ui/toolbar";
|
|
309
|
+
import { ToolbarText } from "@kerfjs/ui/toolbar-text";
|
|
310
|
+
|
|
311
|
+
const root = document.getElementById("app")!;
|
|
312
|
+
|
|
313
|
+
mount(root, () => (
|
|
314
|
+
<>
|
|
315
|
+
<Toolbar label="Files" leading={<ToolbarText text="Workspace" />} />
|
|
316
|
+
<ListItem action="open-file" label="src/main.ts" selected />
|
|
317
|
+
</>
|
|
318
|
+
));
|
|
319
|
+
```
|
|
320
|
+
|
|
321
|
+
Start with the [component selection matrix](./ui/docs/component-selection.md),
|
|
322
|
+
or read the complete [`@kerfjs/ui` package guide](./ui/README.md).
|
|
323
|
+
|
|
261
324
|
## Optional tooling
|
|
262
325
|
|
|
263
326
|
Install and JSX setup are in [Quick start](#quick-start) above. These companion packages are opt-in.
|
|
264
327
|
|
|
265
328
|
### Optional: `eslint-plugin-kerfjs`
|
|
266
329
|
|
|
267
|
-
A companion ESLint plugin enforces kerf's hard rules at edit time.
|
|
330
|
+
A companion ESLint plugin enforces kerf's hard rules at edit time. Its eight core rules cover inline JSX event handlers, missing `data-key` in `each()`, nested `mount()`, delegate-disposer capture, `attr()` selector rename-safety, `raw()` XSS audit trails, JSX augmentation, and AI-assistant config hygiene. Six additional UI rules check component ownership, composition, CSS values, application preferences, wiring, and public boundaries when you opt into the UI preset. The plugin requires no TypeScript parser service.
|
|
268
331
|
|
|
269
332
|
```bash
|
|
270
333
|
npm install --save-dev eslint-plugin-kerfjs
|
|
@@ -272,15 +335,15 @@ npm install --save-dev eslint-plugin-kerfjs
|
|
|
272
335
|
|
|
273
336
|
```js
|
|
274
337
|
// eslint.config.js (flat config, ESLint v9+)
|
|
275
|
-
import kerfjs from
|
|
338
|
+
import kerfjs from "eslint-plugin-kerfjs";
|
|
276
339
|
export default [kerfjs.configs.recommended];
|
|
277
340
|
```
|
|
278
341
|
|
|
279
|
-
Full docs at [brianwestphal.github.io/kerf/docs/eslint-plugin/](https://brianwestphal.github.io/kerf/docs/eslint-plugin/) —
|
|
342
|
+
Full docs at [brianwestphal.github.io/kerf/docs/eslint-plugin/](https://brianwestphal.github.io/kerf/docs/eslint-plugin/) — flat config, per-rule examples, and the rationale for which violations get lint rules vs. dev-warns vs. strict TS.
|
|
280
343
|
|
|
281
344
|
### Optional: `create-kerf-component`
|
|
282
345
|
|
|
283
|
-
Building a reusable component package? Scaffold one that already follows kerf's hard packaging rules (kerfjs as a peer dependency and `external` in the build, ESM + `.d.ts`, `jsxImportSource: "kerfjs"`, subpath exports)
|
|
346
|
+
Building a reusable component package? Scaffold one that already follows kerf's hard packaging rules (kerfjs as a peer dependency and `external` in the build, ESM + `.d.ts`, `jsxImportSource: "kerfjs"`, subpath exports), includes an example component showing per-instance state via a factory and a `wire(root)` delegation disposer, and generates checked package-qualified AI component metadata from explicit author decisions:
|
|
284
347
|
|
|
285
348
|
```bash
|
|
286
349
|
npm create kerf-component@latest my-widgets
|
|
@@ -294,16 +357,17 @@ See [`docs/13-component-packages.md`](./docs/13-component-packages.md) for the f
|
|
|
294
357
|
- **Docs:** [`docs/`](./docs/) — overview · reactivity · stores · render · events · jsx · svg · [API reference](./docs/8-api-reference.md)
|
|
295
358
|
- **Migrating:** [coming from another framework?](https://brianwestphal.github.io/kerf/migrating/) — side-by-side TodoMVC translations + per-framework gotchas
|
|
296
359
|
- **AI guide:** [`docs/ai/usage-guide.md`](./docs/ai/usage-guide.md) — reference for AI tools fetching kerf docs (linked from `llms.txt`)
|
|
297
|
-
- **
|
|
298
|
-
- **
|
|
360
|
+
- **UI package:** [`@kerfjs/ui`](./ui/README.md) — accessible components, responsive app layouts, typed CSS values, Web Awesome adapters, and checked AI-facing component metadata
|
|
361
|
+
- **ESLint plugin:** [brianwestphal.github.io/kerf/docs/eslint-plugin/](https://brianwestphal.github.io/kerf/docs/eslint-plugin/) — `eslint-plugin-kerfjs`; eight core rules plus six opt-in UI rules at edit time (source: [`eslint-plugin/`](./eslint-plugin/))
|
|
362
|
+
- **Component scaffold:** `npm create kerf-component@latest <dir>` — `create-kerf-component`; generates a publishable component package with packaging rules plus deterministic, drift-checked AI metadata pre-wired (source: [`create-kerf-component/`](./create-kerf-component/))
|
|
299
363
|
- **Demo:** [live demo](https://brianwestphal.github.io/kerf/demo/) — nine sections exercising every primitive (counter, store-backed cart, focus survival, keyed list, morph-skip, SVG render, Tier-2 capture, `arraySignal` patches, fine-grained signal bindings)
|
|
300
364
|
- **Repo:** [github.com/brianwestphal/kerf](https://github.com/brianwestphal/kerf)
|
|
301
365
|
|
|
302
366
|
## Why "kerf"?
|
|
303
367
|
|
|
304
|
-
A
|
|
368
|
+
A _kerf_ is the narrow strip of material a saw blade removes when cutting — the smallest possible cut. The framework's job is the same: apply the smallest possible mutation to update your DOM.
|
|
305
369
|
|
|
306
|
-
(And yes, ~~kerformance~~ →
|
|
370
|
+
(And yes, ~~kerformance~~ → _performance_ jokes were written. They were also rejected.)
|
|
307
371
|
|
|
308
372
|
## Status
|
|
309
373
|
|