@astryxdesign/core 0.1.3 → 0.1.4-canary.01e5b29

package/src/Overlay/Overlay.test.tsx

@@ -0,0 +1,356 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Overlay.test.tsx
+ * @input Uses vitest, @testing-library/react, Overlay + useOverlay
+ * @output Characterization tests for the Overlay component and useOverlay hook
+ * @position Testing; validates the overlay/scrim rendering + touch-toggle contract
+ *
+ * SYNC: When Overlay.tsx / useOverlay.tsx / OverlayScrim.tsx change,
+ * update tests to match new behavior
+ */
+
+import {describe, it, expect, beforeEach, afterEach} from 'vitest';
+import {render, screen, renderHook} from '@testing-library/react';
+import {createRef} from 'react';
+import {Overlay} from './Overlay';
+import {useOverlay} from './useOverlay';
+
+/** The scrim is the div carrying data-position (from themeProps). */
+function getScrim(container: HTMLElement): HTMLElement {
+  const el = container.querySelector<HTMLElement>('[data-position]');
+  if (!el) {
+    throw new Error('scrim element not found');
+  }
+  return el;
+}
+
+/**
+ * Force window.matchMedia('(hover: none)') to report a given value so we can
+ * exercise the touch vs. pointer branches of useOverlay. Returns a restore fn.
+ */
+function mockHoverNone(matches: boolean): () => void {
+  const original = window.matchMedia;
+  window.matchMedia = ((query: string) => ({
+    matches: query.includes('hover: none') ? matches : false,
+    media: query,
+    onchange: null,
+    addListener: () => {},
+    removeListener: () => {},
+    addEventListener: () => {},
+    removeEventListener: () => {},
+    dispatchEvent: () => false,
+  }));
+  return () => {
+    window.matchMedia = original;
+  };
+}
+
+describe('Overlay', () => {
+  describe('rendering & structure', () => {
+    it('renders the base children', () => {
+      render(
+        <Overlay content={<span>badge</span>}>
+          <img alt="hero" src="x.jpg" />
+        </Overlay>,
+      );
+      expect(screen.getByAltText('hero')).toBeInTheDocument();
+    });
+
+    it('renders the overlay content inside the scrim', () => {
+      render(
+        <Overlay content={<button type="button">Quick view</button>}>
+          <div>base</div>
+        </Overlay>,
+      );
+      expect(
+        screen.getByRole('button', {name: 'Quick view'}),
+      ).toBeInTheDocument();
+    });
+
+    it('renders a root div carrying the astryx-overlay class', () => {
+      const {container} = render(
+        <Overlay content={<span>c</span>}>
+          <div>base</div>
+        </Overlay>,
+      );
+      const root = container.firstElementChild as HTMLElement;
+      expect(root.tagName).toBe('DIV');
+      expect(root.className).toContain('astryx-overlay');
+    });
+
+    it('places the scrim after the base children in DOM order', () => {
+      const {container} = render(
+        <Overlay content={<span data-testid="ovl">c</span>}>
+          <div data-testid="base">base</div>
+        </Overlay>,
+      );
+      const root = container.firstElementChild as HTMLElement;
+      const base = screen.getByTestId('base');
+      const scrim = getScrim(container);
+      // base comes before scrim
+      expect(
+        base.compareDocumentPosition(scrim) & Node.DOCUMENT_POSITION_FOLLOWING,
+      ).toBeTruthy();
+      expect(root).toContainElement(scrim);
+    });
+
+    it('applies the astryx-overlay-scrim class to the scrim', () => {
+      const {container} = render(
+        <Overlay content={<span>c</span>}>
+          <div>b</div>
+        </Overlay>,
+      );
+      expect(getScrim(container).className).toContain('astryx-overlay-scrim');
+    });
+  });
+
+  describe('position', () => {
+    it('defaults data-position to "fill"', () => {
+      const {container} = render(
+        <Overlay content={<span>c</span>}>
+          <div>b</div>
+        </Overlay>,
+      );
+      expect(getScrim(container).getAttribute('data-position')).toBe('fill');
+    });
+
+    it.each(['fill', 'bottom', 'top'] as const)(
+      'reflects position="%s" as data-position',
+      position => {
+        const {container} = render(
+          <Overlay position={position} content={<span>c</span>}>
+            <div>b</div>
+          </Overlay>,
+        );
+        expect(getScrim(container).getAttribute('data-position')).toBe(
+          position,
+        );
+      },
+    );
+  });
+
+  describe('scrim mode → media theme inversion', () => {
+    it('dark scrim (default) wraps content in a dark MediaTheme', () => {
+      const {container} = render(
+        <Overlay content={<span>c</span>}>
+          <div>b</div>
+        </Overlay>,
+      );
+      expect(
+        container.querySelector('[data-astryx-media="dark"]'),
+      ).toBeInTheDocument();
+    });
+
+    it('light scrim wraps content in a light MediaTheme', () => {
+      const {container} = render(
+        <Overlay scrim="light" content={<span>c</span>}>
+          <div>b</div>
+        </Overlay>,
+      );
+      expect(
+        container.querySelector('[data-astryx-media="light"]'),
+      ).toBeInTheDocument();
+      expect(
+        container.querySelector('[data-astryx-media="dark"]'),
+      ).not.toBeInTheDocument();
+    });
+
+    it('scrim={false} renders no MediaTheme wrapper', () => {
+      const {container} = render(
+        <Overlay scrim={false} content={<span>c</span>}>
+          <div>b</div>
+        </Overlay>,
+      );
+      expect(
+        container.querySelector('[data-astryx-media]'),
+      ).not.toBeInTheDocument();
+    });
+  });
+
+  describe('controlled visibility (isOpen)', () => {
+    it('marks the scrim inert when isOpen is false', () => {
+      const {container} = render(
+        <Overlay isOpen={false} content={<span>c</span>}>
+          <div>b</div>
+        </Overlay>,
+      );
+      expect(getScrim(container).hasAttribute('inert')).toBe(true);
+    });
+
+    it('does not mark the scrim inert when isOpen is true', () => {
+      const {container} = render(
+        <Overlay isOpen content={<span>c</span>}>
+          <div>b</div>
+        </Overlay>,
+      );
+      expect(getScrim(container).hasAttribute('inert')).toBe(false);
+    });
+
+    it('is never inert in uncontrolled (CSS-driven) mode', () => {
+      const {container} = render(
+        <Overlay showOn="hover" content={<span>c</span>}>
+          <div>b</div>
+        </Overlay>,
+      );
+      expect(getScrim(container).hasAttribute('inert')).toBe(false);
+    });
+
+    it('toggles inert when the isOpen prop flips', () => {
+      const {container, rerender} = render(
+        <Overlay isOpen={false} content={<span>c</span>}>
+          <div>b</div>
+        </Overlay>,
+      );
+      expect(getScrim(container).hasAttribute('inert')).toBe(true);
+      rerender(
+        <Overlay isOpen content={<span>c</span>}>
+          <div>b</div>
+        </Overlay>,
+      );
+      expect(getScrim(container).hasAttribute('inert')).toBe(false);
+    });
+  });
+
+  describe('styling & ref', () => {
+    it('forwards ref to the root div element', () => {
+      const ref = createRef<HTMLDivElement>();
+      render(
+        <Overlay ref={ref} content={<span>c</span>}>
+          <div>b</div>
+        </Overlay>,
+      );
+      expect(ref.current).toBeInstanceOf(HTMLDivElement);
+      expect(ref.current?.className).toContain('astryx-overlay');
+    });
+
+    it('merges a caller className onto the root', () => {
+      const {container} = render(
+        <Overlay className="custom-cls" content={<span>c</span>}>
+          <div>b</div>
+        </Overlay>,
+      );
+      const root = container.firstElementChild as HTMLElement;
+      expect(root.className).toContain('custom-cls');
+      expect(root.className).toContain('astryx-overlay');
+    });
+
+    it('merges a caller inline style onto the root', () => {
+      const {container} = render(
+        <Overlay style={{opacity: 0.5}} content={<span>c</span>}>
+          <div>b</div>
+        </Overlay>,
+      );
+      const root = container.firstElementChild as HTMLElement;
+      expect(root.style.opacity).toBe('0.5');
+    });
+  });
+});
+
+describe('useOverlay', () => {
+  describe('return shape', () => {
+    it('exposes containerRef, containerProps, element and renderOverlay', () => {
+      const {result} = renderHook(() => useOverlay());
+      expect(result.current.containerRef).toHaveProperty('current');
+      expect(result.current.containerProps).toBeDefined();
+      expect(typeof result.current.renderOverlay).toBe('function');
+    });
+
+    it('containerProps.className is a non-empty marker string', () => {
+      const {result} = renderHook(() => useOverlay());
+      expect(typeof result.current.containerProps.className).toBe('string');
+      expect(result.current.containerProps.className?.length).toBeGreaterThan(
+        0,
+      );
+    });
+
+    it('returns element=null when no content is provided', () => {
+      const {result} = renderHook(() => useOverlay({showOn: 'hover'}));
+      expect(result.current.element).toBeNull();
+    });
+
+    it('returns a scrim element when content is provided', () => {
+      const {result} = renderHook(() => useOverlay({content: <span>c</span>}));
+      expect(result.current.element).not.toBeNull();
+    });
+
+    it('renderOverlay(children) produces a renderable scrim', () => {
+      const {result} = renderHook(() => useOverlay({showOn: 'hover'}));
+      const el = result.current.renderOverlay(<span>on demand</span>);
+      const {container} = render(el);
+      expect(screen.getByText('on demand')).toBeInTheDocument();
+      expect(getScrim(container)).toBeInTheDocument();
+    });
+  });
+
+  describe('pointer (non-touch) device', () => {
+    let restore: () => void;
+    beforeEach(() => {
+      restore = mockHoverNone(false);
+    });
+    afterEach(() => restore());
+
+    it('does not attach touch toggle handlers in hover mode', () => {
+      const {result} = renderHook(() => useOverlay({showOn: 'hover'}));
+      expect(result.current.containerProps.onClick).toBeUndefined();
+      expect(result.current.containerProps.onMouseUp).toBeUndefined();
+    });
+  });
+
+  describe('touch device', () => {
+    let restore: () => void;
+    beforeEach(() => {
+      restore = mockHoverNone(true);
+    });
+    afterEach(() => restore());
+
+    it('attaches tap-to-toggle handlers in hover mode', () => {
+      const {result} = renderHook(() => useOverlay({showOn: 'hover'}));
+      expect(typeof result.current.containerProps.onClick).toBe('function');
+      expect(typeof result.current.containerProps.onMouseUp).toBe('function');
+    });
+
+    it('does NOT attach toggle handlers when showOn="always" (no toggle needed)', () => {
+      const {result} = renderHook(() => useOverlay({showOn: 'always'}));
+      expect(result.current.containerProps.onClick).toBeUndefined();
+      expect(result.current.containerProps.onMouseUp).toBeUndefined();
+    });
+
+    it('does NOT attach toggle handlers when showOn="focus"', () => {
+      const {result} = renderHook(() => useOverlay({showOn: 'focus'}));
+      expect(result.current.containerProps.onClick).toBeUndefined();
+    });
+
+    it('a consumer prop isOpen overrides the touch toggle (scrim reflects it)', () => {
+      // With isOpen provided, the scrim is controlled regardless of touch.
+      const {container} = render(
+        <Overlay showOn="hover" isOpen={false} content={<span>c</span>}>
+          <div>b</div>
+        </Overlay>,
+      );
+      expect(getScrim(container).hasAttribute('inert')).toBe(true);
+    });
+  });
+
+  describe('memoization', () => {
+    it('returns a stable renderOverlay across re-renders with same options', () => {
+      const {result, rerender} = renderHook(
+        (props: {showOn: 'hover' | 'always'}) => useOverlay(props),
+        {initialProps: {showOn: 'hover'}},
+      );
+      const first = result.current.renderOverlay;
+      rerender({showOn: 'hover'});
+      expect(result.current.renderOverlay).toBe(first);
+    });
+
+    it('returns a new renderOverlay when options change', () => {
+      const {result, rerender} = renderHook(
+        (props: {showOn: 'hover' | 'always'}) => useOverlay(props),
+        {initialProps: {showOn: 'hover'}},
+      );
+      const first = result.current.renderOverlay;
+      rerender({showOn: 'always'});
+      expect(result.current.renderOverlay).not.toBe(first);
+    });
+  });
+});

