@sanity/workflow-studio-plugin 0.5.0 → 0.20.0

package/CHANGELOG.md

@@ -1,5 +1,125 @@
 # @sanity/workflow-studio-plugin
 
+## 0.20.0
+
+### Minor Changes
+
+- 419cd5e: Action buttons and action-menu items take their face from declared decision semantics: `decision.accept` renders positive with a checkmark icon, `decision.decline` renders caution with a cross icon, in the quiet top-row, the concluding footer, and the "Select action" menu treatments alike — the icon doubles the tone as a non-color channel. A declared `failed` status keeps its bare critical face and outranks the semantics; actions without semantics render as before.
+- e3122cc: The document view's boot indicators consolidate: section headers no longer spin while sessions boot — the Active Workflows heading carries one spinner for the group (held back 400ms so warm boots paint nothing), since a document's sections boot together over shared discovery and one consolidated guard query. A section speaks up individually only when it diverges: its invalid notice, or its stage body's loading row — now shaped as a work row (spinner in the status glyph's slot) so a one-activity stage swaps loading for content with zero layout shift.
+- 46b0285: **BREAKING:** Replace manually declared document applicability with automatic
+  discovery from deployed first-class subject fields.
+
+  Update Studio configuration as follows:
+  - `mappings` is optional. Omit it when every applicable definition declares a
+    first-class subject. A mapping may customize an automatically discovered
+    `(docType, definition)` binding or explicitly register a definition modeled
+    with a plain `doc.ref` instead of a first-class subject.
+  - Multiple workflows may target one document type. Use one mapping row for each
+    distinct `(docType, definition)` pair. An exact duplicate pair is a
+    configuration error rather than a last-row-wins override.
+  - Remove the top-level `autoStart` map or function. Put `autoStart: true` on
+    each mapping row that should start automatically. Configure workspace-specific
+    behavior in that workspace's mapping rows. This also works for explicitly
+    registered definitions using the `doc.ref` field named `subject` convention.
+  - Replace `workflowDefaultDocumentNode({mappings})` with
+    `workflowDefaultDocumentNode()`.
+
+  Before:
+
+  ```ts
+  structureTool({defaultDocumentNode: workflowDefaultDocumentNode({mappings})})
+  workflowStudioPlugin({
+    tag: 'production',
+    mappings,
+    autoStart: {article: ['article-review', 'legal-review']},
+  })
+  ```
+
+  After:
+
+  ```ts
+  structureTool({defaultDocumentNode: workflowDefaultDocumentNode()})
+  workflowStudioPlugin({
+    tag: 'production',
+    mappings: [
+      {
+        docType: 'article',
+        definition: 'article-review',
+        label: 'Article review',
+        autoStart: true,
+      },
+      {
+        docType: 'article',
+        definition: 'legal-review',
+        label: 'Legal review',
+        autoStart: true,
+      },
+    ],
+  })
+  ```
+
+  Also remove all per-schema Editorial Workflows preview wiring:
+  - Remove `components: {preview: WorkflowStagePreview}`.
+  - Remove `_id` added only for Editorial Workflows from `preview.select` and
+    stop passing it through `preview.prepare`.
+  - Remove imports of `WorkflowStagePreview`; that component is no longer a
+    public package export.
+  - Remove imports of `mappingForDocType` and `workflowDocTypes`; effective
+    mappings are resolved inside the plugin and those host-side helpers are no
+    longer exported.
+  - Keep each schema's native inferred or custom preview unchanged. The plugin
+    now installs preview middleware itself, consumes the document identity Studio
+    already supplies, and delegates title, subtitle, media, and custom preview
+    composition through `renderDefault`.
+
+  Workflow stage pills appear on Studio surfaces that invoke preview middleware,
+  including reference and array-item previews. Custom preview components that
+  replace Studio's layout must render the `status` prop they receive. Studio's
+  Structure document-list rows bypass both plugin and schema preview middleware,
+  so they do not show workflow stage pills. Workflow status remains available in
+  the document form, footer badge, Workflows view, and Workflows tool.
+
+  Document-reference GDRs for dataset content now reject stored draft IDs
+  (`drafts.<id>`) and Content Release version IDs
+  (`versions.<release>.<id>`). Use the stable document ID in the GDR and select
+  the draft or release through workflow perspective instead. The validation error
+  includes the corresponding stable ID so CLI and API callers can correct the
+  input before an unresolvable workflow instance is created.
+
+  Previously persisted draft/version GDRs remain invalid workflow identities.
+  Read-side Studio displays now tolerate them by showing the raw URI instead of
+  crashing, and query-sourced occurrences are discarded through the existing
+  fail-soft field-resolution path. Correct existing data by starting a new
+  instance with the stable document ID; perspective selects the desired draft or
+  release content.
+
+- 98e488e: Stabilize Editorial Workflows discovery subscriptions and limit full reactive sessions to surfaces that need live evaluation.
+- e3122cc: Settled workflow runs no longer boot reactive sessions. The provider mounts an evaluator only for in-flight discovered instances (plus any instance explicitly pulled in through the refcounted request seam, settled or not); settled entries render from committed documents and are vacuously `ready`, so the accordion header no longer spins for finished sections. The mounted sessions share one consolidated guard live query per resource (the plan's `guardScope`), so opening a document costs one discovery subscription plus guard machinery that doesn't grow with its active-run count.
+- e860898: **BREAKING:** Published Editorial Workflows packages now ship as one fixed release stack and require exact-version peers for every shared runtime package. Install the matching stack so the engine, reactive core, adapters, tools, and UI cannot silently load private or version-skewed copies.
+
+### Patch Changes
+
+- 8a76c67: Add incremental reactive-session document feeds, coalesce watched-document emissions, and reuse discovery derivations and Studio layout output. Deleted watched documents now leave the held snapshot instead of remaining as stale evaluation input. The component test runner also has aggregate-suite timeout headroom.
+- ab5e454: Share projected project members and use indexed, memoized assignee display lookups.
+- Updated dependencies [bce09fc]
+- Updated dependencies [efb4cd9]
+- Updated dependencies [ab5e454]
+- Updated dependencies [46b0285]
+- Updated dependencies [ab5e454]
+- Updated dependencies [8a76c67]
+- Updated dependencies [e3122cc]
+- Updated dependencies [e3122cc]
+- Updated dependencies [7e8f459]
+- Updated dependencies [98e488e]
+- Updated dependencies [7c4dd86]
+- Updated dependencies [e860898]
+- Updated dependencies [e3122cc]
+  - @sanity/workflow-engine@0.20.0
+  - @sanity/workflow-studio@0.20.0
+  - @sanity/workflow-react@0.20.0
+  - @sanity/workflow-components@0.20.0
+  - @sanity/workflow-diagram@0.20.0
+
 ## 0.5.0
 
 ### Minor Changes

package/README.md

@@ -33,11 +33,10 @@ treat plugin-side checks as a security boundary.
 ## 1. Install
 
 ```sh
-npm install @sanity/workflow-studio-plugin @sanity/workflow-engine @sanity/workflow-cli
+npm install @sanity/workflow-studio-plugin @sanity/workflow-components @sanity/workflow-diagram @sanity/workflow-engine @sanity/workflow-react @sanity/workflow-sdk @sanity/workflow-studio @sanity/workflow-cli
 ```
 
-Requires a Studio v6 project (`sanity ^6`, `react ^19`,
-`styled-components ^6`, `@sanity/sdk ^2.12` — the usual studio peers).
+Use one matching version for every `@sanity/workflow-*` package in that command; they publish as a fixed runtime stack. The plugin also requires a Studio v6 project (`sanity ^6`, `react ^19`, `styled-components ^6`, `@sanity/sdk ^2.12` — the usual Studio peers).
 
 ## 2. Define a workflow
 
@@ -125,100 +124,76 @@ no-op.
 
 ## 4. Wire the studio
 
-Add to your `sanity.config.ts`, replacing `article` with one of your own
-document types:
+Add to your `sanity.config.ts`:
 
 ```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`
-    label: 'Article review',
-  },
-]
+import {workflowDefaultDocumentNode, workflowStudioPlugin} from '@sanity/workflow-studio-plugin'
 
 export default defineConfig({
   // ...your projectId, dataset, schema...
   plugins: [
     structureTool({
-      // Adds the "Workflows" tab next to the editor for mapped types.
-      defaultDocumentNode: workflowDefaultDocumentNode({mappings: workflowMappings}),
+      // Adds the "Workflows" tab next to document editors.
+      defaultDocumentNode: workflowDefaultDocumentNode(),
     }),
     workflowStudioPlugin({
       tag: 'production', // must match the deploy tag
-      mappings: workflowMappings,
     }),
   ],
 })
 ```
 
-Start the studio and open an `article`: the workflow strip above the form
+The plugin discovers deployed definitions whose caller-provided subject accepts
+a document type in this Studio schema. 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
+Mappings customize discovered subject bindings or explicitly bind definitions
+that use a plain `doc.ref` instead of a first-class subject. Multiple
+definitions for the same `docType` remain separate workflows. A mapping row
+replaces the discovered defaults for its exact `(docType, definition)` pair or
+adds that pair when discovery did not produce it. Duplicate rows for the same
+pair are rejected as configuration errors.
 
-`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:
+### Workflow status in previews
 
