@astryxdesign/core 0.1.1 → 0.1.2-canary.3893cd5

package/src/Table/useTableStickyColumns.doc.mjs

@@ -0,0 +1,59 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+  name: 'useTableStickyColumns',
+  subComponentOf: 'Table',
+  displayName: 'useTableStickyColumns',
+  description:
+    'Hook that returns a TablePlugin which pins a contiguous run of columns to the start and/or end edge of the table. Pinned columns get cumulative offsets and a soft, scroll-aware shadow over the scrolling content. An empty config ({}) is a valid no-op that pins nothing.',
+  props: [
+    {
+      name: 'startKeys',
+      type: 'string[]',
+      description:
+        'Column keys pinned to the start (inline-start / left in LTR) edge — the contiguous run from the first column through the last listed key.',
+    },
+    {
+      name: 'endKeys',
+      type: 'string[]',
+      description:
+        'Column keys pinned to the end (inline-end / right in LTR) edge — the contiguous run from the first listed key through the last column.',
+    },
+  ],
+};
+
+export const docsZh = {
+  name: 'useTableStickyColumns',
+  displayName: 'useTableStickyColumns',
+  description:
+    '返回 TablePlugin 的 Hook，将一组连续的列固定到表格的起始和/或结束边缘。固定的列具有累积偏移量，并在滚动内容上方显示柔和的、随滚动感知的阴影。空配置 ({}) 是有效的空操作，不固定任何列。',
+  props: [
+    {
+      name: 'startKeys',
+      type: 'string[]',
+      description:
+        '固定到起始（inline-start / LTR 中为左侧）边缘的列键——从第一列到最后列出的键的连续范围。',
+    },
+    {
+      name: 'endKeys',
+      type: 'string[]',
+      description:
+        '固定到结束（inline-end / LTR 中为右侧）边缘的列键——从第一个列出的键到最后一列的连续范围。',
+    },
+  ],
+};
+
+export const docsDense = {
+  name: 'useTableStickyColumns',
+  displayName: 'useTableStickyColumns',
+  description:
+    'Hook returning TablePlugin that pins contiguous column runs to start/end edges w/ cumulative offsets + scroll-aware shadow. Empty config = no-op.',
+  propDescriptions: {
+    startKeys:
+      'Column keys pinned to the start edge (contiguous run from column 0 through the last listed key).',
+    endKeys:
+      'Column keys pinned to the end edge (contiguous run from the first listed key through the last column).',
+  },
+};

package/src/Text/Heading.doc.mjs

@@ -32,7 +32,7 @@ export const docs = {
     },
     {
       name: 'color',
-      type: "'primary' | 'secondary' | 'disabled' | 'placeholder' | 'active' | 'inherit'",
+      type: "'primary' | 'secondary' | 'disabled' | 'placeholder' | 'accent' | 'inherit'",
       description: 'Text color.',
       default: "'primary'",
     },
@@ -64,6 +64,12 @@ export const docs = {
       type: "'wrap' | 'nowrap' | 'balance' | 'pretty'",
       description: 'Text wrapping behavior.',
     },
