@astryxdesign/core 0.1.2 → 0.1.3

package/src/NumberInput/NumberInput.doc.mjs

@@ -62,6 +62,12 @@ export const docs = {
       type: 'boolean',
       description: 'Whether the input is disabled.',
     },
+    {
+      name: 'disabledMessage',
+      type: 'string',
+      description:
+        'Explains why the input is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the input focusable via aria-disabled (the field becomes read-only). Use this instead of wrapping a disabled NumberInput in Tooltip.',
+    },
     {
       name: 'placeholder',
       type: 'string',
@@ -166,6 +172,7 @@ export const docs = {
       { guidance: true, description: 'Show units (e.g. "%" or "GB") so users know what the number represents.' },
       { guidance: false, description: 'Use NumberInput for free-form text that happens to contain numbers; use TextInput instead.' },
       { guidance: false, description: 'Set both isOptional and isRequired on the same field.' },
+      { guidance: false, description: "Wrap a disabled NumberInput in Tooltip to explain why it's disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead." },
     ],
     anatomy: [
       {name: 'Label', required: true, description: 'The label for the number input.'},
@@ -236,6 +243,12 @@ export const docsZh = {
       type: 'boolean',
       description: '输入框是否禁用。',
     },
+    {
+      name: 'disabledMessage',
+      type: 'string',
+      description:
+        '说明输入框被禁用的原因。与 isDisabled 一起使用时，在悬停/键盘聚焦时显示工具提示，并通过 aria-disabled 保持输入框可聚焦（字段变为只读）。请使用此属性，而不是用 Tooltip 包裹已禁用的 NumberInput。',
+    },
     {
       name: 'placeholder',
       type: 'string',
@@ -339,6 +352,7 @@ export const docsZh = {
       { guidance: true, description: 'Show units (e.g. "%" or "GB") so users know what the number represents.' },
       { guidance: false, description: 'Use NumberInput for free-form text that happens to contain numbers; use TextInput instead.' },
       { guidance: false, description: 'Set both isOptional and isRequired on the same field.' },
+      { guidance: false, description: "Wrap a disabled NumberInput in Tooltip to explain why it's disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead." },
     ],
     anatomy: [
       {name: 'Label', required: true, description: 'The label for the number input.'},
@@ -361,6 +375,7 @@ export const docsDense = {
       { guidance: true, description: 'Show units (e.g. "%" or "GB") so users know what the number represents.' },
       { guidance: false, description: 'Use NumberInput for free-form text that happens to contain numbers; use TextInput instead.' },
       { guidance: false, description: 'Set both isOptional and isRequired on the same field.' },
+      { guidance: false, description: "Wrap a disabled NumberInput in Tooltip to explain why it's disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead." },
     ],
     anatomy: [
       {name: 'Label', required: true, description: 'The label for the number input.'},
@@ -380,6 +395,8 @@ export const docsDense = {
     isOptional: 'Field optional (mutually exclusive w/ isRequired).',
     isRequired: 'Field required (mutually exclusive w/ isOptional).',
     isDisabled: 'Input disabled.',
+    disabledMessage:
+      'Explains why input is disabled. With isDisabled, shows tooltip on hover/focus + keeps input focusable via aria-disabled (field becomes read-only). Use instead of wrapping a disabled NumberInput in Tooltip.',
     placeholder: 'Placeholder text.',
     labelTooltip: 'Tooltip text in info icon at label end.',
     startIcon: 'Icon at input start.',

package/src/NumberInput/NumberInput.test.tsx

@@ -9,17 +9,46 @@
  * SYNC: When NumberInput.tsx changes, update tests to match new behavior
  */
 
-import {describe, it, expect, vi} from 'vitest';
-import {render, screen, fireEvent} from '@testing-library/react';
+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 {NumberInput} from './NumberInput';
 
+// Mock showPopover/hidePopover since jsdom does not implement them. Used by the
+// disabledMessage tooltip.
+beforeEach(() => {
+  HTMLElement.prototype.showPopover = vi.fn(function (this: HTMLElement) {
+    this.setAttribute('popover-open', '');
+    const event = new Event('toggle', {bubbles: false});
+    Object.defineProperty(event, 'newState', {value: 'open'});
+    this.dispatchEvent(event);
+  });
+  HTMLElement.prototype.hidePopover = vi.fn(function (this: HTMLElement) {
+    this.removeAttribute('popover-open');
+    const event = new Event('toggle', {bubbles: false});
+    Object.defineProperty(event, 'newState', {value: 'closed'});
+    this.dispatchEvent(event);
+  });
+  const originalMatches = HTMLElement.prototype.matches;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  (HTMLElement.prototype as any).matches = function (
+    selector: string,
+  ): boolean {
+    if (selector === ':popover-open') {
+      return this.hasAttribute('popover-open');
+    }
+    return originalMatches.call(this, selector);
+  };
+});
+
+// jsdom popover content is in the DOM but may not be "visible" in the
+// accessibility tree. Use hidden: true to find it.
+const h = {hidden: true} as const;
+
 describe('NumberInput', () => {
   it('renders with label', () => {
-    render(
-      <NumberInput label="Quantity" value={null} onChange={() => {}} />,
-    );
+    render(<NumberInput label="Quantity" value={null} onChange={() => {}} />);
     expect(screen.getByLabelText('Quantity')).toBeInTheDocument();
   });
 
@@ -41,9 +70,7 @@ describe('NumberInput', () => {
   });
 
   it('displays null for null value', () => {
-    render(
-      <NumberInput label="Quantity" value={null} onChange={() => {}} />,
-    );
+    render(<NumberInput label="Quantity" value={null} onChange={() => {}} />);
     expect(screen.getByRole('spinbutton')).toHaveValue(null);
   });
 
@@ -103,9 +130,7 @@ describe('NumberInput', () => {
   });
 
   it('does not set aria-required when isRequired is false', () => {
-    render(
-      <NumberInput label="Quantity" value={null} onChange={() => {}} />,
-    );
+    render(<NumberInput label="Quantity" value={null} onChange={() => {}} />);
     expect(screen.getByRole('spinbutton')).not.toHaveAttribute('aria-required');
   });
 
@@ -139,9 +164,7 @@ describe('NumberInput', () => {
   });
 
   it('is not disabled by default', () => {
-    render(
-      <NumberInput label="Quantity" value={null} onChange={() => {}} />,
-    );
+    render(<NumberInput label="Quantity" value={null} onChange={() => {}} />);
     expect(screen.getByRole('spinbutton')).not.toBeDisabled();
   });
 
@@ -176,12 +199,7 @@ describe('NumberInput', () => {
 
     it('sets max attribute', () => {
       render(
-        <NumberInput
-          label="Age"
-          value={null}
-          onChange={() => {}}
-          max={120}
-        />,
+        <NumberInput label="Age" value={null} onChange={() => {}} max={120} />,
       );
       expect(screen.getByRole('spinbutton')).toHaveAttribute('max', '120');
     });
@@ -204,11 +222,7 @@ describe('NumberInput', () => {
       const user = userEvent.setup();
       const handleChange = vi.fn();
       render(
-        <NumberInput
-          label="Quantity"
-          value={null}
-          onChange={handleChange}
-        />,
+        <NumberInput label="Quantity" value={null} onChange={handleChange} />,
       );
 
       const input = screen.getByRole('spinbutton');
@@ -497,6 +511,68 @@ describe('NumberInput', () => {
     });
   });
 
+  describe('invalid typed input feedback (WCAG 3.3.1)', () => {
+    it('sets aria-invalid="true" when typed input is unparseable', async () => {
+      const user = userEvent.setup();
+      render(
+        <NumberInput
+          label="Count"
+          value={null}
+          onChange={() => {}}
+          isIntegerOnly
+        />,
+      );
+
+      const input = screen.getByRole('spinbutton');
+      await user.click(input);
+      // "3.5" is invalid when isIntegerOnly is set
+      await user.type(input, '3.5');
+
+      expect(input).toHaveAttribute('aria-invalid', 'true');
+    });
+
+    it('does not set aria-invalid when typed input is valid', async () => {
+      const user = userEvent.setup();
+      render(<NumberInput label="Count" value={null} onChange={() => {}} />);
+
+      const input = screen.getByRole('spinbutton');
+      await user.click(input);
+      await user.type(input, '42');
+
+      expect(input).not.toHaveAttribute('aria-invalid');
+    });
+
+    it('announces an alert message when typed input is invalid', async () => {
+      const user = userEvent.setup();
+      render(
+        <NumberInput
+          label="Count"
+          value={null}
+          onChange={() => {}}
+          isIntegerOnly
+        />,
+      );
+
+      const input = screen.getByRole('spinbutton');
+      await user.click(input);
+      await user.type(input, '3.5');
+
+      expect(screen.getByRole('alert')).toHaveTextContent('Invalid number');
+    });
+
+    it('does not announce an alert message when input is valid', async () => {
+      const user = userEvent.setup();
+      render(<NumberInput label="Count" value={null} onChange={() => {}} />);
+
+      const input = screen.getByRole('spinbutton');
+      await user.click(input);
+      await user.type(input, '42');
+
+      expect(screen.getByRole('alert')).toHaveTextContent('');
+      expect(screen.queryByText('Invalid number')).not.toBeInTheDocument();
+    });
+  });
+
   it('renders tooltip info icon when labelTooltip is provided', () => {
     render(
       <NumberInput
@@ -510,9 +586,7 @@ describe('NumberInput', () => {
   });
 
   it('does not render tooltip icon when labelTooltip is not provided', () => {
-    render(
-      <NumberInput label="Quantity" value={null} onChange={() => {}} />,
-    );
+    render(<NumberInput label="Quantity" value={null} onChange={() => {}} />);
     expect(document.querySelector('svg')).not.toBeInTheDocument();
   });
 
@@ -530,9 +604,7 @@ describe('NumberInput', () => {
     });
 
     it('does not focus when hasAutoFocus is false', () => {
-      render(
-        <NumberInput label="Quantity" value={null} onChange={() => {}} />,
-      );
+      render(<NumberInput label="Quantity" value={null} onChange={() => {}} />);
       expect(screen.getByRole('spinbutton')).not.toHaveFocus();
     });
   });
@@ -554,9 +626,7 @@ describe('NumberInput', () => {
     });
 
     it('does not set name attribute when htmlName is not provided', () => {
-      render(
-        <NumberInput label="Quantity" value={null} onChange={() => {}} />,
-      );
+      render(<NumberInput label="Quantity" value={null} onChange={() => {}} />);
       expect(screen.getByRole('spinbutton')).not.toHaveAttribute('name');
     });
   });
@@ -590,12 +660,7 @@ describe('NumberInput', () => {
 
     it('does not show clear button when value is null', () => {
       render(
-        <NumberInput
-          label="Qty"
-          value={null}
-          onChange={() => {}}
-          hasClear
-        />,
+        <NumberInput label="Qty" value={null} onChange={() => {}} hasClear />,
       );
       expect(
         screen.queryByRole('button', {name: 'Clear Qty'}),
@@ -664,4 +729,141 @@ describe('NumberInput', () => {
       expect(input).toHaveFocus();
     });
   });
+
+  describe('disabledMessage', () => {
+    it('shows the reason tooltip on hover when disabled with a reason', async () => {
+      render(
+        <NumberInput
+          label="Quantity"
+          value={5}
+          onChange={() => {}}
+          isDisabled
+          disabledMessage="You need the Editor role"
+        />,
+      );
+
+      const input = screen.getByRole('spinbutton');
+      const container = input.parentElement as HTMLElement;
+      const tooltip = screen.getByRole('tooltip', h);
+      expect(tooltip).toHaveTextContent('You need the Editor role');
+
+      fireEvent.mouseEnter(container);
+      await waitFor(() => {
+        expect(tooltip).toHaveAttribute('popover-open');
+      });
+
+      fireEvent.mouseLeave(container);
+      await waitFor(() => {
+        expect(tooltip).not.toHaveAttribute('popover-open');
+      });
+    });
+
+    it('shows the reason tooltip on keyboard focus', async () => {
+      const user = userEvent.setup();
+      render(
+        <NumberInput
+          label="Quantity"
+          value={5}
+          onChange={() => {}}
+          isDisabled
+          disabledMessage="You need the Editor role"
+        />,
+      );
+
+      const tooltip = screen.getByRole('tooltip', h);
+      await user.tab();
+      expect(screen.getByRole('spinbutton')).toHaveFocus();
+      await waitFor(() => {
+        expect(tooltip).toHaveAttribute('popover-open');
+      });
+    });
+
+    it('does not render a tooltip when not disabled', () => {
+      render(
+        <NumberInput
+          label="Quantity"
+          value={5}
+          onChange={() => {}}
+          disabledMessage="You need the Editor role"
+        />,
+      );
+      expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();
+    });
+
+    it('does not render a tooltip when disabled without a reason', () => {
+      render(
+        <NumberInput
+          label="Quantity"
+          value={5}
+          onChange={() => {}}
+          isDisabled
+        />,
+      );
+      expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();
+    });
+
+    it('keeps the input focusable via aria-disabled when a reason is provided', () => {
+      render(
+        <NumberInput
+          label="Quantity"
+          value={5}
+          onChange={() => {}}
+          isDisabled
+          disabledMessage="You need the Editor role"
+        />,
+      );
+      const input = screen.getByRole('spinbutton');
+      expect(input).not.toBeDisabled();
+      expect(input).toHaveAttribute('aria-disabled', 'true');
+      expect(input).toHaveAttribute('readonly');
+    });
+
+    it('links the reason tooltip from the input via aria-describedby', () => {
+      render(
+        <NumberInput
+          label="Quantity"
+          value={5}
+          onChange={() => {}}
+          isDisabled
+          disabledMessage="You need the Editor role"
+        />,
+      );
+      const input = screen.getByRole('spinbutton');
+      const tooltip = screen.getByRole('tooltip', h);
+      expect(input.getAttribute('aria-describedby')).toContain(tooltip.id);
+    });
+
+    it('blocks value changes while focusable-disabled', async () => {
+      const user = userEvent.setup();
+      const onChange = vi.fn();
+      render(
+        <NumberInput
+          label="Quantity"
+          value={5}
+          onChange={onChange}
+          isDisabled
+          disabledMessage="You need the Editor role"
+        />,
+      );
+
+      const input = screen.getByRole('spinbutton');
+      await user.click(input);
+      await user.keyboard('9');
+      expect(onChange).not.toHaveBeenCalled();
+    });
+
+    it('remains natively disabled when disabled without a reason', () => {
+      render(
+        <NumberInput
+          label="Quantity"
+          value={5}
+          onChange={() => {}}
+          isDisabled
+        />,
+      );
+      const input = screen.getByRole('spinbutton');
+      expect(input).toBeDisabled();
+      expect(input).not.toHaveAttribute('aria-disabled');
+    });
+  });
 });

package/src/NumberInput/NumberInput.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file NumberInput.tsx
- * @input Uses React, useId, useState, useMemo, useCallback, Field, Icon
+ * @input Uses React, useId, useState, useMemo, useCallback, Field, Icon, InputGroupContext
  * @output Exports NumberInput component, NumberInputProps
  * @position Core implementation; consumed by index.ts, tested by NumberInput.test.tsx
  *
@@ -46,6 +46,9 @@ import {
   inputStatusFocusWithinStyles,
 } from '../Field';
 import {Icon, renderIconSlot, type IconType} from '../Icon';
+import {VisuallyHidden} from '../VisuallyHidden';
+import {useTooltip} from '../Tooltip';
+import {getInputARIA} from '../utils';
 import {useSize} from '../SizeContext/SizeContext';
 import {useInputContainer} from '../hooks/useInputContainer';
 import {useInputGroup} from '../InputGroup/InputGroupContext';
@@ -167,6 +170,27 @@ interface NumberInputPropsBase extends Omit<
    * @default false
    */
   isDisabled?: boolean;
+  /**
+   * Explains why the input is disabled. When set together with `isDisabled`,
+   * the input shows a tooltip with this text on hover and keyboard focus, and
+   * stays focusable (via `aria-disabled`) so the reason is discoverable by
+   * keyboard and assistive technology. The field cannot be edited (it becomes
+   * read-only) while disabled.
+   *
+   * Use this instead of wrapping a disabled input in `Tooltip` — disabled
+   * controls don't emit the pointer events an external tooltip needs.
+   *
+   * @example
+   * ```
+   * <NumberInput
+   *   label="Quantity"
+   *   value={quantity}
+   *   isDisabled
+   *   disabledMessage="Editing is locked while the order is processing"
+   * />
+   * ```
+   */
+  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.
@@ -346,6 +370,7 @@ export function NumberInput({
   isOptional = false,
   isRequired = false,
   isDisabled = false,
+  disabledMessage,
   startIcon,
   labelIcon,
   status,
@@ -376,6 +401,7 @@ export function NumberInput({
 }: NumberInputProps) {
   const size = useSize(sizeProp, 'md');
   const id = useId();
+  const inputLabelID = useId();
   const descriptionID = useId();
   const statusMessageID = useId();
   const inputRef = useRef<HTMLInputElement | null>(null);
@@ -385,6 +411,20 @@ export function NumberInput({
   // Pending input while user is typing (null = show formatted value)
   const [pendingInput, setPendingInput] = useState<string | null>(null);
 
+  // Disabled-reason tooltip. Disabled controls swallow pointer events, so the
+  // tooltip listeners attach to the input container (which already exists) and
+  // the input stays perceivable via aria-disabled instead of the native
+  // disabled attribute. The field is made read-only so it can't be typed into,
+  // and value mutation is blocked by the isDisabled guard in the handlers.
+  const showsDisabledMessage = isDisabled && !!disabledMessage;
+  const disabledMessageTooltip = useTooltip({
+    placement: 'above',
+    // The container div is not naturally focusable; focusin bubbles up from
+    // the input, so always attach focus listeners.
+    focusTrigger: 'always',
+    isEnabled: showsDisabledMessage,
+  });
+
   const statusIconMap: Record<InputStatusType, IconName> = {
     warning: 'warning',
     error: 'error',
@@ -400,13 +440,15 @@ export function NumberInput({
     success: 'success',
   };
 
-  const ariaDescribedBy =
+  const {ariaLabelledBy, ariaDescribedBy} = getInputARIA(
+    inputLabelID,
     [
       description ? descriptionID : null,
       status?.message ? statusMessageID : null,
-    ]
-      .filter(Boolean)
-      .join(' ') || undefined;
+      showsDisabledMessage ? disabledMessageTooltip.describedBy : null,
+    ],
+    inputGroup,
+  );
 
   // Display value: pending input if typing, otherwise the raw value
   // Note: With type="number", we can't use formatted display values
@@ -431,6 +473,12 @@ export function NumberInput({
   // Handle input text change - update immediately if valid
   const handleInputChange = useCallback(
     (e: React.ChangeEvent<HTMLInputElement>) => {
+      // Value can't change while showing a disabled message (the field is
+      // read-only and non-native-disabled), but guard the handler too so the
+      // pending value and onChange never fire.
+      if (isDisabled) {
+        return;
+      }
       const newValue = e.target.value;
       setPendingInput(newValue);
 
@@ -440,7 +488,7 @@ export function NumberInput({
         onChange(parsed);
       }
     },
-    [value, onChange, min, max, isIntegerOnly],
+    [value, onChange, min, max, isIntegerOnly, isDisabled],
   );
 
   // Handle focus
@@ -522,7 +570,13 @@ export function NumberInput({
 
   const inputWrapper = (
     <div
-      ref={containerRef}
+      ref={el => {
+        containerRef.current = el;
+        // Anchor + hover/focus listeners for the disabled-message tooltip.
+        // Handlers are gated internally by isEnabled, and anchor names
+        // compose, so attaching unconditionally is safe.
+        disabledMessageTooltip.ref(el);
+      }}
       onClick={handleWrapperClick}
       onMouseUp={handleWrapperMouseUp}
       {...mergeProps(
@@ -542,6 +596,7 @@ export function NumberInput({
         style,
       )}>
       {startIcon && renderIconSlot(startIcon, {size: 'sm', color: 'secondary'})}
+      {inputGroup && <VisuallyHidden id={inputLabelID}>{label}</VisuallyHidden>}
       <input
         {...rest}
         ref={mergeRefs(ref, inputRef)}
@@ -555,7 +610,12 @@ export function NumberInput({
         onBlur={handleBlur}
         onKeyDown={handleKeyDown}
         placeholder={placeholder}
-        disabled={isDisabled}
+        // With a disabledMessage the input keeps focusability via aria-disabled
+        // so the reason is focus-discoverable; readOnly + the handler guards
+        // keep the value from changing.
+        disabled={isDisabled && !showsDisabledMessage}
+        aria-disabled={showsDisabledMessage ? 'true' : undefined}
+        readOnly={showsDisabledMessage || undefined}
         autoFocus={hasAutoFocus}
         data-autofocus={hasAutoFocus || undefined}
         min={min ?? undefined}
@@ -563,8 +623,10 @@ export function NumberInput({
         step={step ?? undefined}
         aria-describedby={ariaDescribedBy}
         aria-required={isRequired === true ? 'true' : undefined}
-        aria-invalid={status?.type === 'error' ? 'true' : undefined}
-        aria-label={inputGroup ? label : undefined}
+        aria-invalid={
+          status?.type === 'error' || !isInputValid ? 'true' : undefined
+        }
+        aria-labelledby={ariaLabelledBy}
         {...stylex.props(
           styles.input,
           isDisabled && styles.inputDisabled,
@@ -572,6 +634,14 @@ export function NumberInput({
         )}
       />
       {units && <span {...stylex.props(styles.units)}>{units}</span>}
+      {/*
+        Live region announcing invalid typed input to assistive technology.
+        The value silently reverts on blur, so without this a screen-reader
+        user would get no feedback that their entry was rejected (WCAG 3.3.1).
+      */}
+      <VisuallyHidden as="div" role="alert" aria-live="assertive">
+        {!isInputValid ? 'Invalid number' : ''}
+      </VisuallyHidden>
       {hasClear && value != null && !isDisabled && (
         <button
           type="button"
@@ -592,7 +662,13 @@ export function NumberInput({
   );
 
   if (inputGroup) {
-    return inputWrapper;
+    return (
+      <>
+        {inputWrapper}
+        {showsDisabledMessage &&
+          disabledMessageTooltip.renderTooltip(disabledMessage)}
+      </>
+    );
   }
 
   return (
@@ -618,6 +694,8 @@ export function NumberInput({
       labelTooltip={labelTooltip}
       width={width}>
       {inputWrapper}
+      {showsDisabledMessage &&
+        disabledMessageTooltip.renderTooltip(disabledMessage)}
     </Field>
   );
 }

package/src/Pagination/Pagination.doc.mjs

@@ -47,7 +47,7 @@ export const docs = {
     {
       name: 'pageSize',
       type: 'number',
-      description: 'Number of items per page.',
+      description: 'Number of items per page. Coerced to a positive integer; non-finite values fall back to the default.',
       default: '10',
     },
     {
@@ -175,7 +175,7 @@ export const docsZh = {
     {
       name: 'pageSize',
       type: 'number',
-      description: '每页项目数。',
+      description: '每页项目数。强制转换为正整数；非有限值回退到默认值。',
       default: '10',
     },
     {
@@ -277,7 +277,7 @@ export const docsDense = {
     totalItems: 'Total items. Calculates page count. Precedence over totalPages.',
     totalPages: 'Total pages. Use when page count known but not item count.',
     hasMore: 'More pages exist after current. For cursor-based pagination.',
-    pageSize: 'Items per page.',
+    pageSize: 'Items per page; coerced to positive integer, non-finite falls back to default',
     pageSizeOptions: 'Page size options. Shows selector dropdown when provided.',
     onPageSizeChange: 'Called on page size change. Auto resets to page 1.',
     variant: 'Display between prev/next buttons.',