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

package/src/TabList/__tests__/TabPressPointer.interaction.browser.spec.ts

@@ -0,0 +1,163 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file TabPressPointer.interaction.browser.spec.ts
+ * @input Uses @playwright/test and the interaction harness (a built
+ *   Storybook)
+ * @output Proves a Tab's hover and press layer under a fine and a coarse
+ *   primary pointer
+ * @position Interaction proof for packages/core/src/TabList/Tab.tsx
+ *
+ * Tab's press layer has a hover branch and a coarse-pointer rule, which
+ * StyleX makes exclusive. The outcome on every pointer: a fine pointer
+ * paints the hover, then a pressed overlay that differs from it; under a
+ * coarse pointer a finger's press paints as an image (`data-astryx-press`),
+ * and the colour layer stays transparent while the tab is `:active`.
+ * Chromium only: it holds a finger, and forces `:active`, through the
+ * DevTools protocol.
+ */
+
+import {expect, test, type CDPSession, type Page} from '@playwright/test';
+import {openStory, withStorybook} from '@astryxdesign/interaction-harness';
+
+const storybook = withStorybook(test);
+
+const TRANSPARENT = 'rgba(0, 0, 0, 0)';
+
+/** The "Projects" tab: not the story's current one. */
+function projectsTab(page: Page) {
+  return page.locator('button', {hasText: 'Projects'}).first();
+}
+
+/** The tab's colour layer (its first aria-hidden span) and the pointer. */
+async function tabState(page: Page): Promise<{
+  colour: string;
+  image: string;
+  press: string | null;
+  coarse: boolean;
+  hover: boolean;
+}> {
+  return projectsTab(page).evaluate(element => {
+    const layer = element.querySelector('span[aria-hidden="true"]');
+    const style = layer == null ? null : getComputedStyle(layer);
+    return {
+      colour: style?.backgroundColor ?? '',
+      image: style?.backgroundImage ?? '',
+      press: element.getAttribute('data-astryx-press'),
+      coarse: matchMedia('(pointer: coarse)').matches,
+      hover: matchMedia('(hover: hover)').matches,
+    };
+  });
+}
+
+/** The layer's colour once its transition has landed (three equal reads). */
+async function settledColour(page: Page): Promise<string> {
+  let last = '';
+  let same = 0;
+  for (let read = 0; read < 60 && same < 3; read++) {
+    const colour = (await tabState(page)).colour;
+    same = colour === last ? same + 1 : 1;
+    last = colour;
+    await page.waitForTimeout(50);
+  }
+  return last;
+}
+
+/** The tab's centre, in page coordinates. */
+async function tabCentre(page: Page): Promise<{x: number; y: number}> {
+  const box = await projectsTab(page).boundingBox();
+  if (box == null) {
+    throw new Error('the Projects tab has no box');
+  }
+  return {x: box.x + box.width / 2, y: box.y + box.height / 2};
+}
+
+/** A finger held on the tab's centre; returns the lift. */
+async function holdFinger(
+  page: Page,
+  cdp: CDPSession,
+): Promise<() => Promise<void>> {
+  await cdp.send('Input.dispatchTouchEvent', {
+    type: 'touchStart',
+    touchPoints: [await tabCentre(page)],
+  });
+  return async () => {
+    await cdp.send('Input.dispatchTouchEvent', {
+      type: 'touchEnd',
+      touchPoints: [],
+    });
+  };
+}
+
+/** Puts the tab in `:active` (or out of it) through the DevTools protocol. */
+async function forceActive(cdp: CDPSession, isActive: boolean): Promise<void> {
+  await cdp.send('DOM.enable');
+  await cdp.send('CSS.enable');
+  const {root} = await cdp.send('DOM.getDocument', {depth: -1});
+  const {nodeIds} = await cdp.send('DOM.querySelectorAll', {
+    nodeId: root.nodeId,
+    selector: 'button',
+  });
+  for (const nodeId of nodeIds) {
+    const {outerHTML} = await cdp.send('DOM.getOuterHTML', {nodeId});
+    if (outerHTML.includes('Projects')) {
+      await cdp.send('CSS.forcePseudoState', {
+        nodeId,
+        forcedPseudoClasses: isActive ? ['active'] : [],
+      });
+      return;
+    }
+  }
+  throw new Error('the Projects tab has no node');
+}
+
+test.describe('Tab press layer by pointer', () => {
+  test.skip(
+    ({browserName}) => browserName !== 'chromium',
+    'Chromium holds a finger and forces :active through the DevTools protocol',
+  );
+
+  test.describe('fine pointer with hover', () => {
+    test.use({isMobile: false, hasTouch: false});
+    test('paints the hover, then a pressed overlay that differs from it', async ({
+      page,
+    }) => {
+      await openStory(page, storybook(), 'core-tablist--default');
+      await projectsTab(page).hover();
+      const state = await tabState(page);
+      expect(state.coarse).toBe(false);
+      expect(state.hover).toBe(true);
+      await expect
+        .poll(async () => (await tabState(page)).colour)
+        .not.toBe(TRANSPARENT);
+      const hovered = await settledColour(page);
+      await page.mouse.down();
+      // The pressed overlay is its own colour, not the hover paint held on.
+      await expect
+        .poll(async () => (await tabState(page)).colour)
+        .not.toBe(hovered);
+      expect(await settledColour(page)).not.toBe(hovered);
+      await page.mouse.up();
+    });
+  });
+
+  test("coarse pointer: a finger's press paints as an image, and the colour layer stays transparent while the tab is :active", async ({
+    page,
+  }) => {
+    await openStory(page, storybook(), 'core-tablist--default');
+    const cdp = await page.context().newCDPSession(page);
+    expect((await tabState(page)).coarse).toBe(true);
+    // The finger's press: the press model marks the tab, and the layer
+    // paints the pressed overlay as an image.
+    const lift = await holdFinger(page, cdp);
+    await expect.poll(async () => (await tabState(page)).press).toBe('on');
+    expect((await tabState(page)).image).not.toBe('none');
+    await lift();
+    await expect.poll(async () => (await tabState(page)).press).not.toBe('on');
+    // The tab in :active under the coarse pointer: the reset keeps the
+    // colour layer transparent, past any transition.
+    await forceActive(cdp, true);
+    expect(await settledColour(page)).toBe(TRANSPARENT);
+    await forceActive(cdp, false);
+  });
+});

