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

package/src/hooks/usePressFeedback.doc.mjs

@@ -20,12 +20,12 @@ export const docs = {
       name: 'pressableProps',
       type: "{'data-astryx-pressable': ''}",
       description:
-        "The marker attribute to spread on the element that paints the press. Compose one of `interactionOverlayStyles` (from `@astryxdesign/core/utils`) on the same element — `backgroundColor` or `backgroundImage` for a surface whose hover and press are the system's overlays, `pressedBackgroundColor` for one whose hover is its own — and it paints the pressed token at the press's strength on the first frame of a believed press and fades it over the release, keeping `:active` for a mouse on a desktop. On a phone or tablet, where the stylesheet drops `:active`, the controller also paints a mouse, trackpad or Space-key press: at once, held while the button or key is down, faded at the release. A press is themed through `--color-overlay-pressed`.",
+        "The marker attribute to spread on the element that paints the press. Compose one of `interactionOverlayStyles` (from `@astryxdesign/core/utils`) on the same element — `backgroundColor` or `backgroundImage` for a surface whose hover and press are the system's overlays, `pressedBackgroundColor` for one whose hover is its own — and it paints the pressed token on the first frame of a press and fades it over the release, keeping `:active` for a mouse on a desktop. On a phone or tablet, where the stylesheet drops `:active`, the controller also paints a mouse, trackpad or Space-key press: at once, held while the button or key is down, faded at the release. A press is themed through `--color-overlay-pressed`.",
     },
   ],
   usage: {
     description:
-      'The touch press model every Astryx pressable uses, for a local component that paints its own press. Under a finger, CSS `:active` paints on the touch itself and can outlive the start of a scroll; the press model instead waits 150 ms before believing a press, cancels it the moment the finger travels 10 px or a scroll claims the gesture, never brings it back inside that gesture, answers a quick tap at the lift, and fades the release over 200 ms — the clocks a native list uses. One document-level controller does this for every marked element (installed by the first pressable to mount, removed by the last to unmount), so calling the hook adds no listener or state to your element. On a desktop a mouse press is still your `:active` rule: keep it, and drop it under `@media (pointer: coarse)` the way the built-in components do. That query reads the primary pointer, so on a phone or tablet it also drops `:active` for a connected mouse, trackpad or keyboard; the controller paints those presses there (at once, faded at the release), so nothing goes unanswered.',
+      'The touch press model every Astryx pressable uses, for a local component that paints its own press. Under a finger, CSS `:active` paints on the touch itself and can outlive the start of a scroll; the press model instead tracks the touch the way UIKit tracks a control: it highlights as the finger lands (after the content-touch delay inside a scroller, where a flick paints nothing), a quick tap answers at the lift, and a scroll that takes the touch cancels it with no fade. One document-level controller does this for every marked element (installed by the first pressable to mount, removed by the last to unmount), so calling the hook adds no listener or state to your element. On a desktop a mouse press is still your `:active` rule: keep it, and drop it under `@media (pointer: coarse)` the way the built-in components do. That query reads the primary pointer, so on a phone or tablet it also drops `:active` for a connected mouse, trackpad or keyboard; the controller paints those presses there (at once, faded at the release), so nothing goes unanswered.',
     bestPractices: [
       {
         guidance: true,
@@ -58,7 +58,7 @@ export const docs = {
 /** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description:
-    'Marks an element as a pressable surface of the touch press model (150 ms onset, 10 px slop, cancel on scroll, tap answers at lift, 200 ms fade) and installs the shared document controller; on a coarse primary pointer it also paints mouse, trackpad and Space-key presses at once. Returns the data-astryx-pressable marker to spread; compose one of interactionOverlayStyles on the same element to paint.',
+    'Marks an element as a pressable surface of the touch press model, tracked like a UIKit control (highlight as the finger lands, 150 ms inside a scroller, fade at the lift), and installs the shared document controller; on a coarse primary pointer it also paints mouse, trackpad and Space-key presses at once. Returns the data-astryx-pressable marker to spread; compose one of interactionOverlayStyles on the same element to paint.',
   paramDescriptions: {},
   returnDescriptions: {
     pressableProps:

package/src/hooks/usePressFeedback.ts

@@ -26,11 +26,11 @@ import {installPressFeedback, pressableProps} from '../utils/pressFeedback';
  * `interactionOverlayStyles` (from `@astryxdesign/core/utils`) on the same
  * element: `backgroundColor` or `backgroundImage` for a surface whose hover
  * and press are the system's overlays, `pressedBackgroundColor` for one
- * whose hover is its own. The controller writes its attribute on the element
- * while a touch press is believed (after the onset delay, cancelled by travel
- * or by a scroll) and for the release, and the composed style paints the
- * pressed token at the press's strength on the first frame and fades it over
- * the release, keeping `:active` for a mouse on a desktop. On a phone or
+ * whose hover is its own. Under a finger the controller tracks the press the
+ * way UIKit tracks a control and writes its
+ * attribute on the element while the press is held and for the release; the
+ * composed style paints the pressed token on the first frame and fades it
+ * over the release, keeping `:active` for a mouse on a desktop. On a phone or
  * tablet the stylesheet drops `:active` for every press, so the controller
  * also paints a mouse, trackpad or Space-key press there, at once. A press is
  * themed through `--color-overlay-pressed`, which the hold, the flash and the
@@ -46,7 +46,7 @@ import {installPressFeedback, pressableProps} from '../utils/pressFeedback';
  * @example
  * ```
  * const pressable = usePressFeedback();
- * return <div role="button" {...pressable} {...stylex.props(styles.row)} />;
+ * return <button {...pressable} {...stylex.props(styles.button)} />;
  * ```
  */
 export function usePressFeedback(): typeof pressableProps {

package/src/hooks/useScrollRegionProps.ts

@@ -0,0 +1,76 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useScrollRegionProps.ts
+ * @input Whether a region may scroll, and the caller's role and label
+ * @output useScrollRegionProps: a ref for the region, and the role and
+ *   accessible name that the region carries while its content overflows
+ * @position Internal hook for LayoutContent, LayoutPanel and StackItem.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/hooks/useScrollRegionProps.test.tsx
+ * - /packages/core/src/AppShell/observeMainOverflow.ts
+ */
+
+import {useCallback, useState, type AriaRole, type RefCallback} from 'react';
+import {
+  registerEnglishFallback,
+  useComponentTranslator,
+} from '../i18n/useComponentTranslator';
+import english from '../i18n/generated-english/hooks/useScrollRegionProps.generated';
+import {observeMainOverflow} from '../AppShell/observeMainOverflow';
+
+registerEnglishFallback(english);
+
+export interface ScrollRegionOptions {
+  /** Whether the region may scroll at all (`overflow: auto`). */
+  isScrollable: boolean;
+  /** The caller's role. It always wins, and takes no default name. */
+  role?: AriaRole;
+  /** The caller's accessible name. It always wins. */
+  label?: string;
+}
+
+export interface ScrollRegionProps {
+  ref: RefCallback<HTMLElement>;
+  role: AriaRole | undefined;
+  'aria-label': string | undefined;
+}
+
+/**
+ * The region's ref, role and accessible name. While the region may scroll
+ * and its content overflows, it is a group named by the caller's `label`, or
+ * by the translated "Content". A caller's `role` is kept with only the
+ * caller's `label`: a single main landmark relies on its role alone. When
+ * the region does not scroll, the caller's own `role` and `label` pass
+ * through unchanged.
+ */
+export function useScrollRegionProps({
+  isScrollable,
+  role,
+  label,
+}: ScrollRegionOptions): ScrollRegionProps {
+  const t = useComponentTranslator();
+  const [overflows, setOverflows] = useState(false);
+  // A caller's role takes no default name, so its region is not observed.
+  const hasRole = role != null;
+  const ref = useCallback(
+    (element: HTMLElement | null) => {
+      if (element == null || !isScrollable || hasRole) {
+        setOverflows(false);
+        return undefined;
+      }
+      return observeMainOverflow(element, setOverflows);
+    },
+    [hasRole, isScrollable],
+  );
+  const isGroup = !hasRole && isScrollable && overflows;
+  return {
+    ref,
+    role: role ?? (isGroup ? 'group' : undefined),
+    'aria-label':
+      label ?? (isGroup ? t('@astryx.scrollRegion.label') : undefined),
+  };
+}

package/src/i18n/InternationalizationContext.ts

@@ -25,10 +25,16 @@
 import {createContext} from 'react';
 import {getResolve} from './resolve';
 import type {Locale, MessagesByLocale, Overrides} from './types';
+import type {CalendarSystem} from '../utils/calendarSystem';
 
 export interface InternationalizationContextValue {
   locale: Locale;
   direction: 'ltr' | 'rtl';
+  /**
+   * The provider's requested calendar system. A context without it means
+   * Gregorian dates.
+   */
+  calendar?: CalendarSystem;
   messages: MessagesByLocale;
   overrides?: Overrides;
   translate: ReturnType<typeof getResolve>;

package/src/i18n/InternationalizationProvider.doc.mjs

@@ -26,7 +26,7 @@ export const docs = {
         name: 'Provider boundary',
         required: true,
         description:
-          'A nonvisual context boundary that supplies locale, message catalogs, overrides, and direction to descendant Astryx components. It renders no DOM element.',
+          'A nonvisual context boundary that supplies locale, message catalogs, overrides, and direction to descendant Astryx components, and a calendar system to `Calendar`. It renders no DOM element.',
       },
     ],
     bestPractices: [
@@ -50,6 +50,11 @@ export const docs = {
         description:
           "Set the `dir` attribute on `<html>` (or a wrapping element) yourself; the provider does not set it. Astryx components mirror layout and directional icons from the DOM `dir`, so an RTL locale won't visually mirror without it. Use `getLocaleDirection(locale)` to derive the value for both the provider and the DOM.",
       },
+      {
+        guidance: true,
+        description:
+          'Set `calendar` to show `Calendar`, `DateInput`, `DateRangeInput`, and `DateTimeInput` in another calendar system and write Timestamp, PowerSearch, and Schedule dates in it. A locale never selects the calendar: `fa-IR` shows Gregorian dates until you set `calendar="persian"`, and a `-u-ca-` keyword in `locale`, as in `th-TH-u-ca-buddhist`, keeps Gregorian dates too. Date values stay Gregorian ISO strings.',
+      },
       {
         guidance: false,
         description:
@@ -86,6 +91,13 @@ export const docs = {
       description:
         'Explicit text-direction override for the context. When omitted, direction is derived from `locale` via `Intl.Locale.getTextInfo()`. This sets the direction Astryx reads, but it does NOT set the DOM `dir` attribute; you must set `dir` on `<html>` (or a wrapping element) yourself, since Astryx components mirror layout and directional icons from the DOM `dir`, not from this prop. Set both to the same value and keep them in sync.',
     },
+    {
+      name: 'calendar',
+      type: "'gregory' | 'iso8601' | 'buddhist' | 'roc' | 'japanese' | 'persian' | 'indian' | 'hebrew' | 'chinese' | 'dangi' | 'coptic' | 'ethiopic' | 'ethioaa' | 'islamic-civil' | 'islamic-tbla' | 'islamic-umalqura'",
+      required: false,
+      description:
+        "Calendar system of the subtree, such as 'persian', 'hebrew', or 'buddhist'. `Calendar`, `DateInput`, `DateRangeInput`, and `DateTimeInput` show it, and Timestamp, PowerSearch, and Lab's Schedule write their dates in it. When omitted, the calendar is Gregorian: a locale never selects it, neither by its default calendar nor by a `-u-ca-` keyword. A component's own `calendar` prop takes precedence. Values stay Gregorian ISO dates. Calendars other than gregory, iso8601, buddhist, roc, and japanese need `Temporal`; the context keeps the requested calendar, and where the runtime lacks `Temporal`, these components show Gregorian dates and warn in development. Load a polyfill such as `temporal-polyfill/full/global` on the server and in the browser.",
+    },
     {
       name: 'children',
       type: 'ReactNode',
@@ -124,6 +136,20 @@ export function AppI18n({children}: {children: ReactNode}) {
       {children}
     </InternationalizationProvider>
   );
+}`,
+    },
+    {
+      label: 'Show Calendar in the Persian calendar',
+      code: `import type {ReactNode} from 'react';
+import {InternationalizationProvider} from '@astryxdesign/core/i18n';
+
+// Values stay Gregorian ISO dates, for example '2026-10-30'.
+export function AppI18n({children}: {children: ReactNode}) {
+  return (
+    <InternationalizationProvider locale="fa-IR" calendar="persian">
+      {children}
+    </InternationalizationProvider>
+  );
 }`,
     },
     {
@@ -190,5 +216,7 @@ export const docsDense = {
       'map of BCP 47 tag to a rich Catalog or generated RuntimeCatalog; "en" is always available',
     overrides:
       'sparse per-locale key overrides applied on top of shipped defaults',
+    calendar:
+      'calendar system for Calendar, DateInput, DateRangeInput, DateTimeInput, Timestamp, PowerSearch, and Schedule dates (default: gregory; a -u-ca- keyword in locale does not select it); values stay Gregorian ISO; non-Gregorian-aligned calendars need Temporal',
   },
 };

package/src/i18n/InternationalizationProvider.tsx

@@ -4,9 +4,9 @@
 
 /**
  * @file InternationalizationProvider.tsx
- * @input React, InternationalizationContext, i18n types
+ * @input React, InternationalizationContext, i18n types, calendar resolution
  * @output Exports InternationalizationProvider component and props type
- * @position Provider component for astryx i18n locale + messages
+ * @position Provider component for astryx i18n locale, messages, and calendar
  *
  * Wraps a subtree with a locale and (optional) additional message catalogs +
  * overrides. Astryx components inside the subtree resolve their strings via
@@ -22,6 +22,8 @@
 import {useMemo, type ReactNode} from 'react';
 import {InternationalizationContext} from './InternationalizationContext';
 import {getLocaleDirection} from './getLocaleDirection';
+import {resolveCalendarSystem} from './useCalendarSystem';
+import type {CalendarSystem} from '../utils/calendarSystem';
 import type {
   Locale,
   MessagesByLocale,
@@ -30,6 +32,8 @@ import type {
 } from './types';
 import {getResolve} from './resolve';
 
+const PROVIDER_NAME = 'InternationalizationProvider';
+
 function normalizeMessages(
   messages: ProviderMessagesByLocale,
 ): MessagesByLocale {
@@ -100,6 +104,25 @@ export interface InternationalizationProviderProps {
    * in sync (e.g. `dir={getLocaleDirection(locale)}` on both).
    */
   dir?: 'ltr' | 'rtl';
+  /**
+   * The calendar system of this subtree, such as `'persian'` or `'hebrew'`.
+   * `Calendar` shows it, and Timestamp, PowerSearch, and Lab's Schedule write
+   * their dates in it. `DateInput`, `DateRangeInput`, and `DateTimeInput`
+   * show it too. Values stay
+   * Gregorian ISO dates. When omitted, the calendar is Gregorian: a locale
+   * never selects it, neither by its default calendar nor by a `-u-ca-`
+   * keyword. A component's own `calendar` prop takes precedence. Calendars
+   * other than `gregory`, `iso8601`, `buddhist`, `roc`, and `japanese` need
+   * `Temporal`. The context keeps the requested calendar; where `Temporal` is
+   * missing, these components show Gregorian dates and warn once in
+   * development.
+   *
+   * @example
+   * ```
+   * <InternationalizationProvider locale="fa-IR" calendar="persian">
+   * ```
+   */
+  calendar?: CalendarSystem;
   children: ReactNode;
 }
 
@@ -112,19 +135,28 @@ export function InternationalizationProvider({
   messages,
   overrides,
   dir,
+  calendar: calendarProp,
   children,
 }: InternationalizationProviderProps) {
   const direction = dir ?? getLocaleDirection(locale);
+  const calendar = useMemo(
+    () =>
+      calendarProp != null
+        ? resolveCalendarSystem(calendarProp, PROVIDER_NAME)
+        : 'gregory',
+    [calendarProp],
+  );
   const value = useMemo(() => {
     const providedMessages = messages ?? {};
     return {
       locale,
       direction,
+      calendar,
       messages: normalizeMessages(providedMessages),
       overrides,
       translate: getResolve(locale, providedMessages, overrides),
     };
-  }, [locale, direction, messages, overrides]);
+  }, [locale, direction, calendar, messages, overrides]);
   return (
     <InternationalizationContext value={value}>
       {children}

package/src/i18n/generated-english/DateInput/DateInput.generated.ts

@@ -10,7 +10,6 @@ const english: Readonly<Record<string, string>> = {
   "@astryx.dateInput.clear": "Clear {label}",
   "@astryx.dateInput.closeCalendar": "Close calendar",
   "@astryx.dateInput.dialogLabel": "Choose date",
-  "@astryx.dateInput.invalidDate": "Invalid date",
   "@astryx.dateInput.openCalendar": "Open calendar",
   "@astryx.dateInput.placeholder": "Select a date",
   "@astryx.dateInput.toggleCalendarClose": "Close calendar",

package/src/i18n/generated-english/DateInput/useTypedDate.generated.ts

@@ -0,0 +1,17 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @generated by scripts/generate-i18n-runtime.mjs from packages/core/locales/en.json,
+ * holding the English for the catalog keys named in packages/core/src/DateInput/useTypedDate.ts.
+ * Do not edit by hand. Run `pnpm generate:i18n-runtime` instead.
+ */
+
+const english: Readonly<Record<string, string>> = {
+  "@astryx.dateInput.calendarDescription": "Dates use the {calendar}",
+  "@astryx.dateInput.formatHint": "e.g., {example}",
+  "@astryx.dateInput.invalidDate": "Invalid date",
+  "@astryx.dateInput.nonexistentDate": "This date does not exist in the {calendar}",
+  "@astryx.dateInput.outOfRangeDate": "{bounds, select, both {Enter a date from {min} to {max}} min {Enter a date on or after {min}} max {Enter a date on or before {max}} other {This date is not available}}"
+};
+
+export default english;

package/src/i18n/generated-english/DateTimeInput/DateTimeInput.generated.ts

@@ -9,7 +9,6 @@
 const english: Readonly<Record<string, string>> = {
   "@astryx.dateInput.clear": "Clear {label}",
   "@astryx.dateInput.closeCalendar": "Close calendar",
-  "@astryx.dateInput.invalidDate": "Invalid date",
   "@astryx.dateInput.openCalendar": "Open calendar",
   "@astryx.dateInput.toggleCalendarClose": "Close calendar",
   "@astryx.dateTimeInput.dialogLabel": "Choose date and time",

package/src/i18n/generated-english/hooks/useScrollRegionProps.generated.ts

@@ -0,0 +1,13 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @generated by scripts/generate-i18n-runtime.mjs from packages/core/locales/en.json,
+ * holding the English for the catalog keys named in packages/core/src/hooks/useScrollRegionProps.ts.
+ * Do not edit by hand. Run `pnpm generate:i18n-runtime` instead.
+ */
+
+const english: Readonly<Record<string, string>> = {
+  "@astryx.scrollRegion.label": "Content"
+};
+
+export default english;

package/src/i18n/generated-locales/en.generated.ts

@@ -325,6 +325,12 @@ const runtimeCatalog: Readonly<Record<string, string>> = {
   '@astryx.dateInput.toggleCalendarClose': 'Close calendar',
   '@astryx.dateInput.clear': 'Clear {label}',
   '@astryx.dateInput.invalidDate': 'Invalid date',
+  '@astryx.dateInput.nonexistentDate':
+    'This date does not exist in the {calendar}',
+  '@astryx.dateInput.outOfRangeDate':
+    '{bounds, select, both {Enter a date from {min} to {max}} min {Enter a date on or after {min}} max {Enter a date on or before {max}} other {This date is not available}}',
+  '@astryx.dateInput.formatHint': 'e.g., {example}',
+  '@astryx.dateInput.calendarDescription': 'Dates use the {calendar}',
   '@astryx.dateInput.resetPicking': 'Reset',
   '@astryx.dateInput.savePicking': 'Save',
   '@astryx.dateInput.doneChoosingMonth': 'Done',
@@ -375,6 +381,7 @@ const runtimeCatalog: Readonly<Record<string, string>> = {
   '@astryx.banner.expand': 'Expand',
   '@astryx.button.loading': 'Loading',
   '@astryx.spinner.loading': 'Loading',
+  '@astryx.scrollRegion.label': 'Content',
   '@astryx.chatComposerDrawer.expand': 'Expand {label}',
   '@astryx.chatComposerDrawer.collapse': 'Collapse {label}',
   '@astryx.chatDictationButton.startDictation': 'Start dictation',

package/src/i18n/generated-locales/pseudo.generated.ts

@@ -333,6 +333,12 @@ const runtimeCatalog: Readonly<Record<string, string>> = {
   '@astryx.dateInput.toggleCalendarClose': '⟦Çłóšé çàłéñðàř⟧',
   '@astryx.dateInput.clear': '⟦Çłéàř {label}⟧',
   '@astryx.dateInput.invalidDate': '⟦Íñṽàłíð ðàţé⟧',
+  '@astryx.dateInput.nonexistentDate':
+    '⟦Ţĥíš ðàţé ðóéš ñóţ éẋíšţ íñ ţĥé {calendar}⟧',
+  '@astryx.dateInput.outOfRangeDate':
+    '⟦{bounds, select, both {Enter a date from {min} to {max}} min {Enter a date on or after {min}} max {Enter a date on or before {max}} other {This date is not available}}⟧',
+  '@astryx.dateInput.formatHint': '⟦é.ĝ., {example}⟧',
+  '@astryx.dateInput.calendarDescription': '⟦Ðàţéš úšé ţĥé {calendar}⟧',
   '@astryx.dateInput.resetPicking': '⟦Řéšéţ⟧',
   '@astryx.dateInput.savePicking': '⟦Šàṽé⟧',
   '@astryx.dateInput.doneChoosingMonth': '⟦Ðóñé⟧',
@@ -383,6 +389,7 @@ const runtimeCatalog: Readonly<Record<string, string>> = {
   '@astryx.banner.expand': '⟦Éẋþàñð⟧',
   '@astryx.button.loading': '⟦Łóàðíñĝ⟧',
   '@astryx.spinner.loading': '⟦Łóàðíñĝ⟧',
+  '@astryx.scrollRegion.label': '⟦Çóñţéñţ⟧',
   '@astryx.chatComposerDrawer.expand': '⟦Éẋþàñð {label}⟧',
   '@astryx.chatComposerDrawer.collapse': '⟦Çółłàþšé {label}⟧',
   '@astryx.chatDictationButton.startDictation': '⟦Šţàřţ ðíçţàţíóñ⟧',

package/src/i18n/index.ts

@@ -15,6 +15,7 @@
  *   - useDirection                — hook returning the ambient text direction
  *   - getLocaleDirection          — server-safe locale → direction helper
  *   - Translator                  — interface for consumer-injected runtimes
+ *   - CalendarSystem              — the calendars date components can show
  *
  * `useTranslator` and `InternationalizationContext` are the public paths
  * that resolve any Astryx key, so they register the whole English catalog.
@@ -39,6 +40,7 @@ export {useLocale} from './useLocale';
 export {useCollator} from './useCollator';
 export {useDirection} from './useDirection';
 export {getLocaleDirection} from './getLocaleDirection';
+export type {CalendarSystem} from '../utils/calendarSystem';
 export type {Translator} from './translator';
 export type {
   Locale,

package/src/i18n/useCalendarSystem.ts

@@ -0,0 +1,95 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useCalendarSystem.ts
+ * @input InternationalizationContext, an optional component `calendar`
+ * @output The calendar system a date component shows, and the helpers that
+ *   normalize a calendar identifier
+ * @position Internal i18n hook; read by InternationalizationProvider, date
+ *   components, and the public calendar hooks. Not re-exported from the i18n
+ *   barrel.
+ */
+
+import {use} from 'react';
+import {InternationalizationContext} from './InternationalizationContext';
+import {
+  type CalendarSystem,
+  isCalendarSystem,
+  isCalendarSystemAvailable,
+} from '../utils/calendarSystem';
+import {warnOnce} from '../utils/devWarning';
+
+/**
+ * Normalizes a calendar identifier. An identifier outside `CalendarSystem`
+ * resolves to `gregory` and warns once in development.
+ */
+export function resolveCalendarSystem(
+  id: string,
+  source: string,
+): CalendarSystem {
+  if (isCalendarSystem(id)) {
+    return id;
+  }
+  warnOnce(
+    `calendar-unsupported:${id}`,
+    source,
+    `The calendar "${id}" is not supported; showing Gregorian dates.`,
+  );
+  return 'gregory';
+}
+
+/**
+ * A calendar this runtime can show, else `gregory`. Calendars outside the
+ * Gregorian-aligned set need a `Temporal` that supports them. The fallback
+ * warns once for each calendar, on the server and in the browser.
+ */
+function availableCalendarOrGregorian(
+  calendar: CalendarSystem,
+  source: string,
+): CalendarSystem {
+  if (isCalendarSystemAvailable(calendar)) {
+    return calendar;
+  }
+  warnOnce(
+    `calendar-unavailable:${calendar}`,
+    source,
+    `The "${calendar}" calendar needs a Temporal that supports it, and this ` +
+      'runtime has none; showing Gregorian dates. Load a Temporal polyfill ' +
+      "with every calendar, such as 'temporal-polyfill/full/global', on the " +
+      'server and in the browser.',
+  );
+  return 'gregory';
+}
+
+/**
+ * The calendar that a caller names, without the provider: an unknown
+ * identifier, or one this runtime cannot show, becomes `gregory` and warns
+ * once in development.
+ */
+export function resolveShownCalendar(
+  calendar: string,
+  source: string,
+): CalendarSystem {
+  return availableCalendarOrGregorian(
+    resolveCalendarSystem(calendar, source),
+    source,
+  );
+}
+
+/**
+ * The calendar a date component shows: its own `calendar`, else the
+ * provider's resolved calendar, else `gregory`. It resolves during render, so
+ * the server and the browser agree when both have `Temporal` or both lack it.
+ */
+export function useCalendarSystem(
+  calendar: CalendarSystem | undefined,
+  source: string,
+): CalendarSystem {
+  const context = use(InternationalizationContext);
+  return resolveShownCalendar(
+    calendar ?? context.calendar ?? 'gregory',
+    source,
+  );
+}

package/src/internal/calendar-system.ts

@@ -0,0 +1,26 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file calendar-system.ts
+ * @input The i18n calendar resolution
+ * @output `@astryxdesign/core/internal/calendar-system`: the hook that
+ *   resolves the calendar a date component shows, and the helpers that name
+ *   its months and days as Core's Calendar does, for Lab components
+ * @position An internal entry reserved for Astryx's own packages:
+ *   undocumented, outside the public API and its compatibility promise,
+ *   versioned in lockstep with Core, and allowed only in Core and Lab by the
+ *   `@astryx/no-core-internal-import` lint rule. Named re-exports only.
+ *
+ * SYNC: When modified, update calendar-system.test.ts and
+ * scripts/sync-exports.js.
+ */
+
+export {useCalendarSystem} from '../i18n/useCalendarSystem';
+export {
+  calendarMonthLabelDay,
+  calendarMonthOf,
+  formatCalendarDate,
+  formatCalendarDateToParts,
+  formatCalendarInstantRange,
+} from '../utils/calendarSystem';
+export type {CalendarSystem} from '../utils/calendarSystem';

package/src/internal/spinner-rotor.ts

@@ -0,0 +1,20 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+/**
+ * @file spinner-rotor.ts
+ * @input Spinner's shared rotor
+ * @output `@astryxdesign/core/internal/spinner-rotor`: SPINNER_ARC_FRACTION,
+ *   spinnerRotorStyles and syncRotationPhase, re-exported by name for Lab's
+ *   indeterminate CircularProgress
+ * @position An internal entry reserved for Astryx's own packages. It is
+ *   undocumented, outside the public API and its compatibility promise, and
+ *   versioned in lockstep with Core. The `@astryx/no-core-internal-import`
+ *   lint rule allows it only in Core and Lab. Core components import the
+ *   same modules by relative path. Named re-exports only.
+ *
+ * SYNC: When modified, update scripts/sync-exports.js.
+ */
+export {
+  SPINNER_ARC_FRACTION,
+  spinnerRotorStyles,
+  syncRotationPhase,
+} from '../Spinner/spinnerRotor';

package/src/internal/touch.ts

@@ -2,9 +2,12 @@
 
 /**
  * @file touch.ts
- * @input The gesture core: the arena, the recognizers, and their geometry
+ * @input The gesture core: the arena, the recognizers, and their geometry;
+ *   the pan, the motion engine and math, and the touch-presentation and
+ *   direction helpers that Lab components read
  * @output `@astryxdesign/core/internal/touch`: the gesture core's primitives
- *   for Lab components, re-exported by name
+ *   and the motion, touch-presentation and direction modules for Lab
+ *   components, re-exported by name
  * @position An internal entry reserved for Astryx's own packages:
  *   undocumented, outside the public API and its compatibility promise
  *   (spec:AST-017 FR21), versioned in lockstep with Core, and allowed only in
@@ -39,3 +42,41 @@ export {
 export {LongPressGestureRecognizer} from '../gestures/LongPressGestureRecognizer';
 export {TapGestureRecognizer} from '../gestures/TapGestureRecognizer';
 export {DEFAULT_ENVIRONMENT} from '../gestures/types';
+
+// Lab's useRefreshControl reads these: its pull's pan and the hook that
+// starts it. It also reads the motion engine and math, and the scroll
+// view's bounce spring, for its pull, settle and end. Its indicator fades
+// along the settle's curve, and the motion-role parsers read the theme's
+// tokens for its end.
+export {PanGestureRecognizer} from '../gestures/PanGestureRecognizer';
+export type {PanGestureRecognizerOptions} from '../gestures/PanGestureRecognizer';
+export type {
+  GestureEventContext,
+  GestureTouch,
+  PointerKind,
+} from '../gestures/types';
+export {useGestureRecognizer} from '../gestures/useGestureRecognizer';
+// The motion engine's factory. The public one, `createAnimator`, plays
+// only the theme's state-change motion.
+export {createMotionEngine} from '../motion/animator';
+export type {
+  Animator as MotionEngine,
+  AnimatorOptions as MotionEngineOptions,
+  MotionCurve,
+} from '../motion/animator';
+export {cubicBezier} from '../motion/bezier';
+export {mapProgress} from '../motion/progress';
+export {parseCssEasing, parseMotionRoleValue} from '../motion/roles';
+export {
+  rubberBand,
+  rubberBandInverse,
+  rubberBandSlope,
+} from '../motion/rubberBand';
+export {scroll} from '../motion/uikit/scroll';
+
+// Lab components also read the UIKit gesture table, the touch presentation
+// and its query, and an element's direction.
+export {isRtlElement} from '../hooks/isRtlElement';
+export {UIKIT_GESTURES} from '../motion/uikit/gestures';
+export {useTouchPresentation} from '../utils/touchPresentation';
+export {TOUCH_QUERY} from '../utils/touchQueries';

package/src/motion/MEASUREMENTS.md

@@ -314,3 +314,14 @@ scroll view coasts with 0.25 × the pan's velocity plus 0.75 × its value one
 event earlier (four HID releases; `velocity.scrollReleaseWeight`, which a
 pan's `scrollVelocity()` reads). On UIKit, Reduce Motion with Prefer Cross-Fade changes
 nothing on a picker; the Wheel follows design:reduced-motion instead.
+
+## Menus (UIMenu)
+
+Probe: the UIKit lab host app with a UIButton whose `UIMenu` is its primary
+action (`showsMenuAsPrimaryAction`), three to twelve items, on a plain view
+and inside a UIScrollView; the gesture-state, presentation-modifier,
+display-link and feedback hooks; real HID touches.
+
+| ID    | Scene                  | Gesture                                                                                                                                                 | Extract                                                                                                                                 | Method |
+| ----- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ------ |
+| M-MN2 | button on a plain view | hold until the menu is open, then lift still; move 8 pt down, 8 pt right, 12 pt down, (7, 7), (8, 8) and lift; move 6 pt before the open and 6 pt after | row picked or not; handoff and list-selection recognizer states; highlighted row per frame: threshold, metric, where it is counted from | C      |