@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/src/Layer/useLayerDismissal.test.tsx

@@ -10,9 +10,10 @@
  * question the stack exists to answer.
  */
 
-import {render, fireEvent} from '@testing-library/react';
-import {describe, expect, it, vi, afterEach} from 'vitest';
+import {render, fireEvent, cleanup} from '@testing-library/react';
+import {describe, expect, it, vi, afterEach, beforeEach} from 'vitest';
 import {StrictMode, useRef} from 'react';
+import {createPortal} from 'react-dom';
 
 import {LayerDepthProvider} from './LayerDepthContext';
 import {useLayerDismissal} from './useLayerDismissal';
@@ -467,6 +468,88 @@ describe('useLayerDismissal', () => {
       fireEvent.blur(field);
       expect(ask(onAsk)).toBe(true);
     });
+
+    it('answers against the top-most layer of its own document', () => {
+      // A layer that opened later in a second document is on top there, not
+      // here: it cannot make a close request in this document decline.
+      const onAsk = vi.fn();
+      const frame = document.createElement('iframe');
+      document.body.appendChild(frame);
+      try {
+        render(<CloseRequestLayer onAsk={onAsk} />);
+        render(
+          createPortal(
+            <Layer onDismiss={vi.fn()} />,
+            frame.contentDocument!.body,
+          ),
+        );
+
+        expect(ask(onAsk)).toBe(true);
+      } finally {
+        cleanup();
+        frame.remove();
+      }
+    });
+  });
+
+  describe('in a second document', () => {
+    // A same-origin iframe stands in for any second document an app renders
+    // layers into through a portal, Document Picture-in-Picture included. A
+    // key press reaches only the document it happened in.
+    let frame: HTMLIFrameElement;
+    let secondDocument: Document;
+
+    beforeEach(() => {
+      frame = document.createElement('iframe');
+      document.body.appendChild(frame);
+      secondDocument = frame.contentDocument!;
+    });
+
+    afterEach(() => {
+      // Unmount before the frame goes, or React removes nodes from a
+      // document that no longer exists.
+      cleanup();
+      frame.remove();
+    });
+
+    it('dismisses the top-most layer of the document the press arrived in', () => {
+      const here = vi.fn();
+      const there = vi.fn();
+      render(<Layer onDismiss={here} />);
+      // Registered later, so one order across both documents would put it on
+      // top of the layer here as well.
+      render(createPortal(<Layer onDismiss={there} />, secondDocument.body));
+
+      fireEvent.keyDown(secondDocument, {key: 'Escape'});
+      expect(there).toHaveBeenCalledTimes(1);
+      expect(here).not.toHaveBeenCalled();
+
+      pressEscape();
+      expect(here).toHaveBeenCalledTimes(1);
+      expect(there).toHaveBeenCalledTimes(1);
+    });
+
+    it('listens in a document once, and only while it holds a layer', () => {
+      const added = vi.spyOn(secondDocument, 'addEventListener');
+      const removed = vi.spyOn(secondDocument, 'removeEventListener');
+      const keydownCalls = (spy: typeof added) =>
+        spy.mock.calls.filter(([type]) => type === 'keydown').length;
+
+      const {unmount} = render(
+        createPortal(
+          <>
+            <Layer onDismiss={vi.fn()} />
+            <Layer onDismiss={vi.fn()} />
+          </>,
+          secondDocument.body,
+        ),
+      );
+      expect(keydownCalls(added)).toBe(1);
+      expect(keydownCalls(removed)).toBe(0);
+
+      unmount();
+      expect(keydownCalls(removed)).toBe(1);
+    });
   });
 
   it('leaves the event alone when no layer is open', () => {

package/src/Layer/useLayerDismissal.ts

@@ -7,8 +7,8 @@
  * @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.
+ *   layerStack (registration + the Escape listener on each layer's document)
+ *   and reads nesting depth from LayerDepthContext.
  *
  * SYNC: When modified, update:
  * - /packages/core/src/Layer/index.ts
@@ -48,7 +48,10 @@ export interface UseLayerDismissalOptions {
   /**
    * 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.
+   * renders nothing), so nesting can still be recovered from the DOM. Its
+   * document is also the layer's: the stack listens there and ranks the layer
+   * among that document's layers. Without it, the layer belongs to the global
+   * `document`.
    */
   getContainer?: () => HTMLElement | null;
   /**
@@ -94,12 +97,12 @@ export interface UseLayerDismissalReturn {
 /**
  * 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, including
- * CommandPalette), Popover and the menus built on it, ContextMenu, Tooltip,
- * HoverCard, Lightbox, MobileNav, BottomSheet, BottomSheetSwitcher and
- * `Drawer` register today.
+ * The layer does NOT attach a key listener — the stack owns one listener per
+ * document and routes each Escape press to the top-most REGISTERED layer of
+ * the document it arrived in, so one press dismisses exactly one of them.
+ * Dialog (and what is built on it, including CommandPalette), Popover and the
+ * menus built on it, ContextMenu, Tooltip, HoverCard, Lightbox, MobileNav,
+ * BottomSheet, BottomSheetSwitcher and `Drawer` register today.
  *
  * `DropdownMenuSubMenu` and `PowerSearchEditPopover` still run their own Escape
  * listeners. They stay safe next to the stack only because each claims the press

package/src/Layer/useTouchTrigger.ts

@@ -24,9 +24,21 @@
  * lose, so the tap opens the layer and the next tap outside dismisses it. That
  * is `auto`; `tap` and `none` state the choice outright, which is what an
  * icon-button whose only job is to reveal the layer needs.
+ *
+ * A touch decides nothing until it is a tap. A finger landing on the trigger
+ * may be starting a scroll, a pinch or a long press, and only the browser
+ * knows which once the finger moves or lifts. Its `click` is that verdict (on
+ * iOS it comes from UIKit's own tap recognizer), so the press only records
+ * itself and the tap's `click` opens or closes the layer; a press the browser
+ * takes for scrolling ends in `pointercancel` and never gets there. That is
+ * how a UIKit tap behaves: it recognizes when the finger lifts and fails once
+ * the scroll view claims the touch. The tap outside that closes a tap-opened
+ * layer counts when the finger lifts too, or when a scroll takes the touch,
+ * which is when UIKit dismisses a popover.
  */
 
 import {useCallback, useEffect, useRef, type RefObject} from 'react';
+import {currentGesture} from './gestureCounter';
 import {
   getInteractionModality,
   useInteractionModalityTracking,
@@ -175,7 +187,9 @@ export interface UseTouchTriggerReturn {
   /**
    * Attach to the trigger. Returns true when the press was a touch one and
    * this hook has dealt with it, meaning the caller's own pointer-down
-   * behavior must not also run.
+   * behavior must not also run. A touch press opens or closes nothing by
+   * itself: the hook waits for that press's tap (the `click` the browser
+   * fires when the finger lifts without scrolling) on the same element.
    */
   handlePointerDown: (event: PointerEvent) => boolean;
 
@@ -234,6 +248,9 @@ export function useTouchTrigger(
   const outsideListenerRef = useRef<((event: PointerEvent) => void) | null>(
     null,
   );
+  // A touch press on the trigger still waiting for its tap: calling it stops
+  // waiting. The next press, a cancel, the tap itself or unmounting calls it.
+  const forgetPendingTapRef = useRef<(() => void) | null>(null);
 
   useInteractionModalityTracking();
 
@@ -244,23 +261,30 @@ export function useTouchTrigger(
       return;
     }
     outsideListenerRef.current = null;
-    document.removeEventListener('pointerdown', listener, true);
+    document.removeEventListener('pointerup', listener, true);
+    document.removeEventListener('pointercancel', listener, true);
   }, []);
 
   // Capture phase, so a trigger that stops propagation cannot strand an open
-  // layer. The opening tap's own capture phase at the document has already
-  // passed by the time this runs, so the listener never sees it.
+  // layer. It is armed by the opening tap's `click`, after that tap's own
+  // `pointerup`, so the listener never sees the tap that opened the layer.
+  // A tap outside counts when it lifts (`pointerup`); a scroll or pinch that
+  // starts outside counts as soon as the browser takes it (`pointercancel`).
   const armOutsideDismiss = useCallback(() => {
     isTapOpenRef.current = true;
     if (outsideListenerRef.current != null) {
       return;
     }
 
-    const handleOutsidePointerDown = (event: PointerEvent) => {
+    const handleOutsidePointerEnd = (event: PointerEvent) => {
       const target = event.target as Node | null;
       if (target != null) {
-        // The trigger's own handler owns the toggle.
-        if (triggerRef.current?.contains(target) === true) {
+        // A tap on the trigger is the trigger's to toggle. A scroll that
+        // starts there is a scroll outside the layer, and it does close it.
+        if (
+          event.type === 'pointerup' &&
+          triggerRef.current?.contains(target) === true
+        ) {
           return;
         }
         // Hover card content is interactive; a tap inside it is not a dismiss.
@@ -274,11 +298,13 @@ export function useTouchTrigger(
       hideRef.current();
     };
 
-    outsideListenerRef.current = handleOutsidePointerDown;
-    document.addEventListener('pointerdown', handleOutsidePointerDown, true);
+    outsideListenerRef.current = handleOutsidePointerEnd;
+    document.addEventListener('pointerup', handleOutsidePointerEnd, true);
+    document.addEventListener('pointercancel', handleOutsidePointerEnd, true);
   }, [triggerRef, disarmOutsideDismiss]);
 
   useEffect(() => disarmOutsideDismiss, [disarmOutsideDismiss]);
+  useEffect(() => () => forgetPendingTapRef.current?.(), []);
 
   const isTouchInteraction = useCallback(
     () => isTouchPointerRef.current && getInteractionModality() === 'pointer',
@@ -293,52 +319,80 @@ export function useTouchTrigger(
     isTouchPointerRef.current = event.pointerType === 'touch';
   }, []);
 
+  // What a tap on the trigger does. It runs from the tap's `click`, after the
+  // render that armed it, so it reads the latest props through this ref.
+  const answerTapRef = useRef<() => void>(() => {});
+  answerTapRef.current = () => {
+    const trigger = triggerRef.current;
+    const mode =
+      touchTrigger === 'auto'
+        ? trigger != null && isActionTrigger(trigger)
+          ? 'none'
+          : 'tap'
+        : touchTrigger;
+
+    if (mode === 'none' || !isEnabled) {
+      // A layer left open by an earlier tap must not survive the next one.
+      disarmOutsideDismiss();
+      hide();
+      return;
+    }
+
+    // A lazily mounted layer reports `isOpen` a tick after `show()`, so the
+    // tap's own bookkeeping is what makes the second tap a close.
+    if (isOpenRef.current || isTapOpenRef.current) {
+      disarmOutsideDismiss();
+      hide();
+      return;
+    }
+
+    armOutsideDismiss();
+    show();
+  };
+
   const handlePointerDown = useCallback(
     (event: PointerEvent): boolean => {
       const isTouch = TOUCH_POINTER_TYPES.has(event.pointerType);
       isTouchPointerRef.current = isTouch;
+      // A new press replaces one that never became a tap.
+      forgetPendingTapRef.current?.();
 
       if (!isTouch || isControlled) {
         return false;
       }
 
-      const trigger = triggerRef.current;
-      const mode =
-        touchTrigger === 'auto'
-          ? trigger != null && isActionTrigger(trigger)
-            ? 'none'
-            : 'tap'
-          : touchTrigger;
-
-      if (mode === 'none' || !isEnabled) {
-        // A layer left open by an earlier tap must not survive the next one.
-        disarmOutsideDismiss();
-        hide();
+      const trigger =
+        event.currentTarget instanceof Element
+          ? event.currentTarget
+          : triggerRef.current;
+      if (trigger == null) {
         return true;
       }
 
-      // A lazily mounted layer reports `isOpen` a tick after `show()`, so the
-      // tap's own bookkeeping is what makes the second tap a close.
-      if (isOpenRef.current || isTapOpenRef.current) {
-        disarmOutsideDismiss();
-        hide();
-        return true;
-      }
-
-      armOutsideDismiss();
-      show();
+      // The tap must belong to this press. A key press or a new pointer press
+      // advances the gesture, so a keyboard activation that later fires
+      // `click` on the trigger (Enter on a button) is not mistaken for it.
+      const gesture = currentGesture();
+      const forget = () => {
+        trigger.removeEventListener('click', handleTap);
+        trigger.removeEventListener('pointercancel', forget);
+        if (forgetPendingTapRef.current === forget) {
+          forgetPendingTapRef.current = null;
+        }
+      };
+      const handleTap = () => {
+        forget();
+        if (currentGesture() === gesture) {
+          answerTapRef.current();
+        }
+      };
+      trigger.addEventListener('click', handleTap);
+      // The browser took the touch for a scroll or a pinch: no tap is coming.
+      trigger.addEventListener('pointercancel', forget);
+      forgetPendingTapRef.current = forget;
       return true;
     },
-    [
-      touchTrigger,
-      isEnabled,
-      isControlled,
-      triggerRef,
-      show,
-      hide,
-      armOutsideDismiss,
-      disarmOutsideDismiss,
-    ],
+    [isControlled, triggerRef],
   );
 
   // A layer closed by any other path (Escape, a consumer, the browser) leaves

package/src/Layout/Layout.tsx

@@ -25,6 +25,7 @@ import {LayoutDividerContext} from './LayoutDividerContext';
 import {stack} from '../Stack/stack.stylex';
 import {stackItem} from '../Stack/stackItem.stylex';
 import {mergeProps} from '../utils';
+import {layoutFooterMarker, layoutHeaderMarker} from './layoutEdges.stylex';
 import type {BaseProps} from '../BaseProps';
 import type {SizeValue, SpacingStep} from '../utils/types';
 import {themeProps} from '../utils/themeProps';
@@ -101,6 +102,23 @@ const styles = stylex.create({
   middle: {
     flex: 1,
     minHeight: 0,
+    // A LayoutHeader without a divider right before this row, or a
+    // LayoutFooter without one right after it, removes the matching inner
+    // padding of LayoutContent (it reads these, falling back to its padding).
+    // Sibling relations on this row only: a `:has()` on the layout followed
+    // by `*` restyles everything inside it on any change. Unset otherwise, so
+    // a nested Layout's content inherits an outer row's value, as the
+    // ancestor rule this replaces matched any enclosing layout.
+    '--_layout-flush-block-start': {
+      default: null,
+      [stylex.when.siblingBefore(':not([data-divider])', layoutHeaderMarker)]:
+        '0px',
+    },
+    '--_layout-flush-block-end': {
+      default: null,
+      [stylex.when.siblingAfter(':not([data-divider])', layoutFooterMarker)]:
+        '0px',
+    },
   },
   middleQuery: {
     containerType: {

package/src/Layout/LayoutContent.tsx

@@ -41,20 +41,11 @@ const styles = stylex.create({
     // Default: inner padding on all sides (will be overridden by position-specific styles)
     paddingInlineStart: `var(--layout-padding-inner-x, ${spacingVars['--spacing-4']})`,
     paddingInlineEnd: `var(--layout-padding-inner-x, ${spacingVars['--spacing-4']})`,
-    paddingBlockStart: {
-      default: `var(--layout-padding-inner-y, ${spacingVars['--spacing-4']})`,
-      // When header has no divider, collapse top padding for seamless visual flow
-      [stylex.when.ancestor(
-        ':has(> .astryx-layout-header:not([data-divider]))',
-      )]: 0,
-    },
-    paddingBlockEnd: {
-      default: `var(--layout-padding-inner-y, ${spacingVars['--spacing-4']})`,
-      // When footer has no divider, collapse bottom padding for seamless visual flow
-      [stylex.when.ancestor(
-        ':has(> .astryx-layout-footer:not([data-divider]))',
-      )]: 0,
-    },
+    // A header or footer without a divider collapses the adjacent padding
+    // for a seamless visual flow: Layout's middle row sets these to 0px then
+    // (see Layout.tsx `middle`).
+    paddingBlockStart: `var(--_layout-flush-block-start, var(--layout-padding-inner-y, ${spacingVars['--spacing-4']}))`,
+    paddingBlockEnd: `var(--_layout-flush-block-end, var(--layout-padding-inner-y, ${spacingVars['--spacing-4']}))`,
     // Publish container padding vars for bleed children (Table, Divider, etc.)
     '--container-padding-inline-start': `var(--layout-padding-inner-x, ${spacingVars['--spacing-4']})`,
     '--container-padding-inline-end': `var(--layout-padding-inner-x, ${spacingVars['--spacing-4']})`,

package/src/Layout/LayoutFooter.tsx

@@ -19,6 +19,7 @@ import type {AriaRole, ReactNode} from 'react';
 import type {BaseProps} from '../BaseProps';
 import {use} from 'react';
 import * as stylex from '@stylexjs/stylex';
+import {layoutFooterMarker} from './layoutEdges.stylex';
 import {LayoutDividerContext} from './LayoutDividerContext';
 import {colorVars, spacingVars} from '../theme/tokens.stylex';
 import {mergeProps} from '../utils';
@@ -161,6 +162,7 @@ export function LayoutFooter({
       {...mergeProps(
         themeProps('layout-footer'),
         stylex.props(
+          layoutFooterMarker,
           styles.footer,
           dynamicStyles.sizing(height ?? null),
 

package/src/Layout/LayoutHeader.tsx

@@ -20,6 +20,7 @@ import type {AriaRole, ReactNode} from 'react';
 import type {BaseProps} from '../BaseProps';
 import {use} from 'react';
 import * as stylex from '@stylexjs/stylex';
+import {layoutHeaderMarker} from './layoutEdges.stylex';
 import {LayoutDividerContext} from './LayoutDividerContext';
 import {colorVars, spacingVars} from '../theme/tokens.stylex';
 import {mergeProps} from '../utils';
@@ -173,6 +174,7 @@ export function LayoutHeader({
       {...mergeProps(
         themeProps('layout-header'),
         stylex.props(
+          layoutHeaderMarker,
           styles.header,
           dynamicStyles.sizing(height ?? null),
 

package/src/Layout/__tests__/Layout.a11y.chromium.spec.ts

@@ -1,4 +1,5 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
+// @pr-a11y scope ^(internal/a11y-spec/src/patterns/landmark|packages/core/src/Layout/|apps/storybook/stories/LayoutLandmarkA11y)
 
 /** Real-browser and accessibility-tree binding evidence for Layout regions. */
 

package/src/Layout/layoutEdges.stylex.ts

@@ -0,0 +1,25 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file layoutEdges.stylex.ts
+ * @input StyleX markers
+ * @output Exports layoutHeaderMarker and layoutFooterMarker
+ * @position Internal markers LayoutHeader and LayoutFooter carry on their own
+ *   element, so Layout's middle row can tell whether a divider-less header
+ *   precedes it or a divider-less footer follows it with sibling relations
+ *   alone, instead of a `:has()` on the layout followed by `*`, which makes
+ *   engines restyle the whole layout on any change inside it
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/Layout/Layout.tsx
+ * - /packages/core/src/Layout/LayoutHeader.tsx
+ * - /packages/core/src/Layout/LayoutFooter.tsx
+ * - /packages/core/src/Layout/LayoutContent.tsx
+ */
+
+import * as stylex from '@stylexjs/stylex';
+
+export const layoutHeaderMarker: ReturnType<typeof stylex.defineMarker> =
+  stylex.defineMarker();
+export const layoutFooterMarker: ReturnType<typeof stylex.defineMarker> =
+  stylex.defineMarker();

package/src/Lightbox/Lightbox.spec.md

@@ -72,11 +72,12 @@ in `Lightbox.doc.mjs`.
 
 ## Behavioral and layout contract
 
-| ID  | Candidate invariant                                                                                                                                                                    | Basis                           | Draft review state                                 |
-| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | -------------------------------------------------- |
-| FR1 | The current viewer contains one active Media item and a Close button; galleries additionally contain Previous and Next buttons plus a Counter, and Caption renders only when supplied. | Current source, docs, and tests | Verified current behavior; no new behavior decided |
-| FR2 | Viewer overlay carries the current `lightbox` target. Media, Caption, and Counter carry no Lightbox public target.                                                                     | Current source and public docs  | Verified current reachability; no target change    |
-| FR3 | Close, Previous, and Next button surfaces use Button's `button` target through IconButton rather than Lightbox-owned button targets.                                                   | Current source and target docs  | Verified current delegation; no ownership change   |
+| ID  | Candidate invariant                                                                                                                                                                                                                                                                | Basis                           | Draft review state                                 |
+| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | -------------------------------------------------- |
+| FR1 | The current viewer contains one active Media item and a Close button; galleries additionally contain Previous and Next buttons plus a Counter, and Caption renders only when supplied.                                                                                             | Current source, docs, and tests | Verified current behavior; no new behavior decided |
+| FR2 | Viewer overlay carries the current `lightbox` target. Media, Caption, and Counter carry no Lightbox public target.                                                                                                                                                                 | Current source and public docs  | Verified current reachability; no target change    |
+| FR3 | Close, Previous, and Next button surfaces use Button's `button` target through IconButton rather than Lightbox-owned button targets.                                                                                                                                               | Current source and target docs  | Verified current delegation; no ownership change   |
+| FR4 | The open viewer is a focus region through Core's shared focus-region module (`component:Dialog/DEC-2`): Tab from its last control moves focus to its first and Shift+Tab from its first moves focus to its last, so focus never leaves the viewer for the browser's own interface. | `component:Dialog/DEC-2`        | Owner decision; tests land with the implementation |
 
 ### Allowed variation
 
@@ -106,9 +107,9 @@ in `Lightbox.doc.mjs`.
 
 ## Accessibility contract
 
-This draft does not change or extend Lightbox's existing dialog naming, focus,
-media alternatives, announcements, button labels, keyboard behavior, or
-dismissal behavior.
+Apart from Tab containment (FR4), this draft does not change or extend
+Lightbox's existing dialog naming, focus, media alternatives, announcements,
+button labels, keyboard behavior, or dismissal behavior.
 
 ## Design relationships
 

package/src/Lightbox/Lightbox.test.tsx

@@ -53,6 +53,21 @@ describe('Lightbox', () => {
     expect(dialog).toBeInTheDocument();
   });
 
+  it('opens once an item arrives when opened with none', () => {
+    const {rerender} = render(
+      <Lightbox isOpen={true} onOpenChange={() => {}} media={[]} />,
+    );
+    expect(document.querySelector('dialog')).toBeNull();
+    rerender(
+      <Lightbox
+        isOpen={true}
+        onOpenChange={() => {}}
+        media={[{src: '/photo.jpg', alt: 'Photo'}]}
+      />,
+    );
+    expect(document.querySelector('dialog')).toHaveAttribute('open');
+  });
+
   it('calls showModal when isOpen becomes true', () => {
     render(
       <Lightbox
@@ -322,6 +337,50 @@ describe('Lightbox', () => {
       fireEvent.keyDown(dialog, {key: 'ArrowLeft'});
       expect(onIndexChange).toHaveBeenCalledWith(0);
     });
+
+    it('follows the visual direction of the arrows in RTL', () => {
+      const onIndexChange = vi.fn();
+      render(
+        <div dir="rtl">
+          <Lightbox
+            isOpen={true}
+            onOpenChange={() => {}}
+            media={media}
+            index={1}
+            onIndexChange={onIndexChange}
+          />
+        </div>,
+      );
+      const dialog = document.querySelector('dialog')!;
+      // The component resolves direction with getComputedStyle at keydown, and
+      // jsdom does not inherit `dir` down to it, so set it on the dialog too.
+      dialog.style.direction = 'rtl';
+      // Next sits on the left in RTL: ArrowLeft moves to the next item.
+      fireEvent.keyDown(dialog, {key: 'ArrowLeft'});
+      expect(onIndexChange).toHaveBeenLastCalledWith(2);
+      fireEvent.keyDown(dialog, {key: 'ArrowRight'});
+      expect(onIndexChange).toHaveBeenLastCalledWith(0);
+      expect(onIndexChange).toHaveBeenCalledTimes(2);
+    });
+
+    it('resolves the direction at keydown, so a direction change applies at once', () => {
+      const onIndexChange = vi.fn();
+      render(
+        <Lightbox
+          isOpen={true}
+          onOpenChange={() => {}}
+          media={media}
+          index={1}
+          onIndexChange={onIndexChange}
+        />,
+      );
+      const dialog = document.querySelector('dialog')!;
+      fireEvent.keyDown(dialog, {key: 'ArrowLeft'});
+      expect(onIndexChange).toHaveBeenLastCalledWith(0);
+      dialog.style.direction = 'rtl';
+      fireEvent.keyDown(dialog, {key: 'ArrowLeft'});
+      expect(onIndexChange).toHaveBeenLastCalledWith(2);
+    });
   });
 
   describe('screen-reader announcements', () => {
@@ -569,6 +628,30 @@ describe('Lightbox', () => {
       expect(onIndexChange).toHaveBeenCalledWith(2);
     });
 
+    it('keeps panning physical in RTL: the image is not mirrored', () => {
+      const onIndexChange = vi.fn();
+      render(
+        <Lightbox
+          isOpen={true}
+          onOpenChange={() => {}}
+          media={media}
+          index={1}
+          onIndexChange={onIndexChange}
+          hasZoom
+        />,
+      );
+      const dialog = document.querySelector('dialog')!;
+      dialog.style.direction = 'rtl';
+      fireEvent.keyDown(zoomTarget(), {key: 'Enter'});
+      const img = screen.getByAltText('Image B');
+      // ArrowRight still reveals what is to the right of the photo.
+      fireEvent.keyDown(dialog, {key: 'ArrowRight'});
+      expect(img.getAttribute('style') ?? '').toContain(
+        'translate(-25px, 0px)',
+      );
+      expect(onIndexChange).not.toHaveBeenCalled();
+    });
+
     it('announces zoom state changes politely', async () => {
       render(
         <Lightbox