wiki-formant 0.26.1 → 0.27.0

package/README.md

@@ -387,6 +387,35 @@ One copy also built two Maps keyed by a recursive `JSON.stringify` of every
 block, on every save, and never read either one. Matching is by id and always
 was. That half is not here.
 
+## History
+
+What each revision changed, as a history view shows it. `revisions` stays free
+of dependencies because every save imports it; this is the reading half, and it
+needs `fast-diff`, an optional peer.
+
+```tsx
+import { withChanges } from 'wiki-formant/history';
+import { RevisionChanges } from 'wiki-formant/react-server';
+
+const rows = withChanges(revisionsNewestFirst); // each row needs its `content`
+<RevisionChanges changes={rows[0].changes} label={type => BLOCK_LABELS[type]} />
+```
+
+- **Diffed on the server, from stored content.** radix-wiki used to send both
+  HTML bodies of every modified block to the browser and diff them there: 887 KB
+  of payload for a 13-revision page whose drawn diffs came to 25 KB. A row
+  leaves `withChanges` without its content.
+- **Words, not letters.** Semantic cleanup is on, so a rewritten sentence reads
+  as the old words struck and the new ones added.
+- **Leaves only.** A container's own entry restates its children. A leaf whose
+  type changed is a replacement and gets no text diff. `leafText` names the prose
+  field of a block beyond the core `content` one.
+- **A window diffs against what precedes it.** The oldest row is diffed against
+  an empty page, so fetch one revision more than you show and drop the last row.
+
+`RevisionChanges` marks struck and added text as `<del>` and `<ins>` and keys
+each change on `data-action`; `base.css` only resets the list.
+
 ## Feeds
 
 Three repos, four feeds, 47 of 64 significant lines identical — including,

package/dist/base.css

@@ -103,3 +103,16 @@ pre:hover > .code-copy-btn,
 [aria-sort='descending'] > .sort-header::after {
   --sort-icon: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M12 5v14'/%3E%3Cpath d='m19 12-7 7-7-7'/%3E%3C/svg%3E");
 }
