@jmbarzee/force-graph 0.0.1

package/dist-lib/graph/scheme.d.ts

@@ -0,0 +1,68 @@
+import { AxisValue } from './axis';
+import { Taxonomy } from './taxonomy';
+/** The two themes every colour is declared in. */
+export type Theme = 'light' | 'dark';
+/** Both themes, in order. */
+export declare const THEMES: readonly Theme[];
+/** A fill and a border. */
+export interface ColorPair {
+    /** Canvas fill colour. */
+    readonly fill: string;
+    /** Canvas border colour, a few stops darker than the fill. */
+    readonly border: string;
+}
+/** A value's colour in both themes — declared together, so no half can go missing. */
+export interface ThemedColor {
+    readonly light: ColorPair;
+    readonly dark: ColorPair;
+}
+/** How an edge type is stroked: its colour per theme, base alpha, dash pattern and width. */
+export interface EdgeStroke {
+    readonly color: {
+        readonly light: string;
+        readonly dark: string;
+    };
+    readonly alpha: number;
+    readonly dash: readonly number[];
+    readonly width: number;
+}
+/**
+ * The stem of a value's custom-property name: the value id in kebab case
+ * (`twoWords` → `two-words`). Derived, never stored.
+ */
+export declare function cssSuffix(value: AxisValue): string;
+/**
+ * The inline custom properties a pane carries for one theme: every style
+ * value's fill and border. Set on the pane's root, they are what tokens, chip
+ * tints and typed rows read, and they follow the resolved theme by being
+ * recomputed, not overridden.
+ */
+export declare function schemeVars(taxonomy: Taxonomy, theme: Theme): Record<string, string>;
+/**
+ * The red, green and blue of a scheme colour, or undefined. A scheme colour
+ * is hex of either length, `rgb()`/`rgba()` or `hsl()`/`hsla()` — a form
+ * every reader can parse without a browser, so the taxonomy can refuse
+ * anything else at construction (`isSchemeColor`) and no reader meets a
+ * colour it cannot read.
+ */
+export declare function rgbOf(color: string): readonly [number, number, number] | undefined;
+/** Whether a colour is one every reader parses: hex, `rgb()` or `hsl()`. */
+export declare const isSchemeColor: (color: string) => boolean;
+/**
+ * A colour at an alpha, as `rgba()`, for a canvas gradient or fill. A colour
+ * outside the scheme's forms becomes a neutral grey, said once per colour on
+ * the console — never a throw, because this runs inside the draw loop.
+ * Unreachable for a taxonomy's colours, which are refused at
+ * construction; it guards the library's own group palette and any caller
+ * that bypasses the taxonomy.
+ */
+export declare function withAlpha(color: string, alpha: number): string;
+/**
+ * A stylesheet for a host's own CSS: every style value's fill and border on
+ * `:root`, and the dark values that differ under `darkSelector` — by default
+ * `[data-theme="dark"]`, the attribute the pane carries on its own root; a
+ * host that marks its theme another way names its own selector. The pane
+ * does not read this — it carries `schemeVars` inline — so a host that
+ * styles nothing of its own by node value never needs it.
+ */
+export declare function schemeStylesheet(taxonomy: Taxonomy, darkSelector?: string): string;

package/dist-lib/graph/shapes.d.ts

