@signal9/era-ui 3.10.0 → 3.12.0

package/dist/apps/notes/tree.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Notes tree index — a hierarchical table of contents built by walking a
+ * TipTap document's heading structure.
+ *
+ * This is the retrieval half of the app. Instead of embedding notes and
+ * hoping vector similarity lands on the right paragraph, a model is handed
+ * `treeToText(tree)` as a table of contents and reasons about which section to
+ * open — then `extractSection()` returns just that slice, structure intact
+ * (PageIndex-style reasoning-based retrieval).
+ *
+ * Nothing here touches the editor or the DOM: it operates on stored documents,
+ * so it is equally usable from a tool handler, a worker, or a build step.
+ */
+import type { TiptapDocument, TiptapNode } from './types.js';
+export interface NoteTreeNode {
+    title: string;
+    noteId?: string;
+    headingId?: string;
+    /** 0=root, 1=note, 2=H1, 3=H2, 4=H3 — heading level shifted by the note row. */
+    level: number;
+    /** Words in this section's own content, not its children's. */
+    wordCount: number;
+    children: NoteTreeNode[];
+}
+export interface SectionResult {
+    /** `Note Title > H2 > H3` */
+    headingPath: string;
+    /** Markdown for this section — structure-preserving, not flattened text. */
+    content: string;
+    wordCount: number;
+}
+export interface SectionNodes {
+    headingPath: string;
+    nodes: TiptapNode[];
+}
+/** Build a tree for one note's document. */
+export declare function buildNoteTree(noteId: string, title: string, doc: TiptapDocument): NoteTreeNode;
+/** Combine every note into one index tree. */
+export declare function buildGlobalTree(notes: Array<{
+    id: string;
+    title: string;
+    content: TiptapDocument;
+}>): NoteTreeNode;
+/** Node count below (and including) this node. */
+export declare function countNodes(node: NoteTreeNode): number;
+/** Total words in this subtree. */
+export declare function totalWords(node: NoteTreeNode): number;
+/**
+ * Render the tree as YAML-shaped key/value text for a model to read.
+ *
+ * YAML-style indented pairs beat JSON on nested data in the 2025 retrieval
+ * benchmarks, and the labelled fields (`id`, `hid`) are copy-pasteable straight
+ * back into a `get(id)` / `extractSection(noteId, headingId)` call, which is
+ * the whole point of handing over a TOC.
+ */
+export declare function treeToText(tree: NoteTreeNode): string;
+/**
+ * The raw nodes of one section: everything between the target heading and the
+ * next heading of the same or a higher level, plus the breadcrumb that led to
+ * it. Callers pick their own serialisation.
+ */
+export declare function extractSectionNodes(noteTitle: string, doc: TiptapDocument, targetHeadingId: string): SectionNodes | null;
+/**
+ * One section, serialised to markdown.
+ *
+ * Markdown rather than flattened text on purpose: plain-text extraction garbles
+ * lists, tables, and code blocks, which is exactly the structure a model needs
+ * to answer from a retrieved section.
+ */
+export declare function extractSection(noteTitle: string, doc: TiptapDocument, targetHeadingId: string): SectionResult | null;

package/dist/apps/notes/tree.js

