@eifi1/ui-kit 0.31.1 → 0.32.1

package/src/billing/billing-banner.tsx

@@ -0,0 +1,205 @@
+import type { ComponentPropsWithoutRef, ReactNode } from "react";
+import { CreditCard, Hourglass, PencilOff } from "lucide-react";
+
+import type { LabelOverride } from "../i18n/kit-labels";
+import { AlertBanner } from "../components/alert-banner";
+import type { AlertSize, AlertTone } from "../components/alert-banner";
+import { Button, Spinner } from "../components/ui";
+import { useBillingLabels } from "./billing-labels";
+import type { BillingLabels } from "./billing-labels";
+
+/**
+ * The billing banners (docs/billing-harmonization.md §3.3, §7, §12.6, §12.21):
+ *
+ * - `trial-ending` — from 7 days before `trial_ends_at` (§3.3);
+ * - `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;
+ * - `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).
+ */
+export type BillingBannerKind =
+  | "trial-ending"
+  | "grant-ending"
+  | "payment-failed"
+  | "plan-ended"
+  | "guest"
+  | "processing";
+
+interface BillingBannerBaseProps extends Omit<ComponentPropsWithoutRef<"div">, "children" | "onClick"> {
+  /**
+   * Over the kind's tone: `trial-ending` and `grant-ending` are `info` until the last
+   * three days and `warning` in them; `payment-failed` is `danger` (money did not
+   * arrive — kastlan's past-due strip was red); `plan-ended` is `warning`, a state with
+   * everything still there rather than an error; `guest` and `processing` are `info`.
+   */
+  tone?: AlertTone;
+  /** `strip` (default): the band under the top bar, on every page. `box`: the same
+   *  message on the subscription page itself. */
+  variant?: "strip" | "box";
+  /** Default `sm` for a strip (the demo's banner), `md` for a box. */
+  size?: AlertSize;
+  /**
+   * Where the action goes — the subscription page, say. The app's action, as an `href`
+   * or as {@link onAction}; without either there is no button. Never a write-locked
+   * commit: billing itself always works (§3.3).
+   */
+  actionHref?: string;
+  /** What the action does — the app's portal call (`POST /billing/portal`, then off to
+   *  its `url`). The kit sends no request. */
+  onAction?: () => void;
+  /**
+   * Over the kind's action words: "Choose a plan" (trial, grant, plan ended), "Update
+   * payment method" (payment failed), "Check again" (processing). The guest banner has
+   * none of its own: an action there needs this.
+   */
+  actionLabel?: string;
+  /** The action is under way: the button's spinner, no second press. */
+  actionPending?: boolean;
+  /** An × that calls this; the app removes the banner and remembers that it did. */
+  onDismiss?: () => void;
+  dismissLabel?: string;
+  /** Prop > `<UiKitProvider labels={{ billing }}>` > English. */
+  labels?: LabelOverride<BillingLabels>;
+}
+
+export type BillingBannerProps = BillingBannerBaseProps &
+  (
+    | {
+        kind: "trial-ending" | "grant-ending";
+        /** Calendar days left — `billingDaysLeft(trial_ends_at)`. 0 is today. */
+        daysLeft: number;
+        item?: never;
+      }
+    | {
+        kind: "guest";
+        /** The item's own name ("Household 2026"), or nothing. NEVER the owner's status:
+         *  the banner says "for now" and nothing more (§12.6). */
+        item?: string;
+        daysLeft?: never;
+      }
+    | {
+        kind: "payment-failed" | "plan-ended" | "processing";
+        daysLeft?: never;
+        item?: never;
+      }
+  );
+
+/** The last days, in which an ending trial or grant turns from news into a warning. */
+const LAST_DAYS = 3;
+
+function defaultTone(kind: BillingBannerKind, daysLeft: number | undefined): AlertTone {
+  switch (kind) {
+    case "trial-ending":
+    case "grant-ending":
+      return (daysLeft ?? 0) > LAST_DAYS ? "info" : "warning";
+    case "payment-failed":
+      return "danger";
+    case "plan-ended":
+      return "warning";
+    default:
+      return "info";
+  }
+}
+
+/**
+ * One of the billing banners, as a kit `AlertBanner` strip (§7): the kind's sentence, its
+ * glyph and tone, and the app's action. Carries `data-billing-banner` with the kind.
+ *
+ * The app decides WHICH banner shows, from `GET /billing/overview` (and hides all of them
+ * while billing is off, §4); the kit only says it. A guest's banner takes no status at
+ * all — the type does not let one in — so the owner's payment state cannot leak into it
+ * by a wrong prop (§12.6).
+ *
+ * `processing` is a live region (`role="status"`): it appears when the person comes back
+ * from checkout and goes when the overview catches up (§12.21), and a screen reader
+ * should hear both. The others are page furniture, role-less as the strip is.
+ */
+export function BillingBanner(props: BillingBannerProps) {
+  const {
+    kind,
+    daysLeft,
+    item,
+    tone,
+    variant = "strip",
+    size,
+    actionHref,
+    onAction,
+    actionLabel,
+    actionPending,
+    onDismiss,
+    dismissLabel,
+    labels: labelsProp,
+    role,
+    ...rest
+  } = props;
+  const labels = useBillingLabels(labelsProp);
+  const days = Math.max(0, Math.floor(daysLeft ?? 0));
+
+  let text: string;
+  let icon: ReactNode;
+  let ownAction: string | undefined;
+  switch (kind) {
+    case "trial-ending":
+      text = labels.trialEnding(days);
+      icon = <Hourglass />;
+      ownAction = labels.choosePlan;
+      break;
+    case "grant-ending":
+      text = labels.grantEnding(days);
+      icon = <Hourglass />;
+      ownAction = labels.choosePlan;
+      break;
+    case "payment-failed":
+      text = labels.paymentFailed;
+      icon = <CreditCard />;
+      ownAction = labels.updatePayment;
+      break;
+    case "plan-ended":
+      text = labels.planEnded;
+      icon = <PencilOff />;
+      ownAction = labels.choosePlan;
+      break;
+    case "guest":
+      text = labels.guestReadOnly(item);
+      icon = <PencilOff />;
+      ownAction = undefined;
+      break;
+    case "processing":
+      text = labels.processing;
+      icon = <Spinner label={null} />;
+      ownAction = labels.checkAgain;
+      break;
+  }
+
+  const words = actionLabel ?? ownAction;
+  const action =
+    words === undefined || (actionHref === undefined && onAction === undefined) ? undefined : actionHref !== undefined ? (
+      <Button href={actionHref} variant="secondary" size="sm">
+        {words}
+      </Button>
+    ) : (
+      <Button type="button" variant="secondary" size="sm" onClick={onAction} pending={actionPending}>
+        {words}
+      </Button>
+    );
+
+  return (
+    <AlertBanner
+      {...rest}
+      role={role ?? (kind === "processing" ? "status" : undefined)}
+      variant={variant}
+      size={size ?? (variant === "strip" ? "sm" : "md")}
+      tone={tone ?? defaultTone(kind, days)}
+      icon={icon}
+      action={action}
+      onDismiss={onDismiss}
+      dismissLabel={dismissLabel}
+      data-billing-banner={kind}
+    >
+      {text}
+    </AlertBanner>
+  );
+}