-```ts
-import {WorkflowStagePreview} from '@sanity/workflow-studio-plugin'
-import {defineType} from 'sanity'
+Editorial Workflows status does not require `components.preview`, a projected
+`_id`, or changes to `preview.select` / `preview.prepare`. Studio already
+supplies document identity to preview middleware, and the plugin uses it while delegating
+the document's title, subtitle, media, and custom preview component unchanged.
 
-export const article = defineType({
-  name: 'article',
-  type: 'document',
-  fields: [
-    /* ... */
-  ],
-  preview: {
-    select: {_id: '_id', title: 'title'},
-    prepare: ({_id, title}) => ({_id, title}),
-  },
-  components: {preview: WorkflowStagePreview},
-})
-```
+The status pill appears on Studio surfaces that invoke preview middleware,
+including reference and array-item previews. A custom preview component must
+render the `status` prop it receives if it replaces Studio's default layout.
+
+Studio's Structure document-list rows bypass plugin preview middleware, so
+those rows do not render workflow stage status. Their native previews remain
+unchanged; workflow status is available in
+the document form, footer badge, and Workflows tab.
 
 ### Auto-start a workflow on new documents
 
-`autoStart` starts a workflow the moment an editor opens a **fresh** document
+`autoStart` on a mapping override starts a workflow the moment an editor opens a **fresh** document
 of a given type — the document is born with its workflow instead of relying on
