@jini-ai/user-management 0.3.3 → 0.6.10

package/dist/react/users/UserRowParts.d.ts

@@ -0,0 +1,53 @@
+import type { ReactNode } from "react";
+import type { RowMenuItem } from "@jini-ai/admin/react";
+import type { Translate } from "@jini-ai/ui/panel-kit";
+import type { AdminIdentityUser, AdminPolicy, AdminRole } from "../models.js";
+import type { UserRowActionsController } from "./Users.js";
+/**
+ * @file The cells and menu-item wiring of `Users.tsx`'s `UserRow`, split out of it in the
+ * complexity-ceiling pass (lot L182a): `UserRow` scored cyclomatic 16 with every cell's own
+ * fallback (`isOwn`, the status/role `renderServerLabel ?? …` chains, the two "none" placeholders,
+ * the rename/capability optional calls) counted against the row itself. Each piece below now owns
+ * its own branches; the markup each one renders is exactly what `UserRow` rendered inline before.
+ */
+type ServerLabelRenderer = ((required: {
+    value: string;
+}) => ReactNode) | undefined;
+export interface UserNameCellProps {
+    user: AdminIdentityUser;
+    isOwn: boolean | undefined;
+    expanded: boolean;
+    onToggle: (user: AdminIdentityUser) => void;
+    agentBase: string;
+    t: (key: string) => string;
+}
+/** The username cell: the Manage toggle button plus the "(you)" marker on the caller's own row. */
+export declare function UserNameCell({ user, isOwn, expanded, onToggle, agentBase, t }: UserNameCellProps): import("react").JSX.Element;
+export interface UserStatusCellProps {
+    status: AdminIdentityUser["status"];
+    t: (key: string) => string;
+    renderServerLabel: ServerLabelRenderer;
+}
+/** The status badge cell — the host's `renderServerLabel` wins, falling back to `t(status)`. */
+export declare function UserStatusCell({ status, t, renderServerLabel }: UserStatusCellProps): import("react").JSX.Element;
+export interface UserGrantCellsProps {
+    user: AdminIdentityUser;
+    roleById: ReadonlyMap<string, AdminRole>;
+    policyById: ReadonlyMap<string, AdminPolicy>;
+    t: (key: string) => string;
+    translate: Translate;
+    renderServerLabel: ServerLabelRenderer;
+}
+/** The Roles and Policies cells, each a joined label or a muted "none". As before the split, only
+ *  the role label is offered to `renderServerLabel`; the policy label renders as-is. */
+export declare function UserGrantCells({ user, roleById, policyById, t, translate, renderServerLabel }: UserGrantCellsProps): import("react").JSX.Element;
+/** `rules.ts`'s `userRowMenuItems`, wired to one row's {@link UserRowActionsController}. The
+ *  `?? actions.canDelete` capability fallback is a permission default for a controller with no
+ *  per-row `rowCapabilities` — kept, not "simplified away" (the server stays the real boundary). */
+export declare function userRowMenuItemsFor({ user, actions, translate }: {
+    user: AdminIdentityUser;
+    actions: UserRowActionsController;
+    translate: Translate;
+}): RowMenuItem[];
+export {};
+//# sourceMappingURL=UserRowParts.d.ts.map

package/dist/react/users/UserRowParts.js

@@ -0,0 +1,39 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { agentHandle } from "@jini-ai/agentic";
+import { formatGrantLabel, userRowMenuItems } from "./rules.js";
+/** The username cell: the Manage toggle button plus the "(you)" marker on the caller's own row. */
+export function UserNameCell({ user, isOwn, expanded, onToggle, agentBase, t }) {
+    return (_jsxs("td", { children: [_jsx("button", { type: "button", className: "link-button", onClick: () => onToggle(user), "aria-expanded": expanded, ...agentHandle({ handle: `${agentBase}-manage` }, {
+                    role: "button",
+                    label: "Open this user's Manage panel — edit email, assign a role, attach a policy",
+                }), children: user.username }), isOwn ? _jsx("span", { style: { color: "var(--jini-text-secondary)", fontSize: "inherit", fontWeight: 400, marginInlineStart: "0.35em" }, children: t("(you)") }) : null] }));
+}
+/** The status badge cell — the host's `renderServerLabel` wins, falling back to `t(status)`. */
+export function UserStatusCell({ status, t, renderServerLabel }) {
+    return (_jsx("td", { children: _jsx("span", { className: `status status-${status}`, children: renderServerLabel?.({ value: status }) ?? t(status) }) }));
+}
+/** The Roles and Policies cells, each a joined label or a muted "none". As before the split, only
+ *  the role label is offered to `renderServerLabel`; the policy label renders as-is. */
+export function UserGrantCells({ user, roleById, policyById, t, translate, renderServerLabel }) {
+    const roleLabel = formatGrantLabel({ ids: user.roleIds, byId: roleById, translate });
+    const policyLabel = formatGrantLabel({ ids: user.policyIds, byId: policyById });
+    return (_jsxs(_Fragment, { children: [_jsx("td", { children: roleLabel !== null ? (renderServerLabel?.({ value: roleLabel }) ?? roleLabel) : _jsx("span", { className: "muted-cell", children: t("none") }) }), _jsx("td", { children: policyLabel !== null ? policyLabel : _jsx("span", { className: "muted-cell", children: t("none") }) })] }));
+}
+/** `rules.ts`'s `userRowMenuItems`, wired to one row's {@link UserRowActionsController}. The
+ *  `?? actions.canDelete` capability fallback is a permission default for a controller with no
+ *  per-row `rowCapabilities` — kept, not "simplified away" (the server stays the real boundary). */
+export function userRowMenuItemsFor({ user, actions, translate }) {
+    return userRowMenuItems({
+        user, toggleSaving: actions.savingId === user.principalId,
+        handlers: {
+            onRequestDisable: actions.requestDisable,
+            onEnable: (u) => void actions.toggleStatus(u),
+            onManage: actions.toggleExpanded,
+            onResetPassword: actions.openResetPassword,
+            onChangeUsername: actions.renameUserHandler?.({ user }),
+            onRequestDelete: actions.requestDelete,
+        }, translate, canDelete: actions.canDelete,
+        capabilities: actions.rowCapabilities?.(user) ?? actions.canDelete,
+    });
+}
+//# sourceMappingURL=UserRowParts.js.map

