@plannotator/ui 0.40.0 → 0.41.0

package/components/diagram/DiagramViewer.tsx

@@ -0,0 +1,276 @@
+import { 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 { DiagramSourcePane } from './DiagramSourcePane';
+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.
+ */
+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 && (
+        <DiagramSourcePane
+          draft={draft}
+          editable={editable}
+          markedLines={markedLines}
+          className="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"
+        />
+      )}
+      <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/index.ts

@@ -0,0 +1,36 @@
+/**
+ * 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 { DiagramCanvas, svgContentSize, 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';