@kerfjs/ui 5.0.0-beta.10 → 5.0.0-beta.100

package/dist/tab-navigator.d.ts

@@ -0,0 +1,114 @@
+import { SafeHtml } from 'kerfjs';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import { PaneAppearance } from './pane.js';
+import './scroll-clearance-BikHljTc.js';
+
+interface TabNavigatorTabBase<Id extends string> {
+    id: Id;
+    label: string;
+    /** Decorative icon shown above the label in the bottom bar. */
+    icon?: SafeHtml;
+    /** The tab's content — typically a `NavStack` so each tab keeps its own stack. */
+    content: KerfUiContent;
+    /** Background of this scene's scrolling work surface. */
+    appearance?: PaneAppearance;
+    /** Add 8px to every side of a plain scene's scrolling content. */
+    deepInset?: boolean;
+    /** Opt into keyboard (`0`) or programmatic (`-1`) focus on this scene. */
+    tabIndex?: 0 | -1;
+    /** Keep the standard focus outline visible while this scene is active. */
+    outlined?: boolean;
+}
+/** A tab with an optional count or short-status badge. */
+interface TabNavigatorTabCountBadge {
+    /**
+     * Optional count or short status shown as a solid danger `Badge` at the
+     * top-trailing corner of the tab icon (the iOS tab-bar badge). Omitted, `''`,
+     * or non-finite numbers render no badge. The visual badge is `aria-hidden`;
+     * its meaning reaches assistive technology through `badgeLabel`.
+     *
+     * Pass `true` instead for the text-free dot (new content without a count).
+     */
+    badge?: string | number;
+    /**
+     * Localized phrase folded into the tab's accessible name as
+     * `"<label>, <badgeLabel>"` (for example `"3 unread"` → `"Inbox, 3 unread"`).
+     * Defaults to the badge text itself. Ignored when no badge renders.
+     */
+    badgeLabel?: string;
+}
+/** A tab with the text-free dot badge (new content without a count). */
+interface TabNavigatorTabDotBadge {
+    /**
+     * `true` shows a solid danger dot `Badge` at the top-trailing corner of the
+     * tab icon — the iOS tab-bar dot for new content without a count.
+     */
+    badge: true;
+    /**
+     * Required localized phrase folded into the tab's accessible name as
+     * `"<label>, <badgeLabel>"` (for example `"New activity"` →
+     * `"Feed, New activity"`). A dot has no text, so this is its only meaning.
+     */
+    badgeLabel: string;
+}
+/** One bottom-bar destination: its label, optional icon and badge, and content. */
+type TabNavigatorTab<Id extends string = string> = TabNavigatorTabBase<Id> & (TabNavigatorTabCountBadge | TabNavigatorTabDotBadge);
+/**
+ * How a {@link TabNavigator}'s tab bar relates to the active scene: `docked`
+ * below it, or `overlay` laid over its bottom edge on the translucent chrome
+ * material, so the scene's content scrolls visibly beneath the bar.
+ */
+type TabNavigatorBarPresentation = 'docked' | 'overlay';
+interface TabNavigatorProps<Id extends string = string> {
+    id: string;
+    /** Accessible name for the tab bar. */
+    label: string;
+    tabs: readonly TabNavigatorTab<Id>[];
+    /** The controlled active tab id (the app owns selection). */
+    active: NoInfer<Id>;
+    /**
+     * The bar's top separator. `auto` (default) draws it against a sunken active
+     * work surface and otherwise follows `chromeDividers`; `hidden` suppresses
+     * the line, including a scroll divider.
+     */
+    separator?: 'auto' | 'hidden';
+    /**
+     * The line over the tab bar, where it meets the active scene. `scroll`
+     * (default) shows it only while more of the scene's content lies below —
+     * never at the scroll end or when the content fits — once
+     * `wireScrollDividers` (`@kerfjs/ui/wire-scroll-dividers`) is wired above
+     * the scaffold; unwired, it does not show. `always` shows it without the
+     * wiring; `none` suppresses that scroll divider. A sunken active work
+     * surface still draws the separator unless `separator="hidden"`. The line
+     * is the bar's own 1px top border, so no state moves the bar or a tab.
+     */
+    chromeDividers?: 'scroll' | 'always' | 'none';
+    /**
+     * `docked` (default) gives the tab bar its own band below the scenes.
+     * `overlay` lays it over the active scene's bottom edge on the translucent
+     * chrome material (opaque under reduced transparency, increased contrast,
+     * or without `backdrop-filter`; `Canvas` in forced colors), 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 `--kui-edge-inset-*`
+     * context, so a plain scene, a sole `Pane`, or a `NavStack` (and its own
+     * bottom toolbar, which then sits above the bar) rests its last item clear
+     * of it. Until then it stays docked. Unselected tab labels lift halfway
+     * toward the normal text color to keep AA over the content beneath.
+     */
+    barPresentation?: TabNavigatorBarPresentation;
+    className?: string;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
+}
+/**
+ * A mobile-first, iOS-like bottom tab navigator: a bottom tab bar that switches
+ * between major sections, each tab keeping its own content (usually a `NavStack`)
+ * mounted so its stack and scroll survive a switch. Controlled — the app owns
+ * `active`; wire selection with `@kerfjs/ui/wire-tab-navigator`'s `wireTabNavigator`.
+ * On larger classes, promote the tabs to a `Workbench` rail or sidebar instead of
+ * a bottom bar. See `docs/23-app-layouts.md` §3.4.
+ */
+declare function TabNavigator<Id extends string>({ id, label, tabs, active, separator, chromeDividers, barPresentation, className, slot, }: TabNavigatorProps<Id>): SafeHtml;
+
+export { TabNavigator, type TabNavigatorBarPresentation, type TabNavigatorProps, type TabNavigatorTab };

