@kerfjs/ui 5.0.0-beta.6 → 5.0.0-beta.61

package/dist/toolbar-control-group.d.ts

@@ -1,15 +1,73 @@
-import { SafeHtml } from 'kerfjs';
+import * as kerfjs from 'kerfjs';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 
+type ToolbarControlGroupAppearance = 'contained' | 'borderless';
+type ToolbarControlGroupTone = 'default' | 'dark';
+type ToolbarControlGroupButtonAppearance = 'plain' | 'push';
+type ToolbarControlGroupShape = 'pill' | 'rounded';
+type ToolbarControlGroupSize = 'default' | 'compact';
+type ToolbarControlGroupDensity = 'comfortable' | 'tight';
+type ToolbarControlGroupContent = 'icon' | 'text' | 'mixed' | 'avatar' | 'search';
+type ToolbarControlGroupFocusRing = 'control' | 'outline' | 'halo';
+type ToolbarControlGroupSelectedChrome = 'raised' | 'filled' | 'outline';
+type ToolbarControlGroupSelectedTone = 'brand' | 'neutral' | 'pop';
+type ToolbarControlGroupOverflow = 'visible' | 'scroll';
+type ToolbarControlGroupMenuInset = 'standard' | 'compact' | 'list-zero';
+type ToolbarControlGroupVisibility = 'always' | 'compact-only';
+interface ToolbarActionLinkProps {
+    href: string;
+    label: string;
+    icon?: KerfUiContent;
+    /** Optional machine-readable detail hidden visually but included in the default accessible name. */
+    detail?: string;
+    /** Override the accessible name when surrounding context is needed. */
+    ariaLabel?: string;
+    /** Open in a new tab with a safe rel and announce that behavior. */
+    external?: boolean;
+    className?: string;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
+}
+/** A semantic anchor with ToolbarControlGroup-owned action geometry. */
+declare function ToolbarActionLink({ href, label, icon, detail, ariaLabel, external, className, slot, }: ToolbarActionLinkProps): kerfjs.SafeHtml;
 interface ToolbarControlGroupProps {
-    children: SafeHtml | SafeHtml[];
+    children: KerfUiContent;
     label?: string;
     className?: string;
     expanded?: boolean;
     single?: boolean;
-    appearance?: 'contained' | 'borderless';
-    tone?: 'default' | 'dark';
-    buttonAppearance?: 'plain' | 'push';
+    appearance?: ToolbarControlGroupAppearance;
+    tone?: ToolbarControlGroupTone;
+    buttonAppearance?: ToolbarControlGroupButtonAppearance;
+    /** Corner shape: fully round `pill` (default) or a softer `rounded` rectangle. */
+    shape?: ToolbarControlGroupShape;
+    size?: ToolbarControlGroupSize;
+    density?: ToolbarControlGroupDensity;
+    content?: ToolbarControlGroupContent;
+    /** Whether controls paint focus individually or the group paints an outline/halo on focus-within. */
+    focusRing?: ToolbarControlGroupFocusRing;
+    selectedChrome?: ToolbarControlGroupSelectedChrome;
+    selectedTone?: ToolbarControlGroupSelectedTone;
+    /** Size a nested Web Awesome dropdown trigger as part of this group. */
+    nestedDropdown?: boolean;
+    /** Configure the nested dropdown menu inset without consumer ::part() CSS. */
+    menuInset?: ToolbarControlGroupMenuInset;
+    /** Keep an overlong row of actions inside the available width with horizontal scrolling. */
+    overflow?: ToolbarControlGroupOverflow;
+    /** Responsive visibility owned by the enclosing Toolbar container. */
+    visibility?: ToolbarControlGroupVisibility;
+    /** Move this group into the work-area toolbar when its panel collapses. */
+    relocateOnCollapse?: boolean;
+    /** Add contrast behind photo-backed avatar content. */
+    scrim?: boolean;
+    /**
+     * Avatar image URL. A single-control group paints it on the group; a
+     * multi-control group paints it only on the pressed selection highlight.
+     */
+    avatarImage?: string;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
 }
