@sanity/workflow-studio-plugin 0.32.0 → 0.33.0

package/CHANGELOG.md

@@ -1,5 +1,158 @@
 # @sanity/workflow-studio-plugin
 
+## 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,26 @@ 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`, `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 +138,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 +404,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.