@pipelex/mthds-ui 0.27.0 → 0.29.0

package/dist/graph/react/index.d.ts

@@ -1,11 +1,83 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import React from 'react';
-import { c as GraphNodeData, d as GraphEdge, e as GraphNode, b as GraphSpec, f as GraphConfig, g as GraphDirection, F as FoldMode, h as GraphThemeMode, T as ToolbarPosition, G as GraphTheme, i as PipeStatus, j as GraphSpecNodeIoItem, k as ValidationState, V as ValidationIssue, L as LabelDescriptor, l as PipeControllerType, m as FoldToggleOptions, N as NodeValidationSummary, n as PipeType, o as GraphSpecMode, C as ConceptInfo, p as GraphSpecNode } from '../../types-DgqW3Jg4.js';
-export { q as PipeOperatorType } from '../../types-DgqW3Jg4.js';
+import { b as GraphSpec, c as GraphNodeData, d as GraphEdge, e as GraphNode, f as GraphConfig, g as GraphDirection, F as FoldMode, h as GraphThemeMode, T as ToolbarPosition, G as GraphTheme, i as PipeStatus, j as GraphSpecNodeIoItem, k as ValidationState, V as ValidationIssue, L as LabelDescriptor, l as PipeControllerType, m as FoldToggleOptions, N as NodeValidationSummary, n as NodePipeType, o as GraphSpecMode, C as ConceptInfo, p as GraphSpecNode } from '../../types-BaFWy56P.js';
+export { q as PipeOperatorType } from '../../types-BaFWy56P.js';
 import { PipeIOContracts, OutputForm, InputForm, SaveFiles } from '@pipelex/mthds-form';
 import { ResolveUrl, ResolveShareUrl, DownloadDisplay } from '@pipelex/mthds-form/react';
 import { Edge, Node, ReactFlowInstance } from '@xyflow/react';
 
+/**
+ * A graph and the artifacts that describe its pipes, taken from ONE source.
+ *
+ * `GraphViewer` takes this as its single `graph` prop rather than a spec and
+ * three descriptor props side by side, because the descriptors are keyed by the
+ * graph's own `pipe_ref`s: the detail panel walks from a data node back to the
+ * pipe that produced it and looks that pipe up in `outputForm` and
+ * `pipeIoContracts`. A spec paired with another source's descriptors (a past
+ * run's graph beside the current method's validate report, after the method's
+ * pipes were renamed) misses every lookup, and the panel can only say that no
+ * descriptor describes the value. Carrying all four in one object is what keeps
+ * them from one run, or from one validate call.
+ *
+ * Where each source lives:
+ *
+ * - **A run**: its results carry `graph_spec`, `pipe_io_contracts`,
+ *   `output_form` and `input_form` together; `graphArtifactsFrom(results)`
+ *   reads them in one call.
+ * - **A method that has not run** (a dry run, or a static graph built from its
+ *   sources): the descriptors come from the same method's validate report, the
+ *   one the dry graph or the static build describes.
+ *
+ * The descriptors are optional, and nullable as the wire carries them. Without
+ * `pipeIoContracts` and `outputForm` together, the panel shows a data node's
+ * structure table and no data tab, which is the honest floor for a graph whose
+ * artifacts were not produced. `inputForm` is optional even beside the other
+ * two: it is what lets a method's own inputs, which no pipe produced, show their
+ * value through the consuming pipe's slot.
+ */
+interface GraphArtifacts {
+    /** The graph to draw: a run's `graph_spec`, a dry run's, or a static build. */
+    graphSpec: GraphSpec;
+    /** `pipe_io_contracts` for the pipes of THIS graph. */
+    pipeIoContracts?: PipeIOContracts | null;
+    /** `output_form` for the pipes of THIS graph, from the same source. */
+    outputForm?: OutputForm | null;
+    /** `input_form` for the pipes of THIS graph, from the same source. */
+    inputForm?: InputForm | null;
+}
+/**
+ * The four artifacts as a run's results, or a validate report, spell them on
+ * the wire. `graph_spec` is `unknown` because transport layers type it that way;
+ * `GraphViewer` validates it at its boundary.
+ */
+interface GraphArtifactsSource {
+    graph_spec?: unknown;
+    pipe_io_contracts?: PipeIOContracts | null;
+    output_form?: OutputForm | null;
+    input_form?: InputForm | null;
+}
+/**
+ * Read the graph and its descriptors out of one run's results (or one report
+ * that carries all four), so a host never assembles the bundle by hand from two
+ * places. Returns `null` when the source carries no graph.
+ */
+declare function graphArtifactsFrom(source: GraphArtifactsSource): GraphArtifacts | null;
+/** The descriptors the detail panel renders a value from, once they are usable. */
+interface ResultDescriptors {
+    pipeIoContracts: PipeIOContracts;
+    outputForm: OutputForm;
+    inputForm?: InputForm;
+}
+/**
+ * The descriptors a graph's detail panel can render from, or `null`.
+ *
+ * Both `pipeIoContracts` and `outputForm`, or neither: the contract names the
+ * payload's shape and the descriptor says what the result IS, so a panel given
+ * one of the two would be guessing the other. `inputForm` rides along when the
+ * other two are there.
+ */
+declare function resultDescriptors(graph: GraphArtifacts | null): ResultDescriptors | null;
+
 /** ReactFlow node parameterized with our domain data. */
 type AppNode = Node<GraphNodeData>;
 /** ReactFlow edge with standard fields (domain-only fields are dropped at the boundary). */
