@shoppexio/storefront-react 0.4.0 → 0.5.0

package/eject/account/subscriptions.tsx

@@ -14,6 +14,12 @@
  * its own email code before it mints the portal session; the producer's
  * `can_manage_payment_method` decides whether it shows.
  *
+ * Pausing asks first (Design Batch 4, feature 6): a small card with the lengths
+ * and resume dates the producer offers in `pause_options`, a reason only when
+ * the shop asks for one, and "Pause until {date}". A running or scheduled pause
+ * and the yearly limit are read from `pause` and `pause_limit`; "Don't pause"
+ * calls off a scheduled pause through the resume route.
+ *
  * List and detail are two views of one panel. The platform defines a detail
  * path for orders and for nothing else, so a `/dashboard/subscriptions/<id>`
  * URL would be this template inventing platform route shape; the selection
@@ -22,16 +28,33 @@
 
 import { useState, type ReactNode } from 'react';
 import { Link } from 'react-router-dom';
+import { accountOrderHref } from '@shoppexio/storefront-react';
 import {
+  billingEntryDays,
+  billingEntryTitle,
   billingMessage,
   cancelsAtPeriodEnd,
+  defaultPauseLength,
+  endedAfterHold,
+  endedNoteKey,
   narrowBillingHistory,
+  noteIntervalKey,
+  openRenewalState,
+  pausesLeftMessage,
+  renewalDate,
+  resumeBillsToday,
+  type OpenRenewalState,
   subscriptionTiming,
   subscriptionTimingKey,
 } from './account-subscriptions';
 import { callCustomerApi, safeExternalHref } from './customer-account';
 import { hostedPageHref } from './hosted-page';
-import type { SdkCustomerSubscription } from '@shoppexio/storefront-react';
+import type {
+  SdkCustomerOpenRenewal,
+  SdkCustomerPauseOptions,
+  SdkCustomerPauseReason,
+  SdkCustomerSubscription,
+} from '@shoppexio/storefront-react';
 import { t } from './i18n';
 import { CircleAlertIcon } from './icons';
 import { useAccountDashboard } from './dashboard';
@@ -45,6 +68,7 @@ import {
   AccountSectionTitle,
   BusySpinner,
   HostedPageLink,
+  InvoiceStatusChip,
   StatusChip,
   formatAccountAmount,
   formatAccountDate,
@@ -127,7 +151,7 @@ export function AccountSubscriptions() {
                 {formatAccountAmount(subscription.plan.price, subscription.plan.currency)}
               </span>
             ) : null}
-            <StatusChip status={subscription.status} />
+            <SubscriptionStatus subscription={subscription} />
           </button>
           <RenewalDue subscription={subscription} className="sxa:mt-2" />
         </li>
