@akinon/projectzero 2.0.32 → 2.0.33-beta.0

package/app-template/src/views/checkout/variants/one-page/sections/shipping-section.tsx

@@ -0,0 +1,298 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import clsx from 'clsx';
+import { useAppDispatch, useAppSelector } from '@akinon/next/redux/hooks';
+import {
+  useSetShippingOptionMutation,
+  useSetAttributeBasedShippingOptionsMutation,
+  useSetDataSourceShippingOptionsMutation
+} from '@akinon/next/data/client/checkout';
+import { setSelectedShippingOptions } from '@akinon/next/redux/reducers/checkout';
+import { useLocalization } from '@akinon/next/hooks';
+import { Button, Price, Radio } from '@theme/components';
+import type { RootState } from '@theme/redux/store';
+import AccordionSection, { SectionStatus } from '../accordion-section';
+import { ShippingOptionsSkeleton } from '../skeletons/shipping-skeleton';
+
+interface ShippingSectionProps {
+  status: SectionStatus;
+  onEdit: () => void;
+  onComplete: () => void;
+  editable?: boolean;
+}
+
+const ShippingSection = ({
+  status,
+  onEdit,
+  onComplete,
+  editable = true
+}: ShippingSectionProps) => {
+  const { t } = useLocalization();
+  const dispatch = useAppDispatch();
+  const {
+    shippingOptions,
+    attributeBasedShippingOptions,
+    dataSourceShippingOptions,
+    preOrder,
+    selectedShippingOptions
+  } = useAppSelector((state: RootState) => state.checkout);
+  const {
+    shipping_option,
+    attribute_based_shipping_options,
+    data_source_shipping_options
+  } = preOrder ?? {};
+
+  const [setShippingOption, { isLoading: isSettingPlain }] =
+    useSetShippingOptionMutation();
+  const [setAttributeBasedShippingOptions, { isLoading: isSettingAttribute }] =
+    useSetAttributeBasedShippingOptionsMutation();
+  const [setDataSourceShippingOption, { isLoading: isSettingDataSource }] =
+    useSetDataSourceShippingOptionsMutation();
+  const isSetting = isSettingPlain || isSettingAttribute || isSettingDataSource;
+
+  const prevAttributeBasedRef = useRef(attributeBasedShippingOptions);
+  const [selectedDataSourcePks, setSelectedDataSourcePks] = useState<
+    { dataSourcePk: number; optionPk: number }[] | null
+  >(null);
+
+  const initializeAttributeOptions = useCallback(() => {
+    if (!attribute_based_shipping_options) return;
+    const next = { ...selectedShippingOptions };
+    let changed = false;
+    Object.entries(attributeBasedShippingOptions).forEach(([key, options]) => {
+      if (!next[key] || !options.some((opt) => opt.pk === next[key])) {
+        next[key] = options[0].pk;
+        changed = true;
+      }
+    });
+    if (changed) {
+      dispatch(setSelectedShippingOptions(next));
+      setAttributeBasedShippingOptions(next);
+    }
+  }, [
+    attributeBasedShippingOptions,
+    selectedShippingOptions,
+    attribute_based_shipping_options,
+    dispatch,
+    setAttributeBasedShippingOptions
+  ]);
+
+  useEffect(() => {
+    if (!data_source_shipping_options) return;
+    setSelectedDataSourcePks(
+      data_source_shipping_options.map((option) => ({
+        dataSourcePk: option.data_source.pk,
+        optionPk: option.pk
+      }))
+    );
+  }, [data_source_shipping_options]);
+
+  useEffect(() => {
+    if (
+      JSON.stringify(prevAttributeBasedRef.current) !==
+        JSON.stringify(attributeBasedShippingOptions) ||
+      Object.keys(selectedShippingOptions).length === 0
+    ) {
+      initializeAttributeOptions();
+      prevAttributeBasedRef.current = attributeBasedShippingOptions;
+    }
+  }, [
+    attributeBasedShippingOptions,
+    selectedShippingOptions,
+    initializeAttributeOptions
+  ]);
+
+  const handlePlainOption = (pk: number) => {
+    setShippingOption(pk);
+  };
+
+  const handleAttributeOption = (key: string, pk: number) => {
+    const next = { ...selectedShippingOptions, [key]: pk };
+    dispatch(setSelectedShippingOptions(next));
+    setAttributeBasedShippingOptions(next);
+  };
+
+  const handleDataSourceOption = (dataSourcePk: number, optionPk: number) => {
+    const updated = selectedDataSourcePks?.map((item) =>
+      item.dataSourcePk === dataSourcePk ? { ...item, optionPk } : item
+    );
+    if (!updated) return;
+    setSelectedDataSourcePks(updated);
+    setDataSourceShippingOption(updated.map((item) => item.optionPk));
+  };
+
+  const summary = shipping_option ? (
+    <div className="flex flex-col">
+      <span className="font-medium">{shipping_option.name}</span>
+      {shipping_option.shipping_amount && (
+        <span className="text-xs text-black-700">
+          <Price value={shipping_option.shipping_amount} />
+        </span>
+      )}
+    </div>
+  ) : null;
+
+  const hasAttributeOptions = useMemo(
+    () =>
+      attributeBasedShippingOptions &&
+      Object.keys(attributeBasedShippingOptions).length > 0,
+    [attributeBasedShippingOptions]
+  );
+
+  const hasDataSourceOptions = useMemo(
+    () => dataSourceShippingOptions && dataSourceShippingOptions.length > 0,
+    [dataSourceShippingOptions]
+  );
+
+  const noOptionsLoaded =
+    shippingOptions.length === 0 &&
+    !hasAttributeOptions &&
+    !hasDataSourceOptions;
+
+  return (
+    <AccordionSection
+      step={3}
+      title={t('checkout.one_page.shipping.title')}
+      status={status}
+      onEdit={onEdit}
+      editable={editable}
+      summary={summary}
+      dataTestId="one-page-shipping"
+    >
+      {noOptionsLoaded ? (
+        <ShippingOptionsSkeleton />
+      ) : (
+        <div
+          className={clsx('flex flex-col gap-4', {
+            'opacity-60 pointer-events-none': isSetting
+          })}
+        >
+          {shippingOptions.length > 0 && (
+            <div
+              className="flex flex-col gap-2"
+              role="radiogroup"
+              aria-label={t('checkout.one_page.shipping.title')}
+            >
+              {shippingOptions.map((option) => (
+                <label
+                  key={option.pk}
+                  className={clsx(
+                    'flex cursor-pointer items-center justify-between rounded-sm border px-4 py-3 transition-all',
+                    'focus-within:ring-2 focus-within:ring-secondary focus-within:ring-offset-1',
+                    shipping_option?.pk === option.pk
+                      ? 'border-secondary-400 bg-secondary-50/50'
+                      : 'border-gray-300 hover:border-secondary-400'
+                  )}
+                >
+                  <Radio
+                    name="one-page-shipping"
+                    checked={option.pk === shipping_option?.pk}
+                    onChange={() => handlePlainOption(option.pk)}
+                    data-testid={`one-page-shipping-option-${option.pk}`}
+                  >
+                    <span className="ml-1 text-sm">{option.name}</span>
+                  </Radio>
+                  <span className="text-sm font-medium">
+                    <Price value={option.shipping_amount} />
+                  </span>
+                </label>
+              ))}
+            </div>
+          )}
+
+          {hasAttributeOptions &&
+            Object.entries(attributeBasedShippingOptions).map(
+              ([key, options]) => (
+                <div key={key}>
+                  <h4 className="mb-2 text-sm font-medium text-black-800">
+                    {key}
+                  </h4>
+                  <div
+                    className="flex flex-col gap-2"
+                    role="radiogroup"
+                    aria-label={key}
+                  >
+                    {options.map((option) => (
+                      <label
+                        key={option.pk}
+                        className="flex cursor-pointer items-center justify-between rounded-sm border border-gray-300 px-4 py-3 hover:border-secondary-400"
+                      >
+                        <Radio
+                          name={`one-page-attr-${key}`}
+                          checked={selectedShippingOptions[key] === option.pk}
+                          onChange={() =>
+                            handleAttributeOption(key, option.pk)
+                          }
+                          data-testid={`one-page-attr-shipping-${option.pk}`}
+                        >
+                          <span className="ml-1 text-sm">
+                            {option.shipping_option_name}
+                          </span>
+                        </Radio>
+                        <span className="text-sm font-medium">
+                          <Price value={option.shipping_amount} />
+                        </span>
+                      </label>
+                    ))}
+                  </div>
+                </div>
+              )
+            )}
+
+          {hasDataSourceOptions &&
+            dataSourceShippingOptions.map((source) => (
+              <div key={source.pk}>
+                <h4 className="mb-2 text-sm font-medium text-black-800">
+                  {source.name}
+                </h4>
+                <div
+                  className="flex flex-col gap-2"
+                  role="radiogroup"
+                  aria-label={source.name}
+                >
+                  {source.data_source_shipping_options.map((opt) => (
+                    <label
+                      key={opt.pk}
+                      className="flex cursor-pointer items-center justify-between rounded-sm border border-gray-300 px-4 py-3 hover:border-secondary-400"
+                    >
+                      <Radio
+                        name={`one-page-ds-${source.pk}`}
+                        checked={
+                          selectedDataSourcePks?.some(
+                            (item) => item.optionPk === opt.pk
+                          ) || false
+                        }
+                        onChange={() =>
+                          handleDataSourceOption(source.pk, opt.pk)
+                        }
+                        data-testid={`one-page-ds-shipping-${opt.pk}`}
+                      >
+                        <span className="ml-1 text-sm">
+                          {opt.shipping_option_name}
+                        </span>
+                      </Radio>
+                      <span className="text-sm font-medium">
+                        <Price value={opt.shipping_amount} />
+                      </span>
+                    </label>
+                  ))}
+                </div>
+              </div>
+            ))}
+
+          {shipping_option && (
+            <div className="flex justify-end">
+              <Button
+                onClick={onComplete}
+                data-testid="one-page-shipping-continue"
+              >
+                {t('checkout.one_page.continue_to_payment')}
+              </Button>
+            </div>
+          )}
+        </div>
+      )}
+    </AccordionSection>
+  );
+};
+
+export default ShippingSection;

