@eifi1/ui-kit 0.51.6 → 0.52.0

package/src/admin/plan-change.tsx

@@ -18,7 +18,8 @@ import { AdminActionConfirm } from "./admin-action-confirm";
 import type { AdminActionConfirmValues } from "./admin-action-confirm";
 import { personLabel, useDayText } from "./admin-parts";
 import type { AdminPerson, MaybePromise } from "./admin-parts";
-import { DEFAULT_PLAN_CHANGE_LABELS } from "./plan-change-labels";
+import { DEFAULT_PLAN_CHANGE_LABELS } from "../billing/plan-change-labels";
+import type { PlanChangeLabels } from "../billing/plan-change-labels";
 
 /**
  * The operator's plan parts (docs/billing-harmonization.md §14.12, decision 27):
@@ -34,49 +35,11 @@ import { DEFAULT_PLAN_CHANGE_LABELS } from "./plan-change-labels";
  * whatever the billing switch says.
  */
 
-/** The `planChange` namespace: the column, the grant dialog and the result's lines. */
-export interface PlanChangeLabels {
-  /** The column's header: "Plan". */
-  column: string;
-  /** The dialog's title: "Change plan". */
-  title: string;
-  /** Its confirm button: "Change plan". */
-  confirm: string;
-  /** The plan select's label: "Plan". */
-  plan: string;
-  /** The line over the select: "Current plan: Free". */
-  current: (plan: string) => string;
-  /** Under the select — the fact that is not on the button. */
-  keepsItems: string;
-  /** The end of a free grant's field: "Free until". */
-  until: string;
-  /** Under it. */
-  untilHint: string;
-  /** Why the confirm is held while nothing would change. */
-  needsChange: string;
-  /** The result: the plan moved from one to another. */
-  changed: (from: string, to: string) => string;
-  /** The result: an account with no plan before, or the same plan again. */
-  set: (to: string) => string;
-  /** The result: a running beta kept its own end (§12.34); only the plan moved. */
-  keptBeta: string;
-  /** The result: the grant runs until `date` (formatted). */
-  untilDone: (date: string) => string;
-  /** The result: the account owns more than the new plan allows. */
-  overLimit: string;
-  /**
-   * The column's usage, spelled out (its tooltip): "1 of 5 budgets". Figures arrive
-   * formatted; `dimension` is the app's word, as `usage.label` gives it — since 0.33.1
-   * in the form the LIMIT takes when the label gives its plural forms ("1 of 1 budget",
-   * "1 of 5 budgets"): in every shipped language the word follows the limit, or heads
-   * the line in German, whose `von` would want a dative plural no app form carries
-   * ("Budgets: 1 von 5"). An override of yours gets the same word. Since 0.34 the grant
-   * dialog's usage line too, when `usage` comes as the column's shape.
-   */
-  usageOf: (used: string, limit: string, dimension: string) => string;
-}
-
-// Defined in ./plan-change-labels, which holds no component code (0.34, KS U8).
+// The words and their type live in billing/plan-change-labels, which holds no component
+// code (0.34, KS U8): PlanSwitchConfirm reads them too, and billing importing admin while
+// this module imports billing made the two folders import each other (refactor audit
+// 2026-10-30, MOD-6).
+export type { PlanChangeLabels };
 export { DEFAULT_PLAN_CHANGE_LABELS };
 
 /** A plan code as the parts compare it: lowercase (§12.16 — an older row's "FREE" is

package/src/admin/reviewer-scope-editor.tsx

@@ -8,6 +8,7 @@ import { CheckboxGroup } from "../components/checkbox-group";
 import type { CheckboxGroupOption } from "../components/checkbox-group";
 import { FormActions } from "../components/form-actions";
 import { Caption } from "../components/text";
+import { describeFailure } from "../lib/describe-failure";
 import { hasContent } from "../lib/presence";
 import type { MaybePromise } from "./admin-parts";
 import type { CommitScope } from "../components/write-lock";
@@ -165,7 +166,7 @@ export function ReviewerScopeEditor({
     try {
       result = onSave(scope);
     } catch (error) {
-      setFailure(describeError?.(error) ?? labels.failed);
+      setFailure(describeFailure(describeError?.(error), labels.failed));
       return;
     }
     if (!result || typeof result.then !== "function") return;
@@ -174,8 +175,7 @@ export function ReviewerScopeEditor({
       () => setPending(false),
       (error: unknown) => {
         setPending(false);
-        const own = describeError?.(error);
-        setFailure(hasContent(own) ? own : labels.failed);
+        setFailure(describeFailure(describeError?.(error), labels.failed));
       },
     );
   };

package/src/auth/auth-errors-labels.ts

@@ -0,0 +1,23 @@
+// The English of every `rateLimited` label, in a module with no component code and no
+// error probing: the English catalogue (src/i18n/defaults.ts) reaches it through nine
+// `*-labels.ts` modules, and until 0.52 that pulled `auth/auth-errors` — and since MOD-6
+// its `lib/http-status` — into the `en` chunk (refactor audit 2026-10-30, MOD-6).
+// auth/auth-errors re-exports both.
+
+/**
+ * The English of every `rateLimited` label (0.30.0): "Too many attempts. Try again in
+ * 30 s." with a wait under a minute, in whole minutes from one minute up (keksdose's
+ * reset throttle answers in hours, and "3600 s" is a number nobody reads), and "Wait a
+ * moment and try again." without one — or with a `0`.
+ *
+ * @internal The namespaces' English; not part of the barrel.
+ */
+export function englishRateLimited(seconds?: number): string {
+  if (!seconds || seconds <= 0) return "Too many attempts. Wait a moment and try again.";
+  return `Too many attempts. Try again in ${englishWait(seconds)}.`;
+}
+
+/** "30 s", "2 min" — a wait in English, rounded up. @internal */
+export function englishWait(seconds: number): string {
+  return seconds < 60 ? `${Math.ceil(seconds)} s` : `${Math.ceil(seconds / 60)} min`;
+}

