@bendyline/squisq-editor-react 1.6.1 → 2.0.0

package/src/timeline/TimelineViewExtension.ts

@@ -0,0 +1,252 @@
+/**
+ * TimelineViewExtension — mounts a WYSIWYG timeline editor over qualifying
+ * authored timeline code fences while keeping the fence text as source of
+ * truth. Every semantic edit is rendered back through the core codec.
+ */
+
+import { Extension } from '@tiptap/core';
+import { Plugin, PluginKey } from '@tiptap/pm/state';
+import type { Transaction } from '@tiptap/pm/state';
+import type { Node as PMNode } from '@tiptap/pm/model';
+import { Decoration, DecorationSet } from '@tiptap/pm/view';
+import type { Editor } from '@tiptap/react';
+import { createElement } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import {
+  detectAsciiTimeline,
+  isEligibleAsciiTimelineFenceLang,
+  isExplicitTimelineLang,
+  type AsciiTimeline,
+} from '@bendyline/squisq/doc';
+import { TimelineEditorWidget } from './TimelineEditorWidget';
+
+export interface TimelineBlockEntry {
+  /** Synthetic session id, stable across edits to one fence. */
+  id: string;
+  /** Current document position of the codeBlock node. */
+  pos: number;
+}
+
+export interface TimelineViewPluginState {
+  entries: TimelineBlockEntry[];
+  decorations: DecorationSet;
+  seq: number;
+}
+
+export const TIMELINE_VIEW_KEY = new PluginKey<TimelineViewPluginState>('squisq-timeline-view');
+
+const detectCache = new WeakMap<PMNode, AsciiTimeline | null>();
+const parseCache = new WeakMap<PMNode, AsciiTimeline | null>();
+
+function fenceLangOf(node: PMNode): string | null {
+  const language = (node.attrs as { language?: string | null }).language;
+  return typeof language === 'string' ? language : null;
+}
+
+function eventCount(timeline: AsciiTimeline): number {
+  return timeline.tracks.reduce((sum, track) => sum + track.events.length, 0);
+}
+
+/** Conservative full-detection gate used when first claiming a code fence. */
+export function getTimelineForNode(node: PMNode): AsciiTimeline | null {
+  if (node.type.name !== 'codeBlock') return null;
+  const cached = detectCache.get(node);
+  if (cached !== undefined) return cached;
+
+  let result: AsciiTimeline | null = null;
+  const language = fenceLangOf(node);
+  if (isEligibleAsciiTimelineFenceLang(language)) {
+    const detection = detectAsciiTimeline(node.textContent, {
+      explicit: isExplicitTimelineLang(language),
+    });
+    if (detection.isTimeline && detection.timeline && eventCount(detection.timeline) > 0) {
+      result = detection.timeline;
+      parseCache.set(node, result);
+    }
+  }
+  detectCache.set(node, result);
+  return result;
+}
+
+/** Relaxed/sticky gate for a block already registered by this extension. */
+export function parseTimelineForNode(node: PMNode): AsciiTimeline | null {
+  if (node.type.name !== 'codeBlock') return null;
+  const cached = parseCache.get(node);
+  if (cached !== undefined) return cached;
+
+  let result: AsciiTimeline | null = null;
+  if (isEligibleAsciiTimelineFenceLang(fenceLangOf(node))) {
+    const detection = detectAsciiTimeline(node.textContent, { explicit: true });
+    if (detection.isTimeline && detection.timeline && eventCount(detection.timeline) > 0) {
+      result = detection.timeline;
+    }
+  }
+  parseCache.set(node, result);
+  return result;
+}
+
+export function findTimelineBlockPos(editor: Editor, blockId: string): number | null {
+  return (
+    TIMELINE_VIEW_KEY.getState(editor.state)?.entries.find((entry) => entry.id === blockId)?.pos ??
+    null
+  );
+}
+
+interface TimelineWidgetHost extends HTMLElement {
+  __squisqTimelineRoot?: Root;
+}
+
+function buildDecorations(
+  doc: PMNode,
+  entries: readonly TimelineBlockEntry[],
+  editor: Editor,
+): DecorationSet {
+  const decorations: Decoration[] = [];
+  for (const entry of entries) {
+    const node = doc.nodeAt(entry.pos);
+    if (!node || node.type.name !== 'codeBlock') continue;
+
+    decorations.push(
+      Decoration.node(entry.pos, entry.pos + node.nodeSize, {
+        class: 'squisq-ascii-timeline-fence-hidden',
+      }),
+    );
+    decorations.push(
+      Decoration.widget(
+        entry.pos + node.nodeSize,
+        () => {
+          const container = document.createElement('div') as TimelineWidgetHost;
+          container.className = 'squisq-ascii-timeline-widget-host';
+          container.contentEditable = 'false';
+          // The widget contains real form controls inside a ProseMirror
+          // decoration. Keep their complete edit/composition stream inside
+          // the React root so browser/IME `beforeinput` events cannot also be
+          // interpreted as text insertion at the document selection.
+          for (const eventName of [
+            'pointerdown',
+            'mousedown',
+            'keydown',
+            'keyup',
+            'beforeinput',
+            'input',
+            'change',
+            'compositionstart',
+            'compositionupdate',
+            'compositionend',
+            'paste',
+            'cut',
+          ]) {
+            container.addEventListener(eventName, (event) => event.stopPropagation());
+          }
+          const root = createRoot(container);
+          root.render(createElement(TimelineEditorWidget, { editor, blockId: entry.id }));
+          container.__squisqTimelineRoot = root;
+          return container;
+        },
+        {
+          destroy: (dom) => {
+            const root = (dom as TimelineWidgetHost).__squisqTimelineRoot;
+            if (root) setTimeout(() => root.unmount(), 0);
+          },
+          side: 1,
+          ignoreSelection: true,
+          key: `squisq-timeline-${entry.id}`,
+        },
+      ),
+    );
+  }
+  return DecorationSet.create(doc, decorations);
+}
+
+function applyState(
+  tr: Transaction,
+  previous: TimelineViewPluginState,
+  editor: Editor,
+  doc: PMNode,
+): TimelineViewPluginState {
+  if (!tr.docChanged) return previous;
+
+  const mapped = new Map<number, string>();
+  const claimed = new Set<string>();
+  for (const entry of previous.entries) {
+    const result = tr.mapping.mapResult(entry.pos, 1);
+    if (!result.deleted) {
+      mapped.set(result.pos, entry.id);
+      claimed.add(entry.id);
+    }
+  }
+  // `setNodeMarkup` during language promotion can mark the opening token as
+  // deleted even though the codeBlock still occupies the mapped position.
+  for (const entry of previous.entries) {
+    if (claimed.has(entry.id)) continue;
+    const result = tr.mapping.mapResult(entry.pos, 1);
+    if (mapped.has(result.pos)) continue;
+    if (doc.nodeAt(result.pos)?.type.name === 'codeBlock') {
+      mapped.set(result.pos, entry.id);
+      claimed.add(entry.id);
+    }
+  }
+
+  let seq = previous.seq;
+  const entries: TimelineBlockEntry[] = [];
+  doc.descendants((node, pos) => {
+    if (node.type.name !== 'codeBlock') return;
+    const knownId = mapped.get(pos);
+    const timeline = knownId ? parseTimelineForNode(node) : getTimelineForNode(node);
+    if (!timeline) return false;
+    entries.push({ id: knownId ?? `timeline-${++seq}`, pos });
+    return false;
+  });
+
+  return { entries, seq, decorations: buildDecorations(doc, entries, editor) };
+}
+
+export interface TimelineViewExtensionOptions {
+  /** When false, the extension does not claim fences or mount widgets. */
+  enabled?: boolean;
+}
+
+export const TimelineViewExtension = Extension.create<TimelineViewExtensionOptions>({
+  name: 'squisqTimelineView',
+
+  addOptions() {
+    return { enabled: true };
+  },
+
+  addProseMirrorPlugins() {
+    const editor = this.editor as Editor;
+    if (this.options.enabled === false) return [];
+
+    return [
+      new Plugin<TimelineViewPluginState>({
+        key: TIMELINE_VIEW_KEY,
+        state: {
+          init: (_config, state) => {
+            let seq = 0;
+            const entries: TimelineBlockEntry[] = [];
+            state.doc.descendants((node, pos) => {
+              if (node.type.name !== 'codeBlock') return;
+              if (!getTimelineForNode(node)) return false;
+              entries.push({ id: `timeline-${++seq}`, pos });
+              return false;
+            });
+            return {
+              entries,
+              seq,
+              decorations: buildDecorations(state.doc, entries, editor),
+            };
+          },
+          apply: (tr, previous, _oldState, newState) =>
+            applyState(tr, previous, editor, newState.doc),
+        },
+        props: {
+          decorations(state) {
+            return this.getState(state)?.decorations ?? DecorationSet.empty;
+          },
+        },
+      }),
+    ];
+  },
+});
+
+export default TimelineViewExtension;