package/dist/tab-navigator.js

@@ -0,0 +1,102 @@
+import { Badge } from './chunk-U6QYTMDB.js';
+import { ensureSunkenTexture } from './chunk-IKS72C6P.js';
+
+import { jsxs, jsx } from 'kerfjs/jsx-runtime';
+
+function TabNavigator({
+  id,
+  label,
+  tabs,
+  active,
+  separator = "auto",
+  chromeDividers = "scroll",
+  barPresentation = "docked",
+  className = "",
+  slot
+}) {
+  if (tabs.some((tab) => tab.appearance === "sunken")) ensureSunkenTexture();
+  return /* @__PURE__ */ jsxs(
+    "section",
+    {
+      class: `kui-tab-scaffold ${className}`.trim(),
+      id,
+      "data-component": "tab-scaffold",
+      "data-tab-scaffold-id": id,
+      "data-separator": separator,
+      "data-chrome-dividers": chromeDividers === "always" || chromeDividers === "none" ? chromeDividers : void 0,
+      "data-bar-presentation": barPresentation === "overlay" ? "overlay" : void 0,
+      slot,
+      children: [
+        /* @__PURE__ */ jsx("div", { class: "kui-tab-scaffold__scenes", children: tabs.map((tab) => /* @__PURE__ */ jsx(
+          "div",
+          {
+            class: "kui-tab-scaffold__scene",
+            "data-tab-scaffold-scene": tab.id,
+            "data-active": String(tab.id === active),
+            "data-appearance": tab.appearance === "sunken" ? "sunken" : void 0,
+            "data-deep-inset": tab.deepInset ? "true" : void 0,
+            "data-outlined": tab.id === active && tab.outlined ? "true" : void 0,
+            role: tab.tabIndex === void 0 ? void 0 : "tabpanel",
+            "aria-label": tab.tabIndex === void 0 ? void 0 : tab.label,
+            "aria-hidden": String(tab.id !== active),
+            tabindex: tab.id === active ? tab.tabIndex : tab.tabIndex === void 0 ? void 0 : -1,
+            children: tab.content
+          }
+        )) }),
+        /* @__PURE__ */ jsx("nav", { class: "kui-tab-scaffold__bar", role: "tablist", "aria-label": label, children: tabs.map((tab) => {
+          const dot = tab.badge === true;
+          const badgeText = dot ? void 0 : normalizeBadge(tab.badge);
+          const hasBadge = dot || badgeText !== void 0;
+          const badge = hasBadge && /* @__PURE__ */ jsx(
+            "span",
+            {
+              class: "kui-tab-scaffold__tab-badge",
+              "data-badge-kind": dot ? "dot" : "text",
+              children: badgeText === void 0 ? /* @__PURE__ */ jsx(Badge, { tone: "danger", size: "dot", ariaHidden: true }) : /* @__PURE__ */ jsx(
+                Badge,
+                {
+                  tone: "danger",
+                  appearance: "solid",
+                  size: "compact",
+                  ariaHidden: true,
+                  children: badgeText
+                }
+              )
+            }
+          );
+          const badgeLabel = hasBadge ? tab.badgeLabel?.trim() || badgeText : void 0;
+          return /* @__PURE__ */ jsxs(
+            "button",
+            {
+              type: "button",
+              class: "kui-tab-scaffold__tab",
+              role: "tab",
+              "data-tab-scaffold-tab": tab.id,
+              "aria-selected": String(tab.id === active),
+              tabindex: tab.id === active ? "0" : "-1",
+              "aria-label": badgeLabel === void 0 ? void 0 : `${tab.label}, ${badgeLabel}`,
+              "data-has-badge": hasBadge ? "true" : void 0,
+              children: [
+                tab.icon ? /* @__PURE__ */ jsxs("span", { class: "kui-tab-scaffold__tab-icon", "aria-hidden": "true", children: [
+                  tab.icon,
+                  badge
+                ] }) : badge,
+                /* @__PURE__ */ jsx("span", { class: "kui-tab-scaffold__tab-label", children: tab.label })
+              ]
+            }
+          );
+        }) })
+      ]
+    }
+  );
+}
+function normalizeBadge(badge) {
+  if (typeof badge === "number")
+    return Number.isFinite(badge) ? String(badge) : void 0;
+  if (typeof badge === "string" && badge.trim()) return badge.trim();
+  return void 0;
+}
+
+export { TabNavigator };
+
+//# sourceMappingURL=tab-navigator.js.map