package/src/Pagination/Pagination.test.tsx

@@ -345,6 +345,149 @@ describe('Pagination', () => {
       const activeDot = screen.getByRole('button', {name: 'Go to page 3'});
       expect(activeDot).toHaveAttribute('aria-current', 'page');
     });
+
+    // -------------------------------------------------------------------------
+    // Keyboard navigation (roving tabindex + arrow keys via useListFocus).
+    // Selection follows focus: arrow/Home/End move focus and select that page.
+    // -------------------------------------------------------------------------
+
+    it('uses roving tabindex — active dot has tabIndex 0, others -1', () => {
+      render(
+        <Pagination
+          page={2}
+          onChange={() => {}}
+          totalPages={4}
+          variant="dots"
+        />,
+      );
+      expect(
+        screen.getByRole('button', {name: 'Go to page 2'}),
+      ).toHaveAttribute('tabindex', '0');
+      expect(
+        screen.getByRole('button', {name: 'Go to page 1'}),
+      ).toHaveAttribute('tabindex', '-1');
+      expect(
+        screen.getByRole('button', {name: 'Go to page 3'}),
+      ).toHaveAttribute('tabindex', '-1');
+    });
+
+    it('ArrowRight moves focus to the next dot and selects it', async () => {
+      const user = userEvent.setup();
+      const onChange = vi.fn();
+      render(
+        <Pagination
+          page={2}
+          onChange={onChange}
+          totalPages={4}
+          variant="dots"
+        />,
+      );
+      screen.getByRole('button', {name: 'Go to page 2'}).focus();
+      await user.keyboard('{ArrowRight}');
+      expect(onChange).toHaveBeenCalledWith(3);
+      expect(screen.getByRole('button', {name: 'Go to page 3'})).toHaveFocus();
+    });
+
+    it('ArrowLeft moves focus to the previous dot and selects it', async () => {
+      const user = userEvent.setup();
+      const onChange = vi.fn();
+      render(
+        <Pagination
+          page={3}
+          onChange={onChange}
+          totalPages={4}
+          variant="dots"
+        />,
+      );
+      screen.getByRole('button', {name: 'Go to page 3'}).focus();
+      await user.keyboard('{ArrowLeft}');
+      expect(onChange).toHaveBeenCalledWith(2);
+      expect(screen.getByRole('button', {name: 'Go to page 2'})).toHaveFocus();
+    });
+
+    it('Home selects the first page, End the last', async () => {
+      const user = userEvent.setup();
+      const onChange = vi.fn();
+      const {rerender} = render(
+        <Pagination
+          page={3}
+          onChange={onChange}
+          totalPages={5}
+          variant="dots"
+        />,
+      );
+      screen.getByRole('button', {name: 'Go to page 3'}).focus();
+      await user.keyboard('{Home}');
+      expect(onChange).toHaveBeenCalledWith(1);
+      expect(screen.getByRole('button', {name: 'Go to page 1'})).toHaveFocus();
+
+      onChange.mockClear();
+      rerender(
+        <Pagination
+          page={3}
+          onChange={onChange}
+          totalPages={5}
+          variant="dots"
+        />,
+      );
+      screen.getByRole('button', {name: 'Go to page 3'}).focus();
+      await user.keyboard('{End}');
+      expect(onChange).toHaveBeenCalledWith(5);
+      expect(screen.getByRole('button', {name: 'Go to page 5'})).toHaveFocus();
+    });
+
+    it('wraps from the last dot to the first with ArrowRight', async () => {
+      const user = userEvent.setup();
+      const onChange = vi.fn();
+      render(
+        <Pagination
+          page={4}
+          onChange={onChange}
+          totalPages={4}
+          variant="dots"
+        />,
+      );
+      screen.getByRole('button', {name: 'Go to page 4'}).focus();
+      await user.keyboard('{ArrowRight}');
+      expect(onChange).toHaveBeenCalledWith(1);
+      expect(screen.getByRole('button', {name: 'Go to page 1'})).toHaveFocus();
+    });
+
+    it('wraps from the first dot to the last with ArrowLeft', async () => {
+      const user = userEvent.setup();
+      const onChange = vi.fn();
+      render(
+        <Pagination
+          page={1}
+          onChange={onChange}
+          totalPages={4}
+          variant="dots"
+        />,
+      );
+      screen.getByRole('button', {name: 'Go to page 1'}).focus();
+      await user.keyboard('{ArrowLeft}');
+      expect(onChange).toHaveBeenCalledWith(4);
+      expect(screen.getByRole('button', {name: 'Go to page 4'})).toHaveFocus();
+    });
+
+    it('does not navigate with arrow keys when disabled', async () => {
+      const user = userEvent.setup();
+      const onChange = vi.fn();
+      render(
+        <Pagination
+          page={2}
+          onChange={onChange}
+          totalPages={4}
+          variant="dots"
+          isDisabled
+        />,
+      );
+      const dot = screen.getByRole('button', {name: 'Go to page 2'});
+      expect(dot).toBeDisabled();
+      dot.focus();
+      await user.keyboard('{ArrowRight}');
+      expect(onChange).not.toHaveBeenCalled();
+    });
   });
 
   // ---------------------------------------------------------------------------
