@startsimpli/ui 0.4.142 → 0.4.144

package/src/components/track-changes/TrackedTextEditor.tsx

@@ -0,0 +1,595 @@
+'use client';
+
+/**
+ * TrackedTextEditor — the track-changes editor surface (bd startsim-sjuai;
+ * design startsim-xyn25 section d).
+ *
+ * CodeMirror 6 over the STORED STRING: markdown source for a blog, plain text
+ * for LinkedIn. Quinn chose this over a Word-like rich editor because a rich
+ * editor saves its own serialization, and on the 183 live drafts that rewrote
+ * 4 blogs and every LinkedIn post, which blame would then credit to whoever
+ * saved. This editor never normalizes: what the host passes in is what it
+ * hands back, byte for byte.
+ *
+ * TWO MODES.
+ * - EDITING: typing changes the field. `onChange(text)` reports the whole
+ *   string; the host saves it (useConditionalSave) and passes it back.
+ * - SUGGESTING: typing changes a LOCAL PROPOSED COPY, shown as insert/delete
+ *   marks against the stored text. `onChange` is NEVER called, so nothing can
+ *   PATCH the field. The whole proposed text is posted with the base version
+ *   (`onPropose`) after a pause (5 s), on blur, and on leaving the mode; the
+ *   server hunks it and supersedes this author's own open set. A reviewer who
+ *   may not edit (`canEdit={false}`) is held in this mode: view-only reviewers
+ *   may suggest (Quinn, 2026-10-07).
+ *
+ * PRESENTATIONAL. It fetches nothing. Annotations come in as props, normally
+ * from {@link useTrackChanges}, which owns the injected client; the changes
+ * rail (startsim-whwxd.3) reads that same hook result and drives this editor
+ * through the ref handle (`focusMark`, `nextChange`, `selectionAnchor`) and the
+ * `show`/`onActiveChange` props. The rail, show/hide, final/original views and
+ * the Read-view overlay are deliberately not here.
+ *
+ * ACCESSIBLE. Every mark carries its sentence as a `title`; F8 / Shift+F8 move
+ * between suggestions and comments, Alt+F8 / Shift+Alt+F8 between authorship
+ * spans; the mark at the cursor is announced in a polite live region. Tab
+ * leaves the editor (no tab trapping).
+ *
+ * LAYOUT on the component's own container, never the viewport (bd
+ * startsim-jkkn7.12): its common home is a narrow review column.
+ *
+ * CodeMirror is an OPTIONAL peer dependency of @startsimpli/ui, imported only
+ * from the `@startsimpli/ui/track-changes` subpath. Mount it with a dynamic
+ * import so pages that never edit do not load it.
+ */
+import { defaultKeymap, history, historyKeymap } from '@codemirror/commands';
+import { markdownLanguage } from '@codemirror/lang-markdown';
+import { LanguageSupport, defaultHighlightStyle, syntaxHighlighting } from '@codemirror/language';
+import { Compartment, EditorState, type Extension } from '@codemirror/state';
+import { EditorView, keymap } from '@codemirror/view';
+import { forwardRef, useCallback, useEffect, useId, useImperativeHandle, useRef, useState } from 'react';
+
+import {
+  DEFAULT_KEYS,
+  activeMarkOf,
+  enterSuggesting,
+  focusMark,
+  internalChange,
+  isAuthorship,
+  isChangeOrComment,
+  isSuggesting,
+  leaveSuggesting,
+  marksOf,
+  moveToMark,
+  ownSuggestions,
+  rebaseOnto,
+  selectionAnchorOf,
+  setAnnotations,
+  trackChanges,
+  trackingOf,
+  type MarkVisibility,
+  type TrackKeys,
+  type TrackMark,
+} from './extension';
+import type { BlameSpan, CommentThread, SelectionAnchor, Suggestion } from './types';
+
+export type TrackMode = 'editing' | 'suggesting';
+
+export interface TrackedTextEditorProps {
+  /** The stored string at `version`. */
+  value: string;
+  /** The record version `value` was read at. Suggestions are posted against
+   *  it; `null` disables suggesting. */
+  version: number | null;
+  /** Accessible name of the text area ("Blog (markdown)"). */
+  label: string;
+  /** `markdown` highlights markdown syntax; `plain` is plain text. The stored
+   *  string is identical either way. */
+  language?: 'markdown' | 'plain';
+
+  /** Controlled mode. */
+  mode?: TrackMode;
+  defaultMode?: TrackMode;
+  onModeChange?: (mode: TrackMode) => void;
+  /** False: this reviewer may suggest but not edit. Default true. */
+  canEdit?: boolean;
+  /** Neither edit nor suggest; marks stay navigable. */
+  readOnly?: boolean;
+
+  /** Editing mode only: the whole string after each edit. */
+  onChange?: (value: string) => void;
+  /** Suggesting mode: post the whole proposed text against `baseVersion`.
+   *  Reject to keep the proposal and show it as not sent. */
+  onPropose?: (proposed: string, baseVersion: number) => Promise<unknown> | void;
+  /** Pause before a proposal is posted. Default 5000 ms (design section d). */
+  proposeDelayMs?: number;
+
+  /** Annotations, normalized (see useTrackChanges), in `value` coordinates. */
+  blame?: BlameSpan[];
+  suggestions?: Suggestion[];
+  threads?: CommentThread[];
+  /** The signed-in reviewer's `sub`. Their own open suggestions are loaded into
+   *  the proposal when suggesting starts, so that the next post (which
+   *  supersedes their open set) carries them forward. REQUIRED: pass `null`
+   *  only when the reviewer has no sub, accepting that limitation. */
+  currentActorSub: string | null;
+
+  /** Show/hide per kind (whwxd.3's toggle). Authors are the `showAuthors`
+   *  prop, because this editor owns that toggle. */
+  show?: Omit<MarkVisibility, 'blame'>;
+  showAuthors?: boolean;
+  defaultShowAuthors?: boolean;
+  onShowAuthorsChange?: (show: boolean) => void;
+
+  /** Sentences to show under the editor (from useTrackChanges `notices`). */
+  notices?: string[];
+  /** The mark at the cursor changed (keyboard, click or `focusMark`). */
+  onActiveChange?: (mark: TrackMark | null) => void;
+  /** The selection as a stored-string anchor, or null (for "comment on
+   *  selection" in the rail). */
+  onSelectionChange?: (anchor: SelectionAnchor | null) => void;
+
+  keys?: TrackKeys;
+  /** Render the mode and authors toolbar. Default true. */
+  toolbar?: boolean;
+  className?: string;
+  editorClassName?: string;
+}
+
+export interface TrackedTextEditorHandle {
+  readonly view: EditorView | null;
+  focus: () => void;
+  nextChange: () => boolean;
+  prevChange: () => boolean;
+  /** Select and announce a mark by id (suggestion, thread or blame span id). */
+  focusMark: (id: string) => boolean;
+  selectionAnchor: () => SelectionAnchor | null;
+  /** Post the pending proposal now (no-op outside suggesting mode or when
+   *  nothing changed since the last post). */
+  flush: () => Promise<void>;
+  proposedText: () => string;
+}
+
+type ProposalState =
+  | { state: 'idle' }
+  | { state: 'pending' }
+  | { state: 'sending' }
+  | { state: 'sent' }
+  | { state: 'error'; message: string };
+
+const EMITTED_MEMORY = 50;
+
+function keyLabel(k: string) {
+  return k.replace(/-/g, '+');
+}
+
+const baseEditorTheme = EditorView.theme({
+  '&': { fontSize: 'inherit', backgroundColor: 'transparent' },
+  '&.cm-focused': { outline: 'none' },
+  // The host's font, not CodeMirror's monospace default: this is prose.
+  '.cm-scroller': { fontFamily: 'inherit', lineHeight: 'inherit' },
+  '.cm-content': { fontFamily: 'inherit', padding: '0.75rem', minHeight: '8rem', caretColor: 'currentColor' },
+  '.cm-line': { padding: '0' },
+});
+
+export const TrackedTextEditor = forwardRef<TrackedTextEditorHandle, TrackedTextEditorProps>(
+  function TrackedTextEditor(props, ref) {
+    const {
+      value,
+      version,
+      label,
+      language = 'markdown',
+      mode: modeProp,
+      defaultMode,
+      onModeChange,
+      canEdit = true,
+      readOnly = false,
+      onPropose,
+      blame,
+      suggestions,
+      threads,
+      currentActorSub,
+      show,
+      showAuthors: showAuthorsProp,
+      defaultShowAuthors = false,
+      onShowAuthorsChange,
+      notices,
+      keys,
+      toolbar = true,
+      className,
+      editorClassName,
+    } = props;
+
+    const propsRef = useRef(props);
+    propsRef.current = props;
+
+    const hostRef = useRef<HTMLDivElement>(null);
+    const viewRef = useRef<EditorView | null>(null);
+    const compartments = useRef({
+      language: new Compartment(),
+      readOnly: new Compartment(),
+      history: new Compartment(),
+      attrs: new Compartment(),
+    }).current;
+    const emittedRef = useRef<string[]>([]);
+    const lastPostedRef = useRef<string>('');
+    const touchedRef = useRef(false);
+    const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+    const activeRef = useRef<TrackMark | null>(null);
+
+    const helpId = useId();
+    const [innerMode, setInnerMode] = useState<TrackMode>(defaultMode ?? (canEdit ? 'editing' : 'suggesting'));
+    const mode: TrackMode = !canEdit ? 'suggesting' : (modeProp ?? innerMode);
+    const [innerShowAuthors, setInnerShowAuthors] = useState(defaultShowAuthors);
+    const showAuthors = showAuthorsProp ?? innerShowAuthors;
+    const [active, setActive] = useState<TrackMark | null>(null);
+    const [unsaved, setUnsaved] = useState(false);
+    const [localCount, setLocalCount] = useState(0);
+    const [proposal, setProposal] = useState<ProposalState>({ state: 'idle' });
+    const [unplacedOwn, setUnplacedOwn] = useState(0);
+
+    const canSuggest = version != null && !!onPropose && !readOnly;
+    const editable = !readOnly && (mode === 'editing' ? canEdit : canSuggest);
+
+    /* ------------------------------ proposals ----------------------------- */
+
+    const flush = useCallback(async () => {
+      if (timerRef.current) clearTimeout(timerRef.current);
+      timerRef.current = null;
+      const view = viewRef.current;
+      const p = propsRef.current;
+      if (!view || !isSuggesting(view.state) || p.version == null || !p.onPropose) return;
+      const text = view.state.doc.toString();
+      if (text === lastPostedRef.current) {
+        setProposal((s) => (s.state === 'pending' ? { state: 'idle' } : s));
+        return;
+      }
+      const previous = lastPostedRef.current;
+      lastPostedRef.current = text;
+      setProposal({ state: 'sending' });
+      try {
+        await p.onPropose(text, p.version);
+        setProposal({ state: 'sent' });
+      } catch (err) {
+        lastPostedRef.current = previous;
+        const message = err instanceof Error && err.message ? err.message : 'the server did not say why';
+        setProposal({ state: 'error', message });
+      }
+    }, []);
+
+    const schedule = useCallback(() => {
+      if (timerRef.current) clearTimeout(timerRef.current);
+      const delay = propsRef.current.proposeDelayMs ?? 5000;
+      timerRef.current = setTimeout(() => void flush(), delay);
+      setProposal({ state: 'pending' });
+    }, [flush]);
+
+    /** Enter suggesting mode. What counts as "already posted" is set BEFORE
+     *  the switch is dispatched, so nothing that runs during the dispatch can
+     *  post the starting text as if it were a proposal. */
+    const enter = useCallback((view: EditorView) => {
+      const specs = enterSuggesting(view.state);
+      let next = view.state;
+      for (const spec of specs) next = next.update(spec).state;
+      lastPostedRef.current = next.doc.toString();
+      for (const spec of specs) view.dispatch(spec);
+    }, []);
+
+    /* -------------------------------- mount ------------------------------- */
+
+    useEffect(() => {
+      const host = hostRef.current;
+      if (!host) return;
+      const p = propsRef.current;
+      const listener = EditorView.updateListener.of((u) => {
+        const cur = propsRef.current;
+        const suggestingNow = isSuggesting(u.state);
+        const byUser = u.transactions.some((tr) => tr.docChanged && !tr.annotation(internalChange));
+        if (byUser) {
+          if (suggestingNow) {
+            touchedRef.current = true;
+            schedule();
+          } else {
+            const text = u.state.doc.toString();
+            const emitted = emittedRef.current;
+            emitted.push(text);
+            if (emitted.length > EMITTED_MEMORY) emitted.shift();
+            cur.onChange?.(text);
+          }
+        }
+        if (u.docChanged || u.transactions.some((tr) => tr.effects.length)) {
+          setUnsaved(!suggestingNow && !trackingOf(u.state).changes.empty);
+          setLocalCount(suggestingNow ? marksOf(u.state).filter((m) => m.kind === 'local').length : 0);
+          setUnplacedOwn(suggestingNow ? ownSuggestions(u.state).overlapping.length : 0);
+        }
+        const nextActive = activeMarkOf(u.state);
+        const prev = activeRef.current;
+        if (nextActive?.id !== prev?.id || nextActive?.description !== prev?.description) {
+          activeRef.current = nextActive;
+          setActive(nextActive);
+          cur.onActiveChange?.(nextActive);
+        }
+        if (u.selectionSet) cur.onSelectionChange?.(selectionAnchorOf(u.state));
+      });
+      // Post on blur from the DOM event itself, NOT from `update.focusChanged`:
+      // CodeMirror reports a focus change with the NEXT update, and when the
+      // reviewer clicks "Suggesting" that next update is the mode switch, so a
+      // focusChanged check would see suggesting mode and post the untouched
+      // text (caught in the browser harness). The event fires at mousedown,
+      // while the mode is still the one the reviewer was typing in.
+      const blurPost = EditorView.domEventHandlers({
+        blur: (_e, v) => {
+          if (isSuggesting(v.state)) void flush();
+          return false;
+        },
+      });
+
+      const k = { ...DEFAULT_KEYS, ...p.keys };
+      const view = new EditorView({
+        parent: host,
+        state: EditorState.create({
+          doc: p.value,
+          extensions: [
+            trackChanges({ keys: k }),
+            compartments.history.of(history()),
+            keymap.of([...defaultKeymap, ...historyKeymap]),
+            EditorView.lineWrapping,
+            compartments.language.of([]),
+            compartments.readOnly.of(EditorState.readOnly.of(true)),
+            compartments.attrs.of([]),
+            baseEditorTheme,
+            listener,
+            blurPost,
+          ],
+        }),
+      });
+      viewRef.current = view;
+      return () => {
+        void flush();
+        view.destroy();
+        viewRef.current = null;
+      };
+      // Mount once; every prop below is applied by its own effect.
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+
+    /* ------------------------ props → editor state ------------------------ */
+
+    useEffect(() => {
+      const view = viewRef.current;
+      if (!view) return;
+      // `markdownLanguage` (GFM) on its own, NOT `markdown()`: the latter also
+      // loads the HTML, CSS and JavaScript grammars and autocomplete to colour
+      // embedded code, which roughly doubles the editor's weight (measured
+      // ~190 KB minified) for prose that has none.
+      const ext: Extension =
+        language === 'markdown'
+          ? [new LanguageSupport(markdownLanguage), syntaxHighlighting(defaultHighlightStyle, { fallback: true })]
+          : [];
+      view.dispatch({ effects: compartments.language.reconfigure(ext) });
+    }, [language, compartments]);
+
+    useEffect(() => {
+      viewRef.current?.dispatch({
+        effects: compartments.attrs.reconfigure(
+          EditorView.contentAttributes.of({ 'aria-label': label, 'aria-describedby': helpId, 'aria-multiline': 'true' }),
+        ),
+      });
+    }, [label, helpId, compartments]);
+
+    useEffect(() => {
+      viewRef.current?.dispatch({ effects: compartments.readOnly.reconfigure(EditorState.readOnly.of(!editable)) });
+    }, [editable, compartments]);
+
+    // The stored value moved: a save echo, or an external change (accept,
+    // another reviewer, restore). Declared before the annotations effect so a
+    // render that changes both rebases first and then paints the new offsets.
+    useEffect(() => {
+      const view = viewRef.current;
+      if (!view) return;
+      const before = view.state.doc.toString();
+      const spec = rebaseOnto(view.state, value, { ownEcho: emittedRef.current.includes(value) });
+      if (!spec) return;
+      view.dispatch(spec);
+      if (isSuggesting(view.state) && lastPostedRef.current === before) {
+        lastPostedRef.current = view.state.doc.toString();
+      }
+    }, [value]);
+
+    useEffect(() => {
+      const view = viewRef.current;
+      if (!view) return;
+      view.dispatch({
+        effects: setAnnotations.of({
+          blame: blame ?? [],
+          suggestions: suggestions ?? [],
+          threads: threads ?? [],
+          currentActorSub,
+          show: { suggestions: show?.suggestions ?? true, comments: show?.comments ?? true, blame: showAuthors },
+        }),
+      });
+      // The reviewer's own suggestions often arrive AFTER suggesting started
+      // (the reads are async). Until they type, reload the proposal from them,
+      // or the first post would supersede and drop them.
+      if (isSuggesting(view.state) && !touchedRef.current) {
+        view.dispatch(leaveSuggesting(view.state));
+        enter(view);
+      }
+    }, [blame, suggestions, threads, currentActorSub, show?.suggestions, show?.comments, showAuthors, enter]);
+
+    useEffect(() => {
+      const view = viewRef.current;
+      if (!view) return;
+      const want = mode === 'suggesting' && canSuggest;
+      const have = isSuggesting(view.state);
+      if (want === have) return;
+      if (want) {
+        if (!trackingOf(view.state).changes.empty) return; // unsaved typing; the switch is disabled
+        enter(view);
+        touchedRef.current = false;
+        setProposal({ state: 'idle' });
+      } else {
+        void flush(); // reads the proposal synchronously, before it is discarded
+        view.dispatch(leaveSuggesting(view.state));
+      }
+      // A fresh undo history per mode: undoing in suggesting mode must never
+      // reach back into edits that were already saved to the field.
+      view.dispatch({ effects: compartments.history.reconfigure([]) });
+      view.dispatch({ effects: compartments.history.reconfigure(history()) });
+    }, [mode, canSuggest, flush, enter, compartments]);
+
+    /* ------------------------------- handle ------------------------------- */
+
+    useImperativeHandle(
+      ref,
+      () => ({
+        get view() {
+          return viewRef.current;
+        },
+        focus: () => viewRef.current?.focus(),
+        nextChange: () => {
+          const v = viewRef.current;
+          const spec = v && moveToMark(v.state, 1, isChangeOrComment);
+          if (!v || !spec) return false;
+          v.dispatch(spec);
+          return true;
+        },
+        prevChange: () => {
+          const v = viewRef.current;
+          const spec = v && moveToMark(v.state, -1, isChangeOrComment);
+          if (!v || !spec) return false;
+          v.dispatch(spec);
+          return true;
+        },
+        focusMark: (id: string) => {
+          const v = viewRef.current;
+          const spec = v && focusMark(v.state, id);
+          if (!v || !spec) return false;
+          v.dispatch(spec);
+          v.focus();
+          return true;
+        },
+        selectionAnchor: () => (viewRef.current ? selectionAnchorOf(viewRef.current.state) : null),
+        flush,
+        proposedText: () => viewRef.current?.state.doc.toString() ?? '',
+      }),
+      [flush],
+    );
+
+    /* ------------------------------- render ------------------------------- */
+
+    const setMode = (m: TrackMode) => {
+      if (m === mode) return;
+      if (modeProp === undefined) setInnerMode(m);
+      onModeChange?.(m);
+    };
+    const toggleAuthors = () => {
+      const next = !showAuthors;
+      if (showAuthorsProp === undefined) setInnerShowAuthors(next);
+      onShowAuthorsChange?.(next);
+    };
+
+    const k = { ...DEFAULT_KEYS, ...keys };
+    const segment = (on: boolean) =>
+      [
+        'rounded px-2.5 py-1 text-sm font-medium transition-colors',
+        'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+        'disabled:cursor-not-allowed disabled:opacity-50',
+        on ? 'bg-secondary text-secondary-foreground' : 'text-muted-foreground hover:text-foreground',
+      ].join(' ');
+
+    const suggestDisabledWhy =
+      version == null
+        ? 'This record has no version yet, so suggestions cannot be anchored.'
+        : !onPropose
+          ? 'Suggestions are not available here.'
+          : unsaved && mode === 'editing'
+            ? 'Your edits are still saving. Suggesting starts from the saved text.'
+            : undefined;
+
+    let proposalLine: string | null = null;
+    if (mode === 'suggesting' && canSuggest) {
+      const n = `${localCount} ${localCount === 1 ? 'change' : 'changes'}`;
+      proposalLine =
+        proposal.state === 'error'
+          ? `Suggestion not sent: ${proposal.message}. It will be retried.`
+          : proposal.state === 'sending'
+            ? `${n}, sending…`
+            : proposal.state === 'pending'
+              ? `${n}, not sent yet`
+              : proposal.state === 'sent'
+                ? `${n}, sent`
+                : n;
+    } else if (mode === 'suggesting' && !canSuggest && !readOnly) {
+      proposalLine = 'You can read this field but not suggest changes to it.';
+    }
+
+    return (
+      <div data-testid="tracked-text-editor" className={['@container flex flex-col gap-2', className].filter(Boolean).join(' ')}>
+        {toolbar && (
+          <div className="flex flex-col gap-2 @md:flex-row @md:items-center @md:justify-between">
+            <div role="group" aria-label="Mode" className="inline-flex w-fit gap-0.5 rounded-md border border-border p-0.5">
+              <button
+                type="button"
+                className={segment(mode === 'editing')}
+                aria-pressed={mode === 'editing'}
+                disabled={!canEdit || readOnly}
+                title={!canEdit ? 'You can suggest changes to this field but not edit it.' : undefined}
+                onClick={() => setMode('editing')}
+              >
+                Editing
+              </button>
+              <button
+                type="button"
+                className={segment(mode === 'suggesting')}
+                aria-pressed={mode === 'suggesting'}
+                disabled={mode !== 'suggesting' && !!suggestDisabledWhy}
+                title={suggestDisabledWhy}
+                onClick={() => setMode('suggesting')}
+              >
+                Suggesting
+              </button>
+            </div>
+            <div className="flex flex-wrap items-center gap-x-3 gap-y-1 text-xs text-muted-foreground">
+              {proposalLine && <span data-testid="proposal-state">{proposalLine}</span>}
+              <button
+                type="button"
+                className={segment(showAuthors)}
+                aria-pressed={showAuthors}
+                onClick={toggleAuthors}
+              >
+                Show authors
+              </button>
+            </div>
+          </div>
+        )}
+        <div
+          ref={hostRef}
+          className={
+            editorClassName ??
+            'rounded-md border border-input bg-background text-sm leading-relaxed focus-within:ring-2 focus-within:ring-ring'
+          }
+        />
+        <p role="status" aria-live="polite" className="min-h-[1rem] text-xs text-muted-foreground">
+          {active?.description ?? ''}
+        </p>
+        <p id={helpId} className="sr-only">
+          {`${keyLabel(k.nextChange)} and ${keyLabel(k.prevChange)} move to the next and previous suggestion or comment. `}
+          {`${keyLabel(k.nextAuthor)} and ${keyLabel(k.prevAuthor)} move between passages by author when authors are shown. `}
+          {'Tab leaves the editor.'}
+        </p>
+        {mode === 'suggesting' && unplacedOwn > 0 && (
+          <p className="text-xs text-foreground">
+            {unplacedOwn === 1
+              ? '1 of your earlier suggestions overlaps another of yours and could not be placed; your next change will replace it.'
+              : `${unplacedOwn} of your earlier suggestions overlap another of yours and could not be placed; your next change will replace them.`}
+          </p>
+        )}
+        {notices?.map((n) => (
+          <p key={n} className="text-xs text-muted-foreground">
+            {n}
+          </p>
+        ))}
+      </div>
+    );
+  },
+);