@aurora-ds/components 1.1.7 → 1.2.0

package/dist/index.d.ts

@@ -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;
@@ -337,10 +343,29 @@ 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"`. */
+    /**
+     * 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 +375,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 +412,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 +433,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 +475,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 +515,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 +561,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 +605,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 +639,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 +687,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 +716,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 +744,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 +810,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 +846,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;
@@ -983,44 +1079,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 +1161,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 +1176,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'];
 };
 
@@ -1073,7 +1229,10 @@ type DrawerContextValue = {
 declare const useDrawerContext: () => DrawerContextValue;
 
 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 +1293,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 +1310,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 +1357,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 +1382,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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aurora-ds/components",
-  "version": "1.1.7",
+  "version": "1.2.0",
   "type": "module",
   "description": "Aurora DS - React Components Library",
   "main": "dist/cjs/index.js",