Rich Text Editor

1/** Matches an absolute web address, an email or a phone link. */
2const ABSOLUTE_HREF = /^(https?:\/\/\S+|mailto:\S+|tel:\S+)$/i;
3
4/** Matches a path on the current site: a single leading slash, never `//host`. */
5const SITE_PATH_HREF = /^\/(?!\/)\S*$/;
6
7const HREF_PATTERNS = [ABSOLUTE_HREF, SITE_PATH_HREF];
8
9/**
10 * Trims a link address and checks it against what the editor may produce:
11 * `https://`, `http://`, `mailto:`, `tel:` or a site path starting with `/`.
12 * Anything else (`javascript:`, `data:`, a bare word) is rejected so the
13 * stored HTML never carries a scheme the consuming app has to filter out.
14 *
15 * @param raw - The address as typed.
16 * @returns The trimmed address, or `null` when it is not allowed.
17 */
18export const normalizeLinkHref = (raw: string): string | null => {
19  const href = raw.trim();
20  const isAllowed = HREF_PATTERNS.some((pattern) => pattern.test(href));
21
22  return isAllowed ? href : null;
23};

1import type { Extensions } from "@tiptap/react";
2import { StarterKit } from "@tiptap/starter-kit";
3import { Image } from "@tiptap/extension-image";
4import { Link } from "@tiptap/extension-link";
5import { normalizeLinkHref } from "./link-href.js";
6import type { RichTextEditorFeature } from "./rich-text-editor-items.js";
7
8/**
9 * Only the attributes the README allowlist names are kept, so pasted HTML
10 * cannot smuggle `target`, `rel`, `class` or `title` past a sanitiser that
11 * trusts "the editor can only produce" them.
12 */
13const SafeLink = Link.extend({
14  addAttributes: () => ({
15    href: {
16      default: null,
17      // Store the address as the dialog would: trimmed.
18      parseHTML: (element) => element.getAttribute("href")?.trim() ?? null,
19    },
20  }),
21});
22
23const SafeImage = Image.extend({
24  addAttributes: () => ({
25    src: { default: null },
26    alt: { default: null },
27    width: { default: null },
28    height: { default: null },
29  }),
30});
31
32const HEADING_LEVELS: (2 | 3)[] = [2, 3];
33
34/**
35 * Builds the TipTap extensions for a feature set. The set is also the output
36 * allowlist: nothing outside the toolbar's formats (underline, strike, code,
37 * code blocks, rules, h1 and h4 to h6) can be produced, even by a keyboard
38 * shortcut or a paste, so the consuming app's sanitiser only has to allow
39 * what is listed on `RichText`.
40 *
41 * @param features - The features switched on.
42 */
43export const buildExtensions = (
44  features: RichTextEditorFeature[],
45): Extensions => {
46  const isOn = (feature: RichTextEditorFeature) => features.includes(feature);
47  const extensions: Extensions = [
48    StarterKit.configure({
49      bold: isOn("bold") ? undefined : false,
50      italic: isOn("italic") ? undefined : false,
51      heading: isOn("heading") ? { levels: HEADING_LEVELS } : false,
52      bulletList: isOn("bulletList") ? undefined : false,
53      orderedList: isOn("orderedList") ? undefined : false,
54      blockquote: isOn("blockquote") ? undefined : false,
55      code: false,
56      codeBlock: false,
57      horizontalRule: false,
58      strike: false,
59      underline: false,
60      // StarterKit bundles Link; the package adds its own below so the
61      // options (and the dependency) are explicit.
62      link: false,
63    }),
64  ];
65
66  if (isOn("link")) {
67    extensions.push(
68      SafeLink.configure({
69        openOnClick: false,
70        autolink: false,
71        // The dialog's rule applies to pasted and parsed links too.
72        isAllowedUri: (url) => normalizeLinkHref(url) !== null,
73        shouldAutoLink: (url) => normalizeLinkHref(url) !== null,
74        // Site paths stay in the tab, and the stored anchor carries only href.
75        HTMLAttributes: { target: null, rel: null },
76      }),
77    );
78  }
79
80  if (isOn("image")) {
81    extensions.push(SafeImage.configure({ inline: false }));
82  }
83
84  return extensions;
85};

