@qilin-agent/client-ui-primitives 0.0.0-stage → 3.1.3

package/lib/types/Checkbox.d.ts

@@ -0,0 +1,20 @@
+/** Controlled native checkbox with a caller-owned visible and accessible label. */
+/**
+ * Render a labeled checkbox with native keyboard and form semantics.
+ * @param props.checked - current checked state.
+ * @param props.onChange - receives the requested checked state.
+ * @param props.label - localized visible and accessible label.
+ * @param props.disabled - whether the control refuses changes.
+ * @param props.title - optional localized hover text.
+ * @param props.className - extra class for the label's placement.
+ * @returns the label containing its checkbox.
+ */
+export declare function Checkbox({ checked, onChange, label, disabled, title, className }: {
+    checked: boolean;
+    onChange: (next: boolean) => void;
+    label: string;
+    disabled?: boolean;
+    title?: string | undefined;
+    className?: string | undefined;
+}): import("react").JSX.Element;
+//# sourceMappingURL=Checkbox.d.ts.map

package/lib/types/CodeFileIcon.d.ts

@@ -0,0 +1,12 @@
+import type { ReactNode } from 'react';
+import type { IconProps } from './icons/props.ts';
+import type { CodeFileType } from './code-file-types.ts';
+/**
+ * Render one full-color square code-file glyph from the embedded icon set.
+ * @param props - Detailed code type, optional size, and optional CSS class.
+ * @returns The selected decorative SVG with its identifying palette intact.
+ */
+export declare function CodeFileIcon({ type, size, className }: IconProps & {
+    readonly type: CodeFileType;
+}): ReactNode;
+//# sourceMappingURL=CodeFileIcon.d.ts.map

package/lib/types/ConnectionIndicator.d.ts

@@ -0,0 +1,26 @@
+/** Visual state rendered by {@link ConnectionIndicator}. */
+export type ConnectionIndicatorState = 'disconnected' | 'connecting' | 'recovered';
+/**
+ * Render an inline connection-recovery control. The outage and retry-attempt
+ * states are one button whose static label already names the retry action;
+ * clicking it requests an immediate reconnect. The indicator animates in on
+ * appearance and fades out for {@link EXIT_MS} before unmounting.
+ * @param props.state - visible outage, retry-attempt, or recovered state.
+ * @param props.disconnectedLabel - localized outage text naming the retry action.
+ * @param props.connectingLabel - localized retry text followed by the attempt dots.
+ * @param props.recoveredLabel - localized recovery confirmation.
+ * @param props.reconnectActionLabel - accessible label for the outage action.
+ * @param props.restartActionLabel - accessible label for replacing an active attempt.
+ * @param props.onReconnect - request an immediate reconnect attempt.
+ * @returns the indicator, or null when no connection feedback is active.
+ */
+export declare function ConnectionIndicator({ state, disconnectedLabel, connectingLabel, recoveredLabel, reconnectActionLabel, restartActionLabel, onReconnect, }: {
+    state: ConnectionIndicatorState | undefined;
+    disconnectedLabel: string;
+    connectingLabel: string;
+    recoveredLabel: string;
+    reconnectActionLabel: string;
+    restartActionLabel: string;
+    onReconnect: () => void;
+}): import("react").JSX.Element | null;
+//# sourceMappingURL=ConnectionIndicator.d.ts.map

package/lib/types/DiffBlock.d.ts

