@jini-ai/user-management 0.3.0 → 0.3.1

package/dist/react/users/Users.js

@@ -3,103 +3,170 @@ import { Fragment } 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, userRowMenuItems } from "./rules.js";
+import { formatGrantLabel, grantOptionLabel, userRowMenuItems, isOwnerAccount } from "./rules.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";
+/** The "New user" form — extracted from `Users` verbatim; own scope for `formError`/`saving`. */
 function NewUserForm({ username, setUsername, email, setEmail, password, setPassword, saving, formError, onCreate, t }) {
-    return (_jsxs("form", { onSubmit: onCreate, className: "notice integrations-form form-measure", children: [formError ? _jsx("span", { className: "save-error", children: formError }) : null, _jsxs("label", { children: [t("Username"), _jsx("input", { value: username, onChange: (e) => setUsername(e.target.value), required: true, ...agentHandle({ handle: "users-new-username" }, { role: "field", label: t("The new user's username") }) })] }), _jsxs("label", { children: [t("Email (optional)"), _jsx("input", { type: "email", value: email, onChange: (e) => setEmail(e.target.value), ...agentHandle({ handle: "users-new-email" }, { role: "field", label: t("The new user's email address") }) })] }), _jsxs("label", { children: [t("Password"), _jsx("input", { type: "password", autoComplete: "new-password", value: password, onChange: (e) => setPassword(e.target.value), required: true, minLength: 1, ...agentHandle({ handle: "users-new-password" }, {
+    return (_jsxs("form", { onSubmit: onCreate, className: "notice integrations-form form-measure", children: [formError ? _jsx("span", { className: "save-error", children: formError }) : null, _jsxs("label", { children: [t("Username"), _jsx("input", { value: username, onChange: (e) => setUsername(e.target.value), required: true, ...agentHandle({ handle: "users-new-username" }, { role: "field", label: "The new user's username" }) })] }), _jsxs("label", { children: [t("Email (optional)"), _jsx("input", { type: "email", value: email, onChange: (e) => setEmail(e.target.value), ...agentHandle({ handle: "users-new-email" }, { role: "field", label: "The new user's email address" }) })] }), _jsxs("label", { children: [t("Password"), _jsx("input", { type: "password", autoComplete: "new-password", value: password, onChange: (e) => setPassword(e.target.value), required: true, minLength: 1, ...agentHandle({ handle: "users-new-password" }, {
                             role: "field",
-                            label: t("The new user's password — a credential field, so only a human can fill it"),
-                        }) })] }), _jsx("button", { type: "submit", disabled: saving, ...agentHandle({ handle: "users-new-submit" }, { role: "button", label: t("Create this operator account") }), children: saving ? t("Creating…") : t("Create user") })] }));
+                            label: "The new user's password — a credential field, so only a human can fill it",
+                        }) })] }), _jsx("button", { type: "submit", disabled: saving, ...agentHandle({ handle: "users-new-submit" }, { role: "button", label: "Create this operator account" }), children: saving ? t("Creating…") : t("Create user") })] }));
 }
+/** The select-plus-button both grants render. */
 function GrantSelect({ principalId, label, placeholder, submitLabel, grant, saving, agentBase, t }) {
     return (_jsxs("label", { children: [label, _jsxs("span", { className: "editor-actions", children: [_jsxs("select", { value: grant.pendingId, onChange: (e) => grant.setPendingId(e.target.value), ...agentHandle({ handle: `${agentBase}-select` }, {
                             role: "field",
-                            label: t(`${label} — set with page.select_option, not click`),
-                        }), children: [_jsx("option", { value: "", children: placeholder }), grant.options.map((option) => (_jsxs("option", { value: option.id, children: [option.name, option.isBuiltin ? ` ${t("(built-in)")}` : ""] }, option.id)))] }), _jsx("button", { type: "button", disabled: !grant.pendingId || saving, onClick: () => grant.submit({ principalId }), ...agentHandle({ handle: `${agentBase}-submit` }, { role: "button", label: t(`${submitLabel} the selected option to this user`) }), children: saving ? t("Saving…") : submitLabel })] })] }));
+                            label: `${label} — set with page.select_option, not click`,
+                        }), children: [_jsx("option", { value: "", children: placeholder }), grant.options.map((option) => (_jsxs("option", { value: option.id, children: [grantOptionLabel({ option, translate: t }), option.isBuiltin ? ` ${t("(built-in)")}` : ""] }, option.id)))] }), _jsx("button", { type: "button", disabled: !grant.pendingId || saving, onClick: () => grant.submit({ principalId }), ...agentHandle({ handle: `${agentBase}-submit` }, { role: "button", label: `${submitLabel} the selected option to this user` }), children: saving ? t("Saving…") : submitLabel })] })] }));
 }
