An open source design system that's fully customizable and agent ready
TypeScript
Improve Toast docs page and block examples (#1571)
Kenton Quatmanc06963f0be4a
diff --git a/packages/cli/templates/blocks/components/Toast/ToastAction.doc.mjs b/packages/cli/templates/blocks/components/Toast/ToastAction.doc.mjsnew file mode 100644index 0000000000..fcf7ae4ebe--- /dev/null+++ b/packages/cli/templates/blocks/components/Toast/ToastAction.doc.mjs@@ -0,0 +1,9 @@+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */+export const doc = {+ type: 'block',+ name: 'Toast — Action',+ description: 'Persistent toasts with a trailing button or link so the user can act on the notification, like undoing a delete or viewing a report.',+ isReady: true,+ aspectRatio: 16 / 9,+ componentsUsed: ['Toast', 'Button', 'Link', 'Layout', 'Text'],+};diff --git a/packages/cli/templates/blocks/components/Toast/ToastAction.tsx b/packages/cli/templates/blocks/components/Toast/ToastAction.tsxnew file mode 100644index 0000000000..2bb456af44--- /dev/null+++ b/packages/cli/templates/blocks/components/Toast/ToastAction.tsx@@ -0,0 +1,54 @@+'use client';++import {useXDSToast} from '@xds/core/Toast';+import {XDSButton} from '@xds/core/Button';+import {XDSLink} from '@xds/core/Link';+import {XDSStack} from '@xds/core/Layout';+import {XDSText} from '@xds/core/Text';++export default function ToastAction() {+ const toast = useXDSToast();++ return (+ <XDSStack direction="vertical" gap={4}>+ <XDSText type="supporting" color="secondary">+ Trailing actions for undo or navigation+ </XDSText>+ <XDSStack direction="horizontal" gap={3} vAlign="center">+ <XDSButton+ label="Delete with undo"+ variant="secondary"+ onClick={() =>+ toast({+ body: 'Item deleted',+ isAutoHide: false,+ endContent: (+ <XDSButton+ label="Undo"+ variant="secondary"+ size="sm"+ onClick={() => {}}+ />+ ),+ })+ }+ />+ <XDSButton+ label="Report ready"+ variant="secondary"+ onClick={() =>+ toast({+ body: 'Your report is ready.',+ isAutoHide: false,+ endContent: (+ <XDSLink href="#" label="View report" hasUnderline>+ View report+ </XDSLink>+ ),+ })+ }+ />+ </XDSStack>+ </XDSStack>+ );+}diff --git a/packages/cli/templates/blocks/components/Toast/ToastDeduplication.doc.mjs b/packages/cli/templates/blocks/components/Toast/ToastDeduplication.doc.mjsindex 905ab213d1..a58994bc2d 100644--- a/packages/cli/templates/blocks/components/Toast/ToastDeduplication.doc.mjs+++ b/packages/cli/templates/blocks/components/Toast/ToastDeduplication.doc.mjs@@ -2,9 +2,8 @@export const doc = {type: 'block',name: 'Toast — Deduplication',- description:- 'Prevent duplicate toasts with uniqueID, using ignore or overwrite collision strategies.',+ description: 'Prevent duplicate toasts with uniqueID. Use ignore to keep the first toast, or overwrite to replace it with updated content like a progress percentage.',isReady: true,- aspectRatio: 4 / 3,- componentsUsed: ['Toast', 'Button', 'Stack'],+ aspectRatio: 16 / 9,+ componentsUsed: ['Toast', 'Button', 'Layout', 'Text'],};diff --git a/packages/cli/templates/blocks/components/Toast/ToastDeduplication.tsx b/packages/cli/templates/blocks/components/Toast/ToastDeduplication.tsxindex a8c386c801..d6f4f0f13f 100644--- a/packages/cli/templates/blocks/components/Toast/ToastDeduplication.tsx+++ b/packages/cli/templates/blocks/components/Toast/ToastDeduplication.tsx@@ -2,35 +2,43 @@import {useXDSToast} from '@xds/core/Toast';import {XDSButton} from '@xds/core/Button';-import {XDSStack} from '@xds/core/Stack';+import {XDSStack} from '@xds/core/Layout';+import {XDSText} from '@xds/core/Text';export default function ToastDeduplication() {const toast = useXDSToast();+return (- <XDSStack direction="horizontal" gap={2}>- <XDSButton- label="Offline (ignore)"- onClick={() =>- toast({- body: 'You are offline',- uniqueID: 'offline',- collisionBehavior: 'ignore',- isAutoHide: false,- })- }- />- <XDSButton- label="Progress (overwrite)"- variant="secondary"- onClick={() =>- toast({- body: `Uploading... ${Math.floor(Math.random() * 100)}%`,- uniqueID: 'upload-progress',- collisionBehavior: 'overwrite',- isAutoHide: false,- })- }- />+ <XDSStack direction="vertical" gap={4}>+ <XDSText type="supporting" color="secondary">+ Ignore keeps the first toast; overwrite replaces it+ </XDSText>+ <XDSStack direction="horizontal" gap={3} vAlign="center">+ <XDSButton+ label="Offline (ignore)"+ variant="secondary"+ onClick={() =>+ toast({+ body: 'You are offline',+ uniqueID: 'offline',+ collisionBehavior: 'ignore',+ isAutoHide: false,+ })+ }+ />+ <XDSButton+ label="Progress (overwrite)"+ variant="secondary"+ onClick={() =>+ toast({+ body: `Uploading\u2026 ${Math.floor(Math.random() * 100)}%`,+ uniqueID: 'upload-progress',+ collisionBehavior: 'overwrite',+ isAutoHide: false,+ })+ }+ />+ </XDSStack></XDSStack>);}diff --git a/packages/cli/templates/blocks/components/Toast/ToastDismiss.doc.mjs b/packages/cli/templates/blocks/components/Toast/ToastDismiss.doc.mjsnew file mode 100644index 0000000000..c938dd29a4--- /dev/null+++ b/packages/cli/templates/blocks/components/Toast/ToastDismiss.doc.mjs@@ -0,0 +1,9 @@+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */+export const doc = {+ type: 'block',+ name: 'Toast — Dismiss',+ description: 'Show a persistent toast and dismiss it programmatically using the function returned by useXDSToast. Use for long-running operations that need manual cleanup.',+ isReady: true,+ aspectRatio: 16 / 9,+ componentsUsed: ['Toast', 'Button', 'Layout', 'Text'],+};diff --git a/packages/cli/templates/blocks/components/Toast/ToastDismiss.tsx b/packages/cli/templates/blocks/components/Toast/ToastDismiss.tsxnew file mode 100644index 0000000000..3859ff7f48--- /dev/null+++ b/packages/cli/templates/blocks/components/Toast/ToastDismiss.tsx@@ -0,0 +1,40 @@+'use client';++import {useRef} from 'react';+import {useXDSToast} from '@xds/core/Toast';+import {XDSButton} from '@xds/core/Button';+import {XDSStack} from '@xds/core/Layout';+import {XDSText} from '@xds/core/Text';++export default function ToastDismiss() {+ const toast = useXDSToast();+ const dismissRef = useRef<(() => void) | null>(null);++ return (+ <XDSStack direction="vertical" gap={4}>+ <XDSText type="supporting" color="secondary">+ Show a persistent toast, then dismiss it from code+ </XDSText>+ <XDSStack direction="horizontal" gap={3} vAlign="center">+ <XDSButton+ label="Show persistent toast"+ variant="secondary"+ onClick={() => {+ dismissRef.current = toast({+ body: 'Uploading file\u2026',+ isAutoHide: false,+ });+ }}+ />+ <XDSButton+ label="Dismiss"+ variant="ghost"+ onClick={() => {+ dismissRef.current?.();+ dismissRef.current = null;+ }}+ />+ </XDSStack>+ </XDSStack>+ );+}diff --git a/packages/cli/templates/blocks/components/Toast/ToastProgrammaticDismiss.doc.mjs b/packages/cli/templates/blocks/components/Toast/ToastProgrammaticDismiss.doc.mjsdeleted file mode 100644index 982d5cb08a..0000000000--- a/packages/cli/templates/blocks/components/Toast/ToastProgrammaticDismiss.doc.mjs+++ /dev/null@@ -1,10 +0,0 @@-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */-export const doc = {- type: 'block',- name: 'Toast — Programmatic Dismiss',- description:- 'Show a persistent toast and dismiss it programmatically using the returned dismiss function.',- isReady: true,- aspectRatio: 4 / 3,- componentsUsed: ['Toast', 'Button', 'Stack'],-};diff --git a/packages/cli/templates/blocks/components/Toast/ToastProgrammaticDismiss.tsx b/packages/cli/templates/blocks/components/Toast/ToastProgrammaticDismiss.tsxdeleted file mode 100644index 9edf3b71e0..0000000000--- a/packages/cli/templates/blocks/components/Toast/ToastProgrammaticDismiss.tsx+++ /dev/null@@ -1,33 +0,0 @@-'use client';--import {useRef} from 'react';-import {useXDSToast} from '@xds/core/Toast';-import {XDSButton} from '@xds/core/Button';-import {XDSStack} from '@xds/core/Stack';--export default function ToastProgrammaticDismiss() {- const toast = useXDSToast();- const dismissRef = useRef<(() => void) | null>(null);-- return (- <XDSStack direction="horizontal" gap={2}>- <XDSButton- label="Show persistent toast"- onClick={() => {- dismissRef.current = toast({- body: 'Uploading...',- isAutoHide: false,- });- }}- />- <XDSButton- label="Dismiss"- variant="secondary"- onClick={() => {- dismissRef.current?.();- dismissRef.current = null;- }}- />- </XDSStack>- );-}diff --git a/packages/cli/templates/blocks/components/Toast/ToastShowcase.doc.mjs b/packages/cli/templates/blocks/components/Toast/ToastShowcase.doc.mjsindex 9b1644bae3..ff8b471aeb 100644--- a/packages/cli/templates/blocks/components/Toast/ToastShowcase.doc.mjs+++ b/packages/cli/templates/blocks/components/Toast/ToastShowcase.doc.mjs@@ -3,6 +3,6 @@ export const doc = {type: 'block',name: 'Toast',isReady: true,- aspectRatio: 1,+ aspectRatio: 16 / 9,isShowcase: true,};diff --git a/packages/cli/templates/blocks/components/Toast/ToastStacking.doc.mjs b/packages/cli/templates/blocks/components/Toast/ToastStacking.doc.mjsindex c16a993520..e6dfdacaad 100644--- a/packages/cli/templates/blocks/components/Toast/ToastStacking.doc.mjs+++ b/packages/cli/templates/blocks/components/Toast/ToastStacking.doc.mjs@@ -2,9 +2,8 @@export const doc = {type: 'block',name: 'Toast — Stacking',- description:- 'Multiple toasts stacking vertically, alternating between info and error types.',+ description: 'Multiple toasts stacking vertically with smooth enter and exit animations. Click repeatedly to see how toasts queue and dismiss.',isReady: true,- aspectRatio: 4 / 3,- componentsUsed: ['Toast', 'Button'],+ aspectRatio: 16 / 9,+ componentsUsed: ['Toast', 'Button', 'Layout', 'Text'],};diff --git a/packages/cli/templates/blocks/components/Toast/ToastStacking.tsx b/packages/cli/templates/blocks/components/Toast/ToastStacking.tsxindex ca46b432c8..b5e7abf934 100644--- a/packages/cli/templates/blocks/components/Toast/ToastStacking.tsx+++ b/packages/cli/templates/blocks/components/Toast/ToastStacking.tsx@@ -3,23 +3,33 @@import {useRef} from 'react';import {useXDSToast} from '@xds/core/Toast';import {XDSButton} from '@xds/core/Button';+import {XDSStack} from '@xds/core/Layout';+import {XDSText} from '@xds/core/Text';++const MESSAGES = [+ {body: 'Changes saved.', type: 'info' as const},+ {body: 'Failed to upload file.', type: 'error' as const},+ {body: 'Message sent to Sarah Chen.', type: 'info' as const},+ {body: 'Connection lost.', type: 'error' as const},+];export default function ToastStacking() {const toast = useXDSToast();const countRef = useRef(0);return (- <XDSButton- label="Add toast"- onClick={() => {- countRef.current++;- const types = ['info', 'error'] as const;- const type = types[countRef.current % types.length];- toast({- body: `Toast #${countRef.current} — ${type} notification.`,- type,- });- }}- />+ <XDSStack direction="vertical" gap={4}>+ <XDSText type="supporting" color="secondary">+ Click multiple times to see stacking behavior+ </XDSText>+ <XDSButton+ label="Add toast"+ onClick={() => {+ const msg = MESSAGES[countRef.current % MESSAGES.length];+ countRef.current++;+ toast(msg);+ }}+ />+ </XDSStack>);}diff --git a/packages/cli/templates/blocks/components/Toast/ToastTypes.doc.mjs b/packages/cli/templates/blocks/components/Toast/ToastTypes.doc.mjsindex 31e62da0f6..71c3587ed0 100644--- a/packages/cli/templates/blocks/components/Toast/ToastTypes.doc.mjs+++ b/packages/cli/templates/blocks/components/Toast/ToastTypes.doc.mjs@@ -2,9 +2,8 @@export const doc = {type: 'block',name: 'Toast — Types',- description:- 'Info and error toast variants. Error toasts persist until dismissed.',+ description: 'Info and error toast variants side by side. Info toasts auto-dismiss after 5 seconds, error toasts persist until the user dismisses them.',isReady: true,- aspectRatio: 4 / 3,- componentsUsed: ['Toast', 'Button', 'Stack'],+ aspectRatio: 16 / 9,+ componentsUsed: ['Toast', 'Button', 'Layout', 'Text'],};diff --git a/packages/cli/templates/blocks/components/Toast/ToastTypes.tsx b/packages/cli/templates/blocks/components/Toast/ToastTypes.tsxindex 8f25471a35..eaf843262e 100644--- a/packages/cli/templates/blocks/components/Toast/ToastTypes.tsx+++ b/packages/cli/templates/blocks/components/Toast/ToastTypes.tsx@@ -2,26 +2,33 @@import {useXDSToast} from '@xds/core/Toast';import {XDSButton} from '@xds/core/Button';-import {XDSStack} from '@xds/core/Stack';+import {XDSStack} from '@xds/core/Layout';+import {XDSText} from '@xds/core/Text';export default function ToastTypes() {const toast = useXDSToast();+return (- <XDSStack direction="horizontal" gap={2}>- <XDSButton- label="Info"- variant="secondary"- onClick={() =>- toast({body: 'This is an info notification.', type: 'info'})- }- />- <XDSButton- label="Error"- variant="destructive"- onClick={() =>- toast({body: 'This is an error notification.', type: 'error'})- }- />+ <XDSStack direction="vertical" gap={4}>+ <XDSText type="supporting" color="secondary">+ Click each button to see the toast variant+ </XDSText>+ <XDSStack direction="horizontal" gap={3} vAlign="center">+ <XDSButton+ label="Info toast"+ variant="secondary"+ onClick={() =>+ toast({body: 'Changes saved successfully.', type: 'info'})+ }+ />+ <XDSButton+ label="Error toast"+ variant="destructive"+ onClick={() =>+ toast({body: 'Failed to save changes.', type: 'error'})+ }+ />+ </XDSStack></XDSStack>);}diff --git a/packages/cli/templates/blocks/components/Toast/ToastWithAction.doc.mjs b/packages/cli/templates/blocks/components/Toast/ToastWithAction.doc.mjsdeleted file mode 100644index 266ff8b6aa..0000000000--- a/packages/cli/templates/blocks/components/Toast/ToastWithAction.doc.mjs+++ /dev/null@@ -1,10 +0,0 @@-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */-export const doc = {- type: 'block',- name: 'Toast — With Action',- description:- 'Persistent toasts with trailing actions using a button or a link.',- isReady: true,- aspectRatio: 4 / 3,- componentsUsed: ['Toast', 'Button', 'Link', 'Stack'],-};diff --git a/packages/cli/templates/blocks/components/Toast/ToastWithAction.tsx b/packages/cli/templates/blocks/components/Toast/ToastWithAction.tsxdeleted file mode 100644index a357affd16..0000000000--- a/packages/cli/templates/blocks/components/Toast/ToastWithAction.tsx+++ /dev/null@@ -1,46 +0,0 @@-'use client';--import {useXDSToast} from '@xds/core/Toast';-import {XDSButton} from '@xds/core/Button';-import {XDSLink} from '@xds/core/Link';-import {XDSStack} from '@xds/core/Stack';--export default function ToastWithAction() {- const toast = useXDSToast();- return (- <XDSStack direction="horizontal" gap={2}>- <XDSButton- label="With button"- onClick={() =>- toast({- body: 'Item deleted',- isAutoHide: false,- endContent: (- <XDSButton- label="Undo"- variant="secondary"- size="sm"- onClick={() => {}}- />- ),- })- }- />- <XDSButton- label="With link"- variant="secondary"- onClick={() =>- toast({- body: 'Your report is ready.',- isAutoHide: false,- endContent: (- <XDSLink href="#" label="View report" hasUnderline>- View report- </XDSLink>- ),- })- }- />- </XDSStack>- );-}diff --git a/packages/core/src/Toast/Toast.doc.mjs b/packages/core/src/Toast/Toast.doc.mjsindex a49c4b5c0b..f5896018a2 100644--- a/packages/core/src/Toast/Toast.doc.mjs+++ b/packages/core/src/Toast/Toast.doc.mjs@@ -57,12 +57,20 @@ export const docs = {usage: {description:- 'Toast is a transient notification that appears briefly to confirm an action or surface non-critical information. Use it for save confirmations, undo opportunities, or status updates that do not require user interaction.',+ '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.',bestPractices: [- { guidance: true, description: 'Keep toast messages short and actionable so users can read them before they auto-dismiss.' },- { guidance: true, description: 'Include an undo action in the endContent slot for reversible operations.' },- { guidance: false, description: 'Use a toast for critical errors or information that requires user acknowledgment — use Banner instead.' },- { guidance: false, description: 'Stack multiple toasts for the same event — use uniqueID to deduplicate.' },+ {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.'},+ ],+ 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.'},],},};@@ -87,12 +95,20 @@ export const docsZh = {},usage: {description:- 'Toast is a transient notification that appears briefly to confirm an action or surface non-critical information. Use it for save confirmations, undo opportunities, or status updates that do not require user interaction.',+ 'Toast 显示简短的非阻塞通知,用于确认操作或呈现临时信息。适用于用户需要反馈但不需要做决定的场景,如保存、删除或状态变更。',bestPractices: [- { guidance: true, description: 'Keep toast messages short and actionable so users can read them before they auto-dismiss.' },- { guidance: true, description: 'Include an undo action in the endContent slot for reversible operations.' },- { guidance: false, description: 'Use a toast for critical errors or information that requires user acknowledgment — use Banner instead.' },- { guidance: false, description: 'Stack multiple toasts for the same event — use uniqueID to deduplicate.' },+ {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——使用内联字段验证让用户看到具体哪个字段需要修复。'},+ ],+ anatomy: [+ {name: '正文', required: true, description: '描述发生了什么或用户应该知道什么的主要消息文本。'},+ {name: '尾部内容', required: false, description: '正文后的尾随操作,如撤销按钮或链接。'},+ {name: '关闭按钮', required: true, description: '让用户在自动隐藏前手动关闭 toast 的关闭按钮。'},],},};@@ -103,12 +119,15 @@ export const docsDense = {'toast notification w/ auto-dismiss, stacking, dedup, smooth animations; XDSMediaTheme inverted surface',usage: {description:- 'Toast is a transient notification that appears briefly to confirm an action or surface non-critical information. Use it for save confirmations, undo opportunities, or status updates that do not require user interaction.',+ 'Brief non-blocking notification for action confirmations and temporary info. Use where user needs feedback not decisions — saves, deletes, status changes.',bestPractices: [- { guidance: true, description: 'Keep toast messages short and actionable so users can read them before they auto-dismiss.' },- { guidance: true, description: 'Include an undo action in the endContent slot for reversible operations.' },- { guidance: false, description: 'Use a toast for critical errors or information that requires user acknowledgment — use Banner instead.' },- { guidance: false, description: 'Stack multiple toasts for the same event — use uniqueID to deduplicate.' },+ {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.'},],},propDescriptions: {