@sanity/workflow-studio-plugin 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sanity, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,357 @@
+# @sanity/workflow-studio-plugin
+
+> **Status: private, unpublished.** This README describes the intended
+> consumer setup for when the package is published. Every
+> `@sanity/workflow-*` package is pre-1.0; APIs may change.
+
+Editorial workflows inside Sanity Studio. You describe a workflow in code —
+stages like _Drafting → Review → Approved_, and the actions that move work
+between them — deploy it to your dataset, and this plugin gives editors the
+UI: a **workflow strip** above the editor form of mapped documents (the
+current stage, your task count, and a **Start workflow** button), and a
+**Workflows tab** next to the editor with the stage's activities and action
+items, where they fire actions and read the history.
+
+Four ideas cover everything in this guide:
+
+- A **definition** describes a workflow's stages and actions. It's authored
+  in code and deployed as a document into your dataset.
+- An **instance** is one run of a definition, attached to one of your
+  documents. Starting a workflow creates an instance; firing actions moves it
+  through stages.
+- The **plugin** (this package) is the Studio UI over both.
+- A small **runtime** you host (two Sanity Functions, step 5) handles what
+  editors can't: waits that resolve on a timer, and side-effects that should
+  run unattended.
+
+Everything the plugin checks is **advisory** — it disables the right buttons
+and explains why, but the Content Lake is the only enforcement point. Don't
+treat plugin-side checks as a security boundary.
+
+## 1. Install
+
+```sh
+npm install @sanity/workflow-studio-plugin @sanity/workflow-engine @sanity/workflow-cli
+```
+
+Requires a Studio v5 project (`sanity ^5.30`, `react ^19`,
+`styled-components ^6`, `@sanity/sdk ^2.12` — the usual studio peers).
+
+## 2. Define a workflow
+
+A complete, working definition — a document goes _Drafting → Review →
+Approved_; a writer submits, an editor approves. Save as
+`workflows/article-review.ts` next to your studio config:
+
+```ts
+import {defineWorkflow} from '@sanity/workflow-engine/define'
+
+export const articleReview = defineWorkflow({
+  name: 'article-review',
+  title: 'Article review',
+  description: 'Draft, review, approve.',
+  initialStage: 'drafting',
+  fields: [
+    // The document this workflow is about. The plugin fills it in when an
+    // editor starts the workflow from a document.
+    {type: 'doc.ref', name: 'subject', title: 'Article', initialValue: {type: 'input'}},
+  ],
+  stages: [
+    {
+      name: 'drafting',
+      title: 'Drafting',
+      activities: [
+        {
+          name: 'write',
+          title: 'Write the article',
+          activation: 'auto',
+          // `status: 'done'` = firing this action completes the activity.
+          actions: [{name: 'submit', title: 'Submit for review', status: 'done'}],
+        },
+      ],
+      // No filter = the stage advances once all its activities are done.
+      transitions: [{name: 'to-review', title: 'Send to review', to: 'review'}],
+    },
+    {
+      name: 'review',
+      title: 'Editorial review',
+      activities: [
+        {
+          name: 'review',
+          title: 'Review the article',
+          activation: 'auto',
+          actions: [{name: 'approve', title: 'Approve', status: 'done'}],
+        },
+      ],
+      transitions: [{name: 'to-approved', title: 'Approve', to: 'approved'}],
+    },
+    // No transitions out = terminal stage. The workflow completes here.
+    {name: 'approved', title: 'Approved', activities: []},
+  ],
+})
+```
+
+## 3. Deploy it
+
+Save as `sanity.workflow.ts` next to your studio config, filling in your
+project id and dataset:
+
+```ts
+import {defineWorkflowConfig} from '@sanity/workflow-engine/define'
+import {articleReview} from './workflows/article-review'
+
+export default defineWorkflowConfig({
+  deployments: [
+    {
+      name: 'production',
+      // The tag namespaces all workflow data — the plugin only sees
+      // definitions and instances deployed under the tag it's configured with.
+      tag: 'production',
+      workflowResource: {type: 'dataset', id: '<projectId>.<dataset>'},
+      definitions: [articleReview],
+    },
+  ],
+})
+```
+
+```sh
+npx sanity-workflows deploy --tag production   # add --dry-run to preview
+```
+
+Auth comes from your `sanity login` session (or a `SANITY_AUTH_TOKEN` env
+var). Deploys are idempotent — re-running with an unchanged definition is a
+no-op.
+
+## 4. Wire the studio
+
+Add to your `sanity.config.ts`, replacing `article` with one of your own
+document types:
+
+```ts
+import {defineConfig} from 'sanity'
+import {structureTool} from 'sanity/structure'
+import {
+  workflowDefaultDocumentNode,
+  workflowStudioPlugin,
+  type WorkflowMapping,
+} from '@sanity/workflow-studio-plugin'
+
+const workflowMappings: readonly WorkflowMapping[] = [
+  {
+    docType: 'article', // your schema type
+    definition: 'article-review', // the deployed definition's `name`
+    subjectKind: 'document',
+    subjectGdrType: 'article',
+    label: 'Article review',
+  },
+]
+
+export default defineConfig({
+  // ...your projectId, dataset, schema...
+  plugins: [
+    structureTool({
+      // Adds the "Workflows" tab next to the editor for mapped types.
+      defaultDocumentNode: workflowDefaultDocumentNode({mappings: workflowMappings}),
+    }),
+    workflowStudioPlugin({
+      tag: 'production', // must match the deploy tag
+      mappings: workflowMappings,
+    }),
+  ],
+})
+```
+
+Start the studio and open an `article`: the workflow strip above the form
+offers **Start workflow**. Once started, the strip shows the current
+stage, the document footer shows an **active workflow** chip, and the
+**Workflows** tab lists the stage's activities — click one to open it and
+fire _Submit for review_, then _Approve_, and watch it reach Approved.
+
+### Stage badges in document lists
+
+`WorkflowStagePreview` puts each document's current stage in the list pane's
+status slot (it defers to the default preview for everything else). Wire it
+per mapped schema type via `components.preview`, and select `_id` in the
+type's `preview` so the component knows which document to look up — a custom
+`prepare` must pass `_id` through:
+
+```ts
+import {WorkflowStagePreview} from '@sanity/workflow-studio-plugin'
+import {defineType} from 'sanity'
+
+export const article = defineType({
+  name: 'article',
+  type: 'document',
+  fields: [
+    /* ... */
+  ],
+  preview: {
+    select: {_id: '_id', title: 'title'},
+    prepare: ({_id, title}) => ({_id, title}),
+  },
+  components: {preview: WorkflowStagePreview},
+})
+```
+
+Plugin options, for later: `workflowDataset` (keep workflow state in a
+separate dataset), `effectHandlers` (run effect side-effects in the browser
+— the runtime below is usually the better home), and per-mapping `mandatory`
+(gate the editor form until a workflow is attached), `initialStateBuilder`,
+and `perspectiveField` (bind a release to the workflow).
+
+## 5. Add the runtime (two Sanity Functions)
+
+Everything above works with editors driving. Two things need a caller when
+no editor is looking, and both are small
+[Sanity Functions](https://www.sanity.io/docs/functions):
+
+- **heartbeat** — definitions can wait on time (`completeWhen` conditions
+  over `$now`, e.g. an embargo date). Time passing emits no event, so a
+  schedule must periodically `tick` in-flight instances. Ticking an instance
+  with nothing due is a no-op.
+- **drain-effects** — definitions can queue **effects** (named side-effects
+  like "publish the subject"). This function runs your handlers for them
+  whenever an instance has pending effects. Effects it has no handler for
+  stay pending; completing one re-triggers the function, so cascades drain
+  themselves.
+
+`functions/heartbeat/index.ts`:
+
+```ts
+import {createClient} from '@sanity/client'
+import {scheduledEventHandler} from '@sanity/functions'
+import {createEngine, type WorkflowClient} from '@sanity/workflow-engine'
+
+const TAG = 'production'
+
+export const handler = scheduledEventHandler(async ({context}) => {
+  const projectId = process.env.SANITY_PROJECT_ID
+  const dataset = process.env.SANITY_DATASET ?? 'production'
+  if (!projectId) throw new Error('heartbeat: SANITY_PROJECT_ID is required')
+
+  const client = createClient({
+    projectId,
+    dataset,
+    apiVersion: '2026-04-29',
+    useCdn: false,
+    perspective: 'raw',
+    token: context.clientOptions?.token,
+  })
+  const engine = createEngine({
+    client: client as unknown as WorkflowClient,
+    tag: TAG,
+    workflowResource: {type: 'dataset', id: `${projectId}.${dataset}`},
+  })
+
+  const inflight = await engine.query<{_id: string}[]>({
+    groq: `*[_type == "sanity.workflow.instance" && tag == $tag && !defined(completedAt)]{_id}`,
+  })
+  for (const {_id} of inflight) {
+    await engine.tick({instanceId: _id})
+  }
+})
+```
+
+`functions/drain-effects/index.ts`:
+
+```ts
+import {createClient} from '@sanity/client'
+import {documentEventHandler} from '@sanity/functions'
+import {createEngine, type EffectHandler, type WorkflowClient} from '@sanity/workflow-engine'
+
+const TAG = 'production'
+
+// Your side-effects, keyed by the effect names your definitions queue.
+const effectHandlers: Record<string, EffectHandler> = {
+  // 'publish.article': async (params, ctx) => { ... },
+}
+
+export const handler = documentEventHandler(async ({event, context}) => {
+  const projectId = process.env.SANITY_PROJECT_ID
+  const dataset = process.env.SANITY_DATASET ?? 'production'
+  if (!projectId) throw new Error('drain-effects: SANITY_PROJECT_ID is required')
+
+  const client = createClient({
+    projectId,
+    dataset,
+    apiVersion: '2026-04-29',
+    useCdn: false,
+    perspective: 'raw',
+    token: context.clientOptions?.token,
+  })
+  const engine = createEngine({
+    client: client as unknown as WorkflowClient,
+    tag: TAG,
+    workflowResource: {type: 'dataset', id: `${projectId}.${dataset}`},
+    effectHandlers,
+    // Leave effects this runtime has no handler for pending, for another
+    // runtime (or the Studio's manual controls) to resolve.
+    missingHandler: 'skip',
+  })
+
+  await engine.drainEffects({instanceId: event.data._id as string})
+})
+```
+
+Each function directory needs its own `package.json` depending on
+`@sanity/functions`, `@sanity/client`, and `@sanity/workflow-engine`.
+
+`sanity.blueprint.ts` at the project root declares both, plus the robot
+token they run under:
+
+```ts
+import {
+  defineBlueprint,
+  defineDocumentFunction,
+  defineRobotToken,
+  defineScheduledFunction,
+} from '@sanity/blueprints'
+
+const projectId = process.env.SANITY_PROJECT_ID ?? ''
+const dataset = process.env.SANITY_DATASET ?? 'production'
+
+export default defineBlueprint({
+  resources: [
+    defineRobotToken({
+      name: 'wf-robot',
+      label: 'Workflow runtime',
+      memberships: [{resourceType: 'project', resourceId: projectId, roleNames: ['editor']}],
+    }),
+    defineDocumentFunction({
+      name: 'drain-effects',
+      src: './functions/drain-effects',
+      event: {
+        on: ['create', 'update'],
+        filter: "_type == 'sanity.workflow.instance' && count(pendingEffects[!defined(claim)]) > 0",
+        projection: '{_id}',
+        resource: {type: 'dataset', id: `${projectId}.${dataset}`},
+      },
+    }),
+    defineScheduledFunction({
+      name: 'heartbeat',
+      src: './functions/heartbeat',
+      event: {expression: '* * * * *'}, // every minute; loosen to taste
+      robotToken: '$.resources.wf-robot.token',
+    }),
+  ],
+})
+```
+
+```sh
+npx sanity blueprints deploy
+```
+
+Note: scheduled functions currently require an **organization-scoped**
+stack — see Sanity's Functions documentation for stack setup. Concurrent
+runtimes are safe: ticks are idempotent, pending effects carry claims, and
+`missingHandler: 'skip'` keeps runtimes out of each other's effects.
+
+## Limitations
+
+- **Advisory enforcement.** The plugin's gates and locks are UI; only
+  lake-side rules actually block writes.
+- **Studio actions run on the editor's token** — including workflow
+  bookkeeping. The runtime's robot token covers the unattended paths.
+- **Failed effects settle as failed** (workflows proceed rather than
+  strand) and can't be retried from the Studio — run consequential effects
+  in the runtime, not the browser.