@blue-patterns/richtext 0.0.0-stage → 0.7.18

package/dist/RichTextEditorAutoLinkPlugin.d.ts

@@ -0,0 +1,83 @@
+/**
+ * @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 { type LinkMatcher } from '@lexical/react/LexicalAutoLinkPlugin';
+/**
+ * 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 declare const NEW_TAB_LINK_ATTRIBUTES: {
+    readonly target: "_blank";
+    readonly rel: "noopener noreferrer";
+};
+/**
+ * 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 declare const DEFAULT_LINK_MATCHERS: LinkMatcher[];
+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 declare function RichTextEditorAutoLinkPlugin({ matchers, onChange, }: RichTextEditorAutoLinkPluginProps): import("react").JSX.Element;
+export declare namespace RichTextEditorAutoLinkPlugin {
+    var displayName: string;
+}
+//# sourceMappingURL=RichTextEditorAutoLinkPlugin.d.ts.map

package/dist/RichTextEditorAutoLinkPlugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RichTextEditorAutoLinkPlugin.d.ts","sourceRoot":"","sources":["../src/RichTextEditorAutoLinkPlugin.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EAGL,KAAK,WAAW,EACjB,MAAM,sCAAsC,CAAC;AAK9C;;;;GAIG;AACH,eAAO,MAAM,uBAAuB;;;CAG1B,CAAC;AAEX;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,EAAE,WAAW,EAc9C,CAAC;AAMF,MAAM,WAAW,iCAAiC;IAChD;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,WAAW,EAAE,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;CACjE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,4BAA4B,CAAC,EAC3C,QAAgC,EAChC,QAAQ,GACT,EAAE,iCAAiC,+BAQnC;yBAXe,4BAA4B"}

package/dist/RichTextEditorAutoLinkPlugin.js

@@ -0,0 +1,99 @@
+// 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 } from '@lexical/react/LexicalAutoLinkPlugin';
+import { $isCodeNode } from '@lexical/code';
+import { URL_MATCHER, EMAIL_MATCHER, sanitizeUrl } from "./linkUtils.js";
+
+/**
+ * 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.
+ */
+import { jsx as _jsx } from "react/jsx-runtime";
+export const NEW_TAB_LINK_ATTRIBUTES = {
+  target: '_blank',
+  rel: 'noopener noreferrer'
+};
+
+/**
+ * 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 = [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 = [$isCodeNode];
+/**
+ * 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
+}) {
+  return /*#__PURE__*/_jsx(AutoLinkPlugin, {
+    matchers: matchers,
+    onChange: onChange,
+    excludeParents: EXCLUDE_PARENTS
+  });
+}
+RichTextEditorAutoLinkPlugin.displayName = 'RichTextEditorAutoLinkPlugin';

package/dist/RichTextEditorToolbar.d.ts

