semiotic 3.7.4 → 3.8.0

package/dist/components/recipes/gofishIRExamples.d.ts

@@ -0,0 +1,38 @@
+import type { GofishDisplayListDocument } from "./gofishIR";
+import { gofishDisplayListExamples as generatedExamples } from "./gofishDisplayListFixtures.generated";
+/**
+ * Canonical GoFish **DisplayList** documents for the adapter gallery.
+ *
+ * Most are *real* baked render-IR documents — the output of `gofish-graphics`'
+ * `toDisplayList({ w, h })` layout pass — generated by
+ * `scripts/gen-gofish-fixtures.ts` and checked in so the adapter tests and the
+ * `/interoperability/gofish` page stay deterministic and never depend on the
+ * GoFish nightly at runtime. Each stands in for what a host gets by calling
+ * `await spec.toDisplayList({ w, h })`.
+ *
+ * The one exception is **boba**, which is *hand-written* (`gofishBobaHandwritten.ts`,
+ * no `gofish-graphics` at all) — the counter-proof that the DisplayList is an
+ * open, host-emittable format, not something only GoFish can produce.
+ *
+ * Regenerate the baked set after a GoFish bump with:
+ *   `node --experimental-strip-types scripts/gen-gofish-fixtures.ts --write`
+ */
+export declare const flowerIR: GofishDisplayListDocument;
+export declare const polarribbonIR: GofishDisplayListDocument;
+export declare const treemapIR: GofishDisplayListDocument;
+export declare const bottleIR: GofishDisplayListDocument;
+export declare const bobaIR: GofishDisplayListDocument;
+export declare const pythonIR: GofishDisplayListDocument;
+export interface GofishIRExample {
+    /** Generated keys (derived so new baked fixtures never drift this) plus the hand-written `boba`. */
+    key: (typeof generatedExamples)[number]["key"] | "boba";
+    label: string;
+    doc: GofishDisplayListDocument;
+    /** A one-line note on what the document demonstrates. */
+    blurb: string;
+    /** The upstream example this mirrors. */
+    source: string;
+    /** True for the hand-emitted document (no GoFish bake). */
+    handWritten?: boolean;
+}
+export declare const gofishIRExamples: readonly GofishIRExample[];

package/dist/components/recipes/intervalLanes.d.ts

