@eifi1/ui-kit 0.41.0 → 0.43.0

package/src/admin/admin-overview.tsx

@@ -0,0 +1,217 @@
+import type { ReactNode } from "react";
+import { AlertBanner } from "../components/alert-banner";
+import { Button } from "../components/button";
+import { StatTile, StatTileGrid } from "../components/stat-tile";
+import type { StatTileProps } from "../components/stat-tile";
+import type { LabelOverride } from "../i18n/kit-labels";
+import { cn } from "../lib/cn";
+import { useAdminAreaLabels } from "./admin-area-labels";
+import type { AdminAreaLabels } from "./admin-area-labels";
+
+/**
+ * The admin's start page (0.42.0, docs/admin-harmonization.md §2.4, §6.1–§6.5): a grid
+ * of tiles, each a count of what is waiting and a link to where the work is, fed by one
+ * server answer.
+ */
+
+/**
+ * `GET /admin/attention` (§2.4 decision 14, §6.4) — server-kit's `AdminAttention`
+ * (`eifi1_server_kit.user_admin.attention`), as the API sends it.
+ *
+ * Each count is `null` where the app has no such thing or this viewer cannot act on it,
+ * and every count is `null` in a demo session. Demo accounts never count. `extra` holds
+ * the app's own counts, keyed as its overview names them (keksdose `support_waiting`,
+ * Kurvenschmiede `released_for_work`).
+ */
+export interface AdminAttention {
+  /** "To triage": OPEN reports, crash reports included (§6.1). */
+  feedback_waiting: number | null;
+  /** Accounts that asked to be deleted — only where this viewer acts on them (§6.2). */
+  deletion_requests: number | null;
+  invitations_pending: number | null;
+  users_total: number | null;
+  /** Accounts made in the last seven days. */
+  users_new_7d: number | null;
+  extra: Record<string, number | null>;
+}
+
+/** The shared counts that are a tile of their own (`users_new_7d` is the users tile's line). */
+export type AdminAttentionTile = "feedback_waiting" | "deletion_requests" | "invitations_pending" | "users_total";
+
+/** Where each shared tile links when the app names nothing else (§2.4 decision 13). */
+export const DEFAULT_ADMIN_ATTENTION_HREFS: Readonly<Record<AdminAttentionTile, string>> = Object.freeze({
+  feedback_waiting: "/feedback",
+  deletion_requests: "/admin/users?state=deletion_requested",
+  invitations_pending: "/admin/invitations",
+  users_total: "/admin/users",
+});
+
+/**
+ * The account menu's badge (§2.4 decision 15, §6.3): the sum of the counts that are work
+ * waiting on THIS admin — each app names its own (keksdose `["feedback_waiting",
+ * "support_waiting", "awaiting_verdict"]`, kastlan `["feedback_waiting"]`, Kurvenschmiede
+ * `["feedback_waiting", "deletion_requests"]`). A name is a shared count or an `extra`
+ * key; a `null` or missing count adds nothing. Invitations and users never belong in it.
+ * `null` while there is no answer yet, so the badge shows nothing rather than a 0.
+ */
+export function adminWaitingCount(
+  attention: AdminAttention | null | undefined,
+  counts: readonly (AdminAttentionTile | (string & {}))[],
+): number | null {
+  if (!attention) return null;
+  let sum = 0;
+  for (const key of counts) {
+    const shared = (attention as unknown as Record<string, unknown>)[key];
+    const value = typeof shared === "number" ? shared : attention.extra?.[key];
+    if (typeof value === "number" && value > 0) sum += value;
+  }
+  return sum;
+}
+
+export interface AttentionTileProps extends Omit<StatTileProps, "href" | "onClick" | "value"> {
+  /** The count. `null` shows the tile's dash; {@link AdminOverview} leaves such a tile out. */
+  count: number | null | undefined;
+  /** Where the work is — the tile is a link to it. Since 0.43 it may be left out: a
+   *  quiet count, no link (Kurvenschmiede). */
+  href?: string;
+}
+
+/**
+ * One tile of the overview: a {@link StatTile} that is a LINK to where the work is, its
+ * count the headline. The whole tile is the link, named by its label; route it through
+ * `renderLink` or the provider's link component, as any StatTile. Without `href` (0.43) it
+ * is a quiet count, no link.
+ */
+export function AttentionTile({ count, href, ...tile }: AttentionTileProps) {
+  return <StatTile data-slot="attention-tile" {...tile} value={count ?? null} href={href} />;
+}
+
+/** One of the app's own tiles (§2.4 decision 13: keksdose's "Support waiting"). */
+export interface AdminExtraTile {
+  /** Unique among the tiles; usually the `extra` key it shows. */
+  key: string;
+  label: ReactNode;
+  /** `null` or `undefined` leaves the tile out, as for a shared one. */
+  count: number | null | undefined;
+  /** Where the work is. Left out (0.43, Kurvenschmiede): a quiet count with no link —
+   *  a number worth seeing that has no page of its own. */
+  href?: string;
+  /** A line under the count. */
+  description?: ReactNode;
+}
+
+export interface AdminOverviewProps {
+  /** The server's answer; `undefined` while it loads (the grid shows its skeletons). */
+  attention: AdminAttention | null | undefined;
+  /**
+   * Where the shared tiles link, over {@link DEFAULT_ADMIN_ATTENTION_HREFS} — the
+   * inbox's address filtered to OPEN (§6.1) is the app's own:
+   * `{ feedback_waiting: "/feedback?status=OPEN" }`.
+   */
+  hrefs?: Partial<Record<AdminAttentionTile, string>>;
+  /** The app's own tiles, after the shared ones, in this order. */
+  extraTiles?: readonly AdminExtraTile[];
+  /** Passed to every tile — `renderLink` for the router, `size`, `variant`. */
+  tileProps?: Pick<StatTileProps, "renderLink" | "size" | "variant" | "locale">;
+  /**
+   * 0.43 (keksdose): the answer failed — the query's `error`, or `true`. Anything truthy
+   * shows `adminArea.overviewError` in a danger box, with "Try again" when
+   * {@link onRetry} is given. A failed poll keeps the last good tiles: with `attention`
+   * still there (a query keeps its last data), the box shows ALONGSIDE them, above, not
+   * instead (build review 0.43, keksdose N7) — pass `attention.data` as it is. Without
+   * an answer yet, the box alone. Without `error`: `undefined` is the skeletons and
+   * `null` nothing, as before.
+   */
+  error?: unknown;
+  /** "Try again" in the error box — the query's `refetch`. */
+  onRetry?: () => void;
+  /** Prop > `<UiKitProvider labels={{ adminArea }}>` > English. */
+  labels?: LabelOverride<AdminAreaLabels>;
+  className?: string;
+}
+
+/**
+ * The overview section (§2.4): the shared tiles in their order — To triage, Deletion
+ * requests, Pending invitations, Users (with the new accounts of the last 7 days under
+ * the total) — then the app's `extraTiles`. A tile whose count is `null` is left out,
+ * so each app shows only what it has; a `0` is a quiet tile, "nothing waiting".
+ *
+ * The overview is the admin area's landing page, standalone: it is NOT wrapped in a
+ * `SettingsSection` (`adminSections` gives it no entry; render it as the page's body, as
+ * Kurvenschmiede's `OverviewPanel` does). keksdose links its metrics from here with at
+ * most two tiles (§6.5).
+ */
+export function AdminOverview({
+  attention,
+  hrefs,
+  extraTiles = [],
+  tileProps,
+  error,
+  onRetry,
+  labels: labelsProp,
+  className,
+}: AdminOverviewProps) {
+  const labels = useAdminAreaLabels(labelsProp);
+  /** The error box: on its own (`alone`) it is the overview's root. */
+  const errorBox = (alone: boolean) => (
+    <AlertBanner
+      data-slot={alone ? "admin-overview" : undefined}
+      data-state={alone ? "error" : undefined}
+      variant="box"
+      tone="danger"
+      className={alone ? className : undefined}
+      action={
+        onRetry ? (
+          <Button type="button" variant="secondary" size="sm" onClick={() => onRetry()}>
+            {labels.retry}
+          </Button>
+        ) : undefined
+      }
+    >
+      {labels.overviewError}
+    </AlertBanner>
+  );
+  // Nothing good to keep: the box alone.
+  if (error && !attention) return errorBox(true);
+  const href = { ...DEFAULT_ADMIN_ATTENTION_HREFS, ...hrefs };
+  const loading = attention === undefined;
+  const shared: { key: AdminAttentionTile; label: string; description?: ReactNode }[] = [
+    { key: "feedback_waiting", label: labels.tiles.feedbackWaiting },
+    { key: "deletion_requests", label: labels.tiles.deletionRequests },
+    { key: "invitations_pending", label: labels.tiles.invitationsPending },
+    {
+      key: "users_total",
+      label: labels.tiles.users,
+      description:
+        attention && typeof attention.users_new_7d === "number" ? labels.tiles.usersNew(attention.users_new_7d) : undefined,
+    },
+  ];
+  const tiles = [
+    ...shared.map((t) => ({ ...t, count: attention ? attention[t.key] : undefined, href: href[t.key] })),
+    ...extraTiles,
+  ].filter((t) => loading || (t.count !== null && t.count !== undefined));
+  if (!loading && tiles.length === 0) return error ? errorBox(true) : null;
+  const grid = (
+    <StatTileGrid data-slot={error ? undefined : "admin-overview"} loading={loading} className={error ? undefined : className}>
+      {tiles.map((t) => (
+        <AttentionTile
+          key={t.key}
+          {...tileProps}
+          data-attention={t.key}
+          label={t.label}
+          count={t.count}
+          href={t.href}
+          description={t.description}
+        />
+      ))}
+    </StatTileGrid>
+  );
+  if (!error) return grid;
+  // A failed poll: the error above the last good tiles.
+  return (
+    <div data-slot="admin-overview" data-state="error" className={cn("space-y-4", className)}>
+      {errorBox(false)}
+      {grid}
+    </div>
+  );
+}

