@astryxdesign/core 0.1.1 → 0.1.2-canary.04e71b2

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>
   );
 }

package/src/Grid/Grid.doc.mjs

@@ -39,13 +39,23 @@ export const docs = {
     },
     {
       name: 'width',
-      type: 'number | string',
-      description: 'Container width.',
+      type: 'SizeValue',
+      description: 'Container width. Numbers are treated as pixels, strings are used as-is.',
     },
     {
       name: 'height',
-      type: 'number | string',
-      description: 'Container height.',
+      type: 'SizeValue',
+      description: 'Container height. Numbers are treated as pixels, strings are used as-is.',
+    },
+    {
+      name: 'maxWidth',
+      type: 'SizeValue',
+      description: 'Maximum container width. Numbers are treated as pixels, strings are used as-is.',
+    },
+    {
+      name: 'minHeight',
+      type: 'SizeValue',
+      description: 'Minimum container height. Numbers are treated as pixels, strings are used as-is.',
     },
     {
       name: 'gap',

package/src/Grid/Grid.tsx

@@ -83,6 +83,18 @@ export interface GridProps extends BaseProps<HTMLDivElement> {
    */
   height?: SizeValue;
 
+  /**
+   * Maximum width of the grid container.
+   * Numbers are treated as pixels, strings are used as-is (e.g., '100%').
+   */
+  maxWidth?: SizeValue;
+
+  /**
+   * Minimum height of the grid container.
+   * Numbers are treated as pixels, strings are used as-is (e.g., '100%').
+   */
+  minHeight?: SizeValue;
+
   /**
    * Spacing between all grid items (both row and column).
    * Accepts numeric spacing steps: 0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10.
@@ -346,6 +358,8 @@ export function Grid({
   rowHeight,
   width,
   height,
+  maxWidth,
+  minHeight,
   gap,
   rowGap,
   columnGap,
@@ -409,6 +423,12 @@ export function Grid({
     ...(height != null && {
       height: typeof height === 'number' ? `${height}px` : height,
     }),
+    ...(maxWidth != null && {
+      maxWidth: typeof maxWidth === 'number' ? `${maxWidth}px` : maxWidth,
+    }),
+    ...(minHeight != null && {
+      minHeight: typeof minHeight === 'number' ? `${minHeight}px` : minHeight,
+    }),
   };
 
   // For themeProps, extract numeric columns value for variant tracking

package/src/HoverCard/HoverCard.doc.mjs

@@ -108,6 +108,7 @@ export const docs = {
       { guidance: false, description: 'Place critical actions or required information inside a hover card; users may miss content that only appears on hover.' },
       { guidance: false, description: 'Use a hover card when a simple Tooltip or Popover would suffice.' },
       { guidance: false, description: 'Use a HoverCard for content the user must interact with; it disappears when the cursor leaves.' },
+      { guidance: false, description: 'Nest a HoverCard whose content has block elements directly inside phrasing-only contexts such as a <p>, <label>, or heading. The card renders inline, so block content there is invalid HTML the browser reparents. Wrap the surrounding text in a block element (e.g. a <div>) instead.' },
     ],
     anatomy: [
       {name: 'Trigger', required: true, description: 'The element that opens the hover card on hover or focus: a button, link, or inline text.'},
@@ -216,6 +217,7 @@ export const docsZh = {
       { guidance: false, description: 'Place critical actions or required information inside a hover card; users may miss content that only appears on hover.' },
       { guidance: false, description: 'Use a hover card when a simple Tooltip or Popover would suffice.' },
       { guidance: false, description: 'Use a HoverCard for content the user must interact with; it disappears when the cursor leaves.' },
+      { guidance: false, description: 'Nest a HoverCard whose content has block elements directly inside phrasing-only contexts such as a <p>, <label>, or heading. The card renders inline, so block content there is invalid HTML the browser reparents. Wrap the surrounding text in a block element (e.g. a <div>) instead.' },
     ],
   },
 };
@@ -233,6 +235,7 @@ export const docsDense = {
       { guidance: false, description: 'Place critical actions or required information inside a hover card; users may miss content that only appears on hover.' },
       { guidance: false, description: 'Use a hover card when a simple Tooltip or Popover would suffice.' },
       { guidance: false, description: 'Use a HoverCard for content the user must interact with; it disappears when the cursor leaves.' },
+      { guidance: false, description: 'Nest a block-content HoverCard directly inside phrasing-only contexts (<p>, <label>, heading); it renders inline so block content is invalid HTML there. Wrap surrounding text in a block element instead.' },
     ],
   },
   components: [