@eifi1/ui-kit 0.41.0 → 0.43.0

package/dist/billing/plan-switch.d.ts

@@ -51,6 +51,15 @@ export interface PlanSwitchConfirmProps {
     onConfirm: () => void;
     /** The figures' and the date's locale. Default: the provider's. */
     locale?: string;
+    /**
+     * 0.42 (§16.2 decision 5, §16.8 B): the payer's free grant runs without an end —
+     * `isPermanentGrant(overview)`. The switch changes the PAID plan, not the applied one
+     * (§12.11), so the dialog says so above its figures (`grantWarningTitle`,
+     * `grantWarningBody`) before the payer agrees. Confirm stays Confirm: the warning is
+     * this dialog's own, and `PlanPicker` — told `switching` — shows none of its own on
+     * the way here, so the payer reads it once.
+     */
+    permanentGrant?: boolean;
     /** Prop > `<UiKitProvider labels={{ billing }}>` > English. */
     labels?: LabelOverride<BillingLabels>;
 }
@@ -76,4 +85,4 @@ export interface PlanSwitchConfirmProps {
  * change plan, as they may pay. A demo lock still holds it, as the server's demo guard
  * does. The kit sends no request.
  */
-export declare function PlanSwitchConfirm({ open, onOpenChange, from, to, preview, pending, planName, dimensionLabels, formatLimit, onConfirm, locale: localeProp, labels: labelsProp, }: PlanSwitchConfirmProps): import("react").JSX.Element;
+export declare function PlanSwitchConfirm({ open, onOpenChange, from, to, preview, pending, planName, dimensionLabels, formatLimit, onConfirm, locale: localeProp, permanentGrant, labels: labelsProp, }: PlanSwitchConfirmProps): import("react").JSX.Element;

package/dist/billing/plan-switch.js

@@ -4,6 +4,7 @@ import { useKitLabels, useKitLocale } from "../i18n/kit-labels.js";
 import { DEFAULT_COMMON_LABELS } from "../i18n/shared-labels.js";
 import { pluralForm } from "../i18n/plurals.js";
 import { formatDate, formatMoney, formatNumber } from "../lib/format.js";
+import { AlertBanner } from "../components/alert-banner.js";
 import { Button } from "../components/button.js";
 import { DialogFrame } from "../components/dialog-frame.js";
 import { Spinner } from "../components/spinner.js";
@@ -23,6 +24,7 @@ function PlanSwitchConfirm({
   formatLimit,
   onConfirm,
   locale: localeProp,
+  permanentGrant = false,
   labels: labelsProp
 }) {
   const labels = useBillingLabels(labelsProp);
@@ -44,7 +46,7 @@ function PlanSwitchConfirm({
   });
   const credit = preview !== void 0 && preview.now_minor < 0;
   const lines = preview ? overLimit(preview) : [];
-  return /* @__PURE__ */ jsx(
+  return /* @__PURE__ */ jsxs(
     DialogFrame,
     {
       open,
@@ -70,20 +72,27 @@ function PlanSwitchConfirm({
           }
         )
       ] }),
-      children: preview === void 0 ? /* @__PURE__ */ jsx("div", { className: "flex justify-center py-4", children: /* @__PURE__ */ jsx(Spinner, { showLabel: true }) }) : /* @__PURE__ */ jsxs(Fragment, { children: [
-        /* @__PURE__ */ jsxs("dl", { className: "grid grid-cols-[minmax(0,1fr)_auto] gap-x-4 gap-y-1 text-sm", "data-plan-switch-preview": true, children: [
-          /* @__PURE__ */ jsx("dt", { className: "text-secondary", children: credit ? labels.switchCredited : labels.switchChargedNow }),
-          /* @__PURE__ */ jsx("dd", { className: "text-right font-medium tabular-nums", "data-now": credit ? "credit" : "charge", children: money(Math.abs(preview.now_minor), preview.currency) }),
-          preview.next_billed_at && preview.next_minor != null && /* @__PURE__ */ jsxs(Fragment, { children: [
-            /* @__PURE__ */ jsx("dt", { className: "text-secondary", children: labels.switchNextCharge(formatDate(preview.next_billed_at, "medium", { locale })) }),
-            /* @__PURE__ */ jsx("dd", { className: "text-right tabular-nums", children: money(preview.next_minor, preview.currency) })
-          ] })
+      children: [
+        permanentGrant && /* @__PURE__ */ jsxs(AlertBanner, { tone: "warning", size: "sm", "data-grant-warning": "", children: [
+          /* @__PURE__ */ jsx("strong", { className: "block font-medium", children: labels.grantWarningTitle }),
+          " ",
+          labels.grantWarningBody
         ] }),
-        lines.length > 0 && /* @__PURE__ */ jsxs("div", { className: "space-y-1 text-sm", "data-plan-switch-over-limit": true, children: [
-          /* @__PURE__ */ jsx("p", { children: planChange.overLimit }),
-          /* @__PURE__ */ jsx("ul", { className: "list-disc space-y-0.5 ps-5 text-secondary", children: lines.map((line) => /* @__PURE__ */ jsx("li", { children: line }, line)) })
+        preview === void 0 ? /* @__PURE__ */ jsx("div", { className: "flex justify-center py-4", children: /* @__PURE__ */ jsx(Spinner, { showLabel: true }) }) : /* @__PURE__ */ jsxs(Fragment, { children: [
+          /* @__PURE__ */ jsxs("dl", { className: "grid grid-cols-[minmax(0,1fr)_auto] gap-x-4 gap-y-1 text-sm", "data-plan-switch-preview": true, children: [
+            /* @__PURE__ */ jsx("dt", { className: "text-secondary", children: credit ? labels.switchCredited : labels.switchChargedNow }),
+            /* @__PURE__ */ jsx("dd", { className: "text-right font-medium tabular-nums", "data-now": credit ? "credit" : "charge", children: money(Math.abs(preview.now_minor), preview.currency) }),
+            preview.next_billed_at && preview.next_minor != null && /* @__PURE__ */ jsxs(Fragment, { children: [
+              /* @__PURE__ */ jsx("dt", { className: "text-secondary", children: labels.switchNextCharge(formatDate(preview.next_billed_at, "medium", { locale })) }),
+              /* @__PURE__ */ jsx("dd", { className: "text-right tabular-nums", children: money(preview.next_minor, preview.currency) })
+            ] })
+          ] }),
+          lines.length > 0 && /* @__PURE__ */ jsxs("div", { className: "space-y-1 text-sm", "data-plan-switch-over-limit": true, children: [
+            /* @__PURE__ */ jsx("p", { children: planChange.overLimit }),
+            /* @__PURE__ */ jsx("ul", { className: "list-disc space-y-0.5 ps-5 text-secondary", children: lines.map((line) => /* @__PURE__ */ jsx("li", { children: line }, line)) })
+          ] })
         ] })
-      ] })
+      ]
     }
   );
 }

package/dist/billing/plan-switch.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/billing/plan-switch.tsx"],"sourcesContent":["import type { KeyboardEvent } from \"react\";\n\nimport { useKitLabels, useKitLocale } from \"../i18n/kit-labels\";\nimport type { LabelOverride } from \"../i18n/kit-labels\";\nimport { DEFAULT_COMMON_LABELS } from \"../i18n/shared-labels\";\nimport { pluralForm } from \"../i18n/plurals\";\nimport type { PluralForms } from \"../i18n/plurals\";\nimport { formatDate, formatMoney, formatNumber } from \"../lib/format\";\nimport { Button } from \"../components/button\";\nimport { DialogFrame } from \"../components/dialog-frame\";\nimport { Spinner } from \"../components/spinner\";\nimport { COMMIT_EXCEPT_BILLING } from \"../components/write-lock\";\nimport { DEFAULT_PLAN_CHANGE_LABELS } from \"../admin/plan-change-labels\";\nimport { useBillingLabels } from \"./billing-labels\";\nimport type { BillingLabels } from \"./billing-labels\";\nimport type { PlanSwitchPreview } from \"./billing-overview\";\nimport { minorToMajor } from \"./plan-price\";\nimport type { BillingInterval } from \"./plan-price\";\n\n/**\n * The payer's plan switch (docs/billing-harmonization.md §15.2.10, ui-kit 0.39): built\n * once in the kits and used by all three apps, instead of Paddle's portal. While a\n * provider subscription runs, the app sends a `PlanPicker` pick to\n * `POST /billing/plan/preview` and opens this dialog with the answer; Confirm is the\n * app's `POST /billing/plan`. Otherwise the pick goes to the checkout, as before.\n *\n * The switch is immediate and prorated: an upgrade charges the difference now, a\n * downgrade credits the unused part to the customer's balance, which Paddle takes off\n * the next charges. So the payer agrees to a figure — Paddle's preview — and sees the\n * dimensions over the new plan's limit before agreeing (§3.4: a limit gates creation\n * only, so the switch is allowed).\n */\n\n/** One side of a switch: a plan code and its billing period. */\nexport interface PlanSwitchSide {\n  plan: string;\n  interval: BillingInterval;\n}\n\nexport interface PlanSwitchConfirmProps {\n  open: boolean;\n  /** `false` when the payer dismisses it — Cancel, Escape, the backdrop. Confirm leaves\n   *  it open: close it once the switch answers. */\n  onOpenChange: (open: boolean) => void;\n  /** What the payer pays now: the overview's `paid`. */\n  from: PlanSwitchSide;\n  /** The pick. */\n  to: PlanSwitchSide;\n  /** `POST /billing/plan/preview`'s answer. Undefined while it loads: a spinner, and\n   *  Confirm is held. */\n  preview?: PlanSwitchPreview;\n  /** `POST /billing/plan` is under way: Confirm's spinner, no second press, and Escape\n   *  doesn't close. */\n  pending?: boolean;\n  /** The plan's display name, the app's (§3.1). Default: the code. */\n  planName?: (code: string) => string;\n  /**\n   * The app's word per dimension, for the over-limit lines. A heading's word (\"Budgets\")\n   * reads \"Budgets: 7 of 5\" (`billing.limitUsageLine`); its plural forms\n   * (`{ one: \"budget\", other: \"budgets\" }`) read \"7 of 5 budgets\" (`planChange.usageOf`,\n   * the form the limit takes). A dimension without one is named by its key.\n   */\n  dimensionLabels?: Readonly<Record<string, string | PluralForms>>;\n  /** How a usage or limit figure is written. Default: a number in the locale. */\n  formatLimit?: (dimension: string, value: number) => string;\n  /** Confirm: the app's `POST /billing/plan` with `{plan, interval}` of `to`. */\n  onConfirm: () => void;\n  /** The figures' and the date's locale. Default: the provider's. */\n  locale?: string;\n  /** Prop > `<UiKitProvider labels={{ billing }}>` > English. */\n  labels?: LabelOverride<BillingLabels>;\n}\n\n/**\n * The confirm for a plan switch (§15.2.10): from → to, each with its billing period;\n * Paddle's preview — \"Charged now\" (an upgrade) or \"Credited towards your next charges\"\n * (a downgrade), and the next charge with its date — in the subscription's currency;\n * the dimensions over the new plan's limit; and Confirm.\n *\n *     const preview = useMutation({ mutationFn: api.previewPlanSwitch });\n *     <PlanSwitchConfirm\n *       open={pick !== null}\n *       onOpenChange={(open) => !open && setPick(null)}\n *       from={overview.paid}\n *       to={pick}\n *       preview={preview.data}\n *       pending={switching.isPending}\n *       planName={planName}\n *       onConfirm={() => switching.mutate(pick)}\n *     />\n *\n * It takes no billing lock (`COMMIT_EXCEPT_BILLING` built in): a read-only payer may\n * change plan, as they may pay. A demo lock still holds it, as the server's demo guard\n * does. The kit sends no request.\n */\nexport function PlanSwitchConfirm({\n  open,\n  onOpenChange,\n  from,\n  to,\n  preview,\n  pending = false,\n  planName = (code) => code,\n  dimensionLabels,\n  formatLimit,\n  onConfirm,\n  locale: localeProp,\n  labels: labelsProp,\n}: PlanSwitchConfirmProps) {\n  const labels = useBillingLabels(labelsProp);\n  const planChange = useKitLabels(\"planChange\", DEFAULT_PLAN_CHANGE_LABELS);\n  const common = useKitLabels(\"common\", DEFAULT_COMMON_LABELS);\n  const locale = useKitLocale(localeProp);\n\n  const period = (interval: BillingInterval) => (interval === \"year\" ? labels.yearly : labels.monthly);\n  const side = (s: PlanSwitchSide) => `${planName(s.plan.toLowerCase())} (${period(s.interval)})`;\n  const money = (minor: number, currency: string) =>\n    formatMoney(minorToMajor(minor, currency), currency, { locale });\n  const figure = (dimension: string, value: number) =>\n    formatLimit ? formatLimit(dimension, value) : formatNumber(value, { locale });\n\n  /** One line per dimension over the new limit, in the word's own sentence. */\n  const overLimit = (p: PlanSwitchPreview): string[] =>\n    (p.over_limit ?? []).flatMap((dimension) => {\n      const limit = p.limits?.[dimension];\n      const used = p.usage?.[dimension];\n      if (limit === null || limit === undefined || used === undefined) return [];\n      const word = dimensionLabels?.[dimension] ?? dimension;\n      return [\n        typeof word === \"string\"\n          ? labels.limitUsageLine(word, figure(dimension, used), figure(dimension, limit))\n          : planChange.usageOf(figure(dimension, used), figure(dimension, limit), pluralForm(limit, word, locale)),\n      ];\n    });\n\n  const credit = preview !== undefined && preview.now_minor < 0;\n  const lines = preview ? overLimit(preview) : [];\n\n  return (\n    <DialogFrame\n      open={open}\n      title={labels.switchTitle}\n      description={labels.switchFromTo(side(from), side(to))}\n      onClose={() => onOpenChange(false)}\n      onKeyDown={(e: KeyboardEvent<HTMLDivElement>) => {\n        if (pending && e.key === \"Escape\") e.preventDefault();\n      }}\n      aria-busy={preview === undefined || pending || undefined}\n      actions={(close) => (\n        <>\n          <Button variant=\"secondary\" onClick={close} disabled={pending}>\n            {common.cancel}\n          </Button>\n          <Button\n            commit={COMMIT_EXCEPT_BILLING}\n            pending={pending}\n            disabled={preview === undefined}\n            onClick={() => {\n              if (preview !== undefined && !pending) onConfirm();\n            }}\n          >\n            {labels.switchConfirm}\n          </Button>\n        </>\n      )}\n    >\n      {preview === undefined ? (\n        <div className=\"flex justify-center py-4\">\n          <Spinner showLabel />\n        </div>\n      ) : (\n        <>\n          <dl className=\"grid grid-cols-[minmax(0,1fr)_auto] gap-x-4 gap-y-1 text-sm\" data-plan-switch-preview>\n            <dt className=\"text-secondary\">{credit ? labels.switchCredited : labels.switchChargedNow}</dt>\n            <dd className=\"text-right font-medium tabular-nums\" data-now={credit ? \"credit\" : \"charge\"}>\n              {money(Math.abs(preview.now_minor), preview.currency)}\n            </dd>\n            {preview.next_billed_at && preview.next_minor != null && (\n              <>\n                <dt className=\"text-secondary\">\n                  {labels.switchNextCharge(formatDate(preview.next_billed_at, \"medium\", { locale }))}\n                </dt>\n                <dd className=\"text-right tabular-nums\">{money(preview.next_minor, preview.currency)}</dd>\n              </>\n            )}\n          </dl>\n          {lines.length > 0 && (\n            <div className=\"space-y-1 text-sm\" data-plan-switch-over-limit>\n              <p>{planChange.overLimit}</p>\n              <ul className=\"list-disc space-y-0.5 ps-5 text-secondary\">\n                {lines.map((line) => (\n                  <li key={line}>{line}</li>\n                ))}\n              </ul>\n            </div>\n          )}\n        </>\n      )}\n    </DialogFrame>\n  );\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/billing/plan-switch.tsx"],"sourcesContent":["import type { KeyboardEvent } from \"react\";\n\nimport { useKitLabels, useKitLocale } from \"../i18n/kit-labels\";\nimport type { LabelOverride } from \"../i18n/kit-labels\";\nimport { DEFAULT_COMMON_LABELS } from \"../i18n/shared-labels\";\nimport { pluralForm } from \"../i18n/plurals\";\nimport type { PluralForms } from \"../i18n/plurals\";\nimport { formatDate, formatMoney, formatNumber } from \"../lib/format\";\nimport { AlertBanner } from \"../components/alert-banner\";\nimport { Button } from \"../components/button\";\nimport { DialogFrame } from \"../components/dialog-frame\";\nimport { Spinner } from \"../components/spinner\";\nimport { COMMIT_EXCEPT_BILLING } from \"../components/write-lock\";\nimport { DEFAULT_PLAN_CHANGE_LABELS } from \"../admin/plan-change-labels\";\nimport { useBillingLabels } from \"./billing-labels\";\nimport type { BillingLabels } from \"./billing-labels\";\nimport type { PlanSwitchPreview } from \"./billing-overview\";\nimport { minorToMajor } from \"./plan-price\";\nimport type { BillingInterval } from \"./plan-price\";\n\n/**\n * The payer's plan switch (docs/billing-harmonization.md §15.2.10, ui-kit 0.39): built\n * once in the kits and used by all three apps, instead of Paddle's portal. While a\n * provider subscription runs, the app sends a `PlanPicker` pick to\n * `POST /billing/plan/preview` and opens this dialog with the answer; Confirm is the\n * app's `POST /billing/plan`. Otherwise the pick goes to the checkout, as before.\n *\n * The switch is immediate and prorated: an upgrade charges the difference now, a\n * downgrade credits the unused part to the customer's balance, which Paddle takes off\n * the next charges. So the payer agrees to a figure — Paddle's preview — and sees the\n * dimensions over the new plan's limit before agreeing (§3.4: a limit gates creation\n * only, so the switch is allowed).\n */\n\n/** One side of a switch: a plan code and its billing period. */\nexport interface PlanSwitchSide {\n  plan: string;\n  interval: BillingInterval;\n}\n\nexport interface PlanSwitchConfirmProps {\n  open: boolean;\n  /** `false` when the payer dismisses it — Cancel, Escape, the backdrop. Confirm leaves\n   *  it open: close it once the switch answers. */\n  onOpenChange: (open: boolean) => void;\n  /** What the payer pays now: the overview's `paid`. */\n  from: PlanSwitchSide;\n  /** The pick. */\n  to: PlanSwitchSide;\n  /** `POST /billing/plan/preview`'s answer. Undefined while it loads: a spinner, and\n   *  Confirm is held. */\n  preview?: PlanSwitchPreview;\n  /** `POST /billing/plan` is under way: Confirm's spinner, no second press, and Escape\n   *  doesn't close. */\n  pending?: boolean;\n  /** The plan's display name, the app's (§3.1). Default: the code. */\n  planName?: (code: string) => string;\n  /**\n   * The app's word per dimension, for the over-limit lines. A heading's word (\"Budgets\")\n   * reads \"Budgets: 7 of 5\" (`billing.limitUsageLine`); its plural forms\n   * (`{ one: \"budget\", other: \"budgets\" }`) read \"7 of 5 budgets\" (`planChange.usageOf`,\n   * the form the limit takes). A dimension without one is named by its key.\n   */\n  dimensionLabels?: Readonly<Record<string, string | PluralForms>>;\n  /** How a usage or limit figure is written. Default: a number in the locale. */\n  formatLimit?: (dimension: string, value: number) => string;\n  /** Confirm: the app's `POST /billing/plan` with `{plan, interval}` of `to`. */\n  onConfirm: () => void;\n  /** The figures' and the date's locale. Default: the provider's. */\n  locale?: string;\n  /**\n   * 0.42 (§16.2 decision 5, §16.8 B): the payer's free grant runs without an end —\n   * `isPermanentGrant(overview)`. The switch changes the PAID plan, not the applied one\n   * (§12.11), so the dialog says so above its figures (`grantWarningTitle`,\n   * `grantWarningBody`) before the payer agrees. Confirm stays Confirm: the warning is\n   * this dialog's own, and `PlanPicker` — told `switching` — shows none of its own on\n   * the way here, so the payer reads it once.\n   */\n  permanentGrant?: boolean;\n  /** Prop > `<UiKitProvider labels={{ billing }}>` > English. */\n  labels?: LabelOverride<BillingLabels>;\n}\n\n/**\n * The confirm for a plan switch (§15.2.10): from → to, each with its billing period;\n * Paddle's preview — \"Charged now\" (an upgrade) or \"Credited towards your next charges\"\n * (a downgrade), and the next charge with its date — in the subscription's currency;\n * the dimensions over the new plan's limit; and Confirm.\n *\n *     const preview = useMutation({ mutationFn: api.previewPlanSwitch });\n *     <PlanSwitchConfirm\n *       open={pick !== null}\n *       onOpenChange={(open) => !open && setPick(null)}\n *       from={overview.paid}\n *       to={pick}\n *       preview={preview.data}\n *       pending={switching.isPending}\n *       planName={planName}\n *       onConfirm={() => switching.mutate(pick)}\n *     />\n *\n * It takes no billing lock (`COMMIT_EXCEPT_BILLING` built in): a read-only payer may\n * change plan, as they may pay. A demo lock still holds it, as the server's demo guard\n * does. The kit sends no request.\n */\nexport function PlanSwitchConfirm({\n  open,\n  onOpenChange,\n  from,\n  to,\n  preview,\n  pending = false,\n  planName = (code) => code,\n  dimensionLabels,\n  formatLimit,\n  onConfirm,\n  locale: localeProp,\n  permanentGrant = false,\n  labels: labelsProp,\n}: PlanSwitchConfirmProps) {\n  const labels = useBillingLabels(labelsProp);\n  const planChange = useKitLabels(\"planChange\", DEFAULT_PLAN_CHANGE_LABELS);\n  const common = useKitLabels(\"common\", DEFAULT_COMMON_LABELS);\n  const locale = useKitLocale(localeProp);\n\n  const period = (interval: BillingInterval) => (interval === \"year\" ? labels.yearly : labels.monthly);\n  const side = (s: PlanSwitchSide) => `${planName(s.plan.toLowerCase())} (${period(s.interval)})`;\n  const money = (minor: number, currency: string) =>\n    formatMoney(minorToMajor(minor, currency), currency, { locale });\n  const figure = (dimension: string, value: number) =>\n    formatLimit ? formatLimit(dimension, value) : formatNumber(value, { locale });\n\n  /** One line per dimension over the new limit, in the word's own sentence. */\n  const overLimit = (p: PlanSwitchPreview): string[] =>\n    (p.over_limit ?? []).flatMap((dimension) => {\n      const limit = p.limits?.[dimension];\n      const used = p.usage?.[dimension];\n      if (limit === null || limit === undefined || used === undefined) return [];\n      const word = dimensionLabels?.[dimension] ?? dimension;\n      return [\n        typeof word === \"string\"\n          ? labels.limitUsageLine(word, figure(dimension, used), figure(dimension, limit))\n          : planChange.usageOf(figure(dimension, used), figure(dimension, limit), pluralForm(limit, word, locale)),\n      ];\n    });\n\n  const credit = preview !== undefined && preview.now_minor < 0;\n  const lines = preview ? overLimit(preview) : [];\n\n  return (\n    <DialogFrame\n      open={open}\n      title={labels.switchTitle}\n      description={labels.switchFromTo(side(from), side(to))}\n      onClose={() => onOpenChange(false)}\n      onKeyDown={(e: KeyboardEvent<HTMLDivElement>) => {\n        if (pending && e.key === \"Escape\") e.preventDefault();\n      }}\n      aria-busy={preview === undefined || pending || undefined}\n      actions={(close) => (\n        <>\n          <Button variant=\"secondary\" onClick={close} disabled={pending}>\n            {common.cancel}\n          </Button>\n          <Button\n            commit={COMMIT_EXCEPT_BILLING}\n            pending={pending}\n            disabled={preview === undefined}\n            onClick={() => {\n              if (preview !== undefined && !pending) onConfirm();\n            }}\n          >\n            {labels.switchConfirm}\n          </Button>\n        </>\n      )}\n    >\n      {permanentGrant && (\n        <AlertBanner tone=\"warning\" size=\"sm\" data-grant-warning=\"\">\n          <strong className=\"block font-medium\">{labels.grantWarningTitle}</strong> {labels.grantWarningBody}\n        </AlertBanner>\n      )}\n      {preview === undefined ? (\n        <div className=\"flex justify-center py-4\">\n          <Spinner showLabel />\n        </div>\n      ) : (\n        <>\n          <dl className=\"grid grid-cols-[minmax(0,1fr)_auto] gap-x-4 gap-y-1 text-sm\" data-plan-switch-preview>\n            <dt className=\"text-secondary\">{credit ? labels.switchCredited : labels.switchChargedNow}</dt>\n            <dd className=\"text-right font-medium tabular-nums\" data-now={credit ? \"credit\" : \"charge\"}>\n              {money(Math.abs(preview.now_minor), preview.currency)}\n            </dd>\n            {preview.next_billed_at && preview.next_minor != null && (\n              <>\n                <dt className=\"text-secondary\">\n                  {labels.switchNextCharge(formatDate(preview.next_billed_at, \"medium\", { locale }))}\n                </dt>\n                <dd className=\"text-right tabular-nums\">{money(preview.next_minor, preview.currency)}</dd>\n              </>\n            )}\n          </dl>\n          {lines.length > 0 && (\n            <div className=\"space-y-1 text-sm\" data-plan-switch-over-limit>\n              <p>{planChange.overLimit}</p>\n              <ul className=\"list-disc space-y-0.5 ps-5 text-secondary\">\n                {lines.map((line) => (\n                  <li key={line}>{line}</li>\n                ))}\n              </ul>\n            </div>\n          )}\n        </>\n      )}\n    </DialogFrame>\n  );\n}\n"],"mappings":"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","names":[]}

package/dist/billing/provider-page.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 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 declare function openProviderPage(fetchUrl: () => Promise<string>, options?: OpenProviderPageOptions): Promise<ProviderPageWay>;

package/dist/billing/provider-page.js

@@ -0,0 +1,33 @@
+"use client";
+async function openProviderPage(fetchUrl, options = {}) {
+  const win = options.window ?? window;
+  let tab;
+  try {
+    tab = win.open("about:blank", "_blank");
+  } catch {
+    tab = null;
+  }
+  if (tab) {
+    try {
+      tab.opener = null;
+    } catch {
+    }
+  }
+  let url;
+  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";
+}
+export {
+  openProviderPage
+};
+//# sourceMappingURL=provider-page.js.map

package/dist/billing/provider-page.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/billing/provider-page.ts"],"sourcesContent":["/**\n * The provider's hosted portal in a NEW TAB (0.43, docs/billing-harmonization.md §17):\n * \"Payment and invoices\", the portal's \"Cancel subscription\" and the payment-failed\n * banner's \"Update payment method\" open at the provider while the app stays open where\n * it was. kastlan's `usePortal` (feat/kit-0.42, `72c3177`) is the reference.\n *\n * The checkout is NOT one of them (§17.4): it stays in the same tab, since the page waits\n * for the payer's return (`useCheckoutProcessing`).\n */\n\n/** How the page went: in a tab of its own, or — the browser refused one — in this one. */\nexport type ProviderPageWay = \"new-tab\" | \"same-tab\";\n\nexport interface OpenProviderPageOptions {\n  /** The window to open from and to fall back to. Default the global `window` (a test's\n   *  or an iframe's own). */\n  window?: Window;\n}\n\n/**\n * Opens the provider's page in a new tab, from INSIDE the click: call it in the click\n * handler itself, before any `await` — a `window.open` after one is blocked as a pop-up.\n *\n * 1. opens `about:blank` synchronously and sets its `opener` to `null`, so the provider's\n *    page cannot reach back into the app;\n * 2. awaits `fetchUrl` — the app's `POST /billing/portal` with its target, answering the\n *    `url` (the kit sends no request);\n * 3. points the tab at the URL;\n * 4. on a refusal closes the tab again and rethrows, so the app shows its error;\n * 5. where the browser refused the tab (a pop-up blocker), or it was closed while the\n *    URL was on its way, the app's own page goes there instead.\n *\n *     <SubscriptionActions\n *       onPortal={(target) => {\n *         openProviderPage(() => api.billingPortal({ target }).then((r) => r.url)).catch(showError);\n *       }}\n *       providerName=\"Paddle\"\n *       appName=\"Kastlan\"\n *     />\n *\n * Resolves with the way it went.\n */\nexport async function openProviderPage(\n  fetchUrl: () => Promise<string>,\n  options: OpenProviderPageOptions = {},\n): Promise<ProviderPageWay> {\n  const win = options.window ?? window;\n  let tab: Window | null;\n  try {\n    tab = win.open(\"about:blank\", \"_blank\");\n  } catch {\n    tab = null;\n  }\n  if (tab) {\n    try {\n      // The provider's page must not reach back into the app.\n      tab.opener = null;\n    } catch {\n      /* a browser that guards `opener`: the tab is still ours to point */\n    }\n  }\n  let url: string;\n  try {\n    url = await fetchUrl();\n  } catch (error) {\n    tab?.close();\n    throw error;\n  }\n  if (tab && !tab.closed) {\n    tab.location.href = url;\n    return \"new-tab\";\n  }\n  win.location.assign(url);\n  return \"same-tab\";\n}\n"],"mappings":";AA0CA,eAAsB,iBACpB,UACA,UAAmC,CAAC,GACV;AAC1B,QAAM,MAAM,QAAQ,UAAU;AAC9B,MAAI;AACJ,MAAI;AACF,UAAM,IAAI,KAAK,eAAe,QAAQ;AAAA,EACxC,QAAQ;AACN,UAAM;AAAA,EACR;AACA,MAAI,KAAK;AACP,QAAI;AAEF,UAAI,SAAS;AAAA,IACf,QAAQ;AAAA,IAER;AAAA,EACF;AACA,MAAI;AACJ,MAAI;AACF,UAAM,MAAM,SAAS;AAAA,EACvB,SAAS,OAAO;AACd,SAAK,MAAM;AACX,UAAM;AAAA,EACR;AACA,MAAI,OAAO,CAAC,IAAI,QAAQ;AACtB,QAAI,SAAS,OAAO;AACpB,WAAO;AAAA,EACT;AACA,MAAI,SAAS,OAAO,GAAG;AACvB,SAAO;AACT;","names":[]}

package/dist/billing/subscription-actions.d.ts

@@ -1,7 +1,13 @@
 import type { ComponentPropsWithRef } from "react";
 import type { LabelOverride } from "../i18n/kit-labels.js";
 import type { BillingLabels } from "./billing-labels.js";
-import type { PortalTarget } from "./billing-overview.js";
+import type { BillingPortalAccess, PortalTarget } from "./billing-overview.js";
+import type { CancelRequested } from "./cancel-request.js";
+/** The portal action's mark (§17.3): the external-link glyph after the words, and "(opens
+ *  in a new tab)" for a reader — on a link, `Button`'s `external` says the latter. */
+export declare function ExternalMark({ reader }: {
+    reader?: string;
+}): import("react").JSX.Element;
 export interface SubscriptionActionsProps extends Omit<ComponentPropsWithRef<"div">, "children"> {
     /** "Payment and invoices", as a link — or {@link onManage}. Without either, none. */
     manageHref?: string;
@@ -30,8 +36,54 @@ export interface SubscriptionActionsProps extends Omit<ComponentPropsWithRef<"di
      * (§12.26). Default true (0.32's behaviour).
      */
     atProvider?: boolean;
-    /** Which of the two is under way: its spinner, no second press. */
-    pending?: "manage" | "cancel" | null;
+    /**
+     * 0.42 (§16.2, server-kit 0.14): the overview's `portal`. `"buyer_only"` — the row has
+     * a buyer and the viewer isn't them, so the portal would answer `403
+     * billing_portal_buyer_only`: "Payment and invoices" becomes a caption naming the buyer
+     * (`buyerHolds`, no button), and "Cancel subscription" calls {@link onCancelInApp}
+     * (no portal at all — `cancelHref`, `onCancel` and `onPortal` are not used). `"open"`
+     * (default): as before.
+     */
+    portal?: BillingPortalAccess;
+    /** 0.42: the overview's `buyer_name`, for the caption under `"buyer_only"`. Empty: "…with
+     *  the admin who bought the subscription". */
+    buyerName?: string | null;
+    /**
+     * 0.42 (§16.2 decision 2): "Cancel subscription" in the app — open
+     * `CancelSubscriptionConfirm`, whose Confirm is `POST /billing/cancel`. The cancel under
+     * `"buyer_only"`. Under `"open"` it is the last resort, used only when no portal cancel
+     * (`cancelHref`, `onCancel`, `onPortal`) is given — a person-payer app that mounts the
+     * route and not the portal's cancel.
+     */
+    onCancelInApp?: () => void;
+    /** 0.42 (§16.7 C): the overview's `cancel_at_period_end` — a cancel is scheduled. With
+     *  {@link onResume}, "Keep subscription" takes the cancel's place. */
+    cancelAtPeriodEnd?: boolean;
+    /** 0.42 (§16.7 C): "Keep subscription", the app's `POST /billing/resume` — shown in
+     *  the cancel's place while {@link cancelAtPeriodEnd} is true. Without it, the cancel
+     *  stays as before. */
+    onResume?: () => void;
+    /**
+     * 0.43 (kastlan `18bf4c0`): what was asked in the app and the overview does not show
+     * yet — `useCancelRequest().view(row).requested`. `"cancel"`: shown as scheduled ("Keep
+     * subscription" with {@link onResume}; without it, no second "Cancel subscription").
+     * `"resume"`: shown as not scheduled. `null` (default): {@link cancelAtPeriodEnd} says.
+     */
+    cancelRequested?: CancelRequested;
+    /**
+     * 0.43 (§17): the portal opens in a NEW TAB — the app's handler calls
+     * `openProviderPage` — so its actions carry the external-link mark, a link opens with
+     * `target="_blank"`, and the `portalOpensNewTab` note shows under them. Default true;
+     * `false` for an app whose portal still opens in the same tab.
+     */
+    portalNewTab?: boolean;
+    /** 0.43: the provider's name in the note. Default `"Paddle"` (§2 decision 16). */
+    providerName?: string;
+    /** 0.43: the app's name in the note ("Kastlan stays open here"). Without it, "this page
+     *  stays open". */
+    appName?: string;
+    /** Which one is under way: its spinner, no second press. `"resume"` since 0.42. */
+    pending?: "manage" | "cancel" | "resume" | null;
     /** Prop > `<UiKitProvider labels={{ billing }}>` > English. */
     labels?: LabelOverride<BillingLabels>;
 }
@@ -50,5 +102,17 @@ export interface SubscriptionActionsProps extends Omit<ComponentPropsWithRef<"di
  * Before the payer has reached the provider (`atProvider={false}`, a trial without a
  * card, a beta) there is no portal to open: the part says so in a caption instead of
  * offering two buttons that could only end in `409 billing_not_at_provider`.
+ *
+ * 0.42 (§16): where the company's buyer is another admin (`portal="buyer_only"`), the
+ * portal stays the buyer's — "Payment and invoices" is a caption that names them, and
+ * "Cancel subscription" is the in-app cancel (`onCancelInApp`). While a cancel is
+ * scheduled (`cancelAtPeriodEnd`) and `onResume` is given, "Keep subscription" stands in
+ * the cancel's place, whoever the viewer is.
+ *
+ * 0.43 (§17): the portal opens in a new tab (`openProviderPage` in the app's handler):
+ * its actions carry the external-link mark, and a muted note says so — "Payment and
+ * invoices open at {provider} in a new tab; {app} stays open here." The in-app cancel and
+ * "Keep subscription" stay unmarked. After an in-app cancel or resume, `cancelRequested`
+ * (`useCancelRequest`) shows what was asked until the provider's webhook lands.
  */
-export declare function SubscriptionActions({ manageHref, onManage, cancelHref, onCancel, onPortal, atProvider, pending, labels: labelsProp, className, ...rest }: SubscriptionActionsProps): import("react").JSX.Element | null;
+export declare function SubscriptionActions({ manageHref, onManage, cancelHref, onCancel, onPortal, atProvider, portal, buyerName, onCancelInApp, cancelAtPeriodEnd, onResume, cancelRequested, portalNewTab, providerName, appName, pending, labels: labelsProp, className, ...rest }: SubscriptionActionsProps): import("react").JSX.Element | null;

package/dist/billing/subscription-actions.js

@@ -1,8 +1,23 @@
 "use client";
-import { jsx, jsxs } from "react/jsx-runtime";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { ExternalLink } from "lucide-react";
+import { DEFAULT_COMMON_LABELS, useKitLabels } from "../i18n/kit-labels.js";
 import { cn } from "../lib/cn.js";
 import { Button } from "../components/button.js";
 import { useBillingLabels } from "./billing-labels.js";
+function ExternalMark({ reader }) {
+  return /* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsx(ExternalLink, { "aria-hidden": true, "data-external": "", className: "size-4 shrink-0 rtl:-scale-x-100" }),
+    reader !== void 0 && /* @__PURE__ */ jsxs(Fragment, { children: [
+      " ",
+      /* @__PURE__ */ jsxs("span", { className: "sr-only", children: [
+        "(",
+        reader,
+        ")"
+      ] })
+    ] })
+  ] });
+}
 function SubscriptionActions({
   manageHref,
   onManage,
@@ -10,26 +25,71 @@ function SubscriptionActions({
   onCancel,
   onPortal,
   atProvider = true,
+  portal = "open",
+  buyerName,
+  onCancelInApp,
+  cancelAtPeriodEnd = false,
+  onResume,
+  cancelRequested = null,
+  portalNewTab = true,
+  providerName = "Paddle",
+  appName,
   pending,
   labels: labelsProp,
   className,
   ...rest
 }) {
   const labels = useBillingLabels(labelsProp);
+  const common = useKitLabels("common", DEFAULT_COMMON_LABELS);
   if (!atProvider) {
     return /* @__PURE__ */ jsx("div", { ...rest, "data-at-provider": "false", className: cn("text-sm text-muted", className), children: /* @__PURE__ */ jsx("p", { children: labels.notAtProvider }) });
   }
+  const buyerOnly = portal === "buyer_only";
   const manageCall = onManage ?? (onPortal ? () => onPortal("overview") : void 0);
-  const cancelCall = onCancel ?? (onPortal ? () => onPortal("cancel") : void 0);
-  const manage = manageHref !== void 0 ? /* @__PURE__ */ jsx(Button, { href: manageHref, variant: "secondary", children: labels.manage }) : manageCall !== void 0 ? /* @__PURE__ */ jsx(Button, { type: "button", variant: "secondary", onClick: manageCall, pending: pending === "manage", children: labels.manage }) : null;
-  const cancel = cancelHref !== void 0 ? /* @__PURE__ */ jsx(Button, { href: cancelHref, variant: "link", tone: "danger", children: labels.cancel }) : cancelCall !== void 0 ? /* @__PURE__ */ jsx(Button, { type: "button", variant: "link", tone: "danger", onClick: cancelCall, pending: pending === "cancel", children: labels.cancel }) : null;
+  const portalCancel = onCancel ?? (onPortal ? () => onPortal("cancel") : void 0);
+  const cancelCall = buyerOnly ? onCancelInApp : portalCancel ?? (cancelHref === void 0 ? onCancelInApp : void 0);
+  const scheduled = cancelRequested === "cancel" ? true : cancelRequested === "resume" ? false : cancelAtPeriodEnd;
+  const newTab = portalNewTab && !buyerOnly;
+  const words = (text, external, link) => external ? /* @__PURE__ */ jsxs(Fragment, { children: [
+    text,
+    /* @__PURE__ */ jsx(ExternalMark, { reader: link ? void 0 : common.opensInNewTab })
+  ] }) : text;
+  const portalCancelShown = !buyerOnly && (cancelHref !== void 0 || portalCancel !== void 0);
+  const manage = buyerOnly ? /* @__PURE__ */ jsx("p", { className: "basis-full text-sm text-muted", "data-buyer-holds": "", children: labels.buyerHolds(buyerName || void 0) }) : manageHref !== void 0 ? /* @__PURE__ */ jsx(Button, { href: manageHref, variant: "secondary", external: newTab || void 0, "data-portal-action": "manage", children: words(labels.manage, newTab, true) }) : manageCall !== void 0 ? /* @__PURE__ */ jsx(
+    Button,
+    {
+      type: "button",
+      variant: "secondary",
+      onClick: manageCall,
+      pending: pending === "manage",
+      className: newTab ? "relative" : void 0,
+      "data-portal-action": "manage",
+      children: words(labels.manage, newTab, false)
+    }
+  ) : null;
+  const cancel = scheduled && onResume !== void 0 ? /* @__PURE__ */ jsx(Button, { type: "button", variant: "link", onClick: onResume, pending: pending === "resume", "data-keep-subscription": "", children: labels.keepSubscription }) : cancelRequested === "cancel" ? null : cancelHref !== void 0 && !buyerOnly ? /* @__PURE__ */ jsx(Button, { href: cancelHref, variant: "link", tone: "danger", external: newTab || void 0, "data-portal-action": "cancel", children: words(labels.cancel, newTab, true) }) : cancelCall !== void 0 ? /* @__PURE__ */ jsx(
+    Button,
+    {
+      type: "button",
+      variant: "link",
+      tone: "danger",
+      onClick: cancelCall,
+      pending: pending === "cancel",
+      className: newTab && portalCancelShown ? "relative" : void 0,
+      "data-portal-action": portalCancelShown ? "cancel" : void 0,
+      children: words(labels.cancel, newTab && portalCancelShown, false)
+    }
+  ) : null;
   if (!manage && !cancel) return null;
+  const portalShown = !buyerOnly && (manage !== null || cancel !== null && portalCancelShown && !(scheduled && onResume));
   return /* @__PURE__ */ jsxs("div", { ...rest, className: cn("flex flex-wrap items-center gap-x-4 gap-y-2", className), children: [
     manage,
-    cancel
+    cancel,
+    newTab && portalShown && /* @__PURE__ */ jsx("p", { className: "basis-full text-sm text-muted", "data-portal-note": "", children: labels.portalOpensNewTab(providerName, appName || void 0) })
   ] });
 }
 export {
+  ExternalMark,
   SubscriptionActions
 };
 //# sourceMappingURL=subscription-actions.js.map

package/dist/billing/subscription-actions.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/billing/subscription-actions.tsx"],"sourcesContent":["import type { ComponentPropsWithRef } from \"react\";\n\nimport type { LabelOverride } from \"../i18n/kit-labels\";\nimport { cn } from \"../lib/cn\";\nimport { Button } from \"../components/button\";\nimport { useBillingLabels } from \"./billing-labels\";\nimport type { BillingLabels } from \"./billing-labels\";\nimport type { PortalTarget } from \"./billing-overview\";\n\nexport interface SubscriptionActionsProps extends Omit<ComponentPropsWithRef<\"div\">, \"children\"> {\n  /** \"Payment and invoices\", as a link — or {@link onManage}. Without either, none. */\n  manageHref?: string;\n  /** \"Payment and invoices\", as the app's call: `POST /billing/portal` with\n   *  `{target: \"overview\"}`, then off to its `url` (§4, §14.5). The kit sends no\n   *  request. */\n  onManage?: () => void;\n  /** \"Cancel subscription\", as a link — or {@link onCancel}. Without either, none. */\n  cancelHref?: string;\n  /** \"Cancel subscription\", as the app's call: the portal again, with `{target:\n   *  \"cancel\"}` — its cancel link, where the provider's cancel and withdrawal functions\n   *  are (§12.26, §14.5). Not the overview. */\n  onCancel?: () => void;\n  /**\n   * Both, as one call that says where to ({@link PortalTarget}, the body of\n   * `POST /billing/portal`): `\"overview\"` for \"Payment and invoices\",\n   * `\"cancel\"` for \"Cancel subscription\" — so the target can't be mixed up (kastlan's\n   * cancel opened the overview). {@link onManage} and {@link onCancel} win over it.\n   */\n  onPortal?: (target: PortalTarget) => void;\n  /**\n   * The overview's `at_provider` (§14.5): whether the payer has reached the provider.\n   * `false`: no customer there yet, so nothing to open — a caption (`notAtProvider`)\n   * stands in place of both actions. `true`: both show, WHATEVER the status or source —\n   * a payer who bought under a grant keeps the way to the invoices and to \"Cancel\"\n   * (§12.26). Default true (0.32's behaviour).\n   */\n  atProvider?: boolean;\n  /** Which of the two is under way: its spinner, no second press. */\n  pending?: \"manage\" | \"cancel\" | null;\n  /** Prop > `<UiKitProvider labels={{ billing }}>` > English. */\n  labels?: LabelOverride<BillingLabels>;\n}\n\n/**\n * The two ways to the provider's hosted portal on the subscription page\n * (docs/billing-harmonization.md §2.8, §7, §12.26): \"Payment and invoices\" — the payment\n * method and the invoices live there, never in the app — and a VISIBLE \"Cancel\n * subscription\". Consumer law wants the second in plain sight: Germany's cancellation\n * button (§312k BGB) and the EU withdrawal function (Directive (EU) 2023/2673, from\n * 19 June 2026) are in the portal, and the app's page must not hide the way there behind\n * \"manage\".\n *\n * Neither takes the write lock: a read-only payer must be able to pay, leave or cancel\n * (§3.3).\n *\n * Before the payer has reached the provider (`atProvider={false}`, a trial without a\n * card, a beta) there is no portal to open: the part says so in a caption instead of\n * offering two buttons that could only end in `409 billing_not_at_provider`.\n */\nexport function SubscriptionActions({\n  manageHref,\n  onManage,\n  cancelHref,\n  onCancel,\n  onPortal,\n  atProvider = true,\n  pending,\n  labels: labelsProp,\n  className,\n  ...rest\n}: SubscriptionActionsProps) {\n  const labels = useBillingLabels(labelsProp);\n  if (!atProvider) {\n    return (\n      <div {...rest} data-at-provider=\"false\" className={cn(\"text-sm text-muted\", className)}>\n        <p>{labels.notAtProvider}</p>\n      </div>\n    );\n  }\n  const manageCall = onManage ?? (onPortal ? () => onPortal(\"overview\") : undefined);\n  const cancelCall = onCancel ?? (onPortal ? () => onPortal(\"cancel\") : undefined);\n  const manage =\n    manageHref !== undefined ? (\n      <Button href={manageHref} variant=\"secondary\">\n        {labels.manage}\n      </Button>\n    ) : manageCall !== undefined ? (\n      <Button type=\"button\" variant=\"secondary\" onClick={manageCall} pending={pending === \"manage\"}>\n        {labels.manage}\n      </Button>\n    ) : null;\n  const cancel =\n    cancelHref !== undefined ? (\n      <Button href={cancelHref} variant=\"link\" tone=\"danger\">\n        {labels.cancel}\n      </Button>\n    ) : cancelCall !== undefined ? (\n      <Button type=\"button\" variant=\"link\" tone=\"danger\" onClick={cancelCall} pending={pending === \"cancel\"}>\n        {labels.cancel}\n      </Button>\n    ) : null;\n  if (!manage && !cancel) return null;\n  return (\n    <div {...rest} className={cn(\"flex flex-wrap items-center gap-x-4 gap-y-2\", className)}>\n      {manage}\n      {cancel}\n    </div>\n  );\n}\n"],"mappings":";AA2EQ,cA4BJ,YA5BI;AAxER,SAAS,UAAU;AACnB,SAAS,cAAc;AACvB,SAAS,wBAAwB;AAsD1B,SAAS,oBAAoB;AAAA,EAClC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA,aAAa;AAAA,EACb;AAAA,EACA,QAAQ;AAAA,EACR;AAAA,EACA,GAAG;AACL,GAA6B;AAC3B,QAAM,SAAS,iBAAiB,UAAU;AAC1C,MAAI,CAAC,YAAY;AACf,WACE,oBAAC,SAAK,GAAG,MAAM,oBAAiB,SAAQ,WAAW,GAAG,sBAAsB,SAAS,GACnF,8BAAC,OAAG,iBAAO,eAAc,GAC3B;AAAA,EAEJ;AACA,QAAM,aAAa,aAAa,WAAW,MAAM,SAAS,UAAU,IAAI;AACxE,QAAM,aAAa,aAAa,WAAW,MAAM,SAAS,QAAQ,IAAI;AACtE,QAAM,SACJ,eAAe,SACb,oBAAC,UAAO,MAAM,YAAY,SAAQ,aAC/B,iBAAO,QACV,IACE,eAAe,SACjB,oBAAC,UAAO,MAAK,UAAS,SAAQ,aAAY,SAAS,YAAY,SAAS,YAAY,UACjF,iBAAO,QACV,IACE;AACN,QAAM,SACJ,eAAe,SACb,oBAAC,UAAO,MAAM,YAAY,SAAQ,QAAO,MAAK,UAC3C,iBAAO,QACV,IACE,eAAe,SACjB,oBAAC,UAAO,MAAK,UAAS,SAAQ,QAAO,MAAK,UAAS,SAAS,YAAY,SAAS,YAAY,UAC1F,iBAAO,QACV,IACE;AACN,MAAI,CAAC,UAAU,CAAC,OAAQ,QAAO;AAC/B,SACE,qBAAC,SAAK,GAAG,MAAM,WAAW,GAAG,+CAA+C,SAAS,GAClF;AAAA;AAAA,IACA;AAAA,KACH;AAEJ;","names":[]}
+{"version":3,"sources":["../../src/billing/subscription-actions.tsx"],"sourcesContent":["import type { ComponentPropsWithRef, ReactNode } from \"react\";\nimport { ExternalLink } from \"lucide-react\";\n\nimport { DEFAULT_COMMON_LABELS, useKitLabels } from \"../i18n/kit-labels\";\nimport type { LabelOverride } from \"../i18n/kit-labels\";\nimport { cn } from \"../lib/cn\";\nimport { Button } from \"../components/button\";\nimport { useBillingLabels } from \"./billing-labels\";\nimport type { BillingLabels } from \"./billing-labels\";\nimport type { BillingPortalAccess, PortalTarget } from \"./billing-overview\";\nimport type { CancelRequested } from \"./cancel-request\";\n\n/** The portal action's mark (§17.3): the external-link glyph after the words, and \"(opens\n *  in a new tab)\" for a reader — on a link, `Button`'s `external` says the latter. */\nexport function ExternalMark({ reader }: { reader?: string }) {\n  return (\n    <>\n      <ExternalLink aria-hidden data-external=\"\" className=\"size-4 shrink-0 rtl:-scale-x-100\" />\n      {reader !== undefined && (\n        <>\n          {\" \"}\n          <span className=\"sr-only\">({reader})</span>\n        </>\n      )}\n    </>\n  );\n}\n\nexport interface SubscriptionActionsProps extends Omit<ComponentPropsWithRef<\"div\">, \"children\"> {\n  /** \"Payment and invoices\", as a link — or {@link onManage}. Without either, none. */\n  manageHref?: string;\n  /** \"Payment and invoices\", as the app's call: `POST /billing/portal` with\n   *  `{target: \"overview\"}`, then off to its `url` (§4, §14.5). The kit sends no\n   *  request. */\n  onManage?: () => void;\n  /** \"Cancel subscription\", as a link — or {@link onCancel}. Without either, none. */\n  cancelHref?: string;\n  /** \"Cancel subscription\", as the app's call: the portal again, with `{target:\n   *  \"cancel\"}` — its cancel link, where the provider's cancel and withdrawal functions\n   *  are (§12.26, §14.5). Not the overview. */\n  onCancel?: () => void;\n  /**\n   * Both, as one call that says where to ({@link PortalTarget}, the body of\n   * `POST /billing/portal`): `\"overview\"` for \"Payment and invoices\",\n   * `\"cancel\"` for \"Cancel subscription\" — so the target can't be mixed up (kastlan's\n   * cancel opened the overview). {@link onManage} and {@link onCancel} win over it.\n   */\n  onPortal?: (target: PortalTarget) => void;\n  /**\n   * The overview's `at_provider` (§14.5): whether the payer has reached the provider.\n   * `false`: no customer there yet, so nothing to open — a caption (`notAtProvider`)\n   * stands in place of both actions. `true`: both show, WHATEVER the status or source —\n   * a payer who bought under a grant keeps the way to the invoices and to \"Cancel\"\n   * (§12.26). Default true (0.32's behaviour).\n   */\n  atProvider?: boolean;\n  /**\n   * 0.42 (§16.2, server-kit 0.14): the overview's `portal`. `\"buyer_only\"` — the row has\n   * a buyer and the viewer isn't them, so the portal would answer `403\n   * billing_portal_buyer_only`: \"Payment and invoices\" becomes a caption naming the buyer\n   * (`buyerHolds`, no button), and \"Cancel subscription\" calls {@link onCancelInApp}\n   * (no portal at all — `cancelHref`, `onCancel` and `onPortal` are not used). `\"open\"`\n   * (default): as before.\n   */\n  portal?: BillingPortalAccess;\n  /** 0.42: the overview's `buyer_name`, for the caption under `\"buyer_only\"`. Empty: \"…with\n   *  the admin who bought the subscription\". */\n  buyerName?: string | null;\n  /**\n   * 0.42 (§16.2 decision 2): \"Cancel subscription\" in the app — open\n   * `CancelSubscriptionConfirm`, whose Confirm is `POST /billing/cancel`. The cancel under\n   * `\"buyer_only\"`. Under `\"open\"` it is the last resort, used only when no portal cancel\n   * (`cancelHref`, `onCancel`, `onPortal`) is given — a person-payer app that mounts the\n   * route and not the portal's cancel.\n   */\n  onCancelInApp?: () => void;\n  /** 0.42 (§16.7 C): the overview's `cancel_at_period_end` — a cancel is scheduled. With\n   *  {@link onResume}, \"Keep subscription\" takes the cancel's place. */\n  cancelAtPeriodEnd?: boolean;\n  /** 0.42 (§16.7 C): \"Keep subscription\", the app's `POST /billing/resume` — shown in\n   *  the cancel's place while {@link cancelAtPeriodEnd} is true. Without it, the cancel\n   *  stays as before. */\n  onResume?: () => void;\n  /**\n   * 0.43 (kastlan `18bf4c0`): what was asked in the app and the overview does not show\n   * yet — `useCancelRequest().view(row).requested`. `\"cancel\"`: shown as scheduled (\"Keep\n   * subscription\" with {@link onResume}; without it, no second \"Cancel subscription\").\n   * `\"resume\"`: shown as not scheduled. `null` (default): {@link cancelAtPeriodEnd} says.\n   */\n  cancelRequested?: CancelRequested;\n  /**\n   * 0.43 (§17): the portal opens in a NEW TAB — the app's handler calls\n   * `openProviderPage` — so its actions carry the external-link mark, a link opens with\n   * `target=\"_blank\"`, and the `portalOpensNewTab` note shows under them. Default true;\n   * `false` for an app whose portal still opens in the same tab.\n   */\n  portalNewTab?: boolean;\n  /** 0.43: the provider's name in the note. Default `\"Paddle\"` (§2 decision 16). */\n  providerName?: string;\n  /** 0.43: the app's name in the note (\"Kastlan stays open here\"). Without it, \"this page\n   *  stays open\". */\n  appName?: string;\n  /** Which one is under way: its spinner, no second press. `\"resume\"` since 0.42. */\n  pending?: \"manage\" | \"cancel\" | \"resume\" | null;\n  /** Prop > `<UiKitProvider labels={{ billing }}>` > English. */\n  labels?: LabelOverride<BillingLabels>;\n}\n\n/**\n * The two ways to the provider's hosted portal on the subscription page\n * (docs/billing-harmonization.md §2.8, §7, §12.26): \"Payment and invoices\" — the payment\n * method and the invoices live there, never in the app — and a VISIBLE \"Cancel\n * subscription\". Consumer law wants the second in plain sight: Germany's cancellation\n * button (§312k BGB) and the EU withdrawal function (Directive (EU) 2023/2673, from\n * 19 June 2026) are in the portal, and the app's page must not hide the way there behind\n * \"manage\".\n *\n * Neither takes the write lock: a read-only payer must be able to pay, leave or cancel\n * (§3.3).\n *\n * Before the payer has reached the provider (`atProvider={false}`, a trial without a\n * card, a beta) there is no portal to open: the part says so in a caption instead of\n * offering two buttons that could only end in `409 billing_not_at_provider`.\n *\n * 0.42 (§16): where the company's buyer is another admin (`portal=\"buyer_only\"`), the\n * portal stays the buyer's — \"Payment and invoices\" is a caption that names them, and\n * \"Cancel subscription\" is the in-app cancel (`onCancelInApp`). While a cancel is\n * scheduled (`cancelAtPeriodEnd`) and `onResume` is given, \"Keep subscription\" stands in\n * the cancel's place, whoever the viewer is.\n *\n * 0.43 (§17): the portal opens in a new tab (`openProviderPage` in the app's handler):\n * its actions carry the external-link mark, and a muted note says so — \"Payment and\n * invoices open at {provider} in a new tab; {app} stays open here.\" The in-app cancel and\n * \"Keep subscription\" stay unmarked. After an in-app cancel or resume, `cancelRequested`\n * (`useCancelRequest`) shows what was asked until the provider's webhook lands.\n */\nexport function SubscriptionActions({\n  manageHref,\n  onManage,\n  cancelHref,\n  onCancel,\n  onPortal,\n  atProvider = true,\n  portal = \"open\",\n  buyerName,\n  onCancelInApp,\n  cancelAtPeriodEnd = false,\n  onResume,\n  cancelRequested = null,\n  portalNewTab = true,\n  providerName = \"Paddle\",\n  appName,\n  pending,\n  labels: labelsProp,\n  className,\n  ...rest\n}: SubscriptionActionsProps) {\n  const labels = useBillingLabels(labelsProp);\n  const common = useKitLabels(\"common\", DEFAULT_COMMON_LABELS);\n  if (!atProvider) {\n    return (\n      <div {...rest} data-at-provider=\"false\" className={cn(\"text-sm text-muted\", className)}>\n        <p>{labels.notAtProvider}</p>\n      </div>\n    );\n  }\n  const buyerOnly = portal === \"buyer_only\";\n  const manageCall = onManage ?? (onPortal ? () => onPortal(\"overview\") : undefined);\n  const portalCancel = onCancel ?? (onPortal ? () => onPortal(\"cancel\") : undefined);\n  // Under \"buyer_only\" the in-app cancel only; under \"open\" the portal's first, the\n  // in-app cancel only where no way to the portal's is given.\n  const cancelCall = buyerOnly ? onCancelInApp : (portalCancel ?? (cancelHref === undefined ? onCancelInApp : undefined));\n  // 0.43: what was asked in the app wins over the row until the row moves.\n  const scheduled = cancelRequested === \"cancel\" ? true : cancelRequested === \"resume\" ? false : cancelAtPeriodEnd;\n  // 0.43 (§17): the portal's actions are marked, a link opens a tab of its own.\n  const newTab = portalNewTab && !buyerOnly;\n  const words = (text: string, external: boolean, link: boolean): ReactNode =>\n    external ? (\n      <>\n        {text}\n        <ExternalMark reader={link ? undefined : common.opensInNewTab} />\n      </>\n    ) : (\n      text\n    );\n  const portalCancelShown = !buyerOnly && (cancelHref !== undefined || portalCancel !== undefined);\n  const manage = buyerOnly ? (\n    <p className=\"basis-full text-sm text-muted\" data-buyer-holds=\"\">\n      {labels.buyerHolds(buyerName || undefined)}\n    </p>\n  ) : manageHref !== undefined ? (\n    <Button href={manageHref} variant=\"secondary\" external={newTab || undefined} data-portal-action=\"manage\">\n      {words(labels.manage, newTab, true)}\n    </Button>\n  ) : manageCall !== undefined ? (\n    <Button\n      type=\"button\"\n      variant=\"secondary\"\n      onClick={manageCall}\n      pending={pending === \"manage\"}\n      className={newTab ? \"relative\" : undefined}\n      data-portal-action=\"manage\"\n    >\n      {words(labels.manage, newTab, false)}\n    </Button>\n  ) : null;\n  const cancel =\n    scheduled && onResume !== undefined ? (\n      <Button type=\"button\" variant=\"link\" onClick={onResume} pending={pending === \"resume\"} data-keep-subscription=\"\">\n        {labels.keepSubscription}\n      </Button>\n    ) : cancelRequested === \"cancel\" ? null : cancelHref !== undefined && !buyerOnly ? (\n      <Button href={cancelHref} variant=\"link\" tone=\"danger\" external={newTab || undefined} data-portal-action=\"cancel\">\n        {words(labels.cancel, newTab, true)}\n      </Button>\n    ) : cancelCall !== undefined ? (\n      <Button\n        type=\"button\"\n        variant=\"link\"\n        tone=\"danger\"\n        onClick={cancelCall}\n        pending={pending === \"cancel\"}\n        className={newTab && portalCancelShown ? \"relative\" : undefined}\n        data-portal-action={portalCancelShown ? \"cancel\" : undefined}\n      >\n        {words(labels.cancel, newTab && portalCancelShown, false)}\n      </Button>\n    ) : null;\n  if (!manage && !cancel) return null;\n  // The note while a way to the portal shows: \"Payment and invoices open at Paddle in a\n  // new tab; Kastlan stays open here.\"\n  const portalShown = !buyerOnly && (manage !== null || (cancel !== null && portalCancelShown && !(scheduled && onResume)));\n  return (\n    <div {...rest} className={cn(\"flex flex-wrap items-center gap-x-4 gap-y-2\", className)}>\n      {manage}\n      {cancel}\n      {newTab && portalShown && (\n        <p className=\"basis-full text-sm text-muted\" data-portal-note=\"\">\n          {labels.portalOpensNewTab(providerName, appName || undefined)}\n        </p>\n      )}\n    </div>\n  );\n}\n"],"mappings":"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","names":[]}

