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

package/src/Table/plugins/sortable/useTableSortableState.test.tsx

@@ -186,9 +186,7 @@ describe('useTableSortableState', () => {
       render(<SortableStateTable />);
 
       // Click Name header to sort ascending
-      await userEvent.click(
-        screen.getByRole('button', {name: /sort by name/i}),
-      );
+      await userEvent.click(screen.getByRole('button', {name: 'Name'}));
       expect(getNameColumnValues()).toEqual([
         'Alice',
         'Bob',
@@ -197,9 +195,7 @@ describe('useTableSortableState', () => {
       ]);
 
       // Click again to sort descending
-      await userEvent.click(
-        screen.getByRole('button', {name: /sort by name/i}),
-      );
+      await userEvent.click(screen.getByRole('button', {name: 'Name'}));
       expect(getNameColumnValues()).toEqual([
         'Diana',
         'Charlie',
@@ -223,7 +219,7 @@ describe('useTableSortableState', () => {
       ]);
 
       // Sort by age instead
-      await userEvent.click(screen.getByRole('button', {name: /sort by age/i}));
+      await userEvent.click(screen.getByRole('button', {name: 'Age'}));
 
       // Age ascending: Alice(28), Diana(31), Charlie(35), Bob(42)
       expect(getNameColumnValues()).toEqual([
@@ -243,13 +239,9 @@ describe('useTableSortableState', () => {
       );
 
       // Click to descending
-      await userEvent.click(
-        screen.getByRole('button', {name: /sort by name/i}),
-      );
+      await userEvent.click(screen.getByRole('button', {name: 'Name'}));
       // Click to unsorted
-      await userEvent.click(
-        screen.getByRole('button', {name: /sort by name/i}),
-      );
+      await userEvent.click(screen.getByRole('button', {name: 'Name'}));
 
       // Back to original order
       expect(getNameColumnValues()).toEqual([
@@ -265,7 +257,7 @@ describe('useTableSortableState', () => {
     it('sorts numbers correctly without custom comparator', async () => {
       render(<SortableStateTable />);
 
-      await userEvent.click(screen.getByRole('button', {name: /sort by age/i}));
+      await userEvent.click(screen.getByRole('button', {name: 'Age'}));
 
       // Age ascending: 28, 31, 35, 42
       expect(getNameColumnValues()).toEqual([
@@ -397,9 +389,7 @@ describe('useTableSortableState', () => {
 
       render(<ControlledWithSpy />);
 
-      await userEvent.click(
-        screen.getByRole('button', {name: /sort by name/i}),
-      );
+      await userEvent.click(screen.getByRole('button', {name: 'Name'}));
 
       expect(onSortChange).toHaveBeenCalledWith([
         {sortKey: 'name', direction: 'ascending'},
@@ -442,7 +432,7 @@ describe('useTableSortableState', () => {
       // Department ascending: Design(Bob, Diana), Engineering(Alice, Charlie)
       // Now shift+click Name to add secondary sort
       await user.keyboard('{Shift>}');
-      await user.click(screen.getByRole('button', {name: /sort by name/i}));
+      await user.click(screen.getByRole('button', {name: 'Name'}));
       await user.keyboard('{/Shift}');
 
       // Design: Bob, Diana; Engineering: Alice, Charlie
@@ -541,9 +531,7 @@ describe('useTableSortableState', () => {
       // Should render without throwing — table still mounts with empty data
       expect(screen.getByRole('table')).toBeInTheDocument();
       // Sort headers should still be interactive
-      expect(
-        screen.getByRole('button', {name: /sort by name/i}),
-      ).toBeInTheDocument();
+      expect(screen.getByRole('button', {name: 'Name'})).toBeInTheDocument();
     });
   });
 

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>

package/src/TextInput/TextInput.test.tsx

@@ -823,6 +823,27 @@ describe('TextInput', () => {
     });
   });
 
+  it('keeps the clear button where it is when the field turns busy', () => {
+    // What follows the button in the lane (a `<template>` is not rendered).
+    const after = (button: HTMLElement) =>
+      Array.from(button.parentElement?.children ?? [])
+        .slice(Array.from(button.parentElement?.children ?? []).indexOf(button))
+        .filter(el => el !== button && el.tagName !== 'TEMPLATE');
+    const props = {label: 'Name', value: 'hello', onChange: () => {}};
+    const {rerender} = render(<TextInput {...props} hasClear />);
+    const idle = screen.getByRole('button', {name: 'Clear Name'});
+    const idleAfter = after(idle).length;
+
+    rerender(<TextInput {...props} hasClear isLoading />);
+    const busy = screen.getByRole('button', {name: 'Clear Name'});
+    // The Spinner joins on the inward side, before the button, so nothing new
+    // follows it and its distance from the end does not change.
+    expect(after(busy)).toHaveLength(idleAfter);
+    expect(busy.previousElementSibling?.getAttribute('aria-hidden')).toBe(
+      'true',
+    );
+  });
+
   describe('click-to-focus', () => {
     it('focuses input when clicking the start icon', () => {
       render(

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

@@ -10,6 +10,7 @@
 import {afterEach, describe, expect, it, vi} from 'vitest';
 import {act, fireEvent, render, screen} from '@testing-library/react';
 import {TimeInput} from './TimeInput';
+import {InternationalizationProvider} from '../i18n';
 import {InputGroup, InputGroupText} from '../InputGroup';
 import {resetDateSegmentProbe} from '../DateInput/nativeDateSegments';
 import type {ISOTimeString} from '../utils';
@@ -48,6 +49,22 @@ afterEach(() => {
 });
 
 describe('TimeInput nativePicker', () => {
+  it("shows the resting value in the locale's hour cycle", () => {
+    stubPointer(true);
+    render(
+      <InternationalizationProvider locale="de-DE">
+        <TimeInput
+          label="Start time"
+          value={'14:30' as ISOTimeString}
+          onChange={() => {}}
+        />
+      </InternationalizationProvider>,
+    );
+    expect(getNativeTimeInput()).toHaveValue('14:30');
+    expect(screen.getByText('14:30')).toBeInTheDocument();
+    expect(screen.queryByText('2:30 PM')).toBeNull();
+  });
+
   it('uses the browser/OS picker on a coarse pointer by default', () => {
     stubPointer(true);
     render(

package/src/TimeInput/Presentation.test.tsx

@@ -10,6 +10,8 @@
 import {afterEach, beforeAll, describe, expect, it, vi} from 'vitest';
 import {fireEvent, render, screen} from '@testing-library/react';
 import {TimeInput} from './TimeInput';
+import {InternationalizationProvider} from '../i18n';
+import type {ISOTimeString} from '../utils';
 import {resetDateSegmentProbe} from '../DateInput/nativeDateSegments';
 
 const HOVER_CAPABLE = /\(\s*hover\s*:\s*hover\s*\)/;
@@ -80,6 +82,25 @@ describe('TimeInput presentation', () => {
     }
   });
 
+  it("bottom-sheet follows the locale's hour cycle in its text and wheels", () => {
+    stubPointer(false);
+    render(
+      <InternationalizationProvider locale="de-DE">
+        <TimeInput
+          label="Start"
+          presentation="bottom-sheet"
+          value={'14:30' as ISOTimeString}
+          onChange={() => {}}
+        />
+      </InternationalizationProvider>,
+    );
+    const input = screen.getByRole('combobox', {name: 'Start'});
+    expect(input).toHaveValue('14:30');
+    fireEvent.click(input);
+    expect(screen.getByRole('listbox', {name: 'Hour'})).toBeInTheDocument();
+    expect(screen.queryByRole('listbox', {name: 'AM/PM'})).toBeNull();
+  });
+
   it('bottom-sheet renders the sheet field even on a fine pointer', () => {
     stubPointer(false);
     render(

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: