@blue-patterns/richtext 0.0.0-stage → 0.7.18

package/src/RichTextEditor.tsx

@@ -0,0 +1,1109 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file RichTextEditor.tsx
+ * @input Uses React, useId, a declared DOM boundary, Lexical (lexical + @lexical/react, composed through
+ *   LexicalExtensionComposer), Field, VisuallyHidden, useInputStatusIcon,
+ *   mergeProps, design tokens
+ * @output Exports an accessibly labelled RichTextEditor component with a flush
+ *   top toolbar slot, configurable editable-surface minimum height, and distinct
+ *   read-only and disabled states that follow prop changes, RichTextEditorProps,
+ *   RichTextEditorStatus, RichTextEditorStatusType, RichTextEditorSize
+ * @position @blue-patterns/richtext implementation; consumed by the package index.ts and
+ *   re-exported from @blue-patterns/richtext. Tested by RichTextEditor.test.tsx.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/richtext/src/RichTextEditor.doc.mjs (props table, features, implementation notes)
+ * - /packages/richtext/src/RichTextEditor.test.tsx (tests for new/changed behavior)
+ * - /packages/richtext/src/index.ts (exports if types change)
+ * - /apps/storybook/stories/RichTextEditor.stories.tsx (storybook stories)
+ *
+ * NOTE: `lexical` and `@lexical/*` are OPTIONAL peer dependencies — install them to
+ * use this component.
+ */
+
+import {
+  useEffect,
+  useId,
+  useImperativeHandle,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+  type Ref,
+} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {
+  colorVars,
+  spacingVars,
+  typographyVars,
+  typeScaleVars,
+} from '@blue-patterns/core/theme/tokens.stylex';
+import {sharedEditorTheme} from './editorTheme';
+import {
+  Field,
+  inputWrapperStyles,
+  inputStatusBorderStyles,
+  inputStatusHoverShadowStyles,
+  inputStatusFocusWithinStyles,
+  type FieldStatusVariant,
+} from '@blue-patterns/core/Field';
+import type {BaseProps} from '@blue-patterns/core';
+import {useInputStatusIcon} from '@blue-patterns/core/hooks';
+import {VisuallyHidden} from '@blue-patterns/core/VisuallyHidden';
+import {useTranslator} from '@blue-patterns/core/i18n';
+import {
+  isRenderable,
+  mergeProps,
+  themeProps,
+  type SizeValue,
+} from '@blue-patterns/core/utils';
+import {useSize} from '@blue-patterns/core/SizeContext';
+
+import {LexicalExtensionComposer} from '@lexical/react/LexicalExtensionComposer';
+import {useLexicalComposerContext} from '@lexical/react/LexicalComposerContext';
+import {RichTextPlugin} from '@lexical/react/LexicalRichTextPlugin';
+import {ContentEditable} from '@lexical/react/LexicalContentEditable';
+import {LexicalErrorBoundary} from '@lexical/react/LexicalErrorBoundary';
+import {HistoryPlugin} from '@lexical/react/LexicalHistoryPlugin';
+import {ListPlugin} from '@lexical/react/LexicalListPlugin';
+import {LinkPlugin} from '@lexical/react/LexicalLinkPlugin';
+import {TabIndentationPlugin} from '@lexical/react/LexicalTabIndentationPlugin';
+import {MarkdownShortcutPlugin} from '@lexical/react/LexicalMarkdownShortcutPlugin';
+import {OnChangePlugin} from '@lexical/react/LexicalOnChangePlugin';
+import {TablePlugin} from '@lexical/react/LexicalTablePlugin';
+import {HorizontalRuleExtension} from '@lexical/extension';
+import {TextSemanticsExtension} from './textSemantics';
+import {TableColumnFloorPlugin} from './internal/TableColumnFloorPlugin';
+import {TablePastePlugin} from './internal/TablePastePlugin';
+import {CodeBackspacePlugin} from './internal/CodeBackspacePlugin';
+import {CodeBlockHeaderPlugin} from './internal/CodeBlockHeaderPlugin';
+import {CodePastePlugin} from './internal/CodePastePlugin';
+import {CodeSyntaxPlugin} from './internal/CodeSyntaxPlugin';
+import {CodeTabPlugin} from './internal/CodeTabPlugin';
+import {MarkdownExtensionsPlugin} from './internal/MarkdownExtensionsPlugin';
+import type {RichTextMarkdownExtension} from './markdownExtensions';
+import type {CodeLanguage} from '@blue-patterns/core/CodeBlock';
+import {TaskCheckboxPlugin} from './internal/TaskCheckboxPlugin';
+import {ListItemShortcutsPlugin} from './internal/ListItemShortcutsPlugin';
+import {DisabledLinkGuardPlugin} from './internal/DisabledLinkGuardPlugin';
+import {SelectAllScopePlugin} from './internal/SelectAllScopePlugin';
+import {ImageSourceCaretPlugin} from './internal/ImageSourceCaretPlugin';
+import {type Transformer} from '@lexical/markdown';
+import {$generateHtmlFromNodes} from '@lexical/html';
+import {DEFAULT_NODES} from './editorNodes';
+import {$exportMarkdownKeepingSource} from './markdownSource';
+import {DEFAULT_TRANSFORMERS} from './markdownTable';
+import {
+  BLUR_COMMAND,
+  COMMAND_PRIORITY_LOW,
+  defineExtension,
+  KEY_DOWN_COMMAND,
+  KEY_ESCAPE_COMMAND,
+  KEY_TAB_COMMAND,
+  mergeRegister,
+  type AnyLexicalExtension,
+  type EditorState,
+  type Klass,
+  type LexicalEditor,
+  type LexicalNode,
+  type EditorThemeClasses,
+} from 'lexical';
+import {rendererManagedRootProps} from './privateAttributes/layerPortalBoundary.stylex';
+
+/**
+ * Serialized state for an empty editor: a root containing a single empty
+ * paragraph. Used by the imperative `clear()` handle.
+ *
+ * We deliberately reset the editor via `editor.setEditorState(...)` rather than
+ * an `editor.update(() => { $getRoot()... })` callback, because `$getRoot` /
+ * `$createParagraphNode` are *runtime value* imports from the top-level
+ * `lexical` package. In the sandbox's Next build a top-level `lexical` value
+ * import forces Babel to transpile lexical's raw `src/*.ts` (which uses
+ * `declare` class fields) and fails the build. `parseEditorState` /
+ * `setEditorState` are methods on the editor instance, so no top-level
+ * `lexical` value import is needed. Setting a fresh state still notifies update
+ * listeners, so `onChange` fires.
+ */
+const EMPTY_EDITOR_STATE_JSON = JSON.stringify({
+  root: {
+    children: [
+      {
+        children: [],
+        direction: null,
+        format: '',
+        indent: 0,
+        type: 'paragraph',
+        version: 1,
+      },
+    ],
+    direction: null,
+    format: '',
+    indent: 0,
+    type: 'root',
+    version: 1,
+  },
+});
+
+const styles = stylex.create({
+  wrapper: {
+    // Establish a new container boundary so Toolbar's Section does not escape
+    // padding inherited from an ancestor Section outside the editor field.
+    '--container-padding-inline-start': '0px',
+    '--container-padding-inline-end': '0px',
+    '--container-padding-block-start': '0px',
+    '--container-padding-block-end': '0px',
+    flexDirection: 'column',
+    alignItems: 'stretch',
+    gap: spacingVars['--spacing-0'],
+    paddingBlock: spacingVars['--spacing-0'],
+    paddingInline: spacingVars['--spacing-0'],
+    minHeight: 'auto',
+  },
+  editorBody: {
+    position: 'relative',
+    boxSizing: 'border-box',
+    width: '100%',
+    paddingBlock: spacingVars['--spacing-1'],
+    paddingInline: spacingVars['--spacing-2'],
+  },
+  editorBodyWithToolbar: {
+    borderTopWidth: 1,
+    borderTopStyle: 'solid',
+    borderTopColor: colorVars['--color-border'],
+  },
+  editorBodyWithStatus: {
+    // Reserve the same trailing space as TextArea: the normal text inset plus
+    // room for the 20px status icon and its gap.
+    paddingInlineEnd: `calc(${spacingVars['--spacing-2']} + ${spacingVars['--spacing-6']})`,
+  },
+  contentEditable: {
+    display: 'block',
+    width: '100%',
+    borderWidth: 0,
+    borderStyle: 'none',
+    padding: 0,
+    outline: 'none',
+    color: colorVars['--color-text-primary'],
+  },
+  placeholder: {
+    position: 'absolute',
+    top: spacingVars['--spacing-0'],
+    insetInlineStart: 0,
+    pointerEvents: 'none',
+    userSelect: 'none',
+    color: colorVars['--color-text-secondary'],
+  },
+  editorRoot: {
+    position: 'relative',
+    width: '100%',
+    // ContentEditable and Lexical's sibling placeholder inherit one shared
+    // text style. This keeps their leading and coarse-pointer sizing identical
+    // to TextInput/TextArea without duplicating placeholder typography. The
+    // 16px floor is iOS-only: iOS Safari zooms the page when a focused
+    // control sits under 16px, and only iOS WebKit implements
+    // -webkit-touch-callout to key the coarse-pointer floor to it.
+    fontFamily: typographyVars['--font-family-body'],
+    fontSize: {
+      default: typeScaleVars['--text-body-size'],
+      '@media (pointer: coarse)': {
+        '@supports (-webkit-touch-callout: none)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      },
+    },
+    lineHeight: typeScaleVars['--text-body-leading'],
+  },
+  statusIcon: {
+    position: 'absolute',
+    top: spacingVars['--spacing-2'],
+    insetInlineEnd: spacingVars['--spacing-2'],
+    zIndex: 1,
+    display: 'flex',
+    alignItems: 'center',
+  },
+  disabled: {
+    // Per #5335: `default`, not `not-allowed`. A disabled control already
+    // carries its own visual treatment, and `not-allowed` is unpaintable on
+    // the part of the library sealed behind `pointer-events: none`, so the
+    // library cannot promise it consistently.
+    cursor: {
+      default: 'default',
+      ':is(:disabled,[aria-disabled="true"])': 'default',
+    },
+  },
+  counter: {
+    display: 'flex',
+    justifyContent: 'flex-end',
+    marginTop: spacingVars['--spacing-1'],
+    fontFamily: typographyVars['--font-family-body'],
+    fontSize: typeScaleVars['--text-supporting-size'],
+    color: colorVars['--color-text-secondary'],
+  },
+  counterError: {
+    color: colorVars['--color-text-error'],
+  },
+});
+
+const dynamicStyles = stylex.create({
+  contentEditableMinHeight: (minHeight: SizeValue) => ({minHeight}),
+});
+
+const editorBodySizeStyles = stylex.create({
+  // Only `lg` adds block padding; `sm` and `md` take the base body spacing.
+  // An empty entry each would read as deliberate size-specific styling.
+  lg: {
+    paddingBlock: spacingVars['--spacing-2'],
+  },
+});
+
+/**
+ * Fraction of `maxLength` at which the character counter begins announcing
+ * remaining/over-limit characters to screen readers. Matches TextArea.
+ */
+const COUNTER_WARNING_THRESHOLD = 0.8;
+
+export type RichTextEditorStatusType = 'warning' | 'error' | 'success';
+
+export type RichTextEditorSize = 'sm' | 'md' | 'lg';
+
+export interface RichTextEditorStatus {
+  /** The type of status to display. */
+  type: RichTextEditorStatusType;
+  /** Optional message to display below the editor. */
+  message?: string;
+}
+
+/**
+ * Imperative handle exposed via `ref`. Lets callers focus, clear, and read the
+ * editor without wiring a custom plugin. Available after mount.
+ */
+export interface RichTextEditorRef {
+  /**
+   * Move focus into the editor's editable surface. No-op when the editor is
+   * read-only or disabled.
+   */
+  focus: () => void;
+  /**
+   * Remove all content, resetting the editor to a single empty paragraph.
+   * No-op when the editor is read-only or disabled.
+   */
+  clear: () => void;
+  /** Read the current `EditorState`. Serialize with `.toJSON()` to persist. */
+  getEditorState: () => EditorState;
+  /**
+   * Serialize the current content to a Markdown string, using the same
+   * `transformers` the editor is configured with (so custom transformers
+   * layered in via the `transformers` prop are honored). Content imported
+   * with `markdownToEditorStateJSON` comes back as written: blocks nobody
+   * changed byte for byte, and only edited or added blocks in canonical
+   * Markdown.
+   */
+  getMarkdown: () => string;
+  /**
+   * Serialize the current content to an HTML string via
+   * `$generateHtmlFromNodes`. Requires a DOM (available in the browser and in
+   * jsdom-based tests). Useful for copy/paste, email, or non-Lexical consumers.
+   */
+  getHTML: () => string;
+  /**
+   * Access the underlying `LexicalEditor` instance for advanced use cases
+   * (custom commands, listeners, node transforms).
+   */
+  getEditor: () => LexicalEditor;
+}
+
+export interface RichTextEditorProps extends Omit<
+  BaseProps,
+  'onChange' | 'defaultValue'
+> {
+  /**
+   * Imperative handle for callers that manage the editor from outside. In
+   * React 19 `ref` is an ordinary prop, so it is declared here rather than
+   * supplied by a `forwardRef` wrapper.
+   */
+  ref?: Ref<RichTextEditorRef>;
+  /** Label text for the editor (always rendered for accessibility). */
+  label: string;
+  /**
+   * Whether to visually hide the label (still accessible to screen readers).
+   * @default false
+   */
+  isLabelHidden?: boolean;
+  /** Description text displayed between the label and editor. */
+  description?: string;
+  /**
+   * Whether the field is optional. Mutually exclusive with isRequired.
+   * @default false
+   */
+  isOptional?: boolean;
+  /**
+   * Whether the field is required. Mutually exclusive with isOptional.
+   * @default false
+   */
+  isRequired?: boolean;
+  /**
+   * Initial serialized editor state (a JSON string produced by
+   * `JSON.stringify(editorState.toJSON())`), used to seed the editor on mount.
+   * The editor is uncontrolled: this is read once.
+   */
+  defaultValue?: string;
+  /**
+   * Callback fired when the editor content changes. Receives the current
+   * `EditorState` and the `LexicalEditor` instance. Serialize with
+   * `editorState.toJSON()` for persistence.
+   */
+  onChange?: (editorState: EditorState, editor: LexicalEditor) => void;
+  /** Placeholder text shown when the editor is empty. */
+  placeholder?: string;
+  /**
+   * Whether the editor is read-only (non-editable). The content stays at full
+   * opacity, in the tab order, and announced as read-only, so people can still
+   * reach, read, and copy it. Takes effect when changed after mount.
+   * @default false
+   */
+  isReadOnly?: boolean;
+  /**
+   * Whether the editor is disabled: non-editable, dimmed, out of the tab
+   * order, and announced as disabled. Its links do not navigate and are not
+   * tab stops. Wins when `isReadOnly` is also set.
+   * Takes effect when changed after mount.
+   * @default false
+   */
+  isDisabled?: boolean;
+  /**
+   * Status indicator. When set, displays a colored border. If message is
+   * provided, displays a message box below the editor.
+   */
+  status?: RichTextEditorStatus;
+  /**
+   * How the status message is placed relative to the editor.
+   * - 'attached': message overlaps directly below the editor and the status
+   *   icon remains inside the editing surface
+   * - 'detached': message floats below with its own leading status icon
+   * - 'tooltip': no message box; the in-editor status icon becomes a focusable
+   *   info-tip button that reveals the message
+   * @default 'attached'
+   */
+  statusVariant?: FieldStatusVariant | 'tooltip';
+  /**
+   * Width of the field. Numbers are treated as pixels, strings are used as-is
+   * (e.g. `'100%'`).
+   */
+  width?: SizeValue;
+  /**
+   * Minimum height of the editable content surface. Numbers are treated as
+   * pixels, strings are used as CSS lengths.
+   * @default '4.5rem'
+   */
+  minHeight?: SizeValue;
+  /** Tooltip text to display in an info icon at the end of the label. */
+  labelTooltip?: string;
+  /**
+   * The size of the editor, affecting internal padding.
+   * @default 'md'
+   */
+  size?: RichTextEditorSize;
+  /**
+   * Additional Lexical nodes to register beyond the default OSS set
+   * (Heading, Quote, List, Link, Code). Use this extension point to plug in
+   * custom nodes (e.g. mentions, images) without forking the editor.
+   */
+  nodes?: ReadonlyArray<Klass<LexicalNode>>;
+  /**
+   * Toolbar content rendered edge-to-edge at the top of the field, before the
+   * padded editing surface. Pass `<RichTextEditorToolbar />` here so the
+   * toolbar stays inside the Lexical composer while retaining correct visual
+   * and keyboard order.
+   */
+  toolbar?: ReactNode;
+  /**
+   * Additional Lexical plugins to render inside the composer. Use this to
+   * compose extra behaviour (mentions, autolink, etc.) on top of the base
+   * editor. Plugins receive the editor via `useLexicalComposerContext()`.
+   */
+  plugins?: ReactNode;
+  /**
+   * Whether to enable Markdown shortcut typing (e.g. `# ` for a heading,
+   * `- ` for a list). Uses the `transformers` prop (defaults to the standard
+   * `@lexical/markdown` transformers plus GFM tables). At the start of a list
+   * item, `- `, `1. `, or `[ ] ` switches its list between bullets, numbers,
+   * and tasks, and `# ` or `> ` takes a top-level item out of its list as a
+   * heading or a quote.
+   * @default true
+   */
+  hasMarkdownShortcuts?: boolean;
+  /**
+   * Markdown transformers — the single source of truth for markdown behaviour.
+   * Defaults to the standard `@lexical/markdown` `TRANSFORMERS` plus GFM
+   * tables. A custom array replaces the default, tables included.
+   *
+   * The same array drives all three markdown operations in Lexical (see the
+   * lexical-playground reference, where one `PLAYGROUND_TRANSFORMERS` array
+   * feeds each):
+   *  - shortcut typing        — `registerMarkdownShortcuts` (wired here today)
+   *  - markdown -> state       — `$convertFromMarkdownString` (future import API)
+   *  - state -> markdown       — `$convertToMarkdownString` (future `getMarkdown`)
+   *
+   * Pass a custom array to support additional node types (e.g. custom
+   * transformers layered in via the `nodes` extension point) consistently
+   * across all three. Shortcut typing is only applied when
+   * `hasMarkdownShortcuts` is true; the array is still the intended input for
+   * the serialization APIs added in later phases.
+   */
+  transformers?: ReadonlyArray<Transformer>;
+  /**
+   * Markdown plugins whose nodes this surface draws, each adopted with
+   * `createRichTextExtension` (spec:AST-064). A plugin node renders exactly as
+   * core `Markdown` renders it, and one whose plugin is not given here shows
+   * its source. Pass the extensions the content was converted with. Create
+   * them in a client module: they hold the plugins' functions, so they are not
+   * serializable props.
+   */
+  markdownExtensions?: ReadonlyArray<RichTextMarkdownExtension>;
+  /**
+   * CodeBlock language values a fence may name, each imported on its own,
+   * such as `graphql` from `@blue-patterns/core/CodeBlock/languages/graphql`,
+   * or made with `createCodeLanguage`. Pass the same list as `Markdown`'s
+   * `codeLanguages`, so reading and editing paint and label the same
+   * languages (spec:AST-061).
+   */
+  codeLanguages?: ReadonlyArray<CodeLanguage>;
+  /** Whether to automatically focus the editor on mount. @default false */
+  hasAutoFocus?: boolean;
+  /**
+   * Screen-reader hint describing how to move focus out of the editor, since
+   * Tab is bound to indentation (press Escape, then Tab). Rendered visually
+   * hidden and referenced from the editor's `aria-describedby`. Override it
+   * to change the text, or pass an empty string to omit the hint entirely
+   * (e.g. when the host app provides its own instructions).
+   * @default 'Press Escape then Tab to move focus out of the editor.', translated for the active locale
+   */
+  tabEscapeHint?: string;
+  /**
+   * Maximum number of characters. When set, a character counter
+   * (current/max) is displayed below the editor. Like TextArea, this does
+   * NOT enforce the limit natively — the counter shows error styling when the
+   * plain-text length exceeds the limit. Count is the editor's plain-text
+   * content length.
+   */
+  maxLength?: number;
+  /**
+   * The Lexical composer namespace, used for editor identity.
+   * @default 'astryx-editor'
+   */
+  namespace?: string;
+}
+
+/**
+ * A WYSIWYG rich-text editor built on Lexical, styled with Astryx design
+ * tokens. Ships from `@blue-patterns/richtext`. `lexical` and `@lexical/*` are
+ * optional peer dependencies — install them to use this component.
+ *
+ * The editor is intentionally minimal and extensible: pass `toolbar`, `nodes`,
+ * and `plugins` to layer richer behaviour (formatting, mentions, hover cards)
+ * on top without forking.
+ *
+ * The forwarded `RichTextEditorRef` exposes imperative `focus()` and `clear()`
+ * methods for callers that manage the editor from outside.
+ *
+ * @example
+ * ```
+ * import {RichTextEditor, type RichTextEditorRef} from '@blue-patterns/richtext';
+ * const ref = useRef<RichTextEditorRef>(null);
+ * <RichTextEditor
+ *   ref={ref}
+ *   label="Notes"
+ *   placeholder="Write something..."
+ *   onChange={state => save(JSON.stringify(state.toJSON()))}
+ * />
+ * ```
+ */
+export const RichTextEditor = function RichTextEditor({
+  label,
+  isLabelHidden = false,
+  description,
+  isOptional = false,
+  isRequired = false,
+  defaultValue,
+  onChange,
+  placeholder,
+  isReadOnly = false,
+  isDisabled = false,
+  status,
+  statusVariant = 'attached',
+  width,
+  minHeight = '4.5rem',
+  labelTooltip,
+  size: sizeProp,
+  nodes,
+  toolbar,
+  plugins,
+  hasMarkdownShortcuts = true,
+  transformers = DEFAULT_TRANSFORMERS,
+  markdownExtensions,
+  codeLanguages,
+  hasAutoFocus = false,
+  tabEscapeHint: tabEscapeHintFromProps,
+  maxLength,
+  namespace = 'astryx-editor',
+  xstyle,
+  className,
+  style,
+  ref,
+  ...rest
+}: RichTextEditorProps) {
+  const size = useSize(sizeProp, 'md');
+  const t = useTranslator();
+  const tabEscapeHint =
+    tabEscapeHintFromProps ?? t('@astryx.richTextEditor.tabEscapeHint');
+  const inputID = useId();
+  const labelID = useId();
+  const descriptionID = useId();
+  const statusMessageID = useId();
+  const placeholderID = useId();
+  const counterID = useId();
+  const tabEscapeHintID = useId();
+
+  // Plain-text character count, tracked from inside the composer via
+  // CharCountPlugin. Only used when maxLength is set.
+  const [charCount, setCharCount] = useState(0);
+
+  // Theme is stable per render; build once.
+  const themeRef = useRef<EditorThemeClasses | null>(null);
+  if (themeRef.current === null) {
+    themeRef.current = sharedEditorTheme();
+  }
+
+  const editable = !isReadOnly && !isDisabled;
+
+  // Stabilize the transformers array so MarkdownShortcutPlugin doesn't
+  // re-register on every render. `[...transformers]` would allocate a new
+  // array each time; memoize on the prop identity instead. (React Compiler
+  // isn't running the transform in this repo, so this isn't auto-memoized.)
+  const markdownTransformers = useMemo(() => [...transformers], [transformers]);
+
+  // The extension replaces LexicalComposer's `initialConfig`: it carries the
+  // same editor configuration (namespace, theme, nodes, editability, initial
+  // state) in the shape LexicalBuilder consumes.
+  //
+  // LexicalExtensionComposer re-creates the editor whenever the extension's
+  // identity changes, whereas LexicalComposer read `initialConfig` exactly once
+  // on mount. Build it on first render and keep it, so the editor's lifetime —
+  // and the content it holds — is unaffected by later renders (a consumer
+  // passing an inline `nodes={[...]}` array would otherwise blow away the
+  // editor's content on every render).
+  const extensionRef = useRef<AnyLexicalExtension | null>(null);
+  if (extensionRef.current === null) {
+    extensionRef.current = defineExtension({
+      name: '@blue-patterns/richtext/RichTextEditor',
+      namespace,
+      theme: themeRef.current,
+      editable,
+      nodes: nodes ? [...DEFAULT_NODES, ...nodes] : [...DEFAULT_NODES],
+      // Horizontal rules select on click and show their selection; struck
+      // text is a deletion.
+      dependencies: [HorizontalRuleExtension, TextSemanticsExtension],
+      // `undefined` (not `null`) leaves Lexical's default initializer in place,
+      // which seeds the empty document with one paragraph — what
+      // LexicalComposer did when no `editorState` was given. `null` would mean
+      // "start from a genuinely empty root".
+      $initialEditorState: defaultValue ?? undefined,
+      onError(error: Error) {
+        // Surface errors to the host app rather than swallowing them.
+        throw error;
+      },
+    });
+  }
+
+  const hasTabEscapeHint = editable && tabEscapeHint !== '';
+  const hasToolbar = isRenderable(toolbar);
+
+  const {statusIcon, describedBy: statusTooltipDescribedBy} =
+    useInputStatusIcon({
+      status,
+      statusVariant,
+    });
+
+  const ariaDescribedBy =
+    [
+      description ? descriptionID : null,
+      statusVariant !== 'tooltip' && status?.message ? statusMessageID : null,
+      // Tooltip status renders no FieldStatus message box. Reference the
+      // tooltip layer so assistive technology still receives the message.
+      statusTooltipDescribedBy,
+      placeholder ? placeholderID : null,
+      maxLength != null ? counterID : null,
+      hasTabEscapeHint ? tabEscapeHintID : null,
+    ]
+      .filter(Boolean)
+      .join(' ') || undefined;
+
+  return (
+    <Field
+      label={label}
+      isLabelHidden={isLabelHidden}
+      description={description}
+      inputID={inputID}
+      labelID={labelID}
+      descriptionID={description ? descriptionID : undefined}
+      isOptional={isOptional}
+      isRequired={isRequired}
+      isDisabled={isDisabled}
+      status={
+        status
+          ? {
+              type: status.type,
+              message: status.message,
+              messageID: status.message ? statusMessageID : undefined,
+            }
+          : undefined
+      }
+      statusVariant={statusVariant}
+      labelTooltip={labelTooltip}
+      width={width}>
+      <div
+        {...mergeProps(
+          themeProps('rich-text-editor', {
+            size,
+            status: status?.type ?? null,
+          }),
+          stylex.props(
+            inputWrapperStyles.base,
+            inputWrapperStyles.textField,
+            styles.wrapper,
+            // Only disabled is dimmed, matching TextArea: a read-only editor
+            // keeps full-opacity text and stays keyboard-reachable.
+            isDisabled && inputWrapperStyles.disabled,
+            isDisabled && styles.disabled,
+            status && inputStatusBorderStyles[status.type],
+            status &&
+              !isDisabled &&
+              !isReadOnly &&
+              inputStatusHoverShadowStyles[status.type],
+            status && inputStatusFocusWithinStyles[status.type],
+            xstyle,
+          ),
+          className,
+          style,
+        )}>
+        <LexicalExtensionComposer
+          extension={extensionRef.current}
+          contentEditable={null}>
+          {hasToolbar ? toolbar : null}
+          <div
+            {...stylex.props(
+              styles.editorBody,
+              hasToolbar && styles.editorBodyWithToolbar,
+              !!statusIcon && styles.editorBodyWithStatus,
+              size === 'lg' && editorBodySizeStyles.lg,
+            )}>
+            <div {...stylex.props(styles.editorRoot)} dir={rest.dir}>
+              <RichTextPlugin
+                contentEditable={
+                  <EditorContentEditable
+                    id={inputID}
+                    ariaLabel={isLabelHidden ? label : undefined}
+                    ariaLabelledBy={isLabelHidden ? undefined : labelID}
+                    ariaDescribedBy={ariaDescribedBy}
+                    ariaRequired={isRequired && !isOptional}
+                    ariaInvalid={status?.type === 'error'}
+                    isReadOnly={isReadOnly}
+                    isDisabled={isDisabled}
+                    placeholderText={placeholder}
+                    placeholderID={placeholderID}
+                    minHeight={minHeight}
+                    rest={rest}
+                  />
+                }
+                placeholder={null}
+                ErrorBoundary={LexicalErrorBoundary}
+              />
+              <HistoryPlugin />
+              <ListPlugin />
+              <TaskCheckboxPlugin isReadOnly={isReadOnly || isDisabled} />
+              <LinkPlugin />
+              <DisabledLinkGuardPlugin isDisabled={isDisabled} />
+              {/* Tab keeps its editor meaning inside a table (indent, and
+                  Escape then Tab to leave the editor); arrow keys move
+                  between cells. GFM tables have no merged cells or cell
+                  colors, and a wide table scrolls inside its own wrapper. */}
+              <TablePlugin
+                hasCellMerge={false}
+                hasCellBackgroundColor={false}
+                hasTabHandler={false}
+                hasHorizontalScroll
+              />
+              <TableColumnFloorPlugin />
+              <TablePastePlugin />
+              <CodeBlockHeaderPlugin codeLanguages={codeLanguages} />
+              <CodeSyntaxPlugin codeLanguages={codeLanguages} />
+              {/* Backspace at the very start of a code block makes it a
+                  paragraph, instead of merging it into the block above. */}
+              <CodeBackspacePlugin />
+              <CodePastePlugin />
+              {markdownExtensions != null && markdownExtensions.length > 0 ? (
+                <MarkdownExtensionsPlugin
+                  extensions={markdownExtensions}
+                  transformers={markdownTransformers}
+                />
+              ) : null}
+              {/* In a code block, Tab indents the lines the selection
+                  touches instead of inserting a tab character. */}
+              <CodeTabPlugin />
+              <TabIndentationPlugin />
+              <TabFocusEscapePlugin />
+              <SelectAllScopePlugin />
+              <ImageSourceCaretPlugin />
+              {hasMarkdownShortcuts && (
+                <MarkdownShortcutPlugin transformers={markdownTransformers} />
+              )}
+              {hasMarkdownShortcuts && (
+                <ListItemShortcutsPlugin transformers={markdownTransformers} />
+              )}
+              {hasAutoFocus && <AutoFocusOnMount />}
+              {onChange && (
+                <OnChangePlugin
+                  onChange={onChange}
+                  ignoreHistoryMergeTagChange
+                  ignoreSelectionChange
+                />
+              )}
+              {plugins}
+              <EditorRefBridge
+                editorRef={ref}
+                editable={editable}
+                transformers={markdownTransformers}
+              />
+              {maxLength != null && (
+                <CharCountPlugin onCountChange={setCharCount} />
+              )}
+            </div>
+            {statusIcon && (
+              <div {...stylex.props(styles.statusIcon)}>{statusIcon}</div>
+            )}
+          </div>
+        </LexicalExtensionComposer>
+        {hasTabEscapeHint && (
+          <VisuallyHidden id={tabEscapeHintID}>{tabEscapeHint}</VisuallyHidden>
+        )}
+      </div>
+      {/* eslint-disable-next-line @astryx/no-nullish-jsx-guard -- `maxLength` is a number; 0 still shows its counter */}
+      {maxLength != null && (
+        <div
+          id={counterID}
+          {...stylex.props(
+            styles.counter,
+            charCount > maxLength && styles.counterError,
+          )}>
+          {charCount}/{maxLength}
+          <VisuallyHidden aria-live="polite">
+            {charCount >= maxLength * COUNTER_WARNING_THRESHOLD
+              ? charCount > maxLength
+                ? t('@astryx.textArea.charactersOverLimit', {
+                    count: charCount - maxLength,
+                  })
+                : t('@astryx.textArea.charactersRemaining', {
+                    count: maxLength - charCount,
+                  })
+              : ''}
+          </VisuallyHidden>
+        </div>
+      )}
+    </Field>
+  );
+};
+
+// Keeps the editor inside `@astryx/require-baseprops-passthrough`, which only
+// checks components that assign a top-level `displayName`. Without it, a
+// dropped `className`, `style` or `xstyle` on the root stops warning.
+RichTextEditor.displayName = 'RichTextEditor';
+
+/**
+ * Keys that must not cancel an armed Tab escape: Escape (arming again),
+ * Tab (the escape itself) and bare modifier presses — the Shift keydown that
+ * precedes Shift+Tab must not disarm, or Escape → Shift+Tab could never
+ * escape backwards.
+ */
+const ESCAPE_REARM_EXEMPT_KEYS = new Set([
+  'Escape',
+  'Tab',
+  'Shift',
+  'Control',
+  'Alt',
+  'Meta',
+]);
+
+/**
+ * WCAG 2.1.2 (No Keyboard Trap) escape for TabIndentationPlugin.
+ *
+ * TabIndentationPlugin rebinds Tab to indent/outdent, which would otherwise
+ * trap keyboard focus inside the editor. This plugin restores an exit: after
+ * Escape is pressed, the next Tab (or Shift+Tab) performs native focus
+ * movement instead of indenting; pressing any other non-modifier key — or
+ * leaving the editor — re-arms indentation.
+ *
+ * Mechanics: TabIndentationPlugin handles KEY_TAB_COMMAND at
+ * COMMAND_PRIORITY_EDITOR (0), the lowest priority, and Lexical runs command
+ * listeners from the highest priority down, stopping at the first one that
+ * returns true. Registering at COMMAND_PRIORITY_LOW (1) therefore runs first;
+ * when the escape is armed we return true WITHOUT calling
+ * `event.preventDefault()`, so the indentation handlers (TabIndentationPlugin,
+ * and CodeTabPlugin at the front of the same priority) never see the event
+ * and the browser performs its default Tab focus navigation.
+ */
+function TabFocusEscapePlugin(): null {
+  const [editor] = useLexicalComposerContext();
+  useEffect(() => {
+    let escapeArmed = false;
+    return mergeRegister(
+      editor.registerCommand<KeyboardEvent>(
+        KEY_ESCAPE_COMMAND,
+        () => {
+          escapeArmed = true;
+          // Consumed: this supersedes @lexical/rich-text's default Escape
+          // handler (COMMAND_PRIORITY_EDITOR), which blurs the editor and
+          // drops focus on the document body — disorienting, and it would
+          // immediately disarm via BLUR_COMMAND below. Consumer plugins that
+          // handle Escape (e.g. to close a popover) register at a higher
+          // priority and still run first.
+          return true;
+        },
+        COMMAND_PRIORITY_LOW,
+      ),
+      editor.registerCommand<KeyboardEvent>(
+        KEY_TAB_COMMAND,
+        () => {
+          if (!escapeArmed) {
+            return false;
+          }
+          escapeArmed = false;
+          // Consume the command (blocks indentation) but leave the event's
+          // default alone so focus moves natively.
+          return true;
+        },
+        COMMAND_PRIORITY_LOW,
+      ),
+      editor.registerCommand<KeyboardEvent>(
+        KEY_DOWN_COMMAND,
+        event => {
+          if (escapeArmed && !ESCAPE_REARM_EXEMPT_KEYS.has(event.key)) {
+            escapeArmed = false;
+          }
+          return false;
+        },
+        COMMAND_PRIORITY_LOW,
+      ),
+      editor.registerCommand(
+        BLUR_COMMAND,
+        () => {
+          escapeArmed = false;
+          return false;
+        },
+        COMMAND_PRIORITY_LOW,
+      ),
+    );
+  }, [editor]);
+  return null;
+}
+
+/**
+ * Focuses the editor on mount. Split into its own plugin so it runs inside the
+ * composer context.
+ */
+function AutoFocusOnMount(): null {
+  const [editor] = useLexicalComposerContext();
+  useEffect(() => {
+    editor.focus();
+  }, [editor]);
+  return null;
+}
+
+/**
+ * Wires the imperative `RichTextEditorRef` handle. Split into its own plugin so
+ * it runs inside the composer context and can reach the `LexicalEditor` via
+ * `useLexicalComposerContext()`. Renders nothing.
+ *
+ * `focus()` and `clear()` are gated on `editable` so a read-only or disabled
+ * editor cannot be mutated or focused through the imperative handle — matching
+ * the behaviour of the editable surface itself.
+ */
+function EditorRefBridge({
+  editorRef,
+  editable,
+  transformers,
+}: {
+  // Optional, matching the public `ref` prop: with `forwardRef` gone, React
+  // no longer supplies `null` when the caller passes nothing.
+  editorRef: Ref<RichTextEditorRef> | undefined;
+  editable: boolean;
+  transformers: Array<Transformer>;
+}): null {
+  const [editor] = useLexicalComposerContext();
+
+  // The extension applies `editable` once, when the composer builds the
+  // editor, so a later isReadOnly/isDisabled change would leave
+  // contenteditable at its mount value while the wrapper styling and ARIA
+  // follow the props. Sync the editor on a prop change only: the mount value
+  // is already applied, and this bridge renders after `plugins`, so
+  // re-asserting it on mount would undo a plugin that set editability during
+  // its own mount.
+  const syncedEditableRef = useRef(editable);
+  useEffect(() => {
+    if (syncedEditableRef.current === editable) {
+      return;
+    }
+    syncedEditableRef.current = editable;
+    editor.setEditable(editable);
+  }, [editor, editable]);
+
+  useImperativeHandle(
+    editorRef,
+    () => ({
+      focus: () => {
+        if (!editable) {
+          return;
+        }
+        editor.focus();
+      },
+      clear: () => {
+        if (!editable) {
+          return;
+        }
+        // Reset to a single empty paragraph via a fresh EditorState. Uses the
+        // editor instance's own parse/set methods so we avoid a top-level
+        // `lexical` value import (see EMPTY_EDITOR_STATE_JSON). This still
+        // notifies update listeners, so `onChange` fires.
+        editor.setEditorState(editor.parseEditorState(EMPTY_EDITOR_STATE_JSON));
+      },
+      getEditorState: () => editor.getEditorState(),
+      getMarkdown: () =>
+        // Untouched blocks export exactly as imported and changed blocks in
+        // canonical form (spec:AST-062). Honors the same transformers the
+        // editor uses for shortcuts, so custom transformers round-trip. Reads
+        // the state without changing it.
+        editor
+          .getEditorState()
+          .read(() => $exportMarkdownKeepingSource(transformers)),
+      getHTML: () =>
+        // $generateHtmlFromNodes serializes the whole document (null selection)
+        // to HTML; must run in a read context and requires a DOM.
+        // `@lexical/html` is a subpackage (built dist) — safe.
+        editor
+          .getEditorState()
+          .read(() => $generateHtmlFromNodes(editor, null)),
+      getEditor: () => editor,
+    }),
+    [editor, editable, transformers],
+  );
+  return null;
+}
+
+/**
+ * Tracks the editor's plain-text length and reports it to the host component.
+ * Split into its own plugin so it runs inside the composer context and can
+ * read the editor state via `useLexicalComposerContext()`. Renders nothing.
+ */
+function CharCountPlugin({
+  onCountChange,
+}: {
+  onCountChange: (count: number) => void;
+}): null {
+  const [editor] = useLexicalComposerContext();
+  useEffect(() => {
+    // Report the initial count (e.g. seeded via defaultValue) from the mounted
+    // root element's text, then track changes via registerTextContentListener,
+    // which hands us the plain-text content directly.
+    //
+    // We deliberately avoid importing `$getRoot` from the top-level `lexical`
+    // package: that is a *runtime value* import, and in the sandbox's Next
+    // build it forces Babel to transpile lexical's raw `src/*.ts` (which uses
+    // `declare` class fields) and fails. Both APIs used here are methods on the
+    // editor instance, so no top-level `lexical` value import is needed.
+    onCountChange(editor.getRootElement()?.textContent?.length ?? 0);
+    return editor.registerTextContentListener(textContent => {
+      onCountChange(textContent.length);
+    });
+  }, [editor, onCountChange]);
+  return null;
+}
+
+/**
+ * Renders the Lexical ContentEditable. Split out so the placeholder
+ * discriminated union (`placeholder` + `aria-placeholder` present together, or
+ * neither) is satisfied by two concrete branches rather than a spread.
+ */
+function EditorContentEditable({
+  id,
+  ariaLabel,
+  ariaLabelledBy,
+  ariaDescribedBy,
+  ariaRequired,
+  ariaInvalid,
+  isReadOnly,
+  isDisabled,
+  placeholderText,
+  placeholderID,
+  minHeight,
+  rest,
+}: {
+  id: string;
+  ariaLabel?: string;
+  ariaLabelledBy?: string;
+  ariaDescribedBy?: string;
+  ariaRequired: boolean;
+  ariaInvalid: boolean;
+  isReadOnly: boolean;
+  isDisabled: boolean;
+  placeholderText?: string;
+  placeholderID: string;
+  minHeight: SizeValue;
+  rest: Record<string, unknown>;
+}) {
+  const shared = {
+    id,
+    role: 'textbox' as const,
+    'aria-multiline': 'true' as const,
+    'aria-label': ariaLabel,
+    'aria-labelledby': ariaLabelledBy,
+    'aria-describedby': ariaDescribedBy,
+    'aria-required': ariaRequired ? ('true' as const) : undefined,
+    'aria-invalid': ariaInvalid ? ('true' as const) : undefined,
+    // Lexical announces every non-editable surface as aria-readonly and
+    // leaves it out of the tab order. Split the two states: read-only stays
+    // reachable and is announced read-only; disabled is announced disabled
+    // instead. These keys land after Lexical's computed attributes, so the
+    // disabled branch's explicit `undefined` removes the wrong read-only
+    // announcement. With neither prop set no keys are passed, so a plugin
+    // that drives editor.setEditable keeps Lexical's own aria-readonly.
+    ...(isDisabled
+      ? {'aria-disabled': 'true' as const, 'aria-readonly': undefined}
+      : isReadOnly
+        ? {tabIndex: 0, 'aria-readonly': 'true' as const}
+        : null),
+    ...stylex.props(
+      styles.contentEditable,
+      dynamicStyles.contentEditableMinHeight(minHeight),
+    ),
+    ...rest,
+    // Lexical reconciles this DOM, so Layer keeps corrective portals out.
+    ...rendererManagedRootProps,
+  };
+  if (placeholderText) {
+    return (
+      <ContentEditable
+        {...shared}
+        aria-placeholder={placeholderText}
+        placeholder={() => (
+          <div
+            id={placeholderID}
+            aria-hidden="true"
+            {...stylex.props(styles.placeholder)}>
+            {placeholderText}
+          </div>
+        )}
+      />
+    );
+  }
+  return <ContentEditable {...shared} />;
+}