@0m0g1/griot 0.1.2 → 0.1.4

package/src/core/Block.js

@@ -1,63 +1,60 @@
 // ─── Block.js ─────────────────────────────────────────────────────────────────
-// Pure data. No DOM, no rendering. A block is a plain serialisable object.
-//
-// Shape:
-//   { id, type, text?, meta:{} }
-//
-// meta holds type-specific fields:
-//   heading  → meta.level (1-6)
-//   callout  → meta.icon
-//   code     → meta.language
-//   image    → meta.src, meta.alt, meta.caption
-//   divider  → (no extra fields)
-//   timeline_ref  → meta.eventId, meta.eventTitle
-//   book_citation → meta.bookId, meta.unitId, meta.quote, meta.note
+// Pure block primitives. No schema dependency, no document awareness.
 // ─────────────────────────────────────────────────────────────────────────────
 
 let _seq = 0;
-const uid = (prefix = 'b') => `${prefix}_${Date.now()}_${(++_seq).toString(36)}`;
+const uid = () => `b_${Date.now().toString(36)}_${(++_seq).toString(36)}`;
 
-// TEXT_TYPES — block types that carry a user-editable `text` field
+/** Block types that carry a text field (editable as plain text). */
 export const TEXT_TYPES = new Set([
-  'paragraph', 'heading', 'blockquote', 'callout', 'code',
+  'paragraph', 'heading', 'blockquote',
+  'callout', 'callout_warning', 'callout_tip', 'callout_danger',
+  'code', 'list_ul', 'list_ol',
 ]);
 
-// ALL_TYPES — exhaustive list for validation
-export const ALL_TYPES = new Set([
-  'paragraph', 'heading', 'blockquote', 'callout', 'code',
-  'divider', 'image', 'timeline_ref', 'book_citation',
-]);
+/** All known block types (informational; canonical list is BlockSchema). */
+export const ALL_TYPES = [
+  'paragraph', 'heading', 'blockquote',
+  'callout', 'callout_warning', 'callout_tip', 'callout_danger',
+  'code', 'list_ul', 'list_ol', 'table',
+  'divider', 'image', 'video', 'timeline_ref', 'book_citation',
+];
 
-// ─── Factory ──────────────────────────────────────────────────────────────────
+/**
+ * Create a new block with a fresh unique id.
+ * @param {string} type
+ * @param {{ id?, text?, meta? }} [overrides]
+ */
 export function createBlock(type = 'paragraph', overrides = {}) {
-  if (!ALL_TYPES.has(type)) {
-    console.warn(`[Griot] Unknown block type "${type}", defaulting to paragraph`);
-    type = 'paragraph';
-  }
   return {
-    id:   uid('b'),
+    id:   overrides.id   ?? uid(),
     type,
-    text: TEXT_TYPES.has(type) ? '' : null,
-    meta: {},
-    ...overrides,
+    text: TEXT_TYPES.has(type) ? (overrides.text ?? '') : null,
+    meta: overrides.meta ?? {},
   };
 }
 
