Skip to content

docs(core): prop types name only types the package exports; Toast's doc marks the card's timing props required - #12337

Draft
cixzhang wants to merge 12 commits into
mainfrom
lane4/docs-name-exported-types
Draft

cixzhang wants to merge 12 commits into
mainfrom
lane4/docs-name-exported-types

Conversation

@cixzhang

@cixzhang cixzhang commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Four component and hook docs name a prop type the package does not export, so an agent that reads astryx component <Name> --props and tries to import that type, or looks it up, finds nothing. Toast's doc also lists isAutoHide and autoHideDuration as optional with defaults, while the Toast card's exported ToastProps requires them. An app that renders <Toast> from that table does not type-check. This PR makes those docs name types @astryxdesign/core exports, and marks Toast's isAutoHide and autoHideDuration required, as ToastProps declares; type keeps its documented 'info' default.

What changes for you

  • Selector: options is SelectorOptionType[]. SelectorOption is a component, not the item type.
  • SyntaxTheme: theme is a SyntaxThemeDefinition. The docsite playground picks its theme preset control by the type name, so it now matches SyntaxThemeDefinition, and CodeBlock's and Lab DiffViewer's syntaxTheme rows, typed the same way, get the picker too. For an optional prop the picker starts at None and None sends nothing, so an unset prop keeps the theme-level syntax colors. Show code names a picked preset by its exported identifier, such as syntaxTheme={dracula}, not the whole preset object. component-prop-controls.test.ts and syntax-theme-control.test.ts cover these; they fail without the change. Show code prints a picked preset by its exported name (dracula, oneDarkPro) through the same identifier helper it uses for theme names.
  • useImperativeAlertDialog: show is (options: Omit<AlertDialogProps, 'isOpen' | 'onOpenChange'>) => void.
  • useImperativeDialog: show is (content: ReactNode, options?: Omit<DialogProps, 'isOpen' | 'onOpenChange' | 'children'>) => void. Both dialog shapes are the ones the hooks declare, written with exported types.
  • Toast: isAutoHide and autoHideDuration are required, as ToastProps declares, and each says, in English, Chinese and the dense text, what useToast()'s show function sets when it is not given. That an error toast persists until dismissed is show's default for isAutoHide, so that sentence moves from type to isAutoHide. type keeps its documented 'info' default (variant A below). The show-only options (uniqueID, collisionBehavior, onHide) and their defaults move to useToast's doc. The best practice about uniqueID names useToast().
  • Record: docs/specs/components/Toast/Toast.spec.md says consumer usage lives in Toast.doc.mjs (the card) and useToast.doc.mjs (the show function).
  • Drift list: five of the six Toast entries in packages/cli/test/core-prop-docs.known-drift.json are gone, as the drift test asks once the doc matches the code. Toast.type required_mismatch stays, because type keeps its default.
  • Native: packages/native/src/components/Selector.ts maps the renamed doc type SelectorOptionType to the native SelectorOption, the one key the rename reaches. The native contract and Swift output are unchanged.

No type is exported or changed; only docs, one record sentence and native's doc-name mapping change.

Why type keeps its default (variant A): the theme editor renders each component with its playground defaults and reads a visual prop's documented default. With type required, or set in the playground, it splits the toast by type and prints --when type:info on its toast lines, which changes what theme suggests. So type keeps default: "'info'", the playground sets only body, isAutoHide and autoHideDuration, and the editor's output stays as it was. Documenting type as required with the playground fix alone (variant B) still changed the editor's output, so it is not used.

