@plannotator/ui 0.40.0 → 0.41.1

package/components/diagram/DiagramViewer.tsx

@@ -0,0 +1,285 @@
+import { lazy, Suspense, useCallback, useEffect, useMemo, useState, type ReactNode } from 'react';
+import type { DiagramKind } from '@plannotator/core/diagram-anchor';
+import { cn } from '../../lib/utils';
+import { diagramFamilyOf } from '../../utils/diagram-anchor';
+import { diagramFinder, type DiagramTheme } from '../../utils/diagram-render';
+import { DiagramCanvas, type DiagramCanvasHandle, type DiagramEscapeOutcome } from './DiagramCanvas';
+import { DiagramComposer } from './DiagramComposer';
+import { DiagramOverlay } from './DiagramOverlay';
+import { useDiagramComments, type DiagramComment, type DiagramCreateComment } from './useDiagramComments';
+import { useDiagramRender, type DiagramRenderState } from './useDiagramRender';
+import { useDiagramSourceDraft, type SaveResult } from './useDiagramSourceDraft';
+
+/**
+ * The one diagram viewer: the canvas with its overlay, the Source pane on
+ * its LEFT (stacked under it on the phone) when the host can save, the
+ * parse-error strip over a dimmed last-good render. It takes the diagram
+ * source and the host's comments on it, and reports a new comment through
+ * `onCreateComment`; the comments rail, storage and identity are the
+ * host's. Plannotator's fence blocks render through it in the document
+ * (`components/DiagramBlock`) and again at full size in the popout; a host
+ * with its own document store renders it wherever a diagram lives.
+ */
+/**
+ * The Source pane is CodeMirror, and a viewer that can never open one (every
+ * fence in a Plannotator document today: no host passes `onSave`) must not
+ * carry it. It loads on the first open of the pane and never before, so the
+ * editor stays out of the document-read closure of a chunked host.
+ */
+const DiagramSourcePane = lazy(async () => ({ default: (await import('./DiagramSourcePane')).DiagramSourcePane }));
+
+/** The pane's box while its chunk loads: same class list, so the split it
+ * opens into is already the right size and nothing jumps when it lands.
+ * Never `null` here — that would collapse the row back onto the canvas. */
+const PANE_CLASS = 'order-last min-h-0 shrink-0 basis-2/5 border-t border-border md:order-first md:w-80 md:basis-auto md:border-r md:border-t-0';
+
+export interface DiagramViewerProps {
+  readonly kind: DiagramKind;
+  /** The diagram text. With `onSave` this is the saved baseline the pane's
+   * draft starts from; without it, what the canvas renders. */
+  readonly source: string;
+  readonly theme: DiagramTheme;
+  readonly comments: readonly DiagramComment[];
+  /** A comment composed on a part. Absent: clicks open nothing. */
+  readonly onCreateComment?: DiagramCreateComment;
+  /** Save the pane's text. Absent: there is no Source pane. */
+  readonly onSave?: (source: string) => Promise<SaveResult>;
+  /** With `onSave`: show the pane read-only (no edit access). */
+  readonly readOnlySource?: boolean;
+  /** Whether the Source pane is open (the host owns the toggle). */
+  readonly sourceOpen?: boolean;
+  readonly selectedCommentId?: string | null;
+  readonly onSelectComment?: (id: string | null) => void;
+  /** The comments whose part is gone from the current render, once per
+   * membership change, after every render. */
+  readonly onUnanchoredChange?: (ids: ReadonlySet<string>) => void;
+  /** Every comment's verdict (true: its part is in this render), whenever
+   * a verdict or the comment list changes. */
+  readonly onResolutionChange?: (resolution: ReadonlyMap<string, boolean>) => void;
+  /** Escape with no composer open and nothing selected: a popout closes. */
+  readonly onDismiss?: () => void;
+  /** A stable prefix for the rendered element ids; two viewers over one
+   * document need two. */
+  readonly renderId?: string;
+  /** Lines to add so a comment's `sourceLine` names DOCUMENT lines: 0 when
+   * the document is the diagram, the fence's opening line for a fence. */
+  readonly sourceLineOffset?: number;
+  /** Shift-click targets one comment may also cover. Default 0: a comment
+   * covers one part. */
+  readonly maxAdditionalTargets?: number;
+  /** Commenting is off, and this is why (shown in place of the composer). */
+  readonly commentingDisabledReason?: string;
+  /** Bumped by the host's Retry after a failed engine load. */
+  readonly retryToken?: number;
+  /** Every render state change (the host sizes itself, shows its own
+   * pending or error chrome). */
+  readonly onRenderState?: (state: DiagramRenderState) => void;
+  /** What to show while there is no svg yet (the first render pending, or
+   * the first render failed). Default: a quiet status line. */
+  readonly renderFallback?: (state: DiagramRenderState) => ReactNode;
+  /** Take the keyboard on mount (a popout). */
+  readonly autoFocus?: boolean;
+  readonly className?: string;
+  /** Classes for the canvas host. The canvas lets a finger scroll the page
+   * past it (`touch-action: pan-y`); a viewer that owns the whole screen
+   * passes `touch-none`. */
+  readonly canvasClassName?: string;
+}
+
+export function DiagramViewer({
+  kind,
+  source,
+  theme,
+  comments,
+  onCreateComment,
+  onSave,
+  readOnlySource = false,
+  sourceOpen = false,
+  selectedCommentId = null,
+  onSelectComment,
+  onUnanchoredChange,
+  onResolutionChange,
+  onDismiss,
+  renderId = 'diagram',
+  sourceLineOffset = 0,
+  maxAdditionalTargets = 0,
+  commentingDisabledReason,
+  retryToken,
+  onRenderState,
+  renderFallback,
+  autoFocus,
+  className,
+  canvasClassName,
+}: DiagramViewerProps) {
+  const finder = diagramFinder(kind);
+  const familyOf = useCallback((svg: Element) => (kind === 'graphviz' ? ('graphviz' as const) : diagramFamilyOf(svg)), [kind]);
+  const hasPane = onSave !== undefined;
+  const editable = hasPane && !readOnlySource;
+
+  const draft = useDiagramSourceDraft({ source, editable, onSave });
+  const rendered = hasPane ? draft.preview : source;
+  const savedSource = hasPane ? draft.baseline : source;
+  const sourceDirty = hasPane && draft.dirty;
+
+  const render = useDiagramRender(kind, renderId, rendered, theme, { retryToken });
+  useEffect(() => {
+    onRenderState?.(render);
+  }, [onRenderState, render]);
+
+  const [svgRoot, setSvgRoot] = useState<SVGSVGElement | null>(null);
+  const onSvgRoot = useCallback((root: SVGSVGElement | null) => setSvgRoot(root), []);
+
+  const canCreate = onCreateComment !== undefined || commentingDisabledReason !== undefined;
+  const commentsState = useDiagramComments({
+    finder,
+    svgRoot,
+    renderId: render.renderId,
+    renderVersion: render.renderVersion,
+    comments,
+    savedSource,
+    sourceLineOffset,
+    sourceDirty,
+    maxAdditionalTargets,
+    canCreate,
+    onCreateComment,
+    onSelectComment,
+    onUnanchoredChange,
+    onResolutionChange,
+    familyOf,
+  });
+
+  // The selected comment's source line for the pane's gutter mark. The
+  // anchor names DOCUMENT lines; the pane shows the diagram text.
+  const markedLines = useMemo(() => {
+    if (selectedCommentId === null) return null;
+    const line = comments.find((entry) => entry.id === selectedCommentId)?.anchor.sourceLine;
+    if (line === null || line === undefined) return null;
+    return [line[0] - sourceLineOffset, line[1] - sourceLineOffset] as const;
+  }, [comments, selectedCommentId, sourceLineOffset]);
+
+  const onEscape = useCallback((): DiagramEscapeOutcome => {
+    if (commentsState.composer !== null) {
+      commentsState.cancel();
+      return 'consumed';
+    }
+    if (selectedCommentId !== null && onSelectComment !== undefined) {
+      onSelectComment(null);
+      return 'consumed';
+    }
+    onDismiss?.();
+    return 'pass';
+  }, [commentsState, onDismiss, onSelectComment, selectedCommentId]);
+
+  // Closing the pane only closes an open composer so the layout shift does
+  // not strand it; the draft survives a reopen.
+  const cancelComposer = commentsState.cancel;
+  useEffect(() => {
+    if (!sourceOpen) cancelComposer();
+  }, [cancelComposer, sourceOpen]);
+
+  const overlay = useCallback(
+    (handle: DiagramCanvasHandle) => (
+      <DiagramOverlay
+        handle={handle}
+        resolved={commentsState.resolved}
+        hover={commentsState.hover}
+        composer={commentsState.composer}
+        selectedCommentId={selectedCommentId}
+        onSelectComment={onSelectComment}
+        renderComposer={(anchorRect) =>
+          commentsState.composer === null ? null : (
+            <DiagramComposer
+              key={`${commentsState.composer.primary.target.id ?? ''}:${commentsState.composer.primary.target.from ?? ''}:${commentsState.composer.primary.target.to ?? ''}`}
+              draft={commentsState.composer}
+              anchorRect={anchorRect}
+              hostWidth={handle.hostRef.current?.getBoundingClientRect().width ?? 0}
+              sourceDirty={sourceDirty}
+              submitting={commentsState.submitting}
+              error={commentsState.submitError}
+              disabledReason={commentingDisabledReason}
+              onSubmit={(text) => void commentsState.submit(text)}
+              onCancel={commentsState.cancel}
+            />
+          )
+        }
+      />
+    ),
+    [commentingDisabledReason, commentsState, onSelectComment, selectedCommentId, sourceDirty],
+  );
+
+  const showFallback = render.svgNode === null;
+
+  return (
+    // `annotation-exclude`: the document's text highlighter never enters a
+    // diagram, so a text restore can never wrap a <mark> inside the svg.
+    <div data-diagram-viewer="" className={cn('annotation-exclude flex h-full min-h-0 w-full flex-col md:flex-row', className)}>
+      {/* The pane comes FIRST in the row (owner ruling: the source sits on
+          the left of the diagram while editing). On the phone the row is a
+          column and the pane stays stacked UNDER the canvas, which
+          `order-last` keeps while `md:order-first` puts it left from `md`. */}
+      {hasPane && sourceOpen && (
+        <Suspense fallback={<div data-diagram-source-pane-pending="" aria-hidden="true" className={PANE_CLASS} />}>
+          <DiagramSourcePane draft={draft} editable={editable} markedLines={markedLines} className={PANE_CLASS} />
+        </Suspense>
+      )}
+      <div className="relative min-h-0 min-w-0 flex-1">
+        {showFallback ? (
+          <div data-diagram-fallback="" className="h-full min-h-0 w-full">
+            {renderFallback !== undefined ? (
+              renderFallback(render)
+            ) : (
+              <div className="flex h-full items-center justify-center p-4 text-xs text-muted-foreground" aria-live="polite">
+                {render.error !== null
+                  ? `The diagram does not parse${render.error.line === null ? '' : ` (line ${render.error.line})`}: ${render.error.message}`
+                  : render.pending
+                    ? 'Rendering diagram…'
+                    : 'Nothing to render yet.'}
+              </div>
+            )}
+          </div>
+        ) : (
+          <DiagramCanvas
+            svgNode={render.svgNode}
+            targetSelector={finder.targetSelector}
+            pickTarget={commentsState.pickTarget}
+            className={canvasClassName}
+            dimmed={render.error !== null}
+            onSvgRoot={onSvgRoot}
+            onHoverElement={commentsState.setHoverElement}
+            onClickElement={commentsState.clickElement}
+            onEscape={onEscape}
+            overlay={overlay}
+            autoFocus={autoFocus}
+          >
+            {render.error !== null && (
+              <div
+                data-diagram-parse-error=""
+                role="alert"
+                className="absolute inset-x-3 top-3 z-10 rounded-md border border-warning/40 bg-card/95 px-3 py-2 text-xs shadow-lg backdrop-blur"
+              >
+                <div className="font-medium text-foreground">
+                  {render.error.line === null ? 'The diagram does not parse' : `The diagram does not parse (line ${render.error.line})`}
+                </div>
+                <div className="mt-0.5 text-muted-foreground">
+                  {render.error.message}
+                  {' The last good render stays below.'}
+                </div>
+              </div>
+            )}
+            {/* The chip earns its place only while the pane is closed (the
+                draft survives a close); with the pane open its header carries
+                the one "Draft · unsaved". */}
+            {editable && draft.dirty && !sourceOpen && (
+              <span
+                data-diagram-preview-state=""
+                className="absolute left-3 top-3 z-10 rounded-sm border border-border bg-card/85 px-1.5 py-0.5 text-[10px] text-muted-foreground backdrop-blur"
+              >
+                Draft preview · unsaved
+              </span>
+            )}
+          </DiagramCanvas>
+        )}
+      </div>
+    </div>
+  );
+}

