@eifi1/ui-kit 0.41.0 → 0.42.0

package/src/i18n/locales/zh.ts

@@ -1613,6 +1613,9 @@ export function uiKitLabelsZh(numberLocale = "zh-CN"): UiKitLabels {
       processing: "您的付款正在处理中。确认后您的套餐即会生效；此页面会自动更新。",
       choosePlan: "选择套餐",
       updatePayment: "更新付款方式",
+      // 0.42 (§16.7 A): for an admin who isn't the buyer.
+      paymentFailedAskBuyer: (buyer) =>
+        buyer ? `付款未成功。${buyer} 可以更新付款方式。` : "付款未成功。购买该订阅的管理员可以更新付款方式。",
       checkAgain: "再次检查",
       lockReason: "您的套餐已结束。选择套餐后即可再次进行修改。",
       // As `characterCount.limitReached` ("已达到字符数上限").
@@ -1643,6 +1646,18 @@ export function uiKitLabelsZh(numberLocale = "zh-CN"): UiKitLabels {
       switchCredited: "抵扣后续扣款",
       switchNextCharge: (date) => `下次扣款日期：${date}`,
       switchConfirm: "更改套餐",
+      // 0.42 (§16): the portal for the buyer only, the in-app cancel, the grant warning.
+      buyerHolds: (buyer) =>
+        buyer
+          ? `付款方式和发票由购买该订阅的 ${buyer} 管理。`
+          : "付款方式和发票由购买该订阅的管理员管理。",
+      cancelConfirmTitle: "取消订阅",
+      cancelConfirmBody: (date) => `您的订阅将于 ${date} 结束。在此之前，一切照常使用。`,
+      cancelConfirmAction: "立即取消订阅",
+      keepSubscription: "保留订阅",
+      grantWarningTitle: "您的免费使用权仍然有效",
+      grantWarningBody: "您的免费使用权没有结束日期。在此期间，购买不会改变您的套餐：您将为一个不生效的套餐付费。",
+      grantWarningAction: "仍然购买",
       waitingChanges: (count) => `${n(count)} 项修改正在等待套餐`,
       // "放弃", as `wizard.cancelConfirmLabel`.
       discardWaiting: "放弃等待中的修改",
@@ -1708,6 +1723,70 @@ export function uiKitLabelsZh(numberLocale = "zh-CN"): UiKitLabels {
       more: "更多",
       moreTitle: "更多页面",
     },
+    // 0.42.0 — docs/admin-harmonization.md §3.1: the admin area's shared words.
+    adminArea: {
+      title: "管理",
+      waiting: (count) => `${n(count)} 项待处理`,
+      forbiddenTitle: "仅限管理员",
+      forbiddenBody: (appName) => `管理员在这里管理 ${appName}。您的账户无法打开此页面。`,
+      forbiddenHome: "前往首页",
+      forbiddenReviewer: "审校翻译",
+      sections: {
+        overview: { title: "概览", help: "一眼看清待处理的事项。" },
+        users: { title: "用户", help: "谁拥有账户，以及每个人可以做什么。" },
+        invitations: { title: "邀请", help: "让新成员加入的链接。" },
+        billing: { title: "账单", help: "套餐、付款和发票。" },
+        activity: { title: "活动", help: "管理员的操作记录，最新的在前。" },
+      },
+      tiles: {
+        feedbackWaiting: "待分类",
+        deletionRequests: "删除请求",
+        invitationsPending: "待接受的邀请",
+        users: "用户",
+        usersNew: (count) => `近 7 天新增 ${n(count)} 人`,
+      },
+      tools: "工具",
+    },
+    // 0.42.0 — docs/top-bar-harmonization.md §3.1: the top bar's shared parts; "套餐" as
+    // `billing`.
+    topBarParts: {
+      tours: {
+        menu: "导览",
+        newDot: "有新导览",
+        thisPage: "本页",
+        newTours: "新导览",
+        allTours: "全部导览…",
+        badgeNew: "新",
+        completed: "已完成",
+      },
+      sync: {
+        blocked: (count) => `${n(count)} 项修改无法从此设备发送`,
+        offline: "离线——修改已保存在此设备上，重新连接后会同步",
+        refused: "服务器拒绝了上一次同步",
+        syncing: "正在同步…",
+        pending: (count) => `${n(count)} 项修改等待同步`,
+        syncedAt: (time) => `已于 ${time} 同步`,
+        idle: "已是最新",
+        syncHint: "点按立即同步",
+        offlineHint: "离线时无可同步内容",
+        withHint: (state, hint) => `${state}——${hint}`,
+        scoped: (scope, state) => `${scope}：${state}`,
+        offlineShort: "离线",
+        syncingShort: "正在同步…",
+        waitingShort: (count) => `${n(count)} 项等待中`,
+        refusedShort: "未同步",
+        offlineUnsaved: "离线——重新连接前无法保存修改",
+        saving: "正在保存…",
+      },
+      dev: {
+        roleHeading: "开发 · 角色",
+        switchPlan: "切换套餐",
+        plan: (value) => `套餐：${value}`,
+        planHeading: "开发 · 套餐",
+        backTo: (role) => `返回 ${role}`,
+        billingOff: "本地已关闭计费：切换套餐不会改变任何内容",
+      },
+    },
   };
 }
 

