@astryxdesign/core 0.1.4-canary.39ffd21 → 0.1.4-canary.3d64ef2

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/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/NavMenu/NavMenu.doc.mjs

@@ -17,12 +17,27 @@ export const docs = {
       'NavHeadingMenuItem renders individual selectable items. ' +
       'Pass as the menu prop of SideNavHeading or TopNavHeading.',
   },
+  playground: {
+    defaults: {
+      children: [
+        {__element: 'NavHeadingMenuItem', props: {label: 'Dashboard', href: '#'}},
+        {__element: 'NavHeadingMenuItem', props: {label: 'Analytics', href: '#'}},
+        {__element: 'NavHeadingMenuItem', props: {label: 'Settings', href: '#'}},
+      ],
+    },
+  },
   props: [
     {name: 'children', type: 'ReactNode', required: true, description: 'Menu items.'},
     {name: 'size', type: "'sm' | 'md' | 'lg'", default: "'md'", description: 'Controls min-width and item padding.'},
     {name: 'minWidth', type: 'number | string', description: 'Minimum width override.'},
     {name: 'xstyle', type: 'StyleXStyles', description: 'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value, not an inline style object like style={{}}.'},
   ],
+  theming: {
+    targets: [
+      {className: 'astryx-nav-heading-menu', visualProps: ['size']},
+      {className: 'astryx-nav-heading-menu-item', visualProps: ['size']},
+    ],
+  },
 };
 
 /** @type {import('../docs-types').TranslationDoc} */

package/src/NumberInput/NumberInput.test.tsx

@@ -12,7 +12,7 @@
 import {describe, it, expect, vi, beforeEach} from 'vitest';
 import {render, screen, fireEvent, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
-import {HashtagIcon} from '@heroicons/react/24/outline';
+import {TestIcon} from '../__tests__/TestIcon';
 import {NumberInput} from './NumberInput';
 
 // Mock showPopover/hidePopover since jsdom does not implement them. Used by the
@@ -174,7 +174,7 @@ describe('NumberInput', () => {
         label="Count"
         value={null}
         onChange={() => {}}
-        startIcon={HashtagIcon}
+        startIcon={TestIcon}
       />,
     );
     expect(screen.getByRole('spinbutton')).toBeInTheDocument();
@@ -707,7 +707,7 @@ describe('NumberInput', () => {
           label="Qty"
           value={0}
           onChange={() => {}}
-          startIcon={<HashtagIcon />}
+          startIcon={<TestIcon />}
         />,
       );
 
@@ -867,3 +867,48 @@ describe('NumberInput', () => {
     });
   });
 });
+
+describe('keyboard clearing with hasClear (#3599)', () => {
+  it('commits null when the input is emptied and blurred', () => {
+    const onChange = vi.fn();
+    render(
+      <NumberInput label="Qty" hasClear value={42} onChange={onChange} />,
+    );
+    const input = screen.getByLabelText('Qty');
+    fireEvent.change(input, {target: {value: ''}});
+    fireEvent.blur(input);
+    expect(onChange).toHaveBeenCalledWith(null);
+  });
+
+  it('commits null when the input is emptied and Enter is pressed', () => {
+    const onChange = vi.fn();
+    render(
+      <NumberInput label="Qty" hasClear value={42} onChange={onChange} />,
+    );
+    const input = screen.getByLabelText('Qty');
+    fireEvent.change(input, {target: {value: ''}});
+    fireEvent.keyDown(input, {key: 'Enter'});
+    expect(onChange).toHaveBeenCalledWith(null);
+  });
+
+  it('does not fire when emptied and blurred with no prior value', () => {
+    const onChange = vi.fn();
+    render(
+      <NumberInput label="Qty" hasClear value={null} onChange={onChange} />,
+    );
+    const input = screen.getByLabelText('Qty');
+    fireEvent.change(input, {target: {value: ''}});
+    fireEvent.blur(input);
+    expect(onChange).not.toHaveBeenCalled();
+  });
+
+  it('still reverts on blur when hasClear is not set', () => {
+    const onChange = vi.fn();
+    render(<NumberInput label="Qty" value={42} onChange={onChange} />);
+    const input = screen.getByLabelText('Qty');
+    fireEvent.change(input, {target: {value: ''}});
+    fireEvent.blur(input);
+    expect(onChange).not.toHaveBeenCalled();
+    expect((input as HTMLInputElement).value).toBe('42');
+  });
+});

