@astryxdesign/core 0.1.3 → 0.1.4-canary.01e5b29

package/src/Table/plugins/sortable/useTableSortableState.tsx

@@ -168,14 +168,18 @@ function defaultCompare<T extends Record<string, unknown>>(
   const aVal = a[sortKey];
   const bVal = b[sortKey];
 
-  // null/undefined sort to the end
-  if (aVal == null && bVal == null) {
+  // null/undefined/NaN sort to the end. NaN must not reach the numeric fast
+  // path: a NaN comparator result reads as "equal" to Array.sort, which makes
+  // the comparator inconsistent and corrupts the order of the other rows.
+  const aMissing = aVal == null || (typeof aVal === 'number' && Number.isNaN(aVal));
+  const bMissing = bVal == null || (typeof bVal === 'number' && Number.isNaN(bVal));
+  if (aMissing && bMissing) {
     return 0;
   }
-  if (aVal == null) {
+  if (aMissing) {
     return 1;
   }
-  if (bVal == null) {
+  if (bMissing) {
     return -1;
   }
 

package/src/Table/tableContextMenu.test.tsx

@@ -99,9 +99,7 @@ describe('Table header context menu', () => {
         ],
       }),
     };
-    render(
-      <Table data={data} columns={columns} idKey="id" plugins={{a, b}} />,
-    );
+    render(<Table data={data} columns={columns} idKey="id" plugins={{a, b}} />);
     fireEvent.contextMenu(screen.getByText('Name'));
     expect(
       screen.getAllByRole('menuitem', {name: 'Action A', hidden: true}).length,
@@ -154,4 +152,30 @@ describe('Table body context menu', () => {
     fireEvent.click(items[0]);
     expect(onSelect).toHaveBeenCalledWith('1');
   });
+
+  it('trigger wrapper fills the full cell so the whole cell is right-clickable', () => {
+    const plugin: TablePlugin<Row> = {
+      transformBodyCell: props => ({
+        ...props,
+        contextMenuActions: [{id: 'act', label: 'Act', onSelect: () => {}}],
+      }),
+    };
+    render(
+      <Table data={data} columns={columns} idKey="id" plugins={{plugin}} />,
+    );
+    // The context-menu trigger wraps the cell content. It must fill the cell
+    // (block display + 100% width) so right-clicking anywhere in the cell —
+    // not just on the content — opens the menu. Regression test for the bug
+    // where only the wide first column responded to right-click.
+    const alice = screen.getByText('Alice');
+    const trigger = alice.closest('div');
+    expect(trigger).not.toBeNull();
+    expect(trigger?.className).toBeTruthy();
+    // The fillCell style sets inline-size:100% + display:block on the trigger.
+    const styleAttr = trigger?.getAttribute('class') ?? '';
+    // StyleX compiles to atomic classes; just assert the wrapper carries styles
+    // (the visual fill is covered by the compiled CSS). The key contract is
+    // that the trigger is a styled block wrapper, not a bare inline element.
+    expect(styleAttr.length).toBeGreaterThan(0);
+  });
 });

package/src/Table/tableContextMenu.tsx

@@ -16,6 +16,7 @@
 import {useState, type ReactNode} from 'react';
 import {ContextMenu, type ContextMenuOption} from '../ContextMenu';
 import {Icon} from '../Icon';
+import type {StyleXStyles} from '../theme/types';
 import type {TableContextAction, TableContextActions} from './types';
 
 /**
@@ -99,14 +100,17 @@ function toContextMenuOptions(
 function LazyTableContextMenu({
   element,
   getActions,
+  triggerXstyle,
 }: {
   element: ReactNode;
   getActions: () => TableContextAction[];
+  triggerXstyle?: StyleXStyles | StyleXStyles[];
 }): ReactNode {
   const [options, setOptions] = useState<ContextMenuOption[] | null>(null);
   return (
     <ContextMenu
       items={options ?? []}
+      triggerXstyle={triggerXstyle}
       onOpenChange={open => {
         // Resolve actions when opening; clear on close so state derived later
         // (e.g. current sort direction) is always fresh next open.
@@ -122,14 +126,24 @@ function LazyTableContextMenu({
  * context menu rendering the aggregated `actions`. Accepts a static array or a
  * getter (resolved lazily on open). When there are no actions the element is
  * returned untouched so the native browser menu passes through.
+ *
+ * `triggerXstyle` styles the right-click target wrapper. Cells pass a fill +
+ * padding style so the entire cell (padding included) opens the menu.
  */
 export function wrapInTableContextMenu(
   element: ReactNode,
   actions: TableContextActions | undefined,
+  triggerXstyle?: StyleXStyles | StyleXStyles[],
 ): ReactNode {
   // Getter form → resolve lazily on open.
   if (typeof actions === 'function') {
-    return <LazyTableContextMenu element={element} getActions={actions} />;
+    return (
+      <LazyTableContextMenu
+        element={element}
+        getActions={actions}
+        triggerXstyle={triggerXstyle}
+      />
+    );
   }
   if (!actions || actions.length === 0) {
     return element;
@@ -137,6 +151,10 @@ export function wrapInTableContextMenu(
   // item (it looked like "ascending" was always selected). Focus moves only
   // when the user arrow-keys into the menu.
   return (
-    <ContextMenu items={toContextMenuOptions(actions)}>{element}</ContextMenu>
+    <ContextMenu
+      items={toContextMenuOptions(actions)}
+      triggerXstyle={triggerXstyle}>
+      {element}
+    </ContextMenu>
   );
 }

package/src/Table/useTablePagination.doc.mjs

@@ -6,7 +6,10 @@ export const docs = {
   name: 'useTablePagination',
   subComponentOf: 'Table',
   displayName: 'useTablePagination',
-  description: 'Headless pagination plugin for Table. Supports client-side slicing, server-side pagination, and cursor-based pagination. Renders Pagination controls automatically above, below, or both.',
+  description: 'Headless pagination plugin for Table. Call with a config object: `useTablePagination({ page, onPageChange, totalItems })`. Returns a TablePlugin to pass to `<Table plugins={{ pagination: paginationPlugin }} />`.',
+  usage: {
+    description: 'Call useTablePagination with a config object containing page state and callback. Pass the returned plugin to Table via the plugins prop.',
+  },
   props: [
     {
       name: 'page',

package/src/Table/useTableRowExpansion.doc.mjs

@@ -0,0 +1,80 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+  name: 'useTableRowExpansion',
+  subComponentOf: 'Table',
+  displayName: 'useTableRowExpansion',
+  description:
+    'Hook that returns a TablePlugin implementing expandable rows with inherited columns. Child rows use the same columns as their parents, indented by depth. Clicking the chevron (or right-click context menu) toggles expansion. Pair with useTableRowExpansionState, which flattens the tree and derives this config (expand/collapse handlers + expand-all state) from a single expandedKeys set.',
+  props: [
+    {
+      name: 'expandedKeys',
+      type: 'Set<string>',
+      description: 'Set of currently-expanded row keys.',
+      required: true,
+    },
+    {
+      name: 'onToggle',
+      type: '(key: string) => void',
+      description: 'Called when a row expansion is toggled.',
+      required: true,
+    },
+    {
+      name: 'getRowKey',
+      type: '(item: T) => string',
+      description: 'Derive a stable unique key from a row item.',
+      required: true,
+    },
+    {
+      name: 'getChildren',
+      type: '(item: T) => T[]',
+      description: 'Return the children of a row (determines expandability).',
+      required: true,
+    },
+    {
+      name: 'getDepth',
+      type: '(item: T) => number',
+      description: 'Return the depth of a row in the hierarchy (0 = top-level). Used for indentation.',
+    },
+    {
+      name: 'getIsItemExpandable',
+      type: '(item: T) => boolean',
+      description: 'Control which rows are expandable. Defaults to checking getChildren length.',
+    },
+    {
+      name: 'hasRowClickExpansion',
+      type: 'boolean',
+      description: 'When true, clicking anywhere on the row toggles expansion.',
+      default: 'false',
+    },
+    {
+      name: 'isAllExpanded',
+      type: "boolean | 'indeterminate'",
+      description: 'State of the expand-all toggle in the header. Enables the header toggle button.',
+    },
+    {
+      name: 'onToggleExpandAll',
+      type: '(expand: boolean) => void',
+      description: 'Callback when the expand-all header toggle is clicked.',
+    },
+  ],
+};
+
+/** @type {import('../docs-types').TranslationDoc} */
+export const docsDense = {
+  description:
+    'Returns a TablePlugin for expandable rows w/ inherited columns. Child rows reuse parent columns, indented by depth. Chevron click (or right-click menu) toggles expansion. Pair w/ useTableRowExpansionState, which flattens the tree + derives this config from one expandedKeys set.',
+  propDescriptions: {
+    expandedKeys: 'Set of currently-expanded row keys.',
+    onToggle: 'Called when a row expansion is toggled.',
+    getRowKey: 'Derive a stable unique key from a row item.',
+    getChildren: 'Return children of a row; determines expandability.',
+    getDepth: 'Return depth of a row (0 = top-level). Used for indentation.',
+    getIsItemExpandable: 'Control which rows are expandable. Defaults to checking getChildren length.',
+    hasRowClickExpansion: 'If true, clicking anywhere on the row toggles expansion. Default false.',
+    isAllExpanded: 'State of the expand-all header toggle. Enables the header toggle button.',
+    onToggleExpandAll: 'Callback when the expand-all header toggle is clicked.',
+  },
+};

package/src/Table/useTableSortable.doc.mjs

@@ -6,7 +6,10 @@ export const docs = {
   name: 'useTableSortable',
   subComponentOf: 'Table',
   displayName: 'useTableSortable',
-  description: 'Headless multi-sort plugin for Table. The consumer owns sort state and provides a callback. Shift+click enables secondary sort columns. Sort indicators render in header cells automatically.',
+  description: 'Headless multi-sort plugin for Table. Call with a config object: `useTableSortable({ sort, onSortChange })`. Returns a TablePlugin to pass to `<Table plugins={{ sort: sortPlugin }} />`.',
+  usage: {
+    description: 'Call useTableSortable with a config object containing sort state and callback. Pass the returned plugin to Table via the plugins prop.',
+  },
   props: [
     {
       name: 'sort',

package/src/Text/Text.doc.mjs

@@ -16,7 +16,7 @@ export const docs = {
   theming: {
     targets: [
       {className: 'astryx-heading', visualProps: ['level', 'color']},
-      {className: 'astryx-text', visualProps: ['type', 'color']},
+      {className: 'astryx-text', visualProps: ['type', 'size', 'color']},
     ],
   },
   description: 'Semantic body text component that renders text with type-based styling from the theme, with optional truncation, decoration, and layout props.',
@@ -174,4 +174,4 @@ export const docsDense = {
       { guidance: false, description: 'Text for headings: use Heading with level (1\u20136).' },
     ],
   },
-};
+};

package/src/Text/Text.test.tsx

@@ -114,6 +114,17 @@ describe('Text', () => {
       expect(screen.getByText('Bold text')).toBeInTheDocument();
     });
 
+    it('reflects explicit size overrides for styling and theming', () => {
+      render(
+        <Text type="code" size="2xs">
+          Tiny code
+        </Text>,
+      );
+      const element = screen.getByText('Tiny code');
+      expect(element).toHaveAttribute('data-size', '2xs');
+      expect(element.className).toContain('size-2xs');
+    });
+
     it('accepts display prop', () => {
       render(
         <Text type="body" display="block">

package/src/Text/Text.tsx

@@ -32,6 +32,7 @@ import type {
 import {
   colorStyles,
   defaultWeightByTypeStyles,
+  sizeStyles,
   sizeByTypeStyles,
   weightStyles,
   displayStyles,
@@ -201,7 +202,7 @@ function resolveStyleType(type: TextType): BuiltinTextType {
  */
 export function Text({
   type = 'body',
-  size: _size,
+  size,
   color,
   weight,
   display = 'inline',
@@ -254,10 +255,11 @@ export function Text({
       <Component
         ref={mergeRefs(ref, truncation.ref, textRef)}
         {...mergeProps(
-          themeProps('text', {type, color: resolvedColor}),
+          themeProps('text', {type, size, color: resolvedColor}),
           stylex.props(
             colorStyles[resolvedColor],
             sizeByTypeStyles[styleType],
+            size && sizeStyles[size],
             defaultWeightByTypeStyles[styleType],
             weight && weightStyles[weight],
             // Display: use truncation styles when maxLines > 0

package/src/Text/text.stylex.ts

@@ -14,6 +14,7 @@ import * as stylex from '@stylexjs/stylex';
 import {
   colorVars,
   fontWeightVars,
+  textSizeVars,
   typeScaleVars,
   typographyVars,
 } from '../theme/tokens.stylex';
@@ -145,6 +146,46 @@ export const sizeByTypeStyles = stylex.create({
   },
 });
 
+// =============================================================================
+// Explicit Size Override
+// =============================================================================
+
+export const sizeStyles = stylex.create({
+  '4xs': {
+    fontSize: textSizeVars['--font-size-4xs'],
+  },
+  '3xs': {
+    fontSize: textSizeVars['--font-size-3xs'],
+  },
+  '2xs': {
+    fontSize: textSizeVars['--font-size-2xs'],
+  },
+  xsm: {
+    fontSize: textSizeVars['--font-size-xs'],
+  },
+  sm: {
+    fontSize: textSizeVars['--font-size-sm'],
+  },
+  base: {
+    fontSize: textSizeVars['--font-size-base'],
+  },
+  lg: {
+    fontSize: textSizeVars['--font-size-lg'],
+  },
+  xl: {
+    fontSize: textSizeVars['--font-size-xl'],
+  },
+  '2xl': {
+    fontSize: textSizeVars['--font-size-2xl'],
+  },
+  '3xl': {
+    fontSize: textSizeVars['--font-size-3xl'],
+  },
+  '4xl': {
+    fontSize: textSizeVars['--font-size-4xl'],
+  },
+});
+
 // =============================================================================
 // Baseline Size/Leading by Heading Level (from type-scale tokens)
 //

package/src/TextArea/TextArea.doc.mjs

@@ -74,7 +74,7 @@ export const docs = {
       name: 'disabledMessage',
       type: 'string',
       description:
-        'Explains why the textarea is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the textarea focusable via aria-disabled (the field becomes read-only). Use this instead of wrapping a disabled TextArea in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+        'Explains why the textarea is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the textarea focusable via aria-disabled (the field becomes read-only). Use this instead of wrapping a disabled TextArea in Tooltip. Disabled controls swallow the hover events an external Tooltip needs.',
     },
     {
       name: 'isLoading',

package/src/TextArea/TextArea.test.tsx

@@ -13,7 +13,7 @@ import {useState} from 'react';
 import {describe, it, expect, vi, beforeEach} from 'vitest';
 import {render, screen, fireEvent, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
-import {MagnifyingGlassIcon} from '@heroicons/react/24/outline';
+import {TestIcon} from '../__tests__/TestIcon';
 import {TextArea} from './TextArea';
 
 // Mock showPopover/hidePopover since jsdom does not implement them. Used by the
@@ -193,7 +193,7 @@ describe('TextArea', () => {
         label="Description"
         value=""
         onChange={() => {}}
-        startIcon={MagnifyingGlassIcon}
+        startIcon={TestIcon}
       />,
     );
     expect(screen.getByRole('textbox')).toBeInTheDocument();
@@ -577,7 +577,7 @@ describe('TextArea', () => {
           label="Notes"
           value=""
           onChange={() => {}}
-          startIcon={<MagnifyingGlassIcon />}
+          startIcon={<TestIcon />}
         />,
       );
 

package/src/TextInput/TextInput.doc.mjs

@@ -82,7 +82,7 @@ export const docs = {
       name: 'disabledMessage',
       type: 'string',
       description:
-        'Explains why the input is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the input focusable via aria-disabled (the field becomes read-only). Use this instead of wrapping a disabled TextInput in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+        'Explains why the input is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the input focusable via aria-disabled (the field becomes read-only). Use this instead of wrapping a disabled TextInput in Tooltip. Disabled controls swallow the hover events an external Tooltip needs.',
     },
     {
       name: 'isLoading',

package/src/TextInput/TextInput.test.tsx

@@ -12,7 +12,7 @@
 import {describe, it, expect, vi, beforeEach} from 'vitest';
 import {render, screen, fireEvent, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
-import {MagnifyingGlassIcon} from '@heroicons/react/24/outline';
+import {TestIcon} from '../__tests__/TestIcon';
 import {TextInput} from './TextInput';
 
 // Mock showPopover/hidePopover since jsdom does not implement them. Used by the
@@ -163,7 +163,7 @@ describe('TextInput', () => {
         label="Search"
         value=""
         onChange={() => {}}
-        startIcon={MagnifyingGlassIcon}
+        startIcon={TestIcon}
       />,
     );
     expect(screen.getByRole('textbox')).toBeInTheDocument();
@@ -482,7 +482,7 @@ describe('TextInput', () => {
           label="Search"
           value=""
           onChange={() => {}}
-          startIcon={<MagnifyingGlassIcon />}
+          startIcon={<TestIcon />}
         />,
       );
 

package/src/Thumbnail/Thumbnail.test.tsx

@@ -37,11 +37,45 @@ describe('Thumbnail', () => {
     expect(screen.getByRole('status')).toBeInTheDocument();
   });
 
-  it('uses label as accessible name on root', () => {
+  it('exposes the label as an accessible name via a valid group role', () => {
     render(<Thumbnail label="photo.png" data-testid="thumb" />);
-    expect(screen.getByTestId('thumb')).toHaveAttribute('aria-label', 'photo.png');
+    // The accessible name must be carried by a valid named role (group),
+    // not by a bare aria-label on a generic div (aria-prohibited-attr).
+    const group = screen.getByRole('group', {name: 'photo.png'});
+    expect(group).toBe(screen.getByTestId('thumb'));
   });
 
+  it('does not put aria-label on a generic (roleless) element', () => {
+    render(<Thumbnail label="photo.png" data-testid="thumb" />);
+    const thumb = screen.getByTestId('thumb');
+    // The labeled element must declare a role so the name is legitimate.
+    expect(thumb).toHaveAttribute('role', 'group');
+  });
+
+  it('keeps interactive children accessible while exposing the group name', () => {
+    const onRemove = vi.fn();
+    render(
+      <Thumbnail
+        src="/img.jpg"
+        alt="Clickable"
+        label="file.png"
+        onClick={vi.fn()}
+        onRemove={onRemove}
+      />,
+    );
+    // A group role (unlike img) must not hide descendant controls.
+    expect(
+      screen.getByRole('group', {name: 'file.png — Clickable'}),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByRole('button', {name: 'Open file.png — Clickable'}),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByRole('button', {name: 'Remove file.png — Clickable'}),
+    ).toBeInTheDocument();
+  });
+
+
   it('label is shown via tooltip, not as inline text', () => {
     render(<Thumbnail label="photo.png" data-testid="thumb" />);
     // Label should exist in DOM (tooltip) but not as a direct child text node

package/src/Thumbnail/Thumbnail.tsx

@@ -58,8 +58,9 @@ export interface ThumbnailProps extends BaseProps<HTMLDivElement> {
   alt?: string;
   /**
    * Accessible label for the thumbnail (e.g. file name).
-   * Not rendered visually — shown in a tooltip on hover and used
-   * as accessible name for the remove button.
+   * Not rendered visually — shown in a tooltip on hover, exposed as the
+   * accessible name of the thumbnail group, and used as the accessible
+   * name for the remove button.
    */
   label?: string;
   /**
@@ -296,6 +297,7 @@ export function Thumbnail({
     <div
       ref={ref}
       data-testid={testId}
+      role="group"
       aria-label={accessibleName}
       {...mergeProps(
         themeProps('thumbnail'),

package/src/TimeInput/TimeInput.doc.mjs

@@ -26,7 +26,7 @@ export const docs = {
       {
         guidance: true,
         description:
-          'Choose the hour format (12h or 24h) that matches your audience\'s locale; 12-hour with AM/PM for US-centric UIs, 24-hour for international or technical contexts.',
+          'Choose the hour format (12h or 24h) that matches your audience\'s locale: 12-hour with AM/PM for US-centric UIs, 24-hour for international or technical contexts.',
       },
       {
         guidance: true,
@@ -41,7 +41,7 @@ export const docs = {
       {
         guidance: true,
         description:
-          'Use the status prop to surface validation errors inline; show a message like "Time must be during business hours" so users know exactly what to fix.',
+          'Use the status prop to surface validation errors inline: show a message like "Time must be during business hours" so users know exactly what to fix.',
       },
       {
         guidance: true,
@@ -146,7 +146,7 @@ export const docs = {
       name: 'disabledMessage',
       type: 'string',
       description:
-        'Explains why the input is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the field focusable via aria-disabled (activation stays blocked). Use this instead of wrapping a disabled TimeInput in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+        'Explains why the input is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the field focusable via aria-disabled (activation stays blocked). Use this instead of wrapping a disabled TimeInput in Tooltip. Disabled controls swallow the hover events an external Tooltip needs.',
     },
     {
       name: 'value',
@@ -396,7 +396,7 @@ export const docsZh = {
       {
         guidance: true,
         description:
-          'Choose the hour format (12h or 24h) that matches your audience\'s locale; 12-hour with AM/PM for US-centric UIs, 24-hour for international or technical contexts.',
+          'Choose the hour format (12h or 24h) that matches your audience\'s locale: 12-hour with AM/PM for US-centric UIs, 24-hour for international or technical contexts.',
       },
       {
         guidance: true,
@@ -411,7 +411,7 @@ export const docsZh = {
       {
         guidance: true,
         description:
-          'Use the status prop to surface validation errors inline; show a message like "Time must be during business hours" so users know exactly what to fix.',
+          'Use the status prop to surface validation errors inline: show a message like "Time must be during business hours" so users know exactly what to fix.',
       },
       {
         guidance: true,
@@ -480,7 +480,7 @@ export const docsDense = {
       {
         guidance: true,
         description:
-          'Choose hour format (12h/24h) to match locale; 12h for US, 24h for international.',
+          'Choose hour format (12h/24h) to match locale: 12h for US, 24h for international.',
       },
       {
         guidance: true,
@@ -497,6 +497,11 @@ export const docsDense = {
         description: 'Use status prop for inline validation errors.',
       },
       {guidance: true, description: 'Enable hasClear for optional fields.'},
+      {
+        guidance: true,
+        description:
+          'Place inside InputGroup for a single-line prefix or suffix addon, like a label or timezone marker.',
+      },
       {
         guidance: false,
         description:

package/src/TimeInput/TimeInput.test.tsx

@@ -160,6 +160,43 @@ describe('TimeInput', () => {
     expect(onChange).not.toHaveBeenCalled();
   });
 
+  it('sets aria-invalid="true" when typed input is out of range', () => {
+    render(<TimeInput label="Time" onChange={() => {}} />);
+
+    const input = screen.getByRole('textbox');
+    fireEvent.change(input, {target: {value: '25:99'}});
+
+    expect(input).toHaveAttribute('aria-invalid', 'true');
+  });
+
+  it('does not set aria-invalid when typed input is a valid time', () => {
+    render(<TimeInput label="Time" onChange={() => {}} />);
+
+    const input = screen.getByRole('textbox');
+    fireEvent.change(input, {target: {value: '3:45 pm'}});
+
+    expect(input).not.toHaveAttribute('aria-invalid');
+  });
+
+  it('announces an alert message when typed input is invalid', () => {
+    render(<TimeInput label="Time" onChange={() => {}} />);
+
+    const input = screen.getByRole('textbox');
+    fireEvent.change(input, {target: {value: '25:99'}});
+
+    expect(screen.getByRole('alert')).toHaveTextContent('Invalid time');
+  });
+
+  it('does not announce an alert message when input is valid', () => {
+    render(<TimeInput label="Time" onChange={() => {}} />);
+
+    const input = screen.getByRole('textbox');
+    fireEvent.change(input, {target: {value: '3:45 pm'}});
+
+    expect(screen.getByRole('alert')).toHaveTextContent('');
+    expect(screen.queryByText('Invalid time')).not.toBeInTheDocument();
+  });
+
   it('calls onChange on blur when input is valid', async () => {
     const user = userEvent.setup();
     const onChange = vi.fn();

package/src/TimeInput/TimeInput.tsx

@@ -635,7 +635,9 @@ export function TimeInput({
         data-autofocus={hasAutoFocus || undefined}
         aria-describedby={ariaDescribedBy}
         aria-required={isRequired === true ? 'true' : undefined}
-        aria-invalid={status?.type === 'error' ? 'true' : undefined}
+        aria-invalid={
+          status?.type === 'error' || !isInputValid ? 'true' : undefined
+        }
         aria-busy={isBusy || undefined}
         aria-labelledby={ariaLabelledBy}
         {...stylex.props(
@@ -644,6 +646,14 @@ export function TimeInput({
           !isInputValid && styles.inputInvalid,
         )}
       />
+      {/*
+          Live region announcing invalid typed input to assistive technology.
+          The value silently reverts on blur, so without this a screen-reader
+          user would get no feedback that their entry was rejected (WCAG 3.3.1).
+        */}
+      <VisuallyHidden as="div" role="alert" aria-live="assertive">
+        {!isInputValid ? 'Invalid time' : ''}
+      </VisuallyHidden>
       {isBusy && <Spinner size="sm" />}
       {hasClear && value && !isDisabled && (
         <button

package/src/Timestamp/Timestamp.doc.mjs

@@ -84,7 +84,7 @@ export const docs = {
   ],
   theming: {
     targets: [
-      {className: 'astryx-timestamp', visualProps: ['type', 'color']},
+      {className: 'astryx-timestamp', visualProps: ['type', 'color', 'format']},
     ],
   },
   usage: {