@eifi1/ui-kit 0.42.0 → 0.43.0

package/src/admin/admin-area-labels.ts

@@ -48,6 +48,10 @@ export interface AdminAreaLabels {
   sections: Record<AdminSharedSection, SettingsGroupLabels>;
   /** The overview's tiles. */
   tiles: AdminTileLabels;
+  /** 0.43: `AdminOverview`'s `error` — the counts could not be loaded. */
+  overviewError: string;
+  /** 0.43: its button, which calls `onRetry`. */
+  retry: string;
   /** The Tools list's heading and name (§2.5 decision 16). */
   tools: string;
 }
@@ -62,7 +66,7 @@ export const DEFAULT_ADMIN_AREA_LABELS: AdminAreaLabels = {
   sections: {
     overview: { title: "Overview", help: "What is waiting, at a glance." },
     users: { title: "Users", help: "Who has an account, and what each may do." },
-    invitations: { title: "Invitations", help: "The links that let a new person in." },
+    invitations: { title: "Invitations", help: "Invite people by e-mail in their language; resend or revoke what’s still open." },
     billing: { title: "Billing", help: "The plan, the payment and the invoices." },
     activity: { title: "Activity", help: "What the admins did, newest first." },
   },
@@ -73,6 +77,8 @@ export const DEFAULT_ADMIN_AREA_LABELS: AdminAreaLabels = {
     users: "Users",
     usersNew: (count) => `${count} new in 7 days`,
   },
+  overviewError: "The overview couldn’t be loaded.",
+  retry: "Try again",
   tools: "Tools",
 };
 

package/src/admin/admin-overview.tsx

@@ -1,7 +1,10 @@
 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";
 
