@w6w/ui 0.0.0-stage → 0.1.0

package/dist/run-visuals.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Pure derivation of a live run's canvas visuals (T1.1.1) — step node styling
+ * and main-graph edge taken/skipped/untouched state. Plain functions of (run
+ * state, step/edge identity) → visual state, with **no React import**, so
+ * `node --test` exercises them directly (A7) the same way `flow-connect.ts`'s
+ * connection rules do.
+ *
+ * `RunStatus`/`StepStatus`/`RunState`/`StepExecution` below are thin LOCAL
+ * copies of the shapes `@w6w/workflow-types` declares
+ * (`packages/w6w-workflow/packages/types/mod.ts`) — the same house idiom
+ * `components/HealthStatusPill.tsx`'s `HealthPillState` uses, and the same
+ * design note `flow-types.ts`'s own header already states for
+ * `FlowWorkflow`/`FlowStep`: `packages/ui/package.json` has no dependency on
+ * `@w6w/workflow-types` and must not gain one, so this module stays a
+ * pure-presentation leaf with no transport/spec coupling. A caller who
+ * already has the real `RunState`/`StepExecution` is structurally compatible
+ * for free.
+ */
+/** Mirrors `RunStatus` in `@w6w/workflow-types`. */
+export type RunStatus = "queued" | "running" | "succeeded" | "failed" | "canceled";
+/** Mirrors `StepStatus` in `@w6w/workflow-types`. */
+export type StepStatus = "pending" | "running" | "succeeded" | "failed" | "skipped";
+/** The slice of `StepExecution` this module reads. */
+export interface StepExecution {
+    status: StepStatus;
+}
+/** The slice of `RunState` this module reads — steps keyed by step id, same
+ *  as the engine's own `RunState.steps`. */
+export interface RunState {
+    status: RunStatus;
+    steps: Record<string, StepExecution>;
+}
+/**
+ * A step node's rendered state — exactly the five {@link StepStatus} values
+ * plus `"no-run"` (A2): `runState` omitted ⇒ `"no-run"` (this canvas isn't
+ * showing any run). A step present in `runState.steps` renders its own
+ * recorded status; a step the run hasn't reached yet has no entry there at
+ * all (only steps that were actually started/skipped get a `StepExecution` —
+ * see the engine's `recordSkipped`), so absence reads as `"pending"`.
+ */
+export type StepVisualState = "no-run" | StepStatus;
+/**
+ * The rendered state for step `stepId` under `runState` — the StepStatus
+ * half of A3's RunStatus × StepStatus mapping. Pure function of the run's own
+ * step records; no additional data needed (`GET /runs/:id` already returns
+ * everything this reads).
+ */
+export declare function stepVisualState(runState: RunState | undefined, stepId: string): StepVisualState;
+/** One node's non-persisted, run-aware look. Colour is never the only signal
+ *  (the house rule `HealthStatusPill`'s own doc comment states) — every
+ *  non-default state also differs from the default (`"no-run"`) in
+ *  `borderStyle`, `borderWidth`, or `opacity`. */
+export interface StepNodeVisual {
+    borderColor: string;
+    borderStyle: "solid" | "dashed";
+    borderWidth: number;
+    opacity: number;
+}
+/**
+ * The node visual for a step's {@link StepVisualState}, `runStatus`
+ * (the owning run's OWN status) additionally distinguishing the `"pending"`
+ * case — A3: a `canceled`/`failed` run's not-yet-reached steps render
+ * dimmer/muted (they never will run) than a `queued`/`running` run's
+ * not-yet-reached steps (they still might), even though both share the same
+ * `StepVisualState`. Every token used is one of the five named in
+ * `context.notes` (`--w6w-accent`/`--w6w-success`/`--w6w-danger`/
+ * `--w6w-muted`/`--w6w-border`) — never a literal hex, never a different
+ * token family.
+ */
+export declare function stepNodeVisual(state: StepVisualState, runStatus?: RunStatus): StepNodeVisual;
+/** Whether a main-graph edge was taken, skipped, or left untouched by the
+ *  run (`undefined` — the source step hasn't been decided yet, or there is
+ *  no run). */
+export type EdgeRunState = "taken" | "skipped";
+/**
+ * Whether the edge `from --(when)--> …` was taken or skipped in `runState` —
+ * computable from the run's step records alone (no engine data beyond what
+ * `GET /runs/:id` already returns):
+ *   - `from` **succeeded**: its `"success"`/omitted-`when` edges are taken,
+ *     its `"error"` edges are skipped.
+ *   - `from` **failed**: a declared `"error"` edge is taken, every other
+ *     outgoing edge (the `"success"` lane) is skipped.
+ *   - `from` was itself **skipped** (reached only through a skipped edge —
+ *     the engine's own `recordSkipped`/`markOutgoingEdgesSkipped`): every
+ *     outgoing edge is skipped too, regardless of lane — a step that never
+ *     ran cannot have taken an exit.
+ *   - `from` is **running**, or has no record at all (not yet reached): the
+ *     edge's fate isn't decided yet ⇒ `undefined`.
+ */
+export declare function edgeRunState(runState: RunState | undefined, from: string, when: "success" | "error" | undefined): EdgeRunState | undefined;

package/dist/step-preview-state.d.ts

@@ -0,0 +1,143 @@
+import { Edge } from '@xyflow/react';
+import { ExpressionStepSource } from './components/ExpressionOptions.tsx';
+import { StepNode } from './flow-utils.ts';
+import { ActionShapeDef } from './output-shape.ts';
+import { StepMeta, StepStartState, StepTest } from './provider.tsx';
+/**
+ * What the editor knows about upstream steps' output SHAPES beyond the static
+ * `internalNodeDef(...).output` — both optional, so a caller without them gets
+ * exactly the old projection.
+ */
+export interface StepShapeContext {
+    /**
+     * An app step's action definition (its declared `output` / `sample`).
+     * `undefined` while that app's actions haven't loaded — the step then makes
+     * no "run a test" claim it might have to retract a moment later.
+     */
+    actionDef?: (app: string, action: string) => ActionShapeDef | undefined;
+    /** Each step's latest saved test-run output, by step id. */
+    testOutputs?: Record<string, unknown>;
+}
+/** A graph ancestor carrying a saved step-test, offered as a one-click seed. */
+export interface SeedSource {
+    stepId: string;
+    label: string;
+    test: StepTest;
+}
+/**
+ * `pendingConnect`'s shape (`WorkflowFlowEditor.tsx`'s state): the handle a
+ * connection drag was released from, when it ended on empty canvas and opened
+ * the step builder to create + auto-wire a new node. `position` is part of
+ * that state too (where to place the new node) but unused by the direction
+ * rule below, so it is deliberately omitted here — `pendingConnect`'s real
+ * type carries it, and a wider object satisfies this narrower one structurally.
+ */
+interface PendingConnect {
+    nodeId: string;
+    handleType: "source" | "target";
+}
+/**
+ * The workflow state a given step can reference: the outputs of every step
+ * that runs before it (its graph ancestors) plus whether a trigger precedes
+ * it.
+ *
+ * A trigger ancestor is **both**. It is pushed into `steps` like any other
+ * ancestor — `core/rfcs/node-types.md` ("Triggers as nodes"): *"Executing a
+ * trigger node yields the run's start payload … which downstream nodes read as
+ * `steps.<triggerId>.output`"* — **and** it sets `hasTrigger`, which offers the
+ * separate `trigger.event` root. The two are different values, not two spellings
+ * of one: `trigger.event` is the dispatcher-delivered event payload (seeded from
+ * `seed.event`), while a manual trigger's filled fields land under
+ * `steps.<id>.output`. Offering only the former is why a trigger's declared
+ * fields were unreachable from the picker.
+ *
+ * A **manual trigger** that declares output fields (`with.fields`) carries
+ * them as `outputs`, so a consumer can offer `steps.<id>.output.<key>` per
+ * field. Only a manual trigger: `fields` is an ordinary param name, and on any
+ * other node — including a webhook/scheduler entry node, whose payload is
+ * `trigger.event` instead (see the ⚠️ note below) — it holds that action's
+ * INPUT; an `@w6w/http:request` with `with.fields = [{key:"x"}]` would
+ * otherwise be advertised as declaring an output `x` it never produces. The
+ * manual trigger's `fields` is the one case where the param IS the output
+ * contract (`core/rfcs/node-types.md:194-196`; `trigger.md:119` covers only
+ * what drives editor autocomplete).
+ *
+ * ⚠️ These declared fields resolve differently on each run path. On the
+ * **single-step Test / ▶ Run** path (below), this editor sends a start state
+ * seeded from the upstream saved fixtures (see {@link startStateFromSeeds})
+ * which `POST /apps/:id/actions/:key/invoke` projects onto
+ * `steps.<id>.output`. On a **full run**, a manual trigger's declared fields
+ * resolve too: `POST /workflows/:id/run` accepts an `input` body field, and
+ * `run-workflow.ts` seeds the `@w6w/trigger` node's own output with it
+ * (verified by `server/e2e/trigger_run_payload_e2e_test.ts`). A
+ * webhook/scheduler entry node's declared fields do **not** resolve on a full
+ * run — its payload there is `trigger.event`, not `steps.<id>.output`, by
+ * design (`core/rfcs/trigger.md:378`) — which is exactly why the projection
+ * above is narrowed to a manual trigger only.
+ *
+ * With no specific step (shouldn't happen for a field edit) every node is offered.
+ */
+export declare function upstreamStateSources(editingId: string | null, nodes: StepNode[], edges: Edge[], shapes?: StepShapeContext): {
+    steps: ExpressionStepSource[];
+    hasTrigger: boolean;
+};
+/**
+ * The new add-step wizard's graph ancestors, derived from `pendingConnect` —
+ * the handle a connection drag was released from before the builder opened
+ * (`null` for a floating add with no drag at all).
+ *
+ * **Direction matters.** `addBuiltStep`'s edge-wiring ternary
+ * (`WorkflowFlowEditor.tsx`) only makes the new step DOWNSTREAM of
+ * `pendingConnect.nodeId` when the drag came off a **source** handle
+ * (`[pendingConnect.nodeId, id]`); off a **target** handle the new step becomes
+ * the edge's SOURCE instead (`[id, pendingConnect.nodeId]`), so
+ * `pendingConnect.nodeId` ends up downstream of the new step, not upstream —
+ * offering it as a seed would be backwards. A `handleType: "source"` drag
+ * carries the dragged node itself (it IS upstream of the step about to be
+ * created) plus that node's own ancestors, via the same projection
+ * {@link upstreamStateSources} uses.
+ */
+export declare function stepBuilderUpstreamSteps(pendingConnect: PendingConnect | null, nodes: StepNode[], edges: Edge[], shapes?: StepShapeContext): ExpressionStepSource[];
+/**
+ * Gather each graph ancestor's latest saved step-test so the incoming-state
+ * control can offer it as a seed. **One implementation**, called by every
+ * surface that mounts {@link SeedSource}s — the step editor's Test tab, the
+ * canvas ▶ Run collect form, and `StepBuilderModal`'s add-step Test tab — so
+ * the `gate_1 · succeeded` chip behaves identically everywhere.
+ *
+ * `listStepTests` is injected (rather than reached for via `useW6WApi()`
+ * directly) so this stays a plain async function `node --test` can call with a
+ * stub — the React-facing wrapper is `use-seed-sources.ts`'s `useSeedSources`.
+ * It returns oldest-first per step, so the last entry is the most recent
+ * fixture. A step with no saved fixture (an empty list, or a lookup that
+ * throws) contributes nothing — best-effort, per step, never breaking the rest.
+ */
+export declare function fetchSeedSources(listStepTests: (stepId: string) => Promise<StepTest[]>, upstreamSteps: ExpressionStepSource[]): Promise<SeedSource[]>;
+/**
+ * The start state a single-step Test / ▶ Run is sent with: **the last-known
+ * saved output of each upstream step**, keyed by step id, in the shape the
+ * invoke route accepts (`{ steps: { <id>: { output } } }` — the server's
+ * `StartStateInput`, `packages/api/ambient-scope.ts`). It is what makes a
+ * `with` block written as `{{ steps.<id>.output.<field> }}` resolve to the
+ * value that step last produced instead of concatenating as `""`.
+ *
+ * Read from the same `step_tests` fixtures the seed chips offer — no upstream
+ * step is re-run to produce it, and nothing here is computed live.
+ *
+ * A step whose fixture never captured an output contributes **no entry** rather
+ * than an empty one, and a set with no outputs at all returns `undefined` so
+ * the invoke body carries no `state` key at all (byte-identical to a request
+ * from before this existed). Each id gets its OWN `{ output }` object: sharing
+ * one would make every reference resolve the last step's data.
+ *
+ * ⚠️ Single-step scope only. A full run (`POST /workflows/:id/run`) builds its
+ * own scope and is not affected by this.
+ */
+export declare function startStateFromSeeds(seeds: SeedSource[]): StepStartState | undefined;
+/**
+ * Sample values for a step's `steps.<id>.meta.*` refs, from a saved fixture's
+ * `lastRunMeta`. Reads the four named fields only; absent meta yields nothing
+ * (a version or connection is never derived from anywhere else).
+ */
+export declare function stepMetaSampleValues(stepId: string, meta: StepMeta | null | undefined): Record<string, unknown>;
+export {};

