@kerfjs/ui 5.0.0-beta.111 → 5.0.0-beta.113

package/README.md

@@ -273,6 +273,8 @@ interchangeable. `ListItem` and `ListActionRow` deliberately expose no raw
 | `LoadingSpinner`                                             | `@kerfjs/ui/loading-spinner`            | `@kerfjs/ui/loading-spinner.css`         |
 | `Skeleton`                                                   | `@kerfjs/ui/skeleton`                   | `@kerfjs/ui/skeleton.css`                |
 | `SunkenPanel`                                                | `@kerfjs/ui/sunken-panel`               | `@kerfjs/ui/sunken-panel.css`            |
+| `ValuePreview`                                               | `@kerfjs/ui/value-preview`              | `@kerfjs/ui/value-preview.css`           |
+| `EditorFrame`                                                | `@kerfjs/ui/editor-frame`               | `@kerfjs/ui/editor-frame.css`            |
 | `BackdropImage`                                              | `@kerfjs/ui/backdrop-image`             | `@kerfjs/ui/backdrop-image.css`          |
 | `Select`                                                     | `@kerfjs/ui/select`                     | `@kerfjs/ui/select.css`                  |
 | `SegmentedControl`                                           | `@kerfjs/ui/segmented-control`          | `@kerfjs/ui/segmented-control.css`       |

package/ai/component-catalog.json

@@ -1726,7 +1726,8 @@
         "progressive blur from a once-filtered copy or an app-supplied blurred asset, with an optional dim",
         "fade into a color that also paints below",
         "bottom or full scrim under overlay content",
-        "image running beneath clear or overlay chrome (underChrome)"
+        "image running beneath clear or overlay chrome (underChrome)",
+        "opt-in deferOffscreen hero paint deferral for dense image feeds without changing reserved height"
       ],
       "accessibility": [
         "alt describes a meaningful image; pass an empty alt for a decorative one. A tiled image with alt text is exposed as role=\"img\". Parallax and the progressive blur run only with prefers-reduced-motion: no-preference and scroll-driven animation support, and are off under data-kui-effects=\"static\" and on slow-update displays, leaving a static, sharp image; the blurred copy is decorative and aria-hidden. Reduced transparency or increased contrast replaces the fade with a hard edge on solid fadeTo and puts overlay content on a solid fadeTo band. Overlay text needs a scrim or fade color that keeps it at AA."
@@ -3049,6 +3050,147 @@
         "recipe": "docs/component-selection.md#ambiguous-choices"
       }
     },