@@ -160,14 +184,19 @@ function SubscriptionDetail({
   onBack: () => void;
   onChanged: (message: string) => void;
 }) {
-  const [pendingAction, setPendingAction] = useState<'pause' | 'resume' | 'cancel' | null>(null);
+  const [pendingAction, setPendingAction] = useState<'pause' | 'resume' | 'unpause' | 'cancel' | null>(null);
   const [confirmingCancel, setConfirmingCancel] = useState(false);
+  const [pausing, setPausing] = useState(false);
   const [actionError, setActionError] = useState<string | null>(null);
 
   const atPeriodEnd = cancelsAtPeriodEnd(subscription.gateway);
+  // Pause opens the dialog, so it needs the lengths the producer offers; an SDK
+  // older than the pause policy strips them, and then nothing is offered.
+  const pauseOptions = subscription.actions.can_pause ? subscription.pause_options ?? null : null;
+  const scheduledPause = subscription.pause?.state === 'scheduled';
 
   const run = async (
-    action: 'pause' | 'resume' | 'cancel',
+    action: 'resume' | 'unpause' | 'cancel',
     call: () => Promise<{ success: boolean; message?: string }>,
     doneMessage: string,
   ) => {
@@ -200,13 +229,14 @@ function SubscriptionDetail({
             {t('subscriptions.startedOn', { date: formatAccountDate(subscription.created_at) })}
           </p>
         </div>
-        <StatusChip status={subscription.status} />
+        <SubscriptionStatus subscription={subscription} />
       </div>
 
       {notice ? <AccountNotice message={notice} /> : null}
       {actionError ? <div className="sxa:mt-3"><AccountError message={actionError} /></div> : null}
 
       <RenewalDue subscription={subscription} className="sxa:mt-3" />
+      <PauseState subscription={subscription} />
 
       {subscription.status === 'PAST_DUE' && subscription.actions.can_manage_payment_method ? (
         <PastDueCard subscription={subscription} />
@@ -256,37 +286,36 @@ function SubscriptionDetail({
         control still promises that pressing it would have worked.
       */}
       <div className="sxa:mt-6 sxa:flex sxa:flex-wrap sxa:gap-2">
-        {subscription.actions.can_pause ? (
+        {pauseOptions && !pausing ? (
           <button
             type="button"
             disabled={pendingAction !== null}
-            aria-busy={pendingAction === 'pause' || undefined}
             className="sx-account-button sxa:card-button sxa:card-button--add sxa:disabled:cursor-not-allowed sxa:disabled:opacity-50"
-            onClick={() => void run(
-              'pause',
-              () => callCustomerApi((sdk) => sdk.pauseSubscription(subscription.uniqid)),
-              t('subscriptions.paused'),
-            )}
+            onClick={() => {
+              setConfirmingCancel(false);
+              setActionError(null);
+              setPausing(true);
+            }}
           >
-            {pendingAction === 'pause' ? <BusySpinner className="sxa:mr-1.5 sxa:h-3.5 sxa:w-3.5" /> : null}
-            {pendingAction === 'pause' ? t('subscriptions.pausing') : t('subscriptions.pause')}
+            {t('subscriptions.pause')}
           </button>
         ) : null}
 
+        {/* `can_resume` is "Resume now" on a paused plan and "Don't pause" on a scheduled pause. */}
         {subscription.actions.can_resume ? (
           <button
             type="button"
             disabled={pendingAction !== null}
-            aria-busy={pendingAction === 'resume' || undefined}
+            aria-busy={pendingAction === 'resume' || pendingAction === 'unpause' || undefined}
             className="sx-account-button sxa:card-button sxa:card-button--add sxa:disabled:cursor-not-allowed sxa:disabled:opacity-50"
             onClick={() => void run(
-              'resume',
+              scheduledPause ? 'unpause' : 'resume',
               () => callCustomerApi((sdk) => sdk.resumeSubscription(subscription.uniqid)),
-              t('subscriptions.resumed'),
+              scheduledPause ? t('subscriptions.pauseCalledOff') : t('subscriptions.resumed'),
             )}
           >
-            {pendingAction === 'resume' ? <BusySpinner className="sxa:mr-1.5 sxa:h-3.5 sxa:w-3.5" /> : null}
-            {pendingAction === 'resume' ? t('subscriptions.resuming') : t('subscriptions.resume')}
+            {pendingAction === 'resume' || pendingAction === 'unpause' ? <BusySpinner className="sxa:mr-1.5 sxa:h-3.5 sxa:w-3.5" /> : null}
+            {pendingAction === 'resume' ? t('subscriptions.resuming') : scheduledPause ? t('subscriptions.dontPause') : t('subscriptions.resumeNow')}
           </button>
         ) : null}
 
@@ -295,13 +324,42 @@ function SubscriptionDetail({
             type="button"
             disabled={pendingAction !== null}
             className="sx-account-button sxa:card-button sxa:card-button--add sxa:disabled:cursor-not-allowed sxa:disabled:opacity-50"
-            onClick={() => setConfirmingCancel(true)}
+            onClick={() => {
+              setPausing(false);
+              setConfirmingCancel(true);
+            }}
           >
             {t('subscriptions.cancel')}
           </button>
         ) : null}
       </div>
 
+      {subscription.pause_limit ? (
+        <p className="sxa:mt-3 sxa:text-small sxa:text-muted">
+          {subscription.pause_limit.pauses_per_year === 1
+            ? t('subscriptions.pauseLimitOne', { date: formatAccountDate(subscription.pause_limit.available_again_at) })
+            : t('subscriptions.pauseLimit', {
+              count: subscription.pause_limit.pauses_per_year,
+              date: formatAccountDate(subscription.pause_limit.available_again_at),
+            })}
+        </p>
+      ) : null}
+
+      {pausing && pauseOptions ? (
+        <PauseDialog
+          key={subscription.uniqid}
+          subscription={subscription}
+          options={pauseOptions}
+          busy={pendingAction !== null}
+          onBusy={(busy) => setPendingAction(busy ? 'pause' : null)}
+          onClose={() => setPausing(false)}
+          onPaused={() => {
+            setPausing(false);
+            onChanged(t('subscriptions.pauseSavedNotice'));
+          }}
+        />
+      ) : null}
+
       {/*
         Cancelling asks first, and the question names what cancelling does on
         THIS gateway. PayPal cannot stop a billing agreement at the period
@@ -353,34 +411,185 @@ function SubscriptionDetail({
 }
 
 /**
- * A renewal payment that is due, and the way to pay it.
- *
- * `renewal_checkout_url` is the hosted checkout of the renewal invoice the
- * server already opened, so this is a plain link: following it creates
- * nothing, and no call is made from here. No URL means nothing is due and
- * nothing is shown; a URL that fails the scheme check gets no anchor, only the
- * sentence, because the payment is still due.
+ * An open renewal, and the way to pay it: on hold, due, or invoiced ahead.
+ * The producer names the invoice's hosted checkout in `open_renewal`, so this
+ * is a plain link, never a call: paying is a purchase, and purchases carry
+ * their authorisation in checkout (ADR-0064). Nothing open (or a backend that
+ * does not send the field yet), nothing shown. A URL that fails the scheme check
+ * gets no anchor, only the sentence, because the payment is still due.
  */
 function RenewalDue({ subscription, className }: { subscription: SdkCustomerSubscription; className: string }) {
-  const url = subscription.renewal_checkout_url ?? null;
-  if (url === null) return null;
-  const href = safeExternalHref(url);
+  const ended = endedAfterHold(subscription);
+  if (ended) {
+    return (
+      <AccountCard className={`${className} sxa:px-5 sxa:py-3`}>
+        <p className="sxa:text-small">{t(endedNoteKey(ended))}</p>
+      </AccountCard>
+    );
+  }
+  const state = openRenewalState(subscription);
+  const open = subscription.open_renewal;
+  if (state === null || !open) return null;
+  const href = safeExternalHref(open.pay_url);
+  const { note, payLabel } = renewalCopy(subscription, state, open);
 
   return (
     <AccountCard className={`${className} sxa:flex sxa:flex-wrap sxa:items-center sxa:justify-between sxa:gap-3 sxa:px-5 sxa:py-3`}>
-      <p className="sxa:min-w-0 sxa:text-small">{t('subscriptions.renewalDue')}</p>
+      <p className="sxa:min-w-0 sxa:text-small">{note}</p>
       {href === null ? null : (
         <a
           href={href}
           className="sx-account-cta sxa:cta-button sxa:inline-flex sxa:h-9 sxa:shrink-0 sxa:items-center sxa:px-4 sxa:text-small sxa:font-semibold"
         >
-          {t('subscriptions.payNow')}
+          {payLabel}
         </a>
       )}
     </AccountCard>
   );
 }
 
+const PAUSE_LENGTH_KEYS: Readonly<Record<SdkCustomerPauseOptions['lengths'][number]['days'], string>> = {
+  7: 'subscriptions.pauseLength7',
+  14: 'subscriptions.pauseLength14',
+  30: 'subscriptions.pauseLength30',
+  60: 'subscriptions.pauseLength60',
+  90: 'subscriptions.pauseLength90',
+};
+
+/** `SUBSCRIPTION_PAUSE_REASONS`, in the producer's order, with their buyer labels. */
+const PAUSE_REASONS: ReadonlyArray<readonly [SdkCustomerPauseReason, string]> = [
+  ['taking_a_break', 'subscriptions.pauseReasonTakingABreak'],
+  ['too_expensive', 'subscriptions.pauseReasonTooExpensive'],
+  ['not_using', 'subscriptions.pauseReasonNotUsing'],
+  ['not_working', 'subscriptions.pauseReasonNotWorking'],
+  ['other', 'subscriptions.pauseReasonOther'],
+];
+
+/**
+ * The pause dialog: the lengths the producer offers, each with its resume date, a reason
+ * when the shop asks for one, and what the pause means. A failure keeps the dialog and
+ * says nothing changed; the buyer tries again from here.
+ */
+function PauseDialog({
+  subscription,
+  options,
+  busy,
+  onBusy,
+  onClose,
+  onPaused,
+}: {
+  subscription: SdkCustomerSubscription;
+  options: SdkCustomerPauseOptions;
+  busy: boolean;
+  onBusy: (busy: boolean) => void;
+  onClose: () => void;
+  onPaused: () => void;
+}) {
+  const [days, setDays] = useState(() => defaultPauseLength(options));
+  const [reason, setReason] = useState<SdkCustomerPauseReason | ''>('');
+  const [failed, setFailed] = useState(false);
+  const length = options.lengths.find((entry) => entry.days === days) ?? null;
+  const start = formatAccountDate(options.starts_at);
+  const startsLater = Date.parse(options.starts_at) > Date.now();
+  const left = pausesLeftMessage(options.pauses_left_after);
+
+  const confirm = async () => {
+    if (!length) return;
+    onBusy(true);
+    setFailed(false);
+    const result = await callCustomerApi((sdk) => sdk.pauseSubscription(subscription.uniqid, {
+      length_days: length.days,
+      ...(options.reason_enabled && reason !== '' ? { reason } : {}),
+    }));
+    onBusy(false);
+    if (!result.success) {
+      setFailed(true);
+      return;
+    }
+    onPaused();
+  };
+
+  return (
+    <AccountCard className="sxa:mt-4 sxa:p-6">
+      <p className="sxa:font-heading sxa:font-semibold">
+        {t('subscriptions.pauseTitle', { plan: subscription.plan?.name ?? t('subscriptions.unnamedPlan') })}
+      </p>
+      {startsLater ? (
+        <p className="sxa:mt-2 sxa:text-small sxa:text-muted">{t('subscriptions.pauseStartsAfter', { date: start })}</p>
+      ) : null}
+
+      <p className="sxa:mt-4 sxa:text-small sxa:font-semibold">{t('subscriptions.pauseHowLong')}</p>
+      <div className="sxa:mt-2 sxa:flex sxa:flex-wrap sxa:gap-2" role="radiogroup" aria-label={t('subscriptions.pauseHowLong')}>
+        {options.lengths.map((entry) => (
+          <button
+            key={entry.days}
+            type="button"
+            role="radio"
+            aria-checked={entry.days === days}
+            disabled={busy}
+            className={`sx-account-button sxa:card-button ${entry.days === days ? 'sxa:card-button--add' : ''} sxa:disabled:cursor-not-allowed sxa:disabled:opacity-50`}
+            onClick={() => setDays(entry.days)}
+          >
+            {t(PAUSE_LENGTH_KEYS[entry.days])}
+          </button>
+        ))}
+      </div>
+
+      {options.reason_enabled ? (
+        <label className="sxa:mt-4 sxa:block">
+          <span className="sxa:text-small sxa:font-semibold">{t('subscriptions.pauseReasonLabel')}</span>
+          <span className="sxa:text-small sxa:text-muted"> · {t('subscriptions.pauseOptional')}</span>
+          <select
+            value={reason}
+            disabled={busy}
+            onChange={(event) => setReason(PAUSE_REASONS.find(([value]) => value === event.target.value)?.[0] ?? '')}
+            className="sx-account-input sxa:mt-2 sxa:block sxa:w-full sxa:rounded-input sxa:border sxa:bg-surface sxa:px-3 sxa:py-2 sxa:text-small"
+          >
+            <option value="">{t('subscriptions.pauseReasonNone')}</option>
+            {PAUSE_REASONS.map(([value, key]) => <option key={value} value={value}>{t(key)}</option>)}
+          </select>
+        </label>
+      ) : null}
+
+      {length ? (
+        <ul className="sxa:mt-4 sxa:list-disc sxa:space-y-1 sxa:pl-5 sxa:text-small sxa:text-muted">
+          {[
+            t('subscriptions.pauseSummary', { start, end: formatAccountDate(length.resume_at) }),
+            pauseAccessLine(subscription),
+            t('subscriptions.pauseResumeAnyTime'),
+            t(left.key, left.params),
+          ].map((line) => <li key={line}>{line}</li>)}
+        </ul>
+      ) : null}
+
+      {failed ? <div className="sxa:mt-3"><AccountError message={t('subscriptions.pauseError')} /></div> : null}
+
+      <div className="sxa:mt-4 sxa:flex sxa:flex-wrap sxa:items-center sxa:gap-2">
+        {length ? (
+          <button
+            type="button"
+            disabled={busy}
+            aria-busy={busy || undefined}
+            className="sx-account-cta sxa:cta-button sxa:inline-flex sxa:h-8 sxa:items-center sxa:px-4 sxa:text-micro sxa:font-semibold sxa:disabled:cursor-not-allowed sxa:disabled:opacity-50"
+            onClick={() => void confirm()}
+          >
+            {busy ? <BusySpinner className="sxa:mr-1.5 sxa:h-3.5 sxa:w-3.5" /> : null}
+            {busy ? t('subscriptions.pausing') : t('subscriptions.pauseConfirm', { date: formatAccountDate(length.resume_at) })}
+          </button>
+        ) : null}
+        <button
+          type="button"
+          disabled={busy}
+          className="sx-account-button sxa:card-button sxa:card-button--add sxa:disabled:cursor-not-allowed sxa:disabled:opacity-50"
+          onClick={onClose}
+        >
+          {t('subscriptions.pauseKeep')}
+        </button>
+      </div>
+    </AccountCard>
+  );
+}
+
 /**
  * A past-due Stripe plan: the last charge failed, and the card is what to
  * change before the plan ends. The same hosted billing link as "Update card".
@@ -406,6 +615,63 @@ function PastDueCard({ subscription }: { subscription: SdkCustomerSubscription }
   );
 }
 
+/** What the pause takes: the Discord roles by name when the producer knows them, else "your access". */
+function pauseAccessLine(subscription: SdkCustomerSubscription): string {
+  const roles = subscription.pause_access_roles ?? [];
+  if (roles.length === 0) return t('subscriptions.pauseAccess');
+  return t(roles.length === 1 ? 'subscriptions.pauseAccessRole' : 'subscriptions.pauseAccessRoles', {
+    roles: roles.map((role) => `@${role}`).join(', '),
+  });
+}
+
+/** A running or scheduled pause, read from the producer's `pause`. */
+function PauseState({ subscription }: { subscription: SdkCustomerSubscription }) {
+  const pause = subscription.pause;
+  if (!pause || subscription.status.toUpperCase() === 'CANCELED') return null;
+  let title: string;
+  let body: string;
+  if (pause.state === 'scheduled') {
+    title = t('subscriptions.pauseScheduled', { date: formatAccountDate(pause.starts_at) });
+    body = pause.resume_at === null
+      ? t('subscriptions.pauseScheduledBodyOpenEnded')
+      : t('subscriptions.pauseScheduledBody', { date: formatAccountDate(pause.resume_at) });
+  } else {
+    title = pause.resume_at === null
+      ? t('subscriptions.pausedOpenEnded')
+      : t('subscriptions.pausedUntil', { date: formatAccountDate(pause.resume_at) });
+    const paused = `${t('subscriptions.pausedBody')} ${pauseAccessLine(subscription)}`;
+    body = subscription.plan && resumeBillsToday(subscription)
+      ? `${paused} ${t('subscriptions.pausedPayToday', {
+        price: formatAccountAmount(subscription.plan.price, subscription.plan.currency),
+      })}`
+      : paused;
+  }
+  return (
+    <AccountCard className="sxa:mt-3 sxa:px-5 sxa:py-3">
+      <p className="sxa:text-small sxa:font-semibold">{title}</p>
+      <p className="sxa:mt-0.5 sxa:text-small sxa:text-muted">{body}</p>
+    </AccountCard>
+  );
+}
+
+/** The subscription's status, or what its open renewal makes it: on hold, or payment due. */
+function SubscriptionStatus({ subscription }: { subscription: SdkCustomerSubscription }) {
+  const state = openRenewalState(subscription);
+  if (state === 'held') return <StatusChip status="PAST_DUE" label={t('subscriptions.statusOnHold')} />;
+  if (state === 'due') return <StatusChip status="PENDING" label={t('subscriptions.statusPaymentDue')} />;
+  return <StatusChip status={subscription.status} />;
+}
+
+/** The renewal note and the pay label for an open renewal. */
+function renewalCopy(subscription: SdkCustomerSubscription, state: OpenRenewalState, open: SdkCustomerOpenRenewal) {
+  const amount = formatAccountAmount(open.amount, open.currency);
+  const date = formatAccountDate(open.pay_by);
+  const renewal = formatAccountDate(renewalDate(subscription.current_period_end));
+  if (state === 'held') return { note: t('subscriptions.holdNote', { amount, date, interval: t(noteIntervalKey(open, 'hold')) }), payLabel: t('subscriptions.payAndResume', { amount }) };
+  const note = state === 'ready' ? t('subscriptions.readyNote', { renewal, interval: t(noteIntervalKey(open, 'ready')) }) : t('subscriptions.dueNote', { renewal, date });
+  return { note, payLabel: t('subscriptions.payAmount', { amount }) };
+}
+
 function DetailRow({ label, children }: { label: string; children: ReactNode }) {
   return (
     <div className="sxa:flex sxa:items-center sxa:justify-between sxa:gap-4">
@@ -439,7 +705,7 @@ function BillingHistory({ uniqid }: { uniqid: string }) {
   );
 }
 
-function BillingHistoryList({ payload, reload }: { payload: unknown; reload: () => void }) {
+export function BillingHistoryList({ payload, reload }: { payload: unknown; reload: () => void }) {
   const history = narrowBillingHistory(payload);
 
   /*
@@ -460,21 +726,33 @@ function BillingHistoryList({ payload, reload }: { payload: unknown; reload: ()
     );
   }
 
+  // Each row says what it billed and opens its order in the account, where the receipt is (Design Batch 9, C3).
   return (
     <ul className="sxa:space-y-4">
-      {history.invoices.map((invoice) => (
-        <li key={invoice.uniqid} className="sxa:flex sxa:items-center sxa:gap-4 sxa:rounded-input sxa:border sxa:bg-surface sxa:p-5 sxa:shadow-card">
-          <div className="sxa:min-w-0 sxa:flex-1">
-            <p className="sxa:truncate sxa:text-small sxa:font-semibold sxa:tabular-nums">
-              {formatAccountAmount(invoice.total, invoice.currency)}
-            </p>
-            <p className="sxa:mt-1 sxa:truncate sxa:text-micro sxa:text-muted">
-              {formatAccountDate(invoice.created_at)}
-            </p>
-          </div>
-          <StatusChip status={invoice.status} />
-        </li>
-      ))}
+      {history.invoices.map((invoice) => {
+        const title = billingEntryTitle(invoice);
+        const days = billingEntryDays(invoice);
+        return (
+          <li key={invoice.uniqid}>
+            <Link
+              to={accountOrderHref(invoice.uniqid)}
+              className="sxa:flex sxa:items-center sxa:gap-4 sxa:rounded-input sxa:border sxa:bg-surface sxa:p-5 sxa:shadow-card sxa:transition-opacity sxa:hover:opacity-80"
+            >
+              <div className="sxa:min-w-0 sxa:flex-1">
+                <p className="sxa:text-small sxa:font-semibold">{t(title.key, title.params)}</p>
+                <p className="sxa:mt-1 sxa:text-micro sxa:tabular-nums sxa:text-muted">
+                  {formatAccountDate(invoice.created_at)}
+                  {days ? ` · ${t(days.key, days.params)}` : null}
+                </p>
+              </div>
+              <div className="sxa:flex sxa:shrink-0 sxa:flex-col sxa:items-end sxa:gap-1.5 sxa:sm:flex-row sxa:sm:items-center sxa:sm:gap-3">
+                <span className="sxa:text-small sxa:font-semibold sxa:tabular-nums">{formatAccountAmount(invoice.total, invoice.currency)}</span>
+                <InvoiceStatusChip status={invoice.status} />
+              </div>
+            </Link>
+          </li>
+        );
+      })}
     </ul>
   );
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shoppexio/storefront-react",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "React hooks, models and a customer account for Shoppex code storefronts",
   "type": "module",
   "homepage": "https://docs.shoppex.io/storefront/code-storefront-development",