semiotic 3.7.5 → 3.8.1

package/dist/components/stream/networkColorAccessors.d.ts

@@ -0,0 +1,49 @@
+import type { Datum } from "../charts/shared/datumTypes";
+import type { RealtimeEdge, RealtimeNode } from "./networkTypes";
+export declare function resolveNetworkEdgeEndpoint(endpoint: RealtimeNode | string | undefined, nodes: Map<string, RealtimeNode> | undefined): RealtimeNode | null;
+export declare function resolveNetworkNodeColor(options: {
+    node: RealtimeNode;
+    colorBy?: string | ((node: RealtimeNode) => unknown);
+    colorScheme?: string | string[] | Record<string, string>;
+    nodeColorMap: Map<string, string>;
+    colorIndexRef: {
+        current: number;
+    };
+}): string;
+export declare function resolveNetworkEdgeColor(options: {
+    edge: RealtimeEdge;
+    edgeColorBy?: string | ((edge: RealtimeEdge) => string);
+    getNodeColor: (node: RealtimeNode) => string;
+    resolveEndpoint: (endpoint: RealtimeNode | string | undefined) => RealtimeNode | null;
+    fallback: string;
+}): string;
+export declare function resolveNetworkParticleColor(options: {
+    edge: RealtimeEdge;
+    particleStyleColor?: string | ((edge: RealtimeEdge, node: RealtimeNode) => string);
+    particleColorBy?: string;
+    hasExplicitParticleColorBy: boolean;
+    getEdgeColor: (edge: RealtimeEdge) => string;
+    getNodeColor: (node: RealtimeNode) => string;
+    resolveEndpoint: (endpoint: RealtimeNode | string | undefined) => RealtimeNode | null;
+    fallback: string;
+}): string;
+/** Sync scene fills into the node color map; fill gaps from palette. */
+export declare function syncNetworkNodeColorMap(options: {
+    sceneNodes: ReadonlyArray<{
+        id?: string;
+        style?: {
+            fill?: unknown;
+        };
+    }>;
+    nodes: Iterable<RealtimeNode>;
+    nodeColorMap: Map<string, string>;
+    colorScheme?: string | string[] | Record<string, string>;
+}): number;
+export declare function networkEdgeFallbackColor(theme: {
+    colors?: {
+        border?: string;
+        secondary?: string;
+        primary?: string;
+    };
+} | null | undefined): string;
+export type { Datum };

package/dist/components/stream/networkCustomLayoutRunner.d.ts

@@ -0,0 +1,23 @@
+import type { NetworkLayoutResult } from "./networkCustomLayout";
+import { type CustomLayoutFailureDiagnostic } from "./customLayoutFailure";
+import type { NetworkPipelineConfig, RealtimeEdge, RealtimeNode } from "./networkTypes";
+interface NetworkCustomLayoutRunInput {
+    config: NetworkPipelineConfig;
+    customLayout: NonNullable<NetworkPipelineConfig["customNetworkLayout"]>;
+    size: [number, number];
+    nodes: RealtimeNode[];
+    edges: RealtimeEdge[];
+    previousResult: NetworkLayoutResult | null;
+    revision: number;
+}
+export type NetworkCustomLayoutRunResult = {
+    kind: "success";
+    result: NetworkLayoutResult;
+} | {
+    kind: "failure";
+    diagnostic: CustomLayoutFailureDiagnostic;
+    preservedLastGoodScene: boolean;
+};
+/** Runs user-provided network layout code behind the common failure boundary. */
+export declare function runNetworkCustomLayout({ config, customLayout, size, nodes, edges, previousResult, revision }: NetworkCustomLayoutRunInput): NetworkCustomLayoutRunResult;
+export {};

package/dist/components/stream/networkCustomRestyle.d.ts

@@ -0,0 +1,15 @@
+import type { CustomLayoutSelection } from "./customLayoutSelection";
+import type { NetworkLayoutResult } from "./networkCustomLayout";
+import type { NetworkSceneEdge, NetworkSceneNode } from "./networkTypes";
+import type { Style } from "./types";
+export declare function snapshotNetworkCustomStyles(nodes: NetworkSceneNode[], edges: NetworkSceneEdge[]): WeakMap<object, Style>;
+interface NetworkRestyleInput {
+    nodes: NetworkSceneNode[];
+    edges: NetworkSceneEdge[];
+    restyle: NetworkLayoutResult["restyle"];
+    restyleEdge: NetworkLayoutResult["restyleEdge"];
+    baseStyles: WeakMap<object, Style>;
+    selection: CustomLayoutSelection | null;
+}
+export declare function restyleNetworkCustomScene({ nodes, edges, restyle, restyleEdge, baseStyles, selection }: NetworkRestyleInput): boolean;
+export {};

