@kerfjs/ui 5.0.0-beta.11 → 5.0.0-beta.12

package/README.md

@@ -103,6 +103,8 @@ as a `New` marker.
 | `ListActionRow` | `@kerfjs/ui/list-action-row` | `@kerfjs/ui/list-action-row.css` |
 | `ListItem` | `@kerfjs/ui/list-item` | `@kerfjs/ui/list-item.css` |
 | `ListHeader` | `@kerfjs/ui/list-header` | `@kerfjs/ui/list-header.css` |
+| `ListInsetControl` | `@kerfjs/ui/list-inset-control` | `@kerfjs/ui/list-inset-control.css` |
+| `ListInsetText` | `@kerfjs/ui/list-inset-text` | `@kerfjs/ui/list-inset-text.css` |
 | Pane, content, and navigation composition | — | `@kerfjs/ui/layout.css` |
 | `ResizableRegion` | `@kerfjs/ui/resizable-region` | `@kerfjs/ui/resizable-region.css` |
 | `wireResizableRegions` | `@kerfjs/ui/wire-resizable-regions` | — |

package/ai/component-catalog.json

@@ -385,10 +385,12 @@
         "ToolbarControlGroup"
       ],
       "useWhen": [
-        "Group related controls inside a toolbar with a supported visual treatment."
+        "Group related controls inside a toolbar with a supported visual treatment.",
+        "Fill it with plain <button> controls (the group styles > button fully); use wa-button only for a Web Awesome feature such as a wa-dropdown popup trigger."
       ],
       "avoidWhen": [
-        "Do not use merely to align unrelated buttons or to imitate an exclusive choice."
+        "Do not use merely to align unrelated buttons or to imitate an exclusive choice.",
+        "Do not reach for wa-button for an ordinary control inside the group — a plain <button> is the default and avoids the Web Awesome dependency."
       ],
       "alternatives": [
         {
@@ -1109,6 +1111,104 @@
         "recipe": "docs/component-selection.md#problem-to-component-matrix"
       }
     },
