@hirobius/design-system 0.11.0 → 0.13.0

package/dist/types/src/app/components/cluster.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Cluster — wrapping horizontal group with even gaps.
+ * @category Layout
+ * @tier primitive
+ * @ai-intent Solves the "row of same-ish things that wraps gracefully" problem
+ * (tag rows, button groups, chip lists, filter pills) with a single flex-wrap
+ * wrapper and a tokenized gap in both axes, so agents stop hand-rolling
+ * `flexWrap` + `gap` + alignment combinations inline.
+ * @ai-rules Reach for this named layout intent before Box/sx. Use Cluster for
+ * horizontal groups that should wrap as a unit. Spacing MUST use semantic
+ * steps, never raw px. Do NOT use Cluster for a strict single-line row — use
+ * Stack with `direction="row"` when wrapping is never desired. Do NOT use
+ * Cluster for two-dimensional grid layouts — use Grid.
+ *
+ * Every Layout reference: https://every-layout.dev/layouts/cluster/
+ */
+import React from 'react';
+type LayoutGap = 'tight' | 'normal' | 'inset' | 'spacious';
+type ClusterAlign = 'start' | 'center' | 'end' | 'stretch';
+type ClusterJustify = 'start' | 'center' | 'end' | 'space-between';
+interface ClusterProps {
+    /** Cluster content — items that wrap as a unit. */
+    children: React.ReactNode;
+    /** Gap token applied to both axes (row and column). Defaults to 'tight'. */
+    gap?: LayoutGap;
+    /** Cross-axis alignment of items within a wrapped row. Defaults to 'center'. */
+    align?: ClusterAlign;
+    /** Main-axis distribution. Defaults to 'start'. */
+    justify?: ClusterJustify;
+    /** Escape hatch: only use when tokenized props cannot express the required wrapper class. */
+    className?: string;
+    /** Escape hatch: only use for narrow layout adjustments that do not belong in the primitive API. */
+    style?: React.CSSProperties;
+    /** Element rendered as the outer wrapper. Defaults to 'div'. */
+    as?: React.ElementType;
+}
+/** @public */
+export declare const Cluster: React.ForwardRefExoticComponent<ClusterProps & React.RefAttributes<HTMLDivElement>>;
+export {};

package/dist/types/src/app/components/code-block.d.ts

@@ -3,6 +3,23 @@
  * @category Display
  * @tier primitive
  */
