Workflow editor

Preview

Install

First time? Get started sets up the registry and theme. Or with shadcn directly: npx shadcn@latest add @candor/workflow-editor

Brings in: bidi, button, change-hash, checkbox, combobox, date-range-picker, field, filter-bar, graph-layout, graph-view, heading-level, heading-scope, input, label, locale, locked, motion, number-input, radio-group, schedule-editor, select, textarea, tokens, utils · npm: lucide-react@^1.67.0

Usage

"use client"

import * as React from "react"
import type { FilterField } from "@/components/candor/filter-bar"
import { WorkflowEditor, type WorkflowAction, type WorkflowDefinition, type WorkflowEvent, type WorkflowIssue, type WorkflowNode } from "@/components/candor/workflow-editor"

const events: WorkflowEvent[] = [
  { id: "invoice.received", label: "An invoice arrives", description: "When the intake inbox receives an invoice and reads its fields." },
  { id: "invoice.disputed", label: "A supplier disputes a payment" },
]

const actions: WorkflowAction[] = [
  { id: "request-approval", label: "Ask finance to approve", description: "Opens an approval for the finance team; the workflow waits for it." },
  { id: "mark-ready", label: "Mark as ready to pay" },
  { id: "pay", label: "Schedule the payment", description: "Adds the invoice to the next payment run." },
  { id: "notify", label: "Post to the team channel" },
  { id: "hold", label: "Put the invoice on hold" },
]

const fields: FilterField[] = [
  { id: "amount", label: "Amount", kind: "number" },
  { id: "supplier", label: "Supplier", kind: "option", options: [{ value: "new", label: "New" }, { value: "known", label: "Known" }] },
  { id: "reference", label: "Reference", kind: "text" },
]

const proposal: WorkflowDefinition = {
  trigger: { kind: "event", event: "invoice.received" },
  nodes: [
    {
      id: "big-or-new",
      kind: "condition",
      match: "any",
      rules: [
        { id: "r1", field: "amount", operator: "greaterThan", value: 5000 },
        { id: "r2", field: "supplier", operator: "is", value: "new" },
      ],
      whenTrue: [{ id: "approve", kind: "step", action: "request-approval", note: "Large amounts and new suppliers need a second look." }],
      whenFalse: [{ id: "ready", kind: "step", action: "mark-ready" }],
    },
    { id: "tell-team", kind: "step", action: "notify", note: "Say which way the invoice went." },
  ],
}

/** Your app's own rule: a payment needs an approval before it on the same path. */
function validate(definition: WorkflowDefinition): WorkflowIssue[] {
  const issues: WorkflowIssue[] = []
  const walk = (nodes: WorkflowNode[], approved: boolean): boolean => {
    let ok = approved
    for (const node of nodes) {
      if (node.kind === "step") {
        if (node.action === "request-approval") ok = true
        if (node.action === "pay" && !ok) issues.push({ node: node.id, message: "A payment needs an approval step before it on the same path." })
        if (node.action === "notify" && !node.note) issues.push({ node: node.id, message: "Say what the post is about, or the channel gets the invoice number alone.", severity: "warning" })
      } else {
        const a = walk(node.whenTrue, ok)
        const b = walk(node.whenFalse, ok)
        ok = a && b
      }
    }
    return ok
  }
  walk(definition.nodes, false)
  return issues
}

export default function Example() {
  const [saved, setSaved] = React.useState<string>()
  return (
    <div className="flex max-w-3xl flex-col gap-3">
      <WorkflowEditor
        title="Invoice intake"
        agent="Finance agent"
        proposal={proposal}
        events={events}
        actions={actions}
        fields={fields}
        validate={validate}
        timeZones={["Europe/London", "America/New_York", "Asia/Tokyo"]}
        onSave={(definition, hash) =>
          // Your server recomputes the hash from the definition it receives, stores both, and only then turns it on.
          new Promise<void>((done) =>
            window.setTimeout(() => {
              setSaved(`${definition.nodes.length} top-level steps · sha256:${hash.slice(0, 12)}…`)
              done()
            }, 900)
          )
        }
      />
      {saved && <p className="text-xs text-muted-foreground">Sent to the server: {saved}</p>}
    </div>
  )
}

<WorkflowEditor>

Strings

Motion

Set with --cd-motion-workflow-editor-<moment>-* in your brand file; the families are in the design reference.

Types

WorkflowEvent

Something in your app that can start a workflow: "A ticket is opened".

{ id: string; /** The event in your app's words. */ label: string; /** A line saying when it fires, shown under the choice. */ description?: string | undefined; }

WorkflowAction

Something a step can do, from your app's list: "Send an email", "Assign to a queue".

{ id: string; /** The action in your app's words. */ label: string; /** A line saying what it does, shown under the choice. */ description?: string | undefined; }

WorkflowTrigger

What starts the workflow: an event in your app, a schedule (in `schedule-editor`'s shape), or a person.

/** When the event fires; `null` while none is chosen. */ { kind: "event"; event: string | null; } /** On a schedule, its times wall-clock times in `timeZone` (an IANA name). */ | { kind: "schedule"; recurrence: ScheduleRecurrence; timeZone: string; } /** Only when a person starts it. */ | { kind: "manual"; }

WorkflowStep

A step: one action from your app's list, with a note in words.

{ /** Stable for this step. Your issues name it, and it is part of what's hashed. */ id: string; kind: "step"; /** The `id` of a `WorkflowAction`; `null` while none is chosen. */ action: string | null; /** What the step is for, in words. Shown as text, never as HTML or a link. */ note?: string | undefined; }

WorkflowCondition

An If/Else: terms built from your app's fields (as `filter-bar`'s rules), and what runs when they hold or don't.

{ /** Stable for this condition. Your issues name it, and it is part of what's hashed. */ id: string; kind: "condition"; /** "all": every term must hold. "any": one is enough. */ match: "all" | "any"; /** The terms, as FilterBar's rules: a field, an operator and a value. */ rules: FilterRule[]; /** What runs when the terms hold (Then). */ whenTrue: WorkflowNode[]; /** What runs when they don't (Else). */ whenFalse: WorkflowNode[]; }

WorkflowNode

A step or a condition. After a condition, the next node in its list runs whichever branch ran.

WorkflowStep | WorkflowCondition

WorkflowDefinition

A whole workflow: what starts it, and the nodes that run in order. This is what is saved and hashed.

{ trigger: WorkflowTrigger; nodes: WorkflowNode[] }

WorkflowIssue

A problem your app found, tied to the trigger or a node. One that names neither is about the whole workflow. Errors lock Save until they're gone; warnings are shown and don't.

{ /** The node it is about, by id. */ node?: string | undefined; /** It is about the trigger. */ trigger?: boolean | undefined; /** What is wrong, in words that say how to fix it. */ message: string; /** "error" (the default) locks Save; "warning" doesn't. */ severity?: "error" | "warning" | undefined; }

Terms used here

Change hash

The SHA-256 of a change in one canonical form (object keys sorted at every depth), the same in the browser and on the server. An approval is made against a hash, so the server can check that what runs is the change the person saw. If the person edits the change before allowing it, the hash is worked out again for the edited version.

Every term is defined in the glossary (Markdown).

Types from other items

The props above take these. Each is defined by another item; import it from the path shown.

HeadingLevel from @/lib/candor/heading-level

A heading's level in the page's outline: `1` is `<h1>`, `6` is `<h6>`. Every Candor item that draws a heading takes its `headingLevel` as this type; the level is where the heading sits in the outline, never how large it looks.

1 | 2 | 3 | 4 | 5 | 6