@@ -0,0 +1,185 @@
+/**
+ * Notes tree index — a hierarchical table of contents built by walking a
+ * TipTap document's heading structure.
+ *
+ * This is the retrieval half of the app. Instead of embedding notes and
+ * hoping vector similarity lands on the right paragraph, a model is handed
+ * `treeToText(tree)` as a table of contents and reasons about which section to
+ * open — then `extractSection()` returns just that slice, structure intact
+ * (PageIndex-style reasoning-based retrieval).
+ *
+ * Nothing here touches the editor or the DOM: it operates on stored documents,
+ * so it is equally usable from a tool handler, a worker, or a build step.
+ */
+import { textContent, tiptapToMarkdown } from './markdown.js';
+function countWords(text) {
+    return text.trim().split(/\s+/).filter(Boolean).length;
+}
+/** Build a tree for one note's document. */
+export function buildNoteTree(noteId, title, doc) {
+    const root = { title, noteId, level: 1, wordCount: 0, children: [] };
+    if (!doc.content || doc.content.length === 0)
+        return root;
+    const stack = [root];
+    let currentText = '';
+    for (const node of doc.content) {
+        if (node.type === 'heading' && node.attrs?.level) {
+            // Text seen since the last heading belongs to the section we're leaving.
+            if (currentText.trim()) {
+                stack[stack.length - 1].wordCount += countWords(currentText);
+                currentText = '';
+            }
+            const headingLevel = node.attrs.level;
+            const treeLevel = headingLevel + 1; // note=1, H1=2, H2=3, H3=4
+            const headingNode = {
+                title: textContent(node),
+                headingId: node.attrs?.id ?? undefined,
+                level: treeLevel,
+                wordCount: 0,
+                children: []
+            };
+            // The parent is the deepest node still shallower than this heading.
+            while (stack.length > 1 && stack[stack.length - 1].level >= treeLevel) {
+                stack.pop();
+            }
+            stack[stack.length - 1].children.push(headingNode);
+            stack.push(headingNode);
+        }
+        else {
+            currentText += textContent(node) + ' ';
+        }
+    }
+    if (currentText.trim()) {
+        stack[stack.length - 1].wordCount += countWords(currentText);
+    }
+    // A note with no headings at all is one flat section.
+    if (root.children.length === 0 && root.wordCount === 0) {
+        root.wordCount = countWords(doc.content.map(textContent).join(' '));
+    }
+    return root;
+}
+/** Combine every note into one index tree. */
+export function buildGlobalTree(notes) {
+    return {
+        title: 'Notes Index',
+        level: 0,
+        wordCount: 0,
+        children: notes.map((n) => buildNoteTree(n.id, n.title, n.content))
+    };
+}
+/** Node count below (and including) this node. */
+export function countNodes(node) {
+    return 1 + node.children.reduce((sum, c) => sum + countNodes(c), 0);
+}
+/** Total words in this subtree. */
+export function totalWords(node) {
+    return node.wordCount + node.children.reduce((sum, c) => sum + totalWords(c), 0);
+}
+/**
+ * Render the tree as YAML-shaped key/value text for a model to read.
+ *
+ * YAML-style indented pairs beat JSON on nested data in the 2025 retrieval
+ * benchmarks, and the labelled fields (`id`, `hid`) are copy-pasteable straight
+ * back into a `get(id)` / `extractSection(noteId, headingId)` call, which is
+ * the whole point of handing over a TOC.
+ */
+export function treeToText(tree) {
+    if (tree.children.length === 0)
+        return '(no notes)';
+    const blocks = [];
+    for (const note of tree.children) {
+        const noteWords = totalWords(note);
+        const lines = [
+            `- title: ${note.title || 'Untitled'}`,
+            `  id: ${note.noteId ?? '?'}`,
+            `  words: ${noteWords}`
+        ];
+        if (note.children.length > 0) {
+            lines.push('  sections:');
+            renderSections(note.children, lines, 2);
+        }
+        blocks.push(lines.join('\n'));
+    }
+    return blocks.join('\n');
+}
+function renderSections(nodes, lines, depth) {
+    const indent = '  '.repeat(depth);
+    for (const node of nodes) {
+        const shortId = node.headingId ? node.headingId.slice(0, 8) : '';
+        lines.push(`${indent}- title: ${node.title || 'Untitled'}`);
+        if (shortId)
+            lines.push(`${indent}  hid: ${shortId}`);
+        if (node.wordCount > 0)
+            lines.push(`${indent}  words: ${node.wordCount}`);
+        if (node.children.length > 0) {
+            lines.push(`${indent}  sections:`);
+            renderSections(node.children, lines, depth + 1);
+        }
+    }
+}
+function isHeading(node) {
+    return node.type === 'heading' && typeof node.attrs?.level === 'number';
+}
+function updateBreadcrumb(stack, title, level) {
+    while (stack.length > 1 && stack[stack.length - 1].level >= level) {
+        stack.pop();
+    }
+    stack.push({ title, level });
+}
+/**
+ * The raw nodes of one section: everything between the target heading and the
+ * next heading of the same or a higher level, plus the breadcrumb that led to
+ * it. Callers pick their own serialisation.
+ */
+export function extractSectionNodes(noteTitle, doc, targetHeadingId) {
+    if (!doc.content)
+        return null;
+    const headingStack = [{ title: noteTitle, level: 0 }];
+    let startIdx = -1;
+    let targetLevel = 0;
+    for (let i = 0; i < doc.content.length; i++) {
+        const node = doc.content[i];
+        if (!isHeading(node))
+            continue;
+        updateBreadcrumb(headingStack, textContent(node), node.attrs.level);
+        const headingId = node.attrs?.id;
+        if (!headingId)
+            continue;
+        // `treeToText` emits 8-char prefixes, so accept a prefix as well as the
+        // full id — otherwise a model copying from the TOC never matches.
+        if (headingId === targetHeadingId || headingId.startsWith(targetHeadingId)) {
+            startIdx = i + 1;
+            targetLevel = node.attrs.level;
+            break;
+        }
+    }
+    if (startIdx < 0)
+        return null;
+    const headingPath = headingStack.map((h) => h.title).join(' > ');
+    const nodes = [];
+    for (let i = startIdx; i < doc.content.length; i++) {
+        const node = doc.content[i];
+        if (isHeading(node) && node.attrs.level <= targetLevel)
+            break;
+        nodes.push(node);
+    }
+    return { headingPath, nodes };
+}
+/**
+ * One section, serialised to markdown.
+ *
+ * Markdown rather than flattened text on purpose: plain-text extraction garbles
+ * lists, tables, and code blocks, which is exactly the structure a model needs
+ * to answer from a retrieved section.
+ */
+export function extractSection(noteTitle, doc, targetHeadingId) {
+    const section = extractSectionNodes(noteTitle, doc, targetHeadingId);
+    if (!section)
+        return null;
+    const content = tiptapToMarkdown({ type: 'doc', content: section.nodes }).trim();
+    return {
+        headingPath: section.headingPath,
+        content,
+        wordCount: countWords(content)
+    };
+}

