@astryxdesign/core 0.1.8 → 0.1.9-canary.02ef052

package/src/TextInput/TextInput.tsx

@@ -27,7 +27,6 @@ import {
   type ReactNode,
 } from 'react';
 import * as stylex from '@stylexjs/stylex';
-import type {IconName} from '../Icon';
 import {
   colorVars,
   sizeVars,
@@ -39,11 +38,11 @@ import {
 import {
   Field,
   type InputStatus,
-  type InputStatusType,
   inputWrapperStyles,
   inputStatusBorderStyles,
   inputStatusHoverShadowStyles,
   inputStatusFocusWithinStyles,
+  type FieldStatusVariant,
 } from '../Field';
 import {Icon, renderIconSlot, type IconType} from '../Icon';
 import {Spinner} from '../Spinner';
@@ -119,6 +118,7 @@ export type {
 import {mergeProps, mergeRefs} from '../utils';
 import {useSize} from '../SizeContext/SizeContext';
 import {useInputContainer} from '../hooks/useInputContainer';
+import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
 import {useInputGroup} from '../InputGroup/InputGroupContext';
 import type {BaseProps} from '../BaseProps';
 import type {SizeValue} from '../utils/types';
@@ -198,6 +198,14 @@ export interface TextInputProps extends Omit<
    * If message is provided, displays a floating message box below the input.
    */
   status?: InputStatus;
+  /**
+   * How the status message is placed relative to the input.
+   * - 'attached': message overlaps directly below the input (bordered treatment)
+   * - 'detached': message floats below as a separate element with spacing
+   * - 'tooltip': no message box; the status icon becomes a focusable info-tip button that reveals the message on hover, keyboard focus, or tap
+   * @default 'attached'
+   */
+  statusVariant?: FieldStatusVariant;
   /**
    * The size of the input.
    * - 'sm': Compact size (18px height)
@@ -280,6 +288,7 @@ export function TextInput({
   disabledMessage,
   startIcon,
   status,
+  statusVariant = 'attached',
   size: sizeProp,
   onChange,
   changeAction,
@@ -328,26 +337,25 @@ export function TextInput({
     isEnabled: showsDisabledMessage,
   });
 
-  const statusIconMap: Record<InputStatusType, IconName> = {
-    warning: 'warning',
-    error: 'error',
-    success: 'success',
-  };
-
-  const statusIconColorMap: Record<
-    InputStatusType,
-    'warning' | 'error' | 'success'
-  > = {
-    warning: 'warning',
-    error: 'error',
-    success: 'success',
-  };
+  const {statusIcon, describedBy: statusTooltipDescribedBy} =
+    useInputStatusIcon({
+      status,
+      statusVariant,
+      isInGroup: !!inputGroup,
+    });
 
   const {ariaLabelledBy, ariaDescribedBy} = getInputARIA(
     inputLabelID,
     [
       description ? descriptionID : null,
-      status?.message ? statusMessageID : null,
+      // The status message element is rendered by Field, which is skipped
+      // inside an InputGroup — only reference it when it actually exists.
+      !inputGroup && statusVariant !== 'tooltip' && status?.message
+        ? statusMessageID
+        : null,
+      // The tooltip variant renders no message box; describe the input by the
+      // tooltip's content instead so the status is still announced.
+      statusTooltipDescribedBy,
       showsDisabledMessage ? disabledMessageTooltip.describedBy : null,
     ],
     inputGroup,
@@ -402,7 +410,7 @@ export function TextInput({
           sizeStyles[size],
           isDisabled && inputWrapperStyles.disabled,
           status && inputStatusBorderStyles[status.type],
-          status && inputStatusHoverShadowStyles[status.type],
+          status && !isDisabled && inputStatusHoverShadowStyles[status.type],
           status && inputStatusFocusWithinStyles[status.type],
           inputGroup && groupStyles.inGroup,
           xstyle,
@@ -456,13 +464,7 @@ export function TextInput({
         </button>
       )}
       {isBusy && <Spinner size="sm" />}
-      {status && !inputGroup && (
-        <Icon
-          icon={statusIconMap[status.type]}
-          size="md"
-          color={statusIconColorMap[status.type]}
-        />
-      )}
+      {statusIcon}
     </div>
   );
 
@@ -495,6 +497,7 @@ export function TextInput({
             }
           : undefined
       }
+      statusVariant={statusVariant}
       labelTooltip={labelTooltip}
       width={width}>
       {inputWrapper}

package/src/Thumbnail/Thumbnail.doc.mjs

@@ -16,7 +16,7 @@ export const docs = {
     {
       name: 'alt',
       type: 'string',
-      description: 'Alt text for the image.',
+      description: 'Alt text for the image. When omitted, the image is explicitly decorative (alt="", role="presentation", aria-hidden) and hidden from screen readers; a dev warning fires if neither alt nor label is set.',
     },
     {
       name: 'label',
@@ -31,7 +31,7 @@ export const docs = {
     {
       name: 'onClick',
       type: '(e: React.MouseEvent) => void',
-      description: 'Click handler. Adds button semantics and hover shadow.',
+      description: 'Click handler. Adds button semantics and a hover overlay.',
     },
     {
       name: 'isLoading',
@@ -45,6 +45,13 @@ export const docs = {
       description: 'Whether the thumbnail is disabled.',
       default: 'false',
     },
+    {
+      name: 'showRemoveOn',
+      type: "'always' | 'hover'",
+      description:
+        'When the remove button is visible. `hover` (the default) reveals it on hover and on keyboard focus, and keeps it visible on any touch-capable device; `always` shows it at rest. Only applies when `onRemove` is set.',
+      default: "'hover'",
+    },
     {
       name: 'xstyle',
       type: 'StyleXStyles',
@@ -77,14 +84,14 @@ export const docs = {
     bestPractices: [
       {guidance: true, description: 'Always provide a label prop with the file name so the thumbnail and its remove button are accessible to screen readers and show a tooltip on hover.'},
       {guidance: true, description: 'Use isLoading without a src to show a skeleton during initial upload, and isLoading with a src to show a spinner overlay once a preview URL is available.'},
-      {guidance: true, description: 'Pair onClick with a lightbox or detail view so users can inspect the full image; the thumbnail adds button semantics and a hover shadow automatically.'},
+      {guidance: true, description: 'Pair onClick with a lightbox or detail view so users can inspect the full image; the thumbnail adds button semantics and a hover overlay automatically.'},
       {guidance: false, description: "Don't use Thumbnail for non-image file types like PDFs or spreadsheets; use a file attachment component with an appropriate icon instead."},
       {guidance: false, description: "Don't omit alt text when a src is provided; screen readers need a description of the image content, not just the file name from label."},
     ],
     anatomy: [
       {name: 'Image', required: false, description: 'The preview image, displayed as a square with cover fit.'},
       {name: 'Placeholder', required: false, description: 'An image silhouette icon shown when no src is provided.'},
-      {name: 'Remove button', required: false, description: 'An overlaid close button in the top-right corner. Appears when onRemove is set. Uses APCA luminance detection to stay visible on any image.'},
+      {name: 'Remove button', required: false, description: 'An overlaid close button in the top-right corner. Appears when onRemove is set. Sits on a fixed --color-overlay scrim with an --color-on-dark icon to stay visible on any image.'},
       {name: 'Upload overlay', required: false, description: 'A semi-transparent overlay with a spinner, shown when isLoading is true and a src preview is available.'},
       {name: 'Skeleton', required: false, description: 'A shimmer animation shown when isLoading is true and no src is set.'},
     ],
@@ -95,12 +102,13 @@ export const docs = {
 export const docsZh = {
   propDescriptions: {
     src: '\u56FE\u7247\u6E90 URL\u3002',
-    alt: '\u56FE\u7247\u7684\u66FF\u4EE3\u6587\u672C\u3002',
+    alt: '\u56FE\u7247\u7684\u66FF\u4EE3\u6587\u672C\u3002\u7701\u7565\u65F6\u56FE\u7247\u4F1A\u88AB\u663E\u5F0F\u6807\u8BB0\u4E3A\u88C5\u9970\u6027\uFF08alt=""\u3001role="presentation"\u3001aria-hidden\uFF09\u5E76\u5BF9\u5C4F\u5E55\u9605\u8BFB\u5668\u9690\u85CF\uFF1B\u82E5 alt \u548C label \u5747\u672A\u8BBE\u7F6E\uFF0C\u5F00\u53D1\u73AF\u5883\u4F1A\u53D1\u51FA\u8B66\u544A\u3002',
     label: '\u65E0\u969C\u788D\u6807\u7B7E\uFF08\u5982\u6587\u4EF6\u540D\uFF09\u3002\u60AC\u505C\u65F6\u4EE5\u63D0\u793A\u5DE5\u5177\u663E\u793A\u3002',
     onRemove: '\u8986\u76D6\u5C42\u79FB\u9664\u6309\u94AE\u7684\u56DE\u8C03\u3002',
-    onClick: '\u70B9\u51FB\u5904\u7406\u5668\u3002\u6DFB\u52A0\u6309\u94AE\u8BED\u4E49\u548C\u60AC\u505C\u9634\u5F71\u3002',
+    onClick: '\u70B9\u51FB\u5904\u7406\u5668\u3002\u6DFB\u52A0\u6309\u94AE\u8BED\u4E49\u548C\u60AC\u505C\u8986\u76D6\u5C42\u3002',
     isLoading: '\u663E\u793A\u9AA8\u67B6\u5C4F\uFF08\u65E0 src\uFF09\u6216\u4E0A\u4F20\u8986\u76D6\u5C42\uFF08\u6709 src\uFF09\u3002',
     isDisabled: '\u662F\u5426\u7981\u7528\u7F29\u7565\u56FE\u3002',
+    showRemoveOn: '\u4F55\u65F6\u663E\u793A\u79FB\u9664\u6309\u94AE\uFF1Ahover\uFF08\u9ED8\u8BA4\uFF0C\u60AC\u505C\u65F6\u4EE5\u53CA\u952E\u76D8\u805A\u7126\u65F6\u663E\u793A\uFF0C\u89E6\u6478\u8BBE\u5907\u4E0A\u4FDD\u6301\u53EF\u89C1\uFF09| always\uFF08\u59CB\u7EC8\u663E\u793A\uFF09\u3002\u4EC5\u5728\u8BBE\u7F6E onRemove \u65F6\u751F\u6548\u3002',
     xstyle: '\u7528\u4E8E\u5E03\u5C40\u81EA\u5B9A\u4E49\u7684 StyleX \u6837\u5F0F\u3002\u5FC5\u987B\u662F stylex.create() \u7684\u503C\uFF0C\u800C\u975E\u5185\u8054\u6837\u5F0F\u5BF9\u8C61\u3002',
     className: '\u6839\u5143\u7D20\u7684 CSS \u7C7B\u540D\u3002\u5EFA\u8BAE\u4F7F\u7528 xstyle\u3002',
     style: '\u6839\u5143\u7D20\u7684\u5185\u8054\u6837\u5F0F\u3002\u5EFA\u8BAE\u4F7F\u7528 xstyle\u3002',
@@ -112,7 +120,7 @@ export const docsZh = {
     bestPractices: [
       {guidance: true, description: '\u59CB\u7EC8\u63D0\u4F9B label \u5C5E\u6027\u5E76\u586B\u5199\u6587\u4EF6\u540D\uFF0C\u4EE5\u4FBF\u5C4F\u5E55\u9605\u8BFB\u5668\u80FD\u591F\u8BC6\u522B\u7F29\u7565\u56FE\u53CA\u5176\u79FB\u9664\u6309\u94AE\uFF0C\u5E76\u5728\u60AC\u505C\u65F6\u663E\u793A\u63D0\u793A\u3002'},
       {guidance: true, description: '\u4E0A\u4F20\u521D\u671F\u4F7F\u7528\u4E0D\u5E26 src \u7684 isLoading \u663E\u793A\u9AA8\u67B6\u5C4F\uFF1B\u83B7\u5F97\u9884\u89C8 URL \u540E\u4F7F\u7528\u5E26 src \u7684 isLoading \u663E\u793A\u65CB\u8F6C\u52A0\u8F7D\u8986\u76D6\u5C42\u3002'},
-      {guidance: true, description: '\u5C06 onClick \u4E0E\u706F\u7BB1\u6216\u8BE6\u60C5\u89C6\u56FE\u914D\u5BF9\uFF0C\u4EE5\u4FBF\u7528\u6237\u67E5\u770B\u5B8C\u6574\u56FE\u7247\u2014\u2014\u7EC4\u4EF6\u4F1A\u81EA\u52A8\u6DFB\u52A0\u6309\u94AE\u8BED\u4E49\u548C\u60AC\u505C\u9634\u5F71\u3002'},
+      {guidance: true, description: '\u5C06 onClick \u4E0E\u706F\u7BB1\u6216\u8BE6\u60C5\u89C6\u56FE\u914D\u5BF9\uFF0C\u4EE5\u4FBF\u7528\u6237\u67E5\u770B\u5B8C\u6574\u56FE\u7247\u2014\u2014\u7EC4\u4EF6\u4F1A\u81EA\u52A8\u6DFB\u52A0\u6309\u94AE\u8BED\u4E49\u548C\u60AC\u505C\u8986\u76D6\u5C42\u3002'},
       {guidance: false, description: '\u5BF9 PDF \u6216\u7535\u5B50\u8868\u683C\u7B49\u975E\u56FE\u7247\u6587\u4EF6\u7C7B\u578B\u4F7F\u7528 Thumbnail\u2014\u2014\u5E94\u4F7F\u7528\u5E26\u6709\u76F8\u5E94\u56FE\u6807\u7684\u6587\u4EF6\u9644\u4EF6\u7EC4\u4EF6\u3002'},
       {guidance: false, description: '\u63D0\u4F9B src \u65F6\u7701\u7565 alt \u6587\u672C\u2014\u2014\u5C4F\u5E55\u9605\u8BFB\u5668\u9700\u8981\u56FE\u7247\u5185\u5BB9\u7684\u63CF\u8FF0\uFF0C\u800C\u4E0D\u4EC5\u662F label \u4E2D\u7684\u6587\u4EF6\u540D\u3002'},
     ],
@@ -128,19 +136,20 @@ export const docsDense = {
     bestPractices: [
       {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; pair with lightbox for full preview.'},
+      {guidance: true, description: 'onClick adds button semantics + hover overlay; 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: {
     src: 'Image source URL.',
-    alt: 'Alt text for image.',
+    alt: 'Alt text for image. Omitted → explicitly decorative (alt="" + role="presentation" + aria-hidden); dev warn when src set with no alt and no label.',
     label: 'Accessible label (file name). Tooltip on hover, aria-label.',
     onRemove: '(e) => void. Overlaid remove button callback.',
-    onClick: '(e) => void. Adds button semantics + hover shadow.',
+    onClick: '(e) => void. Adds button semantics + hover overlay.',
     isLoading: 'Skeleton (no src) or upload overlay (with src). Default: false.',
     isDisabled: 'Disabled state. Default: false.',
+    showRemoveOn: "When remove button shows: hover (default: reveal on hover/focus, stays visible on touch) | always. Only when onRemove set.",
     xstyle: 'stylex.create() for layout.',
     className: 'CSS class. Prefer xstyle.',
     style: 'Inline styles. Prefer xstyle.',

package/src/Thumbnail/Thumbnail.test.tsx

@@ -21,16 +21,19 @@ describe('Thumbnail', () => {
   });
 
   it('shows skeleton when isLoading with no src', () => {
-    const {container} = render(
-      <Thumbnail isLoading data-testid="thumb" />,
-    );
+    const {container} = render(<Thumbnail isLoading data-testid="thumb" />);
     expect(container.querySelector('.astryx-skeleton')).toBeInTheDocument();
     expect(screen.queryByRole('img')).toBeNull();
   });
 
   it('shows image with upload overlay when isLoading with src', () => {
     render(
-      <Thumbnail src="/local.jpg" alt="Uploading" isLoading data-testid="thumb" />,
+      <Thumbnail
+        src="/local.jpg"
+        alt="Uploading"
+        isLoading
+        data-testid="thumb"
+      />,
     );
     const img = screen.getByRole('img');
     expect(img).toHaveAttribute('src', '/local.jpg');
@@ -75,6 +78,40 @@ describe('Thumbnail', () => {
     ).toBeInTheDocument();
   });
 
+  it('marks the image as explicitly decorative when no alt is provided', () => {
+    render(
+      <Thumbnail src="/photo.jpg" label="photo.png" data-testid="thumb" />,
+    );
+    const img = screen.getByTestId('thumb').querySelector('img');
+    expect(img).toHaveAttribute('alt', '');
+    expect(img).toHaveAttribute('role', 'presentation');
+    expect(img).toHaveAttribute('aria-hidden', 'true');
+    // The image must not be exposed to assistive technology as a nameless img.
+    expect(screen.queryByRole('img')).toBeNull();
+  });
+
+  it('exposes the image with normal img semantics when alt is provided', () => {
+    render(<Thumbnail src="/photo.jpg" alt="Vacation photo" />);
+    const img = screen.getByRole('img', {name: 'Vacation photo'});
+    expect(img).not.toHaveAttribute('role');
+    expect(img).not.toHaveAttribute('aria-hidden');
+  });
+
+  it('warns once when src is set with no alt and no label', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    render(<Thumbnail src="/photo.jpg" />);
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    expect(warnSpy.mock.calls[0][0]).toContain('Thumbnail');
+    warnSpy.mockRestore();
+  });
+
+  it('does not warn when the thumbnail is named via label or alt', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    render(<Thumbnail src="/a.jpg" label="a.png" />);
+    render(<Thumbnail src="/b.jpg" alt="Photo b" />);
+    expect(warnSpy).not.toHaveBeenCalled();
+    warnSpy.mockRestore();
+  });
 
   it('label is shown via tooltip, not as inline text', () => {
     render(<Thumbnail label="photo.png" data-testid="thumb" />);
@@ -117,9 +154,7 @@ describe('Thumbnail', () => {
 
   it('is not interactive when isLoading', () => {
     const onClick = vi.fn();
-    render(
-      <Thumbnail src="/img.jpg" alt="Test" onClick={onClick} isLoading />,
-    );
+    render(<Thumbnail src="/img.jpg" alt="Test" onClick={onClick} isLoading />);
     expect(screen.queryByRole('button')).toBeNull();
   });
 
@@ -128,4 +163,60 @@ describe('Thumbnail', () => {
     render(<Thumbnail ref={ref} data-testid="thumb" />);
     expect(ref).toHaveBeenCalled();
   });
+
+  describe('showRemoveOn', () => {
+    // The reveal style lives on the slot <div> that wraps the remove button
+    // (ancestor-marker styles can't ride on a child component's xstyle prop),
+    // so assert on the button's parent element.
+    const removeSlotClass = (
+      showRemoveOn?: 'always' | 'hover',
+    ): {className: string; unmount: () => void} => {
+      const view = render(
+        <Thumbnail
+          label="file.png"
+          onRemove={vi.fn()}
+          showRemoveOn={showRemoveOn}
+        />,
+      );
+      const slot = screen.getByRole('button', {
+        name: 'Remove file.png',
+      }).parentElement!;
+      return {className: slot.className, unmount: view.unmount};
+    };
+
+    it('renders the remove button in the DOM even when showRemoveOn="hover"', () => {
+      // Hover reveal is CSS-only (opacity) — the button must stay mounted so
+      // it remains reachable by keyboard and assistive tech.
+      render(
+        <Thumbnail label="file.png" onRemove={vi.fn()} showRemoveOn="hover" />,
+      );
+      expect(
+        screen.getByRole('button', {name: 'Remove file.png'}),
+      ).toBeInTheDocument();
+    });
+
+    it('applies a distinct slot class when showRemoveOn="hover" vs "always"', () => {
+      const always = removeSlotClass('always');
+      always.unmount();
+      const hover = removeSlotClass('hover');
+      expect(hover.className).not.toBe(always.className);
+    });
+
+    it('defaults to "hover" (same slot class as an explicit hover)', () => {
+      const def = removeSlotClass(undefined);
+      def.unmount();
+      const hover = removeSlotClass('hover');
+      expect(def.className).toBe(hover.className);
+    });
+
+    it('still fires onRemove when revealed on hover', async () => {
+      const user = userEvent.setup();
+      const onRemove = vi.fn();
+      render(
+        <Thumbnail label="file.png" onRemove={onRemove} showRemoveOn="hover" />,
+      );
+      await user.click(screen.getByRole('button', {name: 'Remove file.png'}));
+      expect(onRemove).toHaveBeenCalledOnce();
+    });
+  });
 });