@astryxdesign/core 0.1.6 → 0.1.7-canary.0a6de96

package/src/Table/useTableGroupedRows.doc.mjs

@@ -7,7 +7,7 @@ export const docs = {
   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\u2019s data rows while keeping the header visible. Mirrors useTableRowExpansionState: the consumer owns the collapsedGroups set and the hook returns {data, plugin, idKey} \u2014 pass all three to Table (data, plugins, and idKey respectively).',
+    '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',
@@ -58,10 +58,10 @@ export const docs = {
 /** @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} \u2014 pass to Table data / plugins / idKey. Consumer owns the collapsedGroups set.',
+    '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\u2019s group key. Same key = same section.',
+    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>)'.",

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>

package/src/Toast/Toast.tsx

@@ -22,6 +22,7 @@ import {useTheme} from '../theme';
 import {MediaTheme} from '../theme/MediaTheme';
 import type {ToastType, ToastDismissReason} from './types';
 import {themeProps} from '../utils/themeProps';
+import {useTranslator} from '../i18n';
 
 const styles = stylex.create({
   root: {
@@ -115,6 +116,7 @@ export function Toast({
   isExiting = false,
   onDismiss,
 }: ToastProps) {
+  const t = useTranslator();
   const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const isPausedRef = useRef(false);
   const remainingRef = useRef(autoHideDuration);
@@ -226,7 +228,7 @@ export function Toast({
               variant="ghost"
               size="sm"
               icon={<Icon icon="close" size="sm" color="inherit" />}
-              label="Dismiss notification"
+              label={t('@astryx.toast.dismiss')}
               onClick={handleDismiss}
               isIconOnly
             />

package/src/Toast/ToastViewport.tsx

@@ -17,6 +17,7 @@ import {INTERACTIVE_SELECTORS} from '../hooks/useClickableContainer';
 import {Toast} from './Toast';
 import {ToastContext, type ToastContextValue} from './ToastContext';
 import type {ToastEntry, ToastPosition, ToastDismissReason} from './types';
+import {useTranslator} from '../i18n';
 
 const styles = stylex.create({
   viewport: {
@@ -107,6 +108,7 @@ export function ToastViewport({
   isTopLayer = true,
   children,
 }: ToastViewportProps) {
+  const t = useTranslator();
   const [toasts, setToasts] = useState<ToastEntry[]>([]);
   const [exitingIds, setExitingIds] = useState<Set<string>>(new Set());
   const toastsRef = useRef(toasts);
@@ -363,7 +365,7 @@ export function ToastViewport({
       <div
         ref={viewportRef}
         role="region"
-        aria-label="Notifications"
+        aria-label={t('@astryx.toast.viewport')}
         tabIndex={-1}
         // popover="manual" promotes to the top layer (above dialogs).
         // Omitted inside dialogs where the viewport is already in a top layer.

package/src/Token/Token.tsx

@@ -34,6 +34,7 @@ import {useLinkComponent} from '../Link/useLinkComponent';
 import {useInteractiveRole} from '../hooks/useInteractiveRole';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
+import {useTranslator} from '../i18n';
 
 // =============================================================================
 // Types
@@ -324,6 +325,7 @@ export function Token({
   'data-testid': testId,
   ref,
 }: TokenProps) {
+  const t = useTranslator();
   const LinkComponent = useLinkComponent();
   const role = useInteractiveRole({href, onClick, isDisabled});
 
@@ -342,7 +344,7 @@ export function Token({
       {onRemove != null && (
         <button
           type="button"
-          aria-label={`Remove ${label}`}
+          aria-label={t('@astryx.token.remove', {label})}
           onClick={e => {
             e.stopPropagation();
             onRemove(e);
@@ -432,7 +434,7 @@ export function Token({
         {onRemove != null && (
           <button
             type="button"
-            aria-label={`Remove ${label}`}
+            aria-label={t('@astryx.token.remove', {label})}
             onClick={e => {
               e.stopPropagation();
               onRemove(e);

package/src/Tokenizer/Tokenizer.doc.mjs

@@ -84,7 +84,7 @@ export const docs = {
     },
     {
       name: 'status',
-      type: 'InputStatus',
+      type: "{type: 'warning' | 'error' | 'success', message?: string}",
       description:
         'Validation status object with type and message for error/warning/success states.',
     },
@@ -296,7 +296,7 @@ export const docsZh = {
     },
     {
       name: 'status',
-      type: 'InputStatus',
+      type: "{type: 'warning' | 'error' | 'success', message?: string}",
       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',
     },

package/src/Tokenizer/Tokenizer.tsx

@@ -52,6 +52,7 @@ import {
 import type {SearchableItem, SearchSource} from '../Typeahead/types';
 import {mergeProps} from '../utils';
 import {themeProps} from '../utils/themeProps';
+import {useTranslator} from '../i18n';
 
 // Re-export status types for convenience
 export type {
@@ -81,9 +82,7 @@ export type TokenizerSize = 'sm' | 'md' | 'lg';
  * - `'unfocusedLayer'`: Shows a single line with "+ N more" when unfocused, expands as an overlay on focus.
  */
 export type TokenizerOverflowBehavior =
-  | 'none'
-  | 'unfocusedInline'
-  | 'unfocusedLayer';
+  'none' | 'unfocusedInline' | 'unfocusedLayer';
 
 /**
  * Imperative handle for Tokenizer handleRef.
@@ -403,6 +402,7 @@ export function Tokenizer<T extends SearchableItem>({
   ref,
   handleRef,
 }: TokenizerProps<T>) {
+  const t = useTranslator();
   const size = useSize(sizeProp, 'md');
   const inputId = useId();
   const descriptionId = useId();
@@ -786,7 +786,7 @@ export function Tokenizer<T extends SearchableItem>({
           {endContent}
           {hasClear && value.length > 0 && !isDisabled && (
             <InputClearButton
-              label="Clear all"
+              label={t('@astryx.tokenizer.clearAll')}
               onClick={e => {
                 e.stopPropagation();
                 handleClearAll();

package/src/Toolbar/Toolbar.doc.mjs

@@ -116,7 +116,7 @@ export const docs = {
         },
         {
           name: 'gap',
-          type: 'SpacingStep',
+          type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
           description: 'Gap between items within each slot.',
           default: '1',
         },

package/src/TopNav/TopNav.doc.mjs

@@ -109,6 +109,7 @@ export const docs = {
       name: 'label',
       type: 'string',
       description: 'Accessible label for the navigation landmark, applied as aria-label on the <nav> element.',
+      default: "'Top navigation'",
     },
     {
       name: 'xstyle',

package/src/TopNav/TopNav.test.tsx

@@ -13,6 +13,7 @@ import {describe, it, expect, vi} from 'vitest';
 import {render, screen} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {TopNav} from './TopNav';
+import {TopNavRenderContext} from './TopNavRenderContext';
 import {TopNavHeading} from './TopNavHeading';
 import {NavIcon} from '../NavIcon';
 import {TopNavItem} from './TopNavItem';
@@ -45,6 +46,35 @@ describe('TopNav', () => {
     );
   });
 
+  it('defaults the landmark label to "Top navigation" when label is omitted', () => {
+    render(<TopNav />);
+    expect(
+      screen.getByRole('navigation', {name: 'Top navigation'}),
+    ).toBeInTheDocument();
+  });
+
+  it('defaults the landmark label in mobile-bar mode', () => {
+    render(
+      <TopNavRenderContext value="mobile-bar">
+        <TopNav heading={<span>Logo</span>} />
+      </TopNavRenderContext>,
+    );
+    expect(
+      screen.getByRole('navigation', {name: 'Top navigation'}),
+    ).toBeInTheDocument();
+  });
+
+  it('custom label overrides the default in mobile-bar mode', () => {
+    render(
+      <TopNavRenderContext value="mobile-bar">
+        <TopNav label="Utility navigation" />
+      </TopNavRenderContext>,
+    );
+    expect(
+      screen.getByRole('navigation', {name: 'Utility navigation'}),
+    ).toBeInTheDocument();
+  });
+
   it('renders heading slot content', () => {
     render(<TopNav heading={<span data-testid="title-content">Logo</span>} />);
     expect(screen.getByTestId('title-content')).toBeInTheDocument();