+    {
+      "id": "editor-frame",
+      "name": "EditorFrame",
+      "category": "Structure",
+      "kind": "component",
+      "source": "kerf",
+      "description": "A bounded editor surface with a fixed toolbar and one native source or preview scroll owner.",
+      "uses": [
+        "toolbar"
+      ],
+      "purpose": "Own a framed or embedded writing surface while the app owns its native textarea, draft, and rendered preview.",
+      "publicExports": [
+        "EditorFrame"
+      ],
+      "useWhen": [
+        "A standalone Markdown or text editor needs a fixed toolbar above a bounded native textarea or preview.",
+        "An embedded editor needs the same source/preview anatomy without a second frame."
+      ],
+      "avoidWhen": [
+        "Do not use for an ordinary single form field; use TextField.",
+        "Do not replace the app's draft, recovery, focus, or preview behavior."
+      ],
+      "alternatives": [
+        {
+          "id": "text-field",
+          "relationship": "nearest",
+          "when": "Use TextField for a conventional form value without editor toolbar and preview."
+        }
+      ],
+      "appOwns": [
+        "draft value",
+        "editing actions",
+        "preview rendering",
+        "recovery and focus management"
+      ],
+      "variants": [
+        "source and preview modes",
+        "framed and embedded appearances",
+        "padded and flush insets",
+        "expanded overlay",
+        "embedded autosize or restored source height"
+      ],
+      "accessibility": [
+        "Give the editor frame a label when it is a distinct region; the app labels its native textarea and supplies toolbar controls."
+      ],
+      "geometry": {
+        "margin": "none",
+        "border": "self",
+        "padding": "self"
+      },
+      "delivery": {
+        "browserImport": "@kerfjs/ui/editor-frame",
+        "manualCssImport": "@kerfjs/ui/editor-frame.css",
+        "sideEffects": [
+          "browser-condition-css"
+        ]
+      },
+      "wiring": [],
+      "publicClasses": [
+        "kui-editor-frame",
+        "kui-editor-frame__toolbar",
+        "kui-editor-frame__surface"
+      ],
+      "publicTokens": [
+        "--kui-color-neutral-border-normal",
+        "--kui-color-neutral-on-normal",
+        "--kui-color-surface",
+        "--kui-radius-l",
+        "--kui-shadow-l"
+      ],
+      "links": {
+        "catalogRoute": "?component=editor-frame",
+        "documentation": "docs/editor-frame.md",
+        "recipe": "docs/editor-frame.md"
+      }
+    },
+    {
+      "id": "value-preview",
+      "name": "ValuePreview",
+      "category": "Structure",
+      "kind": "component",
+      "source": "kerf",
+      "description": "A bounded, read-only multiline text value with keyboard scrolling.",
+      "uses": [
+        "sunken-panel"
+      ],
+      "purpose": "Display a literal long value with line breaks and long tokens inside a bounded scroll region.",
+      "publicExports": [
+        "ValuePreview"
+      ],
+      "useWhen": [
+        "A read-only value may have multiple lines or long unbroken text and needs bounded scrolling, such as a conflict version."
+      ],
+      "avoidWhen": [
+        "Do not use for editing; use a multiline TextField.",
+        "Do not use for short label/value facts; use ValueTable."
+      ],
+      "alternatives": [
+        {
+          "id": "value-table",
+          "relationship": "nearest",
+          "when": "Use ValueTable for rows of short labelled facts."
+        }
+      ],
+      "appOwns": [
+        "value",
+        "empty wording"
+      ],
+      "variants": [
+        "typed minimum and maximum height"
+      ],
+      "accessibility": [
+        "Give the focusable output a label so keyboard and screen-reader users can identify and scroll it."
+      ],
+      "geometry": {
+        "margin": "none",
+        "border": "none",
+        "padding": "none"
+      },
+      "delivery": {
+        "browserImport": "@kerfjs/ui/value-preview",
+        "manualCssImport": "@kerfjs/ui/value-preview.css",
+        "sideEffects": [
+          "browser-condition-css"
+        ]
+      },
+      "wiring": [],
+      "publicClasses": [
+        "kui-value-preview"
+      ],
+      "publicTokens": [
+        "--kui-color-text",
+        "--kui-font-xs",
+        "--kui-focus-ring"
+      ],
+      "links": {
+        "catalogRoute": "?component=value-preview",
+        "documentation": "docs/value-preview.md",
+        "recipe": "docs/value-preview.md"
+      }
+    },
     {
       "id": "value-table",
       "name": "ValueTable",
@@ -3224,14 +3366,15 @@
       "category": "Structure",
       "kind": "component",
       "source": "kerf",
-      "description": "A selectable, focusable summary of one item as a list row or a board card, with a state rail, a clamped title, trailing meta, and a metadata line.",
+      "description": "A selectable option or static diagnostic group as a list row or board card, with a state rail, a clamped title, trailing meta, and a metadata line.",
       "uses": [],
       "purpose": "Present dense item summaries (tickets, tasks, messages) as selectable list rows or board cards with Kerf-owned selection, hover, focus, rail, clamping, list-edge rounding, and narrow compaction, without app row CSS.",
       "publicExports": [
         "SummaryRow"
       ],
       "useWhen": [
-        "A list or board shows many items as dense, selectable summaries with an identifier, a title, a timestamp, and metadata."
+        "A list or board shows many items as dense, selectable summaries with an identifier, a title, a timestamp, and metadata.",
+        "An unreadable item needs the same summary chrome with a nested recovery action but must be a labeled non-option group."
       ],
       "avoidWhen": [
         "Do not use for navigation rows with a single label; use ListItem.",
@@ -3263,10 +3406,12 @@
         "state rail",
         "list edge start, end, or only",
         "title line budget",
-        "deferred rendering"
+        "deferred rendering",
+        "static labeled group with a nested action (semanticRole=group)",
+        "native draggable option root for list rows and board cards"
       ],
       "accessibility": [
-        "Each SummaryRow is role=option with tabindex=0 and aria-selected; place rows in a labeled role=listbox and move focus with the arrow keys in the app. The rail is decorative; carry its meaning in text."
+        "By default SummaryRow is role=option with tabindex=0 and aria-selected; place options in a labeled role=listbox and move focus with the arrow keys in the app. semanticRole=group requires ariaLabel and omits the root Tab stop and aria-selected, so a nested native action owns focus and activation. The rail is decorative; carry its meaning in text."
       ],
       "geometry": {
         "margin": "none",
@@ -4967,7 +5112,8 @@
         "chat bubble at the start or end of the row (bubble), fit to its content up to 80%",
         "named focus-target region",
         "multi-select rich grid row",
-        "gridRow: a non-selectable row (role=\"row\" with a gridcell) between selectable rows of a multi-select List or Grid"
+        "gridRow: a non-selectable row (role=\"row\" with a gridcell) between selectable rows of a multi-select List or Grid",
+        "image-led feed media with opt-in deferOffscreen hero paint deferral"
       ],
       "accessibility": [
         "An ordinary item adds no role or name; pass ariaLabel only when the item is a distinct named region (it then renders role=\"region\").",

package/ai/component-composition.json

@@ -2709,6 +2709,116 @@
         "composition": "generated-permissive-default"
       }
     },
+    {
+      "key": "@kerfjs/ui:editor-frame",
+      "package": "@kerfjs/ui",
+      "id": "editor-frame",
+      "name": "EditorFrame",
+      "kind": "component",
+      "source": "kerf",
+      "parents": { "mode": "any", "entries": [] },
+      "contexts": ["application-ui"],
+      "zones": [],
+      "children": { "mode": "any", "concepts": [], "requiredConcepts": [] },
+      "state": [
+        { "id": "draft value", "owner": "application", "required": false },
+        { "id": "editing actions", "owner": "application", "required": false },
+        {
+          "id": "preview rendering",
+          "owner": "application",
+          "required": false
+        },
+        {
+          "id": "recovery and focus management",
+          "owner": "application",
+          "required": false
+        }
+      ],
+      "wiring": {
+        "required": false,
+        "helpers": [],
+        "obligations": [],
+        "stateAttributes": []
+      },
+      "responsive": { "owner": "not-applicable", "behaviors": [] },
+      "layout": {
+        "roles": ["structure"],
+        "geometry": { "margin": "none", "border": "self", "padding": "self" }
+      },
+      "accessibility": {
+        "obligations": [
+          "Give the editor frame a label when it is a distinct region; the app labels its native textarea and supplies toolbar controls."
+        ]
+      },
+      "cssValueProps": [],
+      "boundaries": {
+        "rootClass": "kui-editor-frame",
+        "publicClasses": [
+          "kui-editor-frame",
+          "kui-editor-frame__toolbar",
+          "kui-editor-frame__surface"
+        ],
+        "publicTokens": [
+          "--kui-color-neutral-border-normal",
+          "--kui-color-neutral-on-normal",
+          "--kui-color-surface",
+          "--kui-radius-l",
+          "--kui-shadow-l"
+        ]
+      },
+      "diagnostics": [],
+      "provenance": {
+        "selection": "ai/component-catalog.json",
+        "composition": "generated-permissive-default"
+      }
+    },
+    {
+      "key": "@kerfjs/ui:value-preview",
+      "package": "@kerfjs/ui",
+      "id": "value-preview",
+      "name": "ValuePreview",
+      "kind": "component",
+      "source": "kerf",
+      "parents": { "mode": "any", "entries": [] },
+      "contexts": ["application-ui"],
+      "zones": [],
+      "children": { "mode": "any", "concepts": [], "requiredConcepts": [] },
+      "state": [
+        { "id": "value", "owner": "application", "required": false },
+        { "id": "empty wording", "owner": "application", "required": false }
+      ],
+      "wiring": {
+        "required": false,
+        "helpers": [],
+        "obligations": [],
+        "stateAttributes": []
+      },
+      "responsive": { "owner": "not-applicable", "behaviors": [] },
+      "layout": {
+        "roles": ["structure"],
+        "geometry": { "margin": "none", "border": "none", "padding": "none" }
+      },
+      "accessibility": {
+        "obligations": [
+          "Give the focusable output a label so keyboard and screen-reader users can identify and scroll it."
+        ]
+      },
+      "cssValueProps": [],
+      "boundaries": {
+        "rootClass": "kui-value-preview",
+        "publicClasses": ["kui-value-preview"],
+        "publicTokens": [
+          "--kui-color-text",
+          "--kui-font-xs",
+          "--kui-focus-ring"
+        ]
+      },
+      "diagnostics": [],
+      "provenance": {
+        "selection": "ai/component-catalog.json",
+        "composition": "generated-permissive-default"
+      }
+    },
     {
       "key": "@kerfjs/ui:value-table",
       "package": "@kerfjs/ui",
@@ -2894,7 +3004,7 @@
       },
       "accessibility": {
         "obligations": [
-          "Each SummaryRow is role=option with tabindex=0 and aria-selected; place rows in a labeled role=listbox and move focus with the arrow keys in the app. The rail is decorative; carry its meaning in text."
+          "By default SummaryRow is role=option with tabindex=0 and aria-selected; place options in a labeled role=listbox and move focus with the arrow keys in the app. semanticRole=group requires ariaLabel and omits the root Tab stop and aria-selected, so a nested native action owns focus and activation. The rail is decorative; carry its meaning in text."
         ]
       },
       "cssValueProps": [],

