@hirobius/design-system 0.18.0 → 0.19.1

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

@@ -30,7 +30,15 @@ declare const AlertDialogPortal: React.FC<AlertDialogPrimitive.AlertDialogPortal
 declare const AlertDialogAction: React.ForwardRefExoticComponent<AlertDialogPrimitive.AlertDialogActionProps & React.RefAttributes<HTMLButtonElement>>;
 declare const AlertDialogCancel: React.ForwardRefExoticComponent<AlertDialogPrimitive.AlertDialogCancelProps & React.RefAttributes<HTMLButtonElement>>;
 declare const AlertDialogOverlay: React.ForwardRefExoticComponent<Omit<AlertDialogPrimitive.AlertDialogOverlayProps & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
-declare const AlertDialogContent: React.ForwardRefExoticComponent<Omit<AlertDialogPrimitive.AlertDialogContentProps & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
+/** @public */
+export interface AlertDialogContentProps extends React.ComponentPropsWithoutRef<typeof AlertDialogPrimitive.Content> {
+    /**
+     * Element to portal into. Defaults to the nearest `data-hds` scope, so the
+     * overlay inherits its theme; pass `null` to use `document.body`.
+     */
+    container?: HTMLElement | null;
+}
+declare const AlertDialogContent: React.ForwardRefExoticComponent<AlertDialogContentProps & React.RefAttributes<HTMLDivElement>>;
 declare const AlertDialogHeader: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & React.RefAttributes<HTMLDivElement>>;
 declare const AlertDialogFooter: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & React.RefAttributes<HTMLDivElement>>;
 declare const AlertDialogTitle: React.ForwardRefExoticComponent<Omit<AlertDialogPrimitive.AlertDialogTitleProps & React.RefAttributes<HTMLHeadingElement>, "ref"> & React.RefAttributes<HTMLHeadingElement>>;

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

@@ -2,6 +2,10 @@
  * Alert - compact feedback surface with contextual severity.
  * @category Feedback
  * @tier primitive
+ * @usage Show a persistent inline message with a severity, next to the content it concerns.
+ * @whenNot A brief confirmation that should disappear on its own, or a status label.
+ * @useInstead ToastProvider a brief confirmation that fades away
+ * @useInstead Badge a short status label
  * @figma https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=33-34
  */
 import React from 'react';

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

@@ -2,6 +2,10 @@
  * Avatar - user or entity image with an initials fallback.
  * @category Display
  * @tier primitive
+ * @usage Show a person or entity as an image with an initials fallback.
+ * @whenNot A generic pictogram, or a status marker.
+ * @useInstead Icon a generic pictogram
+ * @useInstead Badge a status marker
  * @figma https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=34-18
  */
 import * as React from 'react';

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

@@ -2,6 +2,10 @@
  * 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.
+ * @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
  * @figma https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=31-15
  */
 import * as React from 'react';

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

@@ -2,6 +2,11 @@
  * Box — polymorphic layout primitive with a token-first `sx` engine.
  * @category Layout
  * @tier primitive
+ * @usage Build one-off layout that no named layout primitive covers, using token keys through `sx`.
+ * @whenNot Ordinary vertical or horizontal spacing, columns, or page-width constraint.
+ * @useInstead Stack a row or column of content with even gaps
+ * @useInstead Grid multi-column layout
+ * @useInstead Container a width-constrained page region
  * @ai-intent Provides one narrow escape hatch for genuinely one-off layout that no
  * named primitive covers, without inviting ad hoc inline styles or raw hex/px values
  * back into the system — the `sx` engine only accepts HDS token keys and a small,

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

@@ -2,6 +2,10 @@
  * Breadcrumb - hierarchical navigation trail.
  * @category Navigation
  * @tier pattern
+ * @usage Show where the current page sits in a hierarchy and link back up it.
+ * @whenNot Switching between sibling views, or stepping through pages of results.
+ * @useInstead Tabs switching between sibling views
+ * @useInstead Pagination stepping through pages of results
  * @figma https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=86-159
  */
 import * as React from 'react';

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

