@astryxdesign/core 0.6.3-canary.f22695a → 0.6.3

package/src/Timer/Timer.tsx

@@ -1,258 +0,0 @@
-// 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

@@ -1,11 +0,0 @@
-// 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/hooks/useClickableContainer.test.tsx

@@ -1,236 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file useClickableContainer.test.tsx
- * @input Uses vitest, @testing-library/react, useClickableContainer
- * @output Unit tests for the hook's navigation paths
- * @position Testing; pins the shared navigation-destination rule on every
- *   activation method the hook owns — plain click (location.href), new tab
- *   (target="_blank"), Cmd/Ctrl-click, middle-click, and the delegated click
- *   on the interactive ref. None of these pass through React DOM's own href
- *   vetting, so each one has a positive and a blocked case here.
- */
-
-import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
-import {useRef} from 'react';
-import {fireEvent, render, screen} from '@testing-library/react';
-import {useClickableContainer} from './useClickableContainer';
-
-// The scheme the rule exists to stop (kept in consts so the JSX below stays
-// lint-clean — the tests are ABOUT these URLs never navigating).
-const scriptUrl = 'javascript:alert(1)';
-// The same scheme hidden behind a control character a browser ignores.
-const hiddenScriptUrl = 'java\nscript:alert(1)';
-
-function Card({href, target}: {href: string; target?: string}) {
-  const containerRef = useRef<HTMLDivElement>(null);
-  const {onClick, onMouseUp} = useClickableContainer({
-    containerRef,
-    href,
-    target,
-  });
-  return (
-    <div
-      ref={containerRef}
-      data-testid="card"
-      onClick={onClick}
-      onMouseUp={onMouseUp}>
-      content
-    </div>
-  );
-}
-
-/**
- * Card that delegates plain clicks to an inner link (the ClickableCard /
- * Item shape). The inner anchor's own click is spied on so the test observes
- * whether the hook activated it.
- */
-function DelegatingCard({
-  href,
-  onAnchorClick,
-}: {
-  href: string;
-  onAnchorClick: () => void;
-}) {
-  const containerRef = useRef<HTMLDivElement>(null);
-  const interactiveRef = useRef<HTMLAnchorElement>(null);
-  const {onClick, onMouseUp} = useClickableContainer({
-    containerRef,
-    interactiveRef,
-    href,
-  });
-  return (
-    <div
-      ref={containerRef}
-      data-testid="card"
-      onClick={onClick}
-      onMouseUp={onMouseUp}>
-      content
-      <a
-        ref={interactiveRef}
-        // The anchor is the delegate, not the subject: the tests below use a
-        // fixed inert href here so that only the hook's decision is observed.
-        href="#inner"
-        data-testid="inner-link"
-        onClick={e => {
-          e.preventDefault();
-          onAnchorClick();
-        }}>
-        inner
-      </a>
-    </div>
-  );
-}
-
-afterEach(() => {
-  vi.restoreAllMocks();
-  vi.unstubAllGlobals();
-});
-
-describe('useClickableContainer navigation — new tab (target="_blank")', () => {
-  it('opens ordinary hrefs in a new tab', () => {
-    const open = vi.spyOn(window, 'open').mockImplementation(() => null);
-    render(<Card href="https://example.com/docs" target="_blank" />);
-    fireEvent.click(screen.getByTestId('card'));
-    expect(open).toHaveBeenCalledWith(
-      'https://example.com/docs',
-      '_blank',
-      'noopener',
-    );
-  });
-
-  it('does not open a script-scheme href in a new tab', () => {
-    const open = vi.spyOn(window, 'open').mockImplementation(() => null);
-    // eslint-disable-next-line @eslint-react/dom-no-script-url -- the test proves this URL never navigates
-    render(<Card href={scriptUrl} target="_blank" />);
-    fireEvent.click(screen.getByTestId('card'));
-    expect(open).not.toHaveBeenCalled();
-  });
-});
-
-describe('useClickableContainer navigation — Cmd/Ctrl-click', () => {
-  it('opens ordinary hrefs in a new tab on Cmd-click', () => {
-    const open = vi.spyOn(window, 'open').mockImplementation(() => null);
-    render(<Card href="/docs" />);
-    fireEvent.click(screen.getByTestId('card'), {metaKey: true});
-    expect(open).toHaveBeenCalledWith('/docs', '_blank', 'noopener');
-  });
-
-  it('opens ordinary hrefs in a new tab on Ctrl-click', () => {
-    const open = vi.spyOn(window, 'open').mockImplementation(() => null);
-    render(<Card href="/docs" />);
-    fireEvent.click(screen.getByTestId('card'), {ctrlKey: true});
-    expect(open).toHaveBeenCalledWith('/docs', '_blank', 'noopener');
-  });
-
-  it('does not open a script-scheme href on Cmd-click', () => {
-    const open = vi.spyOn(window, 'open').mockImplementation(() => null);
-    // eslint-disable-next-line @eslint-react/dom-no-script-url -- the test proves this URL never navigates
-    render(<Card href={scriptUrl} />);
-    fireEvent.click(screen.getByTestId('card'), {metaKey: true});
-    expect(open).not.toHaveBeenCalled();
-  });
-
-  it('does not open a script-scheme href on Ctrl-click', () => {
-    const open = vi.spyOn(window, 'open').mockImplementation(() => null);
-    // eslint-disable-next-line @eslint-react/dom-no-script-url -- the test proves this URL never navigates
-    render(<Card href={scriptUrl} />);
-    fireEvent.click(screen.getByTestId('card'), {ctrlKey: true});
-    expect(open).not.toHaveBeenCalled();
-  });
-});
-
-describe('useClickableContainer navigation — middle-click', () => {
-  it('opens ordinary hrefs on middle-click', () => {
-    const open = vi.spyOn(window, 'open').mockImplementation(() => null);
-    render(<Card href="/docs" />);
-    fireEvent.mouseUp(screen.getByTestId('card'), {button: 1});
-    expect(open).toHaveBeenCalledWith('/docs', '_blank', 'noopener');
-  });
-
-  it('does not open a script-scheme href on middle-click', () => {
-    const open = vi.spyOn(window, 'open').mockImplementation(() => null);
-    // eslint-disable-next-line @eslint-react/dom-no-script-url -- the test proves this URL never navigates
-    render(<Card href={scriptUrl} />);
-    fireEvent.mouseUp(screen.getByTestId('card'), {button: 1});
-    expect(open).not.toHaveBeenCalled();
-  });
-});
-
-describe('useClickableContainer navigation — plain click (location.href)', () => {
-  // jsdom does not navigate, so assigning `location.href` is a no-op there
-  // and would let a missing guard pass unnoticed. Stand in a plain object so
-  // the assignment is observable.
-  let location: {href: string};
-
-  beforeEach(() => {
-    location = {href: 'https://app.example/start'};
-    vi.stubGlobal('location', location);
-  });
-
-  it('assigns ordinary hrefs to location', () => {
-    render(<Card href="/docs" />);
-    fireEvent.click(screen.getByTestId('card'));
-    expect(location.href).toBe('/docs');
-  });
-
-  it('does not assign a script-scheme href to location', () => {
-    // eslint-disable-next-line @eslint-react/dom-no-script-url -- the test proves this URL never navigates
-    render(<Card href={scriptUrl} />);
-    fireEvent.click(screen.getByTestId('card'));
-    expect(location.href).toBe('https://app.example/start');
-  });
-
-  it('does not assign a control-character-hidden script scheme to location', () => {
-    // eslint-disable-next-line @eslint-react/dom-no-script-url -- the test proves this URL never navigates
-    render(<Card href={hiddenScriptUrl} />);
-    fireEvent.click(screen.getByTestId('card'));
-    expect(location.href).toBe('https://app.example/start');
-  });
-});
-
-describe('useClickableContainer navigation — delegated interactive ref', () => {
-  it('delegates ordinary hrefs to the inner link', () => {
-    const onAnchorClick = vi.fn();
-    render(<DelegatingCard href="/docs" onAnchorClick={onAnchorClick} />);
-    fireEvent.click(screen.getByTestId('card'));
-    expect(onAnchorClick).toHaveBeenCalledTimes(1);
-  });
-
-  it('does not delegate a script-scheme href to the inner link', () => {
-    const onAnchorClick = vi.fn();
-    // eslint-disable-next-line @eslint-react/dom-no-script-url -- the test proves this URL never navigates
-    render(<DelegatingCard href={scriptUrl} onAnchorClick={onAnchorClick} />);
-    fireEvent.click(screen.getByTestId('card'));
-    expect(onAnchorClick).not.toHaveBeenCalled();
-  });
-
-  it('a click on the inner link itself is left to the link', () => {
-    const onAnchorClick = vi.fn();
-    render(<DelegatingCard href="/docs" onAnchorClick={onAnchorClick} />);
-    fireEvent.click(screen.getByTestId('inner-link'));
-    // The anchor's own handler ran once; the hook did not proxy a second one.
-    expect(onAnchorClick).toHaveBeenCalledTimes(1);
-  });
-});
-
-describe('useClickableContainer navigation — blocked href keeps the rest', () => {
-  it('still fires the onClick handler for a blocked href', () => {
-    const onClick = vi.fn();
-    const open = vi.spyOn(window, 'open').mockImplementation(() => null);
-    function Surface() {
-      const containerRef = useRef<HTMLDivElement>(null);
-      const handlers = useClickableContainer({
-        containerRef,
-        href: scriptUrl,
-        target: '_blank',
-        onClick,
-      });
-      return <div ref={containerRef} data-testid="card" {...handlers} />;
-    }
-    render(<Surface />);
-    fireEvent.click(screen.getByTestId('card'));
-    expect(onClick).toHaveBeenCalledTimes(1);
-    expect(open).not.toHaveBeenCalled();
-  });
-});

