@sanity/workflow-diagram 0.0.0

package/dist/index.d.cts

@@ -0,0 +1,123 @@
+import type { HistoryEntry } from "@sanity/workflow-engine";
+import { JSX } from "react";
+import type { Stage } from "@sanity/workflow-engine";
+import type { Transition } from "@sanity/workflow-engine";
+import type { WorkflowDefinition } from "@sanity/workflow-engine";
+import type { WorkflowEvaluation } from "@sanity/workflow-engine";
+
+export declare function flattenTransitions(
+  stages: readonly Stage[],
+): FlatTransition[];
+
+/**
+ * A transition flattened with its source stage name. Definitions nest
+ * transitions per stage; the diagram wants a flat edge list keyed by `from`.
+ */
+export declare interface FlatTransition extends Transition {
+  from: string;
+}
+
+/**
+ * Context widget around the current stage — NOT a trimmed graph explorer.
+ * Only the current stage's own transitions render: `next` shows where the
+ * run can go (incoming collapses to short stubs), `previous` shows where it
+ * came from (outgoing collapses to stubs), `both` shows both sides with no
+ * stubs. Neighbor stages never show their own edges.
+ */
+export declare interface LocalView {
+  /** Which of the current stage's neighbors to render (default 'next'). */
+  show?: LocalViewShow | undefined;
+  /** Ultra compression: each side of the current stage collapses into ONE
+   *  synthetic edge and an "N stages" vertex (click it to expand to the
+   *  regular local view). Constant footprint whatever the workflow shape. */
+  groupEdges?: boolean | undefined;
+}
+
+export declare type LocalViewShow = "next" | "previous" | "both";
+
+/**
+ * Stage diagram for a workflow definition: stages + transitions laid out
+ * left-to-right, current stage highlighted, visited path toned by history.
+ * Hovering anywhere along a transition line opens its detail tooltip (title,
+ * description; machine name, GROQ filter and effects only in devMode); a
+ * gated transition additionally carries a lock marker on the line.
+ */
+export declare function WorkflowDiagram({
+  definition,
+  currentStage,
+  selectedStage,
+  onSelectStage,
+  history,
+  guardCount,
+  gatedTransitions,
+  local,
+  static: isStatic,
+  devMode,
+  explain,
+  evaluation,
+  height,
+}: WorkflowDiagramProps): JSX.Element;
+
+export declare interface WorkflowDiagramProps {
+  /** The whole definition, not just its stages: definition-level vocabulary
+   *  (field titles, author predicates) feeds features like human-language
+   *  explanations, so the contract asks for it up front. */
+  definition: WorkflowDefinition;
+  /** Highlight this stage as where the instance is now. */
+  currentStage?: string | undefined;
+  /** Controlled selection — mark this stage as inspected. */
+  selectedStage?: string | undefined;
+  /** Stage click (name) / pane click (undefined). Enables selection UX. */
+  onSelectStage?: ((stage: string | undefined) => void) | undefined;
+  /** Instance history; tones visited stages and traversed transitions. */
+  history?: readonly HistoryEntry[] | undefined;
+  /** Active mutation-guard count, shown as a lock on the current node. */
+  guardCount?: number | undefined;
+  /** Names of current-stage transitions that cannot fire yet — their
+   *  markers show a lock ("can't proceed, criteria unmet"). */
+  gatedTransitions?: readonly string[] | undefined;
+  /** Context snippet around the current stage instead of the whole workflow:
+   *  only the current stage's own transitions render ({@link LocalView.show}
+   *  picks next / previous / both). The hidden side collapses into short
+   *  ghost-anchored stubs whose tooltips name the hidden stage. Requires
+   *  currentStage. */
+  local?: LocalView | undefined;
+  /** Frozen canvas: no pan/zoom, no zoom controls — shows its initial fit.
+   *  Tooltips, hover highlight and selection stay live. */
+  static?: boolean | undefined;
+  /** Tooling mode: tooltips additionally show machine names, GROQ filters
+   *  and effects. Never on for end users. */
+  devMode?: boolean | undefined;
+  /** Explain the workflow in human language: tooltips gain each gate's
+   *  phrased requirements ("«Review decision» must be 'approve'") — derived
+   *  from the definition alone, so it works without an instance. */
+  explain?: boolean | undefined;
+  /** A live evaluation upgrades the explanations where it speaks — the
+   *  current stage's transitions and gates get real ✓/✗ verdicts from the
+   *  insight the engine already computed; the rest of the chart stays on
+   *  the static tier. Only read when {@link WorkflowDiagramProps.explain}
+   *  is on: `explain` is the feature gate, `evaluation` is its data. */
+  evaluation?: WorkflowEvaluation | undefined;
+  /** Height CEILING: the canvas hugs the laid-out content (and centers in
+   *  its parent) when the graph is smaller than this. */
+  height?: number | string | undefined;
+}
+
+/**
+ * The base `--ws-*` design tokens, mapped onto Sanity UI's card vars so the
+ * workflow tools (diagram, inspector, simulator) follow the ambient theme.
+ * Consumers retheme by overriding `--ws-*` on a wrapping element.
+ */
+export declare const WS_CARD_TOKENS: {
+  "--ws-accent": string;
+  "--ws-accent-bg": string;
+  "--ws-panel": string;
+  "--ws-ink": string;
+  "--ws-ink-2": string;
+  "--ws-border": string;
+  "--ws-red": string;
+  "--ws-positive": string;
+  "--ws-font": string;
+};
+
+export {};

