@stapel/workspaces-react 0.12.0 → 0.14.0

package/src/i18n/generated/errors.json

@@ -490,6 +490,13 @@
     "remediation": "wait_and_retry",
     "en": "The authentication service is unavailable; try again later"
   },
+  {
+    "code": "error.503.profiles_not_configured",
+    "status": 503,
+    "params": [],
+    "remediation": "contact_support",
+    "en": "This deployment has no profiles service configured, so a display name cannot be written here"
+  },
   {
     "code": "error.503.profiles_unavailable",
     "status": 503,

package/src/i18n/generated/errors.ru.gen.ts

@@ -77,5 +77,6 @@ export const workspacesErrorBundleRu: Record<WorkspacesErrorCode, string> = {
   "error.429.too_many_requests": "Слишком много запросов. Пожалуйста, повторите попытку позже.",
   "error.500.internal": "Что-то пошло не так",
   "error.503.auth_unavailable": "Сервис аутентификации недоступен; повторите попытку позже",
+  "error.503.profiles_not_configured": "В этой инсталляции не настроен сервис профилей — отображаемое имя здесь записать нельзя",
   "error.503.profiles_unavailable": "Сервис профилей недоступен; повторите попытку позже",
 };

package/src/i18n/keys.ts

@@ -12,13 +12,26 @@ import { workspacesErrorBundleEn } from "./generated/errors.gen.js";
  */
 export const WORKSPACES_I18N_KEYS = {
   unknownError: "workspaces.error.unknown",
+  // Retry affordance beside a stated failure — an error a person cannot act
+  // on is only half the message.
+  retry: "workspaces.retry",
   // Workspace list (WorkspaceList headless)
   listLoading: "workspaces.list.loading",
   listEmpty: "workspaces.list.empty",
+  /**
+   * "We could not load your workspaces" — the sentence whose ABSENCE was the
+   * 2026-08-09 incident. Deliberately about US failing to load, never about
+   * the person having none, and never a 404's "no longer available" (which
+   * asserts the thing does not exist — tracker #211).
+   */
+  listLoadFailed: "workspaces.list.load_failed",
   listCreate: "workspaces.list.create",
   listCreating: "workspaces.list.creating",
   // Members (Members headless)
   membersLoading: "workspaces.members.loading",
+  membersEmpty: "workspaces.members.empty",
+  membersLoadFailed: "workspaces.members.load_failed",
+  rolesLoadFailed: "workspaces.roles.load_failed",
   membersInvite: "workspaces.members.invite",
   membersInviting: "workspaces.members.inviting",
   membersUpdateRole: "workspaces.members.update_role",
@@ -34,6 +47,9 @@ export const WORKSPACES_I18N_KEYS = {
   fieldSlug: "workspaces.settings.field.slug",
   fieldType: "workspaces.settings.field.type",
   save: "workspaces.settings.save",
+  // Why a settings control is switched off (core's `useActionGate`).
+  blockedNotOwner: "workspaces.settings.blocked.not_owner",
+  blockedNameRequired: "workspaces.settings.blocked.name_required",
   saving: "workspaces.settings.saving",
   dangerZoneTitle: "workspaces.settings.danger_zone.title",
   deleteWorkspace: "workspaces.settings.danger_zone.delete",
@@ -102,11 +118,18 @@ export const workspacesI18nBundleEn: I18nDictionary = {
 
   // workspaces-react UI
   "workspaces.error.unknown": "Something went wrong. Please try again.",
+  "workspaces.retry": "Try again",
   "workspaces.list.loading": "Loading workspaces…",
   "workspaces.list.empty": "No workspaces yet.",
+  "workspaces.list.load_failed":
+    "We could not load your workspaces. This is a problem on our side, not a sign that you have none.",
   "workspaces.list.create": "Create workspace",
   "workspaces.list.creating": "Creating…",
   "workspaces.members.loading": "Loading members…",
+  "workspaces.members.empty": "No members yet.",
+  "workspaces.members.load_failed": "We could not load the member list.",
+  "workspaces.roles.load_failed":
+    "We could not load the role list, so the role picker is empty. It is not a workspace without roles.",
   "workspaces.members.invite": "Invite",
   "workspaces.members.inviting": "Inviting…",
   "workspaces.members.update_role": "Change role",
@@ -120,6 +143,9 @@ export const workspacesI18nBundleEn: I18nDictionary = {
   "workspaces.settings.field.slug": "URL slug",
   "workspaces.settings.field.type": "Type",
   "workspaces.settings.save": "Save changes",
+  "workspaces.settings.blocked.not_owner":
+    "Only the workspace owner can change these settings.",
+  "workspaces.settings.blocked.name_required": "Enter a workspace name.",
   "workspaces.settings.saving": "Saving…",
   "workspaces.settings.danger_zone.title": "Danger zone",
   "workspaces.settings.danger_zone.delete": "Delete workspace",

package/src/i18n/ru.ts

@@ -25,11 +25,18 @@ export const workspacesI18nBundleRu: I18nDictionary = {
 
   // workspaces-react UI (hand-written ru mirror of the en copy in keys.ts)
   "workspaces.error.unknown": "Что-то пошло не так. Попробуйте ещё раз.",
+  "workspaces.retry": "Попробовать снова",
   "workspaces.list.loading": "Загрузка рабочих пространств…",
   "workspaces.list.empty": "Пока нет рабочих пространств.",
+  "workspaces.list.load_failed":
+    "Не удалось загрузить ваши рабочие пространства. Это сбой на нашей стороне, а не признак того, что их у вас нет.",
   "workspaces.list.create": "Создать рабочее пространство",
   "workspaces.list.creating": "Создание…",
   "workspaces.members.loading": "Загрузка участников…",
+  "workspaces.members.empty": "Пока нет участников.",
+  "workspaces.members.load_failed": "Не удалось загрузить список участников.",
+  "workspaces.roles.load_failed":
+    "Не удалось загрузить список ролей, поэтому выбор роли пуст. Это не рабочее пространство без ролей.",
   "workspaces.members.invite": "Пригласить",
   "workspaces.members.inviting": "Приглашение…",
   "workspaces.members.update_role": "Изменить роль",
@@ -43,6 +50,9 @@ export const workspacesI18nBundleRu: I18nDictionary = {
   "workspaces.settings.field.slug": "URL-идентификатор",
   "workspaces.settings.field.type": "Тип",
   "workspaces.settings.save": "Сохранить изменения",
+  "workspaces.settings.blocked.not_owner":
+    "Менять эти настройки может только владелец рабочего пространства.",
+  "workspaces.settings.blocked.name_required": "Введите название рабочего пространства.",
   "workspaces.settings.saving": "Сохранение…",
   "workspaces.settings.danger_zone.title": "Опасная зона",
   "workspaces.settings.danger_zone.delete": "Удалить рабочее пространство",

package/src/model/queries.ts

@@ -4,8 +4,8 @@ import type {
   UseInfiniteQueryResult,
   UseQueryResult,
 } from "@tanstack/react-query";
-import { useActiveSessionReady } from "@stapel/core";
-import type { StapelApiError } from "@stapel/core";
+import { loadStateFromQuery, mapLoad, useActiveSessionReady } from "@stapel/core";
+import type { LoadState, StapelApiError } from "@stapel/core";
 import type {
   InvitationPage,
   InvitationPreview,
@@ -223,15 +223,21 @@ export function useInvitationPreview(
 /** What {@link useCapabilities} returns: the caller's granted capability
  * strings in one workspace plus the wildcard-aware `can()` check. */
 export interface CapabilitiesResult {
-  /** Verbatim registry strings of the caller's role (wildcards included);
-   * empty while loading or when the caller is not a member. */
-  readonly capabilities: readonly string[];
+  /**
+   * The capability read, as a state. `ready` with the verbatim registry
+   * strings of the caller's role (wildcards included; `[]` for a non-member,
+   * and for a backend older than 0.6.0 which does not send the field at all).
+   *
+   * A state and not an array, because "you may not do this" and "we could not
+   * find out whether you may" both end in a hidden button, and only one of
+   * them should end in silence. `can()` stays deny-by-default in both — that
+   * part is a security property and does not change — but a screen that wants
+   * to SAY why can now tell them apart.
+   */
+  readonly state: LoadState<readonly string[]>;
   /** Wildcard-aware check (`*` / `prefix.*` — the backend matcher, ported).
    * UI convenience only: the backend re-checks on every operation. */
   can(capability: string): boolean;
-  readonly isLoading: boolean;
-  readonly isError: boolean;
-  readonly error: StapelApiError | null;
 }
 
 /**
@@ -243,13 +249,17 @@ export interface CapabilitiesResult {
  */
 export function useCapabilities(workspaceId: string | null): CapabilitiesResult {
   const query = useWorkspace(workspaceId);
-  const capabilities = query.data?.my_capabilities ?? [];
+  // `my_capabilities` is additive since stapel-workspaces 0.6.0, so a
+  // SUCCESSFUL read against an older backend legitimately carries none. That
+  // is an empty grant, not a failed load, and the two must not merge.
+  const state = mapLoad(
+    loadStateFromQuery(query),
+    (workspace) => workspace.my_capabilities ?? []
+  );
   return {
-    capabilities,
-    can: (capability) => hasCapability(capabilities, capability),
-    isLoading: query.isLoading,
-    isError: query.isError,
-    error: query.error ?? null,
+    state,
+    can: (capability) =>
+      state.status === "ready" && hasCapability(state.data, capability),
   };
 }
 
@@ -299,7 +309,7 @@ export function useCapabilityGate(
   workspaceId: string | null,
   capability: string
 ): CapabilityGate {
-  const { can, isLoading } = useCapabilities(workspaceId);
+  const { can, state } = useCapabilities(workspaceId);
   const level = capabilityLevel(capability);
   return {
     capability,
@@ -307,6 +317,6 @@ export function useCapabilityGate(
     level,
     requiresStepUp: level === "high",
     stepUpScope: level === "high" ? SENSITIVE_SCOPE : null,
-    isLoading,
+    isLoading: state.status === "loading",
   };
 }

package/src/model/selection.tsx

@@ -8,8 +8,15 @@ import {
   useState,
 } from "react";
 import type { Context, ReactElement, ReactNode } from "react";
-import { createRepository } from "@stapel/core";
-import type { Repository } from "@stapel/core";
+import {
+  bothLoaded,
+  createRepository,
+  loadLoading,
+  loadReady,
+  loadStateFromQuery,
+  mapLoad,
+} from "@stapel/core";
+import type { LoadState, Repository } from "@stapel/core";
 import type { Workspace } from "../api/types.js";
 import { useWorkspaces } from "./queries.js";
 import { useSetPreferredWorkspace } from "./mutations.js";
@@ -96,11 +103,26 @@ export interface WorkspaceSelectionUrlBinding {
 
 /** What {@link useWorkspaceSelection} hands back. */
 export interface WorkspaceSelection {
-  /** The caller's workspaces (empty before load, and for a guest). */
-  readonly workspaces: readonly Workspace[];
   /**
-   * The resolved workspace — `null` while loading, and for a person who
-   * belongs to none.
+   * The workspace list, as a state a host cannot flatten: `loading` / `ready`
+   * with the rows / `failed` with the error. Render it through core's
+   * `matchList`.
+   *
+   * THIS FIELD IS THE FIX FOR THE 2026-08-09 INCIDENT. What used to be here
+   * was `workspaces: readonly Workspace[]` beside `loading: boolean`, and NO
+   * error field at all — so when the list endpoint answered 404 (a route
+   * mounted one segment too deep), a host saw `loading: false`, `workspaces:
+   * []`, `current: null`, and had literally no way to tell that apart from a
+   * person who belongs to no workspace. Every screen in the product said "you
+   * have no workspaces" for hours. The distinction was not merely easy to
+   * miss; it was ABSENT from the type.
+   */
+  readonly state: LoadState<readonly Workspace[]>;
+  /**
+   * The resolved workspace, once the list is `ready` and the chain has picked
+   * one. `null` while loading, when the load FAILED, and for a person who
+   * belongs to none — which is exactly why a screen must branch on
+   * {@link state} and not on this being null.
    *
    * Downstream fetching must gate on THIS, never on a raw id: an id that has
    * not been checked against the fetched list is exactly how a client ends up
@@ -116,8 +138,6 @@ export interface WorkspaceSelection {
    * this. The person has already been landed somewhere sane.
    */
   readonly urlWorkspaceInvalid: boolean;
-  /** The workspace list is still loading. */
-  readonly loading: boolean;
   /**
    * An EXPLICIT choice by the person — the only entry point that persists.
    * Writes the URL (push), local storage, and the backend preference.
@@ -128,6 +148,10 @@ export interface WorkspaceSelection {
   refetch: () => Promise<void>;
 }
 
+/** Stable identity for the no-rows case — a fresh `[]` per render would
+ * re-run every consumer effect that depends on the memoised bag (#251). */
+const EMPTY_WORKSPACES: readonly Workspace[] = [];
+
 const SelectionContext: Context<WorkspaceSelection | null> =
   createContext<WorkspaceSelection | null>(null);
 
@@ -227,11 +251,38 @@ export function WorkspaceSelectionProvider(
     };
   }, [repo]);
 
-  const workspaces = useMemo(
-    () => query.data?.workspaces ?? [],
-    [query.data]
+  // The list read and the local-storage read must BOTH land before the chain
+  // can answer, and a failure of either must not read as "still loading" —
+  // `bothLoaded` is exactly that rule, so it is not restated here.
+  // Memoised on the query's OWN fields, never on the query object: TanStack
+  // returns a new result object every render, so `[query]` here would hand
+  // every consumer a new `state` on every render — the #251 loop the bag
+  // memoisation below exists to prevent, reintroduced one level up.
+  const { status: queryStatus, data: queryData, error: queryError } = query;
+  const state = useMemo<LoadState<readonly Workspace[]>>(
+    () =>
+      mapLoad(
+        bothLoaded(
+          mapLoad(
+            loadStateFromQuery({
+              status: queryStatus,
+              data: queryData,
+              error: queryError,
+            }),
+            (list) => list.workspaces ?? []
+          ),
+          localRead ? loadReady(null) : loadLoading()
+        ),
+        ([rows]) => rows
+      ),
+    [queryStatus, queryData, queryError, localRead]
   );
-  const loading = query.isLoading || !localRead;
+
+  // The resolution chain below is a COMPUTATION over rows, not a rendering of
+  // them, so it reads the rows flat — and it runs only when the state is
+  // `ready`, which is what keeps a failed load from resolving to anything.
+  const workspaces = state.status === "ready" ? state.data : EMPTY_WORKSPACES;
+  const resolvable = state.status === "ready";
 
   const memberOf = useCallback(
     (id: string | null | undefined): Workspace | null =>
@@ -246,7 +297,7 @@ export function WorkspaceSelectionProvider(
     workspace: Workspace | null;
     source: WorkspaceSelectionSource | null;
   }>(() => {
-    if (loading || workspaces.length === 0) {
+    if (!resolvable || workspaces.length === 0) {
       return { workspace: null, source: null };
     }
     const explicit = memberOf(chosenId);
@@ -266,7 +317,7 @@ export function WorkspaceSelectionProvider(
     // Last resort only — see this module's header for why it is last and why
     // it is still here.
     return { workspace: workspaces[0] ?? null, source: "positional" };
-  }, [loading, workspaces, memberOf, chosenId, urlWorkspaceId, localId, query.data]);
+  }, [resolvable, workspaces, memberOf, chosenId, urlWorkspaceId, localId, query.data]);
 
   // The URL named something the person cannot open. Deliberately NOT an
   // error state that blanks the screen, and deliberately NOT a silent
@@ -274,7 +325,7 @@ export function WorkspaceSelectionProvider(
   // showing workspace Y's data is the same misattribution class as #239.
   // They land through the rest of the chain, and this flag drives the notice.
   const urlWorkspaceInvalid =
-    !loading &&
+    resolvable &&
     workspaces.length > 0 &&
     chosenId === null &&
     !!urlWorkspaceId &&
@@ -298,11 +349,14 @@ export function WorkspaceSelectionProvider(
   // later-corrected backend preference or instance default; deleting it just
   // stops the next boot retrying a dead id.
   useEffect(() => {
-    if (loading || !repo || localId === null) return;
+    // Only a SUCCESSFUL load proves a stored id is dead. Deleting it because
+    // the request failed would punish an outage by forgetting the person's
+    // workspace on every affected boot.
+    if (!resolvable || !repo || localId === null) return;
     if (memberOf(localId)) return;
     setLocalId(null);
     void repo.del(REPO_KEY).catch(() => undefined);
-  }, [loading, repo, localId, memberOf]);
+  }, [resolvable, repo, localId, memberOf]);
 
   /**
    * The only path that persists anything, and that is the whole write policy:
@@ -349,20 +403,18 @@ export function WorkspaceSelectionProvider(
   // spinner that never resolves, with nothing in the console.
   const value = useMemo<WorkspaceSelection>(
     () => ({
-      workspaces,
+      state,
       current: resolved.workspace,
       source: resolved.source,
       urlWorkspaceInvalid,
-      loading,
       switchTo,
       refetch,
     }),
     [
-      workspaces,
+      state,
       resolved.workspace,
       resolved.source,
       urlWorkspaceInvalid,
-      loading,
       switchTo,
       refetch,
     ]