package/src/billing/billing-labels.ts

@@ -0,0 +1,240 @@
+import { useKitLabels } from "../i18n/kit-labels";
+import type { LabelOverride } from "../i18n/kit-labels";
+
+/**
+ * The subscription's status vocabulary (docs/billing-harmonization.md §3.2) — server-kit's
+ * `SubscriptionStatus`, value for value:
+ *
+ * - `trialing` — the 30-day trial without a card (§2.7), or a pure guest's row whose trial
+ *   has not started (§12.9, `trial_ends_at` empty);
+ * - `active` — paid;
+ * - `past_due` — a payment failed; in good standing during the provider's retries (§3.3);
+ * - `canceled` — the payer cancelled; the American spelling is the wire's, the word shown
+ *   is "Cancelled";
+ * - `expired` — a trial, a grant or a failed subscription ran out: read-only (§2.3);
+ * - `comped` — free by the operator's grant or as a beta user (§3.2, `comped_until`).
+ */
+export type SubscriptionStatus = "trialing" | "active" | "past_due" | "canceled" | "expired" | "comped";
+
+/** Every status, in the order a lifecycle reads: trial, paid, trouble, ended, granted. */
+export const SUBSCRIPTION_STATUSES: readonly SubscriptionStatus[] = Object.freeze([
+  "trialing",
+  "active",
+  "past_due",
+  "canceled",
+  "expired",
+  "comped",
+]);
+
+/**
+ * The words of the subscription parts — the `billing` namespace of `<UiKitProvider labels>`
+ * (docs/billing-harmonization.md §7, §10; ui-kit 0.32.0).
+ *
+ * WORDING (§12.24): the English group is "Subscription", never "Plan" — keksdose's "plan"
+ * is the month's budget plan ("One plan per month"), and two meanings of one word on one
+ * settings page is the clash the review found. "Plan" stays the word for WHAT is bought
+ * (Free, Pro), "subscription" for the standing arrangement. German says "Tarif" for the
+ * plan and "Abonnement" for the subscription (§10).
+ *
+ * Prices are GROSS (§12.17): Swiss consumer law (PBV) wants a consumer price with the
+ * MWST in it, so the cards say so (`vatIncluded`).
+ */
+export interface BillingLabels {
+  /** The settings group or admin section the parts live on (§7, §12.24): "Subscription". */
+  group: string;
+
+  /* ── PlanPicker / PlanCard (§7) ── */
+  /** The picker's name when it has no visible `legend`: "Plans". */
+  plans: string;
+  /** The name of the billing-period switch: "Billing period". */
+  interval: string;
+  /** The switch's two options — yearly first (§12.17). */
+  yearly: string;
+  monthly: string;
+  /** The name of the currency switch: "Currency". */
+  currency: string;
+  /** After a price: "per year", "per month". */
+  perYear: string;
+  perMonth: string;
+  /** Under a price (§12.17): "VAT included". German: "inkl. MWST". */
+  vatIncluded: string;
+  /** A plan with no price, or a price of 0: "Free". */
+  free: string;
+  /** A plan with prices, but none for this currency and period. */
+  notOffered: string;
+  /** A limit of `null` (§3.1): "Unlimited". */
+  unlimited: string;
+  /** The accessible names of a card's two lists. */
+  limits: string;
+  features: string;
+  /** The chip on the payer's current plan. */
+  current: string;
+  /** The picker's button for `plan` (the plan's display name) with no current plan —
+   *  during a trial, or after a plan ended: "Choose Pro". */
+  choose: (plan: string) => string;
+  /** …for a plan after the current one in the catalogue's order: "Upgrade to Pro". */
+  upgrade: (plan: string) => string;
+  /** …for a plan before it: "Switch to Free". */
+  downgrade: (plan: string) => string;
+  /** Why the button is off while the current plan is the one picked. */
+  isCurrent: string;
+  /** Why it is off while nothing is picked. */
+  pickFirst: string;
+
+  /* ── SubscriptionStatusChip (§6) ── */
+  /** One word per status. */
+  status: Record<SubscriptionStatus, string>;
+
+  /* ── BillingBanner (§3.3, §12.6, §12.21) ── */
+  /** A trial ends in `days` calendar days — 0 is today, 1 tomorrow. */
+  trialEnding: (days: number) => string;
+  /** A free grant (`comped_until`: a beta user's 12 months, an operator's grant) ends in
+   *  `days` calendar days. */
+  grantEnding: (days: number) => string;
+  /** The first failed payment (`past_due`), while the provider retries. */
+  paymentFailed: string;
+  /** Out of good standing: read-only, never locked (§2.3). */
+  planEnded: string;
+  /**
+   * A guest in someone else's item that is read-only for billing (§12.6). It never says
+   * WHY beyond "for now": the owner's payment status is the owner's personal data.
+   * `item` is the item's own name ("Household 2026"), shown in quotes — or `undefined`.
+   */
+  guestReadOnly: (item?: string) => string;
+  /** Back from checkout before the provider's webhook landed (§12.21). */
+  processing: string;
+  /** The action of the trial, grant and plan-ended banners, and of `PlanLimitNotice`'s
+   *  `upgrade` mode: "Choose a plan". */
+  choosePlan: string;
+  /** The payment-failed banner's action, to the provider's portal: "Update payment method". */
+  updatePayment: string;
+  /** The processing banner's action, when the app gives one: "Check again". */
+  checkAgain: string;
+
+  /* ── The read-only lock (§3.3, §12.6) ── */
+  /** The `WriteLockProvider` reason for the payer (§3.3, verbatim). A guest's reason is
+   *  {@link guestReadOnly}. */
+  lockReason: string;
+
+  /* ── PlanLimitNotice (§3.4) ── */
+  /** The notice's first line: "Plan limit reached". */
+  limitReached: string;
+  /** Mode `upgrade`: what the action does. */
+  limitUpgrade: string;
+  /** Mode `contact` (the operator grants plans by hand, keksdose's today). */
+  limitContact: string;
+  /** Mode `contact`'s action, a mail to support: "Ask for more". */
+  askForMore: string;
+  /** The meter's value: "3 of 3". Both figures are formatted already. */
+  usage: (used: string, limit: string) => string;
+  /** The subject of the `contact` mail; `dimension` is the app's name for it ("Budgets"). */
+  contactSubject: (dimension: string) => string;
+
+  /* ── The provider's portal (§7, §12.26) ── */
+  /** The portal: payment method and invoices (§2.8, the provider hosts both). */
+  manage: string;
+  /**
+   * The visible cancel link on the app's subscription page (§12.26). German: §312k BGB
+   * wants the button that leads to the cancellation labelled "Verträge hier kündigen" or
+   * as unambiguously — a translator should use exactly that.
+   */
+  cancel: string;
+
+  /* ── Offline (§12.5) ── */
+  /** Changes refused as `billing_read_only` inside a sync reply, kept queued and sent
+   *  after payment: "3 changes waiting for a plan". */
+  waitingChanges: (count: number) => string;
+  /** The sign-out guard's way out for someone who will not pay. */
+  discardWaiting: string;
+
+  /* ── Refusals with no part of their own (0.32.1, kastlan's 0.32 report) ── */
+  /**
+   * `billing_not_configured`: billing is on but the provider's settings are missing — the
+   * operator's mistake, so the words ask the payer to wait, not to act. For the toast or
+   * alert after "Choose a plan" or "Payment and invoices" (`isBillingError(err,
+   * "billing_not_configured")`). `billing_read_only` and `plan_limit` need none: the
+   * write lock, the banner and `PlanLimitNotice` say them.
+   */
+  notConfigured: string;
+  /** `billing_disabled`: billing is switched off on this server (§2.9), for a page or a
+   *  link that reached it anyway. */
+  disabled: string;
+}
+
+/** "today", "tomorrow", "in 5 days". */
+function inDays(days: number): string {
+  if (days <= 0) return "today";
+  if (days === 1) return "tomorrow";
+  return `in ${days} days`;
+}
+
+export const DEFAULT_BILLING_LABELS: BillingLabels = {
+  group: "Subscription",
+
+  plans: "Plans",
+  interval: "Billing period",
+  yearly: "Yearly",
+  monthly: "Monthly",
+  currency: "Currency",
+  perYear: "per year",
+  perMonth: "per month",
+  vatIncluded: "VAT included",
+  free: "Free",
+  notOffered: "Not offered for this billing period",
+  unlimited: "Unlimited",
+  limits: "Limits",
+  features: "Included",
+  current: "Current plan",
+  choose: (plan) => `Choose ${plan}`,
+  upgrade: (plan) => `Upgrade to ${plan}`,
+  downgrade: (plan) => `Switch to ${plan}`,
+  isCurrent: "This is your current plan.",
+  pickFirst: "Pick a plan first.",
+
+  status: {
+    trialing: "Trial",
+    active: "Active",
+    past_due: "Payment overdue",
+    canceled: "Cancelled",
+    expired: "Expired",
+    comped: "Complimentary",
+  },
+
+  trialEnding: (days) =>
+    `Your trial ends ${inDays(days)}. After that you can still view everything, but changes need a plan.`,
+  grantEnding: (days) =>
+    `Your free access ends ${inDays(days)}. After that you can still view everything, but changes need a plan.`,
+  paymentFailed: "Your last payment didn’t go through. Update your payment method to keep your plan.",
+  planEnded: "Your plan has ended. You can still view and export everything; choose a plan to make changes again.",
+  guestReadOnly: (item) =>
+    item ? `“${item}” is read-only for now; its owner can lift that.` : "This is read-only for now; its owner can lift that.",
+  processing: "Your payment is being processed. Your plan starts as soon as it’s confirmed; this page updates by itself.",
+  choosePlan: "Choose a plan",
+  updatePayment: "Update payment method",
+  checkAgain: "Check again",
+
+  lockReason: "Your plan has ended. Choose a plan to make changes again.",
+
+  limitReached: "Plan limit reached",
+  limitUpgrade: "To add more, choose a plan with a higher limit.",
+  limitContact: "To add more, ask us for a higher limit.",
+  askForMore: "Ask for more",
+  usage: (used, limit) => `${used} of ${limit}`,
+  contactSubject: (dimension) => `Plan limit: ${dimension}`,
+
+  manage: "Payment and invoices",
+  cancel: "Cancel subscription",
+
+  waitingChanges: (count) =>
+    count === 1 ? "1 change waiting for a plan" : `${count} changes waiting for a plan`,
+  discardWaiting: "Discard waiting changes",
+
+  notConfigured: "Payments aren't set up yet. Please try again later.",
+  disabled: "Subscriptions aren't available here.",
+};
+
+/** The `billing` namespace, resolved: English, then the provider, then `labels` — which
+ *  may be partial at every depth (`{ status: { comped: "Beta" } }`). */
+export function useBillingLabels(labels?: LabelOverride<BillingLabels>): BillingLabels {
+  return useKitLabels("billing", DEFAULT_BILLING_LABELS, labels as Partial<BillingLabels> | undefined);
+}