package/src/NumberInput/NumberInput.tsx

@@ -503,13 +503,21 @@ export function NumberInput({
   const handleBlur = useCallback(
     (e: FocusEvent<HTMLInputElement>) => {
       if (pendingInput !== null) {
-        const parsed = parseNumberInput(pendingInput, {
-          min,
-          max,
-          isIntegerOnly,
-        });
-        if (parsed !== null && parsed !== value) {
-          onChange(parsed);
+        if (hasClear && pendingInput.trim() === '') {
+          // Keyboard clearing honors the clearable contract: an emptied
+          // input commits null instead of silently reverting on blur.
+          if (value != null) {
+            onChange(null);
+          }
+        } else {
+          const parsed = parseNumberInput(pendingInput, {
+            min,
+            max,
+            isIntegerOnly,
+          });
+          if (parsed !== null && parsed !== value) {
+            onChange(parsed);
+          }
         }
       }
 
@@ -517,7 +525,7 @@ export function NumberInput({
       setPendingInput(null);
       onBlur?.(e);
     },
-    [pendingInput, value, onChange, min, max, isIntegerOnly, onBlur],
+    [pendingInput, value, onChange, min, max, isIntegerOnly, onBlur, hasClear],
   );
 
   // Handle keyboard events
@@ -526,13 +534,21 @@ export function NumberInput({
       if (e.key === 'Enter') {
         // Validate and commit on Enter
         if (pendingInput !== null) {
-          const parsed = parseNumberInput(pendingInput, {
-            min,
-            max,
-            isIntegerOnly,
-          });
-          if (parsed !== null && parsed !== value) {
-            onChange(parsed);
+          if (hasClear && pendingInput.trim() === '') {
+            // Same clearable contract as blur: Enter on an emptied input
+            // commits null instead of reverting.
+            if (value != null) {
+              onChange(null);
+            }
+          } else {
+            const parsed = parseNumberInput(pendingInput, {
+              min,
+              max,
+              isIntegerOnly,
+            });
+            if (parsed !== null && parsed !== value) {
+              onChange(parsed);
+            }
           }
         }
         onEnter?.();
@@ -548,6 +564,7 @@ export function NumberInput({
       isIntegerOnly,
       onEnter,
       onKeyDown,
+      hasClear,
     ],
   );
 

package/src/Overlay/Overlay.doc.mjs

@@ -180,6 +180,12 @@ export const docs = {
       description: 'Ref forwarded to the overlay root element.',
     },
   ],
+  theming: {
+    targets: [
+      {className: 'astryx-overlay'},
+      {className: 'astryx-overlay-scrim', visualProps: ['position']},
+    ],
+  },
 };
 
 /** @type {import('../docs-types').TranslationDoc} */

package/src/Pagination/Pagination.test.tsx

@@ -345,6 +345,149 @@ describe('Pagination', () => {
       const activeDot = screen.getByRole('button', {name: 'Go to page 3'});
       expect(activeDot).toHaveAttribute('aria-current', 'page');
     });
+
+    // -------------------------------------------------------------------------
+    // Keyboard navigation (roving tabindex + arrow keys via useListFocus).
+    // Selection follows focus: arrow/Home/End move focus and select that page.
+    // -------------------------------------------------------------------------
+
+    it('uses roving tabindex — active dot has tabIndex 0, others -1', () => {
+      render(
+        <Pagination
+          page={2}
+          onChange={() => {}}
+          totalPages={4}
+          variant="dots"
+        />,
+      );
+      expect(
+        screen.getByRole('button', {name: 'Go to page 2'}),
+      ).toHaveAttribute('tabindex', '0');
+      expect(
+        screen.getByRole('button', {name: 'Go to page 1'}),
+      ).toHaveAttribute('tabindex', '-1');
+      expect(
+        screen.getByRole('button', {name: 'Go to page 3'}),
+      ).toHaveAttribute('tabindex', '-1');
+    });
+
+    it('ArrowRight moves focus to the next dot and selects it', async () => {
+      const user = userEvent.setup();
+      const onChange = vi.fn();
+      render(
+        <Pagination
+          page={2}
+          onChange={onChange}
+          totalPages={4}
+          variant="dots"
+        />,
+      );
+      screen.getByRole('button', {name: 'Go to page 2'}).focus();
+      await user.keyboard('{ArrowRight}');
+      expect(onChange).toHaveBeenCalledWith(3);
+      expect(screen.getByRole('button', {name: 'Go to page 3'})).toHaveFocus();
+    });
+
+    it('ArrowLeft moves focus to the previous dot and selects it', async () => {
+      const user = userEvent.setup();
+      const onChange = vi.fn();
+      render(
+        <Pagination
+          page={3}
+          onChange={onChange}
+          totalPages={4}
+          variant="dots"
+        />,
+      );
+      screen.getByRole('button', {name: 'Go to page 3'}).focus();
+      await user.keyboard('{ArrowLeft}');
+      expect(onChange).toHaveBeenCalledWith(2);
+      expect(screen.getByRole('button', {name: 'Go to page 2'})).toHaveFocus();
+    });
+
+    it('Home selects the first page, End the last', async () => {
+      const user = userEvent.setup();
+      const onChange = vi.fn();
+      const {rerender} = render(
+        <Pagination
+          page={3}
+          onChange={onChange}
+          totalPages={5}
+          variant="dots"
+        />,
+      );
+      screen.getByRole('button', {name: 'Go to page 3'}).focus();
+      await user.keyboard('{Home}');
+      expect(onChange).toHaveBeenCalledWith(1);
+      expect(screen.getByRole('button', {name: 'Go to page 1'})).toHaveFocus();
+
+      onChange.mockClear();
+      rerender(
+        <Pagination
+          page={3}
+          onChange={onChange}
+          totalPages={5}
+          variant="dots"
+        />,
+      );
+      screen.getByRole('button', {name: 'Go to page 3'}).focus();
+      await user.keyboard('{End}');
+      expect(onChange).toHaveBeenCalledWith(5);
+      expect(screen.getByRole('button', {name: 'Go to page 5'})).toHaveFocus();
+    });
+
+    it('wraps from the last dot to the first with ArrowRight', async () => {
+      const user = userEvent.setup();
+      const onChange = vi.fn();
+      render(
+        <Pagination
+          page={4}
+          onChange={onChange}
+          totalPages={4}
+          variant="dots"
+        />,
+      );
+      screen.getByRole('button', {name: 'Go to page 4'}).focus();
+      await user.keyboard('{ArrowRight}');
+      expect(onChange).toHaveBeenCalledWith(1);
+      expect(screen.getByRole('button', {name: 'Go to page 1'})).toHaveFocus();
+    });
+
+    it('wraps from the first dot to the last with ArrowLeft', async () => {
+      const user = userEvent.setup();
+      const onChange = vi.fn();
+      render(
+        <Pagination
+          page={1}
+          onChange={onChange}
+          totalPages={4}
+          variant="dots"
+        />,
+      );
+      screen.getByRole('button', {name: 'Go to page 1'}).focus();
+      await user.keyboard('{ArrowLeft}');
+      expect(onChange).toHaveBeenCalledWith(4);
+      expect(screen.getByRole('button', {name: 'Go to page 4'})).toHaveFocus();
+    });
+
+    it('does not navigate with arrow keys when disabled', async () => {
+      const user = userEvent.setup();
+      const onChange = vi.fn();
+      render(
+        <Pagination
+          page={2}
+          onChange={onChange}
+          totalPages={4}
+          variant="dots"
+          isDisabled
+        />,
+      );
+      const dot = screen.getByRole('button', {name: 'Go to page 2'});
+      expect(dot).toBeDisabled();
+      dot.focus();
+      await user.keyboard('{ArrowRight}');
+      expect(onChange).not.toHaveBeenCalled();
+    });
   });
 
   // ---------------------------------------------------------------------------