semiotic 3.7.4 → 3.8.0

package/dist/components/charts/physics/GaltonBoardChart.d.ts

@@ -0,0 +1,66 @@
+import * as React from "react";
+import type { Datum } from "../shared/datumTypes";
+import type { BaseChartProps, ChartAccessor } from "../shared/types";
+import { type PhysicsFrameHandle } from "./physicsHocHandle";
+import { type PhysicsHocFrameProps, type PhysicsSharedChartProps, type PhysicsSimulationMode, type TooltipProp } from "./physicsHocUtils";
+import type { ChartMode } from "../shared/types";
+export interface GaltonBoardReferenceLine {
+    value: number;
+    label?: React.ReactNode;
+    color?: string;
+    className?: string;
+    strokeDasharray?: string;
+    strokeWidth?: number;
+    labelPosition?: "top" | "bottom";
+}
+export interface GaltonBoardChartProps<TDatum extends Datum = Datum> extends Omit<BaseChartProps, "margin" | "mode">, PhysicsSharedChartProps {
+    data?: TDatum[];
+    size?: [number, number];
+    valueAccessor?: ChartAccessor<TDatum, number>;
+    valueExtent?: [number, number];
+    bins?: number;
+    /**
+     * Chart display mode (`primary`/`context`/`sparkline`/`mobile`) **or**
+     * legacy simulation mode (`sample`/`mechanical`). Prefer `simulationMode`
+     * for sample vs mechanical; use `mode` for ChartContainer / ChartMode.
+     */
+    mode?: ChartMode | PhysicsSimulationMode;
+    /** Sample data rows vs seeded mechanical demo (no data required). */
+    simulationMode?: PhysicsSimulationMode;
+    pegRows?: number;
+    mechanicalCount?: number;
+    branchProbability?: number;
+    ballRadius?: number;
+    colorBy?: ChartAccessor<TDatum, string>;
+    referenceLines?: GaltonBoardReferenceLine | GaltonBoardReferenceLine[];
+    seed?: number;
+    showProjection?: boolean;
+    tooltip?: TooltipProp;
+    paused?: boolean;
+    frameProps?: PhysicsHocFrameProps<"config">;
+}
+/**
+ * Physics-backed Galton board chart that drops values through seeded pegs into a settled distribution.
+ *
+ * @example
+ * ```tsx
+ * <GaltonBoardChart
+ *   data={[{ id: "a", value: 2 }, { id: "b", value: 7 }]}
+ *   valueAccessor="value"
+ *   bins={12}
+ *   size={[520, 320]}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <GaltonBoardChart
+ *   mode="mechanical"
+ *   mechanicalCount={80}
+ *   branchProbability={0.62}
+ *   seed={11}
+ * />
+ * ```
+ */
+export declare const GaltonBoardChart: React.ForwardRefExoticComponent<GaltonBoardChartProps<Datum> & React.RefAttributes<PhysicsFrameHandle>>;
+export default GaltonBoardChart;

package/dist/components/charts/physics/GauntletChart.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const GauntletChartCapability: ChartCapability;

package/dist/components/charts/physics/GauntletChart.d.ts

