@aurora-ds/components 1.1.7 → 1.4.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ComponentType, SVGProps, ButtonHTMLAttributes, Ref, FC, AnchorHTMLAttributes, HTMLAttributes, ReactNode, CSSProperties, FormEvent, InputHTMLAttributes, AriaRole, AriaAttributes } from 'react';
+import { ComponentType, SVGProps, ButtonHTMLAttributes, Ref, FC, AnchorHTMLAttributes, HTMLAttributes, ReactNode, CSSProperties, FormEvent, InputHTMLAttributes, MouseEvent, AriaRole, AriaAttributes } from 'react';
 
 declare const lightPalette: {
     surfaceBackground: string;
@@ -282,8 +282,11 @@ type ButtonProps = ButtonHTMLAttributes<HTMLButtonElement> & {
     isLoading?: boolean;
     /** Native button type. @default 'button' */
     type?: 'button' | 'submit' | 'reset';
-    /** Text label displayed inside the button. */
-    label: string;
+    /**
+     * Text label displayed inside the button. Can also pass children directly.
+     * @a11y Recommended — provides the button's accessible name. With no visible text, prefer `IconButton` with `ariaLabel`.
+     */
+    label?: string;
     /** SVG icon component rendered before the label (inherits the button color). */
     startIcon?: ButtonIcon;
     /** SVG icon component rendered after the label (inherits the button color). */
@@ -304,7 +307,10 @@ type IconButtonProps = Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'children'
     ref?: Ref<HTMLButtonElement>;
     /** SVG icon component to render inside the button. */
     icon: ButtonIcon;
-    /** Accessible label — required since there is no visible text. */
+    /**
+     * Accessible label — required since there is no visible text.
+     * @a11y Required — the button's only accessible name (no visible text). Describe the action, not the icon (e.g. "Close" rather than "Cross").
+     */
     ariaLabel: string;
     /** Visual style. @default 'contained' */
     variant?: ButtonVariant;
@@ -329,6 +335,8 @@ type IconButtonProps = Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'children'
 declare const IconButton: FC<IconButtonProps>;
 
 type LinkUnderline = 'always' | 'hover' | 'none';
+/** Controls the link color palette. `'default'` uses the brand blue, `'secondary'` uses `textSecondary`. */
+type LinkColor = 'default' | 'secondary';
 
 /** SVG icon component, e.g. imported via `?react` or taken from the `IconRegistry`. */
 type LinkIcon = ComponentType<SVGProps<SVGSVGElement>>;
@@ -337,10 +345,35 @@ type LinkProps = AnchorHTMLAttributes<HTMLAnchorElement> & {
     ref?: Ref<HTMLAnchorElement>;
     /** Controls when the underline is visible. @default 'hover' */
     underline?: LinkUnderline;
-    /** Open in a new tab with `rel="noopener noreferrer"`. */
+    /**
+     * Color palette variant. `'default'` uses the brand blue link color,
+     * `'secondary'` uses the `textSecondary` color token.
+     * @default 'default'
+     */
+    color?: LinkColor;
+    /**
+     * Open in a new tab with `rel="noopener noreferrer"`.
+     * @a11y Recommended — warn users that a new tab will open (via visible text or `aria-label`).
+     */
     external?: boolean;
-    /** Prevent navigation and style as inactive. */
+    /**
+     * Prevent navigation and style as inactive.
+     * @a11y Sets `aria-disabled`, removes the element from the tab order.
+     */
     disabled?: boolean;
+    /**
+     * The URL to navigate to. When omitted (SPA navigation via `onClick`),
+     * the component automatically adds `role="link"`, `tabIndex={0}` and
+     * handles Enter-key activation so that accessibility is preserved.
+     *
+     * @example
+     * // Standard href
+     * <Link href="/about">About</Link>
+     *
+     * // React Router (no href)
+     * <Link onClick={() => navigate('/about')}>About</Link>
+     */
+    href?: string;
     /** SVG icon rendered before the text. */
     startIcon?: LinkIcon;
     /** SVG icon rendered after the text. */
@@ -350,10 +383,15 @@ type LinkProps = AnchorHTMLAttributes<HTMLAnchorElement> & {
 /**
  * Theme-aware anchor element with optional icons and underline control.
  *
+ * Supports SPA navigation (e.g. React Router) via `onClick` without `href`.
+ * In that case the component stays accessible: it gets `role="link"`,
+ * `tabIndex={0}` and keyboard Enter support automatically.
+ *
  * @example <Link href='/about'>About</Link>
  * @example <Link href='https://example.com' external>External site</Link>
  * @example <Link href='/profile' underline='always' startIcon={UserIcon}>Profile</Link>
  * @example <Link href='/terms' underline='none'>Terms</Link>
+ * @example <Link onClick={() => navigate('/about')}>About (SPA)</Link>
  */
 declare const Link: FC<LinkProps>;
 
@@ -382,7 +420,10 @@ type BadgeProps = HTMLAttributes<HTMLSpanElement> & {
     endIcon?: BadgeIcon;
     /** @deprecated Use `startIcon` instead. */
     icon?: BadgeIcon;
-    /** Render as a small colored dot indicator — children and icons are ignored. @default false */
+    /**
+     * Render as a small colored dot indicator — children and icons are ignored. @default false
+     * @a11y Recommended — a dot conveys meaning visually only; add `role="img"` + `aria-label` (via the spread props) to describe it.
+     */
     dot?: boolean;
 };
 
@@ -400,7 +441,10 @@ type TooltipPlacement = 'top' | 'bottom' | 'left' | 'right';
 interface TooltipProps {
     /** Content that triggers the tooltip on hover/focus. */
     children: ReactNode;
-    /** Text displayed inside the tooltip bubble. */
+    /**
+     * Text displayed inside the tooltip bubble.
+     * @a11y Recommended — exposed to assistive tech; keep it concise as it describes the trigger.
+     */
     label: string;
     /** Placement of the tooltip relative to the trigger element. @default 'right' */
     placement?: TooltipPlacement;
@@ -439,7 +483,10 @@ interface TooltipProps {
 }
 
 interface InfoBubbleProps {
-    /** Text displayed inside the tooltip bubble. */
+    /**
+     * Text displayed inside the tooltip bubble.
+     * @a11y Recommended — provides the accessible name/description of the info trigger.
+     */
     label: string;
     /** Placement of the tooltip relative to the info icon. @default 'top' */
     placement?: TooltipPlacement;
@@ -476,7 +523,10 @@ declare const InfoBubble: FC<InfoBubbleProps>;
 
 type IconProps = HTMLAttributes<HTMLDivElement> & {
     ref?: Ref<HTMLDivElement>;
-    /** SVG component to render — import with `?react` (e.g. `import MyIcon from './my-icon.svg?react'`). */
+    /**
+     * SVG component to render — import with `?react` (e.g. `import MyIcon from './my-icon.svg?react'`).
+     * @a11y Recommended — decorative by default (`aria-hidden`). When meaningful, pass `role="img"` + `aria-label` through the spread props.
+     */
     icon: ComponentType<SVGProps<SVGSVGElement>>;
     /** Size token mapped to `theme.fontSize`. Controls both width and height. @default 'md' */
     size?: keyof Theme['fontSize'];
@@ -519,7 +569,10 @@ type SkeletonAnimation = 'shimmer' | false;
 
 type SkeletonProps = HTMLAttributes<HTMLSpanElement> & {
     ref?: Ref<HTMLSpanElement>;
-    /** Shape of the placeholder: `'text'` | `'circular'` | `'rectangular'` | `'rounded'`. @default 'rounded' */
+    /**
+     * Shape of the placeholder: `'text'` | `'circular'` | `'rectangular'` | `'rounded'`. @default 'rounded'
+     * @a11y Recommended — convey loading state to assistive tech by wrapping the region with `aria-busy="true"` (or `role="status"`).
+     */
     variant?: SkeletonVariant;
     /** Loading animation: `'shimmer'` (default) or `false` to disable. */
     animation?: SkeletonAnimation;
@@ -560,9 +613,15 @@ type TextVariantStyle = {
 
 type TextProps = HTMLAttributes<HTMLElement> & {
     ref?: Ref<HTMLElement>;
-    /** Semantic variant — determines the rendered HTML tag and baseline styles. @default 'span' */
+    /**
+     * Semantic variant — determines the rendered HTML tag and baseline styles. @default 'span'
+     * @a11y Recommended — pick the variant matching the document outline (e.g. `h1`–`h6`, `p`) so semantics are conveyed to assistive tech.
+     */
     variant?: TextVariants;
-    /** Override the rendered HTML tag while keeping variant styles (e.g. `variant="h1" as="h2"`). */
+    /**
+     * Override the rendered HTML tag while keeping variant styles (e.g. `variant="h1" as="h2"`).
+     * @a11y Recommended — keep the rendered tag consistent with the heading level expected by the page outline.
+     */
     as?: string;
     /** Theme color token — e.g. `'textPrimary'`, `'errorMain'`, `'linkHover'`. @default 'inherit' */
     color?: keyof Theme['colors'];
@@ -588,7 +647,10 @@ type TextProps = HTMLAttributes<HTMLElement> & {
     noWrap?: boolean;
     /** Preserve whitespace and line breaks (`white-space: pre-wrap`). */
     preserveWhitespace?: boolean;
-    /** Associates a `<label>` with an input — only meaningful when `variant` or `as` is `"label"`. */
+    /**
+     * Associates a `<label>` with an input — only meaningful when `variant` or `as` is `"label"`.
+     * @a11y Recommended — link the label to its control's `id` so clicking the label focuses the input.
+     */
     htmlFor?: string;
     /** Explicit CSS width applied as a style property (not an HTML attribute). */
     width?: CSSProperties['width'];
@@ -633,9 +695,15 @@ type FormProps = {
     children: ReactNode;
     /** Called when the form is submitted. Receives the native submit event. */
     onSubmit: (event: FormEvent<HTMLFormElement>) => void;
-    /** Accessible name for the form. */
+    /**
+     * Accessible name for the form.
+     * @a11y Recommended — names the form landmark; use `aria-labelledby` instead when a visible heading exists.
+     */
     'aria-label'?: string;
-    /** Id of an element that labels the form. */
+    /**
+     * Id of an element that labels the form.
+     * @a11y Recommended — references a visible heading to name the form landmark.
+     */
     'aria-labelledby'?: string;
 };
 
@@ -656,7 +724,10 @@ type SwitchColor = 'primary' | 'success' | 'error' | 'warning' | 'info' | 'neutr
 
 type SwitchProps = Omit<InputHTMLAttributes<HTMLInputElement>, 'size' | 'type'> & {
     ref?: Ref<HTMLInputElement>;
-    /** Visible label rendered next to the switch. */
+    /**
+     * Visible label rendered next to the switch.
+     * @a11y Recommended — provides the switch's accessible name. Without it, set `aria-label` instead.
+     */
     label?: string;
     /** Size variant. @default 'md' */
     size?: SwitchSize;
@@ -681,13 +752,22 @@ type TextFieldStatus = 'default' | 'error' | 'success' | 'warning';
 
 type TextFieldProps = Omit<InputHTMLAttributes<HTMLInputElement>, 'size'> & {
     ref?: Ref<HTMLInputElement>;
-    /** Visible label rendered above the field. */
+    /**
+     * Visible label rendered above the field.
+     * @a11y Recommended — provides the input's accessible name (linked via `htmlFor`/`id`).
+     */
     label?: string;
-    /** Helper text or validation message rendered below the field. */
+    /**
+     * 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;
     /** Size variant controlling height, padding and font size. @default 'md' */
     size?: TextFieldSize;
-    /** Semantic status affecting border and helper text color. @default 'default' */
+    /**
+     * Semantic status affecting border and helper text color. @default 'default'
+     * @a11y Recommended — `status='error'` sets `aria-invalid` on the input.
+     */
     status?: TextFieldStatus;
     /** SVG icon component rendered on the left inside the field. */
     startIcon?: ComponentType<SVGProps<SVGSVGElement>>;
@@ -738,19 +818,31 @@ type SelectProps = {
     onChange?: (value: string) => void;
     /** List of options. */
     options?: SelectOption[];
-    /** Label rendered above the trigger. */
+    /**
+     * Label rendered above the trigger.
+     * @a11y Recommended — associates an accessible name with the combobox via `aria-labelledby`.
+     */
     label?: string;
-    /** Helper text or validation message rendered below the trigger. */
+    /**
+     * Helper text or validation message rendered below the trigger.
+     * @a11y Recommended — linked to the trigger via `aria-describedby` (and `aria-errormessage` when `status='error'`).
+     */
     helperText?: string;
     /** Placeholder shown when no option is selected. */
     placeholder?: string;
     /** Size variant. @default 'md' */
     size?: TextFieldSize;
-    /** Semantic status affecting border and helper text color. @default 'default' */
+    /**
+     * Semantic status affecting border and helper text color. @default 'default'
+     * @a11y Recommended — `status='error'` sets `aria-invalid` and links the error message.
+     */
     status?: TextFieldStatus;
     /** Whether the select is disabled. */
     disabled?: boolean;
-    /** Whether the field is required. */
+    /**
+     * Whether the field is required.
+     * @a11y Recommended — sets `aria-required` on the combobox and shows the visual asterisk on the label.
+     */
     required?: boolean;
     /** Fixed width for the select. Defaults to 100% of its container. */
     width?: string | number;
@@ -762,15 +854,27 @@ declare const Select: FC<SelectProps>;
 
 type CheckboxProps = Omit<InputHTMLAttributes<HTMLInputElement>, 'type' | 'size'> & {
     ref?: Ref<HTMLInputElement>;
-    /** Visible label rendered next to the checkbox. */
+    /**
+     * Visible label rendered next to the checkbox.
+     * @a11y Recommended — provides the checkbox's accessible name (clickable to toggle it).
+     */
     label?: ReactNode;
-    /** Helper text or validation message rendered below the checkbox row. */
+    /**
+     * Helper text or validation message rendered below the checkbox row.
+     * @a11y Recommended — linked to the input via `aria-describedby`.
+     */
     helperText?: string;
     /** Size variant controlling checkbox box size and text scale. @default 'md' */
     size?: TextFieldSize;
-    /** Semantic status affecting border and helper text color. @default 'default' */
+    /**
+     * Semantic status affecting border and helper text color. @default 'default'
+     * @a11y Recommended — `status='error'` sets `aria-invalid` on the input.
+     */
     status?: TextFieldStatus;
-    /** Sets the native checkbox in indeterminate (mixed) state. */
+    /**
+     * Sets the native checkbox in indeterminate (mixed) state.
+     * @a11y Recommended — exposes the mixed state via `aria-checked="mixed"`.
+     */
     indeterminate?: boolean;
     /** @deprecated Use `status='error'` instead. Kept for backward compatibility. */
     error?: boolean;
@@ -950,6 +1054,61 @@ declare const Grid: FC<GridProps>;
  */
 declare const Stack: FC<StackProps>;
 
+/** Separator character rendered between breadcrumb items. */
+type BreadcrumbSeparator = '/' | '-' | '>';
+
+type BreadcrumbProps = {
+    /** Breadcrumb items — use `Breadcrumb.Item` as children. */
+    children: ReactNode;
+    /**
+     * Character rendered between each breadcrumb item.
+     * @default '/'
+     */
+    separator?: BreadcrumbSeparator;
+    /**
+     * Accessible label for the `<nav>` landmark.
+     * @default 'Breadcrumb'
+     * @a11y Recommended — describe the navigation to assistive technologies.
+     */
+    ariaLabel?: string;
+};
+
+type BreadcrumbItemProps = {
+    /** Text label of the breadcrumb item. */
+    label: string;
+    /**
+     * URL to navigate to.
+     * Can be omitted when using SPA navigation via `onClick` (e.g. React Router).
+     */
+    href?: string;
+    /**
+     * SPA navigation handler (e.g. React Router's `navigate`).
+     * When provided without `href`, the link stays accessible: `role="link"`,
+     * `tabIndex={0}` and Enter-key activation are handled automatically by `Link`.
+     *
+     * @example
+     * <Breadcrumb.Item label="Products" onClick={() => navigate('/products')} />
+     */
+    onClick?: (e: MouseEvent<HTMLAnchorElement>) => void;
+    /**
+     * Marks this item as the current page. Renders as bold text (non-clickable)
+     * and sets `aria-current="page"`.
+     * @default false
+     */
+    current?: boolean;
+    /**
+     * Injected internally by `Breadcrumb` — hides the separator for the first item.
+     * @internal
+     */
+    isFirst?: boolean;
+};
+
+type BreadcrumbComponent = FC<BreadcrumbProps> & {
+    Item: FC<BreadcrumbItemProps>;
+};
+
+declare const Breadcrumb: BreadcrumbComponent;
+
 /**
  * Layout variant for the Drawer.
  * - `'permanent'` — inline drawer that pushes page content (default on desktop).
@@ -983,44 +1142,80 @@ type DrawerProps = {
     onClose?: () => void;
     /** ARIA role applied to the root navigation container. @default 'navigation' */
     role?: AriaRole;
-    /** Accessible name for the drawer landmark. @default 'Navigation' */
+    /**
+     * Accessible name for the drawer landmark. @default 'Navigation'
+     * @a11y Recommended — distinguishes this landmark when several navigation regions exist on the page.
+     */
     ariaLabel?: string;
-    /** Id of the element that labels the drawer landmark. */
+    /**
+     * Id of the element that labels the drawer landmark.
+     * @a11y Recommended — references a visible heading to name the landmark (alternative to `ariaLabel`).
+     */
     ariaLabelledBy?: string;
-    /** Id of the element that describes the drawer landmark. */
+    /**
+     * Id of the element that describes the drawer landmark.
+     * @a11y Recommended — references descriptive text via `aria-describedby`.
+     */
     ariaDescribedBy?: string;
 };
 
 type DrawerHeaderProps = Omit<BoxProps, 'aria-label' | 'aria-labelledby' | 'aria-describedby'> & {
     /** ARIA role applied to the header container. */
     role?: AriaRole;
-    /** Accessible name for the header region. */
+    /**
+     * Accessible name for the header region.
+     * @a11y Recommended — names the header region for assistive tech.
+     */
     ariaLabel?: string;
-    /** Id of the element that labels the header region. */
+    /**
+     * Id of the element that labels the header region.
+     * @a11y Recommended — references a visible heading via `aria-labelledby`.
+     */
     ariaLabelledBy?: string;
-    /** Id of the element that describes the header region. */
+    /**
+     * Id of the element that describes the header region.
+     * @a11y Recommended — references descriptive text via `aria-describedby`.
+     */
     ariaDescribedBy?: string;
 };
 
 type DrawerBodyProps = Omit<BoxProps, 'aria-label' | 'aria-labelledby' | 'aria-describedby'> & {
     /** ARIA role applied to the body container. */
     role?: AriaRole;
-    /** Accessible name for the body region. */
+    /**
+     * Accessible name for the body region.
+     * @a11y Recommended — names the body region for assistive tech.
+     */
     ariaLabel?: string;
-    /** Id of the element that labels the body region. */
+    /**
+     * Id of the element that labels the body region.
+     * @a11y Recommended — references a visible heading via `aria-labelledby`.
+     */
     ariaLabelledBy?: string;
-    /** Id of the element that describes the body region. */
+    /**
+     * Id of the element that describes the body region.
+     * @a11y Recommended — references descriptive text via `aria-describedby`.
+     */
     ariaDescribedBy?: string;
 };
 
 type DrawerFooterProps = Omit<BoxProps, 'aria-label' | 'aria-labelledby' | 'aria-describedby'> & {
     /** ARIA role applied to the footer container. */
     role?: AriaRole;
-    /** Accessible name for the footer region. */
+    /**
+     * Accessible name for the footer region.
+     * @a11y Recommended — names the footer region for assistive tech.
+     */
     ariaLabel?: string;
-    /** Id of the element that labels the footer region. */
+    /**
+     * Id of the element that labels the footer region.
+     * @a11y Recommended — references a visible heading via `aria-labelledby`.
+     */
     ariaLabelledBy?: string;
-    /** Id of the element that describes the footer region. */
+    /**
+     * Id of the element that describes the footer region.
+     * @a11y Recommended — references descriptive text via `aria-describedby`.
+     */
     ariaDescribedBy?: string;
 };
 
@@ -1029,7 +1224,10 @@ type DrawerItemIcon = ComponentType<SVGProps<SVGSVGElement>>;
 type DrawerItemProps = {
     /** SVG icon shown in both expanded and collapsed states. */
     startIcon: DrawerItemIcon;
-    /** Text label — visible when expanded, shown as tooltip when collapsed. */
+    /**
+     * Text label — visible when expanded, shown as tooltip when collapsed.
+     * @a11y Recommended — provides the item's accessible name in both expanded and collapsed states.
+     */
     label: string;
     /** Marks the item as selected/active. @default false */
     selected?: boolean;
@@ -1041,19 +1239,40 @@ type DrawerItemProps = {
     onClick?: () => void;
     /** Prevents interaction and dims the item. @default false */
     disabled?: boolean;
-    /** Accessible label override (by default uses `label` when collapsed). */
+    /**
+     * Accessible label override (by default uses `label` when collapsed).
+     * @a11y Recommended — override the accessible name when `label` is not descriptive enough.
+     */
     ariaLabel?: string;
-    /** Id of the element that labels this item. */
+    /**
+     * Id of the element that labels this item.
+     * @a11y Recommended — references an external label via `aria-labelledby`.
+     */
     ariaLabelledBy?: string;
-    /** Id of the element that describes this item. */
+    /**
+     * Id of the element that describes this item.
+     * @a11y Recommended — references descriptive text via `aria-describedby`.
+     */
     ariaDescribedBy?: string;
-    /** Id of the element controlled by this item. */
+    /**
+     * Id of the element controlled by this item.
+     * @a11y Recommended — set with `ariaExpanded` when the item toggles a submenu/panel.
+     */
     ariaControls?: string;
-    /** Whether the controlled element is expanded/collapsed. */
+    /**
+     * Whether the controlled element is expanded/collapsed.
+     * @a11y Recommended — exposes the expanded state of the controlled element via `aria-expanded`.
+     */
     ariaExpanded?: boolean;
-    /** Indicates popup behavior when item triggers a menu/dialog/listbox/tree/grid. */
+    /**
+     * Indicates popup behavior when item triggers a menu/dialog/listbox/tree/grid.
+     * @a11y Recommended — set `aria-haspopup` when the item opens an overlay.
+     */
     ariaHasPopup?: AriaAttributes['aria-haspopup'];
-    /** Explicit current state. Defaults to `page` when `selected` is true. */
+    /**
+     * Explicit current state. Defaults to `page` when `selected` is true.
+     * @a11y Recommended — exposes the active item to assistive tech via `aria-current`.
+     */
     ariaCurrent?: AriaAttributes['aria-current'];
 };
 
@@ -1072,8 +1291,67 @@ type DrawerContextValue = {
 };
 declare const useDrawerContext: () => DrawerContextValue;
 
+type TabsProps = {
+    /** Children — typically a `Tabs.List` with `Tabs.Tab`s and one or more `Tabs.Panel`s. */
+    children: ReactNode;
+    /** Controlled selected tab value. */
+    value?: string;
+    /** Default selected tab value when uncontrolled. */
+    defaultValue?: string;
+    /** Called whenever the selected tab changes. */
+    onChange?: (value: string) => void;
+    /** Optional id prefix used to derive `id`/`aria-controls`/`aria-labelledby`. */
+    id?: string;
+};
+
+type TabsListProps = {
+    /** `Tabs.Tab` children. */
+    children: ReactNode;
+    /** Accessible label for the tablist (required by WAI-ARIA when no visible label exists). */
+    ariaLabel?: string;
+    /** Id of an element labelling the tablist (alternative to `ariaLabel`). */
+    ariaLabelledBy?: string;
+};
+
+type TabItemProps = {
+    /** Unique value identifying this tab — must match the corresponding `Tabs.Panel` value. */
+    value: string;
+    /** Visible label of the tab. */
+    label: string;
+    /**
+     * Disables the tab. Sets `aria-disabled="true"` without removing the element from
+     * the focus tree — screen readers can still announce its existence.
+     * Click and keyboard activation are blocked programmatically.
+     * Disabled tabs are skipped during ArrowLeft/Right/Home/End keyboard navigation.
+     */
+    disabled?: boolean;
+};
+
+type TabsPanelProps = {
+    /** Value of the tab this panel is associated with. */
+    value: string;
+    /** Panel content. Only rendered when its tab is active (no DOM cost when inactive). */
+    children: ReactNode;
+    /**
+     * Keep the panel mounted even when inactive (set `hidden` instead of unmount).
+     * Useful when the panel holds expensive state that should survive tab switches.
+     */
+    keepMounted?: boolean;
+};
+
+type TabsComponent = FC<TabsProps> & {
+    List: FC<TabsListProps>;
+    Tab: FC<TabItemProps>;
+    Panel: FC<TabsPanelProps>;
+};
+
+declare const Tabs: TabsComponent;
+
 type AlertProps = {
-    /** Visual style of the alert. @default 'default' */
+    /**
+     * Visual style of the alert. @default 'default'
+     * @a11y Recommended — `'error'` renders `role="alert"` + `aria-live="assertive"`; other variants use `role="status"` + `aria-live="polite"`.
+     */
     variant?: AlertVariant;
     /** Alert sub-components: Alert.Title and/or Alert.Body. */
     children?: ReactNode;
@@ -1134,7 +1412,10 @@ declare const Backdrop: FC<BackdropProps>;
 type DialogProps = {
     /** Whether the dialog is visible. */
     open: boolean;
-    /** Called when the dialog should close (Escape key or close button). */
+    /**
+     * Called when the dialog should close (Escape key or close button).
+     * @a11y Recommended — enables closing via Escape, which assistive-tech users expect.
+     */
     onClose: () => void;
     /** Whether clicking the backdrop closes the dialog. @default false */
     closeOnBackdropClick?: boolean;
@@ -1148,16 +1429,25 @@ type DialogProps = {
     minHeight?: number | string;
     /** Whether the dialog takes the full viewport height on mobile (bottom-sheet variant). @default false */
     fullscreen?: boolean;
-    /** Accessible label — use when Dialog.Header is not present. */
+    /**
+     * Accessible label — use when Dialog.Header is not present.
+     * @a11y Recommended — provides the dialog's accessible name when there is no `Dialog.Header` title to reference.
+     */
     'aria-label'?: string;
     /** Dialog content. Typically Dialog.Header + Dialog.Body. */
     children: ReactNode;
 };
 
 type DialogHeaderProps = {
-    /** Dialog title displayed in the header. */
+    /**
+     * Dialog title displayed in the header.
+     * @a11y Recommended — labels the dialog via `aria-labelledby` (the accessible name).
+     */
     title: string;
-    /** Called when the close button is clicked. */
+    /**
+     * Called when the close button is clicked.
+     * @a11y Recommended — the close button exposes an accessible label for keyboard/screen-reader users.
+     */
     onClose: () => void;
 };
 
@@ -1186,6 +1476,16 @@ type MenuProps = {
     maxHeight?: string;
     /** ARIA id for the listbox 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-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.
+     */
+    'aria-labelledby'?: string;
     /** Menu content — MenuGroup and/or MenuItem. */
     children: ReactNode;
 };
@@ -1201,11 +1501,17 @@ type MenuGroupProps = {
 
 type MenuItemProps = HTMLAttributes<HTMLLIElement> & {
     ref?: Ref<HTMLLIElement>;
-    /** Display text of the item. */
+    /**
+     * Display text of the item.
+     * @a11y Recommended — provides the option's accessible name.
+     */
     label: string;
     /** Optional SVG icon rendered before the label. */
     icon?: ComponentType<SVGProps<SVGSVGElement>>;
-    /** Whether this item is currently selected. */
+    /**
+     * Whether this item is currently selected.
+     * @a11y Recommended — exposes the selected state via `aria-selected`.
+     */
     selected?: boolean;
     /** Whether this item has keyboard focus (highlighted via arrow navigation). */
     focused?: boolean;
@@ -1245,5 +1551,5 @@ declare const lightTheme: Theme;
 
 declare const darkTheme: Theme;
 
-export { Alert, Backdrop, Badge, Box, Button, Card, Checkbox, Dialog, Drawer, Form, Grid, Icon, IconButton, InfoBubble, Link, Menu, Select, Skeleton, Stack, Switch, Text, TextField, Tooltip, darkTheme, lightTheme, useDrawerContext };
-export type { AlertBodyProps, AlertProps, AlertTitleProps, AlertVariant, BackdropProps, BadgeColor, BadgeIcon, BadgeProps, BadgeSize, BadgeVariant, BoxProps, 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, LinkIcon, LinkProps, LinkUnderline, MenuGroupProps, MenuItemProps, MenuProps, Palette, SelectOption, SelectProps, SkeletonAnimation, SkeletonProps, SkeletonVariant, StackProps, SwitchColor, SwitchProps, SwitchSize, TextFieldProps, TextFieldSize, TextFieldStatus, TextProps, TextStyleParams, TextVariantStyle, TextVariants, Theme, TooltipPlacement, TooltipProps };
+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 };