-export function UserManagePanel({ principalId, manage, t }) {
-    return (_jsx("tr", { children: _jsx("td", { colSpan: 6, children: _jsxs("div", { className: "notice integrations-form", children: [manage.error ? _jsx("span", { className: "save-error", children: manage.error }) : null, _jsxs("label", { children: [t("Email"), _jsxs("span", { className: "editor-actions", children: [_jsx("input", { type: "email", value: manage.email.value, onChange: (e) => manage.email.set(e.target.value), placeholder: t("(none)"), ...agentHandle({ handle: "user-manage-email" }, { role: "field", label: t("This user's email address") }) }), _jsx("button", { type: "button", disabled: manage.email.saving, onClick: () => manage.email.save({ principalId }), ...agentHandle({ handle: "user-manage-email-save" }, { role: "button", label: t("Save this user's email address") }), children: manage.email.saving ? t("Saving…") : t("Save email") })] })] }), _jsx(GrantSelect, { principalId: principalId, label: t("Assign role"), placeholder: t("Select a role…"), submitLabel: t("Assign"), grant: manage.roleGrant, saving: manage.saving, agentBase: "user-manage-role", t: t }), _jsx(GrantSelect, { principalId: principalId, label: t("Attach policy"), placeholder: t("Select a policy…"), submitLabel: t("Attach"), grant: manage.policyGrant, saving: manage.saving, agentBase: "user-manage-policy", t: t })] }) }) }));
+/** The expanded "Manage" row's contents (email edit, role/policy grant forms).
+ *
+ *  Exported so a test can drive it with a hand-built {@link UserManageController} — the seam only
+ *  counts as one if something other than `Users` can supply it. */
+export function UserManagePanel({ principalId, manage, t, colSpan = 6 }) {
+    return (_jsx("tr", { children: _jsx("td", { colSpan: colSpan, children: _jsxs("div", { className: "notice integrations-form", children: [manage.error ? _jsx("span", { className: "save-error", children: manage.error }) : null, _jsxs("label", { children: [t("Email"), _jsxs("span", { className: "editor-actions", children: [_jsx("input", { type: "email", value: manage.email.value, onChange: (e) => manage.email.set(e.target.value), placeholder: t("(none)"), ...agentHandle({ handle: "user-manage-email" }, { role: "field", label: "This user's email address" }) }), _jsx("button", { type: "button", disabled: manage.email.saving, onClick: () => manage.email.save({ principalId }), ...agentHandle({ handle: "user-manage-email-save" }, { role: "button", label: "Save this user's email address" }), children: manage.email.saving ? t("Saving…") : t("Save email") })] })] }), manage.roleGrant ? (_jsx(GrantSelect, { principalId: principalId, label: t("Assign role"), placeholder: t("Select a role…"), submitLabel: t("Assign"), grant: manage.roleGrant, saving: manage.saving, agentBase: "user-manage-role", t: t })) : null, manage.policyGrant ? (_jsx(GrantSelect, { principalId: principalId, label: t("Attach policy"), placeholder: t("Select a policy…"), submitLabel: t("Attach"), grant: manage.policyGrant, saving: manage.saving, agentBase: "user-manage-policy", t: t })) : null] }) }) }));
 }
-function UserRow({ user, roleById, policyById, actions, manage, agentBase, t, translate }) {
-    const roleLabel = formatGrantLabel({ ids: user.roleIds, byId: roleById });
+/** 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: [_jsx("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: t("Open this user's Manage panel — edit email, assign a role, attach a policy"),
-                            }), children: user.username }) }), _jsx("td", { children: user.email ?? _jsx("span", { className: "muted-cell", children: "\u2014" }) }), _jsx("td", { children: _jsx("span", { className: `status status-${user.status}`, children: t(user.status) }) }), _jsx("td", { children: roleLabel !== null ? t(roleLabel) : _jsx("span", { className: "muted-cell", children: t("none") }) }), _jsx("td", { children: policyLabel !== null ? policyLabel : _jsx("span", { className: "muted-cell", children: t("none") }) }), _jsx("td", { children: _jsx(RowMenu, { triggerLabel: `${t("Actions for user")} "${user.username}"`, agentHandle: `${agentBase}-menu`, items: userRowMenuItems({
-                                user,
-                                toggleSaving: actions.savingId === user.principalId,
+    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,
                                     onRequestDelete: actions.requestDelete,
-                                },
-                                translate,
-                                canDelete: actions.canDelete,
-                            }) }) })] }), actions.expandedId === user.principalId ? (_jsx(UserManagePanel, { principalId: user.principalId, manage: manage, t: t })) : null] }));
+                                }, 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 UsersTable({ users, roles, policies, actions, manage, t, translate }) {
+/** 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 }) {
     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.") })] }) }));
     }
+    // Not `useMemo`d: computed after the empty-state early return above, so a `useMemo` here would
+    // need hoisting above it to keep hook order stable across renders — same constraint `Media.tsx`
+    // documents for its own post-early-return computation. Not worth that indirection: these three
+    // maps/handles are a single O(n) pass each over one operator's own users/roles/policies (already
+    // built once per render rather than once per row, per this function's own doc comment above).
     const roleById = new Map(roles.map((role) => [role.id, role]));
     const policyById = new Map(policies.map((policy) => [policy.id, policy]));
+    // 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") }), _jsx("th", { children: t("Roles") }), _jsx("th", { children: t("Policies") }), _jsx("th", { children: t("More") })] }) }), _jsx("tbody", { children: users.map((user, index) => (_jsx(Fragment, { children: _jsx(UserRow, { user: user, roleById: roleById, policyById: policyById, actions: actions, manage: manage, agentBase: rowHandles[index], t: t, translate: translate }) }, 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))) })] }) }));
 }
+/** The Disable confirm dialog — extracted from `Users` verbatim. */
 function UserDisableDialog({ confirmingDisable, setConfirmingDisable, toggleSavingId, confirmDisable, t }) {
     return (_jsx(ConfirmDialog, { cancelLabel: t("Cancel"), open: confirmingDisable !== null, agentHandle: "users-disable", title: t("Disable this user?"), body: confirmingDisable ? (_jsxs("p", { children: [t("Disable"), " \"", confirmingDisable.username, "\"? ", t("They will not be able to sign in until re-enabled.")] })) : null, confirmLabel: t("Disable"), tone: "warning", pending: confirmingDisable !== null && toggleSavingId === confirmingDisable.principalId, onConfirm: confirmDisable, onCancel: () => setConfirmingDisable(null) }));
 }
+/** The Delete confirm dialog (delete-user plan v2, 2026-09-24) — mirrors {@link UserDisableDialog}'s
+ *  shape exactly (own props, own state), naming the Trash rather than a permanent removal since
+ *  that is what "Delete" now does here (decisions 2/7 of the plan). */
 function UserDeleteDialog({ confirmingDelete, setConfirmingDelete, deleteSaving, confirmDelete, t }) {
     return (_jsx(ConfirmDialog, { cancelLabel: t("Cancel"), open: confirmingDelete !== null, agentHandle: "users-delete", title: t("Delete this user?"), body: confirmingDelete ? (_jsxs("p", { children: [t("Delete"), " \"", confirmingDelete.username, "\"?", " ", t("They will be signed out and moved to the Trash. You can restore them there; they are deleted permanently after 60 days.")] })) : null, confirmLabel: t("Move to trash"), tone: "danger", pending: deleteSaving, onConfirm: confirmDelete, onCancel: () => setConfirmingDelete(null) }));
 }
+/** Open-eye glyph — standard "reveal" affordance, shown while a `RevealablePasswordField` is
+ *  hidden (click to show). House stroke-icon convention (`viewBox="0 0 18 18"`, `fill="none"`,
+ *  `stroke="currentColor"`, `strokeWidth={1.5}`, `aria-hidden`) — same shape `Media.tsx`'s
+ *  `PlaceholderIcon`/`ExpandIcon`/`CloseIcon` and `nav.ts`'s panel icons use throughout this app. */
 function EyeIcon() {
     return (_jsxs("svg", { viewBox: "0 0 18 18", fill: "none", stroke: "currentColor", strokeWidth: 1.5, "aria-hidden": "true", children: [_jsx("path", { d: "M1.5 9S4.5 4 9 4s7.5 5 7.5 5-3 5-7.5 5-7.5-5-7.5-5Z", strokeLinejoin: "round" }), _jsx("circle", { cx: "9", cy: "9", r: "2" })] }));
 }
+/** Same glyph with a slash through it — standard "hide" affordance, shown while the field is
+ *  currently revealed (click to hide). */
 function EyeOffIcon() {
     return (_jsxs("svg", { viewBox: "0 0 18 18", fill: "none", stroke: "currentColor", strokeWidth: 1.5, "aria-hidden": "true", children: [_jsx("path", { d: "M1.5 9S4.5 4 9 4s7.5 5 7.5 5-3 5-7.5 5-7.5-5-7.5-5Z", strokeLinejoin: "round" }), _jsx("circle", { cx: "9", cy: "9", r: "2" }), _jsx("path", { d: "M3 3 15 15", strokeLinecap: "round" })] }));
 }
+/** One password input plus its own independent show/hide toggle. `UserResetPasswordDialog` renders
+ *  this twice (new password, confirm new password) so each field can be revealed on its own — the
+ *  whole point of the confirm field is catching a typo by eye, which a single toggle driving both
+ *  fields would not let the operator do selectively. Follows this file's `GrantSelect` precedent: a
+ *  shape used by more than one caller gets its own top-level function instead of staying inline
+ *  twice.
+ *
+ *  The toggle itself is icon-only (standard eye / eye-with-slash convention, per owner request —
+ *  not a text "Show"/"Hide" link): the accessible name still flips between "Show password"/"Hide
+ *  password" via `aria-label` (screen reader), and `aria-pressed` mirrors `visible` so assistive
+ *  tech gets the same on/off signal a text label would have given.
+ *
+ *  The input's inline `flex`/`minWidth` override neutralizes `styles.css`'s `.field input { width:
+ *  100% }` fighting the toggle button for room inside the `.editor-actions` row below — an inline
+ *  style wins on specificity without adding a new class to a stylesheet this feature doesn't own. */
 function RevealablePasswordField({ id, label, value, onChange, visible, onToggleVisible, agentBase, t }) {
     const toggleLabel = visible ? t("Hide password") : t("Show password");
-    return (_jsxs("div", { className: "field", children: [_jsx("label", { className: "field-label", htmlFor: id, children: label }), _jsxs("span", { className: "editor-actions", children: [_jsx("input", { id: id, type: visible ? "text" : "password", autoComplete: "new-password", value: value, onChange: (e) => onChange(e.target.value), style: { flex: "1 1 auto", minWidth: 0 }, ...agentHandle({ handle: agentBase }, {
+    return (_jsxs("div", { className: "field", children: [_jsx("label", { className: "field-label", htmlFor: id, children: label }), _jsxs("span", { className: "editor-actions", children: [_jsx("input", { id: id, type: visible ? "text" : "password", 
+                        // `new-password`, not `off` (Chrome ignores `off`): without it Chrome filled a saved
+                        // login into "New password" only. Kept while revealed as `type="text"`, too.
+                        autoComplete: "new-password", value: value, onChange: (e) => onChange(e.target.value), style: { flex: "1 1 auto", minWidth: 0 }, ...agentHandle({ handle: agentBase }, {
                             role: "field",
-                            label: t(`${label} — a credential field, so only a human can fill it`),
-                        }) }), _jsx("button", { type: "button", className: "link-button", "aria-label": toggleLabel, "aria-pressed": visible, title: toggleLabel, onClick: onToggleVisible, ...agentHandle({ handle: `${agentBase}-reveal` }, { role: "button", label: t(`Show or hide the ${label.toLowerCase()} field's characters`) }), children: _jsx("span", { style: { display: "inline-flex", width: 16, height: 16 }, children: visible ? _jsx(EyeOffIcon, {}) : _jsx(EyeIcon, {}) }) })] })] }));
+                            label: `${label} — a credential field, so only a human can fill it`,
+                        }) }), _jsx("button", { type: "button", className: "link-button", "aria-label": toggleLabel, "aria-pressed": visible, title: toggleLabel, onClick: onToggleVisible, ...agentHandle({ handle: `${agentBase}-reveal` }, { role: "button", label: `Show or hide the ${label.toLowerCase()} field's characters` }), children: _jsx("span", { style: { display: "inline-flex", width: 16, height: 16 }, children: visible ? _jsx(EyeOffIcon, {}) : _jsx(EyeIcon, {}) }) })] })] }));
 }
+/** Resolves `useFields` to the real hook when no override is passed, because ESLint's
+ *  cyclomatic-complexity rule counts a default parameter value evaluated inside a function's OWN
+ *  body as one of that function's own branches; a call out to a separately-scoped resolver does
+ *  not. */
 function resolveResetPasswordFieldsHook(override) {
     return override ?? useResetPasswordFields;
 }
+/** The reset-password dialog — extracted from `Users` verbatim, since extended with the confirm
+ *  field and both reveal toggles (see this file's header). */
 function UserResetPasswordDialog({ resetPasswordFor, setResetPasswordFor, newPassword, setNewPassword, passwordError, setPasswordError, passwordSaving, confirmResetPassword, t, useFields: useFieldsProp, }) {
     const useFields = resolveResetPasswordFieldsHook(useFieldsProp);
     const fields = useFields({ resetPasswordFor, newPassword });
+    /** Blocks the reset entirely when the two fields disagree — a mismatch never reaches
+     *  `confirmResetPassword`/the server. The inline message below is driven by the same `mismatch`
+     *  value, so it is already visible by the time a blocked click can happen; there is nothing
+     *  further to surface here. */
     function handleConfirm() {
         if (fields.mismatch)
             return;
         void confirmResetPassword();
     }
-    return (_jsx(ConfirmDialog, { cancelLabel: t("Cancel"), open: resetPasswordFor !== null, agentHandle: "users-reset-password", title: t("Reset password?"), body: resetPasswordFor ? (_jsxs(_Fragment, { children: [_jsxs("p", { children: [t("Set a new password for"), " \"", resetPasswordFor.username, "\".", " ", t("Every active session for this user will be signed out.")] }), _jsx(RevealablePasswordField, { id: "users-reset-password-input", label: t("New password"), value: newPassword, onChange: setNewPassword, visible: fields.showNewPassword, onToggleVisible: fields.toggleShowNewPassword, agentBase: "users-reset-password", t: t }), _jsx(RevealablePasswordField, { id: "users-reset-password-confirm-input", label: t("Confirm new password"), value: fields.confirmPassword, onChange: fields.setConfirmPassword, visible: fields.showConfirmPassword, onToggleVisible: fields.toggleShowConfirmPassword, agentBase: "users-reset-password-retype", t: t }), fields.mismatch ? (_jsx("p", { className: "save-error", role: "alert", children: t("Passwords do not match.") })) : passwordError ? (_jsx("p", { className: "save-error", role: "alert", children: passwordError })) : null] })) : null, confirmLabel: t("Reset password"), tone: "warning", pending: passwordSaving, onConfirm: handleConfirm, onCancel: () => {
+    return (_jsx(ConfirmDialog, { cancelLabel: t("Cancel"), open: resetPasswordFor !== null, agentHandle: "users-reset-password", title: t("Reset password?"), body: resetPasswordFor ? (_jsxs(_Fragment, { children: [_jsxs("p", { children: [t("Set a new password for"), " \"", resetPasswordFor.username, "\".", " ", t("Every active session for this user will be signed out.")] }), _jsx(RevealablePasswordField, { id: "users-reset-password-input", label: t("New password"), value: newPassword, onChange: setNewPassword, visible: fields.showNewPassword, onToggleVisible: fields.toggleShowNewPassword, agentBase: "users-reset-password", t: t }), _jsx(RevealablePasswordField, { id: "users-reset-password-confirm-input", label: t("Confirm new password"), value: fields.confirmPassword, onChange: fields.setConfirmPassword, visible: fields.showConfirmPassword, onToggleVisible: fields.toggleShowConfirmPassword, 
+                    // NOT "users-reset-password-confirm" — that string is already the dialog's own
+                    // ConfirmDialog Confirm button handle (`agentHandle="users-reset-password"` above,
+                    // `-confirm` sub-handle). Two elements answering to the same handle is a
+                    // page-authoring bug the page driver refuses to resolve (see
+                    // `dom-page-driver.ts`'s `ambiguousHandleError`), so this field gets its own name.
+                    agentBase: "users-reset-password-retype", t: t }), fields.mismatch ? (_jsx("p", { className: "save-error", role: "alert", children: t("Passwords do not match.") })) : passwordError ? (_jsx("p", { className: "save-error", role: "alert", children: passwordError })) : null] })) : null, confirmLabel: t("Reset password"), tone: "warning", pending: passwordSaving, onConfirm: handleConfirm, onCancel: () => {
             setResetPasswordFor(null);
             setNewPassword("");
             setPasswordError(null);
         } }));
 }
+/** The page title plus the "New user"/"Cancel" toggle button — extracted from `Users` verbatim so
+ *  its two `formOpen` ternaries (class, label) count against this function, not `Users`'. */
 function UsersPageHeader({ formOpen, setFormOpen, t }) {
-    return (_jsxs("div", { className: "page-header", ...agentHandle({ handle: "users-header" }, { role: "region", label: t("Users header — page title and the New user button") }), children: [_jsxs("div", { className: "page-header-text", children: [_jsx("p", { className: "page-kicker", children: t("People") }), _jsxs("h1", { className: "page-title", children: [t("Users"), _jsx(InfoTip, { label: t("No 'forgot password' email yet. If someone is locked out, the owner can reset their password here."), agentHandle: "users-reset-password-info" })] }), _jsx("p", { className: "page-description", children: t("Operator accounts with access to this admin — assign roles and policies, or disable access.") })] }), _jsx("div", { className: "page-actions", children: _jsx("button", { className: formOpen ? "btn-secondary" : undefined, onClick: () => setFormOpen((v) => !v), ...agentHandle({ handle: "users-new-toggle" }, { role: "button", label: t("Open or close the new-user form") }), children: formOpen ? t("Cancel") : t("New user") }) })] }));
+    return (_jsxs("div", { className: "page-header", ...agentHandle({ handle: "users-header" }, { role: "region", label: "Users header — page title and the New user button" }), children: [_jsxs("div", { className: "page-header-text", children: [_jsx("p", { className: "page-kicker", children: t("People") }), _jsxs("h1", { className: "page-title", children: [t("Users"), _jsx(InfoTip, { label: t("No 'forgot password' email yet. If someone is locked out, the owner can reset their password here."), agentHandle: "users-reset-password-info" })] }), _jsx("p", { className: "page-description", children: t("Operator accounts with access to this admin — assign roles and policies, or disable access.") })] }), _jsx("div", { className: "page-actions", children: _jsx("button", { className: formOpen ? "btn-secondary" : undefined, onClick: () => setFormOpen((v) => !v), ...agentHandle({ handle: "users-new-toggle" }, { role: "button", label: "Open or close the new-user form" }), children: formOpen ? t("Cancel") : t("New user") }) })] }));
 }
+/** The Disable/Enable-toggle error banner and the reset-password success notice — extracted from
+ *  `Users` verbatim. `Users` was still cyc 10 (over the tightened <=9/<=9 bar) with these two
+ *  independent ternaries inline; moving them out is the same "extract to a top-level function"
+ *  rule the rest of this pass follows. */
 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 }) {
-    const { users, roles, policies, 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, confirmingDelete, setConfirmingDelete, requestDelete, deleteSaving, confirmDelete, t, translate, } = useUsersHook({ port, translate: injectedTranslate, queryScope }, { openOwnPasswordReset, onOwnPasswordResetClosed });
+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, confirmingDelete, setConfirmingDelete, requestDelete, deleteSaving, confirmDelete, t, translate, } = useUsersHook({ port, translate: injectedTranslate, queryScope }, {
+        openOwnPasswordReset, onOwnPasswordResetClosed, passwordResetNotice,
+    });
     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 }), 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, 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, roles: roles, policies: policies, showGrants: canGrant, actions: {
                     expandedId,
                     toggleExpanded,
                     savingId: toggleSavingId,
@@ -107,23 +174,18 @@ export function Users({ useUsersHook = useUsers, port, translate: injectedTransl
                     toggleStatus: onToggleStatus,
                     openResetPassword,
                     canDelete: canManageUserTrash,
+                    rowCapabilities,
                     requestDelete,
                 }, manage: {
                     error: grantError,
                     saving: grantSaving,
                     email: { value: editEmail, set: setEditEmail, saving: emailSaving, save: onSaveEmail },
-                    roleGrant: {
-                        options: roles,
-                        pendingId: pendingRoleId,
-                        setPendingId: setPendingRoleId,
-                        submit: onAssignRole,
-                    },
-                    policyGrant: {
-                        options: policies,
-                        pendingId: pendingPolicyId,
-                        setPendingId: setPendingPolicyId,
-                        submit: onAttachPolicy,
-                    },
-                }, t: t, translate: translate }), _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 })] }));
+                    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 })] }));
 }
 //# sourceMappingURL=Users.js.map

