@0m0g1/griot 0.1.0

package/README.md

@@ -0,0 +1,179 @@
+# Griot
+
+A self-contained block-based rich text editor and renderer.  
+Built for structured historical document authoring — works standalone or embedded inside a larger app.
+
+---
+
+## Install
+
+```bash
+# Copy src/ into your project, or:
+npm install griot   # (once published)
+```
+
+```js
+import 'griot/css';                         // styles
+import { Editor, Viewer, createDocument } from 'griot';
+```
+
+---
+
+## Quick start
+
+### Editor
+
+```js
+import { Editor, createDocument } from 'griot';
+import 'griot/css';
+
+const doc = createDocument('My Article');
+
+const editor = new Editor(document.querySelector('#editor'), {
+  doc,
+  books: [],                         // optional: parsed books for citations
+  onChange(updatedDoc) {
+    localStorage.setItem('draft', JSON.stringify(updatedDoc));
+  },
+  onEventClick(eventId) {
+    // e.g. AppShell.handleSelectItemById(eventId)
+    console.log('Open timeline event:', eventId);
+  },
+  onCiteClick(blockId) {
+    // scroll viewer to that block
+    viewer.setHighlight(blockId);
+  },
+  onRequestBookPicker(blockId, callback) {
+    // Open your SourcePicker UI, then call:
+    // callback({ bookId, unitId, quote, note })
+  },
+});
+```
+
+### Viewer
+
+```js
+import { Viewer } from 'griot';
+
+const viewer = new Viewer(document.querySelector('#viewer'), {
+  doc,
+  books: [],
+  onEventClick(eventId) {
+    console.log('Open event:', eventId);
+  },
+});
+
+// Jump to a block (e.g. from a timeline citation)
+viewer.setHighlight('b_abc123');
+```
+
+---
+
+## Block types
+
+| Type | Icon | Text field | Notes |
+|---|---|---|---|
+| `paragraph` | ¶ | ✓ | Inline syntax supported |
+| `heading` | H | ✓ | `meta.level` 1–6 |
+| `blockquote` | ❝ | ✓ | Inline syntax supported |
+| `callout` | 💡 | ✓ | `meta.icon` for the emoji |
+| `code` | </> | ✓ | No inline parsing. `meta.language` for highlight |
+| `divider` | — | — | Horizontal rule |
+| `image` | 🖼 | — | `meta.src`, `meta.alt`, `meta.caption` |
+| `timeline_ref` | ⏱ | — | `meta.eventId`, `meta.eventTitle`, `meta.note` |
+| `book_citation` | 📖 | — | `meta.bookId`, `meta.unitId`, `meta.quote`, `meta.note` |
+
+---
+
+## Inline syntax
+
+Works inside any block with `hasInline: true` (paragraph, blockquote, callout, note fields):
+
+```
+**bold**
+*italic*
+`inline code`
+[link text](https://example.com)
+[[event:rome_founding|The Founding of Rome]]   → timeline event chip
+[[cite:b_abc123|See Chapter 2]]                → citation cross-reference
+```
+
+---
+
+## Document format (`.griot.json`)
+
+```json
+{
+  "version": 1,
+  "id": "doc_abc",
+  "title": "The Fall of Rome",
+  "createdAt": "2025-01-01T00:00:00.000Z",
+  "updatedAt": "2025-01-01T00:00:00.000Z",
+  "blocks": [
+    { "id": "b_1", "type": "heading",   "text": "The Fall of Rome",  "meta": { "level": 1 } },
+    { "id": "b_2", "type": "paragraph", "text": "In **476 CE** the last emperor [[event:fall_of_rome|was deposed]].", "meta": {} },
+    { "id": "b_3", "type": "book_citation", "text": null, "meta": {
+        "bookId": "book_xyz", "unitId": "unit_abc",
+        "quote": "The barbarians had long served in Roman armies.",
+        "note": "Essential context for understanding the transition."
+    }}
+  ]
+}
+```
+
+---
+
+## Deep-link anchors
+
+Every rendered block gets `id="griot-{blockId}"` in the DOM.
+
+```js
+import { anchorId, scrollToBlock } from 'griot';
+
+// Get the DOM id for a block
+anchorId('b_abc123')          // → "griot-b_abc123"
+
+// Scroll to a block (viewer or editor)
+scrollToBlock('b_abc123');
+scrollToBlock('b_abc123', 'instant');
+```
+
+This is the contract for timeline → article navigation:  
+store `{ docId, blockId }` on a citation, then call `scrollToBlock(blockId)` when the timeline jumps to it.
+
+---
+
+## API reference
+
+### `Editor`
+| Method | Description |
+|---|---|
+| `new Editor(el, options)` | Mount editor into `el` |
+| `editor.doc` | Current document (read-only) |
+| `editor.setDoc(doc)` | Replace document |
+| `editor.setBooks(books)` | Update available books |
+| `editor.focus(blockId)` | Focus a specific block |
+| `editor.destroy()` | Unmount and clean up |
+
+### `Viewer`
+| Method | Description |
+|---|---|
+| `new Viewer(el, options)` | Mount viewer into `el` |
+| `viewer.setDoc(doc)` | Replace document |
+| `viewer.setBooks(books)` | Update available books |
+| `viewer.setHighlight(blockId)` | Scroll to + briefly highlight a block |
+| `viewer.destroy()` | Unmount and clean up |
+
+### Document helpers
+```js
+createDocument(title)
+createBlock(type, overrides)
+updateBlock(doc, blockId, patch)
+insertBlockAfter(doc, blockId, newBlock)
+removeBlock(doc, blockId)
+splitBlock(doc, blockId, offset)         // returns [newDoc, newBlockId]
+mergeBlockWithPrev(doc, blockId)         // returns [newDoc, prevId, offset]
+moveBlock(doc, fromIndex, toIndex)
+toJSON(doc)
+fromJSON(jsonStringOrObject)
+```

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@0m0g1/griot",
+  "version": "0.1.0",
+  "description": "A self-contained block-based rich text editor and renderer built for historical document authoring.",
+  "type": "module",
+  "main": "./src/Griot.js",
+  "module": "./src/Griot.js",
+  "exports": {
+    ".": "./src/Griot.js",
+    "./css": "./src/griot.css"
+  },
+  "files": [
+    "src/"
+  ],
+  "keywords": ["rich-text", "editor", "blocks", "history", "document"],
+  "license": "MIT"
+}