+declare const blockContainerVariants: (props?: import("class-variance-authority/dist/types").ClassProp) => string;
+declare const inlineWrapperVariants: (props?: import("class-variance-authority/dist/types").ClassProp) => string;
+declare const blockHeaderVariants: (props?: import("class-variance-authority/dist/types").ClassProp) => string;
+declare const collapsibleToggleVariants: (props?: import("class-variance-authority/dist/types").ClassProp) => string;
+declare const chevronVariants: (props?: {
+    expanded?: boolean;
+} & import("class-variance-authority/dist/types").ClassProp) => string;
+declare const copyButtonVariants: (props?: {
+    variant?: "block" | "inline";
+} & import("class-variance-authority/dist/types").ClassProp) => string;
+declare const inlineCodeTextVariants: (props?: {
+    truncateFromStart?: boolean;
+} & import("class-variance-authority/dist/types").ClassProp) => string;
+declare const blockCodeTextVariants: (props?: import("class-variance-authority/dist/types").ClassProp) => string;
+declare const prePanelVariants: (props?: {
+    panelBackground?: boolean;
+} & import("class-variance-authority/dist/types").ClassProp) => string;
 interface CodeBlockProps {
     /** Code string displayed in the block. */
     code: string;
@@ -26,4 +43,5 @@ interface CodeBlockProps {
 }
 /** @public */
 export declare function CodeBlock({ code, variant, truncateFromStart, language, filename, collapsible, defaultExpanded, className, }: CodeBlockProps): import("react/jsx-runtime").JSX.Element;
-export {};
+/** @internal — CVA variant helpers; compose via CodeBlock props instead. */
+export { blockContainerVariants, inlineWrapperVariants, blockHeaderVariants, collapsibleToggleVariants, copyButtonVariants, inlineCodeTextVariants, blockCodeTextVariants, prePanelVariants, chevronVariants, };

package/dist/types/src/app/components/command-palette.d.ts

@@ -0,0 +1,44 @@
+/**
+ * CommandPalette — Cmd-K / Ctrl-K fuzzy-search over the HDS manifest.
+ * @category Overlays
+ * @tier primitive
+ * @public
+ *
+ * Built on Dialog (8s-7 / Radix) with a custom listbox + input. NO new
+ * npm deps — search is a hand-rolled subsequence + token-Levenshtein scorer
+ * (think micro-fzf). Indexes four corpora from `virtual:hds-manifest`:
+ *
+ *   1. componentSpecs — non-hidden, non-docExempt entries (primitive / pattern / template)
+ *   2. utilities      — non-hidden entries (utility tier)
+ *   3. role tokens    — `role.*` entries from manifest.tokens.role
+ *   4. section anchors — curated /hds foundation + tokens pages
+ *
+ * Each row carries a tier chip + brief description. Enter (or click)
+ * navigates via React Router; Esc closes. ↑/↓ wraps. Cmd-K / Ctrl-K
+ * toggles open from anywhere in the doc shell.
+ *
+ * Result rows sanitize free-text: HMAC-style tokens (long hex / signed
+ * URL fragments that may leak from upstream description fields) are
+ * stripped before render.
+ */
+import * as React from 'react';
+declare const cmdkRowVariants: (props?: {
+    active?: boolean;
+} & import("class-variance-authority/dist/types").ClassProp) => string;
+declare const cmdkKindBadgeVariants: (props?: {
+    active?: boolean;
+} & import("class-variance-authority/dist/types").ClassProp) => string;
+declare const cmdkDescriptionVariants: (props?: {
+    active?: boolean;
+} & import("class-variance-authority/dist/types").ClassProp) => string;
+export interface CommandPaletteProps {
+    /** Optional className for the trigger button. */
+    className?: string;
+}
+/**
+ * Mountable trigger + dialog. Drop into header slot; component manages its
+ * own open state and Cmd-K / Ctrl-K global keybinding.
+ */
+export declare const CommandPalette: React.ForwardRefExoticComponent<CommandPaletteProps & React.RefAttributes<HTMLInputElement>>;
+/** @internal — CVA variant helpers; compose via CommandPalette instead. */
+export { cmdkRowVariants, cmdkKindBadgeVariants, cmdkDescriptionVariants };

package/dist/types/src/app/components/container.d.ts

@@ -2,6 +2,16 @@
  * Container — semantic width-constrained layout.
  * @category Layout
  * @tier primitive
+ * @ai-intent Solves horizontal width constraint and page centering with a
+ * semantic max-width scale, so agents stop hand-rolling `marginInline: auto`
+ * plus an ad hoc max-width pixel value for page shells.
+ * @ai-rules Reach for this named layout intent before Box/sx. maxWidth MUST
+ * use the semantic width scale ('content' | 'max'), never a raw px value. Do
+ * NOT use the deprecated `padding` prop — it is a no-op; apply padding via
+ * Surface or a Stack instead. Do NOT import Container directly inside a page
+ * under src/app/pages — use Page, which wraps Container and owns vertical
+ * rhythm. Use Center instead when you also need a horizontal gutter, which
+ * Container does not support.
  *
  * Centers content horizontally and applies semantic max-width constraints.
  * - maxWidth options: 'content' (760px prose) | 'max' (1200px full layout)

package/dist/types/src/app/components/context-menu.d.ts

@@ -0,0 +1,55 @@
+/**
+ * ContextMenu — right-click context menu on Radix ContextMenu.
+ * @category Overlays
+ * @tier primitive
+ * @doc-exempt: no Overlays doc page yet — add demo when the overlays page is created
+ *
+ * Radix ContextMenu (@radix-ui/react-context-menu) themed with the same overlay
+ * role tokens as Menu, so the dropdown and the right-click menu are visually
+ * identical. Provides roving focus, type-ahead, checkbox/radio items, submenus,
+ * cursor-anchored positioning, and portal mounting out of the box.
+ *
+ *   <ContextMenu>
+ *     <ContextMenu.Trigger>Right-click me</ContextMenu.Trigger>
+ *     <ContextMenu.Content>
+ *       <ContextMenu.Item onSelect={…}>Cut</ContextMenu.Item>
+ *       <ContextMenu.Separator />
+ *       <ContextMenu.Item disabled>Paste</ContextMenu.Item>
+ *     </ContextMenu.Content>
+ *   </ContextMenu>
+ */
+import * as React from 'react';
+import * as ContextMenuPrimitive from '@radix-ui/react-context-menu';
+declare const ContextMenuTrigger: React.ForwardRefExoticComponent<ContextMenuPrimitive.ContextMenuTriggerProps & React.RefAttributes<HTMLSpanElement>>;
+declare const ContextMenuGroup: React.ForwardRefExoticComponent<ContextMenuPrimitive.ContextMenuGroupProps & React.RefAttributes<HTMLDivElement>>;
+declare const ContextMenuRadioGroup: React.ForwardRefExoticComponent<ContextMenuPrimitive.ContextMenuRadioGroupProps & React.RefAttributes<HTMLDivElement>>;
+declare const ContextMenuSub: React.FC<ContextMenuPrimitive.ContextMenuSubProps>;
+declare const ContextMenuContent: React.ForwardRefExoticComponent<Omit<ContextMenuPrimitive.ContextMenuContentProps & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
+declare const ContextMenuItem: React.ForwardRefExoticComponent<Omit<ContextMenuPrimitive.ContextMenuItemProps & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
+declare const ContextMenuCheckboxItem: React.ForwardRefExoticComponent<Omit<ContextMenuPrimitive.ContextMenuCheckboxItemProps & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
+declare const ContextMenuRadioItem: React.ForwardRefExoticComponent<Omit<ContextMenuPrimitive.ContextMenuRadioItemProps & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
+declare const ContextMenuLabel: React.ForwardRefExoticComponent<Omit<ContextMenuPrimitive.ContextMenuLabelProps & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
+declare const ContextMenuSeparator: React.ForwardRefExoticComponent<Omit<ContextMenuPrimitive.ContextMenuSeparatorProps & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
+declare const ContextMenuSubTrigger: React.ForwardRefExoticComponent<Omit<ContextMenuPrimitive.ContextMenuSubTriggerProps & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
+declare const ContextMenuSubContent: React.ForwardRefExoticComponent<Omit<ContextMenuPrimitive.ContextMenuSubContentProps & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
+interface ContextMenuComponent extends React.FC<React.ComponentProps<typeof ContextMenuPrimitive.Root>> {
+    Trigger: typeof ContextMenuTrigger;
+    Content: typeof ContextMenuContent;
+    Item: typeof ContextMenuItem;
+    CheckboxItem: typeof ContextMenuCheckboxItem;
+    RadioGroup: typeof ContextMenuRadioGroup;
+    RadioItem: typeof ContextMenuRadioItem;
+    Label: typeof ContextMenuLabel;
+    Separator: typeof ContextMenuSeparator;
+    Group: typeof ContextMenuGroup;
+    Sub: typeof ContextMenuSub;
+    SubTrigger: typeof ContextMenuSubTrigger;
+    SubContent: typeof ContextMenuSubContent;
+}
+/**
+ * ContextMenu root + parts. Wrap the right-clickable area in
+ * `ContextMenu.Trigger`. Controlled via `onOpenChange`.
+ * @public
+ */
+export declare const ContextMenu: ContextMenuComponent;
+export {};

package/dist/types/src/app/components/cover.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Cover — vertical shell with an auto-centered main region.
+ * @category Layout
+ * @tier primitive
+ * @ai-intent Solves the "full-height section with an optional header, a
+ * centered hero/main region that absorbs the remaining space, and an
+ * optional footer" problem via the flex auto-margin centering technique, so
+ * agents stop hand-rolling `position: absolute` centering or a fixed 50vh
+ * split.
+ * @ai-rules Reach for this named layout intent before Box/sx. gap MUST use a
+ * semantic space step, never raw px. minHeight is a CSS length dimension
+ * (not spacing) — defaults to '100svh' (small viewport height, safe against
+ * mobile browser chrome). Pass minHeight="100vh" explicitly if you need the
+ * classic viewport unit for a target that predates svh support. Do NOT use
+ * Cover for ordinary page content flow — use Stack.
+ *
+ * Every Layout reference: https://every-layout.dev/layouts/cover/
+ */
+import React from 'react';
+type LayoutGap = 'tight' | 'normal' | 'inset' | 'spacious';
+interface CoverProps {
+    /** The centered main region — takes the remaining space via auto margins. Also available as `centerSlot`. */
+    children?: React.ReactNode;
+    /** Alias for `children` — the centered main region. If both are set, `centerSlot` wins. */
+    centerSlot?: React.ReactNode;
+    /** Optional content pinned to the top. */
+    header?: React.ReactNode;
+    /** Optional content pinned to the bottom. */
+    footer?: React.ReactNode;
+    /** Minimum block size of the cover (CSS length). Defaults to '100svh'. */
+    minHeight?: string;
+    /** Gap enforced between header/main/footer, in addition to the auto-margin centering. Defaults to 'normal'. */
+    gap?: LayoutGap;
+    /** Escape hatch: only use when tokenized props cannot express the required wrapper class. */
+    className?: string;
+    /** Escape hatch: only use for narrow layout adjustments that do not belong in the primitive API. */
+    style?: React.CSSProperties;
+    /** Element rendered as the outer wrapper. Defaults to 'div'. */
+    as?: React.ElementType;
+}
+/** @public */
+export declare const Cover: React.ForwardRefExoticComponent<CoverProps & React.RefAttributes<HTMLDivElement>>;
+export {};

package/dist/types/src/app/components/date-input.d.ts

@@ -0,0 +1,31 @@
+/**
+ * DateInput — single-date text field with a calendar popover picker, so
+ * typing a date and picking one from a grid read as one input rather than
+ * two disconnected controls glued together by a consuming app.
+ * @category Inputs
+ * @tier pattern
+ * @public
+ *
+ * Composes the HDS Popover (trigger = calendar icon button) with Calendar
+ * for the grid, and date-fns for parse/format of the free-typed text. The
+ * text field and the picker stay in sync in both directions.
+ *
+ *   <DateInput value={date} onChange={setDate} />
+ */
+import * as React from 'react';
+/** @public */
+export interface DateInputProps {
+    /** Currently selected date, or undefined when empty. */
+    value?: Date;
+    /** Fired with the next date, or undefined when the field is cleared/invalid. */
+    onChange?: (date: Date | undefined) => void;
+    /** date-fns format string used to display and parse the text value. */
+    displayFormat?: string;
+    /** Placeholder shown when the field is empty; defaults to the display format. */
+    placeholder?: string;
+    disabled?: boolean;
+    id?: string;
+    'aria-label'?: string;
+}
+/** Text field + calendar popover for picking a single date. */
+export declare const DateInput: React.ForwardRefExoticComponent<DateInputProps & React.RefAttributes<HTMLInputElement>>;

package/dist/types/src/app/components/date-range-input.d.ts

@@ -0,0 +1,34 @@
+/**
+ * DateRangeInput — date-range field composing the existing Popover with
+ * Calendar in range mode, so picking a start/end date reads as one overlay
+ * pattern with Combobox and Menu rather than a bespoke widget.
+ * @category Inputs
+ * @tier pattern
+ * @public
+ *
+ * No new primitive — built entirely on the HDS Popover + Calendar. The
+ * trigger reads like a secondary input, showing a placeholder or the
+ * formatted `from – to` range; the content is a two-month range calendar.
+ *
+ *   <DateRangeInput value={range} onChange={setRange} />
+ */
+import * as React from 'react';
+import type { DateRange } from 'react-day-picker';
+/** @public */
+export interface DateRangeInputProps {
+    /** Currently selected range. */
+    value?: DateRange;
+    /** Fired with the next range whenever the calendar selection changes. */
+    onChange?: (range: DateRange | undefined) => void;
+    /** date-fns format string used to render the selected range on the trigger. */
+    displayFormat?: string;
+    /** Trigger text when nothing is selected. */
+    placeholder?: string;
+    disabled?: boolean;
+    /** Number of months rendered side by side in the calendar. */
+    numberOfMonths?: number;
+    id?: string;
+    'aria-label'?: string;
+}
+/** @public */
+export declare const DateRangeInput: React.ForwardRefExoticComponent<DateRangeInputProps & React.RefAttributes<HTMLButtonElement>>;

package/dist/types/src/app/components/date-time-input.d.ts

@@ -0,0 +1,30 @@
+/**
+ * DateTimeInput — combined date + time field pairing a text date input with
+ * a calendar popover and a native time field, so picking a moment in time
+ * reads as one control instead of two disconnected inputs glued together by
+ * a consuming app.
+ * @category Inputs
+ * @tier pattern
+ * @public
+ *
+ * Composes the HDS Popover (trigger = calendar icon button) with Calendar
+ * for the date grid, and TimeInput for the time-of-day, keeping both parts
+ * in sync with a single `Date` value via date-fns.
+ *
+ *   <DateTimeInput value={date} onChange={setDate} />
+ */
+import * as React from 'react';
+/** @public */
+export interface DateTimeInputProps {
+    /** Currently selected date + time, or undefined when empty. */
+    value?: Date;
+    /** Fired with the next combined date/time, or undefined when cleared. */
+    onChange?: (date: Date | undefined) => void;
+    /** date-fns format string used to display and parse the date portion. */
+    dateFormat?: string;
+    disabled?: boolean;
+    id?: string;
+    'aria-label'?: string;
+}
+/** Text date field + calendar popover, paired with a native time field, producing one Date. */
+export declare const DateTimeInput: React.ForwardRefExoticComponent<DateTimeInputProps & React.RefAttributes<HTMLInputElement>>;

package/dist/types/src/app/components/disclosure.d.ts

@@ -5,6 +5,9 @@
  */
 import React, { type CSSProperties, type ReactNode } from 'react';
 type DisclosureVariant = 'panel' | 'nav' | 'card';
+declare const disclosureTriggerVariants: (props?: {
+    variant?: "nav" | "panel" | "card";
+} & import("class-variance-authority/dist/types").ClassProp) => string;
 type DisclosureProps = {
     /** Summary label rendered in the disclosure trigger. Accepts a string or ReactNode for icon+label combos. */
     label: ReactNode;
@@ -29,4 +32,5 @@ type DisclosureProps = {
 };
 /** @public */
 export declare const Disclosure: React.ForwardRefExoticComponent<DisclosureProps & React.RefAttributes<HTMLDivElement>>;
-export {};
+/** @internal — CVA variant helper; compose via Disclosure props instead. */
+export { disclosureTriggerVariants };

package/dist/types/src/app/components/divider.d.ts

@@ -3,19 +3,23 @@
  * @category Layout
  * @tier primitive
  */
-import type { CSSProperties } from 'react';
-interface DividerProps {
-    /** Divider orientation. */
-    orientation?: 'horizontal' | 'vertical';
+import * as React from 'react';
+import { type VariantProps } from 'class-variance-authority';
+declare const dividerVariants: (props?: {
+    orientation?: "horizontal" | "vertical";
+    variant?: "default" | "strong";
+} & import("class-variance-authority/dist/types").ClassProp) => string;
+type DividerVariantProps = VariantProps<typeof dividerVariants>;
+/** @public */
+export interface DividerProps extends Omit<React.HTMLAttributes<HTMLHRElement>, 'children'>, DividerVariantProps {
     /** Perpendicular spacing around the divider. */
     spacing?: string | number;
-    /** Increase the stroke weight for stronger separation. */
+    /**
+     * @deprecated Use `variant="strong"` instead. Kept for backward
+     * compatibility; when set, it takes precedence over `variant`.
+     */
     strong?: boolean;
-    /** Optional inline styles for one-off layout adjustments. */
-    style?: CSSProperties;
-    /** Optional class hook for parent-level styling. */
-    className?: string;
 }
 /** @public */
-export declare function Divider({ orientation, spacing, strong, style, className, }: DividerProps): import("react/jsx-runtime").JSX.Element;
+export declare const Divider: React.ForwardRefExoticComponent<DividerProps & React.RefAttributes<HTMLHRElement>>;
 export {};

package/dist/types/src/app/components/doc-link-card.d.ts

@@ -21,6 +21,10 @@ interface DocLinkCardProps {
     /** Directional affordance for the header icon. */
     affordance?: 'up-right' | 'right' | 'left';
 }
+declare const docLinkCardVariants: (props?: {
+    variant?: "feature" | "pager";
+} & import("class-variance-authority/dist/types").ClassProp) => string;
 /** @public */
 export declare function DocLinkCard({ title, description, href, icon: CardIcon, meta, metaStyle, accent, variant, disabled, affordance, }: DocLinkCardProps): import("react/jsx-runtime").JSX.Element;
-export {};
+/** @internal — CVA variant helper; compose via DocLinkCard props instead. */
+export { docLinkCardVariants };

package/dist/types/src/app/components/field.d.ts

@@ -3,23 +3,21 @@
  * @tier primitive
  */
 import * as React from 'react';
-declare const VALUE_TONE: {
-    readonly default: "text-foreground";
-    readonly success: "text-[var(--semantic-color-feedback-success)]";
-    readonly warning: "text-[var(--semantic-color-feedback-warning)]";
-    readonly danger: "text-[var(--semantic-color-feedback-error)]";
-};
-export type FieldTone = keyof typeof VALUE_TONE;
+import { type VariantProps } from 'class-variance-authority';
+declare const fieldValueVariants: (props?: {
+    tone?: "success" | "danger" | "warning" | "info" | "neutral";
+    mono?: boolean;
+} & import("class-variance-authority/dist/types").ClassProp) => string;
+type FieldValueVariantProps = VariantProps<typeof fieldValueVariants>;
 /** @public */
-export interface FieldProps extends React.HTMLAttributes<HTMLDivElement> {
+export interface FieldProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'children'>, FieldValueVariantProps {
     label: string;
     value?: React.ReactNode;
-    tone?: FieldTone;
-    mono?: boolean;
     children?: React.ReactNode;
 }
 /**
  * Caption label paired with a value — used in metadata grids and read-only forms.
  */
 export declare const Field: React.ForwardRefExoticComponent<FieldProps & React.RefAttributes<HTMLDivElement>>;
-export {};
+/** @internal — CVA variant helper; compose via Field props instead. */
+export { fieldValueVariants };

package/dist/types/src/app/components/file-input.d.ts

@@ -0,0 +1,28 @@
+/**
+ * FileInput — styled dropzone that wraps a real native file input for full
+ * keyboard and screen-reader accessibility, with optional drag-and-drop.
+ * @category Inputs
+ * @tier pattern
+ * @public
+ */
+import * as React from 'react';
+declare const fileInputVariants: (props?: {
+    dragging?: boolean;
+    disabled?: boolean;
+} & import("class-variance-authority/dist/types").ClassProp) => string;
+export interface FileInputProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'type' | 'onChange'> {
+    /** Called with the selected (or dropped) files. */
+    onFiles?: (files: File[]) => void;
+    /** Dropzone prompt content. */
+    label?: React.ReactNode;
+    /** Native `accept` attribute, e.g. `"image/*"`. */
+    accept?: string;
+    /** Allow selecting more than one file. */
+    multiple?: boolean;
+    /** Disable interaction. */
+    disabled?: boolean;
+}
+/** A dashed dropzone that opens the native file picker or accepts a drag-and-drop. */
+export declare const FileInput: React.ForwardRefExoticComponent<FileInputProps & React.RefAttributes<HTMLInputElement>>;
+/** @internal — CVA variant helper; compose via FileInput props instead. */
+export { fileInputVariants };

package/dist/types/src/app/components/frame.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Frame — aspect-ratio-locked, token-clipped media box.
+ * @category Layout
+ * @tier primitive
+ * @ai-intent Solves "media that must reserve a fixed aspect ratio and never
+ * cause layout shift while it loads, cropped to a token-governed corner
+ * radius" — a thin, token-skinned wrapper over `AspectRatio`
+ * (`@radix-ui/react-aspect-ratio`), which already owns the ratio-lock
+ * mechanics. Frame adds the overflow-hidden clip and semantic radius that a
+ * bare media frame needs and `AspectRatio` deliberately leaves undecorated.
+ * @ai-rules Reach for this named layout intent before Box/sx when framing
+ * media (image, video, embed, map tile). radius MUST use a semantic
+ * borderRadius token, never a raw px value. Do NOT reach for bare
+ * `AspectRatio` in product code just to add a border-radius by hand — use
+ * Frame. Do NOT use Frame for non-media layout — it exists purely as a media
+ * clipping frame.
+ *
+ * Every Layout reference: https://every-layout.dev/layouts/frame/
+ */
+import React from 'react';
+type FrameRadius = 'none' | 'sm' | 'md' | 'full';
+interface FrameProps {
+    /** Media rendered inside the locked-ratio, clipped frame. */
+    children: React.ReactNode;
+    /** Desired width-to-height ratio, e.g. `16 / 9`. Defaults to `16 / 9`. */
+    ratio?: number;
+    /** Corner radius token applied to the clipped frame. Defaults to 'md'. */
+    radius?: FrameRadius;
+    /** Escape hatch: only use when tokenized props cannot express the required wrapper class. */
+    className?: string;
+    /** Escape hatch: only use for narrow layout adjustments that do not belong in the primitive API. */
+    style?: React.CSSProperties;
+    /** Element rendered as the outer clipping wrapper. Defaults to 'div'. */
+    as?: React.ElementType;
+}
+/** @public */
+export declare const Frame: React.ForwardRefExoticComponent<FrameProps & React.RefAttributes<HTMLDivElement>>;
+export {};

package/dist/types/src/app/components/heading-stack.d.ts

@@ -16,9 +16,18 @@
  * @tier primitive
  * @doc-exempt: internal typography lockup utility, documented through page composition rather than a standalone component page
  */
-import React, { type ElementType } from 'react';
-type HdsHeadingLevel = 'heading1' | 'heading2' | 'heading3';
-type HdsHeadingGap = 'px4' | 'px8';
+import { type ElementType } from 'react';
+import { type VariantProps } from 'class-variance-authority';
+declare const headingStackVariants: (props?: {
+    gap?: "px4" | "px8";
+} & import("class-variance-authority/dist/types").ClassProp) => string;
+declare const headingStackLevelVariants: (props?: {
+    level?: "heading1" | "heading2" | "heading3";
+} & import("class-variance-authority/dist/types").ClassProp) => string;
+type HeadingStackGapVariantProps = VariantProps<typeof headingStackVariants>;
+type HeadingStackLevelVariantProps = VariantProps<typeof headingStackLevelVariants>;
+type HdsHeadingLevel = NonNullable<HeadingStackLevelVariantProps['level']>;
+type HdsHeadingGap = NonNullable<HeadingStackGapVariantProps['gap']>;
 type HdsHeadingTag = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
 type HdsSupportingTag = 'p' | 'div' | 'span';
 interface HeadingStackProps {
@@ -38,5 +47,6 @@ interface HeadingStackProps {
     subheadingAs?: HdsSupportingTag;
 }
 /** @public */
-export declare const HeadingStack: React.ForwardRefExoticComponent<HeadingStackProps & React.RefAttributes<HTMLElement>>;
-export {};
+export declare const HeadingStack: import("react").ForwardRefExoticComponent<HeadingStackProps & import("react").RefAttributes<HTMLElement>>;
+/** @internal — CVA variant helpers; compose via HeadingStack props instead. */
+export { headingStackVariants, headingStackLevelVariants };

package/dist/types/src/app/components/hover-card.d.ts

@@ -0,0 +1,31 @@
+/**
+ * HoverCard — rich preview shown on hover/focus, on Radix HoverCard.
+ * @category Overlays
+ * @tier primitive
+ * @doc-exempt: no Overlays doc page yet — add demo when the overlays page is created
+ *
+ * Radix HoverCard (@radix-ui/react-hover-card) themed with the overlay role
+ * tokens to match Menu/Popover. For sighted-pointer preview affordances (user
+ * cards, link previews) — it is NOT a replacement for an accessible tooltip on
+ * an interactive control; use HdsTooltip for labelling.
+ *
+ *   <HoverCard>
+ *     <HoverCard.Trigger asChild><InlineLink href="…">@ada</InlineLink></HoverCard.Trigger>
+ *     <HoverCard.Content>Ada Lovelace — first programmer.</HoverCard.Content>
+ *   </HoverCard>
+ */
+import * as React from 'react';
+import * as HoverCardPrimitive from '@radix-ui/react-hover-card';
+declare const HoverCardTrigger: React.ForwardRefExoticComponent<HoverCardPrimitive.HoverCardTriggerProps & React.RefAttributes<HTMLAnchorElement>>;
+declare const HoverCardContent: React.ForwardRefExoticComponent<Omit<HoverCardPrimitive.HoverCardContentProps & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
+interface HoverCardComponent extends React.FC<React.ComponentProps<typeof HoverCardPrimitive.Root>> {
+    Trigger: typeof HoverCardTrigger;
+    Content: typeof HoverCardContent;
+}
+/**
+ * HoverCard root + parts. Controlled via `open`/`onOpenChange`, or uncontrolled
+ * with `defaultOpen`; tune timing with `openDelay`/`closeDelay`.
+ * @public
+ */
+export declare const HoverCard: HoverCardComponent;
+export {};

package/dist/types/src/app/components/image-lightbox.d.ts

@@ -0,0 +1,13 @@
+interface LightboxProps {
+    open: boolean;
+    onClose: () => void;
+    src: string;
+    alt?: string;
+    naturalWidth?: number;
+    naturalHeight?: number;
+    caption?: string;
+    captionHref?: string;
+    captionLabel?: string;
+}
+export declare function Lightbox({ open, onClose, src, alt, naturalWidth, naturalHeight, caption, captionHref, captionLabel, }: LightboxProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/types/src/app/components/inline-code.d.ts

@@ -1,12 +1,23 @@
 import type { CSSProperties, ReactNode } from 'react';
+import { type VariantProps } from 'class-variance-authority';
+declare const inlineCodeVariants: (props?: {
+    density?: "compact" | "comfortable";
+} & import("class-variance-authority/dist/types").ClassProp) => string;
+type InlineCodeVariantProps = VariantProps<typeof inlineCodeVariants>;
 type InlineCodeProps = {
     children: ReactNode;
     style?: CSSProperties;
-    /** Compact mode is tuned for dense body copy and table prose. */
+    /** Layout density. `compact` tightens vertical rhythm for dense body copy and table prose. Defaults to `comfortable`. */
+    density?: InlineCodeVariantProps['density'];
+    /**
+     * @deprecated Use `density="compact"` instead. Kept for backward
+     * compatibility; when set, it takes precedence over `density`.
+     */
     compact?: boolean;
     /** Show a copy-to-clipboard button. children must be a string when true. */
     copyable?: boolean;
 };
 /** @public */
-export declare function InlineCode({ children, style, compact, copyable }: InlineCodeProps): import("react/jsx-runtime").JSX.Element;
-export {};
+export declare function InlineCode({ children, style, density, compact, copyable, }: InlineCodeProps): import("react/jsx-runtime").JSX.Element;
+/** @internal — CVA variant helper; compose via InlineCode props instead. */
+export { inlineCodeVariants };

package/dist/types/src/app/components/input-group.d.ts

@@ -0,0 +1,23 @@
+/**
+ * InputGroup — a text input framed with leading and/or trailing adornments.
+ * @category Inputs
+ * @tier primitive
+ */
+import * as React from 'react';
+import { type VariantProps } from 'class-variance-authority';
+declare const inputGroupVariants: (props?: {
+    size?: "sm" | "md" | "lg";
+} & import("class-variance-authority/dist/types").ClassProp) => string;
+type InputGroupVariantProps = VariantProps<typeof inputGroupVariants>;
+/** @public */
+export interface InputGroupProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'size'>, InputGroupVariantProps {
+    /** Content rendered before the input, e.g. an icon or a static prefix. */
+    leading?: React.ReactNode;
+    /** Content rendered after the input, e.g. a unit or a clear button. */
+    trailing?: React.ReactNode;
+    /** Class applied to the wrapper (the input itself stays transparent). */
+    className?: string;
+}
+/** A single-line input with optional `leading`/`trailing` adornments. */
+export declare const InputGroup: React.ForwardRefExoticComponent<InputGroupProps & React.RefAttributes<HTMLInputElement>>;
+export {};