package/dist/react/users/hooks/use-reset-password-fields.hooks.d.ts

@@ -1,16 +1,48 @@
 import type { AdminIdentityUser } from "../../models.js";
+/**
+ * @file The reset-password dialog's own confirm-field and reveal-toggle state — client-side only,
+ * never sent to the server (`use-users.hooks.ts`'s `resetPasswordMutation` still posts only
+ * `principalId`/`password`). Split out of `Users.tsx` because this is one dialog's own ephemeral UI
+ * concern, not part of the screen-wide `UsersController` `use-users.hooks.ts` already owns, so it
+ * gets its own small hook rather than growing that one further. No `-port.hooks.ts`/
+ * `-dependencies.hooks.ts` pair — this hook does no I/O of its own.
+ */
 export interface ResetPasswordFieldsInput {
+    /** Which user the dialog is open for — `null` when closed. Only `principalId` is read (see
+     *  `useResetPasswordFields`'s own doc comment for why). */
     resetPasswordFor: AdminIdentityUser | null;
+    /** The dialog's own "New password" value, owned by `use-users.hooks.ts` — passed in so this hook
+     *  can derive `mismatch` without `UserResetPasswordDialog` having to compare the two fields itself. */
     newPassword: string;
 }
 export interface ResetPasswordFieldsController {
+    /** The typed confirmation value. Never read by anything outside this dialog — it exists only to
+     *  be compared against `newPassword`, and is discarded (never becomes part of the request body). */
     confirmPassword: string;
     setConfirmPassword: (value: string) => void;
+    /** True whenever `newPassword` and `confirmPassword` differ, including while `confirmPassword` is
+     *  still empty. `UserResetPasswordDialog` uses this to block the confirm action and to choose
+     *  which message occupies its single error slot. */
     mismatch: boolean;
     showNewPassword: boolean;
     toggleShowNewPassword: () => void;
     showConfirmPassword: boolean;
     toggleShowConfirmPassword: () => void;
 }