package/dist/index.d.ts

@@ -0,0 +1,123 @@
+import type { HistoryEntry } from "@sanity/workflow-engine";
+import { JSX } from "react";
+import type { Stage } from "@sanity/workflow-engine";
+import type { Transition } from "@sanity/workflow-engine";
+import type { WorkflowDefinition } from "@sanity/workflow-engine";
+import type { WorkflowEvaluation } from "@sanity/workflow-engine";
+
+export declare function flattenTransitions(
+  stages: readonly Stage[],
+): FlatTransition[];
+
+/**
+ * A transition flattened with its source stage name. Definitions nest
+ * transitions per stage; the diagram wants a flat edge list keyed by `from`.
+ */
+export declare interface FlatTransition extends Transition {
+  from: string;
+}
+
+/**
+ * Context widget around the current stage — NOT a trimmed graph explorer.
+ * Only the current stage's own transitions render: `next` shows where the
+ * run can go (incoming collapses to short stubs), `previous` shows where it
+ * came from (outgoing collapses to stubs), `both` shows both sides with no
+ * stubs. Neighbor stages never show their own edges.
+ */
+export declare interface LocalView {
+  /** Which of the current stage's neighbors to render (default 'next'). */
+  show?: LocalViewShow | undefined;
+  /** Ultra compression: each side of the current stage collapses into ONE
+   *  synthetic edge and an "N stages" vertex (click it to expand to the
+   *  regular local view). Constant footprint whatever the workflow shape. */
+  groupEdges?: boolean | undefined;
+}
+
+export declare type LocalViewShow = "next" | "previous" | "both";
+
+/**
+ * Stage diagram for a workflow definition: stages + transitions laid out
+ * left-to-right, current stage highlighted, visited path toned by history.
+ * Hovering anywhere along a transition line opens its detail tooltip (title,
+ * description; machine name, GROQ filter and effects only in devMode); a
+ * gated transition additionally carries a lock marker on the line.
+ */
+export declare function WorkflowDiagram({
+  definition,
+  currentStage,
+  selectedStage,
+  onSelectStage,
+  history,
+  guardCount,
+  gatedTransitions,
+  local,
+  static: isStatic,
+  devMode,
+  explain,
+  evaluation,
+  height,
+}: WorkflowDiagramProps): JSX.Element;
+
+export declare interface WorkflowDiagramProps {
+  /** The whole definition, not just its stages: definition-level vocabulary
+   *  (field titles, author predicates) feeds features like human-language
+   *  explanations, so the contract asks for it up front. */
+  definition: WorkflowDefinition;
+  /** Highlight this stage as where the instance is now. */
+  currentStage?: string | undefined;
+  /** Controlled selection — mark this stage as inspected. */
+  selectedStage?: string | undefined;
+  /** Stage click (name) / pane click (undefined). Enables selection UX. */
+  onSelectStage?: ((stage: string | undefined) => void) | undefined;
+  /** Instance history; tones visited stages and traversed transitions. */
+  history?: readonly HistoryEntry[] | undefined;
+  /** Active mutation-guard count, shown as a lock on the current node. */
+  guardCount?: number | undefined;
+  /** Names of current-stage transitions that cannot fire yet — their
+   *  markers show a lock ("can't proceed, criteria unmet"). */
+  gatedTransitions?: readonly string[] | undefined;
+  /** Context snippet around the current stage instead of the whole workflow:
+   *  only the current stage's own transitions render ({@link LocalView.show}
+   *  picks next / previous / both). The hidden side collapses into short
+   *  ghost-anchored stubs whose tooltips name the hidden stage. Requires
+   *  currentStage. */
+  local?: LocalView | undefined;
+  /** Frozen canvas: no pan/zoom, no zoom controls — shows its initial fit.
+   *  Tooltips, hover highlight and selection stay live. */
+  static?: boolean | undefined;
+  /** Tooling mode: tooltips additionally show machine names, GROQ filters
+   *  and effects. Never on for end users. */
+  devMode?: boolean | undefined;
+  /** Explain the workflow in human language: tooltips gain each gate's
+   *  phrased requirements ("«Review decision» must be 'approve'") — derived
+   *  from the definition alone, so it works without an instance. */
+  explain?: boolean | undefined;
+  /** A live evaluation upgrades the explanations where it speaks — the
+   *  current stage's transitions and gates get real ✓/✗ verdicts from the
+   *  insight the engine already computed; the rest of the chart stays on
+   *  the static tier. Only read when {@link WorkflowDiagramProps.explain}
+   *  is on: `explain` is the feature gate, `evaluation` is its data. */
+  evaluation?: WorkflowEvaluation | undefined;
+  /** Height CEILING: the canvas hugs the laid-out content (and centers in
+   *  its parent) when the graph is smaller than this. */
+  height?: number | string | undefined;
+}
+
+/**
+ * The base `--ws-*` design tokens, mapped onto Sanity UI's card vars so the
+ * workflow tools (diagram, inspector, simulator) follow the ambient theme.
+ * Consumers retheme by overriding `--ws-*` on a wrapping element.
+ */
+export declare const WS_CARD_TOKENS: {
+  "--ws-accent": string;
+  "--ws-accent-bg": string;
+  "--ws-panel": string;
+  "--ws-ink": string;
+  "--ws-ink-2": string;
+  "--ws-border": string;
+  "--ws-red": string;
+  "--ws-positive": string;
+  "--ws-font": string;
+};
+
+export {};