1import type { Editor } from "@tiptap/react";
2import {
3  BoldIcon,
4  ImageIcon,
5  ItalicIcon,
6  LinkIcon,
7  ListIcon,
8  ListOrderedIcon,
9  QuoteIcon,
10  type IconComponent,
11} from "@behivetech/atoms.icon";
12import type { RichTextEditorLabels } from "./rich-text-editor-labels.js";
13
14/** A group of controls the `features` prop can switch on or off. */
15export type RichTextEditorFeature =
16  | "bold"
17  | "italic"
18  | "heading"
19  | "bulletList"
20  | "orderedList"
21  | "blockquote"
22  | "link"
23  | "image";
24
25export const ALL_FEATURES: RichTextEditorFeature[] = [
26  "bold",
27  "italic",
28  "heading",
29  "bulletList",
30  "orderedList",
31  "blockquote",
32  "link",
33  "image",
34];
35
36export type ToolbarItemId =
37  | "bold"
38  | "italic"
39  | "heading2"
40  | "heading3"
41  | "bulletList"
42  | "orderedList"
43  | "blockquote"
44  | "link"
45  | "image";
46
47export type ToolbarGroupId = "marks" | "headings" | "blocks" | "insert";
48
49/** What pressing a toolbar button does: toggle a format, or open something. */
50export type ToolbarAction = "toggle" | "link" | "image";
51
52export interface ToolbarItem {
53  id: ToolbarItemId;
54  group: ToolbarGroupId;
55  feature: RichTextEditorFeature;
56  action: ToolbarAction;
57  /** Key into the labels, which is also the accessible name */
58  label: keyof RichTextEditorLabels;
59  /** Glyph for icon buttons */
60  Icon?: IconComponent;
61  /** Key of the visible text for text buttons (H2, H3) */
62  textLabel?: keyof RichTextEditorLabels;
63}
64
65/** Toolbar order. Groups wrap as whole groups on narrow screens. */
66export const TOOLBAR_ITEMS: ToolbarItem[] = [
67  {
68    id: "bold",
69    group: "marks",
70    feature: "bold",
71    action: "toggle",
72    label: "bold",
73    Icon: BoldIcon,
74  },
75  {
76    id: "italic",
77    group: "marks",
78    feature: "italic",
79    action: "toggle",
80    label: "italic",
81    Icon: ItalicIcon,
82  },
83  {
84    id: "heading2",
85    group: "headings",
86    feature: "heading",
87    action: "toggle",
88    label: "heading2",
89    textLabel: "heading2Short",
90  },
91  {
92    id: "heading3",
93    group: "headings",
94    feature: "heading",
95    action: "toggle",
96    label: "heading3",
97    textLabel: "heading3Short",
98  },
99  {
100    id: "bulletList",
101    group: "blocks",
102    feature: "bulletList",
103    action: "toggle",
104    label: "bulletList",
105    Icon: ListIcon,
106  },
107  {
108    id: "orderedList",
109    group: "blocks",
110    feature: "orderedList",
111    action: "toggle",
112    label: "orderedList",
113    Icon: ListOrderedIcon,
114  },
115  {
116    id: "blockquote",
117    group: "blocks",
118    feature: "blockquote",
119    action: "toggle",
120    label: "blockquote",
121    Icon: QuoteIcon,
122  },
123  {
124    id: "link",
125    group: "insert",
126    feature: "link",
127    action: "link",
128    label: "link",
129    Icon: LinkIcon,
130  },
131  {
132    id: "image",
133    group: "insert",
134    feature: "image",
135    action: "image",
136    label: "image",
137    Icon: ImageIcon,
138  },
139];
140
141const HEADING_LEVEL_2 = 2;
142const HEADING_LEVEL_3 = 3;
143
144/** Runs the toggle for an item against the editor, focusing it first. */
145export const TOGGLE_COMMANDS: Partial<
146  Record<ToolbarItemId, (editor: Editor) => void>
147> = {
148  bold: (editor) => editor.chain().focus().toggleBold().run(),
149  italic: (editor) => editor.chain().focus().toggleItalic().run(),
150  heading2: (editor) =>
151    editor.chain().focus().toggleHeading({ level: HEADING_LEVEL_2 }).run(),
152  heading3: (editor) =>
153    editor.chain().focus().toggleHeading({ level: HEADING_LEVEL_3 }).run(),
154  bulletList: (editor) => editor.chain().focus().toggleBulletList().run(),
155  orderedList: (editor) => editor.chain().focus().toggleOrderedList().run(),
156  blockquote: (editor) => editor.chain().focus().toggleBlockquote().run(),
157};
158
159/** Reads whether the caret sits inside the format an item toggles. */
160export const IS_ACTIVE: Record<ToolbarItemId, (editor: Editor) => boolean> = {
161  bold: (editor) => editor.isActive("bold"),
162  italic: (editor) => editor.isActive("italic"),
163  heading2: (editor) => editor.isActive("heading", { level: HEADING_LEVEL_2 }),
164  heading3: (editor) => editor.isActive("heading", { level: HEADING_LEVEL_3 }),
165  bulletList: (editor) => editor.isActive("bulletList"),
166  orderedList: (editor) => editor.isActive("orderedList"),
167  blockquote: (editor) => editor.isActive("blockquote"),
168  link: (editor) => editor.isActive("link"),
169  image: () => false,
170};