@@ -0,0 +1,87 @@
+import type { OrdinalCustomLayout } from "../stream/ordinalCustomLayout";
+import type { Datum } from "../charts/shared/datumTypes";
+/**
+ * `intervalLanesLayout` — a Gantt / swimlane timeline as an `OrdinalCustomChart`
+ * layout. Each ordinal **lane** holds events that occupy a `[start, end]` span on
+ * a shared time axis; concurrent events within a lane are packed into stacked
+ * sub-tracks ({@link packIntervals}). The recipe emits one real, hit-tested,
+ * theme-colored rect per event (so every bar inherits keyboard nav, tooltips,
+ * selection, and transitions) and draws lane labels, optional period bands, and
+ * a time axis in `overlays`.
+ *
+ * Sibling to `flextreeLayout` / `dagreLayout`. The complement to a
+ * concurrency line — see {@link activeCountOverDomain}.
+ *
+ * @example
+ * ```tsx
+ * import { OrdinalCustomChart } from "semiotic/ordinal"
+ * import { intervalLanesLayout } from "semiotic/recipes"
+ *
+ * <OrdinalCustomChart
+ *   data={wars}
+ *   layout={intervalLanesLayout}
+ *   categoryAccessor="sphere"
+ *   valueAccessor="startYear"
+ *   oExtent={SPHERES}
+ *   layoutConfig={{
+ *     laneAccessor: "sphere", startAccessor: "startYear", endAccessor: "endYear",
+ *     domain: [1775, 2015], unit: 1, color: (d, lane) => COLORS[lane],
+ *     axisTicks: [1800, 1850, 1900, 1950, 2000],
+ *   }}
+ *   width={900} height={620}
+ * />
+ * ```
+ */
+export interface IntervalLanesConfig<T = Datum> {
+    /** Which lane each record belongs to. */
+    laneAccessor: string | ((d: T) => string);
+    /** Interval start, in the same units as `domain`. */
+    startAccessor: string | ((d: T) => number);
+    /** Interval end, in the same units as `domain`. */
+    endAccessor: string | ((d: T) => number);
+    /** `[min, max]` of the time axis. */
+    domain: [number, number];
+    /** Lane order. @default the chart's `o` scale domain (its `oExtent`), else the
+     *  distinct lane values in first-seen order. */
+    lanes?: string[];
+    /** Per-record fill. @default `ctx.resolveColor(lane)`. */
+    color?: (d: T, lane: string) => string;
+    /** Stable id per record → bar transition identity. @default none */
+    idAccessor?: string | ((d: T) => string);
+    /** Extend each bar this many domain units past `end`, so inclusive whole-unit
+     *  intervals (e.g. years) fill their final unit. @default 0 */
+    unit?: number;
+    /** Vertical gap between stacked sub-tracks, px. @default 1.5 */
+    barGap?: number;
+    /** Minimum rendered interval width, px. Keeps zero- and short-duration
+     *  events visible and hoverable on long domains. @default 2 */
+    minBarWidth?: number;
+    /** @default 3.5 */
+    minBarHeight?: number;
+    /** @default 10 */
+    maxBarHeight?: number;
+    /** Vertical padding inside each lane, px. @default 7 */
+    lanePadding?: number;
+    /** Bar corner radius, px. @default 2 */
+    cornerRadius?: number;
+    /** Reserve this many px at the bottom (for a caller-drawn strip, e.g. a
+     *  concurrency line). Lanes fill the remaining height. @default 0 */
+    bottomInset?: number;
+    /** Draw a label to the left of each lane. @default true */
+    showLaneLabels?: boolean;
+    /** Gap between the plot's left edge and lane labels, px. @default 12 */
+    laneLabelGap?: number;
+    /** Alternating background period bands across the full plot height. */
+    periods?: Array<{
+        start: number;
+        end: number;
+        name?: string;
+    }>;
+    /** Draw a top time axis with gridlines. @default true */
+    showAxis?: boolean;
+    /** Explicit axis tick values. @default ~7 evenly-spaced across `domain`. */
+    axisTicks?: number[];
+    /** Format axis tick labels. @default `String` */
+    tickFormat?: (v: number) => string;
+}
+export declare const intervalLanesLayout: OrdinalCustomLayout<IntervalLanesConfig>;

package/dist/components/recipes/intervals.d.ts

@@ -0,0 +1,80 @@
+import type { Datum } from "../charts/shared/datumTypes";
+/**
+ * Interval (Gantt/timeline) packing + temporal-density helpers — the generic
+ * geometry behind any "events that overlap in time" view. A swimlane/Gantt
+ * layout packs concurrent intervals into sub-tracks; its natural companion is a
+ * concurrency line counting how many intervals are active over the domain.
+ *
+ * Pure / SSR-safe. Accessors may be a field name or a function.
+ */
+type Accessor<T> = string | ((item: T) => number);
+export interface PackedInterval<T> {
+    /** The original item. */
+    item: T;
+    /** Zero-based sub-track index the greedy packer assigned. Concurrent
+     *  intervals get distinct tracks; non-overlapping intervals reuse a track. */
+    track: number;
+}
+export interface PackIntervalsResult<T> {
+    /** Each input item paired with its assigned sub-track. Input order preserved
+     *  unless `sort` is left on (the default), which sorts by start ascending. */
+    packed: PackedInterval<T>[];
+    /** Number of sub-tracks used — the lane needs this many rows. */
+    trackCount: number;
+}
+export interface PackIntervalsOptions<T> {
+    /** Interval start accessor. @default `"start"` */
+    start?: Accessor<T>;
+    /** Interval end accessor. @default `"end"` */
+    end?: Accessor<T>;
+    /** Sort by start ascending (then longest-first) before packing — the stable,
+     *  gap-minimizing order. Set `false` if the input is already ordered and you
+     *  want that order preserved. @default true */
+    sort?: boolean;
+}
+/**
+ * Greedy interval packing: assign each interval to the first sub-track whose
+ * last interval has already ended, otherwise open a new track. The textbook
+ * Gantt/swimlane packer. O(n·tracks).
+ *
+ * @example
+ * ```ts
+ * const { packed, trackCount } = packIntervals(wars, { start: "startTime", end: "endTime" })
+ * // bar y = laneTop + track * (barHeight + gap)
+ * ```
+ */
+export declare function packIntervals<T = Datum>(items: readonly T[], options?: PackIntervalsOptions<T>): PackIntervalsResult<T>;
+export interface ActiveCount {
+    /** Domain position (e.g. a year). */
+    value: number;
+    /** Number of intervals active at this position. */
+    count: number;
+}
+export interface ActiveCountOptions<T> {
+    /** Interval start accessor. @default `"start"` */
+    start?: Accessor<T>;
+    /** Interval end accessor. @default `"end"` */
+    end?: Accessor<T>;
+    /** `[min, max]` domain to sample across (inclusive of both ends). */
+    domain: [number, number];
+    /** Sample spacing. @default 1 */
+    step?: number;
+    /** Count an interval active at position `v` when `start <= v <= end`
+     *  (`"closed"`, the default — natural for whole-unit intervals like years),
+     *  or when `start <= v < end` (`"half-open"`). @default "closed" */
+    bounds?: "closed" | "half-open";
+}
+/**
+ * Count how many intervals are active at each sampled position across a domain —
+ * the concurrency series you draw as a step line beneath packed interval lanes.
+ *
+ * @example
+ * ```ts
+ * const counts = activeCountOverDomain(wars, {
+ *   start: "startYear", end: "endYear", domain: [1775, 2015],
+ * })
+ * // → [{ value: 1775, count: 1 }, { value: 1776, count: 2 }, ...]
+ * ```
+ */
+export declare function activeCountOverDomain<T = Datum>(items: readonly T[], options: ActiveCountOptions<T>): ActiveCount[];
+export {};

