@startsimpli/ui 0.4.143 → 0.4.144

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

@@ -0,0 +1,293 @@
+'use client';
+
+/**
+ * TrackedField — one text field under track changes: the rendered Read view
+ * or the source editor, show/hide changes, the Current / Final / Original
+ * views, and the changes rail beside it (bd startsim-whwxd.3; design
+ * startsim-xyn25 section d). The page composer, so every foundry that tracks
+ * a field mounts the same thing instead of re-assembling the parts.
+ *
+ * WHAT THE HOST OWNS, and why. Persistence: `onChange` reports edits made in
+ * the source view's EDITING mode, and the host saves them with its own
+ * conditional save. The accept precondition: `runAccept` hands the host a
+ * function that accepts at a version it chooses, so the host can close its
+ * write gate, flush real unsaved typing, accept at its LIVE version and fold
+ * the answer (the new text and version) before anything else writes. A host
+ * that skips the fold would let its next save PATCH the old text back over
+ * the accept.
+ *
+ * WHAT `value` AND `version` MUST BE: the text as stored at `version`, the
+ * version the host's next write will assert. Not unsaved keystrokes (every
+ * offset would describe other text) and not a version loaded once and never
+ * advanced (every read after the first save would be held back as stale).
+ *
+ * LAYOUT on its own container, never the viewport (startsim-jkkn7.12): the
+ * rail sits beside the text when the field is wide, under it when narrow.
+ */
+import { forwardRef, useCallback, useImperativeHandle, useMemo, useRef, useState, type ReactNode, type Ref } from 'react';
+
+import { ChangesRail } from './ChangesRail';
+import { applyOpenSuggestions } from './final-text';
+import { TrackedReadView } from './TrackedReadView';
+import { TrackedTextEditor, type TrackedTextEditorHandle } from './TrackedTextEditor';
+import { useTrackChanges } from './useTrackChanges';
+import type { AcceptResponseWire, SelectionAnchor, TrackChangesClient } from './types';
+
+export type TrackedFieldSurface = 'read' | 'source';
+export type TrackedFieldView = 'current' | 'final' | 'original';
+
+export interface TrackedFieldProps {
+  client: TrackChangesClient;
+  field: string;
+  /** "Blog post". */
+  label: string;
+  language?: 'markdown' | 'plain';
+  /** The stored text at `version`. */
+  value: string;
+  version: number | null;
+  currentActorSub: string | null;
+  /** False: suggest and comment only (view-only reviewers, Quinn Q5). */
+  canEdit?: boolean;
+  /** Source view, editing mode: the whole string after each edit. */
+  onChange?: (value: string) => void;
+  /** See the file header. Default: accept at `version`. */
+  runAccept?: (accept: (expectedVersion: number) => Promise<AcceptResponseWire>) => Promise<unknown>;
+  defaultSurface?: TrackedFieldSurface;
+  /** Extra controls for the header (word count, save state). */
+  headerExtra?: ReactNode;
+  /** The Read view's element, for a host that paints its own highlights. */
+  readViewRef?: Ref<HTMLDivElement>;
+  className?: string;
+}
+
+export interface TrackedFieldHandle {
+  /** Show the source or the rendered text. */
+  setSurface: (s: TrackedFieldSurface) => void;
+  /** Post a pending suggestion now (before a navigation, say). */
+  flush: () => Promise<void>;
+}
+
+const seg = (on: boolean) =>
+  [
+    'inline-flex items-center px-2 py-1 text-xs transition-colors',
+    'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+    on ? 'bg-primary text-primary-foreground' : 'bg-transparent text-muted-foreground hover:bg-muted',
+  ].join(' ');
+
+export const TrackedField = forwardRef<TrackedFieldHandle, TrackedFieldProps>(function TrackedField(
+  {
+    client,
+    field,
+    label,
+    language = 'markdown',
+    value,
+    version,
+    currentActorSub,
+    canEdit = true,
+    onChange,
+    runAccept,
+    defaultSurface,
+    headerExtra,
+    readViewRef,
+    className,
+  },
+  ref,
+) {
+  const tc = useTrackChanges({ client, field, value, version });
+  const [surface, setSurface] = useState<TrackedFieldSurface>(defaultSurface ?? (language === 'markdown' ? 'read' : 'source'));
+  const [view, setView] = useState<TrackedFieldView>('current');
+  const [showChanges, setShowChanges] = useState(true);
+  const [showAuthors, setShowAuthors] = useState(false);
+  const [active, setActive] = useState<string | null>(null);
+  const [selection, setSelection] = useState<SelectionAnchor | null>(null);
+  const editorRef = useRef<TrackedTextEditorHandle>(null);
+
+  useImperativeHandle(
+    ref,
+    () => ({
+      setSurface,
+      flush: async () => {
+        await editorRef.current?.flush();
+      },
+    }),
+    [],
+  );
+
+  const final = useMemo(() => applyOpenSuggestions(value, tc.suggestions), [value, tc.suggestions]);
+
+  const focusItem = useCallback(
+    (id: string) => {
+      setActive(id);
+      if (surface === 'source') editorRef.current?.focusMark(id);
+    },
+    [surface],
+  );
+
+  const accept = tc.actions.accept;
+  const onAccept = accept
+    ? async (ids: string[]) => {
+        const doAccept = (v: number) => accept(ids, v);
+        if (runAccept) await runAccept(doAccept);
+        else if (version != null) await doAccept(version);
+        else throw new Error('This record has no version yet, so nothing can be accepted.');
+      }
+    : undefined;
+
+  const onComment = tc.actions.comment
+    ? async (body: string, mentions: string[], sel: SelectionAnchor | null) => {
+        const span = sel && sel.to > sel.from && version != null;
+        await tc.actions.comment!({
+          body,
+          field,
+          ...(mentions.length ? { mentions } : {}),
+          ...(span ? { from: sel!.from, to: sel!.to, base_version: version! } : {}),
+        });
+        setSelection(null);
+      }
+    : undefined;
+
+  const marked = view === 'current';
+  const readSource = view === 'final' ? final.text : value;
+  const nSugg = tc.suggestions.filter((s) => s.status === 'open').length;
+
+  return (
+    <section
+      data-testid={`tracked-field-${field}`}
+      aria-label={label}
+      className={['@container rounded-lg border border-border bg-card', className].filter(Boolean).join(' ')}
+    >
+      <div className="flex flex-col gap-2 border-b border-border px-4 py-2 @lg:flex-row @lg:flex-wrap @lg:items-center @lg:justify-between">
+        <h3 className="text-xs font-semibold uppercase tracking-wide text-muted-foreground">{label}</h3>
+        <div className="flex flex-wrap items-center gap-2">
+          {headerExtra}
+          <div role="group" aria-label={`${label}: which text`} className="inline-flex overflow-hidden rounded-md border border-border">
+            <button type="button" className={seg(view === 'current')} aria-pressed={view === 'current'} onClick={() => setView('current')}>
+              Current
+            </button>
+            <button
+              type="button"
+              className={seg(view === 'final')}
+              aria-pressed={view === 'final'}
+              onClick={() => setView('final')}
+              title="As it would read with every open suggestion accepted"
+            >
+              Final
+            </button>
+            <button
+              type="button"
+              className={seg(view === 'original')}
+              aria-pressed={view === 'original'}
+              onClick={() => setView('original')}
+              title="As stored, without any suggestion"
+            >
+              Original
+            </button>
+          </div>
+          {marked && (
+            <div role="group" aria-label={`${label}: surface`} className="inline-flex overflow-hidden rounded-md border border-border">
+              <button type="button" className={seg(surface === 'read')} aria-pressed={surface === 'read'} onClick={() => setSurface('read')}>
+                Read
+              </button>
+              <button type="button" className={seg(surface === 'source')} aria-pressed={surface === 'source'} onClick={() => setSurface('source')}>
+                {canEdit ? 'Edit' : 'Suggest'}
+              </button>
+            </div>
+          )}
+          {marked && (
+            <button type="button" className={`${seg(showChanges)} rounded-md border border-border`} aria-pressed={showChanges} onClick={() => setShowChanges((v) => !v)}>
+              Show changes
+            </button>
+          )}
+          {marked && surface === 'read' && (
+            <button type="button" className={`${seg(showAuthors)} rounded-md border border-border`} aria-pressed={showAuthors} onClick={() => setShowAuthors((v) => !v)}>
+              Show authors
+            </button>
+          )}
+        </div>
+      </div>
+
+      <div className="grid gap-4 p-4 @3xl:grid-cols-[minmax(0,1fr)_18rem]">
+        <div className="min-w-0">
+          {!marked ? (
+            <>
+              <p className="mb-2 text-xs text-muted-foreground" role="status">
+                {view === 'final'
+                  ? `Final: as it would read with ${final.applied.length} open ${final.applied.length === 1 ? 'suggestion' : 'suggestions'} accepted.` +
+                    (final.skipped.length
+                      ? ` ${final.skipped.length} overlapping ${final.skipped.length === 1 ? 'suggestion is' : 'suggestions are'} not included.`
+                      : '')
+                  : `Original: as stored, without ${nSugg === 1 ? 'the open suggestion' : `the ${nSugg} open suggestions`}.`}
+              </p>
+              <TrackedReadView ref={readViewRef} source={readSource} language={language} showChanges={false} />
+            </>
+          ) : surface === 'read' ? (
+            <TrackedReadView
+              ref={readViewRef}
+              source={value}
+              language={language}
+              blame={tc.blame}
+              suggestions={tc.suggestions}
+              threads={tc.threads}
+              showChanges={showChanges}
+              showAuthors={showAuthors}
+              activeId={active}
+              onActivate={(id) => {
+                setActive(id);
+                const item = document.querySelector<HTMLElement>(`[data-testid="tracked-field-${field}"] [data-item-id="${id}"]`);
+                item?.focus();
+              }}
+              onSelectionChange={setSelection}
+            />
+          ) : (
+            <TrackedTextEditor
+              ref={editorRef}
+              label={label}
+              language={language}
+              value={value}
+              version={version}
+              canEdit={canEdit}
+              currentActorSub={currentActorSub}
+              blame={tc.blame}
+              suggestions={tc.suggestions}
+              threads={tc.threads}
+              notices={[]}
+              show={{ suggestions: showChanges, comments: showChanges }}
+              showAuthors={showAuthors}
+              onShowAuthorsChange={setShowAuthors}
+              onChange={onChange}
+              onPropose={tc.propose}
+              onActiveChange={(m) => setActive(m && m.kind !== 'blame' && m.kind !== 'local' ? m.id : null)}
+              onSelectionChange={setSelection}
+            />
+          )}
+          {tc.notices.map((n) => (
+            <p key={n} className="mt-2 text-xs text-muted-foreground">
+              {n}
+            </p>
+          ))}
+        </div>
+        <ChangesRail
+          fieldLabel={label}
+          suggestions={tc.suggestions}
+          threads={tc.threads}
+          currentActorSub={currentActorSub}
+          canAccept={canEdit}
+          activeId={active}
+          onFocusItem={focusItem}
+          onNextChange={surface === 'source' && marked ? () => editorRef.current?.nextChange() : undefined}
+          onPrevChange={surface === 'source' && marked ? () => editorRef.current?.prevChange() : undefined}
+          onAccept={canEdit ? onAccept : undefined}
+          onReject={canEdit ? tc.actions.reject : undefined}
+          onWithdraw={tc.actions.withdraw}
+          onComment={onComment}
+          onReply={tc.actions.reply}
+          onResolve={tc.actions.resolve}
+          onReopen={tc.actions.reopen}
+          selection={selection}
+          mentionable={tc.mentionable}
+          mentionNotice={tc.rosterNotice}
+        />
+      </div>
+    </section>
+  );
+});

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

