An open source design system that's fully customizable and agent ready
TypeScript
docs(richtext): RichTextView, RichTextEditorToolbar and RichTextEditorAutoLinkPlugin get their own doc files (#10407)
Cindy Zhanga646669ab199
diff --git a/.changeset/richtext-component-docs.md b/.changeset/richtext-component-docs.mdnew file mode 100644index 0000000000..a39932c876--- /dev/null+++ b/.changeset/richtext-component-docs.md@@ -0,0 +1,8 @@+---+'@astryxdesign/cli': patch+'@astryxdesign/richtext': patch+---++[docs] `RichTextView`, `RichTextEditorToolbar` and `RichTextEditorAutoLinkPlugin` each ship a doc file, so `astryx component`, `astryx discover` and the docs list their props, defaults and usage.++@cixzhangdiff --git a/apps/docsite/src/__tests__/data-extraction.test.ts b/apps/docsite/src/__tests__/data-extraction.test.tsindex 366bf074b9..d19a574aae 100644--- a/apps/docsite/src/__tests__/data-extraction.test.ts+++ b/apps/docsite/src/__tests__/data-extraction.test.ts@@ -285,7 +285,12 @@ describe('componentRegistry', () => {'ChartTooltip',]);expect(components['@astryxdesign/richtext'].map(comp => comp.name)).toEqual(- ['RichTextEditor'],+ [+ 'RichTextEditor',+ 'RichTextEditorAutoLinkPlugin',+ 'RichTextEditorToolbar',+ 'RichTextView',+ ],);expect(components['@astryxdesign/vega'].map(comp => comp.name)).toEqual(['VegaChart',diff --git a/internal/shadcn-registry/routes.lock.json b/internal/shadcn-registry/routes.lock.jsonindex a1f8877aa2..ec0b341ce3 100644--- a/internal/shadcn-registry/routes.lock.json+++ b/internal/shadcn-registry/routes.lock.json@@ -882,6 +882,21 @@"path": "components/richtext/rich-text-editor","aliases": []},+ {+ "name": "component-richtext-rich-text-editor-auto-link-plugin",+ "path": "components/richtext/rich-text-editor-auto-link-plugin",+ "aliases": []+ },+ {+ "name": "component-richtext-rich-text-editor-toolbar",+ "path": "components/richtext/rich-text-editor-toolbar",+ "aliases": []+ },+ {+ "name": "component-richtext-rich-text-view",+ "path": "components/richtext/rich-text-view",+ "aliases": []+ },{"name": "component-scrollable-area","path": "components/scrollable-area",diff --git a/packages/cli/api/discover/discover.test.mjs b/packages/cli/api/discover/discover.test.mjsindex 771c55bc73..5e6c54f6b2 100644--- a/packages/cli/api/discover/discover.test.mjs+++ b/packages/cli/api/discover/discover.test.mjs@@ -70,10 +70,14 @@ describe('discover() dispatcher routing', () => {// leaf returns the multi-match discover.search envelope. Proves free-text// routing reaches the search leaf and projects its envelope. Search also// matches package names, so the package itself is listed after them.+ // Official packages' components can match too, so only this fixture's+ // package is compared.const r = await discover('a');expect(r.type).toBe('discover.search');expect(- r.data.matches.filter(m => m.kind === 'component').map(m => m.component),+ r.data.matches+ .filter(m => m.kind === 'component' && m.package === '@acme/widgets')+ .map(m => m.component),).toEqual(['Alpha', 'Beta']);expect(r.data.matches).toContainEqual({package: '@acme/widgets',diff --git a/packages/cli/assets/discover/official-packages.json b/packages/cli/assets/discover/official-packages.jsonindex 9351ed525a..fdb101f73f 100644--- a/packages/cli/assets/discover/official-packages.json+++ b/packages/cli/assets/discover/official-packages.json@@ -283,6 +283,18 @@"kind": "component","name": "RichTextEditor"},+ {+ "kind": "component",+ "name": "RichTextEditorAutoLinkPlugin"+ },+ {+ "kind": "component",+ "name": "RichTextEditorToolbar"+ },+ {+ "kind": "component",+ "name": "RichTextView"+ },{"kind": "template","name": "RichTextEditorShowcase"diff --git a/packages/cli/test/__golden__/no-icon-set/discover-malformed-icon-set-source.json b/packages/cli/test/__golden__/no-icon-set/discover-malformed-icon-set-source.jsonindex e696bf73cb..fd7ba4e53a 100644--- a/packages/cli/test/__golden__/no-icon-set/discover-malformed-icon-set-source.json+++ b/packages/cli/test/__golden__/no-icon-set/discover-malformed-icon-set-source.json@@ -9,7 +9,10 @@"name": "@astryxdesign/richtext","package": "@astryxdesign/richtext","components": [- "RichTextEditor"+ "RichTextEditor",+ "RichTextEditorAutoLinkPlugin",+ "RichTextEditorToolbar",+ "RichTextView"],"version": "<version>","description": "Astryx rich text — a Lexical-based rich text editor and viewer, styled with Astryx design tokens.",diff --git a/packages/cli/test/__golden__/no-icon-set/discover.json b/packages/cli/test/__golden__/no-icon-set/discover.jsonindex 41efd10cc5..8827c884c1 100644--- a/packages/cli/test/__golden__/no-icon-set/discover.json+++ b/packages/cli/test/__golden__/no-icon-set/discover.json@@ -16,7 +16,10 @@"name": "@astryxdesign/richtext","package": "@astryxdesign/richtext","components": [- "RichTextEditor"+ "RichTextEditor",+ "RichTextEditorAutoLinkPlugin",+ "RichTextEditorToolbar",+ "RichTextView"],"version": "<version>","description": "Astryx rich text — a Lexical-based rich text editor and viewer, styled with Astryx design tokens.",diff --git a/packages/richtext/src/RichTextEditorAutoLinkPlugin.doc.mjs b/packages/richtext/src/RichTextEditorAutoLinkPlugin.doc.mjsnew file mode 100644index 0000000000..2d36114fae--- /dev/null+++ b/packages/richtext/src/RichTextEditorAutoLinkPlugin.doc.mjs@@ -0,0 +1,43 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */++export const docs = {+ name: 'RichTextEditorAutoLinkPlugin',+ subComponentOf: 'RichTextEditor',+ description:+ 'Turns typed and pasted URLs and email addresses into links, in the plugins slot of RichTextEditor.',+ displayName: 'Rich Text Editor Auto-Link Plugin',+ keywords: ['richtext', 'autolink', 'link', 'url', 'email', 'plugin'],+ props: [+ {+ name: 'matchers',+ type: 'LinkMatcher[]',+ description:+ 'Link matchers to use. The default recognizes URLs and email addresses and opens the links in a new tab. Build extra matchers with createLinkMatcherWithRegExp from @lexical/react/LexicalAutoLinkPlugin.',+ default: 'DEFAULT_LINK_MATCHERS',+ },+ {+ name: 'onChange',+ type: '(url: string | null, prevUrl: string | null) => void',+ description:+ 'Called when auto-linking creates, updates or removes a link. It gets the new URL, or null when the link is removed, and the previous URL.',+ },+ ],+ usage: {+ description:+ "Turns typed and pasted URLs and email addresses into links. Render it in RichTextEditor's plugins slot; it reaches the editor through the editor's Lexical composer and uses AutoLinkNode, which the editor registers by default.",+ bestPractices: [+ {+ guidance: true,+ description:+ 'Pass it as plugins={<RichTextEditorAutoLinkPlugin />}. Its links open in a new tab, with target="_blank" and rel="noopener noreferrer" in the node.',+ },+ {+ guidance: false,+ description:+ "Render it outside RichTextEditor's plugins slot: it needs the editor's Lexical composer.",+ },+ ],+ },+};diff --git a/packages/richtext/src/RichTextEditorToolbar.doc.mjs b/packages/richtext/src/RichTextEditorToolbar.doc.mjsnew file mode 100644index 0000000000..7061d7a7b1--- /dev/null+++ b/packages/richtext/src/RichTextEditorToolbar.doc.mjs@@ -0,0 +1,92 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */++export const docs = {+ name: 'RichTextEditorToolbar',+ subComponentOf: 'RichTextEditor',+ description: 'Formatting toolbar for the toolbar slot of RichTextEditor.',+ displayName: 'Rich Text Editor Toolbar',+ keywords: ['richtext', 'toolbar', 'formatting', 'bold', 'link', 'heading'],+ props: [+ {+ name: 'ref',+ type: 'Ref<HTMLDivElement>',+ description:+ 'Ref to the toolbar\'s root element. The ref, className, style and xstyle reach the root of the Astryx Toolbar it renders; data-*, other aria-* attributes and DOM handlers reach its role="toolbar" element.',+ },+ {+ name: 'label',+ type: 'string',+ description:+ 'Accessible label for the toolbar element. Pass label rather than aria-label.',+ default: "'Text formatting' (translated)",+ },+ {+ name: 'headingLevels',+ type: "ReadonlyArray<'h1' | 'h2' | 'h3'>",+ description:+ 'Which heading levels the block-format selector offers, in order.',+ default: "['h1', 'h2', 'h3']",+ },+ {+ name: 'size',+ type: "'sm' | 'md' | 'lg'",+ description:+ "Size of the toolbar's controls; it also sets the toolbar's padding.",+ default: "'sm'",+ },+ {+ name: 'hasLink',+ type: 'boolean',+ description:+ 'Whether to show the link button. It opens an Astryx Dialog that adds, updates or removes a link and keeps the editor selection. With a collapsed selection the URL is inserted as link text; otherwise the selected text is linked. Only http, https, mailto and tel URLs are written.',+ default: 'true',+ },+ {+ name: 'promptForUrl',+ type: '(selectedText: string) => string | null | undefined',+ description:+ 'A synchronous URL prompt that replaces the built-in Dialog when the link button is pressed on a selection that is not a link. It gets the selected text; return the URL, or null or an empty string to cancel.',+ },+ {+ name: 'hasNewTabLinks',+ type: 'boolean',+ description:+ 'Whether links made with the toolbar open in a new tab. When true, target="_blank" and rel="noopener noreferrer" are written into the link node, so they serialize.',+ default: 'true',+ },+ {+ name: 'endContent',+ type: 'ReactNode',+ description:+ 'Extra items at the end of the toolbar, after a divider, such as mention or AI controls.',+ },+ {+ name: 'xstyle',+ type: 'StyleXStyles',+ description: "StyleX styles for the toolbar's root.",+ },+ ],+ usage: {+ description:+ "A formatting toolbar for RichTextEditor, built from Astryx Toolbar, Selector and ToggleButton controls: undo and redo, a block-format selector for paragraphs, headings, lists and quotes, inline bold, italic, underline, strikethrough and code, and links. Render it in the editor's toolbar slot; it reaches the editor through the editor's Lexical composer, so it must live inside it.",+ bestPractices: [+ {+ guidance: true,+ description:+ 'Pass it as toolbar={<RichTextEditorToolbar />}. The slot places it at the top of the field, before the editing surface, in the right keyboard order.',+ },+ {+ guidance: true,+ description:+ "Restyle a glyph from a theme by its richtext:* icon key (see RICHTEXT_ICON_KEYS), for example defineTheme({icons: {'richtext:bold': <MyBoldIcon />}}).",+ },+ {+ guidance: false,+ description:+ "Render it outside RichTextEditor's toolbar slot: it needs the editor's Lexical composer.",+ },+ ],+ },+};diff --git a/packages/richtext/src/RichTextView.doc.mjs b/packages/richtext/src/RichTextView.doc.mjsnew file mode 100644index 0000000000..6eaff13fa6--- /dev/null+++ b/packages/richtext/src/RichTextView.doc.mjs@@ -0,0 +1,101 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */++export const docs = {+ name: 'RichTextView',+ displayName: 'Rich Text View',+ category: 'Content',+ keywords: [+ 'richtext',+ 'rich text',+ 'viewer',+ 'read-only',+ 'lexical',+ 'render',+ 'serialized',+ ],+ props: [+ {+ name: 'value',+ type: 'string',+ description:+ 'Serialized editor state to render: the JSON string from JSON.stringify(editorState.toJSON()). The view updates when value changes.',+ required: true,+ },+ {+ name: 'nodes',+ type: 'ReadonlyArray<Klass<LexicalNode>>',+ description:+ 'Lexical nodes to register beyond the default set. Pass the same nodes the content was authored with, so custom node types deserialize.',+ },+ {+ name: 'markdownExtensions',+ type: 'ReadonlyArray<RichTextMarkdownExtension>',+ description:+ 'Markdown plugins whose nodes this view draws, each adopted with createRichTextExtension. A plugin node renders as core Markdown renders it; a node whose plugin is not passed shows its source. Pass the extensions the content was converted with, created in a client module.',+ },+ {+ name: 'codeLanguages',+ type: 'ReadonlyArray<CodeLanguage>',+ description:+ "CodeBlock languages a fence may name, such as graphql from @astryxdesign/core/CodeBlock/languages/graphql. Pass the same list as Markdown's codeLanguages, so reading and editing label and paint the same languages.",+ },+ {+ name: 'plugins',+ type: 'ReactNode',+ description:+ 'Read-only Lexical plugins to render inside the view, such as hover cards or decorators.',+ },+ {+ name: 'namespace',+ type: 'string',+ description: 'The Lexical composer namespace.',+ default: "'astryx-view'",+ },+ {+ name: 'onParseError',+ type: '(error: Error) => void',+ description:+ 'Called when value cannot be parsed or rendered, for example malformed JSON or a node type that is not registered through nodes. Use it to log or report the failure.',+ },+ {+ name: 'errorFallback',+ type: 'ReactNode',+ description:+ 'What to render when value cannot be parsed or rendered. The view renders it instead of throwing.',+ default: 'null',+ },+ {+ name: 'xstyle',+ type: 'StyleXStyles',+ description: 'StyleX styles for the view root.',+ },+ ],+ usage: {+ description:+ 'Renders serialized RichTextEditor content read-only, with the same nodes, tables, code blocks and Markdown plugin nodes the editor draws. Ships from @astryxdesign/richtext, with lexical and @lexical/* as optional peer dependencies.',+ bestPractices: [+ {+ guidance: true,+ description:+ 'Store editorState.toJSON() from RichTextEditor onChange, and pass the stringified JSON as value.',+ },+ {+ guidance: true,+ description:+ 'Register the same custom nodes and markdownExtensions on the editor and the view, so stored content round-trips.',+ },+ {+ guidance: true,+ description:+ 'Pass onParseError and an errorFallback when the stored content can come from an older or a foreign schema. By default a parse failure renders nothing instead of throwing.',+ },+ {+ guidance: false,+ description:+ 'Use RichTextView to render Markdown source; use core Markdown for that.',+ },+ ],+ },+};