@sanity/workflow-studio 0.26.0 → 0.28.0

package/CHANGELOG.md

@@ -1,5 +1,94 @@
 # @sanity/workflow-studio
 
+## 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
+
+- 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.
+
+### Patch Changes
+
+- Updated dependencies [780cf93]
+- Updated dependencies [b7c8bed]
+  - @sanity/workflow-engine@0.27.0
+  - @sanity/workflow-sdk@0.27.0
+  - @sanity/workflow-react@0.27.0
+
 ## 0.26.0
 
 ### Patch 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

@@ -194,11 +194,11 @@ function isRecord(value) {
 }
 
 function isRole(value) {
-    return isRecord(value) && typeof value.name == "string";
+    return isRecord(value) && typeof value.name == "string" && (value.title === void 0 || typeof value.title == "string");
 }
 
 function isMembership(value) {
-    return isRecord(value) && typeof value.id == "string" && (value.isRobot === void 0 || typeof value.isRobot == "boolean") && (value.roles === void 0 || Array.isArray(value.roles) && value.roles.every(isRole));
+    return isRecord(value) && typeof value.id == "string" && (value.isRobot === void 0 || typeof value.isRobot == "boolean") && (value.isCurrentUser === void 0 || typeof value.isCurrentUser == "boolean") && (value.roles === void 0 || Array.isArray(value.roles) && value.roles.every(isRole));
 }
 
 async function fetchProjectUsers(client, projectId) {
@@ -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";
@@ -39,8 +40,10 @@ export declare interface StudioObserverOptions {
 export declare interface StudioProjectMembership {
   readonly id: string;
   readonly isRobot?: boolean;
+  readonly isCurrentUser?: boolean;
   readonly roles?: readonly {
     readonly name: string;
+    readonly title?: string;
   }[];
   readonly [key: string]: unknown;
 }
@@ -59,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";
@@ -39,8 +40,10 @@ export declare interface StudioObserverOptions {
 export declare interface StudioProjectMembership {
   readonly id: string;
   readonly isRobot?: boolean;
+  readonly isCurrentUser?: boolean;
   readonly roles?: readonly {
     readonly name: string;
+    readonly title?: string;
   }[];
   readonly [key: string]: unknown;
 }
@@ -59,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;
@@ -202,11 +202,11 @@ function isRecord(value) {
 }
 
 function isRole(value) {
-    return isRecord(value) && typeof value.name == "string";
+    return isRecord(value) && typeof value.name == "string" && (value.title === void 0 || typeof value.title == "string");
 }
 
 function isMembership(value) {
-    return isRecord(value) && typeof value.id == "string" && (value.isRobot === void 0 || typeof value.isRobot == "boolean") && (value.roles === void 0 || Array.isArray(value.roles) && value.roles.every(isRole));
+    return isRecord(value) && typeof value.id == "string" && (value.isRobot === void 0 || typeof value.isRobot == "boolean") && (value.isCurrentUser === void 0 || typeof value.isCurrentUser == "boolean") && (value.roles === void 0 || Array.isArray(value.roles) && value.roles.every(isRole));
 }
 
 async function fetchProjectUsers(client, projectId) {
@@ -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.26.0",
+  "version": "0.28.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-engine": "0.26.0",
-    "@sanity/workflow-sdk": "0.26.0",
-    "@sanity/workflow-react": "0.26.0"
+    "@sanity/workflow-engine": "0.28.0",
+    "@sanity/workflow-react": "0.28.0",
+    "@sanity/workflow-sdk": "0.28.0"
   },
   "peerDependencies": {
     "@sanity/sdk": "^2.12.0",
     "react": "^19.2.7",
     "sanity": "^6",
-    "@sanity/workflow-react": "0.26.0",
-    "@sanity/workflow-engine": "0.26.0",
-    "@sanity/workflow-sdk": "0.26.0"
+    "@sanity/workflow-engine": "0.28.0",
+    "@sanity/workflow-react": "0.28.0",
+    "@sanity/workflow-sdk": "0.28.0"
   },
   "engines": {
     "node": ">=20"