-export declare function useResetPasswordFields({ resetPasswordFor, newPassword }: ResetPasswordFieldsInput): ResetPasswordFieldsController;
+/**
+ * Owns the "Confirm new password" field and both fields' independent reveal toggles.
+ *
+ * Resets `confirmPassword` and both reveal flags to their defaults on every open transition —
+ * keyed on `resetPasswordFor?.principalId` rather than the `user` object's own identity, so a
+ * reopen of the SAME user (e.g. Cancel, then "Reset password" again from the row menu) still
+ * resets even if the `users` list query happens to hand back the same object reference. This is
+ * also why closing the dialog (`principalId` going back to `null`) resets these fields too: there
+ * is no user-visible difference between "reset on close" and "reset on open" for a dialog that is
+ * unmounted-in-effect (`ConfirmDialog` stays in the DOM but hidden) between the two.
+ *
+ * @param input - `resetPasswordFor` (open/closed + which user) and the sibling `newPassword` value.
+ * @returns The confirm field's value/setter, the derived `mismatch` flag, and both reveal toggles.
+ * @complexity Time/space: O(1) — fixed number of state cells, no iteration.
+ */
+export declare function useResetPasswordFields({ resetPasswordFor, newPassword }: ResetPasswordFieldsInput, _optional?: Record<string, never>): ResetPasswordFieldsController;
 //# sourceMappingURL=use-reset-password-fields.hooks.d.ts.map

