@dou-ui/flow 0.0.0-stage → 0.1.0-alpha.0

package/dist/types/core/extension.d.ts

@@ -0,0 +1,141 @@
+import type { ContextMenuItem } from 'dou-ui';
+import type { Component } from 'vue';
+import type { FlowEditorContext } from '../context';
+import type { FlowDrawContext } from '../export/context';
+import type { FlowConnection, PortTypes } from './connect';
+import type { EdgeTypeSpec } from './edge-types';
+import type { FlowMenuTarget, FlowToolbarItem } from './menu';
+import type { FlowDocument, FlowEdge, FlowNode, Point } from './model';
+import type { NodeTypeSpec } from './node-types';
+import type { FlowTransaction } from './transaction';
+/** What an extension's hooks receive; the same as `useFlowEditor()`. */
+export type FlowExtensionContext = FlowEditorContext;
+/**
+ * A key handler: return `false` to let the key through to the next handler
+ * and the editor's own keys; anything else means it was handled.
+ */
+export type FlowKeyHandler = (event: KeyboardEvent) => boolean | void;
+/** An undo history that replaces the editor's own, e.g. one that only undoes this user's changes. */
+export interface FlowHistoryHandler {
+    /** `false` when there is nothing to undo. */
+    undo: () => boolean;
+    redo: () => boolean;
+    canUndo: () => boolean;
+    canRedo: () => boolean;
+}
+/** A press on the editor that an extension may take over, e.g. a drawing tool. */
+export interface FlowPress {
+    /** Where it was pressed, in canvas coordinates. */
+    point: Point;
+    /** The node under the pointer, if any. */
+    node: FlowNode | null;
+    event: PointerEvent;
+}
+/** Follows a press an extension took over, until the pointer is let go. */
+export interface FlowPressHandler {
+    move?: (point: Point, event: PointerEvent) => void;
+    end?: (point: Point, event: PointerEvent) => void;
+    /** Escape, a second finger, or the browser took the pointer. */
+    cancel?: () => void;
+}
+/**
+ * A piece of the editor: node types, port types, connection rules, keys and
+ * extra layers. The default node type comes as an extension too (see
+ * `flowKit`), so a third-party extension stands on equal footing with it.
+ */
+export interface FlowExtension {
+    name: string;
+    /** Higher runs first: its keys and rules are asked before others. Defaults to 100. */
+    priority?: number;
+    nodeTypes?: NodeTypeSpec<any>[];
+    /** Edge types, used by `edge.type`; `flowKit` brings `bezier`, `step` and `straight`. */
+    edgeTypes?: EdgeTypeSpec<any>[];
+    /**
+     * The edge type of edges without a `type`, unless the editor's `edge-type`
+     * prop says otherwise. The last extension that sets it wins.
+     */
+    edgeType?: string;
+    /** Looks and connection rules of port types; see the `portTypes` prop. */
+    portTypes?: PortTypes;
+    /**
+     * A connection rule, asked after the built-in ones. Return `false` to
+     * refuse, or a sentence saying why. Called for every port while dragging.
+     */
+    canConnect?: (connection: FlowConnection, doc: FlowDocument) => boolean | string;
+    /** Keys, written as in `useHotkey` (e.g. `mod+g`, `shift+t`), while the canvas has focus. */
+    keymap?: (context: FlowExtensionContext) => Record<string, FlowKeyHandler>;
+    /** Rewrites nodes and edges before they are pasted, e.g. to reset run state. */
+    transformPaste?: (data: FlowDocument, context: FlowExtensionContext) => FlowDocument;
+    /**
+     * Components drawn in canvas coordinates: `below` under the edges, `above`
+     * over the nodes. They move and zoom with the canvas.
+     */
+    layers?: {
+        below?: Component[];
+        above?: Component[];
+    };
+    /**
+     * What `layers.above` shows, for `exportSVG` and `exportPNG`: SVG markup
+     * in canvas coordinates, drawn over the nodes. `nodes` are the ones in the
+     * picture; `draw.width` and `draw.height` are the picture's size.
+     */
+    drawLayer?: (context: FlowExtensionContext, draw: FlowDrawContext, nodes: FlowNode[]) => string;
+    /**
+     * Components drawn over the editor in screen space, e.g. a panel or a
+     * popup. They can call `useFlowEditor()`.
+     */
+    overlays?: Component[];
+    /**
+     * Items for the menu opened by a right click, a long press on the empty
+     * canvas, or the context menu key. Extensions' items follow each other
+     * in priority order; an empty list leaves them out.
+     */
+    contextMenu?: (context: FlowExtensionContext, target: FlowMenuTarget) => ContextMenuItem[];
+    /** Buttons for the toolbar that floats above the selected nodes. */
+    toolbarItems?: (context: FlowExtensionContext, nodes: FlowNode[]) => FlowToolbarItem[];
+    /** Buttons for the toolbar that floats above the selected edges, when no node is selected. */
+    edgeToolbarItems?: (context: FlowExtensionContext, edges: FlowEdge[]) => FlowToolbarItem[];
+    /**
+     * Asked first when the canvas or a node is pressed with the main button or
+     * one finger, in priority order. Return handlers to take the press over;
+     * the editor then doesn't select, drag or pan for it.
+     */
+    press?: (context: FlowExtensionContext, press: FlowPress) => FlowPressHandler | void;
+    /** Runs once the editor is mounted. Return a function to run when it unmounts. */
+    setup?: (context: FlowExtensionContext) => void | (() => void);
+    /**
+     * Sees every change before it reaches the document, in priority order,
+     * and may add steps to it. Undo and redo come through here too.
+     */
+    transaction?: (tr: FlowTransaction, context: FlowExtensionContext) => void;
+    /** Replaces the editor's undo history; the first extension that has one wins. */
+    history?: (context: FlowExtensionContext) => FlowHistoryHandler;
+}
+/** Declares an extension; only gives it a type. */
+export declare function defineFlowExtension(extension: FlowExtension): FlowExtension;
+/** Everything the extensions contribute, gathered once per list. */
+export interface ResolvedFlowExtensions {
+    extensions: FlowExtension[];
+    nodeTypes: Map<string, NodeTypeSpec>;
+    edgeTypes: Map<string, EdgeTypeSpec>;
+    edgeType: string | undefined;
+    portTypes: PortTypes;
+    rules: NonNullable<FlowExtension['canConnect']>[];
+    keymaps: NonNullable<FlowExtension['keymap']>[];
+    pasteTransforms: NonNullable<FlowExtension['transformPaste']>[];
+    below: Component[];
+    above: Component[];
+    overlays: Component[];
+    menus: NonNullable<FlowExtension['contextMenu']>[];
+    toolbars: NonNullable<FlowExtension['toolbarItems']>[];
+    edgeToolbars: NonNullable<FlowExtension['edgeToolbarItems']>[];
+    drawLayers: NonNullable<FlowExtension['drawLayer']>[];
+    setups: NonNullable<FlowExtension['setup']>[];
+    transactions: NonNullable<FlowExtension['transaction']>[];
+    history: FlowExtension['history'];
+    presses: NonNullable<FlowExtension['press']>[];
+}
+type ExtensionList = readonly (FlowExtension | readonly FlowExtension[])[];
+/** Sorts the extensions by priority and collects what they add. */
+export declare function resolveFlowExtensions(list: ExtensionList): ResolvedFlowExtensions;
+export {};

