@owlmeans/web-payment 0.1.18-rc.20 → 0.1.18-rc.21

package/src/consumer/withdrawal.tsx

@@ -0,0 +1,279 @@
+import { useEffect, useMemo, useState, type ReactNode } from 'react'
+import { baseLanguageOf } from '@owlmeans/payment'
+import type { WithdrawalBody, WithdrawalCandidate, WithdrawalReceipt } from '@owlmeans/payment'
+import { cn } from '@/lib/utils'
+import { Button } from '@/components/ui/button'
+import { Dialog, DialogContent, DialogDescription, DialogTitle } from '@/components/ui/dialog'
+import { dayUtc, lastDayUtc, momentUtc, money } from '../format.js'
+import { legalTextOf, paymentTextOf, useLegalText, usePaymentText } from './copy.js'
+import { Choice, Field, Honeypot, isEmail } from './fields.js'
+import { ErrorLine, LanguageToggle, useShownLanguage, useUiLanguage } from './legal.js'
+import type {
+  DeclarationStep, WithdrawalDialogProps, WithdrawalFormProps, WithdrawalFunctionButtonProps,
+} from './types.js'
+
+/**
+ * The withdrawal function's entry (CRD Art. 11a; § 356a BGB "Vertrag widerrufen"; L221-21
+ * "Renoncer au contrat ici"): the statutory label in the CONTRACT language, and the interface
+ * language's label as its `title` when the two differ.
+ *
+ * `[data-withdrawal-function]` with `data-language`.
+ */
+export const WithdrawalFunctionButton = ({
+  language, uiLanguage, onClick, disabled, variant = 'outline', className,
+}: WithdrawalFunctionButtonProps) => {
+  const ui = useUiLanguage(uiLanguage)
+  const contract = baseLanguageOf(language) || ui
+  const label = legalTextOf(contract)('withdrawal.function')
+  const title = contract !== ui ? legalTextOf(ui)('withdrawal.function') : undefined
+
+  return <Button type="button" variant={variant} onClick={onClick} disabled={disabled} title={title} lang={contract}
+    data-withdrawal-function="" data-language={contract} className={className}>
+    {label}
+  </Button>
+}
+
+const isWithdrawalReceipt = (receipt: object): receipt is WithdrawalReceipt => 'status' in receipt
+
+interface Frame {
+  title: string
+  intro: string
+  language: string
+  step: DeclarationStep
+}
+
+interface StepsProps extends WithdrawalFormProps {
+  /** How the title and intro are rendered — a section heading, or a dialog's title. */
+  frame: (frame: Frame, body: ReactNode) => ReactNode
+}
+
+/** The three steps, framed by the caller. */
+const WithdrawalSteps = ({
+  mode, language: contractLanguage, uiLanguage, list, defaults, pending = false, error, receipt, onSubmit, onClose,
+  formatAmount, frame,
+}: StepsProps) => {
+  const language = useShownLanguage(contractLanguage, uiLanguage)
+  const legal = useLegalText(language.shown)
+  const text = usePaymentText(language.shown)
+  const candidates = useMemo(() => list?.candidates ?? [], [list])
+
+  const initialPurchase = (): string => {
+    const byId = candidates.find(candidate => candidate.purchaseId === defaults?.purchaseId)
+    const byRef = candidates.find(candidate => candidate.contractRef === defaults?.contractRef)
+
+    return (byId ?? byRef ?? (candidates.length === 1 ? candidates[0] : undefined))?.purchaseId ?? ''
+  }
+  const [step, setStep] = useState<'form' | 'review'>('form')
+  const [purchaseId, setPurchaseId] = useState(initialPurchase)
+  const [contractRef, setContractRef] = useState(defaults?.contractRef ?? '')
+  const [name, setName] = useState(defaults?.name ?? list?.name ?? '')
+  const [email, setEmail] = useState(defaults?.email ?? list?.email ?? '')
+  const [honeypot, setHoneypot] = useState('')
+  const [checked, setChecked] = useState(false)
+  const [submitted, setSubmitted] = useState<WithdrawalBody | null>(null)
+  useEffect(() => {
+    // The list may arrive after the form: preselect and prefill then, never over what was typed.
+    if (purchaseId === '' && candidates.length > 0) setPurchaseId(initialPurchase())
+    if (list?.name != null) setName(held => held === '' ? list.name ?? '' : held)
+    if (list?.email != null) setEmail(held => held === '' ? list.email ?? '' : held)
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [list])
+  useEffect(() => {
+    if (receipt == null) setStep(current => submitted == null ? current : 'form')
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [receipt])
+
+  const current: DeclarationStep = receipt != null ? 'receipt' : step
+
+  const format = (minor: number, currency: string) => formatAmount != null
+    ? formatAmount(minor, currency, language.shown) : money(minor, currency, language.shown)
+  const candidate: WithdrawalCandidate | undefined = candidates.find(item => item.purchaseId === purchaseId)
+  const contract = mode === 'in-app' ? candidate?.contractRef ?? '' : contractRef.trim()
+  const errors = {
+    contract: mode === 'in-app'
+      ? (candidate == null ? text('consumer.required') : null)
+      : (contract === '' ? text('consumer.required') : null),
+    name: name.trim() === '' ? text('consumer.required') : null,
+    email: email.trim() === '' ? text('consumer.required') : !isEmail(email.trim()) ? text('consumer.email-invalid') : null,
+  }
+  const shown = (key: keyof typeof errors) => checked ? errors[key] : null
+  const valid = Object.values(errors).every(value => value == null)
+  const body = (): WithdrawalBody => ({
+    ...(mode === 'in-app' && candidate != null
+      ? { purchaseId: candidate.purchaseId, contractRef: candidate.contractRef }
+      : { contractRef: contract }),
+    name: name.trim(),
+    email: email.trim(),
+    language: language.shown,
+    ...(honeypot !== '' ? { honeypot } : {}),
+  })
+  const toReview = () => {
+    setChecked(true)
+    if (valid) setStep('review')
+  }
+  const confirm = async () => {
+    if (!valid || pending) return
+    const declared = body()
+    setSubmitted(declared)
+    await onSubmit(declared)
+  }
+
+  const estimateLine = (item: WithdrawalCandidate) => item.estimate != null
+    ? <span data-withdrawal-estimate="" data-refund-minor={item.estimate.refundMinor}>
+      {text('withdrawal.estimate', { amount: format(item.estimate.refundMinor, item.estimate.currency) })}
+    </span>
+    : <span data-withdrawal-estimate="" className="text-muted-foreground">{text('withdrawal.estimate-unknown')}</span>
+
+  const summary = (declared: Pick<WithdrawalBody, 'name' | 'email'> & { contract: string }) =>
+    <dl className="grid grid-cols-[auto_1fr] gap-x-4 gap-y-1.5 rounded-lg border bg-muted/30 p-4 text-sm">
+      <dt className="text-muted-foreground">{legal('withdrawal.name')}</dt><dd data-summary="name">{declared.name}</dd>
+      <dt className="text-muted-foreground">{legal('withdrawal.contract')}</dt><dd data-summary="contract">{declared.contract}</dd>
+      <dt className="text-muted-foreground">{legal('withdrawal.email')}</dt><dd data-summary="email">{declared.email}</dd>
+    </dl>
+
+  let content: ReactNode
+  if (current === 'receipt' && receipt != null) {
+    const receivedAt = new Date(receipt.receivedAt)
+    const declared = submitted ?? body()
+    const status = isWithdrawalReceipt(receipt) ? receipt.status : undefined
+    content = <div className="grid gap-4" data-withdrawal-receipt="" data-status={status ?? 'received'}
+      data-declaration-id={receipt.declarationId} data-received-at={Number.isNaN(receivedAt.getTime()) ? undefined : receivedAt.toISOString()}>
+      <h3 className="text-sm font-medium">{text('consumer.receipt')}</h3>
+      <p className="text-sm">{receipt.mailed
+        ? legal('withdrawal.received', { date: momentUtc(receivedAt, language.shown), email: declared.email })
+        : `${text('consumer.received-at')}: ${momentUtc(receivedAt, language.shown)} (UTC). ${text('consumer.not-mailed')}`}</p>
+      <dl className="grid grid-cols-[auto_1fr] gap-x-4 gap-y-1.5 rounded-lg border p-4 text-sm">
+        <dt className="text-muted-foreground">{text('consumer.reference')}</dt>
+        <dd data-withdrawal-reference="">{receipt.declarationId}</dd>
+        <dt className="text-muted-foreground">{text('consumer.received-at')}</dt>
+        <dd data-withdrawal-received-at="">{momentUtc(receivedAt, language.shown)} (UTC)</dd>
+        <dt className="text-muted-foreground">{legal('withdrawal.name')}</dt><dd>{declared.name}</dd>
+        <dt className="text-muted-foreground">{legal('withdrawal.contract')}</dt><dd>{declared.contractRef ?? ''}</dd>
+        <dt className="text-muted-foreground">{legal('withdrawal.email')}</dt><dd>{declared.email}</dd>
+        {status != null && <>
+          <dt className="text-muted-foreground">{text('consumer.status')}</dt>
+          <dd data-withdrawal-status="">{text(`withdrawal.status.${status}`)}</dd>
+        </>}
+        {isWithdrawalReceipt(receipt) && receipt.refundMinor != null && receipt.currency != null && <>
+          <dt className="text-muted-foreground">{text('withdrawal.refund')}</dt>
+          <dd data-withdrawal-refund="" data-refund-minor={receipt.refundMinor}>{format(receipt.refundMinor, receipt.currency)}</dd>
+        </>}
+      </dl>
+      {isWithdrawalReceipt(receipt) && receipt.subscriptionCanceled === true
+        && <p className="text-sm">{text('withdrawal.subscription-canceled')}</p>}
+      {onClose != null && <div className="flex justify-end">
+        <Button type="button" variant="outline" onClick={onClose}>{text('consumer.close')}</Button>
+      </div>}
+    </div>
+  } else if (current === 'review') {
+    content = <div className="grid gap-4">
+      <h3 className="text-sm font-medium">{text('consumer.review')}</h3>
+      <p className="text-sm">{legal('withdrawal.review')}</p>
+      {summary({ name: name.trim(), email: email.trim(), contract })}
+      {mode === 'in-app' && candidate != null && <p className="text-sm">{estimateLine(candidate)}</p>}
+      <ErrorLine error={error} text={text} />
+      <div className="flex flex-col-reverse gap-2 sm:flex-row sm:justify-end">
+        <Button type="button" variant="outline" disabled={pending} onClick={() => setStep('form')}
+          data-withdrawal-back="">{text('consumer.back')}</Button>
+        <Button type="button" disabled={pending || !valid} onClick={() => void confirm()} data-withdrawal-confirm="">
+          {pending ? text('consumer.pending') : legal('withdrawal.confirm')}
+        </Button>
+      </div>
+    </div>
+  } else {
+    content = <form className="relative grid gap-4" noValidate onSubmit={event => { event.preventDefault(); toReview() }}>
+      {mode === 'in-app'
+        ? candidates.length === 0
+          ? <p className="text-muted-foreground text-sm" data-withdrawal-none="">{text('withdrawal.none')}</p>
+          : <fieldset className="grid gap-2">
+            <legend className="mb-1 text-sm font-medium">{legal('withdrawal.contract')}</legend>
+            {candidates.map(item => <Choice
+              key={item.purchaseId} id={`withdrawal-candidate-${item.purchaseId}`} name="withdrawal-candidate"
+              checked={item.purchaseId === purchaseId} onSelect={() => setPurchaseId(item.purchaseId)} disabled={pending}
+              hook={{ 'data-withdrawal-candidate-input': item.purchaseId }}
+            >
+              <span data-withdrawal-candidate="" data-purchase-id={item.purchaseId} data-contract-ref={item.contractRef}
+                className="grid gap-0.5">
+                <span className="font-medium">{item.contractRef} · {text(`withdrawal.kind.${item.kind}`)}</span>
+                <span className="text-muted-foreground text-xs">
+                  {text('withdrawal.purchased', { date: dayUtc(item.purchasedAt, language.shown) })}
+                  {' · '}{text('withdrawal.paid', { amount: format(item.amountTotalMinor, item.currency) })}
+                  {' · '}{text('withdrawal.until', { date: lastDayUtc(item.deadline, language.shown) })}
+                </span>
+                <span className="text-xs">{estimateLine(item)}</span>
+              </span>
+            </Choice>)}
+            {shown('contract') != null && <p className="text-destructive text-xs">{shown('contract')}</p>}
+          </fieldset>
+        : <Field id="withdrawal-contract" label={legal('withdrawal.contract')} value={contractRef} onChange={setContractRef}
+          error={shown('contract')} disabled={pending} hook={{ 'data-withdrawal-field': 'contract' }} />}
+      <Field id="withdrawal-name" label={legal('withdrawal.name')} value={name} onChange={setName} error={shown('name')}
+        autoComplete="name" disabled={pending} hook={{ 'data-withdrawal-field': 'name' }} />
+      <Field id="withdrawal-email" type="email" label={legal('withdrawal.email')} value={email} onChange={setEmail}
+        error={shown('email')} autoComplete="email" disabled={pending} hook={{ 'data-withdrawal-field': 'email' }} />
+      {mode === 'public' && <Honeypot id="withdrawal-website" label={text('consumer.website')} value={honeypot} onChange={setHoneypot} />}
+      <ErrorLine error={error} text={text} />
+      <div className="flex justify-end">
+        <Button type="submit" disabled={pending || (mode === 'in-app' && candidates.length === 0)} data-withdrawal-continue="">
+          {text('consumer.continue')}
+        </Button>
+      </div>
+    </form>
+  }
+
+  return frame({ title: legal('withdrawal.title'), intro: legal('withdrawal.intro'), language: language.shown, step: current }, <>
+    <LanguageToggle language={language} hook="data-withdrawal-language-toggle" />
+    <div data-withdrawal-form="" data-withdrawal-step={current} data-step={current} data-mode={mode}
+      data-language={language.shown} lang={language.shown} className="grid gap-4">
+      {content}
+    </div>
+  </>)
+}
+
+/**
+ * The withdrawal function as a page section: the form (in-app a contract picker with the estimated
+ * refund, publicly a contract reference — and nothing but name, contract and e-mail is asked),
+ * the review with the statutory confirm button ("Confirm withdrawal", "Widerruf bestätigen",
+ * "Confirmer la rétractation"), and the receipt with the date and time of receipt in UTC. Legal
+ * copy in the contract language, with a toggle to the interface language.
+ *
+ * Selectors: `[data-withdrawal-form]` / `[data-withdrawal-step="form|review|receipt"]` (also
+ * `data-step`, `data-language`, `data-mode`), `[data-withdrawal-candidate]` (`data-purchase-id`),
+ * `[data-withdrawal-estimate]`, `[data-withdrawal-field="contract|name|email"]`,
+ * `[data-withdrawal-continue]`, `[data-withdrawal-confirm]`, `[data-withdrawal-receipt]`
+ * (`data-status`, `data-declaration-id`, `data-received-at`), `[data-withdrawal-reference]`.
+ */
+export const WithdrawalForm = ({ className, ...props }: WithdrawalFormProps) => <WithdrawalSteps
+  {...props}
+  frame={(frame, body) => <section className={cn('grid gap-4', className)} data-withdrawal-section=""
+    data-language={frame.language}>
+    <header className="grid gap-1.5" lang={frame.language}>
+      <h2 className="text-lg font-semibold leading-none">{frame.title}</h2>
+      {frame.step === 'form' && <p className="text-muted-foreground text-sm">{frame.intro}</p>}
+    </header>
+    {body}
+  </section>}
+/>
+
+/**
+ * `WithdrawalForm` in a dialog: `[data-withdrawal-dialog]` carries `data-language` and `data-step`.
+ * Closing it does not clear a receipt the application holds — reset it when the dialog closes.
+ */
+export const WithdrawalDialog = ({ open, onOpenChange, className, ...props }: WithdrawalDialogProps) =>
+  <Dialog open={open} onOpenChange={onOpenChange}>
+    {open && <WithdrawalSteps
+      {...props}
+      onClose={() => onOpenChange(false)}
+      frame={(frame, body) => <DialogContent
+        closeLabel={paymentTextOf(frame.language)('consumer.close')}
+        data-withdrawal-dialog="" data-language={frame.language} data-step={frame.step}
+        className={cn('max-h-[90vh] overflow-y-auto', className)}
+      >
+        <div className="grid gap-2" lang={frame.language}>
+          <DialogTitle>{frame.title}</DialogTitle>
+          <DialogDescription className={frame.step === 'form' ? undefined : 'sr-only'}>{frame.intro}</DialogDescription>
+        </div>
+        {body}
+      </DialogContent>}
+    />}
+  </Dialog>

package/src/dialog.tsx

@@ -1,6 +1,7 @@
 import { useEffect, useMemo, useState } from 'react'
 import { useI18nLib, useLanguage } from '@owlmeans/client-i18n'
-import { assertCheckoutAmount, chargeAmountMinor } from '@owlmeans/payment'
+import { assertCheckoutAmount, chargeAmountMinor, narrowAmountPolicy } from '@owlmeans/payment'
+import type { AmountCheckoutPolicy, CheckoutLimitView } from '@owlmeans/payment'
 import { Button } from '@/components/ui/button'
 import {
   Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle,
@@ -8,66 +9,92 @@ import {
 import { Input } from '@/components/ui/input'
 import { Label } from '@/components/ui/label'
 import { inputAmount, parseAmountMinor } from './amount.js'
+import { CheckoutLimitNote } from './checkout-limit.js'
 import { PriceEstimateSummary } from './estimate-summary.js'
+import { money } from './format.js'
 import type { AmountCheckoutDialogProps } from './types.js'
 
-const money = (minor: number, currency: string, locale: string): string => new Intl.NumberFormat(locale, {
-  style: 'currency', currency: currency.toUpperCase(), minimumFractionDigits: 2,
-}).format(minor / 100)
+/**
+ * The policy the dialog offers: `policy` narrowed by `limit` — the same `narrowAmountPolicy` the
+ * server refuses with. A policy the package cannot narrow (an invalid one) is offered as given.
+ */
+const effectivePolicyOf = (policy: AmountCheckoutPolicy, limit?: CheckoutLimitView | null): AmountCheckoutPolicy => {
+  if (limit == null || (!limit.narrowed && !limit.blocked)) {
+    return policy
+  }
+  try {
+    return narrowAmountPolicy(policy, [{
+      maximumMinor: limit.maximumMinor,
+      reason: limit.reason ?? 'limit',
+      ...(limit.resetsAt != null ? { resetsAt: limit.resetsAt } : {}),
+      ...(limit.remainingMinor != null ? { remainingMinor: limit.remainingMinor } : {}),
+    }]).policy
+  } catch {
+    return policy
+  }
+}
 
 export const AmountCheckoutDialog = ({
-  open, onOpenChange, policy, pending = false, onConfirm, estimate,
+  open, onOpenChange, policy: basePolicy, pending = false, onConfirm, estimate, limit, legalNote,
 }: AmountCheckoutDialogProps) => {
   const t = useI18nLib('web-payment', 'amount-checkout')
   const [locale] = useLanguage()
+  const policy = useMemo(() => effectivePolicyOf(basePolicy, limit), [basePolicy, limit])
+  const blocked = limit?.blocked === true
+  // The limit, not the plan, set the maximum — also when `policy` arrives already narrowed.
+  const limited = limit != null && limit.narrowed && limit.maximumMinor <= policy.maximumMinor
   const [value, setValue] = useState(() => inputAmount(policy.defaultMinor, locale))
   useEffect(() => {
     if (open) setValue(inputAmount(policy.defaultMinor, locale))
   }, [open, policy.defaultMinor, locale])
 
   const amountMinor = useMemo(() => parseAmountMinor(value, locale), [value, locale])
-  const error = amountMinor == null
-    ? t('invalid')
-    : amountMinor < policy.minimumMinor
-      ? t('below', { amount: money(policy.minimumMinor, policy.currency, locale) })
-      : amountMinor > policy.maximumMinor
-        ? t('above', { amount: money(policy.maximumMinor, policy.currency, locale) })
-        : null
-  const valid = error == null && amountMinor != null
+  const error = blocked
+    ? null
+    : amountMinor == null
+      ? t('invalid')
+      : amountMinor < policy.minimumMinor
+        ? t('below', { amount: money(policy.minimumMinor, policy.currency, locale) })
+        : amountMinor > policy.maximumMinor
+          ? t(limited ? 'above-limit' : 'above', { amount: money(policy.maximumMinor, policy.currency, locale) })
+          : null
+  const valid = !blocked && error == null && amountMinor != null
   const chargeMinor = valid ? chargeAmountMinor(amountMinor, policy) : 0
   const adjustmentMinor = valid && amountMinor != null ? chargeMinor - amountMinor : 0
+  const locked = pending || blocked
   const submit = async () => {
-    if (amountMinor == null || !valid || pending) return
+    if (amountMinor == null || !valid || locked) return
     assertCheckoutAmount(policy, amountMinor)
     await onConfirm(amountMinor, estimate?.country)
   }
 
   return <Dialog open={open} onOpenChange={onOpenChange}>
-    <DialogContent closeLabel={t('close')}>
+    <DialogContent closeLabel={t('close')} data-amount-checkout="" data-blocked={blocked ? 'true' : 'false'}>
       <DialogHeader>
         <DialogTitle>{t('title')}</DialogTitle>
         <DialogDescription>{t('description')}</DialogDescription>
       </DialogHeader>
       <div className="grid gap-5">
-        <div className="grid grid-cols-2 gap-2 sm:grid-cols-4" aria-label={t('presets')}>
+        {limit != null && <CheckoutLimitNote limit={limit} />}
+        {policy.presetsMinor.length > 0 && <div className="grid grid-cols-2 gap-2 sm:grid-cols-4" aria-label={t('presets')}>
           {policy.presetsMinor.map(preset => <Button
-            key={preset} type="button" variant={preset === amountMinor ? 'default' : 'outline'}
-            disabled={pending} onClick={() => setValue(inputAmount(preset, locale))}
+            key={preset} type="button" variant={preset === amountMinor ? 'default' : 'outline'} data-amount-preset={preset}
+            disabled={locked} onClick={() => setValue(inputAmount(preset, locale))}
           >{money(preset, policy.currency, locale)}</Button>)}
-        </div>
+        </div>}
         <div className="grid gap-2">
           <Label htmlFor="payment-amount">{t('custom')}</Label>
           <Input
             id="payment-amount" inputMode="decimal" autoComplete="off" value={value}
-            disabled={pending} aria-invalid={error != null} aria-describedby="payment-amount-help"
+            disabled={locked} aria-invalid={error != null} aria-describedby="payment-amount-help"
             onChange={event => setValue(event.target.value)}
           />
-          <p id="payment-amount-help" className={error == null ? 'text-muted-foreground text-xs' : 'text-destructive text-xs'}>
+          {!blocked && <p id="payment-amount-help" className={error == null ? 'text-muted-foreground text-xs' : 'text-destructive text-xs'}>
             {error ?? t('bounds', {
               minimum: money(policy.minimumMinor, policy.currency, locale),
               maximum: money(policy.maximumMinor, policy.currency, locale),
             })}
-          </p>
+          </p>}
         </div>
         <dl className="grid grid-cols-[1fr_auto] gap-x-4 gap-y-2 rounded-lg border bg-muted/30 p-4 text-sm">
           <dt className="text-muted-foreground">{t('credits')}</dt><dd>{valid && amountMinor != null ? money(amountMinor, policy.currency, locale) : '—'}</dd>
@@ -77,10 +104,13 @@ export const AmountCheckoutDialog = ({
         {estimate != null
           ? valid && <PriceEstimateSummary control={estimate} subtotalMinor={chargeMinor} currency={policy.currency} />
           : <p className="text-muted-foreground text-xs">{t('tax-note')}</p>}
+        {legalNote != null && <div className="text-muted-foreground text-xs" data-legal-note="">{legalNote}</div>}
       </div>
       <DialogFooter>
         <Button type="button" variant="outline" disabled={pending} onClick={() => onOpenChange(false)}>{t('cancel')}</Button>
-        <Button type="button" disabled={!valid || pending} onClick={() => void submit()}>{pending ? t('pending') : t('continue')}</Button>
+        <Button type="button" data-amount-confirm="" disabled={!valid || locked} onClick={() => void submit()}>
+          {pending ? t('pending') : t('continue')}
+        </Button>
       </DialogFooter>
     </DialogContent>
   </Dialog>

package/src/estimate-summary.tsx

@@ -1,15 +1,12 @@
-import { Fragment, useMemo } from 'react'
+import { Fragment, useMemo, type ReactNode } from 'react'
 import { useI18nLib, useLanguage } from '@owlmeans/client-i18n'
 import { COUNTRY_CODES, TaxEstimateStatus, estimateOf } from '@owlmeans/payment'
 import { cn } from '@/lib/utils'
 import { Label } from '@/components/ui/label'
 import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/components/ui/select'
+import { money } from './format.js'
 import type { PriceEstimateControl } from './types.js'
 
-const money = (minor: number, currency: string, locale: string): string => new Intl.NumberFormat(locale, {
-  style: 'currency', currency: currency.toUpperCase(), minimumFractionDigits: 2,
-}).format(minor / 100)
-
 const localMoney = (amount: number, currency: string, locale: string): string => {
   try {
     return new Intl.NumberFormat(locale, { style: 'currency', currency: currency.toUpperCase() }).format(amount)
@@ -36,6 +33,10 @@ export interface CountrySelectProps {
   label?: string
   id?: string
   className?: string
+  /** The country cannot be changed here — a billing country locked by the first purchase. */
+  disabled?: boolean
+  /** A line under the picker — why it is disabled, typically. */
+  note?: ReactNode
 }
 
 /**
@@ -43,25 +44,32 @@ export interface CountrySelectProps {
  * self-contained estimate, and what a shared picker (several estimates, one country — a plan
  * comparison table) renders once and drives every `usePriceEstimate({ country, onCountryChange })`
  * with. Country names are the viewer's own language, alphabetically ordered.
+ *
+ * `[data-country-select]` carries `data-locked` (`"true"` while disabled) and the chosen
+ * `data-country`; the note is `[data-country-note]`.
  */
-export const CountrySelect = ({ value, onChange, label, id = 'price-estimate-country', className }: CountrySelectProps) => {
+export const CountrySelect = ({
+  value, onChange, label, id = 'price-estimate-country', className, disabled = false, note,
+}: CountrySelectProps) => {
   const t = useI18nLib('web-payment', 'estimate')
   const [locale] = useLanguage()
   const countries = useCountryOptions(locale)
   const text = label ?? t('country')
 
-  return <div className={cn('grid gap-2', className)}>
+  return <div className={cn('grid gap-2', className)} data-country-select="" data-locked={disabled ? 'true' : 'false'}
+    data-country={value}>
     <Label htmlFor={id}>{text}</Label>
     {/* Always controlled, `''` included (no `SelectItem` ever has that value) — switching to
         `undefined` once a country is chosen is what trips React's controlled/uncontrolled warning. */}
-    <Select value={value} onValueChange={onChange}>
-      <SelectTrigger id={id} aria-label={text}>
+    <Select value={value} onValueChange={next => { if (!disabled) onChange(next) }} disabled={disabled}>
+      <SelectTrigger id={id} aria-label={text} aria-describedby={note != null ? `${id}-note` : undefined}>
         <SelectValue placeholder={t('country-placeholder')} />
       </SelectTrigger>
       <SelectContent>
         {countries.map(({ code, name }) => <SelectItem key={code} value={code}>{name}</SelectItem>)}
       </SelectContent>
     </Select>
+    {note != null && <p id={`${id}-note`} className="text-muted-foreground text-xs" data-country-note="">{note}</p>}
   </div>
 }
 
@@ -153,10 +161,12 @@ export interface PriceEstimateSummaryProps {
  * estimates sharing one picker (a plan comparison table) compose the two pieces separately instead.
  */
 export const PriceEstimateSummary = ({ control, subtotalMinor, currency, suffix, className }: PriceEstimateSummaryProps) => {
-  const { country, onCountryChange } = control
+  const t = useI18nLib('web-payment', 'estimate')
+  const { country, onCountryChange, locked = false } = control
 
   return <div className={cn('grid gap-3', className)}>
-    <CountrySelect value={country} onChange={onCountryChange} />
+    <CountrySelect value={country} onChange={onCountryChange} disabled={locked}
+      note={locked ? t('country-locked') : undefined} />
     <PriceEstimateAmount control={control} subtotalMinor={subtotalMinor} currency={currency} suffix={suffix} />
   </div>
 }

package/src/estimate.ts

@@ -32,6 +32,10 @@ export interface UsePriceEstimateOptions {
  * in-flight request is shared. Uncontrolled (no `opts.country`): the first answer whose `source` is
  * `'customer'` preselects its `country`, once, so a returning buyer sees their own country without
  * picking it. Controlled (`opts.country` given): the country and its preselection are the caller's.
+ *
+ * An answer for a LOCKED billing country (`locked`, or `source: 'profile'`) wins over any pick: the
+ * hook adopts its country (controlled: through `opts.onCountryChange`, once), returns `locked:
+ * true`, and ignores `onCountryChange` from then on — the picker renders disabled.
  */
 export const usePriceEstimate = <Request extends PriceEstimateRequest>(
   entry: RegisteredEntrypoint<Request, PriceEstimate>, opts: UsePriceEstimateOptions,
@@ -49,6 +53,11 @@ export const usePriceEstimate = <Request extends PriceEstimateRequest>(
   const [loading, setLoading] = useState(false)
   const [failed, setFailed] = useState(false)
   const preselectedRef = useRef(false)
+  const lockedRef = useRef(false)
+  const locked = estimate != null && isLockedAnswer(estimate)
+  lockedRef.current = locked
+  const onCountryChangeRef = useRef(opts.onCountryChange)
+  onCountryChangeRef.current = opts.onCountryChange
 
   useEffect(() => {
     if (!opts.enabled) {
@@ -65,6 +74,16 @@ export const usePriceEstimate = <Request extends PriceEstimateRequest>(
       if (!active) return
       setEstimate(result)
       setLoading(false)
+      if (isLockedAnswer(result) && result.country != null && result.country !== country) {
+        // A locked billing country overrides whatever was picked: adopt it, once per country.
+        preselectedRef.current = true
+        if (controlled) {
+          onCountryChangeRef.current?.(result.country)
+        } else {
+          setInternalCountry(result.country)
+        }
+        return
+      }
       if (!controlled && !preselectedRef.current && country === '' && result.source === 'customer' && result.country != null) {
         preselectedRef.current = true
         setInternalCountry(result.country)
@@ -80,6 +99,9 @@ export const usePriceEstimate = <Request extends PriceEstimateRequest>(
   }, [opts.enabled, opts.ttlMs, bodyKey, country])
 
   const onCountryChange = useCallback((next: string) => {
+    if (lockedRef.current) {
+      return
+    }
     if (controlled) {
       opts.onCountryChange?.(next)
       return
@@ -89,5 +111,9 @@ export const usePriceEstimate = <Request extends PriceEstimateRequest>(
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [controlled, opts.onCountryChange])
 
-  return { estimate, country, loading, failed, onCountryChange }
+  return { estimate, country, loading, failed, locked, onCountryChange }
 }
+
+/** An answer computed for the entity's locked billing country, which no picker may change. */
+export const isLockedAnswer = (estimate: PriceEstimate): boolean =>
+  estimate.locked === true || estimate.source === 'profile'

package/src/format.ts

@@ -0,0 +1,71 @@
+import { lastWithdrawalDayOf } from '@owlmeans/payment'
+
+/** Minor units as a currency amount in a locale; an unknown locale or currency still reads. */
+export const money = (minor: number, currency: string, locale: string): string => {
+  try {
+    return new Intl.NumberFormat(locale, {
+      style: 'currency', currency: currency.toUpperCase(), minimumFractionDigits: 2,
+    }).format(minor / 100)
+  } catch {
+    return `${(minor / 100).toFixed(2)} ${currency.toUpperCase()}`
+  }
+}
+
+const dateOf = (date: Date | string | null | undefined): Date | null => {
+  if (date == null) {
+    return null
+  }
+  const value = date instanceof Date ? date : new Date(date)
+
+  return Number.isNaN(value.getTime()) ? null : value
+}
+
+/** A calendar day in UTC (`dateStyle: 'long'`); `''` for no or an unparseable date. */
+export const dayUtc = (date: Date | string | null | undefined, locale: string): string => {
+  const value = dateOf(date)
+  if (value == null) {
+    return ''
+  }
+  try {
+    return new Intl.DateTimeFormat(locale, { dateStyle: 'long', timeZone: 'UTC' }).format(value)
+  } catch {
+    return value.toISOString().slice(0, 10)
+  }
+}
+
+/**
+ * The last day of a window whose deadline is EXCLUSIVE (the start of the next UTC day) — the day a
+ * consumer reads as "until". The rule is `@owlmeans/payment`'s `lastWithdrawalDayOf`, the one the
+ * server's e-mails and texts use, so the dialog and the mail never name different days.
+ */
+export const lastDayUtc = (deadline: Date | string | null | undefined, locale: string): string => {
+  const value = dateOf(deadline)
+
+  return value == null ? '' : dayUtc(lastWithdrawalDayOf(value), locale)
+}
+
+/** A date and time in UTC, to the second — the moment a declaration was received. */
+export const momentUtc = (date: Date | string | null | undefined, locale: string): string => {
+  const value = dateOf(date)
+  if (value == null) {
+    return ''
+  }
+  try {
+    return new Intl.DateTimeFormat(locale, { dateStyle: 'long', timeStyle: 'medium', timeZone: 'UTC' }).format(value)
+  } catch {
+    return value.toISOString().replace('T', ' ').slice(0, 19)
+  }
+}
+
+/** A date and time in UTC to the minute, with the zone named — when a limit rises again. */
+export const shortMomentUtc = (date: Date | string | null | undefined, locale: string): string => {
+  const value = dateOf(date)
+  if (value == null) {
+    return ''
+  }
+  try {
+    return `${new Intl.DateTimeFormat(locale, { dateStyle: 'medium', timeStyle: 'short', timeZone: 'UTC' }).format(value)} UTC`
+  } catch {
+    return `${value.toISOString().replace('T', ' ').slice(0, 16)} UTC`
+  }
+}