@@ -2,6 +2,10 @@
  * ButtonGroup — attaches Button children into one segmented control.
  * @category Actions
  * @tier primitive
+ * @usage Attach related Buttons into one segmented row or column that reads as a single control.
+ * @whenNot Buttons that are unrelated, or choosing one of several views.
+ * @useInstead SegmentedControl choosing one of several views
+ * @useInstead Stack loosely spaced buttons
  */
 import * as React from 'react';
 import { type VariantProps } from 'class-variance-authority';

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

@@ -33,6 +33,9 @@ export interface ButtonProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonE
 }
 /**
  * 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.
+ * @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. */

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

@@ -128,11 +128,20 @@ export interface CardMetricProps extends React.HTMLAttributes<HTMLDivElement> {
     /** Tone for the value — applies semantic color. Defaults to neutral. */
     tone?: CardTone;
 }
+/**
+ * Card.Metric — one uppercase label, a large value and an optional sub-line inside a Card.
+ * @usage Show one headline figure (a KPI, a count, a total) with its label inside a Card.
+ * @whenNot A metric outside a Card, or several figures that share one label.
+ */
 declare const CardMetric: React.ForwardRefExoticComponent<CardMetricProps & React.RefAttributes<HTMLDivElement>>;
 /**
  * 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.
+ * @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 };

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

@@ -2,6 +2,10 @@
  * Checkbox — custom-drawn checkbox with check / indeterminate glyph.
  * @category Inputs
  * @tier primitive
+ * @usage Let people tick one or more independent options, or a parent choice that is partly selected.
+ * @whenNot An immediate on/off setting, or a choice of exactly one option from a set.
+ * @useInstead Toggle a setting that applies as soon as it flips
+ * @useInstead Radio exactly one choice from a set
  * @figma https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=35-29
  */
 import type { InputHTMLAttributes } from 'react';

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

@@ -2,6 +2,16 @@
  * Combobox — searchable single-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.
+ * @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 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
  *

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

