@rokkit/graph 1.7.0 → 1.8.1

package/dist/state/GraphConfig.svelte.d.ts

@@ -0,0 +1,124 @@
+import type { GraphPreset } from '../preset.js';
+import type { Arrange, Density, EdgeStyle, LayoutFn, NodeAxis, ShowEdges } from '../layout/types.js';
+import type { GraphFields } from '../types.js';
+import type { GraphStateConfig } from '../GraphState.svelte.js';
+export type GraphConfigValues = {
+    nodes: unknown[];
+    edges: unknown[];
+    fields: GraphFields;
+    layout: string | LayoutFn;
+    focus: string | null;
+    density: Density;
+    arrange: Arrange;
+    groupBy: NodeAxis;
+    nestBy: NodeAxis | null;
+    groupTint: boolean;
+    sizeBy: string;
+    sizeScale: 'linear' | 'log';
+    depth: number;
+    focusPath: string[];
+    levels: number | undefined;
+    root: string | null;
+    bundleTension: number | undefined;
+    radialMode: 'tree' | 'dendrogram';
+    edgeStyle: EdgeStyle;
+    preset: GraphPreset;
+    mode: 'light' | 'dark';
+    label: string | undefined;
+    onselect: ((id: string | null) => void) | undefined;
+    ondrill: GraphStateConfig['ondrill'];
+    ondrillup: GraphStateConfig['ondrillup'];
+    onfocuspath: GraphStateConfig['onfocuspath'];
+    onexpand: GraphStateConfig['onexpand'];
+    oncollapse: GraphStateConfig['oncollapse'];
+    showEdges: ShowEdges;
+    layerLabels: string[] | undefined;
+    widthBy: string | undefined;
+    heightBy: string | undefined;
+    colorBy: string | undefined;
+    above: string | undefined;
+    shadeBy: string | undefined;
+};
+type Key = keyof GraphConfigValues;
+type Field = {
+    key: Key;
+    /** Shapes the supplied-or-fallback value; sees the whole config (nestBy reads groupBy). */
+    normalise?: (value: unknown, config: GraphStateConfig) => unknown;
+} & ({
+    fallback: () => unknown;
+    raw?: never;
+}
+/** Taken as given — a `null` stays `null`, an omitted key is `undefined` — no fallback. */
+ | {
+    raw: true;
+    fallback?: never;
+});
+/**
+ * Every input, its default, and how it is shaped. `update()` assigns every field on every call —
+ * an omitted key reverts to its fallback, which is the contract the GraphState specs pin
+ * field by field.
+ */
+export declare const CONFIG_FIELDS: readonly Field[];
+/**
+ * A graph's inputs — the one job `update()` has. The layout pipeline and the selection read
+ * from here.
+ *
+ * `update()` FULLY re-applies config rather than merging deltas, matching `SparkState.update` —
+ * so a prop reverting to undefined actually reverts. `apply()` is the merging verb, for a
+ * component writing the few options its own controls drive into a state someone else owns.
+ */
+export declare class GraphConfig {
+    #private;
+    constructor(config?: GraphStateConfig);
+    update(config?: GraphStateConfig): void;
+    /** Merge a partial config over the last full one, leaving every key it does not name alone. */
+    apply(config: Partial<GraphStateConfig>): GraphStateConfig;
+    /**
+     * Change the detail level from inside the component. `Graph`'s `density` PROP only reaches
+     * the state it owns; with a caller-supplied state — how all three views share one — a
+     * control that set the prop would render, click, and change nothing.
+     */
+    setDensity(density: Density): void;
+    /** Every edge or only the climbing ones (#167) — what `ViolationsControl` drives. */
+    setShowEdges(value: ShowEdges): void;
+    /** Move the drill path from inside the state — drilling. See `GraphDrill`. */
+    setFocusPath(path: string[]): void;
+    /** Change the grouping axes from inside the component — same reason as `setDensity`. */
+    setGrouping(outer: NodeAxis, inner?: NodeAxis | null): void;
+    get nodes(): unknown[];
+    get edges(): unknown[];
+    get fields(): GraphFields;
+    get layout(): string | LayoutFn;
+    get focus(): string | null;
+    get density(): Density;
+    get arrange(): Arrange;
+    get groupBy(): NodeAxis;
+    get nestBy(): NodeAxis | null;
+    get groupTint(): boolean;
+    get sizeBy(): string;
+    get sizeScale(): "linear" | "log";
+    get depth(): number;
+    get focusPath(): string[];
+    get levels(): number | undefined;
+    get root(): string | null;
+    get bundleTension(): number | undefined;
+    get radialMode(): "tree" | "dendrogram";
+    get edgeStyle(): EdgeStyle;
+    get preset(): GraphPreset;
+    get mode(): "light" | "dark";
+    get label(): string | undefined;
+    get onselect(): ((id: string | null) => void) | undefined;
+    get ondrill(): ((path: string[], node: import("../types.js").GraphNode | null) => void | Promise<void>) | undefined;
+    get ondrillup(): ((path: string[]) => void | Promise<void>) | undefined;
+    get onfocuspath(): ((path: string[]) => void) | undefined;
+    get onexpand(): ((id: string, node: import("../types.js").GraphNode) => void) | undefined;
+    get oncollapse(): ((id: string, node: import("../types.js").GraphNode) => void) | undefined;
+    get showEdges(): ShowEdges;
+    get layerLabels(): string[] | undefined;
+    get widthBy(): string | undefined;
+    get heightBy(): string | undefined;
+    get colorBy(): string | undefined;
+    get above(): string | undefined;
+    get shadeBy(): string | undefined;
+}
+export {};