package/src/billing/billing-lock.ts

@@ -0,0 +1,75 @@
+import type { ReactNode } from "react";
+
+import type { LabelOverride } from "../i18n/kit-labels";
+import { useBillingLabels } from "./billing-labels";
+import type { BillingLabels } from "./billing-labels";
+
+/** One reason an app may lock writing: whether it locks now, and its one sentence. */
+export interface WriteLockSource {
+  locked: boolean;
+  /** The sentence a locked commit shows ("Not possible in the demo."). */
+  reason?: ReactNode;
+}
+
+/** What {@link combineWriteLocks} answers: the props of one `WriteLockProvider`. */
+export interface CombinedWriteLock {
+  locked: boolean;
+  /** The first locked source's reason; `undefined` while nothing locks. */
+  reason: ReactNode | undefined;
+}
+
+/**
+ * Several reasons to lock writing, as ONE `WriteLockProvider` (docs/billing-harmonization.md
+ * §12.6): the demo's read-only data and billing's read-only lapse, in keksdose's case on
+ * the same budget page.
+ *
+ *     const demo = useDemoLabels();
+ *     const billingReason = useBillingLockReason({ guest: !isOwner, item: budget.name });
+ *     <WriteLockProvider {...combineWriteLocks([
+ *       { locked: demoReadOnly, reason: demo.writeLocked },
+ *       { locked: budget.locked === "billing", reason: billingReason },
+ *     ])}>
+ *
+ * WHY NOT TWO NESTED PROVIDERS: the nearest provider wins (write-lock.tsx), and an inner
+ * `locked={false}` REOPENS an outer lock on purpose — a viewer's own notes on a shared
+ * curve. So `<Demo locked><Billing locked={false}>` would unlock the demo's data, and an
+ * app would have to mount the inner provider only while it locks. One provider fed by
+ * this function has no such order to get wrong.
+ *
+ * Locked when any source is; the reason is the FIRST locked source's, so list them in the
+ * order the server refuses them (§12.3): the demo's 403 before billing's 402. One sentence,
+ * not two joined: a tooltip answers "why can't I?" once, and in practice one source locks
+ * at a time — demo users have no subscription row and are never gated (§12.7). `null`,
+ * `undefined` and `false` entries are skipped, for `cond && { … }`.
+ */
+export function combineWriteLocks(
+  sources: ReadonlyArray<WriteLockSource | null | undefined | false>,
+): CombinedWriteLock {
+  for (const source of sources) {
+    if (source && source.locked) return { locked: true, reason: source.reason };
+  }
+  return { locked: false, reason: undefined };
+}
+
+export interface BillingLockReasonOptions {
+  /**
+   * The reader is a GUEST in someone else's item (§12.6): the reason never says why
+   * beyond "for now", because the owner's payment status is the owner's personal data —
+   * "This budget is read-only for now; its owner can lift that." Default false: the
+   * reader is the payer, "Your plan has ended. Choose a plan to make changes again."
+   */
+  guest?: boolean;
+  /** A guest's item, by its own name ("Household 2026"). Ignored for the payer. */
+  item?: string;
+  labels?: LabelOverride<BillingLabels>;
+}
+
+/**
+ * The billing lock's sentence for a `WriteLockProvider` (§3.3), in the `billing` words of
+ * the nearest provider: the payer's `lockReason`, or a guest's `guestReadOnly`. Feed it
+ * to {@link combineWriteLocks} beside the demo's.
+ */
+export function useBillingLockReason(options: BillingLockReasonOptions = {}): string {
+  const labels = useBillingLabels(options.labels);
+  return options.guest ? labels.guestReadOnly(options.item) : labels.lockReason;
+}