@@ -0,0 +1,227 @@
+import { AxisId, AxisValue } from './axis';
+import { EdgeStroke, ThemedColor } from './scheme';
+/** A rest band on one layout axis: the range inside which a value feels no gravity. */
+export interface Band {
+    min: number;
+    max: number;
+}
+/**
+ * How one value on the style axis is drawn, sized, and physically weighted,
+ * as a host declares it. Only the id, the label and the colour are required;
+ * the rest is derived from them and from the value's position in the
+ * declaration order (top of the hierarchy first):
+ *
+ *   - `abbreviation`: the first two characters of the label.
+ *   - `icon`: none.
+ *   - `size.r`: 12; `size.iconSize`: nine tenths of the radius, rounded, at least 9.
+ *   - `physics.charge`: −40 × r; `physics.coreRadius`: 4 × r.
+ *   - `physics.band.y`: the value's slice of the stack, by position — the
+ *     first value's band at the top of the canvas, the last at the bottom,
+ *     neighbours overlapping a fifth; `physics.band.x`: 0 to 380.
+ *   - `whenHidden`: `ascend`; `summaryKind`: `degree`.
+ *
+ * A field given overrides its default, field by field — a band's `x` may be
+ * declared and its `y` left to the stack.
+ */
+export interface NodeStyle {
+    /** The value on the style axis this style is for. */
+    id: AxisValue;
+    /** Display name, e.g. "Service". */
+    label: string;
+    /**
+     * One or two characters for a control token: a control surface renders a
+     * token per value and has no room for a name.
+     */
+    abbreviation?: string;
+    /** Single glyph drawn inside the canvas node. */
+    icon?: string;
+    /** Fill and border in both themes; the canvas reads `color[theme]`. */
+    color: ThemedColor;
+    size?: {
+        /** Circle radius in world units. Hit-test radius = r + 4. */
+        r?: number;
+        /** Font size for the icon glyph (px). */
+        iconSize?: number;
+    };
+    physics?: {
+        /**
+         * Repulsion charge. Negative = repulsion. The starting point for the
+         * value the user tunes at runtime via the control panel.
+         */
+        charge?: number;
+        /**
+         * Core radius (charge softening, as a length). A pair of nodes softens
+         * its charge by the squared average of the two endpoints' effective core
+         * radii (`coreRadiusMultiplier × coreRadius`), added to d². Larger =
+         * gentler, wider plateau.
+         */
+        coreRadius?: number;
+        /**
+         * Rest bands, one per layout axis, inside which this value feels no
+         * gravity. `y` is the hierarchy (negative = top of canvas); `x` bounds
+         * the horizontal spread. The simulation seeds nodes inside their bands on
+         * creation, so the structure is visible before the first tick — which
+         * also makes this the seeding function, not only the gravity target.
+         */
+        band?: {
+            x?: Band;
+            y?: Band;
+        };
+    };
+    /**
+     * What a dependency edge touching a HIDDEN node of this value does:
+     * `ascend` re-points the endpoint to the node's nearest visible ancestor;
+     * `splice` follows the node's own dependency edges through to the far
+     * side, so caller → hidden → callee draws as caller → callee.
+     */
+    whenHidden?: 'ascend' | 'splice';
+    /**
+     * The glanceable summary for a node of this value: the children it contains,
+     * counted per style value and named by that value's abbreviation
+     * (`2 Sv · 1 Pd`); its dependency degree (`→3 ←2`); or nothing.
+     */
+    summaryKind?: 'children' | 'degree' | 'none';
+}
+/**
+ * A node style with every default filled in — what `Taxonomy.styleOf` answers.
+ *
+ * Reached through `Taxonomy.nodeStyleOf`, never by key lookup from the
+ * engine — a miss has to resolve to the fallback rather than throw, because
+ * the resolution happens per node per frame inside the draw loop where an
+ * exception stops the canvas repainting for good.
+ */
+export interface ResolvedNodeStyle {
+    id: AxisValue;
+    label: string;
+    abbreviation: string;
+    /** Empty when the style declares none: nothing is drawn. */
+    icon: string;
+    color: ThemedColor;
+    size: {
+        r: number;
+        iconSize: number;
+    };
+    physics: {
+        charge: number;
+        coreRadius: number;
+        band: {
+            x: Band;
+            y: Band;
+        };
+    };
+    whenHidden: 'ascend' | 'splice';
+    summaryKind: 'children' | 'degree' | 'none';
+}
+/**
+ * Stable id for one edge type.
+ *
+ * A string, not a union, and that is the library's whole position on edge
+ * vocabulary: it is the override key in the spring tuning and the hover-link
+ * key across the spring map, curves, and canvas, so it has to be something a
+ * host can extend. A host narrows it to its own union.
+ */
+export type EdgeTypeId = string;
+/** One spring: stiffness (k) and rest length. */
+export interface SpringPhysics {
+    strength: number;
+    distance: number;
+}
+/**
+ * One kind of edge, as a host declares it: which values it runs between and
+ * which relation it expresses, optionally which values the edge itself must
+ * carry (`match`), and — optionally — how it is stroked, its spring and its
+ * hover text. An edge is classified as the declared type of its relation
+ * that runs between its endpoints' values, in either orientation, and whose
+ * `match` (if any) its own values satisfy; a satisfied `match` beats a type
+ * without one, the declared orientation beats the reverse, and declaration
+ * order settles the rest — unless the taxonomy's `classifyEdge` says
+ * otherwise. A label left out is the id; a stroke left out is the neutral
+ * stroke (the containment stroke for a containment type), field by field; a
+ * spring left out is the middling spring; a tooltip left out is the label.
+ */
+export interface EdgeType {
+    /** Stable id — also the override key in the spring tuning. */
+    id: EdgeTypeId;
+    /** Short control-panel label. Default: the id. */
+    label?: string;
+    /**
+     * The endpoint values on the style axis this type runs between — one
+     * value or several at each end: the type runs between every source value
+     * and every target value, in either orientation. Read off the edge's
+     * original endpoint nodes when an edge is classified; the first of each
+     * is the split-colour token's two halves. Values, not types: the engine
+     * resolves an edge's type from where its nodes sit.
+     */
+    sourceValue: AxisValue | readonly AxisValue[];
+    targetValue: AxisValue | readonly AxisValue[];
+    /** Which relation an edge of this type expresses; an edge is classified only as a type of its own relation. */
+    relation: 'containment' | 'dependency';
+    /**
+     * Values the edge itself must carry on the host's edge axes to be this
+     * type — how two types on one pair are told apart (a call and a signal
+     * between the same two values, by the edge's `dispatch`). An edge lacking
+     * one of these values is not this type. Absent, the pair alone decides,
+     * and this type is the fallback for a pair other types `match` on.
+     */
+    match?: Readonly<Record<AxisId, AxisValue>>;
+    /** Declared stiffness / rest length — what the type resolves to until tuned. */
+    physics?: SpringPhysics;
+    /** How the canvas strokes an edge of this type, in both themes; any field left out is its relation's default stroke's (`NEUTRAL_STROKE`, or `CONTAINMENT_STROKE` for a containment type). */
+    style?: Partial<EdgeStroke>;
+    /** The hover text for the type. Default: the label. */
+    tooltip?: string;
+}
+/** An edge type with its defaults filled in — what `Taxonomy.edgeTypes` carries. */
+export interface ResolvedEdgeType extends EdgeType {
+    label: string;
+    /** The first declared source value — one half of the split-colour token. */
+    sourceValue: AxisValue;
+    /** The first declared target value — the other half. */
+    targetValue: AxisValue;
+    /** Every (source, target) pair the type runs between: each source value with each target value, in declaration order. */
+    pairs: readonly (readonly [AxisValue, AxisValue])[];
+    physics: SpringPhysics;
+    style: EdgeStroke;
+    tooltip: string;
+}
+/** The stroke a dependency type starts from, and the stroke of a dependency edge no type claims: a quiet, solid grey. */
+export declare const NEUTRAL_STROKE: EdgeStroke;
+/** The stroke a containment type starts from, and the stroke of a containment edge no type claims: the same grey, faint and dashed. */
+export declare const CONTAINMENT_STROKE: EdgeStroke;
+/** The values declared at one end of an edge type, as a list. */
+export declare function endpointValues(declared: AxisValue | readonly AxisValue[]): readonly AxisValue[];
+/** Every (source, target) pair a type runs between: each source value with each target value, in declaration order. */
+export declare function edgePairs(type: Pick<EdgeType, 'sourceValue' | 'targetValue'>): readonly (readonly [AxisValue, AxisValue])[];
+/**
+ * The frame the default rest bands are laid in, in world units: the
+ * hierarchy axis runs from `top` (the first declared value) to `bottom` (the
+ * last), and every value spreads across `x`. A host that declares a band of
+ * its own writes it in these units.
+ */
+export declare const BAND_FRAME: {
+    readonly top: -300;
+    readonly bottom: 400;
+    readonly x: Band;
+};
+/** The spring a type starts from when it declares none. */
+export declare const MIDDLING_SPRING: SpringPhysics;
+/**
+ * The rest band on the hierarchy axis for the value at position `i` of `n`:
+ * centres spread evenly down the stack, each band wide enough to overlap its
+ * neighbours by a fifth, so the structure reads as tiers without a gap a node
+ * could never rest in. One value alone takes the whole stack.
+ */
+export declare function stackBand(i: number, n: number): Band;
+/**
+ * A declared style with every default filled in, given its position in the
+ * declaration order. Pure: the same inputs give the same object, so the
+ * taxonomy resolves each value once and hands out that one object.
+ */
+export declare function resolveNodeStyle(style: NodeStyle, i: number, n: number): ResolvedNodeStyle;
+/**
+ * A declared edge type with its defaults filled in: the id as label, the
+ * first declared value at each end beside every pair, the middling spring,
+ * its relation's stroke field by field, the label as tooltip. The taxonomy
+ * has refused an end that names no value before this runs.
+ */
+export declare function resolveEdgeType(type: EdgeType): ResolvedEdgeType;

