@astryxdesign/core 0.7.5 → 0.7.6-canary.0bd3b37

package/src/TabList/TabList.tsx

@@ -515,6 +515,10 @@ export function TabList({
     revealSelectedTabRef.current = revealSelectedTab;
   }, [revealSelectedTab]);
 
+  // The tab whose focus revealed it (see `handleRootFocus`), while it keeps
+  // focus.
+  const focusRevealedValueRef = useRef<string | null>(null);
+
   // The tab you are on has to be visible. Selection can move without focus —
   // on mount, or when the host sets `value` itself — and neither scrolls the
   // strip the way clicking or arrowing to a tab does. The check is what makes
@@ -525,6 +529,14 @@ export function TabList({
       return;
     }
     revealedValueRef.current = value;
+    if (value != null && focusRevealedValueRef.current === value) {
+      // A press or an arrow focused this tab first, and focusing it revealed
+      // it. Measuring now would force the new selection's style and layout
+      // inside the press, before it can paint. The next frame lays them out
+      // anyway, so finish there: the selected weight can still widen the tab.
+      const frame = requestAnimationFrame(() => revealSelectedTabRef.current());
+      return () => cancelAnimationFrame(frame);
+    }
     revealSelectedTabRef.current();
   }, [value]);
 
@@ -595,7 +607,9 @@ export function TabList({
       // The browser scrolls a focused element into view only when it is
       // entirely outside the scrollport, so arrowing onto a half-visible stop
       // leaves it cut off under the fade. Finish the job it started.
-      revealStop(e.target.closest(TAB_STOP_SELECTOR));
+      const stop = e.target.closest<HTMLElement>(TAB_STOP_SELECTOR);
+      revealStop(stop);
+      focusRevealedValueRef.current = stop?.dataset.tabValue ?? null;
     },
     [onFocusProp, onHintFocus, handleFocus, revealStop],
   );
