Skip to content
Draft
Show file tree
Hide file tree
Changes from 2 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] 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`).
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
6 changes: 3 additions & 3 deletions packages/core/src/Markdown/Markdown.doc.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -143,7 +143,7 @@ export const docs = {
},
{
name: 'plugins',
type: 'readonly MarkdownPluginEntry[]',
type: 'readonly ReturnType<typeof createMarkdownPlugin>[]',
Comment thread
astracat-bot[bot] marked this conversation as resolved.
Resolved
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.',
},
Expand Down Expand Up @@ -687,7 +687,7 @@ export const docsZh = {
},
{
name: 'plugins',
type: 'readonly MarkdownPluginEntry[]',
type: 'readonly ReturnType<typeof createMarkdownPlugin>[]',
description:
'由 createMarkdownPlugin() 创建的有序扩展。插件可添加有界语法、不可变的类型化 AST 转换和类型化扩展渲染器。使用 isMarkdownExtensionNode() 缩小从其他插件观察到的扩展数据类型。渲染回调必须是纯函数;需要 Hook 时请返回子组件。省略或传入空列表时保持已发布的 Markdown 行为。',
},
Expand Down Expand Up @@ -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<typeof createMarkdownPlugin>[]. 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:
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
41 changes: 10 additions & 31 deletions packages/core/src/Toast/Toast.doc.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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.",
Comment thread
astracat-bot[bot] marked this conversation as resolved.
Resolved
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.",
Comment thread
astracat-bot[bot] marked this conversation as resolved.
Resolved
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 +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',
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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'。",
},
Expand All @@ -230,7 +211,7 @@ export const docsZh = {
{
guidance: true,
description:
'使用 uniqueID 去重重复操作触发的 toast,如多次点击保存按钮。',
'传入 useToast() 的 uniqueID 选项,去重重复操作触发的 toast,如多次点击保存按钮。',
},
{
guidance: true,
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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',
},
Expand Down
4 changes: 2 additions & 2 deletions packages/core/src/Toast/useToast.doc.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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.',
Comment thread
astracat-bot[bot] marked this conversation as resolved.
Resolved
},
],
usage: {
Expand All @@ -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.',
Expand Down
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