+
+/* ---- RevisionChanges ------------------------------------------------------
+   A list of changes rather than a bulleted one, each diff directly under its
+   heading line. `del` and `ins` keep their browser defaults, a strike and an
+   underline, so a diff still reads before a stylesheet colours it. */
+.revision-changes {
+  display: grid;
+  gap: 0.5em;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+.revision-diff { margin: 0.25em 0 0; }

package/dist/history.d.ts

@@ -0,0 +1,37 @@
+import { type BlockChange, type BlockGroup, type DiffBlock } from './revisions.js';
+/** A stretch of text: -1 struck, 0 kept, 1 added. */
+export type DiffPart = [-1 | 0 | 1, string];
+/** A change as a history view lists it: the diff it draws, not the two bodies behind it. */
+export type HistoryChange = BlockChange<DiffPart[]>;
+/**
+ * Two HTML bodies as the words struck and added between them, or `undefined`
+ * when their text is the same. Semantic cleanup is on: without it a rewritten
+ * sentence comes out as fragments of the letters the two versions share.
+ */
+export declare function textDiff(from: string, to: string): DiffPart[] | undefined;
+export interface HistoryOptions<B> {
+    /** Defaults to `coreBlockGroups`, as in `diffBlocks`. */
+    containers?: (block: B) => BlockGroup<B>[] | null;
+    /**
+     * The HTML a leaf's diff is drawn from, or `undefined` for a block with no
+     * prose. Defaults to a `content` block's `text`, the core model's one prose leaf.
+     */
+    leafText?: (block: B) => string | undefined;
+}
+/**
+ * What changed between two versions of a page, leaves only: a container's own
+ * entry restates its children. A leaf whose type changed is a replacement, and
+ * one side's text against the other's would read as an edit, so it gets none.
+ */
+export declare function historyChanges<B extends DiffBlock>(oldContent: readonly B[], newContent: readonly B[], opts?: HistoryOptions<B>): HistoryChange[];
+/**
+ * A page's revisions, newest first, each carrying what changed against the one
+ * after it in the list and without the content it was diffed from. The last is
+ * diffed against an empty page, so a caller showing a window of the history
+ * passes one revision more than it shows and drops the last result.
+ */
+export declare function withChanges<R extends {
+    content: unknown;
+}, B extends DiffBlock = DiffBlock>(revisions: readonly R[], opts?: HistoryOptions<B>): (Omit<R, 'content'> & {
+    changes: HistoryChange[];
+})[];

package/dist/history.js

@@ -0,0 +1,67 @@
+// history.ts – what changed between revisions, as a history view draws it.
+//
+// `revisions.ts` decides which bump a save asks for and stays free of
+// dependencies, because every write path imports it. This is the reading half:
+// the same walk, turned into what a reviewer is shown. It needs a text diff, so
+// it needs `fast-diff`, an optional peer; hence its own subpath.
+//
+// radix-wiki had it first and shipped both HTML bodies of every modified block
+// to the browser to diff there: 887 KB of payload for a 13-revision page whose
+// drawn diffs came to 25 KB. The other two wikis showed a revision's message
+// and nothing of what it changed.
+import fastDiff from 'fast-diff';
+import { diffBlocks, extractBlocks } from './revisions.js';
+import { coreBlockGroups } from './blocks.js';
+import { stripHtml } from './text.js';
+/** Kept text is context, so a run longer than this keeps only its ends. */
+const KEPT_MAX = 60;
+const clip = (t) => (t.length > KEPT_MAX ? `${t.slice(0, 30)}…${t.slice(-30)}` : t);
+/**
+ * Two HTML bodies as the words struck and added between them, or `undefined`
+ * when their text is the same. Semantic cleanup is on: without it a rewritten
+ * sentence comes out as fragments of the letters the two versions share.
+ */
+export function textDiff(from, to) {
+    const a = stripHtml(from);
+    const b = stripHtml(to);
+    if (a === b)
+        return undefined;
+    const parts = fastDiff(a, b, undefined, true)
+        .filter(([, t]) => t.trim())
+        .map(([op, t]) => [op, op === 0 ? clip(t) : t]);
+    return parts.length ? parts : undefined;
+}
+const contentText = (block) => block.type === 'content' ? block.text : undefined;
+/**
+ * What changed between two versions of a page, leaves only: a container's own
+ * entry restates its children. A leaf whose type changed is a replacement, and
+ * one side's text against the other's would read as an edit, so it gets none.
+ */
+export function historyChanges(oldContent, newContent, opts = {}) {
+    const containers = opts.containers ?? (coreBlockGroups);
+    const leafText = opts.leafText ?? contentText;
+    const containerIds = new Set([...extractBlocks(oldContent, containers), ...extractBlocks(newContent, containers)]
+        .filter(({ block }) => containers(block))
+        .map(({ block }) => block.id));
+    return diffBlocks(oldContent, newContent, {
+        containers,
+        leafDiff: (from, to) => {
+            const a = from ? leafText(from) : '';
+            const b = to ? leafText(to) : '';
+            return a === undefined || b === undefined ? undefined : textDiff(a, b);
+        },
+    }).filter(c => !containerIds.has(c.id));
+}
+/**
+ * A page's revisions, newest first, each carrying what changed against the one
+ * after it in the list and without the content it was diffed from. The last is
+ * diffed against an empty page, so a caller showing a window of the history
+ * passes one revision more than it shows and drops the last result.
+ */
+export function withChanges(revisions, opts = {}) {
+    const blocks = (r) => (r?.content ?? []);
+    return revisions.map((revision, i) => {
+        const { content: _, ...rest } = revision;
+        return { ...rest, changes: historyChanges(blocks(revisions[i + 1]), blocks(revision), opts) };
+    });
+}

package/dist/react-server.d.ts

@@ -1,5 +1,6 @@
 import type { ComponentType, ReactNode } from 'react';
 import type { Control, FacetControlGroup, MetadataRow } from './taxonomy.js';
+import type { HistoryChange } from './history.js';
 /**
  * The shape a router's link component has to satisfy here.
  *
@@ -253,3 +254,16 @@ export interface InfoboxFactsProps {
  * shares its value — the way into the set, not dead text.
  */
 export declare function InfoboxFacts({ rows, link: Link, formatValue }: InfoboxFactsProps): import("react").JSX.Element | null;
+export interface RevisionChangesProps {
+    /** One revision's changes, from `historyChanges` or `withChanges` in `wiki-formant/history`. */
+    changes: readonly HistoryChange[];
+    /** What a block type is called where a reader sees it, such as the editor's label. Defaults to the type. */
+    label?: (type: string) => string;
+}
+/**
+ * What one revision changed, block by block, each prose leaf with its text
+ * diff. Struck and added text are `<del>` and `<ins>`, which a screen reader
+ * announces as such; their colours, and the action's, keyed on `data-action`,
+ * are the importing stylesheet's.
+ */
+export declare function RevisionChanges({ changes, label }: RevisionChangesProps): import("react").JSX.Element | null;

package/dist/react-server.js

@@ -21,6 +21,7 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 import { Fragment } from 'react';
 import { safeLinkHref } from './validation.js';
 import { isoDate } from './html.js';
+import { blockLocation } from './revisions.js';
 /**
  * The default for anything that does not need client-side navigation.
  *
@@ -207,3 +208,20 @@ export function InfoboxFacts({ rows, link: Link = Anchor, formatValue = formatFa
         return null;
     return (_jsx("table", { className: "infobox-facts", children: _jsx("tbody", { children: rows.map(row => (_jsxs("tr", { children: [_jsx("th", { scope: "row", children: row.label }), _jsx("td", { children: row.href ? _jsx(Link, { href: row.href, children: row.value }) : formatValue(row.value, row.type) })] }, row.label))) }) }));
 }
+const ACTION_LABEL = {
+    added: 'Added',
+    removed: 'Removed',
+    modified: 'Modified',
+    moved: 'Moved',
+};
+/**
+ * What one revision changed, block by block, each prose leaf with its text
+ * diff. Struck and added text are `<del>` and `<ins>`, which a screen reader
+ * announces as such; their colours, and the action's, keyed on `data-action`,
+ * are the importing stylesheet's.
+ */
+export function RevisionChanges({ changes, label = type => type }) {
+    if (!changes.length)
+        return null;
+    return (_jsx("ul", { className: "revision-changes", children: changes.map((c, i) => (_jsxs("li", { className: "revision-change", "data-action": c.action, children: [_jsx("span", { className: "revision-change-action", children: ACTION_LABEL[c.action] }), ` – ${label(c.type)} at ${blockLocation(c.path)}`, c.leafDiff && (_jsx("p", { className: "revision-diff", children: c.leafDiff.map(([op, text], j) => op === -1 ? _jsx("del", { children: text }, j) : op === 1 ? _jsx("ins", { children: text }, j) : _jsx("span", { children: text }, j)) }))] }, i))) }));
+}

package/dist/revisions.d.ts

@@ -56,6 +56,12 @@ interface Located<B> {
     block: B;
     path: string;
 }
+/**
+ * A path as a reader says it: `root.1.columns.0.blocks.2` is
+ * "Block 2 → Column 1 → Block 3". Positions count from one; a segment that
+ * names a group (`blocks`, `columns`) only says what the next number counts.
+ */
+export declare function blockLocation(path: string): string;
 /** Every block in the tree, flattened, each with the path that addresses it. */
 export declare function extractBlocks<B>(blocks: readonly B[], containers: (block: B) => BlockGroup<B>[] | null, basePath?: string): Located<B>[];
 /**

package/dist/revisions.js

@@ -6,6 +6,22 @@
 // Matching is by id.
 import { incrementVersion, parseVersion } from './versioning.js';
 import { coreBlockGroups } from './blocks.js';
+/**
+ * A path as a reader says it: `root.1.columns.0.blocks.2` is
+ * "Block 2 → Column 1 → Block 3". Positions count from one; a segment that
+ * names a group (`blocks`, `columns`) only says what the next number counts.
+ */
+export function blockLocation(path) {
+    let group = '';
+    const out = [];
+    for (const seg of path.split('.').slice(1)) {
+        if (/^\d+$/.test(seg))
+            out.push(`${group === 'columns' ? 'Column' : 'Block'} ${Number(seg) + 1}`);
+        else
+            group = seg;
+    }
+    return out.join(' → ');
+}
 /** Every block in the tree, flattened, each with the path that addresses it. */
 export function extractBlocks(blocks, containers, basePath = 'root') {
     const out = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wiki-formant",
-  "version": "0.26.1",
+  "version": "0.27.0",
   "description": "The portable half of a wiki: derived taxonomy and facet controls, a version-negotiating MCP transport, markdown twins, block rendering, a rich-text editor engine, and conditional-GET plumbing.",
   "type": "module",
   "license": "MIT",
@@ -78,6 +78,10 @@
       "types": "./dist/revisions.d.ts",
       "import": "./dist/revisions.js"
     },
+    "./history": {
+      "types": "./dist/history.d.ts",
+      "import": "./dist/history.js"
+    },
     "./search": {
       "types": "./dist/search.d.ts",
       "import": "./dist/search.js"
@@ -209,6 +213,7 @@
     "@types/node": "^22.0.0",
     "@types/react": "^19.0.0",
     "@types/sanitize-html": "^2.16.1",
+    "fast-diff": "^1.3.0",
     "jose": "^6.2.10",
     "jsdom": "^30.1.0",
     "react": "^19.2.4",
@@ -227,12 +232,13 @@
     "@tiptap/extension-table-header": ">=2.10",
     "@tiptap/extension-table-row": ">=2.10",
     "@tiptap/extension-youtube": ">=2.10",
+    "@tiptap/pm": ">=2.10",
     "@tiptap/react": ">=2.10",
     "@tiptap/starter-kit": ">=2.10",
+    "fast-diff": ">=1.3",
     "jose": ">=5",
     "react": ">=18",
-    "sanitize-html": ">=2",
-    "@tiptap/pm": ">=2.10"
+    "sanitize-html": ">=2"
   },
   "peerDependenciesMeta": {
     "react": {
@@ -285,6 +291,9 @@
     },
     "@tiptap/pm": {
       "optional": true
+    },
+    "fast-diff": {
+      "optional": true
     }
   }
 }