@astryxdesign/core 0.1.4 → 0.1.5-canary.76e6697

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/Overlay/useOverlay.tsx

@@ -149,7 +149,6 @@ export interface UseOverlayResult {
  *   showOn: 'hover',
  *   content: <Button label="Quick view" variant="ghost" />,
  * });
- *
  * <Card ref={overlay.containerRef} {...overlay.containerProps}>
  *   <Layout content={...} />
  *   {overlay.element}
@@ -158,9 +157,7 @@ export interface UseOverlayResult {
  *
  * @example
  * ```
- * // Callback mode — render on demand
  * const overlay = useOverlay({ showOn: 'hover' });
- *
  * <div ref={overlay.containerRef} {...overlay.containerProps}>
  *   <img src={src} />
  *   {overlay.renderOverlay(<Button label="Quick view" />)}

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');
+    });
+  });
 });