package/dist/components/recipes/isometricLandmarks.d.ts

@@ -0,0 +1,88 @@
+import type { Datum } from "../charts/shared/datumTypes";
+import type { GeoCustomLayout } from "../stream/geoCustomLayout";
+export type LandmarkKind = "city" | "culture" | "monument" | "faith" | "nature" | "knowledge" | "defense" | "arena" | "transport";
+export type IsometricTerrainKind = "land" | "ocean" | "forest" | "grassland" | "cropland" | "wetland" | "urban" | "scrub" | "bare" | "snow";
+export interface IsometricTerrainCell {
+    kind: IsometricTerrainKind;
+    /** Fraction of the geographic cell covered by this terrain, from 0 to 1. */
+    coverage?: number;
+    /** Optional per-cell color override. */
+    fill?: string;
+}
+export interface IsometricLandmarkConfig {
+    /** Geographic center represented by the middle grid cell. */
+    center: {
+        lon: number;
+        lat: number;
+    };
+    /** Datum id forced into the middle cell. */
+    centerId?: string;
+    /** Odd number of rows/columns. @default 5 */
+    gridSize?: number;
+    /** Half-width of the local square represented by the board. @default 75 */
+    gridRadiusKm?: number;
+    /** Isometric tile dimensions in pixels. @default 80×40 */
+    tileWidth?: number;
+    tileHeight?: number;
+    /** Source-data accessors. */
+    idAccessor?: string | ((d: Datum) => string);
+    nameAccessor?: string | ((d: Datum) => string);
+    longitudeAccessor?: string | ((d: Datum) => number);
+    latitudeAccessor?: string | ((d: Datum) => number);
+    kindAccessor?: string | ((d: Datum) => LandmarkKind);
+    /** Lower values win when live and fallback candidates share a cell. */
+    candidatePriorityAccessor?: string | ((d: Datum) => number);
+    /** Optional replacement sprite URLs. Transparent PNGs work best. */
+    sprites?: Partial<Record<LandmarkKind, string>>;
+    /** Rendered resource sprite size. @default 32 */
+    resourceSpriteSize?: number;
+    /** Rendered major-city sprite size. @default 64 */
+    citySpriteSize?: number;
+    /** Civ-style terrain palette. */
+    terrainColors?: string[];
+    /** Geographic terrain classification keyed by `tile-{row}-{column}`. */
+    terrainByCell?: Record<string, IsometricTerrainKind | IsometricTerrainCell>;
+    /** Civ-style colors used for classified terrain cells. */
+    terrainPalette?: Partial<Record<IsometricTerrainKind, string>>;
+    tileStroke?: string;
+    showCityLabel?: boolean;
+}
+export interface IsometricLandmarkTile {
+    id: string;
+    row: number;
+    column: number;
+    centerXKm: number;
+    centerYKm: number;
+    terrainIndex: number;
+    landmark: (Datum & {
+        id: string;
+        name: string;
+        kind: LandmarkKind;
+        lon: number;
+        lat: number;
+        distanceKm: number;
+    }) | null;
+    /** All candidates assigned to the cell, with the displayed landmark first. */
+    landmarks: Array<Datum & {
+        id: string;
+        name: string;
+        kind: LandmarkKind;
+        lon: number;
+        lat: number;
+        distanceKm: number;
+    }>;
+}
+export declare const DEFAULT_ISOMETRIC_SPRITE_SIZES: {
+    readonly resource: 32;
+    readonly city: 64;
+};
+/**
+ * Quantize geographic landmarks into an odd square grid and choose one
+ * representative per cell. Selection balances proximity to the cell center
+ * with category reuse so a dense class does not consume the whole board.
+ */
+export declare function selectIsometricLandmarks(points: Datum[], config: IsometricLandmarkConfig): IsometricLandmarkTile[];
+/**
+ * Isometric landmark board for `GeoCustomChart`.
+ */
+export declare const isometricLandmarkLayout: GeoCustomLayout<IsometricLandmarkConfig>;