@@ -0,0 +1,52 @@
+/** Output lines shown before the height cap collapses the middle. */
+export declare const DEFAULT_DIFF_MAX_LINES = 16;
+/**
+ * One file change in the form {@link DiffBlock} renders. It is declared here
+ * so this primitive stays independent of the tool contract.
+ */
+export interface DiffHunk {
+    /** The changed file's path, drawn verbatim as the hunk's header (the tool's model-facing path). */
+    path: string;
+    /** Prior content including context, or `null` when no prior content is available. */
+    oldText: string | null;
+    /** Content after the change, including any shared context. */
+    newText: string;
+}
+export interface DiffBlockProps {
+    /** One entry per applied hunk, in file order; empty renders nothing. */
+    diffs: DiffHunk[];
+    /** Localized chrome supplied by the owning render site. */
+    labels: DiffBlockLabels;
+    /** Height cap in body lines before the middle collapses (default {@link DEFAULT_DIFF_MAX_LINES}). */
+    maxLines?: number | undefined;
+    /** Extra class merged onto the wrapper (callers position; this component draws). */
+    className?: string | undefined;
+}
+/** Localized chrome for {@link DiffBlock}. */
+export interface DiffBlockLabels {
+    copy: string;
+    copied: string;
+    collapseAria: string;
+    expandAria: (hidden: number) => string;
+    collapse: string;
+    expand: (hidden: number) => string;
+    files: (count: number) => string;
+}
+/**
+ * Count displayed additions and deletions. Exact patches exclude shared context;
+ * comparisons exceeding the edit limit count both complete fragments as replaced.
+ * Text follows {@link contentLines}'s terminator rule.
+ * @param diffs - the hunks to count.
+ * @returns the +/- totals for summaries and the card footer.
+ */
+export declare function diffTotals(diffs: DiffHunk[]): {
+    added: number;
+    removed: number;
+};
+/**
+ * Render a file mutation as an inline diff surface.
+ * @param props - see {@link DiffBlockProps}.
+ * @returns the diff block element.
+ */
+export declare function DiffBlock({ diffs, labels, maxLines, className }: DiffBlockProps): import("react").JSX.Element | null;
+//# sourceMappingURL=DiffBlock.d.ts.map

package/lib/types/DisclosureRow.d.ts

@@ -0,0 +1,36 @@
+import { type ReactNode } from 'react';
+/** Shared 24px disclosure chrome for compact flow rows. */
+export interface DisclosureRowProps {
+    icon: ReactNode;
+    title: string;
+    open: boolean;
+    expandable: boolean;
+    onToggle: () => void;
+    /** Animate the complete header while its owning operation is running. */
+    running?: boolean | undefined;
+    /** Makes the complete title row the disclosure target. */
+    expandOnRowClick?: boolean | undefined;
+    /** Replaces the collapsed icon with a chevron while the row is hovered. */
+    previewChevron?: boolean | undefined;
+    /** Keeps `collapsedContent` inline while open. */
+    keepContentWhenOpen?: boolean | undefined;
+    collapsedContent?: ReactNode;
+    children?: ReactNode;
+    className?: string | undefined;
+    rowClassName?: string | undefined;
+    /** Sizing class for the header text area, beside the leading icon. */
+    contentClassName?: string | undefined;
+    /** Layout class shared by the header text and its decorative copy. */
+    contentLayoutClassName?: string | undefined;
+    leadingClassName?: string | undefined;
+    chevronClassName?: string | undefined;
+    titleClassName?: string | undefined;
+}
+/**
+ * Render one disclosure header and its controlled expanded content.
+ * Shallow prop comparison requires stable callbacks and React nodes to skip unchanged renders.
+ * @param props - Visual content, controlled state, and interaction policy.
+ * @returns the disclosure row.
+ */
+export declare const DisclosureRow: import("react").MemoExoticComponent<({ icon, title, open, expandable, onToggle, running, expandOnRowClick, previewChevron, keepContentWhenOpen, collapsedContent, children, className, rowClassName, contentClassName, contentLayoutClassName, leadingClassName, chevronClassName, titleClassName, }: DisclosureRowProps) => import("react").JSX.Element>;
+//# sourceMappingURL=DisclosureRow.d.ts.map

package/lib/types/FileTypeIcon.d.ts

