@aurora-ds/components 0.24.9 → 0.25.1

package/dist/esm/index.js

@@ -1,5 +1,5 @@
 import { jsx, jsxs, Fragment as Fragment$1 } from 'react/jsx-runtime';
-import React, { Children, isValidElement, cloneElement, createElement, Fragment, useMemo, memo, useCallback, forwardRef, useState, useRef, useEffect, useLayoutEffect, createContext, useContext } from 'react';
+import React, { Children, isValidElement, cloneElement, createElement, Fragment, useMemo, memo, useCallback, forwardRef, useId, useState, useRef, useEffect, useLayoutEffect, createContext, useContext } from 'react';
 import { createStyles, useTheme, keyframes, colors } from '@aurora-ds/theme';
 import { createPortal } from 'react-dom';
 
@@ -226,7 +226,7 @@ const parseTextWithBold = (children) => {
  * - Preserve whitespace with `preserveWhitespace` prop
  * - Bold text with **double asterisks** syntax
  */
-const Text = ({ children, variant = 'span', color, fontSize, fontFamily, maxLines, underline, preserveWhitespace, ariaLabel, ariaLabelledBy, ariaDescribedBy, role, tabIndex, }) => {
+const Text = ({ children, variant = 'span', color, fontSize, fontFamily, maxLines, underline, preserveWhitespace, ariaLabel, ariaLabelledBy, ariaDescribedBy, role, tabIndex, id, }) => {
     const theme = useTheme();
     const variantStyles = useMemo(() => getTextVariantStyles(theme), [theme]);
     const tag = variantStyles[variant].tag;
@@ -234,6 +234,7 @@ const Text = ({ children, variant = 'span', color, fontSize, fontFamily, maxLine
     // Force inline truncate styles when needed (fix for multi-line clamp not applied in some envs)
     const truncateStyles = maxLines ? getTruncateTextStyles(maxLines) : undefined;
     return createElement(tag, {
+        id,
         className: TEXT_STYLES.root({ variant, color, fontSize, fontFamily, maxLines, underline, preserveWhitespace }),
         style: truncateStyles,
         'aria-label': ariaLabel,
@@ -530,20 +531,37 @@ const AVATAR_STYLES = createStyles((theme) => {
 /**
  * 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" />
+ * ```
  */
-const Avatar = ({ image, label, onClick, size = 'medium', color, borderColor, backgroundColor, }) => {
+const Avatar = ({ image, label, onClick, size = 'medium', color, borderColor, backgroundColor, ariaLabel, tabIndex, }) => {
     // hooks
     const theme = useTheme();
     // variables
     const AVATAR_SIZES = getAvatarSizes(theme);
     const hasImage = !!image;
     const clickable = !!onClick;
-    return (jsx("div", { className: AVATAR_STYLES.root({ hasImage, clickable, size, color, borderColor, backgroundColor }), onClick: (event) => {
-            if (onClick) {
-                onClick(event);
-            }
-        }, children: hasImage ? (jsx("img", { src: image, alt: label || 'Avatar', className: AVATAR_STYLES.image })) : (jsx(Text, { variant: 'label', fontSize: AVATAR_SIZES[size].fontSize, children: label || '?' })) }));
+    const handleKeyDown = (event) => {
+        if (onClick && (event.key === 'Enter' || event.key === ' ')) {
+            event.preventDefault();
+            onClick(event);
+        }
+    };
+    return (jsx("div", { className: AVATAR_STYLES.root({ hasImage, clickable, size, color, borderColor, backgroundColor }), onClick: onClick, onKeyDown: clickable ? handleKeyDown : undefined, role: clickable ? 'button' : undefined, tabIndex: clickable ? (tabIndex ?? 0) : tabIndex, "aria-label": ariaLabel || label, children: hasImage ? (jsx("img", { src: image, alt: label || ariaLabel || '', className: AVATAR_STYLES.image })) : (jsx(Text, { variant: 'label', fontSize: AVATAR_SIZES[size].fontSize, children: label || '?' })) }));
 };
 Avatar.displayName = 'Avatar';
 
@@ -785,13 +803,21 @@ const BUTTON_STYLES = createStyles((theme) => {
  * - `contained`: Solid background button (default)
  * - `outlined`: Border only button
  * - `text`: Text only button without background
- */
-const Button = ({ label, startIcon, endIcon, variant = 'contained', active = false, onClick, disabled, type = 'button', textColor: customTextColor, backgroundColor, hoverBackgroundColor, activeBackgroundColor, size = 'medium', ariaLabel, ariaLabelledBy, ariaDescribedBy, role, tabIndex, }) => {
+ * - `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
+ */
+const Button = ({ label, startIcon, endIcon, variant = 'contained', active = false, onClick, disabled, type = 'button', textColor: customTextColor, backgroundColor, hoverBackgroundColor, activeBackgroundColor, size = 'medium', ariaLabel, ariaLabelledBy, ariaDescribedBy, role, tabIndex, ariaPressed, ariaBusy, ariaExpanded, ariaHasPopup, ariaControls, }) => {
     const theme = useTheme();
     const variantStyles = getButtonVariantStyles(theme);
     const sizeStyles = getButtonSizeStyles();
     const textColor = disabled ? 'disabledText' : (customTextColor ?? variantStyles[variant].textColor);
-    return (jsxs("button", { onClick: onClick, disabled: disabled, type: type, className: BUTTON_STYLES.root({ variant, active, textColor: customTextColor, backgroundColor, hoverBackgroundColor, activeBackgroundColor, size }), "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, role: role, tabIndex: tabIndex, children: [startIcon && (jsx(Icon, { color: textColor, children: startIcon })), jsx(Text, { variant: 'label', color: textColor, fontSize: sizeStyles[size].fontSize, children: label }), endIcon && (jsx(Icon, { color: textColor, children: endIcon }))] }));
+    return (jsxs("button", { onClick: onClick, disabled: disabled, type: type, className: BUTTON_STYLES.root({ variant, active, textColor: customTextColor, backgroundColor, hoverBackgroundColor, activeBackgroundColor, size }), "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, "aria-pressed": ariaPressed, "aria-busy": ariaBusy, "aria-expanded": ariaExpanded, "aria-haspopup": ariaHasPopup, "aria-controls": ariaControls, role: role, tabIndex: tabIndex, children: [startIcon && (jsx(Icon, { color: textColor, children: startIcon })), jsx(Text, { variant: 'label', color: textColor, fontSize: sizeStyles[size].fontSize, children: label }), endIcon && (jsx(Icon, { color: textColor, children: endIcon }))] }));
 };
 Button.displayName = 'Button';
 
@@ -859,12 +885,25 @@ const ICON_BUTTON_STYLES = createStyles((theme) => {
     };
 });
 
-const IconButton = ({ icon, variant = 'contained', active = false, type = 'button', onClick, disabled, textColor: customTextColor, backgroundColor, hoverBackgroundColor, activeBackgroundColor, size = 'medium', ariaLabel, ariaLabelledBy, ariaDescribedBy, role, tabIndex, }) => {
+/**
+ * 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} />
+ * ```
+ */
+const IconButton = ({ icon, variant = 'contained', active = false, type = 'button', onClick, disabled, textColor: customTextColor, backgroundColor, hoverBackgroundColor, activeBackgroundColor, size = 'medium', ariaLabel, ariaLabelledBy, ariaDescribedBy, role, tabIndex, ariaPressed, ariaBusy, ariaExpanded, ariaHasPopup, ariaControls, }) => {
     const theme = useTheme();
     const variantStyles = getButtonVariantStyles(theme);
     const textColor = disabled ? 'disabledText' : (customTextColor ?? variantStyles[variant].textColor);
     const iconSize = getIconButtonSizeStyles()[size].iconSize;
-    return (jsx("button", { onClick: onClick, disabled: disabled, type: type, className: ICON_BUTTON_STYLES.root({ variant, active, size, textColor: customTextColor, backgroundColor, hoverBackgroundColor, activeBackgroundColor }), "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, role: role, tabIndex: tabIndex, children: jsx(Icon, { color: textColor, size: iconSize, children: icon }) }));
+    return (jsx("button", { onClick: onClick, disabled: disabled, type: type, className: ICON_BUTTON_STYLES.root({ variant, active, size, textColor: customTextColor, backgroundColor, hoverBackgroundColor, activeBackgroundColor }), "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, "aria-pressed": ariaPressed, "aria-busy": ariaBusy, "aria-expanded": ariaExpanded, "aria-haspopup": ariaHasPopup, "aria-controls": ariaControls, role: role, tabIndex: tabIndex, children: jsx(Icon, { color: textColor, size: iconSize, children: icon }) }));
 };
 IconButton.displayName = 'IconButton';
 
@@ -1215,15 +1254,38 @@ const UploadIcon = () => (jsxs("svg", { xmlns: 'http://www.w3.org/2000/svg', wid
 
 /**
  * Input component
+ *
+ * A text input field with optional label, icons, and error state.
+ *
+ * **Accessibility:**
+ * - `aria-label` defaults to the `label` prop for screen readers
+ * - When `error` is provided, `aria-invalid="true"` and `aria-errormessage`
+ *   are automatically set to link the input to its error message
+ * - `mandatory` adds `aria-required="true"` to the input element
+ *
+ * @example
+ * ```tsx
+ * <Input
+ *   value={email}
+ *   onChange={setEmail}
+ *   label="Email address"
+ *   mandatory
+ *   error={emailError}
+ *   type="email"
+ * />
+ * ```
  */
-const Input = forwardRef(({ value, onChange, onFocus, onBlur, onClick, label, mandatory = false, placeholder, disabled = false, type = 'text', ariaLabel, startIcon, endIcon, width, }, ref) => {
+const Input = forwardRef(({ value, onChange, onFocus, onBlur, onClick, label, mandatory = false, placeholder, disabled = false, type = 'text', ariaLabel, startIcon, endIcon, width, error, id, }, ref) => {
+    const generatedId = useId();
+    const inputId = id ?? generatedId;
+    const errorId = error ? `${inputId}-error` : undefined;
     const [showPassword, setShowPassword] = useState(false);
     const handleChange = (event) => {
         onChange(event.target.value);
     };
     const inputType = type === 'password' ? (showPassword ? 'text' : 'password') : type;
     const hasPasswordToggle = type === 'password';
-    return (jsxs(Stack, { direction: 'column', gap: 'xs', align: 'stretch', width: width ?? '100%', children: [label && (jsxs(Stack, { direction: 'row', gap: 'xs', align: 'center', children: [jsx(Text, { variant: 'label', fontSize: 'sm', children: label }), mandatory && (jsx(Text, { variant: 'label', fontSize: 'sm', color: 'error', children: "*" }))] })), jsxs("div", { className: `${INPUT_STYLES.container({ width })} ${disabled ? 'disabled' : ''}`, children: [jsx("input", { ref: ref, type: inputType, value: value, onChange: handleChange, onFocus: onFocus, onBlur: onBlur, onClick: onClick, placeholder: placeholder, disabled: disabled, className: INPUT_STYLES.root({ disabled, hasStartIcon: !!startIcon, hasEndIcon: !!endIcon, hasPasswordToggle }), "aria-label": ariaLabel || label }), startIcon && (jsx("div", { className: INPUT_STYLES.startIcon, children: jsx(Icon, { color: 'textTertiary', children: startIcon }) })), endIcon && (jsx("div", { className: hasPasswordToggle ? INPUT_STYLES.endIconShifted : INPUT_STYLES.endIcon, children: jsx(Icon, { color: 'textTertiary', children: endIcon }) })), hasPasswordToggle && (jsx("div", { className: INPUT_STYLES.passwordToggle, children: jsx(IconButton, { icon: showPassword ? jsx(EyeOffIcon, {}) : jsx(EyeIcon, {}), onClick: () => setShowPassword(!showPassword), disabled: disabled, ariaLabel: ariaLabel || label, variant: 'text', size: 'small', textColor: 'textSecondary' }) }))] })] }));
+    return (jsxs(Stack, { direction: 'column', gap: 'xs', align: 'stretch', width: width ?? '100%', children: [label && (jsxs(Stack, { direction: 'row', gap: 'xs', align: 'center', children: [jsx(Text, { variant: 'label', fontSize: 'sm', id: `${inputId}-label`, children: label }), mandatory && (jsx(Text, { variant: 'label', fontSize: 'sm', color: 'error', ariaLabel: 'required', children: "*" }))] })), jsxs("div", { className: `${INPUT_STYLES.container({ width })} ${disabled ? 'disabled' : ''}`, children: [jsx("input", { id: inputId, ref: ref, type: inputType, value: value, onChange: handleChange, onFocus: onFocus, onBlur: onBlur, onClick: onClick, placeholder: placeholder, disabled: disabled, className: INPUT_STYLES.root({ disabled, hasStartIcon: !!startIcon, hasEndIcon: !!endIcon, hasPasswordToggle, hasError: !!error }), "aria-label": ariaLabel || label, "aria-required": mandatory || undefined, "aria-invalid": error ? true : undefined, "aria-errormessage": errorId }), startIcon && (jsx("div", { className: INPUT_STYLES.startIcon, children: jsx(Icon, { color: 'textTertiary', children: startIcon }) })), endIcon && (jsx("div", { className: hasPasswordToggle ? INPUT_STYLES.endIconShifted : INPUT_STYLES.endIcon, children: jsx(Icon, { color: 'textTertiary', children: endIcon }) })), hasPasswordToggle && (jsx("div", { className: INPUT_STYLES.passwordToggle, children: jsx(IconButton, { icon: showPassword ? jsx(EyeOffIcon, {}) : jsx(EyeIcon, {}), onClick: () => setShowPassword(!showPassword), disabled: disabled, ariaLabel: showPassword ? 'Hide password' : 'Show password', variant: 'text', size: 'small', textColor: 'textSecondary' }) }))] }), error && (jsx(Text, { variant: 'span', fontSize: 'sm', color: 'error', id: errorId, role: 'alert', children: error }))] }));
 });
 Input.displayName = 'Input';
 var Input_default = memo(Input);
@@ -1275,23 +1337,40 @@ const TEXTAREA_STYLES = createStyles((theme) => ({
 
 /**
  * TextArea component with auto-expanding height based on content
+ *
+ * **Accessibility:**
+ * - `aria-label` defaults to the `label` prop for screen readers
+ * - When `error` is provided, `aria-invalid="true"` and `aria-errormessage`
+ *   are automatically set to link the textarea to its error message
+ * - `mandatory` adds `aria-required="true"` to the textarea element
+ *
+ * @example
+ * ```tsx
+ * <TextArea
+ *   value={message}
+ *   onChange={setMessage}
+ *   label="Message"
+ *   mandatory
+ *   error={messageError}
+ *   minRows={4}
+ * />
+ * ```
  */
-const TextArea = forwardRef(({ value, onChange, onFocus, onBlur, label, mandatory = false, placeholder, disabled = false, ariaLabel, width, minRows = 3, maxRows, }, ref) => {
+const TextArea = forwardRef(({ value, onChange, onFocus, onBlur, label, mandatory = false, placeholder, disabled = false, ariaLabel, width, minRows = 3, maxRows, error, id, }, ref) => {
+    const generatedId = useId();
+    const textareaId = id ?? generatedId;
+    const errorId = error ? `${textareaId}-error` : undefined;
     const internalRef = useRef(null);
     const textareaRef = ref || internalRef;
     const adjustHeight = useCallback(() => {
         const textarea = textareaRef.current;
         if (textarea) {
-            // Reset height to calculate the correct scrollHeight
             textarea.style.height = 'auto';
-            // Set minHeight based on minRows
             const lineHeight = parseInt(getComputedStyle(textarea).lineHeight) || 20;
             const minHeight = lineHeight * minRows;
             const maxHeight = maxRows ? lineHeight * maxRows : Infinity;
-            // Set the height to the greater of minHeight or scrollHeight, but capped at maxHeight
             const newHeight = Math.min(Math.max(minHeight, textarea.scrollHeight), maxHeight);
             textarea.style.height = `${newHeight}px`;
-            // Enable scrolling if content exceeds maxHeight
             textarea.style.overflowY = textarea.scrollHeight > maxHeight ? 'auto' : 'hidden';
         }
     }, [minRows, maxRows, textareaRef]);
@@ -1301,7 +1380,7 @@ const TextArea = forwardRef(({ value, onChange, onFocus, onBlur, label, mandator
     const handleChange = (event) => {
         onChange(event.target.value);
     };
-    return (jsxs(Stack, { direction: 'column', gap: 'xs', align: 'stretch', width: width ?? '100%', children: [label && (jsxs(Stack, { direction: 'row', gap: 'xs', align: 'center', children: [jsx(Text, { variant: 'label', fontSize: 'sm', children: label }), mandatory && (jsx(Text, { variant: 'label', fontSize: 'sm', color: 'error', children: "*" }))] })), jsx("div", { className: `${TEXTAREA_STYLES.container({ width })} ${disabled ? 'disabled' : ''}`, children: jsx("textarea", { ref: textareaRef, value: value, onChange: handleChange, onFocus: onFocus, onBlur: onBlur, placeholder: placeholder, disabled: disabled, className: TEXTAREA_STYLES.root({ disabled }), "aria-label": ariaLabel || label, rows: minRows }) })] }));
+    return (jsxs(Stack, { direction: 'column', gap: 'xs', align: 'stretch', width: width ?? '100%', children: [label && (jsxs(Stack, { direction: 'row', gap: 'xs', align: 'center', children: [jsx(Text, { variant: 'label', fontSize: 'sm', id: `${textareaId}-label`, children: label }), mandatory && (jsx(Text, { variant: 'label', fontSize: 'sm', color: 'error', ariaLabel: 'required', children: "*" }))] })), jsx("div", { className: `${TEXTAREA_STYLES.container({ width })} ${disabled ? 'disabled' : ''}`, children: jsx("textarea", { id: textareaId, ref: textareaRef, value: value, onChange: handleChange, onFocus: onFocus, onBlur: onBlur, placeholder: placeholder, disabled: disabled, className: TEXTAREA_STYLES.root({ disabled, hasError: !!error }), "aria-label": ariaLabel || label, "aria-required": mandatory || undefined, "aria-invalid": error ? true : undefined, "aria-errormessage": errorId, rows: minRows }) }), error && (jsx(Text, { variant: 'span', fontSize: 'sm', color: 'error', id: errorId, role: 'alert', children: error }))] }));
 });
 TextArea.displayName = 'TextArea';
 var TextArea_default = memo(TextArea);
@@ -1624,10 +1703,31 @@ MenuItem.displayName = 'MenuItem';
 
 /**
  * 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}
+ * />
+ * ```
  */
-const Select = ({ options, value, onChange, label, mandatory = false, placeholder = 'Select an option', disabled = false, width }) => {
+const Select = ({ options, value, onChange, label, mandatory = false, placeholder = 'Select an option', disabled = false, width, error, id, ariaLabel, }) => {
     const [isOpen, setIsOpen] = useState(false);
     const triggerRef = useRef(null);
+    const generatedId = useId();
+    const selectId = id ?? generatedId;
+    const errorId = error ? `${selectId}-error` : undefined;
     const selectedOption = options.find(option => option.value === value);
     const menuWidth = triggerRef.current?.offsetWidth ?? width;
     const handleTriggerClick = () => {
@@ -1635,6 +1735,18 @@ const Select = ({ options, value, onChange, label, mandatory = false, placeholde
             setIsOpen(!isOpen);
         }
     };
+    const handleTriggerKeyDown = (event) => {
+        if (disabled) {
+            return;
+        }
+        if (event.key === 'Enter' || event.key === ' ') {
+            event.preventDefault();
+            setIsOpen(prev => !prev);
+        }
+        if (event.key === 'Escape' && isOpen) {
+            setIsOpen(false);
+        }
+    };
     const handleClose = () => {
         setIsOpen(false);
     };
@@ -1642,7 +1754,7 @@ const Select = ({ options, value, onChange, label, mandatory = false, placeholde
         onChange(selectedValue);
         setIsOpen(false);
     };
-    return (jsxs(Stack, { direction: 'column', gap: 'xs', align: 'stretch', width: width ?? '100%', children: [label && (jsxs(Stack, { direction: 'row', gap: 'xs', align: 'center', children: [jsx(Text, { variant: 'label', fontSize: 'sm', children: label }), mandatory && (jsx(Text, { variant: 'label', fontSize: 'sm', color: 'error', children: "*" }))] })), jsxs("div", { ref: triggerRef, className: SELECT_STYLES.root({ disabled, width, isOpen }), onClick: handleTriggerClick, role: 'button', tabIndex: disabled ? -1 : 0, "aria-expanded": isOpen, "aria-haspopup": 'listbox', children: [jsx("div", { className: SELECT_STYLES.trigger, children: jsx(Text, { variant: 'p', maxLines: 1, color: selectedOption ? 'text' : 'textSecondary', children: selectedOption ? selectedOption.label : placeholder }) }), jsx(Icon, { children: jsx(ChevronDownIcon, {}) })] }), jsx(Menu, { anchor: isOpen ? triggerRef.current : null, onClose: handleClose, width: menuWidth, children: jsx(MenuGroup, { children: options.map(option => (jsx(SelectItem, { option: option, isSelected: option.value === value, onSelect: handleSelect }, option.value))) }) })] }));
+    return (jsxs(Stack, { direction: 'column', gap: 'xs', align: 'stretch', width: width ?? '100%', children: [label && (jsxs(Stack, { direction: 'row', gap: 'xs', align: 'center', children: [jsx(Text, { variant: 'label', fontSize: 'sm', id: `${selectId}-label`, children: label }), mandatory && (jsx(Text, { variant: 'label', fontSize: 'sm', color: 'error', ariaLabel: 'required', children: "*" }))] })), jsxs("div", { ref: triggerRef, className: SELECT_STYLES.root({ disabled, width, isOpen, hasError: !!error }), onClick: handleTriggerClick, onKeyDown: handleTriggerKeyDown, role: 'combobox', tabIndex: disabled ? -1 : 0, "aria-expanded": isOpen, "aria-haspopup": 'listbox', "aria-label": ariaLabel || label, "aria-required": mandatory || undefined, "aria-invalid": error ? true : undefined, "aria-errormessage": errorId, children: [jsx("div", { className: SELECT_STYLES.trigger, children: jsx(Text, { variant: 'p', maxLines: 1, color: selectedOption ? 'text' : 'textSecondary', children: selectedOption ? selectedOption.label : placeholder }) }), jsx(Icon, { children: jsx(ChevronDownIcon, {}) })] }), error && (jsx(Text, { variant: 'span', fontSize: 'sm', color: 'error', id: errorId, role: 'alert', children: error })), jsx(Menu, { anchor: isOpen ? triggerRef.current : null, onClose: handleClose, width: menuWidth, children: jsx(MenuGroup, { children: options.map(option => (jsx(SelectItem, { option: option, isSelected: option.value === value, onSelect: handleSelect }, option.value))) }) })] }));
 };
 Select.displayName = 'Select';
 
@@ -2808,6 +2920,11 @@ const getAlertIcon = (variant) => {
  * - 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
@@ -2824,6 +2941,8 @@ const Alert = memo(({ text, variant = 'default', position = 'top-right', isVisib
     const lastHeightRef = useRef(0);
     const icon = useMemo(() => getAlertIcon(variant), [variant]);
     const colors = useMemo(() => getAlertVariantColors(theme, variant), [theme, variant]);
+    // Error alerts are urgent → assertive; others are polite
+    const ariaLive = variant === 'error' ? 'assertive' : 'polite';
     // Report height changes to parent (only when height actually changes)
     useEffect(() => {
         if (alertRef.current && onHeightChange && isVisible && alertId) {
@@ -2835,7 +2954,7 @@ const Alert = memo(({ text, variant = 'default', position = 'top-right', isVisib
             }
         }
     }, [isVisible, text, maxWidth, alertId, onHeightChange]);
-    return (jsxs("div", { ref: alertRef, className: ALERT_STYLES.root({ variant, position, isVisible, offsetY, maxWidth }), role: 'alert', "aria-live": 'polite', children: [jsx(Icon, { size: 'sm', color: colors.iconColor, children: icon }), jsx(Text, { variant: 'span', fontSize: 'sm', color: colors.iconColor, maxLines: 4, children: text })] }));
+    return (jsxs("div", { ref: alertRef, className: ALERT_STYLES.root({ variant, position, isVisible, offsetY, maxWidth }), role: 'alert', "aria-live": ariaLive, "aria-atomic": 'true', children: [jsx(Icon, { size: 'sm', color: colors.iconColor, children: icon }), jsx(Text, { variant: 'span', fontSize: 'sm', color: colors.iconColor, maxLines: 4, children: text })] }));
 });
 Alert.displayName = 'Alert';
 
@@ -2875,15 +2994,98 @@ const MODAL_STYLES = createStyles((theme) => ({
     }),
 }));
 
+const FOCUSABLE_SELECTORS = [
+    'a[href]',
+    'button:not([disabled])',
+    'input:not([disabled])',
+    'select:not([disabled])',
+    'textarea:not([disabled])',
+    '[tabindex]:not([tabindex="-1"])',
+].join(', ');
+/**
+ * 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>
+ * ```
+ */
 const Modal = ({ isOpen, onClose, label, children, isForm, action }) => {
     // refs
     const modalRef = useRef(null);
+    const contentRef = useRef(null);
+    const previousFocusRef = useRef(null);
+    // unique id for aria-labelledby
+    const titleId = useId();
     // hooks
     const { isVisible, isFadingIn } = useTransitionRender(isOpen);
+    // Save focus and trap it inside modal
+    useEffect(() => {
+        if (isOpen) {
+            previousFocusRef.current = document.activeElement;
+            // Move focus to first focusable element in modal
+            setTimeout(() => {
+                const content = contentRef.current;
+                if (content) {
+                    const focusable = content.querySelectorAll(FOCUSABLE_SELECTORS);
+                    focusable[0]?.focus();
+                }
+            }, 50);
+        }
+        else {
+            // Restore focus to the element that triggered the modal
+            previousFocusRef.current?.focus();
+        }
+    }, [isOpen]);
+    // Keyboard: Escape to close + focus trap (Tab/Shift+Tab)
     useEffect(() => {
         const handleKeyDown = (event) => {
-            if (event.key === 'Escape' && isOpen) {
+            if (!isOpen) {
+                return;
+            }
+            if (event.key === 'Escape') {
                 onClose();
+                return;
+            }
+            if (event.key === 'Tab') {
+                const content = contentRef.current;
+                if (!content) {
+                    return;
+                }
+                const focusable = Array.from(content.querySelectorAll(FOCUSABLE_SELECTORS));
+                if (focusable.length === 0) {
+                    return;
+                }
+                const first = focusable[0];
+                const last = focusable[focusable.length - 1];
+                if (event.shiftKey) {
+                    if (document.activeElement === first) {
+                        event.preventDefault();
+                        last.focus();
+                    }
+                }
+                else {
+                    if (document.activeElement === last) {
+                        event.preventDefault();
+                        first.focus();
+                    }
+                }
             }
         };
         document.addEventListener('keydown', handleKeyDown);
@@ -2892,13 +3094,17 @@ const Modal = ({ isOpen, onClose, label, children, isForm, action }) => {
     // actions
     const safeInvokeAction = (e) => {
         if (action && typeof action.onClick === 'function') {
-            // Cast e to required MouseEvent type (or undefined) and call
             action.onClick(e);
         }
     };
     // body of the modal
-    const body = (jsxs(Fragment$1, { children: [jsxs(Stack, { justify: 'space-between', height: BUTTON_SIZE, width: '100%', children: [jsx(Text, { variant: 'h3', children: label }), !action && (jsx(IconButton, { icon: jsx(CloseIcon, {}), onClick: onClose, size: 'small', variant: 'text', textColor: 'text' }))] }), children, action && (jsxs(Stack, { justify: 'flex-end', width: '100%', children: [jsx(Button, { label: 'Cancel', onClick: onClose, variant: 'outlined' }), jsx(Button, { ...action, type: isForm ? 'submit' : 'button', onClick: isForm ? undefined : action.onClick })] }))] }));
-    return createPortal(jsx(Fragment, { children: isVisible ? (jsx("div", { className: MODAL_STYLES.background(isFadingIn), ref: modalRef, children: jsx("div", { className: MODAL_STYLES.content(isFadingIn), children: isForm ? (jsx(Form, { onSubmit: (e) => { e.preventDefault(); safeInvokeAction(); }, children: body })) : (jsx(Fragment, { children: body })) }) })) : null }), document.body);
+    const body = (jsxs(Fragment$1, { children: [jsxs(Stack, { justify: 'space-between', height: BUTTON_SIZE, width: '100%', children: [jsx(Text, { variant: 'h3', id: titleId, children: label }), !action && (jsx(IconButton, { icon: jsx(CloseIcon, {}), onClick: onClose, size: 'small', variant: 'text', textColor: 'text', ariaLabel: 'Close dialog' }))] }), children, action && (jsxs(Stack, { justify: 'flex-end', width: '100%', children: [jsx(Button, { label: 'Cancel', onClick: onClose, variant: 'outlined' }), jsx(Button, { ...action, type: isForm ? 'submit' : 'button', onClick: isForm ? undefined : action.onClick })] }))] }));
+    return createPortal(jsx(Fragment, { children: isVisible ? (jsx("div", { className: MODAL_STYLES.background(isFadingIn), ref: modalRef, onClick: (e) => {
+                // Close when clicking the backdrop
+                if (e.target === e.currentTarget) {
+                    onClose();
+                }
+            }, children: jsx("div", { ref: contentRef, className: MODAL_STYLES.content(isFadingIn), role: 'dialog', "aria-modal": 'true', "aria-labelledby": titleId, children: isForm ? (jsx(Form, { onSubmit: (e) => { e.preventDefault(); safeInvokeAction(); }, children: body })) : (jsx(Fragment, { children: body })) }) })) : null }), document.body);
 };
 Modal.displayName = 'Modal';