package/dist/components/stream/networkDefaultTooltip.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Default network hover tooltip for StreamNetworkFrame.
+ * Uses shared `defaultTooltipStyle` for theme CSS-var consistency.
+ */
+import * as React from "react";
+import type { HoverData } from "../realtime/types";
+declare function DefaultNetworkTooltip({ data }: {
+    data: HoverData;
+}): React.JSX.Element | null;
+export { DefaultNetworkTooltip };

package/dist/components/stream/networkFrameAnimation.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Whether the network paint loop needs another animation frame.
+ *
+ * Particles are continuous only for sankey and custom layouts; pulse and
+ * pipeline animations apply to every chart type.
+ */
+export declare function shouldContinueNetworkAnimation(chartType: string, hasCustomNetworkLayout: boolean, showParticles: boolean, hasPulse: boolean, isStoreAnimating: boolean): boolean;

package/dist/components/stream/networkFrameHandleTypes.d.ts

@@ -0,0 +1,39 @@
+import type { Datum } from "../charts/shared/datumTypes";
+import type { EdgePush, RealtimeEdge, RealtimeNode } from "./networkTypes";
+import type { CustomLayoutFailureDiagnostic } from "./customLayoutFailure";
+import type { NetworkLayoutResult } from "./networkCustomLayout";
+/** Imperative API exposed by `StreamNetworkFrame` refs. */
+export interface StreamNetworkFrameHandle {
+    push(edge: EdgePush): void;
+    pushMany(edges: EdgePush[]): void;
+    /** Remove a node by ID. Also removes connected edges. */
+    removeNode(id: string): boolean;
+    /** Remove edges by source+target, or by edge ID when edgeIdAccessor is configured. */
+    removeEdge(sourceIdOrEdgeId: string, targetId?: string): boolean;
+    /** Update a node's data by ID. Returns previous data. */
+    updateNode(id: string, updater: (data: Datum) => Datum): Datum | null;
+    /** Update all edges between source+target. Returns array of previous data. */
+    updateEdge(sourceId: string, targetId: string, updater: (data: Datum) => Datum): Datum[];
+    clear(): void;
+    getTopology(): {
+        nodes: RealtimeNode[];
+        edges: RealtimeEdge[];
+    };
+    getTopologyDiff(): {
+        addedNodes: string[];
+        removedNodes: string[];
+        addedEdges: string[];
+        removedEdges: string[];
+    };
+    relayout(): void;
+    getTension(): number;
+    /** The most recent custom layout result (sceneNodes/sceneEdges/overlays as
+     *  returned by `customNetworkLayout`) - host readback so pages that need the
+     *  computed placement do not re-run the layout. Null before the first layout
+     *  or when no custom layout is configured. A failed retry retains the prior
+     *  good result; inspect `getLayoutFailure()` to distinguish recovery. */
+    getCustomLayout(): NetworkLayoutResult | null;
+    /** The latest custom-layout failure, if any. Cleared by a successful layout,
+     * removing the custom layout, or `clear()`. */
+    getLayoutFailure(): CustomLayoutFailureDiagnostic | null;
+}

package/dist/components/stream/networkFrameInteraction.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Pointer hit-testing helpers for StreamNetworkFrame hover/click.
+ * Returns a structured result so the frame owns React setState.
+ */
+import type { HoverData } from "../realtime/types";
+import { type HoverPointerCoords } from "./hoverUtils";
+import type { NetworkSceneEdge, NetworkSceneNode } from "./networkTypes";
+import type { Quadtree } from "d3-quadtree";
+import type { NetworkCircleNode } from "./networkTypes";
+export type NetworkPointerHit = {
+    kind: "miss-outside";
+} | {
+    kind: "miss";
+} | {
+    kind: "hit";
+    hover: HoverData;
+};
+export declare function resolveNetworkPointerHit(options: {
+    clientX: number;
+    clientY: number;
+    canvasRect: DOMRect;
+    margin: {
+        left: number;
+        top: number;
+    };
+    adjustedWidth: number;
+    adjustedHeight: number;
+    sceneNodes: NetworkSceneNode[];
+    sceneEdges: NetworkSceneEdge[];
+    nodeQuadtree: Quadtree<NetworkCircleNode> | null;
+    maxNodeRadius: number;
+    hitRadius?: number;
+}): NetworkPointerHit;
+export declare function pointerFromMouseEvent(e: {
+    clientX: number;
+    clientY: number;
+}): HoverPointerCoords;

