@elabs-ai/components-process 4.1.0

package/dist/test/index.d.ts

@@ -0,0 +1,196 @@
+import * as react from 'react';
+import { HTMLAttributes } from 'react';
+
+/** Selection carried by a process view's coordinated-selection contract (RM-068 completes it). */
+type ProcessSelection = null | {
+    kind: "node";
+    id: string;
+} | {
+    kind: "edge";
+    id: string;
+};
+/** What {@link assertProcessContract} checks for one double. */
+interface ProcessContractSpec {
+    /** Name of the prop carrying the double's primary data payload. */
+    dataProp: "graph" | "variants";
+    /** Other props the real component requires; the double must not silently accept `undefined`. */
+    requiredProps?: string[];
+}
+/** Thrown by {@link assertProcessContract} when a double is used with an invalid prop shape. */
+declare class ProcessContractError extends Error {
+    constructor(componentName: string, message: string);
+}
+/**
+ * Validate a double's props against its contract spec. Throws {@link ProcessContractError} on
+ * a missing/invalid required prop — mirroring what the real component would fail on at
+ * runtime, so a test that gets the props wrong fails loudly rather than silently rendering an
+ * empty double.
+ */
+declare function assertProcessContract(componentName: string, props: Record<string, unknown>, spec: ProcessContractSpec): void;
+/** What a double records to `data-process-props`, for assertions without a real layout. */
+interface ProcessDoublePayload {
+    component: string;
+    dataLength: number;
+    selection?: ProcessSelection;
+}
+/** Build the inspectable payload a double serializes into `data-process-props`. */
+declare function buildProcessDoublePayload(componentName: string, props: Record<string, unknown>, spec: ProcessContractSpec): ProcessDoublePayload;
+/** Read a mounted double's payload back out of the DOM (companion to {@link buildProcessDoublePayload}). */
+declare function readProcessDoubleProps(el: Element): ProcessDoublePayload | null;
+
+/**
+ * The framework-free event-log and process-graph model — RM-049.
+ *
+ * Every downstream item in the process-mining track (RM-050 abstraction, RM-051 the
+ * process map, RM-052 the variant explorer, RM-053 the case table, RM-054 the coverage
+ * strip) reads these shapes, so they are the wave's frozen contract. Keep additions
+ * additive: a required field added here is a breaking change for five items at once.
+ *
+ * NOTHING in this module — or anywhere under `src/core/` — may import React, React Flow,
+ * visx, d3 or an `@elabs-ai/components-*` package. See `.claude/rules/process-components.md`
+ * and `pnpm process:reuse:check`.
+ */
+/**
+ * One raw row of an event log, before normalization.
+ *
+ * `timestamp` accepts the three shapes tabular sources actually produce — an ISO string,
+ * an epoch number, or a `Date` — because the adapters hand rows through unchanged and a
+ * consumer should not have to pre-convert. {@link normalizeLog} resolves all three to
+ * epoch milliseconds.
+ */
+interface EventRow {
+    /** Case (process instance) this event belongs to. */
+    caseId: string;
+    /** Activity name. This is the node identity in the discovered graph. */
+    activity: string;
+    /** When the event completed (or, for a `lifecycle: "start"` row, when it started). */
+    timestamp: string | number | Date;
+    /**
+     * Optional explicit start of an interval event. Ignored when the row is one half of a
+     * `lifecycle` pair — the paired `"start"` row wins, because it is the observed value.
+     */
+    startTimestamp?: string | number | Date;
+    /** Who or what executed the event (a user, a queue, a system). */
+    resource?: string;
+    /** Lifecycle transition. Absent means the row is an atomic (already-complete) event. */
+    lifecycle?: "start" | "complete";
+    /** Free-form event-level attributes carried through normalization untouched. */
+    attributes?: Record<string, string | number | boolean | null>;
+}
+/** A raw event log: the rows, plus optional per-case attributes keyed by `caseId`. */
+interface EventLog {
+    events: EventRow[];
+    caseAttributes?: Record<string, Record<string, unknown>>;
+}
+/**
+ * Summary statistics over a set of duration samples, in milliseconds.
+ *
+ * All seven members are always present; an empty sample set yields zeros rather than
+ * `null`, so a renderer never has to branch on absence.
+ */
+interface DurationStats {
+    min: number;
+    max: number;
+    mean: number;
+    median: number;
+    p90: number;
+    sum: number;
+    /** Mean after discarding the lowest and highest 10% of samples. */
+    trimmedMean: number;
+}
+/** Per-activity aggregates in a discovered graph. */
+interface ActivityStats {
+    /** Stable node identity — the activity name. */
+    id: string;
+    /** Human-readable label. Equal to `id` unless a caller relabels the graph. */
+    label: string;
+    /** Total occurrences across all cases. */
+    instances: number;
+    /** Number of distinct cases the activity occurs in at least once. */
+    cases: number;
+    /** True when the activity starts at least one case. */
+    isStart: boolean;
+    /** True when the activity ends at least one case. */
+    isEnd: boolean;
+    /** Distribution of the activity's own execution durations. */
+    duration: DurationStats;
+}
+/** Per-edge aggregates in a discovered graph (a directly-follows relation). */
+interface TransitionStats {
+    source: string;
+    target: string;
+    /** Total occurrences of the directly-follows pair across all cases. */
+    count: number;
+    /** Number of distinct cases the pair occurs in at least once. */
+    caseCount: number;
+    /** Distribution of the flow time between the two activities. */
+    duration: DurationStats;
+    /** `source === target`. */
+    isSelfLoop: boolean;
+    /**
+     * Whether the edge points backwards in the laid-out graph. Discovery does not lay out,
+     * so this is always `false` here; a layout pass sets it (RM-044).
+     */
+    isBackEdge: boolean;
+}
+/** A directly-follows graph plus its totals. */
+interface ProcessGraph {
+    activities: ActivityStats[];
+    transitions: TransitionStats[];
+    /** Activity name → number of cases that start with it. */
+    startActivities: Record<string, number>;
+    /** Activity name → number of cases that end with it. */
+    endActivities: Record<string, number>;
+    totals: {
+        cases: number;
+        events: number;
+        variants: number;
+    };
+}
+/** One distinct activity sequence, with the cases that follow it. */
+interface Variant {
+    /** Stable, reproducible id derived from the sequence — see `variantId`. */
+    id: string;
+    sequence: string[];
+    /** Number of cases following this sequence. */
+    count: number;
+    /** `count / totalCases`. */
+    share: number;
+    /** Running share across the descending-frequency order — monotonically non-decreasing. */
+    cumulativeShare: number;
+    /** Case ids following this sequence, in first-appearance order. */
+    caseIds: string[];
+    /** Distribution of the end-to-end case durations of `caseIds`. */
+    duration: DurationStats;
+}
+
+interface DoubleOwnProps extends HTMLAttributes<HTMLDivElement> {
+    selection?: ProcessSelection;
+    onSelectionChange?: (selection: ProcessSelection) => void;
+}
+interface ProcessMapDoubleProps extends DoubleOwnProps {
+    graph: ProcessGraph;
+}
+interface VariantExplorerDoubleProps extends DoubleOwnProps {
+    variants: Variant[];
+}
+interface ProcessKpiStripDoubleProps extends HTMLAttributes<HTMLDivElement> {
+    graph: ProcessGraph;
+}
+/** Stand-in for the future `ProcessMap` (RM-051). Named with a `Double` suffix — see contract.ts header. */
+declare const ProcessMapDouble: react.ForwardRefExoticComponent<ProcessMapDoubleProps & react.RefAttributes<HTMLDivElement>>;
+/** Stand-in for the future `VariantExplorer` (RM-052). */
+declare const VariantExplorerDouble: react.ForwardRefExoticComponent<VariantExplorerDoubleProps & react.RefAttributes<HTMLDivElement>>;
+/** Stand-in for the future `ProcessKpiStrip` (RM-054). */
+declare const ProcessKpiStripDouble: react.ForwardRefExoticComponent<ProcessKpiStripDoubleProps & react.RefAttributes<HTMLDivElement>>;
+
+/** The derived triple most process stories/tests want from one raw log. */
+interface ProcessFixture {
+    log: EventLog;
+    graph: ProcessGraph;
+    variants: Variant[];
+}
+/** Derive {@link ProcessFixture} from a raw event log. Pure — no caching, no I/O. */
+declare function withProcessFixture(log: EventLog): ProcessFixture;
+
+export { ProcessContractError, type ProcessContractSpec, type ProcessDoublePayload, type ProcessFixture, ProcessKpiStripDouble, type ProcessKpiStripDoubleProps, ProcessMapDouble, type ProcessMapDoubleProps, type ProcessSelection, VariantExplorerDouble, type VariantExplorerDoubleProps, assertProcessContract, buildProcessDoublePayload, readProcessDoubleProps, withProcessFixture };