package/src/admin/admin-sections.tsx

@@ -0,0 +1,198 @@
+import { createElement } from "react";
+import type { ReactNode } from "react";
+import { History, LayoutDashboard, Mail, Receipt, Users } from "lucide-react";
+import type { LucideIcon } from "lucide-react";
+import type { SettingsGroup } from "../settings/settings-catalogue";
+import { DEFAULT_ADMIN_AREA_LABELS } from "./admin-area-labels";
+import type { AdminAreaLabels, AdminSharedSection } from "./admin-area-labels";
+
+/**
+ * The admin area's sections (0.42.0, docs/admin-harmonization.md §2.3, §6.8): the five
+ * every app shares, in the template's order, and the helper that builds an app's
+ * `SettingsLayout` catalogue groups from them and the app's own.
+ */
+
+/** One shared section: its path segment and its icon. The words are `adminArea.sections`. */
+export interface AdminSectionDefinition {
+  id: AdminSharedSection;
+  icon: LucideIcon;
+}
+
+/**
+ * The shared sections in the template's order (§2.3 decision 10, §6.13): Overview, Users,
+ * Invitations, Billing, Activity. An app's own sections go between them
+ * ({@link adminSections}).
+ */
+export const ADMIN_SECTIONS: readonly AdminSectionDefinition[] = Object.freeze([
+  { id: "overview", icon: LayoutDashboard },
+  { id: "users", icon: Users },
+  { id: "invitations", icon: Mail },
+  { id: "billing", icon: Receipt },
+  { id: "activity", icon: History },
+]);
+
+/**
+ * One of the app's own sections: a catalogue group with its words, plus where it goes.
+ * `after` names the section it follows — a shared one or another of the app's own. Left
+ * out, it goes where the template puts an app's sections, after Invitations and before
+ * Billing, in the order given.
+ */
+export interface AdminOwnSection<G extends string = string> extends SettingsGroup<G> {
+  after?: AdminSharedSection | G;
+}
+
+/** Where one section goes, without its words — what {@link adminSectionOrder} takes. An
+ *  {@link AdminOwnSection} is one. */
+export interface AdminSectionPlace<G extends string = string> {
+  id: G;
+  after?: AdminSharedSection | G;
+}
+
+/** The order's options: the shared sections an app does not have. */
+export interface AdminSectionOrderOptions<L extends AdminSharedSection = AdminSharedSection> {
+  /**
+   * Shared sections this app does not have — keksdose and Kurvenschmiede have no billing
+   * view (`["billing"]`). Left out, every shared section is in the catalogue. Since 0.43
+   * the result's type leaves them out too, so no cast is needed to drop `"billing"` —
+   * when TypeScript infers the type arguments. With them written out, name the left-out
+   * ones as the second (`adminSections<Own, "billing">(…)`); `adminSections<Own>(…)`
+   * keeps every shared id in the type, as before.
+   */
+  leaveOut?: readonly L[];
+}
+
+export interface AdminSectionsOptions<L extends AdminSharedSection = AdminSharedSection> extends AdminSectionOrderOptions<L> {
+  /**
+   * A shared section that is in the catalogue but hidden for now, as
+   * {@link SettingsGroup.visible}: kastlan's `{ billing: billingEnabled }` (settings §5),
+   * whose path then acts as an unknown one.
+   */
+  visible?: Partial<Record<AdminSharedSection, boolean>>;
+}
+
+/** The shared sections an app keeps when it leaves out `L`. A `leaveOut` typed as the
+ *  whole union (a variable of `AdminSharedSection[]`) says nothing about which, so it
+ *  narrows nothing. */
+export type AdminKeptSection<L extends AdminSharedSection = AdminSharedSection> = [AdminSharedSection] extends [L]
+  ? AdminSharedSection
+  : Exclude<AdminSharedSection, L>;
+
+/** The shared section after which the app's sections go when they name no place. */
+const OWN_DEFAULT_AFTER: AdminSharedSection = "invitations";
+
+/** The shared and own sections in their order — a shared one as its definition, an own
+ *  one as given. Throws as {@link adminSections} documents. */
+function orderSections<S extends AdminSectionPlace<string>>(
+  own: readonly S[],
+  leaveOutIds: readonly AdminSharedSection[] | undefined,
+): ({ shared: AdminSectionDefinition } | { own: S })[] {
+  const leaveOut = new Set<string>(leaveOutIds ?? []);
+  const shared = new Set<string>(ADMIN_SECTIONS.map((s) => s.id));
+  const ownIds = new Set<string>();
+  for (const section of own) {
+    if (shared.has(section.id)) throw new Error(`adminSections: "${section.id}" is a shared section's id`);
+    if (ownIds.has(section.id)) throw new Error(`adminSections: "${section.id}" is given twice`);
+    ownIds.add(section.id);
+  }
+  for (const section of own) {
+    const after = section.after;
+    if (after !== undefined && !shared.has(after) && !ownIds.has(after)) {
+      throw new Error(`adminSections: "${section.id}" goes after "${after}", which is no section`);
+    }
+  }
+
+  // Each section's followers, in the order given: the shared ones, then the own ones
+  // under their `after`, recursively, so an own section may follow another own one.
+  const followers = new Map<string, S[]>();
+  for (const section of own) {
+    const after = section.after ?? OWN_DEFAULT_AFTER;
+    followers.set(after, [...(followers.get(after) ?? []), section]);
+  }
+
+  const out: ({ shared: AdminSectionDefinition } | { own: S })[] = [];
+  const placed = new Set<string>();
+  const placeAfter = (id: string) => {
+    for (const section of followers.get(id) ?? []) {
+      out.push({ own: section });
+      placed.add(section.id);
+      placeAfter(section.id);
+    }
+  };
+  for (const definition of ADMIN_SECTIONS) {
+    if (!leaveOut.has(definition.id)) out.push({ shared: definition });
+    // A left-out section's followers keep its place.
+    placeAfter(definition.id);
+  }
+  const stuck = own.filter((s) => !placed.has(s.id)).map((s) => s.id);
+  if (stuck.length) throw new Error(`adminSections: ${stuck.join(", ")} follow each other in a circle`);
+  return out;
+}
+
+/**
+ * The admin area's section ids in the template's order (0.43, keksdose) — what
+ * {@link adminSections} builds its groups in, without the words: for an app that needs the
+ * ORDER only (a router's list of paths, a test), outside a component, with no labels.
+ *
+ *     adminSectionOrder([{ id: "metrics", after: "overview" }], { leaveOut: ["billing"] })
+ *     // ["overview", "metrics", "users", "invitations", "activity"]
+ *
+ * Throws as {@link adminSections} does.
+ */
+export function adminSectionOrder<G extends string = never, L extends AdminSharedSection = AdminSharedSection>(
+  own: readonly AdminSectionPlace<G>[] = [],
+  options: AdminSectionOrderOptions<L> = {},
+): (AdminKeptSection<L> | G)[] {
+  return orderSections(own, options.leaveOut).map((s) =>
+    "shared" in s ? (s.shared.id as AdminKeptSection<L>) : s.own.id,
+  );
+}
+
+/**
+ * An app's admin catalogue groups, in the template's order (§2.3 decision 10, §6.8): the
+ * shared sections with the kit's icons and words, and the app's own at the places they
+ * name. The result is `SettingsLayout`'s `groups`; the entries stay the app's (a group
+ * with no visible entry is hidden, as on any settings page — except, since 0.43, the
+ * Overview, a page of tiles that needs no entry: it is `standalone`). Since 0.43 the
+ * result's type leaves out the `leaveOut` sections, and {@link adminSectionOrder} gives
+ * the same order as ids, without words.
+ *
+ *     const groups = adminSections(useAdminAreaLabels(), [
+ *       { id: "metrics", icon: <BarChart3 />, title: t("…"), help: t("…"), after: "overview" },
+ *       { id: "messaging", icon: <MessageSquare />, title: t("…"), help: t("…") },
+ *       { id: "health", icon: <HeartPulse />, title: t("…"), help: t("…"), after: "billing" },
+ *     ], { leaveOut: ["billing"] });
+ *
+ * gives keksdose's overview, metrics, users, invitations, messaging, health, activity.
+ * An `after` that names a left-out section takes that section's place. Kurvenschmiede's
+ * Teams needs no `after`: between Invitations and Activity is the default.
+ *
+ * `labels` is the `adminArea` namespace, resolved — {@link useAdminAreaLabels} inside a
+ * component, or the app's catalogue for the language; `undefined` is English. Throws for
+ * an own section whose id is a shared one, an id given twice, or an `after` that names no
+ * section: the catalogue is built once, and a section quietly missing from it is worse.
+ */
+export function adminSections<G extends string = never, L extends AdminSharedSection = AdminSharedSection>(
+  labels: AdminAreaLabels | undefined,
+  own: readonly AdminOwnSection<G>[] = [],
+  options: AdminSectionsOptions<L> = {},
+): SettingsGroup<AdminKeptSection<L> | G>[] {
+  const words = labels ?? DEFAULT_ADMIN_AREA_LABELS;
+  return orderSections(own, options.leaveOut).map((s): SettingsGroup<AdminKeptSection<L> | G> => {
+    if ("own" in s) {
+      const { after: _after, ...group } = s.own;
+      return group;
+    }
+    const { id, icon } = s.shared;
+    const visible = options.visible?.[id];
+    return {
+      id: id as AdminKeptSection<L>,
+      icon: createElement(icon, { "aria-hidden": true }) as ReactNode,
+      title: words.sections[id].title,
+      help: words.sections[id].help,
+      // 0.43 (kastlan): the overview is a page of tiles, not of setting cards — it shows
+      // with no entry of its own.
+      ...(id === "overview" ? { standalone: true } : null),
+      ...(visible === undefined ? null : { visible }),
+    };
+  });
+}

