@astryxdesign/core 0.1.2 → 0.1.3

package/src/PowerSearch/PowerSearch.doc.mjs

@@ -71,6 +71,12 @@ export const docs = {
       description: 'Disables the entire component.',
       default: 'false',
     },
+    {
+      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.',
+    },
     {
       name: 'status',
       type: 'InputStatus',
@@ -136,6 +142,7 @@ export const docs = {
       { guidance: true, description: 'Define clear, descriptive field names and aliases so users can quickly find the filter they need.' },
       { guidance: true, description: 'Provide a result count to give users feedback on how their filters affect the data set.' },
       { guidance: false, description: 'Use PowerSearch for simple keyword searches; a standard text input is more appropriate for single-field lookups.' },
+      { guidance: false, description: 'Wrap a disabled PowerSearch in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },
     ],
   },
 };
@@ -212,6 +219,12 @@ export const docsZh = {
       description: '禁用整个组件。',
       default: 'false',
     },
+    {
+      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.',
+    },
     {
       name: 'status',
       type: 'InputStatus',
@@ -269,6 +282,7 @@ export const docsZh = {
       { guidance: true, description: 'Define clear, descriptive field names and aliases so users can quickly find the filter they need.' },
       { guidance: true, description: 'Provide a result count to give users feedback on how their filters affect the data set.' },
       { guidance: false, description: 'Use PowerSearch for simple keyword searches; a standard text input is more appropriate for single-field lookups.' },
+      { guidance: false, description: 'Wrap a disabled PowerSearch in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },
     ],
   },
 };
@@ -284,6 +298,7 @@ export const docsDense = {
       { guidance: true, description: 'Define clear, descriptive field names and aliases so users can quickly find the filter they need.' },
       { guidance: true, description: 'Provide a result count to give users feedback on how their filters affect the data set.' },
       { guidance: false, description: 'Use PowerSearch for simple keyword searches; a standard text input is more appropriate for single-field lookups.' },
+      { guidance: false, description: 'Wrap a disabled PowerSearch in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },
     ],
   },
   propDescriptions: {

package/src/PowerSearch/PowerSearch.test.tsx

@@ -11,7 +11,7 @@
 
 import {useState} from 'react';
 import {describe, it, expect, vi, beforeAll, afterAll} from 'vitest';
-import {render, screen, act} from '@testing-library/react';
+import {render, screen, act, fireEvent, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {PowerSearch} from './PowerSearch';
 import type {PowerSearchConfig, PowerSearchFilter} from './types';
@@ -199,4 +199,100 @@ describe('PowerSearch', () => {
       expect(pasteResults).toEqual(typeResults);
     });
   });
+
+  describe('disabledMessage', () => {
+    const h = {hidden: true} as const;
+    const isOpen = (el: Element) => el.matches(':popover-open');
+
+    function renderSearch(props?: {onChange?: () => void}) {
+      return render(
+        <PowerSearch
+          config={config}
+          filters={[]}
+          onChange={props?.onChange ?? (() => {})}
+          isDisabled
+          disabledMessage="You need edit access to search"
+        />,
+      );
+    }
+
+    it('shows the reason tooltip on hover when disabled with a reason', async () => {
+      renderSearch();
+      const tooltip = screen.getByRole('tooltip', h);
+      expect(tooltip).toHaveTextContent('You need edit access to search');
+      const wrapper = screen.getByRole('group');
+      fireEvent.mouseEnter(wrapper);
+      await waitFor(() => expect(isOpen(tooltip)).toBe(true));
+      fireEvent.mouseLeave(wrapper);
+      await waitFor(() => expect(isOpen(tooltip)).toBe(false));
+    });
+
+    it('shows the reason tooltip on keyboard focus', async () => {
+      const user = userEvent.setup();
+      renderSearch();
+      const tooltip = screen.getByRole('tooltip', h);
+      await user.tab();
+      expect(screen.getByRole('combobox')).toHaveFocus();
+      await waitFor(() => expect(isOpen(tooltip)).toBe(true));
+    });
+
+    it('does not render a tooltip when not disabled', () => {
+      render(
+        <PowerSearch
+          config={config}
+          filters={[]}
+          onChange={() => {}}
+          disabledMessage="You need edit access to search"
+        />,
+      );
+      expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();
+    });
+
+    it('does not render a tooltip when disabled without a reason', () => {
+      render(
+        <PowerSearch
+          config={config}
+          filters={[]}
+          onChange={() => {}}
+          isDisabled
+        />,
+      );
+      expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();
+    });
+
+    it('keeps the input focusable via aria-disabled when a reason is provided', () => {
+      renderSearch();
+      const input = screen.getByRole('combobox');
+      expect(input).not.toBeDisabled();
+      expect(input).toHaveAttribute('aria-disabled', 'true');
+    });
+
+    it('links the reason tooltip via aria-describedby', () => {
+      renderSearch();
+      const input = screen.getByRole('combobox');
+      const tooltip = screen.getByRole('tooltip', h);
+      expect(input.getAttribute('aria-describedby')).toContain(tooltip.id);
+    });
+
+    it('blocks input while focusable-disabled', async () => {
+      const user = userEvent.setup();
+      renderSearch();
+      const input = screen.getByRole('combobox');
+      input.focus();
+      await user.keyboard('open');
+      expect((input as HTMLInputElement).value).toBe('');
+    });
+
+    it('keeps the input natively disabled when disabled without a reason', () => {
+      render(
+        <PowerSearch
+          config={config}
+          filters={[]}
+          onChange={() => {}}
+          isDisabled
+        />,
+      );
+      expect(screen.getByRole('combobox')).toBeDisabled();
+    });
+  });
 });