package/src/Griot.js

@@ -0,0 +1,54 @@
+// ─── Griot.js ─────────────────────────────────────────────────────────────────
+// Public facade. Import from here — never from internal modules directly.
+//
+// Named exports cover every public surface:
+//
+//   Classes
+//     Editor, Viewer
+//
+//   Document model
+//     createDocument, createBlock, cloneBlock
+//     updateBlock, insertBlockAfter, insertBlockBefore,
+//     removeBlock, splitBlock, mergeBlockWithPrev, moveBlock,
+//     getBlock, getBlockIndex, toJSON, fromJSON
+//
+//   Block helpers
+//     anchorId, scrollToBlock, isTextBlock
+//
+//   Inline
+//     tokenizeInline, renderInlineToDOM, renderInlineToHTML, TOKEN
+//
+//   Schema
+//     getBlockDef, getAllTypes, defaultMeta, BlockSchema
+// ─────────────────────────────────────────────────────────────────────────────
+
+// Core
+export {
+  createBlock, cloneBlock, isTextBlock, isValidBlock,
+  anchorId, scrollToBlock,
+  TEXT_TYPES, ALL_TYPES,
+} from './core/Block.js';
+
+export {
+  createDocument, toJSON, fromJSON,
+  getBlock, getBlockIndex, getBlockAfter, getBlockBefore,
+  updateBlock, insertBlockAfter, insertBlockBefore,
+  removeBlock, moveBlock, splitBlock, mergeBlockWithPrev,
+} from './core/Document.js';
+
+export { History } from './core/History.js';
+
+// Inline
+export { tokenizeInline, TOKEN } from './inline/InlineLexer.js';
+export {
+  renderInlineToDOM, renderInlineToHTML, escHtml, escAttr,
+} from './inline/InlineRenderer.js';
+
+// Blocks
+export { getBlockDef, getAllTypes, defaultMeta }    from './blocks/BlockSchema.js';
+export { default as BlockSchema }                  from './blocks/BlockSchema.js';
+export { renderBlock }                             from './blocks/BlockRenderer.js';
+
+// Editor / Viewer
+export { Editor }  from './editor/Editor.js';
+export { Viewer }  from './viewer/Viewer.js';

package/src/blocks/BlockRenderer.js

@@ -0,0 +1,201 @@
+// ─── BlockRenderer.js ─────────────────────────────────────────────────────────
+// Renders a single block to a DOM element.
+// Used by both Viewer (read-only) and Editor (preview layer).
+//
+// Options:
+//   books         — array of parsed book objects (for book_citation)
+//   onEventClick  — (eventId) => void
+//   onCiteClick   — (blockId) => void
+//   editable      — if true, skips event listeners (Editor manages them)
+// ─────────────────────────────────────────────────────────────────────────────
+
+import { anchorId }                             from '../core/Block.js';
+import { renderInlineToDOM, renderInlineToHTML, escHtml, escAttr } from '../inline/InlineRenderer.js';
+import { getBlockDef }                          from './BlockSchema.js';
+
+// ─── Public entry point ───────────────────────────────────────────────────────
+export function renderBlock(block, { books = [], onEventClick, onCiteClick } = {}) {
+  const el = _render(block, { books, onEventClick, onCiteClick });
+  if (el) {
+    el.id = anchorId(block.id);
+    el.dataset.blockId = block.id;
+    el.dataset.blockType = block.type;
+  }
+  return el;
+}
+
+// ─── Internal ─────────────────────────────────────────────────────────────────
+function inlineDOM(text, opts) {
+  return renderInlineToDOM(text, {
+    onEventClick: opts.onEventClick,
+    onCiteClick:  opts.onCiteClick,
+  });
+}
+
+function _render(block, opts) {
+  const { text, meta = {}, type } = block;
+
+  switch (type) {
+
+    case 'paragraph': {
+      const el = document.createElement('p');
+      el.className = 'griot-block griot-paragraph';
+      if (text) el.appendChild(inlineDOM(text, opts));
+      return el;
+    }
+
+    case 'heading': {
+      const level = Math.max(1, Math.min(6, meta.level ?? 2));
+      const el = document.createElement(`h${level}`);
+      el.className = `griot-block griot-heading griot-heading--${level}`;
+      el.textContent = text ?? '';
+      return el;
+    }
+
+    case 'blockquote': {
+      const el = document.createElement('blockquote');
+      el.className = 'griot-block griot-blockquote';
+      if (text) el.appendChild(inlineDOM(text, opts));
+      return el;
+    }
+
+    case 'callout': {
+      const el    = document.createElement('div');
+      const icon  = document.createElement('span');
+      const body  = document.createElement('div');
+      el.className   = 'griot-block griot-callout';
+      icon.className = 'griot-callout__icon';
+      body.className = 'griot-callout__body';
+      icon.textContent = meta.icon ?? '💡';
+      if (text) body.appendChild(inlineDOM(text, opts));
+      el.appendChild(icon);
+      el.appendChild(body);
+      return el;
+    }
+
+    case 'code': {
+      const pre  = document.createElement('pre');
+      const code = document.createElement('code');
+      pre.className  = 'griot-block griot-code';
+      if (meta.language) code.className = `language-${meta.language}`;
+      code.textContent = text ?? '';
+      pre.appendChild(code);
+      return pre;
+    }
+
+    case 'divider': {
+      const el = document.createElement('hr');
+      el.className = 'griot-block griot-divider';
+      return el;
+    }
+
+    case 'image': {
+      const figure  = document.createElement('figure');
+      const img     = document.createElement('img');
+      figure.className = 'griot-block griot-image';
+      img.src = meta.src ?? '';
+      img.alt = meta.alt ?? '';
+      figure.appendChild(img);
+      if (meta.caption) {
+        const cap = document.createElement('figcaption');
+        cap.textContent = meta.caption;
+        figure.appendChild(cap);
+      }
+      return figure;
+    }
+
+    case 'timeline_ref': {
+      const el = document.createElement('div');
+      el.className = 'griot-block griot-timeline-ref';
+      if (meta.eventId && opts.onEventClick) {
+        el.setAttribute('role', 'button');
+        el.tabIndex = 0;
+        el.addEventListener('click', () => opts.onEventClick(meta.eventId));
+        el.addEventListener('keydown', (e) => {
+          if (e.key === 'Enter' || e.key === ' ') opts.onEventClick(meta.eventId);
+        });
+      }
+      el.innerHTML = `
+        <span class="griot-timeline-ref__icon">⏱</span>
+        <div class="griot-timeline-ref__body">
+          <div class="griot-timeline-ref__title">${escHtml(meta.eventTitle || 'Timeline Event')}</div>
+          ${meta.note ? `<div class="griot-timeline-ref__note">${escHtml(meta.note)}</div>` : ''}
+        </div>
+        ${meta.eventId ? '<span class="griot-timeline-ref__arrow">→</span>' : ''}
+      `;
+      return el;
+    }
+
+    case 'book_citation': {
+      return _renderCitation(block, opts);
+    }
+
+    default: {
+      const el = document.createElement('p');
+      el.className = 'griot-block griot-paragraph';
+      el.textContent = text ?? '';
+      return el;
+    }
+  }
+}
+
+function _renderCitation(block, opts) {
+  const { meta = {} } = block;
+  const wrap = document.createElement('figure');
+  wrap.className = 'griot-block griot-citation';
+
+  if (!meta.bookId) {
+    wrap.innerHTML = `<div class="griot-citation__empty">📖 No source selected yet</div>`;
+    return wrap;
+  }
+
+  const book = (opts.books ?? []).find(b => b.id === meta.bookId);
+  const unit = book?.units?.find(u => u.id === meta.unitId);
+
+  if (!book || !unit) {
+    wrap.innerHTML = `<div class="griot-citation__missing">📖 Source not found — book may have been removed</div>`;
+    return wrap;
+  }
+
+  const inner = document.createElement('div');
+  inner.className = 'griot-citation__inner';
+
+  // Header
+  const hdr = document.createElement('div');
+  hdr.className = 'griot-citation__header';
+  hdr.innerHTML = `
+    <span class="griot-citation__book-icon">📖</span>
+    <span class="griot-citation__book-title">${escHtml(book.title)}</span>
+    ${book.author ? `<span class="griot-citation__author">${escHtml(book.author)}</span>` : ''}
+    <span class="griot-citation__unit">${escHtml(unit.label)}</span>
+  `;
+  inner.appendChild(hdr);
+
+  // Quote
+  if (meta.quote) {
+    const q = document.createElement('blockquote');
+    q.className = 'griot-citation__quote';
+    q.textContent = meta.quote;
+    inner.appendChild(q);
+  }
+
+  // Note (supports inline syntax)
+  if (meta.note) {
+    const note = document.createElement('div');
+    note.className = 'griot-citation__note';
+    note.appendChild(inlineDOM(meta.note, opts));
+    inner.appendChild(note);
+  }
+
+  wrap.appendChild(inner);
+
+  // Content preview
+  if (unit.content) {
+    const preview = document.createElement('div');
+    preview.className = 'griot-citation__preview';
+    preview.textContent = unit.content.slice(0, 180) + (unit.content.length > 180 ? '…' : '');
+    wrap.appendChild(preview);
+  }
+
+  return wrap;
+}

