@kerfjs/ui 5.0.0-beta.11 → 5.0.0-beta.110

package/dist/pane.d.ts

@@ -0,0 +1,258 @@
+import * as kerfjs from 'kerfjs';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import { S as ScrollClearance } from './scroll-clearance-BikHljTc.js';
+import { CssColor } from './css-values.js';
+
+/**
+ * What clear (fully transparent) chrome fades in as content scrolls beneath
+ * it: `none` stays clear; `material` fades in the translucent chrome
+ * material; `surface` fades in the opaque surface. The fade tracks the scroll
+ * over `scrollEdgeDistance` (opacity only), from the scroll state
+ * `wireScrollDividers` reports; unwired, the chrome stays clear.
+ */
+type ScrollEdge = 'none' | 'material' | 'surface';
+
+/** The color scheme an app declares for a {@link SurfaceTint}'s color. */
+type SurfaceTintScheme = 'light' | 'dark';
+/**
+ * A scoped tint for a layout surface: the app's color (usually sampled from
+ * artwork it already knows) and the scheme that color belongs to. Kerf does no
+ * color detection; `scheme` says whether the color reads as a light or a dark
+ * surface. Inside the scope the surface, raised surface, text, quiet text, and
+ * everything built on them (quiet fills, separators' backdrop, the chrome
+ * material) re-derive from the color, with lightness clamped so text keeps
+ * WCAG AA over any color.
+ */
+interface SurfaceTint {
+    color: CssColor;
+    scheme: SurfaceTintScheme;
+    /**
+     * An optional accent (usually the artwork's most vivid color). The scope's
+     * brand ramp re-derives from it: loud fills and their text, brand text and
+     * links, text on brand fills, and the focus ring, each clamped to keep AA.
+     */
+    accent?: CssColor;
+}
+
+/**
+ * Logical pane sides: where a {@link Pane} can show a separator and where it can
+ * compensate for a device safe-area inset.
+ */
+type PaneSeparatorSide = 'block-start' | 'block-end' | 'inline-start' | 'inline-end';
+/** Semantic root elements supported by {@link Pane}. */
+type PaneElement = 'article' | 'aside' | 'div' | 'main' | 'section';
+/** Semantic elements supported by the scrolling content slot. */
+type PaneContentElement = 'div' | 'main' | 'nav' | 'section';
+type PaneRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
+    'data-component'?: never;
+    'data-separator-block-start'?: never;
+    'data-separator-block-end'?: never;
+    'data-separator-inline-start'?: never;
+    'data-separator-inline-end'?: never;
+    'data-safe-area-block-start'?: never;
+    'data-safe-area-block-end'?: never;
+    'data-safe-area-inline-start'?: never;
+    'data-safe-area-inline-end'?: never;
+    'data-chrome-placement'?: never;
+    'data-chrome-dividers'?: never;
+    'data-appearance'?: never;
+    'data-background'?: never;
+    'data-kui-tint'?: never;
+    'data-kui-tint-accent'?: never;
+    'data-deep-inset'?: never;
+    'data-outlined'?: never;
+    'data-scroll-clearance'?: never;
+    'data-header-presentation'?: never;
+    'data-header-material'?: never;
+    'data-scroll-edge'?: never;
+    'data-scroll-edge-distance'?: never;
+    'data-header-overlay'?: never;
+    'data-compact-header'?: never;
+    'data-compact-footer'?: never;
+    'data-compact-header-open'?: never;
+    'data-compact-footer-open'?: never;
+}>;
+/** How a Pane's header and footer relate to its scrolling content. */
+type PaneChromePlacement = 'fixed' | 'auto';
+/**
+ * How a header or footer behaves when the pane's container presents
+ * compactly (a `NavStack` view, a `TabNavigator` scene, a full-screen dialog,
+ * or a compact `Workbench`): `fixed` stays docked and shrinks the content
+ * area; `scroll` sits inline with the content (a footer settles at the end
+ * and scrolls past when the content is longer); `overlay` lies over the
+ * content on the chrome material, shown only while the app opens it.
+ */
+type PaneCompactChrome = 'fixed' | 'scroll' | 'overlay';
+/** The compact chrome policy for a Pane's header and footer. */
+interface PaneCompactChromePolicy {
+    header?: PaneCompactChrome;
+    footer?: PaneCompactChrome;
+}
+/**
+ * When a Pane draws the divider between its pinned header or footer and its
+ * scrolling content: `scroll` while content is scrolled away beneath that
+ * chrome, as `wireScrollDividers` reports; `always`; or `none`.
+ */
+type PaneChromeDividers = 'scroll' | 'always' | 'none';
+/**
+ * How a Pane's header relates to its scrolling content: `docked` in its own
+ * row above the content, or `overlay` laid over the content's top edge on the
+ * translucent chrome material, so content scrolls visibly beneath it.
+ * `clear` lays it over
+ * the same edge fully transparent, for chrome over imagery: legibility comes
+ * from glass control groups or a scrim, and with `scrollEdge="material"` the
+ * chrome material fades in once content scrolls beneath it.
+ */
+type PaneHeaderPresentation = 'docked' | 'overlay' | 'clear';
+/** Background treatment of the Pane's scrolling work surface. */
+type PaneAppearance = 'default' | 'sunken';
+interface PaneProps {
+    /** Optional fixed chrome above the scrolling content, arranged vertically. */
+    header?: KerfUiContent;
+    /** The pane's primary vertical, scrolling content stack. */
+    children?: KerfUiContent;
+    /** Optional fixed chrome below the scrolling content. */
+    footer?: KerfUiContent;
+    /**
+     * Whether the header and footer stay pinned around the scrolling content.
+     * `fixed` (default) always pins them. `auto` pins them while the pane is
+     * tall enough, and below 480px of height (30rem, so it scales with the text
+     * size) lets the whole pane scroll as one column, so tall chrome can never
+     * squeeze the content to nothing.
+     */
+    chromePlacement?: PaneChromePlacement;
+    /**
+     * The divider under the header and over the footer, where they meet the
+     * scrolling content. Omitted defaults to `scroll` for a plain pane and
+     * `always` for `appearance="sunken"`. `scroll` shows the header's divider only
+     * while the content is scrolled down, and the footer's only while more
+     * content lies below — never when the content fits — once
+     * `wireScrollDividers` (`@kerfjs/ui/wire-scroll-dividers`) is wired above
+     * the pane; unwired, neither shows. `always` shows both; `none` neither.
+     * The line is drawn inside the chrome, so no state moves the content.
+     */
+    chromeDividers?: PaneChromeDividers;
+    /**
+     * `docked` (default) gives the header its own row above the scrolling
+     * content. `overlay` lays the header over the content's top edge on the
+     * translucent chrome material (`--kui-chrome-material`, opaque under
+     * `prefers-reduced-transparency`, forced colors, or without
+     * `backdrop-filter`), so content scrolls visibly beneath it. Once
+     * `wireScrollDividers` (`@kerfjs/ui/wire-scroll-dividers`) is wired above
+     * the pane it measures the header and publishes its height as the
+     * `--kui-scroll-clearance-block-start` context, which the content adds to
+     * its block-start padding and `scroll-padding` without any
+     * `scrollClearance` prop, so the first item, and anything focused or
+     * scrolled into view, rests clear of the header. Until then, and with
+     * `chromePlacement="auto"`, the header stays docked. Keep overlay header
+     * text in the normal text color: quiet text can fall below AA over the
+     * content passing beneath it.
+     */
+    /**
+     * What the header and footer do when the pane's container presents
+     * compactly (default `fixed`); roomy containers ignore it. The container
+     * interprets it, so set it on panes inside a `NavStack`, `TabNavigator`,
+     * full-screen dialog, or `Workbench`.
+     */
+    compactChrome?: PaneCompactChromePolicy;
+    /**
+     * Which `overlay` compact chrome is showing. The app owns it and flips it
+     * from a control the person can reach while the chrome is hidden.
+     */
+    compactChromeOpen?: {
+        header?: boolean;
+        footer?: boolean;
+    };
+    headerPresentation?: PaneHeaderPresentation;
+    /**
+     * With `headerPresentation="clear"`, `material` fades the chrome material
+     * in behind the header once content scrolls beneath it (default `none`).
+     */
+    scrollEdge?: ScrollEdge;
+    /**
+     * The scroll distance, in CSS pixels, over which the scroll edge fades in
+     * (default 60).
+     */
+    scrollEdgeDistance?: number;
+    /** Paint the scrolling work surface with the shared lowered-surface color. */
+    appearance?: PaneAppearance;
+    /**
+     * Paint the whole pane, header and footer included, in an app-chosen color
+     * (`uiColor('surface-raised')`, `fillColor('#1f2a44')`, or `colorVar(…)`
+     * from `@kerfjs/ui/css-values`). It replaces the appearance's fill: a sunken
+     * pane drops its lowered color and grain. Omitted, the pane keeps its
+     * default (transparent, or the sunken surface). Forced colors paint
+     * `Canvas`. Keep text at AA over the color; a dark color needs a matching
+     * tint or dark tones for its content.
+     */
+    background?: CssColor;
+    /**
+     * A scoped tint: `{ color, scheme }`, the app's color and the scheme it
+     * belongs to. The pane paints the tinted surface (unless `background` is
+     * set) and its whole subtree, chrome material and quiet fills included,
+     * re-derives its surface and text tokens from the color with lightness
+     * clamped to keep text at WCAG AA. Without relative color syntax, or under
+     * `prefers-contrast: more`, the scope keeps the plain palette in the
+     * declared scheme.
+     */
+    tint?: SurfaceTint;
+    /**
+     * Clear chrome that lies over the scrolling content's block-start and/or
+     * block-end edge, such as a `DialogSurface` floating footer over a filling
+     * Pane. The content scroller adds the inherited
+     * `--kui-scroll-clearance-block-*` context that chrome publishes to its block
+     * padding and `scroll-padding`, so content scrolls visibly beneath the chrome
+     * while its first and last items (and anything focused or scrolled into
+     * view) can still rest clear of it. Defaults to none.
+     */
+    scrollClearance?: ScrollClearance;
+    /** Add 8px to every side of scrolling content (default: false). */
+    deepInset?: boolean;
+    /** Opt into keyboard (`0`) or programmatic (`-1`) focus on the Pane root. */
+    tabIndex?: 0 | -1;
+    /** Keep the standard focus outline visible, such as for a drop target. */
+    outlined?: boolean;
+    /** Root semantics. Defaults to `div`. */
+    element?: PaneElement;
+    /** Scrolling content semantics. Defaults to `div`. */
+    contentElement?: PaneContentElement;
+    /** Independent logical-edge separator lines. Defaults to none. */
+    separators?: readonly PaneSeparatorSide[];
+    /**
+     * Sides on which the pane may compensate for a device safe-area inset.
+     * Defaults to every side: the pane pads its slots for each side that still
+     * reaches an unsafe screen edge, as its surrounding layout reports, while its
+     * background and separators paint through. List only the sides an app-owned
+     * layout places at a screen edge, or pass `[]` to opt out.
+     */
+    safeAreaEdges?: readonly PaneSeparatorSide[];
+    id?: string;
+    /** Accessible name for a landmark root such as `aside` or `main`. */
+    label?: string;
+    /** Accessible name for a landmark scrolling slot such as `nav`. */
+    contentLabel?: string;
+    className?: string;
+    headerClassName?: string;
+    contentClassName?: string;
+    footerClassName?: string;
+    /** Safe `data-*` metadata; Pane-owned structural attributes remain protected. */
+    rootAttributes?: PaneRootAttributes;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
+}
+/**
+ * A pane's configuration, apart from its content and styling hooks: the props a
+ * composite that renders a `Pane` for the app (a Workbench panel or work area,
+ * or a CollapsiblePanel) forwards, so the app configures that pane instead of
+ * styling it. An omitted or `undefined` field keeps the composite's default.
+ */
+type PaneConfig = Pick<PaneProps, 'contentElement' | 'contentLabel' | 'separators' | 'safeAreaEdges' | 'chromeDividers' | 'compactChrome' | 'compactChromeOpen' | 'headerPresentation' | 'scrollEdge' | 'scrollEdgeDistance' | 'appearance' | 'background' | 'tint' | 'deepInset' | 'scrollClearance' | 'tabIndex' | 'outlined'>;
+/**
+ * An unpadded application column with optional fixed header/footer slots and one
+ * scrolling vertical content owner. Separator lines are independently opt-in on
+ * each logical edge, so the same component works as a sidebar, main area,
+ * inspector, or dialog column.
+ */
+declare function Pane({ header, children, footer, chromePlacement, chromeDividers, compactChrome, compactChromeOpen, headerPresentation, scrollEdge, scrollEdgeDistance, appearance, background, tint, deepInset, scrollClearance, tabIndex, outlined, element, contentElement, separators, safeAreaEdges, id, label, contentLabel, className, headerClassName, contentClassName, footerClassName, rootAttributes, slot, }: PaneProps): kerfjs.SafeHtml;
+
+export { Pane, type PaneAppearance, type PaneChromeDividers, type PaneChromePlacement, type PaneCompactChrome, type PaneCompactChromePolicy, type PaneConfig, type PaneContentElement, type PaneElement, type PaneHeaderPresentation, type PaneProps, type PaneSeparatorSide, ScrollClearance, type ScrollEdge, type SurfaceTint, type SurfaceTintScheme };