package/dist/apps/notes/types.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The Notes document model.
+ *
+ * TipTap's own `JSONContent` is deliberately loose (every field optional), so
+ * the app carries its own narrowed shapes: a `doc` always has `content`, and a
+ * `Note` always has the fields the list and the editor read. Nothing here
+ * imports from `@tiptap/*` — the model is the persistence contract, and a
+ * consumer storing notes server-side should be able to type its API against it
+ * without pulling the editor in.
+ */
+export interface TiptapMark {
+    type: string;
+    attrs?: Record<string, unknown>;
+}
+export interface TiptapNode {
+    type: string;
+    attrs?: Record<string, unknown>;
+    marks?: TiptapMark[];
+    content?: TiptapNode[];
+    text?: string;
+}
+export interface TiptapDocument {
+    type: 'doc';
+    content: TiptapNode[];
+}
+export interface Note {
+    id: string;
+    title: string;
+    /** A single emoji/character shown in the list, or `null` for the default glyph. */
+    icon: string | null;
+    content: TiptapDocument;
+    /**
+     * Flattened text of `content`, refreshed on every write. Kept denormalised
+     * so filtering the list never has to walk every document's AST.
+     */
+    plainText: string;
+    pinned: boolean;
+    /** Epoch milliseconds — JSON-safe, so a note survives a `structuredClone` or a
+     *  `JSON.stringify` round-trip through storage without a revive step. */
+    createdAt: number;
+    updatedAt: number;
+}
+/** The projection the sidebar list renders — no document body. */
+export type NoteListItem = Pick<Note, 'id' | 'title' | 'icon' | 'pinned' | 'updatedAt'>;
+/** Fields a caller may hand to `NotesStore.create()`. */
+export type NoteInit = Partial<Pick<Note, 'title' | 'icon' | 'content' | 'pinned'>>;
+/** Fields `NotesStore.update()` accepts. */
+export type NotePatch = Partial<Pick<Note, 'title' | 'icon' | 'content' | 'pinned'>>;
+export declare const EMPTY_DOC: TiptapDocument;

package/dist/apps/notes/types.js

