@astryxdesign/core 0.1.9 → 0.2.0-canary.068bda9

package/src/Icon/Icon.test.tsx

@@ -11,6 +11,7 @@
 
 import {describe, it, expect, vi} from 'vitest';
 import {render, screen} from '@testing-library/react';
+import * as stylex from '@stylexjs/stylex';
 import {TestIcon} from '../__tests__/TestIcon';
 import {Icon} from './Icon';
 
@@ -279,4 +280,92 @@ describe('Icon', () => {
       );
     });
   });
+
+  describe('styling prop handling', () => {
+    it('composes a consumer className with the internal classes (string mode)', () => {
+      render(
+        <Icon icon="check" className="consumer-target" data-testid="icon" />,
+      );
+      const icon = screen.getByTestId('icon');
+      // Consumer className must survive alongside the stable astryx-icon class
+      // and the StyleX classes — previously it was clobbered by the later
+      // internal spread.
+      expect(icon).toHaveClass('consumer-target');
+      expect(icon).toHaveClass('astryx-icon');
+      // At least one StyleX-generated class is still present.
+      expect(icon.className.split(' ').length).toBeGreaterThan(2);
+    });
+
+    it('forwards a consumer className in component (SVG) mode', () => {
+      render(
+        <Icon icon={TestIcon} className="consumer-target" data-testid="icon" />,
+      );
+      const icon = screen.getByTestId('icon');
+      expect(icon).toHaveClass('consumer-target');
+      expect(icon).toHaveClass('astryx-icon');
+    });
+
+    it('merges a consumer style onto the rendered element (string mode)', () => {
+      render(<Icon icon="check" style={{opacity: 0.5}} data-testid="icon" />);
+      expect(screen.getByTestId('icon')).toHaveStyle({opacity: '0.5'});
+    });
+
+    it('merges a consumer style onto the rendered element (component mode)', () => {
+      render(
+        <Icon icon={TestIcon} style={{opacity: 0.5}} data-testid="icon" />,
+      );
+      expect(screen.getByTestId('icon')).toHaveStyle({opacity: '0.5'});
+    });
+
+    it('applies xstyle to the rendered element (string mode)', () => {
+      const overrides = stylex.create({root: {opacity: 0.25}});
+      render(<Icon icon="check" xstyle={overrides.root} data-testid="icon" />);
+      const icon = screen.getByTestId('icon');
+      // xstyle is folded into stylex.props, so it contributes a StyleX class
+      // (and, in jsdom's stylex runtime, an inline style) alongside the base
+      // color/size classes rather than clobbering them.
+      expect(icon).toHaveClass('astryx-icon');
+      expect(icon).toHaveStyle({opacity: '0.25'});
+    });
+
+    it('applies xstyle to the rendered element (component mode)', () => {
+      const overrides = stylex.create({root: {opacity: 0.25}});
+      render(
+        <Icon icon={TestIcon} xstyle={overrides.root} data-testid="icon" />,
+      );
+      const icon = screen.getByTestId('icon');
+      expect(icon).toHaveClass('astryx-icon');
+      expect(icon).toHaveStyle({opacity: '0.25'});
+    });
+
+    it('leaves default rendering unchanged when no styling props are passed (string mode)', () => {
+      const {container} = render(
+        <Icon icon="check" size="sm" color="secondary" />,
+      );
+      const icon = container.querySelector('.astryx-icon') as HTMLElement;
+      const {container: refContainer} = render(
+        <Icon icon="check" size="sm" color="secondary" />,
+      );
+      const refIcon = refContainer.querySelector('.astryx-icon') as HTMLElement;
+      // Default output is identical to itself — the styling-prop handling adds
+      // nothing (no extra class, no inline style) unless a prop is passed.
+      expect(icon.className).toBe(refIcon.className);
+      expect(icon.getAttribute('style')).toBe(refIcon.getAttribute('style'));
+    });
+
+    it('leaves default rendering unchanged when no styling props are passed (component mode)', () => {
+      const {container} = render(
+        <Icon icon={TestIcon} size="sm" color="secondary" />,
+      );
+      const icon = container.querySelector('.astryx-icon') as HTMLElement;
+      const {container: refContainer} = render(
+        <Icon icon={TestIcon} size="sm" color="secondary" />,
+      );
+      const refIcon = refContainer.querySelector('.astryx-icon') as HTMLElement;
+      // SVGElement.className is an SVGAnimatedString, so compare the class
+      // attribute string rather than the property object.
+      expect(icon.getAttribute('class')).toBe(refIcon.getAttribute('class'));
+      expect(icon.getAttribute('style')).toBe(refIcon.getAttribute('style'));
+    });
+  });
 });

