@pipelex/mthds-ui 0.16.0 → 0.18.0

package/README.md

@@ -14,10 +14,11 @@ Released versions are listed on the [npm page](https://www.npmjs.com/package/@pi
 
 ### Peer dependencies
 
-| Dependency           | Required | Used by                       |
-| -------------------- | -------- | ----------------------------- |
-| `react`, `react-dom` | no       | React layer (`graph/react`)   |
-| `shiki`              | no       | Syntax highlighting (`shiki`) |
+| Dependency            | Required | Used by                                   |
+| --------------------- | -------- | ----------------------------------------- |
+| `react`, `react-dom`  | no       | React layer (`graph/react`, `form/react`) |
+| `shiki`               | no       | Syntax highlighting (`shiki`)             |
+| `@pipelex/mthds-form` | no       | Run form panel (`form/react`)             |
 
 ### Bundled dependencies
 
@@ -271,6 +272,7 @@ See `graphConfig.ts` for the full default palette.
 | ------------------------------- | ------------------------------------------------------------------ |
 | `@pipelex/mthds-ui`             | Pure-TS graph logic — types, builders, layout, controllers, config |
 | `@pipelex/mthds-ui/graph/react` | React components — `GraphViewer`, label helpers, type converters   |
+| `@pipelex/mthds-ui/form/react`  | `RunPanel` — a pipe's input form (needs `@pipelex/mthds-form`)     |
 | `@pipelex/mthds-ui/shiki`       | MTHDS syntax highlighting with shiki                               |
 
 ## Pure TypeScript usage
@@ -295,6 +297,38 @@ const { nodes, edges } = getLayoutedElements(graphData.nodes, graphData.edges, "
 const final = applyControllers(nodes, edges, graphspec, analysis, true);
 ```
 
+## Run form panel
+
+`RunPanel` renders a pipe's input form from its IO contract: the fields, the readiness verdict on the Run button, and the wire-ready payload a run receives.
+
+```bash
+npm install @pipelex/mthds-form   # optional peer — graph-only consumers skip it
+```
+
+```tsx
+import { getPipeIOContract } from "@pipelex/mthds-form";
+import { RunPanel } from "@pipelex/mthds-ui/form/react";
+import "@pipelex/mthds-ui/form/react/RunPanel.css";
+
+// Note the argument order — the kernel's README currently shows it wrong.
+const contract = getPipeIOContract(pipeIoContracts, domain, pipeCode);
+
+<RunPanel
+  contract={contract}
+  values={values}
+  onValuesChange={setValues}
+  onRun={(apiInputs) => execute(pipeCode, apiInputs)}
+  title={pipeCode}
+  theme="dark"
+/>;
+```
+
+`onRun` fires only once the kernel's run gate passes. This library renders and never executes: no API client, no upload, no storage resolution — the host injects all three.
+
+The controls are the kernel's, styled with Tailwind over shadcn tokens, so **bringing in their styling is the host's lane** — either add `./node_modules/@pipelex/mthds-form/dist/**/*.js` to your Tailwind `content` globs, or import the prebuilt `@pipelex/mthds-form/theme.css` + `styles.css`. Pick one; they are mutually exclusive, and a Tailwind host that forgets the glob gets a _mostly_-styled form that reads like a broken design system.
+
+Full contract, the styling trap, the `.dark` bridge and the `mthds-run-panel` token hook: [docs/run-form-panel.md](./docs/run-form-panel.md).
+
 ## Shiki integration
 
 Syntax-highlight MTHDS code with the bundled grammar and themes:

package/dist/chunk-2N65P32H.js

@@ -0,0 +1,17 @@
+// src/graph/pipeRefs.ts
+function parsePipeRef(raw) {
+  if (raw.includes("->")) return null;
+  if (raw === "" || raw.startsWith(".") || raw.endsWith(".") || raw.includes("..")) return null;
+  const dot = raw.lastIndexOf(".");
+  if (dot === -1) return { domainPath: null, pipeCode: raw };
+  return { domainPath: raw.slice(0, dot), pipeCode: raw.slice(dot + 1) };
+}
+function makePipeRef(domainCode, pipeCode) {
+  return `${domainCode}.${pipeCode}`;
+}
+
+export {
+  parsePipeRef,
+  makePipeRef
+};
+//# sourceMappingURL=chunk-2N65P32H.js.map

package/dist/chunk-2N65P32H.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/graph/pipeRefs.ts"],"sourcesContent":["// Pipe-ref helpers — the presentation-side mirror of pipelex's `QualifiedRef`\n// (`pipelex/core/qualified_ref.py`). A pipe ref is `domain_code.pipe_code`\n// (the domain path may be multi-segment: `legal.contracts.compute_score`);\n// parsing splits on the LAST dot. Hosts must use these helpers instead of\n// re-implementing the split, so every consumer agrees with the runtime on\n// what a ref means.\n\n/** A parsed pipe ref: the (possibly multi-segment) domain path and the bare code. */\nexport interface ParsedPipeRef {\n  /** Dotted domain path (`scoring`, `legal.contracts`), or null for a bare ref. */\n  domainPath: string | null;\n  /** The bare pipe code (`compute_score`). */\n  pipeCode: string;\n}\n\n/**\n * Parse a pipe ref with `QualifiedRef.parse` semantics: split on the last dot,\n * reject malformed forms (empty, leading/trailing dot, consecutive dots) by\n * returning `null` instead of throwing. Cross-package refs (`alias->…`) are\n * opaque in the presentation chain for now and also return `null` — an issue\n * about one stays untargetable rather than mis-resolved.\n */\nexport function parsePipeRef(raw: string): ParsedPipeRef | null {\n  if (raw.includes(\"->\")) return null;\n  if (raw === \"\" || raw.startsWith(\".\") || raw.endsWith(\".\") || raw.includes(\"..\")) return null;\n  const dot = raw.lastIndexOf(\".\");\n  if (dot === -1) return { domainPath: null, pipeCode: raw };\n  return { domainPath: raw.slice(0, dot), pipeCode: raw.slice(dot + 1) };\n}\n\n/** Render a fully-qualified pipe ref (`QualifiedRef.full_ref`): `domain_code.pipe_code`. */\nexport function makePipeRef(domainCode: string, pipeCode: string): string {\n  return `${domainCode}.${pipeCode}`;\n}\n"],"mappings":";AAsBO,SAAS,aAAa,KAAmC;AAC9D,MAAI,IAAI,SAAS,IAAI,EAAG,QAAO;AAC/B,MAAI,QAAQ,MAAM,IAAI,WAAW,GAAG,KAAK,IAAI,SAAS,GAAG,KAAK,IAAI,SAAS,IAAI,EAAG,QAAO;AACzF,QAAM,MAAM,IAAI,YAAY,GAAG;AAC/B,MAAI,QAAQ,GAAI,QAAO,EAAE,YAAY,MAAM,UAAU,IAAI;AACzD,SAAO,EAAE,YAAY,IAAI,MAAM,GAAG,GAAG,GAAG,UAAU,IAAI,MAAM,MAAM,CAAC,EAAE;AACvE;AAGO,SAAS,YAAY,YAAoB,UAA0B;AACxE,SAAO,GAAG,UAAU,IAAI,QAAQ;AAClC;","names":[]}

package/dist/{chunk-UDA2XA23.js → chunk-BFQHQQ3E.js}

@@ -1,25 +1,22 @@
+import {
+  makePipeRef
+} from "./chunk-2N65P32H.js";
 import {
   ARROW_CLOSED_MARKER,
   CONTROLLER_PADDING_BOTTOM,
   CONTROLLER_PADDING_TOP,
   CONTROLLER_PADDING_X,
-  EDGE_TYPE,
-  FOLD_MODE,
-  GRAPH_THEME,
-  GRAPH_THEME_MODE,
   KNOWN_PIPE_TYPES,
   NODE_TYPE_CONTROLLER,
   NODE_TYPE_PIPE_CARD,
   NODE_TYPE_STUFF,
-  TOOLBAR_POSITION,
   graphSpecMode,
   isStuffNodeId,
-  makePipeRef,
   nodeHeight,
   nodeWidth,
   stuffDigestFromId,
   stuffNodeId
-} from "./chunk-HURB2U53.js";
+} from "./chunk-RJVEDP7M.js";
 import {
   __objRest,
   __spreadProps,
@@ -77,6 +74,81 @@ function validateIoItem(item, path) {
   }
   requireNonEmptyString(item.name, `${path}.name`);
 }
+function requireNumber(value, path) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    fail(path, `expected a finite number, got ${describe(value)}`);
+  }
+  return value;
+}
+function requireNullableNumber(value, path) {
+  if (value === null) return;
+  requireNumber(value, path);
+}
+function normalizeNullableNumber(value, path) {
+  if (value === void 0 || value === null) return null;
+  return requireNumber(value, path);
+}
+function requireNumberRecord(value, path) {
+  if (!isPlainObject(value)) {
+    fail(path, `expected an object, got ${describe(value)}`);
+  }
+  for (const [key, entry] of Object.entries(value)) {
+    requireNumber(entry, `${path}.${key}`);
+  }
+}
+function validateUsage(usage, path) {
+  if (!isPlainObject(usage)) {
+    fail(path, `expected an object, got ${describe(usage)}`);
+  }
+  requireNumber(usage.inference_calls, `${path}.inference_calls`);
+  requireNumber(usage.rated_inference_calls, `${path}.rated_inference_calls`);
+  requireNumberRecord(usage.nb_tokens_by_category, `${path}.nb_tokens_by_category`);
+  requireNumber(usage.total_tokens, `${path}.total_tokens`);
+  requireNullableNumber(usage.cost, `${path}.cost`);
+  usage.cost_input = normalizeNullableNumber(usage.cost_input, `${path}.cost_input`);
+  usage.cost_output = normalizeNullableNumber(usage.cost_output, `${path}.cost_output`);
+  requireNumber(usage.subtree_inference_calls, `${path}.subtree_inference_calls`);
+  requireNumber(usage.subtree_rated_inference_calls, `${path}.subtree_rated_inference_calls`);
+  requireNumberRecord(usage.subtree_nb_tokens_by_category, `${path}.subtree_nb_tokens_by_category`);
+  requireNumber(usage.subtree_total_tokens, `${path}.subtree_total_tokens`);
+  requireNullableNumber(usage.subtree_cost, `${path}.subtree_cost`);
+  usage.subtree_cost_input = normalizeNullableNumber(
+    usage.subtree_cost_input,
+    `${path}.subtree_cost_input`
+  );
+  usage.subtree_cost_output = normalizeNullableNumber(
+    usage.subtree_cost_output,
+    `${path}.subtree_cost_output`
+  );
+  usage.by_model = normalizeModelUsageList(usage.by_model, `${path}.by_model`);
+  usage.subtree_by_model = normalizeModelUsageList(
+    usage.subtree_by_model,
+    `${path}.subtree_by_model`
+  );
+}
+function normalizeModelUsageList(value, path) {
+  if (value === void 0) return [];
+  if (!Array.isArray(value)) {
+    fail(path, `expected an array when present, got ${describe(value)}`);
+  }
+  value.forEach((entry, index) => {
+    const entryPath = `${path}[${index}]`;
+    if (!isPlainObject(entry)) {
+      fail(entryPath, `expected an object, got ${describe(entry)}`);
+    }
+    requireNonEmptyString(entry.inference_model_name, `${entryPath}.inference_model_name`);
+    requireNonEmptyString(entry.inference_model_id, `${entryPath}.inference_model_id`);
+    if (entry.model_type === void 0) {
+      entry.model_type = "unknown";
+    } else {
+      requireNonEmptyString(entry.model_type, `${entryPath}.model_type`);
+    }
+    requireNumber(entry.inference_calls, `${entryPath}.inference_calls`);
+    requireNumber(entry.rated_inference_calls, `${entryPath}.rated_inference_calls`);
+    requireNullableNumber(entry.cost, `${entryPath}.cost`);
+  });
+  return value;
+}
 function validateNode(node, path) {
   if (!isPlainObject(node)) {
     fail(path, `expected an object, got ${describe(node)}`);
@@ -124,6 +196,11 @@ function validateNode(node, path) {
   }
   io.inputs.forEach((item, j) => validateIoItem(item, `${path}.io.inputs[${j}]`));
   io.outputs.forEach((item, j) => validateIoItem(item, `${path}.io.outputs[${j}]`));
+  if (node.usage === null) {
+    delete node.usage;
+  } else if (node.usage !== void 0) {
+    validateUsage(node.usage, `${path}.usage`);
+  }
 }
 function validateEdge(edge, path) {
   if (!isPlainObject(edge)) {
@@ -173,6 +250,15 @@ function validateGraphSpec(raw) {
       `expected an object when present, got ${describe(raw.concept_registry)}`
     );
   }
+  if (raw.usage === null) {
+    delete raw.usage;
+  } else if (raw.usage !== void 0) {
+    if (!isPlainObject(raw.usage)) {
+      fail("usage", `expected an object when present, got ${describe(raw.usage)}`);
+    }
+    validateUsage(raw.usage.total, "usage.total");
+    validateUsage(raw.usage.unattributed, "usage.unattributed");
+  }
   raw.nodes.forEach((node, i) => validateNode(node, `nodes[${i}]`));
   raw.edges.forEach((edge, i) => validateEdge(edge, `edges[${i}]`));
   return raw;
@@ -1491,181 +1577,6 @@ function applyControllers(layoutedNodes, layoutedEdges, graphspec, analysis, sho
   return { nodes: allNodes, edges: filteredEdges };
 }
 
-// src/graph/graphConfig.ts
-var FONT_TOKENS = {
-  "--font-sans": '"Inter", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif',
-  "--font-mono": '"JetBrains Mono", "Monaco", "Menlo", monospace'
-};
-var DARK_PALETTE_COLORS = __spreadProps(__spreadValues({}, FONT_TOKENS), {
-  // Surfaces
-  "--surface-page": "#0a0a0a",
-  "--surface-panel": "#111118",
-  "--surface-overlay": "rgba(17, 17, 24, 0.8)",
-  "--surface-overlay-hover": "rgba(30, 30, 40, 0.9)",
-  "--surface-overlay-disabled": "rgba(17, 17, 24, 0.6)",
-  "--surface-elevated": "rgba(255, 255, 255, 0.06)",
-  "--surface-elevated-hover": "rgba(255, 255, 255, 0.1)",
-  "--surface-sunken": "rgba(255, 255, 255, 0.03)",
-  "--surface-pill": "rgba(255, 255, 255, 0.06)",
-  "--surface-pill-border": "rgba(255, 255, 255, 0.08)",
-  // Borders
-  "--border-subtle": "rgba(255, 255, 255, 0.06)",
-  "--border-default": "rgba(255, 255, 255, 0.1)",
-  "--border-strong": "rgba(255, 255, 255, 0.18)",
-  "--border-dashed": "rgba(255, 255, 255, 0.15)",
-  // Text
-  "--text-primary": "#f8fafc",
-  "--text-default": "#e2e8f0",
-  "--text-secondary": "#cbd5e1",
-  "--text-muted": "#94a3b8",
-  "--text-dim": "#64748b",
-  "--text-on-accent": "#0e0e0e",
-  // Effects
-  "--shadow-sm": "0 2px 8px rgba(0, 0, 0, 0.4)",
-  "--shadow-md": "0 4px 16px rgba(0, 0, 0, 0.6)",
-  "--shadow-lg": "0 8px 24px rgba(0, 0, 0, 0.5)",
-  "--focus-ring": "rgba(59, 130, 246, 0.6)",
-  // Domain-semantic colors (graph nodes/edges)
-  "--color-pipe": "#ff6b6b",
-  "--color-pipe-bg": "rgba(224,108,117,0.18)",
-  "--color-pipe-text": "#ffffff",
-  "--color-stuff": "#4ECDC4",
-  "--color-stuff-bg": "rgba(78,205,196,0.12)",
-  "--color-stuff-border": "#9ddcfd",
-  "--color-stuff-text": "#98FB98",
-  "--color-stuff-text-dim": "#9ddcfd",
-  "--color-edge": "#FFFACD",
-  "--color-batch-item": "#bd93f9",
-  "--color-batch-aggregate": "#50fa7b",
-  "--color-parallel-combine": "#d6a4ff",
-  "--color-success": "#50FA7B",
-  "--color-success-bg": "rgba(80,250,123,0.15)",
-  "--color-error": "#FF5555",
-  "--color-error-bg": "rgba(255,85,85,0.15)",
-  "--color-error-border": "rgba(255,85,85,0.2)",
-  "--color-accent": "#8BE9FD",
-  "--color-accent-strong": "#3b82f6",
-  "--color-warning": "#FFB86C",
-  // Controller-group palette (tinted borders/backgrounds per controller type)
-  "--ctrl-sequence-border": "rgba(148, 163, 184, 0.25)",
-  "--ctrl-sequence-bg": "rgba(148, 163, 184, 0.03)",
-  "--ctrl-sequence-text": "#94a3b8",
-  "--ctrl-parallel-border": "rgba(139, 233, 253, 0.35)",
-  "--ctrl-parallel-bg": "rgba(139, 233, 253, 0.03)",
-  "--ctrl-parallel-text": "#8be9fd",
-  "--ctrl-condition-border": "rgba(251, 191, 36, 0.35)",
-  "--ctrl-condition-bg": "rgba(251, 191, 36, 0.03)",
-  "--ctrl-condition-text": "#fbbf24",
-  "--ctrl-batch-border": "rgba(167, 139, 250, 0.35)",
-  "--ctrl-batch-bg": "rgba(167, 139, 250, 0.03)",
-  "--ctrl-batch-text": "#a78bfa",
-  "--ctrl-folded-bg": "rgba(148, 163, 184, 0.25)",
-  "--ctrl-folded-border": "rgba(148, 163, 184, 0.4)",
-  // Legacy aliases — kept so existing inline styles in graph builders keep
-  // working until they're migrated. New code should use the semantic tokens.
-  "--color-bg": "#0a0a0a",
-  "--color-bg-dots": "rgba(255, 255, 255, 0.35)",
-  "--color-text-muted": "#94a3b8",
-  "--color-controller-text": "#94a3b8"
-});
-var LIGHT_PALETTE_COLORS = __spreadProps(__spreadValues({}, FONT_TOKENS), {
-  // Surfaces — chart stays a soft off-white, panels slightly cooler
-  "--surface-page": "#f8fafc",
-  "--surface-panel": "#ffffff",
-  "--surface-overlay": "rgba(255, 255, 255, 0.92)",
-  "--surface-overlay-hover": "rgba(241, 245, 249, 0.96)",
-  "--surface-overlay-disabled": "rgba(255, 255, 255, 0.7)",
-  "--surface-elevated": "rgba(15, 23, 42, 0.05)",
-  "--surface-elevated-hover": "rgba(15, 23, 42, 0.09)",
-  "--surface-sunken": "rgba(15, 23, 42, 0.03)",
-  "--surface-pill": "rgba(15, 23, 42, 0.05)",
-  "--surface-pill-border": "rgba(15, 23, 42, 0.1)",
-  // Borders
-  "--border-subtle": "rgba(15, 23, 42, 0.08)",
-  "--border-default": "rgba(15, 23, 42, 0.12)",
-  "--border-strong": "rgba(15, 23, 42, 0.22)",
-  "--border-dashed": "rgba(15, 23, 42, 0.18)",
-  // Text
-  "--text-primary": "#020617",
-  "--text-default": "#0f172a",
-  "--text-secondary": "#1e293b",
-  "--text-muted": "#475569",
-  "--text-dim": "#64748b",
-  "--text-on-accent": "#ffffff",
-  // Effects
-  "--shadow-sm": "0 2px 8px rgba(15, 23, 42, 0.08)",
-  "--shadow-md": "0 4px 16px rgba(15, 23, 42, 0.14)",
-  "--shadow-lg": "0 8px 24px rgba(15, 23, 42, 0.15)",
-  "--focus-ring": "rgba(2, 132, 199, 0.5)",
-  // Domain-semantic colors — darker for contrast on light backgrounds
-  "--color-pipe": "#dc2626",
-  "--color-pipe-bg": "rgba(220, 38, 38, 0.1)",
-  "--color-pipe-text": "#ffffff",
-  "--color-stuff": "#0891b2",
-  "--color-stuff-bg": "rgba(8, 145, 178, 0.08)",
-  "--color-stuff-border": "#0e7490",
-  "--color-stuff-text": "#0f172a",
-  "--color-stuff-text-dim": "#475569",
-  "--color-edge": "#64748b",
-  "--color-batch-item": "#7c3aed",
-  "--color-batch-aggregate": "#15803d",
-  "--color-parallel-combine": "#6d28d9",
-  "--color-success": "#15803d",
-  "--color-success-bg": "rgba(21, 128, 61, 0.12)",
-  "--color-error": "#dc2626",
-  "--color-error-bg": "rgba(220, 38, 38, 0.1)",
-  "--color-error-border": "rgba(220, 38, 38, 0.25)",
-  "--color-accent": "#0284c7",
-  "--color-accent-strong": "#0284c7",
-  "--color-warning": "#d97706",
-  // Controller-group palette
-  "--ctrl-sequence-border": "rgba(71, 85, 105, 0.3)",
-  "--ctrl-sequence-bg": "rgba(71, 85, 105, 0.04)",
-  "--ctrl-sequence-text": "#475569",
-  "--ctrl-parallel-border": "rgba(8, 145, 178, 0.4)",
-  "--ctrl-parallel-bg": "rgba(8, 145, 178, 0.05)",
-  "--ctrl-parallel-text": "#0e7490",
-  "--ctrl-condition-border": "rgba(217, 119, 6, 0.4)",
-  "--ctrl-condition-bg": "rgba(217, 119, 6, 0.05)",
-  "--ctrl-condition-text": "#b45309",
-  "--ctrl-batch-border": "rgba(124, 58, 237, 0.4)",
-  "--ctrl-batch-bg": "rgba(124, 58, 237, 0.05)",
-  "--ctrl-batch-text": "#6d28d9",
-  "--ctrl-folded-bg": "rgba(71, 85, 105, 0.18)",
-  "--ctrl-folded-border": "rgba(71, 85, 105, 0.35)",
-  // Legacy aliases
-  "--color-bg": "#f8fafc",
-  "--color-bg-dots": "rgba(15, 23, 42, 0.18)",
-  "--color-text-muted": "#475569",
-  "--color-controller-text": "#475569"
-});
-function getPaletteForTheme(theme) {
-  return theme === GRAPH_THEME.LIGHT ? LIGHT_PALETTE_COLORS : DARK_PALETTE_COLORS;
-}
-var DEFAULT_GRAPH_CONFIG = {
-  direction: "LR",
-  showControllers: false,
-  foldMode: FOLD_MODE.EXPANDED,
-  // `system` follows the host environment (OS/browser, or editor theme) out of
-  // the box — the least-surprising default for an embedded component. Hosts
-  // that want a fixed appearance pass `theme: "dark"` / `"light"` explicitly.
-  theme: GRAPH_THEME_MODE.SYSTEM,
-  // Backward-compatible default: the toolbar stays pinned top-right unless the
-  // host overrides it via `config.toolbarPosition` or the `toolbarPosition` prop.
-  toolbarPosition: TOOLBAR_POSITION.TOP_RIGHT,
-  nodesep: 50,
-  ranksep: 100,
-  edgeType: EDGE_TYPE.DEFAULT,
-  initialZoom: null,
-  panToTop: true
-  // `paletteColors` intentionally omitted from the default. The viewer derives
-  // the palette from the active `theme`. Consumers only set `paletteColors` to
-  // override specific tokens (sparse merge on top of the theme palette).
-};
-function getPaletteColors() {
-  return DARK_PALETTE_COLORS;
-}
-
 export {
   GraphSpecValidationError,
   validateGraphSpec,
@@ -1693,11 +1604,6 @@ export {
   getLayoutedElements,
   MAX_VISIBLE_CONTROLLER_CHILDREN,
   buildControllerNodes,
-  applyControllers,
-  DARK_PALETTE_COLORS,
-  LIGHT_PALETTE_COLORS,
-  getPaletteForTheme,
-  DEFAULT_GRAPH_CONFIG,
-  getPaletteColors
+  applyControllers
 };
-//# sourceMappingURL=chunk-UDA2XA23.js.map
+//# sourceMappingURL=chunk-BFQHQQ3E.js.map