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

package/dist/types-CVgIwSdq.d.ts

@@ -0,0 +1,189 @@
+import { ToolbarConfig } from './toolbar.js';
+import { WorkbenchPanel } from './workbench.js';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.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;
+}
+/**
+ * The UX Review capture link a {@link Catalog} shows when it knows the local
+ * project directory (see `uxReviewPlugin` and `wireCatalog`'s
+ * `onUxReviewProject`).
+ */
+interface CatalogUxReview {
+    /** The absolute project directory UX Review files captures under. */
+    projectDirectory: string;
+    /** The catalog's name in the capture title and context (default `brand.title`). */
+    name?: string;
+}
+type CatalogStageRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
+    'data-catalog-stage'?: never;
+    'data-background-style'?: never;
+}>;
+/** Background used behind catalog specimens. */
+type CatalogBackgroundStyle = 'checkerboard' | 'vertical-stripes' | 'layout-guide' | 'surface' | 'sunken';
+/**
+ * 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;
+}
+/**
+ * The Catalog settings pane's configuration, forwarded to its Workbench right
+ * rail. Everything is optional; omitted fields keep the Catalog's defaults.
+ */
+interface CatalogSettingsConfig extends Pick<WorkbenchPanel, 'resizable' | 'separator' | 'collapseMotion' | 'presentation' | 'responsiveOverlayAt' | 'compactOverlay'> {
+    /**
+     * Pane 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 `settingsSize`, which writes each committed resize to it.
+     */
+    size?: number;
+    /** The pane's title (default `Settings`); it also names the toggle. */
+    title?: string;
+    /** The pane header toolbar's configuration. */
+    toolbar?: ToolbarConfig;
+}
+interface CatalogProps {
+    /**
+     * The catalog's `id` (default `kui-catalog`). Its Workbench derives the
+     * sidebar's id from it (`<id>-left-rail`) and the settings pane's
+     * (`<id>-right-rail`), which `wireCatalog` wires.
+     */
+    id?: string;
+    brand: CatalogBrand;
+    sections: readonly CatalogSection[];
+    active: string;
+    content: KerfUiContent;
+    collapsed?: boolean;
+    theme?: 'light' | 'dark';
+    /** Show the controlled increased-contrast toggle when supplied. The app applies the preference. */
+    increasedContrast?: boolean;
+    /** Show the controlled reduced-motion toggle when supplied. The app applies the preference. */
+    reducedMotion?: boolean;
+    /** Show the preview background chooser; `backgroundStyle` remains app-owned. */
+    backgroundControl?: boolean;
+    headerActions?: KerfUiContent;
+    /**
+     * The active entry's settings (variant and state controls for its preview).
+     * When supplied, the Catalog renders a settings pane beside the stage — a
+     * Workbench right rail titled `settingsPanel.title` — with the standard
+     * toggle: in the pane's header while it is open, at the end of the entry
+     * toolbar while it is collapsed. Omit it (or pass `null`) for an entry with
+     * no settings; neither the pane nor the toggle renders. Below the
+     * Workbench's `narrow` breakpoint the pane overlays the stage.
+     */
+    settings?: KerfUiContent;
+    /**
+     * Whether the settings pane is collapsed (default `false`). The app owns
+     * it; hand the same signal to `wireCatalog`'s `settingsCollapsed`, which
+     * flips it from the toggle and makes the pane a transient overlay on a
+     * small screen.
+     */
+    settingsCollapsed?: boolean;
+    /**
+     * The settings pane's title, size, resizing, and overlay configuration
+     * (default: `Settings`, 288px, not resizable, an overlay below the
+     * Workbench's `narrow` breakpoint, `inset` in a compact Workbench).
+     */
+    settingsPanel?: CatalogSettingsConfig;
+    /**
+     * Show a "Capture region" link to UX Review after `headerActions`, preset
+     * with the project and the active entry. Supply it once the project is known
+     * (`wireCatalog`'s `onUxReviewProject`); omit it on static hosting.
+     */
+    uxReview?: CatalogUxReview;
+    secondarySections?: CatalogSecondaryGroup;
+    sidebarFooter?: KerfUiContent;
+    status?: KerfUiContent;
+    /** Preview background (default `checkerboard`). */
+    backgroundStyle?: CatalogBackgroundStyle;
+    /** Consumer-owned data attributes applied to the preview stage. */
+    stageRootAttributes?: CatalogStageRootAttributes;
+    selectAction?: string;
+    toggleSidebarAction?: string;
+    toggleThemeAction?: string;
+    toggleContrastAction?: string;
+    toggleMotionAction?: string;
+    selectBackgroundAction?: string;
+    toggleSecondaryAction?: string;
+    /** The settings pane toggle's `data-action` (default `catalog-toggle-settings`). */
+    toggleSettingsAction?: 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, CatalogBackgroundStyle as a, CatalogProps as b, CatalogBrand as c, CatalogEntry as d, CatalogRelated as e, CatalogSecondaryGroup as f, CatalogSection as g, CatalogSettingsConfig as h, CatalogStageRootAttributes as i, CatalogUxReview as j };