package/app-template/src/views/checkout/variants/one-page/skeletons/address-skeleton.tsx

@@ -0,0 +1,25 @@
+import { Skeleton } from '@theme/components';
+
+export const AddressListSkeleton = () => (
+  <div className="flex flex-col gap-4" aria-busy="true">
+    <div className="flex items-center justify-between">
+      <Skeleton className="h-4 w-32" />
+      <Skeleton className="h-4 w-48" />
+    </div>
+    <div className="grid grid-cols-1 gap-2 md:grid-cols-2">
+      {Array.from({ length: 3 }).map((_, i) => (
+        <div
+          key={i}
+          className="rounded-sm border border-gray-300 p-3 shadow-sm"
+        >
+          <Skeleton className="mb-2 h-4 w-4 rounded-full" />
+          <Skeleton className="mb-1.5 h-3 w-3/4" />
+          <Skeleton className="mb-1.5 h-3 w-1/2" />
+          <Skeleton className="h-3 w-full" />
+        </div>
+      ))}
+    </div>
+  </div>
+);
+
+export default AddressListSkeleton;

package/app-template/src/views/checkout/variants/one-page/skeletons/checkout-skeleton.tsx

@@ -0,0 +1,27 @@
+import { SectionSkeleton } from './section-skeleton';
+import { AddressListSkeleton } from './address-skeleton';
+import { SummarySkeleton } from './summary-skeleton';
+
+export const CheckoutOnePageSkeleton = () => (
+  <div className="min-h-screen bg-[#fafafa] pb-20 md:pb-16">
+    <div className="container w-full px-4 pt-6 md:px-6 md:pt-10 lg:px-8">
+      <div className="flex flex-col gap-6 lg:flex-row lg:items-start lg:gap-8">
+        <div className="w-full lg:w-2/3">
+          <SectionSkeleton />
+          <SectionSkeleton active>
+            <AddressListSkeleton />
+          </SectionSkeleton>
+          <SectionSkeleton />
+          <SectionSkeleton />
+        </div>
+        <aside className="hidden w-full lg:block lg:w-1/3">
+          <div className="sticky top-6">
+            <SummarySkeleton />
+          </div>
+        </aside>
+      </div>
+    </div>
+  </div>
+);
+
+export default CheckoutOnePageSkeleton;