package/dist/theme.d.ts

@@ -0,0 +1,32 @@
+import { ThemeMode } from './types.ts';
+/**
+ * Set by `<W6WUIProvider theme={...}>` (`provider.tsx`) — the HOST's
+ * explicit theme choice for an EMBEDDED `@w6w/ui`, threaded through context
+ * so every JS-side theme-aware component resolves the SAME value the
+ * provider's own `data-theme` DOM wrapper sets for the CSS side (below),
+ * without each component separately re-deriving it from `<html>`.
+ * `undefined` when no `<W6WUIProvider>` is in the tree, or one that didn't
+ * pass `theme` — every consumer then falls through to the pre-existing
+ * `data-theme`-on-`<html>` / OS-preference chain unchanged. See
+ * `docs/theming.md`.
+ */
+export declare const ProvidedThemeCtx: import('react').Context<ThemeMode | undefined>;
+/**
+ * Resolve the effective light/dark mode. Priority: explicit prop >
+ * `<W6WUIProvider theme>` > `data-theme` on <html> > `prefers-color-scheme`.
+ * The `data-theme` step matches the CSS defaults in `styles.css`, so
+ * components and stylesheet agree even without a provider `theme` — see
+ * `docs/theming.md` for why relying on that alone is a trap for an embedded
+ * host, though.
+ */
+export declare function detectTheme(explicit: ThemeMode | undefined, provided?: ThemeMode): ThemeMode;
+/**
+ * Reactive `detectTheme`: reads `<W6WUIProvider theme>` from context, and —
+ * when that's unset — subscribes to `data-theme` mutations on <html> and OS
+ * `prefers-color-scheme` changes, so a runtime theme toggle (e.g. studio's
+ * ThemeToggle, or a host re-rendering `<W6WUIProvider theme>` with a new
+ * value) is reflected without a remount. Shared by every ui component that
+ * needs the mode in JS (AppIcon, CodeEditor, JsonEditor, WorkflowFlowEditor)
+ * so they never drift from each other or from the CSS.
+ */
+export declare function useEffectiveTheme(explicit?: ThemeMode): ThemeMode;