package/dist/components/stream/networkFrameObservations.d.ts

@@ -0,0 +1,15 @@
+import { type SemanticClickBehavior, type SemanticHoverBehavior } from "../charts/shared/semanticInteractions";
+import type { HoverData } from "../realtime/types";
+import type { OnObservationCallback } from "../store/ObservationStore";
+interface NetworkObservationBehaviorOptions {
+    customHoverBehavior?: SemanticHoverBehavior<HoverData>;
+    customClickBehavior?: SemanticClickBehavior<HoverData>;
+    onObservation?: OnObservationCallback;
+    chartId?: string;
+}
+/** Adds the standard observation vocabulary to the network behavior callbacks. */
+export declare function useNetworkObservationBehaviors({ customHoverBehavior: customHoverBehaviorProp, customClickBehavior: customClickBehaviorProp, onObservation, chartId }: NetworkObservationBehaviorOptions): {
+    customHoverBehavior: SemanticHoverBehavior<HoverData>;
+    customClickBehavior: SemanticClickBehavior<HoverData>;
+};
+export {};

package/dist/components/stream/networkFramePaint.d.ts

@@ -0,0 +1,52 @@
+import type { NetworkPipelineStore } from "./NetworkPipelineStore";
+import type { SceneRevisionDiagnostics } from "./sceneRevisionDiagnostics";
+import type { NetworkPipelineConfig, ParticleStyle, RealtimeEdge, NetworkSceneNode, NetworkSceneEdge } from "./networkTypes";
+import type { MarginType } from "../types/marginType";
+import type { DecayConfig, PulseConfig, StalenessConfig, SceneRenderMode } from "./types";
+export interface NetworkFramePaintContext {
+    canvas: HTMLCanvasElement;
+    store: NetworkPipelineStore;
+    sceneRevisionDiagnostics?: SceneRevisionDiagnostics;
+    size: [number, number];
+    margin: MarginType;
+    adjustedWidth: number;
+    adjustedHeight: number;
+    background?: string;
+    renderMode?: SceneRenderMode<NetworkSceneNode | NetworkSceneEdge>;
+    /** Skip opaque canvas fill when an SVG backgroundGraphics layer is present. */
+    hasBackgroundGraphics?: boolean;
+    dirtyRef: {
+        current: boolean;
+    };
+    lastFrameTimeRef: {
+        current: number;
+    };
+    /** FrameRuntime logical timestamp for this paint. */
+    now: number;
+    /** FrameRuntime random source for particle placement/spawn sampling. */
+    random: () => number;
+    reducedMotion: boolean;
+    showParticles: boolean;
+    isContinuous: boolean;
+    /** Truthy animate (boolean or config object) enables topology-diff pulses. */
+    animate: unknown;
+    decay?: DecayConfig;
+    pulse?: PulseConfig;
+    thresholds?: NetworkPipelineConfig["thresholds"];
+    staleness?: StalenessConfig;
+    particleStyle: ParticleStyle;
+    getParticleColor: (edge: RealtimeEdge, node?: unknown) => string;
+    pendingAnnotationFrameRef: {
+        current: boolean;
+    };
+    lastAnnotationFrameTimeRef: {
+        current: number;
+    };
+    setAnnotationFrame: (updater: (f: number) => number) => void;
+    scheduleNextFrame: () => void;
+}
+/**
+ * Run one paint tick. Returns whether another rAF should be scheduled
+ * (also invoked via scheduleNextFrame for continuous modes).
+ */
+export declare function paintNetworkFrame(ctx: NetworkFramePaintContext): void;

package/dist/components/stream/networkInteractionTypes.d.ts

