noteloom 0.3.0 → 0.3.1

package/README.md

@@ -440,41 +440,25 @@ A comment thread is `{ id, blockId, anchorRunIds, resolved, messages: [{ id, aut
 
 ## Version history
 
-Point-in-time document snapshots, stored in IndexedDB (a third object store, alongside `usePersistedDocument`'s `documents` and Templates' `templates`) — periodic, manual, or both. `examples/07-version-history/` is a complete runnable app with a version list and one-click restore.
+Google Docs-style — there's no "type a label and save" step. Point-in-time document snapshots (stored in IndexedDB, a third object store alongside `usePersistedDocument`'s `documents` and Templates' `templates`) are captured automatically after each burst of edits settles down, each one attributed to whoever made the changes. `examples/07-version-history/` is a complete runnable app.
 
 ```jsx
-import { createPeriodicVersionSnapshotter, useDocumentVersions, saveDocumentVersion, applyDocumentTemplate, exportDocumentJSON } from 'noteloom';
-
-// Automatic: snapshot every few minutes, keep the most recent 50.
-useEffect(() => {
-  const snapshotter = createPeriodicVersionSnapshotter({ store: editor.store, docId, intervalMs: 5 * 60 * 1000 });
-  return () => snapshotter.stop();
-}, [editor.store, docId]);
-
-// Manual: "save a version now" button.
-async function saveNow(label) {
-  const doc = JSON.parse(exportDocumentJSON(editor.store)); // exportDocumentJSON returns a JSON *string* — parse it first
-  await saveDocumentVersion({ id: crypto.randomUUID(), docId, timestamp: Date.now(), label, doc });
-}
+import { useEditor, NoteloomEditor, VersionHistory } from 'noteloom';
 
