@astryxdesign/core 0.3.0 → 0.4.0

package/src/hooks/useContainerReveal.test.tsx

@@ -3,61 +3,55 @@
 /**
  * @file useContainerReveal.test.tsx
  * @input Uses vitest, @testing-library/react, useContainerReveal
- * @output Unit tests for the marker-pool free-list, per-instance scoping, the
- *   inert (disabled) path, and the content-option → style-block mapping.
- * @position Testing; validates useContainerReveal.ts and its pool.
+ * @output Unit tests for the enabled/disabled contract, the dynamic isEnabled
+ *   prop, the content-option → style-block mapping, and the promise that a
+ *   large flat list mounts without dev warnings.
+ * @position Testing; validates useContainerReveal.ts.
+ *
+ * Nesting isolation is a cascade behavior jsdom does not implement, so it is
+ * verified in a real browser (Storybook's NestedIsolation story) rather than
+ * asserted here.
  *
  * SYNC: When useContainerReveal.ts changes, update these tests.
  */
 
-import {describe, it, expect} from 'vitest';
-import {renderHook, render, act} from '@testing-library/react';
+import {describe, it, expect, vi, afterEach} from 'vitest';
+import {renderHook, render} from '@testing-library/react';
 import {useContainerReveal} from './useContainerReveal';
