@astryxdesign/core 0.1.2 → 0.1.3

package/src/TextInput/TextInput.test.tsx

@@ -9,12 +9,43 @@
  * SYNC: When TextInput.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 {MagnifyingGlassIcon} from '@heroicons/react/24/outline';
 import {TextInput} from './TextInput';
 
+// 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('TextInput', () => {
   it('renders with label', () => {
     render(<TextInput label="Name" value="" onChange={() => {}} />);
@@ -62,31 +93,20 @@ describe('TextInput', () => {
 
   it('displays controlled value', () => {
     render(
-      <TextInput
-        label="Name"
-        value="Controlled value"
-        onChange={() => {}}
-      />,
+      <TextInput label="Name" value="Controlled value" onChange={() => {}} />,
     );
     expect(screen.getByRole('textbox')).toHaveValue('Controlled value');
   });
 
   it('forwards ref correctly', () => {
     const ref = vi.fn();
-    render(
-      <TextInput ref={ref} label="Name" value="" onChange={() => {}} />,
-    );
+    render(<TextInput ref={ref} label="Name" value="" onChange={() => {}} />);
     expect(ref).toHaveBeenCalledWith(expect.any(HTMLInputElement));
   });
 
   it('visually hides label when isLabelHidden is true', () => {
     render(
-      <TextInput
-        label="Search"
-        isLabelHidden
-        value=""
-        onChange={() => {}}
-      />,
+      <TextInput label="Search" isLabelHidden value="" onChange={() => {}} />,
     );
     const label = screen.getByText('Search');
     expect(label).toBeInTheDocument();
@@ -116,9 +136,7 @@ describe('TextInput', () => {
   });
 
   it('sets disabled attribute when isDisabled is true', () => {
-    render(
-      <TextInput label="Name" isDisabled value="" onChange={() => {}} />,
-    );
+    render(<TextInput label="Name" isDisabled value="" onChange={() => {}} />);
     expect(screen.getByRole('textbox')).toBeDisabled();
   });
 
@@ -410,12 +428,7 @@ describe('TextInput', () => {
   describe('hasClear', () => {
     it('shows clear button when hasClear is true and value is non-empty', () => {
       render(
-        <TextInput
-          label="Name"
-          value="hello"
-          onChange={() => {}}
-          hasClear
-        />,
+        <TextInput label="Name" value="hello" onChange={() => {}} hasClear />,
       );
       expect(
         screen.getByRole('button', {name: 'Clear Name'}),
@@ -423,9 +436,7 @@ describe('TextInput', () => {
     });
 
     it('does not show clear button when value is empty', () => {
-      render(
-        <TextInput label="Name" value="" onChange={() => {}} hasClear />,
-      );
+      render(<TextInput label="Name" value="" onChange={() => {}} hasClear />);
       expect(
         screen.queryByRole('button', {name: 'Clear Name'}),
       ).not.toBeInTheDocument();
@@ -457,12 +468,7 @@ describe('TextInput', () => {
       const user = userEvent.setup();
       const onChange = vi.fn();
       render(
-        <TextInput
-          label="Name"
-          value="hello"
-          onChange={onChange}
-          hasClear
-        />,
+        <TextInput label="Name" value="hello" onChange={onChange} hasClear />,
       );
       await user.click(screen.getByRole('button', {name: 'Clear Name'}));
       expect(onChange).toHaveBeenCalledWith('', null);
@@ -524,4 +530,132 @@ describe('TextInput', () => {
       expect(fieldRoot.getAttribute('style') ?? '').not.toContain('100%');
     });
   });
+
+  describe('disabledMessage', () => {
+    it('shows the reason tooltip on hover when disabled with a reason', async () => {
+      render(
+        <TextInput
+          label="Owner"
+          value=""
+          onChange={() => {}}
+          isDisabled
+          disabledMessage="You need the Editor role"
+        />,
+      );
+
+      const input = screen.getByRole('textbox');
+      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(
+        <TextInput
+          label="Owner"
+          value=""
+          onChange={() => {}}
+          isDisabled
+          disabledMessage="You need the Editor role"
+        />,
+      );
+
+      const tooltip = screen.getByRole('tooltip', h);
+      await user.tab();
+      expect(screen.getByRole('textbox')).toHaveFocus();
+      await waitFor(() => {
+        expect(tooltip).toHaveAttribute('popover-open');
+      });
+    });
+
+    it('does not render a tooltip when not disabled', () => {
+      render(
+        <TextInput
+          label="Owner"
+          value=""
+          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(
+        <TextInput label="Owner" value="" onChange={() => {}} isDisabled />,
+      );
+      expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();
+    });
+
+    it('keeps the input focusable via aria-disabled when a reason is provided', () => {
+      render(
+        <TextInput
+          label="Owner"
+          value=""
+          onChange={() => {}}
+          isDisabled
+          disabledMessage="You need the Editor role"
+        />,
+      );
+      const input = screen.getByRole('textbox');
+      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(
+        <TextInput
+          label="Owner"
+          value=""
+          onChange={() => {}}
+          isDisabled
+          disabledMessage="You need the Editor role"
+        />,
+      );
+      const input = screen.getByRole('textbox');
+      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(
+        <TextInput
+          label="Owner"
+          value=""
+          onChange={onChange}
+          isDisabled
+          disabledMessage="You need the Editor role"
+        />,
+      );
+
+      const input = screen.getByRole('textbox');
+      await user.click(input);
+      await user.keyboard('hello');
+      expect(onChange).not.toHaveBeenCalled();
+      expect(input).toHaveValue('');
+    });
+
+    it('remains natively disabled when disabled without a reason', () => {
+      render(
+        <TextInput label="Owner" value="" onChange={() => {}} isDisabled />,
+      );
+      const input = screen.getByRole('textbox');
+      expect(input).toBeDisabled();
+      expect(input).not.toHaveAttribute('aria-disabled');
+    });
+  });
 });

package/src/TextInput/TextInput.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file TextInput.tsx
- * @input Uses React, useId, ChangeEvent, Field, Icon
+ * @input Uses React, useId, ChangeEvent, Field, Icon, InputGroupContext
  * @output Exports TextInput component, TextInputProps
  * @position Core implementation; consumed by index.ts, tested by TextInput.test.tsx
  *
@@ -47,6 +47,9 @@ import {
 } from '../Field';
 import {Icon, renderIconSlot, type IconType} from '../Icon';
 import {Spinner} from '../Spinner';
+import {useTooltip} from '../Tooltip';
+import {VisuallyHidden} from '../VisuallyHidden';
+import {getInputARIA} from '../utils';
 
 const styles = stylex.create({
   clearButton: {
@@ -162,6 +165,27 @@ export interface TextInputProps 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
+   * ```
+   * <TextInput
+   *   label="Owner"
+   *   value={owner}
+   *   isDisabled
+   *   disabledMessage="You need the Editor role to change this"
+   * />
+   * ```
+   */
+  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.
@@ -252,6 +276,7 @@ export function TextInput({
   isOptional = false,
   isRequired = false,
   isDisabled = false,
+  disabledMessage,
   startIcon,
   status,
   size: sizeProp,
@@ -276,6 +301,7 @@ export function TextInput({
   const size = useSize(sizeProp, 'md');
 
   const id = useId();
+  const inputLabelID = useId();
   const descriptionID = useId();
   const statusMessageID = useId();
   const inputRef = useRef<HTMLInputElement | null>(null);
@@ -286,6 +312,20 @@ export function TextInput({
   const [optimisticValue, setOptimisticValue] = useOptimistic(value);
   const isBusy = isLoading || optimisticValue !== value;
 
+  // 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 handleChange.
+  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',
@@ -301,15 +341,23 @@ export function TextInput({
     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,
+  );
 
   const handleChange = (e: 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
+    // optimistic value and callbacks never fire.
+    if (isDisabled) {
+      return;
+    }
     const newValue = e.target.value;
     onChange?.(newValue, e);
     if (changeAction && !e.defaultPrevented) {
@@ -336,7 +384,13 @@ export function TextInput({
 
   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(
@@ -355,6 +409,7 @@ export function TextInput({
         style,
       )}>
       {startIcon && renderIconSlot(startIcon, {size: 'sm', color: 'secondary'})}
+      {inputGroup && <VisuallyHidden id={inputLabelID}>{label}</VisuallyHidden>}
       <input
         {...rest}
         ref={mergeRefs(ref, inputRef)}
@@ -374,14 +429,19 @@ export function TextInput({
             : undefined
         }
         placeholder={placeholder}
-        disabled={isDisabled}
+        // With a disabledMessage the input keeps focusability via aria-disabled
+        // so the reason is focus-discoverable; readOnly + the handleChange guard
+        // keep the value from changing.
+        disabled={isDisabled && !showsDisabledMessage}
+        aria-disabled={showsDisabledMessage ? 'true' : undefined}
+        readOnly={showsDisabledMessage || undefined}
         autoFocus={hasAutoFocus}
         data-autofocus={hasAutoFocus || undefined}
         aria-describedby={ariaDescribedBy}
         aria-required={isRequired === true ? 'true' : undefined}
         aria-invalid={status?.type === 'error' ? 'true' : undefined}
         aria-busy={isBusy || undefined}
-        aria-label={inputGroup ? label : undefined}
+        aria-labelledby={ariaLabelledBy}
         {...stylex.props(styles.input, isDisabled && styles.inputDisabled)}
       />
       {hasClear && value !== '' && !isDisabled && (
@@ -405,7 +465,13 @@ export function TextInput({
   );
 
   if (inputGroup) {
-    return inputWrapper;
+    return (
+      <>
+        {inputWrapper}
+        {showsDisabledMessage &&
+          disabledMessageTooltip.renderTooltip(disabledMessage)}
+      </>
+    );
   }
 
   return (
@@ -430,6 +496,8 @@ export function TextInput({
       labelTooltip={labelTooltip}
       width={width}>
       {inputWrapper}
+      {showsDisabledMessage &&
+        disabledMessageTooltip.renderTooltip(disabledMessage)}
     </Field>
   );
 }

package/src/Thumbnail/Thumbnail.doc.mjs

@@ -126,11 +126,11 @@ export const docsDense = {
     description:
       'Compact square image preview. Shimmer while uploading, image on success, placeholder when empty. Use in chat composers, file lists, or small media previews.',
     bestPractices: [
-      {guidance: true, description: 'Always set label (file name) for a11y \u2014 powers screen reader announce + hover tooltip.'},
+      {guidance: true, description: 'Always set label (file name) for a11y; powers screen reader announce + hover tooltip.'},
       {guidance: true, description: 'isLoading w/o src \u2192 skeleton; isLoading w/ src \u2192 spinner overlay. Two distinct loading states.'},
-      {guidance: true, description: 'onClick adds button semantics + hover shadow \u2014 pair with lightbox for full preview.'},
-      {guidance: false, description: "Don't use for non-image files (PDF, xlsx) \u2014 use file attachment component with icon instead."},
-      {guidance: false, description: "Don't omit alt when src present \u2014 screen readers need image content description, not just label."},
+      {guidance: true, description: 'onClick adds button semantics + hover shadow; pair with lightbox for full preview.'},
+      {guidance: false, description: "Don't use for non-image files (PDF, xlsx); use file attachment component with icon instead."},
+      {guidance: false, description: "Don't omit alt when src present; screen readers need image content description, not just label."},
     ],
   },
   propDescriptions: {