@astryxdesign/richtext 0.7.11 → 0.7.12-canary.ccb4a6d

package/dist/editorTheme.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"editorTheme.d.ts","sourceRoot":"","sources":["../src/editorTheme.ts"],"names":[],"mappings":"AA2BA,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,SAAS,CAAC;AAqchD;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,kBAAkB,CAgEtD"}
+{"version":3,"file":"editorTheme.d.ts","sourceRoot":"","sources":["../src/editorTheme.ts"],"names":[],"mappings":"AA2BA,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,SAAS,CAAC;AAschD;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,kBAAkB,CAgEtD"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@astryxdesign/richtext",
   "displayName": "Rich Text",
-  "version": "0.7.11",
+  "version": "0.7.12-canary.ccb4a6d",
   "description": "Astryx rich text — a Lexical-based rich text editor and viewer, styled with Astryx design tokens.",
   "author": "Meta Open Source",
   "license": "MIT",
@@ -66,7 +66,7 @@
   },
   "peerDependencies": {
     "@stylexjs/stylex": ">=0.10.0",
-    "@astryxdesign/core": "0.7.11",
+    "@astryxdesign/core": "0.7.12-canary.ccb4a6d",
     "react": ">=19.0.0",
     "react-dom": ">=19.0.0",
     "lexical": "^0.52.0",
@@ -125,6 +125,8 @@
     }
   },
   "devDependencies": {
+    "@astryxdesign/a11y-spec": "0.7.12-canary.ccb4a6d",
+    "@astryxdesign/cli": "0.7.12-canary.ccb4a6d",
     "@babel/cli": "^7.29.7",
     "@babel/core": "^7.29.7",
     "@babel/preset-react": "^7.29.7",
@@ -143,9 +145,7 @@
     "@lexical/utils": "^0.52.0",
     "@stylexjs/babel-plugin": "^0.19.0",
     "@testing-library/react": "^16.3.2",
-    "lexical": "^0.52.0",
-    "@astryxdesign/a11y-spec": "0.0.0",
-    "@astryxdesign/cli": "0.7.11"
+    "lexical": "^0.52.0"
   },
   "scripts": {
     "api:report": "node ../../scripts/api-report/cli.mjs --package .",

package/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.",
+      },
+    ],
+  },
+};

package/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.",
+      },
+    ],
+  },
+};

package/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.',
+      },
+    ],
+  },
+};

package/src/editorTheme.ts

@@ -62,9 +62,10 @@ const editorTheme = stylex.create({
   // Lexical marks every top-level block `dir="auto"`, which picks each
   // block's direction from its first strong character: a Hebrew paragraph in
   // an English document flips to the right, an English one in an Arabic
-  // document to the left. Blocks take the direction of the surface around
-  // them instead, as core Markdown's do, and bidi inside a block still
-  // follows the Unicode algorithm (spec:AST-061 FR6).
+  // document to the left. Here blocks take the direction of the surface
+  // around them, and bidi inside a block still follows the Unicode
+  // algorithm. Core Markdown differs: it gives each block the direction of
+  // its own text.
   providerDirection: {
     direction: 'inherit',
   },