package/dist/components/recipes/isotypeGlyphs.d.ts

@@ -0,0 +1,17 @@
+import type { GlyphDef } from "../stream/glyphDef";
+export declare const isotypeInk = "#334155";
+export declare const isotypePaper = "#f8fafc";
+export declare const isotypeGhost = "#cbd5e1";
+export declare const isotypeServerGlyph: GlyphDef;
+export declare const isotypeChipGlyph: GlyphDef;
+export declare const isotypeBoltGlyph: GlyphDef;
+export declare const isotypeBusGlyph: GlyphDef;
+export declare const isotypePersonPath = "M 9.12,3.34 C 8.28,3.29 7.44,3.40 6.64,3.69 4.17,3.63 1.97,5.37 0.91,7.51 -1.32,11.80 2.55,17.76 8.19,16.55 11.62,16.13 15.55,14.04 16.17,10.33 16.38,6.53 12.77,3.52 9.12,3.34 Z M 9.35,19.86 C 8.89,19.84 8.41,19.92 7.92,20.11 5.12,21.55 3.72,24.68 2.79,27.54 2.32,29.86 0.87,32.04 1.36,34.49 1.63,37.60 8.04,38.95 8.04,38.95 8.04,38.95 14.67,39.65 16.50,36.33 17.16,31.95 16.34,27.23 14.01,23.42 13.07,21.69 11.36,19.92 9.35,19.86 Z";
+export declare const isotypePersonGlyph: GlyphDef;
+export declare const isotypeNetworkGlyphs: {
+    readonly server: GlyphDef;
+    readonly chip: GlyphDef;
+    readonly bolt: GlyphDef;
+    readonly bus: GlyphDef;
+    readonly person: GlyphDef;
+};

package/dist/components/recipes/mermaidDag.d.ts

