@aurora-ds/components 1.4.0 → 1.5.0

package/dist/index.d.ts

@@ -1,4 +1,6 @@
-import { ComponentType, SVGProps, ButtonHTMLAttributes, Ref, FC, AnchorHTMLAttributes, HTMLAttributes, ReactNode, CSSProperties, FormEvent, InputHTMLAttributes, MouseEvent, AriaRole, AriaAttributes } from 'react';
+import * as react from 'react';
+import { ComponentType, SVGProps, ButtonHTMLAttributes, Ref, FC, AnchorHTMLAttributes, ReactNode, HTMLAttributes, CSSProperties, TdHTMLAttributes, ThHTMLAttributes, AriaAttributes, ErrorInfo, Component, FormEvent, InputHTMLAttributes, MouseEvent, AriaRole } from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
 
 declare const lightPalette: {
     surfaceBackground: string;
@@ -28,6 +30,7 @@ declare const lightPalette: {
     borderSubtle: string;
     borderMain: string;
     borderStrong: string;
+    focusRing: string;
     disabledMain: string;
     disabledText: string;
     successMain: string;
@@ -302,6 +305,63 @@ type ButtonProps = ButtonHTMLAttributes<HTMLButtonElement> & {
  */
 declare const Button: FC<ButtonProps>;
 
+/** Semantic color intent of the FAB. */
+type FabColor = ButtonColor;
+/** SVG icon component used by the FAB. */
+type FabIcon = ButtonIcon;
+/** Size token controlling dimensions of the FAB. */
+type FabSize = 'sm' | 'md' | 'lg';
+/** Screen corner where the FAB is anchored when `position` is fixed. */
+type FabPlacement = 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+
+type FabProps = Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'children' | 'aria-label'> & {
+    /** Ref forwarded to the underlying button element. */
+    ref?: Ref<HTMLButtonElement>;
+    /**
+     * Accessible label — required since the FAB may contain only an icon.
+     * @a11y Required — the button's only accessible name when no label is visible. Describe the action (e.g. "Add item").
+     */
+    ariaLabel: string;
+    /** SVG icon component rendered inside the FAB. */
+    icon: FabIcon;
+    /**
+     * Optional text label displayed next to the icon (extended FAB).
+     * When provided the FAB adopts a pill shape.
+     */
+    label?: string;
+    /** Semantic color intent. @default 'primary' */
+    color?: FabColor;
+    /** Size token controlling width, height and icon scale. @default 'md' */
+    size?: FabSize;
+    /**
+     * Screen corner where the FAB is anchored with `position: fixed`.
+     * Set to `undefined` to opt out of fixed positioning (useful for inline placement).
+     * @default 'bottom-right'
+     */
+    placement?: FabPlacement | null;
+    /** Horizontal offset from the placement edge. @default '1.5rem' */
+    offsetX?: string;
+    /** Vertical offset from the placement edge. @default '1.5rem' */
+    offsetY?: string;
+    /** Show a spinner and disable interaction. */
+    isLoading?: boolean;
+    /** Native button type. @default 'button' */
+    type?: 'button' | 'submit' | 'reset';
+};
+
+/**
+ * Floating Action Button (FAB).
+ *
+ * A circular elevated button intended for the primary action of a screen.
+ * Pass a `label` to get an extended (pill-shaped) FAB.
+ *
+ * @example <Fab icon={AddIcon} ariaLabel="Add item" />
+ * @example <Fab icon={AddIcon} ariaLabel="Add item" label="Add" color="success" />
+ * @example <Fab icon={EditIcon} ariaLabel="Edit" placement="bottom-left" />
+ * @example <Fab icon={AddIcon} ariaLabel="Add" placement={null} /> // inline, no fixed positioning
+ */
+declare const Fab: FC<FabProps>;
+
 type IconButtonProps = Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'children' | 'aria-label'> & {
     /** Ref forwarded to the underlying button element. */
     ref?: Ref<HTMLButtonElement>;
@@ -395,6 +455,371 @@ type LinkProps = AnchorHTMLAttributes<HTMLAnchorElement> & {
  */
 declare const Link: FC<LinkProps>;
 
+/** Visual style available for toggle buttons. Intentionally restricted to 2 variants. */
+type ToggleButtonVariant = 'outlined' | 'text';
+
+type ToggleButtonProps = Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'children'> & {
+    /** Ref forwarded to the underlying button element. */
+    ref?: Ref<HTMLButtonElement>;
+    /**
+     * Text label displayed inside the button.
+     * @a11y Recommended — provides the button's accessible name.
+     */
+    label?: string;
+    /** Visual style. @default 'outlined' */
+    variant?: ToggleButtonVariant;
+    /** Semantic color. @default 'primary' */
+    color?: ButtonColor;
+    /** Size token controlling height, padding and font size. @default 'md' */
+    size?: ButtonSize;
+    /** Explicit width for the button. Accepts numbers (px) or any CSS width value. */
+    width?: number | string;
+    /** Flex grow factor applied to the button container. */
+    flexGrow?: number;
+    /** Flex shrink factor applied to the button container. */
+    flexShrink?: number;
+    /**
+     * Controlled active (pressed) state.
+     * When provided the component is in controlled mode.
+     */
+    active?: boolean;
+    /**
+     * Initial active state for uncontrolled mode.
+     * @default false
+     */
+    defaultActive?: boolean;
+    /** Called when the active state changes. */
+    onActiveChange?: (active: boolean) => void;
+    /**
+     * Identifier used by `ToggleGroup` to track which toggle is selected.
+     * Required when used inside a `ToggleGroup`.
+     */
+    value?: string;
+    /** SVG icon component rendered before the label. */
+    startIcon?: ButtonIcon;
+    /** SVG icon component rendered after the label. */
+    endIcon?: ButtonIcon;
+    /** Show a spinner and disable interaction. */
+    isLoading?: boolean;
+    /** Native button type. @default 'button' */
+    type?: 'button' | 'submit' | 'reset';
+};
+
+/**
+ * A toggle button that can be pressed/unpressed (`aria-pressed`).
+ * Supports both **controlled** (`active` + `onActiveChange`) and **uncontrolled**
+ * (`defaultActive`) modes.
+ *
+ * When placed inside a `ToggleGroup`, the group manages mutual exclusivity:
+ * the `value` prop identifies this button within the group.
+ *
+ * @example
+ * // Standalone, uncontrolled
+ * <ToggleButton label="Bold" defaultActive={false} onActiveChange={setBold} />
+ *
+ * @example
+ * // Standalone, controlled
+ * <ToggleButton label="Bold" active={isBold} onActiveChange={setIsBold} />
+ *
+ * @example
+ * // Inside a ToggleGroup
+ * <ToggleGroup defaultValue="md" ariaLabel="Text size">
+ *     <ToggleButton value="sm" label="Small" />
+ *     <ToggleButton value="md" label="Medium" />
+ * </ToggleGroup>
+ */
+declare const ToggleButton: FC<ToggleButtonProps>;
+
+type ToggleIconButtonProps = Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'children' | 'aria-label'> & {
+    /** Ref forwarded to the underlying button element. */
+    ref?: Ref<HTMLButtonElement>;
+    /** SVG icon component to render inside the button. */
+    icon: ButtonIcon;
+    /**
+     * Accessible label — required since there is no visible text.
+     * @a11y Required — the button's only accessible name. Describe the action, not the icon.
+     */
+    ariaLabel: string;
+    /** Visual style. @default 'outlined' */
+    variant?: ToggleButtonVariant;
+    /** Semantic color. @default 'primary' */
+    color?: ButtonColor;
+    /** Size token controlling width, height and padding. @default 'md' */
+    size?: ButtonSize;
+    /** Show a spinner and disable interaction. */
+    isLoading?: boolean;
+    /** Native button type. @default 'button' */
+    type?: 'button' | 'submit' | 'reset';
+    /**
+     * Controlled active (pressed) state.
+     * When provided the component is in controlled mode.
+     */
+    active?: boolean;
+    /**
+     * Initial active state for uncontrolled mode.
+     * @default false
+     */
+    defaultActive?: boolean;
+    /** Called when the active state changes. */
+    onActiveChange?: (active: boolean) => void;
+    /**
+     * Identifier used by `ToggleGroup` to track which toggle is selected.
+     * Required when used inside a `ToggleGroup`.
+     */
+    value?: string;
+};
+
+/**
+ * A square icon-only toggle button that can be pressed/unpressed (`aria-pressed`).
+ * `ariaLabel` is mandatory since there is no visible text.
+ *
+ * Supports both **controlled** (`active` + `onActiveChange`) and **uncontrolled**
+ * (`defaultActive`) modes.
+ *
+ * When placed inside a `ToggleGroup`, the group manages mutual exclusivity:
+ * the `value` prop identifies this button within the group.
+ *
+ * @example
+ * // Standalone, controlled
+ * <ToggleIconButton icon={BoldIcon} ariaLabel="Toggle bold" active={isBold} onActiveChange={setIsBold} />
+ *
+ * @example
+ * // Inside a ToggleGroup (alignment segmented control)
+ * <ToggleGroup value={align} onChange={setAlign} ariaLabel="Text alignment" joined>
+ *     <ToggleIconButton value="left"   icon={AlignLeftIcon}   ariaLabel="Align left" />
+ *     <ToggleIconButton value="center" icon={AlignCenterIcon} ariaLabel="Align center" />
+ *     <ToggleIconButton value="right"  icon={AlignRightIcon}  ariaLabel="Align right" />
+ * </ToggleGroup>
+ */
+declare const ToggleIconButton: FC<ToggleIconButtonProps>;
+
+type ToggleGroupProps = {
+    /** Toggle buttons to render inside the group. */
+    children: ReactNode;
+    /**
+     * Controlled selected value.
+     * When provided the component is in controlled mode.
+     * Pass `null` to express "nothing selected".
+     */
+    value?: string | null;
+    /**
+     * Initial selected value for uncontrolled mode.
+     * @default null
+     */
+    defaultValue?: string | null;
+    /** Called when the selected value changes. */
+    onChange?: (value: string | null) => void;
+    /**
+     * Accessible label for the group.
+     * @a11y Either `ariaLabel` or `ariaLabelledBy` is required.
+     */
+    ariaLabel?: string;
+    /**
+     * ID of an element that labels this group.
+     * @a11y Alternative to `ariaLabel`.
+     */
+    ariaLabelledBy?: string;
+    /**
+     * Layout direction.
+     * @default 'horizontal'
+     */
+    orientation?: 'horizontal' | 'vertical';
+    /**
+     * Visually join the toggle buttons into a single segmented control
+     * (shared borders, no gap, rounded ends only).
+     * @default false
+     */
+    joined?: boolean;
+    /**
+     * Variant applied to all child toggles (overrides their own `variant` prop).
+     */
+    variant?: ToggleButtonVariant;
+    /**
+     * Color applied to all child toggles (overrides their own `color` prop).
+     */
+    color?: ButtonColor;
+    /**
+     * Size applied to all child toggles (overrides their own `size` prop).
+     */
+    size?: ButtonSize;
+    /**
+     * Whether clicking the currently active toggle deselects it (value becomes null).
+     * @default true
+     */
+    allowDeselect?: boolean;
+};
+
+/**
+ * Groups multiple `ToggleButton` or `ToggleIconButton` components so that only
+ * one can be active at a time (mutual exclusivity).
+ *
+ * Supports both **controlled** (`value` + `onChange`) and **uncontrolled**
+ * (`defaultValue`) modes. Set `allowDeselect={false}` to always keep one
+ * option selected.
+ *
+ * @example
+ * // Uncontrolled
+ * <ToggleGroup defaultValue="md" ariaLabel="Text size">
+ *     <ToggleButton value="sm" label="Small" />
+ *     <ToggleButton value="md" label="Medium" />
+ *     <ToggleButton value="lg" label="Large" />
+ * </ToggleGroup>
+ *
+ * @example
+ * // Controlled
+ * const [align, setAlign] = useState<string | null>('left')
+ * <ToggleGroup value={align} onChange={setAlign} ariaLabel="Text alignment" joined>
+ *     <ToggleIconButton value="left"   icon={AlignLeftIcon}   ariaLabel="Align left" />
+ *     <ToggleIconButton value="center" icon={AlignCenterIcon} ariaLabel="Align center" />
+ *     <ToggleIconButton value="right"  icon={AlignRightIcon}  ariaLabel="Align right" />
+ * </ToggleGroup>
+ */
+declare const ToggleGroup: FC<ToggleGroupProps>;
+
+/** Avatar size token controlling the avatar's width and height. */
+type AvatarSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
+/** Avatar shape – circle (default) or rounded square. */
+type AvatarShape = 'circle' | 'square';
+/**
+ * Semantic color intent used for the fallback background
+ * (shown when no image is provided).
+ */
+type AvatarColor = 'default' | 'primary' | 'secondary' | 'success' | 'warning' | 'error' | 'info' | 'orange' | 'pink' | 'violet';
+/** Overlap density between avatars inside an AvatarGroup. */
+type AvatarGroupOverlap = 'sm' | 'md' | 'lg';
+
+type AvatarProps = {
+    /**
+     * URL of the image to display.
+     * Falls back to `initials` (or first letters of `name`) if the image fails to load.
+     */
+    src?: string;
+    /**
+     * Full name of the person/entity.
+     * Automatically extracts 1–2 initials when no `src` is provided.
+     * Also used as `aria-label` when no explicit `ariaLabel` is given.
+     */
+    name?: string;
+    /**
+     * Explicit initials to display when no image is available.
+     * Takes precedence over initials derived from `name`.
+     * Keep to 1–2 characters.
+     */
+    initials?: string;
+    /** Size token controlling width and height. @default 'md' */
+    size?: AvatarSize;
+    /** Shape of the avatar. @default 'circle' */
+    shape?: AvatarShape;
+    /**
+     * Background color token used for the fallback (initials/empty) state.
+     * @default 'primary'
+     */
+    color?: AvatarColor;
+    /**
+     * Makes the avatar interactive (adds `role="button"` and keyboard support).
+     * Called when the user clicks or presses Enter/Space.
+     */
+    onClick?: () => void;
+    /** Accessible label. Defaults to `name` when set, otherwise `'Avatar'`. */
+    ariaLabel?: string;
+};
+
+/**
+ * Displays a user's profile picture, falling back gracefully to initials
+ * and then to a blank coloured circle when no image is available.
+ *
+ * **Display priority:**
+ * 1. `src` image (hides on load error)
+ * 2. `initials` (explicit) or letters derived from `name`
+ * 3. Empty coloured circle
+ *
+ * **Accessibility:**
+ * - Static avatar → `role="img"` + `aria-label`
+ * - Interactive avatar (has `onClick`) → `role="button"` + keyboard support
+ *
+ * @example
+ * ```tsx
+ * // Image avatar:
+ * <Avatar src="/users/alice.jpg" name="Alice Dupont" size="md" />
+ *
+ * // Initials fallback:
+ * <Avatar name="Bob Martin" color="info" size="lg" />
+ *
+ * // Interactive:
+ * <Avatar src="/me.jpg" name="Me" onClick={() => openProfile()} ariaLabel="Open profile" />
+ * ```
+ */
+declare const Avatar: FC<AvatarProps>;
+
+type AvatarGroupProps = {
+    /** Avatar components to render inside the group. */
+    children: ReactNode;
+    /**
+     * Maximum number of avatars to display.
+     * When exceeded, a surplus counter (+N) avatar is shown at the end.
+     */
+    max?: number;
+    /**
+     * Size passed down to all Avatar children and to the surplus avatar.
+     * Individual Avatar size props are overridden by this value when set.
+     */
+    size?: AvatarSize;
+    /**
+     * Shape passed down to all Avatar children **and to the surplus avatar**.
+     * Ensures visual consistency — e.g. `shape="square"` makes the +N tile
+     * square as well.
+     * Individual Avatar shape props are overridden by this value when set.
+     */
+    shape?: AvatarShape;
+    /**
+     * Controls the horizontal overlap between adjacent avatars.
+     * - `sm` — tight (most overlap)
+     * - `md` — moderate overlap (default)
+     * - `lg` — loose (least overlap)
+     * @default 'md'
+     */
+    overlap?: AvatarGroupOverlap;
+    /**
+     * Background color of the surplus counter avatar (+N).
+     * @default 'default'
+     */
+    surplusColor?: AvatarColor;
+    /**
+     * Accessible label for the group (`aria-label` on `role="list"`).
+     *
+     * **Auto-computed when omitted** — built from the `name` props of child
+     * Avatars (e.g. *"Alice Dupont, Bob Martin et 3 autres"*).
+     * Pass an explicit value to override this behaviour.
+     */
+    ariaLabel?: string;
+};
+
+/**
+ * Renders a horizontally overlapping stack of `Avatar` components.
+ *
+ * When the number of children exceeds `max`, the remaining count is shown
+ * as a **surplus avatar** (`+N`) at the end of the row.
+ *
+ * **Accessibility:**
+ * - Root element uses `role="list"` so screen readers announce the item count.
+ * - Each slot uses `role="listitem"`.
+ * - The `aria-label` on the root is auto-built from children `name` props
+ *   (e.g. *"Alice Dupont, Bob Martin et 3 autres"*) unless overridden.
+ *
+ * @example
+ * ```tsx
+ * <AvatarGroup max={4} size="md" overlap="md">
+ *   <Avatar name="Alice Dupont" color="primary" />
+ *   <Avatar name="Bob Martin"   color="info"    />
+ *   <Avatar src="/carol.jpg"    name="Carol"    />
+ *   <Avatar name="Dan Lee"      color="success" />
+ *   <Avatar name="Eve Chen"     color="warning" />
+ * </AvatarGroup>
+ * // → shows 4 avatars + "+1"
+ * ```
+ */
+declare const AvatarGroup: FC<AvatarGroupProps>;
+
 /** SVG icon component used by badge icon slots. */
 type BadgeIcon = ComponentType<SVGProps<SVGSVGElement>>;
 /** Visual style of the badge surface. */
@@ -521,6 +946,245 @@ interface InfoBubbleProps {
  */
 declare const InfoBubble: FC<InfoBubbleProps>;
 
+/** Horizontal alignment of a cell's content. */
+type TableAlign = 'left' | 'center' | 'right';
+/** Strategy used to size the table columns. `'fixed'` honors `columns` widths strictly. */
+type TableLayout = 'auto' | 'fixed';
+/**
+ * Declarative column definition — the single source of truth for column widths.
+ *
+ * Widths are applied through a native `<colgroup>`, which (combined with
+ * `layout="fixed"`) is the simplest and most reliable way to control column
+ * sizing: declare it once at the root and every cell follows.
+ */
+type TableColumn = {
+    /** Column width — any CSS width (e.g. `'40%'`, `120`, `'12rem'`, `'auto'`). */
+    width?: CSSProperties['width'];
+    /** Minimum width applied to the column. */
+    minWidth?: CSSProperties['minWidth'];
+    /** Maximum width applied to the column. */
+    maxWidth?: CSSProperties['maxWidth'];
+    /** Default horizontal alignment for the column's loading/empty cells. @default 'left' */
+    align?: TableAlign;
+};
+
+type TableProps = {
+    /**
+     * Compound children — typically a `Table.Head` and a `Table.Body`.
+     * Can be omitted when `loading` or `isEmpty` is `true` — the body placeholder
+     * is rendered by the context without requiring children.
+     */
+    children?: ReactNode;
+    /**
+     * Column definitions — the single source of truth for column widths.
+     * Rendered as a native `<colgroup>` and also used to size loading/empty rows.
+     * @example columns={[{ width: '40%' }, { width: 120 }, { width: 'auto' }]}
+     */
+    columns?: TableColumn[];
+    /** Column sizing strategy. `'fixed'` enforces `columns` widths strictly. @default 'fixed' */
+    layout?: TableLayout;
+    /** Alternate background color on even body rows. @default false */
+    striped?: boolean;
+    /** Highlight body rows on hover. @default false */
+    hoverable?: boolean;
+    /** Wrap the table in a bordered, rounded container. @default false */
+    bordered?: boolean;
+    /**
+     * Keep the header visible while the body scrolls vertically. @default false
+     * @remarks Requires `maxHeight` so the table's own container becomes the scroller.
+     */
+    stickyHeader?: boolean;
+    /**
+     * Constrain the table height and turn its container into the vertical scroller.
+     * Required for `stickyHeader` to take effect.
+     */
+    maxHeight?: CSSProperties['maxHeight'];
+    /**
+     * Render a skeleton placeholder body instead of the children.
+     * Each skeleton cell fills the width of its column. @default false
+     * @a11y Sets `aria-busy="true"` on the table while loading.
+     */
+    loading?: boolean;
+    /** Number of skeleton rows rendered while `loading`. @default 3 */
+    loadingRows?: number;
+    /** Render the empty placeholder instead of the children (ignored while loading). @default false */
+    isEmpty?: boolean;
+    /** Content displayed when `isEmpty` is true. @default 'No data available' */
+    emptyContent?: ReactNode;
+    /**
+     * Accessible name for the table.
+     * @a11y Recommended — gives the table a name describing its content for assistive tech.
+     */
+    ariaLabel?: string;
+    /** Id of an external element labelling the table. */
+    ariaLabelledBy?: string;
+    /** Optional id forwarded to the `<table>` element. */
+    id?: string;
+};
+
+type TableBodyProps = {
+    /**
+     * The data rows (`Table.Row`). Ignored while the parent `Table` is
+     * `loading` (skeleton rows are shown) or `isEmpty` (placeholder is shown).
+     */
+    children?: ReactNode;
+};
+
+type TableCellProps = TdHTMLAttributes<HTMLTableCellElement> & {
+    ref?: Ref<HTMLTableCellElement>;
+    /** Cell content. */
+    children?: ReactNode;
+    /** Horizontal alignment of the content. @default 'left' */
+    align?: TableAlign;
+};
+
+type TableFootProps = {
+    /** One or more `Table.Row` rendered inside the `<tfoot>`. */
+    children: ReactNode;
+};
+
+type TableHeadProps = {
+    /** One or more `Table.Row` containing `Table.HeaderCell`s. */
+    children: ReactNode;
+};
+
+type TableHeaderCellProps = ThHTMLAttributes<HTMLTableCellElement> & {
+    ref?: Ref<HTMLTableCellElement>;
+    /** Header content. */
+    children?: ReactNode;
+    /** Horizontal alignment of the content. @default 'left' */
+    align?: TableAlign;
+    /**
+     * Scope of the header, mapped to the native `scope` attribute. @default 'col'
+     * @a11y Required — associates the header with its column (`'col'`) or row (`'row'`).
+     */
+    scope?: 'col' | 'row' | 'colgroup' | 'rowgroup';
+    /**
+     * Current sort direction, mapped to `aria-sort`.
+     * @a11y Recommended on sortable columns so assistive tech announces the order.
+     */
+    sortDirection?: AriaAttributes['aria-sort'];
+};
+
+type TableRowProps = HTMLAttributes<HTMLTableRowElement> & {
+    ref?: Ref<HTMLTableRowElement>;
+    /** Cells of the row — `Table.HeaderCell` and/or `Table.Cell`. */
+    children: ReactNode;
+    /**
+     * Marks the row as selected — sets `aria-selected="true"` and a highlighted background.
+     * @a11y When rows are interactive, also provide keyboard handling and a focusable target.
+     */
+    selected?: boolean;
+};
+
+/** Compound component type — `Table` plus its statically attached sub-components. */
+type TableComponent = FC<TableProps> & {
+    Head: FC<TableHeadProps>;
+    Body: FC<TableBodyProps>;
+    Foot: FC<TableFootProps>;
+    Row: FC<TableRowProps>;
+    HeaderCell: FC<TableHeaderCellProps>;
+    Cell: FC<TableCellProps>;
+};
+declare const Table: TableComponent;
+
+type ErrorBoundaryFallbackRenderProps = {
+    error: Error;
+    reset: () => void;
+};
+type ErrorBoundaryProps = {
+    /**
+     * Custom fallback. Receives the caught error and a `reset()` callback that
+     * clears the error state so the children can attempt to re-mount.
+     * If omitted, `DefaultErrorFallback` is used.
+     */
+    fallback?: (props: ErrorBoundaryFallbackRenderProps) => ReactNode;
+    /**
+     * Side-effect hook for monitoring (Sentry, Datadog, custom logger…).
+     * Pure UI consumers should not rely on this for state updates.
+     */
+    onError?: (error: Error, info: ErrorInfo) => void;
+    children: ReactNode;
+};
+type ErrorBoundaryState = {
+    error: Error | null;
+};
+
+/**
+ * Generic React error boundary.
+ * Catches synchronous render-time errors thrown by descendant components
+ * and renders a recoverable fallback UI instead of crashing the whole app.
+ *
+ * Note: error boundaries do NOT catch:
+ *  - errors in event handlers (use try/catch + setState),
+ *  - errors in async code (promises, setTimeout),
+ *  - errors during SSR,
+ *  - errors thrown in the boundary itself.
+ *
+ * For routing errors thrown by loaders/actions, use `RouteErrorBoundary`
+ * (powered by `useRouteError`) directly on a `RouteObject.errorElement`.
+ *
+ * Class component is mandatory: hooks cannot replace `componentDidCatch`
+ * / `getDerivedStateFromError` as of React 19.
+ */
+declare class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+    static displayName: string;
+    state: ErrorBoundaryState;
+    static getDerivedStateFromError: (error: Error) => ErrorBoundaryState;
+    componentDidCatch(error: Error, info: ErrorInfo): void;
+    private reset;
+    render(): string | number | bigint | boolean | Iterable<react.ReactNode> | Promise<string | number | bigint | boolean | react.ReactPortal | react.ReactElement<unknown, string | react.JSXElementConstructor<any>> | Iterable<react.ReactNode> | null | undefined> | react_jsx_runtime.JSX.Element | null | undefined;
+}
+
+type DefaultErrorFallbackProps = {
+    /** Caught error passed by `ErrorBoundary`. */
+    error: Error;
+    /** Callback to clear the error state and re-mount children. */
+    onRetry: () => void;
+    /**
+     * Heading displayed above the message.
+     * @default 'Something went wrong'
+     */
+    title?: string;
+    /**
+     * Descriptive message shown below the title.
+     * @default 'An unexpected error occurred. Please try again.'
+     */
+    message?: string;
+    /**
+     * Label of the retry button.
+     * @default 'Try again'
+     */
+    retryLabel?: string;
+};
+
+/**
+ * Default fallback UI rendered by `ErrorBoundary` when no custom
+ * `fallback` prop is provided.
+ *
+ * Displays a centred error message with a collapsible technical detail
+ * section and a retry button that resets the boundary state.
+ *
+ * @example
+ * ```tsx
+ * // Used automatically by ErrorBoundary:
+ * <ErrorBoundary>
+ *     <MyFeature />
+ * </ErrorBoundary>
+ *
+ * // Or rendered directly with mocked data (e.g. in Storybook):
+ * <DefaultErrorFallback
+ *     error={new Error('Network request failed')}
+ *     onRetry={() => refetch()}
+ *     title="Failed to load data"
+ * />
+ * ```
+ */
+declare const DefaultErrorFallback: {
+    ({ error, onRetry, title, message, retryLabel, }: DefaultErrorFallbackProps): react_jsx_runtime.JSX.Element;
+    displayName: string;
+};
+
 type IconProps = HTMLAttributes<HTMLDivElement> & {
     ref?: Ref<HTMLDivElement>;
     /**
@@ -551,12 +1215,94 @@ type IconStyleParams = {
 };
 
 /**
- * Renders an SVG icon inside a theme-aware wrapper.
+ * Renders an SVG icon inside a theme-aware wrapper.
+ *
+ * @example <Icon icon={MenuIcon} size='md' strokeColor='primaryMain' />
+ * @example <Icon icon={CloseIcon} strokeColor='textInverse' backgroundColor='primaryMain' padding='sm' borderRadius='full' />
+ */
+declare const Icon: FC<IconProps>;
+
+type ImageProps = {
+    /** URL source of the image */
+    src: string;
+    /**
+     * Accessible alternative text.
+     * - Provide a meaningful description for meaningful images.
+     * - Pass an empty string `""` for purely decorative images.
+     */
+    alt: string;
+    /** Width of the image — any valid CSS value (e.g. '200px', '50%', 200) */
+    width?: CSSProperties['width'];
+    /** Height of the image — any valid CSS value (e.g. '150px', 'auto', 150) */
+    height?: CSSProperties['height'];
+    /** Max-width constraint — useful for responsive layouts */
+    maxWidth?: CSSProperties['maxWidth'];
+    /** Max-height constraint */
+    maxHeight?: CSSProperties['maxHeight'];
+    /** CSS object-fit value controlling how the image fills its container */
+    objectFit?: CSSProperties['objectFit'];
+    /** Lazy-load the image to improve performance. Defaults to 'lazy' */
+    loading?: 'lazy' | 'eager';
+    /** Border radius using theme tokens */
+    borderRadius?: keyof Theme['radius'];
+    /** ID of element that describes this image */
+    ariaDescribedBy?: string;
+};
+
+/**
+ * Renders a standard HTML image (`<img>`) with sizing, object-fit, border radius,
+ * and accessibility support.
+ *
+ * **Features:**
+ * - Free sizing via `width` / `height` (e.g. `'200px'`, `'50%'`, `200`)
+ * - Responsive constraint via `maxWidth` / `maxHeight`
+ * - `objectFit` to control how the image fills its container
+ * - `borderRadius` using theme tokens (e.g. `'md'`, `'full'`)
+ * - Native lazy-loading via `loading` prop (defaults to `'lazy'`)
+ * - Accessibility: `alt` is required — pass `""` for decorative images
+ *
+ * @example
+ * ```tsx
+ * // Decorative image (empty alt):
+ * <Image src="/bg.jpg" alt="" width="100%" height={200} objectFit="cover" />
+ *
+ * // Meaningful image:
+ * <Image
+ *   src="/avatar.png"
+ *   alt="Profile picture of Jane Doe"
+ *   width={64}
+ *   height={64}
+ *   borderRadius="full"
+ *   objectFit="cover"
+ * />
+ * ```
+ */
+declare const Image: FC<ImageProps>;
+
+type LoaderScreenProps = {
+    /**
+     * Accessible label announced to screen readers while loading.
+     * @default 'Loading…'
+     */
+    label?: string;
+};
+
+/**
+ * Full-screen loading placeholder shown while data is being fetched.
  *
- * @example <Icon icon={MenuIcon} size='md' strokeColor='primaryMain' />
- * @example <Icon icon={CloseIcon} strokeColor='textInverse' backgroundColor='primaryMain' padding='sm' borderRadius='full' />
+ * Renders a centred spinner over a full-viewport surface.
+ * The spinner rotation is suppressed when the user prefers reduced motion.
+ *
+ * @example
+ * ```tsx
+ * // Swap with real content once data is ready:
+ * {isLoading ? <LoaderScreen /> : <AppContent />}
+ *
+ * // With a custom label for screen readers:
+ * <LoaderScreen label="Loading your dashboard…" />
+ * ```
  */
-declare const Icon: FC<IconProps>;
+declare const LoaderScreen: FC<LoaderScreenProps>;
 
 /** Shape variant of the Skeleton placeholder. */
 type SkeletonVariant = 'text' | 'circular' | 'rectangular' | 'rounded';
@@ -599,6 +1345,53 @@ type SkeletonProps = HTMLAttributes<HTMLSpanElement> & {
  */
 declare const Skeleton: FC<SkeletonProps>;
 
+type SvgImageProps = {
+    /** SVG image component to render (from ImagesRegistry) */
+    image: ComponentType<SVGProps<SVGSVGElement>>;
+    /** Width of the image — any valid CSS value (e.g. '200px', '50%', 200) */
+    width?: CSSProperties['width'];
+    /** Height of the image — any valid CSS value (e.g. '150px', 'auto', 150) */
+    height?: CSSProperties['height'];
+    /** Max width constraint — useful for responsive layouts */
+    maxWidth?: CSSProperties['maxWidth'];
+    /** Max height constraint */
+    maxHeight?: CSSProperties['maxHeight'];
+    /** Accessibility label for screen readers (marks the image as meaningful) */
+    ariaLabel?: string;
+    /** ID of element that labels this image */
+    ariaLabelledBy?: string;
+    /** ID of element that describes this image */
+    ariaDescribedBy?: string;
+};
+
+/**
+ * Renders an SVG illustration with free-form sizing.
+ *
+ * Unlike `Icon` (constrained to theme font sizes), `SvgImage` accepts any
+ * valid CSS value for `width` and `height`.
+ *
+ * **Features:**
+ * - Free sizing via `width` / `height` (e.g. `'200px'`, `'50%'`, `200`)
+ * - Responsive constraint via `maxWidth` / `maxHeight`
+ * - Accessibility: `ariaLabel`, `ariaLabelledBy`, `ariaDescribedBy`
+ * - No label → `aria-hidden` (decorative illustration)
+ *
+ * @example
+ * ```tsx
+ * // Decorative illustration (no accessible label needed):
+ * <SvgImage image={ImagesRegistry.WelcomeIllustration} width={320} />
+ *
+ * // Meaningful illustration (must have a label):
+ * <SvgImage
+ *   image={ImagesRegistry.EmptyStateIllustration}
+ *   width={'50%'}
+ *   maxWidth={400}
+ *   ariaLabel="No results found illustration"
+ * />
+ * ```
+ */
+declare const SvgImage: FC<SvgImageProps>;
+
 type TextVariants = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'p' | 'span' | 'label' | 'strong';
 type TextVariantStyle = {
     /** HTML tag to render. */
@@ -719,6 +1512,95 @@ type FormProps = {
  */
 declare const Form: FC<FormProps>;
 
+/** Size variant of the RadioButton. */
+type RadioButtonSize = 'sm' | 'md' | 'lg';
+/** Semantic status of the RadioButton, affecting border and helper text color. */
+type RadioButtonStatus = 'default' | 'error' | 'success' | 'warning';
+
+type RadioButtonProps = Omit<InputHTMLAttributes<HTMLInputElement>, 'type' | 'size'> & {
+    ref?: Ref<HTMLInputElement>;
+    /**
+     * Visible label rendered next to the radio button.
+     * @a11y Recommended — provides the radio button's accessible name (clickable to select it).
+     */
+    label?: ReactNode;
+    /**
+     * Helper text or validation message rendered below the radio button row.
+     * @a11y Recommended — linked to the input via `aria-describedby`.
+     */
+    helperText?: string;
+    /** Size variant controlling radio button size and text scale. @default 'md' */
+    size?: RadioButtonSize;
+    /**
+     * Semantic status affecting border and helper text color. @default 'default'
+     * @a11y Recommended — `status='error'` sets `aria-invalid` on the input.
+     */
+    status?: RadioButtonStatus;
+    /** @deprecated Use `status='error'` instead. Kept for backward compatibility. */
+    error?: boolean;
+};
+
+declare const RadioButton: FC<RadioButtonProps>;
+
+/** Orientation of the RadioGroup. */
+type RadioGroupOrientation = 'vertical' | 'horizontal';
+
+type RadioGroupProps = {
+    /** The radio options to render inside the group. Should be `RadioButton` components. */
+    children: ReactNode;
+    /**
+     * The `name` attribute shared by all radio inputs in the group.
+     * If omitted, a unique id is auto-generated.
+     */
+    name?: string;
+    /** Controlled selected value. */
+    value?: string;
+    /** Default selected value for uncontrolled usage. */
+    defaultValue?: string;
+    /** Callback fired when the selected value changes. */
+    onChange?: (value: string) => void;
+    /**
+     * Layout direction of the radio options.
+     * @default 'vertical'
+     */
+    orientation?: RadioGroupOrientation;
+    /** Disables all radio buttons in the group. */
+    disabled?: boolean;
+    /**
+     * Legend text rendered as an accessible `<legend>` above the group.
+     * @a11y Recommended — labels the entire radio group for screen readers.
+     */
+    legend?: ReactNode;
+    /** Size applied to all radio buttons in the group unless individually overridden. @default 'md' */
+    size?: RadioButtonSize;
+    /**
+     * Status applied to all radio buttons in the group unless individually overridden.
+     * @default 'default'
+     */
+    status?: RadioButtonStatus;
+    /**
+     * Marks the radio group as required.
+     * @a11y Sets `aria-required` on the group element — indicates that at least one option must be selected.
+     */
+    required?: boolean;
+    /** @deprecated Use `status='error'` instead. Kept for backward compatibility. */
+    error?: boolean;
+};
+
+/**
+ * Accessible radio group wrapping multiple `RadioButton` components inside a `<fieldset>`.
+ *
+ * Supports controlled (`value` + `onChange`) and uncontrolled (`defaultValue`) modes.
+ * Propagates `name`, `value`, `disabled`, `size`, and `status` to all child `RadioButton` elements via context.
+ *
+ * @example
+ * <RadioGroup legend="Preferred contact" defaultValue="email" onChange={setValue}>
+ *   <RadioButton value="email" label="Email" />
+ *   <RadioButton value="phone" label="Phone" />
+ * </RadioGroup>
+ */
+declare const RadioGroup: FC<RadioGroupProps>;
+
 type SwitchSize = 'sm' | 'md' | 'lg';
 type SwitchColor = 'primary' | 'success' | 'error' | 'warning' | 'info' | 'neutral';
 
@@ -799,6 +1681,11 @@ type SelectOption = {
     label: string;
     /** Optional icon rendered before the label in the menu item. */
     icon?: ComponentType<SVGProps<SVGSVGElement>>;
+    /**
+     * Color applied to the icon's stroke. Uses theme color tokens.
+     * When omitted, the icon inherits the default item color behaviour (primaryMain when selected, textSecondary otherwise).
+     */
+    iconColor?: keyof Theme['colors'];
     /** Whether the option cannot be selected. */
     disabled?: boolean;
     /**
@@ -882,6 +1769,81 @@ type CheckboxProps = Omit<InputHTMLAttributes<HTMLInputElement>, 'type' | 'size'
 
 declare const Checkbox: FC<CheckboxProps>;
 
+/** Size variant of the DatePicker — aligned with the other form fields. */
+type DatePickerSize = TextFieldSize;
+/** Semantic status of the DatePicker — aligned with the other form fields. */
+type DatePickerStatus = TextFieldStatus;
+/** First day of the week shown in the calendar. `0` = Sunday … `6` = Saturday. */
+type WeekStart = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+
+type DatePickerProps = {
+    /** Ref forwarded to the underlying text input. */
+    ref?: Ref<HTMLInputElement>;
+    /** Selected date (controlled mode). Pass `null` for an empty value. */
+    value?: Date | null;
+    /** Initial date for uncontrolled mode. @default null */
+    defaultValue?: Date | null;
+    /** Called with the new `Date` (or `null` when cleared) whenever the selection changes. */
+    onChange?: (date: Date | null) => void;
+    /** Earliest selectable date (inclusive). Dates before it are disabled. */
+    minDate?: Date;
+    /** Latest selectable date (inclusive). Dates after it are disabled. */
+    maxDate?: Date;
+    /**
+     * Label rendered above the field.
+     * @a11y Recommended — provides the field's accessible name (linked via `htmlFor`/`id`).
+     */
+    label?: string;
+    /**
+     * Helper text or validation message rendered below the field.
+     * @a11y Recommended — linked to the input via `aria-describedby` (and `aria-errormessage` when `status='error'`).
+     */
+    helperText?: string;
+    /** Placeholder shown when no date is selected. Defaults to the display format in uppercase (e.g. `DD/MM/YYYY`). */
+    placeholder?: string;
+    /** Size variant. @default 'md' */
+    size?: DatePickerSize;
+    /**
+     * Semantic status affecting border and helper text color. @default 'default'
+     * @a11y Recommended — `status='error'` sets `aria-invalid` and links the error message.
+     */
+    status?: DatePickerStatus;
+    /** Whether the field is disabled. */
+    disabled?: boolean;
+    /**
+     * Whether the field is required.
+     * @a11y Recommended — sets `aria-required` on the input and shows the visual asterisk on the label.
+     */
+    required?: boolean;
+    /** Allow typing the date directly in the input. When `false` the input is read-only. @default true */
+    editable?: boolean;
+    /**
+     * Token format used to display and parse the typed value. Supports `dd`, `MM`, `yyyy`.
+     * When omitted, the format is derived from `locale` (field order and separators).
+     */
+    displayFormat?: string;
+    /** BCP 47 locale used for month/weekday labels in the calendar. @default 'en-US' */
+    locale?: string;
+    /** First day of the week shown in the calendar. @default 1 (Monday) */
+    weekStartsOn?: WeekStart;
+    /** Fixed width for the field. Defaults to 100% of its container. */
+    width?: string | number;
+    /** HTML id for the input. */
+    id?: string;
+};
+
+/**
+ * Accessible date field combining a text input trigger and a calendar popover.
+ *
+ * The input round-trips the value with `displayFormat` (typing is allowed unless
+ * `editable={false}`), while the trailing icon button opens a focus-trapped
+ * `role="dialog"` calendar following the WAI-ARIA date-grid pattern.
+ *
+ * @example <DatePicker label="Birth date" />
+ * @example <DatePicker label="Start" minDate={new Date()} required helperText="Pick a future date." />
+ */
+declare const DatePicker: FC<DatePickerProps>;
+
 type BoxProps = HTMLAttributes<HTMLDivElement> & BoxStyleProps & {
     ref?: Ref<HTMLDivElement>;
 };
@@ -953,6 +1915,54 @@ type BoxStyleProps = {
     opacity?: CSSProperties['opacity'];
 };
 
+/**
+ * Common props type for semantic HTML layout elements enriched with Box style props.
+ *
+ * Use this as the base type for semantic layout components (Article, Aside,
+ * Footer, Header, Main, Nav, Section…) so they all expose the same token-aware
+ * style props as `Box`.
+ *
+ * @template T - The underlying HTML element type (e.g. `HTMLElement`, `HTMLDivElement`).
+ */
+type SemanticBoxProps<T extends HTMLElement = HTMLElement> = HTMLAttributes<T> & BoxStyleProps & {
+    /** Ref forwarded to the underlying HTML element. */
+    ref?: Ref<T>;
+};
+
+/**
+ * Props for the Article component.
+ * Accepts all style tokens from Box, forwarded to a native `<article>` element.
+ */
+type ArticleProps = SemanticBoxProps<HTMLElement>;
+
+/**
+ * Semantic `<article>` enriched with the same token-aware style props as `Box`.
+ *
+ * Use `Article` for self-contained content that could stand alone and be
+ * re-distributed independently (blog posts, news articles, forum posts, cards).
+ * Each `Article` should ideally have a heading.
+ *
+ * @example <Article padding="lg" borderRadius="md" backgroundColor="surfacePaper">…</Article>
+ */
+declare const Article: FC<ArticleProps>;
+
+/**
+ * Props for the Aside component.
+ * Accepts all style tokens from Box, forwarded to a native `<aside>` element.
+ */
+type AsideProps = SemanticBoxProps<HTMLElement>;
+
+/**
+ * Semantic `<aside>` enriched with the same token-aware style props as `Box`.
+ *
+ * Use `Aside` for supplemental content that is tangentially related to the
+ * surrounding content (sidebars, pull-quotes, ads, related links).
+ * Screen-readers expose it as the `complementary` landmark.
+ *
+ * @example <Aside aria-label="Related articles" width="280px" padding="md">…</Aside>
+ */
+declare const Aside: FC<AsideProps>;
+
 /**
  * A plain `div` enriched with convenient, token-aware style props.
  *
@@ -1005,6 +2015,23 @@ type CardComponent = FC<CardProps> & {
 
 declare const Card: CardComponent;
 
+/**
+ * Props for the Footer component.
+ * Accepts all style tokens from Box, forwarded to a native `<footer>` element.
+ */
+type FooterProps = SemanticBoxProps<HTMLElement>;
+
+/**
+ * Semantic `<footer>` enriched with the same token-aware style props as `Box`.
+ *
+ * Use `Footer` for the closing content of a page or a section
+ * (copyright, links, contact info). Screen-readers expose it as the
+ * `contentinfo` landmark when it is a direct child of `<body>`.
+ *
+ * @example <Footer py="md" display="flex" justifyContent="space-between">…</Footer>
+ */
+declare const Footer: FC<FooterProps>;
+
 /**
  * Extra CSS Grid props not covered by BoxProps.
  * `columns` and `rows` are convenience shorthands:
@@ -1042,6 +2069,134 @@ type GridProps = Omit<BoxProps, 'display'> & GridStyleProps & {
  */
 declare const Grid: FC<GridProps>;
 
+/**
+ * Props for the Header component.
+ * Accepts all style tokens from Box, forwarded to a native `<header>` element.
+ */
+type HeaderProps = SemanticBoxProps<HTMLElement>;
+
+/**
+ * Semantic `<header>` enriched with the same token-aware style props as `Box`.
+ *
+ * Use `Header` for the introductory content of a page or a section
+ * (logo, site title, navigation). Screen-readers expose it as the
+ * `banner` landmark when it is a direct child of `<body>`.
+ *
+ * @example <Header padding="md" display="flex" alignItems="center" gap="sm">…</Header>
+ */
+declare const Header: FC<HeaderProps>;
+
+/**
+ * Props for the Main component.
+ * Accepts all style tokens from Box, forwarded to a native `<main>` element.
+ */
+type MainProps = SemanticBoxProps<HTMLElement>;
+
+/**
+ * Semantic `<main>` enriched with the same token-aware style props as `Box`.
+ *
+ * Use `Main` for the primary content of the page. There should be only **one**
+ * `Main` per page. Screen-readers expose it as the `main` landmark, allowing
+ * users to jump directly to the core content.
+ *
+ * @example <Main padding="xl" display="flex" flexDirection="column" gap="lg">…</Main>
+ */
+declare const Main: FC<MainProps>;
+
+/**
+ * Props for the Nav component.
+ * Accepts all style tokens from Box, forwarded to a native `<nav>` element.
+ */
+type NavProps = SemanticBoxProps<HTMLElement>;
+
+/**
+ * Semantic `<nav>` enriched with the same token-aware style props as `Box`.
+ *
+ * Use `Nav` to wrap sets of navigation links. When multiple `Nav` elements
+ * are present, give each a distinct `aria-label` so screen-reader users can
+ * tell them apart (e.g. `aria-label="Main navigation"` vs `aria-label="Footer links"`).
+ *
+ * @example <Nav aria-label="Main navigation" display="flex" gap="sm">…</Nav>
+ */
+declare const Nav: FC<NavProps>;
+
+/**
+ * Props for the Section component.
+ * Accepts all style tokens from Box, forwarded to a native `<section>` element.
+ */
+type SectionProps = SemanticBoxProps<HTMLElement>;
+
+/**
+ * Semantic `<section>` enriched with the same token-aware style props as `Box`.
+ *
+ * Use `Section` to group thematically related content — the browser outline
+ * and screen-readers will announce it as a landmark region when it has an
+ * accessible name (`aria-label` or `aria-labelledby`).
+ *
+ * @example <Section aria-label="Features" padding="lg" gap="md">…</Section>
+ */
+declare const Section: FC<SectionProps>;
+
+/** Orientation of the separator line. */
+type SeparatorOrientation = 'horizontal' | 'vertical';
+/** Visual thickness of the separator line in pixels. */
+type SeparatorThickness = '1' | '2' | '4';
+
+type SeparatorProps = Omit<HTMLAttributes<HTMLElement>, 'children'> & {
+    ref?: Ref<HTMLElement>;
+    /**
+     * Orientation of the separator — determines layout direction. @default 'horizontal'
+     * @a11y Sets `aria-orientation` accordingly on the rendered element.
+     *        For `'vertical'`, the parent must be a flex/grid container so `align-self: stretch` works.
+     */
+    orientation?: SeparatorOrientation;
+    /**
+     * Theme color token for the separator line. @default 'borderMain'
+     */
+    color?: keyof Theme['colors'];
+    /**
+     * Thickness of the separator line in pixels. @default '1'
+     */
+    thickness?: SeparatorThickness;
+    /**
+     * Spacing token applied as margin around the separator.
+     * Horizontal: `margin-block`; Vertical: `margin-inline`.
+     */
+    spacing?: keyof Theme['spacing'];
+    /**
+     * Optional centered text label — only rendered on `orientation="horizontal"`.
+     * When provided, the label is used as `aria-label` so screen readers announce
+     * the section boundary with its name.
+     */
+    label?: string;
+    /**
+     * Mark the separator as decorative (visual only). Sets `aria-hidden="true"`. @default false
+     * @a11y Use when the separator is purely cosmetic and does not convey structural meaning.
+     */
+    decorative?: boolean;
+};
+type SeparatorStyleParams = {
+    orientation?: SeparatorOrientation;
+    color?: keyof Theme['colors'];
+    thickness?: SeparatorThickness;
+    spacing?: keyof Theme['spacing'];
+    hasLabel?: boolean;
+};
+
+/**
+ * A visual separator line (horizontal or vertical) with optional centered label.
+ *
+ * Uses `<hr>` for horizontal separators (implicit `role="separator"`) and a
+ * `<div role="separator">` for vertical or labeled variants.
+ *
+ * @example <Separator />
+ * @example <Separator orientation="vertical" />
+ * @example <Separator label="Or" spacing="md" />
+ * @example <Separator color="primaryMain" thickness="2" />
+ * @example <Separator decorative />
+ */
+declare const Separator: FC<SeparatorProps>;
+
 /**
  * A flex `Box` for laying out children along a single axis.
  *
@@ -1291,6 +2446,83 @@ type DrawerContextValue = {
 };
 declare const useDrawerContext: () => DrawerContextValue;
 
+/** Size token controlling the dimensions and font scale of pagination items. */
+type PaginationSize = 'sm' | 'md' | 'lg';
+/** Visual shape of the pagination items. */
+type PaginationShape = 'rounded' | 'circular';
+
+type PaginationProps = {
+    /**
+     * Currently active page (1-based). The component is controlled.
+     * @a11y The matching page button exposes `aria-current="page"`.
+     */
+    currentPage: number;
+    /** Total number of pages available. */
+    totalPages: number;
+    /** Called with the requested page when the user navigates. */
+    onPageChange: (page: number) => void;
+    /**
+     * Number of pages displayed on each side of the current page.
+     * @default 1
+     */
+    siblingCount?: number;
+    /**
+     * Number of pages always displayed at the very start and end.
+     * @default 1
+     */
+    boundaryCount?: number;
+    /** Size token controlling item dimensions and font scale. @default 'md' */
+    size?: PaginationSize;
+    /** Visual shape of the items. @default 'rounded' */
+    shape?: PaginationShape;
+    /** Render the previous / next arrow controls. @default true */
+    showPrevNext?: boolean;
+    /** Render the jump-to-first / jump-to-last controls. @default false */
+    showFirstLast?: boolean;
+    /** Disable the whole pagination. */
+    disabled?: boolean;
+    /**
+     * Accessible label for the `<nav>` landmark.
+     * @default 'Pagination'
+     * @a11y Recommended — describe the navigation to assistive technologies.
+     */
+    ariaLabel?: string;
+    /** Accessible label for the previous-page control. @default 'Go to previous page' */
+    previousAriaLabel?: string;
+    /** Accessible label for the next-page control. @default 'Go to next page' */
+    nextAriaLabel?: string;
+    /** Accessible label for the first-page control. @default 'Go to first page' */
+    firstAriaLabel?: string;
+    /** Accessible label for the last-page control. @default 'Go to last page' */
+    lastAriaLabel?: string;
+    /**
+     * Builds the accessible label of a page button.
+     * @default (page, selected) => selected ? `page ${page}` : `Go to page ${page}`
+     */
+    getPageAriaLabel?: (page: number, selected: boolean) => string;
+};
+
+/**
+ * Accessible, controlled pagination control.
+ *
+ * Renders a `<nav>` landmark wrapping a list of page buttons, with optional
+ * previous/next and first/last controls. Collapses long ranges using ellipses
+ * (configurable via `siblingCount` and `boundaryCount`). The active page exposes
+ * `aria-current="page"`.
+ *
+ * ```tsx
+ * const [page, setPage] = useState(1)
+ *
+ * <Pagination
+ *     currentPage={page}
+ *     totalPages={10}
+ *     onPageChange={setPage}
+ *     showFirstLast
+ * />
+ * ```
+ */
+declare const Pagination: FC<PaginationProps>;
+
 type TabsProps = {
     /** Children — typically a `Tabs.List` with `Tabs.Tab`s and one or more `Tabs.Panel`s. */
     children: ReactNode;
@@ -1347,6 +2579,48 @@ type TabsComponent = FC<TabsProps> & {
 
 declare const Tabs: TabsComponent;
 
+type AccordionProps = {
+    /** Whether the accordion panel is expanded. Used for controlled mode. */
+    open?: boolean;
+    /** Initial open state in uncontrolled mode. @default false */
+    defaultOpen?: boolean;
+    /** Called when the open state changes. */
+    onOpenChange?: (open: boolean) => void;
+    /** `Accordion.Title` and `Accordion.Body` sub-components. */
+    children: ReactNode;
+    /**
+     * Visual style variant. @default 'ghost'
+     * - `ghost` — no border, minimal decoration.
+     * - `outlined` — bordered card-like appearance.
+     */
+    variant?: 'outlined' | 'ghost';
+    /** Whether the accordion is disabled. @default false */
+    disabled?: boolean;
+};
+
+type AccordionTitleProps = {
+    /** Trigger label — accepts any ReactNode (string, Text, Stack with icon, etc.). */
+    children: ReactNode;
+    /**
+     * Heading level wrapping the trigger button, as recommended by the WAI-ARIA Accordion pattern.
+     * The heading allows screen-reader users to navigate accordion items via the heading outline.
+     * Match the level to the surrounding document hierarchy. @default 3
+     */
+    headingLevel?: 1 | 2 | 3 | 4 | 5 | 6;
+};
+
+type AccordionBodyProps = {
+    /** Content to reveal when the accordion is open. */
+    children: ReactNode;
+};
+
+type AccordionComponent = FC<AccordionProps> & {
+    Title: FC<AccordionTitleProps>;
+    Body: FC<AccordionBodyProps>;
+};
+
+declare const Accordion: AccordionComponent;
+
 type AlertProps = {
     /**
      * Visual style of the alert. @default 'default'
@@ -1463,10 +2737,13 @@ type DialogComponent = FC<DialogProps> & {
 
 declare const Dialog: DialogComponent;
 
+/** Where the menu opens relative to its anchor. */
+type MenuPlacement = 'bottom' | 'right';
+
 type MenuProps = {
     /** Whether the menu is visible. */
     open: boolean;
-    /** Called when the menu should close (click outside or Escape key). */
+    /** Called when the menu should close (click outside, outside scroll or Escape key). */
     onClose: () => void;
     /** Reference element used to position the menu. */
     anchorEl?: HTMLElement | null;
@@ -1474,16 +2751,25 @@ type MenuProps = {
     minWidth?: number | string;
     /** Maximum height before scrolling. @default '20rem' */
     maxHeight?: string;
-    /** ARIA id for the listbox panel. */
+    /** Where the menu opens relative to the anchor. @default 'bottom' */
+    placement?: MenuPlacement;
+    /** ARIA id for the menu panel. */
     id?: string;
     /**
-     * Accessible name for the listbox (use when there is no visible label).
-     * @a11y Recommended — names the listbox when no labelling element is referenced via `aria-labelledby`.
+     * ARIA role of the panel surface.
+     * - `'menu'` (default) — action menu; children use `menuitem`.
+     * - `'listbox'` — single/multi-select popup; children use `option`.
+     * @default 'menu'
+     */
+    role?: 'menu' | 'listbox';
+    /**
+     * Accessible name for the menu (use when there is no visible label).
+     * @a11y Recommended — names the menu when no labelling element is referenced via `aria-labelledby`.
      */
     'aria-label'?: string;
     /**
-     * Id of an element that labels the listbox (e.g. the trigger's label).
-     * @a11y Recommended — references the trigger's visible label to name the listbox.
+     * Id of an element that labels the menu (e.g. the trigger's label).
+     * @a11y Recommended — references the trigger's visible label to name the menu.
      */
     'aria-labelledby'?: string;
     /** Menu content — MenuGroup and/or MenuItem. */
@@ -1499,24 +2785,58 @@ type MenuGroupProps = {
     children: ReactNode;
 };
 
+/** ARIA role of a menu item. */
+type MenuItemRole = 'menuitem' | 'menuitemcheckbox' | 'menuitemradio' | 'option';
 type MenuItemProps = HTMLAttributes<HTMLLIElement> & {
     ref?: Ref<HTMLLIElement>;
     /**
      * Display text of the item.
-     * @a11y Recommended — provides the option's accessible name.
+     * @a11y Recommended — provides the item's accessible name.
      */
     label: string;
     /** Optional SVG icon rendered before the label. */
     icon?: ComponentType<SVGProps<SVGSVGElement>>;
     /**
-     * Whether this item is currently selected.
-     * @a11y Recommended — exposes the selected state via `aria-selected`.
+     * Color applied to the icon's stroke. Uses theme color tokens.
+     * When omitted, the icon inherits the default behaviour (primaryMain when selected, textSecondary otherwise).
+     */
+    iconColor?: keyof Theme['colors'];
+    /**
+     * ARIA role of the item.
+     * - `'menuitem'` (default) — a regular action item.
+     * - `'menuitemcheckbox'` — a toggleable item; pair with `checked`.
+     * - `'menuitemradio'` — a single-choice item within a group; pair with `checked`.
+     * @default 'menuitem'
+     */
+    role?: MenuItemRole;
+    /**
+     * Checked state for `menuitemcheckbox` / `menuitemradio` items.
+     * @a11y Recommended — exposes the state via `aria-checked` and shows the indicator.
+     */
+    checked?: boolean;
+    /**
+     * Whether this item is visually highlighted as selected (e.g. the current value).
+     * For checkbox/radio items prefer `checked`.
      */
     selected?: boolean;
     /** Whether this item has keyboard focus (highlighted via arrow navigation). */
     focused?: boolean;
     /** Whether the item is non-interactive. */
     disabled?: boolean;
+    /**
+     * Whether clicking the item closes the whole menu (in addition to running
+     * `onClick`).
+     * @default true for `menuitem`, false for `menuitemcheckbox` / `menuitemradio`
+     */
+    closeOnClick?: boolean;
+    /**
+     * Submenu content (MenuItem / MenuGroup). When provided, the item becomes a
+     * submenu trigger that opens on hover, click, or ArrowRight.
+     * @a11y Recommended — exposes `aria-haspopup="menu"` and `aria-expanded`.
+     */
+    submenu?: ReactNode;
+    /** Where the submenu opens relative to the item. @default 'right' */
+    submenuPlacement?: MenuPlacement;
 };
 
 type MenuComponent = FC<MenuProps> & {
@@ -1551,5 +2871,5 @@ declare const lightTheme: Theme;
 
 declare const darkTheme: Theme;
 
-export { Alert, Backdrop, Badge, Box, Breadcrumb, Button, Card, Checkbox, Dialog, Drawer, Form, Grid, Icon, IconButton, InfoBubble, Link, Menu, Select, Skeleton, Stack, Switch, Tabs, Text, TextField, Tooltip, darkTheme, lightTheme, useDrawerContext };
-export type { AlertBodyProps, AlertProps, AlertTitleProps, AlertVariant, BackdropProps, BadgeColor, BadgeIcon, BadgeProps, BadgeSize, BadgeVariant, BoxProps, BreadcrumbItemProps, BreadcrumbProps, BreadcrumbSeparator, ButtonColor, ButtonIcon, ButtonProps, ButtonSize, ButtonVariant, CardBodyProps, CardHeaderProps, CardProps, CardVariant, CheckboxProps, DialogBodyProps, DialogHeaderProps, DialogProps, DrawerBodyProps, DrawerFooterProps, DrawerHeaderProps, DrawerItemIcon, DrawerItemProps, DrawerProps, DrawerVariant, FormProps, GridProps, GridStyleProps, IconButtonProps, IconProps, IconStyleParams, InfoBubbleProps, LinkColor, LinkIcon, LinkProps, LinkUnderline, MenuGroupProps, MenuItemProps, MenuProps, Palette, SelectOption, SelectProps, SkeletonAnimation, SkeletonProps, SkeletonVariant, StackProps, SwitchColor, SwitchProps, SwitchSize, TabItemProps, TabsListProps, TabsPanelProps, TabsProps, TextFieldProps, TextFieldSize, TextFieldStatus, TextProps, TextStyleParams, TextVariantStyle, TextVariants, Theme, TooltipPlacement, TooltipProps };
+export { Accordion, Alert, Article, Aside, Avatar, AvatarGroup, Backdrop, Badge, Box, Breadcrumb, Button, Card, Checkbox, DatePicker, DefaultErrorFallback, Dialog, Drawer, ErrorBoundary, Fab, Footer, Form, Grid, Header, Icon, IconButton, Image, InfoBubble, Link, LoaderScreen, Main, Menu, Nav, Pagination, RadioButton, RadioGroup, Section, Select, Separator, Skeleton, Stack, SvgImage, Switch, Table, Tabs, Text, TextField, ToggleButton, ToggleGroup, ToggleIconButton, Tooltip, darkTheme, lightTheme, useDrawerContext };
+export type { AccordionBodyProps, AccordionProps, AccordionTitleProps, AlertBodyProps, AlertProps, AlertTitleProps, AlertVariant, ArticleProps, AsideProps, AvatarColor, AvatarGroupOverlap, AvatarGroupProps, AvatarProps, AvatarShape, AvatarSize, BackdropProps, BadgeColor, BadgeIcon, BadgeProps, BadgeSize, BadgeVariant, BoxProps, BreadcrumbItemProps, BreadcrumbProps, BreadcrumbSeparator, ButtonColor, ButtonIcon, ButtonProps, ButtonSize, ButtonVariant, CardBodyProps, CardHeaderProps, CardProps, CardVariant, CheckboxProps, DatePickerProps, DatePickerSize, DatePickerStatus, DefaultErrorFallbackProps, DialogBodyProps, DialogHeaderProps, DialogProps, DrawerBodyProps, DrawerFooterProps, DrawerHeaderProps, DrawerItemIcon, DrawerItemProps, DrawerProps, DrawerVariant, ErrorBoundaryFallbackRenderProps, ErrorBoundaryProps, FabColor, FabIcon, FabPlacement, FabProps, FabSize, FooterProps, FormProps, GridProps, GridStyleProps, HeaderProps, IconButtonProps, IconProps, IconStyleParams, ImageProps, InfoBubbleProps, LinkColor, LinkIcon, LinkProps, LinkUnderline, LoaderScreenProps, MainProps, MenuGroupProps, MenuItemProps, MenuItemRole, MenuPlacement, MenuProps, NavProps, PaginationProps, PaginationShape, PaginationSize, Palette, RadioButtonProps, RadioGroupProps, SectionProps, SelectOption, SelectProps, SeparatorOrientation, SeparatorProps, SeparatorStyleParams, SeparatorThickness, SkeletonAnimation, SkeletonProps, SkeletonVariant, StackProps, SvgImageProps, SwitchColor, SwitchProps, SwitchSize, TabItemProps, TableAlign, TableBodyProps, TableCellProps, TableColumn, TableFootProps, TableHeadProps, TableHeaderCellProps, TableLayout, TableProps, TableRowProps, TabsListProps, TabsPanelProps, TabsProps, TextFieldProps, TextFieldSize, TextFieldStatus, TextProps, TextStyleParams, TextVariantStyle, TextVariants, Theme, ToggleButtonProps, ToggleButtonVariant, ToggleGroupProps, ToggleIconButtonProps, TooltipPlacement, TooltipProps, WeekStart };