package/dist/components/account-chips.d.ts

@@ -2,7 +2,7 @@ import type { ReactElement, ReactNode } from "react";
 import type { LucideIcon } from "lucide-react";
 import type { DateInput, FormatDateStyle, FormatRelativeTimeOptions } from "../lib/format.js";
 import { type LabelOverride } from "../i18n/kit-labels.js";
-import type { ChipShape, ChipSize, ChipTone, ChipVariant } from "./chip.js";
+import type { ChipLinkProps, ChipShape, ChipSize, ChipTone, ChipVariant } from "./chip.js";
 import type { DataTableColumn } from "./data-table.js";
 import { DEFAULT_ACCOUNT_STATE_LABELS } from "./account-chips-labels.js";
 /**
@@ -38,8 +38,29 @@ interface AccountChipLook {
 export interface RoleDefinition {
     label: string;
     tone?: ChipTone;
-    /** A lucide component or an element — Kurvenschmiede marks its admins with a shield. */
+    /**
+     * A lucide component or an element — Kurvenschmiede marks its admins with a shield.
+     * Unlike {@link href} and {@link variant}, it shows EVERYWHERE the role is drawn: in
+     * {@link AccountRoleChip} and in {@link RoleChip} (the roster's column) alike. That is
+     * intended (0.43, keksdose's question): the glyph is part of how the role reads, so the
+     * shield on the header's chip is the shield in the users list. An app that wants the
+     * glyph in one place only hands the other a second vocabulary without `icon`.
+     */
     icon?: LucideIcon | ReactElement;