package/dist/state/GraphConfig.svelte.js

@@ -0,0 +1,253 @@
+import { defaultGraphPreset } from '../preset.js';
+/**
+ * A level cap, or nothing.
+ *
+ * Left UNDEFINED when the caller said nothing: a state-level default of 2 is indistinguishable
+ * from an explicit 2, and `radial` needs "no cap" to mean the whole tree — inventing a number
+ * here silently pruned a codebase dendrogram to two rings.
+ */
+const floorLevels = (levels) => levels === undefined ? undefined : Math.max(1, Math.floor(levels));
+/**
+ * Rejected rather than rendered: a box subdivided by its OWN axis yields exactly one child
+ * containing everything, which reads as a rendering fault, not a no-op.
+ */
+const distinctNest = (inner, outer) => (inner === outer ? null : inner);
+/**
+ * Every input, its default, and how it is shaped. `update()` assigns every field on every call —
+ * an omitted key reverts to its fallback, which is the contract the GraphState specs pin
+ * field by field.
+ */
+export const CONFIG_FIELDS = Object.freeze([
+    { key: 'nodes', fallback: () => [] },
+    { key: 'edges', fallback: () => [] },
+    { key: 'fields', fallback: () => ({}) },
+    { key: 'layout', fallback: () => 'flow' },
+    { key: 'focus', fallback: () => null },
+    { key: 'density', fallback: () => 'keys' },
+    { key: 'arrange', fallback: () => 'untangle' },
+    { key: 'groupBy', fallback: () => 'group' },
+    {
+        key: 'nestBy',
+        fallback: () => null,
+        normalise: (v, config) => distinctNest(v, config.groupBy ?? 'group')
+    },
+    { key: 'groupTint', fallback: () => false },
+    { key: 'sizeBy', fallback: () => 'degree' },
+    { key: 'sizeScale', fallback: () => 'linear' },
+    // Floored at 1: a depth of 0 or -1 is a request for nothing, and returning an empty canvas
+    // for it looks identical to a broken focus.
+    { key: 'depth', fallback: () => 1, normalise: (v) => Math.max(1, Math.floor(v)) },
+    { key: 'focusPath', fallback: () => [] },
+    { key: 'levels', normalise: floorLevels, raw: true },
+    { key: 'root', fallback: () => null },
+    { key: 'bundleTension', raw: true },
+    { key: 'radialMode', fallback: () => 'tree' },
+    { key: 'edgeStyle', fallback: () => 'curved' },
+    { key: 'preset', fallback: () => defaultGraphPreset },
+    { key: 'mode', fallback: () => 'light' },
+    { key: 'label', raw: true },
+    { key: 'onselect', raw: true },
+    { key: 'ondrill', raw: true },
+    { key: 'ondrillup', raw: true },
+    { key: 'onfocuspath', raw: true },
+    { key: 'onexpand', raw: true },
+    { key: 'oncollapse', raw: true },
+    { key: 'showEdges', fallback: () => 'all' },
+    { key: 'layerLabels', raw: true },
+    { key: 'widthBy', raw: true },
+    { key: 'heightBy', raw: true },
+    { key: 'colorBy', raw: true },
+    { key: 'above', raw: true },
+    { key: 'shadeBy', raw: true }
+]);
+function resolve(config) {
+    const values = {};
+    for (const field of CONFIG_FIELDS) {
+        const given = config[field.key];
+        const value = field.raw ? given : (given ?? field.fallback());
+        const { key, normalise } = field;
+        values[key] = normalise ? normalise(value, config) : value;
+    }
+    return values;
+}
+/**
+ * A graph's inputs — the one job `update()` has. The layout pipeline and the selection read
+ * from here.
+ *
+ * `update()` FULLY re-applies config rather than merging deltas, matching `SparkState.update` —
+ * so a prop reverting to undefined actually reverts. `apply()` is the merging verb, for a
+ * component writing the few options its own controls drive into a state someone else owns.
+ */
+export class GraphConfig {
+    #v = $state(resolve({}));
+    /** The last FULL config, so `apply` can merge over it rather than reset around it. */
+    #last = {};
+    constructor(config = {}) {
+        this.update(config);
+    }
+    update(config = {}) {
+        const previous = this.#last;
+        this.#last = config;
+        // Field by field onto the one proxy, not a new object: each field stays its own signal,
+        // so a re-render that leaves `nodes` alone does not re-trigger what reads only `nodes`.
+        //
+        // And only the fields whose INPUT changed. Re-assigning the same array still fires its
+        // signal — the proxy wraps it afresh — and an absent `fields` resolves to a fresh `{}`, so
+        // every update would re-normalise the whole model even when only a layout option moved.
+        // A consumer's own `$state` array mutated in place is unaffected: it is tracked through
+        // its own proxy, not through this assignment.
+        const resolved = resolve(config);
+        const target = this.#v;
+        for (const key of Object.keys(resolved)) {
+            if (key in config && config[key] === previous[key])
+                continue;
+            if (!(key in config) && !(key in previous))
+                continue;
+            target[key] = resolved[key];
+        }
+    }
+    /** Merge a partial config over the last full one, leaving every key it does not name alone. */
+    apply(config) {
+        const merged = { ...this.#last, ...config };
+        this.update(merged);
+        return merged;
+    }
+    /**
+     * Change the detail level from inside the component. `Graph`'s `density` PROP only reaches
+     * the state it owns; with a caller-supplied state — how all three views share one — a
+     * control that set the prop would render, click, and change nothing.
+     */
+    setDensity(density) {
+        this.#v.density = density;
+        this.#remember({ density });
+    }
+    /** Every edge or only the climbing ones (#167) — what `ViolationsControl` drives. */
+    setShowEdges(value) {
+        this.#v.showEdges = value;
+        this.#remember({ showEdges: value });
+    }
+    /** Move the drill path from inside the state — drilling. See `GraphDrill`. */
+    setFocusPath(path) {
+        this.#v.focusPath = path;
+        this.#remember({ focusPath: path });
+    }
+    /** Change the grouping axes from inside the component — same reason as `setDensity`. */
+    setGrouping(outer, inner = null) {
+        this.#v.groupBy = outer;
+        this.#v.nestBy = distinctNest(inner, outer);
+        this.#remember({ groupBy: outer, nestBy: this.#v.nestBy });
+    }
+    /**
+     * Fold a change made from INSIDE into the last full config. `apply()` merges over that, so a
+     * setter that changed only the live value was quietly undone by the next merge — any
+     * component writing its own options put the old drill path, density or grouping back.
+     */
+    #remember(change) {
+        this.#last = { ...this.#last, ...change };
+    }
+    get nodes() {
+        return this.#v.nodes;
+    }
+    get edges() {
+        return this.#v.edges;
+    }
+    get fields() {
+        return this.#v.fields;
+    }
+    get layout() {
+        return this.#v.layout;
+    }
+    get focus() {
+        return this.#v.focus;
+    }
+    get density() {
+        return this.#v.density;
+    }
+    get arrange() {
+        return this.#v.arrange;
+    }
+    get groupBy() {
+        return this.#v.groupBy;
+    }
+    get nestBy() {
+        return this.#v.nestBy;
+    }
+    get groupTint() {
+        return this.#v.groupTint;
+    }
+    get sizeBy() {
+        return this.#v.sizeBy;
+    }
+    get sizeScale() {
+        return this.#v.sizeScale;
+    }
+    get depth() {
+        return this.#v.depth;
+    }
+    get focusPath() {
+        return this.#v.focusPath;
+    }
+    get levels() {
+        return this.#v.levels;
+    }
+    get root() {
+        return this.#v.root;
+    }
+    get bundleTension() {
+        return this.#v.bundleTension;
+    }
+    get radialMode() {
+        return this.#v.radialMode;
+    }
+    get edgeStyle() {
+        return this.#v.edgeStyle;
+    }
+    get preset() {
+        return this.#v.preset;
+    }
+    get mode() {
+        return this.#v.mode;
+    }
+    get label() {
+        return this.#v.label;
+    }
+    get onselect() {
+        return this.#v.onselect;
+    }
+    get ondrill() {
+        return this.#v.ondrill;
+    }
+    get ondrillup() {
+        return this.#v.ondrillup;
+    }
+    get onfocuspath() {
+        return this.#v.onfocuspath;
+    }
+    get onexpand() {
+        return this.#v.onexpand;
+    }
+    get oncollapse() {
+        return this.#v.oncollapse;
+    }
+    get showEdges() {
+        return this.#v.showEdges;
+    }
+    get layerLabels() {
+        return this.#v.layerLabels;
+    }
+    get widthBy() {
+        return this.#v.widthBy;
+    }
+    get heightBy() {
+        return this.#v.heightBy;
+    }
+    get colorBy() {
+        return this.#v.colorBy;
+    }
+    get above() {
+        return this.#v.above;
+    }
+    get shadeBy() {
+        return this.#v.shadeBy;
+    }
+}

