@eifi1/ui-kit 0.40.1 → 0.42.0

package/src/billing/billing-overview.ts

@@ -54,6 +54,43 @@ export interface BillingOverview {
    * server-kit before 0.13 still type-checks; absent, read it as false.
    */
   switching?: boolean;
+  /**
+   * 0.42 (server-kit 0.14, §16.3): who may open the provider's portal. `"buyer_only"`:
+   * the row has a buyer (`provider_payer_user_id`) and the viewer isn't them — every
+   * portal target would answer `403 billing_portal_buyer_only`, so "Payment and
+   * invoices" is a caption naming the buyer and "Cancel subscription" is the in-app
+   * cancel (`POST /billing/cancel`). `"open"`, or absent (server-kit before 0.14): as
+   * before. Pass it to `SubscriptionActions`' `portal`.
+   */
+  portal?: BillingPortalAccess;
+  /**
+   * 0.42 (§16.3, §16.7 G): the buyer's display name, for the caption under
+   * `"buyer_only"`; `null` when the buyer is gone or no longer a member of the company,
+   * and the words then say "the admin who bought the subscription".
+   */
+  buyer_name?: string | null;
+}
+
+/** 0.42 (§16.3): `BillingOverview.portal` and `BillingStanding.portal` — server-kit's
+ *  `Literal["open", "buyer_only"]`. */
+export type BillingPortalAccess = "open" | "buyer_only";
+
+/**
+ * 0.42 (§16.2 decision 5, §16.7 E): whether the payer's free grant runs WITHOUT AN END —
+ * an operator's grant (`source: "manual"`) with `comped_until` empty. A purchase under
+ * it leaves the row `comped` on the grant's plan (§12.11): only the paid price moves,
+ * so the payer would pay for a plan that never applies. Pass it to `PlanPicker`'s and
+ * `PlanSwitchConfirm`'s `permanentGrant`, which warn before the checkout or the switch.
+ *
+ * `source` is checked explicitly, not implied by the missing date: Kurvenschmiede's
+ * pre-launch beta rows are `comped` with `comped_until` null too (their launch-plus-12-
+ * months end isn't written yet, §3.2), and they are not permanent. A grant with an end
+ * gets no warning either: the bought plan applies from that end on.
+ */
+export function isPermanentGrant(
+  overview: Pick<BillingOverview, "status" | "source"> & { comped_until?: BillingOverview["comped_until"] },
+): boolean {
+  return overview.status === "comped" && overview.source === "manual" && overview.comped_until == null;
 }
 
 /** 0.39: what the payer pays at the provider (server-kit's `PaidPrice`, §15.2.10),

package/src/billing/billing-standing.ts

@@ -1,6 +1,7 @@
 import { toDate } from "../lib/format";
 import type { DateInput } from "../lib/format";
 import type { SubscriptionStatus } from "./billing-labels";
+import type { BillingPortalAccess } from "./billing-overview";
 
 /**
  * What a device knows of the payer's standing — the fields of `GET /billing/overview`
@@ -16,6 +17,13 @@ export interface BillingStanding {
   /** When a free grant ends: a beta user's 12 months, an operator's grant. Empty for a
    *  grant without an end (§12.8). */
   comped_until?: DateInput;