package/dist/value-table.d.ts

@@ -1,4 +1,7 @@
+import * as kerfjs from 'kerfjs';
 import { SafeHtml } from 'kerfjs';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import { CssLength } from './css-values.js';
 
 interface ValueTableRowProps {
     label: string | SafeHtml;
@@ -7,14 +10,37 @@ interface ValueTableRowProps {
     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, placeholder }: ValueTableRowProps): SafeHtml;
+declare function ValueTableRow({ label, value, icon, className, placeholder, slot, }: ValueTableRowProps): SafeHtml;
 
+/** `columns` keeps label and value side by side; `stacked` puts each value under its label. */
+type ValueTablePresentation = 'columns' | 'stacked';
+/** Table width below which columns stack: `compact` is 512px, `narrow` 576px. */
+type ValueTableStackBelow = 'compact' | 'narrow';
 interface ValueTableProps {
     label: string;
+    /** Compact row spacing for metadata-dense surfaces. */
+    density?: 'default' | 'compact';
+    /**
+     * Minimum width of the label column (for example `px(160)`); the value then
+     * takes the rest of the row. Omitted, label and value share the row by
+     * content.
+     */
+    labelWidth?: CssLength;
+    /** Side-by-side columns (default) or values stacked under their labels. */
+    presentation?: ValueTablePresentation;
+    /**
+     * Stack the rows only while the table itself is narrower than the preset,
+     * so one table reads as columns in a wide dialog and stacks on a phone.
+     */
+    stackBelow?: ValueTableStackBelow;
     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, labelWidth, presentation, stackBelow, className, children, slot, }: ValueTableProps): kerfjs.SafeHtml;
 
-export { ValueTable, type ValueTableProps, ValueTableRow, type ValueTableRowProps };
+export { ValueTable, type ValueTablePresentation, type ValueTableProps, ValueTableRow, type ValueTableRowProps, type ValueTableStackBelow };

package/dist/value-table.js

@@ -1,4 +1,5 @@
-export { ValueTable, ValueTableRow } from './chunk-37T3VNIZ.js';
+export { ValueTable, ValueTableRow } from './chunk-DZJ4GBSP.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

