@kerfjs/ui 5.0.0-beta.4 → 5.0.0-beta.41

package/dist/select-register.js

@@ -1,8 +1,136 @@
+import '@awesome.me/webawesome/dist/components/button/button.js';
 import '@awesome.me/webawesome/dist/components/divider/divider.js';
+import '@awesome.me/webawesome/dist/components/dropdown/dropdown.js';
+import '@awesome.me/webawesome/dist/components/dropdown-item/dropdown-item.js';
 import '@awesome.me/webawesome/dist/components/option/option.js';
-import '@awesome.me/webawesome/dist/components/select/select.js';
+import WaSelect from '@awesome.me/webawesome/dist/components/select/select.js';
+import { WaAfterHideEvent } from '@awesome.me/webawesome/dist/events/after-hide.js';
+import { WaAfterShowEvent } from '@awesome.me/webawesome/dist/events/after-show.js';
+import { WaHideEvent } from '@awesome.me/webawesome/dist/events/hide.js';
+import { WaShowEvent } from '@awesome.me/webawesome/dist/events/show.js';
 
 // src/select-register.ts
+
+// src/animate-select-popup.ts
+function animateSelectPopup(popup, phase, signal) {
+  return new Promise((resolve) => {
+    let settled = false;
+    let frame = 0;
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      window.cancelAnimationFrame(frame);
+      signal.removeEventListener("abort", finish);
+      popup.classList.remove(phase);
+      resolve();
+    };
+    signal.addEventListener("abort", finish, { once: true });
+    popup.classList.add(phase);
+    frame = window.requestAnimationFrame(() => {
+      void Promise.all(
+        popup.getAnimations().map((animation) => animation.finished.catch(() => void 0))
+      ).then(finish);
+    });
+    if (signal.aborted) finish();
+  });
+}
+
+// src/install-select-lifecycle.ts
+function installSelectLifecycle(prototype) {
+  const installed = /* @__PURE__ */ Symbol.for("@kerfjs/ui/select-lifecycle");
+  if (Object.prototype.hasOwnProperty.call(prototype, installed)) return;
+  Object.defineProperty(prototype, installed, { value: true });
+  const original = prototype.handleOpenChange;
+  const originalDisabled = prototype.handleDisabledChange;
+  prototype.handleDisabledChange = function() {
+    const host = this;
+    const wasOpen = host.open;
+    originalDisabled.call(this);
+    if (host.dataset.component === "select" && wasOpen && !host.open) {
+      void host.handleOpenChange();
+    }
+  };
+  const transitions = /* @__PURE__ */ new WeakMap();
+  const restorations = /* @__PURE__ */ new WeakMap();
+  prototype.handleOpenChange = async function() {
+    const host = this;
+    if (host.dataset.component !== "select") return original.call(this);
+    const restoring = restorations.get(host)?.open === host.open;
+    restorations.delete(host);
+    if (restoring) return;
+    const transition = new AbortController();
+    const opening = host.open && !host.disabled;
+    const current = () => !transition.signal.aborted && host.isConnected && (host.open && !host.disabled) === opening;
+    try {
+      if (!host.isConnected) return;
+      if (opening) {
+        host.setCurrentOption(host.selectedOptions[0] || host.getFirstOption());
+      }
+      const event = opening ? new WaShowEvent() : new WaHideEvent();
+      host.dispatchEvent(event);
+      if (event.defaultPrevented) {
+        host.open = !opening;
+        const restoration = { open: host.open };
+        restorations.set(host, restoration);
+        void host.updateComplete.then(() => {
+          if (restorations.get(host) === restoration) restorations.delete(host);
+        });
+        return;
+      }
+      if (!current()) return;
+      transitions.get(host)?.abort();
+      transitions.set(host, transition);
+      if (opening) {
+        host.addOpenListeners();
+        host.listbox.hidden = false;
+        host.popup.active = true;
+        window.requestAnimationFrame(() => {
+          if (current()) host.setCurrentOption(host.currentOption);
+        });
+      } else {
+        host.removeOpenListeners();
+      }
+      await animateSelectPopup(
+        host.popup.popup,
+        opening ? "show" : "hide",
+        transition.signal
+      );
+      if (!transition.signal.aborted && !host.isConnected) {
+        host.removeOpenListeners();
+        host.listbox.hidden = true;
+        host.popup.active = false;
+      }
+      if (!current()) return;
+      if (opening) {
+        const option = host.currentOption;
+        if (option) {
+          const list = host.listbox;
+          const offset = Math.round(
+            option.getBoundingClientRect().top - list.getBoundingClientRect().top
+          );
+          if (offset < 0)
+            list.scrollTo({ top: list.scrollTop + offset, behavior: "auto" });
+          else if (offset + option.clientHeight > list.offsetHeight) {
+            list.scrollTo({
+              top: list.scrollTop + offset - list.offsetHeight + option.clientHeight,
+              behavior: "auto"
+            });
+          }
+        }
+        host.dispatchEvent(new WaAfterShowEvent());
+      } else {
+        host.listbox.hidden = true;
+        host.popup.active = false;
+        host.dispatchEvent(new WaAfterHideEvent());
+      }
+    } finally {
+      if (transitions.get(host) === transition) transitions.delete(host);
+    }
+  };
+}
+
+// src/select-register.ts
+installSelectLifecycle(WaSelect.prototype);
 var selectElementsRegistered = true;
 
 export { selectElementsRegistered };