package/dist/pane.js

@@ -0,0 +1,6 @@
+export { Pane } from './chunk-HQZG3OFL.js';
+
+
+
+
+//# sourceMappingURL=pane.js.map

package/dist/pane.js.map

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

package/dist/panel-toolbar-vg6Ir5Dy.d.ts

@@ -0,0 +1,77 @@
+import { ToolbarConfig } from './toolbar.js';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import { LucideIcon } from './lucide-icon.js';
+
+/** Which edge a collapsible panel docks to. */
+type PanelSide = 'left' | 'right' | 'bottom';
+/**
+ * The standard collapse/expand icon for a panel `side` and `collapsed` state,
+ * so every app's sidebars and drawers use one recognizable convention:
+ * `PanelLeft*` for a left rail, `PanelRight*` for a right rail, `PanelBottom*`
+ * for a bottom drawer — the `Close` glyph while open, the `Open` glyph while
+ * collapsed. Exposed so an app can render its own toggle affordance.
+ */
+declare function collapsiblePanelToggleIcon(side: PanelSide, collapsed: boolean): {
+    icon: Parameters<typeof LucideIcon>[0]['icon'];
+    name: string;
+};
+/**
+ * The standard collapse toggle a panel toolbar renders. The app handles the
+ * button's `data-action` and flips its own `collapsed` flag.
+ */
+interface PanelToggle {
+    /** The `data-action` the toggle button carries. */
+    action: string;
+    /**
+     * The panel's short title-style name ("Navigator", "Build Output"). It is
+     * the toggle group's accessible name and completes the default "Show …" /
+     * "Hide …" label ("Show Navigator"), so it follows the title-style rule in
+     * `docs/writing.md`; it is never recapitalized.
+     */
+    name: string;
+    /** Accessible label while the panel is collapsed. Defaults to `Show {name}`. */
+    showLabel?: string;
+    /** Accessible label while the panel is open. Defaults to `Hide {name}`. */
+    hideLabel?: string;
+}
+/**
+ * A collapsible panel's top toolbar, composed so its groups follow the
+ * panel's open state.
+ *
+ * - `title` precedes the `leading` zone. Groups may appear in any of the
+ *   `leading`, `center`, and `trailing` zones while the panel is open.
+ * - Groups marked `relocateOnCollapse` move to the work area's toolbar while
+ *   the panel is collapsed, preserving their order across the three zones.
+ * - `toggle` is always the last group: in the panel's toolbar while it is
+ *   open, and right after the relocated groups in the work area's toolbar
+ *   while it is collapsed.
+ *
+ * Relocated content renders in both places while the panel is collapsed (the
+ * panel's copy is inert), so give it no `id`s. Pass groups directly or in
+ * arrays so their render-time annotation remains available to the panel.
+ *
+ * The toolbar's configuration (`dividerSides`, `centerAlign`, `responsive`,
+ * `responsiveAt`, `safeAreaEdges`) forwards to its `Toolbar`. It draws no
+ * divider of its own: the panel's `Pane` draws the line under it while the
+ * content is scrolled (its `chromeDividers`, wired by `wireScrollDividers`).
+ */
+interface PanelToolbar extends ToolbarConfig {
+    /** Accessible name of the panel's toolbar. */
+    label: string;
+    title?: KerfUiContent;
+    leading?: KerfUiContent;
+    center?: KerfUiContent;
+    trailing?: KerfUiContent;
+    toggle?: PanelToggle;
+}
+/** A panel's fixed bottom toolbar, below its optional footer content. */
+interface PanelBottomToolbar extends ToolbarConfig {
+    label: string;
+    leading?: KerfUiContent;
+    center?: KerfUiContent;
+    trailing?: KerfUiContent;
+}
+/** Whether panel chrome stays fixed, scrolls, or follows Pane's auto rule. */
+type PanelChromePlacement = 'fixed' | 'scroll' | 'auto';
+
+export { type PanelSide as P, type PanelToolbar as a, type PanelChromePlacement as b, type PanelBottomToolbar as c, type PanelToggle as d, collapsiblePanelToggleIcon as e };

