@tarhnama/core 0.1.0

package/src/nested.ts

@@ -0,0 +1,271 @@
+import { buildIndex, subtreeRange } from './tree.js';
+import { BODY, MAX_LEVEL, type Blocks, type OutlineLevel } from './types.js';
+
+/**
+ * Nested tree <-> flat blocks.
+ *
+ * Almost every system that stores a tree stores it as ADJACENCY: one row per node with a
+ * `parentId` and an ordinal. This editor's model is deliberately the opposite — a flat list
+ * where each block carries an explicit level, which is what lets it import the Word and
+ * Markdown documents that skip levels constantly (CLAUDE.md §1).
+ *
+ * Binding the two is the entire cost of embedding this editor in a host that already has a
+ * tree, and every host has to do it. Doing it here once, with tests, beats each of them
+ * writing the awkward parts again — the awkward parts being ordering, depth beyond what a
+ * level can express, cycles, orphans, and the fields a tree carries that an outline cannot.
+ */
+
+/** A host's nested node. The shape is the common denominator, not any one product's schema. */
+export interface NestedNode<T = unknown> {
+  readonly id: string;
+  readonly parentId: string | null;
+  readonly title: string;
+  /** Order among siblings. Absent sorts last, stably. */
+  readonly ordinal?: number;
+  /** Prose under the heading. */
+  readonly body?: string;
+  /**
+   * Anything the host keeps that the outline cannot represent — evidence, a source, a
+   * foreign key. Carried through untouched so a round trip never costs the host a field.
+   */
+  readonly data?: T;
+}
+
+export interface NestedToBlocksResult<C> {
+  readonly blocks: Blocks<C>;
+  /**
+   * What could not be represented faithfully.
+   *
+   * Returned rather than thrown, and never silent: a 12-deep branch that quietly flattens
+   * to 9 loses three levels of someone's tree with nothing reporting a problem, and they
+   * find out when they save.
+   */
+  readonly warnings: readonly string[];
+}
+
+/** How a title and a body become block content. Defaults to a single plain run. */
+export interface NestedOptions<C> {
+  readonly toContent?: (text: string) => C;
+  readonly fromContent?: (content: C | undefined) => string;
+}
+
+const defaultToContent = (text: string): unknown => [{ text }];
+
+const defaultFromContent = (content: unknown): string => {
+  if (!Array.isArray(content)) return '';
+  return content.map((run) => (run as { text?: string }).text ?? '').join('');
+};
+
+/** Where the true depth is stashed when a level cannot hold it. See `nestedToBlocks`. */
+const DEPTH_ATTR = 'nestedDepth';
+/** Where the host's own payload rides. */
+const DATA_ATTR = 'data';
+/** The parent, recorded so the reverse mapping never has to guess at a clamped level. */
+const PARENT_ATTR = 'nestedParentId';
+
+/**
+ * Flatten a nested tree into blocks.
+ *
+ * Depth becomes level. Where depth exceeds `MAX_LEVEL` the level CLAMPS — a block with
+ * level 12 is not representable and would be rejected downstream — but the real depth and
+ * the real parent ride along in `attrs`, so `blocksToNested` restores the exact tree. The
+ * clamp is a display limit, never a data loss, and it is reported either way.
+ */
+export function nestedToBlocks<C = unknown, T = unknown>(
+  nodes: readonly NestedNode<T>[],
+  options?: NestedOptions<C>,
+): NestedToBlocksResult<C> {
+  const toContent = (options?.toContent ?? defaultToContent) as (text: string) => C;
+  const warnings: string[] = [];
+
+  const byId = new Map<string, NestedNode<T>>();
+  for (const node of nodes) byId.set(node.id, node);
+
+  // Children by parent, in sibling order. Built once: doing it per node is the quadratic
+  // version of this function and a knowledge tree can be large.
+  const children = new Map<string | null, NestedNode<T>[]>();
+  for (const node of nodes) {
+    /*
+     * A parent that is not in the set makes this node a ROOT rather than dropping it.
+     * Dropping deletes the user's content on the way in; promoting keeps it where they can
+     * see it and fix it.
+     */
+    const missing = node.parentId !== null && !byId.has(node.parentId);
+    if (missing) {
+      warnings.push(
+        `Node ${JSON.stringify(node.id)} has parent ${JSON.stringify(node.parentId)}, which is not in the tree — treated as a root.`,
+      );
+    }
+    const key = missing ? null : node.parentId;
+    const bucket = children.get(key);
+    if (bucket) bucket.push(node);
+    else children.set(key, [node]);
+  }
+
+  for (const bucket of children.values()) {
+    bucket.sort((a, b) => {
+      // Absent ordinals sort last and keep their relative order, so a host that never set
+      // them gets its array order back rather than an arbitrary shuffle.
+      const left = a.ordinal ?? Number.MAX_SAFE_INTEGER;
+      const right = b.ordinal ?? Number.MAX_SAFE_INTEGER;
+      return left - right;
+    });
+  }
+
+  const blocks: unknown[] = [];
+  const seen = new Set<string>();
+
+  /* Iterative, not recursive: a knowledge tree deep enough to blow the stack is a crash
+     with no message, and this runs on data the library did not create. */
+  const stack: { node: NestedNode<T>; depth: number }[] = [];
+  for (const root of [...(children.get(null) ?? [])].reverse()) {
+    stack.push({ node: root, depth: 1 });
+  }
+
+  while (stack.length > 0) {
+    const { node, depth } = stack.pop()!;
+    if (seen.has(node.id)) continue;
+    seen.add(node.id);
+
+    const level = Math.min(depth, MAX_LEVEL) as OutlineLevel;
+    if (depth > MAX_LEVEL) {
+      warnings.push(
+        `Node ${JSON.stringify(node.id)} is ${depth} deep; levels stop at ${MAX_LEVEL}, so it renders at ${MAX_LEVEL}. Its real depth is preserved.`,
+      );
+    }
+
+    const attrs: Record<string, unknown> = {};
+    if (node.data !== undefined) attrs[DATA_ATTR] = node.data;
+    // Only recorded when the level cannot express the truth on its own.
+    if (depth > MAX_LEVEL) {
+      attrs[DEPTH_ATTR] = depth;
+      attrs[PARENT_ATTR] = node.parentId;
+    }
+
+    blocks.push({
+      id: node.id,
+      level,
+      type: 'heading',
+      dir: 'auto',
+      collapsed: false,
+      content: toContent(node.title),
+      ...(Object.keys(attrs).length > 0 ? { attrs } : {}),
+    });
+
+    if (node.body !== undefined && node.body !== '') {
+      blocks.push({
+        // Body text is not a node of its own, so it gets no node id to collide with.
+        id: '',
+        level: BODY,
+        type: 'paragraph',
+        dir: 'auto',
+        collapsed: false,
+        content: toContent(node.body),
+      });
+    }
+
+    for (const child of [...(children.get(node.id) ?? [])].reverse()) {
+      stack.push({ node: child, depth: depth + 1 });
+    }
+  }
+
+  /*
+   * Anything never reached is in a cycle, or hangs off one. Reported rather than emitted:
+   * a cycle has no depth, so there is no level to give it, and inventing one would put the
+   * nodes somewhere arbitrary in the user's document.
+   */
+  const unreachable = nodes.filter((node) => !seen.has(node.id));
+  if (unreachable.length > 0) {
+    warnings.push(
+      `${unreachable.length} node(s) are unreachable from any root — a parent cycle: ${unreachable
+        .map((n) => JSON.stringify(n.id))
+        .join(', ')}.`,
+    );
+  }
+
+  return { blocks: blocks as Blocks<C>, warnings };
+}
+
+/**
+ * Rebuild the nested tree from blocks.
+ *
+ * The inverse of `nestedToBlocks`, and the direction that has to be right on save: a host
+ * writes what this returns back into their database, so anything it gets wrong is data loss
+ * rather than a rendering bug.
+ *
+ * Ordinals are RENUMBERED from document order. That is the point of editing an outline —
+ * the user reordered it — and preserving the incoming ordinals would throw their edit away.
+ */
+export function blocksToNested<C = unknown, T = unknown>(
+  blocks: Blocks<C>,
+  options?: NestedOptions<C>,
+): readonly NestedNode<T>[] {
+  const fromContent = (options?.fromContent ?? defaultFromContent) as (
+    content: C | undefined,
+  ) => string;
+
+  const index = buildIndex(blocks);
+  const out: NestedNode<T>[] = [];
+  const ordinals = new Map<string | null, number>();
+
+  for (let i = 0; i < blocks.length; i++) {
+    const block = blocks[i];
+    if (!block || block.level === BODY) continue;
+
+    /*
+     * The parent is the nearest ancestor HEADING. Taken from the tree index rather than
+     * recomputed, so this agrees with collapse, indent and every other consumer of the
+     * hierarchy — a second implementation of "who is my parent" is a second answer.
+     */
+    const attrs = block.attrs;
+    const clampedParent = attrs?.[PARENT_ATTR];
+    let parentId: string | null;
+    if (typeof clampedParent === 'string' || clampedParent === null) {
+      // Beyond MAX_LEVEL the level cannot express the parent, so the recorded one wins.
+      parentId = clampedParent;
+    } else {
+      const parent = parentOf(blocks, index, i);
+      parentId = parent === -1 ? null : (blocks[parent]?.id ?? null);
+    }
+
+    const ordinal = ordinals.get(parentId) ?? 0;
+    ordinals.set(parentId, ordinal + 1);
+
+    // Body text belonging to this heading: the level-0 blocks that immediately follow it.
+    const bodyParts: string[] = [];
+    for (let j = i + 1; j < blocks.length; j++) {
+      const next = blocks[j];
+      if (!next || next.level !== BODY) break;
+      bodyParts.push(fromContent(next.content));
+    }
+
+    const data = attrs?.[DATA_ATTR];
+
+    out.push({
+      id: block.id,
+      parentId,
+      title: fromContent(block.content),
+      ordinal,
+      ...(bodyParts.length > 0 ? { body: bodyParts.join('\n\n') } : {}),
+      ...(data !== undefined ? { data: data as T } : {}),
+    });
+  }
+
+  return out;
+}
+
+/** Nearest preceding block at a shallower level — the parent heading, or -1. */
+function parentOf(blocks: Blocks, index: ReturnType<typeof buildIndex>, i: number): number {
+  const level = blocks[i]?.level;
+  if (level === undefined || level <= 1) return -1;
+  for (let j = i - 1; j >= 0; j--) {
+    const other = blocks[j]?.level;
+    if (other === undefined || other === BODY) continue;
+    if (other < level) {
+      // Confirm containment against the shared index rather than trusting the scan alone.
+      const [, end] = subtreeRange(index, j);
+      return i < end ? j : -1;
+    }
+  }
+  return -1;
+}