package/app-template/src/views/checkout/variants/one-page/skeletons/index.ts

@@ -0,0 +1,6 @@
+export { SectionSkeleton } from './section-skeleton';
+export { AddressListSkeleton } from './address-skeleton';
+export { ShippingOptionsSkeleton } from './shipping-skeleton';
+export { PaymentGridSkeleton } from './payment-skeleton';
+export { SummarySkeleton } from './summary-skeleton';
+export { CheckoutOnePageSkeleton } from './checkout-skeleton';

package/app-template/src/views/checkout/variants/one-page/skeletons/payment-skeleton.tsx

@@ -0,0 +1,23 @@
+import { Skeleton } from '@theme/components';
+
+export const PaymentGridSkeleton = () => (
+  <div
+    className="grid grid-cols-1 gap-2 sm:grid-cols-2 lg:grid-cols-3"
+    aria-busy="true"
+  >
+    {Array.from({ length: 6 }).map((_, i) => (
+      <div
+        key={i}
+        className="flex min-h-[5rem] flex-col justify-center gap-2 rounded-md border border-gray-300 bg-white px-4 py-3"
+      >
+        <div className="flex items-center justify-between">
+          <Skeleton className="h-5 w-5" />
+          <Skeleton className="h-4 w-4 rounded-full" />
+        </div>
+        <Skeleton className="h-4 w-3/4" />
+      </div>
+    ))}
+  </div>
+);
+
+export default PaymentGridSkeleton;