package/dist/state/GraphDrill.svelte.d.ts

@@ -0,0 +1,52 @@
+import type { Cluster } from '../layout/types.js';
+import type { GraphModel } from '../types.js';
+import type { GraphConfig } from './GraphConfig.svelte.js';
+export type Breadcrumb = {
+    /** The drill path this crumb returns to. `[]` is the root. */
+    path: string[];
+    /** The segment's name; null for the root, which the view names (`All`, a title…). */
+    label: string | null;
+    /** Where the reader is now — the last crumb, which is shown but not a way back. */
+    current: boolean;
+};
+type Sources = {
+    config: GraphConfig;
+    model: () => GraphModel;
+    /** The layout's registry key, or 'custom'. */
+    layoutName: () => string;
+};
+/**
+ * Drilling: moving `focusPath` — which containment subtree is the whole canvas — and telling the
+ * host, who may have to FETCH that level (#165). docs/design/24-world-view.md, Decision 3.
+ *
+ * Drilling changes scope; it never selects. Only a layout that declares `focusPath` drills — a
+ * custom LayoutFn might ignore it, and a no-op gesture is worse than none.
+ *
+ * A handler may return a promise: the state is `pending` until it settles, only the LATEST
+ * drill's settlement counts (an older load finishing late changes nothing), and a rejection —
+ * or a handler that throws — restores the previous path and exposes the error, because an
+ * empty canvas would read as a broken level rather than a failed load.
+ */
+export declare class GraphDrill {
+    #private;
+    constructor(sources: Sources);
+    get path(): string[];
+    get breadcrumbs(): Breadcrumb[];
+    get pending(): boolean;
+    /** Why the last drill failed, until the next drill. */
+    get error(): unknown;
+    /** Whether the active layout drills at all. */
+    get enabled(): boolean;
+    /**
+     * Whether a box can be opened: in a drilling layout, with an address (a pathless box has
+     * none), not already the canvas, and with something below it — in the data, or behind the
+     * host's loader.
+     */
+    canDrill(box: Cluster): boolean;
+    drillInto(box: Cluster): boolean;
+    /** Climb `levels` toward the root. False (and silent) when already there. */
+    drillOut(levels?: number): boolean;
+    /** Return to an ancestor — what a breadcrumb does. False for anything that is not one. */
+    drillTo(path: string[]): boolean;
+}
+export {};

