@astryxdesign/core 0.6.2 → 0.6.3-canary.0899f21

package/src/Timer/Timer.test.tsx

@@ -0,0 +1,302 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Timer.test.tsx
+ * @input Uses React Testing Library, fake clocks, React Profiler, and Timer
+ * @output Verifies formats, adaptive cadence, render isolation, typography, resources, semantics, and passthrough
+ */
+
+import {Profiler, StrictMode, createRef} from 'react';
+import {renderToString} from 'react-dom/server';
+import {act, fireEvent, render, screen} from '@testing-library/react';
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
+import {Timer} from './Timer';
+
+describe('Timer', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date('2026-09-22T00:00:00Z'));
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  it('renders deterministic zero-duration markup for each standard format', () => {
+    const {rerender} = render(<Timer data-testid="timer" />);
+    const timer = screen.getByTestId('timer');
+
+    expect(timer.tagName).toBe('TIME');
+    expect(timer).toHaveTextContent('0s');
+    expect(timer).toHaveAttribute('datetime', 'PT0S');
+
+    rerender(<Timer format="clock" data-testid="timer" />);
+    expect(timer).toHaveTextContent('0:00');
+    expect(timer).toHaveAttribute('datetime', 'PT0S');
+  });
+
+  it('keeps server markup independent of the clock', () => {
+    const firstMarkup = renderToString(<Timer startTime={0} />);
+    const firstClockMarkup = renderToString(
+      <Timer startTime={0} format="clock" />,
+    );
+
+    vi.setSystemTime(new Date('2030-01-01T00:00:00Z'));
+    const secondMarkup = renderToString(<Timer startTime={0} />);
+    const secondClockMarkup = renderToString(
+      <Timer startTime={0} format="clock" />,
+    );
+
+    expect(firstMarkup).toBe(secondMarkup);
+    expect(firstMarkup).toContain('dateTime="PT0S"');
+    expect(firstMarkup).toContain('>0s</time>');
+    expect(firstClockMarkup).toBe(secondClockMarkup);
+    expect(firstClockMarkup).toContain('>0:00</time>');
+  });
+
+  it('derives elapsed time from the clock without accumulating callback count', () => {
+    let scheduledTick: (() => void) | undefined;
+    vi.spyOn(globalThis, 'setTimeout').mockImplementation(callback => {
+      scheduledTick = callback as () => void;
+      return 1 as unknown as ReturnType<typeof setTimeout>;
+    });
+
+    render(<Timer data-testid="timer" />);
+
+    vi.setSystemTime(new Date('2026-09-22T00:00:08.750Z'));
+    act(() => {
+      scheduledTick?.();
+    });
+
+    const timer = screen.getByTestId('timer');
+    expect(timer).toHaveTextContent('8s');
+    expect(timer).toHaveAttribute('datetime', 'PT8S');
+  });
+
+  it('formats elapsed durations across seconds, minutes, and hours', () => {
+    const now = Date.now();
+    const {rerender} = render(
+      <Timer startTime={now - 34_000} data-testid="timer" />,
+    );
+    const timer = screen.getByTestId('timer');
+    expect(timer).toHaveTextContent('34s');
+    expect(timer).toHaveAttribute('datetime', 'PT34S');
+
+    rerender(<Timer startTime={now - 128_000} data-testid="timer" />);
+    expect(timer).toHaveTextContent('2m 08s');
+    expect(timer).toHaveAttribute('datetime', 'PT128S');
+
+    rerender(<Timer startTime={now - 3_753_000} data-testid="timer" />);
+    expect(timer).toHaveTextContent('1h 02m');
+    expect(timer).toHaveAttribute('datetime', 'PT3720S');
+  });
+
+  it('formats clock durations across minutes and hours', () => {
+    const now = Date.now();
+    const {rerender} = render(
+      <Timer format="clock" startTime={now - 128_000} data-testid="timer" />,
+    );
+    const timer = screen.getByTestId('timer');
+    expect(timer).toHaveTextContent('2:08');
+    expect(timer).toHaveAttribute('datetime', 'PT128S');
+
+    rerender(
+      <Timer format="clock" startTime={now - 3_753_000} data-testid="timer" />,
+    );
+    expect(timer).toHaveTextContent('1:02:33');
+    expect(timer).toHaveAttribute('datetime', 'PT3753S');
+  });
+
+  it('uses second cadence until elapsed format reaches an hour, then minute cadence', () => {
+    const setTimeoutSpy = vi.spyOn(globalThis, 'setTimeout');
+    const startTime = Date.now() - 3_599_000;
+    render(<Timer startTime={startTime} data-testid="timer" />);
+    const timer = screen.getByTestId('timer');
+
+    expect(timer).toHaveTextContent('59m 59s');
+    expect(setTimeoutSpy).toHaveBeenLastCalledWith(expect.any(Function), 1000);
+
+    act(() => {
+      vi.advanceTimersByTime(1000);
+    });
+    expect(timer).toHaveTextContent('1h 00m');
+    expect(timer).toHaveAttribute('datetime', 'PT3600S');
+    expect(setTimeoutSpy).toHaveBeenLastCalledWith(
+      expect.any(Function),
+      60_000,
+    );
+  });
+
+  it('keeps clock format on second cadence after an hour', () => {
+    const setTimeoutSpy = vi.spyOn(globalThis, 'setTimeout');
+    render(
+      <Timer
+        format="clock"
+        startTime={Date.now() - 3_723_000}
+        data-testid="timer"
+      />,
+    );
+
+    expect(screen.getByTestId('timer')).toHaveTextContent('1:02:03');
+    expect(setTimeoutSpy).toHaveBeenLastCalledWith(expect.any(Function), 1000);
+  });
+
+  it('counts from a finite caller-provided start time', () => {
+    const now = Date.now();
+    render(<Timer startTime={now - 12_400} data-testid="timer" />);
+
+    expect(screen.getByTestId('timer')).toHaveTextContent('12s');
+    expect(screen.getByTestId('timer')).toHaveAttribute('datetime', 'PT12S');
+  });
+
+  it('returns to the original mount origin when startTime is removed', () => {
+    const mountedAt = Date.now();
+    const {rerender} = render(
+      <Timer startTime={mountedAt - 10_000} data-testid="timer" />,
+    );
+
+    act(() => {
+      vi.advanceTimersByTime(2000);
+    });
+    rerender(<Timer data-testid="timer" />);
+
+    expect(screen.getByTestId('timer')).toHaveTextContent('2s');
+    expect(screen.getByTestId('timer')).toHaveAttribute('datetime', 'PT2S');
+  });
+
+  it('falls back to mount time for a non-finite start time', () => {
+    render(<Timer startTime={Number.NaN} data-testid="timer" />);
+
+    act(() => {
+      vi.advanceTimersByTime(2000);
+    });
+
+    expect(screen.getByTestId('timer')).toHaveTextContent('2s');
+  });
+
+  it('clamps a future origin to zero and schedules its first visible change directly', () => {
+    const setTimeoutSpy = vi.spyOn(globalThis, 'setTimeout');
+    render(<Timer startTime={Date.now() + 5000} data-testid="timer" />);
+
+    expect(screen.getByTestId('timer')).toHaveTextContent('0s');
+    expect(screen.getByTestId('timer')).toHaveAttribute('datetime', 'PT0S');
+    expect(setTimeoutSpy).toHaveBeenLastCalledWith(expect.any(Function), 6000);
+
+    act(() => {
+      vi.advanceTimersByTime(6000);
+    });
+
+    expect(screen.getByTestId('timer')).toHaveTextContent('1s');
+    expect(screen.getByTestId('timer')).toHaveAttribute('datetime', 'PT1S');
+  });
+
+  it('updates format without remounting or losing current elapsed time', () => {
+    const now = Date.now();
+    const {rerender} = render(
+      <Timer startTime={now - 3_723_000} data-testid="timer" />,
+    );
+    const timer = screen.getByTestId('timer');
+    expect(timer).toHaveTextContent('1h 02m');
+    expect(timer).toHaveAttribute('datetime', 'PT3720S');
+
+    rerender(
+      <Timer format="clock" startTime={now - 3_723_000} data-testid="timer" />,
+    );
+    expect(screen.getByTestId('timer')).toBe(timer);
+    expect(timer).toHaveTextContent('1:02:03');
+    expect(timer).toHaveAttribute('datetime', 'PT3723S');
+  });
+
+  it('does not schedule React update commits as time advances', () => {
+    const onRender = vi.fn();
+    render(
+      <Profiler id="timer" onRender={onRender}>
+        <Timer />
+      </Profiler>,
+    );
+    expect(onRender).toHaveBeenCalledTimes(1);
+
+    act(() => {
+      vi.advanceTimersByTime(5000);
+    });
+
+    expect(onRender).toHaveBeenCalledTimes(1);
+  });
+
+  it('owns one timer resource and cleans up under StrictMode replay', () => {
+    const setTimeoutSpy = vi.spyOn(window, 'setTimeout');
+    const clearTimeoutSpy = vi.spyOn(window, 'clearTimeout');
+    const {unmount} = render(
+      <StrictMode>
+        <Timer />
+      </StrictMode>,
+    );
+
+    expect(setTimeoutSpy).toHaveBeenCalledTimes(2);
+    expect(clearTimeoutSpy).toHaveBeenCalledTimes(1);
+
+    unmount();
+    expect(clearTimeoutSpy).toHaveBeenCalledTimes(2);
+  });
+
+  it('matches Timestamp typography defaults and accepts overrides', () => {
+    const {rerender} = render(<Timer data-testid="timer" />);
+    const timer = screen.getByTestId('timer');
+    const text = timer.parentElement;
+
+    expect(text).toHaveClass('astryx-text');
+    expect(text).toHaveClass('astryx-timer');
+    expect(text).toHaveAttribute('data-type', 'supporting');
+    expect(text).toHaveAttribute('data-color', 'secondary');
+
+    rerender(
+      <Timer
+        type="body"
+        size="lg"
+        color="primary"
+        weight="bold"
+        data-testid="timer"
+      />,
+    );
+    expect(text).toHaveAttribute('data-type', 'body');
+    expect(text).toHaveAttribute('data-size', 'lg');
+    expect(text).toHaveAttribute('data-color', 'primary');
+  });
+
+  it('forwards its time ref and preserves Timestamp-style root styling and time props', () => {
+    const ref = createRef<HTMLTimeElement>();
+    const onClick = vi.fn();
+    render(
+      <Timer
+        ref={ref}
+        id="elapsed"
+        className="custom-class"
+        style={{color: 'rgb(1, 2, 3)'}}
+        aria-live="polite"
+        onClick={onClick}
+        data-testid="timer"
+      />,
+    );
+
+    const timer = screen.getByTestId('timer');
+    const text = timer.parentElement;
+    expect(ref.current).toBe(timer);
+    expect(timer).toHaveAttribute('id', 'elapsed');
+    expect(text).toHaveClass('astryx-timer');
+    expect(text).toHaveClass('custom-class');
+    expect(text).toHaveStyle({color: 'rgb(1, 2, 3)'});
+    expect(timer).toHaveAttribute('aria-live', 'polite');
+
+    fireEvent.click(timer);
+    expect(onClick).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not add live-region semantics by default', () => {
+    render(<Timer data-testid="timer" />);
+    const timer = screen.getByTestId('timer');
+
+    expect(timer).not.toHaveAttribute('aria-live');
+    expect(timer).not.toHaveAttribute('role');
+  });
+});