package/src/Table/__tests__/Table.a11y.chromium.spec.ts

@@ -100,15 +100,27 @@ async function runState(
   });
 }
 
-test('every Table expectation is exercised by at least one Table state', async ({
-  page,
-}) => {
-  const cdp = await page.context().newCDPSession(page);
+// Checking coverage runs every state again, which on a loaded runner nears
+// the per-test timeout as one test. It runs as one serial part per state,
+// sharing their results, then one check over all of them.
+test.describe('every Table expectation is exercised by at least one Table state', () => {
+  test.describe.configure({mode: 'serial'});
   const results: BindingResult[] = [];
+
   for (const state of TABLE_A11Y_STATES) {
-    results.push(await runState(page, cdp, state));
+    test(`runs ${state.id}`, async ({page}) => {
+      const cdp = await page.context().newCDPSession(page);
+      results.push(await runState(page, cdp, state));
+    });
   }
-  expect(neverExercised(results)).toEqual([]);
+
+  test('no expectation is left unexercised', () => {
+    // Every part ran in this worker; this test alone proves nothing.
+    expect(results.map(result => result.state).sort()).toEqual(
+      TABLE_A11Y_STATES.map(state => state.id).sort(),
+    );
+    expect(neverExercised(results)).toEqual([]);
+  });
 });
 
 for (const state of TABLE_A11Y_STATES) {

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

@@ -574,6 +574,28 @@ describe('useTableColumnResize', () => {
       expect(handle).toHaveAttribute('aria-label', 'Resize column Name');
     });
 
+    it("names a node header's handle by the header's visible text (AR1)", () => {
+      function Glyph() {
+        return <svg aria-hidden />;
+      }
+      render(
+        <ResizeTable
+          columns={[
+            {key: 'name', header: <span>Amount (EUR)</span>},
+            {key: 'role', header: <Glyph />},
+            {key: 'id', header: 'ID'},
+          ]}
+        />,
+      );
+      const [amount, role] = getResizeHandles();
+      expect(amount).toHaveAttribute(
+        'aria-label',
+        'Resize column Amount (EUR)',
+      );
+      // A header with no text it renders through children falls back to the key.
+      expect(role).toHaveAttribute('aria-label', 'Resize column role');
+    });
+
     it('handle has aria-valuemin', () => {
       render(<ResizeTable minWidth={80} />);
       const handle = getResizeHandles()[0];

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/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.test.tsx

@@ -5,8 +5,9 @@
  * Tests for useTruncation
  */
 
-import {render, screen, waitFor} from '@testing-library/react';
+import {act, render, screen, waitFor} from '@testing-library/react';
 import {afterEach, describe, it, expect, vi} from 'vitest';
+import {useCallback} from 'react';
 import {useTruncation} from './useTruncation';
 
 function Probe({text}: {text: string}) {
@@ -37,6 +38,132 @@ describe('useTruncation', () => {
     );
   });
 
+  describe('first measurement', () => {
+    afterEach(() => {
+      vi.unstubAllGlobals();
+    });
+
+    // Measuring inside React's commit forces a style and layout pass per text
+    // on a page that mounts many; after the commit, every text reads together.
+    it('measures after the commit, not inside it', async () => {
+      const observed: Element[] = [];
+      vi.stubGlobal(
+        'ResizeObserver',
+        class {
+          observe(target: Element) {
+            observed.push(target);
+          }
+          unobserve() {}
+          disconnect() {}
+        },
+      );
+
+      const {unmount} = render(<Probe text="a status line" />);
+
+      // Observed, but not measured during the commit.
+      expect(observed).toHaveLength(1);
+      expect(screen.getByTestId('full-text')).toHaveTextContent('');
+
+      await act(async () => {});
+
+      expect(screen.getByTestId('full-text')).toHaveTextContent(
+        'a status line',
+      );
+      unmount();
+    });
+
+    // FR4/PR1: with measuring turned off before the first measurement runs,
+    // nothing is measured and the hook reports no truncation.
+    it('skips the first measurement when measuring turns off in the same task', async () => {
+      vi.stubGlobal(
+        'ResizeObserver',
+        class {
+          observe() {}
+          unobserve() {}
+          disconnect() {}
+        },
+      );
+      const proto = window.HTMLElement.prototype;
+      const scrollWidth = Object.getOwnPropertyDescriptor(proto, 'scrollWidth');
+      const offsetWidth = Object.getOwnPropertyDescriptor(proto, 'offsetWidth');
+      Object.defineProperty(proto, 'scrollWidth', {
+        configurable: true,
+        get: () => 400,
+      });
+      Object.defineProperty(proto, 'offsetWidth', {
+        configurable: true,
+        get: () => 100,
+      });
+      function Unclamping({maxLines}: {maxLines: number}) {
+        const truncation = useTruncation({maxLines});
+        return (
+          <>
+            <span ref={truncation.ref}>overflowing text</span>
+            <output data-testid="state">
+              {String(truncation.isTruncated)}|{truncation.fullText}
+            </output>
+          </>
+        );
+      }
+      try {
+        // Measuring turns off in the same task, before the first measurement.
+        const {rerender, unmount} = render(<Unclamping maxLines={1} />);
+        rerender(<Unclamping maxLines={0} />);
+        await act(async () => {});
+        expect(screen.getByTestId('state')).toHaveTextContent(/^false\|$/);
+        unmount();
+      } finally {
+        if (scrollWidth) {
+          Object.defineProperty(proto, 'scrollWidth', scrollWidth);
+        }
+        if (offsetWidth) {
+          Object.defineProperty(proto, 'offsetWidth', offsetWidth);
+        }
+      }
+    });
+
+    // The browser sends no second first-notification for an element the
+    // shared observer already watches, so the first measurement cannot wait
+    // for one.
+    it('measures an element another subscriber already observes', async () => {
+      vi.stubGlobal(
+        'ResizeObserver',
+        class {
+          observe() {}
+          unobserve() {}
+          disconnect() {}
+        },
+      );
+      const {observeResize} = await import('../utils/sharedResizeObserver');
+      const watched = document.createElement('span');
+      function Shared({text}: {text: string}) {
+        const truncation = useTruncation({maxLines: 1});
+        const {ref} = truncation;
+        const attach = useCallback(
+          (element: HTMLElement | null) => {
+            if (element && element !== watched) {
+              observeResize(element, () => {});
+            }
+            ref(element);
+          },
+          [ref],
+        );
+        return (
+          <>
+            <span ref={attach}>{text}</span>
+            <output data-testid="full-text">{truncation.fullText}</output>
+          </>
+        );
+      }
+      const {unmount} = render(<Shared text="already watched" />);
+      await act(async () => {});
+      expect(screen.getByTestId('full-text')).toHaveTextContent(
+        'already watched',
+      );
+      unmount();
+    });
+  });
+
   describe('content observation', () => {
     afterEach(() => {
       vi.unstubAllGlobals();

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.test.tsx

@@ -17,6 +17,7 @@ import * as stylex from '@stylexjs/stylex';
 import {colorVars} from '../theme/tokens.stylex';
 import {TestIcon} from '../__tests__/TestIcon';
 import {TextArea} from './TextArea';
+import {InternationalizationProvider} from '../i18n';
 import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
 
 // jsdom cannot match `:focus-visible`: compare the ring's StyleX class hash.
@@ -521,6 +522,38 @@ describe('TextArea', () => {
       expect(screen.getByText('5/20')).toBeInTheDocument();
     });
 
+    it('formats the counter from the catalog with locale number formatting', () => {
+      render(
+        <InternationalizationProvider
+          locale="de-DE"
+          overrides={{
+            'de-DE': {
+              '@astryx.textArea.counter': '{count, number} von {limit, number}',
+            },
+          }}>
+          <TextArea
+            label="Bio"
+            value={'a'.repeat(62)}
+            onChange={() => {}}
+            maxLength={2000}
+          />
+        </InternationalizationProvider>,
+      );
+      expect(screen.getByText('62 von 2.000')).toBeInTheDocument();
+    });
+
+    it('formats an English counter with grouped digits', () => {
+      render(
+        <TextArea
+          label="Bio"
+          value="hi"
+          onChange={() => {}}
+          maxLength={2000}
+        />,
+      );
+      expect(screen.getByText('2/2,000')).toBeInTheDocument();
+    });
+
     it('does not display counter when maxLength is not provided', () => {
       render(
         <TextArea label="Description" value="Hello" onChange={() => {}} />,
@@ -1255,3 +1288,30 @@ describe('TextArea theme target names', () => {
     expect(root).not.toHaveClass('astryx-textarea');
   });
 });
+
+describe('TextArea caller aria-labelledby', () => {
+  it('names the textarea by its label and a caller aria-labelledby', () => {
+    render(
+      <>
+        <span id="billing-heading">Billing</span>
+        <TextArea
+          label="Notes"
+          value=""
+          onChange={() => {}}
+          aria-labelledby="billing-heading"
+        />
+      </>,
+    );
+    const textarea = screen.getByRole('textbox', {name: 'Notes Billing'});
+    expect(textarea.getAttribute('aria-labelledby')?.split(' ')).toContain(
+      'billing-heading',
+    );
+  });
+
+  it('leaves a textarea named by its label element without a caller aria-labelledby', () => {
+    render(<TextArea label="Notes" value="" onChange={() => {}} />);
+    expect(screen.getByRole('textbox', {name: 'Notes'})).not.toHaveAttribute(
+      'aria-labelledby',
+    );
+  });
+});

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>