@@ -68,14 +71,16 @@ export function adminWaitingCount(
 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. */
-  href: string;
+  /** 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.
+ * `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} />;
@@ -88,7 +93,9 @@ export interface AdminExtraTile {
   label: ReactNode;
   /** `null` or `undefined` leaves the tile out, as for a shared one. */
   count: number | null | undefined;
-  href: string;
+  /** 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;
 }
@@ -106,6 +113,18 @@ export interface AdminOverviewProps {
   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;
@@ -117,19 +136,43 @@ export interface AdminOverviewProps {
  * 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".
  *
- * Put it in the `overview` section's `SettingsSection` (titled by the sidebar, so
- * `titleVisible={false}`). keksdose links its metrics from here with at most two tiles
- * (§6.5).
+ * 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 }[] = [
@@ -147,9 +190,9 @@ export function AdminOverview({
     ...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 null;
-  return (
-    <StatTileGrid data-slot="admin-overview" loading={loading} className={className}>
+  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}
@@ -163,4 +206,12 @@ export function AdminOverview({
       ))}
     </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

@@ -41,12 +41,27 @@ export interface AdminOwnSection<G extends string = string> extends SettingsGrou
   after?: AdminSharedSection | G;
 }
 
-export interface AdminSectionsOptions {
+/** 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.
+   * 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 AdminSharedSection[];
+  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),
@@ -55,37 +70,23 @@ export interface AdminSectionsOptions {
   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";
 
-/**
- * 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).
- *
- *     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>(
-  labels: AdminAreaLabels | undefined,
-  own: readonly AdminOwnSection<G>[] = [],
-  options: AdminSectionsOptions = {},
-): SettingsGroup<AdminSharedSection | G>[] {
-  const words = labels ?? DEFAULT_ADMIN_AREA_LABELS;
-  const leaveOut = new Set<string>(options.leaveOut ?? []);
+/** 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) {
@@ -102,36 +103,96 @@ export function adminSections<G extends string = never>(
 
   // 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, AdminOwnSection<G>[]>();
+  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: SettingsGroup<AdminSharedSection | G>[] = [];
+  const out: ({ shared: AdminSectionDefinition } | { own: S })[] = [];
+  const placed = new Set<string>();
   const placeAfter = (id: string) => {
     for (const section of followers.get(id) ?? []) {
-      const { after: _after, ...group } = section;
-      out.push(group);
+      out.push({ own: section });
+      placed.add(section.id);
       placeAfter(section.id);
     }
   };
-  for (const { id, icon } of ADMIN_SECTIONS) {
-    if (!leaveOut.has(id)) {
-      const visible = options.visible?.[id];
-      out.push({
-        id,
-        icon: createElement(icon, { "aria-hidden": true }) as ReactNode,
-        title: words.sections[id].title,
-        help: words.sections[id].help,
-        ...(visible === undefined ? null : { visible }),
-      });
-    }
+  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(id);
+    placeAfter(definition.id);
   }
-  const placed = new Set<string>(out.map((g) => g.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/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";
@@ -9,6 +10,7 @@ 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):
@@ -66,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;
@@ -161,6 +171,7 @@ export function BillingBanner(props: BillingBannerProps) {
     onAction,
     actionLabel,
     actionPending,
+    actionNewTab,
     onDismiss,
     dismissLabel,
     labels: labelsProp,
@@ -168,6 +179,7 @@ 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;
@@ -209,14 +221,25 @@ export function BillingBanner(props: BillingBannerProps) {
   }
 
   const words = actionLabel ?? ownAction;
+  const newTab = actionNewTab ?? (kind === "payment-failed" && actionHref === undefined && onAction !== undefined);
   const action =
     askBuyer || words === undefined || (actionHref === undefined && onAction === undefined) ? undefined : actionHref !== undefined ? (
-      <Button href={actionHref} variant="secondary" size="sm">
+      <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>
     );
 

package/src/billing/billing-labels.ts

@@ -179,6 +179,10 @@ export interface BillingLabels {
   /** In place of "Cancel subscription" while a cancel is scheduled (§16.7 C, `POST
    *  /billing/resume`): "Keep subscription". */
   keepSubscription: string;
+  /** 0.43 (§17.3): the muted note under the actions while the portal opens in a new tab —
+   *  `provider` the provider's name ("Paddle"), `app` the app's; without the app, "this
+   *  page". "Payment and invoices open at Paddle in a new tab; Kastlan stays open here." */
+  portalOpensNewTab: (provider: string, app?: string) => string;
 
   /* ── The pay page (§14.4) ── */
   /* Built into the static page `dist/pay/` at the kit's build: it has no React and no
@@ -334,6 +338,8 @@ export const DEFAULT_BILLING_LABELS: BillingLabels = {
   cancelConfirmBody: (date) => `Your subscription ends on ${date}. Until then everything works as before.`,
   cancelConfirmAction: "Cancel subscription now",
   keepSubscription: "Keep subscription",
+  portalOpensNewTab: (provider, app) =>
+    `Payment and invoices open at ${provider} in a new tab; ${app ? `${app} stays open here` : "this page stays open"}.`,
 
   payOpening: "Opening the secure checkout…",
   payNothing: "There’s no payment to make here. To choose a plan, go back to the app.",

package/src/billing/cancel-request.ts

@@ -0,0 +1,75 @@
+import { useState } from "react";
+
+/**
+ * What the payer asked for in the app (0.43, kastlan `18bf4c0`): `"cancel"` after
+ * `POST /billing/cancel` answered 204, `"resume"` after `POST /billing/resume` — while the
+ * overview still shows the old `cancel_at_period_end`, until the provider's
+ * `subscription.updated` has landed (§16.3). `null`: nothing asked, or the row has moved.
+ */
+export type CancelRequested = "cancel" | "resume" | null;
+
+/** What the page shows for the row as read now — `CancelRequest.view(rowScheduled)`. */
+export interface CancelRequestView {
+  /** For `SubscriptionActions`' `cancelRequested`. */
+  requested: CancelRequested;
+  /** What the plan line says — the asked-for state until the row moves, then the row's:
+   *  "Cancels on …" at once after a cancel, "Renews on …" after "Keep subscription". */
+  cancelScheduled: boolean;
+  /** Call on the 204 of a cancel or of a resume. A cancel and its undo both asked before
+   *  the row moved cancel out. */
+  noteAsked: () => void;
+}
+
+export interface CancelRequest {
+  /** Read the overview again every few seconds while this is true — the overview query's
+   *  `waiting` (kastlan's `useBillingOverview({ waiting })`, a `refetchInterval` inside) —
+   *  so the page follows the provider. Needs no overview data: pass it to the query. */
+  waiting: boolean;
+  /**
+   * The row as read now (the overview's `cancel_at_period_end`; `undefined` while it
+   * loads) → what the page shows. Call it during render, after the query: when the row
+   * has moved past what was asked, it drops the request (React's "adjust state while
+   * rendering" pattern), so `waiting` turns false and the query stops polling.
+   */
+  view: (rowScheduled: boolean | null | undefined) => CancelRequestView;
+}
+
+/**
+ * The in-app cancel's follow-up (0.43, kastlan's derivation in `18bf4c0`): after "Cancel
+ * subscription now" or "Keep subscription" the server answers 204 at once, but the row's
+ * `cancel_at_period_end` only changes when the provider's webhook lands. Until then the
+ * page shows what was asked for, and a second press would ask the provider again.
+ *
+ * The state lives in the hook and needs no overview at construction, so it goes BEFORE
+ * the overview query, which reads `waiting`, and the view comes after it — the overview
+ * read once (build review 0.43, kastlan B2; kastlan `subscription-section.tsx:74-92`):
+ *
+ *     const request = useCancelRequest();
+ *     const { data } = useBillingOverview({ waiting: request.waiting });
+ *     const view = request.view(data?.cancel_at_period_end);
+ *     <p>{standingLine({ ...data, cancel_at_period_end: view.cancelScheduled })}</p>
+ *     <SubscriptionActions
+ *       cancelAtPeriodEnd={data.cancel_at_period_end}
+ *       cancelRequested={view.requested}
+ *       onResume={() => resume.mutate(undefined, { onSuccess: view.noteAsked })}
+ *       …
+ *     />
+ */
+export function useCancelRequest(): CancelRequest {
+  // What was asked, kept with the row's state it was asked against.
+  const [asked, setAsked] = useState<{ scheduled: boolean } | null>(null);
+  const view = (row: boolean | null | undefined): CancelRequestView => {
+    // Not read yet: nothing to show against, and nothing to drop.
+    if (row === undefined || row === null) return { requested: null, cancelScheduled: false, noteAsked: () => {} };
+    // The row has moved: it says the rest. Adjusted during render, React's pattern for
+    // state that follows a prop.
+    if (asked !== null && asked.scheduled !== row) setAsked(null);
+    const open = asked !== null && asked.scheduled === row;
+    return {
+      requested: open ? (row ? "resume" : "cancel") : null,
+      cancelScheduled: open ? !row : row,
+      noteAsked: () => setAsked((a) => (a !== null && a.scheduled === row ? null : { scheduled: row })),
+    };
+  };
+  return { waiting: asked !== null, view };
+}

package/src/billing/provider-page.ts

@@ -0,0 +1,75 @@
+/**
+ * The provider's hosted portal in a NEW TAB (0.43, docs/billing-harmonization.md §17):
+ * "Payment and invoices", the portal's "Cancel subscription" and the payment-failed
+ * banner's "Update payment method" open at the provider while the app stays open where
+ * it was. kastlan's `usePortal` (feat/kit-0.42, `72c3177`) is the reference.
+ *
+ * The checkout is NOT one of them (§17.4): it stays in the same tab, since the page waits
+ * for the payer's return (`useCheckoutProcessing`).
+ */
+
+/** How the page went: in a tab of its own, or — the browser refused one — in this one. */
+export type ProviderPageWay = "new-tab" | "same-tab";
+
+export interface OpenProviderPageOptions {
+  /** The window to open from and to fall back to. Default the global `window` (a test's
+   *  or an iframe's own). */
+  window?: Window;
+}
+
+/**
+ * Opens the provider's page in a new tab, from INSIDE the click: call it in the click
+ * handler itself, before any `await` — a `window.open` after one is blocked as a pop-up.
+ *
+ * 1. opens `about:blank` synchronously and sets its `opener` to `null`, so the provider's
+ *    page cannot reach back into the app;
+ * 2. awaits `fetchUrl` — the app's `POST /billing/portal` with its target, answering the
+ *    `url` (the kit sends no request);
+ * 3. points the tab at the URL;
+ * 4. on a refusal closes the tab again and rethrows, so the app shows its error;
+ * 5. where the browser refused the tab (a pop-up blocker), or it was closed while the
+ *    URL was on its way, the app's own page goes there instead.
+ *
+ *     <SubscriptionActions
+ *       onPortal={(target) => {
+ *         openProviderPage(() => api.billingPortal({ target }).then((r) => r.url)).catch(showError);
+ *       }}
+ *       providerName="Paddle"
+ *       appName="Kastlan"
+ *     />
+ *
+ * Resolves with the way it went.
+ */
+export async function openProviderPage(
+  fetchUrl: () => Promise<string>,
+  options: OpenProviderPageOptions = {},
+): Promise<ProviderPageWay> {
+  const win = options.window ?? window;
+  let tab: Window | null;
+  try {
+    tab = win.open("about:blank", "_blank");
+  } catch {
+    tab = null;
+  }
+  if (tab) {
+    try {
+      // The provider's page must not reach back into the app.
+      tab.opener = null;
+    } catch {
+      /* a browser that guards `opener`: the tab is still ours to point */
+    }
+  }
+  let url: string;
+  try {
+    url = await fetchUrl();
+  } catch (error) {
+    tab?.close();
+    throw error;
+  }
+  if (tab && !tab.closed) {
+    tab.location.href = url;
+    return "new-tab";
+  }
+  win.location.assign(url);
+  return "same-tab";
+}