package/dist-lib/graph/taxonomy.d.ts

@@ -0,0 +1,207 @@
+import { ReactNode } from 'react';
+import { AxisDescriptor, AxisId, AxisValues, AxisValue, ResolvedAxisDescriptor } from './axis';
+import { GraphEdge, GraphNode } from './model';
+import { EdgeType, EdgeTypeId, NodeStyle, ResolvedEdgeType, ResolvedNodeStyle } from './shapes';
+import { ResolvedScalarAxis, ScalarAxis } from './scalar';
+import { EdgeStroke } from './scheme';
+/** A highlight: the node ids lit and the edge ids lit. Edges absent means "every visible edge between lit nodes". */
+export interface Highlight {
+    readonly nodes: ReadonlySet<string>;
+    readonly edges?: ReadonlySet<string>;
+}
+/** What a highlight rule may read: the visible graph, and a lookup for any node. */
+export interface HighlightGraph {
+    readonly visibleNodes: readonly GraphNode[];
+    readonly visibleEdges: readonly GraphEdge[];
+    readonly visibleIds: ReadonlySet<string>;
+    getNode(id: string): GraphNode | undefined;
+}
+/** Which way a highlight walks from its node: what it depends on, or what depends on it. */
+export type HighlightDirection = 'downstream' | 'upstream';
+/** The minimum a consumer needs of a node in order to resolve its style. */
+export type StyleSubject = {
+    values: AxisValues;
+};
+/** What the hover box shows under a node's name: one line, or several — text or a host's own elements. */
+export type ContextLine = ReactNode | readonly ReactNode[];
+/**
+ * The built taxonomy: what the view resolves every style, edge type, axis
+ * policy and host hook through. Built once by `createTaxonomy`; derive a
+ * variant from the spec, never by spreading this object.
+ *
+ * What a host reads: `filterAxes`, `axisFor` and `valueOn` to filter its own
+ * records the way the view does; `styleOf`, `styleValues` and `colorVar` for
+ * chrome of its own in the scheme's colours; `edgeTypes` for a legend;
+ * `searchText` to match as the view matches. The rest is the engine's
+ * interface — resolution for the draw loop — and a host has no call to read
+ * it.
+ */
+export interface Taxonomy {
+    /**
+     * The axis this taxonomy resolves style on.
+     *
+     * One axis, named once. Every other feature elects its own — the physics reads
+     * its axis off the force params, filters read theirs off the filter — and no
+     * feature composes two.
+     *
+     * A method, not a field, and that is a correctness property rather than a
+     * style choice: a container derived by spreading (`{ ...taxonomy,
+     * styleAxis: 'other' }`) would rewrite a field and leave the closures
+     * answering on the old axis — an object that disagrees with itself, the
+     * draw loop reading one half and the physics the other. With one source
+     * there is nothing to override out of step.
+     */
+    styleAxis(): AxisId;
+    /** The style axis's display name, for a control that names axes. */
+    styleLabel(): string;
+    /**
+     * The axes a filter may operate on, with their per-axis policies,
+     * every default filled in. Host-declared, like the entries: which axes
+     * exist is a domain fact. The engine reads only the policies and never
+     * enumerates the ids.
+     */
+    readonly filterAxes: readonly ResolvedAxisDescriptor[];
+    /** One axis's policies, or undefined if the host does not declare it. */
+    axisFor(axis: AxisId): ResolvedAxisDescriptor | undefined;
+    /**
+     * The value a subject presents on one axis — read off its values, for
+     * every axis alike. An axis that is a projection of another is materialized
+     * by the host when it builds the node, so nothing here knows which axes are
+     * derived.
+     */
+    valueOn(subject: StyleSubject, axis: AxisId): AxisValue | undefined;
+    /** Every style value, in declaration order (top of the hierarchy first). */
+    readonly styleValues: readonly AxisValue[];
+    /** Every edge type, in control-panel order, its defaults filled in. */
+    readonly edgeTypes: readonly ResolvedEdgeType[];
+    /** Every computed scalar a layout axis may key on, its words filled in: the built-ins, then the host's. */
+    readonly scalars: readonly ResolvedScalarAxis[];
+    /** How the canvas strokes an edge of this type; the neutral stroke, said once, for an id the taxonomy does not declare. */
+    edgeStrokeFor(id: EdgeTypeId): EdgeStroke;
+    /**
+     * The custom property a value's fill is published under (`-border` for its
+     * border): `--gv-node-` and the value id in kebab case, or a numbered name
+     * when the id kebab-cases to nothing or to another value's name. The one
+     * way to learn the name; a host's CSS reads it through `schemeVars` or
+     * `schemeStylesheet`.
+     */
+    colorVar(value: AxisValue): string;
+    /** The hover box's context line(s) for a node — the host's, or its parent's name. */
+    contextLine(node: GraphNode, parent: GraphNode | undefined): ContextLine;
+    /** What the search control matches against for a node — the host's text, or the name. */
+    searchText(node: GraphNode): string;
+    /** The highlight for an active node — the host's refinement of the library's transitive walk in the given direction. */
+    highlight(active: GraphNode, base: Highlight, graph: HighlightGraph, direction: HighlightDirection): Highlight;
+    /**
+     * Style, size, physics and summary metadata for a value. Never throws — a
+     * value the taxonomy does not declare, and an ABSENT value, both resolve to
+     * the fallback.
+     */
+    styleOf(value: AxisValue | undefined): ResolvedNodeStyle;
+    /** Where a node sits on the style axis, or undefined if it sits nowhere. */
+    styleValueOf(subject: StyleSubject): AxisValue | undefined;
+    /**
+     * Short label for a value — one or two characters. Control surfaces render a
+     * token per value and have no room for a full name. A value the taxonomy
+     * does not declare abbreviates to its own first two characters.
+     */
+    abbreviationFor(value: AxisValue): string;
+    /** The same as `styleOf`, addressed by a node. The hot-path entry point. */
+    nodeStyleOf(subject: StyleSubject): ResolvedNodeStyle;
+    /**
+     * Which declared edge type an edge is, given the style values of its two
+     * ORIGINAL endpoints: the declared type of the edge's relation that runs
+     * between those values in either orientation and whose `match` the edge's
+     * own values satisfy (a satisfied `match` over none, the declared
+     * orientation over the reverse, then declaration order), handed to the
+     * spec's `classifyEdge`, which may keep it, replace it, or supply one where
+     * there is none; undefined when neither names one. Classified once, on
+     * the original endpoints; the type is carried through graduation, so a
+     * re-pointed edge keeps its stroke and its spring.
+     */
+    edgeTypeOf(edge: GraphEdge, src: AxisValue | undefined, tgt: AxisValue | undefined): EdgeTypeId | undefined;
+    /** Which of two graduated edges on one visible pair survives: the host's choice, or the one kept so far. */
+    collapse(kept: GraphEdge, candidate: GraphEdge): GraphEdge;
+}
+/**
+ * What a host declares in order to build an `Taxonomy`: the style axis and
+ * its values, the edge types and the rule that classifies an edge, the filter
+ * axes. Everything with a sensible default is optional.
+ */
+export interface TaxonomySpec {
+    /** The axis every node's style is read on. */
+    styleAxis: AxisId;
+    /** The style axis's display name. Absent, the axis id. */
+    styleLabel?: string;
+    /**
+     * The style values, top of the hierarchy first. The order places each
+     * value's rest band down the stack when it declares none, and orders the
+     * control surfaces and the hover box's child counts.
+     */
+    styles: readonly NodeStyle[];
+    /**
+     * Drawn for a value the taxonomy does not declare, and for a node with no
+     * value on the style axis. Absent, a grey disc with a question mark that
+     * rests anywhere in the stack.
+     */
+    fallbackStyle?: Omit<NodeStyle, 'id'>;
+    /** The edge types, in control-panel order. Absent, none: every edge draws untyped in its relation's stroke, and `validateGraph` says so. */
+    edgeTypes?: readonly EdgeType[];
+    /**
+     * The host's say in classifying an edge, given the style values of its
+     * original endpoints and `declared` — the type the declarations answer (by
+     * relation, endpoint pair, `match` and orientation), or undefined: an id
+     * to use, or undefined to keep the declared answer. For the exceptions the
+     * declarations cannot express — a type that also runs between pairs it
+     * does not declare, say: `(edge, src, tgt, declared) => declared ?? …`.
+     * Required only when two declared types on one pair share an orientation
+     * and a `match`.
+     */
+    classifyEdge?: (edge: GraphEdge, src: AxisValue | undefined, tgt: AxisValue | undefined, declared: EdgeTypeId | undefined) => EdgeTypeId | undefined;
+    /** The axes the filter bar offers. Absent, the style axis alone, as an allow-list. */
+    filterAxes?: readonly AxisDescriptor[];
+    /**
+     * Computed scalars this host adds to the built-ins: each reads node
+     * metadata — its own payload included — and the graph's structure, and
+     * answers a number per node, which the frame maps onto [0, 1] the way the
+     * scalar's `normalize` says. Absent, the built-ins alone.
+     */
+    scalars?: readonly ScalarAxis[];
+    /**
+     * The hover box's context under the name: what a host wants said there —
+     * addressing metadata from its own payload, a parent by another name, an
+     * origin — as one line or several. Absent, the line is the parent's name.
+     */
+    contextLine?: (node: GraphNode, parent: GraphNode | undefined) => ContextLine;
+    /**
+     * What the search control matches a node on, case-insensitively: a code
+     * from the payload beside the name, say. Absent, the name.
+     */
+    searchText?: (node: GraphNode) => string;
+    /**
+     * The highlight for an active node: given the library's transitive walk
+     * from it in `direction`, the host may widen it (members it relates by
+     * metadata) or replace it. Absent, the walk is the highlight.
+     */
+    highlight?: (active: GraphNode, base: Highlight, graph: HighlightGraph, direction: HighlightDirection) => Highlight;
+    /**
+     * When two dependency edges each lose an end to a hidden node and come to
+     * run between the same two visible nodes, which of the two originals the
+     * drawn edge stands for. Both arguments are the host's own edges, so
+     * a host whose edges carry routing metadata may prefer the one that does.
+     * Absent, the one met first in the host's edge order is kept. Two edges
+     * whose ends are both visible are never collapsed.
+     */
+    collapse?: (kept: GraphEdge, candidate: GraphEdge) => GraphEdge;
+}
+/**
+ * Build the container, refusing an incoherent spec: a value declared twice, an
+ * edge type declared twice, running between values nobody declared or naming
+ * no value at an end, a filter axis declared twice, a colour no reader can
+ * parse, a band whose ends cross, a policy outside its vocabulary, a scalar
+ * id already taken. Every problem is named at once, by its path in the spec.
+ * To derive a variant, build one from a spec (`createTaxonomy({ ...spec, … })`);
+ * spreading the built object copies closures that still read the original's
+ * fields.
+ */
+export declare function createTaxonomy(spec: TaxonomySpec): Taxonomy;