package/app-template/src/views/checkout/variants/one-page/skeletons/section-skeleton.tsx

@@ -0,0 +1,47 @@
+import { ReactNode } from 'react';
+import clsx from 'clsx';
+import { Skeleton } from '@theme/components';
+
+interface SectionSkeletonProps {
+  active?: boolean;
+  children?: ReactNode;
+  contentClassName?: string;
+}
+
+export const SectionSkeleton = ({
+  active = false,
+  children,
+  contentClassName
+}: SectionSkeletonProps) => {
+  return (
+    <div
+      className={clsx(
+        'mb-4 overflow-hidden rounded-2xl bg-white last:mb-0',
+        active
+          ? 'shadow-[0_12px_40px_-16px_rgba(0,0,0,0.16)] ring-1 ring-black-800/10'
+          : 'shadow-[0_1px_3px_rgba(0,0,0,0.04)] ring-1 ring-black/[0.04]'
+      )}
+      aria-busy="true"
+      aria-label="Loading section"
+    >
+      <header className="flex items-center justify-between px-6 py-5 sm:px-7">
+        <div className="flex items-center gap-3.5">
+          <Skeleton className="h-8 w-8 rounded-full bg-gray-200" />
+          <Skeleton className="h-5 w-44 bg-gray-200" />
+        </div>
+      </header>
+      {(active || children) && (
+        <div
+          className={clsx(
+            'border-t border-gray-100 px-6 py-6 sm:px-7',
+            contentClassName
+          )}
+        >
+          {children ?? <Skeleton className="h-14 w-full bg-gray-200" />}
+        </div>
+      )}
+    </div>
+  );
+};
+
+export default SectionSkeleton;

package/app-template/src/views/checkout/variants/one-page/skeletons/shipping-skeleton.tsx

@@ -0,0 +1,20 @@
+import { Skeleton } from '@theme/components';
+
+export const ShippingOptionsSkeleton = () => (
+  <div className="flex flex-col gap-2" aria-busy="true">
+    {Array.from({ length: 3 }).map((_, i) => (
+      <div
+        key={i}
+        className="flex items-center justify-between rounded-sm border border-gray-300 px-4 py-3"
+      >
+        <div className="flex items-center gap-3">
+          <Skeleton className="h-4 w-4 rounded-full" />
+          <Skeleton className="h-4 w-32" />
+        </div>
+        <Skeleton className="h-4 w-16" />
+      </div>
+    ))}
+  </div>
+);
+
+export default ShippingOptionsSkeleton;

package/app-template/src/views/checkout/variants/one-page/skeletons/summary-skeleton.tsx

