@rokkit/graph 1.8.0 → 1.8.1

package/dist/GraphState.svelte.d.ts

@@ -1,26 +1,18 @@
 import { SvelteSet } from 'svelte/reactivity';
 import type { GraphPreset } from './preset.js';
-import type { Arrange, Cards, Cluster, Column, Density, EdgeStyle, LayoutFn, NodeAxis, RoutedEdge, Size } from './layout/types.js';
+import type { Arrange, Cards, Cluster, Column, Density, EdgeStyle, LayoutFn, NodeAxis, RoutedEdge, ShowEdges, Size, LayoutResult } from './layout/types.js';
 import type { GraphEdge, GraphFields, GraphModel, GraphNode } from './types.js';
-export type EntityRow = {
-    id: string;
-    label: string;
-    group?: string;
-    kind?: string;
-    rowCount: number;
-    refCount: number;
-    note?: string;
-};
-export type Relationship = {
-    direction: 'in' | 'out';
-    id: string;
-    label: string;
-    group?: string;
-    /** The canonical edge — always present. A relationship is a fact about the model. */
-    edge: GraphEdge;
-    /** Routed geometry, present only when the ACTIVE layout placed this edge. */
-    routed?: RoutedEdge;
-};
+import type { Relationship } from './model/relationships.js';
+import type { EntityRow } from './model/entities.js';
+import { GraphConfig } from './state/GraphConfig.svelte.js';
+import { GraphSelection } from './state/GraphSelection.svelte.js';
+import { GraphDrill } from './state/GraphDrill.svelte.js';
+import { GraphGroups } from './state/GraphGroups.svelte.js';
+import type { GroupAction } from './state/GraphGroups.svelte.js';
+import type { Intent } from './state/intents.js';
+import type { ChannelRow } from './state/text.js';
+import type { Breadcrumb } from './state/GraphDrill.svelte.js';
+export type { Relationship, EntityRow, Breadcrumb, GroupAction };
 export type GraphStateConfig = {
     nodes?: unknown[];
     edges?: unknown[];
@@ -66,9 +58,66 @@ export type GraphStateConfig = {
     mode?: 'light' | 'dark';
     label?: string;
     onselect?: (id: string | null) => void;
+    /**
+     * The reader drilled INTO a box: `path` is the new `focusPath`, `node` the declared node at
+     * it (null for a container nothing declared). Return a promise to show a pending state
+     * until the level's data arrives; a rejection restores the previous level. Distinct from
+     * `onselect` — drilling changes scope, it does not select.
+     */
+    ondrill?: (path: string[], node: GraphNode | null) => void | Promise<void>;
+    /** The reader drilled OUT; `path` is the new, shorter `focusPath`. Same promise contract. */
+    ondrillup?: (path: string[]) => void | Promise<void>;
+    /**
+     * Every internal change of `focusPath` — drill in, out, or a rollback after a failed load.
+     * For a component that owns a bindable `focusPath` prop, so its next `update()` agrees.
+     */
+    onfocuspath?: (path: string[]) => void;
+    /**
+     * The reader expanded a group (#166). With its members already in `nodes` they appear at
+     * once; a host that sends only the group can load them in answer.
+     */
+    onexpand?: (id: string, node: GraphNode) => void;
+    /** The reader collapsed a group back into one node. */
+    oncollapse?: (id: string, node: GraphNode) => void;
+    /**
+     * Every edge (the default), or only the ones the view is about: `violations` in `layers`
+     * (#167), `hidden` in `arcs` (#169).
+     */
+    showEdges?: ShowEdges;
+    /** `layers` only — band names by layer index. */
+    layerLabels?: string[];
+    /** `polymetric` only — the measures box width, height and shade encode (#168). */
+    widthBy?: string;
+    heightBy?: string;
+    colorBy?: string;
+    /** `arcs` only — the relation drawn on the right of the axis (#169). */
+    above?: string;
+    /** `world` / `sunburst` — the measure (a 0..1 share) each box is shaded by (#164). */
+    shadeBy?: string;
 };
+/**
+ * The store. Turns raw `nodes`/`edges`/`fields` into the reactive shape the visuals
+ * render, and owns every transition.
+ *
+ * Components read from this and call its methods — they never compute. That is what
+ * lets the geometry, badge derivation and selection logic be covered exhaustively
+ * with no DOM, and lets the component specs assert only attributes.
+ *
+ * A composition: `config` (every input, `state/GraphConfig`) feeds the layout pipeline
+ * derived here; the selection and the view queries read both. `update()` FULLY re-applies
+ * config rather than merging deltas — so a prop reverting to undefined actually reverts;
+ * `apply()` merges.
+ */
 export declare class GraphState {
     #private;
+    /** Every input — see `CONFIG_FIELDS` for what each omitted key falls back to. */
+    readonly config: GraphConfig;
+    /** Which subtree is the canvas, and the host events for moving it (#165). */
+    readonly drill: GraphDrill;
+    /** What the reader picked and opened. */
+    readonly selection: GraphSelection;
+    /** Which groups are collapsed (#166). */
+    readonly groups: GraphGroups;
     constructor(config?: GraphStateConfig);
     /**
      * Fully re-applies config. Safe to call on every prop change.
@@ -88,27 +137,41 @@ export declare class GraphState {
      */
     apply(config: Partial<GraphStateConfig>): void;
     select(id: string): void;
+    /** Drop the selection and report `null` — see `GraphSelection.clear`. */
+    clear(): void;
+    /** Show one node's rows in full, whatever the density says — see `GraphSelection`. */
+    toggleExpanded(id: string): void;
+    isExpanded(id: string): boolean;
+    isGroup(id: string): boolean;
+    isCollapsed(id: string): boolean;
+    memberCount(id: string): number;
+    groupOf(id: string): string | null;
     /**
-     * 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.
+     * Expand or collapse a group. Collapsing one whose member is selected moves the selection to
+     * the group: the thing being looked at is now inside it, and a selection naming a hidden node
+     * would leave the entity panel empty for no visible reason.
      */
-    clear(): void;
+    toggleGroup(id: string): boolean;
+    /** The selection's group action — what a drill bar offers. */
+    get groupAction(): GroupAction | null;
+    get drillPath(): string[];
+    get breadcrumbs(): Breadcrumb[];
+    /** A drill's handler returned a promise that has not settled. */
+    get pending(): boolean;
+    get drillError(): unknown;
+    canDrill(box: Cluster): boolean;
+    drillInto(box: Cluster): boolean;
+    drillOut(levels?: number): boolean;
+    drillTo(path: string[]): boolean;
     /**
-     * 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.
+     * The selected box, when it can be opened — what a drill bar's "Open" acts on. The keyboard
+     * route into a leaf: Enter selects it, and this is the next step.
      */
-    toggleExpanded(id: string): void;
-    isExpanded(id: string): boolean;
+    /** The failed drill, worded for the reader; null when the last drill did not fail. */
+    get drillErrorText(): string | null;
+    get drillTarget(): Cluster | null;
+    /** Whether a drill bar has anything to show: a trail, a load, a failure, or a box to open. */
+    get showsDrillBar(): boolean;
     /**
      * The more-row's text, or null when the card is hiding nothing and needs no control.
      *
@@ -130,17 +193,24 @@ export declare class GraphState {
      * prop would render, click, and change nothing.
      */
     setDensity(density: Density): void;
+    /** Every edge or only the climbing ones — what `ViolationsControl` drives (#167). */
+    setShowEdges(value: ShowEdges): void;
+    get showEdges(): ShowEdges;
     nodeState(id: string): 'selected' | 'related' | 'dim' | null;
     edgeState(edge: RoutedEdge): 'highlight' | 'dim' | null;
     edgePath(edge: RoutedEdge): string;
     groupStyle(group: string | undefined): Record<string, string>;
     /**
-     * The same style as a `style=` attribute string.
-     *
-     * A template cannot spread an object into `style`, so something has to serialise it.
-     * Doing that inline put the same map/join in two places in `Graph.svelte` — a derivation
-     * living in a component, which is the one thing this layer exists to prevent.
+     * A box's paint as a style attribute: the shade ramp's step for its share when shading
+     * (#164), else its group's colour. Custom properties, so a theme still has the last word.
      */
+    boxStyleAttr(cluster: Cluster): string;
+    /** What a legend says about the shade: the measure and the ramp's two ends, or null. */
+    get shadeLegend(): {
+        measure: string;
+        low: string;
+        high: string;
+    } | null;
     groupStyleAttr(group: string | undefined): string;
     get model(): GraphModel;
     /**
@@ -160,7 +230,8 @@ export declare class GraphState {
     get overlayEdges(): GraphEdge[];
     /**
      * An edge's weight as 0..1 of the heaviest weighted edge, for stroke width — or undefined
-     * for an edge with no weight, which draws at the theme's normal width.
+     * for an edge with no weight, which draws at the theme's normal width. A layout's own
+     * per-set `strength` wins.
      */
     edgeWeight(edge: RoutedEdge): number | undefined;
     get size(): Size;
@@ -190,14 +261,6 @@ export declare class GraphState {
     get unplacedEdges(): GraphEdge[];
     get density(): Density;
     get arrange(): Arrange;
-    /**
-     * A cluster's unique render key.
-     *
-     * NOT the name: nesting puts a `table` box under `public` AND under `billing`, and keying
-     * an `{#each}` by name alone is a duplicate key — Svelte throws `each_key_duplicate`, the
-     * render aborts, and no inner box appears at all, which reads as nesting silently not
-     * working rather than as an error.
-     */
     /**
      * The SVG path for a wedge-shaped box, centred on the canvas.
      *
@@ -212,7 +275,53 @@ export declare class GraphState {
      * differ only in the element and its role, which is exactly the difference that matters.
      */
     boxAttrs(cluster: Cluster): Record<string, string | null | undefined>;
+    /** Whether a box takes the pointer and the keyboard: it has an intent. */
+    interactive(cluster: Cluster): boolean;
+    /** A box's visible caption: its name, and the layout's caption or its count. */
+    caption(cluster: Cluster): string;
+    /**
+     * A node card's hooks and intents: it selects on press, and folds or opens its group on open
+     * (#166). A card with nothing below its head — no rows shown, none to reveal, not a group —
+     * is marked head-only so the theme can drop the empty body.
+     */
+    cardAttrs(key: string): Record<string, string | undefined>;
+    /** What a card's head counts: a group, the members it stands for; anything else, its rows. */
+    cardCount(key: string): number;
+    /** The "more rows" control's hooks: it expands the card, and says when a filter emptied it. */
+    moreAttrs(key: string): Record<string, string | undefined>;
+    /**
+     * The box a `data-graph-key` names, if it is on the canvas: a container by its render key,
+     * a leaf by its node id — the one key a leaf carries for both its press and its open.
+     */
+    boxFor(key: string): Cluster | undefined;
+    /**
+     * Perform an intent read off the DOM (see `state/intents`). An unknown intent, or a key
+     * that names nothing, does nothing — the DOM is not a trusted source.
+     */
+    act(intent: Intent, key: string | null): void;
+    /**
+     * A cluster's unique render key.
+     *
+     * NOT the name: nesting puts a `table` box under `public` AND under `billing`, and keying
+     * an `{#each}` by name alone is a duplicate key — Svelte throws `each_key_duplicate`, the
+     * render aborts, and no inner box appears at all, which reads as nesting silently not
+     * working rather than as an error.
+     */
     clusterKey(cluster: Cluster): string;
+    /** `polymetric` — which measure is on which channel, and each one's cap; for the legend. */
+    get channels(): LayoutResult['channels'];
+    /** The polymetric legend's rows, labelled from the locale (#168). */
+    get channelRows(): ChannelRow[];
+    /** What each side of an arc diagram shows, named from the data or the locale (#169). */
+    get sideNames(): {
+        below: string;
+        above: string;
+    };
+    /**
+     * Every measure a channel could bind: the keys in the nodes' `measures`, plus `weight` and
+     * `degree`, which every node has an answer for. Sorted, so a picker does not reshuffle.
+     */
+    get measureKeys(): string[];
     get groupBy(): NodeAxis;
     /**
      * The node kinds actually present, sorted.
@@ -231,9 +340,9 @@ export declare class GraphState {
     get relationsPresent(): string[];
     /** The group names present, sorted. Same reasoning as `kindsPresent`. */
     get groupsPresent(): string[];
-    /** Whether cards carry the group ramp themselves. See `GraphStateConfig.groupTint`. */
     /** `dot` or `card` — what the active layout draws a node as. */
     get nodeShape(): 'dot' | 'card';
+    /** Whether cards carry the group ramp themselves. See `GraphStateConfig.groupTint`. */
     get groupTint(): boolean;
     get nestBy(): NodeAxis | null;
     get sizeBy(): string;