@@ -760,4 +903,23 @@ describe('Pagination', () => {
       ).not.toBeInTheDocument();
     });
   });
+
+  describe('rest forwarding', () => {
+    it('forwards data-testid, id, and aria-* to the root nav', () => {
+      const {container} = render(
+        <Pagination
+          page={1}
+          onChange={() => {}}
+          totalPages={3}
+          data-testid="pager"
+          id="pager-1"
+          aria-describedby="hint"
+        />,
+      );
+      const nav = container.querySelector('nav')!;
+      expect(nav).toHaveAttribute('data-testid', 'pager');
+      expect(nav).toHaveAttribute('id', 'pager-1');
+      expect(nav).toHaveAttribute('aria-describedby', 'hint');
+    });
+  });
 });

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';
@@ -349,6 +350,7 @@ export function Pagination({
   className,
   style,
   ref,
+  ...rest
 }: PaginationProps) {
   const [, startTransition] = useTransition();
 
@@ -370,6 +372,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 +427,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 +557,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>
         );
       }
@@ -558,14 +611,15 @@ export function Pagination({
   return (
     <nav
       ref={ref}
-      aria-label={label}
-      data-testid={testId}
       {...mergeProps(
         themeProps('pagination', {variant, size}),
         stylex.props(styles.root, xstyle),
         className,
         style,
-      )}>
+      )}
+      {...rest}
+      aria-label={label}
+      data-testid={testId}>
       {pageSizeOptions != null && pageSizeOptions.length > 0 && (
         <div {...stylex.props(styles.pageSizeSelector)}>
           <div {...stylex.props(styles.pageSizeSelectorControl)}>