@astryxdesign/core 0.1.6 → 0.1.7-canary.04cd8f7

package/src/Field/Field.doc.mjs

@@ -95,7 +95,7 @@ export const docs = {
     {
       name: 'labelIcon',
       type: 'IconType',
-      description: 'Icon to display before the label text. See `npx astryx docs icons` for valid semantic names.',
+      description: 'Icon to display before the label text. See `astryx docs icons` for valid semantic names.',
     },
     {
       name: 'labelTooltip',
@@ -104,8 +104,8 @@ export const docs = {
     },
     {
       name: 'status',
-      type: 'FieldStatus',
-      description: 'Status indicator with type and optional message. When message is set, displays a colored status box.',
+      type: "{type: 'warning' | 'error' | 'success', message?: string, messageID?: string}",
+      description: 'Status indicator with type and optional message. When message is set, displays a colored status box. messageID is for wiring aria-describedby on the input.',
     },
     {
       name: 'statusVariant',

package/src/Field/FieldLabel.doc.mjs

@@ -48,7 +48,7 @@ export const docs = {
     {
       name: 'labelIcon',
       type: 'IconType',
-      description: 'Icon before the label text. See `npx astryx docs icons` for valid semantic names.',
+      description: 'Icon before the label text. See `astryx docs icons` for valid semantic names.',
     },
     {
       name: 'labelTooltip',

package/src/FileInput/FileInput.test.tsx

@@ -10,7 +10,13 @@
  */
 
 import {describe, it, expect, vi, afterEach, beforeEach} from 'vitest';
-import {render, screen, fireEvent, waitFor} from '@testing-library/react';
+import {
+  render,
+  screen,
+  fireEvent,
+  createEvent,
+  waitFor,
+} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {FileInput} from './FileInput';
 import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
@@ -588,6 +594,39 @@ describe('FileInput', () => {
       expect(screen.getByText('Choose file')).toBeInTheDocument();
     });
 
+    it('keeps the drag-over state while dragging over the dropzone children', () => {
+      render(
+        <FileInput
+          label="Upload"
+          value={null}
+          onChange={() => {}}
+          mode="dropzone"
+        />,
+      );
+      const dropzone = screen.getByRole('button', {name: 'Upload'});
+      fireEvent.dragEnter(dropzone);
+      expect(screen.getByText('Drop files here')).toBeInTheDocument();
+
+      // Moving from the container onto one of its own children fires a
+      // dragleave on the container with the child as relatedTarget — the
+      // highlight must not flicker off while still inside the dropzone.
+      // (jsdom's DragEvent init drops relatedTarget, so set it directly.)
+      const child = screen.getByText('Drop files here');
+      const leaveToChild = createEvent.dragLeave(dropzone);
+      Object.defineProperty(leaveToChild, 'relatedTarget', {value: child});
+      fireEvent(dropzone, leaveToChild);
+      expect(screen.getByText('Drop files here')).toBeInTheDocument();
+
+      // Actually leaving the dropzone ends the drag-over state.
+      const leaveToOutside = createEvent.dragLeave(dropzone);
+      Object.defineProperty(leaveToOutside, 'relatedTarget', {
+        value: document.body,
+      });
+      fireEvent(dropzone, leaveToOutside);
+      expect(screen.queryByText('Drop files here')).not.toBeInTheDocument();
+      expect(screen.getByText('Choose file')).toBeInTheDocument();
+    });
+
     it('displays file name in dropzone mode', () => {
       const file = createFile('doc.pdf', 100, 'application/pdf');
       render(

package/src/FileInput/FileInput.tsx

@@ -55,6 +55,7 @@ import {mergeProps, mergeRefs} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import type {SizeValue} from '../utils/types';
 import {themeProps} from '../utils/themeProps';
+import {useTranslator} from '../i18n';
 
 function formatFileSize(bytes: number): string {
   if (bytes < 1024) {
@@ -425,6 +426,7 @@ export function FileInput({
   ref,
   ...rest
 }: FileInputProps) {
+  const t = useTranslator();
   const id = useId();
   const descriptionID = useId();
   const statusMessageID = useId();
@@ -607,6 +609,15 @@ export function FileInput({
   const handleDragLeave = useCallback((e: DragEvent) => {
     e.preventDefault();
     e.stopPropagation();
+    // Moving over the dropzone's own children (icon, text) fires dragleave on
+    // the container too — only a leave that actually exits the dropzone ends
+    // the drag-over state, otherwise the highlight flickers mid-drag.
+    if (
+      e.relatedTarget instanceof Node &&
+      e.currentTarget.contains(e.relatedTarget)
+    ) {
+      return;
+    }
     setIsDragOver(false);
   }, []);
 
@@ -774,7 +785,7 @@ export function FileInput({
         />
         {isDropzone ? renderDropzoneContent() : renderCompactContent()}
         {hasFiles && !isDisabled && !isLoading && (
-          <InputClearButton label={`Clear ${label}`} onClick={handleClear} />
+          <InputClearButton label={t('@astryx.fileInput.clearLabel', {label})} onClick={handleClear} />
         )}
       </div>
       <div

package/src/Grid/Grid.doc.mjs

@@ -60,28 +60,28 @@ export const docs = {
     },
     {
       name: 'gap',
-      type: 'SpacingStep',
+      type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
       description: 'Spacing between all items.',
     },
     {
       name: 'rowGap',
-      type: 'SpacingStep',
+      type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
       description: 'Row spacing; overrides `gap` for the row axis.',
     },
     {
       name: 'columnGap',
-      type: 'SpacingStep',
+      type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
       description: 'Column spacing; overrides `gap` for the column axis.',
     },
     {
       name: 'align',
-      type: 'GridAlignment',
+      type: "'start' | 'center' | 'end' | 'stretch'",
       description: 'Vertical alignment of items.',
       default: "'stretch'",
     },
     {
       name: 'justify',
-      type: 'GridAlignment',
+      type: "'start' | 'center' | 'end' | 'stretch'",
       description: 'Horizontal alignment of items.',
       default: "'stretch'",
     },

package/src/Icon/Icon.test.tsx

@@ -96,6 +96,52 @@ describe('Icon', () => {
     expect(screen.getByTestId('icon')).toBeInTheDocument();
   });
 
+  it('sizes component-mode icons in rem so they scale with root font-size', () => {
+    const sizes = {
+      xsm: '0.75rem',
+      sm: '1rem',
+      md: '1.25rem',
+      lg: '1.5rem',
+    } as const;
+    for (const [size, expected] of Object.entries(sizes)) {
+      const {unmount} = render(
+        <Icon
+          icon={TestIcon}
+          size={size as keyof typeof sizes}
+          data-testid="icon"
+        />,
+      );
+      const style = getComputedStyle(screen.getByTestId('icon'));
+      expect(style.width).toBe(expected);
+      expect(style.height).toBe(expected);
+      unmount();
+    }
+  });
+
+  it('sizes registry (string-mode) icons in rem, including fontSize', () => {
+    const sizes = {
+      xsm: '0.75rem',
+      sm: '1rem',
+      md: '1.25rem',
+      lg: '1.5rem',
+    } as const;
+    for (const [size, expected] of Object.entries(sizes)) {
+      const {unmount} = render(
+        <Icon
+          icon="check"
+          size={size as keyof typeof sizes}
+          data-testid="icon"
+        />,
+      );
+      const style = getComputedStyle(screen.getByTestId('icon'));
+      expect(style.width).toBe(expected);
+      expect(style.height).toBe(expected);
+      // fontSize is expressed in rem so 1em-based registry icons scale too.
+      expect(style.fontSize).toBe(expected);
+      unmount();
+    }
+  });
+
   it('forwards ref correctly', () => {
     const ref = vi.fn();
     render(<Icon icon={TestIcon} ref={ref} />);

package/src/Icon/Icon.tsx

@@ -111,51 +111,64 @@ const colorStyles = stylex.create({
 /**
  * Size styles for direct SVG icon components.
  * Uses width/height only — SVG components handle their own viewBox scaling.
+ *
+ * Sizes are expressed in `rem` (relative to the root font-size) so icons scale
+ * in step with text when the document font-size changes, matching the rest of
+ * the design system's rem-based type scale. Values are the px-equivalents at a
+ * 16px root: 12px → 0.75rem, 16px → 1rem, 20px → 1.25rem, 24px → 1.5rem.
  */
 const sizeStyles = stylex.create({
   xsm: {
-    width: 12,
-    height: 12,
+    width: '0.75rem',
+    height: '0.75rem',
   },
   sm: {
-    width: 16,
-    height: 16,
+    width: '1rem',
+    height: '1rem',
   },
   md: {
-    width: 20,
-    height: 20,
+    width: '1.25rem',
+    height: '1.25rem',
   },
   lg: {
-    width: 24,
-    height: 24,
+    width: '1.5rem',
+    height: '1.5rem',
   },
 });
 
 /**
  * Size styles for string-based (registry) icons.
  * Includes fontSize so that 1em-based icons from the registry scale correctly.
+ *
+ * Expressed in `rem` for the same reason as {@link sizeStyles} — icons track the
+ * root font-size instead of being locked to absolute pixels.
  */
 const spanSizeStyles = stylex.create({
+  /* eslint-disable @astryx/no-hardcoded-styles -- fontSize here sizes 1em-based
+     registry SVGs to the icon box; icons use their own 12/16/20/24 scale, not
+     the 14px-anchored textSizeVars type scale. Values are rem so icons track
+     the root font-size. */
   xsm: {
-    width: 12,
-    height: 12,
-    fontSize: 12,
+    width: '0.75rem',
+    height: '0.75rem',
+    fontSize: '0.75rem',
   },
   sm: {
-    width: 16,
-    height: 16,
-    fontSize: 16,
+    width: '1rem',
+    height: '1rem',
+    fontSize: '1rem',
   },
   md: {
-    width: 20,
-    height: 20,
-    fontSize: 20,
+    width: '1.25rem',
+    height: '1.25rem',
+    fontSize: '1.25rem',
   },
   lg: {
-    width: 24,
-    height: 24,
-    fontSize: 24,
+    width: '1.5rem',
+    height: '1.5rem',
+    fontSize: '1.5rem',
   },
+  /* eslint-enable @astryx/no-hardcoded-styles */
 });
 
 // =============================================================================
@@ -194,10 +207,10 @@ export interface IconProps extends Omit<
   color?: IconColor;
   /**
    * The size of the icon.
-   * - 'xsm': 12px
-   * - 'sm': 16px
-   * - 'md': 20px
-   * - 'lg': 24px
+   * - 'xsm': 0.75rem (12px at a 16px root)
+   * - 'sm': 1rem (16px at a 16px root)
+   * - 'md': 1.25rem (20px at a 16px root)
+   * - 'lg': 1.5rem (24px at a 16px root)
    * @default 'md'
    */
   size?: IconSize;

package/src/InputGroup/InputGroup.doc.mjs

@@ -76,7 +76,7 @@ export const docs = {
     },
     {
       name: 'status',
-      type: 'InputStatus',
+      type: "{type: 'warning' | 'error' | 'success', message?: string}",
       description: 'Status indicator applied to the group border.',
     },
     {

package/src/Kbd/Kbd.test.tsx

@@ -119,4 +119,30 @@ describe('Kbd', () => {
     expect(screen.getByText('⇧')).toBeInTheDocument();
     expect(screen.getByText('+')).toBeInTheDocument();
   });
+
+  it('keeps the computed role and aria-label when unrelated rest props are spread', () => {
+    render(<Kbd keys="mod+k" data-testid="kbd" id="shortcut" />);
+    const el = screen.getByTestId('kbd');
+    // Pass-through attributes land on the wrapper...
+    expect(el).toHaveAttribute('id', 'shortcut');
+    // ...without disturbing the computed accessibility contract.
+    expect(el).toHaveAttribute('role', 'img');
+    expect(el).toHaveAttribute('aria-label', 'Control + K');
+  });
+
+  it('computed role and aria-label win over consumer-passed overrides', () => {
+    // Contract props the component computes must not be clobbered by
+    // pass-through attributes: {...rest} is spread before role/aria-label.
+    render(
+      <Kbd
+        keys="mod+k"
+        role="presentation"
+        aria-label="custom"
+        data-testid="kbd"
+      />,
+    );
+    const el = screen.getByTestId('kbd');
+    expect(el).toHaveAttribute('role', 'img');
+    expect(el).toHaveAttribute('aria-label', 'Control + K');
+  });
 });

package/src/Kbd/Kbd.tsx

@@ -188,10 +188,10 @@ export function Kbd({keys, ref, xstyle, className, style, ...rest}: KbdProps) {
 
   return (
     <span
+      {...rest}
       ref={ref}
       role="img"
       aria-label={accessibleName}
-      {...rest}
       {...mergeProps(
         themeProps('kbd'),
         stylex.props(styles.wrapper, xstyle),

package/src/Layer/useLayer.doc.mjs

@@ -72,13 +72,14 @@ export const docs = {
     {
       name: 'id',
       type: 'string',
-      description: 'Unique ID for aria-describedby or other ARIA relationships.',
+      description:
+        'Unique ID for aria-describedby or other ARIA relationships.',
     },
     {
       name: 'render',
       type: '(children: ReactNode, props: ContextRenderProps | FixedRenderProps) => ReactNode',
       description:
-        'Render function for the popover element. Pass placement/alignment in context mode or x/y in fixed mode. Placement/alignment are logical: they map to the self-* position-area keyword family, which resolves against the popover\'s own inherited direction, so RTL contexts mirror automatically in pure CSS. Pass `positioning: "custom"` in context mode to author position styles yourself via `style` (e.g. explicit anchor() insets or an anchor-size() cover): the hook keeps the popover behavior and position-anchor wiring but derives no position styles — including the automatic RTL mirroring, which becomes your responsibility. In context mode, pass `as: "span"` to render an inline-safe layer (e.g. inside a paragraph). The layer renders inline in the React tree; the Popover API promotes it to the top layer when shown, so it escapes ancestor clipping and stacking without a portal.',
+        'Render function for the popover element. Pass placement/alignment in context mode or x/y in fixed mode. Placement/alignment are logical: they map to the self-* position-area keyword family, which resolves against the popover\'s own inherited direction, so RTL contexts mirror automatically in pure CSS. Pass `positioning: "custom"` in context mode to author position styles yourself via `style` (e.g. explicit anchor() insets or an anchor-size() cover): the hook keeps the popover behavior and position-anchor wiring but derives no position styles, including the automatic RTL mirroring, which becomes your responsibility. In context mode, pass `as: "span"` to render an inline-safe layer (e.g. inside a paragraph). The layer renders inline in the React tree; the Popover API promotes it to the top layer when shown, so it escapes ancestor clipping and stacking without a portal. When the layer would overflow the viewport, position-try fallbacks flip it to the opposite side; centered layers additionally slide along the alignment axis (span fallbacks) so they stay on-screen near viewport edges.',
     },
   ],
   usage: {
@@ -130,7 +131,7 @@ export const docsDense = {
     hide: 'hide layer.',
     isOpen: 'whether layer is open.',
     id: 'unique ARIA id.',
-    render: 'renders popover element; pass placement/alignment or x/y. Placement/alignment logical: mapped to self-* position-area keywords resolved against the popover\'s inherited direction (RTL mirrors in pure CSS). `positioning: "custom"` (context mode) = author position styles yourself via `style`; keeps popover behavior + position-anchor wiring, derives nothing (incl. RTL mirroring — yours). Context mode accepts `as: "span"` for inline-safe layers. Renders inline; the Popover API top layer escapes clipping/stacking without a portal.',
+    render: 'renders popover element; pass placement/alignment or x/y. Placement/alignment logical: mapped to self-* position-area keywords resolved against the popover\'s inherited direction (RTL mirrors in pure CSS). `positioning: "custom"` (context mode) = author position styles yourself via `style`; keeps popover behavior + position-anchor wiring, derives nothing (incl. RTL mirroring, which becomes yours). Context mode accepts `as: "span"` for inline-safe layers. Renders inline; the Popover API top layer escapes clipping/stacking without a portal. Viewport overflow: flips to opposite side; centered layers also slide along the alignment axis (span fallbacks).',
   },
   usage: {
     description:
@@ -138,11 +139,13 @@ export const docsDense = {
     bestPractices: [
       {
         guidance: true,
-        description: 'Use context mode for trigger-anchored overlays; fixed mode for explicit coordinates.',
+        description:
+          'Use context mode for trigger-anchored overlays; fixed mode for explicit coordinates.',
       },
       {
         guidance: true,
-        description: 'Build on Popover/HoverCard/Tooltip for common overlay patterns.',
+        description:
+          'Build on Popover/HoverCard/Tooltip for common overlay patterns.',
       },
       {
         guidance: true,

package/src/Layer/useLayer.test.tsx

@@ -12,7 +12,7 @@
 import {describe, it, expect, vi, afterEach} from 'vitest';
 import {render, act} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
-import {useLayer} from './useLayer';
+import {useLayer, getPositionTryFallbacks} from './useLayer';
 import type {
   LayerPlacement,
   LayerAlignment,
@@ -33,6 +33,141 @@ function LayerHarness({
   return <>{layer.render(<span>Layer content</span>, {x: 0, y: 0})}</>;
 }
 
+/**
+ * Context-mode harness: renders a trigger plus the layer so tests can assert
+ * on the anchor-positioning styles applied to the popover element.
+ */
+function ContextLayerHarness({
+  placement,
+  alignment,
+}: {
+  placement?: LayerPlacement;
+  alignment?: LayerAlignment;
+}) {
+  const layer = useLayer({mode: 'context'});
+  return (
+    <>
+      <button type="button" ref={layer.ref}>
+        Trigger
+      </button>
+      {layer.render(<span>Layer content</span>, {placement, alignment})}
+    </>
+  );
+}
+
+describe('getPositionTryFallbacks (issue #3671)', () => {
+  const FLIPS = 'flip-block, flip-inline, flip-block flip-inline';
+
+  it('appends inline span fallbacks for centered above/below layers so inline overflow can resolve (flip-inline is a no-op on center)', () => {
+    expect(getPositionTryFallbacks('above', 'center')).toBe(
+      `${FLIPS}, top span-left, top span-right, bottom span-left, bottom span-right`,
+    );
+    expect(getPositionTryFallbacks('below', 'center')).toBe(
+      `${FLIPS}, bottom span-left, bottom span-right, top span-left, top span-right`,
+    );
+  });
+
+  it('appends block span fallbacks for centered start/end layers so block overflow can resolve (flip-block is a no-op on center)', () => {
+    expect(getPositionTryFallbacks('start', 'center')).toBe(
+      `${FLIPS}, left span-top, left span-bottom, right span-top, right span-bottom`,
+    );
+    expect(getPositionTryFallbacks('end', 'center')).toBe(
+      `${FLIPS}, right span-top, right span-bottom, left span-top, left span-bottom`,
+    );
+  });
+
+  it('keeps flip-only fallbacks for non-centered alignments (flips already resolve overflow there)', () => {
+    const nonCentered: [LayerPlacement, LayerAlignment][] = [
+      ['above', 'start'],
+      ['above', 'end'],
+      ['below', 'start'],
+      ['below', 'end'],
+      ['start', 'start'],
+      ['start', 'end'],
+      ['end', 'start'],
+      ['end', 'end'],
+    ];
+    for (const [placement, alignment] of nonCentered) {
+      expect(getPositionTryFallbacks(placement, alignment)).toBe(FLIPS);
+    }
+  });
+
+  it('defaults to above/center when called without arguments (matches renderContext defaults)', () => {
+    expect(getPositionTryFallbacks()).toBe(
+      getPositionTryFallbacks('above', 'center'),
+    );
+    expect(getPositionTryFallbacks(undefined, undefined)).toBe(
+      `${FLIPS}, top span-left, top span-right, bottom span-left, bottom span-right`,
+    );
+  });
+
+  it('produces well-formed, duplicate-free lists with flips first and axis-correct spans for every placement/alignment combo', () => {
+    const placements: LayerPlacement[] = ['above', 'below', 'start', 'end'];
+    const alignments: LayerAlignment[] = ['start', 'center', 'end'];
+    const spanPattern: Record<LayerPlacement, RegExp> = {
+      above: /^(top|bottom) span-(left|right)$/,
+      below: /^(top|bottom) span-(left|right)$/,
+      start: /^(left|right) span-(top|bottom)$/,
+      end: /^(left|right) span-(top|bottom)$/,
+    };
+
+    for (const placement of placements) {
+      for (const alignment of alignments) {
+        const list = getPositionTryFallbacks(placement, alignment);
+        const items = list.split(', ');
+
+        expect(items.slice(0, 3)).toEqual([
+          'flip-block',
+          'flip-inline',
+          'flip-block flip-inline',
+        ]);
+        expect(new Set(items).size).toBe(items.length);
+        for (const item of items.slice(3)) {
+          expect(item).toMatch(spanPattern[placement]);
+        }
+        expect(items.length).toBe(alignment === 'center' ? 7 : 3);
+      }
+    }
+  });
+
+  it('updates the fallback list when placement/alignment props change on re-render', () => {
+    const {container, rerender} = render(
+      <ContextLayerHarness placement="above" alignment="center" />,
+    );
+    const layerEl = container.querySelector('[popover]') as HTMLElement;
+    expect(layerEl.style.positionTryFallbacks).toContain('top span-left');
+
+    rerender(<ContextLayerHarness placement="above" alignment="start" />);
+    expect(layerEl.style.positionTryFallbacks).toBe(FLIPS);
+
+    rerender(<ContextLayerHarness placement="start" alignment="center" />);
+    expect(layerEl.style.positionTryFallbacks).toBe(
+      `${FLIPS}, left span-top, left span-bottom, right span-top, right span-bottom`,
+    );
+  });
+
+  it('does not apply anchor fallbacks in fixed mode (manual coordinates)', () => {
+    function FixedHarness() {
+      const layer = useLayer({mode: 'fixed'});
+      return <>{layer.render(<span>Fixed content</span>, {x: 10, y: 20})}</>;
+    }
+    const {container} = render(<FixedHarness />);
+    const layerEl = container.querySelector('[popover]') as HTMLElement;
+    expect(layerEl.style.positionTryFallbacks ?? '').toBeFalsy();
+    expect(layerEl.style.left).toBe('10px');
+    expect(layerEl.style.top).toBe('20px');
+  });
+
+  it('applies span fallbacks to the rendered popover for the default (above/center) layer', () => {
+    const {container} = render(<ContextLayerHarness />);
+    const layerEl = container.querySelector('[popover]') as HTMLElement;
+    expect(layerEl).not.toBeNull();
+    expect(layerEl.style.positionTryFallbacks).toBe(
+      `${FLIPS}, top span-left, top span-right, bottom span-left, bottom span-right`,
+    );
+  });
+});
+
 describe('useLayer', () => {
   const originalShowPopover = HTMLElement.prototype.showPopover;
   const originalHidePopover = HTMLElement.prototype.hidePopover;

package/src/Layer/useLayer.tsx

@@ -320,6 +320,36 @@ function getPositionArea(
   return inline; // center
 }
 
+/**
+ * Compute the `position-try-fallbacks` list for a placement/alignment pair.
+ *
+ * Flips alone cannot rescue a centered layer — flipping along the alignment
+ * axis maps center → center, so overflow on that axis renders clipped
+ * (#3671). Centered alignments therefore append span-based fallbacks letting
+ * the browser slide the layer along the alignment axis as a last resort
+ * (same-side spans first). Flips already resolve non-centered alignments.
+ */
+export function getPositionTryFallbacks(
+  placement: LayerPlacement = 'above',
+  alignment: LayerAlignment = 'center',
+): string {
+  const flips = 'flip-block, flip-inline, flip-block flip-inline';
+
+  if (alignment !== 'center') {
+    return flips;
+  }
+
+  if (placement === 'above' || placement === 'below') {
+    const [same, opposite] =
+      placement === 'above' ? ['top', 'bottom'] : ['bottom', 'top'];
+    return `${flips}, ${same} span-left, ${same} span-right, ${opposite} span-left, ${opposite} span-right`;
+  }
+
+  const [same, opposite] =
+    placement === 'start' ? ['left', 'right'] : ['right', 'left'];
+  return `${flips}, ${same} span-top, ${same} span-bottom, ${opposite} span-top, ${opposite} span-bottom`;
+}
+
 /**
  * Core layer hook that handles popover behavior and positioning.
  *
@@ -512,8 +542,10 @@ export function useLayer(
           : {
               positionAnchor: anchorId,
               positionArea: getPositionArea(placement, alignment),
-              positionTryFallbacks:
-                'flip-block, flip-inline, flip-block flip-inline',
+              positionTryFallbacks: getPositionTryFallbacks(
+                placement,
+                alignment,
+              ),
             };
 
       const stylexResult = stylex.props(styles.base, xstyle);

package/src/Lightbox/Lightbox.doc.mjs

@@ -22,8 +22,13 @@ export const docs = {
     },
     {
       name: 'media',
+      // Left as the named type on purpose: the shape carries `caption?:
+      // ReactNode`, so spelling it out makes the docsite playground parse the
+      // whole prop as an editable *string*, which would feed the preview text
+      // where a media object belongs. The shape and its legal values live in
+      // the description instead (#1645).
       type: 'LightboxMedia | LightboxMedia[]',
-      description: 'Media to display. Pass a single object for one item, or an array for gallery mode with prev/next navigation. Each item has src, alt, optional caption and type.',
+      description: "Media to display. Pass a single object for one item, or an array for gallery mode with prev/next navigation. Each item is {src: string, alt: string, caption?: ReactNode, type?: 'image' | 'video'}; type defaults to 'image', and zoom/pan is disabled for 'video'.",
       required: true,
     },
     {
@@ -100,7 +105,7 @@ export const docsZh = {
     {
       name: 'media',
       type: 'LightboxMedia | LightboxMedia[]',
-      description: '要显示的媒体。传入单个对象或数组（用于画廊模式的上一张/下一张导航）。',
+      description: "要显示的媒体。传入单个对象或数组（用于画廊模式的上一张/下一张导航）。每项为 {src, alt, caption?, type?: 'image' | 'video'}；type 默认为 'image'，'video' 禁用缩放/平移。",
       required: true,
     },
     {