+    /**
+     * 0.42.0 (docs/admin-harmonization.md §2.1, settings §12.3): the role's tool — an
+     * admin's `/admin`, a reviewer's `/translations`. {@link AccountRoleChip} is a link to
+     * it; a role without one gets a plain chip. {@link RoleChip} ignores it: a roster's
+     * chips name a role, they are not a way in.
+     */
+    href?: string;
+    /**
+     * 0.42.0 (keksdose build review): this role's look in {@link AccountRoleChip} — keksdose
+     * draws only ADMIN `solid` and its REVIEWER and MEMBER `soft`. Default `solid`, the
+     * header's look; the chip's own `variant` prop wins over it. {@link RoleChip} ignores
+     * it: a roster's column keeps one look, set on the column.
+     */
+    variant?: ChipVariant;
 }
 /**
  * Every role an app has, keyed by the value its API sends. Annotate the app's table
@@ -67,6 +88,33 @@ export interface RoleChipProps<R extends string = string> extends AccountChipLoo
  * style hook.
  */
 export declare function RoleChip<R extends string = string>({ value: role, roles, size, variant, shape, caps, className, ...rest }: RoleChipProps<R>): import("react").JSX.Element | null;
+export interface AccountRoleChipProps<R extends string = string> extends RoleChipProps<R> {
+    /**
+     * Runs on the way to the role's tool — the account menu's `close`, so the panel does
+     * not stay open over the page it just navigated to (keksdose F7). Only called on a
+     * link chip.
+     */
+    onNavigate?: () => void;
+    /** Your router's link for the role's `href`. Default: the `<UiKitProvider
+     *  linkComponent>`, then `<a>` — {@link Chip}'s `renderLink`. */
+    renderLink?: (props: ChipLinkProps) => ReactElement;
+}
+/**
+ * The role in the account menu's header (0.42.0, docs/admin-harmonization.md §2.1, §7):
+ * {@link RoleChip} in keksdose's look — `solid`, `sm`, `square`, `caps`, the role's icon
+ * and tone — made for `TopBarActionMenu`'s `header.extra`:
+ *
+ *     extra: (close) => <AccountRoleChip value={me.role} roles={ROLES} onNavigate={close} />
+ *
+ * A role whose {@link RoleDefinition.href} is set is a shortcut to its tool: the chip is a
+ * link (through `renderLink`, else the provider's link, as {@link Chip} draws links) and
+ * calls `onNavigate` on the click. Any other role is a plain chip — every account shows
+ * its role (§7, "Always a badge"). The words and tones are the app's vocabulary; the kit
+ * adds none. `solid` stays the default, so a role the app gives no look still reads as
+ * the header's tag; a role that should sit quieter (keksdose's MEMBER and REVIEWER) sets
+ * {@link RoleDefinition.variant} `soft` in the vocabulary. Carries `data-role` with the key.
+ */
+export declare function AccountRoleChip<R extends string = string>({ value: role, roles, onNavigate, renderLink, size, variant, shape, caps, className, ...rest }: AccountRoleChipProps<R>): import("react").JSX.Element | null;
 /**
  * The states both rosters show, each as the app's own flag maps onto it:
  *

package/dist/components/account-chips.js

@@ -34,6 +34,38 @@ function RoleChip({
     }
   );
 }
+function AccountRoleChip({
+  value: role,
+  roles,
+  onNavigate,
+  renderLink,
+  size = "sm",
+  variant,
+  shape = "square",
+  caps = true,
+  className,
+  ...rest
+}) {
+  if (role === null || role === void 0 || role === "") return null;
+  const def = roles[role];
+  const look = {
+    ...rest,
+    "data-role": role,
+    tone: def?.tone ?? "neutral",
+    icon: def?.icon,
+    size,
+    // The prop, then the role's own look, then the header's `solid`.
+    variant: variant ?? def?.variant ?? "solid",
+    shape,
+    caps,
+    className
+  };
+  const label = def?.label ?? role;
+  if (def?.href) {
+    return /* @__PURE__ */ jsx(Chip, { ...look, href: def.href, renderLink, onClick: onNavigate ? () => onNavigate() : void 0, children: label });
+  }
+  return /* @__PURE__ */ jsx(Chip, { ...look, children: label });
+}
 const ACCOUNT_STATE_TONES = {
   active: "success",
   inactive: "danger",
@@ -158,6 +190,7 @@ function dateColumn({
 }
 export {
   ACCOUNT_STATE_TONES,
+  AccountRoleChip,
   AccountStateChip,
   DEFAULT_ACCOUNT_STATE_LABELS,
   DateMark,