+    {
+      "id": "list-inset-control",
+      "name": "ListInsetControl",
+      "category": "Structure",
+      "kind": "component",
+      "source": "kerf",
+      "description": "Insets a self-bordered control into a pane/list content region.",
+      "uses": [],
+      "purpose": "Insets a self-bordered control into a pane/list content region.",
+      "publicExports": [
+        "ListInsetControl"
+      ],
+      "useWhen": [
+        "Place a control that carries its own border and padding (an input, a wa-* control) in a pane/list content region so its edges align with .kui-content items."
+      ],
+      "avoidWhen": [
+        "Do not wrap a component that already owns its content-item margin (ListItem, StateBanner, …) — that double-insets it. Use ListInsetText for bare text."
+      ],
+      "alternatives": [
+        {
+          "id": "list-inset-text",
+          "relationship": "nearest"
+        }
+      ],
+      "appOwns": [
+        "the wrapped control and its behavior"
+      ],
+      "accessibility": [
+        "A layout wrapper only; it adds no role or name — the wrapped control keeps its own."
+      ],
+      "delivery": {
+        "browserImport": "@kerfjs/ui/list-inset-control",
+        "manualCssImport": "@kerfjs/ui/list-inset-control.css",
+        "sideEffects": [
+          "browser-condition-css"
+        ]
+      },
+      "wiring": [],
+      "publicClasses": [
+        "kui-list-inset-control"
+      ],
+      "publicTokens": [
+        "--kui-layout-inline-margin"
+      ],
+      "links": {
+        "catalogRoute": "?component=list-inset-control",
+        "documentation": "docs/component-selection.md",
+        "recipe": "docs/component-selection.md#problem-to-component-matrix"
+      }
+    },
+    {
+      "id": "list-inset-text",
+      "name": "ListInsetText",
+      "category": "Structure",
+      "kind": "component",
+      "source": "kerf",
+      "description": "Gives bare text the content-item geometry so it lines up with bordered items.",
+      "uses": [],
+      "purpose": "Gives bare text the content-item geometry so it lines up with bordered items.",
+      "publicExports": [
+        "ListInsetText"
+      ],
+      "useWhen": [
+        "Line a plain text element up with bordered .kui-content items — it adds the 8px margin, 1px transparent border, and 8px padding the text lacks."
+      ],
+      "avoidWhen": [
+        "Do not use it to wrap an interactive control (use ListInsetControl), or a component that already owns its content-item geometry."
+      ],
+      "alternatives": [
+        {
+          "id": "list-inset-control",
+          "relationship": "nearest"
+        }
+      ],
+      "appOwns": [
+        "the text content"
+      ],
+      "accessibility": [
+        "A layout wrapper only; it adds no role or name."
+      ],
+      "delivery": {
+        "browserImport": "@kerfjs/ui/list-inset-text",
+        "manualCssImport": "@kerfjs/ui/list-inset-text.css",
+        "sideEffects": [
+          "browser-condition-css"
+        ]
+      },
+      "wiring": [],
+      "publicClasses": [
+        "kui-list-inset-text"
+      ],
+      "publicTokens": [],
+      "links": {
+        "catalogRoute": "?component=list-inset-text",
+        "documentation": "docs/component-selection.md",
+        "recipe": "docs/component-selection.md#problem-to-component-matrix"
+      }
+    },
     {
       "id": "tabs",
       "name": "AppTab",

package/ai/public-api-signatures-v1.md

@@ -1,6 +1,6 @@
 # Public API signatures for the UI authoring corpus
 
-Generated from emitted declarations for `@kerfjs/ui@5.0.0-beta.11` and `kerfjs@5.0.0-beta.11`. This bounded reference covers only APIs used by the seven-task corpus. It is interface evidence, not an implementation or runtime guarantee.
+Generated from emitted declarations for `@kerfjs/ui@5.0.0-beta.12` and `kerfjs@5.0.0-beta.12`. This bounded reference covers only APIs used by the seven-task corpus. It is interface evidence, not an implementation or runtime guarantee.
 
 ## `@kerfjs/ui/disclosure-arrow`
 
@@ -265,6 +265,48 @@ declare function ListItem({ label, icon, trailing, selected, action, itemId, cla
 export { ListItem, type ListItemProps };
 ```
 
+## `@kerfjs/ui/list-inset-control`
+
+```ts
+import { SafeHtml } from 'kerfjs';
+
+interface ListInsetControlProps {
+    /** Control(s) that own their own border and padding (e.g. an input, a `wa-*`). */
+    children: SafeHtml | SafeHtml[];
+    className?: string;
+}
+/**
+ * Insets a control into a pane/list content region: an 8px inline margin (so its
+ * edges line up with `.kui-content` items) and a stretch flex row with an 8px gap.
+ * Use it for controls that carry their own border and padding but no outer margin
+ * — the wrapper adds only the alignment margin and layout, not a second inset.
+ */
+declare function ListInsetControl({ children, className }: ListInsetControlProps): SafeHtml;
+
+export { ListInsetControl, type ListInsetControlProps };
+```
+
+## `@kerfjs/ui/list-inset-text`
+
+```ts
+import { SafeHtml } from 'kerfjs';
+
+interface ListInsetTextProps {
+    /** Text (or inline content) that carries no margin, border, or padding of its own. */
+    children: SafeHtml | SafeHtml[] | string;
+    className?: string;
+}
+/**
+ * Gives bare text the content-item geometry — an 8px inline margin, a 1px
+ * transparent border, and 8px padding — so a plain string lines up with
+ * bordered `.kui-content` items (its text edge lands at the same 17px inset).
+ * Use it for text elements that have no margin, border, or padding of their own.
+ */
+declare function ListInsetText({ children, className }: ListInsetTextProps): SafeHtml;
+
+export { ListInsetText, type ListInsetTextProps };
+```
+
 ## `@kerfjs/ui/panel-header`
 
 ```ts

package/ai/skill.md

@@ -63,7 +63,7 @@ Hard rules:
 14. Treat the complete Web Awesome catalog as support coverage, not a recommendation list. Consider Popup when it replaces custom anchored positioning. Prefer Kerf `Select` over direct Dropdown/Dropdown Item/Select/Option composition, `SegmentedControl` over Button Group, `TabBar` or `SegmentedControl` over Web Awesome Tabs, `LucideIcon` over Web Awesome Icon, and `ResizableRegion` over Split Panel. Use Tree/Tree Item, Animated Image, and Comparison only for a specific required behavior; avoid Zoomable Frame.
 15. Build sidebars, main areas, inspectors, and dialogs from `@kerfjs/ui/layout.css`: an unpadded `.kui-pane`, optional `.kui-pane__toolbar`, one scrolling `.kui-pane__content`, and optional `.kui-pane__footer`. Add `.kui-content` for 24px major vertical separation and `.kui-content-item` for a child-owned 8px inline margin, 1px transparent-or-visible border, 8px padding, and 12px radius. Use the pill modifier for 22px. Do not pad pane shells or duplicate item geometry in wrappers.
 16. Keep a visible collapsible pane's collapse control in its own toolbar. When hidden, move its restore control into the adjacent main toolbar on the corresponding logical edge: leading for an inline-start sidebar and trailing for an inline-end inspector. Collapse the pane completely; do not preserve an empty icon-only rail.
-16. The only direct children of a `Toolbar` zone (`leading`/`center`/`trailing`) are `ToolbarText` (identity/title text) and `ToolbarControlGroup`; never drop bare buttons, inputs, links, or arbitrary markup straight into a zone. `SegmentedControl`, `Select`, a collapsible `TokenSearchField`, and Web Awesome controls all live inside a `ToolbarControlGroup`. A popup menu in a toolbar is a `single` `ToolbarControlGroup` wrapping a `wa-dropdown` whose `slot="trigger"` `wa-button` is the toolbar button and whose `wa-dropdown-item`s are the menu, with the dropdown kept under `data-morph-skip-children`. `PanelHeader` composes these for you as a panel/dialog/page heading. Wrap every toolbar item, including dormant text, in `ToolbarControlGroup`. A group remains 44px outside (`calc(2px + remify(42px))`) when its border/background are transparent; use 8px between groups and inside items. Split dormant and interactive regions: `ListHeader` fills the available inline width and keeps its label and mutually exclusive semantic count or non-count `badge` together, with an independent logical-end 44px action unless disclosure mode makes the title cluster the button. Its action visual defaults to 18px through `--kui-list-header-action-icon-size`; never shrink the target to match it. Pass every non-negative safe-integer section quantity through `count` with a localized full spoken `countLabel`; never concatenate it into `label` or put a number in `badge`. `ListItem.trailing` is dormant; use `ListActionRow` when primary and trailing actions need sibling 44px native buttons. Its `label`, `icon`, and `trailingActionIcon` slots are also dormant and cannot contain controls. Let panes relocate at narrow widths instead of shrinking targets.
+16. The only direct children of a `Toolbar` zone (`leading`/`center`/`trailing`) are `ToolbarText` (identity/title text) and `ToolbarControlGroup`; never drop bare buttons, inputs, links, or arbitrary markup straight into a zone. `SegmentedControl`, `Select`, a collapsible `TokenSearchField`, and Web Awesome controls all live inside a `ToolbarControlGroup`. For an ordinary icon/action control inside a group, use a plain `<button>` (the group styles `> button` fully) — that is the default; reach for `wa-button` only when you need a Web Awesome feature, chiefly a `wa-dropdown` popup trigger. A popup menu in a toolbar is a `single` `ToolbarControlGroup` wrapping a `wa-dropdown` whose `slot="trigger"` `wa-button` is the toolbar button and whose `wa-dropdown-item`s are the menu, with the dropdown kept under `data-morph-skip-children`. `PanelHeader` composes these for you as a panel/dialog/page heading. Wrap every toolbar item, including dormant text, in `ToolbarControlGroup`. A group remains 44px outside (`calc(2px + remify(42px))`) when its border/background are transparent; use 8px between groups and inside items. Split dormant and interactive regions: `ListHeader` fills the available inline width and keeps its label and mutually exclusive semantic count or non-count `badge` together, with an independent logical-end 44px action unless disclosure mode makes the title cluster the button. Its action visual defaults to 18px through `--kui-list-header-action-icon-size`; never shrink the target to match it. Pass every non-negative safe-integer section quantity through `count` with a localized full spoken `countLabel`; never concatenate it into `label` or put a number in `badge`. `ListItem.trailing` is dormant; use `ListActionRow` when primary and trailing actions need sibling 44px native buttons. Its `label`, `icon`, and `trailingActionIcon` slots are also dormant and cannot contain controls. Let panes relocate at narrow widths instead of shrinking targets.
 17. When a recurring concept has no matching export or production recipe, keep its semantics in a thin application adapter while reusing the public layout vocabulary. The composer recipe uses one visible form surface, `PanelHeader` title/summary ids, shared 8px field/action gutters, 24px major rhythm, and a conditional StateBanner as its only nested semantic surface; do not turn every section into a card or double-inset intrinsically bordered controls. The application-local `../docs/examples/command-palette-adapter.tsx` is reference source for one such missing concept, not an `@kerfjs/ui` runtime export or catalog recipe. The application owns its registration, ranking, history, permissions, availability, shortcut policy, focus policy, dispatch, and copy. If a missing concept recurs across products, open an upstream component or recipe request.
 18. Compose `ValueTable` from typed `ValueTableRow` entries instead of handwritten `dt`/`dd` wrappers. Pass `icon` for the optional 24px leading visual; the row owns 8px of root-scaled top and bottom padding, the 8px iconless or 40px icon-bearing separator start, and the common 8px right inset.
 19. Use `PanelHeader` for a panel, dialog, or page heading, not a custom heading row. It is a plain top `Toolbar` (overriding no Toolbar styles): the leading zone holds an optional icon (a normal bordered `ToolbarControlGroup` given a brand fill with a matching border) and the title as extra-large `ToolbarText`; the app's trailing controls (typically a `ToolbarControlGroup`) go straight in the trailing zone, and the icon group is omitted when no icon is passed. Its optional `summary`/`summaryId` row stays below the title. The app owns modal behavior, focus, dismissal, command policy, and action handling.
@@ -89,6 +89,7 @@ Common mistakes:
 | Choose a listed ecosystem component by default | Apply the component-selection guidance above; catalog coverage means supported and themed, not preferred |
 | Add sidebar-specific wrapper padding | Use the unpadded `.kui-pane`; let `ListHeader`, `ListItem`, and `.kui-content-item` own their 8/1/8 geometry |
 | Put bare text or controls directly in a toolbar slot | Wrap every item in `ToolbarControlGroup`, using `appearance="borderless"` for transparent chrome |
+| Reach for `wa-button` for a plain control inside a `ToolbarControlGroup` | Use a plain `<button>` (the group styles it fully); `wa-button` is only for Web Awesome features like a `wa-dropdown` popup trigger |
 | Let the document, pane, and list all scroll | Keep fixed chrome outside one `.kui-pane__content` scroll owner per pane |
 | Invent an `@kerfjs/ui` command-palette export | Keep the semantics application-local, reuse public layout vocabulary, and propose recurring behavior upstream |
 | Handwrite `ValueTable` row wrappers or compensate their padding or separators | Compose `ValueTableRow`; its root-scaled block padding, optional icon hook, and separator geometry are public contract |

package/ai/webawesome-jsx-signatures-v1.md

@@ -1,6 +1,6 @@
 # Web Awesome JSX signatures for the UI authoring corpus
 
-Generated from the emitted `@kerfjs/ui@5.0.0-beta.11` declaration boundary. Import `@kerfjs/ui/webawesome` for type effects when authoring direct `wa-*` JSX. The module emits no runtime behavior and does not register custom elements.
+Generated from the emitted `@kerfjs/ui@5.0.0-beta.12` declaration boundary. Import `@kerfjs/ui/webawesome` for type effects when authoring direct `wa-*` JSX. The module emits no runtime behavior and does not register custom elements.
 
 ```ts
 import { KerfCustomElement } from 'kerfjs/jsx-runtime';

package/dist/browser/list-inset-control.js

@@ -0,0 +1,3 @@
+import '../styles/foundation.css';
+import '../styles/list-inset-control.css';
+export * from '../list-inset-control.js';

package/dist/browser/list-inset-text.js

@@ -0,0 +1,3 @@
+import '../styles/foundation.css';
+import '../styles/list-inset-text.css';
+export * from '../list-inset-text.js';

package/dist/catalog.js

@@ -1,7 +1,7 @@
-import { ListHeader } from './chunk-5ATCDSQS.js';
-import { ListItem } from './chunk-L4OKFDJY.js';
 import { ToolbarControlGroup } from './chunk-RNPGFQ33.js';
 import { Toolbar } from './chunk-DAFFDO33.js';
+import { ListHeader } from './chunk-5ATCDSQS.js';
+import { ListItem } from './chunk-L4OKFDJY.js';
 
 
 

package/dist/chunk-VPCTCUED.js

@@ -0,0 +1,10 @@
+import { jsx } from 'kerfjs/jsx-runtime';
+
+// src/list-inset-control.tsx
+function ListInsetControl({ children, className = "" }) {
+  return /* @__PURE__ */ jsx("div", { class: `kui-list-inset-control ${className}`.trim(), "data-component": "list-inset-control", children });
+}
+
+export { ListInsetControl };
+
+//# sourceMappingURL=chunk-VPCTCUED.js.map

package/dist/chunk-VPCTCUED.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/list-inset-control.tsx"],"names":[],"mappings":";;;AAcO,SAAS,gBAAA,CAAiB,EAAE,QAAA,EAAU,SAAA,GAAY,IAAG,EAA0B;AACpF,EAAA,uBAAO,GAAA,CAAC,KAAA,EAAA,EAAI,KAAA,EAAO,CAAA,uBAAA,EAA0B,SAAS,GAAG,IAAA,EAAK,EAAG,gBAAA,EAAe,oBAAA,EAAsB,QAAA,EAAS,CAAA;AACjH","file":"chunk-VPCTCUED.js","sourcesContent":["import type { SafeHtml } from 'kerfjs';\n\nexport interface ListInsetControlProps {\n  /** Control(s) that own their own border and padding (e.g. an input, a `wa-*`). */\n  children: SafeHtml | SafeHtml[];\n  className?: string;\n}\n\n/**\n * Insets a control into a pane/list content region: an 8px inline margin (so its\n * edges line up with `.kui-content` items) and a stretch flex row with an 8px gap.\n * Use it for controls that carry their own border and padding but no outer margin\n * — the wrapper adds only the alignment margin and layout, not a second inset.\n */\nexport function ListInsetControl({ children, className = '' }: ListInsetControlProps) {\n  return <div class={`kui-list-inset-control ${className}`.trim()} data-component=\"list-inset-control\">{children}</div>;\n}\n"]}

package/dist/chunk-XE4OX6AZ.js

@@ -0,0 +1,10 @@
+import { jsx } from 'kerfjs/jsx-runtime';
+
+// src/list-inset-text.tsx
+function ListInsetText({ children, className = "" }) {
+  return /* @__PURE__ */ jsx("div", { class: `kui-list-inset-text ${className}`.trim(), "data-component": "list-inset-text", children });
+}
+
+export { ListInsetText };
+
+//# sourceMappingURL=chunk-XE4OX6AZ.js.map

package/dist/chunk-XE4OX6AZ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/list-inset-text.tsx"],"names":[],"mappings":";;;AAcO,SAAS,aAAA,CAAc,EAAE,QAAA,EAAU,SAAA,GAAY,IAAG,EAAuB;AAC9E,EAAA,uBAAO,GAAA,CAAC,KAAA,EAAA,EAAI,KAAA,EAAO,CAAA,oBAAA,EAAuB,SAAS,GAAG,IAAA,EAAK,EAAG,gBAAA,EAAe,iBAAA,EAAmB,QAAA,EAAS,CAAA;AAC3G","file":"chunk-XE4OX6AZ.js","sourcesContent":["import type { SafeHtml } from 'kerfjs';\n\nexport interface ListInsetTextProps {\n  /** Text (or inline content) that carries no margin, border, or padding of its own. */\n  children: SafeHtml | SafeHtml[] | string;\n  className?: string;\n}\n\n/**\n * Gives bare text the content-item geometry — an 8px inline margin, a 1px\n * transparent border, and 8px padding — so a plain string lines up with\n * bordered `.kui-content` items (its text edge lands at the same 17px inset).\n * Use it for text elements that have no margin, border, or padding of their own.\n */\nexport function ListInsetText({ children, className = '' }: ListInsetTextProps) {\n  return <div class={`kui-list-inset-text ${className}`.trim()} data-component=\"list-inset-text\">{children}</div>;\n}\n"]}

package/dist/index.d.ts

@@ -4,6 +4,8 @@ export { EmptyState, EmptyStateProps } from './empty-state.js';
 export { FloatingToolbar, FloatingToolbarPosition, FloatingToolbarProps } from './floating-toolbar.js';
 export { ListActionRow, ListActionRowProps } from './list-action-row.js';
 export { ListHeader, ListHeaderProps } from './list-header.js';
+export { ListInsetControl, ListInsetControlProps } from './list-inset-control.js';
+export { ListInsetText, ListInsetTextProps } from './list-inset-text.js';
 export { ListItem, ListItemProps } from './list-item.js';
 export { LoadingSpinner, LoadingSpinnerProps } from './loading-spinner.js';
 export { LucideIcon, LucideIconProps, LucideNode } from './lucide-icon.js';

package/dist/index.js

@@ -1,21 +1,23 @@
 export { wireResizableRegions } from './chunk-AQNKJRFH.js';
 export { reorderTabs, wireTabBars } from './chunk-XXMOARTH.js';
 export { wireTokenSearchFields } from './chunk-LCOBDOCC.js';
+export { TabBar } from './chunk-AVZHJN6C.js';
 export { TokenSearchField, placeTokenSearchCaret, readTokenSearchField } from './chunk-7LDCTU7D.js';
 export { ValueTable, ValueTableRow } from './chunk-37T3VNIZ.js';
+export { PanelHeader } from './chunk-XE5ZLPCC.js';
 export { SegmentedControl } from './chunk-YGN7OMLT.js';
 export { Select } from './chunk-CH4SQ6H5.js';
+export { ResizableRegion, clampRegionSize, resizeRegionFromPointer } from './chunk-M5JRI6MN.js';
 export { StateBanner } from './chunk-I7INRJO4.js';
-export { TabBar } from './chunk-AVZHJN6C.js';
 export { ListActionRow } from './chunk-7JB7VPRI.js';
-export { PanelHeader } from './chunk-XE5ZLPCC.js';
+export { ListInsetControl } from './chunk-VPCTCUED.js';
+export { ListInsetText } from './chunk-XE4OX6AZ.js';
 export { ToolbarText } from './chunk-RUNWEPR4.js';
-export { ResizableRegion, clampRegionSize, resizeRegionFromPointer } from './chunk-M5JRI6MN.js';
 export { AppTab } from './chunk-2Z5TWHKQ.js';
-export { ListHeader } from './chunk-5ATCDSQS.js';
-export { ListItem } from './chunk-L4OKFDJY.js';
 export { ToolbarControlGroup } from './chunk-RNPGFQ33.js';
 export { Toolbar } from './chunk-DAFFDO33.js';
+export { ListHeader } from './chunk-5ATCDSQS.js';
+export { ListItem } from './chunk-L4OKFDJY.js';
 
 export { Skeleton } from './chunk-B24C4A6T.js';
 export { DisclosureArrow } from './chunk-56RJXPHG.js';

package/dist/list-inset-control.d.ts

@@ -0,0 +1,16 @@
+import { SafeHtml } from 'kerfjs';
+
+interface ListInsetControlProps {
+    /** Control(s) that own their own border and padding (e.g. an input, a `wa-*`). */
+    children: SafeHtml | SafeHtml[];
+    className?: string;
+}
+/**
+ * Insets a control into a pane/list content region: an 8px inline margin (so its
+ * edges line up with `.kui-content` items) and a stretch flex row with an 8px gap.
+ * Use it for controls that carry their own border and padding but no outer margin
+ * — the wrapper adds only the alignment margin and layout, not a second inset.
+ */
+declare function ListInsetControl({ children, className }: ListInsetControlProps): SafeHtml;
+
+export { ListInsetControl, type ListInsetControlProps };

package/dist/list-inset-control.js

@@ -0,0 +1,3 @@
+export { ListInsetControl } from './chunk-VPCTCUED.js';
+
+//# sourceMappingURL=list-inset-control.js.map

package/dist/list-inset-control.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"list-inset-control.js"}

package/dist/list-inset-text.d.ts

@@ -0,0 +1,16 @@
+import { SafeHtml } from 'kerfjs';
+
+interface ListInsetTextProps {
+    /** Text (or inline content) that carries no margin, border, or padding of its own. */
+    children: SafeHtml | SafeHtml[] | string;
+    className?: string;
+}
+/**
+ * Gives bare text the content-item geometry — an 8px inline margin, a 1px
+ * transparent border, and 8px padding — so a plain string lines up with
+ * bordered `.kui-content` items (its text edge lands at the same 17px inset).
+ * Use it for text elements that have no margin, border, or padding of their own.
+ */
+declare function ListInsetText({ children, className }: ListInsetTextProps): SafeHtml;
+
+export { ListInsetText, type ListInsetTextProps };

package/dist/list-inset-text.js

@@ -0,0 +1,3 @@
+export { ListInsetText } from './chunk-XE4OX6AZ.js';
+
+//# sourceMappingURL=list-inset-text.js.map

package/dist/list-inset-text.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"list-inset-text.js"}

package/dist/split-view.js

@@ -1,7 +1,7 @@
 import { NavStack } from './chunk-BLK3UEEI.js';
-
 import { ResizableRegion } from './chunk-M5JRI6MN.js';
 
+
 import { jsx, jsxs } from 'kerfjs/jsx-runtime';
 
 function SplitView({ id, label, list, detail, compact = false, detailActive = false, listTitle = "", detailTitle = "", backLabel = "Back", resizable, className = "" }) {

package/dist/styles/list-inset-control.css

@@ -0,0 +1,7 @@
+.kui-list-inset-control {
+  display: flex;
+  margin-inline: var(--kui-layout-inline-margin, 0.5rem);
+  justify-content: stretch;
+  align-items: stretch;
+  gap: 0.5rem;
+}

package/dist/styles/list-inset-text.css

@@ -0,0 +1,5 @@
+.kui-list-inset-text {
+  margin: 0 0.5rem;
+  border: 1px solid transparent;
+  padding: 0.5rem;
+}

package/docs/component-contract.md

@@ -113,7 +113,11 @@ changing geometry. `.kui-content-item--pill` selects the 22px radius.
 
 `ToolbarControlGroup` is the unit of toolbar organization, even for dormant
 text. Each group reserves `calc(2px + remify(42px))`, or 44px, with 8px between
-groups and inside items. `ListHeader` similarly separates its dormant title and
+groups and inside items. For an ordinary icon/action control inside a group, use
+a plain `<button>` — the group styles `> button` fully, and it keeps the group
+free of a Web Awesome dependency and shadow DOM. Reach for `wa-button` only when
+you need a Web Awesome feature, chiefly the `slot="trigger"` button of a
+`wa-dropdown` popup menu. `ListHeader` similarly separates its dormant title and
 optional count or badge from its optional 44px action. Use the mutually
 exclusive `count`/`countLabel` pair for non-negative safe-integer section
 quantities; reserve `badge` for non-count `SafeHtml`. Do not concatenate counts

package/docs/component-selection.md

@@ -69,6 +69,8 @@ an upstream component or recipe request.
 | Navigation row — `ListItem` | A pane or navigation area needs a selectable, disabled, dormant-trailing, or multiline action row. | Do not put a control in `trailing`; use `ListActionRow` when the trailing region must be independently interactive. Use an `<a>` for navigation that must retain link behavior, a native `<button>` for an ordinary action, or implement the complete ARIA menu widget. | Delegate its `data-action`; compose inside a `.kui-content` section. Put domain event/drop metadata in `rootAttributes` rather than adding wrapper markup. | Routing, selection, permissions, copy, action handling, and domain `data-*` values. | `@kerfjs/ui/list-item` | [Pane geometry](../README.md#pane-and-content-geometry) |
 | Navigation row with trailing action — `ListActionRow` | A full-width row needs a selectable primary action and an independently focusable trailing action. | Use `ListItem` when trailing content is dormant metadata. Do not put controls inside the row's `label`, `icon`, or `trailingActionIcon` SafeHtml slots. Do not use `AppTab` outside tablist semantics or `ToolbarControlGroup` outside a toolbar. | Delegate both action strings; update controlled selection and any popover/context-menu state in the app. | Routing, selection, both action policies, domain metadata, and popover/context-menu behavior. | `@kerfjs/ui/list-action-row` | [Accessibility](./accessibility.md#listactionrow) |
 | Navigation section heading — `ListHeader` | A menu section needs a full-width label, semantic count, non-count badge, logical-end action, or real disclosure state. | Do not concatenate counts into `label` or put numeric content in `badge`; use `count` with the localized full phrase in `countLabel`. Do not add a disclosure arrow to navigation that reveals nothing. Do not shrink its 44px action target to the 18px visual. Do not use it as a page, panel, or dialog title; use `PanelHeader`. | Delegate its optional action; the app controls expanded state and revealed content. Toggle mode supplies `DisclosureArrow` unless `actionIcon` replaces it. Use `triggerAttributes` only for domain `data-*` or a native popover relationship. | Section organization, valid count and localized count label, disclosure state and content, non-count badge content, popover target behavior, and policy. | `@kerfjs/ui/list-header` | [Pane geometry](../README.md#pane-and-content-geometry) |
+| Inset self-bordered control — `ListInsetControl` | A control that owns its own border and padding but no outer margin (a search input, a `SegmentedControl`) must line up inside a `.kui-content` list with the standard 8px inline margins and stretch to fill the row. | Do not wrap a `.kui-content-item` or a `ListItem`/`ListHeader` that already owns its inline margin — that double-insets it. Do not add ad-hoc `margin`/`padding` around a bare control to align it; use this instead. | Place the self-bordered control(s) as children; they stretch to fill. It applies only the inline margin, flex stretch, and 8px gap — the child owns its own border and padding. | The control(s), their state, and action wiring. | `@kerfjs/ui/list-inset-control` | [Pane geometry](../README.md#component-subpaths) |
+| Inset bare text — `ListInsetText` | A plain string or inline content with no margin, border, or padding of its own must sit in a `.kui-content` list with its text edge aligned to the bordered items around it. | Do not use it to wrap a component that already owns content-item geometry (`ListItem`, `StateBanner`, a `.kui-content-item`) — that double-insets it. Do not hand-roll the 8px margin / 1px border / 8px padding. | Pass the text or inline `SafeHtml` as children; it supplies the 8px inline margin, 1px transparent border, and 8px padding so the text edge lands at the standard 17px inset. | The text, copy, and localization. | `@kerfjs/ui/list-inset-text` | [Pane geometry](../README.md#component-subpaths) |
 | Application layout composition | A sidebar, main area, inspector, or dialog needs shared toolbar/content/footer and child geometry. | Do not pad the pane shell, wrap child-owned geometry in competing insets, invent unrelated centered measures, or leave an icon-only rail for a hidden pane. | Use `.kui-pane` and one `.kui-pane__content`; add `.kui-content` and `.kui-content-item` as needed. A visible pane owns collapse in its toolbar; move a hidden inline-start pane's restore control to the main toolbar leading edge and an inline-end pane's restore control to its trailing edge. | Layout hierarchy, reading width, scroll ownership, responsive relocation, and pane visibility state. | `@kerfjs/ui/layout.css` | [Pane anatomy](./layout.md#anatomy) |
 | Menu composition | Navigation sections need full-size rows and the same content-item geometry as every other pane. | Do not add sidebar-specific wrapper padding, shrink targets to icon size, nest an interactive trailing control in `ListItem`, or use a chevron on a row that does not disclose content. Use ordinary links for a different navigation contract. | Compose `ListHeader`, `ListItem`, and `ListActionRow` in `.kui-content`; use `ListHeader` toggle mode with real controlled content, and use `.kui-content-item` for other surfaces plus a pane footer for toolbar actions. | Information architecture, disclosure content and state, responsive drawer/shell behavior, and token overrides. | `@kerfjs/ui/layout.css` | [Pane geometry](../README.md#pane-and-content-geometry) |
 | Resizable application pane — `ResizableRegion`, `clampRegionSize`, `resizeRegionFromPointer` | A controlled split pane needs the Kerf separator, collapse state, pointer plus keyboard resizing, or a product-specific decorative grip. | Do not use it for a static two-column layout; use CSS grid. Prefer it over Web Awesome `wa-split-panel` unless that component's distinct API is required. Keep `handleIcon` noninteractive. | Call `wireResizableRegions` from `@kerfjs/ui/wire-resizable-regions` once and retain its disposer. | Size signal, min/max policy, collapse policy, persistence, and optional decorative handle icon. | `@kerfjs/ui/resizable-region` | [ResizableRegion contract](./accessibility.md#resizableregion) |

package/llms.txt

@@ -47,9 +47,12 @@ maintain a central style list. Configure JSX with `"jsxImportSource": "kerfjs"`.
 - **Toolbars hold only `ToolbarText` and `ToolbarControlGroup`.** Never put a bare
   button, input, link, or loose markup in a `leading`/`center`/`trailing` zone.
   Wrap every control — `SegmentedControl`, `Select`, a collapsible
-  `TokenSearchField`, Web Awesome controls — inside a `ToolbarControlGroup`. A
-  toolbar popup menu is a `single` `ToolbarControlGroup` around a `wa-dropdown`
-  (its `slot="trigger"` `wa-button` is the toolbar button, kept under
+  `TokenSearchField`, Web Awesome controls — inside a `ToolbarControlGroup`. For an
+  ordinary icon/action control inside the group use a **plain `<button>`** (the
+  group styles it fully) — that is the default; reach for `wa-button` only when you
+  need a Web Awesome feature, chiefly the `slot="trigger"` button of a `wa-dropdown`
+  popup menu. A toolbar popup menu is a `single` `ToolbarControlGroup` around a
+  `wa-dropdown` (its `slot="trigger"` `wa-button` is the toolbar button, kept under
   `data-morph-skip-children`).
 - **`PanelHeader` is *the* panel/dialog/page heading.** A plain toolbar with an
   optional bordered icon group, an extra-large `ToolbarText` title, the trailing
@@ -100,7 +103,8 @@ maintain a central style list. Configure JSX with `"jsxImportSource": "kerfjs"`.
 ## Public exports
 
 `LucideIcon`, `DisclosureArrow`, `Toolbar`, `ToolbarControlGroup`, `FloatingToolbar`, `ToolbarText`,
-`PanelHeader`, `ListItem`, `ListActionRow`, `ListHeader`, `SegmentedControl`,
+`PanelHeader`, `ListItem`, `ListActionRow`, `ListHeader`, `ListInsetControl`,
+`ListInsetText`, `SegmentedControl`,
 `Select`, `TokenSearchField` (+ `readTokenSearchField`, `placeTokenSearchCaret`,
 `wireTokenSearchFields`), `AppTab`, `TabBar` (+ `wireTabBars`, `reorderTabs`),
 `ResizableRegion` (+ `wireResizableRegions`), `StateBanner`, `EmptyState`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kerfjs/ui",
-  "version": "5.0.0-beta.11",
+  "version": "5.0.0-beta.12",
   "description": "Accessible, composable UI primitives for kerf applications.",
   "type": "module",
   "license": "MIT",
@@ -84,6 +84,16 @@
       "browser": "./dist/browser/list-header.js",
       "import": "./dist/list-header.js"
     },
+    "./list-inset-control": {
+      "types": "./dist/list-inset-control.d.ts",
+      "browser": "./dist/browser/list-inset-control.js",
+      "import": "./dist/list-inset-control.js"
+    },
+    "./list-inset-text": {
+      "types": "./dist/list-inset-text.d.ts",
+      "browser": "./dist/browser/list-inset-text.js",
+      "import": "./dist/list-inset-text.js"
+    },
     "./resizable-region": {
       "types": "./dist/resizable-region.d.ts",
       "browser": "./dist/browser/resizable-region.js",
@@ -225,6 +235,8 @@
     "./list-action-row.css": "./dist/styles/list-action-row.css",
     "./list-item.css": "./dist/styles/list-item.css",
     "./list-header.css": "./dist/styles/list-header.css",
+    "./list-inset-control.css": "./dist/styles/list-inset-control.css",
+    "./list-inset-text.css": "./dist/styles/list-inset-text.css",
     "./resizable-region.css": "./dist/styles/resizable-region.css",
     "./app-tab.css": "./dist/styles/app-tab.css",
     "./catalog.css": "./dist/styles/catalog.css",