@eifi1/ui-kit 0.29.0 → 0.31.0

package/src/admin/reviewer-scope-editor.tsx

@@ -0,0 +1,234 @@
+import { useState } from "react";
+import type { ReactNode } from "react";
+import { useKitLabels } from "../i18n/kit-labels";
+import { KIT_LANGUAGES } from "../i18n/languages";
+import type { KitLanguageCode } from "../i18n/languages";
+import { AlertBanner } from "../components/alert-banner";
+import { CheckboxGroup } from "../components/checkbox-group";
+import type { CheckboxGroupOption } from "../components/checkbox-group";
+import { FormActions } from "../components/form-actions";
+import { Caption } from "../components/text";
+import { hasMessage } from "./admin-parts";
+import type { MaybePromise } from "./admin-parts";
+
+/**
+ * Who may review which translations: the REVIEWER role and its scope, in one editor
+ * (docs/user-admin-harmonization.md §4.1 `PUT /admin/users/{id}/reviewer {locales, areas}`,
+ * §7). It replaces three: keksdose's `user-reviewer-role.tsx` (a checkbox per language,
+ * saved on each click), Kurvenschmiede's `reviewer-dialog.tsx` (a `CheckboxGroup` in a
+ * dialog with Save) and kastlan's platform column.
+ *
+ * - **Languages** are the scope. Ticking none takes the role away — that is how both
+ *   apps remove a reviewer — and the editor says so under the boxes.
+ * - **Areas** narrow it: "Only the legal pages" (Imprint, Privacy Policy, Terms) for a
+ *   lawyer, who reads law, not French. An area only means something beside at least one
+ *   language, so the areas wait for one. Saved as `areas: null` when none is ticked —
+ *   server-kit's "every area" — never `[]`, which would be "no area at all".
+ *
+ * A draft with Save, not a save per click: keksdose saved every tick, and two quick ticks
+ * could land as a set nobody chose; one Save sends the whole scope, in the languages'
+ * order (CheckboxGroup's), so the answer equals the request and the row does not
+ * reshuffle on refetch. The server keeps its rules (an admin reviews everything already,
+ * a customer is not given the role): `disabledReason` says them here.
+ */
+
+/** A reviewer's scope — the request body of `PUT …/reviewer`. */
+export interface ReviewerScope {
+  /** Language codes, in the editor's order. Empty: not a reviewer. */
+  locales: string[];
+  /** The areas the scope is narrowed to; `null` = every area (server-kit's rule). */
+  areas: string[] | null;
+}
+
+/** One area the scope can be narrowed to. */
+export interface ReviewerScopeArea {
+  value: string;
+  label: ReactNode;
+  hint?: ReactNode;
+}
+
+/** One language the editor offers, when the app's list is not the kit's codes. */
+export interface ReviewerScopeLanguage {
+  value: string;
+  label: ReactNode;
+}
+
+/** The `reviewerScope` namespace. */
+export interface ReviewerScopeLabels {
+  /** The language group's legend. */
+  languages: string;
+  /** Under the languages. */
+  hint: string;
+  /** Under the languages while none is ticked. */
+  none: string;
+  /** The area group's legend. */
+  areas: string;
+  /** The default area, `legal`. */
+  legalOnly: string;
+  legalOnlyHint: string;
+  /** A rejected save, unless `describeError` says better. */
+  failed: string;
+}
+
+export const DEFAULT_REVIEWER_SCOPE_LABELS: ReviewerScopeLabels = {
+  languages: "Languages",
+  hint: "Tick the languages this person reviews.",
+  none: "No language: saving takes the reviewer role away.",
+  areas: "Limit to",
+  legalOnly: "Only the legal pages",
+  legalOnlyHint: "Imprint, Privacy Policy and Terms — for a lawyer rather than a native speaker.",
+  failed: "The reviewer scope couldn’t be saved. Please try again.",
+};
+
+export interface ReviewerScopeEditorProps {
+  /** The scope the server has — the draft starts from it. Key the editor by the
+   *  account (`key={user.id}`) so another account starts a fresh draft. */
+  value: { locales?: readonly string[] | null; areas?: readonly string[] | null };
+  /** Sends the scope. A promise keeps the editor busy, and a rejection keeps the draft
+   *  and shows why. */
+  onSave: (scope: ReviewerScope) => MaybePromise;
+  /** A Cancel beside Save — a dialog's way out. */
+  onCancel?: () => void;
+  /**
+   * The languages offered: kit codes (named by the kit's registry, each in its own
+   * language — "Deutsch", "Français") or the app's own `{ value, label }` rows. Default:
+   * all seven of the kit's.
+   */
+  languages?: readonly KitLanguageCode[] | readonly ReviewerScopeLanguage[];
+  /** The areas the scope can be narrowed to. Default: `legal` alone. `[]` for none. */
+  areas?: readonly ReviewerScopeArea[];
+  /** Why the scope cannot be changed for this account ("Administrators review every
+   *  language already"). Every box says it; there is no Save. */
+  disabledReason?: ReactNode;
+  /** The app's words for a failed save. */
+  describeError?: (error: unknown) => ReactNode | undefined;
+  /** Over the languages: what the role is, in the app's words. */
+  intro?: ReactNode;
+  /** Columns for the languages from `sm` up. Default 2 (Kurvenschmiede's dialog). */
+  columns?: 1 | 2 | 3 | 4;
+  /** Save COMMITS: under a locked `WriteLockProvider` it is held with the lock's reason. */
+  commit?: boolean;
+  labels?: Partial<ReviewerScopeLabels>;
+}
+
+function languageOptions(languages: ReviewerScopeEditorProps["languages"]): CheckboxGroupOption[] {
+  const rows = languages ?? KIT_LANGUAGES.map((language) => language.code);
+  return rows.map((row) => {
+    if (typeof row !== "string") return { value: row.value, label: row.label };
+    const language = KIT_LANGUAGES.find((entry) => entry.code === row);
+    return {
+      value: row,
+      // Each name in its own language, marked so a screen reader says it so.
+      label: language ? <span lang={language.formatLocale}>{language.nativeName}</span> : row,
+    };
+  });
+}
+
+/** The same set, regardless of order. */
+function sameSet(a: readonly string[], b: readonly string[]): boolean {
+  if (a.length !== b.length) return false;
+  const seen = new Set(a);
+  return b.every((x) => seen.has(x));
+}
+
+export function ReviewerScopeEditor({
+  value,
+  onSave,
+  onCancel,
+  languages,
+  areas: areasProp,
+  disabledReason,
+  describeError,
+  intro,
+  columns = 2,
+  commit,
+  labels: labelsProp,
+}: ReviewerScopeEditorProps) {
+  const labels = useKitLabels("reviewerScope", DEFAULT_REVIEWER_SCOPE_LABELS, labelsProp);
+  const areaOptions: readonly ReviewerScopeArea[] =
+    areasProp ?? [{ value: "legal", label: labels.legalOnly, hint: labels.legalOnlyHint }];
+  const savedLocales = [...(value.locales ?? [])];
+  const savedAreas = [...(value.areas ?? [])];
+  const [locales, setLocales] = useState<string[]>(savedLocales);
+  const [areas, setAreas] = useState<string[]>(savedAreas);
+  const [pending, setPending] = useState(false);
+  const [failure, setFailure] = useState<ReactNode>(null);
+  const locked = hasMessage(disabledReason);
+
+  const nextAreas = locales.length === 0 ? [] : areas;
+  const dirty = !sameSet(locales, savedLocales) || !sameSet(nextAreas, locales.length === 0 ? [] : savedAreas);
+
+  const save = () => {
+    if (pending || locked || !dirty) return;
+    const scope: ReviewerScope = {
+      locales,
+      areas: locales.length > 0 && areas.length > 0 ? areas : null,
+    };
+    setFailure(null);
+    let result: MaybePromise;
+    try {
+      result = onSave(scope);
+    } catch (error) {
+      setFailure(describeError?.(error) ?? labels.failed);
+      return;
+    }
+    if (!result || typeof result.then !== "function") return;
+    setPending(true);
+    result.then(
+      () => setPending(false),
+      (error: unknown) => {
+        setPending(false);
+        const own = describeError?.(error);
+        setFailure(hasMessage(own) ? own : labels.failed);
+      },
+    );
+  };
+
+  return (
+    <div className="space-y-3">
+      {intro && <div className="text-sm text-[var(--text-secondary)]">{intro}</div>}
+      <CheckboxGroup
+        legend={labels.languages}
+        options={languageOptions(languages)}
+        value={locales}
+        onChange={(next) => {
+          setFailure(null);
+          setLocales(next);
+        }}
+        columns={columns}
+        hint={locked ? undefined : locales.length === 0 ? labels.none : labels.hint}
+        disabledReason={disabledReason}
+      />
+      {areaOptions.length > 0 && (
+        <CheckboxGroup
+          legend={labels.areas}
+          options={areaOptions.map((area) => ({ value: area.value, label: area.label, hint: area.hint }))}
+          value={nextAreas}
+          onChange={(next) => {
+            setFailure(null);
+            setAreas(next);
+          }}
+          // An area narrows a language scope; with no language there is none to narrow.
+          disabled={locales.length === 0}
+          disabledReason={disabledReason}
+        />
+      )}
+      {failure && (
+        <AlertBanner tone="danger" size="sm">
+          {failure}
+        </AlertBanner>
+      )}
+      {locked ? (
+        <Caption>{disabledReason}</Caption>
+      ) : (
+        <FormActions
+          onSubmit={save}
+          onCancel={onCancel}
+          pending={pending}
+          submitDisabled={!dirty}
+          commit={commit}
+        />
+      )}
+    </div>
+  );
+}