package/dist/types/core/geometry.d.ts

@@ -0,0 +1,63 @@
+import type { FlowViewport, Point, Rect } from './model';
+export declare function boundsOf(rects: readonly Rect[]): Rect | null;
+export declare function intersects(a: Rect, b: Rect): boolean;
+/** The rectangle spanned by two corners, in any order. */
+export declare function rectFrom(a: Point, b: Point): Rect;
+export declare const snapTo: (value: number, step: number) => number;
+export interface Guide {
+    axis: 'x' | 'y';
+    /** The canvas coordinate of the line. */
+    at: number;
+    /** Where the line starts and ends along the other axis. */
+    from: number;
+    to: number;
+}
+export interface SnapResult {
+    /** How far to shift the moving box so it lines up. */
+    dx: number;
+    dy: number;
+    guides: Guide[];
+}
+/**
+ * A port on a moving node and the port it is connected to. Lining them up
+ * makes the edge between them a straight line.
+ */
+export interface SnapLink {
+    /** Where the moving port is before the snap. */
+    from: Point;
+    to: Point;
+    /** `y` levels ports on the left or right; `x` ports on the top or bottom. */
+    axis: 'x' | 'y';
+}
+/**
+ * Lines the moving box up, on each axis separately, when it is within
+ * `threshold`: first a port with the port it is connected to, then the
+ * nearest edge or centre of another box. Without a match on an axis, the
+ * box's top left corner snaps to `grid` instead.
+ */
+export declare function snapBox(box: Rect, others: readonly Rect[], { threshold, grid, links }: {
+    threshold: number;
+    grid: number;
+    links?: readonly SnapLink[];
+}): SnapResult;
+/** Turns `point` by `degrees` around `centre`. */
+export declare function turn(point: Point, centre: Point, degrees: number): Point;
+/** The box around `rect` turned by `degrees` about its centre. */
+export declare function turnedBox(rect: Rect, degrees: number): Rect;
+/** Whether `box` and `rect` turned by `degrees` about its centre overlap. */
+export declare function intersectsTurned(box: Rect, rect: Rect, degrees: number): boolean;
+/**
+ * Keeps a pan within reach of the nodes: the view may go as far as having
+ * the nodes just leave it on the opposite side, a screen of room to draw in,
+ * and no further, so the canvas never runs off to coordinates the browser
+ * can't draw (it clamps lengths at about 3.3e7 px, and the layer and the
+ * nodes stop lining up long before). With no nodes, the origin is kept in
+ * view. A view already outside, e.g. set through `v-model:viewport` or left
+ * there when nodes were removed, isn't pulled back: it can only move closer.
+ * Zooming in is left as it is: it stays inside the view, so it never goes
+ * further out.
+ */
+export declare function clampPan(next: FlowViewport, current: FlowViewport, content: Rect | null, size: {
+    width: number;
+    height: number;
+}): FlowViewport;

