@sanity/workflow-studio-plugin 0.26.0 → 0.28.0

package/CHANGELOG.md

@@ -1,5 +1,246 @@
 # @sanity/workflow-studio-plugin
 
+## 0.28.0
+
+### Minor Changes
+
+- b9947cb: Both "For me" surfaces — the document Workflows view's tab and the Workflows
+  tool's segment — now account for work that reached the reader through a role
+  rather than by name. When any listed row is assigned to a role the reader
+  holds, a line above the list reads "Including tasks assigned to your role". A
+  list whose rows only name the reader shows nothing, and neither does the tool's
+  "All documents" tab, which never claimed its rows were the reader's. In the tool
+  the line tracks the filtered list, so filtering every role-matched row away
+  takes it with it.
+
+  What counts as assigned is unchanged — role-matched work already appeared in
+  "For me" and still does, and the tab's task count is unaffected. Only the
+  explanation is new.
+
+  **No upgrade action required.** The notice derives from the same assignment
+  matching the list already used, so no definition, configuration, or role setup
+  changes.
+
+  **Docs impact:** Update the Studio plugin guide where it describes the "For me"
+  tab and the Workflows tool's For me segment, to note that role assignment
+  surfaces work to every holder of the role and that both surfaces say so when it
+  happens.
+
+- 6584554: **BREAKING:** assignment surfaces now read the project's role catalog, so a role
+  with no current holders is assignable and carries its project title.
+
+  Previously the only role vocabulary was the roles loaded members happened to
+  hold. A role the project defines but nobody has yet could not be offered at all,
+  and a role named by a stored value rendered as its bare machine name because no
+  membership record carried a title for it. Both are fixed by reading
+  `GET /projects/{projectId}/roles`. That read is gated on
+  `sanity-project-roles: read`, which the default user-facing project roles carry
+  down to viewer, so it is not expected to need an administrator.
+
+  The catalog also becomes the bound on what a picker offers, which subtracts as
+  well as adds: a role a member holds that the catalog does not list stops being
+  offerable, though it still labels correctly wherever it is already assigned. On
+  a complete catalog nothing is lost, since every held role is in it.
+
+  Three API changes, all in `@sanity/workflow-components`:
+  - `ProjectMembersState` gains a required `roles` field, the project's assignable
+    roles. Anything constructing this state by hand must supply it; `roles: []`
+    preserves the previous behaviour, since resolution falls back to the roles
+    members hold. `MemberPicker` does not take it — it lists members only, and its
+    props were narrowed to the three fields it reads.
+  - `memberRoleFor` and `roleLabelFor` take a `RoleVocabulary` (`{members, roles}`)
+    in place of a bare member array. The state either adapter returns satisfies it,
+    so a caller holding one can pass it straight through.
+  - `AssigneeBadge` and `AssigneeBadges` take `vocabulary` in place of `members`,
+    for the same reason.
+
+  Not migrating leaves a type error at each call site rather than a silent
+  behaviour change.
+
+  Hosts using `@sanity/workflow-studio` or `@sanity/workflow-sdk` get the catalog
+  without changes: both adapters fetch it beside the member list, each behind a
+  per-client, per-project cache, so it costs one extra request per project per page
+  load however many surfaces read it. A failed roles read is deliberately
+  non-fatal — it degrades to the previous member-derived behaviour rather than
+  taking down the member list, and therefore every assignment control, with it. It
+  is reported once on the console with its cause, because nothing downstream can
+  tell an unreadable catalog from a project that defines no assignable roles. That
+  empty result is cached too, so a project whose catalog cannot be read stays on
+  the member-derived behaviour until the page reloads.
+
+  **Docs impact:** Update the assignment concepts and any Studio plugin guidance
+  that describes which roles can be assigned, to say the catalog is the source,
+  that a role with no holders is offered, and that a held role missing from the
+  catalog is not. The `@sanity/workflow-components` README covers the new
+  `RoleVocabulary` shape and the picker's behaviour.
+
+### Patch Changes
+
+- f4405b4: The Workflows tool reports a failed read as a failure, in one critical-toned
+  banner, on every surface that derives counts or lists from it: the Workflows
+  tab, a workflow's definition panel, the task tabs, a workflow's board, and the
+  New workflow picker. A failed read is distinguishable from a project with
+  nothing running — it produces no zero counts, no "no tasks" empty state and no
+  empty board, and where a count cannot be stated the definition panel shows an
+  em-dash. The banner tells an editor plainly that something didn't load and that
+  trying later may work; the technical cause is logged to the browser console for
+  whoever maintains the Studio.
+
+  **No upgrade action required.** This is display-only — no API, configuration,
+  or stored data changes, and a successful read renders exactly as before.
+
+  **Docs impact:** None. Only the failed-read path changes; a successful read
+  renders identically, so nothing the Workflows tool guide describes about
+  active-instance counts, task lists, or the board is affected.
+
+- a044ba5: Report a Studio start whose auto-advance lost a write race as the finished run
+  it is. Starting a workflow from the Studio while another runtime (a deployed
+  Function, a script) drives the same instance could hand the editor a warning
+  toast — "'…' started but didn't finish", with a raw `unexpected revision ID`
+  mutation error under it — for a run that had in fact completed: the Studio's own
+  auto-advance simply lost the write race to whoever committed the equivalent move
+  first. That toast was indistinguishable from a genuinely stuck workflow. The
+  Studio now confirms the completed start instead of warning about it.
+
+  Narrow by design: only a lost revision race whose run is already complete is
+  reclassified. A conflict that left the run in flight, and any other reason an
+  auto-advance failed, still surface as before.
+
+  `@sanity/workflow-engine` exports `isRevisionConflict`, the predicate that tells
+  a lost optimistic-locking race from a real error, so integrations can classify
+  one without matching on message text. It answers on the error alone, so narrow
+  to a single rev-guarded write before asking — a bare 409 also covers a create-id
+  collision.
+
+  **No upgrade action required.** Engine behaviour is unchanged and the new export
+  is additive.
+
+  **Docs impact:** `isRevisionConflict` is new public engine surface, added to the
+  errors section of `docs/reference.md` alongside the concurrency errors it
+  classifies; mirror that entry wherever published reference material lists the
+  engine's error helpers.
+
+- Updated dependencies [1e4a5da]
+- Updated dependencies [6584554]
+- Updated dependencies [6584554]
+- Updated dependencies [5050b06]
+- Updated dependencies [a044ba5]
+- Updated dependencies [6584554]
+  - @sanity/workflow-engine@0.28.0
+  - @sanity/workflow-components@0.28.0
+  - @sanity/workflow-studio@0.28.0
+  - @sanity/workflow-diagram@0.28.0
+  - @sanity/workflow-react@0.28.0
+
+## 0.27.0
+
+### Minor Changes
+
+- b7ebbee: The Workflows document view now presents each workflow instance as its own
+  card rather than a row in a shared accordion band. The card's header carries
+  the run's title over the stage it sits at, with its status badges ("Aborted",
+  "Older version") on the trailing edge, so a collapsed run still says where it
+  stands. Clicking anywhere on the header toggles the card — the previous
+  double-click-the-band gesture and its discrete chevron button are gone. An
+  open card tints its header to separate it from the body below.
+
+  Each card carries a run's own history and actions behind an overflow menu on
+  its header. "Workflow history" opens the activity feed in a dialog, and
+  "Abort workflow…" sits under a divider, reusing the existing confirm dialog
+  and its required reason. Because both are now local to the card, the "View
+  workflow details" link that jumped to the Workflows tool is gone; the tool's
+  run detail keeps its own address and is still reachable from the Tasks tab
+  and from any link carrying the workflow intent.
+
+  Field pills lead with the field's title. A pill holding a value reads
+  "Title: value" with the title as a muted label; an empty pill shows the title
+  alone and no longer prefixes it with "Set". A pill's hover hint carries only
+  the author's description, since the chip now states the title itself, and a
+  read-only pill no longer repeats the run's own state back — "This workflow is
+  already complete" and "This workflow was aborted" describe the instance, which
+  the card already shows, while every verdict specific to the field still
+  appears. A to-do list holding nothing now says so with the shared empty card
+  rather than rendering blank, carrying the add affordance when the run can
+  still take items.
+
+  The stage diagram inside a card no longer sits on a filled band; its dividing
+  rule alone separates it from the stage's work. This also applies to the run
+  detail in the Workflows tool, which renders the same body.
+
+  **No upgrade action required.** This is presentation only: no plugin
+  configuration, workflow definition, telemetry event, or stored instance shape
+  changes.
+
+  **Docs impact:** Refresh any screenshot or walkthrough of the document
+  editor's Workflows tab — instances are cards, expanding one is a single click
+  on its header rather than a double click on a band, and a run's history and
+  abort are reached from the card's overflow menu rather than by navigating to
+  the Workflows tool. Update any guidance that tells readers to open the tool's
+  run detail for history or to stop a workflow.
+
+- 780cf93: **BREAKING:** `ProjectMember.roles` is now `readonly {name: string; title?: string}[]` instead of `readonly string[]`, and `AssigneeStack`'s `roles` prop takes the same records rather than name strings. This affects integrations that build or read `ProjectMember` rows directly, or render `AssigneeStack` themselves. Read `role.name` wherever a role name was read before, and pass role records rather than name strings into `projectMemberRow` and `AssigneeStack`. Until migrated, TypeScript fails at those sites. Integrations using `useProjectMembers` from `@sanity/workflow-sdk` or the Studio plugin's own equivalent get the new shape without changes, because the adapters own the projection.
+
+  A role now reads as its project title rather than its machine name — `Administrator`, not `administrator` — wherever one is shown: picker role rows, assignee badges, the instance-snapshot pills, and the hover hint naming a collapsed assignee cluster. A square role avatar takes its letters from the title too, so `Blueprints Deployer` reads as `BD` where `blueprints-deployer` could only ever give one letter; its colour still derives from the machine name, so retitling a project role keeps the role's colour. A role whose membership record carries no title — or a title that is only whitespace, which counts as none — and a role named by an assignee that no current member holds, both still read as the machine name. `roleLabel`, `roleLabelFor`, and `memberRoleFor` are exported for callers rendering their own role labels.
+
+  Both people-pickers now say who a person is, so choosing one no longer requires knowing the org chart. Search matches role names and titles as well as display name and email, so typing a role narrows the list to its holders. Members are also listed by display name rather than in the order the host supplied them, which was the sequence people joined the project — expect the list order to change, and on a large project to become usable. And hovering a row previews the account behind the name — a larger avatar badged with the person's identity provider, their email, and the roles they hold. Marks exist for Google, GitHub, and `saml-`-prefixed deployments; any other provider badges nothing rather than showing an empty circle. That is what tells two members sharing a display name apart, which no role label could. Rows share one tooltip delay group, so the wait to open is paid once and moving along the list swaps the preview rather than waiting again at each row.
+
+  `MemberAvatar` takes an optional `loginProvider` to badge the provider mark onto its corner. `ProjectMember` gains optional `loginProvider` and `isCurrentUser`; both are populated by the adapters, so integrations using `useProjectMembers` get them without changes.
+
+  Neither picker ranks or groups its member rows by the roles those members hold, and neither claims who is eligible for an activity. (The roles-and-members picker still lists selectable roles above the members, as it did before.) An activity has no role gate; only an action does, and a manually fired action's `roles` is folded into its `filter` at desugar, so the accepted set is not readable from a deployed definition. A picker has nothing to derive eligibility from, and a ranked list would assert something no engine or Content Lake check backs.
+
+  Stored values are unchanged. An assignee still persists the machine role name, and titles are display only.
+
+  **Docs impact:** Update the `@sanity/workflow-components` member-selection reference for the `ProjectMember.roles` and `AssigneeStack` `roles` shapes and the `roleLabel` / `roleLabelFor` / `memberRoleFor` exports (done in this package's README). Any concept or guide page showing a role in Studio UI should show titles rather than machine names, and the assignment guide should state that a picker never restricts or ranks who may be assigned. Add the `ProjectMember.roles` migration to the release notes.
+
+- 7788422: Every assignee field in the Studio plugin opens the same roles-and-members
+  picker, and a role can be assigned or cleared from any of them: the activity
+  row's assign control, a to-do item's assignee control, the start dialog's
+  assignees input, the instance-snapshot field pills and the editable field panel.
+  Actor fields — a claim, an action's `actor` param, provenance — keep the
+  members-only picker, because they name a concrete person and cannot hold a role.
+
+  A row shows one cluster holding both kinds: people as round avatars and each
+  assigned role as a square one, initialled and colored from the role's own name.
+  Roles ride on top, so a cluster past three items collapses to roles rather than
+  to faces, and a leading counter stands for the rest. The names live in the
+  cluster's hover hint, which lists roles and members under separate headings.
+
+  An activity row derives its assignment from the activity's `assignees` entry
+  alone. That kind is what the engine treats as the assignment — it reads that
+  kind for `$assigned` and caps a scope at one, the way `dueDate` is the deadline
+  and a plain `date` is not. Any other assignee-valued field on the activity, such
+  as a declared `primaryReviewer` of the singular `assignee` kind, is an ordinary
+  field and keeps its own picker in the snapshot pills and the activity dialog.
+
+  **No upgrade action required.** No stored shape changes: `{type: 'role', role}`
+  was already a valid assignee everywhere the engine accepts one. Two display
+  notes for anyone comparing before and after. An activity that carries an
+  assignee-valued field beside its `assignees` field shows fewer people on the row
+  than it used to, because only the `assignees` entry now feeds it — that other
+  field is unchanged and still editable in the snapshot and the dialog. And the
+  Workflows tool's assignee filter names people only, so a role-assigned task is
+  not selected by filtering on a member who holds that role.
+
+  **Docs impact:** Update the Studio plugin guide where it describes assigning
+  activities and to-do items, so it states that assignment accepts a role as well
+  as a person from every assignee control, and that a role shows as a square
+  avatar whose name appears on hover. Refresh screenshots of the activity row.
+  Note in the assignment concept material that a row's assignment is the
+  `assignees` entry, and that other assignee-valued fields are ordinary fields.
+  The assignee-filter behavior above is worth a sentence wherever the Workflows
+  tool's filters are documented.
+
+### Patch Changes
+
+- Updated dependencies [780cf93]
+- Updated dependencies [7788422]
+- Updated dependencies [b7c8bed]
+  - @sanity/workflow-components@0.27.0
+  - @sanity/workflow-engine@0.27.0
+  - @sanity/workflow-studio@0.27.0
+  - @sanity/workflow-react@0.27.0
+  - @sanity/workflow-diagram@0.27.0
+
 ## 0.26.0
 
 ### Patch Changes