@sanity/workflow-studio 0.27.0 → 0.29.0

package/CHANGELOG.md

@@ -1,5 +1,80 @@
 # @sanity/workflow-studio
 
+## 0.29.0
+
+### Patch Changes
+
+- Updated dependencies [f44fc33]
+- Updated dependencies [26f25e0]
+- Updated dependencies [25bd1fb]
+- Updated dependencies [3fd04f1]
+  - @sanity/workflow-engine@0.29.0
+  - @sanity/workflow-react@0.29.0
+  - @sanity/workflow-sdk@0.29.0
+
+## 0.28.0
+
+### Minor Changes
+
+- 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
+
+- Updated dependencies [1e4a5da]
+- Updated dependencies [6584554]
+- Updated dependencies [f4405b4]
+- Updated dependencies [5050b06]
+- Updated dependencies [a044ba5]
+  - @sanity/workflow-engine@0.28.0
+  - @sanity/workflow-sdk@0.28.0
+  - @sanity/workflow-react@0.28.0
+
 ## 0.27.0
 
 ### Minor Changes

package/README.md

@@ -33,10 +33,16 @@ Studio source context (`useSource` / `useClient`).
   errors surface reactively through `error`.
 - `useStudioProjectUsers` — the shared Studio project-user directory used by
   actor resolution and member pickers. It returns the upstream membership and