package/dist/select-register.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/select-register.ts"],"names":[],"mappings":";;;;;AAKO,IAAM,wBAAA,GAA2B","file":"select-register.js","sourcesContent":["import '@awesome.me/webawesome/dist/components/divider/divider.js';\nimport '@awesome.me/webawesome/dist/components/option/option.js';\nimport '@awesome.me/webawesome/dist/components/select/select.js';\n\n/** Marker export for tests and tooling; importing this module performs registration. */\nexport const selectElementsRegistered = true;\n"]}
+{"version":3,"sources":["../src/animate-select-popup.ts","../src/install-select-lifecycle.ts","../src/select-register.ts"],"names":[],"mappings":"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","file":"select-register.js","sourcesContent":["/** Run one native Select CSS animation; a reversal owns cancellation and cleanup. */\nexport function animateSelectPopup(\n  popup: HTMLElement,\n  phase: 'show' | 'hide',\n  signal: AbortSignal,\n): Promise<void> {\n  return new Promise((resolve) => {\n    let settled = false;\n    let frame = 0;\n    const finish = () => {\n      if (settled) return;\n      settled = true;\n      window.cancelAnimationFrame(frame);\n      signal.removeEventListener('abort', finish);\n      popup.classList.remove(phase);\n      resolve();\n    };\n    signal.addEventListener('abort', finish, { once: true });\n    popup.classList.add(phase);\n    // Activation renders asynchronously. Check for reduced/absent motion only\n    // after the native popup has had its normal render opportunity.\n    frame = window.requestAnimationFrame(() => {\n      // Observe these exact animations. An old CSS animationcancel event can\n      // arrive after the next phase starts and must not finish that new phase.\n      void Promise.all(\n        popup\n          .getAnimations()\n          .map((animation) => animation.finished.catch(() => undefined)),\n      ).then(finish);\n    });\n    if (signal.aborted) finish();\n  });\n}\n","import type WaSelect from '@awesome.me/webawesome/dist/components/select/select.js';\nimport { WaAfterHideEvent } from '@awesome.me/webawesome/dist/events/after-hide.js';\nimport { WaAfterShowEvent } from '@awesome.me/webawesome/dist/events/after-show.js';\nimport { WaHideEvent } from '@awesome.me/webawesome/dist/events/hide.js';\nimport { WaShowEvent } from '@awesome.me/webawesome/dist/events/show.js';\n\nimport { animateSelectPopup } from './animate-select-popup.js';\n\n// Web Awesome 3.12/3.13 expose the lifecycle method but not these helper types.\n// Keep this integration boundary local: native option selection, dismissal\n// listeners, popup positioning and rendering remain owned by Web Awesome.\ninterface SelectHost extends Pick<\n  WaSelect,\n  | 'open'\n  | 'disabled'\n  | 'isConnected'\n  | 'dataset'\n  | 'popup'\n  | 'listbox'\n  | 'currentOption'\n  | 'selectedOptions'\n  | 'dispatchEvent'\n  | 'handleOpenChange'\n  | 'updateComplete'\n> {\n  getFirstOption(): WaSelect['currentOption'];\n  setCurrentOption(option: WaSelect['currentOption']): void;\n  addOpenListeners(): void;\n  removeOpenListeners(): void;\n}\n\n/** Install once at the explicit registration boundary, only for Kerf Selects. */\nexport function installSelectLifecycle(\n  prototype: Pick<WaSelect, 'handleOpenChange' | 'handleDisabledChange'>,\n): void {\n  const installed = Symbol.for('@kerfjs/ui/select-lifecycle');\n  if (Object.prototype.hasOwnProperty.call(prototype, installed)) return;\n  Object.defineProperty(prototype, installed, { value: true });\n  const original = prototype.handleOpenChange;\n  const originalDisabled = prototype.handleDisabledChange;\n  prototype.handleDisabledChange = function () {\n    const host = this as unknown as SelectHost;\n    const wasOpen = host.open;\n    originalDisabled.call(this);\n    // WA's disabled watcher runs after its open watcher in the same Lit update.\n    // Its open=false mutation otherwise misses the open lifecycle altogether.\n    if (host.dataset.component === 'select' && wasOpen && !host.open) {\n      void host.handleOpenChange();\n    }\n  };\n  const transitions = new WeakMap<SelectHost, AbortController>();\n  const restorations = new WeakMap<SelectHost, { open: boolean }>();\n  prototype.handleOpenChange = async function () {\n    const host = this as unknown as SelectHost;\n    if (host.dataset.component !== 'select') return original.call(this);\n    const restoring = restorations.get(host)?.open === host.open;\n    restorations.delete(host);\n    if (restoring) return;\n    const transition = new AbortController();\n    const opening = host.open && !host.disabled;\n    const current = () =>\n      !transition.signal.aborted &&\n      host.isConnected &&\n      (host.open && !host.disabled) === opening;\n    try {\n      if (!host.isConnected) return;\n      if (opening) {\n        host.setCurrentOption(host.selectedOptions[0] || host.getFirstOption());\n      }\n      const event = opening ? new WaShowEvent() : new WaHideEvent();\n      host.dispatchEvent(event);\n      if (event.defaultPrevented) {\n        // Restore the accepted state without emitting the opposite transition.\n        // Clear at the update checkpoint too: Lit can coalesce a restoration.\n        host.open = !opening;\n        const restoration = { open: host.open };\n        restorations.set(host, restoration);\n        void host.updateComplete.then(() => {\n          if (restorations.get(host) === restoration) restorations.delete(host);\n        });\n        return;\n      }\n      // A consumer can reverse the request synchronously in a lifecycle event.\n      if (!current()) return;\n      // A rejected reversal must not cancel the previously accepted animation.\n      transitions.get(host)?.abort();\n      transitions.set(host, transition);\n      if (opening) {\n        host.addOpenListeners();\n        host.listbox.hidden = false;\n        host.popup.active = true;\n        window.requestAnimationFrame(() => {\n          if (current()) host.setCurrentOption(host.currentOption);\n        });\n      } else {\n        host.removeOpenListeners();\n      }\n      await animateSelectPopup(\n        host.popup.popup,\n        opening ? 'show' : 'hide',\n        transition.signal,\n      );\n      if (!transition.signal.aborted && !host.isConnected) {\n        host.removeOpenListeners();\n        host.listbox.hidden = true;\n        host.popup.active = false;\n      }\n      if (!current()) return;\n      if (opening) {\n        // Match native vertical, immediate option reveal without scrolling an\n        // ancestor page or moving focus after animation completion.\n        const option = host.currentOption;\n        if (option) {\n          const list = host.listbox;\n          const offset = Math.round(\n            option.getBoundingClientRect().top -\n              list.getBoundingClientRect().top,\n          );\n          if (offset < 0)\n            list.scrollTo({ top: list.scrollTop + offset, behavior: 'auto' });\n          else if (offset + option.clientHeight > list.offsetHeight) {\n            list.scrollTo({\n              top:\n                list.scrollTop +\n                offset -\n                list.offsetHeight +\n                option.clientHeight,\n              behavior: 'auto',\n            });\n          }\n        }\n        host.dispatchEvent(new WaAfterShowEvent());\n      } else {\n        host.listbox.hidden = true;\n        host.popup.active = false;\n        host.dispatchEvent(new WaAfterHideEvent());\n      }\n    } finally {\n      if (transitions.get(host) === transition) transitions.delete(host);\n    }\n  };\n}\n","import '@awesome.me/webawesome/dist/components/button/button.js';\nimport '@awesome.me/webawesome/dist/components/divider/divider.js';\nimport '@awesome.me/webawesome/dist/components/dropdown/dropdown.js';\nimport '@awesome.me/webawesome/dist/components/dropdown-item/dropdown-item.js';\nimport '@awesome.me/webawesome/dist/components/option/option.js';\n\nimport WaSelect from '@awesome.me/webawesome/dist/components/select/select.js';\n\nimport { installSelectLifecycle } from './install-select-lifecycle.js';\n\ninstallSelectLifecycle(WaSelect.prototype);\n\n/**\n * Marker export for tests and tooling; importing this module performs registration.\n * Registers both the `Select` elements and the `Catalog` related-entries popup-menu\n * elements (`wa-dropdown` / `wa-dropdown-item` / `wa-button`).\n */\nexport const selectElementsRegistered = true;\n"]}

