@astryxdesign/core 0.5.0 → 0.5.1-canary.046f6ea

package/src/TextArea/TextArea.tsx

@@ -556,12 +556,18 @@ export function TextArea({
         onClick={handleWrapperClick}
         onMouseUp={handleWrapperMouseUp}
         {...mergeProps(
-          themeProps('textarea', {
-            size,
-            status: status?.type ?? null,
-            disabled: isDisabled ? 'disabled' : null,
-            readonly: isReadOnly ? 'readonly' : null,
-          }),
+          themeProps(
+            'text-area',
+            {
+              size,
+              status: status?.type ?? null,
+              disabled: isDisabled ? 'disabled' : null,
+              readonly: isReadOnly ? 'readonly' : null,
+            },
+            // `textarea` ran the compound name together; themes styling it
+            // keep working until the next major.
+            {legacyNames: ['textarea']},
+          ),
           stylex.props(
             inputWrapperStyles.base,
             styles.wrapper,
@@ -609,19 +615,22 @@ export function TextArea({
               : undefined
           }
           aria-busy={isBusy || undefined}
-          {...stylex.props(
-            styles.textarea,
-            textareaSizeStyles[size],
-            isDisabled && styles.textareaDisabled,
-            Boolean(startIcon) && styles.textareaWithStartIcon,
-            // Reserve trailing space only when the end slot actually renders
-            // something (spinner or on-field status icon). The `detached`
-            // status variant suppresses the on-field icon — its glyph lives in
-            // the message box below — so reserving here would inset the text
-            // for an icon that never appears.
-            (isBusy || statusIcon != null) && styles.textareaWithStatus,
-            isBusy && statusIcon != null && styles.textareaWithBusyStatus,
-            maxLength != null && styles.textareaWithCounter,
+          {...mergeProps(
+            themeProps('text-area-control'),
+            stylex.props(
+              styles.textarea,
+              textareaSizeStyles[size],
+              isDisabled && styles.textareaDisabled,
+              Boolean(startIcon) && styles.textareaWithStartIcon,
+              // Reserve trailing space only when the end slot actually renders
+              // something (spinner or on-field status icon). The `detached`
+              // status variant suppresses the on-field icon — its glyph lives
+              // in the message box below — so reserving here would inset the
+              // text for an icon that never appears.
+              (isBusy || statusIcon != null) && styles.textareaWithStatus,
+              isBusy && statusIcon != null && styles.textareaWithBusyStatus,
+              maxLength != null && styles.textareaWithCounter,
+            ),
           )}
         />
         {(isBusy || statusIcon) && (
@@ -633,9 +642,12 @@ export function TextArea({
         {maxLength != null && (
           <div
             id={counterID}
-            {...stylex.props(
-              styles.counter,
-              valueLength > maxLength && styles.counterError,
+            {...mergeProps(
+              themeProps('text-area-counter'),
+              stylex.props(
+                styles.counter,
+                valueLength > maxLength && styles.counterError,
+              ),
             )}>
             {valueLength > maxLength && (
               // Non-color cue so the over-limit state isn't conveyed by the red

package/src/TextInput/TextInput.doc.mjs

@@ -5,7 +5,7 @@
 export const docs = {
   name: 'TextInput',
   displayName: 'Text Input',
-  category: 'Data Input',
+  category: 'Form Controls',
   keywords: ["textinput","textfield","input","search","clearable","prefix","suffix","adornment","validation"],
   props: [
     {

package/src/TimeInput/TimeInput.doc.mjs

@@ -5,7 +5,7 @@
 export const docs = {
   name: 'TimeInput',
   displayName: 'Time Input',
-  category: 'Data Input',
+  category: 'Form Controls',
   keywords: [
     'timeinput',
     'timepicker',

package/src/Timestamp/Timestamp.test.tsx

@@ -12,6 +12,7 @@ import {
 import {render, screen, act, waitFor, fireEvent} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {Timestamp} from './Timestamp';
+import {formatInstant} from './formatInstant';
 import {formatTooltipLines} from './tooltipEntries';
 import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
 import {InternationalizationProvider} from '../i18n';
@@ -277,6 +278,36 @@ describe('Timestamp', () => {
     expect(screen.getByTestId('ts')).toHaveTextContent('25. Januar 2026');
   });
 
+  it.each(['full', 'date', 'date_long', 'date_weekday', 'date_time'] as const)(
+    'keeps Gregorian years for the %s format under a non-Gregorian locale',
+    format => {
+      const value = formatInstant(
+        new Date('2026-08-22T12:00:00Z'),
+        format,
+        'th-TH',
+        {timeZone: 'UTC'},
+      );
+      expect(value).toContain('2026');
+      expect(value).not.toContain('2569');
+    },
+  );
+
+  it('keeps Gregorian years in Timestamp output under a non-Gregorian locale', () => {
+    render(
+      <InternationalizationProvider locale="th-TH">
+        <Timestamp
+          value="2026-08-22T12:00:00Z"
+          format="date_long"
+          hasTooltip={false}
+          data-testid="ts"
+        />
+      </InternationalizationProvider>,
+    );
+
+    expect(screen.getByTestId('ts')).toHaveTextContent('2026');
+    expect(screen.getByTestId('ts')).not.toHaveTextContent('2569');
+  });
+
   it('renders date format', () => {
     render(
       <Timestamp value="2026-02-19T17:00:00Z" format="date" data-testid="ts" />,
@@ -673,6 +704,24 @@ describe('Timestamp', () => {
       expect(screen.getByTestId('ts')).toHaveAttribute('tabindex', '0');
     });
 
+    it('does not put aria-expanded on the role-less hover-card trigger', async () => {
+      render(
+        <Timestamp
+          value={Date.now() / 1000 - 3600}
+          format="relative"
+          data-testid="ts"
+        />,
+      );
+      const trigger = screen.getByTestId('ts').parentElement;
+      // The trigger is Text's <span>, which has no role, so aria-expanded is
+      // invalid on it (axe aria-allowed-attr, critical). aria-haspopup is
+      // global and still advertises the dialog.
+      await waitFor(() => {
+        expect(trigger).toHaveAttribute('aria-haspopup', 'dialog');
+      });
+      expect(trigger).not.toHaveAttribute('aria-expanded');
+    });
+
     it('shows the hover card when the timestamp receives keyboard focus', async () => {
       const user = userEvent.setup();
       render(
@@ -1305,3 +1354,43 @@ describe('Timestamp', () => {
     });
   });
 });
+
+describe('Timestamp pass-through props', () => {
+  it('forwards pass-through props to the time element', () => {
+    render(
+      <Timestamp
+        value="2024-01-15T10:30:00Z"
+        format="date_time"
+        aria-label="Published"
+        id="published-at"
+        data-source="cms"
+        data-testid="stamp"
+      />,
+    );
+    const time = screen.getByTestId('stamp');
+    expect(time.tagName).toBe('TIME');
+    expect(time).toHaveAttribute('aria-label', 'Published');
+    expect(time).toHaveAttribute('id', 'published-at');
+    expect(time).toHaveAttribute('data-source', 'cms');
+  });
+
+  it('keeps its own spelled-out label on a relative timestamp', () => {
+    render(
+      <Timestamp
+        value={Date.now()}
+        format="relative"
+        aria-label="Caller label"
+        data-source="cms"
+        data-testid="stamp"
+      />,
+    );
+    const stamp = screen.getByTestId('stamp');
+    expect({
+      ariaLabel: stamp.getAttribute('aria-label'),
+      dataSource: stamp.getAttribute('data-source'),
+    }).toEqual({
+      ariaLabel: expect.not.stringMatching(/^Caller label$/),
+      dataSource: 'cms',
+    });
+  });
+});

package/src/Timestamp/Timestamp.tsx

@@ -419,6 +419,7 @@ export function Timestamp({
   style,
   ref,
   'data-testid': testId,
+  ...rest
 }: TimestampProps) {
   const t = useTranslator();
   const locale = useLocale();
@@ -530,15 +531,16 @@ export function Timestamp({
       <time
         ref={mergedTimeRef}
         dateTime={isoString}
+        data-testid={testId}
+        {...stylex.props(styles.time)}
+        {...rest}
         // `ariaLabelText` is '' only for an invalid date, which bails out
         // before rendering — but keep the guard local: an empty aria-label
         // must be omitted entirely (not rendered as aria-label="") so AT
         // falls back to reading the visible <time> content.
-        aria-label={
-          isRelativeFormat(effectiveFormat) && ariaLabelText !== ''
-            ? ariaLabelText
-            : undefined
-        }
+        {...(isRelativeFormat(effectiveFormat) && ariaLabelText !== ''
+          ? {'aria-label': ariaLabelText}
+          : {})}
         // The hover card is anchored here with focusTrigger="always", which
         // attaches focus listeners but does not itself make the anchor
         // focusable. A bare <time> is not focusable, so without a tab stop
@@ -547,9 +549,7 @@ export function Timestamp({
         // gratuitous tab stops otherwise. The card carries its own
         // dashed-underline hover indication as the affordance, so the anchor
         // needs no separate focus outline.
-        tabIndex={showTooltip ? 0 : undefined}
-        data-testid={testId}
-        {...stylex.props(styles.time)}>
+        {...(showTooltip ? {tabIndex: 0} : {})}>
         {displayText}
       </time>
     </Text>

package/src/Timestamp/formatInstant.ts

@@ -182,24 +182,28 @@ export function formatInstant(
         ...FULL_OPTIONS,
         timeZoneName: timeZoneNameStyle,
         ...zone,
+        calendar: 'gregory',
       }).format(date);
 
     case 'date':
       return new Intl.DateTimeFormat(locale, {
         ...SHARED_DATE_FORMAT_OPTIONS.date,
         ...zone,
+        calendar: 'gregory',
       }).format(date);
 
     case 'date_long':
       return new Intl.DateTimeFormat(locale, {
         ...SHARED_DATE_FORMAT_OPTIONS.date_long,
         ...zone,
+        calendar: 'gregory',
       }).format(date);
 
     case 'date_weekday':
       return new Intl.DateTimeFormat(locale, {
         ...SHARED_DATE_FORMAT_OPTIONS.date_weekday,
         ...zone,
+        calendar: 'gregory',
       }).format(date);
 
     case 'date_time':
@@ -207,6 +211,7 @@ export function formatInstant(
         ...DATE_TIME_OPTIONS,
         ...zoneName,
         ...zone,
+        calendar: 'gregory',
       }).format(date);
 
     case 'time':

package/src/Toast/Toast.doc.mjs

@@ -8,7 +8,15 @@ export const docs = {
   group: 'Toast',
   category: 'Overlay',
   hiddenComponents: ['ToastViewport'],
-  keywords: ["toast","notification","snackbar","alert","message","feedback","status"],
+  keywords: [
+    'toast',
+    'notification',
+    'snackbar',
+    'alert',
+    'message',
+    'feedback',
+    'status',
+  ],
 
   props: [
     {
@@ -16,29 +24,35 @@ export const docs = {
       type: 'ReactNode',
       description: 'Primary message content.',
       required: true,
-      slotElements: [{__element: 'Text', props: {type: 'body'}, children: 'Toast message'}],
+      slotElements: [
+        {__element: 'Text', props: {type: 'body'}, children: 'Toast message'},
+      ],
     },
     {
       name: 'type',
       type: "'info' | 'error'",
-      description: 'Toast type controlling background color. Error toasts persist until dismissed.',
+      description:
+        'Toast type controlling background color. Error toasts persist until dismissed.',
       default: "'info'",
     },
     {
       name: 'isAutoHide',
       type: 'boolean',
-      description: 'Whether the toast auto-dismisses. Defaults to true for info, false for error.',
+      description:
+        'Whether the toast auto-dismisses. Defaults to true for info, false for error.',
     },
     {
       name: 'autoHideDuration',
       type: 'number',
-      description: 'Duration in ms before auto-dismiss.',
+      description:
+        'Duration in ms before auto-dismiss. Timed content must satisfy WCAG 2.2.1.',
       default: '5000',
     },
     {
       name: 'endContent',
       type: 'ReactNode',
-      description: 'Content rendered at the trailing end (e.g. Undo button, link).',
+      description:
+        'Content rendered at the trailing end (e.g. Undo button, link). Keep action labels short.',
       slotElements: [
         {__element: 'Icon', props: {icon: 'chevronDown', size: 'sm'}},
         {__element: 'Badge', props: {label: '3'}},
@@ -52,7 +66,8 @@ export const docs = {
     {
       name: 'collisionBehavior',
       type: "'overwrite' | 'ignore'",
-      description: 'Behavior when a toast with matching uniqueID already exists.',
+      description:
+        'Behavior when a toast with matching uniqueID already exists.',
       default: "'overwrite'",
     },
     {
@@ -66,28 +81,109 @@ export const docs = {
       description: 'Callback fired when the toast is dismissed.',
       required: true,
     },
-  ],  theming: {
-    targets: [
-      {className: 'astryx-toast', visualProps: ['type']},
+    {
+      name: 'renderContent',
+      type: '(toast: ToastContentRenderProps) => ReactNode',
+      description:
+        "Replaces the content of this toast's card with your own layout. Astryx keeps the card, its astryx-toast theme target, the live-region role and auto-hide behavior, then hands the renderer the message, endContent, resolved toast settings and a dismiss callback. The custom renderer owns every control in its layout: compose the control you want and call dismiss from it. Astryx does not inject a fallback close into custom content. Per-toast: an app shares one layout by wrapping useToast and passing it on every call, while a toast raised by library code that never passes it renders as an ordinary Astryx toast. The argument is {body, endContent, type, isAutoHide, autoHideDuration, dismiss}, where type is 'info' | 'error'.",
+    },
+  ],
+  theming: {
+    targets: [{className: 'astryx-toast', visualProps: ['type']}],
+    vars: [
+      {
+        name: '--_toast-slide-y',
+        description:
+          'Private block-axis offset inherited from ToastViewport for entry and exit motion',
+        default: 'var(--spacing-2)',
+        private: true,
+      },
+      {
+        name: '--_toast-swipe-y',
+        description: 'Private active swipe offset along the block axis',
+        default: '0px',
+        private: true,
+      },
+      {
+        name: '--_toast-swipe-exit-y',
+        description: 'Private completed-swipe exit offset',
+        default: 'var(--_toast-swipe-y)',
+        private: true,
+      },
+      {
+        name: '--_toast-swipe-opacity',
+        description: 'Private opacity feedback during an accepted swipe',
+        default: '1',
+        private: true,
+      },
+      {
+        name: '--_toast-swipe-scale',
+        description: 'Private scale feedback during an accepted swipe',
+        default: '1',
+        private: true,
+      },
     ],
   },
 
   usage: {
     description:
-      'Toast shows a brief, non-blocking notification to confirm an action or present temporary information. Use it for scenarios where the user needs feedback but not a decision, such as saving, deleting, or changing a status.\n\nFor production use, prefer the `useToast()` hook; it handles positioning, stacking, auto-dismiss, and deduplication via `ToastViewport`. The `Toast` component renders the visual toast element inline and is useful for previews, documentation, and static showcases where the viewport lifecycle is not needed.',
+      'Toast shows a brief, non-blocking notification to confirm an action or present temporary information. Use it for scenarios where the user needs feedback but not a decision, such as saving, deleting, or changing a status.\n\nFor production use, prefer the `useToast()` hook; it handles positioning, stacking, auto-dismiss, and deduplication via `ToastViewport`. Toasts stay within viewport and safe-area gutters, wrap long message content, and enter, exit, or swipe-dismiss toward their configured top or bottom edge. The vertical swipe uses the same spatial model as placement motion: top Toasts leave upward and bottom Toasts leave downward. Swipe waits for dominant edge-directed intent before cancelling native touch movement and reports the existing manual dismissal reason. Pen is supported as direct-contact input; mouse drag is excluded to avoid conflicting with desktop text selection, where the visible close control remains available. Set `isAutoHide: false` explicitly when an action or message must remain available. The `Toast` component renders the visual toast element inline and is useful for previews, documentation, and static showcases where the viewport lifecycle is not needed.',
     bestPractices: [
-      {guidance: true, description: 'Keep messages short: only a few words that tell the user what happened, like "Changes saved" or "Message sent".'},
-      {guidance: true, description: 'Add an undo action in the endContent slot for reversible operations like deleting an item, so the user can recover without navigating away.'},
-      {guidance: true, description: 'Use uniqueID to deduplicate toasts that fire from repeated actions, like clicking a save button multiple times.'},
-      {guidance: true, description: 'Use error type for failures that need attention but not immediate action; it persists until dismissed so the user won\'t miss it.'},
-      {guidance: false, description: 'Don\'t use a toast for critical errors that block the user. Use Banner for persistent, in-context messaging that requires acknowledgment.'},
-      {guidance: false, description: 'Don\'t put long or multi-line content in a toast; it disappears after 5 seconds and the user may not finish reading.'},
-      {guidance: false, description: 'Don\'t show form validation errors as toasts. Use inline field validation so the user can see exactly which field needs fixing.'},
+      {
+        guidance: true,
+        description:
+          'Keep messages short: only a few words that tell the user what happened, like "Changes saved" or "Message sent".',
+      },
+      {
+        guidance: true,
+        description:
+          'Add a short undo action in the endContent slot for reversible operations. Set isAutoHide to false when the action must remain available.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use uniqueID to deduplicate toasts that fire from repeated actions, like clicking a save button multiple times.',
+      },
+      {
+        guidance: true,
+        description:
+          "Use error type for failures that need attention but not immediate action; it persists until dismissed so the user won't miss it.",
+      },
+      {
+        guidance: false,
+        description:
+          "Don't use a toast for critical errors that block the user. Use Banner for persistent, in-context messaging that requires acknowledgment.",
+      },
+      {
+        guidance: false,
+        description:
+          "Don't put long or multi-line content in a toast; it disappears after 5 seconds and the user may not finish reading.",
+      },
+      {
+        guidance: false,
+        description:
+          "Don't show form validation errors as toasts. Use inline field validation so the user can see exactly which field needs fixing.",
+      },
     ],
     anatomy: [
-      {name: 'Body', required: true, description: 'The primary message text describing what happened or what the user should know.'},
-      {name: 'End content', required: false, description: 'A trailing action like an Undo button or a link, placed after the body text.'},
-      {name: 'Dismiss button', required: true, description: 'A close button that lets the user manually dismiss the toast before auto-hide.'},
+      {
+        name: 'Body',
+        required: true,
+        description:
+          'The primary message text describing what happened or what the user should know.',
+      },
+      {
+        name: 'End content',
+        required: false,
+        description:
+          'A trailing action like an Undo button or a link, placed after the body text.',
+      },
+      {
+        name: 'Dismiss button',
+        required: true,
+        description:
+          'A close button that lets the user manually dismiss the toast before auto-hide.',
+      },
     ],
   },
 };
@@ -104,28 +200,71 @@ export const docsZh = {
     body: '主要消息内容。',
     type: 'Toast 类型，控制背景颜色。error toast 持续显示直到关闭。',
     isAutoHide: '是否自动关闭。info 默认为 true，error 默认为 false。',
-    autoHideDuration: '自动关闭前的持续时间（毫秒）。',
-    endContent: '尾部渲染的内容（如撤销按钮、链接）。',
+    autoHideDuration:
+      '自动关闭前的持续时间（毫秒）。定时内容必须符合 WCAG 2.2.1。',
+    endContent: '尾部渲染的内容（如撤销按钮、链接）。操作标签应保持简短。',
     uniqueID: '用于去重的唯一标识符。',
     collisionBehavior: '当已存在相同 uniqueID 的 toast 时的行为。',
     onHide: '当 toast 被移除时触发的回调。',
+    renderContent:
+      "用你自己的布局替换该 toast 卡片内部的内容。Astryx 保留卡片本身、astryx-toast 主题目标、实时区域角色和自动关闭行为，并把消息、endContent、解析后的 toast 设置和 dismiss 回调交给渲染函数。自定义渲染函数完全拥有布局中的控件：请组合所需的控件并通过它调用 dismiss。Astryx 不会向自定义内容注入后备关闭按钮。按 toast 单独设置：应用可通过封装 useToast 并在每次调用时传入来共享同一套布局；而由库代码发起、从不传入该参数的 toast 会渲染为普通的 Astryx toast。传入参数为 {body, endContent, type, isAutoHide, autoHideDuration, dismiss}，其中 type 为 'info' | 'error'。",
   },
   usage: {
     description:
-      'Toast 显示简短的非阻塞通知，用于确认操作或呈现临时信息。适用于用户需要反馈但不需要做决定的场景，如保存、删除或状态变更。\n\n生产环境中推荐使用 `useToast()` hook，它通过 `ToastViewport` 处理定位、堆叠、自动关闭和去重。`Toast` 组件以内联方式渲染 toast 视觉元素，适用于预览、文档和静态展示。',
+      'Toast 显示简短的非阻塞通知，用于确认操作或呈现临时信息。适用于用户需要反馈但不需要做决定的场景，如保存、删除或状态变更。\n\n生产环境中推荐使用 `useToast()` hook，它通过 `ToastViewport` 处理定位、堆叠、自动关闭和去重。Toast 会保持在视口和安全区域边距内，较长的消息会换行，并根据配置的顶部或底部边缘进入、退出或滑动关闭。垂直滑动与位置动效使用同一空间模型：顶部 Toast 向上离开，底部 Toast 向下离开。只有在动作明确朝向关闭边缘时才会接管原生触摸移动，滑动关闭继续报告现有的 manual 原因。触控笔属于直接接触输入，因此支持相同手势；鼠标拖动会与桌面文本选择冲突，所以不启用，关闭按钮始终可用。当操作或消息必须持续可用时，请显式设置 `isAutoHide: false`。`Toast` 组件以内联方式渲染 toast 视觉元素，适用于不需要视口生命周期的预览、文档和静态展示。',
     bestPractices: [
-      {guidance: true, description: '保持消息简短，只需几个词告诉用户发生了什么，如"更改已保存"或"消息已发送"。'},
-      {guidance: true, description: '在 endContent 插槽中添加撤销操作，用于可逆操作如删除项目，让用户无需导航即可恢复。'},
-      {guidance: true, description: '使用 uniqueID 去重重复操作触发的 toast，如多次点击保存按钮。'},
-      {guidance: true, description: '对需要关注但不需要立即操作的错误使用 error 类型，它会持续显示直到关闭。'},
-      {guidance: false, description: '不要对阻塞用户的严重错误使用 toast，使用 Banner 进行持久的上下文消息传递。'},
-      {guidance: false, description: '不要在 toast 中放置长内容或多行内容，它会在5秒后消失，用户可能来不及阅读。'},
-      {guidance: false, description: '不要将表单验证错误显示为 toast，使用内联字段验证让用户看到具体哪个字段需要修复。'},
+      {
+        guidance: true,
+        description:
+          '保持消息简短，只需几个词告诉用户发生了什么，如"更改已保存"或"消息已发送"。',
+      },
+      {
+        guidance: true,
+        description:
+          '在 endContent 插槽中添加简短的撤销操作，用于可逆操作。当操作必须持续可用时，将 isAutoHide 设置为 false。',
+      },
+      {
+        guidance: true,
+        description:
+          '使用 uniqueID 去重重复操作触发的 toast，如多次点击保存按钮。',
+      },
+      {
+        guidance: true,
+        description:
+          '对需要关注但不需要立即操作的错误使用 error 类型，它会持续显示直到关闭。',
+      },
+      {
+        guidance: false,
+        description:
+          '不要对阻塞用户的严重错误使用 toast，使用 Banner 进行持久的上下文消息传递。',
+      },
+      {
+        guidance: false,
+        description:
+          '不要在 toast 中放置长内容或多行内容，它会在5秒后消失，用户可能来不及阅读。',
+      },
+      {
+        guidance: false,
+        description:
+          '不要将表单验证错误显示为 toast，使用内联字段验证让用户看到具体哪个字段需要修复。',
+      },
     ],
     anatomy: [
-      {name: '正文', required: true, description: '描述发生了什么或用户应该知道什么的主要消息文本。'},
-      {name: '尾部内容', required: false, description: '正文后的尾随操作，如撤销按钮或链接。'},
-      {name: '关闭按钮', required: true, description: '让用户在自动隐藏前手动关闭 toast 的关闭按钮。'},
+      {
+        name: '正文',
+        required: true,
+        description: '描述发生了什么或用户应该知道什么的主要消息文本。',
+      },
+      {
+        name: '尾部内容',
+        required: false,
+        description: '正文后的尾随操作，如撤销按钮或链接。',
+      },
+      {
+        name: '关闭按钮',
+        required: true,
+        description: '让用户在自动隐藏前手动关闭 toast 的关闭按钮。',
+      },
     ],
   },
 };
@@ -136,25 +275,55 @@ export const docsDense = {
     'toast notification w/ auto-dismiss, stacking, dedup, smooth animations; MediaTheme inverted surface',
   usage: {
     description:
-      'Brief non-blocking notification for action confirmations and temporary info. Use where user needs feedback not decisions: saves, deletes, status changes. useToast() hook for production (positioning, stacking, auto-dismiss, dedup via ToastViewport). Toast renders inline for previews/docs/static showcases.',
+      'Brief non-blocking notification for action confirmations and temporary info. Use where user needs feedback not decisions: saves, deletes, status changes. useToast() hook for production (safe-area positioning, responsive message wrapping, stacking, auto-dismiss, dedup via ToastViewport). Enters, exits, or swipe-dismisses toward configured edge; touch is claimed only after dominant edge-directed intent; swipe reports manual. Pen uses the direct-contact gesture; mouse drag stays off to preserve text selection and the close control remains available. Set isAutoHide false explicitly for must-remain actions/messages. Toast renders inline for previews/docs/static showcases.',
     bestPractices: [
-      {guidance: true, description: 'Short messages, a few words: "Changes saved", "Message sent".'},
-      {guidance: true, description: 'Undo action in endContent for reversible ops like deletes.'},
-      {guidance: true, description: 'uniqueID to dedup repeated action toasts.'},
-      {guidance: true, description: 'Error type for failures needing attention; persists until dismissed.'},
-      {guidance: false, description: 'Don\'t use for critical blocking errors. Use Banner for persistent in-context messaging.'},
-      {guidance: false, description: 'Don\'t put long/multi-line content; disappears in 5s, user may not finish reading.'},
-      {guidance: false, description: 'Don\'t show form validation errors. Use inline field validation instead.'},
+      {
+        guidance: true,
+        description:
+          'Short messages, a few words: "Changes saved", "Message sent".',
+      },
+      {
+        guidance: true,
+        description:
+          'Short Undo action in endContent for reversible ops; set isAutoHide false when it must remain available.',
+      },
+      {
+        guidance: true,
+        description: 'uniqueID to dedup repeated action toasts.',
+      },
+      {
+        guidance: true,
+        description:
+          'Error type for failures needing attention; persists until dismissed.',
+      },
+      {
+        guidance: false,
+        description:
+          "Don't use for critical blocking errors. Use Banner for persistent in-context messaging.",
+      },
+      {
+        guidance: false,
+        description:
+          "Don't put long/multi-line content; disappears in 5s, user may not finish reading.",
+      },
+      {
+        guidance: false,
+        description:
+          "Don't show form validation errors. Use inline field validation instead.",
+      },
     ],
   },
   propDescriptions: {
     body: 'primary message content',
     type: 'toast type; controls bg color; error persists until dismissed',
     isAutoHide: 'auto-dismiss; true for info, false for error',
-    autoHideDuration: 'ms before auto-dismiss',
-    endContent: 'trailing end content (undo btn, link)',
+    autoHideDuration:
+      'ms before auto-dismiss; timed content must satisfy WCAG 2.2.1',
+    endContent:
+      'trailing end content (undo btn, link); keep action labels short',
     uniqueID: 'unique id for dedup',
     collisionBehavior: 'behavior when matching uniqueID exists',
     onHide: 'callback when toast removed',
+    renderContent: 'custom inner layout; receives content, resolved settings + dismiss callback; no injected fallback control',
   },
 };