+  /** 0.42 (server-kit 0.14, §16.7 A): who may open the provider's portal, as the
+   *  overview's `portal` — `GET /billing/status` says it too, for the payment-failed
+   *  banner (`BillingBanner`'s `portal`). Absent: `"open"`. */
+  portal?: BillingPortalAccess;
+  /** 0.42 (§16.7 A): the buyer's display name, as the overview's `buyer_name`; `null`
+   *  when the buyer is gone or has left the company. */
+  buyer_name?: string | null;
 }
 
 /**

package/src/billing/cancel-subscription.tsx

@@ -0,0 +1,102 @@
+import type { KeyboardEvent } from "react";
+
+import { useKitLabels, useKitLocale } from "../i18n/kit-labels";
+import type { LabelOverride } from "../i18n/kit-labels";
+import { DEFAULT_COMMON_LABELS } from "../i18n/shared-labels";
+import { formatDate } from "../lib/format";
+import type { DateInput } from "../lib/format";
+import { Button } from "../components/button";
+import { DialogFrame } from "../components/dialog-frame";
+import { COMMIT_EXCEPT_BILLING } from "../components/write-lock";
+import { useBillingLabels } from "./billing-labels";
+import type { BillingLabels } from "./billing-labels";
+
+export interface CancelSubscriptionConfirmProps {
+  open: boolean;
+  /** `false` when the admin dismisses it — Back, Escape, the backdrop. Confirm leaves it
+   *  open: close it once `POST /billing/cancel` answers. */
+  onOpenChange: (open: boolean) => void;
+  /** The overview's `current_period_end`: the day the subscription ends. Formatted with
+   *  the kit's date formatter (`formatDate`, `"medium"`). */
+  periodEnd: DateInput;
+  /** Confirm: the app's `POST /billing/cancel` (server-kit 0.14, §16.3). */
+  onConfirm: () => void;
+  /** The cancel is under way: Confirm's spinner, no second press, and Escape and Back
+   *  don't close. */
+  pending?: boolean;
+  /** The date's locale. Default: the provider's. */
+  locale?: string;
+  /** Prop > `<UiKitProvider labels={{ billing }}>` > English. */
+  labels?: LabelOverride<BillingLabels>;
+}
+
+/**
+ * The in-app cancel's confirm (docs/billing-harmonization.md §16.2 decision 2, §16.4,
+ * ui-kit 0.42): "Cancel subscription" for an admin the provider's portal doesn't open for
+ * (`SubscriptionActions`' `portal="buyer_only"` → `onCancelInApp`). It names the day the
+ * subscription ends — "Your subscription ends on 9 Nov 2026. Until then everything works
+ * as before." — and its button reads "Cancel subscription now" (German "Jetzt kündigen",
+ * the confirmation button of §312k BGB).
+ *
+ *     <CancelSubscriptionConfirm
+ *       open={asking}
+ *       onOpenChange={setAsking}
+ *       periodEnd={overview.current_period_end}
+ *       pending={cancel.isPending}
+ *       onConfirm={() => cancel.mutate()}
+ *     />
+ *
+ * The cancel is at the period's end (Paddle's `cancel`, not immediately); the row follows
+ * by webhook (`cancel_at_period_end`), as after a cancel in the portal, and
+ * `SubscriptionActions` then offers "Keep subscription" (`onResume`).
+ *
+ * It takes no billing lock (`COMMIT_EXCEPT_BILLING` built in, §3.3): a read-only payer
+ * may always cancel. A demo lock still holds it, as the server's demo guard does. The kit
+ * sends no request.
+ */
+export function CancelSubscriptionConfirm({
+  open,
+  onOpenChange,
+  periodEnd,
+  onConfirm,
+  pending = false,
+  locale: localeProp,
+  labels: labelsProp,
+}: CancelSubscriptionConfirmProps) {
+  const labels = useBillingLabels(labelsProp);
+  const common = useKitLabels("common", DEFAULT_COMMON_LABELS);
+  const locale = useKitLocale(localeProp);
+
+  return (
+    <DialogFrame
+      open={open}
+      title={labels.cancelConfirmTitle}
+      description={labels.cancelConfirmBody(formatDate(periodEnd, "medium", { locale }))}
+      onClose={() => {
+        if (!pending) onOpenChange(false);
+      }}
+      onKeyDown={(e: KeyboardEvent<HTMLDivElement>) => {
+        if (pending && e.key === "Escape") e.preventDefault();
+      }}
+      aria-busy={pending || undefined}
+      data-cancel-subscription-confirm=""
+      actions={(close) => (
+        <>
+          <Button variant="secondary" onClick={close} disabled={pending}>
+            {common.back}
+          </Button>
+          <Button
+            variant="danger"
+            commit={COMMIT_EXCEPT_BILLING}
+            pending={pending}
+            onClick={() => {
+              if (!pending) onConfirm();
+            }}
+          >
+            {labels.cancelConfirmAction}
+          </Button>
+        </>
+      )}
+    />
+  );
+}

package/src/billing/plan-card.tsx

@@ -11,6 +11,7 @@ import type { ChoiceCardProps } from "../components/choice-card";
 import { Chip } from "../components/chip";
 import { ToggleGroup } from "../components/toggle-group";
 import { Button } from "../components/button";