package/ai/components/README.md

@@ -35,6 +35,8 @@ Exact prop and callback types live in [`public-api-signatures-v1.md`](../public-
 - [ToolbarText](./toolbar-text.md) — Extra-large through extra-small toolbar identity text.
 - [Text](./text.md) — Render paragraph semantics by default, h1 through h6 when selected, or geometry-free inline secondary text as a span while independently configuring quiet or danger tone, compact through extra-large size, or monospace font.
 - [Headers](./headers.md) — Page, dialog, and definition-list hierarchy.
+- [EditorFrame](./editor-frame.md) — Own a framed or embedded writing surface while the app owns its native textarea, draft, and rendered preview.
+- [ValuePreview](./value-preview.md) — Display a literal long value with line breaks and long tokens inside a bounded scroll region.
 - [ValueTable](./value-table.md) — Key/value rows with optional icons and aligned separators.
 - [FramedList](./framed-list.md) — Group settings-style rows of arbitrary content (copy, keycaps, controls) in one framed surface with between-row dividers and an optional highlighted row, without app list CSS.
 - [SummaryRow](./summary-row.md) — Present dense item summaries (tickets, tasks, messages) as selectable list rows or board cards with Kerf-owned selection, hover, focus, rail, clamping, list-edge rounding, and narrow compaction, without app row CSS.

package/ai/components/backdrop-image.md

@@ -43,6 +43,7 @@ Exact prop names and types: [`@kerfjs/ui/backdrop-image`](../public-api-signatur
 - fade into a color that also paints below
 - bottom or full scrim under overlay content
 - image running beneath clear or overlay chrome (underChrome)
+- opt-in deferOffscreen hero paint deferral for dense image feeds without changing reserved height
 
 ## Composition
 

package/ai/components/content-item.md

@@ -53,6 +53,7 @@ Exact prop names and types: [`@kerfjs/ui/content-item`](../public-api-signatures
 - named focus-target region
 - multi-select rich grid row
 - gridRow: a non-selectable row (role="row" with a gridcell) between selectable rows of a multi-select List or Grid
+- image-led feed media with opt-in deferOffscreen hero paint deferral
 
 ## Composition
 

package/ai/components/editor-frame.md

@@ -0,0 +1,80 @@
+# EditorFrame
+
+<!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
+
+`@kerfjs/ui:editor-frame` · Kerf UI · component · Structure
+
+A bounded editor surface with a fixed toolbar and one native source or preview scroll owner.
+
+## When to use
+
+Own a framed or embedded writing surface while the app owns its native textarea, draft, and rendered preview.
+
+- A standalone Markdown or text editor needs a fixed toolbar above a bounded native textarea or preview.
+- An embedded editor needs the same source/preview anatomy without a second frame.
+
+**Not when:**
+
+- Do not use for an ordinary single form field; use TextField.
+- Do not replace the app's draft, recovery, focus, or preview behavior.
+
+**Alternatives:**
+
+- [TextField](./text-field.md) (nearest) — Use TextField for a conventional form value without editor toolbar and preview.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/editor-frame` — exports `EditorFrame`.
+- CSS: the browser build of `@kerfjs/ui/editor-frame` pulls its CSS automatically; import `@kerfjs/ui/editor-frame.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/editor-frame`](../public-api-signatures-v1.md#kerfjsuieditor-frame) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- source and preview modes
+- framed and embedded appearances
+- padded and flush insets
+- expanded overlay
+- embedded autosize or restored source height
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+- Built from: [Toolbar](./toolbar.md).
+
+## State and wiring
+
+**The app owns:** draft value; editing actions; preview rendering; recovery and focus management.
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: self · padding: self (layout role: structure). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+- Give the editor frame a label when it is a distinct region; the app labels its native textarea and supplies toolbar controls.
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Public class hooks (select for layout placement only, never to change the component's look): `kui-editor-frame`, `kui-editor-frame__toolbar`, `kui-editor-frame__surface`.
+
+Never put `kui-editor-frame`, `kui-editor-frame__toolbar`, `kui-editor-frame__surface` on an element you write; render `EditorFrame` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-color-neutral-border-normal`, `--kui-color-neutral-on-normal`, `--kui-color-surface`, `--kui-radius-l`, `--kui-shadow-l`. Set a token only where its public contract allows; prefer a prop.
+
+Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
+
+## Related
+
+- Components: [Toolbar](./toolbar.md), [TextField](./text-field.md).
+- Docs: [`docs/editor-frame.md`](../../docs/editor-frame.md).
+- UX catalog route: `?component=editor-frame`.

package/ai/components/summary-row.md

@@ -4,13 +4,14 @@
 
 `@kerfjs/ui:summary-row` · Kerf UI · component · Structure
 
-A selectable, focusable summary of one item as a list row or a board card, with a state rail, a clamped title, trailing meta, and a metadata line.
+A selectable option or static diagnostic group as a list row or board card, with a state rail, a clamped title, trailing meta, and a metadata line.
 
 ## When to use
 
 Present dense item summaries (tickets, tasks, messages) as selectable list rows or board cards with Kerf-owned selection, hover, focus, rail, clamping, list-edge rounding, and narrow compaction, without app row CSS.
 
 - A list or board shows many items as dense, selectable summaries with an identifier, a title, a timestamp, and metadata.
+- An unreadable item needs the same summary chrome with a nested recovery action but must be a labeled non-option group.
 
 **Not when:**
 
@@ -43,6 +44,8 @@ Exact prop names and types: [`@kerfjs/ui/summary-row`](../public-api-signatures-
 - list edge start, end, or only
 - title line budget
 - deferred rendering
+- static labeled group with a nested action (semanticRole=group)
+- native draggable option root for list rows and board cards
 
 ## Composition
 
@@ -64,7 +67,7 @@ Margin: none · border: self · padding: self (layout role: structure). `self` m
 
 ## Accessibility
 
-- Each SummaryRow is role=option with tabindex=0 and aria-selected; place rows in a labeled role=listbox and move focus with the arrow keys in the app. The rail is decorative; carry its meaning in text.
+- By default SummaryRow is role=option with tabindex=0 and aria-selected; place options in a labeled role=listbox and move focus with the arrow keys in the app. semanticRole=group requires ariaLabel and omits the root Tab stop and aria-selected, so a nested native action owns focus and activation. The rail is decorative; carry its meaning in text.
 
 ## Styling boundary
 

package/ai/components/value-preview.md

@@ -0,0 +1,75 @@
+# ValuePreview
+
+<!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
+
+`@kerfjs/ui:value-preview` · Kerf UI · component · Structure
+
+A bounded, read-only multiline text value with keyboard scrolling.
+
+## When to use
+
+Display a literal long value with line breaks and long tokens inside a bounded scroll region.
+
+- A read-only value may have multiple lines or long unbroken text and needs bounded scrolling, such as a conflict version.
+
+**Not when:**
+
+- Do not use for editing; use a multiline TextField.
+- Do not use for short label/value facts; use ValueTable.
+
+**Alternatives:**
+
+- [ValueTable](./value-table.md) (nearest) — Use ValueTable for rows of short labelled facts.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/value-preview` — exports `ValuePreview`.
+- CSS: the browser build of `@kerfjs/ui/value-preview` pulls its CSS automatically; import `@kerfjs/ui/value-preview.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/value-preview`](../public-api-signatures-v1.md#kerfjsuivalue-preview) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- typed minimum and maximum height
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+- Built from: [SunkenPanel](./sunken-panel.md).
+
+## State and wiring
+
+**The app owns:** value; empty wording.
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: none · padding: none (layout role: structure). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+- Give the focusable output a label so keyboard and screen-reader users can identify and scroll it.
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Public class hooks (select for layout placement only, never to change the component's look): `kui-value-preview`.
+
+Never put `kui-value-preview` on an element you write; render `ValuePreview` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-color-text`, `--kui-font-xs`, `--kui-focus-ring`. Set a token only where its public contract allows; prefer a prop.
+
+Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
+
+## Related
+
+- Components: [SunkenPanel](./sunken-panel.md), [ValueTable](./value-table.md).
+- Docs: [`docs/value-preview.md`](../../docs/value-preview.md).
+- UX catalog route: `?component=value-preview`.