@@ -0,0 +1,73 @@
+import * as React from "react";
+import type { PhysicsFrameHandle } from "./physicsHocHandle";
+import type { Datum } from "../shared/datumTypes";
+import type { GauntletChartProps } from "./gauntletChartProps";
+export { GAUNTLET_WALL, clampGauntletPoint, buildGauntletPhysics } from "./gauntletPhysics";
+export { applyGauntletEffect, planGauntletPropertyWork, replaceGauntletNegative } from "./gauntletEffects";
+export type { GauntletAccessors, GauntletCoreBodyFn, GauntletEffect, GauntletEvent, GauntletEventContext, GauntletEventLogItem, GauntletGate, GauntletLayout, GauntletPopSpec, GauntletProjectPlacement, GauntletProjectPlacementFn, GauntletProjectState, GauntletPropertyDefinition, GauntletPropertyForceContext, GauntletPropertyWorkPlan, GauntletPropertyWorkPlanOptions, GauntletNegativeReplacementOptions, GauntletViabilityFn } from "./gauntletPhysics";
+export type { GauntletChartProps };
+/**
+ * Physics-backed gauntlet: project core + property satellites through timed or
+ * capacity-gated process events.
+ *
+ * @example
+ * ```tsx
+ * <GauntletChart
+ *   data={[{ id: "plan-a", positives: ["homes"], negatives: ["cost"] }]}
+ *   positiveProperties={[{ id: "homes", label: "Homes", radius: 10 }]}
+ *   negativeProperties={[{ id: "cost", label: "Cost", load: 1.2, radius: 8 }]}
+ *   size={[720, 380]}
+ * />
+ * ```
+ *
+ * @example
+ * Multiple attached properties routed through timed gates, with the
+ * settled viability/outcome projection strip enabled:
+ * ```tsx
+ * <GauntletChart
+ *   data={[{ id: "plan-a", positives: ["homes", "jobs"], negatives: ["cost"] }]}
+ *   positiveProperties={[
+ *     { id: "homes", label: "Homes", radius: 10 },
+ *     { id: "jobs", label: "Jobs", radius: 10 },
+ *   ]}
+ *   negativeProperties={[{ id: "cost", label: "Cost", load: 1.2, radius: 8 }]}
+ *   gates={[
+ *     { id: "review", label: "Review" },
+ *     { id: "budget", label: "Budget" },
+ *   ]}
+ *   showProjection
+ *   size={[720, 380]}
+ * />
+ * ```
+ *
+ * @example
+ * Stagger negative-only compound entities on project-local clocks and share a
+ * finite service across their root bodies:
+ * ```tsx
+ * <GauntletChart
+ *   data={pullRequests}
+ *   startTimeAccessor="arrival"
+ *   negativeAccessor="risks"
+ *   negativeProperties={riskProperties}
+ *   gates={[{
+ *     id: "review",
+ *     capacity: { unitsPerSecond: 5, unitAccessor: "reviewWork" }
+ *   }]}
+ *   events={reviewEvents}
+ *   onCapacityChange={setCapacity}
+ * />
+ * ```
+ */
+export declare const GauntletChart: {
+    <TDatum extends Datum = Datum>(props: GauntletChartProps<TDatum> & React.RefAttributes<PhysicsFrameHandle>): React.ReactElement | null;
+    displayName?: string;
+};
+/**
+ * @deprecated Typo alias of {@link GauntletChart}. Use `GauntletChart` instead.
+ * Removed in the next major version.
+ */
+export declare const GuantletChart: {
+    <TDatum extends Datum = Datum>(props: GauntletChartProps<TDatum> & React.RefAttributes<PhysicsFrameHandle>): React.ReactElement | null;
+    displayName?: string;
+};
+export default GauntletChart;

package/dist/components/charts/physics/PhysicalFlowChart.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const PhysicalFlowChartCapability: ChartCapability;

package/dist/components/charts/physics/PhysicalFlowChart.d.ts

