feat(core): ARIA live regions for dynamic state changes (stackwright-qb9)

.changeset/feat-aria-live-regions.md

@@ -0,0 +1,5 @@
+---
+"@stackwright/core": minor
+---
+
+feat(core): add AriaLiveRegion utility and wire aria-live regions into Form, SearchModal, Carousel, ContentItemErrorBoundary (WCAG 4.1.3)

packages/core/src/components/ContentItemErrorBoundary.tsx

@@ -33,6 +33,7 @@ export class ContentItemErrorBoundary extends React.Component<
     if (this.state.hasError) {
       return (
         <div
+          role="alert"
           style={{
             padding: '16px',
             margin: '8px 0',

packages/core/src/components/base/AriaLiveRegion.tsx

@@ -0,0 +1,40 @@
+import React from 'react';
+
+/** Visually-hidden live region that announces dynamic state changes to screen readers. */
+export interface AriaLiveRegionProps {
+  /** The message to announce. Update this string to trigger an announcement. */
+  message: string;
+  /** 'polite' waits for the user to finish; 'assertive' interrupts immediately. Default: 'polite' */
+  politeness?: 'polite' | 'assertive';
+}
+
+/** CSS clip pattern for visually hiding an element while keeping it in the a11y tree. */
+const VISUALLY_HIDDEN: React.CSSProperties = {
+  position: 'absolute',
+  width: '1px',
+  height: '1px',
+  padding: 0,
+  margin: '-1px',
+  overflow: 'hidden',
+  clip: 'rect(0, 0, 0, 0)',
+  whiteSpace: 'nowrap',
+  border: 0,
+};
+
+/**
+ * Renders a visually-hidden element with `aria-live` that announces `message`
+ * to screen readers whenever it changes. Use `politeness="assertive"` for
+ * errors/warnings; keep the default `"polite"` for non-critical updates.
+ */
+export function AriaLiveRegion({ message, politeness = 'polite' }: AriaLiveRegionProps) {
+  return (
+    <div
+      role={politeness === 'assertive' ? 'alert' : 'status'}
+      aria-live={politeness}
+      aria-atomic="true"
+      style={VISUALLY_HIDDEN}
+    >
+      {message}
+    </div>
+  );
+}

packages/core/src/components/base/Form.tsx

@@ -194,6 +194,9 @@ export function Form({
 
         {submitted ? (
           <div
+            role="status"
+            aria-live="polite"
+            aria-atomic="true"
             style={{
               padding: theme.spacing.lg,
               backgroundColor: theme.colors.primary,

packages/core/src/components/base/index.ts

@@ -1,5 +1,7 @@
 // Clean named exports - no "default as" needed
 
+export { AriaLiveRegion } from './AriaLiveRegion';
+export type { AriaLiveRegionProps } from './AriaLiveRegion';
 export { TextGrid } from './TextGrid';
 export { TextBlockGrid } from './TextBlockGrid';
 export { MainContentGrid } from './MainContentGrid';

packages/core/src/components/narrative/Carousel/Carousel.tsx

@@ -2,6 +2,7 @@
 
 import React, { useState, useEffect, useCallback, useRef } from 'react';
 import { OverflowImageCard } from './OverFlowImageCard';
+import { AriaLiveRegion } from '../../base/AriaLiveRegion';
 import { CarouselContent } from '@stackwright/types';
 import { useSafeTheme } from '../../../hooks/useSafeTheme';
 import { useBreakpoints } from '../../../hooks/useBreakpoints';
@@ -205,6 +206,11 @@ export const Carousel = (carouselContent: CarouselContent) => {
       </div>
 
       {scrollAndButtonsEnabled && <ArrowButton direction="right" onClick={manualNext} />}
+
+      {/* Announce slide position to screen readers */}
+      <AriaLiveRegion
+        message={`Showing slide ${currentIndex + 1} of ${carouselContent.items.length}`}
+      />
     </div>
   );
 };

packages/core/src/components/structural/SearchModal.tsx

@@ -6,7 +6,8 @@
  * during prebuild.
  */
 
-import React, { useState, useEffect, useCallback, useRef } from 'react';
+import React, { useState, useEffect, useCallback, useRef, useMemo } from 'react';
+import { AriaLiveRegion } from '../base/AriaLiveRegion';
 // fuse.js is NOT imported statically — it is dynamically imported inside the
 // useEffect below so webpack creates a separate async chunk for it.
 // The type-only import gives TypeScript the FuseResult shape without bundling.
@@ -172,6 +173,15 @@ export function SearchModal({
     }
   }, [selectedIndex]);
 
+  // Derive announcement for screen readers based on search state
+  // Must be before early return — React hooks must not be called conditionally
+  const liveMessage = useMemo(() => {
+    if (loading) return 'Loading search results…';
+    if (!query.trim()) return '';
+    if (results.length === 0) return `No results found for "${query}"`;
+    return `${results.length} result${results.length !== 1 ? 's' : ''} found for "${query}"`;
+  }, [loading, query, results.length]);
+
   if (!isOpen) return null;
 
   return (
@@ -200,6 +210,9 @@ export function SearchModal({
         }}
         onClick={(e) => e.stopPropagation()}
       >
+        {/* Screen reader announcement for result count changes */}
+        <AriaLiveRegion message={liveMessage} />
+
         {/* Search Input */}
         <div
           style={{

packages/core/test/components/Form.test.tsx

@@ -293,3 +293,21 @@ describe('Form — client-side validation', () => {
     expect(screen.getByText(/"phone" is required\./)).toBeInTheDocument();
   });
 });
+
+// ---------------------------------------------------------------------------
+// Accessibility — WCAG 4.1.3 live region announcements
+// ---------------------------------------------------------------------------
+
+describe('Form — accessibility', () => {
+  it('success message has role="status" for screen reader announcement', async () => {
+    (global.fetch as ReturnType<typeof vi.fn>).mockResolvedValue({ ok: true });
+    render(<Form {...baseProps} fields={[]} success_message="Your message has been sent!" />);
+    const submitButton = screen.getByRole('button', { name: /submit/i });
+    fireEvent.click(submitButton);
+    await waitFor(() => {
+      const statusEl = document.querySelector('[role="status"]');
+      expect(statusEl).toBeTruthy();
+      expect(statusEl?.textContent).toContain('Your message has been sent!');
+    });
+  });
+});

packages/core/test/components/aria-live-region.test.tsx

@@ -0,0 +1,46 @@
+import React from 'react';
+import { describe, it, expect } from 'vitest';
+import { render } from '@testing-library/react';
+import { AriaLiveRegion } from '../../src/components/base/AriaLiveRegion';
+
+describe('AriaLiveRegion', () => {
+  it('renders a visually-hidden element with the message', () => {
+    const { getByRole } = render(<AriaLiveRegion message="Test announcement" />);
+    const region = getByRole('status');
+    expect(region).toBeTruthy();
+    expect(region.textContent).toBe('Test announcement');
+  });
+
+  it('uses role="status" and aria-live="polite" by default', () => {
+    const { container } = render(<AriaLiveRegion message="Polite message" />);
+    const el = container.firstChild as HTMLElement;
+    expect(el.getAttribute('role')).toBe('status');
+    expect(el.getAttribute('aria-live')).toBe('polite');
+    expect(el.getAttribute('aria-atomic')).toBe('true');
+  });
+
+  it('uses role="alert" and aria-live="assertive" when politeness is assertive', () => {
+    const { container } = render(
+      <AriaLiveRegion message="Error occurred" politeness="assertive" />
+    );
+    const el = container.firstChild as HTMLElement;
+    expect(el.getAttribute('role')).toBe('alert');
+    expect(el.getAttribute('aria-live')).toBe('assertive');
+  });
+
+  it('is visually hidden (clip pattern applied)', () => {
+    const { container } = render(<AriaLiveRegion message="Hidden message" />);
+    const el = container.firstChild as HTMLElement;
+    expect(el.style.position).toBe('absolute');
+    expect(el.style.width).toBe('1px');
+    expect(el.style.height).toBe('1px');
+    expect(el.style.overflow).toBe('hidden');
+  });
+
+  it('updates message content when prop changes', () => {
+    const { rerender, getByRole } = render(<AriaLiveRegion message="First message" />);
+    expect(getByRole('status').textContent).toBe('First message');
+    rerender(<AriaLiveRegion message="Second message" />);
+    expect(getByRole('status').textContent).toBe('Second message');
+  });
+});

packages/core/test/components/content-item-error-boundary.test.tsx

@@ -45,4 +45,18 @@ describe('ContentItemErrorBoundary', () => {
     expect(screen.getByText(/Error rendering "bad"/)).toBeInTheDocument();
     errorSpy.mockRestore();
   });
+
+  it('error state has role="alert" for screen reader announcement', () => {
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    const { container } = render(
+      <ContentItemErrorBoundary contentType="test" label="test-label">
+        <ThrowingComponent />
+      </ContentItemErrorBoundary>
+    );
+    // Error div should have role="alert" so screen readers announce it immediately
+    const alertDiv = container.querySelector('[role="alert"]');
+    expect(alertDiv).toBeTruthy();
+    expect(alertDiv?.textContent).toContain('Render explosion');
+    errorSpy.mockRestore();
+  });
 });