package/dist/select.d.ts

@@ -1,4 +1,5 @@
 import { SafeHtml } from 'kerfjs';
+import { CssColor } from './css-values.js';
 import { LucideNode } from './lucide-icon.js';
 import 'lucide';
 
@@ -7,22 +8,47 @@ interface SelectChoice<Value extends string = string> {
     label: string;
     icon?: LucideNode;
     iconName?: string;
-    color?: string;
+    /** Typed semantic or application-owned color for the optional icon. */
+    color?: CssColor;
     group?: string;
     separatorBefore?: boolean;
 }
-interface SelectProps<Value extends string = string> {
-    name: string;
-    value: Value;
-    label?: string;
+type SelectAccessibleName = {
+    label: string;
     ariaLabel?: string;
+} | {
+    label?: never;
+    ariaLabel: string;
+};
+type SelectPresentation = 'form' | 'toolbar-borderless' | 'navigation';
+type SelectSize = 'default' | 'compact';
+type SelectSelectedPresentation = 'label' | 'icon-only';
+type SelectFocusRingOwner = 'select' | 'group';
+interface SelectBaseProps<Value extends string = string> {
+    name: string;
+    value: NoInfer<Value>;
     choices: readonly SelectChoice<Value>[];
     className?: string;
-    placeholder?: string;
+    /** Empty-value hint text shown in the closed control (the native select placeholder). */
+    placeholderText?: string;
+    /** Supporting text shown below the control and associated with its combobox. */
+    hint?: string;
     disabled?: boolean;
     fitMenu?: boolean;
     renderSelected?: (choice: SelectChoice<Value>) => SafeHtml;
+    /** Render as an unanimated loading skeleton: the label above a static, empty control box. */
+    placeholder?: boolean;
+    /** Form (default), borderless toolbar, or intrinsic navigation chrome. */
+    presentation?: SelectPresentation;
+    size?: SelectSize;
+    /** Show only the selected choice icon while retaining the Select's accessible name. */
+    selectedPresentation?: SelectSelectedPresentation;
+    /** Let an enclosing ToolbarControlGroup paint the composed focus ring. */
+    focusRingOwner?: SelectFocusRingOwner;
+    /** Maximum closed-control label width in CSS pixels before ellipsis. */
+    labelMaxWidth?: number;
 }
-declare function Select<Value extends string>({ name, value, label, ariaLabel, choices, className, placeholder, disabled, fitMenu, renderSelected }: SelectProps<Value>): SafeHtml;
+type SelectProps<Value extends string = string> = SelectBaseProps<Value> & SelectAccessibleName;
+declare function Select<Value extends string>({ name, value, label, ariaLabel, choices, className, placeholderText, hint, disabled, fitMenu, renderSelected, placeholder, presentation, size, selectedPresentation, focusRingOwner, labelMaxWidth, }: SelectProps<Value>): SafeHtml;
 
-export { Select, type SelectChoice, type SelectProps };
+export { Select, type SelectChoice, type SelectFocusRingOwner, type SelectPresentation, type SelectProps, type SelectSelectedPresentation, type SelectSize };

package/dist/select.js

@@ -1,4 +1,6 @@
-export { Select } from './chunk-CTQKI2XL.js';
+export { Select } from './chunk-CK6P5AUK.js';
+
+
 
 
 //# sourceMappingURL=select.js.map

package/dist/semantic-content-BbzjvSu9.d.ts

@@ -0,0 +1,14 @@
+import { SafeHtml } from 'kerfjs';
+
+/**
+ * Renderable content for semantic Kerf UI component positions.
+ *
+ * Unlike core JSX children, UI content intentionally excludes raw strings,
+ * numbers, and signals: semantic component zones should contain trusted
+ * `SafeHtml` components. Boolean and nullish values render nothing, and nested
+ * readonly arrays let conditionals and mapped component collections compose
+ * directly without an otherwise-unnecessary Fragment.
+ */
+type KerfUiContent = SafeHtml | boolean | null | undefined | readonly KerfUiContent[];
+
+export type { KerfUiContent as K };

package/dist/skeleton.d.ts

@@ -0,0 +1,25 @@
+import * as kerfjs from 'kerfjs';
+import { CssSize, CssLength } from './css-values.js';
+
+interface SkeletonProps {
+    /** Typed width or intrinsic sizing keyword. Defaults to filling its slot. */
+    width?: CssSize;
+    /** Typed height or intrinsic sizing keyword. Defaults to a single text line. */
+    height?: CssSize;
+    /** Typed corner-radius override. Defaults to the small radius token. */
+    radius?: CssLength;
+    /** Render this many stacked lines (the last one shorter), for multi-line text. */
+    lines?: number;
+    /** Accessible label. Omit to keep the block decorative (`aria-hidden`). */
+    label?: string;
+    className?: string;
+}
+/**
+ * A subtle, deliberately **unanimated** loading placeholder block. Use it for a
+ * value slot whose content is not yet known, on its own or via a component's
+ * `placeholder` prop. Decorative by default (`aria-hidden`); pass `label` to
+ * announce it. Sizes to its slot unless `width`/`height` are given.
+ */
+declare function Skeleton({ width, height, radius, lines, label, className, }: SkeletonProps): kerfjs.SafeHtml;
+
+export { Skeleton, type SkeletonProps };

package/dist/skeleton.js

@@ -0,0 +1,4 @@
+export { Skeleton } from './chunk-T7DOWS6T.js';
+
+
+//# sourceMappingURL=skeleton.js.map

package/dist/skeleton.js.map

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

package/dist/spacer.d.ts

@@ -0,0 +1,16 @@
+import * as kerfjs from 'kerfjs';
+import { UiSpaceName, CssLength } from './css-values.js';
+
+interface SpacerProps {
+    /** Grow and shrink to fill the available space along a parent's flex axis. */
+    flex?: boolean;
+    /** A named UI spacing token or typed physical width. */
+    width?: UiSpaceName | CssLength;
+    /** A named UI spacing token or typed physical height. */
+    height?: UiSpaceName | CssLength;
+    className?: string;
+}
+/** A decorative fixed-size or flexible gap for Row, List, and other flex layouts. */
+declare function Spacer({ flex, width, height, className, }: SpacerProps): kerfjs.SafeHtml;
+
+export { CssLength, Spacer, type SpacerProps, UiSpaceName };

package/dist/spacer.js

@@ -0,0 +1,4 @@
+export { Spacer } from './chunk-OGTJNHRG.js';
+
+
+//# sourceMappingURL=spacer.js.map

package/dist/spacer.js.map

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

package/dist/split-view.d.ts

@@ -0,0 +1,43 @@
+import * as kerfjs from 'kerfjs';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+
+interface SplitViewResizable {
+    size: number;
+    min: number;
+    max: number;
+}
+interface SplitViewProps {
+    id: string;
+    label: string;
+    /** The list (primary) pane. */
+    list: KerfUiContent;
+    /** The detail (secondary) pane. */
+    detail: KerfUiContent;
+    /**
+     * Compact ("one pane at a time") classes — a handset or portrait tablet.
+     * Derive from `deviceClass().value.compact`. When true the split collapses to
+     * a `NavStack`: the list is the root and the detail is pushed over it.
+     */
+    compact?: boolean;
+    /** In compact mode, whether the detail is currently pushed over the list. */
+    detailActive?: boolean;
+    /** Title/label for the list (compact NavStack root + region label). */
+    listTitle?: string;
+    /** Title/label for the detail (compact NavStack pushed view + region label). */
+    detailTitle?: string;
+    /** Back label for the compact NavStack (default "Back"). */
+    backLabel?: string;
+    /** A resizable separator on roomy classes (min/max px). Omit for a fixed split. */
+    resizable?: SplitViewResizable;
+    className?: string;
+}
+/**
+ * A list-detail split. On roomy classes it shows both panes side
+ * by side with an optional resizable separator; on compact classes it collapses
+ * to a `NavStack` (list → detail). See `docs/23-app-layouts.md` §3.2. Compose the
+ * resizable wiring with `wireResizableRegions` and the compact back with
+ * `wireNavStack`.
+ */
+declare function SplitView({ id, label, list, detail, compact, detailActive, listTitle, detailTitle, backLabel, resizable, className, }: SplitViewProps): kerfjs.SafeHtml;
+
+export { SplitView, type SplitViewProps, type SplitViewResizable };

package/dist/split-view.js

@@ -0,0 +1,82 @@
+import { NavStack } from './chunk-AQFWBG23.js';
+
+import { ResizableRegion } from './chunk-CAB6NQ2T.js';
+
+
+import { jsx, jsxs } from 'kerfjs/jsx-runtime';
+
+function SplitView({
+  id,
+  label,
+  list,
+  detail,
+  compact = false,
+  detailActive = false,
+  listTitle = "",
+  detailTitle = "",
+  backLabel = "Back",
+  resizable,
+  className = ""
+}) {
+  if (compact) {
+    const views = detailActive ? [
+      { key: "list", title: listTitle, content: list },
+      { key: "detail", title: detailTitle, content: detail }
+    ] : [{ key: "list", title: listTitle, content: list }];
+    return /* @__PURE__ */ jsx(
+      "div",
+      {
+        class: `kui-split-view kui-split-view--compact ${className}`.trim(),
+        id,
+        "data-component": "split-view",
+        "data-split-mode": "compact",
+        children: /* @__PURE__ */ jsx(
+          NavStack,
+          {
+            id: `${id}-stack`,
+            label,
+            views,
+            backLabel
+          }
+        )
+      }
+    );
+  }
+  const listPane = resizable ? /* @__PURE__ */ jsx(
+    ResizableRegion,
+    {
+      id: `${id}-list`,
+      label: listTitle || "List",
+      size: resizable.size,
+      min: resizable.min,
+      max: resizable.max,
+      children: /* @__PURE__ */ jsx("div", { class: "kui-split-view__list kui-pane", "data-split-list": true, children: list })
+    }
+  ) : /* @__PURE__ */ jsx("div", { class: "kui-split-view__list kui-pane", "data-split-list": true, children: list });
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      class: `kui-split-view ${className}`.trim(),
+      id,
+      "data-component": "split-view",
+      "data-split-mode": "split",
+      "aria-label": label,
+      children: [
+        listPane,
+        /* @__PURE__ */ jsx(
+          "div",
+          {
+            class: "kui-split-view__detail kui-pane",
+            "data-split-detail": true,
+            "aria-label": detailTitle || void 0,
+            children: detail
+          }
+        )
+      ]
+    }
+  );
+}
+
+export { SplitView };
+
+//# sourceMappingURL=split-view.js.map

