mind-elixir
Version:
Mind elixir is a free open source mind map core.
153 lines (152 loc) • 6.58 kB
TypeScript
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;