@@ -0,0 +1,63 @@
+import * as React from "react";
+import type { Datum } from "../shared/datumTypes";
+import type { BaseChartProps, ChartAccessor } from "../shared/types";
+import { type PhysicalFlowCoordinateMode, type PhysicalFlowPathConstraint, type PhysicalFlowRawPath } from "./physicsChartUtils";
+import { type PhysicsFrameHandle } from "./physicsHocHandle";
+import { type PhysicsHocFrameProps, type PhysicsSharedChartProps, type TooltipProp } from "./physicsHocUtils";
+export interface PhysicalFlowChartProps<TNode extends Datum = Datum, TLink extends Datum = Datum> extends Omit<BaseChartProps, "margin">, PhysicsSharedChartProps {
+    nodes?: TNode[];
+    links?: TLink[];
+    edges?: TLink[];
+    data?: TLink[];
+    size?: [number, number];
+    nodeIdAccessor?: ChartAccessor<TNode, string>;
+    nodeXAccessor?: ChartAccessor<TNode, number>;
+    nodeYAccessor?: ChartAccessor<TNode, number>;
+    sourceAccessor?: ChartAccessor<TLink, string>;
+    targetAccessor?: ChartAccessor<TLink, string>;
+    throughputAccessor?: ChartAccessor<TLink, number>;
+    pathAccessor?: ChartAccessor<TLink, PhysicalFlowRawPath | undefined>;
+    coordinateMode?: PhysicalFlowCoordinateMode;
+    particleRate?: number;
+    maxParticles?: number;
+    particleRadius?: number;
+    flowSpeed?: number;
+    pathConstraint?: PhysicalFlowPathConstraint;
+    reducedMotion?: boolean;
+    showStaticFlow?: boolean;
+    showNodeLabels?: boolean;
+    showSensors?: boolean;
+    colorBy?: ChartAccessor<TLink, string>;
+    seed?: number;
+    tooltip?: TooltipProp;
+    paused?: boolean;
+    frameProps?: PhysicsHocFrameProps<"config">;
+}
+/**
+ * Physics-backed flow chart that sends packet bodies along authored routes while retaining a static throughput layer.
+ *
+ * @example
+ * ```tsx
+ * <PhysicalFlowChart
+ *   nodes={[{ id: "in", x: 0.1, y: 0.5 }, { id: "out", x: 0.9, y: 0.5 }]}
+ *   links={[{ source: "in", target: "out", value: 40 }]}
+ *   coordinateMode="normalized"
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <PhysicalFlowChart
+ *   nodes={ports}
+ *   edges={routes}
+ *   pathAccessor="path"
+ *   maxParticles={120}
+ *   showSensors
+ * />
+ * ```
+ */
+export declare const PhysicalFlowChart: {
+    <TNode extends Datum = Datum, TLink extends Datum = Datum>(props: PhysicalFlowChartProps<TNode, TLink> & React.RefAttributes<PhysicsFrameHandle>): React.ReactElement | null;
+    displayName?: string;
+};
+export default PhysicalFlowChart;

package/dist/components/charts/physics/PhysicsCustomChart.d.ts

@@ -0,0 +1,120 @@
+import * as React from "react";
+import type { ReactNode } from "react";
+import { type ScaleLinear } from "d3-scale";
+import type { ThemeSemanticColors } from "../../stream/types";
+import { type PhysicsSemanticItem, type StreamPhysicsBodyForce, type StreamPhysicsFrameProps, type StreamPhysicsRegionEffect } from "../../stream/physics/StreamPhysicsFrame";
+import type { PhysicsController } from "../../stream/physics/PhysicsControllers";
+import { PhysicsPipelineStore, type PhysicsPipelineConfig, type PhysicsQueuedSpawn, type PhysicsSpawnPacingOptions } from "../../stream/physics/PhysicsPipelineStore";
+import type { PhysicsColliderSpec, PhysicsSpringSpec } from "../../stream/physics/PhysicsKernel";
+import type { Datum } from "../shared/datumTypes";
+import type { BaseChartProps, ChartAccessor } from "../shared/types";
+import { type PhysicsChartArea } from "./physicsChartUtils";
+import { type PhysicsDatumSpawnResult, type PhysicsFrameHandle } from "./physicsHocHandle";
+import { type PhysicsHocFrameProps, type PhysicsSharedChartProps, type TooltipProp } from "./physicsHocUtils";
+export interface PhysicsCustomLayoutContext<TDatum extends Datum = Datum, TConfig extends object = Record<string, unknown>> {
+    data: TDatum[];
+    scales: {
+        x: ScaleLinear<number, number>;
+        y: ScaleLinear<number, number>;
+    };
+    dimensions: PhysicsChartArea;
+    theme: {
+        semantic: ThemeSemanticColors;
+        categorical: string[];
+    };
+    resolveColor: (key: string, datum?: TDatum) => string;
+    config: TConfig;
+    /**
+     * Scratch pipeline store initialized from the base frame config. Use it for
+     * derived geometry, seeded randomness, or quick settle probes; return
+     * declarative `bodies`/`colliders` from the layout result for rendering.
+     */
+    world: PhysicsPipelineStore;
+}
+export interface PhysicsCustomLayoutResult {
+    bodies?: PhysicsQueuedSpawn[];
+    initialSpawns?: PhysicsQueuedSpawn[];
+    /** Fresh collider geometry replaces the live world without resetting bodies. */
+    colliders?: PhysicsColliderSpec[];
+    /** Fresh sensor geometry replaces the live world without resetting bodies. */
+    sensors?: PhysicsColliderSpec[];
+    constraints?: PhysicsSpringSpec[];
+    config?: PhysicsPipelineConfig;
+    initialSpawnPacing?: PhysicsSpawnPacingOptions;
+    /**
+     * Region effects (membranes, capacity stages, portals). Prefer declaring
+     * these here and driving interaction via `controllers` / `layoutConfig`
+     * rather than re-spawning bodies.
+     */
+    regionEffects?: StreamPhysicsRegionEffect[];
+    /**
+     * Process plugins (capacity queues, portals). Tick with the frame heartbeat
+     * without rebuilding world topology when only `layoutConfig` changes.
+     */
+    controllers?: PhysicsController[];
+    bodyForces?: StreamPhysicsBodyForce;
+    overlays?: ReactNode;
+    backgroundOverlays?: ReactNode;
+    bodyStyle?: StreamPhysicsFrameProps["bodyStyle"];
+    selectedBodyStyle?: StreamPhysicsFrameProps["selectedBodyStyle"];
+    semanticItems?: PhysicsSemanticItem[];
+}
+export type PhysicsCustomLayout<TDatum extends Datum = Datum, TConfig extends object = Record<string, unknown>> = (ctx: PhysicsCustomLayoutContext<TDatum, TConfig>) => PhysicsCustomLayoutResult;
+export type PhysicsCustomSpawnDatumResult = PhysicsDatumSpawnResult | PhysicsQueuedSpawn | PhysicsQueuedSpawn[];
+export interface PhysicsCustomChartProps<TDatum extends Datum = Datum, TConfig extends object = Record<string, unknown>> extends Omit<BaseChartProps, "margin">, PhysicsSharedChartProps {
+    data?: TDatum[];
+    layout: PhysicsCustomLayout<TDatum, TConfig>;
+    /**
+     * Interaction / style config passed as `ctx.config`. Changing only
+     * `layoutConfig` re-runs the layout for colliders, sensors, regionEffects,
+     * controllers, overlays, and bodyStyle — it does **not** re-create the
+     * physics store or re-enqueue initial spawns (topology is keyed by data +
+     * size + layout identity). Keep collider/sensor ids stable across updates.
+     */
+    layoutConfig?: TConfig;
+    config?: PhysicsPipelineConfig;
+    size?: [number, number];
+    xExtent?: [number, number];
+    yExtent?: [number, number];
+    colorBy?: ChartAccessor<TDatum, string | number>;
+    colorScheme?: string | string[] | Record<string, string>;
+    paused?: boolean;
+    tooltip?: TooltipProp;
+    /**
+     * Extra process controllers composed with any returned from `layout()`.
+     */
+    controllers?: PhysicsController[];
+    spawnDatum?: (datum: TDatum, index: number, ctx: PhysicsCustomLayoutContext<TDatum, TConfig>) => PhysicsCustomSpawnDatumResult;
+    /**
+     * Frame passthrough. Prefer top-level `controllers` / layout-returned
+     * regionEffects; frameProps merges are still supported for escape hatches.
+     */
+    frameProps?: PhysicsHocFrameProps<"config">;
+}
+interface ResolvedPhysicsCustomLayout<TDatum extends Datum = Datum, TConfig extends object = Record<string, unknown>> {
+    config: PhysicsPipelineConfig;
+    context: PhysicsCustomLayoutContext<TDatum, TConfig>;
+    initialSpawnPacing?: PhysicsSpawnPacingOptions;
+    initialSpawns: PhysicsQueuedSpawn[];
+    result: PhysicsCustomLayoutResult;
+}
+export declare function resolveCustomLayout<TDatum extends Datum, TConfig extends object>(options: {
+    chartId?: string;
+    colorScheme?: string | string[] | Record<string, string>;
+    config?: PhysicsPipelineConfig;
+    data: TDatum[];
+    layout: PhysicsCustomLayout<TDatum, TConfig>;
+    layoutConfig?: TConfig;
+    onObservation?: BaseChartProps["onObservation"];
+    semantic: ThemeSemanticColors;
+    skipLayout?: boolean;
+    size: [number, number];
+    themeCategorical: string[];
+    xExtent?: [number, number];
+    yExtent?: [number, number];
+}): ResolvedPhysicsCustomLayout<TDatum, TConfig>;
+export declare const PhysicsCustomChart: {
+    <TDatum extends Datum = Datum, TConfig extends object = Record<string, unknown>>(props: PhysicsCustomChartProps<TDatum, TConfig> & React.RefAttributes<PhysicsFrameHandle>): React.ReactElement | null;
+    displayName?: string;
+};
+export default PhysicsCustomChart;

