@aurora-ds/components 0.24.9 → 0.25.1

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { PropsWithChildren, FC, ReactNode, MouseEvent, CSSProperties, FormEvent, FocusEvent, ComponentType, SVGProps, DragEvent, ComponentPropsWithoutRef, ReactElement, RefObject } from 'react';
+import { PropsWithChildren, FC, ReactNode, MouseEvent, KeyboardEvent, CSSProperties, FormEvent, FocusEvent, ComponentType, SVGProps, DragEvent, ComponentPropsWithoutRef, ReactElement, RefObject } from 'react';
 
 /**
  * Alert variant types
@@ -404,6 +404,8 @@ type TextProps = PropsWithChildren<{
     role?: string;
     /** Tab index for keyboard navigation */
     tabIndex?: number;
+    /** HTML id attribute (used for aria-labelledby / aria-describedby references) */
+    id?: string;
 }>;
 
 /**
@@ -471,10 +473,16 @@ declare const Status: FC<StatusProps>;
 type AvatarProps = {
     /** Image source URL */
     image?: string;
-    /** Fallback text to display when no image */
+    /**
+     * Fallback text to display when no image (initials, name, etc.)
+     * Also used as the image `alt` text for accessibility.
+     */
     label?: string;
-    /** Click handler */
-    onClick?: (e: MouseEvent<HTMLDivElement>) => void;
+    /**
+     * Click handler. When provided, the avatar becomes interactive
+     * with `role="button"` and keyboard support (Enter/Space).
+     */
+    onClick?: (e: MouseEvent<HTMLDivElement> | KeyboardEvent<HTMLDivElement>) => void;
     /** Size of the avatar */
     size?: AvatarSize;
     /** Text color for the label */
@@ -483,12 +491,34 @@ type AvatarProps = {
     borderColor?: string;
     /** Background color */
     backgroundColor?: string;
+    /**
+     * Accessibility label for screen readers.
+     * Defaults to `label` prop when not provided.
+     */
+    ariaLabel?: string;
+    /** Tab index for keyboard navigation (auto-set when onClick is provided) */
+    tabIndex?: number;
 };
 
 /**
  * Avatar component
  *
- * Displays a user's avatar with optional image or fallback text.
+ * Displays a user's avatar with an optional image or fallback initials.
+ *
+ * **Accessibility:**
+ * - When `onClick` is provided, the avatar becomes a focusable button
+ *   with keyboard support (Enter/Space activates the click)
+ * - Provide `label` or `ariaLabel` for screen readers
+ * - For decorative avatars, both can be omitted
+ *
+ * @example
+ * ```tsx
+ * // Static avatar with image
+ * <Avatar image="/user.jpg" label="Jane Doe" />
+ *
+ * // Interactive avatar (clickable)
+ * <Avatar label="JD" onClick={() => openProfile()} ariaLabel="Open Jane's profile" />
+ * ```
  */
 declare const Avatar: FC<AvatarProps>;
 
@@ -553,6 +583,16 @@ type ButtonProps = {
     role?: string;
     /** Tab index for keyboard navigation */
     tabIndex?: number;
+    /** Whether the button is in a pressed/active state (for toggle buttons) */
+    ariaPressed?: boolean;
+    /** Whether the button is in a loading/busy state */
+    ariaBusy?: boolean;
+    /** Whether the button controls an expandable section */
+    ariaExpanded?: boolean;
+    /** Whether the button has a popup (menu, dialog, etc.) */
+    ariaHasPopup?: boolean | 'menu' | 'listbox' | 'tree' | 'grid' | 'dialog';
+    /** ID of the element controlled by this button */
+    ariaControls?: string;
 };
 
 /**
@@ -562,6 +602,14 @@ type ButtonProps = {
  * - `contained`: Solid background button (default)
  * - `outlined`: Border only button
  * - `text`: Text only button without background
+ * - `destructive`: Danger/delete action button
+ *
+ * **Accessibility:**
+ * - Use `ariaLabel` when the button has no visible text or the label is unclear
+ * - Use `ariaPressed` for toggle buttons to indicate their state
+ * - Use `ariaBusy` when the button triggers an async action
+ * - Use `ariaExpanded` when the button controls a collapsible section
+ * - Use `ariaControls` to reference the controlled element
  */
 declare const Button: FC<ButtonProps>;
 
@@ -588,7 +636,7 @@ type IconButtonProps = {
     activeBackgroundColor?: keyof ThemeContract['colors'];
     /** Size of the icon button */
     size?: IconButtonSizes;
-    /** Accessibility label for screen readers */
+    /** Accessibility label for screen readers (strongly recommended for icon-only buttons) */
     ariaLabel?: string;
     /** ID of element that labels this button */
     ariaLabelledBy?: string;
@@ -598,8 +646,31 @@ type IconButtonProps = {
     role?: string;
     /** Tab index for keyboard navigation */
     tabIndex?: number;
+    /** Whether the button is in a pressed/active state (for toggle buttons) */
+    ariaPressed?: boolean;
+    /** Whether the button is in a loading/busy state */
+    ariaBusy?: boolean;
+    /** Whether the button controls an expandable section */
+    ariaExpanded?: boolean;
+    /** Whether the button has a popup (menu, dialog, etc.) */
+    ariaHasPopup?: boolean | 'menu' | 'listbox' | 'tree' | 'grid' | 'dialog';
+    /** ID of the element controlled by this button */
+    ariaControls?: string;
 };
 
+/**
+ * IconButton component
+ *
+ * A button that displays only an icon without text.
+ *
+ * **⚠️ Accessibility:** Always provide an `ariaLabel` for icon-only buttons
+ * so screen readers can describe the action.
+ *
+ * @example
+ * ```tsx
+ * <IconButton icon={<CloseIcon />} ariaLabel="Close dialog" onClick={onClose} />
+ * ```
+ */
 declare const IconButton: FC<IconButtonProps>;
 
 type ButtonToggleProps = {
@@ -719,7 +790,7 @@ type InputProps = {
     disabled?: boolean;
     /** Input type */
     type?: 'text' | 'password' | 'email' | 'number';
-    /** Accessibility label */
+    /** Accessibility label (defaults to `label` if not provided) */
     ariaLabel?: string;
     /** Icon to display before the input */
     startIcon?: ReactNode;
@@ -727,6 +798,13 @@ type InputProps = {
     endIcon?: ReactNode;
     /** Custom width for the input */
     width?: CSSProperties['width'];
+    /**
+     * Error message to display below the input.
+     * When provided, `aria-invalid="true"` and `aria-errormessage` are set automatically.
+     */
+    error?: string;
+    /** Unique HTML id for the input element (required when using `error`) */
+    id?: string;
 };
 
 declare const _default$2: react.MemoExoticComponent<react.ForwardRefExoticComponent<InputProps & react.RefAttributes<HTMLInputElement>>>;
@@ -748,7 +826,7 @@ type TextAreaProps = {
     placeholder?: string;
     /** Whether the textarea is disabled */
     disabled?: boolean;
-    /** Accessibility label */
+    /** Accessibility label (defaults to `label` if not provided) */
     ariaLabel?: string;
     /** Custom width for the textarea */
     width?: CSSProperties['width'];
@@ -756,6 +834,13 @@ type TextAreaProps = {
     minRows?: number;
     /** Maximum number of visible text lines (adds scroll when exceeded) */
     maxRows?: number;
+    /**
+     * Error message to display below the textarea.
+     * When provided, `aria-invalid="true"` and `aria-errormessage` are set automatically.
+     */
+    error?: string;
+    /** Unique HTML id for the textarea element (required when using `error`) */
+    id?: string;
 };
 
 declare const _default$1: react.MemoExoticComponent<react.ForwardRefExoticComponent<TextAreaProps & react.RefAttributes<HTMLTextAreaElement>>>;
@@ -793,10 +878,41 @@ type SelectProps = {
      * Width of the select
      */
     width?: string | number;
+    /**
+     * Error message to display below the select.
+     * When provided, `aria-invalid="true"` and `aria-errormessage` are set automatically.
+     */
+    error?: string;
+    /**
+     * Unique HTML id for the select trigger (required when using `error`)
+     */
+    id?: string;
+    /**
+     * Accessibility label for screen readers (defaults to `label`)
+     */
+    ariaLabel?: string;
 };
 
 /**
  * Select component that uses Menu for dropdown
+ *
+ * **Accessibility:**
+ * - Uses `role="combobox"` with `aria-expanded` and `aria-haspopup="listbox"`
+ * - Keyboard support: Enter/Space opens, Escape closes
+ * - When `error` is provided, `aria-invalid="true"` and `aria-errormessage` are set
+ * - `mandatory` adds `aria-required="true"`
+ *
+ * @example
+ * ```tsx
+ * <Select
+ *   options={[{ value: 'fr', label: 'France' }]}
+ *   value={country}
+ *   onChange={setCountry}
+ *   label="Country"
+ *   mandatory
+ *   error={countryError}
+ * />
+ * ```
  */
 declare const Select: FC<SelectProps>;
 
@@ -1516,6 +1632,11 @@ interface AlertProps {
  * - Smooth animations
  * - Dynamic height calculation for proper stacking
  *
+ * **Accessibility:**
+ * - Uses `role="alert"` for screen reader announcements
+ * - Error alerts use `aria-live="assertive"` for urgent announcements
+ * - Other variants use `aria-live="polite"` to avoid interrupting users
+ *
  * @example
  * ```tsx
  * <Alert
@@ -1576,6 +1697,30 @@ type ModalProps = {
     action?: ButtonProps;
 };
 
+/**
+ * Modal component
+ *
+ * An overlay dialog for focused interactions.
+ *
+ * **Accessibility:**
+ * - Uses `role="dialog"` and `aria-modal="true"` for screen readers
+ * - `aria-labelledby` links to the modal title
+ * - Focus is trapped inside the modal while it is open
+ * - Focus returns to the triggering element when closed
+ * - Escape key closes the modal
+ *
+ * @example
+ * ```tsx
+ * <Modal
+ *   isOpen={isOpen}
+ *   onClose={() => setIsOpen(false)}
+ *   label="Confirm deletion"
+ *   action={{ label: 'Delete', onClick: handleDelete }}
+ * >
+ *   <Text>Are you sure you want to delete this item?</Text>
+ * </Modal>
+ * ```
+ */
 declare const Modal: FC<ModalProps>;
 
 type DrawerItemProps = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aurora-ds/components",
-  "version": "0.24.9",
+  "version": "0.25.1",
   "type": "module",
   "description": "Aurora DS - React Components Library",
   "main": "dist/cjs/index.js",
@@ -24,7 +24,7 @@
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {
-    "@aurora-ds/theme": "^3.2.0",
+    "@aurora-ds/theme": "^3.2.9",
     "@babel/core": "^7.23.0",
     "@babel/preset-env": "^7.23.0",
     "@babel/preset-react": "^7.23.0",