@bendyline/squisq-editor-react 1.6.2 → 2.0.1

package/src/timeline/timelineCommands.ts

@@ -0,0 +1,421 @@
+/**
+ * Write direction for the WYSIWYG timeline editor:
+ *
+ *   fence text -> parse -> pure op -> render -> verify -> one fence rewrite
+ *
+ * The original code block remains the source of truth and every successful
+ * edit is a single ProseMirror transaction/undo step.
+ */
+
+import type { Editor } from '@tiptap/react';
+import {
+  isWrappedFlowTimelineSource,
+  parseAsciiTimeline,
+  renderAsciiTimeline,
+  type AsciiTimeline,
+  type AsciiTimelineMarker,
+  type AsciiTimelineSide,
+} from '@bendyline/squisq/doc';
+import { replaceAsciiFenceText } from '../asciiDiagram/asciiDiagramCommands';
+import { findTimelineBlockPos, parseTimelineForNode } from './TimelineViewExtension';
+import {
+  addTimelineTrackOp,
+  addTimelineEventOp,
+  removeTimelineTrackOp,
+  removeTimelineEventOp,
+  sanitizeTimelineText,
+  updateTimelineTrackOp,
+  updateTimelineEventOp,
+  type TimelineEventPatch,
+} from './timelineOps';
+
+export type TimelineCommand =
+  | {
+      kind: 'addTrack';
+      id?: string;
+      label?: string;
+      eventId?: string;
+      eventLabel?: string;
+    }
+  | { kind: 'updateTrack'; trackId: string; label: string }
+  | { kind: 'removeTrack'; trackId: string }
+  | {
+      kind: 'addEvent';
+      trackId: string;
+      /** Normalized position on the global timeline rail. */
+      position: number;
+      id?: string;
+      label?: string;
+      description?: string;
+      side?: AsciiTimelineSide;
+      descriptionSide?: AsciiTimelineSide;
+      callout?: boolean;
+      marker?: AsciiTimelineMarker;
+    }
+  | { kind: 'updateEvent'; eventId: string; patch: TimelineEventPatch }
+  | { kind: 'removeEvent'; eventId: string };
+
+export interface TimelineCommandResult {
+  applied: boolean;
+  /** Present after add so the widget can select/focus the new marker. */
+  eventId?: string;
+  /** Present after adding a track. */
+  trackId?: string;
+  /** Why an otherwise valid semantic edit was deliberately blocked. */
+  reason?: 'read-only' | 'unsafe-source';
+}
+
+interface OpResult {
+  timeline: AsciiTimeline;
+  eventId?: string;
+  trackId?: string;
+}
+
+const NOT_APPLIED: TimelineCommandResult = { applied: false };
+const READ_ONLY: TimelineCommandResult = { applied: false, reason: 'read-only' };
+const UNSAFE_SOURCE: TimelineCommandResult = { applied: false, reason: 'unsafe-source' };
+
+function countEvents(timeline: AsciiTimeline): number {
+  return timeline.tracks.reduce((sum, track) => sum + track.events.length, 0);
+}
+
+function hasEvent(timeline: AsciiTimeline, eventId: string): boolean {
+  return timeline.tracks.some((track) => track.events.some((event) => event.id === eventId));
+}
+
+function hasTrack(timeline: AsciiTimeline, trackId: string): boolean {
+  return timeline.tracks.some((track) => track.id === trackId);
+}
+
+/**
+ * Layout rows and source dimensions are deliberately absent: canonical
+ * rendering is allowed to compact hand-authored art. Everything the editor
+ * can semantically preserve is included, so this signature can distinguish
+ * harmless layout normalization from content loss.
+ */
+function semanticSignature(timeline: AsciiTimeline): string {
+  return JSON.stringify({
+    style: timeline.style,
+    tracks: timeline.tracks.map((track) => ({
+      id: track.id,
+      label: track.label,
+      endLabel: track.endLabel,
+      startColumn: track.startColumn,
+      endColumn: track.endColumn,
+      events: track.events.map((event) => ({
+        id: event.id,
+        label: event.label,
+        description: event.description,
+        column: event.column,
+        side: event.side,
+        descriptionSide: event.descriptionSide,
+        callout: event.callout,
+        marker: event.marker,
+      })),
+    })),
+    links: timeline.links,
+    warnings: timeline.warnings,
+  });
+}
+
+const METADATA_BLOCK_RE = /\{([^{}\r\n]*)\}/gu;
+const METADATA_ATTEMPT_RE = /^(?:#[^\s{}]*|[A-Za-z][A-Za-z0-9]*=)/u;
+const MALFORMED_METADATA_RE =
+  /(?:\{[^{}\r\n]*(?:#[^\s{}]+|[A-Za-z][A-Za-z0-9]*=)|(?:#[^\s{}]+|[A-Za-z][A-Za-z0-9]*=)[^{}\r\n]*\})/u;
+const UNICODE_MARKER_RE = /[●○◉◆◇•]/u;
+const ASCII_MARKERS = new Set(['*', 'o', 'O']);
+const RAIL_CHARS = new Set(['─', '━', '═', '╌', '╍', '┄', '┅', '┈', '┉', '-']);
+const STRUCTURAL_CHARS_RE = /[─━═╌╍┄┅┈┉●○◉◆◇•►▶▷→>▲△▼▽│|└┌├┬┘┐╰╭╯╮:\-*]/gu;
+const SEMANTIC_LEXEME_RE = /[\p{L}\p{N}_]+|[^\s]/gu;
+
+type MetadataKind = 'track' | 'event';
+
+/**
+ * Validate every metadata block that the parser could consume, then replace
+ * it with whitespace for source-content comparison. The parser deliberately
+ * accepts recognized tokens from a mixed block and ignores the rest; the
+ * editor must be stricter or `{#id unknown}` would be silently normalized.
+ */
+function validateAndStripMetadata(source: string, timeline: AsciiTimeline): string | null {
+  const trackRows = new Set(timeline.tracks.map((track) => track.row));
+  const lines = source.replace(/\r\n?/g, '\n').split('\n');
+
+  for (let row = 0; row < lines.length; row++) {
+    const line = lines[row];
+    const trackRow = trackRows.has(row);
+    const pointerRow = /[▲△▼▽^v]/u.test(line);
+    if (!trackRow && !pointerRow) continue;
+    const firstMarker = trackRow ? firstAxisMarkerOffset(line, timeline.style) : -1;
+    let valid = true;
+    const stripped = line.replace(METADATA_BLOCK_RE, (block, inner: string, offset: number) => {
+      const tokens = inner.trim() ? inner.trim().split(/\s+/u) : [];
+      if (!tokens.some((token) => METADATA_ATTEMPT_RE.test(token))) return block;
+      const kind: MetadataKind =
+        trackRow && firstMarker >= 0 && offset < firstMarker ? 'track' : 'event';
+      if (!isValidMetadata(tokens, kind)) valid = false;
+      return ' '.repeat(block.length);
+    });
+    // A missing/opening brace prevents METADATA_BLOCK_RE from seeing the
+    // block at all. Reject the remaining metadata-shaped fragment as well.
+    if (!valid || MALFORMED_METADATA_RE.test(stripped)) return null;
+    lines[row] = stripped;
+  }
+  return lines.join('\n');
+}
+
+function isValidMetadata(tokens: readonly string[], kind: MetadataKind): boolean {
+  if (tokens.length === 0) return false;
+  const seen = new Set<string>();
+  for (const token of tokens) {
+    let key: string;
+    let valid = false;
+    if (token.startsWith('#') && token.length > 1) {
+      key = '#';
+      valid = !/[{}\s]/u.test(token.slice(1));
+    } else {
+      const separator = token.indexOf('=');
+      key = separator > 0 ? token.slice(0, separator) : token;
+      const value = separator > 0 ? token.slice(separator + 1) : '';
+      if (kind === 'track' && (key === 'start' || key === 'end')) {
+        valid = value.trim() !== '' && Number.isFinite(Number(value));
+      } else if (kind === 'event' && key === 'side') {
+        valid = value === 'above' || value === 'below';
+      } else if (kind === 'event' && key === 'descriptionSide') {
+        valid = value === 'above' || value === 'below';
+      } else if (kind === 'event' && key === 'column') {
+        valid = value.trim() !== '' && Number.isFinite(Number(value));
+      } else if (kind === 'event' && key === 'callout') {
+        valid = value === 'true' || value === 'false';
+      }
+    }
+    if (!valid || seen.has(key)) return false;
+    seen.add(key);
+  }
+  return true;
+}
+
+function firstAxisMarkerOffset(line: string, style: AsciiTimeline['style']): number {
+  if (style === 'unicode') return line.search(UNICODE_MARKER_RE);
+  for (let index = 0; index < line.length; index++) {
+    if (!ASCII_MARKERS.has(line[index])) continue;
+    const leftRail = railRun(line, index, -1);
+    const rightRail = railRun(line, index, 1);
+    const beforeIsWord = /[\p{L}\p{N}_]/u.test(line[index - 1] ?? '');
+    const afterIsWord = /[\p{L}\p{N}_]/u.test(line[index + 1] ?? '');
+    if ((leftRail >= 2 && !afterIsWord) || (rightRail >= 2 && !beforeIsWord)) return index;
+  }
+  return -1;
+}
+
+function railRun(line: string, index: number, direction: -1 | 1): number {
+  let count = 0;
+  for (let cursor = index + direction; RAIL_CHARS.has(line[cursor] ?? ''); cursor += direction) {
+    count++;
+  }
+  return count;
+}
+
+function semanticLexemeCounts(text: string): Map<string, number> {
+  const counts = new Map<string, number>();
+  const prose = text.normalize('NFC').replace(STRUCTURAL_CHARS_RE, ' ');
+  for (const match of prose.matchAll(SEMANTIC_LEXEME_RE)) {
+    const lexeme = match[0].toLocaleLowerCase();
+    counts.set(lexeme, (counts.get(lexeme) ?? 0) + 1);
+  }
+  return counts;
+}
+
+function countsEqual(
+  left: ReadonlyMap<string, number>,
+  right: ReadonlyMap<string, number>,
+): boolean {
+  if (left.size !== right.size) return false;
+  for (const [lexeme, count] of left) {
+    if (right.get(lexeme) !== count) return false;
+  }
+  return true;
+}
+
+function hasUnrepresentedStructuralOnlyLine(source: string, timeline: AsciiTimeline): boolean {
+  const trackRows = new Set(timeline.tracks.map((track) => track.row));
+  const lines = source.split('\n');
+  for (let row = 0; row < lines.length; row++) {
+    if (!lines[row].trim() || trackRows.has(row)) continue;
+    if (semanticLexemeCounts(lines[row]).size === 0) return true;
+  }
+  return false;
+}
+
+/**
+ * Semantic operations replace the whole fence with canonical rendered art.
+ * Fail closed when that would discard source the timeline model cannot
+ * represent. Warnings catch unresolved/unlabeled constructs; the semantic
+ * round-trip catches renderer normalization that changes modeled content;
+ * exact metadata validation rejects partially consumed attrs; and a linear
+ * semantic-residue comparison catches ignored prose/symbol rows without
+ * reparsing a successively shorter document for every source line.
+ */
+export function isTimelineSourceSafeForSemanticEdit(
+  source: string,
+  timeline: AsciiTimeline,
+): boolean {
+  if (timeline.warnings.length > 0) return false;
+
+  const rendered = renderAsciiTimeline(timeline);
+  if (!rendered) return false;
+  const reparsed = parseAsciiTimeline(rendered);
+  const signature = semanticSignature(timeline);
+  if (reparsed.warnings.length > 0 || semanticSignature(reparsed) !== signature) return false;
+  // Wrapped-flow acceptance is deliberately all-or-nothing: its parser only
+  // returns a model when every nonblank row is represented. Once the model
+  // also survives the canonical render/parse signature above, the differing
+  // source vocabulary (lane headings and wrap connectors versus point
+  // metadata) is safe to normalize on the first visual edit.
+  if (isWrappedFlowTimelineSource(source)) return true;
+
+  const strippedSource = validateAndStripMetadata(source, timeline);
+  const strippedRendered = validateAndStripMetadata(rendered, reparsed);
+  if (!strippedSource || !strippedRendered) return false;
+  if (hasUnrepresentedStructuralOnlyLine(strippedSource, timeline)) return false;
+  return countsEqual(semanticLexemeCounts(strippedSource), semanticLexemeCounts(strippedRendered));
+}
+
+/**
+ * Verify the renderer/parser boundary before changing the document. Rows and
+ * source dimensions intentionally are not compared: canonical rendering
+ * compacts authored multi-line art while preserving its semantic content.
+ */
+function verifyRenderedTimeline(next: AsciiTimeline, rendered: string): AsciiTimeline | null {
+  if (!rendered) return null;
+  const verification = parseAsciiTimeline(rendered);
+  if (renderAsciiTimeline(verification) !== rendered) return null;
+  if (verification.tracks.length !== next.tracks.length) return null;
+  if (countEvents(verification) !== countEvents(next)) return null;
+  if (verification.links.length !== next.links.length) return null;
+
+  const ids = new Set(
+    verification.tracks.flatMap((track) => track.events.map((event) => event.id)),
+  );
+  const trackIds = new Set(verification.tracks.map((track) => track.id));
+  if (trackIds.size !== verification.tracks.length) return null;
+  if (ids.size !== countEvents(verification)) return null;
+  if (verification.links.some((link) => !ids.has(link.source) || !ids.has(link.target))) {
+    return null;
+  }
+  return verification;
+}
+
+function applyOp(
+  editor: Editor,
+  blockId: string,
+  op: (timeline: AsciiTimeline) => OpResult | null,
+  verifyResult?: (timeline: AsciiTimeline) => boolean,
+): TimelineCommandResult {
+  // Resolve at dispatch time; captured ProseMirror positions become stale as
+  // soon as content above the fence changes.
+  const pos = findTimelineBlockPos(editor, blockId);
+  if (pos === null) return NOT_APPLIED;
+  const node = editor.state.doc.nodeAt(pos);
+  if (!node || node.type.name !== 'codeBlock') return NOT_APPLIED;
+  const timeline = parseTimelineForNode(node);
+  if (!timeline) return NOT_APPLIED;
+  if (!isTimelineSourceSafeForSemanticEdit(node.textContent, timeline)) return UNSAFE_SOURCE;
+
+  const result = op(timeline);
+  if (!result || result.timeline === timeline) return NOT_APPLIED;
+  const rendered = renderAsciiTimeline(result.timeline);
+  const verification = verifyRenderedTimeline(result.timeline, rendered);
+  if (
+    !verification ||
+    (result.eventId && !hasEvent(verification, result.eventId)) ||
+    (result.trackId && !hasTrack(verification, result.trackId)) ||
+    (verifyResult && !verifyResult(verification))
+  ) {
+    return NOT_APPLIED;
+  }
+
+  // Promoting to the explicit language makes an edited timeline sticky over
+  // Markdown <-> Tiptap round trips. Text + attrs change in one undo step.
+  if (!replaceAsciiFenceText(editor, pos, rendered, 'timeline')) return NOT_APPLIED;
+  return {
+    applied: true,
+    ...(result.eventId ? { eventId: result.eventId } : {}),
+    ...(result.trackId ? { trackId: result.trackId } : {}),
+  };
+}
+
+/** Apply one semantic timeline command to a registered fence block. */
+export function applyTimelineCommand(
+  editor: Editor,
+  blockId: string,
+  command: TimelineCommand,
+): TimelineCommandResult {
+  // Commands may outlive the render that created their controls. Enforce the
+  // editor's current authority at dispatch time, not only in widget props.
+  if (!editor.isEditable) return READ_ONLY;
+
+  switch (command.kind) {
+    case 'addTrack':
+      return applyOp(editor, blockId, (timeline) =>
+        addTimelineTrackOp(timeline, {
+          id: command.id,
+          label: command.label,
+          eventId: command.eventId,
+          eventLabel: command.eventLabel,
+        }),
+      );
+    case 'updateTrack': {
+      const expectedLabel = sanitizeTimelineText(command.label);
+      return applyOp(
+        editor,
+        blockId,
+        (timeline) => ({
+          timeline: updateTimelineTrackOp(timeline, command.trackId, command.label),
+        }),
+        (timeline) =>
+          timeline.tracks.some(
+            (track) => track.id === command.trackId && track.label === expectedLabel,
+          ),
+      );
+    }
+    case 'removeTrack':
+      return applyOp(
+        editor,
+        blockId,
+        (timeline) => ({ timeline: removeTimelineTrackOp(timeline, command.trackId) }),
+        (timeline) => !hasTrack(timeline, command.trackId),
+      );
+    case 'addEvent':
+      return applyOp(editor, blockId, (timeline) => {
+        const result = addTimelineEventOp(timeline, command.trackId, command.position, {
+          id: command.id,
+          label: command.label,
+          description: command.description,
+          side: command.side,
+          descriptionSide: command.descriptionSide,
+          callout: command.callout,
+          marker: command.marker,
+        });
+        return result;
+      });
+    case 'updateEvent':
+      return applyOp(
+        editor,
+        blockId,
+        (timeline) => ({
+          timeline: updateTimelineEventOp(timeline, command.eventId, command.patch),
+        }),
+        (timeline) => hasEvent(timeline, command.eventId),
+      );
+    case 'removeEvent':
+      return applyOp(
+        editor,
+        blockId,
+        (timeline) => ({ timeline: removeTimelineEventOp(timeline, command.eventId) }),
+        (timeline) => !hasEvent(timeline, command.eventId),
+      );
+  }
+  const exhaustive: never = command;
+  void exhaustive;
+  return NOT_APPLIED;
+}

package/src/timeline/timelineData.ts

@@ -0,0 +1,54 @@
+/** Live read-direction adapter from a registered timeline fence to React. */
+
+import { useEffect, useMemo, useRef, useState } from 'react';
+import type { Editor } from '@tiptap/react';
+import type { AsciiTimeline } from '@bendyline/squisq/doc';
+import { findTimelineBlockPos, parseTimelineForNode } from './TimelineViewExtension';
+
+export interface TimelineViewData {
+  timeline: AsciiTimeline;
+  text: string;
+  warnings: string[];
+}
+
+export function useTimelineData(editor: Editor, blockId: string): TimelineViewData | null {
+  const [version, setVersion] = useState(0);
+  const dataCache = useRef<{
+    text: string;
+    language: string | null;
+    data: TimelineViewData;
+  } | null>(null);
+  useEffect(() => {
+    const onEditorChange = () => setVersion((value) => value + 1);
+    editor.on('transaction', onEditorChange);
+    // setEditable() updates editor options and emits `update`, but does not
+    // necessarily dispatch a ProseMirror transaction. Keep mounted widgets in
+    // sync when a host toggles read-only mode at runtime.
+    editor.on('update', onEditorChange);
+    return () => {
+      editor.off('transaction', onEditorChange);
+      editor.off('update', onEditorChange);
+    };
+  }, [editor]);
+
+  return useMemo(() => {
+    const pos = findTimelineBlockPos(editor, blockId);
+    if (pos === null) return null;
+    const node = editor.state.doc.nodeAt(pos);
+    if (!node || node.type.name !== 'codeBlock') return null;
+    const text = node.textContent;
+    const rawLanguage = (node.attrs as { language?: unknown }).language;
+    const language = typeof rawLanguage === 'string' ? rawLanguage : null;
+    const cached = dataCache.current;
+    // ProseMirror can rebuild ancestor nodes for an unrelated edit. Source
+    // text + language fully determine the timeline parse, so retain the data
+    // and model identities across those transactions (and editable updates).
+    if (cached?.text === text && cached.language === language) return cached.data;
+    const timeline = parseTimelineForNode(node);
+    if (!timeline) return null;
+    const data = { timeline, text, warnings: timeline.warnings };
+    dataCache.current = { text, language, data };
+    return data;
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [editor, blockId, version]);
+}