-import {POOL_SIZE} from './containerReveal.pool.stylex';
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
 
 describe('useContainerReveal', () => {
   it('returns spreadable getter props for container and content', () => {
     const {result} = renderHook(() => useContainerReveal());
     const container = result.current.getContainerProps();
     const content = result.current.getContentRevealProps();
-    expect(container).toHaveProperty('className');
-    expect(content).toHaveProperty('className');
     expect(typeof container.className).toBe('string');
     expect(typeof content.className).toBe('string');
   });
 
-  it('is inert when disabled: no marker class, empty content props', () => {
-    const {result} = renderHook(() =>
-      useContainerReveal({isEnabled: false}),
-    );
+  it('is inert when disabled: no container class, empty content props', () => {
+    const {result} = renderHook(() => useContainerReveal({isEnabled: false}));
     expect(result.current.getContainerProps()).toEqual({});
     expect(result.current.getContentRevealProps()).toEqual({});
   });
 
-  it('gives two concurrently mounted containers DISTINCT marker classes', () => {
-    // The core leak-safety property: nested/concurrent containers must never
-    // share a marker, or an ancestor container's :hover would reveal a
-    // descendant container's content.
-    const a = renderHook(() => useContainerReveal());
-    const b = renderHook(() => useContainerReveal());
-    const classA = a.result.current.getContainerProps().className;
-    const classB = b.result.current.getContainerProps().className;
-    expect(classA).toBeTruthy();
-    expect(classB).toBeTruthy();
-    expect(classA).not.toBe(classB);
-    a.unmount();
-    b.unmount();
-  });
+  it('follows isEnabled after mount, in both directions', () => {
+    const {result, rerender} = renderHook(
+      ({isEnabled}) => useContainerReveal({isEnabled}),
+      {initialProps: {isEnabled: true}},
+    );
+    expect(result.current.getContentRevealProps().className).toBeTruthy();
 
-  it('recycles a slot after unmount (free-list release)', () => {
-    const first = renderHook(() => useContainerReveal());
-    const firstClass = first.result.current.getContainerProps().className;
-    first.unmount();
-    // A fresh mount should be able to reclaim the just-released slot.
-    const second = renderHook(() => useContainerReveal());
-    const secondClass = second.result.current.getContainerProps().className;
-    expect(secondClass).toBe(firstClass);
-    second.unmount();
+    rerender({isEnabled: false});
+    expect(result.current.getContainerProps()).toEqual({});
+    expect(result.current.getContentRevealProps()).toEqual({});
+
+    rerender({isEnabled: true});
+    expect(result.current.getContainerProps().className).toBeTruthy();
+    expect(result.current.getContentRevealProps().className).toBeTruthy();
   });
 
   it('reveal and conceal map to different style blocks', () => {
@@ -80,37 +74,23 @@ describe('useContainerReveal', () => {
     expect(clipped).not.toBe(preserved);
   });
 
-  it('assigns distinct markers across a full pool of concurrent containers', () => {
-    function Probe({onClass}: {onClass: (c: string) => void}) {
-      const {getContainerProps} = useContainerReveal();
-      onClass(getContainerProps().className ?? '');
-      return null;
+  it('mounts a large flat list without a dev warning', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    function Row() {
+      const {getContainerProps, getContentRevealProps} = useContainerReveal();
+      return (
+        <div {...getContainerProps()}>
+          <span {...getContentRevealProps()}>actions</span>
+        </div>
+      );
     }
-    const classes: string[] = [];
-    const {unmount} = render(
+    render(
       <>
-        {Array.from({length: POOL_SIZE}, (_, i) => (
-          <Probe key={i} onClass={(c) => classes.push(c)} />
+        {Array.from({length: 500}, (_, i) => (
+          <Row key={i} />
         ))}
       </>,
     );
-    const unique = new Set(classes.filter(Boolean));
-    expect(unique.size).toBe(POOL_SIZE);
-    unmount();
-  });
-
-  it('survives repeated mount/unmount without leaking the pool', () => {
-    // Mount and unmount a full pool several times; each cycle must still hand
-    // out POOL_SIZE distinct markers, proving slots are released.
-    for (let cycle = 0; cycle < 3; cycle++) {
-      const hooks = Array.from({length: POOL_SIZE}, () =>
-        renderHook(() => useContainerReveal()),
-      );
-      const classes = hooks.map(
-        (h) => h.result.current.getContainerProps().className,
-      );
-      expect(new Set(classes).size).toBe(POOL_SIZE);
-      act(() => hooks.forEach((h) => h.unmount()));
-    }
+    expect(warn).not.toHaveBeenCalled();
   });
 });

package/src/hooks/useContainerReveal.ts

@@ -4,7 +4,7 @@
 
 /**
  * @file useContainerReveal.ts
- * @input Uses React, the generated marker pool, useDevWarning
+ * @input Uses the containerReveal styles
  * @output Exports useContainerReveal — a headless hover/focus reveal primitive
  * @position Core hook. Consumed by any component that reveals (or conceals)
  *   content when its container is hovered or focused — e.g. Thumbnail's remove
@@ -12,8 +12,13 @@
  *
  * Gives a container a scoped hover/focus-within trigger that reveals or
  * conceals content inside it, entirely in CSS (no hover state in JS, no
- * re-render on hover). The caller authors NO StyleX: the hook hands out a
- * marker + matching reveal styles from a pre-compiled pool.
+ * re-render on hover). The caller authors NO StyleX: the hook hands out the
+ * container style and the matching content styles.
+ *
+ * Scoping is by inheritance: the container publishes its reveal state as
+ * custom properties on itself and the content reads them, so a nested
+ * container shadows its ancestor's state for its own subtree. See
+ * containerReveal.stylex.ts.
  *
  * ACCESSIBILITY (WCAG 2.2 by construction):
  * - Revealed content is visually hidden at rest via position + opacity, so it
@@ -27,56 +32,19 @@
  *
  * SYNC: When modified, update:
  * - /packages/core/src/hooks/index.ts (export)
- * - containerReveal.pool.stylex.ts (if the slot shape changes)
+ * - containerReveal.stylex.ts (if the style blocks change)
  */
 
-import {useState, useEffect, type CSSProperties} from 'react';
+import {useMemo, type CSSProperties} from 'react';
 import * as stylex from '@stylexjs/stylex';
-import {POOL, POOL_SIZE, type RevealSlot} from './containerReveal.pool.stylex';
-import {useDevWarning} from './useDevWarning';
-
-// Module-level free-list. Each mounted, enabled useContainerReveal claims a
-// distinct pool slot so that any two CONCURRENTLY mounted containers — in
-// particular a nested container inside another's revealed content — get
-// different markers and cannot leak hover/focus into one another. Slots are
-// returned on unmount. Sibling containers that would only ever collide when
-// the pool is exhausted are harmless (a sibling is never an ancestor), so the
-// pool only needs to cover the number of concurrently mounted containers, not
-// instances over time.
-const claimed: boolean[] = new Array(POOL_SIZE).fill(false);
-
-interface Claim {
-  /** Pool index to use. */
-  index: number;
-  /** True when the pool was full and this claim fell back to a shared slot. */
-  isExhausted: boolean;
-}
-
-function claimSlot(): Claim {
-  for (let i = 0; i < POOL_SIZE; i++) {
-    if (!claimed[i]) {
-      claimed[i] = true;
-      return {index: i, isExhausted: false};
-    }
-  }
-  // Exhausted: fall back to slot 0. Safe for siblings (a sibling is never an
-  // ancestor); only nesting deeper than POOL_SIZE could reintroduce a leak.
-  // Surfaced via useDevWarning so the pool can be grown.
-  return {index: 0, isExhausted: true};
-}
-
-function releaseSlot(index: number, isExhausted: boolean): void {
-  // A fallback claim never owned the slot exclusively; leave it as-is.
-  if (!isExhausted) {
-    claimed[index] = false;
-  }
-}
+import {styles} from './containerReveal.stylex';
 
 export interface UseContainerRevealOptions {
   /**
-   * When false the hook is inert: no marker is applied and content getters
-   * return no styles, so content is always shown. Lets a component gate on its
-   * own prop (e.g. `revealOn === 'hover'`).
+   * When false the hook is inert: the container gets no styles and content
+   * getters return no styles, so content is always shown. Read on every
+   * render, so a component can flip it with its own prop (e.g.
+   * `revealOn === 'hover'`).
    * @default true
    */
   isEnabled?: boolean;
@@ -114,7 +82,7 @@ const EMPTY = Object.freeze({});
  * Scoped, CSS-only hover/focus reveal for content inside a container.
  *
  * @example
- * ```tsx
+ * ```
  * const {getContainerProps, getContentRevealProps} = useContainerReveal({
  *   isEnabled: revealOn === 'hover',
  * });
@@ -132,50 +100,27 @@ export function useContainerReveal(
 ): UseContainerRevealReturn {
   const {isEnabled = true} = options;
 
-  // Claim a slot for this container's lifetime. Assigned in the initializer
-  // (not the render body) and released on unmount so the free-list stays
-  // effect-scoped and StrictMode-safe.
-  const [claim] = useState<Claim | null>(() =>
-    isEnabled ? claimSlot() : null,
-  );
-
-  useEffect(() => {
-    if (claim == null) {
-      return;
+  return useMemo(() => {
+    if (!isEnabled) {
+      return {
+        getContainerProps: () => EMPTY,
+        getContentRevealProps: () => EMPTY,
+      };
     }
-    return () => releaseSlot(claim.index, claim.isExhausted);
-  }, [claim]);
-
-  useDevWarning(
-    'useContainerReveal',
-    `More than ${POOL_SIZE} reveal containers are mounted at once; nested ` +
-      `containers beyond the pool may share a marker. Add markers to ` +
-      `containerReveal.pool.stylex.ts and raise POOL_SIZE.`,
-    claim?.isExhausted ?? false,
-  );
-
-  if (claim == null) {
     return {
-      getContainerProps: () => EMPTY,
-      getContentRevealProps: () => EMPTY,
+      getContainerProps: () => stylex.props(styles.container),
+      getContentRevealProps: (contentOptions: ContentRevealOptions = {}) => {
+        const {isRevealInverted = false, isLayoutPreserved = false} =
+          contentOptions;
+        const style = isRevealInverted
+          ? isLayoutPreserved
+            ? styles.concealLayoutPreserved
+            : styles.conceal
+          : isLayoutPreserved
+            ? styles.revealLayoutPreserved
+            : styles.reveal;
+        return stylex.props(style);
+      },
     };
-  }
-
-  const slot: RevealSlot = POOL[claim.index];
-
-  return {
-    getContainerProps: () => stylex.props(slot.marker),
-    getContentRevealProps: (contentOptions: ContentRevealOptions = {}) => {
-      const {isRevealInverted = false, isLayoutPreserved = false} =
-        contentOptions;
-      const style = isRevealInverted
-        ? isLayoutPreserved
-          ? slot.concealLayoutPreserved
-          : slot.conceal
-        : isLayoutPreserved
-          ? slot.revealLayoutPreserved
-          : slot.reveal;
-      return stylex.props(style);
-    },
-  };
+  }, [isEnabled]);
 }

package/src/hooks/useImageMode.test.ts

@@ -105,7 +105,7 @@ describe('useImageMode', () => {
     stubCorsBlockedFetch();
     const {result} = renderHook(() =>
       useImageMode(
-        'https://lookaside.facebook.com/assets/astryx/moody-scene-vertical-2.png',
+        'https://cdn.example.com/photos/moody-scene-vertical-2.png',
         {fallback: null},
       ),
     );

package/src/hooks/useIndicatorFocusRing.tsx

@@ -0,0 +1,120 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useIndicatorFocusRing.tsx
+ * @input A ref to the element wrapping only the indicator
+ * @output Focus handlers that draw the standard ring on the indicator itself
+ * @position Used by controls whose focusable input is visually hidden
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/hooks/index.ts (exports)
+ *
+ * A checkbox or radio focuses a native `<input>` that is `opacity: 0`, so the
+ * visible focus indicator has to appear on the picture beside it — and that
+ * picture is a themeable indicator, which is what makes "who draws the ring"
+ * awkward:
+ *
+ * - Only the indicator's own element can shape the ring: `outline` follows
+ *   that element's `border-radius`. Draw it on a wrapper and the owner has to
+ *   hardcode a guess about whatever indicator it hosts (RadioListItem used to
+ *   carry `border-radius: 50%` for a circle it did not own).
+ * - But an indicator supplied by a theme is third-party code. If drawing the
+ *   ring is its job, a replacement that simply doesn't ships a control with no
+ *   visible focus (WCAG 2.4.7) — and that is the DEFAULT outcome: the sample
+ *   replacement in our own Storybook destructures `{state, size, isDisabled}`
+ *   and drops the rest, which is what a theme author plausibly writes. Nothing
+ *   can enforce otherwise; a component ignoring every prop is still assignable
+ *   to `IndicatorComponent`, and branding the return type does not work either
+ *   (JSX types every expression as `JSX.Element`).
+ *
+ * So the owner draws it, on the indicator's own element, imperatively at focus
+ * time. No cooperation is required and none can be forgotten.
+ *
+ * Two details that are load-bearing, both measured rather than assumed:
+ *
+ * 1. **Inline style, not a class.** React replaces `className` wholesale on
+ *    re-render, so an injected class disappears the moment the control changes
+ *    state — pressing Space on a focused checkbox lost the ring. React
+ *    reconciles `style` per property, so an `outline` set here survives.
+ * 2. **`:focus-visible`, not `:focus`.** The CSS this replaces got
+ *    keyboard-vs-pointer for free; an event handler has to ask. Checking the
+ *    element keeps the browser's heuristic, including `focus({focusVisible:
+ *    true})`, which a hand-rolled modality guess would miss.
+ *
+ * Imperative styling on an interaction event follows `useTableSelection`,
+ * which sets row-selection styles the same way.
+ */
+
+import {useCallback, useMemo} from 'react';
+import type {FocusEvent, RefObject} from 'react';
+import {
+  FOCUS_OUTLINE_PARTS,
+  FOCUS_OUTLINE_PARTS_NONE,
+} from '../utils/focusOutline.stylex';
+
+export interface UseIndicatorFocusRingReturn {
+  /** Spread onto the element that owns the focusable input. */
+  focusProps: {
+    onFocus: (event: FocusEvent<HTMLElement>) => void;
+    onBlur: () => void;
+  };
+}
+
+/**
+ * Draw the standard focus ring on the indicator inside `containerRef`, shaped
+ * by whatever that indicator actually is.
+ *
+ * @param containerRef - Wraps ONLY the indicator, so its single element child
+ *   is unambiguously the thing to ring, whatever a theme renders there.
+ * @param isDisabled - Skip the ring; a disabled control is not focusable.
+ *
+ * @example
+ * ```
+ * const indicatorRef = useRef<HTMLSpanElement>(null);
+ * const {focusProps} = useIndicatorFocusRing(indicatorRef, isDisabled);
+ * <div {...focusProps}>
+ *   <input type="checkbox" />
+ *   <span ref={indicatorRef}><Indicator state="checked" /></span>
+ * </div>
+ * ```
+ */
+export function useIndicatorFocusRing(
+  containerRef: RefObject<HTMLElement | null>,
+  isDisabled = false,
+): UseIndicatorFocusRingReturn {
+  const paint = useCallback(
+    (on: boolean) => {
+      // `firstElementChild`, not a search: the container holds the indicator
+      // and nothing else, so there is no ambiguity — and no way for a later
+      // sibling to quietly become the target.
+      const indicator = containerRef.current?.firstElementChild;
+      if (indicator instanceof HTMLElement) {
+        Object.assign(
+          indicator.style,
+          on ? FOCUS_OUTLINE_PARTS : FOCUS_OUTLINE_PARTS_NONE,
+        );
+      }
+    },
+    [containerRef],
+  );
+
+  const onFocus = useCallback(
+    (event: FocusEvent<HTMLElement>) => {
+      if (isDisabled) {
+        return;
+      }
+      const target = event.target;
+      if (target instanceof HTMLElement && !target.matches(':focus-visible')) {
+        return;
+      }
+      paint(true);
+    },
+    [isDisabled, paint],
+  );
+
+  const onBlur = useCallback(() => paint(false), [paint]);
+
+  return useMemo(() => ({focusProps: {onFocus, onBlur}}), [onFocus, onBlur]);
+}

package/src/hooks/useLongPress.test.tsx

@@ -81,6 +81,24 @@ describe('useLongPress', () => {
     expect(onLongPress).not.toHaveBeenCalled();
   });
 
+  it('cancels when a second finger touches down mid-press', () => {
+    const onLongPress = vi.fn();
+    const {result} = renderHook(() => useLongPress({onLongPress}));
+
+    act(() => {
+      result.current.onTouchStart(touchEvent([{clientX: 0, clientY: 0}]));
+      // A second finger joins before the press fires (e.g. pinch-to-zoom).
+      result.current.onTouchStart(
+        touchEvent([
+          {clientX: 0, clientY: 0},
+          {clientX: 50, clientY: 50},
+        ]),
+      );
+      vi.advanceTimersByTime(500);
+    });
+    expect(onLongPress).not.toHaveBeenCalled();
+  });
+
   it('cancels when the finger moves past the threshold', () => {
     const onLongPress = vi.fn();
     const {result} = renderHook(() => useLongPress({onLongPress}));

package/src/hooks/useLongPress.ts

@@ -70,7 +70,12 @@ export function useLongPress(
 
   const onTouchStart = useCallback(
     (e: React.TouchEvent) => {
-      if (disabled || e.touches.length !== 1) {
+      if (disabled) {
+        return;
+      }
+      if (e.touches.length !== 1) {
+        // Multi-touch cancels any pending long-press.
+        clear();
         return;
       }
       const touch = e.touches[0];
@@ -92,7 +97,12 @@ export function useLongPress(
   const onTouchMove = useCallback(
     (e: React.TouchEvent) => {
       const start = startRef.current;
-      if (start == null || e.touches.length !== 1) {
+      if (start == null) {
+        return;
+      }
+      if (e.touches.length !== 1) {
+        // Multi-touch cancels the pending long-press.
+        clear();
         return;
       }
       const touch = e.touches[0];

package/src/hooks/useScrollLock.test.ts

@@ -0,0 +1,72 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file useScrollLock.test.ts
+ * @input Uses vitest, @testing-library/react, useScrollLock hook
+ * @output Unit tests for single and concurrent useScrollLock instances
+ * @position Testing; validates useScrollLock.ts implementation
+ *
+ * SYNC: When useScrollLock.ts changes, update tests to match new behavior
+ */
+
+import {afterEach, describe, expect, it, vi} from 'vitest';
+import {cleanup, renderHook} from '@testing-library/react';
+import {useScrollLock} from './useScrollLock';
+
+describe('useScrollLock', () => {
+  afterEach(() => {
+    cleanup();
+    document.body.style.cssText = '';
+    vi.restoreAllMocks();
+  });
+
+  it('restores body styles and scroll position after a single lock is released', () => {
+    document.body.style.overflow = 'auto';
+    document.body.style.position = 'relative';
+
+    vi.spyOn(window, 'scrollX', 'get').mockReturnValue(120);
+    vi.spyOn(window, 'scrollY', 'get').mockReturnValue(480);
+    vi.spyOn(window, 'scrollTo').mockImplementation(() => {});
+
+    const lock = renderHook(() => useScrollLock(true));
+
+    expect(document.body.style.overflow).toBe('hidden');
+    expect(document.body.style.position).toBe('fixed');
+
+    lock.unmount();
+
+    expect(document.body.style.overflow).toBe('auto');
+    expect(document.body.style.position).toBe('relative');
+    expect(window.scrollTo).toHaveBeenCalledWith(120, 480);
+  });
+
+  it('stays locked while a second overlay is still open, even if the first closes out of order', () => {
+    vi.spyOn(window, 'scrollTo').mockImplementation(() => {});
+
+    const first = renderHook(() => useScrollLock(true));
+    const second = renderHook(() => useScrollLock(true));
+
+    first.unmount();
+
+    expect(document.body.style.position).toBe('fixed');
+    expect(document.body.style.overflow).toBe('hidden');
+
+    second.unmount();
+  });
+
+  it('fully restores the body once every overlay has closed, regardless of close order', () => {
+    vi.spyOn(window, 'scrollTo').mockImplementation(() => {});
+
+    const first = renderHook(() => useScrollLock(true));
+    const second = renderHook(() => useScrollLock(true));
+
+    first.unmount();
+    second.unmount();
+
+    expect(document.body.style.position).toBe('');
+    expect(document.body.style.overflow).toBe('');
+    expect(document.body.style.top).toBe('');
+    expect(document.body.style.left).toBe('');
+    expect(document.body.style.right).toBe('');
+  });
+});

package/src/hooks/useScrollLock.ts

@@ -17,6 +17,19 @@
 
 import {useEffect} from 'react';
 
+interface ScrollLockSnapshot {
+  scrollX: number;
+  scrollY: number;
+  overflow: string;
+  position: string;
+  top: string;
+  left: string;
+  right: string;
+}
+
+let lockCount = 0;
+let originalBodyState: ScrollLockSnapshot | null = null;
+
 /**
  * Locks body scroll when `isLocked` is true.
  *
@@ -36,28 +49,47 @@ export function useScrollLock(isLocked: boolean): void {
       return;
     }
 
-    const scrollX = window.scrollX;
-    const scrollY = window.scrollY;
     const {body} = document;
-    const prevOverflow = body.style.overflow;
-    const prevPosition = body.style.position;
-    const prevTop = body.style.top;
-    const prevLeft = body.style.left;
-    const prevRight = body.style.right;
-
-    body.style.overflow = 'hidden';
-    body.style.position = 'fixed';
-    body.style.top = `-${scrollY}px`;
-    body.style.left = '0';
-    body.style.right = '0';
+
+    if (lockCount === 0) {
+      const scrollX = window.scrollX;
+      const scrollY = window.scrollY;
+
+      originalBodyState = {
+        scrollX,
+        scrollY,
+        overflow: body.style.overflow,
+        position: body.style.position,
+        top: body.style.top,
+        left: body.style.left,
+        right: body.style.right,
+      };
+
+      body.style.overflow = 'hidden';
+      body.style.position = 'fixed';
+      body.style.top = `-${scrollY}px`;
+      body.style.left = '0';
+      body.style.right = '0';
+    }
+
+    lockCount += 1;
 
     return () => {
-      body.style.overflow = prevOverflow;
-      body.style.position = prevPosition;
-      body.style.top = prevTop;
-      body.style.left = prevLeft;
-      body.style.right = prevRight;
-      window.scrollTo(scrollX, scrollY);
+      lockCount -= 1;
+
+      if (lockCount !== 0 || originalBodyState == null) {
+        return;
+      }
+
+      const state = originalBodyState;
+      originalBodyState = null;
+
+      body.style.overflow = state.overflow;
+      body.style.position = state.position;
+      body.style.top = state.top;
+      body.style.left = state.left;
+      body.style.right = state.right;
+      window.scrollTo(state.scrollX, state.scrollY);
     };
   }, [isLocked]);
 }