@astryxdesign/core 0.1.4-canary.39ffd21 → 0.1.4-canary.3d64ef2

package/src/Pagination/Pagination.tsx

@@ -35,6 +35,7 @@ import {Icon} from '../Icon';
 import {Selector} from '../Selector';
 import {Text} from '../Text';
 import {useAnnounce} from '../hooks/useAnnounce';
+import {useListFocus} from '../hooks/useListFocus';
 import {mergeProps} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
@@ -370,6 +371,21 @@ export function Pagination({
   // in-flight target instead of stalling on the last committed page.
   const [optimisticPage, setOptimisticPage] = useOptimistic(page);
 
+  // Roving-tabindex + arrow/Home/End keyboard nav for the dots variant, owned
+  // by the shared useListFocus primitive (mirrors SegmentedControl). It stamps a
+  // single tab stop across the dots and moves focus horizontally; selection
+  // follows focus via handleDotsFocus so arrow keys move the active page.
+  const {
+    listRef: dotsListRef,
+    handleKeyDown: handleDotsKeyDown,
+    handleFocus: handleDotsRovingFocus,
+  } = useListFocus<HTMLDivElement>({
+    itemSelector: 'button',
+    hasRovingTabIndex: true,
+    wrap: true,
+    orientation: 'horizontal',
+  });
+
   // Compute pagination state
   const computedTotalPages =
     totalPagesProp ??
@@ -410,6 +426,28 @@ export function Pagination({
     });
   };
 
+  // Selection-follows-focus for the dots (APG radiogroup pattern): useListFocus
+  // only *moves* focus, so when focus lands on a dot -- via arrow/Home/End, or a
+  // click that focuses it -- we select that dot's page. handleDotsRovingFocus
+  // keeps the roving tab stop in sync. The current page is skipped so tabbing
+  // into the group is a no-op.
+  const handleDotsFocus = (e: React.FocusEvent) => {
+    handleDotsRovingFocus(e);
+    if (isDisabled) {
+      return;
+    }
+    const focused = (e.target as HTMLElement | null)?.closest<HTMLElement>(
+      'button[data-page]',
+    );
+    if (!focused) {
+      return;
+    }
+    const nextPage = Number(focused.dataset.page);
+    if (Number.isFinite(nextPage) && nextPage !== optimisticPage) {
+      handlePageChange(nextPage);
+    }
+  };
+
   const handlePrevious = () => {
     if (hasPrevious) {
       handlePageChange(optimisticPage - 1);
@@ -518,33 +556,47 @@ export function Pagination({
         if (computedTotalPages == null) {
           return null;
         }
+
         return (
           <div
+            ref={dotsListRef}
             {...stylex.props(styles.dotsContainer)}
             role="group"
-            aria-label="Page indicators">
-            {Array.from({length: computedTotalPages}, (_, i) => (
-              <button
-                key={i + 1}
-                type="button"
-                aria-label={`Go to page ${i + 1}`}
-                aria-current={i + 1 === optimisticPage ? 'page' : undefined}
-                onClick={() => handlePageChange(i + 1)}
-                disabled={isDisabled}
-                {...mergeProps(
-                  themeProps('pagination-dot', {
-                    active: i + 1 === optimisticPage ? 'active' : null,
-                    size,
-                  }),
-                  stylex.props(
-                    styles.dot,
-                    isSm && styles.dotSm,
-                    i + 1 === optimisticPage && styles.dotActive,
-                    isDisabled && styles.dotDisabled,
-                  ),
-                )}
-              />
-            ))}
+            aria-label="Page indicators"
+            onKeyDown={handleDotsKeyDown}
+            onFocus={handleDotsFocus}>
+            {Array.from({length: computedTotalPages}, (_, i) => {
+              const isActive = i + 1 === optimisticPage;
+              return (
+                <button
+                  key={i + 1}
+                  type="button"
+                  data-page={i + 1}
+                  aria-label={`Go to page ${i + 1}`}
+                  aria-current={isActive ? 'page' : undefined}
+                  // The active dot is the single roving tab stop; useListFocus
+                  // maintains it as focus and the active page move.
+                  tabIndex={isActive ? 0 : -1}
+                  // Selection is driven by focus (handleDotsFocus); clicking only
+                  // needs to focus the dot, which some browsers (Safari) skip for
+                  // buttons, so focus it explicitly.
+                  onClick={e => e.currentTarget.focus()}
+                  disabled={isDisabled}
+                  {...mergeProps(
+                    themeProps('pagination-dot', {
+                      active: isActive ? 'active' : null,
+                      size,
+                    }),
+                    stylex.props(
+                      styles.dot,
+                      isSm && styles.dotSm,
+                      isActive && styles.dotActive,
+                      isDisabled && styles.dotDisabled,
+                    ),
+                  )}
+                />
+              );
+            })}
           </div>
         );
       }

package/src/Popover/Popover.test.tsx

@@ -354,4 +354,69 @@ describe('Popover', () => {
       expect(trigger).toHaveAttribute('aria-expanded', 'true');
     });
   });
+
+  describe('focus restoration', () => {
+    it('returns focus to the trigger when closed via Escape', () => {
+      render(
+        <Popover
+          content={
+            <button type="button" data-testid="inside-content">
+              Inside
+            </button>
+          }
+          label="Test">
+          <button type="button">Open</button>
+        </Popover>,
+      );
+      const trigger = screen.getByRole('button', {name: 'Open'});
+      trigger.focus();
+      expect(trigger).toHaveFocus();
+
+      fireEvent.click(trigger);
+      expect(trigger).toHaveAttribute('aria-expanded', 'true');
+
+      // Move focus into the open popover, as a keyboard user would.
+      const inside = screen.getByTestId('inside-content');
+      inside.focus();
+      expect(inside).toHaveFocus();
+
+      fireEvent.keyDown(document, {key: 'Escape'});
+      expect(trigger).toHaveAttribute('aria-expanded', 'false');
+      expect(trigger).toHaveFocus();
+    });
+
+    it('returns focus to the trigger on light dismiss', () => {
+      render(
+        <Popover
+          content={
+            <button type="button" data-testid="inside-content">
+              Inside
+            </button>
+          }
+          label="Test">
+          <button type="button">Open</button>
+        </Popover>,
+      );
+      const trigger = screen.getByRole('button', {name: 'Open'});
+      trigger.focus();
+
+      fireEvent.click(trigger);
+      expect(trigger).toHaveAttribute('aria-expanded', 'true');
+
+      const inside = screen.getByTestId('inside-content');
+      inside.focus();
+      expect(inside).toHaveFocus();
+
+      // Simulate the browser's light dismiss for popover="auto": clicking
+      // outside fires a `toggle` event with newState "closed".
+      const popoverEl = document.querySelector('[popover]');
+      expect(popoverEl).not.toBeNull();
+      const toggleEvent = new Event('toggle');
+      Object.defineProperty(toggleEvent, 'newState', {value: 'closed'});
+      fireEvent(popoverEl as HTMLElement, toggleEvent);
+
+      expect(trigger).toHaveAttribute('aria-expanded', 'false');
+      expect(trigger).toHaveFocus();
+    });
+  });
 });