package/dist/types/core/groups.d.ts

@@ -0,0 +1,23 @@
+import type { FlowNode, Point, Rect } from './model';
+/**
+ * Parent links between nodes, worked out once per document. A `parent`
+ * naming a missing node, or one that would close a loop, is ignored.
+ */
+export declare class FlowTree {
+    readonly parents: Map<string, string>;
+    readonly children: Map<string, string[]>;
+    constructor(nodes: readonly FlowNode[]);
+    parentOf(id: string): string | undefined;
+    /** The node's ancestors, nearest first. */
+    ancestors(id: string): string[];
+    /** All nodes inside, at any depth. */
+    descendants(id: string): string[];
+    depth(id: string): number;
+    /** `ids` without the ones inside another of them. */
+    topmost(ids: Iterable<string>): string[];
+}
+/** The innermost of `containers` whose rect holds `point`. */
+export declare function containerAt(point: Point, containers: {
+    id: string;
+    rect: Rect;
+}[]): string | undefined;

package/dist/types/core/history.d.ts

@@ -0,0 +1,24 @@
+import type { FlowDocument, FlowSelection } from './model';
+import { type FlowTransaction } from './transaction';
+export declare class FlowHistory {
+    private depth;
+    private done;
+    private undone;
+    constructor(depth?: number);
+    get canUndo(): boolean;
+    get canRedo(): boolean;
+    record(tr: FlowTransaction, selectionBefore: FlowSelection, selectionAfter: FlowSelection, now?: number): void;
+    /** Ends the current group, so the next change starts a new undo step. */
+    close(): void;
+    /** Forgets the last entry if it belongs to `group`, e.g. after a cancelled drag. */
+    drop(group: string): void;
+    undo(doc: FlowDocument): {
+        tr: FlowTransaction;
+        selection: FlowSelection;
+    } | null;
+    redo(doc: FlowDocument): {
+        tr: FlowTransaction;
+        selection: FlowSelection;
+    } | null;
+    clear(): void;
+}

package/dist/types/core/menu.d.ts