package/components/diagram/anchorClaims.ts

@@ -0,0 +1,71 @@
+import { createContext } from 'react';
+
+/**
+ * Who shows a diagram comment that names no diagram block of the document.
+ *
+ * A comment composed in a block carries that block's `blockId`. One that
+ * arrives through `POST /api/external-annotations` carries `blockId:
+ * "external"`, and one whose fence was deleted carries an id that no longer
+ * exists; neither says which diagram it belongs to, but its anchor does.
+ * Every diagram block tries such a comment against its own render and
+ * reports the verdict here; the FIRST block in document order whose finder
+ * resolves it shows it, and when every block has answered and none did, it
+ * is unanchored (listed in the rail with the chip, never silently dropped).
+ * A block that has not answered yet keeps the verdict pending, so nothing is
+ * called unanchored while a diagram is still rendering.
+ */
+export class DiagramAnchorClaims {
+  private readonly reports = new Map<string, Map<string, boolean>>();
+  private readonly listeners = new Set<() => void>();
+  private version = 0;
+
+  /** The diagram blocks of the document, in document order. */
+  constructor(readonly blockIds: readonly string[]) {}
+
+  /** A block's verdicts for the unowned comments it tried. Verdicts for ids
+   * it no longer tries are kept: a block stops trying a comment once another
+   * block owns it, and that must not read as "could not resolve". */
+  report(blockId: string, results: ReadonlyMap<string, boolean>): void {
+    let mine = this.reports.get(blockId);
+    let changed = false;
+    if (mine === undefined) {
+      mine = new Map();
+      this.reports.set(blockId, mine);
+      changed = true;
+    }
+    for (const [id, resolved] of results) {
+      if (mine.get(id) !== resolved) {
+        mine.set(id, resolved);
+        changed = true;
+      }
+    }
+    if (!changed) return;
+    this.version += 1;
+    for (const listener of [...this.listeners]) listener();
+  }
+
+  /** The block that shows the comment; `null` when every block answered and
+   * none resolved it (unanchored); `undefined` while an earlier block has
+   * not answered yet. */
+  owner(annotationId: string): string | null | undefined {
+    for (const blockId of this.blockIds) {
+      const verdict = this.reports.get(blockId)?.get(annotationId);
+      if (verdict === undefined) return undefined;
+      if (verdict) return blockId;
+    }
+    return null;
+  }
+
+  readonly subscribe = (listener: () => void): (() => void) => {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  };
+
+  readonly getVersion = (): number => this.version;
+}
+
+/** Provided by `Viewer` with the document's diagram block ids; a diagram
+ * block rendered on its own makes a one-block coordinator for itself. */
+export const DiagramAnchorClaimsContext = createContext<DiagramAnchorClaims | null>(null);

