@blue-patterns/richtext 0.0.0-stage → 0.7.18

package/src/RichTextEditorAutoLinkPlugin.doc.mjs

@@ -0,0 +1,43 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@blue-patterns/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. Text inside a code block stays code and is never linked. 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/RichTextEditorAutoLinkPlugin.tsx

@@ -0,0 +1,126 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file RichTextEditorAutoLinkPlugin.tsx
+ * @input Uses `@lexical/react/LexicalAutoLinkPlugin` (`AutoLinkPlugin`,
+ *   `createLinkMatcherWithRegExp`) and the shared URL/email matchers from
+ *   `linkUtils`.
+ * @output Exports `RichTextEditorAutoLinkPlugin` and its props type, plus the
+ *   default `DEFAULT_LINK_MATCHERS`.
+ * @position @blue-patterns/richtext. Drop into RichTextEditor's `plugins` slot to
+ *   auto-linkify URLs and emails as they are typed or pasted, except inside
+ *   a code block. Requires `AutoLinkNode` to be registered (it is, by
+ *   default).
+ *
+ * SYNC: When modified, update:
+ * - /packages/richtext/src/index.ts (exports / barrel)
+ * - /packages/richtext/src/RichTextEditor.doc.mjs (usage notes)
+ * - /packages/richtext/src/RichTextEditor.test.tsx (tests)
+ * - /apps/storybook/stories/RichTextEditor.stories.tsx (story)
+ *
+ * NOTE: `lexical` and `@lexical/*` are OPTIONAL peer dependencies — install them
+ * to use this.
+ *
+ * COMPATIBILITY: the plugin is deliberately a thin pass-through so an
+ * application with its own link conventions can adopt it without forking. It
+ * uses the stock matcher shape (`createLinkMatcherWithRegExp` + `attributes`)
+ * and new-tab defaults, so a consumer supplies a richer matcher set — an
+ * application-specific identifier or ticket syntax, say — through the
+ * `matchers` prop without changing the contract. An application needing a
+ * hardened transform (expanded separators, say) substitutes its own plugin in
+ * the same slot; astryx stays on the upstream `AutoLinkPlugin`.
+ */
+
+import {
+  AutoLinkPlugin,
+  createLinkMatcherWithRegExp,
+  type LinkMatcher,
+} from '@lexical/react/LexicalAutoLinkPlugin';
+import {$isCodeNode} from '@lexical/code';
+import type {ElementNode} from 'lexical';
+import {URL_MATCHER, EMAIL_MATCHER, sanitizeUrl} from './linkUtils';
+
+/**
+ * Attributes written onto every auto-created link so it opens in a new tab.
+ * `rel="noopener noreferrer"` is required whenever `target="_blank"` is set, to
+ * prevent reverse-tabnabbing.
+ */
+export const NEW_TAB_LINK_ATTRIBUTES = {
+  target: '_blank',
+  rel: 'noopener noreferrer',
+} as const;
+
+/**
+ * Default matchers: bare URLs (defaulting to `https://` when scheme-less) and
+ * email addresses (as `mailto:` links). Both carry {@link NEW_TAB_LINK_ATTRIBUTES}.
+ * URLs are passed through {@link sanitizeUrl} so only http/https/mailto/tel
+ * schemes are ever written.
+ */
+export const DEFAULT_LINK_MATCHERS: LinkMatcher[] = [
+  text => {
+    const match = createLinkMatcherWithRegExp(URL_MATCHER, url =>
+      sanitizeUrl(url),
+    )(text);
+    return match ? {...match, attributes: NEW_TAB_LINK_ATTRIBUTES} : null;
+  },
+  text => {
+    const match = createLinkMatcherWithRegExp(
+      EMAIL_MATCHER,
+      email => `mailto:${email}`,
+    )(text);
+    return match ? {...match, attributes: NEW_TAB_LINK_ATTRIBUTES} : null;
+  },
+];
+
+// Text in a code block is never linked. The upstream plugin registers again
+// when this array changes. Keep it a module constant.
+const EXCLUDE_PARENTS: ((parent: ElementNode) => boolean)[] = [$isCodeNode];
+
+export interface RichTextEditorAutoLinkPluginProps {
+  /**
+   * Link matchers to use. Defaults to {@link DEFAULT_LINK_MATCHERS} (URLs +
+   * emails, opening in a new tab). Provide a custom array to recognize
+   * additional patterns (e.g. product-specific shortform references) — build
+   * each with `createLinkMatcherWithRegExp` from
+   * `@lexical/react/LexicalAutoLinkPlugin`.
+   */
+  matchers?: LinkMatcher[];
+  /**
+   * Called when a link is created, updated, or removed by auto-linking.
+   * Receives the new URL (or `null` when removed) and the previous URL.
+   */
+  onChange?: (url: string | null, prevUrl: string | null) => void;
+}
+
+/**
+ * Automatically converts typed/pasted URLs and email addresses into links.
+ * Render it inside the editor's `plugins` slot — it reaches the editor via
+ * `useLexicalComposerContext()`, so it must live within the editor's
+ * `LexicalComposer`. Requires `AutoLinkNode` (registered by default).
+ *
+ * @example
+ * ```
+ * import {RichTextEditor, RichTextEditorAutoLinkPlugin} from '@blue-patterns/richtext';
+ *
+ * <RichTextEditor
+ *   label="Notes"
+ *   plugins={<RichTextEditorAutoLinkPlugin />}
+ * />
+ * ```
+ */
+export function RichTextEditorAutoLinkPlugin({
+  matchers = DEFAULT_LINK_MATCHERS,
+  onChange,
+}: RichTextEditorAutoLinkPluginProps) {
+  return (
+    <AutoLinkPlugin
+      matchers={matchers}
+      onChange={onChange}
+      excludeParents={EXCLUDE_PARENTS}
+    />
+  );
+}
+
+RichTextEditorAutoLinkPlugin.displayName = 'RichTextEditorAutoLinkPlugin';

package/src/RichTextEditorToolbar.doc.mjs

@@ -0,0 +1,92 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@blue-patterns/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 a link popover anchored to the button, with one URL field applied with Enter and Remove when the selection is in a link. The popover is not modal; Escape or Cancel returns focus and the selection to the editor. 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 link popover 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.",
+      },
+    ],
+  },
+};