@@ -30,7 +102,21 @@ declare function toAppNodes(nodes: GraphNode[]): AppNode[];
 declare function toAppEdges(edges: GraphEdge[]): AppEdge[];
 
 interface GraphViewerProps {
-    graphspec: GraphSpec | null;
+    /**
+     * The graph to draw, together with the artifacts that describe its pipes —
+     * all four from ONE source: a run's results, or a method's validate report
+     * beside the dry or static graph of that same method. `null` draws nothing.
+     *
+     * One object rather than a spec prop and three descriptor props, because the
+     * detail panel looks a data node's descriptor up by the `pipe_ref` of the pipe
+     * that produced it IN THIS GRAPH. A graph paired with another source's
+     * descriptors misses every lookup. See `GraphArtifacts`.
+     *
+     * Without `pipeIoContracts` and `outputForm`, the panel still works: it shows
+     * the concept's structure table and no data tab, which is the honest floor
+     * for a graph whose artifacts the host does not hold.
+     */
+    graph: GraphArtifacts | null;
     config?: GraphConfig;
     /** Initial layout direction. Users can toggle this via the built-in toolbar. */
     initialDirection?: GraphDirection;
@@ -94,7 +180,10 @@ interface GraphViewerProps {
     onNavigateToPipe?: (pipeCode: string, status?: PipeStatus) => void;
     onStuffNodeClick?: (stuff: GraphSpecNodeIoItem) => void;
     onReactFlowInit?: (instance: AppRFInstance) => void;
-    /** Layer 2 execution state: pipe_code → current status. Updates node status dots in real-time. */
+    /**
+     * Layer 2 execution state: pipe_code → current status. Updates node status dots in real-time.
+     * A binding card is never matched: its `pipeCode` is the path it binds, not a pipe's code.
+     */
     statusMap?: Record<string, PipeStatus>;
     /** Called when any node is clicked with full node data. Use for detail/inspector panels. */
     onNodeSelect?: (nodeId: string, nodeData: GraphNodeData, event: React.MouseEvent) => void;
@@ -102,35 +191,6 @@ interface GraphViewerProps {
     onPaneClick?: () => void;
     /** Render extra content below the built-in detail panel content for the selected node. */
     renderDetailExtra?: (nodeId: string, nodeData: GraphNodeData) => React.ReactNode;
-    /**
-     * `pipe_io_contracts` for the method this spec is a run of — one half of what
-     * the detail panel needs to render a data node's VALUE.
-     *
-     * The graph renders results itself now. It used to take a render prop instead,
-     * because the form kernel was an optional peer and `./graph/react` had to keep
-     * resolving without it — an arrangement that made sense while the kernel only
-     * powered an optional run form, and stopped making sense the moment the
-     * standard's `output_form` became how this viewer shows a result at all. A
-     * viewer whose detail panel cannot show data is not a viewer, so the kernel is
-     * a dependency of this package and the seam is gone.
-     *
-     * Omit these and the panel still works: it shows the concept's structure table
-     * and no data tab, which is the honest floor for a spec whose artifacts the
-     * host does not hold (a static graph, a spec restored without its validate
-     * report).
-     */
-    contracts?: PipeIOContracts;
-    /**
-     * `output_form` from the SAME `/validate` call — the other half. The contract
-     * names the payload's shape; the descriptor says what the result IS.
-     */
-    outputForm?: OutputForm;
-    /**
-     * `input_form`, optional even here. It is what lets a method's own INPUTS show
-     * their value: no pipe produced them, so no output descriptor describes them,
-     * and the CONSUMING pipe's descriptor for their slot is what names them.
-     */
-    inputForm?: InputForm;
     /**
      * Turns the runtime's own `pipelex-storage://…` reference into a URL a
      * browser can fetch, so files in a result actually paint.
@@ -272,8 +332,9 @@ declare const controllerNodeTypes: {
 
 type PipeCardDirection = "LR" | "TB";
 interface PipeCardData {
+    /** The pipe code, or the `from` path of a binding step's card. */
     pipeCode: string;
-    pipeType: PipeType;
+    pipeType: NodePipeType;
     description?: string;
     status: PipeStatus;
     graphMode?: GraphSpecMode;
@@ -336,10 +397,12 @@ declare function PipeCardBase({ data, children }: PipeCardBaseProps): react_jsx_
  *
  * ## What it needs from the host, and why
  *
- * The artifacts every `/validate` call returns beside the graph spec, keyed by
- * `pipe_ref`. The join is the producing pipe: the graph hands over
- * `producerPipeRef` (see `stuffLookup.ts`), and `output_form` plus the output
- * half of the contract are looked up by it.
+ * The artifacts a run's results (or a `/validate` call) return beside the graph
+ * spec, keyed by `pipe_ref`. The join is the producing pipe: the graph hands
+ * over `producerPipeRef` (see `stuffLookup.ts`), and `output_form` plus the
+ * output half of the contract are looked up by it. That join only holds when
+ * the artifacts and the graph come from the same source, which is why
+ * `GraphViewer` takes them as one `graph` object (`GraphArtifacts`).
  *
  * ## The method's own inputs, which no pipe produced
  *
@@ -380,9 +443,14 @@ declare function PipeCardBase({ data, children }: PipeCardBaseProps): react_jsx_
  * never reach a panel that installs its own.
  */
 interface StuffResultRendererOptions {
-    /** `pipe_io_contracts` for the method being displayed. */
-    contracts: PipeIOContracts;
-    /** `output_form` for the same method — the SAME `/validate` call. */
+    /**
+     * `pipe_io_contracts` from the same source as the `producerPipeRef` and
+     * `consumer` below: the run, or the validate report, whose graph they were
+     * read from. Inside `GraphViewer` that pairing is guaranteed by its single
+     * `graph` prop; a host using this panel on its own owns it.
+     */
+    pipeIoContracts: PipeIOContracts;
+    /** `output_form` from that SAME source. */
     outputForm: OutputForm;
     /**
      * `input_form`, optional. Supplying it is what lets a method's own INPUTS
@@ -440,7 +508,7 @@ interface StuffResultPanelProps extends StuffResultRendererOptions {
      */
     downloads?: DownloadDisplay;
 }
-declare function StuffResultPanel({ contracts, outputForm, inputForm, stuff, producerPipeRef, consumer, resolveUrl, resolveShareUrl, saveFiles, downloads, }: StuffResultPanelProps): react_jsx_runtime.JSX.Element | null;
+declare function StuffResultPanel({ pipeIoContracts, outputForm, inputForm, stuff, producerPipeRef, consumer, resolveUrl, resolveShareUrl, saveFiles, downloads, }: StuffResultPanelProps): react_jsx_runtime.JSX.Element | null;
 
 interface DetailPanelProps {
     isOpen: boolean;
@@ -472,8 +540,8 @@ interface ConceptDetailPanelProps {
     isDryRun?: boolean;
     /**
      * Renders the data half. `GraphViewer` supplies it as a `StuffResultPanel`,
-     * the form kernel's descriptor-driven result view, when the host passed the
-     * `contracts` and `outputForm` artifacts; see `docs/stuff-result-panel.md`.
+     * the form kernel's descriptor-driven result view, when the host's `graph`
+     * carries `pipeIoContracts` and `outputForm`; see `docs/stuff-result-panel.md`.
      *
      * Without it — or when it returns nothing for this item — the panel shows the
      * structure table alone and no tabs, which is what a viewer that has not been
@@ -511,4 +579,4 @@ interface UseResizableResult {
 }
 declare function useResizable({ defaultWidth, minWidth, maxWidth, containerRef, }: UseResizableOptions): UseResizableResult;
 
-export { type AppEdge, type AppNode, type AppRFInstance, ConceptDetailPanel, type ConceptDetailPanelProps, ControllerGroupNode, DetailPanel, type DetailPanelProps, GraphViewer, type GraphViewerProps, PipeCardBase, type PipeCardBaseProps, type PipeCardData, PipeCardNode, PipeDetailPanel, type PipeDetailPanelProps, PipeStatus, StuffResultPanel, type StuffResultPanelProps, type StuffResultRendererOptions, type UseResizableOptions, type UseResizableResult, ValidationPanel, type ValidationPanelPlacement, type ValidationPanelProps, applyStatusOverrides, controllerNodeTypes, detectSystemTheme, hydrateLabels, renderLabel, toAppEdges, toAppNodes, useResizable, useSystemTheme, validationLabel, validationPanelPlacement };
+export { type AppEdge, type AppNode, type AppRFInstance, ConceptDetailPanel, type ConceptDetailPanelProps, ControllerGroupNode, DetailPanel, type DetailPanelProps, type GraphArtifacts, type GraphArtifactsSource, GraphViewer, type GraphViewerProps, PipeCardBase, type PipeCardBaseProps, type PipeCardData, PipeCardNode, PipeDetailPanel, type PipeDetailPanelProps, PipeStatus, type ResultDescriptors, StuffResultPanel, type StuffResultPanelProps, type StuffResultRendererOptions, type UseResizableOptions, type UseResizableResult, ValidationPanel, type ValidationPanelPlacement, type ValidationPanelProps, applyStatusOverrides, controllerNodeTypes, detectSystemTheme, graphArtifactsFrom, hydrateLabels, renderLabel, resultDescriptors, toAppEdges, toAppNodes, useResizable, useSystemTheme, validationLabel, validationPanelPlacement };