@astryxdesign/core 0.1.3 → 0.1.4-canary.01e5b29

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

@@ -75,7 +75,7 @@ export const docs = {
       name: 'disabledMessage',
       type: 'string',
       description:
-        'Explains why the search is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the input focusable via aria-disabled (input stays blocked). Use this instead of wrapping a disabled PowerSearch in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+        'Explains why the search is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the input focusable via aria-disabled (input stays blocked). Use this instead of wrapping a disabled PowerSearch in Tooltip. Disabled controls swallow the hover events an external Tooltip needs.',
     },
     {
       name: 'status',
@@ -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',
@@ -223,7 +223,7 @@ export const docsZh = {
       name: 'disabledMessage',
       type: 'string',
       description:
-        'Explains why the search is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the input focusable via aria-disabled (input stays blocked). Use this instead of wrapping a disabled PowerSearch in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+        'Explains why the search is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the input focusable via aria-disabled (input stays blocked). Use this instead of wrapping a disabled PowerSearch in Tooltip. Disabled controls swallow the hover events an external Tooltip needs.',
     },
     {
       name: 'status',
@@ -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.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.doc.mjs

@@ -74,11 +74,17 @@ export const docs = {
       description: 'Whether all radio items are disabled.',
       default: 'false',
     },
+    {
+      name: 'htmlName',
+      type: 'string',
+      description:
+        'The HTML name attribute shared by the radio inputs, useful for form submissions. When omitted, a unique internal name still groups the radios.',
+    },
     {
       name: 'disabledMessage',
       type: 'string',
       description:
-        'Explains why the group is disabled. Applies to the whole-group disabled state (isDisabled), not per item. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the radios focusable via aria-disabled (selection stays blocked). Use this instead of wrapping a disabled RadioList in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+        'Explains why the group is disabled. Applies to the whole-group disabled state (isDisabled), not per item. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the radios focusable via aria-disabled (selection stays blocked). Use this instead of wrapping a disabled RadioList in Tooltip. Disabled controls swallow the hover events an external Tooltip needs.',
     },
     {
       name: 'isRequired',

package/src/RadioList/RadioList.test.tsx

@@ -576,4 +576,69 @@ describe('RadioList', () => {
       }
     });
   });
+  describe('form participation', () => {
+    it('submits the selected value under htmlName', () => {
+      const {container} = render(
+        <form>
+          <RadioList label="Preference" htmlName="pref" value="b" onChange={() => {}}>
+            <RadioListItem label="Option A" value="a" />
+            <RadioListItem label="Option B" value="b" />
+          </RadioList>
+        </form>,
+      );
+      const data = new FormData(container.querySelector('form')!);
+      expect(data.get('pref')).toBe('b');
+    });
+
+    it('is excluded from form data when disabled, even with a disabledMessage', () => {
+      const {container} = render(
+        <form>
+          <RadioList
+            label="Preference"
+            htmlName="pref"
+            value="a"
+            onChange={() => {}}
+            isDisabled
+            disabledMessage="Locked"
+          >
+            <RadioListItem label="Option A" value="a" />
+          </RadioList>
+        </form>,
+      );
+      expect([...new FormData(container.querySelector('form')!).keys()]).toEqual([]);
+    });
+
+    it('keeps working as an isolated group when htmlName is omitted', () => {
+      const {container} = render(
+        <form>
+          <RadioList label="Preference" value="a" onChange={() => {}}>
+            <RadioListItem label="Option A" value="a" />
+          </RadioList>
+        </form>,
+      );
+      // Auto-generated internal name still groups the radios, but the field
+      // name is not part of the public form contract.
+      const input = container.querySelector('input[type="radio"]')!;
+      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/RadioList.tsx

@@ -111,6 +111,13 @@ export interface RadioListProps extends Omit<
    * @default false
    */
   isDisabled?: boolean;
+
+  /**
+   * The HTML name attribute shared by the radio inputs in the group.
+   * Useful for form submissions; when omitted, a unique internal name is
+   * generated so the group still roves correctly.
+   */
+  htmlName?: string;
   /**
    * Explains why the radio group is disabled. Applies to the whole-group
    * disabled state (`isDisabled`), not individual items. When set together with
@@ -199,9 +206,11 @@ export function RadioList({
   className,
   style,
   'data-testid': dataTestId,
+  htmlName,
   children,
 }: RadioListProps) {
-  const name = useId();
+  const autoName = useId();
+  const name = htmlName ?? autoName;
   const inputID = useId();
   const labelID = useId();
   const descriptionID = useId();

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) {
@@ -254,6 +257,10 @@ export function RadioListItem({
         checked={isChecked}
         disabled={isDisabled && !keepsFocusableForMessage}
         aria-disabled={keepsFocusableForMessage ? 'true' : undefined}
+        // A focusable-disabled radio is not natively disabled, so detach it
+        // from the form instead: it keeps its name (grouping) but is excluded
+        // from submission, matching a natively disabled control.
+        form={keepsFocusableForMessage ? '' : undefined}
         required={context.isRequired}
         onChange={() => {
           if (isDisabled) {
@@ -309,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={