@@ -0,0 +1,43 @@
+import type { ReactNode } from 'react';
+import { type CodeFileType, type FileTypeProjectContext } from './code-file-types.ts';
+import type { IconProps } from './icons/props.ts';
+/** File categories with distinct 28px glyphs. */
+export type FileType = CodeFileType | 'code' | 'excel' | 'folder' | 'html' | 'image' | 'markdown' | 'other' | 'pdf' | 'ppt' | 'video' | 'word';
+/** Compatibility name for consumers that pass an already resolved category. */
+export type FileTypeKind = FileType;
+type ClassifiedFileType = Exclude<FileType, 'folder'>;
+export type { CodeFileType, FileTypeProjectContext } from './code-file-types.ts';
+/** Props for {@link FileTypeIcon}: either a path to classify or an already resolved kind. */
+export type FileTypeIconProps = IconProps & ({
+    /** File path or name to classify. */
+    readonly path: string;
+    /** Optional project-file snapshot for context-sensitive code icons such as Flutter. */
+    readonly context?: FileTypeProjectContext | undefined;
+} | {
+    /** Explicit category for callers that already resolved the file type. */
+    readonly kind: FileTypeKind;
+});
+/**
+ * Extract the final suffix from a file path without changing its case.
+ * A leading dot starts a suffix, while a missing or trailing dot returns an empty string.
+ * @param path - File path or basename using either path separator.
+ * @returns The characters after the basename's final dot.
+ */
+export declare function fileExtension(path: string): string;
+/**
+ * Classify a file path or name for file-card presentation.
+ * Matching is case-insensitive and applies code filename rules before extension rules;
+ * unknown names fall back to `other`.
+ * @param path - File path or basename using either path separator.
+ * @param context - Optional project files used by context-sensitive code mappings.
+ * @returns The file's closed presentation category.
+ */
+export declare function classifyFileType(path: string, context?: FileTypeProjectContext): ClassifiedFileType;
+/**
+ * Render a decorative file-type glyph for a path or an explicitly resolved kind.
+ * @param props - Path or kind selection, optional project context, size, and CSS class.
+ * @returns The category-colored SVG; the caller owns the accessible name and may override
+ * the color through `--qilin-file-type-icon-color`.
+ */
+export declare function FileTypeIcon(props: FileTypeIconProps): ReactNode;
+//# sourceMappingURL=FileTypeIcon.d.ts.map

package/lib/types/FoldToggle.d.ts

@@ -0,0 +1,20 @@
+interface FoldToggleProps {
+    className: string | undefined;
+    expanded: boolean;
+    hidden: number;
+    labels: {
+        collapseAria: string;
+        expandAria: (hidden: number) => string;
+        collapse: string;
+        expand: (hidden: number) => string;
+    };
+    onToggle: () => void;
+}
+/**
+ * Render the shared head-tail fold control with caller-owned localized copy.
+ * @param props - Fold state, localized labels, and toggle callback.
+ * @returns The accessible expand or collapse button.
+ */
+export declare function FoldToggle({ className, expanded, hidden, labels, onToggle, }: FoldToggleProps): import("react").JSX.Element;
+export {};
+//# sourceMappingURL=FoldToggle.d.ts.map

package/lib/types/HoverCard.d.ts

@@ -0,0 +1,32 @@
+import type { ReactNode } from 'react';
+/**
+ * Render an anchor with a hover-triggered preview card, hidden while a tooltip within the anchor is visible.
+ * @param props.anchor - the hover target (rendered in place inside a wrapper span).
+ * @param props.content - card content; the pointer may rest on it, so it is
+ * readable and selectable, but it carries no dismissal affordance of its own.
+ * @param props.openDelayMs - hover dwell before the card shows (default 500).
+ * @param props.inline - keep the anchor in prose; show a contained preview on hover or keyboard focus.
+ * @param props.disabled - suppress opening; turning true closes an open card.
+ * @param props.copyText - optional primary value copied by activation and
+ * included in the card's accessible name.
+ * @param props.copyLabel - localized accessible activation-label prefix.
+ * @param props.copiedLabel - localized visible success label.
+ * @returns anchor wrapper with the conditional portaled card.
+ */
+export declare function HoverCard({ anchor, content, openDelayMs, disabled, copyText, copyLabel, copiedLabel, inline, }: {
+    anchor: ReactNode;
+    /** Inline media preview using the shared menu material and keyboard focus. */
+    inline?: boolean;
+    content: ReactNode;
+    openDelayMs?: number;
+    disabled?: boolean;
+} & ({
+    copyText?: string | undefined;
+    copyLabel: string;
+    copiedLabel: string;
+} | {
+    copyText?: undefined;
+    copyLabel?: string;
+    copiedLabel?: string;
+})): import("react").JSX.Element;
+//# sourceMappingURL=HoverCard.d.ts.map

