Add comprehensive ARIA attributes for accessibility

Author: kotAPI

src/core/utils/RovingFocusGroup/fragments/RovingFocusGroup.tsx

@@ -6,9 +6,13 @@ import { RovingFocusGroupContext } from '../context/RovingFocusGroupContext';
 /**
  * Props for the RovingFocusGroup component
  * @property {React.ReactNode} children - Child components (should include RovingFocusItem components)
+ * @property {string} [aria-label] - Accessible label for this specific group
+ * @property {string} [aria-labelledby] - ID of an element that labels this specific group
  */
 type RovingFocusGroupProps = {
     children: React.ReactNode;
+    'aria-label'?: string;
+    'aria-labelledby'?: string;
 } & React.HTMLAttributes<HTMLDivElement>;
 
 /**
@@ -19,12 +23,17 @@ type RovingFocusGroupProps = {
  * Each group maintains its own list of focusable items and tracks which item has focus.
  *
  * @example
- * <RovingFocusGroup className="flex gap-2">
+ * <RovingFocusGroup className="flex gap-2" aria-label="Navigation section">
  *   <RovingFocusItem><Button>Item 1</Button></RovingFocusItem>
  *   <RovingFocusItem><Button>Item 2</Button></RovingFocusItem>
  * </RovingFocusGroup>
  */
-const RovingFocusGroup = ({ children, ...props }: RovingFocusGroupProps) => {
+const RovingFocusGroup = ({
+    children,
+    'aria-label': ariaLabel,
+    'aria-labelledby': ariaLabelledBy,
+    ...props
+}: RovingFocusGroupProps) => {
     const groupRef = useRef<HTMLDivElement>(null);
     const [focusItems, setFocusItems] = useState<string[]>([]);
     const [focusedItemId, setFocusedItemId] = useState<string | null>(null);
@@ -55,7 +64,14 @@ const RovingFocusGroup = ({ children, ...props }: RovingFocusGroupProps) => {
     };
 
     return <RovingFocusGroupContext.Provider value={sendValues}>
-        <Primitive.div id={groupId} ref={groupRef} {...props}>
+        <Primitive.div
+            id={groupId}
+            ref={groupRef}
+            role="group"
+            aria-label={ariaLabel}
+            aria-labelledby={ariaLabelledBy}
+            {...props}
+        >
             {children}
         </Primitive.div>
     </RovingFocusGroupContext.Provider>;

src/core/utils/RovingFocusGroup/fragments/RovingFocusItem.tsx

@@ -8,9 +8,13 @@ import { RovingFocusRootContext } from '../context/RovingFocusRootContext';
 /**
  * Props for the RovingFocusItem component
  * @property {React.ReactNode} children - Child component that will receive focus (usually a button or other interactive element)
+ * @property {string} [aria-label] - Accessible label for this item
+ * @property {string} [aria-labelledby] - ID of an element that labels this item
  */
 type RovingFocusItemProps = {
     children: React.ReactNode;
+    'aria-label'?: string;
+    'aria-labelledby'?: string;
 } & React.ButtonHTMLAttributes<HTMLButtonElement>;
 
 /**
@@ -22,15 +26,20 @@ type RovingFocusItemProps = {
  * Automatically respects the disabled state of child elements.
  *
  * @example
- * <RovingFocusItem>
+ * <RovingFocusItem aria-label="Navigation option">
  *   <Button>Focusable Item</Button>
  * </RovingFocusItem>
  *
  * <RovingFocusItem>
  *   <Button disabled>Disabled Item (skipped during navigation)</Button>
  * </RovingFocusItem>
  */
-const RovingFocusItem = forwardRef<HTMLButtonElement, RovingFocusItemProps>(({ children, ...props }, ref) => {
+const RovingFocusItem = forwardRef<HTMLButtonElement, RovingFocusItemProps>(({
+    children,
+    'aria-label': ariaLabel,
+    'aria-labelledby': ariaLabelledBy,
+    ...props
+}, ref) => {
     const id = useId();
     const { focusedItemId, setFocusedItemId, addFocusItem, focusItems, groupRef } = useContext(RovingFocusGroupContext);
     const { direction, loop } = useContext(RovingFocusRootContext);
@@ -40,6 +49,9 @@ const RovingFocusItem = forwardRef<HTMLButtonElement, RovingFocusItemProps>(({ c
     const child = childrenArray[0] as React.ReactElement;
     const isDisabled = child?.props?.disabled === true;
 
+    // Is this item currently selected
+    const isSelected = focusedItemId === id;
+
     // Register this item with the parent group
     useEffect(() => {
         // we check if the item is in the focusItems array, if not we add it
@@ -226,11 +238,16 @@ const RovingFocusItem = forwardRef<HTMLButtonElement, RovingFocusItemProps>(({ c
     return <Primitive.button
         asChild
         onFocus={handleFocus}
-        tabIndex={!isDisabled && focusedItemId === id ? 0 : -1}
+        tabIndex={!isDisabled && isSelected ? 0 : -1}
         ref={ref}
         id={id}
         onKeyDown={handleKeyDown}
         data-child-disabled={isDisabled}
+        role="option"
+        aria-selected={isSelected}
+        aria-disabled={isDisabled}
+        aria-label={ariaLabel}
+        aria-labelledby={ariaLabelledBy}
         {...props}
     >
         {children}

src/core/utils/RovingFocusGroup/fragments/RovingFocusRoot.tsx

@@ -9,11 +9,15 @@ import { RovingFocusRootContext } from '../context/RovingFocusRootContext';
  * @property {React.ReactNode} children - Child components (should include RovingFocusGroup)
  * @property {'horizontal'|'vertical'} [direction='horizontal'] - Direction of keyboard navigation
  * @property {boolean} [loop=true] - Whether focus should loop from last to first item and vice versa
+ * @property {string} [aria-label] - Accessible label for the roving focus group
+ * @property {string} [aria-labelledby] - ID of an element that labels the roving focus group
  */
 type RovingFocusRootProps = {
     children: React.ReactNode;
     direction?: 'horizontal' | 'vertical';
     loop?: boolean;
+    'aria-label'?: string;
+    'aria-labelledby'?: string;
 } & React.HTMLAttributes<HTMLDivElement>;
 
 /**
@@ -23,21 +27,34 @@ type RovingFocusRootProps = {
  * Manages overall direction (horizontal/vertical) and loop behavior.
  *
  * @example
- * <RovingFocusRoot direction="horizontal" loop={true}>
+ * <RovingFocusRoot direction="horizontal" loop={true} aria-label="Main navigation">
  *   <RovingFocusGroup>
  *     <RovingFocusItem><Button>Item 1</Button></RovingFocusItem>
  *     <RovingFocusItem><Button>Item 2</Button></RovingFocusItem>
  *   </RovingFocusGroup>
  * </RovingFocusRoot>
  */
-const RovingFocusRoot = ({ children, direction = 'horizontal', loop = true, ...props }: RovingFocusRootProps) => {
+const RovingFocusRoot = ({
+    children,
+    direction = 'horizontal',
+    loop = true,
+    'aria-label': ariaLabel,
+    'aria-labelledby': ariaLabelledBy,
+    ...props
+}: RovingFocusRootProps) => {
     const sendValues = {
         direction,
         loop
     };
 
     return <RovingFocusRootContext.Provider value={sendValues}>
-        <Primitive.div {...props}>
+        <Primitive.div
+            role="listbox"
+            aria-orientation={direction}
+            aria-label={ariaLabel}
+            aria-labelledby={ariaLabelledBy}
+            {...props}
+        >
             {children}
         </Primitive.div>
     </RovingFocusRootContext.Provider>;

src/core/utils/RovingFocusGroup/index.tsx

@@ -16,17 +16,21 @@ import RovingFocusItem from './fragments/RovingFocusItem';
  * - Optional looping when reaching the end of a group
  * - Prevents default scrolling behavior when using arrow keys
  * - Automatically respects disabled state of child elements
+ * - Comprehensive ARIA roles and attributes for screen readers
  *
  * Accessibility benefits:
  * - Follows WAI-ARIA best practices for keyboard navigation
  * - Improves navigation for keyboard and screen reader users
  * - Maintains a single tab stop within a group of related elements
  * - Properly identifies and skips disabled elements during navigation
+ * - Uses appropriate ARIA roles (listbox/option pattern)
+ * - Provides aria-selected state for the currently focused item
+ * - Supports proper labeling with aria-label and aria-labelledby
  *
  * @example
- * <RovingFocusGroup.Root direction="horizontal" loop={true}>
- *   <RovingFocusGroup.Group className="flex gap-2">
- *     <RovingFocusGroup.Item>
+ * <RovingFocusGroup.Root direction="horizontal" loop={true} aria-label="Main Menu">
+ *   <RovingFocusGroup.Group className="flex gap-2" aria-label="Navigation Section">
+ *     <RovingFocusGroup.Item aria-label="First option">
  *       <Button>Option 1</Button>
  *     </RovingFocusGroup.Item>
  *     <RovingFocusGroup.Item>

src/core/utils/RovingFocusGroup/stories/RovingFocusGroup.stories.tsx

@@ -254,3 +254,77 @@ export const DisabledItems = {
         </SandboxEditor>
     )
 };
+
+// Story demonstrating the ARIA roles and attributes for screen reader accessibility
+export const AccessibilityDemo = {
+    render: () => (
+        <SandboxEditor className="space-y-8 bg-gray-50">
+            <div className="p-4 bg-gray-50 rounded-md border border-gray-300">
+                <h2 className="text-lg font-semibold mb-2">Screen Reader Accessibility</h2>
+                <p className="mb-1">This example demonstrates ARIA roles and attributes for screen reader accessibility.</p>
+                <p className="mb-1"><strong>Features:</strong> Proper ARIA roles, labels, and states for screen readers.</p>
+                <p className="text-sm text-gray-600">The component uses listbox/option pattern with aria-selected state.</p>
+            </div>
+
+            <div className="space-y-6">
+                <div>
+                    <h3 className="text-md font-medium mb-2">ARIA Labeled Navigation Example</h3>
+                    <RovingFocusGroup.Root
+                        direction="horizontal"
+                        loop={true}
+                        aria-label="Main navigation menu"
+                        className="rounded-md border border-blue-500 p-4"
+                    >
+                        <RovingFocusGroup.Group
+                            className="flex gap-3"
+                            aria-label="Primary actions"
+                        >
+                            <RovingFocusGroup.Item aria-label="Dashboard view">
+                                <Button>Dashboard</Button>
+                            </RovingFocusGroup.Item>
+                            <RovingFocusGroup.Item aria-label="User profile settings">
+                                <Button>Profile</Button>
+                            </RovingFocusGroup.Item>
+                            <RovingFocusGroup.Item aria-label="System settings">
+                                <Button>Settings</Button>
+                            </RovingFocusGroup.Item>
+                            <RovingFocusGroup.Item>
+                                <Button disabled className="opacity-50">Admin (Disabled)</Button>
+                            </RovingFocusGroup.Item>
+                        </RovingFocusGroup.Group>
+                    </RovingFocusGroup.Root>
+                </div>
+
+                <div>
+                    <h3 className="text-md font-medium mb-2">ARIA Attributes Explained</h3>
+                    <div className="grid grid-cols-2 gap-4 text-sm border border-gray-200 p-4 rounded-md">
+                        <div className="font-semibold">Root Component</div>
+                        <div>role="listbox", aria-orientation, aria-label</div>
+
+                        <div className="font-semibold">Group Component</div>
+                        <div>role="group", aria-label</div>
+
+                        <div className="font-semibold">Item Component</div>
+                        <div>role="option", aria-selected, aria-disabled</div>
+
+                        <div className="font-semibold">Navigation</div>
+                        <div>Arrow keys, Home/End, with proper ARIA states</div>
+                    </div>
+                </div>
+            </div>
+
+            <div className="p-4 bg-gray-50 rounded-md border border-gray-300">
+                <h3 className="text-md font-medium mb-2">Screen Reader Testing Instructions</h3>
+                <p className="text-sm text-gray-600">Use VoiceOver (Mac) or NVDA/JAWS (Windows) to test the component.</p>
+                <p className="text-sm text-gray-600 mt-1">Tab to the group, then use arrow keys to navigate between options.</p>
+                <p className="text-sm text-gray-600 mt-1">The screen reader should announce:</p>
+                <ul className="list-disc pl-5 text-sm text-gray-600 mt-1">
+                    <li>When you enter the navigation menu</li>
+                    <li>The name of each option as you navigate</li>
+                    <li>The selected state of the focused option</li>
+                    <li>When an option is disabled</li>
+                </ul>
+            </div>
+        </SandboxEditor>
+    )
+};