@astryxdesign/core 0.6.2 → 0.6.3-canary.0788c49

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',

package/src/ToggleButton/ToggleButton.test.tsx

@@ -3,7 +3,8 @@
 /**
  * @file ToggleButton.test.tsx
  * @input Uses vitest, @testing-library/react, ToggleButton, ToggleButtonGroup
- * @output Unit tests for ToggleButton and ToggleButtonGroup
+ * @output Unit tests for ToggleButton callback/Action order, pending state,
+ *   group-owned selection, and ToggleButtonGroup
  *
  * SYNC: When ToggleButton.tsx or ToggleButtonGroup.tsx changes, update tests
  */
@@ -388,8 +389,94 @@ describe('ToggleButton', () => {
     expect(pressedChangeAction).toHaveBeenCalledWith(true);
   });
 
+  it('runs the synchronous callback before the Action with the same next state', async () => {
+    const calls: string[] = [];
+    const pressedChangeAction = vi.fn(() => {
+      calls.push('action');
+    });
+    const onPressedChange = vi.fn(() => {
+      expect(pressedChangeAction).not.toHaveBeenCalled();
+      calls.push('change');
+    });
+    render(
+      <ToggleButton
+        label="Favorite"
+        isPressed={false}
+        onPressedChange={onPressedChange}
+        pressedChangeAction={pressedChangeAction}
+      />,
+    );
+
+    await userEvent.setup().click(screen.getByRole('button'));
+
+    expect(calls).toEqual(['change', 'action']);
+    expect(onPressedChange).toHaveBeenCalledExactlyOnceWith(
+      true,
+      expect.anything(),
+    );
+    expect(pressedChangeAction).toHaveBeenCalledExactlyOnceWith(true);
+  });
+
+  it('keeps callback-only controlled toggles synchronous without pending feedback', async () => {
+    function LegacyToggle() {
+      const [isPressed, setIsPressed] = useState(false);
+      return (
+        <ToggleButton
+          label="Bold"
+          isPressed={isPressed}
+          onPressedChange={setIsPressed}
+        />
+      );
+    }
+    render(<LegacyToggle />);
+    const button = screen.getByRole('button');
+
+    fireEvent.click(button);
+    expect(button).toHaveAttribute('aria-pressed', 'true');
+    expect(button).not.toHaveAttribute('aria-busy', 'true');
+    fireEvent.click(button);
+    expect(button).toHaveAttribute('aria-pressed', 'false');
+    expect(button).not.toHaveAttribute('aria-busy', 'true');
+    await act(async () => {});
+  });
+
+  it('runs an Action without onPressedChange and settles to the controlled value', async () => {
+    let resolveAction: (() => void) | undefined;
+    const pressedChangeAction = vi.fn(
+      async () =>
+        new Promise<void>(resolve => {
+          resolveAction = resolve;
+        }),
+    );
+    const {rerender} = render(
+      <ToggleButton
+        label="Favorite"
+        isPressed={false}
+        pressedChangeAction={pressedChangeAction}
+      />,
+    );
+    const button = screen.getByRole('button');
+
+    await userEvent.setup().click(button);
+    expect(pressedChangeAction).toHaveBeenCalledExactlyOnceWith(true);
+    expect(button).toHaveAttribute('aria-pressed', 'true');
+    expect(button).toHaveAttribute('aria-busy', 'true');
+    await act(async () => resolveAction?.());
+    expect(button).toHaveAttribute('aria-pressed', 'false');
+    expect(button).not.toHaveAttribute('aria-busy', 'true');
+
+    rerender(
+      <ToggleButton
+        label="Favorite"
+        isPressed
+        pressedChangeAction={pressedChangeAction}
+      />,
+    );
+    expect(button).toHaveAttribute('aria-pressed', 'true');
+    expect(pressedChangeAction).toHaveBeenCalledTimes(1);
+  });
+
   it('skips pressedChangeAction when onPressedChange calls preventDefault', async () => {
-    const user = userEvent.setup();
     const pressedChangeAction = vi.fn();
     const onPressedChange = vi.fn(
       (_next: boolean, event: MouseEvent<HTMLButtonElement>) => {
@@ -406,10 +493,17 @@ describe('ToggleButton', () => {
       />,
     );
 
-    await user.click(screen.getByRole('button', {name: 'Favorite'}));
+    const button = screen.getByRole('button', {name: 'Favorite'});
+    fireEvent.click(button);
 
-    expect(onPressedChange).toHaveBeenCalledWith(true, expect.anything());
+    expect(onPressedChange).toHaveBeenCalledExactlyOnceWith(
+      true,
+      expect.anything(),
+    );
     expect(pressedChangeAction).not.toHaveBeenCalled();
+    expect(button).toHaveAttribute('aria-pressed', 'false');
+    expect(button).not.toHaveAttribute('aria-busy', 'true');
+    await act(async () => {});
   });
 });
 
@@ -570,6 +664,207 @@ describe('ToggleButtonGroup (multiple)', () => {
   });
 });
 