package/lib/types/ImageLightbox.d.ts

@@ -0,0 +1,27 @@
+/** Lightbox strings the owner resolves from its own locale namespace. */
+export interface ImageLightboxLabels {
+    /** Accessible name of the preview dialog. */
+    dialog: string;
+    /** Accessible label of the close control. */
+    close: string;
+}
+/**
+ * Document-level original-image preview opened by clicking a thumbnail.
+ * Closes on Escape, backdrop press, or the close control, and restores focus
+ * to the opener on unmount. Rendered through a body portal: an opener inside
+ * a transformed or filtered ancestor would otherwise trap the fixed backdrop
+ * in that ancestor's box instead of covering the viewport.
+ *
+ * @param props.src - the original image URL.
+ * @param props.alt - the image's alt text.
+ * @param props.labels - dialog and close-control strings.
+ * @param props.onClose - dismiss callback owned by the opener.
+ * @returns the modal preview dialog.
+ */
+export declare function ImageLightbox({ src, alt, labels, onClose }: {
+    src: string;
+    alt: string;
+    labels: ImageLightboxLabels;
+    onClose: () => void;
+}): import("react").ReactPortal;
+//# sourceMappingURL=ImageLightbox.d.ts.map

package/lib/types/ImagePreview.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Render an image without introducing a second activation target.
+ * @param props - Source, accessible description, localized status.
+ * @returns A contained preview with loading or failure status.
+ */
+export declare function ImagePreview({ src, alt, loadingLabel, failedLabel }: {
+    src: string;
+    alt: string;
+    loadingLabel: string;
+    failedLabel: string;
+}): import("react").JSX.Element;
+//# sourceMappingURL=ImagePreview.d.ts.map

package/lib/types/Input.d.ts

@@ -0,0 +1,12 @@
+import { type InputHTMLAttributes, type ReactNode } from 'react';
+/**
+ * Render a text input with an optional leading icon.
+ * @param props.icon - optional 16px leading icon node.
+ * @param ref - the native input, cleared when it unmounts.
+ * @returns wrapper span containing the native input; input attributes pass through.
+ */
+export declare const Input: import("react").ForwardRefExoticComponent<{
+    icon?: ReactNode;
+    className?: string | undefined;
+} & InputHTMLAttributes<HTMLInputElement> & import("react").RefAttributes<HTMLInputElement>>;
+//# sourceMappingURL=Input.d.ts.map

