@astryxdesign/core 0.7.7 → 0.7.8-canary.0588a13

package/src/TimeInput/timeWheelRules.ts

@@ -0,0 +1,352 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file timeWheelRules.ts
+ * @input A time of day, the hour format and the bounds
+ * @output Pure rules of UIDatePicker's time wheels: the columns' rows, the
+ *   time a turned column makes, and which other columns turn with it
+ * @position Internal helper of the TimeInput and DateTimeInput sheets: the
+ *   rows of both their finger and their mouse wheels
+ *
+ * The columns do not loop. Each rule follows a leaf of motion/uikit/
+ * datePicker.ts `wheels`. Pure functions keep the rules testable without a
+ * layout engine.
+ *
+ * SYNC: When modified, update timeWheelRules.test.ts and TimeWheels.tsx.
+ */
+
+import {
+  clampTime,
+  formatISOTime,
+  parseISOTime,
+  type ISOTimeString,
+} from '../utils/timeParser';
+
+/** A time of day, 24-hour. */
+export interface TimeParts {
+  hour: number;
+  minute: number;
+  second: number;
+}
+
+/** A time wheel column. */
+export type TimeColumn = 'hour' | 'minute' | 'second' | 'meridiem';
+
+/** One row of a column: the value it stands for and its label. */
+export interface TimeRow {
+  value: number;
+  label: string;
+  isDisabled: boolean;
+  /**
+   * Where the row falls when a key steps the column. An hour row holds the hour
+   * it stands for, so a key follows the full time: 12 PM comes before 1 PM.
+   */
+  order?: number;
+}
+
+/** Inclusive bounds in seconds since midnight; `null` is unbounded. */
+export interface TimeBounds {
+  min: number | null;
+  max: number | null;
+}
+
+const SECONDS_PER_DAY = 24 * 3600;
+
+function secondsOfISO(time: ISOTimeString | undefined): number | null {
+  if (time == null) {
+    return null;
+  }
+  const parsed = parseISOTime(time);
+  return parsed == null
+    ? null
+    : parsed.hour * 3600 + parsed.minute * 60 + parsed.second;
+}
+
+/** The bounds of a field's `min` and `max` times. */
+export function wheelBounds(
+  min: ISOTimeString | undefined,
+  max: ISOTimeString | undefined,
+): TimeBounds {
+  return {min: secondsOfISO(min), max: secondsOfISO(max)};
+}
+
+/** Whether the hour falls in the PM half (1) or the AM half (0). */
+export function meridiemOf(hour: number): 0 | 1 {
+  return hour < 12 ? 0 : 1;
+}
+
+/** The 12-hour clock's label for a 24-hour hour: 0 → 12, 13 → 1. */
+export function hour12From24(hour: number): number {
+  const h = hour % 12;
+  return h === 0 ? 12 : h;
+}
+
+/** The 24-hour hour for a 12-hour hour in a half of the day: 12 AM → 0. */
+export function hour24From12(hour: number, meridiem: number): number {
+  return (hour % 12) + (meridiem === 1 ? 12 : 0);
+}
+
+function partsOf(seconds: number): TimeParts {
+  const s = ((seconds % SECONDS_PER_DAY) + SECONDS_PER_DAY) % SECONDS_PER_DAY;
+  return {
+    hour: Math.floor(s / 3600),
+    minute: Math.floor((s % 3600) / 60),
+    second: s % 60,
+  };
+}
+
+/** Whether [start, end] (seconds) overlaps the bounds. */
+function overlaps(start: number, end: number, bounds: TimeBounds): boolean {
+  return (
+    (bounds.min == null || end >= bounds.min) &&
+    (bounds.max == null || start <= bounds.max)
+  );
+}
+
+/**
+ * The time the wheels show for `time`: its seconds kept when the picker has a
+ * seconds column and dropped when it has none. A time outside the bounds is
+ * shown as it is, on its disabled rows: opening the sheet never moves an
+ * untouched value.
+ */
+export function displayedTime(time: TimeParts, hasSeconds: boolean): TimeParts {
+  return {...time, second: hasSeconds ? time.second : 0};
+}
+
+/**
+ * The time a column's rest commits when it would make `time`: the nearest
+ * time inside the bounds that the columns have a row for. Past a bound, that
+ * is the bound itself, or, with no seconds column, the nearest whole minute
+ * inside it (a 16:55:30 maximum: 16:55). Inside the bounds, `time` itself.
+ */
+export function restingTime(
+  time: TimeParts,
+  hasSeconds: boolean,
+  bounds: TimeBounds,
+): TimeParts {
+  const boundAt = (seconds: number | null) =>
+    seconds == null ? undefined : formatISOTime(partsOf(seconds), true);
+  const resting = clampTime(
+    formatISOTime(time, hasSeconds),
+    boundAt(bounds.min),
+    boundAt(bounds.max),
+    hasSeconds,
+  );
+  return parseISOTime(resting) ?? time;
+}
+
+/**
+ * The hour the hour column makes when it comes to rest on `row` from the row
+ * that showed `from` (24-hour). In 24-hour time the row is the hour. In 12-hour
+ * time the half of the day changes only when the move passes between 11 and 12.
+ * The column (1 … 12) does not loop, so 12 counts as next to 1. A move between
+ * 12 and 1 to 6 keeps the half of the day. A move between 12 and 7 to 11
+ * changes it.
+ *
+ * @example
+ * ```
+ * hourAfterTurn(11, 12, '12h'); // 12: 11 AM → 12 PM
+ * hourAfterTurn(12, 1, '12h'); // 13: 12 PM → 1 PM
+ * hourAfterTurn(13, 9, '12h'); // 21: 1 PM → 9 PM
+ * ```
+ */
+export function hourAfterTurn(
+  from: number,
+  row: number,
+  hourFormat: '12h' | '24h',
+): number {
+  if (hourFormat === '24h') {
+    return row;
+  }
+  const shown = hour12From24(from);
+  if (row === shown) {
+    return from;
+  }
+  const half = meridiemOf(from);
+  const passes11And12 =
+    (shown === 12 && row >= 7) || (row === 12 && shown >= 7);
+  return hour24From12(row, passes11And12 ? 1 - half : half);
+}
+
+function hourRowsFor(
+  hourFormat: '12h' | '24h',
+  hourOf: (row: number) => number,
+  bounds: TimeBounds,
+): TimeRow[] {
+  const rows =
+    hourFormat === '24h'
+      ? Array.from({length: 24}, (_, hour) => hour)
+      : Array.from({length: 12}, (_, index) => index + 1);
+  return rows.map(row => {
+    const hour = hourOf(row);
+    return {
+      value: row,
+      label: hourFormat === '24h' ? String(row).padStart(2, '0') : String(row),
+      isDisabled: !overlaps(hour * 3600, hour * 3600 + 3599, bounds),
+      order: hour,
+    };
+  });
+}
+
+/**
+ * The hour column under a finger. In 24-hour time its rows are 00 … 23. In
+ * 12-hour time they are 1 … 12, each row standing for the hour a turn onto it
+ * from `from` makes (`hourAfterTurn`). A row is disabled when no minute of that
+ * hour is inside the bounds.
+ */
+export function hourRows(
+  from: number,
+  hourFormat: '12h' | '24h',
+  bounds: TimeBounds,
+): TimeRow[] {
+  return hourRowsFor(
+    hourFormat,
+    row => hourAfterTurn(from, row, hourFormat),
+    bounds,
+  );
+}
+
+/**
+ * The hour column under a mouse, whose columns turn one at a time. A 12-hour
+ * row stands for its hour in the half of the day that `from` is in.
+ */
+export function hourRowsInHalf(
+  from: number,
+  hourFormat: '12h' | '24h',
+  bounds: TimeBounds,
+): TimeRow[] {
+  const half = meridiemOf(from);
+  return hourRowsFor(
+    hourFormat,
+    row => (hourFormat === '24h' ? row : hour24From12(row, half)),
+    bounds,
+  );
+}
+
+/**
+ * The minute column for `hour`: every minute. A row is disabled when it is
+ * outside the bounds (its whole minute, when the picker shows seconds).
+ */
+export function minuteRows(
+  hour: number,
+  hasSeconds: boolean,
+  bounds: TimeBounds,
+): TimeRow[] {
+  return Array.from({length: 60}, (_, minute): TimeRow => {
+    const start = hour * 3600 + minute * 60;
+    return {
+      value: minute,
+      label: String(minute).padStart(2, '0'),
+      isDisabled: !overlaps(start, start + (hasSeconds ? 59 : 0), bounds),
+    };
+  });
+}
+
+/** The second column for `hour`:`minute`. */
+export function secondRows(
+  hour: number,
+  minute: number,
+  bounds: TimeBounds,
+): TimeRow[] {
+  return Array.from({length: 60}, (_, second): TimeRow => {
+    const at = hour * 3600 + minute * 60 + second;
+    return {
+      value: second,
+      label: String(second).padStart(2, '0'),
+      isDisabled: !overlaps(at, at, bounds),
+    };
+  });
+}
+
+/** The AM/PM column: a half is disabled when none of its hours is in bounds. */
+export function meridiemRows(
+  labels: {am: string; pm: string},
+  bounds: TimeBounds,
+): TimeRow[] {
+  return [
+    {
+      value: 0,
+      label: labels.am,
+      isDisabled: !overlaps(0, 12 * 3600 - 1, bounds),
+    },
+    {
+      value: 1,
+      label: labels.pm,
+      isDisabled: !overlaps(12 * 3600, SECONDS_PER_DAY - 1, bounds),
+    },
+  ];
+}
+
+/**
+ * The time made by turning `column` to `value` (its row's value) from `from`
+ * (the time the wheels show). Only that column changes, and the AM/PM column
+ * moves the hour by twelve.
+ */
+export function turnColumn(
+  from: TimeParts,
+  column: TimeColumn,
+  value: number,
+  hourFormat: '12h' | '24h',
+): TimeParts {
+  switch (column) {
+    case 'hour':
+      return {...from, hour: hourAfterTurn(from.hour, value, hourFormat)};
+    case 'minute':
+      return {...from, minute: value};
+    case 'second':
+      return {...from, second: value};
+    case 'meridiem':
+      return {...from, hour: hour24From12(hour12From24(from.hour), value)};
+  }
+}
+
+/** What a column shows for a time: its row's value. */
+export function columnValue(
+  time: TimeParts,
+  column: TimeColumn,
+  hourFormat: '12h' | '24h',
+): number {
+  switch (column) {
+    case 'hour':
+      return hourFormat === '24h' ? time.hour : hour12From24(time.hour);
+    case 'minute':
+      return time.minute;
+    case 'second':
+      return time.second;
+    case 'meridiem':
+      return meridiemOf(time.hour);
+  }
+}
+
+/**
+ * The columns that must turn after `column` came to rest on `value`. That is
+ * every column whose row for the committed time differs from the row it shows
+ * now. The column that moved shows `value`; the others show `from`. An hour
+ * that crossed 11 ↔ 12 turns the AM/PM column; a time brought back onto a bound
+ * turns every column whose row changed.
+ */
+export function columnsToTurn(
+  from: TimeParts,
+  column: TimeColumn,
+  value: number,
+  committed: TimeParts,
+  options: {hourFormat: '12h' | '24h'; hasSeconds: boolean},
+): {column: TimeColumn; value: number}[] {
+  const columns: TimeColumn[] = ['hour', 'minute'];
+  if (options.hasSeconds) {
+    columns.push('second');
+  }
+  if (options.hourFormat === '12h') {
+    columns.push('meridiem');
+  }
+  const turns: {column: TimeColumn; value: number}[] = [];
+  for (const each of columns) {
+    const shown =
+      each === column ? value : columnValue(from, each, options.hourFormat);
+    const target = columnValue(committed, each, options.hourFormat);
+    if (shown !== target) {
+      turns.push({column: each, value: target});
+    }
+  }
+  return turns;
+}