package/src/billing/billing-standing.ts

@@ -0,0 +1,72 @@
+import { toDate } from "../lib/format";
+import type { DateInput } from "../lib/format";
+import type { SubscriptionStatus } from "./billing-labels";
+
+/**
+ * What a device knows of the payer's standing — the fields of `GET /billing/overview`
+ * (docs/billing-harmonization.md §4) that decide the read-only lock, under their wire
+ * names. Pass the overview as it came; the other fields are ignored.
+ */
+export interface BillingStanding {
+  status: SubscriptionStatus;
+  /** The server's answer at the time of the read (§3.3). */
+  in_good_standing: boolean;
+  /** When a trial ends (§3.2). Empty for a pure guest whose trial has not started (§12.9). */
+  trial_ends_at?: DateInput;
+  /** 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;
+}
+
+/**
+ * The moment this payer's data becomes read-only by itself, known IN ADVANCE — or `null`
+ * when no date says so (docs/billing-harmonization.md §12.5).
+ *
+ * A device writes locally first and sends later (keksdose's outbox, an encrypted budget
+ * always), so a lock that only arrives with the server's 402 comes after the UI already
+ * said "saved" — keksdose's phantom save (dev#496). The two dates that end good standing
+ * on a schedule are in the overview, so the device locks itself on time, offline too:
+ * a trial at `trial_ends_at`, a grant at `comped_until`. Only `past_due` → `expired`
+ * depends on the provider's retries and waits for the next sync.
+ */
+export function billingLockAt(standing: BillingStanding): Date | null {
+  if (standing.status === "trialing") return toDate(standing.trial_ends_at ?? null);
+  if (standing.status === "comped") return toDate(standing.comped_until ?? null);
+  return null;
+}
+
+/**
+ * Whether the payer's data is read-only at `now` (default: the present moment): the
+ * server already said so (`in_good_standing: false`), or a date from
+ * {@link billingLockAt} has passed since the overview was read. Mirror it into the app's
+ * offline write gate and its `WriteLockProvider` (§3.3, §12.5).
+ *
+ * A GUEST's device cannot do this for the owner: the owner's dates are the owner's
+ * personal data (§12.6). An item shared with a guest carries `locked: "billing" | null`,
+ * which the guest's device mirrors as it comes.
+ */
+export function isBillingReadOnly(standing: BillingStanding, now: number | Date = Date.now()): boolean {
+  if (!standing.in_good_standing) return true;
+  const at = billingLockAt(standing);
+  const instant = typeof now === "number" ? now : now.getTime();
+  return at !== null && at.getTime() <= instant;
+}
+
+const DAY = 86_400_000;
+
+/**
+ * Whole calendar days from `now` to `endsAt`, in the device's time zone — 0 on the day
+ * itself (and after it), 1 the day before — or `null` for no readable date. The count a
+ * trial or grant banner says ("ends tomorrow", "ends in 5 days"), from the day a reader
+ * lives in rather than from 24-hour blocks: a trial ending at 01:00 tomorrow ends
+ * "tomorrow", not "today".
+ */
+export function billingDaysLeft(endsAt: DateInput, now: number | Date = Date.now()): number | null {
+  const end = toDate(endsAt);
+  if (!end) return null;
+  const from = typeof now === "number" ? new Date(now) : now;
+  const endDay = new Date(end.getFullYear(), end.getMonth(), end.getDate()).getTime();
+  const fromDay = new Date(from.getFullYear(), from.getMonth(), from.getDate()).getTime();
+  // `round`, not `floor`: a day across a DST change is 23 or 25 hours long.
+  return Math.max(0, Math.round((endDay - fromDay) / DAY));
+}