@rokkit/graph 1.8.0 → 1.8.2

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;
+    }
+}

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

@@ -0,0 +1,53 @@
+import { SvelteSet } from 'svelte/reactivity';
+import type { Relationship } from '../model/relationships.js';
+import type { RoutedEdge } from '../layout/types.js';
+import type { GraphModel, GraphNode } from '../types.js';
+type Sources = {
+    /** The canonical model. */
+    model: () => GraphModel;
+    /** The structural edges the active layout routed — geometry for relationships. */
+    routedEdges: () => RoutedEdge[];
+    /** The consumer's selection callback, read at call time (it is config, and can change). */
+    onselect: () => ((id: string | null) => void) | undefined;
+};
+/**
+ * What the reader has picked and opened: the selected node, what it touches, and which cards
+ * are expanded — plus the transitions that change them.
+ */
+export declare class GraphSelection {
+    #private;
+    constructor(sources: Sources);
+    get value(): string | null;
+    get related(): SvelteSet<string>;
+    get entity(): GraphNode | null;
+    get relationships(): Relationship[];
+    /** Take a value the CALLER supplied — no callback, it already knows. */
+    adopt(id: string | null): void;
+    select(id: string): void;
+    /**
+     * Drop the selection, and SAY SO.
+     *
+     * Found by dbd consuming the package: it owns `selected` in its route and branches on it
+     * to show the entity panel, so a silent clear left that panel open over nothing. A
+     * controlled consumer cannot observe an internal value — the callback is the only
+     * channel, which is why it carries `null` rather than being skipped.
+     *
+     * Guarded on an actual change, or a background click on an already-empty canvas
+     * round-trips through the consumer's setter on every stray click.
+     */
+    clear(): void;
+    /**
+     * Show one node's rows in full, whatever the density says.
+     *
+     * Per NODE rather than a global density change: a reader who clicks "+3 more" on one
+     * card is asking about that card, and expanding all of them answers a question they did
+     * not ask — on a large diagram it also relayouts everything under them.
+     */
+    toggleExpanded(id: string): void;
+    isExpanded(id: string): boolean;
+    /** The set the layouts read to size expanded cards. */
+    get expanded(): SvelteSet<string>;
+    nodeState(id: string): 'selected' | 'related' | 'dim' | null;
+    edgeState(edge: RoutedEdge): 'highlight' | 'dim' | null;
+}
+export {};

package/dist/state/GraphSelection.svelte.js

