@sanity/workflow-studio-plugin 0.28.0 → 0.29.0

package/CHANGELOG.md

@@ -1,5 +1,300 @@
 # @sanity/workflow-studio-plugin
 
+## 0.29.0
+
+### Minor Changes
+
+- 25bd1fb: A workflow's documents page now shows the faults its catalog card advertises.
+  Clicking a card flagged for stuck runs or overdue work used to land on a board
+  that showed neither, so a reader who came to fix something arrived with no way
+  to find it.
+
+  Each document card carries the same glyph-and-number pairs a catalog card wears,
+  in the same tones: open tasks, which recede to a dimmed zero when there are none,
+  and overdue tasks in caution, absent when nothing is late. A run that cannot
+  continue wears the critical alert glyph opposite its title, where a catalog card
+  wears its own. These replace the "3 pending tasks" chip, which said one fact in
+  words where the row now says three in the space the chip took; the affirmative it
+  used to show moves into the open-tasks hint, since a lane of finished runs
+  repeated it under a heading that already said the stage.
+
+  Stage headings carry the same two marks for the lane beneath them, so a fault on
+  a card below the fold is visible without scrolling to it. They count CARDS, the
+  unit the heading's own count already uses. That differs from a catalog card's
+  overdue tally, which counts documents: one document carrying two runs of the same
+  workflow is two cards on the board and one on the card. Both figures are right
+  for the question their surface answers, and each hint says which it means.
+
+  Overdue is measured on one shared rule for both surfaces, so a card and the board
+  under it can no longer disagree about which activities are open or which dates
+  have passed.
+
+  An activity's own due date now tones and explains itself the way a todo item's
+  already did: muted until it passes, caution once it has, and "Now overdue" on
+  hover. One rendering serves every due date a run shows, so an activity chip and a
+  todo row cannot disagree with the cards and lane headings above them about the
+  same date. It tones while editable too — a deadline is late whether or not this
+  reader can move it. Where a date
+  also carries a reason it cannot be changed, the hint leads with the lateness and
+  keeps the reason on a second line. Both surfaces render through one component
+  that owns the tone and the hint together, so neither can state a date the other
+  judges differently.
+
+  The catalog card no longer flags a rejected mapping row. That fault belongs to
+  the definition rather than to any of its runs, it stops a workflow being STARTED
+  on a document type while leaving every run already in flight untouched, and its
+  diagnostic is written for whoever maintains the host's mapping table rather than
+  for an editor — a different class, owed its own surface. Until that surface
+  exists the fault is reported on the workflow's Definition page and in the browser
+  console, and not on the landing grid.
+
+  **No upgrade action required.** No API, prop or stored shape changes, and the
+  mapping validation itself is unchanged — only where its verdict is shown.
+
+  **Docs impact:** Update the Workflows tool guide where it describes a workflow's
+  documents page, to cover the per-card signals and the stage-heading marks, and
+  note that a rejected mapping row surfaces on the Definition page rather than on
+  the catalog card.
+
+- 25bd1fb: Each card in the Studio plugin's Workflows tab now carries what the definition
+  is doing, not just its name: how many of its documents have work in flight, when
+  one of them last changed stage, how many hold a task past its due date, and one
+  alert glyph when something is wrong. The card reports live state only — what a
+  workflow runs on and what it says about itself change on a deploy, and that
+  workflow's own Definition page already names both. The
+  grid bands into "Assigned to you" and "Other workflows", so whether the reader
+  has work in a workflow is carried by where its card sits; rows keep the
+  catalog's alphabetical order inside each band. A card wears one alert, and it
+  means a run of that workflow cannot continue without help. The engine's
+  `blocked` readiness hold earns none, because it is an expected transient state
+  and flagging it would mark most cards most of the time; a rejected
+  document-type binding earns none either, because it belongs to the definition
+  rather than to any of its runs and is reported on that workflow's Definition
+  page.
+
+  The age on a card is a STAGE ARRIVAL, not a last-modified stamp. Every engine
+  commit moves an instance's change stamp — an assignment, a date, a drained
+  effect — and a workflow can absorb a great deal of that without advancing, so
+  the arrival is the event a catalog can read as progress. The consequence is
+  deliberate: a busy workflow held inside one stage reads as old, which is the
+  pathology worth seeing. Hovering that age names the move — which document went
+  to which stage, and the exact time — resolving the document's title through the
+  preview store only once the tooltip opens.
+
+  Overdue is the only signal drawn in a tone — caution, where the alert glyph
+  takes critical — and the only one that disappears when it reads zero: it reports
+  that something is wrong rather than how things stand, so a card with nothing
+  late spends no room saying so. A
+  document counts as overdue while an unsettled task on it is past its due date;
+  a finished task's date, however old, is not a debt. Overdue is measured on one
+  shared rule with the todo rows, so a card's count and a row's face can no
+  longer disagree about a single date.
+
+  The grid counts DOCUMENTS where it used to count instances, because its reader
+  is an editor and the document is what they open. Several instances on one
+  document count once. An instance whose chain references no document counts as
+  one unit of its own, so a workflow that runs on no document does not read as
+  idle. The workflow's own page still reports instances, in those words.
+
+  Hovering that count also says how many of those documents have yet to leave the
+  stage their workflow starts from — on a line of its own, so the two facts can be
+  scanned rather than read through, and folded into the first line when the answer
+  is all of them, where a second line would repeat one number. A document counts
+  there while any of its runs still waits at the start, judged against that run's
+  own pinned snapshot, so a run begun under an earlier version answers to where
+  that version started. The count stays in the hint rather than taking a slot on
+  the rule: it is a part of a number the card already shows, meaningless without
+  that total beside it, and no glyph in the set says "waiting at the start".
+
+  The page no longer opens on a project-wide total. The band headings count the
+  workflows, so a total above them stated the same figure twice, and a total of
+  documents invited a comparison against the cards that can never add up — one
+  document running two workflows is one document in a project total and one on
+  each of their cards.
+
+  The engine gains `documentStuckCause`, which classifies an instance as stuck
+  from its persisted document and pinned snapshot alone — no evaluation, no
+  reads, no actor. It answers for the effect- and activity-level causes
+  `diagnoseInstance` reports (`failed-effect`, `failed-activity`,
+  `hung-effect`) and returns `undefined` for the transition-level ones, which
+  need GROQ results. It is sound but incomplete by construction: a cause it
+  reports is real, and the absence of one means only that no cause was provable,
+  never that the instance is healthy. Surfaces flagging on it must not word an
+  unflagged state as an all-clear. `findActivityNode` and `findStageNode`, the
+  tolerant definition tree lookups it uses, are exported alongside it.
+
+  The tool's instance read is held per engine for the session and replayed on the
+  next mount, which changes what the Workflows tab paints while it loads. A first
+  visit now waits for that read before the definitions grid appears, where it used
+  to lay out cards from the catalog and rearrange them once the instances landed —
+  the grid's bands and counts come from the instances, so the cards had no stable
+  shape until both reads were in. The grid waits on the reader's identity for the
+  same reason: which band a card sits in depends on who is looking, and a
+  project-scoped account resolves through the project member directory, so banding
+  before that answer arrived would have moved every card once it did. An account
+  the directory cannot place, or a directory that fails to load, is an answer
+  rather than a wait — the grid paints unbanded and every card reports no assigned
+  work. A later visit inside the same session paints the
+  held read at once and refreshes behind it.
+
+  The form strip's assigned-task count tells those two apart as well, so an account
+  the member directory cannot place no longer leaves a spinner turning in that slot
+  for the rest of the session. It shows no count, which is what it already did for
+  an account with nothing assigned. The hold is not local to the grid: the
+  task rows under "All documents" and "For me", and the active-instance count on a
+  workflow's Definition page, read the same stream, so they too open on held
+  numbers before the fresh read lands. A failed read is never held, and a provider remount mints a new engine and
+  so starts cold.
+
+  **No upgrade action required.** The card additions are automatic, and
+  `documentStuckCause` is a new export that changes no existing verdict —
+  `diagnoseInstance` classifies exactly as before, now sharing one
+  implementation of the document-derivable causes.
+
+  **Docs impact:** Update the Workflows tool guide where it describes the
+  definitions grid, to cover the new card signals, the assigned-work ordering, the
+  document-versus-instance split between the grid and a workflow's own page, and
+  that the tab opens on a held read after the first visit.
+  `docs/reference.md` already carries `documentStuckCause` beside
+  `diagnoseInstance` with its bound stated; the hosted engine reference needs the
+  same entry, so integrators do not read a missing cause as a health check.
+
+- 25bd1fb: A run that cannot continue now says why, on the run itself. A card flagged it and
+  the run it opened showed nothing, so a reader who followed the flag to fix
+  something arrived at the one screen that should have explained it and found four
+  history rows to interpret.
+
+  The notice leads the detail body — above even the document, since it is what the
+  reader came for — and names the fault plus what would move it: which automated
+  step failed or never finished, or which task failed, or that every task here is
+  done and nothing routes onward. It is absent when nothing is wrong, so it never
+  becomes chrome to skip.
+
+  It is worded for an editor rather than for whoever runs the engine. The engine
+  names each remedy as a surface-neutral verb alongside a rationale written for an
+  operator; the plugin maps the verb to its own copy and does not render that
+  rationale. So an effect reads as "the automated step", matching the label its
+  activity row already wears, and aborting keeps the word the button in Manage
+  workflow uses.
+
+  One hold is drawn in caution rather than critical and offers no remedy: a route
+  out of the stage that cannot be evaluated yet clears itself once what it reads
+  becomes readable, and the engine deliberately suggests no verb for it, because
+  forcing the run onward would skip the gate doing its job. Telling a reader their
+  work is broken when they can only wait is the same error as flagging an expected
+  transient.
+
+  The detail asks a fuller question than the card that led to it. Cards classify
+  from the committed document alone, because a grid painting every workflow at once
+  cannot afford an evaluation per run; that read cannot answer the two causes needing
+  GROQ results. A detail has one run and a live session, so it uses the full
+  diagnosis and falls back to the card's classifier only when no evaluation exists.
+  A card flagging nothing never claimed the run was healthy — only that nothing was
+  provable from a document — so a detail may report a fault its card could not see.
+
+  A reader can now follow the fault down to the task that owns it. An effect is
+  declared by one activity's action, so a failed or hung effect belongs to that
+  task — resolved through the effect's name, which is unique per definition. Where
+  the pinned snapshot no longer declares the effect, no task is named rather than a
+  sibling guessed at. A task the fault belongs to carries a critical glyph beside
+  its title, suppressed where its own status already reads failed so one problem
+  never shows as two, and its dialog carries the notice. A task the fault is not
+  about stays quiet.
+
+  What can be pressed there depends on the fault. A hung effect offers the drain,
+  which is the one operation this plugin can run; every other cause carries advice
+  naming what would move the run, because the step that unsticks it is not callable
+  from a browser.
+
+  The two surfaces say different things rather than the same thing twice. The run
+  names the class of fault and offers the way in — a reader there has not decided to
+  fix anything, and the title of the step that failed is precise where they want
+  orientation. The task names the step and carries what can be pressed. Both lines
+  are titles: what is in the way, with no clause explaining that the workflow is
+  therefore stuck, which a red notice on the workflow does not need to say.
+
+  Pressing the button runs the effect handlers registered in this Studio — the same
+  operation the history feed's pending rows already offered, now reachable from the
+  fault that calls for it. It is the only remedy the plugin can run today; resetting
+  a task and forcing a stage remain advice, and aborting goes unsaid because the
+  engine offers it against nearly every cause and the run already carries its own
+  Abort control.
+
+  **No upgrade action required.** No API, prop or stored shape changes; the
+  diagnosis and remediation functions were already exported and are now consumed.
+
+  **Docs impact:** Update the Workflows tool guide where it covers a run's detail
+  view, to describe the fault notice and to state that a workflow's detail can
+  report a stuck cause its card could not prove.
+
+- 3fd04f1: **BREAKING:** `ActionSemantic` was a closed union of action decision values; it now also includes signal values and the open `custom.${string}` form. TypeScript consumers that exhaustively map `ActionSemantic` must handle signal and custom values or narrow to the decision subset before upgrading, otherwise their build will fail. Workflow authors can attach advisory signals and validated custom semantics to workflow roots, stages, activities, and actions, and evaluation results expose them at each matching level.
+
+  Existing stored definitions and runtime behavior remain compatible. The Studio plugin continues to render decision faces when decision values are composed with signal or custom semantics, while non-decision values receive the default action face.
+
+  **Docs impact:** Update the definition and evaluation references plus the concepts guide to document level-wide advisory semantics, the signal vocabulary, custom grammar, and action-only decision values.
+
+### Patch Changes
+
+- 25bd1fb: The workflow documents board no longer mounts with every card blank while its
+  titles are still arriving. The board holds a loading row until each card's preview
+  title has landed, so it can mount once, sorted. Readiness now requires a board to
+  be a claim about: a workflow that has not resolved yet orders by no documents, and
+  an empty ordering no longer reads as ready.
+
+  The hold stays bounded, so a title that can never resolve — a permission-denied
+  document with an unopenable stored type — cannot keep a surface waiting forever.
+  Two bounds, because two different things go wrong: once a title has landed the wait
+  ends when answers stop, measured from the last one and re-armed by each new one, so
+  a batch still answering is waited for however long it takes; before the first answer
+  there is nothing to measure a stall against, so that case gets its own far longer
+  allowance.
+
+  **No upgrade action required.** No API, prop or stored shape changes; a surface
+  that was already mounting fully sorted behaves as before.
+
+  **Docs impact: None.** The loading behaviour of these lists is not described in
+  the docs, and no guide states the previous timing.
+
+- 25bd1fb: Loading cues no longer flash on fast reads. A read that settles quickly now
+  paints nothing at all, while a slow one still announces itself. The wait covers
+  the whole cue rather than the spinner alone: where a spinner and its label share
+  a row, both are held and both arrive on the same frame, so a cue never assembles
+  itself a piece at a time. A spinner standing on its own beside a heading is held
+  the same way, because the tool's loading rows and headings share one reserved
+  slot. That slot already reserved its square whether or not the glyph rendered, which is what
+  makes the wait free — nothing moves when the cue arrives late, and no caller
+  needs a delay of its own. Two surfaces that delayed their own busy flag to dodge
+  this flash no longer do, since they would otherwise wait twice; one figure
+  governs every cue that rides the slot. The document view's discovery spinner
+  keeps a longer wait of its own.
+
+  The Workflows tool's first line also sits at one height across its states. A
+  tab's loading note, a workflow page's picker and the definitions grid's band
+  headings each sat at a different offset, which showed as the line jumping when a
+  read landed. The status row takes the panel step plus the heading inset that
+  every other first line gets from the box it sits in, and the picker's inset moved
+  off the button onto the row around it, because a button clamps its own vertical
+  padding below that step. The picker keeps its full-height hit area by reclaiming
+  that inset. Its row moves down by the correction, so the page's own strip and the
+  board below it follow.
+
+  **No upgrade action required.** Both are internal to the plugin's own chrome and
+  change no API, prop or stored shape.
+
+  **Docs impact: None.** Neither the spinner timing nor the tool's internal
+  line-up is described in the docs; no guide, reference or example states the old
+  behaviour.
+
+- Updated dependencies [f44fc33]
+- Updated dependencies [26f25e0]
+- Updated dependencies [25bd1fb]
+- Updated dependencies [3fd04f1]
+  - @sanity/workflow-engine@0.29.0
+  - @sanity/workflow-components@0.29.0
+  - @sanity/workflow-diagram@0.29.0
+  - @sanity/workflow-react@0.29.0
+  - @sanity/workflow-studio@0.29.0
+
 ## 0.28.0
 
 ### Minor Changes