Skip to content
Draft
Show file tree
Hide file tree
Changes from 4 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions .changeset/docs-name-exported-types.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
'@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`).
Comment thread
astracat-bot[bot] marked this conversation as resolved.
Resolved

@cixzhang
3 changes: 2 additions & 1 deletion docs/specs/components/Toast/Toast.spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
6 changes: 0 additions & 6 deletions packages/cli/test/core-prop-docs.known-drift.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
11 changes: 7 additions & 4 deletions packages/core/src/AlertDialog/useImperativeAlertDialog.doc.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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<AlertDialogProps, 'isOpen' | 'onOpenChange'>) => void",
description:
'Show the alert dialog with the given options. Options are the same as AlertDialog props minus isOpen/onOpenChange.',
},
{
name: 'hide',
Expand All @@ -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',
Expand Down
11 changes: 7 additions & 4 deletions packages/core/src/Dialog/useImperativeDialog.doc.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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<DialogProps, 'isOpen' | 'onOpenChange' | 'children'>) => void",
description:
'Show the dialog with the given content. Options are the same as Dialog props minus isOpen/onOpenChange/children.',
},
{
name: 'hide',
Expand All @@ -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',
Expand Down
2 changes: 1 addition & 1 deletion packages/core/src/Selector/Selector.doc.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
64 changes: 26 additions & 38 deletions packages/core/src/Toast/Toast.doc.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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: [
Expand All @@ -36,21 +43,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. 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, so an error toast it shows persists until dismissed.",
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,
Comment thread
astracat-bot[bot] marked this conversation as resolved.
Resolved
},
{
name: 'endContent',
Expand All @@ -62,23 +70,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',
Expand Down Expand Up @@ -146,7 +137,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,
Expand Down Expand Up @@ -202,14 +193,12 @@ 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: '尾部渲染的内容(如撤销按钮、链接)。操作标签应保持简短。',
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'。",
},
Expand All @@ -230,7 +219,7 @@ export const docsZh = {
{
guidance: true,
description:
'使用 uniqueID 去重重复操作触发的 toast,如多次点击保存按钮。',
'传入 useToast() 的 uniqueID 选项,去重重复操作触发的 toast,如多次点击保存按钮。',
},
{
guidance: true,
Expand Down Expand Up @@ -293,7 +282,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,
Expand All @@ -319,15 +309,13 @@ 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',
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',
},
Expand Down
73 changes: 59 additions & 14 deletions packages/core/src/Toast/useToast.doc.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -5,24 +5,50 @@ 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
],
returns: [
{
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: {
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'],
Expand All @@ -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), 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.',
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.',
},
],
},
};
2 changes: 1 addition & 1 deletion packages/core/src/theme/SyntaxTheme.doc.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@ export const docs = {
props: [
{
name: 'theme',
type: 'SyntaxTheme',
type: 'SyntaxThemeDefinition',
Comment thread
astracat-bot[bot] marked this conversation as resolved.
Resolved
required: true,
description:
'Syntax highlighting theme: a preset from @astryxdesign/core/theme/syntax or a custom theme created with defineSyntaxTheme().',
Expand Down