package/src/admin/admin-tool-links.tsx

@@ -0,0 +1,84 @@
+import { useId } from "react";
+import type { ReactElement, ReactNode } from "react";
+import { cn } from "../lib/cn";
+import { List, ListItem } from "../components/list";
+import type { ListItemLinkProps } from "../components/list";
+import type { LabelOverride } from "../i18n/kit-labels";
+import { useAdminAreaLabels } from "./admin-area-labels";
+import type { AdminAreaLabels } from "./admin-area-labels";
+
+/** One link of the Tools list. */
+export interface AdminToolLink {
+  /** Unique in the list. */
+  key: string;
+  label: string;
+  href: string;
+  /** A lucide element, sized by the row. */
+  icon?: ReactNode;
+  /** `false` leaves the link out — Translations for an admin who doesn't review
+   *  (§6.11, ka F7). Default: shown. */
+  visible?: boolean;
+}
+
+export interface AdminToolLinksProps {
+  links: readonly AdminToolLink[];
+  /**
+   * `sidebar` (default): a `<nav>` named and headed "Tools", for `SettingsLayout`'s
+   * `sidebarFooter` under the section list on a desktop. `list`: the bare rows, for
+   * `SettingsLayout`'s `phoneFooter`, which puts them in a list of their own.
+   */
+  variant?: "sidebar" | "list";
+  /** Your router's link. Default: the `<UiKitProvider linkComponent>`, then `<a>`. */
+  renderLink?: (props: ListItemLinkProps) => ReactElement;
+  /** Prop > `<UiKitProvider labels={{ adminArea }}>` > English. */
+  labels?: LabelOverride<AdminAreaLabels>;
+  className?: string;
+}
+
+/**
+ * The admin area's links to the admin tools that are pages of their own (0.42.0,
+ * docs/admin-harmonization.md §2.5 decision 16, §6.11): Translations, and the app's task
+ * pages (kastlan's Data import). The feedback inbox is not one of them: the top bar's
+ * feedback menu reaches it, and the overview's tiles link to it.
+ *
+ * Draw it twice from one list — at the foot of the section sidebar and in the phone
+ * footer:
+ *
+ *     <SettingsLayout
+ *       sidebarFooter={<AdminToolLinks links={TOOLS} />}
+ *       phoneFooter={<AdminToolLinks links={TOOLS} variant="list" />}
+ *       …
+ *     />
+ *
+ * With no visible link it renders nothing.
+ */
+export function AdminToolLinks({ links, variant = "sidebar", renderLink, labels: labelsProp, className }: AdminToolLinksProps) {
+  const labels = useAdminAreaLabels(labelsProp);
+  const headingId = useId();
+  const shown = links.filter((l) => l.visible !== false);
+  if (shown.length === 0) return null;
+  const rows = shown.map((l) => (
+    <ListItem
+      key={l.key}
+      href={l.href}
+      renderLink={renderLink}
+      title={l.label}
+      leading={
+        l.icon === undefined ? undefined : (
+          <span aria-hidden className="flex shrink-0 text-muted [&_svg]:size-4">
+            {l.icon}
+          </span>
+        )
+      }
+    />
+  ));
+  if (variant === "list") return <>{rows}</>;
+  return (
+    <nav data-slot="admin-tool-links" aria-labelledby={headingId} className={cn("space-y-1", className)}>
+      <div id={headingId} className="px-3 text-caption font-semibold uppercase tracking-wide text-muted">
+        {labels.tools}
+      </div>
+      <List density="compact">{rows}</List>
+    </nav>
+  );
+}