package/src/Timer/Timer.tsx

@@ -0,0 +1,258 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file Timer.tsx
+ * @input Uses an optional start time, standardized format, Timestamp typography, BaseProps, and React ref
+ * @output Exports Timer, TimerProps, and TimerFormat with non-rendering elapsed-time updates
+ * @position Core content primitive for elapsed duration in active operations
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/Timer/Timer.spec.md
+ * - /packages/core/src/Timer/Timer.doc.mjs
+ * - /packages/core/src/Timer/Timer.test.tsx
+ * - /packages/core/src/Timer/index.ts
+ * - /apps/storybook/stories/Timer.stories.tsx
+ * - /packages/cli/assets/templates/blocks/components/Timer/
+ */
+
+import {useEffect, useRef, useState} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import type {BaseProps} from '../BaseProps';
+import {useMergedRefs} from '../hooks/useMergedRefs';
+import {Text} from '../Text';
+import type {TextColor, TextSize, TextType, TextWeight} from '../theme/types';
+import {mergeProps} from '../utils';
+import {themeProps} from '../utils/themeProps';
+
+const ONE_SECOND_MS = 1000;
+const ONE_MINUTE_MS = 60 * ONE_SECOND_MS;
+const ONE_HOUR_SECONDS = 60 * 60;
+const MAX_TIMEOUT_MS = 2_147_483_647;
+
+const styles = stylex.create({
+  time: {
+    color: 'inherit',
+    display: 'inline',
+    fontFamily: 'inherit',
+    fontSize: 'inherit',
+    fontStyle: 'normal',
+    fontVariantNumeric: 'tabular-nums',
+    fontWeight: 'inherit',
+    lineHeight: 'inherit',
+  },
+});
+
+export type TimerFormat = 'elapsed' | 'clock';
+
+type TimerPresentation = {
+  dateTime: string;
+  text: string;
+};
+
+function pad(value: number): string {
+  return String(value).padStart(2, '0');
+}
+
+function resolveFormat(format: TimerFormat): TimerFormat {
+  return format === 'clock' ? 'clock' : 'elapsed';
+}
+
+function getElapsedMilliseconds(now: number, startTime: number): number {
+  return Math.max(0, now - startTime);
+}
+
+function getPresentation(
+  elapsedMilliseconds: number,
+  format: TimerFormat,
+): TimerPresentation {
+  const elapsedSeconds = Math.floor(elapsedMilliseconds / ONE_SECOND_MS);
+
+  if (format === 'clock') {
+    const hours = Math.floor(elapsedSeconds / ONE_HOUR_SECONDS);
+    const minutes = Math.floor((elapsedSeconds % ONE_HOUR_SECONDS) / 60);
+    const seconds = elapsedSeconds % 60;
+    return {
+      dateTime: `PT${elapsedSeconds}S`,
+      text:
+        hours > 0
+          ? `${String(hours)}:${pad(minutes)}:${pad(seconds)}`
+          : `${String(minutes)}:${pad(seconds)}`,
+    };
+  }
+
+  if (elapsedSeconds < 60) {
+    return {
+      dateTime: `PT${elapsedSeconds}S`,
+      text: `${String(elapsedSeconds)}s`,
+    };
+  }
+
+  const totalMinutes = Math.floor(elapsedSeconds / 60);
+  if (totalMinutes < 60) {
+    return {
+      dateTime: `PT${elapsedSeconds}S`,
+      text: `${String(totalMinutes)}m ${pad(elapsedSeconds % 60)}s`,
+    };
+  }
+
+  const representedSeconds = totalMinutes * 60;
+  return {
+    dateTime: `PT${representedSeconds}S`,
+    text: `${String(Math.floor(totalMinutes / 60))}h ${pad(totalMinutes % 60)}m`,
+  };
+}
+
+function getMillisecondsUntilNextChange(
+  now: number,
+  startTime: number,
+  elapsedMilliseconds: number,
+  format: TimerFormat,
+): number {
+  if (now < startTime) {
+    return Math.min(startTime - now + ONE_SECOND_MS, MAX_TIMEOUT_MS);
+  }
+
+  const precision =
+    format === 'elapsed' &&
+    elapsedMilliseconds >= ONE_HOUR_SECONDS * ONE_SECOND_MS
+      ? ONE_MINUTE_MS
+      : ONE_SECOND_MS;
+  return precision - (elapsedMilliseconds % precision);
+}
+
+export interface TimerProps extends Omit<
+  BaseProps<HTMLTimeElement>,
+  'dateTime'
+> {
+  /** Ref forwarded to the rendered `<time>` element. */
+  ref?: React.Ref<HTMLTimeElement>;
+  /**
+   * Unix time in milliseconds when the measured operation began. Omit it to
+   * start counting from this Timer's mount.
+   */
+  startTime?: number;
+  /**
+   * Standard duration representation.
+   * @default 'elapsed'
+   */
+  format?: TimerFormat;
+  /**
+   * Semantic text type. Matches Timestamp typography behavior.
+   * @default 'supporting'
+   */
+  type?: TextType;
+  /** Explicit font size override. Overrides the size from `type`. */
+  size?: TextSize;
+  /**
+   * Text color.
+   * @default 'secondary'
+   */
+  color?: TextColor;
+  /** Font weight override. */
+  weight?: TextWeight;
+}
+
+/**
+ * Displays a standardized elapsed duration without scheduling React tick renders.
+ *
+ * Timer writes changing text and its ISO 8601 duration directly to the owned
+ * `<time>` node. Use `elapsed` for compact duration text or `clock` for a
+ * stopwatch-like reading.
+ *
+ * @example
+ * ```
+ * <Timer />
+ * <Timer format="clock" />
+ * ```
+ */
+export function Timer({
+  startTime,
+  format = 'elapsed',
+  type = 'supporting',
+  size,
+  color = 'secondary',
+  weight,
+  ref,
+  xstyle,
+  className,
+  style,
+  ...rest
+}: TimerProps) {
+  const [mountTime] = useState(() => Date.now());
+  const timerRef = useRef<HTMLTimeElement>(null);
+  const mergedRef = useMergedRefs(ref, timerRef);
+  const resolvedFormat = resolveFormat(format);
+  const initialPresentation = getPresentation(0, resolvedFormat);
+
+  useEffect(() => {
+    const resolvedStartTime =
+      startTime !== undefined && Number.isFinite(startTime)
+        ? startTime
+        : mountTime;
+    let timeoutID: ReturnType<typeof setTimeout> | undefined;
+    let previousDateTime: string | undefined;
+    let previousText: string | undefined;
+
+    const tick = () => {
+      const now = Date.now();
+      const elapsedMilliseconds = getElapsedMilliseconds(
+        now,
+        resolvedStartTime,
+      );
+      const presentation = getPresentation(elapsedMilliseconds, resolvedFormat);
+      const node = timerRef.current;
+
+      if (node != null) {
+        if (presentation.text !== previousText) {
+          node.textContent = presentation.text;
+          previousText = presentation.text;
+        }
+        if (presentation.dateTime !== previousDateTime) {
+          node.dateTime = presentation.dateTime;
+          previousDateTime = presentation.dateTime;
+        }
+      }
+
+      timeoutID = setTimeout(
+        tick,
+        getMillisecondsUntilNextChange(
+          now,
+          resolvedStartTime,
+          elapsedMilliseconds,
+          resolvedFormat,
+        ),
+      );
+    };
+
+    tick();
+    return () => {
+      if (timeoutID !== undefined) {
+        clearTimeout(timeoutID);
+      }
+    };
+  }, [mountTime, resolvedFormat, startTime]);
+
+  const timerProps = mergeProps(themeProps('timer'), {className, style});
+
+  return (
+    <Text
+      type={type}
+      size={size}
+      color={color}
+      weight={weight}
+      xstyle={xstyle}
+      {...timerProps}>
+      <time
+        {...rest}
+        ref={mergedRef}
+        dateTime="PT0S"
+        {...stylex.props(styles.time)}>
+        {initialPresentation.text}
+      </time>
+    </Text>
+  );
+}
+
+Timer.displayName = 'Timer';