package/src/PowerSearch/PowerSearch.tsx

@@ -358,6 +358,16 @@ export interface PowerSearchProps extends Omit<
   isReadOnly?: boolean;
   /** Whether the input is disabled. @default false */
   isDisabled?: boolean;
+  /**
+   * Explains why the search is disabled. When set together with `isDisabled`,
+   * the search shows a tooltip with this text on hover and keyboard focus, and
+   * the input stays focusable (via `aria-disabled`) so the reason is
+   * discoverable by keyboard and assistive technology. Input stays blocked.
+   *
+   * Use this instead of wrapping a disabled PowerSearch in `Tooltip` — disabled
+   * controls don't emit the pointer events an external tooltip needs.
+   */
+  disabledMessage?: string;
   /**
    * Icon to display at the start of the input.
    * Accepts a ReactNode (e.g. `<Icon icon={SearchIcon} />`) or an SVG icon component directly.
@@ -508,6 +518,7 @@ export function PowerSearch({
   hasClear = true,
   isReadOnly = false,
   isDisabled = false,
+  disabledMessage,
   startIcon,
   onFocus,
   onBlur,
@@ -546,6 +557,9 @@ export function PowerSearch({
     hasLightDismiss: true,
     hasCloseButton: false,
     hasAutoFocus: false,
+    // The popup's own listbox/menu content is the exposed semantics; focus
+    // stays on the tokenizer input, so a modal dialog wrapper is incorrect.
+    role: 'none',
   });
 
   // Wrapper that manages layer visibility and tokenizer focus alongside state
@@ -795,9 +809,7 @@ export function PowerSearch({
         filter.value.value[0].photo
       ) {
         const entity = filter.value.value[0];
-        tokenIcon = (
-          <Avatar src={entity.photo} name={entity.label} size={16} />
-        );
+        tokenIcon = <Avatar src={entity.photo} name={entity.label} size={16} />;
       }
 
       return (
@@ -982,6 +994,7 @@ export function PowerSearch({
           startIcon={startIcon}
           endContent={combinedEndContent}
           isDisabled={isDisabled}
+          disabledMessage={disabledMessage}
           size={size}
           tokenOverflowBehavior={tokenOverflowBehavior}
           hasEntriesOnFocus

package/src/ProgressBar/ProgressBar.test.tsx

@@ -7,11 +7,19 @@ import {ProgressBar} from './ProgressBar';
 describe('ProgressBar', () => {
   it('renders with default props', () => {
     render(<ProgressBar value={50} label="Progress" />);
-    const meter = screen.getByRole('meter');
-    expect(meter).toBeInTheDocument();
-    expect(meter).toHaveAttribute('aria-valuenow', '50');
-    expect(meter).toHaveAttribute('aria-valuemin', '0');
-    expect(meter).toHaveAttribute('aria-valuemax', '100');
+    const progressbar = screen.getByRole('progressbar');
+    expect(progressbar).toBeInTheDocument();
+    expect(progressbar).toHaveAttribute('aria-valuenow', '50');
+    expect(progressbar).toHaveAttribute('aria-valuemin', '0');
+    expect(progressbar).toHaveAttribute('aria-valuemax', '100');
+  });
+
+  it('uses role="progressbar" (not "meter") for determinate progress', () => {
+    // A determinate ProgressBar conveys task completion, so it must be a
+    // progressbar (announced on update), not a meter (a static gauge).
+    render(<ProgressBar value={50} label="Progress" />);
+    expect(screen.getByRole('progressbar')).toBeInTheDocument();
+    expect(screen.queryByRole('meter')).not.toBeInTheDocument();
   });
 
   it('renders visible label by default', () => {
@@ -23,8 +31,8 @@ describe('ProgressBar', () => {
     render(<ProgressBar value={50} label="Hidden label" isLabelHidden />);
     const label = screen.getByText('Hidden label');
     expect(label).toBeInTheDocument();
-    const meter = screen.getByRole('meter');
-    expect(meter).toHaveAttribute('aria-labelledby');
+    const progressbar = screen.getByRole('progressbar');
+    expect(progressbar).toHaveAttribute('aria-labelledby');
   });
 
   it('shows value label when hasValueLabel is true', () => {
@@ -43,33 +51,33 @@ describe('ProgressBar', () => {
       />,
     );
     expect(screen.getByText('3 GB / 5 GB')).toBeInTheDocument();
-    const meter = screen.getByRole('meter');
-    expect(meter).toHaveAttribute('aria-valuetext', '3 GB / 5 GB');
+    const progressbar = screen.getByRole('progressbar');
+    expect(progressbar).toHaveAttribute('aria-valuetext', '3 GB / 5 GB');
   });
 
   it('sets aria-valuetext from formatValueLabel', () => {
     render(<ProgressBar value={50} label="Progress" />);
-    const meter = screen.getByRole('meter');
-    expect(meter).toHaveAttribute('aria-valuetext', '50%');
+    const progressbar = screen.getByRole('progressbar');
+    expect(progressbar).toHaveAttribute('aria-valuetext', '50%');
   });
 
   it('respects custom max', () => {
     render(<ProgressBar value={3} max={10} label="Steps" />);
-    const meter = screen.getByRole('meter');
-    expect(meter).toHaveAttribute('aria-valuenow', '3');
-    expect(meter).toHaveAttribute('aria-valuemax', '10');
+    const progressbar = screen.getByRole('progressbar');
+    expect(progressbar).toHaveAttribute('aria-valuenow', '3');
+    expect(progressbar).toHaveAttribute('aria-valuemax', '10');
   });
 
   it('clamps value to [0, max]', () => {
     const {rerender} = render(
       <ProgressBar value={150} max={100} label="Over" />,
     );
-    let meter = screen.getByRole('meter');
-    expect(meter).toHaveAttribute('aria-valuenow', '100');
+    let progressbar = screen.getByRole('progressbar');
+    expect(progressbar).toHaveAttribute('aria-valuenow', '100');
 
     rerender(<ProgressBar value={-10} max={100} label="Under" />);
-    meter = screen.getByRole('meter');
-    expect(meter).toHaveAttribute('aria-valuenow', '0');
+    progressbar = screen.getByRole('progressbar');
+    expect(progressbar).toHaveAttribute('aria-valuenow', '0');
   });
 
   it('forwards ref to outer container', () => {
@@ -95,14 +103,14 @@ describe('ProgressBar', () => {
       const {unmount} = render(
         <ProgressBar value={50} label={variant} variant={variant} />,
       );
-      expect(screen.getByRole('meter')).toBeInTheDocument();
+      expect(screen.getByRole('progressbar')).toBeInTheDocument();
       unmount();
     }
   });
 
   it('renders at fixed 8px track height', () => {
     render(<ProgressBar value={50} label="Progress" />);
-    expect(screen.getByRole('meter')).toBeInTheDocument();
+    expect(screen.getByRole('progressbar')).toBeInTheDocument();
   });
 
   it('shows value label with hidden label', () => {
@@ -121,15 +129,15 @@ describe('ProgressBar', () => {
     expect(screen.queryByText('42%')).not.toBeInTheDocument();
     const label = screen.getByText('Context usage');
     expect(label).toBeInTheDocument();
-    const meter = screen.getByRole('meter');
-    expect(meter).toHaveAttribute('aria-labelledby', label.id);
+    const progressbar = screen.getByRole('progressbar');
+    expect(progressbar).toHaveAttribute('aria-labelledby', label.id);
   });
 
   it('handles zero max gracefully', () => {
     render(<ProgressBar value={0} max={0} label="Empty" />);
-    const meter = screen.getByRole('meter');
-    expect(meter).toHaveAttribute('aria-valuenow', '0');
-    expect(meter).toHaveAttribute('aria-valuemax', '0');
+    const progressbar = screen.getByRole('progressbar');
+    expect(progressbar).toHaveAttribute('aria-valuenow', '0');
+    expect(progressbar).toHaveAttribute('aria-valuemax', '0');
   });
 
   // Disabled state
@@ -138,7 +146,7 @@ describe('ProgressBar', () => {
       render(
         <ProgressBar value={50} label="Canceled" isDisabled hasValueLabel />,
       );
-      expect(screen.getByRole('meter')).toBeInTheDocument();
+      expect(screen.getByRole('progressbar')).toBeInTheDocument();
       expect(screen.getByText('50%')).toBeInTheDocument();
     });
 

package/src/ProgressBar/ProgressBar.tsx

@@ -31,6 +31,7 @@ import {
 import {mergeProps} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
+import {VisuallyHidden} from '../VisuallyHidden';
 
 /**
  * Extensible variant map for ProgressBar.
@@ -313,14 +314,12 @@ export function ProgressBar({
           )}
         </div>
       ) : (
-        <span id={labelId} {...stylex.props(styles.visuallyHidden)}>
-          {label}
-        </span>
+        <VisuallyHidden id={labelId}>{label}</VisuallyHidden>
       )}
 
       {/* Progress track */}
       <div