-  profile records without an Editorial Workflows projection, plus the engine's
-  `ProjectUserDirectory` integration. Concurrent loads are coalesced, the
-  settled successful directory is reused for the client/project lifetime, and
-  failed loads retry after a 30-second backoff. A directory that has not
+  profile records without an Editorial Workflows projection, the project's
+  assignable `roles`, and the engine's `ProjectUserDirectory` integration. The
+  role catalog is read alongside the memberships and is the only account of a
+  role nobody currently holds; it is filtered to roles a person can be assigned,
+  and it is empty when the read is unavailable, which leaves role labels to the
+  roles members hold and is reported once on the console with its cause.
+  Concurrent loads are coalesced, the settled successful directory is reused for
+  the client/project lifetime, and a failed membership load retries after a
+  30-second backoff. That backoff does not cover the catalog: an unavailable one
+  is held empty for the client's lifetime rather than re-read. A directory that has not
   answered reports `loading`, including before its fetch starts (the fetch
   begins in a consumer's effect), so an empty `users` with `loading: false`
   and no `error` is a confirmed "no members" rather than a directory nobody

package/dist/index.cjs

@@ -226,6 +226,7 @@ const projectUsersByClient = /* @__PURE__ */ new WeakMap;
 function createProjectUsersStore(client, projectId) {
     let snapshot = {
         users: [],
+        roles: [],
         loading: !0,
         error: void 0
     }, pending, retryAt = 0, usersById = /* @__PURE__ */ new Map, usersByEmail = /* @__PURE__ */ new Map;
@@ -238,18 +239,23 @@ function createProjectUsersStore(client, projectId) {
             ...snapshot,
             loading: !0,
             error: void 0
-        }), pending = fetchProjectUsers(client, projectId).then(users => (usersById = new Map(users.flatMap(user => {
+        }), pending = Promise.all([ fetchProjectUsers(client, projectId), projectUsers.loadProjectRolesOrNone({
+            client: client,
+            projectId: projectId
+        }) ]).then(([users, roles]) => (usersById = new Map(users.flatMap(user => {
             const entries = [ [ user.membership.id, user ] ], globalId = user.profile?.sanityUserId;
             return globalId !== void 0 && globalId !== user.membership.id && entries.push([ globalId, user ]), 
             entries;
         })), usersByEmail = new Map(users.flatMap(user => user.profile?.email ? [ [ user.profile.email.toLowerCase(), user ] ] : [])), 
         retryAt = 1 / 0, setSnapshot({
             users: users,
+            roles: roles,
             loading: !1,
             error: void 0
         }), pending = void 0, users), error => {
             throw retryAt = Date.now() + PROJECT_USERS_RETRY_MS, setSnapshot({
                 users: [],
+                roles: [],
                 loading: !1,
                 error: error
             }), pending = void 0, error;
@@ -316,6 +322,7 @@ function studioProjectUserDirectory(client, projectId) {
 
 const missingProjectSnapshot = {
     users: [],
+    roles: [],
     loading: !1,
     error: new Error("No projectId on the Studio client")
 }, noopSubscribe = () => () => {};

package/dist/index.d.cts

@@ -6,6 +6,7 @@ import type { GdrUri } from "@sanity/workflow-engine";
 import type { InstancesQueryFilter } from "@sanity/workflow-engine";
 import { MissingHandlerPolicy } from "@sanity/workflow-engine";
 import { MutationGuardDoc } from "@sanity/workflow-react";
+import { ProjectRole } from "@sanity/workflow-sdk/project-users";
 import { ProjectUserDirectory } from "@sanity/workflow-engine";
 import { ProjectUserProfile } from "@sanity/workflow-sdk/project-users";
 import { ResourceClientResolver } from "@sanity/workflow-engine";
@@ -61,6 +62,9 @@ export declare function studioProjectUserDirectory(
 
 export declare interface StudioProjectUsersState {
   readonly users: readonly StudioProjectUser[];
+  /** The project's assignable roles, whether or not anyone holds them. Empty
+   *  when the read is unavailable — see {@link loadProjectRolesOrNone}. */
+  readonly roles: readonly ProjectRole[];
   /** True while the directory has not answered, including before its load
    *  starts — the fetch begins in a consumer's effect or the first directory
    *  lookup, one commit after the first render reads this state. An empty

package/dist/index.d.ts

@@ -6,6 +6,7 @@ import type { GdrUri } from "@sanity/workflow-engine";
 import type { InstancesQueryFilter } from "@sanity/workflow-engine";
 import { MissingHandlerPolicy } from "@sanity/workflow-engine";
 import { MutationGuardDoc } from "@sanity/workflow-react";
+import { ProjectRole } from "@sanity/workflow-sdk/project-users";
 import { ProjectUserDirectory } from "@sanity/workflow-engine";
 import { ProjectUserProfile } from "@sanity/workflow-sdk/project-users";
 import { ResourceClientResolver } from "@sanity/workflow-engine";
@@ -61,6 +62,9 @@ export declare function studioProjectUserDirectory(
 
 export declare interface StudioProjectUsersState {
   readonly users: readonly StudioProjectUser[];
+  /** The project's assignable roles, whether or not anyone holds them. Empty
+   *  when the read is unavailable — see {@link loadProjectRolesOrNone}. */
+  readonly roles: readonly ProjectRole[];
   /** True while the directory has not answered, including before its load
    *  starts — the fetch begins in a consumer's effect or the first directory
    *  lookup, one commit after the first render reads this state. An empty

package/dist/index.js

@@ -12,7 +12,7 @@ import { useSource, useClient } from "sanity";
 
 import { useWorkflowTelemetry, useWorkflowSession as useWorkflowSession$1, useDocumentWorkflows as useDocumentWorkflows$1, useWorkflowInstances as useWorkflowInstances$1 } from "@sanity/workflow-react";
 
-import { loadProjectUserProfiles } from "@sanity/workflow-sdk/project-users";
+import { loadProjectRolesOrNone, loadProjectUserProfiles } from "@sanity/workflow-sdk/project-users";
 
 function makeStudioObserver(sdk, options) {
     const {client: client, engineResource: engineResource} = options;
@@ -234,6 +234,7 @@ const projectUsersByClient = /* @__PURE__ */ new WeakMap;
 function createProjectUsersStore(client, projectId) {
     let snapshot = {
         users: [],
+        roles: [],
         loading: !0,
         error: void 0
     }, pending, retryAt = 0, usersById = /* @__PURE__ */ new Map, usersByEmail = /* @__PURE__ */ new Map;
@@ -246,18 +247,23 @@ function createProjectUsersStore(client, projectId) {
             ...snapshot,
             loading: !0,
             error: void 0
-        }), pending = fetchProjectUsers(client, projectId).then(users => (usersById = new Map(users.flatMap(user => {
+        }), pending = Promise.all([ fetchProjectUsers(client, projectId), loadProjectRolesOrNone({
+            client: client,
+            projectId: projectId
+        }) ]).then(([users, roles]) => (usersById = new Map(users.flatMap(user => {
             const entries = [ [ user.membership.id, user ] ], globalId = user.profile?.sanityUserId;
             return globalId !== void 0 && globalId !== user.membership.id && entries.push([ globalId, user ]), 
             entries;
         })), usersByEmail = new Map(users.flatMap(user => user.profile?.email ? [ [ user.profile.email.toLowerCase(), user ] ] : [])), 
         retryAt = 1 / 0, setSnapshot({
             users: users,
+            roles: roles,
             loading: !1,
             error: void 0
         }), pending = void 0, users), error => {
             throw retryAt = Date.now() + PROJECT_USERS_RETRY_MS, setSnapshot({
                 users: [],
+                roles: [],
                 loading: !1,
                 error: error
             }), pending = void 0, error;
@@ -324,6 +330,7 @@ function studioProjectUserDirectory(client, projectId) {
 
 const missingProjectSnapshot = {
     users: [],
+    roles: [],
     loading: !1,
     error: new Error("No projectId on the Studio client")
 }, noopSubscribe = () => () => {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/workflow-studio",
-  "version": "0.27.0",
+  "version": "0.29.0",
   "description": "React adapter that drives the @sanity/workflow-engine reactive session in Sanity Studio through the App SDK store.",
   "keywords": [
     "sanity",
@@ -50,17 +50,17 @@
     "react-dom": "^19.2.7",
     "sanity": "^6",
     "vitest": "^4.1.8",
-    "@sanity/workflow-react": "0.27.0",
-    "@sanity/workflow-engine": "0.27.0",
-    "@sanity/workflow-sdk": "0.27.0"
+    "@sanity/workflow-engine": "0.29.0",
+    "@sanity/workflow-react": "0.29.0",
+    "@sanity/workflow-sdk": "0.29.0"
   },
   "peerDependencies": {
     "@sanity/sdk": "^2.12.0",
     "react": "^19.2.7",
     "sanity": "^6",
-    "@sanity/workflow-react": "0.27.0",
-    "@sanity/workflow-sdk": "0.27.0",
-    "@sanity/workflow-engine": "0.27.0"
+    "@sanity/workflow-react": "0.29.0",
+    "@sanity/workflow-engine": "0.29.0",
+    "@sanity/workflow-sdk": "0.29.0"
   },
   "engines": {
     "node": ">=20"