@@ -0,0 +1,273 @@
+'use client';
+
+/**
+ * TrackedReadView — the rendered Read view with track-changes marks drawn over
+ * it (bd startsim-whwxd.3; design startsim-xyn25 section d).
+ *
+ * Markdown goes through the shared MarkdownRenderer with the
+ * {@link rehypeTrackMarks} transform; plain text (LinkedIn) is one text node
+ * through the SAME transform, so both fields mark identically.
+ *
+ * WHAT WORKS HERE. Clicking a mark selects it (`onActivate`) so the rail can
+ * offer accept/reject/reply for it; selecting text reports a source anchor
+ * (`onSelectionChange`) for "comment on selection". Editing is not offered in
+ * the Read view; that is the source view's job.
+ *
+ * WHAT IT WILL NOT DO is draw a mark somewhere it cannot prove. Anything that
+ * could not be placed (inside code, or in text whose rendering cannot be
+ * aligned to its source) is counted in a line under the text, and it is still
+ * in the rail and in the source view.
+ */
+import { forwardRef, useCallback, useEffect, useMemo, useRef, useState, type ReactNode } from 'react';
+
+import { MarkdownRenderer } from '../blog/MarkdownRenderer';
+import { describeBlame, describeSuggestion, describeThread } from './describe';
+import { anchorFor } from './normalize';
+import { markTree, plainTree, rehypeTrackMarks, sourceOffsetOf, type HastNode, type ReadMark } from './read-marks';
+import type { BlameSpan, CommentThread, SelectionAnchor, Suggestion } from './types';
+
+export interface TrackedReadViewProps {
+  /** The text to render: the stored string, or a Final/Original preview. */
+  source: string;
+  language?: 'markdown' | 'plain';
+  blame?: BlameSpan[];
+  suggestions?: Suggestion[];
+  threads?: CommentThread[];
+  /** Draw suggestions and comments. Default true. */
+  showChanges?: boolean;
+  /** Draw authorship. Default false. */
+  showAuthors?: boolean;
+  /** The mark the rail has selected; drawn with an outline. */
+  activeId?: string | null;
+  onActivate?: (id: string) => void;
+  onSelectionChange?: (anchor: SelectionAnchor | null) => void;
+  className?: string;
+  /** Shown when `source` is empty. */
+  emptyText?: string;
+}
+
+/** Stable tint per author: eight hues, picked by a hash of the key. */
+const TINTS = [
+  'tc-author-0',
+  'tc-author-1',
+  'tc-author-2',
+  'tc-author-3',
+  'tc-author-4',
+  'tc-author-5',
+  'tc-author-6',
+  'tc-author-7',
+];
+
+export function authorTint(key: string): string {
+  let h = 0;
+  for (let i = 0; i < key.length; i++) h = (h * 31 + key.charCodeAt(i)) | 0;
+  return TINTS[Math.abs(h) % TINTS.length];
+}
+
+/** The marks to draw, in source offsets. */
+export function readMarksOf({
+  blame = [],
+  suggestions = [],
+  threads = [],
+  showChanges = true,
+  showAuthors = false,
+}: Pick<TrackedReadViewProps, 'blame' | 'suggestions' | 'threads' | 'showChanges' | 'showAuthors'>): ReadMark[] {
+  const out: ReadMark[] = [];
+  if (showAuthors) {
+    for (const b of blame) {
+      const key = b.author ? b.author.sub || b.author.label : '';
+      out.push({
+        id: b.id,
+        kind: 'blame',
+        from: b.from,
+        to: b.to,
+        title: describeBlame(b),
+        className: b.author ? (b.author.kind === 'machine' ? 'tc-author-machine' : authorTint(key)) : 'tc-author-unknown',
+      });
+    }
+  }
+  if (showChanges) {
+    for (const s of suggestions) {
+      if (s.status !== 'open' || s.anchorState === 'orphaned') continue;
+      out.push({ id: s.id, kind: 'suggestion', from: s.from, to: s.to, title: describeSuggestion(s), insert: s.replacement });
+    }
+    for (const t of threads) {
+      if (t.resolved || t.anchorState === 'orphaned' || t.from == null || t.to == null || t.to <= t.from) continue;
+      out.push({ id: t.id, kind: 'comment', from: t.from, to: t.to, title: describeThread(t) });
+    }
+  }
+  return out;
+}
+
+/* ---------------------------- hast -> React ------------------------------ */
+
+const ALLOWED = new Set(['span', 'del', 'ins', 'mark', 'div', 'p', 'br']);
+
+function propsOf(p: Record<string, unknown> | undefined): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  if (!p) return out;
+  for (const [k, v] of Object.entries(p)) {
+    if (k === 'className') out.className = Array.isArray(v) ? v.join(' ') : String(v);
+    else if (k.startsWith('data')) out[`data-${k.slice(4).replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`).replace(/^-/, '')}`] = String(v);
+    else if (k === 'title') out.title = String(v);
+  }
+  return out;
+}
+
+/** Renders the transform's own output (plain fields only). */
+export function renderHast(node: HastNode, key = 'n'): ReactNode {
+  if (node.type === 'text') return (node as { value: string }).value;
+  const kids = ((node as { children?: HastNode[] }).children ?? []).map((c, i) => renderHast(c, `${key}.${i}`));
+  if (node.type === 'root') return kids;
+  const tag = (node as { tagName?: string }).tagName ?? 'span';
+  const Tag = (ALLOWED.has(tag) ? tag : 'span') as 'span';
+  return (
+    <Tag key={key} {...propsOf((node as { properties?: Record<string, unknown> }).properties)}>
+      {kids}
+    </Tag>
+  );
+}
+
+export const TrackedReadView = forwardRef<HTMLDivElement, TrackedReadViewProps>(function TrackedReadView(
+  {
+    source,
+    language = 'markdown',
+    blame,
+    suggestions,
+    threads,
+    showChanges = true,
+    showAuthors = false,
+    activeId,
+    onActivate,
+    onSelectionChange,
+    className,
+    emptyText = 'Nothing to show yet.',
+  },
+  ref,
+) {
+  const marks = useMemo(
+    () => readMarksOf({ blame, suggestions, threads, showChanges, showAuthors }),
+    [blame, suggestions, threads, showChanges, showAuthors],
+  );
+  // What the markdown transform drew, as a sorted id list. The transform runs
+  // inside the renderer on every render and makes a new Set each time, so it
+  // is compared by CONTENT, or the state write would loop.
+  const [placedKey, setPlacedKey] = useState<string | null>(null);
+  const placedRef = useRef<Set<string> | null>(null);
+
+  // Plain text is transformed here; markdown inside the renderer's pipeline.
+  const plain = useMemo(() => {
+    if (language !== 'plain') return null;
+    const tree = plainTree(source);
+    const r = markTree(tree, source, marks);
+    return { tree, placed: r.placed };
+  }, [language, source, marks]);
+
+  const onPlaced = useCallback((p: Set<string>) => {
+    placedRef.current = p;
+  }, []);
+  const plugins = useMemo(
+    () => (language === 'markdown' ? [rehypeTrackMarks({ source, marks, onPlaced })] : undefined),
+    [language, source, marks, onPlaced],
+  );
+
+  useEffect(() => {
+    if (plain || !placedRef.current) return;
+    const k = [...placedRef.current].sort().join('\u0000');
+    if (k !== placedKey) setPlacedKey(k);
+  });
+  const placedNow = plain
+    ? plain.placed
+    : placedKey == null
+      ? null
+      : new Set(placedKey ? placedKey.split('\u0000') : []);
+  const unplaced = marks.filter((m) => m.kind !== 'blame' && placedNow && !placedNow.has(m.id)).length;
+
+  const hostRef = useRef<HTMLDivElement | null>(null);
+  const setRefs = (el: HTMLDivElement | null) => {
+    hostRef.current = el;
+    if (typeof ref === 'function') ref(el);
+    else if (ref) ref.current = el;
+  };
+
+  const reportSelection = () => {
+    if (!onSelectionChange) return;
+    const sel = typeof window !== 'undefined' ? window.getSelection() : null;
+    const host = hostRef.current;
+    if (!sel || sel.isCollapsed || !host || !sel.anchorNode || !host.contains(sel.anchorNode)) {
+      onSelectionChange(null);
+      return;
+    }
+    const a = sourceOffsetOf(sel.anchorNode, sel.anchorOffset);
+    const b = sourceOffsetOf(sel.focusNode, sel.focusOffset);
+    if (a == null || b == null || a === b) {
+      onSelectionChange(null);
+      return;
+    }
+    onSelectionChange(anchorFor(source, a, b));
+  };
+
+  const onClick = (e: React.MouseEvent) => {
+    const hit = (e.target as Element | null)?.closest?.('[data-tc-id]');
+    const id = hit?.getAttribute('data-tc-id');
+    if (id && onActivate) onActivate(id);
+  };
+
+  const activeStyle = activeId
+    ? `[data-tc-read] [data-tc-id="${CSS_ESCAPE(activeId)}"]{outline:2px solid currentColor;outline-offset:1px;border-radius:2px}`
+    : '';
+
+  return (
+    <div
+      ref={setRefs}
+      data-tc-read=""
+      data-testid="tracked-read-view"
+      className={className}
+      onClick={onClick}
+      onMouseUp={reportSelection}
+      onKeyUp={reportSelection}
+    >
+      {/* Static, author-written CSS plus an id that is escaped. */}
+      <style>{READ_STYLE + activeStyle}</style>
+      {!source ? (
+        <p className="text-sm italic text-muted-foreground">{emptyText}</p>
+      ) : plain ? (
+        <div className="whitespace-pre-wrap break-words text-sm leading-relaxed text-foreground">{renderHast(plain.tree)}</div>
+      ) : (
+        <MarkdownRenderer content={source} rehypePlugins={plugins} />
+      )}
+      {unplaced > 0 && (
+        <p className="mt-2 text-xs text-muted-foreground">
+          {unplaced === 1
+            ? '1 suggestion or comment cannot be drawn on the rendered text (it sits in code or formatting). It is in the list, and in the source view.'
+            : `${unplaced} suggestions or comments cannot be drawn on the rendered text (they sit in code or formatting). They are in the list, and in the source view.`}
+        </p>
+      )}
+    </div>
+  );
+});
+
+function CSS_ESCAPE(s: string): string {
+  return s.replace(/["\\\n\r]/g, (c) => `\\${c.charCodeAt(0).toString(16)} `);
+}
+
+/**
+ * The marks' paint. Tokens where the theme has them; the author tints are
+ * fixed hues at low alpha so they read on light and dark backgrounds.
+ */
+export const READ_STYLE = [
+  '[data-tc-read] .tc-read-suggestion{text-decoration:line-through;text-decoration-color:rgb(220 38 38);background:rgb(220 38 38 / .10);cursor:pointer}',
+  '[data-tc-read] .tc-read-ins{text-decoration:underline;text-decoration-color:rgb(22 163 74);background:rgb(22 163 74 / .12);color:inherit;cursor:pointer}',
+  '[data-tc-read] .tc-read-comment{background:rgb(234 179 8 / .30);color:inherit;cursor:pointer;border-bottom:2px solid rgb(234 179 8)}',
+  '[data-tc-read] .tc-read-blame{box-shadow:inset 0 -2px 0 var(--tc-tint,transparent)}',
+  '[data-tc-read] .tc-author-0{--tc-tint:rgb(59 130 246 / .7)}',
+  '[data-tc-read] .tc-author-1{--tc-tint:rgb(168 85 247 / .7)}',
+  '[data-tc-read] .tc-author-2{--tc-tint:rgb(20 184 166 / .7)}',
+  '[data-tc-read] .tc-author-3{--tc-tint:rgb(249 115 22 / .7)}',
+  '[data-tc-read] .tc-author-4{--tc-tint:rgb(236 72 153 / .7)}',
+  '[data-tc-read] .tc-author-5{--tc-tint:rgb(132 204 22 / .7)}',
+  '[data-tc-read] .tc-author-6{--tc-tint:rgb(14 165 233 / .7)}',
+  '[data-tc-read] .tc-author-7{--tc-tint:rgb(234 88 12 / .7)}',
+  '[data-tc-read] .tc-author-machine{--tc-tint:rgb(100 116 139 / .9);background:rgb(100 116 139 / .08)}',
+  '[data-tc-read] .tc-author-unknown{--tc-tint:rgb(148 163 184 / .5)}',
+].join('');