package/dist/tab-navigator.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/components/navigation/tab-navigator/tab-navigator.tsx"],"names":[],"mappings":";;;;;AAyHO,SAAS,YAAA,CAAgC;AAAA,EAC9C,EAAA;AAAA,EACA,KAAA;AAAA,EACA,IAAA;AAAA,EACA,MAAA;AAAA,EACA,SAAA,GAAY,MAAA;AAAA,EACZ,cAAA,GAAiB,QAAA;AAAA,EACjB,eAAA,GAAkB,QAAA;AAAA,EAClB,SAAA,GAAY,EAAA;AAAA,EACZ;AACF,CAAA,EAA0B;AACxB,EAAA,IAAI,IAAA,CAAK,KAAK,CAAC,GAAA,KAAQ,IAAI,UAAA,KAAe,QAAQ,GAAG,mBAAA,EAAoB;AACzE,EAAA,uBACE,IAAA;AAAA,IAAC,SAAA;AAAA,IAAA;AAAA,MACC,KAAA,EAAO,CAAA,iBAAA,EAAoB,SAAS,CAAA,CAAA,CAAG,IAAA,EAAK;AAAA,MAC5C,EAAA;AAAA,MACA,gBAAA,EAAe,cAAA;AAAA,MACf,sBAAA,EAAsB,EAAA;AAAA,MACtB,gBAAA,EAAgB,SAAA;AAAA,MAChB,sBAAA,EACE,cAAA,KAAmB,QAAA,IAAY,cAAA,KAAmB,SAC9C,cAAA,GACA,MAAA;AAAA,MAEN,uBAAA,EACE,eAAA,KAAoB,SAAA,GAAY,SAAA,GAAY,MAAA;AAAA,MAE9C,IAAA;AAAA,MAEA,QAAA,EAAA;AAAA,wBAAA,GAAA,CAAC,SAAI,KAAA,EAAM,0BAAA,EACR,QAAA,EAAA,IAAA,CAAK,GAAA,CAAI,CAAC,GAAA,qBACT,GAAA;AAAA,UAAC,KAAA;AAAA,UAAA;AAAA,YACC,KAAA,EAAM,yBAAA;AAAA,YACN,2BAAyB,GAAA,CAAI,EAAA;AAAA,YAC7B,aAAA,EAAa,MAAA,CAAO,GAAA,CAAI,EAAA,KAAO,MAAM,CAAA;AAAA,YACrC,iBAAA,EAAiB,GAAA,CAAI,UAAA,KAAe,QAAA,GAAW,QAAA,GAAW,MAAA;AAAA,YAC1D,iBAAA,EAAiB,GAAA,CAAI,SAAA,GAAY,MAAA,GAAS,MAAA;AAAA,YAC1C,iBACE,GAAA,CAAI,EAAA,KAAO,MAAA,IAAU,GAAA,CAAI,WAAW,MAAA,GAAS,MAAA;AAAA,YAE/C,IAAA,EAAM,GAAA,CAAI,QAAA,KAAa,MAAA,GAAY,MAAA,GAAY,UAAA;AAAA,YAC/C,YAAA,EAAY,GAAA,CAAI,QAAA,KAAa,MAAA,GAAY,SAAY,GAAA,CAAI,KAAA;AAAA,YACzD,aAAA,EAAa,MAAA,CAAO,GAAA,CAAI,EAAA,KAAO,MAAM,CAAA;AAAA,YACrC,QAAA,EACE,IAAI,EAAA,KAAO,MAAA,GACP,IAAI,QAAA,GACJ,GAAA,CAAI,QAAA,KAAa,MAAA,GACf,MAAA,GACA,EAAA;AAAA,YAGP,QAAA,EAAA,GAAA,CAAI;AAAA;AAAA,SAER,CAAA,EACH,CAAA;AAAA,wBACA,GAAA,CAAC,KAAA,EAAA,EAAI,KAAA,EAAM,uBAAA,EAAwB,IAAA,EAAK,SAAA,EAAU,YAAA,EAAY,KAAA,EAC3D,QAAA,EAAA,IAAA,CAAK,GAAA,CAAI,CAAC,GAAA,KAAQ;AACjB,UAAA,MAAM,GAAA,GAAM,IAAI,KAAA,KAAU,IAAA;AAC1B,UAAA,MAAM,SAAA,GAAY,GAAA,GAAM,MAAA,GAAY,cAAA,CAAe,IAAI,KAAK,CAAA;AAC5D,UAAA,MAAM,QAAA,GAAW,OAAO,SAAA,KAAc,MAAA;AACtC,UAAA,MAAM,QAAQ,QAAA,oBACZ,GAAA;AAAA,YAAC,MAAA;AAAA,YAAA;AAAA,cACC,KAAA,EAAM,6BAAA;AAAA,cACN,iBAAA,EAAiB,MAAM,KAAA,GAAQ,MAAA;AAAA,cAE9B,QAAA,EAAA,SAAA,KAAc,MAAA,mBACb,GAAA,CAAC,KAAA,EAAA,EAAM,IAAA,EAAK,UAAS,IAAA,EAAK,KAAA,EAAM,UAAA,EAAU,IAAA,EAAC,CAAA,mBAE3C,GAAA;AAAA,gBAAC,KAAA;AAAA,gBAAA;AAAA,kBACC,IAAA,EAAK,QAAA;AAAA,kBACL,UAAA,EAAW,OAAA;AAAA,kBACX,IAAA,EAAK,SAAA;AAAA,kBACL,UAAA,EAAU,IAAA;AAAA,kBAET,QAAA,EAAA;AAAA;AAAA;AACH;AAAA,WAEJ;AAIF,UAAA,MAAM,aAAa,QAAA,GACf,GAAA,CAAI,UAAA,EAAY,IAAA,MAAU,SAAA,GAC1B,MAAA;AACJ,UAAA,uBACE,IAAA;AAAA,YAAC,QAAA;AAAA,YAAA;AAAA,cACC,IAAA,EAAK,QAAA;AAAA,cACL,KAAA,EAAM,uBAAA;AAAA,cACN,IAAA,EAAK,KAAA;AAAA,cACL,yBAAuB,GAAA,CAAI,EAAA;AAAA,cAC3B,eAAA,EAAe,MAAA,CAAO,GAAA,CAAI,EAAA,KAAO,MAAM,CAAA;AAAA,cACvC,QAAA,EAAU,GAAA,CAAI,EAAA,KAAO,MAAA,GAAS,GAAA,GAAM,IAAA;AAAA,cACpC,YAAA,EACE,eAAe,MAAA,GACX,MAAA,GACA,GAAG,GAAA,CAAI,KAAK,KAAK,UAAU,CAAA,CAAA;AAAA,cAEjC,gBAAA,EAAgB,WAAW,MAAA,GAAS,MAAA;AAAA,cAEnC,QAAA,EAAA;AAAA,gBAAA,GAAA,CAAI,uBACH,IAAA,CAAC,MAAA,EAAA,EAAK,KAAA,EAAM,4BAAA,EAA6B,eAAY,MAAA,EAClD,QAAA,EAAA;AAAA,kBAAA,GAAA,CAAI,IAAA;AAAA,kBACJ;AAAA,iBAAA,EACH,CAAA,GAEA,KAAA;AAAA,gCAEF,GAAA,CAAC,MAAA,EAAA,EAAK,KAAA,EAAM,6BAAA,EAA+B,cAAI,KAAA,EAAM;AAAA;AAAA;AAAA,WACvD;AAAA,QAEJ,CAAC,CAAA,EACH;AAAA;AAAA;AAAA,GACF;AAEJ;AAEA,SAAS,eACP,KAAA,EACoB;AACpB,EAAA,IAAI,OAAO,KAAA,KAAU,QAAA;AACnB,IAAA,OAAO,OAAO,QAAA,CAAS,KAAK,CAAA,GAAI,MAAA,CAAO,KAAK,CAAA,GAAI,MAAA;AAClD,EAAA,IAAI,OAAO,UAAU,QAAA,IAAY,KAAA,CAAM,MAAK,EAAG,OAAO,MAAM,IAAA,EAAK;AACjE,EAAA,OAAO,MAAA;AACT","file":"tab-navigator.js","sourcesContent":["import type { SafeHtml } from 'kerfjs';\n\nimport type { KerfUiContent } from '../../../shared/content/semantic-content.js';\nimport { ensureSunkenTexture } from '../../../shared/styles/sunken-texture.js';\nimport { Badge } from '../../feedback/badge/badge.js';\nimport type { PaneAppearance } from '../../layout/pane/pane.js';\n\ninterface TabNavigatorTabBase<Id extends string> {\n  id: Id;\n  label: string;\n  /** Decorative icon shown above the label in the bottom bar. */\n  icon?: SafeHtml;\n  /** The tab's content — typically a `NavStack` so each tab keeps its own stack. */\n  content: KerfUiContent;\n  /** Background of this scene's scrolling work surface. */\n  appearance?: PaneAppearance;\n  /** Add 8px to every side of a plain scene's scrolling content. */\n  deepInset?: boolean;\n  /** Opt into keyboard (`0`) or programmatic (`-1`) focus on this scene. */\n  tabIndex?: 0 | -1;\n  /** Keep the standard focus outline visible while this scene is active. */\n  outlined?: boolean;\n}\n\n/** A tab with an optional count or short-status badge. */\ninterface TabNavigatorTabCountBadge {\n  /**\n   * Optional count or short status shown as a solid danger `Badge` at the\n   * top-trailing corner of the tab icon (the iOS tab-bar badge). Omitted, `''`,\n   * or non-finite numbers render no badge. The visual badge is `aria-hidden`;\n   * its meaning reaches assistive technology through `badgeLabel`.\n   *\n   * Pass `true` instead for the text-free dot (new content without a count).\n   */\n  badge?: string | number;\n  /**\n   * Localized phrase folded into the tab's accessible name as\n   * `\"<label>, <badgeLabel>\"` (for example `\"3 unread\"` → `\"Inbox, 3 unread\"`).\n   * Defaults to the badge text itself. Ignored when no badge renders.\n   */\n  badgeLabel?: string;\n}\n\n/** A tab with the text-free dot badge (new content without a count). */\ninterface TabNavigatorTabDotBadge {\n  /**\n   * `true` shows a solid danger dot `Badge` at the top-trailing corner of the\n   * tab icon — the iOS tab-bar dot for new content without a count.\n   */\n  badge: true;\n  /**\n   * Required localized phrase folded into the tab's accessible name as\n   * `\"<label>, <badgeLabel>\"` (for example `\"New activity\"` →\n   * `\"Feed, New activity\"`). A dot has no text, so this is its only meaning.\n   */\n  badgeLabel: string;\n}\n\n/** One bottom-bar destination: its label, optional icon and badge, and content. */\nexport type TabNavigatorTab<Id extends string = string> =\n  TabNavigatorTabBase<Id> &\n    (TabNavigatorTabCountBadge | TabNavigatorTabDotBadge);\n\n/**\n * How a {@link TabNavigator}'s tab bar relates to the active scene: `docked`\n * below it, or `overlay` laid over its bottom edge on the translucent chrome\n * material, so the scene's content scrolls visibly beneath the bar.\n */\nexport type TabNavigatorBarPresentation = 'docked' | 'overlay';\n\nexport interface TabNavigatorProps<Id extends string = string> {\n  id: string;\n  /** Accessible name for the tab bar. */\n  label: string;\n  tabs: readonly TabNavigatorTab<Id>[];\n  /** The controlled active tab id (the app owns selection). */\n  active: NoInfer<Id>;\n  /**\n   * The bar's top separator. `auto` (default) draws it against a sunken active\n   * work surface and otherwise follows `chromeDividers`; `hidden` suppresses\n   * the line, including a scroll divider.\n   */\n  separator?: 'auto' | 'hidden';\n  /**\n   * The line over the tab bar, where it meets the active scene. `scroll`\n   * (default) shows it only while more of the scene's content lies below —\n   * never at the scroll end or when the content fits — once\n   * `wireScrollDividers` (`@kerfjs/ui/wire-scroll-dividers`) is wired above\n   * the scaffold; unwired, it does not show. `always` shows it without the\n   * wiring; `none` suppresses that scroll divider. A sunken active work\n   * surface still draws the separator unless `separator=\"hidden\"`. The line\n   * is the bar's own 1px top border, so no state moves the bar or a tab.\n   */\n  chromeDividers?: 'scroll' | 'always' | 'none';\n  /**\n   * `docked` (default) gives the tab bar its own band below the scenes.\n   * `overlay` lays it over the active scene's bottom edge on the translucent\n   * chrome material (opaque under reduced transparency, increased contrast,\n   * or without `backdrop-filter`; `Canvas` in forced colors), so content\n   * scrolls visibly beneath it, as under an iOS tab bar. `wireTabNavigator`\n   * measures the live bar (bottom safe area included) and the scenes hand\n   * its height to their content as the block-end `--kui-edge-inset-*`\n   * context, so a plain scene, a sole `Pane`, or a `NavStack` (and its own\n   * bottom toolbar, which then sits above the bar) rests its last item clear\n   * of it. Until then it stays docked. Unselected tab labels lift halfway\n   * toward the normal text color to keep AA over the content beneath.\n   */\n  barPresentation?: TabNavigatorBarPresentation;\n  className?: string;\n  /** Native named-slot assignment when composed inside a web component. */\n  slot?: string;\n}\n\n/**\n * A mobile-first, iOS-like bottom tab navigator: a bottom tab bar that switches\n * between major sections, each tab keeping its own content (usually a `NavStack`)\n * mounted so its stack and scroll survive a switch. Controlled — the app owns\n * `active`; wire selection with `@kerfjs/ui/wire-tab-navigator`'s `wireTabNavigator`.\n * On larger classes, promote the tabs to a `Workbench` rail or sidebar instead of\n * a bottom bar. See `docs/23-app-layouts.md` §3.4.\n */\nexport function TabNavigator<Id extends string>({\n  id,\n  label,\n  tabs,\n  active,\n  separator = 'auto',\n  chromeDividers = 'scroll',\n  barPresentation = 'docked',\n  className = '',\n  slot,\n}: TabNavigatorProps<Id>) {\n  if (tabs.some((tab) => tab.appearance === 'sunken')) ensureSunkenTexture();\n  return (\n    <section\n      class={`kui-tab-scaffold ${className}`.trim()}\n      id={id}\n      data-component=\"tab-scaffold\"\n      data-tab-scaffold-id={id}\n      data-separator={separator}\n      data-chrome-dividers={\n        chromeDividers === 'always' || chromeDividers === 'none'\n          ? chromeDividers\n          : undefined\n      }\n      data-bar-presentation={\n        barPresentation === 'overlay' ? 'overlay' : undefined\n      }\n      slot={slot}\n    >\n      <div class=\"kui-tab-scaffold__scenes\">\n        {tabs.map((tab) => (\n          <div\n            class=\"kui-tab-scaffold__scene\"\n            data-tab-scaffold-scene={tab.id}\n            data-active={String(tab.id === active)}\n            data-appearance={tab.appearance === 'sunken' ? 'sunken' : undefined}\n            data-deep-inset={tab.deepInset ? 'true' : undefined}\n            data-outlined={\n              tab.id === active && tab.outlined ? 'true' : undefined\n            }\n            role={tab.tabIndex === undefined ? undefined : 'tabpanel'}\n            aria-label={tab.tabIndex === undefined ? undefined : tab.label}\n            aria-hidden={String(tab.id !== active)}\n            tabindex={\n              tab.id === active\n                ? tab.tabIndex\n                : tab.tabIndex === undefined\n                  ? undefined\n                  : -1\n            }\n          >\n            {tab.content}\n          </div>\n        ))}\n      </div>\n      <nav class=\"kui-tab-scaffold__bar\" role=\"tablist\" aria-label={label}>\n        {tabs.map((tab) => {\n          const dot = tab.badge === true;\n          const badgeText = dot ? undefined : normalizeBadge(tab.badge);\n          const hasBadge = dot || badgeText !== undefined;\n          const badge = hasBadge && (\n            <span\n              class=\"kui-tab-scaffold__tab-badge\"\n              data-badge-kind={dot ? 'dot' : 'text'}\n            >\n              {badgeText === undefined ? (\n                <Badge tone=\"danger\" size=\"dot\" ariaHidden />\n              ) : (\n                <Badge\n                  tone=\"danger\"\n                  appearance=\"solid\"\n                  size=\"compact\"\n                  ariaHidden\n                >\n                  {badgeText}\n                </Badge>\n              )}\n            </span>\n          );\n          // A dot has no text fallback: without a usable badgeLabel (reachable\n          // only from untyped callers) the tab keeps its plain accessible name.\n          const badgeLabel = hasBadge\n            ? tab.badgeLabel?.trim() || badgeText\n            : undefined;\n          return (\n            <button\n              type=\"button\"\n              class=\"kui-tab-scaffold__tab\"\n              role=\"tab\"\n              data-tab-scaffold-tab={tab.id}\n              aria-selected={String(tab.id === active)}\n              tabindex={tab.id === active ? '0' : '-1'}\n              aria-label={\n                badgeLabel === undefined\n                  ? undefined\n                  : `${tab.label}, ${badgeLabel}`\n              }\n              data-has-badge={hasBadge ? 'true' : undefined}\n            >\n              {tab.icon ? (\n                <span class=\"kui-tab-scaffold__tab-icon\" aria-hidden=\"true\">\n                  {tab.icon}\n                  {badge}\n                </span>\n              ) : (\n                badge\n              )}\n              <span class=\"kui-tab-scaffold__tab-label\">{tab.label}</span>\n            </button>\n          );\n        })}\n      </nav>\n    </section>\n  );\n}\n\nfunction normalizeBadge(\n  badge: string | number | undefined,\n): string | undefined {\n  if (typeof badge === 'number')\n    return Number.isFinite(badge) ? String(badge) : undefined;\n  if (typeof badge === 'string' && badge.trim()) return badge.trim();\n  return undefined;\n}\n"]}

package/dist/text.d.ts

@@ -0,0 +1,98 @@
+import * as kerfjs from 'kerfjs';
+import { KerfBaseAttrs } from 'kerfjs/jsx-runtime';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import { S as Sides } from './sides-BPSWde0A.js';
+import { CssForegroundColor } from './css-values.js';
+
+type FieldLabelProps = Omit<KerfBaseAttrs, 'children' | 'class' | 'className'> & {
+    children: string;
+    class?: string;
+    className?: string;
+};
+/** Visible field heading for a read-only preview; use its id with aria-labelledby on the preview group. */
+declare function FieldLabel({ children, class: classValue, className, ...attributes }: FieldLabelProps): kerfjs.SafeHtml;
+
+type TextVariant = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'p' | 'span';
+type TextTone = 'default' | 'quiet' | 'danger';
+type TextSize = 'compact' | 'default' | 'large' | 'xlarge';
+type TextFont = 'default' | 'monospace';
+type TextBorder = 'transparent' | 'none';
+type TextLineHeight = 'default' | 'tight';
+type TextWrap = 'normal' | 'anywhere' | 'nowrap' | 'truncate';
+/** Inline alignment of the text's lines, in logical (writing-direction) terms. */
+type TextAlign = 'start' | 'center' | 'end';
+/**
+ * Where `wrap="truncate"` places its ellipsis: `end` (default) keeps the
+ * start, `start` keeps the tail (branch names, the end of an identifier), and
+ * `middle` keeps both the start and a suffix (file paths).
+ */
+type TextTruncate = 'end' | 'middle' | 'start';
+/**
+ * The suffix `truncate="middle"` always keeps: a number of trailing
+ * characters, or `segment` for the last path segment with its separator.
+ */
+type TextTruncateKeep = number | 'segment';
+type TextContent = KerfUiContent | string | number | readonly TextContent[];
+type TextCommonProps = Omit<KerfBaseAttrs, 'children' | 'class' | 'className'> & {
+    /** Native heading, paragraph, or inline span element to render. Defaults to `p`. */
+    variant?: TextVariant;
+    /** Semantic foreground treatment. Defaults to the inherited foreground. */
+    tone?: TextTone;
+    /** Foreground color; overrides tone when supplied, or inherits when omitted. */
+    color?: CssForegroundColor;
+    /** Text sizing independent of the native semantic element. */
+    size?: TextSize;
+    /** Font family independent of the native semantic element. */
+    font?: TextFont;
+    /** Transparent alignment border or no border when embedded in owner chrome. */
+    border?: TextBorder;
+    /** Add the shared control gutter outside selected physical edges. */
+    controlMargins?: Sides;
+    /** Remove the block variant's item padding and border in compact content. */
+    flush?: boolean;
+    /** Use compact leading for short dialog or metadata copy. */
+    lineHeight?: TextLineHeight;
+    /** Inline alignment of the lines (default `start`), for centered status copy. */
+    align?: TextAlign;
+    children: TextContent;
+    class?: string;
+    className?: string;
+};
+type TextProps = TextCommonProps & ({
+    /** Wrap normally or break long unbroken strings. Defaults to normal. */
+    wrap?: 'normal' | 'anywhere';
+    /** Cap wrapped text to this positive number of lines. */
+    maxLines?: number;
+    truncate?: never;
+    truncateKeep?: never;
+} | {
+    /** Keep one line without an ellipsis. */
+    wrap: 'nowrap';
+    maxLines?: never;
+    truncate?: never;
+    truncateKeep?: never;
+} | {
+    /** Keep one line with an ellipsis. */
+    wrap: 'truncate';
+    maxLines?: never;
+    /**
+     * Where the ellipsis goes (default `end`). `start` and `middle` are
+     * for left-to-right identifiers and paths, and `middle` requires
+     * string or number children so it can split them.
+     */
+    truncate?: TextTruncate;
+    /**
+     * The suffix `truncate="middle"` keeps (default `segment`: the last
+     * path segment, or the last 10 characters when there is no `/` or
+     * `\\` separator).
+     */
+    truncateKeep?: TextTruncateKeep;
+});
+/**
+ * Semantic heading, paragraph, or inline text. Block variants use the standard
+ * content-item padding; `span` adds no box geometry.
+ * All ordinary native heading/paragraph attributes pass through to the element.
+ */
+declare function Text({ variant: Variant, tone, color, size, font, border, flush, controlMargins, lineHeight, align, wrap, maxLines, truncate, truncateKeep, children, class: classValue, className, style, ...attributes }: TextProps): kerfjs.SafeHtml;
+
+export { FieldLabel, type FieldLabelProps, Sides, Text, type TextAlign, type TextBorder, type TextContent, type TextFont, type TextLineHeight, type TextProps, type TextSize, type TextTone, type TextTruncate, type TextTruncateKeep, type TextVariant, type TextWrap };