package/src/theme/declarationBoundary.test.ts

@@ -1,126 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file Tests for the declaration boundary scanner.
- *
- * Every "keeps" case is valid CSS a browser reads as one declaration; every
- * "rejects" case would end the declaration or rule early, swallow what follows
- * it, or be discarded by the browser as a bad token.
- */
-
-import {describe, it, expect} from 'vitest';
-import {
-  checkDeclarationName,
-  checkDeclarationValue,
-} from './declarationBoundary';
-
-describe('checkDeclarationValue keeps valid CSS inside one declaration', () => {
-  it.each([
-    ['plain color', '#FF00FF'],
-    ['color function', 'color-mix(in oklch, #FF00FF 80%, white)'],
-    ['gradient', 'linear-gradient(135deg, #FF00FF 0%, #00FFFF 100%)'],
-    ['calc', 'calc(100% - 24px)'],
-    ['light-dark', 'light-dark(#fff, #111)'],
-    ['font stack', "'Inter Var', ui-sans-serif, system-ui"],
-    ['important flag', 'red !important'],
-    [
-      'data URI, semicolon inside url()',
-      'url(data:image/png;base64,iVBORw0KGgo=)',
-    ],
-    ['uppercase URL()', 'URL(data:image/svg+xml;base64,PHN2Zz4=)'],
-    ['uppercase URL with an inert brace', 'URL(data:text/plain,a{b)'],
-    ['mixed-case Url() with spaces', 'Url( data:image/png;base64,iVBORw0= )'],
-    ['quoted url with semicolon', 'url("data:image/svg+xml;utf8,<svg/>")'],
-    ['quoted url with a quoted brace', "url('x.png?a={1;2}')"],
-    ['url nested in image-set', 'image-set(url(a;b.png) 1x, url(c;d.png) 2x)'],
-    ['escaped space in identifier', 'Gill\\ Sans, serif'],
-    ['escaped semicolon in identifier', 'a\\;b'],
-    ['hex escape', '\\31 23'],
-    ['escaped quote inside a string', '"a\\" ; b"'],
-    ['semicolon inside a double-quoted string', '"a;b"'],
-    ['semicolon inside a single-quoted string', "'a;b'"],
-    ['braces inside a string', '"} body { color: red }"'],
-    ['closed comment', '/* brand */ red'],
-    ['closed comment with a semicolon inside', 'red /* ; } */'],
-    ['comment-like text inside a string', '"/* not a comment"'],
-    ['balanced brackets in a grid line name', '[full-start] 1fr [full-end]'],
-    ['semicolon nested in parentheses', 'var(--x, a;b)'],
-    ['brace nested in parentheses', 'var(--x, {a})'],
-    ['backslash before a newline is a delim', 'a\\\nb'],
-    ['whitespace including tab and newline', 'a\t\nb'],
-    ['CRLF string continuation', '"a\\\r\nb"'],
-    ['CRLF after a hex escape in a string', '"\\61\r\nb"'],
-    ['escaped url identifier', 'u\\72l(data:image/png;base64,a)'],
-    ['null is preprocessed by CSS', 'red\u0000'],
-    ['control character inside a string', '"a\u0001b"'],
-    ['control character inside a closed comment', 'red /* \u0001 ; } */'],
-    ['empty value', ''],
-  ])('keeps %s', (_label, value) => {
-    expect(checkDeclarationValue(value)).toBeNull();
-  });
-});
-
-describe('checkDeclarationValue rejects true declaration and rule breaks', () => {
-  it.each([
-    ['top-level semicolon', 'red; background: url(x)', ';'],
-    ['top-level closing brace', 'red } body { color: blue', '}'],
-    ['top-level opening brace', 'red { color: blue }', '{'],
-    ['escaped quote is not a string opener', '\\"; background: red; "', ';'],
-    ['unbalanced closing paren', 'red) ; body { color: blue', ')'],
-    ['unbalanced closing bracket', 'red] ; x', ']'],
-    ['mismatched closer', 'calc(1] ; x)', ']'],
-    ['unclosed paren', 'calc(100% - 24px', '('],
-    ['unclosed bracket', '[full-start', '['],
-    ['unclosed string', '"open', 'string'],
-    ['unclosed comment', 'red /* comment', 'comment'],
-    ['unclosed url', 'url(x.png', 'url('],
-    ['trailing backslash', 'red\\', 'backslash'],
-    ['newline inside a string (bad string)', '"a\nb"', 'bad string'],
-    ['whitespace inside an unquoted url (bad url)', 'url(a b)', 'bad url'],
-    ['uppercase bad url', 'URL(a b)', 'bad url'],
-    ['quote inside an unquoted url (bad url)', 'url(a"b)', 'bad url'],
-    ['paren inside an unquoted url (bad url)', 'url(a(b)', 'bad url'],
-    [
-      'stray backslash inside an unquoted url (bad url)',
-      'url(a\\\nb)',
-      'bad url',
-    ],
-    ['control character inside an unquoted url', 'url(a\u0001b)', 'bad url'],
-  ])('rejects %s', (_label, value, fragment) => {
-    const reason = checkDeclarationValue(value);
-    expect(reason).not.toBeNull();
-    expect(reason).toContain(fragment);
-  });
-});
-
-describe('checkDeclarationName', () => {
-  it.each([
-    'color',
-    'background-image',
-    '-webkit-line-clamp',
-    '-moz-osx-font-smoothing',
-    '--brand-accent',
-    '--_internal',
-    '--',
-    '--1',
-    '_private',
-    'caf\u00e9',
-    'a\\:b',
-  ])('keeps %s', name => {
-    expect(checkDeclarationName(name)).toBeNull();
-  });
-
-  it.each([
-    '',
-    '1px',
-    '-1',
-    'color: red',
-    '--x:red} body{color:blue',
-    'color;',
-    'a b',
-    'a\\',
-    'background{',
-  ])('rejects %j', name => {
-    expect(checkDeclarationName(name)).not.toBeNull();
-  });
-});