@@ -0,0 +1,44 @@
+import type { NetworkCustomLayout } from "../stream/networkCustomLayout";
+/**
+ * Layered flowchart layout for the Mermaid adapter (and any pre-layered DAG).
+ *
+ * A Mermaid flowchart is a directed acyclic graph, not a force graph — so it
+ * should render as a *layered diagram* with shape-appropriate node glyphs,
+ * directional arrows, and edge labels, the way Mermaid draws it. This recipe
+ * does exactly that from the `layer`/`row` coordinates `fromMermaid` already
+ * computes (longest-path layering), so it needs **no layout engine and no new
+ * dependency**. It ships in `semiotic/recipes`, so it tree-shakes — you only
+ * pull it in if you use it.
+ *
+ * For large or dense graphs where crossing-minimization matters, run a real
+ * Sugiyama layouter (the BYO `dagre` recipe, or `d3-dag`) to assign
+ * `layer`/`row`, then render with this layout — the rendering and the
+ * positioning are deliberately separate concerns.
+ *
+ * Pure, SSR-safe: hit-testable rects are emitted as scene nodes; all visual
+ * chrome (shape glyphs, labels, edges, arrowheads, edge labels) is an SVG
+ * `overlays` group painted on top, in plot-relative coordinates.
+ */
+export type MermaidDirection = "TD" | "TB" | "BT" | "LR" | "RL";
+export interface MermaidDagConfig {
+    /** Flow direction. TD/TB top-down, BT bottom-up, LR left-right, RL right-left. @default "TD" */
+    direction?: MermaidDirection;
+    /** Glyph width / height in px (shrunk to fit). @default 150 / 46 */
+    nodeWidth?: number;
+    nodeHeight?: number;
+    /** Node field accessors. @default "layer" / "row" / "label" / "shape" */
+    layerAccessor?: string;
+    rowAccessor?: string;
+    labelAccessor?: string;
+    shapeAccessor?: string;
+    /** Edge label field. @default "label" */
+    edgeLabelAccessor?: string;
+    /** Colors (CSS vars by default so they follow the theme). */
+    nodeFill?: string;
+    nodeStroke?: string;
+    textColor?: string;
+    edgeColor?: string;
+    /** Stroke for decision (diamond) glyphs. */
+    accentColor?: string;
+}
+export declare const mermaidDagLayout: NetworkCustomLayout<MermaidDagConfig>;

package/dist/components/recipes/mobileAnnotationStrategy.d.ts

@@ -0,0 +1,48 @@
+import type { Datum } from "../charts/shared/datumTypes";
+export type MobileAnnotationStrategyMode = "plot" | "callout-list" | "hybrid";
+export interface MobileAnnotationStrategyConfig {
+    /** Activate the strategy explicitly. When omitted, width/breakpoint decides. */
+    active?: boolean;
+    /** Measured plot/container width in CSS pixels. */
+    width?: number;
+    /** Width at or below which the strategy activates. Default 480. */
+    breakpoint?: number;
+    /** Plot-only, list-only, or hybrid visible-plus-list behavior. Default "hybrid". */
+    strategy?: MobileAnnotationStrategyMode;
+    /** Maximum persistent note annotations left in the plot. Alias: maxAnnotations. */
+    maxPlotAnnotations?: number;
+    maxAnnotations?: number;
+    /** Minimum number of note annotations kept in the plot. Default 1. */
+    minPlotAnnotations?: number;
+    minVisible?: number;
+    /** Maximum callout-list items. Default 6. */
+    maxCalloutItems?: number;
+    /** Keep primary/emergency notes in the plot before lower-priority notes. Default true. */
+    preservePrimary?: boolean;
+    /** Prefer mobileText/shortText over full label. Default true. */
+    preferShortText?: boolean;
+    /** Field or function used as an explicit priority score. */
+    priorityAccessor?: string | ((annotation: Datum, index: number) => number | undefined);
+    /** Optional filter for annotations that should move into the callout list. */
+    calloutFilter?: (annotation: Datum, index: number) => boolean;
+}
+export interface MobileAnnotationCalloutItem {
+    id: string;
+    label: string;
+    shortLabel?: string;
+    pointId?: string | number;
+    emphasis?: string;
+    source?: string;
+    priority: number;
+    annotation: Datum;
+}
+export interface MobileAnnotationStrategyResult {
+    active: boolean;
+    strategy: MobileAnnotationStrategyMode;
+    budget: number;
+    visible: Datum[];
+    deferred: Datum[];
+    calloutList: MobileAnnotationCalloutItem[];
+    hidden: Datum[];
+}
+export declare function mobileAnnotationStrategy(annotations: readonly Datum[] | undefined, config?: MobileAnnotationStrategyConfig): MobileAnnotationStrategyResult;

package/dist/components/recipes/mobileChartFamilyRecipes.d.ts