package/src/i18n/review.ts

@@ -393,9 +393,28 @@ export const KIT_LABEL_SAMPLES: Readonly<Record<string, readonly (readonly unkno
   // 0.39: PlanSwitchConfirm's two lines with figures (§15.2.10).
   "billing.switchFromTo": [["{{from}}", "{{to}}"]],
   "billing.switchNextCharge": [["{{date}}"]],
+  // 0.42 (§16): the buyer's name, or none once they are gone; the cancel's period end.
+  "billing.buyerHolds": [["{{buyer}}"], [undefined]],
+  "billing.paymentFailedAskBuyer": [["{{buyer}}"], [undefined]],
+  "billing.cancelConfirmBody": [["{{date}}"]],
   "planChange.current": [["{{plan}}"]],
   "planChange.changed": [["{{from}}", "{{to}}"]],
   "planChange.set": [["{{to}}"]],
   "planChange.untilDone": [["{{date}}"]],
   "planChange.usageOf": [["{{used}}", "{{limit}}", "{{dimension}}"]],
+  // 0.42.0 (docs/admin-harmonization.md §3.1): the menu row's count, the 403 page's app,
+  // the users tile's new accounts.
+  "adminArea.waiting": one,
+  "adminArea.forbiddenBody": [["{{app}}"]],
+  "adminArea.tiles.usersNew": one,
+  // 0.42.0 (docs/top-bar-harmonization.md §3.1): the sync indicator's counts, its time, the
+  // state joined to its hint or to the app's scope; the dev plan and the role to go back to.
+  "topBarParts.sync.blocked": one,
+  "topBarParts.sync.pending": one,
+  "topBarParts.sync.syncedAt": [["{{time}}"]],
+  "topBarParts.sync.withHint": [["{{state}}", "{{hint}}"]],
+  "topBarParts.sync.scoped": [["{{scope}}", "{{state}}"]],
+  "topBarParts.sync.waitingShort": one,
+  "topBarParts.dev.plan": [["{{plan}}"]],
+  "topBarParts.dev.backTo": [["{{role}}"]],
 };

package/src/index.ts