@@ -0,0 +1,40 @@
+import type { ContextMenuItem } from 'dou-ui';
+import type { Component } from 'vue';
+import type { FlowEdge, FlowNode, Point } from './model';
+/** What a context menu was opened on. `point` is in canvas coordinates. */
+export type FlowMenuTarget = {
+    kind: 'node';
+    node: FlowNode;
+    point: Point;
+} | {
+    kind: 'edge';
+    edge: FlowEdge;
+    point: Point;
+} | {
+    kind: 'canvas';
+    point: Point;
+};
+export interface FlowToolbarItem {
+    /** Unique within the toolbar. */
+    key: string;
+    /** Shown as a tooltip and read by screen readers. */
+    label: string;
+    icon: Component;
+    /** Called on click. */
+    run?: () => void;
+    disabled?: boolean;
+    /** For a button that turns something on and off: whether it is on. */
+    pressed?: boolean;
+    /**
+     * The key that does the same, as a hotkey like `mod+d`: shown in the
+     * tooltip and given to screen readers as `aria-keyshortcuts`. It is only
+     * a hint; bind the key with `keymap`.
+     */
+    shortcut?: string;
+    /**
+     * Choices to show under the button instead of `run`: the editor places
+     * the menu, marks the button as opening one, and closes it on a second
+     * click. Give the items `checked` to mark the one in use.
+     */
+    children?: ContextMenuItem[];
+}

package/dist/types/core/model.d.ts

@@ -0,0 +1,87 @@
+export type FlowData = Record<string, unknown>;
+export interface FlowNode<Data extends FlowData = FlowData> {
+    id: string;
+    /** A registered node type; `'default'` when left out. */
+    type?: string;
+    x: number;
+    y: number;
+    /** Only stored for nodes that can be resized; otherwise the content decides. */
+    width?: number;
+    height?: number;
+    data?: Data;
+    /** A locked node cannot be moved or deleted. */
+    locked?: boolean;
+    /**
+     * The container node, e.g. a group, this node sits in. Its `x` and `y`
+     * stay canvas coordinates; moving the container moves it along.
+     */
+    parent?: string;
+    /**
+     * Stacking order among nodes that aren't containers: higher is drawn on
+     * top. Nodes without it count as `0`; equal ones keep the document order.
+     */
+    z?: number;
+}
+export interface FlowEndpoint {
+    node: string;
+    /** Leave out to attach to the node itself. */
+    port?: string;
+}
+export interface FlowEdge<Data extends FlowData = FlowData> {
+    id: string;
+    source: FlowEndpoint;
+    target: FlowEndpoint;
+    /** The edge type: `bezier`, `step`, `straight` or one added by an extension. The editor's `edge-type` when left out. */
+    type?: string;
+    /** Text shown on the edge. */
+    label?: string;
+    /** Dashes run along the edge in its direction, e.g. while data flows through it. */
+    animated?: boolean;
+    data?: Data;
+}
+export interface FlowDocument {
+    /** The version of the format; see `migrateDocument`. */
+    version: 1;
+    nodes: FlowNode[];
+    edges: FlowEdge[];
+}
+export type PortSide = 'left' | 'right' | 'top' | 'bottom';
+export interface FlowPortSpec {
+    id: string;
+    /** Inputs receive edges, outputs start them. */
+    kind: 'input' | 'output';
+    /** Where the port sits; inputs default to the left, outputs to the right. */
+    side?: PortSide;
+    label?: string;
+    /** What the port carries. Two ports connect when they share a type, or either is `'any'`. */
+    dataType?: string | string[];
+    /**
+     * The most edges the port takes. Inputs take one by default, outputs any
+     * number. A new edge on a full port replaces its oldest edge.
+     */
+    max?: number;
+}
+/** Where the canvas is shown: `x` and `y` are the screen offset of the canvas origin. */
+export interface FlowViewport {
+    x: number;
+    y: number;
+    zoom: number;
+}
+export interface FlowSelection {
+    nodes: string[];
+    edges: string[];
+}
+export interface Point {
+    x: number;
+    y: number;
+}
+export interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export declare const emptyDocument: () => FlowDocument;
+export declare const emptySelection: () => FlowSelection;
+/** A short id, unique within this page and very likely across clients. */
+export declare function createId(prefix?: string): string;