@@ -0,0 +1,59 @@
+import type { ResponsiveRule } from "../charts/shared/responsiveRules";
+import type { MobileInteractionConfig, MobileSnapBehavior, MobileStandardControlsMode } from "../charts/shared/types";
+import type { MobileVisualizationContract } from "../charts/shared/auditMobileVisualization";
+export type MobileChartFamily = "line" | "area" | "ordinal" | "scatter" | "network" | "geo" | "small-multiple";
+export interface MobileChartFamilyRecipeOptions {
+    breakpoint?: number;
+    targetSize?: number;
+    mode?: "mobile" | false;
+    density?: "comfortable" | "compact" | "dense";
+    transformProfile?: "overview" | "compare" | "inspect";
+    keepAxes?: boolean;
+    showLegend?: boolean;
+    directLabel?: boolean;
+    maxAnnotations?: number;
+    maxCalloutItems?: number;
+    chartHeight?: number;
+    mobileColumns?: number;
+    tabletColumns?: number;
+    snap?: MobileSnapBehavior;
+    standardControls?: MobileStandardControlsMode;
+    summary?: string;
+}
+export interface MobileChartFamilyRecipe {
+    family: MobileChartFamily;
+    props: Record<string, unknown>;
+    responsiveRules: ResponsiveRule<Record<string, unknown>>[];
+    mobileInteraction: MobileInteractionConfig;
+    mobileSemantics: MobileVisualizationContract;
+}
+export declare function mobileLineChartRecipe(options?: MobileChartFamilyRecipeOptions): MobileChartFamilyRecipe;
+export declare function mobileAreaChartRecipe(options?: MobileChartFamilyRecipeOptions): MobileChartFamilyRecipe;
+export declare function mobileOrdinalChartRecipe(options?: MobileChartFamilyRecipeOptions): MobileChartFamilyRecipe;
+export declare function mobileScatterplotRecipe(options?: MobileChartFamilyRecipeOptions): MobileChartFamilyRecipe;
+export declare function mobileNetworkChartRecipe(options?: MobileChartFamilyRecipeOptions): MobileChartFamilyRecipe;
+export declare function mobileGeoChartRecipe(options?: MobileChartFamilyRecipeOptions): MobileChartFamilyRecipe;
+export declare function mobileSmallMultipleRecipe(options?: MobileChartFamilyRecipeOptions): MobileChartFamilyRecipe;
+export declare function mobileChartFamilyRecipe(family: MobileChartFamily, options?: MobileChartFamilyRecipeOptions): MobileChartFamilyRecipe;
+export interface MobileBrushAlternativeOptions {
+    targetSize?: number;
+    controls?: Array<"range-inputs" | "chip-filter" | "clear" | "stepper">;
+    summary?: string;
+}
+export declare function mobileBrushAlternatives(options?: MobileBrushAlternativeOptions): {
+    mobileInteraction: {
+        enabled: boolean;
+        targetSize: number;
+        tapToSelect: boolean;
+        tapToLockTooltip: boolean;
+        standardControls: "brush";
+    };
+    mobileSemantics: {
+        interaction: {
+            primary: "filter";
+            alternatives: ("clear" | "range-inputs" | "chip-filter" | "stepper")[];
+            summary: string;
+        };
+    };
+    controls: ("clear" | "range-inputs" | "chip-filter" | "stepper")[];
+};