package/src/ops.ts

@@ -0,0 +1,341 @@
+import {
+  type Block,
+  type Blocks,
+  type OutlineLevel,
+  BODY,
+  MAX_LEVEL,
+} from './types.js';
+import { ancestors, buildIndex, isLocked, prevHeading, subtreeRange } from './tree.js';
+
+/**
+ * Structural operations. All are pure: they take a flat list and return a new one,
+ * sharing unchanged blocks by reference so downstream memoization works.
+ *
+ * The defining rule of this module: an operation on a heading applies to its whole
+ * SUBTREE. Indenting a heading and leaving its children behind — the bug in the
+ * earlier Tiptap scaffold — produces an orphaned document.
+ */
+
+/**
+ * Can `i` be indented?
+ *
+ * The rule prevents skipped levels: a heading may go one deeper than the nearest
+ * preceding heading, never more. Without this you can indent from level 1 straight
+ * to level 3 and create a block with no representable parent.
+ *
+ * Body text has no level, so indenting it is meaningless — use `setLevel` to promote
+ * body text into a heading instead.
+ */
+export function canIndent(blocks: Blocks, i: number): boolean {
+  const block = blocks[i];
+  if (!block || block.level === BODY) return false;
+  // A locked block's position is fixed. Checked here rather than in `indent` so the UI
+  // can grey the control out instead of offering an action that silently does nothing.
+  if (isLocked(blocks, buildIndex(blocks), i)) return false;
+
+  const prev = prevHeading(blocks, i);
+  if (prev === -1) return false; // first heading in the document: nothing to nest under
+  if (block.level > blocks[prev]!.level) return false; // already a child of prev
+
+  // The deepest descendant must still fit within MAX_LEVEL after the shift.
+  const index = buildIndex(blocks);
+  const end = index.subtreeEnd[i]!;
+  for (let j = i; j < end; j++) {
+    const l = blocks[j]!.level;
+    if (l !== BODY && l + 1 > MAX_LEVEL) return false;
+  }
+  return true;
+}
+
+export function indent<C>(blocks: Blocks<C>, i: number): Blocks<C> {
+  if (!canIndent(blocks, i)) return blocks;
+  return shiftSubtree(blocks, i, +1);
+}
+
+/** Level 1 cannot outdent — there is nothing above it. Body text has no level. */
+export function canOutdent(blocks: Blocks, i: number): boolean {
+  const block = blocks[i];
+  if (!block || block.level < 2) return false;
+  return !isLocked(blocks, buildIndex(blocks), i);
+}
+
+/**
+ * Outdent a heading and its subtree.
+ *
+ * Pleasant property of the flat model: the following siblings that were at the
+ * outdented block's old level automatically become its children, which is exactly
+ * what Workflowy and Word's outline view do — no extra code needed.
+ */
+export function outdent<C>(blocks: Blocks<C>, i: number): Blocks<C> {
+  if (!canOutdent(blocks, i)) return blocks;
+  return shiftSubtree(blocks, i, -1);
+}
+
+function shiftSubtree<C>(blocks: Blocks<C>, i: number, delta: number): Blocks<C> {
+  const index = buildIndex(blocks);
+  const end = index.subtreeEnd[i]!;
+  const next = blocks.slice();
+  for (let j = i; j < end; j++) {
+    const b = blocks[j]!;
+    if (b.level === BODY) continue; // body text has no level to shift
+    next[j] = { ...b, level: (b.level + delta) as OutlineLevel };
+  }
+  return next;
+}
+
+/** Set a block's level directly — used to promote body text to a heading and back. */
+export function canSetLevel(blocks: Blocks, i: number): boolean {
+  return !!blocks[i] && !isLocked(blocks, buildIndex(blocks), i);
+}
+
+export function setLevel<C>(blocks: Blocks<C>, i: number, level: OutlineLevel): Blocks<C> {
+  if (!canSetLevel(blocks, i)) return blocks;
+  const block = blocks[i];
+  if (!block || block.level === level) return blocks;
+  const next = blocks.slice();
+  next[i] = { ...block, level };
+  return next;
+}
+
+export function toggleCollapse<C>(blocks: Blocks<C>, i: number): Blocks<C> {
+  const block = blocks[i];
+  if (!block) return blocks;
+  const next = blocks.slice();
+  next[i] = { ...block, collapsed: !block.collapsed };
+  return next;
+}
+
+/**
+ * Expand every collapsed ancestor of a block, so it can actually be reached.
+ *
+ * Needed wherever the app navigates to a block the user did not click: a search result, a
+ * cross-document link, a backlink. A collapsed subtree is ABSENT from the DOM, not hidden,
+ * so scrolling to it finds nothing and the jump silently does nothing at all — which reads
+ * as a broken feature rather than as "that match is folded away".
+ *
+ * Only ancestors are touched. The block's own collapse state is left alone: revealing a
+ * heading should not also unfold everything beneath it.
+ *
+ * Returns the SAME list when nothing was collapsed.
+ */
+export function expandAncestors<C>(blocks: Blocks<C>, blockId: string): Blocks<C> {
+  const at = blocks.findIndex((block) => block.id === blockId);
+  if (at === -1) return blocks;
+
+  const index = buildIndex(blocks);
+  const toOpen = new Set(
+    ancestors(index, at).filter((i) => blocks[i]?.collapsed === true),
+  );
+  if (toOpen.size === 0) return blocks;
+
+  return blocks.map((block, i) => (toOpen.has(i) ? { ...block, collapsed: false } : block));
+}
+
+export function setDirection<C>(
+  blocks: Blocks<C>,
+  i: number,
+  dir: Block['dir'],
+): Blocks<C> {
+  const block = blocks[i];
+  if (!block || block.dir === dir) return blocks;
+  const next = blocks.slice();
+  next[i] = { ...block, dir };
+  return next;
+}
+
+/**
+ * Move the subtree rooted at `from` so it begins at document position `to`.
+ *
+ * `to` is interpreted against the ORIGINAL list. Moving a subtree into itself is a
+ * no-op rather than an error, because drag-and-drop will attempt it constantly.
+ */
+/**
+ * Can the subtree at `from` be moved to `to`?
+ *
+ * Both ends matter: a locked subtree cannot be dragged away, and nothing may be dropped
+ * INTO a locked one. Checking only the source is the easy mistake — it lets a reader
+ * append into a chapter they are not allowed to change.
+ */
+export function canMoveSubtree(blocks: Blocks, from: number, to: number): boolean {
+  const index = buildIndex(blocks);
+  if (!blocks[from]) return false;
+  if (isLocked(blocks, index, from)) return false;
+  // A drop lands BETWEEN blocks, so the block before the insertion point is checked as
+  // well: landing just after a locked heading would place the block inside its subtree.
+  const before = to - 1;
+  if (before >= 0 && before < blocks.length && isLocked(blocks, index, before)) {
+    const [, end] = subtreeRange(index, before);
+    if (to < end) return false;
+  }
+  if (to < blocks.length && isLocked(blocks, index, to)) return false;
+  return true;
+}
+
+export function moveSubtree<C>(blocks: Blocks<C>, from: number, to: number): Blocks<C> {
+  const index = buildIndex(blocks);
+  const end = index.subtreeEnd[from]!;
+  if (to >= from && to <= end) return blocks; // dropping inside itself
+  if (!canMoveSubtree(blocks, from, to)) return blocks;
+
+  const slice = blocks.slice(from, end);
+  const rest = [...blocks.slice(0, from), ...blocks.slice(end)];
+  const insertAt = to > from ? to - (end - from) : to;
+  return [...rest.slice(0, insertAt), ...slice, ...rest.slice(insertAt)];
+}
+
+/**
+ * Repair skipped levels — the import path for real Word documents, which jump from
+ * H1 to H3 constantly.
+ *
+ * Each heading is clamped to at most one deeper than the preceding heading, and the
+ * first heading is clamped to 1. Body text is untouched.
+ */
+export function normalizeLevels<C>(blocks: Blocks<C>): Blocks<C> {
+  let changed = false;
+  const next = blocks.slice();
+  let prevLevel = 0;
+
+  for (let i = 0; i < blocks.length; i++) {
+    const b = blocks[i]!;
+    if (b.level === BODY) continue;
+
+    const max = (prevLevel + 1) as OutlineLevel;
+    const level = b.level > max ? max : b.level;
+    if (level !== b.level) {
+      next[i] = { ...b, level };
+      changed = true;
+    }
+    prevLevel = level;
+  }
+
+  return changed ? next : blocks;
+}
+
+/** True when no heading is more than one level deeper than the one before it. */
+export function isNormalized(blocks: Blocks): boolean {
+  let prevLevel = 0;
+  for (const b of blocks) {
+    if (b.level === BODY) continue;
+    if (b.level > prevLevel + 1) return false;
+    prevLevel = b.level;
+  }
+  return true;
+}
+
+
+/**
+ * Lock or unlock a block. Locking a heading makes its whole subtree read-only by
+ * derivation — only the heading itself carries the flag.
+ */
+export function setLocked<C>(blocks: Blocks<C>, i: number, locked: boolean): Blocks<C> {
+  const block = blocks[i];
+  if (!block || (block.locked ?? false) === locked) return blocks;
+  const out = [...blocks];
+  // Unlocking REMOVES the flag rather than setting it to `false`, so a document that
+  // never used locking serializes exactly as it did before the feature existed.
+  out[i] = locked ? { ...block, locked: true } : stripLocked(block);
+  return out;
+}
+
+function stripLocked<C>(block: Block<C>): Block<C> {
+  const { locked: _locked, ...rest } = block;
+  return rest as Block<C>;
+}
+
+/**
+ * The previous sibling of the block at `i`, or -1.
+ *
+ * A sibling is the nearest preceding block at the SAME level that shares a parent — which
+ * for this model means: walking backwards, the first block at that level, stopping if a
+ * shallower one appears first, because that is the parent and the run has ended.
+ */
+function previousSibling(blocks: Blocks, i: number): number {
+  const level = blocks[i]?.level;
+  if (level === undefined) return -1;
+  for (let j = i - 1; j >= 0; j--) {
+    const other = blocks[j]?.level;
+    if (other === undefined) continue;
+    if (other === level) return j;
+    // Body text (level 0) sits under headings and never terminates a heading's run, but a
+    // heading shallower than us IS our parent and there is no earlier sibling under it.
+    if (other !== BODY && other < level) return -1;
+    if (level === BODY && other !== BODY) return -1;
+  }
+  return -1;
+}
+
+/**
+ * Move a node before its previous sibling, subtree and all.
+ *
+ * "Up" is **a sibling**, not a row. A heading with forty blocks under it must jump the
+ * whole of its neighbour's subtree; swapping single rows would tear both apart, and the
+ * design's درخت menu calls this "move node" for that reason.
+ *
+ * A first sibling does not move. The tempting alternative — promote it above its parent —
+ * changes the node's LEVEL as a side effect of a move, and a command that quietly does two
+ * things is one users stop trusting. Indent and outdent are how a level changes.
+ */
+export function moveBlockUp<C>(blocks: Blocks<C>, blockId: string): Blocks<C> {
+  const at = blocks.findIndex((block) => block.id === blockId);
+  if (at === -1) return blocks;
+  const target = previousSibling(blocks, at);
+  if (target === -1) return blocks;
+  return moveSubtree(blocks, at, target);
+}
+
+/**
+ * Move a node after its next sibling, subtree and all.
+ *
+ * The target is the END of the sibling's subtree, in ORIGINAL indices — `moveSubtree`
+ * interprets `to` against the list it was given and does the shift arithmetic itself.
+ * Pre-adjusting by the moved subtree's size (the obvious defensive move) lands the target
+ * back inside the node being moved, where `moveSubtree`'s "dropping inside itself" guard
+ * correctly refuses it and the command silently does nothing.
+ */
+export function moveBlockDown<C>(blocks: Blocks<C>, blockId: string): Blocks<C> {
+  const at = blocks.findIndex((block) => block.id === blockId);
+  if (at === -1) return blocks;
+
+  const index = buildIndex(blocks);
+  const [, end] = subtreeRange(index, at);
+  if (end >= blocks.length) return blocks;
+
+  const level = blocks[at]?.level;
+  const nextLevel = blocks[end]?.level;
+  if (level === undefined || nextLevel === undefined) return blocks;
+  // The block after our subtree is only a SIBLING if it is at our level; anything
+  // shallower is the end of our parent's run and there is nothing left to swap with.
+  if (nextLevel !== level) return blocks;
+
+  const [, siblingEnd] = subtreeRange(index, end);
+  return moveSubtree(blocks, at, siblingEnd);
+}
+
+/**
+ * The level this heading skipped over, or `null`.
+ *
+ * `isNormalized` answers "does this document skip anywhere", which is enough to enable a
+ * repair command and useless for showing the reader WHERE. Frame 1a puts an amber
+ * «سطح ۳ جا افتاده» chip on the offending heading, so the question has to be asked of a
+ * single block.
+ *
+ * Returns the FIRST missing level, not the deepest. When 2 → 4 skips only 3 that is the
+ * same answer either way, but 1 → 4 skips both 2 and 3, and 2 is the one to add first —
+ * naming 3 would send someone to fix the wrong end of the gap.
+ *
+ * Body text is never an answer and never breaks the chain: level 0 is not a hierarchy
+ * level, it belongs to the nearest preceding heading, and a paragraph between two headings
+ * does not make the second one a skip.
+ */
+export function skippedLevelAt(blocks: Blocks, i: number): OutlineLevel | null {
+  const block = blocks[i];
+  if (!block || block.level === BODY) return null;
+
+  const prev = prevHeading(blocks, i);
+  // A document that opens below level 1 has no representable parent for its first heading.
+  const parentLevel = prev === -1 ? 0 : (blocks[prev]?.level ?? 0);
+
+  // Going back up, or one step down, is never a skip.
+  if (block.level <= parentLevel + 1) return null;
+  return (parentLevel + 1) as OutlineLevel;
+}