-declare function ToolbarControlGroup({ children, label, className, expanded, single, appearance, tone, buttonAppearance }: ToolbarControlGroupProps): SafeHtml;
+declare function ToolbarControlGroup({ children, label, className, expanded, single, appearance, tone, buttonAppearance, shape, size, density, content, focusRing, selectedChrome, selectedTone, nestedDropdown, menuInset, overflow, visibility, relocateOnCollapse, scrim, avatarImage, slot, }: ToolbarControlGroupProps): kerfjs.SafeHtml;
 
-export { ToolbarControlGroup, type ToolbarControlGroupProps };
+export { ToolbarActionLink, type ToolbarActionLinkProps, ToolbarControlGroup, type ToolbarControlGroupAppearance, type ToolbarControlGroupButtonAppearance, type ToolbarControlGroupContent, type ToolbarControlGroupDensity, type ToolbarControlGroupFocusRing, type ToolbarControlGroupMenuInset, type ToolbarControlGroupOverflow, type ToolbarControlGroupProps, type ToolbarControlGroupSelectedChrome, type ToolbarControlGroupSelectedTone, type ToolbarControlGroupShape, type ToolbarControlGroupSize, type ToolbarControlGroupTone, type ToolbarControlGroupVisibility };

package/dist/toolbar-control-group.js

@@ -1,3 +1,3 @@
-export { ToolbarControlGroup } from './chunk-MFKMHK5W.js';
+export { ToolbarActionLink, ToolbarControlGroup } from './chunk-7JUBXOIV.js';
 
 //# sourceMappingURL=toolbar-control-group.js.map

package/dist/toolbar-text.d.ts

@@ -1,13 +1,46 @@
 import * as kerfjs from 'kerfjs';
 
-type ToolbarTextSize = 'xlarge' | 'large' | 'default' | 'small';
-interface ToolbarTextProps {
+type ToolbarTextSize = 'xlarge' | 'large' | 'default' | 'small' | 'xsmall';
+/** ARIA heading level for a title exposed as a heading landmark. */
+type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
+interface ToolbarTextBaseProps {
     text: string;
     size?: ToolbarTextSize;
     className?: string;
     /** Optional id, e.g. so a dialog can reference the title via aria-labelledby. */
     id?: string;
+    /**
+     * Expose heading semantics (`role="heading"` + `aria-level`) so the text acts as
+     * a heading landmark — e.g. a page's primary title. Omit to keep the plain span
+     * (the default), which suits a dialog title referenced via `aria-labelledby`.
+     */
+    headingLevel?: HeadingLevel;
+    /** Render the text as an unanimated loading skeleton instead of its value. */
+    placeholder?: boolean;
+    /**
+     * Show a trailing ellipsis (…) where the text is truncated — on the single line
+     * (default), or at the `maxLines` boundary when wrapping. Set false to hard-clip
+     * instead. Default true.
+     */
+    ellipsis?: boolean;
+    /**
+     * Grow to fill the free space of the flex row it sits in (a Toolbar zone),
+     * truncating at the space left by its siblings instead of taking only its
+     * text's width. Default false.
+     */
+    fill?: boolean;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
 }
-declare function ToolbarText({ text, size, className, id }: ToolbarTextProps): kerfjs.SafeHtml;
+type ToolbarTextWrappingProps = {
+    /** Wrap onto multiple lines; combine with `maxLines` to cap them. */
+    wrap: true;
+    maxLines?: number | null;
+} | {
+    wrap?: false;
+    maxLines?: never;
+};
+type ToolbarTextProps = ToolbarTextBaseProps & ToolbarTextWrappingProps;
+declare function ToolbarText({ text, size, className, id, headingLevel, placeholder, wrap, ellipsis, maxLines, fill, slot, }: ToolbarTextProps): kerfjs.SafeHtml;
 
-export { ToolbarText, type ToolbarTextProps, type ToolbarTextSize };
+export { type HeadingLevel, ToolbarText, type ToolbarTextProps, type ToolbarTextSize };

package/dist/toolbar-text.js

@@ -1,3 +1,5 @@
-export { ToolbarText } from './chunk-24Z2XE6C.js';
+export { ToolbarText } from './chunk-3SXMEK3B.js';
+
+
 
 //# sourceMappingURL=toolbar-text.js.map

package/dist/toolbar.d.ts

@@ -1,13 +1,62 @@
-import { SafeHtml } from 'kerfjs';
+import * as kerfjs from 'kerfjs';
+import { PaneSeparatorSide } from './pane.js';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import { S as Sides } from './sides-BPSWde0A.js';
 
 interface ToolbarProps {
-    leading?: SafeHtml;
-    center?: SafeHtml;
-    trailing?: SafeHtml;
+    leading?: KerfUiContent;
+    center?: KerfUiContent;
+    trailing?: KerfUiContent;
     label?: string;
-    divider?: boolean;
+    /**
+     * Physical divider edges in canonical top/right/bottom/left order, drawn
+     * always. Defaults to none: a toolbar pinned over or under scrolling content
+     * gets its divider from the scroll state instead — a `Pane` draws the line
+     * between its chrome and content while content is scrolled away beneath it,
+     * and `wireScrollDividers` `targets` can name a toolbar as chrome, which
+     * then draws its facing side the same way.
+     */
+    dividerSides?: Sides;
+    /** Horizontal treatment of the center zone. Defaults to centered content. */
+    centerAlign?: 'center' | 'stretch';
+    /**
+     * Component-owned responsive layout; applications choose the policy rather
+     * than restyling toolbar internals. Under every policy the trailing zone
+     * wraps its groups instead of clipping an action, and the center zone keeps
+     * its whole content width: when the zones do not fit one row, the leading
+     * title truncates with an ellipsis rather than the center overlapping it.
+     * - `none` keeps one row; the leading identity truncates first.
+     * - `stack` stacks the zones at `responsiveAt`, wrapping stacked control
+     *   groups onto further rows.
+     * - `wrap` keeps one row while every zone fits at its natural width, and
+     *   otherwise moves the trailing zone below a whole leading identity.
+     * - `center-priority` gives an expanded center control the full row.
+     * - `trailing-priority` moves an expanded trailing control to a full row
+     *   below the leading identity at `responsiveAt`.
+     */
+    responsive?: 'none' | 'stack' | 'wrap' | 'center-priority' | 'trailing-priority';
+    /** Container width at which `stack` or `trailing-priority` activates. */
+    responsiveAt?: 'compact' | 'narrow';
+    /**
+     * Screen edges this toolbar claims for device safe-area compensation, for an
+     * app bar or bottom bar that sits directly at a screen edge rather than in a
+     * Pane header or footer. Each listed side pads by the inset its surrounding
+     * layout reports through `--kui-edge-inset-*`, or the full device inset when
+     * nothing routes that edge, while the toolbar's box and dividers paint
+     * through. Omitted, the toolbar pads only the inline edges an owner such as
+     * a Pane header hands it, and never a block edge.
+     */
+    safeAreaEdges?: readonly PaneSeparatorSide[];
     className?: string;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
 }
-declare function Toolbar({ leading, center, trailing, label, divider, className }: ToolbarProps): SafeHtml;
+/**
+ * A toolbar's configuration, apart from its content: the props a composite
+ * that renders a `Toolbar` for the app (a Workbench or CollapsiblePanel
+ * toolbar) forwards, so the app configures that toolbar instead of styling it.
+ */
+type ToolbarConfig = Pick<ToolbarProps, 'dividerSides' | 'centerAlign' | 'responsive' | 'responsiveAt' | 'safeAreaEdges'>;
+declare function Toolbar({ leading, center, trailing, label, dividerSides, centerAlign, responsive, responsiveAt, safeAreaEdges, className, slot, }: ToolbarProps): kerfjs.SafeHtml;
 
-export { Toolbar, type ToolbarProps };
+export { Sides, Toolbar, type ToolbarConfig, type ToolbarProps };

package/dist/toolbar.js

@@ -1,3 +1,3 @@
-export { Toolbar } from './chunk-DAFFDO33.js';
+export { Toolbar } from './chunk-MERWRTBG.js';
 
 //# sourceMappingURL=toolbar.js.map

package/dist/types-BuHELdXR.d.ts

@@ -0,0 +1,117 @@
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import { ToolbarConfig } from './toolbar.js';
+import { WorkbenchPanel } from './workbench.js';
+
+/** A reference link shown in the detail footer for the active entry. */
+interface CatalogResource {
+    label: string;
+    href: string;
+    /** Optional machine-readable detail (e.g. a file path) carried by the action link. */
+    detail?: string;
+}
+/** A related entry offered in the detail footer's "Related entries" popup menu. */
+interface CatalogRelated {
+    id: string;
+    name: string;
+    /** Group heading in the menu, e.g. "Uses" / "Used by". */
+    group: string;
+}
+interface CatalogEntry {
+    id: string;
+    name: string;
+    description?: string;
+    /** Short metadata tags shown at the trailing edge of the sidebar row. */
+    tags?: readonly string[];
+    resources?: readonly CatalogResource[];
+    related?: readonly CatalogRelated[];
+}
+interface CatalogSection {
+    category: string;
+    entries: readonly CatalogEntry[];
+}
+/** A quieter, optionally collapsible group of catalog sections. */
+interface CatalogSecondaryGroup {
+    label: string;
+    sections: readonly CatalogSection[];
+    collapsible?: boolean;
+    expanded?: boolean;
+}
+interface CatalogBrand {
+    title: string;
+    subtitle?: string;
+    /** Logo image URL (rendered decorative). Omit for a text-only brand. */
+    logoUrl?: string;
+}
+type CatalogStageRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
+    'data-catalog-stage'?: never;
+}>;
+/**
+ * The Catalog sidebar's configuration, forwarded to its Workbench left rail.
+ * Everything is optional; omitted fields keep the Catalog's defaults.
+ */
+interface CatalogSidebarConfig extends Pick<WorkbenchPanel, 'resizable' | 'separator' | 'collapseMotion' | 'presentation' | 'responsiveOverlayAt' | 'compactOverlay'> {
+    /**
+     * Sidebar width in px (default 288). With `resizable`, it is the current
+     * width: render the app's size signal here and hand the same signal to
+     * `wireCatalog`'s `sidebarSize`, which writes each committed resize to it.
+     */
+    size?: number;
+    /** The sidebar header toolbar's configuration (default: no divider; its pane draws one while scrolled). */
+    toolbar?: ToolbarConfig;
+}
+interface CatalogProps {
+    /**
+     * The catalog's `id` (default `kui-catalog`). Its Workbench derives the
+     * sidebar's id from it (`<id>-left-rail`), which `wireCatalog` wires.
+     */
+    id?: string;
+    brand: CatalogBrand;
+    sections: readonly CatalogSection[];
+    active: string;
+    content: KerfUiContent;
+    collapsed?: boolean;
+    theme?: 'light' | 'dark';
+    headerActions?: KerfUiContent;
+    secondarySections?: CatalogSecondaryGroup;
+    sidebarFooter?: KerfUiContent;
+    status?: KerfUiContent;
+    geometryOverlay?: boolean;
+    /** Consumer-owned data attributes applied to the preview stage. */
+    stageRootAttributes?: CatalogStageRootAttributes;
+    selectAction?: string;
+    toggleSidebarAction?: string;
+    toggleThemeAction?: string;
+    toggleSecondaryAction?: string;
+    /**
+     * Whether the entry toolbar and description stay pinned above the preview
+     * (`fixed`), scroll away with it (`scroll`), or stay pinned while the entry
+     * pane is tall enough and scroll with the preview when it is short (`auto`,
+     * default), so a short window or large text never squeezes the preview out.
+     */
+    headerPlacement?: 'fixed' | 'scroll' | 'auto';
+    /**
+     * The same for the status and resource footer (default `auto`).
+     */
+    footerPlacement?: 'fixed' | 'scroll' | 'auto';
+    /**
+     * The sidebar's size, resizing, and overlay configuration, forwarded to the
+     * Workbench left rail (default: 288px, not resizable, an overlay below the
+     * Workbench's `narrow` breakpoint, `inset` in a compact Workbench).
+     */
+    sidebar?: CatalogSidebarConfig;
+    /**
+     * The entry toolbar's configuration (default `responsive: 'wrap'`: the entry
+     * title stays whole and the actions wrap below it when narrow).
+     */
+    mainToolbar?: ToolbarConfig;
+    /**
+     * The resource footer toolbar's configuration (default no divider,
+     * `responsive: 'stack'` at `responsiveAt: 'narrow'`).
+     */
+    footerToolbar?: ToolbarConfig;
+    className?: string;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
+}
+
+export type { CatalogResource as C, CatalogProps as a, CatalogBrand as b, CatalogEntry as c, CatalogRelated as d, CatalogSecondaryGroup as e, CatalogSection as f, CatalogStageRootAttributes as g };

package/dist/value-table.d.ts

@@ -1,18 +1,28 @@
+import * as kerfjs from 'kerfjs';
 import { SafeHtml } from 'kerfjs';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 
 interface ValueTableRowProps {
     label: string | SafeHtml;
     value: string | SafeHtml;
     icon?: SafeHtml;
     className?: string;
+    /** Render the value as an unanimated loading skeleton, keeping the field label. */
+    placeholder?: boolean;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
 }
-declare function ValueTableRow({ label, value, icon, className }: ValueTableRowProps): SafeHtml;
+declare function ValueTableRow({ label, value, icon, className, placeholder, slot, }: ValueTableRowProps): SafeHtml;
 
 interface ValueTableProps {
     label: string;
+    /** Compact row spacing for metadata-dense surfaces. */
+    density?: 'default' | 'compact';
     className?: string;
-    children: SafeHtml | readonly SafeHtml[];
+    children: KerfUiContent;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
 }
-declare function ValueTable({ label, className, children }: ValueTableProps): SafeHtml;
+declare function ValueTable({ label, density, className, children, slot, }: ValueTableProps): kerfjs.SafeHtml;
 
 export { ValueTable, type ValueTableProps, ValueTableRow, type ValueTableRowProps };

package/dist/value-table.js

@@ -1,3 +1,5 @@
-export { ValueTable, ValueTableRow } from './chunk-R6JHHBKQ.js';
+export { ValueTable, ValueTableRow } from './chunk-P7D3EMXM.js';
+
+
 
 //# sourceMappingURL=value-table.js.map