@@ -0,0 +1,94 @@
+import { SvelteSet } from 'svelte/reactivity';
+import { relationshipsOf } from '../model/relationships.js';
+/**
+ * What the reader has picked and opened: the selected node, what it touches, and which cards
+ * are expanded — plus the transitions that change them.
+ */
+export class GraphSelection {
+    #sources;
+    #value = $state(null);
+    #expanded = new SvelteSet();
+    #related;
+    #entity;
+    /** From the canonical model, not the layout's filtered edges — see `relationshipsOf`. */
+    #relationships;
+    constructor(sources) {
+        this.#sources = sources;
+        // Derived in the constructor, after `#sources` exists — a field initializer would read
+        // it before it is assigned.
+        this.#related = $derived(this.#value
+            ? new SvelteSet(sources.model().neighbors.get(this.#value) ?? [])
+            : new SvelteSet());
+        this.#entity = $derived(this.#value ? (sources.model().byId.get(this.#value) ?? null) : null);
+        this.#relationships = $derived(relationshipsOf(sources.model(), this.#value, sources.routedEdges()));
+    }
+    get value() {
+        return this.#value;
+    }
+    get related() {
+        return this.#related;
+    }
+    get entity() {
+        return this.#entity;
+    }
+    get relationships() {
+        return this.#relationships;
+    }
+    /** Take a value the CALLER supplied — no callback, it already knows. */
+    adopt(id) {
+        this.#value = id;
+    }
+    select(id) {
+        this.#value = id;
+        this.#sources.onselect()?.(id);
+    }
+    /**
+     * Drop the selection, and SAY SO.
+     *
+     * Found by dbd consuming the package: it owns `selected` in its route and branches on it
+     * to show the entity panel, so a silent clear left that panel open over nothing. A
+     * controlled consumer cannot observe an internal value — the callback is the only
+     * channel, which is why it carries `null` rather than being skipped.
+     *
+     * Guarded on an actual change, or a background click on an already-empty canvas
+     * round-trips through the consumer's setter on every stray click.
+     */
+    clear() {
+        if (this.#value === null)
+            return;
+        this.#value = null;
+        this.#sources.onselect()?.(null);
+    }
+    /**
+     * Show one node's rows in full, whatever the density says.
+     *
+     * Per NODE rather than a global density change: a reader who clicks "+3 more" on one
+     * card is asking about that card, and expanding all of them answers a question they did
+     * not ask — on a large diagram it also relayouts everything under them.
+     */
+    toggleExpanded(id) {
+        if (this.#expanded.has(id))
+            this.#expanded.delete(id);
+        else
+            this.#expanded.add(id);
+    }
+    isExpanded(id) {
+        return this.#expanded.has(id);
+    }
+    /** The set the layouts read to size expanded cards. */
+    get expanded() {
+        return this.#expanded;
+    }
+    nodeState(id) {
+        if (!this.#value)
+            return null;
+        if (id === this.#value)
+            return 'selected';
+        return this.#related.has(id) ? 'related' : 'dim';
+    }
+    edgeState(edge) {
+        if (!this.#value)
+            return null;
+        return edge.fromKey === this.#value || edge.toKey === this.#value ? 'highlight' : 'dim';
+    }
+}

package/dist/state/intents.d.ts

@@ -0,0 +1,33 @@
+/**
+ * What a press or a double-click on the graph does, as data.
+ *
+ * The state writes an intent onto each element (`data-graph-press`, `data-graph-open`, with
+ * `data-graph-key`); the `interactions` action reads it back and calls `GraphState.act`, which
+ * looks it up here. So the meaning of a click lives in one table — not in a handler on every
+ * element — and each entry is testable on a bare state.
+ */
+import type { Breadcrumb } from './GraphDrill.svelte.js';
+import type { GroupAction } from './GraphGroups.svelte.js';
+import type { Cluster } from '../layout/types.js';
+export type Intent = 'select' | 'toggle' | 'drill' | 'group' | 'expand' | 'crumb' | 'open-selected' | 'group-selected' | 'clear';
+/** What an intent may call — the slice of `GraphState` the table needs. */
+export type Actor = {
+    select(id: string): void;
+    clear(): void;
+    readonly value: string | null;
+    drillInto(cluster: Cluster): unknown;
+    drillTo(path: string[]): unknown;
+    toggleGroup(id: string): void;
+    toggleExpanded(id: string): void;
+    isGroup(id: string): boolean;
+    groupOf(id: string): string | null;
+    boxFor(key: string): Cluster | undefined;
+    readonly breadcrumbs: Breadcrumb[];
+    readonly drillTarget: Cluster | null;
+    readonly groupAction: GroupAction | null;
+};
+type Perform = (graph: Actor, key: string) => void;
+export declare const INTENTS: Record<Intent, Perform>;
+/** Whether `value` names an intent — the action reads it from the DOM, where anything goes. */
+export declare const isIntent: (value: string | null | undefined) => value is Intent;
+export {};

package/dist/state/intents.js

@@ -0,0 +1,30 @@
+/** A group toggles itself; a member of an open group folds that group back. */
+const groupFor = (graph, key) => (graph.isGroup(key) ? key : (graph.groupOf(key) ?? key));
+export const INTENTS = {
+    select: (graph, key) => graph.select(key),
+    /** Select, or clear when it is already the selection — a matrix row's press. */
+    toggle: (graph, key) => (graph.value === key ? graph.clear() : graph.select(key)),
+    drill: (graph, key) => {
+        const cluster = graph.boxFor(key);
+        if (cluster)
+            graph.drillInto(cluster);
+    },
+    group: (graph, key) => graph.toggleGroup(groupFor(graph, key)),
+    expand: (graph, key) => graph.toggleExpanded(key),
+    crumb: (graph, key) => {
+        const crumb = graph.breadcrumbs[Number(key)];
+        if (crumb)
+            graph.drillTo(crumb.path);
+    },
+    'open-selected': (graph) => {
+        if (graph.drillTarget)
+            graph.drillInto(graph.drillTarget);
+    },
+    'group-selected': (graph) => {
+        if (graph.groupAction)
+            graph.toggleGroup(graph.groupAction.group);
+    },
+    clear: (graph) => graph.clear()
+};
+/** Whether `value` names an intent — the action reads it from the DOM, where anything goes. */
+export const isIntent = (value) => value !== null && value !== undefined && Object.hasOwn(INTENTS, value);

package/dist/state/text.d.ts

@@ -0,0 +1,28 @@
+import type { Card, ChannelScale, Density, LayoutResult, PolymetricChannel } from '../layout/types.js';
+import type { GraphEdge } from '../types.js';
+/** The default accessible name: what the diagram holds. */
+export declare function diagramLabel(nodes: number, edges: number): string;
+/**
+ * The "more rows" control on a card: `show less` when expanded, `+ N more` when rows are
+ * hidden, and `no keys · N rows` when a key filter matched nothing (see `GraphState.moreLabel`).
+ */
+export declare function moreRowsLabel(expanded: boolean, card: Pick<Card, 'more' | 'vis'> | undefined, density: Density): string | null;
+export type ChannelRow = {
+    key: PolymetricChannel;
+    label: string;
+    scale: ChannelScale;
+};
+/** One legend row per polymetric channel present, labelled from the locale (#168). */
+export declare function channelRows(channels: LayoutResult['channels']): ChannelRow[];
+/**
+ * What each side of an arc diagram shows (#169): the relations drawn there, from the data, or
+ * Declared / Observed from the locale when a side's edges name none.
+ */
+export declare function sideNames(edges: GraphEdge[], above: string | undefined): {
+    below: string;
+    above: string;
+};
+/** What a failed drill says: the error's own message, in the locale's sentence. */
+export declare function drillErrorText(error: unknown): string | null;
+/** Underscores are the WIRE format (dbd sends `materialized_view`), not something to read. */
+export declare const readable: (value: string) => string;

package/dist/state/text.js

@@ -0,0 +1,56 @@
+/**
+ * The words the state produces, from `messages.graph` (see `messages.ts`). Pure functions of
+ * their inputs and the active locale, so the canvas has no English of its own and each is
+ * testable without a renderer.
+ */
+import { counted, say } from '../messages.js';
+import { sideOf } from '../layout/arcs.js';
+/** The default accessible name: what the diagram holds. */
+export function diagramLabel(nodes, edges) {
+    return say('diagram', {
+        nodes: counted(nodes, 'nodeOne', 'nodeMany'),
+        edges: counted(edges, 'relationshipOne', 'relationshipMany')
+    });
+}
+/**
+ * The "more rows" control on a card: `show less` when expanded, `+ N more` when rows are
+ * hidden, and `no keys · N rows` when a key filter matched nothing (see `GraphState.moreLabel`).
+ */
+export function moreRowsLabel(expanded, card, density) {
+    if (expanded)
+        return say('less');
+    if (!card || card.more <= 0)
+        return null;
+    // Only `keys` filters rows by a property — at `names` an empty card is what was asked for.
+    if (density !== 'keys' || card.vis.length > 0)
+        return say('more', { n: card.more });
+    return say('noKeys', { rows: counted(card.more, 'rowOne', 'rowMany') });
+}
+const CHANNEL_LABEL = { width: 'width', height: 'height', color: 'shade' };
+/** One legend row per polymetric channel present, labelled from the locale (#168). */
+export function channelRows(channels) {
+    if (!channels)
+        return [];
+    const keys = channels.color ? ['width', 'height', 'color'] : ['width', 'height'];
+    return keys.map((key) => ({ key, label: say(CHANNEL_LABEL[key]), scale: channels[key] }));
+}
+/**
+ * What each side of an arc diagram shows (#169): the relations drawn there, from the data, or
+ * Declared / Observed from the locale when a side's edges name none.
+ */
+export function sideNames(edges, above) {
+    const named = { below: new Set(), above: new Set() };
+    for (const edge of edges)
+        if (edge.relation)
+            named[sideOf(edge, above)].add(edge.relation);
+    const name = (side, fallback) => named[side].size > 0 ? [...named[side]].join(' · ') : say(fallback);
+    return { below: name('below', 'sideBelow'), above: name('above', 'sideAbove') };
+}
+/** What a failed drill says: the error's own message, in the locale's sentence. */
+export function drillErrorText(error) {
+    if (error === null || error === undefined)
+        return null;
+    return say('drillError', { message: error instanceof Error ? error.message : String(error) });
+}
+/** Underscores are the WIRE format (dbd sends `materialized_view`), not something to read. */
+export const readable = (value) => value.replace(/_/g, ' ');