@sanity/workflow-studio-plugin 0.32.0 → 0.34.0

package/CHANGELOG.md

@@ -1,5 +1,175 @@
 # @sanity/workflow-studio-plugin
 
+## 0.34.0
+
+### Minor Changes
+
+- 30a515c: **BREAKING:** Workflows Studio packages now target the Sanity UI 4 API. The Studio plugin, shared components, and diagram package each install `@sanity/ui ^4.2.1` for the UI they render; React, styled-components, and Studio remain peer contracts. This does not prevent Studio from hosting unrelated Sanity UI 3 plugins. Upgrade Sanity Studio to 6.15 or later and upgrade every `@sanity/workflow-*` package in the installation to the same release, then reinstall dependencies and commit the updated lockfile. Partial Workflows upgrades can pair packages built for different Sanity UI APIs and fail the Studio build.
+
+  Docs impact: Update the Studio plugin installation prerequisites and release guidance to require Sanity Studio 6.15 or later and a lockstep Workflows package upgrade.
+
+### Patch Changes
+
+- Updated dependencies [30a515c]
+  - @sanity/workflow-components@0.34.0
+  - @sanity/workflow-diagram@0.34.0
+  - @sanity/workflow-studio@0.34.0
+  - @sanity/workflow-engine@0.34.0
+  - @sanity/workflow-react@0.34.0
+
+## 0.33.0
+
+### Minor Changes
+
+- 225e0fb: **BREAKING:** Workflows App SDK and Studio integrations now require `@sanity/sdk` 3.1 or later in the 3.x line, and `@sanity/workflow-sdk` requires the matching `@sanity/sdk-react` 3.1 line when its React entry is used. The previous SDK 2 peer contract is no longer supported. The exported `WorkflowClient`, `TelemetryIntakeClient`, `ProjectUserProfileClient`, and `StudioUserClient` request contracts now pass their target in `url`; the previous `uri` request target is no longer used. The engine's effective client config also accepts the broader `{type: string, id: string}` resource descriptors returned by Sanity client 8.
+
+  Before upgrading Workflows, upgrade `@sanity/sdk` and `@sanity/sdk-react` together to 3.1 or later. Applications that stay on SDK 2 must stay on an earlier Workflows release. If you implement any of the request contracts named above, update it to read the request target from `url` instead of `uri`; otherwise its request-backed reads will fail. Existing `WorkflowClient.config()` implementations need no change when their resource descriptor already has string `type` and `id` fields. No separate CLI upgrade action is required; its definition-sharing and telemetry requests adopt `url` internally.
+
+  Before installing, override SDK 3's `@sanity/mutate` dependency to `0.18.2` in your application's root package-manager configuration, reinstall, and commit the updated lockfile. SDK 3.1.0 allows Mutate 0.18.1, which can leave document reads pending with client 8. For npm, set `overrides["@sanity/sdk"]["@sanity/mutate"]` to `"0.18.2"` in `package.json`. For pnpm, set `overrides['@sanity/sdk@3>@sanity/mutate']` to `0.18.2` in `pnpm-workspace.yaml`. Keep the override until your SDK release requires Mutate 0.18.2 or later. Complete examples and verification steps are in the Installation section of the published `@sanity/workflow-sdk` README.
+
+  Malformed project-member responses now report an inaccessible directory and can recover on a later lookup, instead of being cached as a missing user. No additional upgrade action is required for this correction.
+
+  **Docs impact:** Update the App SDK and Studio integration installation guidance, package compatibility references, and examples to require Sanity App SDK 3.1 and the consumer Mutate override described in the published `@sanity/workflow-sdk` README; update the client API references for `request({url})`, effective resource descriptors, and directory-response failures.
+
+- 8326bbf: Contributors can now develop and inspect the Studio plugin's isolated workflow chrome in a local Storybook, including light and dark themes and representative loading, empty, error, disabled, workflow-status, deadline, and board states.
+
+  **No upgrade action required.** The workshop adds development tooling without changing the package API or published runtime files.
+
+  **Docs impact:** None. Storybook is contributor tooling documented in the repository README, not in the published package README.
+
+- 7c46aca: Integrations outside Studio can import `AgoStamp`, `ActivityStatusIcon`, and
+  `StartIncompleteBadge` from `@sanity/workflow-components`. These workflow atoms
+  use the same implementation as the Studio plugin and accept domain values
+  without requiring Studio data providers.
+
+  Studio integrations can import `RunsTable` and `ForMeTable` from
+  `@sanity/workflow-studio-plugin`, with `runRowsOf`, `forMeTaskRowsOf`, and their
+  supporting types. These tables retain the Workflows tool's document previews,
+  member faces, task hints, and virtualized layout. Hosts supply sorted rows and
+  selection callbacks, render inside a Studio configured with `workflowStudioPlugin`, and provide a
+  height-constrained container with vertical scrolling. Table columns also recover
+  when a hidden container becomes visible and continue tracking width changes.
+
+  **No upgrade action required.** Existing plugin surfaces retain their table
+  presentation. Upgrade the Workflows packages together before adopting the new
+  exports.
+
+  **Docs impact:** Update the shared-components API reference for the status,
+  timestamp, and start badge atoms, and the Studio plugin reference and custom-tool
+  examples for table exports, row builders, providers, and controlled interaction.
+
+- 6fba6b3: The Workflows tool now marks needs-attention runs at the grain the reader can
+  act on. In the Overview table and on board cards, each late task carries an
+  amber dot on its own token, so a stage holding several tasks shows which of
+  them are overdue rather than only that the run is. The lateness readout beside
+  the tokens shows a span (`4d`) only when every late task shares it, and the
+  bare word `overdue` when they differ — a single span standing for tasks late by
+  different amounts read as each task's when it was only the oldest one's.
+
+  The blocked mark moves to the thing it blocks. In the Overview table it sits
+  beside the stage name, since a failed activity stops that stage from advancing;
+  on a board card it sits in the top right corner. The Overview's separate
+  trailing attention column is gone, and its width is split between the widened
+  Tasks column and the workflow subject beside it. The For me table keeps its own
+  attention column, where a row is a task rather than a run.
+
+  No upgrade action required — this is presentation only, with no API or
+  persisted-shape change. Consumers rendering the tool see the new marks after
+  upgrading.
+
+  **Docs impact:** Update the Workflows tool guide's Overview and board
+  descriptions to cover the per-task overdue dot, the shared-span rule for the
+  lateness readout, and the blocked mark's placement beside the stage name and in
+  a card's corner. No concept or reference page changes.
+
+### Patch Changes
+
+- 8874c50: **BREAKING:** A `subject`, `doc.ref`, or `doc.refs` field marked `required: true`
+  now requires its selected documents to remain readable after initialization.
+  Previously, the flag checked only that an initial value was supplied. Missing
+  required targets now produce a fault and prevent normal actions, triggered
+  actions, and transitions from advancing, even without an activity requirement
+  reading those targets. Abort and direct edits to editable fields remain
+  available. Optional references fault only when an unmet runtime condition needs
+  their content; completed workflows remain completed.
+
+  `StuckCause` adds `document-missing`. Update exhaustive handlers before upgrading,
+  or their typechecks fail and renderers have no matching branch. Evaluation
+  identifies the affected field and reference in `missingDocuments`, with its title
+  and completed availability evidence; `blockingMissingDocuments` selects the
+  references that prevent progress. The engine checks draft, published, and release
+  representations before distinguishing deletion from inaccessible content or
+  content outside the workflow perspective. Studio, CLI, and MCP use that same
+  result. Failed availability checks report unreadable content and log the cause;
+  optional references still permit unrelated actions. Incomplete reads do not
+  claim deletion, and an existing task fault keeps
+  its recovery controls. The fault clears when the required content becomes
+  readable; this release adds no undo-delete operation and does not automatically
+  abort workflows.
+
+  Upgrade every Workflows runtime sharing affected data, including Studio, CLI,
+  MCP servers, and deployed Functions, before relying on continued required-target
+  availability. Then set the deployment's reviewed `expectedMinReaderModel` to
+  `10` before deploying definitions with required content references. Writers stamp
+  model 10; this feature requires reader model 10, while documents without it keep
+  the floor required by their other features, normally 4, 8, or 9. Existing
+  instances remain readable without a backfill and adopt the rule under upgraded
+  engines. Their stored floor rises on the next full write, so an older runtime
+  can still advance an unstamped existing instance until the fleet is upgraded.
+  See `packages/workflow-engine/DATAMODEL.md` for the complete rollout contract.
+
+  The rendered CLI `show` command evaluates running instances. If evaluation fails,
+  it warns and displays stored state; terminal instances and `show --json` retain
+  their stored-state behavior.
+
+  **Docs impact:** Update field requiredness and initialization guidance, required
+  reference repair examples, the model-10 readers-first rollout, the diagnostics
+  reference for `StuckCause` and `MissingDocument`, CLI `show` and `diagnose`, MCP
+  workflow-state guidance, and the Workflows tool and document-view guides for
+  loading, deletion, permissions, and perspectives.
+
+- 7eb9eca: Correct the API references for field initialization and edits, start requirements,
+  transitions, reference IDs, effect handling, reactive state, member controls,
+  Studio mappings, test helpers, and GROQ condition outcomes. The references state
+  caller constraints and defaults that were missing or incorrect. Package setup
+  guidance identifies the public npm packages and supported deployment command;
+  the MCP validation description distinguishes validation from deployment checks.
+  Runtime behavior and API signatures are unchanged.
+
+  **No upgrade action required.**
+
+  **Docs impact:** After release and reference sync, reconcile the modeling,
+  runtime, reactive UI, Studio, testing, deployment, MCP, and evaluation-insight
+  guides and references with the corrected contracts. Fix affected examples and
+  replace redundant API inventories with verified symbol links while preserving
+  useful teaching and the CLI/MCP reference material not exposed by TypeDoc.
+
+- 2cef086: Internal maintenance consolidates engine action/edit handling and Studio document
+  and workflow title sorting. Action and field-edit calls retain their inputs and
+  results, and document and workflow titles retain their ordering. Action
+  availability, telemetry, and persisted document formats are unchanged.
+
+  **No upgrade action required.**
+
+  **Docs impact: None** because public APIs, configuration, and workflow behavior
+  are unchanged.
+
+- Updated dependencies [3f7c2fd]
+- Updated dependencies [393ac71]
+- Updated dependencies [8874c50]
+- Updated dependencies [0555271]
+- Updated dependencies [b3b2797]
+- Updated dependencies [225e0fb]
+- Updated dependencies [7c46aca]
+- Updated dependencies [7eb9eca]
+- Updated dependencies [2cef086]
+- Updated dependencies [232f811]
+  - @sanity/workflow-components@0.33.0
+  - @sanity/workflow-engine@0.33.0
+  - @sanity/workflow-studio@0.33.0
+  - @sanity/workflow-diagram@0.33.0
+  - @sanity/workflow-react@0.33.0
+
 ## 0.32.0
 
 ### Minor Changes

package/README.md

@@ -1,8 +1,7 @@
 # @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.
+> This package is published on npm. Every `@sanity/workflow-*` package is
+> pre-1.0; APIs may change.
 
 Workflows inside Sanity Studio. You describe a workflow in code —
 stages like _Drafting → Review → Approved_, and the actions that move work
@@ -41,11 +40,27 @@ treat plugin-side checks as a security boundary.
 
 ## 1. Install
 
+Use one matching version for every `@sanity/workflow-*` package in the
+command below. The plugin also requires `sanity ^6.15`, which provides
+`@sanity/ui ^4.2.1`, plus `react ^19`, `styled-components ^6`, and
+`@sanity/sdk ^3.1`.
+
+Before installing, select Mutate 0.18.2 for SDK 3 in your application's root
+configuration. For npm, set `overrides["@sanity/sdk"]["@sanity/mutate"]` to
+`"0.18.2"` in `package.json`. For pnpm, set
+`overrides['@sanity/sdk@3>@sanity/mutate']` to `0.18.2` in
+`pnpm-workspace.yaml`. Without this override, an existing lockfile can
+retain Mutate 0.18.1 and leave document reads pending.
+
 ```sh
 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
 ```
 
-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).
+Commit the configuration and updated lockfile. Run
+`npm ls @sanity/sdk @sanity/mutate` or `pnpm why @sanity/mutate` and verify SDK 3 resolves Mutate
+0.18.2. Keep the override until your SDK release requires Mutate 0.18.2 or
+later. The [SDK package's installation guide](https://www.npmjs.com/package/@sanity/workflow-sdk#installation)
+includes complete configuration examples.
 
 ## 2. Define a workflow
 
@@ -124,7 +139,7 @@ export default defineWorkflowConfig({
 ```
 
 ```sh
-npx sanity-workflows deploy --tag production   # add --dry-run to preview
+npx @sanity/workflow-cli deploy --tag production   # add --dry-run to preview
 ```
 
 Auth comes from your `sanity login` session (or a `SANITY_AUTH_TOKEN` env
@@ -390,3 +405,34 @@ see the cookbook recipe
 - **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.
+
+## Embed instance tables in a custom Studio tool
+
+The package exports `RunsTable` (Overview) and `ForMeTable` (assigned tasks),
+plus their prop and row types. They provide the same document previews, member
+faces, deadline formatting, and attention hints as the Workflows tool. Render
+them inside a Studio configured with `workflowStudioPlugin` and a height-constrained container with
+`overflowY: 'auto'`.
+
+Use `runRowsOf({previews, definitions, now})` to derive instance rows from the
+instance-preview read and a map of deployed definitions. Supply the complete
+preview result, including settled parent instances, so child runs retain their
+root document attribution. `forMeTaskRowsOf({rows, who})` derives assigned tasks;
+`who` uses the account-global user ID and resolved role names from
+`AssignmentIdentity`.
+
+The host owns data loading, filtering, ordering, and selection. Supply rows in
+the displayed order and update them in response to `onSort`. `onSelectRun`
+receives the original `RunRow`, and `onSelect` receives the original
+`ForMeTaskRow`. `selectedId`, `selectedRef`, and `onNavigateKey` let the host
+control focus, arrow-key navigation, and scrolling. Reset the scrolling
+container when changing scope or sort order. Update `now` to refresh timestamps.
+
+These exports are tables, without the Workflows tool's filters, URL state,
+loading indicators, empty states, or detail panels. Compose those around them as
+needed. `RunSort`, `ForMeSort`, their column-key types, `RunsScope`, and
+`RunNavigationKeyEvent` describe the controlled table state and callbacks.
+
+For integrations outside Studio, `@sanity/workflow-components` exports workflow
+status, timestamp, badge, assignee, and date controls. Compose those atoms in
+your integration’s own views.