+    {
+      name: 'justify',
+      type: "'start' | 'center' | 'end'",
+      description: 'Text alignment (justification). Uses logical values (start/end) for i18n/RTL compatibility.',
+      default: "'start'",
+    },
     {
       name: 'hasCapsize',
       type: 'boolean',
@@ -113,7 +119,7 @@ export const docsZh = {
     },
     {
       name: 'color',
-      type: "'primary' | 'secondary' | 'disabled' | 'placeholder' | 'active' | 'inherit'",
+      type: "'primary' | 'secondary' | 'disabled' | 'placeholder' | 'accent' | 'inherit'",
       description: '文本颜色。',
       default: "'primary'",
     },
@@ -145,6 +151,12 @@ export const docsZh = {
       type: "'wrap' | 'nowrap' | 'balance' | 'pretty'",
       description: '文本换行行为。',
     },
+    {
+      name: 'justify',
+      type: "'start' | 'center' | 'end'",
+      description: '文本对齐（两端对齐）。使用逻辑值（start/end）以兼容 i18n/RTL。',
+      default: "'start'",
+    },
     {
       name: 'hasCapsize',
       type: 'boolean',
@@ -180,6 +192,7 @@ export const docsDense = {
     hasTruncateTooltip: "Tooltip for truncated text; true=default position, false=disabled, or a placement ('above' | 'below' | 'start' | 'end').",
     wordBreak: "Word break behavior; defaults 'break-all' for single-line, 'break-word' otherwise.",
     textWrap: 'Text wrapping behavior.',
+    justify: "Text alignment (justification); logical values 'start' | 'center' | 'end' for RTL.",
     hasCapsize: 'Optical alignment via text-box-trim; forces block display.',
     hasStrikethrough: 'Strikethrough text decoration.',
     id: 'HTML id attribute.',

package/src/Text/Text.doc.mjs

@@ -40,7 +40,7 @@ export const docs = {
     },
     {
       name: 'color',
-      type: "'primary' | 'secondary' | 'disabled' | 'placeholder' | 'active' | 'inherit'",
+      type: "'primary' | 'secondary' | 'disabled' | 'placeholder' | 'accent' | 'inherit'",
       description: "Text color. Defaults to 'secondary' for the 'supporting' type, 'primary' for all others.",
     },
     {
@@ -82,6 +82,12 @@ export const docs = {
       type: "'wrap' | 'nowrap' | 'balance' | 'pretty'",
       description: 'Text wrapping behavior.',
     },
+    {
+      name: 'justify',
+      type: "'start' | 'center' | 'end'",
+      description: 'Text alignment (justification). Uses logical values (start/end) for i18n/RTL compatibility.',
+      default: "'start'",
+    },
     {
       name: 'hasCapsize',
       type: 'boolean',

package/src/Text/text.stylex.ts

@@ -35,8 +35,8 @@ export const colorStyles = stylex.create({
   placeholder: {
     color: colorVars['--color-text-secondary'],
   },
-  active: {
-    color: colorVars['--color-accent'],
+  accent: {
+    color: colorVars['--color-text-accent'],
   },
   inherit: {
     color: 'inherit',

package/src/Timestamp/Timestamp.doc.mjs

@@ -7,6 +7,15 @@ export const docs = {
   displayName: 'Timestamp',
   category: 'Content',
   keywords: ['date', 'time', 'datetime', 'relative', 'ago', 'clock', 'format', 'duration'],
+  playground: {
+    // `value` is required but has no semantic default, so the properties-tab
+    // preview fell back to the literal string "value" — which
+    // `new Date("value")` rejects, crashing the preview with "Invalid time
+    // value". Seed a valid ISO 8601 date so the interactive preview renders.
+    defaults: {
+      value: '2026-02-19T17:00:00Z',
+    },
+  },
   props: [
     {
       name: 'value',

package/src/Timestamp/Timestamp.test.tsx

@@ -33,10 +33,30 @@ describe('Timestamp', () => {
     expect(screen.getByText('2 hours ago')).toBeInTheDocument();
   });
 
-  it('renders "just now" for very recent times', () => {
+  it('renders "now" for very recent times', () => {
     const fiveSecondsAgo = Date.now() / 1000 - 5;
     render(<Timestamp value={fiveSecondsAgo} format="relative" />);
-    expect(screen.getByText('just now')).toBeInTheDocument();
+    expect(screen.getByText('now')).toBeInTheDocument();
+  });
+
+  it('renders "now" for the current instant (not a future phrase)', () => {
+    // A value equal to "right now". Because the internal `now` baseline is
+    // captured at render time, it can lag the value by a fraction of a second,
+    // producing a tiny negative delta that must not be treated as the future.
+    render(<Timestamp value={Date.now() / 1000} format="relative" />);
+    expect(screen.queryByText(/^in /)).not.toBeInTheDocument();
+    expect(screen.getByText('now')).toBeInTheDocument();
+  });
+
+  it('renders "now" for a value a hair in the future (clock skew)', () => {
+    // Real-world clock / captured-now skew can make a current-ish value land a
+    // fraction of a second in the future relative to the component's internal
+    // `now`. This must read as the present ("now"), never "in a few
+    // seconds". Regression test for the right-now -> future-phrase bug.
+    const aHairInTheFuture = Date.now() / 1000 + 0.6;
+    render(<Timestamp value={aHairInTheFuture} format="relative" />);
+    expect(screen.queryByText(/^in /)).not.toBeInTheDocument();
+    expect(screen.getByText('now')).toBeInTheDocument();
   });
 
   it('renders "yesterday" for times ~1 day ago', () => {
@@ -49,11 +69,7 @@ describe('Timestamp', () => {
 
   it('renders date format', () => {
     render(
-      <Timestamp
-        value="2026-02-19T17:00:00Z"
-        format="date"
-        data-testid="ts"
-      />,
+      <Timestamp value="2026-02-19T17:00:00Z" format="date" data-testid="ts" />,
     );
     const el = screen.getByTestId('ts');
     expect(el.textContent).toContain('2026');
@@ -77,11 +93,7 @@ describe('Timestamp', () => {
 
   it('renders time format', () => {
     render(
-      <Timestamp
-        value="2026-02-19T17:00:00Z"
-        format="time"
-        data-testid="ts"
-      />,
+      <Timestamp value="2026-02-19T17:00:00Z" format="time" data-testid="ts" />,
     );
     const el = screen.getByTestId('ts');
     // Should contain time but not year
@@ -197,7 +209,7 @@ describe('Timestamp', () => {
   it('live updates relative time', () => {
     const now = Date.now() / 1000;
     render(<Timestamp value={now - 5} format="relative" isLive />);
-    expect(screen.getByText('just now')).toBeInTheDocument();
+    expect(screen.getByText('now')).toBeInTheDocument();
 
     act(() => {
       vi.advanceTimersByTime(30_000);
@@ -210,11 +222,7 @@ describe('Timestamp', () => {
   it('forwards ref', () => {
     const ref = {current: null as HTMLTimeElement | null};
     render(
-      <Timestamp
-        ref={ref}
-        value="2026-03-25T10:00:00Z"
-        format="date_time"
-      />,
+      <Timestamp ref={ref} value="2026-03-25T10:00:00Z" format="date_time" />,
     );
     expect(ref.current).toBeInstanceOf(HTMLTimeElement);
   });
@@ -240,6 +248,24 @@ describe('Timestamp', () => {
     expect(screen.getByText('in 1 hour')).toBeInTheDocument();
   });
 
+  it('renders "now" for a value a few seconds in the future (clock skew)', () => {
+    // Beyond the sub-second render lag but still within the skew tolerance: a
+    // value ~20s ahead of our clock is almost always skew (the value's clock
+    // running fast), not a genuine future event, so it should read as the
+    // present rather than "in a few seconds".
+    const twentySecondsFromNow = Date.now() / 1000 + 20;
+    render(<Timestamp value={twentySecondsFromNow} format="relative" />);
+    expect(screen.queryByText(/^in /)).not.toBeInTheDocument();
+    expect(screen.getByText('now')).toBeInTheDocument();
+  });
+
+  it('renders a genuine near-future time beyond the skew tolerance', () => {
+    // Past the skew window — this is a real upcoming time, not clock drift.
+    const fortyFiveSecondsFromNow = Date.now() / 1000 + 45;
+    render(<Timestamp value={fortyFiveSecondsFromNow} format="relative" />);
+    expect(screen.getByText('in a few seconds')).toBeInTheDocument();
+  });
+
   // --- Long-ago relative ---
 
   it('renders months ago for dates older than 30 days', () => {

package/src/Timestamp/Timestamp.tsx

@@ -19,12 +19,7 @@
 import {useEffect, useRef, useState, lazy, Suspense} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {Text} from '../Text';
-import type {
-  TextType,
-  TextSize,
-  TextColor,
-  TextWeight,
-} from '../theme/types';
+import type {TextType, TextSize, TextColor, TextWeight} from '../theme/types';
 import {mergeProps, mergeRefs} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
@@ -54,7 +49,7 @@ export interface TimestampProps extends BaseProps<HTMLTimeElement> {
   value: string | number;
   /**
    * Display format.
-   * - `'relative'`: "2 hours ago", "yesterday", "just now"
+   * - `'relative'`: "2 hours ago", "yesterday", "now"
    * - `'auto'`: Relative for recent times, `date_time` for older
    * - `'date'`: "Mar 21, 2025"
    * - `'date_time'`: "Mar 21, 2025, 2:51 PM"
@@ -138,6 +133,18 @@ const YEAR = 365 * DAY;
 /** Default auto threshold: 7 days in seconds */
 const DEFAULT_AUTO_THRESHOLD = 7 * DAY;
 
+/**
+ * Tolerance (in seconds) for treating a *future* timestamp as the present.
+ * A value only a handful of seconds ahead of our reference clock is almost
+ * always clock skew — the displayed `now` lagging the real clock, or the value
+ * being produced on a slightly faster clock — not a genuine future event, so
+ * it reads as "now" rather than a confusing "in a few seconds". The future
+ * side gets a wider window than the past (which only needs to absorb the
+ * sub-second render-time lag) because future drift is far more likely to be
+ * skew than real.
+ */
+const FUTURE_SKEW_TOLERANCE = 30;
+
 function parseValue(value: string | number): Date {
   if (typeof value === 'number') {
     // Heuristic: if the number is less than 1e12, treat as seconds; otherwise ms.
@@ -150,9 +157,25 @@ function parseValue(value: string | number): Date {
 function getRelativeTimeString(date: Date, now: Date): string {
   const diffSeconds = Math.round((now.getTime() - date.getTime()) / 1000);
 
+  // Treat values at (or a hair before/after) the present as "now". The
+  // internal `now` reference is captured at render time, so it can lag the
+  // real clock; a value equal to "right now" can land a fraction of a second
+  // in the future and round to a small negative delta. Without this clamp,
+  // such values fall into the future branch and render "in a few seconds".
+  if (Math.abs(diffSeconds) < 10) {
+    return 'now';
+  }
+
   if (diffSeconds < 0) {
     // Future dates
     const absDiff = Math.abs(diffSeconds);
+    // A value only a few seconds ahead of our clock is almost always skew, not
+    // a genuine future event — render it as the present rather than a
+    // confusing "in a few seconds". Wider than the past window above on
+    // purpose (see FUTURE_SKEW_TOLERANCE).
+    if (absDiff <= FUTURE_SKEW_TOLERANCE) {
+      return 'now';
+    }
     if (absDiff < MINUTE) {
       return 'in a few seconds';
     }
@@ -176,9 +199,6 @@ function getRelativeTimeString(date: Date, now: Date): string {
     return `in ${years} ${years === 1 ? 'year' : 'years'}`;
   }
 
-  if (diffSeconds < 10) {
-    return 'just now';
-  }
   if (diffSeconds < MINUTE) {
     return `${diffSeconds} seconds ago`;
   }

package/src/ToggleButton/ToggleButton.doc.mjs

@@ -34,13 +34,13 @@ export const docs = {
     },
     {
       name: 'onPressedChange',
-      type: '(isPressed: boolean) => void',
-      description: 'Called when pressed state should change. Ignored when inside a group.',
+      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.',
     },
     {
       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 (debounced) spinner while pending; interruptible by re-clicks.',
+      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.',
     },
     {
       name: 'size',
@@ -74,6 +74,12 @@ export const docs = {
         },
       ],
     },
+    {
+      name: 'isIconOnly',
+      type: 'boolean',
+      description: 'When true, renders as a square icon-only button with `label` as the aria-label and an automatic tooltip from the label.',
+      default: 'false',
+    },
     {
       name: 'pressedIcon',
       type: 'ReactNode',

package/src/ToggleButton/ToggleButton.test.tsx

@@ -9,9 +9,9 @@
  */
 
 import {describe, it, expect, vi} from 'vitest';
-import {render, screen, act, fireEvent, waitFor} from '@testing-library/react';
+import {render, screen, act, fireEvent} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
-import {useState} from 'react';
+import {useState, type MouseEvent} from 'react';
 import {ToggleButton} from './ToggleButton';
 import {ToggleButtonGroup} from './ToggleButtonGroup';
 
@@ -88,7 +88,7 @@ describe('ToggleButton', () => {
     );
 
     await user.click(screen.getByRole('button'));
-    expect(handleChange).toHaveBeenCalledWith(true);
+    expect(handleChange).toHaveBeenCalledWith(true, expect.anything());
   });
 
   it('calls onPressedChange with false when clicking pressed button', async () => {
@@ -103,7 +103,7 @@ describe('ToggleButton', () => {
     );
 
     await user.click(screen.getByRole('button'));
-    expect(handleChange).toHaveBeenCalledWith(false);
+    expect(handleChange).toHaveBeenCalledWith(false, expect.anything());
   });
 
   it('renders pressedIcon when pressed', () => {
@@ -193,7 +193,7 @@ describe('ToggleButton', () => {
     expect(screen.getByTestId('bold-toggle')).toBeInTheDocument();
   });
 
-  it('shows the optimistic pressed state immediately, before any spinner', async () => {
+  it('shows the optimistic pressed state and stays interruptible while pending', async () => {
     const user = userEvent.setup();
     let resolveAction: (() => void) | undefined;
     const pressedChangeAction = vi.fn(
@@ -217,12 +217,13 @@ describe('ToggleButton', () => {
 
     await user.click(button);
 
-    // The optimistic state flips immediately. The spinner is debounced, so the
-    // button is not disabled or aria-busy yet — it stays interruptible.
+    // The optimistic state flips immediately and the spinner shows via
+    // aria-busy, but the button is never disabled — it stays clickable so the
+    // action can be interrupted by another click.
     expect(pressedChangeAction).toHaveBeenCalledWith(true);
     expect(button).toHaveAttribute('aria-pressed', 'true');
+    expect(button).toHaveAttribute('aria-busy', 'true');
     expect(button).not.toBeDisabled();
-    expect(button).not.toHaveAttribute('aria-busy', 'true');
 
     // Settle the action so the pending transition doesn't leak into later tests.
     await act(async () => {
@@ -231,7 +232,7 @@ describe('ToggleButton', () => {
     });
   });
 
-  it('shows a loading spinner once the action stays pending past the delay', async () => {
+  it('clears the loading state once the action settles', async () => {
     const user = userEvent.setup();
     let resolveAction: (() => void) | undefined;
     const pressedChangeAction = vi.fn(
@@ -253,18 +254,15 @@ describe('ToggleButton', () => {
     const button = screen.getByRole('button', {name: 'Favorite'});
     await user.click(button);
 
-    // The optimistic state shows immediately; the spinner is debounced and
-    // appears only after the action stays pending past the delay window.
-    expect(button).toHaveAttribute('aria-pressed', 'true');
-    await waitFor(() => expect(button).toBeDisabled());
     expect(button).toHaveAttribute('aria-busy', 'true');
+    expect(button).not.toBeDisabled();
 
     await act(async () => {
       resolveAction?.();
       await Promise.resolve();
     });
-    expect(button).not.toBeDisabled();
     expect(button).not.toHaveAttribute('aria-busy', 'true');
+    expect(button).not.toBeDisabled();
   });
 
   it('interrupts an in-flight action on re-click (true -> false -> true)', async () => {
@@ -290,9 +288,8 @@ describe('ToggleButton', () => {
     const button = screen.getByRole('button', {name: 'Favorite'});
 
     // Each click derives the next state from the optimistic (in-progress)
-    // value, so rapid clicks toggle rather than being dropped. fireEvent keeps
-    // the clicks within the spinner debounce window so the button stays
-    // interruptible.
+    // value, so rapid clicks toggle rather than being dropped. The button is
+    // never disabled while pending, so every click lands and interrupts.
     await act(async () => {
       fireEvent.click(button);
     });
@@ -335,9 +332,33 @@ describe('ToggleButton', () => {
     const button = screen.getByRole('button', {name: 'Favorite'});
     await user.click(button);
 
-    expect(onPressedChange).toHaveBeenCalledWith(true);
+    expect(onPressedChange).toHaveBeenCalledWith(true, expect.anything());
     expect(pressedChangeAction).toHaveBeenCalledWith(true);
   });
+
+  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>) => {
+        event.preventDefault();
+      },
+    );
+
+    render(
+      <ToggleButton
+        label="Favorite"
+        isPressed={false}
+        onPressedChange={onPressedChange}
+        pressedChangeAction={pressedChangeAction}
+      />,
+    );
+
+    await user.click(screen.getByRole('button', {name: 'Favorite'}));
+
+    expect(onPressedChange).toHaveBeenCalledWith(true, expect.anything());
+    expect(pressedChangeAction).not.toHaveBeenCalled();
+  });
 });
 
 // =============================================================================