1/**
2 * Every string the editor shows or announces. Registry packages ship no i18n
3 * layer, so the app passes translated text through the `labels` prop and the
4 * English defaults here fill the gaps.
5 */
6export interface RichTextEditorLabels {
7  /** Accessible name of the editing area when the app passes no `aria-label` */
8  editor: string;
9  /** Accessible name of the toolbar */
10  toolbar: string;
11  bold: string;
12  italic: string;
13  /** Visible text of the H2 button */
14  heading2Short: string;
15  /** Accessible name of the H2 button; starts with the visible text (WCAG 2.5.3) */
16  heading2: string;
17  /** Visible text of the H3 button */
18  heading3Short: string;
19  /** Accessible name of the H3 button; starts with the visible text (WCAG 2.5.3) */
20  heading3: string;
21  bulletList: string;
22  orderedList: string;
23  blockquote: string;
24  link: string;
25  image: string;
26  /** Title of the link dialog */
27  linkTitle: string;
28  linkText: string;
29  linkAddress: string;
30  linkAddressHint: string;
31  linkAddressError: string;
32  linkRemove: string;
33  linkCancel: string;
34  linkSave: string;
35}
36
37/** English text for every label; the `labels` prop overrides single keys. */
38export const DEFAULT_LABELS: RichTextEditorLabels = {
39  editor: "Rich text editor",
40  toolbar: "Formatting",
41  bold: "Bold",
42  italic: "Italic",
43  heading2Short: "H2",
44  heading2: "H2 heading",
45  heading3Short: "H3",
46  heading3: "H3 heading",
47  bulletList: "Bulleted list",
48  orderedList: "Numbered list",
49  blockquote: "Quote",
50  link: "Link",
51  image: "Image",
52  linkTitle: "Link",
53  linkText: "Text",
54  linkAddress: "Address",
55  linkAddressHint:
56    "A web page (https://…), an email (mailto:…) or a page on this site (/guide/…).",
57  linkAddressError:
58    "Enter a web address, a mailto: or tel: link, or a path that starts with /.",
59  linkRemove: "Remove link",
60  linkCancel: "Cancel",
61  linkSave: "Save link",
62};

