From c20b58a6a9d93b37c2e05e6d7394394e32aab7a4 Mon Sep 17 00:00:00 2001 From: cixzhang Date: Tue, 17 Nov 2026 03:46:28 -0800 Subject: [PATCH 01/10] docs(core): prop types name only types the package exports Selector's options are SelectorOptionType[] (SelectorOption is a component), SyntaxTheme's theme is a SyntaxThemeDefinition, Markdown's plugins are what createMarkdownPlugin() returns, and the imperative dialog hooks' show() options are written as the exported Dialog and AlertDialog props they are built from. --- .../src/AlertDialog/useImperativeAlertDialog.doc.mjs | 11 +++++++---- packages/core/src/Dialog/useImperativeDialog.doc.mjs | 11 +++++++---- packages/core/src/Markdown/Markdown.doc.mjs | 6 +++--- packages/core/src/Selector/Selector.doc.mjs | 2 +- packages/core/src/theme/SyntaxTheme.doc.mjs | 2 +- 5 files changed, 19 insertions(+), 13 deletions(-) diff --git a/packages/core/src/AlertDialog/useImperativeAlertDialog.doc.mjs b/packages/core/src/AlertDialog/useImperativeAlertDialog.doc.mjs index 8b560d5ba5869..c0dcfb546ef54 100644 --- a/packages/core/src/AlertDialog/useImperativeAlertDialog.doc.mjs +++ b/packages/core/src/AlertDialog/useImperativeAlertDialog.doc.mjs @@ -6,12 +6,14 @@ export const docs = { name: 'useImperativeAlertDialog', subComponentOf: 'AlertDialog', displayName: 'useImperativeAlertDialog', - description: 'Hook for showing an alert dialog without managing open state. Call alert.show(options) to open and alert.hide() to close. Render alert.element in your JSX tree.', + description: + 'Hook for showing an alert dialog without managing open state. Call alert.show(options) to open and alert.hide() to close. Render alert.element in your JSX tree.', props: [ { name: 'show', - type: '(options: AlertDialogOptions) => void', - description: 'Show the alert dialog with the given options. Options are the same as AlertDialog props minus isOpen/onOpenChange.', + type: "(options: Omit) => void", + description: + 'Show the alert dialog with the given options. Options are the same as AlertDialog props minus isOpen/onOpenChange.', }, { name: 'hide', @@ -33,7 +35,8 @@ export const docs = { export const docsDense = { name: 'useImperativeAlertDialog', - description: 'Hook to show alert dialog w/o managing open state. Call alert.show(options) to open, alert.hide() to close; render alert.element in JSX tree.', + description: + 'Hook to show alert dialog w/o managing open state. Call alert.show(options) to open, alert.hide() to close; render alert.element in JSX tree.', propDescriptions: { show: 'show dialog w/ options; same as AlertDialog props minus isOpen/onOpenChange', hide: 'hide dialog', diff --git a/packages/core/src/Dialog/useImperativeDialog.doc.mjs b/packages/core/src/Dialog/useImperativeDialog.doc.mjs index e79a94ee4506c..c93b54e0195e9 100644 --- a/packages/core/src/Dialog/useImperativeDialog.doc.mjs +++ b/packages/core/src/Dialog/useImperativeDialog.doc.mjs @@ -6,12 +6,14 @@ export const docs = { name: 'useImperativeDialog', subComponentOf: 'Dialog', displayName: 'useImperativeDialog', - description: 'Hook for showing a dialog without managing open state. Call dialog.show(content, options) to open and dialog.hide() to close. Render dialog.element in your JSX tree.', + description: + 'Hook for showing a dialog without managing open state. Call dialog.show(content, options) to open and dialog.hide() to close. Render dialog.element in your JSX tree.', props: [ { name: 'show', - type: '(content: ReactNode, options?: DialogOptions) => void', - description: 'Show the dialog with the given content. Options are the same as Dialog props minus isOpen/onOpenChange/children.', + type: "(content: ReactNode, options?: Omit) => void", + description: + 'Show the dialog with the given content. Options are the same as Dialog props minus isOpen/onOpenChange/children.', }, { name: 'hide', @@ -33,7 +35,8 @@ export const docs = { export const docsDense = { name: 'useImperativeDialog', - description: 'hook to show a dialog w/o managing open state; call dialog.show(content, options) to open + dialog.hide() to close; render dialog.element in your JSX tree', + description: + 'hook to show a dialog w/o managing open state; call dialog.show(content, options) to open + dialog.hide() to close; render dialog.element in your JSX tree', propDescriptions: { show: 'show the dialog with given content; options = Dialog props minus isOpen/onOpenChange/children', hide: 'hide the dialog', diff --git a/packages/core/src/Markdown/Markdown.doc.mjs b/packages/core/src/Markdown/Markdown.doc.mjs index 4276da428b647..305e57be3a9fc 100644 --- a/packages/core/src/Markdown/Markdown.doc.mjs +++ b/packages/core/src/Markdown/Markdown.doc.mjs @@ -143,7 +143,7 @@ export const docs = { }, { name: 'plugins', - type: 'readonly MarkdownPluginEntry[]', + type: 'readonly ReturnType[]', description: 'Ordered extensions created by createMarkdownPlugin(). Plugins may add bounded syntax, immutable typed AST transforms, and typed extension renderers. Use isMarkdownExtensionNode() to narrow extension data observed from other plugins. Renderer callbacks are pure; return a child component when hooks are needed. Omitted and empty lists preserve the released Markdown behavior.', }, @@ -687,7 +687,7 @@ export const docsZh = { }, { name: 'plugins', - type: 'readonly MarkdownPluginEntry[]', + type: 'readonly ReturnType[]', description: '由 createMarkdownPlugin() 创建的有序扩展。插件可添加有界语法、不可变的类型化 AST 转换和类型化扩展渲染器。使用 isMarkdownExtensionNode() 缩小从其他插件观察到的扩展数据类型。渲染回调必须是纯函数;需要 Hook 时请返回子组件。省略或传入空列表时保持已发布的 Markdown 行为。', }, @@ -1034,7 +1034,7 @@ export const docsDense = { contentAlign: "'start'|'center'. Prose alignment when contentWidth < container. Default: 'start'.", plugins: - 'readonly MarkdownPluginEntry[]. Ordered syntax, immutable AST transforms, and typed extension renderers from createMarkdownPlugin(), plus first-party helpers such as createMarkdownHeadingLinks(). Default: omitted or empty.', + 'readonly ReturnType[]. Ordered syntax, immutable AST transforms, and typed extension renderers from createMarkdownPlugin(), plus first-party helpers such as createMarkdownHeadingLinks(). Default: omitted or empty.', inlinePlugins: 'MarkdownInlinePlugin[]. Regex matches in text nodes -> custom inline React elements. Skips inline/fenced code and math.', autolink: diff --git a/packages/core/src/Selector/Selector.doc.mjs b/packages/core/src/Selector/Selector.doc.mjs index 5b5c7966b647f..3c42ed1f74bc9 100644 --- a/packages/core/src/Selector/Selector.doc.mjs +++ b/packages/core/src/Selector/Selector.doc.mjs @@ -182,7 +182,7 @@ export const docs = { }, { name: 'options', - type: 'SelectorOption[]', + type: 'SelectorOptionType[]', description: 'Array of items: strings, objects with value/label/description/icon/disabled, dividers ({type: "divider"}), or sections ({type: "section", title, options}).', required: true, diff --git a/packages/core/src/theme/SyntaxTheme.doc.mjs b/packages/core/src/theme/SyntaxTheme.doc.mjs index f2b5baeb82551..ef32688f8e9cf 100644 --- a/packages/core/src/theme/SyntaxTheme.doc.mjs +++ b/packages/core/src/theme/SyntaxTheme.doc.mjs @@ -59,7 +59,7 @@ export const docs = { props: [ { name: 'theme', - type: 'SyntaxTheme', + type: 'SyntaxThemeDefinition', required: true, description: 'Syntax highlighting theme: a preset from @astryxdesign/core/theme/syntax or a custom theme created with defineSyntaxTheme().', From 03c20f5a87f0907f8270edaf1746d9f0624482b6 Mon Sep 17 00:00:00 2001 From: cixzhang Date: Tue, 17 Nov 2026 03:58:16 -0800 Subject: [PATCH 02/10] docs(core): Toast's doc describes the card; useToast's doc gives the show options Toast's props table now matches ToastProps: type, isAutoHide and autoHideDuration are required, as the card takes them resolved. The show-only options (uniqueID, collisionBehavior, onHide) and the defaults the show function fills in move to useToast's doc. The Toast record names both docs. --- .changeset/docs-name-exported-types.md | 7 ++++ docs/specs/components/Toast/Toast.spec.md | 3 +- .../cli/test/core-prop-docs.known-drift.json | 6 --- packages/core/src/Toast/Toast.doc.mjs | 41 +++++-------------- packages/core/src/Toast/useToast.doc.mjs | 4 +- 5 files changed, 21 insertions(+), 40 deletions(-) create mode 100644 .changeset/docs-name-exported-types.md diff --git a/.changeset/docs-name-exported-types.md b/.changeset/docs-name-exported-types.md new file mode 100644 index 0000000000000..9d10ab84abab3 --- /dev/null +++ b/.changeset/docs-name-exported-types.md @@ -0,0 +1,7 @@ +--- +'@astryxdesign/core': patch +--- + +[docs] Component and hook docs name only types the package exports. Selector's `options` are `SelectorOptionType[]`, SyntaxTheme's `theme` is a `SyntaxThemeDefinition`, Markdown's `plugins` are what `createMarkdownPlugin()` returns, and `useImperativeDialog` and `useImperativeAlertDialog` write their `show()` options with the exported Dialog and AlertDialog props. Toast's doc describes the card: `type`, `isAutoHide` and `autoHideDuration` are required there, and `useToast`'s doc lists the show options and their defaults (`uniqueID`, `collisionBehavior`, `onHide`). + +@cixzhang diff --git a/docs/specs/components/Toast/Toast.spec.md b/docs/specs/components/Toast/Toast.spec.md index adeefca06b9bc..fcf9bce4de7fc 100644 --- a/docs/specs/components/Toast/Toast.spec.md +++ b/docs/specs/components/Toast/Toast.spec.md @@ -70,7 +70,8 @@ This table is a review projection; the body below is authoritative. Toast shows brief, non-modal notifications. This record covers the toast card (`Toast`), the viewport that stacks, hosts, and announces toasts (`ToastViewport`, which has no consumer doc of its own), and the behavior the -`useToast` show function drives. Consumer usage lives in `Toast.doc.mjs`. +`useToast` show function drives. Consumer usage lives in `Toast.doc.mjs` (the +card) and `useToast.doc.mjs` (the show function). ## Compatibility and migration diff --git a/packages/cli/test/core-prop-docs.known-drift.json b/packages/cli/test/core-prop-docs.known-drift.json index 93ecab03d29ac..c4616aeb540ab 100644 --- a/packages/cli/test/core-prop-docs.known-drift.json +++ b/packages/cli/test/core-prop-docs.known-drift.json @@ -55,13 +55,7 @@ "src/TimeInput/TimeInput.doc.mjs TimeInput.controlClassName not_in_doc", "src/TimeInput/TimeInput.doc.mjs TimeInput.controlStyle not_in_doc", "src/TimeInput/TimeInput.doc.mjs TimeInput.hasAutoFocus not_in_doc", - "src/Toast/Toast.doc.mjs Toast.autoHideDuration required_mismatch", - "src/Toast/Toast.doc.mjs Toast.collisionBehavior not_in_code", - "src/Toast/Toast.doc.mjs Toast.isAutoHide required_mismatch", "src/Toast/Toast.doc.mjs Toast.isExiting not_in_doc", - "src/Toast/Toast.doc.mjs Toast.onHide not_in_code", - "src/Toast/Toast.doc.mjs Toast.type required_mismatch", - "src/Toast/Toast.doc.mjs Toast.uniqueID not_in_code", "src/Tokenizer/Tokenizer.doc.mjs Tokenizer.onKeyDown not_in_doc", "src/Tooltip/Tooltip.doc.mjs Tooltip.content required_mismatch", "src/TopNav/TopNavHeading.doc.mjs TopNavHeading.logoLabel not_in_doc", diff --git a/packages/core/src/Toast/Toast.doc.mjs b/packages/core/src/Toast/Toast.doc.mjs index c2c6bea9cfc70..9466928e2ef62 100644 --- a/packages/core/src/Toast/Toast.doc.mjs +++ b/packages/core/src/Toast/Toast.doc.mjs @@ -36,21 +36,22 @@ export const docs = { name: 'type', type: "'info' | 'error'", description: - 'Toast type controlling background color. Error toasts persist until dismissed.', - default: "'info'", + "Toast type controlling background color. Error toasts persist until dismissed. useToast()'s show function sets 'info' when it is not given.", + required: true, }, { name: 'isAutoHide', type: 'boolean', description: - 'Whether the toast auto-dismisses. Defaults to true for info, false for error.', + "Whether the toast auto-dismisses. useToast()'s show function sets true for info and false for error when it is not given.", + required: true, }, { name: 'autoHideDuration', type: 'number', description: - 'Duration in ms before auto-dismiss. Timed content must satisfy WCAG 2.2.1.', - default: '5000', + "Duration in ms before auto-dismiss. Timed content must satisfy WCAG 2.2.1. useToast()'s show function sets 5000 when it is not given.", + required: true, }, { name: 'endContent', @@ -62,23 +63,6 @@ export const docs = { {__element: 'Badge', props: {label: '3'}}, ], }, - { - name: 'uniqueID', - type: 'string', - description: 'Unique identifier for deduplication.', - }, - { - name: 'collisionBehavior', - type: "'overwrite' | 'ignore'", - description: - 'Behavior when a toast with matching uniqueID already exists.', - default: "'overwrite'", - }, - { - name: 'onHide', - type: '(reason: "auto" | "manual") => void', - description: 'Callback fired when the toast is removed.', - }, { name: 'onDismiss', type: '(reason: "auto" | "manual") => void', @@ -146,7 +130,7 @@ export const docs = { { guidance: true, description: - 'Use uniqueID to deduplicate toasts that fire from repeated actions, like clicking a save button multiple times.', + "Pass useToast()'s uniqueID option to deduplicate toasts that fire from repeated actions, like clicking a save button multiple times.", }, { guidance: true, @@ -207,9 +191,6 @@ export const docsZh = { autoHideDuration: '自动关闭前的持续时间(毫秒)。定时内容必须符合 WCAG 2.2.1。', endContent: '尾部渲染的内容(如撤销按钮、链接)。操作标签应保持简短。', - uniqueID: '用于去重的唯一标识符。', - collisionBehavior: '当已存在相同 uniqueID 的 toast 时的行为。', - onHide: '当 toast 被移除时触发的回调。', renderContent: "用你自己的布局替换该 toast 卡片内部的内容。Astryx 保留卡片本身、astryx-toast 主题目标和自动关闭行为(在 ToastViewport 中由视口播报该 toast;当模态框承载视口时由卡片自行播报),并把消息、endContent、解析后的 toast 设置和 dismiss 回调交给渲染函数。自定义渲染函数完全拥有布局中的控件:请组合所需的控件并通过它调用 dismiss。Astryx 不会向自定义内容注入后备关闭按钮。按 toast 单独设置:应用可通过封装 useToast 并在每次调用时传入来共享同一套布局;而由库代码发起、从不传入该参数的 toast 会渲染为普通的 Astryx toast。传入参数为 {body, endContent, type, isAutoHide, autoHideDuration, dismiss},其中 type 为 'info' | 'error'。", }, @@ -230,7 +211,7 @@ export const docsZh = { { guidance: true, description: - '使用 uniqueID 去重重复操作触发的 toast,如多次点击保存按钮。', + '传入 useToast() 的 uniqueID 选项,去重重复操作触发的 toast,如多次点击保存按钮。', }, { guidance: true, @@ -293,7 +274,8 @@ export const docsDense = { }, { guidance: true, - description: 'uniqueID to dedup repeated action toasts.', + description: + "useToast()'s uniqueID option to dedup repeated action toasts.", }, { guidance: true, @@ -325,9 +307,6 @@ export const docsDense = { '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', }, diff --git a/packages/core/src/Toast/useToast.doc.mjs b/packages/core/src/Toast/useToast.doc.mjs index 17f7623f8a0ce..a1965deb43db1 100644 --- a/packages/core/src/Toast/useToast.doc.mjs +++ b/packages/core/src/Toast/useToast.doc.mjs @@ -13,7 +13,7 @@ export const docs = { { name: 'showToast', type: '(options: ToastOptions) => () => void', - description: 'Show a toast notification. Returns a dismiss function. Options include body (ReactNode), type ("info" | "error"), isAutoHide, autoHideDuration, endContent, uniqueID, and collisionBehavior.', + description: 'Show a toast notification. Returns a dismiss function. Options: body (ReactNode, required); type ("info" | "error", default "info"); isAutoHide (default true for info, false for error); autoHideDuration (ms, default 5000); endContent; renderContent; uniqueID, which deduplicates toasts; collisionBehavior ("overwrite" | "ignore", default "overwrite"), what a show with an existing uniqueID does; and onHide, called with "auto" or "manual" when the toast is removed.', }, ], usage: { @@ -35,7 +35,7 @@ export const docs = { export const docsDense = { description: 'Show toast notifications from anywhere in component tree. Returns function accepting toast options + showing notification. Works automatically w/ LayerProvider / self-mounts fallback viewport.', returnDescriptions: { - showToast: 'show toast notification. Returns dismiss function. Options: body (ReactNode), type ("info" | "error"), isAutoHide, autoHideDuration, endContent, uniqueID, collisionBehavior.', + showToast: 'show toast notification. Returns dismiss function. Options: body (ReactNode, required), type ("info" | "error", default "info"), isAutoHide (default true for info, false for error), autoHideDuration (default 5000 ms), endContent, renderContent, uniqueID (dedup), collisionBehavior ("overwrite" default | "ignore"), onHide (reason "auto" | "manual").', }, usage: { description: 'Show toast notifications from anywhere in component tree. Returns function accepting toast options + showing notification. Works automatically w/ LayerProvider / self-mounts fallback viewport.', From 305b2de2d6ec5971188326a9c4740e30664db37a Mon Sep 17 00:00:00 2001 From: cixzhang Date: Tue, 17 Nov 2026 05:47:21 -0800 Subject: [PATCH 03/10] docs(core): Markdown keeps MarkdownPluginEntry; Toast states what show sets in every language MarkdownPluginEntry is exported from @astryxdesign/core/Markdown/plugins, so the Markdown doc keeps naming it. The Toast card does not decide that an error toast persists: useToast()\s show function sets isAutoHide to false for one, so that sentence moves to isAutoHide, and the zh and dense text say what show sets for each required prop. The changeset names the docs this changes. --- .changeset/docs-name-exported-types.md | 2 +- packages/core/src/Markdown/Markdown.doc.mjs | 6 +- packages/core/src/Toast/Toast.doc.mjs | 18 ++--- packages/core/src/Toast/useToast.doc.mjs | 73 +++++++++++++++++---- 4 files changed, 73 insertions(+), 26 deletions(-) diff --git a/.changeset/docs-name-exported-types.md b/.changeset/docs-name-exported-types.md index 9d10ab84abab3..3553bd3b43891 100644 --- a/.changeset/docs-name-exported-types.md +++ b/.changeset/docs-name-exported-types.md @@ -2,6 +2,6 @@ '@astryxdesign/core': patch --- -[docs] Component and hook docs name only types the package exports. Selector's `options` are `SelectorOptionType[]`, SyntaxTheme's `theme` is a `SyntaxThemeDefinition`, Markdown's `plugins` are what `createMarkdownPlugin()` returns, and `useImperativeDialog` and `useImperativeAlertDialog` write their `show()` options with the exported Dialog and AlertDialog props. Toast's doc describes the card: `type`, `isAutoHide` and `autoHideDuration` are required there, and `useToast`'s doc lists the show options and their defaults (`uniqueID`, `collisionBehavior`, `onHide`). +[docs] Four docs name prop types the package exports. Selector's `options` are `SelectorOptionType[]` (`SelectorOption` is a component), SyntaxTheme's `theme` is a `SyntaxThemeDefinition`, and `useImperativeDialog` and `useImperativeAlertDialog` write their `show()` options with the exported Dialog and AlertDialog props. Toast's doc describes the card: `type`, `isAutoHide` and `autoHideDuration` are required there, and `useToast`'s doc lists the show options and their defaults (`uniqueID`, `collisionBehavior`, `onHide`). @cixzhang diff --git a/packages/core/src/Markdown/Markdown.doc.mjs b/packages/core/src/Markdown/Markdown.doc.mjs index 305e57be3a9fc..4276da428b647 100644 --- a/packages/core/src/Markdown/Markdown.doc.mjs +++ b/packages/core/src/Markdown/Markdown.doc.mjs @@ -143,7 +143,7 @@ export const docs = { }, { name: 'plugins', - type: 'readonly ReturnType[]', + type: 'readonly MarkdownPluginEntry[]', description: 'Ordered extensions created by createMarkdownPlugin(). Plugins may add bounded syntax, immutable typed AST transforms, and typed extension renderers. Use isMarkdownExtensionNode() to narrow extension data observed from other plugins. Renderer callbacks are pure; return a child component when hooks are needed. Omitted and empty lists preserve the released Markdown behavior.', }, @@ -687,7 +687,7 @@ export const docsZh = { }, { name: 'plugins', - type: 'readonly ReturnType[]', + type: 'readonly MarkdownPluginEntry[]', description: '由 createMarkdownPlugin() 创建的有序扩展。插件可添加有界语法、不可变的类型化 AST 转换和类型化扩展渲染器。使用 isMarkdownExtensionNode() 缩小从其他插件观察到的扩展数据类型。渲染回调必须是纯函数;需要 Hook 时请返回子组件。省略或传入空列表时保持已发布的 Markdown 行为。', }, @@ -1034,7 +1034,7 @@ export const docsDense = { contentAlign: "'start'|'center'. Prose alignment when contentWidth < container. Default: 'start'.", plugins: - 'readonly ReturnType[]. Ordered syntax, immutable AST transforms, and typed extension renderers from createMarkdownPlugin(), plus first-party helpers such as createMarkdownHeadingLinks(). Default: omitted or empty.', + 'readonly MarkdownPluginEntry[]. Ordered syntax, immutable AST transforms, and typed extension renderers from createMarkdownPlugin(), plus first-party helpers such as createMarkdownHeadingLinks(). Default: omitted or empty.', inlinePlugins: 'MarkdownInlinePlugin[]. Regex matches in text nodes -> custom inline React elements. Skips inline/fenced code and math.', autolink: diff --git a/packages/core/src/Toast/Toast.doc.mjs b/packages/core/src/Toast/Toast.doc.mjs index 9466928e2ef62..ebd54533e4f55 100644 --- a/packages/core/src/Toast/Toast.doc.mjs +++ b/packages/core/src/Toast/Toast.doc.mjs @@ -36,14 +36,14 @@ export const docs = { name: 'type', type: "'info' | 'error'", description: - "Toast type controlling background color. Error toasts persist until dismissed. useToast()'s show function sets 'info' when it is not given.", + "Toast type controlling background color. useToast()'s show function sets 'info' when it is not given.", required: true, }, { name: 'isAutoHide', type: 'boolean', description: - "Whether the toast auto-dismisses. useToast()'s show function sets true for info and false for error when it is not given.", + "Whether the toast auto-dismisses. useToast()'s show function sets true for info and false for error when it is not given, so an error toast it shows persists until dismissed.", required: true, }, { @@ -186,10 +186,11 @@ export const docs = { export const docsZh = { propDescriptions: { body: '主要消息内容。', - type: 'Toast 类型,控制背景颜色。error toast 持续显示直到关闭。', - isAutoHide: '是否自动关闭。info 默认为 true,error 默认为 false。', + type: 'Toast 类型,控制背景颜色。未传入时,useToast() 的 show 函数设为 info。', + isAutoHide: + '是否自动关闭。未传入时,useToast() 的 show 函数对 info 设为 true、对 error 设为 false,因此它显示的 error toast 会持续显示直到关闭。', autoHideDuration: - '自动关闭前的持续时间(毫秒)。定时内容必须符合 WCAG 2.2.1。', + '自动关闭前的持续时间(毫秒)。定时内容必须符合 WCAG 2.2.1。未传入时,useToast() 的 show 函数设为 5000。', endContent: '尾部渲染的内容(如撤销按钮、链接)。操作标签应保持简短。', renderContent: "用你自己的布局替换该 toast 卡片内部的内容。Astryx 保留卡片本身、astryx-toast 主题目标和自动关闭行为(在 ToastViewport 中由视口播报该 toast;当模态框承载视口时由卡片自行播报),并把消息、endContent、解析后的 toast 设置和 dismiss 回调交给渲染函数。自定义渲染函数完全拥有布局中的控件:请组合所需的控件并通过它调用 dismiss。Astryx 不会向自定义内容注入后备关闭按钮。按 toast 单独设置:应用可通过封装 useToast 并在每次调用时传入来共享同一套布局;而由库代码发起、从不传入该参数的 toast 会渲染为普通的 Astryx toast。传入参数为 {body, endContent, type, isAutoHide, autoHideDuration, dismiss},其中 type 为 'info' | 'error'。", @@ -301,10 +302,11 @@ export const docsDense = { }, propDescriptions: { body: 'primary message content', - type: 'toast type; controls bg color; error persists until dismissed', - isAutoHide: 'auto-dismiss; true for info, false for error', + type: 'toast type; controls bg color; useToast() show sets info when omitted', + isAutoHide: + 'auto-dismiss; useToast() show sets true for info, false for error when omitted (so its error toasts persist until dismissed)', autoHideDuration: - 'ms before auto-dismiss; timed content must satisfy WCAG 2.2.1', + 'ms before auto-dismiss; timed content must satisfy WCAG 2.2.1; useToast() show sets 5000 when omitted', endContent: 'trailing end content (undo btn, link); keep action labels short', renderContent: diff --git a/packages/core/src/Toast/useToast.doc.mjs b/packages/core/src/Toast/useToast.doc.mjs index a1965deb43db1..2c6b26a631f62 100644 --- a/packages/core/src/Toast/useToast.doc.mjs +++ b/packages/core/src/Toast/useToast.doc.mjs @@ -5,7 +5,15 @@ export const docs = { name: 'useToast', displayName: 'useToast', group: 'Toast', - keywords: ['toast', 'notification', 'snackbar', 'alert', 'message', 'feedback', 'flash'], + keywords: [ + 'toast', + 'notification', + 'snackbar', + 'alert', + 'message', + 'feedback', + 'flash', + ], params: [ // useToast takes no arguments; returns a show function ], @@ -13,16 +21,34 @@ export const docs = { { name: 'showToast', type: '(options: ToastOptions) => () => void', - description: 'Show a toast notification. Returns a dismiss function. Options: body (ReactNode, required); type ("info" | "error", default "info"); isAutoHide (default true for info, false for error); autoHideDuration (ms, default 5000); endContent; renderContent; uniqueID, which deduplicates toasts; collisionBehavior ("overwrite" | "ignore", default "overwrite"), what a show with an existing uniqueID does; and onHide, called with "auto" or "manual" when the toast is removed.', + description: + 'Show a toast notification. Returns a dismiss function. Options: body (ReactNode, required); type ("info" | "error", default "info"); isAutoHide (default true for info, false for error); autoHideDuration (ms, default 5000); endContent; renderContent; uniqueID, which deduplicates toasts; collisionBehavior ("overwrite" | "ignore", default "overwrite"), what a show with an existing uniqueID does; and onHide, called with "auto" or "manual" when the toast is removed.', }, ], usage: { - description: 'Hook for showing toast notifications from anywhere in your component tree. Returns a function that accepts toast options and shows the notification. Works automatically with LayerProvider or self-mounts a fallback viewport.', + description: + 'Hook for showing toast notifications from anywhere in your component tree. Returns a function that accepts toast options and shows the notification. Works automatically with LayerProvider or self-mounts a fallback viewport.', bestPractices: [ - {guidance: true, description: 'Use for transient success/error feedback that does not require user action.'}, - {guidance: true, description: 'Set uniqueID to deduplicate toasts from rapid user actions.'}, - {guidance: false, description: 'Use for critical errors that require acknowledgment; use AlertDialog instead.'}, - {guidance: false, description: 'Call useToast in the same component that renders LayerProvider; it must be called from a child component inside the provider.'}, + { + guidance: true, + description: + 'Use for transient success/error feedback that does not require user action.', + }, + { + guidance: true, + description: + 'Set uniqueID to deduplicate toasts from rapid user actions.', + }, + { + guidance: false, + description: + 'Use for critical errors that require acknowledgment; use AlertDialog instead.', + }, + { + guidance: false, + description: + 'Call useToast in the same component that renders LayerProvider; it must be called from a child component inside the provider.', + }, ], }, relatedComponents: ['Toast', 'Banner', 'AlertDialog'], @@ -33,17 +59,36 @@ export const docs = { /** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */ export const docsDense = { - description: 'Show toast notifications from anywhere in component tree. Returns function accepting toast options + showing notification. Works automatically w/ LayerProvider / self-mounts fallback viewport.', + description: + 'Show toast notifications from anywhere in component tree. Returns function accepting toast options + showing notification. Works automatically w/ LayerProvider / self-mounts fallback viewport.', returnDescriptions: { - showToast: 'show toast notification. Returns dismiss function. Options: body (ReactNode, required), type ("info" | "error", default "info"), isAutoHide (default true for info, false for error), autoHideDuration (default 5000 ms), endContent, renderContent, uniqueID (dedup), collisionBehavior ("overwrite" default | "ignore"), onHide (reason "auto" | "manual").', + showToast: + 'show toast notification. Returns dismiss function. Options: body (ReactNode, required), type ("info" | "error", default "info"), isAutoHide (default true for info, false for error), autoHideDuration (default 5000 ms), endContent, renderContent, uniqueID (dedup), collisionBehavior ("overwrite" default | "ignore"), onHide (reason "auto" | "manual").', }, usage: { - description: 'Show toast notifications from anywhere in component tree. Returns function accepting toast options + showing notification. Works automatically w/ LayerProvider / self-mounts fallback viewport.', + description: + 'Show toast notifications from anywhere in component tree. Returns function accepting toast options + showing notification. Works automatically w/ LayerProvider / self-mounts fallback viewport.', bestPractices: [ - {guidance: true, description: 'Use for transient success/error feedback not requiring user action.'}, - {guidance: true, description: 'Set uniqueID to deduplicate toasts from rapid user actions.'}, - {guidance: false, description: 'Use for critical errors requiring acknowledgment; use AlertDialog instead.'}, - {guidance: false, description: 'Call useToast in same component that renders LayerProvider; must be called from child component inside provider.'}, + { + guidance: true, + description: + 'Use for transient success/error feedback not requiring user action.', + }, + { + guidance: true, + description: + 'Set uniqueID to deduplicate toasts from rapid user actions.', + }, + { + guidance: false, + description: + 'Use for critical errors requiring acknowledgment; use AlertDialog instead.', + }, + { + guidance: false, + description: + 'Call useToast in same component that renders LayerProvider; must be called from child component inside provider.', + }, ], }, }; From b0a864e0fe0740a8953dd0fec4ffadb035208731 Mon Sep 17 00:00:00 2001 From: cixzhang Date: Tue, 17 Nov 2026 08:27:44 -0800 Subject: [PATCH 04/10] docs(core): Toast's playground starts with the values show sets Without defaults on the now-required type, isAutoHide and autoHideDuration, the docsite playground started autoHideDuration at 0. Its defaults are now the values useToast()'s show function sets. --- packages/core/src/Toast/Toast.doc.mjs | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/packages/core/src/Toast/Toast.doc.mjs b/packages/core/src/Toast/Toast.doc.mjs index ebd54533e4f55..b3ab31a3c77af 100644 --- a/packages/core/src/Toast/Toast.doc.mjs +++ b/packages/core/src/Toast/Toast.doc.mjs @@ -19,7 +19,14 @@ export const docs = { ], playground: { - defaults: {body: 'Changes saved'}, + // The values useToast()'s show function sets, so the playground's toast + // starts as a shown info toast does. + defaults: { + body: 'Changes saved', + type: 'info', + isAutoHide: true, + autoHideDuration: 5000, + }, }, props: [ From 503c1bc56fd6315ad737f96b21e1686d126cc902 Mon Sep 17 00:00:00 2001 From: cixzhang Date: Tue, 17 Nov 2026 13:23:12 -0800 Subject: [PATCH 05/10] docs(docsite): a SyntaxThemeDefinition prop gets the syntax theme preset control SyntaxTheme's doc now types theme as SyntaxThemeDefinition, and the playground still picked the preset control by the old name, so the SyntaxTheme page rendered with no picker and a render error. CodeBlock's syntaxTheme row, typed the same way, gets the picker too. --- apps/docsite/src/__tests__/component-prop-controls.test.ts | 6 ++++++ .../src/components/component-detail/parsePropType.ts | 2 +- 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/apps/docsite/src/__tests__/component-prop-controls.test.ts b/apps/docsite/src/__tests__/component-prop-controls.test.ts index c93865aa61fc5..1f95e09234246 100644 --- a/apps/docsite/src/__tests__/component-prop-controls.test.ts +++ b/apps/docsite/src/__tests__/component-prop-controls.test.ts @@ -90,6 +90,12 @@ describe('component detail prop controls', () => { } }); + it('gives a SyntaxThemeDefinition prop the syntax theme preset control', () => { + expect(parsePropType('SyntaxThemeDefinition', 'theme')).toEqual({ + kind: 'syntax-theme', + }); + }); + it('derives IconType options from the canonical icon registry', () => { const control = parsePropType('IconType', 'labelIcon'); diff --git a/apps/docsite/src/components/component-detail/parsePropType.ts b/apps/docsite/src/components/component-detail/parsePropType.ts index 3a1a1b9f124b5..c7f25c1f4d8b0 100644 --- a/apps/docsite/src/components/component-detail/parsePropType.ts +++ b/apps/docsite/src/components/component-detail/parsePropType.ts @@ -183,7 +183,7 @@ export function parsePropType( if (t === 'DefinedTheme') { return {kind: 'theme'}; } - if (t === 'SyntaxTheme') { + if (t === 'SyntaxThemeDefinition') { return {kind: 'syntax-theme'}; } if (t === 'IconType' || t === 'IconName') { From f245db13e1bb2a2e356bdb6e97e18c4896b26ef8 Mon Sep 17 00:00:00 2001 From: cixzhang Date: Tue, 17 Nov 2026 15:59:25 -0800 Subject: [PATCH 06/10] docs(docsite): an optional syntax-theme row starts at None and can return to it The syntax-theme picker now also serves CodeBlock's and Lab DiffViewer's optional syntaxTheme rows. For an optional prop it offers None first, shows None while the prop is unset, and None sends nothing, so the preview keeps the theme-level syntax colors. A required prop keeps the presets only. --- .../__tests__/syntax-theme-control.test.ts | 31 ++++++++++ .../component-detail/PlaygroundPropsTable.tsx | 49 ++++++--------- .../component-detail/syntaxThemeChoices.ts | 61 +++++++++++++++++++ 3 files changed, 109 insertions(+), 32 deletions(-) create mode 100644 apps/docsite/src/__tests__/syntax-theme-control.test.ts create mode 100644 apps/docsite/src/components/component-detail/syntaxThemeChoices.ts diff --git a/apps/docsite/src/__tests__/syntax-theme-control.test.ts b/apps/docsite/src/__tests__/syntax-theme-control.test.ts new file mode 100644 index 0000000000000..084684231253a --- /dev/null +++ b/apps/docsite/src/__tests__/syntax-theme-control.test.ts @@ -0,0 +1,31 @@ +// Copyright (c) Meta Platforms, Inc. and affiliates. + +import {allSyntaxPresets} from '@astryxdesign/core/theme/syntax'; +import {describe, expect, it} from 'vitest'; +import { + NO_SYNTAX_THEME, + selectedSyntaxTheme, + syntaxThemeChoices, + syntaxThemeFor, +} from '../components/component-detail/syntaxThemeChoices'; + +describe('the playground syntax theme control', () => { + it('shows an unset optional prop as None, and None sends nothing', () => { + expect(syntaxThemeChoices(false)[0].value).toBe(NO_SYNTAX_THEME); + expect(selectedSyntaxTheme(undefined, false)).toBe(NO_SYNTAX_THEME); + expect(syntaxThemeFor(NO_SYNTAX_THEME)).toBeUndefined(); + }); + + it('offers no None for a required prop, which shows the first preset', () => { + expect( + syntaxThemeChoices(true).some(choice => choice.value === NO_SYNTAX_THEME), + ).toBe(false); + expect(selectedSyntaxTheme(undefined, true)).toBe(allSyntaxPresets[0].name); + }); + + it('shows and sends a chosen preset', () => { + const preset = allSyntaxPresets[1]; + expect(selectedSyntaxTheme(preset, false)).toBe(preset.name); + expect(syntaxThemeFor(preset.name)).toBe(preset); + }); +}); diff --git a/apps/docsite/src/components/component-detail/PlaygroundPropsTable.tsx b/apps/docsite/src/components/component-detail/PlaygroundPropsTable.tsx index 07a8d3736e6ba..5af36961f033a 100644 --- a/apps/docsite/src/components/component-detail/PlaygroundPropsTable.tsx +++ b/apps/docsite/src/components/component-detail/PlaygroundPropsTable.tsx @@ -22,9 +22,13 @@ import {Badge} from '@astryxdesign/core/Badge'; import {IconButton} from '@astryxdesign/core/IconButton'; import {Minus, Plus} from 'lucide-react'; import {useMediaQuery} from '@astryxdesign/core/hooks'; -import {allSyntaxPresets} from '@astryxdesign/core/theme/syntax'; import {themeObjectsFull} from '../../generated/themeRegistry'; import {coerceEnumOption, type PropControlDescriptor} from './parsePropType'; +import { + selectedSyntaxTheme, + syntaxThemeChoices, + syntaxThemeFor, +} from './syntaxThemeChoices'; import {resolveTypeRefs, TypeRefText} from './TypeRefText'; import type {KnobProp} from './InteractivePreview'; import {resolveElementDescriptor} from './resolveElements'; @@ -166,15 +170,6 @@ const themeOptions = Object.entries(themeObjectsFull).map( }), ); -const syntaxThemeOptions = allSyntaxPresets.map(theme => ({ - value: theme.name, - label: theme.name - .split('-') - .map(part => part.charAt(0).toUpperCase() + part.slice(1)) - .join(' '), - theme, -})); - function ThemeControl({ value, onChange, @@ -217,36 +212,20 @@ function ThemeControl({ function SyntaxThemeControl({ value, + isRequired, onChange, }: { value: unknown; + isRequired: boolean; onChange: (next: unknown) => void; }) { - const selected = - syntaxThemeOptions.find( - option => - option.theme === value || - (value != null && - typeof value === 'object' && - 'name' in value && - option.theme.name === value.name), - )?.value ?? syntaxThemeOptions[0].value; - return ( ({ - value: optionValue, - label, - }))} - onChange={next => { - const match = syntaxThemeOptions.find(option => option.value === next); - if (match) { - onChange(match.theme); - } - }} + value={selectedSyntaxTheme(value, isRequired)} + options={syntaxThemeChoices(isRequired)} + onChange={next => onChange(syntaxThemeFor(next))} /> ); } @@ -475,7 +454,13 @@ function InlineControl({ case 'theme': return ; case 'syntax-theme': - return ; + return ( + + ); case 'string': return ( ({ + value: theme.name, + label: theme.name + .split('-') + .map(part => part.charAt(0).toUpperCase() + part.slice(1)) + .join(' '), + theme, +})); + +/** + * The presets, with a first choice that leaves the prop unset when the prop + * is optional. An unset prop keeps the theme-level syntax colors. + */ +export function syntaxThemeChoices( + isRequired: boolean, +): {value: string; label: string}[] { + const choices = presets.map(({value, label}) => ({value, label})); + return isRequired + ? choices + : [{value: NO_SYNTAX_THEME, label: NO_SYNTAX_THEME}, ...choices]; +} + +/** The choice that shows `value`. */ +export function selectedSyntaxTheme( + value: unknown, + isRequired: boolean, +): string { + const match = presets.find( + option => + option.theme === value || + (value != null && + typeof value === 'object' && + 'name' in value && + option.theme.name === value.name), + ); + if (match) { + return match.value; + } + return isRequired ? presets[0].value : NO_SYNTAX_THEME; +} + +/** The value a choice sends: a preset, or nothing for the unset choice. */ +export function syntaxThemeFor(choice: string): unknown { + return presets.find(option => option.value === choice)?.theme; +} From db9363664f97946b393cfb11ff6bccf20fc3d912 Mon Sep 17 00:00:00 2001 From: cixzhang Date: Tue, 17 Nov 2026 18:56:20 -0800 Subject: [PATCH 07/10] docs(docsite): Show code names a syntax preset by its identifier A syntax preset picked in the playground printed as the whole preset object. Show code now prints the identifier the preset is exported as, such as syntaxTheme={dracula}, for any prop. --- .../src/__tests__/syntax-theme-control.test.ts | 11 +++++++++++ .../component-detail/InteractivePreview.tsx | 5 +++++ .../component-detail/syntaxThemeChoices.ts | 18 ++++++++++++++++-- 3 files changed, 32 insertions(+), 2 deletions(-) diff --git a/apps/docsite/src/__tests__/syntax-theme-control.test.ts b/apps/docsite/src/__tests__/syntax-theme-control.test.ts index 084684231253a..332053158901a 100644 --- a/apps/docsite/src/__tests__/syntax-theme-control.test.ts +++ b/apps/docsite/src/__tests__/syntax-theme-control.test.ts @@ -6,6 +6,7 @@ import { NO_SYNTAX_THEME, selectedSyntaxTheme, syntaxThemeChoices, + syntaxPresetIdentifier, syntaxThemeFor, } from '../components/component-detail/syntaxThemeChoices'; @@ -28,4 +29,14 @@ describe('the playground syntax theme control', () => { expect(selectedSyntaxTheme(preset, false)).toBe(preset.name); expect(syntaxThemeFor(preset.name)).toBe(preset); }); + + it('names a preset by its exported identifier in code', () => { + const dracula = allSyntaxPresets.find(theme => theme.name === 'dracula'); + const oneDarkPro = allSyntaxPresets.find( + theme => theme.name === 'one-dark-pro', + ); + expect(syntaxPresetIdentifier(dracula)).toBe('dracula'); + expect(syntaxPresetIdentifier(oneDarkPro)).toBe('oneDarkPro'); + expect(syntaxPresetIdentifier({name: 'dracula'})).toBeNull(); + }); }); diff --git a/apps/docsite/src/components/component-detail/InteractivePreview.tsx b/apps/docsite/src/components/component-detail/InteractivePreview.tsx index 1d18ef87b23fb..7d2aaf8e30843 100644 --- a/apps/docsite/src/components/component-detail/InteractivePreview.tsx +++ b/apps/docsite/src/components/component-detail/InteractivePreview.tsx @@ -14,6 +14,7 @@ import { } from 'react'; import * as stylex from '@stylexjs/stylex'; import {getComponent, resolveValue} from './resolveElements'; +import {syntaxPresetIdentifier} from './syntaxThemeChoices'; import {AppShellMobileContext} from '@astryxdesign/core/AppShell'; import {Button} from '@astryxdesign/core/Button'; import {Card} from '@astryxdesign/core/Card'; @@ -122,6 +123,10 @@ function formatValue( if (value === null) { return 'null'; } + const syntaxPreset = syntaxPresetIdentifier(value); + if (syntaxPreset != null) { + return syntaxPreset; + } if ( value != null && typeof value === 'object' && diff --git a/apps/docsite/src/components/component-detail/syntaxThemeChoices.ts b/apps/docsite/src/components/component-detail/syntaxThemeChoices.ts index 177e4c461a0a8..3ae0044cc3591 100644 --- a/apps/docsite/src/components/component-detail/syntaxThemeChoices.ts +++ b/apps/docsite/src/components/component-detail/syntaxThemeChoices.ts @@ -3,8 +3,8 @@ /** * @file syntaxThemeChoices.ts * @input The value of a syntax-theme prop and whether the prop is required - * @output The preset choices the playground offers, the selected choice, and - * the value a choice sends + * @output The preset choices the playground offers, the selected choice, the + * value a choice sends, and the identifier that names a preset in code * @position Logic of the playground's syntax-theme control * (PlaygroundPropsTable) */ @@ -55,6 +55,20 @@ export function selectedSyntaxTheme( return isRequired ? presets[0].value : NO_SYNTAX_THEME; } +/** + * The identifier a preset is exported as, such as `oneDarkPro` for + * "one-dark-pro"; null when `value` is not a preset. + */ +export function syntaxPresetIdentifier(value: unknown): string | null { + const match = presets.find(option => option.theme === value); + if (!match) { + return null; + } + return match.value.replace(/-([a-z0-9])/g, (_, next: string) => + next.toUpperCase(), + ); +} + /** The value a choice sends: a preset, or nothing for the unset choice. */ export function syntaxThemeFor(choice: string): unknown { return presets.find(option => option.value === choice)?.theme; From 83a4ebcc2b82e9c193ff744a25a7ff2048cf7a93 Mon Sep 17 00:00:00 2001 From: cixzhang Date: Wed, 18 Nov 2026 14:28:19 -0800 Subject: [PATCH 08/10] docs(changeset): the show-only Toast options leave its props table because the useToast doc lists them --- .changeset/docs-name-exported-types.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.changeset/docs-name-exported-types.md b/.changeset/docs-name-exported-types.md index 3553bd3b43891..5389389493748 100644 --- a/.changeset/docs-name-exported-types.md +++ b/.changeset/docs-name-exported-types.md @@ -2,6 +2,6 @@ '@astryxdesign/core': patch --- -[docs] Four docs name prop types the package exports. Selector's `options` are `SelectorOptionType[]` (`SelectorOption` is a component), SyntaxTheme's `theme` is a `SyntaxThemeDefinition`, and `useImperativeDialog` and `useImperativeAlertDialog` write their `show()` options with the exported Dialog and AlertDialog props. Toast's doc describes the card: `type`, `isAutoHide` and `autoHideDuration` are required there, and `useToast`'s doc lists the show options and their defaults (`uniqueID`, `collisionBehavior`, `onHide`). +[docs] Four docs name prop types the package exports. Selector's `options` are `SelectorOptionType[]` (`SelectorOption` is a component), SyntaxTheme's `theme` is a `SyntaxThemeDefinition`, and `useImperativeDialog` and `useImperativeAlertDialog` write their `show()` options with the exported Dialog and AlertDialog props. Toast's doc describes the card: `type`, `isAutoHide` and `autoHideDuration` are required there, and the show-only options (`uniqueID`, `collisionBehavior`, `onHide`) leave its props table, because `useToast`'s doc lists them with their defaults. @cixzhang From 85268d7cf5612093d64b1ff1920fce3bd087c4ed Mon Sep 17 00:00:00 2001 From: cixzhang Date: Fri, 20 Nov 2026 04:23:38 -0800 Subject: [PATCH 09/10] docs(core): Toast keeps its documented type default and native maps the renamed Selector option type - Native's Selector additions map the exported SelectorOptionType doc name to the native SelectorOption type, so the native contract and Swift output stay as they were. - Toast's type keeps its 'info' default and the playground no longer sets type, so the theme editor's toast lines stay as they were. The type required_mismatch drift entry returns. --- .changeset/docs-name-exported-types.md | 2 +- packages/cli/test/core-prop-docs.known-drift.json | 1 + packages/core/src/Toast/Toast.doc.mjs | 5 ++--- packages/native/src/components/Selector.ts | 2 +- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/.changeset/docs-name-exported-types.md b/.changeset/docs-name-exported-types.md index 5389389493748..9256f047cbea6 100644 --- a/.changeset/docs-name-exported-types.md +++ b/.changeset/docs-name-exported-types.md @@ -2,6 +2,6 @@ '@astryxdesign/core': patch --- -[docs] Four docs name prop types the package exports. Selector's `options` are `SelectorOptionType[]` (`SelectorOption` is a component), SyntaxTheme's `theme` is a `SyntaxThemeDefinition`, and `useImperativeDialog` and `useImperativeAlertDialog` write their `show()` options with the exported Dialog and AlertDialog props. Toast's doc describes the card: `type`, `isAutoHide` and `autoHideDuration` are required there, and the show-only options (`uniqueID`, `collisionBehavior`, `onHide`) leave its props table, because `useToast`'s doc lists them with their defaults. +[docs] Four docs name prop types the package exports. Selector's `options` are `SelectorOptionType[]` (`SelectorOption` is a component), SyntaxTheme's `theme` is a `SyntaxThemeDefinition`, and `useImperativeDialog` and `useImperativeAlertDialog` write their `show()` options with the exported Dialog and AlertDialog props. Toast's doc describes the card: `isAutoHide` and `autoHideDuration` are required there, and the show-only options (`uniqueID`, `collisionBehavior`, `onHide`) leave its props table, because `useToast`'s doc lists them with their defaults. @cixzhang diff --git a/packages/cli/test/core-prop-docs.known-drift.json b/packages/cli/test/core-prop-docs.known-drift.json index 56c31be0377cd..3a893f56b04b2 100644 --- a/packages/cli/test/core-prop-docs.known-drift.json +++ b/packages/cli/test/core-prop-docs.known-drift.json @@ -41,6 +41,7 @@ "src/TimeInput/TimeInput.doc.mjs TimeInput.controlClassName not_in_doc", "src/TimeInput/TimeInput.doc.mjs TimeInput.controlStyle not_in_doc", "src/TimeInput/TimeInput.doc.mjs TimeInput.hasAutoFocus not_in_doc", + "src/Toast/Toast.doc.mjs Toast.type required_mismatch", "src/Tokenizer/Tokenizer.doc.mjs Tokenizer.onKeyDown not_in_doc", "src/Tooltip/Tooltip.doc.mjs Tooltip.content required_mismatch", "src/TopNav/TopNavHeading.doc.mjs TopNavHeading.logoLabel not_in_doc", diff --git a/packages/core/src/Toast/Toast.doc.mjs b/packages/core/src/Toast/Toast.doc.mjs index 7c848598df00b..3bb8b80420fb1 100644 --- a/packages/core/src/Toast/Toast.doc.mjs +++ b/packages/core/src/Toast/Toast.doc.mjs @@ -20,10 +20,9 @@ export const docs = { playground: { // The values useToast()'s show function sets, so the playground's toast - // starts as a shown info toast does. + // starts as a shown info toast does. `type` keeps its documented default. defaults: { body: 'Changes saved', - type: 'info', isAutoHide: true, autoHideDuration: 5000, }, @@ -44,7 +43,7 @@ export const docs = { type: "'info' | 'error'", description: "Toast type controlling background color. useToast()'s show function sets 'info' when it is not given.", - required: true, + default: "'info'", }, { name: 'isAutoHide', diff --git a/packages/native/src/components/Selector.ts b/packages/native/src/components/Selector.ts index e2b3cbc638d28..7b8227e94153e 100644 --- a/packages/native/src/components/Selector.ts +++ b/packages/native/src/components/Selector.ts @@ -13,7 +13,7 @@ import type {NativeAdditions} from '../contract/fromComponentDoc.js'; export const selector: NativeAdditions = { name: 'Selector', baseTarget: 'trigger', - typeNames: {SelectorOption: 'SelectorOption'}, + typeNames: {SelectorOptionType: 'SelectorOption'}, types: { // The portable part of core's option data. Its rich description, icon, // and secondary control are web-only until typed slots exist. From f8552e917114e247d98452fcf296142db24bbe7c Mon Sep 17 00:00:00 2001 From: cixzhang Date: Fri, 20 Nov 2026 05:44:38 -0800 Subject: [PATCH 10/10] refactor(docsite): Show code names a syntax preset with the one identifier helper - syntaxThemeChoices gives the preset's name; Show code turns it into the identifier with toIdentifierName, as it does for theme names. - The changeset says only what changes for Toast: isAutoHide and autoHideDuration are required; type keeps its 'info' default. --- .changeset/docs-name-exported-types.md | 2 +- .../src/__tests__/syntax-theme-control.test.ts | 10 +++++----- .../component-detail/InteractivePreview.tsx | 6 +++--- .../component-detail/syntaxThemeChoices.ts | 16 +++++----------- 4 files changed, 14 insertions(+), 20 deletions(-) diff --git a/.changeset/docs-name-exported-types.md b/.changeset/docs-name-exported-types.md index 9256f047cbea6..0fa764afacccf 100644 --- a/.changeset/docs-name-exported-types.md +++ b/.changeset/docs-name-exported-types.md @@ -2,6 +2,6 @@ '@astryxdesign/core': patch --- -[docs] Four docs name prop types the package exports. Selector's `options` are `SelectorOptionType[]` (`SelectorOption` is a component), SyntaxTheme's `theme` is a `SyntaxThemeDefinition`, and `useImperativeDialog` and `useImperativeAlertDialog` write their `show()` options with the exported Dialog and AlertDialog props. Toast's doc describes the card: `isAutoHide` and `autoHideDuration` are required there, and the show-only options (`uniqueID`, `collisionBehavior`, `onHide`) leave its props table, because `useToast`'s doc lists them with their defaults. +[docs] Four docs name prop types the package exports. Selector's `options` are `SelectorOptionType[]` (`SelectorOption` is a component), SyntaxTheme's `theme` is a `SyntaxThemeDefinition`, and `useImperativeDialog` and `useImperativeAlertDialog` write their `show()` options with the exported Dialog and AlertDialog props. Toast's doc marks the card's `isAutoHide` and `autoHideDuration` required, as `ToastProps` declares, and the show-only options (`uniqueID`, `collisionBehavior`, `onHide`) leave its props table, because `useToast`'s doc lists them with their defaults; `type` keeps its documented `'info'` default. @cixzhang diff --git a/apps/docsite/src/__tests__/syntax-theme-control.test.ts b/apps/docsite/src/__tests__/syntax-theme-control.test.ts index 332053158901a..d07475fe0b898 100644 --- a/apps/docsite/src/__tests__/syntax-theme-control.test.ts +++ b/apps/docsite/src/__tests__/syntax-theme-control.test.ts @@ -6,7 +6,7 @@ import { NO_SYNTAX_THEME, selectedSyntaxTheme, syntaxThemeChoices, - syntaxPresetIdentifier, + syntaxPresetName, syntaxThemeFor, } from '../components/component-detail/syntaxThemeChoices'; @@ -30,13 +30,13 @@ describe('the playground syntax theme control', () => { expect(syntaxThemeFor(preset.name)).toBe(preset); }); - it('names a preset by its exported identifier in code', () => { + it('names the preset a value is', () => { const dracula = allSyntaxPresets.find(theme => theme.name === 'dracula'); const oneDarkPro = allSyntaxPresets.find( theme => theme.name === 'one-dark-pro', ); - expect(syntaxPresetIdentifier(dracula)).toBe('dracula'); - expect(syntaxPresetIdentifier(oneDarkPro)).toBe('oneDarkPro'); - expect(syntaxPresetIdentifier({name: 'dracula'})).toBeNull(); + expect(syntaxPresetName(dracula)).toBe('dracula'); + expect(syntaxPresetName(oneDarkPro)).toBe('one-dark-pro'); + expect(syntaxPresetName({name: 'dracula'})).toBeNull(); }); }); diff --git a/apps/docsite/src/components/component-detail/InteractivePreview.tsx b/apps/docsite/src/components/component-detail/InteractivePreview.tsx index 7d2aaf8e30843..0a1c1c2c2a011 100644 --- a/apps/docsite/src/components/component-detail/InteractivePreview.tsx +++ b/apps/docsite/src/components/component-detail/InteractivePreview.tsx @@ -14,7 +14,7 @@ import { } from 'react'; import * as stylex from '@stylexjs/stylex'; import {getComponent, resolveValue} from './resolveElements'; -import {syntaxPresetIdentifier} from './syntaxThemeChoices'; +import {syntaxPresetName} from './syntaxThemeChoices'; import {AppShellMobileContext} from '@astryxdesign/core/AppShell'; import {Button} from '@astryxdesign/core/Button'; import {Card} from '@astryxdesign/core/Card'; @@ -123,9 +123,9 @@ function formatValue( if (value === null) { return 'null'; } - const syntaxPreset = syntaxPresetIdentifier(value); + const syntaxPreset = syntaxPresetName(value); if (syntaxPreset != null) { - return syntaxPreset; + return toIdentifierName(syntaxPreset); } if ( value != null && diff --git a/apps/docsite/src/components/component-detail/syntaxThemeChoices.ts b/apps/docsite/src/components/component-detail/syntaxThemeChoices.ts index 3ae0044cc3591..50e49d2b16268 100644 --- a/apps/docsite/src/components/component-detail/syntaxThemeChoices.ts +++ b/apps/docsite/src/components/component-detail/syntaxThemeChoices.ts @@ -4,7 +4,7 @@ * @file syntaxThemeChoices.ts * @input The value of a syntax-theme prop and whether the prop is required * @output The preset choices the playground offers, the selected choice, the - * value a choice sends, and the identifier that names a preset in code + * value a choice sends, and the name of the preset a value is * @position Logic of the playground's syntax-theme control * (PlaygroundPropsTable) */ @@ -56,17 +56,11 @@ export function selectedSyntaxTheme( } /** - * The identifier a preset is exported as, such as `oneDarkPro` for - * "one-dark-pro"; null when `value` is not a preset. + * The name of the preset `value` is, such as "one-dark-pro"; null when + * `value` is not a preset. */ -export function syntaxPresetIdentifier(value: unknown): string | null { - const match = presets.find(option => option.theme === value); - if (!match) { - return null; - } - return match.value.replace(/-([a-z0-9])/g, (_, next: string) => - next.toUpperCase(), - ); +export function syntaxPresetName(value: unknown): string | null { + return presets.find(option => option.theme === value)?.value ?? null; } /** The value a choice sends: a preset, or nothing for the unset choice. */