@@ -0,0 +1,38 @@
+import { Skeleton } from '@theme/components';
+
+export const SummarySkeleton = () => (
+  <div className="flex flex-col gap-4" aria-busy="true">
+    <section className="overflow-hidden rounded-2xl bg-white shadow-[0_1px_3px_rgba(0,0,0,0.04)] ring-1 ring-black/[0.04]">
+      <div className="flex items-baseline justify-between px-6 py-5">
+        <Skeleton className="h-5 w-24 bg-gray-200" />
+        <Skeleton className="h-3 w-14 bg-gray-200" />
+      </div>
+      <div className="divide-y divide-gray-100 border-t border-gray-100">
+        {Array.from({ length: 2 }).map((_, i) => (
+          <div key={i} className="flex gap-3 px-6 py-4">
+            <Skeleton className="h-20 w-14 flex-shrink-0 rounded-md bg-gray-200" />
+            <div className="flex flex-1 flex-col gap-2">
+              <Skeleton className="h-3 w-3/4 bg-gray-200" />
+              <Skeleton className="h-3 w-1/2 bg-gray-200" />
+              <div className="mt-auto flex justify-between">
+                <Skeleton className="h-3 w-16 bg-gray-200" />
+                <Skeleton className="h-3 w-12 bg-gray-200" />
+              </div>
+            </div>
+          </div>
+        ))}
+      </div>
+      <div className="space-y-2.5 border-t border-gray-100 px-6 py-5">
+        <Skeleton className="h-3 w-full bg-gray-200" />
+        <Skeleton className="h-3 w-full bg-gray-200" />
+        <Skeleton className="h-3 w-full bg-gray-200" />
+      </div>
+      <div className="flex items-baseline justify-between border-t border-gray-100 px-6 py-5">
+        <Skeleton className="h-4 w-16 bg-gray-200" />
+        <Skeleton className="h-7 w-28 bg-gray-200" />
+      </div>
+    </section>
+  </div>
+);
+
+export default SummarySkeleton;

package/app-template/src/views/checkout/variants/one-page/trust-badges.tsx

@@ -0,0 +1,30 @@
+import { useLocalization } from '@akinon/next/hooks';
+import { Icon } from '@theme/components';
+import { Image } from '@akinon/next/components/image';
+
+const TrustBadges = () => {
+  const { t } = useLocalization();
+
+  return (
+    <div className="mt-6 flex flex-col gap-3 px-2 sm:flex-row sm:items-center sm:justify-between">
+      <div className="flex items-center gap-2 text-xs text-gray-600">
+        <Icon name="info" size={14} className="fill-gray-500" aria-hidden="true" />
+        <span>{t('checkout.one_page.trust.secure_note')}</span>
+      </div>
+      <div className="flex items-center gap-2 opacity-70" aria-hidden="true">
+        <Image src="/visa.png" alt="Visa" width={36} height={12} />
+        <Image src="/mastercard.png" alt="Mastercard" width={20} height={12} />
+        <Image src="/vbv.png" alt="Verified by Visa" width={26} height={12} />
+        <Image
+          src="/mastersecure.png"
+          alt="Mastercard Secure"
+          width={32}
+          height={12}
+        />
+        <Image src="/ssl-secure.png" alt="SSL Secure" width={12} height={12} />
+      </div>
+    </div>
+  );
+};
+
+export default TrustBadges;

package/app-template/src/views/checkout/variants/registry.ts

@@ -0,0 +1,32 @@
+import dynamic from 'next/dynamic';
+import type { ComponentType } from 'react';
+import type { CheckoutVariantId, CheckoutVariantProps } from './types';
+
+type VariantLoader = () => Promise<{
+  default: ComponentType<CheckoutVariantProps>;
+}>;
+
+const variantLoaders: Record<CheckoutVariantId, VariantLoader> = {
+  'multi-step': () => import('./multi-step'),
+  'one-page': () => import('./one-page'),
+  accordion: () => import('./one-page'),
+  'basket-and-checkout': () => import('./basket-and-checkout')
+};
+
+/**
+ * Variants that embed the basket inside the checkout page. In these modes the
+ * basket page redirects to checkout, so checkout must never redirect back to
+ * the basket page — that would create an infinite redirect loop.
+ */
+export const UNIFIED_VARIANTS: ReadonlySet<string> = new Set([
+  'basket-and-checkout'
+]);
+
+export const getCheckoutVariant = (variant: CheckoutVariantId | undefined) => {
+  const loader = variantLoaders[variant ?? 'multi-step'] ?? variantLoaders['multi-step'];
+
+  return dynamic(loader, { ssr: false });
+};
+
+export const isKnownVariant = (value: unknown): value is CheckoutVariantId =>
+  typeof value === 'string' && value in variantLoaders;

package/app-template/src/views/checkout/variants/types.ts

