@astryxdesign/core 0.1.1 → 0.1.2-canary.04e71b2

package/src/TimeInput/TimeInput.tsx

@@ -63,6 +63,7 @@ import type {BaseProps} from '../BaseProps';
 import type {SizeValue} from '../utils/types';
 import {useSize} from '../SizeContext/SizeContext';
 import {useInputContainer} from '../hooks/useInputContainer';
+import {useTooltip} from '../Tooltip';
 import {themeProps} from '../utils/themeProps';
 
 const styles = stylex.create({
@@ -183,6 +184,29 @@ export interface TimeInputProps extends Omit<
    */
   isDisabled?: boolean;
 
+  /**
+   * Explains why the input is disabled. When set together with
+   * `isDisabled`, the input shows a tooltip with this text on hover and
+   * keyboard focus, and the field stays focusable (via `aria-disabled`)
+   * so the reason is discoverable by keyboard and assistive technology.
+   * Typing and arrow-key adjustment stay blocked.
+   *
+   * Use this instead of wrapping a disabled input in `Tooltip` — disabled
+   * controls don't emit the pointer events an external tooltip needs.
+   *
+   * @example
+   * ```
+   * <TimeInput
+   *   label="Start time"
+   *   value={time}
+   *   onChange={setTime}
+   *   isDisabled
+   *   disabledMessage="You need the Editor role to change this"
+   * />
+   * ```
+   */
+  disabledMessage?: string;
+
   /**
    * The selected time in ISO format (HH:MM or HH:MM:SS).
    */
@@ -301,6 +325,7 @@ export function TimeInput({
   isOptional = false,
   isRequired = false,
   isDisabled = false,
+  disabledMessage,
   value,
   onChange,
   changeAction,
@@ -334,6 +359,19 @@ export function TimeInput({
   const [optimisticValue, setOptimisticValue] = useOptimistic(value);
   const isBusy = isLoading || optimisticValue !== value;
 
+  // Disabled-reason tooltip. Disabled controls swallow pointer events, so the
+  // tooltip listeners attach to the input container (which already exists) and
+  // the input stays perceivable via aria-disabled instead of the disabled
+  // attribute. Typing is blocked with readOnly and value mutation guards.
+  const showsDisabledMessage = isDisabled && !!disabledMessage;
+  const disabledMessageTooltip = useTooltip({
+    placement: 'above',
+    // The container div is not naturally focusable; focusin bubbles up from
+    // the input, so always attach focus listeners.
+    focusTrigger: 'always',
+    isEnabled: showsDisabledMessage,
+  });
+
   // Status icon mapping
   const statusIconMap: Record<InputStatusType, IconName> = {
     warning: 'warning',
@@ -354,6 +392,7 @@ export function TimeInput({
     [
       description ? descriptionID : null,
       status?.message ? statusMessageID : null,
+      showsDisabledMessage ? disabledMessageTooltip.describedBy : null,
     ]
       .filter(Boolean)
       .join(' ') || undefined;
@@ -415,6 +454,11 @@ export function TimeInput({
   // Handle input text change - update immediately if valid
   const handleInputChange = useCallback(
     (e: React.ChangeEvent<HTMLInputElement>) => {
+      // With a disabledMessage the input drops `disabled` for focusability, so
+      // guard value mutation explicitly (readOnly also blocks typing).
+      if (isDisabled) {
+        return;
+      }
       const newValue = e.target.value;
       setPendingInput(newValue);
 
@@ -424,13 +468,19 @@ export function TimeInput({
         fireChange(parsed);
       }
     },
-    [hasSeconds, min, max, value, fireChange],
+    [hasSeconds, min, max, value, fireChange, isDisabled],
   );
 
   // Handle focus
   const handleFocus = useCallback(() => {
+    // A disabled input stays focusable (via aria-disabled) so its reason is
+    // discoverable, but it must not present editing affordances — keep the
+    // static placeholder rather than swapping in the format hint.
+    if (isDisabled) {
+      return;
+    }
     setIsFocused(true);
-  }, []);
+  }, [isDisabled]);
 
   // Handle blur - validate and clear pending input
   const handleBlur = useCallback(
@@ -466,6 +516,11 @@ export function TimeInput({
   // Handle keyboard navigation on input
   const handleInputKeyDown = useCallback(
     (e: KeyboardEvent<HTMLInputElement>) => {
+      // Arrow-key adjustment mutates the value; block it while showing a
+      // disabled reason (the input keeps focusability via aria-disabled).
+      if (isDisabled) {
+        return;
+      }
       if (e.key === 'ArrowUp' || e.key === 'ArrowDown') {
         e.preventDefault();
 
@@ -492,7 +547,7 @@ export function TimeInput({
         }
       }
     },
-    [value, hasSeconds, increment, min, max, fireChange],
+    [value, hasSeconds, increment, min, max, fireChange, isDisabled],
   );
 
   // Handle clear button click
@@ -531,7 +586,13 @@ export function TimeInput({
       labelTooltip={labelTooltip}
       width={width}>
       <div
-        ref={containerRef}
+        ref={el => {
+          containerRef.current = el;
+          // Anchor + hover/focus listeners for the disabled-message tooltip.
+          // Handlers are gated internally by isEnabled, so attaching
+          // unconditionally is safe.
+          disabledMessageTooltip.ref(el);
+        }}
         onClick={handleWrapperClick}
         onMouseUp={handleWrapperMouseUp}
         {...mergeProps(
@@ -561,7 +622,12 @@ export function TimeInput({
           onBlur={handleBlur}
           onKeyDown={handleInputKeyDown}
           placeholder={displayPlaceholder}
-          disabled={isDisabled}
+          // With a disabledMessage the input keeps focusability via
+          // aria-disabled so the reason is focus-discoverable; typing and
+          // arrow-key adjustment are blocked with readOnly and the guards.
+          disabled={isDisabled && !showsDisabledMessage}
+          aria-disabled={showsDisabledMessage ? 'true' : undefined}
+          readOnly={showsDisabledMessage || undefined}
           autoFocus={hasAutoFocus}
           data-autofocus={hasAutoFocus || undefined}
           aria-describedby={ariaDescribedBy}
@@ -592,6 +658,9 @@ export function TimeInput({
           />
         )}
       </div>
+
+      {showsDisabledMessage &&
+        disabledMessageTooltip.renderTooltip(disabledMessage)}
     </Field>
   );
 }

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/Toast/Toast.tsx

@@ -167,6 +167,20 @@ export function Toast({
     };
   }, [autoHideDuration, startTimer]);
 
+  // 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.
+  useEffect(() => {
+    if (!isAutoHide) {
+      return;
+    }
+    window.addEventListener('blur', pauseTimer);
+    window.addEventListener('focus', resumeTimer);
+    return () => {
+      window.removeEventListener('blur', pauseTimer);
+      window.removeEventListener('focus', resumeTimer);
+    };
+  }, [isAutoHide, pauseTimer, resumeTimer]);
+
   const handleDismiss = useCallback(() => {
     onDismiss('manual');
   }, [onDismiss]);

package/src/Toast/ToastViewport.test.tsx

@@ -0,0 +1,204 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file ToastViewport.test.tsx
+ * @input Uses vitest, @testing-library/react, ToastViewport + useToast
+ * @output Unit tests for toast keyboard reach and focus management
+ * @position Testing; validates ToastViewport.tsx + Toast.tsx focus behavior
+ *
+ * SYNC: When ToastViewport.tsx or Toast.tsx focus handling changes, update these tests
+ */
+
+import {describe, it, expect, vi, beforeAll} from 'vitest';
+import {render, screen, fireEvent, act} from '@testing-library/react';
+import React from 'react';
+import {ToastViewport} from './ToastViewport';
+import {useToast} from './useToast';
+import type {ToastOptions} from './types';
+
+// Popover API is not implemented in jsdom.
+beforeAll(() => {
+  if (typeof HTMLElement.prototype.showPopover === 'undefined') {
+    HTMLElement.prototype.showPopover = vi.fn();
+    HTMLElement.prototype.hidePopover = vi.fn();
+  }
+});
+
+// Module-level constant default props (avoids unstable-default-props lint).
+const EMPTY_OPTIONS: ToastOptions = {body: 'placeholder'};
+
+function ShowToastButton({
+  options = EMPTY_OPTIONS,
+  triggerLabel = 'Trigger',
+}: {
+  options?: ToastOptions;
+  triggerLabel?: string;
+}) {
+  const toast = useToast();
+  return (
+    <button type="button" onClick={() => toast(options)}>
+      {triggerLabel}
+    </button>
+  );
+}
+
+const INFO_A: ToastOptions = {body: 'Toast A'};
+const INFO_B: ToastOptions = {body: 'Toast B'};
+const AUTO_TOAST: ToastOptions = {body: 'Auto toast', autoHideDuration: 3000};
+
+function renderViewport(children: React.ReactNode) {
+  return render(<ToastViewport isTopLayer={false}>{children}</ToastViewport>);
+}
+
+// Fire the transition-end that ToastViewport listens for to unmount an
+// exiting toast (jsdom does not run CSS transitions).
+function completeExit(toastId: string) {
+  const node = document.querySelector<HTMLElement>(
+    `[data-toast-id="${toastId}"]`,
+  );
+  if (node) {
+    fireEvent.transitionEnd(node, {propertyName: 'grid-template-rows'});
+  }
+}
+
+describe('ToastViewport keyboard reach + focus', () => {
+  it('F6 moves focus into the newest toast', () => {
+    renderViewport(
+      <ShowToastButton options={INFO_A} triggerLabel="Trigger A" />,
+    );
+    const trigger = screen.getByText('Trigger A');
+    trigger.focus();
+    act(() => {
+      fireEvent.click(trigger);
+    });
+
+    expect(screen.getByText('Toast A')).toBeInTheDocument();
+    expect(document.activeElement).toBe(trigger);
+
+    act(() => {
+      fireEvent.keyDown(document, {key: 'F6'});
+    });
+
+    // Focus lands on the dismiss button of the newest toast.
+    const dismiss = screen.getByRole('button', {name: 'Dismiss notification'});
+    expect(document.activeElement).toBe(dismiss);
+  });
+
+  it('dismissing a focused toast moves focus to a remaining toast, not body', () => {
+    renderViewport(
+      <>
+        <ShowToastButton options={INFO_A} triggerLabel="Trigger A" />
+        <ShowToastButton options={INFO_B} triggerLabel="Trigger B" />
+      </>,
+    );
+    act(() => {
+      fireEvent.click(screen.getByText('Trigger A'));
+    });
+    act(() => {
+      fireEvent.click(screen.getByText('Trigger B'));
+    });
+
+    const dismissButtons = screen.getAllByRole('button', {
+      name: 'Dismiss notification',
+    });
+    expect(dismissButtons).toHaveLength(2);
+
+    // Focus the first toast's dismiss button, then dismiss it.
+    const firstToast = document.querySelectorAll('[data-toast-id]')[0];
+    const firstToastId = firstToast.getAttribute('data-toast-id')!;
+    const firstDismiss = firstToast.querySelector<HTMLElement>(
+      'button[aria-label="Dismiss notification"]',
+    )!;
+    firstDismiss.focus();
+    expect(document.activeElement).toBe(firstDismiss);
+
+    act(() => {
+      fireEvent.click(firstDismiss);
+    });
+    act(() => {
+      completeExit(firstToastId);
+    });
+
+    // Focus must NOT drop to <body>; it moves to the remaining toast.
+    expect(document.activeElement).not.toBe(document.body);
+    expect(document.activeElement?.getAttribute('aria-label')).toBe(
+      'Dismiss notification',
+    );
+  });
+
+  it('dismissing the last focused toast restores the previously-focused element', () => {
+    renderViewport(
+      <ShowToastButton options={INFO_A} triggerLabel="Trigger A" />,
+    );
+    const trigger = screen.getByText('Trigger A');
+    trigger.focus();
+    act(() => {
+      fireEvent.click(trigger);
+    });
+
+    // F6 into the toast, remembering the trigger as the prior focus.
+    act(() => {
+      fireEvent.keyDown(document, {key: 'F6'});
+    });
+    const dismiss = screen.getByRole('button', {name: 'Dismiss notification'});
+    expect(document.activeElement).toBe(dismiss);
+
+    const toastId = document
+      .querySelector('[data-toast-id]')!
+      .getAttribute('data-toast-id')!;
+
+    act(() => {
+      fireEvent.click(dismiss);
+    });
+    act(() => {
+      completeExit(toastId);
+    });
+
+    // No toasts left — focus returns to the element focused before F6.
+    expect(document.activeElement).toBe(trigger);
+  });
+});
+
+describe('Toast blur timer pause', () => {
+  it('pauses the auto-hide timer while the window is blurred', () => {
+    vi.useFakeTimers();
+    try {
+      renderViewport(
+        <ShowToastButton options={AUTO_TOAST} triggerLabel="Trigger Auto" />,
+      );
+      act(() => {
+        fireEvent.click(screen.getByText('Trigger Auto'));
+      });
+      expect(screen.getByText('Auto toast')).toBeInTheDocument();
+
+      // Window loses focus — timer should pause.
+      act(() => {
+        window.dispatchEvent(new Event('blur'));
+      });
+      act(() => {
+        vi.advanceTimersByTime(5000);
+      });
+      // Still present because the timer was paused while blurred.
+      expect(screen.getByText('Auto toast')).toBeInTheDocument();
+
+      // Window regains focus — timer resumes and the toast dismisses.
+      act(() => {
+        window.dispatchEvent(new Event('focus'));
+      });
+      act(() => {
+        vi.advanceTimersByTime(5000);
+      });
+      const toastId = document
+        .querySelector('[data-toast-id]')
+        ?.getAttribute('data-toast-id');
+      if (toastId) {
+        act(() => {
+          completeExit(toastId);
+        });
+      }
+      expect(screen.queryByText('Auto toast')).not.toBeInTheDocument();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});