package/dist/types/core/node-types.d.ts

@@ -0,0 +1,103 @@
+import type { FlowDrawContext } from '../export/context';
+import type { Component } from 'vue';
+import type { FlowMessages } from '../locale';
+import type { FlowData, FlowNode, FlowPortSpec, PortSide, Rect } from './model';
+/** What a node type's component receives. */
+export interface NodeViewProps<Data extends FlowData = FlowData> {
+    node: FlowNode<Data>;
+    data: Data;
+    ports: FlowPortSpec[];
+    selected: boolean;
+    readonly: boolean;
+    /** Merges `patch` into the node's data, as one undo step. */
+    updateData: (patch: Partial<Data>) => void;
+}
+export interface NodeTypeSpec<Data extends FlowData = FlowData> {
+    type: string;
+    /**
+     * Renders the node's content. The editor draws the frame, selection and
+     * focus ring around it. Place ports with `<DouFlowPort>`; ports the
+     * component does not place are spread along their sides.
+     */
+    component?: Component;
+    /** The node's ports, fixed or worked out from its data. */
+    ports?: FlowPortSpec[] | ((node: FlowNode<Data>) => FlowPortSpec[]);
+    /** Data for a new node of this type. */
+    defaults?: () => Data;
+    /**
+     * The node's accessible name; `data.label` by default. `messages` are the
+     * editor's current strings, for names that follow the locale.
+     */
+    label?: (node: FlowNode<Data>, messages: FlowMessages) => string;
+    /**
+     * How the type is offered by `paletteTypes` and in the list that opens
+     * when an edge is dropped on the empty canvas. Types without it aren't offered.
+     */
+    palette?: NodePaletteSpec;
+    /**
+     * Nodes dropped inside become its children (`parent`) and move with it;
+     * with `data.collapsed` they are hidden and their edges end on it.
+     * Containers are drawn under edges and other nodes.
+     */
+    container?: boolean;
+    /**
+     * A handle on the selected node changes its stored `width` and `height`.
+     * A function decides per node, e.g. not while it is turned.
+     */
+    resizable?: NodeResize | ((node: FlowNode<Data>) => NodeResize);
+    /** The `width` and `height` a new node starts with. */
+    size?: {
+        width: number;
+        height: number;
+    };
+    /**
+     * `false` leaves out the card the editor draws around the component (its
+     * border, background and shadow), for nodes that draw their own outline,
+     * e.g. a circle. Selection then shows as a thin outline around the box.
+     */
+    frame?: boolean;
+    /**
+     * How far the node is drawn turned about its centre, in degrees clockwise;
+     * `0` by default. The component turns what it draws, and `draw` turns its
+     * export; the editor follows: the selection outline, picking with a box,
+     * what is drawn in view, the toolbar and other people's outlines. For
+     * nodes with `frame: false`. A turned node has no editor resize handle.
+     */
+    rotation?: (node: FlowNode<Data>) => number;
+    /**
+     * The box the node covers on screen when it draws outside its own `rect`.
+     * The toolbar over the selection floats above it. By default the box
+     * around `rect` turned by `rotation`.
+     */
+    bounds?: (node: FlowNode<Data>, rect: Rect) => Rect;
+    /**
+     * Draws the node as SVG markup for `exportSVG` and `exportPNG`, in its
+     * own coordinates. Without it the node is drawn as a card with its name.
+     */
+    draw?: (node: FlowNode<Data>, draw: FlowDrawContext) => string;
+}
+export interface NodePaletteSpec {
+    label: string;
+    icon?: Component;
+    /** Types with the same group are listed together under its name. */
+    group?: string;
+    description?: string;
+    /** Other words the search should find the type by. */
+    keywords?: string[];
+}
+/** Declares a node type, with the data type checked against its component. */
+export declare function defineNodeType<Data extends FlowData = FlowData>(spec: NodeTypeSpec<Data>): NodeTypeSpec<Data>;
+export declare const portSide: (port: FlowPortSpec) => PortSide;
+export declare function portsOf(spec: NodeTypeSpec | undefined, node: FlowNode): FlowPortSpec[];
+export type NodeResize = boolean | {
+    minWidth?: number;
+    minHeight?: number;
+};
+/** Whether a node can be resized, and its smallest size; `null` when it can't. */
+export declare function resizeOf(spec: NodeTypeSpec | undefined, node: FlowNode): {
+    minWidth?: number;
+    minHeight?: number;
+} | null;
+export declare function labelOf(spec: NodeTypeSpec | undefined, node: FlowNode, messages: FlowMessages): string;
+/** The box `node` covers on screen, drawn at `rect`. */
+export declare function nodeBounds(spec: NodeTypeSpec, node: FlowNode, rect: Rect): Rect;