package/src/Timer/Timer.tsx

@@ -186,6 +186,7 @@ export function Timer({
   const resolvedFormat = resolveFormat(format);
   const initialPresentation = getPresentation(0, resolvedFormat);
 
+  // Syncs the elapsed-time text with a timer.
   useEffect(() => {
     const resolvedStartTime =
       startTime !== undefined && Number.isFinite(startTime)

package/src/Timestamp/Timestamp.tsx

@@ -378,7 +378,7 @@ export function Timestamp({
     ? formatInstant(date, 'full', locale, {timeZoneNameStyle: 'long'})
     : '';
 
-  // Live updates
+  // Syncs the relative time with an interval timer while the timestamp is live.
   useEffect(() => {
     if (!isLive || !isValidDate || !isRelativeFormat(effectiveFormat)) {
       return;

package/src/Timestamp/formatInstant.ts

@@ -29,7 +29,7 @@
  * - /packages/core/src/Timestamp/Timestamp.test.tsx
  */
 
-import {SHARED_DATE_FORMAT_OPTIONS, getTimeZoneParts} from '../utils/plainDate';
+import {SHARED_DATE_FORMAT_OPTIONS, getWallClock} from '../utils/plainDate';
 import type {Locale} from '../i18n/types';
 import type {TimestampFormat} from './Timestamp';
 
@@ -125,38 +125,6 @@ function pad(n: number): string {
   return String(n).padStart(2, '0');
 }
 
-/** The fields a `system_*` string is assembled from. */
-interface WallClock {
-  year: number;
-  month: number;
-  day: number;
-  hour: number;
-  minute: number;
-  second: number;
-}
-
-/**
- * Wall-clock fields for an instant: in the named zone, or — with no zone —
- * the viewer's own, read straight off the `Date`. The zone-less branch
- * deliberately stays on plain getters so the default rendering never gains a
- * dependency on `Intl` zone data it did not have before.
- *
- * The explicit return type is load-bearing: it is what forces the two branches
- * to keep producing the same shape.
- */
-function getWallClock(date: Date, timeZone: string | undefined): WallClock {
-  return timeZone === undefined
-    ? {
-        year: date.getFullYear(),
-        month: date.getMonth() + 1,
-        day: date.getDate(),
-        hour: date.getHours(),
-        minute: date.getMinutes(),
-        second: date.getSeconds(),
-      }
-    : getTimeZoneParts(date.getTime(), timeZone);
-}
-
 /**
  * Renders one instant in one absolute format.
  *

package/src/Toast/Toast.doc.mjs

@@ -89,7 +89,7 @@ export const docs = {
       name: 'renderContent',
       type: '(toast: ToastContentRenderProps) => ReactNode',
       description:
-        "Replaces the content of this toast's card with your own layout. Astryx keeps the card, its astryx-toast theme target, the live-region role and auto-hide behavior, then hands the renderer the message, endContent, resolved toast settings and a dismiss callback. The custom renderer owns every control in its layout: compose the control you want and call dismiss from it. Astryx does not inject a fallback close into custom content. Per-toast: an app shares one layout by wrapping useToast and passing it on every call, while a toast raised by library code that never passes it renders as an ordinary Astryx toast. The argument is {body, endContent, type, isAutoHide, autoHideDuration, dismiss}, where type is 'info' | 'error'.",
+        "Replaces the content of this toast's card with your own layout. Astryx keeps the card, its astryx-toast theme target and auto-hide behavior (inside a ToastViewport the viewport announces the toast, and while a modal hosts the viewport the card announces itself), then hands the renderer the message, endContent, resolved toast settings and a dismiss callback. The custom renderer owns every control in its layout: compose the control you want and call dismiss from it. Astryx does not inject a fallback close into custom content. Per-toast: an app shares one layout by wrapping useToast and passing it on every call, while a toast raised by library code that never passes it renders as an ordinary Astryx toast. The argument is {body, endContent, type, isAutoHide, autoHideDuration, dismiss}, where type is 'info' | 'error'.",
     },
   ],
   theming: {
@@ -211,7 +211,7 @@ export const docsZh = {
     collisionBehavior: '当已存在相同 uniqueID 的 toast 时的行为。',
     onHide: '当 toast 被移除时触发的回调。',
     renderContent:
-      "用你自己的布局替换该 toast 卡片内部的内容。Astryx 保留卡片本身、astryx-toast 主题目标、实时区域角色和自动关闭行为，并把消息、endContent、解析后的 toast 设置和 dismiss 回调交给渲染函数。自定义渲染函数完全拥有布局中的控件：请组合所需的控件并通过它调用 dismiss。Astryx 不会向自定义内容注入后备关闭按钮。按 toast 单独设置：应用可通过封装 useToast 并在每次调用时传入来共享同一套布局；而由库代码发起、从不传入该参数的 toast 会渲染为普通的 Astryx toast。传入参数为 {body, endContent, type, isAutoHide, autoHideDuration, dismiss}，其中 type 为 'info' | 'error'。",
+      "用你自己的布局替换该 toast 卡片内部的内容。Astryx 保留卡片本身、astryx-toast 主题目标和自动关闭行为（在 ToastViewport 中由视口播报该 toast；当模态框承载视口时由卡片自行播报），并把消息、endContent、解析后的 toast 设置和 dismiss 回调交给渲染函数。自定义渲染函数完全拥有布局中的控件：请组合所需的控件并通过它调用 dismiss。Astryx 不会向自定义内容注入后备关闭按钮。按 toast 单独设置：应用可通过封装 useToast 并在每次调用时传入来共享同一套布局；而由库代码发起、从不传入该参数的 toast 会渲染为普通的 Astryx toast。传入参数为 {body, endContent, type, isAutoHide, autoHideDuration, dismiss}，其中 type 为 'info' | 'error'。",
   },
   usage: {
     description:
@@ -328,6 +328,7 @@ export const docsDense = {
     uniqueID: 'unique id for dedup',
     collisionBehavior: 'behavior when matching uniqueID exists',
     onHide: 'callback when toast removed',
-    renderContent: 'custom inner layout; receives content, resolved settings + dismiss callback; no injected fallback control',
+    renderContent:
+      'custom inner layout; receives content, resolved settings + dismiss callback; no injected fallback control',
   },
 };

package/src/Toast/Toast.tsx

@@ -154,6 +154,16 @@ export interface ToastProps {
 
 interface ToastSurfaceProps extends ToastProps {
   gestureDirection: ToastGestureDirection;
+  /**
+   * Changes when a uniqueID overwrite updates this card in place: the new
+   * toast's auto-hide timer starts over.
+   */
+  timerKey?: string;
+  /**
+   * False when the viewport announces the toast: the card then carries no
+   * live region of its own, so an update in place is announced once.
+   */
+  isLiveRegion?: boolean;
 }
 
 /**
@@ -193,6 +203,8 @@ export function ToastSurface({
   onDismiss,
   renderContent,
   gestureDirection,
+  timerKey,
+  isLiveRegion = true,
 }: ToastSurfaceProps) {
   const t = useComponentTranslator();
   const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
@@ -226,34 +238,28 @@ export function ToastSurface({
     }, remainingRef.current);
   }, [isAutoHide]);
 
-  const pauseTimer = useCallback(
-    (source: PauseSource) => {
-      if (!isAutoHide) {
-        return;
-      }
-      const sources = pauseSourcesRef.current;
-      const wasRunning = sources.size === 0;
-      sources.add(source);
-      if (!wasRunning) {
-        return;
-      }
-      if (timerRef.current) {
-        clearTimeout(timerRef.current);
-        timerRef.current = null;
-      }
-      if (startTimeRef.current != null) {
-        const elapsed = Date.now() - startTimeRef.current;
-        remainingRef.current = Math.max(remainingRef.current - elapsed, 1000);
-      }
-    },
-    [isAutoHide],
-  );
+  // Pointer, focus and gesture holds are tracked whatever isAutoHide is: an
+  // overwrite can turn a toast that does not auto-hide into one that does
+  // while a hold is in place. The window hold leaves with its listeners.
+  const pauseTimer = useCallback((source: PauseSource) => {
+    const sources = pauseSourcesRef.current;
+    const wasRunning = sources.size === 0;
+    sources.add(source);
+    if (!wasRunning) {
+      return;
+    }
+    if (timerRef.current) {
+      clearTimeout(timerRef.current);
+      timerRef.current = null;
+    }
+    if (startTimeRef.current != null) {
+      const elapsed = Date.now() - startTimeRef.current;
+      remainingRef.current = Math.max(remainingRef.current - elapsed, 1000);
+    }
+  }, []);
 
   const resumeTimer = useCallback(
     (source: PauseSource) => {
-      if (!isAutoHide) {
-        return;
-      }
       const sources = pauseSourcesRef.current;
       if (!sources.delete(source)) {
         return;
@@ -271,20 +277,31 @@ export function ToastSurface({
       }
       startTimer();
     },
-    [isAutoHide, startTimer],
+    [startTimer],
   );
 
   useEffect(() => {
     remainingRef.current = autoHideDuration;
+    // An update in place can remove the focused control, which fires no blur:
+    // a focus hold whose focus has left the card is stale.
+    const root = cardRootRef.current?.current;
+    if (
+      pauseSourcesRef.current.has('focus') &&
+      root != null &&
+      !root.contains(root.ownerDocument.activeElement)
+    ) {
+      pauseSourcesRef.current.delete('focus');
+    }
     startTimer();
     return () => {
       if (timerRef.current) {
         clearTimeout(timerRef.current);
       }
     };
-    // startTimer's identity is stable per isAutoHide, so this runs on mount
-    // and on a genuine duration change — not on unrelated viewport renders.
-  }, [autoHideDuration, startTimer]);
+    // startTimer's identity is stable per isAutoHide, so this runs on mount,
+    // on a genuine duration change and on an overwrite (timerKey), not on
+    // unrelated viewport renders.
+  }, [autoHideDuration, startTimer, timerKey]);
 
   // Pause the auto-hide timer while the window is not focused, so a toast
   // doesn't silently expire while the user is in another window or tab.
@@ -292,6 +309,7 @@ export function ToastSurface({
     if (!isAutoHide) {
       return;
     }
+    const pauseSources = pauseSourcesRef.current;
     const pauseForWindow = () => pauseTimer('window');
     const resumeForWindow = () => resumeTimer('window');
     window.addEventListener('blur', pauseForWindow);
@@ -304,6 +322,8 @@ export function ToastSurface({
     return () => {
       window.removeEventListener('blur', pauseForWindow);
       window.removeEventListener('focus', resumeForWindow);
+      // With the listeners gone, no focus event would clear the window hold.
+      pauseSources.delete('window');
     };
   }, [isAutoHide, pauseTimer, resumeTimer]);
 
@@ -368,9 +388,9 @@ export function ToastSurface({
   return (
     <div
       ref={rootRef}
-      role={isError ? 'alert' : 'status'}
-      aria-live={isError ? 'assertive' : 'polite'}
-      aria-atomic="true"
+      role={isLiveRegion ? (isError ? 'alert' : 'status') : undefined}
+      aria-live={isLiveRegion ? (isError ? 'assertive' : 'polite') : undefined}
+      aria-atomic={isLiveRegion ? 'true' : undefined}
       onMouseEnter={pauseForPointer}
       onMouseLeave={resumeForPointer}
       onFocusCapture={pauseForFocus}