package/dist/components/charts/physics/PhysicsPileChart.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const PhysicsPileChartCapability: ChartCapability;

package/dist/components/charts/physics/PhysicsPileChart.d.ts

@@ -0,0 +1,53 @@
+import * as React from "react";
+import type { Datum } from "../shared/datumTypes";
+import type { BaseChartProps, ChartAccessor, ChartMode } from "../shared/types";
+import { type PhysicsFrameHandle } from "./physicsHocHandle";
+import { type PhysicsHocFrameProps, type PhysicsSharedChartProps, type PhysicsSimulationMode, type TooltipProp } from "./physicsHocUtils";
+export interface PhysicsPileChartProps<TDatum extends Datum = Datum> extends Omit<BaseChartProps, "margin" | "mode">, PhysicsSharedChartProps {
+    data?: TDatum[];
+    size?: [number, number];
+    categoryAccessor?: ChartAccessor<TDatum, string>;
+    valueAccessor?: ChartAccessor<TDatum, number>;
+    /**
+     * Chart display mode **or** legacy simulation mode (`sample`/`mechanical`).
+     * Prefer `simulationMode` for mechanical demos; use `mode` for ChartMode.
+     */
+    mode?: ChartMode | PhysicsSimulationMode;
+    simulationMode?: PhysicsSimulationMode;
+    mechanicalCount?: number;
+    mechanicalCategories?: readonly string[];
+    unitValue?: number;
+    ballRadius?: number;
+    colorBy?: ChartAccessor<TDatum, string>;
+    seed?: number;
+    showProjection?: boolean;
+    sediment?: boolean;
+    tooltip?: TooltipProp;
+    paused?: boolean;
+    frameProps?: PhysicsHocFrameProps<"config">;
+}
+/**
+ * Physics-backed unit pile chart that converts category values into repeated bodies and a readable settled projection.
+ *
+ * @example
+ * ```tsx
+ * <PhysicsPileChart
+ *   data={[{ category: "A", value: 12 }, { category: "B", value: 8 }]}
+ *   categoryAccessor="category"
+ *   valueAccessor="value"
+ *   unitValue={1}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <PhysicsPileChart
+ *   mode="mechanical"
+ *   mechanicalCategories={["North", "South", "West"]}
+ *   mechanicalCount={90}
+ *   seed={5}
+ * />
+ * ```
+ */
+export declare const PhysicsPileChart: React.ForwardRefExoticComponent<PhysicsPileChartProps<Datum> & React.RefAttributes<PhysicsFrameHandle>>;
+export default PhysicsPileChart;

package/dist/components/charts/physics/ProcessFlowChart.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const ProcessFlowChartCapability: ChartCapability;

package/dist/components/charts/physics/ProcessFlowChart.d.ts

@@ -0,0 +1,96 @@
+import * as React from "react";
+import { type PhysicsBodySelection, type StreamPhysicsFrameProps } from "../../stream/physics/StreamPhysicsFrame";
+import { type CapacityQueueSnapshot } from "../../stream/physics/PhysicsControllers";
+import { type ProcessChromeOptions } from "../../recipes/processChrome";
+import type { Datum } from "../shared/datumTypes";
+import type { BaseChartProps, ChartAccessor } from "../shared/types";
+import { type ProcessFlowProjectionMetadata, type ProcessFlowStageDef } from "./physicsChartUtils";
+import { type PhysicsFrameHandle } from "./physicsHocHandle";
+import { type PhysicsHocFrameProps, type PhysicsSharedChartProps, type TooltipProp } from "./physicsHocUtils";
+export type { ProcessFlowStageDef, ProcessFlowProjectionMetadata };
+export interface ProcessFlowChartProps<TDatum extends Datum = Datum> extends Omit<BaseChartProps, "margin" | "selection">, PhysicsSharedChartProps {
+    data?: TDatum[];
+    size?: [number, number];
+    stages: readonly ProcessFlowStageDef[];
+    idAccessor?: ChartAccessor<TDatum, string>;
+    stageAccessor?: ChartAccessor<TDatum, string>;
+    groupBy?: ChartAccessor<TDatum, string>;
+    groupLabelAccessor?: ChartAccessor<TDatum, string>;
+    workAccessor?: ChartAccessor<TDatum, number>;
+    radiusAccessor?: ChartAccessor<TDatum, number>;
+    ballRadius?: number;
+    colorBy?: ChartAccessor<TDatum, string>;
+    seed?: number;
+    route?: "horizontal";
+    groupCompletion?: "allAbsorbed" | "none";
+    groupAnchorAlong?: number;
+    showProjection?: boolean;
+    showChrome?: boolean;
+    /** Options for the default processChrome overlay (stage bays, badges, sockets). */
+    chromeOptions?: ProcessChromeOptions;
+    settle?: boolean;
+    gravityX?: number;
+    gravityY?: number;
+    springStiffness?: number;
+    springDamping?: number;
+    tooltip?: TooltipProp;
+    paused?: boolean;
+    initialSpawnPacing?: StreamPhysicsFrameProps["initialSpawnPacing"];
+    /**
+     * When true (default), stages with `capacity` install live FIFO queue
+     * controllers that drain work at unitsPerSecond — not just force theater.
+     */
+    liveCapacity?: boolean;
+    /** Live capacity metrics callback (queue depth, processed count per region). */
+    onCapacityChange?: (stats: CapacityQueueSnapshot[]) => void;
+    /** Shared selection (process body restyle without relayout). */
+    selection?: PhysicsBodySelection | null;
+    /**
+     * Soft body budget: caps live bodies via pipeline bodyLimit (evict oldest).
+     * Use for infinite/long streams with sediment-style history in the readout.
+     */
+    bodyLimit?: number;
+    /** Mark kind for all bodies, or read per-row from datum.__physicsMark / mark. */
+    bodyMark?: "circle" | "halo" | "faceted" | "pill" | "diamond" | "square";
+    /** Frame passthrough; HOC-owned `config` is merged after the built pipeline config. */
+    frameProps?: PhysicsHocFrameProps;
+}
+/**
+ * Physics-backed multi-body process flow: work items move through capacitated
+ * stages with optional feature groups that complete only when every member is
+ * absorbed (the merge-pressure / review-queue pattern).
+ *
+ * @example
+ * ```tsx
+ * <ProcessFlowChart
+ *   data={prs}
+ *   idAccessor="id"
+ *   stageAccessor="status"
+ *   groupBy="featureId"
+ *   stages={[
+ *     { id: "coding", label: "Coding", force: 14 },
+ *     { id: "review", label: "Review", capacity: { unitsPerSecond: 4 }, pressure: true },
+ *     { id: "merged", label: "Merged", absorb: true },
+ *   ]}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Push-only: omit data, stream work items live through the capacity lane.
+ * const ref = useRef()
+ * <ProcessFlowChart
+ *   ref={ref}
+ *   stages={[
+ *     { id: "triage", label: "Triage", force: 10 },
+ *     { id: "review", label: "Review", capacity: { unitsPerSecond: 3 } },
+ *     { id: "done", label: "Done", absorb: true },
+ *   ]}
+ *   stageAccessor="stage"
+ *   liveCapacity
+ * />
+ * ref.current?.push({ id: "pr-42", stage: "review", work: 2 })
+ * ```
+ */
+export declare const ProcessFlowChart: React.ForwardRefExoticComponent<ProcessFlowChartProps<Datum> & React.RefAttributes<PhysicsFrameHandle>>;
+export default ProcessFlowChart;

package/dist/components/charts/physics/chainReactionOverlay.d.ts

@@ -0,0 +1,22 @@
+import * as React from "react";
+import type { Datum } from "../shared/datumTypes";
+import type { DependencyMachine, DependencyTrackLayout } from "./dependencyMachine";
+import type { RuntimeState } from "./chainReactionRuntime";
+export interface ChainReactionOverlayProps<TDatum extends Datum = Datum> {
+    machine: DependencyMachine<TDatum>;
+    layout: DependencyTrackLayout;
+    runtime: RuntimeState;
+    downstreamSet: ReadonlySet<string>;
+    selectedSet: ReadonlySet<string>;
+    width: number;
+    height: number;
+    seed: number;
+    reduced: boolean;
+    onSelectTask: (taskID: string) => void;
+}
+/**
+ * SVG chrome painted above the physics canvas: workstream lanes, dependency
+ * tracks + delivery sockets, and the domino task cards (which topple on
+ * completion). Interaction is delegated back through `onSelectTask`.
+ */
+export declare function ChainReactionOverlay<TDatum extends Datum = Datum>({ machine, layout, runtime, downstreamSet, selectedSet, width, height, seed, reduced, onSelectTask }: ChainReactionOverlayProps<TDatum>): React.ReactElement;

package/dist/components/charts/physics/chainReactionRuntime.d.ts

@@ -0,0 +1,37 @@
+import type { PhysicsBodyState } from "../../stream/physics/PhysicsKernel";
+import type { PhysicsQueuedSpawn } from "../../stream/physics/PhysicsPipelineStore";
+import type { PhysicsSemanticItem, StreamPhysicsBodyForceContext } from "../../stream/physics/StreamPhysicsFrame";
+import type { Datum } from "../shared/datumTypes";
+import type { DependencyMachine, DependencyMachineEdge, DependencyMachineNode, DependencyPoint, DependencyTrackLayout, DependencyTrackRoute } from "./dependencyMachine";
+import type { ChainReactionMode } from "./chainReactionTypes";
+export interface RuntimeState {
+    currentTime: number;
+    playing: boolean;
+    completed: Set<string>;
+    delivered: Set<string>;
+    inFlight: Set<string>;
+    armed: Set<string>;
+    blockers: Map<string, string>;
+    previewTaskID: string | null;
+}
+interface DependencyBallDatum {
+    kind: "dependency-ball";
+    edgeID: string;
+    sourceID: string;
+    targetID: string;
+    route: DependencyPoint[];
+}
+export declare const EMPTY_SPAWNS: PhysicsQueuedSpawn[];
+export declare function numericTime(value: number | Date | undefined, fallback?: number): number;
+export declare function taskCompletionTime<TDatum extends Datum>(node: DependencyMachineNode<TDatum>): number | null;
+export declare function resolvedArmed<TDatum extends Datum>(machine: DependencyMachine<TDatum>, delivered: ReadonlySet<string>, blockers: ReadonlyMap<string, string>, completed: ReadonlySet<string>): Set<string>;
+export declare function initialRuntime<TDatum extends Datum>(machine: DependencyMachine<TDatum>, mode: ChainReactionMode, currentTime: number, reducedMotion: boolean): RuntimeState;
+export declare function copyRuntime(runtime: RuntimeState): RuntimeState;
+export declare function dependencyBallDatum(body: PhysicsBodyState): DependencyBallDatum | null;
+export declare function dependencyBodyForce(context: StreamPhysicsBodyForceContext): {
+    x: number;
+    y: number;
+} | null;
+export declare function ballSpawn(edge: DependencyMachineEdge, route: DependencyTrackRoute): PhysicsQueuedSpawn;
+export declare function machineSemanticItems<TDatum extends Datum>(machine: DependencyMachine<TDatum>, layout: DependencyTrackLayout, runtime: RuntimeState): PhysicsSemanticItem[];
+export {};