package/src/PowerSearch/PowerSearch.doc.mjs

@@ -120,7 +120,7 @@ export const docs = {
       name: 'resultCount',
       type: 'number | string',
       description:
-        'Number of results matching the current filters. When a number, formatted as "N results". When a string, displayed as-is.',
+        'Number of results matching the current filters. When a number, formatted as "N results". When a string, displayed as-is. Changes are announced to screen readers via a polite live region.',
     },
     {
       name: 'size',
@@ -261,7 +261,7 @@ export const docsZh = {
       name: 'resultCount',
       type: 'number | string',
       description:
-        '匹配当前过滤器的结果数量。数字类型时格式化为"N results"。字符串类型时按原样显示。',
+        '匹配当前过滤器的结果数量。数字类型时格式化为"N results"。字符串类型时按原样显示。数量变化会通过 polite 实时区域向屏幕阅读器播报。',
     },
     {
       name: 'size',

package/src/PowerSearch/PowerSearch.test.tsx

@@ -10,10 +10,11 @@
  */
 
 import {useState} from 'react';
-import {describe, it, expect, vi, beforeAll, afterAll} from 'vitest';
+import {describe, it, expect, vi, beforeAll, afterAll, afterEach} from 'vitest';
 import {render, screen, act, fireEvent, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {PowerSearch} from './PowerSearch';
+import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
 import type {PowerSearchConfig, PowerSearchFilter} from './types';
 
 // =============================================================================
@@ -59,6 +60,12 @@ afterAll(() => {
   (HTMLElement.prototype as any).matches = originalMatches;
 });
 
+// Reset the singleton live regions between tests so result-count
+// announcements from one test don't leak into the next.
+afterEach(() => {
+  __resetLiveRegionsForTest();
+});
+
 // =============================================================================
 // Fixtures
 // =============================================================================
@@ -295,4 +302,105 @@ describe('PowerSearch', () => {
       expect(screen.getByRole('combobox')).toBeDisabled();
     });
   });
+
+  describe('result count announcements', () => {
+    const politeRegion = () =>
+      document.querySelector('[data-astryx-live-region="polite"]');
+
+    it('announces the result count to a polite live region when it changes', async () => {
+      const {rerender} = render(
+        <PowerSearch
+          config={config}
+          filters={[]}
+          onChange={() => {}}
+          resultCount={0}
+        />,
+      );
+      rerender(
+        <PowerSearch
+          config={config}
+          filters={[]}
+          onChange={() => {}}
+          resultCount={5}
+        />,
+      );
+      await waitFor(() => {
+        expect(politeRegion()).toHaveTextContent('5 results');
+      });
+    });
+
+    it('announces "1 result" (singular) for a single match', async () => {
+      const {rerender} = render(
+        <PowerSearch
+          config={config}
+          filters={[]}
+          onChange={() => {}}
+          resultCount={0}
+        />,
+      );
+      rerender(
+        <PowerSearch
+          config={config}
+          filters={[]}
+          onChange={() => {}}
+          resultCount={1}
+        />,
+      );
+      await waitFor(() => {
+        expect(politeRegion()).toHaveTextContent('1 result');
+      });
+      expect(politeRegion()?.textContent).not.toMatch(/results/);
+    });
+
+    it('announces a string result count verbatim', async () => {
+      const {rerender} = render(
+        <PowerSearch
+          config={config}
+          filters={[]}
+          onChange={() => {}}
+          resultCount="0 items"
+        />,
+      );
+      rerender(
+        <PowerSearch
+          config={config}
+          filters={[]}
+          onChange={() => {}}
+          resultCount="Showing 1.2k matches"
+        />,
+      );
+      await waitFor(() => {
+        expect(politeRegion()).toHaveTextContent('Showing 1.2k matches');
+      });
+    });
+
+    it('does not announce the result count present on initial mount', async () => {
+      render(
+        <PowerSearch
+          config={config}
+          filters={[]}
+          onChange={() => {}}
+          resultCount={42}
+        />,
+      );
+      // Flush effects and any pending live-region rAF writes.
+      await act(async () => {
+        await new Promise(resolve => setTimeout(resolve, 50));
+      });
+      expect(politeRegion()?.textContent ?? '').not.toContain('42');
+    });
+
+    it('leaves Typeahead dropdown announcements intact and stays silent when no resultCount is set', async () => {
+      const user = userEvent.setup();
+      render(<PowerSearchWrapper config={config} />);
+      const input = screen.getByRole('combobox');
+      await user.click(input);
+      await user.type(input, 'Status');
+      // BaseTypeahead announces the dropdown suggestion count; PowerSearch adds
+      // no result-count announcement because resultCount is unset.
+      await waitFor(() => {
+        expect(politeRegion()?.textContent).toMatch(/\d+ results?/);
+      });
+    });
+  });
 });