@@ -0,0 +1,186 @@
+/**
+ * @file RichTextEditorToolbar.tsx
+ * @input Uses React, @lexical/react (composer context), @lexical/rich-text,
+ *   @lexical/selection, @lexical/list, @lexical/utils, and the lexical core
+ *   command constants, plus Astryx Toolbar / IconButton / Selector /
+ *   ToggleButton / Divider / Layout primitives, and the link popover in
+ *   ToolbarLinkPopover.
+ * @output Exports RichTextEditorToolbar (a compact formatting toolbar with a
+ *   RichText-owned 4px control gutter, a horizontally scrollable action row,
+ *   and a link popover anchored to its Link button) and
+ *   RichTextEditorToolbarProps, plus format and glyph helpers RichText shares
+ *   internally.
+ * @position @blue-patterns/richtext. Drop into RichTextEditor's `toolbar` slot to
+ *   add a flush top formatting toolbar. Themed via Astryx Toolbar, Selector,
+ *   IconButton, and ToggleButton, so it inherits the active theme. Base props
+ *   pass through to the Astryx Toolbar exactly as Toolbar places them
+ *   (spec:AST-061/DEC-8).
+ *
+ * SYNC: When modified, update:
+ * - /packages/richtext/src/index.ts (exports)
+ * - /packages/richtext/src/RichTextEditor.doc.mjs (usage notes)
+ * - /packages/richtext/src/RichTextEditor.test.tsx (tests)
+ * - /apps/storybook/stories/RichTextEditor.stories.tsx (WithToolbar story)
+ *
+ * NOTE: `lexical` and `@lexical/*` are OPTIONAL peer dependencies — install them
+ * to use this.
+ * Behavior mirrors the Lexical playground toolbar (selection sync + format
+ * commands); the UI is built from Astryx primitives so it matches the theme.
+ *
+ * ICONS: Each control resolves its glyph through the core icon registry under a
+ * stable `richtext:*` key (see {@link RICHTEXT_ICON_KEYS}) for the active
+ * theme, falling back to the bundled inline SVGs below — the library seam
+ * `getExtendedIcon` documents. A theme restyles any glyph by naming its key:
+ *   defineTheme({icons: {'richtext:bold': <MyBoldIcon />}});
+ * Undo and redo point backward and forward in time, so they mirror under RTL
+ * whichever glyph draws them.
+ */
+import { type ReactNode, type Ref } from 'react';
+import type { BaseProps } from '@blue-patterns/core';
+import { type TranslatorFn } from '@blue-patterns/core/i18n';
+import { type LexicalEditor, type NodeSelection, type RangeSelection } from 'lexical';
+/**
+ * Stable icon-registry keys for the toolbar's controls. A theme overrides any
+ * of these by key: `defineTheme({icons: {'richtext:bold': <MyIcon />}})`.
+ * Keys are namespaced (`richtext:*`) to avoid collisions with the core
+ * semantic icon set.
+ */
+export declare const RICHTEXT_ICON_KEYS: {
+    readonly bold: "richtext:bold";
+    readonly italic: "richtext:italic";
+    readonly underline: "richtext:underline";
+    readonly strikethrough: "richtext:strikethrough";
+    readonly code: "richtext:code";
+    readonly link: "richtext:link";
+    readonly paragraph: "richtext:paragraph";
+    readonly h1: "richtext:h1";
+    readonly h2: "richtext:h2";
+    readonly h3: "richtext:h3";
+    readonly quote: "richtext:quote";
+    readonly bullet: "richtext:bullet";
+    readonly number: "richtext:number";
+    readonly undo: "richtext:undo";
+    readonly redo: "richtext:redo";
+};
+/** The inline formats, in the order a toolbar offers them. */
+export declare const INLINE_FORMAT_ACTIONS: readonly [{
+    readonly format: "bold";
+    readonly icon: "bold";
+}, {
+    readonly format: "italic";
+    readonly icon: "italic";
+}, {
+    readonly format: "underline";
+    readonly icon: "underline";
+}, {
+    readonly format: "strikethrough";
+    readonly icon: "strikethrough";
+}, {
+    readonly format: "code";
+    readonly icon: "code";
+}];
+export type InlineFormat = (typeof INLINE_FORMAT_ACTIONS)[number]['format'];
+/** The inline formats' button labels. */
+export declare function inlineFormatLabels(t: TranslatorFn): Record<InlineFormat, string>;
+/**
+ * The inline formats a range or node selection carries, which their buttons
+ * show pressed. A selection of Markdown plugin nodes alone (a range around
+ * them, or a node selection from a click) shows their formats. Any other
+ * node selection, such as a rule, has none.
+ */
+export declare function $inlineFormatsOf(selection: RangeSelection | NodeSelection): Set<InlineFormat>;
+/** Toggles an inline format over the editor's selection. */
+export declare function formatSelection(editor: LexicalEditor, format: InlineFormat): void;
+export type ToolbarIconName = keyof typeof RICHTEXT_ICON_KEYS;
+/** The glyph resolver for the active theme, as the toolbars draw glyphs. */
+export declare function useToolbarIcon(): (name: ToolbarIconName) => ReactNode;
+export interface RichTextEditorToolbarProps extends BaseProps<HTMLDivElement> {
+    /**
+     * Ref to the toolbar's root element. Base props pass through to the
+     * underlying Astryx `Toolbar`: the ref, `className`, `style`, and `xstyle`
+     * reach its root, and `data-*`, other `aria-*` attributes, and DOM
+     * handlers reach the `role="toolbar"` element inside it. The toolbar names
+     * itself, so pass `label` rather than `aria-label`.
+     */
+    ref?: Ref<HTMLDivElement>;
+    /**
+     * Accessible label for the toolbar element.
+     * @default 'Text formatting', translated for the active locale
+     */
+    label?: string;
+    /**
+     * Which heading levels to expose in the block-format selector, in order.
+     * @default ['h1', 'h2', 'h3']
+     */
+    headingLevels?: ReadonlyArray<'h1' | 'h2' | 'h3'>;
+    /**
+     * Toolbar size. Cascades to formatting controls and coordinates the
+     * Toolbar's internal padding.
+     * @default 'sm'
+     */
+    size?: 'sm' | 'md' | 'lg';
+    /**
+     * Whether to show the insert/edit-link button. By default, pressing it (or
+     * Cmd/Ctrl+K in the editor) opens an Astryx Popover anchored to the button:
+     * one URL field, applied with Enter, with Remove when the selection is in a
+     * link. The popover is not modal. Escape or Cancel closes it and returns
+     * focus and the selection to the editor; a URL that cannot be linked shows
+     * an error under the field, which keeps focus. With a collapsed selection,
+     * applying inserts the entered URL as link text at the caret; with a
+     * non-empty selection it links the selected text.
+     *
+     * Requires `LinkNode` to be registered (it is, by default) — no extra setup.
+     * The entered URL is sanitized (see `sanitizeUrl`) so only
+     * http/https/mailto/tel links are written.
+     * @default true
+     */
+    hasLink?: boolean;
+    /**
+     * Called to obtain a URL when the link button is pressed on a non-link
+     * selection. Return the URL string to link, or `null`/`''` to cancel.
+     * Receives the currently selected text as a hint. When omitted, the built-in
+     * link popover is used. This synchronous override is retained
+     * for consumers that already provide their own URL UI.
+     */
+    promptForUrl?: (selectedText: string) => string | null | undefined;
+    /**
+     * Whether links created via the toolbar open in a new tab. When `true`
+     * (default), the created link carries `target="_blank"` and
+     * `rel="noopener noreferrer"` — written into the link node's data (so it
+     * serializes and round-trips), not patched onto the DOM. Set `false` to
+     * create same-tab links.
+     * @default true
+     */
+    hasNewTabLinks?: boolean;
+    /**
+     * Extra items rendered at the end of the toolbar (after a divider). Use this
+     * to compose product-specific controls (e.g. mentions, AI) alongside the
+     * default formatting buttons.
+     */
+    endContent?: ReactNode;
+}
+/**
+ * A composable formatting toolbar for {@link RichTextEditor}, built from Astryx
+ * `Toolbar` / `ToggleButton` primitives so it matches the active theme. Reads
+ * the current selection to keep the active states in sync and dispatches the
+ * standard Lexical formatting commands.
+ *
+ * Render it inside the editor's `toolbar` slot — it uses
+ * `useLexicalComposerContext()` to reach the editor, so it must live within the
+ * `LexicalComposer` the editor sets up.
+ *
+ * @example
+ * ```
+ * import {RichTextEditor, RichTextEditorToolbar} from '@blue-patterns/richtext';
+ *
+ * <RichTextEditor
+ *   label="Notes"
+ *   toolbar={<RichTextEditorToolbar />}
+ * />
+ * ```
+ */
+export declare function RichTextEditorToolbar({ label: labelFromProps, headingLevels, size, hasLink, promptForUrl, hasNewTabLinks, endContent, xstyle, ref, ...rest }: RichTextEditorToolbarProps): import("react").JSX.Element;
+export declare namespace RichTextEditorToolbar {
+    var displayName: string;
+}
+//# sourceMappingURL=RichTextEditorToolbar.d.ts.map