package/src/billing/billing-banner.tsx

@@ -1,6 +1,7 @@
 import type { ComponentPropsWithRef, ReactNode } from "react";
 import { CreditCard, Hourglass, PencilOff } from "lucide-react";
 
+import { DEFAULT_COMMON_LABELS, useKitLabels } from "../i18n/kit-labels";
 import type { LabelOverride } from "../i18n/kit-labels";
 import { AlertBanner } from "../components/alert-banner";
 import type { AlertSize, AlertTone } from "../components/alert-banner";
@@ -8,6 +9,8 @@ import { Button } from "../components/button";
 import { Spinner } from "../components/spinner";
 import { useBillingLabels } from "./billing-labels";
 import type { BillingLabels } from "./billing-labels";
+import type { BillingPortalAccess } from "./billing-overview";
+import { ExternalMark } from "./subscription-actions";
 
 /**
  * The billing banners (docs/billing-harmonization.md §3.3, §7, §12.6, §12.21):
@@ -16,7 +19,8 @@ import type { BillingLabels } from "./billing-labels";
  * - `grant-ending` — from 7 days before `comped_until`: a beta user's 12 months, an
  *   operator's grant;
  * - `payment-failed` — from the first failed payment (`past_due`), while the provider
- *   retries;
+ *   retries; since 0.42, for an admin who isn't the buyer (`portal="buyer_only"`), it
+ *   names who can update the payment method, with no button;
  * - `plan-ended` — out of good standing: read-only, never locked (§2.3);
  * - `guest` — a guest in someone else's read-only item (§12.6);
  * - `processing` — back from checkout before the webhook landed (§12.21).
@@ -64,6 +68,14 @@ interface BillingBannerBaseProps extends Omit<ComponentPropsWithRef<"div">, "chi
   actionLabel?: string;
   /** The action is under way: the button's spinner, no second press. */
   actionPending?: boolean;