@@ -0,0 +1,26 @@
+import type { ReactNode } from "react";
+import type { Datum } from "../charts/shared/datumTypes";
+import type { SemanticClickBehavior, SemanticHoverBehavior } from "../charts/shared/semanticInteractions";
+import type { OnAnnotationActivateCallback } from "../charts/shared/annotationActivation";
+import type { AnnotationContext, HoverData } from "../realtime/types";
+import type { AutoPlaceAnnotations } from "../recipes/annotationLayout";
+import type { OnObservationCallback } from "../store/ObservationStore";
+/** Interaction and annotation callbacks shared by every network chart layout. */
+export interface StreamNetworkInteractionProps<Node, Edge> {
+    enableHover?: boolean;
+    tooltipContent?: (d: HoverData) => ReactNode;
+    customHoverBehavior?: SemanticHoverBehavior<HoverData>;
+    customClickBehavior?: SemanticClickBehavior<HoverData>;
+    /** Observation callback — emits hover/click events to the ObservationStore and this callback. */
+    onObservation?: OnObservationCallback;
+    /** @internal HOC observation callback forwarded only to annotation widgets. */
+    annotationObservationCallback?: OnObservationCallback;
+    /** Chart instance identifier for observation filtering. */
+    chartId?: string;
+    onTopologyChange?: (nodes: Node[], edges: Edge[]) => void;
+    annotations?: Datum[];
+    /** Observe activation of widget annotations without replacing widget behavior. */
+    onAnnotationActivate?: OnAnnotationActivateCallback;
+    autoPlaceAnnotations?: AutoPlaceAnnotations;
+    svgAnnotationRules?: (annotation: Datum, index: number, context: AnnotationContext) => ReactNode;
+}

package/dist/components/stream/networkPipelineConfig.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Build NetworkPipelineConfig from StreamNetworkFrame props + theme.
+ * Keeps the large useMemo payload out of the React component file.
+ */
+import type { SemioticTheme } from "../store/ThemeStore";
+import type { NetworkPipelineConfig } from "./networkTypes";
+import type { StreamNetworkFrameProps } from "./networkTypes";
+export type NetworkPipelineConfigSources = Pick<StreamNetworkFrameProps, "chartType" | "nodeIDAccessor" | "sourceAccessor" | "targetAccessor" | "valueAccessor" | "edgeIdAccessor" | "childrenAccessor" | "hierarchySum" | "orientation" | "nodeAlign" | "nodePaddingRatio" | "nodeWidth" | "iterations" | "forceStrength" | "padAngle" | "groupWidth" | "sortGroups" | "edgeSort" | "treeOrientation" | "edgeType" | "padding" | "paddingTop" | "nodeStyle" | "edgeStyle" | "nodeLabel" | "showLabels" | "labelMode" | "colorBy" | "colorScheme" | "edgeColorBy" | "edgeOpacity" | "colorByDepth" | "nodeSize" | "nodeSizeRange" | "decay" | "pulse" | "transition" | "staleness" | "thresholds" | "orbitMode" | "orbitSize" | "orbitSpeed" | "orbitRevolution" | "orbitRevolutionStyle" | "orbitEccentricity" | "orbitShowRings" | "orbitAnimated" | "clock" | "random" | "seed" | "customNetworkLayout" | "onLayoutError" | "layoutConfig"> & {
+    tensionConfig: NetworkPipelineConfig["tensionConfig"];
+    showParticles: boolean;
+    particleStyle: NetworkPipelineConfig["particleStyle"];
+    introAnimation: boolean;
+    currentTheme: SemioticTheme | null | undefined;
+};
+export declare function buildNetworkPipelineConfig(sources: NetworkPipelineConfigSources): NetworkPipelineConfig;
+/** Fields that force re-ingest / re-layout when changed. */
+export type NetworkLayoutConfigSignature = Pick<NetworkPipelineConfigSources, "chartType" | "nodeIDAccessor" | "sourceAccessor" | "targetAccessor" | "valueAccessor" | "edgeIdAccessor" | "childrenAccessor" | "hierarchySum" | "orientation" | "nodeAlign" | "nodePaddingRatio" | "nodeWidth" | "iterations" | "forceStrength" | "padAngle" | "groupWidth" | "sortGroups" | "edgeSort" | "treeOrientation" | "edgeType" | "padding" | "paddingTop" | "random" | "seed" | "tensionConfig" | "customNetworkLayout"> & {
+    orbitMode?: NetworkPipelineConfigSources["orbitMode"];
+    orbitSize?: NetworkPipelineConfigSources["orbitSize"];
+    orbitEccentricity?: NetworkPipelineConfigSources["orbitEccentricity"];
+};
+export declare function buildNetworkLayoutConfigSignature(sources: NetworkLayoutConfigSignature): Record<string, unknown>;

package/dist/components/stream/networkPipelineHelpers.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Network pipeline pure helpers (node factory + bezier cache validation).
+ */
+import type { RealtimeNode, BezierCache } from "./networkTypes";
+export declare function createNode(id: string): RealtimeNode;
+/** Validate a value matches the `BezierCache` shape before assigning it
+ *  to a `RealtimeEdge`. The particle pipeline reads
+ *  `edge.bezier.points[i].x` etc. unguarded — a malformed bezier
+ *  (e.g. `bezier: true`, missing points, non-finite coords) would
+ *  crash the canvas frame loop. */
+export declare function isValidBezierCache(value: unknown): value is BezierCache;
+export declare function isFourFinitePoints(pts: unknown): boolean;

