@shoppexio/storefront-react 0.0.0 → 0.1.1

package/eject/account/shared.tsx

@@ -0,0 +1,398 @@
+/**
+ * The pieces every account panel needs.
+ *
+ * Every class here is an `sxa:` utility compiled into `account.css`, and every
+ * value those utilities read is one of the host theme's `--sx-*` custom
+ * properties: cards are `rounded-input border bg-surface shadow-card`, inner
+ * tiles `bg-bg`, secondary text `text-muted`. The account has no palette of its
+ * own. The `sx-account-*` classes carry no styles; they are the hooks a theme
+ * restyles through.
+ *
+ * Loading, empty and failed all render something a buyer can act on, and none
+ * of them invents a value the producer did not send.
+ */
+
+import { useCallback, useEffect, useRef, useState, type ReactNode } from 'react';
+import { Link } from 'react-router-dom';
+import { toPanelState, type AccountPanelState } from './customer-account';
+import type { SdkResponse } from '@shoppexio/storefront-react';
+import { getActiveLocale, t, tOptional } from './i18n';
+import {
+  ArrowLeftIcon,
+  CheckIcon,
+  CircleAlertIcon,
+  CopyIcon,
+  LoaderIcon,
+} from './icons';
+
+/**
+ * Loads one panel's data and keeps the three states apart.
+ *
+ * `key` is what the load depends on: the page number for the order list, the
+ * order id for a detail view. A response that arrives after the key changed is
+ * dropped, so a slow request cannot overwrite the panel the buyer is now on.
+ */
+export function useAccountResource<T>(
+  key: string,
+  load: () => Promise<SdkResponse<T>>,
+  options: {
+    /**
+     * Keep ready data when a same-key re-read fails, carrying the error as
+     * `staleMessage` — ONLY for consumers that render that field (the points
+     * section, and the shell read it revalidates). Everything else keeps the
+     * plain contract: a failed re-read is an error state with a retry, shown
+     * where ready data was.
+     */
+    keepStale?: boolean;
+  } = {},
+): { state: AccountPanelState<T>; reload: () => void } {
+  const [state, setState] = useState<AccountPanelState<T>>({ status: 'loading' });
+  const [attempt, setAttempt] = useState(0);
+  const loadRef = useRef(load);
+  loadRef.current = load;
+  const keepStaleRef = useRef(options.keepStale === true);
+  keepStaleRef.current = options.keepStale === true;
+
+  /*
+   * Back to loading DURING the render that changed the key, not in the effect
+   * afterwards.
+   *
+   * An effect runs after the render commits, so for one render this hook still
+   * handed out the PREVIOUS key's finished data. A panel mounted on it, started
+   * its own nested reads, was torn down when the effect finally set loading,
+   * and started every one of those reads again when the new data arrived — five
+   * duplicated requests on the wholesale panel. React's documented way to reset
+   * state when an input changes is to do it while rendering, which is what this
+   * is; the extra render it schedules happens before anything is shown.
+   *
+   * A bumped ATTEMPT on the same key is a different thing and is not reset: it
+   * re-reads the subject already on screen. Blanking finished data for the
+   * length of that read empties the panel one frame after the buyer acted on
+   * it — the points section taking its own "credited" notice down with it — so
+   * ready data stays until the new answer replaces it. Only a key change, or a
+   * re-read of something that never finished, goes back to loading.
+   */
+  const token = `${key}::${attempt}`;
+  const [rendered, setRendered] = useState({ token, key });
+  if (token !== rendered.token) {
+    setRendered({ token, key });
+    if (key !== rendered.key || state.status !== 'ready') setState({ status: 'loading' });
+  }
+
+  useEffect(() => {
+    let active = true;
+
+    loadRef.current()
+      .then((response) => {
+        if (!active) return;
+        // A failed RE-read keeps what the buyer is looking at — ready data
+        // only exists here for a same-key revalidation (a key change went back
+        // to loading above), and replacing it with an error tears down the
+        // panel that just acted. But it does not stay silent: the retained
+        // figures are marked stale, so the panel can say they may be out of
+        // date. The first read of a key still surfaces its error normally.
+        setState((previous) => {
+          const next = toPanelState(response);
+          if (next.status === 'error' && previous.status === 'ready') {
+            return keepStaleRef.current ? { ...previous, staleMessage: next.message } : next;
+          }
+          return next;
+        });
+      })
+      .catch((error: unknown) => {
+        if (!active) return;
+        const message = error instanceof Error ? error.message : String(error);
+        setState((previous) => (previous.status === 'ready' && keepStaleRef.current
+          ? { ...previous, staleMessage: message }
+          : { status: 'error', message }));
+      });
+
+    return () => {
+      active = false;
+    };
+  }, [token]);
+
+  return { state, reload: useCallback(() => setAttempt((value) => value + 1), []) };
+}
+
+/**
+ * An invoice amount, in the currency the buyer sees.
+ *
+ * `currency` is the BUYER display currency and `total` is the USD-normalized
+ * aggregate, so the two are not a pair. `totalDisplay` is the same total in
+ * that currency and is what to render; the producer documents
+ * `total_display ?? total` as the rule, and this is the only place the template
+ * applies it.
+ */
+export function formatInvoiceAmount(
+  displayAmount: string | null,
+  normalizedAmount: string,
+  currency: string,
+): string {
+  return formatAccountAmount(displayAmount ?? normalizedAmount, currency);
+}
+
+export function formatAccountAmount(amount: string, currency: string): string {
+  const value = Number(amount);
+  if (!Number.isFinite(value)) return amount;
+  try {
+    return new Intl.NumberFormat(getActiveLocale(), {
+      style: 'currency',
+      currency: currency || 'USD',
+    }).format(value);
+  } catch {
+    // An unknown currency code is the shop's, not ours to correct.
+    return `${amount} ${currency}`.trim();
+  }
+}
+
+export function formatAccountDate(value: string | Date): string {
+  const date = value instanceof Date ? value : new Date(value);
+  if (Number.isNaN(date.getTime())) return typeof value === 'string' ? value : '';
+  return new Intl.DateTimeFormat(getActiveLocale(), {
+    year: 'numeric',
+    month: 'short',
+    day: 'numeric',
+  }).format(date);
+}
+
+export function formatAccountDateTime(value: string | Date): string {
+  const date = value instanceof Date ? value : new Date(value);
+  if (Number.isNaN(date.getTime())) return typeof value === 'string' ? value : '';
+  return new Intl.DateTimeFormat(getActiveLocale(), {
+    dateStyle: 'medium',
+    timeStyle: 'short',
+  }).format(date);
+}
+
+/**
+ * A producer status as a word.
+ *
+ * `tOptional` first: a status the catalog names is shown in the buyer's
+ * language, and one it does not is shown as the producer spelled it rather than
+ * as a guess. New statuses appear upstream before they appear here.
+ *
+ * The catalog is keyed by the producer's own spelling — `status.COMPLETED`,
+ * uppercase — so the lookup normalizes UP. Lowercasing it missed every key in
+ * every one of the 16 locales and quietly served `humanizeStatus`, i.e. English
+ * word-splitting, to buyers reading the shop in another language.
+ */
+export function statusLabel(status: string): string {
+  return tOptional(`status.${status.trim().toUpperCase()}`) ?? humanizeStatus(status);
+}
+
+function humanizeStatus(status: string): string {
+  return status
+    .toLowerCase()
+    .split('_')
+    .map((word) => (word ? word[0]!.toUpperCase() + word.slice(1) : word))
+    .join(' ');
+}
+
+/**
+ * The tone table. Anything unlisted is neutral rather than green.
+ *
+ * The chip tones are the catalog's stock-level tones. They read as
+ * stock levels because the catalog's chips are where they were introduced;
+ * there is no separate success/warning/danger trio to reach for, and inventing
+ * one would leave the storefront with two chip systems.
+ */
+const TONE_GOOD = 'sxa:meta-chip--in_stock';
+const TONE_WAITING = 'sxa:meta-chip--low_stock';
+const TONE_BAD = 'sxa:meta-chip--sold_out';
+
+const STATUS_TONES: Record<string, string> = {
+  // Done, and nothing is owed either way.
+  COMPLETED: TONE_GOOD,
+  PAID: TONE_GOOD,
+  ACTIVE: TONE_GOOD,
+  APPROVED: TONE_GOOD,
+  RESOLVED: TONE_GOOD,
+  CONVERTED: TONE_GOOD,
+  // In flight. The buyer is waiting on someone, or someone is waiting on them.
+  PENDING: TONE_WAITING,
+  PENDING_PAYMENT: TONE_WAITING,
+  PROCESSING: TONE_WAITING,
+  AWAITING_STOCK: TONE_WAITING,
+  AWAITING_REPLY: TONE_WAITING,
+  UNDERPAID: TONE_WAITING,
+  TRIALING: TONE_WAITING,
+  PAUSED: TONE_WAITING,
+  INCOMPLETE: TONE_WAITING,
+  REQUESTED: TONE_WAITING,
+  // Something the buyer would want to notice.
+  PAST_DUE: TONE_BAD,
+  UNPAID: TONE_BAD,
+  DISPUTED: TONE_BAD,
+  EXPIRED: TONE_BAD,
+  VOIDED: TONE_BAD,
+  REVOKED: TONE_BAD,
+  REJECTED: TONE_BAD,
+  SUSPENDED: TONE_BAD,
+  FAILED: TONE_BAD,
+  CANCELED: TONE_BAD,
+  CANCELLED: TONE_BAD,
+};
+
+/*
+ * Deliberately untoned, and neutral is the honest answer for each:
+ * REFUNDED / PARTIAL_REFUND (settled, and the buyer has their money),
+ * INACTIVE, OPEN / CLOSED (a support thread's two normal ends).
+ *
+ * `delivery.*` statuses — DELIVERED, AWAITING_FULFILLMENT — are a DIFFERENT
+ * namespace and belong to the per-line delivery chip, not here. They sat in
+ * this table until the guard test caught them: the lookup could never hit, so
+ * the tone never applied.
+ */
+
+export function StatusChip({ status }: { status: string }) {
+  const tone = STATUS_TONES[status.trim().toUpperCase()] ?? 'sxa:meta-chip--neutral';
+  return (
+    <span className={`sx-account-status sx-account-chip sxa:meta-chip sxa:meta-chip--status ${tone} sxa:shrink-0`}>{statusLabel(status)}</span>
+  );
+}
+
+/** The card surface every panel section sits on. */
+export function AccountCard({
+  children,
+  className = '',
+}: {
+  children: ReactNode;
+  className?: string;
+}) {
+  return (
+    <div className={`sx-account-card sxa:rounded-input sxa:border sxa:bg-surface sxa:shadow-card ${className}`}>{children}</div>
+  );
+}
+
+export function AccountSectionTitle({ children }: { children: ReactNode }) {
+  return <h2 className="sx-account-section-title sxa:font-heading sxa:text-body sxa:font-semibold">{children}</h2>;
+}
+
+export function AccountRowsSkeleton({ rows = 3, label }: { rows?: number; label: string }) {
+  return (
+    <div role="status" aria-label={label} className="sx-account-skeleton sxa:space-y-3">
+      {Array.from({ length: rows }, (_, index) => (
+        <div key={index} className="sxa:h-16 sxa:animate-pulse sxa:rounded-input sxa:border sxa:bg-bg" />
+      ))}
+    </div>
+  );
+}
+
+/**
+ * A failure, in the producer's own words where it gave any.
+ *
+ * The retry is the point: a buyer who cannot see their orders wants to try
+ * again, not read an apology.
+ */
+export function AccountError({
+  message,
+  onRetry,
+}: {
+  message: string;
+  onRetry?: () => void;
+}) {
+  return (
+    <AccountCard className="sx-account-error sxa:px-6 sxa:py-10 sxa:text-center">
+      <div className="sxa:mx-auto sxa:mb-4 sxa:flex sxa:h-12 sxa:w-12 sxa:items-center sxa:justify-center sxa:rounded-input sxa:border sxa:bg-bg">
+        <CircleAlertIcon className="sxa:h-5 sxa:w-5 sxa:text-muted" />
+      </div>
+      <p role="alert" className="sxa:text-small sxa:text-muted">{message}</p>
+      {onRetry ? (
+        <button type="button" onClick={onRetry} className="sx-account-cta sxa:cta-button sxa:mt-5 sxa:h-9 sxa:px-4 sxa:text-small">
+          {t('common.retry')}
+        </button>
+      ) : null}
+    </AccountCard>
+  );
+}
+
+export function AccountNotice({ message }: { message: string }) {
+  return (
+    <p role="status" className="sx-account-notice sxa:mt-3 sxa:inline-flex sxa:items-center sxa:gap-1.5 sxa:text-small sxa:text-success">
+      <CheckIcon className="sxa:h-4 sxa:w-4 sxa:shrink-0" />
+      {message}
+    </p>
+  );
+}
+
+export function AccountFieldError({ message }: { message: string }) {
+  return <p role="alert" className="sx-account-field-error sxa:mt-3 sxa:text-small sxa:text-error">{message}</p>;
+}
+
+export function AccountEmpty({
+  title,
+  body,
+  action,
+}: {
+  title: string;
+  body: string;
+  action?: ReactNode;
+}) {
+  return (
+    <AccountCard className="sx-account-empty sxa:px-8 sxa:py-16 sxa:text-center">
+      <p className="sxa:font-heading sxa:font-semibold">{title}</p>
+      <p className="sxa:mx-auto sxa:mt-2 sxa:max-w-md sxa:text-small sxa:text-muted">{body}</p>
+      {action ? <div className="sxa:mt-5">{action}</div> : null}
+    </AccountCard>
+  );
+}
+
+export function AccountBackLink({ to, label }: { to: string; label: string }) {
+  return (
+    <Link to={to} className="sx-account-back sxa:inline-flex sxa:items-center sxa:gap-1.5 sxa:text-small sxa:transition-opacity sxa:hover:opacity-80">
+      <ArrowLeftIcon className="sxa:h-4 sxa:w-4 sxa:shrink-0" />
+      {label}
+    </Link>
+  );
+}
+
+export function AccountBackButton({ onClick, label }: { onClick: () => void; label: string }) {
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      className="sx-account-back sxa:inline-flex sxa:items-center sxa:gap-1.5 sxa:text-small sxa:transition-opacity sxa:hover:opacity-80"
+    >
+      <ArrowLeftIcon className="sxa:h-4 sxa:w-4 sxa:shrink-0" />
+      {label}
+    </button>
+  );
+}
+
+/**
+ * Copies what the row actually shows.
+ *
+ * The confirmation is time-boxed rather than sticky: a "Copied" that never
+ * clears is a claim about the clipboard the page cannot keep checking.
+ */
+export function CopyButton({ value, className = '' }: { value: string; className?: string }) {
+  const [copied, setCopied] = useState(false);
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(() => () => {
+    if (timer.current) clearTimeout(timer.current);
+  }, []);
+
+  return (
+    <button
+      type="button"
+      className={`sx-account-copy sx-account-button sxa:card-button sxa:card-button--add ${className}`}
+      onClick={() => {
+        void navigator.clipboard?.writeText(value).then(() => {
+          setCopied(true);
+          if (timer.current) clearTimeout(timer.current);
+          timer.current = setTimeout(() => setCopied(false), 1500);
+        });
+      }}
+    >
+      {copied ? <CheckIcon className="sxa:h-3.5 sxa:w-3.5" /> : <CopyIcon className="sxa:h-3.5 sxa:w-3.5" />}
+      <span className="sxa:ml-1.5">{copied ? t('common.copied') : t('common.copy')}</span>
+    </button>
+  );
+}
+
+/** The spinner a control shows while its own request is in flight. */
+export function BusySpinner({ className = '' }: { className?: string }) {
+  return <LoaderIcon className={`sxa:h-4 sxa:w-4 sxa:shrink-0 sxa:animate-spin ${className}`} />;
+}