package/src/auth/auth-errors.ts

@@ -1,3 +1,5 @@
+import { httpStatusOf } from "../lib/http-status";
+
 /**
  * The coded refusals of sign-in and sign-up (docs/auth-harmonization.md §5.2): every
  * refusal the auth routes answer carries a machine-readable `code`, and the pages
@@ -274,29 +276,13 @@ export function errorBodyWithCode(
   return undefined;
 }
 
-/** An HTTP status as a number, or undefined. */
-function statusOf(value: unknown): number | undefined {
-  return typeof value === "number" && Number.isInteger(value) ? value : undefined;
-}
-
 /**
- * The HTTP status a thrown error carries, wherever the apps' HTTP clients put it —
- * without depending on any of them:
- *
- *  1. `err.response.status` — axios (all three apps' clients);
- *  2. `err.status` — ofetch's `FetchError`, the generated OpenAPI clients' `ApiError`, and
- *     a `Response` thrown as it came;
- *  3. `err.statusCode` — ofetch's alias, and Node-style errors.
- *
- * `undefined` when none is a whole number. Package-private — not re-exported from the
- * barrel; {@link isRateLimited} and the session refresh's classifier read it (DUP-11,
- * refactor audit 2026-10: the refresh carried its own copy of this probe).
+ * The HTTP status a thrown error carries ({@link httpStatusOf}): axios'
+ * `response.status`, then `status`, then `statusCode`. Lives in `lib/http-status.ts`
+ * since 0.52 (refactor audit 2026-10-30, MOD-6); re-exported here for the modules that
+ * import it from auth. Package-private — not re-exported from the barrel.
  */