package/src/admin/role-select.tsx

@@ -0,0 +1,286 @@
+import type { ReactNode } from "react";
+import { useKitLabels } from "../i18n/kit-labels";
+import type { RoleVocabulary } from "../components/account-chips";
+import { CheckboxGroup } from "../components/checkbox-group";
+import type { CheckboxGroupOption } from "../components/checkbox-group";
+import { Select } from "../components/ui";
+import type { SelectProps } from "../components/ui";
+
+/**
+ * The role of an account, chosen by an admin (docs/user-admin-harmonization.md §3.3,
+ * §4.1, §7): {@link RoleSelect} for the apps where an account has ONE role (keksdose,
+ * Kurvenschmiede) and {@link RolesEditor} for kastlan, where an account has several per
+ * company.
+ *
+ * Both take the app's {@link RoleVocabulary} — the one `RoleChip` reads — so a role is
+ * called the same in the chip, the select and the editor. Neither sends a request: a role
+ * change is an `acknowledge` action (§4.2), so the app opens `AdminActionConfirm` from
+ * `onChange` and the value stays where the server has it until the server says otherwise.
+ *
+ * WHY THE REASONS. The server refuses the last active admin's demotion (`last_admin`),
+ * your own admin role (`self`), Kurvenschmiede's CUSTOMER for an account that owns work,
+ * kastlan's TENANT until a tenant portal exists (§4.1, §9.6). A choice the server will
+ * refuse is shown as unavailable, with why, rather than offered and answered with an
+ * error after a confirmation dialog — the 0.18 write-lock rule: a control that cannot
+ * act says so where it is. `"last_admin"` and `"self"` are the kit's words in every
+ * language; anything else is the app's own sentence.
+ */
+
+/** A reason the kit words itself. `self_action` is the server's code for `self` (the
+ *  account error codes), so a refusal's code can be handed on as it came. */
+export type RoleLockCode = "last_admin" | "self" | "self_action";
+
+/**
+ * Why a role (or the whole control) cannot be changed: one of the kit's
+ * {@link RoleLockCode}s, or the app's own words.
+ */
+export type RoleLock = RoleLockCode | (string & {}) | ReactNode;
+
+/** The `roleSelect` namespace — RoleSelect's and RolesEditor's words. */
+export interface RoleSelectLabels {
+  /** The select's name where no `label` is drawn, and RolesEditor's legend. "Role". */
+  label: string;
+  /** RolesEditor's legend. "Roles". */
+  rolesLegend: string;
+  /** The select's accessible name in a roster row — "Role of Ada Example". */
+  roleOf: (name: string) => string;
+  /** The whole control is locked: the account is the last active administrator. */
+  lockedLastAdmin: string;
+  /** The whole control is locked: it is the admin's own account. */
+  lockedSelf: string;
+  /** One option is unavailable for the last active administrator — said after the
+   *  role's name, inside the option. */
+  notForLastAdmin: string;
+  /** One option is unavailable on the admin's own account. */
+  notForSelf: string;
+  /** An unavailable option's text: the role's name and why. */
+  unavailable: (role: string, reason: string) => string;
+}
+
+export const DEFAULT_ROLE_SELECT_LABELS: RoleSelectLabels = {
+  label: "Role",
+  rolesLegend: "Roles",
+  roleOf: (name) => `Role of ${name}`,
+  lockedLastAdmin: "The last active administrator keeps this role.",
+  lockedSelf: "You can’t change your own role.",
+  notForLastAdmin: "not for the last administrator",
+  notForSelf: "not for your own account",
+  unavailable: (role, reason) => `${role} (${reason})`,
+};
+
+/** The whole-control reason, the kit's codes in the kit's words. */
+function lockText(reason: RoleLock, labels: RoleSelectLabels): ReactNode {
+  if (reason === "last_admin") return labels.lockedLastAdmin;
+  if (reason === "self" || reason === "self_action") return labels.lockedSelf;
+  return reason;
+}
+
+/** An option's reason as the text a native `<option>` can hold. */
+function optionReasonText(reason: string, labels: RoleSelectLabels): string {
+  if (reason === "last_admin") return labels.notForLastAdmin;
+  if (reason === "self" || reason === "self_action") return labels.notForSelf;
+  return reason;
+}
+
+function present(node: ReactNode): boolean {
+  return node !== undefined && node !== null && node !== false && node !== "";
+}
+
+/** The vocabulary's keys, in its own order. */
+function keysOf<R extends string>(roles: RoleVocabulary<R>): R[] {
+  return Object.keys(roles) as R[];
+}
+
+/* ── RoleSelect ─────────────────────────────────────────────────────────────── */
+
+export interface RoleSelectProps<R extends string = string>
+  extends Omit<SelectProps, "value" | "defaultValue" | "onChange" | "children" | "multiple" | "disabledReason"> {
+  /** The role the server has. Controlled: a pick does not move the select until the
+   *  app's request lands and the row comes back with the new role. */
+  value: R | null | undefined;
+  /** The app's roles — what `RoleChip` reads. Their order is the list's. */
+  roles: RoleVocabulary<R>;
+  /** A role other than `value` was picked. The app asks `AdminActionConfirm` (an
+   *  `acknowledge` action, §4.2) and sends the change. */
+  onChange: (role: R) => void;
+  /**
+   * The roles that may be CHOSEN here, in the vocabulary's order whatever order this is
+   * in. Default: all of them. A role the account holds that is not offered (Kurvenschmiede's
+   * REVIEWER, given only through the reviewer scope, §9.6) is still shown, unavailable:
+   * a select that dropped it would show the account as something it is not.
+   */
+  offered?: readonly R[];
+  /**
+   * Why the whole choice is locked for this account: `"last_admin"`, `"self"`, or the
+   * app's own words. The select stays focusable and says so (Select's `disabledReason`).
+   */
+  disabledReason?: RoleLock;
+  /**
+   * Why ONE role cannot be chosen for this account: `"last_admin"`, `"self"`, or the
+   * app's own words (Kurvenschmiede: "owns work", for CUSTOMER) — a STRING, because a
+   * native option holds text only. The option is disabled and reads "Member (not for the
+   * last administrator)". `undefined` for an available role.
+   */
+  optionDisabledReason?: (role: R) => string | undefined;
+  /** The account's name, for the select's accessible name in a roster row ("Role of
+   *  Ada Example") where no `label` is drawn. */
+  name?: string;
+  labels?: Partial<RoleSelectLabels>;
+}
+
+/**
+ * One role, picked from the app's vocabulary — Kurvenschmiede's roster `Select`
+ * (users-panel.tsx), with the reasons it left to the server's toast drawn in place.
+ *
+ * Unlabelled by default, for a table cell: named "Role of Ada Example" (`name`) or
+ * "Role". Pass `label` for a form field. Every {@link Select} prop passes through
+ * (`size`, `commit`, `hint`, `error`, `data-*`).
+ */
+export function RoleSelect<R extends string = string>({
+  value,
+  roles,
+  onChange,
+  offered,
+  disabledReason,
+  optionDisabledReason,
+  name,
+  labels: labelsProp,
+  label,
+  ...rest
+}: RoleSelectProps<R>) {
+  const labels = useKitLabels("roleSelect", DEFAULT_ROLE_SELECT_LABELS, labelsProp);
+  const all = keysOf(roles);
+  const choosable = new Set<R>(offered ?? all);
+  const held = value ?? null;
+  // A cell has no room for a visible label: the select is named for the account it
+  // belongs to, so fifty of them in a roster are not fifty "Role"s.
+  const ariaLabel =
+    label === undefined ? (rest["aria-label"] ?? (name ? labels.roleOf(name) : labels.label)) : rest["aria-label"];
+  return (
+    <Select
+      {...rest}
+      label={label}
+      aria-label={ariaLabel}
+      value={held ?? ""}
+      disabledReason={present(disabledReason) ? lockText(disabledReason, labels) : undefined}
+      onChange={(event) => {
+        const next = event.target.value as R;
+        if (next && next !== held) onChange(next);
+      }}
+    >
+      {held === null && <option value="" disabled />}
+      {all
+        .filter((role) => choosable.has(role) || role === held)
+        .map((role) => {
+          const word = roles[role].label;
+          const reason = role === held ? undefined : optionDisabledReason?.(role);
+          const unavailable = !choosable.has(role) || present(reason);
+          return (
+            <option key={role} value={role} disabled={unavailable && role !== held}>
+              {reason ? labels.unavailable(word, optionReasonText(reason, labels)) : word}
+            </option>
+          );
+        })}
+      {/* A role the vocabulary does not know (an older client against a newer API) is
+          still the account's role: shown as its key, as RoleChip shows it. */}
+      {held !== null && !all.includes(held) && (
+        <option value={held} disabled>
+          {held}
+        </option>
+      )}
+    </Select>
+  );
+}
+
+/* ── RolesEditor ────────────────────────────────────────────────────────────── */
+
+export interface RolesEditorProps<R extends string = string> {
+  /** The roles ticked — the draft the app holds while its dialog is open. */
+  value: readonly R[];
+  roles: RoleVocabulary<R>;
+  /** The new set, in the vocabulary's order (a role the editor does not offer, but the
+   *  account holds, is kept after the rest — CheckboxGroup's rule). */
+  onChange: (roles: R[]) => void;
+  /** The roles that may be ticked or unticked here. Default: all. kastlan leaves TENANT
+   *  out until a tenant portal exists (§4.1). */
+  offered?: readonly R[];
+  /** Why nothing can be changed: `"last_admin"`, `"self"` or the app's words. */
+  disabledReason?: RoleLock;
+  /** Why one role cannot be changed — shown under it, and the box keeps its state:
+   *  `"last_admin"` on the last administrator's ADMIN, say. */
+  optionDisabledReason?: (role: R) => RoleLock | undefined;
+  /** Default `roleSelect.rolesLegend` — "Roles". kastlan names the company: "Roles in
+   *  Example Ltd". */
+  legend?: ReactNode;
+  legendVisibility?: "visible" | "sr-only";
+  /** At least one role (kastlan's dialog saves none). Draws the required star. */
+  required?: boolean;
+  hint?: ReactNode;
+  error?: ReactNode;
+  columns?: 1 | 2 | 3 | 4;
+  /** The editor SAVES on change — the write lock's opt-in (CheckboxGroup's `commit`). */
+  commit?: boolean;
+  className?: string;
+  labels?: Partial<RoleSelectLabels>;
+}
+
+/**
+ * Several roles at once — kastlan's manage-roles dialog (`ChoiceCardGroup multiple`),
+ * which holds an account's roles in the CURRENT company (§4.1: `PUT /admin/users/{id}/roles`).
+ * A kit {@link CheckboxGroup} of the vocabulary, with the reasons of {@link RoleSelect}:
+ * a role that cannot change keeps its box as it is and says why under it.
+ *
+ * A field, not a form: the app's dialog holds the draft, and its Save goes through
+ * `AdminActionConfirm` (`acknowledge`, §4.2) — which can draw this editor as its
+ * `children`, so the roles and the tick are one dialog.
+ */
+export function RolesEditor<R extends string = string>({
+  value,
+  roles,
+  onChange,
+  offered,
+  disabledReason,
+  optionDisabledReason,
+  legend,
+  legendVisibility,
+  required,
+  hint,
+  error,
+  columns,
+  commit,
+  className,
+  labels: labelsProp,
+}: RolesEditorProps<R>) {
+  const labels = useKitLabels("roleSelect", DEFAULT_ROLE_SELECT_LABELS, labelsProp);
+  const all = keysOf(roles);
+  const choosable = new Set<R>(offered ?? all);
+  const held = new Set<R>(value);
+  const options: CheckboxGroupOption<R>[] = all
+    .filter((role) => choosable.has(role) || held.has(role))
+    .map((role) => {
+      const reason = optionDisabledReason?.(role);
+      const locked = present(reason);
+      return {
+        value: role,
+        label: roles[role].label,
+        hint: locked ? lockText(reason, labels) : undefined,
+        disabled: locked || !choosable.has(role),
+      };
+    });
+  return (
+    <CheckboxGroup<R>
+      legend={legend ?? labels.rolesLegend}
+      legendVisibility={legendVisibility}
+      options={options}
+      value={[...value]}
+      onChange={onChange}
+      required={required}
+      hint={hint}
+      error={error}
+      columns={columns}
+      commit={commit}
+      disabledReason={present(disabledReason) ? lockText(disabledReason, labels) : undefined}
+      className={className}
+    />
+  );
+}