package/dist/state/GraphDrill.svelte.js

@@ -0,0 +1,115 @@
+import { LAYOUT_OPTIONS } from '../layout/options.js';
+const isPrefix = (prefix, path) => prefix.length <= path.length && prefix.every((segment, i) => path[i] === segment);
+const isThenable = (value) => value !== null && typeof value === 'object' && typeof value.then === 'function';
+/**
+ * Drilling: moving `focusPath` — which containment subtree is the whole canvas — and telling the
+ * host, who may have to FETCH that level (#165). docs/design/24-world-view.md, Decision 3.
+ *
+ * Drilling changes scope; it never selects. Only a layout that declares `focusPath` drills — a
+ * custom LayoutFn might ignore it, and a no-op gesture is worse than none.
+ *
+ * A handler may return a promise: the state is `pending` until it settles, only the LATEST
+ * drill's settlement counts (an older load finishing late changes nothing), and a rejection —
+ * or a handler that throws — restores the previous path and exposes the error, because an
+ * empty canvas would read as a broken level rather than a failed load.
+ */
+export class GraphDrill {
+    #sources;
+    #pending = $state(false);
+    #error = $state(null);
+    /** Bumped by every drill; a settlement for an older token is ignored. */
+    #token = 0;
+    constructor(sources) {
+        this.#sources = sources;
+    }
+    get path() {
+        return this.#sources.config.focusPath;
+    }
+    get breadcrumbs() {
+        const path = this.path;
+        return [
+            { path: [], label: null, current: path.length === 0 },
+            ...path.map((segment, i) => ({
+                path: path.slice(0, i + 1),
+                label: segment,
+                current: i === path.length - 1
+            }))
+        ];
+    }
+    get pending() {
+        return this.#pending;
+    }
+    /** Why the last drill failed, until the next drill. */
+    get error() {
+        return this.#error;
+    }
+    /** Whether the active layout drills at all. */
+    get enabled() {
+        return LAYOUT_OPTIONS[this.#sources.layoutName()]?.includes('focusPath') === true;
+    }
+    /**
+     * Whether a box can be opened: in a drilling layout, with an address (a pathless box has
+     * none), not already the canvas, and with something below it — in the data, or behind the
+     * host's loader.
+     */
+    canDrill(box) {
+        const path = box.path ?? [];
+        if (!this.enabled || path.length === 0 || isPrefix(path, this.path))
+            return false;
+        return !box.leaf || this.#sources.config.ondrill !== undefined;
+    }
+    drillInto(box) {
+        if (!this.canDrill(box))
+            return false;
+        const path = box.path;
+        const node = box.declared ? (this.#sources.model().byId.get(box.declared) ?? null) : null;
+        this.#move(path, () => this.#sources.config.ondrill?.(path, node));
+        return true;
+    }
+    /** Climb `levels` toward the root. False (and silent) when already there. */
+    drillOut(levels = 1) {
+        if (this.path.length === 0)
+            return false;
+        return this.drillTo(this.path.slice(0, Math.max(0, this.path.length - levels)));
+    }
+    /** Return to an ancestor — what a breadcrumb does. False for anything that is not one. */
+    drillTo(path) {
+        if (path.length >= this.path.length || !isPrefix(path, this.path))
+            return false;
+        this.#move(path, () => this.#sources.config.ondrillup?.(path));
+        return true;
+    }
+    #move(path, fire) {
+        const previous = this.path;
+        const token = ++this.#token;
+        this.#pending = false;
+        this.#error = null;
+        this.#setPath(path);
+        const fail = (error) => {
+            if (token !== this.#token)
+                return;
+            this.#pending = false;
+            this.#error = error;
+            this.#setPath(previous);
+        };
+        let result;
+        try {
+            result = fire();
+        }
+        catch (error) {
+            fail(error);
+            return;
+        }
+        if (!isThenable(result))
+            return;
+        this.#pending = true;
+        result.then(() => {
+            if (token === this.#token)
+                this.#pending = false;
+        }, fail);
+    }
+    #setPath(path) {
+        this.#sources.config.setFocusPath(path);
+        this.#sources.config.onfocuspath?.(path);
+    }
+}

package/dist/state/GraphGroups.svelte.d.ts

@@ -0,0 +1,35 @@
+import type { GraphModel } from '../types.js';
+import type { GraphConfig } from './GraphConfig.svelte.js';
+/** What a drill bar can offer for the selection: open its group, or fold its group back. */
+export type GroupAction = {
+    kind: 'expand' | 'collapse';
+    group: string;
+    label: string;
+};
+type Sources = {
+    /** The CANONICAL model — before condensation, so every group and member is visible here. */
+    model: () => GraphModel;
+    config: GraphConfig;
+};
+/**
+ * Which groups are collapsed (#166). A group starts as its node says (`collapsed`, default
+ * true — a node with members is a group to fold); the reader toggles from there. The state
+ * condenses the model through `collapsed` before any layout sees it.
+ */
+export declare class GraphGroups {
+    #private;
+    constructor(sources: Sources);
+    /** The collapsed group ids — what condensation reads. */
+    get collapsed(): Set<string>;
+    isGroup(id: string): boolean;
+    isCollapsed(id: string): boolean;
+    /** How many members the group names — loaded or not, since the host may send them later. */
+    memberCount(id: string): number;
+    /** The EXPANDED group a node belongs to, or null — what a member collapses back into. */
+    groupOf(id: string): string | null;
+    /** Flip a group. False for a node that is not one. Tells the host either way it went. */
+    toggle(id: string): boolean;
+    /** The selection's group action, or null when it is neither a collapsed group nor a member. */
+    actionFor(selected: string | null): GroupAction | null;
+}
+export {};

package/dist/state/GraphGroups.svelte.js

@@ -0,0 +1,73 @@
+import { SvelteSet } from 'svelte/reactivity';
+import { groupsOf } from '../model/condense.js';
+/**
+ * Which groups are collapsed (#166). A group starts as its node says (`collapsed`, default
+ * true — a node with members is a group to fold); the reader toggles from there. The state
+ * condenses the model through `collapsed` before any layout sees it.
+ */
+export class GraphGroups {
+    #sources;
+    /** Groups the reader flipped from their starting state. */
+    #toggled = new SvelteSet();
+    #groups;
+    #collapsed;
+    constructor(sources) {
+        this.#sources = sources;
+        this.#groups = $derived(groupsOf(sources.model()));
+        // A SvelteSet, as GraphSelection's `related` is: the house shape for a derived id set.
+        this.#collapsed = $derived(new SvelteSet([...this.#groups.keys()].filter((id) => this.#startsCollapsed(id) !== this.#toggled.has(id))));
+    }
+    #node(id) {
+        return this.#sources.model().byId.get(id);
+    }
+    #startsCollapsed(id) {
+        return this.#node(id)?.collapsed ?? true;
+    }
+    /** The collapsed group ids — what condensation reads. */
+    get collapsed() {
+        return this.#collapsed;
+    }
+    isGroup(id) {
+        return this.#groups.has(id);
+    }
+    isCollapsed(id) {
+        return this.#collapsed.has(id);
+    }
+    /** How many members the group names — loaded or not, since the host may send them later. */
+    memberCount(id) {
+        return this.#node(id)?.members?.length ?? 0;
+    }
+    /** The EXPANDED group a node belongs to, or null — what a member collapses back into. */
+    groupOf(id) {
+        for (const [group, members] of this.#groups) {
+            if (!this.#collapsed.has(group) && members.includes(id))
+                return group;
+        }
+        return null;
+    }
+    /** Flip a group. False for a node that is not one. Tells the host either way it went. */
+    toggle(id) {
+        const node = this.#node(id);
+        if (!node || !this.isGroup(id))
+            return false;
+        const expanding = this.isCollapsed(id);
+        if (this.#toggled.has(id))
+            this.#toggled.delete(id);
+        else
+            this.#toggled.add(id);
+        const { onexpand, oncollapse } = this.#sources.config;
+        (expanding ? onexpand : oncollapse)?.(id, node);
+        return true;
+    }
+    /** The selection's group action, or null when it is neither a collapsed group nor a member. */
+    actionFor(selected) {
+        if (!selected)
+            return null;
+        const label = (group) => this.#node(group)?.label ?? group;
+        if (this.isGroup(selected) && this.isCollapsed(selected)) {
+            return { kind: 'expand', group: selected, label: label(selected) };
+        }
+        const group = this.groupOf(selected);
+        return group ? { kind: 'collapse', group, label: label(group) } : null;
+    }
+}