package/lib/types/JsonTree.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Display copy for the tree's copy affordance; the owner passes localized
+ * labels (this package is cordis-free, so copy arrives via props).
+ */
+export interface JsonTreeLabels {
+    /** Menu item: copy the raw primitive value. */
+    copyValue: string;
+    /** Menu item: copy the value as compact JSON (primitive rows). */
+    copyJson: string;
+    /** Menu item: copy the property path. */
+    copyPath: string;
+    /** Menu item: copy the value as pretty-printed JSON. */
+    copyPrettyJson: string;
+    /** Menu item: copy the value as compact JSON (object rows). */
+    copyCompactJson: string;
+    /** Copy-button state label after a successful copy. */
+    copied: string;
+    /** Copy-button state label after a failed copy. */
+    copyFailed: string;
+    /** Expander aria label while expanded. */
+    collapseNode: string;
+    /** Expander aria label while collapsed. */
+    expandNode: string;
+    /** Copy-button tooltip, given the current action label. */
+    copyButtonTitle: (action: string) => string;
+}
+/** Props for the read-only, token-themed JSON tree. */
+export interface JsonTreeProps {
+    /** Parsed JSON object or array. */
+    data: object | unknown[];
+    /** Accessible label for the tree. */
+    label: string;
+    /** Optional positioning class owned by the caller. */
+    className?: string | undefined;
+    /** Maximum visible lines per collapsed string; defaults to 3. */
+    collapsedStringLines?: number;
+    /** Optional wrap toggle; each expansion reads the shared default without changing other open strings. */
+    stringWrapping?: {
+        /** Localized label for the wrapping toggle. */
+        label: string;
+        /** Read the wrapping preference when a string is expanded. @returns Whether to wrap long lines. */
+        getDefault: () => boolean;
+        /** Remember a user toggle for future expansions. @param wrapped - Whether to wrap long lines. */
+        setDefault: (wrapped: boolean) => void;
+    } | undefined;
+    /** Whether JSON rows expose copy actions. */
+    copyable?: boolean;
+    /** Whether the top-level object or array is always expanded. */
+    expandTopLevel?: boolean;
+    /** Localized display copy supplied by the owning render site. */
+    labels: JsonTreeLabels;
+}
+/**
+ * Render parsed JSON as a compact, keyboard-accessible inspector tree.
+ * @param props - Parsed data, accessible label, and display options.
+ * @returns A read-only JSON tree with an optionally fixed-open top level.
+ */
+export declare function JsonTree({ data, label, className, collapsedStringLines, stringWrapping, copyable, expandTopLevel, labels, }: JsonTreeProps): import("react").JSX.Element;
+//# sourceMappingURL=JsonTree.d.ts.map

package/lib/types/LinkIcon.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Leading category glyph for clickable artifact links (anchors, file
+ * mentions, produced-file chips). One component keyed by link category;
+ * every glyph renders fill="currentColor" and so rides the link's own
+ * color. Glyphs stay private to this module: the public surface is the
+ * category vocabulary, not the individual glyph components, so consumers
+ * cannot compose a glyph outside a link. Design sources:
+ * ic_globe_language_outline_20, ic_code_outline_20, ic_folder_outline_20,
+ * ic_photo_outline_20, ic_paper_doc_outline_20, ic_paper_outline_20.
+ *
+ * A `url` glyph whose destination names a well-known site is that site's own
+ * mark instead of the globe (`SiteGlyph.tsx`); every mark keeps the same
+ * currentColor-only rule.
+ */
+import type { ReactNode } from 'react';
+import type { IconProps } from './icons/props.ts';
+/**
+ * Link categories with distinct leading glyphs. `url` and `folder` are
+ * destination categories the consumer states directly; the rest are file
+ * categories `classifyLinkPath` derives from a path. Code, web, and data
+ * files share the `code` glyph by design.
+ */
+export type LinkIconKind = 'url' | 'folder' | 'code' | 'image' | 'document' | 'other';
+/** Props for {@link LinkIcon}: the category plus the shared icon sizing seat. */
+export interface LinkIconProps extends IconProps {
+    kind: LinkIconKind;
+    /**
+     * Destination of a `url` link. A well-known site draws its own mark, so
+     * callers that know the destination should pass it; anything else keeps the
+     * globe. Other kinds ignore it — their destination is a path, not a site.
+     */
+    href?: string | undefined;
+}
+/**
+ * Derive a file path's link-icon category from its extension. Unknown and
+ * missing extensions fall to `other` (the plain-paper glyph).
+ * @param path - File path as the producing tool spelled it (either separator).
+ * @returns The file's glyph category; never `url` or `folder`.
+ */
+export declare function classifyLinkPath(path: string): LinkIconKind;
+/**
+ * Render the leading glyph for one clickable artifact link.
+ * @param props - The link category, the optional destination that can select a
+ * site mark, optional size (default 14px — the inline link text size these
+ * glyphs sit beside), and optional CSS class.
+ * @returns The category's SVG glyph, riding currentColor.
+ */
+export declare function LinkIcon({ kind, href, size, className }: LinkIconProps): ReactNode;
+//# sourceMappingURL=LinkIcon.d.ts.map