package/dist/popup-menu-register.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Marker export for tests and tooling; importing this module wires every
+ * `PopupMenu` in the document: opening from its trigger and from
+ * `openPopupMenu` / `openPopupMenuAt` / `closePopupMenu`, top-layer placement,
+ * keyboard navigation and typeahead, hover-opened submenus, the `kui-menu-select`
+ * choice event, and focus return. It also registers the help tag an
+ * icon-only trigger shows on hover or keyboard focus.
+ */
+declare const popupMenuElementsRegistered = true;
+
+export { popupMenuElementsRegistered };

package/dist/popup-menu-register.js

@@ -0,0 +1,13 @@
+import { installPopupMenus } from './chunk-EYDXFOSH.js';
+import { installHelpTags } from './chunk-2LM3PYHA.js';
+
+
+
+// src/components/actions/popup-menu/register/popup-menu-register.ts
+installPopupMenus();
+installHelpTags();
+var popupMenuElementsRegistered = true;
+
+export { popupMenuElementsRegistered };
+
+//# sourceMappingURL=popup-menu-register.js.map

package/dist/popup-menu-register.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/components/actions/popup-menu/register/popup-menu-register.ts"],"names":[],"mappings":";;;;;;AAGA,iBAAA,EAAkB;AAClB,eAAA,EAAgB;AAUT,IAAM,2BAAA,GAA8B","file":"popup-menu-register.js","sourcesContent":["import { installHelpTags } from '../../../../wiring/help-tags.js';\nimport { installPopupMenus } from '../internal/popup-menu-controller.js';\n\ninstallPopupMenus();\ninstallHelpTags();\n\n/**\n * Marker export for tests and tooling; importing this module wires every\n * `PopupMenu` in the document: opening from its trigger and from\n * `openPopupMenu` / `openPopupMenuAt` / `closePopupMenu`, top-layer placement,\n * keyboard navigation and typeahead, hover-opened submenus, the `kui-menu-select`\n * choice event, and focus return. It also registers the help tag an\n * icon-only trigger shows on hover or keyboard focus.\n */\nexport const popupMenuElementsRegistered = true;\n"]}