package/src/timeline/__tests__/TimelineEditorWidget.test.tsx

@@ -0,0 +1,355 @@
+import { Editor } from '@tiptap/core';
+import StarterKit from '@tiptap/starter-kit';
+import { EditorContent } from '@tiptap/react';
+import { act, cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { afterEach, beforeAll, describe, expect, it } from 'vitest';
+import { parseAsciiTimeline, renderAsciiTimeline, type AsciiTimeline } from '@bendyline/squisq/doc';
+import { markdownToTiptap } from '../../tiptapBridge';
+import { HeadingWithTemplate } from '../../TemplateAnnotation';
+import { TimelineEditorWidget } from '../TimelineEditorWidget';
+import { TIMELINE_VIEW_KEY, TimelineViewExtension } from '../TimelineViewExtension';
+import { useTimelineData, type TimelineViewData } from '../timelineData';
+
+const TIMELINE: AsciiTimeline = {
+  tracks: [
+    {
+      id: 'kernel',
+      label: 'Kernel',
+      row: 0,
+      startColumn: 0,
+      endColumn: 100,
+      events: [
+        { id: 'start', label: 'Start', column: 0, side: 'above', marker: 'filled' },
+        { id: 'review', label: 'Review', column: 50, side: 'below', marker: 'hollow' },
+      ],
+    },
+    {
+      id: 'client',
+      label: 'Client',
+      row: 1,
+      startColumn: 0,
+      endColumn: 100,
+      events: [
+        {
+          id: 'frame',
+          label: 'f',
+          column: 25,
+          side: 'above',
+          callout: false,
+          marker: 'hollow',
+        },
+        { id: 'paint', label: 'Paint', column: 100, side: 'below', marker: 'filled' },
+      ],
+    },
+  ],
+  links: [{ source: 'review', target: 'paint', label: 'handoff' }],
+  width: 101,
+  height: 2,
+  style: 'unicode',
+  warnings: [],
+};
+
+const ART = renderAsciiTimeline(TIMELINE);
+const editors: Editor[] = [];
+
+beforeAll(() => {
+  if (typeof globalThis.PointerEvent !== 'undefined') return;
+  class PointerEventStub extends MouseEvent {
+    readonly pointerId: number;
+
+    constructor(type: string, init: PointerEventInit = {}) {
+      super(type, init);
+      this.pointerId = init.pointerId ?? 0;
+    }
+  }
+  globalThis.PointerEvent = PointerEventStub as typeof PointerEvent;
+});
+
+function makeEditor(editable = true, art = ART): Editor {
+  const editor = new Editor({
+    editable,
+    extensions: [
+      StarterKit.configure({
+        heading: false,
+        codeBlock: { HTMLAttributes: { class: 'squisq-code-block' } },
+      }),
+      HeadingWithTemplate.configure({ levels: [1, 2, 3, 4, 5, 6] }),
+      TimelineViewExtension,
+    ],
+    content: markdownToTiptap(`\`\`\`timeline\n${art}\n\`\`\`\n`),
+  });
+  editors.push(editor);
+  return editor;
+}
+
+function blockIdOf(editor: Editor): string {
+  const entries = TIMELINE_VIEW_KEY.getState(editor.state)?.entries ?? [];
+  expect(entries).toHaveLength(1);
+  return entries[0].id;
+}
+
+function renderWidget(editable = true): Editor {
+  const editor = makeEditor(editable);
+  render(<TimelineEditorWidget editor={editor} blockId={blockIdOf(editor)} />);
+  return editor;
+}
+
+function timelineOf(editor: Editor): AsciiTimeline {
+  let fence = '';
+  editor.state.doc.descendants((node) => {
+    if (node.type.name !== 'codeBlock') return true;
+    fence = node.textContent;
+    return false;
+  });
+  return parseAsciiTimeline(fence);
+}
+
+function eventOf(editor: Editor, id: string) {
+  return timelineOf(editor)
+    .tracks.flatMap((track) => track.events)
+    .find((event) => event.id === id);
+}
+
+afterEach(() => {
+  cleanup();
+  for (const editor of editors) editor.destroy();
+  editors.length = 0;
+});
+
+describe('TimelineEditorWidget', () => {
+  it('selects different dots, including a cadence-only dot, and exposes branches', async () => {
+    const editor = makeEditor();
+    const rendered = render(<TimelineEditorWidget editor={editor} blockId={blockIdOf(editor)} />);
+
+    const start = screen.getByRole('button', { name: /Edit Start, Kernel/ });
+    await waitFor(() => expect(start.getAttribute('aria-pressed')).toBe('true'));
+
+    const review = screen.getByRole('button', { name: /Edit Review, Kernel/ });
+    fireEvent.click(review);
+    expect(review.getAttribute('aria-pressed')).toBe('true');
+    expect((screen.getByLabelText('Label') as HTMLInputElement).value).toBe('Review');
+
+    const cadence = screen.getByRole('button', { name: /Edit f, Client/ });
+    fireEvent.click(cadence);
+    expect(cadence.getAttribute('aria-pressed')).toBe('true');
+    expect((screen.getByLabelText('Label') as HTMLInputElement).value).toBe('f');
+
+    const branchList = screen.getByRole('list', { name: 'Timeline branches' });
+    expect(screen.getAllByRole('listitem')).toHaveLength(1);
+    expect(branchList.textContent).toContain('review');
+    expect(branchList.textContent).toContain('paint');
+    expect(branchList.textContent).toContain('handoff');
+    expect(
+      rendered.container.querySelectorAll('.squisq-ascii-timeline-branches path'),
+    ).toHaveLength(1);
+  });
+
+  it('rewrites label and callout text on blur while preserving the event id and branch', async () => {
+    const editor = renderWidget();
+    fireEvent.click(screen.getByRole('button', { name: /Edit Review, Kernel/ }));
+
+    const label = screen.getByLabelText('Label') as HTMLInputElement;
+    fireEvent.change(label, { target: { value: 'Gate' } });
+    fireEvent.blur(label);
+
+    await waitFor(() => expect(eventOf(editor, 'review')?.label).toBe('Gate'));
+    expect(timelineOf(editor).links).toEqual([
+      { source: 'review', target: 'paint', label: 'handoff' },
+    ]);
+
+    const callout = screen.getByLabelText('Callout text') as HTMLTextAreaElement;
+    fireEvent.change(callout, { target: { value: 'Interpolate the latest snapshot' } });
+    fireEvent.blur(callout);
+
+    await waitFor(() =>
+      expect(eventOf(editor, 'review')?.description).toBe('Interpolate the latest snapshot'),
+    );
+    expect((screen.getByLabelText('Label') as HTMLInputElement).value).toBe('Gate');
+    expect(
+      screen.getByRole('button', { name: /Edit Gate, Kernel/ }).getAttribute('aria-pressed'),
+    ).toBe('true');
+  });
+
+  it('adds and selects a point where the empty rail is clicked', async () => {
+    const editor = renderWidget();
+    const rail = screen.getByRole('group', { name: 'Kernel timeline rail' });
+    rail.getBoundingClientRect = () =>
+      ({
+        x: 100,
+        y: 0,
+        left: 100,
+        top: 0,
+        right: 500,
+        bottom: 40,
+        width: 400,
+        height: 40,
+        toJSON: () => ({}),
+      }) as DOMRect;
+
+    fireEvent.click(rail, { clientX: 240 });
+
+    await waitFor(() => expect(eventOf(editor, 'new-event')?.column).toBe(35));
+    const marker = screen.getByRole('button', { name: /Edit New event, Kernel/ });
+    expect(marker.getAttribute('aria-pressed')).toBe('true');
+    expect((screen.getByLabelText('Label') as HTMLInputElement).value).toBe('New event');
+    expect(screen.getByText('New timeline point added. Edit its text below.')).toBeTruthy();
+  });
+
+  it('previews a dragged dot and commits its new position only on drop', async () => {
+    const editor = renderWidget();
+    const rail = screen.getByRole('group', { name: 'Kernel timeline rail' });
+    rail.getBoundingClientRect = () =>
+      ({
+        x: 100,
+        y: 0,
+        left: 100,
+        top: 0,
+        right: 500,
+        bottom: 40,
+        width: 400,
+        height: 40,
+        toJSON: () => ({}),
+      }) as DOMRect;
+
+    const review = screen.getByRole('button', { name: /Edit Review, Kernel/ });
+    fireEvent.pointerDown(review, { pointerId: 7, button: 0, clientX: 300 });
+    fireEvent.pointerMove(review, { pointerId: 7, clientX: 400 });
+
+    await waitFor(() =>
+      expect(review.closest('.squisq-ascii-timeline-point')?.getAttribute('style')).toContain(
+        '75%',
+      ),
+    );
+    expect(eventOf(editor, 'review')?.column).toBe(50);
+    expect(screen.queryAllByRole('button', { name: /Add point to Kernel at/ })).toHaveLength(0);
+
+    fireEvent.pointerUp(review, { pointerId: 7, button: 0, clientX: 400 });
+
+    await waitFor(() => expect(eventOf(editor, 'review')?.column).toBe(75));
+    expect(screen.getByText('Review moved to 75 percent.')).toBeTruthy();
+    expect(
+      screen
+        .getByRole('button', { name: /Edit Review, Kernel, 75 percent/ })
+        .getAttribute('aria-pressed'),
+    ).toBe('true');
+  });
+
+  it('cancels a pointer drag without rewriting the timeline', async () => {
+    const editor = renderWidget();
+    const rail = screen.getByRole('group', { name: 'Kernel timeline rail' });
+    rail.getBoundingClientRect = () =>
+      ({ left: 0, right: 400, top: 0, bottom: 40, width: 400, height: 40 }) as DOMRect;
+    const before = JSON.stringify(editor.state.doc.toJSON());
+    const review = screen.getByRole('button', { name: /Edit Review, Kernel/ });
+
+    fireEvent.pointerDown(review, { pointerId: 8, button: 0, clientX: 200 });
+    fireEvent.pointerMove(review, { pointerId: 8, clientX: 320 });
+    fireEvent.pointerCancel(review, { pointerId: 8 });
+
+    await waitFor(() => expect(screen.getByText('Timeline point move cancelled.')).toBeTruthy());
+    expect(JSON.stringify(editor.state.doc.toJSON())).toBe(before);
+    expect(eventOf(editor, 'review')?.column).toBe(50);
+  });
+
+  it('always exposes a keyboard-reachable add-point control for each track', async () => {
+    const editor = renderWidget();
+    fireEvent.click(screen.getByRole('button', { name: 'Add point to Kernel timeline' }));
+
+    await waitFor(() => expect(eventOf(editor, 'new-event')?.column).toBe(25));
+    expect(screen.getByRole('button', { name: /Edit New event, Kernel/ })).toBeTruthy();
+  });
+
+  it('keeps dots selectable but prevents every mutation in read-only mode', async () => {
+    const editor = renderWidget(false);
+    const before = JSON.stringify(editor.state.doc.toJSON());
+    expect(screen.getByText('Read only')).toBeTruthy();
+
+    const review = screen.getByRole('button', { name: /Edit Review, Kernel/ });
+    fireEvent.click(review);
+    expect(review.getAttribute('aria-pressed')).toBe('true');
+    expect((screen.getByLabelText('Label') as HTMLInputElement).value).toBe('Review');
+    expect(
+      (screen.getByLabelText('Label').closest('fieldset') as HTMLFieldSetElement).disabled,
+    ).toBe(true);
+
+    const rail = screen.getByRole('group', { name: 'Kernel timeline rail' });
+    fireEvent.click(rail, { clientX: 200 });
+    await Promise.resolve();
+    expect(JSON.stringify(editor.state.doc.toJSON())).toBe(before);
+    expect(screen.queryByRole('button', { name: /Add point to Kernel at/ })).toBeNull();
+    expect(screen.queryByRole('button', { name: 'Add point to Kernel timeline' })).toBeNull();
+  });
+
+  it('reacts when a mounted editor toggles between editable and read-only', async () => {
+    const editor = renderWidget();
+    expect(screen.getByRole('button', { name: 'Add point to Kernel timeline' })).toBeTruthy();
+
+    editor.setEditable(false);
+    await screen.findByText('Read only');
+    expect(screen.queryByRole('button', { name: 'Add point to Kernel timeline' })).toBeNull();
+    expect(
+      (screen.getByLabelText('Label').closest('fieldset') as HTMLFieldSetElement).disabled,
+    ).toBe(true);
+
+    editor.setEditable(true);
+    await waitFor(() =>
+      expect(screen.getByRole('button', { name: 'Add point to Kernel timeline' })).toBeTruthy(),
+    );
+  });
+
+  it('retains parsed timeline identity across unrelated editor transactions', async () => {
+    const editor = makeEditor();
+    const blockId = blockIdOf(editor);
+    const observed: TimelineViewData[] = [];
+    function Probe() {
+      const data = useTimelineData(editor, blockId);
+      if (data) observed.push(data);
+      return null;
+    }
+    render(<Probe />);
+    await waitFor(() => expect(observed.length).toBeGreaterThan(0));
+    const first = observed[observed.length - 1];
+
+    act(() => {
+      editor.commands.insertContentAt(0, '<p>Unrelated content</p>');
+    });
+
+    await waitFor(() => expect(observed.length).toBeGreaterThan(1));
+    expect(observed[observed.length - 1]).toBe(first);
+    expect(observed[observed.length - 1]?.timeline).toBe(first.timeline);
+  });
+
+  it('pauses visual mutations when source cannot be rewritten losslessly', async () => {
+    const unsafeArt = `${ART}\nbranch: review -> missing : preserve me`;
+    const editor = makeEditor(true, unsafeArt);
+    render(<TimelineEditorWidget editor={editor} blockId={blockIdOf(editor)} />);
+    const before = JSON.stringify(editor.state.doc.toJSON());
+
+    expect(screen.getByText('Source repair needed')).toBeTruthy();
+    expect(screen.getByRole('status').textContent).toContain('Visual editing paused');
+    expect(screen.queryByRole('button', { name: 'Add point to Kernel timeline' })).toBeNull();
+    expect(
+      (screen.getByLabelText('Label').closest('fieldset') as HTMLFieldSetElement).disabled,
+    ).toBe(true);
+
+    fireEvent.click(screen.getByRole('button', { name: /Edit Review, Kernel/ }));
+    expect((screen.getByLabelText('Label') as HTMLInputElement).value).toBe('Review');
+    expect(JSON.stringify(editor.state.doc.toJSON())).toBe(before);
+  });
+
+  it('keeps mounted widget input events out of the underlying ProseMirror selection', async () => {
+    const editor = makeEditor();
+    render(<EditorContent editor={editor} />);
+
+    const review = await screen.findByRole('button', { name: /Edit Review, Kernel/ });
+    fireEvent.click(review);
+    const label = screen.getByLabelText('Label') as HTMLInputElement;
+    fireEvent.change(label, { target: { value: 'Gate' } });
+    fireEvent.blur(label);
+
+    await waitFor(() => expect(eventOf(editor, 'review')?.label).toBe('Gate'));
+    expect(editor.state.doc.childCount).toBe(1);
+    expect(editor.state.doc.firstChild?.type.name).toBe('codeBlock');
+    expect(editor.state.doc.firstChild?.textContent).toContain('Gate');
+  });
+});