@astryxdesign/core 0.1.8 → 0.1.9-canary.09e9ddd

package/src/Thumbnail/thumbnail.markers.stylex.ts

@@ -0,0 +1,12 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import * as stylex from '@stylexjs/stylex';
+
+/**
+ * Scoped marker for Thumbnail ancestor selectors. Applied to the image
+ * container so the remove button's hover/focus reveal (`showRemoveOn="hover"`)
+ * responds only to this thumbnail — not to hover/focus state from an outer
+ * container the thumbnail happens to sit inside.
+ */
+export const thumbnailScope: ReturnType<typeof stylex.defineMarker> =
+  stylex.defineMarker();

package/src/TimeInput/TimeInput.doc.mjs

@@ -229,6 +229,13 @@ export const docs = {
       description:
         'Status indicator that colors the border and displays an icon. When a message is provided it is rendered below the input.',
     },
+    {
+      name: 'statusVariant',
+      type: "'attached' | 'detached'",
+      description:
+        'How the status message is placed relative to the input. attached overlaps directly below the input (bordered treatment); detached floats below as a separate element with spacing.',
+      default: "'attached'",
+    },
     {
       name: 'labelTooltip',
       type: 'string',
@@ -372,6 +379,13 @@ export const docsZh = {
       description:
         '为边框着色并显示图标的状态指示器。当提供消息时，消息渲染在输入框下方。',
     },
+    {
+      name: 'statusVariant',
+      type: "'attached' | 'detached'",
+      description:
+        '状态消息相对于输入框的放置方式。attached 直接叠加在输入框下方（带边框处理）；detached 作为独立元素浮于下方并留有间距。',
+      default: "'attached'",
+    },
     {
       name: 'labelTooltip',
       type: 'string',
@@ -545,6 +559,7 @@ export const docsDense = {
     placeholder: 'Placeholder when empty. Focused+empty shows format hint.',
     size: 'Input element height.',
     status: 'Colored border+icon. Message rendered below input.',
+    statusVariant: 'How status message is placed: attached overlaps below input; detached floats below w/ spacing.',
     labelTooltip: 'Tooltip as info icon at label row end.',
     xstyle:
       'StyleX styles for layout customization. Must be stylex.create() value, not inline style.',

package/src/TimeInput/TimeInput.test.tsx

@@ -9,12 +9,24 @@
  * SYNC: When TimeInput.tsx changes, update tests to match new behavior
  */
 
-import {describe, it, expect, vi, beforeEach} from 'vitest';
+import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
 import {render, screen, fireEvent, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {TimeInput} from './TimeInput';
 import {InputGroup, InputGroupText} from '../InputGroup';
 import type {ISOTimeString} from '../utils';
+import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
+
+function politeRegion(): HTMLElement | null {
+  return document.querySelector('[data-astryx-live-region="polite"]');
+}
+function assertiveRegion(): HTMLElement | null {
+  return document.querySelector('[data-astryx-live-region="assertive"]');
+}
+
+afterEach(() => {
+  __resetLiveRegionsForTest();
+});
 
 describe('TimeInput', () => {
   it('renders with label', () => {
@@ -352,6 +364,69 @@ describe('TimeInput', () => {
       // duplicated.
       expect(container.querySelectorAll('svg')).toHaveLength(1);
     });
+
+    // The grouped status node exists only for aria-describedby; announcing
+    // happens through the persistent useAnnounce regions because a live
+    // region mounted together with its content is not reliably announced.
+    it('keeps the grouped status node role-free while announcing via the persistent region', async () => {
+      render(
+        <InputGroup label="Schedule">
+          <InputGroupText>Starts</InputGroupText>
+          <TimeInput
+            label="Start time"
+            isLabelHidden
+            value={'09:00' as ISOTimeString}
+            onChange={() => {}}
+            status={{type: 'error', message: 'Start time is required'}}
+          />
+        </InputGroup>,
+      );
+
+      const input = screen.getByRole('textbox', {
+        name: 'Schedule Start time',
+      });
+      const describedByIDs =
+        input.getAttribute('aria-describedby')?.split(' ') ?? [];
+      const statusNode = describedByIDs
+        .map(id => document.getElementById(id))
+        .find(el => el?.textContent === 'Start time is required');
+      expect(statusNode).toBeTruthy();
+      expect(statusNode).not.toHaveAttribute('role');
+      expect(statusNode).not.toHaveAttribute('aria-live');
+
+      await waitFor(() => {
+        expect(assertiveRegion()).toHaveTextContent('Start time is required');
+      });
+    });
+
+    // Regression: a grouped status message appearing after mount (the common
+    // validation flow) must land in the persistent announce region.
+    it('announces a grouped status message that appears after mount', async () => {
+      const grouped = (status?: {
+        type: 'error' | 'warning';
+        message: string;
+      }) => (
+        <InputGroup label="Schedule">
+          <InputGroupText>Starts</InputGroupText>
+          <TimeInput
+            label="Start time"
+            isLabelHidden
+            value={'09:00' as ISOTimeString}
+            onChange={() => {}}
+            status={status}
+          />
+        </InputGroup>
+      );
+      const {rerender} = render(grouped());
+      expect(politeRegion()).toBeNull();
+
+      rerender(grouped({type: 'warning', message: 'Schedule is unusual'}));
+      await waitFor(() => {
+        expect(politeRegion()).toHaveTextContent('Schedule is unusual');
+      });
+      // Non-error statuses stay on the polite channel.
+      expect(assertiveRegion()).toHaveTextContent('');
+    });
   });
 
   describe('disabledMessage', () => {
@@ -496,3 +571,26 @@ describe('TimeInput', () => {
     });
   });
 });
+
+
+describe('TimeInput statusVariant forwarding', () => {
+  it('defaults to attached (status renders with data-variant="attached")', () => {
+    const {container} = render(
+      <TimeInput label="Start" value={undefined} onChange={() => {}} status={{type: 'error', message: 'Required'}} />,
+    );
+    expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
+      'data-variant',
+      'attached',
+    );
+  });
+
+  it('forwards statusVariant="detached" to the underlying Field status', () => {
+    const {container} = render(
+      <TimeInput label="Start" value={undefined} onChange={() => {}} status={{type: 'error', message: 'Required'}} statusVariant="detached" />,
+    );
+    expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
+      'data-variant',
+      'detached',
+    );
+  });
+});

package/src/TimeInput/TimeInput.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file TimeInput.tsx
- * @input Uses React, useId, useState, useCallback, useRef, Field, Icon, InputGroupContext
+ * @input Uses React, useId, useState, useCallback, useRef, Field, Icon, InputGroupContext, useAnnounce
  * @output Exports TimeInput component, TimeInputProps
  * @position Core implementation; consumed by index.ts, tested by TimeInput.test.tsx
  *
@@ -20,6 +20,7 @@ import {
   useId,
   useState,
   useCallback,
+  useEffect,
   useRef,
   useMemo,
   useOptimistic,
@@ -45,6 +46,7 @@ import {
   inputStatusBorderStyles,
   inputStatusHoverShadowStyles,
   inputStatusFocusWithinStyles,
+  type FieldStatusVariant,
 } from '../Field';
 import {Icon} from '../Icon';
 import {Spinner} from '../Spinner';
@@ -64,6 +66,7 @@ import {
 import type {BaseProps} from '../BaseProps';
 import type {SizeValue} from '../utils/types';
 import {useSize} from '../SizeContext/SizeContext';
+import {useAnnounce} from '../hooks/useAnnounce';
 import {useInputContainer} from '../hooks/useInputContainer';
 import {useInputGroup} from '../InputGroup/InputGroupContext';
 import {groupStyles} from '../InputGroup/groupStyles';
@@ -296,6 +299,13 @@ export interface TimeInputProps extends Omit<
    * If message is provided, displays below the input.
    */
   status?: InputStatus;
+  /**
+   * How the status message is placed relative to the input.
+   * - 'attached': message overlaps directly below the input (bordered treatment)
+   * - 'detached': message floats below as a separate element with spacing
+   * @default 'attached'
+   */
+  statusVariant?: FieldStatusVariant;
 
   /**
    * Width of the field. Numbers are treated as pixels, strings are used as-is
@@ -345,6 +355,7 @@ export function TimeInput({
   placeholder: placeholderFromProps,
   size: sizeProp,
   status,
+  statusVariant = 'attached',
   labelTooltip,
   width,
   xstyle,
@@ -369,6 +380,21 @@ export function TimeInput({
   const [optimisticValue, setOptimisticValue] = useOptimistic(value);
   const isBusy = isLoading || optimisticValue !== value;
 
+  // In grouped mode the status message renders as a visually-hidden node that
+  // exists only for aria-describedby. Announce it through the persistent
+  // useAnnounce live regions instead of role/aria-live on that node — a live
+  // region mounted together with its content is not reliably announced.
+  // Ungrouped mode delegates to Field -> FieldStatus, which announces itself.
+  const announce = useAnnounce();
+  useEffect(() => {
+    if (inputGroup && status?.message) {
+      announce(
+        status.message,
+        status.type === 'error' ? 'assertive' : 'polite',
+      );
+    }
+  }, [announce, inputGroup, status?.message, status?.type]);
+
   // 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
@@ -611,11 +637,7 @@ export function TimeInput({
         </VisuallyHidden>
       )}
       {inputGroup && status?.message && (
-        <VisuallyHidden
-          as="div"
-          id={statusMessageID}
-          role={status.type === 'error' ? 'alert' : 'status'}
-          aria-live={status.type === 'error' ? 'assertive' : 'polite'}>
+        <VisuallyHidden as="div" id={statusMessageID}>
           {status.message}
         </VisuallyHidden>
       )}
@@ -707,6 +729,7 @@ export function TimeInput({
             }
           : undefined
       }
+      statusVariant={statusVariant}
       labelTooltip={labelTooltip}
       width={width}>
       {inputWrapper}

package/src/Timestamp/Timestamp.doc.mjs

@@ -26,9 +26,9 @@ export const docs = {
     },
     {
       name: 'format',
-      type: "'relative' | 'auto' | 'date' | 'date_time' | 'time' | 'system_date' | 'system_date_time' | 'system_time'",
+      type: "'relative' | 'auto' | 'date' | 'date_long' | 'date_weekday' | 'date_time' | 'time' | 'system_date' | 'system_date_time' | 'system_time'",
       description:
-        "Display format. 'relative' shows '2 hours ago', 'date' shows 'Mar 21, 2025', 'date_time' shows 'Mar 21, 2025, 2:51 PM', 'time' shows '2:51 PM', 'system_*' variants use ISO-style formatting, 'auto' switches from relative to date_time based on recency.",
+        "Display format. 'relative' shows '2 hours ago', 'date' shows 'Mar 21, 2025', 'date_long' shows 'March 21, 2025', 'date_weekday' shows 'Wed, Mar 21, 2025', 'date_time' shows 'Mar 21, 2025, 2:51 PM', 'time' shows '2:51 PM', 'system_*' variants use ISO-style formatting, 'auto' switches from relative to date_time based on recency.",
       default: "'auto'",
     },
     {
@@ -110,7 +110,7 @@ export const docs = {
 export const docsZh = {
   propDescriptions: {
     value: '\u8981\u663e\u793a\u7684\u65e5\u671f/\u65f6\u95f4\u3002\u63a5\u53d7 Unix \u65f6\u95f4\u6233\uff08\u79d2\uff09\u6216 ISO 8601 \u5b57\u7b26\u4e32\u3002',
-    format: "\u663e\u793a\u683c\u5f0f\u3002'relative' \u663e\u793a '2\u5c0f\u65f6\u524d'\uff0c'date' \u663e\u793a\u65e5\u671f\uff0c'auto' \u6839\u636e\u65f6\u95f4\u8fdc\u8fd1\u81ea\u52a8\u5207\u6362\u3002",
+    format: "\u663e\u793a\u683c\u5f0f\u3002'relative' \u663e\u793a '2\u5c0f\u65f6\u524d'\uff0c'date' \u663e\u793a\u65e5\u671f\uff0c'date_long' \u663e\u793a\u957f\u6708\u4efd\u65e5\u671f\uff0c'date_weekday' \u663e\u793a\u661f\u671f+\u65e5\u671f\uff0c'auto' \u6839\u636e\u65f6\u95f4\u8fdc\u8fd1\u81ea\u52a8\u5207\u6362\u3002",
     autoThreshold: "auto \u683c\u5f0f\u4ece\u76f8\u5bf9\u65f6\u95f4\u5207\u6362\u5230 date_time \u7684\u9608\u503c\u79d2\u6570\u3002",
     hasTooltip: '\u60ac\u505c\u65f6\u662f\u5426\u663e\u793a\u5305\u542b\u5b8c\u6574\u65e5\u671f/\u65f6\u95f4\u7684\u5de5\u5177\u63d0\u793a\uff08\u76f8\u5bf9\u65f6\u95f4\u6a21\u5f0f\uff09\u3002',
     isTimezoneShown: '\u662f\u5426\u9644\u52a0\u65f6\u533a\u7f29\u5199\u3002',
@@ -157,7 +157,7 @@ export const docsDense = {
   },
   propDescriptions: {
     value: 'date/time as unix seconds or ISO string',
-    format: "display mode: 'relative', 'auto', 'date', 'date_time', 'time', 'system_date', 'system_date_time', 'system_time'",
+    format: "display mode: 'relative', 'auto', 'date', 'date_long', 'date_weekday', 'date_time', 'time', 'system_date', 'system_date_time', 'system_time'",
     autoThreshold: 'seconds threshold for auto relative\u2192date_time switch',
     hasTooltip: 'show full time tooltip on hover (relative mode)',
     isTimezoneShown: 'append timezone abbreviation',

package/src/Timestamp/Timestamp.test.tsx

@@ -99,6 +99,38 @@ describe('Timestamp', () => {
     expect(el.textContent).not.toContain(':');
   });
 
+  it('renders date_weekday format with a weekday prefix', () => {
+    render(
+      <Timestamp
+        value="2026-02-19T17:00:00Z"
+        format="date_weekday"
+        data-testid="ts"
+      />,
+    );
+    const el = screen.getByTestId('ts');
+    // Includes the year and a leading weekday abbreviation, no time portion.
+    expect(el.textContent).toContain('2026');
+    expect(el.textContent).not.toContain(':');
+    // en-US short weekday for 2026-02-19 is "Thu"; assert a weekday word is
+    // present without over-fitting the exact locale punctuation.
+    expect(el.textContent).toMatch(/Mon|Tue|Wed|Thu|Fri|Sat|Sun/);
+  });
+
+  it('renders date_long format with a full month name', () => {
+    render(
+      <Timestamp
+        value="2026-02-19T17:00:00Z"
+        format="date_long"
+        data-testid="ts"
+      />,
+    );
+    const el = screen.getByTestId('ts');
+    // Long-month shape: full month name, year, no time portion.
+    expect(el.textContent).toContain('February');
+    expect(el.textContent).toContain('2026');
+    expect(el.textContent).not.toContain(':');
+  });
+
   it('renders date_time format', () => {
     render(
       <Timestamp

package/src/Timestamp/Timestamp.tsx

@@ -21,9 +21,11 @@ import * as stylex from '@stylexjs/stylex';
 import {Text} from '../Text';
 import type {TextType, TextSize, TextColor, TextWeight} from '../theme/types';
 import {mergeProps, mergeRefs} from '../utils';
+import {useDevWarning} from '../hooks/useDevWarning';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
 import {colorVars} from '../theme/tokens.stylex';
+import {SHARED_DATE_FORMAT_OPTIONS} from '../utils/plainDate';
 
 const LazyXDSTooltip = lazy(async () =>
   import('../Tooltip/Tooltip').then(mod => ({default: mod.Tooltip})),
@@ -37,6 +39,8 @@ export type TimestampFormat =
   | 'relative'
   | 'auto'
   | 'date'
+  | 'date_long'
+  | 'date_weekday'
   | 'date_time'
   | 'time'
   | 'system_date'
@@ -53,6 +57,8 @@ export interface TimestampProps extends BaseProps<HTMLTimeElement> {
    * - `'relative'`: "2 hours ago", "yesterday", "now"
    * - `'auto'`: Relative for recent times, `date_time` for older
    * - `'date'`: "Mar 21, 2025"
+   * - `'date_long'`: "March 21, 2025"
+   * - `'date_weekday'`: "Wed, Mar 21, 2025"
    * - `'date_time'`: "Mar 21, 2025, 2:51 PM"
    * - `'time'`: "2:51 PM"
    * - `'system_date'`: "2025-03-21"
@@ -249,11 +255,22 @@ function formatTimestamp(
 ): string {
   switch (format) {
     case 'date':
-      return new Intl.DateTimeFormat(undefined, {
-        year: 'numeric',
-        month: 'short',
-        day: 'numeric',
-      }).format(date);
+      return new Intl.DateTimeFormat(
+        undefined,
+        SHARED_DATE_FORMAT_OPTIONS.date,
+      ).format(date);
+
+    case 'date_long':
+      return new Intl.DateTimeFormat(
+        undefined,
+        SHARED_DATE_FORMAT_OPTIONS.date_long,
+      ).format(date);
+
+    case 'date_weekday':
+      return new Intl.DateTimeFormat(
+        undefined,
+        SHARED_DATE_FORMAT_OPTIONS.date_weekday,
+      ).format(date);
 
     case 'date_time':
       return new Intl.DateTimeFormat(undefined, {
@@ -415,11 +432,14 @@ export function Timestamp({
     return () => clearInterval(timer);
   }, [isLive, isValidDate, effectiveFormat, diffSeconds]);
 
+  useDevWarning(
+    'Timestamp',
+    `could not parse value ${JSON.stringify(value)} as a date. Rendering nothing.`,
+    !isValidDate,
+  );
+
   // Placed after all hooks so the hook order stays stable across renders.
   if (!isValidDate) {
-    console.warn(
-      `Timestamp: could not parse value ${JSON.stringify(value)} as a date. Rendering nothing.`,
-    );
     return null;
   }
 

package/src/Toast/useToast.tsx

@@ -7,6 +7,7 @@ import {createRoot} from 'react-dom/client';
 import {dataAttr} from '../naming';
 import {ToastContext, type ToastContextValue} from './ToastContext';
 import {ToastViewport} from './ToastViewport';
+import {warnOnce} from '../utils/devWarning';
 import type {
   ToastOptions,
   ToastDismissFn,
@@ -17,7 +18,6 @@ import type {
 // Fallback singleton
 let fallbackContext: ToastContextValue | null = null;
 let fallbackRoot: ReturnType<typeof createRoot> | null = null;
-let fallbackWarned = false;
 
 const ROOT_THEME_ATTRS = ['data-theme', dataAttr('theme')] as const;
 
@@ -70,13 +70,12 @@ function getFallbackContext(): ToastContextValue {
     );
   }
 
-  if (!fallbackWarned) {
-    fallbackWarned = true;
-    console.warn(
-      'useToast: No LayerProvider found. Using fallback viewport. ' +
-        'Wrap your app with <LayerProvider> or <AppShell> for full control.',
-    );
-  }
+  warnOnce(
+    'toast-fallback-viewport',
+    'useToast',
+    'No LayerProvider found. Using fallback viewport. ' +
+      'Wrap your app with <LayerProvider> or <AppShell> for full control.',
+  );
 
   const container = document.createElement('div');
   container.setAttribute('data-astryx-toast-fallback', '');

package/src/ToggleButton/ToggleButtonGroup.tsx

@@ -41,7 +41,7 @@ interface ToggleButtonGroupContextValue {
   isDisabled?: boolean;
 }
 
-export const ToggleButtonGroupContext =
+const ToggleButtonGroupContext =
   createContext<ToggleButtonGroupContextValue | null>(null);
 ToggleButtonGroupContext.displayName = 'ToggleButtonGroupContext';
 

package/src/Tokenizer/Tokenizer.doc.mjs

@@ -31,7 +31,7 @@ export const docs = {
       name: 'onChange',
       type: '(items: T[], change: TokenizerChange<T>) => void',
       description:
-        "Called when selection changes. The change argument includes the affected item and type ('add' | 'create' | 'remove' | 'reorder').",
+        "Called when selection changes. The change argument includes the affected item and type ('add' | 'create' | 'remove' | 'reorder'). Additions and removals (including Backspace on an empty input) are announced to screen readers via a polite live region.",
       required: true,
     },
     {
@@ -88,6 +88,13 @@ export const docs = {
       description:
         'Validation status object with type and message for error/warning/success states.',
     },
+    {
+      name: 'statusVariant',
+      type: "'attached' | 'detached'",
+      description:
+        'How the status message is placed relative to the input. attached overlaps directly below the input (bordered treatment); detached floats below as a separate element with spacing.',
+      default: "'attached'",
+    },
     {
       name: 'isLabelHidden',
       type: 'boolean',
@@ -165,6 +172,13 @@ export const docs = {
       type: '(query: string) => void',
       description: 'Callback fired when the search query text changes.',
     },
+    {
+      name: 'startIcon',
+      type: 'ReactNode | IconType',
+      description:
+        'Icon to display at the start of the input, before any tokens. Accepts a semantic icon name, an SVG icon component, or a ReactNode directly.',
+      slotElements: [{__element: 'Icon', props: {icon: 'search', size: 'sm'}}],
+    },
     {
       name: 'endContent',
       type: 'ReactNode',
@@ -300,6 +314,13 @@ export const docsZh = {
       description:
         '\u9a8c\u8bc1\u72b6\u6001\u5bf9\u8c61\uff0c\u5305\u542b\u7c7b\u578b\u548c\u6d88\u606f\uff0c\u7528\u4e8e\u9519\u8bef/\u8b66\u544a/\u6210\u529f\u72b6\u6001\u3002',
     },
+    {
+      name: 'statusVariant',
+      type: "'attached' | 'detached'",
+      description:
+        '状态消息相对于输入框的放置方式。attached 直接叠加在输入框下方（带边框处理）；detached 作为独立元素浮于下方并留有间距。',
+      default: "'attached'",
+    },
     {
       name: 'isLabelHidden',
       type: 'boolean',
@@ -370,6 +391,12 @@ export const docsZh = {
       type: '(query: string) => void',
       description: '\u641c\u7d22\u67e5\u8be2\u6587\u672c\u53d8\u66f4\u65f6\u89e6\u53d1\u7684\u56de\u8c03\u3002',
     },
+    {
+      name: 'startIcon',
+      type: 'ReactNode | IconType',
+      description:
+        '\u5728\u8f93\u5165\u6846\u5f00\u5934\uff08token \u4e4b\u524d\uff09\u663e\u793a\u7684\u56fe\u6807\u3002\u63a5\u53d7\u8bed\u4e49\u56fe\u6807\u540d\u79f0\u3001SVG \u56fe\u6807\u7ec4\u4ef6\u6216\u76f4\u63a5\u4f20\u5165 ReactNode\u3002',
+    },
     {
       name: 'endContent',
       type: 'ReactNode',
@@ -448,6 +475,7 @@ export const docsDense = {
     isDisabled: 'Disables input+all token interactions.',
     htmlName: 'HTML name attr; one hidden input per selected item id.',
     status: 'Validation status w/ type+message for error/warning/success.',
+    statusVariant: 'How status message is placed: attached overlaps below input; detached floats below w/ spacing.',
     isLabelHidden: 'Visually hides label; keeps a11y.',
     description: 'Helper text below label.',
     isRequired: 'Marks field required.',
@@ -460,6 +488,7 @@ export const docsDense = {
     size: 'Input+token size.',
     debounceMs: 'Search debounce delay ms. 0 for sync sources.',
     onChangeQuery: 'Fired on search query text change.',
+    startIcon: 'Icon at input start, before tokens. Icon name, SVG component, or ReactNode.',
     endContent: 'Content at input row end. For buttons, counts, controls.',
     handleRef: 'Imperative handle for focus() and blur() control.',
     xstyle: 'StyleX layout styles (margins, positioning). Must be stylex.create() value.',