package/dist/types/core/order.d.ts

@@ -0,0 +1,7 @@
+import type { FlowDocument, FlowNode } from './model';
+/**
+ * Nodes in the order a flow reads: every node after the ones it depends on,
+ * and among nodes that are ready, the leftmost (then topmost) first. Nodes
+ * on a cycle follow the rest, left to right.
+ */
+export declare function flowOrder(doc: FlowDocument): FlowNode[];

package/dist/types/core/transaction.d.ts

@@ -0,0 +1,97 @@
+import type { FlowDocument, FlowEdge, FlowNode } from './model';
+type Patch<T> = {
+    [K in keyof T]?: T[K] | undefined;
+};
+export type FlowStep = {
+    type: 'addNode';
+    node: FlowNode;
+    index?: number;
+} | {
+    type: 'removeNode';
+    id: string;
+} | {
+    type: 'updateNode';
+    id: string;
+    patch: Patch<FlowNode>;
+} | {
+    type: 'addEdge';
+    edge: FlowEdge;
+    index?: number;
+} | {
+    type: 'removeEdge';
+    id: string;
+} | {
+    type: 'updateEdge';
+    id: string;
+    patch: Patch<FlowEdge>;
+};
+export interface FlowTransactionMeta {
+    /** Keep out of the undo history, e.g. changes from another client. */
+    history?: boolean;
+    /**
+     * Consecutive transactions in the same group within a second undo as
+     * one, e.g. the frames of a drag or repeated arrow key nudges.
+     */
+    group?: string;
+    /** Who made the change, passed on to the `transaction` event. */
+    origin?: string;
+}
+/**
+ * A batch of changes to a document. Steps apply as they are added, so
+ * later calls see earlier ones; `doc` is the result.
+ */
+export declare class FlowTransaction {
+    readonly before: FlowDocument;
+    readonly steps: FlowStep[];
+    /** The steps that undo this transaction, in the order to apply them. */
+    readonly inverse: FlowStep[];
+    meta: FlowTransactionMeta;
+    private nodes;
+    private edges;
+    private copied;
+    constructor(before: FlowDocument);
+    get doc(): FlowDocument;
+    /** Whether the change makes any change: it has steps and wasn't cancelled. */
+    get changed(): boolean;
+    private stopped;
+    /**
+     * Stops the change: none of it is applied or kept for undo, and the
+     * editor fires `transactionCancel` and says why. For an extension's `transaction`
+     * hook, e.g. to keep people from changing what they may not; hooks after
+     * it don't run. A change kept out of the history (`meta.history: false`),
+     * such as undo, redo or another person's, can't be cancelled and goes ahead.
+     */
+    cancel(reason?: string): this;
+    /** Whether `cancel` stopped it. */
+    get cancelled(): boolean;
+    /** What `cancel` was given, to tell people why. */
+    get cancelReason(): string | undefined;
+    getNode(id: string): FlowNode<import("./model").FlowData> | undefined;
+    getEdge(id: string): FlowEdge<import("./model").FlowData> | undefined;
+    /** Edges that start or end at a node. */
+    edgesOf(id: string): FlowEdge<import("./model").FlowData>[];
+    setMeta(meta: FlowTransactionMeta): this;
+    step(step: FlowStep): this;
+    addNode(node: FlowNode, index?: number): this;
+    /** Removes a node and every edge attached to it. */
+    removeNode(id: string): this;
+    updateNode(id: string, patch: Patch<FlowNode>): this;
+    moveNode(id: string, x: number, y: number): this;
+    /** Merges `patch` into the node's `data`. */
+    updateData(id: string, patch: Record<string, unknown>): this;
+    addEdge(edge: FlowEdge, index?: number): this;
+    removeEdge(id: string): this;
+    updateEdge(id: string, patch: Patch<FlowEdge>): this;
+    private writable;
+    /** Applies a step and returns its inverse, or `null` when it changes nothing. */
+    private apply;
+}
+/** Applies steps to a document; steps that no longer apply are skipped. */
+export declare function applyFlowSteps(doc: FlowDocument, steps: readonly FlowStep[]): FlowTransaction;
+/**
+ * Folds updates of the same node or edge into one, as long as nothing
+ * adds or removes it in between. Updates of different targets commute, so
+ * the result applies the same as the original list.
+ */
+export declare function compactFlowSteps(steps: readonly FlowStep[]): FlowStep[];
+export {};