package/dist/components/charts/physics/chainReactionTypes.d.ts

@@ -0,0 +1,97 @@
+import type { Datum } from "../shared/datumTypes";
+import type { BlockerAmplification, DependencyAccessor, DependencyTaskStatus } from "./dependencyMachine";
+export type ChainReactionMode = "snapshot" | "replay" | "mechanical";
+export type ChainReactionInsight = "none" | "blocker-amplification";
+export type ChainReactionControl = "play" | "pause" | "step" | "reset" | "settle";
+export type ChainReactionObservation<TDatum extends Datum = Datum> = {
+    type: "task-completed";
+    taskID: string;
+    datum: TDatum;
+} | {
+    type: "dependency-delivered";
+    sourceID: string;
+    targetID: string;
+} | {
+    type: "task-armed";
+    taskID: string;
+} | {
+    type: "machine-stalled";
+    blockerID: string;
+    downstreamTaskCount: number;
+    affectedLaneCount: number;
+} | {
+    type: "blocker-previewed";
+    blockerID: string;
+    downstreamTaskIDs: string[];
+} | {
+    type: "machine-settled";
+};
+export interface ChainReactionTaskState {
+    taskID: string;
+    completed: boolean;
+    armed: boolean;
+    blocked: boolean;
+    blockerReason?: string;
+}
+export interface ChainReactionDependencyState {
+    edgeID: string;
+    sourceID: string;
+    targetID: string;
+    state: "waiting" | "in-flight" | "delivered";
+}
+export interface ChainReactionMachineState {
+    currentTime: number;
+    playing: boolean;
+    previewTaskID: string | null;
+    selectedTaskIDs: string[];
+    tasks: ChainReactionTaskState[];
+    dependencies: ChainReactionDependencyState[];
+}
+export interface ChainReactionChartHandle {
+    play: () => void;
+    pause: () => void;
+    step: () => void;
+    reset: () => void;
+    settle: () => void;
+    previewResolve: (taskID: string) => void;
+    clearPreview: () => void;
+    completeTask: (taskID: string) => void;
+    blockTask: (taskID: string, reason: string) => void;
+    unblockTask: (taskID: string) => void;
+    getAmplification: (taskID: string) => BlockerAmplification;
+    getMachineState: () => ChainReactionMachineState;
+}
+export interface ChainReactionChartProps<TDatum extends Datum = Datum> {
+    data: readonly TDatum[];
+    taskIDAccessor: DependencyAccessor<TDatum, string | number>;
+    labelAccessor: DependencyAccessor<TDatum, string>;
+    laneAccessor: DependencyAccessor<TDatum, string>;
+    dependencyAccessor: DependencyAccessor<TDatum, readonly (string | number)[]>;
+    startAccessor?: DependencyAccessor<TDatum, number | Date | undefined>;
+    endAccessor?: DependencyAccessor<TDatum, number | Date | undefined>;
+    progressAccessor?: DependencyAccessor<TDatum, number | undefined>;
+    statusAccessor?: DependencyAccessor<TDatum, DependencyTaskStatus | undefined>;
+    completionTimeAccessor?: DependencyAccessor<TDatum, number | Date | undefined>;
+    blockerAccessor?: DependencyAccessor<TDatum, string | undefined>;
+    milestoneAccessor?: DependencyAccessor<TDatum, boolean | undefined>;
+    mechanism?: "domino-ball";
+    orientation?: "vertical";
+    mode?: ChainReactionMode;
+    insight?: ChainReactionInsight;
+    currentTime?: number | Date;
+    controls?: boolean | readonly ChainReactionControl[];
+    selectedTaskIDs?: readonly string[];
+    onSelectionChange?: (ids: string[]) => void;
+    onObservation?: (event: ChainReactionObservation<TDatum>) => void;
+    reducedMotion?: "settle";
+    seed?: number;
+    width?: number;
+    height?: number;
+    responsiveWidth?: boolean;
+    responsiveHeight?: boolean;
+    title?: string;
+    description?: string;
+    className?: string;
+    accessibleTable?: boolean;
+    enableHover?: boolean;
+}