package/dist/RichTextEditorToolbar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RichTextEditorToolbar.d.ts","sourceRoot":"","sources":["../src/RichTextEditorToolbar.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,EAKL,KAAK,SAAS,EACd,KAAK,GAAG,EACT,MAAM,OAAO,CAAC;AAmBf,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,qBAAqB,CAAC;AAenD,OAAO,EAAgB,KAAK,YAAY,EAAC,MAAM,0BAA0B,CAAC;AAC1E,OAAO,EAYL,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,cAAc,EAGpB,MAAM,SAAS,CAAC;AAwEjB;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;CAgBrB,CAAC;AAEX,8DAA8D;AAC9D,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;EAMxB,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,CAAC;AAE5E,yCAAyC;AACzC,wBAAgB,kBAAkB,CAChC,CAAC,EAAE,YAAY,GACd,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAS9B;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,cAAc,GAAG,aAAa,GACxC,GAAG,CAAC,YAAY,CAAC,CAanB;AAED,4DAA4D;AAC5D,wBAAgB,eAAe,CAC7B,MAAM,EAAE,aAAa,EACrB,MAAM,EAAE,YAAY,GACnB,IAAI,CAEN;AA4MD,MAAM,MAAM,eAAe,GAAG,MAAM,OAAO,kBAAkB,CAAC;AAkB9D,4EAA4E;AAC5E,wBAAgB,cAAc,IAAI,CAAC,IAAI,EAAE,eAAe,KAAK,SAAS,CAGrE;AAaD,MAAM,WAAW,0BAA2B,SAAQ,SAAS,CAAC,cAAc,CAAC;IAC3E;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,GAAG,CAAC,cAAc,CAAC,CAAC;IAC1B;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC;IAClD;;;;OAIG;IACH,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;IAC1B;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IACnE;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;OAIG;IACH,UAAU,CAAC,EAAE,SAAS,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,qBAAqB,CAAC,EACpC,KAAK,EAAE,cAAc,EACrB,aAAkC,EAClC,IAAW,EACX,OAAc,EACd,YAAY,EACZ,cAAqB,EACrB,UAAU,EACV,MAAM,EACN,GAAG,EACH,GAAG,IAAI,EACR,EAAE,0BAA0B,+BAyR5B;yBApSe,qBAAqB"}