package/dist/text.js

@@ -0,0 +1,3 @@
+export { FieldLabel, Text } from './chunk-LL45C7BB.js';
+
+//# sourceMappingURL=text.js.map

package/dist/text.js.map

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

package/dist/token-search-field.d.ts

@@ -1,43 +1,3 @@
-import { SafeHtml } from 'kerfjs';
-
-interface TokenSearchToken {
-    value: string;
-    label: string;
-    offset?: number;
-    accessibleLabel?: string;
-}
-interface TokenSearchFieldProps {
-    id: string;
-    label: string;
-    query?: string;
-    tokens?: readonly TokenSearchToken[];
-    placeholder?: string;
-    tokenPlaceholder?: string;
-    disabled?: boolean;
-    autofocus?: boolean;
-    /** Allow an empty field to render as one iconic action. */
-    collapsible?: boolean;
-    /** Keep an empty collapsible field open while the application owns focus. */
-    expanded?: boolean;
-    expandAction?: string;
-    expandLabel?: string;
-    leading?: SafeHtml;
-    trailing?: SafeHtml;
-    editAction?: string;
-    removeAction?: string;
-    clearAction?: string;
-    clearLabel?: string;
-    className?: string;
-    editorAttributes?: Readonly<Record<`data-${string}`, string>>;
-}
-interface TokenSearchFieldValue {
-    query: string;
-    tokens: TokenSearchToken[];
-}
-declare function TokenSearchField({ id, label, query, tokens, placeholder, tokenPlaceholder, disabled, autofocus, collapsible, expanded, expandAction, expandLabel, leading, trailing, editAction, removeAction, clearAction, clearLabel, className, editorAttributes, }: TokenSearchFieldProps): SafeHtml;
-/** Read editable text and ordered token offsets from a rendered TokenSearchField editor. */
-declare function readTokenSearchField(editor: HTMLElement, knownTokens?: readonly TokenSearchToken[]): TokenSearchFieldValue;
-/** Focus an editor and place its caret at a text offset, skipping atomic token chips. */
-declare function placeTokenSearchCaret(editor: HTMLElement, offset?: number): void;
-
-export { TokenSearchField, type TokenSearchFieldProps, type TokenSearchFieldValue, type TokenSearchToken, placeTokenSearchCaret, readTokenSearchField };
+export { T as TokenSearchEditorAttributes, a as TokenSearchField, b as TokenSearchFieldProps, c as TokenSearchFieldValue, j as TokenSearchToken, k as TokenSearchTrailingAction, l as TokenSearchTrailingActionAttributes, p as placeTokenSearchCaret, r as readTokenSearchField } from './token-search-model-aYR0YAei.js';
+import 'kerfjs';
+import './semantic-content-BbzjvSu9.js';