package/dist/trigger-fields.d.ts

@@ -0,0 +1,56 @@
+import { ActionParam } from './types.ts';
+/**
+ * One field configured on a manual (`@w6w/trigger`) or webhook (`@w6w/webhook`)
+ * trigger — the `fields` param stores an array of these *definitions*
+ * (`{ key, type, default, required }`), not values. The Test tab derives a
+ * fillable form from them (see `TriggerFillForm`).
+ */
+export interface TriggerFieldDef {
+    key?: string;
+    /** Declared value type — maps to an existing `ParamsForm` widget. */
+    type?: string;
+    /** Author-declared default (stored as text on the trigger config). */
+    default?: unknown;
+    required?: boolean;
+}
+/** Read a trigger's `fields` param value as an array of field definitions. */
+export declare function asFieldDefs(fields: unknown): TriggerFieldDef[];
+/**
+ * Map a field def's declared type onto one of the `ParamsForm` scalar
+ * widgets. `object`/`array` (a `WorkflowVariable`'s type union,
+ * `w6w-workflow/packages/types/mod.ts:40-45` — this seam is also reused for
+ * T1.1.5's run-page form) render as the `json` widget, same as an explicit
+ * `json` declaration: there is no dedicated object/array widget, and `json`
+ * is the one that round-trips a structured value without flattening it to
+ * text. Verified inert for the trigger `fields` editor itself: its type
+ * `<select>` offers exactly `string|number|boolean|json`
+ * (`flow-types.ts:343-353`), so no editor-authored trigger field can reach
+ * these two arms — only a call site that hands in `WorkflowVariable.type`
+ * can.
+ */
+export declare function fieldWidget(type: string | undefined): ActionParam["type"];
+/**
+ * Coerce a field's author-declared default into a value of the field's
+ * declared type, so the derived form seeds a sensible starting value and the
+ * required gate sees it as filled. Returns `undefined` for an empty/invalid
+ * default (the operator then supplies the value).
+ *
+ * A trigger field's default is stored as **text** and needs parsing; a
+ * `WorkflowVariable`'s default is stored as a **real JSON value already**
+ * (T1.1.5) — coercing it through `String(...)` would flatten `{a:1}` to the
+ * literal text `"[object Object]"` and `[1,2]` to `"1,2"`, and re-parsing
+ * `String({a:1})` as JSON fails outright (`coerceDefault("json", {a:1})` used
+ * to return `undefined`, silently dropping the default). So an already-object
+ * or already-array `raw` is returned unchanged, before any type-specific
+ * branch runs — this holds regardless of `type`, because the value needs no
+ * coercion either way.
+ */
+export declare function coerceDefault(type: string | undefined, raw: unknown): unknown;
+/**
+ * Project a trigger's `fields` definitions into a `ParamsForm`-compatible param
+ * list — one input per declared field, keyed by the field's `key`, rendered with
+ * the existing per-type widget. Unnamed fields are skipped.
+ */
+export declare function fieldsToParams(defs: TriggerFieldDef[]): ActionParam[];
+/** Seed the fill-form values from each declared field's (coerced) default. */
+export declare function seedValues(defs: TriggerFieldDef[]): Record<string, unknown>;