@astryxdesign/core 0.7.2 → 0.7.3-canary.04c7468

package/src/TimeInput/NativeTimeInput.test.tsx

@@ -231,14 +231,38 @@ describe('TimeInput nativePicker', () => {
     expect(input).not.toBeDisabled();
     expect(input).toHaveAttribute('aria-disabled', 'true');
     expect(input).toHaveAttribute('readonly');
+    // The shared native time segment's picker button is focusable-disabled
+    // (spec:AST-085 FR1) and still blocks opening.
     expect(
       screen.getByRole('button', {name: 'Open Start time'}),
-    ).toBeDisabled();
+    ).toHaveAttribute('aria-disabled', 'true');
     const tooltip = document.querySelector<HTMLElement>('[role="tooltip"]');
     expect(tooltip).not.toBeNull();
     expect(input.getAttribute('aria-describedby')).toContain(tooltip?.id);
   });
 
+  it('keeps a disabled native field focusable without native disabled (AST-085 FR1, FR2)', () => {
+    stubPointer(true);
+    const onClick = vi.fn();
+    render(
+      <TimeInput
+        label="Start time"
+        nativePicker="always"
+        isDisabled
+        onClick={onClick}
+        onChange={() => {}}
+      />,
+    );
+    const input = getNativeTimeInput();
+    expect(input).not.toHaveAttribute('disabled');
+    expect(input).toHaveAttribute('aria-disabled', 'true');
+    expect(input).toHaveAttribute('readonly');
+    input.focus();
+    expect(input).toHaveFocus();
+    fireEvent.click(input);
+    expect(onClick).not.toHaveBeenCalled();
+  });
+
   it('forwards refs and autofocus to the native input', () => {
     stubPointer(true);
     const ref = vi.fn();

package/src/TimeInput/Presentation.test.tsx

@@ -96,6 +96,29 @@ describe('TimeInput presentation', () => {
     expect(screen.getByRole('listbox', {name: 'Minute'})).toBeInTheDocument();
   });
 
+  it('bottom-sheet: a disabled field stays focusable and inert (AST-085 FR1, FR2)', () => {
+    stubPointer(false);
+    const onClick = vi.fn();
+    render(
+      <TimeInput
+        label="Start"
+        presentation="bottom-sheet"
+        isDisabled
+        onClick={onClick}
+        onChange={() => {}}
+      />,
+    );
+    const input = screen.getByRole('combobox', {name: 'Start'});
+    expect(input).not.toHaveAttribute('disabled');
+    expect(input).toHaveAttribute('aria-disabled', 'true');
+    input.focus();
+    expect(input).toHaveFocus();
+    fireEvent.click(input);
+    expect(input).toHaveAttribute('aria-expanded', 'false');
+    expect(screen.queryByRole('listbox', {name: 'Hour'})).toBeNull();
+    expect(onClick).not.toHaveBeenCalled();
+  });
+
   it('adaptive-bottom-sheet: typed on fine, sheet on coarse', () => {
     stubPointer(false);
     const {unmount} = render(

package/src/TimeInput/TimeInput.doc.mjs

@@ -71,7 +71,7 @@ export const docs = {
       {
         guidance: false,
         description:
-          'Wrap a disabled TimeInput in Tooltip to explain why it is disabled; disabled triggers swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',
+          'Wrap a disabled TimeInput in Tooltip to explain why it is disabled. Use the disabledMessage prop instead, which ties the reason to the field.',
       },
     ],
     anatomy: [
@@ -144,14 +144,15 @@ export const docs = {
     {
       name: 'isDisabled',
       type: 'boolean',
-      description: 'Disables the input and suppresses interactions.',
+      description:
+        'Disables the input and suppresses interactions. The input stays focusable and exposes `aria-disabled`.',
       default: 'false',
     },
     {
       name: 'disabledMessage',
       type: 'string',
       description:
-        'Explains why the input is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the field focusable via aria-disabled (activation stays blocked). Use this instead of wrapping a disabled TimeInput in Tooltip. Disabled controls swallow the hover events an external Tooltip needs.',
+        'Explains why the input is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and describes the input (activation stays blocked). Use this instead of wrapping a disabled TimeInput in Tooltip.',
     },
     {
       name: 'value',
@@ -212,7 +213,7 @@ export const docs = {
       name: 'increment',
       type: 'number',
       description:
-        'Number of minutes to add or subtract when the user presses the up or down arrow key.',
+        'Number of minutes to add or subtract when the user presses the up or down arrow key. Steps are whole minutes; a fractional value leaves the time unchanged.',
       default: '1',
     },
     {
@@ -329,14 +330,14 @@ export const docsZh = {
     {
       name: 'isDisabled',
       type: 'boolean',
-      description: '禁用输入框并抑制交互。',
+      description: '禁用输入框并抑制交互。输入框仍可聚焦并暴露 `aria-disabled`。',
       default: 'false',
     },
     {
       name: 'disabledMessage',
       type: 'string',
       description:
-        '说明输入框为何被禁用。与 isDisabled 一起使用时，在悬停/键盘聚焦时显示提示，并通过 aria-disabled 保持输入框可聚焦（仍阻止输入和调整）。请使用此属性，而不是用 Tooltip 包裹已禁用的 TimeInput。',
+        '说明输入框为何被禁用。与 isDisabled 一起使用时，在悬停/键盘聚焦时显示提示，并描述输入框（仍阻止输入和调整）。请使用此属性，而不是用 Tooltip 包裹已禁用的 TimeInput。',
     },
     {
       name: 'value',
@@ -392,7 +393,8 @@ export const docsZh = {
     {
       name: 'increment',
       type: 'number',
-      description: '用户按上或下方向键时增加或减少的分钟数。',
+      description:
+        '用户按上或下方向键时增加或减少的分钟数。步长为整分钟；传入小数时时间保持不变。',
       default: '1',
     },
     {
@@ -509,7 +511,7 @@ export const docsZh = {
       {
         guidance: false,
         description:
-          'Wrap a disabled TimeInput in Tooltip to explain why it is disabled; disabled triggers swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',
+          'Wrap a disabled TimeInput in Tooltip to explain why it is disabled. Use the disabledMessage prop instead, which ties the reason to the field.',
       },
     ],
     anatomy: [
@@ -611,7 +613,7 @@ export const docsDense = {
       'Marks required+sets aria-required. Mutually exclusive w/ isOptional.',
     isDisabled: 'Disables input, suppresses interactions.',
     disabledMessage:
-      'Reason shown in a tooltip on hover/focus when disabled; keeps input focusable via aria-disabled.',
+      'Reason shown in a tooltip on hover/focus when disabled; describes the input.',
     value: 'Controlled time in ISO format (HH:MM or HH:MM:SS).',
     onChange: 'Fired on time change. Receives undefined when cleared.',
     changeAction:
@@ -623,7 +625,8 @@ export const docsDense = {
     hasClear: 'Shows clear button when value set+not disabled.',
     hourFormat:
       "Display format. '12h' shows AM/PM; '24h' uses 24-hour notation.",
-    increment: 'Minutes to add/subtract on arrow up/down.',
+    increment:
+      'Minutes to add/subtract on arrow up/down. Whole minutes only; a fractional value leaves the time unchanged.',
     presentation:
       "picker surface: 'adaptive-native' (default) = typed field fine / browser/OS coarse (hasSeconds or increment!=1 retains typed); 'native' = browser/OS always, no fallback; 'adaptive-bottom-sheet' = typed fine / Astryx wheel sheet coarse; 'bottom-sheet' = sheet always; 'text-input'/'popover' = typed field only.",
     nativePicker:

package/src/TimeInput/TimeInput.test.tsx

@@ -10,8 +10,10 @@
  */
 
 import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
-import {render, screen, fireEvent, waitFor} from '@testing-library/react';
+import {act, render, screen, fireEvent, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
+import * as stylex from '@stylexjs/stylex';
+import {colorVars} from '../theme/tokens.stylex';
 import {TimeInput} from './TimeInput';
 import {InputGroup, InputGroupText} from '../InputGroup';
 import {InternationalizationProvider} from '../i18n';
@@ -65,6 +67,26 @@ describe('TimeInput', () => {
     expect(onChange).toHaveBeenCalledWith('14:31');
   });
 
+  it('does not step into a fractional minute when increment is fractional', () => {
+    const onChange = vi.fn();
+    render(
+      <TimeInput
+        label="Time"
+        value={'14:30' as ISOTimeString}
+        increment={0.5}
+        onChange={onChange}
+      />,
+    );
+    const input = screen.getByLabelText('Time');
+
+    // `increment` is documented as minutes and typed `number`. A fractional one
+    // used to reach formatISOTime unrounded, which pads "30.5" to two
+    // characters and leaves it, so the arrow key handed the consumer a value
+    // that is no longer a time at all.
+    fireEvent.keyDown(input, {key: 'ArrowUp'});
+    expect(onChange).toHaveBeenCalledWith('14:30');
+  });
+
   it('displays formatted time in 12h format', () => {
     render(
       <TimeInput
@@ -121,9 +143,41 @@ describe('TimeInput', () => {
     );
   });
 
-  it('disables input when isDisabled is true', () => {
+  it('keeps a disabled input focusable without native disabled (AST-085 FR1)', () => {
+    render(<TimeInput label="Time" isDisabled onChange={() => {}} />);
+    const input = screen.getByRole('textbox');
+    expect(input).not.toHaveAttribute('disabled');
+    expect(input).toHaveAttribute('aria-disabled', 'true');
+    expect(input).toHaveAttribute('readonly');
+    input.focus();
+    expect(input).toHaveFocus();
+  });
+
+  it('restores the focus ring on a focused disabled field (AST-085 FR6)', () => {
+    // The same declarations as the field's ring style compile to the same
+    // atomic classes; the shared disabled style alone drops them.
+    const ringClasses = stylex
+      .props(
+        stylex.create({
+          ring: {
+            borderColor: {
+              default: colorVars['--color-border-emphasized'],
+              ':focus-within': colorVars['--color-accent'],
+            },
+            boxShadow: {
+              default: 'none',
+              ':focus-within': `inset 0px 0px 0px 2px ${colorVars['--color-accent-muted']}`,
+            },
+          },
+        }).ring,
+      )
+      .className!.split(' ')
+      .filter(name => !name.includes('__'));
     render(<TimeInput label="Time" isDisabled onChange={() => {}} />);
-    expect(screen.getByRole('textbox')).toBeDisabled();
+    const wrapper = screen.getByRole('textbox').closest('.astryx-time-input')!;
+    for (const name of ringClasses) {
+      expect(wrapper).toHaveClass(name);
+    }
   });
 
   it('shows clear button when hasClear is true and value exists', () => {
@@ -625,11 +679,89 @@ describe('TimeInput', () => {
       expect(onChange).not.toHaveBeenCalled();
     });
 
-    it('remains natively disabled when disabled without a reason', () => {
-      render(<TimeInput label="Time" isDisabled />);
+    it('blocks typing, arrows and a caller onClick when disabled without a reason (AST-085 FR2)', async () => {
+      const user = userEvent.setup();
+      const onChange = vi.fn();
+      const onClick = vi.fn();
+      render(
+        <TimeInput
+          label="Time"
+          value={'09:00' as ISOTimeString}
+          onChange={onChange}
+          onClick={onClick}
+          isDisabled
+        />,
+      );
+      const input = screen.getByLabelText('Time');
+      await user.click(input);
+      await user.type(input, '1');
+      await user.keyboard('{ArrowUp}');
+      await user.tab();
+      expect(onChange).not.toHaveBeenCalled();
+      expect(onClick).not.toHaveBeenCalled();
+    });
+
+    it.each([
+      ['text-input', false, {isDisabled: true}],
+      ['native', true, {isDisabled: true}],
+      ['bottom-sheet', true, {isDisabled: true}],
+      ['bottom-sheet', true, {isLoading: true}],
+    ] as const)(
+      'does not submit a surrounding form on Enter: %s (coarse %s) %o (AST-085 FR2)',
+      async (presentation, isCoarse, state) => {
+        vi.stubGlobal('matchMedia', (query: string) => ({
+          matches: /pointer:\s*coarse/.test(query)
+            ? isCoarse
+            : /pointer:\s*fine/.test(query) && !isCoarse,
+          media: query,
+          addEventListener: () => {},
+          removeEventListener: () => {},
+          addListener: () => {},
+          removeListener: () => {},
+        }));
+        const user = userEvent.setup();
+        const onSubmit = vi.fn((e: React.FormEvent) => e.preventDefault());
+        render(
+          <form onSubmit={onSubmit}>
+            <TimeInput
+              label="Time"
+              presentation={presentation}
+              value={'09:00' as ISOTimeString}
+              onChange={() => {}}
+              {...state}
+            />
+            <button type="submit">Save</button>
+          </form>,
+        );
+        try {
+          const input = document.querySelector<HTMLInputElement>(
+            '.astryx-time-input input:not([type=hidden])',
+          )!;
+          act(() => input.focus());
+          await user.keyboard('{Enter}');
+          expect(onSubmit).not.toHaveBeenCalled();
+        } finally {
+          vi.unstubAllGlobals();
+        }
+      },
+    );
+
+    it('drops a draft instead of committing it when the field becomes disabled (AST-085 FR2)', async () => {
+      const user = userEvent.setup();
+      const onChange = vi.fn();
+      const value = '09:00' as ISOTimeString;
+      const {rerender} = render(
+        <TimeInput label="Time" value={value} onChange={onChange} />,
+      );
       const input = screen.getByLabelText('Time');
-      expect(input).toBeDisabled();
-      expect(input).not.toHaveAttribute('aria-disabled');
+      await user.click(input);
+      await user.clear(input);
+      onChange.mockClear();
+      rerender(
+        <TimeInput label="Time" value={value} onChange={onChange} isDisabled />,
+      );
+      await user.tab();
+      expect(onChange).not.toHaveBeenCalled();
     });
 
     it('does not swap in the format-hint placeholder on focus while disabled', () => {

package/src/TimeInput/TimeInput.tsx

@@ -93,6 +93,18 @@ import {useDevWarning} from '../hooks/useDevWarning';
 const TOUCH_POINTER_QUERY = '(pointer: coarse)';
 
 const styles = stylex.create({
+  // The shared disabled style drops the focus ring; restore it while a
+  // control inside the field holds focus (spec:AST-085 FR6). Defaults repeat it.
+  disabledFocusRing: {
+    borderColor: {
+      default: colorVars['--color-border-emphasized'],
+      ':focus-within': colorVars['--color-accent'],
+    },
+    boxShadow: {
+      default: 'none',
+      ':focus-within': `inset 0px 0px 0px 2px ${colorVars['--color-accent-muted']}`,
+    },
+  },
   icon: {
     display: 'flex',
     alignItems: 'center',
@@ -207,12 +219,12 @@ export interface TimeInputProps extends Omit<
   /**
    * Explains why the input is disabled. When set together with
    * `isDisabled`, the input shows a tooltip with this text on hover and
-   * keyboard focus, and the field stays focusable (via `aria-disabled`)
-   * so the reason is discoverable by keyboard and assistive technology.
-   * Typing and arrow-key adjustment stay blocked.
+   * keyboard focus, and the input is described by it, so the reason is
+   * discoverable by keyboard and assistive technology. Typing and arrow-key
+   * adjustment stay blocked.
    *
-   * Use this instead of wrapping a disabled input in `Tooltip` — disabled
-   * controls don't emit the pointer events an external tooltip needs.
+   * Use this instead of wrapping a disabled input in `Tooltip`, so the
+   * reason is tied to the field.
    *
    * @example
    * ```
@@ -286,7 +298,8 @@ export interface TimeInputProps extends Omit<
   hourFormat?: TimeInputHourFormat;
 
   /**
-   * Increment in minutes when using arrow keys.
+   * Increment in minutes when using arrow keys. Steps are whole minutes: a
+   * fractional value leaves the time unchanged.
    * @default 1
    */
   increment?: number;
@@ -478,10 +491,10 @@ function TimeField({
     }
   }, [announce, inputGroup, status?.message, status?.type]);
 
-  // Disabled-reason tooltip. Disabled controls swallow pointer events, so the
-  // tooltip listeners attach to the input container (which already exists) and
-  // the input stays perceivable via aria-disabled instead of the disabled
-  // attribute. Typing is blocked with readOnly and value mutation guards.
+  // A disabled field never renders native `disabled` (spec:AST-085 FR1): the
+  // input stays focusable via aria-disabled, and readOnly plus the value
+  // mutation guards block typing. The disabled-reason tooltip's listeners
+  // attach to the input container.
   const showsDisabledMessage = isDisabled && !!disabledMessage;
   const disabledMessageTooltip = useTooltip({
     placement: 'above',
@@ -576,8 +589,8 @@ function TimeField({
   // Handle input text change - update immediately if valid
   const handleInputChange = useCallback(
     (e: React.ChangeEvent<HTMLInputElement>) => {
-      // With a disabledMessage the input drops `disabled` for focusability, so
-      // guard value mutation explicitly (readOnly also blocks typing).
+      // The input is never natively disabled (spec:AST-085 FR1), so guard
+      // value mutation explicitly (readOnly also blocks typing).
       if (isDisabled) {
         return;
       }
@@ -612,6 +625,11 @@ function TimeField({
       if (pendingInput === null) {
         return;
       }
+      // Disabled: keep the value, drop the draft (spec:AST-085 FR2).
+      if (isDisabled) {
+        setPendingInput(null);
+        return;
+      }
 
       if (!pendingInput.trim()) {
         // Empty input clears the value
@@ -632,10 +650,17 @@ function TimeField({
       // Clear pending input - display will revert to formatted value
       setPendingInput(null);
     },
-    [pendingInput, value, fireChange, hasSeconds, min, max],
+    [pendingInput, isDisabled, value, fireChange, hasSeconds, min, max],
   );
 
   // Handle keyboard navigation on input
+  // Enter in a focused disabled field would submit a surrounding form (FR2).
+  const preventDisabledEnter = (e: KeyboardEvent<HTMLInputElement>) => {
+    if (isDisabled && e.key === 'Enter') {
+      e.preventDefault();
+    }
+  };
+
   const handleInputKeyDown = useCallback(
     (e: KeyboardEvent<HTMLInputElement>) => {
       // ArrowUp/ArrowDown step the time and preventDefault; an IME candidate
@@ -645,8 +670,7 @@ function TimeField({
       if (isImeKeyEvent(e.nativeEvent)) {
         return;
       }
-      // Arrow-key adjustment mutates the value; block it while showing a
-      // disabled reason (the input keeps focusability via aria-disabled).
+      // Arrow-key adjustment mutates the value; block it while disabled.
       if (isDisabled) {
         return;
       }
@@ -743,6 +767,7 @@ function TimeField({
           inputWrapperStyles.base,
           sizeStyles[size],
           isDisabled && inputWrapperStyles.disabled,
+          isDisabled && styles.disabledFocusRing,
           status && inputStatusBorderStyles[status.type],
           status && !isDisabled && inputStatusHoverShadowStyles[status.type],
           status && inputStatusFocusWithinStyles[status.type],
@@ -777,7 +802,7 @@ function TimeField({
           max={max}
           hourFormat={hourFormat}
           isEffectivelyDisabled={isDisabled}
-          hasDisabledMessage={showsDisabledMessage}
+          isFocusableDisabled
           isEffectivelyRequired={isEffectivelyRequired}
           isBusy={isBusy}
           statusType={status?.type}
@@ -786,7 +811,8 @@ function TimeField({
             ...controlProps,
             onFocus: onFocusProp,
             onBlur: onBlurProp,
-            onKeyDown: onKeyDownProp,
+            onKeyDown: chainEventHandlers(preventDisabledEnter, onKeyDownProp),
+            onClick: isDisabled ? undefined : controlProps.onClick,
           }}
         />
       ) : (
@@ -803,14 +829,17 @@ function TimeField({
             onChange={handleInputChange}
             onFocus={chainEventHandlers(handleFocus, onFocusProp)}
             onBlur={chainEventHandlers(handleBlur, onBlurProp)}
-            onKeyDown={chainEventHandlers(handleInputKeyDown, onKeyDownProp)}
+            onKeyDown={chainEventHandlers(
+              preventDisabledEnter,
+              handleInputKeyDown,
+              onKeyDownProp,
+            )}
             placeholder={displayPlaceholder}
-            // With a disabledMessage the input keeps focusability via
-            // aria-disabled so the reason is focus-discoverable; typing and
-            // arrow-key adjustment are blocked with readOnly and the guards.
-            disabled={isDisabled && !showsDisabledMessage}
-            aria-disabled={showsDisabledMessage ? 'true' : undefined}
-            readOnly={showsDisabledMessage || undefined}
+            aria-disabled={isDisabled ? 'true' : undefined}
+            readOnly={isDisabled || undefined}
+            // The browser still dispatches a click on an aria-disabled input,
+            // so a caller's onClick is skipped too (spec:AST-085 FR2).
+            onClick={isDisabled ? undefined : controlProps.onClick}
             autoFocus={hasAutoFocus}
             data-autofocus={hasAutoFocus || undefined}
             aria-describedby={ariaDescribedBy}

package/src/TimeInput/TouchTimeField.tsx

@@ -24,6 +24,7 @@ import {
   useRef,
   useState,
   useTransition,
+  type KeyboardEvent,
 } from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {BottomSheet} from '../BottomSheet';
@@ -45,7 +46,7 @@ import {useMergedRefs} from '../hooks/useMergedRefs';
 import {useResolvedRequired} from '../hooks/useResolvedRequired';
 import {Icon} from '../Icon';
 import {useTranslator} from '../i18n';
-import {sizeVars, spacingVars} from '../theme/tokens.stylex';
+import {colorVars, sizeVars, spacingVars} from '../theme/tokens.stylex';
 import {useSize} from '../SizeContext/SizeContext';
 import {Spinner} from '../Spinner';
 import {useTooltip} from '../Tooltip';
@@ -74,6 +75,17 @@ const sizeStyles = stylex.create({
 });
 
 const styles = stylex.create({
+  // Same as TimeInput's: the focus ring for a focused disabled field.
+  disabledFocusRing: {
+    borderColor: {
+      default: colorVars['--color-border-emphasized'],
+      ':focus-within': colorVars['--color-accent'],
+    },
+    boxShadow: {
+      default: 'none',
+      ':focus-within': `inset 0px 0px 0px 2px ${colorVars['--color-accent-muted']}`,
+    },
+  },
   iconButton: {
     display: 'flex',
     alignItems: 'center',
@@ -447,6 +459,7 @@ export function TouchTimeField({
           inputWrapperStyles.base,
           sizeStyles[size],
           isDisabled && inputWrapperStyles.disabled,
+          isDisabled && styles.disabledFocusRing,
           status && inputStatusBorderStyles[status.type],
           status && !isDisabled && inputStatusHoverShadowStyles[status.type],
           status && inputStatusFocusWithinStyles[status.type],
@@ -459,7 +472,7 @@ export function TouchTimeField({
       <button
         type="button"
         onClick={openSheet}
-        disabled={isEffectivelyDisabled}
+        aria-disabled={isEffectivelyDisabled || undefined}
         aria-label={t('@astryx.timeInput.openPicker', {label})}
         tabIndex={-1}
         {...stylex.props(focusOutlineStyles.focusVisible, styles.iconButton)}>
@@ -475,10 +488,19 @@ export function TouchTimeField({
         readOnly
         inputMode="none"
         onChange={() => {}}
-        onClick={chainEventHandlers(openSheet, onClickProp)}
+        onClick={
+          isEffectivelyDisabled
+            ? undefined
+            : chainEventHandlers(openSheet, onClickProp)
+        }
+        // Enter would submit a surrounding form while disabled (FR2).
+        onKeyDown={chainEventHandlers((e: KeyboardEvent<HTMLInputElement>) => {
+          if (isEffectivelyDisabled && e.key === 'Enter') {
+            e.preventDefault();
+          }
+        }, controlProps.onKeyDown)}
         placeholder={placeholder}
-        disabled={isEffectivelyDisabled && !showsDisabledMessage}
-        aria-disabled={showsDisabledMessage ? 'true' : undefined}
+        aria-disabled={isEffectivelyDisabled ? 'true' : undefined}
         aria-describedby={ariaDescribedBy}
         aria-required={isEffectivelyRequired ? 'true' : undefined}
         aria-invalid={status?.type === 'error' ? 'true' : undefined}

package/src/Timestamp/Timestamp.doc.mjs

@@ -28,7 +28,7 @@ export const docs = {
       name: 'format',
       type: "'relative' | 'relative_short' | 'auto' | 'date' | 'date_long' | 'date_weekday' | 'date_time' | 'time' | 'system_date' | 'system_date_time' | 'system_time' | 'unix_seconds'",
       description:
-        "Display format. 'relative' uses the locale's native long relative-time wording ('2 hours ago' in English), 'relative_short' uses its narrow pattern ('2h ago' in English) for compact surfaces, 'date' shows 'Mar 21, 2025', 'date_long' shows 'March 21, 2025', 'date_weekday' shows 'Wed, Mar 21, 2025', 'date_time' shows 'Mar 21, 2025, 2:51 PM', 'time' shows '2:51 PM', 'system_*' variants use ISO-style formatting, 'unix_seconds' shows the Unix time in whole seconds since the epoch (an absolute, zone-independent value), 'auto' switches from relative to date_time based on recency.",
+        "Display format. 'relative' uses the locale's native long relative-time wording ('2 hours ago' in English), 'relative_short' uses its narrow pattern ('2h ago' in English) for compact surfaces, 'date' shows 'Mar 21, 2025', 'date_long' shows 'March 21, 2025', 'date_weekday' shows 'Wed, Mar 21, 2025', 'date_time' shows 'Mar 21, 2025, 2:51 PM', 'time' shows '2:51 PM', 'system_*' variants use ISO-style formatting, 'unix_seconds' shows the Unix time in whole seconds since the epoch (an absolute, zone-independent value), 'auto' switches from relative to date_time based on recency. Absolute formats never read the current time. 'relative', 'relative_short' and 'auto' read it on the client only: a server render or static prerender shows the full date and time in UTC, labelled, and the client switches to the format's normal output after hydration.",
       default: "'auto'",
     },
     {