feat(a11y): add ARIA roles and arrow-key nav to Tabs component

Implements APG Tabs pattern: role=tablist/tab/tabpanel, aria-selected,
aria-controls, aria-labelledby, roving tabindex, and arrow/Home/End
keyboard navigation with wrap-around.

Resolves GOO-107.

Co-Authored-By: Paperclip <noreply@paperclip.ing>

apps/web/components/ui/__tests__/tabs.spec.tsx

@@ -3,88 +3,55 @@ import userEvent from '@testing-library/user-event';
 import { describe, expect, it, vi } from 'vitest';
 import { Tabs, TabsList, TabsTrigger, TabsContent } from '../tabs';
 
-describe('Tabs', () => {
+function renderTabs(value = 'tab1', onValueChange = vi.fn()) {
-  it('renders the active tab content', () => {
+  return {
-    render(
+    onValueChange,
-      <Tabs value="tab1" onValueChange={vi.fn()}>
+    ...render(
+      <Tabs value={value} onValueChange={onValueChange}>
         <TabsList>
           <TabsTrigger value="tab1">Tab 1</TabsTrigger>
           <TabsTrigger value="tab2">Tab 2</TabsTrigger>
+          <TabsTrigger value="tab3">Tab 3</TabsTrigger>
         </TabsList>
         <TabsContent value="tab1">Content 1</TabsContent>
         <TabsContent value="tab2">Content 2</TabsContent>
+        <TabsContent value="tab3">Content 3</TabsContent>
       </Tabs>,
-    );
+    ),
+  };
+}
 
+describe('Tabs', () => {
+  it('renders the active tab content', () => {
+    renderTabs('tab1');
     expect(screen.getByText('Content 1')).toBeInTheDocument();
     expect(screen.queryByText('Content 2')).not.toBeInTheDocument();
   });
 
   it('hides inactive tab content', () => {
-    render(
+    renderTabs('tab2');
-      <Tabs value="tab2" onValueChange={vi.fn()}>
-        <TabsList>
-          <TabsTrigger value="tab1">Tab 1</TabsTrigger>
-          <TabsTrigger value="tab2">Tab 2</TabsTrigger>
-        </TabsList>
-        <TabsContent value="tab1">Content 1</TabsContent>
-        <TabsContent value="tab2">Content 2</TabsContent>
-      </Tabs>,
-    );
-
     expect(screen.queryByText('Content 1')).not.toBeInTheDocument();
     expect(screen.getByText('Content 2')).toBeInTheDocument();
   });
 
   it('calls onValueChange when a trigger is clicked', async () => {
     const onValueChange = vi.fn();
-    render(
+    renderTabs('tab1', onValueChange);
-      <Tabs value="tab1" onValueChange={onValueChange}>
-        <TabsList>
-          <TabsTrigger value="tab1">Tab 1</TabsTrigger>
-          <TabsTrigger value="tab2">Tab 2</TabsTrigger>
-        </TabsList>
-        <TabsContent value="tab1">Content 1</TabsContent>
-        <TabsContent value="tab2">Content 2</TabsContent>
-      </Tabs>,
-    );
-
     await userEvent.click(screen.getByText('Tab 2'));
     expect(onValueChange).toHaveBeenCalledWith('tab2');
   });
 
   it('renders all trigger buttons', () => {
-    render(
+    renderTabs();
-      <Tabs value="tab1" onValueChange={vi.fn()}>
+    expect(screen.getByText('Tab 1')).toBeInTheDocument();
-        <TabsList>
+    expect(screen.getByText('Tab 2')).toBeInTheDocument();
-          <TabsTrigger value="tab1">First</TabsTrigger>
+    expect(screen.getByText('Tab 3')).toBeInTheDocument();
-          <TabsTrigger value="tab2">Second</TabsTrigger>
-          <TabsTrigger value="tab3">Third</TabsTrigger>
-        </TabsList>
-        <TabsContent value="tab1">C1</TabsContent>
-        <TabsContent value="tab2">C2</TabsContent>
-        <TabsContent value="tab3">C3</TabsContent>
-      </Tabs>,
-    );
-
-    expect(screen.getByText('First')).toBeInTheDocument();
-    expect(screen.getByText('Second')).toBeInTheDocument();
-    expect(screen.getByText('Third')).toBeInTheDocument();
   });
 
   it('applies active styles to selected trigger', () => {
-    render(
+    renderTabs('tab1');
-      <Tabs value="tab1" onValueChange={vi.fn()}>
+    expect(screen.getByRole('tab', { name: 'Tab 1' })).toHaveClass('bg-background');
-        <TabsList>
+    expect(screen.getByRole('tab', { name: 'Tab 2' })).not.toHaveClass('bg-background');
-          <TabsTrigger value="tab1" data-testid="trigger-1">Tab 1</TabsTrigger>
-          <TabsTrigger value="tab2" data-testid="trigger-2">Tab 2</TabsTrigger>
-        </TabsList>
-        <TabsContent value="tab1">Content</TabsContent>
-      </Tabs>,
-    );
-
-    expect(screen.getByTestId('trigger-1')).toHaveClass('bg-background');
-    expect(screen.getByTestId('trigger-2')).not.toHaveClass('bg-background');
   });
 
   it('applies custom className to TabsList', () => {
@@ -96,7 +63,6 @@ describe('Tabs', () => {
         <TabsContent value="tab1">Content</TabsContent>
       </Tabs>,
     );
-
     expect(screen.getByTestId('list')).toHaveClass('custom-list');
   });
 
@@ -111,7 +77,92 @@ describe('Tabs', () => {
         </TabsContent>
       </Tabs>,
     );
-
     expect(screen.getByTestId('content')).toHaveClass('custom-content');
   });
+
+  describe('ARIA attributes', () => {
+    it('sets role="tablist" on TabsList', () => {
+      renderTabs();
+      expect(screen.getByRole('tablist')).toBeInTheDocument();
+    });
+
+    it('sets role="tab" with aria-selected on triggers', () => {
+      renderTabs('tab1');
+      const tab1 = screen.getByRole('tab', { name: 'Tab 1' });
+      const tab2 = screen.getByRole('tab', { name: 'Tab 2' });
+      expect(tab1).toHaveAttribute('aria-selected', 'true');
+      expect(tab2).toHaveAttribute('aria-selected', 'false');
+    });
+
+    it('sets aria-controls on triggers matching tabpanel ids', () => {
+      renderTabs('tab1');
+      const tab1 = screen.getByRole('tab', { name: 'Tab 1' });
+      const panel = screen.getByRole('tabpanel');
+      expect(tab1).toHaveAttribute('aria-controls', panel.id);
+    });
+
+    it('sets role="tabpanel" with aria-labelledby on content', () => {
+      renderTabs('tab1');
+      const panel = screen.getByRole('tabpanel');
+      const tab1 = screen.getByRole('tab', { name: 'Tab 1' });
+      expect(panel).toHaveAttribute('aria-labelledby', tab1.id);
+    });
+
+    it('sets tabIndex correctly (0 for selected, -1 for others)', () => {
+      renderTabs('tab1');
+      expect(screen.getByRole('tab', { name: 'Tab 1' })).toHaveAttribute('tabindex', '0');
+      expect(screen.getByRole('tab', { name: 'Tab 2' })).toHaveAttribute('tabindex', '-1');
+      expect(screen.getByRole('tab', { name: 'Tab 3' })).toHaveAttribute('tabindex', '-1');
+    });
+  });
+
+  describe('Arrow-key navigation', () => {
+    it('moves to next tab on ArrowRight', async () => {
+      const onValueChange = vi.fn();
+      renderTabs('tab1', onValueChange);
+      screen.getByRole('tab', { name: 'Tab 1' }).focus();
+      await userEvent.keyboard('{ArrowRight}');
+      expect(onValueChange).toHaveBeenCalledWith('tab2');
+    });
+
+    it('moves to previous tab on ArrowLeft', async () => {
+      const onValueChange = vi.fn();
+      renderTabs('tab2', onValueChange);
+      screen.getByRole('tab', { name: 'Tab 2' }).focus();
+      await userEvent.keyboard('{ArrowLeft}');
+      expect(onValueChange).toHaveBeenCalledWith('tab1');
+    });
+
+    it('wraps around from last to first on ArrowRight', async () => {
+      const onValueChange = vi.fn();
+      renderTabs('tab3', onValueChange);
+      screen.getByRole('tab', { name: 'Tab 3' }).focus();
+      await userEvent.keyboard('{ArrowRight}');
+      expect(onValueChange).toHaveBeenCalledWith('tab1');
+    });
+
+    it('wraps around from first to last on ArrowLeft', async () => {
+      const onValueChange = vi.fn();
+      renderTabs('tab1', onValueChange);
+      screen.getByRole('tab', { name: 'Tab 1' }).focus();
+      await userEvent.keyboard('{ArrowLeft}');
+      expect(onValueChange).toHaveBeenCalledWith('tab3');
+    });
+
+    it('moves to first tab on Home', async () => {
+      const onValueChange = vi.fn();
+      renderTabs('tab3', onValueChange);
+      screen.getByRole('tab', { name: 'Tab 3' }).focus();
+      await userEvent.keyboard('{Home}');
+      expect(onValueChange).toHaveBeenCalledWith('tab1');
+    });
+
+    it('moves to last tab on End', async () => {
+      const onValueChange = vi.fn();
+      renderTabs('tab1', onValueChange);
+      screen.getByRole('tab', { name: 'Tab 1' }).focus();
+      await userEvent.keyboard('{End}');
+      expect(onValueChange).toHaveBeenCalledWith('tab3');
+    });
+  });
 });

apps/web/components/ui/tabs.tsx

@@ -6,6 +6,10 @@ import { cn } from '@/lib/utils';
 interface TabsContextValue {
   value: string;
   onValueChange: (value: string) => void;
+  baseId: string;
+  registerTab: (value: string) => void;
+  unregisterTab: (value: string) => void;
+  tabs: string[];
 }
 
 const TabsContext = React.createContext<TabsContextValue | null>(null);
@@ -21,25 +25,71 @@ interface TabsProps extends React.HTMLAttributes<HTMLDivElement> {
   onValueChange: (value: string) => void;
 }
 
+let tabsCounter = 0;
+
 function Tabs({ value, onValueChange, className, ...props }: TabsProps) {
+  const [baseId] = React.useState(() => `tabs-${++tabsCounter}`);
+  const [tabs, setTabs] = React.useState<string[]>([]);
+
+  const registerTab = React.useCallback((tabValue: string) => {
+    setTabs((prev) => (prev.includes(tabValue) ? prev : [...prev, tabValue]));
+  }, []);
+
+  const unregisterTab = React.useCallback((tabValue: string) => {
+    setTabs((prev) => prev.filter((t) => t !== tabValue));
+  }, []);
+
   return (
-    <TabsContext.Provider value={{ value, onValueChange }}>
+    <TabsContext.Provider value={{ value, onValueChange, baseId, registerTab, unregisterTab, tabs }}>
       <div className={cn('w-full', className)} {...props} />
     </TabsContext.Provider>
   );
 }
 
 const TabsList = React.forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>(
-  ({ className, ...props }, ref) => (
+  ({ className, ...props }, ref) => {
-    <div
+    const { tabs, value, onValueChange } = useTabs();
-      ref={ref}
+
-      className={cn(
+    const handleKeyDown = (e: React.KeyboardEvent<HTMLDivElement>) => {
-        'inline-flex h-10 items-center justify-center rounded-md bg-muted p-1 text-muted-foreground',
+      const currentIndex = tabs.indexOf(value);
-        className,
+      if (currentIndex === -1) return;
-      )}
+
-      {...props}
+      let nextIndex: number | null = null;
-    />
+
-  ),
+      switch (e.key) {
+        case 'ArrowRight':
+          nextIndex = (currentIndex + 1) % tabs.length;
+          break;
+        case 'ArrowLeft':
+          nextIndex = (currentIndex - 1 + tabs.length) % tabs.length;
+          break;
+        case 'Home':
+          nextIndex = 0;
+          break;
+        case 'End':
+          nextIndex = tabs.length - 1;
+          break;
+        default:
+          return;
+      }
+
+      e.preventDefault();
+      onValueChange(tabs[nextIndex]);
+    };
+
+    return (
+      <div
+        ref={ref}
+        role="tablist"
+        onKeyDown={handleKeyDown}
+        className={cn(
+          'inline-flex h-10 items-center justify-center rounded-md bg-muted p-1 text-muted-foreground',
+          className,
+        )}
+        {...props}
+      />
+    );
+  },
 );
 TabsList.displayName = 'TabsList';
 
@@ -49,13 +99,37 @@ interface TabsTriggerProps extends React.ButtonHTMLAttributes<HTMLButtonElement>
 
 const TabsTrigger = React.forwardRef<HTMLButtonElement, TabsTriggerProps>(
   ({ className, value, ...props }, ref) => {
-    const { value: selectedValue, onValueChange } = useTabs();
+    const { value: selectedValue, onValueChange, baseId, registerTab, unregisterTab } = useTabs();
+    const isSelected = selectedValue === value;
+    const internalRef = React.useRef<HTMLButtonElement | null>(null);
+
+    React.useEffect(() => {
+      registerTab(value);
+      return () => unregisterTab(value);
+    }, [value, registerTab, unregisterTab]);
+
+    // Focus the newly selected tab
+    React.useEffect(() => {
+      if (isSelected && internalRef.current) {
+        internalRef.current.focus();
+      }
+    }, [isSelected]);
+
     return (
       <button
-        ref={ref}
+        ref={(node) => {
+          internalRef.current = node;
+          if (typeof ref === 'function') ref(node);
+          else if (ref) ref.current = node;
+        }}
+        role="tab"
+        id={`${baseId}-trigger-${value}`}
+        aria-selected={isSelected}
+        aria-controls={`${baseId}-content-${value}`}
+        tabIndex={isSelected ? 0 : -1}
         className={cn(
           'inline-flex items-center justify-center whitespace-nowrap rounded-sm px-3 py-1.5 text-sm font-medium ring-offset-background transition-all focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50',
-          selectedValue === value
+          isSelected
             ? 'bg-background text-foreground shadow-sm'
             : 'hover:bg-background/50',
           className,
@@ -74,11 +148,15 @@ interface TabsContentProps extends React.HTMLAttributes<HTMLDivElement> {
 
 const TabsContent = React.forwardRef<HTMLDivElement, TabsContentProps>(
   ({ className, value, ...props }, ref) => {
-    const { value: selectedValue } = useTabs();
+    const { value: selectedValue, baseId } = useTabs();
     if (selectedValue !== value) return null;
     return (
       <div
         ref={ref}
+        role="tabpanel"
+        id={`${baseId}-content-${value}`}
+        aria-labelledby={`${baseId}-trigger-${value}`}
+        tabIndex={0}
         className={cn('mt-2 ring-offset-background focus-visible:outline-none', className)}
         {...props}
       />