@eifi1/ui-kit 0.28.1 → 0.29.0

package/src/i18n/locales/it.ts

@@ -838,6 +838,149 @@ export function uiKitLabelsIt(numberLocale = "it-IT"): UiKitLabels {
         },
       },
     },
+    // 0.29.0 — docs/auth-harmonization.md: keksdose's reviewed Italian (auth.*,
+    // verify_email, error.not_found_*, budget_share.join_*), kastlan's for the names and
+    // the 2FA prompt; written fresh where neither app had the sentence. Formal, "Lei" and
+    // "Suo" capitalised; headings addressed formally ("Scelga", not keksdose's "Scegli").
+    signIn: {
+      email: "Email",
+      password: "Password",
+      submit: "Accedi",
+      passkey: "Accedi con una passkey",
+      forgotPassword: "Password dimenticata?",
+      noAccount: "Non ha ancora un account?",
+      register: "Crea account",
+      invalidCredentials: "L’indirizzo email o la password non sono corretti.",
+      failed: "Accesso non riuscito. Riprovi.",
+      passkeyFailed: "Accesso con passkey non riuscito.",
+      deactivatedHint: "Account disattivato? Scriva a {contact}.",
+      // "Account creato con…" rather than "Si è registrato con…", which needs a gender.
+      tagHint: (taggedAddress) => `Account creato con ${taggedAddress}? Usi quell’indirizzo.`,
+      twoFactorTitle: "Autenticazione a due fattori",
+      twoFactorIntro: "Inserisca il codice mostrato dalla Sua app di autenticazione.",
+      code: "Codice 2FA",
+      verify: "Verifica",
+      codeInvalid: "Codice 2FA non valido.",
+      setPasswordTitle: "Scelga una nuova password",
+      setPasswordIntro:
+        "Per questo account è stata richiesta una nuova password. Ne scelga una e accederà subito.",
+      newPassword: "Nuova password",
+      confirmPassword: "Ripeti la nuova password",
+      passwordMismatch: "Le password non coincidono.",
+      setPasswordSubmit: "Imposta la password e accedi",
+      setPasswordFailed: "Impossibile impostare la password.",
+      expired: "Questo accesso è scaduto. Acceda di nuovo.",
+      backToSignIn: "Torna all’accesso",
+    },
+    register: {
+      firstName: "Nome",
+      lastName: "Cognome",
+      email: "Email",
+      emailTagUse: (address) => `Usa ${address}`,
+      emailTagHint:
+        "Molti provider recapitano nome+tag@… nella stessa casella, così la posta di questa app è filtrabile e riconoscibile. Verifichi che il Suo lo faccia prima di farci affidamento: accederebbe con l’indirizzo con il tag.",
+      invitedEmailHint: "L’indirizzo a cui è stato inviato il Suo invito.",
+      invitedTagNote: "L’indirizzo con il tag riceve una propria email di conferma.",
+      password: "Password",
+      confirmPassword: "Ripeti la password",
+      passwordMismatch: "Le password non coincidono.",
+      language: "Lingua",
+      submit: "Crea account",
+      haveAccount: "Ha già un account?",
+      signIn: "Accedi",
+      emailTaken: "Esiste già un account con questo indirizzo email.",
+      registrationClosed:
+        "I nuovi account si creano solo su invito. Chieda al gestore di invitare il Suo indirizzo email.",
+      invitationInvalid: "Questo link di invito non è valido.",
+      invitationExpired: "Questo invito è scaduto. Ne chieda uno nuovo.",
+      failed: "Registrazione non riuscita. Riprovi.",
+    },
+    completeName: {
+      title: "Completi il Suo nome",
+      description:
+        "Nome e cognome ora vengono richiesti separatamente. Controlli quanto è già compilato e aggiunga ciò che manca.",
+      firstName: "Nome",
+      lastName: "Cognome",
+      save: "Salva",
+      later: "Più tardi",
+      failed: "Impossibile salvare il Suo nome. Riprovi.",
+    },
+    forgotPassword: {
+      title: "Password dimenticata",
+      intro:
+        "Inserisca l’indirizzo email del Suo account. Le invieremo un link per scegliere una nuova password.",
+      email: "Email",
+      submit: "Invia il link",
+      sent: (email) => `Se esiste un account per ${email}, il link è in arrivo.`,
+      sentHint: "Il link è valido per un’ora e funziona una sola volta. Controlli anche la cartella spam.",
+      backToSignIn: "Torna all’accesso",
+      error: "Richiesta non riuscita. Riprovi più tardi.",
+    },
+    resetPassword: {
+      title: "Scelga una nuova password",
+      checking: "Verifica del link…",
+      intro: (email) => `Sta impostando una nuova password per ${email}.`,
+      newPassword: "Nuova password",
+      confirmPassword: "Ripeti la nuova password",
+      mismatch: "Le password non coincidono.",
+      submit: "Salva password",
+      failed: "Impossibile cambiare la password.",
+      noToken: "Questo link è incompleto.",
+      invalid: "Questo link non è valido o è scaduto.",
+      invalidHint:
+        "I link sono validi per un’ora e funzionano una sola volta. Ne richieda semplicemente uno nuovo.",
+      requestNew: "Richiedi un nuovo link",
+      success: "La Sua password è stata cambiata. Ora può accedere con quella.",
+      sessionsEnded: "I dispositivi connessi sono stati disconnessi: lì dovrà accedere di nuovo.",
+      signIn: "Vai all’accesso",
+    },
+    verifyEmail: {
+      title: "Confermi il Suo indirizzo email",
+      verifying: "Conferma in corso…",
+      verified: "Il Suo indirizzo email è confermato.",
+      continue: "Continua",
+      invalid: "Questo link di conferma non è valido",
+      expired: "Questo link di conferma è scaduto",
+      noToken: "A questo link manca il token di conferma.",
+      invalidHint: "Il link potrebbe essere scaduto o già stato usato.",
+      requestInApp: "Può richiederne uno nuovo dall’app.",
+      requestHere: "Può richiederne uno nuovo qui.",
+      resend: "Invia di nuovo",
+      resendIn: (seconds) => `Invia di nuovo tra ${n(seconds)} s`,
+      resent: "Email di conferma inviata",
+      resendError: "Impossibile inviare l’email di conferma",
+      banner: "Confermi il Suo indirizzo email.",
+      dismiss: "Non ora",
+    },
+    notFound: {
+      title: "Pagina non trovata",
+      body: "Questo indirizzo non esiste (più). Forse è un errore di battitura, oppure la pagina è stata spostata.",
+      home: "Vai alla pagina iniziale",
+      app: "Torna all’app",
+    },
+    acceptInvitation: {
+      title: "Accetta l’invito",
+      accepting: "Adesione in corso…",
+      accepted: "Invito accettato.",
+      // "Ora fa parte di…" rather than "Si è unito/a a…", which needs a gender.
+      joined: (name) => `Ora fa parte di ${name}.`,
+      continue: "Continua",
+      invalid: "Impossibile unirsi con questo link",
+      expired: "Questo invito è scaduto",
+      noToken: "A questo link manca il token di invito.",
+      askAgain: "Chieda a chi ha inviato l’invito di mandarne uno nuovo.",
+      signInFirst: "Acceda per accettare questo invito",
+      signInHint: "Usi l’account a cui è stato inviato l’invito.",
+      signIn: "Accedi",
+      register: "Crea account",
+    },
+    companySwitcher: {
+      switchCompany: "Cambia azienda",
+      heading: "Aziende",
+      current: (name) => `Azienda: ${name}`,
+      currentMark: "(attuale)",
+      switching: "Cambio azienda in corso…",
+    },
     characterCount: {
       count: (used, max) => `${n(used)} di ${n(max)} ${plural(max, "carattere", "caratteri")}`,
       remaining: (left) =>

package/src/i18n/locales/zh.ts

@@ -814,6 +814,144 @@ export function uiKitLabelsZh(numberLocale = "zh-CN"): UiKitLabels {
         },
       },
     },