+import { DialogFrame } from "../components/dialog-frame";
 import { useBillingLabels } from "./billing-labels";
 import type { BillingLabels } from "./billing-labels";
 import { BILLING_INTERVALS, billingCurrencyFor, formatPlanPrice, planPrice } from "./plan-price";
@@ -263,6 +264,24 @@ export interface PlanPickerProps extends Omit<PlanDisplayProps, "currency" | "in
   onChoose: (choice: PlanChoice) => void;
   /** The checkout is being opened: the button's spinner, no second press. */
   pending?: boolean;
+  /**
+   * 0.42 (§16.2 decision 5, §16.8 B): the payer's free grant runs without an end —
+   * `isPermanentGrant(overview)`. A purchase under it changes nothing the payer gets
+   * while the grant runs (§12.11), so the button first opens a confirm —
+   * `grantWarningTitle`, `grantWarningBody`, "Buy anyway" (`grantWarningAction`) and
+   * "Back" — and {@link onChoose} runs only on "Buy anyway". Warned, not refused.
+   *
+   * Not while {@link switching}: then the pick opens `PlanSwitchConfirm`, which takes
+   * the same `permanentGrant` and shows the warning above its figures — one warning,
+   * in the dialog where the payer agrees, rather than a confirm before a confirm.
+   */
+  permanentGrant?: boolean;
+  /**
+   * 0.42: the overview's `switching` — the app sends this pick to `PlanSwitchConfirm`
+   * (§15.2.10), not the checkout. Only decides where {@link permanentGrant}'s warning
+   * shows; the button and {@link onChoose} are the same either way.
+   */
+  switching?: boolean;
   /** The provider's localised price for a plan, or `undefined` for the catalogue's —
    *  see {@link PlanCardProps.pricePreview}. */
   pricePreview?: (plan: BillingPlan, choice: Omit<PlanChoice, "plan">) => ReactNode | undefined;
