@astryxdesign/core 0.1.5 → 0.1.6-canary.02f2602

package/src/Table/plugins/selection/useTableSelection.tsx

@@ -45,12 +45,9 @@ import * as stylex from '@stylexjs/stylex';
 import {colorVars} from '../../../theme/tokens.stylex';
 import {CheckboxInput} from '../../../CheckboxInput';
 import {mergeRefs} from '../../../utils';
-import type {
-  TablePlugin,
-  TableColumn,
-  BodyRowRenderProps,
-} from '../../types';
+import type {TablePlugin, TableColumn, BodyRowRenderProps} from '../../types';
 import {pixel} from '../../columnUtils';
+import {useTranslator} from '../../../i18n';
 
 // =============================================================================
 // Config Type
@@ -181,6 +178,7 @@ function SelectAllCheckboxInner<T extends Record<string, unknown>>({
 }: {
   store: SelectionStore<T>;
 }) {
+  const t = useTranslator();
   const getSnapshot = useCallback(() => {
     const config = store.getConfig();
     const allSelected = config.getIsAllSelected();
@@ -197,7 +195,7 @@ function SelectAllCheckboxInner<T extends Record<string, unknown>>({
 
   return (
     <CheckboxInput
-      label="Select all rows"
+      label={t('@astryx.table.selection.selectAllRows')}
       isLabelHidden
       value={allSelected ? true : indeterminate ? 'indeterminate' : false}
       onChange={() =>
@@ -232,6 +230,7 @@ function SelectionCellContentInner<T extends Record<string, unknown>>({
   store: SelectionStore<T>;
   item: T;
 }) {
+  const t = useTranslator();
   const config = store.getConfig();
   const isSelected = useIsItemSelected(store, item);
   const selectable = config.getIsItemSelectable?.(item) ?? true;
@@ -243,7 +242,7 @@ function SelectionCellContentInner<T extends Record<string, unknown>>({
 
   return (
     <CheckboxInput
-      label="Select row"
+      label={t('@astryx.table.selection.selectRow')}
       isLabelHidden
       value={isSelected}
       onChange={() =>

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

@@ -18,6 +18,7 @@ import * as stylex from '@stylexjs/stylex';
 import {colorVars, spacingVars, radiusVars} from '../../../theme/tokens.stylex';
 import {Icon} from '../../../Icon';
 import {resolveContextActions} from '../../tableContextMenu';
+import {useTranslator} from '../../../i18n';
 import type {
   TablePlugin,
   HeaderCellRenderProps,
@@ -344,6 +345,7 @@ export function useTableSortable<
   T extends Record<string, unknown>,
   TSortKey extends string = string,
 >(config: UseTableSortableConfig<TSortKey>): TablePlugin<T> {
+  const t = useTranslator();
   const configRef = useRef(config);
   configRef.current = config;
 
@@ -367,12 +369,13 @@ export function useTableSortable<
         // checked/clear state always reflects the latest sort.
         const getSortActions = (): TableContextAction[] => {
           const c = configRef.current;
-          const dir = c.sort.find(e => e.sortKey === sortKey)?.direction ?? null;
+          const dir =
+            c.sort.find(e => e.sortKey === sortKey)?.direction ?? null;
           const actions: TableContextAction[] = [
             {
               id: 'sort-asc',
               group: 'sort',
-              label: 'Sort ascending',
+              label: t('@astryx.table.sort.ascending'),
               icon: <Icon icon="arrowUp" size="xsm" aria-hidden />,
               checked: dir === 'ascending',
               onSelect: () =>
@@ -383,7 +386,7 @@ export function useTableSortable<
             {
               id: 'sort-desc',
               group: 'sort',
-              label: 'Sort descending',
+              label: t('@astryx.table.sort.descending'),
               icon: <Icon icon="arrowDown" size="xsm" aria-hidden />,
               checked: dir === 'descending',
               onSelect: () =>
@@ -396,7 +399,7 @@ export function useTableSortable<
             actions.push({
               id: 'sort-clear',
               group: 'sort-clear',
-              label: 'Clear sort',
+              label: t('@astryx.table.sort.clear'),
               icon: <Icon icon="close" size="xsm" aria-hidden />,
               onSelect: () =>
                 c.onSortChange(c.sort.filter(e => e.sortKey !== sortKey)),
@@ -430,6 +433,6 @@ export function useTableSortable<
         };
       },
     }),
-    [],
+    [t],
   );
 }

package/src/Table/useTableFiltering.doc.mjs

@@ -23,7 +23,7 @@ export const docs = {
     },
     {
       name: 'variant',
-      type: "'popover' | 'inline'",
+      type: "'popover' | 'inline' | 'inline-compact'",
       description: 'Display variant for filter controls.',
       default: "'popover'",
     },
@@ -50,7 +50,7 @@ export const docsZh = {
     },
     {
       name: 'variant',
-      type: "'popover' | 'inline'",
+      type: "'popover' | 'inline' | 'inline-compact'",
       description: '筛选控件的显示变体。',
       default: "'popover'",
     },

package/src/Table/useTableGroupedRows.doc.mjs

@@ -0,0 +1,71 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+  name: 'useTableGroupedRows',
+  subComponentOf: 'Table',
+  displayName: 'useTableGroupedRows',
+  description:
+    'Hook that groups a flat data array into collapsible section rows. Each distinct groupBy value becomes a full-width section-header row with a chevron toggle, the group label, and a member count; collapsing hides that group\'s data rows while keeping the header visible. Mirrors useTableRowExpansionState: the consumer owns the collapsedGroups set and the hook returns {data, plugin, idKey}: pass all three to Table (data, plugins, and idKey respectively).',
+  props: [
+    {
+      name: 'data',
+      type: 'T[]',
+      description: 'The flat data to group.',
+      required: true,
+    },
+    {
+      name: 'groupBy',
+      type: '(item: T) => string',
+      description:
+        'Derive the group key for a row. Rows with the same key share a section.',
+      required: true,
+    },
+    {
+      name: 'collapsedGroups',
+      type: 'Set<string>',
+      description: 'Set of currently-collapsed group keys.',
+      required: true,
+    },
+    {
+      name: 'onToggleGroup',
+      type: '(groupKey: string) => void',
+      description: 'Called with a group key when its header is toggled.',
+      required: true,
+    },
+    {
+      name: 'renderGroupHeader',
+      type: '(groupKey: string, count: number, collapsed: boolean) => ReactNode',
+      description:
+        "Custom renderer for a group header's content (right of the chevron). Defaults to `<groupKey> (<count>)`.",
+    },
+    {
+      name: 'getRowKey',
+      type: '(item: T) => string',
+      description:
+        'Stable key for a real row. Falls back to a positional key when omitted.',
+    },
+    {
+      name: 'groupOrder',
+      type: 'string[]',
+      description:
+        'Explicit group ordering; groups not listed keep first-seen order after these.',
+    },
+  ],
+};
+
+/** @type {import('../docs-types').TranslationDoc} */
+export const docsDense = {
+  description:
+    'Groups a flat data array into collapsible section rows. Each groupBy value becomes a full-width header (chevron + label + count); collapsing hides its rows. Returns {data, plugin, idKey}: pass to Table data / plugins / idKey. Consumer owns the collapsedGroups set.',
+  propDescriptions: {
+    data: 'The flat data to group.',
+    groupBy: 'Derive a row\'s group key. Same key = same section.',
+    collapsedGroups: 'Set of currently-collapsed group keys.',
+    onToggleGroup: 'Called with the group key when a header is toggled.',
+    renderGroupHeader: "Custom header content (right of chevron). Default '<key> (<count>)'.",
+    getRowKey: 'Stable key for a real row; positional fallback when omitted.',
+    groupOrder: 'Pin these group keys first; others keep first-seen order.',
+  },
+};

package/src/Table/useTableRowIndex.doc.mjs

@@ -0,0 +1,50 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+  name: 'useTableRowIndex',
+  subComponentOf: 'Table',
+  displayName: 'useTableRowIndex',
+  description:
+    'Hook that returns a TablePlugin which prepends a right-aligned, monospaced row-number column. Numbering follows the rendered data order (reflecting the current sort / filter / pagination view) and starts at 1 by default. Astryx renderCell receives only the row item, so the plugin takes the rendered data array to derive each ordinal.',
+  props: [
+    {
+      name: 'data',
+      type: 'T[]',
+      description:
+        'The data array currently rendered by the table (post sort/filter/page). Numbering follows this order.',
+      required: true,
+    },
+    {
+      name: 'getRowKey',
+      type: '(item: T) => string',
+      description:
+        'Optional key extractor returning a unique string per row. When provided, index lookup is keyed by the returned string; otherwise items are matched by reference identity. Memoize with useCallback for a stable plugin identity.',
+    },
+    {
+      name: 'label',
+      type: 'ReactNode',
+      description: 'Header label for the index column.',
+      default: "'#'",
+    },
+    {
+      name: 'startFrom',
+      type: 'number',
+      description: 'First index value.',
+      default: '1',
+    },
+  ],
+};
+
+/** @type {import('../docs-types').TranslationDoc} */
+export const docsDense = {
+  description:
+    'Returns a TablePlugin that prepends a right-aligned monospaced row-number column. Numbering follows the rendered data order (current sort/filter/page view), 1-based by default. Pass the rendered data array; renderCell only receives the item so the plugin derives ordinals from it.',
+  propDescriptions: {
+    data: 'The rendered data array (post sort/filter/page). Numbering follows this order.',
+    getRowKey: 'Optional key extractor returning a unique string per row; otherwise items match by reference.',
+    label: "Header label for the index column. Default '#'.",
+    startFrom: 'First index value. Default 1.',
+  },
+};

package/src/Table/useTableSortable.doc.mjs

@@ -13,20 +13,20 @@ export const docs = {
   props: [
     {
       name: 'sort',
-      type: 'TableSortState<TSortKey>',
-      description: 'Current sort state. Ordered array of {sortKey, direction} entries. First entry is the primary sort.',
+      type: "Array<{sortKey: TSortKey, direction: 'ascending' | 'descending'}>",
+      description: "Current sort state (TableSortState<TSortKey>). Ordered array of entries; the first is the primary sort, the rest are tiebreakers. An empty array means unsorted. Direction is the full word — 'ascending' / 'descending', not 'asc' / 'desc'.",
       required: true,
     },
     {
       name: 'onSortChange',
-      type: '(sort: TableSortState<TSortKey>) => void',
-      description: 'Called when the user clicks a header cell to change sort.',
+      type: "(sort: Array<{sortKey: TSortKey, direction: 'ascending' | 'descending'}>) => void",
+      description: 'Called when the user clicks a header cell to change sort. Receives the next sort state.',
       required: true,
     },
     {
       name: 'allowUnsortedState',
       type: 'boolean',
-      description: 'Allow cycling back to unsorted. When true: asc, desc, unsorted. When false: asc, desc, asc.',
+      description: "Allow cycling back to unsorted. When true: 'ascending', 'descending', unsorted. When false: 'ascending', 'descending', 'ascending'.",
       default: 'false',
     },
     {
@@ -45,20 +45,20 @@ export const docsZh = {
   props: [
     {
       name: 'sort',
-      type: 'TableSortState<TSortKey>',
-      description: '当前排序状态。{sortKey, direction} 条目的有序数组。第一个条目是主排序。',
+      type: "Array<{sortKey: TSortKey, direction: 'ascending' | 'descending'}>",
+      description: "当前排序状态。{sortKey, direction} 条目的有序数组。第一个条目是主排序。方向值为完整单词 'ascending' / 'descending'，不是 'asc' / 'desc'。",
       required: true,
     },
     {
       name: 'onSortChange',
-      type: '(sort: TableSortState<TSortKey>) => void',
+      type: "(sort: Array<{sortKey: TSortKey, direction: 'ascending' | 'descending'}>) => void",
       description: '用户点击表头单元格更改排序时调用。',
       required: true,
     },
     {
       name: 'allowUnsortedState',
       type: 'boolean',
-      description: '允许循环回到未排序状态。为 true 时：升序、降序、未排序。为 false 时：升序、降序、升序。',
+      description: "允许循环回到未排序状态。为 true 时：'ascending'、'descending'、未排序。为 false 时：'ascending'、'descending'、'ascending'。",
       default: 'false',
     },
     {
@@ -75,9 +75,9 @@ export const docsDense = {
   displayName: 'useTableSortable',
   description: 'Headless multi-sort plugin. Consumer owns sort state + callback. Shift+click for secondary sort. Sort indicators auto-render in header cells.',
   propDescriptions: {
-    sort: 'Current sort state; ordered array of {sortKey, direction} entries.',
+    sort: "Current sort state; ordered array of {sortKey, direction: 'ascending'|'descending'} entries. Not 'asc'/'desc'.",
     onSortChange: 'Called on header click to change sort.',
-    allowUnsortedState: 'Allow cycling to unsorted. true: asc>desc>unsorted. false: asc>desc>asc.',
+    allowUnsortedState: "Allow cycling to unsorted. true: ascending>descending>unsorted. false: ascending>descending>ascending.",
     isMultiSortEnabled: 'Enable multi-sort via Shift+click. Regular click replaces sort state.',
   },
 };

package/src/Text/Text.doc.mjs

@@ -23,8 +23,8 @@ export const docs = {
   props: [
     {
       name: 'type',
-      type: "'body' | 'large' | 'label' | 'supporting' | 'code' | 'display-1' | 'display-2' | 'display-3'",
-      description: 'Semantic text type. Determines size, weight, and line-height from the theme. Note: this prop is called `type`, not `variant`.',
+      type: "'body' | 'large' | 'label' | 'supporting' | 'code' | 'display-1' | 'display-2' | 'display-3' | 'inherit'",
+      description: "Semantic text type. Determines size, weight, and line-height from the theme. 'inherit' takes all three from the surrounding text instead. Themes may add custom types. Note: this prop is called `type`, not `variant`.",
       default: "'body'",
     },
     {

package/src/TextInput/TextInput.tsx

@@ -123,6 +123,7 @@ import {useInputGroup} from '../InputGroup/InputGroupContext';
 import type {BaseProps} from '../BaseProps';
 import type {SizeValue} from '../utils/types';
 import {themeProps} from '../utils/themeProps';
+import {useTranslator} from '../i18n';
 
 export type TextInputType = 'text' | 'password' | 'email';
 
@@ -298,6 +299,7 @@ export function TextInput({
   ref,
   ...rest
 }: TextInputProps) {
+  const t = useTranslator();
   const size = useSize(sizeProp, 'md');
 
   const id = useId();
@@ -448,7 +450,7 @@ export function TextInput({
         <button
           type="button"
           onClick={handleClear}
-          aria-label={`Clear ${label}`}
+          aria-label={t('@astryx.textInput.clearLabel', {label})}
           {...stylex.props(styles.clearButton)}>
           <Icon icon="close" size="sm" color="secondary" />
         </button>

package/src/Thumbnail/Thumbnail.tsx

@@ -40,6 +40,7 @@ import {useImageMode} from '../hooks/useImageMode';
 import type {BaseProps} from '../BaseProps';
 import {mergeProps} from '../utils';
 import {themeProps} from '../utils/themeProps';
+import {useTranslator} from '../i18n';
 
 /** Sample the region behind the remove button (20px button, 4px inset, in 64px container). */
 const BUTTON_REGION = {x: 0.5, y: 0.06, width: 0.44, height: 0.44};
@@ -252,6 +253,7 @@ export function Thumbnail({
   ref,
   ...props
 }: ThumbnailProps) {
+  const t = useTranslator();
   const imageMode = useImageMode(src, {region: BUTTON_REGION, fallback: null});
 
   const hasSrc = src != null;
@@ -281,7 +283,7 @@ export function Thumbnail({
     onRemove != null && !isDisabled ? (
       <Button
         icon={<Icon icon="close" size="xsm" />}
-        label={`Remove ${accessibleName}`}
+        label={t('@astryx.thumbnail.remove', {accessibleName})}
         variant="secondary"
         size="sm"
         isIconOnly
@@ -315,7 +317,7 @@ export function Thumbnail({
           <button
             type="button"
             onClick={onClick}
-            aria-label={`Open ${accessibleName}`}
+            aria-label={t('@astryx.thumbnail.open', {accessibleName})}
             {...stylex.props(styles.interactiveButton)}>
             {imageContent}
           </button>

package/src/TimeInput/TimeInput.doc.mjs

@@ -225,7 +225,7 @@ export const docs = {
     },
     {
       name: 'status',
-      type: 'InputStatus',
+      type: "{type: 'warning' | 'error' | 'success', message?: string}",
       description:
         'Status indicator that colors the border and displays an icon. When a message is provided it is rendered below the input.',
     },
@@ -368,7 +368,7 @@ export const docsZh = {
     },
     {
       name: 'status',
-      type: 'InputStatus',
+      type: "{type: 'warning' | 'error' | 'success', message?: string}",
       description:
         '为边框着色并显示图标的状态指示器。当提供消息时，消息渲染在输入框下方。',
     },

package/src/TimeInput/TimeInput.tsx

@@ -69,6 +69,7 @@ import {useInputGroup} from '../InputGroup/InputGroupContext';
 import {groupStyles} from '../InputGroup/groupStyles';
 import {useTooltip} from '../Tooltip';
 import {themeProps} from '../utils/themeProps';
+import {useTranslator} from '../i18n';
 
 const styles = stylex.create({
   icon: {
@@ -341,7 +342,7 @@ export function TimeInput({
   hasAutoFocus = false,
   hourFormat = '12h',
   increment = 1,
-  placeholder = 'Select a time',
+  placeholder: placeholderFromProps,
   size: sizeProp,
   status,
   labelTooltip,
@@ -351,6 +352,9 @@ export function TimeInput({
   style,
   ref,
 }: TimeInputProps) {
+  const t = useTranslator();
+  const placeholder =
+    placeholderFromProps ?? t('@astryx.timeInput.placeholder');
   const size = useSize(sizeProp, 'md');
 
   const id = useId();
@@ -659,7 +663,7 @@ export function TimeInput({
         <button
           type="button"
           onClick={handleClear}
-          aria-label={`Clear ${label}`}
+          aria-label={t('@astryx.timeInput.clearLabel', {label})}
           {...stylex.props(styles.clearButton)}>
           <Icon icon="close" size="sm" color="secondary" />
         </button>

package/src/Timestamp/Timestamp.doc.mjs

@@ -61,24 +61,24 @@ export const docs = {
     },
     {
       name: 'type',
-      type: 'TextType',
+      type: "'body' | 'large' | 'label' | 'supporting' | 'code' | 'display-1' | 'display-2' | 'display-3' | 'inherit'",
       description: 'Semantic text type from Text. Determines size, weight, and line-height.',
       default: "'supporting'",
     },
     {
       name: 'size',
-      type: 'TextSize',
+      type: "'4xs' | '3xs' | '2xs' | 'xsm' | 'sm' | 'base' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl'",
       description: 'Explicit font size override. Overrides the size from type.',
     },
     {
       name: 'color',
-      type: 'TextColor',
+      type: "'primary' | 'secondary' | 'disabled' | 'placeholder' | 'accent' | 'inherit'",
       description: 'Text color.',
       default: "'secondary'",
     },
     {
       name: 'weight',
-      type: 'TextWeight',
+      type: "'normal' | 'medium' | 'semibold' | 'bold'",
       description: 'Font weight override.',
     },
   ],

package/src/Timestamp/Timestamp.test.tsx

@@ -1,7 +1,8 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
-import {render, screen, act} from '@testing-library/react';
+import {render, screen, act, waitFor} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
 import {Timestamp} from './Timestamp';
 
 describe('Timestamp', () => {
@@ -41,9 +42,7 @@ describe('Timestamp', () => {
     );
     expect(screen.getByText('59 minutes ago')).toBeInTheDocument();
 
-    rerender(
-      <Timestamp value={Date.now() / 1000 - 86399} format="relative" />,
-    );
+    rerender(<Timestamp value={Date.now() / 1000 - 86399} format="relative" />);
     expect(screen.getByText('23 hours ago')).toBeInTheDocument();
 
     rerender(
@@ -52,9 +51,7 @@ describe('Timestamp', () => {
     expect(screen.getByText('29 days ago')).toBeInTheDocument();
 
     // Same guarantee on the future side.
-    rerender(
-      <Timestamp value={Date.now() / 1000 + 3599} format="relative" />,
-    );
+    rerender(<Timestamp value={Date.now() / 1000 + 3599} format="relative" />);
     expect(screen.getByText('in 59 minutes')).toBeInTheDocument();
   });
 
@@ -342,4 +339,120 @@ describe('Timestamp', () => {
       warn.mockRestore();
     }
   });
+
+  // --- Tooltip keyboard reachability (WCAG 1.4.13 / 2.1.1) ---
+
+  describe('tooltip keyboard reachability', () => {
+    const originalMatches = HTMLElement.prototype.matches;
+    const originalShowPopover = HTMLElement.prototype.showPopover;
+    const originalHidePopover = HTMLElement.prototype.hidePopover;
+
+    beforeEach(() => {
+      // The tooltip is lazy-loaded via a dynamic import; real timers let the
+      // import promise and RTL's waitFor resolve naturally (the outer
+      // beforeEach installs fake timers, which would stall them).
+      vi.useRealTimers();
+
+      // Mock the Popover API, which jsdom does not implement.
+      HTMLElement.prototype.showPopover = vi.fn();
+      HTMLElement.prototype.hidePopover = vi.fn();
+
+      // jsdom does not derive :focus-visible from keyboard focus for a <time>
+      // element; treat the focused element as focus-visible so the tooltip's
+      // keyboard-focus path can be exercised.
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      (HTMLElement.prototype as any).matches = function (
+        selector: string,
+      ): boolean {
+        if (selector === ':focus-visible') {
+          return this === document.activeElement;
+        }
+        return originalMatches.call(this, selector);
+      };
+    });
+
+    afterEach(() => {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      (HTMLElement.prototype as any).matches = originalMatches;
+      HTMLElement.prototype.showPopover = originalShowPopover;
+      HTMLElement.prototype.hidePopover = originalHidePopover;
+    });
+
+    it('makes the <time> element focusable while the tooltip is attached', () => {
+      render(
+        <Timestamp
+          value={Date.now() / 1000 - 3600}
+          format="relative"
+          data-testid="ts"
+        />,
+      );
+      expect(screen.getByTestId('ts')).toHaveAttribute('tabindex', '0');
+    });
+
+    it('shows the tooltip when the timestamp receives keyboard focus', async () => {
+      const user = userEvent.setup();
+      render(
+        <Timestamp
+          value={Date.now() / 1000 - 3600}
+          format="relative"
+          data-testid="ts"
+        />,
+      );
+      const el = screen.getByTestId('ts');
+
+      // Wait for the lazy-loaded tooltip layer to mount and confirm it
+      // carries the full absolute time (same string as the aria-label).
+      // Compare with normalized whitespace: Intl output can contain narrow
+      // no-break spaces that jest-dom's matcher normalization would break on.
+      const layer = await screen.findByRole('tooltip', {hidden: true});
+      const normalize = (s: string) => s.replace(/\s+/g, ' ');
+      expect(normalize(layer.textContent ?? '')).toContain(
+        normalize(el.getAttribute('aria-label') ?? '\0'),
+      );
+
+      // Tab onto the timestamp — the only tab stop in the document.
+      await user.tab();
+      expect(el).toHaveFocus();
+      await waitFor(() => {
+        expect(HTMLElement.prototype.showPopover).toHaveBeenCalled();
+      });
+    });
+
+    it('does not add a tab stop when the tooltip is disabled', () => {
+      render(
+        <Timestamp
+          value={Date.now() / 1000 - 3600}
+          format="relative"
+          hasTooltip={false}
+          data-testid="ts"
+        />,
+      );
+      expect(screen.getByTestId('ts')).not.toHaveAttribute('tabindex');
+    });
+
+    it('does not add a tab stop for absolute formats (no tooltip)', () => {
+      render(
+        <Timestamp
+          value="2026-02-19T17:00:00Z"
+          format="date_time"
+          data-testid="ts"
+        />,
+      );
+      expect(screen.getByTestId('ts')).not.toHaveAttribute('tabindex');
+    });
+
+    it('keeps the full absolute aria-label while the tooltip is attached', () => {
+      render(
+        <Timestamp
+          value={Date.now() / 1000 - 3600}
+          format="relative"
+          data-testid="ts"
+        />,
+      );
+      const label = screen.getByTestId('ts').getAttribute('aria-label');
+      expect(label).toBeTruthy();
+      // The label is the full absolute string, not the relative text.
+      expect(label).not.toContain('ago');
+    });
+  });
 });

package/src/Timestamp/Timestamp.tsx

@@ -23,6 +23,7 @@ import type {TextType, TextSize, TextColor, TextWeight} from '../theme/types';
 import {mergeProps, mergeRefs} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
+import {colorVars} from '../theme/tokens.stylex';
 
 const LazyXDSTooltip = lazy(async () =>
   import('../Tooltip/Tooltip').then(mod => ({default: mod.Tooltip})),
@@ -118,6 +119,18 @@ const styles = stylex.create({
     color: 'inherit',
     fontWeight: 'inherit',
   },
+  // Visible focus ring for the tooltip tab stop, matching the repo-wide
+  // focus-visible outline treatment (see Token, Thumbnail).
+  focusable: {
+    outline: {
+      default: null,
+      ':focus-visible': `2px solid ${colorVars['--color-accent']}`,
+    },
+    outlineOffset: {
+      default: '0',
+      ':focus-visible': '2px',
+    },
+  },
 });
 
 // =============================================================================
@@ -431,8 +444,15 @@ export function Timestamp({
         aria-label={
           effectiveFormat === 'relative' ? fullAbsoluteText : undefined
         }
+        // The absolute-time tooltip is anchored here with the default 'auto'
+        // focus trigger, which only activates on focusable anchors. A bare
+        // <time> is not focusable, so without a tab stop sighted keyboard
+        // users could never reveal the tooltip (WCAG 1.4.13 / 2.1.1). Only
+        // add the tab stop while a tooltip is actually attached — no
+        // gratuitous tab stops otherwise.
+        tabIndex={showTooltip ? 0 : undefined}
         data-testid={testId}
-        {...stylex.props(styles.time)}>
+        {...stylex.props(styles.time, showTooltip && styles.focusable)}>
         {displayText}
       </time>
     </Text>