package/src/blocks/BlockSchema.js

@@ -0,0 +1,94 @@
+// ─── BlockSchema.js ───────────────────────────────────────────────────────────
+// The single source of truth for what block types exist, their labels,
+// icons, whether they have text, and any default meta values.
+// ─────────────────────────────────────────────────────────────────────────────
+
+const SCHEMA = {
+  paragraph: {
+    label:     'Paragraph',
+    icon:      '¶',
+    hasText:   true,
+    hasInline: true,
+    defaultMeta: {},
+    placeholder: 'Write something… **bold** *italic* `code` [[event:id|label]]',
+  },
+  heading: {
+    label:     'Heading',
+    icon:      'H',
+    hasText:   true,
+    hasInline: false, // headings render as plain text, no inline chips
+    defaultMeta: { level: 2 },
+    placeholder: 'Heading…',
+  },
+  blockquote: {
+    label:     'Quote',
+    icon:      '❝',
+    hasText:   true,
+    hasInline: true,
+    defaultMeta: {},
+    placeholder: 'Quote…',
+  },
+  callout: {
+    label:     'Callout',
+    icon:      '💡',
+    hasText:   true,
+    hasInline: true,
+    defaultMeta: { icon: '💡' },
+    placeholder: 'Callout text…',
+  },
+  code: {
+    label:     'Code',
+    icon:      '</>',
+    hasText:   true,
+    hasInline: false, // code blocks are raw, no inline parsing
+    defaultMeta: { language: '' },
+    placeholder: '// code…',
+  },
+  divider: {
+    label:     'Divider',
+    icon:      '—',
+    hasText:   false,
+    hasInline: false,
+    defaultMeta: {},
+    placeholder: null,
+  },
+  image: {
+    label:     'Image',
+    icon:      '🖼',
+    hasText:   false,
+    hasInline: false,
+    defaultMeta: { src: '', alt: '', caption: '' },
+    placeholder: null,
+  },
+  timeline_ref: {
+    label:     'Timeline Event',
+    icon:      '⏱',
+    hasText:   false,
+    hasInline: false,
+    defaultMeta: { eventId: '', eventTitle: '', note: '' },
+    placeholder: null,
+  },
+  book_citation: {
+    label:     'Book Citation',
+    icon:      '📖',
+    hasText:   false,
+    hasInline: false,
+    defaultMeta: { bookId: '', unitId: '', quote: '', note: '' },
+    placeholder: null,
+  },
+};
+
+export function getBlockDef(type) {
+  return SCHEMA[type] ?? SCHEMA.paragraph;
+}
+
+export function getAllTypes() {
+  return Object.keys(SCHEMA);
+}
+
+// Returns default meta for a type (shallow copy)
+export function defaultMeta(type) {
+  return { ...(SCHEMA[type]?.defaultMeta ?? {}) };
+}
+
+export default SCHEMA;