@@ -308,6 +327,11 @@ function pricedIntervals(plans: readonly BillingPlan[]): BillingInterval[] {
  * The button never takes the write lock: billing itself always works, a read-only payer
  * must be able to pay (§3.3). It is off, with the reason on hover and focus, while
  * nothing is picked or the current plan is.
+ *
+ * 0.42 (§16.8 B): under a grant without an end (`permanentGrant`) the payer is warned
+ * before paying for a plan that won't apply — here, in a confirm before `onChoose`, on
+ * the way to the checkout; on the way to a switch (`switching`) in `PlanSwitchConfirm`
+ * instead, so the warning shows once on either path.
  */
 export function PlanPicker({
   plans,
@@ -324,6 +348,8 @@ export function PlanPicker({
   currencies: currenciesProp,
   onChoose,
   pending,
+  permanentGrant = false,
+  switching = false,
   pricePreview,
   legend,
   name,
@@ -338,6 +364,8 @@ export function PlanPicker({
   const labels = useBillingLabels(labelsProp);
   const locale = useKitLocale(localeProp);
   const generated = useId();
+  /** The choice the grant warning holds back until "Buy anyway". */
+  const [warned, setWarned] = useState<PlanChoice | null>(null);
   const groupName = name ?? generated;
   const legendId = `${generated}-legend`;
 
@@ -447,11 +475,79 @@ export function PlanPicker({
           className="max-sm:w-full"
           disabledReason={blocked}
           pending={pending}
-          onClick={() => picked && onChoose({ plan: picked.code, interval, currency })}
+          onClick={() => {
+            if (!picked) return;
+            const choice = { plan: picked.code, interval, currency };
+            if (permanentGrant && !switching) setWarned(choice);
+            else onChoose(choice);
+          }}
         >
           {buttonText}
         </Button>
       </div>
+      {permanentGrant && !switching && (
+        <GrantWarningConfirm
+          open={warned !== null}
+          onOpenChange={(open) => {
+            if (!open) setWarned(null);
+          }}
+          onConfirm={() => {
+            if (warned) onChoose(warned);
+          }}
+          labels={labelsProp}
+        />
+      )}
     </div>
   );
 }
+
+export interface GrantWarningConfirmProps {
+  /** Shown, controlled. */
+  open: boolean;
+  /** `false` on "Back", Escape, the backdrop — and after "Buy anyway". */
+  onOpenChange: (open: boolean) => void;
+  /** "Buy anyway": the app opens its checkout. The dialog closes itself after it. */
+  onConfirm: () => void;
+  /** Prop > `<UiKitProvider labels={{ billing }}>` > English: `grantWarningTitle`,
+   *  `grantWarningBody`, `grantWarningAction`. "Back" is `common.back`. */
+  labels?: LabelOverride<BillingLabels>;
+}
+
+/**
+ * 0.42 (§16.8 B): the permanent-grant warning before a checkout — `grantWarningTitle`,
+ * `grantWarningBody`, "Back" and "Buy anyway" (`grantWarningAction`). {@link PlanPicker}
+ * shows it itself under `permanentGrant` when not `switching`. Exported for the path the
+ * picker cannot see: an app that meant to switch, learned there is no subscription to
+ * switch (keksdose: `/billing/plan/preview` → 409 `billing_not_subscribed`) and falls back
+ * to a checkout — show this before that checkout, so a permanent-grant holder is still
+ * warned. Carries `data-grant-warning`.
+ */
+export function GrantWarningConfirm({ open, onOpenChange, onConfirm, labels: labelsProp }: GrantWarningConfirmProps) {
+  const labels = useBillingLabels(labelsProp);
+  const common = useKitLabels("common", DEFAULT_COMMON_LABELS);
+  return (
+    <DialogFrame
+      open={open}
+      title={labels.grantWarningTitle}
+      description={labels.grantWarningBody}
+      onClose={() => onOpenChange(false)}
+      data-grant-warning=""
+      actions={(close) => (
+        <>
+          <Button variant="secondary" onClick={close}>
+            {common.back}
+          </Button>
+          <Button
+            variant="primary"
+            onClick={() => {
+              onConfirm();
+              onOpenChange(false);
+            }}
+          >
+            {labels.grantWarningAction}
+          </Button>
+        </>
+      )}
+    />
+  );
+}

package/src/billing/plan-switch.tsx

@@ -6,6 +6,7 @@ import { DEFAULT_COMMON_LABELS } from "../i18n/shared-labels";
 import { pluralForm } from "../i18n/plurals";
 import type { PluralForms } from "../i18n/plurals";
 import { formatDate, formatMoney, formatNumber } from "../lib/format";
+import { AlertBanner } from "../components/alert-banner";
 import { Button } from "../components/button";
 import { DialogFrame } from "../components/dialog-frame";
 import { Spinner } from "../components/spinner";
@@ -67,6 +68,15 @@ export interface PlanSwitchConfirmProps {
   onConfirm: () => void;
   /** The figures' and the date's locale. Default: the provider's. */
   locale?: string;
+  /**
+   * 0.42 (§16.2 decision 5, §16.8 B): the payer's free grant runs without an end —
+   * `isPermanentGrant(overview)`. The switch changes the PAID plan, not the applied one
+   * (§12.11), so the dialog says so above its figures (`grantWarningTitle`,
+   * `grantWarningBody`) before the payer agrees. Confirm stays Confirm: the warning is
+   * this dialog's own, and `PlanPicker` — told `switching` — shows none of its own on
+   * the way here, so the payer reads it once.
+   */
+  permanentGrant?: boolean;
   /** Prop > `<UiKitProvider labels={{ billing }}>` > English. */
   labels?: LabelOverride<BillingLabels>;
 }
@@ -105,6 +115,7 @@ export function PlanSwitchConfirm({
   formatLimit,
   onConfirm,
   locale: localeProp,
+  permanentGrant = false,
   labels: labelsProp,
 }: PlanSwitchConfirmProps) {
   const labels = useBillingLabels(labelsProp);
@@ -164,6 +175,11 @@ export function PlanSwitchConfirm({
         </>
       )}
     >
+      {permanentGrant && (
+        <AlertBanner tone="warning" size="sm" data-grant-warning="">
+          <strong className="block font-medium">{labels.grantWarningTitle}</strong> {labels.grantWarningBody}
+        </AlertBanner>
+      )}
       {preview === undefined ? (
         <div className="flex justify-center py-4">
           <Spinner showLabel />

package/src/billing/subscription-actions.tsx

@@ -5,7 +5,7 @@ import { cn } from "../lib/cn";
 import { Button } from "../components/button";
 import { useBillingLabels } from "./billing-labels";
 import type { BillingLabels } from "./billing-labels";
-import type { PortalTarget } from "./billing-overview";
+import type { BillingPortalAccess, PortalTarget } from "./billing-overview";
 
 export interface SubscriptionActionsProps extends Omit<ComponentPropsWithRef<"div">, "children"> {
   /** "Payment and invoices", as a link — or {@link onManage}. Without either, none. */
@@ -35,8 +35,35 @@ export interface SubscriptionActionsProps extends Omit<ComponentPropsWithRef<"di
    * (§12.26). Default true (0.32's behaviour).
    */
   atProvider?: boolean;
-  /** Which of the two is under way: its spinner, no second press. */
-  pending?: "manage" | "cancel" | null;
+  /**
+   * 0.42 (§16.2, server-kit 0.14): the overview's `portal`. `"buyer_only"` — the row has
+   * a buyer and the viewer isn't them, so the portal would answer `403
+   * billing_portal_buyer_only`: "Payment and invoices" becomes a caption naming the buyer
+   * (`buyerHolds`, no button), and "Cancel subscription" calls {@link onCancelInApp}
+   * (no portal at all — `cancelHref`, `onCancel` and `onPortal` are not used). `"open"`
+   * (default): as before.
+   */
+  portal?: BillingPortalAccess;
+  /** 0.42: the overview's `buyer_name`, for the caption under `"buyer_only"`. Empty: "…with
+   *  the admin who bought the subscription". */
+  buyerName?: string | null;
+  /**
+   * 0.42 (§16.2 decision 2): "Cancel subscription" in the app — open
+   * `CancelSubscriptionConfirm`, whose Confirm is `POST /billing/cancel`. The cancel under
+   * `"buyer_only"`. Under `"open"` it is the last resort, used only when no portal cancel
+   * (`cancelHref`, `onCancel`, `onPortal`) is given — a person-payer app that mounts the
+   * route and not the portal's cancel.
+   */
+  onCancelInApp?: () => void;
+  /** 0.42 (§16.7 C): the overview's `cancel_at_period_end` — a cancel is scheduled. With
+   *  {@link onResume}, "Keep subscription" takes the cancel's place. */
+  cancelAtPeriodEnd?: boolean;
+  /** 0.42 (§16.7 C): "Keep subscription", the app's `POST /billing/resume` — shown in
+   *  the cancel's place while {@link cancelAtPeriodEnd} is true. Without it, the cancel
+   *  stays as before. */
+  onResume?: () => void;
+  /** Which one is under way: its spinner, no second press. `"resume"` since 0.42. */
+  pending?: "manage" | "cancel" | "resume" | null;
   /** Prop > `<UiKitProvider labels={{ billing }}>` > English. */
   labels?: LabelOverride<BillingLabels>;
 }
@@ -56,6 +83,12 @@ export interface SubscriptionActionsProps extends Omit<ComponentPropsWithRef<"di
  * Before the payer has reached the provider (`atProvider={false}`, a trial without a
  * card, a beta) there is no portal to open: the part says so in a caption instead of
  * offering two buttons that could only end in `409 billing_not_at_provider`.
+ *
+ * 0.42 (§16): where the company's buyer is another admin (`portal="buyer_only"`), the
+ * portal stays the buyer's — "Payment and invoices" is a caption that names them, and
+ * "Cancel subscription" is the in-app cancel (`onCancelInApp`). While a cancel is
+ * scheduled (`cancelAtPeriodEnd`) and `onResume` is given, "Keep subscription" stands in
+ * the cancel's place, whoever the viewer is.
  */
 export function SubscriptionActions({
   manageHref,
@@ -64,6 +97,11 @@ export function SubscriptionActions({
   onCancel,
   onPortal,
   atProvider = true,
+  portal = "open",
+  buyerName,
+  onCancelInApp,
+  cancelAtPeriodEnd = false,
+  onResume,
   pending,
   labels: labelsProp,
   className,
@@ -77,20 +115,31 @@ export function SubscriptionActions({
       </div>
     );
   }
+  const buyerOnly = portal === "buyer_only";
   const manageCall = onManage ?? (onPortal ? () => onPortal("overview") : undefined);
-  const cancelCall = onCancel ?? (onPortal ? () => onPortal("cancel") : undefined);
-  const manage =
-    manageHref !== undefined ? (
-      <Button href={manageHref} variant="secondary">
-        {labels.manage}
-      </Button>
-    ) : manageCall !== undefined ? (
-      <Button type="button" variant="secondary" onClick={manageCall} pending={pending === "manage"}>
-        {labels.manage}
-      </Button>
-    ) : null;
+  const portalCancel = onCancel ?? (onPortal ? () => onPortal("cancel") : undefined);
+  // Under "buyer_only" the in-app cancel only; under "open" the portal's first, the
+  // in-app cancel only where no way to the portal's is given.
+  const cancelCall = buyerOnly ? onCancelInApp : (portalCancel ?? (cancelHref === undefined ? onCancelInApp : undefined));
+  const manage = buyerOnly ? (
+    <p className="basis-full text-sm text-muted" data-buyer-holds="">
+      {labels.buyerHolds(buyerName || undefined)}
+    </p>
+  ) : manageHref !== undefined ? (
+    <Button href={manageHref} variant="secondary">
+      {labels.manage}
+    </Button>
+  ) : manageCall !== undefined ? (
+    <Button type="button" variant="secondary" onClick={manageCall} pending={pending === "manage"}>
+      {labels.manage}
+    </Button>
+  ) : null;
   const cancel =
-    cancelHref !== undefined ? (
+    cancelAtPeriodEnd && onResume !== undefined ? (
+      <Button type="button" variant="link" onClick={onResume} pending={pending === "resume"} data-keep-subscription="">
+        {labels.keepSubscription}
+      </Button>
+    ) : cancelHref !== undefined && !buyerOnly ? (
       <Button href={cancelHref} variant="link" tone="danger">
         {labels.cancel}
       </Button>

package/src/components/account-chips.tsx

@@ -6,7 +6,7 @@ import type { DateInput, FormatDateStyle, FormatRelativeTimeOptions } from "../l
 import { useKitDateFormatter, useKitLabels, useKitLocale, type LabelOverride } from "../i18n/kit-labels";
 import { toLocalIso } from "../lib/dates";
 import { Chip } from "./chip";
-import type { ChipShape, ChipSize, ChipTone, ChipVariant } from "./chip";
+import type { ChipLinkProps, ChipShape, ChipSize, ChipTone, ChipVariant } from "./chip";
 import type { DataTableColumn } from "./data-table";
 import { DEFAULT_ACCOUNT_STATE_LABELS } from "./account-chips-labels";
 
@@ -49,6 +49,20 @@ export interface RoleDefinition {
   tone?: ChipTone;
   /** A lucide component or an element — Kurvenschmiede marks its admins with a shield. */
   icon?: LucideIcon | ReactElement;
+  /**
+   * 0.42.0 (docs/admin-harmonization.md §2.1, settings §12.3): the role's tool — an
+   * admin's `/admin`, a reviewer's `/translations`. {@link AccountRoleChip} is a link to
+   * it; a role without one gets a plain chip. {@link RoleChip} ignores it: a roster's
+   * chips name a role, they are not a way in.
+   */
+  href?: string;
+  /**
+   * 0.42.0 (keksdose build review): this role's look in {@link AccountRoleChip} — keksdose
+   * draws only ADMIN `solid` and its REVIEWER and MEMBER `soft`. Default `solid`, the
+   * header's look; the chip's own `variant` prop wins over it. {@link RoleChip} ignores
+   * it: a roster's column keeps one look, set on the column.
+   */
+  variant?: ChipVariant;
 }
 
 /**
@@ -107,6 +121,72 @@ export function RoleChip<R extends string = string>({
   );
 }
 
+/* ── AccountRoleChip ───────────────────────────────────────────────────────── */
+
+export interface AccountRoleChipProps<R extends string = string> extends RoleChipProps<R> {
+  /**
+   * Runs on the way to the role's tool — the account menu's `close`, so the panel does
+   * not stay open over the page it just navigated to (keksdose F7). Only called on a
+   * link chip.
+   */
+  onNavigate?: () => void;
+  /** Your router's link for the role's `href`. Default: the `<UiKitProvider
+   *  linkComponent>`, then `<a>` — {@link Chip}'s `renderLink`. */
+  renderLink?: (props: ChipLinkProps) => ReactElement;
+}
+
+/**
+ * The role in the account menu's header (0.42.0, docs/admin-harmonization.md §2.1, §7):
+ * {@link RoleChip} in keksdose's look — `solid`, `sm`, `square`, `caps`, the role's icon
+ * and tone — made for `TopBarActionMenu`'s `header.extra`:
+ *
+ *     extra: (close) => <AccountRoleChip value={me.role} roles={ROLES} onNavigate={close} />
+ *
+ * A role whose {@link RoleDefinition.href} is set is a shortcut to its tool: the chip is a
+ * link (through `renderLink`, else the provider's link, as {@link Chip} draws links) and
+ * calls `onNavigate` on the click. Any other role is a plain chip — every account shows
+ * its role (§7, "Always a badge"). The words and tones are the app's vocabulary; the kit
+ * adds none. `solid` stays the default, so a role the app gives no look still reads as
+ * the header's tag; a role that should sit quieter (keksdose's MEMBER and REVIEWER) sets
+ * {@link RoleDefinition.variant} `soft` in the vocabulary. Carries `data-role` with the key.
+ */
+export function AccountRoleChip<R extends string = string>({
+  value: role,
+  roles,
+  onNavigate,
+  renderLink,
+  size = "sm",
+  variant,
+  shape = "square",
+  caps = true,
+  className,
+  ...rest
+}: AccountRoleChipProps<R>) {
+  if (role === null || role === undefined || role === "") return null;
+  const def = roles[role];
+  const look = {
+    ...rest,
+    "data-role": role,
+    tone: def?.tone ?? "neutral",
+    icon: def?.icon,
+    size,
+    // The prop, then the role's own look, then the header's `solid`.
+    variant: variant ?? def?.variant ?? "solid",
+    shape,
+    caps,
+    className,
+  } as const;
+  const label = def?.label ?? role;
+  if (def?.href) {
+    return (
+      <Chip {...look} href={def.href} renderLink={renderLink} onClick={onNavigate ? () => onNavigate() : undefined}>
+        {label}
+      </Chip>
+    );
+  }
+  return <Chip {...look}>{label}</Chip>;
+}
+
 /* ── AccountStateChip ──────────────────────────────────────────────────────── */
 
 /**

package/src/components/empty-state.tsx

@@ -17,8 +17,9 @@ export interface EmptyStateProps extends Omit<ComponentPropsWithRef<"div">, "chi
    * keksdose's error boundary IS the page when it trips, and its `<h2>` went missing
    * when it moved onto EmptyState — so the page's heading outline lost the one line
    * that says what happened. Only the element changes; the look is the box's.
+   * `h1` (0.42.0) for an empty state that is the whole page — `AdminForbidden`.
    */
-  headingAs?: "h2" | "h3" | "h4" | "h5" | "h6";
+  headingAs?: "h1" | "h2" | "h3" | "h4" | "h5" | "h6";
   /** A glyph ABOVE the title — kastlan's InboxEmptyState (an inbox), keksdose's
    *  offline card (a cloud with a slash). Sized by the box (`[&_svg]:size-8`) and
    *  muted, so five call sites cannot pick five sizes; hidden from assistive tech,

package/src/components/nav-pills.tsx

@@ -73,8 +73,8 @@ const PILL_DISABLED = "cursor-not-allowed opacity-50 hover:bg-transparent hover:
  * keksdose's swipe-settings card (swipe-settings-card:152) hand-rolled this: four
  * surface names that do not fit a 406px phone, and a sideways scroll would hide the
  * ones that do not fit behind a gesture nothing announces (live #332: *"Have the tabs
- * in more rows, rather than scrolling sideways"*). It is not {@link Tabs} with `wrap`
- * because its items are not tabs: a `role="tab"` promises a tabpanel, a roving tab
+ * in more rows, rather than scrolling sideways"*). It is not {@link Tabs} (which
+ * scrolls; its multirow `wrap` went in 0.41) because its items are not tabs: a `role="tab"` promises a tabpanel, a roving tab
  * stop and arrow keys, and a set of links to pages (or of buttons that switch the rest
  * of a card) promises none of that. So every pill is its own tab stop, the set is a
  * list (a screen reader hears "list, 4 items"), and "current" is `aria-current` — the