@@ -603,6 +617,7 @@ export function TabList({
   const handleRootBlur = useCallback(
     (e: React.FocusEvent<HTMLElement>) => {
       onBlurProp?.(e);
+      focusRevealedValueRef.current = null;
       if (e.defaultPrevented) {
         return;
       }

package/src/Table/Table.spec.md

@@ -127,7 +127,7 @@ documented in `Table.doc.mjs` and the member and module docs.
 
 | ID   | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Basis                                                                  | Evidence state                                                                                                                                                                       |
 | ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| FR1  | By default, Styled Table renders one named Scroll region around one observed content box and one semantic Table. The Scroll region enters the keyboard order and contains inline overscroll only while inline content effectively overflows; fitting content passes scroll gestures to its ancestor. Explicit scroll-wrapper plugin HTML attributes remain authoritative.                                                                                                                                                                                                                                                                                                           | `spec:AST-025` FR12, FR14, FR19, FR21; current source, docs, and tests | Verified fitting and inline-overflow transitions through the shared `useScrollableArea` behavior core                                                                                |
+| FR1  | By default, Styled Table renders one named Scroll region around one observed content box and one semantic Table. The Scroll region takes the Table's own name (its `aria-labelledby`, else its `aria-label`), and a generic table name only when the Table has none. The Scroll region enters the keyboard order and contains inline overscroll only while inline content effectively overflows; fitting content passes scroll gestures to its ancestor. Explicit scroll-wrapper plugin HTML attributes remain authoritative.                                                                                                                                                       | `spec:AST-025` FR12, FR14, FR19, FR21; current source, docs, and tests | Verified fitting and inline-overflow transitions through the shared `useScrollableArea` behavior core                                                                                |
 | FR2  | Data-driven mode renders a Body section and a Header section with Column header cells when columns are present. Each data item renders a standard Row and Cells; an empty data array instead renders the configured empty-state row when enabled. It never creates a Footer section.                                                                                                                                                                                                                                                                                                                                                                                                | Current source, docs, and tests                                        | Verified current behavior; no new behavior decided                                                                                                                                   |
 | FR3  | Children mode passes caller composition through to the Table. TableHeader, TableBody, and TableFooter provide the respective sections, and TableRow, TableHeaderCell, and TableCell provide standard rows and cells.                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Current source, docs, and tests                                        | Verified current composition; no new API or DOM rule                                                                                                                                 |
 | FR4  | `Table.doc.mjs` is the canonical aggregate consumer owner for the eight current targets: `table`, `table-scroll-wrapper`, `table-header`, `table-body`, `table-footer`, `table-row`, `table-cell`, and `table-header-cell`. Member docs retain direct lookup metadata through `subComponentOf: 'Table'`.                                                                                                                                                                                                                                                                                                                                                                            | Current docs and CLI target tests                                      | Verified parent ownership; focused placement coverage is partial                                                                                                                     |

package/src/Table/Table.tsx

@@ -17,7 +17,7 @@
  * - /packages/cli/assets/templates/blocks/components/Table/ (showcase blocks)
  */
 
-import {useMemo, type ReactElement, type Ref} from 'react';
+import {createContext, use, useMemo, type ReactElement, type Ref} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {colorVars} from '../theme/tokens.stylex';
 import {BaseTable} from './BaseTable';
@@ -135,6 +135,17 @@ const scrollWrapperStyles = stylex.create({
   },
 });
 
+/**
+ * The Table's own name, for the scroll region that names itself after it.
+ * Internal to Table: the scroll wrapper is not given it as a prop, so it adds
+ * nothing to the public table types.
+ */
+const TableNameContext = createContext<{
+  label?: string;
+  labelledBy?: string;
+} | null>(null);
+TableNameContext.displayName = 'TableNameContext';
+
 function TableScrollWrapper({
   children,
   htmlProps,
@@ -151,7 +162,17 @@ function TableScrollWrapper({
   afterTable?: React.ReactNode;
 }) {
   const t = useTranslator();
-  const label = t('@astryx.table.label');
+  const tableName = use(TableNameContext);
+  // The focusable scroll region takes the table's own name (spec:AST-025
+  // FR12), so two tables are not two groups both named "Table". It is named
+  // the way the table is: `aria-labelledby` wins over `aria-label`, as it does
+  // in accessible-name computation; the generic name is the fallback for an
+  // unnamed table.
+  const labelledBy = tableName?.labelledBy;
+  const label =
+    labelledBy != null
+      ? undefined
+      : (tableName?.label ?? t('@astryx.table.label'));
   const {getViewportProps, getContentProps, state} = useScrollableArea({
     axis: 'inline',
     keyboardAccess: {owner: 'content'},
@@ -161,6 +182,9 @@ function TableScrollWrapper({
   const viewportProps = getViewportProps<HTMLDivElement>({
     role: 'group',
     'aria-label': label,
+    // A plugin's explicit name stays authoritative (Table FR1).
+    'aria-labelledby':
+      restHtmlProps['aria-label'] == null ? labelledBy : undefined,
     ...(state.inline.isScrollable ? {tabIndex: 0} : {}),
     ...restHtmlProps,
     ref,
@@ -240,18 +264,26 @@ function TableInner<T extends Record<string, unknown>>({
     }),
     [density, dividers, isStriped, hasHover, verticalAlign, textOverflow],
   );
+  const tableLabel = rest['aria-label'];
+  const tableLabelledBy = rest['aria-labelledby'];
+  const tableName = useMemo(
+    () => ({label: tableLabel, labelledBy: tableLabelledBy}),
+    [tableLabel, tableLabelledBy],
+  );
 
   return (
     <TableContext value={contextValue}>
-      <BaseTable<T>
-        ref={ref}
-        data={data}
-        columns={columns}
-        plugins={mergedPlugins}
-        textOverflow={textOverflow}
-        scrollWrapper={TableScrollWrapper}
-        {...rest}
-      />
+      <TableNameContext value={tableName}>
+        <BaseTable<T>
+          ref={ref}
+          data={data}
+          columns={columns}
+          plugins={mergedPlugins}
+          textOverflow={textOverflow}
+          scrollWrapper={TableScrollWrapper}
+          {...rest}
+        />
+      </TableNameContext>
     </TableContext>
   );
 }

package/src/Table/plugins/columnResize/useTableColumnResize.tsx

@@ -29,6 +29,8 @@ import {
   DEFAULT_MIN_COLUMN_WIDTH,
 } from '../../columnUtils';
 import {observeResize} from '../../../utils/sharedResizeObserver';
+import {getNodeText} from '../../../utils/getNodeText';
+import {useTranslator} from '../../../i18n';
 
 // =============================================================================
 // Config Type
@@ -384,6 +386,7 @@ function ResizeHandle({
   isDraggingRef,
   tableRef,
 }: ResizeHandleProps) {
+  const t = useTranslator();
   const setTableDragging = useCallback(
     (dragging: boolean) => {
       const table = tableRef.current;
@@ -743,10 +746,11 @@ function ResizeHandle({
     ],
   );
 
-  const ariaLabel =
-    typeof columnHeader === 'string'
-      ? `Resize column ${columnHeader}`
-      : `Resize column ${columnKey}`;
+  // Named by the column's visible text, also when its header is a node; the
+  // key is the fallback only for a header with no reachable text (AR1).
+  const ariaLabel = t('@astryx.table.columnResize.resizeColumn', {
+    label: getNodeText(columnHeader) || columnKey,
+  });
 
   return (
     <div

package/src/Table/plugins/sortable/useTableSortable.tsx

@@ -13,13 +13,13 @@
  * - /packages/core/src/Table/index.ts (exports)
  */
 
-import {useRef, useMemo, type ReactNode} from 'react';
+import {useId, useRef, useMemo, type ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {colorVars, spacingVars, radiusVars} from '../../../theme/tokens.stylex';
 import {focusOutlineProps} from '../../../utils/focusOutline.stylex';
 import {Icon} from '../../../Icon';
 import {resolveContextActions} from '../../tableContextMenu';
-import {useTranslator, type TranslatorFn} from '../../../i18n';
+import {useTranslator} from '../../../i18n';
 import type {
   TablePlugin,
   HeaderCellRenderProps,
@@ -183,42 +183,6 @@ function resolveSortKey<T extends Record<string, unknown>>(
   return sortable.sortKey ?? column.key;
 }
 
-function getHeaderLabel<T extends Record<string, unknown>>(
-  column: TableColumn<T>,
-): string {
-  const {header} = column;
-  if (typeof header === 'string') {
-    return header;
-  }
-  return column.key;
-}
-
-function buildAriaLabel<T extends Record<string, unknown>>(
-  t: TranslatorFn,
-  column: TableColumn<T>,
-  direction: TableSortDirection | null,
-  rank: number | null,
-  total: number,
-): string {
-  const label = getHeaderLabel(column);
-  if (direction == null) {
-    return t('@astryx.table.sort.sortBy', {label});
-  }
-  const directionLabel =
-    direction === 'ascending'
-      ? t('@astryx.table.sort.direction.ascending')
-      : t('@astryx.table.sort.direction.descending');
-  if (rank != null && total > 1) {
-    return t('@astryx.table.sort.sortedByWithPriority', {
-      label,
-      direction: directionLabel,
-      rank,
-      total,
-    });
-  }
-  return t('@astryx.table.sort.sortedBy', {label, direction: directionLabel});
-}
-
 function getNextDirection(
   current: TableSortDirection | null,
   allowUnsortedState: boolean,
@@ -264,13 +228,11 @@ function SortHeaderButton<T extends Record<string, unknown>>({
         ? 'arrowDown'
         : 'arrowsUpDown';
 
-  const ariaLabel = buildAriaLabel(
-    t,
-    column,
-    direction,
-    rank,
-    config.sort.length,
-  );
+  // The button is named by its column's text, so the column header keeps
+  // that name; direction lives in the header's aria-sort. Only the multi-sort
+  // priority, which aria-sort cannot carry, is a description
+  // (spec:AST-020 FR15; WCAG 1.3.1).
+  const priorityId = useId();
 
   const handleClick = (e: React.MouseEvent | React.KeyboardEvent) => {
     const cfg = configRef.current;
@@ -315,37 +277,46 @@ function SortHeaderButton<T extends Record<string, unknown>>({
   };
 
   return (
-    <button
-      type="button"
-      {...focusOutlineProps.focusVisible(
-        sortStyles.button,
-        column.align === 'end'
-          ? sortStyles.buttonAlignEnd
-          : column.align === 'center'
-            ? sortStyles.buttonAlignCenter
-            : null,
-      )}
-      aria-label={ariaLabel}
-      onClick={handleClick}>
-      <span>{children}</span>
-      <span
-        {...stylex.props(
-          direction != null
-            ? sortStyles.iconWrapperActive
-            : sortStyles.iconWrapperUnsorted,
-        )}>
-        <Icon
-          icon={iconName}
-          size="xsm"
-          color={direction != null ? 'accent' : 'secondary'}
-        />
-      </span>
+    <>
+      <button
+        type="button"
+        {...focusOutlineProps.focusVisible(
+          sortStyles.button,
+          column.align === 'end'
+            ? sortStyles.buttonAlignEnd
+            : column.align === 'center'
+              ? sortStyles.buttonAlignCenter
+              : null,
+        )}
+        aria-describedby={rank != null ? priorityId : undefined}
+        onClick={handleClick}>
+        <span>{children}</span>
+        <span
+          {...stylex.props(
+            direction != null
+              ? sortStyles.iconWrapperActive
+              : sortStyles.iconWrapperUnsorted,
+          )}>
+          <Icon
+            icon={iconName}
+            size="xsm"
+            color={direction != null ? 'accent' : 'secondary'}
+          />
+        </span>
+        {rank != null && (
+          <span {...stylex.props(sortStyles.rank)} aria-hidden="true">
+            {rank}
+          </span>
+        )}
+      </button>
       {rank != null && (
-        <span {...stylex.props(sortStyles.rank)} aria-hidden="true">
-          {rank}
+        // Hidden, so it adds nothing to the button's or the header's name;
+        // aria-describedby still reads it.
+        <span id={priorityId} hidden>
+          {t('@astryx.table.sort.priority', {rank, total: config.sort.length})}
         </span>
       )}
-    </button>
+    </>
   );
 }
 

package/src/Text/Text.tsx

@@ -48,7 +48,7 @@ import {
 } from './text.stylex';
 import {useTruncation} from './useTruncation';
 import type {LayerPlacement} from '../Layer';
-import {mergeProps} from '../utils';
+import {mergeProps} from '../utils/mergeProps';
 import {useMergedRefs} from '../hooks/useMergedRefs';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';

package/src/Text/useTruncation.ts

@@ -123,12 +123,30 @@ export function useTruncation(
       elementRef.current = element;
 
       if (element && maxLines > 0) {
-        // Observe via shared singleton (if available).
-        // observeResize fires the callback once on registration,
-        // so no separate initial check is needed.
+        // Observe via shared singleton (if available). The first measurement
+        // runs after the commit, in a microtask, instead of in the call
+        // observeResize makes on registration: that call runs inside React's
+        // commit, after other components' DOM writes, and forced a style and
+        // layout pass per text on a page that mounts many. Every text
+        // registered in one commit then reads layout once, together, and a
+        // text whose element another subscriber already observes is measured
+        // too. The truncated state only decides whether to compose the
+        // tooltip, so nothing paints differently.
         if (typeof ResizeObserver !== 'undefined') {
-          unobserveRef.current = observeResize(element, () => {
-            checkTruncation(element);
+          let registered = false;
+          const unobserve = observeResize(element, () => {
+            if (registered) {
+              checkTruncation(element);
+            }
+          });
+          registered = true;
+          unobserveRef.current = unobserve;
+          // Skipped when this registration has ended by then (measuring
+          // turned off, or the element replaced, in the same task).
+          queueMicrotask(() => {
+            if (unobserveRef.current === unobserve) {
+              checkTruncation(element);
+            }
           });
         } else {
           checkTruncation(element);

package/src/TextArea/TextArea.spec.md

@@ -52,15 +52,15 @@ system_specs: [spec:AST-085, spec:AST-086]
 
 ## Contract at a glance
 
-| Area                    | Contract                                                                                                                                                                                                                                                                                 |
-| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract         | None changes. TextArea is a controlled multi-line field with Field props, `rows`, size, status, start icon, `maxLength` counter, `onChange`, `changeAction`, `isLoading`, disabled and read-only states, and the input-family part props.                                                |
-| Behavior                | Typing calls `onChange`, then an optional `changeAction` with an optimistic value and one busy Spinner. `maxLength` adds a visual character counter that warns but never blocks typing.                                                                                                  |
-| End-user impact         | People write longer text with a live count that is announced only when they near or pass the limit. Keyboard and screen-reader users can reach a disabled field and its reason. An error without a message has no text.                                                                  |
-| Builder impact          | None.                                                                                                                                                                                                                                                                                    |
-| Compatibility/readiness | Records shipped behavior; no API, default, or DOM change. Attached status on a tall surface, dropped grouped container props, text under the counter, counter text outside the catalog, an error without text, and a color-only `detached` status are listed under Current-state impact. |
-| Review checks           | Reject a counter that truncates input or counts code units, an announcement on every keystroke, text that runs under the icons or counter, a disabled field that leaves the tab order or submits, or root styling props.                                                                 |
-| Governing rules         | `family:input-fields` FR4–FR6, FR8–FR10, AV3; `spec:AST-085` FR1–FR3, FR6; `spec:AST-086` FR8; `architecture:component-theming-surface`.                                                                                                                                                 |
+| Area                    | Contract                                                                                                                                                                                                                                               |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Public contract         | None changes. TextArea is a controlled multi-line field with Field props, `rows`, size, status, start icon, `maxLength` counter, `onChange`, `changeAction`, `isLoading`, disabled and read-only states, and the input-family part props.              |
+| Behavior                | Typing calls `onChange`, then an optional `changeAction` with an optimistic value and one busy Spinner. `maxLength` adds a visual character counter that warns but never blocks typing.                                                                |
+| End-user impact         | People write longer text with a live count that is announced only when they near or pass the limit. Keyboard and screen-reader users can reach a disabled field and its reason. An error without a message has no text.                                |
+| Builder impact          | None.                                                                                                                                                                                                                                                  |
+| Compatibility/readiness | Records shipped behavior; no API, default, or DOM change. Attached status on a tall surface, dropped grouped container props, text under the counter, an error without text, and a color-only `detached` status are listed under Current-state impact. |
+| Review checks           | Reject a counter that truncates input or counts code units, an announcement on every keystroke, text that runs under the icons or counter, a disabled field that leaves the tab order or submits, or root styling props.                               |
+| Governing rules         | `family:input-fields` FR4–FR6, FR8–FR10, AV3; `spec:AST-085` FR1–FR3, FR6; `spec:AST-086` FR8; `architecture:component-theming-surface`.                                                                                                               |
 
 This table is a review projection; the body below is authoritative.
 
@@ -128,7 +128,7 @@ Consumer migration instructions belong in consumer docs and release notes.
 | FR2  | The input container carries `text-area` with `data-size`, `data-status`, `data-disabled`, and `data-readonly`; the textarea carries `text-area-control`; the counter carries `text-area-counter`. Placeholder text is part of the textarea; the over-limit glyph is part of the counter.                                                                                                                                                                                                                                                                                                                                                                                                                                       | `architecture:component-theming-surface`; current source and tests    |
 | FR3  | The textarea shows `rows` lines (default 3), resizes only vertically, and uses body text, floored at 16 CSS px only on the iOS touch path. `lg` adds block padding; `sm` and `md` share the default inset.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `family:input-fields` FR9, AV3; current source and tests              |
 | FR4  | Editing calls `onChange(value, event)`; unless that call prevents default, `changeAction(value, event)` then runs in a transition and the field shows the proposed value while the Action is pending, and `value` once it settles. While `isLoading` or while the shown value differs from `value`, the textarea sets `aria-busy`, a decorative Spinner shows, and the busy start is announced once.                                                                                                                                                                                                                                                                                                                           | `family:input-fields` FR5, FR6; `spec:AST-086` FR8; current tests     |
-| FR5  | With `maxLength`, a counter showing the character count and the limit renders at the container's bottom end and describes the textarea. It counts user-perceived characters, so a multi-code-point emoji counts once. It never sets the native `maxLength` and never blocks typing. Over the limit it turns the error color, adds a decorative warning icon, and sets `aria-invalid`. The counter text MUST come from one catalog message (`architecture:internationalization` INV1a). Implementation gap: it is assembled in code as count, slash, and limit.                                                                                                                                                                 | Current tests; `architecture:internationalization` INV1a              |
+| FR5  | With `maxLength`, a counter showing the character count and the limit renders at the container's bottom end and describes the textarea. It counts user-perceived characters, so a multi-code-point emoji counts once. It never sets the native `maxLength` and never blocks typing. Over the limit it turns the error color, adds a decorative warning icon, and sets `aria-invalid`. The counter text MUST come from one catalog message (`architecture:internationalization` INV1a), with both numbers in the locale's number format.                                                                                                                                                                                        | Current tests; `architecture:internationalization` INV1a              |
 | FR6  | Counter announcements happen when an edit lands in a different zone than the previous edit: entering the last 20% of the limit announces the remaining characters politely; exceeding the limit announces the overage assertively; moving back under announces nothing. Zone tracking starts unset, so the first edit after mount announces the near or over zone it lands in, even when the mounted value was already there.                                                                                                                                                                                                                                                                                                  | Current tests                                                         |
 | FR7  | The start icon renders at the top start, and the Spinner and on-field status icon at the top end; the textarea reserves inline padding for each one that renders (more when both end items show) and bottom padding for the counter, so text never runs under them; the counter's bottom padding clears text only at the end of the scroll range. Implementation gap: with a value longer than `rows`, the last visible line paints under the counter unless the field is scrolled to the end. A detached status reserves no end space because it renders no on-field icon.                                                                                                                                                    | `family:input-fields` FR2; current source and tests                   |
 | FR8  | A status paints the status border; `error` sets `aria-invalid`. The on-field status icon shows for `attached` and `tooltip` placement; a `detached` status shows its glyph only in the message box, which renders only with a message. The message renders through Field in the chosen placement. Every status MUST show a cue other than color (WCAG 2.2 1.4.1), and an error MUST be identified in text (WCAG 2.2 3.3.1). Implementation gap: TextArea offers `attached` placement, as its default and explicitly, although `family:input-fields` FR8 and AV6 allow `attached` only on a fixed-height control; an error status may have no message; and a `detached` status without a message shows only the colored border. | `family:input-fields` FR8; current tests                              |
@@ -276,9 +276,6 @@ above match the current Field, FieldStatus, Icon, Spinner, and Tooltip targets.
   FR8 and AV6 allow `attached` only on a fixed-height control.
 - **Grouped container props (FR12).** Inside InputGroup, TextArea still renders
   its Field box but drops `container*` props, warning that no Field box renders.
-- **Counter text (FR5).** The counter's count-and-limit text is assembled in
-  code rather than from one catalog message, against
-  `architecture:internationalization` INV1a.
 - **Text under the counter (FR7).** With a value longer than `rows`, the last
   visible line paints under the counter unless the field is scrolled to the
   end.

package/src/TextArea/TextArea.tsx

@@ -47,6 +47,7 @@ import {Icon, renderIconSlot, type IconType} from '../Icon';
 import {Spinner} from '../Spinner';
 import {useTooltip} from '../Tooltip';
 import {mergeProps} from '../utils';
+import {joinAriaIDs} from '../utils/inputAria';
 import type {BaseProps} from '../BaseProps';
 import {
   type FieldInputBaseProps,
@@ -417,6 +418,7 @@ export function TextArea({
   ref,
   id: idProp,
   'aria-describedby': ariaDescribedByProp,
+  'aria-labelledby': ariaLabelledByProp,
   ...restProps
 }: TextAreaProps) {
   const {rest, container} = useFieldInputStyling('TextArea', restProps, {
@@ -430,6 +432,7 @@ export function TextArea({
   const announce = useAnnounce();
   const generatedID = useId();
   const id = idProp ?? generatedID;
+  const fieldLabelID = useId();
   const descriptionID = useId();
   const statusMessageID = useId();
   const counterID = useId();
@@ -572,6 +575,7 @@ export function TextArea({
       isLabelHidden={isLabelHidden}
       description={description}
       inputID={id}
+      labelID={ariaLabelledByProp != null ? fieldLabelID : undefined}
       descriptionID={description ? descriptionID : undefined}
       isOptional={isOptional}
       isRequired={isRequired}
@@ -644,6 +648,13 @@ export function TextArea({
           spellCheck={hasSpellCheck}
           autoFocus={hasAutoFocus}
           data-autofocus={hasAutoFocus || undefined}
+          // A caller aria-labelledby names the textarea together with the
+          // field's own label, which it would otherwise replace.
+          aria-labelledby={
+            ariaLabelledByProp != null
+              ? joinAriaIDs(fieldLabelID, ariaLabelledByProp)
+              : undefined
+          }
           aria-describedby={
             [ariaDescribedByProp, ariaDescribedBy].filter(Boolean).join(' ') ||
             undefined
@@ -696,7 +707,10 @@ export function TextArea({
               // live-region announcement carry the meaning.
               <Icon icon="warning" size="sm" />
             )}
-            {valueLength}/{maxLength}
+            {t('@astryx.textArea.counter', {
+              count: valueLength,
+              limit: maxLength,
+            })}
           </div>
         )}
       </div>

package/src/TextInput/TextInput.tsx

@@ -537,13 +537,15 @@ export function TextInput({
         aria-labelledby={inputLabelledBy}
         {...stylex.props(styles.input, isDisabled && styles.inputDisabled)}
       />
+      {/* The Spinner comes first so it appears inward of the clear button
+          and the button keeps its place when the field turns busy. */}
+      {isBusy && <Spinner size="sm" aria-hidden="true" />}
       {hasClear && value !== '' && !isDisabled && !isReadOnly && (
         <InputClearButton
           label={t('@astryx.textInput.clearLabel', {label})}
           onClick={handleClear}
         />
       )}
-      {isBusy && <Spinner size="sm" aria-hidden="true" />}
       {statusIcon}
     </div>
   );

package/src/TimeInput/TimeInput.doc.mjs

@@ -31,7 +31,7 @@ export const docs = {
       {
         guidance: true,
         description:
-          "Choose the hour format (12h or 24h) that matches your audience's locale: 12-hour with AM/PM for US-centric UIs, 24-hour for international or technical contexts.",
+          "Leave hourFormat unset so the field follows the InternationalizationProvider locale's hour cycle (12-hour in en-US, 24-hour in en-GB or de-DE). Set it only when the field itself needs a fixed format, and carry a person's own 12/24-hour preference on the provider locale (e.g. 'en-US-u-hc-h23') rather than on each field.",
       },
       {
         guidance: true,
@@ -206,8 +206,8 @@ export const docs = {
       name: 'hourFormat',
       type: "'12h' | '24h'",
       description:
-        "Controls the display format. '12h' shows AM/PM (e.g. '2:30 PM'); '24h' uses 24-hour notation (e.g. '14:30').",
-      default: "'12h'",
+        "Controls the display format. '12h' shows the locale's day period (e.g. '2:30 PM', '오후 2:30'); '24h' uses 24-hour notation (e.g. '14:30'). When unset, follows the InternationalizationProvider locale's hour cycle: en-US reads 12-hour, en-GB and de-DE read 24-hour. To honor a person's own preference, pass it on the locale tag (e.g. 'en-US-u-hc-h23') rather than per field.",
+      default: "the locale's hour cycle",
     },
     {
       name: 'increment',
@@ -387,8 +387,8 @@ export const docsZh = {
       name: 'hourFormat',
       type: "'12h' | '24h'",
       description:
-        "控制显示格式。'12h' 显示 AM/PM（例如 '2:30 PM'）；'24h' 使用 24 小时制（例如 '14:30'）。",
-      default: "'12h'",
+        "控制显示格式。'12h' 使用区域设置的上午/下午用语（例如 '2:30 PM'、'오후 2:30'）；'24h' 使用 24 小时制（例如 '14:30'）。未设置时遵循 InternationalizationProvider 区域设置的小时制：en-US 为 12 小时制，en-GB 和 de-DE 为 24 小时制。要遵循用户自己的偏好，请在区域标签中传入（例如 'en-US-u-hc-h23'），而不是逐个字段设置。",
+      default: '区域设置的小时制',
     },
     {
       name: 'increment',
@@ -476,7 +476,7 @@ export const docsZh = {
       {
         guidance: true,
         description:
-          "Choose the hour format (12h or 24h) that matches your audience's locale: 12-hour with AM/PM for US-centric UIs, 24-hour for international or technical contexts.",
+          "Leave hourFormat unset so the field follows the InternationalizationProvider locale's hour cycle (12-hour in en-US, 24-hour in en-GB or de-DE). Set it only when the field itself needs a fixed format, and carry a person's own 12/24-hour preference on the provider locale (e.g. 'en-US-u-hc-h23') rather than on each field.",
       },
       {
         guidance: true,
@@ -565,7 +565,7 @@ export const docsDense = {
       {
         guidance: true,
         description:
-          'Choose hour format (12h/24h) to match locale: 12h for US, 24h for international.',
+          "Leave hourFormat unset to follow the provider locale's hour cycle; put a person's 12/24h preference on the locale tag (en-US-u-hc-h23), not on each field.",
       },
       {
         guidance: true,
@@ -624,7 +624,7 @@ export const docsDense = {
     hasSeconds: 'Includes seconds in display+parsing.',
     hasClear: 'Shows clear button when value set+not disabled.',
     hourFormat:
-      "Display format. '12h' shows AM/PM; '24h' uses 24-hour notation.",
+      "Display format. '12h' shows the locale's day period; '24h' uses 24-hour notation. Unset follows the provider locale's hour cycle (a -u-hc- tag carries a user preference).",
     increment:
       'Minutes to add/subtract on arrow up/down. Whole minutes only; a fractional value leaves the time unchanged.',
     presentation: