@rokkit/graph 1.6.0

package/dist/types.d.ts

@@ -0,0 +1,160 @@
+/** A flag rendered as a badge on a node row. */
+export type RowBadge = 'pk' | 'fk' | 'uq' | 'nn';
+/** One row inside a node — a column, a parameter, a field. */
+export type GraphRow = {
+    name: string;
+    type?: string;
+    badges: RowBadge[];
+    note?: string;
+};
+/**
+ * Whether an edge expresses a data reference (a foreign key) or a dependency
+ * (a view reading a table, a procedure calling a function). Layouts branch on
+ * this rather than on any schema-specific notion.
+ */
+export type EdgeKind = 'reference' | 'dependency';
+export type GraphNode = {
+    /** Stable key. `${group}.${label}` when a group is present, else `label`. */
+    id: string;
+    label: string;
+    /** Open vocabulary — a schema name. Drives cluster grouping and group colour. */
+    group?: string;
+    /** Closed vocabulary — table | view | matview | function | procedure | enum. */
+    kind?: string;
+    rows: GraphRow[];
+    note?: string;
+    /** Source fields the map did not claim, passed through untouched. */
+    meta: Record<string, unknown>;
+};
+export type GraphEdge = {
+    id: string;
+    /** GraphNode.id */
+    source: string;
+    /** GraphNode.id */
+    target: string;
+    /** GraphRow.name — the anchor row on the source card. */
+    sourceRow?: string;
+    /** GraphRow.name — the anchor row on the target card. */
+    targetRow?: string;
+    kind: EdgeKind;
+    /**
+     * The consumer's own word for the relationship, when it has one — dbd v2's `DepEdge.kind`
+     * is `reads | writes | calls | member`.
+     *
+     * Open vocabulary, deliberately. `kind` stays the two-value discriminator that layouts
+     * branch on; widening THAT to hold four SQL verbs would teach a generic graph package
+     * what a stored procedure is. This carries the word so the renderer can label and theme
+     * it (`data-edge-relation`) without the coupling.
+     */
+    relation?: string;
+    cardinality?: string;
+    action?: string;
+    /**
+     * Endpoints the field map could not resolve to a node, with the raw value left in place
+     * on `source`/`target` so it is still readable.
+     *
+     * An unresolvable endpoint is a NORMAL state, not a defect. Sensei's code graph reports
+     * 59.6% of 4.08M edges with a null target: the call is real, the callee is simply not
+     * indexed. Dropping those would make the graph look far more complete than it is, so the
+     * edge is kept and marked, and it is the renderer's job to dim it.
+     */
+    unplaced?: 'source' | 'target' | 'both';
+};
+export type GraphModel = {
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+    byId: Map<string, GraphNode>;
+    /** Undirected adjacency, self-edges excluded. */
+    neighbors: Map<string, Set<string>>;
+};
+/**
+ * Props for the `Graph` canvas.
+ *
+ * Either hand it a `state` — for composition, or to drive selection from outside — or hand
+ * it `nodes`/`edges`/`fields` and let it construct one. A supplied `state` must have STABLE
+ * IDENTITY for the component's lifetime: drive the existing instance through its own methods
+ * and `update()` rather than swapping instances, because context captures it once at init.
+ */
+export type GraphProps = {
+    state?: import('./GraphState.svelte.js').GraphState;
+    nodes?: unknown[];
+    edges?: unknown[];
+    fields?: GraphFields;
+    layout?: string | import('./layout/types.js').LayoutFn;
+    density?: import('./layout/types.js').Density;
+    arrange?: import('./layout/types.js').Arrange;
+    /** Outer grouping axis — `group` (default) or `kind`. */
+    groupBy?: import('./layout/types.js').NodeAxis;
+    /** Subdivide each cluster by a second axis. Omit for one level. */
+    nestBy?: import('./layout/types.js').NodeAxis;
+    edgeStyle?: import('./layout/types.js').EdgeStyle;
+    /** `neighborhood` only — the node the view centres on. Defaults to the selection. */
+    focus?: string | null;
+    value?: string | null;
+    preset?: import('./preset.js').GraphPreset;
+    mode?: 'light' | 'dark';
+    /**
+     * Multiplier on the fit-to-container scale. 1 fits the whole diagram; above 1 the canvas
+     * scrolls and drags rather than clipping. Bindable — the built-in controls drive it.
+     */
+    zoom?: number;
+    /** Built-in zoom controls, ctrl/pinch-wheel zoom and drag-to-pan. Default true. */
+    zoomable?: boolean;
+    /** Built-in names/keys/all detail toggle on the canvas. Default true. */
+    densityToggle?: boolean;
+    /**
+     * Draw an arrowhead at each edge's target instead of a plain anchor dot. Default true —
+     * an edge is directed, and two identical dots discard that.
+     */
+    arrows?: boolean;
+    label?: string;
+    onselect?: (id: string) => void;
+    /** Icon class per node kind and row badge, merged over the built-in map. */
+    icons?: Record<string, string>;
+    class?: string;
+};
+/**
+ * Field map from a consumer's shape to the canonical model. Every entry is a
+ * dotted path read with `readPath`. Anything omitted falls back to the
+ * same-named key, so a source already shaped like the canonical model needs no map.
+ */
+export type GraphFields = {
+    id?: string;
+    label?: string;
+    group?: string;
+    kind?: string;
+    rows?: string;
+    note?: string;
+    /** Row-level paths, read against each entry of the `rows` array. */
+    rowName?: string;
+    rowType?: string;
+    rowNote?: string;
+    /** Row badge flags — each names a truthy path on the row. */
+    rowBadges?: Partial<Record<RowBadge, string>>;
+    /** Edge-level paths. */
+    source?: string;
+    target?: string;
+    /**
+     * Where each endpoint's GROUP is read from, when the endpoint value is a bare label.
+     * Declared explicitly rather than guessed: dbd's refs nest as `from: { s, t, c }`, so the
+     * group is `from.s`. Falls back to `group` (the node-level path) when unset.
+     */
+    sourceGroup?: string;
+    targetGroup?: string;
+    sourceRow?: string;
+    targetRow?: string;
+    edgeKind?: string;
+    /**
+     * Kind for an edge whose `edgeKind` path yields nothing. Defaults to `'reference'`.
+     *
+     * For a dataset that is ENTIRELY dependencies — dbd v2's `deps`, or a call graph — the
+     * kind is a property of the list, not of each row, and there is no path to point at.
+     * Without this the consumer has to rewrite every edge object just to tag it, or accept
+     * every call being drawn as a foreign key.
+     */
+    defaultEdgeKind?: EdgeKind;
+    /** Path to the consumer's own relationship word — see `GraphEdge.relation`. */
+    relation?: string;
+    cardinality?: string;
+    action?: string;
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@rokkit/graph",
+  "version": "1.6.0",
+  "description": "Node-link diagram components — pluggable layouts, ER/schema views",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jerrythomas/rokkit.git"
+  },
+  "author": "Jerry Thomas <me@jerrythomas.name>",
+  "license": "MIT",
+  "type": "module",
+  "svelte": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "svelte": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./schema": {
+      "types": "./dist/schema/index.d.ts",
+      "svelte": "./dist/schema/index.js",
+      "default": "./dist/schema/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "prepublishOnly": "cp ../../LICENSE . && bun run clean && bun run build && node ../../config/pack-repoint.mjs",
+    "postpublish": "node ../../config/pack-repoint.mjs --restore && rm -f LICENSE",
+    "clean": "rm -rf dist",
+    "build": "svelte-package -i src -o dist",
+    "check": "svelte-check --tsconfig ./tsconfig.json",
+    "check:types": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@rokkit/core": "1.6.0"
+  },
+  "peerDependencies": {
+    "@rokkit/ui": "1.6.0",
+    "svelte": "^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@rokkit/ui": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@rokkit/ui": "1.6.0",
+    "@sveltejs/package": "^2.5.8",
+    "@sveltejs/vite-plugin-svelte": "^6.2.4",
+    "svelte": "^5.55.7",
+    "svelte-check": "^4.7.6"
+  }
+}