package/dist/components/stream/networkPipelineUpdateResults.d.ts

@@ -0,0 +1,38 @@
+import { type ChangeSet, type Invalidation, type UpdateResult } from "./pipelineUpdateContract";
+/**
+ * The retained topology is unchanged by most config updates. The distinction
+ * is public here because callers must not mistake a config patch for a new
+ * ingest: only accessor/chart-type patches need the retained raw graph
+ * re-derived before the declared layout work runs.
+ */
+export type NetworkRetainedDataEffect = "preserve" | "rebuild";
+export interface NetworkConfigPatchDependency {
+    readonly retainedData: NetworkRetainedDataEffect;
+    readonly invalidations: readonly Invalidation[];
+}
+/**
+ * Network's config dependency table. It is deliberately key-level rather
+ * than a single conservative fallback so an integration can inspect whether
+ * a patch rebuilds retained topology, relays out marks, repaints styles, or
+ * only changes future work. Unknown future keys retain the safe layout
+ * fallback below until they receive an explicit entry.
+ */
+export declare const NETWORK_CONFIG_PATCH_DEPENDENCIES: Readonly<Record<string, NetworkConfigPatchDependency>>;
+export interface NetworkConfigPatchClassification {
+    readonly retainedData: NetworkRetainedDataEffect;
+    readonly invalidations: ReadonlySet<Invalidation>;
+}
+/** Union the declared effects for a patch after its effective keys are known. */
+export declare function classifyNetworkConfigPatch(keys: readonly string[]): NetworkConfigPatchClassification;
+type DataChangeKind = Extract<ChangeSet["kind"], "ingest" | "replace" | "remove" | "update" | "clear">;
+/** Result bookkeeping and explicit config-patch dependency policy for Network. */
+export declare class NetworkPipelineUpdateResults {
+    private tracker;
+    get last(): UpdateResult;
+    subscribe(listener: () => void): () => void;
+    recordData(kind: DataChangeKind, count?: number): UpdateResult;
+    recordNoop(kind: DataChangeKind | "restyle"): UpdateResult;
+    recordRestyle(hasCustomRestyle: boolean): UpdateResult;
+    recordConfig(keys: readonly string[]): UpdateResult;
+}
+export {};

package/dist/components/stream/networkRealtimeEncoding.d.ts

@@ -0,0 +1,41 @@
+import type { NetworkSceneEdge, NetworkSceneNode, RealtimeNode } from "./networkTypes";
+import type { DecayConfig, PulseConfig } from "./types";
+import type { NetworkPipelineConfig } from "./networkTypes";
+export type NetworkTimestampMap = Map<string, number>;
+export declare function applyNetworkPulse(options: {
+    sceneNodes: NetworkSceneNode[];
+    sceneEdges: NetworkSceneEdge[];
+    nodeTimestamps: NetworkTimestampMap;
+    edgeTimestamps: NetworkTimestampMap;
+    pulse: PulseConfig | undefined;
+    now: number;
+}): void;
+export interface NetworkDecayCache {
+    sortedNodes: [string, number][] | null;
+    ageMap: Map<string, number> | null;
+}
+export declare function applyNetworkDecay(options: {
+    sceneNodes: NetworkSceneNode[];
+    nodeTimestamps: NetworkTimestampMap;
+    decay: DecayConfig | undefined;
+    cache: NetworkDecayCache;
+}): void;
+export declare function applyNetworkTopologyDiff(options: {
+    sceneNodes: NetworkSceneNode[];
+    addedNodes: Set<string>;
+    lastTopologyChangeTime: number;
+    now: number;
+}): void;
+export declare function hasActiveNetworkTopologyDiff(addedNodes: Set<string>, lastTopologyChangeTime: number, now?: number): boolean;
+export declare function applyNetworkThresholds(options: {
+    sceneNodes: NetworkSceneNode[];
+    nodes: Map<string, RealtimeNode>;
+    thresholds: NetworkPipelineConfig["thresholds"];
+    now: number;
+}): void;
+export declare function hasActiveNetworkThresholds(nodes: Iterable<RealtimeNode>, thresholds: NetworkPipelineConfig["thresholds"]): boolean;
+export declare function hasActiveNetworkPulses(options: {
+    pulse: PulseConfig | undefined;
+    lastIngestTime: number;
+    now?: number;
+}): boolean;