package/src/PowerSearch/PowerSearch.tsx

@@ -16,6 +16,7 @@
 
 import React, {
   useCallback,
+  useEffect,
   useImperativeHandle,
   useMemo,
   useRef,
@@ -38,6 +39,7 @@ import type {IconType} from '../Icon';
 import type {IconName} from '../Icon/globalIconRegistry';
 import type {InputStatus} from '../Field';
 import {usePopover} from '../Popover/usePopover';
+import {useAnnounce} from '../hooks/useAnnounce';
 import {
   spacingVars,
   colorVars,
@@ -945,23 +947,42 @@ export function PowerSearch({
     isReadOnly,
   ]);
 
+  // Plain-text form of the result count, shared by the visible label and the
+  // screen-reader announcement so the two never drift.
+  const resultCountText = useMemo((): string | null => {
+    if (resultCount == null) {
+      return null;
+    }
+    if (typeof resultCount === 'number') {
+      const formatted = new Intl.NumberFormat().format(resultCount);
+      return `${formatted} ${resultCount === 1 ? 'result' : 'results'}`;
+    }
+    return resultCount;
+  }, [resultCount]);
+
+  // Announce result-count changes to screen readers through a polite live
+  // region, mirroring the way Typeahead announces its dropdown result count.
+  // The count is otherwise only shown visually and stays silent to assistive
+  // tech. Skip the first run so the count already present on mount isn't
+  // announced unprompted — only user-driven changes are spoken.
+  const announce = useAnnounce();
+  const hasMountedRef = useRef(false);
+  useEffect(() => {
+    if (!hasMountedRef.current) {
+      hasMountedRef.current = true;
+      return;
+    }
+    if (resultCountText != null) {
+      announce(resultCountText);
+    }
+  }, [resultCountText, announce]);
+
   // Build combined endContent from resultCount + endContent props
   const combinedEndContent = useMemo((): React.ReactNode => {
-    let resultCountNode: React.ReactNode = null;
-    if (resultCount != null) {
-      if (typeof resultCount === 'number') {
-        const formatted = new Intl.NumberFormat().format(resultCount);
-        resultCountNode = (
-          <span {...stylex.props(resultCountStyles.text)}>
-            {formatted} {resultCount === 1 ? 'result' : 'results'}
-          </span>
-        );
-      } else {
-        resultCountNode = (
-          <span {...stylex.props(resultCountStyles.text)}>{resultCount}</span>
-        );
-      }
-    }
+    const resultCountNode =
+      resultCountText != null ? (
+        <span {...stylex.props(resultCountStyles.text)}>{resultCountText}</span>
+      ) : null;
 
     if (resultCountNode && endContent) {
       return (
@@ -972,7 +993,7 @@ export function PowerSearch({
       );
     }
     return resultCountNode || endContent || undefined;
-  }, [resultCount, endContent]);
+  }, [resultCountText, endContent]);
 
   return (
     <>

package/src/ProgressBar/ProgressBar.test.tsx

@@ -140,6 +140,16 @@ describe('ProgressBar', () => {
     expect(progressbar).toHaveAttribute('aria-valuemax', '0');
   });
 
+  it('does not render NaN in the value label when max is zero', () => {
+    render(<ProgressBar value={0} max={0} label="Empty" hasValueLabel />);
+    expect(screen.queryByText(/NaN|Infinity/)).not.toBeInTheDocument();
+    const progressbar = screen.getByRole('progressbar');
+    expect(progressbar.getAttribute('aria-valuetext') ?? '').not.toMatch(
+      /NaN|Infinity/,
+    );
+    expect(screen.getByText('0%')).toBeInTheDocument();
+  });
+
   // Disabled state
   describe('disabled state', () => {
     it('renders with isDisabled', () => {

package/src/ProgressBar/ProgressBar.tsx

@@ -228,7 +228,8 @@ const variantStyles = stylex.create({
 });
 
 function defaultFormatValueLabel(value: number, max: number): string {
-  return `${Math.round((value / max) * 100)}%`;
+  const pct = max > 0 ? Math.round((value / max) * 100) : 0;
+  return `${pct}%`;
 }
 
 /**

package/src/Resizable/ResizeHandle.test.tsx

@@ -0,0 +1,180 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file ResizeHandle.test.tsx
+ * @input Uses vitest, @testing-library/react, useResizable, ResizeHandle
+ * @output Unit tests for ResizeHandle keyboard operability and ARIA state
+ * @position Testing; validates ResizeHandle.tsx implementation
+ *
+ * SYNC: When ResizeHandle.tsx changes, update tests to match new behavior
+ *
+ * These tests guard the WAI-ARIA window-splitter keyboard contract: the
+ * keydown handler must live on the focusable `role="separator"` element.
+ * Keyboard resizing is pure state math in useResizable (no layout
+ * measurement), so the observable effect asserted here is aria-valuenow,
+ * which is bound to the region's `_size`.
+ */
+
+import {describe, it, expect, vi} from 'vitest';
+import {render, screen, fireEvent, act} from '@testing-library/react';
+import {ResizeHandle} from './ResizeHandle';
+import type {ResizeHandleProps} from './ResizeHandle';
+import {useResizable} from './useResizable';
+import type {UseResizableSingleConfig} from './useResizable';
+
+const KEYBOARD_STEP = 10;
+const KEYBOARD_LARGE_STEP = 50;
+
+function Harness({
+  config,
+  handleProps,
+}: {
+  config?: UseResizableSingleConfig;
+  handleProps?: Partial<ResizeHandleProps>;
+}) {
+  const region = useResizable(
+    config ?? {defaultSize: 200, minSizePx: 100, maxSizePx: 400},
+  );
+  return (
+    <ResizeHandle resizable={region.props} label="Resize" {...handleProps} />
+  );
+}
+
+function getSeparator(): HTMLElement {
+  return screen.getByRole('separator');
+}
+
+describe('ResizeHandle', () => {
+  // --- ARIA wiring ---
+
+  it('exposes the region size and bounds via ARIA', () => {
+    render(<Harness />);
+    const separator = getSeparator();
+    expect(separator).toHaveAttribute('aria-valuenow', '200');
+    expect(separator).toHaveAttribute('aria-valuemin', '100');
+    expect(separator).toHaveAttribute('aria-valuemax', '400');
+    // Horizontal layout splits along the vertical axis.
+    expect(separator).toHaveAttribute('aria-orientation', 'vertical');
+    expect(separator).toHaveAttribute('aria-label', 'Resize');
+  });
+
+  it('makes the separator focusable', () => {
+    render(<Harness />);
+    const separator = getSeparator();
+    expect(separator).toHaveAttribute('tabindex', '0');
+    act(() => separator.focus());
+    expect(separator).toHaveFocus();
+  });
+
+  // --- Keyboard resizing (the fix: handler lives on the focused separator) ---
+
+  it('grows the panel by a step on ArrowRight', () => {
+    render(<Harness />);
+    const separator = getSeparator();
+    act(() => separator.focus());
+    fireEvent.keyDown(separator, {key: 'ArrowRight'});
+    expect(separator).toHaveAttribute(
+      'aria-valuenow',
+      String(200 + KEYBOARD_STEP),
+    );
+  });
+
+  it('shrinks the panel by a step on ArrowLeft', () => {
+    render(<Harness />);
+    const separator = getSeparator();
+    act(() => separator.focus());
+    fireEvent.keyDown(separator, {key: 'ArrowLeft'});
+    expect(separator).toHaveAttribute(
+      'aria-valuenow',
+      String(200 - KEYBOARD_STEP),
+    );
+  });
+
+  it('uses the large step when Shift is held', () => {
+    render(<Harness />);
+    const separator = getSeparator();
+    act(() => separator.focus());
+    fireEvent.keyDown(separator, {key: 'ArrowRight', shiftKey: true});
+    expect(separator).toHaveAttribute(
+      'aria-valuenow',
+      String(200 + KEYBOARD_LARGE_STEP),
+    );
+  });
+
+  it('jumps to the minimum on Home', () => {
+    render(<Harness />);
+    const separator = getSeparator();
+    act(() => separator.focus());
+    fireEvent.keyDown(separator, {key: 'Home'});
+    expect(separator).toHaveAttribute('aria-valuenow', '100');
+  });
+
+  it('jumps to the maximum on End', () => {
+    render(<Harness />);
+    const separator = getSeparator();
+    act(() => separator.focus());
+    fireEvent.keyDown(separator, {key: 'End'});
+    expect(separator).toHaveAttribute('aria-valuenow', '400');
+  });
+
+  it('resizes along the block axis for a vertical handle', () => {
+    render(
+      <Harness
+        config={{defaultSize: 200, minSizePx: 100, maxSizePx: 400}}
+        handleProps={{direction: 'vertical'}}
+      />,
+    );
+    const separator = getSeparator();
+    expect(separator).toHaveAttribute('aria-orientation', 'horizontal');
+    act(() => separator.focus());
+    fireEvent.keyDown(separator, {key: 'ArrowDown'});
+    expect(separator).toHaveAttribute(
+      'aria-valuenow',
+      String(200 + KEYBOARD_STEP),
+    );
+    fireEvent.keyDown(separator, {key: 'ArrowUp'});
+    expect(separator).toHaveAttribute('aria-valuenow', '200');
+  });
+
+  it('collapses on Enter when the region is collapsible', () => {
+    render(
+      <Harness
+        config={{
+          defaultSize: 200,
+          minSizePx: 100,
+          maxSizePx: 400,
+          collapsible: true,
+        }}
+      />,
+    );
+    const separator = getSeparator();
+    act(() => separator.focus());
+    fireEvent.keyDown(separator, {key: 'Enter'});
+    expect(separator).toHaveAttribute('aria-valuenow', '0');
+  });
+
+  // --- Disabled guard ---
+
+  it('ignores keyboard input when disabled', () => {
+    render(<Harness handleProps={{isDisabled: true}} />);
+    const separator = getSeparator();
+    expect(separator).toHaveAttribute('tabindex', '-1');
+    fireEvent.keyDown(separator, {key: 'ArrowRight'});
+    expect(separator).toHaveAttribute('aria-valuenow', '200');
+  });
+
+  // --- Prop composition (ordering choice: handler sits after {...props}) ---
+
+  it('runs a consumer onKeyDown alongside keyboard resizing', () => {
+    const onKeyDown = vi.fn();
+    render(<Harness handleProps={{onKeyDown}} />);
+    const separator = getSeparator();
+    act(() => separator.focus());
+    fireEvent.keyDown(separator, {key: 'ArrowRight'});
+    expect(onKeyDown).toHaveBeenCalledTimes(1);
+    expect(separator).toHaveAttribute(
+      'aria-valuenow',
+      String(200 + KEYBOARD_STEP),
+    );
+  });
+});

package/src/Resizable/ResizeHandle.tsx

@@ -510,7 +510,16 @@ export function ResizeHandle({
         ),
         className,
       )}
-      {...props}>
+      {...props}
+      // Keyboard resizing must fire from the focusable separator, not a child:
+      // keydown fires on the focused element and bubbles up, so a handler on a
+      // descendant never runs (per the WAI-ARIA window-splitter pattern).
+      // Placed after {...props} and composed with any consumer onKeyDown so
+      // this accessibility-critical handler can't be clobbered by a passed prop.
+      onKeyDown={e => {
+        props.onKeyDown?.(e);
+        handleKeyDown(e);
+      }}>
       {/* Wider invisible hit area for pointer interaction */}
       <div
         {...stylex.props(
@@ -528,7 +537,6 @@ export function ResizeHandle({
             setIsHovered(false);
           }
         }}
-        onKeyDown={handleKeyDown}
       />
       {/* Pill grip indicator — themed via .astryx-resize-handle-pill */}
       {children ?? (

package/src/SegmentedControl/SegmentedControl.doc.mjs

@@ -16,7 +16,7 @@ export const docs = {
   theming: {
     targets: [
       {className: 'astryx-segmented-control', visualProps: ['size']},
-      {className: 'astryx-segmented-control-item'},
+      {className: 'astryx-segmented-control-item', visualProps: ['size'], states: ['selected', 'disabled']},
     ],
     vars: [
       {name: '--_segmented-control-radius', description: 'Border radius of the segmented control', default: 'var(--radius-element)', private: true},