+  /**
+   * 0.43 (§17): the action opens the provider's portal in a NEW TAB (`openProviderPage`
+   * in {@link onAction}): the external-link mark, "(opens in a new tab)" for a reader,
+   * and `target="_blank"` on an {@link actionHref}. Default: true for `payment-failed`
+   * with `onAction` (the portal's card page), false otherwise — an `actionHref` is
+   * usually the app's own subscription page.
+   */
+  actionNewTab?: boolean;
   /** An × that calls this; the app removes the banner and remembers that it did. */
   onDismiss?: () => void;
   dismissLabel?: string;
@@ -78,6 +90,8 @@ export type BillingBannerProps = BillingBannerBaseProps &
         /** Calendar days left — `billingDaysLeft(trial_ends_at)`. 0 is today. */
         daysLeft: number;
         item?: never;
+        portal?: never;
+        buyerName?: never;
       }
     | {
         kind: "guest";
@@ -85,11 +99,31 @@ export type BillingBannerProps = BillingBannerBaseProps &
          *  the banner says "for now" and nothing more (§12.6). */
         item?: string;
         daysLeft?: never;
+        portal?: never;
+        buyerName?: never;
+      }
+    | {
+        kind: "payment-failed";
+        /**
+         * 0.42 (§16.7 A, §16.8): `GET /billing/status`'s `portal` (`BillingStanding`).
+         * `"buyer_only"` — the viewer isn't the buyer, so the portal's page for the card
+         * would answer 403: the banner says who can update the payment method
+         * (`paymentFailedAskBuyer`) and shows NO button, whatever `actionHref` or
+         * `onAction` say. `"open"` (default): as before.
+         */
+        portal?: BillingPortalAccess;
+        /** 0.42: the status's `buyer_name`, under `"buyer_only"`. Empty: "…the admin who
+         *  bought the subscription". */
+        buyerName?: string | null;
+        daysLeft?: never;
+        item?: never;
       }
     | {
-        kind: "payment-failed" | "plan-ended" | "processing";
+        kind: "plan-ended" | "processing";
         daysLeft?: never;
         item?: never;
+        portal?: never;
+        buyerName?: never;
       }
   );
 