package/src/Timer/index.ts

@@ -0,0 +1,11 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file index.ts
+ * @input Imports Timer, TimerProps, and TimerFormat
+ * @output Public Timer component barrel
+ * @position Component subpath entry point for @astryxdesign/core/Timer
+ */
+
+export {Timer} from './Timer';
+export type {TimerFormat, TimerProps} from './Timer';

package/src/ToggleButton/ToggleButton.doc.mjs

@@ -31,17 +31,17 @@ export const docs = {
     {
       name: 'isPressed',
       type: 'boolean',
-      description: 'Whether the button is currently pressed. Ignored when inside a group.',
+      description: 'Whether the button is currently pressed. Ignored for a ToggleButtonGroup member with a value.',
     },
     {
       name: 'onPressedChange',
       type: '(isPressed: boolean, event: MouseEvent) => void',
-      description: 'Called when pressed state should change. Receives the next state and the click event; call event.preventDefault() to skip pressedChangeAction. Ignored when inside a group.',
+      description: 'Called synchronously when pressed state should change. Receives the next state and the click event; call event.preventDefault() to skip pressedChangeAction. Without an Action, the callback produces no Action-pending feedback. Ignored for a ToggleButtonGroup member with a value.',
     },
     {
       name: 'pressedChangeAction',
       type: '(isPressed: boolean) => void | Promise<void>',
-      description: 'Action handler for API- or navigation-backed toggles, run in a transition. Shows an optimistic pressed state immediately and a spinner while pending; the button stays interruptible by re-clicks.',
+      description: 'Action handler for API- or navigation-backed toggles, run in a transition after the synchronous onPressedChange callback unless that callback calls event.preventDefault(). Works without onPressedChange. Shows an optimistic pressed state and a spinner while pending, and remains interruptible by re-clicks. Omit it for callback-only toggles with no Action-pending feedback. Ignored for a ToggleButtonGroup member with a value.',
     },
     {
       name: 'size',