package/components/diagram/diagramControls.ts

@@ -0,0 +1,41 @@
+/**
+ * The canvas's own chrome, and why a pointer event on it must stop there.
+ *
+ * `DiagramCanvas` resolves what a click means over EVERYTHING under the
+ * pointer (`elementsFromPoint`, node → edge → cluster), because the edge hit
+ * layer sits above the nodes. The controls painted over the canvas — the
+ * zoom strip, the comment composer, the popout's own chrome — are not in the
+ * svg, so that walk skipped straight past them to whatever part happened to
+ * be underneath: pressing Zoom out over a node opened the composer on that
+ * node, and a press on the strip could start a pan.
+ *
+ * So a pointer event whose composed path contains a control surface never
+ * resolves a target, never opens the composer, and never starts a pan. It is
+ * the path rather than the point: a control knows it is a control, while a
+ * rectangle test would have to be kept in step with the layout.
+ *
+ * Mark new chrome with `data-diagram-control`. Buttons and toolbars count
+ * without marking, since anything the pointer can press is chrome by
+ * definition.
+ */
+export const DIAGRAM_CONTROL_SELECTOR =
+  '[data-diagram-control],[data-diagram-composer],[data-diagram-source-pane],[data-diagram-popout-chrome],button,[role="toolbar"],[role="button"],input,textarea,select,a[href]';
+
+function isElement(value: unknown): value is Element {
+  return typeof (value as Element | null)?.matches === 'function';
+}
+
+/** Whether this pointer event was aimed at the canvas's chrome rather than
+ * at the diagram. */
+export function isDiagramControlEvent(event: { target: EventTarget | null; nativeEvent?: Event }): boolean {
+  const native = event.nativeEvent ?? (event as unknown as Event);
+  const path = typeof native?.composedPath === 'function' ? native.composedPath() : [];
+  for (const entry of path) {
+    if (isElement(entry) && entry.matches(DIAGRAM_CONTROL_SELECTOR)) return true;
+  }
+  // `composedPath()` is empty once dispatch has finished, and jsdom-class
+  // DOMs may not implement it at all: the target's own ancestry is the same
+  // answer for everything but a shadow root.
+  const target = event.target;
+  return isElement(target) && target.closest(DIAGRAM_CONTROL_SELECTOR) !== null;
+}