package/dist/react/users/Users.d.ts

@@ -44,6 +44,11 @@ import type { Translate } from "@jini-ai/ui/panel-kit";
  * full-render tests these were extracted underneath (unchanged), plus new
  * `__tests__/users-components.unit.test.tsx` for direct component-level tests of each piece.
  *
+ * Second complexity pass (lot L182a): `UserRow` was back at cyclomatic 16 and `Users` at 11. The
+ * row's cells and its menu-item wiring moved to `UserRowParts.tsx` (`UserNameCell`,
+ * `UserStatusCell`, `UserGrantCells`, `userRowMenuItemsFor`), and the Manage panel's controller
+ * assembly moved out of `Users`' JSX into `userManageController` below. Markup is unchanged.
+ *
  * Reset-password confirm + reveal (typo-catching pass): `UserResetPasswordDialog` gained a second
  * field ("Confirm new password") and an independent show/hide toggle per field, both driven by the
  * new `hooks/use-reset-password-fields.hooks.ts` (confirm-field state and both reveal flags are
@@ -55,13 +60,35 @@ import type { Translate } from "@jini-ai/ui/panel-kit";
  * is the shared field+toggle shape both new inputs use, following this file's own `GrantSelect`
  * precedent for a shape used twice.
  */
-export interface UsersProps extends UsersDependencies, UsersOptions {
-    useUsersHook?: typeof useUsers | undefined;
+/**
+ * What a host-supplied `useUsersHook` is called with: `useUsers`' own inputs, except that `translate`
+ * may be absent. `Users` reads its copy from the controller the hook returns (`controller.translate`),
+ * never from this prop, so a host hook that builds its own controller has no use for it.
+ */
+export type UsersHookDependencies = Omit<UsersDependencies, "translate"> & {
+    translate?: Translate | undefined;
+};
+/** A host replacement for {@link useUsers} that does not need `translate` (see {@link UsersHookDependencies}). */
+export type UsersHook = (dependencies: UsersHookDependencies, options?: UsersOptions) => UsersController;
+/** Every `Users` prop except the hook/`translate` pair (see {@link UsersProps}). */
+export interface UsersBaseProps extends Omit<UsersDependencies, "translate">, UsersOptions {
     /** The host owns localization of protocol status/role labels. */
     renderServerLabel?: ((required: {
         value: string;
     }) => ReactNode) | undefined;
 }
+/**
+ * `translate` is only ever forwarded to the hook, so it is required exactly when the default
+ * {@link useUsers} (or a hook typed like it) runs, and optional when the host supplies a
+ * {@link UsersHook} that does not read it — instead of a dead `translate={key => key}` stub.
+ */
+export type UsersProps = UsersBaseProps & ({
+    useUsersHook?: typeof useUsers | undefined;
+    translate: Translate;
+} | {
+    useUsersHook: UsersHook;
+    translate?: Translate | undefined;
+});
 /** The subset of `AdminRole`/`AdminPolicy` a grant `<select>` actually renders. Named rather than
  *  taking the full records, so the shared control below cannot come to depend on anything a role has
  *  and a policy does not. */
@@ -139,6 +166,7 @@ export interface UserRowActionsController {
 }
 export interface UserRowProps {
     user: AdminIdentityUser;
+    isOwn?: boolean;
     roleById: ReadonlyMap<string, AdminRole>;
     policyById: ReadonlyMap<string, AdminPolicy>;
     /** Whether the Roles/Policies cells render — see {@link UsersTableProps.showGrants}. */
@@ -155,6 +183,7 @@ export interface UserRowProps {
 }
 export interface UsersTableProps {
     users: AdminIdentityUser[];
+    ownPrincipalId?: string | undefined;
     /** The full records, for the Roles/Policies label columns. The grant selects get their own
      *  `options` through `manage`, so neither consumer has to reach into the other's props. */
     roles: AdminRole[];

package/dist/react/users/Users.js

@@ -1,9 +1,10 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-import { Fragment } from "react";
+import {} from "react";
 import { RowMenu, ConfirmDialog } from "@jini-ai/admin/react";
 import { agentHandle } from "@jini-ai/agentic";
 import { buildAgentListHandles } from "@jini-ai/ui/panel-kit";
-import { formatGrantLabel, grantOptionLabel, userRowMenuItems, isOwnerAccount } from "./rules.js";
+import { grantOptionLabel } from "./rules.js";
+import { UserGrantCells, UserNameCell, UserStatusCell, userRowMenuItemsFor } from "./UserRowParts.js";
 import { useUsers } from "./hooks/use-users.hooks.js";
 import { InfoTip } from "@jini-ai/ui/admin-widgets";
 import { useResetPasswordFields } from "./hooks/use-reset-password-fields.hooks.js";
@@ -31,28 +32,13 @@ export function UserManagePanel({ principalId, manage, t, colSpan = 6 }) {
 }
 /** One user's row plus its optional expanded "Manage" row. `key` lives on the `<UserRow>` element at
  *  the call site, not inside here, since this is no longer the array-mapping callback itself. */
-function UserRow({ user, roleById, policyById, showGrants, actions, manage, agentBase, t, translate, renderServerLabel }) {
-    const roleLabel = formatGrantLabel({ ids: user.roleIds, byId: roleById, translate });
-    const policyLabel = formatGrantLabel({ ids: user.policyIds, byId: policyById });
-    return (_jsxs(_Fragment, { children: [_jsxs("tr", { children: [_jsxs("td", { children: [_jsx("button", { type: "button", className: "link-button", onClick: () => actions.toggleExpanded(user), "aria-expanded": actions.expandedId === user.principalId, ...agentHandle({ handle: `${agentBase}-manage` }, {
-                                    role: "button",
-                                    label: "Open this user's Manage panel — edit email, assign a role, attach a policy",
-                                }), children: user.username }), isOwnerAccount({ user, roles: roleById }) ? _jsx("span", { className: "status", children: t("Owner") }) : null] }), _jsx("td", { children: user.email ?? _jsx("span", { className: "muted-cell", children: "\u2014" }) }), _jsx("td", { children: _jsx("span", { className: `status status-${user.status}`, children: renderServerLabel?.({ value: user.status }) ?? t(user.status) }) }), showGrants ? (_jsxs(_Fragment, { children: [_jsx("td", { children: roleLabel !== null ? (renderServerLabel?.({ value: roleLabel }) ?? roleLabel) : _jsx("span", { className: "muted-cell", children: t("none") }) }), _jsx("td", { children: policyLabel !== null ? policyLabel : _jsx("span", { className: "muted-cell", children: t("none") }) })] })) : null, _jsx("td", { children: _jsx(RowMenu, { triggerLabel: `${t("Actions for user")} "${user.username}"`, agentHandle: `${agentBase}-menu`, items: userRowMenuItems({
-                                user, toggleSaving: actions.savingId === user.principalId,
-                                handlers: {
-                                    onRequestDisable: actions.requestDisable,
-                                    onEnable: (u) => void actions.toggleStatus(u),
-                                    onManage: actions.toggleExpanded,
-                                    onResetPassword: actions.openResetPassword,
-                                    onChangeUsername: actions.renameUserHandler?.({ user }),
-                                    onRequestDelete: actions.requestDelete,
-                                }, translate, canDelete: actions.canDelete,
-                                capabilities: actions.rowCapabilities?.(user) ?? actions.canDelete,
-                            }) }) })] }), actions.expandedId === user.principalId ? (_jsx(UserManagePanel, { principalId: user.principalId, manage: manage, t: t, colSpan: showGrants ? 6 : 4 })) : null] }));
+function UserRow({ user, isOwn, roleById, policyById, showGrants, actions, manage, agentBase, t, translate, renderServerLabel }) {
+    const expanded = actions.expandedId === user.principalId;
+    return (_jsxs(_Fragment, { children: [_jsxs("tr", { "aria-current": isOwn ? "true" : undefined, children: [_jsx(UserNameCell, { user: user, isOwn: isOwn, expanded: expanded, onToggle: actions.toggleExpanded, agentBase: agentBase, t: t }), _jsx("td", { children: user.email ?? _jsx("span", { className: "muted-cell", children: "\u2014" }) }), _jsx(UserStatusCell, { status: user.status, t: t, renderServerLabel: renderServerLabel }), showGrants ? (_jsx(UserGrantCells, { user: user, roleById: roleById, policyById: policyById, t: t, translate: translate, renderServerLabel: renderServerLabel })) : null, _jsx("td", { children: _jsx(RowMenu, { triggerLabel: `${t("Actions for user")} "${user.username}"`, agentHandle: `${agentBase}-menu`, items: userRowMenuItemsFor({ user, actions, translate }) }) })] }), expanded ? (_jsx(UserManagePanel, { principalId: user.principalId, manage: manage, t: t, colSpan: showGrants ? 6 : 4 })) : null] }));
 }
 /** The users table, or the empty state. Builds the role/policy lookup maps once per render rather
  *  than once per row. */
-function UsersTable({ users, roles, policies, showGrants, actions, manage, t, translate, renderServerLabel }) {
+function UsersTable({ users, ownPrincipalId, roles, policies, showGrants, actions, manage, t, translate, renderServerLabel }) {
     if (users.length === 0) {
         return (_jsx("div", { className: "card", children: _jsxs("div", { className: "empty-state", children: [_jsx("p", { children: t("No users yet.") }), _jsx("p", { className: "page-description", children: t("Create your first operator account to get started.") })] }) }));
     }
@@ -66,7 +52,12 @@ function UsersTable({ users, roles, policies, showGrants, actions, manage, t, tr
     // Principal ids are stable and unique, so they disambiguate one row's Manage toggle from
     // another's — same reasoning as every other list on this workstream.
     const rowHandles = buildAgentListHandles({ prefix: "users-row", ids: users.map((user) => user.principalId) });
-    return (_jsx("div", { className: "table-scroll", children: _jsxs("table", { className: "list-table", children: [_jsx("thead", { children: _jsxs("tr", { children: [_jsx("th", { children: t("Username") }), _jsx("th", { children: t("Email") }), _jsx("th", { children: t("Status") }), showGrants ? (_jsxs(_Fragment, { children: [_jsx("th", { children: t("Roles") }), _jsx("th", { children: t("Policies") })] })) : null, _jsx("th", { children: t("More") })] }) }), _jsx("tbody", { children: users.map((user, index) => (_jsx(Fragment, { children: _jsx(UserRow, { user: user, roleById: roleById, policyById: policyById, showGrants: showGrants, actions: actions, manage: manage, agentBase: rowHandles[index], t: t, translate: translate, renderServerLabel: renderServerLabel }) }, user.principalId))) })] }) }));
+    return (_jsx("div", { className: "table-scroll", children: _jsxs("table", { className: "list-table", children: [_jsx("thead", { children: _jsxs("tr", { children: [_jsx("th", { children: t("Username") }), _jsx("th", { children: t("Email") }), _jsx("th", { children: t("Status") }), showGrants ? (_jsxs(_Fragment, { children: [_jsxs("th", { "data-label": t("Roles"), children: [t("Roles"), _jsx(InfoTip, { triggerLabel: t("About roles"), label: [
+                                                    t("• Owner — full control, including users and site keys."),
+                                                    t("• Admin — manage content, settings, site keys, and roles within their permissions."),
+                                                    t("• Editor — edit, publish, and delete content; upload, edit, and trash media; switch themes."),
+                                                    t("• Viewer — read content, changes, and plugin information."),
+                                                ].join("\n") })] }), _jsx("th", { children: t("Policies") })] })) : null, _jsx("th", { children: t("More") })] }) }), _jsx("tbody", { children: users.map((user, index) => (_jsx(UserRow, { user: user, isOwn: user.principalId === ownPrincipalId, roleById: roleById, policyById: policyById, showGrants: showGrants, actions: actions, manage: manage, agentBase: rowHandles[index], t: t, translate: translate, renderServerLabel: renderServerLabel }, user.principalId))) })] }) }));
 }
 /** The Disable confirm dialog — extracted from `Users` verbatim. */
 function UserDisableDialog({ confirmingDisable, setConfirmingDisable, toggleSavingId, confirmDisable, t }) {
@@ -160,15 +151,39 @@ function UsersPageHeader({ formOpen, setFormOpen, t }) {
 function UsersNotices({ toggleError, notice }) {
     return (_jsxs(_Fragment, { children: [toggleError ? _jsx("div", { className: "notice error", children: toggleError }) : null, notice ? _jsx("div", { className: "notice", children: notice }) : null] }));
 }
-export function Users({ useUsersHook = useUsers, port, translate: injectedTranslate, queryScope, openOwnPasswordReset, onOwnPasswordResetClosed, passwordResetNotice, renderServerLabel }) {
-    const { users, roles, policies, canGrant, error, formOpen, setFormOpen, username, setUsername, email, setEmail, password, setPassword, saving, formError, onCreate, expandedId, toggleExpanded, pendingRoleId, setPendingRoleId, pendingPolicyId, setPendingPolicyId, grantSaving, grantError, onAssignRole, onAttachPolicy, editEmail, setEditEmail, emailSaving, onSaveEmail, toggleSavingId, toggleError, notice, confirmingDisable, setConfirmingDisable, requestDisable, confirmDisable, onToggleStatus, resetPasswordFor, setResetPasswordFor, newPassword, setNewPassword, passwordSaving, passwordError, setPasswordError, openResetPassword, confirmResetPassword, canManageUserTrash, rowCapabilities, ownProfile, canRenameOwnProfile, openOwnRename, renameUserHandler, changeUsername, confirmingDelete, setConfirmingDelete, requestDelete, deleteSaving, confirmDelete, t, translate, } = useUsersHook({ port, translate: injectedTranslate, queryScope }, {
+/** Assembles the expanded "Manage" panel's {@link UserManageController} from the screen-wide
+ *  controller — extracted from `Users`' JSX in the complexity-ceiling pass (lot L182a) so its two
+ *  `canGrant` ternaries count against this function, not `Users`. `roles`/`policies` are the
+ *  already-loaded (non-null) lists `Users` narrowed before rendering the table. Without `canGrant`
+ *  both grants are `null`, so the panel renders no grant controls. */
+function userManageController({ controller, roles, policies }) {
+    const { canGrant } = controller;
+    return {
+        error: controller.grantError,
+        saving: controller.grantSaving,
+        email: { value: controller.editEmail, set: controller.setEditEmail, saving: controller.emailSaving, save: controller.onSaveEmail },
+        roleGrant: canGrant
+            ? { options: roles, pendingId: controller.pendingRoleId, setPendingId: controller.setPendingRoleId, submit: controller.onAssignRole }
+            : null,
+        policyGrant: canGrant
+            ? { options: policies, pendingId: controller.pendingPolicyId, setPendingId: controller.setPendingPolicyId, submit: controller.onAttachPolicy }
+            : null,
+    };
+}
+export function Users({ useUsersHook, port, translate: injectedTranslate, queryScope, openOwnPasswordReset, onOwnPasswordResetClosed, passwordResetNotice, renderServerLabel }) {
+    // Widening `useUsers` to `UsersHook` is sound only through the `UsersProps` union: whenever
+    // `useUsersHook` is omitted or typed as `useUsers`, `translate` is required, so the default hook
+    // never runs without it. TypeScript cannot correlate the two destructured props itself.
+    const useSelectedUsersHook = (useUsersHook ?? useUsers);
+    const controller = useSelectedUsersHook({ port, translate: injectedTranslate, queryScope }, {
         openOwnPasswordReset, onOwnPasswordResetClosed, passwordResetNotice,
     });
+    const { users, roles, policies, canGrant, error, formOpen, setFormOpen, username, setUsername, email, setEmail, password, setPassword, saving, formError, onCreate, expandedId, toggleExpanded, toggleSavingId, toggleError, notice, confirmingDisable, setConfirmingDisable, requestDisable, confirmDisable, onToggleStatus, resetPasswordFor, setResetPasswordFor, newPassword, setNewPassword, passwordSaving, passwordError, setPasswordError, openResetPassword, confirmResetPassword, canManageUserTrash, rowCapabilities, ownProfile, renameUserHandler, changeUsername, confirmingDelete, setConfirmingDelete, requestDelete, deleteSaving, confirmDelete, t, translate, } = controller;
     if (error)
         return _jsx("div", { className: "notice error", children: error });
     if (!users || !roles || !policies)
         return _jsx("div", { className: "notice", children: t("Loading users…") });
-    return (_jsxs("div", { className: "page", children: [_jsx(UsersPageHeader, { formOpen: formOpen, setFormOpen: setFormOpen, t: t }), ownProfile ? _jsxs("section", { className: "notice", "aria-label": t("My profile"), children: [_jsx("h2", { children: t("My profile") }), _jsx("p", { children: ownProfile.username }), canRenameOwnProfile ? _jsx("button", { type: "button", onClick: openOwnRename, ...agentHandle({ handle: "users-profile-change-username" }, { role: "button", label: "Change my login username" }), children: t("Change username") }) : null] }) : null, formOpen ? (_jsx(NewUserForm, { username: username, setUsername: setUsername, email: email, setEmail: setEmail, password: password, setPassword: setPassword, saving: saving, formError: formError, onCreate: onCreate, t: t })) : null, _jsx(UsersNotices, { toggleError: toggleError, notice: notice }), _jsx(UsersTable, { users: users, roles: roles, policies: policies, showGrants: canGrant, actions: {
+    return (_jsxs("div", { className: "page", children: [_jsx(UsersPageHeader, { formOpen: formOpen, setFormOpen: setFormOpen, t: t }), formOpen ? (_jsx(NewUserForm, { username: username, setUsername: setUsername, email: email, setEmail: setEmail, password: password, setPassword: setPassword, saving: saving, formError: formError, onCreate: onCreate, t: t })) : null, _jsx(UsersNotices, { toggleError: toggleError, notice: notice }), _jsx(UsersTable, { users: users, ownPrincipalId: ownProfile?.principalId, roles: roles, policies: policies, showGrants: canGrant, actions: {
                     expandedId,
                     toggleExpanded,
                     savingId: toggleSavingId,
@@ -179,16 +194,6 @@ export function Users({ useUsersHook = useUsers, port, translate: injectedTransl
                     canDelete: canManageUserTrash,
                     rowCapabilities,
                     requestDelete,
-                }, manage: {
-                    error: grantError,
-                    saving: grantSaving,
-                    email: { value: editEmail, set: setEditEmail, saving: emailSaving, save: onSaveEmail },
-                    roleGrant: canGrant
-                        ? { options: roles, pendingId: pendingRoleId, setPendingId: setPendingRoleId, submit: onAssignRole }
-                        : null,
-                    policyGrant: canGrant
-                        ? { options: policies, pendingId: pendingPolicyId, setPendingId: setPendingPolicyId, submit: onAttachPolicy }
-                        : null,
-                }, t: t, translate: translate, renderServerLabel: renderServerLabel }), _jsx(UserDisableDialog, { confirmingDisable: confirmingDisable, setConfirmingDisable: setConfirmingDisable, toggleSavingId: toggleSavingId, confirmDisable: confirmDisable, t: t }), _jsx(UserDeleteDialog, { confirmingDelete: confirmingDelete, setConfirmingDelete: setConfirmingDelete, deleteSaving: deleteSaving, confirmDelete: confirmDelete, t: t }), _jsx(UserResetPasswordDialog, { resetPasswordFor: resetPasswordFor, setResetPasswordFor: setResetPasswordFor, newPassword: newPassword, setNewPassword: setNewPassword, passwordError: passwordError, setPasswordError: setPasswordError, passwordSaving: passwordSaving, confirmResetPassword: confirmResetPassword, t: t }), changeUsername ? _jsx(ChangeUsernameDialog, { controller: changeUsername, translate: t }) : null] }));
+                }, manage: userManageController({ controller, roles, policies }), t: t, translate: translate, renderServerLabel: renderServerLabel }), _jsx(UserDisableDialog, { confirmingDisable: confirmingDisable, setConfirmingDisable: setConfirmingDisable, toggleSavingId: toggleSavingId, confirmDisable: confirmDisable, t: t }), _jsx(UserDeleteDialog, { confirmingDelete: confirmingDelete, setConfirmingDelete: setConfirmingDelete, deleteSaving: deleteSaving, confirmDelete: confirmDelete, t: t }), _jsx(UserResetPasswordDialog, { resetPasswordFor: resetPasswordFor, setResetPasswordFor: setResetPasswordFor, newPassword: newPassword, setNewPassword: setNewPassword, passwordError: passwordError, setPasswordError: setPasswordError, passwordSaving: passwordSaving, confirmResetPassword: confirmResetPassword, t: t }), changeUsername ? _jsx(ChangeUsernameDialog, { controller: changeUsername, translate: t }) : null] }));
 }
 //# sourceMappingURL=Users.js.map

package/dist/react/users/hooks/use-users.hooks.js

@@ -27,7 +27,10 @@ import { useChangeUsername } from "./use-change-username.hooks.js";
  *  `onSuccess` is skipped only when a switch actually happened since this call started — otherwise
  *  a stale grant's success would erase a NEW, unrelated selection the operator has since made for
  *  the panel they actually have open now. */
-async function runGrantMutation(generationAtStart, toggleGenerationRef, mutate, onSuccess, setGrantSaving, setGrantError, describeError) {
+async function runGrantMutation({ toggleGenerationRef, mutate, onSuccess, setGrantSaving, setGrantError, describeError }) {
+    // Read synchronously, before the first `await` — the same instant both callers used to read and
+    // pass in themselves, so this is still the generation this call STARTED under.
+    const generationAtStart = toggleGenerationRef.current;
     setGrantSaving(true);
     setGrantError(null);
     try {
@@ -68,6 +71,29 @@ async function loadGrantOptions(port) {
         throw e;
     }
 }
+/**
+ * The combined read split into the controller's list fields: all `null` (and `canGrant` false)
+ * until the read settles, then `[]` roles/policies with `canGrant` false when `loadGrantOptions`
+ * reported a 403. Pure so `useUsers` stays a flat wiring list.
+ */
+function selectUsersList({ data }) {
+    if (!data)
+        return { users: null, roles: null, policies: null, canGrant: false };
+    const grantOptions = data.grantOptions;
+    return { users: data.users, roles: grantOptions?.roles ?? [], policies: grantOptions?.policies ?? [], canGrant: grantOptions != null };
+}
+/**
+ * The signed-in caller as the row-level permission checks see it: their own roster row (`null`
+ * while `me()` or the roster is unsettled, or when the caller is not in it), whether that row is an
+ * owner, and the role lookup both checks share. Computed once per render rather than once per row.
+ *
+ * @complexity O(users + roles) per render.
+ */
+function selectCaller({ users, roles, ownPrincipalId }) {
+    const roleMap = new Map((roles ?? []).map(role => [role.id, role]));
+    const ownProfile = users?.find(user => user.principalId === ownPrincipalId) ?? null;
+    return { roleMap, ownProfile, callerIsOwner: ownProfile !== null && isOwnerAccount({ user: ownProfile, roles: roleMap }) };
+}
 /**
  * Everything the Users screen does — full state, effects, and every server write, as one hook so
  * `Users.tsx` stays a pure render of whatever this returns. See this file's header for the
@@ -77,7 +103,6 @@ async function loadGrantOptions(port) {
  * @returns The full `UsersController` the view renders from — see that interface for every field.
  */
 export function useUsers({ port, translate, queryScope }, { openOwnPasswordReset = false, onOwnPasswordResetClosed, passwordResetNotice, } = {}) {
-    const boundT = translate;
     const describeError = (error, fallback) => describeApiError({ error, fallback, translate });
     // `portRef` (password-banner plan, 2026-09-24 Slice 3 deep-link half): captured once at mount and
     // never written again, same discipline and same reasoning as `use-assistant-chats.hooks.ts`'s own
@@ -94,10 +119,7 @@ export function useUsers({ port, translate, queryScope }, { openOwnPasswordReset
             return { users: u.users, grantOptions };
         },
     });
-    const users = list.data?.users ?? null;
-    const roles = list.data ? (list.data.grantOptions?.roles ?? []) : null;
-    const policies = list.data ? (list.data.grantOptions?.policies ?? []) : null;
-    const canGrant = list.data?.grantOptions != null;
+    const { users, roles, policies, canGrant } = selectUsersList({ data: list.data });
     const error = list.error ? describeError(list.error, translate("failed to load users")) : null;
     const [formOpen, setFormOpen] = useState(false);
     const [username, setUsername] = useState("");
@@ -189,27 +211,15 @@ export function useUsers({ port, translate, queryScope }, { openOwnPasswordReset
             cancelled = true;
         };
     }, []);
-    /** Guards the one-shot deep-link auto-open effect below so it fires at most once per mount, even
-     *  as `users`/`ownPrincipalId` keep changing identity across the renders it's waiting on (list
-     *  reloads, `me()` settling). Separate from {@link openedViaDeepLinkRef}, which tracks a DIFFERENT
-     *  question ("should closing the dialog navigate away") over the dialog's own open/close lifetime
-     *  — this one is "has the auto-open already been attempted", which must stay true forever once it
-     *  fires, including after the dialog this effect opened has since been closed. */
+    const { roleMap, ownProfile, callerIsOwner } = selectCaller({ users, roles, ownPrincipalId });
     function rowCapabilities(user) {
-        const roleMap = new Map((roles ?? []).map(role => [role.id, role]));
-        const ownRow = users?.find(row => row.principalId === ownPrincipalId);
-        return userAccountCapabilities({ user, callerPrincipalId: ownPrincipalId,
-            callerIsOwner: ownRow ? isOwnerAccount({ user: ownRow, roles: roleMap }) : false,
-            canManageUserTrash, roles: roleMap });
+        return userAccountCapabilities({ user, callerPrincipalId: ownPrincipalId, callerIsOwner, canManageUserTrash, roles: roleMap });
     }
-    const ownProfile = users?.find(user => user.principalId === ownPrincipalId) ?? null;
     function canRenameUser(user) {
         if (user.canRename === false)
             return false;
         if (!ownPrincipalId || (!effectivePermissions.includes("*") && !effectivePermissions.includes("user.manage")))
             return false;
-        const roleMap = new Map((roles ?? []).map(role => [role.id, role]));
-        const callerIsOwner = ownProfile ? isOwnerAccount({ user: ownProfile, roles: roleMap }) : false;
         // Server-supplied owner flags remain authoritative when role.manage is unavailable.
         const targetIsOwner = user.isOwner ?? (user.roleIds.some(id => !roleMap.has(id)) || isOwnerAccount({ user, roles: roleMap }));
         return !targetIsOwner || callerIsOwner;
@@ -224,6 +234,12 @@ export function useUsers({ port, translate, queryScope }, { openOwnPasswordReset
     function renameUserHandler({ user }, _options = {}) {
         return canRenameUser(user) ? (target) => changeUsername.open({ user: target }) : undefined;
     }
+    /** Guards the one-shot deep-link auto-open effect below so it fires at most once per mount, even
+     *  as `users`/`ownPrincipalId` keep changing identity across the renders it's waiting on (list
+     *  reloads, `me()` settling). Separate from {@link openedViaDeepLinkRef}, which tracks a DIFFERENT
+     *  question ("should closing the dialog navigate away") over the dialog's own open/close lifetime
+     *  — this one is "has the auto-open already been attempted", which must stay true forever once it
+     *  fires, including after the dialog this effect opened has since been closed. */
     const deepLinkAttemptedRef = useRef(false);
     /** Set true exactly when this effect opens the dialog, cleared by the close-effect below the first
      *  time it observes `resetPasswordFor` go back to `null`. Read there to decide whether to navigate
@@ -231,16 +247,13 @@ export function useUsers({ port, translate, queryScope }, { openOwnPasswordReset
      *  normal reset, must not also get shoved to `/users`. */
     const openedViaDeepLinkRef = useRef(false);
     useEffect(() => {
-        if (!openOwnPasswordReset || deepLinkAttemptedRef.current)
-            return;
-        if (!users || ownPrincipalId === null)
-            return;
-        const ownRow = users.find((u) => u.principalId === ownPrincipalId);
-        if (!ownRow)
+        // `ownProfile` is derived from exactly `users`/`ownPrincipalId` (see `selectCaller`), so it is
+        // `null` until both have settled and the caller's own row is in the roster.
+        if (!openOwnPasswordReset || deepLinkAttemptedRef.current || !ownProfile)
             return;
         deepLinkAttemptedRef.current = true;
         openedViaDeepLinkRef.current = true;
-        openResetPassword(ownRow);
+        openResetPassword(ownProfile);
     }, [openOwnPasswordReset, users, ownPrincipalId]);
     useEffect(() => {
         if (resetPasswordFor !== null || !openedViaDeepLinkRef.current)
@@ -278,12 +291,26 @@ export function useUsers({ port, translate, queryScope }, { openOwnPasswordReset
     async function onAssignRole({ principalId }) {
         if (!pendingRoleId)
             return;
-        await runGrantMutation(toggleGenerationRef.current, toggleGenerationRef, () => assignRoleMutation.mutate({ input: { principalId, roleId: pendingRoleId } }), () => setPendingRoleId(""), setGrantSaving, setGrantError, (e) => describeError(e, translate("failed to assign role")));
+        await runGrantMutation({
+            toggleGenerationRef,
+            mutate: () => assignRoleMutation.mutate({ input: { principalId, roleId: pendingRoleId } }),
+            onSuccess: () => setPendingRoleId(""),
+            setGrantSaving,
+            setGrantError,
+            describeError: (e) => describeError(e, translate("failed to assign role")),
+        });
     }
     async function onAttachPolicy({ principalId }) {
         if (!pendingPolicyId)
             return;
-        await runGrantMutation(toggleGenerationRef.current, toggleGenerationRef, () => attachPolicyMutation.mutate({ input: { principalId, policyId: pendingPolicyId } }), () => setPendingPolicyId(""), setGrantSaving, setGrantError, (e) => describeError(e, translate("failed to attach policy")));
+        await runGrantMutation({
+            toggleGenerationRef,
+            mutate: () => attachPolicyMutation.mutate({ input: { principalId, policyId: pendingPolicyId } }),
+            onSuccess: () => setPendingPolicyId(""),
+            setGrantSaving,
+            setGrantError,
+            describeError: (e) => describeError(e, translate("failed to attach policy")),
+        });
     }
     // `onSaveEmail` was left out of the `runGrantMutation` fold above on purpose: it tracks its OWN
     // `emailSaving` flag rather than the shared `grantSaving` `onAssignRole`/`onAttachPolicy` use, so
@@ -479,7 +506,7 @@ export function useUsers({ port, translate, queryScope }, { openOwnPasswordReset
         requestDelete,
         deleteSaving: deleteUserMutation.status === "pending",
         confirmDelete,
-        t: boundT,
+        t: translate,
         translate,
     };
 }

package/dist/server/admin-crud-service.js

@@ -194,16 +194,14 @@ export async function updateUser(required, optional = {}) {
 }
 /** Validate and reserve a normalized name inside the caller's identity transaction.
  * Permission/owner gates run first, so conflicts never disclose accounts to unauthorized callers.
+ * Check order (pinned in `__tests__/admin-crud-service.pins.test.ts`): type, blank, port wiring,
+ * the target's Trash state, host support (actual changes only), then uniqueness.
  * @complexity O(n) normalization for n username characters; one indexed lookup and up to two Trash reads.
  * Throws validation or conflict errors; performs no writes.
  */
-async function resolveUpdatedUsername(required, _optional = {}) {
+async function resolveUpdatedUsername(required) {
     const { deps, input, target } = required;
-    if (typeof input.username !== "string")
-        throw new IdentityValidationError({ message: "username must be a string" });
-    const username = normalizeUsername({ raw: input.username });
-    if (!username)
-        throw new IdentityValidationError({ message: "username must not be blank" });
+    const username = normalizeRequestedUsername({ raw: input.username });
     // Missing host ports are internal wiring faults, not user input errors (HTTP 500, not 400).
     if (!deps.usernameChanges)
         throw new Error("username changes are not configured");
@@ -213,15 +211,29 @@ async function resolveUpdatedUsername(required, _optional = {}) {
     if (username !== target.username) {
         await deps.usernameChanges.assertSupported?.({ workspaceId: input.workspaceId, principalId: input.principalId });
     }
+    await assertUsernameAvailable({ deps, usernameChanges: deps.usernameChanges, workspaceId: input.workspaceId, target, username });
+    return username;
+}
+/** A requested username must be a string that is not blank once normalized. */
+function normalizeRequestedUsername(required) {
+    if (typeof required.raw !== "string")
+        throw new IdentityValidationError({ message: "username must be a string" });
+    const username = normalizeUsername({ raw: required.raw });
+    if (!username)
+        throw new IdentityValidationError({ message: "username must not be blank" });
+    return username;
+}
+/** Refuses a normalized name held by ANY other user, naming Trash as the reason when the holder is there. */
+async function assertUsernameAvailable(required) {
+    const { deps, usernameChanges, workspaceId, target, username } = required;
     // Trash keeps credential rows until purge, so the unfiltered lookup reserves those names too.
-    const existing = await deps.repos.users.findByUsername({ workspaceId: input.workspaceId, username });
-    if (existing && existing.principalId !== target.principalId) {
-        if (await deps.usernameChanges.isInTrash({ workspaceId: input.workspaceId, principalId: existing.principalId })) {
-            throw new IdentityConflictError({ message: "a user with this username is in the Trash; restore or delete them permanently first", code: "USERNAME_IN_TRASH" });
-        }
-        throw new IdentityConflictError({ message: `username '${username}' is already in use`, code: "RESOURCE_CONFLICT" });
+    const existing = await deps.repos.users.findByUsername({ workspaceId, username });
+    if (!existing || existing.principalId === target.principalId)
+        return;
+    if (await usernameChanges.isInTrash({ workspaceId, principalId: existing.principalId })) {
+        throw new IdentityConflictError({ message: "a user with this username is in the Trash; restore or delete them permanently first", code: "USERNAME_IN_TRASH" });
     }
-    return username;
+    throw new IdentityConflictError({ message: `username '${username}' is already in use`, code: "RESOURCE_CONFLICT" });
 }
 /**
  * `RESET_USER_PASSWORD` (feature.spec.md ). Gated by **`user.manage`** only