UNPKG

mind-elixir

Version:

Mind elixir is a free open source mind map core.

153 lines (152 loc) • 6.58 kB
import type MindElixir from '../index'; import type { NodeObj } from '../types/index'; /** * Structural diffing for `nodeData` trees. * * `refresh(data)` rebuilds the whole world: `layout()` empties `.me-nodes` and * `linkDiv()` empties `.lines`. That is the right trade for "install a new * document", but it used to be the only path undo/redo had, so every Ctrl+Z paid * O(nodes) DOM construction plus O(nodes) forced reflows — and dropped * selection, focus and edit state. * * The forward operations (`addChild` / `removeNodes` / `moveNodes*` / * `expandNode`) are already incremental. This module supplies the missing * primitive: `patch(target)` — walk the difference between the live tree and * any target tree, then apply it through those same incremental building * blocks. Undo/redo is one caller (`target` is `entry.before` / `entry.after`); * progressive output (streaming) is another (`target` is whatever the parser * has produced so far). A caller that lags behind simply diffs against the * newest target — intermediate states are never replayed. * * Two layers: * - `diffTree` / `applyDataOps` are **pure** (no DOM, no instance) and define * the op semantics. They are what the property tests exercise. * - `applyTreeOps` performs the same op sequence against a live instance, * mapping each op onto the existing incremental DOM helpers. */ /** * One step of a structural diff. * * Ops are emitted — and must be applied — in phase order (`insert` → `move` → * `remove` → `update`). Every `index` / `before` refers to the state *after* all * preceding ops have been applied, which is what makes a long batch stay * unambiguous — and always to the parent's `children` order, never to a rendered * container. The DOM layer maps that order onto whatever containers the layout * actually uses. */ export type TreeOp = /** Drop this node and everything below it. */ { type: 'remove'; id: string; } /** * Attach a brand new subtree. `node` carries every descendant that is also * new; descendants that already exist in the live tree are pruned out and * arrive later as `move` ops (otherwise the id would exist twice). */ | { type: 'insert'; parentId: string; index: number; node: NodeObj; } /** Relocate an existing node — `before: null` appends to the end. */ | { type: 'move'; id: string; parentId: string; before: string | null; } /** * Reconcile the `children` **key**, not its contents. * * Exported data distinguishes a node that never had children (no key) from one * that lost its last child (`children: []`), and `getData()` shows the * difference. Structural ops can only shrink an array to `[]`, so removing the * key — or creating it — needs this explicit step. Contents are already * correct by the time it runs. */ | { type: 'children'; id: string; present: boolean; } /** Shallow field changes (topic / style / expanded / …). Never structural. */ | { type: 'update'; id: string; patch: Partial<NodeObj>; } /** * The difference is not expressible as local ops — the caller must fall back * to `refresh(target)`. Not a real op: the mere presence aborts the batch. */ | { type: 'resync'; }; export interface DiffOptions { /** * Set when `direction === SIDE`. * * **Ordering is not layout-dependent.** `diffTree` always reconciles the data * order and `applyTreeOps` derives each element's position from that order, so * one parent having two containers (`.lhs` / `.rhs`) needs no special case * here. Getting that split wrong is subtle: reconciling *per container* cannot * reach the target data order at all, because ordering each container says * nothing about how the two interleave in the shared `children` array. * * What *does* depend on the layout is `direction` itself. `layout()` assigns a * side to every main node that has none, alternating left/right as it walks — * a write into the caller's data that no local op can reproduce. A tree holding * an unassigned main node therefore degrades to `resync`. */ sideLayout?: boolean; } /** * Shallow-with-one-level-recursion equality, used to decide whether a field * needs an `update`, and — since arrows and summaries are not diffed — whether * the link layer `diffRefresh` installs is any different from the one already * rendered. Reference equality first (free, and the common case for scalars), * then a structural compare for the object-valued fields. A false negative only * costs an `update` that writes the value it already had, or a redraw of an * unchanged link layer. */ export declare const sameValue: (a: unknown, b: unknown) => boolean; /** * Diff `current` against `target`. * * Emitted order is `insert` → `move` → `remove` → `update`, which is what makes * the indices unambiguous: * - moves run before removes so a node can be rescued out of a subtree that is * about to disappear (the undo of `insertParent` is exactly that shape); * - inserts run first so a move can target a parent that did not exist yet * (the redo of `insertParent`); * - updates run last, so an `expanded` change relocates/materialises children * whose final structure is already in place. */ export declare function diffTree(current: NodeObj, target: NodeObj, options?: DiffOptions): TreeOp[]; /** * Apply ops to a plain tree — the reference implementation of the op semantics. * `applyTreeOps` below mirrors it against the DOM. `root` is mutated in place. */ export declare function applyDataOps(root: NodeObj, ops: TreeOp[]): NodeObj; /** * Apply a diff to a live instance. * * Returns `false` when the op list contains a `resync` — the caller then hands * the target to `refresh()` instead, which is exactly today's behaviour. * * `nodeData` is mutated **in place**: its identity is what the outliner binds to * and what focus mode aliases (`nodeDataBackup`), so replacing it would break * both. * * Data and DOM are indexed separately. A node hidden inside a collapsed ancestor * has no element but its data still has to move; looking nodes up through the * DOM alone would silently drop every op that targeted one. * * `redraw` forces the line/arrow/summary layer to be rebuilt even when the op * list is empty — the caller uses it when it replaced link data (arrows, * summaries) that `diffTree` cannot see. */ export declare const applyTreeOps: (mei: MindElixir, ops: TreeOp[], redraw?: boolean) => boolean;