-export function cloneBlock(block) {
-  return {
-    ...block,
-    id:   uid('b'),
-    meta: { ...block.meta },
-  };
+/** Deep-clone a block. Pass newId=false to keep the same id. */
+export function cloneBlock(block, newId = true) {
+  return { ...block, id: newId ? uid() : block.id, meta: { ...block.meta } };
+}
+
+/** True if this block type stores a text string. */
+export function isTextBlock(block) {
+  return TEXT_TYPES.has(block?.type);
+}
+
+/** Minimal structural validity check. */
+export function isValidBlock(block) {
+  return Boolean(block && typeof block.id === 'string' && typeof block.type === 'string');
 }
 
-// ─── Predicates ───────────────────────────────────────────────────────────────
-export const isTextBlock  = (b) => TEXT_TYPES.has(b?.type);
-export const isValidBlock = (b) => b && typeof b.id === 'string' && ALL_TYPES.has(b.type);
+/** DOM id attribute used to anchor/locate a block element. */
+export function anchorId(blockId) {
+  return `griot-block-${blockId}`;
+}
 
-// ─── Anchor ID (stable DOM id for deep-linking) ───────────────────────────────
-export const anchorId     = (blockId) => `griot-${blockId}`;
-export const scrollToBlock = (blockId, behavior = 'smooth') => {
-  document.getElementById(anchorId(blockId))
-    ?.scrollIntoView({ behavior, block: 'center' });
-};
+/** Smooth-scroll (or jump) to a block's DOM element. */
+export function scrollToBlock(blockId, behavior = 'smooth') {
+  document.getElementById(anchorId(blockId))?.scrollIntoView({ behavior, block: 'center' });
+}

package/src/core/Document.js

@@ -1,128 +1,93 @@
 // ─── Document.js ──────────────────────────────────────────────────────────────
-// An ordered list of blocks with CRUD operations.
-// All mutating methods return a NEW document (immutable updates) so History
-// can cheaply snapshot the state.
+// Immutable document operations. Every function returns a NEW document object.
+// Document shape: { id: string, blocks: Block[] }
 // ─────────────────────────────────────────────────────────────────────────────
 
-import { createBlock, cloneBlock, isValidBlock } from './Block.js';
+import { createBlock } from './Block.js';
 
 let _docSeq = 0;
-const docUid = () => `doc_${Date.now()}_${(++_docSeq).toString(36)}`;
-
-// ─── Factory ──────────────────────────────────────────────────────────────────
-export function createDocument(title = 'Untitled', blocks = null) {
-  return {
-    id:        docUid(),
-    version:   1,
-    title,
-    createdAt: new Date().toISOString(),
-    updatedAt: new Date().toISOString(),
-    blocks:    blocks ?? [createBlock('heading', { text: title, meta: { level: 1 } })],
-  };
-}
+const docUid   = () => `doc_${Date.now().toString(36)}_${++_docSeq}`;
+const withBlks = (doc, blocks) => ({ ...doc, blocks });
 
-// ─── Helpers ──────────────────────────────────────────────────────────────────
-function touch(doc) {
-  return { ...doc, updatedAt: new Date().toISOString() };
-}
+// ── Constructors ──────────────────────────────────────────────────────────────
 
-function withBlocks(doc, blocks) {
-  return touch({ ...doc, blocks });
+export function createDocument(blocks = []) {
+  return { id: docUid(), blocks: blocks.length ? blocks : [createBlock('paragraph')] };
 }
 
-// ─── Reads ────────────────────────────────────────────────────────────────────
-export function getBlock(doc, blockId) {
-  return doc.blocks.find(b => b.id === blockId) ?? null;
-}
+export const toJSON   = (doc) => JSON.stringify(doc);
+export const fromJSON = (j)   => (typeof j === 'string' ? JSON.parse(j) : j);
 
-export function getBlockIndex(doc, blockId) {
-  return doc.blocks.findIndex(b => b.id === blockId);
-}
+// ── Queries ───────────────────────────────────────────────────────────────────
 
-export function getBlockAfter(doc, blockId) {
-  const i = getBlockIndex(doc, blockId);
-  return i >= 0 && i < doc.blocks.length - 1 ? doc.blocks[i + 1] : null;
-}
+export const getBlock       = (doc, id) => doc.blocks.find(b => b.id === id) ?? null;
+export const getBlockIndex  = (doc, id) => doc.blocks.findIndex(b => b.id === id);
+export const getBlockBefore = (doc, id) => { const i = getBlockIndex(doc, id); return i > 0 ? doc.blocks[i - 1] : null; };
+export const getBlockAfter  = (doc, id) => { const i = getBlockIndex(doc, id); return (i >= 0 && i < doc.blocks.length - 1) ? doc.blocks[i + 1] : null; };
 
-export function getBlockBefore(doc, blockId) {
-  const i = getBlockIndex(doc, blockId);
-  return i > 0 ? doc.blocks[i - 1] : null;
-}
+// ── Mutations (always return a new doc) ───────────────────────────────────────
 
-// ─── Writes ───────────────────────────────────────────────────────────────────
-export function updateBlock(doc, blockId, patch) {
-  return withBlocks(doc, doc.blocks.map(b =>
-    b.id === blockId ? { ...b, ...patch, meta: { ...b.meta, ...(patch.meta ?? {}) } } : b
-  ));
+export function updateBlock(doc, id, patch) {
+  return withBlks(doc, doc.blocks.map(b => {
+    if (b.id !== id) return b;
+    const u = { ...b };
+    if ('text' in patch) u.text = patch.text;
+    if ('type' in patch) u.type = patch.type;
+    if ('meta' in patch) u.meta = { ...b.meta, ...patch.meta };
+    return u;
+  }));
 }
 
-export function insertBlockAfter(doc, blockId, newBlock) {
-  const i = getBlockIndex(doc, blockId);
-  if (i < 0) return withBlocks(doc, [...doc.blocks, newBlock]);
-  const next = [...doc.blocks];
-  next.splice(i + 1, 0, newBlock);
-  return withBlocks(doc, next);
+export function insertBlockAfter(doc, afterId, newBlock) {
+  const i = getBlockIndex(doc, afterId);
+  const blocks = [...doc.blocks];
+  blocks.splice(i < 0 ? blocks.length : i + 1, 0, newBlock);
+  return withBlks(doc, blocks);
 }
 
-export function insertBlockBefore(doc, blockId, newBlock) {
-  const i = getBlockIndex(doc, blockId);
-  if (i < 0) return withBlocks(doc, [newBlock, ...doc.blocks]);
-  const next = [...doc.blocks];
-  next.splice(i, 0, newBlock);
-  return withBlocks(doc, next);
+export function insertBlockBefore(doc, beforeId, newBlock) {
+  const i = getBlockIndex(doc, beforeId);
+  const blocks = [...doc.blocks];
+  blocks.splice(i < 0 ? 0 : i, 0, newBlock);
+  return withBlks(doc, blocks);
 }
 
-export function removeBlock(doc, blockId) {
-  if (doc.blocks.length <= 1) return doc; // never empty
-  return withBlocks(doc, doc.blocks.filter(b => b.id !== blockId));
+export function removeBlock(doc, id) {
+  return withBlks(doc, doc.blocks.filter(b => b.id !== id));
 }
 
-export function moveBlock(doc, fromIndex, toIndex) {
-  if (fromIndex === toIndex) return doc;
-  const next = [...doc.blocks];
-  const [moved] = next.splice(fromIndex, 1);
-  next.splice(toIndex, 0, moved);
-  return withBlocks(doc, next);
+export function moveBlock(doc, fromIdx, toIdx) {
+  const blocks = [...doc.blocks];
+  const [item] = blocks.splice(fromIdx, 1);
+  blocks.splice(toIdx, 0, item);
+  return withBlks(doc, blocks);
 }
 
-// Split a text block at a cursor offset — returns [docWithSplit, newBlockId]
+/**
+ * Split a text block at `offset`.
+ * Headings split into a paragraph for the new block.
+ * @returns {[newDoc, newBlockId | null]}
+ */
 export function splitBlock(doc, blockId, offset) {
   const block = getBlock(doc, blockId);
   if (!block || block.text === null) return [doc, null];
 
-  const before = block.text.slice(0, offset);
-  const after  = block.text.slice(offset);
-
-  const newBlock = createBlock('paragraph', { text: after });
-  const updated  = updateBlock(doc, blockId, { text: before });
-  const final    = insertBlockAfter(updated, blockId, newBlock);
-
-  return [final, newBlock.id];
+  const before  = block.text.slice(0, offset);
+  const after   = block.text.slice(offset);
+  const newType = block.type === 'heading' ? 'paragraph' : block.type;
+  const nb      = createBlock(newType, { text: after, meta: { ...block.meta } });
+  return [insertBlockAfter(updateBlock(doc, blockId, { text: before }), blockId, nb), nb.id];
 }
 
-// Merge block into the one before it — returns [docWithMerge, prevBlockId, mergeOffset]
+/**
+ * Merge a block into the previous one.
+ * @returns {[newDoc, prevBlockId | null, mergeOffset]}
+ */
 export function mergeBlockWithPrev(doc, blockId) {
-  const prev = getBlockBefore(doc, blockId);
-  const curr = getBlock(doc, blockId);
-  if (!prev || !curr) return [doc, null, 0];
-  if (prev.text === null || curr.text === null) return [doc, null, 0];
-
-  const mergeOffset = prev.text.length;
-  const merged      = updateBlock(doc, prev.id, { text: prev.text + curr.text });
-  const removed     = removeBlock(merged, blockId);
-
-  return [removed, prev.id, mergeOffset];
-}
-
-// ─── Serialise / deserialise ──────────────────────────────────────────────────
-export function toJSON(doc) {
-  return JSON.stringify(doc, null, 2);
-}
-
-export function fromJSON(json) {
-  const data = typeof json === 'string' ? JSON.parse(json) : json;
-  if (!data?.blocks || !Array.isArray(data.blocks)) {
-    throw new Error('[Griot] fromJSON: invalid document — missing blocks array');
-  }
-  return data;
-}
+  const block = getBlock(doc, blockId);
+  const prev  = getBlockBefore(doc, blockId);
+  if (!prev || prev.text === null || block?.text === null) return [doc, null, 0];
+  const offset = prev.text.length;
+  const merged = updateBlock(doc, prev.id, { text: prev.text + (block.text ?? '') });
+  return [removeBlock(merged, blockId), prev.id, offset];
+}

package/src/core/History.js

@@ -1,58 +1,33 @@
 // ─── History.js ───────────────────────────────────────────────────────────────
-// Linear undo/redo stack.
-// Works with immutable document snapshots — just push the whole doc each time.
+// Linear undo/redo stack. Stores immutable document snapshots.
 // ─────────────────────────────────────────────────────────────────────────────
 
+const MAX_HISTORY = 200;
+
 export class History {
-  constructor(initialDoc, { maxDepth = 100 } = {}) {
-    this._stack    = [initialDoc];
-    this._cursor   = 0;
-    this._maxDepth = maxDepth;
+  constructor(initialDoc) {
+    this._stack  = initialDoc ? [initialDoc] : [];
+    this._cursor = this._stack.length - 1;
   }
 
-  // Current document
-  get current() { return this._stack[this._cursor]; }
-
-  get canUndo() { return this._cursor > 0; }
-  get canRedo() { return this._cursor < this._stack.length - 1; }
+  get current() { return this._stack[this._cursor] ?? null; }
+  canUndo()     { return this._cursor > 0; }
+  canRedo()     { return this._cursor < this._stack.length - 1; }
 
-  // Push a new state (truncates any redo branch)
+  /** Push a new snapshot, discarding any redo future. */
   push(doc) {
-    // Truncate future if we're not at the top
     this._stack = this._stack.slice(0, this._cursor + 1);
     this._stack.push(doc);
-
-    // Enforce max depth
-    if (this._stack.length > this._maxDepth) {
-      this._stack = this._stack.slice(this._stack.length - this._maxDepth);
-    }
-
+    if (this._stack.length > MAX_HISTORY) this._stack.shift();
     this._cursor = this._stack.length - 1;
-    return this;
   }
 
-  undo() {
-    if (!this.canUndo) return this.current;
-    this._cursor--;
-    return this.current;
-  }
-
-  redo() {
-    if (!this.canRedo) return this.current;
-    this._cursor++;
-    return this.current;
-  }
-
-  // Replace current snapshot without branching (for transient changes
-  // like typing individual characters — debounce the push externally)
+  /** Replace the current snapshot in-place (no new undo point). */
   replace(doc) {
-    this._stack[this._cursor] = doc;
-    return this;
+    if (this._cursor >= 0) this._stack[this._cursor] = doc;
+    else this.push(doc);
   }
 
-  clear(doc) {
-    this._stack  = [doc];
-    this._cursor = 0;
-    return this;
-  }
-}
+  undo() { if (this.canUndo()) this._cursor--; return this.current; }
+  redo() { if (this.canRedo()) this._cursor++; return this.current; }
+}