@astryxdesign/core 0.7.3-canary.f94e962 → 0.7.3

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',
@@ -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',
@@ -510,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: [
@@ -612,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:

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';
@@ -141,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={() => {}} />);
-    expect(screen.getByRole('textbox')).toBeDisabled();
+    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={() => {}} />);
+    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', () => {
@@ -645,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
    * ```
@@ -479,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',
@@ -577,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;
       }
@@ -613,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
@@ -633,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
@@ -646,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;
       }
@@ -744,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],
@@ -778,7 +802,7 @@ function TimeField({
           max={max}
           hourFormat={hourFormat}
           isEffectivelyDisabled={isDisabled}
-          hasDisabledMessage={showsDisabledMessage}
+          isFocusableDisabled
           isEffectivelyRequired={isEffectivelyRequired}
           isBusy={isBusy}
           statusType={status?.type}
@@ -787,7 +811,8 @@ function TimeField({
             ...controlProps,
             onFocus: onFocusProp,
             onBlur: onBlurProp,
-            onKeyDown: onKeyDownProp,
+            onKeyDown: chainEventHandlers(preventDisabledEnter, onKeyDownProp),
+            onClick: isDisabled ? undefined : controlProps.onClick,
           }}
         />
       ) : (
@@ -804,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'",
     },
     {

package/src/Timestamp/Timestamp.test.tsx

@@ -11,6 +11,9 @@ import {
 } from 'vitest';
 import {render, screen, act, waitFor, fireEvent} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
+import {Profiler} from 'react';
+import {hydrateRoot, type Root} from 'react-dom/client';
+import {renderToString} from 'react-dom/server';
 import {Timestamp} from './Timestamp';
 import {formatInstant} from './formatInstant';
 import {formatTooltipLines} from './tooltipEntries';
@@ -1466,3 +1469,168 @@ describe('Timestamp pass-through props', () => {
     });
   });
 });
+
+/**
+ * Counts `new Date()` calls with no argument (reads of the current time) made
+ * while `run` executes.
+ */
+function countClockReads(run: () => void): number {
+  const ActiveDate = globalThis.Date;
+  let reads = 0;
+  class CountingDate extends ActiveDate {
+    constructor(...args: [] | [string | number | Date]) {
+      if (args.length === 0) {
+        reads += 1;
+      }
+      super(...(args as [string | number | Date]));
+    }
+  }
+  globalThis.Date = CountingDate as DateConstructor;
+  try {
+    run();
+  } finally {
+    globalThis.Date = ActiveDate;
+  }
+  return reads;
+}
+
+describe('Timestamp server rendering', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date('2026-03-25T12:00:00Z'));
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it.each(['date', 'date_time', 'time', 'unix_seconds'] as const)(
+    'never reads the current time for the absolute %s format',
+    format => {
+      const element = (
+        <Timestamp value="2026-03-25T10:00:00Z" format={format} />
+      );
+      expect(countClockReads(() => renderToString(element))).toBe(0);
+      expect(countClockReads(() => render(element))).toBe(0);
+    },
+  );
+
+  it.each(['relative', 'relative_short', 'auto'] as const)(
+    'renders the %s format as the full date and time in UTC on the server without reading the clock',
+    format => {
+      const value = '2026-03-25T10:00:00Z';
+      let html = '';
+      expect(
+        countClockReads(() => {
+          html = renderToString(<Timestamp value={value} format={format} />);
+        }),
+      ).toBe(0);
+      const host = document.createElement('div');
+      host.innerHTML = html;
+      expect(host.textContent).toBe(
+        formatInstant(new Date(value), 'date_time', 'en-US', {
+          timeZone: 'UTC',
+          isTimezoneShown: true,
+        }),
+      );
+    },
+  );
+
+  it('never commits the UTC placeholder when a client Timestamp switches to a relative format', () => {
+    const value = Date.now() / 1000 - 7200;
+    const committed: string[] = [];
+    function Spy({format}: {format: 'date' | 'relative'}) {
+      return (
+        <Profiler
+          id="ts"
+          onRender={() => {
+            committed.push(document.querySelector('time')?.textContent ?? '');
+          }}>
+          <Timestamp value={value} format={format} hasTooltip={false} />
+        </Profiler>
+      );
+    }
+    const {rerender} = render(<Spy format="date" />);
+    committed.length = 0;
+    rerender(<Spy format="relative" />);
+    expect(screen.getByText('2 hours ago')).toBeInTheDocument();
+    expect(committed.some(text => text.includes('UTC'))).toBe(false);
+  });
+
+  describe('across time zones', () => {
+    const originalTZ = process.env.TZ;
+
+    afterEach(() => {
+      if (originalTZ === undefined) {
+        delete process.env.TZ;
+      } else {
+        process.env.TZ = originalTZ;
+      }
+    });
+
+    it('writes the same server markup whatever the server time zone', () => {
+      const element = (
+        <Timestamp value="2026-03-25T10:00:00Z" format="relative" />
+      );
+      process.env.TZ = 'UTC';
+      const utc = renderToString(element);
+      process.env.TZ = 'Asia/Tokyo';
+      expect(renderToString(element)).toBe(utc);
+    });
+
+    it('hydrates server markup from another time zone without a mismatch', () => {
+      const value = Date.now() / 1000 - 7200;
+      const element = (
+        <Timestamp value={value} format="relative" hasTooltip={false} />
+      );
+      process.env.TZ = 'UTC';
+      const host = document.createElement('div');
+      document.body.appendChild(host);
+      host.innerHTML = renderToString(element);
+
+      process.env.TZ = 'America/Los_Angeles';
+      const errors = vi.spyOn(console, 'error').mockImplementation(() => {});
+      let root: Root | undefined;
+      try {
+        act(() => {
+          root = hydrateRoot(host, element, {
+            onRecoverableError: error => {
+              throw error;
+            },
+          });
+        });
+        expect(host.textContent).toBe('2 hours ago');
+        expect(errors).not.toHaveBeenCalled();
+      } finally {
+        errors.mockRestore();
+        act(() => root?.unmount());
+        host.remove();
+      }
+    });
+  });
+
+  it('hydrates the server markup without a mismatch, then shows the relative phrase', () => {
+    const value = Date.now() / 1000 - 7200;
+    const element = (
+      <Timestamp value={value} format="relative" hasTooltip={false} />
+    );
+    const host = document.createElement('div');
+    document.body.appendChild(host);
+    host.innerHTML = renderToString(element);
+    expect(host.textContent).not.toBe('2 hours ago');
+
+    const errors = vi.spyOn(console, 'error').mockImplementation(() => {});
+    let root: Root | undefined;
+    try {
+      act(() => {
+        root = hydrateRoot(host, element);
+      });
+      expect(host.textContent).toBe('2 hours ago');
+      expect(errors).not.toHaveBeenCalled();
+    } finally {
+      errors.mockRestore();
+      act(() => root?.unmount());
+      host.remove();
+    }
+  });
+});