package/dist/webawesome.d.ts

@@ -23,7 +23,11 @@ declare module 'kerfjs/jsx-runtime' {
                 'aria-label'?: string;
                 value?: string;
                 placeholder?: string;
+                hint?: string;
                 disabled?: boolean;
+                size?: 'xs' | 's' | 'm' | 'l' | 'xl';
+                appearance?: 'filled' | 'outlined' | 'filled-outlined';
+                placement?: 'top' | 'bottom';
             };
             'wa-option': KerfCustomElement & {
                 value?: string;
@@ -39,7 +43,9 @@ declare module 'kerfjs/jsx-runtime' {
             'wa-comparison': KerfCustomElement;
             'wa-copy-button': KerfCustomElement;
             'wa-details': KerfCustomElement;
-            'wa-divider': KerfCustomElement;
+            'wa-divider': KerfCustomElement & {
+                orientation?: 'horizontal' | 'vertical';
+            };
             'wa-dialog': KerfCustomElement;
             'wa-drawer': KerfCustomElement;
             'wa-button': KerfCustomElement & {
@@ -50,6 +56,7 @@ declare module 'kerfjs/jsx-runtime' {
             };
             'wa-dropdown': KerfCustomElement & {
                 placement?: string;
+                size?: 'xs' | 's' | 'm' | 'l' | 'xl';
             };
             'wa-dropdown-item': KerfCustomElement;
             'wa-format-bytes': KerfCustomElement;

package/dist/wire-catalog.d.ts

@@ -0,0 +1,82 @@
+import { Signal } from 'kerfjs';
+
+interface WireCatalogOptions {
+    /** Invoked with the entry id when a sidebar item or a related-entry option is chosen. */
+    onSelect: (id: string) => void;
+    /** Invoked when the sidebar collapse/expand control is activated. */
+    onToggleSidebar?: () => void;
+    /** Invoked when the theme toggle is activated. */
+    onToggleTheme?: () => void;
+    /** Invoked when the secondary (ecosystem) group's disclosure toggle is activated. */
+    onToggleSecondary?: () => void;
+    /** When set, `?<urlParam>=<id>` is written on select via `history.replaceState`. */
+    urlParam?: string;
+    /**
+     * Reveal the chosen sidebar row after selection. `true` uses desktop-safe
+     * defaults; pass options to customize scroll alignment or the media guard.
+     */
+    revealSelection?: boolean | CatalogRevealOptions;
+    selectAction?: string;
+    toggleSidebarAction?: string;
+    toggleThemeAction?: string;
+    toggleSecondaryAction?: string;
+    /**
+     * The sidebar's app-owned collapsed flag. With it, the catalog's Workbench
+     * sidebar is wired like any Workbench rail: it becomes a transient overlay
+     * on a small screen (collapsed as the breakpoint applies, closed on Escape
+     * or a press outside, focus handed back), and choosing an entry from the
+     * open overlay closes it.
+     */
+    collapsed?: Signal<boolean>;
+    /**
+     * The app-owned sidebar width signal for a Catalog rendered with
+     * `sidebar={{ resizable: true, size: sidebarSize.value }}`. Each committed
+     * drag or keyboard resize is written to it.
+     */
+    sidebarSize?: Signal<number>;
+    /**
+     * With `sidebarSize`, load and save the width under this storage key so the
+     * catalog remembers the user's sidebar width.
+     */
+    sidebarStorageKey?: string;
+    /** The Catalog's `id`, when it is not the default `kui-catalog`. */
+    id?: string;
+}
+interface CatalogRevealOptions {
+    /** Scroll alignment within the sidebar. Default `'nearest'`. */
+    block?: ScrollLogicalPosition;
+    /** Cross-axis alignment. Default `'nearest'`. */
+    inline?: ScrollLogicalPosition;
+    /** Scroll behavior. Default `'auto'`. */
+    behavior?: ScrollBehavior;
+    /**
+     * Only reveal when this media query matches. Defaults to the Catalog's
+     * desktop layout; pass `false` to reveal at every viewport size.
+     */
+    media?: string | false;
+}
+/**
+ * Reveal one Catalog sidebar entry after the controlled render settles without
+ * moving focus. Returns a cancellation function for rapid selection changes.
+ */
+declare function revealCatalogEntry(root: HTMLElement, id: string, { block, inline, behavior, media, }?: CatalogRevealOptions): () => void;
+/**
+ * Keep a Catalog's opt-in geometry overlay synchronized with its preview.
+ * Specimens receive computed border highlights (or a dashed bound when they
+ * have no border and are transparent), while positive computed margins use
+ * devtools-style orange bands. CSS/stylesheet-only changes are observed too.
+ * Returns a disposer.
+ */
+declare function wireCatalogGeometryOverlay(root: HTMLElement): () => void;
+/**
+ * Wire a {@link Catalog}'s interactions with one delegated listener set: sidebar
+ * item selection (and the related-entry popup menu), the sidebar collapse toggle, and
+ * the theme toggle. The app owns the `active`/`collapsed`/`theme` signals and updates
+ * them in the callbacks; optionally mirror the active id into the URL via `urlParam`.
+ * It also wires the scroll dividers below root (`wireScrollDividers`), so the
+ * catalog's panes and every example in it show their chrome dividers only
+ * while scrolled. Returns a disposer.
+ */
+declare function wireCatalog(root: HTMLElement, { onSelect, onToggleSidebar, onToggleTheme, onToggleSecondary, urlParam, revealSelection, selectAction, toggleSidebarAction, toggleThemeAction, toggleSecondaryAction, collapsed, sidebarSize, sidebarStorageKey, id: catalogId, }: WireCatalogOptions): () => void;
+
+export { type CatalogRevealOptions, type WireCatalogOptions, revealCatalogEntry, wireCatalog, wireCatalogGeometryOverlay };