@@ -0,0 +1,30 @@
+import { ComponentType } from 'react';
+
+export type CheckoutVariantId =
+  | 'multi-step'
+  | 'one-page'
+  | 'accordion'
+  | 'basket-and-checkout';
+
+export interface CheckoutVariantOptions {
+  /** Show "Edit" button on completed sections so user can revisit them. Default: true */
+  enableEditMode?: boolean;
+  /** Auto-open next incomplete section when the current one becomes complete. Default: true */
+  autoAdvance?: boolean;
+  /** Render the sticky bottom summary drawer on mobile. Default: true */
+  stickyMobileCta?: boolean;
+  /** Show "Order details" review card (address + shipping + payment) in summary. Default: true */
+  showOrderReview?: boolean;
+  /** Show SSL/security badges + trust note under the payment section. Default: true */
+  showTrustBadges?: boolean;
+  /** Fire GA4 funnel events for each section transition. Default: true */
+  gtmEnabled?: boolean;
+  /** Compact spacing/typography for power-user mode. Default: false */
+  compactMode?: boolean;
+}
+
+export interface CheckoutVariantProps {
+  options?: CheckoutVariantOptions;
+}
+
+export type CheckoutVariant = ComponentType<CheckoutVariantProps>;

package/app-template/src/views/checkout/variants/use-resolved-config.ts

@@ -0,0 +1,89 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import settings from '@theme/settings';
+import { isKnownVariant } from './registry';
+import type { CheckoutVariantId, CheckoutVariantOptions } from './types';
+
+export interface ResolvedCheckoutConfig {
+  variantId: CheckoutVariantId;
+  options: CheckoutVariantOptions;
+}
+
+interface RawCheckoutConfig {
+  variant?: string;
+  options?: Record<string, unknown>;
+}
+
+const FALLBACK_VARIANT: CheckoutVariantId = 'multi-step';
+
+const coerceOptions = (
+  raw: Record<string, unknown> | undefined
+): CheckoutVariantOptions => {
+  if (!raw) return {};
+  const cast = raw as Partial<CheckoutVariantOptions>;
+  const out: CheckoutVariantOptions = {};
+  if (typeof cast.enableEditMode === 'boolean') out.enableEditMode = cast.enableEditMode;
+  if (typeof cast.autoAdvance === 'boolean') out.autoAdvance = cast.autoAdvance;
+  if (typeof cast.stickyMobileCta === 'boolean') out.stickyMobileCta = cast.stickyMobileCta;
+  if (typeof cast.showOrderReview === 'boolean') out.showOrderReview = cast.showOrderReview;
+  if (typeof cast.showTrustBadges === 'boolean') out.showTrustBadges = cast.showTrustBadges;
+  if (typeof cast.gtmEnabled === 'boolean') out.gtmEnabled = cast.gtmEnabled;
+  if (typeof cast.compactMode === 'boolean') out.compactMode = cast.compactMode;
+  return out;
+};
+
+const readBaseFromSettings = (): ResolvedCheckoutConfig => {
+  const fromSettings = (settings as { checkout?: RawCheckoutConfig })?.checkout;
+  const variantId = isKnownVariant(fromSettings?.variant)
+    ? fromSettings.variant
+    : FALLBACK_VARIANT;
+  return {
+    variantId,
+    options: coerceOptions(fromSettings?.options)
+  };
+};
+
+const mergeOverride = (
+  base: ResolvedCheckoutConfig,
+  override: RawCheckoutConfig | undefined
+): ResolvedCheckoutConfig => {
+  if (!override) return base;
+  return {
+    variantId: isKnownVariant(override.variant) ? override.variant : base.variantId,
+    options: { ...base.options, ...coerceOptions(override.options) }
+  };
+};
+
+/**
+ * Resolves checkout config from two layers (each optional):
+ *
+ *   1. settings.js (sync, always available — baseline / fallback)
+ *   2. /api/theme-settings (backend theme-config widget — persistent override)
+ *
+ * Layer 2 falls back silently if backend is unreachable or no config is saved.
+ * The editor is OPTIONAL — when no theme-config is saved, the storefront keeps
+ * using its built-in settings.js.
+ */
+export const useResolvedCheckoutConfig = (): ResolvedCheckoutConfig => {
+  const [config, setConfig] = useState<ResolvedCheckoutConfig>(readBaseFromSettings);
+
+  useEffect(() => {
+    let cancelled = false;
+    fetch('/api/theme-settings', { cache: 'no-store' })
+      .then((res) => (res.ok ? res.json() : null))
+      .then((data: { checkout?: RawCheckoutConfig } | null) => {
+        if (cancelled) return;
+        if (!data?.checkout) return;
+        setConfig(() => mergeOverride(readBaseFromSettings(), data.checkout));
+      })
+      .catch(() => {
+        // Silent: backend not reachable or widget missing — keep settings.js baseline
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  return config;
+};