-export function httpStatusOf(err: unknown): number | undefined {
-  if (!isBag(err)) return undefined;
-  const response = err.response;
-  return (isBag(response) ? statusOf(response.status) : undefined) ?? statusOf(err.status) ?? statusOf(err.statusCode);
-}
+export { httpStatusOf };
 
 /**
  * Whether `err` is a throttled request — HTTP `429 Too Many Requests` (0.30.0, from the
@@ -378,20 +364,7 @@ export function retryAfterSeconds(err: unknown, now: number | Date = Date.now())
   return value === undefined ? undefined : parseRetryAfter(value, at);
 }
 
-/**
- * The English of every `rateLimited` label (0.30.0): "Too many attempts. Try again in
- * 30 s." with a wait under a minute, in whole minutes from one minute up (keksdose's
- * reset throttle answers in hours, and "3600 s" is a number nobody reads), and "Wait a
- * moment and try again." without one — or with a `0`.
- *
- * @internal The namespaces' English; not part of the barrel.
- */
-export function englishRateLimited(seconds?: number): string {
-  if (!seconds || seconds <= 0) return "Too many attempts. Wait a moment and try again.";
-  return `Too many attempts. Try again in ${englishWait(seconds)}.`;
-}
-
-/** "30 s", "2 min" — a wait in English, rounded up. @internal */
-export function englishWait(seconds: number): string {
-  return seconds < 60 ? `${Math.ceil(seconds)} s` : `${Math.ceil(seconds / 60)} min`;
-}
+// The English of the `rateLimited` labels, in auth-errors-labels since 0.52: the English
+// catalogue reached this module for them, and with it `lib/http-status` (refactor audit
+// 2026-10-30, MOD-6). Re-exported for the modules that import them from here.
+export { englishRateLimited, englishWait } from "./auth-errors-labels";

package/src/auth/complete-name-dialog.tsx

@@ -1,7 +1,8 @@
 import { useContext, useEffect, useId, useRef, useState } from "react";
-import type { KeyboardEvent, ReactNode } from "react";
+import type { ReactNode } from "react";
 
 import { useKitLabels, type LabelOverride } from "../i18n/kit-labels";
+import { describeFailure } from "../lib/describe-failure";
 import { usePromisePending } from "../components/danger-confirm";
 import { DialogFrame } from "../components/dialog-frame";
 import { ModalCloseContext } from "../components/modal";
@@ -74,8 +75,9 @@ export interface CompleteNameDialogProps {
  * complete name, no page is blocked, and the app asks again at the next sign-in.
  *
  * The promise handling is `ReauthDialog`'s: busy while `onSave` runs (the fields
- * read-only, "Later" disabled, Escape held — a request that has left cannot be called
- * back by closing the dialog), closed on resolve, kept open on reject. Save is a
+ * read-only, "Later" disabled, Escape, the backdrop and Back held — a request that has
+ * left cannot be called back by closing the dialog), closed on resolve, kept open on
+ * reject. Save is a
  * `commit` control, so a `WriteLockProvider` above it locks it with its reason — every
  * lock but a lapsed plan's (`COMMIT_EXCEPT_BILLING`, 0.33): one's own name is the
  * account's own settings, which billing never locks (docs/billing-harmonization.md §3.3,
@@ -152,7 +154,9 @@ export function CompleteNameDialog({
     setFailed(false);
   };
 
-  const message = failed ? (error ?? labels.failed) : undefined;
+  // An app's `failed && words` before it has words is `false`, which `??` kept (refactor
+  // audit 2026-10-30, DUP-14): the kit's sentence unless the app's says something.
+  const message = failed ? describeFailure(error, labels.failed) : undefined;
 
   return (
     <DialogFrame
@@ -160,10 +164,7 @@ export function CompleteNameDialog({
       title={labels.title}
       description={labels.description}
       onClose={() => onClose(saved.current)}
-      onKeyDown={(e: KeyboardEvent<HTMLDivElement>) => {
-        if (pending && e.key === "Escape") e.preventDefault();
-      }}
-      aria-busy={pending || undefined}
+      busy={pending}
       actions={
         <CompleteNameActions
           formId={formId}

package/src/auth/forgot-password-form-labels.ts

@@ -3,7 +3,7 @@
 // loads as one chunk like the other languages (0.34, KS U8). ./forgot-password-form
 // re-exports them.
 
-import { englishRateLimited } from "./auth-errors";
+import { englishRateLimited } from "./auth-errors-labels";
 import type { ForgotPasswordLabels } from "./forgot-password-form";
 
 /** `Required`: every key, the 0.30 one included, has its English here. */

package/src/auth/forgot-password-form.tsx

@@ -2,13 +2,15 @@ import { useId, useRef, useState } from "react";
 import type { ComponentPropsWithRef, FormEvent, ReactNode } from "react";
 import { MailCheck } from "lucide-react";
 import { cn } from "../lib/cn";
+import { describeFailure } from "../lib/describe-failure";
 import { useKitLabels, type LabelOverride } from "../i18n/kit-labels";
 import { AlertBanner } from "../components/alert-banner";
 import { TextLink } from "../components/text-link";
 import { Button } from "../components/button";
 import { Input } from "../components/input";
 import { isRateLimited, retryAfterSeconds } from "./auth-errors";
-import { FORM_HEADING_CLASS, INTRO_CLASS, OutcomeMessage, isThenable, useFocusWhen } from "./status-parts";
+import { isThenable } from "../lib/thenable";
+import { FORM_HEADING_CLASS, INTRO_CLASS, OutcomeMessage, useFocusWhen } from "./status-parts";
 import type { AuthHeadingLevel } from "./status-parts";
 import { DEFAULT_FORGOT_PASSWORD_LABELS } from "./forgot-password-form-labels";
 
@@ -146,12 +148,15 @@ export function ForgotPasswordForm({
     );
   }
 
-  // The app's words first, then the throttle's, then the kit's catch-all.
+  // The app's words first, then the throttle's, then the kit's catch-all — an app's ""
+  // is no words (refactor audit 2026-10-30, DUP-14: `??` drew an empty alert).
   const failureFor = (error: unknown): ReactNode =>
-    describeError?.(error) ??
-    (isRateLimited(error)
-      ? (labels.rateLimited ?? DEFAULT_FORGOT_PASSWORD_LABELS.rateLimited)(retryAfterSeconds(error))
-      : labels.error);
+    describeFailure(
+      describeError?.(error),
+      isRateLimited(error)
+        ? (labels.rateLimited ?? DEFAULT_FORGOT_PASSWORD_LABELS.rateLimited)(retryAfterSeconds(error))
+        : labels.error,
+    );
 
   const submit = (e: FormEvent) => {
     e.preventDefault();

package/src/auth/register-form-labels.ts

@@ -2,7 +2,7 @@
 // catalogue (src/i18n/defaults.ts) imports them without the component, so `en` loads as one
 // chunk like the other languages (0.34, KS U8). ./register-form re-exports them.
 
-import { englishRateLimited } from "./auth-errors";
+import { englishRateLimited } from "./auth-errors-labels";
 import type { RegisterLabels } from "./register-form";
 
 /** `Required`: every key, the 0.30 one included, has its English here. */

package/src/auth/reset-password-form-labels.ts

@@ -3,7 +3,7 @@
 // loads as one chunk like the other languages (0.34, KS U8). ./reset-password-form
 // re-exports them.
 
-import { englishRateLimited } from "./auth-errors";
+import { englishRateLimited } from "./auth-errors-labels";
 import type { ResetPasswordLabels } from "./reset-password-form";
 
 /** `Required`: every key, the 0.30 one included, has its English here. */

package/src/auth/reset-password-form.tsx

@@ -2,6 +2,7 @@ import { useEffect, useId, useRef, useState } from "react";
 import type { ComponentPropsWithRef, FormEvent, ReactNode } from "react";
 import { CheckCircle2, XCircle } from "lucide-react";
 import { cn } from "../lib/cn";
+import { describeFailure } from "../lib/describe-failure";
 import { useKitLabels, type LabelOverride } from "../i18n/kit-labels";
 import { AlertBanner } from "../components/alert-banner";
 import { LoadingState } from "../components/loading-state";
@@ -291,12 +292,15 @@ export function ResetPasswordForm({
             setPhase({ token, phase: { kind: "invalid" } });
             return;
           }
-          // The app's words first, then the throttle's, then the kit's catch-all.
+          // The app's words first, then the throttle's, then the kit's catch-all — an app's
+          // "" is no words (refactor audit 2026-10-30, DUP-14: `??` drew an empty alert).
           setFailure(
-            describeError?.(error) ??
-              (isRateLimited(error)
+            describeFailure(
+              describeError?.(error),
+              isRateLimited(error)
                 ? (labels.rateLimited ?? DEFAULT_RESET_PASSWORD_LABELS.rateLimited)(retryAfterSeconds(error))
-                : labels.failed),
+                : labels.failed,
+            ),
           );
         },
       );

package/src/auth/sign-in-form-labels.ts

@@ -2,7 +2,7 @@
 // catalogue (src/i18n/defaults.ts) imports them without the component, so `en` loads as one
 // chunk like the other languages (0.34, KS U8). ./sign-in-form re-exports them.
 
-import { englishRateLimited } from "./auth-errors";
+import { englishRateLimited } from "./auth-errors-labels";
 import type { SignInLabels } from "./sign-in-form";
 
 /** `Required`: every key, the 0.30 ones included, has its English here. */

package/src/auth/status-parts.tsx

@@ -91,12 +91,6 @@ export function useOncePerKey<T>(
   }, [key]);
 }
 
-/** Whether a callback's return is a promise to wait for. A callback that returns
- *  nothing is done when it returns. */
-export function isThenable(value: unknown): value is PromiseLike<unknown> {
-  return typeof (value as PromiseLike<unknown> | null)?.then === "function";
-}
-
 /**
  * Move focus to `ref` when `active` turns true — the outcome a person's own submit led
  * to ("If an account exists … the link is on its way", "Your password has been

package/src/auth/verify-email-labels.ts

@@ -2,7 +2,7 @@
 // catalogue (src/i18n/defaults.ts) imports them without the component, so `en` loads as one
 // chunk like the other languages (0.34, KS U8). ./verify-email re-exports them.
 
-import { englishRateLimited } from "./auth-errors";
+import { englishRateLimited } from "./auth-errors-labels";
 import type { VerifyEmailLabels } from "./verify-email";
 
 export const DEFAULT_VERIFY_EMAIL_LABELS: VerifyEmailLabels = {

package/src/auth/verify-email.tsx

@@ -2,13 +2,15 @@ import { useEffect, useState } from "react";
 import type { ComponentPropsWithRef, ReactNode } from "react";
 import { CheckCircle2, MailWarning, TimerOff, XCircle } from "lucide-react";
 import { cn } from "../lib/cn";
+import { describeFailure } from "../lib/describe-failure";
 import { useKitLabels, type LabelOverride } from "../i18n/kit-labels";
 import { useAnnounce } from "../hooks/use-announce";
 import { AlertBanner } from "../components/alert-banner";
 import { LoadingState } from "../components/loading-state";
 import { Button } from "../components/button";
 import { EmptyState } from "../components/empty-state";
-import { OUTCOME_CLASS, STATUS_HEADING_CLASS, isThenable, useOncePerKey } from "./status-parts";
+import { isThenable } from "../lib/thenable";
+import { OUTCOME_CLASS, STATUS_HEADING_CLASS, useOncePerKey } from "./status-parts";
 import { authErrorCode, englishRateLimited, isRateLimited, retryAfterSeconds } from "./auth-errors";
 import type { AuthHeadingLevel } from "./status-parts";
 import { DEFAULT_VERIFY_EMAIL_LABELS } from "./verify-email-labels";
@@ -150,13 +152,16 @@ function ResendStatus({
   labels: VerifyEmailLabels;
   className?: string;
 }) {
-  // The app's words first, then the throttle's, then the kit's catch-all.
+  // The app's words first, then the throttle's, then the kit's catch-all — an app's ""
+  // is no words (refactor audit 2026-10-30, DUP-14: `??` printed an empty status).
   const failed =
     phase === "failed"
-      ? (describeError?.(error) ??
-        (isRateLimited(error)
-          ? (labels.rateLimited ?? englishRateLimited)(retryAfterSeconds(error))
-          : labels.resendError))
+      ? describeFailure(
+          describeError?.(error),
+          isRateLimited(error)
+            ? (labels.rateLimited ?? englishRateLimited)(retryAfterSeconds(error))
+            : labels.resendError,
+        )
       : "";
   return (
     <span role="status" className={cn(phase === "failed" ? "text-danger" : "text-success", className)}>

package/src/billing/cancel-request.ts

@@ -1,4 +1,4 @@
-import { useState } from "react";
+import { useEffect, useState } from "react";
 
 /**
  * What the payer asked for in the app (0.43, kastlan `18bf4c0`): `"cancel"` after
@@ -8,6 +8,9 @@ import { useState } from "react";
  */
 export type CancelRequested = "cancel" | "resume" | null;
 
+/** How long a request waits for the provider's webhook: `useCheckoutProcessing`'s bound. */
+const WAIT_FOR = 10 * 60_000;
+
 /** What the page shows for the row as read now — `CancelRequest.view(rowScheduled)`. */
 export interface CancelRequestView {
   /** For `SubscriptionActions`' `cancelRequested`. */
@@ -23,7 +26,8 @@ export interface CancelRequestView {
 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. */
+   *  so the page follows the provider. Needs no overview data: pass it to the query.
+   *  False again after `timeoutMs` with no move of the row. */
   waiting: boolean;
   /**
    * The row as read now (the overview's `cancel_at_period_end`; `undefined` while it
@@ -54,10 +58,25 @@ export interface CancelRequest {
  *       onResume={() => resume.mutate(undefined, { onSuccess: view.noteAsked })}
  *       …
  *     />
+ *
+ * **Bounded,** as `useCheckoutProcessing` is (FLW-6): after `timeoutMs` (10 minutes)
+ * with no move of the row the request is dropped — the polling stops and the page shows
+ * the row as it is. Unbounded, a webhook that never landed kept kastlan re-reading the
+ * overview every 3 s for as long as the page was open, which also kept a Cloud Run
+ * instance awake, and the plan line said "Cancels on …" for a row that never moved.
  */
-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);
+export function useCancelRequest({ timeoutMs = WAIT_FOR }: { timeoutMs?: number } = {}): CancelRequest {
+  // What was asked, kept with the row's state it was asked against and when.
+  const [asked, setAsked] = useState<{ scheduled: boolean; at: number } | null>(null);
+  useEffect(() => {
+    if (asked === null) return;
+    // Only THIS ask: one that a later ask or the row has replaced is not dropped twice.
+    const timer = setTimeout(
+      () => setAsked((current) => (current === asked ? null : current)),
+      Math.max(0, asked.at + timeoutMs - Date.now()),
+    );
+    return () => clearTimeout(timer);
+  }, [asked, timeoutMs]);
   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: () => {} };
@@ -68,7 +87,10 @@ export function useCancelRequest(): CancelRequest {
     return {
       requested: open ? (row ? "resume" : "cancel") : null,
       cancelScheduled: open ? !row : row,
-      noteAsked: () => setAsked((a) => (a !== null && a.scheduled === row ? null : { scheduled: row })),
+      noteAsked: () => {
+        const at = Date.now();
+        setAsked((a) => (a !== null && a.scheduled === row ? null : { scheduled: row, at }));
+      },
     };
   };
   return { waiting: asked !== null, view };

package/src/billing/cancel-subscription.tsx

@@ -1,28 +1,34 @@
-import type { KeyboardEvent } from "react";
-
-import { useKitLabels, useKitLocale } from "../i18n/kit-labels";
+import { useKitLabels } 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 { useDayFormatter } from "../lib/day-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";
+import { dialogClose } from "./dialog-close";
+import type { WithDialogClose } from "./dialog-close";
 
-export interface CancelSubscriptionConfirmProps {
+/** {@link CancelSubscriptionConfirmProps} before one of its two close props is required. */
+interface CancelSubscriptionConfirmFields {
   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"`). */
+  /** The admin dismissed it — Back, Escape, the backdrop. Confirm leaves it open: close it
+   *  once `POST /billing/cancel` answers. 0.52: every other kit dialog's `onClose`
+   *  (CONTRIBUTING §4; refactor audit 2026-10-30, API-5). */
+  onClose?: () => void;
+  /** @deprecated 0.52 — `onClose`, as every other kit dialog; removed in 0.53. Called with
+   *  `false` when there is no `onClose`. */
+  onOpenChange?: (open: boolean) => void;
+  /** The overview's `current_period_end`: the day the subscription ends, in a sentence —
+   *  the `<UiKitProvider formatDate>` (the app's date preference) when it set one, else the
+   *  kit's `formatDate`, `"medium"`, in the provider's locale and `timeZone` (0.52). */
   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. */
+  /** The cancel is under way: Confirm's spinner, no second press, and neither Escape,
+   *  the backdrop nor Back closes it. */
   pending?: boolean;
   /** The date's locale. Default: the provider's. */
   locale?: string;
@@ -30,6 +36,11 @@ export interface CancelSubscriptionConfirmProps {
   labels?: LabelOverride<BillingLabels>;
 }
 
+/** What {@link CancelSubscriptionConfirm} takes: `onClose`, or alone the deprecated
+ *  `onOpenChange`, is required (0.52 code review: with neither it compiled, and nothing
+ *  could dismiss it). */
+export type CancelSubscriptionConfirmProps = WithDialogClose<CancelSubscriptionConfirmFields>;
+
 /**
  * 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
@@ -40,7 +51,7 @@ export interface CancelSubscriptionConfirmProps {
  *
  *     <CancelSubscriptionConfirm
  *       open={asking}
- *       onOpenChange={setAsking}
+ *       onClose={() => setAsking(false)}
  *       periodEnd={overview.current_period_end}
  *       pending={cancel.isPending}
  *       onConfirm={() => cancel.mutate()}
@@ -56,6 +67,7 @@ export interface CancelSubscriptionConfirmProps {
  */
 export function CancelSubscriptionConfirm({
   open,
+  onClose,
   onOpenChange,
   periodEnd,
   onConfirm,
@@ -65,20 +77,15 @@ export function CancelSubscriptionConfirm({
 }: CancelSubscriptionConfirmProps) {
   const labels = useBillingLabels(labelsProp);
   const common = useKitLabels("common", DEFAULT_COMMON_LABELS);
-  const locale = useKitLocale(localeProp);
+  const day = useDayFormatter(undefined, 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}
+      description={labels.cancelConfirmBody(day(periodEnd))}
+      onClose={dialogClose({ onClose, onOpenChange })}
+      busy={pending}
       data-cancel-subscription-confirm=""
       actions={(close) => (
         <>

package/src/billing/dialog-close.ts

@@ -0,0 +1,34 @@
+/**
+ * How the three billing confirms — `CancelSubscriptionConfirm`, `PlanSwitchConfirm`,
+ * `GrantWarningConfirm` — are closed in 0.52: `onClose`, as every other kit dialog
+ * (CONTRIBUTING §4; refactor audit 2026-10-30, API-5), and for one minor the deprecated
+ * `onOpenChange`, called with `false` when there is no `onClose`.
+ *
+ * 0.52 made `onOpenChange` optional for its deprecation and gave `onClose` beside it as
+ * optional too, so a confirm given NEITHER compiled — `<CancelSubscriptionConfirm open
+ * periodEnd={…} onConfirm={…} />` — and Back, Escape and the backdrop then called nothing:
+ * a dialog nobody could dismiss, where 0.51's compiler had required `onOpenChange` (0.52
+ * code review, cancel-subscription.tsx). And the fallback between the two was written
+ * three times, once per dialog.
+ *
+ * @internal Not part of the barrel; each dialog's props type is.
+ */
+
+/** The two close props as a dialog's own props interface declares them. */
+interface CloseProps {
+  onClose?: () => void;
+  onOpenChange?: (open: boolean) => void;
+}
+
+/**
+ * `P` with ONE of its two close props required — `onClose`, or alone the deprecated
+ * `onOpenChange`; both may be given, and `onClose` is then the one called. Built from
+ * `P`'s own members (`Pick`), so their docs and the deprecation stay the ones `P` writes.
+ */
+export type WithDialogClose<P extends CloseProps> = P &
+  (Required<Pick<P, "onClose">> | Required<Pick<P, "onOpenChange">>);
+
+/** The dialog's close: `onClose`, else `onOpenChange(false)`. */
+export function dialogClose({ onClose, onOpenChange }: CloseProps): () => void {
+  return () => (onClose ? onClose() : onOpenChange?.(false));
+}