-someone to press "Start". It's a map of document `_type` to the deployed
-definition name(s) to start:
+someone to press "Start". Add one override row for each definition that should
+start automatically:
 
 ```ts
 workflowStudioPlugin({
   tag: 'production',
   mappings: [
-    /* ... */
+    {docType: 'article', definition: 'article-review', label: 'Article review', autoStart: true},
+    {docType: 'campaign', definition: 'legal-review', label: 'Legal review', autoStart: true},
+    {docType: 'campaign', definition: 'brand-review', label: 'Brand review', autoStart: true},
   ],
-  autoStart: {
-    article: 'article-review', // one workflow
-    campaign: ['legal-review', 'brand-review'], // several, started together
-  },
 })
 ```
 
-Pass a function instead of a map to vary it by workspace (its name, or the
-schema):
-
-```ts
-autoStart: ({workspaceName}) => (workspaceName === 'editorial' ? {article: 'article-review'} : {})
-```
-
 How it behaves:
 
 - **Fresh only.** Studio doesn't persist a new document until its first edit,
@@ -246,9 +221,8 @@ How it behaves:
   type, undeployed or spawn-only workflow, a subject that doesn't accept the
   type) is dropped with a `console.warn`, never a crash.
 
-Naming a workflow here doesn't require a `mappings` entry — the inputs come
-from the deployed definition itself — but pairing the two is common, so the
-same document also carries the workflow strip and views.
+Each auto-start workflow needs a mapping override with `autoStart: true`; its
+inputs still come from the deployed definition.
 
 Plugin options, for later: `workflowDataset` (keep workflow state in a
 separate dataset), `effectHandlers` (run effect side-effects in the browser