-        role={isIndeterminate ? 'progressbar' : 'meter'}
+        role="progressbar"
         aria-valuenow={isIndeterminate ? undefined : clampedValue}
         aria-valuemin={isIndeterminate ? undefined : 0}
         aria-valuemax={isIndeterminate ? undefined : max}

package/src/RadioList/RadioList.doc.mjs

@@ -74,6 +74,12 @@ export const docs = {
       description: 'Whether all radio items are disabled.',
       default: 'false',
     },
+    {
+      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.',
+    },
     {
       name: 'isRequired',
       type: 'boolean',
@@ -121,6 +127,7 @@ export const docs = {
       { guidance: false, description: 'Use when multiple selections are needed; use CheckboxList instead.' },
       { guidance: false, description: 'Use for long lists; use Selector for better discoverability.' },
       { guidance: false, description: 'Use horizontal layout with more than 4 options; it wraps awkwardly.' },
+      { guidance: false, description: 'Wrap a disabled RadioList in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },
     ],
     anatomy: [
       {name: 'Header', required: false, description: 'Optional heading above the radio list.'},
@@ -142,6 +149,7 @@ export const docsZh = {
       { guidance: false, description: 'Use when multiple selections are needed; use CheckboxList instead.' },
       { guidance: false, description: 'Use for long lists; use Selector for better discoverability.' },
       { guidance: false, description: 'Use horizontal layout with more than 4 options; it wraps awkwardly.' },
+      { guidance: false, description: 'Wrap a disabled RadioList in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },
     ],
     anatomy: [
       {name: 'Header', required: false, description: 'Optional heading above the radio list.'},
@@ -165,6 +173,7 @@ export const docsDense = {
       { guidance: false, description: 'Use when multiple selections are needed; use CheckboxList instead.' },
       { guidance: false, description: 'Use for long lists; use Selector for better discoverability.' },
       { guidance: false, description: 'Use horizontal layout with more than 4 options; it wraps awkwardly.' },
+      { guidance: false, description: 'Wrap a disabled RadioList in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },
     ],
     anatomy: [
       {name: 'Header', required: false, description: 'Optional heading above the radio list.'},