@astryxdesign/core 0.4.7 → 0.5.0-canary.32a62fd

package/src/Layer/useLayerDismissal.test.tsx

@@ -0,0 +1,469 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file useLayerDismissal.test.tsx
+ * @input Uses @testing-library/react, vitest
+ * @output Tests for the shared layer dismissal stack
+ * @position Colocated tests for useLayerDismissal + layerStack
+ *
+ * Every case here is "one Escape press, which layers reacted?" — the single
+ * question the stack exists to answer.
+ */
+
+import {render, fireEvent} from '@testing-library/react';
+import {describe, expect, it, vi, afterEach} from 'vitest';
+import {StrictMode, useRef} from 'react';
+
+import {LayerDepthProvider} from './LayerDepthContext';
+import {useLayerDismissal} from './useLayerDismissal';
+import {resetLayerStackForTests} from './layerStack';
+import type {LayerEscapeBehavior} from './layerStack';
+
+afterEach(() => {
+  resetLayerStackForTests();
+});
+
+/** A layer that registers itself and renders its children one level deeper. */
+function Layer({
+  onDismiss,
+  behavior = 'close',
+  isEnabled = true,
+  isActive = true,
+  isPresent,
+  children,
+}: {
+  onDismiss: () => void;
+  behavior?: LayerEscapeBehavior;
+  isEnabled?: boolean;
+  isActive?: boolean;
+  isPresent?: () => boolean;
+  children?: React.ReactNode;
+}) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  useLayerDismissal({
+    isActive,
+    onDismiss,
+    escapeBehavior: behavior,
+    isEnabled,
+    isPresent,
+    getContainer: () => containerRef.current,
+  });
+  return (
+    <div ref={containerRef}>
+      <LayerDepthProvider>{children}</LayerDepthProvider>
+    </div>
+  );
+}
+
+/** A layer that reports no depth — like a bare focus trap, which renders nothing. */
+function FlatLayer({
+  onDismiss,
+  children,
+}: {
+  onDismiss: () => void;
+  children?: React.ReactNode;
+}) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  useLayerDismissal({
+    isActive: true,
+    onDismiss,
+    getContainer: () => containerRef.current,
+  });
+  return <div ref={containerRef}>{children}</div>;
+}
+
+const pressEscape = () => fireEvent.keyDown(document, {key: 'Escape'});
+
+describe('useLayerDismissal', () => {
+  it('dismisses only the top-most layer when both open in the same commit', () => {
+    // The regression: an inner and outer layer that mount together. React runs
+    // child effects first, so registration order reports the inner layer as the
+    // OLDER one — nesting, not order, has to decide.
+    const outer = vi.fn();
+    const inner = vi.fn();
+
+    render(
+      <Layer onDismiss={outer}>
+        <Layer onDismiss={inner} />
+      </Layer>,
+    );
+
+    pressEscape();
+    expect(inner).toHaveBeenCalledTimes(1);
+    expect(outer).not.toHaveBeenCalled();
+  });
+
+  it('falls through to the outer layer once the inner one closes', () => {
+    const outer = vi.fn();
+    const inner = vi.fn();
+    const {rerender} = render(
+      <Layer onDismiss={outer}>
+        <Layer onDismiss={inner} />
+      </Layer>,
+    );
+    rerender(<Layer onDismiss={outer} />);
+
+    pressEscape();
+    expect(outer).toHaveBeenCalledTimes(1);
+    expect(inner).not.toHaveBeenCalled();
+  });
+
+  it('dismisses the later of two unrelated layers', () => {
+    const first = vi.fn();
+    const second = vi.fn();
+    const {rerender} = render(<Layer onDismiss={first} />);
+    rerender(
+      <>
+        <Layer onDismiss={first} />
+        <Layer onDismiss={second} />
+      </>,
+    );
+
+    pressEscape();
+    expect(second).toHaveBeenCalledTimes(1);
+    expect(first).not.toHaveBeenCalled();
+  });
+
+  it('resolves nesting by DOM containment when the tree reports equal depth', () => {
+    // A bare focus trap renders nothing, so it cannot push a depth provider.
+    // Containment is the only nesting signal those layers have.
+    const outer = vi.fn();
+    const inner = vi.fn();
+    render(
+      <FlatLayer onDismiss={outer}>
+        <FlatLayer onDismiss={inner} />
+      </FlatLayer>,
+    );
+
+    pressEscape();
+    expect(inner).toHaveBeenCalledTimes(1);
+    expect(outer).not.toHaveBeenCalled();
+  });
+
+  describe('escapeBehavior', () => {
+    it("'close' consumes the press, so one Escape affects exactly one layer", () => {
+      // A hover tip inside a modal: the tip is on top, so it takes the press
+      // and the modal stays open. A second Escape closes the modal.
+      const modal = vi.fn();
+      const tip = vi.fn();
+      render(
+        <Layer onDismiss={modal}>
+          <Layer onDismiss={tip} />
+        </Layer>,
+      );
+
+      pressEscape();
+      expect(tip).toHaveBeenCalledTimes(1);
+      expect(modal).not.toHaveBeenCalled();
+    });
+
+    it("'block' consumes the press without dismissing anything", () => {
+      const host = vi.fn();
+      const required = vi.fn();
+      render(
+        <Layer onDismiss={host}>
+          <Layer onDismiss={required} behavior="block" />
+        </Layer>,
+      );
+
+      pressEscape();
+      expect(required).not.toHaveBeenCalled();
+      expect(host).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('registration order', () => {
+    /** Two unrelated same-depth layers; the older one's behavior is a prop. */
+    function Siblings({
+      olderBehavior,
+      onOlderDismiss,
+      onNewerDismiss,
+    }: {
+      olderBehavior: LayerEscapeBehavior;
+      onOlderDismiss: () => void;
+      onNewerDismiss: () => void;
+    }) {
+      return (
+        <>
+          <Layer onDismiss={onOlderDismiss} behavior={olderBehavior} />
+          <Layer onDismiss={onNewerDismiss} />
+        </>
+      );
+    }
+
+    it('keeps a layer below the ones that opened after it when its escapeBehavior changes', () => {
+      // A Dialog whose `purpose` flips from required to info while it is open
+      // re-registers with the stack. Re-registration must not reorder it above
+      // a layer opened on top of it.
+      const older = vi.fn();
+      const newer = vi.fn();
+      const {rerender} = render(
+        <Siblings
+          olderBehavior="block"
+          onOlderDismiss={older}
+          onNewerDismiss={newer}
+        />,
+      );
+      rerender(
+        <Siblings
+          olderBehavior="close"
+          onOlderDismiss={older}
+          onNewerDismiss={newer}
+        />,
+      );
+
+      pressEscape();
+      expect(newer).toHaveBeenCalledTimes(1);
+      expect(older).not.toHaveBeenCalled();
+    });
+
+    it('does not let a re-registered layer swallow a press meant for the layer above it', () => {
+      // The same flip the other way: info to required. A `block` layer that
+      // jumped the queue would consume the press and nothing would close.
+      const older = vi.fn();
+      const newer = vi.fn();
+      const {rerender} = render(
+        <Siblings
+          olderBehavior="close"
+          onOlderDismiss={older}
+          onNewerDismiss={newer}
+        />,
+      );
+      rerender(
+        <Siblings
+          olderBehavior="block"
+          onOlderDismiss={older}
+          onNewerDismiss={newer}
+        />,
+      );
+
+      pressEscape();
+      expect(newer).toHaveBeenCalledTimes(1);
+      expect(older).not.toHaveBeenCalled();
+    });
+
+    it('keeps ordering under StrictMode, which mounts every effect twice', () => {
+      const first = vi.fn();
+      const second = vi.fn();
+      render(
+        <StrictMode>
+          <Layer onDismiss={first} />
+          <Layer onDismiss={second} />
+        </StrictMode>,
+      );
+
+      pressEscape();
+      expect(second).toHaveBeenCalledTimes(1);
+      expect(first).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('presence', () => {
+    it('skips a registered layer that is not on screen', () => {
+      // Hover layers stay registered for their lifetime because their open
+      // state lags the DOM. An absent one must not claim the press — that is
+      // exactly the bug where a HoverCard trigger ate Escapes while idle.
+      const below = vi.fn();
+      const absent = vi.fn();
+      render(
+        <Layer onDismiss={below}>
+          <Layer onDismiss={absent} isPresent={() => false} />
+        </Layer>,
+      );
+
+      pressEscape();
+      expect(absent).not.toHaveBeenCalled();
+      expect(below).toHaveBeenCalledTimes(1);
+    });
+
+    it('lets a present layer claim the press over the one beneath', () => {
+      const below = vi.fn();
+      const present = vi.fn();
+      render(
+        <Layer onDismiss={below}>
+          <Layer onDismiss={present} isPresent={() => true} />
+        </Layer>,
+      );
+
+      pressEscape();
+      expect(present).toHaveBeenCalledTimes(1);
+      expect(below).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('opting out', () => {
+    it('skips a disabled layer entirely, so the press reaches the one below', () => {
+      const below = vi.fn();
+      const optedOut = vi.fn();
+      render(
+        <Layer onDismiss={below}>
+          <Layer onDismiss={optedOut} isEnabled={false} />
+        </Layer>,
+      );
+
+      pressEscape();
+      expect(optedOut).not.toHaveBeenCalled();
+      expect(below).toHaveBeenCalledTimes(1);
+    });
+
+    it('does not register an inactive layer', () => {
+      const onDismiss = vi.fn();
+      render(<Layer onDismiss={onDismiss} isActive={false} />);
+
+      pressEscape();
+      expect(onDismiss).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('deferring to content', () => {
+    it('stands down when content already handled the press', () => {
+      // preventDefault from inside the layer — an editor claiming Escape for
+      // its own find widget, for instance.
+      const onDismiss = vi.fn();
+      render(
+        <Layer onDismiss={onDismiss}>
+          <button
+            type="button"
+            data-testid="editor"
+            onKeyDown={e => {
+              if (e.key === 'Escape') {
+                e.preventDefault();
+              }
+            }}
+          />
+        </Layer>,
+      );
+
+      fireEvent.keyDown(document.querySelector('[data-testid="editor"]')!, {
+        key: 'Escape',
+      });
+      expect(onDismiss).not.toHaveBeenCalled();
+    });
+
+    it('ignores Escape that is cancelling an IME composition', () => {
+      const onDismiss = vi.fn();
+      render(<Layer onDismiss={onDismiss} />);
+
+      fireEvent.keyDown(document, {key: 'Escape', isComposing: true});
+      expect(onDismiss).not.toHaveBeenCalled();
+
+      fireEvent.keyDown(document, {key: 'Escape', keyCode: 229});
+      expect(onDismiss).not.toHaveBeenCalled();
+
+      pressEscape();
+      expect(onDismiss).toHaveBeenCalledTimes(1);
+    });
+
+    it('claims the composing Escape so the browser raises no close request', () => {
+      // Not dismissing is only half of it. An unclaimed Escape lets the browser
+      // raise its own close request, which reaches the layer's `cancel` handler
+      // and dismisses it on the same keypress — so the guard has to swallow the
+      // press, not merely skip the dismissal.
+      render(<Layer onDismiss={vi.fn()} />);
+      const event = new KeyboardEvent('keydown', {
+        key: 'Escape',
+        bubbles: true,
+        cancelable: true,
+      });
+      Object.defineProperty(event, 'isComposing', {value: true});
+
+      document.dispatchEvent(event);
+      expect(event.defaultPrevented).toBe(true);
+    });
+
+    it('leaves a composing Escape alone when no layer is on screen', () => {
+      // With nothing to protect the press is not ours to take: an idle hover
+      // layer in the tree must not suppress the page's own close watcher.
+      render(<Layer onDismiss={vi.fn()} isPresent={() => false} />);
+      const event = new KeyboardEvent('keydown', {
+        key: 'Escape',
+        bubbles: true,
+        cancelable: true,
+      });
+      Object.defineProperty(event, 'isComposing', {value: true});
+
+      document.dispatchEvent(event);
+      expect(event.defaultPrevented).toBe(false);
+    });
+  });
+
+  describe('close requests the browser starts itself', () => {
+    // The Android back gesture and the platform close watcher arrive as a
+    // `cancel` with no keydown to read, so the keydown guard cannot see them.
+    function CloseRequestLayer({onAsk}: {onAsk: (answer: boolean) => void}) {
+      const {shouldDismissOnCloseRequest} = useLayerDismissal({
+        isActive: true,
+        onDismiss: () => {},
+      });
+      return (
+        <>
+          <input aria-label="composing field" />
+          <button
+            type="button"
+            onClick={() => onAsk(shouldDismissOnCloseRequest())}>
+            ask
+          </button>
+        </>
+      );
+    }
+
+    const ask = (onAsk: ReturnType<typeof vi.fn>): boolean => {
+      fireEvent.click(document.querySelector('button')!);
+      return Boolean(onAsk.mock.lastCall?.[0]);
+    };
+
+    it('declines while an IME composition is running, and again once it ends', () => {
+      const onAsk = vi.fn();
+      render(<CloseRequestLayer onAsk={onAsk} />);
+      const field = document.querySelector('input')!;
+
+      expect(ask(onAsk)).toBe(true);
+
+      fireEvent.compositionStart(field);
+      expect(ask(onAsk)).toBe(false);
+
+      fireEvent.compositionEnd(field);
+      expect(ask(onAsk)).toBe(true);
+    });
+
+    it('stops declining when focus leaves a field mid-composition', () => {
+      // A compositionend the stack never sees would otherwise leave the flag
+      // stuck on, and every later back gesture would be swallowed.
+      const onAsk = vi.fn();
+      render(<CloseRequestLayer onAsk={onAsk} />);
+      const field = document.querySelector('input')!;
+
+      fireEvent.compositionStart(field);
+      expect(ask(onAsk)).toBe(false);
+
+      fireEvent.blur(field);
+      expect(ask(onAsk)).toBe(true);
+    });
+  });
+
+  it('leaves the event alone when no layer is open', () => {
+    // Nothing registered: the browser keeps its own Escape behavior (exiting
+    // fullscreen, closing a native picker).
+    render(<div />);
+    const event = new KeyboardEvent('keydown', {
+      key: 'Escape',
+      bubbles: true,
+      cancelable: true,
+    });
+    document.dispatchEvent(event);
+    expect(event.defaultPrevented).toBe(false);
+  });
+
+  it('claims the press it handles so the browser does not act too', () => {
+    // preventDefault is what stops the native close-watcher dismissing a second
+    // layer behind the stack's back.
+    render(<Layer onDismiss={vi.fn()} />);
+    const event = new KeyboardEvent('keydown', {
+      key: 'Escape',
+      bubbles: true,
+      cancelable: true,
+    });
+    document.dispatchEvent(event);
+    expect(event.defaultPrevented).toBe(true);
+  });
+});

package/src/Layer/useLayerDismissal.ts

@@ -0,0 +1,173 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useLayerDismissal.ts
+ * @input Uses React hooks, the layer stack, and LayerDepthContext
+ * @output Exports useLayerDismissal + its option/return types
+ * @position The API overlays use to join the shared dismissal stack. Wraps
+ *   layerStack (registration + the single Escape listener) and reads nesting
+ *   depth from LayerDepthContext.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/Layer/index.ts
+ * - /packages/core/src/Layer/useLayerDismissal.test.tsx
+ * - /packages/core/src/Layer/layerStack.ts
+ */
+
+import {useCallback, useEffect, useRef} from 'react';
+
+import {useLayerDepth} from './LayerDepthContext';
+import {
+  isTextComposing,
+  isTopmostLayer,
+  registerLayer,
+  type LayerEscapeBehavior,
+} from './layerStack';
+
+export type {LayerEscapeBehavior};
+
+export interface UseLayerDismissalOptions {
+  /**
+   * Whether this layer is participating right now. Usually the layer's open
+   * state. A layer whose open state lags the DOM should pass `true` for its
+   * lifetime and answer `isPresent` from the DOM instead.
+   */
+  isActive: boolean;
+  /**
+   * Dismiss this layer. Called by the stack when this layer is the one that
+   * should respond to an Escape press. Not called for `escapeBehavior: 'block'`.
+   */
+  onDismiss: () => void;
+  /**
+   * What this layer does with an Escape press that reaches it.
+   * @default 'close'
+   */
+  escapeBehavior?: LayerEscapeBehavior;
+  /**
+   * This layer's container element, read lazily. Optional: supply it when the
+   * layer cannot wrap its content in `LayerDepthProvider` (a bare focus trap
+   * renders nothing), so nesting can still be recovered from the DOM.
+   */
+  getContainer?: () => HTMLElement | null;
+  /**
+   * Whether the layer is really on screen, asked at press time. Supply it when
+   * `isActive` is `true` for the layer's lifetime because its open state lags
+   * the DOM by a frame; the stack skips layers that answer `false`.
+   */
+  isPresent?: () => boolean;
+  /**
+   * Whether this layer takes part in the shared stack at all. When `false` the
+   * layer is invisible to dismissal: a press flows past it to the layer below,
+   * exactly as if it were not open.
+   *
+   * Deliberately separate from `escapeBehavior: 'block'` — `'block'` is a layer
+   * that is present and swallows the press; this is a layer that is not there
+   * at all. One case uses it: `Dialog`'s inline rendering mode, where content
+   * sits in normal flow with nothing layered over anything.
+   *
+   * A controlled layer is NOT one of these. It stays registered and takes the
+   * press like any other, answering it by calling the consumer's change
+   * handler; whether it then closes is the consumer's decision.
+   *
+   * Layers that are never Escape-dismissible (toasts) should simply not call
+   * this hook.
+   *
+   * @default true
+   */
+  isEnabled?: boolean;
+}
+
+export interface UseLayerDismissalReturn {
+  /**
+   * Whether a close request the browser started on its own — a `<dialog>`'s
+   * `cancel`, the Android back gesture, the platform close watcher — should
+   * dismiss this layer. As well as the top-most rule the stack applies to an
+   * Escape press, it declines a request that arrives while an IME composition
+   * is running, which no `cancel` handler can tell on its own because the
+   * event carries no composition state.
+   */
+  shouldDismissOnCloseRequest: () => boolean;
+}
+
+/**
+ * Join the shared layer dismissal stack for as long as this layer is active.
+ *
+ * The layer does NOT attach a key listener — the stack owns one listener and
+ * routes each Escape press to the top-most REGISTERED layer, so one press
+ * dismisses exactly one of them. Dialog (and what is built on it), Popover and
+ * the menus built on it, Tooltip, HoverCard, Lightbox and MobileNav register
+ * today; `BottomSheetSwitcher` registers through its focus trap when modal and
+ * still handles its own press when not.
+ *
+ * `BottomSheet`, `CommandPalette`, `ContextMenu`, `DropdownMenuSubMenu`,
+ * `PowerSearchEditPopover` and lab's `Drawer` still run their own Escape
+ * listener. They stay safe next to the stack only because each claims the press
+ * at element level, and the stack stands down on an already-`defaultPrevented`
+ * press — but a registered layer opened INSIDE one of them does not get the
+ * press: the host takes it and closes instead. Migrating them is the fix.
+ *
+ * Wrap the layer's own content in `LayerDepthProvider` so anything opened from
+ * inside it registers as nested.
+ *
+ * @example
+ * ```tsx
+ * useLayerDismissal({
+ *   isActive: isOpen,
+ *   onDismiss: () => onOpenChange(false),
+ * });
+ * ```
+ */
+export function useLayerDismissal(
+  options: UseLayerDismissalOptions,
+): UseLayerDismissalReturn {
+  const {
+    isActive,
+    onDismiss,
+    escapeBehavior = 'close',
+    getContainer,
+    isPresent,
+    isEnabled = true,
+  } = options;
+
+  const depth = useLayerDepth();
+
+  // Identity for this layer's stack entry, stable across re-registration.
+  const tokenRef = useRef<object>({});
+
+  // The stack calls these during an event, outside React's render, so they must
+  // reach the latest closures rather than the ones captured at registration.
+  const onDismissRef = useRef(onDismiss);
+  const getContainerRef = useRef(getContainer);
+  const isPresentRef = useRef(isPresent);
+  useEffect(() => {
+    onDismissRef.current = onDismiss;
+    getContainerRef.current = getContainer;
+    isPresentRef.current = isPresent;
+  });
+
+  const isRegistered = isActive && isEnabled;
+
+  useEffect(() => {
+    if (!isRegistered) {
+      return;
+    }
+    return registerLayer({
+      token: tokenRef.current,
+      depth,
+      behavior: escapeBehavior,
+      getContainer: () => getContainerRef.current?.() ?? null,
+      isPresent: () => isPresentRef.current?.() ?? true,
+      dismiss: () => onDismissRef.current(),
+    });
+  }, [isRegistered, depth, escapeBehavior]);
+
+  const shouldDismissOnCloseRequest = useCallback(
+    () =>
+      isRegistered && !isTextComposing() && isTopmostLayer(tokenRef.current),
+    [isRegistered],
+  );
+
+  return {shouldDismissOnCloseRequest};
+}

package/src/Layout/Layout.doc.mjs

@@ -95,9 +95,9 @@ export const docs = {
     },
     {
       name: 'contentWidth',
-      type: 'number | string',
+      type: 'SizeValue',
       description:
-        'Maximum width of the content within each slot (header, content, footer, panels), centered when narrower than the available space. Dividers stay full-bleed. Numbers are pixels, strings are used as-is (e.g. `60ch`). Common page widths: 640 for forms, settings, and text-focused pages; 960 for content pages and wider layouts.',
+        'Maximum width of the content within each slot (header, content, footer, panels), centered when narrower than the available space. Dividers stay full-bleed. Numbers are treated as pixels, strings are used as-is (e.g. `60ch`). Common page widths: 640 for forms, settings, and text-focused pages; 960 for content pages and wider layouts.',
     },
     {
       name: 'padding',

package/src/Lightbox/Lightbox.doc.mjs

@@ -47,6 +47,18 @@ export const docs = {
       description: 'Enable zoom on double-click, or Enter/Space/+/- via keyboard (images only). When zoomed, drag or use arrow keys to pan.',
       default: 'false',
     },
+    {
+      name: 'defaultIndex',
+      type: 'number',
+      description: 'Initial image index in gallery mode for uncontrolled usage.',
+      default: '0',
+    },
+    {
+      name: 'hasAutoPlay',
+      type: 'boolean',
+      description: 'Automatically start video playback when a video media item is shown.',
+      default: 'false',
+    },
     {
       name: 'xstyle',
       type: 'StyleXStyles',