@astryxdesign/core 0.1.9 → 0.2.0-canary.0e01213

package/src/FileInput/FileInput.test.tsx

@@ -147,16 +147,33 @@ describe('FileInput', () => {
     expect(screen.getByText('Upload')).toBeInTheDocument();
   });
 
-  it('sets aria-required when isRequired is true', () => {
+  it('conveys required state through the accessible description', () => {
     render(
       <FileInput label="Resume" isRequired value={null} onChange={() => {}} />,
     );
-    // aria-required lives on the focusable role="button" wrapper, not the
+    const trigger = screen.getByRole('button', {name: 'Resume'});
+    // Required is conveyed via a visually hidden "Required" node referenced
+    // from aria-describedby on the focusable role="button" trigger — not the
     // hidden file input (forms-6).
-    expect(screen.getByRole('button', {name: 'Resume'})).toHaveAttribute(
-      'aria-required',
-      'true',
+    expect(trigger).toHaveAccessibleDescription(/Required/);
+    // aria-required is not a supported property of role="button" in
+    // WAI-ARIA 1.2 (AT does not announce it), so it must never appear.
+    expect(trigger).not.toHaveAttribute('aria-required');
+  });
+
+  it('combines required with the description in the accessible description', () => {
+    render(
+      <FileInput
+        label="Resume"
+        description="PDF only"
+        isRequired
+        value={null}
+        onChange={() => {}}
+      />,
     );
+    const trigger = screen.getByRole('button', {name: 'Resume'});
+    expect(trigger).toHaveAccessibleDescription(/PDF only/);
+    expect(trigger).toHaveAccessibleDescription(/Required/);
   });
 
   it('places aria-describedby on the focusable button, not the hidden input (forms-6)', () => {
@@ -176,11 +193,11 @@ describe('FileInput', () => {
     expect(input).toHaveAttribute('aria-hidden', 'true');
   });
 
-  it('does not set aria-required by default', () => {
+  it('does not mention required without isRequired', () => {
     render(<FileInput label="Resume" value={null} onChange={() => {}} />);
-    expect(screen.getByRole('button', {name: 'Resume'})).not.toHaveAttribute(
-      'aria-required',
-    );
+    const trigger = screen.getByRole('button', {name: 'Resume'});
+    expect(trigger).not.toHaveAccessibleDescription(/Required/);
+    expect(trigger).not.toHaveAttribute('aria-required');
   });
 
   it('sets disabled attribute when isDisabled is true', () => {
@@ -353,6 +370,40 @@ describe('FileInput', () => {
       // FieldStatus, but the polite channel must stay empty.)
       expect(politeRegion()?.textContent ?? '').toBe('');
     });
+
+    it('announces a validation error exactly once across live regions', async () => {
+      render(
+        <FileInput
+          label="Upload"
+          value={null}
+          onChange={() => {}}
+          accept=".pdf"
+        />,
+      );
+      fireEvent.change(fileInputEl(), {
+        target: {files: [createFile('note.txt', 100)]},
+      });
+      const errorText = '"note.txt" is not an accepted file type';
+      // The error lands in the assertive announce region (via the FieldStatus
+      // the derived error status mounts)…
+      await waitFor(() => {
+        expect(
+          document.querySelector('[data-astryx-live-region="assertive"]'),
+        ).toHaveTextContent(errorText);
+      });
+      // …and in exactly one live region overall. FileInput's own role="status"
+      // region used to duplicate the FieldStatus announcement, so the same
+      // error was read twice (assertively, then politely).
+      const liveRegions = Array.from(
+        document.querySelectorAll(
+          '[role="status"], [role="alert"], [aria-live]',
+        ),
+      );
+      const regionsWithError = liveRegions.filter(el =>
+        (el.textContent ?? '').includes(errorText),
+      );
+      expect(regionsWithError).toHaveLength(1);
+    });
   });
 
   describe('validation', () => {
@@ -719,16 +770,20 @@ describe('FileInput', () => {
         />,
       );
 
-      const trigger = screen.getByRole('button');
       const tooltip = screen.getByRole('tooltip', h);
       expect(tooltip).toHaveTextContent('You need the Editor role');
 
-      fireEvent.mouseEnter(trigger);
+      // The trigger button is visually hidden, so the disabled-reason tooltip
+      // anchors its hover listeners to the visible container surface.
+      const surface = document.querySelector(
+        '.astryx-file-input',
+      ) as HTMLElement;
+      fireEvent.mouseEnter(surface);
       await waitFor(() => {
         expect(tooltip).toHaveAttribute('popover-open');
       });
 
-      fireEvent.mouseLeave(trigger);
+      fireEvent.mouseLeave(surface);
       await waitFor(() => {
         expect(tooltip).not.toHaveAttribute('popover-open');
       });
@@ -809,7 +864,10 @@ describe('FileInput', () => {
     });
 
     it('blocks opening the file picker while focusable-disabled', async () => {
-      const user = userEvent.setup();
+      // The trigger is a visually-hidden button (pointer-events: none) — real
+      // pointer clicks land on the container surface, so bypass the pointer
+      // check to exercise the disabled guard directly.
+      const user = userEvent.setup({pointerEventsCheck: 0});
       render(
         <FileInput
           label="Resume"
@@ -849,3 +907,36 @@ describe('FileInput', () => {
     });
   });
 });
+
+describe('FileInput statusVariant forwarding', () => {
+  it('defaults to attached (status renders with data-variant="attached")', () => {
+    const {container} = render(
+      <FileInput
+        label="Upload"
+        value={null}
+        onChange={() => {}}
+        status={{type: 'error', message: 'Something went wrong'}}
+      />,
+    );
+    expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
+      'data-variant',
+      'attached',
+    );
+  });
+
+  it('forwards statusVariant="detached" to the underlying Field status', () => {
+    const {container} = render(
+      <FileInput
+        label="Upload"
+        value={null}
+        onChange={() => {}}
+        status={{type: 'error', message: 'Something went wrong'}}
+        statusVariant="detached"
+      />,
+    );
+    expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
+      'data-variant',
+      'detached',
+    );
+  });
+});

package/src/FileInput/FileInput.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file FileInput.tsx
- * @input Uses React, useId, Field, Icon, Spinner
+ * @input Uses React, useId, Field, Icon, Spinner, VisuallyHidden
  * @output Exports FileInput component, FileInputProps, FileInputStatus
  * @position Core implementation; consumed by index.ts, tested by FileInput.test.tsx
  *
@@ -40,11 +40,14 @@ import {
   Field,
   InputClearButton,
   type InputStatus,
-  type InputStatusType,
+  type FieldStatusVariant,
 } from '../Field';
-import {Icon, type IconName} from '../Icon';
+import {Icon} from '../Icon';
 import {Spinner} from '../Spinner';
+import {VisuallyHidden} from '../VisuallyHidden';
 import {useAnnounce} from '../hooks/useAnnounce';
+import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
+import {useClickableContainer} from '../hooks/useClickableContainer';
 import {useTooltip} from '../Tooltip';
 
 export type {
@@ -246,17 +249,6 @@ const styles = stylex.create({
     flex: 1,
     minWidth: 0,
   },
-  liveRegion: {
-    position: 'absolute',
-    width: 1,
-    height: 1,
-    padding: 0,
-    margin: -1,
-    overflow: 'hidden',
-    clip: 'rect(0, 0, 0, 0)',
-    whiteSpace: 'nowrap',
-    borderWidth: 0,
-  },
 });
 
 const statusBorderStyles = stylex.create({
@@ -358,6 +350,14 @@ export interface FileInputProps extends Omit<
    * Validation status for 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;
   /**
    * Description text displayed below the label.
    */
@@ -414,6 +414,7 @@ export function FileInput({
   isRequired = false,
   isLoading = false,
   status: statusProp,
+  statusVariant = 'attached',
   description,
   placeholder,
   mode = 'input',
@@ -430,22 +431,24 @@ export function FileInput({
   const id = useId();
   const descriptionID = useId();
   const statusMessageID = useId();
-  const liveRegionID = useId();
+  const requiredID = useId();
   const inputRef = useRef<HTMLInputElement | null>(null);
+  const containerRef = useRef<HTMLDivElement | null>(null);
   const [isDragOver, setIsDragOver] = useState(false);
   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.
+  // live region (forms-17). Validation errors are announced (assertively) by
+  // the FieldStatus that the derived error status mounts, so only the
+  // successful attach needs an explicit announcement here.
   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.
+  // tooltip listeners attach to the visible container (which stays hoverable)
+  // and the trigger stays perceivable via aria-disabled instead of the native
+  // disabled attribute. Opening the picker is blocked by the isDisabled guards
+  // in the handlers.
   const showsDisabledMessage = isDisabled && !!disabledMessage;
   const disabledMessageTooltip = useTooltip({
     placement: 'above',
@@ -459,25 +462,27 @@ export function FileInput({
       ? {type: 'error' as const, message: validationError}
       : undefined);
 
-  const statusIconMap: Record<InputStatusType, IconName> = {
-    warning: 'warning',
-    error: 'error',
-    success: 'success',
-  };
+  const {statusIcon, describedBy: statusTooltipDescribedBy} =
+    useInputStatusIcon({
+      status,
+      statusVariant,
+    });
 
-  const statusIconColorMap: Record<
-    InputStatusType,
-    'warning' | 'error' | 'success'
-  > = {
-    warning: 'warning',
-    error: 'error',
-    success: 'success',
-  };
+  // Required state. The trigger is a real button, but AT does not reliably
+  // announce aria-required, so the trigger instead points its aria-describedby
+  // at a visually hidden "Required" span — mirroring the Field label's visible
+  // indicator (where isOptional takes precedence) and the pattern Slider uses
+  // for its thumbs.
+  const conveysRequired = isRequired && !isOptional;
 
   const ariaDescribedBy =
     [
       description ? descriptionID : null,
-      status?.message ? statusMessageID : null,
+      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,
+      conveysRequired ? requiredID : null,
       showsDisabledMessage ? disabledMessageTooltip.describedBy : null,
     ]
       .filter(Boolean)
@@ -515,8 +520,9 @@ export function FileInput({
       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).
+      // announced assertively by the FieldStatus that the derived error
+      // status mounts, so only announce the attach here (do not
+      // double-announce errors).
       if (errors.length === 0) {
         announce(
           valid.length === 1
@@ -574,6 +580,9 @@ export function FileInput({
     }
   }, [isDisabled]);
 
+  // Explicit keyboard activation so Enter/Space open the picker even where a
+  // synthetic keydown does not raise a native click. The isDisabled guard
+  // blocks activation while focusable-disabled.
   const handleKeyDown = useCallback(
     (e: React.KeyboardEvent) => {
       if ((e.key === 'Enter' || e.key === ' ') && !isDisabled) {
@@ -584,6 +593,16 @@ export function FileInput({
     [isDisabled],
   );
 
+  // Make the surface clickable without giving it an interactive role. Clicks on
+  // the nested clear/status controls are ignored by the hook, so those buttons
+  // are plain siblings — no nested-interactive violation.
+  const {onClick: onContainerClick, onMouseUp: onContainerMouseUp} =
+    useClickableContainer({
+      containerRef,
+      onClick: handleClick,
+      disabled: isDisabled,
+    });
+
   const handleDragEnter = useCallback(
     (e: DragEvent) => {
       e.preventDefault();
@@ -687,13 +706,7 @@ export function FileInput({
           )}>
           {fileNames ?? displayPlaceholder}
         </span>
-        {status && (
-          <Icon
-            icon={statusIconMap[status.type]}
-            size="md"
-            color={statusIconColorMap[status.type]}
-          />
-        )}
+        {statusIcon}
       </>
     );
   };
@@ -728,39 +741,21 @@ export function FileInput({
             }
           : undefined
       }
+      statusVariant={statusVariant}
       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.
+          containerRef.current = el;
+          // Anchor + hover/focus listeners for the disabled-message tooltip on
+          // the visible container (the focusable trigger is visually hidden, so
+          // anchoring there would place the tooltip at a 1px box). focusin
+          // bubbles from the trigger button, so the tooltip still opens on
+          // keyboard focus. Handlers are gated internally by isEnabled.
           disabledMessageTooltip.ref(el);
         }}
-        role="button"
-        // 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 suppresses child content from the accessible name, so
-        // compose the selected filenames into it — otherwise a screen-reader
-        // user refocusing the control hears only the field label and cannot
-        // tell what (if anything) is attached.
-        aria-label={
-          hasFiles && fileNames
-            ? t('@astryx.fileInput.triggerWithFiles', {label, fileNames})
-            : 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}
+        onClick={!isDisabled ? onContainerClick : undefined}
+        onMouseUp={!isDisabled ? onContainerMouseUp : undefined}
         {...dragDropProps}
         {...mergeProps(
           themeProps('file-input', {mode, status: status?.type ?? null}),
@@ -776,6 +771,40 @@ export function FileInput({
           className,
           style,
         )}>
+        {/* Visually hidden real button carrying the accessible role, name, and
+            ARIA. Kept as a sibling of the clear/status controls inside a
+            non-interactive container, so no interactive element nests inside
+            another (WCAG 4.1.2). The visible focus feedback is the container's
+            :focus-within border; the surface click is handled by the container
+            (VisuallyHidden disables the button's own pointer events), and
+            keyboard activation still fires here. */}
+        <VisuallyHidden>
+          <button
+            type="button"
+            // 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.
+            // Otherwise the native disabled attribute removes it from the tab
+            // order.
+            disabled={isDisabled && !showsDisabledMessage}
+            tabIndex={isDisabled && !showsDisabledMessage ? -1 : 0}
+            aria-disabled={showsDisabledMessage ? 'true' : undefined}
+            onClick={handleClick}
+            onKeyDown={handleKeyDown}
+            // aria-label suppresses child content from the accessible name, so
+            // compose the selected filenames into it — otherwise a
+            // screen-reader user refocusing the control hears only the field
+            // label and cannot tell what (if anything) is attached.
+            aria-label={
+              hasFiles && fileNames
+                ? t('@astryx.fileInput.triggerWithFiles', {label, fileNames})
+                : label
+            }
+            aria-busy={isLoading || undefined}
+            aria-describedby={ariaDescribedBy}
+            aria-invalid={status?.type === 'error' ? 'true' : undefined}
+          />
+        </VisuallyHidden>
         <input
           {...rest}
           ref={mergeRefs(ref, inputRef)}
@@ -786,7 +815,7 @@ export function FileInput({
           disabled={isDisabled}
           onChange={handleInputChange}
           // The visually-hidden native input is never focused (tabIndex={-1});
-          // its describedby/required/invalid live on the role="button" wrapper.
+          // its describedby/required/invalid live on the trigger button.
           aria-hidden="true"
           tabIndex={-1}
           {...stylex.props(styles.hiddenInput)}
@@ -799,13 +828,11 @@ export function FileInput({
           />
         )}
       </div>
-      <div
-        id={liveRegionID}
-        role="status"
-        aria-live="polite"
-        {...stylex.props(styles.liveRegion)}>
-        {validationError}
-      </div>
+      {conveysRequired && (
+        <VisuallyHidden id={requiredID}>
+          {t('@astryx.fileInput.required')}
+        </VisuallyHidden>
+      )}
       {showsDisabledMessage &&
         disabledMessageTooltip.renderTooltip(disabledMessage)}
     </Field>

package/src/Heading/Heading.tsx

@@ -41,6 +41,7 @@ import {
   truncationTooltipStyles,
 } from '../Text/text.stylex';
 import {useTruncation} from '../Text/useTruncation';
+import {resolveStyleColor} from '../Text/Text';
 import type {LayerPlacement} from '../Layer';
 import {mergeProps, mergeRefs} from '../utils';
 import type {BaseProps} from '../BaseProps';
@@ -251,7 +252,7 @@ export function Heading({
         {...mergeProps(
           themeProps('heading', {level, color, ...(type && {type})}),
           stylex.props(
-            colorStyles[color],
+            colorStyles[resolveStyleColor(color)],
             type ? sizeByTypeStyles[type] : sizeByLevelStyles[level],
             type && defaultWeightByTypeStyles[type],
             // Display: use truncation styles when maxLines > 0

package/src/HoverCard/useHoverCard.tsx

@@ -34,7 +34,6 @@ import {
   radiusVars,
   spacingVars,
 } from '../theme/tokens.stylex';
-import {mergeProps} from '../utils';
 import {themeProps} from '../utils/themeProps';
 
 const styles = stylex.create({
@@ -469,6 +468,7 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
       props?: Omit<ContextRenderProps, 'positioning'>,
     ): ReactNode => {
       const renderPlacement = props?.placement ?? placement;
+      const themeClassName = themeProps('hovercard').className;
       const renderProps = {
         placement: renderPlacement,
         alignment: props?.alignment ?? alignment,
@@ -477,7 +477,19 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
         // are non-modal, so group is honest semantics without a name.
         role: label ? 'dialog' : 'group',
         'aria-label': label || undefined,
-        xstyle: [popoverXstyle, layerAnimations[renderPlacement]],
+        // Consumer surface style props land on the layer container — the
+        // themed surface (bg/radius/shadow) where the theme class lives — so
+        // customizing the card targets the same element as the theme. The inner
+        // span keeps `styles.content` for padding.
+        xstyle: [
+          popoverXstyle,
+          layerAnimations[renderPlacement],
+          props?.xstyle,
+        ],
+        className: props?.className
+          ? `${themeClassName} ${props.className}`
+          : themeClassName,
+        style: props?.style,
         // Render the layer as inline-safe phrasing markup so HoverCard stays
         // valid (and hydration-stable) inside inline contexts like a `<p>`.
         as: 'span' as const,
@@ -485,7 +497,7 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
 
       return layer.render(
         <span
-          {...mergeProps(themeProps('hovercard'), stylex.props(styles.content))}
+          {...stylex.props(styles.content)}
           onMouseEnter={() => {
             isHoveringContentRef.current = true;
             clearTimeouts();

package/src/Icon/Icon.doc.mjs

@@ -39,6 +39,12 @@ export const docs = {
       type: 'string',
       description: 'Accessible name for a MEANINGFUL, standalone icon (a status glyph or icon-only indicator with no adjacent text). Setting it exposes the icon to screen readers as role="img" with this text as the accessible name (aria-label) and removes the default aria-hidden. Omit it (default) for decorative icons and the icon stays hidden from assistive tech (aria-hidden="true"). This is the accessible-name / alt-text prop for icons: one prop instead of manually setting aria-label + role + aria-hidden. An empty string is treated as decorative. Do not set it when an interactive parent (Button, IconButton, link) already names the control.',
     },
+    {
+      name: 'xstyle',
+      type: 'StyleXStyles',
+      description:
+        'StyleX styles for customization (color, size, opacity). Folded into the icon\'s own stylex.props() call so it composes with the base color/size styles. Must be a stylex.create() value, not an inline style object like style={{}}.',
+    },
   ],
   theming: {
     targets: [
@@ -90,6 +96,12 @@ export const docsZh = {
       type: 'string',
       description: '有含义的独立图标的可访问名称（无相邻文字的状态图标或纯图标指示器）。设置后会将图标以 role="img" 暴露给辅助技术，并以该文本作为可访问名称（aria-label），同时移除默认的 aria-hidden。省略（默认）用于装饰性图标，图标对辅助技术保持隐藏（aria-hidden="true"）。空字符串按装饰性处理。当交互式父元素（Button、IconButton、链接）已命名该控件时请勿设置。',
     },
+    {
+      name: 'xstyle',
+      type: 'StyleXStyles',
+      description:
+        '用于自定义的 StyleX 样式（颜色、尺寸、不透明度）。会并入图标自身的 stylex.props() 调用，从而与基础的颜色/尺寸样式组合。必须是 stylex.create() 的值，而不是像 style={{}} 这样的内联样式对象。',
+    },
   ],
   theming: {
     targets: [
@@ -136,5 +148,6 @@ export const docsDense = {
     color: 'Color variant mapped to Astryx icon color tokens.',
     size: 'Icon size.',
     label: 'Accessible name for a meaningful, standalone icon. Sets role="img" + aria-label and drops the default aria-hidden. Omit (default) for decorative icons (stays aria-hidden). Empty string = decorative. The accessible-name/alt-text prop for icons.',
+    xstyle: 'StyleX styles (color, size, opacity) via stylex.create(); composes with the base color/size styles.',
   },
 };