package/dist-lib/graph/validate.d.ts

@@ -0,0 +1,47 @@
+import { Graph } from './model';
+import { Taxonomy } from './taxonomy';
+/**
+ * The defects `validateGraph` names. Errors: a node or edge id used twice,
+ * an edge whose endpoint is not in the graph, an unknown relation, a type
+ * whose relation is not the edge's, a rule that threw, a parent not in the
+ * graph. Warnings: an edge no type claims, a style value the taxonomy does
+ * not declare, containment edges that contradict `parentId`, derived
+ * containment edges no type claims (`containment-untyped`, from
+ * `derivedContainmentDiagnostics`).
+ */
+export type GraphDiagnosticCode = 'edge-id-duplicate' | 'edge-endpoint-missing' | 'edge-relation-unknown' | 'edge-type-rule-threw' | 'edge-type-unclassified' | 'edge-type-relation-mismatch' | 'parent-missing' | 'containment-parent-mismatch' | 'node-value-undeclared' | 'node-id-duplicate' | 'containment-untyped';
+/** One defect in a host's graph, as data: its severity, its code, a message, and the node or edge it names. */
+export interface GraphDiagnostic {
+    /** An error names something the view cannot draw as given; a warning, something it draws but the host should know. */
+    severity: 'error' | 'warning';
+    code: GraphDiagnosticCode;
+    message: string;
+    nodeId?: string;
+    edgeId?: string;
+}
+/**
+ * Every defect in a host's graph, as data: errors for what the view cannot
+ * draw as given (a duplicated node id, a dangling endpoint, an unknown
+ * relation, a type whose relation is not the edge's, a parent not in the
+ * graph) and warnings for what it draws but the host should know (an
+ * unclassified edge, an undeclared style value, containment edges that
+ * contradict `parentId`). Pure; the same graph and taxonomy give the same
+ * list, in graph order.
+ */
+export declare function validateGraph(graph: Graph, taxonomy: Taxonomy): GraphDiagnostic[];
+/**
+ * The graph with every node and edge an error names removed and every parent
+ * an error names cleared — what the view draws when the host's graph has
+ * defects. A duplicated id keeps its first node and its first edge. The
+ * host's objects are not mutated; a graph with no errors is returned as is.
+ */
+export declare function dropInvalid(graph: Graph, diagnostics: readonly GraphDiagnostic[]): Graph;
+/**
+ * The one warning the drawn graph adds to the host's: the containment edges
+ * the view derived from `parentId` that no declared containment type claims
+ * (a dependency type the host's rule answers does not count). They draw in
+ * the containment stroke and pull nothing while push and pull key on the
+ * style axis; a host that wants them typed declares a containment type
+ * between the child's value and the parent's.
+ */
+export declare function derivedContainmentDiagnostics(drawn: Graph, host: Graph, taxonomy: Taxonomy): GraphDiagnostic[];

