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

package/src/TextArea/TextArea.tsx

@@ -13,7 +13,7 @@
  * - /packages/core/src/TextArea/TextArea.test.tsx (tests for new/changed behavior)
  * - /packages/core/src/TextArea/index.ts (exports if types change)
  * - /apps/storybook/stories/TextArea.stories.tsx (storybook stories)
- * - /packages/cli/templates/blocks/components/TextArea/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/TextArea/ (showcase blocks)
  */
 
 import {
@@ -21,13 +21,13 @@ import {
   useOptimistic,
   useTransition,
   useRef,
+  useCallback,
   type ChangeEvent,
   type ClipboardEvent,
   type FocusEvent,
   type ReactNode,
 } from 'react';
 import * as stylex from '@stylexjs/stylex';
-import type {IconName} from '../Icon';
 import {
   colorVars,
   spacingVars,
@@ -40,6 +40,7 @@ import {
   inputStatusBorderStyles,
   inputStatusHoverShadowStyles,
   inputStatusFocusWithinStyles,
+  type FieldStatusVariant,
 } from '../Field';
 import {Icon, renderIconSlot, type IconType} from '../Icon';
 import {Spinner} from '../Spinner';
@@ -48,25 +49,40 @@ import {mergeProps, mergeRefs} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import type {SizeValue} from '../utils/types';
 import {useInputContainer} from '../hooks/useInputContainer';
+import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
+import {useAnnounce} from '../hooks/useAnnounce';
 import {useSize} from '../SizeContext/SizeContext';
 import {themeProps} from '../utils/themeProps';
-import {VisuallyHidden} from '../VisuallyHidden';
+import {useTranslator} from '../i18n';
 
 const COUNTER_WARNING_THRESHOLD = 0.8;
 
 const styles = stylex.create({
+  // The wrapper is a bare positioning context. The <textarea> spans the full
+  // container and carries its own internal padding; icons, status/spinner, and
+  // the character counter are absolutely-positioned overlays anchored to the
+  // container corners. This keeps the native resize grip in the true
+  // bottom-right corner and lets the scrollbar represent the full input area.
   wrapper: {
     zIndex: 1,
-    alignItems: 'flex-start',
-    paddingBlock: spacingVars['--spacing-1'],
+    display: 'block',
+    padding: 0,
+    // Internal inline padding for the textarea's text. Defined on the wrapper
+    // so the counter (a sibling overlay) inherits the same value and stays
+    // aligned with the text edge. Kept as an internal var so it can later be
+    // driven by a theme "padding" translation without touching either child.
+    '--_textarea-inline-padding': spacingVars['--spacing-2'],
   },
   textarea: {
     display: 'block',
-    flex: 1,
+    width: '100%',
+    boxSizing: 'border-box',
     minWidth: 0,
     borderWidth: 0,
     borderStyle: 'none',
-    padding: 0,
+    // Base internal padding; overlays get their own reserved space below.
+    paddingBlock: spacingVars['--spacing-1'],
+    paddingInline: 'var(--_textarea-inline-padding)',
     fontFamily: typographyVars['--font-family-body'],
     fontSize: {
       default: typeScaleVars['--text-body-size'],
@@ -84,29 +100,59 @@ const styles = stylex.create({
   textareaDisabled: {
     cursor: 'not-allowed',
   },
+  // Reserve start padding so text clears the start icon.
+  // inline inset + 16px icon (sm) + 8px gap
+  textareaWithStartIcon: {
+    paddingInlineStart: `calc(var(--_textarea-inline-padding) + ${spacingVars['--spacing-6']})`,
+  },
+  // Reserve end padding so text clears the status icon / spinner overlay.
+  // inline inset + 20px icon (md) + 4px gap
+  textareaWithStatus: {
+    paddingInlineEnd: `calc(var(--_textarea-inline-padding) + ${spacingVars['--spacing-6']})`,
+  },
+  // Reserve wider end padding when the spinner AND status icon both show.
+  // inline inset + 16px spinner + 8px gap + 20px icon + 4px gap
+  textareaWithBusyStatus: {
+    paddingInlineEnd: `calc(var(--_textarea-inline-padding) + ${spacingVars['--spacing-12']})`,
+  },
+  // Reserve bottom padding so text clears the character counter overlay.
+  textareaWithCounter: {
+    paddingBottom: spacingVars['--spacing-7'],
+  },
+  startIcon: {
+    position: 'absolute',
+    top: spacingVars['--spacing-2'],
+    insetInlineStart: 'var(--_textarea-inline-padding)',
+    pointerEvents: 'none',
+    display: 'flex',
+  },
+  endSlot: {
+    position: 'absolute',
+    top: spacingVars['--spacing-2'],
+    insetInlineEnd: 'var(--_textarea-inline-padding)',
+    pointerEvents: 'none',
+    display: 'flex',
+    alignItems: 'center',
+    gap: spacingVars['--spacing-2'],
+  },
+  // Character counter lives inside the input container, anchored bottom-right
+  // underneath the textarea, aligned to the same inline inset as the text.
   counter: {
+    position: 'absolute',
+    bottom: spacingVars['--spacing-1'],
+    insetInlineEnd: 'var(--_textarea-inline-padding)',
+    pointerEvents: 'none',
     display: 'flex',
-    justifyContent: 'flex-end',
-    marginTop: spacingVars['--spacing-1'],
+    alignItems: 'center',
+    gap: spacingVars['--spacing-1'],
     fontFamily: typographyVars['--font-family-body'],
     fontSize: typeScaleVars['--text-supporting-size'],
+    lineHeight: typeScaleVars['--text-supporting-leading'],
     color: colorVars['--color-text-secondary'],
   },
   counterError: {
     color: colorVars['--color-error'],
   },
-  statusIcon: {
-    position: 'absolute',
-    top: spacingVars['--spacing-2'],
-    insetInlineEnd: spacingVars['--spacing-2'],
-    pointerEvents: 'none',
-    display: 'flex',
-  },
-  textareaWithStatus: {
-    // Reserve space so text doesn't flow under the absolutely-positioned icon.
-    // 20px (icon md) + 4px gap = 24px (--spacing-6)
-    paddingInlineEnd: spacingVars['--spacing-6'],
-  },
 });
 
 const textareaSizeStyles = stylex.create({
@@ -217,6 +263,14 @@ export interface TextAreaProps extends Omit<
    * If message is provided, displays a floating message box below the textarea.
    */
   status?: TextAreaStatus;
+  /**
+   * 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;
   /**
    * Width of the field. Numbers are treated as pixels, strings are used as-is
    * (e.g. `'100%'`). Sizes the whole field (label, control, and status) so they
@@ -298,6 +352,7 @@ export function TextArea({
   isDisabled = false,
   disabledMessage,
   status,
+  statusVariant = 'attached',
   labelTooltip,
   startIcon,
   hasSpellCheck = true,
@@ -316,12 +371,17 @@ export function TextArea({
   ...rest
 }: TextAreaProps) {
   const size = useSize(sizeProp, 'md');
+  const t = useTranslator();
+  const announce = useAnnounce();
   const id = useId();
   const descriptionID = useId();
   const statusMessageID = useId();
   const counterID = useId();
   const textareaRef = useRef<HTMLTextAreaElement | null>(null);
   const containerRef = useRef<HTMLDivElement | null>(null);
+  // Tracks the counter "zone" last announced (under / near / over) so we only
+  // announce on a zone change, not on every keystroke.
+  const counterZoneRef = useRef<'under' | 'near' | 'over' | null>(null);
 
   const [, startTransition] = useTransition();
   const [optimisticValue, setOptimisticValue] = useOptimistic(value);
@@ -341,31 +401,62 @@ export function TextArea({
     isEnabled: showsDisabledMessage,
   });
 
-  const statusIconMap: Record<TextAreaStatusType, IconName> = {
-    warning: 'warning',
-    error: 'error',
-    success: 'success',
-  };
-
-  const statusIconColorMap: Record<
-    TextAreaStatusType,
-    'warning' | 'error' | 'success'
-  > = {
-    warning: 'warning',
-    error: 'error',
-    success: 'success',
-  };
+  const {statusIcon, describedBy: statusTooltipDescribedBy} =
+    useInputStatusIcon({
+      status,
+      statusVariant,
+    });
 
   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,
       maxLength != null ? counterID : null,
       showsDisabledMessage ? disabledMessageTooltip.describedBy : null,
     ]
       .filter(Boolean)
       .join(' ') || undefined;
 
+  // Announce the character-count status through the shared live region, but
+  // only when the value crosses into a new zone (near the limit / over the
+  // limit) so we don't speak on every keystroke. Over-limit is assertive (an
+  // error the user should hear immediately); nearing the limit is polite.
+  const announceCounter = useCallback(
+    (length: number) => {
+      if (maxLength == null) {
+        return;
+      }
+      const zone: 'under' | 'near' | 'over' =
+        length > maxLength
+          ? 'over'
+          : length >= maxLength * COUNTER_WARNING_THRESHOLD
+            ? 'near'
+            : 'under';
+      if (zone === counterZoneRef.current) {
+        return;
+      }
+      counterZoneRef.current = zone;
+      if (zone === 'over') {
+        announce(
+          t('@astryx.textArea.charactersOverLimit', {
+            count: length - maxLength,
+          }),
+          'assertive',
+        );
+      } else if (zone === 'near') {
+        announce(
+          t('@astryx.textArea.charactersRemaining', {
+            count: maxLength - length,
+          }),
+        );
+      }
+    },
+    [announce, t, maxLength],
+  );
+
   const handleChange = (e: ChangeEvent<HTMLTextAreaElement>) => {
     // 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
@@ -374,6 +465,7 @@ export function TextArea({
       return;
     }
     const newValue = e.target.value;
+    announceCounter(newValue.length);
     onChange?.(newValue, e);
     if (changeAction && !e.defaultPrevented) {
       startTransition(async () => {
@@ -412,6 +504,7 @@ export function TextArea({
             }
           : undefined
       }
+      statusVariant={statusVariant}
       labelTooltip={labelTooltip}
       width={width}>
       <div
@@ -429,18 +522,20 @@ export function TextArea({
           stylex.props(
             inputWrapperStyles.base,
             styles.wrapper,
-            textareaSizeStyles[size],
-            effectivelyDisabled && inputWrapperStyles.disabled,
+            isDisabled && inputWrapperStyles.disabled,
             status && inputStatusBorderStyles[status.type],
-            status && inputStatusHoverShadowStyles[status.type],
+            status && !isDisabled && inputStatusHoverShadowStyles[status.type],
             status && inputStatusFocusWithinStyles[status.type],
             xstyle,
           ),
           className,
           style,
         )}>
-        {startIcon &&
-          renderIconSlot(startIcon, {size: 'sm', color: 'secondary'})}
+        {startIcon && (
+          <span {...stylex.props(styles.startIcon)}>
+            {renderIconSlot(startIcon, {size: 'sm', color: 'secondary'})}
+          </span>
+        )}
         <textarea
           {...rest}
           ref={mergeRefs(ref, textareaRef)}
@@ -473,38 +568,37 @@ export function TextArea({
           aria-busy={isBusy || undefined}
           {...stylex.props(
             styles.textarea,
-            effectivelyDisabled && styles.textareaDisabled,
-            status && styles.textareaWithStatus,
+            textareaSizeStyles[size],
+            isDisabled && styles.textareaDisabled,
+            Boolean(startIcon) && styles.textareaWithStartIcon,
+            (status || isBusy) && styles.textareaWithStatus,
+            isBusy && !!statusIcon && styles.textareaWithBusyStatus,
+            maxLength != null && styles.textareaWithCounter,
           )}
         />
-        {isBusy && <Spinner size="sm" />}
-        {status && (
-          <span {...stylex.props(styles.statusIcon)}>
-            <Icon
-              icon={statusIconMap[status.type]}
-              size="md"
-              color={statusIconColorMap[status.type]}
-            />
+        {(isBusy || statusIcon) && (
+          <span {...stylex.props(styles.endSlot)}>
+            {isBusy && <Spinner size="sm" />}
+            {statusIcon}
           </span>
         )}
+        {maxLength != null && (
+          <div
+            id={counterID}
+            {...stylex.props(
+              styles.counter,
+              optimisticValue.length > maxLength && styles.counterError,
+            )}>
+            {optimisticValue.length > maxLength && (
+              // Non-color cue so the over-limit state isn't conveyed by the red
+              // color alone (WCAG 1.4.1). Decorative — the count text and the
+              // live-region announcement carry the meaning.
+              <Icon icon="warning" size="sm" />
+            )}
+            {optimisticValue.length}/{maxLength}
+          </div>
+        )}
       </div>
-      {maxLength != null && (
-        <div
-          id={counterID}
-          {...stylex.props(
-            styles.counter,
-            optimisticValue.length > maxLength && styles.counterError,
-          )}>
-          {optimisticValue.length}/{maxLength}
-          <VisuallyHidden aria-live="polite">
-            {optimisticValue.length >= maxLength * COUNTER_WARNING_THRESHOLD
-              ? optimisticValue.length > maxLength
-                ? `${optimisticValue.length - maxLength} characters over limit`
-                : `${maxLength - optimisticValue.length} characters remaining`
-              : ''}
-          </VisuallyHidden>
-        </div>
-      )}
       {showsDisabledMessage &&
         disabledMessageTooltip.renderTooltip(disabledMessage)}
     </Field>

package/src/TextInput/TextInput.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'TextInput',
@@ -114,6 +114,13 @@ export const docs = {
       description:
         'Validation status: applies a colored border and status icon. If message is provided, displays a floating message below the input. Error type also sets aria-invalid.',
     },
+    {
+      name: 'statusVariant',
+      type: "'attached' | 'detached' | 'tooltip'",
+      description:
+        'How the status message is placed relative to the input. attached overlaps directly below the input (bordered treatment); detached floats below as a separate element with spacing; tooltip hides the message box and surfaces it in a tooltip on the status icon.',
+      default: "'attached'",
+    },
     {
       name: 'hasClear',
       type: 'boolean',
@@ -133,6 +140,12 @@ export const docs = {
       description:
         'The HTML name attribute for the input, useful for form submissions.',
     },
+    {
+      name: 'width',
+      type: 'SizeValue',
+      description:
+        'Width of the field (number = pixels, string used as-is, e.g. "100%"). Sizes the whole field (label, control, and status) so they stay aligned.',
+    },
   ],
   theming: {
     targets: [
@@ -164,7 +177,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'TextInput',
   displayName: 'Text Input',
@@ -274,6 +287,13 @@ export const docsZh = {
       description:
         '验证状态：应用彩色边框和状态图标。如果提供了 message，在输入框下方显示浮动消息。错误类型还会设置 aria-invalid。',
     },
+    {
+      name: 'statusVariant',
+      type: "'attached' | 'detached' | 'tooltip'",
+      description:
+        '状态消息相对于输入框的放置方式。attached 直接叠加在输入框下方（带边框处理）；detached 作为独立元素浮于下方并留有间距；tooltip 隐藏消息框，并在状态图标上以提示气泡形式显示。',
+      default: "'attached'",
+    },
     {
       name: 'hasClear',
       type: 'boolean',
@@ -323,7 +343,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'Text input for collecting user text w/ label, description, validation status, optional/required indicators.',
   usage: {
@@ -368,6 +388,7 @@ export const docsDense = {
     labelTooltip: 'Tooltip in info icon at label end.',
     startIcon: 'SVG icon at input start (e.g. heroicons or lucide).',
     status: 'Validation status; colored border+icon. Message floats below. Error sets aria-invalid.',
+    statusVariant: 'How status message is placed: attached overlaps below input; detached floats below w/ spacing; tooltip hides the box and shows it on the status icon.',
     hasClear: 'Shows clear button when input has value. Clears value on click.',
     hasAutoFocus: 'Auto-focus input on mount.',
     htmlName: 'HTML name attr for form submissions.',

package/src/TextInput/TextInput.test.tsx

@@ -13,6 +13,7 @@ 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 {TestIcon} from '../__tests__/TestIcon';
+import {InputGroup} from '../InputGroup';
 import {TextInput} from './TextInput';
 
 // Mock showPopover/hidePopover since jsdom does not implement them. Used by the
@@ -229,6 +230,26 @@ describe('TextInput', () => {
       expect(screen.getByText('Invalid email address')).toBeInTheDocument();
     });
 
+    it('has no dangling aria-describedby ids inside InputGroup (WCAG 1.3.1)', () => {
+      // Inside an InputGroup no Field renders, so the status message element
+      // does not exist; aria-describedby must not reference its id.
+      render(
+        <InputGroup label="Contact">
+          <TextInput
+            label="Email"
+            value=""
+            onChange={() => {}}
+            status={{type: 'error', message: 'Invalid email address'}}
+          />
+        </InputGroup>,
+      );
+      const input = screen.getByRole('textbox');
+      const describedBy = input.getAttribute('aria-describedby') ?? '';
+      for (const idToken of describedBy.split(/\s+/).filter(Boolean)) {
+        expect(document.getElementById(idToken)).not.toBeNull();
+      }
+    });
+
     it('does not render status message when not provided', () => {
       render(
         <TextInput
@@ -659,3 +680,132 @@ describe('TextInput', () => {
     });
   });
 });
+
+describe('TextInput statusVariant forwarding', () => {
+  it('defaults to attached (status renders with data-variant="attached")', () => {
+    const {container} = render(
+      <TextInput
+        label="Email"
+        value=""
+        onChange={() => {}}
+        status={{type: 'error', message: 'Invalid email'}}
+      />,
+    );
+    expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
+      'data-variant',
+      'attached',
+    );
+  });
+
+  it('forwards statusVariant="detached" to the underlying Field status', () => {
+    const {container} = render(
+      <TextInput
+        label="Email"
+        value=""
+        onChange={() => {}}
+        status={{type: 'error', message: 'Invalid email'}}
+        statusVariant="detached"
+      />,
+    );
+    expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
+      'data-variant',
+      'detached',
+    );
+  });
+
+  it('renders no message box for statusVariant="tooltip"', () => {
+    const {container} = render(
+      <TextInput
+        label="Email"
+        value=""
+        onChange={() => {}}
+        status={{type: 'error', message: 'Invalid email'}}
+        statusVariant="tooltip"
+      />,
+    );
+    expect(
+      container.querySelector('.astryx-field-status'),
+    ).not.toBeInTheDocument();
+  });
+
+  it('surfaces the status message in a tooltip for statusVariant="tooltip"', () => {
+    render(
+      <TextInput
+        label="Email"
+        value=""
+        onChange={() => {}}
+        status={{type: 'error', message: 'Invalid email'}}
+        statusVariant="tooltip"
+      />,
+    );
+    const tooltip = screen.getByRole('tooltip', h);
+    expect(tooltip).toHaveTextContent('Invalid email');
+  });
+
+  it('describes the input by the status tooltip for statusVariant="tooltip"', () => {
+    render(
+      <TextInput
+        label="Email"
+        value=""
+        onChange={() => {}}
+        status={{type: 'error', message: 'Invalid email'}}
+        statusVariant="tooltip"
+      />,
+    );
+    const input = screen.getByRole('textbox');
+    const tooltip = screen.getByRole('tooltip', h);
+    expect(input.getAttribute('aria-describedby')).toContain(tooltip.id);
+  });
+
+  it('renders the tooltip status affordance as a focusable button (WCAG 2.1.1)', () => {
+    render(
+      <TextInput
+        label="Email"
+        value=""
+        onChange={() => {}}
+        status={{type: 'error', message: 'Invalid email'}}
+        statusVariant="tooltip"
+      />,
+    );
+    // The status affordance is a real button with an accessible name naming
+    // the status type (WCAG 4.1.2), so keyboard-only users (no AT) can reach it.
+    const statusButton = screen.getByRole('button', {name: /error details/i});
+    expect(statusButton).toBeInTheDocument();
+    expect(statusButton).toHaveAttribute('type', 'button');
+  });
+
+  it('opens the status tooltip on keyboard focus for statusVariant="tooltip"', async () => {
+    const user = userEvent.setup();
+    render(
+      <TextInput
+        label="Email"
+        value=""
+        onChange={() => {}}
+        status={{type: 'error', message: 'Invalid email'}}
+        statusVariant="tooltip"
+      />,
+    );
+    const tooltip = screen.getByRole('tooltip', h);
+    // Tab from the input to the status button; keyboard focus reveals the tip.
+    await user.tab();
+    await user.tab();
+    await waitFor(() => {
+      expect(tooltip).toHaveAttribute('popover-open');
+    });
+  });
+
+  it('describes the status button by the tooltip content for statusVariant="tooltip"', () => {
+    render(
+      <TextInput
+        label="Email"
+        value=""
+        onChange={() => {}}
+        status={{type: 'error', message: 'Invalid email'}}
+        statusVariant="tooltip"
+      />,
+    );
+    const statusButton = screen.getByRole('button', {name: /error details/i});
+    const tooltip = screen.getByRole('tooltip', h);
+    expect(statusButton.getAttribute('aria-describedby')).toContain(tooltip.id);
+  });
+});