@astryxdesign/core 0.1.2 → 0.1.3-canary.6d57c8d

package/src/FileInput/FileInput.doc.mjs

@@ -88,6 +88,12 @@ export const docs = {
         'Disables the input, preventing interaction and dimming the element.',
       default: 'false',
     },
+    {
+      name: 'disabledMessage',
+      type: 'string',
+      description:
+        'Explains why the input is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the trigger focusable via aria-disabled (opening the file picker stays blocked). Use this instead of wrapping a disabled FileInput in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+    },
     {
       name: 'isLoading',
       type: 'boolean',
@@ -135,6 +141,7 @@ export const docs = {
       {guidance: true, description: 'Use changeAction for immediate upload workflows that benefit from optimistic UI.'},
       {guidance: false, description: "Don't use FileInput for directory or folder uploads; that is not supported in v1."},
       {guidance: false, description: "Don't avoid dropzone mode unless space is constrained; drag-and-drop is the expected interaction for file uploads."},
+      {guidance: false, description: "Don't wrap a disabled FileInput 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: 'Text that identifies the field. Always rendered for accessibility even when visually hidden.'},
@@ -211,6 +218,12 @@ export const docsZh = {
       description: '禁用输入框，阻止交互并使元素变暗。',
       default: 'false',
     },
+    {
+      name: 'disabledMessage',
+      type: 'string',
+      description:
+        '说明输入框被禁用的原因。与 isDisabled 一起使用时，在悬停/键盘聚焦时显示工具提示，并通过 aria-disabled 保持触发器可聚焦（打开文件选择器仍被阻止）。请使用此属性，而不是用 Tooltip 包裹已禁用的 FileInput。',
+    },
     {
       name: 'isLoading',
       type: 'boolean',
@@ -248,6 +261,7 @@ export const docsZh = {
       {guidance: true, description: 'Add a description to communicate constraints.'},
       {guidance: false, description: "Don't use FileInput for directory uploads."},
       {guidance: false, description: "Don't use mode='input' unless space is constrained; dropzone mode provides a better experience."},
+      {guidance: false, description: "Don't wrap a disabled FileInput in Tooltip to explain the disabled state; use the disabledMessage prop instead."},
     ],
     anatomy: [
       {name: 'Label', required: true, description: 'Text identifying the field.'},
@@ -272,6 +286,7 @@ export const docsDense = {
       {guidance: true, description: 'Use changeAction for immediate upload workflows that benefit from optimistic UI.'},
       {guidance: false, description: "Don't use FileInput for directory uploads."},
       {guidance: false, description: "Don't use mode='input' unless space is constrained; dropzone mode provides a better experience."},
+      {guidance: false, description: "Don't wrap a disabled FileInput in Tooltip to explain the disabled state; use the disabledMessage prop instead."},
     ],
     anatomy: [
       {name: 'Label', required: true, description: 'Text identifying the field.'},
@@ -295,6 +310,8 @@ export const docsDense = {
     isOptional: 'Shows "Optional" indicator.',
     isRequired: 'Shows "Required" indicator+sets aria-required.',
     isDisabled: 'Disables input, prevents interaction.',
+    disabledMessage:
+      'Explains why input is disabled. With isDisabled, shows tooltip on hover/focus + keeps trigger focusable via aria-disabled (opening picker stays blocked). Use instead of wrapping a disabled FileInput in Tooltip.',
     isLoading: 'Loading state w/ spinner+aria-busy.',
     placeholder: 'Placeholder when no files selected.',
     mode: "Visual mode: 'input' (compact) or 'dropzone' (drag-and-drop).",

package/src/FileInput/FileInput.test.tsx

@@ -9,10 +9,64 @@
  * SYNC: When FileInput.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, afterEach, beforeEach} from 'vitest';
+import {render, screen, fireEvent, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {FileInput} from './FileInput';
+import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
+
+afterEach(() => {
+  __resetLiveRegionsForTest();
+});
+
+// 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');
+    }
+    // jsdom does not resolve :focus-visible for role="button" divs the way a
+    // browser does after keyboard focus; treat the active element as
+    // focus-visible so the tooltip's keyboard-focus path is exercised.
+    if (selector === ':focus-visible') {
+      return this === document.activeElement;
+    }
+    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;
+
+function politeRegion(): HTMLElement | null {
+  return document.querySelector('[data-astryx-live-region="polite"]');
+}
+
+function fileInputEl(): HTMLInputElement {
+  const el = document.querySelector('input[type="file"]');
+  if (!(el instanceof HTMLInputElement)) {
+    throw new Error('file input not found');
+  }
+  return el;
+}
 
 function createFile(
   name: string,
@@ -36,12 +90,7 @@ describe('FileInput', () => {
 
   it('renders default placeholder for multiple files', () => {
     render(
-      <FileInput
-        label="Files"
-        value={null}
-        onChange={() => {}}
-        isMultiple
-      />,
+      <FileInput label="Files" value={null} onChange={() => {}} isMultiple />,
     );
     expect(screen.getByText('Choose files')).toBeInTheDocument();
   });
@@ -67,12 +116,7 @@ describe('FileInput', () => {
   it('displays multiple file names', () => {
     const files = [createFile('a.txt', 100), createFile('b.txt', 200)];
     render(
-      <FileInput
-        label="Files"
-        value={files}
-        onChange={() => {}}
-        isMultiple
-      />,
+      <FileInput label="Files" value={files} onChange={() => {}} isMultiple />,
     );
     expect(screen.getByText('a.txt, b.txt')).toBeInTheDocument();
   });
@@ -80,12 +124,7 @@ describe('FileInput', () => {
   it('forwards ref to the native input', () => {
     const ref = vi.fn();
     render(
-      <FileInput
-        ref={ref}
-        label="Upload"
-        value={null}
-        onChange={() => {}}
-      />,
+      <FileInput ref={ref} label="Upload" value={null} onChange={() => {}} />,
     );
     expect(ref).toHaveBeenCalledWith(expect.any(HTMLInputElement));
   });
@@ -103,32 +142,44 @@ describe('FileInput', () => {
   });
 
   it('sets aria-required when isRequired is true', () => {
+    render(
+      <FileInput label="Resume" isRequired value={null} onChange={() => {}} />,
+    );
+    // aria-required lives on the focusable role="button" wrapper, not the
+    // hidden file input (forms-6).
+    expect(screen.getByRole('button', {name: 'Resume'})).toHaveAttribute(
+      'aria-required',
+      'true',
+    );
+  });
+
+  it('places aria-describedby on the focusable button, not the hidden input (forms-6)', () => {
     render(
       <FileInput
         label="Resume"
-        isRequired
+        description="PDF only"
         value={null}
         onChange={() => {}}
       />,
     );
+    const button = screen.getByRole('button', {name: 'Resume'});
+    expect(button).toHaveAttribute('aria-describedby');
+    // The hidden file input no longer carries the describedby/required/invalid.
     const input = document.querySelector('input[type="file"]')!;
-    expect(input).toHaveAttribute('aria-required', 'true');
+    expect(input).not.toHaveAttribute('aria-describedby');
+    expect(input).toHaveAttribute('aria-hidden', 'true');
   });
 
   it('does not set aria-required by default', () => {
     render(<FileInput label="Resume" value={null} onChange={() => {}} />);
-    const input = document.querySelector('input[type="file"]')!;
-    expect(input).not.toHaveAttribute('aria-required');
+    expect(screen.getByRole('button', {name: 'Resume'})).not.toHaveAttribute(
+      'aria-required',
+    );
   });
 
   it('sets disabled attribute when isDisabled is true', () => {
     render(
-      <FileInput
-        label="Upload"
-        isDisabled
-        value={null}
-        onChange={() => {}}
-      />,
+      <FileInput label="Upload" isDisabled value={null} onChange={() => {}} />,
     );
     const input = document.querySelector('input[type="file"]')!;
     expect(input).toBeDisabled();
@@ -143,8 +194,10 @@ describe('FileInput', () => {
         status={{type: 'error', message: 'Something went wrong'}}
       />,
     );
-    const input = document.querySelector('input[type="file"]')!;
-    expect(input).toHaveAttribute('aria-invalid', 'true');
+    expect(screen.getByRole('button', {name: 'Upload'})).toHaveAttribute(
+      'aria-invalid',
+      'true',
+    );
   });
 
   it('does not set aria-invalid for warning status', () => {
@@ -156,8 +209,9 @@ describe('FileInput', () => {
         status={{type: 'warning'}}
       />,
     );
-    const input = document.querySelector('input[type="file"]')!;
-    expect(input).not.toHaveAttribute('aria-invalid');
+    expect(screen.getByRole('button', {name: 'Upload'})).not.toHaveAttribute(
+      'aria-invalid',
+    );
   });
 
   it('renders status message when provided', () => {
@@ -187,9 +241,7 @@ describe('FileInput', () => {
   describe('file selection via native input', () => {
     it('calls onChange when a file is selected', () => {
       const handleChange = vi.fn();
-      render(
-        <FileInput label="Upload" value={null} onChange={handleChange} />,
-      );
+      render(<FileInput label="Upload" value={null} onChange={handleChange} />);
       const input = document.querySelector(
         'input[type="file"]',
       ) as HTMLInputElement;
@@ -247,6 +299,55 @@ describe('FileInput', () => {
     });
   });
 
+  describe('announcements', () => {
+    it('announces a single file selection politely', async () => {
+      render(<FileInput label="Upload" value={null} onChange={() => {}} />);
+      fireEvent.change(fileInputEl(), {
+        target: {files: [createFile('report.pdf', 100)]},
+      });
+      await waitFor(() => {
+        expect(politeRegion()).toHaveTextContent('1 file selected: report.pdf');
+      });
+    });
+
+    it('announces a multi-file count politely', async () => {
+      render(
+        <FileInput
+          label="Upload"
+          value={null}
+          onChange={() => {}}
+          isMultiple
+        />,
+      );
+      const files = [
+        createFile('a.txt', 100),
+        createFile('b.txt', 200),
+        createFile('c.txt', 300),
+      ];
+      fireEvent.change(fileInputEl(), {target: {files}});
+      await waitFor(() => {
+        expect(politeRegion()).toHaveTextContent('3 files selected');
+      });
+    });
+
+    it('does not announce a selection when validation rejects all files', async () => {
+      render(
+        <FileInput
+          label="Upload"
+          value={null}
+          onChange={() => {}}
+          accept=".pdf"
+        />,
+      );
+      fireEvent.change(fileInputEl(), {
+        target: {files: [createFile('note.txt', 100)]},
+      });
+      // A rejected selection creates no polite region (only the error goes to
+      // the existing role="status" region).
+      expect(politeRegion()).toBeNull();
+    });
+  });
+
   describe('validation', () => {
     it('rejects files exceeding maxSize', () => {
       const handleChange = vi.fn();
@@ -382,9 +483,7 @@ describe('FileInput', () => {
       const user = userEvent.setup();
       const handleChange = vi.fn();
       const file = createFile('test.txt', 100);
-      render(
-        <FileInput label="Upload" value={file} onChange={handleChange} />,
-      );
+      render(<FileInput label="Upload" value={file} onChange={handleChange} />);
       await user.click(screen.getByRole('button', {name: 'Clear Upload'}));
       expect(handleChange).toHaveBeenCalledWith(null);
     });
@@ -392,12 +491,7 @@ describe('FileInput', () => {
     it('does not show clear button during loading', () => {
       const file = createFile('test.txt', 100);
       render(
-        <FileInput
-          label="Upload"
-          value={file}
-          onChange={() => {}}
-          isLoading
-        />,
+        <FileInput label="Upload" value={file} onChange={() => {}} isLoading />,
       );
       expect(
         screen.queryByRole('button', {name: 'Clear Upload'}),
@@ -426,9 +520,7 @@ describe('FileInput', () => {
 
     it('does not handle drop in input mode', () => {
       const handleChange = vi.fn();
-      render(
-        <FileInput label="Upload" value={null} onChange={handleChange} />,
-      );
+      render(<FileInput label="Upload" value={null} onChange={handleChange} />);
       const dropzone = screen.getByRole('button', {name: 'Upload'});
       const file = createFile('dropped.txt', 100);
       fireEvent.drop(dropzone, {
@@ -526,4 +618,146 @@ describe('FileInput', () => {
       expect(input).toHaveAttribute('data-testid', 'file-upload');
     });
   });
+
+  describe('disabledMessage', () => {
+    it('shows the reason tooltip on hover when disabled with a reason', async () => {
+      render(
+        <FileInput
+          label="Resume"
+          value={null}
+          onChange={() => {}}
+          isDisabled
+          disabledMessage="You need the Editor role"
+        />,
+      );
+
+      const trigger = screen.getByRole('button');
+      const tooltip = screen.getByRole('tooltip', h);
+      expect(tooltip).toHaveTextContent('You need the Editor role');
+
+      fireEvent.mouseEnter(trigger);
+      await waitFor(() => {
+        expect(tooltip).toHaveAttribute('popover-open');
+      });
+
+      fireEvent.mouseLeave(trigger);
+      await waitFor(() => {
+        expect(tooltip).not.toHaveAttribute('popover-open');
+      });
+    });
+
+    it('shows the reason tooltip on keyboard focus', async () => {
+      const user = userEvent.setup();
+      render(
+        <FileInput
+          label="Resume"
+          value={null}
+          onChange={() => {}}
+          isDisabled
+          disabledMessage="You need the Editor role"
+        />,
+      );
+
+      const tooltip = screen.getByRole('tooltip', h);
+      await user.tab();
+      expect(screen.getByRole('button')).toHaveFocus();
+      await waitFor(() => {
+        expect(tooltip).toHaveAttribute('popover-open');
+      });
+    });
+
+    it('does not render a tooltip when not disabled', () => {
+      render(
+        <FileInput
+          label="Resume"
+          value={null}
+          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(
+        <FileInput
+          label="Resume"
+          value={null}
+          onChange={() => {}}
+          isDisabled
+        />,
+      );
+      expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();
+    });
+
+    it('keeps the trigger focusable via aria-disabled when a reason is provided', () => {
+      render(
+        <FileInput
+          label="Resume"
+          value={null}
+          onChange={() => {}}
+          isDisabled
+          disabledMessage="You need the Editor role"
+        />,
+      );
+      const trigger = screen.getByRole('button');
+      expect(trigger).toHaveAttribute('aria-disabled', 'true');
+      expect(trigger).toHaveAttribute('tabindex', '0');
+    });
+
+    it('links the reason tooltip from the trigger via aria-describedby', () => {
+      render(
+        <FileInput
+          label="Resume"
+          value={null}
+          onChange={() => {}}
+          isDisabled
+          disabledMessage="You need the Editor role"
+        />,
+      );
+      const trigger = screen.getByRole('button');
+      const tooltip = screen.getByRole('tooltip', h);
+      expect(trigger.getAttribute('aria-describedby')).toContain(tooltip.id);
+    });
+
+    it('blocks opening the file picker while focusable-disabled', async () => {
+      const user = userEvent.setup();
+      render(
+        <FileInput
+          label="Resume"
+          value={null}
+          onChange={() => {}}
+          isDisabled
+          disabledMessage="You need the Editor role"
+        />,
+      );
+
+      const trigger = screen.getByRole('button');
+      const input = document.querySelector(
+        'input[type="file"]',
+      ) as HTMLInputElement;
+      const clickSpy = vi.spyOn(input, 'click');
+
+      await user.click(trigger);
+      trigger.focus();
+      await user.keyboard('{Enter}');
+      await user.keyboard(' ');
+
+      expect(clickSpy).not.toHaveBeenCalled();
+    });
+
+    it('keeps the trigger non-focusable when disabled without a reason', () => {
+      render(
+        <FileInput
+          label="Resume"
+          value={null}
+          onChange={() => {}}
+          isDisabled
+        />,
+      );
+      const trigger = screen.getByRole('button');
+      expect(trigger).toHaveAttribute('tabindex', '-1');
+      expect(trigger).not.toHaveAttribute('aria-disabled');
+    });
+  });
 });

package/src/FileInput/FileInput.tsx

@@ -44,6 +44,8 @@ import {
 } from '../Field';
 import {Icon, type IconName} from '../Icon';
 import {Spinner} from '../Spinner';
+import {useAnnounce} from '../hooks/useAnnounce';
+import {useTooltip} from '../Tooltip';
 
 export type {
   InputStatus as FileInputStatus,
@@ -320,6 +322,27 @@ export interface FileInputProps extends Omit<
    * @default false
    */
   isDisabled?: boolean;
+  /**
+   * Explains why the input is disabled. When set together with `isDisabled`,
+   * the file input shows a tooltip with this text on hover and keyboard focus,
+   * and its trigger stays focusable (via `aria-disabled`) so the reason is
+   * discoverable by keyboard and assistive technology. Opening the file picker
+   * stays blocked.
+   *
+   * Use this instead of wrapping a disabled input in `Tooltip` — disabled
+   * controls don't emit the pointer events an external tooltip needs.
+   *
+   * @example
+   * ```
+   * <FileInput
+   *   label="Resume"
+   *   value={file}
+   *   isDisabled
+   *   disabledMessage="Uploads are locked until your profile is verified"
+   * />
+   * ```
+   */
+  disabledMessage?: string;
   /**
    * Whether the input is required.
    * @default false
@@ -386,6 +409,7 @@ export function FileInput({
   maxSize,
   maxFiles,
   isDisabled = false,
+  disabledMessage,
   isRequired = false,
   isLoading = false,
   status: statusProp,
@@ -410,6 +434,23 @@ export function FileInput({
   const [validationError, setValidationError] = useState<string | null>(null);
   const [, startTransition] = useTransition();
 
+  // Announce successful file selection to screen readers via a persistent
+  // live region (forms-17). The component's own role="status" region only
+  // carries validation errors, so a successful attach was previously silent.
+  const announce = useAnnounce();
+
+  // Disabled-reason tooltip. Disabled controls swallow pointer events, so the
+  // tooltip listeners attach to the role="button" trigger (which already
+  // exists) and the trigger stays perceivable via aria-disabled instead of the
+  // native disabled attribute. Opening the picker is blocked by the isDisabled
+  // guards in handleClick / handleKeyDown / handleFiles.
+  const showsDisabledMessage = isDisabled && !!disabledMessage;
+  const disabledMessageTooltip = useTooltip({
+    placement: 'above',
+    focusTrigger: 'always',
+    isEnabled: showsDisabledMessage,
+  });
+
   const status =
     statusProp ??
     (validationError
@@ -435,6 +476,7 @@ export function FileInput({
     [
       description ? descriptionID : null,
       status?.message ? statusMessageID : null,
+      showsDisabledMessage ? disabledMessageTooltip.describedBy : null,
     ]
       .filter(Boolean)
       .join(' ') || undefined;
@@ -470,6 +512,17 @@ export function FileInput({
       const result = isMultiple ? valid : valid[0];
       onChange(result);
 
+      // Announce the successful selection politely. Validation errors are
+      // handled by the role="status" region below, so only announce the
+      // attach here (do not double-announce errors).
+      if (errors.length === 0) {
+        announce(
+          valid.length === 1
+            ? `1 file selected: ${valid[0].name}`
+            : `${valid.length} files selected`,
+        );
+      }
+
       if (changeAction) {
         startTransition(async () => {
           await changeAction(result);
@@ -485,6 +538,7 @@ export function FileInput({
       onChange,
       changeAction,
       startTransition,
+      announce,
     ],
   );
 
@@ -666,12 +720,28 @@ export function FileInput({
       labelTooltip={labelTooltip}
       width={width}>
       <div
+        ref={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);
+        }}
         role="button"
-        tabIndex={isDisabled ? -1 : 0}
+        // With a disabledMessage the trigger keeps focusability via
+        // aria-disabled so the reason is focus-discoverable; opening the picker
+        // is still blocked by the isDisabled guards in the handlers.
+        tabIndex={isDisabled && !showsDisabledMessage ? -1 : 0}
+        aria-disabled={showsDisabledMessage ? 'true' : undefined}
         onClick={handleClick}
         onKeyDown={handleKeyDown}
         aria-label={label}
         aria-busy={isLoading || undefined}
+        // These describe the operable control, so they belong on the focusable
+        // role="button" wrapper — not the hidden tabIndex={-1} file input the
+        // user never focuses (forms-6).
+        aria-describedby={ariaDescribedBy}
+        aria-required={isRequired ? 'true' : undefined}
+        aria-invalid={status?.type === 'error' ? 'true' : undefined}
         {...dragDropProps}
         {...mergeProps(
           themeProps('file-input', {mode, status: status?.type ?? null}),
@@ -696,9 +766,9 @@ export function FileInput({
           multiple={isMultiple}
           disabled={isDisabled}
           onChange={handleInputChange}
-          aria-describedby={ariaDescribedBy}
-          aria-required={isRequired ? 'true' : undefined}
-          aria-invalid={status?.type === 'error' ? 'true' : undefined}
+          // The visually-hidden native input is never focused (tabIndex={-1});
+          // its describedby/required/invalid live on the role="button" wrapper.
+          aria-hidden="true"
           tabIndex={-1}
           {...stylex.props(styles.hiddenInput)}
         />
@@ -714,6 +784,8 @@ export function FileInput({
         {...stylex.props(styles.liveRegion)}>
         {validationError}
       </div>
+      {showsDisabledMessage &&
+        disabledMessageTooltip.renderTooltip(disabledMessage)}
     </Field>
   );
 }