package/lib/types/Menu.d.ts

@@ -0,0 +1,133 @@
+import type { ReactNode } from 'react';
+/** Selectable row (optionally with a nested submenu). */
+export interface MenuItem {
+    id: string;
+    label: ReactNode;
+    disabled?: boolean;
+    /** Effective binding supplied by the command owner; omitted for unbound actions. */
+    shortcut?: {
+        keys: readonly string[];
+        aria?: string | undefined;
+    };
+    /** Leading icon (figma .Menu_cell gap 8). */
+    icon?: ReactNode;
+    /** Destructive row: error-colored text/icon and danger hover fill. */
+    danger?: boolean;
+    /** Nested card opened to the right on hover/focus. */
+    submenu?: readonly MenuItem[];
+}
+/** Hairline between item groups (not selectable). */
+export interface MenuSeparator {
+    type: 'separator';
+    id: string;
+}
+/** Non-interactive heading row above a group of items. */
+export interface MenuLabel {
+    type: 'label';
+    id: string;
+    text: string;
+}
+/** One primary-menu entry: a row, a separator, or a heading label. */
+export type MenuEntry = MenuItem | MenuSeparator | MenuLabel;
+/** Props for one component-rendered menu row. */
+export interface MenuItemButtonProps {
+    /** Visible row label. */
+    children: ReactNode;
+    /** Effective binding supplied by the command owner; omitted for unbound actions. */
+    shortcut?: MenuItem['shortcut'];
+    /** Leading icon (figma .Menu_cell gap 8). */
+    icon?: ReactNode;
+    /** Whether the row cannot be activated. */
+    disabled?: boolean;
+    /** Destructive row: error-colored text/icon and danger hover fill. */
+    danger?: boolean;
+    /**
+     * Start a new group: a hairline above this row, the same one a
+     * `{ type: 'separator' }` data entry draws. It comes and goes with the row,
+     * so a row that renders nothing leaves no stray line; a data separator
+     * directly before it draws no second line, and the list's first row draws none.
+     */
+    separatorBefore?: boolean;
+    /** Row activation (click, Enter, or Tab on the focused row). */
+    onSelect: () => void;
+}
+/**
+ * Render one `role="menuitem"` row for a {@link Menu} whose rows are
+ * components rather than `items` data: the same markup and styling as a data
+ * row, so it joins the list's keyboard walk and post-selection focus return
+ * without any shared state. Closing the menu stays the owner's decision, as
+ * it is for data rows.
+ * @param props.children - visible row label.
+ * @param props.shortcut - effective key labels and accessible combination.
+ * @param props.icon - optional leading icon.
+ * @param props.disabled - whether the row cannot be activated.
+ * @param props.danger - whether to use the destructive row colors.
+ * @param props.separatorBefore - whether this row starts a new group (hairline above it).
+ * @param props.onSelect - row activation callback.
+ * @returns one menu-item row.
+ */
+export declare function MenuItemButton({ children, shortcut, icon, disabled, danger, separatorBefore, onSelect, }: MenuItemButtonProps): import("react").JSX.Element;
+/**
+ * Render an anchored dropdown menu. While the list is open its keys mirror the
+ * composer's: Tab settles the focused row — from the trigger, Tab enters the
+ * list instead — and Escape or Shift+Tab close it and return focus to the
+ * anchor's first button, and selecting a row does the same — the rows unmount
+ * with the list. Only a keyboard on the trigger or inside the list is
+ * intercepted; Tab presses elsewhere on the page stay the browser's.
+ * @param props.autoFocus - focus the first item on open; the arrow keys walk the list either way.
+ * @param props.open - whether the list is showing (owner-controlled).
+ * @param props.anchor - the trigger element (rendered in place).
+ * @param props.items - selectable rows and optional separators.
+ * @param props.selectedId - row shown as selected.
+ * @param props.selectedIds - rows shown as selected when a menu contains independent option groups.
+ * @param props.onSelect - row click callback (not called for disabled rows or submenu parents that only open children).
+ * @param props.onClose - invoked on outside click, Escape, or a window blur
+ * that moved focus into an iframe (the only signal a pointerdown inside a
+ * cross-origin iframe leaves).
+ * @param props.align - list alignment against the anchor (default 'start').
+ * @param props.side - open below (`bottom`, default) or above (`top`) the anchor.
+ * @param props.portal - render the list into document.body, fixed-positioned
+ * from the anchor rect (repositions on scroll/resize while open). Use when an
+ * ancestor's overflow clipping would crop the in-place list; default false
+ * keeps the pure-CSS in-place behavior.
+ * @param props.closeOnPointerLeave - close the list once the pointer has left
+ * both trigger and list for the pointer grace (default false keeps it open
+ * until outside click/Escape/selection). The grace makes the 4px trigger->list
+ * gap and a brief overshoot survivable; coming back cancels the close.
+ * @param props.dense - reduce vertical row spacing without changing the standard typography or card width.
+ * @param props.compact - use reduced menu typography and spacing.
+ * @param props.getAnchorRect - portal mode only: supply the anchor rect
+ * directly (e.g. from a host-owned trigger button) instead of measuring the
+ * Menu's own wrapper span. Required when the wrapper isn't itself laid out at
+ * the trigger (render-prop anchors, effect-positioned proxies — measuring the
+ * wrapper there races the host's layout effects). Called on open and on every
+ * scroll/resize; return null to skip placement for that frame.
+ * @param props.footer - rows pinned below the scrolling items area, separated
+ * by a hairline; they stay visible while the items above scroll.
+ * @param props.selection - how a selected row is marked: a trailing check
+ * (`'check'`, default — figma .Menu_cell) or the hover fill held on the row
+ * with no check (`'fill'`, for icon-labelled rows where a trailing glyph
+ * crowds the cell).
+ * @returns anchor wrapper with the conditional list.
+ */
+export declare function Menu({ open, anchor, items, selectedId, selectedIds, onSelect, onClose, align, side, portal, closeOnPointerLeave, dense, compact, autoFocus, selection, getAnchorRect, footer, className }: {
+    open: boolean;
+    autoFocus?: boolean;
+    anchor: ReactNode;
+    items: readonly MenuEntry[];
+    footer?: readonly MenuEntry[];
+    selectedId?: string | undefined;
+    selectedIds?: readonly string[] | undefined;
+    onSelect: (id: string) => void;
+    onClose: () => void;
+    align?: 'start' | 'end';
+    side?: 'bottom' | 'top' | 'right';
+    portal?: boolean;
+    closeOnPointerLeave?: boolean;
+    dense?: boolean;
+    compact?: boolean;
+    selection?: 'check' | 'fill';
+    getAnchorRect?: () => DOMRect | null;
+    className?: string | undefined;
+}): import("react").JSX.Element;
+//# sourceMappingURL=Menu.d.ts.map

