components/markdown-editor/markdown-editor.react.tsx

Functions

Imports

It imports components/markdown-editor/markdown-editor.ts. Imported by components/markdown-editor/examples.tsx.

Source

1import { useEffect, useId, useRef, type ReactNode } from "react";
2
3import type { LinkTarget, MarkdownEditorHandle, MarkdownEditorOptions } from "./markdown-editor.ts";
4
5export type { LinkTarget, MarkdownEditorHandle, MarkdownEditorOptions, Scaffold, UploadResult } from "./markdown-editor.ts";
6
7export interface MarkdownEditorProps
8  extends Pick<MarkdownEditorOptions, "scaffolds" | "linkTargets" | "onUpload" | "imageMarkdown" | "accept" | "lineNumbers" | "nonce" | "wordsPerMinute" | "onSave"> {
9  // The visible label above the editor.
10  label: ReactNode;
11  // The surface's accessible name; defaults to the label's text plus ", markdown".
12  ariaLabel?: string;
13  // The field's name in a form: the markdown is posted in a hidden textarea of this name.
14  name?: string;
15  id?: string;
16  // Controlled: the text. Without it the editor keeps its own, starting at defaultValue.
17  value?: string;
18  defaultValue?: string;
19  onChange?: (value: string) => void;
20  placeholder?: string;
21  readOnly?: boolean;
22  disabled?: boolean;
23  required?: boolean;
24  // A hint, not a stop: the footer counts characters against it and says when the text is over.
25  maxLength?: number;
26  // Help, between the label and the editor, read as its description.
27  help?: ReactNode;
28  // What is wrong and what to do; shown below the editor, and marks it invalid.
29  error?: ReactNode;
30  // Called once with the handle when CodeMirror has loaded.
31  onReady?: (handle: MarkdownEditorHandle) => void;
32}
33
34// Renders the HTML contract in markdown-editor.md: a label and a real textarea holding the
35// markdown, which is all a server render (and a reader without script) gets. After mount it
36// loads the behaviour module and CodeMirror with import(), so they are their own chunks and
37// never reach a bundle that renders no editor, and upgrades the textarea in place.
38export function MarkdownEditor(props: MarkdownEditorProps) {
39  const { label, ariaLabel, name, value, defaultValue, placeholder, readOnly, disabled, required, maxLength, help, error } = props;
40  const base = useId();
41  const id = props.id ?? `${base}-md`;
42  const helpId = `${base}-help`;
43  const errorId = `${base}-error`;
44  const hasError = error != null && error !== false && error !== "";
45  const describedBy = [hasError ? errorId : null, help ? helpId : null].filter(Boolean).join(" ") || undefined;
46
47  const rootRef = useRef<HTMLDivElement>(null);
48  const handleRef = useRef<MarkdownEditorHandle | null>(null);
49  // What the latest render said, read by the callbacks the editor was mounted with.
50  const latest = useRef(props);
51  latest.current = props;
52
53  const hasUpload = !!props.onUpload;
54  const scaffoldsKey = JSON.stringify(props.scaffolds ?? null);
55
56  const options = (): MarkdownEditorOptions => ({
57    label: latest.current.ariaLabel,
58    lineNumbers: latest.current.lineNumbers,
59    accept: latest.current.accept,
60    nonce: latest.current.nonce,
61    wordsPerMinute: latest.current.wordsPerMinute,
62    scaffolds: latest.current.scaffolds,
63    // Always a function, so a later render's targets are used without rebuilding the editor.
64    linkTargets: async (query) => {
65      const t = latest.current.linkTargets;
66      if (typeof t === "function") return t(query);
67      const { filterLinkTargets } = await import("./markdown-editor.ts");
68      return filterLinkTargets((t ?? []) as LinkTarget[], query);
69    },
70    onUpload: latest.current.onUpload ? (f) => (latest.current.onUpload as NonNullable<MarkdownEditorOptions["onUpload"]>)(f) : undefined,
71    imageMarkdown: latest.current.imageMarkdown ? (i) => (latest.current.imageMarkdown as NonNullable<MarkdownEditorOptions["imageMarkdown"]>)(i) : undefined,
72    onChange: (v) => latest.current.onChange?.(v),
73    onSave: (v) => latest.current.onSave?.(v),
74  });
75
76  useEffect(() => {
77    const host = rootRef.current;
78    if (!host) return;
79    let cancelled = false;
80    let mounted: MarkdownEditorHandle | null = null;
81    import("./markdown-editor.ts")
82      .then((m) => (cancelled ? null : m.mountMarkdownEditor(host, options())))
83      .then((h) => {
84        if (!h) return;
85        if (cancelled) return h.destroy();
86        mounted = h;
87        handleRef.current = h;
88        const v = latest.current.value;
89        if (v !== undefined && v !== h.getValue()) h.setValue(v);
90        latest.current.onReady?.(h);
91      })
92      .catch(() => {
93        // CodeMirror did not load: the textarea stays as the editor.
94      });
95    return () => {
96      cancelled = true;
97      mounted?.destroy();
98      handleRef.current = null;
99    };
100    // Mounted once; later renders reach the editor through `latest` and the effects below.
101    // eslint-disable-next-line react-hooks/exhaustive-deps
102  }, []);
103
104  // A controlled value: set only when it differs, or each keystroke would round-trip and reset the cursor.
105  useEffect(() => {
106    if (value === undefined) return;
107    const h = handleRef.current;
108    if (h) {
109      if (h.getValue() !== value) h.setValue(value);
110    } else {
111      const ta = rootRef.current?.querySelector("textarea");
112      if (ta && ta.value !== value) ta.value = value;
113    }
114  }, [value]);
115
116  // The toolbar and the slash menu are rebuilt only when what they list changes, not each render.
117  useEffect(() => {
118    const o = options();
119    handleRef.current?.update({ scaffolds: o.scaffolds, onUpload: o.onUpload, imageMarkdown: o.imageMarkdown, label: ariaLabel });
120    // eslint-disable-next-line react-hooks/exhaustive-deps
121  }, [scaffoldsKey, hasUpload, ariaLabel]);
122
123  return (
124    <div className="cap-md cap-field" data-cap="markdown-editor" ref={rootRef}>
125      <label className="cap-field-label" htmlFor={id}>
126        {label}
127        {required ? (
128          <span className="cap-field-required" aria-hidden="true">
129            Required
130          </span>
131        ) : null}
132      </label>
133      {help ? (
134        <p className="cap-field-help" id={helpId}>
135          {help}
136        </p>
137      ) : null}
138      <textarea
139        className="cap-input cap-md-source"
140        id={id}
141        name={name}
142        defaultValue={value ?? defaultValue ?? ""}
143        placeholder={placeholder}
144        readOnly={readOnly}
145        disabled={disabled}
146        required={required}
147        maxLength={maxLength}
148        spellCheck
149        aria-invalid={hasError ? true : undefined}
150        aria-describedby={describedBy}
151      />
152      {hasError ? (
153        <p className="cap-field-error" id={errorId}>
154          {error}
155        </p>
156      ) : null}
157    </div>
158  );
159}