package/dist/react/users/hooks/use-reset-password-fields.hooks.js

@@ -1,5 +1,20 @@
 import { useEffect, useState } from "react";
-export function useResetPasswordFields({ resetPasswordFor, newPassword }) {
+/**
+ * Owns the "Confirm new password" field and both fields' independent reveal toggles.
+ *
+ * Resets `confirmPassword` and both reveal flags to their defaults on every open transition —
+ * keyed on `resetPasswordFor?.principalId` rather than the `user` object's own identity, so a
+ * reopen of the SAME user (e.g. Cancel, then "Reset password" again from the row menu) still
+ * resets even if the `users` list query happens to hand back the same object reference. This is
+ * also why closing the dialog (`principalId` going back to `null`) resets these fields too: there
+ * is no user-visible difference between "reset on close" and "reset on open" for a dialog that is
+ * unmounted-in-effect (`ConfirmDialog` stays in the DOM but hidden) between the two.
+ *
+ * @param input - `resetPasswordFor` (open/closed + which user) and the sibling `newPassword` value.
+ * @returns The confirm field's value/setter, the derived `mismatch` flag, and both reveal toggles.
+ * @complexity Time/space: O(1) — fixed number of state cells, no iteration.
+ */
+export function useResetPasswordFields({ resetPasswordFor, newPassword }, _optional = {}) {
     const [confirmPassword, setConfirmPassword] = useState("");
     const [showNewPassword, setShowNewPassword] = useState(false);
     const [showConfirmPassword, setShowConfirmPassword] = useState(false);

package/dist/react/users/hooks/use-users.hooks.d.ts

@@ -1,12 +1,81 @@
-import type { Translate } from "@jini-ai/ui/panel-kit";
 import { type Dispatch, type FormEvent, type SetStateAction } from "react";
-import { type AdminIdentityUser, type AdminPolicy, type AdminRole } from "../../models.js";
+import type { AdminIdentityUser, AdminPolicy, AdminRole } from "../../models.js";
+import { type Translate } from "@jini-ai/ui/panel-kit";
+import { type UserAccountCapabilities } from "../rules.js";
 import type { UsersPort } from "../../ports.js";
+/**
+ * @file Everything the Users screen does, so `Users.tsx` is only markup.
+ *
+ * Extracted verbatim — same state, same declaration order, same effect bodies, same error strings.
+ * This is the highest-state screen in the app (25 `useState` calls): users/roles/policies load, the
+ * "New user" form, the per-row expandable "Manage" panel (role/policy grants, email edit), the
+ * Disable confirm dialog, and the reset-password dialog all live here so `Users.tsx` can stay a pure
+ * render of whatever this hook returns.
+ *
+ * `describeApiError` (this screen's server-error-code overrides) moved to `rules.ts` alongside the
+ * row-menu builder, since both compute a value rather than performing an effect; this hook imports
+ * it back for its own async handlers.
+ *
+ * Naming follows `hooks/use-settings-slice.hooks.ts` and `posts/hooks/use-posts.hooks.ts`:
+ * `use-<thing>.hooks.ts`. Feature-local because nothing outside `features/users` needs it.
+ *
+ * `onCreate` and `confirmResetPassword` — each a single action with its OWN dedicated saving/error
+ * pair — now run through `hooks/use-async-action.hooks.ts`'s `useAsyncAction`, replacing their own
+ * `setXSaving(true)/setXError(null)/try/catch/finally` boilerplate with one `run()` call each; the
+ * public `UsersController` shape (`saving`/`formError`, `passwordSaving`/`passwordError`/
+ * `setPasswordError`) is unchanged. `grantSaving`/`grantError` (shared by three different handlers
+ * for one "Manage" panel error slot) and `toggleSavingId`/`toggleError` (`toggleSavingId` is the
+ * BUSY ROW'S id, not a boolean) stay hand-rolled — see `useAsyncAction`'s own header for why forcing
+ * either shape onto that primitive would change behavior rather than just deduplicate it.
+ *
+ * `t`/`locale` (2026-08-11, standing i18n rule — a component with a hook gets a BOUND `t` from that
+ * hook, not its own `useAdminLocale()`/dictionary import): this hook already called
+ * `useAdminLocale()` for its own error-string translations, so exposing that SAME already-resolved
+ * `locale` as a bound `t` (plus the raw value, still needed for `rules.ts`'s `userRowMenuItems`,
+ * which takes `locale` directly) on the return value adds no new fetch — `Users.tsx` used to call
+ * `useAdminLocale()` a second time and rebuild its own `translateUsers(locale, key)` closure,
+ * entirely redundant with the resolution this hook was already doing internally.
+ *
+ * `lib/fetch-query` migration (2026-08-12): the combined users+roles+policies read is one
+ * `useFetchQuery` keyed on `KEYS.list`; every write below routes its actual API call through a
+ * `useFetchMutation` that `invalidates: [KEYS.list]` instead of the `action`/handler body calling
+ * `reload()` by hand — except `resetPasswordMutation`, which never called `reload()` either (a
+ * password reset doesn't change anything the users table shows). `useAsyncAction` (`createUser`/
+ * `resetPassword` below) keeps owning the busy/error UI state exactly as before — this migration
+ * only changes what runs INSIDE its `action` callback, not the primitive itself, which is shared
+ * with other screens and has no fetch-query concern of its own. `grantSaving`/`grantError`/
+ * `toggleSavingId`/`toggleError` stay hand-rolled for the same reason `use-roles.hooks.ts`'s
+ * `rowSavingId`/`rowError` do: each is shared across MULTIPLE independent mutations, and a single
+ * mutation's own `status`/`error` has no way to carry "which row/action this particular call was
+ * for". `emailSaving` is the one exception — it already tracked exactly one mutation 1:1 before this
+ * migration, so it now derives from `updateEmailMutation.status` directly.
+ *
+ * `useX(dependencies)` / `useWiredX()` conversion (2026-08-14): every `api.xxx()` call below is now
+ * `port.xxx()` — see `users-port.hooks.ts` for the interface and `users-dependencies.hooks.ts` for
+ * the real binding, the only file left that imports `lib/api` as a value for this feature. `port` is
+ * captured once from `deps` and read directly inside the `useFetchQuery`/`useFetchMutation` closures
+ * below, which is safe without the ref-and-dep-array discipline the host admin guidance's "Two traps"
+ * section describes for a hand-rolled `useEffect`: TanStack's `useQuery`/`useMutation` (this file's
+ * actual I/O primitive, via `lib/fetch-query`) take a fresh `queryFn`/`mutationFn` closure every
+ * render by design and do not require referential stability to avoid a refetch loop, unlike a raw
+ * `useEffect([port])`. There is no dependency array in this file for `port` to be listed in wrongly.
+ */
 export interface UsersController {
+    /** `null` until the initial load settles — the caller renders a loading state. Loaded together
+     *  with `roles`/`policies` via `Promise.all`, so all three settle on the same render. */
     users: AdminIdentityUser[] | null;
+    /** `[]` (with `canGrant` false) when the caller may not read roles/policies — see {@link canGrant}. */
     roles: AdminRole[] | null;
     policies: AdminPolicy[] | null;
+    /**
+     * Whether the caller may read (and so grant) roles and policies. The roster route admits
+     * `user.manage` OR `member.manage`, but `/roles` and `/policies` require `role.manage`; a 403 from
+     * those two hides the grant controls instead of failing the whole screen, so the roster the
+     * operator CAN read still shows.
+     */
+    canGrant: boolean;
     error: string | null;
+    /** Whether the "New user" form is expanded. */
     formOpen: boolean;
     setFormOpen: Dispatch<SetStateAction<boolean>>;
     username: string;
@@ -18,6 +87,7 @@ export interface UsersController {
     saving: boolean;
     formError: string | null;
     onCreate: (e: FormEvent) => Promise<void>;
+    /** The row whose "Manage" panel is expanded — `null` when every row is collapsed. */
     expandedId: string | null;
     toggleExpanded: (user: AdminIdentityUser) => void;
     pendingRoleId: string;
@@ -32,20 +102,30 @@ export interface UsersController {
     onAttachPolicy: (required: {
         principalId: string;
     }) => Promise<void>;
+    /** The "Manage" panel's own email field — seeded from `user.email` when the panel opens. */
     editEmail: string;
     setEditEmail: Dispatch<SetStateAction<string>>;
     emailSaving: boolean;
     onSaveEmail: (required: {
         principalId: string;
     }) => Promise<void>;
+    /** In-flight Disable/Enable request, keyed by `principalId` — one at a time. */
     toggleSavingId: string | null;
     toggleError: string | null;
     notice: string | null;
+    /** The user a `RowMenu` "Disable" selection is asking to confirm; `null` when the dialog is
+     *  shut. `ConfirmDialog` stays mounted unconditionally in the view (see its own doc comment on
+     *  why); this is what drives its `open` prop. */
     confirmingDisable: AdminIdentityUser | null;
     setConfirmingDisable: Dispatch<SetStateAction<AdminIdentityUser | null>>;
+    /** Opens the Disable confirm dialog for `user` — the `RowMenu` "Disable" item's `onSelect` when
+     *  the user is currently active (Enable, by contrast, fires immediately via `onToggleStatus`). */
     requestDisable: (user: AdminIdentityUser) => void;
     confirmDisable: () => Promise<void>;
     onToggleStatus: (user: AdminIdentityUser) => Promise<void>;
+    /** The user a `RowMenu` "Reset password" selection is asking about; `null` when the dialog is
+     *  shut. Kept open on failure (unlike the Disable dialog, which closes either way) so a failed
+     *  attempt doesn't discard the password the operator just typed. */
     resetPasswordFor: AdminIdentityUser | null;
     setResetPasswordFor: Dispatch<SetStateAction<AdminIdentityUser | null>>;
     newPassword: string;
@@ -55,15 +135,40 @@ export interface UsersController {
     setPasswordError: Dispatch<SetStateAction<string | null>>;
     openResetPassword: (user: AdminIdentityUser) => void;
     confirmResetPassword: () => Promise<void>;
+    /** Delete-user plan v2 (2026-09-24), Slice 4: whether the SIGNED-IN caller may trash users at all
+     *  — from `port.me()`'s `canManageUserTrash`, resolved by the same one-shot effect that already
+     *  fetches `ownPrincipalId`. `false` until that call settles (or forever if it fails), the same
+     *  "unknown defaults to no affordance" convention `ownPrincipalId`'s doc comment describes. Drives
+     *  `rules.ts`'s `userRowMenuItems` `canDelete` param — see that function's own doc comment for why
+     *  the real boundary is server-side, not this flag. */
     canManageUserTrash: boolean;
+    rowCapabilities: (user: AdminIdentityUser) => UserAccountCapabilities;
+    /** The user a `RowMenu` "Delete" selection is asking to confirm; `null` when the dialog is shut.
+     *  Mirrors `confirmingDisable` exactly (own state, own request/confirm pair) rather than sharing
+     *  it — Delete and Disable are two independent confirms an operator could otherwise not tell apart
+     *  if they shared one slot. */
     confirmingDelete: AdminIdentityUser | null;
     setConfirmingDelete: Dispatch<SetStateAction<AdminIdentityUser | null>>;
+    /** Opens the Delete confirm dialog for `user` — the `RowMenu` "Delete" item's `onSelect`. Never
+     *  fires immediately (see `rules.ts`'s `UserRowMenuHandlers.onRequestDelete` doc comment). */
     requestDelete: (user: AdminIdentityUser) => void;
+    /** In flight while the delete mutation is pending — drives the confirm dialog's `pending` prop,
+     *  same role `toggleSavingId` plays for the Disable dialog. */
     deleteSaving: boolean;
     confirmDelete: () => Promise<void>;
+    /** Bound translator — `key` already resolved against the caller's locale, so `Users.tsx` never
+     *  imports `useAdminLocale`/`users-i18n` itself. See this file's header. */
     t: (key: string) => string;
+    /** Host-bound translation also resolves row menus without a package locale dependency. */
     translate: Translate;
 }
+/** What `useUsers` needs injected from outside — see this file's header for the conversion note.
+ *
+ *  `openOwnPasswordReset`/`navigate` (password-banner plan, 2026-09-24 Slice 3): the dashboard nag's
+ *  "Change password" link deep-links to `/admin/users/change-password`, which `panels.tsx` turns
+ *  into this flag. Both are optional so every existing `useUsers({ port })` call (this file's own
+ *  tests, `Users.tsx`'s default) keeps working unchanged — the deep link is additive behavior, not a
+ *  new required collaborator. */
 export interface UsersDependencies {
     port: UsersPort;
     translate: Translate;
@@ -72,6 +177,18 @@ export interface UsersDependencies {
 export interface UsersOptions {
     openOwnPasswordReset?: boolean | undefined;
     onOwnPasswordResetClosed?: (() => void) | undefined;
+    /** Host formatting keeps dynamic username templates in the host's dictionary. */
+    passwordResetNotice?: ((required: {
+        username: string;
+    }) => string) | undefined;
 }
-export declare function useUsers({ port, translate, queryScope }: UsersDependencies, { openOwnPasswordReset, onOwnPasswordResetClosed }?: UsersOptions): UsersController;
+/**
+ * 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
+ * `useFetchQuery`/`useFetchMutation` migration and the `port` injection it now also carries.
+ *
+ * @param deps - Injected collaborators; production callers get these from {@link useWiredUsers}.
+ * @returns The full `UsersController` the view renders from — see that interface for every field.
+ */
+export declare function useUsers({ port, translate, queryScope }: UsersDependencies, { openOwnPasswordReset, onOwnPasswordResetClosed, passwordResetNotice, }?: UsersOptions): UsersController;
 //# sourceMappingURL=use-users.hooks.d.ts.map