package/src/admin/transfer-ownership-dialog.tsx

@@ -0,0 +1,172 @@
+import { useState } from "react";
+import type { ReactNode } from "react";
+import { useKitLabels } from "../i18n/kit-labels";
+import { Select } from "../components/ui";
+import { Caption } from "../components/text";
+import { AdminActionConfirm } from "./admin-action-confirm";
+import type { AdminActionTarget, AdminConfirmLevel } from "./admin-action-confirm";
+import { usePersonLabel } from "./admin-parts";
+import type { AdminPerson, MaybePromise } from "./admin-parts";
+
+/**
+ * Hand an account's owned work to another account — Kurvenschmiede's `TypedConfirm`
+ * with its recipient select (features/admin/typed-confirm.tsx, users-panel.tsx;
+ * docs/user-admin-harmonization.md §4.1 `POST /admin/users/{id}/transfer {to,
+ * confirm_email}`, §4.2: `type_email`).
+ *
+ * It is {@link AdminActionConfirm} with the recipient as the action's own field: the
+ * typed address is the SOURCE account's — the one whose work moves, which is the row the
+ * admin must prove they are on — and the confirm waits for a recipient too.
+ *
+ * WHO MAY RECEIVE IT (§9.6): never a customer, never a deactivated account, never the
+ * account itself. The APP decides — it knows its roles and states — and marks each
+ * candidate with why it cannot (`unavailable`); the kit shows those accounts, unavailable,
+ * with the reason, rather than leaving the admin to wonder where somebody went. The
+ * source account is marked `self` here whether or not the app did.
+ */
+
+/** Why a candidate cannot receive the work: the kit's three, or the app's own words. */
+export type TransferUnavailable = "customer" | "deactivated" | "self";
+
+/** An account that might receive the work. */
+export interface TransferCandidate extends AdminPerson {
+  id: string | number;
+  email: string;
+  /** Why it cannot: `"customer"`, `"deactivated"`, `"self"`, or the app's own words. */
+  unavailable?: TransferUnavailable | (string & {});
+}
+
+/** What {@link TransferOwnershipDialogProps.onTransfer} receives — the request body. */
+export interface TransferValues {
+  toUserId: string | number;
+  /** The source account's address as typed (at `type_email`). */
+  confirmEmail?: string;
+}
+
+/** The `transferOwnership` namespace. The guard and the refusals are `adminAction`'s
+ *  and `dangerConfirm`'s. */
+export interface TransferOwnershipLabels {
+  /** The heading — "Hand on Ada Example’s work". */
+  title: (name: string) => string;
+  /** What happens. */
+  body: string;
+  /** The recipient select's label. */
+  recipient: string;
+  /** Its empty first option. */
+  choose: string;
+  /** Why the confirm is held while nobody is chosen. */
+  chooseFirst: string;
+  /** The confirm button. */
+  confirm: string;
+  /** Reasons, said after the account's name inside its option. */
+  customer: string;
+  deactivated: string;
+  self: string;
+  /** An unavailable option's text: the account and why. */
+  unavailable: (account: string, reason: string) => string;
+  /** No account can receive it. */
+  noCandidates: string;
+}
+
+export const DEFAULT_TRANSFER_OWNERSHIP_LABELS: TransferOwnershipLabels = {
+  title: (name) => `Hand on ${name}’s work`,
+  body: "Everything this account owns moves to the account you choose, in one step.",
+  recipient: "Hand it to",
+  choose: "Choose an account…",
+  chooseFirst: "Choose who receives the work",
+  confirm: "Hand it on",
+  customer: "a customer",
+  deactivated: "deactivated",
+  self: "the same account",
+  unavailable: (account, reason) => `${account} (${reason})`,
+  noCandidates: "No other account can receive it.",
+};
+
+export interface TransferOwnershipDialogProps {
+  /** The account whose work moves — its address is what the admin types. */
+  from: AdminActionTarget;
+  /** Who might receive it, each marked with why not where it cannot. */
+  candidates: readonly TransferCandidate[];
+  /** What moves, in the app's words — "3 sessions · 1 gear · 2 projects" (counts, never
+   *  content). Under the sentence. */
+  summary?: ReactNode;
+  /** Sends it. Promise handling as {@link AdminActionConfirm}'s `onConfirm`. */
+  onTransfer: (values: TransferValues) => MaybePromise;
+  onClose: (done: boolean) => void;
+  /** The server's level for `transfer` — `type_email` (§4.2), the default. A transfer
+   *  always has a recipient to choose, so `none` asks as `acknowledge` does. */
+  level?: AdminConfirmLevel;
+  describeError?: (error: unknown) => ReactNode | undefined;
+  /** Kept-mounted mode. */
+  open?: boolean;
+  labels?: Partial<TransferOwnershipLabels>;
+}
+
+export function TransferOwnershipDialog({
+  from,
+  candidates,
+  summary,
+  onTransfer,
+  onClose,
+  level = "type_email",
+  describeError,
+  open,
+  labels: labelsProp,
+}: TransferOwnershipDialogProps) {
+  const labels = useKitLabels("transferOwnership", DEFAULT_TRANSFER_OWNERSHIP_LABELS, labelsProp);
+  const nameOf = usePersonLabel();
+  const [chosen, setChosen] = useState("");
+
+  const reasonOf = (candidate: TransferCandidate): string | undefined => {
+    const own = candidate.unavailable;
+    const isSource =
+      (from.id !== undefined && from.id !== null && candidate.id === from.id) ||
+      candidate.email.trim().toLowerCase() === from.email.trim().toLowerCase();
+    const code = isSource ? "self" : own;
+    if (!code) return undefined;
+    if (code === "customer") return labels.customer;
+    if (code === "deactivated") return labels.deactivated;
+    if (code === "self") return labels.self;
+    return code;
+  };
+
+  const rows = candidates.map((candidate) => {
+    const name = nameOf(candidate);
+    const shown = name && name !== candidate.email ? `${name} — ${candidate.email}` : candidate.email;
+    const reason = reasonOf(candidate);
+    return { candidate, value: String(candidate.id), text: reason ? labels.unavailable(shown, reason) : shown, reason };
+  });
+  const available = rows.filter((row) => !row.reason);
+  const recipient = available.find((row) => row.value === chosen)?.candidate;
+
+  return (
+    <AdminActionConfirm
+      open={open}
+      level={level === "none" ? "acknowledge" : level}
+      target={from}
+      title={labels.title(nameOf(from))}
+      consequence={labels.body}
+      confirmLabel={labels.confirm}
+      tone="danger"
+      confirmDisabledReason={
+        available.length === 0 ? labels.noCandidates : recipient === undefined ? labels.chooseFirst : undefined
+      }
+      onConfirm={(values) =>
+        recipient === undefined ? undefined : onTransfer({ toUserId: recipient.id, confirmEmail: values.confirmEmail })
+      }
+      onClose={onClose}
+      describeError={describeError}
+    >
+      {summary && <div className="text-sm text-[var(--text-secondary)]">{summary}</div>}
+      <Select label={labels.recipient} value={chosen} onChange={(event) => setChosen(event.target.value)}>
+        <option value="">{labels.choose}</option>
+        {rows.map((row) => (
+          <option key={row.value} value={row.value} disabled={Boolean(row.reason)}>
+            {row.text}
+          </option>
+        ))}
+      </Select>
+      {available.length === 0 && <Caption>{labels.noCandidates}</Caption>}
+    </AdminActionConfirm>
+  );
+}