@jini-ai/user-management 0.2.0 → 0.3.1

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

@@ -1,26 +1,100 @@
-import type { Translate } from "@jini-ai/ui/panel-kit";
 import { type Dispatch, type SetStateAction } from "react";
 import type { AdminIdentityUser, AdminPolicy, AdminRole } from "../models.js";
+import { type UserAccountCapabilities } from "./rules.js";
 import { useUsers, type UsersDependencies, type UsersOptions } from "./hooks/use-users.hooks.js";
+import type { ReactNode } from "react";
+import type { Translate } from "@jini-ai/ui/panel-kit";
+/**
+ * @file Admin "Users" screen (SPEC-006 §3 human grant-writing transitions + 0.6.0 CRUD-completion
+ * amendment) — markup only.
+ *
+ * State and API calls live in `hooks/use-users.hooks.ts`; the row-menu logic and the
+ * server-error-message overrides live in `rules.ts`. What stays here is what actually renders: the
+ * form, the table, and the two dialogs.
+ *
+ * Mirrors `features/integrations/Integrations.tsx`'s fetch/loading/error/form/table shape.
+ * Lists operator users, creates new ones (`CREATE_USER`), and grants roles/
+ * policies to an existing user (`ASSIGN_ROLE`/`ATTACH_POLICY`) via an
+ * inline expandable "Manage" row. Role/policy *creation* is out of
+ * this screen's UI (no `CREATE_ROLE`/`CREATE_POLICY` form here) — the API
+ * client exposes `api.createRole`/`api.createPolicy` for the Roles &
+ * Permissions screen to reuse.
+ *
+ * 0.6.0: the same expandable row also carries `UPDATE_USER` (email),
+ * `RESET_USER_PASSWORD`, and a quick `DISABLE_PRINCIPAL`/`ENABLE_PRINCIPAL` toggle.
+ *
+ * Row actions (audit follow-up): all three of the above — Disable/Enable, Manage (opens the
+ * expandable row), Reset password — now live behind a single three-dot `RowMenu`, matching
+ * `Posts.tsx`/`Pages.tsx`'s row-action shape rather than a row of separate buttons.
+ *
+ * Delete-user plan v2 (2026-09-24): a fourth "Delete" item joins the menu, shown only when the
+ * signed-in caller may manage the user Trash (owner or the built-in `admin` role — OWNER DECISION
+ * 2026-09-24, `use-users.hooks.ts`'s `canManageUserTrash`). It moves the target to the Trash
+ * (disabled, sessions revoked, restorable there for 60 days) rather than hard-deleting it — see
+ * `UserDeleteDialog`'s own doc comment.
+ *
+ * Complexity-ceiling pass (2026-08-06): `Users` and its row-map closure both scored over the
+ * ceiling (19/16 and 11/11 respectively). Split into four top-level, individually-testable
+ * functions below — `NewUserForm`, `UsersTable`/`UserRow`, `UserDisableDialog`/`UserDeleteDialog`,
+ * `UserResetPasswordDialog` — following `Taxonomy.tsx`'s existing convention of sibling top-level
+ * function components in the same file rather than nested closures (a nested `const` inside
+ * `Users` would not have moved any branching out of `Users`' own scope). `Users` itself is now a
+ * thin composition of those, none of them exported, so no test does anything `Users.tsx`
+ * didn't already support — see `__tests__/Users.unit.test.tsx`/`Users.crud.unit.test.tsx` for the
+ * full-render tests these were extracted underneath (unchanged), plus new
+ * `__tests__/users-components.unit.test.tsx` for direct component-level tests of each piece.
+ *
+ * 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
+ * purely local/ephemeral — never sent to the server, so they don't belong in `use-users.hooks.ts`'s
+ * screen-wide `UsersController`). The confirm-vs-server-error display conflict is resolved by giving
+ * the two states one shared slot with a fixed precedence — a live mismatch always wins over a stale
+ * `passwordError` from a previous attempt — rather than trying to show both at once or inventing a
+ * second error line; see `UserResetPasswordDialog`'s own body for the exact ternary. `RevealablePasswordField`
+ * 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;
-    openOwnPasswordReset?: boolean | undefined;
+    /** The host owns localization of protocol status/role labels. */
+    renderServerLabel?: ((required: {
+        value: string;
+    }) => ReactNode) | 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. */
 export interface GrantOption {
     id: string;
     name: string;
     isBuiltin: boolean;
 }
+/** One "pick something, then grant it to this user" control. Both grants on the Manage panel are
+ *  this same shape, which is what lets them share {@link GrantSelect} instead of being two
+ *  near-identical blocks whose props had to be threaded separately. */
 export interface GrantSelectController {
     options: GrantOption[];
+    /** The id currently selected in the `<select>`, or `""` for the placeholder row. */
     pendingId: string;
     setPendingId: Dispatch<SetStateAction<string>>;
     submit: (required: {
         principalId: string;
     }) => Promise<void>;
 }