package/dist/components/recipes/networkAnalysis.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Network-analysis kit — pure graph algorithms for network visualizations.
+ *
+ * These are the primitives most network charts end up hand-rolling: adjacency,
+ * breadth-first distances, shortest paths, ego networks, degree / betweenness /
+ * closeness centrality, clustering coefficient, and the "spatial problem"
+ * detector (nodes drawn closer than their graph distance warrants). They pair
+ * naturally with `ForceDirectedGraph`, `NetworkCustomChart`, and the layout
+ * recipes: size nodes by centrality, highlight an ego network on hover, trace a
+ * shortest path, or diagnose a misleading layout.
+ *
+ * All functions are pure and dependency-free. Edges are treated as undirected.
+ */
+export interface GraphNode {
+    id: string;
+}
+export interface GraphEdge {
+    source: string;
+    target: string;
+    value?: number;
+}
+export interface Point {
+    x: number;
+    y: number;
+}
+/** Build an undirected adjacency map: node id → set of neighbor ids. */
+export declare function buildAdjacency(nodes: ReadonlyArray<GraphNode>, edges: ReadonlyArray<GraphEdge>): Map<string, Set<string>>;
+/**
+ * Build a **directed** adjacency map: node id → set of successor ids, following
+ * `source → target` only. The directed sibling of {@link buildAdjacency}, for
+ * DAG / flow / dependency graphs where edge direction carries meaning.
+ */
+export declare function buildDirectedAdjacency(nodes: ReadonlyArray<GraphNode>, edges: ReadonlyArray<GraphEdge>): Map<string, Set<string>>;
+/**
+ * The set of nodes reachable from `start` by following the adjacency (BFS).
+ * Works on either an undirected ({@link buildAdjacency}) or directed
+ * ({@link buildDirectedAdjacency}) adjacency map.
+ *
+ * `start` itself is excluded unless it is reachable via a cycle, or
+ * `includeStart` is set — so on a DAG this is exactly the descendant set, and
+ * on a cyclic graph a node that can reach itself is reported as such.
+ */
+export declare function reachableFrom(adjacency: Map<string, Set<string>>, start: string, options?: {
+    includeStart?: boolean;
+}): Set<string>;
+/** Degree (neighbor count) per node id. */
+export declare function degree(nodes: ReadonlyArray<GraphNode>, edges: ReadonlyArray<GraphEdge>): Record<string, number>;
+/** Breadth-first hop distance from `start` to every reachable node. */
+export declare function bfsDistances(adjacency: Map<string, Set<string>>, start: string): Record<string, number>;
+/**
+ * Unweighted shortest path between two node ids (BFS). Returns the path as an
+ * ordered list of ids (inclusive of both ends), or `[]` if unreachable.
+ */
+export declare function shortestPath(nodes: ReadonlyArray<GraphNode>, edges: ReadonlyArray<GraphEdge>, source: string, target: string): string[];
+/**
+ * The ego network of a node: itself plus every node within `depth` hops.
+ * Returns the set of member ids (use it to highlight neighbors on hover).
+ */
+export declare function egoNetwork(nodes: ReadonlyArray<GraphNode>, edges: ReadonlyArray<GraphEdge>, id: string, depth?: number): Set<string>;
+/**
+ * Betweenness centrality (Brandes' algorithm, unweighted, undirected). Higher
+ * scores mark bridge nodes that many shortest paths pass through. Raw scores;
+ * wrap with {@link normalizeScores} for a 0–1 encoding (e.g. node size).
+ */
+export declare function betweenness(nodes: ReadonlyArray<GraphNode>, edges: ReadonlyArray<GraphEdge>): Record<string, number>;
+/**
+ * Closeness centrality: the inverse of the mean shortest-path distance to all
+ * reachable nodes. Higher = more central. Raw scores; see {@link normalizeScores}.
+ */
+export declare function closeness(nodes: ReadonlyArray<GraphNode>, edges: ReadonlyArray<GraphEdge>): Record<string, number>;
+/**
+ * Local clustering coefficient per node (0–1): the fraction of a node's
+ * neighbor pairs that are themselves connected.
+ */
+export declare function clustering(nodes: ReadonlyArray<GraphNode>, edges: ReadonlyArray<GraphEdge>): Record<string, number>;
+/** Rescale a score map to 0–1 by its maximum (for size/opacity encodings). */
+export declare function normalizeScores(scores: Record<string, number>): Record<string, number>;
+export interface ProximityProblemOptions {
+    /** Minimum graph-hop distance for a pair to count as "far". @default 4 */
+    minHops?: number;
+    /** Starting screen-distance threshold (in the units of `positions`). @default 0.08 */
+    startThreshold?: number;
+    /** Cap the threshold search at this distance before relaxing `minHops`. @default 0.2 */
+    maxThreshold?: number;
+}
+export interface ProximityProblemResult {
+    /** Ids drawn misleadingly close given their graph distance. */
+    problemIds: Set<string>;
+    /** The screen-distance threshold at which offenders were found. */
+    threshold: number;
+    /** The graph-hop distance used. */
+    minHops: number;
+}
+/**
+ * The "spatial problem": find nodes drawn near each other on screen yet far
+ * apart (or disconnected) in the graph — proximity pretending to be kinship,
+ * the classic force-layout lie. `positions` is a map of node id → screen point
+ * (any consistent coordinate space; distances are compared in those units).
+ * The search escalates the distance threshold, then relaxes `minHops`, until at
+ * least one offending pair is found.
+ */
+export declare function proximityProblem(nodes: ReadonlyArray<GraphNode>, edges: ReadonlyArray<GraphEdge>, positions: Record<string, Point>, options?: ProximityProblemOptions): ProximityProblemResult;