package/dist/popup-menu.d.ts

@@ -0,0 +1,153 @@
+import { SafeHtml } from 'kerfjs';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+
+type PopupMenuPlacement = 'bottom-start' | 'bottom' | 'bottom-end' | 'top-start' | 'top' | 'top-end';
+type PopupMenuDataAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
+    'data-action'?: never;
+    'data-component'?: never;
+    'data-key'?: never;
+    'data-morph-skip-children'?: never;
+}>;
+/** One command in the menu. */
+interface PopupMenuItem {
+    kind?: 'item';
+    label: string;
+    /** Delegated `data-action` the app handles when the item is chosen. */
+    action?: string;
+    /** The item's value, reported in the menu's `kui-menu-select` event. */
+    value?: string;
+    /** Leading icon, typically a `LucideIcon`, before the label. */
+    icon?: SafeHtml;
+    /** A checkbox choice, including nested choices; omit for a plain command. */
+    checked?: boolean;
+    /** Trailing safe content, such as secondary status. */
+    details?: SafeHtml;
+    /** Destructive command styling. */
+    tone?: 'default' | 'danger';
+    disabled?: boolean;
+    /** Native tooltip text for a disabled command. */
+    disabledReason?: string;
+    /** Application `data-*` metadata such as a record id. */
+    attributes?: PopupMenuDataAttributes;
+    /** Child commands, headings, and dividers opened by hover or keyboard navigation. */
+    submenu?: readonly PopupMenuEntry[];
+}
+/** A labeled group heading; items that follow it belong to the group. */
+interface PopupMenuHeading {
+    kind: 'heading';
+    label: string;
+}
+/** A separator between groups of items. */
+interface PopupMenuDivider {
+    kind: 'divider';
+}
+type PopupMenuEntry = PopupMenuItem | PopupMenuHeading | PopupMenuDivider;
+type PopupMenuTriggerName = {
+    /** Visible trigger text, which is also its accessible name. */
+    text: string;
+    label?: never;
+    triggerContent?: never;
+} | {
+    text?: never;
+    /**
+     * Accessible name of an icon-only trigger, rendered as visually hidden
+     * text inside the trigger button.
+     */
+    label: string;
+    triggerContent?: never;
+} | {
+    text?: never;
+    /**
+     * The trigger's accessible name ("Status: Started"); the visible
+     * content is hidden from assistive technology.
+     */
+    label: string;
+    /**
+     * Visible content that is the whole trigger, such as a `Badge` showing
+     * the current status. Kerf owns the bare button around it (no chrome,
+     * a pill focus ring, the pointer cursor, `aria-haspopup`), and the
+     * caret is off unless `caret` is set.
+     */
+    triggerContent: KerfUiContent;
+    icon?: never;
+};
+/** A context PopupMenu's viewport anchor point. */
+interface PopupMenuAnchor {
+    x: number;
+    y: number;
+}
+type PopupMenuTrigger = (PopupMenuTriggerName & {
+    context?: false;
+    anchor?: never;
+}) | {
+    context: true;
+    label: string;
+    triggerContent?: never;
+    /**
+     * The viewport point (CSS pixels, as in `MouseEvent.clientX/Y`) the
+     * menu opens from. Rendered into the menu itself, so it survives
+     * re-renders and replacement; open it with `openPopupMenu`.
+     */
+    anchor?: PopupMenuAnchor;
+    text?: never;
+    icon?: never;
+    caret?: never;
+    disabled?: never;
+};
+type PopupMenuProps = PopupMenuTrigger & {
+    /** Trigger icon, typically a `LucideIcon`, before any visible text. */
+    icon?: KerfUiContent;
+    items: readonly PopupMenuEntry[];
+    /**
+     * Where the menu opens relative to its trigger, or to its anchor point for
+     * a `context` menu (`top-start` opens above the point). Defaults to
+     * `bottom-start`.
+     */
+    placement?: PopupMenuPlacement;
+    /** Show the disclosure caret after the trigger content. Defaults to true. */
+    caret?: boolean;
+    disabled?: boolean;
+    /** Application `data-*` metadata on the menu root. */
+    rootAttributes?: PopupMenuDataAttributes;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
+};
+/** A rendered PopupMenu root, the element the open and close helpers take. */
+type PopupMenuElement = HTMLElement;
+/**
+ * Open a PopupMenu at viewport pointer coordinates. A `context` menu rendered
+ * without `anchor` moves its invisible anchor there and opens at its
+ * `placement` (a menu rendered with `anchor` opens with `openPopupMenu`
+ * instead). A button-triggered menu (such
+ * as a `ListActionRow` trailing menu) opens `bottom-start` from the point,
+ * like a context menu, for this opening only; its next opening returns to its
+ * trigger and placement. `options.placement` sets the placement at the point
+ * for this opening instead (`top-start` sits above it, say), for either kind
+ * of menu; flipping, shifting, and the height cap still apply. Needs the
+ * `/register` entry.
+ */
+declare function openPopupMenuAt(menu: PopupMenuElement, x: number, y: number, options?: {
+    placement?: PopupMenuPlacement;
+}): void;
+/**
+ * Open a PopupMenu from its trigger, or a context PopupMenu at the `anchor`
+ * it was rendered with (or the point a previous `openPopupMenuAt` set).
+ * Needs the `/register` entry.
+ */
+declare function openPopupMenu(menu: PopupMenuElement): void;
+/** Close an open PopupMenu, and any submenu it shows. */
+declare function closePopupMenu(menu: PopupMenuElement): void;
+/**
+ * An action menu: a trigger button that opens a list of commands in the top
+ * layer. A `single` `ToolbarControlGroup` (with `nestedDropdown`) or a
+ * `PopupSurface` sizes and insets it as usual. Items dispatch through
+ * delegated `data-action`s, and the root reports each choice as a bubbling
+ * `kui-menu-select` event; the app owns the commands and any open-state reaction.
+ * Import `@kerfjs/ui/popup-menu/register` once to wire opening, keyboard
+ * navigation, submenus, and dismissal. At viewport widths up to 480px,
+ * submenus appear above or below their parent menu so their rows do not cover
+ * the parent list.
+ */
+declare function PopupMenu({ text, label, icon, triggerContent, items, placement, caret, disabled, rootAttributes, slot, context, anchor, }: PopupMenuProps): SafeHtml;
+
+export { PopupMenu, type PopupMenuAnchor, type PopupMenuDivider, type PopupMenuElement, type PopupMenuEntry, type PopupMenuHeading, type PopupMenuItem, type PopupMenuPlacement, type PopupMenuProps, closePopupMenu, openPopupMenu, openPopupMenuAt };