+/**
+ * Everything the expanded "Manage" panel needs, as one object.
+ *
+ * Replaces the fifteen loose state/setter/callback props this panel used to take and `UserRow` used
+ * to relay through an `Omit<UserManagePanelProps, "principalId">` rest spread. The grouping is by
+ * interaction, not by convenience: the email editor and the two grants are three independent
+ * controls that happen to share one error line and one in-flight flag, and saying so in the type is
+ * what lets a test build a Manage panel without also standing up a row, a table, and a page.
+ */
 export interface UserManageController {
+    /** The one error line the whole panel shares — any of the three writes can set it. */
     error: string | null;
+    /** Shared by both grants: the panel issues one grant at a time. */
     saving: boolean;
     email: {
         value: string;
@@ -30,43 +104,68 @@ export interface UserManageController {
             principalId: string;
         }) => Promise<void>;
     };
-    roleGrant: GrantSelectController;
-    policyGrant: GrantSelectController;
+    /** `null` when the caller may not read roles/policies (`UsersController.canGrant`): no grant controls. */
+    roleGrant: GrantSelectController | null;
+    policyGrant: GrantSelectController | null;
 }
 export interface UserManagePanelProps {
     principalId: string;
     manage: UserManageController;
     t: (key: string) => string;
+    /** The table's column count, so the panel row spans it exactly (fewer without Roles/Policies). */
+    colSpan?: number;
 }
-export declare function UserManagePanel({ principalId, manage, t }: UserManagePanelProps): import("react").JSX.Element;
+/** 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 declare function UserManagePanel({ principalId, manage, t, colSpan }: UserManagePanelProps): import("react").JSX.Element;
+/** A user row's own affordances — expand/collapse and the three menu actions. Distinct from
+ *  {@link UserManageController}, which describes what the expanded panel does once it is open. */
 export interface UserRowActionsController {
     expandedId: string | null;
     toggleExpanded: (user: AdminIdentityUser) => void;
+    /** Which row has a status write in flight — drives that row's disabled menu item only. */
     savingId: string | null;
     requestDisable: (user: AdminIdentityUser) => void;
     toggleStatus: (user: AdminIdentityUser) => Promise<void>;
     openResetPassword: (user: AdminIdentityUser) => void;
+    /** Delete-user plan v2 (2026-09-24): whether the row's `RowMenu` should carry a "Delete" item at
+     *  all — see `use-users.hooks.ts`'s `canManageUserTrash` doc comment for where this comes from. */
     canDelete: boolean;
+    rowCapabilities?: (user: AdminIdentityUser) => UserAccountCapabilities;
     requestDelete: (user: AdminIdentityUser) => void;
 }
 export interface UserRowProps {
     user: AdminIdentityUser;
     roleById: ReadonlyMap<string, AdminRole>;
     policyById: ReadonlyMap<string, AdminPolicy>;
+    /** Whether the Roles/Policies cells render — see {@link UsersTableProps.showGrants}. */
+    showGrants: boolean;
     actions: UserRowActionsController;
     manage: UserManageController;
+    /** This row's own distinct handle base — computed once, across every rendered row, by
+     *  `UsersTable` (via `buildAgentListHandles`); see `Taxonomy.tsx`'s `NewTermForm.agentBase` for
+     *  why a per-instance uniqueness search does not work here. */
     agentBase: string;
     t: (key: string) => string;
     translate: Translate;
+    renderServerLabel?: UsersProps["renderServerLabel"];
 }
 export interface UsersTableProps {
     users: AdminIdentityUser[];
+    /** 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[];
     policies: AdminPolicy[];
+    /** `UsersController.canGrant`: without `role.manage` there are no names to resolve grant ids
+     *  against, so the Roles/Policies columns are left out rather than showing raw ids. */
+    showGrants: boolean;
     actions: UserRowActionsController;
     manage: UserManageController;
     t: (key: string) => string;
     translate: Translate;
+    renderServerLabel?: UsersProps["renderServerLabel"];
 }
-export declare function Users({ useUsersHook, port, translate: injectedTranslate, queryScope, openOwnPasswordReset, onOwnPasswordResetClosed }: UsersProps): import("react").JSX.Element;
+export declare function Users({ useUsersHook, port, translate: injectedTranslate, queryScope, openOwnPasswordReset, onOwnPasswordResetClosed, passwordResetNotice, renderServerLabel }: UsersProps): import("react").JSX.Element;
 //# sourceMappingURL=Users.d.ts.map

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);