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

package/src/Pagination/Pagination.tsx

@@ -35,6 +35,7 @@ import {Icon} from '../Icon';
 import {Selector} from '../Selector';
 import {Text} from '../Text';
 import {useAnnounce} from '../hooks/useAnnounce';
+import {useListFocus} from '../hooks/useListFocus';
 import {mergeProps} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
@@ -349,6 +350,7 @@ export function Pagination({
   className,
   style,
   ref,
+  ...rest
 }: PaginationProps) {
   const [, startTransition] = useTransition();
 
@@ -370,6 +372,21 @@ export function Pagination({
   // in-flight target instead of stalling on the last committed page.
   const [optimisticPage, setOptimisticPage] = useOptimistic(page);
 
+  // Roving-tabindex + arrow/Home/End keyboard nav for the dots variant, owned
+  // by the shared useListFocus primitive (mirrors SegmentedControl). It stamps a
+  // single tab stop across the dots and moves focus horizontally; selection
+  // follows focus via handleDotsFocus so arrow keys move the active page.
+  const {
+    listRef: dotsListRef,
+    handleKeyDown: handleDotsKeyDown,
+    handleFocus: handleDotsRovingFocus,
+  } = useListFocus<HTMLDivElement>({
+    itemSelector: 'button',
+    hasRovingTabIndex: true,
+    wrap: true,
+    orientation: 'horizontal',
+  });
+
   // Compute pagination state
   const computedTotalPages =
     totalPagesProp ??
@@ -410,6 +427,28 @@ export function Pagination({
     });
   };
 
+  // Selection-follows-focus for the dots (APG radiogroup pattern): useListFocus
+  // only *moves* focus, so when focus lands on a dot -- via arrow/Home/End, or a
+  // click that focuses it -- we select that dot's page. handleDotsRovingFocus
+  // keeps the roving tab stop in sync. The current page is skipped so tabbing
+  // into the group is a no-op.
+  const handleDotsFocus = (e: React.FocusEvent) => {
+    handleDotsRovingFocus(e);
+    if (isDisabled) {
+      return;
+    }
+    const focused = (e.target as HTMLElement | null)?.closest<HTMLElement>(
+      'button[data-page]',
+    );
+    if (!focused) {
+      return;
+    }
+    const nextPage = Number(focused.dataset.page);
+    if (Number.isFinite(nextPage) && nextPage !== optimisticPage) {
+      handlePageChange(nextPage);
+    }
+  };
+
   const handlePrevious = () => {
     if (hasPrevious) {
       handlePageChange(optimisticPage - 1);
@@ -518,33 +557,47 @@ export function Pagination({
         if (computedTotalPages == null) {
           return null;
         }
+
         return (
           <div
+            ref={dotsListRef}
             {...stylex.props(styles.dotsContainer)}
             role="group"
-            aria-label="Page indicators">
-            {Array.from({length: computedTotalPages}, (_, i) => (
-              <button
-                key={i + 1}
-                type="button"
-                aria-label={`Go to page ${i + 1}`}
-                aria-current={i + 1 === optimisticPage ? 'page' : undefined}
-                onClick={() => handlePageChange(i + 1)}
-                disabled={isDisabled}
-                {...mergeProps(
-                  themeProps('pagination-dot', {
-                    active: i + 1 === optimisticPage ? 'active' : null,
-                    size,
-                  }),
-                  stylex.props(
-                    styles.dot,
-                    isSm && styles.dotSm,
-                    i + 1 === optimisticPage && styles.dotActive,
-                    isDisabled && styles.dotDisabled,
-                  ),
-                )}
-              />
-            ))}
+            aria-label="Page indicators"
+            onKeyDown={handleDotsKeyDown}
+            onFocus={handleDotsFocus}>
+            {Array.from({length: computedTotalPages}, (_, i) => {
+              const isActive = i + 1 === optimisticPage;
+              return (
+                <button
+                  key={i + 1}
+                  type="button"
+                  data-page={i + 1}
+                  aria-label={`Go to page ${i + 1}`}
+                  aria-current={isActive ? 'page' : undefined}
+                  // The active dot is the single roving tab stop; useListFocus
+                  // maintains it as focus and the active page move.
+                  tabIndex={isActive ? 0 : -1}
+                  // Selection is driven by focus (handleDotsFocus); clicking only
+                  // needs to focus the dot, which some browsers (Safari) skip for
+                  // buttons, so focus it explicitly.
+                  onClick={e => e.currentTarget.focus()}
+                  disabled={isDisabled}
+                  {...mergeProps(
+                    themeProps('pagination-dot', {
+                      active: isActive ? 'active' : null,
+                      size,
+                    }),
+                    stylex.props(
+                      styles.dot,
+                      isSm && styles.dotSm,
+                      isActive && styles.dotActive,
+                      isDisabled && styles.dotDisabled,
+                    ),
+                  )}
+                />
+              );
+            })}
           </div>
         );
       }
@@ -558,14 +611,15 @@ export function Pagination({
   return (
     <nav
       ref={ref}
-      aria-label={label}
-      data-testid={testId}
       {...mergeProps(
         themeProps('pagination', {variant, size}),
         stylex.props(styles.root, xstyle),
         className,
         style,
-      )}>
+      )}
+      {...rest}
+      aria-label={label}
+      data-testid={testId}>
       {pageSizeOptions != null && pageSizeOptions.length > 0 && (
         <div {...stylex.props(styles.pageSizeSelector)}>
           <div {...stylex.props(styles.pageSizeSelectorControl)}>

package/src/Popover/Popover.doc.mjs

@@ -36,13 +36,13 @@ export const docs = {
         {
           name: 'placement',
           type: "'above' | 'below' | 'start' | 'end'",
-          description: 'Position placement relative to the trigger.',
+          description: 'Position placement relative to the trigger. Logical: start/end resolve against the popover\'s own inherited direction, so RTL contexts mirror automatically in pure CSS.',
           default: "'below'",
         },
         {
           name: 'alignment',
           type: "'start' | 'center' | 'end'",
-          description: 'Alignment along the placement axis.',
+          description: 'Alignment along the placement axis. Logical: start/end follow the popover\'s own inherited direction (RTL mirrors).',
           default: "'start'",
         },
         {
@@ -177,13 +177,13 @@ export const docsZh = {
         {
           name: 'placement',
           type: "'above' | 'below' | 'start' | 'end'",
-          description: '相对于触发器的位置放置方式。',
+          description: '相对于触发器的位置放置方式。逻辑值：start/end 根据弹出层自身继承的方向解析，RTL 环境通过纯 CSS 自动镜像。',
           default: "'below'",
         },
         {
           name: 'alignment',
           type: "'start' | 'center' | 'end'",
-          description: '沿放置轴的对齐方式。',
+          description: '沿放置轴的对齐方式。逻辑值：start/end 跟随弹出层自身继承的方向（RTL 镜像）。',
           default: "'start'",
         },
         {
@@ -305,8 +305,8 @@ export const docsDense = {
         children: 'Trigger element. Must contain <button> or [role="button"] element.',
         anchorRef: 'External ref for popover anchor in sibling mode.',
         content: 'Content displayed inside popover.',
-        placement: 'Position relative to trigger.',
-        alignment: 'Alignment along placement axis.',
+        placement: 'Position relative to trigger. Logical: start/end resolve against the popover\'s inherited direction (RTL mirrors).',
+        alignment: 'Alignment along placement axis. Logical: start/end follow the popover\'s inherited direction (RTL mirrors).',
         isOpen: 'Whether popover shown in controlled mode.',
         onOpenChange: 'Callback fired when popover visibility changes.',
         isEnabled: 'When false, trigger interactions ignored.',

package/src/Popover/Popover.test.tsx

@@ -354,4 +354,69 @@ describe('Popover', () => {
       expect(trigger).toHaveAttribute('aria-expanded', 'true');
     });
   });
+
+  describe('focus restoration', () => {
+    it('returns focus to the trigger when closed via Escape', () => {
+      render(
+        <Popover
+          content={
+            <button type="button" data-testid="inside-content">
+              Inside
+            </button>
+          }
+          label="Test">
+          <button type="button">Open</button>
+        </Popover>,
+      );
+      const trigger = screen.getByRole('button', {name: 'Open'});
+      trigger.focus();
+      expect(trigger).toHaveFocus();
+
+      fireEvent.click(trigger);
+      expect(trigger).toHaveAttribute('aria-expanded', 'true');
+
+      // Move focus into the open popover, as a keyboard user would.
+      const inside = screen.getByTestId('inside-content');
+      inside.focus();
+      expect(inside).toHaveFocus();
+
+      fireEvent.keyDown(document, {key: 'Escape'});
+      expect(trigger).toHaveAttribute('aria-expanded', 'false');
+      expect(trigger).toHaveFocus();
+    });
+
+    it('returns focus to the trigger on light dismiss', () => {
+      render(
+        <Popover
+          content={
+            <button type="button" data-testid="inside-content">
+              Inside
+            </button>
+          }
+          label="Test">
+          <button type="button">Open</button>
+        </Popover>,
+      );
+      const trigger = screen.getByRole('button', {name: 'Open'});
+      trigger.focus();
+
+      fireEvent.click(trigger);
+      expect(trigger).toHaveAttribute('aria-expanded', 'true');
+
+      const inside = screen.getByTestId('inside-content');
+      inside.focus();
+      expect(inside).toHaveFocus();
+
+      // Simulate the browser's light dismiss for popover="auto": clicking
+      // outside fires a `toggle` event with newState "closed".
+      const popoverEl = document.querySelector('[popover]');
+      expect(popoverEl).not.toBeNull();
+      const toggleEvent = new Event('toggle');
+      Object.defineProperty(toggleEvent, 'newState', {value: 'closed'});
+      fireEvent(popoverEl as HTMLElement, toggleEvent);
+
+      expect(trigger).toHaveAttribute('aria-expanded', 'false');
+      expect(trigger).toHaveFocus();
+    });
+  });
 });

package/src/Popover/usePopover.doc.mjs

@@ -29,7 +29,7 @@ export const docs = {
     {name: 'toggle', type: '() => void', description: 'Toggle the popover open or closed.'},
     {name: 'isOpen', type: 'boolean', description: 'Whether the popover is currently open.'},
     {name: 'id', type: 'string', description: 'Unique ID for aria-describedby or aria-controls.'},
-    {name: 'render', type: '(children: ReactNode, props?: ContextRenderProps) => ReactNode', description: 'Render function for anchor-positioned popover content. Pass placement and alignment here.'},
+    {name: 'render', type: '(children: ReactNode, props?: ContextRenderProps) => ReactNode', description: 'Render function for anchor-positioned popover content. Pass placement and alignment here. Logical: start/end resolve against the popover\'s own inherited direction (RTL mirrors in pure CSS).'},
     {name: 'triggerProps', type: '{aria-haspopup: "dialog" | "true"; aria-expanded: boolean; aria-controls: string}', description: 'ARIA attributes to spread onto the trigger element. aria-haspopup reflects the popover role.'},
   ],
   usage: {

package/src/PowerSearch/PowerSearch.doc.mjs

@@ -120,7 +120,7 @@ export const docs = {
       name: 'resultCount',
       type: 'number | string',
       description:
-        'Number of results matching the current filters. When a number, formatted as "N results". When a string, displayed as-is.',
+        'Number of results matching the current filters. When a number, formatted as "N results". When a string, displayed as-is. Changes are announced to screen readers via a polite live region.',
     },
     {
       name: 'size',
@@ -261,7 +261,7 @@ export const docsZh = {
       name: 'resultCount',
       type: 'number | string',
       description:
-        '匹配当前过滤器的结果数量。数字类型时格式化为"N results"。字符串类型时按原样显示。',
+        '匹配当前过滤器的结果数量。数字类型时格式化为"N results"。字符串类型时按原样显示。数量变化会通过 polite 实时区域向屏幕阅读器播报。',
     },
     {
       name: 'size',

package/src/PowerSearch/PowerSearch.test.tsx

@@ -10,10 +10,11 @@
  */
 
 import {useState} from 'react';
-import {describe, it, expect, vi, beforeAll, afterAll} from 'vitest';
+import {describe, it, expect, vi, beforeAll, afterAll, afterEach} from 'vitest';
 import {render, screen, act, fireEvent, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {PowerSearch} from './PowerSearch';
+import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
 import type {PowerSearchConfig, PowerSearchFilter} from './types';
 
 // =============================================================================
@@ -59,6 +60,12 @@ afterAll(() => {
   (HTMLElement.prototype as any).matches = originalMatches;
 });
 
+// Reset the singleton live regions between tests so result-count
+// announcements from one test don't leak into the next.
+afterEach(() => {
+  __resetLiveRegionsForTest();
+});
+
 // =============================================================================
 // Fixtures
 // =============================================================================
@@ -295,4 +302,105 @@ describe('PowerSearch', () => {
       expect(screen.getByRole('combobox')).toBeDisabled();
     });
   });
+
+  describe('result count announcements', () => {
+    const politeRegion = () =>
+      document.querySelector('[data-astryx-live-region="polite"]');
+
+    it('announces the result count to a polite live region when it changes', async () => {
+      const {rerender} = render(
+        <PowerSearch
+          config={config}
+          filters={[]}
+          onChange={() => {}}
+          resultCount={0}
+        />,
+      );
+      rerender(
+        <PowerSearch
+          config={config}
+          filters={[]}
+          onChange={() => {}}
+          resultCount={5}
+        />,
+      );
+      await waitFor(() => {
+        expect(politeRegion()).toHaveTextContent('5 results');
+      });
+    });
+
+    it('announces "1 result" (singular) for a single match', async () => {
+      const {rerender} = render(
+        <PowerSearch
+          config={config}
+          filters={[]}
+          onChange={() => {}}
+          resultCount={0}
+        />,
+      );
+      rerender(
+        <PowerSearch
+          config={config}
+          filters={[]}
+          onChange={() => {}}
+          resultCount={1}
+        />,
+      );
+      await waitFor(() => {
+        expect(politeRegion()).toHaveTextContent('1 result');
+      });
+      expect(politeRegion()?.textContent).not.toMatch(/results/);
+    });
+
+    it('announces a string result count verbatim', async () => {
+      const {rerender} = render(
+        <PowerSearch
+          config={config}
+          filters={[]}
+          onChange={() => {}}
+          resultCount="0 items"
+        />,
+      );
+      rerender(
+        <PowerSearch
+          config={config}
+          filters={[]}
+          onChange={() => {}}
+          resultCount="Showing 1.2k matches"
+        />,
+      );
+      await waitFor(() => {
+        expect(politeRegion()).toHaveTextContent('Showing 1.2k matches');
+      });
+    });
+
+    it('does not announce the result count present on initial mount', async () => {
+      render(
+        <PowerSearch
+          config={config}
+          filters={[]}
+          onChange={() => {}}
+          resultCount={42}
+        />,
+      );
+      // Flush effects and any pending live-region rAF writes.
+      await act(async () => {
+        await new Promise(resolve => setTimeout(resolve, 50));
+      });
+      expect(politeRegion()?.textContent ?? '').not.toContain('42');
+    });
+
+    it('leaves Typeahead dropdown announcements intact and stays silent when no resultCount is set', async () => {
+      const user = userEvent.setup();
+      render(<PowerSearchWrapper config={config} />);
+      const input = screen.getByRole('combobox');
+      await user.click(input);
+      await user.type(input, 'Status');
+      // BaseTypeahead announces the dropdown suggestion count; PowerSearch adds
+      // no result-count announcement because resultCount is unset.
+      await waitFor(() => {
+        expect(politeRegion()?.textContent).toMatch(/\d+ results?/);
+      });
+    });
+  });
 });

package/src/PowerSearch/PowerSearch.tsx

@@ -16,6 +16,7 @@
 
 import React, {
   useCallback,
+  useEffect,
   useImperativeHandle,
   useMemo,
   useRef,
@@ -38,6 +39,7 @@ import type {IconType} from '../Icon';
 import type {IconName} from '../Icon/globalIconRegistry';
 import type {InputStatus} from '../Field';
 import {usePopover} from '../Popover/usePopover';
+import {useAnnounce} from '../hooks/useAnnounce';
 import {
   spacingVars,
   colorVars,
@@ -945,23 +947,42 @@ export function PowerSearch({
     isReadOnly,
   ]);
 
+  // Plain-text form of the result count, shared by the visible label and the
+  // screen-reader announcement so the two never drift.
+  const resultCountText = useMemo((): string | null => {
+    if (resultCount == null) {
+      return null;
+    }
+    if (typeof resultCount === 'number') {
+      const formatted = new Intl.NumberFormat().format(resultCount);
+      return `${formatted} ${resultCount === 1 ? 'result' : 'results'}`;
+    }
+    return resultCount;
+  }, [resultCount]);
+
+  // Announce result-count changes to screen readers through a polite live
+  // region, mirroring the way Typeahead announces its dropdown result count.
+  // The count is otherwise only shown visually and stays silent to assistive
+  // tech. Skip the first run so the count already present on mount isn't
+  // announced unprompted — only user-driven changes are spoken.
+  const announce = useAnnounce();
+  const hasMountedRef = useRef(false);
+  useEffect(() => {
+    if (!hasMountedRef.current) {
+      hasMountedRef.current = true;
+      return;
+    }
+    if (resultCountText != null) {
+      announce(resultCountText);
+    }
+  }, [resultCountText, announce]);
+
   // Build combined endContent from resultCount + endContent props
   const combinedEndContent = useMemo((): React.ReactNode => {
-    let resultCountNode: React.ReactNode = null;
-    if (resultCount != null) {
-      if (typeof resultCount === 'number') {
-        const formatted = new Intl.NumberFormat().format(resultCount);
-        resultCountNode = (
-          <span {...stylex.props(resultCountStyles.text)}>
-            {formatted} {resultCount === 1 ? 'result' : 'results'}
-          </span>
-        );
-      } else {
-        resultCountNode = (
-          <span {...stylex.props(resultCountStyles.text)}>{resultCount}</span>
-        );
-      }
-    }
+    const resultCountNode =
+      resultCountText != null ? (
+        <span {...stylex.props(resultCountStyles.text)}>{resultCountText}</span>
+      ) : null;
 
     if (resultCountNode && endContent) {
       return (
@@ -972,7 +993,7 @@ export function PowerSearch({
       );
     }
     return resultCountNode || endContent || undefined;
-  }, [resultCount, endContent]);
+  }, [resultCountText, endContent]);
 
   return (
     <>

package/src/ProgressBar/ProgressBar.doc.mjs

@@ -73,6 +73,7 @@ export const docs = {
     targets: [
       {className: 'astryx-progressbar', visualProps: ['variant']},
       {className: 'astryx-progressbar-fill', visualProps: ['variant']},
+      {className: 'astryx-progressbar-track'},
     ],
   },
   usage: {
@@ -159,6 +160,7 @@ export const docsZh = {
     targets: [
       {className: 'astryx-progressbar', visualProps: ['variant']},
       {className: 'astryx-progressbar-fill', visualProps: ['variant']},
+      {className: 'astryx-progressbar-track'},
     ],
   },
   usage: {

package/src/ProgressBar/ProgressBar.test.tsx

@@ -140,6 +140,36 @@ describe('ProgressBar', () => {
     expect(progressbar).toHaveAttribute('aria-valuemax', '0');
   });
 
+  it('treats a NaN value as empty progress instead of leaking "NaN"', () => {
+    // e.g. an upstream `loaded / total * 100` where total is still 0.
+    render(<ProgressBar value={NaN} label="Upload" hasValueLabel />);
+    const progressbar = screen.getByRole('progressbar');
+    expect(progressbar).toHaveAttribute('aria-valuenow', '0');
+    expect(progressbar.getAttribute('aria-valuetext')).toBe('0%');
+    expect(screen.queryByText(/NaN/)).not.toBeInTheDocument();
+    // The fill width must be a real percentage, not "NaN%".
+    const fill = progressbar.firstElementChild as HTMLElement;
+    expect(fill.style.width).toBe('0%');
+  });
+
+  it('treats a NaN max as an empty range instead of leaking "NaN"', () => {
+    render(<ProgressBar value={5} max={NaN} label="Steps" hasValueLabel />);
+    const progressbar = screen.getByRole('progressbar');
+    expect(progressbar).toHaveAttribute('aria-valuenow', '0');
+    expect(progressbar).toHaveAttribute('aria-valuemax', '0');
+    expect(screen.queryByText(/NaN/)).not.toBeInTheDocument();
+  });
+
+  it('does not render NaN in the value label when max is zero', () => {
+    render(<ProgressBar value={0} max={0} label="Empty" hasValueLabel />);
+    expect(screen.queryByText(/NaN|Infinity/)).not.toBeInTheDocument();
+    const progressbar = screen.getByRole('progressbar');
+    expect(progressbar.getAttribute('aria-valuetext') ?? '').not.toMatch(
+      /NaN|Infinity/,
+    );
+    expect(screen.getByText('0%')).toBeInTheDocument();
+  });
+
   // Disabled state
   describe('disabled state', () => {
     it('renders with isDisabled', () => {

package/src/ProgressBar/ProgressBar.tsx

@@ -228,7 +228,8 @@ const variantStyles = stylex.create({
 });
 
 function defaultFormatValueLabel(value: number, max: number): string {
-  return `${Math.round((value / max) * 100)}%`;
+  const pct = max > 0 ? Math.round((value / max) * 100) : 0;
+  return `${pct}%`;
 }
 
 /**
@@ -272,9 +273,15 @@ export function ProgressBar({
   ...rest
 }: ProgressBarProps) {
   const labelId = useId();
-  const clampedValue = Math.min(Math.max(0, value), max);
-  const percentage = max > 0 ? (clampedValue / max) * 100 : 0;
-  const valueText = formatValueLabel(clampedValue, max);
+  // A non-finite value or max (e.g. a NaN from an upstream `loaded / total`
+  // with total 0) would otherwise leak into aria-valuenow, the value label,
+  // and the fill width as the string "NaN". Treat it as empty progress,
+  // matching the max=0 handling below.
+  const safeValue = Number.isFinite(value) ? value : 0;
+  const safeMax = Number.isFinite(max) ? max : 0;
+  const clampedValue = Math.min(Math.max(0, safeValue), safeMax);
+  const percentage = safeMax > 0 ? (clampedValue / safeMax) * 100 : 0;
+  const valueText = formatValueLabel(clampedValue, safeMax);
 
   const showValueLabel = hasValueLabel && !isIndeterminate;
 
@@ -322,7 +329,7 @@ export function ProgressBar({
         role="progressbar"
         aria-valuenow={isIndeterminate ? undefined : clampedValue}
         aria-valuemin={isIndeterminate ? undefined : 0}
-        aria-valuemax={isIndeterminate ? undefined : max}
+        aria-valuemax={isIndeterminate ? undefined : safeMax}
         aria-labelledby={labelId}
         aria-valuetext={isIndeterminate ? undefined : valueText}
         {...mergeProps(

package/src/RadioList/RadioList.test.tsx

@@ -622,4 +622,23 @@ describe('RadioList', () => {
       expect(input.getAttribute('name')).toBeTruthy();
     });
   });
+
+  describe('RadioListItem rest forwarding', () => {
+    it('forwards data-testid, id, and aria-* to the item root element', () => {
+      render(
+        <RadioList label="Preference" value="" onChange={() => {}}>
+          <RadioListItem
+            label="Option A"
+            value="a"
+            data-testid="item-a"
+            id="item-a-id"
+            aria-label="First option"
+          />
+        </RadioList>,
+      );
+      const item = screen.getByTestId('item-a');
+      expect(item).toHaveAttribute('id', 'item-a-id');
+      expect(item).toHaveAttribute('aria-label', 'First option');
+    });
+  });
 });

package/src/RadioList/RadioListItem.tsx

@@ -220,7 +220,10 @@ export function RadioListItem({
   isDisabled: isItemDisabled = false,
   startContent,
   endContent,
-  'data-testid': dataTestId,
+  xstyle,
+  className,
+  style,
+  ...rest
 }: RadioListItemProps) {
   const context = use(RadioListContext);
   if (!context) {
@@ -313,11 +316,13 @@ export function RadioListItem({
   return (
     <div
       ref={ref}
-      data-testid={dataTestId}
       {...mergeProps(
         themeProps('radio-list-item'),
-        stylex.props(styles.container, !isDisabled && radioScope),
-      )}>
+        stylex.props(styles.container, !isDisabled && radioScope, xstyle),
+        className,
+        style,
+      )}
+      {...rest}>
       <Item
         startContent={mediaContent}
         label={