package/src/core/Block.js

@@ -0,0 +1,63 @@
+// ─── 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
+// ─────────────────────────────────────────────────────────────────────────────
+
+let _seq = 0;
+const uid = (prefix = 'b') => `${prefix}_${Date.now()}_${(++_seq).toString(36)}`;
+
+// TEXT_TYPES — block types that carry a user-editable `text` field
+export const TEXT_TYPES = new Set([
+  'paragraph', 'heading', 'blockquote', 'callout', 'code',
+]);
+
+// ALL_TYPES — exhaustive list for validation
+export const ALL_TYPES = new Set([
+  'paragraph', 'heading', 'blockquote', 'callout', 'code',
+  'divider', 'image', 'timeline_ref', 'book_citation',
+]);
+
+// ─── Factory ──────────────────────────────────────────────────────────────────
+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'),
+    type,
+    text: TEXT_TYPES.has(type) ? '' : null,
+    meta: {},
+    ...overrides,
+  };
+}
+
+export function cloneBlock(block) {
+  return {
+    ...block,
+    id:   uid('b'),
+    meta: { ...block.meta },
+  };
+}
+
+// ─── Predicates ───────────────────────────────────────────────────────────────
+export const isTextBlock  = (b) => TEXT_TYPES.has(b?.type);
+export const isValidBlock = (b) => b && typeof b.id === 'string' && ALL_TYPES.has(b.type);
+
+// ─── 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' });
+};