Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
39.8 KB
Raw Blame
// 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 @astryxdesign/richtext implementation; consumed by the package index.ts and
 *   re-exported from @astryxdesign/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 '@astryxdesign/core/theme/tokens.stylex';
import {sharedEditorTheme} from './editorTheme';
import {
  Field,
  inputWrapperStyles,
  inputStatusBorderStyles,
  inputStatusHoverShadowStyles,
  inputStatusFocusWithinStyles,
  type FieldStatusVariant,
} from '@astryxdesign/core/Field';
import type {BaseProps} from '@astryxdesign/core';
import {useInputStatusIcon} from '@astryxdesign/core/hooks';
import {VisuallyHidden} from '@astryxdesign/core/VisuallyHidden';
import {useTranslator} from '@astryxdesign/core/i18n';
import {
  isRenderable,
  mergeProps,
  themeProps,
  type SizeValue,
} from '@astryxdesign/core/utils';
import {useSize} from '@astryxdesign/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 './TableColumnFloorPlugin';
import {CodeBackspacePlugin} from './CodeBackspacePlugin';
import {CodeBlockHeaderPlugin} from './CodeBlockHeaderPlugin';
import {CodePastePlugin} from './CodePastePlugin';
import {CodeSyntaxPlugin} from './CodeSyntaxPlugin';
import {CodeTabPlugin} from './CodeTabPlugin';
import {MarkdownExtensionsPlugin} from './MarkdownExtensionsPlugin';
import type {RichTextMarkdownExtension} from './markdownExtensions';
import type {CodeLanguage} from '@astryxdesign/core/CodeBlock';
import {TaskCheckboxPlugin} from './TaskCheckboxPlugin';
import {DisabledLinkGuardPlugin} from './DisabledLinkGuardPlugin';
import {SelectAllScopePlugin} from './SelectAllScopePlugin';
import {ImageSourceCaretPlugin} from './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).
   * @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 `@astryxdesign/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 `@astryxdesign/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 '@astryxdesign/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: '@astryxdesign/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 />
              <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} />
              )}
              {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} />;
}