package/dist/popup-menu.js

@@ -0,0 +1,7 @@
+export { PopupMenu, closePopupMenu, openPopupMenu, openPopupMenuAt } from './chunk-OQP3PFKQ.js';
+
+
+
+
+
+//# sourceMappingURL=popup-menu.js.map

package/dist/popup-menu.js.map

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

package/dist/progress-bar.d.ts

@@ -0,0 +1,52 @@
+import * as kerfjs from 'kerfjs';
+
+/** The fill color: `brand` (default), or a status tone. */
+type ProgressTone = 'brand' | 'success' | 'warning' | 'danger';
+/** `default` is a 6px track; `compact` is 4px, for a row or table cell. */
+type ProgressBarSize = 'default' | 'compact';
+/**
+ * Application `data-*` identity on the ProgressBar root, such as `data-key`;
+ * its own configuration attributes stay protected.
+ */
+type ProgressBarRootAttributes = Readonly<Record<`data-${string}`, string | undefined>>;
+type ProgressBarProps = {
+    /**
+     * Work done so far, from 0 to `max`. Omit it for indeterminate progress
+     * (work whose size is unknown), which animates instead.
+     */
+    value?: number;
+    /** The amount that means done (default 1). */
+    max?: number;
+    /**
+     * Spoken progress in place of the percentage, such as "3 of 12 files". With
+     * `showValue` it is also the visible text.
+     */
+    valueText?: string;
+    /** Show the value (or `valueText`) at the end of the label row. */
+    showValue?: boolean;
+    tone?: ProgressTone;
+    size?: ProgressBarSize;
+    id?: string;
+    rootAttributes?: ProgressBarRootAttributes;
+    className?: string;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
+} & ({
+    /** A visible label above the bar that also names it. */
+    label: string;
+    ariaLabel?: never;
+} | {
+    label?: never;
+    /** The bar's accessible name when it shows no visible label. */
+    ariaLabel: string;
+});
+/**
+ * A linear progress indicator on the native `<progress>` element: determinate
+ * (`value` of `max`) or indeterminate (no `value`, an animated sweep), named
+ * by a visible `label` or an `ariaLabel`, toned, and in two track sizes. The
+ * native element carries the progressbar role and its value to assistive
+ * technology; `valueText` replaces the spoken percentage.
+ */
+declare function ProgressBar({ value, max, valueText, showValue, label, ariaLabel, tone, size, id, rootAttributes, className, slot, }: ProgressBarProps): kerfjs.SafeHtml;
+
+export { ProgressBar, type ProgressBarProps, type ProgressBarRootAttributes, type ProgressBarSize, type ProgressTone };