1import { type FormEvent, useId, useState } from "react";
2import { getClassName } from "@bht-component-registry/class-names";
3import { Button } from "@behivetech/atoms.button";
4import { Modal } from "@behivetech/atoms.modal";
5import { TextField } from "@behivetech/atoms.text-field";
6import { FormField } from "@behivetech/forms.form-field";
7import { normalizeLinkHref } from "./link-href.js";
8import type { RichTextEditorLabels } from "./rich-text-editor-labels.js";
9import styles from "./rich-text-editor-link-dialog.module.scss";
10
11export interface LinkDialogValue {
12  /** Visible text of the link; empty means "use the address" */
13  text: string;
14  /** Validated, trimmed address */
15  href: string;
16}
17
18export interface RichTextEditorLinkDialogProps {
19  /** Text prefilled from the selection */
20  initialText: string;
21  /** Address prefilled when the caret is already in a link */
22  initialHref: string;
23  /** Shows "Remove link", only when the caret is in a link */
24  canRemove: boolean;
25  labels: RichTextEditorLabels;
26  /** Called with the validated values when the form is submitted */
27  onSave: (value: LinkDialogValue) => void;
28  /** Called when the user removes the link */
29  onRemove: () => void;
30  /** Called on Cancel, Escape, backdrop click or the close button */
31  onClose: () => void;
32}
33
34/**
35 * The small dialog the toolbar's Link button opens, on `Modal`. Enter submits,
36 * Escape cancels, and focus starts in Address. An address that is not an
37 * allowed link shows an inline error and the dialog stays open.
38 */
39export const RichTextEditorLinkDialog = ({
40  initialText,
41  initialHref,
42  canRemove,
43  labels,
44  onSave,
45  onRemove,
46  onClose,
47}: RichTextEditorLinkDialogProps) => {
48  const [rootClass, getChildClass] = getClassName({
49    rootClass: "BHT__RichTextEditorLinkDialog",
50    styles,
51  });
52  const fieldId = useId();
53  const hintId = `${fieldId}-hint`;
54  const errorId = `${fieldId}-error`;
55  const [text, setText] = useState(initialText);
56  const [href, setHref] = useState(initialHref);
57  const [hasError, setHasError] = useState(false);
58
59  const handleSubmit = (event: FormEvent<HTMLFormElement>) => {
60    event.preventDefault();
61    const normalized = normalizeLinkHref(href);
62
63    setHasError(normalized === null);
64    if (normalized !== null) {
65      onSave({ text: text.trim(), href: normalized });
66    }
67  };
68
69  return (
70    // Modal's content portals to body, so the ghost-label colour is set through its className.
71    <Modal
72      className={rootClass}
73      title={labels.linkTitle}
74      headingLevel={2}
75      padding="md"
76      onClose={onClose}
77    >
78      <form
79        className={getChildClass("form")}
80        onSubmit={handleSubmit}
81        noValidate
82      >
83        <FormField label={labels.linkText} htmlFor={`${fieldId}-text`}>
84          <TextField
85            id={`${fieldId}-text`}
86            value={text}
87            onChange={(event) => setText(event.target.value)}
88          />
89        </FormField>
90        <FormField
91          label={labels.linkAddress}
92          htmlFor={`${fieldId}-address`}
93          hint={<span id={hintId}>{labels.linkAddressHint}</span>}
94          error={
95            hasError ? (
96              <span id={errorId}>{labels.linkAddressError}</span>
97            ) : undefined
98          }
99          required
100        >
101          <TextField
102            name="address"
103            required
104            aria-describedby={hasError ? errorId : hintId}
105            // Focus starts in the one required field. Radix leaves focus alone when it is already inside the dialog.
106            autoFocus
107            id={`${fieldId}-address`}
108            type="url"
109            inputMode="url"
110            value={href}
111            invalid={hasError}
112            onChange={(event) => {
113              setHref(event.target.value);
114              setHasError(false);
115            }}
116          />
117        </FormField>
118        <div className={getChildClass("actions")}>
119          {canRemove && (
120            <Button type="button" variant="ghost" onClick={onRemove}>
121              {labels.linkRemove}
122            </Button>
123          )}
124          <div className={getChildClass("main-actions")}>
125            <Button type="button" variant="ghost" onClick={onClose}>
126              {labels.linkCancel}
127            </Button>
128            <Button type="submit" variant="primary">
129              {labels.linkSave}
130            </Button>
131          </div>
132        </div>
133      </form>
134    </Modal>
135  );
136};