@@ -39,6 +39,8 @@ export interface CommandPaletteProps {
  * 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>>;
+export declare const CommandPalette: React.ForwardRefExoticComponent<CommandPaletteProps & React.RefAttributes<HTMLInputElement>> & {
+    displayName: string;
+};
 /** @internal — CVA variant helpers; compose via CommandPalette instead. */
 export { cmdkRowVariants, cmdkKindBadgeVariants, cmdkDescriptionVariants };

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

@@ -2,6 +2,11 @@
  * Container — semantic width-constrained layout.
  * @category Layout
  * @tier primitive
+ * @usage Constrain a page region to the content or maximum width and centre it.
+ * @whenNot Spacing between siblings, columns, or a surface with padding.
+ * @useInstead Stack spacing between siblings
+ * @useInstead Grid columns
+ * @useInstead Box one-off layout that no named primitive covers
  * @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.

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

@@ -2,6 +2,17 @@
  * ContextMenu — right-click context menu on Radix ContextMenu.
  * @category Overlays
  * @tier primitive
+ * @usage Offer actions for an item on right-click, or the equivalent keyboard gesture.
+ * @whenNot The only way to reach an action, or actions from a visible trigger.
+ * @useInstead Menu actions from a visible trigger
+ * @slot trigger The area that opens the menu on right-click (ContextMenu.Trigger).
+ * @slot content The popup holding the items (ContextMenu.Content).
+ * @keyboard ArrowDown/ArrowUp Moves the highlight and stops at the first and last item.
+ * @keyboard End Jumps to the last item.
+ * @keyboard Character Highlights the next item that starts with the typed letter.
+ * @keyboard Enter Selects the highlighted item and closes the menu.
+ * @keyboard Escape Closes the menu without leaving focus inside the removed content.
+ * @keyboard Tab Does not leave the open menu.
  * @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
@@ -24,14 +35,26 @@ declare const ContextMenuTrigger: React.ForwardRefExoticComponent<ContextMenuPri
 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 ContextMenuContent: React.ForwardRefExoticComponent<Omit<ContextMenuPrimitive.ContextMenuContentProps & React.RefAttributes<HTMLDivElement>, "ref"> & {
+    /**
+     * Element to portal into. Defaults to the nearest `data-hds` scope, so the
+     * overlay inherits its theme; pass `null` to use `document.body`.
+     */
+    container?: HTMLElement | null;
+} & 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>>;
+declare const ContextMenuSubContent: React.ForwardRefExoticComponent<Omit<ContextMenuPrimitive.ContextMenuSubContentProps & React.RefAttributes<HTMLDivElement>, "ref"> & {
+    /**
+     * Element to portal into. Defaults to the nearest `data-hds` scope, so the
+     * overlay inherits its theme; pass `null` to use `document.body`.
+     */
+    container?: HTMLElement | null;
+} & React.RefAttributes<HTMLDivElement>>;
 interface ContextMenuComponent extends React.FC<React.ComponentProps<typeof ContextMenuPrimitive.Root>> {
     Trigger: typeof ContextMenuTrigger;
     Content: typeof ContextMenuContent;

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

@@ -0,0 +1,45 @@
+/**
+ * DataTableSection - a titled table with a toolbar, row actions and an empty state.
+ * @category Display
+ * @tier pattern
+ */
+import * as React from 'react';
+import { type TableColumn } from './table.js';
+/** @public */
+export interface DataTableSectionRow {
+    /** Stable row key. */
+    key: string;
+    /** One node per column, in column order. */
+    cells: React.ReactNode[];
+    /**
+     * Row actions (a `Button` group, a `Menu` trigger, `IconButton`s). Rendered in a
+     * trailing column; the pattern bakes in no icon.
+     */
+    actions?: React.ReactNode;
+}
+/** @public */
+export interface DataTableSectionProps extends Omit<React.HTMLAttributes<HTMLElement>, 'title'> {
+    /** Section heading. */
+    title: React.ReactNode;
+    /** Toolbar beside the heading: a search field, a filter, an "Add" button. */
+    toolbar?: React.ReactNode;
+    /** Data columns, in order. Do not include the actions column; it is added for you. */
+    columns: TableColumn[];
+    /** Data rows. An empty array renders the empty state instead of the table. */
+    rows: DataTableSectionRow[];
+    /** Header of the trailing actions column. Defaults to "Actions". */
+    actionsLabel?: string;
+    /** Empty-state message when there are no rows. Defaults to "Nothing here yet". */
+    emptyTitle?: React.ReactNode;
+    /** Optional supporting line under the empty-state message. */
+    emptyDescription?: React.ReactNode;
+    /** Heading element for the title. Changes the DOM element only. Defaults to 2. */
+    level?: 2 | 3 | 4 | 5 | 6;
+}
+/**
+ * Section heading and toolbar over a `Table`. Row actions are consumer nodes in a
+ * trailing column, the table scrolls horizontally on narrow widths without a
+ * `minWidth` from the caller, and zero rows shows an `EmptyState`.
+ * @screenPattern
+ */
+export declare const DataTableSection: React.ForwardRefExoticComponent<DataTableSectionProps & React.RefAttributes<HTMLElement>>;

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

@@ -0,0 +1,32 @@
+/**
+ * DestructiveSection - the one place a screen puts an irreversible action.
+ * @category Actions
+ * @tier pattern
+ */
+import * as React from 'react';
+/** @public */
+export interface DestructiveSectionProps extends Omit<React.HTMLAttributes<HTMLElement>, 'title'> {
+    /** What the zone does, as a short action ("Archive client"). Also the dialog title. */
+    title: React.ReactNode;
+    /** What happens and what is kept. One or two plain sentences. */
+    description: React.ReactNode;
+    /** Label of the danger button that opens the confirmation. Defaults to `confirmLabel`. */
+    actionLabel?: React.ReactNode;
+    /** Label of the confirm button inside the dialog. Name the action ("Archive client"). */
+    confirmLabel: string;
+    /** Body of the confirmation dialog: the consequence, stated plainly. */
+    confirmBody: React.ReactNode;
+    /** Called once, only when the dialog's confirm button is pressed. */
+    onConfirm: () => void;
+    /** Label of the dialog's cancel button. Defaults to "Cancel". */
+    cancelLabel?: string;
+    /** Heading element for the title. Changes the DOM element only. Defaults to 2. */
+    level?: 2 | 3 | 4 | 5 | 6;
+}
+/**
+ * Titled danger zone: a title, an explanation, and one danger `Button` that
+ * opens an `AlertDialog`. Pressing the button never runs the action; only the
+ * dialog's confirm does. Place it last on the screen, below the form.
+ * @screenPattern
+ */
+export declare const DestructiveSection: React.ForwardRefExoticComponent<DestructiveSectionProps & React.RefAttributes<HTMLElement>>;

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

@@ -28,8 +28,10 @@
  *
  * Surface uses role.popover (semantic.color.surface.overlay) +
  * shadow-overlay (semantic.shadow.overlay from 8e-1). The scrim is
- * a foreground/80 wash so it picks up the theme without a hardcoded
- * black. The close affordance is rendered as an absolutely-positioned
+ * role.scrim (semantic.color.surface.scrim) at 60% alpha: dark in both
+ * themes, black in dark mode. The overlay portals into the nearest
+ * `data-hds` scope so it inherits the active theme; pass `container` to
+ * override. The close affordance is rendered as an absolutely-positioned
  * X inside Content; pass `hideClose` to opt out for fully-custom layouts.
  */
 import * as React from 'react';
@@ -42,6 +44,11 @@ declare const DialogOverlay: React.ForwardRefExoticComponent<Omit<DialogPrimitiv
 export interface DialogContentProps extends React.ComponentPropsWithoutRef<typeof DialogPrimitive.Content> {
     /** Hide the built-in close affordance. Useful for fully custom layouts. */
     hideClose?: boolean;
+    /**
+     * Element to portal into. Defaults to the nearest `data-hds` scope, so the
+     * overlay inherits its theme; pass `null` to use `document.body`.
+     */
+    container?: HTMLElement | null;
 }
 declare const DialogContent: React.ForwardRefExoticComponent<DialogContentProps & React.RefAttributes<HTMLDivElement>>;
 declare const DialogHeader: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & React.RefAttributes<HTMLDivElement>>;
@@ -72,6 +79,17 @@ interface DialogComponent extends React.FC<DialogProps> {
 /**
  * Tagged per-export, not on the file block: this module exports ten components
  * 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 Alert a message that needs no reply
+ * @useInstead ToastProvider a brief confirmation
+ * @slot trigger The element that opens the dialog (Dialog.Trigger).
+ * @slot surface The modal surface (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.
+ * @keyboard Shift+Tab Cycles focus backwards inside the open dialog.
  * @figma https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=93-27
  */
 export declare const Dialog: DialogComponent;

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

@@ -2,6 +2,9 @@
  * Disclosure - compact disclosure surface for optional explanatory content.
  * @category Layout
  * @tier pattern
+ * @usage Hide optional explanatory content behind a heading that people can expand.
+ * @whenNot Content people must see, or switching between panels.
+ * @useInstead Tabs switching between panels of content
  * @figma https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=88-453
  */
 import React, { type CSSProperties, type ReactNode } from 'react';

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

@@ -2,6 +2,10 @@
  * Divider — semantic separator between content regions.
  * @category Layout
  * @tier primitive
+ * @usage Separate two regions of content with a thin semantic rule.
+ * @whenNot Spacing alone would do, or the separation needs a container.
+ * @useInstead Stack gap-based spacing between siblings
+ * @useInstead Surface a bounded region with its own background
  * @figma https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=89-26
  */
 import * as React from 'react';

package/dist/types/src/app/components/empty-state.d.ts

@@ -2,6 +2,10 @@
  * EmptyState — consistent no-data placeholder for lists, grids, and sections.
  * @category Display
  * @tier primitive
+ * @usage Say that a list, grid or section has no data yet, with a title and an optional description.
+ * @whenNot Content that is still loading, or a full-page error.
+ * @useInstead Skeleton content that is still loading
+ * @useInstead Alert a message about something that went wrong
  * @figma https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=88-352
  * @ai-intent Inline empty-state placeholder so any list, grid, or section can
  *   communicate "no data yet" with consistent muted typography instead of agents

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

@@ -1,6 +1,10 @@
 /**
  * @category Display
  * @tier primitive
+ * @usage Show a labelled read-only value, such as a name and its value in a detail view.
+ * @whenNot Editable input, or a single headline figure.
+ * @useInstead Input an editable single-line value
+ * @useInstead Card.Metric a headline figure inside a Card
  * @figma https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=85-81
  */
 import * as React from 'react';

package/dist/types/src/app/components/form-actions.d.ts

@@ -0,0 +1,26 @@
+/**
+ * FormActions - the footer row of a form: primary right-most, secondary to its left.
+ * @category Actions
+ * @tier pattern
+ */
+import * as React from 'react';
+/** @public */
+export interface FormActionsProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'children'> {
+    /** The submit action (a primary `Button`). Always last in DOM order and right-most. */
+    primary: React.ReactNode;
+    /** The cancel or back action, placed immediately left of the primary. */
+    secondary?: React.ReactNode;
+    /**
+     * A destructive action (delete, remove). Placed on the far left, apart from the
+     * primary and secondary so a mis-click never lands on it. Never right of the primary.
+     */
+    destructive?: React.ReactNode;
+    /** Pin the row to the bottom of the scroll container. Off by default. */
+    sticky?: boolean;
+}
+/**
+ * Form footer with one fixed order: destructive (far left, if any), then secondary,
+ * then primary last and right-most. Gap is the tight layout token.
+ * @screenPattern
+ */
+export declare const FormActions: React.ForwardRefExoticComponent<FormActionsProps & React.RefAttributes<HTMLDivElement>>;

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

@@ -2,6 +2,10 @@
  * Grid — responsive grid composition primitive.
  * @category Layout
  * @tier primitive
+ * @usage Lay out content in responsive columns with token-governed gaps, or align nested content with subgrid.
+ * @whenNot A single row or column, or styling a surface.
+ * @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.
  *

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

@@ -26,8 +26,20 @@
 import * as React from 'react';
 import * as TooltipPrimitive from '@radix-ui/react-tooltip';
 /** @public */
-export type HdsTooltipContentProps = React.ComponentPropsWithoutRef<typeof TooltipPrimitive.Content>;
-declare const HdsTooltipContent: React.ForwardRefExoticComponent<Omit<TooltipPrimitive.TooltipContentProps & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
+export type HdsTooltipContentProps = React.ComponentPropsWithoutRef<typeof TooltipPrimitive.Content> & {
+    /**
+     * Element to portal into. Defaults to the nearest `data-hds` scope, so the
+     * overlay inherits its theme; pass `null` to use `document.body`.
+     */
+    container?: HTMLElement | null;
+};
+declare const HdsTooltipContent: React.ForwardRefExoticComponent<Omit<TooltipPrimitive.TooltipContentProps & React.RefAttributes<HTMLDivElement>, "ref"> & {
+    /**
+     * Element to portal into. Defaults to the nearest `data-hds` scope, so the
+     * overlay inherits its theme; pass `null` to use `document.body`.
+     */
+    container?: HTMLElement | null;
+} & React.RefAttributes<HTMLDivElement>>;
 interface HdsTooltipComponent extends React.FC<React.ComponentProps<typeof TooltipPrimitive.Root> & {
     /** Hover-open delay in ms (Radix Provider). Default 300. */
     delayDuration?: number;

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

@@ -2,6 +2,15 @@
  * HoverCard — rich preview shown on hover/focus, on Radix HoverCard.
  * @category Overlays
  * @tier primitive
+ * @usage Preview extra detail about a link or mention when it is hovered or focused, without navigating.
+ * @whenNot Content people must reach, or a label for an interactive control.
+ * @useInstead Dialog content people must act on
+ * @useInstead Tooltip a short label for a control
+ * @slot trigger The link or element that opens the card (HoverCard.Trigger).
+ * @slot content The preview (HoverCard.Content).
+ * @keyboard Focus Opens the card when the trigger receives keyboard focus.
+ * @keyboard Escape Closes the card and keeps focus on the trigger.
+ * @keyboard Tab Moves on to the next element and closes the card.
  * @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
@@ -17,7 +26,13 @@
 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>>;
+declare const HoverCardContent: React.ForwardRefExoticComponent<Omit<HoverCardPrimitive.HoverCardContentProps & React.RefAttributes<HTMLDivElement>, "ref"> & {
+    /**
+     * Element to portal into. Defaults to the nearest `data-hds` scope, so the
+     * overlay inherits its theme; pass `null` to use `document.body`.
+     */
+    container?: HTMLElement | null;
+} & React.RefAttributes<HTMLDivElement>>;
 interface HoverCardComponent extends React.FC<React.ComponentProps<typeof HoverCardPrimitive.Root>> {
     Trigger: typeof HoverCardTrigger;
     Content: typeof HoverCardContent;

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

@@ -2,6 +2,10 @@
  * Icon — semantic icon wrapper for Lucide icons.
  * @category Display
  * @tier primitive
+ * @usage Draw a Lucide glyph at a size and colour from the design tokens.
+ * @whenNot A control someone can activate, or a picture that carries content.
+ * @useInstead Button a clickable control, with iconOnly for an icon-only one
+ * @useInstead Avatar a picture of a person or entity
  */
 import React from 'react';
 import type { LucideIcon } from 'lucide-react';

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

@@ -2,6 +2,10 @@
  * InlineLink ” inline navigation and external-link primitive for body copy.
  * @category Navigation
  * @tier primitive
+ * @usage Link to a route or external URL from inside body copy.
+ * @whenNot An action that changes something, or a control that needs button styling.
+ * @useInstead Button an action or a link that needs button styling
+ * @useInstead Text unlinked body copy
  * @figma https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=89-161
  */
 import React from 'react';

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

@@ -2,6 +2,11 @@
  * Input — text field primitive with label, helper, and error slots.
  * @category Inputs
  * @tier primitive
+ * @usage Collect a single line of text, a number, an email or a password, with label, helper and error slots.
+ * @whenNot Multi-line text, or choosing from a fixed list of options.
+ * @useInstead Textarea multi-line text
+ * @useInstead Select a short fixed list
+ * @useInstead Combobox a long fixed list that needs search
  * @figma https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=38-20
  */
 import * as React from 'react';

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

@@ -2,6 +2,9 @@
  * Kbd — inline keyboard key / shortcut hint rendered as a native <kbd>.
  * @category Display
  * @tier primitive
+ * @usage Show a keyboard key or shortcut hint inline, as a native kbd element.
+ * @whenNot Code samples, or a control that runs the shortcut.
+ * @useInstead Text inline code and other typography
  */
 import * as React from 'react';
 import { type VariantProps } from 'class-variance-authority';

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

@@ -26,14 +26,26 @@ declare const MenuTrigger: React.ForwardRefExoticComponent<MenuPrimitive.Dropdow
 declare const MenuGroup: React.ForwardRefExoticComponent<MenuPrimitive.DropdownMenuGroupProps & React.RefAttributes<HTMLDivElement>>;
 declare const MenuRadioGroup: React.ForwardRefExoticComponent<MenuPrimitive.DropdownMenuRadioGroupProps & React.RefAttributes<HTMLDivElement>>;
 declare const MenuSub: React.FC<MenuPrimitive.DropdownMenuSubProps>;
-declare const MenuContent: React.ForwardRefExoticComponent<Omit<MenuPrimitive.DropdownMenuContentProps & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
+declare const MenuContent: React.ForwardRefExoticComponent<Omit<MenuPrimitive.DropdownMenuContentProps & React.RefAttributes<HTMLDivElement>, "ref"> & {
+    /**
+     * Element to portal into. Defaults to the nearest `data-hds` scope, so the
+     * overlay inherits its theme; pass `null` to use `document.body`.
+     */
+    container?: HTMLElement | null;
+} & React.RefAttributes<HTMLDivElement>>;
 declare const MenuItem: React.ForwardRefExoticComponent<Omit<MenuPrimitive.DropdownMenuItemProps & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
 declare const MenuCheckboxItem: React.ForwardRefExoticComponent<Omit<MenuPrimitive.DropdownMenuCheckboxItemProps & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
 declare const MenuRadioItem: React.ForwardRefExoticComponent<Omit<MenuPrimitive.DropdownMenuRadioItemProps & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
 declare const MenuLabel: React.ForwardRefExoticComponent<Omit<MenuPrimitive.DropdownMenuLabelProps & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
 declare const MenuSeparator: React.ForwardRefExoticComponent<Omit<MenuPrimitive.DropdownMenuSeparatorProps & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
 declare const MenuSubTrigger: React.ForwardRefExoticComponent<Omit<MenuPrimitive.DropdownMenuSubTriggerProps & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
-declare const MenuSubContent: React.ForwardRefExoticComponent<Omit<MenuPrimitive.DropdownMenuSubContentProps & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
+declare const MenuSubContent: React.ForwardRefExoticComponent<Omit<MenuPrimitive.DropdownMenuSubContentProps & React.RefAttributes<HTMLDivElement>, "ref"> & {
+    /**
+     * Element to portal into. Defaults to the nearest `data-hds` scope, so the
+     * overlay inherits its theme; pass `null` to use `document.body`.
+     */
+    container?: HTMLElement | null;
+} & React.RefAttributes<HTMLDivElement>>;
 interface MenuComponent extends React.FC<React.ComponentProps<typeof MenuPrimitive.Root>> {
     Trigger: typeof MenuTrigger;
     Content: typeof MenuContent;
@@ -51,6 +63,18 @@ interface MenuComponent extends React.FC<React.ComponentProps<typeof MenuPrimiti
 /**
  * Menu root + parts. Controlled via `open`/`onOpenChange`, or uncontrolled with
  * `defaultOpen`.
+ * @usage Offer a list of actions from a trigger, closed until opened.
+ * @whenNot Choosing one value for a form field, or a set of options that must stay visible.
+ * @useInstead Select choosing a value for a form field
+ * @slot trigger The element that opens the menu (Menu.Trigger).
+ * @slot content The popup holding the items (Menu.Content).
+ * @keyboard Enter/Space/ArrowDown Opens the menu from the trigger and highlights the first item.
+ * @keyboard ArrowDown/ArrowUp Moves the highlight; it stops at the first and last item.
+ * @keyboard Home/End Jumps to the first or last item.
+ * @keyboard Character Highlights the next item that starts with the typed letter.
+ * @keyboard Enter Selects the highlighted item and closes the menu.
+ * @keyboard Escape Closes the menu and returns focus to the trigger.
+ * @keyboard Tab Does not leave the open menu.
  * @public
  */
 declare const Menu: MenuComponent;