@kerfjs/ui 5.0.0-beta.45 → 5.0.0-beta.47

package/docs/ux-demo.md

@@ -19,7 +19,7 @@ deterministic state, and semantic layout owners from the [recipe guide](./recipe
 - It imports public component subpaths, exercising their browser-selected reachable CSS rather than a catalog-only style path.
 - The `ListActionRow` route demonstrates sibling primary/trailing native controls, independent disabled states, controlled selection, first-line leading-icon alignment for wrapped labels, and an application-owned native popover relationship without nesting controls. The `ListItem` route demonstrates the same multiline leading-icon anchor alongside its single-control navigation contract.
 - The `AppTab` and `TabBar` routes are focused component specimens: AppTab shows its selected, compact, segmented, icon-only, truncation, placeholder, metadata, and close-icon axes inside the required tablist context; TabBar shows its rail, segmented, inspector, allocation, placement, and accessory-zone axes without application readouts. The separate `Application tabs composition` route demonstrates controlled selection, matching panel content, overflow, adding, closing, keyboard/pointer reordering, and application-owned ordering. The `ResizableRegion` route likewise replaces only the decorative handle glyph while retaining separator semantics and shared wiring.
-- Every first-party visual component and every free Web Awesome 3.12 component has its own stable `?component=<id>` URL and focused demo. Composite header, menu, feedback, and theme scenarios remain addressable alongside their subcomponents; the root opens the first Kerf component.
+- Every first-party visual component and every free Web Awesome 3.12 component has its own stable `?component=<id>` URL and focused demo. Composite header, menu, and feedback scenarios remain addressable alongside their subcomponents; the root opens the first Kerf component. The former aggregate Web Awesome theme specimen is intentionally omitted because its component families are covered by those focused routes.
 - `ai/component-catalog.json` is the canonical catalog metadata. A deterministic checked-in projection supplies the demo's unique id, category, kind (`component`, `composition`, or `recipe`), source (`kerf` or `webawesome`), name, description, recommendation, direct `uses` dependencies, existing documentation path, and demo-source path; first-party, recipe, and Web Awesome renderer maps are exhaustively typed against its generated id unions. Non-supported Web Awesome recommendations project to a visible `Discouraged` sidebar tag, with Popup as the deliberate conditional exception. Demo paths resolve to the matching `ui/ux-demo/demos/<id>.tsx` or `ui/ux-demo/recipes/*.tsx` file, or to `ui/ux-demo/webawesome-demos.tsx` for Web Awesome entries. `ui/ux-demo/main.tsx` owns only the catalog shell, shared state, routing, and interaction wiring. First-party component entries additionally derive `ui/src/<public-subpath>.tsx` from their canonical `delivery.browserImport` or opt-in `delivery.moduleImport`.
 - Every detail footer groups compact `Demo source` and `Guidance` actions; first-party component details also expose `Component source`. Web Awesome details say `Integration guidance` to distinguish the local integration contract from the upstream component implementation. Each button retains its repository-relative path in the DOM for verification and uses a deploy-safe absolute GitHub blob URL with a contextual new-tab name; the demo does not depend on a local source server or add a package runtime export. At phone widths, the resource group and related-component selector stack as full-width rows, with any resource overflow contained locally so labels cannot overlap the selector or widen the document.
 - The master/detail shell groups first-party routes by category with production `ListHeader` and `ListItem` components. Catalog entries can supply short reusable trailing tags; the Web Awesome projection uses them to label exactly the 15 discouraged choices. The 70 ecosystem components live in a separate `Web Awesome` disclosure with seven subgroups, so they remain discoverable without being presented as first-class `@kerfjs/ui` exports. Direct Web Awesome routes open the disclosure and reveal the selected row at wide sizes; narrow layouts keep the expanded list in document flow rather than introducing a competing nested scroller.
@@ -31,12 +31,13 @@ deterministic state, and semantic layout owners from the [recipe guide](./recipe
 - The `DisclosureArrow` route renders the production 18px root-scaled default without a catalog-only size override. Its two native buttons independently control the default right-to-down chevron and a recognizable right-facing replacement arrow with left-to-up custom directions; both use shortest-path rotation and their names stay stable while `aria-expanded` communicates state. Browser coverage verifies the custom clockwise path, pointer and native keyboard activation, focus, narrow and 200%-zoom stacking with contained labels, consumer sizing, and the independent `.5` Web Awesome glyph scale retained by Kerf `Select`.
 - A detail with relationships renders one content-fitted `Components` footer selector: `Uses` links to direct dependencies and `Used by` links to reverse dependents. Its popup owns the standard surface inset so headings and even long component names stay clear of the menu border. Choosing either navigates to that component's demo. The relationship group is absent when both sets are empty; no duplicate summary is rendered.
 - Demo-only CSS supplies only the catalog shell and stages; component appearance stays in package CSS. Decorative chrome and Web Awesome controls share the same semantic system palette instead of carrying a separate demo identity.
-- Scenarios use deterministic data and cover real variants, long content, disabled state, selection, progress, feedback, overlays, media, helpers, and stateful interactions. The Web Awesome theme route remains the broad system view, while individual action, form, layout, navigation, feedback, media, and helper routes provide focused specimens; ListItem and ListHeader demonstrate typed domain metadata, protected native button/disclosure semantics, and a native popover trigger relationship without product props; the Headers composition demonstrates direct toolbar headings with an extra-large title, optional supporting copy, and grouped icon/actions; the Select route verifies that option icons survive unrelated Kerf rerenders and selected slot content follows value changes; the Animation route exposes preset, easing, duration, playback-rate, and transport controls with live lifecycle status; observer routes provide user-driven intersection, mutation, and resize events with live results; ToolbarControlGroup exposes all eight Hot Sheet 2 variants, loads the Web Awesome registrations needed by its popup specimen, and preserves the upgraded dropdown's managed light-DOM children across Kerf rerenders; the Toolbar route composes a collapsible TokenSearchField inside a group, animates between the empty iconic and complete field states, stays open while populated, and focuses the revealed editor; SegmentedControl covers toolbar, rounded-rectangle, pill, equal-width, and disabled presentations; TokenSearchField covers editable ordered chips, pointer and keyboard removal, caret-preserving controlled deletion, editing, clearing, free text, disabled state, and fixed first-line alignment while content wraps; StateBanner exposes every built-in tone with tone-tinted badges plus a scoped override; the Application tabs composition demonstrates overflow, edge autoscroll, and controlled pointer/keyboard reordering.
+- Scenarios use deterministic data and cover real variants, long content, disabled state, selection, progress, feedback, overlays, media, helpers, and stateful interactions. Individual Web Awesome action, form, layout, navigation, feedback, media, and helper routes provide focused theme specimens without a redundant aggregate route; ListItem and ListHeader demonstrate typed domain metadata, protected native button/disclosure semantics, and a native popover trigger relationship without product props; the Headers composition demonstrates direct toolbar headings with an extra-large title, optional supporting copy, and grouped icon/actions; the Select route verifies that option icons survive unrelated Kerf rerenders and selected slot content follows value changes; the Animation route exposes preset, easing, duration, playback-rate, and transport controls with live lifecycle status; observer routes provide user-driven intersection, mutation, and resize events with live results; ToolbarControlGroup exposes all eight Hot Sheet 2 variants, loads the Web Awesome registrations needed by its popup specimen, and preserves the upgraded dropdown's managed light-DOM children across Kerf rerenders; the Toolbar route composes a collapsible TokenSearchField inside a group, animates between the empty iconic and complete field states, stays open while populated, and focuses the revealed editor; SegmentedControl covers toolbar, rounded-rectangle, pill, equal-width, and disabled presentations; TokenSearchField covers editable ordered chips, pointer and keyboard removal, caret-preserving controlled deletion, editing, clearing, free text, disabled state, and fixed first-line alignment while content wraps; StateBanner exposes every built-in tone with tone-tinted badges plus a scoped override; the Application tabs composition demonstrates overflow, edge autoscroll, and controlled pointer/keyboard reordering.
 - The ToolbarControlGroup route also demonstrates the public compact/tight,
   mixed-content, filled-selection, nested-dropdown, and avatar/scrim contracts
   added for consumers that previously restyled group descendants. The compact
-  mixed specimen keeps its separator, trigger label, and caret inside both pill
-  and rounded group shapes. Avatar images are chrome rather than nested `img`
+  mixed specimen keeps its connected separator plus the standard 8px dropdown
+  trigger inset, label, and caret inside both pill and rounded group shapes.
+  Avatar images are chrome rather than nested `img`
   elements: a lone avatar paints the group, while a multi-button avatar group
   paints only the pressed selection, with contain fitting in both cases. Its
   collapsible-search specimen follows the selected group shape with a
@@ -46,6 +47,6 @@ deterministic state, and semantic layout owners from the [recipe guide](./recipe
 - The footer action log is an `aria-live` region, making interactions visible to both people and browser tests.
 - The focused Toast route calls Web Awesome's documented programmatic stack API and notes that Hot Sheet 2 still uses its own app-level toast implementation; the catalog demonstrates ecosystem support without implying current product adoption.
 - Browser coverage walks every Kerf, composition, and Web Awesome route, checks every listed Web Awesome custom element is registered in its focused specimen, exercises the ecosystem disclosure and both relationship directions, validates offline source/guidance hrefs and accessible wide/narrow/200%-zoom wrapping, and covers tab selection/reordering/overflow, semantic palettes and scoped overrides, light/dark rendering, toolbar popup and responsive find behavior, single/multiline search alignment, menu alignment, banner urgency, keyboard resizing, live custom-element values, and representative wide/narrow captures.
-- The production build keeps the catalog shell and Kerf routes in the entry chunk, then dynamically imports the complete Web Awesome specimen and registration surface when an ecosystem route, the broad Web Awesome theme route, or the ToolbarControlGroup popup specimen is selected. Directly addressed routes pass through the same loader.
+- The production build keeps the catalog shell and Kerf routes in the entry chunk, then dynamically imports the complete Web Awesome specimen and registration surface when an ecosystem route or the ToolbarControlGroup popup specimen is selected. Directly addressed routes pass through the same loader.
 
 Before handoff, inspect the actual captures for readability, context, alignment, clipping, spacing, responsiveness, focus, and obvious defects. Fix and recapture rather than treating the screenshot as proof by itself.

package/docs/webawesome-theme.md

@@ -97,6 +97,11 @@ tiers:
   complete surface and the inset within it. Accordion applies the outer margin
   once to the group rather than separating connected items; Card's header,
   body, and footer all receive the full inset.
+- `appearance="sunken"` is a Kerf theme extension for Accordion, Card, and
+  Details. It removes raised chrome, paints the lowered semantic surface, and
+  uses the shared rounded-rectangle radius. Override
+  `--kui-wa-sunken-background` or `--kui-wa-sunken-radius` on an instance or
+  containing scope when that surface needs different tokens.
 - `--kui-wa-container-inset` defaults to the 16px homogeneous-group step. Tab
   Panel retains this roomier tier for unframed panel content. Dialog body uses
   the 8px surface inset, while its footer uses the 16px container inset so
@@ -111,9 +116,19 @@ parts, which CSS shadow parts do not support.
 
 Badge remains intentionally compact at Web Awesome's intrinsic `0.375em` block /
 `0.625em` inline padding (4.5px / 7.5px at its default 12px text size): it is a
-short status or count, not a content item. Breadcrumb has no bordered or filled
-container, and Scroller delegates item chrome to its slotted children, so both
-retain their upstream geometry. Web Awesome 3.12's free catalog has
+short status or count, not a content item. A badge with `appearance="filled"` or
+`appearance="filled-outlined"` uses its variant's quiet fill with normal text by
+default so every shipped semantic variant meets WCAG AA for that small text;
+filled-outlined keeps its normal variant border. Accent badges keep their loud
+fills, with brand, success, and danger using a dark foreground that clears AA in
+both themes (neutral and warning retain their already-safe variant foregrounds).
+Override
+`--kui-wa-badge-filled-background` and `--kui-wa-badge-filled-foreground` on a
+badge or containing scope when a product needs a different contrast-safe pair,
+or `--kui-wa-badge-accent-foreground` for a reviewed accent foreground.
+Breadcrumb has no bordered or filled container, and Scroller delegates item chrome
+to its slotted children, so both retain their upstream geometry. Web Awesome
+3.12's free catalog has
 `wa-dropdown-item`, but no `wa-menu-item`; the theme therefore styles the
 supported dropdown item rather than carrying a dead selector.
 
@@ -174,8 +189,9 @@ generic Kerf wrappers around them. Their variants and appearances already read
 the semantic palette above, and importing their component modules remains
 independent and tree-shakeable.
 
-- Use `wa-badge pill` for compact status, count, or activity labels. Hot Sheet
-  2's pill-shaped ticket status treatment is the reference shape.
+- Use `wa-badge pill appearance="filled"` for compact status, count, or activity
+  labels. Hot Sheet 2's quiet, contrast-safe pill-shaped ticket status treatment
+  is the reference shape.
 - Use the default, non-pill `wa-tag` for categories, filters, and removable
   selections. Its medium-radius rounded rectangle keeps tags distinct from
   status badges. Handle the bubbling `wa-remove` event in the feature that owns

package/llms.txt

@@ -115,6 +115,11 @@ maintain a central style list. Configure JSX with `"jsxImportSource": "kerfjs"`.
   the surface (8px) and container (16px) tiers respectively, independent of the
   dialog's shared `--spacing`. Override the tier at the narrowest useful scope
   instead of restyling individual shadow parts.
+  Filled badges use each semantic variant's quiet fill with normal text for
+  WCAG-AA compact-copy contrast. Override
+  `--kui-wa-badge-filled-background` and
+  `--kui-wa-badge-filled-foreground` as a contrast-safe pair instead of adding
+  host selectors.
   When a dialog provides another dismissal affordance, add `hide-actions` to
   the `wa-dialog` host; the theme hides its directly exported `header-actions`
   part without an unsupported chained `::part()` selector.
@@ -160,9 +165,11 @@ maintain a central style list. Configure JSX with `"jsxImportSource": "kerfjs"`.
   toolbar.
 - **Use `Text` for ordinary semantic headings and paragraphs outside toolbar
   title zones.** Omit `variant` for the default `p`, or pass `h1`–`h6` based on
-  the document outline. It passes native attributes through and owns the standard
-  transparent border plus item padding; keep toolbar titles on `ToolbarText` and
-  list-aligned bare prose on `ListInsetText`.
+  the document outline. Independently compose `tone="quiet|danger"`,
+  `size="compact"`, and `font="monospace"` for supporting, error, compact, and
+  code roles instead of global utility classes. It passes native attributes
+  through and owns the standard transparent border plus item padding; keep
+  toolbar titles on `ToolbarText` and list-aligned bare prose on `ListInsetText`.
 - **Space by the five-step scale, by relationship not by eye.** `0`
   `--kui-space-none`, `4px` `--kui-space-2xs`, `8px` `--kui-space-xs` (inside a
   group), `16px` `--kui-space-m`, `24px` `--kui-space-l` (between major differing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kerfjs/ui",
-  "version": "5.0.0-beta.45",
+  "version": "5.0.0-beta.47",
   "description": "Accessible, composable UI primitives for kerf applications.",
   "type": "module",
   "license": "MIT",

package/dist/chunk-QM4GQ7W3.js

@@ -1,17 +0,0 @@
-import { jsx } from 'kerfjs/jsx-runtime';
-
-// src/text.tsx
-function Text({
-  variant: Variant = "p",
-  children,
-  class: classValue = "",
-  className = "",
-  ...attributes
-}) {
-  const classes = `kui-text ${classValue} ${className}`.trim();
-  return /* @__PURE__ */ jsx(Variant, { ...attributes, class: classes, "data-component": "text", children });
-}
-
-export { Text };
-
-//# sourceMappingURL=chunk-QM4GQ7W3.js.map

package/dist/chunk-QM4GQ7W3.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/text.tsx"],"names":[],"mappings":";;;AAwBO,SAAS,IAAA,CAAK;AAAA,EACnB,SAAS,OAAA,GAAU,GAAA;AAAA,EACnB,QAAA;AAAA,EACA,OAAO,UAAA,GAAa,EAAA;AAAA,EACpB,SAAA,GAAY,EAAA;AAAA,EACZ,GAAG;AACL,CAAA,EAAc;AACZ,EAAA,MAAM,UAAU,CAAA,SAAA,EAAY,UAAU,CAAA,CAAA,EAAI,SAAS,GAAG,IAAA,EAAK;AAC3D,EAAA,uBACE,GAAA,CAAC,WAAS,GAAG,UAAA,EAAY,OAAO,OAAA,EAAS,gBAAA,EAAe,QACrD,QAAA,EACH,CAAA;AAEJ","file":"chunk-QM4GQ7W3.js","sourcesContent":["import type { KerfBaseAttrs } from 'kerfjs/jsx-runtime';\n\nimport type { KerfUiContent } from './semantic-content.js';\n\nexport type TextVariant = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'p';\n\nexport type TextContent =\n  KerfUiContent | string | number | readonly TextContent[];\n\nexport type TextProps = Omit<\n  KerfBaseAttrs,\n  'children' | 'class' | 'className'\n> & {\n  /** Native heading or paragraph element to render. Defaults to `p`. */\n  variant?: TextVariant;\n  children: TextContent;\n  class?: string;\n  className?: string;\n};\n\n/**\n * Semantic heading or paragraph text with the standard content-item padding.\n * All ordinary native heading/paragraph attributes pass through to the element.\n */\nexport function Text({\n  variant: Variant = 'p',\n  children,\n  class: classValue = '',\n  className = '',\n  ...attributes\n}: TextProps) {\n  const classes = `kui-text ${classValue} ${className}`.trim();\n  return (\n    <Variant {...attributes} class={classes} data-component=\"text\">\n      {children}\n    </Variant>\n  );\n}\n"]}