package/components/diagram/index.ts

@@ -0,0 +1,39 @@
+/**
+ * The diagram engine's host surface (0.41.0): the one viewer over the
+ * renderer slot, its canvas, overlay, composer and Source pane, and the
+ * hooks and types a host wires them with. The renderer slot itself, the
+ * runtime slots and the anchor codecs live under `utils/` (`diagram-render`,
+ * `graphviz`, `mermaid`, `diagram-anchor`, `diagram-anchor-graphviz`,
+ * `diagram-projection`).
+ */
+export { DiagramViewer, type DiagramViewerProps } from './DiagramViewer';
+export { DiagramPopout } from './DiagramPopout';
+export { DiagramPending, DiagramInlineSource, DiagramBlockPending } from './DiagramPending';
+export { isDiagramControlEvent, DIAGRAM_CONTROL_SELECTOR } from './diagramControls';
+export { svgContentSize } from './svgContentSize';
+export { DiagramCanvas, KEY_PAN_PX, type DiagramCanvasHandle, type DiagramEscapeOutcome } from './DiagramCanvas';
+export { DiagramOverlay } from './DiagramOverlay';
+export { DiagramComposer } from './DiagramComposer';
+export { DiagramSourcePane } from './DiagramSourcePane';
+export {
+  useDiagramComments,
+  type DiagramComment,
+  type DiagramComposerDraft,
+  type DiagramCreateComment,
+  type DiagramHover,
+  type ResolvedDiagramComment,
+} from './useDiagramComments';
+export { useDiagramRender, type DiagramRenderState } from './useDiagramRender';
+export { useDiagramSourceDraft, PREVIEW_DEBOUNCE_MS, type DiagramSourceDraft, type SaveResult } from './useDiagramSourceDraft';
+export {
+  useDiagramViewport,
+  DRAG_THRESHOLD_PX,
+  TOUCH_DRAG_THRESHOLD_PX,
+  FIT_PADDING_PX,
+  WHEEL_ZOOM_SENSITIVITY,
+  ZOOM_MAX,
+  ZOOM_MIN,
+  ZOOM_STEP,
+  type ContentSize,
+  type Viewport,
+} from './useDiagramViewport';

