@astryxdesign/core 0.7.8 → 0.7.9-canary.0200dfe

package/src/Spinner/Spinner.tsx

@@ -18,7 +18,7 @@
 
 import {useId, type ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
-import {colorVars, durationVars, spacingVars} from '../theme/tokens.stylex';
+import {colorVars, spacingVars} from '../theme/tokens.stylex';
 import type {BaseProps} from '../BaseProps';
 import {Text} from '../Text/Text';
 import {mergeProps} from '../utils/mergeProps';
@@ -28,6 +28,7 @@ import {
   useComponentTranslator,
 } from '../i18n/useComponentTranslator';
 import english from '../i18n/generated-english/Spinner/Spinner.generated';
+import {spinnerRotorStyles, syncRotationPhase} from './spinnerRotor';
 
 registerEnglishFallback(english);
 
@@ -36,13 +37,13 @@ registerEnglishFallback(english);
 // =============================================================================
 
 /**
- * Default fraction of the ring the moving arc covers. The canvas ring this
- * replaces swept 135deg, not the 270deg its constant's comment claimed.
+ * The fraction of the ring the arc covers: SPINNER_ARC_FRACTION. StyleX reads
+ * only a literal in this file, and a test pins the two together.
  *
  * Themeable via `--spinner-arc-fraction`, declared alongside the other public
  * vars in `sizeStyles` below. Only the inline `strokeDasharray` attribute
- * (the pre-stylesheet render — see its own comment) still reads this
- * constant directly; the CSS side composes the dash from the live var.
+ * (the pre-stylesheet render) still reads the constant directly; the CSS side
+ * composes the dash from the live var.
  */
 const ARC_FRACTION = 0.375;
 
@@ -152,75 +153,6 @@ function registerSpinnerVars(): void {
 // elide.
 registerSpinnerVars();
 
-/**
- * Pin every ring's rotation to the document timeline's origin instead of its
- * own start time, so spinners mounted seconds apart stay in phase.
- *
- * Setting `startTime` is exact where arithmetic on a clock read is not. A
- * negative `animation-delay` computed at mount is only as good as the gap
- * between the clock read and the frame the animation starts in. At 10x CPU
- * throttling that gap measured 116 degrees of drift.
- *
- * Rotors are collected and pinned in one frame. `getAnimations()` resolves
- * style, and `startTime` dirties it again. So pinning them one at a time makes
- * each mount re-force what the previous one invalidated: 53 style recalcs for
- * 38 spinners, against 19 batched.
- */
-const pendingRotors = new Set<HTMLSpanElement>();
-let flushScheduled = false;
-
-function pinRotorsToTimelineOrigin(): void {
-  flushScheduled = false;
-  const animations: Animation[] = [];
-  for (const rotor of pendingRotors) {
-    animations.push(...rotor.getAnimations());
-  }
-  pendingRotors.clear();
-  for (const animation of animations) {
-    animation.startTime = 0;
-  }
-}
-
-/**
- * Ref callback for the rotor: the one place a mounted ring touches the DOM.
- *
- * It reads nothing back — the geometry is resolved by the cascade, not in JS.
- */
-function syncRotationPhase(
-  rotor: HTMLSpanElement | null,
-): (() => void) | undefined {
-  if (rotor == null) {
-    return undefined;
-  }
-  // jsdom implements no Web Animations, and this runs in every consumer's
-  // component tests.
-  if (typeof rotor.getAnimations !== 'function') {
-    return undefined;
-  }
-  pendingRotors.add(rotor);
-  if (!flushScheduled) {
-    flushScheduled = true;
-    requestAnimationFrame(pinRotorsToTimelineOrigin);
-  }
-  return () => {
-    pendingRotors.delete(rotor);
-  };
-}
-
-// =============================================================================
-// Animation
-// =============================================================================
-
-/**
- * A `transform` animation runs on the compositor, so the ring keeps turning
- * while a script runs. A `stroke-dashoffset` animation would repaint the arc
- * on the main thread every frame, so it would stop while a script runs.
- */
-const rotation = stylex.keyframes({
-  '0%': {transform: 'rotate(0deg)'},
-  '100%': {transform: 'rotate(360deg)'},
-});
-
 // =============================================================================
 // Styles
 // =============================================================================
@@ -299,20 +231,6 @@ const styles = stylex.create({
     gridArea: '1 / 1',
     width: `var(${BOX_SIZE})`,
     height: `var(${BOX_SIZE})`,
-    // Mobile Safari keeps a re-timed animation off the main thread only on an
-    // element with its own layer. So the rotor declares one before the start
-    // time is set (see `pinRotorsToTimelineOrigin`).
-    willChange: 'transform',
-    // Reduced motion slows the turn but never stops it: a still ring reads as
-    // broken. The status role and its name still say that work is busy.
-    animationDuration: {
-      // The loop reads the duration before a theme's tempo scales it.
-      default: `var(--_astryx-pre-tempo-duration-slow-min, ${durationVars['--duration-slow-min']})`,
-      '@media (prefers-reduced-motion: reduce)': '3s',
-    },
-    animationIterationCount: 'infinite',
-    animationName: rotation,
-    animationTimingFunction: 'linear',
   },
   circle: {
     fill: 'none',
@@ -594,7 +512,7 @@ export function Spinner({
       <span
         ref={syncRotationPhase}
         aria-hidden="true"
-        {...stylex.props(styles.rotor)}>
+        {...stylex.props(styles.rotor, spinnerRotorStyles.turn)}>
         <svg
           width={frameSize}
           height={frameSize}

package/src/Spinner/index.ts

@@ -12,8 +12,4 @@
  */
 
 export {Spinner} from './Spinner';
-export type {
-  SpinnerProps,
-  SpinnerSize,
-  SpinnerShade,
-} from './Spinner';
+export type {SpinnerProps, SpinnerSize, SpinnerShade} from './Spinner';

package/src/Spinner/spinnerRotor.ts

@@ -0,0 +1,113 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file spinnerRotor.ts
+ * @input StyleX keyframes and the slow-min duration token
+ * @output The one turning arc: SPINNER_ARC_FRACTION, spinnerRotorStyles.turn
+ *   and syncRotationPhase
+ * @position Spinner's rotor, shared by Spinner and Lab's indeterminate
+ *   CircularProgress (through `@astryxdesign/core/internal/spinner-rotor`), so
+ *   both rings turn the same way on the compositor.
+ */
+
+import * as stylex from '@stylexjs/stylex';
+import {durationVars} from '../theme/tokens.stylex';
+
+/** The fraction of the ring the arc covers: 135°. */
+export const SPINNER_ARC_FRACTION = 0.375;
+
+/**
+ * Full turns in one iteration of the rotation.
+ *
+ * Chromium wakes the main thread at each iteration boundary while the
+ * document listens for `animationiteration`. React listens for it on every
+ * root. One iteration holds 100 turns, so the wake comes once in 100 turns.
+ * Each turn is 360 degrees, so the ring looks the same.
+ */
+const TURNS_PER_ITERATION = 100;
+
+/**
+ * A `transform` animation runs on the compositor, so the ring keeps turning
+ * while a script runs. A `stroke-dashoffset` animation would repaint the arc
+ * on the main thread every frame, so it would stop while a script runs.
+ */
+const rotation = stylex.keyframes({
+  '0%': {transform: 'rotate(0deg)'},
+  '100%': {transform: `rotate(${360 * TURNS_PER_ITERATION}deg)`},
+});
+
+export const spinnerRotorStyles = stylex.create({
+  turn: {
+    // Mobile Safari keeps a re-timed animation off the main thread only on an
+    // element with its own layer. So the rotor declares one before the start
+    // time is set (see `pinRotorsToTimelineOrigin`).
+    willChange: 'transform',
+    // Reduced motion slows the turn but never stops it: a still ring reads as
+    // broken. The ring's role and name still say that work is busy.
+    animationDuration: {
+      // The loop reads the duration before a theme's tempo scales it.
+      default: `calc(var(--_astryx-pre-tempo-duration-slow-min, ${durationVars['--duration-slow-min']}) * ${TURNS_PER_ITERATION})`,
+      '@media (prefers-reduced-motion: reduce)': `calc(3s * ${TURNS_PER_ITERATION})`,
+    },
+    animationIterationCount: 'infinite',
+    animationName: rotation,
+    animationTimingFunction: 'linear',
+  },
+});
+
+/**
+ * Pin every ring's rotation to the document timeline's origin instead of its
+ * own start time, so spinners mounted seconds apart stay in phase.
+ *
+ * Setting `startTime` is exact where arithmetic on a clock read is not. A
+ * negative `animation-delay` computed at mount is only as good as the gap
+ * between the clock read and the frame the animation starts in. At 10x CPU
+ * throttling that gap measured 116 degrees of drift.
+ *
+ * Rotors are collected and pinned in one frame. `getAnimations()` resolves
+ * style, and `startTime` dirties it again. So pinning them one at a time makes
+ * each mount re-force what the previous one invalidated: 53 style recalcs for
+ * 38 spinners, against 19 batched.
+ */
+const pendingRotors = new Set<Element>();
+let flushScheduled = false;
+
+function pinRotorsToTimelineOrigin(): void {
+  flushScheduled = false;
+  const animations: Animation[] = [];
+  for (const rotor of pendingRotors) {
+    animations.push(...rotor.getAnimations());
+  }
+  pendingRotors.clear();
+  for (const animation of animations) {
+    animation.startTime = 0;
+  }
+}
+
+/**
+ * Ref callback for a rotor: the one place a mounted ring touches the DOM.
+ *
+ * It reads nothing back — the geometry is resolved by the cascade, not in JS.
+ */
+export function syncRotationPhase(
+  rotor: Element | null,
+): (() => void) | undefined {
+  if (rotor == null) {
+    return undefined;
+  }
+  // jsdom implements no Web Animations, and this runs in every consumer's
+  // component tests.
+  if (typeof rotor.getAnimations !== 'function') {
+    return undefined;
+  }
+  pendingRotors.add(rotor);
+  if (!flushScheduled) {
+    flushScheduled = true;
+    requestAnimationFrame(pinRotorsToTimelineOrigin);
+  }
+  return () => {
+    pendingRotors.delete(rotor);
+  };
+}

package/src/Stack/Stack.doc.mjs

@@ -524,7 +524,7 @@ export const docs = {
           name: 'isScrollable',
           type: 'boolean',
           description:
-            'Enables scrollable overflow (overflow: auto). StackItem already applies the flex min-height/min-width reset, so <StackItem size="fill" isScrollable> is a complete scroll region. Matches isScrollable on LayoutContent and LayoutPanel.',
+            'Enables scrollable overflow (overflow: auto). StackItem already applies the flex min-height/min-width reset, so <StackItem size="fill" isScrollable> is a complete scroll region. Matches isScrollable on LayoutContent and LayoutPanel. While its content overflows, a div or span item is a group named by aria-label, or by a translated "Content"; another element keeps its own role.',
           default: 'false',
         },
         {

package/src/Stack/StackItem.tsx

@@ -2,9 +2,11 @@
 
 /**
  * @file StackItem.tsx
- * @input Uses React, ElementType, stackItem utility
+ * @input Uses React, ElementType, stackItem utility, StackItemScrollRegion
  * @output Exports StackItem polymorphic component and StackItemProps
- * @position Layout/Stack component; uses stackItem.stylex.ts
+ * @position Layout/Stack component; uses stackItem.stylex.ts. A scrollable
+ *   `div` or `span` item renders through StackItemScrollRegion, which names
+ *   it while it scrolls.
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Stack/Stack.doc.mjs
@@ -21,6 +23,7 @@ import {
 } from './stackItem.stylex';
 import {mergeProps} from '../utils/mergeProps';
 import {themeProps} from '../utils/themeProps';
+import {StackItemScrollRegion} from '../hooks/StackItemScrollRegion';
 
 const overflowStyles = stylex.create({
   scrollable: {
@@ -53,7 +56,9 @@ export interface StackItemProps extends BaseProps<HTMLElement> {
    * reset, so `<StackItem size="fill" isScrollable>` is a complete scroll
    * region — it grows to fill the stack and scrolls its own overflow with
    * no extra style plumbing. Matches `isScrollable` on `LayoutContent`
-   * and `LayoutPanel`.
+   * and `LayoutPanel`. While its content overflows, a `div` or `span` item
+   * is a group named by the caller's `aria-label`, or by a translated
+   * "Content". Another element keeps its own role.
    * @default false
    */
   isScrollable?: boolean;
@@ -102,18 +107,27 @@ export function StackItem({
     xstyle,
   );
 
+  const elementProps = {
+    ...mergeProps(
+      themeProps('stack-item', {size}),
+      stylexProps,
+      className,
+      style,
+    ),
+    ...props,
+  };
+
+  if (isScrollable && (element === 'div' || element === 'span')) {
+    return createElement(
+      StackItemScrollRegion,
+      {as: element, ref, elementProps},
+      children,
+    );
+  }
+
   return createElement(
     element,
-    {
-      ref: ref as Ref<Element>,
-      ...mergeProps(
-        themeProps('stack-item', {size}),
-        stylexProps,
-        className,
-        style,
-      ),
-      ...props,
-    },
+    {ref: ref as Ref<Element>, ...elementProps},
     children,
   );
 }

package/src/Switch/Switch.tsx

@@ -62,9 +62,9 @@ import {
 import english from '../i18n/generated-english/Switch/Switch.generated';
 
 registerEnglishFallback(english);
+import {reducedMotionFadeConsts} from '../motion/reducedMotion.stylex';
 import {
   interactionOverlayStyles,
-  pressConsts,
   pressVars,
 } from '../utils/interactionOverlay.stylex';
 import {pressHoldsDragProps} from '../privateAttributes/pressHoldsDrag.stylex';
@@ -93,14 +93,15 @@ const PRESS_FADING = '[data-astryx-press="fading"]';
 
 /**
  * The shared press release, for the press layers the switch fades on the
- * compositor. The clock scales by the theme's tempo, and the curve is the
- * controller's own. Switch.test.tsx compares the two.
+ * compositor: the theme's exit motion tokens, no longer than the Reduce
+ * Motion fade under Reduce Motion. Switch.test.tsx compares them with
+ * the overlay's.
  * SYNC: utils/interactionOverlay.stylex.ts PRESS_RELEASE_DURATION,
  * PRESS_RELEASE_DURATION_REDUCED and RELEASE_EASE.
  */
-const PRESS_RELEASE_DURATION = `calc(${pressConsts.releaseMs}ms * min(var(--_astryx-motion-tempo, 1), 1.5))`;
-const PRESS_RELEASE_DURATION_REDUCED = `min(${pressConsts.releaseMs}ms, calc(${pressConsts.releaseMs}ms * var(--_astryx-motion-tempo, 1)))`;
-const PRESS_RELEASE_EASE = 'cubic-bezier(0, 0, 0.2, 1)';
+const PRESS_RELEASE_DURATION = durationVars['--duration-exit'];
+const PRESS_RELEASE_DURATION_REDUCED = `min(${durationVars['--duration-exit']}, ${reducedMotionFadeConsts.duration})`;
+const PRESS_RELEASE_EASE = easeVars['--ease-exit'];
 
 // The measured hit insets (utils/hitArea), 0 until measured.
 const HIT_TOP = 'var(--astryx-hit-inset-top, 0px)';

package/src/Switch/useSwitchTouch.ts

@@ -23,7 +23,7 @@ import type {GestureTouch} from '../gestures/types';
 import {isRtlElement} from '../hooks/isRtlElement';
 import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
 import {
-  createMotionAnimator,
+  createMotionEngine,
   type Animator,
   type MotionCurve,
 } from '../motion/animator';
@@ -282,15 +282,15 @@ export class SwitchTouchController {
       return;
     }
     registerSwitchTable();
-    this.thumb = createMotionAnimator(elements.thumb);
+    this.thumb = createMotionEngine(elements.thumb);
     // The layer rests clear (its class's opacity 0) while the visuals show
     // the value; from here its opacity is the animator's.
-    this.fade = createMotionAnimator(elements.track, {
+    this.fade = createMotionEngine(elements.track, {
       pseudoElement: '::after',
       initial: {opacity: 0},
     });
     this.fade.set({opacity: 0});
-    this.shadow = createMotionAnimator(elements.thumb, {
+    this.shadow = createMotionEngine(elements.thumb, {
       pseudoElement: '::after',
       initial: {opacity: 0},
     });

package/src/TabList/Tab.tsx

@@ -39,6 +39,7 @@ import {useLinkComponent} from '../Link/useLinkComponent';
 import type {LinkComponentType} from '../Link/types';
 import {mergeProps} from '../utils';
 import {useDevWarning} from '../hooks/useDevWarning';
+import {withholdCallerHandlers} from '../utils/disabledInteraction';
 import {EDGE_COMP_ATTR} from '../Layout/edgeCompensation.stylex';
 import {themeProps} from '../utils/themeProps';
 import {focusOutlineProps} from '../utils/focusOutline.stylex';
@@ -362,7 +363,10 @@ export function Tab({
   ) : null;
 
   const sharedProps = {
-    ...restProps,
+    // A disabled tab keeps its tab stop, so the browser still sends it events.
+    // It runs no caller handler other than `onFocus` and `onBlur`, as a natively
+    // disabled control runs none. `onClick` is guarded in `handleSelect`.
+    ...withholdCallerHandlers(restProps, isDisabled),
     ...pressable,
     ...(isLabelHidden ? {'aria-label': label} : {}),
     [EDGE_COMP_ATTR]: '',

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

@@ -168,7 +168,7 @@ const sortStyles = stylex.create({
     fontSize: 10,
     // eslint-disable-next-line @astryx/no-hardcoded-styles -- no token for lineHeight:1 (tight badge)
     lineHeight: '1',
-    color: colorVars['--color-accent'],
+    color: colorVars['--color-text-accent'],
   },
 });
 

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. 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.",
+        "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. Date-bearing formats ('date', 'date_long', 'date_weekday', 'date_time', and the full date in the hover card and the accessible name) use the InternationalizationProvider calendar, such as calendar=\"persian\"; 'time', the relative formats, 'system_*', and 'unix_seconds' do not change.",
       default: "'auto'",
     },
     {
@@ -124,7 +124,7 @@ export const docs = {
 export const docsZh = {
   propDescriptions: {
     value: '\u8981\u663e\u793a\u7684\u65e5\u671f/\u65f6\u95f4\u3002\u63a5\u53d7 Unix \u65f6\u95f4\u6233\uff08\u79d2\uff09\u6216 ISO 8601 \u5b57\u7b26\u4e32\u3002',
-    format: "\u663e\u793a\u683c\u5f0f\u3002'relative' \u663e\u793a '2\u5c0f\u65f6\u524d'\uff0c'date' \u663e\u793a\u65e5\u671f\uff0c'date_long' \u663e\u793a\u957f\u6708\u4efd\u65e5\u671f\uff0c'date_weekday' \u663e\u793a\u661f\u671f+\u65e5\u671f\uff0c'auto' \u6839\u636e\u65f6\u95f4\u8fdc\u8fd1\u81ea\u52a8\u5207\u6362\u3002",
+    format: "\u663e\u793a\u683c\u5f0f\u3002'relative' \u663e\u793a '2\u5c0f\u65f6\u524d'\uff0c'date' \u663e\u793a\u65e5\u671f\uff0c'date_long' \u663e\u793a\u957f\u6708\u4efd\u65e5\u671f\uff0c'date_weekday' \u663e\u793a\u661f\u671f+\u65e5\u671f\uff0c'auto' \u6839\u636e\u65f6\u95f4\u8fdc\u8fd1\u81ea\u52a8\u5207\u6362\u3002\u5e26\u65e5\u671f\u7684\u683c\u5f0f\uff08'date'\u3001'date_long'\u3001'date_weekday'\u3001'date_time'\uff0c\u4ee5\u53ca\u60ac\u505c\u5361\u7247\u548c\u65e0\u969c\u788d\u540d\u79f0\u4e2d\u7684\u5b8c\u6574\u65e5\u671f\uff09\u4f7f\u7528 InternationalizationProvider \u7684\u5386\u6cd5\uff08\u5982 calendar=\"persian\"\uff09\uff1b'time'\u3001\u76f8\u5bf9\u683c\u5f0f\u3001'system_*' \u548c 'unix_seconds' \u4e0d\u53d8\u3002",
     autoThreshold: "auto \u683c\u5f0f\u4ece\u76f8\u5bf9\u65f6\u95f4\u5207\u6362\u5230 date_time \u7684\u9608\u503c\u79d2\u6570\u3002",
     hasTooltip: '\u60ac\u505c\u65f6\u662f\u5426\u663e\u793a\u5305\u542b\u5b8c\u6574\u65e5\u671f/\u65f6\u95f4\u7684\u53ef\u590d\u5236\u60ac\u505c\u5361\u7247\uff08\u76f8\u5bf9\u65f6\u95f4\u6a21\u5f0f\uff0c\u6216\u914d\u7f6e tooltipEntries \u7684\u4efb\u610f\u683c\u5f0f\uff09\u3002',
     tooltipEntries:
@@ -186,7 +186,7 @@ export const docsDense = {
   },
   propDescriptions: {
     value: 'date/time as unix seconds or ISO string',
-    format: "display mode: 'relative' (locale-native long wording), 'relative_short' (locale-native narrow wording), 'auto', 'date', 'date_long', 'date_weekday', 'date_time', 'time', 'system_date', 'system_date_time', 'system_time', 'unix_seconds'",
+    format: "display mode: 'relative' (locale-native long wording), 'relative_short' (locale-native narrow wording), 'auto', 'date', 'date_long', 'date_weekday', 'date_time', 'time', 'system_date', 'system_date_time', 'system_time', 'unix_seconds'; date-bearing formats use the provider calendar, system_* and time do not",
     autoThreshold: 'seconds threshold for auto relative\u2192date_time switch',
     hasTooltip: 'show copyable full-time hover card on hover (relative mode, or any format with tooltipEntries)',
     tooltipEntries:

package/src/Timestamp/Timestamp.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file Timestamp.tsx
- * @input Uses React, Text, provider locale, and Timestamp formatters
+ * @input Uses React, Text, provider locale and calendar, and Timestamp formatters
  * @output Exports Timestamp component and related types
  * @position Core implementation; renders formatted timestamps
  *
@@ -31,6 +31,7 @@ import type {TextType, TextSize, TextColor, TextWeight} from '../theme/types';
 import {mergeProps} from '../utils';
 import {useDevWarning} from '../hooks/useDevWarning';
 import {useLocale} from '../i18n/useLocale';
+import {useCalendarSystem} from '../i18n/useCalendarSystem';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
 import {formatInstant} from './formatInstant';
@@ -297,6 +298,7 @@ export function Timestamp({
 }: TimestampProps) {
   const t = useComponentTranslator();
   const locale = useLocale();
+  const calendar = useCalendarSystem(undefined, 'Timestamp');
   const timeRef = useRef<HTMLTimeElement>(null);
   const mergedTimeRef = useMergedRefs(ref, timeRef);
   // Only relative and auto formats depend on the current time. Absolute
@@ -358,12 +360,12 @@ export function Timestamp({
               date,
               effectiveFormat,
               locale,
-              // The pre-hydration placeholder is written in UTC, labelled, so
-              // the server and the hydrating client produce the same text in
-              // every time zone.
+              // The placeholder before hydration is Gregorian and in UTC, with
+              // its zone. The server and the client then write the same text,
+              // with or without Temporal.
               isClockPending
                 ? {timeZone: 'UTC', isTimezoneShown: true}
-                : {isTimezoneShown},
+                : {isTimezoneShown, calendar},
             )
           : '';
 
@@ -372,10 +374,13 @@ export function Timestamp({
   // out in full: abbreviations like "PST" or "GMT+2" are unexpanded
   // abbreviations to a screen-reader user (WCAG 3.1.4).
   const fullAbsoluteText = isValidDate
-    ? formatInstant(date, 'full', locale)
+    ? formatInstant(date, 'full', locale, {calendar})
     : '';
   const ariaLabelText = isValidDate
-    ? formatInstant(date, 'full', locale, {timeZoneNameStyle: 'long'})
+    ? formatInstant(date, 'full', locale, {
+        timeZoneNameStyle: 'long',
+        calendar,
+      })
     : '';
 
   // Syncs the relative time with an interval timer while the timestamp is live.
@@ -424,7 +429,7 @@ export function Timestamp({
   const lines: ReadonlyArray<TimestampTooltipLine> =
     entries === undefined
       ? [{value: fullAbsoluteText, isCopyable: true}]
-      : formatTooltipLines(date, entries, locale);
+      : formatTooltipLines(date, entries, locale, calendar);
 
   const timestampProps = mergeProps(
     themeProps('timestamp', {format: effectiveFormat}),

package/src/Timestamp/formatInstant.ts

@@ -2,7 +2,7 @@
 
 /**
  * @file formatInstant.ts
- * @input A Date, one absolute format name, and an optional time zone
+ * @input A Date, one absolute format name, an optional time zone and calendar
  * @output That instant rendered as a string
  * @position Leaf shared by Timestamp's visible text and each of its tooltip
  *   lines; owns every absolute format Timestamp can produce
@@ -30,6 +30,10 @@
  */
 
 import {SHARED_DATE_FORMAT_OPTIONS, getWallClock} from '../utils/plainDate';
+import {
+  formatCalendarInstant,
+  type CalendarSystem,
+} from '../utils/calendarSystem';
 import type {Locale} from '../i18n/types';
 import type {TimestampFormat} from './Timestamp';
 
@@ -80,6 +84,14 @@ export interface FormatInstantOptions {
    * @default 'short'
    */
   timeZoneNameStyle?: 'short' | 'long';
+  /**
+   * The calendar that date-bearing formats write the date in. Timestamp
+   * passes its resolved calendar. `time` has no date, and the `system_*`
+   * shapes and `unix_seconds` stay Gregorian ISO or calendar-neutral in every
+   * calendar.
+   * @default 'gregory'
+   */
+  calendar?: CalendarSystem;
 }
 
 // =============================================================================
@@ -139,6 +151,7 @@ export function formatInstant(
     timeZone,
     isTimezoneShown = false,
     timeZoneNameStyle = 'short',
+    calendar = 'gregory',
   }: FormatInstantOptions = {},
 ): string {
   const zone = timeZone === undefined ? {} : {timeZone};
@@ -146,41 +159,49 @@ export function formatInstant(
 
   switch (format) {
     case 'full':
-      return new Intl.DateTimeFormat(locale, {
-        ...FULL_OPTIONS,
-        timeZoneName: timeZoneNameStyle,
-        ...zone,
-        calendar: 'gregory',
-      }).format(date);
+      return formatCalendarInstant(
+        calendar,
+        date,
+        {...FULL_OPTIONS, timeZoneName: timeZoneNameStyle},
+        locale,
+        timeZone,
+      );
 
     case 'date':
-      return new Intl.DateTimeFormat(locale, {
-        ...SHARED_DATE_FORMAT_OPTIONS.date,
-        ...zone,
-        calendar: 'gregory',
-      }).format(date);
+      return formatCalendarInstant(
+        calendar,
+        date,
+        SHARED_DATE_FORMAT_OPTIONS.date,
+        locale,
+        timeZone,
+      );
 
     case 'date_long':
-      return new Intl.DateTimeFormat(locale, {
-        ...SHARED_DATE_FORMAT_OPTIONS.date_long,
-        ...zone,
-        calendar: 'gregory',
-      }).format(date);
+      return formatCalendarInstant(
+        calendar,
+        date,
+        SHARED_DATE_FORMAT_OPTIONS.date_long,
+        locale,
+        timeZone,
+      );
 
     case 'date_weekday':
-      return new Intl.DateTimeFormat(locale, {
-        ...SHARED_DATE_FORMAT_OPTIONS.date_weekday,
-        ...zone,
-        calendar: 'gregory',
-      }).format(date);
+      return formatCalendarInstant(
+        calendar,
+        date,
+        SHARED_DATE_FORMAT_OPTIONS.date_weekday,
+        locale,
+        timeZone,
+      );
 
     case 'date_time':
-      return new Intl.DateTimeFormat(locale, {
-        ...DATE_TIME_OPTIONS,
-        ...zoneName,
-        ...zone,
-        calendar: 'gregory',
-      }).format(date);
+      return formatCalendarInstant(
+        calendar,
+        date,
+        {...DATE_TIME_OPTIONS, ...zoneName},
+        locale,
+        timeZone,
+      );
 
     case 'time':
       return new Intl.DateTimeFormat(locale, {