1import {
2  type KeyboardEvent,
3  useCallback,
4  useMemo,
5  useRef,
6  useState,
7} from "react";
8import { getClassName } from "@bht-component-registry/class-names";
9import { Button } from "@behivetech/atoms.button";
10import { Tooltip } from "@behivetech/atoms.tooltip";
11import {
12  type ToolbarGroupId,
13  type ToolbarItem,
14  type ToolbarItemId,
15} from "./rich-text-editor-items.js";
16import type { RichTextEditorLabels } from "./rich-text-editor-labels.js";
17import styles from "./rich-text-editor-toolbar.module.scss";
18
19const GROUP_ORDER: ToolbarGroupId[] = ["marks", "headings", "blocks", "insert"];
20
21/** Where each navigation key lands, given the current index and the count. */
22const KEY_TARGETS: Record<string, (index: number, count: number) => number> = {
23  ArrowRight: (index, count) => (index + 1) % count,
24  ArrowLeft: (index, count) => (index - 1 + count) % count,
25  Home: () => 0,
26  End: (_index, count) => count - 1,
27};
28
29export interface RichTextEditorToolbarProps {
30  /** Id of the editing area the toolbar controls */
31  controls?: string;
32  /** Buttons to show, already filtered by `features` */
33  items: ToolbarItem[];
34  /** Which items are pressed right now */
35  pressed: Partial<Record<ToolbarItemId, boolean>>;
36  /** Item whose action is in flight, shown as a loading button */
37  busyId?: ToolbarItemId;
38  /** Disables every button, used before the editor mounts */
39  disabled: boolean;
40  labels: RichTextEditorLabels;
41  /** Called with the item the user pressed */
42  action: (item: ToolbarItem, button: HTMLButtonElement) => void;
43  className?: string;
44}
45
46/**
47 * The formatting toolbar: four groups of icon buttons that wrap as whole
48 * groups. It is a single tab stop (roving tabindex); the arrow keys, Home and
49 * End move between the buttons.
50 */
51export const RichTextEditorToolbar = ({
52  controls,
53  items,
54  pressed,
55  busyId,
56  disabled,
57  labels,
58  action,
59  className,
60}: RichTextEditorToolbarProps) => {
61  const [rootClass, getChildClass] = getClassName({
62    className,
63    rootClass: "BHT__RichTextEditorToolbar",
64    styles,
65  });
66  const toolbarRef = useRef<HTMLDivElement>(null);
67  const [activeIndex, setActiveIndex] = useState(0);
68
69  // `items` can shrink under a stored index; keep one button in the tab order.
70  const tabStop = Math.min(activeIndex, items.length - 1);
71
72  const groups = useMemo(
73    () =>
74      GROUP_ORDER.map((group) => ({
75        group,
76        items: items.filter((item) => item.group === group),
77      })).filter(({ items: groupItems }) => groupItems.length > 0),
78    [items],
79  );
80
81  const moveFocus = useCallback((index: number) => {
82    const buttons = toolbarRef.current?.querySelectorAll("button");
83    const target = buttons?.[index];
84    if (target) {
85      setActiveIndex(index);
86      target.focus();
87    }
88  }, []);
89
90  const handleKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {
91    const getTarget = KEY_TARGETS[event.key];
92
93    if (getTarget) {
94      event.preventDefault();
95      moveFocus(getTarget(activeIndex, items.length));
96    }
97  };
98
99  return (
100    <div
101      ref={toolbarRef}
102      role="toolbar"
103      aria-label={labels.toolbar}
104      aria-controls={controls}
105      className={rootClass}
106      onKeyDown={handleKeyDown}
107    >
108      {groups.map(({ group, items: groupItems }) => (
109        <div key={group} className={getChildClass("group")}>
110          {groupItems.map((item) => {
111            const index = items.indexOf(item);
112            const isPressed = pressed[item.id] === true;
113            const label = labels[item.label];
114            const { Icon } = item;
115
116            return (
117              <Tooltip key={item.id} label={label}>
118                <Button
119                  type="button"
120                  iconOnly
121                  size="md"
122                  variant={isPressed ? "primary" : "ghost"}
123                  aria-label={label}
124                  aria-pressed={item.action === "image" ? undefined : isPressed}
125                  aria-haspopup={item.action === "link" ? "dialog" : undefined}
126                  disabled={disabled}
127                  loading={busyId === item.id}
128                  tabIndex={index === tabStop ? 0 : -1}
129                  onFocus={() => setActiveIndex(index)}
130                  onClick={(event) => action(item, event.currentTarget)}
131                >
132                  {Icon ? (
133                    <Icon size="sm" />
134                  ) : item.textLabel ? (
135                    labels[item.textLabel]
136                  ) : null}
137                </Button>
138              </Tooltip>
139            );
140          })}
141        </div>
142      ))}
143    </div>
144  );
145};