package/lib/types/MenuGroup.d.ts

@@ -0,0 +1,22 @@
+/** Accessible menu groups with shared sticky-heading presentation and viewport observation. */
+import { type ReactNode } from 'react';
+/**
+ * Render a named group with an instance-owned heading id and an inaccessible position sentinel.
+ * @param props - Caller-localized label and optional menu rows.
+ * @returns A section named by its direct heading, followed by the supplied children.
+ */
+export declare function MenuGroup({ label, children }: {
+    label: string;
+    children?: ReactNode;
+}): import("react").JSX.Element;
+/**
+ * Update heading backgrounds asynchronously from native intersection and viewport-size observations.
+ * Headings remain transparent until observations identify a section crossing the viewport top.
+ * Without IntersectionObserver or ResizeObserver, CSS sticky headings remain transparent.
+ * Group membership is captured at setup; dispose before observing changed groups or the same viewport again.
+ * @param viewport - Unpadded, borderless scroll container with direct MenuGroup children.
+ * @returns Cleanup owning both intersection observers and the viewport resize observer; disconnects
+ * them, ignores queued callbacks, and clears managed data-stuck attributes. No valid groups acquires nothing.
+ */
+export declare function observeStickyMenuGroups(viewport: HTMLElement): () => void;
+//# sourceMappingURL=MenuGroup.d.ts.map