+// =============================================================================
+// Group ownership — member Actions must not compete with controlled selection
+// =============================================================================
+
+describe.each(['single', 'multiple'] as const)(
+  'ToggleButtonGroup (%s) ownership',
+  type => {
+    it('keeps selection group-owned even when a member has standalone handlers', async () => {
+      const onChange = vi.fn();
+      const onPressedChange = vi.fn();
+      const pressedChangeAction = vi.fn();
+      const groupProps =
+        type === 'single'
+          ? {type, value: 'list', onChange}
+          : {type, value: ['list'], onChange};
+      const children = (
+        <>
+          <ToggleButton value="list" label="List" isPressed={false} />
+          <ToggleButton
+            value="grid"
+            label="Grid"
+            isPressed
+            onPressedChange={onPressedChange}
+            pressedChangeAction={pressedChangeAction}
+          />
+        </>
+      );
+      const {rerender} = render(
+        <ToggleButtonGroup {...groupProps} label="View">
+          {children}
+        </ToggleButtonGroup>,
+      );
+      const grid = screen.getByRole('button', {name: 'Grid'});
+      expect(grid).toHaveAttribute('aria-pressed', 'false');
+      expect(screen.getByRole('button', {name: 'List'})).toHaveAttribute(
+        'aria-pressed',
+        'true',
+      );
+
+      await userEvent.setup().click(grid);
+      expect(onChange).toHaveBeenCalledExactlyOnceWith(
+        type === 'single' ? 'grid' : ['list', 'grid'],
+      );
+      expect(onPressedChange).not.toHaveBeenCalled();
+      expect(pressedChangeAction).not.toHaveBeenCalled();
+      expect(grid).toHaveAttribute('aria-pressed', 'false');
+      expect(grid).not.toHaveAttribute('aria-busy', 'true');
+
+      const acceptedProps =
+        type === 'single'
+          ? {type, value: 'grid', onChange}
+          : {type, value: ['list', 'grid'], onChange};
+      rerender(
+        <ToggleButtonGroup {...acceptedProps} label="View">
+          {children}
+        </ToggleButtonGroup>,
+      );
+      expect(grid).toHaveAttribute('aria-pressed', 'true');
+      await userEvent.setup().click(grid);
+      expect(onChange).toHaveBeenLastCalledWith(
+        type === 'single' ? null : ['list'],
+      );
+      expect(onPressedChange).not.toHaveBeenCalled();
+      expect(pressedChangeAction).not.toHaveBeenCalled();
+    });
+  },
+);
+
+// =============================================================================
+// Disabled state — family:buttons FR3 (disabled means non-operable)
+// =============================================================================
+
+/**
+ * Two ways a ToggleButton becomes unavailable, and the rule that binds them:
+ * a group disables everything it contains, and a member can disable itself
+ * while the group stays enabled. Neither source may cancel the other out.
+ *
+ * The tooltip cases are here at the attribute and callback level only. A
+ * tooltip'd disabled toggle carries `aria-disabled` instead of the native
+ * `disabled` attribute, so whether a REAL mouse press is refused is an engine
+ * fact that jsdom's synthetic click cannot settle — that half lives in
+ * ./__tests__/ToggleButton.a11y.chromium.spec.ts.
+ */
+describe('disabled state', () => {
+  it('keeps a member disabled when the group disables nothing', async () => {
+    const user = userEvent.setup();
+    const handleChange = vi.fn();
+    render(
+      <ToggleButtonGroup value={null} onChange={handleChange} label="View mode">
+        <ToggleButton value="list" label="List" isDisabled />
+        <ToggleButton value="grid" label="Grid" />
+      </ToggleButtonGroup>,
+    );
+
+    expect(screen.getByRole('button', {name: 'List'})).toBeDisabled();
+
+    await user.click(screen.getByRole('button', {name: 'List'}));
+    expect(handleChange).not.toHaveBeenCalled();
+  });
+
+  it('leaves the rest of an enabled group selectable', async () => {
+    const user = userEvent.setup();
+    const handleChange = vi.fn();
+    render(
+      <ToggleButtonGroup value={null} onChange={handleChange} label="View mode">
+        <ToggleButton value="list" label="List" isDisabled />
+        <ToggleButton value="grid" label="Grid" />
+      </ToggleButtonGroup>,
+    );
+
+    expect(screen.getByRole('button', {name: 'Grid'})).toBeEnabled();
+
+    await user.click(screen.getByRole('button', {name: 'Grid'}));
+    expect(handleChange).toHaveBeenCalledWith('grid');
+  });
+
+  it('still disables a member that says nothing when the group is disabled', async () => {
+    const user = userEvent.setup();
+    const handleChange = vi.fn();
+    render(
+      <ToggleButtonGroup
+        value={null}
+        onChange={handleChange}
+        label="View mode"
+        isDisabled>
+        <ToggleButton value="list" label="List" />
+      </ToggleButtonGroup>,
+    );
+
+    expect(screen.getByRole('button', {name: 'List'})).toBeDisabled();
+
+    await user.click(screen.getByRole('button', {name: 'List'}));
+    expect(handleChange).not.toHaveBeenCalled();
+  });
+
+  it('keeps a tooltip-bearing disabled member focusable but inert', async () => {
+    const user = userEvent.setup();
+    const handleChange = vi.fn();
+    render(
+      <ToggleButtonGroup value={null} onChange={handleChange} label="View mode">
+        <ToggleButton
+          value="list"
+          label="List"
+          tooltip="List view is unavailable for this dataset"
+          isDisabled
+        />
+      </ToggleButtonGroup>,
+    );
+
+    const member = screen.getByRole('button', {name: 'List'});
+    // The tooltip is the disabled reason, so the control stays reachable to
+    // read it: aria-disabled rather than the native attribute, which would
+    // take it out of the tab order along with its own explanation.
+    expect(member).toHaveAttribute('aria-disabled', 'true');
+    expect(member).not.toBeDisabled();
+
+    await user.click(member);
+    expect(handleChange).not.toHaveBeenCalled();
+  });
+
+  it('does not toggle a standalone disabled toggle that carries a tooltip', async () => {
+    const user = userEvent.setup();
+    const handleChange = vi.fn();
+    render(
+      <ToggleButton
+        label="Bold"
+        tooltip="Formatting is locked for this document"
+        isPressed={false}
+        onPressedChange={handleChange}
+        isDisabled
+      />,
+    );
+
+    const toggle = screen.getByRole('button', {name: 'Bold'});
+    expect(toggle).toHaveAttribute('aria-disabled', 'true');
+
+    await user.click(toggle);
+    expect(handleChange).not.toHaveBeenCalled();
+    expect(toggle).toHaveAttribute('aria-pressed', 'false');
+  });
+
+  it('still toggles an enabled toggle that carries the same tooltip', async () => {
+    const user = userEvent.setup();
+    const handleChange = vi.fn();
+    render(
+      <ToggleButton
+        label="Bold"
+        tooltip="Bold the selected text"
+        isPressed={false}
+        onPressedChange={handleChange}
+      />,
+    );
+
+    const toggle = screen.getByRole('button', {name: 'Bold'});
+    expect(toggle).not.toHaveAttribute('aria-disabled');
+
+    await user.click(toggle);
+    expect(handleChange).toHaveBeenCalledWith(true, expect.anything());
+  });
+});
+
 // jsdom cannot emulate forced-colors rendering, so these assert that the
 // compiled output includes the forced-colors rules; visual behavior needs
 // manual verification under Windows High Contrast.