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/CHANGELOG.md
CHANGED
|
@@ -6,7 +6,3348 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
|
6
6
|
|
|
7
7
|
## [Unreleased]
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
### Added
|
|
10
|
+
|
|
11
|
+
- **RadioGroup preview tiles in the design templates and Sketch Library (KF-1M9SJA).** The `radio-group` SVG design templates gain a Preview Tiles variant, a selected and an unselected tile with a hint, and `Kerf-UI.sketch` gains its editable light and dark Symbols (328 Symbols for 115 variants). Existing Symbol, Text and Color Variable IDs are unchanged, so linked instances sync with their overrides.
|
|
12
|
+
|
|
13
|
+
### Fixed
|
|
14
|
+
|
|
15
|
+
- **The Kerf UI editor's project type checks are several times faster (KF-SNM61J).** Each analysis asked TypeScript for auto-import completions, which re-read the project's `package.json` about 1,300 times, and every request re-read every program file. The project type service now reads each manifest once per request, keeps file snapshots until a file's modification time changes, and skips completions where nothing shows them: formatting a draft (a new `suggest: false` analysis option, which the editor sends) and document validation. Warm CPU time per request fell from 0.3–1.6 s to 0.07–0.2 s for formatting and from 1.3–2.3 s to about 0.5 s for a two-parameter validation, so parameter dialogs no longer sit at "Checking type…" when several editors share one project server.
|
|
16
|
+
- **A DialogSurface reopened just as its exit motion ends stays open (KF-C0RV1G).** Browsers deliver a dialog's native `close` event as a later task. An `openDialog()` call that landed after the exit motion closed the dialog, but before that event arrived, left it closed, and the late event then cleared the reopened state (the Kerf UI editor's parameter dialog lost a row chosen mid-close this way). `openDialog()` now opens such a dialog afresh, and the superseded `close` event no longer reaches the application.
|
|
17
|
+
- **StateBanner accepts several action controls in the composition catalog (KF-8TF7Y8).** Its `action` already lays out one or more Buttons as a wrapping list, as the guidance says, but the catalog limited the zone to one child, so `kerf-ui-doctor` and the `kerfjs/ui-composition` lint rule reported `KUI-L203` for two Buttons in a fragment and pushed apps toward the Row wrapper the guidance forbids. The zone now accepts any number of controls; EmptyState's single action is unchanged.
|
|
18
|
+
- **The Kerf UI editor's parameter dialog reopens when a row is chosen while it closes (KF-8SPEG7).** The new choice was lost when the exit motion ended.
|
|
19
|
+
- **Kerf UI relocated toolbar groups keep keyboard focus when the relocated set changes (KF-KHTDC2).** A labeled `ToolbarControlGroup` with `relocateOnCollapse` now renders a stable `data-key` from its `label`; a `data-key` in `rootAttributes` overrides it. When groups join or leave the set a collapsed panel relocates, a focused control in an unchanged group keeps its DOM node and focus instead of dropping to `<body>`.
|
|
20
|
+
|
|
21
|
+
- **Homepage size claims (KF-60YNT1).** The homepage advertises the measured ~15 KB core bundle, and all four claims now participate in the existing bundle-size gate.
|
|
22
|
+
|
|
23
|
+
- **Dependency security (KF-3NWVZN).** Refresh vulnerable tooling, docs and example dependencies. The setup CLI retains Node 18 support through the unaffected minimatch 6 branch; contributor tooling resolves affected minimatch versions to patched 11.x. Astro stays on its patched 7.3 line to preserve the docs site's Node 22.12 floor.
|
|
24
|
+
|
|
25
|
+
- **Downstream Library previews (KF-RQJ15M).** Hosts and component catalogs can register typed Library-only samples, static schematics and icon fallbacks. Built-ins use the same extension; inert shadow thumbnails share styles and refit loaded assets, while insertion defaults and canvas rendering stay independent.
|
|
26
|
+
|
|
27
|
+
- Editor container, document and icon pickers restore the empty search placeholder and geometry after keyboard deletion, using their own SearchField wiring without duplicating play-stage helpers (KF-TBVRS4).
|
|
28
|
+
|
|
29
|
+
- Stable release CLI rejects unknown options and supports an explicit noninteractive dry-run plan without altering release state or metadata, fetching/creating tags, committing, pushing, or publishing (KF-Y9A9XE).
|
|
30
|
+
|
|
31
|
+
- **Shared generated component runtime (KF-4DR6XR).** Generated TypeScript and JavaScript views import one lightweight `@kerfjs/ui/view-runtime` helper instead of repeating it in every module. The curried boundary preserves component prop checking and linear catalog bundling analysis; declarations-only and component-free views add no runtime import.
|
|
32
|
+
|
|
33
|
+
- **Project TypeScript parameters (KF-26P9FT, KF-B8YSHV, KF-MB5FFZ, KF-AFW3ZA).** The Params rail shows compact name/type rows. A dialog provides TypeScript text entry, project symbol completion, automatic formatting and nested type navigation. The owning project compiler checks expressions, defaults and generated bindings before editor export or CLI generation; saved expressions preserve their import context.
|
|
34
|
+
|
|
35
|
+
- **Library file icons (KF-CBA2H7).** Both document layouts show decorative Lucide folder icons and extension-specific file icons, with a generic file fallback.
|
|
36
|
+
|
|
37
|
+
- **Library disclosure latency (KF-1XBJDT).** The document hierarchy stays stable across disclosure changes and TreeList offers explicit `keyedRows` reconciliation while default markup keeps nested-list composition. Divider matching excludes internal divider-free tree rows, and normal block flow avoids full-column flex layout on a branch change. The initial keyed-row plus final-icon measurement phase recorded 158–174 ms Chromium disclosure turns (about 421 ms before that optimization) and 732–814 ms in WebKit, with no pre-change WebKit baseline; these are earlier-phase figures, not final block-flow results. Same-machine rendering controls and later exact-source Linux results are recorded separately in the performance reports. CI measures the unchanged budgets once in a single-worker phase after functional tests, with exact-once test coverage and separate raw evidence; this controls benchmark workload rather than claiming another product speedup.
|
|
38
|
+
|
|
39
|
+
- **Library minimum size (KF-GC3PRB).** Shrinking the Library keeps its search and result rows visible through a public, viewport-capped PinnablePopoverSurface `minHeight` option. Keyboard resize remembers the actual constrained height without pinning.
|
|
40
|
+
|
|
41
|
+
- **Library keyboard-cleared search (KF-0XRNXD).** Select All then Delete now restores the same empty editor, placeholder, and field height as the clear button by installing shared SearchField wiring on the Library surface.
|
|
42
|
+
|
|
43
|
+
- **Library column clipping (KF-7HP7R9).** Document columns now clip at the Library surface edges while retaining row content insets. Public ColumnTrack/ColumnExplorer `inset` and PinnablePopoverSurface `bodyInset` options configure that boundary.
|
|
44
|
+
|
|
45
|
+
- **Library column headings (KF-MGAP67).** Each document column now carries its own quiet parent-folder heading; the shared path label and Back control are removed.
|
|
46
|
+
|
|
47
|
+
- **Editor Library resize (KF-EQRNAR).** Bottom-edge pointer and keyboard resizing now remembers the chosen size without pinning the Library. Header movement still pins it; transient panels keep light dismissal and restore their size after reopening or reload.
|
|
48
|
+
|
|
49
|
+
### Removed
|
|
50
|
+
|
|
51
|
+
- **`@kerfjs/ui/view` generator internals (KF-V5DPD1).** `printDoc` and `moduleSpecifier` are no longer exported by the public view subpath; repository tests import them from the generator module. The view subpath has only shipped in the 5.0.0 beta line.
|
|
52
|
+
- **Pinned TabBarItem support.** Removed `pinned` and its sticky/backdrop tokens and RTL compensation. Put fixed controls in TabBar's existing `leading`, `trailing`, or `end` zones outside the scrolling tablist. Ordinary tabs retain keyboard navigation, selection reveal, reordering, scroll dividers, and optional whole-tab snapping (`KF-K6GKN3`).
|
|
53
|
+
|
|
54
|
+
### Added
|
|
55
|
+
|
|
56
|
+
- **Kerf UI `RadioGroup` draws preview tiles (KF-C29WJ9).** `presentation="tiles"` draws each choice as a framed preview above its label and optional hint, for options best told apart by a picture of their result, such as a Theme picker's Auto, Light, and Dark. Each choice takes a decorative `preview` (a small SVG or image, `aria-hidden`). The selection shows as a brand ring plus a check mark, and the tiles wrap whole, with three fitting a phone-width column. The radios stay native: one Tab stop, arrow keys move and select, and the checked value submits. The UX catalog's RadioGroup page has a **Preview Tiles** example.
|
|
57
|
+
|
|
58
|
+
- **Kerf UI `PinnablePopoverSurface` has a persistent, app-owned mode (KF-850ZRF).** `pinnable={false}` renders a floating panel that is always pinned: there's no Pin toggle, and it never re-anchors or closes on a press outside. It still drags by its title, moves with the arrow keys, resizes, stays inside the viewport, and reports moves and resizes through `onChange`. `closable={false}` omits the header Close button so an application control owns visibility; Escape then closes it only when `wirePinnablePopover` is given the new `closeOnEscape: true`. `headerActions` stay, so an app can offer a Reattach control. The UX catalog's surface-scaffold page has a **Persistent Floating Panel** example.
|
|
59
|
+
|
|
60
|
+
- **Kerf UI `TabBarFit` reports the room beside an adjacent tab strip (KF-3A0DBM).** `wireTabBars`' `onFitChange` adds `barWidth` (the bar's content width) and `endFree` (the room between the leading, tab, and trailing zones and the `end` zone, or the bar's end edge without one). With `trailingPlacement="adjacent"` the strip is only as wide as its tabs, so `free` stays about 0; `endFree` is the room an `end` action can grow into. The wiring now also observes the bar itself, so a bar that grows without any zone resizing reports again.
|
|
61
|
+
|
|
62
|
+
- **A ListHeader can start on the summary rows' leading edge (KF-J8GMA2).** `leadingEdge="summary-row"` makes a fill-width header span its container as `SummaryRow`s do and start its label (toggle or heading) on their leading-content edge, compacting with them at the same 384px width. Apps no longer mirror SummaryRow's internal inset and compaction width in their own CSS.
|
|
63
|
+
|
|
64
|
+
- **A collapsible ListHeader can carry its section's commands (KF-X2MRCT).** A `toggle` header takes one trailing overflow button (`overflowAction`, `overflowLabel`, `overflowIcon`, optional `overflowDisabled` and `overflowTriggerAttributes` for popup metadata). It is a separate focus stop at the logical end, outside the disclosure button: the label and arrow toggle the section, and the overflow button never does.
|
|
65
|
+
|
|
66
|
+
- **Editor Documents folder layouts (KF-D4XZXG).** The Library's Documents mode now offers a folder TreeList and a paged ColumnExplorer with a remembered layout choice, keyboard navigation, and per-column parent-folder headings. File rows retain click and drag insertion.
|
|
67
|
+
- **Differential `bindList` and morph transition fuzzing (KF-YVMSEK).** Seeded mutations now compare incremental output with a fresh render across snapshot, granular, virtualized, and live-DOM protection states; directed tests cover recovery, refill, measured heights, and paired lists.
|
|
68
|
+
- **Kerf UI size, density, and inset prop vocabulary (KF-XQJECP).** Control sizes and row densities use `default` / `compact`; surface inset props use `none`, `compact`, `default`, or `comfortable` where applicable. Legacy literals remain accepted for this major version, with `KUI-L026` analyzer review findings and canonical DOM attributes. The component catalog records aliases and semantic exceptions, and its check rejects new divergent literals. `DialogSurface`'s legacy `compact` inset keeps its 8px geometry; new callers use `default` for 8px.
|
|
69
|
+
|
|
70
|
+
- **`debouncedSignal()` can be disposed (KF-EE8EPV).** It returns a `DebouncedSignal<T>`: the same read-only signal plus an idempotent `dispose()` that unsubscribes from the source and drops any pending write.
|
|
71
|
+
- **`@kerfjs/ui/view` exports one child-kind dispatch (KF-TZKGBZ).** `childKind()` / `classifyChild()` and the `ViewEachChild` / `ViewIfChild` / `ViewSlotChild` types replace hand-written `'$each' in child` chains.
|
|
72
|
+
- **`@kerfjs/ui` exports a shared `SurfacePresentation` type (KF-0MY6JQ).** The popover and pinnable presentation types are now aliases of it.
|
|
73
|
+
- **`npm create kerf-component --name <package-name>` (KF-7H7FWV).** Scoped package names are now reachable; the CLI rejects unknown flags and explains when the target is an existing file.
|
|
74
|
+
- **Kerf UI `wireTabBars` reports how each TabBar's tabs fit (KF-XFG3FZ).** A new `onFitChange(fit)` option reports `{ barId, overflowing, stripWidth, tabsWidth, free, trailingWidth, endWidth }`. It fires once per bar when the wiring first sees it, then on the next frame after any rounded value changes: a resize, an added or removed tab, or a swapped action. An app can swap a wide `end` action for a compact one while the tabs overflow without measuring TabBar's private parts. `free` is the room the tabs leave unused and is negative by the amount they overflow. Intrinsic tabs ellipsize before the strip scrolls, so `free` reaches 0 before `overflowing` turns true. The UX catalog's **Adaptive End Action** example shows the no-oscillation recipe: remember the wide action's `endWidth`, and restore it once `free` covers the difference. The new `TabBarFit` type is exported from `@kerfjs/ui/wire-tab-bars`.
|
|
75
|
+
- **The Kerf UI editor's Library offers the project's documents (KF-FXACB5).** With a storage that lists documents, the Library popover shows a **Documents** group after its component groups: each other `.kui.json` document as a row (file name over its folder) or, in the grid view, a tile with a file icon. The Library's filter also filters them (a match on "Documents" keeps them all). A click inserts a `#view` of the document inside the selected node (its main zone first), else after it; with nothing selected, inside the root; in a rootless document, as the root. A drag drops it onto the canvas or the outline like a component. Either way its required params are seeded, it renders at once, it is one undoable edit, and a transient Library closes unless it is pinned or Option is held. A document that cannot be composed (declares slots, unreadable, does not parse) is refused with the reason in the Library; a drag over the canvas says why. A node type without a package (`#view`) no longer adds a bogus catalog entry when placed.
|
|
76
|
+
- **The Kerf UI editor inserts an existing document as a `#view` from a picker (KF-PX5EVZ).** With storage, Add a child's Component Select offers **Existing document…**; Add opens an **Insert Document** dialog that lists the project's other `.kui.json` documents under a filter. Choosing one reads it, puts a `#view` of it in the chosen zone with its required params seeded with example values, selects it, and renders it at once, as one undoable edit. A document that declares slots, cannot be read, or does not parse is refused with the reason. `EditorStorage` gains an optional `list()` (project-relative `.kui.json` paths); `devServerStorage(api?, listApi?)` implements it over the new `EDITOR_LIST_API`, which `@kerfjs/ui/vite-editor`'s `editorFileMiddleware` answers (`KERF_UI_EDITOR_LIST_API`, `editorDocuments(root)`: sorted, at most 5000, skipping `node_modules`, `dist`, `test-results`, and dot-folders). A storage without `list()` gets a path field instead.
|
|
77
|
+
- **The Kerf UI editor says how to switch a condition chain to kinds (KF-B0ZDE6).** On a list whose rows are picked by an `$if` chain, Row designs now shows "Rows chosen by conditions; to pick them by kind, remove designs down to one." where a one-design list offers Or pick designs by kind. The editor deliberately does not convert between the two forms: a chain reads true/false item fields and a kinds map reads one kind field, so switching changes the data the application sends (docs/26 §3.5).
|
|
78
|
+
- **A document composed into a row is keyed, and its actions are row actions (KF-RDZ7N7, KF-EP2152).** Every generated `render<Name>(inputs, slots, rowKey?)` takes an optional third argument and puts it on its root as `data-key`; a row whose template (or `$if`-chain design, or kinds-map entry) is a `#view` passes `String(<key>)`, and `interpretView` / `previewView` thread the key the same way. Before, those composed row roots had no `data-key`, so kerf `each()` matched them by position and a row action's `key` read empty. Such a document's actions now count as row actions of the composing document (its own contract keeps them view-scoped), so the composing module's handlers get the row `key`, and the editor's Extract to document no longer refuses a row design that shares the other designs' action. Composing the same document both inside and outside a row reports `KUI-V009`. The argument is not an input, so contract digests are unchanged; regenerate view modules to pick up the key.
|
|
79
|
+
- **Kerf UI `Toolbar responsive="wrap-groups"` wraps a leading zone of control groups (KF-K3TXCT).** For a toolbar whose leading zone is several `ToolbarControlGroup`s rather than a title, each leading group shares a row with the trailing zone while it fits and otherwise moves, whole, to the next row; the trailing zone stays at the inline end. Before, `wrap` kept the leading zone on one row and `stack` wrapped only the center and trailing zones, so the last leading group was clipped at a narrow width. The existing policies are unchanged. The Kerf UI editor's play bar uses it: the device options and Scale are back beside the device picker at wide widths, and still wrap whole at 390px.
|
|
80
|
+
- **Play mode wires the rest of a composed document's controls (KF-HBRKFH).** Inside a `#view`'s document in the Kerf UI editor's play mode, a Combobox, ColorField, ColorPicker, or TagField change, a ResizableRegion or SplitView list resize, and a TabBar reorder now reach that document's play copy (or the row it sits in). Each composed SplitView follows the device into `compact`, and each composed NavStack starts at its root view. A repeated tab in a composed document closes out of the param its items come from, through the `#view`'s `$param` props to a top param, or by changing a literal (or unset) prop on the `#view` that holds it. A repeated `#view`'s structural state is still shared by its rows.
|
|
81
|
+
- **Play mode wires controlled components inside composed documents (KF-58917B).** In the Kerf UI editor's play mode, a Switch, TabBar, TabNavigator, NavStack, or other controlled component inside a `#view`'s document now responds. Each composed node plays with a composed id (its `#view`'s id and its own), each `#view` keeps a play copy of its document, and a row `#view` passes its row keys so per-row state stays in its row. A value change goes where the value comes from: through a `$param` to the `#view`'s prop, then to a param, the `#view`'s literal prop, or (for a repeated `#view`'s `$bind`) its row item's field. Anything it cannot trace stays on the node for its row. The pure parts are `ui/src/editor/model/play-views.ts`.
|
|
82
|
+
- **The Kerf UI editor shows and plays `PinnablePopoverSurface` (KF-ZWG0B2).** Like `PopoverDialogSurface`, it shows embedded on the edit canvas (header, Pin, Close, and content, all selectable) instead of as a closed top-layer popover, and the Components grid gives it its own sketch. In play mode it is wired with `wirePinnablePopover`, so it opens below its trigger, light-dismisses while transient, and pins, moves, and resizes; a `pinned` prop starts it pinned.
|
|
83
|
+
- **Play mode renders composed documents (KF-85SCQD).** In the Kerf UI editor's play mode, a `#view` (such as an `$each` row that is its own row document) played as a "cannot render" placeholder, because the play stage has no storage. The editor now sends the composed documents it loaded with the document it plays, so the stage renders the rows as the canvas does, and a row document's actions reach the host's play handlers and the action log, named as their `#view`.
|
|
84
|
+
- **Kerf UI editor: reorder row designs (KF-STBQBG).** A selected row design in the Repeat section's Row designs moves with Move design earlier and Move design later. In an `$if` chain a design's condition moves with it and the last design, the `else` for every other item, stays last; in a list keyed by kind any design moves, which changes only the map's order. The model edits are `moveRowDesign` and `rowDesignMoves` in the editor's `model/row-designs.ts`.
|
|
85
|
+
- **Smarter drop targeting in the Kerf UI editor (KF-WKABP2).** Dragging over a Workbench or SplitView shows each zone that would take the drag as a region where it renders (a Workbench's left and right rails, header, main, footer, and bottom drawer), and the region under the pointer is where the drop goes: dropping a NavStack on a new Workbench's left side now fills its left rail instead of always landing in the main header. A node alone in a one-child zone can be replaced by a drop ("Replace Main"); a seeded placeholder is replaced at once, authored content after a confirmation, and Undo restores it. A drop made with Option (Alt) held, or one inside a container with several zones and no main one, opens a menu listing every place it can go.
|
|
86
|
+
- **Kerf UI view documents: a row design per item (KF-8J8E5V).** An `$each` template may now be an `$if` chain, `{ "$if": <boolean>, "then": <node>, "else": <node or another chain> }`, so a list can render a section header row for some items and an item row for others. Each branch is one keyable node with a `data-*` channel, and `else` is required, so every item yields exactly one row. The condition resolves in the item's scope. `generateView` writes `each(items, (item) => (cond ? A : B), { key })`, `interpretView` and `previewView` render the same branch, and a named node in any branch is a keyed ref that returns `null` for a row that took another branch. `validateView` reports a chain without `else`, a branch that is not one node, and a branch with no `data-*` channel as `KUI-V008`. The view-document schema accepts the chain, and `ViewTemplate` / `ViewTemplateChain` are exported types. Documents that do not use a chain generate byte-identical modules. Authoring a chain in the Kerf UI editor follows in KF-1CRGP1.
|
|
87
|
+
- **Kerf UI `PinnablePopoverSurface`: a non-modal panel the person can pin and move (KF-C57ZX0).** `@kerfjs/ui/surface-scaffold` adds `PinnablePopoverSurface` with `wirePinnablePopover(surface, { anchor?, pinned?, placement?, step?, largeStep?, onChange? })`, `pinPopover(surface, pinned?)`, and `isPopoverPinned(surface)`. It opens transient below its `popoverTarget` control and closes on Escape or a press outside. Pinned by its header Pin toggle (`aria-pressed`) or `pinPopover`, it stays open while the page is used, drags by its title, moves with the arrow keys on the focused title (Shift moves farther), resizes from its corner, and stays inside the viewport gutter after a window resize, returning to where the person put it when there is room. Moving a transient surface pins it. `onChange` reports `{ pinned, placement, reason }` for the application to store, and the `pinned` and `placement` options restore it. The controller keeps its state across application re-renders. It takes `PopoverDialogSurface`'s geometry props and an `embedded` presentation. The Surface Scaffolds demo's Pinnable Popover example shows the transient, pinned, moved, and restored states. The UI skill is now 1.74.0.
|
|
88
|
+
- **The Kerf UI editor extracts a subtree into a document of its own (KF-D9P3NP).** **Extract to › New document…** in the Flow area (also **Extract to Document…** in the node context menu) asks for the new document's path in a Save As–style dialog, suggesting one beside the current document, then writes a document whose root is the selected node (a repeated row, one row design of an `$if` chain or kinds map, or any other subtree) and puts a `#view` of it in its place. Every `$param` and `$bind` the subtree reads becomes one of the new document's params, typed from the source (a row's `message.subject` becomes a string param `subject`), and the `#view` passes the values back. One Undo restores the subtree; the new file stays. It is disabled, with the reason, on the root, on a subtree holding a slot, and without storage, and refused when the result would add a problem.
|
|
89
|
+
- **The Kerf UI editor renders and inspects composed documents (KF-5N26H6).** A `#view` node, such as an `$each` row that is its own row document, now loads its document through the editor's storage (resolving `src` from the composing document's folder, as `kerf-ui-view` does) and renders it in place on the canvas; a click anywhere in it selects the `#view`. Problems validate against the loaded document, so a missing required param or a prop of the wrong type is `KUI-V012` on its field, and a document that cannot load says why (no storage, still loading, no such file, or unreadable). The Inspector edits a `#view`'s props as that document's params, with the same fields and **Bind a prop** sources as any prop (a row's `message.subject`, offered only when its type fits). **Open document** opens the composed document, saving the composing one first, and **Back to <file>** in the canvas toolbar returns to it with the `#view` selected. Export and Compare generate a composing document's module with its composed documents. Inserting a `#view` from a picker comes next.
|
|
90
|
+
- **Kerf UI view documents: row designs keyed by item kind (KF-YX6HMT).** An `$each` may carry `"templates": { "<kind>": <node>, … }` and `"kind": <string value>` instead of `template`, so each item's `kind` picks its row design, like Interface Builder's prototype cells. A `default` entry is required and takes every other kind, so a repeat never filters. `validateView` reports, as `KUI-V008`, an `$each` with both `template` and `templates`, a map without `default`, a missing or stray `kind`, and an entry that is not one keyable node. `generateView` compares the kind per row and exports `type <Name><As>Kind`; the contract gains a `kinds` member only for documents that use a map (other digests are unchanged), and `diffContracts` reports a removed kind as breaking and an added one as not. `interpretView` and `previewView` pick the same template, the schema accepts the map, and `ViewChild`'s `$each` gains the `templates`/`kind` variant. In the editor, a one-design list can pick its designs by kind, then add, rename, and remove kinds in Row designs. The view bundle budgets rise to 13000 B (`interpretView`, 12915 measured) and 9450 B (`validateView`, 9364 measured).
|
|
91
|
+
- **Kerf UI editor: row designs (KF-1CRGP1).** A repeated node's Inspector has a Row designs section that authors an `$if`-chain template: Add a row design picks a component and a true/false param or item field, and the new design shows for those items while the last design keeps every other item. A selected design changes when it shows or is removed; a chain left with one design becomes a plain template. The outline lists each design with `if …`, `else if …`, or `otherwise`, the canvas renders each item's design, and play mode keeps row state and logs row actions for rows of any design. `ViewChild`'s `$each` `template` is now typed `ViewTemplate`, so TypeScript code that reads `child.template.id` narrows it first.
|
|
92
|
+
- **Kerf UI's no-network guarantee is tested and documented (KF-WK5DEF).** No Kerf UI component requests anything at runtime: icons are bundled Lucide SVG, and no component renders a Web Awesome element (4.4.1's `Select` did, so its `wa-icon` chevron fetched from Font Awesome's CDN). A browser test now loads every Kerf component's catalog demo and fails on any request off the page's origin. `ui/docs/webawesome-theme.md`, `ui/llms.txt`, and the UI skill (1.73.0) say so, and tell an application that renders Web Awesome elements itself to register a local icon library.
|
|
93
|
+
- **A grid view for the Kerf UI editor's Components palette (KF-JC7WTW).** A List/Grid control beside the Components filter switches the palette to tiles, and the editor remembers the choice per browser. Each tile shows its component as it would be added, rendered live and scaled into the tile: a Switch looks like a switch. Layouts, dialogs, and arrangement primitives (Workbench, SplitView, NavStack, DialogSurface, Grid, Spacer, and others) show a simplified sketch of their arrangement instead, since they render almost nothing when added empty. Tiles select, filter, and drag onto the canvas or the Outline like rows.
|
|
94
|
+
- **Kerf UI `Gauge` (KF-Y0XT2R).** `@kerfjs/ui/gauge` is a speedometer-style dial for a live rate or level read at a glance: a 240-degree track, a fill, and a needle scaled to `max`, as a named `role="meter"`. `variant="full"` (88px by default) adds ticks and the value and `unit` inside the dial; `variant="bare"` (40px) is the arc, fill, and needle at chip height with a hover title. Values above `max` pin the needle while the text shows the real value. `tone` colors the fill, `size` takes a `CssLength`, and `colors` takes typed `CssColor` values for a consumer palette. The needle and fill animate only on a value change and hold still under reduced motion.
|
|
95
|
+
- **Kerf UI `SegmentedControl` choice count badges (KF-170258).** A `SegmentedControlChoice` takes `badge` (a count, short text, or `true` for a dot), `badgeTone` (default `danger`), and `badgeMax` (default 99, so 128 shows "99+"), the same contract as `ToolbarButton`, so a toolbar view switcher can show a live count without app CSS or giving up its exclusive selection. A count of 0 or empty text shows nothing, and a loading `placeholder` shows no badge. The badge is `aria-hidden`; name the count in the choice's `label` and `title`. Kerf seats it on the segment's top edge over its icon and rings it in the segment's current fill (at rest, hover, or selected), and it never leaves the segment, so neither a toolbar nor a filled track clips it.
|
|
96
|
+
- **Kerf UI `ToolbarButton` count badges (KF-HDQTVV).** A ToolbarControlGroup button takes `badge` (a count, short text, or `true` for a dot), `badgeTone` (default `danger`), and `badgeMax` (default 99, so 128 shows "99+"). A count of 0 or empty text shows no badge. Kerf owns the pill's placement just over the icon's top-trailing corner, a 2px ring against the group's surface (the page surface for a borderless group), and 16px sizing at both group sizes, so apps no longer position a `Badge` with their own CSS. A Toolbar zone holding one stops clipping it, because WebKit cut its top off flat. The badge is `aria-hidden`, so the caller names the count in `ariaLabel` and `title` ("Workers, 2 live"). It is plain data, so the Kerf UI editor can author it. The ToolbarControlGroup demo's Corner Count example shows 0, 2, 99+, and a dot at default and compact sizes.
|
|
97
|
+
- **Kerf UI `SummaryRow` `action` (KF-YT6A0N).** A SummaryRow option takes an `action` prop, rendered as `data-action`, as ContentItem and ListItem do. A view document can now name the action a row fires, so the editor's play mode logs it (and hands it to the app's play handler) when the row is clicked or chosen with Enter or Space. A `data-action` in `rootAttributes` still works; `action` wins when both are set. Group rows (`semanticRole="group"`) take no `action`.
|
|
98
|
+
- **The Kerf UI editor's New starts with no root; the root can be deleted (KF-PK3GVY).** New, and the editor's first draft when the host passes no document, no longer seed a Pane. The canvas shows "Start with a component" with a component picker (Pane first) and Add, and the Outline says "No components yet". The chosen component becomes the root, seeded as Replace the root seeds it (a Pane starts with `fill`), and a component dragged from Components onto the empty canvas, or a pasted copy, becomes the root the same way. The root can now be deleted from the Inspector, the context menu, or the Delete key: the document goes back to having no root, keeps its params, slots, and name, and one Undo restores the tree. Replace the root stays as a shortcut. **File format:** `root` is now optional in `kerf-ui-document/v1` (`ui/ai/view-document.schema.json`, `ViewDocument.root?`), so an empty draft autosaves and saves as a document with no `root` field. `validateView` reports it as the new `KUI-V017` ("the document has no root"), so `generateView`, `interpretView`, and `kerf-ui-view` refuse it with that diagnostic, and `previewView` renders nothing.
|
|
99
|
+
- **Kerf UI `PagedView` `pageLabel` localizes the page dots (KF-QSWJGQ).** Each dot's accessible name was fixed English ("Page 2 of 3: <label>"). `pageLabel` is a template string that fills `{index}` (1-based), `{count}`, and `{label}`, such as `pageLabel="Seite {index} von {count}: {label}"`; the default `Page {index} of {count}: {label}` is unchanged. It is a plain string, so the Kerf UI editor can author it. A placeholder inside a page label is spoken as written.
|
|
100
|
+
- **A Kerf UI `PagedView` (KF-0QJ2K3).** `PagedView` (`@kerfjs/ui/paged-view`) pages a sidebar or panel region horizontally between full-size panes, with compact page dots floating in a chrome-material pill at the bottom; page content scrolls beneath the dots and ends clear of them. Touch swipes and trackpad scrolls snap to a page, and the dots work by click and by Left, Right, Home, and End. `wirePagedViews(root, { onPageChange })` (`@kerfjs/ui/wire-paged-views`) reports the chosen page id so the app can own and persist `page`, and scrolls to whatever page a render shows, smoothly unless reduced motion is preferred. The dots are a tablist named "Page 2 of 3: <label>", and off-screen pages are inert.
|
|
101
|
+
- **Kerf UI single-select listboxes get the listbox keyboard (KF-3WS7RR).** A `List selectionMode="single"` listbox is now one Tab stop with Kerf-owned movement, matching the multi-select grid. The new `wireSummaryRows(root)` (`@kerfjs/ui/wire-summary-rows`) handles `SummaryRow` options and `wireContentItems` handles `ContentItem selectionMode="single"` options. The roving `tabindex` sits on the last focused option, else the selected one, else the first, and survives re-renders. Up/Down/Home/End move focus without selecting. Enter or Space selects the focused option by dispatching its click (Space on release, carrying the key's Shift, Ctrl, and Cmd state), so the app's delegated `data-action` handler still owns the selection. Apps can always override a key, in listboxes and grids alike: Kerf skips a key event that is already `defaultPrevented`, so handling the key first (on the option, in the capture phase, or from a listener added to the root before wiring) and calling `preventDefault()` replaces Kerf's movement or activation. The UX catalog wires `wireSummaryRows`. Its SummaryRow and ContentItem listboxes are now one Tab stop each.
|
|
102
|
+
- **A node context menu in the Kerf UI editor (KF-JV7XW1).** Right-click an Outline row or an element on the edit canvas, or press Shift+F10 or the ContextMenu key on a focused row, to select that node and open a menu at the pointer (below the row when opened from the keyboard). The menu offers **Embed in ›**, with the same entries and legality as the Flow area plus Other…, then Move up, Move down, Duplicate, and Delete. Commands that cannot act on the node are disabled. The menu is Kerf UI's own context `PopupMenu`. It does not open in play mode, it leaves click-to-select and drag alone, and focus returns to the row it opened from.
|
|
103
|
+
- **Kerf UI: `List landmark="group"` and `labelledBy` (KF-P9NV94).** A List can now be a named `role="group"` as well as a `region`, and a landmark List can take its name from a visible label with `labelledBy` (its id, rendered as `aria-labelledby`) instead of `ariaLabel`, never both. A read-only field preview grouped under its `FieldLabel` no longer needs a raw `<div role="group" aria-labelledby>`, so the editor can build it; the Text › Read-Only Field Preview demo uses it and has an editor build.
|
|
104
|
+
- **Embed in a NavStack, TabNavigator, or SplitView in the Kerf UI editor (KF-N7K17T).** These layouts have no main zone, so Embed in never offered them. A NavStack or TabNavigator now holds the embedded node in its first view's or tab's content, in place of that view's seeded slot, and a SplitView holds it in its detail pane beside its seeded list. Turning a Pane root into a NavStack no longer means Replace the root and losing the tree.
|
|
105
|
+
- **Embed in for the root in the Kerf UI editor (KF-84CCD1).** The root node's Flow area now has Embed in. The chosen container becomes the new root and holds the whole old tree in its main zone, under the same rule as any other node: it is offered only when the result adds no validation problem. A Pane that becomes the root starts with `fill`, as New's root does. The step is one undo. A node that is a `$each` template or an `$if` branch also embeds in place now.
|
|
106
|
+
- **Kerf UI view documents: `$param` / `$bind` inside list and object values (KF-3QEZFB).** A field inside a prop value, such as a ContentItem's `media.src`, can hold a document param or an `$each` item field, checked against that field's type, so app data sits beside fields the document builds (`media.overlay`). `interpretView` and generated code read it in place. The editor's object form gains **Bind a field**, which binds one scalar field or promotes its literal to a param with that literal as the default.
|
|
107
|
+
- **Kerf UI `List` `landmark="region"` and `ColumnTrack` `ariaLabel` (KF-CW7Z38).** `List landmark="region" ariaLabel="…"` renders a named `role="region"` (a reader, a result picker, a board column) and owns its `role` and `aria-label` over `rootAttributes`; TypeScript requires the name and rejects combining `landmark` with `selectionMode`, and the props catalog records both, so a view document with an unnamed landmark fails validation (`KUI-V004`). `ColumnTrack ariaLabel` names the board's scroller as a `role="region"`, as `SunkenPanel` does; a bare `aria-label` in its `rootAttributes` named a role-less `div` and was not exposed. `ListLandmark` is exported. The List › Document Inset, Result Picker, and List View Transitions demos and both ColumnTrack boards use the props instead of a `role` in `rootAttributes`, and the editor builds Document Inset, Result Picker, and both boards. Text › Read-Only Field Preview (a group named by its label's id) stays unbuilt pending KF-P9NV94.
|
|
108
|
+
- **Kerf UI `List` `selectionMode="single"`: a labeled listbox (KF-MN7QK5).** `List selectionMode="single" ariaLabel="…"` renders `role="listbox"` with that name, for `SummaryRow` options and `ContentItem selectionMode="single"` options, the way `selectionMode="multiple"` renders a multi-select grid; the app no longer wraps rows in its own `<div role="listbox">`. The options keep their Tab stop, `aria-selected`, and Enter/Space activation; the app still owns the selection and any arrow-key movement. TypeScript now requires `ariaLabel` whenever `selectionMode` is set (`ListSelectionMode` is exported), and the props catalog records it, so a view document with a selectable List and no name fails validation (`KUI-V004`). The SummaryRow, Grid › Selectable Document Tiles, and Text › Presentation Roles demos compose `Text variant="span" weight="strong"` instead of raw `<strong>`, and the editor builds all five examples.
|
|
109
|
+
- **Kerf UI `Pane` `scrollAnchoring`; the editor Inspector no longer jumps in Safari (KF-NV427Y).** `scrollAnchoring="none"` opts a Pane's scrolling content out of the browser's scroll anchoring (`overflow-anchor: none`); the default `auto` keeps it. `PaneConfig` forwards it through Workbench panes, CollapsiblePanel, and NavStack views. The editor's Inspector views opt out, because Safari applied a stale anchoring jump to the Inspector about 300ms after an edit inserted a row, when the autosave status reflowed another pane.
|
|
110
|
+
- **Docs: the Worker recipe cancels, disposes, and pools (KF-E6ER9X).** The `kerfjs/async` "heavy app compute in a Worker" recipe is now a `createCompute(spawn, init)` client: a `resource()` run's `AbortSignal` terminates a running job's worker, and the next call starts a fresh one and reloads its resident data through `init`; `dispose()` terminates and rejects pending and later calls, registered on a `kerfjs/scope`; and a short pool snippet sends each call to the least busy worker. No `kerfjs/worker` subpath ships (`docs/27-worker.md`).
|
|
111
|
+
- **Docs: the Worker recipe's `call()` no longer hangs on a failed worker (KF-CP3SZV).** The `kerfjs/async` "heavy app compute in a Worker" recipe now handles the worker's `error` and `messageerror` events: a worker that fails to load or crashes rejects every pending call, and later calls reject at once instead of waiting forever.
|
|
112
|
+
- **Kerf UI embedded popups sit in flow outside a Toolbar (KF-A1Y7SY).** An `embedded` PopupMenu or Select placed directly in a Pane (or any scrolling container) had its preview menu clipped, because an overlay cannot escape a scroller. Outside a Toolbar the embedded popup now sits in flow below its trigger (a Select's listbox before its hint); inside a Toolbar it still overlays so the control band keeps its height.
|
|
113
|
+
- **Editor: the Inspector hides preview-only popup props (KF-TGGSHZ).** PopupMenu `embedded` / `embeddedSubmenu` and Select `embedded` exist for the canvas preview, which sets them itself; authored in a view they would make the app's popup inert, so the props catalog marks them `hidden`. A dialog's `embedded` presentation stays authorable.
|
|
114
|
+
- **Kerf UI `FieldLabel` declares `id` (KF-Q70Q9Y).** `id` was only a pass-through native attribute, so the editor could not author the id a group's `labelledBy` names. It is now a declared prop in the props catalog.
|
|
115
|
+
- **Editor: an object's required switches write `false` (KF-VQTDYG).** Filling in an object prop in the Inspector (a DialogSurface `stack`) now writes `false` for each required boolean whose switch shows off, so the document is valid without turning each switch on and off.
|
|
116
|
+
- **View validation places a ListDetailDialog's toolbar controls in their Toolbar (KF-WBH5P2).** A composition entry's `configTypes` can name one field of a config type (`ListDetailDialogList.toolbar`, `ListDetailDialogDetail.actions`), so a ToolbarControlGroup in a ListDetailDialog's list toolbar or detail actions no longer fails `KUI-L201`, while the column's `content` and `footer` keep their own placement rules.
|
|
117
|
+
- **Kerf UI `PopupMenu` `embeddedSubmenu`; the editor canvas shows the submenu being edited (KF-M2FGPQ).** With `embedded`, `embeddedSubmenu` (a path of `items` indices, one per level) also shows that submenu open, in the document and inert. It sits beside its item with its first row level with the item, as the register places a real one, on the start side for an end-aligned menu, and below its parent menu at phone widths. The item takes its open-submenu fill. While the Inspector edits a place inside a PopupMenu item's `submenu` (`items.2.submenu…`), the edit canvas shows that submenu open. The document, the Inspector, and the export are unchanged. The UX catalog's Embedded Preview menu shows a Group By submenu.
|
|
118
|
+
- **An embedded Kerf UI `PopupMenu` or `Select` keeps no focus fill, and a Select's listbox sits on its control (KF-HVJDWF).** An embedded popup's rows take no focus: a menu's items render as static rows instead of buttons, and a Select's choices and listbox drop their `tabindex`. A click on a row no longer leaves the current-row fill, which looked like a stuck hover or a choice, and on the editor canvas the click still selects the PopupMenu or Select. An embedded Select's listbox now hangs right below the control, over its `hint`, as the real listbox does. The UX catalog's Embedded Preview Select shows a hint.
|
|
119
|
+
- **Kerf UI `PopupMenu` and `Select` `embedded`; the editor canvas shows a selected one open (KF-KN9CPE).** `embedded` renders the popup open at its trigger, in the document instead of the top layer, as a static preview: a PopupMenu's menu at its `placement` (its submenus stay closed), a Select's listbox below the control. It overlays what lies below rather than pushing it aside, so a trigger in a toolbar group keeps its place, and a toolbar's leading zone stops clipping while it holds one. An embedded popup is inert: the registers leave it alone, so its trigger opens nothing and its rows choose nothing, and a menu's items render without their `data-action`. The editor's edit canvas shows the selected PopupMenu or Select embedded, so the `items` or `choices` edited in the Inspector are visible; the document, the Inspector, and the export keep the authored props, and play mode opens the real popup. The UX catalog shows each as an Embedded Preview example.
|
|
120
|
+
- **Kerf UI `Pane` `anchorName` (KF-TBCXTR).** A Pane names its root as a CSS anchor (`anchor-name`) from a dashed ident, so an app names its main column for an anchored `PopoverDialogSurface` without CSS. `PaneConfig` forwards it through Workbench panes, panel panes, CollapsiblePanel, and NavStack views. A value that is not a dashed ident throws.
|
|
121
|
+
- **Kerf UI `PopoverDialogSurface` manual dismiss and anchored docking; transient surfaces on the editor canvas (KF-T1V86Q).** `dismiss="manual"` renders `popover="manual"`, so Escape and a press outside leave a request open until its own controls close it. `anchorName` (a CSS dashed ident) docks the open overlay centered on the bottom edge of the element the application names with that `anchor-name`, inset by `viewportGutter`; engines without CSS anchor positioning keep the centered placement. The editor's edit canvas now shows every PopoverDialogSurface embedded, and play mode names its view root with each `anchorName` the played view references, a placeholder anchor standing in for the application's region. The UX catalog's anchored request popup is now a PopoverDialogSurface instead of an app-owned element with its own CSS.
|
|
122
|
+
- **`eslint-plugin-kerfjs` flags a raw `<form>` (KF-JPE38T).** `ui-preferences` reports a native `<form>` as `KUI-L303` and points at Kerf UI's `Form` with `wireForms`, which keeps a submission from navigating the page. A `Form` rendered without `wireForms` reachable was already reported by `ui-wiring` (`KUI-L401`); that case is now pinned by a test. Kerf UI `Form` gains `labelledBy`, `ariaLabel`, and `describedBy` for a named `form` landmark, and the composer-form recipe renders a `Form` instead of a raw `<form>`.
|
|
123
|
+
- **Kerf UI Button new-tab links get `rel="noopener noreferrer"` (KF-6GBJBP).** An enabled link `Button` whose target is `_blank` (through `link` or `href` + `target`) now renders `rel="noopener noreferrer"`, matching a link `Chip`'s `external`.
|
|
124
|
+
- **Kerf UI Button link emphasis and a `link` prop (KF-RESJ2S).** `emphasis="link"` draws any `Button`, a `<button>` with an `action` or a link, as an inline text link: underlined text in its tone's link color (neutral takes `--kui-color-text-link`) at the surrounding text size, with no fill, border, padding, or control height, keeping its native role and focus ring. It cannot take `pressed`. `link` takes a URL string, a `URL`, or `{ href, target }` and renders an `<a>` that keeps the Button's emphasis; it is the preferred form of `href` + `target`, which keep working, and giving both throws. The Inspector edits `link` as text or as a destination with a target. The ContentItem feed-card demo's raw "Source" anchor is now a link-emphasis Button.
|
|
125
|
+
- **Router `match()` / `activeClass()` notify only the links that change (KF-5P2QAP).** A navigation used to re-evaluate every link's active check; links now share one `setSelector()` over the current path's segment prefixes, so a navigation updates the links that turned on or off and nothing else, however long the nav. Results are unchanged, including `match('/')` staying exact. The router subpath grows by 0.30 KB min+gzip.
|
|
126
|
+
- **`selector()` / `setSelector()` key signals stay current while held (KF-4TXB21).** A key signal read outside any subscriber, such as one a click handler keeps, now returns the current comparison. Before, it kept the answer it had when handed out until something subscribed. Subscribed keys still update at O(1) per change.
|
|
127
|
+
- **Opt-in selector fan-out dev warning (KF-AJ4KG6).** `enableWarnings({ selectorFanout: true })` from `kerfjs/dev` (or `KERF_DEV_WARN_SELECTOR_FANOUT=1` under Node) warns once per signal when three writes in a row each re-evaluate at least 200 `computed()`s and almost none of them (at most 2, or 2%) produce a different value — the per-row `computed(() => row.id === selected.value ? 'danger' : '')` shape that `selector()` and `setSelector()` make O(1). The message prints the write's stack. A broad update whose computeds all change stays silent, and a tick that writes two tracked signals is not attributed. Like `untrackedSignals`, it only covers signals and computeds created after the switch is on. `computed()` is now a thin kerf wrapper over signals-core's (same signature, `watched` / `unwatched` options forwarded).
|
|
128
|
+
- **A Kerf UI `TabPanel` (KF-RE1EBK).** `TabPanel` (`@kerfjs/ui/tab-panel`) renders the application-owned panel a `TabBarItem` controls: `role="tabpanel"` with `id`, `aria-labelledby` from `tabId`, `hidden`, and `busy` (`aria-busy`), plus content `children`, `className`, `slot`, and `data-*` `rootAttributes`. Pair its `id` with the tab's `panelId` and its `tabId` with the tab's `tabId`; selection stays application state, so hide every panel but the selected tab's. It adds no inset, chrome, or layout. The ApplicationTabs catalog demos now use TabPanel and nested `Text` nodes instead of raw `<section role="tabpanel">` and `<strong>` markup, and the Kerf UI editor builds both of them.
|
|
129
|
+
- **A Kerf UI `Form` (KF-XX4Y95).** `Form` (`@kerfjs/ui/form`) renders a layout-neutral native form (`display: contents`, no inset or chrome) with `id`, `name`, `action`, `noValidate`, `children`, and `rootAttributes`. Its `action` is a delegated `data-action` handled on `submit` with `delegateActions(root, 'submit', table)`, not a URL; call `wireForms(root)` (`@kerfjs/ui/wire-forms`) once so a submit Button or Enter in a field never navigates the page. The Kerf UI editor places it from the palette like any container and never navigates on a canvas or play-mode submission, and the ChoiceChips dialog demo uses it instead of a raw form.
|
|
130
|
+
- **`setSelector()` for set membership (KF-1TFHMP).** `setSelector(checked)` over a `signal<ReadonlySet<K>>` returns `(key) => ReadonlySignal<boolean>`; a write diffs the previous set against the next and notifies only the keys that were added or removed, so multi-select, expanded tree rows, or error fields stop re-evaluating every row. A new Set with the same members notifies nothing. Exported from `kerfjs`; it tree-shakes away when unused.
|
|
131
|
+
- **WorkbenchDialog and ListDetailDialog `embedded` (KF-RWJ9KD).** Both render in flow and always shown, keeping their `height`, through DialogSurface's embedded presentation, and the Kerf UI editor's edit canvas shows them that way so their content can be seen and selected. An embedded DialogSurface now also keeps a `height` / `maxHeight` and clips a filling body to its rounded corners as a modal does. It draws a 1px border instead of the drop shadow, which a scrolling pane clipped at its edge (KF-4RSG7D).
|
|
132
|
+
- **DialogSurface `presentation="embedded"`, and dialogs in the Kerf UI editor (KF-SYGSD0).** An embedded DialogSurface is the same panel in flow and always open, without the top layer or a backdrop; `openDialog` / `closeDialog` leave it alone and its close controls do not hide it. The editor's edit canvas shows every DialogSurface embedded, so a closed modal's content can be seen and selected while the document keeps its authored presentation. In play mode a `show-dialog` trigger with `data-dialog-id` opens its dialog modally, with `data-dialog-close`, Escape and the backdrop wired as in an app, and the action is logged.
|
|
133
|
+
- **`selector()` for O(1) row selection (KF-769EW2).** `selector(selectedId)` returns `(key) => ReadonlySignal<boolean>`. Bind `computed(() => isSelected(row.id).value ? 'danger' : '')` in each row: the selector subscribes to `selectedId` once and a change writes only the previous and next keys' signals, where the plain `row.id === selectedId.value` computed re-evaluated every row. Entries are released with the rows that watch them. Exported from `kerfjs`; it tree-shakes away when unused.
|
|
134
|
+
- **`resource()` fetchers can cancel superseded runs (KF-DSXXTD).** A fetcher now receives an `AbortSignal` as its second argument. It aborts when a newer `run()` supersedes the run or `reset()` is called, and never after the run has settled. Pass it to `fetch()` to close a superseded request, or terminate a Worker job; the abort rejection is dropped by the stale guard, so it never surfaces as `failed`. Existing `() => …` and `(report) => …` fetchers are unchanged.
|
|
135
|
+
- **`KUI-L024` / `KUI-L025` analyzer findings.** `kerf-ui-analyze` and `kerf-ui-doctor` report a stylesheet selector naming `.wa-light` / `.wa-dark` / `.wa-invert` / `.wa-theme-default` (use the `scheme` prop or the `.kui-*` scopes), and a `--wa-*` write that nothing reads in a package without `@awesome.me/webawesome`. Writes to the `--wa-*` values Kerf's foundation reads stay legitimate theming. `KUI-L023` also joins the diagnostic ID registry, so profile exceptions for it load (`KF-J0MCPN`).
|
|
136
|
+
- **`KUI-L302` lint finding for Web Awesome scope classes.** `eslint-plugin-kerfjs`'s `ui-preferences` rule reports `wa-light`, `wa-dark`, `wa-invert`, and `wa-theme-default` in a JSX `class` / `className` and points at the `scheme` prop or the `.kui-*` scope classes, since the Web Awesome classes do nothing without its theme. Like `KUI-L301`, it honors profile exceptions (`KF-M2F5K4`).
|
|
137
|
+
- **Kerf-owned appearance scopes.** `.kui-light`, `.kui-dark`, `.kui-invert` and `[data-kui-scheme]` set a subtree's scheme from `foundation.css`, so they work without Web Awesome. `Pane`, `ContentItem`, `NavStack`, `TabNavigator` and its tabs take a `scheme` prop for the plain palette in a fixed scheme; a `tint` implies its scheme, and a disagreeing pair throws. Tinted surfaces now render `data-kui-scheme` and `kui-<scheme>` in place of the Web Awesome `wa-<scheme>` class, which only worked when the Web Awesome bridge was loaded. The bridge re-derives Web Awesome elements inside the Kerf scopes and still honors `.wa-*` (`KF-E44H0A`).
|
|
138
|
+
- **`ListHeader controls` and `List hidden`.** A toggle header names the region it shows or hides with `controls` (reported as `aria-controls` on its trigger), and a List collapses with `hidden`, so a disclosed group is a List instead of a raw `div` and the Kerf UI editor can build the List "Scrollable Application List" demo (`KF-9JACQY`).
|
|
139
|
+
- **Edit and add text runs in the Kerf UI editor (KF-YBMVVM).** A zone that mixes text and nodes holds `#text` runs, but a run's text could not be edited and the only way to make one was **Use as nodes**, so text could not follow a node in a sentence. A selected run's Inspector now edits its text, and a text-accepting zone offers **Text run** in Add a child.
|
|
140
|
+
- **Text `lang` and `ariaLabel` are declared props (KF-AC7AFR).** Text took them only as inherited native attributes, which the Kerf UI editor does not edit, so the Semantic Variants demo's labelled paragraph could not be built. They render the same `lang` and `aria-label` attributes as before.
|
|
141
|
+
- **Button `expanded` (KF-DE348P).** A Button can be a disclosure control: `expanded` renders `aria-expanded`, the application flips it in its `action` handler, and a `DisclosureArrow` makes a natural `icon`. A link Button refuses it, as it refuses `pressed`. The DisclosureArrow demos now use it in place of raw `<button aria-expanded>` elements, so the Kerf UI editor can rebuild them; the editor offers it as a Not set / On / Off Select beside `pressed`.
|
|
142
|
+
- **Pick a ColorSwatches value by swatch in the Kerf UI editor (KF-H1X3S7).** The Inspector's value picker read only a node's `choices`, so a ColorSwatches `value` was a free text field where an author typed `#0a84ff`. `component-props.json` props can now name the sibling list a value picks from (`choicesFrom`, set in the props overlay); ColorSwatches' `value` takes its `swatches`, so it is a Select of swatch labels, and renaming a swatch's value keeps it selected. `check:props` rejects a `choicesFrom` that names no sibling prop.
|
|
143
|
+
- **Rename a param in the Kerf UI editor (KF-1HEZZZ).** Promote to a param names the new param `<ref name><Prop>`, or `node<Prop>` for a node without a ref name, and nothing could change it. A prop bound to a param now shows a **<Prop> param** field: a new name renames the param, keeps its place in `params`, and updates every `$param` reference (bindings, `$each` sources, `$if` conditions, composed inputs). A taken or non-camelCase name is refused in the field.
|
|
144
|
+
- **Set a component's classes in the Kerf UI editor (KF-X8X8VX).** `className` was hidden in the Inspector, so a view could not carry a class such as an appearance scope. It is now a **Classes** field in a trailing **Advanced** section; `component-props.json` marks it `control: "classes"` (also allowed in the props overlay schema). Inner hooks such as `headerClassName` stay hidden.
|
|
145
|
+
- **Text `id` is a declared prop.** Text took `id` only as an inherited native attribute, which the Kerf UI editor does not edit, so a Text could not be built as a link's destination (the ListItem › Native Navigation Link demo's `#list-item-link-target`). It renders the same `id` attribute as before (`KF-86PM4R`).
|
|
146
|
+
- **Text `live` and `rootAttributes`, and Row `ariaLabel`.** A Text readout can be an `aria-live` region and carry `data-*` hooks, and a Row of related controls can name itself as a group. The SearchField demos now use these in place of raw attributes, a raw `<span>` and a raw `<div role="group">`, so the Kerf UI editor can rebuild them (`KF-7V2VGS`).
|
|
147
|
+
- **A TextField end toggle, and Not set in the Kerf UI editor.** `TextField` takes `toggle: { label, icon, pressed, action }`, an icon toggle button inside the end of a single-line field that reports `aria-pressed` and runs its delegated `action` (a password's Show, for example). The editor's Inspector uses it for every optional text prop: the toggle, pressed while the prop is unset, unsets it, and an emptied field now holds the empty string instead of unsetting. A required text prop can be `""`, so ValueTableRow placeholder rows (`value=""`) are buildable (`KF-3Y2GS2`).
|
|
148
|
+
- **An empty zone in a Kerf UI view document is an explicit `null` (KF-YCM09F).** `validateView` accepts an empty zone list for a required prop that takes `null`, and `interpretView` and generated modules pass `null` for any empty zone. SplitView's `detail` composition minimum is now 0, so the editor can build a SplitView with nothing selected by removing the detail's last child. The SplitView demo passes `null` instead of an empty `<div />`.
|
|
149
|
+
- **Switch a list item's kind in the Kerf UI editor (KF-BGKYYH).** An item of a discriminated union list, such as a `ScrollEffect` effect or a `PopupMenu` entry, has a Kind Select in its form: switching a reveal to a scale keeps its `range`, `rangeStart`, and `rangeEnd` and shows the scale's `from` and `to`. So reveal on entry plus fade on exit builds in the effects list editor without JSON. Switching a member no longer carries over the old member's literal discriminant.
|
|
150
|
+
- **Data attributes in the Kerf UI editor, and `KUI-V015` (KF-65FTKX).** The Inspector's Data attributes section edits a component's `rootAttributes` as Name and Value fields with Add and Remove, so a view document can carry app identity such as `data-band`. View documents carry lowercase `data-*` attributes only: `validateView` reports `KUI-V015` for any other key, and for the reserved `data-kerf-*` (the node marker), `data-key` (the row key), and `data-editor-*` names. `dataAttributeProblem(key)` in `@kerfjs/ui/view` names the problem with one key. A document that set a List's `role` or another non-`data-*` key through `rootAttributes` is now invalid.
|
|
151
|
+
- **A new ScrollEffect starts with one effect in the Kerf UI editor (KF-T3PYVC).** A required list whose placeholder items would all be identical, such as a ScrollEffect's `effects` (three stacked `parallax` layers before), now seeds one item. Lists whose items differ keep three numbered placeholders, so a Select's choices and a PopupMenu's items are unchanged.
|
|
152
|
+
- **A new Kerf UI editor document fills the screen (KF-Z70DBC).** New's root Pane, and a Pane chosen in Replace the root, starts with `fill` on, so a new view fills an app's `.kui-app-root` and play mode instead of ending after its content. Turn `fill` off in Properties for a Pane that should take its content's height.
|
|
153
|
+
- **`Pane` `fill`.** `<Pane fill>` takes the full height of a parent with a definite height (an app's `.kui-app-root`, a `SizedRegion`, a grid cell) or the rest of a flex column, so a one-screen app's root Pane reaches the bottom of the screen with its header and footer pinned and its content scrolling between them, the same way a NavStack view or Workbench region fills its Pane. The default is unchanged: a Pane takes its content's height. `docs/app-layouts.md` now says when to use a filled Pane (one screen that never navigates) and when a one-entry `NavStack` (a screen that pushes views or needs the stack's chrome) (`KF-RMEME0`).
|
|
154
|
+
- **Play mode in the Kerf UI editor.** **Play** in the Canvas toolbar runs the document in a stage that hosts a device-sized frame, scaled down to fit the stage (never up) while its viewport inside stays the device's. The view runs with its real wiring: tabs switch, a NavStack's back pops, and Workbench rails and sidebars collapse, all on a play-time copy. **Done** (or Escape while focus is outside the frame) returns to the editor as it was, and the document never changes. The frame loads the host's own editor page with `?kerf-ui-play`, where `createEditor` returns the player, so hosts need no change (`KF-60BEEJ`).
|
|
155
|
+
- **Play mode devices (KF-R7KXSN).** The play bar picks the device the view runs on: an iPhone SE, iPhone 17, iPhone 17 Pro Max, Android (Pixel 8), three iPads, two MacBooks, a 1080p desktop, or Flexible, with each preset's size and safe areas cited to a published source. Phones and tablets rotate and have an **Installed app** toggle: off, the view runs as a browser tab inside the device's safe areas; on, it fills the device and gets the safe areas through `--kui-safe-area-*` on the play page's `:root`. **Scale** is Fit or a fixed 50–150%, which may overflow and scroll the stage. Flexible takes a typed or dragged width and height. Changing devices resizes the running view without reloading it, and the choice is remembered per browser. Hosts add devices through `createEditor({ devicePresets })` or the Vite plugin's `devicePresets` module.
|
|
156
|
+
- **Play mode subtracts the mobile browsers' toolbars (KF-FNQFPJ).** With Installed app off, each shipped phone and tablet now takes its browser's toolbars from the viewport as well as its safe areas: Safari's bottom address bar and toolbar on iPhone (the default iPhone 17 tab is 402×678, was 402×778), Safari's tab and address bar on iPad, and Chrome's toolbar and gesture bar on Android. The heights are estimates of the toolbars fully expanded. The drawn address bar is now a pill at most 40px tall.
|
|
157
|
+
- **Play mode draws a top browser toolbar (KF-YC59PH).** In a browser tab, iPad Safari, Chrome for Android, and the iPhones in landscape now show the status bar at the device's own safe-area height with an address bar below it, instead of a status bar stretched over the whole top band. iPhone portrait, whose toolbar is at the bottom, is unchanged.
|
|
158
|
+
- **Play mode device frames (KF-E8T0AY).** The played view sits in a generic, unbranded mock device: a phone body with a pill cutout, a punch-hole, or a Home button; a tablet; a laptop with a window title bar; or a monitor on a stand. Phones and tablets get a status bar and a home indicator, and a browser tab gets its address bar where there's room. The play bar's Device frame toggle hides the frame without moving or resizing the view.
|
|
159
|
+
- **Play mode actions and the action log (KF-RF6RCS).** A played view's `$action`s call the host's mock handlers. Register them with `createEditor({ playHandlers })` or the `@kerfjs/ui/vite-editor` plugin's `playHandlers` module. A handler receives `{ action, nodeId, event, params, view }` and can set params (re-rendering the view), push or pop a NavStack through `view.navStack(name)`, or open an overlay. A handler that throws is logged, and the view keeps running. The play bar's Action log button shows a count of unseen actions and opens a list, newest first: each action, its node, the event, and whether a handler ran, was missing, or threw. The log keeps 200 entries and clears each time play mode starts.
|
|
160
|
+
- **Play mode starts each NavStack at its root view (KF-BFE3EC).** A played view opens the way an app launches: every NavStack shows its first view, and a mock handler pushes the rest with `view.navStack(name).push(key)`. A "row opens its detail" flow no longer needs a Back first. The editing canvas still shows the view you're editing.
|
|
161
|
+
- **More components respond in play mode (KF-XV732Q).** Workbench panels and ResizableRegions resize, a SplitView collapses on a compact device and pushes its detail from a list row, and value controls (Switch, Checkbox, RadioGroup, Slider, Select, SegmentedControl, ChoiceChips, Combobox, ColorField, ColorPicker, TagField, Disclosure, and a toggle ListItem) keep the person's change across re-renders: in the play copy, in the `$param` the prop reads, or for one `$each` row. A TabBarItem repeated by `$each` selects for its own row, a tab's close removes it, and a sidebar toggled by several actions responds to each.
|
|
162
|
+
- **Play mode keeps nested controls per row (KF-7XQAFR).** A value control inside an `$each` row, not only the row's own root (a Switch in a repeated Row, for instance), keeps the person's change for its row across re-renders. A repeated tab also closes when its `$each` reads a `$bind` (a param object's array, or an outer row's array) instead of a `$param`: the item leaves the param it comes from.
|
|
163
|
+
- **Play mode keeps a repeat-inside-a-repeat's rows apart (KF-ZMBST3).** An inner `$each` row's play-time state is keyed by its row path (the outer rows' keys, then its own), so two inner rows sharing a key under different outer rows no longer share it. Toggling a Switch on tab `a` in group 2 leaves tab `a` in group 1 alone. A TabBar repeated per group selects within its own group, and a closed selected tab hands its selection to a neighbor in the same group. A keyed ref on an inner template still returns the first row with that key.
|
|
164
|
+
- **Play mode selects and closes a placed tab in its own row's bar (KF-36QBFM).** A tab placed directly in a TabBar that repeats per row (not repeated by the bar's own `$each`) was one node shared by every row's bar: clicking it selected it in every bar and cleared the repeated tabs' selection everywhere, and its close did nothing. It now selects for its own row's bar only, and its close hides it there, handing a selection to the row's next open placed tab.
|
|
165
|
+
- **`Select` and `PopupMenu` take a `popupNote` (KF-59BF6C).** Quiet text at the bottom of the open popup, below the choices, announced as the listbox's or menu's description and never an option or item. It wraps to the choices' width and is drawn from the shared popup contract, so both look the same. A toolbar Select, which has no room for a `hint` below its trigger, can now say what its choices leave out: the editor's play bar uses it for the Device menu's "Touch, pixel density, and the on-screen keyboard aren't emulated."
|
|
166
|
+
- **`ScrollEffect` and the shared scroll-effect layer (KF-YCX1XH).** `@kerfjs/ui/scroll-effect` ties compositor-only effects on any content to its own scroll position, with no scroll listener: `effects` takes `parallax` (`lag`), `reveal`, `fade`, `scale` (`from`/`to`), and `dim` (`to`) presets, each over an `entry`, `exit`, `cover`, or `contain` view-timeline range with optional `rangeStart`/`rangeEnd` percentages, nested in array order so transforms stack and opacities multiply. Out-of-range numbers throw a `RangeError`. Only `transform` and `opacity` animate. The named view timeline, the keyframes, and the static fallbacks (no scroll-driven animation support, reduced motion, `data-kui-effects="static"`, `update: slow`, reduced transparency, increased contrast, forced colors) now live once in `@kerfjs/ui/scroll-effect.css`, and `BackdropImage` runs its parallax, progressive blur, and dim on the same layer with unchanged output; `@kerfjs/ui/backdrop-image.css` imports it. There is no blur preset for arbitrary content (a compositor-only blur needs a second copy of the content) and no IntersectionObserver gating.
|
|
167
|
+
- **Show a NavStack's lower view in the Kerf UI editor.** A NavStack's Flow area lists its views under Shown on the canvas; choosing one previews the stack cut back to it, so that view's nodes can be seen, ringed, and dropped into. The document keeps every view (`KF-RMZ2NP`).
|
|
168
|
+
- **Embed in, in the Kerf UI editor.** The selected node's Embed in menu puts it inside a new container in its place: SizedRegion, ListInsetControl, or ListInsetText where each can hold it, or any container from the Other… dialog. A nested whole-screen layout's hint row offers Embed in SizedRegion, and the canvas no longer draws its own frame around such a layout, so it shows the collapse an app would until it is embedded (`KF-6MGYSG`).
|
|
169
|
+
- **View hints.** `validateView` now returns `hints`, non-blocking advice that never makes a document invalid. The first, `KUI-H001`, flags a `NavStack`, `SplitView`, `TabNavigator`, or `Workbench` below the root with nothing giving it a height and suggests a `SizedRegion`. `kerf-ui-view` prints hints without failing, and the Kerf UI editor lists them under Problems (`KF-KQ72TW`).
|
|
170
|
+
- **`SizedRegion` gives a nested whole-screen layout a height.** `NavStack`, `SplitView`, `TabNavigator`, and `Workbench` have no height of their own and collapsed to their bar below an app's root. Wrap one in `SizedRegion` (`@kerfjs/ui/sized-region`): `height="fill"` (the default) takes the rest of a Pane's content, and `minHeight` alone gives a usable height even in content that sizes to itself. (`KF-63XR5K`).
|
|
171
|
+
- **The Kerf UI editor's canvas shows the tab you are editing.** Selecting a node inside a TabNavigator tab's content previews that tab, so its content, selection ring, and drop targets are visible; the document keeps the tab it opens on (`KF-YZPBFH`).
|
|
172
|
+
- **`Button` and `ToolbarButton` open native popovers.** `popoverTarget` and `popoverTargetAction` (`toggle`, `show`, `hide`) make either one the Popover API's invoker, and `ariaHasPopup` reports the popup it opens; a link `Button` refuses `popoverTarget`. The catalog's popover triggers and the anchored request popup's actions now use them (`KF-PAMQNM`).
|
|
173
|
+
|
|
174
|
+
- **`Text` takes `weight="strong"`.** A title or key phrase that matters more than its neighbors renders inside a `<strong>` element (through every wrap, truncation, and line-cap mode), so view documents and the Kerf UI editor can express it instead of raw `<strong>` markup; the demos and recipes use it (`KF-6A9GJ2`).
|
|
175
|
+
- **`ToolbarButton` in `@kerfjs/ui/toolbar-control-group`.** A ToolbarControlGroup's native `<button type="button">` as a component: icon-only with `ariaLabel`, or labeled, with `action`, `pressed`, `disabled`, `title`, and `selectedChrome="none"`. It renders exactly the button the group already styles, so view documents, the Kerf UI editor, and generated code can place toolbar actions (`KF-5ZEYKP`).
|
|
176
|
+
- **A node's problems in its Inspector in the Kerf UI editor.** The selected node's problems lead its Properties, and a field a problem is about, or that a variant hint names, shows it as its error ("To fix: set "label" or "ariaLabel""). The document is validated once per edit for the canvas, the Problems list, and the Inspector (`KF-H782W9`).
|
|
177
|
+
- **Duplicate, copy, and paste in the Kerf UI editor.** The selected node's heading carries a Duplicate action (or press ⌘D / Ctrl+D) that copies it right after itself; ⌘C and ⌘V (Ctrl+C / Ctrl+V) copy a node and paste it after the selection, or at the end of the selected root's main zone. Copies get fresh ids and numbered names (`folderList2`), each is one undo step, and a paste the document cannot take changes nothing and says why (`KF-QAVK73`).
|
|
178
|
+
- **Promote list and object props to params in the Kerf UI editor.** Promoting a list, object, or record prop (a Select's `choices`) makes a param typed exactly as that prop that keeps its current value as the default, so the application can supply the data (`KF-V9V2B6`).
|
|
179
|
+
- **App-supplied functions and models in view documents.** A param typed `{ "kind": "prop", "component": …, "prop": … }` carries a value a document cannot spell (a Select's `renderSelected`, a SearchField's `model`): the generated module types it from the component (`Parameters<typeof Select>[0]["renderSelected"]`), it is optional exactly when the prop is, and it binds only to that prop. The Kerf UI editor promotes such props to these params and previews them with placeholders; `createEditorCatalog({ placeholders })` adds a host's own (`KF-H3CB2P`).
|
|
180
|
+
- **More props edit in the Kerf UI editor.** A Chip's `children` and a ListHeader's `actionIcon` take text or components, an inline object deep in a config (a pane's `compactChromeOpen`) edits as a form, and a nested `data-*` attribute map edits as JSON. The props catalog now records a text-and-markup union as content and keeps inline object fields five levels deep (`KF-24G2KV`).
|
|
181
|
+
- **Field zones: nodes inside prop values.** A view document's zone key can name a content field inside a prop value (`leftRail.content`, `mainToolbar.title`, `views.0.content`); `validateView`, `interpretView`, and generated modules put its nodes in that field, and `fieldZoneOf` resolves such a key. In the Kerf UI editor a Workbench's rails and drawer, a toolbar's title and slots, and each NavStack view's content now take components from Add a child, the outline, and drag and drop (`KF-PD6QC5`).
|
|
182
|
+
- **Workbench rails and drawers in the Kerf UI editor.** A Workbench's (or WorkbenchDialog's) `leftRail`, `rightRail`, and `bottomDrawer` pick Static panel or Navigation panel, then edit that panel's form; switching keeps the label and size (`KF-907BXY`).
|
|
183
|
+
- **Typed choices in the Kerf UI editor.** Props that take one of several kinds of value (a LucideIcon's `size` as a keyword or a number, a Button's `badge`, a Select's `value`), number or boolean enums (`headingLevel`, `tabIndex`), and optional literals (`selectionMode`) now edit in a Select that keeps the value's type, with a text, number, list, or form control for an open member, instead of a read-only row (`KF-3CKTKN`).
|
|
184
|
+
- **Rounded segmented tab strips.** `TabBar` takes `shape="rounded"` with `presentation="segmented"` to draw the strip at the shared control radius, with every tab concentric inside it, instead of a pill track. The Kerf UI editor's Document and Inspector rail strips use it, as the UX review asked. Segmented strips stay pills by default, and the earlier change that drew every segmented tab as a pill is reverted (`KF-YBD6XJ`).
|
|
185
|
+
- **An outlined, compact PopupMenu trigger.** `PopupMenu` takes `emphasis="secondary"` to outline its button trigger like a secondary `Button`, and `size="compact"` for a compact Button's height, so a menu outside a toolbar (an Add menu in a row of actions) matches the buttons beside it. The Kerf UI editor's list editor uses both for its **Add ▾** menu (`KF-MGKDJC`).
|
|
186
|
+
- **Color fields suggest colors in the Kerf UI editor.** A color prop such as a Pane's `background` or a LucideIcon's `color` now shows a color builder placeholder (`uiColor("surface-raised")`) and hint instead of `px(8)` (`KF-PE0PTT`).
|
|
187
|
+
- **Field editors for your own types in the Kerf UI editor.** `createEditor({ fieldEditors })`, or a `src/kerf-ui-field-editors.ts` module beside `@kerfjs/ui/vite-editor`, registers an editor for a named type (`'ShippingWindow'`, `'ListConfig'`) that replaces the type-driven form wherever a prop or field has that type. Its `render(context)` gets the value, its type, `commit`, preset-button and control attributes, and the type-driven `form()` to compose (`KF-EXA2WH`).
|
|
188
|
+
- **A list editor in the Kerf UI editor.** A list of objects or union items (a Select's `choices`, a PopupMenu's `items`, a NavStack's `views`) now opens as one row per item: choose a row to edit that item's form, remove it, drag or Alt+Shift+Arrow to reorder, and **Add** a new item (or pick the kind from **Add ▾** for a PopupMenu's items, headings, and dividers) (`KF-CY1D5W`).
|
|
189
|
+
- **An icon picker in the Kerf UI editor.** A LucideIcon's `icon` (and any icon-data prop or field) now opens a dialog that searches the Lucide icons and shows them; choosing one sets it, and the canvas updates (`KF-VYRDDQ`).
|
|
190
|
+
- **Inline tag and checkbox editors in the Kerf UI editor.** A list of strings (a TagField's `tags`, a ColumnExplorer's `path`) now edits in a TagField and a set of sides (a Pane's `separators` or `safeAreaEdges`) in a CheckboxGroup, instead of JSON (`KF-A9ZHGW`).
|
|
191
|
+
- **Object forms in the Kerf UI editor.** An object prop (a Workbench's `mainFooterList`, a Pane's `tint`) now opens a form built from its type's fields instead of a JSON textarea. A form of at most 10 fields slides into the Inspector, Back returns, and the canvas updates as you edit; a larger one, such as a Workbench's `mainPane`, opens in a dialog. Nested objects open the same way. **Edit as JSON**, **Reset**, and **Fill with example** remain on every form (`KF-Z9S029`).
|
|
192
|
+
- **The Kerf UI editor's component filter stays put.** The Filter Components field now sits in the Document rail's pinned header, under the tab strip, so it stays in view while the Components list scrolls (`KF-PR8MA6`).
|
|
193
|
+
- **Clearer component groups in the Kerf UI editor.** The Components list titles each category with a default `ListHeader` and spaces the categories apart, as the catalog's sidebar does (`KF-K2VP9A`, `KF-YR81M0`).
|
|
194
|
+
- **Every component renders as added in the Kerf UI editor.** A Workbench, SplitView, TabBar, ToolbarControlGroup, FloatingToolbar, and 18 other components showed "cannot render" when added, because their required zones and content started empty. A new node now gets placeholders for them: the zone's own component where the catalog names one (a TabBar gets a TabBarItem), otherwise a `Text` naming the zone ("Main"). Seeded numbers start at their default or 1 (a Grid's `columns`), icon data names a Lucide icon, and list-or-set unions seed a list. Every placeholder can be changed or removed like any other node (`KF-FGD8B3`).
|
|
195
|
+
- **Filter the Kerf UI editor's components.** The Components area opens with a Filter Components field that narrows the palette to components whose name or category holds the text, with an empty state when nothing matches and a clear button (`KF-Y26SKM`).
|
|
196
|
+
- **Edit sizes in the Kerf UI editor.** A List, Row, or Grid `gap`, a layout `flex`, a Spacer or Skeleton `width`/`height`, and a dialog `height` were read-only in the Inspector because they take either a keyword or a css-values builder. They now get a Select of their keywords (spacing tokens in scale order) plus **Custom…**, which opens a field for a builder call such as `px(12)` (`KF-Q5AXNP`).
|
|
197
|
+
- **Replace the root in the Kerf UI editor.** Selecting a document's root offers Replace the root under Children: pick any component (such as a NavStack or TabNavigator, which fill the view only as the root) to start the document from it. Params, slots, and the name stay, and Undo restores the previous tree (`KF-KWQVDJ`).
|
|
198
|
+
- **Item slots in Kerf UI view documents.** `{ "$slot": "name" }` is now valid at a content field inside a prop value, such as a NavStack view's `content`, a TabNavigator tab's `content`, or a row menu's `icon`. The application fills it like a zone's `$slot`: `validateView` checks it, the contract and generated `<Name>Slots` include it, and generated code and `interpretView` render `slots.name()` in place. The editor seeds one for each such required field of a new node, so NavStack, TabNavigator, ListDetailDialog, and ListActionRow render as soon as they are added, and lists them in the outline under their node (`KF-SXDM56`).
|
|
199
|
+
- **Placeholder lists in the Kerf UI editor.** A Combobox, Select, PopupMenu, or any other component added with a required list or object prop now starts with numbered placeholders ("Suggestion 1", "Choice 1", "Item 1") built from the props catalog, so it renders right away instead of reporting `requires "suggestions"`. The Inspector edits those props as JSON checked against their type, and **Fill with example** restores the placeholder for an unset one (`KF-HNNWN9`).
|
|
200
|
+
- **Tabbed rails in the Kerf UI editor.** The Document rail switches between Outline, Components, and Problems (with a count badge), and the Inspector between a node's Properties, Flow (Show, Otherwise, Repeat, Move to), and Children (Add a child, slots), with segmented tab strips instead of one long list. A newly added node opens on its Properties (`KF-MHY1GB`).
|
|
201
|
+
- **Drag components from the Kerf UI editor's palette.** A Components row drags onto the canvas and drops before, after, or inside a node wherever the validator allows, or into the root when dropped on blank canvas (so an empty document takes its first node); the new node has its required props filled and is selected. A click still shows the component's documentation (`KF-78MHM8`).
|
|
202
|
+
- **`ChoiceChips` `overflow="scroll"` for one-row strips.** A section or filter strip can stay on one row that scrolls sideways inside the group, with no scrollbar, so it never wraps the content below it down. `wireChoiceChips` keeps the checked chip in view (scrolling only the group), `wireScrollDividers` fades each edge with chips past it, and the focus ring is never clipped. It cannot be combined with `maxHeight` (`KF-0Q7Q3D`).
|
|
203
|
+
- **The Kerf UI editor's Inspector keeps its tabs in reach.** A selected node's title and its Properties, Flow, and Children tab strip stay pinned under the Inspector's toolbar while a long form scrolls, with a scroll divider (`KF-5QXNWS`).
|
|
204
|
+
- **Drop palette components on the Kerf UI editor's outline.** A drag rests on the Outline tab to open it, then lands before, after, or inside an outline row with TreeList's own indicator. The Document rail's tab strip is now pinned under its toolbar, with a scroll divider. `@kerfjs/ui/wire-tree-list` adds `treeListExternalDrop(root, { canDrop })` so an application's own pointer drag from outside a TreeList can target its rows (`KF-67K2VP`).
|
|
205
|
+
- **Clearer drag feedback in the Kerf UI editor.** A chip naming the dragged component or node follows the pointer, the drop line or ring carries a caption such as "After folderList" or "Inside Pane › content", and a node moved on the canvas dims in place. A line before the first node no longer disappears on the canvas's clipped top edge (`KF-Y4GHQV`).
|
|
206
|
+
- **Every palette component drags in the Kerf UI editor.** Components with required props the editor cannot fill in yet (Select, PopupMenu, Combobox, CornerStatus, ResizableRegion, ListInsetControl, ChoiceChips, and about 40 others) could not be dropped anywhere, because those unfilled props counted as problems the drop would add. A drop now accepts the new node's own unfilled props, unmatched variants, and empty required zones, as Add a child does, and Problems then asks for them; where the node may go still decides (`KF-DC23E9`).
|
|
207
|
+
- **New in the Kerf UI editor.** The toolbar's New starts an empty document (an empty Pane) with no undo history. With autosave it is a new draft, saved at once, and the previous document stays in its own file (`KF-QSSTMX`).
|
|
208
|
+
- **The Kerf UI editor saves every change.** With `createEditor({ storage })` (both editor hosts pass `devServerStorage()`), each change saves through the dev server about 400 ms after it: to an autosaved draft in the project's self-ignoring `.kerf-ui-editor/drafts/` folder until **Save As…** names a `.kui.json` path inside the project, then to that file. The Preview header shows the file and whether it is saved, saving, or not saved (with the reason), and the editor reopens the last file on the next visit. `@kerfjs/ui/vite-editor` serves the file endpoint (`editorFileMiddleware`), which reads and writes only project `.kui.json` files and refuses writes from other sites. With storage, downloading a copy moves to Export's Document (.kui.json) (`KF-0SY9M6`).
|
|
209
|
+
- **`KUI-V014`: controls inside controls.** `validateView` now reports a control, link, or component that renders one placed at any depth in the zones of a component whose root is a control or link, such as a Button in an actionable ListItem's `trailing`. The browser splits that markup, which used to break the row at render time. A composed `#view` document is checked with the enclosing control in force (`KF-71ATXP`). `eslint-plugin-kerfjs`'s `ui-composition` rule, and so `kerf-ui-doctor`, reports the same placement in JSX as `KUI-L205` (`KF-VTFKX8`). The Kerf UI editor's drops and Move to stop offering those places. Selection catalog entries declare the rules as `content.interactive` (`root` or `contains`, optionally only `whenProps` are set, with per-export `content.exports`), projected into `component-composition.json`; every Kerf UI component that renders a native control, link, or label is classified, plus the interactive Web Awesome elements. Component packages declare the same rules under `composition.content` in `kerf.components.json`, which `create-kerf-component` validates and copies; components without them stay unchecked (`KF-0P9WWB`).
|
|
210
|
+
- **A preview that fails to mount no longer breaks the Kerf UI editor.** The canvas preview is rendered and test-mounted outside the editor's render, so a document whose markup the browser splits (a Button nested in a repeated ListItem's description) shows why it cannot be previewed while the rest of the editor keeps responding (`KF-P6FPG2`).
|
|
211
|
+
- **Drag nodes on the Kerf UI editor's canvas.** Pressing a node or slot placeholder and dragging past a few pixels moves it before, after, or inside the node under the pointer (read along a row's flow when its parent lays out left to right), with a line or ring over the canvas for legal drops only; Escape cancels and the ending click does not reselect (`KF-CWDE93`).
|
|
212
|
+
- **Slots select and move like nodes in the Kerf UI editor.** Clicking a slot's canvas placeholder selects it and rings it, and a selected slot moves with the Inspector toolbar's Move up, Move down, and Delete, or by dragging its outline row; the separate Delete slot button is gone (`KF-5RKX3W`).
|
|
213
|
+
- **Drag-and-drop in `TreeList` and the Kerf UI editor's outline.** TreeList nodes take `draggable`, and `wireTreeList(root, { canDrop, onMove })` lets a row be dragged before, after, or inside another row of its tree, painting a line or ring only for drops `canDrop` accepts. `moveTreeListNode(nodes, move)` applies a move to a plain node tree. The editor's outline drags nodes to legal places (beside a node, slot, repeat, or condition, or into a node's first zone that takes it), and the Inspector's Move to picker moves the selected node to the end of any zone it fits, as the keyboard alternative (`KF-WXP6AB`).
|
|
214
|
+
- **Otherwise branches in the Kerf UI editor.** A conditional node's Otherwise show select puts a component in the `$if`'s `else` branch (or removes it), nodes in either branch edit the shared condition and their own repeat, and removing a two-branch condition keeps both nodes. Nodes under a condition that also repeats are now found for prop edits and bindings (`KF-5S56VQ`).
|
|
215
|
+
- **Richer value editing in the Kerf UI editor.** A css-value prop's field lists the builders the prop accepts and how to compose them (`calc(plus(px(8), space("m")))`), and refuses an outer builder the prop does not take. A text-accepting content prop such as a Button's label switches between text and nodes: Use as nodes moves the text into a text node so components can sit beside it, adding a child does the same first, and Use as text moves a lone text run back (`KF-YR91FA`).
|
|
216
|
+
- **Control flow in the Kerf UI editor.** The Inspector's Control flow section shows a node only while a true/false param or item field holds (`$if`) and repeats it for each item of a list (`$each`, with a suggested item name and row key; renaming the item updates the row's bindings). Add a child also adds a `$slot`, declared when new and, inside a row, given the row item as input; a selected slot binds its inputs and can be deleted. Choices are the sources the validator accepts, the outline shows conditions, repeats, and slots, and every change is undoable (`KF-90GTJN`).
|
|
217
|
+
- **Bind props in the Kerf UI editor.** The editor's Inspector binds a prop to a document param or a field of an enclosing `$each` item, offering only the sources the validator accepts for that prop; Not bound clears a binding, and every change is undoable (`KF-K5TKCV`).
|
|
218
|
+
- **`ColumnExplorer` in `@kerfjs/ui`.** `@kerfjs/ui/column-explorer` browses a hierarchy the macOS column-view way: one column of ListItem rows per level in a ColumnTrack, where choosing a row with children opens the next column, and an optional `preview` column shows a chosen leaf. It reads TreeList's nodes, and the app owns the chosen `path` (`treeListPath(nodes, id)`). `layout="paged"` shows one column per page on a phone. `wireColumnExplorer` (`@kerfjs/ui/wire-column-explorer`) adds per-column keyboard navigation (Up, Down, Home, End, Right to open and enter, Left to return, type-ahead) and brings a newly opened column into view (`KF-JY68DQ`).
|
|
219
|
+
- **Run the Kerf UI editor in your app with `@kerfjs/ui/vite-editor`.** `kerfUiEditor()` serves the editor at `/__kerf-ui-editor/` on your Vite dev server only. It previews Kerf UI's components and those your `.kerf-ui-profile.json` catalogs declare, each through the function its catalog names (app-source components too), with your CSS and aliases. Options: `route`, and `registry` (default `src/kerf-ui-registry.ts`) to add or replace component functions. Adding an app component lists its package in the document's `catalogs` (`KF-6GT5QY`).
|
|
220
|
+
- **`@kerfjs/ui/editor`: the Kerf UI editor as a module.** `createEditor({ catalog, document?, save? })` mounts the editor shell (document rail, preview canvas, editing inspector, undo and redo, open, save, export, and compare). `createEditorCatalog({ props, composition, selection?, components })` combines Kerf UI's catalogs with an application package's, and `componentMap(props, modules)` maps each catalog key to its component function from the modules its `import` fields name. Application components appear under Application in the palette, can be added to legal zones, and a component with no registered function previews as a labeled placeholder. The host loads the global stylesheets plus `@kerfjs/ui/editor.css` and registers `@kerfjs/ui/popup-menu/register` and `@kerfjs/ui/select/register` (`KF-6GT5QY`).
|
|
221
|
+
- **`TreeList` in `@kerfjs/ui`.** `@kerfjs/ui/tree-list` shows a hierarchy as ListItem rows indented by depth, with a disclosure arrow on each row that has children: an ARIA tree whose nodes, expansion, and selection the app owns (`action` chooses, `toggleAction` opens or closes). Nodes take icons, descriptions, trailing content, `disabled`, and `hasChildren` for children loaded on demand. `wireTreeList` (`@kerfjs/ui/wire-tree-list`) adds tree keyboard navigation: arrows, Home and End, Right and Left to open, enter, close, and return to the parent, Enter and Space to choose, and type-ahead. `treeListRows` and `treeListPath` expose the model. The Kerf UI editor's outline is now a TreeList (`KF-ECR4XG`).
|
|
222
|
+
- **`FilePickerTrigger` can look like a Button.** Give it `tone`, `emphasis`, or `size` (the same values as `Button`, with the same defaults) and it draws as a Button of those settings instead of the compact link-toned trigger, so an Open picker matches a Save button beside it. It stays a native file label around the hidden input, and keyboard focus on that input shows the Button's focus ring (`KF-W99E6W`).
|
|
223
|
+
- **App-source components in Kerf UI view tools.** `kerf-ui-props` builds a prop catalog for components that live in an application's source (no package export) from their composition entry's `source` file and the app's `tsconfig.json`, recording root-relative imports. `kerf-ui-view` rewrites those imports relative to each document, so a generated view imports `../src/order-card.js` and compiles against the app's own code (`KF-7JP509`).
|
|
224
|
+
- **`rootAttributes` on 36 more components.** Every Kerf UI component with a single root now takes a `rootAttributes` prop for application `data-*` metadata (a row key, a test hook, the editor's node marker), filtered against the component's own protected markers. Affected components: ChoiceChips, CollapsiblePanel, CollapsiblePanelToggle, Combobox, ContentSwap, CornerStatus, DisclosureArrow, EdgeActivityIndicator, EmptyState, FilePickerTrigger, FileDropZone, FloatingToolbar, ListInsetControl, LoadingSpinner, LucideIcon, NavStack, ResizableRegion, SearchField, SegmentedControl, Select, Skeleton, Spacer, SplitView, SunkenPanel, PopupSurface, TabBar, TabNavigator, TagField, Toolbar, ToolbarControlGroup, ToolbarActionLink, ToolbarText, ValuePreview, ValueTable, ValueTableRow, and Workbench. `component-props.json` records each component's `dataChannel`, and the Kerf UI editor can now name and select nodes of all of them (`KF-PYR8XZ`).
|
|
225
|
+
- **Compare with an existing view module.** The Kerf UI editor's Compare picker reads a `.view.ts` your app already imports and lists the contract changes regenerating would make before you export. `readViewHeader` and `kerfjs/no-generated-view-edits` now also detect an edited `kui-contract` header line, not only an edited body (`KF-9J810J`).
|
|
226
|
+
- **Profiles locate prop catalogs.** A `.kerf-ui-profile.json` catalog entry may declare `props`: the package's `component-props.json` (`schemaVersion` matches `kerf-ui-component-props/v<n>`). The `@kerfjs/ui` defaults declare their own. `kerf-ui-view` now discovers the composition and prop catalogs that the profiles above a document declare, so documents can use a component package's components without `--props` / `--composition` flags; `--no-profile` opts out (`KF-S61KAT`).
|
|
227
|
+
- **`previewView` for editor previews.** `@kerfjs/ui/view` adds a lenient renderer for editors. It skips validation and the contract check, and it renders a caller-supplied placeholder for nodes the caller flags as broken or whose rendering throws, so one bad node never blanks the preview. Applications keep using the strict `interpretView`. The Kerf UI editor now previews documents with problems this way (`KF-F355BF`).
|
|
228
|
+
- **Component packages ship `component-props.json`.** `@kerfjs/ui` adds a `kerf-ui-props --write | --check` bin. It generates a component package's structured prop schema, the same format as Kerf UI's own, from the package's composition catalog and built declarations, plus optional inspector hints. Packages scaffolded by `create-kerf-component` get `props:generate` and `props:check` scripts, with `prepublishOnly` regenerating the file, so Kerf UI view tools can validate, inspect, and generate documents that use their components (`KF-B8TGP4`).
|
|
229
|
+
- **Icons in Kerf UI view documents.** A document places a Lucide icon by name with `{ "$icon": "inbox" }` on `LucideIcon`'s `icon` prop, which `component-props.json` now marks with `iconSource: "lucide"`. `validateView` reports misuse or, given a name list, unknown icons as `KUI-V013`. Generated modules import the icon from `lucide` under a collision-free alias, and `interpretView` resolves it from an `icons` map (`KF-91KCPK`).
|
|
230
|
+
- **`kerfjs/no-generated-view-edits` lint rule.** `eslint-plugin-kerfjs` reports a generated Kerf UI view module (`*.view.ts` / `.view.js` / `.view.d.ts`) whose body no longer matches the digest in its `kerf-ui-view` header, a damaged header, or a hand-written module sitting beside a `.kui.json` document. Regenerate instead of editing; behavior and overrides belong in your own files. It is in `recommended` at `error` and ignores CRLF conversion (`KF-BD3ZHQ`).
|
|
231
|
+
- **`interpretView` for server-driven Kerf UI views.** `@kerfjs/ui/view` renders a `*.kui.json` view document at runtime, with the same output as its generated module, given an explicit component map. It first checks the document's contract digest against the `<name>Contract` your app compiled (from a `--declarations-only` module). A served document that changed inputs, actions, slots, or refs throws `KuiContractMismatch`, or renders your `onMismatch` fallback, instead of silently breaking the client (`KF-5G4CNW`).
|
|
232
|
+
- **`kerf-ui-view` generator for Kerf UI view documents.** `@kerfjs/ui` ships `generateView` and a `kerf-ui-view generate | check | diff` bin. They turn a `*.kui.json` view document into a read-only, deterministic `*.view.ts` module that calls component functions directly (no JSX, no build step). The module exports typed inputs, an exhaustive action-handler interface (row actions get the row key), `SafeHtml` slots, refs resolved through a `data-kerf-node` marker, and a contract digest. `check` fails on stale or hand-edited modules, and `diff` lists breaking and compatible contract changes before you regenerate. `--target js` emits `.view.js` plus `.view.d.ts` for no-build apps (`KF-WWJGSN`).
|
|
233
|
+
- **`@kerfjs/ui/view` document validator.** `validateView` checks a Kerf UI view document (`kerf-ui-document/v1`, the editor's JSON source of truth) against the component-props and composition catalogs. It reports `KUI-V001`–`V012` (shape, unknown components and props, values that don't fit their types or variants, missing required props, ids and names, `$param`/`$bind` scope, keyed `$each`, action scope, strictly parsed `$css` builder calls, node-marker channels, composed views) plus the `KUI-L201`–`L204` composition checks the ESLint rule runs on JSX. `ai/view-document.schema.json` ships for editors, and `component-props.json` now marks text-accepting content (`acceptsText`) and `data-*` index signatures (`index`) (`KF-FB9340`).
|
|
234
|
+
- **Structured component prop schema.** `@kerfjs/ui` ships `ai/component-props.json` (plus its schema), generated from the published declarations and Web Awesome's manifest. It lists every component's props in a small type grammar, with required, documented defaults, enum values in source order, zones and content slots, css-value grammars, and the discriminated variants of union props such as Button's icon-only form and ListHeader's toggle mode. Editors, validators, and code generators can read prop shapes without parsing TypeScript. `npm run props:sync` regenerates it, and the package check fails on drift (`KF-8PXPKW`).
|
|
235
|
+
- **One Kerf UI Sketch Library.** `@kerfjs/ui` ships `docs/design/sketch/Kerf-UI.sketch`, with 308 editable light/dark Symbols covering all 110 design-template variants on one page per family. It includes 141 `Kerf/<Theme>/<Role>` Color Variables and Button's shared styles. Its document, Symbol, Text, and Color Variable IDs stay stable across releases, so linked instances sync while keeping overrides. The six family `.sketch` files become build inputs; install `Kerf-UI.sketch` instead (`KF-WW7BNZ`).
|
|
236
|
+
- **Kerf UI Sketch text names SF Pro.** `Kerf-UI.sketch` used Sketch's nameless system font, which Sketch's Embed Fonts settings reported as three Invalid Font entries. It now names SF Pro's Regular, Medium, and Semibold faces, the font production's `system-ui` uses on macOS, so install Apple's SF Pro fonts before adding the Library (`KF-KFV416`).
|
|
237
|
+
- **Decline setup value proposals.** `kerfjs setup --resolve <id>=skip` remembers an unused dependency, script, compiler option, or catalog/profile value per package. Dry runs expose proposal ids, `=kerf` adopts a declined value later, and new authored conflicts still require an explicit conflict resolution (`KF-0TTETG`).
|
|
238
|
+
- **Stable `StateBanner` root identity.** `rootAttributes` accepts a safe `data-key` so a conditional status banner can disappear before a sibling without replacing the sibling's focused action (`KF-KDF5YG`).
|
|
239
|
+
- **Native drag on `SummaryRow` options.** `draggable` writes the native attribute on the selectable row or board card root, preserving its option semantics and delegated identity across rerenders (`KF-NHPCWZ`).
|
|
240
|
+
- **Static diagnostic `SummaryRow`.** `semanticRole="group"` renders a labeled, non-option list row or board card that retains rail and selected visuals while a nested native recovery action owns focus and activation (`KF-H32FQY`).
|
|
241
|
+
- **Dense-feed media deferral.** `BackdropImage.deferOffscreen` and `ContentItem.media.deferOffscreen` opt into skipping offscreen hero painting while retaining card height and the shared scrollport. The 200-card constrained-CPU feed improved in both desktop and narrow measurements; the default remains unchanged (`KF-J5SAFS`).
|
|
242
|
+
- **`DialogSurface` `closeEmphasis`.** Set it to `quiet` for a smaller, quieter close glyph within the existing 40px native button. Accessible naming, focus, forced colors, and close requests remain intact; `normal` keeps the established default (`KF-GJ4GTJ`).
|
|
243
|
+
- **`Button` `currentStep`.** A setup or progress step can mark its native button or link with `aria-current="step"` through a typed prop, including when disabled, without changing its label or visual state (`KF-TGEW3B`).
|
|
244
|
+
- **`each()` keeps a uniquely keyed row across item-object replacement.** Replacing an item with a new object that renders the same unique `id` or `data-key` now morphs its same-tag row in place, including during a reorder, so live children such as an open popover anchor stay connected. Ambiguous keys and tag changes still replace the row; the per-item HTML cache remains based on object identity (`KF-GS850A`).
|
|
245
|
+
- **Kerf Button in TabBar action zones.** The published TabBar composition contract now accepts one standalone Kerf `Button` in either `trailing` or `end`, alongside the existing `ToolbarControlGroup` and `wa-button` cases. The catalog, doctor, and examples agree with the already supported rendering and fixed action placement (`KF-535H1M`: TabBar Kerf Button composition).
|
|
246
|
+
- **`--kui-color-brand`.** An application sets one opt-in token on `:root` to change its brand: Kerf derives the brand fill (and the quiet and normal fills and borders mixed from it), on-loud text, brand text and links, brand text on brand fills, and the focus ring, clamping lightness so every pair keeps WCAG AA for any hue and chroma; Web Awesome's `--wa-color-brand-*` and `--wa-color-focus` follow. Unset, every brand token keeps its tuned default exactly. Previously an app that overrode only the brand fill kept the default blue brand text and focus ring (`KF-EM1T5S`).
|
|
247
|
+
- **A wrapped `Toolbar` keeps its height beside a long scroller.** In a `List` shell (a filling List holding a `Toolbar` above a `flex` `scrollable` List), a toolbar that wraps or stacks onto two rows at a phone width no longer shrinks to one control band when the scroller below holds a long page, which clipped its second row. A Toolbar in a List no longer shrinks; the app wrapper (`List flex="none"`) is unnecessary (`KF-0A7B8D`).
|
|
248
|
+
- **`wireWorkbench` focuses an overlay opened from an external toggle.** An overlay rail or drawer opened from a persistent toggle outside the Workbench (an app-bar button whose `aria-controls` names the panel) now receives focus once it becomes focusable. Previously the opening `focus()` ran while the app's render had not yet shown the panel, and the only retry waited for the Workbench's own toggle to be removed, so focus stayed on the toggle behind the overlay. Focus the person has moved elsewhere is never taken (`KF-7QMRFN`).
|
|
249
|
+
- **`ToolbarControlGroup` `visibility="yield-to-priority-row"`.** A trailing group yields exactly while its Toolbar's `responsive="trailing-priority"` row is active, from the same container query as the row at the Toolbar's `responsiveAt`, so an app no longer restates that breakpoint with `hideBelow`. `hideBelow` is strict where the Toolbar's widths are inclusive, so at exactly 704px the row was active while `hideBelow={rem(44)}` still showed the group, which wrapped onto a third row. The contract and selection docs now say so (`KF-Y19A2V`).
|
|
250
|
+
- **A `fill` SearchField keeps a `sizing="grow"` group's basis.** Opening a collapsible `fill` SearchField inside a `ToolbarControlGroup` with `sizing="grow"` no longer makes the group take the whole line, which wrapped every sibling group onto a second row at any toolbar width; the grow basis sizes the group, and `fill` fills the group (`KF-3P3GNH`).
|
|
251
|
+
- **`Toolbar` and `List` `id`; `Chip` `rootAttributes`.** `Toolbar` and `List` take an `id`, so a toolbar above a scrolling list can be named as its chrome in `wireScrollDividers({ targets })` instead of falling back to a permanent `dividerSides`. `Chip` takes safe `data-*` `rootAttributes` on its plain, link, and action roots, for tests and delegated handlers; Chip-owned attributes stay protected (`KF-Q2MKX9`).
|
|
252
|
+
- **`DialogSurface` `alert`.** `alert` marks a confirmation before a destructive action as an alert dialog: the native `<dialog>` renders `role="alertdialog"`, described by its message through `describedBy`. A `rootAttributes` role is still ignored. The catalog shows an Alert Dialog example (`KF-Z0EFSY`).
|
|
253
|
+
- **`SegmentedControl` `disabled`.** A group-level `disabled` makes the whole control unavailable: every segment is disabled and dimmed like an author-disabled choice, the current selection stays visible, and the group reports `aria-disabled`. A choice's own `disabled` still disables just that segment, and a disabled control's `placeholder` stays dimmed. The catalog shows a Disabled example (`KF-DJN15J`).
|
|
254
|
+
- **`KUI-L204`: inset-bearing children inside an embedded `Disclosure`.** `kerf-ui-doctor` (through `eslint-plugin-kerfjs`'s `ui-composition` rule) now reports a block `Text`, or any other child whose catalog geometry owns its margin, border, and padding, written directly inside `Disclosure appearance="embedded"`, where it re-adds the 1px border and 8px padding the owner chrome already provides; the message names `Text flush` / `variant="span"` or inline content as the fix. The check is catalog-driven: composition entries declare `insetFreeChildren` (prop conditions under which direct children must be inset-free) and `insetFreeWhen` (a child's inset-free forms), so a third-party catalog can declare the same contract (`KF-E8PGDQ`).
|
|
255
|
+
- **Inset-free metadata in `create-kerf-component`.** A component package's `kerf.components.json` can now declare `composition.insetFreeChildren` (prop conditions under which a container's direct children must bring no content-item inset) and `composition.insetFreeWhen` (a component's own inset-free forms). `kerf-component-catalog` validates each `{ prop, equals }` condition at its exact metadata path, accepting the same shapes as `@kerfjs/ui`'s catalog validator, and copies both fields into the generated `component-composition.json`, so `kerf-ui-doctor` reports `KUI-L204` for a package-declared inset-free container (`KF-3CCTAQ`).
|
|
256
|
+
- **`Button` `fill`.** `fill` spans a Button across its parent's available inline width instead of sizing it to its label, for a full-width primary action in a form, sheet, or narrow column; it is the same `fill` `SplitButton` takes. The icon and label stay centered as one group, the label ellipsizes once the column is narrower than it, a link Button (`href`) fills the same way, and the default outside focus ring and `focusRingInset` keep their geometry. `data-fill` is protected from `rootAttributes`. The catalog's Button demo and design template show a Full-Width Primary Action (`KF-FXKCHW`).
|
|
257
|
+
- **`Disclosure` `appearance="embedded"`.** A Disclosure inside a `ContentItem` (or other chrome that already owns the content-item inset) no longer frames its content twice: `embedded` drops the Disclosure's own 8px inline margin, 1px border, and 8px summary padding, so the summary row and its `DisclosureArrow` sit on the item's content inset, and the summary becomes a compact 24px-minimum row without a hover fill. The native `<details>` state, Enter/Space toggling, and the arrow's rotation are unchanged; the content (a `flush` `Text`) starts on the title's text column 8px below the summary. The UX catalog shows it in a framed ContentItem (`KF-2JTH1A`).
|
|
258
|
+
- **`ListHeader` `wrap`.** A `ListHeader` label is one ellipsized line by default; `wrap` breaks it onto further lines instead, for a heading whose whole label must stay readable in a narrow column. Wrapped lines keep a 4px block inset inside the unchanged minimum height, and `data-wrap` is protected from `rootAttributes` (`KF-12WBGR`).
|
|
259
|
+
- **`openPopupMenuAt` placement.** `openPopupMenuAt(menu, x, y, { placement })` takes an optional `PopupMenuPlacement` for that opening, so a button-triggered menu (a `ListActionRow` trailing menu opened from the row's `contextmenu`) can open `top-start` above the pointer instead of `bottom-start` below it; the viewport flip, shift, and height cap still apply, and the next opening returns to its trigger and its own placement. Omitted, nothing changes: a button-triggered menu opens `bottom-start` at the point and a context menu at its `placement` (`KF-QGT77X`).
|
|
260
|
+
- **`Button` and `SplitButton` `focusRingInset`.** Inside an ancestor that clips overflow, `focusRingInset` draws the focus ring inside the box (each half's, on a SplitButton) instead of 1px outside it, the same option `Select` takes. The inset ring is two-tone, a 3px surface-colored line inside the ring color, so it keeps 3:1 contrast on a loud fill of its own hue (a single-color inset ring measured 1.0:1 on the brand fill); `data-focus-ring-inset` is protected from `rootAttributes`. The default outside ring is unchanged (`KF-BZE90H`). The line paints the surface the control sits on, through a new foundation surface context (`--kui-color-surface-current`, `--kui-color-surface-current-region`, `--kui-color-surface-current-tint`) that `SunkenPanel`, sunken `Disclosure`, `FramedList`, quiet `ContentItem`s, `List` `surface`, `AnchoredSurface`, dialogs, and sunken `Pane`/`Workbench`/`TabNavigator` regions publish on their own elements, so on a lowered or tinted surface it no longer reads as a light halo (`KF-40SSN2`). Highlighted `FramedList` rows, `TabBar` strips, `Pane` and `TabNavigator` app `background` colors, and glass chrome at rest (overlay Pane headers, NavStack chrome and bottom toolbars, TabNavigator bars, floating dialog headers) publish it too (`KF-MWN5CW`).
|
|
261
|
+
- **Dialog accessible descriptions.** `DialogSurface` takes an optional `describedBy` id, rendered as `aria-describedby` on its native `<dialog>`, so a modal dialog can name its heading `ToolbarText`'s `descriptionId` or app-owned summary copy in its body as its accessible description; `rootAttributes` still takes only `data-*` attributes and cannot set it. `WorkbenchDialog` now describes itself by its title `description` automatically (id `<id>-description`) and takes `describedBy` for other content; `ListDetailDialog` takes `describedBy` (its detail description describes the selection, not the dialog). The catalog's Viewport-Bounded Modal and Floating Title Bar dialogs demonstrate it (`KF-JNV47V`).
|
|
262
|
+
- **`CheckboxGroup` in `@kerfjs/ui`.** `@kerfjs/ui/checkbox-group` puts a labeled set of related options in a native fieldset of `Checkbox`es: a `choices` array with per-choice hints and disabled choices, an array `value` of checked values that all submit under `name`, a group `hint` and `error` (marking the group invalid), `default` or `compact` size, and a stacked or wrapping horizontal `orientation`. It is named by `label`, `ariaLabel`, or `labelledBy` and laid out exactly like `RadioGroup`: each box on the inline-start edge, choices at the shared 28px pitch, hints on the label column. `wa-checkbox-group` now points to it (`KF-JJ80V3`).
|
|
263
|
+
- **`SplitButton` `shape`.** `shape="pill"` fully rounds both outer ends of a SplitButton, the same `rounded` (default) or `pill` choice `Button` takes; the divider between the halves stays square, and each half's hover fill and focus ring follow its rounded end (`KF-4GC1J4`).
|
|
264
|
+
- **`wirePaneChrome`.** `@kerfjs/ui/wire-pane-chrome` makes a Pane's open `overlay` compact chrome transient: Escape or a press outside it closes it through the app's `compactChromeOpen` signals, and focus returns to the control that opened it (`KF-EEGAT7`).
|
|
265
|
+
- **ChoiceChips icon picker.** `presentation="icons"` renders square 36px icon-only choices, each named by its label (hidden, and its hover title), and `maxHeight` scrolls a long grid, with native radio (or toggle, or listbox) semantics unchanged (`KF-K60RRM`).
|
|
266
|
+
- **`Pane` `compactChrome`.** A Pane declares what its header and footer do when its container presents compactly: `fixed` (default), `scroll` (inline with the content; a footer settles at the end and scrolls past long content), or `overlay` (over the content on the chrome material, shown while the app's `compactChromeOpen` says so). NavStack views, TabNavigator scenes, full-screen dialogs, and compact Workbenches apply it; roomy containers ignore it. `PaneConfig` forwards both props (`KF-Q8EMWE`). The UX catalog's NavStack Compact Chrome example now pushes a message thread from each row, whose own Pane scrolls its sender line away and keeps its reply hint fixed, so the policy visibly applies per view as the stack pushes and pops (`KF-C891G3`).
|
|
267
|
+
- **Vertical `Slider`.** `orientation="vertical"` stands a Slider up with its minimum at the bottom, `length` tall (default 160px), drawn the same in Chromium, Firefox, and WebKit; the AnchoredSurface media volume popup is vertical again (`KF-SVDPSR`).
|
|
268
|
+
- **`FileDropZone` `dropScope`.** A selector for an enclosing element (an attachments panel) that also takes drops: `wireFilePickers` highlights the zone while files are dragged over any part of it and reports drops there for the zone with `via: 'drop'`, so an app no longer writes the zone's `data-dragging` itself (`KF-HNRWM9`).
|
|
269
|
+
- **`PopupMenu` `triggerContent`.** App content, such as a `Badge` showing a status, can be the whole trigger: Kerf owns the bare button around it (no chrome, a pill focus ring, the pointer cursor, `aria-haspopup`), `label` names it, the caret is off by default, and no help tag repeats the name. Submenus and checked choices work as on any PopupMenu (`KF-PHGQ6D`).
|
|
270
|
+
- **Corner count badges.** `Badge` takes `placement="corner"` to straddle the top-trailing corner of the control it sits in (an icon-only `Button` or a button in a `ToolbarControlGroup`, which positions itself for it). `Button` takes `badge` (a count, short text, or `true` for a dot), `badgeLabel` (added to the button's name; the count stays out of it otherwise), and `badgeTone` (default `danger`) (`KF-WT2EMZ`).
|
|
271
|
+
- **`Text` `size="medium"`.** A heading at the 16px body size keeps its heading weight and wraps, for an in-list group title with a long user-authored name (`KF-43XH56`).
|
|
272
|
+
- **`List` `contentWidth` and `contentAlign`.** A page column caps its content at a readable measure (`compact` 440px, `medium` 640px, `wide` 864px) plus its own insets and centers it (or keeps it at the start), composing with `inset="document"`, so a settings page needs no application `max-width` CSS (`KF-P3069N`).
|
|
273
|
+
- **`Select` `maxTriggerWidth` and `minTriggerWidth`.** Typed `CssLength` bounds on the closed trigger under any presentation (title and inline included). The value or `renderSelected` content ellipsizes inside the cap and the caret stays, so an app no longer wraps a Select in its own sized element (`KF-DQANHZ`).
|
|
274
|
+
- **`LucideIcon` `title`.** An icon takes hover text as an SVG `<title>` over its whole box (not just its strokes), so a labeled status icon carries its own explanation without an application wrapper (`KF-2V9XJQ`).
|
|
275
|
+
- **`Button` `title`.** A Button takes native hover text that says more than its name ("Delete the Selected Draft" on an icon-only Delete). An icon-only Button already shows its `ariaLabel` as a help tag; a `title` replaces that tag (`KF-8MYB8B`).
|
|
276
|
+
- **`WorkbenchDialog` in `@kerfjs/ui`, the modal workbench dialog type.** `@kerfjs/ui/workbench-dialog` renders a header-less modal around a `Workbench`. The work area's toolbar carries the dialog's title, actions, and close control; the side rails keep their own toolbars and run the dialog's full height. On compact devices the dialog fills the screen and its rails become overlays over the work area, shown by their toolbar toggles; with `wireWorkbench`, Escape closes an open rail before the dialog (`KF-Q9ERQ6`).
|
|
277
|
+
- `WorkbenchMainToolbar` gains `end`: groups after a hidden right rail's relocated toggle, so a dialog's close control stays outermost.
|
|
278
|
+
- **`ColorField` in `@kerfjs/ui`.** `@kerfjs/ui/color-field` puts a color in a form or inspector: a label above a trigger that shows the color as a swatch (over a checkerboard) and its hex value, with a hint or error, compact size, and a hidden input under `name`.
|
|
279
|
+
- `wireColorFields(root, { onInput, onChange, pickers })` (`@kerfjs/ui/wire-color-fields`) opens a `ColorPicker` in an `AnchoredSurface` below the trigger, with per-field presets and samples. Edits preview on the trigger at once; Escape or a press outside closes the picker and returns focus.
|
|
280
|
+
- `wa-color-picker` is now `Discouraged` (47 in all), and the profile defaults avoid it (`KF-PZBW7F`).
|
|
281
|
+
- **`ColorPicker` in `@kerfjs/ui`.** `@kerfjs/ui/color-picker` is a full inline picker: a saturation and brightness area, hue and opacity sliders, an RGB/HSL/HSB/Grayscale model menu with channel fields, a hex field (8 digits below full opacity), an opacity field, a screen sampler where the EyeDropper API exists, and optional preset and sample swatches with an "Add to Samples" action.
|
|
282
|
+
- `wireColorPickers(root, { onInput, onChange })` (`@kerfjs/ui/wire-color-pickers`) makes it interactive: pointer drags and arrow keys on the area, native range sliders, field commits, model switching, and swatches.
|
|
283
|
+
- Each change reports `#rrggbb` or `#rrggbbaa` through bubbling `kui-color-input`/`kui-color-change` events and the callbacks, and the picker adopts a new controlled value.
|
|
284
|
+
- Hue survives gray colors, and conversions round-trip without drift (`KF-HBE31H`).
|
|
285
|
+
- **`ColorSwatches` in `@kerfjs/ui`.** `@kerfjs/ui/color-swatches` chooses one color from a fixed palette. It is a native radio group of round swatches with no visible text: one Tab stop, arrow keys to move, and the chosen value submitted under `name`. Each swatch is named by its color label, also shown as its hover hint. The chosen swatch wears a ring in the text color, so the choice never depends on hue. A `'transparent'` swatch offers no color. It has `default` and `compact` sizes, a disabled state, and the shared block-content inset (`KF-E4GC0B`).
|
|
286
|
+
- **`TagField` in `@kerfjs/ui`.** `@kerfjs/ui/tag-field` collects short values as removable tags, each submitted as a hidden input under `name`. It is built on SearchField's token editor in its `form-field` presentation, with a label, a hint or `error`, a tag glyph, a clear button, `max`, and `required`/`disabled`.
|
|
287
|
+
- `wireTagFields(root, { onChange })` (`@kerfjs/ui/wire-tag-fields`) adds a tag on Enter or a delimiter (and several from pasted text), and adds the typed text on Tab or when focus leaves the editor.
|
|
288
|
+
- It enforces duplicates, `max`, and `normalize`, reporting each refusal to `onReject`.
|
|
289
|
+
- Removing: a chip's × or Backspace at the start removes a tag, a chip's label moves it back to edit, and the clear button empties the list.
|
|
290
|
+
- Moving: arrows move between the chips and the editor. A `wireSearchFields` on the same root leaves a TagField's keys to `wireTagFields`.
|
|
291
|
+
- `wa-tag-input` is now `Discouraged` (46 in all), and the profile defaults avoid it (`KF-PZ5J93`).
|
|
292
|
+
- **`Slider` in `@kerfjs/ui`.** `@kerfjs/ui/slider` is a native `<input type="range">` drawn as a track, a brand fill up to the value, and a round thumb, the same in Chromium, Firefox, and WebKit. It has a label row, an optional live readout (`showValue`, `unit`, also spoken as the value text), labeled `ticks`, a `hint`, a `compact` size, and a disabled state. It fills its width on the shared block-content inset. `wireSliders(root)` (`@kerfjs/ui/wire-sliders`) keeps the fill and readout in step with a drag before the app re-renders. `wa-slider` is now `Discouraged` (45 in all), and the profile defaults avoid it (`KF-0R9G4Y`).
|
|
293
|
+
- **`ProgressBar` and `ProgressRing` in `@kerfjs/ui`.**
|
|
294
|
+
- `@kerfjs/ui/progress-bar` is a native `<progress>`. It is determinate (`value` of `max`) or, without a `value`, an indeterminate sweep. A visible `label` names it through `aria-labelledby`, or `ariaLabel` does without one. `showValue` adds a readout, and `valueText` replaces the spoken percentage. It takes brand and status `tone`s and a `compact` 4px track.
|
|
295
|
+
- `@kerfjs/ui/progress-ring` is an SVG `role="progressbar"` in `small`, `medium`, and `large` sizes for a line of text, a row, or a toolbar. It is determinate (filling clockwise from the top) or a spinning arc.
|
|
296
|
+
- Both hold still under reduced motion and draw `Highlight` fills in forced colors.
|
|
297
|
+
- `wa-progress-bar` and `wa-progress-ring` are now `Discouraged` (44 in all), and the profile defaults avoid them (`KF-87B2KV`).
|
|
298
|
+
- **`Disclosure` in `@kerfjs/ui`.** `@kerfjs/ui/disclosure` renders a native `<details>` whose `<summary>` carries a `DisclosureArrow`, a title, and an optional quiet `detail`. It sits on the shared content-item geometry, with `plain`, `framed`, and `sunken` appearances, and Kerf block content lands on the title's text column. Disclosures that share a `name` form a native exclusive accordion. The open state is the platform's: `open` renders it open, a re-render never closes it, and the arrow follows the live state; `toggleAction` names it for a captured `toggle` listener. It neutralizes page-wide `<details>` styling such as Web Awesome's `native.css`. `wa-details`, `wa-accordion`, and `wa-accordion-item` are now `Discouraged` (42 in all), and the profile defaults avoid them (`KF-CXCQE9`).
|
|
299
|
+
- **Styled tooltips for `kerfjs/overlay`'s `tooltip()` in `@kerfjs/ui`.** Import `@kerfjs/ui/overlay-tooltip.css` once. A tooltip on any element then takes the help tag's look (loud neutral fill, on-loud 14px text, 3px radius), wraps at 40 characters, never takes the pointer, fades in on its own, and fades out through `exitClass: 'kui-tooltip-exit'` with `exitDuration: 100`. Reduced motion, the static-effects switch, and forced colors are handled. `wa-tooltip` is now `Discouraged` (39 in all), and the package profile defaults avoid it (`KF-VKDRWA`).
|
|
300
|
+
- **Styled toasts for `kerfjs/overlay`'s `toast()` in `@kerfjs/ui`.** Import `@kerfjs/ui/overlay-toast.css` once. Toasts then stack above the bottom edge, clear of the safe area, at most 480px wide, on the raised surface. They take `variant` tones, take the chrome of a `StateBanner` passed as their only content, rise in on their own, and leave through `exitClass: 'kui-toast-exit'` with `exitDuration: 200`. Reduced motion, the static-effects switch, and forced colors are handled. Put `data-placement="top"` on an app-owned region to stack from the top. `wa-toast` and `wa-toast-item` are now `Discouraged` (38 in all), and the package profile defaults avoid them, so `KUI-L301` reports them (`KF-FYTF2Z`).
|
|
301
|
+
- **`ListDetailDialog` in `@kerfjs/ui`, the modal list-detail dialog type.** `@kerfjs/ui/list-detail-dialog` renders a modal whose list and detail columns each run its full height, so the divider runs from top to bottom. The list column carries its own default-size title and controls (`list.title`, `list.toolbar`). The detail column carries the dialog's primary xl title, its `actions`, and the close control, and each column has a pinned `footer`. Pass `compact` from `deviceClass()` and it becomes a full-screen `NavStack` drill-down (`detailActive`, `backLabel`), keeping the close control on every view. It replaces wrapping a `SplitView` in a `DialogSurface` by hand, whose header spanned both columns. The List-detail dialog recipe and the catalog use it. `SplitViewCompactViewToolbars` now also takes a `footer` (`KF-P9VSX1`, `KF-ZZRDDY`, `KF-HZHG4X`).
|
|
302
|
+
- **Non-selectable rows and a single Tab stop for multi-select `List` and `Grid` in `@kerfjs/ui`.** A non-interactive `ContentItem` with `gridRow` renders `role="row"` around a `gridcell`, with no `aria-selected` and no Tab stop. It holds content between selectable rows, such as an activity group or a "messages skipped" divider, so apps no longer hand-write grid roles. `wireContentItems` now makes each multi-select grid one Tab stop through a roving `tabindex`: the last focused row, else the first selected, else the first enabled. The stop survives re-renders. Arrow keys skip non-selectable rows, whose controls stay reachable by Tab (`KF-RAEXQ7`).
|
|
303
|
+
- **Desktop multi-select for `ChoiceChips`, `List`, and `Grid` in `@kerfjs/ui`.** `ChoiceChips` takes `multiple?: boolean | 'toggle'`. With `multiple: true` the group becomes an ARIA multi-select listbox: a click selects one chip, Cmd (Apple platforms) or Ctrl (elsewhere) toggles one, and Shift extends a range. It is one Tab stop: arrows, Home, and End move the selection, Shift with them extends it, Cmd/Ctrl with them moves focus alone, Space toggles, and Cmd/Ctrl+A selects all. Hidden inputs submit each selected value. Wire it with `wireChoiceChips` (`@kerfjs/ui/wire-choice-chips`), which fires `change` on the group; `readChoiceChips` returns the set. The same model is public as `applySelection`, `selectionGesture`, and `isApplePlatform` (`@kerfjs/ui/selection`) for `List`/`Grid` `selectionMode="multiple"` cards, whose activations carry their modifier keys. Without an anchor, a Shift range starts at the first selected item. **Breaking:** the checkbox behavior that `multiple: true` used to select is now `multiple: 'toggle'` (`KF-346HEG`).
|
|
304
|
+
- **`Catalog` secondary groups can hide tagged entries behind a switch.** `CatalogSecondaryGroup` takes an optional `tagFilter: { tag, label, show }`. It adds a compact `Switch` at the top of the open group, and entries carrying `tag` (plus any section they would leave empty) stay hidden until `show` is true. The active entry is always listed. The app owns `show`, and `wireCatalog` reports the switch through `onToggleSecondaryFilter(show)` (action `catalog-toggle-secondary-filter`, configurable with `toggleSecondaryFilterAction`). The UX catalog uses it to hide `Discouraged` Web Awesome entries by default (`KF-8M9QTZ`).
|
|
305
|
+
- **More Web Awesome elements are `Discouraged` in `@kerfjs/ui`.** A review against what Kerf now provides tags six more elements a Kerf component replaces, and moves `wa-button-group` from conditional to avoid: `wa-popover` and `wa-popup` (use `AnchoredSurface`, or `positionAnchored()` from `kerfjs/overlay`), `wa-callout` (`StateBanner`), `wa-card` (`ContentItem` or `SunkenPanel`), `wa-drawer` (`DialogSurface`'s side or bottom sheet, or `CollapsiblePanel`), and `wa-page` (`Workbench`, `SplitView`, `NavStack`, or `TabNavigator`). 34 elements are now `Discouraged`, and the package profile defaults avoid each new one, so `KUI-L301` reports it. `wa-tooltip`, `wa-toast`, and `wa-toast-item` followed once `@kerfjs/ui/overlay-tooltip.css` and `@kerfjs/ui/overlay-toast.css` shipped. The UX catalog's own demos no longer render `wa-card` (`KF-AJFRTE`).
|
|
306
|
+
- **Web Awesome 3.14 elements in the `@kerfjs/ui` catalog.** The optional Web Awesome peer range is now `^3.14.0` (was `^3.12.0`), and the catalog, the `@kerfjs/ui/webawesome` JSX declarations, and the UX catalog's Web Awesome Integration section cover the three elements 3.14 adds: `wa-stepper` and `wa-step` (a multi-step process indicator) and `wa-tag-input` (a form field that submits a list of tags). No Kerf component replaces them, so they are supported integration elements and `KUI-L301`'s profile defaults are unchanged; `wa-tag-input`'s entry points search filters to `TokenSearchField` (`KF-38B7VP`).
|
|
307
|
+
- **Keyboard multi-selection through `wireContentItems`.** Enter and Space on an interactive `ContentItem` now activate it with a click that carries the key's Shift, Ctrl, and Cmd state (Space uses the state at press), and Ctrl- or Cmd-modified Enter and Space are no longer ignored. One delegated click handler that reads `shiftKey`, `ctrlKey`, and `metaKey` now serves range and toggle selection for keyboard and pointer alike. Alt-modified keys are still left to the platform (`KF-45RNDS`).
|
|
308
|
+
- **Design templates for `@kerfjs/ui`'s native form controls.** `docs/design/templates/` now has light and dark SVG templates for `Button`, `TextField`, `Checkbox`, `RadioGroup`, `Switch`, and `Select`, linked from each catalog detail. `Button` now resets the platform's native button appearance like the other Kerf controls; it renders pixel-identically in Chromium, Firefox, and WebKit, and its templates capture as vectors (`KF-97MFYM`).
|
|
309
|
+
- `kerf-ui-doctor`'s `KUI-D040` title-style check now reads Kerf's native form components: the `label` and `ariaLabel` of `TextField`, `Select`, and `RadioGroup`, `TextField`'s `clearLabel`, and the text of a `Button`. `Checkbox` and `Switch` labels and `RadioGroup` choice labels are option text, which stays sentence style and is not read, as before for `wa-checkbox`, `wa-switch`, and `wa-radio` (`KF-MPXMSX`).
|
|
310
|
+
- **`@kerfjs/ui` guidance treats Web Awesome as an optional integration.** Kerf components and native elements are now the only default answer. The catalog tags the 28 Web Awesome elements a Kerf component replaces `Discouraged` (newly `wa-button`, `wa-input`, `wa-textarea`, `wa-checkbox`, `wa-checkbox-group`, `wa-radio`, `wa-radio-group`, `wa-switch`, `wa-dialog`, `wa-tag`, `wa-badge`, `wa-spinner`, and `wa-skeleton`) and lists all 70 under a collapsed `Web Awesome Integration` sidebar section. The package profile defaults avoid each replaced element, so `KUI-L301` (`ui-preferences`, also run by `kerf-ui-doctor`) reports a raw tag and names its Kerf replacement. The selection guide, AI skill, `llms.txt`, design philosophy, and theme contract no longer send applications to `wa-*` when no Kerf component fits. A new migration guide (`docs/webawesome-migration.md`) maps every replaced element to its Kerf component and lists the steps to remove Web Awesome (`KF-F52B04`).
|
|
311
|
+
- **`@kerfjs/ui` no longer needs Web Awesome anywhere.** `@awesome.me/webawesome` stays an optional peer, and `@kerfjs/ui/webawesome.css` (with the type-only `@kerfjs/ui/webawesome`) is now the only entry that touches it. Every Kerf component stylesheet reads only `--kui-*` tokens (`TokenSearchField`, `Text`'s field label and list-header heading, and `Composer` no longer read `--wa-*` variables, three of them without a fallback). `foundation.css` keeps no `wa-*` selectors, and the two tokens whose standalone fallback differed from the Kerf theme now match it: `--kui-font-weight-semibold` falls back to 500 (was 650) and `--kui-font-sans` to `ui-sans-serif, system-ui, sans-serif`. A Kerf-only application renders exactly like the catalog; consumer-bundle tests and a browser parity spec enforce it (`KF-3558JM`).
|
|
312
|
+
- **`Checkbox`, `RadioGroup`, and `Switch` for `@kerfjs/ui`.** Kerf's own toggles instead of `wa-checkbox`, `wa-radio-group` / `wa-radio`, and `wa-switch`: native inputs inside their labels, drawn as a box, circle, or track that matches the old look in every engine and scheme, with `hint` and `error` text on the label column (the input's or group's `aria-description`; an error sets `aria-invalid`), `disabled`, `name`/`value`/`form`, a delegated `action`, and a default or compact size. `Checkbox` takes `checked`, `required`, and `indeterminate` (`wireCheckboxes(root)` from `@kerfjs/ui/wire-checkboxes` sets the native mixed state); `RadioGroup` is a fieldset named by `label` or `ariaLabel` over a `choices` array (per-choice `hint` and `disabled`), stacked or `orientation="horizontal"`, with `value` and `required`; `Switch` is a `role="switch"` checkbox for settings that apply immediately (`KF-5RCPT6`).
|
|
313
|
+
- **`TextField` for `@kerfjs/ui`.** A text field, Kerf's own instead of `wa-input` and `wa-textarea`: a native `<input>` (or, with `multiline`, a `<textarea>`) inside one labeled box, named by `label` or `ariaLabel`, with a `hint` and an `error` below it (together its `aria-description`; an error sets `aria-invalid` and draws the danger border), a leading `icon`, a `clearable` button, `rows` and an optional growing `maxRows`, a live `maxLength` count (`showCount`), `type`, `required` (with an asterisk), `disabled`, `readOnly`, and `autocomplete`, at the 44px control height or `size="compact"` (33px, with a 16px text floor on touch screens). `wireTextFields(root)` (`@kerfjs/ui/wire-text-fields`) makes the clear button empty the field and announce `input` and `change`, and keeps counts current. It matches the old `wa-input` look in every engine and scheme, and the catalog demos and recipes use it instead of `wa-input` and `wa-textarea` (`KF-1DHMP9`).
|
|
314
|
+
- **`Button` for `@kerfjs/ui`.** A standalone action button, Kerf's own instead of `wa-button`: a native `<button>` (or, with `href`, a link) in a `tone` (`neutral`, `brand`, `danger`) and an `emphasis` (`primary`, `secondary`, `plain`), at the 44px control height or `size="compact"` (33px), with an optional leading `icon`, `loading` (a spinner in place of the label, which still names it, and `aria-busy`), `disabled`, a form `type` (default `button`, which never submits) with `name`, `value`, and `form`, a delegated `action`, and an icon-only square form (no label, `ariaLabel` required). It matches the old `wa-button` look pixel for pixel in Chromium, Firefox, and WebKit, light and dark, follows the shared `--kui-layout-rounded-radius`, and keeps the control band in a `Toolbar` trailing zone and a `TabBar` action zone. The catalog's demos and recipes use it (and plain `<button>`s inside toolbar groups) instead of `wa-button`. Import `@kerfjs/ui/button` and `@kerfjs/ui/button.css` (`KF-9HV3B2`).
|
|
315
|
+
- **Action `Chip`.** `Chip` takes an `action` (with the existing `itemId`), and its whole body then renders as a native `<button type="button" data-action data-item-id>` for an application's delegated handler, such as a filter token in a search syntax help popover that inserts itself into the query. The button keeps Chip geometry and adds hover, press, `:focus-visible`, and `disabled` states; an optional `actionLabel` names it when the visible label alone is unclear. A compact, rounded action chip in a wrapping `Row` inside a compact `ValueTable` cell keeps the row height of the compact `Badge` it replaces, even with Web Awesome's native button styles loaded. `action` cannot be combined with `href` or `removeAction`, at the type level or at runtime, because nested interactive content is invalid. The Chip catalog shows a search filter table, and the new Chip design templates cover tags and action chips.
|
|
316
|
+
|
|
317
|
+
- **`@kerfjs/ui/overlay-sheet.css`.** An opt-in stylesheet for core `kerfjs/overlay` dialogs presented with `presentation: 'bottom-sheet'`, matching `DialogSurface`'s sheet:
|
|
318
|
+
- the bottom edge, full width up to 560px and centered beyond;
|
|
319
|
+
- square bottom corners under the dialog radius;
|
|
320
|
+
- the 8px surface inset, padded by the larger of the safe area and the core's `--kerf-keyboard-inset`;
|
|
321
|
+
- a cap below the top safe area;
|
|
322
|
+
- a slide up as it opens.
|
|
323
|
+
|
|
324
|
+
The `kui-overlay-sheet-exit` class (passed as `exitClass`) slides it back down as it closes. It covers the plain and `native: true` hosts and honors reduced motion, the static-effects switch, and forced colors.
|
|
325
|
+
|
|
326
|
+
- **Resizable core bottom sheets in `@kerfjs/ui`.** `wireOverlaySheets()` (from `@kerfjs/ui/wire-overlay-sheets`) gives a core `kerfjs/overlay` bottom sheet with the `kui-overlay-sheet-resizable` class the grabber of a resizable `DialogSurface` sheet. It resizes the visible height by drag or keyboard (arrows, Page Up/Down, Home, End), between `--kui-overlay-sheet-min-height` (160px) and the cap, and reports the height in its ARIA values. The grabber sticks to the top edge while the content scrolls and stays first across re-renders. Call it once for each container sheets open in. Covered in Chromium, Firefox, and WebKit.
|
|
327
|
+
|
|
328
|
+
- **Tint accents.** A `@kerfjs/ui` `tint` takes an optional `accent`: `{ color, scheme, accent }`. Inside the scope, the brand ramp re-derives from it: loud fills and their on-loud text, brand text and links, text on brand fills, and the focus ring. Lightness is clamped so every pair keeps WCAG AA for any accent; an accent seed sweep checks this in Chromium, Firefox, and WebKit.
|
|
329
|
+
- **`npm run dev:lan` for device checks.** From the repo root or `ui/`, it serves the `@kerfjs/ui` development catalog on every network interface. It prints the LAN and Tailscale URLs and accepts Tailscale MagicDNS (`*.ts.net`) and mDNS (`*.local`) host names, so a phone can test what a desktop browser cannot: the virtual keyboard, safe areas, and touch. Plain `npm run dev` stays on `127.0.0.1`. The catalog page now sets `viewport-fit=cover`, so a notched phone reports its real safe-area insets. The device checks are listed in `ui/docs/manual-test-plan.md`.
|
|
330
|
+
- **Exit motion for `kerfjs/overlay` dialogs.** `overlay()`, `confirm()`, `prompt()`, `form()`, and `choice()` take `exitClass` / `exitDuration`, named and defaulted like `toast()`'s, so CSS can animate an overlay out (for example, slide a bottom sheet down). On `close()` everything else still happens immediately: the result settles, the overlay leaves the stack (an overlay opened during the exit is topmost), a `native` dialog leaves the top layer, the wrapper turns `inert`, and focus returns. Only the node's removal waits, until the exit's CSS animations finish or `exitDuration` passes, whichever is first. `prefers-reduced-motion: reduce` skips the exit. `OverlayHandle.close(result, { instant: true })` (new `OverlayCloseOptions` type) skips the exit or ends one in progress. A second `close()` is still a no-op. Without the new options, behavior is unchanged.
|
|
331
|
+
- **Exit motion for `popover()` and `tooltip()`.** Both take `exitClass` / `exitDuration` and use the same exit as `overlay()`. A popover plays it on `close()` and on an outside-click dismissal, and a tooltip plays it when it hides after `hideDelay`. Teardown when the anchor leaves the document stays instant, and so does the tooltip disposer, which also ends an exit in progress. A tooltip shown again while the previous one is still exiting replaces the leaving node at once, so an anchor never has two tooltips. A popover or tooltip anchored inside an overlay now closes at that overlay's `close()`, instead of lingering until an exiting overlay's node is removed.
|
|
332
|
+
- **Bottom-sheet presentation for `kerfjs/overlay` dialogs.** `overlay()`, `confirm()`, `prompt()`, `form()`, and `choice()` take `presentation: 'bottom-sheet'` (the new `OverlayPresentation` type, named after `DialogSurface`'s prop). The wrapper gets `data-presentation="bottom-sheet"` on both the plain and `native` hosts. While the sheet is open, kerf follows `visualViewport` and publishes the virtual keyboard's overlap as `--kerf-keyboard-inset` on the wrapper. The value is cleared when the keyboard hides, while pinch-zoomed, and on close. kerf still ships no CSS: rest the sheet on the bottom edge and add `max(env(safe-area-inset-bottom), var(--kerf-keyboard-inset, 0px))` to its bottom padding (the API reference has the recipe). The default `'modal'` presentation is unchanged. Covered in Chromium, Firefox, and WebKit.
|
|
333
|
+
- **Media Detail recipe for `@kerfjs/ui`.** `?component=recipe-media-detail` composes an Apple-Music-style album page from components only: `NavStack` clear chrome with the scroll-edge material, a scoped `tint` from the artwork's bottom color, an `underChrome` `BackdropImage` with parallax and progressive blur fading into the tinted surface, and glass control groups. Under clear chrome, a `NavStack`'s own back control now sits in a glass control group, so it stays legible over imagery. The recipe has end-to-end coverage in Chromium, Firefox, and WebKit.
|
|
334
|
+
- **`BackdropImage` runs beneath clear chrome.** `underChrome` pulls the image up beneath the Pane's block-start inset: an overlay or clear header's clearance, NavStack chrome handed to a view's Pane, and the top safe area. Artwork fills the screen behind transparent chrome, as on a media detail page. The visible image keeps its `height` below the chrome and its `overlay` stays clear of it. `Pane` now publishes that inset as `--kui-pane-content-inset-block-start`, beside the inline insets.
|
|
335
|
+
- **Clear chrome for `@kerfjs/ui` layouts.** `Pane` `headerPresentation`, `NavStack` `chromePresentation` and `bottomToolbarPresentation`, and `TabNavigator` `barPresentation` take `clear`: an overlay bar with the same measuring and scroll clearance as `overlay`, but fully transparent, for chrome over imagery whose controls sit in glass `ToolbarControlGroup`s. A clear bar stays clear while content scrolls beneath it. `scrollEdge: 'material' | 'surface'` (on `Pane`, also in `PaneConfig`, and on the two layouts) fades the chrome material or the opaque surface in gradually instead, the iOS scroll-edge effect: fully clear at rest, fully in once content has scrolled `scrollEdgeDistance` pixels (default 60) beneath the bar, and only the backing's opacity changes. `wireScrollDividers` publishes the progress from the scroll it already tracks, so it works in every engine. Clear bars draw no scroll divider, turn opaque under reduced transparency or increased contrast, paint `Canvas` in forced colors, and snap on the scroll state instead of tracking it under the static-effects switch or on a slow-updating display. A `Toolbar`'s leading zone no longer clips the shadow of a glass control group.
|
|
336
|
+
- **Scoped tints for `@kerfjs/ui` layout surfaces.** `Pane` (and `PaneConfig`), `NavStack`, `TabNavigator`, and `TabNavigatorTab` take `tint: { color, scheme }`: an app color, typed with `@kerfjs/ui/css-values`, and the `'light'` or `'dark'` scheme it belongs to. Kerf does no color detection. The region paints the tinted surface, and its surface, raised surface, text, quiet text, link and brand text, quiet fills, chrome material, and popup rows re-derive from the color through `color-mix()` and relative color syntax. Lightness is clamped so text keeps WCAG AA over any color: a seed sweep across hue and lightness holds every text token at 4.5:1 or better in Chromium, Firefox, and WebKit, with and without the Web Awesome theme. The scope sets its `color-scheme` and Web Awesome scheme class, so Web Awesome components inside re-derive too. Under `prefers-contrast: more`, or without relative color syntax, it keeps the plain palette in the declared scheme.
|
|
337
|
+
- `@kerfjs/ui` `DialogSurface` gains `presentation="bottom-sheet"`: a dialog attached to the bottom edge of the screen, with square bottom corners, the top corners on the dialog radius, and a panel that runs behind the home indicator and the virtual keyboard while its content stays above them (the larger of the bottom safe area, the keyboard overlap measured from `visualViewport`, and `env(keyboard-inset-height)`). `height`, `maxHeight`, and the new `minHeight` size its visible height. The new `resizable` prop adds a top grabber, a focusable "Resize sheet" separator you drag or move with the arrow, Page Up/Down, Home, and End keys between `minHeight` and the viewport cap. The sheet slides up when it opens and down when it is dismissed; `enterMotion` / `exitMotion` (`"slide"` or `"standard"`) choose per transition, and reduced motion keeps Web Awesome's own animation. The centered `modal` presentation remains the default. The grabber, keyboard clearance, and slide need `@kerfjs/ui/surface-scaffold/register`.
|
|
338
|
+
|
|
339
|
+
### Changed
|
|
340
|
+
|
|
341
|
+
- **Kerf UI `yield-to-expanded-sibling` works in every Toolbar zone (KF-ZX9Q0X).** A `ToolbarControlGroup` with `visibility="yield-to-expanded-sibling"` now leaves a 480px-or-narrower Toolbar while a group in any of its zones is expanded, not only a trailing sibling. A group that a collapsed Workbench or CollapsiblePanel relocates into the work area's leading zone (`relocateOnCollapse`) therefore gives way to the work area's expanded search, with no need to switch `relocateOnCollapse` on the search state. Groups that don't opt in are unaffected.
|
|
342
|
+
|
|
343
|
+
- **The local demo bundle check matches CI on any Node (KF-J1Z4VA).** Gzip sizes differ across Node majors' zlib, so the check used to pass locally on a newer Node while CI, on the pinned Node 22, measured the same bundle over budget. Off the pinned major, the check and `--update-bundle-budget` now measure under that Node through `npx`. When it can't run, a size within 1.5 kB of its budget fails instead of passing.
|
|
344
|
+
- **Type analysis no longer stalls the editor's server (KF-EQFF9K).** `editorFileMiddleware` (and the `@kerfjs/ui/vite-editor` plugin) runs the project-type service in a worker thread, so other responses, such as a Play page, no longer wait behind TypeScript. Measured on the editor's preview server, the Play page's worst wait during a cold analysis dropped from 976 ms to 2.4 ms. A worker crash fails the requests in flight with a 500, and the next request starts a new worker. The middleware gains `dispose()`, which the plugin calls when its server closes.
|
|
345
|
+
- **A Workbench panel's toggle can name its return while it is an overlay (KF-9H30XE).** `PanelToggle` takes `overlayLabel`, Workbench panels take `overlaid`, and `wireWorkbench` panels take an `overlay` signal it keeps equal to whether the panel presents as an overlay. While the panel is open and overlaid, its toggle shows the label beside its icon and is named by it; otherwise it stays icon-only. The editor's narrow Inspector toggle reads "Preview".
|
|
346
|
+
- **Curated Inspector groups for Web Awesome components (KF-AHW2TM).** The 73 `wa-*` catalog entries now name an Inspector family for each visible prop instead of taking one from the prop's name, so no Web Awesome family shows more than ten fields without task pages. Form fields such as `wa-input`, `wa-textarea`, and `wa-tag-input` split Behavior into TextField's Input, Validation, Typing assistance, and State; `wa-button` uses Button's Form and Link; `wa-popup` splits Layout into Position, Flip, Shift, and Size. `dir` and `lang` move to Accessibility and `did-ssr` to Integration.
|
|
347
|
+
- **Curated Inspector groups across the catalog (KF-DXTRPR).** Every Kerf UI component now names an Inspector family for each visible prop instead of relying on the name-based fallback, and the thirteen older entries that used legacy group names (State, Mode, Surface, …) now use the families. Families that hold several tasks gain subgroups, such as NavStack's Top toolbar and Bottom toolbar, ToolbarControlGroup's Focus and selection, and Checkbox's Form and Validation. Misplaced props move to the family that matches their purpose: NavStack's toolbars go to Layout and its tint to Appearance, Checkbox's `size` goes to Appearance and its `name` and `error` to Behavior, and List's `landmark` and `labelledBy` go to Accessibility.
|
|
348
|
+
- **Shorter field labels under their task (KF-FPSWVF).** On an Inspector task heading or page, a field drops the task's name from its label: Workbench's Main page reads Toolbar and Footer list, and Button's Badge heading reads Max, Label and Tone. Summaries, Bindings rows and search keep the full label.
|
|
349
|
+
- **The narrow Inspector keeps the field being edited (KF-EGNN3J).** `wireWorkbench` panels take `keepFocusedOpen`. When the panel holds focus as its overlay breakpoint begins, it stays open as the overlay, focus and all, instead of collapsing. The Kerf UI editor sets it on the Inspector, so a window that narrows mid-edit keeps the open page, draft, focus, selection and scroll, through 1440 → 960 → 390 → 1440.
|
|
350
|
+
- **Clearer Inspector identity and labels (KF-HP1J4Z).** The Inspector's header names the selected component's type alone, so a long name no longer truncates it (the name stays in Ref name). The unlabeled property count is gone, and Ref name's help shows only until the node has a name. A props overlay entry can set a task-facing `label`: Button's `children` now reads **Button text**, and All properties still finds it by its API name.
|
|
351
|
+
- **Binding and promotion beside each field (KF-FN28S3).** Each Inspector Properties page ends with a **Bindings** row per field, naming what it reads (a param, an item field, or Not bound). The row opens the field's own Bind page, with its Source and **Promote to a param**, and explains in place when no source in scope fits. The overview's separate Promote and Bind sections, each with its own property picker, are gone. Data attributes moved to the Integration page beside Classes.
|
|
352
|
+
- **Properties as a task directory (KF-QWDPM3).** The Inspector's Properties area no longer shows every field at once. It lists the selected node's groups, each summarizing what the node sets and how many fields have problems; a row opens the group as a focused page, and a group of more than ten fields opens its tasks (such as Button's Link or Popup) as further pages. **All properties** searches every field by label, API name, or group.
|
|
353
|
+
- **Consistent Inspector groups (KF-4BPSTB).** The editor's Inspector sorts every component's props into the same families — Content, Appearance, Behavior, Layout, Accessibility, Integration — with component-specific tasks under them (Button's Link, Form and Popup; TextField's Typing assistance; Workbench's Main, rail and drawer regions). The "Other" and "Advanced" sections are gone: uncurated props take a family from their name, and Classes sits in Integration. The props overlay gains an optional `subgroup`; older group names such as `State` still read, as Behavior › State, and a custom catalog's own group names keep their sections.
|
|
354
|
+
- **The Kerf UI editor's view and wiring regions are separate modules (KF-YF1PDR, KF-N0CSVT).** Inspector controls, field editors, Library drag and drop, dialogs, and event handlers now receive typed state from `createEditor`; behavior and public entry points are unchanged.
|
|
355
|
+
- **UI source registration survives tree shaking (KF-TA779Y).** The source PopupMenu registration module is listed as side effectful, so Select's public registration import remains in source-built demos.
|
|
356
|
+
- **Browser waits follow UI state (KF-BG83G7).** Browser suites wait for navigation, animation, and rendered state instead of fixed sleeps, with bounded transition-settling checks.
|
|
357
|
+
- **Five long UI functions now have named phases (KF-70DQG4).** Search-field wiring, scroll-divider control, editor play wiring, project analysis, and UI doctor were split into focused helpers without changing their public behavior.
|
|
358
|
+
- **Workbench resize contract moved to its model folder (KF-8G51WR).** The editor and Workbench now import the shared contract without crossing a component's private `internal/` boundary; the source organization check has no allowlisted edge.
|
|
359
|
+
- **The basic site examples follow the Kerf lint rules (KF-4SA1SM).** They use `attr()` selectors and explicit page-lifetime delegates, and site lint now covers all examples.
|
|
360
|
+
- **CI exercises the published Node 18 floor (KF-Q1S54S).** It installs the packed package into a Node 18 consumer, runs the setup dry run, and checks a server render from `dist/`.
|
|
361
|
+
- **`kerfjs setup` separates detection and apply from planning (KF-Q0WSWJ).** The public CLI behavior and exports are unchanged; the packed package now includes focused `setup/detect.mjs`, `setup/apply.mjs`, and `setup/common.mjs` modules.
|
|
362
|
+
- **`bindList` virtualization uses a tagged height model (KF-BA1DW8).** Fixed, declared, and measured row heights now dispatch through one normalized model instead of nullable flags and unchecked casts; behavior is unchanged.
|
|
363
|
+
- **`kerfjs/jsx-runtime` no longer exports `listSafeHtml` / `granularListSafeHtml` (KF-JYCRRJ).** They were internal helpers for `each()`; they are now `_`-prefixed.
|
|
364
|
+
- **Router edge cases are defined (KF-EE8EPV).** `navigate()` to the URL already showing replaces the history entry instead of pushing a duplicate, and `navigate()` after `dispose()` does nothing.
|
|
365
|
+
- **`kerfjs/scope` reports disposer errors (KF-C0S46R).** `dispose()` still runs every disposer, then reports each error through `reportError` instead of swallowing it.
|
|
366
|
+
- **Overlay `dismiss` / `outsideIgnore` arrays are copied at open (KF-Y56AQD).** Mutating them after opening no longer changes the open overlay.
|
|
367
|
+
- **PopupMenu typeahead matches Select (KF-NF65PK).** Backspace backs up the query in both popups, and neither throws on an item without its label span.
|
|
368
|
+
- **`@kerfjs/ui` CLIs share one argument contract (KF-FSCXYT, KF-7NZM4K).** Every bin prints usage and exits 0 on `--help` / `-h` without doing work (`kerf-ui-analyze --help` used to run an analysis), reports a missing or malformed input as `<bin>: <path>: …` with exit 2 instead of a stack trace, and rejects unknown flags and flags missing a value.
|
|
369
|
+
- **`npm create kerf-component` no longer installs TypeScript (KF-7H7FWV).** It is an optional peer of the `kerf-component-catalog` bin, which the scaffold template and `kerfjs setup --ui` already install.
|
|
370
|
+
- **Release tooling (KF-12QS9G, KF-RV39NE).** Release notes keep their `##` / `###` headings and literal backslashes in the tag message and GitHub Release; `npm run release:beta` continues the highest beta series; `npm run release` refuses a dirty tree, a non-main branch, or an existing tag.
|
|
371
|
+
- **The Kerf UI editor's components moved into an Xcode-style Library popover (KF-Z54E4H).** The Document rail's Components tab is gone; the rail keeps Outline and Problems. The Preview toolbar's **Library** (`+`) button and Shift+Cmd+L (Ctrl+Shift+L elsewhere) open the Library, a `PinnablePopoverSurface` with the same filter, List/Grid view (still remembered per browser), thumbnails, categories, click-to-document, and drag onto the canvas or the Outline. It opens with focus in its filter and closes (Escape, Close, the shortcut, or a press outside) with focus back on the Library button. It is transient: a drag from it steps it aside so the canvas and outline it covered take the drop, a drop closes it, and a drop that finds no place brings it back. Hold Option (Alt) to keep it open, as the drag starts or at the drop; an Option drop that asks where it goes (the "drop where?" menu) brings the Library back once the menu closes. Pin it, or drag its title, to keep it open while you work; the editor remembers whether it was pinned and where. The drag chip now draws over the Library too.
|
|
372
|
+
- **A smaller kerf core (KF-DK0B7T).** Both list reconcilers share one bulk row parse and row-contract diagnosis, `each()` renders rows through one helper, and `mount()` walks for nested mounts more briefly. The main entry drops from 15.30 to 15.11 KB min+gzip with no behavior change, and the size budgets ratchet down to hold the gain.
|
|
373
|
+
- **Kerf UI `TabNavigator` tab badges hide a zero count and cap at `badgeMax` (KF-0V773N).** A tab `badge` of 0 or less now renders no badge (and adds nothing to the tab's name), and a count past the new per-tab `badgeMax` (default 99) shows `99+`, using the same helper as `Button` and `ToolbarButton`. Text is still trimmed and shown as written, and non-finite numbers still render nothing. **Behavior change:** a tab that passed `badge: 0` to show a "0" now shows no badge; pass the text `"0"` to keep it.
|
|
374
|
+
- **Kerf UI `Button` badges hide a zero count and cap at `badgeMax` (KF-78EZ8Q).** A `Button` `badge` of 0 or less, or empty text, now renders no badge, and a count past the new `badgeMax` (default 99) shows `99+`, the same rules as `ToolbarButton` (one shared helper, so they cannot drift). `badgeLabel` joins the button's accessible name only while the badge shows. **Behavior change:** a caller that passes `badge={0}` on purpose to show a "0" now gets no badge; pass the text `"0"` to keep it.
|
|
375
|
+
- **AI guidance stops steering toward Web Awesome.** The Kerf skill and Cursor rules (`kerf-skill-version` 1.29.0 / 1.25.0) name the `scheme` prop and `.kui-*` scopes, scope the `webawesome.css` paragraph to the optional integration, and no longer describe `Select` as Web Awesome markup. The `@kerfjs/ui` catalog guidance sends a plain action to `Button` and an ordinary form field to a multiline `TextField` instead of `wa-button` / `wa-textarea`, and the UI skill (1.71.0) labels its `--wa-*` tips as integration-only (`KF-XNKQPX`).
|
|
376
|
+
- **Kerf stylesheets read only `--kui-*` tokens.** Seven Web Awesome theme values Kerf used directly now have foundation tokens that follow them with the same fallbacks: `--kui-font-3xl`, `--kui-font-weight-bold`, `--kui-font-family-heading`, `--kui-font-weight-heading`, `--kui-line-height-condensed`, `--kui-color-overlay-modal` and `--kui-transition-slow`. Dialog, popup and sheet insets read the new `--kui-surface-inset` (8px) and `--kui-container-inset` (16px) instead of the bridge's `--kui-wa-surface-inset` / `--kui-wa-container-inset`, which now alias them for Web Awesome elements only. Override the `--kui-*` tiers to change Kerf surfaces (`KF-0DZ2V9`).
|
|
377
|
+
- **Raw Web Awesome children in Kerf containers are styled by the optional bridge.** No Kerf component renders a Web Awesome element, so the rules for a raw `wa-button` or `wa-dropdown` inside a ToolbarControlGroup, a Toolbar's trailing zone, a popup surface, a Workbench panel, or a ResizableRegion moved from those components' stylesheets into `@kerfjs/ui/webawesome.css`. A Kerf-only bundle sheds about 1.6 KB gzip of selectors that matched nothing, and the catalog no longer loads Web Awesome for Toolbar, TabBar, SurfaceScaffold, PopupMenu, or the composer-form recipe. An app that places raw Web Awesome elements in those containers imports the bridge, as Web Awesome use already requires (`KF-Z2K3RR`).
|
|
378
|
+
- **`KUI-H001` stays quiet in a filled Pane (KF-AMEZB3).** A `NavStack`, `SplitView`, `TabNavigator`, or `Workbench` in the content of a `Pane` with `fill: true` that itself has a height (the root, or inside a `SizedRegion` or layout) no longer gets the "collapses to its bar" hint, since the filled Pane gives it a height. New's root Pane starts filled, so a layout dropped into a new document is no longer flagged.
|
|
379
|
+
- **A StateBanner's action takes Kerf UI Buttons, laid out as a horizontal list.** Put compact pill `Button`s (`size="compact" shape="pill"`) in `action`. A neutral Button takes the banner's tone: a primary one is the translucent tone pill, a secondary one a tone outline, a plain one tone text. Brand, success, and danger Buttons keep their own tone. The action lays out its controls (several Buttons, a `LoadingSpinner` beside one) as a wrapping, end-aligned row, so no `Row` wrapper is needed. Plain `<button>`s still get the pill. The demos, recipes, and guidance use Buttons, and the editor can build a banner action again (`KF-Q87Q17`, replacing `KF-5TGWQG`'s plain-button contract).
|
|
380
|
+
- **`ToolbarButton` can be an avatar button.** In a `ToolbarControlGroup` with `content="avatar"`, a `ToolbarButton` takes `ariaLabel` alone and shows the group's `avatarImage`; its `icon` is optional for that form (`KF-CFWFAE`).
|
|
381
|
+
|
|
382
|
+
- **Overlay render slots for buttons and errors are typed as `data-*` attributes.** `ConfirmRenderSlots`, `PromptRenderSlots`, `FormRenderSlots` / `FormRenderField`, and `ChoiceRenderSlots` type their `ok`, `cancel`, `error`, and `actions` slots as ``Record<`data-${string}`, string>`` (what they always held), so a component that accepts only data attributes, such as a Kerf UI `Button` or `ToolbarButton` via `rootAttributes`, can carry them. Input slots stay `Record<string, string>`; spreading any slot works as before (`KF-YRC20J`).
|
|
383
|
+
|
|
384
|
+
- **`ListHeader` `badge` and `status` take plain text.** Both accept `string | SafeHtml`; ListHeader still wraps each in its own compact Badge, so `badge="New"` replaces `badge={<span>New</span>}` and the Kerf UI editor edits them as text fields instead of suggesting a Badge inside the Badge (`KF-ZYQVHD`).
|
|
385
|
+
- **Promote an app-supplied prop from its own row in the Kerf UI editor.** A function or model prop such as a Select's `renderSelected` showed as a read-only "—"; its row now says the app supplies it and promotes it to a param when chosen. The Promote and Bind lists name props in words (`KF-D85GY0`).
|
|
386
|
+
- **Item forms keep field order in the Kerf UI editor.** In a form for a list item or object (a Select choice), the Icon row and Configure rows now sit where their fields are instead of after every text field, and picking a choice's icon fills its `iconName` with the icon's name until you give it one of your own (`KF-3J47BY`).
|
|
387
|
+
- **Add a child suggests what a zone holds in the Kerf UI editor.** The Component choice lists the components a zone is named for first, under Suggested (a Button's `icon` offers LucideIcon, a `badge` zone Badge), and starts on that suggestion; the rest follow grouped by the palette's categories instead of one alphabetical list of every component. Changing the zone starts its component choice over (`KF-N8TW04`).
|
|
388
|
+
- **A clearer LucideIcon Inspector in the Kerf UI editor.** A LucideIcon's icon comes first, under Icon with its `name`, then Appearance and Accessibility; Inspector rows keep their prop order instead of listing every icon or Configure row after the text fields. A new LucideIcon's `name` matches its icon, and choosing another icon renames it until you give it a name of your own (one undo restores both). The node's own name field is now "Ref name", so it no longer reads like the `name` prop (`KF-DQFXWG`).
|
|
389
|
+
- **Readable field labels in the Kerf UI editor.** The Inspector labels each prop and form field in sentence case (`controlInsets` reads "Control insets", `hAlign` "Horizontal align", `ariaLabel` "ARIA label") instead of its run-together camelCase name, and Configure and Choose rows name their field the same way (`KF-7M4XQR`).
|
|
390
|
+
- **`wa-tree` and `wa-tree-item` are Discouraged.** They now point at `TreeList` (`@kerfjs/ui/tree-list`), and the default application UI profile's `hierarchy-navigation` preference prefers TreeList, so `KUI-L301` steers a hierarchy to it rather than to an exception for Web Awesome Tree (`KF-QMH4F5`).
|
|
391
|
+
- **Compact toolbar groups use compact text.** A `ToolbarControlGroup` with `size="compact"` now sets the 14px text of a compact `Button` (`--kui-font-s`), so its plain buttons, action links, and PopupMenu triggers match a compact Button beside them; before, they kept the default 16px text at the 32px height (`KF-Z8EYHT`).
|
|
392
|
+
- **`ListHeader` action ends on the list's bordered edge.** A full-width header's fitted trailing action no longer sits 4px inside its header to center its glyph on a Pane toolbar slot; its border box now ends flush at the 8px inline margin, on the same edge as a selected or hovered `ListItem` and a Pane header's trailing `ToolbarControlGroup`. Bordered elements in one column align outer edges; borderless nested glyphs align with nested content (`KF-78N7HE`).
|
|
393
|
+
- **A `Switch` hint sits directly under its label.** The `Switch` hint no longer leaves a 7px gap below the switch row; it sits flush under it on the label's column, the same offset as a `Checkbox` hint or a grouped choice hint, so every toggle control reads alike (`KF-YG5CM2`).
|
|
394
|
+
- **A standalone `Checkbox` hint sits directly under its label.** `Checkbox` hint and error text no longer leave a 7px gap below the label row; they sit flush under it, exactly as a `CheckboxGroup` or `RadioGroup` choice hint does, so a lone Checkbox and a grouped choice read the same (`KF-X8F2K5`).
|
|
395
|
+
- **`ColorPicker` hue track is a fixed rainbow.** In HSL and HSB the hue slider now always paints the full-saturation, full-brightness rainbow instead of the hues at the current saturation and brightness, so a dark or nearly gray color still shows which hue each position picks. Its thumb still shows the current color, every other channel and the opacity track keep their live preview, and the rainbow follows the writing direction like every other track (`KF-2AX5T7`).
|
|
396
|
+
- **Stacked checkboxes and radio choices share one 28px pitch.** `RadioGroup` choices now stack 8px apart (`--kui-space-xs`) instead of 12px, the same 20px-control-plus-8px pitch as standalone `Checkbox`es in a `List gap="xs"`, which the guidance now names as the way to stack them; horizontal groups keep their 24px column gap. This deliberately departs from Web Awesome's radio spacing, so the `@kerfjs/ui/webawesome.css` theme gives stacked `wa-radio`s `0.25em` block margins (the first and last stay flush) and a Web Awesome Radio Group keeps matching Kerf (`KF-9R49CW`).
|
|
397
|
+
- **`ColorPicker` sliders follow the color model.** RGB shows red, green, and blue sliders; HSL hue, saturation, and lightness; HSB hue, saturation, and brightness; Grayscale one gray-level slider; each with the opacity slider when `alpha` is on, and each track previews the colors its channel produces while the others hold. The saturation and brightness area stays in every model. Sliders are named for their channel with unit value text (`210°`, `40%`), and a channel edit keeps every other channel exact, so switching models and editing round-trips without drift (an HSL saturation survives black or white). The fixed `kui-color-picker__hue` class gives way to `kui-color-picker__sliders` and `kui-color-picker__slider`; `COLOR_PICKER_CHANNELS` entries gain `unit`, and `colorPickerSlider()` exposes a slider's state (`KF-ZNKCWX`).
|
|
398
|
+
- `@kerfjs/ui` marks two more Web Awesome elements `Discouraged`, for 36 in total; the profile defaults avoid both, so `KUI-L301` reports them. `wa-include` injects fetched markup outside kerf's `SafeHtml` escaping; fetch with `resource()` from `kerfjs/async` and render Kerf content instead. `wa-scroller` gives way to a `Pane`'s scroll edges or `ColumnTrack` (`KF-F5MPVE`).
|
|
399
|
+
- **Breaking: one `Button` replaces `IconButton` and `IconToggleButton` in `@kerfjs/ui`.** `Button` gains `shape` (`rounded` by default, or `pill`) and `pressed`, which makes any Button a toggle: `aria-pressed` reports the state, and a pressed look draws on top of its tone and emphasis (secondary and plain take the quiet tone fill with a doubled outline; primary darkens with an inset ring). An icon-only button is a `Button` with an `icon` and an `ariaLabel` and no label, and help tags now name it on hover and focus. `IconButton`, `IconToggleButton`, and their subpaths and stylesheets are removed with no aliases; migrate `IconButton({ icon, iconName, label })` to `Button({ icon: <LucideIcon …/>, ariaLabel })`, and `IconToggleButton` to that plus `pressed` (and `shape="pill"` for its former default shape). `kerf-ui-doctor` now checks an icon-only Button's `ariaLabel` capitalization (`KF-TQCJSS`).
|
|
400
|
+
- **Breaking: `Composer` is now `MessageComposer` in `@kerfjs/ui`, and its action row is a `Toolbar`.** The new name says what it is: a composer for messages, prompts, and replies. There are no compatibility aliases: `MessageComposer`, `MessageComposerProps`, `wireMessageComposers`, `@kerfjs/ui/message-composer` (and `.css`), `@kerfjs/ui/wire-message-composers`, and `kui-message-composer*`; the catalog id is `message-composer`. The row below the field is now a compact `Toolbar` footer named "<label> Actions", so every toolbar convention applies: control groups and responsive relocation. A new `leading` prop holds controls such as an attach button or a model `Select`, and the `actions` prop is now `trailing` (`KF-ANFPGA`).
|
|
401
|
+
- **Breaking: `AppTab` is now `TabBarItem` in `@kerfjs/ui`.** The item inside a `TabBar` is named after its container, with no compatibility alias: `TabBarItem`, `TabBarItemProps`, `TabBarItemPresentation`, `TabBarItemSize`, and `TabBarItemNameOverflow`; the subpath `@kerfjs/ui/tab-bar-item` (and `.css`); `kui-tab-bar-item*` classes, `data-component="tab-bar-item"`, and `--kui-tab-bar-item-*` tokens (`KF-HAXNZ8`).
|
|
402
|
+
- **Breaking: `TokenSearchField` is now `SearchField` in `@kerfjs/ui`.** Tokens are optional, and it is Kerf's only search control, so the component and everything named after it lose the `Token` prefix, with no compatibility aliases. Exports: `SearchField`, `wireSearchFields`, `readSearchField`, `placeSearchFieldCaret`, `createSearchFieldModel`, and `SearchField*` types (`SearchFieldToken`, `SearchFieldModel`, `SearchFieldState`, …). Subpaths: `@kerfjs/ui/search-field`, `/search-field-model`, `/wire-search-fields`, `/search-field.css`. Markup: `data-component="search-field"`, `kui-search-field*` classes, `data-search-field-*` attributes, and `--kui-search-field-*` tokens. The catalog id is `search-field` (`KF-TF4N13`).
|
|
403
|
+
- **Breaking (`@kerfjs/ui`, 5.0 beta): `PopupMenu` no longer uses Web Awesome's dropdown.** The menu is now Kerf's own: a native trigger `<button>` and a `role="menu"` panel that opens as a manual popover in the browser top layer. `@kerfjs/ui/popup-menu/register` wires every PopupMenu in the document: opening and placement (flip, shift, and a height cap at the viewport edges), keyboard navigation (arrows, Home/End, typeahead, Enter/Space, ArrowRight/Left for submenus), hover-opened submenus with a pointer safe triangle, outside-press and Escape dismissal, and focus return. Its props are unchanged and it looks the same; menus no longer depend on Web Awesome's prototype patches, and a clipping `ResizableRegion` or `Workbench` panel no longer needs to release its clipping for one. Migration for code that reached into the old markup (`KF-EMJJGV`):
|
|
404
|
+
- Query `.kui-popup-menu` (a `<span>`), `.kui-popup-menu__trigger`, `.kui-popup-menu__menu`, and `.kui-popup-menu__item` instead of `wa-dropdown`, its `[slot="trigger"]` `wa-button`, its shadow `menu` part, and `wa-dropdown-item`. The open state is the trigger's `aria-expanded`, not an `open` attribute; `PopupMenuElement` is now plain `HTMLElement`, so open and close a menu with `openPopupMenu`, `openPopupMenuAt`, and `closePopupMenu`.
|
|
405
|
+
- Delegated `data-action`s run as before. The `wa-select` choice event is now a bubbling, cancelable `kui-menu-select` on the root, with `detail.item`, `detail.value`, and `detail.checked`; `wa-show`, `wa-hide`, and `wa-after-hide` are gone.
|
|
406
|
+
- A checkbox item no longer toggles itself: `detail.checked` is the state it asks for, and the item shows it once the application renders it.
|
|
407
|
+
- Escape closes the current submenu first, then the menu.
|
|
408
|
+
- The register no longer registers `wa-dropdown`, `wa-dropdown-item`, `wa-button`, or `wa-divider`. Import those Web Awesome modules yourself where you render them raw.
|
|
409
|
+
- **Breaking (`@kerfjs/ui`, 5.0 beta): `Select` no longer uses Web Awesome's select.** It renders a `kui-select` root holding a native trigger `<button role="combobox">` and a `role="listbox"` that opens as a manual popover in the browser top layer. `@kerfjs/ui/select/register` defines `kui-select` as a form-associated element (it submits under `name` like a native select, `multiple` values included, and returns to its rendered choice on form reset) and wires every Select: placement below the trigger (flipping above when short, capped at the viewport edges), keyboard navigation with typeahead, choosing, the select-all and clear actions, and dismissal by Escape, Tab, or an outside press. Its props are unchanged and it looks the same, with two deliberate fixes: a `title` Select's caret is no longer clipped, and an `inline` Select's box is 20px tall rather than 23.2px. Migration for code that reached into the old markup (`KF-CF0FEN`):
|
|
410
|
+
- Query `kui-select.kui-select`, `.kui-select__trigger`, `.kui-select__popup`, `.kui-select__listbox`, and `.kui-select__option` (`data-value`, `aria-selected`, `aria-disabled`) instead of `wa-select`, its shadow `combobox` / `listbox` parts, and `wa-option`. The open state is the root's `open` attribute and the trigger's `aria-expanded`.
|
|
411
|
+
- `input` and `change` still bubble from the root, and the root's `value` is the chosen value (an array with `multiple`). `wa-show`, `wa-hide`, `wa-after-show`, and `wa-after-hide` are gone; the select-all and clear actions report a `change` only.
|
|
412
|
+
- The `kui-select--label-hidden` class is gone: an `ariaLabel`-only Select now names its trigger with `aria-label` and renders no label element.
|
|
413
|
+
- The register no longer registers `wa-select`, `wa-option`, or `wa-divider`. Import those Web Awesome modules yourself where you render them raw.
|
|
414
|
+
- **Breaking (`@kerfjs/ui`, 5.0 beta): `DialogSurface` is the dialog itself, a native `<dialog>`, instead of a wrapper around a `wa-dialog` you write.** It renders Kerf's header (title, header actions, and a close button), the body, and an optional footer from props, keeps every size, presentation, inset, height, and floating header or footer prop, and looks the same. Open it with `openDialog(dialog)` and close it with `closeDialog(dialog)`, both from `@kerfjs/ui/surface-scaffold`: it opens modally in the top layer with the page inert and focus on an `autofocus` element or the panel, scales and fades in and out, and returns focus to its opener. The close button, any element inside with `data-dialog-close`, Escape, and (with `lightDismiss`) a press on the backdrop dispatch a cancelable `kui-request-close` (`detail.source`: `close-button`, `escape`, or `backdrop`); cancel it to keep the dialog open, and the panel pulses. The native `close` event fires once it has closed. While open, it measures a floating header or footer, follows a bottom sheet's keyboard and grabber, and keeps that state across application re-renders. It renders the host `kerfjs/overlay` uses for popovers and tooltips opened inside it. The four Web Awesome dialog patches are gone, and `surface-scaffold/register` no longer registers `wa-dialog`. Migration (`KF-JR9YFX`):
|
|
415
|
+
|
|
416
|
+
| Before (`wa-dialog` inside `DialogSurface`) | Now (`DialogSurface` props) |
|
|
417
|
+
| ------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
|
|
418
|
+
| `<wa-dialog label="Edit">` inside `<DialogSurface>` | `<DialogSurface label="Edit">`, with the dialog's content as its children |
|
|
419
|
+
| `id` on the `wa-dialog` | `id` |
|
|
420
|
+
| `slot="label"` content, such as a `ToolbarText` | `heading` (keep `label`, or name it with `labelledBy`) |
|
|
421
|
+
| `slot="header-actions"` content | `headerActions` |
|
|
422
|
+
| `slot="footer"` buttons or `Composer` | `footer` |
|
|
423
|
+
| `without-header`, `light-dismiss` | `withoutHeader`, `lightDismiss` |
|
|
424
|
+
| `dialog.open = true` / `false`, or `open={…}` in the template | `openDialog(dialog)` / `closeDialog(dialog)` |
|
|
425
|
+
| `data-dialog="close"` on a button | `data-dialog-close` |
|
|
426
|
+
| `wa-request-close` (cancelable) | `kui-request-close` (cancelable), `detail.source` |
|
|
427
|
+
| `wa-show`, `wa-after-show`, `wa-hide`, `wa-after-hide` | the native `close` event (after closing); nothing fires on open |
|
|
428
|
+
| `::part(dialog \| header \| body \| footer)` | `.kui-dialog-surface` and its `__header`, `__body`, and `__footer` (configure through props) |
|
|
429
|
+
|
|
430
|
+
A raw `wa-dialog` outside `DialogSurface` keeps Web Awesome's own behavior and the theme in `@kerfjs/ui/webawesome.css`; import its module yourself where you render it.
|
|
431
|
+
|
|
432
|
+
- **Breaking (`@kerfjs/ui`, 5.0 beta): `IconButton` is an icon-only `Button`, not a `wa-button`.** It takes the same `tone`, `emphasis`, and `size` as `Button` instead of Web Awesome's `variant`, `appearance`, and `size` (`variant` → `tone`: `neutral`, `brand`, `danger`; `appearance` `outlined` → `emphasis="secondary"`, `plain` → `emphasis="plain"`; `size` `xs`–`xl` → `default` or `compact`), renders a native `button[data-icon-only]` named by `label`, and needs no Web Awesome registration. The `kui-icon-button` class is gone; select the icon-only button by `.kui-button[data-icon-only]` (`KF-9HV3B2`).
|
|
433
|
+
- A `Composer`'s Enter-to-send treats a send action with `aria-busy="true"` (a busy `Button`) as unavailable, as it already did a disabled or `loading` one (`KF-9HV3B2`).
|
|
434
|
+
- `@kerfjs/ui` help tags (the names icon-only `Select` and `PopupMenu` triggers and icon-only toolbar buttons show on hover and keyboard focus) are Kerf's own element instead of a Web Awesome `wa-tooltip`, and they look and behave the same. `select/register`, `popup-menu/register`, and `help-tags/register` no longer register `wa-tooltip`: import its module yourself where you render one raw. A theme that restyled `wa-tooltip.kui-help-tag` targets `.kui-help-tag` instead (`KF-9VNFSG`).
|
|
435
|
+
- `@kerfjs/ui` no longer patches any Web Awesome internals, so it supports every Web Awesome 3.x from 3.12 (the optional peer range, `^3.12.0`) rather than effectively one exact version. Its CI runs the ui unit and Chromium browser suites against the newest 3.x as well as the 3.12.0 floor, and both pass on 3.14.0 (`KF-F3FY5G`).
|
|
436
|
+
|
|
437
|
+
### Fixed
|
|
438
|
+
|
|
439
|
+
- **The editor Library gives project documents their own mode (KF-BBES58).** A Components/Documents switch separates file navigation from component previews, while document click and drag insertion remain available.
|
|
440
|
+
- **Dragging the editor Library avoids repeated layout reads (KF-382S3P).** The header drag caches its active clamp and writes only position variables on pointer moves, then settles against the live viewport at release.
|
|
441
|
+
- **The editor Library resizes from its bottom edge (KF-K662KK).** A visible bottom grip pins the dialog and changes its height within the viewport, while its results remain scrollable.
|
|
442
|
+
- **Library grid names show an ellipsis when a tile is too narrow (KF-CTVDFT).** Component and document tile labels keep their full accessible names and tooltips while using the Text component's explicit single-line truncation.
|
|
443
|
+
- **The editor Library marks scrolled content with a separator (KF-3T9H48).** Its fixed filter row gains a line only while the results List is scrolled, without moving either row.
|
|
444
|
+
- **The editor Library's scrolling results reach the dialog bottom edge (KF-EHEQVX).** In the fill-last popover layout, the scrollport uses the visible bottom edge while its content retains the normal horizontal inset.
|
|
445
|
+
- **EditorFrame source text now scrolls to the frame edge (KF-4HRCHP).** The framed textarea fills its surface while keeping the 16px text inset, so scrolled source content clips at the visible frame boundary like preview content.
|
|
446
|
+
- **The SegmentedControl catalog variants share one inset (KF-WHB4W7).** The two pill groups no longer receive a second Toolbar inset, so their outer edges line up with the rounded, filled, and standalone examples.
|
|
447
|
+
- **The ValuePreview catalog examples share the page text guide (KF-WY8VWR).** Their panel content now aligns with the example headings and descriptions at wide and narrow widths.
|
|
448
|
+
- **`bindList` honors same-reference `arraySignal.update()` (KF-TMYJ4G).** Content rows refresh inside their existing row element, and element rows receive `update(item)`; all consumers see the new content.
|
|
449
|
+
- **Editor undo and redo discard refused Inspector drafts (KF-0Y88XZ).** When history restores the document, an invalid field value is reset alongside its error so the field displays the document's value.
|
|
450
|
+
- **Release pre-flight refuses stale lockfiles offline (KF-F1CPCK).** Before tagging, it checks each lockstep package's manifest against its `package-lock.json` and prints the packages that need an updated lockfile.
|
|
451
|
+
- **`bindList` snapshot render failures recover before later patches (KF-1267Y6).** A row-render throw during `replace()` or another snapshot pass latches a full reconcile for the next valid source notification.
|
|
452
|
+
- **Virtualized `bindList` freezes a rejected duplicate-key source until a valid update (KF-7HV0MF).** Scroll and measurement frames keep the last accepted window and measured-height baseline instead of re-rendering the invalid array.
|
|
453
|
+
- **Preserved nodes inside an `each()` row keep their text on a granular update (KF-HYAA4T).** The row text fast path skips consumer-injected `data-morph-preserve` nodes, including when their text matches the cell's old value. Morph protection now uses one shared bitmask helper.
|
|
454
|
+
- **Store actions no longer subscribe the code that calls them (KF-1268ZK).** An action's `get()` reads state untracked, so calling a `get()`+`set()` action inside `effect()` or `mount()` no longer throws "Cycle detected" or re-runs the effect in a loop.
|
|
455
|
+
- **`kerf-catalog-demo` runs through its npm bin symlink (KF-88VC6W).** It used to exit 0 without doing anything, so a consumer's `--check` passed vacuously.
|
|
456
|
+
- **TabBar drag state ends when a re-render replaces the dragged tab, and `onFitChange` reports a renamed `data-tab-bar-id` or a bar that returns to the root (KF-XJPZJ3).**
|
|
457
|
+
- **An open Select or PopupMenu keeps keyboard focus when its focused option is removed (KF-XJPZJ3).**
|
|
458
|
+
- **`kerfjs setup` names the file it cannot read (KF-7YHK22).** A malformed manifest, state or profile file is reported by its path, and an unreadable `package.json` is no longer treated as missing.
|
|
459
|
+
- **eslint-plugin-kerfjs UI rules refresh in long-running ESLint servers (KF-RZ2G3A).** They pick up a regenerated `component-composition.json`, an edited `.kerf-ui-profile.json`, or a renamed `package.json`, and stop reporting a stale KUI-L090 once the catalog is fixed.
|
|
460
|
+
- **Example apps (KF-203W27).** cart-htmx no longer interpolates JSON into an HTML attribute string, kanban recovers from `pointercancel`, and the dashboard chart loop stops with its feed.
|
|
461
|
+
- **An open Kerf UI `Combobox` list survives an application render while its field is focused (KF-YA45PW).** `Combobox` renders its list closed, so a render while the person was typing (for example when `suggestions` arrived) wrote `hidden` and `aria-expanded="false"` back and closed the open list, and the new options were never filtered against the typed text. `wireComboboxes` now restores a list it held open after such a render, re-filtered, with the same active option when it is still shown. An unfocused list, or one the person closed with Escape or by leaving the field, stays closed.
|
|
462
|
+
- **The Kerf UI editor's Inspector no longer throws on a `#view` with an array or object param (KF-WDA59Q).** Selecting a `#view` whose composed document declares an array- or object-typed param threw while rendering its JSON field, because the param's type had no text for the field's hint. Each param type now carries its text, so the field reads "JSON for readonly string[]".
|
|
463
|
+
- **A row document with its own repeat previews as a KUI-V016 placeholder (KF-A01VDM).** When a `#view` inside an `$each` row composes a document that has its own top-level `$each`, `previewView` (the Kerf UI editor's canvas and play) now renders the node holding that `$each` as a placeholder whose reason names `KUI-V016`, instead of kerf's generic `each()`-inside-a-row error. The rule is unchanged: validation already reports `KUI-V016` and `interpretView` refuses the document; put the repeat in the composing document.
|
|
464
|
+
- **Extract to document keeps an optional item field optional (KF-JE8KHX).** In the Kerf UI editor, extracting a row that reads an item field the item type does not mark `required` (`subject?: string`) gave the new document a required param, so the composing module passed `message.subject` (possibly `undefined`) to a required input and a strict `tsc` rejected it. View documents now accept `optional: true` on a param with no default: its input is optional, a `#view` may leave it out, and an omitted value reads as absent (no default stands in for it). Extract gives such a field that form, and the editor shows it as not required. `validateView` reports `optional` that is not `true`, or that sits beside a `default`, as `KUI-V001`. The view-document schema and the `ViewDocument` type gain the field. Contracts of documents that do not use it are unchanged.
|
|
465
|
+
- **Embedded `PopoverDialogSurface` and `PinnablePopoverSurface` no longer draw a shadow cut off in a square box (KF-ENXYEB).** With `presentation="embedded"`, in flow on the Kerf UI editor's canvas or in a catalog, they now draw their border without the drop shadow, as an embedded `DialogSurface` does. The scrolling container around them (a Pane's content) had clipped the shadow at its edges.
|
|
466
|
+
- **The Kerf UI editor's play bar no longer clips its Scale Select at a narrow window (KF-MAM4AT).** The device options and Scale now sit with the action log and Done in the play bar's trailing zone, which wraps whole groups, so at 390px they move to a second row instead of running off the edge.
|
|
467
|
+
- **A nested `#view` resolves from the document that contains it (KF-3X7MFF).** When `views/list.kui.json` composed `./rows/row.kui.json` and that row composed `./cell.kui.json`, `kerf-ui-view`, `validateView`, and the editor looked for `views/cell.kui.json`, while the generated row module imports `views/rows/cell.kui.json`. Every `src` now resolves from its own document's folder. `resolveView(src, path)` receives `path`, where `src` points relative to the top document's folder, and the new `composedViewPath(from, src)` from `@kerfjs/ui/view` computes it. A resolver that reads only `src` keeps working for the top document's own `#view`s. Cycles are found by path, so the same `src` in two folders is no longer a false cycle and a `../` loop back is no longer missed. The view bundle budgets rise to 13200 B (`interpretView`, 13069 measured) and 9600 B (`validateView`, 9496 measured).
|
|
468
|
+
- **Kerf UI popups open by the viewport's room in a scrolled page (KF-GRNDW5).** A `Select`, `PopupMenu`, or any popup placed by the shared positioning bounded itself by the document element's client rect, which moves up as the page scrolls. In a page that scrolls its document, a `Select` far down opened on the wrong side and was capped short (to 0px at phone width). Popups are now bounded by the viewport rectangle, so they flip and size by the room around their trigger wherever the page is scrolled.
|
|
469
|
+
- **The Kerf UI editor's drag chip draws over the rails in Safari (KF-23EBGS).** The chip naming what is dragged lived inside the canvas pane, which clipped it in WebKit as soon as the pointer left the canvas, so a palette drag heading for a spring-loaded Document tab or an Outline row showed nothing under the pointer. The chip now sits outside the panes and follows the pointer over the whole editor in every engine.
|
|
470
|
+
- **`delegate()` re-resolves a stopped event object re-dispatched on another path (KF-50DWVS).** The dispatch snapshot now records the propagation path it was taken on. When code stops a dispatch and then re-dispatches the same `Event` object on another target, or after its target moved, later kerf listeners resolve against the new path instead of consuming entries resolved against the first dispatch's DOM. Cost: about 0.03 KB min+gzip.
|
|
471
|
+
- **Kerf UI `TabBar`: intrinsic tabs shrink with an ellipsized name before the strip scrolls (KF-VQ1Z8H).** Each `TabBarItem` in an intrinsic strip used to stay at its full width (`min-width: max-content`), so a narrowing bar only narrowed the tab scroller and cut a tab off mid-word at its edge, with no ellipsis. A tab now gives up width by ellipsizing its name down to a minimum of its chrome plus a few characters, and the strip scrolls only once every tab is at that minimum. Leading, trailing, and end zones still never shrink, and a wide bar where everything fits lays out exactly as before: a name shorter than the minimum never widens. The name now sits in a new `kui-tab-bar-item__label`, which sizes it from a hidden generated copy, so the visible name is still the only accessible name. `wireTabBars` gives a truncated tab its full name as a `title` on hover. `nameOverflow="visible"`, placeholder, icon-only, and fill-allocation tabs keep their previous geometry.
|
|
472
|
+
- **Kerf UI `PagedView` keeps its page when its region resizes (KF-W093WV).** `wirePagedViews` now realigns each viewport to its rendered page whenever the viewport resizes, instead of relying on the browser to re-snap. Before, Firefox could be left between pages after a resizable sidebar widened again, and the offset a resize left could be reported to `onPageChange` as if the person had chosen another page.
|
|
473
|
+
- **Kerf UI editor play mode runs the ContentItem and SummaryRow keyboard (KF-963DMT).** Play now installs `wireContentItems` and `wireSummaryRows`, so a played `List selectionMode` listbox or grid is one Tab stop, the arrows and Home/End move focus, and Enter/Space activate the focused option, sending a ContentItem's `action` to the action log as a shipped app does. Media cards also get their load and tint state. `wireContentItems` is now in the component catalog as optional ContentItem wiring, so catalog tooling knows about it.
|
|
474
|
+
- **Kerf UI `SummaryRow`: the keyboard focus ring is drawn inside the row (KF-Q1F3FH).** A focused row drew an outside 24%-alpha shadow ring, so in a list section its neighbors painted over the top and bottom and the section's rounded clip cut the sides, leaving a faint hairline that hid which row had focus once the arrow keys moved it. Row and card options now draw the standard `--kui-focus-ring` inside their own box (a negative-offset outline on an overlay above the leading rail), so nothing around the row covers it, and the selected fill and border still read apart from focus.
|
|
475
|
+
- **Kerf UI `SummaryRow`: a nested action in the title shows its whole focus ring (KF-ETTYMK).** The title's line clamp clips its overflow at the text, so a focused Button inside `title` (a static `semanticRole="group"` row's recovery action) lost the top and bottom of its ring. The clamp box now carries a focus ring's reach as padding offset by an equal negative margin, so the ring fits inside the clip in every engine while the title's layout, line count, and ellipsis are unchanged.
|
|
476
|
+
- **Kerf UI `Select`: an open listbox keeps keyboard focus through a re-render (KF-VJW4XW).** An application re-render that landed while a Select opened could leave focus on the trigger, where Home, End and the arrows are ignored. Focus that falls back to the trigger or the page now returns to the chosen option; focus moved elsewhere stays where it is.
|
|
477
|
+
- **Kerf UI `SummaryRow` ends a clamped title with an ellipsis (KF-KZNNT2).** A title longer than `titleLines` used to stop at its last visible line with no overflow indicator, so a cut at a word boundary read as a complete title. Row and card titles now clamp with `-webkit-line-clamp` and end the last visible line with an ellipsis, while the floated `trailingMeta` still wraps the first line and inline title content still clamps as one paragraph. The title holds its content in one new `kui-summary-row__title-text` block, because WebKit lifts a float out of a line-clamp box. Do not add a clamp or `text-overflow` in app CSS.
|
|
478
|
+
- **Kerf UI view validator: a prop-typed param outside a node's props no longer names an unrelated component (KF-3624D4).** A `$param` / `$bind` typed as a component prop, used in a `$if` condition, a `#text` value, a `#view` prop, or a `$slot` input, was checked against whichever component the validator had visited last, so its `KUI-V004` named an unrelated component and could change when an unrelated node moved. It now reports `a ‹component› "‹prop›" value fits only that prop, not "‹field›"`, whatever comes before it.
|
|
479
|
+
- **Kerf UI view validator: a mismatch message names field zones instead of quoting their nodes (KF-20GMVX).** A `KUI-V004` for an invalid prop value whose field zones hold nodes (a CollapsiblePanel `toolbar`) now writes each zone as `<zone toolbar.leading>` instead of serializing every node inside it. The message stays readable in the Problems rail and the CLI, and editing inside the zone no longer changes it, so the editor's Move to, drops, and Embed in no longer mistake that edit for a new problem.
|
|
480
|
+
- **Editor: selecting a node in a large document is fast again (KF-SFAA5R).** The Inspector's Move to list validated the whole document once per zone on every selection, so a click cost 617 ms at 300 nodes and 7.1 s at 1000. `moveDestinations` now asks the new scoped move check, `createMoveCheck` from `@kerfjs/ui/view`, which re-checks only the source parent, the target parent, and the moved subtree, and falls back to a full validation where only that can tell. Building the list for a node in a flat 1000-node Pane drops from about 9.5 s to 24 ms in Node; the list itself is unchanged.
|
|
481
|
+
- **Editor: a field-level param can be renamed (KF-5ZMAEM).** A field promoted to a param from an object form's Bind a field (a ContentItem's `media.src`) kept its generated name (`nodeMediaSrc`); the form now shows a **Src param** name field while the field is bound to a param, and renaming it updates the param and every prop and field that uses it, as a bound prop's row already did. The Image-Tinted Feed Cards build names its artwork params `skylineUrl` and `skylineBlurredUrl`.
|
|
482
|
+
- **Editor: Bind a field offers params for the first field of an unset object (KF-PTMNSZ).** Binding a ContentItem's `media.src` while `media` was unset listed no source at all, because the result was still missing the required `alt` and that problem rejected every candidate. Source now judges each candidate with the object's other required fields standing in, so the string params that fit `src` are offered and the ones that do not fit stay out.
|
|
483
|
+
- **Editor: a saved document's bytes no longer depend on edit order (KF-YJFMZY).** Save, autosave, and Export's Document (.kui.json) now write each node's props, and every object inside them, in the component's declared prop order. Before, a field landed where it was first written, so a TextField toggle saved `pressed` before or after `action` depending on which was edited first, and an editor build sample re-saved with a different key order. The committed editor build samples are normalized to that order.
|
|
484
|
+
- **Editor: a selection no longer costs the square of the document (KF-ZW633Z).** The outline asked whether each row could be dragged by cloning the whole document for that row, so one click made one full clone per node (611 clones at 600 nodes). Where every node sits is now read from one walk per document version, and the Embed in options validate the unchanged document once instead of once per container. A selection now makes the same three clones at any size, and its remaining work grows linearly with the document: a click in a flat Pane drops from 100 ms to 34 ms at 300 nodes and from 700 ms to 83 ms at 1000 (Chromium, production build).
|
|
485
|
+
- **`each()`'s duplicate-reference error points at the real cause for an `arraySignal` (KF-7HMTZQ).** An `arraySignal` `push()`, `insert()` or `update()` renders through the granular path, which skips the O(N) duplicate check, so the error fired on a later, unrelated render and seemed to blame it. The message now names both indices (`first at index 0, again at index 1`) and, for an `arraySignal`, says the duplicate was most likely added by an earlier mutation. Detection itself is unchanged: an early check would cost O(N) per insert.
|
|
486
|
+
- **A click during a NavStack pop reaches the revealed view (KF-SBP2MV).** While a popped view slid out, it sat over the revealed view and took the pointer, so a click on the revealed view in that moment hit the outgoing copy and did nothing (the Kerf UI editor's Inspector dropped a Configure click right after Back). The exiting view is now `inert` and ignores pointer events for the duration of the slide.
|
|
487
|
+
- **A re-pointed input's `change` fires in WebKit (KF-FMGEJ6).** When a re-render changed a text input's `value` attribute, WebKit kept the value the input was created with as its `change` baseline, so typing that earlier value back fired no `change` (the Kerf UI editor's Inspector lost such commits in Safari). The morph, fine-grained bindings, and the keyed-list attribute fast path now write the live property before the attribute. The end state is unchanged in every engine.
|
|
488
|
+
- **Per-axis gaps in the Kerf UI editor (KF-VA14AP).** A List, Row, or Grid `gap` could hold `{ column, row }` only as JSON after it already held one, so per-axis gaps could not be started. Its size Select now offers **Columns and rows…**, which edits each axis in its own size Select (keywords or Custom…). `validateView` also rejected a token on an axis (`{ column: 'none', row: 'm' }`, `KUI-V004`), because `component-props.json` recorded each axis as a builder-only css-value. A css-values alias that also takes token names now keeps them as literals.
|
|
489
|
+
- **The Kerf UI editor names unnamed object members by what sets them apart (KF-BT1YG0).** A union of object shapes with no type name or literal tag, such as SearchField's `trailingAction` (a disclosure with `expanded`, or a toggle with `pressed`), read "Custom 1…" and "Custom 2…" in the Inspector's type Select. Each member is now named after the fields only it allows: "With expanded…" and "With pressed…".
|
|
490
|
+
- **Badge `ariaHidden` is a switch in the Kerf UI editor (KF-AYX1G2).** `component-props.json` recorded the prop as a `boolean | false | true` union because Badge's labeled and hidden variants narrow it to `false` and `true`, so the Inspector offered a two-item Select. A prop whose variant types are `boolean` and boolean literals now merges into one `boolean`.
|
|
491
|
+
- **The Kerf UI editor names components as authors write them.** The palette, Add a child list, outline and Inspector named an entry's primary component after its catalog title, so `DialogSurface` read "Surface Scaffolds" and `FilePickerTrigger` read "FilePicker". Every component now shows its export name (`KF-9DA687`).
|
|
492
|
+
- **A TabBarItem can be made non-closable in the Kerf UI editor.** `closable` defaults to `true` but did not say so, so `component-props.json` recorded no default and the editor's switch could not write `false`. Its JSDoc now states the default (`KF-X2E1B1`).
|
|
493
|
+
- **Multi-line text props hold line breaks in the Kerf UI editor.** The props overlay's `textarea` control (EmptyState and StateBanner `detail`, Text `children`) was ignored, so every string prop was a single-line field that Enter committed. Those props now edit in a multi-line field that commits on change, and ValuePreview `value` is one of them. TextField's end `toggle` now also works on a multi-line field, pinned to its top end, so an optional multi-line prop keeps its Not set toggle (`KF-8FCJ02`).
|
|
494
|
+
- **A ListActionRow can be an unpressed toggle in the Kerf UI editor.** Its `pressed` edited as a switch, which clears the prop when off, so the editor could not write `pressed: false` (`aria-pressed="false"`). It now has the same Not set / Off / On Select as `Button`, `ListItem`, and `ToolbarButton` (`KF-3T47XJ`).
|
|
495
|
+
- **A ToolbarControlGroup in a MessageComposer's leading zone validates.** MessageComposer draws its controls in a compact Toolbar, and its docs place leading controls in a `ToolbarControlGroup`, but the composition rules allowed a group only in Toolbar, FloatingToolbar or TabBar. So `validateView` reported `KUI-L201` for that documented composition. MessageComposer is now a listed parent (`KF-K1HFS2`).
|
|
496
|
+
- **Default-on boolean props can be turned off in the Kerf UI editor.** `component-props.json` read a default only from a backticked phrasing, so props documented as "(default true)" or "Defaults to true." (Select and PopupMenu `caret`, ColorField and ColorPicker `alpha`, ColorPicker `eyedropper`, BackdropImage `bleedInline`, ToolbarText `ellipsis`) had no default. The editor showed their switch off and could not write `false`. Unquoted `true`/`false` defaults are now read, and Select's `caret` doc states its default (`KF-YNEMFD`).
|
|
497
|
+
- **Turning `multiple` on or off reshapes a Select or ChoiceChips value in the Kerf UI editor.** A picked value became the wrong shape when `multiple` changed. Now one value becomes a one-entry list and a list keeps its first entry, in the same undo step. Renaming a choice's value also renames it inside a list value (`KF-E3MN4B`).
|
|
498
|
+
- **A prop typed with a lone `true` or `false` no longer offers the other boolean.** `component-props.json` folded any boolean literal in a union into `boolean`, so the Kerf UI editor offered `false` for Button's `badge` (`string | number | true`) and `true` for Combobox's `createLabel` (`string | false`). A lone literal now stays a `literal` member (`KF-FY62FK`).
|
|
499
|
+
- **The Kerf UI editor picks several values for an array `value`.** A CheckboxGroup's value, and a ChoiceChips value once `multiple` is on, now get a checkbox per choice instead of a single-choice Select that wrote one string of the wrong type; none checked is `[]`. A required string value (SegmentedControl) can also be set to `Empty ("")` for its no-selection state (`KF-8MEWP2`).
|
|
500
|
+
- **A TextField's spell checking can be turned off in the Kerf UI editor.** Browsers check spelling when `spellcheck` is unset, and the Inspector's switch cleared the prop when turned off, so `spellcheck: false` couldn't be written. It now edits as a Not set / Off / On select, as a toggle's `pressed` does (`KF-38KD5N`).
|
|
501
|
+
- **"Add to …" in a nested form adds to that field in the Kerf UI editor.** A content field inside an object prop that was not yet set, such as a SplitView's Compact stack › List › Toolbar › Trailing, wasn't treated as a zone of the node. So **Add to trailing** said "Every zone of this component is full" or put the child in another zone (`compactStack.backIcon`), which left the document invalid. The field's form now adds to the field itself (`KF-KAVBDD`).
|
|
502
|
+
- **An empty Toolbar's zones stay apart on the Kerf UI editor canvas.** In a narrow column, such as a SplitView's list, the Leading, Center, and Trailing placeholders each kept a 160px minimum and drew over one another, so a drop aimed at Leading landed in Center. A placeholder now never grows past its zone, so each zone is its own drop target (`KF-K3EKKF`).
|
|
503
|
+
- **Embed in no longer writes an empty `props` object in the Kerf UI editor.** A container with no props of its own, embedded through Flow › Embed in (a List or a ContentItem from Other…), exported as `"props": {}`; it now has no `props` key, as when it is dropped from the palette (`KF-QX497W`).
|
|
504
|
+
- **A Workbench panel's nested forms open in the Kerf UI editor.** In a static or navigation panel's form (a rail or the bottom drawer), Configure toolbar, Configure pane, and the other nested object rows did nothing; the type at a path inside a union-typed prop now follows the member the value holds, so those forms open and their fields write inside the panel (`KF-EZN7H2`).
|
|
505
|
+
- **A `$bind` into a param with a default uses the default (KF-8P3H7F).** `{ "$bind": "data.tabs" }` over a `data` param with a default read the raw input, so an app that omitted the optional `data` (and the editor canvas, which samples only params without a default) threw "Cannot read properties of undefined" in `interpretView`, `previewView`, and the generated view module. A `$bind` path now starts from the param read the way `$param` reads it, `(inputs.data ?? <default>)`, in the interpreter and the generator alike; `null` takes the default too.
|
|
506
|
+
- **A repeat inside a repeat's row renders (KF-CFA1S1).** An `$each` inside another `$each`'s template, such as a TabBar per group repeating `group.tabs`, threw in `interpretView`, `previewView`, and the generated view module, because kerf refuses a keyed `each()` inside a row render; the editor canvas showed "This document cannot be previewed". The inner repeat now renders as a plain `.map()` that re-renders with its row, in the interpreter and the generator alike, and its rows still carry `data-key`. A `#view` in an `$each` row whose document has its own top-level `$each` cannot work that way (its module can't know it is in a row), so `validateView` reports it as the new `KUI-V016`.
|
|
507
|
+
- **Icon-only buttons look complete on the Kerf UI editor canvas.** A Button or ToolbarButton with an icon and no text showed a full "is empty — drag a component here" stand-in that swamped its toolbar; a node holding something in another zone now shows its main-zone stand-in only while it is selected (`KF-6EV4Q5`).
|
|
508
|
+
- **Toolbar controls in a view's toolbar validate.** A `ToolbarControlGroup` in a NavStack view's (or a Pane's or Workbench's) toolbar config renders inside that Toolbar, but `validateView` reported `KUI-L201` for it and the editor showed the layout as unable to render. Composition entries can now name the config types they render (`configTypes`), and a content field inside one is placed in that component (`KF-THTR71`).
|
|
509
|
+
- **The Kerf UI editor's selection ring no longer marks the wrong content.** Selecting a node in an inactive tab drew the ring over the active tab's content at the same place; the ring now hides while the selected node can't be seen (`KF-ZC9EXM`).
|
|
510
|
+
- **The Kerf UI editor recognizes a dot-badge tab.** A TabNavigator tab with `badge: true` was listed as a count-badge tab and edited with the count form; a union member whose literal the value carries now wins over an earlier member that only tolerates it (`KF-2XH5XS`).
|
|
511
|
+
- **A list item's typed choice takes an open value in the Kerf UI editor.** Picking Number… or Text… for a field such as a tab's badge in a Configure dialog used to change nothing; it now sets the value and shows its control, as a typed choice in the Inspector does (`KF-ZAQQFK`).
|
|
512
|
+
- **Drop into a tab's content on the Kerf UI editor canvas.** A selected node's seeded item slots (a TabNavigator tab's or NavStack view's content) show as drop stand-ins named after the slot, and a drop there fills the content. Before, the canvas showed only the slot's name, and a drop into its field zone was refused (`KF-HGG7MJ`).
|
|
513
|
+
|
|
514
|
+
- **The Kerf UI editor's outline keeps a node's item content in item order.** A filled field zone (tab 1's content) is listed among the remaining item slots in tab order, rather than after them (`KF-KA5B40`).
|
|
515
|
+
|
|
516
|
+
- **The Kerf UI editor can make an unpressed toggle.** `pressed` on `Button`, `ListItem`, and `ToolbarButton` edits with a Not set / Off / On Select instead of a switch, because unset means a plain action and `false` means a toggle that is off (`aria-pressed="false"`). Off now writes `pressed: false` (`KF-K9VBB4`).
|
|
517
|
+
- **Turning a switch off in the Kerf UI editor clears its prop.** An optional boolean switched back to its default (`showValue` off) no longer leaves `showValue: false` in the document; a prop that defaults on still records `false` (`KF-K03GBN`).
|
|
518
|
+
|
|
519
|
+
- **The UI evaluator names a failed screenshot capture.** When a full-page capture fails after a context's checks ran, `KUI-B001` now says the screenshot could not be captured and suggests a longer timeout, instead of telling you to check that the app is running (`KF-G8KKNY`).
|
|
520
|
+
|
|
521
|
+
- **Kerf UI editor zone labels count items from 1.** A field zone read `views › 0 › content` while the item slot it replaces, and the `View 1` row that edits it, counted from 1; zone labels now read `views › 1 › content` too (the document keeps its 0-based `views.0.content` key) (`KF-3N67HR`).
|
|
522
|
+
- **The Kerf UI editor icon picker shows each Lucide icon once, by its own name.** Lucide exports 255 aliases (`ArrowDownAz` for `ArrowDownAZ`, `Filter` for `Funnel`), which showed as duplicate tiles, and `ArrowDownAZ` was named `arrowDownAZ`; the picker now offers one tile per icon under Lucide's canonical name (`arrow-down-a-z`, `funnel`) while an alias still finds it in a search (`KF-NTK7YW`).
|
|
523
|
+
- **Clearing a Kerf UI editor field commits in Safari.** When a node's problems appeared above its Inspector controls, the re-render turned one prop's input into another's; WebKit then fired no `change` for the next clear, so a cleared `label` stayed set. Each control is now keyed by its prop or field (`KF-QCBJ4F`).
|
|
524
|
+
- **A content field in a Kerf UI editor item form leads to its field zone.** In a SegmentedControl choice’s form, `Content` read “KerfUiContent” and did nothing; it now adds to that choice’s field zone (opening Children with the zone chosen when nothing is suggested), or names and selects the nodes there, like a top-level content row. A field seeded with an item slot (a NavStack view's `content`) names the slot instead of showing its JSON, and nodes added from the row take the slot's place (`KF-VSWT2Q`, `KF-1ZSW5J`).
|
|
525
|
+
- **New nodes in the Kerf UI editor no longer write a `false` variant discriminant.** Dropping a ListHeader exported `toggle: false` and a Select `multiple: false`, restating defaults the validator already assumes when a prop is absent; seeding now leaves them unset (`KF-RRVYCG`).
|
|
526
|
+
- **The Kerf UI editor says why a drop is not allowed.** Dragging a component or node where it cannot go drew nothing and dropped nothing; the drag caption now names the reason in words while the pointer rests there ("ToolbarControlGroup goes in Toolbar or FloatingToolbar or TabBar", or "cannot go here") (`KF-6RYJ64`).
|
|
527
|
+
- **Toolbars and toolbar groups in the Kerf UI editor.** A new ToolbarControlGroup starts with a ToolbarButton instead of a stray Text, and Add a child in a group suggests ToolbarButton then ToolbarActionLink. A container with no main zone (a Toolbar) shows a placeholder for each empty zone ("Leading — drop here", "Center", "Trailing") while it is empty or selected, and a drop on one lands in that zone (`KF-7BB55F`).
|
|
528
|
+
- **A Select's value picks from its choices in the Kerf UI editor.** The `value` of a component with literal `choices` (Select, SegmentedControl, RadioGroup, …) is now a Select of those choices instead of a free text field labeled "Value value"; renaming the selected choice's value carries the value along in the same undo step, and a value that names no choice is shown as such with a hint. Props that take several kinds of value label the kind "<Prop> type" and the value "<Prop>" (`KF-9AWGPS`).
|
|
529
|
+
- **`validateView` accepts `$icon` and `$css` inside list and object values.** A Select choice's `icon` or `color` set in the Kerf UI editor was rejected with a type mismatch that dumped the whole `choices` value, although `interpretView` and the generated module already handled them (`KF-3J9GJV`).
|
|
530
|
+
- **Variant problems say how to fix them in the Kerf UI editor.** A node whose props fit none of its component's variants listed only "props match none of its variants"; the Problems list and banner now add what would fix it, such as `set "label" or "ariaLabel"`, `remove "ariaLabel" or "label"`, or `set "toggle" to false` (`KF-TVZ06Y`).
|
|
531
|
+
- **A gutter around the Kerf UI editor's canvas.** The preview sat flush against the canvas edges, so the selection ring of a node at the edge was drawn over its content; the canvas now leaves a small gutter so the ring and drop lines show whole (`KF-C4EW1V`).
|
|
532
|
+
- **Node-only content props are editable from Properties in the Kerf UI editor.** A prop that takes only components, such as a Button's or ListItem's `icon` or a ListItem's `trailing`, showed as a read-only "—". Its row now adds the component the zone calls for (a LucideIcon for an icon) and selects it, or opens Children on that zone when there is no single choice; once filled, the row names what fills it ("LucideIcon · plus") and selects it (`KF-5T3TE4`).
|
|
533
|
+
- **The Kerf UI editor's icon picker focuses its search.** Opening Choose icon puts focus in the search field, so typing a name filters the icons at once (`KF-GQHRC0`).
|
|
534
|
+
- **Empty containers show on the Kerf UI editor canvas.** A container whose main zone holds nothing (a new document's Pane, a Row just dropped in) previewed with no size, so it could not be seen, clicked, or dropped into. It now shows a placeholder ("Row is empty — drag a component here") that selects the node and takes a drop; the document is unchanged (`KF-ZWJHJR`).
|
|
535
|
+
- **Drops land in a node's main zone in the Kerf UI editor.** Dropping a component on blank canvas, or inside a node, now fills the zone its `children` render into (a Pane's content) before any other, and Add a child starts on that zone, instead of the first zone listed (a Pane's header) (`KF-W10DXQ`).
|
|
536
|
+
- **`@kerfjs/ui/styles.css` now holds the whole root-barrel layer.** It left out the stylesheets of `ListInsetControl`, `ListInsetText`, `SunkenPanel`, and `FloatingToolbar`. A root-barrel import paired with `styles.css`, as the Kerf UI editor's canvas does, therefore rendered those components unstyled: a `ListInsetControl` had no inset. The component-integrations check now fails when a root-barrel component's stylesheet does not reach `styles.css` (`KF-H29W31`).
|
|
537
|
+
- **Singular counts in the Kerf UI editor's preview header.** A document with one node or one problem now reads "1 node" and "1 problem" instead of "1 nodes" and "1 problems" (`KF-X2YQZE`).
|
|
538
|
+
- **A toggle `ListHeader`'s disclosure arrow lines up with its rows' trailing icons.** The arrow was centered in a 24px layer, 3px inside the trailing content edge of the `ListItem` rows below it. The layer now hugs the 18px arrow, so it ends on the toggle's 1px border + 8px padding, the same inset as a row's trailing icon, at standard and compact density (`KF-HZKKK9`).
|
|
539
|
+
- **UI doctor KUI-L401 honors view-scoped exceptions from app entries.** A declared application entry keeps each component use's source file when checking missing wiring, so a narrow exception on one view does not move to the entry or suppress another view's warning (`KF-5X91JH`).
|
|
540
|
+
- **Live Markdown editor at phone width.** The editor and preview stack into full-width, independently scrolling panes on narrow screens; tablet and desktop keep the side-by-side layout (`KF-HR730P`).
|
|
541
|
+
- **UI doctor KUI-L401 respects `ChoiceChips` modes.** Radio and toggle modes no longer require `wireChoiceChips`; listbox and dynamic modes still do. Entry-point wiring remains recognized when bundle entries are declared in `.kerf-ui-profile.json` (`KF-KCM28K`, `KF-CYYR43`).
|
|
542
|
+
- **Site audit accepts the patched DOMPurify release.** The documentation site's direct dependency and lockfile now use DOMPurify 3.4.17, resolving the reported sanitizer advisories while keeping the audit policy and Markdown editor behavior intact (`KF-VB4EXK`).
|
|
543
|
+
- **Quiet and danger Text contrast on lowered surfaces.** The shared light quiet and dark danger colors now clear WCAG AA when `Text` appears in a lowered `ValueTableRow` or `ListHeader` status over the document baseline, in both the foundation fallback and Web Awesome theme (`KF-CQWA7G`).
|
|
544
|
+
- **`require-data-key-in-each` recognizes component `rootAttributes` keys.** A statically named `"data-key"` or `id` in a component row's `rootAttributes` object now satisfies the rule. Dynamic objects and ambiguous later spreads remain diagnostic; native and fragment roots retain their checks (`KF-PD9ZGA`).
|
|
545
|
+
- **Web Awesome Carousel specimens show full slides in Firefox.** A `wa-carousel`'s scroll container is a `grid-auto-columns: 100%` track under an aspect ratio, so it has no definite intrinsic width. In the catalog's shrink-to-fit specimen column Chromium and WebKit resolved it from the aspect ratio (a 457px carousel at 1100px), but Firefox sized it to the first slide's text: a 191px carousel with a 103×34px track that clipped "Foundation" and "Focused carousel item" at every width. The Carousel and Carousel Item specimens now take the medium width tier, as the Zoomable Frame specimen does, so every engine renders the same full slides. A three-engine check asserts the track holds the whole slide at 1100px and 320px (`KF-0TGNQG`).
|
|
546
|
+
- **Web Awesome OTP Input cells render whole.** Upstream caps the OTP Input's segments box, which reserves its focus-ring bleed with 4px padding and an equal negative margin, at 100% of the host. In a shrink-to-fit host (the catalog's start-aligned example grid, any start-aligned grid or flex item) the host is only the cells' width minus that bleed, so the padded box was 8px too narrow and silently clipped the last cell's inline-end edge inside its scroll container at every width. `@kerfjs/ui/webawesome.css` caps it at the host's width plus the bleed its negative margins reserve: a host narrower than the code still scrolls, and the `contained` appearance keeps upstream's cap. The catalog's phone-width check now measures the cells inside the shadow root (`KF-SPEQPY`).
|
|
547
|
+
- **Row and Grid catalog specimens fit a 320px phone.** The Row catalog's vertical-alignment rows now `wrap`, so the Baseline Alignment row's taller chips move the third chip to a second line instead of running 13px past the example, and the non-wrapping Default, Distribution, and Side-Selectable Insets rows use short `One` / `Two` / `Three` chips, which fit 320px with room to spare even in Linux's wider fallback font (the prefixed `Default three` ran about 15px past the example there) (`KF-JWT4QZ`). The Grid catalog's Four Columns example shows short quarter tiles (`Q1` … `Q4 est.`) that fit a phone-width track instead of process-stage words that ran past their own tiles and up to 11px past the example; its note now says a fixed count suits short content and points longer labels at `minColumnWidth`. Both catalogs join the phone-width overrun check (`KF-37ERTC`).
|
|
548
|
+
- **Catalog labels and specimens fit a 320px phone.** A `CatalogExample` label is a content-width `ListHeader`, and its single unbreakable line set the header's minimum width, so about twenty long labels ("Sunken Workbench Regions Without Pane Chrome", "Accessible Name Without a Visible Label", …) ran past the example and were cut off at the stage edge instead of truncating. The label now wraps through the new `ListHeader` `wrap`. The Web Awesome OTP Input specimen uses the small size, whose six grouped cells fit the 280px specimen column (the default size needs 292px), and the ListHeader catalog's inline-header row wraps its trailing status instead of running 16px past the example (`KF-12WBGR`).
|
|
549
|
+
- **Aligned `CatalogExample` specimens no longer run past the example's end edge.** An aligned example (`align="glyph"`, `"inline-control"`, or `"text-trigger"`) inset each specimen with a start margin, so a full-width specimen — the SearchField catalog's Disabled field, the Select catalog's fill-width Visible Label select, the SegmentedControl catalog's control-width Rounded Rectangle frame — kept its full width and ran 8px past the example at every stage width. The inset is now the example's own grid column: the label and note span the full width and every specimen sits in the inset column, so a percentage width resolves against that column and ends on the example's edge, while specimens keep their own width caps. A page-fixed specimen (the EdgeActivityIndicator strip) no longer picks up the inset either (`KF-EE4WEN`).
|
|
550
|
+
- **`ColorPicker` dark design templates draw a solid opacity track end.** The templates' opacity-track stand-in drew its translucent dark checker squares straight onto the template's transparent background, so in the dark templates they took on the viewer's backdrop and showed through the track's opaque end. The checkerboard now sits on an opaque surface underlay, like the component's own, and fades out toward full opacity in light and dark alike (`KF-MV5GE6`).
|
|
551
|
+
- **`ColorPicker` area edge and thumb outline.** The saturation and brightness area had no boundary, so its black bottom vanished into a dark surface and its white corner into a light one; it now draws the same 1px inner edge as the slider tracks (halfway to the text color, the full text color under increased contrast, `CanvasText` in forced colors). Every thumb's outline outside its white border is now dark enough (60% black, was 20–30%) that a light thumb over a light area or track keeps at least 3:1 against it, while the white border holds against dark colors (`KF-F4J2GD`).
|
|
552
|
+
- **The Web Awesome Known Date and Slider catalog specimens have a field width.** Both size to their container, so in the shrink-to-fit specimen column Known Date measured 0px wide (its segments stacked and its hint wrapped a word per line) and Slider about 90px. The catalog now gives Known Date a compact field column and Slider the Kerf Slider demo's medium width, and the Slider specimen takes the field demos' `inline-control` alignment so its label and track land on the Kerf Slider's column. The theme contract notes that both need a width from their container (`KF-ZVA2S2`).
|
|
553
|
+
- **The Web Awesome Progress Bar, Skeleton, and Zoomable Frame catalog specimens no longer collapse.** They also size to their container, so the specimen column shrank Progress Bar to a 30px stub, Skeleton to 0px, and Zoomable Frame to an empty 16px panel. The catalog now gives Progress Bar the Kerf ProgressBar demo's medium width, Skeleton a compact text column, and Zoomable Frame a medium media frame (`KF-J214TZ`).
|
|
554
|
+
- **`wa-tag-input` follows the Web Awesome field theme.** `@kerfjs/ui/webawesome.css` now gives a raw `wa-tag-input` the same treatment as the other bordered fields: its label is uppercase on the 9px text column, its hint shares that column, its box takes Kerf's 44px control height (2.75em), its border sits on the host's inline-start edge, and a small one keeps a 16px editable text size on coarse touch devices. It stays Discouraged in favor of `TagField`; the catalog specimen now uses the field demos' `inline-control` alignment (`KF-S5XTY4`).
|
|
555
|
+
- **`kerf-ui-doctor` reads raw `wa-checkbox-group` labels.** `KUI-D040`'s title-style check already read `CheckboxGroup` and raw `wa-radio-group` labels; the `label` of a raw `wa-checkbox-group` is now read the same way, while `wa-checkbox` option text stays sentence style and unread (`KF-ZJ28W4`).
|
|
556
|
+
- **Every Kerf field demo shares one border and label column.** The UX catalog's ColorField, TagField, and Slider specimens now use `align="inline-control"` like the TextField, Select, Switch, Checkbox, RadioGroup, and CheckboxGroup demos, so field borders and label text line up across the catalog instead of sitting 8px apart. A `CatalogExample` `viewport` that is aligned now takes that offset out of its width, so a full-width specimen frame no longer runs 8px past the example's inline-end edge at narrow widths (`KF-ZPDYQW`).
|
|
557
|
+
- **The ColorSwatches catalog demo joins the field column.** ColorSwatches is a field — a person picks a value with it inline — so its specimens now use `align="inline-control"` and its legend text lands on the field label column with the other form fields. ColorPicker and FilePicker are panels (a multi-part picker and a drop zone) and stay flush; `ui/docs/catalog.md` now states the field-versus-panel rule (`KF-8YAGME`).
|
|
558
|
+
- **Width-sized catalog specimens join the field column.** The ProgressBar demo, the group-title `Text` specimen, the Grid and saved-view SearchField field compositions, and the Web Awesome Progress Bar, Skeleton, and Pagination specimens sat flush at the example's edge, so a bar's "Uploading Files" label started 8px left of the example label and note text. They now use `align="inline-control"` like the form fields, and their sized frames still end at the example's inline-end edge. Panels (ColorPicker, FilePicker, Zoomable Frame) and edge-to-edge compositions stay flush; `ui/docs/catalog.md` states the rule (`KF-WH27TY`).
|
|
559
|
+
- **Web Awesome control and text specimens align like their Kerf counterparts.** The catalog's Web Awesome Button, Button Group, Dropdown, Dropdown Item, Tab family, Badge, Tag, Avatar, Progress Ring, Toast, Toast Item, Animation, observer, and dialog/drawer/popover/tooltip trigger specimens sat flush at the example's edge while the Kerf Button demo puts its control box on the 8px column; they now use `align="inline-control"`. Specimens led by bare text or a glyph (Copy Button, Breadcrumb, Divider, Markdown, Relative Time, Pagination's summary, Stepper and Step, Spinner, Icon) now use `align="glyph"`, so their text sits on the text column as Kerf's flush Text demo does instead of at x=0. The CornerStatus "Embedded" example's banners now sit on the same 8px column as the standalone StateBanner demos. Panels and framed media (Page, Split Panel, Popup, Zoomable Frame, QR Code, Animated Image, Carousel) keep their own geometry (`KF-44TDSF`).
|
|
560
|
+
- **A tall `PopupMenu` or `Select` popup never covers its trigger.** When a popup fit on neither side of its trigger (a toolbar overflow menu at 1024×600), it was shifted across the trigger to stay in the viewport, so a second press on the trigger landed on a row instead of closing the popup. The shared popup placement now shifts only along the trigger's edge: when neither side fits, the popup opens on the side with more room and scrolls inside its capped height. `PopupMenu` menus, `Select` and `Combobox` listboxes, and help tags all share it (`KF-F22WMW`).
|
|
561
|
+
- **A context `PopupMenu` honors its `placement`.** A `context` menu always opened `bottom-start` at its anchor point whatever `placement` it was rendered with, so a menu anchored to a footer or composer could not open above the point. Its placement now applies at the point (`top-start` opens above it, `top-end` above it at its end), with the same viewport flip, shift, and height cap; a button-triggered menu opened at a pointer with `openPopupMenuAt` still opens `bottom-start` from the point for that opening (`KF-MXM1SH`).
|
|
562
|
+
- **A group-owned `Select` draws one focus ring.** A `Select` with `focusRingOwner="group"` inside a `ToolbarControlGroup` that draws the pill ring still painted its own trigger outline on focus, because the trigger's focus rule outranked the owner rule, so keyboard focus showed two rings. The trigger's focus ring now applies only when the Select owns it; a select-owned trigger and a per-control-ring group are unchanged (`KF-GWSEWC`).
|
|
563
|
+
- **`ColorPicker` slider tracks follow the writing direction.** In right-to-left text a native range runs right to left, but every channel and opacity track still painted its gradient left to right, so the thumb at a channel's minimum sat over the color of its maximum. Each track now runs in the writing direction (`to left` under `:dir(rtl)`), and a browser test checks that the thumb at the minimum sits over the gradient's start in both directions (`KF-KKMMJV`).
|
|
564
|
+
- **`ColorPicker` slider tracks keep their edge on a matching surface.** A dark track (a hue at low brightness, a faint opacity) used to vanish into a dark surface, and a light one into a light surface, because each drew only a faint black inner line. Every track now draws a 1px inner edge halfway to the text color, at least 3:1 against the surrounding surface in light and dark; increased contrast draws it in the full text color and forced colors in `CanvasText` (`KF-JN1ZH6`).
|
|
565
|
+
- **`kerf-ui-doctor` no longer reports a false `KUI-L203` for every `MessageComposer`.** The shipped composition catalog still declared the removed `actions` zone; it now declares a required `trailing` zone and an optional `leading` zone, and a test keeps every component's composition zones aligned with its real props (`KF-Z00DKT`).
|
|
566
|
+
- **`SplitButton` focus ring is visible on every tone.** Each half drew its keyboard focus ring inside its loud fill, where it all but vanished on the brand fill in light mode and matched the brand fill exactly in dark mode. The ring now sits outside the focused half, offset 1px like `Button`'s, so it is drawn against the surrounding surface on every tone and in both schemes (`KF-V0HSNG`).
|
|
567
|
+
- **`RadioGroup` circles line up with Checkbox boxes.** Each radio circle now sits on the group's inline-start edge, where a `Checkbox` draws its box, instead of 8px further in, so stacked checkboxes and radios share one control column; the group label and hint keep the text column (`KF-F68AZ9`).
|
|
568
|
+
- **Web Awesome Checkbox Group and Radio Group follow the same control column.** The `@kerfjs/ui/webawesome.css` theme no longer insets a `wa-checkbox-group` or `wa-radio-group` option region by 8px, so each box or circle sits on the group's inline-start edge like Kerf's `Checkbox` and `RadioGroup`, and both groups' hints now join their label on the 9px text column. The unbordered Color Picker trigger keeps its 8px inset (`KF-2X0Z47`).
|
|
569
|
+
- **Web Awesome fields, Switch, and Color Picker share Kerf's field columns.** The `@kerfjs/ui/webawesome.css` theme no longer insets the `wa-color-picker` swatch trigger by 8px, so it sits on the host's inline-start edge like a Kerf `ColorField` trigger, with its label on the 9px text column. The guidance now states the placement rule for every themed field: a bordered `wa-input`, `wa-select`, `wa-textarea`, `wa-number-input`, `wa-time-input`, `wa-known-date`, or `wa-otp-input`, and a `wa-switch` track, start on the host edge exactly where Kerf's `TextField`, `Select`, and `Switch` draw theirs, so place a Web Awesome field where the Kerf field would go. The catalog's field specimens now use the Kerf field demos' alignment, so their borders, labels, and hints land on the same columns in every engine (`KF-6SM43M`).
|
|
570
|
+
- **`NavStack` overlay chrome keeps its material during a push or pop.** The overlay top chrome and bottom toolbar used to fade as a whole while their contents cross-faded, which faded the backdrop blur with them (Safari dropped it outright), so the sliding views showed through the bars mid-transition. Now the live bar keeps the material at full opacity while its new contents fade in, and the copy fading out above it carries only the old contents (`KF-H3NNP6`).
|
|
571
|
+
- **Anchored surfaces follow an anchor that changes size.** `autoReposition()` (and so `popover()`, `tooltip()`, and `AnchoredSurface`) also repositions when the anchor itself resizes, where `ResizeObserver` exists, not only on scroll and resize, so a surface below a field moves down as the field grows a line. The UX catalog's Structured Ticket Search help now anchors to the whole SearchField instead of its help button, so at phone width it no longer covers the field's wrapped second line, and typing in the field leaves it open (`KF-37TGXB`).
|
|
572
|
+
- **Anchored surfaces follow their own size changes.** `autoReposition()` (and so `popover()`, `tooltip()`, and `AnchoredSurface`) also repositions when the positioned element itself resizes, where `ResizeObserver` exists, so an end-aligned surface that grows wider keeps its right edge on the anchor's, and an above-placed one that grows taller keeps hanging just above the anchor instead of growing over it until the next scroll. A resize that the positioning's own writes caused is not acted on again, so repositioning never feeds itself (`KF-S92WX8`).
|
|
573
|
+
- **A scrolled `fitHeight` surface keeps its scroll position in Safari.** To honor the element's own `max-height`, `positionAnchored()` briefly lifts the room it published around a style read. WebKit lays the element out for that read when a size container sits inside it (a `Toolbar`, a `ValueTable`), and the uncapped layout clamped the element back to its top; every scroll inside it repositions it, so wheel scrolling an `AnchoredSurface` jumped back to the first row. The element's current height is now pinned for the read, and a scroll position the read still moves is put back (`KF-PVBPJM`).
|
|
574
|
+
- **`Combobox` suggestions are no longer clipped inside popups.** The listbox is a top-layer popover placed below the field at its width (flipping above when short), so an `AnchoredSurface`, a dialog, or a scrolling `List` around the field no longer cuts it off. The `--kui-combobox-z-index` token is gone; the top layer needs none (`KF-C558Z9`).
|
|
575
|
+
- **`List` `vAlign="middle"` and `Row` `hAlign="center"` gather their children in the middle** with their `gap`, instead of spreading them with `space-around`. `space-around` is now its own explicit value (`data-*-align="around"`), and `center`/`middle` on the cross axis center wrapped lines (`KF-3ZJ9PF`).
|
|
576
|
+
- **A SearchField no longer shows its placeholder over typed text after an unrelated re-render.** Re-rendering the host for another reason, such as an error message beside the field, reset the field's placeholder state from the app's query while the editor still held typed text. `wireSearchFields` now re-derives it from the live editor (`KF-PZ5J93`).
|
|
577
|
+
- **`<details name>` typechecks in kerf JSX.** The intrinsic `details` element now accepts `name`, the native exclusive-accordion group, so `<details name="faq">` no longer fails to typecheck (`KF-KFH2VT`).
|
|
578
|
+
- **A `SplitView` column's only `Pane` now fills the column in `@kerfjs/ui`.** It used to take only its content height, so the Pane's footer sat right below its content instead of at the column's end (`KF-P9VSX1`).
|
|
579
|
+
- A busy `ToolbarControlGroup` whose control shows text (`content="text"` or `"mixed"`) now hides the whole control under its spinner, label included, while keeping its size. Before, only icons were hidden, so the spinner drew over the label ("Pric◌ Check") (`KF-HCN9BH`).
|
|
580
|
+
- `@kerfjs/ui/webawesome.css` draws a loading active `wa-step`'s spinner in the marker's on-accent color. Web Awesome 3.14 colors that spinner with the same accent that fills an active marker, so it was invisible. The fix goes through the step's public `spinner` part (`KF-AW993A`).
|
|
581
|
+
- A `@kerfjs/ui` `Toolbar` with a single zone now gives that zone its whole content box. A leading-only toolbar kept the empty trailing track and its 8px column gap, so leading content set to fill the row (a flex `Row` of controls) stopped 8px short of the inline-end inset; a trailing-only toolbar had the same gap on the leading side. A lone leading, center, or trailing zone now spans every column track. Covered in Chromium, Firefox, and WebKit.
|
|
582
|
+
- Typing in a model-managed `@kerfjs/ui` `TokenSearchField` no longer re-runs the host `mount()` render on every keystroke. The field read the model's per-keystroke `state` during render, so an app that renders it from one large mount re-rendered and morphed the whole app per key. It now subscribes only to the new `model.structure` signal, which changes when a token is committed, removed, or reordered, when the text becomes empty or non-empty, or when the editor revision changes; the live text stays owned by the editor and `wireTokenSearchFields`. `model.suggestions` now publishes only when the suggestion list's content changes, and a model action that changes state publishes its state, result, and suggestions as one batch. Hosts that read `model.state.value` in their own render still subscribe per keystroke by choice: read `model.state.peek()` there, or bind `model.result` (or a `computed`) as a fine-grained text or attribute hole. An app that coalesced the field's per-keystroke projection to work around this can remove it.
|
|
583
|
+
- A `kerfjs/overlay` `initialFocus` that targets a custom element that cannot take focus yet no longer aborts the open. Before, a Web Awesome `wa-button` whose `focus()` throws before it has rendered made `overlay()` (and `confirm()`, `prompt()`, `form()`, `choice()`) roll back and rethrow. Now focus holds on the overlay itself, then moves to the element once it is defined and rendered, unless the overlay has closed or the user has moved focus in the meantime. The same applies to `initialFocus: true` when the first tab stop is such an element. Covered in Chromium, Firefox, and WebKit.
|
|
584
|
+
- `wireNavStack` keeps fallback focus on a pushed view with nothing focusable (an inert loading placeholder, say) across re-renders. The temporary `tabindex="-1"` it adds to the view was morphed away by the next render, which made the view unfocusable and dropped focus to the page body. It is now restored while the view holds that focus, and focus moves to the view's first focus target once content with one arrives under the same key. Focus the person moved elsewhere is left alone.
|
|
585
|
+
- Clearing a collapsible `TokenSearchField` with its ✕ button while focus is outside the field now collapses the emptied field and leaves focus where it was. Previously the clear re-expanded the field and claimed the caret, so it stayed open until it was focused and blurred again. A clear started from inside the field still returns the caret to the editor; that is now decided by where focus was when ✕ was pressed, which also covers WebKit, where the press drops focus to the page before the click.
|
|
586
|
+
- A `DialogSurface` bottom sheet with no `height` now opens at its content height, as documented. A modal dialog sits between both block insets, so the sheet's auto height stretched to its cap. The catalog's resizable sheet now relies on content height: its fixed height sat a few pixels short of the form and clipped the textarea's bottom border on a phone.
|
|
587
|
+
- A title over a `BackdropImage` `scrim` is now light in both color schemes. The scrim is dark in both schemes, so the overlay now takes the dark color scheme and default-tone titles and controls resolve their light foregrounds. `ToolbarText tone="dark"` is unchanged: it matches dark control groups on a loud-filled toolbar and inverts with the scheme, so the guidance no longer recommends it for photo-backed toolbars. Under reduced transparency or increased contrast, where the overlay sits on a solid `fadeTo` band, the overlay keeps the page's scheme.
|
|
588
|
+
- `kerf-ui-doctor --full` and `kerf-ui-analyze` no longer report findings in gitignored, generated output. A local Playwright run's `playwright-report/` (its trace viewer ships CSS) produced about a hundred `KUI-L006` review findings in one app, so running the tests changed the doctor result. Inside a Git work tree, full traversal now skips every path the project's ignore rules ignore, across TypeScript, the isolated ESLint pass, analyzer discovery, and cache inputs; Playwright's `playwright-report`, `test-results`, and `blob-report` directories are also skipped by name, which covers projects outside Git.
|
|
589
|
+
- A dark-tone `AnchoredSurface` (`tone: 'dark'`) now follows a live color-scheme switch while it is open. It picked its inverse scheme once, on open, so an OS preference change or an app theme toggled on an ancestor left the popup on the old side until it was reopened. It now flips with the page. `openAnchoredSurfaceAt` also reads the dark tone's scheme from `point.context`, the element under the pointer, instead of from the body or dialog that holds its temporary anchor, so a region with its own forced `color-scheme` is honored.
|
|
590
|
+
- A keyboard move made as a long `PopupMenu` submenu (or menu) opens now leaves the chosen item in view, not just focused. When Web Awesome's late first-item focus landed after the move (say `End` pressed right after `ArrowRight`), it scrolled the menu back to the top, and kerf's restore refocused the chosen item without scrolling, so the focused last choice sat out of view below the clip. The restore now scrolls the item into view within its own menu, leaving the page alone.
|
|
591
|
+
- A default-tone `ToolbarControlGroup` in an overlay `Pane` header (`headerPresentation="overlay"`) or in a `DialogSurface` floating header's `header-actions` (`headerPresentation="floating"`) now keeps its controls at WCAG AA over content passing beneath the translucent chrome material. Its quiet control color over its own translucent fill measured about 3.0:1 (light) and 3.5:1 (dark) over the worst case; its controls now take the normal text color there, as they already did in overlay `NavStack` chrome.
|
|
592
|
+
- A dark `ToolbarControlGroup` (`tone="dark"`) holding one control no longer hides its icon on hover over a light page. A lone control's hover replaces the whole group's fill, and the dark tone's hover was a translucent surface wash meant to lie over that fill, so the white icon sat on a near-white circle (about 1.3:1). The wash now paints over the group's loud fill, as it does on one control of a multi-control dark group, and it is 14% instead of 28%: at 28% even that layered paint measured about 2.7:1. Hovered dark controls now keep about 3.4:1 over a light page and about 5.8:1 in dark.
|
|
593
|
+
- An unframed scrollable `List` now stops a row focused or scrolled into view with its whole focus ring inside the scroll clip. Only a framed List carried ring-room scroll padding, so in an unframed one the ring of a row brought into view ended flush against the clip and was cut off. Every `scrollable` List now has 6px of block scroll padding (the ring's 4px reach plus 2px of slack), which moves nothing at rest. An unframed List's first and last rows still meet the clip at the scroll extremes; `frame`'s 4px inset is the answer when they must show a whole ring.
|
|
594
|
+
- An overlay `Pane` header (`headerPresentation="overlay"`) now clears its forced-colors edge. In forced colors the header gains a 1px `CanvasText` bottom border, but `wireScrollDividers` observed the header's content box, so the border alone reported no resize and `--kui-scroll-clearance-block-start` stayed 1px short: the content's first item rested under the edge. The wiring now observes each overlay header's border box, the same box it publishes.
|
|
595
|
+
- `positionAnchored({ fitHeight: true })` (and so `autoReposition()`, `popover()`, `tooltip()`, and `@kerfjs/ui`'s `openAnchoredSurface()`) now keeps an element placed above its anchor growing upward. It set `top` from the height the element had at the reposition, so an element still growing afterwards — say an expand-from-0 `max-height` entrance placed above mid-expand — slid its bottom edge down over the anchor until the next scroll or resize. An above placement now pins the element's bottom edge at the gap above the anchor (`bottom`, with `top: auto`), so it grows and shrinks upward, away from the anchor, whatever height it goes on to lay out; a below placement sets `top` with `bottom: auto`. Placement without `fitHeight` is unchanged (`KF-MZ03RG`).
|
|
596
|
+
- An overlay `Pane` header (`headerPresentation="overlay"`) no longer covers the top of a classic, space-taking scrollbar (Windows and Linux, or macOS with "always show scrollbars"). Its thumb and arrow buttons ran beneath the translucent header. `wireScrollDividers` now also measures the content's vertical scrollbar and publishes a classic one's inline size on the Pane as `--kui-pane-scrollbar-inline-size`, and the header ends where the scrollbar's track begins. Overlay scrollbars take no space and still pass beneath the header like the content.
|
|
597
|
+
- A `ToolbarText` in an overlay `Pane` header (`headerPresentation="overlay"`) now keeps WCAG AA over the translucent chrome material. Over worst-case content passing beneath, its quiet `description` measured about 3.2:1 (light) and 4.1:1 (dark), and a default-size title about 3.8:1 (light). In that header an untoned `ToolbarText` now takes the normal text color for its title at every size and mixes its description halfway toward it (about 5.9:1 in both themes), so the description stays readable and still reads as secondary.
|
|
598
|
+
- A framed `List` (`frame`) now keeps a focused middle row's ring inside its scroll clip in Chromium. The frame's scroll padding equaled the ring's 4px reach, but Chromium's focus scroll stops 1px short of the padded target and a row's fractional position can cost another fraction of a pixel, so about 1px of the ring was cut. The scroll padding is now the ring reach plus 2px; the frame's 4px visual inset and its first- and last-row resting positions are unchanged.
|
|
599
|
+
- `positionAnchored({ fitHeight: true })` now measures an element whose `max-height` is mid-animation at the cap it is headed to. An app transition already running on `max-height` (say an expand-from-0 entrance to `max-height: 300px`) or a `@keyframes` animation of `max-height` made the cap read report the current frame, so a reposition mid-expand judged the element by a height it was about to outgrow and could open it on a side its settled cap does not fit. kerf now reads the cap from the running effect instead — its last `max-height` keyframe, or its first while the current iteration plays in reverse — and, for that case, never touches the element's style, so the app's animation keeps running uninterrupted. A finished animation that still fills is read from computed style as before, and a keyframe `var()` kerf cannot resolve outside the element counts as no cap (`KF-YW3PRD`).
|
|
600
|
+
- `eslint-plugin-kerfjs`'s `ui-css-values` rule now recognizes CSS-value helpers imported from any `@kerfjs/ui` subpath, including the documented `@kerfjs/ui/css-values`. It only knew helpers imported from the package root, so `iconTile={{ color: foregroundColor('#000') }}` with `foregroundColor` from `@kerfjs/ui/css-values` passed lint while `kerf-ui-analyze` reported `KUI-L014` (and likewise `KUI-L015` for a bare `plus()`). Lint now resolves a helper exactly as the analyzer does: by its imported name, from the component's package or any subpath of it, through a named, aliased, or namespace import. A same-named helper from another package is still ignored (`KF-HKGK2C`).
|
|
601
|
+
- `positionAnchored({ fitHeight: true })` now honors a relative `max-height` cap and is no longer fooled by a `max-height` transition. A cap that stays relative after computing — `max-height: 60%`, `calc(50% - 2rem)`, `min(300px, 60%)`, `clamp()` — was treated as no cap, so an element that fit the preferred side at that cap still opened on the roomier side. kerf now resolves it against the element's fixed-position containing block (normally the viewport) with an unpainted probe beside the element, so the element's scroll position and layout are untouched. And an app `transition` on `max-height` made the cap read report the transition's running value (the room kerf last published) and fire `transitionrun` / `transitionstart` events, so the cap was ignored again; kerf now holds off only the `max-height` transition for that read, and every other transition keeps running (`KF-53GEGN`).
|
|
602
|
+
- A `StateBanner`'s side action no longer squeezes or covers its copy on a narrow banner. The banner laid out as a three-track grid whose action track took the action's full width, so on a phone a pair of buttons (say Retry Save and Discard Changes in a wrapping `Row`) left the title about 65px, and a word wider than that ran underneath the buttons. The banner is now a wrapping row: the default `actionPlacement="trailing"` keeps the action beside the copy while the copy has at least 12rem, and otherwise moves it to its own end-aligned trailing row. The choice follows the banner's own width rather than a breakpoint, so it also works in a narrow sidebar on a wide screen and inside an intrinsically sized `CornerStatus`. `actionPlacement="below"` still always uses the trailing row (`KF-PXCKVZ`).
|
|
603
|
+
- `positionAnchored({ fitHeight: true })` (and so `autoReposition()`, `popover()`, `tooltip()`, and `@kerfjs/ui`'s `openAnchoredSurface()`) now honors the element's own `max-height` when choosing a side. It measured a scrolling element at its full content height, so an element the app caps below that height — say `max-height: min(300px, var(--kerf-anchor-available-height))` with 500px of content — fit neither side and opened on the roomier one, even when its 300px capped height fit the preferred side. kerf now reads that cap with its own published room swapped for an unbounded one, so it never mistakes its last cap for the app's, and the read is style-only, so the element's scroll position is kept (`KF-878W6T`).
|
|
604
|
+
- A keyboard move made just as a `PopupMenu` submenu finishes opening is no longer undone. Web Awesome hands focus to the submenu's first item from a timer it queues when the show animation settles, and a browser may dispatch a keypress before that timer runs. So pressing `End` (or an arrow key) at that moment focused the chosen item, and the late handoff then snapped focus back to the first item. PopupMenu now keeps the keyboard or pointer choice through that handoff; a deliberate `Home` to the first item still stands (`KF-XMDR2Q`).
|
|
605
|
+
- An open `PopupMenu` is now announced with a name. Web Awesome renders the `role="menu"` panel in a shadow root, and the trigger's name never reached it: a `context` menu's `label` sat only on its `aria-hidden` anchor, and no ID reference can cross into or out of the shadow roots involved. So a screen reader announced an unnamed menu, and `getByRole('menu', { name })` found nothing. The panel now takes the trigger's name (the `context` or icon-only `label`, or the visible `text`), and each submenu is named by its parent item's label (`KF-AB4ZVD`).
|
|
606
|
+
- A `TabBar` with `snapTabs` no longer grows its tab strip past its allocation. The snap mode reserves end scroll room so the last tab can settle at the strip's start, and it reserved that room as end padding on the strip. A flex item can't shrink below its own padding, so room measured at one width held the strip open after the bar narrowed. This happened, for example, when a drawer opened or lost space to a neighboring panel. The strip then pushed an adjacent `trailing` action and the `end` zone out of the bar, where they could not be clicked; a twelve-tab drawer strip measured 1584px against a 1088px edge. The room is now scrollable content after the last tab, inside the strip. It lengthens only the scroll range, so the strip shrinks to its allocation and the last tab can still snap to the start. Writing the room no longer resizes the strip, so `wireTabBars` now re-measures it on the next frame until the value holds. This replaces the follow-up measurement that a resize used to trigger (`KF-3Q98FJ`).
|
|
607
|
+
- In Safari, closing a `Select` inside a scrolling dialog body no longer leaves blank scroll space below the content. WebKit kept the closed listbox's last box in the body's scrollable overflow, so the body scrolled into an empty band the height of the listbox. The Select now relayouts its popup once after it closes, which keeps focus and the keyboard on the Select (`KF-C3523R`).
|
|
608
|
+
- In a divided list, `ListItem`, `ListItemLink`, and `ListActionRow` corners now follow the row's position. A corner is flat wherever a divider line meets it, whether the row draws that line or its neighbor does, so with lines between rows the first row rounds only its top, middle rows are flat, and the last row rounds only its bottom. Previously each row squared only the edges it drew itself, so in a `divider="after"` list every hovered or selected row was rounded on top and flat on the bottom, including the last. A single divided row is unchanged (`KF-AQN4H7`).
|
|
609
|
+
|
|
610
|
+
- A collapsible `TokenSearchField` in a `ToolbarControlGroup` with `content="search"` and `sizing="grow"` now opens and closes as one surface. The group snapped straight to its grown width (its `width: auto` cannot transition) while the field animated its own width inside it, so for about 250ms the pill showed an empty band and the query wrapped onto several lines. The group now animates its flex size, and the field fills it on every frame, laid out at least basis-wide while the group clips it. In a toolbar 480px wide or narrower, where the grown group takes its own row, and under reduced motion, both open in one frame (`KF-50K0JM`). A plain collapsible search group (no `sizing="grow"`) had the same defect in a milder form: its field ran a second width transition that lagged the group's by up to 90px, and the query wrapped onto as many as 19 lines for about 100ms. The group now owns that motion too. The field follows it on every frame and keeps the query on one line until the opening ends, then wraps normally again (`KF-CXQB30`).
|
|
611
|
+
|
|
612
|
+
- A tooltip or popover outside a Web Awesome `wa-dialog` / `wa-drawer` is no longer painted beneath it. Those elements keep their modal `<dialog>` in a shadow root, which kerf's modal checks never saw: a surface opened while one was open was not lifted into the top layer, and surfaces already showing were not re-hosted above one that opened later (its `toggle` event stays inside the shadow root). kerf now also checks the open shadow roots when a surface opens, and watches them for `toggle` while any surface is open; a surface hosted inside the dialog stays where it is. A closed shadow root remains invisible (`KF-1FGTX1`).
|
|
613
|
+
|
|
614
|
+
- A `ToolbarControlGroup` now dims a native button marked `aria-disabled="true"` (one kept focusable while unavailable) exactly as it dims a `disabled` one: half opacity, a `not-allowed` cursor, and no hover surface, including a lone group's whole-group hover. It used to look and hover like an enabled control. A disabled raw `wa-button` in a group also no longer paints the group's hover surface (`KF-Y3ZZ10`).
|
|
615
|
+
|
|
616
|
+
- A focused `scrollable` `List` now draws the theme focus ring inset by the ring width and rounded with the standard control radius. Chromium makes a scroller without focusable rows keyboard-focusable, and a dialog may focus it first. It used to show the UA's square outline outside its box, which a rounded or `overflow: hidden` parent clipped (`KF-AJNFTT`).
|
|
617
|
+
|
|
618
|
+
- Typing quickly into a `TokenSearchField` whose app commits typed grammar to chips from `onEdit` (or removes a chip from `keyboard.onRemoveToken`) no longer loses keys. The token change re-keys the editor, so the controlled render replaced the focused element, and keys typed before the app refocused it went nowhere: `site:north site:annex` became `[site:north] ite:annex`. `wireTokenSearchFields` now hands focus and caret to the replacement at the same mutation checkpoint, as it already did for Clear and native deletion. A caret at the end stays at the end, and any other caret keeps its place in the remaining text (`KF-96TEF4`).
|
|
619
|
+
|
|
620
|
+
- `DialogSurface` no longer names a `wa-dialog`'s native panel when the host is itself an explicit, named dialog (`role="dialog"` or `"alertdialog"`). Both used to carry the same name, so the accessibility tree had two dialogs with one name and role queries such as Playwright's `getByRole('dialog', { name })` failed in strict mode. Removing or changing the host role restores the panel name (`KF-A0NF2S`).
|
|
621
|
+
|
|
622
|
+
- A nested `PopupMenu` submenu's pointer "safe triangle" now spans the gap to the placed submenu. Web Awesome measured the submenu for that triangle before its asynchronous placement landed, so the triangle kept the submenu's pre-placement edge (often the viewport origin): its fixed, viewport-sized hit region fanned away from the submenu and could cover the parent menu's rows, swallowing their hover and clicks. PopupMenu now re-measures once the placement lands and again when the submenu's show animation settles, so applications need no `::part(submenu)::before` override (`KF-YAHAZK`).
|
|
623
|
+
|
|
624
|
+
- A `scrollable` `List` bounded by a `max-height` ancestor now scrolls its rows instead of compressing them. Its children kept the default `flex-shrink: 1`, and a `ListItem` clips its own overflow, so multiline rows shrank into one another and their descriptions overlapped the next row. A scrollable List's direct children no longer shrink, and `docs/layout.md` documents bounding one with `flex` inside a max-height flex column (`KF-93GZC1`).
|
|
625
|
+
|
|
626
|
+
- A `popover()`, `tooltip()`, or `openAnchoredSurface()` opened from inside a Web Awesome `wa-dialog` or `wa-drawer` is now interactive. Those elements keep their modal `<dialog>` in a shadow root, so kerf found no dialog above the slotted trigger and appended the surface to `document.body`, where the modal made it inert: it painted above the dialog, but its controls took no focus or input. kerf now resolves the modal context across shadow boundaries: a shadow host whose slot renders the trigger inside an open modal `<dialog>` counts as that dialog, and kerf creates the overlay host slot in the host's light DOM, so the surface is slotted inside the dialog. A surface inside a modal context, through its host slot or an explicit `container`, now also closes when that dialog closes. Escape still closes only the surface. `openAnchoredSurface()` accepts a `container` for any other modal context, and `openAnchoredSurfaceAt()`'s `context` resolves a `wa-dialog` / `wa-drawer` too (`KF-F52T5D`).
|
|
627
|
+
|
|
628
|
+
- Re-renders of a large page whose rows come from a memoized `each()` now scale with the change instead of the row count. The change-scoped morph now also runs on renders that contain `each()` lists: a change beside the list, such as a details pane that follows the selection, is re-parsed and morphed without visiting the rows, and kerf falls back to the full diff when the change sits in the element that holds the rows. After such a render, the scan for list markers skips the bound rows. `SafeHtml` also builds its HTML string on first read instead of at construction, so each element above a list no longer copies every row's markup. A one-row selection on a 300-row memoized keyed page drops from about 3.7 ms to 0.3 ms per render in Chromium (about 29 ms to 3 ms in happy-dom). An attribute set imperatively on an element outside the changed markup now survives such a render, as it already did on list-free pages (`KF-03KWNV`).
|
|
629
|
+
|
|
630
|
+
- On the same kind of page, a mount that also has a fine-grained binding outside the list (for example `class={signal}` on a page wrapper) no longer searches every row for binding markers after a render that changed the page. Rows carry only their own row-scoped markers, so kerf now skips them. A selection flip on the 300-row keyed fixture with one such binding drops from about 3.7 ms to 0.4 ms in Chromium (about 66 ms to 6 ms in happy-dom) (`KF-5S9XPH`).
|
|
631
|
+
|
|
632
|
+
- `wireTabBars` no longer re-measures every tab strip after every DOM mutation in the root it watches. It used to read computed style and layout for each strip whenever anything under the root changed, such as terminal output or a list update. In Hot Sheet's terminal profile that work was the single hottest function. Now only the bars a mutation touches are re-measured: a change inside a bar, a newly inserted bar, or a `dir` change on an element above one. A strip with a pinned tab also re-measures when its own size changes (`KF-8H2MH2`).
|
|
633
|
+
|
|
634
|
+
- `resource().run()` can be called inside an `effect()`. `run()` read the resource's own state through a tracking read, so an effect that re-ran a resource from an input signal subscribed to that state, wrote it, and threw `Cycle detected`. `run()` and its progress and failure paths now read the state untracked; `resource.value` stays a tracking read (`KF-H5PNHK`).
|
|
635
|
+
|
|
636
|
+
- Re-renders of a large list-free page now scale with the change instead of the page. When a `mount()` render has no `each()` list and no fine-grained bindings, kerf compares the previous and next static HTML, finds the innermost element around the change whose markup parses on its own, and re-parses and morphs only that element's changed children; anything it cannot prove identical to a full diff still takes the full diff. A one-row selection on a 300-row, ~1.4 MB page drops from about 23 ms to 13.5 ms per render in Chromium. One documented behavior narrows: an attribute set imperatively on an element whose markup did not change now survives a render that changed something else, as it already did on a no-op render. The core grows by about 2 KB min+gzip (~13 KB to ~15 KB) (`KF-HA8R27`).
|
|
637
|
+
|
|
638
|
+
- The morph no longer strips the defaults a custom element reflects onto its host. Web Awesome reflects `variant`, `appearance`, `size`, `attention`, and similar defaults onto `wa-button`, `wa-tag`, `wa-badge`, `wa-textarea`, and others; a template that omitted them lost them on every re-render that reached the element, and Lit put them straight back with a full update (one row selection on a 300-row page flipped 1,200 attributes). On custom elements the morph now removes an attribute the template omits only when the previous template rendered it; a template that stops rendering an attribute still removes it, and plain elements are unchanged. An attribute set imperatively on a custom element now survives re-renders (`KF-K8S4RX`). Elements kerf creates (a mount's first render, a morph insertion, a new `each()` row) start with their template's record, taken before they connect, so even the first re-render leaves their reflected defaults alone; only an element kerf did not create uses the ordinary rule on its first attribute sync (`KF-G7N4PK`).
|
|
639
|
+
|
|
640
|
+
- `KUI-L017` (exceptional spacing shorthand, such as `<List gap="s" />`) now has one severity everywhere: a review finding. `eslint-plugin-kerfjs` reported it from the `error`-level `ui-css-values` rule, so a deliberate off-scale choice failed lint while `kerf-ui-analyze` queued it for review, and `kerf-ui-doctor` counted every occurrence twice (error plus review) with a `KUI-D003` conflict warning. The finding moves to a new `ui-exceptional-shorthands` rule, `warn` in both `recommended-ui` and `strict-ui`; `ui-css-values` keeps `KUI-L013`–`KUI-L016` at `error`. The doctor reads an ESLint warning for an analyzer review code as that review finding, and the analyzer's `KUI-L014`–`KUI-L017` messages now match ESLint's word for word, so the doctor merges each CSS-value finding into one diagnostic. A new `@kerfjs/ui` contract test fails if any ESLint UI rule's preset severity disagrees with the analyzer's classification of the codes it reports (`KF-P3945Y`).
|
|
641
|
+
|
|
642
|
+
- `mount()` no longer walks the whole live tree for `each()` list markers after a re-render that changed the page when the render has no `each()` lists and no list is bound. A large list-free page (one `mount()` with plain `.map()`) paid a full DOM traversal per render for markers kerf never emitted (`KF-VBQJAX`).
|
|
643
|
+
|
|
644
|
+
- Faster JSX attribute serialization on large pages: the runtime remembers, per attribute name, that the name passed the `on*` / malformed-name check and whether it is URL-bearing, instead of re-running those regexes for every attribute of every render, and the URL screen returns early for values without a `:` (no scheme to screen). Rejected names still throw their exact message on every render, and every URL value is still screened. Building a 300-row, ~1.4 MB list-free page drops from about 13.7 ms to 10.8 ms of CPU (`KF-VBQJAX`).
|
|
645
|
+
|
|
646
|
+
- `wireScrollDividers` no longer forces a synchronous layout after a render. A content mutation used to re-measure the scrollers in the next animation frame, and a structural one at once in the mutation callback, both before the browser had laid out the new tree. Both now re-measure once the frame has laid out and before it paints: the wiring toggles an inert, zero-size probe outside the app tree, and its `ResizeObserver` reports the probe after layout. Without `ResizeObserver` the previous timing remains. In a 300-row work area, `measure` self time drops from about 408 ms to under 1 ms over 16 segment switches and 8 row selections; the layout itself now runs once, in the browser's frame (`KF-4XYQ95`).
|
|
647
|
+
|
|
648
|
+
- `wireWorkbench` no longer forces a document-wide style recalculation after ordinary renders and presses. It caches each responsive panel's computed overlay state until a Workbench resize, a root font-size change, or a presentation attribute change on that panel, and its observer re-syncs only for a new Workbench, an added or removed panel, or an attribute change on a panel rather than any `data-collapsed` or `data-presentation` change below the root. In a 300-row work area with Web Awesome menus, the overlay check's forced style time drops from about 150 ms to 0 over 16 segment switches and 8 row selections (`KF-CRRD70`).
|
|
649
|
+
|
|
650
|
+
- Faster `PopupMenu` and `LucideIcon` re-renders in large lists. `LucideIcon` returns the same `SafeHtml` for the same icon and props instead of rebuilding its `<svg>` every render (up to 64 prop variants per icon), and builds its child markup as a Fragment instead of wrapping joined strings in `raw()` (`KF-XW15D6`). `PopupMenu` hashes icon and details markup of 64 or more characters as a memoized digest of the whole string instead of reading every character every render. A 300-row list with a nine-entry menu per row drops from about 12.7 ms to 2.1 ms per render when the icons are rebuilt each render, and from 3.9 ms to 1.3 ms when they are prebuilt. A menu with such a part now has a different `data-key` value than before; the key is still stable across renders, and every other byte of the rendered HTML is unchanged (`KF-V2ZBHT`).
|
|
651
|
+
|
|
652
|
+
- `PopupMenu` hashes its content key with a streaming `charCodeAt` loop instead of joining every field (including icon markup) into one string and iterating its code points, and caches each menu's trigger and entry markup in a bounded least-recently-used cache keyed by that hash and an independent check hash. An unchanged menu now costs one hash pass instead of rendering every entry again for the morph to skip. Rendered HTML, including the `data-key` digest, is byte-identical (`KF-GVCMC7`).
|
|
653
|
+
|
|
654
|
+
- Faster attribute serialization for large static values: `LucideIcon` caches each icon node's rendered child markup by node identity, and the JSX runtime's HTML/attribute escaping skips its replace passes when a value has nothing to escape. A 138-icon render pass drops from about 0.80 ms to 0.45 ms (`KF-JPP0Z5`). `jsx()` also iterates props without the rest-spread and `Object.entries` allocations, and the URL screen checks lowercase attribute names without allocating a lowercased copy, about 25% faster for an attribute-heavy list row (`KF-YHNV84`).
|
|
655
|
+
|
|
656
|
+
- `wireTokenSearchFields` collapses an empty field blurred by a pointer press in the click's own task, after the click reaches the window, instead of a separate task, so the click's render and the collapse share one style recalculation; a click that stops propagating still falls back to the next task (`KF-AS24QP`).
|
|
657
|
+
|
|
658
|
+
- `wireScrollDividers` no longer re-collects pairings and re-measures every scroller for mutations that cannot change a pairing, such as a row's selection class or a list morph inside scrolled content; it still refreshes when structural elements or target ids are added, removed, re-classed, or renamed (`KF-50PA0Y`). Those content mutations instead re-measure the known scrollers once in the next animation frame, so an absolutely positioned descendant that extends the scroll area still updates its dividers (`KF-E29N3W`).
|
|
659
|
+
|
|
660
|
+
- The UX Catalog filter keeps its placeholder hidden when a controlled state change rerenders the sidebar while filter text remains (`KF-4EA9R6`).
|
|
661
|
+
|
|
662
|
+
- Inspector TabBars use the shared rounded rectangle radius on the strip and inset tabs while ordinary segmented TabBars retain their pill geometry (`KF-K3RDN1`).
|
|
663
|
+
|
|
664
|
+
- **`KUI-L103` no longer flags a component's classes inside its own source.** `ui-public-boundaries` treats a catalog entry's `source` file as the owner of that entry's public classes, so an app component writing its own root class is not reported as recreating itself. Apps no longer need to mark those classes `placeableClasses` to silence it. Any other file, including another component's source, is still checked (`KF-G6FR6V`).
|
|
665
|
+
|
|
666
|
+
### Documentation
|
|
667
|
+
|
|
668
|
+
- **Imperative nodes inside keyed rows must be marked (KF-TBC6V7).** The render guide explains how an unmarked node can divert a text-only list update and why `data-morph-preserve` is required when adding it.
|
|
669
|
+
- **Nested removal observers use per-root containment (KF-6E8Y2C).** The scope API reference explains that an inner observer disposes a node moved outside its own root, even when it remains inside an outer observed root.
|
|
670
|
+
- **New consumer guides and references.** `ui/docs/view.md` covers `@kerfjs/ui/view` and the `kerf-ui-view` CLI (KF-ABHABR); the doctor, analyzer and evaluator guides gain CLI-option and Node-API tables (KF-GD1BDC); the API reference documents the tooling-facing JSX, brand and dev-hook exports and the `clearDevHooks` / `installDevHooks` signatures (KF-QGKQ0M, KF-FJQP4X); the htmx cart and counter-store apps get their own example pages (KF-GHSA8D).
|
|
671
|
+
- The `@kerfjs/ui` UX catalog's Structured Ticket Search help is lighter: a short title and line, then grouped filter chips (action `Chip`s) that insert their filter into the field, instead of a key/value table. The SearchField examples' notes are shorter too (`KF-XP8742`).
|
|
672
|
+
|
|
673
|
+
- New recipe in the `kerfjs/async` API reference: move heavy app compute (fuzzy search, CSV or markdown parsing, aggregation) into a Worker by having a `resource()` fetcher post a message to the worker and resolve with its reply. It covers request/reply ids, dropping superseded results, worker errors, transferring `ArrayBuffer`s, and keeping the render on the main thread (`KF-04KHT9`).
|
|
674
|
+
|
|
675
|
+
- Clarify for AI consumers that sunken/lowered token names resolve to a translucent tint, and explain intentional nested layers versus duplicate surface paint (`KF-9CM6D8`).
|
|
676
|
+
|
|
677
|
+
- **`layout.roles` vocabulary for app components.** The component-packages guide documents the eleven roles `@kerfjs/ui` uses, what each covers, and how to map application dialogs, rows, status indicators, and composed views onto them. The `kerf.components.json` schema description lists them, and the `create-kerf-component` template now uses `controls` instead of a one-off `counter` role (`KF-4E04HF`).
|
|
678
|
+
|
|
679
|
+
### Removed
|
|
680
|
+
|
|
681
|
+
- **Breaking (`@kerfjs/ui`, 5.0 beta):** remove the Catalog geometry highlight overlay, its `geometryOverlay` prop, `wireCatalogGeometryOverlay` helper, and specimen skip marker. Catalog previews retain their component borders, outlines, and focus states (`KF-E3WKA5`).
|
|
682
|
+
|
|
683
|
+
- **Breaking (`@kerfjs/ui`, 5.0 beta):** remove the deprecated `TabScaffold` component and type aliases, `wireTabScaffold` and `WireTabScaffoldOptions`, and the `tab-scaffold`, `wire-tab-scaffold`, and `tab-scaffold.css` package subpaths. Use `TabNavigator`, `TabNavigatorTab`, `TabNavigatorProps`, `wireTabNavigator`, and their corresponding subpaths. The rendered DOM classes and data attributes remain stable. See `ui/docs/tab-navigator.md` for migration steps (`KF-CMK0W8`).
|
|
684
|
+
|
|
685
|
+
### Added
|
|
686
|
+
|
|
687
|
+
- **Typed background colors on `@kerfjs/ui` layout surfaces.** `Pane` takes `background`, a `CssColor` from `@kerfjs/ui/css-values` (`uiColor(...)`, `fillColor(...)`, or `colorVar(...)`). It paints the whole pane and replaces the default or sunken fill, and it is in `PaneConfig`, so Workbench panels, `CollapsiblePanel`, and `NavStack` view panes forward it. `NavStack` and `TabNavigator` take their own `background` for the stack or navigator surface and their docked bars, and each `TabNavigatorTab` takes one for its scene. Overlay chrome keeps the translucent material, and forced colors paint `Canvas`. Omitted, every surface keeps its current color.
|
|
688
|
+
- **Static-effects switch for `@kerfjs/ui`.** Set `data-kui-effects="static"` on the root element (`document.documentElement.dataset.kuiEffects = 'static'`) to turn every backdrop effect opaque and stop every scroll-driven animation. Use it when the app detects a low-power device itself, since CSS has no reliable signal for one. A slow-updating display (`@media (update: slow)`, such as e-ink) gets the same result automatically. The translucent chrome material (overlay `Pane` headers, `NavStack` and `TabNavigator` overlay bars, floating `DialogSurface` headers) resolves to the opaque surface, as it already does under reduced transparency.
|
|
689
|
+
- `ToolbarControlGroup` takes `material: 'solid' | 'glass'` (default `solid`). A `glass` group paints the translucent chrome material (`--kui-chrome-material`, blurred and saturated by `--kui-chrome-material-filter`), replaces its gray border with a specular edge highlight, and floats on a soft shadow. Use it for per-control glass pills over imagery or a clear (transparent) toolbar, for example inside a `FloatingToolbar`. Its controls take the normal text color, and a raised or outline selection paints an opaque surface pill. Rest, hover, and selected controls keep WCAG AA over worst-case content in light and dark: the bare material leaves the brand selected color at about 3.2:1 over black. The fill turns opaque under reduced transparency, increased contrast, static effects, or without `backdrop-filter`, and the edge gives way to the normal border there. A dark-toned glass group's loud fill turns opaque too. Forced colors paints `Canvas`/`CanvasText` with no filter or shadow. A borderless group ignores the material.
|
|
690
|
+
- **`BackdropImage`.** `@kerfjs/ui/backdrop-image` opens a scrolling Pane or NavStack view with a hero or tiled image (`src`/`srcset`/`alt`, `fit`, `position`, `repeat`, typed `height`). `parallax` (`subtle` or a 0 to 1 factor) lags the image on a compositor-only scroll-driven timeline with no scroll listener or `background-attachment: fixed`; a typed `fadeTo` color dissolves it through a mask and keeps painting under its `children`, so the page reads as one surface; `overlay` content sits over its block end with an optional `scrim`. It is static without scroll-driven animation support, under reduced motion, `data-kui-effects="static"`, or on slow-update displays, and ends on a hard edge over solid `fadeTo` under reduced transparency or increased contrast.
|
|
691
|
+
- **`BackdropImage` progressive blur.** `blur={{ radius?, blurredSrc?, dim? }}` stacks a copy of the image blurred once (a CSS `filter` of `radius`, default 24px, overhanging the block so its fringe is clipped) or an app-supplied pre-blurred `blurredSrc`, and fades only its opacity (plus an optional black `dim` layer) in over the first half of the image's scroll exit, so the blur is at full strength while most of the image is still in view; the filter never animates. A Chromium trace across 200 scroll frames recorded no `Paint` events and no per-frame raster. Static and sharp wherever the parallax is static.
|
|
692
|
+
- `TabNavigator` takes `barPresentation: 'docked' | 'overlay'` (default `docked`). With `overlay`, the tab bar lies over the active scene on the translucent chrome material, so content scrolls visibly beneath it, as under an iOS tab bar. `wireTabNavigator` measures the live bar (bottom safe area included), and the scenes hand its height to their content as the block-end edge inset: a plain scene, a sole `Pane`, or a `NavStack` (whose own overlay bottom toolbar then sits just above the bar) rests its last item clear of it. Unselected and selected labels lift to keep AA over the material. The bar is opaque under reduced transparency, increased contrast, or without `backdrop-filter`, and paints `Canvas` with a `CanvasText` edge in forced colors. Unwired, the bar stays docked. Like the NavStack overlay bars, the tab bar ends where the active scene's classic (space-taking) scrollbar begins, so the thumb and buttons stay visible.
|
|
693
|
+
- `@kerfjs/ui/wire-list-focus-scroll`'s `wireListFocusScroll(root)` brings a keyboard-focused row of a `scrollable` List fully into view, focus ring included, in every engine. Firefox's `focus()` leaves a partly hidden row alone until about half of it is hidden and then centers it, and Safari's never scrolls it, so arrow-key or Tab navigation could rest on a row that was mostly clipped. The wiring calls `scrollIntoView({ block: 'nearest' })` only when a `:focus-visible` element's ring crosses the List's clip, honoring its ring-room scroll padding; pointer focus is left alone, so a click never scrolls its row from under the pointer.
|
|
694
|
+
- **`AnchoredSurface` dark tone for popups anchored to media chrome.** `openAnchoredSurface` and `openAnchoredSurfaceAt` take `tone: 'dark'`, the same loud, inverse tone as a `ToolbarControlGroup` or `ToolbarText` `tone="dark"`. A volume popup anchored to a dark media control group over a video preview is dark beside a light page and light beside a dark one, matching the group that opened it. The surface takes the opposite of its anchor's color scheme when it opens and is marked `data-tone="dark"`. Every semantic token is a `light-dark()` pair, so the content inherits the inverse text, border, and focus colors without tone props or overrides: a `ListItem` mute row and a `wa-slider` included. Measured on the catalog demo in Chromium, Firefox, and WebKit, the row label reads 12.8:1 and its focus ring 8.1:1 on a light page, and 16.8:1 and 4.0:1 on a dark one. The default tone is unchanged.
|
|
695
|
+
- A floating `DialogSurface` title bar (`headerPresentation="floating"`) now draws its divider as scroll state, like an overlay `Pane` header: a 1px line along its bottom edge while the body, or a filling child that reaches beneath it (a transcript `List` or `Pane` with block-start `scrollClearance`), is scrolled away from its top, and none at rest. In light mode the title bar over white bubbles had little separation. `@kerfjs/ui/surface-scaffold/register` follows those scrollers; a nested scroller that starts below the title bar never counts.
|
|
696
|
+
- **Analyzer and lint check row icon-tile colors.** Catalog `cssValueProps` paths now reach a member of an object-valued prop (`iconTile.color`) as well as each array item's member (`choices[].swatch`); a prop given a non-object value, such as a tone string `iconTile="brand"`, is skipped. `ListItem`, `ListItemLink`, and `ListActionRow` record `iconTile.color` as a color fill (`fillColor()`, `uiColor()`, `colorVar()`) and `iconTile.foreground` as a foreground (`uiColor()`, `foregroundColorVar()`, `foregroundColor()`), so the Kerf UI analyzer, `kerf-ui-doctor`, and the `kerfjs/ui-css-values` ESLint rule report `foregroundColor()` on a tile fill (`KUI-L014`) and keep accepting it as the glyph color. The catalog and composition schemas' `path` pattern accepts the same grammar, so consumer catalogs can publish object-member paths (`KF-R02RDK`).
|
|
697
|
+
- **Catalog frames can be a named anchor with a centered content column.** `CatalogExample`'s `viewport` takes `anchorName`, a CSS dashed-ident (`"--app-shell-main"`) that becomes the frame's `anchor-name`, so a top-layer specimen (a `popover="manual"` request popup, say) whose own CSS sets `position-anchor` to that name positions against the frame exactly as it does against its production anchor. An invalid name throws a `TypeError`. `minHeight` adds `"app"` (592px, a floor the frame can grow past), and `contentWidth` (`"compact"` 440px, `"medium"` 640px, or `"wide"` 864px, capped at the frame) with `contentAlign` (`"start"` or `"center"`) gives each in-flow child a centered or start-aligned reading column; `[popover]` children keep their own geometry. An app no longer needs a wrapper stage element to name the anchor and center the column. The catalog's Application Layout page shows a request popup docked to the bottom of its frame (`KF-D532S2`).
|
|
698
|
+
- **`fillColor()` for application fill colors.** `@kerfjs/ui/css-values` adds `fillColor(value)`, the fill twin of `foregroundColor()`: it accepts one application-chosen CSS color (`#3b82f6`, `rgb(20 40 60 / 0.8)`, `rebeccapurple`) with the same single-declaration check, but returns a plain `CssColor` rather than a `CssForegroundColor`, so a fill literal is rejected by props that paint text or an icon (`SelectChoice.color`, `LucideIcon.color`, `Text.color`, an `iconTile` `foreground`). Use it for a `ChoiceChips` `swatch` and a list row's `iconTile` `color`; every example, demo, and design template now does. A `CssForegroundColor` is still a `CssColor`, so an existing `foregroundColor()` fill keeps compiling, and the `ChoiceChips` catalog entry now records `choices[].swatch` as a color fill so the Kerf UI analyzer reports `foregroundColor()` there (`KUI-L014`) with `fillColor()` as the fix (`KF-7JA25S`).
|
|
699
|
+
- **Framed result pickers without app CSS.** `List` takes `frame`, `maxHeight`, and `minHeight` (typed `CssLength`s from `@kerfjs/ui/css-values`). `frame` draws a 1px neutral border with the `--kui-radius-m` control radius and a 4px inset on every side, replacing `inset`, `textInsets`, and `controlInsets`. That inset is exactly a row's focus-ring reach, and the frame adds it to its scroll padding, so the first and last rows' rings stay inside the clip. With `scrollable`, the height bounds work without a flex-column ancestor. `<List scrollable frame gap="2xs" minHeight={rem(4.25)} maxHeight={rem(14)}>` is a bounded list of `ListItem` candidates, such as Hot Sheet's duplicate-ticket picker. The catalog's List page shows it as "Result Picker" (`KF-SHW2J9`).
|
|
700
|
+
- **Transcripts scroll beneath a floating composer.** A `scrollable` `List` and a `Pane` take `scrollClearance` (`"block-start"`, `"block-end"`, or `"both"`; the `ScrollClearance` type). It clears chrome laid over the scroller's block edge inside its own scroll area: the scroller adds the inherited `--kui-scroll-clearance-block-start` / `--kui-scroll-clearance-block-end` context that the chrome publishes to its block padding and `scroll-padding`. Content then passes visibly beneath the chrome, while the first and last items, and anything focused or scrolled into view, still rest clear of it. A `DialogSurface` with `footerPresentation="floating"` publishes block-end clearance for a `fill` or `fill-last` child that opts in. That clearance is the footer's measured height plus its offset. The body stops reserving the footer below that child, so a chat transcript reaches the panel's end and scrolls beneath the transparent composer. Without the opt-in, the transcript still ends at the composer's top. Every dialog body clears clearance inherited from the page. An app that overlays its own translucent chrome on a scrolling region publishes the same context, so header clearance works today. The catalog's chat dialog now scrolls its transcript beneath the composer (`KF-ET0EX8`). `PaneConfig` carries `scrollClearance` too, so a composed Pane opts in through a Workbench `mainPane` or panel `pane`, a `CollapsiblePanel` `pane`, or a `NavStack` view's `pane`; the composites now forward every `PaneConfig` field through one exhaustively typed helper, so a new field can no longer be silently dropped (`KF-574HQV`).
|
|
701
|
+
- **Translucent overlay Pane headers.** `Pane` takes `headerPresentation` (`"docked"`, the default, or `"overlay"`; the `PaneHeaderPresentation` type, also in `PaneConfig`). An overlay header is laid over the top of the scrolling content on the new chrome material. The material is `--kui-chrome-material`, the surface at 80% opacity, behind `--kui-chrome-material-filter`, a blur and saturation backdrop filter, so content scrolls visibly beneath the header. `wireScrollDividers` measures each overlay header with a `ResizeObserver` and publishes its height on the Pane as `--kui-scroll-clearance-block-start`. The Pane's content clears that automatically, so the first item rests just below the header and anything scrolled into view stays clear of it. The clearance follows the header as its title wraps or its text grows. Until the wiring runs, and with `chromePlacement="auto"`, the header stays docked. The material turns opaque under `prefers-reduced-transparency: reduce` or `prefers-contrast: more`, and without `backdrop-filter`. In forced colors the header paints `Canvas` with a `CanvasText` edge. Normal text keeps WCAG AA over any content beneath the material. Quiet text does not, so overlay-header text uses the normal text color (`ui/docs/accessibility.md` "Chrome material"). The catalog's Pane page shows an inbox scrolling beneath its header (`KF-DT6C3F`).
|
|
702
|
+
- **Translucent dialog title bars.** `DialogSurface` takes `headerPresentation` (`"docked"`, the default, or `"floating"`; the `DialogSurfaceHeaderPresentation` type). A floating header lies over the body's block start on `--kui-chrome-material-raised`, a new token for chrome on a raised surface: the raised panel color at 80% opacity behind `--kui-chrome-material-filter`. The `surface-scaffold/register` import now measures the header as well as the footer, and the body reserves the header's height before its own inset, with matching scroll padding, so flowing content starts below the title bar and scrolls beneath it. Without the register, the header stays docked. When the body's only child fills it and opts into block-start `scrollClearance`, the body publishes the header's height as `--kui-scroll-clearance-block-start` instead. With a floating composer and `scrollClearance="both"`, a transcript then scrolls beneath both the title bar and the composer while its first and last messages rest clear of them. The material has the same opaque fallbacks as the Pane overlay header, and normal text keeps WCAG AA over any content beneath it. An untoned `ToolbarText` slotted as the dialog's label (or into its header actions) takes the same AA lift it gets in an overlay Pane header: a normal-color title and a description mixed halfway toward it. The catalog's surface scaffold page adds a "Floating Title Bar" thread dialog (`KF-REH2T2`).
|
|
703
|
+
- **Translucent NavStack top bar.** `NavStack` takes `chromePresentation` (`"docked"`, the default, or `"overlay"`; the `NavStackChromePresentation` type). An overlay top chrome lies over the active view on the same chrome material as an overlay Pane header, so content scrolls visibly beneath it, as under an iOS navigation bar. `wireNavStack` measures the live chrome (never a cross-fading copy) with a `ResizeObserver`, publishes its height on the stack root with a `data-chrome-overlay="measured"` gate, and restores both before paint if a re-render strips them. The measured height, top safe area included, becomes the viewport's block-start edge inset, so a plain view, a sole `Pane`, or a nested layout clears the bar automatically: the first item rests just below it, and focused or scrolled-to content stops clear of it. A classic, space-taking scrollbar in the active view stays uncovered: the chrome ends where its track begins. Unwired, or with `hideToolbar`, the chrome stays docked. The material keeps its opaque fallbacks (reduced transparency, increased contrast, no `backdrop-filter`) and its forced-colors edge, and an untoned `ToolbarText` in the chrome lifts its title and description to AA exactly as in an overlay Pane header. `SplitView` forwards the option through `compactStack`, and a Workbench navigation panel through `navStack`. The catalog's NavStack page adds an **Overlay Chrome** example; `ui/tests/browser/overlay-nav-stack.spec.ts` covers it in Chromium, Firefox, and WebKit.
|
|
704
|
+
- **Translucent NavStack bottom toolbar.** `NavStack` takes `bottomToolbarPresentation` (`"docked"`, the default, or `"overlay"`; the `NavStackBottomToolbarPresentation` type), a separate prop from `chromePresentation`, which keeps governing only the top chrome. An overlay bottom toolbar lies over the active view's bottom edge on the same chrome material, as an iOS toolbar does. `wireNavStack` measures the live toolbar (never a cross-fading copy), publishes its height with a `data-bottom-toolbar-overlay="measured"` gate, and the measured height, bottom safe area included, becomes the views' block-end edge inset: a plain view's or a sole `Pane`'s last item (or the Pane's footer) rests just above the toolbar while content scrolls visibly beneath it, and the toolbar's scroll divider keeps working. Unwired, or while no bottom toolbar is shown, it stays docked; inside a `TabNavigator` scene it sits just above the tab bar. It keeps the material's opaque fallbacks, and in forced colors its top border becomes a `CanvasText` edge. A default-tone `ToolbarControlGroup` in either overlaid bar now lifts its controls to the normal text color, so they keep AA over the content beneath (the top chrome's back control measured about 3.0:1 before). A non-scrolling `List` directly in a `Pane`'s content no longer shrinks below its rows, so the content's block-end padding (a bottom safe area or the toolbar's clearance) follows the last row. `SplitView` forwards the option through `compactStack`, and a Workbench navigation panel through `navStack`. The catalog's **Overlay Chrome** example now overlays both bars; `ui/tests/browser/overlay-nav-stack-bottom.spec.ts` covers it in Chromium, Firefox, and WebKit.
|
|
705
|
+
|
|
706
|
+
- **Anchored surfaces fit beside their anchor.** `positionAnchored()` / `autoReposition()` (and so `popover()` and `tooltip()`) take `viewportMargin`, a gutter in px that the horizontal clamp and the vertical fit test keep from the viewport edges (default `0`, the bare edge as before), and `fitHeight` for an element that scrolls its overflow: when neither side has room for its full height it opens on the roomier side, and every placement publishes that room as the `--kerf-anchor-available-height` custom property on the element, so CSS can cap it (`max-height: var(--kerf-anchor-available-height); overflow: auto`). Scrolling inside the element keeps its scroll position. Without the new options placement is unchanged. `@kerfjs/ui`'s `openAnchoredSurface()` uses both: the surface stays 8px inside the viewport (`viewportMargin` overrides it), caps its height to the room beside its anchor, scrolls its content, and exposes that room to its content as `--kui-anchored-surface-available-height`, refreshed on scroll and resize, so a tall help surface fits beside a field on a phone with no application media queries (`KF-K4GE6K`).
|
|
707
|
+
|
|
708
|
+
- **Stateful `TokenSearchField` trailing action.** `trailingAction` now takes `expanded` (a disclosure such as a help toggle; renders `aria-expanded`) or `pressed` (a toggle; renders `aria-pressed`), which are mutually exclusive at compile time, plus `controls` (`aria-controls`), `haspopup` (`aria-haspopup`), and `attributes` for domain `data-*` metadata (the field keeps `data-action`). An open or pressed button keeps its hover fill and reads at full text strength. In the `toolbar-group` presentation it now takes the clear button's control-highlight radius, so the compact 24px help glyph beside the clear button matches it in every presentation with no application CSS. The catalog's Structured Ticket Search help toggle opens syntax help in an `openAnchoredSurface` (`KF-R056AJ`).
|
|
709
|
+
|
|
710
|
+
- **Link `Chip` for downloadable files.** `Chip` takes an `href`, with an optional `download` (`true` or a suggested file name) and `external` (new tab, `rel="noopener noreferrer"`, and an "(opens in new tab)" accessible-name suffix, as on `ListItemLink`). It then renders a native `<a>` with the chip's geometry, icon slot, truncation, focus ring, and hover feedback, so an app no longer styles its own file-link chips. A link chip cannot also carry a remove button, and a disabled one drops its destination and leaves the tab order. The new `inherit` tone (`ChipTone`) follows the surrounding foreground, for a chip inside a `brand-loud` or `neutral` `ContentItem` bubble. It draws a currentColor border and no fill, so the label keeps the bubble's text contrast, and its focus ring follows the foreground too. The Chip catalog shows file chips in both bubble kinds (`KF-H658D6`).
|
|
711
|
+
|
|
712
|
+
- **Multi-select `ChoiceChips`.** Set `multiple` with a `readonly Value[]` `value` and the same wrapping pills, swatches, and icons become native checkboxes in a named `role="group"`: each pill is its own Tab stop, Space toggles it, assistive technology reads its native checked state, and every checked value submits under `name` (`FormData.getAll(name)`). The props are a discriminated union, so a multiple group rejects a single value (and a single group an array), and a multiple group takes no `required`. Every chip color is a theme token, so on dark inverse chrome, such as a media viewer's annotation intents, place the chips in a dark appearance scope (`.wa-dark`) rather than restyling them. The UX catalog adds Multiple Selection and On Dark Chrome examples, and the design templates add a Multiple Selection variant.
|
|
713
|
+
- `ListItem`, `ListItemLink`, and `ListActionRow` take an `iconTile` prop that presents the leading icon in a filled 32px rounded tile holding an 18px glyph, for settings and command rows identified by color. Pass a tone (`neutral`, `brand`, `success`, `warning`, or `danger`, the same quiet palette as `ToolbarControlGroup.tileTone`) or `{ color, foreground? }` with a typed `CssColor` fill (`uiColor()`, `colorVar()`, or `foregroundColor('#e5484d')`) and an optional `CssForegroundColor` glyph; without a foreground, the glyph is black or white, whichever contrasts with the fill. The tile keeps 6px clear of a standard 44px row, a compact row is at least 42px tall, the label moves to the tile's edge, and hover and selection leave the tile's colors alone.
|
|
714
|
+
|
|
715
|
+
- **A chat composer without app chrome.** The new `Composer` (`@kerfjs/ui/composer`) is a raised frame (the standard border, large radius, and `shadow-l`) whose border turns brand while focus is within. It holds a borderless textarea that grows with `field-sizing: content` between `minRows` (default 1) and `maxRows` (default 8) lines and then scrolls. Below the textarea sits an action row with an optional quiet `hint`, which describes the field when you pass an `id`, and the trailing `actions` (a Send button). Engines without `field-sizing` show a fixed three-line field that scrolls. Slot it into a `DialogSurface` floating footer to float it over a transcript; the catalog's chat dialog now does (`KF-S5EG5K`).
|
|
716
|
+
- **Enter-to-send for `Composer`.** Set `submitOnEnter` and call `wireComposers(root)` (`@kerfjs/ui/wire-composers`) once: Enter, or Cmd/Ctrl+Enter, in the field clicks the composer's first trailing action, so a keyboard send runs the same delegated `data-action` handler as a click. Shift+Enter still inserts a newline. An Enter that commits an IME composition (`isComposing`, keyCode 229, or between `compositionstart` and `compositionend`) is left to the input method, and an empty or whitespace-only message, an auto-repeating key, a disabled field, or a disabled or loading action sends nothing. The field announces the shortcut with `aria-keyshortcuts="Enter"`. The catalog's Composer and chat dialog examples use it (`KF-DGD5QS`).
|
|
717
|
+
- `PopoverDialogSurface` takes an optional `describedBy` id, rendered as `aria-describedby` on its `role="dialog"` root. Pair it with a title `ToolbarText`'s `descriptionId` so a non-modal dialog keeps its accessible description; `rootAttributes` accepts only `data-*` attributes, so there was no way to set it before. `DialogSurface` is unchanged, because it wraps a `wa-dialog` that the app authors and does not render the dialog root itself (`KF-SKVEQW`).
|
|
718
|
+
- A compact `ListActionRow` is 36px tall, as documented, instead of 44px. Its label kept the standard row's minimum height and its primary button kept the standard 8px block padding, so `density="compact"` had no effect on a single-line row. Compact rows now use 4px block padding like a compact `ListItem`, so the two row kinds stay level in a dense list; a compact row with an `iconTile` is exactly 42px. The ListActionRow catalog adds a Compact Rows example (`KF-4Q5MJ5`).
|
|
719
|
+
- `ListActionRow` leading icons default to 18px (they were 24px), the same size as `ListItem` icons, so a `List` that mixes the two row kinds starts their labels on one edge, not 6px apart. Both read a new shared `--kui-list-row-icon-size`: set it on a containing `List` to resize both row kinds' untiled icons together. `--kui-list-item-icon-size` still wins for `ListItem` rows that set it, and an `iconTile` keeps its 32px tile and 18px glyph. An app that wants the old 24px `ListActionRow` glyphs sets `--kui-list-row-icon-size: 24px` on the list (`KF-KWFMM1`).
|
|
720
|
+
- `ListItem` and `ListActionRow` share one leading inline inset. Set `--kui-list-row-padding-inline` on a containing `List` and both row kinds move their content and reorder insertion lines together; a `ListActionRow` adds the 1px a `ListItem` border takes, so their leading icons stay on one edge at any value. It defaults to `--kui-layout-item-padding`, so unset lists render as before. Previously only `ListItem` had an inline padding token, and overriding it moved `ListItem` icons away from `ListActionRow` icons in the same list. `--kui-list-item-padding-inline` still wins for `ListItem` rows that set it. The List catalog's new Shared Row Inset example shows mixed rows on a customized inset (`KF-N3TDV3`).
|
|
721
|
+
- `@kerfjs/ui` now has one capitalization rule for interface copy, taken from Apple's guidance and documented in the new `ui/docs/writing.md`. Text that names a command, control, view, or field is title style ("Save Draft", "Back to Inbox", "Workspace Settings"): buttons, menu items, segments, `Select` choices, tabs, titles, `ListHeader` labels, and field labels. Text that describes, explains, or reports is sentence style: descriptions, messages, tooltips, placeholders, option text, and status lines. The AI skill, `llms.txt`, and the design docs carry the rule. `kerf-ui-doctor` reports a lowercase word in a known title-style label as the warning `KUI-D040`, with the repaired label. The catalog demos, recipes, and design templates now follow the rule (`KF-6VWSV4`).
|
|
722
|
+
- **Chat-style dialogs without `::part()` rules.** `DialogSurface` gains `footerPresentation="floating"`, which lays the footer over the body's block end, a typed `footerOffset` from the panel's inline and block-end edges (default the 16px container inset), on a transparent background. The `surface-scaffold/register` import measures the footer, and the body reserves that height plus the offset, so a growing composer never hides the transcript's last message. `bodyLayout="fill-last"` (also on `PopoverDialogSurface`) keeps the body's leading children at their natural height and gives the last child the remaining height and its own scrolling: a notice above a scrolling transcript. The catalog's new chat dialog example composes both (`KF-913AT2`).
|
|
723
|
+
- `@kerfjs/ui`'s title-style rule now reaches the names the doctor could not see. `TokenSearchField`'s default `clearLabel` is `Clear Search` (it was `Clear search`); a test or app that addresses the clear control by its default accessible name needs the new spelling, and `clearLabel` still overrides it. The catalog shell (`Filter Catalog`, `Clear Filter`, `Reduce Motion`, `Vertical Stripes`, `Layout Guide`, `Related Entries`, `Capture Region`, the `Demo Source` / `Component Source` / `Design Template` / `Integration Guidance` resource links, and the `Used By` related group), the catalog entry names that render as page titles (`Foundation Tokens`, `Surface Scaffolds`, `List Workspace States`, …), and the demos' and recipes' accessible region, control, field, dialog, tab, and list-item names are title style. `kerf-ui-doctor`'s `KUI-D040` now also reads the accessible names of icon-only controls: `IconButton` / `IconToggleButton` / `PopupMenu` `label`, `SplitButton` `optionsLabel`, `TokenSearchField` `clearLabel`, and the `aria-label` of a `button` or `wa-button` whose only content is an icon (`KF-ZAD6EJ`).
|
|
724
|
+
- `@kerfjs/ui` catalog example and stack labels are headings, so they now use title style across every UX-demo page ("Heading Identity Stays Whole", "Icon Trigger in a Toolbar Group"); their notes stay sentence style. Demo content item titles ("Build Output", "Work Area") follow, with mirrored `ariaLabel`s. `kerf-ui-doctor`'s `KUI-D040` now reads `CatalogExample` and `CatalogExampleStack` `label`, and keeps a minor word inside a longer hyphenated compound lowercase ("Edge-to-Edge"). A test that addresses a demo specimen by its region name needs the new spelling (`KF-4TXTVV`).
|
|
725
|
+
- A labelled `CatalogExample` now names its `section` with its label, so each specimen is a named region that assistive technology and `getByRole('region', { name })` can address. An unlabeled example stays an ordinary grouping (`KF-ZQMXK1`).
|
|
726
|
+
- `CatalogExampleStack` takes a `width` option: `reading` (default) keeps the 736px reading measure, and `full` lets the stack span the stage so a catalog can show application-width compositions such as boards, app shells, drawers, and split views without clipping them (`KF-HKVT5S`).
|
|
727
|
+
- `CatalogExample` `viewport.width` takes `sidebar`: a 272px production-rail width, capped at the stage, so sidebar-pane specimens render at their real width without a wrapper (`KF-DH5MH8`).
|
|
728
|
+
- In a `PopupMenu` level (the top menu or one submenu) that holds a checkbox choice, plain commands now reserve the check column too, so check, icon, and label columns line up across checked, unchecked, and plain rows; a level without a choice keeps the compact start. Submenu checkbox rows drop an extra 1em label inset, so their icon-to-label gap matches the top level (`KF-31QHPE`).
|
|
729
|
+
- Hovering a selected (`aria-current`) or pressed `ListItem` likewise keeps its selected tint instead of the neutral hover colors (`KF-84AGE5`).
|
|
730
|
+
- Hovering a selected or pressed `ListActionRow` keeps its selected tint instead of switching to the neutral hover colors, so a freshly selected row no longer looks unselected while the pointer stays on it (`KF-Z737D0`).
|
|
731
|
+
- A `width="full"` `CatalogExampleStack` now spans the whole catalog stage on wide screens; the stage's 1120px canvas cap no longer stops it short of the right edge (`KF-WDSFWH`).
|
|
732
|
+
- **Chat-bubble `ContentItem`s.** `bubble="start" | "end"` lays a `ContentItem` out as a transcript bubble: it fits its message up to 80% of the row, sits at the start (other participants) or end (the person's own messages), and wraps long unbroken text. The new `appearance="brand-loud"` paints the solid brand fill with its on-loud foreground for the person's own messages (`KF-M3HJK8`).
|
|
733
|
+
|
|
734
|
+
- **`DialogSurface rootAttributes`.** `DialogSurface` takes safe `data-*` `rootAttributes`, such as a `data-key`, on its root; its own configuration attributes stay protected. Sibling dialogs that render conditionally then morph by identity rather than by position. Before, a re-render could reuse one open dialog's element for another, swapping its accessible name and suppressing `wa-after-hide`. Apps no longer wrap each dialog in a keyed `div` (`KF-D7H0WN`).
|
|
735
|
+
|
|
736
|
+
- **Heading supporting text.** A read-only `ToolbarText` takes `description`: quiet, single-line, truncating copy under the title ("Changes save automatically."). It starts at the title's text whether or not a leading icon group is present, and shares the control band so trailing actions stay aligned. `descriptionId` gives it an id for `aria-describedby`. With a description, `id` and `headingLevel` apply to the title span alone, so `aria-labelledby` names only the title. Apps no longer recompute the title inset from toolbar tokens (`KF-DXVMBN`).
|
|
737
|
+
|
|
738
|
+
- **Drag-to-reorder list rows in `@kerfjs/ui`.** `ListItem`, `ListItemLink`, and `ListActionRow` take `draggable`, `dragging`, and `dropPosition: 'before' | 'after'`: a draggable row is a native HTML drag source (never while it is a loading placeholder), a dragging row dims, and a drop position draws a 2px brand insertion line on that edge of the row (`--kui-list-item-drop-indicator` / `--kui-list-action-row-drop-indicator` and matching width and dragging-opacity tokens; system `Highlight` in forced colors). The new `@kerfjs/ui/wire-list-reorder` subpath adds `wireListReorder(root, { onReorder })`, which paints those states during a pointer drag, moves rows with Alt+Shift+ArrowUp/ArrowDown and restores focus after the re-render, and reports `{ listId, sourceIds, target: { id, position }, source }`; dragging a selected or pressed row moves every selected row of its `List`. `reorderListItems` applies the change to an array. Apps no longer hand-style dragged rows and insertion lines (`KF-HWYE11`).
|
|
739
|
+
|
|
740
|
+
- **Compact `Toolbar` density.** `Toolbar density="compact"` makes a 40px header for a panel embedded in a card or inspector: a 34px control band (the compact `ToolbarControlGroup` size) with 3px block insets, keeping the 8px inline insets and zone gap. Fill it with `size="compact"` groups. `--kui-toolbar-inset` still overrides the block inset Composite toolbars forward `density` from their `ToolbarConfig` (Workbench panel, main, and bottom toolbars, CollapsiblePanel, NavStack, SplitView) and size the groups they compose (panel and relocated toggles, the back button) to match; `CollapsiblePanelRelocated` takes `density` for its destination toolbar (`KF-0QDF0V`, `KF-QPSTTA`).
|
|
741
|
+
|
|
742
|
+
- **`ChoiceChips` for a wrapping exclusive choice.** `@kerfjs/ui/choice-chips` renders one choice from a visible set too large for a `SegmentedControl` track, such as a nine-color palette in a 560px dialog, as separate pills that wrap with the standard 8px gap at any width. Each pill is backed by a native radio in a named `role="radiogroup"`, so the group is one Tab stop, arrow keys move the selection, and the checked radio submits under `name`. A choice may lead with a `swatch` (a `CssColor`, or `'transparent'` for an outlined dot struck through diagonally) or a decorative `icon`; the group takes `label` or `labelledBy`, a controlled `value`, a delegated `action` for `change`, `size="compact"`, `required`, and group or per-choice `disabled`. Use it instead of wrapping a segmented control or button-appearance `wa-radio` set, whose joined borders turn ragged across rows (`KF-EJPYWD`).
|
|
743
|
+
|
|
744
|
+
- **Viewport-locked app root.** In the opt-in `@kerfjs/ui/document.css` baseline, `data-viewport="locked"` on a body-child `.kui-app-root` gives `html`, `body`, and the root `height: 100dvh` and `overflow: clip`. Mobile browser toolbars can then never leave the root taller than the visible area, and the document itself never scrolls; only the shell's panes do. `docs/document-baseline.md` covers the on-screen keyboard (`KF-1XNQYP`).
|
|
745
|
+
|
|
746
|
+
- **Semantic cursors in `document.css`.** The opt-in `@kerfjs/ui/document.css` baseline now gives native controls semantic cursors with zero specificity: `pointer` on enabled buttons, links, `role="button"`, `summary`, selects, checkbox/radio/button-type inputs, and labels around checkboxes or radios; `not-allowed` on disabled controls, `aria-disabled` role buttons, and a disabled `wa-button`'s `base` part (Web Awesome 3.12 leaves a pointer there); and `text` on text-like inputs and textareas. Components and applications keep their own cursors (`KF-C336VV`).
|
|
747
|
+
|
|
748
|
+
- **`Badge maxWidth`.** A text `Badge` takes `maxWidth` (a `CssLength`). Longer text truncates with an ellipsis inside a new `kui-badge__label`, the badge may shrink below the cap in a tight row, and string or number content becomes the native `title` tooltip unless `title` is supplied (`KF-0WKZY2`).
|
|
749
|
+
|
|
750
|
+
- **`Text align`.** `Text` takes `align="start" | "center" | "end"` (default `start`), so centered status copy that wraps in a narrow surface, or an end-aligned value, uses `Text` directly instead of an app rule on `.kui-text`. Start and middle truncation align their single line to match (`KF-MMAWEG`).
|
|
751
|
+
|
|
752
|
+
- **`SummaryRow`.** `@kerfjs/ui/summary-row` is a selectable, focusable summary of one item (`role="option"`) as a list `row` (bottom divider, `listEdge` rounding for rounded sections) or a board `card`. It has a leading glyph, a semantic `rail`, an identity `title` clamped to `titleLines` (two for rows, four for cards) with `trailingMeta` floated at its end, and a wrapping `metadata` line. Kerf owns hover, focus, `selected`, `dimmed`, narrow compaction, and optional `deferRendering` for long lists (`KF-XCFMX8`).
|
|
753
|
+
- **`Combobox`.** `@kerfjs/ui/combobox` is a free-text field with filtered suggestions that can also create a new value (tags, labels): a native input with the themed field chrome and a 16px font floor on touch devices, on the ARIA combobox pattern (`role="combobox"`, `aria-activedescendant`, a listbox of options). `wireComboboxes(root, { onCommit })` from `@kerfjs/ui/wire-comboboxes` filters as people type, moves the active option with the arrow keys, and reports `{ id, value, created, input }` on Enter, a comma, or a click; `createLabel={false}` allows only suggestions (`KF-XDVAMR`).
|
|
754
|
+
- **File picking and dropping.** `@kerfjs/ui/file-picker` adds `FilePickerTrigger` (a compact, link-toned browse control) and `FileDropZone` (a dashed target that also opens the chooser), both around visually hidden native file inputs with visible focus rings. `wireFilePickers(root, { onFiles })` from `@kerfjs/ui/wire-file-pickers` reports browsed and dropped files, filters drops by `accept` (exported as `fileMatchesAccept`), marks a zone `data-dragging` while files are over it, and resets the input so the same file can be chosen again (`KF-RDV6V9`).
|
|
755
|
+
- **`ContentSwap`.** `@kerfjs/ui/content-swap` swaps two contents in one shared cell (a dialog's two steps, a footer's changing actions) with a `push` (forward or backward, mirrored in right-to-left documents), a `crossfade`, or no motion. Kerf owns the keyframes, the reduced-motion fade, and the inactive side's `inert` and `aria-hidden`; `label` makes it a named region and `slot`/`fill` place it in a dialog label or footer (`KF-V7MZY9`).
|
|
756
|
+
- **`ColumnTrack` for boards.** `@kerfjs/ui/column-track` is a horizontal scroll owner for columns that share the width equally but never narrow below `minColumnWidth` (250px), so a narrow board scrolls instead of crushing them. `layout="paged"` shows one near-full-width column per page with a `peek` of the next, mandatory start snapping, a hidden scrollbar, and smooth scrolling unless reduced motion is preferred (`KF-9WEWRF`).
|
|
757
|
+
- **`EdgeActivityIndicator`.** `@kerfjs/ui/edge-activity-indicator` is a layout-free, pointer-inert activity strip pinned below the top safe area (or flush). While `busy` its thin bars ripple in a traveling wave, drawn by one gradient and an animated mask with no per-bar elements or resize script, and an optional `message` hangs from the edge as a polite status pill. It takes a semantic `tone`, scales in from the edge, and only fades under reduced motion (`KF-CS729Y`).
|
|
758
|
+
- **`ValueTable` layout props.** `labelWidth` (a typed length) gives labels a minimum column and the value the rest of the row; `presentation="stacked"` puts each value under its label, starting at the label's text; and `stackBelow="compact" | "narrow"` stacks only while the table itself is narrower than 512px or 576px (a stacking table fills its container's width). Apps no longer override `--kui-value-table-row-columns` and the row gap/padding tokens for this (`KF-BTMDH5`).
|
|
759
|
+
- **`SplitButton`.** `@kerfjs/ui/split-button` renders a primary action and an attached options trigger on one loud semantic fill (`tone`: brand, neutral, success, warning, danger) with `fill` for full width, `busy` (a spinner and `aria-busy`), and separate `disabled`/`optionsDisabled`. Both halves are native buttons, so the options trigger's `aria-expanded`, `aria-haspopup`, and name reach assistive technology, which a `wa-button-group` could not (`KF-KFC7C2`).
|
|
760
|
+
- **`IconToggleButton` for standalone icon toggles.** `@kerfjs/ui/icon-toggle-button` renders a native `aria-pressed` button with a single contained `ToolbarControlGroup`'s 44px geometry and raised pressed face (pill or rounded), for content and pane footers where a `Toolbar` does not belong and `ToolbarControlGroup`'s toolbar-parent rule (`KUI-L201`) applies. Its required `label` names it and, with help tags registered, shows on hover and focus (`KF-HBWDHE`).
|
|
761
|
+
- **Selected-chrome opt-out for icon-state toggles.** `ToolbarControlGroup` `selectedChrome="none"` keeps pressed controls looking like their neighbors, and `data-selected-chrome="none"` on one button opts out just that control, for a toggle whose glyph already shows its state (an empty or filled star). Hover and focus treatment are unchanged (`KF-GGDABA`).
|
|
762
|
+
- **`FramedList` for inset-grouped rows.** `@kerfjs/ui/framed-list` draws `ValueTable`'s rounded, bordered frame (lowered or base surface) around `FramedListRow`s of arbitrary content, with each row owning its 8px inset, a 44px minimum height, the inset divider above it, and an optional `highlighted` tint. Settings, account, and shortcut lists no longer need a hand-rolled `ul` stylesheet (`KF-2HB7RT`).
|
|
763
|
+
- **ARIA root attributes and a document inset for `List`/`Row`.** `rootAttributes` on a `List` or `Row` now also accepts `aria-*` attributes and a structural `role` (`region`, `group`, `list`, `status`, landmarks, …), so a labeled drop-target region or an `aria-busy` stack needs no wrapper; widget roles are dropped, and a multi-select List keeps owning its grid role and name. `List` `inset="document"` adds a reading inset (24px block, 32px inline, 16px inline below 576px) for reader views (`KF-DNZJCG`).
|
|
764
|
+
- **`Badge` icon, title, and identity.** A text `Badge` takes a decorative leading `icon` (4px before its text, like `Chip`), and every Badge takes a `title` tooltip and safe `data-*` `rootAttributes`, so apps no longer wrap a Badge for status identity or nest a `Row` inside it for icon spacing. A text Badge with a `label` is now a labeled image (`role="img"`), so that name is actually exposed in place of its abbreviated visible text (`KF-2YKKK5`).
|
|
765
|
+
- **`IconButton` for icon-only Lucide buttons.** Web Awesome gives a `wa-button` its square icon-button geometry only when its label holds a lone `wa-icon`, so a button whose only child was a `LucideIcon` kept text-button padding and did not match an adjacent field. `IconButton` (`@kerfjs/ui/icon-button`) renders a `wa-button` with a `LucideIcon` as a square one form-control height on each side, takes a required `label` that names it, and keeps that square beside a field in a `ListInsetControl` (`KF-1315VN`).
|
|
766
|
+
- **`List` surface.** `surface="base"` or `"raised"` paints `--kui-color-surface` or `--kui-color-surface-raised` behind a List and its insets, so a banner strip above a sunken work area no longer needs an app wrapper whose only CSS is a background. A lowered region remains a `SunkenPanel` (`KF-ZKYYH1`).
|
|
767
|
+
- **`CornerStatus` for non-dismissible app-level progress.** The new `@kerfjs/ui/corner-status` component hosts one or more `StateBanner`s at a viewport corner (`placement`: `bottom-end` by default, `bottom-start`, `top-end`, or `top-start`, RTL-aware) with a 16px gutter plus device safe-area insets. It is a native `popover="manual"` in the top layer, so it sits above fixed and z-indexed page chrome, and it has no close button, light dismiss, Escape handling, or focus change. `wireCornerStatus` (`@kerfjs/ui/wire-corner-status`) opens each host as renders insert it; the app removes the host when the work ends. Inside it, a banner drops its inline margin, gains elevation, and paints its tone fill over the opaque surface. `presentation="embedded"` renders the same stack in flow. This replaces fixed-position app CSS around a `StateBanner` and hiding a toast's close button (`KF-PZCPHQ`).
|
|
768
|
+
- **`StateBanner` strip presentation.** `presentation="strip"` renders a full-width status band for a layout edge, such as above a workspace: flush (no inline margin), square, with its copy on the shared content-text column and only tone-colored `dividerSides` edges (bottom by default; `''` draws none). Apps no longer zero the card's margin, radius, padding, and border tokens and draw their own per-tone rule. The default `card` presentation is unchanged (`KF-JQ8FB0`).
|
|
769
|
+
- **Dialogs that fill, and a non-modal dialog surface.**
|
|
770
|
+
- `DialogSurface` gains `height`: a definite modal height bounded by the dynamic viewport minus both gutters, like `maxHeight`. It also gains `bodyLayout="fill"`, which gives the body's whole height to one child (a `SplitView` or `Pane`) that owns its scrolling.
|
|
771
|
+
- The new `PopoverDialogSurface` in `@kerfjs/ui/surface-scaffold` is the non-modal counterpart. It is a native `popover="auto"` `role="dialog"` section that light-dismisses on Escape or an outside press and leaves the page interactive.
|
|
772
|
+
- It owns Kerf's dialog chrome and takes the same `size` / `preferredWidth` / `viewportGutter` / `height` / `maxHeight` / `bodyLayout` props, and it centers in the top layer whatever alignment its host sets. `presentation="embedded"` renders it in flow for catalogs and inline previews.
|
|
773
|
+
- Apps no longer hand-build popovers with their own chrome, viewport math, `:popover-open` grid, and embedded resets (`KF-XHECB9`).
|
|
774
|
+
|
|
775
|
+
- **Sunken surfaces have a fine grain texture.** Every sunken surface paints the new `--kui-sunken-surface`: a seeded 100px monochrome Gaussian grain tile at 4% maximum opacity, over the lowered color. That covers `SunkenPanel`, sunken `Pane`, Workbench regions, TabNavigator scenes, Web Awesome `appearance="sunken"`, and the catalog's lowered specimen viewport. The tile is generated once per page at runtime by the first sunken surface that renders, so no asset ships. `ensureSunkenTexture()` (exported from `@kerfjs/ui` and `@kerfjs/ui/sunken-panel`) covers pages with only Web Awesome sunken surfaces. Set `--kui-sunken-texture: none` at `:root` for the previous flat surface. An app's `--kui-sunken-panel-background` / `--kui-wa-sunken-background` override still wins (`KF-GMAK3H`).
|
|
776
|
+
|
|
777
|
+
- **Required wiring can be root-delegated actions.** Composition catalogs and `kerf.components.json` accept `wiring.actions`, the `data-action` values the app must handle with its own root `delegate()` / `delegateActions()` listener. Required wiring now names at least one helper _or_ action, so an app no longer has to mark such wiring `required: false` and weaken the check. `eslint-plugin-kerfjs`'s `ui-wiring` reports each unhandled action as `KUI-L401`. An action counts as handled when a reachable module imports a Kerf delegation API and names it as a string, selector, or table key. Comments and the component's own source do not count (`KF-AF5KD5`).
|
|
778
|
+
|
|
779
|
+
- **`kerf.components.json` declares where app-owned wiring helpers live.** `composition.wiring.sources` lists each application helper's `{ export, source }`. The generator verifies that the helper is in `helpers`, that the file exists, and that the file exports it. `ui-wiring` then resolves the app's relative imports of that helper, so page-root wiring with helpers such as `wireTicketSearchFields` no longer raises `KUI-L401`. `composition.wiring.scope` (`application` or `module`) is now authorable too. Both fields were previously expressible only in a hand-written catalog (`KF-YZE3DP`).
|
|
780
|
+
|
|
781
|
+
- **`kerf.components.json` zones can name their JSX prop.** A zone may declare `jsx: { prop }` (`children` for the default slot). The prop must be unique per component, and the generated composition catalog keeps it, so `ui-composition` maps a prop's value to its zone exactly as it does for `@kerfjs/ui`'s own catalog (`KF-99Z95S`).
|
|
782
|
+
|
|
783
|
+
- **Context `PopupMenu` owns its anchor.** A context-mode menu takes an `anchor: { x, y }` prop in viewport pixels and renders the point into its own template, so the point survives re-renders and a menu rebuilt with changed items. Open it with the new `openPopupMenu(menu)`; `openPopupMenuAt` still works for menus without `anchor`. The menu's root is now out of flow (`position: fixed`, 0×0). Previously its 0×0 `inline-block` added a line box in block layout and an extra gap slot in a flex row. Apps no longer need a fixed, 1px, z-indexed wrapper, and no z-index is needed because the open menu is in the top layer (`KF-FXGW0C`).
|
|
784
|
+
|
|
785
|
+
- **`SplitView` `listWidth`.** Size the fixed list column with a prop instead of a raw token: a number of CSS pixels, or `{ size, maxFraction }` to cap it at that share of the split's own width (`{ size: 432, maxFraction: 0.5 }` is 432px until the split is narrower than 864px). A narrow dialog then always leaves the detail in view. It is validated, and it throws when combined with `resizable`, which already sizes the list. The guide now states, and browser tests pin, that a SplitView fills any container with a definite height: a block box, a fixed-size popover, a flex column below a header, or a grid. Apps do not need a `display: grid` / `minmax(0, 1fr)` wrapper (`KF-7R5NWM`).
|
|
786
|
+
|
|
787
|
+
- **`Text` truncates at the start or in the middle.** With `wrap="truncate"`, the new `truncate` prop places the ellipsis at the `end` (default), the `start` (keeping the tail, for branch names), or the `middle` (keeping a suffix, for file paths). `truncateKeep` chooses that suffix: the last path segment (default) or a number of trailing characters. Start truncation uses an isolated left-to-right run instead of a bare `direction: rtl`, so punctuation stays in place. Both positions keep the whole value in the DOM and show it as the `title` unless the app sets one. Apps no longer need split spans or rtl CSS for this (`KF-XYA6VR`).
|
|
788
|
+
|
|
789
|
+
- **A trailing overflow menu for `ListActionRow`.** Pass `trailingMenu: { label, icon, items, placement?, disabled? }` instead of the `trailingAction*` props and the row renders a real `PopupMenu` (icon-only, no caret, opening `bottom-end` by default) as its sibling trailing control, so a command row with a "…" menu of Edit and Delete no longer needs a control inside dormant content or an override. The types accept exactly one trailing control. `trailingActionVisibility="interaction"` reveals the menu trigger on hover or focus and keeps it visible while the menu is open; a placeholder row disables it. `openPopupMenuAt` now also opens a button-triggered `PopupMenu` at a pointer position: for that opening the menu anchors at the point and opens `bottom-start`, then returns to its trigger and placement once it closes. A row can therefore open its trailing menu from its own `contextmenu` handler (`KF-VWTCYB`).
|
|
790
|
+
|
|
791
|
+
- **UX Review capture for catalogs served without Vite.** `@kerfjs/ui/vite-ux-review` now also exports the endpoint behind the catalog's **Capture region** link in server-neutral forms: `resolveUxReviewProject({ root?, projectDirectory? })`, `uxReviewProjectResponse(request, projectDirectory)` for Fetch API servers (Hono, Bun, Deno), and `uxReviewMiddleware(projectDirectory)` for Node/connect servers (Express, `node:http`). An app that serves its UX catalog from its own backend mounts one on its development server instead of hand-rolling the route. `uxReviewPlugin()` is now built on the same middleware, with unchanged behavior (`KF-PFF721`).
|
|
792
|
+
|
|
793
|
+
- **A per-entry settings pane in `@kerfjs/ui/catalog`.** Pass an entry's variant and state controls as `Catalog`'s new `settings` prop and the Catalog renders a **Settings** pane beside the stage, with the standard collapse toggle: in the pane's header while open, at the end of the entry toolbar while collapsed. Entries without settings render neither the pane nor the toggle. The app owns `settingsCollapsed`; hand the same signal to `wireCatalog`'s new `settingsCollapsed` option and it flips the signal from the toggle (`onToggleSettings` reports it) and wires the pane as a Workbench rail, so below the `narrow` breakpoint it starts collapsed and opens as an overlay that Escape or an outside press closes, exclusive with the sidebar overlay. `settingsPanel` sets the title, width, resizing, and overlay options (`settingsSize` / `settingsStorageKey` remember a resized width). The UX catalog's Badge entry demonstrates it with a playground. Consumers no longer build their own settings aside and toggle (`KF-0AY6AE`).
|
|
794
|
+
|
|
795
|
+
- **`kerf-component-catalog` generates the selection catalog too.** Packages and apps that keep `kerf.components.json` no longer hand-maintain a second selection JSON (`useWhen`, `avoidWhen`, `publicClasses`, `publicTokens`, …) for `@kerfjs/ui`'s component-catalog extension. Set `package.json#kerfComponentCatalog.selectionOutput`, add a top-level `description` and a per-component `selection` block (`useWhen`, `avoidWhen`, optional `uses`, `styleSources`, `demoSource`, `documentation`, and a `geometry` override), and `--write` / `--check` emit and verify the selection catalog beside the composition catalog. `name`, `kind`, `purpose`, `source`, `publicClasses`, `publicTokens`, and `geometry` come from the existing metadata; the composition catalog's `compatibility.componentCatalog` points at the selection file. The output is validated against the canonical selection schema, which `create-kerf-component` now ships. Recipes are not selection entries, `composed` geometry needs an explicit override, and `uses` must name this package's components or installed `@kerfjs/ui` catalog ids (`KF-K1SY5X`).
|
|
796
|
+
|
|
797
|
+
- **UX Review capture in any `@kerfjs/ui/catalog` app.** The catalog's **Capture region** header link, which starts a UX Review region screenshot preset with the project and the active entry, now ships in the package instead of living in Kerf's own demo. Add `uxReviewPlugin()` from the new Node-only `@kerfjs/ui/vite-ux-review` subpath to the Vite config. Report the project with `wireCatalog`'s new `onUxReviewProject` callback, and pass it to `Catalog`'s new `uxReview` prop. The link appears on local dev and preview servers and stays hidden on static hosting. `uxReviewCaptureUrl` and `loadUxReviewProject` are exported from `@kerfjs/ui/catalog` for custom placements (`KF-XB1G3S`).
|
|
798
|
+
|
|
799
|
+
- Deep-inset Pane content supports `--kui-pane-scrollbar-gutter: stable` for opaque edge-to-edge content, and Pane/Workbench focus rings paint above such scrollers without blocking their controls (`KF-9NVNGT`).
|
|
800
|
+
|
|
801
|
+
- NavStack now has `separator="auto" | "hidden"`. Automatic separators frame a sunken active Pane at the top chrome and optional bottom toolbar; hidden suppresses stack-owned lines (`KF-1XRSRW`).
|
|
802
|
+
|
|
803
|
+
- The UX catalog remembers its background, light or dark theme, contrast, and reduced-motion choices across reloads.
|
|
804
|
+
|
|
805
|
+
- The UX catalog can show a layout guide background with three one-pixel vertical rules at 15px, 23px, and 32px.
|
|
806
|
+
|
|
807
|
+
- `Row`, `Grid`, and `List` accept `gap={{ column, row }}` with independent typed spacing values, while their existing single-value gaps continue to apply to both axes (`KF-8HJFWC`).
|
|
808
|
+
|
|
809
|
+
- `ListHeader` accepts `badge` and `status` together, including explicit `undefined` for either when app state changes; a semantic `count` remains separate.
|
|
810
|
+
|
|
811
|
+
- `Pane`, `SunkenPanel`, plain `TabNavigator` scenes, `Workbench` regions, and static `ContentItem` surfaces can opt into keyboard or programmatic focus; `outlined` holds the standard focus ring for application states such as drop targets. Inactive scenes and collapsed panels suppress their focus stop and outline.
|
|
812
|
+
|
|
813
|
+
- `TabNavigator`, `TabNavigatorTab`, `TabNavigatorProps`, and `wireTabNavigator` name the complete persistent bottom-tab layout. The matching module, wiring, and CSS subpaths are available; former `TabScaffold` names and paths were deprecated aliases in earlier 5.0 betas.
|
|
814
|
+
|
|
815
|
+
- `Pane` exposes its resolved logical inline content insets to child CSS, so a table can paint edge to edge while its cell text stays aligned, with or without `deepInset`.
|
|
816
|
+
|
|
817
|
+
- `Pane` and plain `TabNavigator` scenes accept `deepInset` for a 16px outer content gutter while nested Row, List, and Grid spacing remains at its normal 8px.
|
|
818
|
+
|
|
819
|
+
- The TabNavigator catalog now demonstrates a NavStack with a view-owned top toolbar and Pane above the persistent tab bar, including push, tab switch, and return.
|
|
820
|
+
|
|
821
|
+
- UI Doctor now checks component root class names, stylesheet names, and CSS selectors that reach into another local component.
|
|
822
|
+
|
|
823
|
+
- Configure modal `DialogSurface` viewport gutters and typed maximum heights, including a dynamic viewport cap, without application shadow-part overrides.
|
|
824
|
+
|
|
825
|
+
### Changed
|
|
826
|
+
|
|
827
|
+
- **SVG data URLs are allowed where they load as images.** The URL screen now keeps `data:image/svg+xml` in `<img src>` and in SVG `<image href>` / `<image xlink:href>`, where the browser renders the SVG as an image in secure static mode and runs no script, on the JSX, `html` tagged template, and live-binding paths. Every other sink (`<iframe src>`, `<embed src>`, `<object data>`, `<a href>`, …) still drops it, and no other scheme or `data:` rule changes. Generated SVG artwork no longer needs a `blob:` URL or `raw()`.
|
|
828
|
+
- `@kerfjs/ui` dialog corners are now concentric with a pill `ToolbarControlGroup` (22px) resting at the body inset, in place of Web Awesome's 12px panel radius: 30px by default (a bare `wa-dialog`, `PopoverDialogSurface`, and `DialogSurface` with a `compact` or `none` body inset) and 38px for `bodyInset="comfortable"`. A side sheet's leading corners follow the same radius (`KF-1FNWQG`).
|
|
829
|
+
|
|
830
|
+
- A resizable `@kerfjs/ui` `Workbench` panel without a `label` now names its resize handle in title style, as `ui/docs/writing.md` asks for region names: "Resize Left Rail", "Resize Right Rail", and "Resize Bottom Drawer" (previously "Resize left rail" and so on). A test or locator that matched the old accessible name needs the new one (`KF-NWS9GB`).
|
|
831
|
+
|
|
832
|
+
- `kerf-ui-doctor`'s `KUI-D040` now also checks template literals passed to title-style props, judging only their static words: ``label={`Edit ${name} shortcut`}`` is reported with the suggestion `` `Edit ${name} Shortcut` ``. Interpolated values and words joined to an interpolation are never judged. The UX demos' dynamic control names follow it ("Edit … Shortcut", "Open Ticket …", "New Tab …"), and the NavStack demo's detail item is named by its visible title alone (`KF-8B6JES`).
|
|
833
|
+
|
|
834
|
+
- `kerf-ui-doctor`'s `KUI-D040` now also reads region and landmark names, which `ui/docs/writing.md` makes title style, and raw Web Awesome field labels. The new region names are:
|
|
835
|
+
- the `label` of `Pane`, `Workbench`, `Toolbar`, `ToolbarControlGroup`, `TabBar`, `NavStack`, `CollapsiblePanel`, `FloatingToolbar`, and `ResizableRegion`;
|
|
836
|
+
- the `ariaLabel` of `SunkenPanel` and `List`;
|
|
837
|
+
- a `Pane`'s `contentLabel`;
|
|
838
|
+
- the panel, toolbar, and pane labels in Workbench, CollapsiblePanel, and NavStack configuration;
|
|
839
|
+
- the `aria-label` of `section`, `nav`, `aside`, `main`, `header`, `footer`, `form`, `search`, or an element with a landmark role.
|
|
840
|
+
|
|
841
|
+
The field labels it reads are the `label` of a raw `wa-input`, `wa-select`, `wa-textarea`, or `wa-radio-group`. `wa-checkbox`, `wa-switch`, and `wa-radio` option text, and `LoadingSpinner` and `Skeleton` labels, stay unread. Expect new warnings on lowercase names such as `<Pane label="Workspace pages">` ("Workspace Pages"). The package's own fixtures and examples are fixed. The catalog shell's sidebar navigation is now named "Kerf Components" (it was "Kerf components") (`KF-8JR7EC`).
|
|
842
|
+
|
|
843
|
+
- A panel toolbar's `toggle: { action, name }` (Workbench panels, `CollapsiblePanel`) now documents `name` as the panel's title-style name. Pass `name: "Navigator"`, not `"navigator"`: `name` labels the toggle group and completes the default "Show …" / "Hide …" label, which kerf never recapitalizes. The docs, demos, and recipes passed lowercase names, which produced sentence-style accessible names such as "Show output". They now pass title-style names. The catalog shell names its sidebar "Kerf Catalog" and its settings rail toggle reads "Hide Settings" (they read "Kerf catalog" and "Hide settings"). `KUI-D040` now reports a lowercase `name` in a `toggle` object literal that also has an `action` (`KF-EJ32ZH`).
|
|
844
|
+
- A `NavStack` root view's title now defaults to the `xlarge` page-heading size, and steps down to `large` once a back control shares the bar. An explicit `titleSize` still wins. A Workbench panel's stack keeps `large` at every depth, so narrow rails stay quieter than the work-area title (`KF-2XWXFR`).
|
|
845
|
+
- The built-in close control of a `wa-dialog` or `wa-drawer` now matches a borderless single `ToolbarControlGroup` button, the close a toolbar-composed dialog uses: a 40px circle with no border and the neutral hover fill, instead of Web Awesome's 35px rounded square (`KF-5B5C4W`).
|
|
846
|
+
- A capped, scrolling `Select` listbox, `PopupMenu` menu, or phone-width `PopupMenu` submenu now shows that it scrolls: a soft shadow lines each edge with more choices beyond it. With overlay scrollbars (macOS, iOS, Android), a capped submenu whose bottom edge fell between rows looked like a complete short list. The cue is CSS only, the same on every popup in the shared popup contract, and absent when every choice fits (`KF-B6BTHW`).
|
|
847
|
+
- A centered `NavStack` title (and any lone `ToolbarText` in a `centerAlign="balanced"` center) now keeps the full-strength text color the root title has, instead of dimming to the quieter `large`-size color as it centers (`KF-DX3739`).
|
|
848
|
+
- Once a `NavStack` shows a back control, the view title centers on the toolbar like a platform navigation bar. It stays on the midpoint while the sides leave room, moves away from a wider side when they do not, and truncates with an ellipsis before it reaches the back control or a trailing group. At the root, and on a view that supplies `toolbar.center`, the title stays left-aligned. A lone `ToolbarText` in a `centerAlign="balanced"` toolbar gets this navigation-bar layout in any `Toolbar` (`KF-9YD9KV`).
|
|
849
|
+
- The `NavStack` back control is now a contained, bordered `ToolbarControlGroup` (the default pill), so it reads as a real control instead of a bare chevron beside the title (`KF-TBRP2P`).
|
|
850
|
+
- HTML and attribute escaping in the JSX runtime now runs one pass over a value instead of one `replace` pass per special character, about 2x faster on values that need escaping. Output is unchanged (`KF-3SHRTR`).
|
|
851
|
+
|
|
852
|
+
- Rename the internal TabNavigator implementation folder, files, and focused test files from `tab-scaffold` to `tab-navigator`; public imports and rendered DOM hooks stay stable.
|
|
853
|
+
|
|
854
|
+
- `deepInset` now adds the same 8px to the top and bottom of Pane and plain TabNavigator scroll content, including scroll padding; Pane header and footer still own their safe-area edges.
|
|
855
|
+
|
|
856
|
+
- Toolbar composition guidance and catalog metadata now allow direct `KerfUiContent` in every zone; `ToolbarControlGroup` remains the recommended shared chrome for related controls.
|
|
857
|
+
|
|
858
|
+
- The UI composition lint rule checks component parent requirements for direct content passed through a named zone prop.
|
|
859
|
+
|
|
860
|
+
- Toolbar zones center direct content by default while keeping ToolbarText, control groups, and standalone primary actions on their established control-band axis.
|
|
861
|
+
|
|
862
|
+
### Fixed
|
|
863
|
+
|
|
864
|
+
- Catalog Pane's documented `--kui-pane-scrollbar-gutter` token so downstream doctor and ESLint checks accept the supported setting (`KF-W5VXQF`).
|
|
865
|
+
|
|
866
|
+
- The actionable ToolbarText catalog example uses the standard TokenSearchField toolbar presentation for its search control, and an empty TokenSearchField shows its placeholder.
|
|
867
|
+
|
|
868
|
+
- Preserve toolbar visibility and measurement state across app renders to prevent geometry-driven render loops and repeated observer/layout work (`KF-58HBRR`).
|
|
869
|
+
|
|
870
|
+
- Restore accessible native dialog names through `@kerfjs/ui/surface-scaffold/register`, preserving live title slots and headerless labels.
|
|
871
|
+
|
|
872
|
+
- Validate remote CI freshness through newer-run searches and exact-run details before warning about a failed main build (`KF-X4PTHF`).
|
|
873
|
+
|
|
874
|
+
- Select menus now shift their complete visible surface inside narrow viewport edges while preserving `fitMenu` trigger width (`KF-H4JBQP`).
|
|
875
|
+
|
|
876
|
+
- Toolbar visibility probes stop rewriting unchanged styles, allowing catalog geometry overlays and responsive controls to settle after updates (`KF-JVWC92`).
|
|
877
|
+
|
|
878
|
+
- Busy toolbar groups preserve their relocation annotation, so the inert action and live status remain available when a panel closes.
|
|
879
|
+
|
|
880
|
+
- Navigation stacks now visibly slide pushed views over the previous screen and cross-fade both header and footer across repeated or interrupted push/pop transitions.
|
|
881
|
+
|
|
882
|
+
### Added
|
|
883
|
+
|
|
884
|
+
- Add typed toolbar item `hideBelow`/`showBelow` lengths and `wireToolbarVisibility`, including complementary container-width overflow and dynamic font/token updates (`KF-MXE9YV`).
|
|
885
|
+
|
|
886
|
+
- Expanded grouped search supports `expandedOverflow="visible"` for application-owned surfaces below its positioning anchor.
|
|
887
|
+
|
|
888
|
+
- `@kerfjs/ui` ToolbarControlGroup adds `tileTone` quiet semantic palettes for non-interactive heading icon tiles.
|
|
889
|
+
|
|
890
|
+
- ToolbarText supports `tone="dark"` for filenames, headings, and actionable titles on loud toolbar surfaces.
|
|
891
|
+
- `@kerfjs/ui` Text accepts `controlMargins` for selected exterior control gutters, avoiding a Row wrapper around isolated text.
|
|
892
|
+
|
|
893
|
+
- Make lowered surfaces and decorative neutral fills/borders translucent, and replace the SunkenPanel prototype with direct component compositions.
|
|
894
|
+
|
|
895
|
+
- **UI components share `SemanticTone`.** Badge, Chip, StateBanner, and ContentItem
|
|
896
|
+
use `neutral`, `info`, `pop`, `success`, `warning`, and `danger`. Replace
|
|
897
|
+
Badge/Chip `tone="brand"` with `tone="info"`; the existing brand color tokens
|
|
898
|
+
still supply its palette. `BadgeTone` and `StateBannerTone` are deprecated aliases.
|
|
899
|
+
|
|
900
|
+
- **Catalog sidebars filter by item or heading name.** The shared catalog
|
|
901
|
+
shell now searches primary and ecosystem sections as you type, including
|
|
902
|
+
collapsed groups, and keeps the query when the active preview changes.
|
|
903
|
+
|
|
904
|
+
- **ListHeader has five label sizes.** `size="xs|sm|m|l|xl"` controls visual
|
|
905
|
+
scale separately from the semantic heading level; `sm` preserves the existing
|
|
906
|
+
uppercase treatment and `FieldLabel` remains unchanged.
|
|
907
|
+
|
|
908
|
+
- **The pinned TabBar catalog example scrolls with native momentum.** It no
|
|
909
|
+
longer reserves a long blank strip after the final tab; applications can
|
|
910
|
+
still opt into whole-tab settling with `snapTabs`.
|
|
911
|
+
|
|
912
|
+
- **Doctor reports foreign CSS restyles of co-owned classes.** A stylesheet
|
|
913
|
+
outside every co-owner now receives one `KUI-L019` per subject rule, including
|
|
914
|
+
inferred BEM modifiers, with the co-owner set in the diagnostic evidence.
|
|
915
|
+
|
|
916
|
+
- **Doctor respects explicit ownership groups with implicit ownership enabled.**
|
|
917
|
+
A group's stylesheet remains owned by the group even when one of its source
|
|
918
|
+
modules, or an unrelated module, imports that CSS directly.
|
|
919
|
+
|
|
920
|
+
- **LucideIcon supports filled glyphs.** Pass `appearance="solid"` to use the
|
|
921
|
+
icon's current text color as its fill; outline remains the default.
|
|
922
|
+
|
|
923
|
+
- **Doctor detects borrowed component markup.** Source modules that place a
|
|
924
|
+
foreign public class in JSX, raw HTML, or DOM class writes now receive
|
|
925
|
+
`KUI-L023`; documented placeable classes remain allowed.
|
|
926
|
+
|
|
927
|
+
- **Doctor offers strict same-package selector context checks.**
|
|
928
|
+
`ownershipContext: "any"` reports a sibling component's class even when it is
|
|
929
|
+
only used as selector context; cross-package composition stays available.
|
|
930
|
+
|
|
931
|
+
- **Doctor catches classless descendants of composed components.** Component
|
|
932
|
+
mode uses JSX evidence to identify element selectors below component hooks,
|
|
933
|
+
sibling roots, and direct composed child roots.
|
|
934
|
+
|
|
935
|
+
- **Doctor component ownership recognizes source evidence.** Selection-only
|
|
936
|
+
components and literal BEM classes rendered by a component are protected
|
|
937
|
+
when its stylesheet styles their block. CSS imports can supply the owned
|
|
938
|
+
stylesheet, and uncataloged modules can opt into the same inference.
|
|
939
|
+
|
|
940
|
+
- **`createScope().dispose` is typed as a bound function property.** Consumers
|
|
941
|
+
can store or return it as a teardown without a wrapper or an unbound-method
|
|
942
|
+
lint suppression.
|
|
943
|
+
|
|
944
|
+
- **ToolbarControlGroup grow sizing keeps its basis in wide toolbars.** An
|
|
945
|
+
expanded grow search now contributes its minimum width to the trailing zone's
|
|
946
|
+
intrinsic size, keeping sibling groups beside it instead of wrapping early.
|
|
947
|
+
|
|
948
|
+
- **TabBar can settle overflowing peers at whole-tab starts.** Opt into
|
|
949
|
+
`snapTabs` beside a pinned leading AppTab; selection and scroll gestures
|
|
950
|
+
align peers after the pin in LTR and RTL, with enough end room for the final
|
|
951
|
+
tab instead of leaving a clipped sliver at rest.
|
|
952
|
+
|
|
953
|
+
- **The pre-push check no longer adds timing metadata to Hot Sheet tickets.**
|
|
954
|
+
It still runs the repository gate or skips an identical verified clean tree;
|
|
955
|
+
historical timing notes remain readable through `ticket:timing summary`.
|
|
956
|
+
|
|
957
|
+
- **Wrapping catalog resource groups align with the toolbar control band.** A
|
|
958
|
+
single row centers in the band, while multiple rows start at its top.
|
|
959
|
+
|
|
960
|
+
- **UI browser checks cover the current catalog specimens.** Select, toolbar,
|
|
961
|
+
tab, and control group browser assertions now address the expanded demos;
|
|
962
|
+
a focused toolbar search field restores its default surface color when no
|
|
963
|
+
background override is set.
|
|
964
|
+
|
|
965
|
+
- **Pinned tabs cover the full leading edge of their scroll strip.** The
|
|
966
|
+
backing now includes the strip border as well as its padding, preventing a
|
|
967
|
+
sliver of a scrolling tab label from showing beside the pinned tab.
|
|
968
|
+
|
|
969
|
+
- **Catalog resource links remain readable at phone widths.** The resource
|
|
970
|
+
group wraps whole actions onto another row instead of clipping the Guidance
|
|
971
|
+
label at the right edge; `ToolbarControlGroup overflow="wrap"` is available
|
|
972
|
+
for the same independent-link pattern.
|
|
973
|
+
|
|
974
|
+
- **The UI analyzer resolves application component imports through TypeScript
|
|
975
|
+
path aliases.** `KUI-L022` now catches a styled hook class when an imported
|
|
976
|
+
cataloged component uses an exact or wildcard `paths` mapping; Doctor uses
|
|
977
|
+
the same resolution.
|
|
978
|
+
|
|
979
|
+
- **TabBar accepts standalone Web Awesome actions in `trailing` and `end`.**
|
|
980
|
+
A single `wa-button` can sit beside the scrolling tabs or at the far edge
|
|
981
|
+
without ToolbarControlGroup chrome; the composition rule recognizes the
|
|
982
|
+
cataloged custom element in these zones.
|
|
983
|
+
|
|
984
|
+
- **FieldLabel matches form-control labels over field previews.** The
|
|
985
|
+
`@kerfjs/ui/text` export gives a read-only field the same label typography
|
|
986
|
+
and inset as a themed Web Awesome input, with an id for accessible grouping.
|
|
987
|
+
|
|
988
|
+
- **TokenSearchField form fields match adjacent Web Awesome inputs.** The
|
|
989
|
+
control uses the form-control radius, and its required marker uses the
|
|
990
|
+
same neutral color and offset tokens as `wa-input`.
|
|
991
|
+
|
|
992
|
+
- **Grid supports labeled multi-select ContentItem tiles.** Opt into
|
|
993
|
+
`selectionMode="multiple"` with `ariaLabel`; `wireContentItems` follows the
|
|
994
|
+
rendered columns with four arrow keys and keeps nested controls independent.
|
|
995
|
+
|
|
996
|
+
- **Collapsible TokenSearchField can fill a stretched Toolbar center.** The
|
|
997
|
+
`fill` prop expands the field and its search group to the available width
|
|
998
|
+
while preserving the compact collapsed action.
|
|
999
|
+
|
|
1000
|
+
- **TokenSearchField has a typed trailing icon action.** `trailingAction`
|
|
1001
|
+
renders an accessible button with Kerf owned chrome and a full 24px wide hit
|
|
1002
|
+
target; the existing `trailing` content slot remains for passive content.
|
|
1003
|
+
|
|
1004
|
+
- **PopupMenu and registered PopupSurface dropdowns preserve fast keyboard
|
|
1005
|
+
navigation during opening.** Item focus gained while Web Awesome animates
|
|
1006
|
+
the menu is restored after its initial focus handoff, so Enter acts on the
|
|
1007
|
+
item the user reached.
|
|
1008
|
+
|
|
1009
|
+
- **PopupMenu submenu checkmarks stay inside the menu surface.** Checked
|
|
1010
|
+
submenu rows align their checkmark beside the label instead of letting the
|
|
1011
|
+
Web Awesome negative check margin paint beyond the submenu border.
|
|
1012
|
+
|
|
1013
|
+
- **Filled SegmentedControl labels keep contrast while switching themes.**
|
|
1014
|
+
Web Awesome's native button color transition no longer interpolates the
|
|
1015
|
+
label against the already-switched track fill.
|
|
1016
|
+
|
|
1017
|
+
- **Workbench numeric overlays no longer restyle the full work area on unrelated changes.**
|
|
1018
|
+
The overlay wiring mirrors active presentation and open state onto the Workbench
|
|
1019
|
+
root for CSS, and avoids layout measurements when no wired panel uses a numeric
|
|
1020
|
+
breakpoint.
|
|
1021
|
+
|
|
1022
|
+
## [5.0.0] - 2026-09-29
|
|
1023
|
+
|
|
1024
|
+
- **`ui-public-boundaries` inspects `kerfjs/html` tagged templates.** The
|
|
1025
|
+
no-build `html` template writes the same markup as JSX, so its static
|
|
1026
|
+
`class` attributes now carry `KUI-L101` (private `kui-*` anatomy) and
|
|
1027
|
+
`KUI-L103` (a component's anatomy on your own element):
|
|
1028
|
+
``html`<aside class="kui-pane">` `` is reported with `Pane` to render, and a
|
|
1029
|
+
plain ``html`<div class="kui-content-item">` `` with `ContentItem`, while a
|
|
1030
|
+
`<ul>` carrier keeps the placeable class. The template's static parts are
|
|
1031
|
+
read by the runtime's own rules; a class a hole supplies (`class=${cls}`)
|
|
1032
|
+
is unknown and skipped.
|
|
1033
|
+
|
|
1034
|
+
- **`KUI-L103`'s "render X instead" answer has one implementation.**
|
|
1035
|
+
`@kerfjs/ui` ships `ai/component-class-owners.cjs`, the rule that decides
|
|
1036
|
+
which cataloged classes are a component's anatomy and which export renders
|
|
1037
|
+
each. `eslint-plugin-kerfjs`'s `ui-public-boundaries` loads it beside
|
|
1038
|
+
`application-ui-profile-sync.cjs`, and the generated `ai/components/*.md`
|
|
1039
|
+
pages use it too, so the lint message and the component reference can no
|
|
1040
|
+
longer name different components (a test pins their agreement over the whole
|
|
1041
|
+
shipped catalog). A vendored `profileContractPath` directory must now also
|
|
1042
|
+
hold `component-class-owners.cjs`; an `@kerfjs/ui` without it reports
|
|
1043
|
+
`KUI-L090`.
|
|
1044
|
+
|
|
1045
|
+
- **A delegated click no longer re-fires on a target the re-render recycled.**
|
|
1046
|
+
A delegated handler that writes a signal makes `mount()` re-render
|
|
1047
|
+
synchronously, inside the same event dispatch; when the morph recycled the
|
|
1048
|
+
clicked element in place into a control with a different `data-action`,
|
|
1049
|
+
delegates registered later for the same event matched the recycled element
|
|
1050
|
+
and fired too (a `request` click immediately ran `cancel` and undid itself).
|
|
1051
|
+
`delegate()`, `delegateCapture()`, and `kerfjs/actions`' `delegateActions()`
|
|
1052
|
+
now resolve every delegate's match against the DOM as it stood when the
|
|
1053
|
+
event reached the first kerf delegate listener, like per-element listeners:
|
|
1054
|
+
a delegate that matched at dispatch start still fires (unless an earlier
|
|
1055
|
+
handler removed its element), one that matches only after a re-render does
|
|
1056
|
+
not, and `delegateActions()` dispatches by the action value the element
|
|
1057
|
+
carried at dispatch start. `mount()` stays synchronous. The
|
|
1058
|
+
wrap-it-in-a-distinct-element workaround is no longer needed. Cost: about
|
|
1059
|
+
0.11 KB min+gzip, which moves the advertised core size from ~12 KB to
|
|
1060
|
+
~13 KB.
|
|
1061
|
+
|
|
1062
|
+
- **Component packages declare `placeableClasses`, and `KUI-L103` covers
|
|
1063
|
+
their anatomy classes.** `create-kerf-component`'s `kerf.components.json`
|
|
1064
|
+
accepts optional `boundaries.placeableClasses` (a subset of
|
|
1065
|
+
`publicClasses`) and `boundaries.rootElement`, validates them, and copies
|
|
1066
|
+
them into the generated `component-composition.json`.
|
|
1067
|
+
`eslint-plugin-kerfjs`'s `ui-public-boundaries` now checks every class the
|
|
1068
|
+
application or third-party catalogs in `.kerf-ui-profile.json` declare, not
|
|
1069
|
+
only `kui-*` names: `<div class="acme-meter">` is reported with the
|
|
1070
|
+
package's component to render (`Meter`), while its placeable classes stay
|
|
1071
|
+
allowed. The scaffold template's README explains the field, and
|
|
1072
|
+
`@kerfjs/ui/ai/skill.md` (1.50.0) applies the rule to package entries.
|
|
1073
|
+
|
|
1074
|
+
- **`eslint-plugin-kerfjs` `ui-public-boundaries` reports a plain
|
|
1075
|
+
`<div class="kui-content-item">` as `ContentItem` recreated (`KUI-L103`).**
|
|
1076
|
+
The `kui-content-item` classes stay placeable on another carrier (a `<ul>`, a
|
|
1077
|
+
`Text`, a control-cluster `<footer>`), but a plain `<div>` carrying them is
|
|
1078
|
+
exactly what `ContentItem` renders; the diagnostic now says to render
|
|
1079
|
+
`ContentItem`. The `@kerfjs/ui` catalogs gain an additive `rootElement`
|
|
1080
|
+
field (selection entry and composition `boundaries.rootElement`) naming the
|
|
1081
|
+
element a component renders around its own placeable classes, and
|
|
1082
|
+
`check:guidance` derives its repository check from the same fields, so the
|
|
1083
|
+
package check and the downstream diagnostic cannot drift. The rule also
|
|
1084
|
+
inspects the static class names of a template-literal `class` /
|
|
1085
|
+
`className` value.
|
|
1086
|
+
|
|
1087
|
+
- **`eslint-plugin-kerfjs` `ui-public-boundaries` reports a component's
|
|
1088
|
+
anatomy class written onto an application-owned element (`KUI-L103`).**
|
|
1089
|
+
`<div class="kui-toolbar">`, `<aside class="kui-pane">`, or
|
|
1090
|
+
`<wa-dropdown class="kui-popup-menu">` recreates a component by class and
|
|
1091
|
+
inherits (and invites restyling of) its CSS; the diagnostic names the
|
|
1092
|
+
component to render instead (`Toolbar`, `Pane`, `PopupMenu`). The
|
|
1093
|
+
`@kerfjs/ui` catalogs gain `placeableClasses` (selection entry field and
|
|
1094
|
+
composition `boundaries.placeableClasses`) naming the public classes an
|
|
1095
|
+
application may place itself — the layout utilities, `kui-app-root`, the
|
|
1096
|
+
`kui-content-item` geometry on a non-div carrier, and Web Awesome
|
|
1097
|
+
`hide-actions` — and `check:catalog` requires every class-only entry to list
|
|
1098
|
+
its classes there. A component's own element (`<Toolbar className="kui-toolbar">`)
|
|
1099
|
+
is not reported. The README pane example and `@kerfjs/ui/ai/skill.md`
|
|
1100
|
+
(1.47.0) now render `Pane` instead of writing its classes, and each generated
|
|
1101
|
+
`ai/components/*.md` page states which classes are placeable and which
|
|
1102
|
+
component renders the rest.
|
|
1103
|
+
|
|
1104
|
+
- **`kerf-ui-analyze` retires `KUI-L005` ("forced component dimension").**
|
|
1105
|
+
`KUI-L019` already reports any application rule whose subject is a cataloged
|
|
1106
|
+
component, dimensions included, so `.kui-pane { width: 300px }` was reported
|
|
1107
|
+
twice (an error and a review finding). L005's only other shape, a public
|
|
1108
|
+
class as an ancestor (`.kui-pane .app-sidebar { width: 240px }`), sizes the
|
|
1109
|
+
application's own element and is allowed. The analyzer no longer emits it;
|
|
1110
|
+
the id stays in the diagnostic registry (now listing it under `retired`) so
|
|
1111
|
+
existing profile exceptions that name it still load.
|
|
1112
|
+
|
|
1113
|
+
- **`KUI-L301` now reports every `Discouraged` Web Awesome element rendered
|
|
1114
|
+
directly.** The `@kerfjs/ui` package-default application profile avoids all
|
|
1115
|
+
fifteen Discouraged entries (Dropdown/Dropdown Item → `PopupMenu`,
|
|
1116
|
+
Select/Option → `Select`, Tab Group/Tab/Tab Panel → `TabBar`, Icon →
|
|
1117
|
+
`LucideIcon`, Split Panel → `ResizableRegion`, Button Group →
|
|
1118
|
+
`SegmentedControl`, Tree/Tree Item → `List`, and Animated Image, Comparison,
|
|
1119
|
+
and Zoomable Frame → `ContentItem`), each with a rationale, and
|
|
1120
|
+
`eslint-plugin-kerfjs` `ui-preferences` (and `kerf-ui-doctor`, which runs it)
|
|
1121
|
+
now resolves a custom-element JSX tag such as `<wa-dropdown>` to its catalog
|
|
1122
|
+
entry, not only an imported component. A declared component's own source
|
|
1123
|
+
stays exempt because it is the wrapper that owns the element. A test keeps
|
|
1124
|
+
the profile's avoid set equal to the catalog's Discouraged set in both
|
|
1125
|
+
directions and lints the UX demo, recipes, and catalog shell clean;
|
|
1126
|
+
`@kerfjs/ui/ai/skill.md` (1.46.0) names the diagnostic.
|
|
1127
|
+
|
|
1128
|
+
- **New (`@kerfjs/ui`): `NavStack` and `TabScaffold` take `chromeDividers`
|
|
1129
|
+
(`'scroll' | 'always' | 'none'`), like `Pane`.** `scroll` (the default) keeps
|
|
1130
|
+
today's behavior: the stack's top-chrome and bottom-toolbar lines and the
|
|
1131
|
+
scaffold's bar line follow the scroll once `wireScrollDividers` is installed.
|
|
1132
|
+
`always` draws them permanently without the wiring; `none` never draws them,
|
|
1133
|
+
even when wired. The top `Toolbar`'s own `toolbarConfig.dividerSides` is
|
|
1134
|
+
unaffected. `SplitView` forwards it to its compact stack through
|
|
1135
|
+
`compactStack.chromeDividers`.
|
|
1136
|
+
|
|
1137
|
+
- **Fix (`@kerfjs/ui`): a `Pane` that is the only content of a `NavStack` view
|
|
1138
|
+
or a `TabScaffold` scene fills it.** It used to size to its content, so the
|
|
1139
|
+
view scrolled the whole Pane and its header scrolled away. Now the Pane's own
|
|
1140
|
+
content scrolls under its pinned header and footer, the Pane's slots take the
|
|
1141
|
+
safe-area edges the view or scene still reaches, and scroll dividers key on
|
|
1142
|
+
the Pane's content. The rule lives in `pane.css`, as the Workbench-region fill
|
|
1143
|
+
does.
|
|
1144
|
+
|
|
1145
|
+
- **The `@kerfjs/ui` suite-v3 AI-regression protocol test runs in every gate
|
|
1146
|
+
again.** `ui/tests/integration/ai-regressions-v3.test.ts` was selected by no
|
|
1147
|
+
package script, so neither `npm --prefix ui run check` nor CI executed it. It
|
|
1148
|
+
now runs as `test:ai-regressions` inside the package's `npm test`, and a new
|
|
1149
|
+
unit guard fails when any file under `ui/tests` is selected by no script
|
|
1150
|
+
reachable from `check` or `test:e2e`.
|
|
1151
|
+
|
|
1152
|
+
- **Importing `@kerfjs/ui/catalog` or `@kerfjs/ui/workbench` now ships every
|
|
1153
|
+
stylesheet those composites render.** `catalog`, `workbench`, `nav-stack`,
|
|
1154
|
+
`split-view`, `tab-scaffold`, and `collapsible-panel` gain a CSS-aware
|
|
1155
|
+
`browser` export condition whose generated wrapper imports the foundation, the
|
|
1156
|
+
CSS of each internally rendered component (Pane, Toolbar, ToolbarText, List,
|
|
1157
|
+
ListItem, ListInsetText, Row, PopupMenu, …) in dependency order, and the
|
|
1158
|
+
composite's own CSS. Apps no longer hand-import `pane.css`, and a Catalog
|
|
1159
|
+
sidebar's styling no longer depends on whether the app happens to import
|
|
1160
|
+
`ListInsetText` elsewhere. The list is derived from the source import graph
|
|
1161
|
+
(now following parent-relative imports), the `import` condition stays
|
|
1162
|
+
CSS-free, and the companion `.css` subpaths remain for pipelines without the
|
|
1163
|
+
`browser` condition. `@kerfjs/ui/ai/skill.md` is 1.46.0.
|
|
1164
|
+
|
|
1165
|
+
- **The `@kerfjs/ui` AI guidance now states every maintainer design rule
|
|
1166
|
+
explicitly.** An audit of the package's tickets folded the missing rules into
|
|
1167
|
+
`@kerfjs/ui/ai/skill.md` (1.45.0), `llms.txt`, and the design docs: prefer a
|
|
1168
|
+
Kerf UI component over a Web Awesome component over a raw tag and never render
|
|
1169
|
+
a `Discouraged` Web Awesome element directly (only through the Kerf component
|
|
1170
|
+
that wraps it); nothing wraps inside a `ToolbarControlGroup` and a
|
|
1171
|
+
`ToolbarText` is one ellipsized line unless `wrap`/`maxLines` is set; a
|
|
1172
|
+
`Select` or `PopupMenu` trigger drops its focus ring while its popup is open
|
|
1173
|
+
and the ring follows the control's shape (never add ring CSS); dividers earn
|
|
1174
|
+
their place (`dividerSides=""` over self-spacing content or between a pane's
|
|
1175
|
+
header and its list, never padded around); a control sits near where its
|
|
1176
|
+
effect appears; and text aligns to text and icons to icons — a border is
|
|
1177
|
+
never the alignment anchor. The ToolbarControlGroup catalog entry no longer
|
|
1178
|
+
points at a hand-written `wa-dropdown` trigger, and the bundled kerf app
|
|
1179
|
+
configs (`ai/skill.md` 1.25.0, `ai/cursorrules` 1.23.0) name the List family
|
|
1180
|
+
and carry the "components own their styles; configure, never override" rule.
|
|
1181
|
+
|
|
1182
|
+
- **Applications and component packages are held to the component-ownership
|
|
1183
|
+
rules `@kerfjs/ui` enforces internally: components own their styles and are
|
|
1184
|
+
configured, never overridden.** `kerf-ui-analyze` and `kerf-ui-doctor` add
|
|
1185
|
+
four error diagnostics (review findings under `--adoption`):
|
|
1186
|
+
- `KUI-L019` — a CSS rule whose subject is another package's cataloged
|
|
1187
|
+
component: a public class (`.kui-toolbar`, `.acme-meter`), its
|
|
1188
|
+
`[data-component]` root, or a Web Awesome tag the package themes
|
|
1189
|
+
(`wa-button`). Your own element in a component's context
|
|
1190
|
+
(`.kui-toolbar > .my-widget`), keying on its state inside `:has()`, and
|
|
1191
|
+
setting its public tokens stay allowed.
|
|
1192
|
+
- `KUI-L020` — reading or writing another component's private `--_*`
|
|
1193
|
+
variable (`--_kui-list-gap`).
|
|
1194
|
+
- `KUI-L021` — overriding a token a typed prop sets (`--kui-list-gap` is
|
|
1195
|
+
`<List gap>`); the message quotes the prop's example.
|
|
1196
|
+
- `KUI-L022` — a class placed on a component's root (`<Toolbar
|
|
1197
|
+
className="header" />`) that the application then styles.
|
|
1198
|
+
|
|
1199
|
+
Each message names the component's configuration (typed props, public
|
|
1200
|
+
tokens, variants) and ends by routing a need with no prop to a component-gap
|
|
1201
|
+
report instead of an override. Ownership is per package, from the nearest
|
|
1202
|
+
`package.json`, so a component package styling its own components — including
|
|
1203
|
+
in a Kerf UI parent's context — passes, and third-party catalogs declared in
|
|
1204
|
+
`.kerf-ui-profile.json` get the same protection. `eslint-plugin-kerfjs` adds
|
|
1205
|
+
`ui-component-ownership` (in `recommended-ui` and `strict-ui`, `error`),
|
|
1206
|
+
reporting `KUI-L020` / `KUI-L021` in style strings, style objects, and
|
|
1207
|
+
`style.setProperty()`. The `create-kerf-component` scaffold now ships a
|
|
1208
|
+
`counter.css` that styles only Counter (configured by a typed `size` prop and
|
|
1209
|
+
a `--kerf-counter-gap` token, with context named after Counter and a
|
|
1210
|
+
Toolbar-context rule in its own stylesheet), plus `npm run check:styles`
|
|
1211
|
+
(`kerf-ui-analyze`, from a new `@kerfjs/ui` dev dependency) in
|
|
1212
|
+
`prepublishOnly`.
|
|
1213
|
+
|
|
1214
|
+
- **Behavior change (`@kerfjs/ui`): `NavStack` and `TabScaffold` chrome
|
|
1215
|
+
dividers follow the scroll.** The `NavStack` bottom toolbar's and the
|
|
1216
|
+
`TabScaffold` bar's top borders are no longer permanent. With `wireScrollDividers`
|
|
1217
|
+
installed, a `NavStack`'s top chrome draws a line along its bottom edge only
|
|
1218
|
+
while the active view's content is scrolled beneath it, its bottom toolbar a
|
|
1219
|
+
line along its top edge only while more content lies below, and a
|
|
1220
|
+
`TabScaffold` bar a line along its top edge only while the active scene's
|
|
1221
|
+
content continues below it — none when the content fits. The line follows
|
|
1222
|
+
the active view across a push or pop and the active scene across a tab
|
|
1223
|
+
switch, and keys on whichever element actually scrolls: the view or scene
|
|
1224
|
+
itself, or, through a sole child with no chrome of its own on that edge, a
|
|
1225
|
+
`Pane`'s content or a nested `NavStack`'s active view (a sole `Pane`'s own
|
|
1226
|
+
header or footer draws that boundary instead). Each layout draws the line
|
|
1227
|
+
from its own stylesheet (an overlaid pseudo-element on the stack's chrome; the
|
|
1228
|
+
bottom toolbar and bar keep their 1px top border, transparent until shown),
|
|
1229
|
+
so nothing moves; the wiring
|
|
1230
|
+
writes only its `data-scroll-overflow` / `data-scroll-divider` state. Without
|
|
1231
|
+
the wiring those edges draw no line.
|
|
1232
|
+
|
|
1233
|
+
- **Behavior change (`@kerfjs/ui`): toolbars no longer draw a divider by
|
|
1234
|
+
default; dividers between pinned chrome and scrolling content follow the
|
|
1235
|
+
scroll.** `Toolbar`'s `dividerSides` now defaults to `''` (was `'b'`), and
|
|
1236
|
+
the `Workbench` (`mainToolbar`, `mainBottomToolbar`, panel toolbars, and the
|
|
1237
|
+
`mainHeader` / `mainFooter` lists), `CollapsiblePanel`, and `Catalog`
|
|
1238
|
+
toolbars no longer place dividers of their own. Instead a `Pane` draws one
|
|
1239
|
+
line under its header and one over its footer, wherever that chrome ends:
|
|
1240
|
+
the header's only while content is scrolled beneath it, the footer's only
|
|
1241
|
+
while more content lies below, and neither when the content fits. The new
|
|
1242
|
+
`@kerfjs/ui/wire-scroll-dividers` subpath's `wireScrollDividers(root, {
|
|
1243
|
+
targets? })` reports that state — call it once at the app root and keep its
|
|
1244
|
+
disposer (`wireCatalog` installs it for its own root). It also marks each
|
|
1245
|
+
side of a `TabBar` strip with tabs scrolled out of view, and lets a
|
|
1246
|
+
`Toolbar` or `List` named as chrome in `targets` draw the divider facing an
|
|
1247
|
+
app-owned scroller. The wiring only writes the `data-scroll-overflow` /
|
|
1248
|
+
`data-scroll-divider` state attributes; each component draws its own line,
|
|
1249
|
+
and no state moves the chrome, the content, or a tab. `Pane` gains
|
|
1250
|
+
`chromeDividers` (`scroll` default, `always`, `none`; also in `PaneConfig`,
|
|
1251
|
+
so `mainPane` and a panel's `pane` forward it) and TabBar the
|
|
1252
|
+
`--kui-tab-bar-divider-color` token. To keep a permanent line, set
|
|
1253
|
+
`chromeDividers: "always"` on the pane or an explicit `dividerSides`.
|
|
1254
|
+
|
|
1255
|
+
- **`@kerfjs/ui`: `Pane`, `NavStack`, `SplitView`, and `TabScaffold` fill a
|
|
1256
|
+
Workbench region from their own stylesheets.** As a Workbench main area's
|
|
1257
|
+
or panel's only child, each sets its own `height: 100%` in that context,
|
|
1258
|
+
which the Workbench marks on its regions (`data-workbench-main`, and the new
|
|
1259
|
+
`data-workbench-panel-content` on each panel's content); `workbench.css` no
|
|
1260
|
+
longer sizes another component's root (it still fills a nested Workbench).
|
|
1261
|
+
Rendering is unchanged.
|
|
1262
|
+
|
|
1263
|
+
- **`@kerfjs/ui`: layouts name the covered-floating-controls context after
|
|
1264
|
+
themselves, and no longer write `FloatingToolbar`'s inset token.** Workbench,
|
|
1265
|
+
CollapsiblePanel, and ResizableRegion each provide their own private
|
|
1266
|
+
`--_kui-<layout>-covered` context in place of the shared
|
|
1267
|
+
`--_kui-floating-covered` flag; `FloatingToolbar` and every restore corner
|
|
1268
|
+
read all three. A restore corner no longer sets
|
|
1269
|
+
`--kui-floating-toolbar-inset: 0px`; `FloatingToolbar` zeroes its own inset
|
|
1270
|
+
inside a restore corner (a toolbar's own `inset` still wins). Rendering is
|
|
1271
|
+
unchanged. One edge case changes: a floating control inside an open overlay
|
|
1272
|
+
of one layout type that is itself covered by another layout type's open
|
|
1273
|
+
overlay (for example, a ResizableRegion overlay in a Workbench work area
|
|
1274
|
+
under an open rail overlay) now stays hidden.
|
|
1275
|
+
|
|
1276
|
+
- **`@kerfjs/ui`: `ListHeader`, `NavStack`, `Select`, and `StateBanner` no
|
|
1277
|
+
longer restyle a composed child through a class on its root.** Each child
|
|
1278
|
+
now styles itself: `Text` sets a `ListHeader` label from `text.css`, `Badge`
|
|
1279
|
+
spaces a `Select` count and a `StateBanner` badge from `badge.css`, and a
|
|
1280
|
+
`NavStack` title uses `ToolbarText`'s new `fill` option. Rendering is
|
|
1281
|
+
unchanged. `ToolbarText` gains `fill` (grow into the free space of its
|
|
1282
|
+
toolbar zone and truncate there). The `kui-list-header__label`,
|
|
1283
|
+
`kui-nav-stack__title`, `kui-select__count`, and `kui-state-banner__badge`
|
|
1284
|
+
classes are removed; select a ListHeader label with
|
|
1285
|
+
`.kui-list-header__title > .kui-text` and a NavStack title with
|
|
1286
|
+
`.kui-toolbar-text[data-fill="true"]` if a test needs to find them.
|
|
1287
|
+
|
|
1288
|
+
- **`@kerfjs/ui` ships a markdown component reference for AI assistants.**
|
|
1289
|
+
`@kerfjs/ui/ai/components/README.md` indexes every catalog entry in one line,
|
|
1290
|
+
and `@kerfjs/ui/ai/components/<id>.md` gives each entry a short page: when to
|
|
1291
|
+
use and avoid it, imports and CSS/registration side effects, a link to its
|
|
1292
|
+
exact props, legal parents and zones (JSX prop and child count), app- and
|
|
1293
|
+
wiring-owned state, geometry, accessibility obligations, its styling boundary
|
|
1294
|
+
(configure through props; do not override internals), and its diagnostics.
|
|
1295
|
+
`llms.txt` and the shipped skill now send assistants there instead of to the
|
|
1296
|
+
263 KB `component-catalog.json` and 221 KB `component-composition.json`,
|
|
1297
|
+
which remain the canonical sources for tools. The pages are generated from
|
|
1298
|
+
those two files and a package check fails when they drift.
|
|
1299
|
+
|
|
1300
|
+
- **Breaking (`@kerfjs/ui` and `create-kerf-component`): the composition
|
|
1301
|
+
catalog files are renamed so they no longer read as a "v2" of the component
|
|
1302
|
+
catalog.** The composition catalog is a generated composition layer beside
|
|
1303
|
+
`component-catalog.json`, not a newer version of it. Update any import,
|
|
1304
|
+
`$schema`, `$ref`, or `.kerf-ui-profile.json` catalog location that names an
|
|
1305
|
+
old path:
|
|
1306
|
+
|
|
1307
|
+
| Old path | New path |
|
|
1308
|
+
| -------------------------------------------------------------- | --------------------------------------------------------------- |
|
|
1309
|
+
| `@kerfjs/ui/ai/component-catalog-v2.json` | `@kerfjs/ui/ai/component-composition.json` |
|
|
1310
|
+
| `@kerfjs/ui/ai/component-catalog-v2.schema.json` | `@kerfjs/ui/ai/component-composition.schema.json` |
|
|
1311
|
+
| `@kerfjs/ui/ai/component-catalog-v2.d.ts` | `@kerfjs/ui/ai/component-composition.d.ts` |
|
|
1312
|
+
| `@kerfjs/ui/ai/component-catalog-v2-overrides.json` | `@kerfjs/ui/ai/component-composition-rules.json` |
|
|
1313
|
+
| `@kerfjs/ui/ai/component-catalog-extension-v2.schema.json` | `@kerfjs/ui/ai/component-composition-extension.schema.json` |
|
|
1314
|
+
| `@kerfjs/ui/ai/component-catalog-extension-v2.d.ts` | `@kerfjs/ui/ai/component-composition-extension.d.ts` |
|
|
1315
|
+
| `@kerfjs/ui/docs/examples/component-catalog-extension-v2.json` | `@kerfjs/ui/docs/examples/component-composition-extension.json` |
|
|
1316
|
+
| scaffolded package `component-catalog-v2.json` | scaffolded package `component-composition.json` |
|
|
1317
|
+
|
|
1318
|
+
The exported types follow: `ComponentCatalogV2` → `ComponentComposition`,
|
|
1319
|
+
`CatalogCompositionEntryV2` → `CatalogCompositionEntry`,
|
|
1320
|
+
`ConsumerComponentCatalogV2` → `ConsumerComponentComposition`, and
|
|
1321
|
+
`ConsumerCatalogEntryV2` → `ConsumerCompositionEntry`. In the repository,
|
|
1322
|
+
`npm run catalog:v2:sync` is now `npm run composition:sync`
|
|
1323
|
+
(`catalog:sync` still runs both generators). The file contents and their
|
|
1324
|
+
`schemaVersion` are unchanged.
|
|
1325
|
+
|
|
1326
|
+
- **Breaking (`@kerfjs/ui`, `create-kerf-component`, and `kerfjs setup`): the
|
|
1327
|
+
composition catalog's own fields no longer read as a "v2" of the component
|
|
1328
|
+
catalog.** In `component-composition.json` (and any consumer composition
|
|
1329
|
+
catalog), `"schemaVersion": 2` is now `"schemaVersion": 1` — the composition
|
|
1330
|
+
format's own first version, independent of `component-catalog.json`'s — and
|
|
1331
|
+
`compatibility.v1Catalog` is now `compatibility.componentCatalog`. A
|
|
1332
|
+
scaffolded package's `kerf.components.json` renames its `v1Catalog` field to
|
|
1333
|
+
`componentCatalog` the same way. Regenerate scaffolded catalogs
|
|
1334
|
+
(`npm run catalog:generate`), and change any `.kerf-ui-profile.json` `composition`
|
|
1335
|
+
location from `"schemaVersion": 2` to `"schemaVersion": 1`; a catalog still
|
|
1336
|
+
carrying the old fields fails validation with a message naming the rename.
|
|
1337
|
+
The `ComponentComposition` type follows (`schemaVersion: 1`,
|
|
1338
|
+
`compatibility.componentCatalog`).
|
|
1339
|
+
|
|
1340
|
+
- **`@kerfjs/ui` `NavStack` bars use the standard `Toolbar` padding.** The
|
|
1341
|
+
navigation bar dropped its toolbar's block padding to stay 44px tall, so its
|
|
1342
|
+
title and controls touched the bar's edges. It now keeps the 8px above and
|
|
1343
|
+
below that every other toolbar has (60px plus any top safe-area inset).
|
|
1344
|
+
|
|
1345
|
+
- **`@kerfjs/ui` multiline list rows break long camelCase names at word
|
|
1346
|
+
boundaries.** A string label in a `multiline` `ListItem` or `ListActionRow`
|
|
1347
|
+
(such as a Catalog sidebar entry) gets `<wbr>` break opportunities at its
|
|
1348
|
+
camelCase and acronym boundaries, so `QuickTicketComposer` wraps as
|
|
1349
|
+
`QuickTicket` / `Composer` instead of `QuickTicketComp` / `oser`. Breaking
|
|
1350
|
+
mid-word remains the fallback for a single word that is still too wide.
|
|
1351
|
+
- **`wbr` is a typed JSX intrinsic element.** The runtime already rendered it
|
|
1352
|
+
as a void element; `JSX.IntrinsicElements` now declares it.
|
|
1353
|
+
|
|
1354
|
+
- **`@kerfjs/ui` `Badge` has a text-free dot, and `TabScaffold` tabs can show
|
|
1355
|
+
it.** `Badge` takes `size="dot"`: an 8px solid circle in the badge's tone,
|
|
1356
|
+
with no children, appearance, or shape. Because a dot has no text, its props
|
|
1357
|
+
require either a `label` (announced as an image, for example
|
|
1358
|
+
`label="New activity"`) or `ariaHidden` when the owning component already
|
|
1359
|
+
announces it. `TabScaffoldTab` accepts `badge: true` for the iOS tab-bar dot
|
|
1360
|
+
(new content without a count), centered on the icon's top-trailing corner;
|
|
1361
|
+
its `badgeLabel` is required and joins the tab's accessible name
|
|
1362
|
+
("Settings, Update available"). `BadgeTextProps` and `BadgeDotProps` are
|
|
1363
|
+
exported from the root barrel.
|
|
1364
|
+
|
|
1365
|
+
- **`@kerfjs/ui` `Toolbar` truncates the leading title instead of letting the
|
|
1366
|
+
center zone cover it.** When a leading identity, a `center` group, and
|
|
1367
|
+
trailing actions no longer fit one row, the center zone keeps its whole
|
|
1368
|
+
content width and the leading title ends in an ellipsis. Previously the
|
|
1369
|
+
center track could shrink below its group, which then painted over the
|
|
1370
|
+
title — a pushed `NavStack` view with a center group did this at 390px. The
|
|
1371
|
+
fix holds under every `responsive` policy and both `centerAlign` values, and
|
|
1372
|
+
a toolbar that fits lays out exactly as before.
|
|
1373
|
+
|
|
1374
|
+
- **`@kerfjs/ui` `ValueTableRow` keeps its value readable beside a long
|
|
1375
|
+
label.** A long single-word label (such as `ConnectionStateBanner` in a
|
|
1376
|
+
390px-wide table) no longer squeezes the value to 0px wide, where it wrapped
|
|
1377
|
+
one character per line while the label ran underneath it. The label and value
|
|
1378
|
+
now share the row as two content-sized columns: a short value stays whole on
|
|
1379
|
+
one line, the label wraps at its spaces and ends an over-long word in an
|
|
1380
|
+
ellipsis before the value, and when both are long they split the row.
|
|
1381
|
+
|
|
1382
|
+
- **`@kerfjs/ui` pinned chrome can give way in a short pane.** `Pane` takes
|
|
1383
|
+
`chromePlacement="auto"`: its header and footer stay pinned while the pane is
|
|
1384
|
+
at least 480px (30rem) tall, and below that the whole pane scrolls as one
|
|
1385
|
+
column so tall chrome never squeezes the content to nothing.
|
|
1386
|
+
`WorkbenchChromePlacement` gains `"auto"` for `mainHeaderPlacement` /
|
|
1387
|
+
`mainFooterPlacement`, and `Catalog` now defaults `headerPlacement` /
|
|
1388
|
+
`footerPlacement` to `"auto"`. Its entry description is pinned under the
|
|
1389
|
+
toolbar, which at 200% text size on a short window had left the preview 0px
|
|
1390
|
+
tall.
|
|
1391
|
+
|
|
1392
|
+
- **`@kerfjs/ui` `TabScaffold` tabs can show a badge.** Give a
|
|
1393
|
+
`TabScaffoldTab` a `badge` (a count or short string) to show the iOS tab-bar
|
|
1394
|
+
badge — a compact, solid danger `Badge` at the top-trailing corner of the
|
|
1395
|
+
tab's icon. The badge is hidden from assistive technology; the tab's
|
|
1396
|
+
accessible name becomes `"<label>, <badgeLabel>"` (for example
|
|
1397
|
+
"Inbox, 3 unread"), with `badgeLabel` defaulting to the badge text. Tabs
|
|
1398
|
+
without a badge are unchanged.
|
|
1399
|
+
|
|
1400
|
+
- **`@kerfjs/ui` `ListItem` and `ListActionRow` labels stay out of the
|
|
1401
|
+
trailing slot.** A long single-word primary label (such as a Catalog sidebar
|
|
1402
|
+
entry named `ConnectionStateBanner` in a narrow rail) no longer runs
|
|
1403
|
+
underneath trailing status text. Single-line rows now end the primary label
|
|
1404
|
+
and description with a real ellipsis (previously the text was cut mid-glyph
|
|
1405
|
+
with no "…"), and `multiline` rows break a word wider than the label column
|
|
1406
|
+
onto the next line.
|
|
1407
|
+
|
|
1408
|
+
- **Custom elements keep the `role` and `aria-*` they set on themselves across
|
|
1409
|
+
re-renders.** Web components conventionally own their host's ARIA (Web
|
|
1410
|
+
Awesome's `wa-option` sets `role="option"` / `aria-selected`, `wa-divider`
|
|
1411
|
+
sets `role="separator"`; Shoelace and FAST do the same), but a template never
|
|
1412
|
+
mentions them, so the morph and the keyed-list attribute fast path stripped
|
|
1413
|
+
them on the next re-render. On any custom element (hyphenated tag), `role`
|
|
1414
|
+
and `aria-*` are now element-owned like `open`: never removed just because
|
|
1415
|
+
the template omits them. The template can still set or change them, a signal
|
|
1416
|
+
binding set to `null` / `false` still removes them, and plain elements are
|
|
1417
|
+
unchanged. Trade-off: omitting one from a static template no longer removes
|
|
1418
|
+
it from a custom element — render an explicit value (`aria-pressed="false"`)
|
|
1419
|
+
instead.
|
|
1420
|
+
|
|
1421
|
+
- **`@kerfjs/ui` layout regions no longer slow edits to long lists inside
|
|
1422
|
+
them.** The rule that clears the safe-area context for the children of a
|
|
1423
|
+
Workbench main area or panel, SplitView list or detail, NavStack view,
|
|
1424
|
+
TabScaffold scene, or CollapsiblePanel content made each child re-check the
|
|
1425
|
+
region in Chromium on every DOM change. A 1000-row list placed directly in
|
|
1426
|
+
one of these regions took about 46ms per style recalculation (2ms with the
|
|
1427
|
+
list one level down), and now takes about 0.2ms. Layout and insets are
|
|
1428
|
+
unchanged.
|
|
1429
|
+
|
|
1430
|
+
- **`@kerfjs/ui` `CollapsiblePanel` no longer slows insertions into long
|
|
1431
|
+
lists.** An expanded inline panel clears its screen edge for its siblings;
|
|
1432
|
+
the rules that did so selected the siblings themselves
|
|
1433
|
+
(`:has(~ panel)` and `panel ~ *`), which in Chromium made each row inserted
|
|
1434
|
+
into or removed from a long list restyle the list's other rows — about
|
|
1435
|
+
14.6ms instead of 0.2ms per insertion beside a 1000-row list. The panel's
|
|
1436
|
+
container now carries a flag that a CSS style query reads, so a list pays
|
|
1437
|
+
nothing. The edge still clears for the panel's siblings and returns when it
|
|
1438
|
+
collapses; the one difference is that a sibling placed before a left panel
|
|
1439
|
+
or after a right or bottom panel now loses the edge too.
|
|
1440
|
+
|
|
1441
|
+
- **`@kerfjs/ui` restore corners and covered floating controls no longer slow
|
|
1442
|
+
every style recalculation.** The `CollapsiblePanel` / `ResizableRegion`
|
|
1443
|
+
restore-corner anchor scope (`:has(> restore) > * > * > *`) and the static
|
|
1444
|
+
side-overlay covered flag (`:has(> open overlay) > :not(overlay)`) put a
|
|
1445
|
+
universal selector after a `:has()` container, which in Chromium restyled
|
|
1446
|
+
the children of every ancestor of each DOM change — about 85ms instead of
|
|
1447
|
+
1ms per edit beside a 1000-row list. The drawer now publishes its anchor
|
|
1448
|
+
only beside a restore control's container (or its work-area column), and
|
|
1449
|
+
the covered flag is set on the overlay's container and cleared on its
|
|
1450
|
+
overlay children. Restore-corner placement and covered-control hiding are
|
|
1451
|
+
unchanged; a new CSS unit test rejects the costly `:has()` shapes.
|
|
1452
|
+
|
|
1453
|
+
- **`@kerfjs/ui` adds `ContentItem`.** Import it from
|
|
1454
|
+
`@kerfjs/ui/content-item` to render one self-contained pane child with the
|
|
1455
|
+
shared 8px margin, 1px border, and 8px padding. Framing and shape are typed
|
|
1456
|
+
props instead of hand-written modifier classes:
|
|
1457
|
+
- `frame="framed"` paints the neutral border in the 1px the item always
|
|
1458
|
+
reserves, so its geometry does not change (replacing
|
|
1459
|
+
`class="kui-content-item kui-content-item--framed"`);
|
|
1460
|
+
- `shape="pill"` selects the 22px radius.
|
|
1461
|
+
- `ariaLabel` names a distinct region, and `focusTarget` makes the item a
|
|
1462
|
+
programmatic focus target (`tabindex="-1"`), such as a NavStack view's
|
|
1463
|
+
`data-nav-focus` target.
|
|
1464
|
+
|
|
1465
|
+
The `.kui-content-item` classes stay public for elements that must carry the
|
|
1466
|
+
geometry themselves; their CSS now lives in `content-item.css`, which
|
|
1467
|
+
`layout.css` still imports. There is no filled variant — use `SunkenPanel`
|
|
1468
|
+
for a lowered surface. The catalog, demos, and recipes use the component.
|
|
1469
|
+
|
|
1470
|
+
- **`@kerfjs/ui` icon-only toolbar buttons show the same help tag.** An
|
|
1471
|
+
icon-only `<button>` or link inside a `ToolbarControlGroup`, named by
|
|
1472
|
+
`aria-label` with no visible text, now shows the help tag icon-only Selects
|
|
1473
|
+
and PopupMenus show, with the same 500ms hover delay, keyboard-focus-only
|
|
1474
|
+
display, press/Escape dismissal, and quick scanning along a toolbar. The tag
|
|
1475
|
+
is `aria-hidden` and never renames the button. A button with a native
|
|
1476
|
+
`title`, or with its own Web Awesome tooltip, keeps that and gets no second
|
|
1477
|
+
tag. The `select/register` and `popup-menu/register` imports install it; a
|
|
1478
|
+
toolbar with icon-only buttons but neither control imports the new
|
|
1479
|
+
`@kerfjs/ui/help-tags/register` subpath, which registers only the tooltip.
|
|
1480
|
+
|
|
1481
|
+
- **`@kerfjs/ui` icon-only Select and PopupMenu triggers show a help tag.**
|
|
1482
|
+
An icon-only `Select` (single or `multiple` with `triggerIcon`) and an
|
|
1483
|
+
icon-only `PopupMenu` now show a Web Awesome tooltip naming the control on
|
|
1484
|
+
hover (after 500ms) and on keyboard focus: a filter reads "Filter by label:
|
|
1485
|
+
Bug, Docs", a single Select its name and current choice, a menu its `label`.
|
|
1486
|
+
It hides while the popup is open, on a press, and on Escape. The tag repeats
|
|
1487
|
+
the accessible name, so it is `aria-hidden` and never joins
|
|
1488
|
+
`aria-labelledby`; screen readers still hear the name once. It is installed
|
|
1489
|
+
by the existing `select/register` and `popup-menu/register` imports, needs no
|
|
1490
|
+
props, and never appears for labeled Selects or text menu triggers.
|
|
1491
|
+
|
|
1492
|
+
- **`@kerfjs/ui` toolbar groups drop their focus ring while a popup is open.**
|
|
1493
|
+
A `ToolbarControlGroup` that owns the ring (`focusRing="outline"` or
|
|
1494
|
+
`"halo"`) no longer paints it while a Select listbox or `PopupMenu` inside it
|
|
1495
|
+
is open; the open popup shows focus, and the ring returns when the popup
|
|
1496
|
+
closes with focus still in the group. This matches the per-control Select
|
|
1497
|
+
and PopupMenu triggers.
|
|
1498
|
+
|
|
1499
|
+
- **`@kerfjs/ui` multiple `Select` can be an icon-only toolbar filter menu.**
|
|
1500
|
+
Set `selectedPresentation: 'icon-only'` on a `multiple` Select together with
|
|
1501
|
+
a fixed `triggerIcon` (for example a funnel `LucideIcon`); the types require
|
|
1502
|
+
`triggerIcon` there and reject it everywhere else. The trigger keeps the
|
|
1503
|
+
icon-only caret pill used in a `ToolbarControlGroup`, and:
|
|
1504
|
+
- shows the fixed icon whatever is chosen;
|
|
1505
|
+
- adds a compact count `Badge` while any choice is chosen;
|
|
1506
|
+
- ends the combobox's accessible name with the chosen labels in choice order
|
|
1507
|
+
("Filter by label: Bug, Docs"), leaving the hidden value text empty so the
|
|
1508
|
+
list is not announced twice.
|
|
1509
|
+
|
|
1510
|
+
The popup still stays open while choices toggle.
|
|
1511
|
+
|
|
1512
|
+
- **`@kerfjs/ui` `Select` options keep their accessibility semantics across
|
|
1513
|
+
re-renders.** Re-rendering a Select (for example after its `change` handler
|
|
1514
|
+
updates the controlling signal) removed the `role="option"` and
|
|
1515
|
+
`aria-selected` Web Awesome sets on each option, so screen readers lost every
|
|
1516
|
+
option's role and selected state. They now survive in single and `multiple`
|
|
1517
|
+
Selects through the core rule below (custom elements own their `role` /
|
|
1518
|
+
`aria-*`), with no Select-specific restore.
|
|
1519
|
+
|
|
1520
|
+
- **`@kerfjs/ui` `Select` dividers keep their separator role across
|
|
1521
|
+
re-renders.** The `wa-divider` a `separatorBefore` choice adds lost the
|
|
1522
|
+
`role="separator"` and `aria-orientation` Web Awesome sets on it the first
|
|
1523
|
+
time the enclosing mount re-rendered, and never got them back, so assistive
|
|
1524
|
+
technology stopped announcing the break between option runs. The Select now
|
|
1525
|
+
renders both attributes itself.
|
|
1526
|
+
|
|
1527
|
+
- **`@kerfjs/ui` `Select` and `PopupMenu` re-renders no longer force Web
|
|
1528
|
+
Awesome updates.** Web Awesome reflects its default `size`, `appearance`,
|
|
1529
|
+
`placement`, and `orientation` onto `wa-select`, `wa-dropdown`, and
|
|
1530
|
+
`wa-divider`; the templates omitted them, so every re-render of the enclosing
|
|
1531
|
+
mount stripped them and each host ran a full Lit update to put them back. The
|
|
1532
|
+
templates now render those defaults (`wa-select size="m"
|
|
1533
|
+
appearance="outlined" placement="bottom"`, `wa-dropdown size="m"`, divider
|
|
1534
|
+
`orientation="horizontal"`), so an unchanged re-render leaves the hosts
|
|
1535
|
+
alone. No visual change. The `@kerfjs/ui/webawesome` JSX declarations type
|
|
1536
|
+
these attributes.
|
|
1537
|
+
|
|
1538
|
+
- **`@kerfjs/ui` Workbench and CollapsiblePanel panes and chrome lists are
|
|
1539
|
+
configurable.** The `Pane`s these layouts compose around app content now
|
|
1540
|
+
take the new `PaneConfig` type (`contentElement`, `contentLabel`,
|
|
1541
|
+
`separators`, `safeAreaEdges`): a Workbench panel's or `CollapsiblePanel`'s
|
|
1542
|
+
`pane`, and the Workbench's `mainPane`. The `List`s holding `mainHeader` /
|
|
1543
|
+
`mainFooter` take the new `ListConfig` type (`gap`, `hAlign`, `vAlign`,
|
|
1544
|
+
`dividerSides`, `textInsets`, `controlInsets`) through `mainHeaderList` /
|
|
1545
|
+
`mainFooterList`. Previously this configuration was hard-coded, so, for
|
|
1546
|
+
example, a navigator rail could not render its content as a `nav` landmark
|
|
1547
|
+
without restyling. Omitted or `undefined` fields keep today's defaults, and
|
|
1548
|
+
the default markup is unchanged.
|
|
1549
|
+
|
|
1550
|
+
- **`@kerfjs/ui` `SplitView` forwards its `ResizableRegion` and compact
|
|
1551
|
+
`NavStack` configuration.** `resizable` now also takes the list region's
|
|
1552
|
+
`separator`, `handleIcon`, `contentOverflow`, and collapse options
|
|
1553
|
+
(`collapsed`, `transitioning`, `collapseMotion`, `restoreControl`,
|
|
1554
|
+
`restorePosition`), so an app can hide the list and float a restore control
|
|
1555
|
+
without leaving `SplitView`. The new `compactStack` prop forwards the compact
|
|
1556
|
+
stack's `toolbarConfig`, `backIcon`, `backText`, `hideToolbar`, and
|
|
1557
|
+
persistent `bottomToolbar`, and gives the list and detail views their own
|
|
1558
|
+
toolbar groups (`list` / `detail`: `leading`, `center`, `toolbar`,
|
|
1559
|
+
`bottomToolbar`). Omitted options keep today's defaults.
|
|
1560
|
+
|
|
1561
|
+
- **`@kerfjs/ui` `NavStack` renders its top chrome as a real `Toolbar`.** The
|
|
1562
|
+
back control is a borderless `ToolbarControlGroup` and the title a
|
|
1563
|
+
`ToolbarText` in the leading zone, and the stack now forwards:
|
|
1564
|
+
- `toolbarConfig` — the `Toolbar` configuration (`dividerSides`,
|
|
1565
|
+
`centerAlign`, `responsive`, `responsiveAt`, `safeAreaEdges`) plus `label`,
|
|
1566
|
+
`titleSize` (default `large`), and `headingLevel`;
|
|
1567
|
+
- per-view `leading` and `center` groups beside the existing trailing
|
|
1568
|
+
`toolbar`;
|
|
1569
|
+
- `backIcon` and visible `backText` for the back control.
|
|
1570
|
+
|
|
1571
|
+
The defaults keep today's bar: no divider, one 44px band, and the top and
|
|
1572
|
+
side safe-area edges claimed. The hand-rolled `kui-nav-stack__lead` and
|
|
1573
|
+
`kui-nav-stack__actions` wrappers are gone (their content now sits in the
|
|
1574
|
+
toolbar's zones), and `kui-nav-stack__back` / `kui-nav-stack__back-icon`
|
|
1575
|
+
are no longer styled by the stack.
|
|
1576
|
+
|
|
1577
|
+
- **`@kerfjs/ui` configures with props instead of token overrides.** Five
|
|
1578
|
+
settings apps previously reached through raw `--kui-*` overrides now have a
|
|
1579
|
+
typed prop or modifier; each defaults to today's rendering, and the
|
|
1580
|
+
underlying tokens keep working:
|
|
1581
|
+
- `FloatingToolbar` `inset` (a `CssLength`, default `--kui-space-m`) moves
|
|
1582
|
+
it from the container edges. Omit it inside a restore corner, which owns
|
|
1583
|
+
the inset.
|
|
1584
|
+
- `DisclosureArrow` `size` (a `CssLength`, default 18px root-scaled).
|
|
1585
|
+
- `ListHeader` `headingLevel` (1–6, default 2) sets the label's native
|
|
1586
|
+
heading element for passive and trailing-action headers; a toggle header
|
|
1587
|
+
has no heading and rejects it at compile time.
|
|
1588
|
+
- `TokenSearchField` `clearIcon` replaces the clear action's glyph.
|
|
1589
|
+
- `.kui-content-item--framed` paints the standard neutral border on a
|
|
1590
|
+
content item that marks a real distinction, with no geometry change.
|
|
1591
|
+
|
|
1592
|
+
The docs and AI guidance also stop recommending `--kui-edge-inset-*`
|
|
1593
|
+
overrides: an app-owned arrangement passes `safeAreaEdges` to its panes and
|
|
1594
|
+
edge-claiming toolbars (including the layout toolbar configurations, which
|
|
1595
|
+
forward it).
|
|
1596
|
+
|
|
1597
|
+
- **`@kerfjs/ui` hides a work area's floating controls under an open side
|
|
1598
|
+
overlay.** While a side overlay is open — a Workbench rail (static
|
|
1599
|
+
`presentation: "overlay"`, or a responsive overlay whose breakpoint applies),
|
|
1600
|
+
a `wireSidebar` compact overlay or `presentation="overlay"`
|
|
1601
|
+
`CollapsiblePanel`, or a horizontal `presentation="overlay"`
|
|
1602
|
+
`ResizableRegion` — the covered work area's `FloatingToolbar`s and the
|
|
1603
|
+
layouts' restore corners are now hidden (`visibility: hidden`, so they also
|
|
1604
|
+
leave the tab order and the accessibility tree) instead of relying on
|
|
1605
|
+
stacking order alone. A phone-width app could otherwise paint the main
|
|
1606
|
+
column's floating drawer toggle over its open inspector. They come back as
|
|
1607
|
+
the overlay closes; the overlay's own floating controls and a bottom
|
|
1608
|
+
drawer's overlay are unaffected.
|
|
1609
|
+
|
|
1610
|
+
- **`@kerfjs/ui` `Select` supports multiple selection.** Set `multiple: true`
|
|
1611
|
+
and pass the chosen values as an array `value`; the props are typed so an
|
|
1612
|
+
array value requires `multiple`. Behavior:
|
|
1613
|
+
- The popup stays open while the person toggles choices with the pointer,
|
|
1614
|
+
Enter, or Space, and closes only on an outside press, Escape, or focus
|
|
1615
|
+
leaving.
|
|
1616
|
+
- Each chosen option shows a check.
|
|
1617
|
+
- The closed control summarizes the chosen labels in choice order as a short
|
|
1618
|
+
localized list, or shows `placeholderText` when none are chosen.
|
|
1619
|
+
- `change` / `input` report the value array, and a form submits every chosen
|
|
1620
|
+
value under `name`.
|
|
1621
|
+
- Re-rendering with a different `value` updates the selection even after the
|
|
1622
|
+
person has interacted.
|
|
1623
|
+
|
|
1624
|
+
`renderSelected` and `selectedPresentation="icon-only"` stay single-value
|
|
1625
|
+
only.
|
|
1626
|
+
|
|
1627
|
+
- **`@kerfjs/ui` `PopupMenu` now looks exactly like `Select`.** Both read one
|
|
1628
|
+
shared popup contract, so a command menu beside a value list in a toolbar
|
|
1629
|
+
draws the same popup. `PopupMenu` changes:
|
|
1630
|
+
- its caret turns to face the open menu;
|
|
1631
|
+
- its menu fades in without scaling;
|
|
1632
|
+
- it takes the Select listbox's 4px inset (also under the default
|
|
1633
|
+
`menuInset="standard"`);
|
|
1634
|
+
- its rows use the Select option's height, padding, and reserved check
|
|
1635
|
+
column, and its icons use the same 16px size and 8px gap;
|
|
1636
|
+
- a keyboard-focused item takes the Select's current-option fill instead of
|
|
1637
|
+
a focus ring;
|
|
1638
|
+
- headings render as the Select's uppercase group titles rather than slotted
|
|
1639
|
+
`h3` elements.
|
|
1640
|
+
|
|
1641
|
+
An open `Select` also no longer paints its trigger focus ring. The open
|
|
1642
|
+
listbox shows focus, and the ring returns when it closes.
|
|
1643
|
+
|
|
1644
|
+
- **`@kerfjs/ui` `Catalog` exposes its sidebar and toolbar configuration.** New
|
|
1645
|
+
`sidebar` prop (size, `resizable`, `separator`, `collapseMotion`,
|
|
1646
|
+
`presentation`, `responsiveOverlayAt`, `compactOverlay`, and the header
|
|
1647
|
+
`toolbar`'s `ToolbarConfig`) forwarded to its Workbench rail, plus
|
|
1648
|
+
`mainToolbar` / `footerToolbar` `ToolbarConfig` props. `wireCatalog` takes
|
|
1649
|
+
`sidebarSize` / `sidebarStorageKey` to wire a resizable sidebar. Today's
|
|
1650
|
+
288px fixed sidebar and toolbar policies remain the defaults.
|
|
1651
|
+
|
|
1652
|
+
- **`@kerfjs/ui` composed toolbars are configurable.** `WorkbenchMainToolbar`,
|
|
1653
|
+
`WorkbenchMainBottomToolbar`, and the panel `toolbar` of a Workbench panel or
|
|
1654
|
+
`CollapsiblePanel` now take the `Toolbar`'s configuration: the new
|
|
1655
|
+
`ToolbarConfig` type, covering `dividerSides`, `centerAlign`, `responsive`,
|
|
1656
|
+
`responsiveAt`, and `safeAreaEdges`. Previously their dividers were
|
|
1657
|
+
hard-coded, so for example dropping the line between a toolbar and its
|
|
1658
|
+
content took CSS. Today's dividers remain the defaults. Also:
|
|
1659
|
+
- `mainBottomToolbar` and panel toolbars take a `center`;
|
|
1660
|
+
- panel toggles take localized `showLabel` / `hideLabel`;
|
|
1661
|
+
- a Workbench panel's floating restore controls follow its
|
|
1662
|
+
`restorePosition`.
|
|
1663
|
+
|
|
1664
|
+
- **Breaking (`@kerfjs/ui`): removed the pre-release compatibility surface.**
|
|
1665
|
+
- The `DividerSides` type is gone; use `Sides`, from the renamed `sides`
|
|
1666
|
+
module.
|
|
1667
|
+
- `ListInsetText.horizontalOnly` and its `kui-list-inset-text--horizontal`
|
|
1668
|
+
class are gone; pass `sides="rl"` instead.
|
|
1669
|
+
- The legacy color tokens are gone, both as `--kui-color-*` properties and
|
|
1670
|
+
as `uiColor()` names. Replace them with their canonical tokens:
|
|
1671
|
+
|
|
1672
|
+
| Removed | Use instead |
|
|
1673
|
+
| --------------------------------------------- | ----------------------- |
|
|
1674
|
+
| `border` | `neutral-border-normal` |
|
|
1675
|
+
| `border-quiet` | `neutral-border-quiet` |
|
|
1676
|
+
| `accent` | `brand-fill-normal` |
|
|
1677
|
+
| `accent-text` | `brand-on-quiet` |
|
|
1678
|
+
| `pop` | `pop-fill-quiet` |
|
|
1679
|
+
| `pop-text` | `pop-on-fill` |
|
|
1680
|
+
| `success`, `warning`, `danger` | `*-fill-quiet` |
|
|
1681
|
+
| `success-text`, `warning-text`, `danger-text` | `*-on-quiet` |
|
|
1682
|
+
|
|
1683
|
+
- **New `@kerfjs/ui` `PopupMenu` (`@kerfjs/ui/popup-menu`).** It renders a
|
|
1684
|
+
trigger and typed commands, headings, and dividers over the Web Awesome
|
|
1685
|
+
dropdown. Put it in a `single` `ToolbarControlGroup` with `nestedDropdown`, or
|
|
1686
|
+
wrap it in a `PopupSurface`. Register it once with
|
|
1687
|
+
`@kerfjs/ui/popup-menu/register`. It replaces hand-written `wa-dropdown`
|
|
1688
|
+
markup, which the catalog discourages: the guidance, the toolbar demos, and
|
|
1689
|
+
the Catalog's "Components" menu now use it. It also fixes two defects that
|
|
1690
|
+
hand-written menus had:
|
|
1691
|
+
- Icon-only triggers were unnamed, because a Web Awesome button ignores an
|
|
1692
|
+
`aria-label` on its host. PopupMenu renders `label` as visually hidden text
|
|
1693
|
+
inside the button.
|
|
1694
|
+
- A keyboard choice (Enter or Space) never reached click-delegated
|
|
1695
|
+
`data-action` handlers. PopupMenu's registration routes it through the
|
|
1696
|
+
item's click.
|
|
1697
|
+
- The UX catalog's application-layout demo no longer uses the discouraged
|
|
1698
|
+
`wa-button-group`.
|
|
1699
|
+
|
|
1700
|
+
- **`@kerfjs/ui`'s `TokenSearchField` takes a `revision` prop for programmatic
|
|
1701
|
+
text replacement.** The editor's text is DOM-owned, so a new `query` with the
|
|
1702
|
+
same tokens was silently ignored, for example when reseeding a persistent
|
|
1703
|
+
dialog's field on reopen. Changing `revision` rebuilds the editor from `query`
|
|
1704
|
+
and `tokens`, so consumers no longer need to re-key a wrapper element.
|
|
1705
|
+
|
|
1706
|
+
- **`@kerfjs/ui`'s `TabBar` strip no longer scrolls vertically.** The strip set
|
|
1707
|
+
only `overflow-x: auto`, so any vertical excess (consumer padding, focus-ring
|
|
1708
|
+
insets, taller tabs under larger text) let it scroll up and down on touch. It
|
|
1709
|
+
now scrolls only horizontally, and it takes a `min-height` so it grows to fit
|
|
1710
|
+
taller tabs instead of clipping them.
|
|
1711
|
+
|
|
1712
|
+
- **The `@kerfjs/ui` desktop app-shell recipe is a `Workbench`.** The old
|
|
1713
|
+
pane switcher that showed one pane at a time below desktop sizes is gone. The
|
|
1714
|
+
navigation and inspector are now resizable Workbench rails with their own
|
|
1715
|
+
toolbars, and their show toggles relocate into the work-area toolbar. On a
|
|
1716
|
+
narrow container the rails overlay the task list one at a time. The
|
|
1717
|
+
collapsible-sidebar recipe composes each panel's `toolbar` and uses
|
|
1718
|
+
`CollapsiblePanelRelocated` for its restore controls.
|
|
1719
|
+
|
|
1720
|
+
- **`@kerfjs/ui`'s `CollapsiblePanel` composes a panel toolbar and relocates its
|
|
1721
|
+
controls.** A panel takes the same `toolbar` roles as a `Workbench` panel
|
|
1722
|
+
(`title`, `panelOnly`, `constant`, and a standard `toggle`) plus a `footer`,
|
|
1723
|
+
and the new `CollapsiblePanelRelocated` renders a collapsed panel's constant
|
|
1724
|
+
groups and toggle wherever the app's work-area toolbar holds them.
|
|
1725
|
+
`wireSidebar` hands focus to that relocated toggle when the panel closes, even
|
|
1726
|
+
when the app renders it a frame late. `collapsiblePanelToggleIcon` is
|
|
1727
|
+
unchanged.
|
|
1728
|
+
|
|
1729
|
+
- **`@kerfjs/ui`'s `Catalog` is built on `Workbench` and dogfoods the package's
|
|
1730
|
+
components.** The sidebar is a Workbench left rail with the standard toggle
|
|
1731
|
+
(labels "Show/Hide {brand} catalog"), which moves into the entry toolbar while
|
|
1732
|
+
collapsed; on a small screen the sidebar overlays the stage instead of the
|
|
1733
|
+
former stacked two-column navigation, which is gone. The sidebar, sections,
|
|
1734
|
+
footer, and example notes are `List` / `ListHeader` / `ListInsetText` / `Text`
|
|
1735
|
+
compositions, and most catalog CSS (and every viewport media query in the
|
|
1736
|
+
shell) is removed. New: `Catalog`'s `id`, `headerPlacement`, and
|
|
1737
|
+
`footerPlacement`; `wireCatalog`'s `collapsed` and `id` options (the sidebar is
|
|
1738
|
+
wired like a Workbench rail and an open overlay closes on a selection);
|
|
1739
|
+
`Workbench`'s `mainHeader`, `mainFooter`, `mainHeaderPlacement`,
|
|
1740
|
+
`mainFooterPlacement`, and `mainToolbar.responsive` / `responsiveAt`;
|
|
1741
|
+
`ListInsetText`'s `rootAttributes`. `wireWorkbench` now also re-checks panel
|
|
1742
|
+
breakpoints when the root font size changes, and hands focus to a panel's
|
|
1743
|
+
relocated toggle when an unfocused click on its own toggle closes it (WebKit).
|
|
1744
|
+
|
|
1745
|
+
- **`@kerfjs/ui`'s `Workbench` rails overlay the work area on small screens by
|
|
1746
|
+
default.** A rail's `responsiveOverlayAt` now defaults to `"narrow"` (704px
|
|
1747
|
+
of Workbench width; the new `"never"` keeps it inline), so a sidebar covers
|
|
1748
|
+
the work area and any open drawer instead of squeezing it, one at a time
|
|
1749
|
+
with `wireWorkbench`. On a compact (448px) Workbench an open overlay rail
|
|
1750
|
+
fills the width less a 44px dismiss strip
|
|
1751
|
+
(`--kui-workbench-overlay-dismiss-margin`) on the side away from its edge;
|
|
1752
|
+
the new per-rail `compactOverlay: "full"` fills it. The bottom drawer's
|
|
1753
|
+
behavior is unchanged. `WorkbenchPanelToolbar` and the other panel-toolbar
|
|
1754
|
+
types are now exported from `@kerfjs/ui/workbench`.
|
|
1755
|
+
|
|
1756
|
+
- **`@kerfjs/ui`'s `Workbench` composes panel toolbars and moves a closed
|
|
1757
|
+
panel's controls into the work area.** A panel takes an optional `toolbar`
|
|
1758
|
+
(`title`, `panelOnly`, `constant`, and a standard `toggle: { action, name }`
|
|
1759
|
+
the Workbench renders) and `footer`; the Workbench takes `mainToolbar` and
|
|
1760
|
+
`mainBottomToolbar`. While a panel is closed its constant groups and toggle
|
|
1761
|
+
move to the work area — a left rail's lead the main toolbar, a right rail's
|
|
1762
|
+
end it, a drawer's trail the bottom toolbar or float in a corner
|
|
1763
|
+
`FloatingToolbar` — and its panel-only groups stay behind. `wireWorkbench`
|
|
1764
|
+
keeps focus with the toggle as it moves. Panels without a `toolbar` render
|
|
1765
|
+
exactly as before, and a region's only-child `Pane` or layout now fills it.
|
|
1766
|
+
|
|
1767
|
+
- **`@kerfjs/ui`'s list-detail dialog guidance is Workbench-shaped.** On roomy
|
|
1768
|
+
devices the list is a full-height sidebar and the detail a full-height main
|
|
1769
|
+
column, each a `Pane` with its own top `Toolbar`; the main column carries
|
|
1770
|
+
the primary title, the close control (`data-dialog="close"` in a
|
|
1771
|
+
`without-header` Web Awesome dialog), and the record actions, instead of a
|
|
1772
|
+
dialog header spanning both columns. The recipe, `docs/recipes.md`, and the
|
|
1773
|
+
shipped AI skill say so; compact devices keep the full-screen drill-down
|
|
1774
|
+
sheet.
|
|
1775
|
+
|
|
1776
|
+
- **`@kerfjs/ui`'s `ToolbarControlGroup` centers a direct icon tile.** A
|
|
1777
|
+
non-interactive icon placed directly in a group — a heading's identity
|
|
1778
|
+
glyph — now takes an icon button's 40px slot and 16px visual, so it centers
|
|
1779
|
+
in the group. It previously sat at the group's start edge, which pushed
|
|
1780
|
+
apps to wrap it in a focusable `<button>` that did nothing.
|
|
1781
|
+
|
|
1782
|
+
- **`@kerfjs/ui`'s `Toolbar` keeps its controls in a top control band.** A
|
|
1783
|
+
toolbar now reserves one 44px band at its top: each zone item no taller than
|
|
1784
|
+
the band is centered in it by its own size, and a taller item — a wrapped
|
|
1785
|
+
`ToolbarText` title, a multi-line search, a second trailing row — starts at
|
|
1786
|
+
the band's top and grows down without moving the others. A wrapped title
|
|
1787
|
+
centers its first line in the band, so trailing controls stay beside that
|
|
1788
|
+
line instead of dropping to the middle of the whole title.
|
|
1789
|
+
|
|
1790
|
+
- **`@kerfjs/ui`'s segmented `TabBar` ends its strip concentric with the pill
|
|
1791
|
+
track.** The first tab's leading corners, and with `allocation="fill"` the
|
|
1792
|
+
last tab's trailing corners, now follow the track's curve instead of keeping
|
|
1793
|
+
the small segment radius, and compact tabs are inset from the track's ends
|
|
1794
|
+
by the same distance as from its top and bottom. Corners between tabs are
|
|
1795
|
+
unchanged.
|
|
1796
|
+
|
|
1797
|
+
- **`@kerfjs/ui`'s `StateBanner` keeps its title, badge, and detail on one
|
|
1798
|
+
baseline in Safari.** The truncating detail was a clipped `inline-block`,
|
|
1799
|
+
which WebKit baselines at its bottom edge: the detail rose about 2px above
|
|
1800
|
+
the title and pushed the title and badge down, so the banner's contents
|
|
1801
|
+
looked vertically misaligned. The detail is now an inline flex wrapper
|
|
1802
|
+
around a clipped inner `<span>`, which takes its text baseline in every
|
|
1803
|
+
engine; truncation and the narrow-width detail line are unchanged.
|
|
1804
|
+
|
|
1805
|
+
- **`@kerfjs/ui`'s `wireTabBars` reveals a tab the application selects.** A
|
|
1806
|
+
tab added and selected by the app in an overflowing `TabBar` stayed
|
|
1807
|
+
off-screen, because the wiring revealed a selection only at wire-up, on
|
|
1808
|
+
focus, and after its own keyboard/drag changes. A change of a bar's selected
|
|
1809
|
+
tab now scrolls that bar's strip (never the page) to show it; re-renders that
|
|
1810
|
+
keep the selection leave a user-scrolled strip alone.
|
|
1811
|
+
|
|
1812
|
+
- **`eslint-plugin-kerfjs`'s `ui-composition` rule resolves application
|
|
1813
|
+
wrappers imported through a barrel.** A cataloged wrapper registered only by
|
|
1814
|
+
its defining source file, so `import { DemandSegmentsControl } from
|
|
1815
|
+
'./components/index.js'` (where `index.ts` re-exports it) was an unknown
|
|
1816
|
+
element and reported `KUI-L202` in a toolbar zone despite its `rendersAs`.
|
|
1817
|
+
Relative re-exports — `export { X } from`, `export { X as Y } from`,
|
|
1818
|
+
`export * from`, and chains of them — are now followed to the cataloged
|
|
1819
|
+
source file. Type-only and namespace re-exports and non-cataloged components
|
|
1820
|
+
stay unresolved.
|
|
1821
|
+
|
|
1822
|
+
- **A collapsed `@kerfjs/ui` `Workbench` panel or `ResizableRegion` leaves
|
|
1823
|
+
the accessibility tree.** Only its content was `inert`, so the labeled
|
|
1824
|
+
`aside` / `section` stayed behind as an empty complementary or region
|
|
1825
|
+
landmark that a screen-reader user could still land on. The collapsed
|
|
1826
|
+
region itself now renders `inert` and `aria-hidden="true"`, like a
|
|
1827
|
+
collapsed `CollapsiblePanel`; its separator was already hidden, and each
|
|
1828
|
+
`restoreControl` renders outside it and stays reachable.
|
|
1829
|
+
|
|
1830
|
+
- **An expanded `@kerfjs/ui` `CollapsiblePanel` holds its size in a flex
|
|
1831
|
+
layout.** The panel shrank like any flex item beside a work area with wide
|
|
1832
|
+
content, while its content kept the panel's fixed size for the slide-out, so
|
|
1833
|
+
the panel's edge clipped the content — in the collapsible-sidebar recipe at
|
|
1834
|
+
1280px, the rail showed 211 of its 232px and cut off the selected Inbox
|
|
1835
|
+
row's count. The panel is now `flex-shrink: 0`; the sibling work area gives
|
|
1836
|
+
way instead.
|
|
1837
|
+
|
|
1838
|
+
- **`@kerfjs/ui` overlay panels span their host on the fixed axis.** The
|
|
1839
|
+
85vw / 85vh overlay maximums (`--kui-resizable-region-overlay-max-*`,
|
|
1840
|
+
`--kui-workbench-overlay-max-*`) applied to both axes, so an overlay bottom
|
|
1841
|
+
drawer stopped about 15% short of its host's width and an overlay side rail
|
|
1842
|
+
in a full-height layout stopped short of the bottom. Each maximum now caps
|
|
1843
|
+
only the panel's resizable axis: side overlays cap their width, drawers
|
|
1844
|
+
their height.
|
|
1845
|
+
|
|
1846
|
+
- **An overlay `@kerfjs/ui` `ResizableRegion` paints the surface.** With
|
|
1847
|
+
`presentation="overlay"` the region floated over the work area with a
|
|
1848
|
+
shadow but no background, so the content beneath — and a collapsed rail's
|
|
1849
|
+
restore control stacked under it — showed through. It now paints
|
|
1850
|
+
`--kui-color-surface`, like an overlay `CollapsiblePanel`; an inline region
|
|
1851
|
+
stays transparent over its host.
|
|
1852
|
+
|
|
1853
|
+
- **A pinned `@kerfjs/ui` resize separator no longer overwrites the
|
|
1854
|
+
remembered size.** When a container squeezes a `Workbench` rail, drawer, or
|
|
1855
|
+
`ResizableRegion` below its `min` (or its reachable range collapses to one
|
|
1856
|
+
size), the separator cannot move it, yet an arrow/Home/End key or a drag
|
|
1857
|
+
still committed the configured `min` to the app's size signal and storage:
|
|
1858
|
+
a rail remembered at 280px silently became 180px and came back at 180px
|
|
1859
|
+
when the window widened. A pinned separator now commits nothing, so the
|
|
1860
|
+
track returns at its remembered size once there is room.
|
|
1861
|
+
|
|
1862
|
+
- **A `pending` `@kerfjs/ui` `AppTab` is selectable and no longer dimmed.**
|
|
1863
|
+
A known tab that is still opening now keeps its select button enabled and
|
|
1864
|
+
in the roving tab order, so a user can switch to it and the application can
|
|
1865
|
+
show placeholder content in its panel until loading completes. With
|
|
1866
|
+
`webawesome.css` loaded, Web Awesome's native `button:disabled` no longer
|
|
1867
|
+
dims the pending pill to 50%; it shows only its quiet name color and
|
|
1868
|
+
trailing spinner, as documented. Close and dragging stay disabled while
|
|
1869
|
+
pending, and it stays `aria-busy`. An unknown `placeholder` tab is
|
|
1870
|
+
unchanged: disabled and out of the tab order.
|
|
1871
|
+
|
|
1872
|
+
- **Closing a `@kerfjs/ui` `Workbench` panel from its own control by mouse
|
|
1873
|
+
returns focus in Safari.** Safari never focuses a clicked button, so
|
|
1874
|
+
pressing an open panel's Hide control blurred the focused control to the
|
|
1875
|
+
page before the click collapsed the panel, and `wireWorkbench` — which
|
|
1876
|
+
returns focus only when it is inside the closing panel — left focus on the
|
|
1877
|
+
page body instead of the toggle that opened it. A press that starts inside
|
|
1878
|
+
the panel while focus is there now counts as focus inside, so the close
|
|
1879
|
+
returns it; focus the user has moved to another element since is left
|
|
1880
|
+
alone.
|
|
1881
|
+
- **A collapsed `@kerfjs/ui` `CollapsiblePanel` or `ResizableRegion` leaves
|
|
1882
|
+
the Tab order.** Both kept collapsed content in the DOM, only slid out and
|
|
1883
|
+
clipped, so Tab still reached its controls; focusing one scrolled the clipped
|
|
1884
|
+
panel, and a `CollapsiblePanel`'s `aria-hidden` put those focusable controls
|
|
1885
|
+
inside a hidden subtree. A collapsed `CollapsiblePanel` now renders `inert`
|
|
1886
|
+
beside its `aria-hidden`, and a collapsed `ResizableRegion` renders its
|
|
1887
|
+
content wrapper `inert`, with no wiring needed. The slide-out still animates,
|
|
1888
|
+
each `restoreControl` stays outside the inert subtree and reachable, and
|
|
1889
|
+
`wireSidebar` still hands focus to the panel's toggle when it collapses from
|
|
1890
|
+
inside.
|
|
1891
|
+
|
|
1892
|
+
- **A collapsed `@kerfjs/ui` `Workbench` rail's restore control no longer
|
|
1893
|
+
covers an expanded bottom drawer.** A `leftRail` / `rightRail`
|
|
1894
|
+
`restoreControl` floats in the Workbench's bottom corner, which the bottom
|
|
1895
|
+
drawer's column reaches once the rail collapses, so with the drawer expanded
|
|
1896
|
+
the control sat on the drawer's content. An expanded inline drawer now
|
|
1897
|
+
publishes its top edge as a CSS anchor scoped to its Workbench, and the
|
|
1898
|
+
rail's control floats the restore inset above it, returning to the corner
|
|
1899
|
+
when the drawer collapses. An overlay drawer (static or `responsiveOverlayAt`)
|
|
1900
|
+
still covers the control as every open overlay does, a nested Workbench's
|
|
1901
|
+
drawer moves only its own rails' controls, and engines without anchor
|
|
1902
|
+
positioning keep the corner.
|
|
1903
|
+
|
|
1904
|
+
- **A collapsed `@kerfjs/ui` `Workbench` panel's content leaves the Tab order.**
|
|
1905
|
+
A collapsed rail or bottom drawer kept its content in the DOM, only slid out
|
|
1906
|
+
and clipped, so Tab still reached its controls; focusing one (at a narrow
|
|
1907
|
+
width, the collapsed inspector's or output drawer's own Hide control)
|
|
1908
|
+
scrolled the clipped panel and slid its hidden content back over the work
|
|
1909
|
+
area. The panel's content wrapper now renders `inert` while `collapsed`, with
|
|
1910
|
+
no wiring needed, so neither Tab nor assistive technology reaches it; the
|
|
1911
|
+
slide-out still animates and the `restoreControl`, which lives outside the
|
|
1912
|
+
content, stays reachable.
|
|
1913
|
+
|
|
1914
|
+
- **A `kerfjs/overlay` popover or tooltip in a transformed or filtered modal
|
|
1915
|
+
`<dialog>` now lands against its anchor.** A surface rendered into a
|
|
1916
|
+
dialog's `[data-kerf-overlay-host][data-morph-skip]` slot is
|
|
1917
|
+
`position: fixed`, and a dialog styled with `transform`, `filter`,
|
|
1918
|
+
`perspective`, `contain`, or `will-change` becomes the containing block for
|
|
1919
|
+
fixed descendants, so the surface used to land offset by the dialog's
|
|
1920
|
+
position (and scale). `positionAnchored` (and so `autoReposition`,
|
|
1921
|
+
`popover()`, and `tooltip()`) now measures the element's fixed-position
|
|
1922
|
+
containing block with a transient 1px probe and maps its viewport
|
|
1923
|
+
coordinates into it, compensating translation and scale. Rotated or skewed
|
|
1924
|
+
containing blocks are not compensated.
|
|
1925
|
+
- **The `@kerfjs/ui` UX catalog demonstrates a standalone restore control.**
|
|
1926
|
+
The CollapsiblePanel route gains a "Restore control" example: a bottom
|
|
1927
|
+
drawer that collapses to a `FloatingToolbar` `restoreControl` in its frame's
|
|
1928
|
+
corner, wired with `wireSidebar` so the control restores the drawer and
|
|
1929
|
+
focus moves between it and the drawer's own hide toggle.
|
|
1930
|
+
|
|
1931
|
+
- **A `@kerfjs/ui` collapsed rail's restore control no longer covers an open
|
|
1932
|
+
bottom drawer beside it.** When a `CollapsiblePanel` or `ResizableRegion`
|
|
1933
|
+
with a `restoreControl` shared its container with an expanded bottom
|
|
1934
|
+
drawer — a bottom `CollapsiblePanel` or bottom `ResizableRegion` — as a
|
|
1935
|
+
sibling or inside the app's work-area column, the control floated in the
|
|
1936
|
+
container's bottom corner, on top of the drawer. It now floats the same
|
|
1937
|
+
inset above the drawer's top edge, follows the drawer as it resizes, and
|
|
1938
|
+
returns to the corner when the drawer collapses. A drawer nested deeper,
|
|
1939
|
+
inside the work area's own content, does not move it. This uses CSS anchor
|
|
1940
|
+
positioning; engines without it keep the container corner.
|
|
1941
|
+
|
|
1942
|
+
- **An open `@kerfjs/ui` `CollapsiblePanel` or `ResizableRegion` overlay now
|
|
1943
|
+
covers other panels' restore controls, as a `Workbench` overlay does.** A
|
|
1944
|
+
collapsed panel's `restoreControl` stacked at z-index 42, above
|
|
1945
|
+
`wireSidebar`'s compact overlay and its backdrop and above an overlay
|
|
1946
|
+
`ResizableRegion`, so it floated over an open overlay and stayed clickable
|
|
1947
|
+
behind the overlay's focus trap. `--kui-collapsible-panel-restore-z` now
|
|
1948
|
+
defaults to two less than `--kui-collapsible-panel-overlay-z` (38),
|
|
1949
|
+
`--kui-resizable-region-restore-z` to two less than
|
|
1950
|
+
`--kui-resizable-region-overlay-z` (39), and the compact backdrop's
|
|
1951
|
+
`--kui-collapsible-panel-backdrop-z` to one less than the overlay (still
|
|
1952
|
+
39), so an app that moves the overlay z-index keeps the order. When the
|
|
1953
|
+
overlay closes, the control shows and works again.
|
|
1954
|
+
- **An open `@kerfjs/ui` `Workbench` overlay now covers other panels'
|
|
1955
|
+
restore controls.** Restore controls stacked above every overlay, so a
|
|
1956
|
+
collapsed drawer's corner restore control floated over an open right-rail
|
|
1957
|
+
overlay's content. An open overlay is now the top layer, like a sheet over
|
|
1958
|
+
the view beneath it: `--kui-workbench-restore-z` defaults to two less than
|
|
1959
|
+
`--kui-workbench-overlay-z` (39 by default, previously 42), below the
|
|
1960
|
+
drawer and rail overlays. When the overlay closes, the control shows and
|
|
1961
|
+
works again; a collapsed overlay passes pointer events through to it.
|
|
1962
|
+
- **`@kerfjs/ui` `wireWorkbench` overlay panels now take focus and keep Tab
|
|
1963
|
+
inside them,** like `wireSidebar`'s compact overlay (the ARIA dialog
|
|
1964
|
+
pattern). An open overlay covers the work area, yet focus stayed on the
|
|
1965
|
+
control that opened it and Tab walked through the covered editor. A wired
|
|
1966
|
+
panel that opens while it presents as an overlay now focuses its first
|
|
1967
|
+
focusable control (usually the close control in its header); while it is
|
|
1968
|
+
open, Tab and Shift+Tab cycle through its controls, and Escape, its own
|
|
1969
|
+
close control, or an outside press leaves it, returning focus to the
|
|
1970
|
+
opener. Panels opening inline never move focus. Focus returned on close
|
|
1971
|
+
also skips an opener inside another panel that has closed since.
|
|
1972
|
+
`dismissOverlays: false` leaves all of this to the app.
|
|
1973
|
+
- **`@kerfjs/ui` `Workbench` keeps its work-area minimum beside fixed rails
|
|
1974
|
+
and above the bottom drawer.** `mainMinSize` used to apply only beside a
|
|
1975
|
+
resizable rail, so two fixed 280px rails on a ~730px Workbench left the
|
|
1976
|
+
editor 174px; now every inline rail, fixed or resizable, shrinks in
|
|
1977
|
+
proportion (its content following the shown width) to keep the work area
|
|
1978
|
+
`mainMinSize` px wide. A new `mainMinHeight` prop (default 120, `0` turns it
|
|
1979
|
+
off) is the drawer's counterpart: an inline drawer, fixed or resizable,
|
|
1980
|
+
shrinks when the Workbench gets shorter, and `wireWorkbench` stops a
|
|
1981
|
+
resizable drawer where the work area would drop below that height (reported
|
|
1982
|
+
in `aria-valuemax`) instead of only at the drawer's own `max`.
|
|
1983
|
+
- **A `@kerfjs/ui` Workbench rail squeezed below its minimum now reports the
|
|
1984
|
+
width it shows.** When the Workbench was too narrow for a rail's `min`
|
|
1985
|
+
beside the work-area minimum, the rail showed about 172px while its
|
|
1986
|
+
separator still announced `aria-valuenow="180"`. The separator now reports
|
|
1987
|
+
the shown width, with `aria-valuemin` and `aria-valuemax` pinned to it: the
|
|
1988
|
+
WAI-ARIA window splitter's value is the separator's actual position and must
|
|
1989
|
+
sit inside its range, and the separator cannot move a rail the container
|
|
1990
|
+
holds there. Resizing still commits no less than `min`, and the configured
|
|
1991
|
+
range returns once there is room. A `ResizableRegion` a parent clamps below
|
|
1992
|
+
its `min` reports the same way.
|
|
1993
|
+
- **`KUI-L018` (`kerf-ui-analyze` / `kerf-ui-doctor`) now measures contrast and
|
|
1994
|
+
follows the cascade.** When a `--wa-color-{tone}-fill-loud` override and its
|
|
1995
|
+
`on-loud` are both literal colors (including `light-dark()`), a pair below
|
|
1996
|
+
4.5:1 in either color scheme is reported with its ratio, and an unpaired
|
|
1997
|
+
literal fill that still clears 4.5:1 against the theme's default `on-loud`
|
|
1998
|
+
is no longer reported. An `on-loud` set in an ancestor scope (`:root`, or the
|
|
1999
|
+
leading selector of a descendant chain) or in another stylesheet the same
|
|
2000
|
+
entry loads now counts as the pair.
|
|
2001
|
+
- **`kerf-component-catalog` lets a private application declare components
|
|
2002
|
+
without a fake `exports` map.** In a private package
|
|
2003
|
+
(`"private": true`), a component's `publicExports` items may omit `subpath`; the generator
|
|
2004
|
+
verifies each name against the component's `source` file instead of
|
|
2005
|
+
requiring a `./dist/<path>.js` export the bundled app never emits. Publishable
|
|
2006
|
+
packages still need every subpath in `exports`. The v2 catalog schema makes
|
|
2007
|
+
`subpath` optional to match, and the `kerfjs/ui-composition` rule resolves a
|
|
2008
|
+
subpath-less export only by its source file.
|
|
2009
|
+
- **`kerf-ui-doctor` and the `kerfjs/ui-public-boundaries` ESLint rule no
|
|
2010
|
+
longer flag the documented `class="kui-app-root"` as KUI-L101 private
|
|
2011
|
+
anatomy.** The `@kerfjs/ui` component catalog now has a `document-baseline`
|
|
2012
|
+
composition entry for `@kerfjs/ui/document.css` that lists `kui-app-root`
|
|
2013
|
+
as its public class, with a catalog demo route showing a `SplitView` filling
|
|
2014
|
+
the root's definite height.
|
|
2015
|
+
- The `@kerfjs/ui` heading guidance (`ai/skill.md`, `llms.txt`,
|
|
2016
|
+
`docs/component-selection.md`, `docs/layout.md`) now sizes a panel title to
|
|
2017
|
+
its track: extra-large `ToolbarText` stays the title size for a page, view,
|
|
2018
|
+
dialog, or pane that holds it, while a narrow peripheral rail or drawer
|
|
2019
|
+
names itself with the default size, since extra-large truncated "Inspector"
|
|
2020
|
+
to "Ins…" in a 160px Workbench rail.
|
|
2021
|
+
- **A `@kerfjs/ui` `Workbench` panel open when `wireWorkbench` wired up no
|
|
2022
|
+
longer drops focus to the page when it closes from inside.** Such a panel
|
|
2023
|
+
had no recorded opener, so without a restore control closing it from its
|
|
2024
|
+
own header left focus on `<body>`. Focus now falls back to a control
|
|
2025
|
+
outside the panel whose `aria-controls` names it (or an element inside it).
|
|
2026
|
+
Each panel renders a stable `id` for that — `<id>-left-rail`,
|
|
2027
|
+
`<id>-right-rail`, and `<id>-bottom-drawer` — so a toggle can name the
|
|
2028
|
+
panel it controls.
|
|
2029
|
+
- **`@kerfjs/ui` `wireWorkbench` keeps overlay panels exclusive.** At a narrow
|
|
2030
|
+
width two overlay rails could both be open and, together wider than the
|
|
2031
|
+
Workbench, the right rail covered the left rail's own close control. Opening
|
|
2032
|
+
a panel while it presents as an overlay now closes every other open overlay
|
|
2033
|
+
panel, the bottom drawer included, like `wireSidebar`'s compact overlays;
|
|
2034
|
+
panels presenting inline are never closed by it. New option
|
|
2035
|
+
`exclusiveOverlays` (default `true`); pass `false` to let overlays stay open
|
|
2036
|
+
together.
|
|
2037
|
+
- **A `@kerfjs/ui` `CollapsiblePanel` or `ResizableRegion` restore control
|
|
2038
|
+
stays inside its container.** `restoreControl` was `position: fixed` to the
|
|
2039
|
+
viewport, so a panel or region embedded in a page floated it over unrelated
|
|
2040
|
+
page content. It now floats in the `restorePosition` corner of the element
|
|
2041
|
+
that holds the panel (or region), scrolls with it, and is inset by the
|
|
2042
|
+
component's restore inset plus the unsafe area of the edges that container
|
|
2043
|
+
reaches, so a full-viewport shell still places it clear of them. While the
|
|
2044
|
+
control is shown, that container isolates its stacking and becomes its
|
|
2045
|
+
containing block; an app that positions the container itself keeps its own
|
|
2046
|
+
`position`. As in `Workbench`, the corner owns the inset, so a
|
|
2047
|
+
`FloatingToolbar` hosting the control no longer doubles it.
|
|
2048
|
+
- The `@kerfjs/ui` UX catalog's Workbench page gains a responsive overlay
|
|
2049
|
+
drawer example: an output drawer with `responsiveOverlayAt: "narrow"` that
|
|
2050
|
+
takes its own track beside a wide editor and becomes a transient overlay
|
|
2051
|
+
over the editor's bottom once the Workbench is 704px or narrower, starting
|
|
2052
|
+
hidden there and closing from its own header, on Escape, or on a press
|
|
2053
|
+
outside it. The Workbench guide shows the pattern.
|
|
2054
|
+
- A `@kerfjs/ui` `Workbench` now stacks overlay rails above an overlay bottom
|
|
2055
|
+
drawer. With the drawer and a rail both presented as overlays, their order
|
|
2056
|
+
followed the markup, so the drawer covered the left rail while the right
|
|
2057
|
+
rail covered the drawer. Both rails now stack above the drawer, mirroring
|
|
2058
|
+
the inline layout where rails span the full height beside the drawer's
|
|
2059
|
+
column, and the right rail stacks above the left; restore controls stay
|
|
2060
|
+
above every overlay. The drawer's overlay z-index is now one less than
|
|
2061
|
+
`--kui-workbench-overlay-z`.
|
|
2062
|
+
- **A `@kerfjs/ui` `Workbench` overlay rail can always be closed from inside
|
|
2063
|
+
itself.** At a narrow width, the UX catalog's inspector overlay covered the
|
|
2064
|
+
editor toolbar's "Hide inspector" toggle, leaving only Escape or an outside
|
|
2065
|
+
press to close it. The catalog's resizable rails now carry their own close
|
|
2066
|
+
control in their `Pane` header, and the Workbench guide recommends the same
|
|
2067
|
+
for any panel that may present as an overlay. `wireWorkbench` now returns
|
|
2068
|
+
focus stranded in a panel however the panel closed — including through the
|
|
2069
|
+
app's own control inside it, and for inline panels — to the control that
|
|
2070
|
+
opened it, else to its restore control; before, only an Escape, an outside
|
|
2071
|
+
press, or a breakpoint collapse returned it.
|
|
2072
|
+
- **A `@kerfjs/ui` `Workbench` restore control stays inside its Workbench.**
|
|
2073
|
+
`restoreControl` was `position: fixed` to the viewport, so an embedded
|
|
2074
|
+
Workbench (the UX catalog's, for one) floated it over the page footer. It is
|
|
2075
|
+
now anchored to a corner of the Workbench itself — the drawer's in the
|
|
2076
|
+
corner of the work-area column, so it never covers an expanded rail — inset
|
|
2077
|
+
by `--kui-workbench-restore-inset` plus the unsafe area of the edges that
|
|
2078
|
+
corner reaches, and it scrolls with the Workbench. The Workbench now
|
|
2079
|
+
isolates its own stacking, so its overlays and restore controls never stack
|
|
2080
|
+
against the page around it. A `FloatingToolbar` can host the control
|
|
2081
|
+
without doubling the inset: the corner owns it, and `FloatingToolbar` now
|
|
2082
|
+
honors `--kui-floating-toolbar-inset` set on an ancestor as well as on
|
|
2083
|
+
itself. The catalog's collapsed console restores from such a toolbar.
|
|
2084
|
+
- **`@kerfjs/ui` `wireWorkbench` makes overlay panels transient.** A rail
|
|
2085
|
+
whose `responsiveOverlayAt` breakpoint applied stayed expanded over the
|
|
2086
|
+
editor until the user found its toggle. Pass a panel's app-owned
|
|
2087
|
+
`collapsed` signal (`panels: { leftRail: { collapsed } }`; `size` is now
|
|
2088
|
+
optional, so a panel need not be resizable) and, like `wireSidebar`'s
|
|
2089
|
+
compact overlay, the wiring collapses it when the breakpoint begins to
|
|
2090
|
+
apply (without the collapse motion) and gives back its inline state when
|
|
2091
|
+
the breakpoint stops applying or the wiring is disposed. An open overlay
|
|
2092
|
+
panel, responsive or `presentation: "overlay"`, closes on Escape or on a
|
|
2093
|
+
press that starts and ends outside it, and focus stranded inside returns to
|
|
2094
|
+
the control that opened it, else to its restore control. It is on by
|
|
2095
|
+
default for panels given `collapsed`; `dismissOverlays: false` turns it
|
|
2096
|
+
off. The UX catalog's resizable example wires its rails this way.
|
|
2097
|
+
- A `@kerfjs/ui` `Workbench` rail with `presentation: "overlay"` now renders
|
|
2098
|
+
exactly its size. Out of flow, it sized to its content plus its 1px
|
|
2099
|
+
separator border, so a 280px rail measured 281px; it now takes its size
|
|
2100
|
+
explicitly, as the responsive overlays do. Rails and the drawer are also
|
|
2101
|
+
`border-box` now, so a panel's `size` is its whole track, border included,
|
|
2102
|
+
even in an app without a global `box-sizing` reset, and overlay content
|
|
2103
|
+
fills the panel inside its separator instead of painting over it.
|
|
2104
|
+
- **A `@kerfjs/ui` `Workbench` bottom drawer with `presentation: "overlay"`
|
|
2105
|
+
is visible again.** Its content is positioned against the drawer's bottom
|
|
2106
|
+
edge, so the out-of-flow overlay box had no height of its own and collapsed
|
|
2107
|
+
to its 1px border. An overlay drawer now takes its configured height (220px
|
|
2108
|
+
by default, or its `size`), covers the bottom of the work-area column, and
|
|
2109
|
+
clamps its content to the overlay maximum height. The drawer also accepts
|
|
2110
|
+
`responsiveOverlayAt: "narrow" | "compact"` like the rails: below that
|
|
2111
|
+
Workbench width it presents as the same overlay, without a separator and
|
|
2112
|
+
never resizable, while the work area takes the full height and keeps its
|
|
2113
|
+
bottom safe-area inset beneath it.
|
|
2114
|
+
- The bundled AI assistant configs (`ai/skill.md`, `ai/cursorrules`) now
|
|
2115
|
+
explain the `data-kerf-overlay-host` opt-in next to the one-`mount()`-per-root
|
|
2116
|
+
rule: a modal `<dialog>` of your own that anchors kerf popovers or tooltips
|
|
2117
|
+
needs `<div data-kerf-overlay-host data-morph-skip></div>`, the one allowed
|
|
2118
|
+
nested-mount boundary. The `kerfjs/ai-assistant-configs` lint rule reports
|
|
2119
|
+
installed copies as stale until they are refreshed.
|
|
2120
|
+
- The opt-in `rebuiltListeners` dev warning no longer reports a popover or
|
|
2121
|
+
tooltip closing inside a modal dialog's host slot. Removals inside a
|
|
2122
|
+
`[data-kerf-overlay-host][data-morph-skip]` slot belong to the surface's own
|
|
2123
|
+
mount, so the enclosing mount now ignores them, as its re-renders already
|
|
2124
|
+
did. A listener lost to a re-render inside the surface is still reported,
|
|
2125
|
+
once.
|
|
2126
|
+
- **A popover or tooltip in a modal `<dialog>` no longer lingers after the
|
|
2127
|
+
dialog is removed when its anchor was moved out first.** A surface rendered
|
|
2128
|
+
into a dialog's host slot left with the dialog, but because its anchor was
|
|
2129
|
+
still in the document, kerf kept it registered as open, and a tooltip on
|
|
2130
|
+
that anchor never showed again. A slot-hosted surface now closes itself
|
|
2131
|
+
(without calling `onDismiss`) when it leaves the document, and the tooltip
|
|
2132
|
+
shows again on the next hover or focus.
|
|
2133
|
+
- **A popover inside a modal `<dialog>` is reachable by Tab in Safari on
|
|
2134
|
+
macOS.** A popover or tooltip rendered into a dialog's host slot follows the
|
|
2135
|
+
dialog's own Tab order, and WebKit on macOS skips buttons and links there
|
|
2136
|
+
unless the system keyboard-navigation setting is on. kerf now gives each
|
|
2137
|
+
implicitly tabbable control in a slot-hosted surface an explicit
|
|
2138
|
+
`tabindex="0"` when it opens and again before each Tab keypress, the same
|
|
2139
|
+
way its focus trap already did. Authored tabindexes, disabled controls, and
|
|
2140
|
+
surfaces outside a slot are left alone.
|
|
2141
|
+
- `@kerfjs/ui` `Workbench` rails gain `responsiveOverlayAt: "narrow" |
|
|
2142
|
+
"compact"`, mirroring `ResizableRegion`'s `responsiveFillAt`: below the
|
|
2143
|
+
Workbench's own 704px (`narrow`) or 448px (`compact`) width the rail
|
|
2144
|
+
presents as an overlay over the work area, without a separator and never
|
|
2145
|
+
resizable, and inline above it — the CSS decides, so apps no longer derive
|
|
2146
|
+
`presentation` from a `deviceClass()` check. The bottom drawer ignores it.
|
|
2147
|
+
A collapsed overlay rail (with `presentation: "overlay"` too) now drops its
|
|
2148
|
+
surface and shadow instead of leaving an empty panel-sized box over the work
|
|
2149
|
+
area. The UX catalog's resizable example uses it and now renders at phone
|
|
2150
|
+
widths, and its collapsed console's restore control is a `ToolbarControlGroup`
|
|
2151
|
+
toggle that actually restores the console.
|
|
2152
|
+
- `@kerfjs/ui` `Workbench` keeps a minimum work area beside resizable rails.
|
|
2153
|
+
Two rails dragged near their 480px maximum on a ~1024px Workbench used to
|
|
2154
|
+
leave the editor a sliver; now the work area keeps at least `mainMinSize`
|
|
2155
|
+
px (a new `Workbench` prop, default 320, `0` turns it off). `wireWorkbench`
|
|
2156
|
+
stops drag and keyboard resizing where the work area would drop below it
|
|
2157
|
+
(and reports that reachable maximum in `aria-valuemax`), and when the
|
|
2158
|
+
Workbench narrows, resizable rails shrink in proportion to their sizes, with
|
|
2159
|
+
their content following the shown width, instead of squeezing the work
|
|
2160
|
+
area. Workbenches without a resizable rail render exactly as before. The UX
|
|
2161
|
+
catalog's resizable example adds a resizable inspector to show it.
|
|
2162
|
+
- `@kerfjs/ui`'s static analyzer (`kerf-ui-analyze`, and the analyzer stage of
|
|
2163
|
+
`kerf-ui-doctor`) reports a new review finding, `KUI-L018`, when a
|
|
2164
|
+
stylesheet overrides a loud tone fill (`--wa-color-{tone}-fill-loud` for
|
|
2165
|
+
neutral, brand, success, warning, danger, or pop) without setting the
|
|
2166
|
+
matching `--wa-color-{tone}-on-loud` in the same scope. The theme pairs each
|
|
2167
|
+
loud fill with a foreground that clears WCAG AA, and an unpaired override
|
|
2168
|
+
keeps that foreground on a fill it was never checked against. The pair must
|
|
2169
|
+
share a selector (after resolving nesting and splitting selector lists) and
|
|
2170
|
+
at-rule scope in the same stylesheet, in one rule or separate ones; another
|
|
2171
|
+
tone's `on-loud` does not count. It is a review finding because it checks
|
|
2172
|
+
the pairing, not the contrast; pass `--fail-on-review` to gate it. The
|
|
2173
|
+
`webawesome-theme.md` customization example now sets both halves of each
|
|
2174
|
+
pair.
|
|
2175
|
+
- **Tooltips and popovers also stay visible when your own code opens a modal
|
|
2176
|
+
`<dialog>`.** `kerfjs/overlay` already moved every open tooltip and popover
|
|
2177
|
+
above a modal dialog it opened itself, but a dialog opened with a bare
|
|
2178
|
+
`dialog.showModal()` went unnoticed and left them inert beneath it. While
|
|
2179
|
+
any kerf surface is open, one capture-phase listener on the document now
|
|
2180
|
+
catches the dialog's `toggle` event and re-hosts them the same way, one task
|
|
2181
|
+
after the `showModal()` call. The listener is removed once nothing is open.
|
|
2182
|
+
An engine that fires no `toggle` event for `<dialog>` still misses such a
|
|
2183
|
+
dialog; open it through `overlay()` there.
|
|
2184
|
+
- **A popover inside a modal `<dialog>` is clickable.** Browsers make
|
|
2185
|
+
everything outside an open modal dialog inert, so a popover lifted above the
|
|
2186
|
+
dialog was visible but its buttons could not be clicked or focused, and
|
|
2187
|
+
kerf's one-mount-per-tree rule kept it from rendering inside a kerf-mounted
|
|
2188
|
+
dialog. `popover()` and `tooltip()` whose anchor sits inside an open modal
|
|
2189
|
+
`<dialog>` now render into the dialog's host slot, an element marked
|
|
2190
|
+
`data-kerf-overlay-host data-morph-skip`, so they are part of the modal and
|
|
2191
|
+
fully interactive: Tab reaches them, and Escape closes the popover before the
|
|
2192
|
+
dialog. A dialog `kerfjs/overlay` opened gets the slot automatically (an
|
|
2193
|
+
empty `display: contents` element added on first use). For your own
|
|
2194
|
+
`<dialog>`, add `<div data-kerf-overlay-host data-morph-skip></div>` to its
|
|
2195
|
+
markup, or pass `container`. The slot is the one place a second `mount()`
|
|
2196
|
+
may live inside a mounted tree: the enclosing mount's morph, nesting guard,
|
|
2197
|
+
and binding and `each()` marker scans all stop there. The `kerfjs/dev`
|
|
2198
|
+
`inert` warning now fires only when no slot was used.
|
|
2199
|
+
- `@kerfjs/ui` `Workbench` rails and the bottom drawer can be drag-resized,
|
|
2200
|
+
as an opt-in per panel. `WorkbenchPanel` gains `resizable: true | { min, max }`
|
|
2201
|
+
(off by default, so existing Workbenches render unchanged); a resizable panel
|
|
2202
|
+
gets a separator on its inner edge with the same focusable
|
|
2203
|
+
`role="separator"` contract, grip, and 20px hit target as a
|
|
2204
|
+
`ResizableRegion` handle. The new `@kerfjs/ui/wire-workbench` subpath's
|
|
2205
|
+
`wireWorkbench(root, { id, panels, deviceClass?, storage?, onResize? })`
|
|
2206
|
+
drives it: live pointer drags, arrow / Shift+arrow / Home / End keys,
|
|
2207
|
+
clamping to the limits, and commits to the app-owned size signals, with
|
|
2208
|
+
optional `storageKey` persistence. Collapsing keeps a panel's size, so it
|
|
2209
|
+
expands back to the size it had, and resizing is suspended on compact device
|
|
2210
|
+
classes and for overlay or hidden panels. The UX catalog's Workbench page
|
|
2211
|
+
adds a resizable example. `wireResizableRegions` now drives only handles that
|
|
2212
|
+
are direct children of a `ResizableRegion`, so it never double-drives a
|
|
2213
|
+
Workbench separator under the same root.
|
|
2214
|
+
- `@kerfjs/ui` elevation shadows follow the color scheme, with or without the
|
|
2215
|
+
optional `@kerfjs/ui/webawesome.css` theme. Kerf's theme layer set
|
|
2216
|
+
`--wa-shadow-s` / `-m` / `-l` to fixed light-mode shadows (14%, 11%, and 9%
|
|
2217
|
+
black), which all but vanished against the dark page, and the
|
|
2218
|
+
`--kui-shadow-s` / `--kui-shadow-l` foundation fallbacks copied those fixed
|
|
2219
|
+
values. The theme now pairs each light alpha with a stronger dark one (50%,
|
|
2220
|
+
40%, 32%) through `light-dark()`, and the foundation fallbacks mirror them, so
|
|
2221
|
+
selected segments and app tabs, compact overlay panels, and Web Awesome
|
|
2222
|
+
surfaces that read `--wa-shadow-*` keep their elevation in dark mode. Light mode is unchanged. The browser parity test
|
|
2223
|
+
now compares every `--kui-shadow-*` token with and without the theme in both
|
|
2224
|
+
schemes.
|
|
2225
|
+
- `@kerfjs/ui` text on loud tone fills clears WCAG AA in both color schemes,
|
|
2226
|
+
with or without the optional `@kerfjs/ui/webawesome.css` theme. White
|
|
2227
|
+
`on-loud` text reached about 2.2:1 on the success fill, 3.5:1 on the light
|
|
2228
|
+
brand fill (`#0088ff`), and 3.6:1 on the danger fill (`#ff383c`) in both
|
|
2229
|
+
schemes. Kerf's theme layer and the foundation fallbacks now pair each
|
|
2230
|
+
fill with a foreground chosen to keep the tone's look: success keeps its
|
|
2231
|
+
bright green with dark text (`#1d1d1f`, 7.6:1), as warning already did; light
|
|
2232
|
+
brand and danger keep white text on a slightly deeper fill of the same hue
|
|
2233
|
+
(`#0075db`, 4.6:1; `#eb0005`, 4.6:1); dark danger keeps its fill with dark
|
|
2234
|
+
text (`#111113`, 5.3:1), as dark brand already did. Web Awesome accent
|
|
2235
|
+
buttons, badges, and checked controls pick this up, and accent `wa-badge`s now
|
|
2236
|
+
use their variant's `on-loud` foreground by default instead of a fixed dark
|
|
2237
|
+
color (`--kui-wa-badge-accent-foreground` still overrides it). The browser
|
|
2238
|
+
contrast test asserts every tone's `on-loud` over `fill-loud` pair, including
|
|
2239
|
+
pop and neutral, in both schemes with and without the theme.
|
|
2240
|
+
- `@kerfjs/ui` brand, success, and warning text clears WCAG AA on the lowered
|
|
2241
|
+
page background in light mode, with or without the optional
|
|
2242
|
+
`@kerfjs/ui/webawesome.css` theme. Their light `on-quiet` values (`#1e6ef4`,
|
|
2243
|
+
`#008932`, `#a16a00`) passed on the white surface but reached only about
|
|
2244
|
+
4.1:1 on `#f2f2f7`. Kerf's theme layer and the foundation fallbacks now use
|
|
2245
|
+
the same hues a step darker: `#0c62f3` (4.64:1), `#007f2e` (4.62:1), and
|
|
2246
|
+
`#966200` (4.65:1) on the page, about 5.2:1 on white. Links, selected tabs,
|
|
2247
|
+
segmented and toolbar selections, and token-search accents that read
|
|
2248
|
+
`brand-on-quiet` darken with it. Dark mode is unchanged. The browser contrast
|
|
2249
|
+
test no longer skips light text over the page background.
|
|
2250
|
+
- `@kerfjs/ui` surfaces, links, and focus rings match the optional
|
|
2251
|
+
`@kerfjs/ui/webawesome.css` theme without it. Three foundation fallbacks
|
|
2252
|
+
pointed at a different token than the theme: `--kui-color-surface-raised`
|
|
2253
|
+
fell back to the surface color (the theme's dark raised surface is
|
|
2254
|
+
`#2c2c2e`), `--kui-color-text-link` fell back to the brand fill (`#0088ff`,
|
|
2255
|
+
about 3.5:1 on white) instead of the brand on-quiet text color, and the focus
|
|
2256
|
+
ring used the brand fill instead of the theme's focus color (`#007aff`). Each
|
|
2257
|
+
now falls back to the theme's value. The browser parity test now covers every
|
|
2258
|
+
`--kui-color-*` token the foundation declares, plus the focus ring, instead of
|
|
2259
|
+
only the tone tokens.
|
|
2260
|
+
- The `@kerfjs/ui` UX catalog's `StateBanner` route adds a placeholder with a
|
|
2261
|
+
badge for every tone, next to the existing badge-less placeholder, so visual
|
|
2262
|
+
review and captures show the solid badge's loading skeleton on each tone's
|
|
2263
|
+
fill. A browser test checks that each tone's badged placeholder is present.
|
|
2264
|
+
- `@kerfjs/ui` toned text stays readable in dark mode without the optional
|
|
2265
|
+
`@kerfjs/ui/webawesome.css` theme. The foundation's fallbacks for the
|
|
2266
|
+
success, warning, and danger `on-quiet` and `on-normal` tokens were single
|
|
2267
|
+
light-mode colors, so dark danger `Text` rendered dark red on a dark surface
|
|
2268
|
+
(under 3:1). Every tone token now falls back to the same light and dark
|
|
2269
|
+
pair the theme assigns, including `brand-on-loud` (dark text on the pale dark
|
|
2270
|
+
brand fill instead of white) and `neutral-border-quiet`. Light-mode colors
|
|
2271
|
+
are unchanged. A browser test bundles the package with and without the theme
|
|
2272
|
+
and asserts that every tone token resolves identically in both color schemes
|
|
2273
|
+
and that toned text clears WCAG AA in dark mode.
|
|
2274
|
+
- `@kerfjs/ui` danger text and badges are readable in dark mode, and every
|
|
2275
|
+
tone's `StateBanner` detail and quiet or outline `Badge` text now clears
|
|
2276
|
+
WCAG AA. The danger tone was the only one without an on-fill foreground: its
|
|
2277
|
+
solid badge fill and `StateBanner` text reused `danger-on-quiet`, a mid red
|
|
2278
|
+
in dark mode (banner detail 4.0:1, badge placeholder skeleton 2.25:1). A new
|
|
2279
|
+
`--kui-color-danger-on-fill` token (also accepted by `uiColor()`) matches the
|
|
2280
|
+
other tones' pale dark values, lifting the dark danger banner text to 8.2:1.
|
|
2281
|
+
The banner detail no longer dims to 78% opacity, which left the light info,
|
|
2282
|
+
success, warning, and danger details at 3.4 to 4.3:1; it reads as secondary
|
|
2283
|
+
through its smaller type, and the neutral detail uses the quiet text color.
|
|
2284
|
+
Quiet and outline badges use their tone's on-fill text, lifting light brand,
|
|
2285
|
+
success, and warning from about 4.1:1 to at least 5:1.
|
|
2286
|
+
|
|
2287
|
+
- A `@kerfjs/ui` placeholder skeleton inside a solid `Badge`, such as the
|
|
2288
|
+
badge of a `StateBanner` placeholder, is now clearly visible. The generic
|
|
2289
|
+
skeleton tint, 12% of the text color, almost disappeared on the badge's
|
|
2290
|
+
saturated fill in every tone. A solid badge now tints its skeleton from its
|
|
2291
|
+
own foreground color, which contrasts with the fill in every tone in light
|
|
2292
|
+
and dark mode. Quiet and outline badges keep the generic tint, which already
|
|
2293
|
+
reads on their pale fills. Geometry is unchanged.
|
|
2294
|
+
- The `@kerfjs/ui` SVG design templates render badges as filled pills: the
|
|
2295
|
+
`StateBanner` badge and the `ListHeader` and `List` count pills used to show
|
|
2296
|
+
as plain text, because the template build loaded only a hand-written list of
|
|
2297
|
+
stylesheets that omitted `badge.css`. The build now loads each component's
|
|
2298
|
+
full stylesheet set from its generated browser entry, the same set a
|
|
2299
|
+
consumer's browser import loads, so a nested component's CSS can no longer be
|
|
2300
|
+
missed. The `ListHeader` and `List` templates also pick up the label inset
|
|
2301
|
+
from `text.css`, so a header label now lines up with the list items below it,
|
|
2302
|
+
as it does in the live component.
|
|
2303
|
+
- A `@kerfjs/ui` `StateBanner` placeholder's badge sits at the live badge's
|
|
2304
|
+
height on every platform. With a skeleton instead of text, the badge took a
|
|
2305
|
+
baseline from the skeleton's bottom edge and sat about a pixel higher, by an
|
|
2306
|
+
amount that depended on the platform's font metrics.
|
|
2307
|
+
- A `@kerfjs/ui` `StateBanner` with a long, wrapping title keeps its badge
|
|
2308
|
+
one item gap after the title's last word, and its detail uses the full copy
|
|
2309
|
+
width. The wide flex layout shrank the title and detail together, which left
|
|
2310
|
+
a large gap before the badge and truncated the detail early. The title,
|
|
2311
|
+
badge, and detail now flow as inline text: the detail stays beside the title
|
|
2312
|
+
while it fits whole, and otherwise moves to its own line, truncating only at
|
|
2313
|
+
the full width. A wrapped title's lines stay evenly spaced.
|
|
2314
|
+
- A `@kerfjs/ui` `ListHeader` disclosure toggle disabled with `actionDisabled`
|
|
2315
|
+
is dimmed by the component itself, at the same tone as a disabled action
|
|
2316
|
+
button, and shows the `not-allowed` cursor. It used to rely on Web Awesome's
|
|
2317
|
+
native `button:disabled` dimming, so without `webawesome.css` it looked
|
|
2318
|
+
enabled. Disabled toggles and action buttons also no longer show hover
|
|
2319
|
+
feedback without `webawesome.css`.
|
|
2320
|
+
- A `@kerfjs/ui` `ListActionRow` placeholder keeps its `busy` spinner. The
|
|
2321
|
+
whole status line used to collapse into one skeleton, dropping the spinner
|
|
2322
|
+
the component draws from a known prop. Now only the `status` text becomes a
|
|
2323
|
+
skeleton, matching `ListItem`.
|
|
2324
|
+
- **A tooltip or popover already showing stays visible when a modal opens.**
|
|
2325
|
+
Lifting a surface above an open modal `<dialog>` was decided only when the
|
|
2326
|
+
surface opened, so a tooltip or popover already on screen when a modal
|
|
2327
|
+
dialog opened was left inert beneath it. Whenever `kerfjs/overlay` opens a
|
|
2328
|
+
modal `<dialog>` (a `native: true` modal, or one it lifted), it now moves
|
|
2329
|
+
every open tooltip and popover into the top layer above the new dialog. One
|
|
2330
|
+
that is already a `[popover]` is re-shown so it stacks on top. The existing
|
|
2331
|
+
`kerfjs/dev` warnings still report an engine without the Popover API, and a
|
|
2332
|
+
surface with controls the modal keeps inert. A modal `<dialog>` the app
|
|
2333
|
+
opens itself, outside kerf, is not observed.
|
|
2334
|
+
- Moved `mount()`'s list-binding lifecycle (turning list markers into
|
|
2335
|
+
bindings, first-render row-contract validation, orphan pruning) into its own
|
|
2336
|
+
internal module, so `mount.ts` holds only the render orchestration. No
|
|
2337
|
+
behavior or public API change.
|
|
2338
|
+
- A narrow (576px and below) `@kerfjs/ui` `StateBanner` keeps its badge
|
|
2339
|
+
sized to its content, one item gap after the title and on the title's
|
|
2340
|
+
baseline, as in the wide layout. The narrow grid stretched the badge across
|
|
2341
|
+
the free column into a wide pill that sat less than 1px from the title.
|
|
2342
|
+
- Hovering a `@kerfjs/ui` `ListActionRow` placeholder with
|
|
2343
|
+
`trailingActionVisibility="interaction"` no longer reveals its disabled
|
|
2344
|
+
trailing button. A placeholder is inert, so it keeps the live row's resting
|
|
2345
|
+
state, with the trailing action hidden until an interaction it cannot take.
|
|
2346
|
+
- A `@kerfjs/ui` `ListItem` placeholder keeps its `busy` spinner. The whole
|
|
2347
|
+
trailing slot used to collapse into one skeleton, dropping the spinner the
|
|
2348
|
+
component draws from a known prop and shifting the label's width. Now only
|
|
2349
|
+
the values in that slot become skeletons: `status` text in its status line
|
|
2350
|
+
and author-supplied `trailing` content (always a value, since the component
|
|
2351
|
+
cannot tell a chevron from a count) each get their own.
|
|
2352
|
+
- `@kerfjs/ui` placeholders keep the live disabled tone of a control the
|
|
2353
|
+
author disabled. A disabled `ListItem` or `ListActionRow`, a
|
|
2354
|
+
`trailingActionDisabled` button, a disabled `SegmentedControl` choice, or a
|
|
2355
|
+
`ListHeader` with `actionDisabled` rendered at full opacity as a
|
|
2356
|
+
placeholder, because the placeholder reset could not tell its own
|
|
2357
|
+
`disabled` attribute from the author's. Those controls now carry a
|
|
2358
|
+
component-owned `data-kui-disabled="true"` marker whenever their disabled
|
|
2359
|
+
prop is set; the disabled tone keys on it and the placeholder reset skips
|
|
2360
|
+
it. The marker is reserved: the extension-attribute props cannot set it.
|
|
2361
|
+
- `@kerfjs/ui` adds a browser test that renders every placeholder-capable
|
|
2362
|
+
component live and as a placeholder from identical props and diffs each
|
|
2363
|
+
element's geometry and computed chrome, so any future drift outside a value
|
|
2364
|
+
slot fails. It caught one more: a `ListActionRow` placeholder's `status`
|
|
2365
|
+
line was 3.5px shorter than the live line; the status line now always
|
|
2366
|
+
keeps a full line height.
|
|
2367
|
+
- `@kerfjs/ui`'s `Select` placeholder hint now matches the live hint: 14px
|
|
2368
|
+
text at a 1.6 line height, 7px below the box. It was 12px / 1.4 with a 4px
|
|
2369
|
+
gap, so a placeholder with a `hint` was 8.6px shorter than the loaded
|
|
2370
|
+
control and the content below it jumped when loading finished.
|
|
2371
|
+
- `@kerfjs/ui`'s `StateBanner` placeholder adds a detail skeleton only when
|
|
2372
|
+
`detail` is set, matching the live banner. Previously every placeholder
|
|
2373
|
+
showed a detail line, so a banner without one changed shape when loading
|
|
2374
|
+
finished. Pass the banner's real `title` and `detail` with `placeholder`;
|
|
2375
|
+
an empty `detail` now means no detail line.
|
|
2376
|
+
- `@kerfjs/ui`'s `AppTab` placeholder pill is no longer dimmed to 50% with a
|
|
2377
|
+
`not-allowed` cursor when `webawesome.css` is loaded; it keeps the live
|
|
2378
|
+
tab's tone, and only its name is a skeleton.
|
|
2379
|
+
- `@kerfjs/ui`'s `ListHeader` placeholder no longer dims its action button
|
|
2380
|
+
(48%) or, in `toggle` mode, the whole title and label (Web Awesome's native
|
|
2381
|
+
50%), and its inert action and toggle give no hover feedback. A live
|
|
2382
|
+
`actionDisabled` header still dims its action.
|
|
2383
|
+
- `@kerfjs/ui`'s `SegmentedControl` placeholder now keeps its choices. The
|
|
2384
|
+
choices are known; only the selection is unknown, so a placeholder renders
|
|
2385
|
+
every choice's live label or icon at its live size, selects none, and stays
|
|
2386
|
+
inert. Previously every segment became a 4em text skeleton (widening icon
|
|
2387
|
+
segments from 40px to 60px) and was dimmed to 45%.
|
|
2388
|
+
- `@kerfjs/ui`'s `ListItem` and `ListActionRow` placeholders now match the
|
|
2389
|
+
live row. They are no longer dimmed (the rows' own `:disabled` tone and
|
|
2390
|
+
hover highlight skip placeholders), and a row with a `description` (or a
|
|
2391
|
+
`ListActionRow` `status`) keeps that line as a second, smaller skeleton, so
|
|
2392
|
+
the row keeps its live height instead of collapsing to one line. The
|
|
2393
|
+
`ListActionRow` icon placeholder is an 18px block centered in its icon slot,
|
|
2394
|
+
like `ListItem`'s.
|
|
2395
|
+
- `@kerfjs/ui` placeholders no longer look disabled. A component's
|
|
2396
|
+
`placeholder` keeps its controls `disabled` (inert and out of the keyboard
|
|
2397
|
+
order), but `skeleton.css` now neutralizes generic disabled chrome under
|
|
2398
|
+
`[data-placeholder="true"]`: full opacity and the default cursor instead of
|
|
2399
|
+
Web Awesome's native `button:disabled` dimming to 50% with a `not-allowed`
|
|
2400
|
+
cursor. A component's own opacity (a control hidden until interaction) still
|
|
2401
|
+
applies.
|
|
2402
|
+
- `toElement('<image href="…" />')` now returns an SVG `<image>`. The HTML
|
|
2403
|
+
parser rewrites an orphan `<image>` to an HTML `<img>` before kerf sees the
|
|
2404
|
+
tag, so it previously came back as an XHTML `img` that no `<svg>` would
|
|
2405
|
+
render. kerf now recognizes a leading `<image` tag in the raw input
|
|
2406
|
+
(case-insensitive, after leading whitespace) and parses it through the SVG
|
|
2407
|
+
wrapper. A genuine `<img>` is unchanged.
|
|
2408
|
+
- `delegateActions()` (`kerfjs/actions`) dispatches only the table's own
|
|
2409
|
+
entries. It used to look the action up with a plain property read, so a
|
|
2410
|
+
`data-action` naming an inherited `Object.prototype` member resolved:
|
|
2411
|
+
`"__proto__"` or `"hasOwnProperty"` threw a `TypeError` from the listener,
|
|
2412
|
+
and `"toString"` or `"constructor"` silently ran the inherited function.
|
|
2413
|
+
Those values are now ignored like any other action absent from the table.
|
|
2414
|
+
An own entry with such a name (`{ toString: … }`) still dispatches.
|
|
2415
|
+
- `toElement()` now puts orphan camelCase SVG fragments in the SVG namespace.
|
|
2416
|
+
`toElement('<linearGradient>…</linearGradient>')`, and likewise `clipPath`,
|
|
2417
|
+
`radialGradient`, and `foreignObject`, previously returned an XHTML
|
|
2418
|
+
`LINEARGRADIENT` element that no `<svg>` would render, because the lookup
|
|
2419
|
+
compared the HTML parser's lowercased tag against camelCase names. The
|
|
2420
|
+
fragment is now wrapped in `<svg>` and XML-parsed like `<path>` or `<g>`,
|
|
2421
|
+
and the returned element keeps its camelCase `localName`.
|
|
2422
|
+
- **A tooltip or popover no longer outlives its anchor.** When the anchor left
|
|
2423
|
+
the document, most commonly because the modal containing it closed, the
|
|
2424
|
+
`tooltip()` or `popover()` stayed on screen: a removed element fires no
|
|
2425
|
+
`pointerleave` or `blur`. Both now watch their anchor with the same removal
|
|
2426
|
+
tracking as `kerfjs/attach`. The tooltip hides, and the popover closes
|
|
2427
|
+
without calling `onDismiss`, as soon as the anchor leaves the document.
|
|
2428
|
+
Moving the anchor within the document keeps them open. A tooltip show still
|
|
2429
|
+
pending when its anchor is removed never appears.
|
|
2430
|
+
- **Overlays opened over a modal `<dialog>` are visible and usable.** A browser
|
|
2431
|
+
makes everything outside an open modal dialog inert and paints a plain
|
|
2432
|
+
element beneath it, so a `tooltip()`, `popover()`, or `confirm()` opened
|
|
2433
|
+
from inside a `native: true` dialog without `native` itself was invisible and
|
|
2434
|
+
could not be used. While a modal `<dialog>` is open, `kerfjs/overlay` now
|
|
2435
|
+
hosts such a surface in the top layer anyway: a tooltip or popover becomes a
|
|
2436
|
+
`[popover]`, and a nested modal becomes its own `<dialog>`. The browser's
|
|
2437
|
+
default `[popover]` / `<dialog>` styles then apply, as they do with `native:
|
|
2438
|
+
true`. Browsers keep a popover outside the modal dialog inert even in the top
|
|
2439
|
+
layer, so a lifted popover with buttons is visible but not clickable. A new
|
|
2440
|
+
always-on `kerfjs/dev` warning reports that case, and an engine without the
|
|
2441
|
+
needed API.
|
|
2442
|
+
- **A tooltip shown inside a modal no longer disables the modal.** `kerfjs/overlay`
|
|
2443
|
+
used to treat the most recently opened overlay as the only one that could
|
|
2444
|
+
react to input, so a `tooltip()` (which handles no input) inside an open
|
|
2445
|
+
modal left Escape doing nothing and let Tab leave the dialog. Every overlay,
|
|
2446
|
+
native or fallback, now joins one open-order stack, and each Escape, backdrop
|
|
2447
|
+
click, outside click, or trapped Tab goes to the topmost surface that handles
|
|
2448
|
+
it. A modal still blocks everything beneath it, and a surface that handles
|
|
2449
|
+
nothing never intercepts. A popover that dismisses on Escape gets it before
|
|
2450
|
+
the modal beneath. One click that is both outside a popover and on a modal's
|
|
2451
|
+
backdrop now closes only the popover. A native `<dialog>` is arbitrated with
|
|
2452
|
+
the fallback surfaces: one Escape closes one surface, and a fallback modal
|
|
2453
|
+
beneath an open dialog no longer takes the dialog's Tab. Closing a lower
|
|
2454
|
+
overlay first leaves focus in the overlay that holds it. An overlay opened
|
|
2455
|
+
from inside it then restores focus to the closed overlay's opener, not a
|
|
2456
|
+
detached node.
|
|
2457
|
+
- `kerfjs` now exports the `EachOptions<T>` type (`{ cacheKey?, key? }`), the
|
|
2458
|
+
options-object form of `each()`'s third argument, so a helper that builds or
|
|
2459
|
+
forwards those options can import the shape instead of restating it:
|
|
2460
|
+
`import { type EachOptions } from "kerfjs"`. Type-only; no runtime or bundle
|
|
2461
|
+
change.
|
|
2462
|
+
- Documentation: the companion-utility reference now matches the code. The
|
|
2463
|
+
router's `match()` / `activeClass()` compare a literal path prefix, so
|
|
2464
|
+
`match('/users/:id')` is never true. Link interception still applies to
|
|
2465
|
+
`target="_self"`, the no-match `outlet()` is `null` with `params` `{}`,
|
|
2466
|
+
components receive `(params, route)`, and hash mode keeps `route.hash` at
|
|
2467
|
+
`''`. Invalid `bindList` configuration throws only `RangeError`. `popover()`
|
|
2468
|
+
defaults `className` to `'kerf-popover'`, and the toast region is a reused
|
|
2469
|
+
`.kerf-toasts` element when one exists. A `resource()` `cacheKey` applies
|
|
2470
|
+
only to `run(input, fetcher)`, and throttle's `flush()` leaves the cooldown
|
|
2471
|
+
running. `delegate()` / `delegateCapture()` throw on an invalid selector at
|
|
2472
|
+
registration. The reference also now lists the `kerfjs/jsx-dev-runtime`
|
|
2473
|
+
alias, the `DEV_HOOKS` export of `kerfjs/dev`, and `Signal#peek()`.
|
|
2474
|
+
- Documentation: `morph(liveRoot, template)` is now described as it behaves.
|
|
2475
|
+
It reconciles only the root's children and never touches the root's own
|
|
2476
|
+
attributes, so `template` describes the content inside the root (an
|
|
2477
|
+
`Element` template contributes its child nodes). The examples no longer
|
|
2478
|
+
nest a duplicate `<article>` inside the live one. An `each()` list parent is
|
|
2479
|
+
not a children-only short-circuit: the diff still walks it and skips only
|
|
2480
|
+
the owned rows. The user-agent-owned `open` exception covers custom elements
|
|
2481
|
+
as well as `<details>` / `<dialog>`, and a content-only row change inside an
|
|
2482
|
+
`each()` list keeps its DOM node (and focus) unless the row's top-level tag
|
|
2483
|
+
changes or the same render also inserts, removes, or moves rows.
|
|
2484
|
+
- Every opt-in `kerfjs/dev` warning now ends with a silence hint that leads
|
|
2485
|
+
with the browser-reachable switch, for example "Silence it with
|
|
2486
|
+
enableWarnings({ narrowSet: false }) from kerfjs/dev, or set
|
|
2487
|
+
KERF_DEV_WARN_NARROW_SET=0 (or unset it) under Node." Previously the
|
|
2488
|
+
messages named only the environment variable, which a browser cannot reach.
|
|
2489
|
+
The docs now teach `enableWarnings()` wherever they showed an env-only
|
|
2490
|
+
switch, and name all three creation-time boundaries: `signal()`
|
|
2491
|
+
(`untrackedSignals`), `effect()` (`delegateInEffect`), and `mount()`
|
|
2492
|
+
(`rebuiltListeners`) decide once when created, so anything created before
|
|
2493
|
+
the install or the opt-in stays uncovered.
|
|
2494
|
+
- The `kerfjs/dev` rebuilt-listeners warning (`rebuiltListeners` /
|
|
2495
|
+
`KERF_DEV_WARN_REBUILT_LISTENERS`) now dedups once per `mount()`, as
|
|
2496
|
+
documented. Previously the first warning silenced every other mount for
|
|
2497
|
+
the life of the process, so a second mount with the same bug stayed quiet.
|
|
2498
|
+
- `kerfjs/router`: a second router on the same document no longer diverges
|
|
2499
|
+
from the URL after a link click. The first router's interceptor navigates
|
|
2500
|
+
with `pushState`, which fires no `popstate`, so the second router ignored
|
|
2501
|
+
the already-handled click and kept the old route. An already-handled click
|
|
2502
|
+
now re-syncs the route from the URL; when nothing navigated, it is a no-op.
|
|
2503
|
+
One router per document remains the supported shape: a second router does
|
|
2504
|
+
not follow another router's programmatic `navigate()` (no `popstate` fires
|
|
2505
|
+
and routers do not broadcast to each other) until the next `popstate` or
|
|
2506
|
+
link click. This is now documented and pinned by a test.
|
|
2507
|
+
- `kerfjs/scope`: a disposed `Scope` handle no longer leaks registrations.
|
|
2508
|
+
Previously `add` / `mount` / `effect` / `delegate` on a handle after its
|
|
2509
|
+
`dispose()` (or from a disposer while `dispose()` ran) pushed into a list
|
|
2510
|
+
nothing would ever run, leaving the effect subscribed or the listener
|
|
2511
|
+
attached. Such a registration now tears down at once: `add(fn)` calls `fn`
|
|
2512
|
+
immediately, and the wrappers create and immediately dispose.
|
|
2513
|
+
- `bindList` measured-height virtualization no longer applies a stale
|
|
2514
|
+
scroll-anchor correction. A `setHeight()` report for a row above the viewport
|
|
2515
|
+
is now resolved when the animation frame runs: if the source removed the key,
|
|
2516
|
+
moved it below the fold, or the user scrolled the row into view first,
|
|
2517
|
+
`scrollTop` is left alone, and several reports for one key in a frame net
|
|
2518
|
+
out. Fixed-height windows also clamp to the source length, so a list that
|
|
2519
|
+
shrinks while scrolled deep no longer pads far past its content.
|
|
2520
|
+
- `create-kerf-component` accepts an explicit `boundaries.rootClass: null` as
|
|
2521
|
+
an author decision, as its schema always allowed. A wrapper whose root
|
|
2522
|
+
element belongs to another catalog (a `rendersAs` wrapper) no longer has to
|
|
2523
|
+
invent a class to satisfy the generator. An absent `rootClass` still fails
|
|
2524
|
+
as undecided.
|
|
2525
|
+
- `@kerfjs/ui`'s `Select` placeholder now matches the live control. The label
|
|
2526
|
+
uses the field-label style (uppercase, extra-small, quiet, inset to line up
|
|
2527
|
+
with the value), and the chevron is the same glyph at the same size.
|
|
2528
|
+
Previously the placeholder drew a larger, regular-weight label at a
|
|
2529
|
+
different inset and a different, smaller chevron. Only the value is a
|
|
2530
|
+
skeleton; the chrome no longer changes when loading finishes.
|
|
2531
|
+
- **Wrapper components can declare the cataloged root they render.** A
|
|
2532
|
+
`kerf.components.json` component may set `composition.rendersAs`, for
|
|
2533
|
+
example `["@kerfjs/ui:toolbar-control-group"]`: a list of the roots it
|
|
2534
|
+
renders, any one of them, or nothing. `kerf-component-catalog` copies it
|
|
2535
|
+
into the generated v2 entry and fails unless every key resolves to a
|
|
2536
|
+
cataloged entry. `eslint-plugin-kerfjs`'s `ui-composition` rule, and so
|
|
2537
|
+
`kerf-ui-doctor`, now loads the application and third-party catalogs a
|
|
2538
|
+
`.kerf-ui-profile.json` declares. It resolves their components by package
|
|
2539
|
+
subpath or source file and checks a wrapper as each declared root: a zone
|
|
2540
|
+
must accept every root, each root's parent contract applies where the
|
|
2541
|
+
wrapper is placed, and a wrapper counts as zero or one child. Undeclared
|
|
2542
|
+
wrappers keep reporting `KUI-L202`.
|
|
2543
|
+
- `@kerfjs/ui`'s `AppTab` adds `pending` for a known tab that is still
|
|
2544
|
+
opening. It keeps the name visible in the quiet text color and uses it as
|
|
2545
|
+
the tab's accessible name, so a trailing spinner's label is not folded in.
|
|
2546
|
+
Like `placeholder`, it disables select and close, turns off dragging, and
|
|
2547
|
+
sets `aria-busy`, and it shows the consumer's `trailing` spinner. It keeps
|
|
2548
|
+
the live tab's pill geometry, so it swaps in place without shifting the bar.
|
|
2549
|
+
Dormant tabs (placeholder or pending) no longer reveal their disabled close
|
|
2550
|
+
button on hover.
|
|
2551
|
+
- `@kerfjs/ui`'s `wireSidebar` moves focus into an opening panel without
|
|
2552
|
+
scrolling it. A plain `focus()` scrolled the panel's clipped content to the
|
|
2553
|
+
target while it was still sliding in, then the slide unwound that scroll:
|
|
2554
|
+
a bottom drawer's content jumped up past its top and drifted back. The
|
|
2555
|
+
collapsible-sidebar recipe also floats the drawer's expand toggle in a
|
|
2556
|
+
`FloatingToolbar` at the bottom edge the drawer opens from, and drops the
|
|
2557
|
+
divider under the drawer's toolbar.
|
|
2558
|
+
- `@kerfjs/ui`'s `Skeleton` takes `block` (default `false`). It lays the
|
|
2559
|
+
placeholder out as `display: block` instead of `inline-block`, for a
|
|
2560
|
+
skeleton that stands in for a box rather than text: no text line and no
|
|
2561
|
+
baseline gap of its own. `ListItem`'s placeholder icon uses it.
|
|
2562
|
+
- `@kerfjs/ui/css-values` adds `remify(px)`, the runtime twin of source
|
|
2563
|
+
CSS's `remify(<px>)`. It turns a pixel count into a rem `CssLength` against
|
|
2564
|
+
the fixed 16px baseline, so `remify(18)` is `1.125rem`. `ListItem`'s
|
|
2565
|
+
placeholder icon now uses it at 18px, and `Skeleton` no longer forces a
|
|
2566
|
+
24px minimum width, so small placeholders keep the size they ask for.
|
|
2567
|
+
- `@kerfjs/ui/catalog`'s application-sized (`height: "app"`) example frame
|
|
2568
|
+
no longer loses taps in Safari/WebKit. The frame became the containing block
|
|
2569
|
+
for screen-fixed chrome through `contain: layout`. Combined with its clip,
|
|
2570
|
+
that made WebKit mis-hit-test any transformed element inside an open compact
|
|
2571
|
+
overlay. Every pressed `ListItem` scales, so taps on an overlay rail's items
|
|
2572
|
+
went to their section instead. The frame now uses an identity transform,
|
|
2573
|
+
which docks the same chrome without the bug and renders identically.
|
|
2574
|
+
- **Breaking (`@kerfjs/ui/catalog`):** `CatalogExample`'s viewport drops
|
|
2575
|
+
`height: "fill"` and `fillChildren`. The catalog lays examples out at their
|
|
2576
|
+
content height, so neither could give a specimen a definite height, and a
|
|
2577
|
+
child sized with `height: 100%` (a horizontal `ResizableRegion`, say)
|
|
2578
|
+
collapsed to its content. Use a fixed `height` (`short` through `app`) when
|
|
2579
|
+
a specimen must fill its frame. `minHeight` remains, documented as a minimum
|
|
2580
|
+
rather than a fill.
|
|
2581
|
+
- `create-kerf-component`'s `kerf.components.json` now accepts an optional
|
|
2582
|
+
`composition.wiring.stateAttributes` declaration (the wiring-owned state
|
|
2583
|
+
attributes `@kerfjs/ui`'s catalog now carries), so third-party
|
|
2584
|
+
component authors can list the `data-*` attributes their wiring helpers write
|
|
2585
|
+
(`{ name, on, helper, meaning }`). `kerf-component-catalog` passes them
|
|
2586
|
+
through to the generated `component-catalog-v2.json` and reports a non-`data-*`
|
|
2587
|
+
name, a duplicate name, an empty `on` or `meaning`, or a helper missing from
|
|
2588
|
+
`wiring.helpers` at its exact path.
|
|
2589
|
+
- `@kerfjs/ui`'s component catalog now declares **wiring-owned state
|
|
2590
|
+
attributes**. A new optional `wiring.stateAttributes` in
|
|
2591
|
+
`component-catalog-v2` (and per wiring item in v1) lists each `data-*`
|
|
2592
|
+
attribute a wiring helper writes at runtime, such as `data-handle-inset` and
|
|
2593
|
+
`data-resizing` from `wireResizableRegions`. For each one it records the
|
|
2594
|
+
element, the helper, and the meaning, so AI consumers and tools can tell
|
|
2595
|
+
them apart from attributes the app writes. Every first-party wiring helper
|
|
2596
|
+
is declared. `check:catalog` fails when a helper's declarations differ from
|
|
2597
|
+
what its source writes.
|
|
2598
|
+
- `@kerfjs/ui`'s `wireSidebar` no longer leaves focus inside a panel it just
|
|
2599
|
+
collapsed. When the collapse was triggered from a toggle inside the panel
|
|
2600
|
+
(the documented placement), focus now moves to that panel's toggle outside
|
|
2601
|
+
it, including one the app renders only once the panel is collapsed. The
|
|
2602
|
+
collapsible-sidebar recipe now shows one control per action: each panel's
|
|
2603
|
+
own collapse toggle while it is open, and the main header's expand toggle
|
|
2604
|
+
only while it is collapsed. Wide widths no longer show two rail toggles.
|
|
2605
|
+
- `@kerfjs/ui`'s `wireSidebar` keeps a compact overlay intact when the app
|
|
2606
|
+
re-renders the wired root without changing a panel. Previously, selecting a
|
|
2607
|
+
destination in an open compact rail morphed the root, which removed the
|
|
2608
|
+
overlay attributes and the backdrop, and the "overlay" rail fell back into
|
|
2609
|
+
the layout. The wire now re-applies its host attributes and backdrop after
|
|
2610
|
+
any such re-render, and the backdrop carries `data-morph-preserve`.
|
|
2611
|
+
- `@kerfjs/ui`'s `wireSidebar` now opens a compact overlay only on a user
|
|
2612
|
+
action. Wiring on a compact device, or crossing from a wide device class to
|
|
2613
|
+
a compact one, collapses every panel. The page is no longer covered by a
|
|
2614
|
+
backdrop and focus trap until dismissed. Crossing back to a wide class, or
|
|
2615
|
+
disposing the wire, restores each panel's remembered inline state.
|
|
2616
|
+
Persistence now stores only that inline choice, never an overlay's
|
|
2617
|
+
open/closed state. A new optional `WireSidebarPanel.inlineCollapsed`
|
|
2618
|
+
declares the inline default when an app seeds its signal from the device
|
|
2619
|
+
class, which avoids an open first frame on a compact device. The
|
|
2620
|
+
collapsible-sidebar recipe no longer opens its rail as a blocking overlay
|
|
2621
|
+
on load at compact widths.
|
|
2622
|
+
- `@kerfjs/ui`'s `ResizableRegion` handle keeps its hit target and focus ring
|
|
2623
|
+
whole at a clipping edge. When a parent clamps the region to its own edge
|
|
2624
|
+
(the catalog's 390px stage, an app shell with a `max-width` container),
|
|
2625
|
+
`wireResizableRegions` marks the region `data-handle-inset` and the handle
|
|
2626
|
+
moves inside it instead of overhanging the edge by 10px, where the frame cut
|
|
2627
|
+
its focus ring in half. The ring is now drawn inside the handle's box
|
|
2628
|
+
(`outline-offset: -3px`), so it is also no longer shaved where the region's
|
|
2629
|
+
ends meet a clipping edge.
|
|
2630
|
+
- `@kerfjs/ui`'s `wireResizableRegions` keeps a clamped separator's
|
|
2631
|
+
`aria-valuenow`/`aria-valuemax` current at rest. Previously, after a size was
|
|
2632
|
+
saved at a wider width, narrowing the parent or any unrelated re-render left
|
|
2633
|
+
the handle reporting the unclamped rendered size until it was next focused or
|
|
2634
|
+
resized. A `ResizeObserver` on each region and its parent and a
|
|
2635
|
+
`MutationObserver` for re-renders now re-clamp the report; the disposer
|
|
2636
|
+
disconnects both.
|
|
2637
|
+
- The `@kerfjs/ui` catalog's `height: "app"` example frame is now the
|
|
2638
|
+
containing block for screen-fixed chrome, so a compact `CollapsiblePanel`
|
|
2639
|
+
overlay, its backdrop, and restore controls dock to the frame's edges. The
|
|
2640
|
+
collapsible-sidebar recipe's compact rail was fixed to the page's left edge,
|
|
2641
|
+
24px outside the inset frame, so its leading edge looked cut off at 390px.
|
|
2642
|
+
- The `CollapsiblePanel` compact-overlay backdrop now covers its whole
|
|
2643
|
+
containing block. As a `<button>`, it did not stretch between its insets and
|
|
2644
|
+
scrimmed only a 35px strip.
|
|
2645
|
+
- `@kerfjs/ui`'s `wireResizableRegions` now bounds a resize to the space the
|
|
2646
|
+
region's parent actually leaves. When a parent clamps the track (a
|
|
2647
|
+
`max-width` stage, a narrow container), pointer and keyboard resizing stop at
|
|
2648
|
+
the visible size, and the separator reports that size in `aria-valuenow` and
|
|
2649
|
+
its visible maximum in `aria-valuemax`. Previously a region resized to 420
|
|
2650
|
+
inside a 340px stage announced 420 and needed several key presses before the
|
|
2651
|
+
separator moved. Focusing the handle reports a stale larger committed size as
|
|
2652
|
+
the shown size without committing it.
|
|
2653
|
+
- The UI evaluator's `KUI-B050` target-size rule now accepts a 44×36 target
|
|
2654
|
+
inside compact density (`[data-density="compact"]`), matching the 36px
|
|
2655
|
+
compact row height; standard density still requires 44×44, and the width
|
|
2656
|
+
floor is unchanged.
|
|
2657
|
+
- Fixed `kerf-ui-analyze` and the `eslint-plugin-kerfjs` UI rules treating
|
|
2658
|
+
every name in a catalog entry's `publicExports` as that entry's component,
|
|
2659
|
+
so a helper such as `uiColor` or `flex` called with an object whose keys
|
|
2660
|
+
matched a contract path (`uiColor({ choices: [...] })`) was checked as a
|
|
2661
|
+
`Select` or `List` call. Only component exports, whose names start with an
|
|
2662
|
+
uppercase letter as JSX component tags do, now resolve to an entry; the
|
|
2663
|
+
`@kerfjs/ui` catalog check fails if a cataloged `SafeHtml` render function
|
|
2664
|
+
is lowercase or any other runtime export is uppercase.
|
|
2665
|
+
- The `@kerfjs/ui` component catalog's `ToolbarText` entry now lists every
|
|
2666
|
+
token its `xlarge` size reads (`--kui-color-text`, `--kui-font-l`,
|
|
2667
|
+
`--kui-font-2xl`) in `publicTokens`; previously it named only the tokens of
|
|
2668
|
+
the smaller sizes.
|
|
2669
|
+
- The `@kerfjs/ui` browser evaluator's target-size check (`KUI-B050`) now
|
|
2670
|
+
measures the pointer-reachable area instead of only the border box: an
|
|
2671
|
+
undersized control is hit-tested outward from its center, so a transparent
|
|
2672
|
+
`::before`/`::after` hit layer (such as the `ListHeader` action's) counts,
|
|
2673
|
+
while `pointer-events: none` decoration, clipping, and overlapping
|
|
2674
|
+
neighbors do not. Diagnostic evidence now carries the measured size plus
|
|
2675
|
+
the border `box`.
|
|
2676
|
+
- Fixed the `eslint-plugin-kerfjs` `ui-css-values` messages (`KUI-L013`,
|
|
2677
|
+
`KUI-L014`, `KUI-L017`) listing suggested helpers with unbalanced backticks
|
|
2678
|
+
(``use `uiColor() or `foregroundColorVar().``); each helper is now wrapped
|
|
2679
|
+
as `` `uiColor()` ``.
|
|
2680
|
+
- Fixed `kerf-ui-analyze` skipping the CSS-value contracts of `@kerfjs/ui`
|
|
2681
|
+
`Select` and `Skeleton`. Its component lookup was keyed by display name, so
|
|
2682
|
+
the same-named Web Awesome catalog entries (`wa-select`, `wa-skeleton`) —
|
|
2683
|
+
which carry no CSS-value props — shadowed them, and a wrong-grammar helper
|
|
2684
|
+
such as `colorVar()` for `SelectChoice.color` went unreported although the
|
|
2685
|
+
ESLint rule caught it. Entries now resolve by `package:id`, using the
|
|
2686
|
+
selection catalog's public exports and import subpaths.
|
|
2687
|
+
- Fixed `@kerfjs/ui` monospace text rendering in the generic face (Courier on
|
|
2688
|
+
macOS Chromium) whenever Web Awesome was loaded: `--kui-font-mono` deferred to
|
|
2689
|
+
Web Awesome's `ui-monospace, monospace`, which Chromium does not resolve, and
|
|
2690
|
+
the trailing generic `monospace` kept Kerf's named fallbacks from ever
|
|
2691
|
+
applying. `--kui-font-mono` is now Kerf's own stack (`ui-monospace,
|
|
2692
|
+
SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace`),
|
|
2693
|
+
and the Web Awesome theme points `--wa-font-family-code` at it so Kerf `Text
|
|
2694
|
+
font="monospace"` and Web Awesome code text match.
|
|
2695
|
+
- The `@kerfjs/ui` Web Awesome theme now gives default-size single-line
|
|
2696
|
+
controls Kerf's 44px control height, so a plain `wa-input` or `wa-button`
|
|
2697
|
+
sits flush beside a Kerf `Select` instead of about 9px shorter. It sets
|
|
2698
|
+
`--wa-form-control-height` to `2.75em` (44px at the default size) on Button,
|
|
2699
|
+
Color Picker, Input, Known Date, Number Input, Radio Group, Select, Textarea,
|
|
2700
|
+
and Time Input; `size="large"` scales proportionally, `size="small"` keeps Web
|
|
2701
|
+
Awesome's compact height, and buttons inside a `ToolbarControlGroup` keep the
|
|
2702
|
+
group's 40px (32px compact) height. Tags, copy buttons, and toasts are
|
|
2703
|
+
unchanged.
|
|
2704
|
+
- Fixed an `@kerfjs/ui` `Select` menu drawing two separators when a choice with
|
|
2705
|
+
`separatorBefore` opened a separated group: the group's border plus a
|
|
2706
|
+
`wa-divider` left an empty band between the group title and its first
|
|
2707
|
+
choice. `separatorBefore` now only divides a choice from the previous choice
|
|
2708
|
+
in the same list; a group boundary is already the single separator.
|
|
2709
|
+
- Fixed `@kerfjs/ui` compact `ToolbarControlGroup` end highlights not being
|
|
2710
|
+
concentric with the group: controls sat 2px from the sides but 1px from the
|
|
2711
|
+
top and bottom. A compact group now has no padding, so its 32px controls sit
|
|
2712
|
+
on a 1px inset on every side with a radius of the group radius minus 1px
|
|
2713
|
+
(pill and rounded). In compact mixed groups the raised selection still paints
|
|
2714
|
+
over the border with the group's radius, neighboring controls still abut, and
|
|
2715
|
+
the trailing dropdown trigger keeps the 1px end inset instead of running onto
|
|
2716
|
+
the border. Compact groups are 2px narrower as a result.
|
|
2717
|
+
- Added `Toolbar.safeAreaEdges` to `@kerfjs/ui` so an app bar or bottom bar
|
|
2718
|
+
that sits at a screen edge, outside any `Pane` header or footer, can claim
|
|
2719
|
+
those edges for device safe areas. A toolbar there used to take only the
|
|
2720
|
+
inline edges an owner handed it, so the app-shell recipe's top bar never
|
|
2721
|
+
cleared the status area. Each claimed side pads by the routed
|
|
2722
|
+
`--kui-edge-inset-*` context, or the full device inset when nothing routes
|
|
2723
|
+
it, while the bar's surface and divider still paint through; the minimum
|
|
2724
|
+
height grows with the claimed block insets so a shrinking flex column keeps a
|
|
2725
|
+
whole control row clear. A claim inside a `Pane` header or footer adds
|
|
2726
|
+
nothing, since the pane already owns those edges. The app-shell recipe's app
|
|
2727
|
+
bar now claims the top edge and both sides.
|
|
2728
|
+
- Fixed `@kerfjs/ui` slide-motion `ResizableRegion` content overflowing its
|
|
2729
|
+
separator when a parent clamps the region. The expanded content kept the
|
|
2730
|
+
committed size even when a `max-width` or narrow container held the track
|
|
2731
|
+
smaller, so in the catalog at 390px a region resized to 420px showed text
|
|
2732
|
+
running past its handle. Expanded content now follows the region's actual
|
|
2733
|
+
track on both axes; the fixed expanded size still applies while collapsing, so
|
|
2734
|
+
the collapse keeps reading as a slide.
|
|
2735
|
+
- Fixed `@kerfjs/ui` `ResizableRegion` panes stopping at their content's
|
|
2736
|
+
height. The region's content now spans the whole region, like its separator,
|
|
2737
|
+
and a lone child (normally a `Pane`) fills it, so the app-shell recipe's
|
|
2738
|
+
navigation and inspector panes reach the bottom edge and scroll long content
|
|
2739
|
+
inside their own content slot instead of ending partway down the region.
|
|
2740
|
+
Several children still stack at their natural height.
|
|
2741
|
+
- Fixed `@kerfjs/ui` `Toolbar responsive="center-priority"` leaving an
|
|
2742
|
+
expanded center control at roughly half the row on narrow toolbars. The
|
|
2743
|
+
policy set the toolbar's own grid template inside a container query on the
|
|
2744
|
+
toolbar itself, which can never match, so the center kept only the first
|
|
2745
|
+
column track once the leading and trailing zones left. The dead rule is gone
|
|
2746
|
+
and the expanded center now spans every column track, filling the toolbar's
|
|
2747
|
+
content width at phone widths.
|
|
2748
|
+
- Fixed a nested `@kerfjs/ui` `List`, `Row`, or `Grid` inheriting its
|
|
2749
|
+
ancestor's `gap` and `flex`. Those props travel through private custom
|
|
2750
|
+
properties, which inherit, so a nested `List` without its own `gap` took the
|
|
2751
|
+
enclosing `List`'s gap (a heading unit inside a form got a 24px gap between
|
|
2752
|
+
its title and supporting line) and any nested instance without `flex` took the
|
|
2753
|
+
ancestor's flex growth. Every instance now resets its private values, so an
|
|
2754
|
+
omitted prop means that component's own default. The workspace-header recipe's
|
|
2755
|
+
breadcrumb now sits directly above its title and the List demo's section rows
|
|
2756
|
+
sit flush under their header, as intended.
|
|
2757
|
+
- Fixed `@kerfjs/ui` slide-motion `ResizableRegion` content staying at its
|
|
2758
|
+
previous width during a live resize until the app re-rendered the committed
|
|
2759
|
+
size. `wireResizableRegions` now applies the live size to the sliding content
|
|
2760
|
+
as well as the track, for pointer drags and key presses, so the content fills
|
|
2761
|
+
the region (including a safe-area edge extent) throughout the drag and a later
|
|
2762
|
+
collapse still slides it out at the resized width.
|
|
2763
|
+
- Fixed the `@kerfjs/ui` `ListHeader` action's pointer target being only its
|
|
2764
|
+
fitted 36px square although the guidance promises 44px. A transparent hit
|
|
2765
|
+
layer now extends the target to at least 44 × 44 around the square without
|
|
2766
|
+
moving layout or enlarging the painted hover surface. Compact headers are
|
|
2767
|
+
36px tall like the rest of the compact List family, so their action target is
|
|
2768
|
+
44px wide and clamped to the header height, never reaching into a neighboring
|
|
2769
|
+
row.
|
|
2770
|
+
- Fixed re-renders closing open Web Awesome popups: the morph (and the keyed-list
|
|
2771
|
+
attribute fast path) no longer removes a live `open` attribute from custom
|
|
2772
|
+
elements (`wa-select`, `wa-dropdown`, `wa-dialog`, …) when the template omits
|
|
2773
|
+
it — the same user-agent-owned treatment `<details>` / `<dialog>` already
|
|
2774
|
+
had. A template can still set `open`; closing stays imperative.
|
|
2775
|
+
- The `@kerfjs/ui` composer-form recipe's supporting line now sits directly
|
|
2776
|
+
under its toolbar title instead of 24px lower, because a nested `List` no
|
|
2777
|
+
longer inherits the form's section gap (see the nested `List`/`Row`/`Grid`
|
|
2778
|
+
fix above). The guidance now
|
|
2779
|
+
also states that `ToolbarText` below `xlarge` is intentionally quiet identity
|
|
2780
|
+
text with no tone option. A normal-color subsection title is `Text` with an
|
|
2781
|
+
`h2`–`h6` variant, or `ListHeader` for a list or menu section.
|
|
2782
|
+
- Fixed `@kerfjs/ui` `ToolbarText size="small"` labels rendering in a
|
|
2783
|
+
monospace fallback face in Chromium. The small size used the code-font token,
|
|
2784
|
+
which resolves through Web Awesome's `ui-monospace, monospace` stack; Chromium
|
|
2785
|
+
does not recognize `ui-monospace`, so labels such as a pane's "Workspace" or
|
|
2786
|
+
"Ready" fell back to the generic monospace font. Every `ToolbarText` size now
|
|
2787
|
+
keeps the inherited UI sans stack.
|
|
2788
|
+
- Fixed `@kerfjs/ui` `ListInsetControl` not stretching its control as
|
|
2789
|
+
documented. Its `justify-content: stretch` is a no-op on a flex row, so a
|
|
2790
|
+
`Select`, `wa-input`, or `wa-button` inside stayed at its natural width. Each
|
|
2791
|
+
direct child now grows to fill the inset row (several children share it with
|
|
2792
|
+
the 8px gap) and may shrink below its intrinsic width instead of overflowing.
|
|
2793
|
+
- `@kerfjs/ui` `List`, `Row`, and `Grid` can now be the layout root of a
|
|
2794
|
+
fixed-height parent. New `fill` takes the parent's full height (use `flex`
|
|
2795
|
+
inside a flex layout as before), and new `rootAttributes` carries safe
|
|
2796
|
+
`data-*` metadata while the component's structural attributes stay
|
|
2797
|
+
protected. The app-shell and collapsible-sidebar recipes now use a filling
|
|
2798
|
+
List or Row root instead of a frame `Pane` whose scroll owner never scrolled;
|
|
2799
|
+
the collapsible sidebar's rail and drawer now reach the real frame edges, so
|
|
2800
|
+
they paint through safe areas as the layout model intends. The UX catalog
|
|
2801
|
+
adds an application-sized `height: "app"` (592px) specimen frame, and both
|
|
2802
|
+
recipes use it instead of the cramped 360px `tall` frame.
|
|
2803
|
+
- Fixed a `@kerfjs/ui` stacked `Toolbar` clipping its last trailing action at
|
|
2804
|
+
phone widths (the compact-toolbar recipe's "More" button at 390px). A
|
|
2805
|
+
toolbar's trailing zone now wraps whole control groups onto another
|
|
2806
|
+
trailing-aligned row under every `responsive` policy, and a
|
|
2807
|
+
`responsive="stack"` toolbar wraps its stacked center and trailing groups the
|
|
2808
|
+
same way, so no action is ever clipped or shrunk. Stacked zones also span the
|
|
2809
|
+
full toolbar width; they previously lost 16px to empty column tracks. New:
|
|
2810
|
+
`responsive="wrap"` keeps a heading on one row while everything fits and
|
|
2811
|
+
otherwise moves the trailing zone below a whole title instead of truncating
|
|
2812
|
+
it. The loading-inspector recipe uses it, so its narrow heading shows the
|
|
2813
|
+
whole record title instead of an ellipsis.
|
|
2814
|
+
- `@kerfjs/ui` layouts and `Pane` now handle device safe areas as one model.
|
|
2815
|
+
Pane and panel backgrounds, separators, and dividers paint through unsafe
|
|
2816
|
+
areas; content is padded only on the edges a region actually reaches, and
|
|
2817
|
+
block insets become scroll padding so content can scroll under the status bar
|
|
2818
|
+
or home indicator but always scroll clear. `Workbench` rails and drawer,
|
|
2819
|
+
`CollapsiblePanel`, and the `SplitView` list grow by the inset they dock to.
|
|
2820
|
+
A center pane picks up the inset when an adjacent rail collapses, and
|
|
2821
|
+
interior or nested edges are never double-inset. A header or footer `Toolbar`
|
|
2822
|
+
keeps its dividers edge to edge. New: `Pane.safeAreaEdges` (default all
|
|
2823
|
+
sides; `[]` opts out), the `--kui-safe-area-*` device-inset tokens (default
|
|
2824
|
+
`env(safe-area-inset-*)`), the inherited `--kui-edge-inset-*` edge context for
|
|
2825
|
+
app-owned layouts, and `--kui-resizable-region-edge-extent`. Nothing changes
|
|
2826
|
+
on devices or pages without safe-area insets.
|
|
2827
|
+
- Fixed a `@kerfjs/ui` `ListHeader` action sitting about 4px outside the
|
|
2828
|
+
trailing toolbar action of the Pane header above it. Its fitted action now
|
|
2829
|
+
centers in the same 44px slot a toolbar control occupies at the 8px inline
|
|
2830
|
+
margin, so trailing icon actions share one axis. The action's size, 18px
|
|
2831
|
+
visual, and hover square are unchanged.
|
|
2832
|
+
- **Breaking (`@kerfjs/ui`, 5.0 beta):** `SelectChoice.color` now accepts only
|
|
2833
|
+
a foreground color, the new `CssForegroundColor` brand from
|
|
2834
|
+
`@kerfjs/ui/css-values`. `uiColor()` returns it for foreground token names
|
|
2835
|
+
(the new `UiForegroundColorName`: the `*-on-*` roles, `text`, `text-quiet`,
|
|
2836
|
+
`text-link`, and the `*-text` aliases), and the new
|
|
2837
|
+
`foregroundColorVar('--app-icon-color', fallback?)` returns it for an
|
|
2838
|
+
application-owned property. The `--kui-color-success` / `warning` / `danger`
|
|
2839
|
+
/ `pop` / `accent` compatibility aliases are quiet fills that read like
|
|
2840
|
+
foreground colors; colored with one, an icon rendered at about 1.2:1
|
|
2841
|
+
contrast. `uiColor('success')` and the other fill, border, and surface tokens
|
|
2842
|
+
still return a plain `CssColor` and no longer type-check as an icon color,
|
|
2843
|
+
and neither does a plain `colorVar()` value. Migrate
|
|
2844
|
+
`color: uiColor('success')` to `uiColor('success-on-quiet')` and
|
|
2845
|
+
`color: colorVar('--app-color')` to `foregroundColorVar('--app-color')`;
|
|
2846
|
+
`uiColor('…-on-…')` calls keep compiling unchanged. The catalog's CSS-value
|
|
2847
|
+
contract for `choices[].color` lists `uiColor` and `foregroundColorVar`, so
|
|
2848
|
+
`eslint-plugin-kerfjs` also reports `colorVar()` there (`KUI-L014`), and
|
|
2849
|
+
the source and packed consumer type contracts pin the rejected fills.
|
|
2850
|
+
|
|
2851
|
+
- Fixed an `@kerfjs/ui` icon-only `Select` beside other controls in one
|
|
2852
|
+
`ToolbarControlGroup`. A compact Select no longer eats 1px of the group's
|
|
2853
|
+
4px gap on each side (the lone-trigger padding overlap now applies only when
|
|
2854
|
+
it is the group's only child), a compact rounded Select uses its siblings'
|
|
2855
|
+
item radius instead of the lone-slot radius, and the Select now shows the
|
|
2856
|
+
same hover pill as its sibling buttons (a lone Select lifts the whole group,
|
|
2857
|
+
like a popup-menu dropdown). In a group with per-control focus rings
|
|
2858
|
+
(`focusRing="control"`, the default) the Select paints the same ring as its
|
|
2859
|
+
siblings even when `focusRingOwner="group"` was set, which previously left it
|
|
2860
|
+
with no visible focus. A compact icon-only `<button>` is now a 32px circle,
|
|
2861
|
+
so a selected compact segment is no longer a 34x32 oval. The
|
|
2862
|
+
ToolbarControlGroup catalog adds a "Select beside actions" example.
|
|
2863
|
+
|
|
2864
|
+
- Changed the `@kerfjs/ui` icon-only `Select`
|
|
2865
|
+
(`selectedPresentation="icon-only"`) to keep its disclosure caret. The
|
|
2866
|
+
selected icon and caret now form one pill with the same geometry as a
|
|
2867
|
+
`ToolbarControlGroup` popup-menu `wa-dropdown` trigger: 8px inline padding on
|
|
2868
|
+
both sides, 12px from the icon to the caret, the same caret glyph size, and a
|
|
2869
|
+
40px default or 32px compact control height, so the icon sits left of center
|
|
2870
|
+
to balance the caret. In a single `ToolbarControlGroup` the group now sizes to
|
|
2871
|
+
the trigger (a 70x44 default or 68x34 compact pill, wider than it is tall)
|
|
2872
|
+
with an even inset on every side and a concentric radius, for pill and
|
|
2873
|
+
rounded shapes, so the group-owned outline or halo ring follows the pill while
|
|
2874
|
+
focused and while the listbox is open. Before, a default-size trigger was a
|
|
2875
|
+
32px square left-aligned in its 44px group, and the caret was hidden. The
|
|
2876
|
+
Select catalog adds a default-size "Toolbar icon" example beside the compact
|
|
2877
|
+
one.
|
|
2878
|
+
|
|
2879
|
+
- Fixed the `@kerfjs/ui` icon-only `Select` focus ring in a
|
|
2880
|
+
`ToolbarControlGroup` not matching the control: the compact trigger grew its
|
|
2881
|
+
group into a 36x34 oval and its disclosure caret overflowed the trailing edge.
|
|
2882
|
+
The group-owned ring now stays concentric with the trigger while focused and
|
|
2883
|
+
while the listbox is open. The Select demo's "Quiet" option icon also used the success fill alias
|
|
2884
|
+
as its color and was nearly invisible; it now uses `success-on-quiet`, and the
|
|
2885
|
+
`SelectChoice.color` guidance names foreground tokens.
|
|
2886
|
+
|
|
2887
|
+
- `@kerfjs/ui` UX catalog: the ten production recipes now compose Kerf
|
|
2888
|
+
components, layouts, and Web Awesome surfaces through their public
|
|
2889
|
+
configuration alone, with no route stylesheets, inline styles, or
|
|
2890
|
+
styling-only classes. The list-detail dialog is rebuilt from `DialogSurface`,
|
|
2891
|
+
the dialog's own labeled header and close control, `SplitView` (a full-screen
|
|
2892
|
+
list-to-detail drill-down on compact devices), aligned `ListHeader`s, a
|
|
2893
|
+
`ValueTable`, and footer actions. The desktop application shell switches to one
|
|
2894
|
+
pane at a time below desktop sizes through `deviceClass()`. Page and pane
|
|
2895
|
+
headings stack instead of hiding their titles at narrow widths, and supporting
|
|
2896
|
+
copy, content-item text, and loading skeletons sit on the shared 17px text
|
|
2897
|
+
inset. The catalog frames each recipe in a `CatalogExample` viewport that the
|
|
2898
|
+
recipe declares through an exported `presentation`, and recipe ownership notes
|
|
2899
|
+
render as that example's note. `npm run check:recipes` now fails on a recipe
|
|
2900
|
+
stylesheet, an inline style, a class outside the published layout and Web
|
|
2901
|
+
Awesome vocabulary, a non-public stylesheet import, or recipe-specific rules in
|
|
2902
|
+
the catalog shell stylesheet.
|
|
2903
|
+
- Fixed `@kerfjs/ui/webawesome.css` `wa-dialog` titles given as a plain-string
|
|
2904
|
+
`label` sitting at the bare surface inset; they now inset by one bordered
|
|
2905
|
+
item step (`--kui-layout-item-padding` + 1px) so the header label lines up
|
|
2906
|
+
with body text and icons. Slotted label elements are unaffected.
|
|
2907
|
+
- Fixed icon + label `wa-button`s inside `ToolbarControlGroup` stacking the
|
|
2908
|
+
icon above the label; their label part now lays out as a single nowrap row,
|
|
2909
|
+
matching native mixed buttons.
|
|
2910
|
+
- `prompt()` / `form()` now reject with a `TypeError` when a validator returns
|
|
2911
|
+
a promise (validators are synchronous), instead of resolving the value and
|
|
2912
|
+
leaving an unhandled rejection. `prompt()` also re-reads its input on every
|
|
2913
|
+
OK, so a reactive `render` that replaces the input no longer submits the
|
|
2914
|
+
detached original's stale value, and a removed input rejects the promise.
|
|
2915
|
+
- A local `npm run check` run with `KERF_SKIP_PACKAGE_GATES=1` no longer
|
|
2916
|
+
records a verified tree, so the pre-push hook cannot skip the sibling-package
|
|
2917
|
+
gates that run left out.
|
|
2918
|
+
- `kerfjs/overlay`: a `prompt()` `validate` or `form()` `field.validate` that
|
|
2919
|
+
throws now closes the dialog (full teardown, focus restored) and rejects the
|
|
2920
|
+
returned promise with the original error. Previously the error escaped the
|
|
2921
|
+
OK click or Enter handler, and the dialog stayed open with an OK button that
|
|
2922
|
+
could never succeed. Validators are synchronous; this is the error channel
|
|
2923
|
+
for a validator bug.
|
|
2924
|
+
- `kerfjs/overlay`: when a `form()` field input disappears after the dialog
|
|
2925
|
+
opens (for example a reactive `render` re-render drops it), OK and Enter now
|
|
2926
|
+
close the dialog and reject the promise with an error naming the missing
|
|
2927
|
+
field. Previously `form()` resolved `null`, which
|
|
2928
|
+
reads as a Cancel, and threw from the click handler.
|
|
2929
|
+
- `@kerfjs/ui`: a multiline `ListItem` whose label fits on one line now
|
|
2930
|
+
centers its icon on that line. The row's 44px minimum used to stretch the
|
|
2931
|
+
grid track, which centered the label but left the start-aligned icon about
|
|
2932
|
+
1.4px above it.
|
|
2933
|
+
- `@kerfjs/ui`: a `ToolbarControlGroup` with `focusRing="outline"` or
|
|
2934
|
+
`"halo"` keeps its group focus ring while a `Select` inside it has its
|
|
2935
|
+
listbox open. Chromium and WebKit did not carry `:focus-within` from the
|
|
2936
|
+
focused option to the group, so the ring disappeared.
|
|
2937
|
+
- UX catalog: the foundation palette's Brand swatch uses the brand on-fill
|
|
2938
|
+
color again, the Spacer demo gives its flexible spacer room to grow again,
|
|
2939
|
+
and the TokenSearchField adoption demo again wires its chip keyboard and
|
|
2940
|
+
`onEdit` readout. The catalog demo rework had broken all three.
|
|
2941
|
+
- Documented and pinned how `tooltip()` surfaces a failed show from its delay
|
|
2942
|
+
timer: the half-built tooltip is rolled back, the original error escapes the
|
|
2943
|
+
timer for the host to report (a window `error` event in browsers, matching
|
|
2944
|
+
kerf's other deferred callbacks), and the tooltip stays armed so the next
|
|
2945
|
+
hover or focus tries again.
|
|
2946
|
+
- Fixed the dialog helpers (`confirm` / `prompt` / `form` / `choice`) leaving
|
|
2947
|
+
wiring behind when a step after the overlay opened failed. Their post-open
|
|
2948
|
+
wiring (required-slot checks, the click-table `delegate()`, the Enter-key
|
|
2949
|
+
listener) is now part of construction: a failure removes the listeners
|
|
2950
|
+
already wired, closes the overlay (including a `native` `<dialog>`), restores
|
|
2951
|
+
focus, and rethrows the original error, so no pending promise is left
|
|
2952
|
+
attached to an on-screen dialog.
|
|
2953
|
+
- Added `ticket:timing summary --all`, a read-only cross-ticket timing report
|
|
2954
|
+
(median/p90 per phase, gate, and check step) that counts one push shared by
|
|
2955
|
+
a batch of tickets once and detects and excludes fan-out backfill, such as
|
|
2956
|
+
the first timed push that attached one check interval to 374 historical
|
|
2957
|
+
tickets.
|
|
2958
|
+
- Ticket timing now records per-step durations of the root `npm run check`
|
|
2959
|
+
chain (printed at the end of every run), interrupted gate attempts, active
|
|
2960
|
+
time through `ticket:timing claim`/`release` wrappers around `hotsheet-cli`,
|
|
2961
|
+
and CI/publication intervals imported idempotently from GitHub Actions with
|
|
2962
|
+
`ticket:timing import-ci`.
|
|
2963
|
+
- The pre-push hook no longer reruns `npm run check` when a local run already
|
|
2964
|
+
passed on the exact clean tree being pushed; the skip is recorded in ticket
|
|
2965
|
+
timing, and any dirty worktree, different tree, Node.js change,
|
|
2966
|
+
failed/interrupted rerun, or `KERF_FORCE_CHECK=1` runs the full gate.
|
|
2967
|
+
- The pre-push hook no longer fans its timing record out to every ticket in a
|
|
2968
|
+
push that names more than 25 of them (a first push of a long history, a
|
|
2969
|
+
force-push). It prints a notice and records only the explicit
|
|
2970
|
+
`KERF_TICKET_TIMING_TICKETS` list, or nothing, so it can no longer write the
|
|
2971
|
+
backfill shape the cross-ticket summary has to exclude.
|
|
2972
|
+
- The pre-push hook's "already verified" skip now also requires the same
|
|
2973
|
+
platform, architecture, and installed dependencies as the passing run: a
|
|
2974
|
+
fingerprint of every `package-lock.json` and `node_modules/.package-lock.json`
|
|
2975
|
+
across the root, `ui/`, `eslint-plugin/`, `create-kerf-component/`, and
|
|
2976
|
+
`site/`. A reinstall, a lockfile change, or a missing `node_modules` now runs
|
|
2977
|
+
the full gate.
|
|
2978
|
+
- `ticket:timing record` accepts `--run-id <n>`, and `import-ci` no longer
|
|
2979
|
+
imports a GitHub run a second time when it was already recorded by hand:
|
|
2980
|
+
an interval with that run id, or one with no run id for the same phase and
|
|
2981
|
+
gate whose span overlaps the run's (within 60 seconds), counts as imported.
|
|
2982
|
+
- `bindList()` now rolls back when its first render throws: rows that pass
|
|
2983
|
+
already created are disposed (content mounts and element-mode `dispose`
|
|
2984
|
+
callbacks) and removed before the original error is rethrown, instead of
|
|
2985
|
+
leaking live row effects with no handle to release them.
|
|
2986
|
+
- `bindList()` virtualization now validates its dimensions: heights (fixed,
|
|
2987
|
+
estimated, callback-returned, and `setHeight` reports) must be finite and
|
|
2988
|
+
non-negative, a fixed window-mode `rowHeight` must be positive, and
|
|
2989
|
+
`overscan` / `minRows` must be non-negative integers. Invalid values throw a
|
|
2990
|
+
descriptive error instead of producing blank windows or a corrupted scroll
|
|
2991
|
+
anchor.
|
|
2992
|
+
- `bindList()` now rejects a source that carries the `arraySignal` brand but
|
|
2993
|
+
has no patch queue with a descriptive error at bind time, instead of failing
|
|
2994
|
+
with a generic `TypeError` on its first render.
|
|
2995
|
+
- Added `wa-dialog.hide-actions` support to `@kerfjs/ui/webawesome.css`, hiding
|
|
2996
|
+
Web Awesome's directly exported `header-actions` shadow part for dialogs that
|
|
2997
|
+
provide their own dismissal affordance.
|
|
2998
|
+
- Fixed `mount()` leaving an element permanently "already mounted" when its
|
|
2999
|
+
first render throws. The first render is now transactional: the original
|
|
3000
|
+
error is rethrown, every binding effect and the dev listener observer
|
|
3001
|
+
acquired so far are released, the element's pre-mount child nodes are
|
|
3002
|
+
restored, and a retry on the same element succeeds.
|
|
3003
|
+
- Fixed `overlay()` construction leaking a live wrapper, mount, dismissal
|
|
3004
|
+
listeners, and concurrent-overlay stack entry when setup failed partway. A
|
|
3005
|
+
malformed `initialFocus` selector now throws a descriptive `overlay()` error
|
|
3006
|
+
before anything is touched, and a throwing first render or `native`
|
|
3007
|
+
`showModal()` / `showPopover()` call rolls back everything already installed
|
|
3008
|
+
(restoring focus) before rethrowing. `popover()` and `tooltip()` roll back the
|
|
3009
|
+
same way when positioning fails; the dialog helpers inherit the guarantee.
|
|
3010
|
+
- Added an opt-in `@kerfjs/ui/document.css` baseline for border-box sizing,
|
|
3011
|
+
token-backed body and link presentation, and a `.kui-app-root` full-height
|
|
3012
|
+
chain for application shells.
|
|
3013
|
+
- Added an inline `Text` span variant for secondary copy inside rows, labels,
|
|
3014
|
+
and table cells, preserving tone, size, and font roles without box geometry.
|
|
3015
|
+
- Reworked every focused UX catalog demo to dogfood Kerf components, Web
|
|
3016
|
+
Awesome surfaces, and semantic HTML without route-local stylesheets, inline
|
|
3017
|
+
styles, styling-only classes, or shared icon/button render helpers. Added
|
|
3018
|
+
catalog-owned specimen viewport constraints and a nonwaivable conformance
|
|
3019
|
+
gate that prevents those styling shortcuts from returning.
|
|
3020
|
+
- Fixed `ToolbarControlGroup` dropdown triggers that were sized to fixed 48px/66px boxes,
|
|
3021
|
+
which clipped popup icons and let compact mixed-control carets overflow in
|
|
3022
|
+
Safari while distorting longer catalog controls.
|
|
3023
|
+
- Added a `TabBar.end` action zone for layouts that need a tab-local adjacent
|
|
3024
|
+
`trailing` action and a separate far-edge action; the tab strip now owns the
|
|
3025
|
+
shrink/scroll geometry while all action regions remain visible.
|
|
3026
|
+
- Moved the UX catalog checkerboard to the preview scroll owner and replaced
|
|
3027
|
+
its four gradients with one repeated SVG tile, so the pattern continues
|
|
3028
|
+
through below-fold content.
|
|
3029
|
+
- Added explicit native `slot` support to every stable single-root
|
|
3030
|
+
`@kerfjs/ui` visual component, including alternate render branches, while
|
|
3031
|
+
keeping multi-root `ResizableRegion` and `CollapsiblePanel` excluded.
|
|
3032
|
+
- Fixed the UX catalog's desktop grid sizing so both the sidebar and component
|
|
3033
|
+
detail can scroll all the way to their final content while narrow layouts
|
|
3034
|
+
retain normal document scrolling.
|
|
3035
|
+
- Fixed single-line `ToolbarText` clipping glyph descenders while retaining its
|
|
3036
|
+
horizontal ellipsis behavior.
|
|
3037
|
+
- Formalized UX catalog demos as components, compositions, or recipes; catalogs
|
|
3038
|
+
now group and order those kinds consistently and label compositions with a
|
|
3039
|
+
visible tag instead of title suffixes.
|
|
3040
|
+
- Removed stale Web Awesome guidance that still advertised the deleted
|
|
3041
|
+
aggregate theme route; focused component routes remain the supported catalog
|
|
3042
|
+
surface.
|
|
3043
|
+
- Aligned Web Awesome Accordion and Details disclosure geometry: plain Details
|
|
3044
|
+
keep a flush body, plain Accordion items use the 8px surface inset throughout,
|
|
3045
|
+
framed Details use 16px on the trigger and 8px on the body, and framed
|
|
3046
|
+
Accordion items use 16px throughout.
|
|
3047
|
+
- Added a first-class `@kerfjs/ui/grid` layout primitive for any positive
|
|
3048
|
+
equal-width column count, with typed gap and flex values and zero-minimum
|
|
3049
|
+
fractional tracks that stay equal when child content has different intrinsic
|
|
3050
|
+
widths.
|
|
3051
|
+
- Made accent and filled-outlined Web Awesome badge variants meet WCAG AA at
|
|
3052
|
+
their compact text size while preserving loud accent fills and outlined
|
|
3053
|
+
borders.
|
|
3054
|
+
- Added independent typed `tone`, `size`, and `font` presentation roles to
|
|
3055
|
+
`@kerfjs/ui/text`, covering quiet/danger copy, compact metadata, and monospace
|
|
3056
|
+
identifiers without global utility classes or appearance-only heading levels.
|
|
3057
|
+
- Made filled Web Awesome badges use a quiet semantic fill with normal text by
|
|
3058
|
+
default, preserving variant tint while meeting WCAG AA for their compact text.
|
|
3059
|
+
- Fixed nested Rows and Lists inheriting inset values for sides that were not
|
|
3060
|
+
selected on the inner layout component.
|
|
3061
|
+
- Fixed migrated `Text` instances in Catalog and passive `ListHeader` labels
|
|
3062
|
+
retaining nested padding or border geometry that offset their visible content.
|
|
3063
|
+
- Added `Row.vAlign="baseline"` for native flex cross-axis baseline alignment;
|
|
3064
|
+
`List.vAlign` remains limited to values supported by vertical main-axis
|
|
3065
|
+
distribution.
|
|
3066
|
+
- Added a first-class `@kerfjs/ui/text` component for native `h1`–`h6` and
|
|
3067
|
+
paragraph semantics with standard transparent-border and content-padding
|
|
3068
|
+
geometry and margin-neutral defaults; it renders `p` when `variant` is omitted,
|
|
3069
|
+
and Kerf UI's headings and prose now use it.
|
|
3070
|
+
- Added the shared physical `Sides` contract to `List` and `Row` text/control
|
|
3071
|
+
insets and to `ListInsetText` / `ListInsetControl`; inset wrappers now default
|
|
3072
|
+
to all four sides, while `ListInsetText.horizontalOnly` remains a deprecated
|
|
3073
|
+
compatibility alias for `sides="rl"`.
|
|
3074
|
+
- Added `ListHeader.inline` for shrink-wrapped section labels that remove the
|
|
3075
|
+
component root's outer margin, border, and padding while preserving title,
|
|
3076
|
+
count, action, and disclosure behavior.
|
|
3077
|
+
- Added a catalog-driven public-component integration validator for
|
|
3078
|
+
`@kerfjs/ui`, including an all-at-once dry-run report across package, build,
|
|
3079
|
+
barrel, CSS, demo, route, signature, and compatibility surfaces.
|
|
3080
|
+
- Added one change-local `@kerfjs/ui` verification command that synchronizes
|
|
3081
|
+
generated projections, runs component/bundle/type coverage, builds the demo,
|
|
3082
|
+
reports exact gzip deltas, and records reviewed budget updates with reasons.
|
|
3083
|
+
- Made every `@kerfjs/ui` Playwright invocation build current catalog source
|
|
3084
|
+
after fast preflights, with a served source digest that rejects stale preview
|
|
3085
|
+
output during focused browser runs.
|
|
3086
|
+
- Added durable Hot Sheet phase timing for active work, local verification,
|
|
3087
|
+
push hooks, CI, and publication, including safe failure aggregation and
|
|
3088
|
+
per-ticket summaries.
|
|
3089
|
+
- Added typed flex participation to `Row`, matching `List`'s boolean, finite
|
|
3090
|
+
keyword, and branded `CssFlex` contract.
|
|
3091
|
+
- Added a first-class horizontal `Row` with typed spacing, physical-axis
|
|
3092
|
+
alignment, and opt-in wrapping; `List` now supports the same alignment
|
|
3093
|
+
vocabulary while retaining its existing defaults.
|
|
3094
|
+
- Refined compact mixed `ToolbarControlGroup` selections to retain standard
|
|
3095
|
+
horizontal padding, remove the internal separator, and raise the selected
|
|
3096
|
+
surface over the outer border; avatar group hover now preserves image fitting.
|
|
3097
|
+
- Moved the comprehensive local `npm run check` gate from pre-commit to
|
|
3098
|
+
pre-push so coherent commit batches pay its cost once; pre-commit now performs
|
|
3099
|
+
only Git's staged whitespace check, and multi-source AI guidance files are
|
|
3100
|
+
excluded from repository-wide Prettier enforcement.
|
|
3101
|
+
- Fixed `create-kerf-component` releases carrying a stale composition-catalog
|
|
3102
|
+
schema by generating the bundled copy from `@kerfjs/ui`'s canonical schema
|
|
3103
|
+
and gating both the root check and interactive release flow against drift.
|
|
3104
|
+
- Added catalog-driven CSS value diagnostics across `eslint-plugin-kerfjs`,
|
|
3105
|
+
`kerf-ui-analyze`, and `kerf-ui-doctor`. Stable `KUI-L013`–`KUI-L017`
|
|
3106
|
+
findings now identify raw or unknown values, wrong-dimension helpers,
|
|
3107
|
+
incomplete expressions, declaration-list escapes, and review-worthy
|
|
3108
|
+
off-scale spacing from first- or third-party component catalogs.
|
|
3109
|
+
- Extended the property-specific `@kerfjs/ui/css-values` contracts: `List.flex`
|
|
3110
|
+
now uses finite keywords or `flex()`, `Skeleton` dimensions use `CssSize` and
|
|
3111
|
+
`CssLength`, and `SelectChoice.color` uses `uiColor()` or `colorVar()`.
|
|
3112
|
+
Removed the unrestricted `style` escape hatches from `ListItem` and
|
|
3113
|
+
`ListActionRow` before the 5.0 stable release; use `className`, public tokens,
|
|
3114
|
+
and cataloged props instead.
|
|
3115
|
+
- Added typed, CSS-free `@kerfjs/ui/css-values` builders and branded complete
|
|
3116
|
+
versus expression length types. `List.gap` now accepts direct spacing-token
|
|
3117
|
+
shorthands or complete `CssLength` values and rejects unrestricted CSS strings.
|
|
3118
|
+
- Added the public recursive `JSXChildren` type from both `kerfjs` and
|
|
3119
|
+
`kerfjs/jsx-runtime`, giving third-party function components a canonical
|
|
3120
|
+
declaration for nullable, signal-backed, and arbitrarily nested readonly
|
|
3121
|
+
child content that matches the runtime.
|
|
3122
|
+
- Added the public recursive `KerfUiContent` type across semantic UI content
|
|
3123
|
+
zones, so nullable conditionals and mutable or readonly nested component
|
|
3124
|
+
arrays compose directly without a `Fragment` while raw strings, numbers, and
|
|
3125
|
+
signals remain rejected outside explicit text positions.
|
|
3126
|
+
- Fixed bottom `Workbench` drawers overshooting and snapping during collapse
|
|
3127
|
+
transitions by anchoring fixed-height content to the shell's stable bottom
|
|
3128
|
+
edge.
|
|
3129
|
+
- Fixed bottom `CollapsiblePanel` drawers overshooting their open position and
|
|
3130
|
+
snapping back by anchoring fixed-height content to the panel's stable bottom
|
|
3131
|
+
edge throughout the transform transition.
|
|
3132
|
+
- Formalized named `SafeHtml` prop slots as explicit `zone.jsx.prop` bindings
|
|
3133
|
+
in the UI composition catalog and generalized `ui-composition` linting beyond
|
|
3134
|
+
Toolbar, including statically visible `children`, cardinality, aliases,
|
|
3135
|
+
namespaces, arrays, fragments, and branches.
|
|
3136
|
+
- Added `ToolbarControlGroup.avatarImage`, painting contained avatar imagery on
|
|
3137
|
+
a lone group or on the pressed highlight when the group has multiple buttons.
|
|
3138
|
+
- Split the AppTab and TabBar catalog routes into focused component specimens,
|
|
3139
|
+
and moved their controlled selection, tabpanel, overflow, add/close, and
|
|
3140
|
+
reorder lifecycle into a separate application-tabs composition demo.
|
|
3141
|
+
- Fixed `wireNavStack` focus ownership across controlled navigation: pushes
|
|
3142
|
+
focus the new top view, pops restore its remembered descendant, and removed
|
|
3143
|
+
targets fall back through `data-nav-focus`, the first enabled control, and
|
|
3144
|
+
the view container.
|
|
3145
|
+
- Fixed compact mixed-content `ToolbarControlGroup` dropdown triggers being
|
|
3146
|
+
forced into an icon-only width, which painted the label across its separator
|
|
3147
|
+
and the Web Awesome caret outside the group.
|
|
3148
|
+
- Made `ListItem` clip label, status, and dormant trailing painting to its
|
|
3149
|
+
rounded row boundary so compact and constrained rows cannot visibly overflow;
|
|
3150
|
+
described rows now grow enough to keep their owned two-line label readable.
|
|
3151
|
+
- Fixed compact toolbar `Select` focus to follow its owning group's pill or
|
|
3152
|
+
rounded geometry and restored consistent spacing between popup icons and labels.
|
|
3153
|
+
- Fixed the compact-toolbar recipe's independent overflow action to use the
|
|
3154
|
+
same full-height pill geometry as its adjacent toolbar controls.
|
|
3155
|
+
- Fixed the catalog footer's `Components` relationship selector to fit its icon
|
|
3156
|
+
and plural label and give popup headings/items consistent border clearance.
|
|
3157
|
+
- Fixed a collapsible `TokenSearchField` inside a rounded
|
|
3158
|
+
`ToolbarControlGroup` retaining its independent pill radius instead of using
|
|
3159
|
+
the group's shared concentric highlight radius.
|
|
3160
|
+
- Updated the header-composition catalog demo's supporting copy to use the
|
|
3161
|
+
horizontal `ListInsetText` geometry, aligning it with the value-table content
|
|
3162
|
+
edge across responsive, RTL, and zoomed layouts.
|
|
3163
|
+
- Updated the `Pane` catalog demo's secondary header copy to use
|
|
3164
|
+
`ListInsetText`, aligning it with the standard pane content gutter at wide and
|
|
3165
|
+
narrow sizes instead of maintaining demo-only padding.
|
|
3166
|
+
- Completed `NavStack` navigation transitions by cross-fading top and bottom
|
|
3167
|
+
chrome alongside content slides, added per-view bottom toolbars with a
|
|
3168
|
+
persistent fallback, and replaced the static focused demo with a working
|
|
3169
|
+
push/pop flow.
|
|
3170
|
+
- Replaced the static compact `SplitView` detail specimen with a controlled,
|
|
3171
|
+
interactive list-to-detail drill-down whose Back action restores the list;
|
|
3172
|
+
the roomy example now demonstrates controlled selection as well.
|
|
3173
|
+
- Documented and demonstrated list-first dialog bodies: use `List` with
|
|
3174
|
+
`bodyInset="none"`, and wrap bare dialog copy in `ListInsetText` so content
|
|
3175
|
+
shares the standard list gutter without double-insetting.
|
|
3176
|
+
- Fixed `@kerfjs/ui`'s collapsible `TokenSearchField` keep-open ownership in
|
|
3177
|
+
WebKit: when `focusout.relatedTarget` is missing during pointer activation of
|
|
3178
|
+
an external `data-token-search-keep-open` surface, the helper now uses the
|
|
3179
|
+
actual pointer target instead of collapsing and removing the target before
|
|
3180
|
+
its click handler runs.
|
|
3181
|
+
- Added a first-class vibrant `pop` semantic color for attractive non-status
|
|
3182
|
+
emphasis, with complete light/dark/increased-contrast token roles and typed
|
|
3183
|
+
StateBanner, ListHeader indicator, and ToolbarControlGroup selected tones.
|
|
3184
|
+
- Fixed canonical `Select` popup animation reversals so an earlier close cannot
|
|
3185
|
+
hide a reopened menu after resizing. Canceled transitions retain the accepted
|
|
3186
|
+
state, and removed controls cannot receive stale completion or deferred focus.
|
|
3187
|
+
- Fixed managed `TokenSearchField` Clear focus before the next input task, so
|
|
3188
|
+
immediate typing stays in the replacement editor instead of triggering page
|
|
3189
|
+
shortcuts; genuine later focus handoffs and selections remain untouched.
|
|
3190
|
+
- Fixed `@kerfjs/ui/tab-scaffold` bottom-tab labels being vertically clipped by
|
|
3191
|
+
flex shrinkage while retaining horizontal ellipsis for long labels.
|
|
3192
|
+
- Made inset selection and hover highlights follow their owning control's pill
|
|
3193
|
+
or rounded shape, with concentric inner radii derived from the full inset.
|
|
3194
|
+
- Fixed animated `ResizableRegion` overlays so remembered desktop dimensions
|
|
3195
|
+
cannot make their content overflow the responsive panel cap on narrow screens.
|
|
3196
|
+
- Added configuration-first application-panel policies across `ResizableRegion`,
|
|
3197
|
+
`Workbench`, and `CollapsiblePanel`: separator visibility, instant-track
|
|
3198
|
+
collapse with optional composited content motion, popup-safe overflow,
|
|
3199
|
+
inline/overlay/hidden responsive presentations, and safe-area restore-control
|
|
3200
|
+
placement. `wireResizableRegions` now suppresses motion during pointer drags
|
|
3201
|
+
and ignores unavailable regions; `wireSidebar` supports hidden compact
|
|
3202
|
+
replacements and exclusive overlays.
|
|
3203
|
+
- Added typed `TabBar` allocation/presentation/action-placement and `AppTab`
|
|
3204
|
+
presentation/size/label-width variants for segmented inspector strips,
|
|
3205
|
+
compact drawer tabs, icon-only accessible tabs, and truncating labels.
|
|
3206
|
+
- Added typed `ToolbarControlGroup` size, density, content anatomy, selected
|
|
3207
|
+
chrome/tone, nested-dropdown, and avatar scrim variants.
|
|
3208
|
+
- Added typed `Select` form, borderless-toolbar, intrinsic-navigation, compact,
|
|
3209
|
+
icon-only-selected, truncation, and composed focus-ring variants.
|
|
3210
|
+
- Added `DialogSurface` and `PopupSurface` composition APIs for standard dialog
|
|
3211
|
+
sizes/presentations, independent body/footer insets, and list-compatible popup
|
|
3212
|
+
menu insets without consumer `::part()` overrides.
|
|
3213
|
+
- **Breaking (`@kerfjs/ui`):** removed `PanelHeader` and its subpath/CSS export.
|
|
3214
|
+
Compose page, panel, and dialog headings directly with `Toolbar`, a direct
|
|
3215
|
+
extra-large `ToolbarText`, and optional `ToolbarControlGroup` icon/action zones;
|
|
3216
|
+
keep supporting copy as app-owned content below the toolbar.
|
|
3217
|
+
- Fixed controlled TokenSearchField Select All + Backspace/Delete collapsing the
|
|
3218
|
+
editor: managed deletion keeps the adopted open signal and restores replacement
|
|
3219
|
+
focus before another keystroke, without a stale animation-frame caret reset.
|
|
3220
|
+
The adoption demo now persists both edited text and remaining tokens.
|
|
3221
|
+
- Fixed `Select` controls using only `ariaLabel` being unnamed to assistive
|
|
3222
|
+
technology. Ordinary and custom selected content retain their geometry while
|
|
3223
|
+
the actual shadow combobox receives its accessible name.
|
|
3224
|
+
- Added first-class `Select` hint text below interactive and loading-placeholder
|
|
3225
|
+
controls while keeping empty-value `placeholderText` semantically distinct.
|
|
3226
|
+
|
|
3227
|
+
- Changed the Web Awesome Dialog theme to use 8px body padding and 16px footer
|
|
3228
|
+
padding, independently of the component's shared `--spacing` value.
|
|
3229
|
+
|
|
3230
|
+
- Fixed `kerf-ui-doctor` so its isolated Kerf ESLint pass preserves applicable
|
|
3231
|
+
consumer core rules and suppression reporting options. Playwright's required
|
|
3232
|
+
`no-empty-pattern` fixture suppression no longer becomes a false unused
|
|
3233
|
+
directive while consumer plugin rules remain outside the doctor boundary.
|
|
3234
|
+
|
|
3235
|
+
- Cataloged `SplitView` and its documented
|
|
3236
|
+
`--kui-split-view-list-width` override so `kerf-ui-doctor --full` accepts the
|
|
3237
|
+
public token in downstream application stylesheets.
|
|
3238
|
+
|
|
3239
|
+
- Added the first-class `List` vertical-layout component with gap, flex, scroll,
|
|
3240
|
+
and multi-edge divider options; `Toolbar` now uses the same typed
|
|
3241
|
+
`dividerSides` contract instead of a boolean divider.
|
|
3242
|
+
|
|
3243
|
+
- Added an optional tone-tinted pill badge beside `StateBanner` titles, including
|
|
3244
|
+
loading skeleton behavior and per-instance badge color overrides.
|
|
3245
|
+
|
|
3246
|
+
- Fixed pending `wireTabBars` and `wireTokenSearchFields` controlled-render
|
|
3247
|
+
callbacks moving focus after their owning wiring had been disposed.
|
|
3248
|
+
|
|
3249
|
+
- Changed the default `ListItem` leading icon visual from 24px to a root-scaled
|
|
3250
|
+
18px while retaining the row's 44px minimum target and first-line alignment.
|
|
3251
|
+
|
|
3252
|
+
- Fixed managed `TokenSearchField` clear losing focus or collapsing when an
|
|
3253
|
+
application replaces its controlled editor; continued typing now works without
|
|
3254
|
+
an application reopen callback.
|
|
3255
|
+
|
|
3256
|
+
- Fixed `@kerfjs/ui` automatic TabBar keyboard activation losing focus when a
|
|
3257
|
+
controlled selection replaces the strip; navigation restores the same logical tab.
|
|
3258
|
+
|
|
3259
|
+
- Updated the published setup runtime to patched `minimatch` 9.0.9 and `yaml`
|
|
3260
|
+
2.9.1 releases, resolving the known regular-expression denial-of-service and
|
|
3261
|
+
deeply nested YAML denial-of-service advisories without narrowing Kerf's
|
|
3262
|
+
supported Node.js range.
|
|
3263
|
+
- Fixed `kerf-ui-doctor --full` so its isolated ESLint stage shares the same
|
|
3264
|
+
generated-directory exclusions as TypeScript, static analysis, and cache
|
|
3265
|
+
hashing; populated `dist`, `coverage`, dependency, cache, evidence, and nested
|
|
3266
|
+
worktree directories no longer produce application diagnostics.
|
|
3267
|
+
- Changed `@kerfjs/ui` component-library design templates to compose their
|
|
3268
|
+
individual variant SVGs through HTML and `domotion capture
|
|
3269
|
+
--flatten-nested-svg`, eliminating the hand-built nested-SVG compositor and
|
|
3270
|
+
making top-level template sheets reliable in Sketch.
|
|
3271
|
+
- Added a typed `shape` option to `SunkenPanel`: `rounded` remains the default,
|
|
3272
|
+
while `square` produces a lowered surface with `border-radius: 0` for flush or
|
|
3273
|
+
edge-to-edge application areas. Both shapes now appear in the UX catalog.
|
|
3274
|
+
- Made the Catalog geometry overlay derive both margin bands and border
|
|
3275
|
+
edges/radii from each live specimen's computed CSS. Public example helpers now
|
|
3276
|
+
mark their generated labels and notes for automatic exclusion, and stylesheet,
|
|
3277
|
+
theme, DOM, and resize changes refresh the overlay without duplicated demo
|
|
3278
|
+
measurements.
|
|
3279
|
+
- Updated the `@kerfjs/ui` SVG design-template generator to `domotion-svg`
|
|
3280
|
+
0.30.1 and enabled `--flatten-nested-svg`, so inline component icons are
|
|
3281
|
+
emitted as Sketch-compatible groups without changing their browser rendering.
|
|
3282
|
+
The offline template gate now rejects variant captures that reintroduce nested
|
|
3283
|
+
`<svg>` elements.
|
|
3284
|
+
- Fixed `kerf-ui-doctor` and `kerf-ui-analyze` recursive discovery so nested
|
|
3285
|
+
`.claude/worktrees` checkouts are excluded from source diagnostics, doctor
|
|
3286
|
+
cache inputs, TypeScript, and ESLint.
|
|
3287
|
+
- Added `npx kerfjs setup` and the `kerfjs/setup` automation API for safe,
|
|
3288
|
+
AI-first initialization and migration of core and UI projects. The command
|
|
3289
|
+
provides bounded dry-run diffs, explicit per-conflict keep/Kerf choices,
|
|
3290
|
+
package-scoped hash-backed upgrades, monorepo selection, transactional
|
|
3291
|
+
rollback, shipped guidance, strict TypeScript/ESLint, and UI catalog/profile
|
|
3292
|
+
and doctor discovery. Empty application component metadata now emits a valid
|
|
3293
|
+
empty v2 catalog. Existing JSONC TypeScript configuration is structurally
|
|
3294
|
+
merged without discarding comments, trailing commas, authored fields, or line
|
|
3295
|
+
endings; malformed roots and compiler-option containers require an explicit
|
|
3296
|
+
keep/Kerf decision. Workspace selection now evaluates ordered globstar,
|
|
3297
|
+
brace, exclusion, and re-inclusion patterns deterministically across npm,
|
|
3298
|
+
Yarn, and pnpm declarations, rejects path/symlink/name ambiguity, and uses
|
|
3299
|
+
manager-correct offline commands with explicit Yarn Classic/Berry detection
|
|
3300
|
+
and network-disabled Berry installs.
|
|
3301
|
+
- Added `@kerfjs/ui/doctor` and the `kerf-ui-doctor` command: a versioned, redacted repair-loop report that merges catalog/profile validation, TypeScript, Kerf UI ESLint, static analysis, and opt-in browser evaluation with changed/full modes, monorepo selection, reasoned suppressions, caching, and deterministic exits.
|
|
3302
|
+
- Added the public Playwright-backed `kerf-ui-evaluate` CLI and `@kerfjs/ui/evaluator` Node API. It resolves application profiles and composition catalogs, exercises wide/intermediate/narrow/200%-zoom, light/dark, and reduced-motion contexts across Chromium, Firefox, and WebKit, and emits versioned repair-oriented `KUI-B###` diagnostics plus focused DOM/style evidence and hashed screenshots. Subjective visual quality remains an explicitly separate unrecorded reviewer rubric.
|
|
3303
|
+
- Added `kerf-ui-analyze`, a profile- and catalog-aware static evaluator for Kerf UI integrations. It resolves directory policy per source, follows project-local CSS import graphs without cross-package class leakage, and evaluates shared stylesheets against every consuming source policy before deduplicating findings. Stable portable text, JSON, or SARIF diagnostics cover private selectors, unknown tokens, competing geometry/scroll owners, repeated insets, forced dimensions, off-scale spacing, and dynamic-class review, with exact scoped profile exceptions, a public report schema, and configurable CI review failure.
|
|
3304
|
+
- Added catalog/profile-aware `recommended-ui` and `strict-ui` flat presets to `eslint-plugin-kerfjs`. Toolbar zone acceptance/cardinality and valid wiring imports come from the shipped catalogs; intrinsic or unknown zone children, root/subpath/namespace wiring, and the non-colliding `KUI-L090` load diagnostic are covered by real packed downstream installs on every supported ESLint major.
|
|
3305
|
+
- **Breaking (`@kerfjs/ui` TypeScript declarations):** strengthened invalid-integration contracts for ListHeader modes, Select naming and literal choice identity, SegmentedControl/TabScaffold literal identity, collapsible TokenSearchField props, protected editor metadata, PanelHeader summary ids, ToolbarText line caps, and token-removal callbacks. Added named public unions for previously anonymous finite variants plus source and packed-tarball positive/negative compilation gates. See `ui/docs/type-contracts.md` for the compatibility review and dynamic-data widening syntax.
|
|
3306
|
+
- `create-kerf-component` now scaffolds explicit `kerf.components.json` AI metadata and a deterministic `kerf-component-catalog` generator/checker. Generated v2 entries carry package identity, purpose, verified named exports, composition and geometry ownership, tokens, accessibility, and source links; publishing rejects missing author decisions, schema-invalid source/output fields, deleted sources, renamed exports, duplicate ids, or output drift, including multi-package workspaces. Syntax-aware TypeScript/TSX export discovery prevents JSX text, nested scopes, comments, and literals from impersonating public exports.
|
|
3307
|
+
- Added a versioned application UI profile for AI tools and static evaluators. Shipped package defaults, schema, TypeScript types, Node discovery/merge/validation APIs, and a workspace example now make catalog locations, preferred components/recipes, theme/density policy, semantic token overrides, responsive/layout conventions, and narrow source-located exceptions explicit. Composition-only generated consumer catalogs load without a fabricated v1 selection artifact, while Kerf retains its required v1 selection catalog. Deterministic package → workspace → parent-to-child directory precedence validates every raw layer before merge, attributes resolved diagnostics through field provenance, and rejects stale catalogs, unknown components/tokens/rules, conflicts, malformed value shapes, and broad exemptions.
|
|
3308
|
+
- Fixed `CatalogExampleStack` accessible labels: the helper now renders a semantic `section`, so a supplied `label` exposes the documented named region to assistive technology while an unlabeled stack remains an ordinary grouping.
|
|
3309
|
+
- Added first-class `Pane` and `SunkenPanel` primitives to `@kerfjs/ui`. `Pane` standardizes semantic header/content/footer columns, explicit logical-edge separators, and one content scroll owner; `SunkenPanel` supplies one lowered surface with an 8px inset and vertical rhythm. The Catalog shell now dogfoods `Pane`, and both components ship focused demos, catalog metadata, documentation, and three-engine browser coverage.
|
|
3310
|
+
- Added the package-qualified component catalog v2 alongside the compatible v1 artifact. Its schema and generated metadata formalize child zones, cardinality, exclusivity, wiring, state, responsive behavior, layout and accessibility boundaries, stable validation diagnostics, provenance, and consumer extension catalogs, so AI tools can join Kerf and application components without guessing composition contracts.
|
|
3311
|
+
- Added an AST-based Catalog demo conformance gate. It checks every first-party demo for public helper usage, package imports, focused specimen structure, geometry-overlay metadata, and reviewed schema-checked exceptions, with adversarial fixtures and authoring guidance that makes the same contract available to downstream AI tools.
|
|
3312
|
+
- Made `ui/docs/catalog.md` the authoritative Catalog demo authoring contract, covering focused versus composition previews, public row/group nesting, exact specimen selection, conditional geometry overlays, skip-marker behavior, metadata ownership, and an explicit overlay legend. A shipped `ai/catalog-authoring.json` discovery artifact now routes AI tools to that contract and exact signatures, with schema, link-integrity, and browser-consumer fixture coverage.
|
|
3313
|
+
- Extended `CatalogExample` and `CatalogExampleStack` with typed, runtime-filtered `rootAttributes` for catalog-authoring `data-*` metadata such as `data-demo` and `data-catalog-geometry-overlay-skip`, while preserving helper-owned structural and alignment markers. The UX catalog now composes its example stacks through these public helpers instead of copying private `kui-catalog-*` markup.
|
|
3314
|
+
- Added `revealCatalogEntry` and opt-in `wireCatalog({ revealSelection })` support to the exported Catalog tool. Sidebar or related-entry selection can now reveal the matching row after the controlled render settles, using a desktop-safe media guard, exact id matching, configurable scroll alignment/behavior, focus-preserving scrolling, and cancellation of stale rapid selections; the Kerf UX demo now uses the public behavior.
|
|
3315
|
+
- Added a reusable consumer component-catalog extension schema and checked app-component example. Downstream packages can now publish the same selection facts and margin/border/padding ownership vocabulary as Kerf, and the README, component contract, Catalog guide, `llms.txt`, and AI skill explain how to combine package-qualified app entries with Kerf's shipped catalog for alignment decisions.
|
|
3316
|
+
- Added an opt-in geometry inspector to the exported `@kerfjs/ui/catalog` tool. `geometryOverlay` plus `wireCatalogGeometryOverlay` now marks transparent component bounds with a dashed outline and positive intrinsic margins with devtools-style bands, excludes example labels/alignment scaffolding, stays synchronized across preview changes, and replaces the Kerf UX demo's private implementation.
|
|
3317
|
+
- Added machine-readable margin, border, and padding ownership to every visual entry in the `@kerfjs/ui` component catalog. The additive schema distinguishes self-, parent-, child-, conditional-, and unowned geometry, and enforces complete metadata plus explanatory notes for conditional cases.
|
|
3318
|
+
- Refreshed the standalone reactivity demo lockfile to Vite 6.4.3, PostCSS 8.5.28, and nanoid 3.3.19, clearing its development-toolchain audit advisories.
|
|
3319
|
+
- Overrode the development toolchain's transitive esbuild dependency to 0.28.2, resolving GHSA-g7r4-m6w7-qqqr while current tsup still constrains its declared range to 0.27.x.
|
|
3320
|
+
- Added repository-wide Prettier formatting for TypeScript, JavaScript, Astro, shell, CSS, HTML, Markdown, YAML, and JSON source and structured-content files. Root and `@kerfjs/ui` lint gates now reject formatting drift, while generated, binary, and parser-incompatible fixtures remain explicitly excluded.
|
|
3321
|
+
- Added reusable sidebar tags to `@kerfjs/ui` Catalog entries and marked the 15 Web Awesome components superseded by preferred Kerf patterns or reserved for exceptional cases as `Discouraged` in the UX catalog. The tag is deterministically projected from the canonical recommendation metadata; Popup remains an available conditional positioning primitive.
|
|
3322
|
+
- Aligned Web Awesome Accordion, Card, Details, Callout, and Include surfaces with Kerf content-item geometry: each complete surface now has an overridable 8px logical inline margin and 8px inner padding, Accordion keeps connected items under one group margin, and Card's header/body/footer share the full inset. Tab Panel intentionally retains the roomier 16px container inset.
|
|
3323
|
+
- Fixed `@kerfjs/ui` Web Awesome Slider geometry: its complete interactive region now receives the shared 8px logical inline outer inset without shifting the already-aligned label.
|
|
3324
|
+
- Styled `@kerfjs/ui` Web Awesome OTP Input like a bordered text field: its label now uses the shared uppercase xs/650 field-label treatment, and both label and hint align at the 9px border-plus-padding inset.
|
|
3325
|
+
- Aligned `@kerfjs/ui` Web Awesome Known Date's Month/Day/Year captions and bordered text-like field hints with their values using the shared 9px border-plus-padding inline inset.
|
|
3326
|
+
- Fixed `@kerfjs/ui` Web Awesome Color Picker geometry: its unbordered trigger now receives the shared 8px inline outer inset, aligning it with Kerf content-item spacing.
|
|
3327
|
+
- Fixed `@kerfjs/ui` Web Awesome Checkbox Group and Radio Group option geometry: each group's unbordered option region now receives the shared 8px inline outer inset, aligning it with Kerf content-item spacing without padding the individual controls.
|
|
3328
|
+
- Aligned the remaining bordered/padded Web Awesome chrome in `@kerfjs/ui/webawesome.css` to explicit Kerf spacing tiers: `--kui-wa-control-inset` (8px) drives tabs, inset tree selection, tags, and dropdown items; `--kui-wa-surface-margin` / `--kui-wa-surface-inset` drive bordered surface geometry; and `--kui-wa-container-inset` (16px) retains roomier Tab Panel content. Buttons already inherit the 8px form-control inset; compact badges, unframed Breadcrumb, and slotted Scroller item chrome deliberately retain their native geometry. The tiers are overridable by scope and pinned by three-engine computed-style coverage plus light/dark wide and narrow visual QA.
|
|
3329
|
+
- Tightened the `@kerfjs/ui` Web Awesome theme's form fields to the Kerf content-item inset — a 1px border with 8px inside it (`--wa-form-control-border-width` / `--wa-form-control-padding-block` / `--wa-form-control-padding-inline` now follow `--kui-layout-item-border-width` / `--kui-layout-item-padding`), replacing Web Awesome's larger default pad, so fields land at the standard ~40px height and 9px value inset. Each field's top label is now inset by that same border + padding (9px) so it aligns with the value inside the field, and is styled exactly like a `ListHeader` label — uppercase, xs, weight 650, quiet foreground (`::part(form-control-label)` across Input/Number Input/Textarea/Select/Checkbox Group/Radio Group/Color Picker/Known Date/Time Input, plus the Slider's `::part(label)`). Inline Checkbox/Switch labels keep their sentence case.
|
|
3330
|
+
- Added overflow controls to `@kerfjs/ui`'s `ToolbarText`: `wrap` (flow onto multiple lines instead of a single line), `ellipsis` (show the trailing … at the truncation, or hard-clip when false), and `maxLines` (cap wrapped text to N lines, ellipsizing past it). The default is unchanged — one line, ellipsized when it does not fit. `maxLines` takes effect only with `wrap`. Driven by `data-wrap` / `data-ellipsis` / `data-max-lines` attributes plus a `--kui-toolbar-text-max-lines` var; no new public classes. The UX catalog gains ellipsis/wrap/capped examples.
|
|
3331
|
+
- Fixed a `@kerfjs/ui` `TokenSearchField` bug where selecting all content and pressing Delete (or Backspace) left a stray newline in the field. A `contenteditable` host inserts a bogus `<br>` when emptied that way in every engine — it renders as a newline and `readTokenSearchField` read it back as a space. `wireTokenSearchFields` now strips that line break after any delete input and, when the field is otherwise empty, restores the canonical empty text span and places the caret in it so typing resumes cleanly. Also clears any leftover chips in the select-all case. Regression-tested in unit (happy-dom) and across all three browser engines.
|
|
3332
|
+
- Hardened that full `TokenSearchField` deletion for platform-specific selection
|
|
3333
|
+
ranges whose endpoints sit inside the first and last text spans instead of at
|
|
3334
|
+
the editor boundary—or whose cloned Linux range omits an atomic chip entirely.
|
|
3335
|
+
Full logical text-and-token selection is recognized from its value, while an
|
|
3336
|
+
explicit Ctrl/Cmd+A intent survives only until the next delete and is
|
|
3337
|
+
consumed by that delete even when the browser omits `beforeinput`, and is
|
|
3338
|
+
retained across a controlled editor replacement before or after
|
|
3339
|
+
`beforeinput`. It is captured before propagation can be stopped and
|
|
3340
|
+
invalidated by selection-moving keys, pointer input, blur, or another edit.
|
|
3341
|
+
The explicit shortcut-to-delete transition is handled deterministically:
|
|
3342
|
+
the helper prevents the unreliable mixed-contenteditable native mutation,
|
|
3343
|
+
canonicalizes the empty editor, and emits the corresponding bubbling input
|
|
3344
|
+
event so controlled application state clears before it can restore a chip.
|
|
3345
|
+
A browser can no longer preserve a controlled chip merely because its range
|
|
3346
|
+
shape or native deletion timing differs.
|
|
3347
|
+
- Added a `horizontalOnly` prop to `@kerfjs/ui`'s `ListInsetText`. When true it keeps the horizontal geometry (8px inline margin, 1px left/right border, 8px left/right padding — so the text edge still lands at the 17px inset) but drops the vertical margin, border, and padding, for tight text layout that still aligns with bordered items. It applies a `kui-list-inset-text--horizontal` modifier class; the default (vertical box space intact) is unchanged. The UX catalog gains a horizontal-only example.
|
|
3348
|
+
- Fixed a WCAG AA color-contrast failure on `@kerfjs/ui`'s selected list rows. The selected `ListItem` and `ListActionRow` used the brand accent (`brand-on-quiet`, `#1e6ef4`) for their text, which resolved to only **3.77:1** over the selected `brand-fill-normal` background (`#d6ecff`) — below the 4.5:1 minimum for normal text (flagged by axe downstream). Both now use the normal neutral foreground over the brand-tinted fill, so selection is carried by the fill and border while the text stays readable in light and dark themes. Computed-ratio browser tests pin both selected rows at ≥4.5:1 in both themes across all three engines.
|
|
3349
|
+
- Fixed the same brand-accent contrast failure on `@kerfjs/ui`'s info `StateBanner` tone and `Select`'s current option, where the blue is a semantic (not a selection cue), so the text stays blue rather than going neutral: a new darker `--kui-color-brand-on-fill` token (`#1a5dcf` light; the compliant `#8acbff` in dark) replaces `brand-on-quiet` for brand text placed directly on a brand fill. The info banner (was 4.15:1) now clears ~5.4:1 and the current Select option (was 3.77:1) ~4.9:1. Computed-ratio browser assertions guard both.
|
|
3350
|
+
- Completed the `@kerfjs/ui` `StateBanner` contrast pass: the `success` (was 4.05:1) and `warning` (was 4.39:1) tones failed WCAG AA the same way via their own `*-on-quiet` tokens over the tinted banner fills. New darker `--kui-color-success-on-fill` (`#00792c`) and `--kui-color-warning-on-fill` (`#8f5e00`) tokens (each keeping its semantic hue, dark values unchanged and already compliant) now back the success/warning banner text, clearing ~5.0:1 and ~5.3:1. Every `StateBanner` tone now clears 4.5:1 in both themes, guarded by an all-tone computed-ratio browser assertion.
|
|
10
3351
|
- Added two structure primitives to `@kerfjs/ui` for aligning bare content inside a `.kui-content` list: `ListInsetControl` (`@kerfjs/ui/list-inset-control` + `.css`) wraps a control that owns its own border and padding but no outer margin (a search input, a `SegmentedControl`) with the standard 8px inline margin plus a stretch flex row and an 8px gap, so it lines up with the bordered items around it without double-insetting; `ListInsetText` (`@kerfjs/ui/list-inset-text` + `.css`) gives a bare string or inline content the content-item geometry (8px inline margin, 1px transparent border, 8px padding) so its text edge lands at the same 17px inset as bordered rows. Both are additive, take an optional `className`, and appear in the UX catalog and the component-selection guidance.
|
|
11
3352
|
- `@kerfjs/ui`'s `wireTokenSearchFields` `onEdit` callback now also receives the originating `InputEvent` (`onEdit({ id, editor, event })`), so a consumer can gate token-commit behavior on `event.inputType` / `event.data` (e.g. commit a chip only on whitespace-terminated input) and drop its own `input` listener entirely — completing the goal `onEdit` was added for. Additive; existing `{ id, editor }` destructuring is unaffected.
|
|
12
3353
|
- Added a CI-only visual-drift gate for the `@kerfjs/ui` SVG design templates (`check:design-templates:drift`): it re-renders every template in a browser and fails if any regenerated SVG differs from the committed one (normalizing run-to-run noise — XML comments and auto-minted ids/font names). It closes the gap the offline `check:design-templates` cannot cover and runs in CI's browser-capable job, not the offline pre-commit `check`.
|
|
@@ -139,9 +3480,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
|
139
3480
|
- Added the lockstep `@kerfjs/ui` package: accessible toolbar, menu, tab, header, resize, select, and feedback primitives; semantic CSS tokens and browser component subpaths that automatically include only reachable component styles; CSS-free root/SSR entries and an optional complete stylesheet; opt-in Web Awesome registration; AI-oriented docs; a production-backed UX catalog; bundle/unit/three-engine browser gates; and a least-privilege release workflow.
|
|
140
3481
|
- The virtual-list demo animation opens on the full app again (header, the "N in the DOM" badge, and the list) before the scroll; the list now scrolls inside its own box while the header stays put (previously the whole frame was a full-bleed list strip), holds at row 0 before gliding instead of starting a few rows down, and the loop stays in phase on every pass. Captured with domotion-svg 0.28.2.
|
|
141
3482
|
|
|
142
|
-
|
|
143
|
-
|
|
3483
|
+
- @kerfjs/ui panel toolbars now place groups in leading, center, and trailing zones; relocateOnCollapse keeps chosen groups available when a panel closes.
|
|
144
3484
|
|
|
3485
|
+
## [4.4.1] - 2026-08-26
|
|
145
3486
|
|
|
146
3487
|
- Overhauled the README landing page: new one-line tagline, npm/size/license/TypeScript-types badges, a hoisted "Quick start" (install + `tsconfig`) right under the hook, and a jump nav (Quick start · Why kerf · Quick tour · Docs). The counter example now shows `delegate()` wiring the click handler.
|
|
147
3488
|
- Reworked the homepage hero to lead with the value proposition ("Reactive UI that touches only the bytes that changed"), with "Introducing Kerf" demoted to an eyebrow, a right-sized logo, tighter vertical spacing, and "Get started" as the single filled primary action ("View examples" now a secondary/outline button).
|
|
@@ -150,7 +3491,6 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
|
150
3491
|
- Rewrote the site's docs pages as hand-authored consumer content (cleaner headings, no internal section numbers) rather than verbatim copies of the internal design docs.
|
|
151
3492
|
- Renamed the migration guides' "Side-by-side code" heading to "Section by section" (the sections stack code blocks rather than showing true columns), across all framework pages.
|
|
152
3493
|
|
|
153
|
-
|
|
154
3494
|
- The getting-started and Markdown-editor demo animations now open on a non-blank frame — real code and a rendered heading are visible immediately instead of an empty pane.
|
|
155
3495
|
- Added a horizontal-scroll shadow affordance to wide tables so off-screen columns are discoverable on narrow viewports.
|
|
156
3496
|
- Shortened the longest demo alt text on the router and virtual-list pages for more concise screen-reader output.
|
|
@@ -158,29 +3498,23 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
|
158
3498
|
|
|
159
3499
|
## [4.4.0] - 2026-08-23
|
|
160
3500
|
|
|
161
|
-
|
|
162
|
-
|
|
163
3501
|
- Reworked the router example app to run inside a fake browser window — traffic-light chrome, working Back/Forward buttons wired to `router.back()`/`forward()` via one delegated listener, and a live address bar bound to `router.route` that updates as you navigate — making the URL-driven, no-reload story clearer.
|
|
164
3502
|
|
|
165
3503
|
- **New `kerfjs/router` subpath — a client-side router (the "postcard router").** `createRouter({ routes, mode?, base?, interceptLinks? })` returns a handle over three things kerf already has: a reactive `route` signal (`{ path, params, query, hash }`), `delegate()`-based `<a href>` link interception, and a keyed **outlet** — `router.outlet()` renders the matched route in a `data-key`ed wrapper, so kerf's keyed morph **replaces the page wholesale on a route change** (fresh DOM) and **reconciles in place on a same-route param change** (preserving scroll / focus). Route patterns are static, `:param`, a trailing `*rest` wildcard, and `*` catch-all; the handle also gives `navigate(path, { replace?, state? })`, `back()`/`forward()`, `match(pattern)` / `activeClass(pattern, className)` reactive active-link helpers, hash **or** history mode, an optional base path, and `dispose()`. Link interception is automatic (same-origin, left-click, no modifier/`target`/`download`, opt out per-link with `data-router-ignore` / `rel="external"` or globally with `interceptLinks: false`). **Deliberately scoped** — no nested layouts, data loaders, lazy routes, guards, or SSR matching; compose those with kerf primitives (`resource` for loading, an `effect` on `route` for guards). The kerf **core stays router-free** — this is opt-in and tree-shakeable, adding nothing to the main barrel until imported, and docs/1's "Not a router" is about the runtime. See [`docs/20-router.md`](docs/20-router.md).
|
|
166
3504
|
|
|
167
3505
|
## [4.3.0] - 2026-08-22
|
|
168
3506
|
|
|
169
|
-
|
|
170
|
-
|
|
171
3507
|
- KF-529: refresh README for the 4.3 cycle (prep-major-release) (`909c82a`)
|
|
172
3508
|
- KF-530: extract promise-dialog helpers into overlay-dialogs.ts (`5d4ac38`)
|
|
173
3509
|
- KF-528: sync llms.txt with docs/19 + 4.3 features (`1d9c004`)
|
|
174
3510
|
|
|
175
3511
|
- **`kerfjs/overlay` gains opt-in native top-layer backing (`native: true`).** Every overlay surface (`overlay`, `confirm`, `prompt`, `form`, `choice`, `popover`, `tooltip`) now takes `native?: boolean` (default `false`). When `true` and the engine supports it, a **modal** surface (`trap: true`) is hosted in a `<dialog>` opened with `.showModal()` — real document inerting (pointer + focus + AT) and guaranteed stacking above any `z-index` — and a **non-modal** surface (`trap: false`) uses the **Popover API** (`[popover]` + `showPopover()`). Feature-detected (`HTMLDialogElement.prototype.showModal`, `HTMLElement.prototype.showPopover`), falling back to today's plain `<div>` where unsupported, so `native: true` is always safe to pass. The `render` slot + promise API are unchanged — kerf just hosts your markup in a `<dialog>` / `[popover]`. **Opt-in on purpose:** the native elements carry UA default styles (a `::backdrop`, centering, border, padding) that kerf does **not** reset (a reset would violate the zero-CSS contract) — style the element and its `::backdrop` via `className` (`.kerf-overlay::backdrop { … }`, the stable contract); and `container` becomes a visual no-op in native mode (the top layer ignores DOM position). See [`docs/19-native-overlay-backing.md`](docs/19-native-overlay-backing.md).
|
|
176
|
-
- **`bindList` virtualization gains a `content-visibility` mode.** `virtualize: { rowHeight, mode: 'content-visibility' }` is a second virtualization strategy alongside the default `mode: 'window'` (today's JS windowing). It keeps **every** row in the DOM and sets `content-visibility: auto` + `contain-intrinsic-size: 0 <rowHeight>px` on each row, so a supporting engine (Chromium, Safari 18) skips the
|
|
3512
|
+
- **`bindList` virtualization gains a `content-visibility` mode.** `virtualize: { rowHeight, mode: 'content-visibility' }` is a second virtualization strategy alongside the default `mode: 'window'` (today's JS windowing). It keeps **every** row in the DOM and sets `content-visibility: auto` + `contain-intrinsic-size: 0 <rowHeight>px` on each row, so a supporting engine (Chromium, Safari 18) skips the _layout/paint_ of off-screen rows while **all rows stay findable** — find-in-page (Cmd/Ctrl+F), the accessibility tree, and anchor links / `scrollIntoView` all work on any row (the exact guarantee `mode: 'window'` can't give, since it removes off-window rows from the DOM). The `mode` choice is the app's and it's about list size: pick `'content-visibility'` for medium lists where findability beats the node ceiling, keep `'window'` for very large (100k-row) lists. In this mode `rowHeight` is only the `contain-intrinsic-size` placeholder (no windowing math), `setHeight` / `observeRowHeights` are no-ops (the browser owns measurement), `minRows` is ignored (all rows already render), and no scroll listener / `ResizeObserver` is installed — while `handle.container` / `containerClass` / `containerId` still work. There is deliberately **no feature detection**: on an engine without `content-visibility` the CSS is inert, so all rows still render (correct, still findable) — only the off-screen-skip optimization is absent. See [`docs/17-list-virtualization.md`](docs/17-list-virtualization.md) §17.11.
|
|
177
3513
|
- **Docs: `bindList` virtualization findability/a11y tradeoff is now a first-class caveat.** Off-window rows are removed from the DOM (not just hidden), so with `virtualize` set, find-in-page (Cmd/Ctrl+F), screen readers / the accessibility tree, and anchor links / `scrollIntoView` reach only the visible window. New `docs/17-list-virtualization.md` §17.10 spells out the consequences and the guidance (don't virtualize, or use `minRows` above the list length, when full findability matters more than the DOM node ceiling), and the `bindList` JSDoc + `docs/8-api-reference.md` §8.11 carry the same note. Behavior unchanged — documentation only.
|
|
178
3514
|
- **State-preserving row moves via `moveBefore()` (transparent optimization).** When a keyed list reorders — `each()` (snapshot and granular paths), `bindList`, and `morph()`'s keyed / positional / list-marker moves — kerf now relocates an already-connected row with `Node.prototype.moveBefore()` where the engine supports it (Chromium 133+, spreading to other engines), falling back to `insertBefore()` everywhere else. `moveBefore()` is an atomic move: the node is never disconnected, so a moved row keeps its focus, text selection, `<iframe>` document state, playing media, running CSS transitions/animations, and open `popover`/`dialog` state across the reorder — richer state than the existing focus snapshot in the reconciler could ever restore, and it needs no snapshot at all where it runs. No API change and no behavior change on engines without `moveBefore()`; the focus-preservation snapshot stays in place for them. Fresh (not-yet-connected) rows still use `insertBefore()` — only genuine moves of connected rows take the new path. See [`docs/18-state-preserving-moves.md`](docs/18-state-preserving-moves.md).
|
|
179
3515
|
|
|
180
3516
|
## [4.2.0] - 2026-08-20
|
|
181
3517
|
|
|
182
|
-
|
|
183
|
-
|
|
184
3518
|
- Added a **Virtual list** example app — a 10,000-row virtualized list showcasing the companion subpaths together: `kerfjs/list` viewport virtualization (only a screenful in the DOM), `kerfjs/timing` debounced search, and `kerfjs/overlay` confirm-to-delete with a toast. Includes a live "in the DOM" counter that stays flat as you scroll all 10,000 rows.
|
|
185
3519
|
- Expanded the README with a companion-subpaths spotlight covering `list`, `overlay`, `async`, `scope`, `timing`, `remount`, `attach`, and `actions`, with `bindList` fixed and measured-height virtualization examples.
|
|
186
3520
|
- Corrected the complete-apps index to accurately describe the eight standalone showcase apps and note that the cart and counter-store apps live in the migration guides.
|
|
@@ -194,86 +3528,70 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
|
194
3528
|
- **New `kerfjs/remount` subpath** — `remountOn(parent, key, render)`, the opposite of kerf's morph-by-default: **replace** a subtree wholesale when `key` changes instead of morphing it. Names the hand-rolled `data-key={`gen-${n}`}` + `data-morph-skip` counter trick, for library-owned subtrees (a highlighted diff, a chart, an editor) that must tear down and re-initialize on fresh DOM. `key` is a signal or a thunk `() => K`; an unchanged key (including a thunk whose inputs moved but whose value stayed equal) leaves the subtree alone, so per-row reactivity inside `render` still updates in place. An optional `onMount(root)` callback runs after each (re)mount with the live subtree — the place to bind an imperative widget (`kerfjs/attach`) to the fresh DOM; returning `attach`'s disposer from it makes teardown synchronous. `remountOn` owns `parent`'s children and returns a disposer. Optional and tree-shakeable.
|
|
195
3529
|
- **New `kerfjs/timing` subpath** — the `let timer; clearTimeout(timer); timer = setTimeout(…)` pattern every app hand-rolls, blessed with disposer-shaped ergonomics. `debounce(fn, ms)` is trailing-edge (runs once `ms` after calls stop, latest args); `throttle(fn, ms)` is leading-plus-trailing (fires immediately, then at most once per `ms`, collapsing a burst to one trailing call). Both return a callable with `cancel()` / `flush()`. `debouncedSignal(source, ms)` is a read-only signal that trails `source` by `ms` so it composes inside the reactive graph (`computed`/`effect`/`mount`) instead of beside it. `debounce`/`throttle` are dependency-free; `debouncedSignal` pulls in signals only (no render core). Optional and tree-shakeable; tiny.
|
|
196
3530
|
- **New `kerfjs/scope` subpath** — tie disposers to a DOM element's lifetime, so append-heavy UIs stop leaking detached-but-subscribed effects/listeners. `disposeScope(el)` returns a WeakMap-keyed, accumulating scope whose `add(disposer)` (plus convenience `mount` / `effect` / `delegate` wrappers that register their own disposer) collects teardown; `dispose()` runs it all best-effort and idempotently. `disposeSubtree(root)` sweeps a subtree before removal; `observeRemovals(root)` installs one `MutationObserver` that auto-disposes on removal. No module-level mutable state. Optional and tree-shakeable.
|
|
197
|
-
- **New `kerfjs/overlay` subpath** — the blessed modal/overlay + dismiss manager that every real kerf app hand-rolls. `overlay(content, options?)` appends a wrapper, `mount()`s content inside it (owning the disposal), wires dismissals (Escape / backdrop / outside-click, with `outsideIgnore`), a focus trap (`role="dialog"` / `aria-modal`, Tab wrap-around, restore-focus-on-close), and returns `{ el, close(result?), result }`. `confirm(message, options?)` is a promise-based `window.confirm` replacement, and `prompt(message, options?)` → `Promise<string | null>` its `window.prompt` counterpart (both globals are no-ops in Tauri webviews); `form(fields, options?)` → `Promise<Record<string, string> | null>` collects a two-or-three-field dialog. `choice<R>(message, actions, options?)` → `Promise<R | null>` is the **N-way** sibling of `confirm` — one button per action resolves that action's `value` (or `null` on dismissal), and `options.defaultValue` makes **Enter** (anywhere in the dialog) resolve a default action (the "global Enter-to-confirm" model) without holding the overlay handle. `prompt`/`form` submit on Enter and take an inline `validate`; all auto-escape their content. `confirm` / `prompt` / `form` also accept a **`render` slot option** for design-system teams — return your own markup and spread the provided `ok`/`cancel` (+ `input`/`error`) wiring onto it; kerf keeps owning the promise, `validate`, Enter-submit, dismiss, focus-trap, and focus-restore, so you adopt the batteries-included dialogs without a CSS rewrite. `popover(anchor, content, options?)` → `OverlayHandle` is a non-modal **anchored** overlay: it positions the content relative to `anchor` (below by default, flipping above on viewport overflow, clamped horizontally), defaults to dismiss-on-outside with the anchor exempt, and repositions on scroll / resize. `popover`'s placement core is also exported standalone: **`positionAnchored(el, anchor, options?)`** (one-shot) and **`autoReposition(el, anchor, options?)`** (keeps an element positioned on scroll/resize, returns a disposer) position
|
|
3531
|
+
- **New `kerfjs/overlay` subpath** — the blessed modal/overlay + dismiss manager that every real kerf app hand-rolls. `overlay(content, options?)` appends a wrapper, `mount()`s content inside it (owning the disposal), wires dismissals (Escape / backdrop / outside-click, with `outsideIgnore`), a focus trap (`role="dialog"` / `aria-modal`, Tab wrap-around, restore-focus-on-close), and returns `{ el, close(result?), result }`. `confirm(message, options?)` is a promise-based `window.confirm` replacement, and `prompt(message, options?)` → `Promise<string | null>` its `window.prompt` counterpart (both globals are no-ops in Tauri webviews); `form(fields, options?)` → `Promise<Record<string, string> | null>` collects a two-or-three-field dialog. `choice<R>(message, actions, options?)` → `Promise<R | null>` is the **N-way** sibling of `confirm` — one button per action resolves that action's `value` (or `null` on dismissal), and `options.defaultValue` makes **Enter** (anywhere in the dialog) resolve a default action (the "global Enter-to-confirm" model) without holding the overlay handle. `prompt`/`form` submit on Enter and take an inline `validate`; all auto-escape their content. `confirm` / `prompt` / `form` also accept a **`render` slot option** for design-system teams — return your own markup and spread the provided `ok`/`cancel` (+ `input`/`error`) wiring onto it; kerf keeps owning the promise, `validate`, Enter-submit, dismiss, focus-trap, and focus-restore, so you adopt the batteries-included dialogs without a CSS rewrite. `popover(anchor, content, options?)` → `OverlayHandle` is a non-modal **anchored** overlay: it positions the content relative to `anchor` (below by default, flipping above on viewport overflow, clamped horizontally), defaults to dismiss-on-outside with the anchor exempt, and repositions on scroll / resize. `popover`'s placement core is also exported standalone: **`positionAnchored(el, anchor, options?)`** (one-shot) and **`autoReposition(el, anchor, options?)`** (keeps an element positioned on scroll/resize, returns a disposer) position _your own_ element with no overlay lifecycle. **`tooltip(anchor, content, options?)`** is a hover/focus-triggered, non-modal, auto-hiding tooltip built on them. `toast(content, options?)` now returns a **`ToastHandle` (`{ el, dismiss }`)** instead of a bare dismiss function, so callers can inspect the node, wire an action button, or run entrance/exit transitions; new options: `mode: 'replace'` (collapse a rapid sequence to the latest) with `collapse: 'fade'` (default — run the prior toast's exit transition, good for a stacking region) or `'instant'` (remove it synchronously, what a single centered slot wants so messages never cross-fade in place), `variant` (`'info'`/`'success'`/`'warning'` → a `${className}--${variant}` accent class), `enterClass` (added on the next animation frame for a CSS entrance) and `exitClass` + `exitDuration` (CSS owns the exit — on dismiss the `enterClass` is **removed** so `exitClass` needn't out-specify it, and a symmetric single-class fade works with just `enterClass` + `exitDuration`; the node is removed after the delay). `dismiss({ instant: true })` removes the toast **synchronously** (skipping the exit transition), and `mode: 'replace'` `collapse: 'instant'` also force-removes a toast that is already mid-fade — so an action button that dismisses itself and shows a replacement in a single centered slot doesn't cross-fade the two. **Breaking (beta):** `toast()`'s return type changed from `() => void` to `{ el, dismiss }` — call `toast(...).dismiss()` or destructure `{ dismiss }`. Structural only — kerf ships no CSS. Optional and tree-shakeable; shares the core with the main barrel via code-splitting.
|
|
198
3532
|
- **New `kerfjs/actions` subpath** — the blessed delegated action-table helper. `action(value)` returns a `data-action` `AttrSpec` (a thin specialization of `attr()`); `delegateActions(root, eventType, table, options?)` wires a whole table of `data-action` handlers with one delegated listener (built on `delegate()`) and returns a disposer. Formalizes the most-reinvented idiom in real kerf apps — one `attr('data-action', …)` table as the single source of truth for both the JSX attribute and the delegate dispatch. Optional and tree-shakeable; adds nothing to the main barrel.
|
|
199
3533
|
|
|
200
3534
|
## [4.1.1] - 2026-08-14
|
|
201
3535
|
|
|
202
|
-
|
|
203
|
-
|
|
204
3536
|
- Added a CDN / importmap quickstart (`docs/6-jsx-runtime.md` §6.11.1) covering three no-install ways to load kerf from an ESM CDN: a direct `esm.sh` import, and jsDelivr / unpkg behind an importmap that also maps `@preact/signals-core`. Explains why a raw `dist/*.js` path fails (its unrewritten bare `@preact/signals-core` import won't resolve in the browser) and recommends pinning to a major version.
|
|
205
3537
|
- Updated the README no-build example to use version-pinned CDN URLs (`kerfjs@4`) and noted that jsDelivr / unpkg need an importmap while esm.sh works with a direct import.
|
|
206
3538
|
|
|
207
3539
|
## [4.1.0] - 2026-07-31
|
|
208
3540
|
|
|
209
|
-
|
|
210
|
-
|
|
211
3541
|
- ESLint 10 is now supported: `eslint-plugin-kerfjs` declares `peerDependencies.eslint` as `^9.0.0 || ^10.0.0`, and every named major is exercised by the rule suite in CI.
|
|
212
3542
|
- The plugin now runs its rule suite against each supported ESLint major via `npm run test:eslint-matrix`, which also fails if the declared peer range, the tested set, and the CI matrix disagree — or if the range is left open-ended.
|
|
213
3543
|
|
|
214
|
-
|
|
215
3544
|
- **ESLint 8 is no longer supported by `eslint-plugin-kerfjs`.** The package is ESM-only and ESLint 8 resolves `.eslintrc` plugins with `require()`, so `extends: ["plugin:kerfjs/…"]` could never load it.
|
|
216
3545
|
- **Legacy `.eslintrc` configuration is documented as unsupported.** Use flat config (`eslint.config.js`); the `legacy-recommended` export remains in the package but is unreachable through any config system and should be treated as deprecated.
|
|
217
3546
|
|
|
218
|
-
|
|
219
3547
|
- Generated Hot Sheet skill and rule files no longer hardcode a machine's local API port or shared secret. The curl fallbacks read `$HOTSHEET_PORT` / `$HOTSHEET_SECRET` from `.hotsheet/settings.local.json` and `.hotsheet/secret.json` instead, with `.hotsheet/settings.json` as the fallback for older projects.
|
|
220
3548
|
- A new `npm run check:audit` gate runs `npm audit --omit=dev --audit-level=high` against the published dependency tree and is wired into the pre-push `check:full` gate.
|
|
221
3549
|
|
|
222
|
-
|
|
223
3550
|
- Test tooling moved to vitest 4 and ESLint 10; coverage thresholds were recalibrated to 98.5% branches / 99.5% statements (lines and functions stay at 100%) after vitest 4's sharper AST-based coverage mapping resolved seventeen previously-miscredited defensive branches.
|
|
224
3551
|
- Removed the `hs-m` marketing-ticket skill and Cursor rule.
|
|
225
3552
|
|
|
226
3553
|
## [4.0.0] - 2026-07-28
|
|
227
3554
|
|
|
228
|
-
|
|
229
|
-
|
|
230
3555
|
- `draggable`, `spellCheck`, and `contentEditable` no longer accept booleans — they are enumerated HTML attributes, so write the keyword string (`draggable="true"`, `spellCheck="false"`). The boolean forms rendered markup that meant the opposite of what was written; real boolean attributes like `hidden`/`checked`/`disabled` are unchanged.
|
|
231
3556
|
- `<select value>` / `<textarea value>` (and their `defaultValue` forms) no longer typecheck — neither element has a `value` content attribute, so kerf was emitting markup no browser reads. Use `<option selected>` and `<textarea>{draft}</textarea>`.
|
|
232
|
-
- Lowercase `autofocus` no longer accepts `"true"` / `"false"` — it is a real boolean attribute, so `autofocus="false"` turned autofocus
|
|
233
|
-
|
|
3557
|
+
- Lowercase `autofocus` no longer accepts `"true"` / `"false"` — it is a real boolean attribute, so `autofocus="false"` turned autofocus _on_. Use `autofocus={false}` or omit it.
|
|
234
3558
|
|
|
235
3559
|
- `href="javascript:void(0)"` and its five sibling spellings are no longer dropped by the URL screen. Dropping the `href` unmade the anchor — it lost `:link` styling, keyboard focus, and its pointer cursor. Matching is against the whole normalized value, so nothing can ride along after an inert body.
|
|
236
3560
|
- `defaultSelected` rendered as `defaultselected`, an attribute no browser reads, so the option it named was never pre-selected. It now correctly emits `selected`.
|
|
237
3561
|
|
|
238
|
-
|
|
239
3562
|
- Typed JSX gained a wide set of modern attributes: globals `inert`, `popover`, `nonce`, `part`/`exportparts`, `enterKeyHint`, `translate`, `autocorrect`, and the full microdata family; per-element `<button popoverTarget/popoverTargetAction/command>`, `<input popoverTarget/popoverTargetAction>`, `<form rel>`, `<source width/height>`, and `writingsuggestions`.
|
|
240
3563
|
- `<button command>` is now typed to the spec keywords (`show-modal`, `close`, `request-close`, `toggle-popover`, `show-popover`, `hide-popover`) plus any `--custom` command, catching a custom command written without its required `--` prefix.
|
|
241
3564
|
- `<a download>` and `<area download>` accept the bare boolean form as well as a string filename, so `<a href="/report.pdf" download>` compiles.
|
|
242
3565
|
|
|
243
|
-
|
|
244
3566
|
- The advertised bundle size is corrected everywhere: ~12 KB min+gzip for a realistic import, ~13 KB with `arraySignal` (previously stated as ~11/~12 KB, and ~6.1 KB in the Cursor rules). Every migration page's delta row was recomputed against the new figure.
|
|
245
3567
|
- The JSX runtime doc gained a section on enumerated vs. boolean attributes, and the API reference now records where the JSX types come from (WHATWG HTML Living Standard + SVG 2, not another framework's property table).
|
|
246
3568
|
- The dev-warning sections in the dev-warnings doc were renumbered by family so the `11.2.N` headings run in document order; cross-references elsewhere in the docs were updated to match.
|
|
247
3569
|
|
|
248
|
-
|
|
249
|
-
- The bundle-size check now gates the *prose* as well as the build: every place the docs advertise a size is matched against the measured figure, and a reworded claim that stops matching fails rather than going silently unchecked.
|
|
3570
|
+
- The bundle-size check now gates the _prose_ as well as the build: every place the docs advertise a size is matched against the measured figure, and a reworded claim that stops matching fails rather than going silently unchecked.
|
|
250
3571
|
- New repo checks wired into `npm run check`: `check:docs:dev-warns` (the dev-warning doc and `ENV_NAME` must name the same set, with monotonic section numbers), `check:design-rule-5` (every top-level `let` in `src/` must be accounted for by the documented rule), and `check:skills` (a skill file restating a threshold its owner disagrees with fails).
|
|
251
3572
|
|
|
252
3573
|
## [3.0.0] - 2026-07-27
|
|
253
3574
|
|
|
254
|
-
|
|
255
|
-
|
|
256
3575
|
- **kerf no longer infers development mode — add one line to your entry to keep the dev diagnostics.**
|
|
257
3576
|
|
|
258
3577
|
```js
|
|
259
|
-
if (import.meta.env.DEV) await import(
|
|
260
|
-
if (process.env.NODE_ENV !==
|
|
3578
|
+
if (import.meta.env.DEV) await import("kerfjs/dev"); // Vite
|
|
3579
|
+
if (process.env.NODE_ENV !== "production") await import("kerfjs/dev"); // webpack / Node
|
|
261
3580
|
```
|
|
262
3581
|
|
|
263
3582
|
Without it you get production shape: no dev warnings, no read-only `defineStore` `get()`
|
|
264
3583
|
snapshot, and a screened dangerous URL warns-and-drops instead of throwing. Nothing else
|
|
265
3584
|
changes, and if you never used the dev warnings you get a smaller bundle for free.
|
|
266
3585
|
|
|
267
|
-
**Why it changed.** kerf inferred its own dev/prod mode by reading `globalThis.process?.env?.NODE_ENV`. Bundlers substitute the
|
|
3586
|
+
**Why it changed.** kerf inferred its own dev/prod mode by reading `globalThis.process?.env?.NODE_ENV`. Bundlers substitute the _bare_ `process.env.NODE_ENV` token and never create a `globalThis.process` object for browser targets, so that read was `undefined`, `undefined !== 'production'` was `true`, and every production browser build silently took the development path. Consequences that were shipping: every `defineStore` `get()` returned a deep read-only `Proxy` (an allocation on every store read), a screened `javascript:`/`data:` URL **threw** instead of the documented warn-and-drop, and the always-on list-key warnings printed to production consoles. Server/Node builds, where `process` exists, were unaffected.
|
|
268
3587
|
|
|
269
3588
|
Removing the inference also shrinks production bundles by **~4.7 KB min+gzip (27%)** — a realistic import (`signal`/`computed`/`effect`/`batch`/`mount`/`each`/`delegate`) goes from 16.91 KB to **12.24 KB**. Previously the dev-warning modules were imported unconditionally by `mount()`/`each()` and gated at runtime, so they shipped to production regardless of build mode and no amount of tree-shaking could reclaim them. With the dev entry absent they are unreachable, and the `import()` statement itself is eliminated — the chunk is never emitted, let alone fetched.
|
|
270
3589
|
|
|
271
3590
|
`globalThis.KERF_DEV` is no longer consulted — not importing the dev entry is now the (compile-time) way to opt out. One ordering note: `signal()` picks its constructor at creation time, so put the import first if you rely on the untracked-signal warning.
|
|
272
3591
|
|
|
273
|
-
- The `KERF_DEV_WARN_*` diagnostics no longer consult `NODE_ENV` or `globalThis.KERF_DEV` at all. Whether they run is decided in exactly one place: whether you imported `kerfjs/dev`. The previous release stopped kerf's core from inferring dev mode but left a second, inherited gate inside each warner, so a Node/SSR consumer who
|
|
274
|
-
|
|
3592
|
+
- The `KERF_DEV_WARN_*` diagnostics no longer consult `NODE_ENV` or `globalThis.KERF_DEV` at all. Whether they run is decided in exactly one place: whether you imported `kerfjs/dev`. The previous release stopped kerf's core from inferring dev mode but left a second, inherited gate inside each warner, so a Node/SSR consumer who _deliberately_ installed the diagnostics under `NODE_ENV=production` got silence — and `globalThis.KERF_DEV = false` still silenced warnings the consumer had explicitly opted into. Both are gone; each warning is now gated only by its own env var. If you were using `globalThis.KERF_DEV` to turn diagnostics off, remove the dev import instead (which is also what sheds the ~4.7 KB from your bundle).
|
|
275
3593
|
|
|
276
|
-
- **New:** `each()` accepts an options object — `each(items, render, { cacheKey, key })` — and `key` gives a list a **stable identity**. Without one a list is identified by its position among the `each()` calls in a render, so adding or removing a conditional list above it made kerf rebuild it from scratch: rows lost their DOM nodes, and with them focus, scroll position and in-progress IME composition. Keying a list removes that dependency; because a keyed list doesn't occupy a positional slot, keying just the
|
|
3594
|
+
- **New:** `each()` accepts an options object — `each(items, render, { cacheKey, key })` — and `key` gives a list a **stable identity**. Without one a list is identified by its position among the `each()` calls in a render, so adding or removing a conditional list above it made kerf rebuild it from scratch: rows lost their DOM nodes, and with them focus, scroll position and in-progress IME composition. Keying a list removes that dependency; because a keyed list doesn't occupy a positional slot, keying just the _conditional_ list usually stabilizes its siblings too. The existing three-argument `each(items, render, cacheKey)` form is unchanged. In development kerf now warns once per list when it detects such a shift and names the fix.
|
|
277
3595
|
|
|
278
3596
|
- **`kerfjs/dev` now exports `enableWarnings()`** — and it fixes a defect: until now, none of the
|
|
279
3597
|
`KERF_DEV_WARN_*` diagnostics could be switched on in a browser at all. Every one of them read `globalThis.process.env`, which does not exist in a browser realm — and a bundler `define` cannot reach it either, because the read goes through `globalThis.process` into a local binding rather than the substitutable `process.env.X` token. So in a Vite/webpack dev server, the environment where these warnings are most wanted, the entire opt-in family was permanently and silently off. Only Node/SSR (and kerf's own vitest suite, which is why nothing caught it) could turn any of them on.
|
|
@@ -282,8 +3600,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
|
282
3600
|
|
|
283
3601
|
```js
|
|
284
3602
|
if (import.meta.env.DEV) {
|
|
285
|
-
const dev = await import(
|
|
286
|
-
dev.enableWarnings({
|
|
3603
|
+
const dev = await import("kerfjs/dev");
|
|
3604
|
+
dev.enableWarnings({
|
|
3605
|
+
staleBinding: true,
|
|
3606
|
+
narrowSet: true,
|
|
3607
|
+
invariants: "throw",
|
|
3608
|
+
});
|
|
287
3609
|
}
|
|
288
3610
|
```
|
|
289
3611
|
|
|
@@ -297,8 +3619,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
|
297
3619
|
|
|
298
3620
|
- New opt-in dev warning `KERF_DEV_WARN_LIST_REBIND=1`: fires (once per list) when an `each()` list's container is rebuilt by the morph — an ancestor's tag changed across renders, so the subtree was replaced and the list self-healed by re-binding and repopulating. The recovery is correct but discards row DOM state (focus, scroll, IME, imperative listeners); the warning names the list and points at keeping ancestor tags stable. Follows the standard `KERF_DEV_WARN_*` family rules: off by default, dev-mode only, zero production cost.
|
|
299
3621
|
|
|
300
|
-
|
|
301
|
-
- `KERF_DEV_WARN_UNTRACKED_SIGNALS=1` now tells you what it can and cannot see. The warning picks its machinery when a signal is *created*, so it only covers signals created after `kerfjs/dev` is installed — and because static imports are hoisted above a top-level `await import('kerfjs/dev')`, the module-scope signals it most wants to catch are usually created first. Previously that failed silently: you set the env var, saw nothing, and concluded your code was clean. Opting in now prints the coverage boundary once, along with the fix (make `import 'kerfjs/dev'` the first static import of a dev-only entry file). The boundary itself can't be removed — `Signal.prototype`'s `value` accessor is non-configurable, so already-created signals can't be retro-fitted without kerf keeping a registry of every signal, which production would pay for.
|
|
3622
|
+
- `KERF_DEV_WARN_UNTRACKED_SIGNALS=1` now tells you what it can and cannot see. The warning picks its machinery when a signal is _created_, so it only covers signals created after `kerfjs/dev` is installed — and because static imports are hoisted above a top-level `await import('kerfjs/dev')`, the module-scope signals it most wants to catch are usually created first. Previously that failed silently: you set the env var, saw nothing, and concluded your code was clean. Opting in now prints the coverage boundary once, along with the fix (make `import 'kerfjs/dev'` the first static import of a dev-only entry file). The boundary itself can't be removed — `Signal.prototype`'s `value` accessor is non-configurable, so already-created signals can't be retro-fitted without kerf keeping a registry of every signal, which production would pay for.
|
|
302
3623
|
|
|
303
3624
|
- An `each()` of `<tr>` written directly inside `<table>` now fails with a clear error instead of silently duplicating rows: the HTML parser inserts a `<tbody>` around the rows, which kerf cannot bind through. The message names both tags and shows the supported shape (`<table><tbody>{each(...)}</tbody></table>`). Previously this also mis-reported the rows as missing `data-key`.
|
|
304
3625
|
|
|
@@ -306,8 +3627,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
|
306
3627
|
|
|
307
3628
|
- Toolchain: the repo now type-checks with the native **TypeScript 7** compiler across every gate (`typecheck`, the dist `.d.ts` typing gates, the docs code-block compile — a full-repo `tsc --noEmit` now takes ~0.3 s), with `typescript@6` (the JS-API bridge release) retained for tsup's `.d.ts` emit and typescript-eslint, which still require the JS compiler API. `@typescript-eslint/*` bumped to 8.65. No shipped-code changes — `dist/` output is unaffected.
|
|
308
3629
|
|
|
309
|
-
|
|
310
|
-
- Fixed: passing a **function** as an `each()` item through an `arraySignal` insert/update (an unusual mistake, but functions are valid `WeakMap` keys so the per-item cache silently accepted them) rendered the row and then threw `each(): items must be objects…` on a *later, unrelated* re-render — far from the cause. The granular path now enforces the same objects-only item contract the snapshot path does, so the error is thrown on the render the offending mutation triggered, naming the type and index. Primitive items already behaved this way; functions now match.
|
|
3630
|
+
- Fixed: passing a **function** as an `each()` item through an `arraySignal` insert/update (an unusual mistake, but functions are valid `WeakMap` keys so the per-item cache silently accepted them) rendered the row and then threw `each(): items must be objects…` on a _later, unrelated_ re-render — far from the cause. The granular path now enforces the same objects-only item contract the snapshot path does, so the error is thrown on the render the offending mutation triggered, naming the type and index. Primitive items already behaved this way; functions now match.
|
|
311
3631
|
|
|
312
3632
|
- `arraySignal.update(i, fn)` now works when `fn` mutates the row object and returns it (not only when it returns a fresh object). Previously such a same-ref update rendered correctly in one list but left every other view of the same signal — a second list, a second `mount()`, a `filter()`ed plain-array view — permanently stale, and was lost outright when the update was batched with a selection change or a `replace()`. kerf now tracks a per-item content version so the change reaches every consumer. Returning a fresh object remains the idiomatic style; both are supported. (Fixed in the same line of work: the per-item version tracking briefly made `arraySignal.update()` throw on a signal of primitives — `arraySignal<number>` used as a plain signal — because a primitive can't key the internal version map; primitive items are now simply skipped, since only object rows are ever memoized.)
|
|
313
3633
|
|
|
@@ -319,13 +3639,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
|
319
3639
|
|
|
320
3640
|
- Fixed: an `arraySignal.update()` that mutated a row object in place (returning the same reference) could be silently reverted to its old content by the next unrelated re-render. The granular update path now keeps kerf's per-row HTML cache in sync with what it rendered, so the two never disagree. (Immutable updates — returning a fresh object — were unaffected, and remain the recommendation.)
|
|
321
3641
|
|
|
322
|
-
- Fixed: showing an empty conditionally-rendered `each()` list in the same batch as an update to a
|
|
3642
|
+
- Fixed: showing an empty conditionally-rendered `each()` list in the same batch as an update to a _sibling_ list could empty the sibling entirely — it rendered zero rows. When the conditional list reappeared, its list-marker comment landed next to the sibling's, and the diff overwrote the sibling marker's internal id with the reappearing one's, so the sibling's binding could no longer find its own marker. Marker comments (kerf's internal list and binding anchors) now pair only with the identical marker, never with a different one that happens to be the same kind. Ordinary comments in your markup are unaffected.
|
|
323
3643
|
|
|
324
3644
|
- Fixed: when an element rendered by a condition came back, the diff could pair it with an unrelated sibling that happened to have the same tag, and then whatever protects that sibling's contents kept the wrong contents alive inside it. A `data-morph-skip` widget **swallowed** the reappearing element — its content never rendered — and the widget was duplicated, which for a library-owned subtree (an editor, a chart, a terminal) means a second live instance attached to a node the library has no reference to. A `data-morph-preserve` child ended up under the foreign host and appeared twice. A bound hole's text leaked into the reappearing element and rendered twice. Three rules now gate that pairing: an element with an `id`/`data-key` is only ever matched to a live element with the same key; a `data-morph-skip` element only ever matches another one (so a library-owned subtree is never adopted as a stand-in, whether or not you use keys); and a comment anchoring kerf's own state only matches an anchor of the same kind. Ordinary elements without a key still match positionally exactly as before.
|
|
325
3645
|
|
|
326
|
-
- Fixed: when the number of `each()` calls in a render changed — a conditional list appearing or disappearing — a
|
|
3646
|
+
- Fixed: when the number of `each()` calls in a render changed — a conditional list appearing or disappearing — a _surviving_ list could render the departed list's rows, or render its own rows inside the wrong container. Lists without a `key` are identified by their position among the `each()` calls, and both the per-item HTML cache and the live list binding were being read as belonging to whichever list now held that position. Two lists over the same collection hit each other's cache exactly, so nothing could detect it from the data. A shift now discards that state and re-renders, which is what the documentation already described it as costing: a rebuild, never wrong output. Lists given a `key` are unaffected, and a render that doesn't change the call count is unaffected. One related improvement falls out: an unrelated list no longer loses its row nodes when a nested `each()` shifts the count.
|
|
327
3647
|
|
|
328
|
-
- Fixed: a row added to an `each()` list could land in the wrong place whenever the list wasn't the last thing inside its parent. A list ends at its last row, but kerf was looking for the next
|
|
3648
|
+
- Fixed: a row added to an `each()` list could land in the wrong place whenever the list wasn't the last thing inside its parent. A list ends at its last row, but kerf was looking for the next _element_ after it and skipping everything else on the way — so static content following the list (a footer row, a totals line, an "add item" control) got jumped, and a new row appeared after it instead of before. The same skip crossed a neighboring list's internal anchor: with two `each()` lists in one parent, rows from the first could be placed inside the second's region, and when both lists started empty their rows came out **in the wrong order** — the second list's rows rendered first. Both were correct on the initial paint and only went wrong on a later update, which made them read as intermittent. Lists now anchor on the next node of any kind, so a list's rows always stay within its own region.
|
|
329
3649
|
|
|
330
3650
|
- Fixed: an `each()` list inside an `<svg>` whose row markup contained an apostrophe (or anything else the serializer writes back differently) failed to mount at all, with a self-contradictory error. Also fixed: `each({ key })` now validates the key, so a key containing an HTML comment terminator can no longer break out of the list's internal marker and put markup in the page.
|
|
331
3651
|
|
|
@@ -337,7 +3657,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
|
337
3657
|
|
|
338
3658
|
- Fixed: a controlled `checked` / `value` on an `each()` row's own top-level element could stay visibly stale after the user had interacted with it — the row reconciler's attribute-only fast path wrote the attribute without syncing the live property, so whether the control obeyed your data depended on which internal route the update happened to take.
|
|
339
3659
|
|
|
340
|
-
- Fixed: when a conditionally-rendered `each()` list is added or removed, a sibling list could render the
|
|
3660
|
+
- Fixed: when a conditionally-rendered `each()` list is added or removed, a sibling list could render the _other_ list's rows — a batched "hide one list and push to another" applied the queued update to the wrong list's DOM. Lists now verify which data a pending update belongs to before applying it, and rebuild from their own items when it doesn't match.
|
|
341
3661
|
|
|
342
3662
|
- Fixed: `each()` rows inside an `<svg>` root were re-parsed in the HTML namespace on every update, so rows added or structurally changed after the first render were invisible in the browser — the initial picture looked right, which made it read as a rendering flake. Row parsing now follows the list parent's namespace (rows under `<foreignObject>` correctly stay HTML).
|
|
343
3663
|
|
|
@@ -345,92 +3665,72 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
|
345
3665
|
|
|
346
3666
|
- Fixed: anything sitting between a keyed `each()` list's anchor and its rows — a node injected imperatively into the list region — could make a conditional sibling's removal reorder the list, landing a trailing sibling ahead of the rows. A list's row region (anchor through last row) is now treated as one unit by the diff: it moves whole, the diff's cursor steps over it whole, and injected nodes inside it travel along keeping their position relative to the rows.
|
|
347
3667
|
|
|
348
|
-
- A conditional sibling
|
|
3668
|
+
- A conditional sibling _inside_ a keyed `each()` list's parent — a header row that comes and goes above the list — no longer costs the list's rows their DOM identity. The morph now recognizes the list's marker when a sibling shifts it, moving the marker and its rows up as a single unit instead of rebuilding the list, so row nodes, focus, and the caret survive the toggle. (An ancestor tag change, or a same-tag sibling that positionally takes the container's place, still rebuilds the list — give the list's own container a stable `id`/`data-key` if its rows need to survive that.)
|
|
349
3669
|
|
|
350
3670
|
- Fixed: a conditional sibling that shared or positionally shadowed a keyed `each()` list's container could strand the list's rows and then render a duplicate copy of them (e.g. a header `<li>` toggled inside the list's `<ul>`, or a same-tag banner `<ul>` before the list container). The morph can separate the list's marker comment from its still-attached rows; the self-heal now removes any such still-live stranded rows before repopulating, so recovery replaces the rows rather than duplicating them.
|
|
351
3671
|
|
|
352
3672
|
## [2.0.1] - 2026-07-23
|
|
353
3673
|
|
|
354
|
-
|
|
355
|
-
|
|
356
3674
|
- Fixed a `morph()` bug where static text siblings of a fine-grained bound text hole were dropped after a structural re-render (e.g. `<div>{label} / static</div>` collapsing to just the label).
|
|
357
3675
|
|
|
358
|
-
|
|
359
3676
|
- New animated coding-session demo on the getting-started page: watch the canonical counter get typed out, served, clicked in a browser, and live-edited into a todo list.
|
|
360
3677
|
- Added an animated architecture diagram and a link to the docs site from the README.
|
|
361
3678
|
|
|
362
3679
|
## [2.0.0] - 2026-07-23
|
|
363
3680
|
|
|
364
|
-
|
|
365
|
-
|
|
366
3681
|
- `delegateCapture()` now uses `closest()`-style walk-up matching like `delegate()`, passing the matched ancestor to the handler; pass `{ match: 'direct' }` (new `DelegateOptions`) to restore exact-element matching.
|
|
367
3682
|
- The dangerous-URL screen (`javascript:`, `vbscript:`, script-executing `data:` URLs) now throws an error in development instead of only warning. Production behavior is unchanged: warn and drop the attribute.
|
|
368
3683
|
|
|
369
|
-
|
|
370
3684
|
- New `kerfjs/html` tagged template: author kerf UIs with no build step (CDN / importmap, no JSX transform) with runtime semantics identical to JSX — signal holes become fine-grained bindings, attributes and text are escaped and URL-screened the same way.
|
|
371
3685
|
- New no-build example app, **live-poll**, served exactly as authored — an importmap plus one `html`-templated module, with view-source showing the app.
|
|
372
3686
|
- Added `<filter>` to the typed JSX intrinsic elements, so SVG filters compile in JSX-authored code.
|
|
373
3687
|
- Fully-bound mounts are now a documented, test-pinned guarantee: a render that reads no signal `.value` runs exactly once, forever — every update is a direct per-node write.
|
|
374
3688
|
|
|
375
|
-
|
|
376
3689
|
- Controlled form state now survives user interaction: `checked`, `value`, and `selected` DOM properties are synced when the reconciler mutates those attributes, so a clicked checkbox or typed-into input no longer ignores later updates.
|
|
377
3690
|
- Fixed stale fine-grained bindings after `arraySignal.update()`: in-place row updates now re-wire bindings whose signal instance changed, instead of leaving effects reading the old row object forever.
|
|
378
3691
|
|
|
379
|
-
|
|
380
3692
|
- New runtime dev-mode override: set `globalThis.KERF_DEV = false` (or `true`) to control dev mode without a bundler — CDN/importmap apps are no longer stuck in dev mode in production.
|
|
381
3693
|
- Two new opt-in dev warnings: `KERF_DEV_WARN_STALE_BINDING` flags bindings that silently go stale on the byte-equal fast path, and `KERF_DEV_WARN_VALUE_ONLY_RERENDER` flags re-renders whose only changes could have been fine-grained bindings.
|
|
382
3694
|
- `defineStore`'s dev-mode `get()` snapshot now returns a deep read-only proxy instead of freezing the live state: nested mutations like `get().nested.x = 1` are caught too, and they throw a descriptive `TypeError` rather than failing silently.
|
|
383
3695
|
|
|
384
|
-
|
|
385
3696
|
- Docs repositioned around the "values bind, structure re-renders" idiom as the primary way to render dynamic values, across the overview, reactivity guide, and AI assistant configs.
|
|
386
3697
|
- New guide covering the no-build authoring path and example app, plus a documentation-wide accuracy pass (delegate capture semantics, `effect()` cleanup returns, URL-screen behavior, and more).
|
|
387
3698
|
|
|
388
3699
|
## [1.0.2] - 2026-07-22
|
|
389
3700
|
|
|
390
|
-
|
|
391
|
-
|
|
392
3701
|
- Fixed the row-selector demo animation 404ing on the published site — the missing SVG capture is now generated and committed.
|
|
393
3702
|
|
|
394
3703
|
## [1.0.1] - 2026-07-22
|
|
395
3704
|
|
|
396
|
-
|
|
397
|
-
|
|
398
3705
|
- KF-329: pin release-workflow npm upgrade to npm@11 — npm@12 needs Node ≥ 22.22.2, above the 22.21.0 pin (`c54559f`)
|
|
399
3706
|
|
|
400
3707
|
## [1.0.0] - 2026-07-22
|
|
401
3708
|
|
|
402
|
-
|
|
403
|
-
|
|
404
3709
|
- **Fine-grained signal bindings** — pass a signal or `computed` directly into a JSX attribute or text hole (e.g. `class={computed(...)}` or `{sig}`) inside `mount()`, and that one node updates on signal change without re-running `render()` or walking the list reconciler. Opt-in per hole and non-breaking; works in static content and inside `each()` rows on both the snapshot and `arraySignal` reconcile paths, with binding effects correctly wired, carried, and disposed across row insert/update/remove/move.
|
|
405
3710
|
- Bound values get the same safety treatment as static ones: URL screening and `SafeHtml`/`raw()` unwrapping now apply to fine-grained bound attributes.
|
|
406
3711
|
- New interactive benchmark playground (`npm run bench:serve`) to explore kerf by hand in the standard 1k-rows benchmark app.
|
|
407
3712
|
- New **row-selector** example app and a "Fine-grained bindings" section in the reactivity demo, both showing select-row updates with zero render re-runs and zero list reconciles.
|
|
408
3713
|
|
|
409
|
-
|
|
410
3714
|
- Hardened the dangerous-URL screen: scheme detection now normalizes away C0 control characters, DEL, and leading whitespace, so obfuscations like `java script:` or a NUL before the colon can no longer slip `javascript:`/`vbscript:` URLs past the check.
|
|
411
3715
|
- Attribute names are now validated — malformed names (e.g. from spreading attacker-controlled keys into JSX) throw instead of breaking out of the open tag, and inline `on*` event handlers are rejected on both the static and signal-bound attribute paths, closing an XSS vector where a bound `onclick` would have installed a live handler.
|
|
412
3716
|
- Documented kerf's reserved marker namespace (`data-kfb`, `data-kfbrow`, `kfb:`/`kfbr:`/`kf-list:` comments) — consumer content using these can collide with binding wiring, so they're now explicitly reserved.
|
|
413
3717
|
- Documented the trusted-input bridges (`toElement()`, `morph()` with string/Element templates, `<iframe srcdoc>`) that bypass escaping by design, and the `raw()`/`SafeHtml` trust boundary.
|
|
414
3718
|
- Hardened the release pipeline: least-privilege OIDC scoping per job, SHA-pinned GitHub Actions with automated Dependabot bumps, and a token-holding publish job that runs with `--ignore-scripts` and no build tools.
|
|
415
3719
|
|
|
416
|
-
|
|
417
3720
|
- Reduced the per-row create cost of fine-grained row bindings from ~1.65× to ~1.15× via lazy row wiring — the common single-root-binding case now needs no subtree walk or extra allocations.
|
|
418
3721
|
- Published cross-framework benchmark numbers now come from the official upstream krausest js-framework-benchmark run (kerf is a merged upstream entry), replacing stale local-machine measurements.
|
|
419
3722
|
|
|
420
|
-
|
|
421
3723
|
- README refreshed for the 1.0 release: fine-grained updates and safe-by-default escaping promoted to headline features, and the status line flipped from "Pre-1.0 — API may evolve" to stable 1.0.
|
|
422
3724
|
- Fine-grained bindings documented across all consumer and AI-assistant surfaces (reactivity docs, API reference, usage guide, Cursor rules, Claude skill).
|
|
423
3725
|
|
|
424
|
-
- **Signposted the raw HTML/SVG → DOM bridges as trusted-input only.** `toElement()`, `morph()` (with a string/Element template), and the `<iframe srcdoc>` attribute bypass kerf's escaping/URL-screening by design — they're the same trust model as `innerHTML` / `raw()`. The docs now call this out loudly, including that the SVG path is
|
|
425
|
-
- **Documented kerf's reserved marker namespace.** Fine-grained bindings and `each()` lists coordinate through in-band markers that the wiring pass finds by scanning the mounted subtree and matching by id. A consumer element that carries one of those names can collide with a real binding's id and silently steal its update, so the names are now documented as reserved: the `data-kfb` / `data-kfbrow` attributes and HTML comments beginning `kfb:` / `kfbr:` / `kf-list:`. Don't emit them from your own markup or via `raw()`. (kerf's escaping already prevents a plain text/attribute
|
|
426
|
-
- **Attribute names are now validated, and inline event handlers are rejected outright.** The JSX runtime already escaped attribute
|
|
3726
|
+
- **Signposted the raw HTML/SVG → DOM bridges as trusted-input only.** `toElement()`, `morph()` (with a string/Element template), and the `<iframe srcdoc>` attribute bypass kerf's escaping/URL-screening by design — they're the same trust model as `innerHTML` / `raw()`. The docs now call this out loudly, including that the SVG path is _more_ dangerous than the HTML path (a top-level `<svg><script>`, SVG event attributes, and `xlink:href="javascript:"` execute once inserted, whereas an HTML-string `<script>` is inert), and that `srcdoc` is HTML a browser re-parses as a document (so `srcdoc={userString}` executes even though the value is escaped as an attribute). No behavior change — these are documentation + regression tests: a real-browser spec (`tests/browser/trusted-html-bridges.spec.ts`) pins the execution boundary across Chromium/Firefox/WebKit, a unit test pins that the granular list fast path keeps the URL screen's guarantee end-to-end, and another pins that SVG input isn't sanitized. See [`docs/7-svg.md`](docs/7-svg.md) § Security, [`docs/8-api-reference.md`](docs/8-api-reference.md), and [`docs/6-jsx-runtime.md`](docs/6-jsx-runtime.md) §6.4.3.
|
|
3727
|
+
- **Documented kerf's reserved marker namespace.** Fine-grained bindings and `each()` lists coordinate through in-band markers that the wiring pass finds by scanning the mounted subtree and matching by id. A consumer element that carries one of those names can collide with a real binding's id and silently steal its update, so the names are now documented as reserved: the `data-kfb` / `data-kfbrow` attributes and HTML comments beginning `kfb:` / `kfbr:` / `kf-list:`. Don't emit them from your own markup or via `raw()`. (kerf's escaping already prevents a plain text/attribute _value_ from forging one — the only ways in are hand-written markup or `raw()`.) See [`docs/2-reactivity.md`](docs/2-reactivity.md) § "Reserved marker names".
|
|
3728
|
+
- **Attribute names are now validated, and inline event handlers are rejected outright.** The JSX runtime already escaped attribute _values_; it now also validates each attribute _name_ against a safe shape (a letter/underscore/colon followed by letters, digits, or `_ . : -`) and **throws** on anything else. This closes a markup-injection vector when an object with attacker-controlled keys is spread into JSX (`<div {...untrustedObj}>`) — previously a key like `'x><img onerror=…>'` broke out of the open tag even though the value was escaped. Separately, any `on*` attribute (a function _or_ a string value, in any case — e.g. `onClick={fn}` or `onclick="…"`) now throws and points at `delegate()`; previously only function-valued keys matching `/^on[A-Z]/` were caught, so a string `onclick="alert(1)"` slipped through and became a live inline handler when parsed. Both checks now cover the **fine-grained bound path** too: a signal bound straight into an attribute (`onclick={signal}`) is written with `setAttribute`, and `setAttribute('onclick', …)` installs a live inline handler just as a parsed string would — so an `on*` (or malformed) name bound as a signal is rejected at binding time, closing the same vector on the signal path. See [`docs/6-jsx-runtime.md`](docs/6-jsx-runtime.md) §6.4.2.
|
|
427
3729
|
- **Hardened the dangerous-URL screen.** The URL-attribute filter (on `href`/`src`/`xlink:href`/`formaction`/`action`) now: (1) sees through control-character and whitespace obfuscation of the scheme — a leading ``, an in-scheme `TAB`/`LF`/`CR` (`java script:`), or a `NUL` before the colon are all normalized away before the scheme is read, matching how a browser resolves the URL, so they can no longer slip a `javascript:` past the screen; (2) treats `data:` by subtype instead of only blocking `data:text/html` — script-executing document types (`data:text/html`, `data:image/svg+xml`, XHTML/XML) are dropped while inert media (raster images, fonts, audio, video, plain text/CSS) still pass, and any unknown subtype fails closed; and (3) also screens the `data` attribute on `<object>` (which loads its target as a document). `raw()` remains the opt-out. Both the static serializer and the fine-grained bound-attribute writer share the screen, so both paths are covered.
|
|
428
|
-
- **Fine-grained signal bindings.** Hand a `Signal`/`computed`
|
|
3730
|
+
- **Fine-grained signal bindings.** Hand a `Signal`/`computed` _itself_ (not its `.value`) into a JSX attribute (`class={someSignal}`) or a text hole (`{someSignal}`) inside a `mount()`, and kerf binds that hole directly to the signal: when the signal changes, only that attribute/text node updates — the render function does **not** re-run and the list reconciler does **not** walk. This is kerf's fine-grained update tier, sitting below the coarse `mount()` effect, for the "external state drives one spot" pattern (a `selectedId` flipping a row's class, a live status attribute, etc.). Works in static content and inside `each()` rows on both the snapshot and `arraySignal` (granular) paths, and row bindings' lifetimes track their row node (a row reorder is free; a removed row's binding is torn down). Opt-in and non-breaking: passing a raw signal into JSX previously threw, so existing apps are unchanged, and any hole that isn't a signal stringifies exactly as before. Bound URL attributes (`href`/`src`/`formaction`/`action`/`xlink:href`) get the same `javascript:`/`vbscript:`/`data:text/html` screening as static attributes (`raw()` opts out). Outside a `mount()` (SSR / `SafeHtml.toString()`) a bound signal snapshots its current value and emits no markers. See [`docs/2-reactivity.md`](docs/2-reactivity.md) §2.9.
|
|
429
3731
|
|
|
430
3732
|
## [0.16.0] - 2026-07-01
|
|
431
3733
|
|
|
432
|
-
|
|
433
|
-
|
|
434
3734
|
- Fixed keyed-list selection breaking after a row was removed: a signal read only inside `each()`'s `cacheKey` (such as a `selectedId` toggling a row's class) no longer drops out of the reactive dependency set, so later changes re-render correctly.
|
|
435
3735
|
- Fixed appending items to a list after clearing it rendering nothing.
|
|
436
3736
|
|
|
@@ -439,115 +3739,90 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
|
439
3739
|
|
|
440
3740
|
## [0.15.5] - 2026-06-30
|
|
441
3741
|
|
|
442
|
-
|
|
443
|
-
|
|
444
3742
|
- Corrected the advertised bundle size in `llms.txt` to ~11 KB minified + gzipped (including the `@preact/signals-core` runtime dependency; ~12 KB with `arraySignal`), matching the README.
|
|
445
3743
|
|
|
446
3744
|
## [0.15.4] - 2026-06-30
|
|
447
3745
|
|
|
448
|
-
|
|
449
|
-
|
|
450
3746
|
- `llms.txt` is now published at a public docs-site URL and bundled in the npm package, making kerf's AI-assistant documentation index discoverable to llms.txt directories and tooling.
|
|
451
3747
|
|
|
452
3748
|
- The `kerfjs` package now bundles `llms.txt` (the AI-discovery index) at the package root, and the docs site serves it at `https://brianwestphal.github.io/kerf/llms.txt`. Its links are now absolute GitHub URLs so the file is portable across GitHub, the site, and the installed package.
|
|
453
3749
|
|
|
454
3750
|
## [0.15.3] - 2026-06-30
|
|
455
3751
|
|
|
456
|
-
|
|
457
|
-
|
|
458
3752
|
- `npm create kerf-component` with no directory argument now prompts for the target directory (defaulting to `my-kerf-component`, with a `.` hint for the current directory) instead of printing usage text and exiting with an error.
|
|
459
3753
|
|
|
460
3754
|
## [0.15.2] - 2026-06-30
|
|
461
3755
|
|
|
462
|
-
|
|
463
|
-
|
|
464
3756
|
- Added the `create-kerf-component` initializer — scaffold a ready-to-publish kerf component package with `npm create kerf-component@latest <dir>`, no need to reverse-engineer the packaging rules.
|
|
465
3757
|
|
|
466
3758
|
## [0.15.1] - 2026-06-30
|
|
467
3759
|
|
|
468
|
-
|
|
469
|
-
|
|
470
3760
|
- README refresh + eslint rule-count fixes + CHANGELOG hygiene (`cfbaef3`)
|
|
471
3761
|
|
|
472
3762
|
## [0.15.0] - 2026-06-30
|
|
473
3763
|
|
|
474
|
-
|
|
475
|
-
|
|
476
3764
|
- List updates now morph same-identity rows in place instead of recreating their DOM nodes, avoiding full-table relayout on large lists and preserving DOM identity, focus, and IME composition across re-renders.
|
|
477
3765
|
|
|
478
|
-
|
|
479
3766
|
- New guide on incremental migration: kerf can own a single DOM subtree and coexist with React (or any framework), letting you migrate one island at a time.
|
|
480
3767
|
- New guide on building and publishing reusable kerf components as npm packages.
|
|
481
3768
|
- Example app documentation pages now open with an animated SVG preview of the real app in action, plus a gallery on the complete-examples index.
|
|
482
3769
|
|
|
483
3770
|
## [0.14.0] - 2026-05-27
|
|
484
3771
|
|
|
485
|
-
|
|
486
3772
|
- Fix `toElement()` first-paint divergence in WebKit by adopting its result into the live document
|
|
487
3773
|
- Fix `mount()` first render in WebKit by adopting an inert `rootEl` into the live document
|
|
488
3774
|
|
|
489
3775
|
## [0.13.0] - 2026-05-23
|
|
490
3776
|
|
|
491
|
-
|
|
492
3777
|
- Add `KERF_DEV_WARN_DELEGATE_IN_EFFECT` dev warning to catch `delegate()` calls inside reactive effects
|
|
493
3778
|
- New `require-delegate-disposer` ESLint rule flags `delegate()` calls whose disposer is discarded
|
|
494
3779
|
- Document `delegate()` disposer gotchas and canonical cleanup patterns
|
|
495
3780
|
|
|
496
3781
|
## [0.12.1] - 2026-05-22
|
|
497
3782
|
|
|
498
|
-
|
|
499
3783
|
- Add GitHub Sponsors link to README, homepage, and npm `funding` field
|
|
500
3784
|
|
|
501
3785
|
## [0.12.0] - 2026-05-22
|
|
502
3786
|
|
|
503
|
-
|
|
504
3787
|
- `toElement` now returns `Element | DocumentFragment` to support multi-root inputs
|
|
505
3788
|
|
|
506
3789
|
## [0.11.1] - 2026-05-21
|
|
507
3790
|
|
|
508
|
-
|
|
509
3791
|
- `attr()` redesign: typed `AttrSpec<N, V>` exposes `.attrs` with dual overloads for cleaner attribute handling
|
|
510
3792
|
|
|
511
3793
|
## [0.11.0] - 2026-05-21
|
|
512
3794
|
|
|
513
|
-
|
|
514
3795
|
- `attr()` redesigned with `AttrSpec<N,V>` shape, `.attrs` accessor, and dual overloads
|
|
515
3796
|
- Hardened defensive programming across the runtime for safer edge-case handling
|
|
516
3797
|
- Refreshed published performance numbers from a fresh cross-framework benchmark run
|
|
517
3798
|
|
|
518
3799
|
## [0.10.0] - 2026-05-20
|
|
519
3800
|
|
|
520
|
-
|
|
521
3801
|
- Expose `kerfjs/ai/*` subpaths via package `exports` so the bundled skill/cursorrules files are resolvable
|
|
522
3802
|
- Add a defensive fallback in `kerfjs/ai-assistant-configs` ESLint rule so it fires against installed kerfjs versions whose `exports` block subpath resolution
|
|
523
3803
|
|
|
524
3804
|
## [0.9.1] - 2026-05-20
|
|
525
3805
|
|
|
526
|
-
|
|
527
3806
|
- Bundle the kerf-app Claude Code skill and Cursor rules inside the npm package at `ai/skill.md`, `ai/cursorrules`, and `ai/manifest.json`
|
|
528
3807
|
- Add `kerfjs/ai-assistant-configs` rule to `eslint-plugin-kerfjs` (warn in recommended) to flag drift in installed AI assistant configs
|
|
529
3808
|
- `eslint --fix` now replaces only the canonical section above the `KERF-APP-CANONICAL-END` marker, preserving consumer customizations below it
|
|
530
3809
|
|
|
531
3810
|
## [0.9.0] - 2026-05-20
|
|
532
3811
|
|
|
533
|
-
|
|
534
3812
|
- Bundle the kerf-app Claude Code skill and Cursor rules inside the npm package at `ai/skill.md`, `ai/cursorrules`, and `ai/manifest.json`
|
|
535
3813
|
- Add `kerfjs/ai-assistant-configs` rule (warn in recommended) to `eslint-plugin-kerfjs` v0.9.0 to surface AI-config drift on every lint pass
|
|
536
3814
|
- Canonical-file contract (`kerf-skill-version` + `KERF-APP-CANONICAL-END` marker) lets `eslint --fix` refresh the canonical section while preserving consumer customizations below the marker
|
|
537
3815
|
|
|
538
3816
|
## [0.8.2] - 2026-05-19
|
|
539
3817
|
|
|
540
|
-
|
|
541
3818
|
- Package `homepage` fields now point to the published docs site, with prominent links in both READMEs
|
|
542
3819
|
|
|
543
3820
|
## [0.8.1] - 2026-05-19
|
|
544
3821
|
|
|
545
|
-
|
|
546
3822
|
- New `eslint-plugin-kerfjs` with four AST rules enforcing kerf Hard Rules
|
|
547
3823
|
|
|
548
3824
|
## [0.8.0] - 2026-05-18
|
|
549
3825
|
|
|
550
|
-
|
|
551
3826
|
- Add opt-in dev warning `KERF_DEV_WARN_NARROW_SET=1` that fires when `set()` is called with a partial-state object (replace semantics would silently drop missing keys); names the missing keys and points at the `set({ ...get(), ...next })` merge fix
|
|
552
3827
|
- Widen `KerfBaseAttrs.contentEditable` to accept `'plaintext-only'` and add the lowercase `contenteditable` alias
|
|
553
3828
|
- Expand the `/kerf/migrating/` hub to 13 frameworks — adds Vue 3, Svelte 5, Solid, Preact, htmx, Angular, jQuery, Redux, and Astro pages alongside a refreshed 8-framework comparison matrix
|
|
@@ -558,7 +3833,6 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
|
558
3833
|
|
|
559
3834
|
## [0.7.0] - 2026-05-18
|
|
560
3835
|
|
|
561
|
-
|
|
562
3836
|
- Granular list updates now preserve DOM identity, focus, scroll, IME state, `<details open>`/`<dialog open>`, and `data-morph-skip` subtrees across in-place row updates
|
|
563
3837
|
- Two new fast paths in the granular reconciler cut krausest select-row by 71% (27.8 → 8.2 ms) and partial-update by 28% (46.8 → 33.8 ms)
|
|
564
3838
|
- `each()`'s third parameter renamed from `key` to `cacheKey` to clarify it's a passive cache-invalidation comparator, not a React-style reconciliation identity; positional callers unaffected
|
|
@@ -574,7 +3848,6 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
|
574
3848
|
|
|
575
3849
|
## [0.6.0] - 2026-05-11
|
|
576
3850
|
|
|
577
|
-
|
|
578
3851
|
- Public `morph(liveRoot, template)` export for standalone DOM reconciliation
|
|
579
3852
|
- New `data-morph-preserve` attribute to opt elements out of morphing
|
|
580
3853
|
- New `data-morph-skip-children` attribute — morph host attrs but leave subtree intact
|
|
@@ -583,12 +3856,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
|
583
3856
|
|
|
584
3857
|
## [0.5.1] - 2026-05-11
|
|
585
3858
|
|
|
586
|
-
|
|
587
3859
|
- Fix `dist/jsx-runtime.d.ts` IntrinsicElements self-shadow that broke JSX typing in consumer apps
|
|
588
3860
|
|
|
589
3861
|
## [0.5.0] - 2026-05-10
|
|
590
3862
|
|
|
591
|
-
|
|
592
3863
|
- Add `arraySignal` (`kerfjs/array-signal` subpath) — granular collection signal that drives O(patches) DOM updates for keyed lists
|
|
593
3864
|
- Faster keyed-list updates: bulk-parse contiguous insert runs and consecutive update patches in the granular reconcile path
|
|
594
3865
|
- Perf optimizations on the `each()` / `mount()` update path; benchmarks now competitive with Solid/Vue on swap/remove/clear
|
|
@@ -602,17 +3873,14 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
|
602
3873
|
|
|
603
3874
|
## [0.4.2] - 2026-05-09
|
|
604
3875
|
|
|
605
|
-
|
|
606
3876
|
- No user-facing changes in this release.
|
|
607
3877
|
|
|
608
3878
|
## [0.4.1] - 2026-05-09
|
|
609
3879
|
|
|
610
|
-
|
|
611
3880
|
- Just fixing the build
|
|
612
3881
|
|
|
613
3882
|
## [0.4.0] - 2026-05-09
|
|
614
3883
|
|
|
615
|
-
|
|
616
3884
|
- `delegate()` now auto-promotes the seven well-known non-bubbling events (`focus`, `blur`, `scroll`, `load`, `error`, `mouseenter`, `mouseleave`) to capture phase, with `closest()`-style selector matching preserved
|
|
617
3885
|
- Fixed focus and caret position loss when reordering keyed `each()` rows on engines that drop focus on `insertBefore` (older Safari, happy-dom)
|
|
618
3886
|
- `mount()` now throws a descriptive error when the root element is null/undefined instead of a generic "Cannot set properties of null"
|
|
@@ -623,12 +3891,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
|
623
3891
|
|
|
624
3892
|
## [0.3.1] - 2026-05-08
|
|
625
3893
|
|
|
626
|
-
|
|
627
3894
|
- Removed stale `morphdom` references; the bundled native diff is now the only reconciler
|
|
628
3895
|
|
|
629
3896
|
## [0.3.0] - 2026-05-08
|
|
630
3897
|
|
|
631
|
-
|
|
632
3898
|
- Rebuilt render pipeline with structured segments and a native keyed-list diff, replacing the morphdom dependency
|
|
633
3899
|
- Added `each()` for keyed list iteration with per-item HTML memoization by object identity
|
|
634
3900
|
- Renamed the npm package from `kerf` to `kerfjs` (the `kerf` name tripped npm's typo-squatting heuristic); the brand, GitHub repo, and Pages URL are unchanged
|
|
@@ -639,24 +3905,20 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
|
639
3905
|
|
|
640
3906
|
## [0.2.1] - 2026-05-07
|
|
641
3907
|
|
|
642
|
-
|
|
643
3908
|
- Add `Fragment` export to the `kerfjs` barrel for explicit JSX fragment usage
|
|
644
3909
|
|
|
645
3910
|
## [0.2.0] - 2026-05-07
|
|
646
3911
|
|
|
647
|
-
|
|
648
3912
|
- Fix focused contenteditable losing focus/caret during morph
|
|
649
3913
|
- Fix `SafeHtml` identity mismatch across entry points caused by dist bundling
|
|
650
3914
|
- Fix `clearStoreRegistry` no-op in built output, restoring test isolation
|
|
651
3915
|
|
|
652
3916
|
## [0.1.2] - 2026-05-07
|
|
653
3917
|
|
|
654
|
-
|
|
655
3918
|
- No user-facing changes; release tooling fixes only.
|
|
656
3919
|
|
|
657
3920
|
## [0.1.1] - 2026-05-07
|
|
658
3921
|
|
|
659
|
-
|
|
660
3922
|
- This is just a publication script test
|
|
661
3923
|
|
|
662
3924
|
## [0.1.0] - 2026-05-07
|