@astryxdesign/core 0.1.4 → 0.1.5-canary.76e6697

package/src/Layout/LayoutContent.doc.mjs

@@ -14,6 +14,12 @@ export const docs = {
       type: 'ReactNode',
       description: 'Content.',
     },
+    {
+      name: 'padding',
+      type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
+      description:
+        'Internal padding using the spacing scale. Overrides the default padding from the layout container.',
+    },
     {
       name: 'isScrollable',
       type: 'boolean',
@@ -44,6 +50,11 @@ export const docsZh = {
       type: 'ReactNode',
       description: '内容。',
     },
+    {
+      name: 'padding',
+      type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
+      description: '使用间距比例的内边距。覆盖布局容器的默认内边距。',
+    },
     {
       name: 'isScrollable',
       type: 'boolean',
@@ -70,6 +81,7 @@ export const docsDense = {
   description: 'Scrollable main content area.',
   propDescriptions: {
     children: 'Content.',
+    padding: 'Internal padding on spacing scale. Overrides layout container default.',
     isScrollable: 'Enable scrollable overflow.',
     label: 'Accessible label for landmark element.',
     role: 'ARIA landmark role.',

package/src/Layout/LayoutPanel.doc.mjs

@@ -20,6 +20,12 @@ export const docs = {
       description: 'Border on the appropriate edge.',
       default: 'false',
     },
+    {
+      name: 'padding',
+      type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
+      description:
+        'Internal padding using the spacing scale. Overrides the default padding from the layout container.',
+    },
     {
       name: 'isScrollable',
       type: 'boolean',
@@ -36,6 +42,18 @@ export const docs = {
       type: 'AriaRole',
       description: 'ARIA landmark role.',
     },
+    {
+      name: 'width',
+      type: 'number | string',
+      description:
+        'Width of the panel. Numbers are treated as pixels, strings are used as-is. Ignored when resizable is provided; the hook controls width.',
+    },
+    {
+      name: 'resizable',
+      type: 'ResizableProps',
+      description:
+        'Resize props from useResizable(). When provided, the hook drives the panel width and a ResizeHandle should be placed adjacent to the panel.',
+    },
   ],
 };
 
@@ -56,6 +74,11 @@ export const docsZh = {
       description: '相应边缘的边框。',
       default: 'false',
     },
+    {
+      name: 'padding',
+      type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
+      description: '使用间距比例的内边距。覆盖布局容器的默认内边距。',
+    },
     {
       name: 'isScrollable',
       type: 'boolean',
@@ -72,6 +95,18 @@ export const docsZh = {
       type: 'AriaRole',
       description: 'ARIA 地标角色。',
     },
+    {
+      name: 'width',
+      type: 'number | string',
+      description:
+        '面板宽度。数字按像素处理，字符串按原样使用。提供 resizable 时忽略，宽度由 hook 控制。',
+    },
+    {
+      name: 'resizable',
+      type: 'ResizableProps',
+      description:
+        '来自 useResizable() 的调整大小属性。提供时面板宽度由 hook 驱动，应在面板旁放置 ResizeHandle。',
+    },
   ],
 };
 
@@ -83,8 +118,13 @@ export const docsDense = {
   propDescriptions: {
     children: 'Panel content.',
     hasDivider: 'Border on appropriate edge.',
+    padding: 'Internal padding on spacing scale. Overrides layout container default.',
     isScrollable: 'Enable scrollable overflow.',
     label: 'Accessible label for landmark element.',
     role: 'ARIA landmark role.',
+    width:
+      'Panel width. Numbers = pixels, strings as-is. Ignored when resizable provided; hook controls width.',
+    resizable:
+      'Resize props from useResizable(). Hook drives panel width; place ResizeHandle adjacent.',
   },
 };

package/src/Layout/LayoutSlots.test.tsx

@@ -0,0 +1,364 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file LayoutSlots.test.tsx
+ * @input Uses vitest, @testing-library/react, Layout slot components
+ * @output Characterization tests for LayoutHeader, LayoutFooter,
+ *   LayoutContent and LayoutPanel
+ * @position Testing; validates the slot primitives' rendering, landmark roles,
+ *   divider reflection, sizing and context-driven behavior
+ *
+ * SYNC: When LayoutHeader/LayoutFooter/LayoutContent/LayoutPanel change,
+ * update tests to match new behavior
+ */
+
+import {describe, it, expect} from 'vitest';
+import {render, screen} from '@testing-library/react';
+import {createRef} from 'react';
+import {Layout} from './Layout';
+import {LayoutHeader} from './LayoutHeader';
+import {LayoutFooter} from './LayoutFooter';
+import {LayoutContent} from './LayoutContent';
+import {LayoutPanel} from './LayoutPanel';
+import {LayoutDividerContext} from './LayoutDividerContext';
+import {useResizable} from '../Resizable/useResizable';
+
+// =============================================================================
+// LayoutHeader
+// =============================================================================
+
+describe('LayoutHeader', () => {
+  it('renders its children', () => {
+    render(<LayoutHeader>Page title</LayoutHeader>);
+    expect(screen.getByText('Page title')).toBeInTheDocument();
+  });
+
+  it('carries the astryx-layout-header class', () => {
+    const {container} = render(<LayoutHeader>H</LayoutHeader>);
+    expect(
+      container.querySelector('.astryx-layout-header'),
+    ).toBeInTheDocument();
+  });
+
+  it('exposes a landmark role and accessible name', () => {
+    render(
+      <LayoutHeader role="banner" label="Site header">
+        H
+      </LayoutHeader>,
+    );
+    expect(
+      screen.getByRole('banner', {name: 'Site header'}),
+    ).toBeInTheDocument();
+  });
+
+  it('omits data-divider by default', () => {
+    const {container} = render(<LayoutHeader>H</LayoutHeader>);
+    expect(
+      container
+        .querySelector('.astryx-layout-header')
+        ?.hasAttribute('data-divider'),
+    ).toBe(false);
+  });
+
+  it('reflects hasDivider as data-divider="true"', () => {
+    const {container} = render(<LayoutHeader hasDivider>H</LayoutHeader>);
+    expect(
+      container
+        .querySelector('.astryx-layout-header')
+        ?.getAttribute('data-divider'),
+    ).toBe('true');
+  });
+
+  it('inherits the divider default from LayoutDividerContext', () => {
+    const {container} = render(
+      <LayoutDividerContext value={{defaultHasDividers: true}}>
+        <LayoutHeader>H</LayoutHeader>
+      </LayoutDividerContext>,
+    );
+    expect(
+      container
+        .querySelector('.astryx-layout-header')
+        ?.getAttribute('data-divider'),
+    ).toBe('true');
+  });
+
+  it('an explicit hasDivider={false} overrides an inherited true default', () => {
+    const {container} = render(
+      <LayoutDividerContext value={{defaultHasDividers: true}}>
+        <LayoutHeader hasDivider={false}>H</LayoutHeader>
+      </LayoutDividerContext>,
+    );
+    expect(
+      container
+        .querySelector('.astryx-layout-header')
+        ?.hasAttribute('data-divider'),
+    ).toBe(false);
+  });
+
+  it('applies a numeric height to the element style', () => {
+    const {container} = render(<LayoutHeader height={64}>H</LayoutHeader>);
+    const el = container.querySelector('.astryx-layout-header') as HTMLElement;
+    expect(el.getAttribute('style') ?? '').toContain('64px');
+  });
+
+  it('forwards ref to the outer element', () => {
+    const ref = createRef<HTMLDivElement>();
+    render(<LayoutHeader ref={ref}>H</LayoutHeader>);
+    expect(ref.current).toBeInstanceOf(HTMLDivElement);
+    expect(ref.current?.className).toContain('astryx-layout-header');
+  });
+
+  it('merges a caller className', () => {
+    const {container} = render(
+      <LayoutHeader className="hdr-custom">H</LayoutHeader>,
+    );
+    const el = container.querySelector('.astryx-layout-header') as HTMLElement;
+    expect(el.className).toContain('hdr-custom');
+  });
+
+  it('renders children in an inner wrapper (padding owner), not directly on the root', () => {
+    const {container} = render(<LayoutHeader>Inner</LayoutHeader>);
+    const root = container.querySelector(
+      '.astryx-layout-header',
+    ) as HTMLElement;
+    // Children live in a nested inner wrapper (the padding owner), not on the
+    // divider-owning root itself.
+    const inner = screen.getByText('Inner');
+    expect(inner).not.toBe(root);
+    expect(inner.parentElement).toBe(root);
+    expect(root).toContainElement(inner);
+  });
+});
+
+// =============================================================================
+// LayoutFooter
+// =============================================================================
+
+describe('LayoutFooter', () => {
+  it('renders its children', () => {
+    render(<LayoutFooter>Actions</LayoutFooter>);
+    expect(screen.getByText('Actions')).toBeInTheDocument();
+  });
+
+  it('carries the astryx-layout-footer class', () => {
+    const {container} = render(<LayoutFooter>F</LayoutFooter>);
+    expect(
+      container.querySelector('.astryx-layout-footer'),
+    ).toBeInTheDocument();
+  });
+
+  it('exposes a landmark role and accessible name', () => {
+    render(
+      <LayoutFooter role="contentinfo" label="Page footer">
+        F
+      </LayoutFooter>,
+    );
+    expect(
+      screen.getByRole('contentinfo', {name: 'Page footer'}),
+    ).toBeInTheDocument();
+  });
+
+  it('omits data-divider by default and reflects hasDivider when set', () => {
+    const {container, rerender} = render(<LayoutFooter>F</LayoutFooter>);
+    const sel = '.astryx-layout-footer';
+    expect(container.querySelector(sel)?.hasAttribute('data-divider')).toBe(
+      false,
+    );
+    rerender(<LayoutFooter hasDivider>F</LayoutFooter>);
+    expect(container.querySelector(sel)?.getAttribute('data-divider')).toBe(
+      'true',
+    );
+  });
+
+  it('inherits the divider default from context', () => {
+    const {container} = render(
+      <LayoutDividerContext value={{defaultHasDividers: true}}>
+        <LayoutFooter>F</LayoutFooter>
+      </LayoutDividerContext>,
+    );
+    expect(
+      container
+        .querySelector('.astryx-layout-footer')
+        ?.getAttribute('data-divider'),
+    ).toBe('true');
+  });
+
+  it('forwards ref to the outer element', () => {
+    const ref = createRef<HTMLDivElement>();
+    render(<LayoutFooter ref={ref}>F</LayoutFooter>);
+    expect(ref.current).toBeInstanceOf(HTMLDivElement);
+    expect(ref.current?.className).toContain('astryx-layout-footer');
+  });
+});
+
+// =============================================================================
+// LayoutContent
+// =============================================================================
+
+describe('LayoutContent', () => {
+  it('renders its children', () => {
+    render(<LayoutContent>Body</LayoutContent>);
+    expect(screen.getByText('Body')).toBeInTheDocument();
+  });
+
+  it('carries the astryx-layout-content class', () => {
+    const {container} = render(<LayoutContent>C</LayoutContent>);
+    expect(
+      container.querySelector('.astryx-layout-content'),
+    ).toBeInTheDocument();
+  });
+
+  it('exposes the main landmark role with an accessible name', () => {
+    render(
+      <LayoutContent role="main" label="Main content">
+        C
+      </LayoutContent>,
+    );
+    expect(
+      screen.getByRole('main', {name: 'Main content'}),
+    ).toBeInTheDocument();
+  });
+
+  it('forwards ref to the element', () => {
+    const ref = createRef<HTMLDivElement>();
+    render(<LayoutContent ref={ref}>C</LayoutContent>);
+    expect(ref.current).toBeInstanceOf(HTMLDivElement);
+    expect(ref.current?.className).toContain('astryx-layout-content');
+  });
+
+  it('merges caller className and inline style', () => {
+    const {container} = render(
+      <LayoutContent className="body-custom" style={{color: 'rgb(1, 2, 3)'}}>
+        C
+      </LayoutContent>,
+    );
+    const el = container.querySelector('.astryx-layout-content') as HTMLElement;
+    expect(el.className).toContain('body-custom');
+    expect(el.style.color).toBe('rgb(1, 2, 3)');
+  });
+
+  it('renders correctly as the content slot of a Layout (reads slot context)', () => {
+    render(
+      <Layout
+        header={<LayoutHeader>H</LayoutHeader>}
+        content={<LayoutContent role="main">Main</LayoutContent>}
+      />,
+    );
+    expect(screen.getByRole('main')).toHaveTextContent('Main');
+  });
+
+  it('accepts padding={0} (full bleed) and a numeric padding without crashing', () => {
+    const {rerender, container} = render(
+      <LayoutContent padding={0}>C</LayoutContent>,
+    );
+    expect(
+      container.querySelector('.astryx-layout-content'),
+    ).toBeInTheDocument();
+    rerender(<LayoutContent padding={6}>C</LayoutContent>);
+    expect(
+      container.querySelector('.astryx-layout-content'),
+    ).toBeInTheDocument();
+  });
+});
+
+// =============================================================================
+// LayoutPanel
+// =============================================================================
+
+describe('LayoutPanel', () => {
+  it('renders its children', () => {
+    render(<LayoutPanel>Nav</LayoutPanel>);
+    expect(screen.getByText('Nav')).toBeInTheDocument();
+  });
+
+  it('carries the astryx-layout-panel class', () => {
+    const {container} = render(<LayoutPanel>P</LayoutPanel>);
+    expect(container.querySelector('.astryx-layout-panel')).toBeInTheDocument();
+  });
+
+  it('exposes a navigation landmark with an accessible name', () => {
+    render(
+      <LayoutPanel role="navigation" label="Primary">
+        P
+      </LayoutPanel>,
+    );
+    expect(
+      screen.getByRole('navigation', {name: 'Primary'}),
+    ).toBeInTheDocument();
+  });
+
+  it('applies a numeric width to the element style', () => {
+    const {container} = render(<LayoutPanel width={240}>P</LayoutPanel>);
+    const el = container.querySelector('.astryx-layout-panel') as HTMLElement;
+    expect(el.getAttribute('style') ?? '').toContain('240px');
+  });
+
+  it('applies a string width to the element style', () => {
+    const {container} = render(<LayoutPanel width="18rem">P</LayoutPanel>);
+    const el = container.querySelector('.astryx-layout-panel') as HTMLElement;
+    expect(el.getAttribute('style') ?? '').toContain('18rem');
+  });
+
+  it('resizable._size overrides the width prop', () => {
+    function Harness() {
+      const region = useResizable({defaultSize: 300});
+      return (
+        <LayoutPanel width={100} resizable={region.props}>
+          P
+        </LayoutPanel>
+      );
+    }
+    const {container} = render(<Harness />);
+    const el = container.querySelector('.astryx-layout-panel') as HTMLElement;
+    const style = el.getAttribute('style') ?? '';
+    expect(style).toContain('300px');
+    expect(style).not.toContain('100px');
+  });
+
+  it('forwards ref to the element', () => {
+    const ref = createRef<HTMLDivElement>();
+    render(<LayoutPanel ref={ref}>P</LayoutPanel>);
+    expect(ref.current).toBeInstanceOf(HTMLDivElement);
+    expect(ref.current?.className).toContain('astryx-layout-panel');
+  });
+
+  it('renders as a start-slot panel inside a Layout without crashing', () => {
+    render(
+      <Layout
+        start={
+          <LayoutPanel hasDivider role="navigation" label="Side">
+            Sidebar
+          </LayoutPanel>
+        }
+        content={<LayoutContent>Main</LayoutContent>}
+      />,
+    );
+    expect(screen.getByRole('navigation', {name: 'Side'})).toHaveTextContent(
+      'Sidebar',
+    );
+  });
+
+  it('renders as an end-slot panel inside a Layout without crashing', () => {
+    render(
+      <Layout
+        end={
+          <LayoutPanel hasDivider role="complementary" label="Inspector">
+            Details
+          </LayoutPanel>
+        }
+        content={<LayoutContent>Main</LayoutContent>}
+      />,
+    );
+    expect(
+      screen.getByRole('complementary', {name: 'Inspector'}),
+    ).toHaveTextContent('Details');
+  });
+
+  it('merges a caller className', () => {
+    const {container} = render(
+      <LayoutPanel className="panel-custom">P</LayoutPanel>,
+    );
+    const el = container.querySelector('.astryx-layout-panel') as HTMLElement;
+    expect(el.className).toContain('panel-custom');
+  });
+});

package/src/Lightbox/Lightbox.doc.mjs

@@ -64,8 +64,13 @@ export const docs = {
       { guidance: false, description: 'Nest interactive content inside captions; keep them plain text.' },
     ],
   },
+  // The lightbox opens via showModal() and renders nothing while closed —
+  // overlay mode gives the Properties preview an open trigger instead of an
+  // empty stage, mirroring MobileNav (#3616).
   playground: {
+    overlay: true,
     defaults: {
+      isOpen: false,
       media: {
         src: 'https://lookaside.facebook.com/assets/astryx/light-scene-horizontal-1.png',
         alt: 'Coastal shoreline with ocean waves',

package/src/Lightbox/Lightbox.test.tsx

@@ -1,8 +1,9 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-import {describe, it, expect, vi, beforeEach} from 'vitest';
-import {render, screen, fireEvent} from '@testing-library/react';
+import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
+import {render, screen, fireEvent, waitFor} from '@testing-library/react';
 import {Lightbox} from './Lightbox';
+import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
 
 // Mock showModal/close for jsdom
 beforeEach(() => {
@@ -16,6 +17,16 @@ beforeEach(() => {
   });
 });
 
+// useAnnounce mounts singleton live regions on <body>; reset between tests so
+// stale announcements from one test don't leak into the next.
+afterEach(() => {
+  __resetLiveRegionsForTest();
+});
+
+function politeRegion(): HTMLElement | null {
+  return document.querySelector('[data-astryx-live-region="polite"]');
+}
+
 describe('Lightbox', () => {
   it('renders as a dialog element', () => {
     render(
@@ -300,6 +311,116 @@ describe('Lightbox', () => {
     });
   });
 
+  describe('screen-reader announcements', () => {
+    const media = [
+      {src: '/a.jpg', alt: 'Image A', caption: 'First'},
+      {src: '/b.jpg', alt: 'Image B', caption: 'Second'},
+      {src: '/c.jpg', alt: 'Image C'},
+    ];
+
+    it('announces the new image and position when navigating next via button', async () => {
+      render(
+        <Lightbox
+          isOpen={true}
+          onOpenChange={() => {}}
+          media={media}
+          defaultIndex={0}
+        />,
+      );
+      fireEvent.click(screen.getByLabelText('Next'));
+      await waitFor(() => {
+        expect(politeRegion()).toHaveTextContent('Image B, 2 of 3');
+      });
+    });
+
+    it('announces the new image and position when navigating via arrow keys', async () => {
+      render(
+        <Lightbox
+          isOpen={true}
+          onOpenChange={() => {}}
+          media={media}
+          defaultIndex={1}
+        />,
+      );
+      const dialog = document.querySelector('dialog')!;
+      fireEvent.keyDown(dialog, {key: 'ArrowRight'});
+      await waitFor(() => {
+        expect(politeRegion()).toHaveTextContent('Image C, 3 of 3');
+      });
+    });
+
+    it('announces the new image and position when navigating prev', async () => {
+      render(
+        <Lightbox
+          isOpen={true}
+          onOpenChange={() => {}}
+          media={media}
+          defaultIndex={2}
+        />,
+      );
+      fireEvent.click(screen.getByLabelText('Previous'));
+      await waitFor(() => {
+        expect(politeRegion()).toHaveTextContent('Image B, 2 of 3');
+      });
+    });
+
+    it('falls back to a positional label when the image has no alt', async () => {
+      const unlabeled = [
+        {src: '/a.jpg', alt: 'Image A'},
+        {src: '/b.jpg', alt: ''},
+      ];
+      render(
+        <Lightbox
+          isOpen={true}
+          onOpenChange={() => {}}
+          media={unlabeled}
+          defaultIndex={0}
+        />,
+      );
+      fireEvent.click(screen.getByLabelText('Next'));
+      await waitFor(() => {
+        expect(politeRegion()).toHaveTextContent('Image 2 of 2');
+      });
+    });
+
+    it('does not announce on initial open', async () => {
+      render(
+        <Lightbox
+          isOpen={true}
+          onOpenChange={() => {}}
+          media={media}
+          defaultIndex={1}
+        />,
+      );
+      // Allow any scheduled rAF to flush; nothing should have been announced.
+      await new Promise(resolve => requestAnimationFrame(() => resolve(null)));
+      // The dialog's aria-label already names the current image on open, so no
+      // live region is created (announce is never called).
+      expect(politeRegion()).toBeNull();
+    });
+
+    it('does not announce when the lightbox opens at a new index', async () => {
+      const {rerender} = render(
+        <Lightbox
+          isOpen={false}
+          onOpenChange={() => {}}
+          media={media}
+          index={0}
+        />,
+      );
+      rerender(
+        <Lightbox
+          isOpen={true}
+          onOpenChange={() => {}}
+          media={media}
+          index={2}
+        />,
+      );
+      await new Promise(resolve => requestAnimationFrame(() => resolve(null)));
+      expect(politeRegion()).toBeNull();
+    });
+  });
+
   describe('video support', () => {
     it('renders a video element when type is video', () => {
       const {container} = render(

package/src/Lightbox/Lightbox.tsx

@@ -19,6 +19,7 @@
 import {
   useCallback,
   useEffect,
+  useMemo,
   useRef,
   useState,
   type MouseEvent as ReactMouseEvent,
@@ -28,6 +29,7 @@ import * as stylex from '@stylexjs/stylex';
 import {colorVars, spacingVars, typeScaleVars} from '../theme/tokens.stylex';
 import {Icon} from '../Icon';
 import {IconButton} from '../IconButton';
+import {useAnnounce} from '../hooks/useAnnounce';
 import {useScrollLock} from '../hooks/useScrollLock';
 import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
 import {mergeProps, mergeRefs} from '../utils';
@@ -306,7 +308,10 @@ export function Lightbox({
   const dragStartRef = useRef({x: 0, y: 0, panX: 0, panY: 0});
 
   // Resolve current media item
-  const mediaArray = Array.isArray(media) ? media : [media];
+  const mediaArray = useMemo(
+    () => (Array.isArray(media) ? media : [media]),
+    [media],
+  );
   const isGallery = mediaArray.length > 1;
   const currentItem =
     mediaArray.length > 0
@@ -329,6 +334,29 @@ export function Lightbox({
     setPan({x: 0, y: 0});
   }, [index, currentItem?.src]);
 
+  // Announce gallery navigation to screen readers. Moving between images only
+  // updates the visual counter, which is silent to assistive tech, so mirror
+  // each change in a polite live region ("<alt>, 3 of 12", or "Image 3 of 12"
+  // when the image has no alt). Announce only when the image changes during an
+  // already-open session — not on mount, not when opening (even at a new
+  // index, since the dialog's aria-label already names the current image), and
+  // not on close.
+  const announce = useAnnounce();
+  const prevIndexRef = useRef(index);
+  const wasOpenRef = useRef(isOpen);
+  useEffect(() => {
+    const indexChanged = prevIndexRef.current !== index;
+    const wasOpen = wasOpenRef.current;
+    prevIndexRef.current = index;
+    wasOpenRef.current = isOpen;
+    if (!indexChanged || !isOpen || !wasOpen) {
+      return;
+    }
+    const item = mediaArray[Math.min(index, mediaArray.length - 1)];
+    const position = `${index + 1} of ${mediaArray.length}`;
+    announce(item?.alt ? `${item.alt}, ${position}` : `Image ${position}`);
+  }, [index, isOpen, announce, mediaArray]);
+
   // Open/close dialog
   useIsomorphicLayoutEffect(() => {
     const dialog = dialogRef.current;

package/src/Lightbox/useLightbox.tsx

@@ -76,7 +76,6 @@ export interface UseLightboxReturn {
  * @example
  * ```
  * const lightbox = useLightbox({ media: photos });
- *
  * {photos.map((photo, i) => (
  *   <img
  *     key={photo.src}