package/components/diagram/svgContentSize.ts

@@ -0,0 +1,47 @@
+import type { ContentSize } from './useDiagramViewport';
+
+/**
+ * The rendered diagram's intrinsic size — a pure read of two svg attributes.
+ *
+ * It lives apart from `DiagramCanvas` (which re-exports it, so every
+ * published path still resolves) because the document's fence block needs
+ * it to size its inline box and nothing else of the canvas: importing it
+ * from the canvas dragged the whole zoom/pan surface, its viewport hook and
+ * lucide into any closure that touched a diagram block. The type import is
+ * erased, so this file's runtime dependencies are none.
+ */
+
+/** A numeric svg length: `206`, `206pt`, `206px`. */
+function svgLength(value: string | null): number {
+  if (value === null) return Number.NaN;
+  return Number.parseFloat(value);
+}
+
+/** The svg's intrinsic size, from its viewBox (Mermaid and Graphviz always
+ * write one), else its `width` / `height` attributes (a `pt` or `px` suffix
+ * is accepted, as Graphviz writes them). */
+export function svgContentSize(svg: SVGSVGElement): ContentSize | null {
+  const viewBox = svg.getAttribute('viewBox');
+  if (viewBox !== null) {
+    const parts = viewBox
+      .trim()
+      .split(/[\s,]+/u)
+      .map(Number);
+    const width = parts[2];
+    const height = parts[3];
+    if (
+      parts.length === 4 &&
+      width !== undefined &&
+      height !== undefined &&
+      Number.isFinite(width) &&
+      Number.isFinite(height) &&
+      width > 0 &&
+      height > 0
+    ) {
+      return { width, height };
+    }
+  }
+  const width = svgLength(svg.getAttribute('width'));
+  const height = svgLength(svg.getAttribute('height'));
+  return Number.isFinite(width) && Number.isFinite(height) && width > 0 && height > 0 ? { width, height } : null;
+}