Skip to content

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.md
new file mode 100644
index 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.
+
+@cixzhang
diff --git a/apps/docsite/src/__tests__/data-extraction.test.ts b/apps/docsite/src/__tests__/data-extraction.test.ts
index 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.json
index 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.mjs
index 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.json
index 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.json
index 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.json
index 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.mjs
new file mode 100644
index 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.mjs
new file mode 100644
index 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.mjs
new file mode 100644
index 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.',
+ },
+ ],
+ },
+};