-// A version list:
-function VersionList({ docId }) {
-  const { versions, isLoaded } = useDocumentVersions(docId); // newest first
-  if (!isLoaded) return <p>Loading…</p>;
-  return (
-    <ul>
-      {versions.map((v) => (
-        <li key={v.id}>
-          {v.label ?? '(untitled)'} — {new Date(v.timestamp).toLocaleString()}
-          <button onClick={() => applyDocumentTemplate(editor.store, v.doc)}>Restore</button>
-        </li>
-      ))}
-    </ul>
-  );
-}
+const editor = useEditor({ currentUserId: currentUser.id }); // stamps every edit's author, see below
+
+<NoteloomEditor editor={editor}>
+  <VersionHistory docId={docId} />
+</NoteloomEditor>;
 ```
 
-Restoring needs no new function — it's the exact same `applyDocumentTemplate(store, doc)` Templates already uses to wholesale-replace a live editor's content. `saveDocumentVersion`/`loadDocumentVersion`/`deleteDocumentVersion`/`listDocumentVersions` are the raw storage operations `useDocumentVersions` is built on. `createPeriodicVersionSnapshotter({ store, docId, intervalMs?, label?, maxVersions? })` prunes the oldest version past `maxVersions` (default 50) after each snapshot, so a long-running document doesn't grow the store unbounded.
+That's the whole integration. `<VersionHistory>` is self-contained: it renders the "Version history" button, and for as long as it's mounted it also quietly captures snapshots in the background — no separate wiring needed. Clicking the button opens a drawer (matching the built-in Comments UI's own design language) listing every version grouped by day, each showing an avatar, author, relative time, and a lightweight summary ("3 blocks changed"); clicking one opens it on a **Changes** tab — a word-level diff against the version right before it, insertions highlighted green, deletions struck through in red, Google Docs "show changes"-style — with a **Preview** tab alongside for a plain read-only render, and a "Restore this version" button.
+
+**Attribution** — `currentUserId` (passed to `useEditor()`, or `history.setDefaultActorId(id)`/`new History(store, { defaultActorId })` for the granular API) is stamped as every edit's `actorId` automatically; `VersionHistory`/`createAutoVersionHistory` read it straight off the history log, no separate identity plumbing required. Omit it and versions still get created, just with `authorId: null` (shown as "Unknown").
+
+**Tuning the capture window** — `<VersionHistory docId idleMs={5 * 60 * 1000} maxVersions={200} />`: `idleMs` (default 5 minutes) is how long edits need to pause before a version is closed and saved (a smaller value in the example app, so you don't have to actually wait); `maxVersions` prunes the oldest versions beyond that count. For the granular API, or to save an explicit snapshot right before some risky action, use `createAutoVersionHistory({ store, docId, idleMs?, maxVersions? })` directly — it returns `{ stop, flush }`; `flush()` closes and saves the current window immediately instead of waiting for the idle gap (e.g. right before navigating away).
+
+Restoring needs no new function — it's the exact same `applyDocumentTemplate(store, doc)` Templates already uses to wholesale-replace a live editor's content, which is what the drawer's own Restore button calls. `saveDocumentVersion`/`loadDocumentVersion`/`deleteDocumentVersion`/`listDocumentVersions` are the raw storage operations everything above is built on, for anywhere the built-in UI doesn't fit; `useDocumentVersions(docId)` is the reactive hook if you want to build your own list instead of `<VersionHistory>`; `diffDocumentsHTML(prevDoc, nextDoc)` is the diffing function behind the Changes tab (pass `null` as `prevDoc` to mark everything as newly added), for building a custom diff view instead.
 
 ## Right-to-left / multi-language text
 

package/dist/index.d.ts

@@ -148,6 +148,8 @@ export interface HistoryOptions {
   idleMs?: number;
   trackChanges?: boolean;
   maxChangeLogSize?: number;
+  /** Stamped as every edit's actorId when a perform/performBatch call doesn't pass its own -- see useEditor's `currentUserId`. */
+  defaultActorId?: string | null;
 }
 
 export interface HistoryLogEntry {
@@ -171,6 +173,8 @@ export interface OperationMeta {
 export class History {
   constructor(store: EditorStore, options?: HistoryOptions);
   store: EditorStore;
+  defaultActorId: string | null;
+  setDefaultActorId(actorId: string | null): void;
 
   getBlock(id: string): Block | undefined;
   getRun(id: string): Run | undefined;
@@ -384,6 +388,13 @@ export interface DocumentVersion {
   id: string;
   docId: string;
   timestamp: number;
+  /** Whoever made the most recent edit in this version's window -- read from History's defaultActorId, null if never configured. */
+  authorId?: string | null;
+  /** Every distinct actorId that contributed to this version's window. */
+  authorIds?: string[];
+  /** Lightweight auto-generated description (e.g. "3 blocks changed") -- not a full diff. */
+  summary?: string;
+  /** Only ever set by renaming a version yourself -- nothing in this package's automatic capture sets it. */
   label?: string;
   doc: DocumentJSON;
 }
@@ -394,16 +405,21 @@ export function deleteDocumentVersion(id: string): Promise<void>;
 /** All versions saved for docId, newest first. */
 export function listDocumentVersions(docId: string): Promise<DocumentVersion[]>;
 
-/** Periodically snapshots a live document into the versions store; prunes oldest beyond maxVersions for this docId. Restore with applyDocumentTemplate(store, version.doc). */
-export function createPeriodicVersionSnapshotter(options: {
-  store: History | EditorStore;
+/**
+ * Automatic, Google Docs-style version history -- no "name it and save"
+ * step. `store` must be a History instance (needs getHistoryLog()/
+ * subscribeToHistory()). Saves one snapshot after each burst of edits
+ * settles (idleMs of inactivity), attributed to whoever made them.
+ */
+export function createAutoVersionHistory(options: {
+  store: History;
   docId: string;
-  intervalMs?: number;
-  label?: string;
+  /** Inactivity gap that closes a version's window. Default 5 minutes. */
+  idleMs?: number;
   maxVersions?: number;
   onSnapshot?: (version: DocumentVersion) => void;
   onError?: (error: unknown) => void;
-}): { stop: () => void };
+}): { stop: () => void; flush: () => Promise<void> };
 
 export function useDocumentVersions(docId: string | null | undefined): {
   versions: DocumentVersion[];
@@ -411,6 +427,24 @@ export function useDocumentVersions(docId: string | null | undefined): {
   refresh: () => Promise<void>;
 };
 
+/**
+ * Google Docs "show changes"-style HTML diff of `nextDoc` against `prevDoc`
+ * (pass null/undefined for prevDoc to mark everything as newly added) --
+ * word-level insertions/deletions wrapped in `.be-version-diff-added`/
+ * `.be-version-diff-removed` spans. Used internally by `<VersionHistory>`'s
+ * "Changes" tab; exported for building a custom version-history UI.
+ */
+export function diffDocumentsHTML(prevDoc: DocumentJSON | null | undefined, nextDoc: DocumentJSON): string;
+
+export interface VersionHistoryProps {
+  docId: string;
+  idleMs?: number;
+  maxVersions?: number;
+}
+
+/** Self-contained "Version history" button + drawer (list/preview/restore) -- also owns the automatic capture (createAutoVersionHistory) for as long as it's mounted. `store` (from context) must be a History instance. */
+export const VersionHistory: ComponentType<VersionHistoryProps>;
+
 // ---------------------------------------------------------------------------
 // comments/
 // ---------------------------------------------------------------------------
@@ -815,6 +849,8 @@ export interface UseEditorOptions {
   doc?: DocumentJSON;
   /** true (default): store is undo/redo-aware (a History instance). false: a plain EditorStore. */
   history?: boolean;
+  /** Stamped as every edit's actorId (History's defaultActorId) -- used by createAutoVersionHistory/VersionHistory for "who changed this", with no separate identity plumbing needed. Ignored when history: false. */
+  currentUserId?: string | null;
   /** Replaces registerBuiltInBlocks for an opt-in subset of block types. */
   registerBlocks?: (registry: BlockRegistry) => void;
   /** Replaces registerBuiltInInlineTypes for an opt-in subset of inline types. */