package/dist/progress-bar.js

@@ -0,0 +1,68 @@
+import { filterDataAttributes } from './chunk-KH4KEMSP.js';
+import { jsxs, jsx } from 'kerfjs/jsx-runtime';
+
+var PROGRESS_BAR_PROTECTED = /* @__PURE__ */ new Set([
+  "data-component",
+  "data-tone",
+  "data-size",
+  "data-indeterminate"
+]);
+function percent(value, max) {
+  return `${Math.round(value / max * 100)}%`;
+}
+function ProgressBar({
+  value,
+  max = 1,
+  valueText,
+  showValue = false,
+  label,
+  ariaLabel,
+  tone = "brand",
+  size = "default",
+  id,
+  rootAttributes = {},
+  className = "",
+  slot
+}) {
+  if (!Number.isFinite(max) || max <= 0)
+    throw new RangeError("ProgressBar max must be a positive number.");
+  if (value !== void 0 && (!Number.isFinite(value) || value < 0))
+    throw new RangeError("ProgressBar value must be zero or more.");
+  const clamped = value === void 0 ? void 0 : Math.min(value, max);
+  const labelId = id === void 0 ? void 0 : `${id}-label`;
+  const shownValue = showValue && (valueText ?? (clamped === void 0 ? void 0 : percent(clamped, max)));
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      ...filterDataAttributes(rootAttributes, PROGRESS_BAR_PROTECTED),
+      id,
+      class: `kui-progress-bar ${className}`.trim(),
+      "data-component": "progress-bar",
+      "data-tone": tone,
+      "data-size": size,
+      "data-indeterminate": clamped === void 0 ? "" : void 0,
+      slot,
+      children: [
+        label === void 0 && !shownValue ? null : /* @__PURE__ */ jsxs("div", { class: "kui-progress-bar__header", children: [
+          label === void 0 ? null : /* @__PURE__ */ jsx("span", { class: "kui-progress-bar__label", id: labelId, children: label }),
+          shownValue ? /* @__PURE__ */ jsx("span", { class: "kui-progress-bar__value", "aria-hidden": "true", children: shownValue }) : null
+        ] }),
+        /* @__PURE__ */ jsx(
+          "progress",
+          {
+            class: "kui-progress-bar__track",
+            value: clamped,
+            max,
+            "aria-label": labelId === void 0 ? label ?? ariaLabel : void 0,
+            "aria-labelledby": labelId,
+            "aria-valuetext": valueText
+          }
+        )
+      ]
+    }
+  );
+}
+
+export { ProgressBar };
+
+//# sourceMappingURL=progress-bar.js.map