package/dist/types/document.d.ts

@@ -0,0 +1,57 @@
+import { type FlowExtension } from './core/extension';
+import type { EdgeTypeSpec } from './core/edge-types';
+import type { FlowDocument } from './core/model';
+import { type NodeTypeSpec } from './core/node-types';
+export interface DocumentProblem {
+    code: 'version' | 'shape' | 'missing-id' | 'duplicate-id' | 'bad-position' | 'unknown-type' | 'missing-node' | 'missing-port' | 'missing-parent' | 'parent-cycle';
+    /** The node at fault, or the node an edge's end points at. */
+    nodeId?: string;
+    /** The edge at fault. */
+    edgeId?: string;
+    /**
+     * Where the problem is, as a path into the document, e.g. `nodes[2]` or
+     * `edges[0].target`; `version` for the version.
+     */
+    path: string;
+    /** The id, type or port at fault, for the editor's message. */
+    text: string;
+    /** An English description, for logs. */
+    message: string;
+}
+export interface CheckDocumentOptions {
+    /**
+     * The editor's `extensions`, for the node and edge types they add. With
+     * none of `extensions`, `nodeTypes` and `edgeTypes`, types and ports are
+     * not checked; with `nodeTypes` or `edgeTypes` alone, the default
+     * `flowKit()` is assumed, as in the editor.
+     */
+    extensions?: readonly (FlowExtension | readonly FlowExtension[])[];
+    /** The editor's `nodeTypes`. */
+    nodeTypes?: readonly NodeTypeSpec<any>[];
+    /** The editor's `edgeTypes`. */
+    edgeTypes?: readonly EdgeTypeSpec<any>[];
+}
+/**
+ * The problems of a flow document, before it is saved or shown: an unknown
+ * version, nodes and edges without an id or sharing one, positions that are
+ * not numbers, edges whose ends are missing, `parent` pointing nowhere or
+ * in a circle, and, given the editor's types, types nobody registered and
+ * ports a node does not have.
+ */
+export declare function checkDocument(document: FlowDocument, options?: CheckDocumentOptions): DocumentProblem[];
+/**
+ * Brings a saved document up to the current version, and fills what an
+ * older or hand-written one may lack (`version`, `nodes`, `edges`). Nodes
+ * and edges that are not objects are dropped; anything else is kept as it
+ * is. Throws for data that is not an object
+ * (an array, `null`, a string) and for a version it does not know.
+ */
+export declare function migrateDocument(input: unknown): FlowDocument;
+/**
+ * The `v-model` as the editor reads it. A document of the wrong shape (not
+ * an object, without `nodes` or `edges`, without a known `version`) gets a
+ * warning in development and is read with what is missing left empty and
+ * the version as 1, so the editor still opens and what it writes back
+ * carries `version: 1`.
+ */
+export declare function readDocument(value: unknown): FlowDocument;

package/dist/types/export/color.d.ts

@@ -0,0 +1,7 @@
+/**
+ * A computed color as `rgb(…)`, `rgba(…)` or `#rrggbb`, which every SVG reader
+ * understands. A canvas converts most colors as it parses them; colors it
+ * keeps in another space (`oklab(…)`, `color(…)`) are painted on a pixel
+ * and read back.
+ */
+export declare function plainColor(color: string): string;