package/dist-lib/index.d.ts

@@ -0,0 +1,35 @@
+export { FilterBar } from './components/FilterBar';
+export type { FilterBarChrome, FilterBarProps } from './components/FilterBar';
+export { GraphView } from './components/GraphView';
+export type { GraphViewChrome, GraphViewHandle, GraphViewProps, GroupsControl, NodeAction, Position, SearchState } from './components/GraphView';
+export { GroupLegend } from './components/GroupLegend';
+export type { GroupLegendProps } from './components/GroupLegend';
+export { useLinkedViews } from './components/graph-view/useLinkedViews';
+export type { LinkedViewProps, LinkedViewState, LinkedViews, LinkedViewsOptions } from './components/graph-view/useLinkedViews';
+export type { FocusRequest } from './components/graph-view/focus';
+export { useFocusRequest } from './components/graph-view/useFocusRequest';
+export type { RecentlyChanged } from './components/graph-view/useRecentlyChanged';
+export { TaxonomyContext, useTaxonomy } from './components/graph-view/useTaxonomy';
+export { themeChoiceOf, useHostTheme } from './components/graph-view/useTheme';
+export type { ThemeChoice } from './components/graph-view/useTheme';
+export { reconcileFilter } from './filter/reconcile';
+export type { ReconcileInput } from './filter/reconcile';
+export { toggleGroup, toggleValue } from './filter/toggle';
+export { initialFilter, filterFromJSON, filterStatesEqual, filterToJSON, hiddenMatchesOf, locksFromJSON, locksToJSON, matchesFocus, passesSelection, reseedFilter, lockedFor, selectionFor, withLock, withSelection } from './filter/types';
+export type { FilterState, FocusTarget, HiddenMatches, HiddenMatchesInput, AxisLocks, PassesSelectionInput, ReconcileResult, AxisSelection, ViewTransition } from './filter/types';
+export { countsOn, valuesOn } from './graph/axis';
+export type { AxisDescriptor, AxisId, AxisNamer, AxisValues, AxisValue, FilterChip, Relation, ResolvedAxisDescriptor } from './graph/axis';
+export type { ActiveGroup, NodeGroup } from './graph/groups';
+export { copyGroups, isContainment, nodesById, payloadNumber, payloadString } from './graph/model';
+export type { Graph, GraphEdge, GraphNode, ReadableGraph } from './graph/model';
+export { createTaxonomy } from './graph/taxonomy';
+export type { ContextLine, Highlight, HighlightDirection, HighlightGraph, StyleSubject, Taxonomy, TaxonomySpec } from './graph/taxonomy';
+export { schemeStylesheet, schemeVars } from './graph/scheme';
+export type { ColorPair, EdgeStroke, Theme, ThemedColor } from './graph/scheme';
+export type { ResolvedScalarAxis, ScalarAxis } from './graph/scalar';
+export { layoutFromJSON, layoutToJSON } from './graph/layout';
+export type { LayoutJSON, LayoutState, LayoutTuningJSON } from './graph/layout';
+export { validateGraph } from './graph/validate';
+export type { GraphDiagnostic, GraphDiagnosticCode } from './graph/validate';
+export { BAND_FRAME, CONTAINMENT_STROKE, NEUTRAL_STROKE } from './graph/shapes';
+export type { Band, EdgeType, EdgeTypeId, NodeStyle, ResolvedEdgeType, ResolvedNodeStyle, SpringPhysics } from './graph/shapes';