package/dist/components/recipes/networkLayouts.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Deterministic, physics-free network layouts — the classic static forms that
+ * predate (and often out-read) the force-directed hairball: the arc diagram,
+ * the adjacency matrix, and the circular layout.
+ *
+ * These are composable positioner / structure helpers (not full scene layouts):
+ * they return normalized positions or a matrix structure that you render inside
+ * a `NetworkCustomChart` layout, so you keep full control of styling. Pure and
+ * dependency-free.
+ */
+import type { GraphNode, GraphEdge, Point } from "./networkAnalysis";
+/**
+ * Order node ids by community/group then descending degree, so related nodes sit
+ * together and hubs lead — the ordering that makes arc diagrams and adjacency
+ * matrices legible. Pass `groupAccessor` to read the grouping field (default
+ * `"group"`); nodes without one are ordered by degree alone.
+ */
+export declare function orderByGroupDegree<N extends GraphNode>(nodes: ReadonlyArray<N>, edges: ReadonlyArray<GraphEdge>, groupAccessor?: keyof N | ((n: N) => number | string)): string[];
+export interface ArcLayoutOptions {
+    /** Baseline y position in [0, 1]. @default 0.62 */
+    baseline?: number;
+    /** Horizontal inset kept clear at each end, in [0, 0.5). @default 0.06 */
+    inset?: number;
+}
+/**
+ * Arc diagram: lay the ordered ids out along a horizontal baseline. Draw each
+ * edge as an arc with {@link arcPath}. Returns id → {x, y} in [0, 1].
+ */
+export declare function arcLayout(ids: ReadonlyArray<string>, options?: ArcLayoutOptions): Record<string, Point>;
+/**
+ * An SVG path string for an arc between two points that share a baseline (as in
+ * an arc diagram). The arc bows away from the baseline by `heightRatio` of the
+ * span. Coordinates are whatever space you pass (typically already projected
+ * into the plot).
+ */
+export declare function arcPath(a: Point, b: Point, heightRatio?: number): string;
+export interface CircularLayoutOptions {
+    /** Ring radius in [0, 0.5]. @default 0.42 */
+    radius?: number;
+    /** Center point in [0, 1]. @default { x: 0.5, y: 0.5 } */
+    center?: Point;
+    /** Start angle in radians (0 = up). @default 0 */
+    startAngle?: number;
+}
+/**
+ * Circular layout: place the ordered ids evenly around a ring. Position carries
+ * no meaning (edges cross the interior) — offered mainly as a labeled, stable
+ * arrangement. Returns id → {x, y} in [0, 1].
+ */
+export declare function circularLayout(ids: ReadonlyArray<string>, options?: CircularLayoutOptions): Record<string, Point>;
+export interface MatrixCell {
+    /** Row index (into the ordered id list). */
+    row: number;
+    /** Column index. */
+    col: number;
+    source: string;
+    target: string;
+    /** Summed edge value between the pair (defaults to 1 per edge). */
+    value: number;
+}
+export interface AdjacencyMatrix {
+    /** The ordered ids used for rows and columns. */
+    order: string[];
+    /** One cell per connected (i, j) pair, both triangles (symmetric). */
+    cells: MatrixCell[];
+    /** Number of rows/columns (`order.length`). */
+    size: number;
+    /** Maximum cell value (for opacity/intensity encoding). */
+    maxValue: number;
+}
+export interface AdjacencyMatrixOptions {
+    /** Explicit row/column order; defaults to {@link orderByGroupDegree}. */
+    order?: ReadonlyArray<string>;
+    /** Group accessor used when computing the default order. @default "group" */
+    groupAccessor?: keyof GraphNode | ((n: GraphNode) => number | string);
+}
+/**
+ * Adjacency matrix structure: every connection becomes a filled cell, so nothing
+ * overlaps and dense graphs stay legible. Returns the ordered ids plus the cell
+ * list; render each cell at `(col, row)` in your layout. Symmetric (both
+ * triangles filled); the diagonal is omitted.
+ */
+export declare function adjacencyMatrix(nodes: ReadonlyArray<GraphNode>, edges: ReadonlyArray<GraphEdge>, options?: AdjacencyMatrixOptions): AdjacencyMatrix;