@@ -412,6 +412,10 @@ export type { WriteLock, WriteLockLabels, WriteLockProviderProps, WriteLockKind,
 // 0.18: the parts both apps' admin rosters repeat (Kurvenschmiede 6).
 export { RoleChip, AccountStateChip, DateMark, dateColumn, DEFAULT_ACCOUNT_STATE_LABELS, ACCOUNT_STATE_TONES } from "./components/account-chips";
 export type { RoleChipProps, RoleDefinition, RoleVocabulary, AccountState, AccountStateLabels, AccountStateChipProps, DateMarkProps, DateColumnOptions } from "./components/account-chips";
+// 0.42 (docs/admin-harmonization.md §2.1): the role in the account menu's header, a link
+// to the role's tool (`RoleDefinition.href`).
+export { AccountRoleChip } from "./components/account-chips";
+export type { AccountRoleChipProps } from "./components/account-chips";
 // 0.18: the cold-start notice keksdose built (#199), for every app: the corner notice
 // that explains the wait (its framework-free watchdog is lib/server-wake).
 export { ServerWakeNotice, useServerWakeStage, DEFAULT_SERVER_WAKE_LABELS } from "./components/server-wake";
@@ -785,6 +789,25 @@ export type {
   InvitationsPanelProps,
 } from "./admin/invitations-panel";
 export type { AdminPerson } from "./admin/admin-parts";
+// 0.42.0 (docs/admin-harmonization.md §3.1): the admin area's template — its words, the
+// shared sections and the catalogue helper, the 403 page, the overview and its tiles fed
+// by `GET /admin/attention`, and the Tools list. The menu row is `./shell`'s.
+export { DEFAULT_ADMIN_AREA_LABELS, useAdminAreaLabels } from "./admin/admin-area-labels";
+export type { AdminAreaLabels, AdminTileLabels, AdminSharedSection } from "./admin/admin-area-labels";
+export { ADMIN_SECTIONS, adminSections } from "./admin/admin-sections";
+export type { AdminSectionDefinition, AdminOwnSection, AdminSectionsOptions } from "./admin/admin-sections";
+export { AdminForbidden } from "./admin/admin-forbidden";
+export type { AdminForbiddenProps } from "./admin/admin-forbidden";
+export { AdminOverview, AttentionTile, adminWaitingCount, DEFAULT_ADMIN_ATTENTION_HREFS } from "./admin/admin-overview";
+export type {
+  AdminAttention,
+  AdminAttentionTile,
+  AdminExtraTile,
+  AdminOverviewProps,
+  AttentionTileProps,
+} from "./admin/admin-overview";
+export { AdminToolLinks } from "./admin/admin-tool-links";
+export type { AdminToolLink, AdminToolLinksProps } from "./admin/admin-tool-links";
 // 0.33.0: the operator's plan parts (docs/billing-harmonization.md §14.12).
 export {
   planColumn,
@@ -811,8 +834,8 @@ export { DEFAULT_BILLING_LABELS, useBillingLabels, SUBSCRIPTION_STATUSES } from
 export type { BillingLabels, SubscriptionStatus } from "./billing/billing-labels";
 export { BILLING_INTERVALS, planPrice, minorToMajor, formatPlanPrice, billingCurrencyFor } from "./billing/plan-price";
 export type { BillingInterval, BillingCurrency, PlanIntervalPrices, PlanPrices, PlanPriceAnswer } from "./billing/plan-price";
-export { PlanCard, PlanPicker, planRelation } from "./billing/plan-card";
-export type { BillingPlan, PlanRelation, PlanCardProps, PlanPickerProps, PlanChoice } from "./billing/plan-card";
+export { PlanCard, PlanPicker, GrantWarningConfirm, planRelation } from "./billing/plan-card";
+export type { BillingPlan, PlanRelation, PlanCardProps, PlanPickerProps, PlanChoice, GrantWarningConfirmProps } from "./billing/plan-card";
 export { SubscriptionStatusChip, SUBSCRIPTION_STATUS_TONES } from "./billing/subscription-status-chip";
 export type { SubscriptionStatusChipProps } from "./billing/subscription-status-chip";
 export { BillingBanner } from "./billing/billing-banner";
@@ -855,6 +878,11 @@ export type { PlanLimitToastOptions } from "./billing/plan-limit-toast";
 export { PlanSwitchConfirm } from "./billing/plan-switch";
 export type { PlanSwitchConfirmProps, PlanSwitchSide } from "./billing/plan-switch";
 export type { PaidPrice, PlanSwitchRequest, PlanSwitchPreview } from "./billing/billing-overview";
+// 0.42 (§16): the portal for the buyer only, the in-app cancel, the permanent-grant warning.
+export { isPermanentGrant } from "./billing/billing-overview";
+export type { BillingPortalAccess } from "./billing/billing-overview";
+export { CancelSubscriptionConfirm } from "./billing/cancel-subscription";
+export type { CancelSubscriptionConfirmProps } from "./billing/cancel-subscription";
 // The operator's plan parts (§14.12) are admin/plan-change, in the admin section.
 
 // ── settings ─────────────────────────────────────────────────────────────────

package/src/settings/settings-layout.tsx

@@ -40,6 +40,9 @@ export type SettingsLayoutWidth = "6xl" | "7xl";
  *  about twelve, keksdose 26; a page of six needs none. */
 export const SETTINGS_SEARCH_THRESHOLD = 8;
 
+/** The desktop sidebar's column: sticky beside a long group (§3.2). */
+const SIDEBAR_COLUMN = "mb-4 md:sticky md:top-6 md:mb-0 md:self-start";
+
 export interface SettingsLayoutProps<G extends string> {
   /** The page's `h1`: "Settings", "Administration". Default: `labels.title`. */
   title?: ReactNode;
@@ -72,6 +75,12 @@ export interface SettingsLayoutProps<G extends string> {
    * own navigation carries them.
    */
   phoneFooter?: ReactNode;
+  /**
+   * 0.42.0 (docs/admin-harmonization.md §2.5 decision 16): content under the section
+   * list on a desktop, in the same sticky column — the admin area's Tools list
+   * (`AdminToolLinks`). Not shown on a phone, where `phoneFooter` carries the same links.
+   */
+  sidebarFooter?: ReactNode;
   /** Prop > `<UiKitProvider labels={{ settings }}>` > English. */
   labels?: LabelOverride<SettingsLabels>;
   /** See {@link SettingsLayoutMode}. Default `"auto"`: the screen decides. */
@@ -151,6 +160,7 @@ export function SettingsLayout<G extends string>({
   width = "6xl",
   renderGroup,
   phoneFooter,
+  sidebarFooter,
   labels: labelsProp,
   layout = "auto",
   appName,
@@ -376,45 +386,59 @@ export function SettingsLayout<G extends string>({
     );
   } else {
     const open = group === null ? undefined : groupById.get(group);
+    // The section list alone, or (0.42) with the app's `sidebarFooter` under it in one
+    // sticky column.
+    const withSidebarFooter = (tabs: ReactNode) =>
+      sidebarFooter == null ? (
+        tabs
+      ) : (
+        <div className={cn(SIDEBAR_COLUMN, "space-y-6")}>
+          {tabs}
+          <div data-slot="settings-sidebar-footer">{sidebarFooter}</div>
+        </div>
+      );
     body = (
       <div className={pageClass} data-settings-view="desktop">
         <PageHeader size="compact" title={pageTitle} />
         {searchField}
         <div className="md:grid md:grid-cols-[14rem_minmax(0,1fr)] md:gap-6">
-          <Tabs<G>
-            orientation="vertical"
-            aria-label={labels.sections}
-            // Sticky (new in the harmonisation, §3.2): keksdose's notifications group
-            // scrolls for screens, and the list should stay in view beside it.
-            className="mb-4 md:sticky md:top-6 md:mb-0 md:self-start"
-            panelId={open && !searching ? panelId : undefined}
-            tabs={route.groups.map((g) => {
-              const count = hitsByGroup.get(g.id) ?? 0;
-              // While searching, the groups with nothing to show step back (keksdose).
-              const dim = searching && count === 0;
-              return {
-                id: g.id,
-                href: `${root}${settingsHref(base, g.id)}`,
-                name: g.title,
-                label: <span className={cn(dim && "opacity-40")}>{g.title}</span>,
-                icon: <span className={cn("inline-flex [&_svg]:size-4", dim && "opacity-40")}>{g.icon}</span>,
-                badge:
-                  searching && count > 0 ? (
-                    <Chip size="sm" tone="brand">
-                      <span aria-hidden>{count}</span>
-                      <span className="sr-only-fixed">{labels.matchCount(count)}</span>
-                    </Chip>
-                  ) : undefined,
-              };
-            })}
-            active={(open?.id ?? route.groups[0]?.id) as G}
-            onChange={(id) => {
-              // While searching the hits stand where the group would; a click on a group
-              // means "go there", so the search makes way (keksdose).
-              setQuery("");
-              select(id);
-            }}
-          />
+          {withSidebarFooter(
+            <Tabs<G>
+              orientation="vertical"
+              aria-label={labels.sections}
+              // Sticky (new in the harmonisation, §3.2): keksdose's notifications group
+              // scrolls for screens, and the list should stay in view beside it. With a
+              // `sidebarFooter` the column round both is the sticky one.
+              className={sidebarFooter == null ? SIDEBAR_COLUMN : undefined}
+              panelId={open && !searching ? panelId : undefined}
+              tabs={route.groups.map((g) => {
+                const count = hitsByGroup.get(g.id) ?? 0;
+                // While searching, the groups with nothing to show step back (keksdose).
+                const dim = searching && count === 0;
+                return {
+                  id: g.id,
+                  href: `${root}${settingsHref(base, g.id)}`,
+                  name: g.title,
+                  label: <span className={cn(dim && "opacity-40")}>{g.title}</span>,
+                  icon: <span className={cn("inline-flex [&_svg]:size-4", dim && "opacity-40")}>{g.icon}</span>,
+                  badge:
+                    searching && count > 0 ? (
+                      <Chip size="sm" tone="brand">
+                        <span aria-hidden>{count}</span>
+                        <span className="sr-only-fixed">{labels.matchCount(count)}</span>
+                      </Chip>
+                    ) : undefined,
+                };
+              })}
+              active={(open?.id ?? route.groups[0]?.id) as G}
+              onChange={(id) => {
+                // While searching the hits stand where the group would; a click on a group
+                // means "go there", so the search makes way (keksdose).
+                setQuery("");
+                select(id);
+              }}
+            />,
+          )}
           <div className="min-w-0 space-y-4">
             {searching ? (
               results

package/src/shell/account-menu-language.tsx

@@ -0,0 +1,116 @@
+import { useState } from "react";
+import type { ReactNode } from "react";
+import { Globe } from "lucide-react";
+import { Disclosure } from "../components/disclosure";
+import { MenuItem } from "../components/menu-item";
+import { DEFAULT_TOP_BAR_LABELS, useKitLabels } from "../i18n/kit-labels";
+
+/** One offered language in the account menu's sub-list. */
+export interface AccountMenuLanguageOption {
+  code: string;
+  /** Its name, in its own language ("Deutsch", "Français"). */
+  label: ReactNode;
+  /**
+   * A flag before the name, as the app draws it — keksdose's flag-icons span
+   * (`<span aria-hidden className="fi fi-ch …" />`). A node rather than a country code, so
+   * the kit ships no flag set; decorative, so give it `aria-hidden`.
+   */
+  flag?: ReactNode;
+  /**
+   * Or the ISO 3166-1 alpha-2 country (lowercase) whose flag-icons flag to draw, as
+   * `LanguageMenu`'s `LanguageOption` takes it — so one language list feeds both
+   * (Kurvenschmiede's `LANGUAGES`). Needs the app's flag-icons CSS, as `LanguageMenu`
+   * does. `flag` wins when both are given.
+   */
+  country?: string;
+}
+
+/** The option's flag: its own node, else the flag-icons flag of its country. */
+function flagOf(lang: AccountMenuLanguageOption): ReactNode {
+  if (lang.flag !== undefined) return lang.flag;
+  if (!lang.country) return undefined;
+  return (
+    <span
+      aria-hidden
+      data-country={lang.country}
+      className={`fi fi-${lang.country} inline-block h-[0.9375rem] w-5 shrink-0 rounded-sm shadow-[0_0_0_1px_rgba(0,0,0,0.08)]`}
+    />
+  );
+}
+
+export interface AccountMenuLanguageProps {
+  languages: readonly AccountMenuLanguageOption[];
+  /** The active language's code. */
+  value: string | undefined;
+  /** A pick: the app sets the device's language and, signed in, the account's
+   *  (settings §6.2). */
+  onPick: (code: string) => void;
+  /** The account menu's `close` (from `TopBarActionMenu`'s `children`): a pick shuts it. */
+  close?: () => void;
+  /** The row's name. Default: `topBar.language` ("Language"). */
+  label?: string;
+  /** Open the sub-list at first. Default `false`. */
+  defaultOpen?: boolean;
+}
+
+/**
+ * The language choice INSIDE the account menu (docs/top-bar-harmonization.md §2.3),
+ * keksdose's sub-list: a `Disclosure variant="menu"` row — the globe, "Language", the
+ * active language's flag and the chevron — that opens in place onto one checked
+ * `MenuItem` per language. Inline rather than a nested popover: a popover inside a
+ * popover fights the outside click and has nowhere to go on a phone (keksdose #140).
+ *
+ * It renders its own `<li>`: drop it into `TopBarActionMenu`'s `children` first after the
+ * app's context rows (§6.5). Signed out there is no account menu; `LanguageMenu` stays
+ * the bar's button (§2.3).
+ */
+export function AccountMenuLanguage({
+  languages,
+  value,
+  onPick,
+  close,
+  label,
+  defaultOpen = false,
+}: AccountMenuLanguageProps) {
+  const words = useKitLabels("topBar", DEFAULT_TOP_BAR_LABELS);
+  const [open, setOpen] = useState(defaultOpen);
+  const active = languages.find((l) => l.code === value);
+  return (
+    <li>
+      <Disclosure
+        variant="menu"
+        open={open}
+        onOpenChange={setOpen}
+        title={
+          <span className="flex items-center justify-between gap-3">
+            <span className="flex items-center gap-2">
+              <Globe aria-hidden className="size-4" />
+              {label ?? words.language}
+            </span>
+            {active && flagOf(active)}
+          </span>
+        }
+      >
+        <ul>
+          {languages.map((lang) => (
+            <li key={lang.code}>
+              <MenuItem
+                checked={lang.code === value}
+                onClick={() => {
+                  onPick(lang.code);
+                  setOpen(false);
+                  close?.();
+                }}
+                leading={flagOf(lang)}
+                // Under the row's own text, past the globe.
+                className="ps-9"
+              >
+                {lang.label}
+              </MenuItem>
+            </li>
+          ))}
+        </ul>
+      </Disclosure>
+    </li>
+  );
+}

package/src/shell/admin-menu.tsx

@@ -0,0 +1,117 @@
+import { Link } from "react-router";
+import { ShieldCheck } from "lucide-react";
+import { Chip } from "../components/chip";
+import { MenuItem } from "../components/menu-item";
+import { useKitLabels, type LabelOverride } from "../i18n/kit-labels";
+import { DEFAULT_ADMIN_AREA_LABELS } from "../admin/admin-area-labels";
+import type { AdminAreaLabels } from "../admin/admin-area-labels";
+import type { TopBarMenuEntry } from "./topbar-action-menu";
+
+/**
+ * The account menu's "Administration" row (0.42.0, docs/admin-harmonization.md §2.1, §6.6,
+ * §7): the way into the admin area everyone finds, in every app, for an admin only. Two
+ * forms of one row — {@link adminMenuEntry} for `TopBarActionMenu`'s `entries`, and
+ * {@link AdminMenuRow} for a menu built from `HoverMenu` children (Kurvenschmiede's).
+ */
+
+/** The badge's text: nothing for none or 0, "99+" past 99. */
+function badgeText(badge: number | null | undefined): string | null {
+  if (typeof badge !== "number" || !(badge > 0)) return null;
+  return badge > 99 ? "99+" : String(Math.floor(badge));
+}
+
+/**
+ * The waiting count at the row's end: the `solid` count pill of {@link Chip}, in the
+ * pending count's tone, with the number for the eye and `adminArea.waiting` for a reader
+ * ("Administration, 3 waiting"). `null` for no count.
+ */
+function WaitingBadge({ badge, labels }: { badge: number | null | undefined; labels: AdminAreaLabels }) {
+  const text = badgeText(badge);
+  if (text === null) return null;
+  return (
+    <Chip size="sm" variant="solid" tone="warning" data-slot="admin-badge">
+      <span aria-hidden>{text}</span>
+      {/* The comma parts it from the row's label in the name: "Administration, 3 waiting". */}
+      <span className="sr-only-fixed">, {labels.waiting(badge as number)}</span>
+    </Chip>
+  );
+}
+
+export interface AdminMenuEntryOptions {
+  /** The admin area. Default `/admin`. */
+  href?: string;
+  /**
+   * The waiting count (§2.4 decision 15, §6.3): only work that waits on this admin —
+   * `adminWaitingCount(attention, […])`. `0`, `null` or none shows no badge.
+   */
+  badge?: number | null;
+  /** The resolved `adminArea` words (`useAdminAreaLabels()`); default English. Builds no
+   *  hook, so the entry can be made in the list of entries. */
+  labels?: AdminAreaLabels;
+  /** The entry's `key`. Default `"administration"`. */
+  key?: string;
+  /** The page already open: `aria-current` and a check mark. */
+  current?: boolean;
+}
+
+/**
+ * The "Administration" {@link TopBarMenuEntry}: a link row with the `ShieldCheck` icon,
+ * the kit's word and the waiting count as its badge. Put it in the entries for an admin
+ * only — the menu closes on the way, as any link row:
+ *
+ *     entries={[…, ...(isAdmin ? [adminMenuEntry({ badge: waiting, labels })] : []), …]}
+ */
+export function adminMenuEntry({
+  href = "/admin",
+  badge,
+  labels = DEFAULT_ADMIN_AREA_LABELS,
+  key = "administration",
+  current,
+}: AdminMenuEntryOptions = {}): TopBarMenuEntry {
+  return {
+    kind: "link",
+    key,
+    to: href,
+    icon: <ShieldCheck className="size-4" aria-hidden />,
+    label: labels.title,
+    trailing: badgeText(badge) === null ? undefined : <WaitingBadge badge={badge} labels={labels} />,
+    current,
+  };
+}
+
+export interface AdminMenuRowProps {
+  /** The admin area. Default `/admin`. */
+  href?: string;
+  /** As {@link AdminMenuEntryOptions.badge}. */
+  badge?: number | null;
+  /** Runs on the way — `HoverMenu`'s `close`. */
+  onNavigate?: () => void;
+  current?: boolean;
+  /** Prop > `<UiKitProvider labels={{ adminArea }}>` > English. */
+  labels?: LabelOverride<AdminAreaLabels>;
+}
+
+/**
+ * The same row as {@link adminMenuEntry} for a menu drawn from `HoverMenu` children: the
+ * `<li>` holding the router-link {@link MenuItem} `TopBarActionMenu` draws for a link
+ * entry, so the two menus look alike.
+ *
+ *     {(close) => <ul>… {isAdmin && <AdminMenuRow badge={waiting} onNavigate={close} />} …</ul>}
+ */
+export function AdminMenuRow({ href = "/admin", badge, onNavigate, current, labels: labelsProp }: AdminMenuRowProps) {
+  const labels = useKitLabels("adminArea", DEFAULT_ADMIN_AREA_LABELS, labelsProp);
+  return (
+    <li>
+      <MenuItem
+        href={href}
+        renderLink={({ href: to, ...p }) => <Link to={to} {...p} />}
+        onClick={onNavigate ? () => onNavigate() : undefined}
+        leading={<ShieldCheck className="size-4" aria-hidden />}
+        trailing={badgeText(badge) === null ? undefined : <WaitingBadge badge={badge} labels={labels} />}
+        current={current}
+      >
+        {labels.title}
+      </MenuItem>
+    </li>
+  );
+}

package/src/shell/app-shell.tsx

@@ -91,6 +91,16 @@ export type AppShellSidebarFooterItem =
       hint?: string;
       /** Leaves the app: a plain `<a target="_blank" rel="noopener noreferrer">`. */
       external?: boolean;
+      /**
+       * 0.42.0 (docs/admin-harmonization.md §6.9): a count of what waits behind the link —
+       * kastlan's "Administration" with its To-triage count. A pill at the end of the
+       * expanded link, a corner dot on the collapsed icon; `0`, `null` or none shows
+       * nothing, and above 99 it reads "99+". The count joins the link's name, in
+       * `badgeLabel`'s words when given ("Administration, 3 waiting").
+       */
+      badge?: number | null;
+      /** The badge's words for a reader — `adminArea.waiting(count)`. Default: the number. */
+      badgeLabel?: string;
     }
   | {
       kind: "links";
@@ -589,6 +599,17 @@ const plainLink: KitLinkComponent = ({ children, ...p }) => <a {...p}>{children}
 const FOOTER_ICON_LINK =
   "flex min-h-8 items-center justify-center rounded-md text-muted hover:bg-hover hover:text-secondary";
 
+/** A footer link's count as drawn: nothing for none, "99+" past 99. */
+function footerBadgeText(badge: number | null | undefined): string | null {
+  if (typeof badge !== "number" || !(badge > 0)) return null;
+  return badge > 99 ? "99+" : String(Math.floor(badge));
+}
+
+/** The count's pill — the solid "count" look of `Chip` (warning, the pending count's
+ *  tone, as `FloatingActionGroup`'s badge), sized for the footer's small text. */
+const FOOTER_BADGE =
+  "inline-flex h-4 min-w-4 shrink-0 items-center justify-center rounded-full bg-warning px-1 text-micro font-semibold leading-4 tabular-nums text-warning-contrast";
+
 /** Calls the link renderer as a component, so a router link's hooks are its own. */
 function RenderedLink({ render, ...props }: KitLinkProps & { render: KitLinkComponent }) {
   return render(props);
@@ -627,12 +648,23 @@ function SidebarFooterItems({
           const to = item.kind === "links" ? (item.to ?? item.links[0]?.to) : item.to;
           if (!to) return null;
           const external = item.kind === "links" ? item.links.find((l) => l.to === to)?.external : item.external;
+          const count = item.kind === "links" ? null : footerBadgeText(item.badge);
+          const spoken = count === null || item.kind === "links" ? null : (item.badgeLabel ?? count);
           return (
             <Tooltip key={item.key} label={item.label} side="end" portal className="block">
               {linkTo(to, external, {
-                "aria-label": item.label,
-                className: FOOTER_ICON_LINK,
-                children: <item.icon className="size-4" aria-hidden />,
+                "aria-label": spoken === null ? item.label : `${item.label}, ${spoken}`,
+                className: cn(FOOTER_ICON_LINK, count !== null && "relative"),
+                children: (
+                  <>
+                    <item.icon className="size-4" aria-hidden />
+                    {count !== null && (
+                      <span aria-hidden data-badge="" className={cn(FOOTER_BADGE, "absolute -top-0.5 end-0.5")}>
+                        {count}
+                      </span>
+                    )}
+                  </>
+                ),
               })}
             </Tooltip>
           );
@@ -655,6 +687,7 @@ function SidebarFooterItems({
             </nav>
           );
         }
+        const count = footerBadgeText(item.badge);
         const link = linkTo(item.to, item.external, {
           className: cn(FOOTER_ICON_LINK, "gap-1.5 text-xs font-medium"),
           children: (
@@ -663,6 +696,14 @@ function SidebarFooterItems({
               {/* Wraps from Large up (text size §10.17, round 0.34 T1): the link is
                   `min-h-8`, so it grows a line rather than cut "Feedb…". */}
               <span className="min-w-0 truncate-until-large">{item.text ?? item.label}</span>
+              {count !== null && (
+                <>
+                  <span aria-hidden data-badge="" className={FOOTER_BADGE}>
+                    {count}
+                  </span>
+                  <span className="sr-only">, {item.badgeLabel ?? count}</span>
+                </>
+              )}
             </>
           ),
         });