package/dist/split-view.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/split-view.tsx"],"names":[],"mappings":";;;;;;;AA2CO,SAAS,SAAA,CAAU;AAAA,EACxB,EAAA;AAAA,EACA,KAAA;AAAA,EACA,IAAA;AAAA,EACA,MAAA;AAAA,EACA,OAAA,GAAU,KAAA;AAAA,EACV,YAAA,GAAe,KAAA;AAAA,EACf,SAAA,GAAY,EAAA;AAAA,EACZ,WAAA,GAAc,EAAA;AAAA,EACd,SAAA,GAAY,MAAA;AAAA,EACZ,SAAA;AAAA,EACA,SAAA,GAAY;AACd,CAAA,EAAmB;AACjB,EAAA,IAAI,OAAA,EAAS;AACX,IAAA,MAAM,QAAQ,YAAA,GACV;AAAA,MACE,EAAE,GAAA,EAAK,MAAA,EAAQ,KAAA,EAAO,SAAA,EAAW,SAAS,IAAA,EAAK;AAAA,MAC/C,EAAE,GAAA,EAAK,QAAA,EAAU,KAAA,EAAO,WAAA,EAAa,SAAS,MAAA;AAAO,KACvD,GACA,CAAC,EAAE,GAAA,EAAK,QAAQ,KAAA,EAAO,SAAA,EAAW,OAAA,EAAS,IAAA,EAAM,CAAA;AACrD,IAAA,uBACE,GAAA;AAAA,MAAC,KAAA;AAAA,MAAA;AAAA,QACC,KAAA,EAAO,CAAA,uCAAA,EAA0C,SAAS,CAAA,CAAA,CAAG,IAAA,EAAK;AAAA,QAClE,EAAA;AAAA,QACA,gBAAA,EAAe,YAAA;AAAA,QACf,iBAAA,EAAgB,SAAA;AAAA,QAEhB,QAAA,kBAAA,GAAA;AAAA,UAAC,QAAA;AAAA,UAAA;AAAA,YACC,EAAA,EAAI,GAAG,EAAE,CAAA,MAAA,CAAA;AAAA,YACT,KAAA;AAAA,YACA,KAAA;AAAA,YACA;AAAA;AAAA;AACF;AAAA,KACF;AAAA,EAEJ;AACA,EAAA,MAAM,WAAW,SAAA,mBACf,GAAA;AAAA,IAAC,eAAA;AAAA,IAAA;AAAA,MACC,EAAA,EAAI,GAAG,EAAE,CAAA,KAAA,CAAA;AAAA,MACT,OAAO,SAAA,IAAa,MAAA;AAAA,MACpB,MAAM,SAAA,CAAU,IAAA;AAAA,MAChB,KAAK,SAAA,CAAU,GAAA;AAAA,MACf,KAAK,SAAA,CAAU,GAAA;AAAA,MAEf,8BAAC,KAAA,EAAA,EAAI,KAAA,EAAM,+BAAA,EAAgC,iBAAA,EAAe,MACvD,QAAA,EAAA,IAAA,EACH;AAAA;AAAA,sBAGF,GAAA,CAAC,KAAA,EAAA,EAAI,OAAM,+BAAA,EAAgC,iBAAA,EAAe,MACvD,QAAA,EAAA,IAAA,EACH,CAAA;AAEF,EAAA,uBACE,IAAA;AAAA,IAAC,KAAA;AAAA,IAAA;AAAA,MACC,KAAA,EAAO,CAAA,eAAA,EAAkB,SAAS,CAAA,CAAA,CAAG,IAAA,EAAK;AAAA,MAC1C,EAAA;AAAA,MACA,gBAAA,EAAe,YAAA;AAAA,MACf,iBAAA,EAAgB,OAAA;AAAA,MAChB,YAAA,EAAY,KAAA;AAAA,MAEX,QAAA,EAAA;AAAA,QAAA,QAAA;AAAA,wBACD,GAAA;AAAA,UAAC,KAAA;AAAA,UAAA;AAAA,YACC,KAAA,EAAM,iCAAA;AAAA,YACN,mBAAA,EAAiB,IAAA;AAAA,YACjB,cAAY,WAAA,IAAe,MAAA;AAAA,YAE1B,QAAA,EAAA;AAAA;AAAA;AACH;AAAA;AAAA,GACF;AAEJ","file":"split-view.js","sourcesContent":["import { NavStack } from './nav-stack.js';\nimport { ResizableRegion } from './resizable-region.js';\nimport type { KerfUiContent } from './semantic-content.js';\n\nexport interface SplitViewResizable {\n  size: number;\n  min: number;\n  max: number;\n}\n\nexport interface SplitViewProps {\n  id: string;\n  label: string;\n  /** The list (primary) pane. */\n  list: KerfUiContent;\n  /** The detail (secondary) pane. */\n  detail: KerfUiContent;\n  /**\n   * Compact (\"one pane at a time\") classes — a handset or portrait tablet.\n   * Derive from `deviceClass().value.compact`. When true the split collapses to\n   * a `NavStack`: the list is the root and the detail is pushed over it.\n   */\n  compact?: boolean;\n  /** In compact mode, whether the detail is currently pushed over the list. */\n  detailActive?: boolean;\n  /** Title/label for the list (compact NavStack root + region label). */\n  listTitle?: string;\n  /** Title/label for the detail (compact NavStack pushed view + region label). */\n  detailTitle?: string;\n  /** Back label for the compact NavStack (default \"Back\"). */\n  backLabel?: string;\n  /** A resizable separator on roomy classes (min/max px). Omit for a fixed split. */\n  resizable?: SplitViewResizable;\n  className?: string;\n}\n\n/**\n * A list-detail split. On roomy classes it shows both panes side\n * by side with an optional resizable separator; on compact classes it collapses\n * to a `NavStack` (list → detail). See `docs/23-app-layouts.md` §3.2. Compose the\n * resizable wiring with `wireResizableRegions` and the compact back with\n * `wireNavStack`.\n */\nexport function SplitView({\n  id,\n  label,\n  list,\n  detail,\n  compact = false,\n  detailActive = false,\n  listTitle = '',\n  detailTitle = '',\n  backLabel = 'Back',\n  resizable,\n  className = '',\n}: SplitViewProps) {\n  if (compact) {\n    const views = detailActive\n      ? [\n          { key: 'list', title: listTitle, content: list },\n          { key: 'detail', title: detailTitle, content: detail },\n        ]\n      : [{ key: 'list', title: listTitle, content: list }];\n    return (\n      <div\n        class={`kui-split-view kui-split-view--compact ${className}`.trim()}\n        id={id}\n        data-component=\"split-view\"\n        data-split-mode=\"compact\"\n      >\n        <NavStack\n          id={`${id}-stack`}\n          label={label}\n          views={views}\n          backLabel={backLabel}\n        />\n      </div>\n    );\n  }\n  const listPane = resizable ? (\n    <ResizableRegion\n      id={`${id}-list`}\n      label={listTitle || 'List'}\n      size={resizable.size}\n      min={resizable.min}\n      max={resizable.max}\n    >\n      <div class=\"kui-split-view__list kui-pane\" data-split-list>\n        {list}\n      </div>\n    </ResizableRegion>\n  ) : (\n    <div class=\"kui-split-view__list kui-pane\" data-split-list>\n      {list}\n    </div>\n  );\n  return (\n    <div\n      class={`kui-split-view ${className}`.trim()}\n      id={id}\n      data-component=\"split-view\"\n      data-split-mode=\"split\"\n      aria-label={label}\n    >\n      {listPane}\n      <div\n        class=\"kui-split-view__detail kui-pane\"\n        data-split-detail\n        aria-label={detailTitle || undefined}\n      >\n        {detail}\n      </div>\n    </div>\n  );\n}\n"]}

package/dist/state-banner.d.ts

@@ -1,15 +1,21 @@
 import { SafeHtml } from 'kerfjs';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 
-type StateBannerTone = 'neutral' | 'info' | 'success' | 'warning' | 'danger';
+type StateBannerTone = 'neutral' | 'info' | 'pop' | 'success' | 'warning' | 'danger';
+type StateBannerUrgency = 'status' | 'alert';
 interface StateBannerProps {
     title: string;
     detail?: string;
+    /** Optional compact status or count shown beside the title. */
+    badge?: string;
     icon?: SafeHtml;
-    action?: SafeHtml;
+    action?: KerfUiContent;
     tone?: StateBannerTone;
-    urgency?: 'status' | 'alert';
+    urgency?: StateBannerUrgency;
     className?: string;
+    /** Render the title, badge, and detail as unanimated loading skeletons, keeping the icon and tone. */
+    placeholder?: boolean;
 }
-declare function StateBanner({ title, detail, icon, action, tone, urgency, className }: StateBannerProps): SafeHtml;
+declare function StateBanner({ title, detail, badge, icon, action, tone, urgency, className, placeholder, }: StateBannerProps): SafeHtml;
 
-export { StateBanner, type StateBannerProps, type StateBannerTone };
+export { StateBanner, type StateBannerProps, type StateBannerTone, type StateBannerUrgency };

package/dist/state-banner.js

@@ -1,3 +1,5 @@
-export { StateBanner } from './chunk-VHW5YNIB.js';
+export { StateBanner } from './chunk-UDHHKZWO.js';
+
+
 
 //# sourceMappingURL=state-banner.js.map

package/dist/styles/app-tab.css

@@ -26,6 +26,13 @@
   align-items: center;
   flex: none;
 }
+.kui-app-tab[data-size="compact"] {
+  height: 2rem;
+}
+.kui-app-tab[data-presentation="segmented"] {
+  border-radius: var(--kui-radius-s);
+  box-shadow: none;
+}
 .kui-app-tab:hover {
   border-color: var(--kui-color-neutral-border-normal);
   background: var(--kui-app-tab-hover-background);
@@ -92,12 +99,31 @@
   flex: none;
 }
 .kui-app-tab__name {
+  max-width: var(--kui-app-tab-label-max-width, none);
   overflow: hidden;
   font-size: var(--kui-font-xs);
   font-weight: 650;
   text-overflow: ellipsis;
   white-space: nowrap;
 }
+.kui-app-tab[data-presentation="icon-only"] .kui-app-tab__select {
+  width: 100%;
+  justify-content: center;
+}
+.kui-app-tab[data-presentation="icon-only"] .kui-app-tab__name {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  clip-path: inset(50%);
+}
+.kui-app-tab[data-presentation="icon-only"] {
+  width: 2rem;
+  min-width: 2rem;
+}
 .kui-app-tab__trailing {
   display: grid;
   min-width: 1.275rem;