package/src/Icon/Icon.tsx

@@ -24,6 +24,7 @@
 
 import React, {type ComponentType, type SVGProps} from 'react';
 import * as stylex from '@stylexjs/stylex';
+import type {StyleXStyles} from '@stylexjs/stylex';
 import {colorVars} from '../theme/tokens.stylex';
 import {getIcon} from './globalIconRegistry';
 import type {IconName} from './globalIconRegistry';
@@ -244,6 +245,19 @@ export interface IconProps extends Omit<
    * ```
    */
   label?: string;
+  /**
+   * StyleX styles created via `stylex.create()`. Folded into the icon's own
+   * `stylex.props()` call (as the last argument) so it merges with the base
+   * color/size styles for optimal deduplication, matching how other Astryx
+   * components accept `xstyle`.
+   *
+   * @example
+   * ```
+   * const overrides = stylex.create({ root: { opacity: 0.5 } });
+   * <Icon icon="search" xstyle={overrides.root} />
+   * ```
+   */
+  xstyle?: StyleXStyles;
 }
 
 /**
@@ -283,6 +297,9 @@ export function Icon({
   size = 'md',
   label,
   ref,
+  className,
+  style,
+  xstyle,
   ...props
 }: IconProps) {
   // Derive ARIA from `label`: decorative (aria-hidden) by default, or a
@@ -297,6 +314,9 @@ export function Icon({
         color={color}
         size={size}
         a11yProps={a11yProps}
+        className={className}
+        style={style}
+        xstyle={xstyle}
         spanProps={props}
       />
     );
@@ -311,9 +331,16 @@ export function Icon({
       // BEFORE {...props} so an explicit aria-hidden/role/aria-label from the
       // consumer still wins as an escape hatch.
       {...a11yProps}
+      // The styling props (className, style, xstyle) are handled here so they
+      // COMPOSE with the internal classes/styles instead of clobbering them:
+      // xstyle folds into stylex.props, and className/style merge via
+      // mergeProps. The remaining rest props keep their prior last-spread
+      // precedence as escape hatches.
       {...mergeProps(
         themeProps('icon', {size, color}),
-        stylex.props(styles.root, colorStyles[color], sizeStyles[size]),
+        stylex.props(styles.root, colorStyles[color], sizeStyles[size], xstyle),
+        className ?? undefined,
+        style,
       )}
       {...props}
     />
@@ -338,12 +365,18 @@ function IconFromRegistry({
   color,
   size,
   a11yProps,
+  className,
+  style,
+  xstyle,
   spanProps,
 }: {
   name: IconName;
   color: IconColor;
   size: IconSize;
   a11yProps: {role: 'img'; 'aria-label': string} | {'aria-hidden': 'true'};
+  className?: string;
+  style?: React.CSSProperties;
+  xstyle?: StyleXStyles;
   spanProps?: Omit<SVGProps<SVGSVGElement>, 'ref' | 'color'>;
 }) {
   const resolvedIcon = getIcon(name);
@@ -352,6 +385,14 @@ function IconFromRegistry({
     return null;
   }
 
+  // The styling props (className, style, xstyle) are handled here so they
+  // COMPOSE with the internal astryx-icon + StyleX classes/styles instead of
+  // being shadowed by the later spread: xstyle folds into stylex.props, and
+  // className/style merge via mergeProps. Other span props keep their prior
+  // precedence (spread before the internal merge).
+  const restSpanProps =
+    (spanProps as React.HTMLAttributes<HTMLSpanElement>) ?? {};
+
   return (
     <span
       // Derived a11y — decorative (aria-hidden) by default, or a meaningful
@@ -359,10 +400,17 @@ function IconFromRegistry({
       // prop spread so consumers can still override it with explicit
       // aria-hidden/role/aria-label. This mirrors component-mode Icon.
       {...a11yProps}
-      {...(spanProps as React.HTMLAttributes<HTMLSpanElement>)}
+      {...restSpanProps}
       {...mergeProps(
         themeProps('icon', {size, color}),
-        stylex.props(styles.span, colorStyles[color], spanSizeStyles[size]),
+        stylex.props(
+          styles.span,
+          colorStyles[color],
+          spanSizeStyles[size],
+          xstyle,
+        ),
+        className ?? undefined,
+        style,
       )}>
       {resolvedIcon}
     </span>

package/src/Item/Item.doc.mjs

@@ -37,6 +37,7 @@ export const docs = {
         {name: 'labelLines', type: 'number', description: 'Max lines before label truncates with ellipsis.'},
         {name: 'descriptionLines', type: 'number', description: 'Max lines before description truncates with ellipsis.'},
         {name: 'onClick', type: '(event: MouseEvent) => void', description: 'Click handler. Makes the item clickable with button semantics.'},
+        {name: 'interactiveRef', type: 'RefObject<HTMLElement | null>', description: 'Ref to a nested control (e.g. a checkbox in startContent) that owns the item\'s keyboard access and action. The row becomes an enlarged click/tap target that delegates surface clicks to it (useClickableContainer) and renders no invisible button/anchor, so the row adds no second tab stop (WCAG 4.1.2). Mutually exclusive with onClick/href — those are ignored when set.'},
         {name: 'href', type: 'string', description: 'Link URL. Makes the item a link via an invisible anchor element.'},
         {name: 'target', type: "'_blank' | '_self'", description: 'Link target. Only used with href. target="_blank" automatically adds noopener noreferrer.'},
         {name: 'rel', type: 'string', description: 'Link relationship tokens. noopener noreferrer are merged automatically for target="_blank".'},
@@ -90,6 +91,8 @@ export const docsZh = {
         labelLines: '标签截断前的最大行数。',
         descriptionLines: '描述截断前的最大行数。',
         onClick: '点击处理函数。使项目可点击，具有按钮语义。',
+        interactiveRef:
+          '指向嵌套控件（如 startContent 中的复选框）的 ref，该控件承载项目的键盘访问和操作。行成为更大的点击/触摸目标，将表面点击委托给该控件（useClickableContainer），且不渲染不可见按钮/锚点，因此行不会增加第二个 Tab 停留点（WCAG 4.1.2）。与 onClick/href 互斥——设置后二者将被忽略。',
         href: '链接 URL。通过不可见锚点元素使项目成为链接。',
         target: '链接目标。仅与 href 一起使用。target="_blank" 会自动添加 noopener noreferrer。',
         rel: '链接关系标记。target="_blank" 会自动合并 noopener noreferrer。',
@@ -157,6 +160,8 @@ export const docsDense = {
         labelLines: 'Max label lines before truncation.',
         descriptionLines: 'Max description lines before truncation.',
         onClick: 'Click handler; enables button semantics.',
+        interactiveRef:
+          'Ref to a nested control that owns the item\'s keyboard access/action; row delegates surface clicks to it (useClickableContainer), no invisible button/anchor, no second tab stop (WCAG 4.1.2). Mutually exclusive with onClick/href.',
         href: 'Link URL; enables anchor semantics.',
         target:
           'Link target, only with href. target="_blank" auto-adds noopener noreferrer.',

package/src/Item/Item.test.tsx

@@ -9,11 +9,35 @@
  * SYNC: When Item component changes, update tests to match new behavior
  */
 
+import {useRef} from 'react';
 import {describe, it, expect, vi} from 'vitest';
 import {render, screen} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {Item} from './Item';
 
+/**
+ * Item in delegation mode: `interactiveRef` points at a nested control that
+ * owns the row's keyboard access and action. The row is an enlarged tap target
+ * that forwards surface clicks to that control (useClickableContainer).
+ */
+function DelegatingItem({onToggle}: {onToggle?: () => void}) {
+  const ref = useRef<HTMLInputElement>(null);
+  return (
+    <Item
+      label="Row"
+      interactiveRef={ref}
+      startContent={
+        <input
+          ref={ref}
+          type="checkbox"
+          aria-label="Pick row"
+          onChange={onToggle}
+        />
+      }
+    />
+  );
+}
+
 describe('Item', () => {
   // ===========================================================================
   // Basic rendering
@@ -190,6 +214,70 @@ describe('Item', () => {
     expect(buttons).toHaveLength(1);
   });
 
+  // ===========================================================================
+  // Interactive — interactiveRef (delegation to a nested control)
+  // ===========================================================================
+
+  it('renders no invisible button in interactiveRef (delegation) mode', () => {
+    const {container} = render(<DelegatingItem />);
+    // The nested control provides keyboard access — the row must not add a
+    // second focusable control for the same action (WCAG 4.1.2).
+    expect(container.querySelector('button')).not.toBeInTheDocument();
+  });
+
+  it('keeps the nested control as the only tab stop in interactiveRef mode', async () => {
+    const user = userEvent.setup();
+    render(<DelegatingItem />);
+    await user.tab();
+    expect(screen.getByRole('checkbox')).toHaveFocus();
+    // Next tab leaves the item entirely — the row itself is not focusable.
+    await user.tab();
+    expect(screen.getByRole('checkbox')).not.toHaveFocus();
+    expect(document.body).toHaveFocus();
+  });
+
+  it('delegates a row-surface click to the interactive control', async () => {
+    const user = userEvent.setup();
+    const onToggle = vi.fn();
+    render(<DelegatingItem onToggle={onToggle} />);
+    // Clicking the label (row surface) is forwarded to the checkbox.
+    await user.click(screen.getByText('Row'));
+    expect(onToggle).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not double-fire when the interactive control itself is clicked', async () => {
+    const user = userEvent.setup();
+    const onToggle = vi.fn();
+    render(<DelegatingItem onToggle={onToggle} />);
+    await user.click(screen.getByRole('checkbox'));
+    // The row must not re-forward the control's own click back to it.
+    expect(onToggle).toHaveBeenCalledTimes(1);
+  });
+
+  it('ignores onClick when interactiveRef is set (delegation wins, single tab stop)', async () => {
+    const user = userEvent.setup();
+    const onClick = vi.fn();
+    function ItemWithBoth() {
+      const ref = useRef<HTMLInputElement>(null);
+      return (
+        <Item
+          label="Row"
+          onClick={onClick}
+          interactiveRef={ref}
+          startContent={
+            <input ref={ref} type="checkbox" aria-label="Pick row" />
+          }
+        />
+      );
+    }
+    const {container} = render(<ItemWithBoth />);
+    // No invisible button (onClick is ignored in delegation mode)...
+    expect(container.querySelector('button')).not.toBeInTheDocument();
+    // ...and the checkbox is still the sole tab stop.
+    await user.tab();
+    expect(screen.getByRole('checkbox')).toHaveFocus();
+  });
+
   // ===========================================================================
   // Interactive — href (invisible anchor pattern)
   // ===========================================================================

package/src/Item/Item.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file Item.tsx
- * @input Uses React, ReactNode, StyleXStyles, theme tokens
+ * @input Uses React, ReactNode, StyleXStyles, theme tokens, useClickableContainer
  * @output Exports Item component, ItemProps type
  * @position Core layout primitive; consumed by index.ts, tested by Item.test.tsx
  *
@@ -16,7 +16,7 @@
  * - /packages/cli/templates/blocks/components/Item/ (showcase blocks)
  */
 
-import type {ReactNode} from 'react';
+import {useRef, type ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {
   colorVars,
@@ -27,9 +27,11 @@ import {
   typeScaleVars,
 } from '../theme/tokens.stylex';
 import type {BaseProps} from '../BaseProps';
-import {mergeProps} from '../utils';
+import {mergeProps, mergeRefs} from '../utils';
 import {computeTargetAndRel} from '../Link/computeTargetAndRel';
 import {useLinkComponent} from '../Link/useLinkComponent';
+import {useClickableContainer} from '../hooks/useClickableContainer';
+import {useDevWarning} from '../hooks/useDevWarning';
 import {themeProps} from '../utils/themeProps';
 
 // =============================================================================
@@ -108,6 +110,20 @@ export interface ItemProps extends BaseProps<HTMLElement> {
    */
   onClick?: (event: React.MouseEvent) => void;
 
+  /**
+   * Ref to a nested control inside the item (e.g. a checkbox in
+   * `startContent`) that already provides the item's keyboard access and
+   * action. When set, the item becomes an enlarged click/tap target that
+   * delegates surface clicks to that control via the `useClickableContainer`
+   * pattern: it renders no invisible button/anchor, so the row adds no second
+   * tab stop (WCAG 4.1.2 — one focusable control per option). Clicks on the
+   * control itself, and on any other nested interactive element, are left to
+   * that element. Mutually exclusive with `onClick`/`href` — when
+   * `interactiveRef` is set those are ignored (the nested control is the sole
+   * action).
+   */
+  interactiveRef?: React.RefObject<HTMLElement | null>;
+
   /**
    * Link URL. Makes the item a link via an invisible anchor element.
    */
@@ -349,6 +365,7 @@ export function Item({
   labelLines,
   descriptionLines,
   onClick,
+  interactiveRef,
   href,
   target: targetFromProps,
   rel: relFromProps,
@@ -363,7 +380,29 @@ export function Item({
   ...restProps
 }: ItemProps) {
   const LinkComponent = useLinkComponent();
-  const isInteractive = onClick != null || href != null;
+
+  // Delegation mode: the row is an enlarged click/tap target for a nested
+  // control (e.g. a checkbox) that owns the keyboard access and action. The
+  // control is the row's only tab stop; the row proxies surface clicks to it.
+  const isDelegate = interactiveRef != null;
+  const containerRef = useRef<HTMLElement | null>(null);
+  // Only onClick is needed: onMouseUp handles middle-click href navigation,
+  // which delegation mode never has (href is ignored here).
+  const {onClick: delegatedOnClick} = useClickableContainer({
+    containerRef,
+    interactiveRef: interactiveRef ?? undefined,
+    disabled: isDisabled,
+  });
+
+  useDevWarning(
+    'Item',
+    '`interactiveRef` is mutually exclusive with `onClick`/`href`. In ' +
+      'delegation mode the row only forwards clicks to the referenced control, ' +
+      'so `onClick`/`href` are ignored. Drop one of them.',
+    isDelegate && (onClick != null || href != null),
+  );
+
+  const isInteractive = onClick != null || href != null || isDelegate;
   const {target, rel} = computeTargetAndRel(targetFromProps, relFromProps);
   // When a semantic role is provided (e.g. "menuitem"), a parent component
   // handles keyboard access. Skip the invisible button/anchor and put
@@ -441,7 +480,10 @@ export function Item({
         <span {...stylex.props(styles.startContent)}>{startContent}</span>
       )}
 
-      {hasParentRole ? (
+      {hasParentRole || isDelegate ? (
+        // Delegation mode (and parent-role mode) put the label in a plain span:
+        // keyboard access lives on the nested control, so no invisible
+        // button/anchor is rendered and the row adds no second tab stop.
         <span
           {...stylex.props(
             styles.content,
@@ -497,7 +539,9 @@ export function Item({
 
   return (
     <Component
-      ref={ref as React.Ref<never>}
+      ref={
+        (isDelegate ? mergeRefs(ref, containerRef) : ref) as React.Ref<never>
+      }
       {...restProps}
       aria-selected={(allowsAriaSelected && isSelected) || undefined}
       // aria-selected is invalid on roles that don't permit it (listitem, a
@@ -527,11 +571,13 @@ export function Item({
       )}
       role={role}
       onClick={
-        hasParentRole
-          ? onClick
-          : isInteractive
-            ? handleContainerClick
-            : undefined
+        isDelegate
+          ? delegatedOnClick
+          : hasParentRole
+            ? onClick
+            : isInteractive
+              ? handleContainerClick
+              : undefined
       }>
       {innerContent}
     </Component>

package/src/Layer/layerAnimations.stylex.ts

@@ -61,6 +61,27 @@ const enterStart = stylex.keyframes({
   to: {opacity: 1, transform: 'translateX(0) scale(1)'},
 });
 
+// RTL: the horizontal entrance nudge is a physical translateX, so it must
+// mirror under RTL — a layer on the inline-end/start side must slide in from
+// the correct physical side following the reading flow. Only the horizontal
+// (translateX) keyframes need mirroring; the vertical enterAbove/enterBelow
+// (translateY) entrances are direction-neutral and are left as-is.
+const enterEndRtl = stylex.keyframes({
+  from: {
+    opacity: 0,
+    transform: `translateX(${spacingVars['--spacing-2']}) scale(0.95)`,
+  },
+  to: {opacity: 1, transform: 'translateX(0) scale(1)'},
+});
+
+const enterStartRtl = stylex.keyframes({
+  from: {
+    opacity: 0,
+    transform: `translateX(calc(-1 * ${spacingVars['--spacing-2']})) scale(0.95)`,
+  },
+  to: {opacity: 1, transform: 'translateX(0) scale(1)'},
+});
+
 const animationBase = {
   animationDuration: durationVars['--duration-fast-max'],
   animationTimingFunction: easeVars['--ease-standard'],
@@ -95,6 +116,7 @@ export const layerAnimations = stylex.create({
   end: {
     animationName: {
       default: enterEnd,
+      ':is([dir="rtl"] *)': enterEndRtl,
       '@media (prefers-reduced-motion: reduce)': 'none',
     },
     ...animationBase,
@@ -102,6 +124,7 @@ export const layerAnimations = stylex.create({
   start: {
     animationName: {
       default: enterStart,
+      ':is([dir="rtl"] *)': enterStartRtl,
       '@media (prefers-reduced-motion: reduce)': 'none',
     },
     ...animationBase,

package/src/Lightbox/Lightbox.test.tsx

@@ -443,4 +443,37 @@ describe('Lightbox', () => {
     );
     expect(container.querySelector('dialog')).not.toBeInTheDocument();
   });
+
+  describe('backdrop dismiss', () => {
+    it('calls onOpenChange(false) when the dark area around the media is clicked', () => {
+      const onOpenChange = vi.fn();
+      render(
+        <Lightbox
+          isOpen={true}
+          onOpenChange={onOpenChange}
+          media={{src: '/photo.jpg', alt: 'Photo'}}
+        />,
+      );
+      // The container fills the whole dialog, so a click on the visual
+      // backdrop (the dark area around the media) lands on it — not on the
+      // dialog element itself.
+      const dialog = document.querySelector('dialog')!;
+      const container = dialog.firstElementChild!;
+      fireEvent.click(container);
+      expect(onOpenChange).toHaveBeenCalledWith(false);
+    });
+
+    it('does not close when the media itself is clicked', () => {
+      const onOpenChange = vi.fn();
+      render(
+        <Lightbox
+          isOpen={true}
+          onOpenChange={onOpenChange}
+          media={{src: '/photo.jpg', alt: 'Photo'}}
+        />,
+      );
+      fireEvent.click(screen.getByRole('img', {hidden: true}));
+      expect(onOpenChange).not.toHaveBeenCalled();
+    });
+  });
 });

package/src/Lightbox/Lightbox.tsx

@@ -32,7 +32,7 @@ import {IconButton} from '../IconButton';
 import {useAnnounce} from '../hooks/useAnnounce';
 import {useScrollLock} from '../hooks/useScrollLock';
 import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
-import {mergeProps, mergeRefs} from '../utils';
+import {mergeProps, mergeRefs, rtlStyles} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
@@ -199,7 +199,7 @@ const styles = stylex.create({
   closeButton: {
     position: 'absolute',
     top: spacingVars['--spacing-3'],
-    right: spacingVars['--spacing-3'],
+    insetInlineEnd: spacingVars['--spacing-3'],
     zIndex: 1,
   },
   navButton: {
@@ -209,15 +209,15 @@ const styles = stylex.create({
     zIndex: 1,
   },
   navPrev: {
-    left: spacingVars['--spacing-3'],
+    insetInlineStart: spacingVars['--spacing-3'],
   },
   navNext: {
-    right: spacingVars['--spacing-3'],
+    insetInlineEnd: spacingVars['--spacing-3'],
   },
   counter: {
     position: 'absolute',
     top: spacingVars['--spacing-3'],
-    left: spacingVars['--spacing-3'],
+    insetInlineStart: spacingVars['--spacing-3'],
     color: colorVars['--color-on-dark'],
     fontSize: typeScaleVars['--text-body-size'],
     lineHeight: typeScaleVars['--text-body-leading'],
@@ -285,6 +285,7 @@ export function Lightbox({
 }: LightboxProps) {
   const t = useTranslator();
   const dialogRef = useRef<HTMLDialogElement>(null);
+  const containerRef = useRef<HTMLDivElement>(null);
   const imageWrapperRef = useRef<HTMLDivElement>(null);
   const triggerElementRef = useRef<Element | null>(null);
 
@@ -390,10 +391,19 @@ export function Lightbox({
     [handleClose],
   );
 
-  // Backdrop click
+  // Backdrop click. The layout container fills the whole transparent dialog,
+  // so clicks on the visual backdrop (the dark area around the media) land on
+  // the container, never on the dialog element itself — treat both as the
+  // backdrop. A pan drag that ends over the backdrop still fires a click on
+  // the common ancestor; ignore it so releasing a drag doesn't dismiss.
+  const didDragRef = useRef(false);
   const handleBackdropClick = useCallback(
     (e: ReactMouseEvent<HTMLDialogElement>) => {
-      if (e.target === e.currentTarget) {
+      if (didDragRef.current) {
+        didDragRef.current = false;
+        return;
+      }
+      if (e.target === e.currentTarget || e.target === containerRef.current) {
         handleClose();
       }
     },
@@ -448,6 +458,7 @@ export function Lightbox({
         return;
       }
       setIsDragging(true);
+      didDragRef.current = false;
       dragStartRef.current = {
         x: e.clientX,
         y: e.clientY,
@@ -464,6 +475,7 @@ export function Lightbox({
     }
 
     const handlePointerMove = (e: PointerEvent) => {
+      didDragRef.current = true;
       const dx = e.clientX - dragStartRef.current.x;
       const dy = e.clientY - dragStartRef.current.y;
       setPan({
@@ -514,7 +526,7 @@ export function Lightbox({
         style,
       )}
       {...props}>
-      <div {...stylex.props(styles.container)}>
+      <div ref={containerRef} {...stylex.props(styles.container)}>
         {/* Close button */}
         <div {...stylex.props(styles.closeButton)}>
           <IconButton
@@ -532,7 +544,11 @@ export function Lightbox({
         {isGallery && (
           <div {...stylex.props(styles.navButton, styles.navPrev)}>
             <IconButton
-              icon={<Icon icon="chevronLeft" size="sm" color="inherit" />}
+              icon={
+                <span {...stylex.props(rtlStyles.mirror)}>
+                  <Icon icon="chevronLeft" size="sm" color="inherit" />
+                </span>
+              }
               label={t('@astryx.lightbox.previous')}
               variant="ghost"
               isDisabled={!canPrev}
@@ -587,7 +603,11 @@ export function Lightbox({
         {isGallery && (
           <div {...stylex.props(styles.navButton, styles.navNext)}>
             <IconButton
-              icon={<Icon icon="chevronRight" size="sm" color="inherit" />}
+              icon={
+                <span {...stylex.props(rtlStyles.mirror)}>
+                  <Icon icon="chevronRight" size="sm" color="inherit" />
+                </span>
+              }
               label={t('@astryx.lightbox.next')}
               variant="ghost"
               isDisabled={!canNext}