@sanity/workflow-studio-plugin 0.4.0 → 0.20.0

package/CHANGELOG.md

@@ -1,5 +1,166 @@
 # @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
+
+- 767497c: Document reference previews render as hoverable card links: the preview card IS the edit-intent link, with hover/focus affordances instead of a static-text face. Compact row lockups (the tool's group bands) compose the chip from schema icon + live title on the row's own text metric — Studio's portable-text inline preview misaligns outside a text run — so chips center exactly with the badges and buttons beside them. The tool's document group bands step up one radius, give the collapse toggle a larger hit area, and vertically center every band item.
+- 0143226: The document form strip now shows every workflow run instead of hiding finished ones and collapsing concurrent actives. Each active instance renders its own line (definition title, current stage, its own assigned-task count — the "N active workflows" aggregate line is gone), and each workflow type whose runs have all settled keeps one line showing its latest run's terminal state (an Aborted chip for a run that never completed), with the settle time on hover; a type running again is represented by its active line instead. Clicking any line opens the Workflows view focused on that run — only its section unfurled, via a sticky pane param that survives reloads.
+- 767497c: Tool instance bands render the form strip's instance lockup — title, then the stage face with its glyph in the primary tone — and the lockup is a real link to the instance's detail view: plain clicks navigate in place (carrying the selected tab), modified clicks open the resolved route in a new tab.
+- 24b11dd: Surface the `progress` field kind: a progress field's pill wears its value as a tweened background fill with a whole-number percent caption in a reserved-width slot (at-a-glance progress that never resizes as it ticks), the tweened `ProgressBar` (from `@sanity/workflow-components`) renders on every field-value display surface — pill popovers, field rows, the activity dialog — and edits go through native 0–100 number inputs honoring declared validation bounds; the MCP authoring guide documents the kind.
+- 767497c: The Workflows tool drops its All workflows tab: the tool is Overview and For me. The instance-level filter arms that only backed that listing are gone with it.
+- 2005ab7: Terminal-action placement keys on what firing concludes: an action whose fire would exit the stage right now (the engine's `firing` consequence) joins the own-status settling actions in the dialog footer and the row's terminal cluster — no longer a quiet top-strip button. The activity detail dialog's footer also drops its Cancel button (field edits commit on their own gestures, so there was nothing to cancel — dismissal is the header X, Esc, or the overlay) and renders only when terminal actions exist.
+- 47fd2b5: Terminal actions fold into menus instead of the primary-plus-chevron split button. An activity list row with two or more actions offers one "Select action" menu listing them all; a lone action stays a plain ghost button. The activity dialog footer lays actions out inline — capped at three, and only as many as the measured footer width fits without wrapping, refitting as the dialog resizes — with the surplus behind a "More actions" menu.
+- 767497c: Workflows tool layout: the title, tabs, and the active tab's filter row are a fixed header — only the task list scrolls, with a stable scrollbar gutter so the scrollbar appearing doesn't reflow rows. Task rows indent under their instance band (the document view's stage inset) and share the bands' border radius. Header padding is uniform, with the tool title optically aligned to the tab labels; the tabs' loading rows share the same optical indent. The plugin now declares `react-dom` as a peer dependency (the header slot renders through a portal).
+- 767497c: Workflows tool: one tab strip — Overview (all tasks, default) and For me (the user's assignments) — replacing the Tasks/All workflows tabs and the nested My tasks/All tasks toggle. The selected tab now rides the tool's URL search params with the same contract as the document view's tab (default elided, unknown values read as the default), so reloads, bookmarks, and detail-view round-trips keep the tab. The "New workflow" button drops its primary tone and tightens its icon-to-label gap.
+- 767497c: Workflows tool: task rows are now the document view's shared activity row — same geometry and the same inline controls: the assignee picker and a new date chip. The Overview groups one dimension per level — a band per document, lighter collapsible bands per workflow instance under it (the title + current-stage lockup, a link to the instance's detail view; every band's affordance acts on exactly the entity it names), and the instance's activity rows below. Instances without a Studio document band bare in a trailing section. The For me segment reads the same hierarchy cut to the user's assignments, its rows carrying the inline terminal-action cluster (everything listed is yours to act on — Overview rows stay action-free); the document pane's For me tab keeps its flat list. Rendered rows pull their instances into the provider's live evaluation to drive the controls; rows hold the committed facts in the same shell until it lands.
+
+  The inline assign and date controls are state-driven so identical-looking triggers never behave differently across rows: a declared-editable field with anything to show always renders its trigger — the popover shows a loading state until the live evaluation lands, and the picker while the field is editable for the actor; once editing is closed (a settled activity, a denying predicate) the trigger swallows the click and explains itself in the hover hint instead of falling through to the row's dialog. Values whose field is never declared editable render as plain content, without button chrome. The activity row gains an optional date-control slot for surfaces that show dates on rows.
+
+- 767497c: An unreadable workflow document no longer blanks the Workflows tool: the task list renders every readable row and flags the refused ones in a compact caution note with a Copy details button producing a paste-ready report (id, reason, and the validation detail naming the offending fields). Document surfaces keep the conservative wholesale notice: an unreadable row can't be attributed to a document, so discovery still fails loud there.
+
+### Patch Changes
+
+- 767497c: Tool bands drop their overflow menus — the document chip and the instance lockup are the inline affordances now, each carrying a tooltip ("Open document" / "View workflow") — and instance bands trail a centered hairline rule filling the rest of the band.
+- 767497c: The document view's workflow instance accordion wears the tool's band shell: a discrete chevron toggle, the title lockup, and the trailing hairline, with the instance menu kept at the band's end. One shared CollapsibleBand component now backs both surfaces, so their geometry can't drift.
+- 767497c: Overflow menus render the standard surface wherever they open — the popover no longer inherits a toned host card's background (a group band's transparent tone painted the menu grey). Menus anchor to the trigger's end edge, flipping above only when there's no room below.
+- 767497c: The inline "Document unavailable" face aligns with linked document chips: same padded box, the warning icon in its own text cell, and the chip's gap before the label.
+- 0143226: The Workflows view's instance section header spinner renders at the header lockup's own text scale (size 1) instead of the default size.
+- 767497c: The tool's task rows stay mounted across the committed-facts → live-evaluation transition: one row component renders either source, so a loading popover opened before the instance's evaluation lands resolves in place into the picker instead of closing. The shared activity row now takes a normalized face (title, status, tags) rather than a raw activity evaluation, so any surface can render it from committed facts.
+- 2005ab7: A terminal-action cluster (a row's lone button or "Select action" menu, the dialog footer's inline buttons plus "More actions" menu) shares one in-flight fire lock: while any member fires, the firing button shows loading, the menu trigger and every item disable, and sibling fires drop before reaching the session. Firing from a menu no longer leaves the cluster looking idle (a menu item unmounts when its menu closes, so its own pending state — and its double-fire guard — died with it).
+- 767497c: Per-instance session updates no longer re-render every workflow surface: the provider's live entries move out of the context value into a subscribable store, consumers subscribe per key with identity-stable snapshots, and report bursts coalesce into one trailing flush per fixed window (never extended, so a steady stream of reports still flushes on cadence). Opening the Workflows tool over dozens of instances now settles in seconds instead of tens of seconds of main-thread churn.
+- Updated dependencies [24b11dd]
+- Updated dependencies [2005ab7]
+- Updated dependencies [767497c]
+- Updated dependencies [24b11dd]
+- Updated dependencies [24b11dd]
+- Updated dependencies [59b40fd]
+  - @sanity/workflow-engine@0.19.0
+  - @sanity/workflow-react@0.14.0
+  - @sanity/workflow-studio@0.10.0
+  - @sanity/workflow-components@0.2.0
+  - @sanity/workflow-diagram@0.4.1
+
 ## 0.4.0
 
 ### Minor Changes

package/README.md

@@ -11,8 +11,8 @@ 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 to-dos,
 where they fire actions and read the history, and a **Workflows tool** in the
-Studio navbar — a tasks view, a dashboard of the newest workflow instances,
-and a deep-linkable per-workflow detail view.
+Studio navbar — the open tasks across the newest workflow instances (capped),
+the user's own cut of them, and a deep-linkable per-workflow detail view.
 
 Four ideas cover everything in this guide:
 
@@ -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