@astryxdesign/core 0.4.7 → 0.5.0-canary.009bcb3

package/src/Text/Text.tsx

@@ -48,7 +48,8 @@ import {
 } from './text.stylex';
 import {useTruncation} from './useTruncation';
 import type {LayerPlacement} from '../Layer';
-import {mergeProps, mergeRefs} from '../utils';
+import {mergeProps} from '../utils';
+import {useMergedRefs} from '../hooks/useMergedRefs';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
 
@@ -271,13 +272,16 @@ export function Text({
   // Ref for the text element (used as tooltip anchor)
   const textRef = useRef<HTMLElement>(null);
 
+  // Keep the merged ref stable across rerenders.
+  const mergedRef = useMergedRefs(ref, truncation.ref, textRef);
+
   // Build inline style for -webkit-line-clamp (dynamic value)
   const inlineStyle = maxLines > 1 ? {WebkitLineClamp: maxLines} : undefined;
 
   return (
     <>
       <Component
-        ref={mergeRefs(ref, truncation.ref, textRef)}
+        ref={mergedRef}
         {...mergeProps(
           themeProps('text', {type, size, color: resolvedColor}),
           stylex.props(
@@ -309,7 +313,6 @@ export function Text({
           className,
           {...style, ...inlineStyle},
         )}
-        title={tooltipEnabled ? truncation.fullText : undefined}
         {...props}>
         {children}
       </Component>

package/src/TextArea/TextArea.doc.mjs

@@ -186,7 +186,12 @@ export const docs = {
   ],
   theming: {
     targets: [
-      {className: 'astryx-textarea', visualProps: ['size', 'status'], states: ['disabled', 'readonly']},
+      {className: 'astryx-text-area', visualProps: ['size', 'status'], states: ['disabled', 'readonly']},
+      {className: 'astryx-text-area-control'},
+      {className: 'astryx-text-area-counter'},
+      // Still emitted beside the names above, so themes written against
+      // them keep working. Drop in the next major.
+      {className: 'astryx-textarea', visualProps: ['size', 'status'], states: ['disabled', 'readonly'], deprecatedFor: 'text-area'},
     ],
     vars: [
       {
@@ -381,7 +386,12 @@ export const docsZh = {
   ],
   theming: {
     targets: [
-      {className: 'astryx-textarea', visualProps: ['size', 'status'], states: ['disabled', 'readonly']},
+      {className: 'astryx-text-area', visualProps: ['size', 'status'], states: ['disabled', 'readonly']},
+      {className: 'astryx-text-area-control'},
+      {className: 'astryx-text-area-counter'},
+      // Still emitted beside the names above, so themes written against
+      // them keep working. Drop in the next major.
+      {className: 'astryx-textarea', visualProps: ['size', 'status'], states: ['disabled', 'readonly'], deprecatedFor: 'text-area'},
     ],
     vars: [
       {

package/src/TextArea/TextArea.test.tsx

@@ -1155,3 +1155,14 @@ describe('TextArea readonly theme state', () => {
     expect(root).not.toHaveAttribute('data-readonly');
   });
 });
+
+describe('TextArea theme target names', () => {
+  it('renders the deprecated class beside the current one', () => {
+    const {container} = render(
+      <TextArea label="Notes" value="" onChange={() => {}} />,
+    );
+    const root = container.querySelector('.astryx-text-area');
+    expect(root).not.toBeNull();
+    expect(root).toHaveClass('astryx-textarea');
+  });
+});

package/src/TextArea/TextArea.tsx

@@ -46,7 +46,7 @@ import {
 import {Icon, renderIconSlot, type IconType} from '../Icon';
 import {Spinner} from '../Spinner';
 import {useTooltip} from '../Tooltip';
-import {mergeProps, mergeRefs} from '../utils';
+import {mergeProps} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import type {SizeValue} from '../utils/types';
 import {useInputContainer} from '../hooks/useInputContainer';
@@ -58,6 +58,7 @@ import {themeProps} from '../utils/themeProps';
 import {characterCount} from '../utils/characters';
 import {useTranslator} from '../i18n';
 
+import {useMergedRefs} from '../hooks/useMergedRefs';
 const COUNTER_WARNING_THRESHOLD = 0.8;
 
 const styles = stylex.create({
@@ -555,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,
@@ -580,7 +587,7 @@ export function TextArea({
         )}
         <textarea
           {...rest}
-          ref={mergeRefs(ref, textareaRef)}
+          ref={useMergedRefs(ref, textareaRef)}
           id={id}
           name={isDisabled ? undefined : htmlName}
           value={optimisticValue}
@@ -608,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) && (
@@ -632,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

@@ -71,6 +71,16 @@ export const docs = {
         'Displays a "Required" indicator next to the label and sets aria-required. Mutually exclusive with isOptional.',
       default: 'false',
     },
+    {
+      name: 'onEnter',
+      type: '() => void',
+      description: 'Callback fired when the user presses the Enter key.',
+    },
+    {
+      name: 'onKeyDown',
+      type: '(e: KeyboardEvent<HTMLInputElement>) => void',
+      description: 'Callback fired on keydown events on the input.',
+    },
     {
       name: 'isDisabled',
       type: 'boolean',

package/src/TextInput/TextInput.tsx

@@ -97,7 +97,7 @@ export type {
   InputStatus as TextInputStatus,
   InputStatusType as TextInputStatusType,
 } from '../Field';
-import {mergeProps, mergeRefs} from '../utils';
+import {mergeProps} from '../utils';
 import {useSize} from '../SizeContext/SizeContext';
 import {useInputContainer} from '../hooks/useInputContainer';
 import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
@@ -108,6 +108,7 @@ import type {SizeValue} from '../utils/types';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
 
+import {useMergedRefs} from '../hooks/useMergedRefs';
 export type TextInputType = 'text' | 'password' | 'email';
 
 export interface TextInputProps extends Omit<
@@ -421,7 +422,7 @@ export function TextInput({
       {inputGroup && <VisuallyHidden id={inputLabelID}>{label}</VisuallyHidden>}
       <input
         {...rest}
-        ref={mergeRefs(ref, inputRef)}
+        ref={useMergedRefs(ref, inputRef)}
         id={id}
         name={isDisabled ? undefined : htmlName}
         type={type}

package/src/Thumbnail/Thumbnail.doc.mjs

@@ -78,7 +78,7 @@ export const docs = {
       {className: 'astryx-thumbnail'},
     ],
     vars: [
-      {name: '--_thumbnail-hit-inset', description: 'Outset of the remove button\u2019s invisible hit area, applied to a ::after overlay. 0 on a fine pointer; negative on a coarse one, which grows the 20px button to the 24px touch target without changing what is drawn.', default: '0px', private: true},
+      {name: '--_thumbnail-hit-inset', description: 'Outset of the remove button\'s invisible hit area, applied to a ::after overlay. 0 on a fine pointer; negative on a coarse one, which grows the 20px button to the 24px touch target without changing what is drawn.', default: '0px', private: true},
     ],
   },
   usage: {

package/src/TimeInput/TimeInput.tsx

@@ -58,7 +58,6 @@ import {
   isImeKeyEvent,
   isTimeInRange,
   mergeProps,
-  mergeRefs,
   getInputARIA,
 } from '../utils';
 import type {BaseProps} from '../BaseProps';
@@ -74,6 +73,7 @@ import {useTooltip} from '../Tooltip';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
 
+import {useMergedRefs} from '../hooks/useMergedRefs';
 const styles = stylex.create({
   icon: {
     display: 'flex',
@@ -648,7 +648,7 @@ export function TimeInput({
         </VisuallyHidden>
       )}
       <input
-        ref={mergeRefs(ref, inputRef)}
+        ref={useMergedRefs(ref, inputRef)}
         id={id}
         type="text"
         value={displayValue}

package/src/Timestamp/Timestamp.test.tsx

@@ -673,6 +673,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 +1323,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

@@ -20,7 +20,7 @@ import {lazy, Suspense, useEffect, useRef, useState} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {Text} from '../Text';
 import type {TextType, TextSize, TextColor, TextWeight} from '../theme/types';
-import {mergeProps, mergeRefs} from '../utils';
+import {mergeProps} from '../utils';
 import {useDevWarning} from '../hooks/useDevWarning';
 import {useTranslator} from '../i18n';
 import {useLocale} from '../i18n/useLocale';
@@ -33,6 +33,7 @@ import type {
   TimestampTooltipLine,
 } from './tooltipEntries';
 
+import {useMergedRefs} from '../hooks/useMergedRefs';
 // Load the overlay lazily so a card-less Timestamp — the default — never
 // bundles HoverCard or the copy affordance's Icon/IconButton. Mirrors the code
 // split the read-only Tooltip path used before it.
@@ -418,10 +419,12 @@ export function Timestamp({
   style,
   ref,
   'data-testid': testId,
+  ...rest
 }: TimestampProps) {
   const t = useTranslator();
   const locale = useLocale();
   const timeRef = useRef<HTMLTimeElement>(null);
+  const mergedTimeRef = useMergedRefs(ref, timeRef);
   const [now, setNow] = useState(() => new Date());
 
   const date = parseValue(value);
@@ -526,17 +529,18 @@ export function Timestamp({
       xstyle={xstyle}
       {...timestampProps}>
       <time
-        ref={mergeRefs(ref, timeRef)}
+        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
@@ -545,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/Toast/Toast.doc.mjs

@@ -32,13 +32,13 @@ export const docs = {
     {
       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'}},
@@ -60,18 +60,32 @@ export const docs = {
       type: '(reason: "auto" | "manual") => void',
       description: 'Callback fired when the toast is removed.',
     },
+    {
+      name: 'onDismiss',
+      type: '(reason: "auto" | "manual") => void',
+      description: 'Callback fired when the toast is dismissed.',
+      required: true,
+    },
   ],  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,
+      },
+    ],
   },
 
   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 or exit toward their configured top or bottom edge. 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: '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.'},
@@ -98,18 +112,18 @@ 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 被移除时触发的回调。',
   },
   usage: {
     description:
-      'Toast 显示简短的非阻塞通知，用于确认操作或呈现临时信息。适用于用户需要反馈但不需要做决定的场景，如保存、删除或状态变更。\n\n生产环境中推荐使用 `useToast()` hook，它通过 `ToastViewport` 处理定位、堆叠、自动关闭和去重。`Toast` 组件以内联方式渲染 toast 视觉元素，适用于预览、文档和静态展示。',
+      'Toast 显示简短的非阻塞通知，用于确认操作或呈现临时信息。适用于用户需要反馈但不需要做决定的场景，如保存、删除或状态变更。\n\n生产环境中推荐使用 `useToast()` hook，它通过 `ToastViewport` 处理定位、堆叠、自动关闭和去重。Toast 会保持在视口和安全区域边距内，较长的消息会换行，并根据配置的顶部或底部边缘进入或退出。当操作或消息必须持续可用时，请显式设置 `isAutoHide: false`。`Toast` 组件以内联方式渲染 toast 视觉元素，适用于不需要视口生命周期的预览、文档和静态展示。',
     bestPractices: [
       {guidance: true, description: '保持消息简短，只需几个词告诉用户发生了什么，如"更改已保存"或"消息已发送"。'},
-      {guidance: true, description: '在 endContent 插槽中添加撤销操作，用于可逆操作如删除项目，让用户无需导航即可恢复。'},
+      {guidance: true, description: '在 endContent 插槽中添加简短的撤销操作，用于可逆操作。当操作必须持续可用时，将 isAutoHide 设置为 false。'},
       {guidance: true, description: '使用 uniqueID 去重重复操作触发的 toast，如多次点击保存按钮。'},
       {guidance: true, description: '对需要关注但不需要立即操作的错误使用 error 类型，它会持续显示直到关闭。'},
       {guidance: false, description: '不要对阻塞用户的严重错误使用 toast，使用 Banner 进行持久的上下文消息传递。'},
@@ -130,10 +144,10 @@ 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). 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: '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.'},
@@ -145,8 +159,8 @@ export const docsDense = {
     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',

package/src/Toast/Toast.tsx

@@ -2,6 +2,21 @@
 
 'use client';
 
+/**
+ * @file Toast.tsx
+ * @input Uses React timers, Toast options, Button/Icon, MediaTheme, tokens, and
+ *   placement-derived motion variables inherited from ToastViewport
+ * @output Exports the rendered Toast surface and its pause/dismiss behavior
+ * @position Core implementation; rendered by ToastViewport and documented by Toast.doc.mjs
+ *
+ * SYNC: When Toast layout, timer pause, media theme, or dismissal behavior changes,
+ *   update these files to stay in sync:
+ * - /packages/core/src/Toast/ToastViewport.test.tsx
+ * - /packages/core/src/Toast/Toast.doc.mjs
+ * - /apps/storybook/stories/Toast.stories.tsx
+ * - /packages/cli/assets/templates/blocks/components/Toast/ (showcase blocks)
+ */
+
 import {useCallback, useEffect, useRef} from 'react';
 import type {ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
@@ -24,13 +39,15 @@ import type {ToastType, ToastDismissReason} from './types';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
 
+const TOAST_EDGE_DRIFT = spacingVars['--spacing-2'];
 const styles = stylex.create({
   root: {
     paddingBlock: spacingVars['--spacing-4'],
     paddingInline: spacingVars['--spacing-4'],
     borderRadius: radiusVars['--radius-container'],
+    boxSizing: 'border-box',
     width: 400,
-    maxWidth: 'min(100%, calc(100vw - 32px))',
+    maxWidth: '100%',
     boxShadow: shadowVars['--shadow-med'],
     opacity: 1,
     fontFamily: typographyVars['--font-family-body'],
@@ -45,15 +62,17 @@ const styles = stylex.create({
     transitionTimingFunction: easeVars['--ease-standard'],
     '@starting-style': {
       opacity: 0,
-      transform: 'translateY(8px)',
+      transform: `translateY(var(--_toast-slide-y, ${TOAST_EDGE_DRIFT}))`,
     },
   },
   variantDefault: {
     backgroundColor: colorVars['--color-background-inverted'],
   },
+
   inner: {
     display: 'flex',
     alignItems: 'flex-start',
+    flexWrap: 'nowrap',
     gap: spacingVars['--spacing-3'],
     width: '100%',
   },
@@ -63,17 +82,22 @@ const styles = stylex.create({
   content: {
     flex: 1,
     minWidth: 0,
+    overflowWrap: 'anywhere',
   },
   exiting: {
     opacity: 0,
-    transform: 'translateY(-8px)',
+    transform: `translateY(var(--_toast-slide-y, ${TOAST_EDGE_DRIFT}))`,
   },
   endContent: {
     flexShrink: 0,
     display: 'flex',
     alignItems: 'center',
     gap: spacingVars['--spacing-2'],
-    marginBlock: `calc(${spacingVars['--spacing-1']} * -1)`,
+    // Keep every trailing control centered on the first 20px body line, even
+    // when the body wraps or a consumer supplies a control taller than the
+    // built-in 28px dismiss button. The action label should still stay short;
+    // the wrappers above let it break rather than widen the Toast.
+    blockSize: `calc(${typeScaleDefaults['--text-body-size']} * ${typeScaleDefaults['--text-body-leading']})`,
     marginInlineEnd: `calc(${spacingVars['--spacing-1']} * -1)`,
   },
 });