@@ -1,3 +1,22 @@
+import { Signal } from 'kerfjs';
+import { a as CatalogBackgroundStyle } from './types-CVgIwSdq.js';
+import './toolbar.js';
+import './semantic-content-BbzjvSu9.js';
+import './sides-BPSWde0A.js';
+import './pane.js';
+import './scroll-clearance-BikHljTc.js';
+import './css-values.js';
+import './workbench.js';
+import './nav-stack-CU_0dKtI.js';
+import './list.js';
+import './extension-attributes-mu8MFUl0.js';
+import './flex-alignment-4ms8ZbV8.js';
+import './panel-toolbar-vg6Ir5Dy.js';
+import './lucide-icon.js';
+import 'lucide';
+import './toolbar-text.js';
+import './resizable-region.js';
+
 interface WireCatalogOptions {
     /** Invoked with the entry id when a sidebar item or a related-entry option is chosen. */
     onSelect: (id: string) => void;
@@ -5,22 +24,109 @@ interface WireCatalogOptions {
     onToggleSidebar?: () => void;
     /** Invoked when the theme toggle is activated. */
     onToggleTheme?: () => void;
+    /** Report a contrast-toggle press; the app updates its signal and applies the preference. */
+    onToggleContrast?: () => void;
+    /** Report a reduced-motion-toggle press; the app updates its signal and applies the preference. */
+    onToggleMotion?: () => void;
+    /** Report a preview background choice; the app updates `backgroundStyle`. */
+    onSelectBackground?: (style: CatalogBackgroundStyle) => void;
+    /**
+     * Invoked when the settings pane toggle is activated. With
+     * `settingsCollapsed`, `wireCatalog` has already flipped the signal.
+     */
+    onToggleSettings?: () => 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;
+    toggleContrastAction?: string;
+    toggleMotionAction?: string;
+    selectBackgroundAction?: string;
     toggleSecondaryAction?: string;
+    toggleSettingsAction?: 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 settings pane's app-owned collapsed flag, rendered as the Catalog's
+     * `settingsCollapsed`. With it, `wireCatalog` owns the pane's toggle (each
+     * press flips the signal) and wires the pane like any Workbench rail: a
+     * transient overlay on a small screen (collapsed as the breakpoint applies,
+     * closed on Escape or a press outside, focus handed back).
+     */
+    settingsCollapsed?: Signal<boolean>;
+    /**
+     * The app-owned settings pane width signal for a Catalog rendered with
+     * `settingsPanel={{ resizable: true, size: settingsSize.value }}`. Each
+     * committed drag or keyboard resize is written to it.
+     */
+    settingsSize?: Signal<number>;
+    /**
+     * With `settingsSize`, load and save the width under this storage key so
+     * the catalog remembers the user's settings pane width.
+     */
+    settingsStorageKey?: string;
+    /** The Catalog's `id`, when it is not the default `kui-catalog`. */
+    id?: string;
+    /**
+     * Ask the page's server once for its UX Review project directory (served by
+     * `uxReviewPlugin` from `@kerfjs/ui/vite-ux-review`) and report it, so the
+     * app can render the Catalog with `uxReview`. Never called on static
+     * hosting or a server without the plugin.
+     */
+    onUxReviewProject?: (projectDirectory: string) => void;
+}
+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;
 /**
  * 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
+ * item selection (and the related-entry popup menu), the sidebar collapse toggle,
+ * the settings pane 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`.
- * Returns a disposer.
+ * 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, selectAction, toggleSidebarAction, toggleThemeAction, toggleSecondaryAction, }: WireCatalogOptions): () => void;
+declare function wireCatalog(root: HTMLElement, { onSelect, onToggleSidebar, onToggleTheme, onToggleContrast, onToggleMotion, onSelectBackground, onToggleSecondary, onToggleSettings, urlParam, revealSelection, selectAction, toggleSidebarAction, toggleThemeAction, toggleContrastAction, toggleMotionAction, selectBackgroundAction, toggleSecondaryAction, toggleSettingsAction, collapsed, sidebarSize, sidebarStorageKey, settingsCollapsed, settingsSize, settingsStorageKey, id: catalogId, onUxReviewProject, }: WireCatalogOptions): () => void;
 
-export { type WireCatalogOptions, wireCatalog };
+export { type CatalogRevealOptions, type WireCatalogOptions, revealCatalogEntry, wireCatalog };