@@ -0,0 +1,11 @@
+/**
+ * The Notes document model.
+ *
+ * TipTap's own `JSONContent` is deliberately loose (every field optional), so
+ * the app carries its own narrowed shapes: a `doc` always has `content`, and a
+ * `Note` always has the fields the list and the editor read. Nothing here
+ * imports from `@tiptap/*` — the model is the persistence contract, and a
+ * consumer storing notes server-side should be able to type its API against it
+ * without pulling the editor in.
+ */
+export const EMPTY_DOC = { type: 'doc', content: [{ type: 'paragraph' }] };

package/dist/docs/notes.md

@@ -0,0 +1,82 @@
+## Usage
+
+Apps ship on their own subpath and are **not** re-exported from `@sig-nine/era-ui`.
+Notes carries TipTap, and a consumer who never imports an app should never pay
+for it.
+
+```svelte
+<script>
+	import { Notes } from '@sig-nine/era-ui/apps';
+</script>
+
+<Notes />
+```
+
+That is the whole integration: a sidebar with filter, pin, and delete; a TipTap
+document with a `/` command menu and a selection toolbar; and persistence to
+`localStorage` under `era-ui:notes`.
+
+## Peer dependencies
+
+Install alongside the library (they are not bundled):
+
+```
+@tiptap/core @tiptap/pm @tiptap/starter-kit @tiptap/suggestion
+@tiptap/extension-code-block-lowlight @tiptap/extension-details
+@tiptap/extension-highlight @tiptap/extension-image
+@tiptap/extension-placeholder @tiptap/extension-table
+@tiptap/extension-task-item @tiptap/extension-task-list
+@tiptap/extension-typography @tiptap/extension-unique-id
+lowlight tiptap-markdown
+```
+
+## Props
+
+| Prop         | Type             | Default            | Notes                                                             |
+| ------------ | ---------------- | ------------------ | ----------------------------------------------------------------- |
+| `store`      | `NotesStore`     | created internally | Bring your own; when set, the host owns its lifecycle.            |
+| `adapter`    | `NotesAdapter`   | `localStorage`     | Persistence for the internally-created store.                     |
+| `storageKey` | `string`         | `era-ui:notes`     | Key for the default adapter.                                      |
+| `noteId`     | `string \| null` | `null`             | `$bindable` — the open note, for deep-linking or session restore. |
+| `seed`       | `NoteInit[]`     | —                  | Created only when storage comes back empty (first-run sample).    |
+
+## Persistence
+
+Persistence is one small interface, so server-backed hosting is a drop-in swap —
+`load`/`save` may be sync or async:
+
+```ts
+import { Notes, NotesStore } from '@sig-nine/era-ui/apps';
+
+const store = new NotesStore({
+	adapter: {
+		load: () => fetch('/api/notes').then((r) => r.json()),
+		save: (notes) => fetch('/api/notes', { method: 'PUT', body: JSON.stringify(notes) })
+	}
+});
+```
+
+`NotesStore` is the reactive source of truth (`notes`, `ordered`, `loading`,
+`status`, `lastError`) with `create` / `update` / `remove` / `togglePin` /
+`setIcon` / `search` / `toMarkdown` / `flush`. Writes are debounced and
+coalesced, so a burst of keystrokes costs one `save`.
+
+## The heading index
+
+Every document is also a tree. `buildGlobalTree()` walks heading structure,
+`treeToText()` renders it as a table of contents a model can read, and
+`extractSection(title, doc, headingId)` returns just the requested slice as
+structure-preserving markdown — reasoning-based retrieval rather than
+embeddings. Heading ids are stable (`@tiptap/extension-unique-id`), so a section
+address survives edits above it.
+
+## Notes
+
+- Keyboard: `/` opens the command menu, `Mod-K` links a selection, `Mod-S`
+  flushes pending writes immediately.
+- The slash menu and selection toolbar are real Svelte components mounted into
+  the document root, so they follow every axis — density tiers, surface chrome,
+  corners, motion, font — instead of carrying their own hardcoded styling.
+- `@tiptap/extension-mathematics` is deliberately absent: it needs KaTeX's
+  stylesheet and fonts to render. Spread `noteExtensions` and add it yourself if
+  you want math.