@hirobius/design-system 0.19.1 → 0.20.0

package/dist/tokens.js

@@ -190,6 +190,7 @@ const a = {
       64: "64px",
       80: "80px",
       96: "96px",
+      120: "120px",
       interactive: {
         min: "44px",
         minCompact: "24px"
@@ -502,16 +503,25 @@ const o = "var(--primitive-typography-family-primary)", n = "var(--primitive-typ
         xs: "var(--semantic-space-subgrid-xs)"
       },
       component: {
-        /** @deprecated hds#206 — use `semantic.space.surface.padding`. */
+        /**
+         * @deprecated hds#206 — use `semantic.space.surface.padding`.
+         * @removeIn 1.0.0
+         */
         padding: "var(--semantic-space-surface-padding)",
-        /** @deprecated hds#206 — use `semantic.space.scale.xs`. */
+        /**
+         * @deprecated hds#206 — use `semantic.space.scale.xs`.
+         * @removeIn 1.0.0
+         */
         gap: "var(--semantic-space-scale-xs)"
       },
       stack: {
         gap: "var(--semantic-space-section-stack)"
       },
       layout: {
-        /** @deprecated hds#206 — use `semantic.space.region.gutter`. */
+        /**
+         * @deprecated hds#206 — use `semantic.space.region.gutter`.
+         * @removeIn 1.0.0
+         */
         gutter: "var(--semantic-space-region-gutter)",
         gap: "var(--semantic-space-layout-gap)",
         section: "var(--semantic-layout-section-paddingY)"
@@ -594,10 +604,21 @@ const o = "var(--primitive-typography-family-primary)", n = "var(--primitive-typ
     large: "var(--primitive-size-24)"
     // 24px — hero / large empty states
   },
-  // ── Density-aware spacing ────────────────────────────────────────────────────
-  // These vars respond to [data-density="compact"] on <html>.
-  // Use for component padding/gap that should tighten in compact mode.
-  // hds.space.px* for fixed measurements that never participate in density.
+  // ── Density-aware spacing (deprecated) ───────────────────────────────────────
+  // These vars respond to [data-density="compact"] on <html>, and so does
+  // semantic.space.scale.*, the one spacing vocabulary (hds#206). The same
+  // names mean different pixels here (density.sm is 8px, scale.sm is 16px),
+  // so this group is deprecated. Nothing in HDS reads it.
+  /**
+   * @deprecated hds#206 — use `hds.semantic.space.scale.*`, which compact density
+   * remaps too. Same pixels at both densities, one step down the name ladder:
+   * `density.sm` → `scale.xs`, `density.md` → `scale.sm`, `density.lg` → `scale.md`,
+   * `density.xl` → `scale.lg`, `density.xl2` → `scale.xl`. `density.xs` (4px),
+   * `density.xl3` (64px) and `density.xl4` (80px) have no scale step:
+   * `hds.space.px4` / `px64` / `px80` keep their comfortable pixels, without the
+   * compact remap.
+   * @removeIn 1.0.0
+   */
   density: {
     xs: "var(--hds-space-xs)",
     // 4px comfortable / 2px compact
@@ -620,7 +641,7 @@ const o = "var(--primitive-typography-family-primary)", n = "var(--primitive-typ
   // CSS var strings — valid in any inline style property that accepts a length.
   // Note: avoid interpolating these into template literal shorthand strings,
   // e.g. `margin: \`0 0 ${hds.space.px20}\`` — use individual properties instead.
-  // For component spacing that adapts to density, use hds.density.* instead.
+  // For component spacing that adapts to density, use hds.semantic.space.scale.* instead.
   space: {
     px1: "var(--primitive-space-px1)",
     px2: "var(--primitive-space-px2)",

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

@@ -18,5 +18,4 @@ export interface AvatarGroupProps extends Omit<React.HTMLAttributes<HTMLDivEleme
 }
 /** Renders up to `max` overlapping avatars followed by a `+N` overflow chip. */
 export declare const AvatarGroup: React.ForwardRefExoticComponent<AvatarGroupProps & React.RefAttributes<HTMLDivElement>>;
-/** @internal — CVA variant helper; compose via AvatarGroup props instead. */
-export { overflowBubbleVariants };
+export {};

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

@@ -2,7 +2,7 @@
  * Badge - compact feedback badge for neutral and semantic states.
  * @category Feedback
  * @tier primitive
- * @usage Label a status, state or count with a compact neutral or semantic chip.
+ * @usage Label a status, state or count with a compact neutral or semantic chip, or a dot.
  * @whenNot A chip people can toggle, or a message that needs a sentence.
  * @useInstead Tag an interactive filter or category chip
  * @useInstead Alert a message that needs a sentence
@@ -18,8 +18,13 @@ type BadgeVariantProps = VariantProps<typeof badgeVariants>;
 export interface BadgeProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, 'style'>, BadgeVariantProps {
     /** Element rendered as the badge wrapper. Defaults to 'span'. */
     as?: React.ElementType;
+    /** Render a solid status dot with no text (children are ignored). */
+    dot?: boolean;
+    /** Dot diameter; used only with `dot`. */
+    size?: 'sm' | 'md' | 'lg';
+    /** Names the dot: role="status" with this aria-label. Without it the dot is aria-hidden. */
+    label?: string;
 }
 /** Compact metadata/status chip. Tone is the only styling input. */
 export declare const Badge: React.ForwardRefExoticComponent<BadgeProps & React.RefAttributes<HTMLSpanElement>>;
-/** @internal — CVA variant helper; compose via Badge props instead. */
-export { badgeVariants };
+export {};

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

@@ -16,5 +16,4 @@ export interface BlockquoteProps extends React.BlockquoteHTMLAttributes<HTMLQuot
 }
 /** A quoted passage; pass `cite` for the source URL and `attribution` for a byline. */
 export declare const Blockquote: React.ForwardRefExoticComponent<BlockquoteProps & React.RefAttributes<HTMLQuoteElement>>;
-/** @internal — CVA variant helper; compose via Blockquote props instead. */
-export { blockquoteVariants };
+export {};

package/dist/types/src/app/components/box-sx.d.ts

@@ -1,13 +1,19 @@
 /**
  * box-sx.ts — pure resolver + CSS injector for Box's `sx` prop.
  *
- * Deliberately dependency-free (no React import) so the resolver is unit
- * testable in isolation from the component tree. `box.tsx` is the only
- * consumer; it re-exports the types below as part of the public `Box` API.
+ * Deliberately React-free (its one import is the dev-only `warnOnce`) so the
+ * resolver is unit testable in isolation from the component tree. Its
+ * consumers: `box.tsx` re-exports the types below as part of the public `Box`
+ * API; `stack.tsx` resolves its `gap` through `resolveSpacingValue`, the one
+ * spacing resolver (hds#206); and the layout components (Grid, Sidebar,
+ * Switcher, Card) resolve theirs through it against `LAYOUT_GAP`, the one copy
+ * of the layout-gap names (hds#404).
  *
  * @internal — the resolver internals (`resolveSx`, `sxClassName`, `injectSx`)
- * are exported for testing but the supported public surface is `Box` + the
- * `Sx*` types, both re-exported from `box.tsx`.
+ * are exported for testing, and `resolveSpacingValue`, `SpacingVocabulary`,
+ * `SPACE_SCALE`, `LAYOUT_GAP_NAMES` and `LAYOUT_GAP` for the components. The
+ * supported public surface is `Box` + the `Sx*` types, both re-exported from
+ * `box.tsx`.
  */
 export declare const BOX_BREAKPOINTS: {
     readonly xs: 375;
@@ -29,18 +35,108 @@ export type ResponsiveValue<T> = T | Partial<Record<Breakpoint, T>>;
 export interface SxObject {
     [key: string]: ResponsiveValue<SxValue> | SxObject | undefined;
 }
+/** The canonical t-shirt scale, `semantic.space.scale.{xs,sm,md,lg,xl}` (hds#206). */
+export declare const SPACE_SCALE: {
+    readonly xs: "var(--semantic-space-scale-xs)";
+    readonly sm: "var(--semantic-space-scale-sm)";
+    readonly md: "var(--semantic-space-scale-md)";
+    readonly lg: "var(--semantic-space-scale-lg)";
+    readonly xl: "var(--semantic-space-scale-xl)";
+};
+/**
+ * The names a spacing prop accepts, and what any other value means there.
+ *
+ * An open vocabulary passes any other string through ('auto', '1rem', a
+ * `var()`) and reads a number by `numbers`: `'units'` is a count of 4px
+ * units (Box `sx`), `'raw'` returns the number as-is for React's inline
+ * style to read as px (Stack and Card `gap`).
+ *
+ * A closed vocabulary resolves its own names and nothing else: any other
+ * value, a number included, resolves to `undefined`, so the prop sets no
+ * style. That is what the layout components rendered before hds#404, when
+ * each looked a value up in a private map.
+ */
+export type SpacingVocabulary = {
+    readonly names: Readonly<Record<string, string>>;
+    readonly numbers: 'units' | 'raw';
+} | {
+    readonly names: Readonly<Record<string, string>>;
+    readonly closed: true;
+};
+type OpenSpacingVocabulary = Extract<SpacingVocabulary, {
+    readonly numbers: unknown;
+}>;
+type ClosedSpacingVocabulary = Extract<SpacingVocabulary, {
+    readonly closed: true;
+}>;
+/**
+ * The layout-gap names (hds#404): the only copy of the four names the layout
+ * components take for a gap, a gutter or a bleed, with the same values as
+ * Stack's `gap`:
+ *
+ *   tight    → var(--semantic-space-scale-sm)
+ *   normal   → var(--semantic-space-scale-md)
+ *   inset    → var(--semantic-space-scale-lg)
+ *   spacious → var(--semantic-space-scale-xl)
+ *
+ * They read the scale steps, so compact density tightens them. Box `sx`'s
+ * deprecated names of the same spelling read the fixed layout vars instead
+ * (BOX_SX_SPACING below). scripts/check-layout-gap-vocabulary.mjs fails a
+ * second copy anywhere else in src/.
+ */
+export declare const LAYOUT_GAP_NAMES: {
+    readonly tight: "var(--semantic-space-scale-sm)";
+    readonly normal: "var(--semantic-space-scale-md)";
+    readonly inset: "var(--semantic-space-scale-lg)";
+    readonly spacious: "var(--semantic-space-scale-xl)";
+};
+/**
+ * Grid, Sidebar and Switcher `gap` (Cluster, Cover, Bleed and Center, which
+ * read it too, went in 0.20.0, hds#394): the four layout-gap names, plus
+ * `medium` (hds#393), and nothing else. Closed, so an untyped value sets no style, as it did before
+ * hds#404 (scripts/__tests__/spacing-computed-lock.test.mjs).
+ *
+ * `medium` is the 12px default gap of TileGrid (removed in 0.20.0, hds#395),
+ * `semantic.space.component.medium`, the step Stack's `medium` reads. Unlike
+ * the four names it is fixed: compact density does not remap it, as it did not
+ * remap TileGrid's 12px. Only
+ * Grid's `gap` type takes it so far. It stays out of LAYOUT_GAP_NAMES, so
+ * Card and Stack, which spread those names, do not change.
+ */
+export declare const LAYOUT_GAP: {
+    names: {
+        medium: string;
+        tight: "var(--semantic-space-scale-sm)";
+        normal: "var(--semantic-space-scale-md)";
+        inset: "var(--semantic-space-scale-lg)";
+        spacious: "var(--semantic-space-scale-xl)";
+    };
+    closed: true;
+};
+/**
+ * The one spacing resolver for Box `sx`, Stack `gap` and the layout
+ * components. A name is looked up in the caller's vocabulary (own keys only,
+ * so 'constructor' is not a name). Anything else ('auto', '1rem', a `var()`)
+ * passes through an open vocabulary and resolves to `undefined` in a closed
+ * one. The return type says which: an open vocabulary never yields
+ * `undefined`, so Box cannot emit `margin:undefined`, and a closed one never
+ * yields a number.
+ */
+export declare function resolveSpacingValue(value: SxValue, vocabulary: OpenSpacingVocabulary): string | number;
+export declare function resolveSpacingValue(value: SxValue, vocabulary: ClosedSpacingVocabulary): string | undefined;
+export declare function resolveSpacingValue(value: SxValue, vocabulary: SpacingVocabulary): string | number | undefined;
 /**
  * Resolves an `SxObject` into an ordered array of standalone, top-level CSS
  * rule strings ready for individual `CSSStyleSheet.insertRule()` calls.
  *
- * Pure — no DOM access. Order: base (non-responsive) rules for every selector
- * encountered (outer class first, then each `&`-selector in declaration
- * order), followed by `@media (min-width: …)` blocks in ascending breakpoint
- * order. Each media block is ONE rule string containing its inner selector
- * rules concatenated as plain text — that concatenation is safe (and
- * required) because a single `insertRule()` call for an `@media {...}` block
- * is one rule; only top-level rule concatenation breaks `insertRule()` (see
- * `injectSx` below).
+ * Pure apart from a dev-only deprecation warning; no DOM access. Order: base
+ * (non-responsive) rules for every selector encountered (outer class first,
+ * then each `&`-selector in declaration order), followed by
+ * `@media (min-width: …)` blocks in ascending breakpoint order. Each media
+ * block is ONE rule string containing its inner selector rules concatenated
+ * as plain text — that concatenation is safe (and required) because a single
+ * `insertRule()` call for an `@media {...}` block is one rule; only top-level
+ * rule concatenation breaks `insertRule()` (see `injectSx` below).
  */
 export declare function resolveSx(sx: SxObject, className: string): string[];
 /** Deterministic class name for an sx object — identical objects (by value) share one class/hash. */
@@ -67,3 +163,4 @@ export declare function sxClassName(sx: SxObject): string;
 export declare function injectSx(sx: SxObject): string;
 /** @internal test-only — clears the injection cache and managed stylesheet between test runs. */
 export declare function __resetBoxSxForTests(): void;
+export {};

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

@@ -16,9 +16,12 @@
  * keys, not raw hex/px. Prefer named layout primitives over ad-hoc flex.
  *
  * `sx` is a deliberate SUBSET of MUI's sx — not all of CSS-in-JS is a feature:
- *   - Spacing shorthands (m/p/gap family) resolve numbers off the 4px HDS scale
- *     (`--primitive-space-<n>`) and named steps ('tight'|'normal'|'inset'|'spacious')
- *     off `--semantic-space-layout-*`.
+ *   - Spacing shorthands (m/p/gap family) take the t-shirt scale
+ *     ('xs'|'sm'|'md'|'lg'|'xl' → `--semantic-space-scale-*`, hds#206) through the
+ *     resolver Stack's `gap` shares. Numbers still resolve as a count of 4px units
+ *     (`p: 4` is 16px), and the deprecated 'tight'|'normal'|'inset'|'spacious' still
+ *     read `--semantic-space-layout-*`, fixed px that compact density does not
+ *     remap. HDS source may not use raw integers (check-spacing-vocabulary).
  *   - `color`/`bgcolor`/`borderColor`/`fill`/`stroke` resolve dotted token keys
  *     ('content.primary', 'surface.raised', 'border.subtle', 'accent',
  *     'accent.hover', 'feedback.success', …) to the matching semantic CSS var.

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

@@ -9,9 +9,6 @@
  * @figma https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=86-159
  */
 import * as React from 'react';
-declare const crumbLabelVariants: (props?: ({
-    current?: boolean | null | undefined;
-} & import("class-variance-authority/dist/types").ClassProp) | undefined) => string;
 /** @public */
 export interface BreadcrumbItem {
     /** Visible label for the crumb. */
@@ -32,5 +29,3 @@ export interface BreadcrumbProps extends Omit<React.HTMLAttributes<HTMLElement>,
  * is marked aria-current="page".
  */
 export declare const Breadcrumb: React.ForwardRefExoticComponent<BreadcrumbProps & React.RefAttributes<HTMLElement>>;
-/** @internal — CVA variant helper; compose via Breadcrumb instead. */
-export { crumbLabelVariants };

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

@@ -7,6 +7,30 @@
  */
 import * as React from 'react';
 import { type VariantProps } from 'class-variance-authority';
+/**
+ * Pressed state (hds#322): an inset box-shadow wash bound to
+ * `role.pressed-overlay` (`semantic.color.state.pressed.overlay`: black in
+ * light, white in dark; the 5% alpha lives in the class, like `bg-scrim/60`),
+ * not the brightness filter it replaces (95% in light, 110% in dark), which
+ * had no token behind it and no Figma equivalent. Why an inset shadow and not
+ * a pseudo-element: Tailwind v4 composes `--tw-inset-shadow` with the
+ * `focus-visible:ring-*` and any consumer `shadow-*` into one `box-shadow`
+ * list, so the focus ring, an outer shadow and the press wash all render at
+ * once with no `relative`/`after:` classes and no extra DOM; the
+ * `inset-shadow-[0_0_0_9999px]` spread fills the padding box, so it works on
+ * a transparent tertiary fill and respects the radius. `disabled:pointer-events-none`
+ * keeps a disabled control from ever matching `:active`. The wash snaps on
+ * and off (`transition-[colors,filter]` is unchanged: the tone variants still
+ * hover through the brightness filter), which is also how the Figma Pressed
+ * variant behaves. Without `color-mix()` support the fallback is the opaque
+ * token, the same fallback Tailwind emits for `bg-scrim/60`.
+ *
+ * Toggled on (`pressed`, hds#393) is a different state from that momentary
+ * wash: `data-pressed="true"` fills with `role.accent` and its foreground,
+ * the on-state a toggle needs, so it reads as on at rest, not only mid-click.
+ * Only toggle buttons get these classes, so every other Button renders the
+ * same markup as before.
+ */
 declare const buttonVariants: (props?: ({
     variant?: "primary" | "secondary" | "tertiary" | null | undefined;
     tone?: "success" | "danger" | "warning" | "info" | "neutral" | null | undefined;
@@ -26,17 +50,22 @@ export interface ButtonProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonE
     iconLeft?: React.ReactNode;
     /** Trailing icon rendered after the label. */
     iconRight?: React.ReactNode;
-    /** Render the button as a square icon-only control. Requires aria-label. */
+    /** Render a square icon-only control; `label` becomes its aria-label. */
     iconOnly?: boolean;
     /** Disable interaction. Mirrors the native HTML attribute. */
     disabled?: boolean;
+    /** Make it a toggle button (aria-pressed), controlled. */
+    pressed?: boolean;
+    /** Initial toggle state when `pressed` is not set. */
+    defaultPressed?: boolean;
+    /** Called with the next pressed state on click. */
+    onPressedChange?: (pressed: boolean) => void;
 }
 /**
  * Triggers an action when activated.
- * @usage Trigger an action (submit, save, open a dialog) with a text label and optional icons; for an icon-only control pass iconOnly with iconLeft.
+ * @usage Trigger an action (submit, save, open a dialog) with a text label and optional icons; for an icon-only control pass iconOnly with iconLeft and label; for an on/off toggle pass pressed.
  * @whenNot Navigating to another page, where a link is the correct element.
  * @useInstead InlineLink navigation to another page
  */
 export declare const Button: React.ForwardRefExoticComponent<ButtonProps & React.RefAttributes<HTMLButtonElement>>;
-/** @internal — CVA variant helper; compose via Button props instead. */
-export { buttonVariants };
+export {};

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

@@ -51,11 +51,6 @@ type GapOption = 'tight' | 'normal' | 'inset' | 'spacious' | keyof typeof hds.sp
 export type CardVariant = 'default' | 'accent';
 /** @public */
 export type CardTone = 'neutral' | 'danger' | 'success' | 'warning' | 'info';
-declare const cardVariants: (props?: ({
-    variant?: "default" | "accent" | null | undefined;
-    tone?: "success" | "danger" | "warning" | "info" | "neutral" | null | undefined;
-    bordered?: boolean | null | undefined;
-} & import("class-variance-authority/dist/types").ClassProp) | undefined) => string;
 /** @public */
 export interface CardProps extends React.HTMLAttributes<HTMLDivElement> {
     /** Render-as element for the root wrapper. */
@@ -79,6 +74,12 @@ export interface CardProps extends React.HTMLAttributes<HTMLDivElement> {
      *  legibility. Default false — repeated cards in grids should stay
      *  borderless and rely on whitespace, rails, or section dividers. */
     bordered?: boolean;
+    /** Make the card one checkbox-like option (role="checkbox"): click or Space toggles it, Enter does not. A click on a control inside it is left to that control. */
+    selectable?: boolean;
+    /** Whether a selectable card is selected. Controlled: pair with onSelectedChange. */
+    selected?: boolean;
+    /** Called with the next selected state when a selectable card is toggled. */
+    onSelectedChange?: (selected: boolean) => void;
 }
 interface CardComponent extends React.ForwardRefExoticComponent<CardProps & React.RefAttributes<HTMLDivElement>> {
     Header: typeof CardHeader;
@@ -138,12 +139,10 @@ declare const CardMetric: React.ForwardRefExoticComponent<CardMetricProps & Reac
  * Tagged per-export, not on the file block: this module exports eight
  * components and a file-level @figma would hand all eight this one node.
  * @figma https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=39-11
- * @usage Group related content on a raised surface with header, body, footer and metric slots.
+ * @usage Group related content on a raised surface with header, body, footer and metric slots, or as one selectable option.
  * @whenNot A bare padded background with no slot anatomy, or a single headline figure.
  * @useInstead Surface a padded background without slot anatomy
  * @useInstead Card.Metric a single headline figure
  */
 export declare const Card: CardComponent;
 export { CardHeader, CardTitle, CardDescription, CardBody, CardFooter, CardProgress, CardMetric };
-/** @internal — CVA variant helper; compose via Card props instead. */
-export { cardVariants };

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

@@ -1,22 +1,23 @@
 /**
- * Combobox — searchable single-select (Popover + filtered listbox).
+ * Combobox — searchable single- or multi-select (Popover + filtered listbox).
  * @category Inputs
  * @tier pattern
- * @usage Pick one value from a long list of options, with a search field that filters as you type.
+ * @usage Pick one value, or several with `multiple`, from a long list of options, with a search field that filters as you type.
  * @whenNot A short list that needs no search, or an action list.
  * @useInstead Select a short list without search
  * @useInstead Menu firing actions from a trigger
  * @keyboard Enter/Space Opens the list from the trigger and moves focus to the search field.
  * @keyboard ArrowDown/ArrowUp Moves the active option and wraps at the ends.
  * @keyboard Character Filters the options to those matching the typed text.
- * @keyboard Enter Commits the active option and closes the list.
+ * @keyboard Enter Commits the active option and closes the list; with `multiple`, toggles it and keeps the list open.
  * @keyboard Escape Closes the list.
  * @keyboard Tab Stays inside the open list.
  * @figma https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=82-237
  * @doc-exempt: no Inputs-overlay doc page yet — add demo when created
  *
  * A select-with-search built on the HDS Popover. The trigger shows the current
- * selection; opening reveals a search field that filters the option list.
+ * selection (with `multiple`, a count and a removable chip per value); opening
+ * reveals a search field that filters the option list.
  * Full keyboard support (↑/↓ to move, Enter to choose, Esc/outside-click to
  * close) and listbox/option ARIA. Controlled via `value` + `onChange`.
  *
@@ -34,14 +35,10 @@ export interface ComboboxOption {
     label: string;
     disabled?: boolean;
 }
-/** @public */
-export interface ComboboxProps {
+/** Props both arms share; consumers name an arm or `ComboboxAnyProps`. */
+interface ComboboxBaseProps {
     /** Selectable options. */
     options: ComboboxOption[];
-    /** Currently selected value, or null when nothing is chosen. */
-    value: string | null;
-    /** Fired with the chosen option's value. */
-    onChange: (value: string) => void;
     /** Trigger text when nothing is selected. */
     placeholder?: string;
     /** Placeholder for the search field. */
@@ -50,8 +47,47 @@ export interface ComboboxProps {
     emptyMessage?: string;
     /** Accessible label for the trigger (when not labelled by a <Field>). */
     'aria-label'?: string;
+    /**
+     * Id of the trigger, so a `<label for>` names it. `FormField` sets it, with
+     * `aria-describedby` and `aria-invalid`.
+     */
+    id?: string;
+    /** Ids of the elements that describe the trigger (helper text, error). */
+    'aria-describedby'?: string;
+    /** Marks the trigger invalid, for example while the field shows an error. */
+    'aria-invalid'?: boolean;
     className?: string;
     disabled?: boolean;
 }
+/**
+ * Single-select: one value, or none.
+ * @public
+ */
+export interface ComboboxProps extends ComboboxBaseProps {
+    /** Leave unset (or false) to pick one value. */
+    multiple?: false;
+    /** Currently selected value, or null when nothing is chosen. */
+    value: string | null;
+    /** Fired with the chosen option's value. */
+    onChange: (value: string) => void;
+}
+/**
+ * Multi-select (`multiple`): any number of values.
+ * @public
+ */
+export interface ComboboxMultipleProps extends ComboboxBaseProps {
+    /** Pick any number of values. */
+    multiple: true;
+    /** Currently selected values, in the order they were picked. */
+    value: readonly string[];
+    /** Fired with the next selected values whenever one is added or removed. */
+    onChange: (value: string[]) => void;
+}
+/**
+ * Either arm: single-select `ComboboxProps` or `ComboboxMultipleProps`.
+ * @public
+ */
+export type ComboboxAnyProps = ComboboxProps | ComboboxMultipleProps;
 /** @public */
-export declare const Combobox: React.ForwardRefExoticComponent<ComboboxProps & React.RefAttributes<HTMLButtonElement>>;
+export declare const Combobox: React.ForwardRefExoticComponent<ComboboxAnyProps & React.RefAttributes<HTMLButtonElement>>;
+export {};

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

@@ -15,8 +15,8 @@
  * 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.
+ * rhythm. For a horizontal gutter, which Container does not support, put a
+ * Box with `style={{ paddingInline }}` inside it.
  *
  * Centers content horizontally and applies semantic max-width constraints.
  * - maxWidth options: 'content' (760px prose) | 'max' (1200px full layout)

package/dist/types/src/app/components/data-table-section.d.ts

@@ -12,7 +12,7 @@ export interface DataTableSectionRow {
     /** One node per column, in column order. */
     cells: React.ReactNode[];
     /**
-     * Row actions (a `Button` group, a `Menu` trigger, `IconButton`s). Rendered in a
+     * Row actions (a `Button` group, a `Menu` trigger, icon-only `Button`s). Rendered in a
      * trailing column; the pattern bakes in no icon.
      */
     actions?: React.ReactNode;

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

@@ -81,11 +81,17 @@ interface DialogComponent extends React.FC<DialogProps> {
  * and a file-level @figma would hand all ten this one node.
  * @usage Interrupt the page with a modal that needs a decision or focused input before people continue.
  * @whenNot A preview on hover, a message that needs no reply, or content that can stay inline.
- * @useInstead HoverCard a preview on hover or focus
+ * @useInstead Tooltip a short hint on hover or focus
  * @useInstead Alert a message that needs no reply
  * @useInstead ToastProvider a brief confirmation
  * @slot trigger The element that opens the dialog (Dialog.Trigger).
+ * @slot overlay The scrim that dims the page behind the dialog (Dialog.Overlay).
  * @slot surface The modal surface (Dialog.Content).
+ * @slot header Groups the title and description (Dialog.Header).
+ * @slot title The heading that names the dialog (Dialog.Title).
+ * @slot description Supporting text announced with the title (Dialog.Description).
+ * @slot footer The row of actions (Dialog.Footer).
+ * @slot close The button that closes the dialog (Dialog.Close, or the X built into Dialog.Content).
  * @keyboard Enter/Space Opens the dialog from the trigger and moves focus inside it.
  * @keyboard Escape Closes the dialog and returns focus to the trigger.
  * @keyboard Tab Cycles focus inside the open dialog.

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

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

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

@@ -24,5 +24,4 @@ export interface FieldProps extends Omit<React.HTMLAttributes<HTMLDivElement>, '
  * Caption label paired with a value — used in metadata grids and read-only forms.
  */
 export declare const Field: React.ForwardRefExoticComponent<FieldProps & React.RefAttributes<HTMLDivElement>>;
-/** @internal — CVA variant helper; compose via Field props instead. */
-export { fieldValueVariants };
+export {};

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

@@ -7,13 +7,14 @@
  * @useInstead Stack a single row or column
  * @useInstead Box one-off layout that no named primitive covers
  * @ai-intent Solves multi-column layout and repeatable alignment with token-governed gaps, responsive column collapse, and a first-class subgrid escape hatch for nested structure.
- * @ai-rules Use Grid for spatial layout, not for surface styling or content padding. Do NOT apply background, border, or internal padding directly to Grid to mimic a card. Do NOT use arbitrary CSS grid templates when fixed, auto-fit, or subgrid modes already express the layout. Do NOT use Grid for simple one-dimensional stacks where Stack is sufficient.
+ * @ai-rules Use Grid for spatial layout, not for surface styling or content padding. Do NOT apply background, border, or internal padding directly to Grid to mimic a card. Do NOT use arbitrary CSS grid templates when fixed, auto-fit, auto-fill, or subgrid modes already express the layout. Do NOT use Grid for simple one-dimensional stacks where Stack is sufficient.
  *
  * Enforces semantic gap and column values. No arbitrary CSS grid.
  * - layout='fixed':   responsive base (collapses via CSS at tablet/mobile).
  *                     `columns` sets desktop count (default 12). Tablet/mobile
  *                     clamp to min(8, cols) and min(4, cols) respectively.
  * - layout='auto-fit': responsive card wrapping via auto-fit.
+ * - layout='auto-fill': tile wrapping at `minItemWidth` (TileGrid's recipe; 0.20.0 removed TileGrid).
  * - subgrid=true:     sets gridTemplateColumns:'subgrid' for nested alignment.
  *
  * Usage (default responsive 12-col):
@@ -29,16 +30,19 @@
  *   </Grid>
  */
 import React, { type ReactNode, type CSSProperties } from 'react';
-type SemanticGap = 'tight' | 'normal' | 'inset' | 'spacious';
-type GridLayout = 'fixed' | 'auto-fit';
-export interface GridProps {
+type SemanticGap = 'medium' | 'tight' | 'normal' | 'inset' | 'spacious';
+type GridLayout = 'fixed' | 'auto-fit' | 'auto-fill';
+/** Grid's own props, plus any HTML attribute (role, aria-*, id) for its root element. */
+export interface GridProps extends React.HTMLAttributes<HTMLDivElement> {
     /** Grid content. */
     children: ReactNode;
-    /** Grid layout mode: 'fixed' (responsive) or 'auto-fit' (card wrapping). Defaults to 'fixed'. */
+    /** Grid layout mode: 'fixed' (responsive), 'auto-fit' (card wrapping) or 'auto-fill' (tile wrapping that keeps empty tracks). Defaults to 'fixed'. */
     layout?: GridLayout;
+    /** Minimum item width before 'auto-fit' or 'auto-fill' wraps, capped at the container width. Defaults to 280px. */
+    minItemWidth?: string;
     /** Desktop column count for layout='fixed'. Tablet clamps to min(8,n), mobile to min(4,n). Defaults to 12. */
     columns?: number;
-    /** Gap between grid items: semantic only. Defaults to 'inset' (32px). */
+    /** Gap between grid items: semantic only. 'medium' is a fixed 12px. Defaults to 'inset' (32px). */
     gap?: SemanticGap;
     /** If true, sets gridTemplateColumns:'subgrid' for nested grid alignment. */
     subgrid?: boolean;

package/dist/types/src/app/components/hds-tooltip.d.ts

@@ -2,6 +2,7 @@
  * Tooltip — accessible hover/focus tooltip on Radix (Overlays).
  * @category Overlays
  * @tier primitive
+ * @figma https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=93-15
  * @doc-exempt: no Overlays doc page yet — add demo when the overlays page is created
  *
  * Radix Tooltip (@radix-ui/react-tooltip) themed with role tokens. Provides
@@ -12,7 +13,7 @@
  *
  *   <Tooltip>
  *     <Tooltip.Trigger asChild>
- *       <IconButton icon={Link} aria-label="Copy link" />
+ *       <Button iconOnly label="Copy link" iconLeft={<Icon icon={Link} />} />
  *     </Tooltip.Trigger>
  *     <Tooltip.Content>Copy link</Tooltip.Content>
  *   </Tooltip>
@@ -21,7 +22,9 @@
  * content text (semantic.color.content.inverse) — these are a designed pair, so
  * the bubble reads correctly in BOTH themes (dark bubble/light text in light
  * mode, light bubble/dark text in dark mode). Radius 4 (primitive.radius.4),
- * shadow-overlay, and a matching arrow. Text reuses the caption type composite.
+ * shadow-floating (semantic.elevation.floating, the popover and dropdown
+ * shadow; shadow-overlay is for dialogs), and a matching arrow. Text reuses the
+ * caption type composite.
  */
 import * as React from 'react';
 import * as TooltipPrimitive from '@radix-ui/react-tooltip';
@@ -51,6 +54,13 @@ interface HdsTooltipComponent extends React.FC<React.ComponentProps<typeof Toolt
  * Tooltip root. Bakes in the Radix Provider so a single `<Tooltip>` is
  * self-contained — no app-level provider required. Controlled via
  * `open`/`onOpenChange`, or uncontrolled with `defaultOpen`.
+ * @usage Name an icon-only control, or add a short hint that appears on hover and keyboard focus.
+ * @whenNot Anything interactive, text people need to finish a task, or a hint touch users must see (touch has no hover).
+ * @useInstead Popover interactive or longer content that opens on click
+ * @useInstead Text a hint that must stay visible
+ * @keyboard Focus Opens the tooltip when the trigger receives keyboard focus.
+ * @keyboard Escape Closes the tooltip and keeps focus on the trigger.
+ * @keyboard Tab Moves on to the next control and closes the tooltip.
  * @public
  */
 declare const Tooltip: HdsTooltipComponent;