Writing rubric results

  • R1 narration: none; the amended sentence states where consumer usage lives.
  • R2 research in the record: none.
  • R3 evidence naming a change: none.
  • R4 rejected alternatives over one line or outside a decision: none.
  • R5 pull request or issue references remaining: none (searched # + digits, /pull/, /issues/).
  • R6 ruled open questions still listing options: none.
  • R7 consistency: the sentence matches the record's Public contract, which gives the defaults and the show-only options to useToast()'s show function and lists Toast (the card) as its own export.

Testing

  • packages/native/src/contract tests pass: the committed Swift binding stays in sync and Selector's portable props keep options.
  • The theme editor's toast tests pass with no output change: theme-auto-media, theme-contrast-check-measures-draws, theme-missed-step-lines and theme-pictures-overlays-drawn-open.
  • The docsite component-prop-controls and syntax-theme-control tests pass (16/16).
  • packages/cli/test/core-prop-docs.test.mjs passes. Core's docs now match Core's props for Toast, and the known-drift list holds nothing fixed.
  • packages/cli/foundation/discovery/doc-types.test.mjs passes. Each changed doc still satisfies its authoring type.
  • pnpm check:knowledge and pnpm check:changesets pass. prettier --check passes on the lines this PR changes (Selector.doc.mjs has one unformatted line from main, outside this change).

Not in this PR: useCombobox and useMultiCombobox document UseComboboxOptions and UseMultiComboboxOptions, which no entry point exports. They are tracked with the same defect. MarkdownPluginEntry, which Markdown's doc names, is exported from @astryxdesign/core/Markdown/plugins, so that doc stays.

Overlap checked: #6819, #12156, #11960, #11517, #11966, #8121, #11544, #11540, #11536, #11530, #11525, #11518, #11508, #11478, #11476, #11466, #11463, #11868, #11621, #12378, #12450 (#6819, #12378 and #12450 share a file and merge cleanly with this change in it; #11868, #11517, #11966 and the rest already conflict with main in the files they share; #12156, #11960 and #11621 are closed)

Owner: fix-loop lane 4. Land path: Specs consistency stamp, CodeBunny, CI, then the drain merges.

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.
…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.
@vercel

vercel Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
astryx Ready Ready Preview Nov 20, 2026 1:55pm UTC

Request Review

@meta-cla meta-cla Bot added the CLA Signed This label is managed by the Meta Open Source bot. label Nov 17, 2026
@astracat-bot

astracat-bot Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

AI review status for this pull request.

Review status Updated
🟡 Reviewed (for maintainers only) Nov 20, 2026, 2:08 PM UTC

@cixzhang cixzhang added the lane:4 Astryx fix-loop lane 4 owns this label Nov 17, 2026
@github-actions github-actions Bot added the needs:spec-owner-review Current knowledge records await owner approval label Nov 17, 2026
@cixzhang

Copy link
Copy Markdown
Contributor Author

/approve-spec 03c20f5

@github-actions

github-actions Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

PR Analysis Report

Current run: The current CI run concluded skipped. Current analysis is unavailable.


Generated by PR Enrichment workflow | View current CI run

@github-actions github-actions Bot removed the needs:spec-owner-review Current knowledge records await owner approval label Nov 17, 2026

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changes requested: the English doc fixes match the code, but five text problems remain in what this pull request changes or claims.

  • The changeset says every component and hook doc now names exported types, but useCombobox and useMultiCombobox still document their options as UseComboboxOptions and UseMultiComboboxOptions, which no entry point exports, so narrow the changeset to the docs this changes or fix those two as well.
  • The description says MarkdownPluginEntry is not exported, but @astryxdesign/core/Markdown/plugins exports it beside createMarkdownPlugin and ReturnType<typeof createMarkdownPlugin> is the same type, so keep readonly MarkdownPluginEntry[], or state the root-entry reason and give useOutlineFromMarkdown's doc the same spelling.
  • Toast's type still says error toasts persist until dismissed, but the card's timer reads only isAutoHide, so move that sentence to isAutoHide as what useToast()'s show function does, in the English, zh and dense text.
  • Toast's zh and dense isAutoHide text still gives card defaults for a prop that is now required, so carry the new English sentence into both translations.
  • packages/core/src/Toast/useToast.doc.mjs fails prettier --check, so the description's "Prettier passes on the changed files" is not yet true; run prettier --write on it.

The other retyped docs, the required flags, the drift-list deletions and the record sentence check out against the code.

Claims and files checked

Review mode: full; reason: no-earlier-review

Claims:

  • Selector's options is the exported item type: verified (Selector/index.ts:19, Selector.tsx:1177).
  • SyntaxTheme's theme is the exported definition type: verified (theme/syntax/SyntaxTheme.tsx:156).
  • Markdown's old plugin type is not exported: false (Markdown/plugins/index.ts:59).
  • The alert dialog hook's show options use the exported props: verified (useImperativeAlertDialog.tsx:20).
  • The dialog hook's show options use the exported props: verified (useImperativeDialog.tsx:26-29).
  • Toast's doc describes the card, with three props required: verified for the English flags (Toast.tsx:152-156); partly false for type and the zh and dense isAutoHide text.
  • The show-only options and their defaults move to useToast's doc: verified (useToast.doc.mjs:16, ToastViewport.tsx:296-298, Layer/toastHost.tsx:64).
  • The uniqueID best practice names useToast(): verified (Toast.doc.mjs:133).
  • The Toast record names both consumer docs: verified (Toast.spec.md:73-74).
  • The six Toast drift entries are gone and the drift test requires it: verified (core-prop-docs.test.mjs passes).
  • No type is exported or changed: verified (API surface comparison lists no row).
  • The prop-docs and doc-type tests pass: verified (run at this head).
  • The knowledge and changeset checks pass: verified (run at this head).
  • Prettier passes on the changed files: false (useToast.doc.mjs).
  • The five named types are exported from Core's root: verified (src/index.ts re-exports).
  • Changeset, component and hook docs name only exported types: false (useCombobox.doc.mjs:27, useMultiCombobox.doc.mjs:27).
  • Changeset, the per-doc details: verified, apart from the Toast type and Markdown points above.

Files:

  • .changeset/docs-name-exported-types.md: finding (over-broad claim).
  • docs/specs/components/Toast/Toast.spec.md: clear.
  • packages/cli/test/core-prop-docs.known-drift.json: clear.
  • packages/core/src/AlertDialog/useImperativeAlertDialog.doc.mjs: clear.
  • packages/core/src/Dialog/useImperativeDialog.doc.mjs: clear.
  • packages/core/src/Markdown/Markdown.doc.mjs: finding (false premise, spelling differs from Outline's doc).
  • packages/core/src/Selector/Selector.doc.mjs: clear.
  • packages/core/src/Toast/Toast.doc.mjs: findings (type persistence, zh and dense isAutoHide).
  • packages/core/src/Toast/useToast.doc.mjs: finding (not formatted).
  • packages/core/src/theme/SyntaxTheme.doc.mjs: clear.

Automated review (maintainer link)

Comment thread .changeset/docs-name-exported-types.md Resolved
Comment thread packages/core/src/Toast/Toast.doc.mjs Resolved
Comment thread packages/core/src/Toast/Toast.doc.mjs Resolved
…w 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.
@cixzhang

Copy link
Copy Markdown
Contributor Author

/approve-spec 305b2de

@astracat-bot astracat-bot Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changes requested: the Toast, Selector and dialog hook docs match the code and the description's overlap note is now accurate, but the SyntaxTheme doc change still breaks the docsite's SyntaxTheme playground.

  • Miss: SyntaxTheme.doc.mjs now types theme as SyntaxThemeDefinition, but the docsite still picks the theme preset control by the old name (apps/docsite/src/components/component-detail/parsePropType.ts:186), so the SyntaxTheme page's playground shows "Render error: Cannot read properties of undefined (reading 'keyword')" with no theme picker; match SyntaxThemeDefinition there and add a docsite test for it.

Miss (non-blocking): the docsite's Toast playground now starts autoHideDuration at 0; adding the show function's values to the doc's playground.defaults keeps the old start (see the existing inline comment).

Claims and files checked

Review mode: same-head; reason: none

  • Claim, changeset: four docs now name exported prop types (Selector, SyntaxTheme, both imperative dialog hooks): verified against the Selector, theme and dialog entry points and the hooks' option types.
  • Claim, changeset and description: Toast's doc describes the card, with type, isAutoHide and autoHideDuration required: verified against ToastProps in Toast.tsx.
  • Claim, changeset and description: useToast's doc lists the show options and their defaults: verified against ToastOptions, the viewport's fallbacks and the toast host's collision default.
  • Claim, description: each required Toast prop says in English, Chinese and dense text what the show function sets, and error persistence moved to isAutoHide: verified in all three.
  • Claim, description: the uniqueID best practice names useToast(): verified in all three.
  • Claim, description: the Toast record names both consumer docs, consistent with its public contract: verified.
  • Claim, description: the six Toast drift entries are gone and the drift test requires it: verified, the test passes.
  • Claim, description: no type is exported or changed, and only docs and one record sentence change: verified (besides the changeset and the drift list).
  • Claim, description: the writing-rubric results for the record sentence: verified.
  • Claim, description: the prop-drift and descriptor-type tests, check:knowledge, check:changesets and Prettier pass: verified by rerunning them.
  • Claim, description: the combobox hooks' option types are not exported, and MarkdownPluginEntry is exported from the Markdown plugins entry: verified.
  • Claim, description: the exported-type resolver from #12326 finds the five named types at Core's root: verified, all five are re-exported from Core's root through the export chains that resolver follows.
  • Claim, description: the overlap note: verified for all nineteen pull requests it names.
  • File .changeset/docs-name-exported-types.md: clear.
  • File docs/specs/components/Toast/Toast.spec.md: clear.
  • File packages/cli/test/core-prop-docs.known-drift.json: clear.
  • File packages/core/src/AlertDialog/useImperativeAlertDialog.doc.mjs: clear.
  • File packages/core/src/Dialog/useImperativeDialog.doc.mjs: clear.
  • File packages/core/src/Selector/Selector.doc.mjs: clear.
  • File packages/core/src/Toast/Toast.doc.mjs: one non-blocking note (docsite playground seeding).
  • File packages/core/src/Toast/useToast.doc.mjs: clear.
  • File packages/core/src/theme/SyntaxTheme.doc.mjs: one blocking finding (docsite playground).

Automated review (maintainer link)

Comment thread packages/core/src/Toast/Toast.doc.mjs Resolved
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.
@cixzhang

Copy link
Copy Markdown
Contributor Author

/approve-spec b0a864e

@astracat-bot astracat-bot Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changes requested: the Toast, Selector and dialog hook docs now match the code, but the SyntaxTheme doc change breaks the docsite's SyntaxTheme playground, and one description claim is out of date.

  • Miss: SyntaxTheme.doc.mjs now types theme as SyntaxThemeDefinition, but the docsite still picks the theme preset control by the old name (apps/docsite/src/components/component-detail/parsePropType.ts:186), so the SyntaxTheme page's playground shows "Render error: Cannot read properties of undefined (reading 'keyword')" with no theme picker; match SyntaxThemeDefinition there and add a case to apps/docsite/src/__tests__/component-prop-controls.test.ts.
  • Regression: the description's overlap note lists #11517 among the pull requests that already conflict with main, but #11517 now merges cleanly with main and with this change, so move it to the group that shares a file and merges cleanly.
Claims and files checked

Review mode: same-head; reason: none

  • Rules changed since the last review: 0.
  • Claim, changeset: the Selector, SyntaxTheme and both imperative dialog hook docs name exported types: verified (SelectorOptionType, SyntaxThemeDefinition, DialogProps and AlertDialogProps are Core root exports, and the show shapes match useImperativeDialog.tsx:26-33 and useImperativeAlertDialog.tsx:20-24).
  • Claim, changeset and description: Toast's doc describes the card, with type, isAutoHide and autoHideDuration required: verified against ToastProps (Toast.tsx:151-158).
  • Claim, changeset and description: useToast's doc lists the show options and their defaults: verified against ToastViewport.tsx:296-298, Layer/toastHost.tsx:64 and Toast/types.ts:53-63.
  • Claim, description: four docs named a type Core does not export, and a <Toast> written from the old table did not type-check: verified on the base.
  • Claim, description: each required Toast prop says in English, Chinese and dense text what the show function sets, and the error-persistence sentence moved to isAutoHide: verified in all three.
  • Claim, description: the uniqueID best practice names useToast(): verified in all three.
  • Claim, description: the Toast record names both consumer docs, consistent with its public contract: verified.
  • Claim, description: the six Toast drift entries are gone and the drift test requires it: verified, the drift test passes at this head.
  • Claim, description: no type is exported or changed, and only docs and one record sentence change: verified (besides the changeset and the drift list); Core's built API surface compares with no change.
  • Claim, description: the writing-rubric results for the record sentence: verified.
  • Claim, description: the prop-drift and descriptor-type tests, check:knowledge, check:changesets and Prettier pass: verified at this head.
  • Claim, description: the combobox hooks' option types are not exported, and MarkdownPluginEntry is exported from the Markdown plugins entry: verified (Selector/hooks.ts:358, MultiSelector/hooks.ts:24, Markdown/plugins/index.ts:59).
  • Claim, description: the five named types resolve at Core's root: verified.
  • Claim, description: the overlap note: verified for eighteen of the nineteen pull requests; false for #11517 (finding above).
  • File .changeset/docs-name-exported-types.md: clear.
  • File docs/specs/components/Toast/Toast.spec.md: clear.
  • File packages/cli/test/core-prop-docs.known-drift.json: clear.
  • File packages/core/src/AlertDialog/useImperativeAlertDialog.doc.mjs: clear.
  • File packages/core/src/Dialog/useImperativeDialog.doc.mjs: clear.
  • File packages/core/src/Selector/Selector.doc.mjs: clear.
  • File packages/core/src/Toast/Toast.doc.mjs: clear.
  • File packages/core/src/Toast/useToast.doc.mjs: clear.
  • File packages/core/src/theme/SyntaxTheme.doc.mjs: one blocking finding (docsite playground).

Automated review (maintainer link)

…set 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.
@cixzhang

Copy link
Copy Markdown
Contributor Author

/approve-spec 503c1bc

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changes requested: the SyntaxTheme playground has its preset picker again, but the same docsite change gives CodeBlock's props table a picker that misstates an unset prop, and one description claim is out of date.

  • The docsite now gives CodeBlock's and Lab DiffViewer's optional syntaxTheme rows the syntax theme picker (apps/docsite/src/components/component-detail/parsePropType.ts:186), which reads "One Dark Pro" while the prop is unset and the preview keeps the theme-level syntax colours, with no way back to unset; give an optional row an unset choice that sends undefined, as the enum control's "None" does, and add a test for it.
  • Regression: the description's overlap note lists #11966 among the pull requests that already conflict with main, but since #11966 merged main it merges cleanly with main and with this change, so move it to the group that shares a file and merges cleanly.
Claims and files checked

Review mode: incremental; reason: none

  • changed rules (0): none.
  • Claim, changeset: the Selector, SyntaxTheme and both imperative dialog hook docs name exported types: verified (Core's root exports SelectorOptionType, SyntaxThemeDefinition, DialogProps and AlertDialogProps, and the show shapes match the hooks' declarations).
  • Claim, changeset and description: Toast's doc describes the card, with type, isAutoHide and autoHideDuration required: verified against ToastProps (Toast.tsx:151-158).
  • Claim, changeset and description: useToast's doc lists the show options and their defaults: verified against ToastViewport.tsx:296-298 and Layer/toastHost.tsx:64.
  • Claim, description: four docs named a type Core does not export, and a <Toast> written from the old table did not type-check: verified on the base.
  • Claim, description: the docsite picks the SyntaxTheme preset control by type name and now matches SyntaxThemeDefinition, and the new test fails without the change: verified (the test fails on the base and passes on this head).
  • Claim, description: CodeBlock's syntaxTheme row gets the picker too: true, but the picker misstates an unset value (finding above).
  • Claim, description: each required Toast prop says in English, Chinese and dense text what the show function sets; the error-persistence sentence moved to isAutoHide; the show-only options moved to useToast's doc; the uniqueID best practice names useToast(): verified.
  • Claim, description: the Toast record names both consumer docs, consistent with its public contract: verified.
  • Claim, description: the six Toast drift entries are gone and the drift test requires it: verified, the drift test passes.
  • Claim, description: no type is exported or changed: verified, Core's built API surface has no change.
  • Claim, description: the writing-rubric results for the record sentence: verified.
  • Claim, description: the prop-drift and descriptor-type tests, check:knowledge, check:changesets and Prettier pass: verified at this head.
  • Claim, description: the combobox hooks' option types are not exported, and MarkdownPluginEntry is exported from the Markdown plugins entry: verified.
  • Claim, description: the five named types resolve at Core's root: verified.
  • Claim, description: the overlap note: verified for eighteen of the nineteen pull requests; false for #11966 (finding above).
  • File .changeset/docs-name-exported-types.md: clear.
  • File apps/docsite/src/__tests__/component-prop-controls.test.ts: clear.
  • File apps/docsite/src/components/component-detail/parsePropType.ts: one blocking finding (optional-row picker).
  • File docs/specs/components/Toast/Toast.spec.md: clear.
  • File packages/cli/test/core-prop-docs.known-drift.json: clear.
  • File packages/core/src/AlertDialog/useImperativeAlertDialog.doc.mjs: clear.
  • File packages/core/src/Dialog/useImperativeDialog.doc.mjs: clear.
  • File packages/core/src/Selector/Selector.doc.mjs: clear.
  • File packages/core/src/Toast/Toast.doc.mjs: clear.
  • File packages/core/src/Toast/useToast.doc.mjs: clear.
  • File packages/core/src/theme/SyntaxTheme.doc.mjs: clear.

Automated review (maintainer link)

…turn 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.
@github-actions github-actions Bot added the needs:design-review Affects visuals — Design should review label Nov 18, 2026

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changes requested: the optional syntax-theme rows on the docsite now start at None and can return to it, but a preset picked there still prints as the whole preset object in the generated code.

  • A preset picked in CodeBlock's or Lab DiffViewer's syntaxTheme row shows in Show code as syntaxTheme={{"name":"dracula","tokens":{…},"__inputTokens":{…}}} (945 characters for Dracula) instead of syntaxTheme={dracula}, because formatValue names a preset only for a prop called theme (apps/docsite/src/components/component-detail/InteractivePreview.tsx:126-132); print a syntax preset by its identifier for any syntax-theme prop, and add a test.

The Toast, Selector, SyntaxTheme and dialog hook docs match the code, the description's claims hold, and the overlap note is now accurate.

Claims and files checked

Review mode: incremental; reason: none

  • Changed rules (0): none.
  • Claim, changeset: Selector's options doc names SelectorOptionType[], and SelectorOption is a component: verified (Selector.doc.mjs:185, Selector/index.ts:19).
  • Claim, changeset: SyntaxTheme's theme doc names SyntaxThemeDefinition: verified (SyntaxTheme.doc.mjs:62, theme/index.ts:83).
  • Claim, changeset and description: the two imperative dialog hooks write show() with the exported Dialog and AlertDialog props, in the shapes the hooks declare: verified (useImperativeDialog.tsx:26-29, useImperativeAlertDialog.tsx:20).
  • Claim, changeset and description: Toast's doc marks type, isAutoHide and autoHideDuration required, as ToastProps does: verified (Toast.tsx:152-156).
  • Claim, changeset and description: useToast's doc lists the show options and their defaults, and the show-only options left the card's doc: verified (useToast.doc.mjs:25, ToastViewport.tsx:296-298, toastHost.tsx:64).
  • Claim, description: each of the three Toast props says in English, Chinese and dense text what the show function sets, the error-persists sentence sits on isAutoHide, and the uniqueID best practice names useToast(): verified (Toast.doc.mjs:43-61, :196-200, :312-316, :140, :222, :286).
  • Claim, description: the docsite matches its syntax theme picker on SyntaxThemeDefinition, and CodeBlock's and DiffViewer's rows get it too: verified (parsePropType.ts:186, CodeBlock.doc.mjs:146, DiffViewer.doc.mjs:208).
  • Claim, description: an optional row starts at None and None sends nothing, so the theme-level colours stay: verified (syntaxThemeChoices.ts:30-61; rendered row and live block).
  • Claim, description: the two docsite tests cover both and fail without the change: verified (both pass; the new one imports the module this change adds; the other fails on the base).
  • Claim, description: the record names both consumer docs, consistent with its Public contract: verified (Toast.spec.md:73-74, :58).
  • Claim, description: the six Toast drift entries are gone and the drift test requires that: verified (core-prop-docs.test.mjs passes).
  • Claim, description: no type is exported or changed, and only docs and one record sentence change: verified (no package source changes; the code changes are in the docsite).
  • Claim, description: the writing rubric results for the record sentence: verified (no narration, references or open options; matches the Public contract).
  • Claim, description: the drift, doc-type, knowledge, changeset and Prettier checks pass: verified (rerun at this head).
  • Claim, description: useCombobox and useMultiCombobox still name unexported option types, and MarkdownPluginEntry is exported from the Markdown plugins entry: verified (useCombobox.doc.mjs:27, useMultiCombobox.doc.mjs:27, Markdown/plugins/index.ts:59).
  • Claim, description: the five named types are exported at Core's root: verified (index.ts:133 and the Selector, theme, AlertDialog and Dialog barrels).
  • Claim, description: the overlap note: verified against the current main (the clean group shares a file and merges cleanly; the rest conflict with main in Toast.spec.md).
  • File apps/docsite/src/components/component-detail/syntaxThemeChoices.ts: finding (generated code above).
  • File apps/docsite/src/components/component-detail/PlaygroundPropsTable.tsx: clear.
  • File apps/docsite/src/components/component-detail/parsePropType.ts: clear.
  • File apps/docsite/src/__tests__/syntax-theme-control.test.ts: clear.
  • File apps/docsite/src/__tests__/component-prop-controls.test.ts: clear.
  • File packages/core/src/Toast/Toast.doc.mjs: clear.
  • File packages/core/src/Toast/useToast.doc.mjs: clear.
  • File docs/specs/components/Toast/Toast.spec.md: clear.
  • File packages/cli/test/core-prop-docs.known-drift.json: clear.
  • File packages/core/src/Selector/Selector.doc.mjs: clear.
  • File packages/core/src/theme/SyntaxTheme.doc.mjs: clear.
  • File packages/core/src/Dialog/useImperativeDialog.doc.mjs: clear.
  • File packages/core/src/AlertDialog/useImperativeAlertDialog.doc.mjs: clear.
  • File .changeset/docs-name-exported-types.md: clear.

Automated review (maintainer link)

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.
@cixzhang

Copy link
Copy Markdown
Contributor Author

/approve-spec db93636

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved pending CI: CI has not run on this head yet, so its checks still need to pass before merge.

Show code on the CodeBlock and DiffViewer pages now prints a picked syntax preset by its export (syntaxTheme={dracula}), which resolves the last open finding; the Toast, Selector, SyntaxTheme and dialog hook docs match the code, and the description's claims hold.

  • Non-blocking: no test reaches the new Show code branch (apps/docsite/src/components/component-detail/InteractivePreview.tsx:126-129); a case in interactive-preview.test.ts that renders CodeBlock with a preset and expects syntaxTheme={dracula} would keep it from regressing.
Claims and files checked

Review mode: incremental; reason: none

  • Changed rules (0): none.
  • Claim, changeset and description: Selector's options doc names SelectorOptionType[], and SelectorOption is a component: verified (Selector.doc.mjs:185, Selector/index.ts:17-19).
  • Claim, changeset and description: SyntaxTheme's theme doc names SyntaxThemeDefinition: verified (SyntaxTheme.doc.mjs:62, theme/index.ts:83).
  • Claim, changeset and description: the two imperative dialog hooks write show() with the exported Dialog and AlertDialog props, in the shapes the hooks declare: verified (useImperativeDialog.tsx:26-29, useImperativeAlertDialog.tsx:20).
  • Claim, changeset and description: Toast's doc marks type, isAutoHide and autoHideDuration required, as ToastProps does: verified (Toast.tsx:152-156, Toast.doc.mjs:43-61).
  • Claim, changeset and description: useToast's doc lists the show options and their defaults, and the show-only options left the card's doc: verified (useToast.doc.mjs:22-25, ToastViewport.tsx:296-298, toastHost.tsx:64).
  • Claim, description: each of the three Toast props says in English, Chinese and dense text what the show function sets, the error-persists sentence sits on isAutoHide, and the uniqueID best practice names useToast(): verified (Toast.doc.mjs:43-61, :196-200, :311-315, :140, :222, :286).
  • Claim, description: the docsite picks its syntax theme picker by SyntaxThemeDefinition, and CodeBlock's and DiffViewer's rows get it too: verified (parsePropType.ts:186, CodeBlock.doc.mjs:146, DiffViewer.doc.mjs:208).
  • Claim, description: an optional row starts at None and None sends nothing, so the theme-level colours stay: verified (syntaxThemeChoices.ts:30-56, :73-74).
  • Claim, description: Show code names a picked preset by its export, such as syntaxTheme={dracula}: verified (InteractivePreview.tsx:126-129, syntaxThemeChoices.ts:62-70; all 12 presets in a render of the preview).
  • Claim, description: the two docsite tests cover these and fail without the change: verified (both pass; the new one imports a module this change adds; the other fails on the base); the Show code wiring itself has no test (note above).
  • Claim, description: the record names both consumer docs, consistent with its Public contract: verified (Toast.spec.md:73-74, :58).
  • Claim, description: the six Toast drift entries are gone and the drift test requires that: verified (core-prop-docs.test.mjs passes).
  • Claim, description: no type is exported or changed, and only docs and one record sentence change: verified (no package source changes and no public API rows; the code changes are the docsite's, which the description lists).
  • Claim, description: the writing rubric results for the record sentence: verified (no narration, references or open options; matches the Public contract).
  • Claim, description: the drift, doc-type, knowledge, changeset and Prettier checks pass: verified (rerun at this head).
  • Claim, description: useCombobox and useMultiCombobox still name unexported option types, and MarkdownPluginEntry is exported from the Markdown plugins entry: verified (useCombobox.doc.mjs:27, useMultiCombobox.doc.mjs:27, Markdown/plugins/index.ts:59).
  • Claim, description: the five named types are exported at Core's root: verified (index.ts:70, :95-96, :133, :215).
  • Claim, description: the overlap note: verified against the current main (the clean group shares a file and merges cleanly with this change; the rest conflict with main in Toast.spec.md).
  • File apps/docsite/src/components/component-detail/InteractivePreview.tsx: note (untested branch above).
  • File apps/docsite/src/components/component-detail/syntaxThemeChoices.ts: clear.
  • File apps/docsite/src/components/component-detail/PlaygroundPropsTable.tsx: clear.
  • File apps/docsite/src/components/component-detail/parsePropType.ts: clear.
  • File apps/docsite/src/__tests__/syntax-theme-control.test.ts: clear.
  • File apps/docsite/src/__tests__/component-prop-controls.test.ts: clear.
  • File packages/core/src/Toast/Toast.doc.mjs: clear.
  • File packages/core/src/Toast/useToast.doc.mjs: clear.
  • File docs/specs/components/Toast/Toast.spec.md: clear.
  • File packages/cli/test/core-prop-docs.known-drift.json: clear.
  • File packages/core/src/Selector/Selector.doc.mjs: clear.
  • File packages/core/src/theme/SyntaxTheme.doc.mjs: clear.
  • File packages/core/src/Dialog/useImperativeDialog.doc.mjs: clear.
  • File packages/core/src/AlertDialog/useImperativeAlertDialog.doc.mjs: clear.
  • File .changeset/docs-name-exported-types.md: clear.

Automated review (maintainer link)

main's useToast doc (#12344) now names the ToastOptions type and every
option, which covers this branch's useToast.doc edit, so the file takes
main's text.
@cixzhang

Copy link
Copy Markdown
Contributor Author

/approve-spec e015cee

@github-actions github-actions Bot added needs:spec-owner-review Current knowledge records await owner approval and removed needs:spec-owner-review Current knowledge records await owner approval labels Nov 18, 2026

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changes requested: the doc and docsite changes check out, but three statements in the changeset and description went stale when main was merged in.

  • Regression: the changeset's last clause says useToast's doc lists the show options and their defaults, but after the merge of main this pull request no longer edits useToast.doc.mjs (#12344 already lists them, with its own release note), so reword it to say the show-only options leave Toast's table because useToast's doc lists them.
  • Regression: the description's overlap note says #11517 and #11966 merge cleanly with this change, but at this head both conflict with it, and with main, in docs/specs/components/Toast/Toast.spec.md, so move them to the "already conflict with main" list.
  • Regression: the Testing claim that prettier --check passes on the changed files is false at this head, because line 351 of packages/core/src/Selector/Selector.doc.mjs, which arrived from main, is not formatted, so run prettier --write on that file or narrow the claim.

Non-blocking: no test exercises Show code's preset naming in InteractivePreview.tsx; a CodeBlock case that picks a preset and expects syntaxTheme={dracula} would hold it.

Claims and files checked

Review mode: full; reason: merge-touches-pr-files

Claims:

  • Changeset: four docs name types the package exports (Selector options, SyntaxTheme theme, both imperative dialog hooks): verified, each is a root export and the exported-type resolver from #12326 finds all of them.
  • Changeset: Toast's doc marks type, isAutoHide and autoHideDuration required: verified against ToastProps in Toast.tsx.
  • Changeset: useToast's doc lists the show options and their defaults: false as a change of this pull request, since this diff does not touch useToast.doc.mjs.
  • Selector's options are SelectorOptionType[] and SelectorOption is a component: verified.
  • SyntaxTheme's theme is SyntaxThemeDefinition; the docsite picker keys on that name and reaches CodeBlock's and DiffViewer's rows: verified (parsePropType.ts:186, both docs type the prop that way).
  • An optional picker starts at None, None sends nothing and the theme-level colours stay: verified (syntaxThemeChoices.ts, Show code drops undefined props, CodeBlock wraps only when the prop is set).
  • Show code names a picked preset by its export: verified (InteractivePreview.tsx:126-129, all 12 presets).
  • The two docsite tests cover these and fail without the change: verified, the new case fails on the base.
  • Both imperative dialog hook show types match the hooks' own declarations: verified.
  • Toast's three props are required and each says, in English, Chinese and the dense text, what the show function sets; the error-persists sentence moved to isAutoHide: verified against ToastViewport.tsx:296-298.
  • The show-only options and their defaults move to useToast's doc: they leave Toast's table, but useToast's doc already listed them on main (same finding as the changeset).
  • The uniqueID best practice names useToast(): verified in all three languages.
  • The Toast record names both consumer docs: verified.
  • The six Toast drift entries are gone and the drift test asks for that: verified, core-prop-docs.test.mjs passes.
  • No type is exported or changed: verified, the built API surfaces compare with no rows.
  • Writing rubric results for the record sentence: verified.
  • The prop-docs and doc-types tests, check:knowledge and check:changesets pass: verified.
  • prettier --check passes on the changed files: false, Selector.doc.mjs:351.
  • useCombobox and useMultiCombobox name options types no entry point exports; MarkdownPluginEntry is exported from the Markdown plugins entry: verified.
  • The overlap note: false for #11517 and #11966; the other entries are as stated.

Files:

  • .changeset/docs-name-exported-types.md: finding (useToast clause).
  • apps/docsite/src/__tests__/component-prop-controls.test.ts: clear.
  • apps/docsite/src/__tests__/syntax-theme-control.test.ts: clear.
  • apps/docsite/src/components/component-detail/InteractivePreview.tsx: clear (non-blocking: the preset branch is untested).
  • apps/docsite/src/components/component-detail/PlaygroundPropsTable.tsx: clear.
  • apps/docsite/src/components/component-detail/parsePropType.ts: clear.
  • apps/docsite/src/components/component-detail/syntaxThemeChoices.ts: clear.
  • docs/specs/components/Toast/Toast.spec.md: clear.
  • packages/cli/test/core-prop-docs.known-drift.json: clear.
  • packages/core/src/AlertDialog/useImperativeAlertDialog.doc.mjs: clear.
  • packages/core/src/Dialog/useImperativeDialog.doc.mjs: clear.
  • packages/core/src/Selector/Selector.doc.mjs: clear for this change's line; its unformatted line 351 makes the Prettier claim false.
  • packages/core/src/Toast/Toast.doc.mjs: clear.
  • packages/core/src/theme/SyntaxTheme.doc.mjs: clear.

Automated review (maintainer link)

Comment thread .changeset/docs-name-exported-types.md Resolved
@cixzhang

Copy link
Copy Markdown
Contributor Author

/approve-spec 83a4ebc

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved pending CI: CI has not run on this head yet, and it runs once the pull request is marked ready for review.

The three statements that went stale when main was merged in are fixed: the changeset now says the show-only Toast options leave the card's table because useToast's doc lists them, the description files #11517 and #11966 with the pull requests that conflict with main, and the Prettier claim covers only the changed lines.

  • Non-blocking: no test exercises Show code's preset naming in InteractivePreview.tsx; a CodeBlock case that picks a preset and expects syntaxTheme={dracula} would hold it.
Claims and files checked

Review mode: incremental; reason: none

Claims:

  • Changeset: four docs name prop types the package exports (Selector options, SyntaxTheme theme, both imperative dialog hooks' show options): verified; each type is exported from Core's root.
  • Changeset: Toast's doc marks type, isAutoHide and autoHideDuration required: verified against ToastProps (Toast.tsx:156-170).
  • Changeset: the show-only options leave Toast's props table because useToast's doc lists them with their defaults: verified (useToast.doc.mjs, unchanged here, lists all three).
  • Title: prop types name only types the package exports: verified; no Core doc's prop type names a type outside Core's declarations apart from React, DOM and built-in types.
  • On the base, four docs name types the package does not export and Toast's table contradicts ToastProps: verified.
  • Selector's options are SelectorOptionType[] and SelectorOption is a component: verified.
  • SyntaxTheme's theme is SyntaxThemeDefinition; the playground picker keys on that name and reaches CodeBlock's and DiffViewer's rows: verified (parsePropType.ts:186; both docs type the prop that way).
  • An optional picker starts at None, and None sends nothing, so an unset prop keeps the theme-level colors: verified (syntaxThemeChoices.ts).
  • Show code names a picked preset by its export: verified (InteractivePreview.tsx:126-129; all 12 preset names camel-case to their exports).
  • The two docsite tests cover these and fail without the change: verified; both fail on the base.
  • Both imperative dialog hooks' show types are the ones the hooks declare: verified (useImperativeAlertDialog.tsx:20, useImperativeDialog.tsx:26-29).
  • Toast's three props are required and each says, in English, Chinese and the dense text, what the show function sets, with the error-persists sentence on isAutoHide: verified against ToastViewport.tsx:296-298.
  • The show-only options and their defaults move to useToast's doc: verified as the result; they leave Toast's table and useToast's doc lists them.
  • The uniqueID best practice names useToast(): verified in all three languages.
  • The Toast record names both consumer docs: verified.
  • The six Toast drift entries are gone, and the drift test asks for that: verified; the prop-docs test passes.
  • No type is exported or changed: verified; the built API surfaces compare with no rows.
  • Writing rubric results for the record sentence: verified.
  • The prop-docs and doc-types tests, the knowledge check and the changeset check pass: verified.
  • Prettier passes on the changed lines, and Selector's doc has one unformatted line from main: verified (line 351 only).
  • useCombobox and useMultiCombobox name options types no entry point exports, and MarkdownPluginEntry is exported from the Markdown plugins entry: verified.
  • The exported-type resolver from #12326 finds the named types at Core's root: verified for the four the docs name (run on this head merged with #12326); ToastProps is a root export.
  • The overlap note: verified; the first five merge cleanly in the files they share, and #11517, #11966 and the rest conflict with main in a file they share.

Files:

  • .changeset/docs-name-exported-types.md: clear.
  • apps/docsite/src/__tests__/component-prop-controls.test.ts: clear.
  • apps/docsite/src/__tests__/syntax-theme-control.test.ts: clear.
  • apps/docsite/src/components/component-detail/InteractivePreview.tsx: clear (non-blocking: the preset branch is untested).
  • apps/docsite/src/components/component-detail/PlaygroundPropsTable.tsx: clear.
  • apps/docsite/src/components/component-detail/parsePropType.ts: clear.
  • apps/docsite/src/components/component-detail/syntaxThemeChoices.ts: clear.
  • docs/specs/components/Toast/Toast.spec.md: clear.
  • packages/cli/test/core-prop-docs.known-drift.json: clear.
  • packages/core/src/AlertDialog/useImperativeAlertDialog.doc.mjs: clear.
  • packages/core/src/Dialog/useImperativeDialog.doc.mjs: clear.
  • packages/core/src/Selector/Selector.doc.mjs: clear.
  • packages/core/src/Toast/Toast.doc.mjs: clear.
  • packages/core/src/theme/SyntaxTheme.doc.mjs: clear.

Automated review (maintainer link)

# Conflicts:
#	packages/cli/test/core-prop-docs.known-drift.json
@cixzhang

Copy link
Copy Markdown
Contributor Author

/approve-spec 0db46bd

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changes requested: one statement in the description went stale when main was merged in.

  • Regression: the overlap note says #11868 shares a file and merges cleanly with this change, but it now conflicts with this head, and with main, in packages/cli/test/core-prop-docs.known-drift.json; move it to the group that already conflicts with main.

The docs, the Toast table, the drift list, the docsite picker and their tests all check out after the merge, and no public API changes.

  • Non-blocking: no test exercises Show code's preset naming in InteractivePreview.tsx; a CodeBlock case that picks a preset and expects syntaxTheme={dracula} would hold it.
Claims and files checked

Review mode: full; reason: merge-touches-pr-files

Claims:

  • Changeset: four docs name prop types the package exports (Selector options, SyntaxTheme theme, both imperative dialog hooks' show options): verified; each named type resolves at Core's root.
  • Changeset: Toast's doc marks type, isAutoHide and autoHideDuration required: verified against ToastProps (Toast.tsx:160-165).
  • Changeset: the show-only options leave Toast's table because useToast's doc lists them with their defaults: verified (useToast.doc.mjs:27-33).
  • Title: prop types name only types the package exports: verified; every Core doc's prop types resolve to Core declarations apart from DOM, built-in and generic names.
  • On the base, four docs name types the package does not export and Toast's table contradicts ToastProps: verified.
  • Selector's options are SelectorOptionType[] and SelectorOption is a component: verified (Selector/index.ts:17-19).
  • SyntaxTheme's theme is SyntaxThemeDefinition; the playground picker keys on that name and reaches CodeBlock's and DiffViewer's rows: verified (parsePropType.ts:186; both docs type the prop that way).
  • An optional picker starts at None, and None sends nothing, so an unset prop keeps the theme-level colors: verified (syntaxThemeChoices.ts:30-56, :73-75).
  • Show code names a picked preset by its export: verified (InteractivePreview.tsx:126-129; all 12 preset names map to their exports).
  • The two docsite tests cover these and fail without the change: verified; both fail on the base and pass on the head.
  • Both imperative dialog hooks' show types are the ones the hooks declare: verified (useImperativeAlertDialog.tsx:20, useImperativeDialog.tsx:26-33).
  • Toast's three props are required and each says, in English, Chinese and the dense text, what the show function sets, with the error-persists sentence on isAutoHide: verified against ToastViewport.tsx:325-327.
  • The show-only options and their defaults move to useToast's doc: verified as the result; they leave Toast's table and useToast's doc lists them.
  • The uniqueID best practice names useToast(): verified in all three languages.
  • The Toast record names both consumer docs: verified.
  • The six Toast drift entries are gone, and the drift test asks for that: verified; the prop-docs test passes after the merge.
  • No type is exported or changed: verified; the built API surfaces compare with no rows.
  • Writing rubric results for the record sentence: verified.
  • The prop-docs and doc-types tests, the knowledge check and the changeset check pass: verified.
  • Prettier passes on the changed lines, and Selector's doc has one unformatted line from main: verified (line 376 only).
  • useCombobox and useMultiCombobox name options types no entry point exports, and MarkdownPluginEntry is exported from the Markdown plugins entry: verified.
  • The exported-type resolver from #12326 finds the five named types at Core's root: verified, run against this head's built Core.
  • Overlap note: false for #11868, which now conflicts with this head and with main in the drift list; true for #6819, #12156, #11960 and #11621 and for every pull request listed as conflicting with main.

Files:

  • .changeset/docs-name-exported-types.md: clear.
  • apps/docsite/src/__tests__/component-prop-controls.test.ts: clear.
  • apps/docsite/src/__tests__/syntax-theme-control.test.ts: clear.
  • apps/docsite/src/components/component-detail/InteractivePreview.tsx: clear (non-blocking: the preset branch is untested).
  • apps/docsite/src/components/component-detail/PlaygroundPropsTable.tsx: clear.
  • apps/docsite/src/components/component-detail/parsePropType.ts: clear.
  • apps/docsite/src/components/component-detail/syntaxThemeChoices.ts: clear.
  • docs/specs/components/Toast/Toast.spec.md: clear.
  • packages/cli/test/core-prop-docs.known-drift.json: clear (the merge keeps exactly the six Toast removals).
  • packages/core/src/AlertDialog/useImperativeAlertDialog.doc.mjs: clear.
  • packages/core/src/Dialog/useImperativeDialog.doc.mjs: clear.
  • packages/core/src/Selector/Selector.doc.mjs: clear.
  • packages/core/src/Toast/Toast.doc.mjs: clear.
  • packages/core/src/theme/SyntaxTheme.doc.mjs: clear.

Automated review (maintainer link)

…he 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.
@cixzhang

Copy link
Copy Markdown
Contributor Author

/approve-spec 85268d7

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changes requested: the title and release note overstate the Toast change, and Show code gains a second copy of an existing helper; the fixes are a wording edit and a small docsite refactor.

  • The title and the changeset say Toast's doc "describes the card", but its type row still reads optional with an 'info' default while ToastProps.type is required (Toast.doc.mjs:46, Toast.tsx:161), so a <Toast> built from the table's required props still fails with TS2741; narrow the wording to what changes, for example "Toast's doc marks the card's isAutoHide and autoHideDuration required, as ToastProps declares; type keeps its documented 'info' default".
  • Miss: syntaxPresetIdentifier camel-cases preset names with its own regex (syntaxThemeChoices.ts:62-70) beside toIdentifierName, which Show code already uses for theme names (InteractivePreview.tsx:101-113); print the matched preset with toIdentifierName, or share one helper, so a fix to one reaches both.

The type renames, the Toast timing rows, the drift list, the native mapping and the reworked overlap note all check out, and no public API changes.

  • Non-blocking: no test reaches Show code's preset branch (InteractivePreview.tsx:126-129); a CodeBlock case that picks a preset and expects syntaxTheme={dracula} would hold it.
Claims and files checked

Review mode: incremental; reason: none

Claims:

  • Changeset: four docs name prop types the package exports (Selector options, SyntaxTheme theme, both imperative dialog hooks' show options): verified; each type reaches Core's root exports.
  • Changeset: Toast's doc describes the card, with isAutoHide and autoHideDuration required there: false in part; the two are required as ToastProps declares (Toast.tsx:164-165), but type still reads optional with a default the card does not have.
  • Changeset: the show-only options leave Toast's table because useToast's doc lists them with their defaults: verified (useToast.doc.mjs:24-33).
  • Title: prop types name only types the package exports: verified for the four docs this changes.
  • Title: Toast's doc describes the card: false for type (above).
  • On the base, four docs name types the package does not export, and Toast's table leaves isAutoHide and autoHideDuration optional although ToastProps requires them: verified.
  • Selector's options are SelectorOptionType[] and SelectorOption is a component: verified (Selector/index.ts:17-19).
  • SyntaxTheme's theme is SyntaxThemeDefinition, and the playground picker now keys on that name and reaches CodeBlock's and DiffViewer's rows: verified (parsePropType.ts:186; both docs type the prop that way).
  • An optional picker starts at None, and None sends nothing, so an unset prop keeps the theme-level colors: verified (syntaxThemeChoices.ts:30-56, :73-75).
  • Show code names a picked preset by its export: verified (InteractivePreview.tsx:126-129).
  • The two docsite tests cover these and fail without the change: verified; both pass at this head and fail on the base.
  • Both imperative dialog hooks' show types are the ones the hooks declare: verified (useImperativeAlertDialog.tsx:20-24, useImperativeDialog.tsx:26-33).
  • isAutoHide and autoHideDuration are required, and each says in English, Chinese and the dense text what the show function sets: verified against ToastViewport.tsx:325-327.
  • The error-persists sentence moves from type to isAutoHide: verified in all three texts.
  • type keeps its documented 'info' default: verified (Toast.doc.mjs:46).
  • The show-only options and their defaults live on useToast's doc: verified.
  • The uniqueID best practice names useToast(): verified in all three languages.
  • The Toast record names both consumer docs: verified.
  • Five of the six Toast drift entries are gone and the type entry stays: verified; the prop-docs test passes.
  • Native maps the renamed Selector doc type to its own option type, the one key the rename reaches, and its contract and Swift output are unchanged: verified; the native contract tests pass and no other native component documents a renamed type.
  • No type is exported or changed: verified; the built API surfaces compare with no rows (the docsite code, tests and drift list change too).
  • The theme editor reads playground defaults and a visual prop's documented default, and documenting type as required, or setting it in the playground, adds --when type:info to its toast lines: verified; both variants fail five theme-editor tests with that line.
  • Writing rubric results for the record sentence: verified.
  • The native contract, theme-editor toast, docsite, prop-docs and doc-type tests, the knowledge check and the changeset check pass: verified.
  • Prettier passes on the changed lines, and Selector's doc has one unformatted line from main: verified (line 376 only, the same on the base).
  • useCombobox and useMultiCombobox name options types no entry point exports, and MarkdownPluginEntry is exported from the Markdown plugins entry: verified (Selector/hooks.ts:368, MultiSelector/hooks.ts:24, Markdown/plugins/index.ts:59).
  • The exported-type resolver finds the five named types at Core's root: verified from Core's root exports.
  • Overlap note: verified; #6819, #12378 and #12450 merge cleanly with this head in the files they share, #11868, #11517, #11966 and the rest conflict with main in the files they share, and #12156, #11960 and #11621 are closed.
  • Owner and land path: process statements, not code claims.

Files:

  • .changeset/docs-name-exported-types.md: finding (describes the card).
  • apps/docsite/src/__tests__/component-prop-controls.test.ts: clear.
  • apps/docsite/src/__tests__/syntax-theme-control.test.ts: clear.
  • apps/docsite/src/components/component-detail/InteractivePreview.tsx: clear (non-blocking: the preset branch is untested).
  • apps/docsite/src/components/component-detail/PlaygroundPropsTable.tsx: clear.
  • apps/docsite/src/components/component-detail/parsePropType.ts: clear.
  • apps/docsite/src/components/component-detail/syntaxThemeChoices.ts: finding (second identifier conversion).
  • docs/specs/components/Toast/Toast.spec.md: clear.
  • packages/cli/test/core-prop-docs.known-drift.json: clear.
  • packages/core/src/AlertDialog/useImperativeAlertDialog.doc.mjs: clear.
  • packages/core/src/Dialog/useImperativeDialog.doc.mjs: clear.
  • packages/core/src/Selector/Selector.doc.mjs: clear.
  • packages/core/src/Toast/Toast.doc.mjs: finding (type row, with the changeset).
  • packages/core/src/theme/SyntaxTheme.doc.mjs: clear.
  • packages/native/src/components/Selector.ts: clear.

Automated review (maintainer link)

Comment thread .changeset/docs-name-exported-types.md Resolved
…ifier 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.
@cixzhang cixzhang changed the title docs(core): prop types name only types the package exports; Toast's doc describes the card docs(core): prop types name only types the package exports; Toast's doc marks the card's timing props required Nov 20, 2026
@cixzhang

Copy link
Copy Markdown
Contributor Author

/approve-spec f8552e9

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changes requested: the doc and docsite changes check out and both findings from the last review are fixed, but two sentences in the description overstate what the change and its tests do.

  • The Testing section says Core's docs now match Core's props for Toast, but type still reads optional with an 'info' default while ToastProps.type is required, and core-prop-docs.known-drift.json:44 keeps Toast.type required_mismatch; add "except type, which stays listed drift" or drop the sentence.
  • The SyntaxTheme bullet says component-prop-controls.test.ts and syntax-theme-control.test.ts cover Show code naming a picked preset, but no test reaches InteractivePreview.tsx:126-129 (the helper test now checks only 'one-dark-pro', and interactive-preview.test.ts mocks the presets as empty), so Show code printing syntaxTheme={one-dark-pro} would pass every test; add a case that pins syntaxTheme={oneDarkPro} in Show code, or narrow the sentence to the picker and the None choice.

No public API changes, and the type renames, the Toast timing rows, the drift list, the native mapping and the overlap note all check out.

Claims and files checked

Review mode: incremental; reason: none

Claims:

  • Changeset: four docs name prop types the package exports (Selector options, SyntaxTheme theme, both imperative dialog hooks' show options): verified; each type reaches Core's root exports.
  • Changeset: Toast's doc marks the card's isAutoHide and autoHideDuration required, as ToastProps declares: verified (Toast.doc.mjs:48-61, Toast.tsx:164-165).
  • Changeset: the show-only options leave Toast's table because useToast's doc lists them with their defaults: verified (useToast.doc.mjs:24-33).
  • Changeset: type keeps its documented 'info' default: verified (Toast.doc.mjs:46).
  • Title: prop types name only types the package exports: verified for the four docs this changes.
  • Title: Toast's doc marks the card's timing props required: verified.
  • On the base, four docs name types the package does not export, and Toast's table leaves isAutoHide and autoHideDuration optional although ToastProps requires them, so a card written from it does not type-check: verified.
  • Selector's options are SelectorOptionType[] and SelectorOption is a component: verified (Selector/index.ts:17-19).
  • SyntaxTheme's theme is SyntaxThemeDefinition, and the playground picker now keys on that name and reaches CodeBlock's and DiffViewer's rows: verified (parsePropType.ts:186; both docs type the prop that way).
  • An optional picker starts at None, and None sends nothing, so an unset prop keeps the theme-level colors: verified (syntaxThemeChoices.ts:30-56, :67-69).
  • Show code names a picked preset by its export, through the same identifier helper it uses for theme names: verified (InteractivePreview.tsx:126-129, :137).
  • The two docsite tests cover these and fail without the change: false for Show code's preset naming (above); the picker and None parts are covered and fail on the base.
  • Both imperative dialog hooks' show types are the ones the hooks declare, written with exported types: verified (useImperativeAlertDialog.tsx:20-24, useImperativeDialog.tsx:26-33).
  • isAutoHide and autoHideDuration are required, and each says in English, Chinese and the dense text what the show function sets: verified against ToastViewport.tsx:325-327.
  • The error-persists sentence moves from type to isAutoHide: verified in all three texts.
  • The show-only options and their defaults live on useToast's doc: verified (already listed there on the base).
  • The uniqueID best practice names useToast(): verified in all three languages.
  • The Toast record names both consumer docs: verified.
  • Five of the six Toast drift entries are gone and the type entry stays: verified; the prop-docs test passes.
  • Native maps the renamed Selector doc type to its own option type, the one key the rename reaches, and its contract and Swift output are unchanged: verified; the native contract tests pass and no other native component documents a renamed type.
  • No type is exported or changed: verified; the built API surfaces compare with no rows (the docsite code, tests and drift list change too).
  • The theme editor reads playground defaults and a visual prop's documented default, and documenting type as required, or setting it in the playground, adds a type-specific line to its toast output: verified; the theme-editor and Toast doc files are unchanged since that check.
  • Writing rubric results for the record sentence: verified.
  • The native contract, theme-editor toast, docsite, prop-docs and doc-type tests, the knowledge check and the changeset check pass: verified.
  • Core's docs now match Core's props for Toast: false; type stays listed drift (core-prop-docs.known-drift.json:44).
  • Prettier passes on the changed lines, and Selector's doc has one unformatted line from main: verified (line 376 only, the same on the base).
  • useCombobox and useMultiCombobox name options types no entry point exports, and MarkdownPluginEntry is exported from the Markdown plugins entry: verified.
  • The exported-type resolver finds the five named types at Core's root: verified from Core's root exports.
  • Overlap note: verified; #6819, #12378 and #12450 merge with this head without conflict in the files they share, #11868, #11517, #11966 and the others that share a file conflict with main in it, and #12156, #11960 and #11621 are closed.
  • Owner and land path: process statements, not code claims.

Files:

  • .changeset/docs-name-exported-types.md: clear.
  • apps/docsite/src/__tests__/component-prop-controls.test.ts: clear.
  • apps/docsite/src/__tests__/syntax-theme-control.test.ts: finding (checks the preset name, not Show code's identifier).
  • apps/docsite/src/components/component-detail/InteractivePreview.tsx: finding (preset branch reached by no test).
  • apps/docsite/src/components/component-detail/PlaygroundPropsTable.tsx: clear.
  • apps/docsite/src/components/component-detail/parsePropType.ts: clear.
  • apps/docsite/src/components/component-detail/syntaxThemeChoices.ts: clear.
  • docs/specs/components/Toast/Toast.spec.md: clear.
  • packages/cli/test/core-prop-docs.known-drift.json: clear (bounds the Testing claim).
  • packages/core/src/AlertDialog/useImperativeAlertDialog.doc.mjs: clear.
  • packages/core/src/Dialog/useImperativeDialog.doc.mjs: clear.
  • packages/core/src/Selector/Selector.doc.mjs: clear.
  • packages/core/src/Toast/Toast.doc.mjs: clear.
  • packages/core/src/theme/SyntaxTheme.doc.mjs: clear.
  • packages/native/src/components/Selector.ts: clear.

Automated review (maintainer link)

"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.onHide not_in_code",
"src/Toast/Toast.doc.mjs Toast.type required_mismatch",

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This entry stays, so the description's Testing line "Core's docs now match Core's props for Toast" is broader than the change: type still reads optional with default: "'info'" (packages/core/src/Toast/Toast.doc.mjs:41-47) while ToastProps.type is required (Toast.tsx:161). Suggest: "Core's Toast doc now matches Core's props except type, which stays listed drift."

}
const syntaxPreset = syntaxPresetName(value);
if (syntaxPreset != null) {
return toIdentifierName(syntaxPreset);

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No test reaches this branch: syntax-theme-control.test.ts:33-41 now checks only that syntaxPresetName returns 'one-dark-pro', and interactive-preview.test.ts:31 mocks allSyntaxPresets as []. With this line changed to return syntaxPreset; every docsite test still passes while Show code prints syntaxTheme={one-dark-pro}, so the description's "cover these" does not hold for Show code. A case that picks a preset and expects syntaxTheme={oneDarkPro} in Show code would pin it; otherwise narrow that sentence to the picker and the None choice.

This branch was successfully deployed

1 active deployment
Preview — f8552e91 Deployed Nov 20, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

CLA Signed This label is managed by the Meta Open Source bot. lane:4 Astryx fix-loop lane 4 owns this needs:design-review Affects visuals — Design should review

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant