@sanity/workflow-studio-plugin 0.22.0 → 0.24.0

package/CHANGELOG.md

@@ -1,5 +1,176 @@
 # @sanity/workflow-studio-plugin
 
+## 0.24.0
+
+### Minor Changes
+
+- d029896: Definition detail: the Deployed row shows the full deploy timestamp with its relative age ("23 Jul 2026, 14:05 (9 days ago)") instead of the date plus the deploy tag, a new Active instances row joins the live in-flight count (with the capped-read disclosure), the spawn-only trigger phrase reads "Started by a parent workflow", the stage diagram sits in a labeled Stages row aligned with the facts above and filling the rest of the page, and the facts sit a step further below the title.
+
+  Hard-loading the page shows one loading row in the title slot instead of two spinners, and the header lands fully resolved in a single pass — no name-then-title swap.
+
+- ab56ae3: Add a Documents board to the Workflows tool: pick a deployed workflow and see its documents grouped by stage, as horizontal columns or a stacked list. The tool's tab strip becomes Definitions, Documents, Tasks, For me, and the board's workflow is a path segment (`…/workflows/documents/<name>`) so a board survives a reload and travels in a shared link; a bare `…/workflows/documents` resolves to the first workflow by display title and writes that back. The layout choice persists per engine resource.
+
+  A card is one RUN, faced by the document that run is about, so a document carrying five runs of the workflow draws five cards — each in the stage its own run sits at. Completed runs park in the stage they finished in; aborted runs are left off. A run whose lead document ref doesn't resolve is faced by its own workflow title instead, which covers both a workflow with no subject entry and a stray unset subject, so no run is dropped. A stage the deployed definition no longer declares holds a trailing column rather than dropping the runs still sitting in it.
+
+  A card carries the document and nothing else. Assignees are properties of activities rather than of a run or a document, so they stay on the activity rows in the Tasks list and in the activity dialog. The board reads its runs filtered by definition lake-side rather than sharing the tool's newest-instances cap, so a busy neighbouring workflow can't crowd a quieter one's runs off the board; the board carries its own cap of the latest 200 runs, disclosed on the board when it bounds the read.
+
+  A **View definition** link sits beside the board's workflow picker, opening that workflow's definition detail view — a real link, so it opens in a new tab like any other.
+
+  Two new UI telemetry events — Board Workflow Selected (carrying the definition content fingerprint and whether the URL named the workflow or the board landed on its default) and Board Layout Changed.
+
+  Three changes to shared components, two of which reach surfaces outside the board:
+  - Document reference previews render through one shell that decides border, radius, tone and inset per layout, so the resolved, pending, missing, foreign and unopenable faces can no longer drift apart. A reference whose probe is still in flight shows a placeholder preview rather than a raw document id.
+  - A document reference now states the width it claims: one sitting among other things in a row keeps its compact chip size, while one that IS a list row fills the row and takes the work rows' hit area. The board's stacked layout is the one surface using the new row width; every other document reference keeps the size it had.
+  - The form strip's hover on a line with no work assigned to the reader reports what the run's current stage actually holds ("3 open tasks, none assigned to you") instead of restating that nothing is theirs. While the stage's read is still outstanding it names the destination instead of claiming a count it doesn't have yet.
+
+- 41a3f02: Add `dueDate` and `dueDatetime` field kinds — elevated aliases of `date` / `datetime` (same stored value and validation) that mark THE due date of a level, so surfaces can identify a deadline by kind instead of guessing which date field means "due". Declarable at workflow, stage, and activity scope; optional (no field becomes required). The kind reserves a level's single due slot, so deploy enforces both halves of that: at most one due-\* (either kind, combined) per scope, and none below scope level — a due-\* nested in an `object`/`array` sub-field or an effect's `outputs` is rejected, naming `date` / `datetime` as the fix, because no deadline reader looks there. A `todoList` row's `dueDate` column is unaffected; it is a `date` named `dueDate`, not the kind. Choice lists (`options`) work on the due kinds exactly as on `date` / `datetime`. Persisted-model version 5 (additive, reader floor unchanged).
+
+  The Studio plugin edits and renders the new kinds exactly like the base kinds they elevate: the calendar picker in the start dialog, the Overview pills, the inline field editors and the activity row's date control, a locale-formatted face, and the Workflows tool's Date filter. Every date-family branch now routes through one shared kind predicate, so an elevated alias can't drift out of a site.
+
+- 333f1d0: An in-flight workflow can be aborted from the Workflows tool's instance detail view: an **Abort workflow** button sits between the stage card and the history feed, and its confirm names the workflow and requires a reason, which lands on the workflow's history. A settled instance shows no button.
+
+  Abort lives on that one page rather than on every surface that lists an instance. Instances are named on both document-view tabs and both tool task tabs, and a destructive control repeated down a work queue is noise and a misclick risk, so the list surfaces link to the instance instead of carrying the action.
+
+  An abort that commits nothing because the instance reached a terminal state while the confirm was open reports that outcome instead of claiming a successful abort. A rejected abort reports an unconfirmed outcome: the engine commits the instance's abort before draining condemned children and propagating to ancestors, so a rejection never proves that nothing happened.
+
+  Abort visibility is advisory, like every other engine-side check — the Content Lake remains the only enforcement point, and its instance-document `update` grant cannot distinguish an abort from an ordinary transition commit.
+
+- 043f8e0: Mapping validation accepts a row whose definition leaves a required field for the start dialog to collect. A definition declaring a required input entry beyond its subject — a reason, a priority, a release the perspective doesn't supply — is startable: the row's Start control is enabled and the dialog asks for the entry, holding Start until it is filled. Validation rejects a row only for faults a developer must fix: an undeployed definition, a seed that lands nowhere (undeclared name, mismatched kind, non-input source, duplicate, invalid scope), a `types` facet that rejects the mapped document type, and a seeded local reference carrying a document type the Studio schema doesn't declare.
+
+  A rejected row's diagnostic is developer-facing and stays out of editor surfaces. The disabled Start control in the form strip and the Workflows document view reads `Unavailable — this workflow isn't set up correctly for <Document type> documents`, naming the document type as the Studio schema titles it. The diagnostic goes where a developer already is: in the Workflows tool, a definition whose bindings are refused renders its catalog row in caution with a warning icon, and its detail view carries a Setup issue card stating the reason per document type. A configured workflow with nothing deployed under its name owns no catalog row, so the catalog names it directly — `"<name>" is set up to run on <Document type> documents, but no deployed workflow has that name` — including when nothing at all is deployed.
+
+  Mapping diagnostics log as warnings — the verdicts are advisory, and nothing has failed at runtime. Each rejected row gets one line naming the row, which is what its author can act on. Every rejection is a row the host wrote: discovery derives a row only when the definition's subject entry accepts that document type, and that is the condition every remaining verdict leg reads, so a derived row has nothing left to fail.
+
+  Discovery binds workflows only to document types an author declares. Studio's reserved `sanity.` namespace — the built-in asset documents among it — and the engine's own document types are skipped, so a definition whose subject declares no `types` is not offered on file and image uploads. An explicit mapping row still binds one, and a workflow field referencing a system document is unaffected.
+
+- 1cec9c8: `Editorial Workflows Studio Plugin Action Control Used` bumps to payload version 2: `surface` now names the hosting view or dialog (document view, tool instance detail, tool task list, activity dialog — the same vocabulary as the other attributed events), and the physical placement (`dialog-strip`, `inline-row`, `terminal-footer`) moves to its own `placement` field. Downstream consumers reading v1's placement values out of `surface` must switch on the event version.
+
+  Four new UI telemetry events close attribution gaps in the plugin's engagement vocabulary. `Editorial Workflows Studio Plugin Field Control Used` logs every inline field-edit commit (assignee, date, scalar, choice, doc-ref, and notes controls) with the hosting surface (document view, tool instance detail, tool task list, or the activity dialog), the declared field kind, and a success flag — the unsampled, failure-aware companion the engine's sampled field-edited event can't provide; the todo list keeps its own seam and never emits this event. `Editorial Workflows Studio Plugin Todo Edited` completes the todo family's coverage: the list's non-toggle writes — an item added, a per-item assignee or due-date patch — log the gesture kind, surface, and success flag beside the toggles' existing Todo Toggled event. `Editorial Workflows Studio Plugin Document Link Clicked` logs the click-through from a workflow surface (field values, doc-ref chips, the detail title, the activity dialog's subject line) to the referenced document's editor. `Editorial Workflows Studio Plugin Definition Detail Viewed` logs the tool's per-definition detail view once the catalog read resolves, carrying the definition's content fingerprint rather than its customer-authored name.
+
+- 2ecde51: To-do items on a live instance can be removed. A remove button sits on a row when the view owns the list that row belongs to and the row's field is editable — the activity dialog for an activity's own checklist, the to-do field dialog for a workflow- or stage-scoped one. A view offers nothing for rows it merely lists: the assigned-to-me reading has no removal at all, on the same rule that withholds its "Add item", and a view that reaches a row only through a tick action cannot drop it. Removal commits through the same field seam as the other row edits, with no confirmation step, an optimistic repaint, and a toast if the write fails. `TodoEditKind` includes a `remove` gesture, which the todo-edited telemetry event carries for these writes.
+
+  Editing and removing a to-do both refuse a stored list whose ids don't name exactly one row, and say why. Both rewrites identify their row by `_key`, so a duplicated id would otherwise edit or delete every row sharing it, and an id present in no row would write a silent no-op; a list in either state is reported as needing repair instead.
+
+- 599e2e0: Workflows tool navigation reordered: Definitions is now the first tab and the landing view (`…/workflows`), followed by Tasks (the task list, at `…/workflows/tasks`) and For me. The Tasks tab presents every document group and instance band unfurled by default; collapsing remains an explicit, remembered toggle. The stored expand/collapse payload moves to a new version, so toggles saved by earlier plugin versions are discarded.
+- cf0e85f: Stop telling editors a saved change failed. A commit that lands and then fails to
+  run its effects rejected the same promise a broken write rejects, so it reached
+  the editor as a critical `Failed to …` above a description saying the change was
+  committed — inviting them to redo work the engine had already persisted. That
+  case is now a typed rejection of its own: caution, titled so the editor knows
+  their change is safe, and carried under its own toast id so a later retry cannot
+  overwrite the only notice that the write landed.
+
+  A gesture that succeeds now clears its own outstanding toast. Without that, a
+  refusal the editor resolved could sit beside the row that shows the action
+  landed — for the full reason dwell, since a fired action raises no confirmation
+  of its own.
+
+- cf0e85f: Settle Studio plugin toast copy on one grammar and stop toasts stacking. A
+  critical toast's title names what did not land — normally
+  `Failed to <verb phrase>`, replacing three competing constructions
+  (`Saving failed`, `Could not create document`, `Couldn’t resolve effect`), or the
+  outcome itself where that is shorter than restating the description, as a failed
+  orphan re-check now reads `Nothing was cleaned up` with the reason below it.
+
+  Authored text is quoted rather than conjugated: an action label is supplied by
+  whoever wrote the definition, so a title that put it in a verb slot only read
+  correctly for labels that happen to be verbs.
+
+  Contractions in editor-facing copy use a typographic apostrophe throughout;
+  several strings that feed toast descriptions used an ASCII one, so a single
+  toast could mix both.
+
+  Each toast now carries a stable id naming its gesture, so repeating a gesture
+  replaces its previous toast instead of stacking a column of cards, and a
+  refusal the editor then resolves can't sit beside the retry that succeeded.
+
+- cf0e85f: Hold Studio plugin toasts that carry a reason on screen longer. Every toast used
+  the toast provider's default dwell, which is tuned for a glanceable line — so a
+  partial orphan cleanup listing one line per skipped-or-failed workflow was taken
+  away on the same timer as "Details copied to clipboard". A toast that carries a reason to read — a caution or critical one with a
+  description — now dwells for 20 seconds; a glanceable confirmation keeps the
+  default.
+- cf0e85f: Tone Studio plugin toasts off what actually happened. An engine refusal — an
+  action the gate declined, a field outside its edit window, a guard holding the
+  document — now reaches editors as caution rather than critical, so a red toast
+  means a write was attempted and broke. A field-edit refusal also renders the
+  sentence the disabled control would have shown instead of the engine's
+  `Field "scope:field" is not editable` developer string.
+
+  Confirmations move from positive to neutral, and a fired action no longer
+  toasts at all: the row repaints when the commit settles, so a landed fire
+  reports itself. `success` is now unused across the plugin — the Studio hosting it
+  already toasts green for the document operations a workflow triggers.
+
+### Patch Changes
+
+- 097632c: Render a finished workflow's terminal stage in gray rather than the primary blue: the stage label and glyph take the default badge tone, the glyph becomes the filled checkmark that already marks a completed activity, and the stage chip's pill swaps the primary tone and its focus-ring blue for the plain card tone with a ring in that same dark gray. This covers every surface showing a completed stage face — the document form strip's finished lines and the stage band in the Workflows document view and tool — so primary blue marks a run in flight and dark gray one that settled.
+- 599e2e0: Document-type badges on the definitions catalog render on a single line, truncating long titles with an ellipsis instead of wrapping the pill onto two lines and stretching its radius.
+- 599e2e0: The Definitions and Tasks tabs render their empty states as the shared empty-state card (centered icon, headline, explanation) the For me tab already uses, instead of a single status line.
+- 599e2e0: Workflows tool URLs that resolve to nothing now recover instead of dressing up as content. A tab segment naming no tab (for example `…/workflows/foo`) replaces itself with the tool home's URL. The instance and definition detail views share one not-found face — an explanatory note over a back button that returns to the list the detail belongs to (“Back to all tasks” for instances, “Back to all definitions” for definitions), derived from the route's own tab mapping. A definition detail for an unknown name no longer shows a title line.
+- d570436: A project-member directory that has not answered yet reports `loading` instead of reading as a loaded directory with no members. Its fetch starts from a consumer's effect, one commit after the first render, so that first pass previously looked settled-and-empty — enough for the plugin to warn that the logged-in user is not a project member before anything had been fetched, on every fresh page load.
+
+  The plugin's identity bridge now resolves the logged-in user before consulting the directory's state. An id that carries its own account-global identity — a `g…` global id, a robot, the global id embedded in a third-party-login `e-` id — resolves immediately and is unaffected by a directory that is still loading or has failed. Only a plain project-scoped id needs the member join, so only it waits, and only it can turn out unresolvable once the directory answers. That case keeps its warning, and a directory that failed to load now says so and names the failure instead of attributing it to project membership.
+
+- 9554d46: The Workflows tool's task list waits for the document groups' preview titles before revealing — up to a short max wait, since an unreadable document's title never resolves — and mounts once in its settled alphabetical order, rather than painting in document-id order and re-sorting as titles land. A cold load answers titles with one batched query (compiled from each type's preview select where that select can be expressed as a flat projection, the type's own `prepare` applied) that also seeds the doc-ref link verdicts, so the wait usually shrinks to a single round trip instead of several chained preview-store hydration waves; types the compiler can't express, and documents the batch can't read, still resolve through the live pipeline under the bounded wait. The live preview observations stay open and always win over the seed, so renames, deletions, and new documents keep flowing in real time. A seeded title a live observation later contradicts warns in the console (document id only) and emits one `Editorial Workflows Studio Plugin Title Seed Drifted` telemetry event per task-list mount, count-only payload. A doc-ref face whose link verdict is still undecided renders a time-boxed title skeleton instead of the raw document id, degrading to the bare id when the verdict is still undecided after a few seconds; the face upgrades to a linked preview or a notice whenever the verdict lands.
+- 208a9e1: Expanding or collapsing one band in the Workflows tool no longer repaints the rest of the page. A segment's expand/collapse memory moves from state held above the list to a subscribable store: a toggle notifies every band, but each band reads only its own key, so the bands that re-render are the ones whose state changed. The Documents board's stacked layout rides the same mechanism. Persistence is unchanged — explicit toggles only, per segment, same stored payload and cap.
+- Updated dependencies [d029896]
+- Updated dependencies [0bc4328]
+- Updated dependencies [d029896]
+- Updated dependencies [0bc4328]
+- Updated dependencies [0bc4328]
+- Updated dependencies [0bc4328]
+- Updated dependencies [0bc4328]
+- Updated dependencies [0bc4328]
+- Updated dependencies [4b7531f]
+- Updated dependencies [0bc4328]
+- Updated dependencies [0bc4328]
+- Updated dependencies [0bc4328]
+- Updated dependencies [0bc4328]
+- Updated dependencies [0bc4328]
+- Updated dependencies [41a3f02]
+- Updated dependencies [d570436]
+  - @sanity/workflow-diagram@0.24.0
+  - @sanity/workflow-engine@0.24.0
+  - @sanity/workflow-studio@0.24.0
+  - @sanity/workflow-components@0.24.0
+  - @sanity/workflow-react@0.24.0
+
+## 0.23.0
+
+### Minor Changes
+
+- 2a2c5d0: The Workflows tool renders full width with a compact title, and its chrome — the title row and the tab strip — stays mounted on every route: detail views render under it with their own title line below the tabs, and selecting a tab from a detail view returns to the home panel on that tab. The back-arrow button is gone; the tab strip is the tool's navigation. The selected tab is a path segment (`…/workflows/definitions`), not a search param, and on detail routes the strip highlights the tab the page's kind belongs to (instances under Overview, definitions under Definitions).
+
+  The tool's task list uses one spacing step between all bands, so a closed workflow band sits the same distance from the next document group as from its own group header.
+
+  The For me tabs share one empty state: the tool now shows the same "Nothing to do!" card as the document view, and on both surfaces the empty card fills the panel's remaining space with its lockup centered.
+
+  The tool's Overview and For me tabs order their document groups alphabetically by each document's resolved preview title, title-less documents trailing on a stable key. Preview titles resolved as data (this ordering, the document filter's options) now follow the doc-ref faces' rules — the target's probed actual type, draft-aware, under the active perspective — so a draft-only document or a generic stored ref type titles the same everywhere.
+
+  The tool gains a Definitions tab between Overview and For me: the deployed catalog, one clickable row per definition with its description, live in-flight instance count, and the document types it runs on (the discovery-effective mappings, schema-titled). Each row opens a deep-linkable definition detail view — when it was deployed and under which tag, how runs begin, the document types, the description, and the full stage diagram.
+
+  The tool's capped instance stream stays warm from the first home-panel visit for the rest of the tool session, so returning to a list from a detail view repaints counts and task rows immediately instead of flashing loading placeholders. A detail view entered directly (deep link, document-view jump-out) doesn't start the stream until a list is first shown.
+
+  The event log moves from the document view into the tool. Each document-view instance section's overflow menu is gone entirely — its "Event log (debug)" dialog is removed, and the jump into the tool becomes a text link under the expanded instance body (collapsed sections offer nothing, so stacked instances don't accumulate header buttons), rendered only when the workspace's resolved tool list includes the Workflows tool — a host studio that filters the tool out gets no dead link. The tool's instance detail renders the log inline under the stage card instead — the full history feed, newest first, with no kind tabs, actor filter, or resolution badge. Each entry is an attributed line: the acting user's avatar and name leading the sentence (engine-driven entries carry a glyph and read standalone — a cascade-fired action attributes to the workflow, not the token that executed it), with a compact relative timestamp ("15d ago") carrying the absolute time on hover. Resolved stage/activity/action titles render bare (no quotes); machine names (effect names, op types) render as monospaced chips; lines never wrap — the sentence ellipsizes so the timestamp stays whole. Pending effects sit at the top of the same feed as ordinary rows — a waiting glyph, the effect and where its run will come from, its queued age — with their resolutions in a per-row overflow menu: "Run registered handlers" (only when the effect has a Studio handler) plus the manual done/failed overrides.
+
+  The tool's instance detail title names its subject: "<workflow title> in <document chip>" — the slim one-line document preview linking to the document, cap-cancelled so the title line's position doesn't shift. Instances referencing no Studio document keep the bare title.
+
+  The tool's instance detail view now renders the same per-instance snapshot as the Workflows document view — part-of band, workflow-scope field pills (with their inline editors), and the spine-topped stage card — constrained to the document pane's width, so the two surfaces read as one. The stage diagram, the Studio-documents preview section, and the "All tasks" list leave the instance detail view — the diagram renders on the definition detail instead, so the plugin's `@sanity/workflow-diagram` peer dependency is unchanged.
+
+  Document previews now come in two modes. The activity dialog's "Studio document" details row renders the slim one-line chip (schema icon + title, opens the document) instead of the full preview card; form contexts (activity field values) keep the full card. The workflow stage/"+N" preview decoration is removed everywhere — the plugin no longer registers preview middleware, so its cards and reference-field previews of workflow-mapped types render Studio's native preview unchanged. Workflow stage remains visible in the form strip, the document footer badge, and the Workflows tool.
+
+### Patch Changes
+
+- 2a2c5d0: The Workflows tool's definition surfaces (Definitions tab, definition detail, start picker) paint the previously read catalog immediately on a revisit while the fresh read runs behind it, instead of showing a loading spinner on every visit.
+- Updated dependencies [94d311e]
+- Updated dependencies [795b4bb]
+  - @sanity/workflow-engine@0.23.0
+  - @sanity/workflow-components@0.23.0
+  - @sanity/workflow-diagram@0.23.0
+  - @sanity/workflow-react@0.23.0
+  - @sanity/workflow-studio@0.23.0
+
 ## 0.22.0
 
 ### Patch Changes

package/README.md

@@ -10,9 +10,15 @@ 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 to-dos,
-where they fire actions and read the history, and a **Workflows tool** in the
-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.
+where they fire actions, and a **Workflows tool** in the Studio navbar — the
+open tasks across the newest workflow instances (capped), the user's own cut
+of them, the deployed definitions catalog, one chosen workflow's documents
+grouped by stage (as side-by-side columns or a stacked list, at its own
+shareable address), and deep-linkable per-instance and per-definition detail
+views (the instance detail carries the full history feed). That detail view is also where a running workflow can be stopped: an
+**Abort workflow** button below the stage card, against a reason recorded in
+the workflow's history. Aborting is open to anyone who can act on the
+instance, and cannot be undone.
 
 Four ideas cover everything in this guide:
 
@@ -146,7 +152,10 @@ export default defineConfig({
 ```
 
 The plugin discovers deployed definitions whose caller-provided subject accepts
-a document type in this Studio schema. Start the studio and open an `article`:
+a document type this Studio schema declares. System document types — Sanity's
+reserved `sanity.` namespace, the built-in asset documents among it, and the
+engine's own types — are never discovered; binding a workflow to one takes an
+explicit mapping row. 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
@@ -160,22 +169,6 @@ 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.
 
-### Workflow status in previews
-
-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.
-
-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` on a mapping override starts a workflow the moment an editor opens a **fresh** document