@plannotator/ui 0.27.0 → 0.28.0

package/README.md

@@ -62,6 +62,22 @@ Building your own tooltip and removing the built-in double-click reset are host-
 
 Requires `@plannotator/markdown-editor ^0.3.2` and `@plannotator/atomic-editor ^0.7.0`. See HANDOFF.md § "Wiki-link seams (0.27.0)".
 
+### Frozen markdown diff (`MarkdownDiff`)
+
+- **`MarkdownDiff` renders two markdown revisions as a frozen, themed comparison** — the newer revision as the real (uncollapsed) document, deletions projected struck-through in place, char/word change emphasis, a change-count toolbar with prev/next, a clickable keyboard-accessible overview rail, and a changed-line gutter. The surface is never editable (edits are rejected at the state and view boundaries; the content DOM is `contenteditable="false"`).
+- **Same shim pattern as `MarkdownEditor`:** theme resolves from `ThemeProvider` (or pass `mode` directly), `gridEnabled` applies the identical card chrome, and `extensions` composes CM6 extensions — `wikiLinks` included — into the frozen view, with the same captured-once, stable-reference calling convention:
+  ```tsx
+  import { MarkdownDiff } from "@plannotator/ui/components/MarkdownDiff";
+  import { wikiLinks } from "@plannotator/ui/components/MarkdownEditor";
+
+  const diffExtensions = [wikiLinks({ resolve, onOpen })]; // stable reference!
+  <MarkdownDiff originalMarkdown={older} modifiedMarkdown={newer} documentId={docId}
+                editorHandleRef={ref} extensions={diffExtensions} />
+  ```
+- **Bytes are the contract:** `ref.current.getMarkdown()` / `.getOriginalMarkdown()` return the exact input strings (CRLF and trailing whitespace included); `getChangeCount()` / `goToNextChange()` / `goToPreviousChange()` drive review navigation.
+
+Requires `@plannotator/markdown-editor ^0.4.0` and `@plannotator/atomic-editor ^0.8.0` (which adds a `@codemirror/merge` peer — declared by this package). See HANDOFF.md § "Frozen markdown diff (0.28.0)".
+
 ## Consuming it (e.g. from Workspaces)
 
 ```bash

package/components/MarkdownDiff.tsx

@@ -0,0 +1,60 @@
+import React from 'react';
+import {
+  MarkdownDiff as PackagedMarkdownDiff,
+  type MarkdownDiffHandle,
+  type MarkdownDiffProps as PackagedMarkdownDiffProps,
+} from '@plannotator/markdown-editor';
+import '@plannotator/markdown-editor/themes/plannotator.css';
+import { useTheme } from './ThemeProvider';
+
+export type { MarkdownDiffHandle };
+
+/* @plannotator/ui is the single supported contract for hosts — do NOT import
+   AtomicDiffEditor or @plannotator/atomic-editor directly (both are outside
+   the import allowlist). Extension builders (wikiLinks, slashCommands,
+   selectionToolbar) are re-exported from ./MarkdownEditor; build them there
+   and pass the result through the `extensions` prop below — the frozen diff
+   view composes them the same way the editor does. */
+
+/* Grid-mode card utilities mirror components/MarkdownEditor.tsx exactly, so a
+   host toggling editor <-> diff keeps identical card chrome. They stay here
+   (not in the package) because they're Plannotator design-system Tailwind
+   classes and this file is @source-scanned. */
+const GRID_CARD_CLASSES = 'px-5 md:px-8 lg:px-10 xl:px-12 shadow-xl border border-border/50';
+
+export interface MarkdownDiffProps
+  extends Omit<PackagedMarkdownDiffProps, 'mode' | 'cardClassName'> {
+  /** Mirrors MarkdownEditor's grid card chrome so editor <-> diff doesn't jump. */
+  gridEnabled?: boolean;
+  /** Theme color mode. Defaults to the ThemeProvider's resolved mode (Plannotator
+      passes nothing); a host without ThemeProvider can supply it directly. */
+  mode?: PackagedMarkdownDiffProps['mode'];
+}
+
+/* Theme-bridging shim around @plannotator/markdown-editor's MarkdownDiff — the
+   frozen two-revision comparison surface (newer revision as the real document,
+   deletions projected struck-through in place). Same pattern as the
+   MarkdownEditor shim: resolve the color mode from ThemeProvider beneath the
+   host's provider and pass it down as a prop.
+
+   The byte contract lives on `editorHandleRef`: getMarkdown() returns the
+   exact `modifiedMarkdown` supplied, getOriginalMarkdown() the exact
+   `originalMarkdown` — both byte-identical to the inputs. The surface itself
+   is frozen: document-changing transactions are rejected at the state and
+   view boundaries, and the content DOM is contenteditable="false".
+
+   `extensions` follows the editor's calling convention: CAPTURED ONCE per
+   mounted comparison (keyed on `documentId` + both document strings) — pass a
+   stable array and feed changing data through callbacks that close over live
+   state. Build extensions against YOUR copy of the `@codemirror/*` packages;
+   two live copies of `@codemirror/state` break the view. */
+export const MarkdownDiff: React.FC<MarkdownDiffProps> = ({ gridEnabled, mode, ...props }) => {
+  const { resolvedMode } = useTheme();
+  return (
+    <PackagedMarkdownDiff
+      {...props}
+      mode={mode ?? resolvedMode}
+      cardClassName={gridEnabled ? GRID_CARD_CLASSES : undefined}
+    />
+  );
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plannotator/ui",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "type": "module",
   "exports": {
     "./components/*": "./components/*.tsx",
@@ -57,6 +57,7 @@
     "@codemirror/lang-yaml": "^6.1.3",
     "@codemirror/language": "^6.12.3",
     "@codemirror/legacy-modes": "^6.5.3",
+    "@codemirror/merge": "^6.12.2",
     "@codemirror/search": "^6.7.0",
     "@codemirror/state": "^6.6.0",
     "@codemirror/view": "^6.43.0",
@@ -65,9 +66,9 @@
     "@lezer/common": "^1.5.2",
     "@lezer/highlight": "^1.2.3",
     "@pierre/diffs": "1.2.8",
-    "@plannotator/atomic-editor": "^0.7.0",
+    "@plannotator/atomic-editor": "^0.8.0",
     "@plannotator/core": "0.22.0",
-    "@plannotator/markdown-editor": "^0.3.2",
+    "@plannotator/markdown-editor": "^0.4.0",
     "@plannotator/web-highlighter": "^0.8.1",
     "@tanstack/react-table": "^8.21.3",
     "@viz-js/viz": "^3.25.0",