@@ -128,6 +162,8 @@ export function BillingBanner(props: BillingBannerProps) {
     kind,
     daysLeft,
     item,
+    portal,
+    buyerName,
     tone,
     variant = "strip",
     size,
@@ -135,6 +171,7 @@ export function BillingBanner(props: BillingBannerProps) {
     onAction,
     actionLabel,
     actionPending,
+    actionNewTab,
     onDismiss,
     dismissLabel,
     labels: labelsProp,
@@ -142,11 +179,14 @@ export function BillingBanner(props: BillingBannerProps) {
     ...rest
   } = props;
   const labels = useBillingLabels(labelsProp);
+  const common = useKitLabels("common", DEFAULT_COMMON_LABELS);
   const days = Math.max(0, Math.floor(daysLeft ?? 0));
 
   let text: string;
   let icon: ReactNode;
   let ownAction: string | undefined;
+  // 0.42 (§16.7 A): only the buyer can reach the portal's card page.
+  const askBuyer = kind === "payment-failed" && portal === "buyer_only";
   switch (kind) {
     case "trial-ending":
       text = labels.trialEnding(days);
@@ -159,7 +199,7 @@ export function BillingBanner(props: BillingBannerProps) {
       ownAction = labels.choosePlan;
       break;
     case "payment-failed":
-      text = labels.paymentFailed;
+      text = askBuyer ? labels.paymentFailedAskBuyer(buyerName || undefined) : labels.paymentFailed;
       icon = <CreditCard />;
       ownAction = labels.updatePayment;
       break;
@@ -181,14 +221,25 @@ export function BillingBanner(props: BillingBannerProps) {
   }
 
   const words = actionLabel ?? ownAction;
+  const newTab = actionNewTab ?? (kind === "payment-failed" && actionHref === undefined && onAction !== undefined);
   const action =
-    words === undefined || (actionHref === undefined && onAction === undefined) ? undefined : actionHref !== undefined ? (
-      <Button href={actionHref} variant="secondary" size="sm">
+    askBuyer || words === undefined || (actionHref === undefined && onAction === undefined) ? undefined : actionHref !== undefined ? (
+      <Button href={actionHref} variant="secondary" size="sm" external={newTab || undefined}>
         {words}
+        {newTab && <ExternalMark />}
       </Button>
     ) : (
-      <Button type="button" variant="secondary" size="sm" onClick={onAction} pending={actionPending}>
+      <Button
+        type="button"
+        variant="secondary"
+        size="sm"
+        onClick={onAction}
+        pending={actionPending}
+        className={newTab ? "relative" : undefined}
+        data-portal-action={newTab ? "payment_method" : undefined}
+      >
         {words}
+        {newTab && <ExternalMark reader={common.opensInNewTab} />}
       </Button>
     );