@plannotator/ui 0.40.0 → 0.41.0

package/components/diagram/DiagramOverlay.tsx

@@ -0,0 +1,215 @@
+import React, { useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { diagramTargetName } from '@plannotator/core/diagram-anchor';
+import { cn } from '../../lib/utils';
+import { projectElement, type ScreenRect } from '../../utils/diagram-projection';
+import type { DiagramCanvasHandle } from './DiagramCanvas';
+import type { DiagramComposerDraft, DiagramHover, ResolvedDiagramComment } from './useDiagramComments';
+
+/**
+ * Rings, numbered badges, the hover chip and the composer's anchor point,
+ * projected from each part's `getBBox()` through `getScreenCTM()`. The
+ * layer is a sibling of the transformed wrapper, so a ring is the same 2px
+ * at every zoom. Reprojection is one requestAnimationFrame pass per change
+ * (viewport, host resize, a new render, a new comment list): a design
+ * constant, not a limit.
+ */
+
+/** Ring inset from the part's box, in overlay pixels. */
+const RING_PAD_PX = 3;
+
+interface Projected {
+  readonly id: string;
+  readonly number: number;
+  readonly label: string;
+  readonly resolved: boolean;
+  readonly whole: boolean;
+  readonly rect: ScreenRect;
+  readonly additional: readonly ScreenRect[];
+}
+
+function pad(rect: ScreenRect): ScreenRect {
+  return {
+    left: rect.left - RING_PAD_PX,
+    top: rect.top - RING_PAD_PX,
+    width: rect.width + RING_PAD_PX * 2,
+    height: rect.height + RING_PAD_PX * 2,
+  };
+}
+
+function ringStyle(rect: ScreenRect): React.CSSProperties {
+  return { left: rect.left, top: rect.top, width: rect.width, height: rect.height };
+}
+
+export function DiagramOverlay({
+  handle,
+  resolved,
+  hover,
+  composer,
+  selectedCommentId,
+  onSelectComment,
+  renderComposer,
+}: {
+  handle: DiagramCanvasHandle;
+  resolved: readonly ResolvedDiagramComment[];
+  hover: DiagramHover | null;
+  composer: DiagramComposerDraft | null;
+  selectedCommentId: string | null;
+  onSelectComment: ((id: string | null) => void) | undefined;
+  /** The composer, given the primary ring's rectangle to sit beside. */
+  renderComposer: (anchorRect: ScreenRect) => React.ReactNode;
+}) {
+  const [projected, setProjected] = useState<readonly Projected[]>([]);
+  const [hoverRect, setHoverRect] = useState<ScreenRect | null>(null);
+  const [draftRects, setDraftRects] = useState<{
+    primary: ScreenRect;
+    additional: readonly ScreenRect[];
+  } | null>(null);
+  const frameRef = useRef<number | null>(null);
+  const { viewport, hostRef, panIntoView } = handle;
+
+  // One projection pass per change, after the wrapper's transform has
+  // been written to the DOM (layout effect), on the next frame.
+  useLayoutEffect(() => {
+    const run = () => {
+      frameRef.current = null;
+      const host = hostRef.current;
+      if (host === null) return;
+      const hostRect = host.getBoundingClientRect();
+      const next: Projected[] = [];
+      for (const entry of resolved) {
+        if (entry.element === null) continue;
+        const rect = projectElement(entry.element, hostRect);
+        if (rect === null) continue;
+        next.push({
+          id: entry.id,
+          number: entry.number,
+          label: entry.label,
+          resolved: entry.resolved,
+          whole: entry.whole,
+          rect: pad(rect),
+          additional: entry.additional
+            .map((el) => projectElement(el, hostRect))
+            .filter((r): r is ScreenRect => r !== null)
+            .map(pad),
+        });
+      }
+      setProjected(next);
+      const hovered = hover === null ? null : projectElement(hover.element, hostRect);
+      setHoverRect(hovered === null ? null : pad(hovered));
+      if (composer === null) {
+        setDraftRects(null);
+      } else {
+        const primary = projectElement(composer.primary.element, hostRect);
+        setDraftRects(
+          primary === null
+            ? null
+            : {
+                primary: pad(primary),
+                additional: composer.additional
+                  .map((extra) => projectElement(extra.element, hostRect))
+                  .filter((r): r is ScreenRect => r !== null)
+                  .map(pad),
+              },
+        );
+      }
+    };
+    if (frameRef.current !== null) cancelAnimationFrame(frameRef.current);
+    if (typeof requestAnimationFrame === 'function') {
+      frameRef.current = requestAnimationFrame(run);
+    } else {
+      run();
+    }
+    return () => {
+      if (frameRef.current !== null) cancelAnimationFrame(frameRef.current);
+      frameRef.current = null;
+    };
+  }, [composer, hostRef, hover, resolved, viewport]);
+
+  // Selecting a comment in the panel pans its part into view; the ring
+  // pulses through the selected class below.
+  const selectedRect = projected.find((entry) => entry.id === selectedCommentId)?.rect;
+  const pannedForRef = useRef<string | null>(null);
+  useEffect(() => {
+    if (selectedRect === undefined || selectedCommentId === null) return;
+    if (pannedForRef.current === selectedCommentId) return;
+    pannedForRef.current = selectedCommentId;
+    panIntoView(selectedRect);
+  }, [panIntoView, selectedCommentId, selectedRect]);
+  useEffect(() => {
+    if (selectedCommentId === null) pannedForRef.current = null;
+  }, [selectedCommentId]);
+
+  return (
+    <div data-diagram-overlay="" className="pointer-events-none absolute inset-0 z-[1]">
+      {projected.map((entry) => (
+        <div key={entry.id} data-diagram-mark={entry.id} data-number={entry.number}>
+          <div
+            className={cn(
+              'absolute rounded-sm border-2',
+              entry.resolved ? 'border-muted-foreground/50' : 'border-primary/70',
+              entry.id === selectedCommentId && 'animate-pulse border-primary',
+            )}
+            style={ringStyle(entry.rect)}
+            aria-hidden="true"
+          />
+          {entry.additional.map((rect, index) => (
+            <div
+              key={index}
+              className="absolute rounded-sm border-2 border-dashed border-primary/60"
+              style={ringStyle(rect)}
+              aria-hidden="true"
+            />
+          ))}
+          <button
+            type="button"
+            data-diagram-badge={entry.id}
+            className={cn(
+              'pointer-events-auto absolute flex size-5 -translate-y-1/2 items-center justify-center rounded-full border font-mono text-[10px] font-medium tabular-nums',
+              // A part's badge rides its top-right corner; the whole
+              // diagram's sits top-left, clear of the parts' badges.
+              entry.whole ? '-translate-x-1/2' : 'translate-x-1/2',
+              entry.resolved
+                ? 'border-border bg-muted text-muted-foreground'
+                : 'border-primary-foreground/40 bg-primary text-primary-foreground',
+              entry.id === selectedCommentId && 'ring-2 ring-primary/40',
+            )}
+            style={{ left: entry.whole ? entry.rect.left : entry.rect.left + entry.rect.width, top: entry.rect.top }}
+            aria-label={`Comment ${entry.number}: ${entry.label}`}
+            title={entry.label}
+            onClick={(event) => {
+              event.stopPropagation();
+              onSelectComment?.(entry.id);
+            }}
+            onPointerDown={(event) => event.stopPropagation()}
+            onPointerUp={(event) => event.stopPropagation()}
+          >
+            {entry.number}
+          </button>
+        </div>
+      ))}
+      {hoverRect !== null && hover !== null && composer === null && (
+        <div data-diagram-hover="">
+          <div className="absolute rounded-sm border-2 border-primary/50" style={ringStyle(hoverRect)} aria-hidden="true" />
+          <span
+            className="absolute -translate-y-full whitespace-nowrap rounded-sm border border-border bg-card px-1.5 py-0.5 text-[10px] text-muted-foreground"
+            style={{ left: hoverRect.left, top: hoverRect.top - 4 }}
+          >
+            {hover.target.label !== '' ? hover.target.label : diagramTargetName(hover.target)}
+            {hover.target.label !== '' && (
+              <span className="text-muted-foreground/70"> · {diagramTargetName(hover.target)}</span>
+            )}
+          </span>
+        </div>
+      )}
+      {draftRects !== null && composer !== null && (
+        <div data-diagram-draft="">
+          <div className="absolute rounded-sm border-2 border-primary" style={ringStyle(draftRects.primary)} aria-hidden="true" />
+          {draftRects.additional.map((rect, index) => (
+            <div key={index} className="absolute rounded-sm border-2 border-dashed border-primary" style={ringStyle(rect)} aria-hidden="true" />
+          ))}
+          {renderComposer(draftRects.primary)}
+        </div>
+      )}
+    </div>
+  );
+}

package/components/diagram/DiagramPopout.tsx

@@ -0,0 +1,70 @@
+import { Code } from 'lucide-react';
+import { useState } from 'react';
+import { cn } from '../../lib/utils';
+import { PopoutDialog } from '../PopoutDialog';
+import { Button } from '../ui/button';
+import { DiagramViewer, type DiagramViewerProps } from './DiagramViewer';
+
+/**
+ * The diagram at full size over the document: the SAME `DiagramViewer` the
+ * fence renders inline, in the `TablePopout` chrome (a non-modal Base UI
+ * dialog with the dark scrim; annotation toolbars that portal outside it
+ * stay interactive). One code path: everything the popout can do, the
+ * inline canvas can do, only larger. The canvas takes the keyboard on
+ * arrival so `+`, `-`, `0` and Escape work without a click; Escape walks
+ * the viewer's ladder first (a draft, a selection) and closes the popout
+ * only when nothing else is left to close.
+ */
+export function DiagramPopout({
+  open,
+  onClose,
+  title,
+  container,
+  dataAttributes,
+  ...viewer
+}: Omit<DiagramViewerProps, 'onDismiss' | 'autoFocus' | 'sourceOpen' | 'className' | 'canvasClassName'> & {
+  open: boolean;
+  onClose: () => void;
+  /** The dialog's accessible name and the header label. */
+  title: string;
+  /** Portal target; null falls back to body. */
+  container?: HTMLElement | null;
+  dataAttributes?: Record<string, string>;
+}) {
+  const [sourceOpen, setSourceOpen] = useState(false);
+  const hasPane = viewer.onSave !== undefined;
+  return (
+    <PopoutDialog
+      open={open}
+      onClose={onClose}
+      title={title}
+      container={container}
+      className="h-[calc(100vh-2rem)] w-[calc(100vw-2rem)] max-w-none"
+      dataAttributes={{ 'data-diagram-popout': '', ...dataAttributes }}
+    >
+      <div className="flex h-9 shrink-0 items-center gap-2 border-b border-border pl-4 pr-12">
+        <span className="truncate text-xs font-medium text-foreground">{title}</span>
+        <span className="flex-1" />
+        {hasPane && (
+          <Button
+            type="button"
+            variant="ghost"
+            size="xs"
+            data-diagram-source-toggle=""
+            aria-pressed={sourceOpen}
+            className={cn('shrink-0', sourceOpen && 'bg-primary/15 text-primary')}
+            title={sourceOpen ? 'Close the source pane' : 'Open the diagram source beside the canvas'}
+            onClick={() => setSourceOpen((value) => !value)}
+          >
+            <Code className="size-3.5" aria-hidden="true" />
+            <span>Source</span>
+          </Button>
+        )}
+      </div>
+      <div className="min-h-0 flex-1">
+        {/* The popout owns the screen: every touch drag is a pan. */}
+        <DiagramViewer {...viewer} sourceOpen={sourceOpen} onDismiss={onClose} autoFocus canvasClassName="touch-none" />
+      </div>
+    </PopoutDialog>
+  );
+}

package/components/diagram/DiagramSourcePane.tsx

@@ -0,0 +1,244 @@
+import { defaultKeymap, history, historyKeymap } from '@codemirror/commands';
+import { Compartment, EditorState, type Extension } from '@codemirror/state';
+import { Decoration, EditorView, keymap, lineNumbers, type DecorationSet } from '@codemirror/view';
+import React, { useEffect, useRef } from 'react';
+import { cn } from '../../lib/utils';
+import { Button } from '../ui/button';
+import type { DiagramSourceDraft } from './useDiagramSourceDraft';
+
+/**
+ * The Source pane beside the canvas (owner ruling: source and diagram are
+ * one view; the pane opens beside the canvas and never replaces it). It
+ * opens on the LEFT of the canvas on the desktop row and stacks UNDER it on
+ * the phone; the caller (DiagramViewer) owns that placement through this
+ * component's `className`. A plain-text CodeMirror buffer, read-only
+ * without edit access and never hidden. Save, Discard, "Draft · unsaved"
+ * and the Reload strip live here; the canvas is the live preview. The
+ * selected comment's source line shows as a line mark.
+ *
+ * Not the package MarkdownEditor (markdown extensions, continuous save):
+ * the draft is local until Save.
+ */
+
+const LINE_MARK_CLASS = 'cm-diagram-comment-line';
+
+const paneTheme = EditorView.theme({
+  '&': {
+    height: '100%',
+    backgroundColor: 'var(--card)',
+    color: 'var(--card-foreground)',
+    fontFamily: 'var(--font-mono)',
+  },
+  '&.cm-focused': { outline: 'none' },
+  '.cm-scroller': { fontFamily: 'var(--font-mono)' },
+  '.cm-gutters': {
+    backgroundColor: 'var(--card)',
+    color: 'var(--muted-foreground)',
+    borderRight: '1px solid var(--border)',
+  },
+  '.cm-activeLineGutter': { backgroundColor: 'transparent' },
+  '.cm-content': { padding: '8px 0' },
+  '.cm-line': { padding: '0 12px' },
+  [`.${LINE_MARK_CLASS}`]: { backgroundColor: 'color-mix(in oklab, var(--primary) 18%, transparent)' },
+});
+
+function lineMarks(state: EditorState, range: readonly [number, number] | null): DecorationSet {
+  if (range === null) return Decoration.none;
+  const first = Math.max(1, Math.min(range[0], state.doc.lines));
+  const last = Math.max(first, Math.min(range[1], state.doc.lines));
+  const marks = [];
+  for (let n = first; n <= last; n += 1) {
+    marks.push(Decoration.line({ class: LINE_MARK_CLASS }).range(state.doc.line(n).from));
+  }
+  return Decoration.set(marks);
+}
+
+function Strip({
+  tone,
+  title,
+  children,
+  action,
+  dataAttr,
+}: {
+  tone: 'accent' | 'destructive';
+  title: string;
+  children?: React.ReactNode;
+  action?: React.ReactNode;
+  dataAttr: string;
+}) {
+  return (
+    <div
+      {...{ [dataAttr]: '' }}
+      role={tone === 'destructive' ? 'alert' : 'status'}
+      className={cn(
+        'flex items-start gap-2 rounded-md border px-2.5 py-2 text-xs',
+        tone === 'destructive' ? 'border-destructive/40 bg-destructive/5 text-destructive' : 'border-primary/30 bg-primary/5 text-foreground',
+      )}
+    >
+      <div className="min-w-0 flex-1">
+        <div className="font-medium">{title}</div>
+        {children !== undefined && <div className="mt-0.5 text-muted-foreground">{children}</div>}
+      </div>
+      {action}
+    </div>
+  );
+}
+
+export function DiagramSourcePane({
+  draft,
+  editable,
+  markedLines,
+  className,
+}: {
+  draft: DiagramSourceDraft;
+  editable: boolean;
+  /** The selected comment's source line range, marked in the gutter. */
+  markedLines: readonly [number, number] | null;
+  className?: string;
+}) {
+  const hostRef = useRef<HTMLDivElement | null>(null);
+  const viewRef = useRef<EditorView | null>(null);
+  const editableCompartment = useRef(new Compartment());
+  const marksCompartment = useRef(new Compartment());
+  const draftRef = useRef(draft);
+  draftRef.current = draft;
+
+  // One view for the pane's life; props reconfigure compartments.
+  useEffect(() => {
+    const host = hostRef.current;
+    if (host === null) return;
+    const editableExtensions = (on: boolean): Extension => [EditorView.editable.of(on), EditorState.readOnly.of(!on)];
+    const view = new EditorView({
+      parent: host,
+      state: EditorState.create({
+        doc: draftRef.current.draft,
+        extensions: [
+          lineNumbers(),
+          history(),
+          EditorView.lineWrapping,
+          paneTheme,
+          keymap.of([
+            {
+              key: 'Mod-s',
+              run: () => {
+                void draftRef.current.save();
+                return true;
+              },
+            },
+            ...historyKeymap,
+            ...defaultKeymap,
+          ]),
+          editableCompartment.current.of(editableExtensions(editable)),
+          marksCompartment.current.of(EditorView.decorations.of(Decoration.none)),
+          EditorView.updateListener.of((update) => {
+            if (update.docChanged) draftRef.current.setDraft(update.state.doc.toString());
+          }),
+        ],
+      }),
+    });
+    viewRef.current = view;
+    return () => {
+      view.destroy();
+      viewRef.current = null;
+    };
+    // The initial doc and editable value seed the state; later values
+    // flow through the effects below.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  useEffect(() => {
+    viewRef.current?.dispatch({
+      effects: editableCompartment.current.reconfigure([EditorView.editable.of(editable), EditorState.readOnly.of(!editable)]),
+    });
+  }, [editable]);
+
+  // Discard and Reload replace the buffer from outside; typing never
+  // round-trips (the listener above already reported it).
+  useEffect(() => {
+    const view = viewRef.current;
+    if (view === null) return;
+    const current = view.state.doc.toString();
+    if (current === draft.draft) return;
+    view.dispatch({
+      changes: { from: 0, to: current.length, insert: draft.draft },
+    });
+  }, [draft.draft]);
+
+  useEffect(() => {
+    const view = viewRef.current;
+    if (view === null) return;
+    view.dispatch({
+      effects: marksCompartment.current.reconfigure(EditorView.decorations.of(lineMarks(view.state, markedLines))),
+    });
+    if (markedLines !== null && markedLines[0] <= view.state.doc.lines) {
+      view.dispatch({
+        effects: EditorView.scrollIntoView(view.state.doc.line(markedLines[0]).from, { y: 'center' }),
+      });
+    }
+  }, [markedLines]);
+
+  return (
+    <section
+      data-diagram-source-pane=""
+      aria-label="Diagram source"
+      className={cn('flex min-h-0 flex-col bg-card', className)}
+      // Escape LEAVES the buffer; it never reaches whatever is behind
+      // the pane. In a popout that outer handler closes it, and one
+      // keystroke mid-draft would take the pane, the preview and the
+      // person's place with it.
+      onKeyDown={(event) => {
+        if (event.key !== 'Escape' || event.defaultPrevented) return;
+        event.preventDefault();
+        event.stopPropagation();
+        viewRef.current?.contentDOM.blur();
+      }}
+    >
+      <div className="flex h-9 shrink-0 items-center gap-2 border-b border-border px-3">
+        <span className="text-xs font-medium text-foreground">Source</span>
+        {editable && draft.dirty && (
+          <span data-diagram-draft-state="" className="text-[10px] text-muted-foreground">
+            Draft · unsaved
+          </span>
+        )}
+        {!editable && <span className="text-[10px] text-muted-foreground">Read only</span>}
+        <span className="flex-1" />
+        {editable && (
+          <>
+            <Button type="button" variant="ghost" size="xs" disabled={!draft.dirty || draft.saving} onClick={draft.discard}>
+              Discard
+            </Button>
+            <Button type="button" size="xs" disabled={!draft.dirty || draft.saving || draft.stale} onClick={() => void draft.save()}>
+              {draft.saving ? 'Saving…' : 'Save'}
+            </Button>
+          </>
+        )}
+      </div>
+      {draft.stale && (
+        <div className="shrink-0 border-b border-border p-2">
+          <Strip
+            tone="accent"
+            dataAttr="data-diagram-reload-strip"
+            title="Changed since you opened"
+            action={
+              <Button variant="outline" size="xs" onClick={draft.reload}>
+                Reload
+              </Button>
+            }
+          >
+            {draft.dirty
+              ? 'Someone saved a newer version. Reload to see it; your draft stays in the pane and Save is held until you do.'
+              : 'Someone saved a newer version. Reload to see it.'}
+          </Strip>
+        </div>
+      )}
+      {draft.saveError !== null && (
+        <div className="shrink-0 border-b border-border p-2">
+          <Strip tone="destructive" dataAttr="data-diagram-save-error" title="The diagram was not saved">
+            {draft.saveError}
+          </Strip>
+        </div>
+      )}
+      <div ref={hostRef} data-diagram-source-editor="" className="min-h-0 flex-1 overflow-hidden text-xs" />
+    </section>
+  );
+}