+    // 0.29.0 — docs/auth-harmonization.md: Kurvenschmiede's reviewed Chinese (auth.*,
+    // notfound) where it says the same, brought into line with the kit's English and this
+    // catalogue's words ("通行密钥", "双重验证"); written fresh where Kurvenschmiede has no
+    // such text yet. Full-width punctuation; an interpolated address or name gets a space
+    // either side, none before full-width punctuation. It goes back to Kurvenschmiede for
+    // review.
+    signIn: {
+      email: "电子邮箱",
+      password: "密码",
+      submit: "登录",
+      passkey: "使用通行密钥登录",
+      forgotPassword: "忘记密码？",
+      noAccount: "还没有账户？",
+      register: "创建账户",
+      invalidCredentials: "电子邮箱或密码不正确。",
+      failed: "登录失败，请重试。",
+      passkeyFailed: "通行密钥登录失败。",
+      deactivatedHint: "账户已停用？请联系 {contact}。",
+      tagHint: (taggedAddress) => `注册时用的是 ${taggedAddress} 吗？请使用该地址。`,
+      twoFactorTitle: "双重验证",
+      twoFactorIntro: "请输入身份验证器应用显示的验证码。",
+      code: "验证码",
+      verify: "验证",
+      codeInvalid: "验证码无效。",
+      setPasswordTitle: "设置新密码",
+      setPasswordIntro: "已要求为此账户设置新密码。设置之后即可直接继续使用。",
+      newPassword: "新密码",
+      confirmPassword: "再次输入新密码",
+      passwordMismatch: "两次输入的密码不一致。",
+      setPasswordSubmit: "设置密码并登录",
+      setPasswordFailed: "无法设置密码。",
+      expired: "本次登录已过期，请重新登录。",
+      backToSignIn: "返回登录",
+    },
+    register: {
+      firstName: "名字",
+      lastName: "姓氏",
+      email: "电子邮箱",
+      emailTagUse: (address) => `使用 ${address}`,
+      emailTagHint:
+        "许多邮件服务商会把发往 name+tag@… 的邮件投递到同一个收件箱，这样本应用发来的邮件便于筛选和追溯。请先确认您的服务商支持这一点再使用：之后您需要用带标签的地址登录。",
+      invitedEmailHint: "接收邀请的地址。",
+      invitedTagNote: "带标签的地址会单独收到一封确认邮件。",
+      password: "密码",
+      confirmPassword: "再次输入密码",
+      passwordMismatch: "两次输入的密码不一致。",
+      language: "语言",
+      submit: "创建账户",
+      haveAccount: "已有账户？",
+      signIn: "登录",
+      emailTaken: "该电子邮箱地址已有账户。",
+      registrationClosed: "新账户仅限受邀注册。请联系运营者，为您的电子邮箱地址发送邀请。",
+      invitationInvalid: "此邀请链接无效。",
+      invitationExpired: "此邀请已过期，请索取新的邀请。",
+      failed: "注册失败，请重试。",
+    },
+    completeName: {
+      title: "完善您的姓名",
+      description: "现在需要分别填写名字和姓氏。请检查已填写的内容，并补充缺少的部分。",
+      firstName: "名字",
+      lastName: "姓氏",
+      save: "保存",
+      later: "稍后",
+      failed: "无法保存您的姓名，请重试。",
+    },
+    forgotPassword: {
+      title: "忘记密码",
+      intro: "请输入您账户的电子邮箱地址。我们会向您发送一个设置新密码的链接。",
+      email: "电子邮箱",
+      submit: "发送链接",
+      sent: (email) => `如果 ${email} 有账户，链接正在发送中。`,
+      sentHint: "该链接有效期一小时，且仅可使用一次。也请查看垃圾邮件文件夹。",
+      backToSignIn: "返回登录",
+      error: "请求失败，请稍后重试。",
+    },
+    resetPassword: {
+      title: "设置新密码",
+      checking: "正在检查链接…",
+      intro: (email) => `您正在为 ${email} 设置新密码。`,
+      newPassword: "新密码",
+      confirmPassword: "再次输入新密码",
+      mismatch: "两次输入的密码不一致。",
+      submit: "保存密码",
+      failed: "无法修改密码。",
+      noToken: "此链接不完整。",
+      invalid: "此链接无效或已过期。",
+      invalidHint: "链接有效期一小时，且仅可使用一次。重新申请一个即可。",
+      requestNew: "申请新链接",
+      success: "您的密码已修改，现在可以用它登录了。",
+      sessionsEnded: "已登录的设备均已退出登录——您需要在这些设备上重新登录。",
+      signIn: "前往登录",
+    },
+    verifyEmail: {
+      title: "确认您的电子邮箱地址",
+      verifying: "正在确认…",
+      verified: "您的电子邮箱地址已确认。",
+      continue: "继续",
+      invalid: "此确认链接无效",
+      expired: "此确认链接已过期",
+      noToken: "此链接缺少确认令牌。",
+      invalidHint: "该链接可能已过期或已被使用。",
+      requestInApp: "您可以在应用内申请新的链接。",
+      requestHere: "您可以在此申请新的链接。",
+      resend: "重新发送",
+      resendIn: (seconds) => `${n(seconds)} 秒后可重新发送`,
+      resent: "确认邮件已发送",
+      resendError: "无法发送确认邮件",
+      banner: "请确认您的电子邮箱地址。",
+      dismiss: "暂不",
+    },
+    notFound: {
+      title: "未找到页面",
+      body: "此地址不存在（或已不存在）。可能是输入有误，也可能是页面已被移动。",
+      home: "前往首页",
+      app: "返回应用",
+    },
+    acceptInvitation: {
+      title: "接受邀请",
+      accepting: "正在加入…",
+      accepted: "已接受邀请。",
+      joined: (name) => `您已加入 ${name}。`,
+      continue: "继续",
+      invalid: "无法通过此链接加入",
+      expired: "此邀请已过期",
+      noToken: "此链接缺少邀请令牌。",
+      askAgain: "请让邀请您的人重新发送一份邀请。",
+      signInFirst: "登录以接受此邀请",
+      signInHint: "请使用收到邀请的账户登录。",
+      signIn: "登录",
+      register: "创建账户",
+    },
+    companySwitcher: {
+      switchCompany: "切换公司",
+      heading: "公司",
+      current: (name) => `公司：${name}`,
+      currentMark: "（当前）",
+      switching: "正在切换公司…",
+    },
     characterCount: {
       count: (used, max) => `已输入 ${n(used)}/${n(max)} 个字符`,
       remaining: (left) => `还可输入 ${n(left)} 个字符`,

package/src/i18n/review.ts

@@ -294,4 +294,12 @@ export const KIT_LABEL_SAMPLES: Readonly<Record<string, readonly (readonly unkno
   "legal.sections.terms.language.body": operatorSample,
   "legal.translation.note": operatorSample,
   "legal.translation.show": operatorSample,
+  // 0.29.0: the sign-in and sign-up parts (docs/auth-harmonization.md).
+  "signIn.tagHint": [["{{taggedAddress}}"]],
+  "register.emailTagUse": [["{{address}}"]],
+  "forgotPassword.sent": [["{{email}}"]],
+  "resetPassword.intro": [["{{email}}"]],
+  "verifyEmail.resendIn": [[30]],
+  "acceptInvitation.joined": [["{{name}}"]],
+  "companySwitcher.current": [["{{name}}"]],
 };

package/src/index.ts

@@ -487,6 +487,59 @@ export type {
   LegalFramedSectionLabels,
 } from "./components/legal";
 export { LegalPage, LegalKitSection, LegalAcceptCheckbox, LEGAL_SKELETON } from "./components/legal-page";
+
+// 0.29.0 (docs/auth-harmonization.md): sign-in, sign-up and the signed-out pages — forms
+// that take callbacks and never send a request themselves — the person-name order of each
+// language, and kastlan's company switcher.
+export { SignInForm, DEFAULT_SIGN_IN_LABELS } from "./auth/sign-in-form";
+export type {
+  SignInFormProps,
+  SignInLabels,
+  SignInAnswer,
+  SignInStep,
+  SignInAction,
+  SignInCredentials,
+  SignInCodeValues,
+  SignInNewPasswordValues,
+} from "./auth/sign-in-form";
+export { RegisterForm, DEFAULT_REGISTER_LABELS } from "./auth/register-form";
+export type { RegisterFormProps, RegisterLabels, RegisterValues } from "./auth/register-form";
+export { CompleteNameDialog, DEFAULT_COMPLETE_NAME_LABELS } from "./auth/complete-name-dialog";
+export type { CompleteNameDialogProps, CompleteNameLabels, CompleteNameValues } from "./auth/complete-name-dialog";
+export { taggedEmail } from "./auth/email-tag";
+export { isAuthError, authErrorCode } from "./auth/auth-errors";
+export type { AuthErrorCode } from "./auth/auth-errors";
+export { ForgotPasswordForm, DEFAULT_FORGOT_PASSWORD_LABELS } from "./auth/forgot-password-form";
+export type { ForgotPasswordFormProps, ForgotPasswordLabels } from "./auth/forgot-password-form";
+export { ResetPasswordForm, DEFAULT_RESET_PASSWORD_LABELS } from "./auth/reset-password-form";
+export type {
+  ResetPasswordFormProps,
+  ResetPasswordLabels,
+  ResetPasswordCheck,
+  ResetPasswordValues,
+  ResetPasswordResult,
+} from "./auth/reset-password-form";
+export { VerifyEmailStatus, EmailVerificationBanner, DEFAULT_VERIFY_EMAIL_LABELS } from "./auth/verify-email";
+export type {
+  VerifyEmailStatusProps,
+  EmailVerificationBannerProps,
+  VerifyEmailLabels,
+  VerifyEmailFailure,
+} from "./auth/verify-email";
+export { NotFoundPage, DEFAULT_NOT_FOUND_LABELS } from "./auth/not-found-page";
+export type { NotFoundPageProps, NotFoundLabels } from "./auth/not-found-page";
+export { AcceptInvitation, DEFAULT_ACCEPT_INVITATION_LABELS } from "./auth/accept-invitation";
+export type {
+  AcceptInvitationProps,
+  AcceptInvitationLabels,
+  AcceptInvitationResult,
+  AcceptInvitationFailure,
+} from "./auth/accept-invitation";
+export type { AuthHeadingLevel } from "./auth/status-parts";
+export { formatPersonName, personInitials } from "./lib/person-name";
+export type { PersonName } from "./lib/person-name";
+export { CompanySwitcher, DEFAULT_COMPANY_SWITCHER_LABELS } from "./shell/company-switcher";
+export type { CompanySwitcherProps, CompanySwitcherLabels, CompanySwitcherCompany } from "./shell/company-switcher";
 export type {
   LegalPageProps,
   LegalKitSectionProps,

package/src/lib/person-name.ts

@@ -0,0 +1,157 @@
+/**
+ * A person's name as the reader's language writes it — the one rule of
+ * docs/auth-harmonization.md §3.2 for every place a name is shown: the top bar, the
+ * account menu, user lists, avatars, feedback, the greeting in a mail.
+ *
+ * WHY A FUNCTION AND NOT `${first} ${last}`. The three apps move from one free-text
+ * `display_name` to `first_name` + `last_name` (§2.3), and the moment a name has two
+ * parts, their ORDER is a language rule, not a data rule:
+ *
+ *  - "First Last" in de-CH, en, fr, it and es — "Ada Example";
+ *  - **"Last First" in hu** — Hungarian puts the family name first: "Example Ada";
+ *  - **"LastFirst" with no space in zh** — a Chinese name is written family name first
+ *    and run together: 李 + 小龙 → "李小龙". Only a name written in CJK characters,
+ *    though: BOTH parts must hold Han (or kana, or hangul) characters. A Latin name read
+ *    in Chinese stays as it is written — "Ada Lovelace", not "LovelaceAda" (the
+ *    coordinator's refinement of §3.2, 2026-10-06).
+ *
+ * WHOSE language (§3.2, §10.6): on screen the READER's, so this takes the locale of the
+ * UI, never the locale stored with the person. A mail uses the recipient's and a frozen
+ * stamp the author's — that is server-kit's `full_name(first, last, locale)`, which
+ * follows exactly these rules so a name reads the same in the app and in its mails.
+ *
+ * NOTHING IS GUESSED. Both parts are trimmed, and an empty part simply drops out: a
+ * migrated keksdose or Kurvenschmiede user keeps the whole old display name as the
+ * first name and an empty last name until they complete it (§3.3), and "Ada Example"
+ * with no last name must still read "Ada Example" — not "Ada Example " and not a split
+ * at the space. Inner spaces are the person's own and stay as typed.
+ *
+ * Only the language subtag counts ("de-CH" → "de", "zh-Hant-TW" → "zh"), and a language
+ * this does not know reads "First Last", the order of the kit's five other languages.
+ */
+
+/** The two parts of a person's name. Either may be missing or blank: a migrated row
+ *  has an empty `last` until it is completed (§3.3), and APIs send `null` for "none". */
+export interface PersonName {
+  /** The given name — `first_name`. */
+  first?: string | null;
+  /** The family name — `last_name`. */
+  last?: string | null;
+}
+
+type NameOrder = "given-first" | "family-first" | "family-first-joined";
+
+/** A part written in CJK characters: Han, and kana or hangul where they occur (a
+ *  Japanese or Korean name in a Chinese UI). One such character is enough. */
+const CJK = /\p{Script=Han}|\p{Script=Hiragana}|\p{Script=Katakana}|\p{Script=Hangul}/u;
+
+function language(locale: string | undefined): string {
+  return (locale ?? "").split(/[-_]/)[0]!.toLowerCase();
+}
+
+/**
+ * The order the reader's language writes THIS name in. See the module note: hu puts the
+ * family name first for every name; zh runs a CJK name together family-first and leaves
+ * any other name as it is written; the rest write the given name first. A part that is
+ * empty passes the CJK test, so a one-part name orders by the part it has. Called with
+ * at least one part filled in.
+ */
+function nameOrder(locale: string | undefined, first: string, last: string): NameOrder {
+  const lang = language(locale);
+  if (lang === "hu") return "family-first";
+  if (lang === "zh" && (!first || CJK.test(first)) && (!last || CJK.test(last))) {
+    return "family-first-joined";
+  }
+  return "given-first";
+}
+
+function clean(part: string | null | undefined): string {
+  return (part ?? "").trim();
+}
+
+/**
+ * The full name in the reader's order: "Ada Example" (en, de, fr, it, es), "Example Ada"
+ * (hu), "李小龙" (zh, for a name in CJK characters — "Ada Lovelace" stays so). Trimmed;
+ * with one part empty, the other alone; with both empty, `""` — so a caller can fall
+ * back with `||` (`formatPersonName(p, l) || email`).
+ *
+ * `locale` is the READER's — the UI language, `useKitLocale()` in a component. Left out,
+ * the given-name-first order.
+ */
+export function formatPersonName(name: PersonName, locale?: string): string {
+  const first = clean(name.first);
+  const last = clean(name.last);
+  if (!last) return first;
+  if (!first) return last;
+  switch (nameOrder(locale, first, last)) {
+    case "family-first":
+      return `${last} ${first}`;
+    case "family-first-joined":
+      return `${last}${first}`;
+    default:
+      return `${first} ${last}`;
+  }
+}
+
+/** One segmenter for every avatar on the page, made on first use. `null`: the runtime
+ *  has none, and code points have to do. */
+let graphemes: Intl.Segmenter | null | undefined;
+
+/** The first user-perceived character — "É" whether it was typed as one code point or
+ *  as E + a combining accent, a whole emoji rather than half a surrogate pair. */
+function firstGrapheme(text: string): string {
+  graphemes ??=
+    typeof Intl !== "undefined" && "Segmenter" in Intl
+      ? new Intl.Segmenter(undefined, { granularity: "grapheme" })
+      : null;
+  if (graphemes) {
+    const segment = graphemes.segment(text)[Symbol.iterator]().next();
+    if (!segment.done) return segment.value.segment;
+  }
+  return [...text][0] ?? "";
+}
+
+/** Upper case under the reader's rules (Turkish "i" → "İ"), and plain upper case for a
+ *  locale tag the runtime refuses rather than a thrown RangeError in a render. */
+function upper(text: string, locale: string | undefined): string {
+  try {
+    return text.toLocaleUpperCase(locale);
+  } catch {
+    return text.toUpperCase();
+  }
+}
+
+/**
+ * The initials for an avatar, in the same order as {@link formatPersonName}:
+ *
+ *  - "AE" for Ada Example in en, de, fr, it and es;
+ *  - "EA" in hu, family name first;
+ *  - **one character in zh for a name in CJK characters, the family name's first** —
+ *    "李" for 李小龙. Two Chinese characters are not initials, they are most of a name.
+ *    A Latin name in zh is "AE", as it is written.
+ *
+ * With only one part (a migrated user's whole old display name in `first`, §3.3), the
+ * initials are what {@link avatarInitials} has always made of a display name: the first
+ * letters of its first two words ("Ada Example" → "AE"), or the first two letters of a
+ * single word ("Ada" → "AD") — so nobody's avatar changes when their account migrates.
+ * In zh, a part in CJK characters gives its first character.
+ *
+ * `""` when both parts are blank; {@link UserAvatar} then falls back to the email.
+ */
+export function personInitials(name: PersonName, locale?: string): string {
+  const first = clean(name.first);
+  const last = clean(name.last);
+  if (!first && !last) return "";
+  const order = nameOrder(locale, first, last);
+  if (order === "family-first-joined") return upper(firstGrapheme(last || first), locale);
+  if (!first || !last) {
+    const words = (first || last).split(/\s+/);
+    const initials =
+      words.length >= 2
+        ? firstGrapheme(words[0]!) + firstGrapheme(words[1]!)
+        : [...words[0]!].slice(0, 2).join("");
+    return upper(initials, locale);
+  }
+  const pair = order === "family-first" ? [last, first] : [first, last];
+  return upper(firstGrapheme(pair[0]!) + firstGrapheme(pair[1]!), locale);
+}

package/src/shell/company-switcher.tsx

@@ -0,0 +1,140 @@
+import { useState } from "react";
+import type { ReactNode } from "react";
+import { Building2 } from "lucide-react";
+import { cn } from "../lib/cn";
+import { useKitLabels } from "../i18n/kit-labels";
+import { useAnnounce } from "../hooks/use-announce";
+import { Spinner } from "../components/ui";
+import { OptionSwitcherMenu } from "./option-switcher-menu";
+import { TOPBAR_TRIGGER_CLASS } from "./topbar-controls";
+
+/** Every string the switcher renders or speaks — the `companySwitcher` namespace. A
+ *  different context (keksdose's budgets) renames them all. */
+export interface CompanySwitcherLabels {
+  /** The trigger's and the menu's accessible name. */
+  switchCompany: string;
+  /** The small heading over the list. */
+  heading: string;
+  /** The trigger's tooltip (and description), given the current company's name. */
+  current: (name: string) => string;
+  /** Read after the current company's name in the list, where the eye sees a check. */
+  currentMark: string;
+  /** Said while a switch is running. */
+  switching: string;
+}
+
+export const DEFAULT_COMPANY_SWITCHER_LABELS: CompanySwitcherLabels = {
+  switchCompany: "Switch company",
+  heading: "Companies",
+  current: (name) => `Company: ${name}`,
+  currentMark: "(current)",
+  switching: "Switching company…",
+};
+
+/** One company the user belongs to — kastlan's `/auth/me` `companies[]` (§5.3). */
+export interface CompanySwitcherCompany<Id extends string | number = string | number> {
+  /** kastlan's ids are numbers; a string works the same. */
+  id: Id;
+  name: string;
+}
+
+export interface CompanySwitcherProps<Id extends string | number> {
+  /** Every company the user belongs to. With fewer than two there is nothing to
+   *  switch, and nothing renders. */
+  companies: readonly CompanySwitcherCompany<Id>[];
+  /** The company the session is in — `/auth/me`'s `current_company_id`. */
+  currentId: Id;
+  /**
+   * Another company was picked: `POST /auth/switch-company {company_id}`, store the
+   * fresh tokens, reload what is company-scoped. While the promise runs the switcher is
+   * disabled, so a second pick cannot race the first; a rejection frees it (the app
+   * says why). Picking the current company does nothing.
+   */
+  onSwitch: (id: Id) => Promise<unknown> | void;
+  /** The trigger's glyph. Default a building; keksdose's budgets would pass a wallet. */
+  icon?: ReactNode;
+  labels?: Partial<CompanySwitcherLabels>;
+}
+
+/**
+ * The company switcher in the top bar (docs/auth-harmonization.md §5.3, §8): a kastlan
+ * user may belong to several companies, and the access token carries the current one,
+ * so switching is a request for new tokens — `onSwitch`, the app's. Built on
+ * {@link OptionSwitcherMenu}, like `RoleSwitcher`: the icon trigger, the current company
+ * in its tooltip, the list with a check on the current one.
+ *
+ * **Only for more than one company** — a user in one company has nothing to switch, and
+ * the top bar stays as it was. **Disabled while a switch runs**: the trigger is swapped
+ * for a disabled one with a spinner (`aria-busy`), and "Switching company…" is said, so
+ * a second pick cannot race the first. The kit never sends the request.
+ *
+ * A generic context switcher: the labels rename it ("Switch budget", "Budgets"), `icon`
+ * replaces the building, and `id` may be a number (kastlan's) or a string.
+ */
+export function CompanySwitcher<Id extends string | number>({
+  companies,
+  currentId,
+  onSwitch,
+  icon,
+  labels: labelsProp,
+}: CompanySwitcherProps<Id>) {
+  const labels = useKitLabels("companySwitcher", DEFAULT_COMPANY_SWITCHER_LABELS, labelsProp);
+  const [pending, setPending] = useState(false);
+  const { announce, regionProps } = useAnnounce();
+  if (companies.length < 2) return null;
+
+  const current = companies.find((c) => c.id === currentId);
+  const select = (value: string) => {
+    if (pending) return;
+    const picked = companies.find((c) => String(c.id) === value);
+    if (!picked || picked.id === currentId) return;
+    const result = onSwitch(picked.id);
+    if (typeof (result as PromiseLike<unknown> | undefined)?.then !== "function") return;
+    setPending(true);
+    announce(labels.switching);
+    (result as PromiseLike<unknown>).then(
+      () => setPending(false),
+      () => setPending(false),
+    );
+  };
+
+  return (
+    <>
+      {pending ? (
+        <button
+          type="button"
+          disabled
+          aria-busy="true"
+          aria-label={labels.switchCompany}
+          className={cn(TOPBAR_TRIGGER_CLASS, "cursor-wait opacity-60 hover:bg-transparent")}
+        >
+          <Spinner label={null} />
+        </button>
+      ) : (
+        <OptionSwitcherMenu<string>
+          ariaLabel={labels.switchCompany}
+          title={current ? labels.current(current.name) : undefined}
+          heading={labels.heading}
+          icon={icon ?? <Building2 className="size-5" />}
+          options={companies.map((c) => ({
+            value: String(c.id),
+            label:
+              c.id === currentId ? (
+                // `relative`: the sr-only mark needs a local containing block.
+                <span className="relative">
+                  {c.name}
+                  <span className="sr-only"> {labels.currentMark}</span>
+                </span>
+              ) : (
+                c.name
+              ),
+          }))}
+          value={String(currentId)}
+          onSelect={select}
+        />
+      )}
+      {/* Outside both triggers, so it survives the swap and is read when it changes. */}
+      <span {...regionProps} />
+    </>
+  );
+}