1import { useEffect, useMemo, useRef } from "react";
2import { EditorContent, useEditor, useEditorState } from "@tiptap/react";
3import { getClassName } from "@bht-component-registry/class-names";
4import { RichText, getRichTextClassName } from "./rich-text.js";
5import { RichTextEditorLinkDialog } from "./rich-text-editor-link-dialog.js";
6import { buildExtensions } from "./rich-text-editor-extensions.js";
7import {
8  ALL_FEATURES,
9  IS_ACTIVE,
10  TOGGLE_COMMANDS,
11  TOOLBAR_ITEMS,
12  type RichTextEditorFeature,
13  type ToolbarItem,
14  type ToolbarItemId,
15} from "./rich-text-editor-items.js";
16import {
17  DEFAULT_LABELS,
18  type RichTextEditorLabels,
19} from "./rich-text-editor-labels.js";
20import { RichTextEditorToolbar } from "./rich-text-editor-toolbar.js";
21import {
22  useRichTextEditorActions,
23  type InsertImageResult,
24} from "./use-rich-text-editor-actions.js";
25import styles from "./rich-text-editor.module.scss";
26
27export type { RichTextEditorFeature } from "./rich-text-editor-items.js";
28export type { RichTextEditorLabels } from "./rich-text-editor-labels.js";
29export type {
30  InsertImageResult,
31  RichTextImage,
32} from "./use-rich-text-editor-actions.js";
33
34export interface RichTextEditorProps {
35  /** Id of the editing area. A `FormField` label cannot name a contenteditable, so also pass `aria-labelledby` */
36  id?: string;
37  /** Additional class names to merge with the component root element */
38  className?: string;
39  /** Current value as HTML. Sanitise it on save: the editor only produces what `RichText` lists, but a stored value can be anything */
40  value: string;
41  /** Called with the updated HTML on every edit; an empty document gives an empty string */
42  onChange: (html: string) => void;
43  /**
44   * Shows the Image button and runs when it is pressed. Resolve with
45   * `{ src, alt, width?, height? }`, or a plain address string (alt is then
46   * empty), to insert the image at the caret; resolve with nothing, or
47   * reject, to insert nothing. The button shows a loading state meanwhile.
48   */
49  onInsertImage?: () => InsertImageResult | Promise<InsertImageResult>;
50  /** Which formats to offer. Defaults to all of them; the Image button also needs `onInsertImage` */
51  features?: RichTextEditorFeature[];
52  /** Marks the editor as invalid: adds the `--invalid` modifier and sets `aria-invalid`. `FormField` carries the message */
53  invalid?: boolean;
54  /** Text overrides for the toolbar and the link dialog, for translation. Missing keys fall back to English */
55  labels?: Partial<RichTextEditorLabels>;
56  /** Accessible name of the editing area; defaults to `labels.editor` */
57  "aria-label"?: string;
58  /** Id of the element that names the editing area, for example the `FormField` label */
59  "aria-labelledby"?: string;
60  /** Id of the element that describes the editing area, for example the `FormField` hint */
61  "aria-describedby"?: string;
62}
63
64interface ContentAttributesInput {
65  id?: string;
66  className: string;
67  name: string;
68  labelledBy?: string;
69  describedBy?: string;
70  invalid: boolean;
71}
72
73/** The attributes of the contenteditable element: a labelled, multiline textbox. */
74const getContentAttributes = ({
75  id,
76  className,
77  name,
78  labelledBy,
79  describedBy,
80  invalid,
81}: ContentAttributesInput): Record<string, string> => ({
82  ...(id ? { id } : {}),
83  class: className,
84  role: "textbox",
85  "aria-multiline": "true",
86  ...(labelledBy ? { "aria-labelledby": labelledBy } : { "aria-label": name }),
87  ...(describedBy ? { "aria-describedby": describedBy } : {}),
88  ...(invalid ? { "aria-invalid": "true" } : {}),
89});
90
91/**
92 * A TipTap-backed WYSIWYG editor: a toolbar (bold, italic, headings 2 and 3,
93 * bulleted and numbered lists, quote, link, image) over a content area that
94 * wears the `RichText` prose styles. Value in and out is HTML.
95 *
96 * Wrap it in `FormField`. Before TipTap mounts it shows the value read-only at
97 * the same size with the toolbar disabled, so the page does not jump.
98 */
99export const RichTextEditor = ({
100  id,
101  className,
102  value,
103  onChange,
104  onInsertImage,
105  features = ALL_FEATURES,
106  invalid = false,
107  labels,
108  "aria-label": ariaLabel,
109  "aria-labelledby": ariaLabelledBy,
110  "aria-describedby": ariaDescribedBy,
111}: RichTextEditorProps) => {
112  const [rootClass, getChildClass] = getClassName({
113    className,
114    rootClass: "BHT__RichTextEditor",
115    modifiers: { invalid },
116    styles,
117  });
118  const text = { ...DEFAULT_LABELS, ...labels };
119  // `features` is usually an inline array, so its contents are the identity:
120  // a new array with the same entries must not rebuild the editor.
121  const featureKey = features.join();
122  const extensions = useMemo(
123    () => buildExtensions(featureKey.split(",") as RichTextEditorFeature[]),
124    [featureKey],
125  );
126  const contentClass = getRichTextClassName(getChildClass("content"));
127
128  const attributes = getContentAttributes({
129    id,
130    className: contentClass,
131    name: ariaLabel ?? text.editor,
132    labelledBy: ariaLabelledBy,
133    describedBy: ariaDescribedBy,
134    invalid,
135  });
136  const attributesKey = JSON.stringify(attributes);
137
138  // The last HTML the editor and the app agreed on. Content is replaced only
139  // when `value` moves away from it, so a stored value TipTap would serialise
140  // differently does not reset the caret on mount or on an echoed onChange.
141  const lastValue = useRef(value);
142
143  const editor = useEditor(
144    {
145      extensions,
146      content: value,
147      immediatelyRender: false,
148      editorProps: { attributes },
149      onUpdate: ({ editor: updated }) => {
150        const html = updated.isEmpty ? "" : updated.getHTML();
151        lastValue.current = html;
152        onChange(html);
153      },
154    },
155    [extensions],
156  );
157
158  // Keep the content area's attributes current without remounting the editor.
159  useEffect(() => {
160    editor?.setOptions({
161      editorProps: { attributes: JSON.parse(attributesKey) },
162    });
163  }, [editor, attributesKey]);
164
165  // Follow a `value` that changed from outside, such as a form reset.
166  useEffect(() => {
167    if (editor && value !== lastValue.current) {
168      lastValue.current = value;
169      editor.commands.setContent(value, { emitUpdate: false });
170    }
171  }, [value, editor]);
172
173  const pressed = useEditorState({
174    editor,
175    selector: ({ editor: current }) =>
176      Object.fromEntries(
177        Object.entries(IS_ACTIVE).map(([itemId, isActive]) => [
178          itemId,
179          current ? isActive(current) : false,
180        ]),
181      ) as Partial<Record<ToolbarItemId, boolean>>,
182  });
183
184  const {
185    linkDraft,
186    isInsertingImage,
187    openLink,
188    saveLink,
189    removeLink,
190    closeLink,
191    insertImage,
192  } = useRichTextEditorActions(editor, onInsertImage);
193
194  const hasImagePicker = onInsertImage !== undefined;
195  const items = useMemo(() => {
196    const enabled = featureKey.split(",");
197
198    return TOOLBAR_ITEMS.filter(
199      (item) =>
200        enabled.includes(item.feature) &&
201        (item.id !== "image" || hasImagePicker),
202    );
203  }, [featureKey, hasImagePicker]);
204
205  const handleAction = (item: ToolbarItem, button: HTMLButtonElement) => {
206    const actions: Record<ToolbarItem["action"], () => void> = {
207      toggle: () => editor && TOGGLE_COMMANDS[item.id]?.(editor),
208      link: () => openLink(button),
209      image: () => void insertImage(button),
210    };
211
212    actions[item.action]();
213  };
214
215  return (
216    <div className={rootClass}>
217      <RichTextEditorToolbar
218        controls={id}
219        items={items}
220        pressed={pressed ?? {}}
221        busyId={isInsertingImage ? "image" : undefined}
222        disabled={!editor}
223        labels={text}
224        action={handleAction}
225      />
226      {editor ? (
227        <EditorContent editor={editor} />
228      ) : (
229        <RichText
230          html={value}
231          className={getChildClass("content")}
232          aria-busy="true"
233        />
234      )}
235      {linkDraft && (
236        <RichTextEditorLinkDialog
237          initialText={linkDraft.text}
238          initialHref={linkDraft.href}
239          canRemove={linkDraft.canRemove}
240          labels={text}
241          onSave={saveLink}
242          onRemove={removeLink}
243          onClose={closeLink}
244        />
245      )}
246    </div>
247  );
248};