package/dist/token-search-field.js

@@ -1,4 +1,5 @@
-export { TokenSearchField, placeTokenSearchCaret, readTokenSearchField } from './chunk-7LDCTU7D.js';
+export { TokenSearchField, placeTokenSearchCaret, readTokenSearchField } from './chunk-MF6ZUUJZ.js';
+
 
 
 //# sourceMappingURL=token-search-field.js.map

package/dist/token-search-model-aYR0YAei.d.ts

@@ -0,0 +1,184 @@
+import { SafeHtml, Signal } from 'kerfjs';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+
+interface TokenSearchToken {
+    value: string;
+    label: string;
+    offset?: number;
+    accessibleLabel?: string;
+}
+/**
+ * Domain `data-*` metadata for a trailing action button. The component owns
+ * `data-action` (pass `action`) and its state attributes.
+ */
+type TokenSearchTrailingActionAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
+    'data-action'?: never;
+    'data-component'?: never;
+    'data-key'?: never;
+}>;
+interface TokenSearchTrailingActionBase {
+    /** Decorative glyph, such as a `LucideIcon`. */
+    icon: SafeHtml;
+    /** Accessible name and tooltip, in title style ("Search Help"). */
+    label: string;
+    /** Delegated `data-action` value. */
+    action: string;
+    id?: string;
+    /** `aria-controls`: the id of the surface this button opens or toggles. */
+    controls?: string;
+    /** `aria-haspopup` for a button that opens a dialog, menu, or listbox. */
+    haspopup?: 'dialog' | 'menu' | 'listbox' | 'true';
+    /** Domain `data-*` metadata for the app's delegated handler. */
+    attributes?: TokenSearchTrailingActionAttributes;
+}
+/**
+ * A compact icon button in the field's trailing slot, sized and styled like
+ * the clear button. Pass `expanded` for a disclosure (a help surface it opens)
+ * or `pressed` for a toggle; the button shows the state with its hover fill.
+ */
+type TokenSearchTrailingAction = TokenSearchTrailingActionBase & ({
+    expanded?: boolean;
+    pressed?: never;
+} | {
+    expanded?: never;
+    pressed?: boolean;
+});
+type TokenSearchEditorAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
+    'data-component'?: never;
+    'data-key'?: never;
+    'data-morph-skip'?: never;
+    'data-token-search-editor'?: never;
+    'data-token-count'?: never;
+    'data-placeholder'?: never;
+}>;
+interface TokenSearchFieldBaseProps {
+    id: string;
+    label: string;
+    query?: string;
+    tokens?: readonly TokenSearchToken[];
+    /** Opt-in grammar, suggestion, and evaluation state. Overrides `query` and `tokens`. */
+    model?: TokenSearchModel;
+    /**
+     * Editor identity for a programmatic text replacement. The editor's text is
+     * DOM-owned between token changes, so a new `query` with the same tokens
+     * does not re-render it (that would reset the caret on every keystroke).
+     * Change `revision` when the app replaces the text itself — reseeding a
+     * persistent dialog's field on reopen, applying a saved search — and the
+     * editor is rebuilt from `query` and `tokens`.
+     */
+    revision?: string | number;
+    placeholder?: string;
+    tokenPlaceholder?: string;
+    disabled?: boolean;
+    autofocus?: boolean;
+    /** Let an expanded collapsible field consume the available inline width. */
+    fill?: boolean;
+    leading?: KerfUiContent;
+    editAction?: string;
+    removeAction?: string;
+    clearAction?: string;
+    clearLabel?: string;
+    /** Icon for the clear button. Default: the Lucide `x` glyph token chips also use. */
+    clearIcon?: SafeHtml;
+    className?: string;
+    editorAttributes?: TokenSearchEditorAttributes;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
+}
+type TokenSearchTrailingProps = {
+    trailing?: KerfUiContent;
+    trailingAction?: never;
+} | {
+    trailing?: never;
+    trailingAction: TokenSearchTrailingAction;
+};
+type TokenSearchPresentationProps = {
+    /** Standalone field chrome or the inset visual layer of a configured toolbar group. */
+    presentation?: 'standalone' | 'toolbar-group';
+    hint?: never;
+    required?: never;
+} | {
+    /** Visible form label and optional hint around the full-width standalone control. */
+    presentation: 'form-field';
+    hint?: string;
+    /** Marks the editor required; the app validates its value. */
+    required?: boolean;
+};
+type TokenSearchCollapsibleProps = {
+    /** Allow an empty field to render as one iconic action. */
+    collapsible: true;
+    /** Keep an empty collapsible field open while the application owns focus. */
+    expanded?: boolean;
+    expandAction?: string;
+    expandLabel?: string;
+} | {
+    collapsible?: false;
+    expanded?: never;
+    expandAction?: never;
+    expandLabel?: never;
+};
+type TokenSearchFieldProps = TokenSearchFieldBaseProps & TokenSearchCollapsibleProps & TokenSearchTrailingProps & TokenSearchPresentationProps;
+interface TokenSearchFieldValue {
+    query: string;
+    tokens: TokenSearchToken[];
+}
+declare function TokenSearchField({ id, label, query, tokens, model, revision, placeholder, tokenPlaceholder, disabled, autofocus, fill, collapsible, expanded, expandAction, expandLabel, leading, trailing, trailingAction, presentation, hint, required, editAction, removeAction, clearAction, clearLabel, clearIcon, className, editorAttributes, slot, }: TokenSearchFieldProps): SafeHtml;
+/** Read editable text and ordered token offsets from a rendered TokenSearchField editor. */
+declare function readTokenSearchField(editor: HTMLElement, knownTokens?: readonly TokenSearchToken[]): TokenSearchFieldValue;
+/** Focus an editor and place its caret at a text offset, skipping atomic token chips. */
+declare function placeTokenSearchCaret(editor: HTMLElement, offset?: number): void;
+
+interface TokenSearchRule {
+    /** The word before `:` (for example `tag` or `status`). */
+    name: string;
+    /** Return a canonical value, or undefined to leave invalid input as text. */
+    parse?: (input: string) => string | undefined;
+    /** Label for a committed chip. Defaults to `name:input`. */
+    label?: (value: string, input: string) => string;
+    /** Suggestions for the unfinished value after `name:`, with current committed tokens. */
+    suggest?: (input: string, state: TokenSearchState) => readonly (string | {
+        value: string;
+        label: string;
+    })[];
+}
+interface TokenSearchResolvedToken extends TokenSearchToken {
+    kind: string;
+    parsedValue: string;
+}
+interface TokenSearchState {
+    query: string;
+    tokens: TokenSearchResolvedToken[];
+}
+interface TokenSearchSuggestion {
+    value: string;
+    label: string;
+}
+interface TokenSearchModel<Result = unknown> {
+    state: Signal<TokenSearchState>;
+    /** Changes when a model action must replace DOM-owned editor text. */
+    editorRevision: Signal<number>;
+    suggestions: Signal<readonly TokenSearchSuggestion[]>;
+    result: Signal<Result | undefined>;
+    edit(value: TokenSearchFieldValue, commit?: boolean): void;
+    /** Replace app-owned search state and rebuild the DOM-owned editor text. */
+    replace(value: TokenSearchFieldValue): void;
+    submit(value: TokenSearchFieldValue): void;
+    choose(value: string): void;
+    /** Commit a value for the active `name:` prefix, even when it is not suggested. */
+    commit(value: string): void;
+    expandToken(value: string): void;
+    remove(value: string): void;
+    clear(): void;
+    dismiss(): void;
+}
+interface TokenSearchModelOptions<Result> {
+    rules?: readonly TokenSearchRule[];
+    initial?: TokenSearchFieldValue;
+    /** Runs after every state change, including initial state. */
+    evaluate?: (state: TokenSearchState) => Result;
+    onSubmit?: (state: TokenSearchState, result: Result | undefined) => void;
+}
+/** Opt-in state, token parsing, suggestions, and evaluation for TokenSearchField. */
+declare function createTokenSearchModel<Result = unknown>({ rules, initial, evaluate, onSubmit, }?: TokenSearchModelOptions<Result>): TokenSearchModel<Result>;
+
+export { type TokenSearchEditorAttributes as T, TokenSearchField as a, type TokenSearchFieldProps as b, type TokenSearchFieldValue as c, type TokenSearchModel as d, type TokenSearchModelOptions as e, type TokenSearchResolvedToken as f, type TokenSearchRule as g, type TokenSearchState as h, type TokenSearchSuggestion as i, type TokenSearchToken as j, type TokenSearchTrailingAction as k, type TokenSearchTrailingActionAttributes as l, createTokenSearchModel as m, placeTokenSearchCaret as p, readTokenSearchField as r };

package/dist/token-search-model.d.ts

@@ -0,0 +1,3 @@
+export { d as TokenSearchModel, e as TokenSearchModelOptions, f as TokenSearchResolvedToken, g as TokenSearchRule, h as TokenSearchState, i as TokenSearchSuggestion, m as createTokenSearchModel } from './token-search-model-aYR0YAei.js';
+import 'kerfjs';
+import './semantic-content-BbzjvSu9.js';

package/dist/token-search-model.js

@@ -0,0 +1,3 @@
+export { createTokenSearchModel } from './chunk-IM3GKYOG.js';
+
+//# sourceMappingURL=token-search-model.js.map

package/dist/token-search-model.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"token-search-model.js"}