package/lib/types/MenuSurface.d.ts

@@ -0,0 +1,16 @@
+/** Shared menu material and the macOS backing that lets Chromium blur transparent windows. */
+import { type ComponentPropsWithoutRef } from 'react';
+/** Menu containers preserve native div props and refs. */
+export interface MenuSurfaceProps extends ComponentPropsWithoutRef<'div'> {
+    /** Match the shared compact menu's smaller outer radius. */
+    compact?: boolean;
+}
+/**
+ * Paint a menu and, on macOS, an opaque backing behind the page content within its bounds.
+ * CSS anchors keep each backing aligned during placement, resizing, and nested-menu movement.
+ * @param props - Div content and placement, and compact geometry.
+ * @param ref - The visible menu div, excluding the non-interactive backing.
+ * @returns Menu content plus a backing portal removed with the menu.
+ */
+export declare const MenuSurface: import("react").ForwardRefExoticComponent<MenuSurfaceProps & import("react").RefAttributes<HTMLDivElement>>;
+//# sourceMappingURL=MenuSurface.d.ts.map

package/lib/types/Modal.d.ts

@@ -0,0 +1,44 @@
+import type { KeyboardEventHandler, ReactNode } from 'react';
+interface ModalBaseProps {
+    open: boolean;
+    onClose: () => void;
+    title: string;
+    description?: string;
+    children?: ReactNode;
+    footer?: ReactNode;
+    className?: string;
+    contentClassName?: string;
+    shortcutModal?: string;
+    onKeyDownCapture?: KeyboardEventHandler<HTMLDivElement>;
+    backdropBlur?: boolean;
+}
+type ModalProps = ModalBaseProps & ({
+    headless: true;
+    closeLabel?: never;
+} | {
+    headless?: false;
+    closeLabel: string;
+});
+/**
+ * Render a centered, body-portaled modal over a page mask.
+ * @param props.open - whether the dialog is showing.
+ * @param props.onClose - application close command, Escape, or mask click; while a menu is open inside the
+ * dialog, Escape belongs to that menu first.
+ * @param props.title - dialog heading (aria-label in every mode).
+ * @param props.closeLabel - localized accessible close-button label.
+ * @param props.description - optional supporting sentence under the title.
+ * @param props.children - dialog body; mark its initial-focus control with
+ * data-modal-autofocus instead of React autoFocus to preserve return focus.
+ * @param props.footer - action row (Cancel / Create).
+ * @param props.contentClassName - optional class for a scrollable content region.
+ * @param props.headless - render children directly in the card (no default
+ * header/close/body chrome); mask, card, Escape, and aria-label remain.
+ * @param props.backdropBlur - disable when the caller already blurs the page; defaults to true.
+ * @param props.shortcutModal - command scope allowed by shortcut owners; unnamed
+ * dialogs block application commands unless their owner allows the "other" scope.
+ * @param props.onKeyDownCapture - handle a nested dialog's keys before the document Escape listeners.
+ * @returns null when closed; otherwise the overlay tree.
+ */
+export declare function Modal({ open, onClose, title, closeLabel, description, children, footer, className, contentClassName, onKeyDownCapture, headless, backdropBlur, shortcutModal, }: ModalProps): import("react").ReactPortal | null;
+export {};
+//# sourceMappingURL=Modal.d.ts.map

package/lib/types/OnboardingSurface.d.ts

@@ -0,0 +1,11 @@
+import type { ReactNode } from 'react';
+/**
+ * Render a body-portaled onboarding stage and keep the application root inert
+ * while mounted.
+ * @param props.children - the step's page content, centered on the stage.
+ * @returns the body-portaled overlay tree.
+ */
+export declare function OnboardingSurface({ children }: {
+    children: ReactNode;
+}): import("react").ReactPortal;
+//# sourceMappingURL=OnboardingSurface.d.ts.map