@forgecart/cli 2.202610052310.0 → 2.202610060357.0

package/templates/storefront-shadcn/src/components/checkout/PaymentElementForm.tsx

@@ -0,0 +1,140 @@
+'use client';
+
+import { useEffect, useRef, useState } from 'react';
+
+import { Button } from '../ui/button';
+
+/**
+ * In-page Stripe Payment Element — the direct-render adapter for
+ * Stripe-model providers (operator decision 2026-08-01: our own payment
+ * chrome is never iframed; the srcdoc embed provided no security boundary —
+ * it is same-origin, and PCI isolation comes from Stripe's OWN nested
+ * input iframes, which apply identically here). The page owns the button
+ * and all visible chrome, so the payment step inherits the design system;
+ * only the card inputs are Stripe's.
+ *
+ * Everything this component needs arrives as data from the shop API
+ * (`getSessionVariables` + the created session's secret) — no keys and no
+ * provider configuration live in the template source. Providers without an
+ * in-page adapter keep the hosted-template embed (`PaymentFormEmbed`).
+ */
+
+/** Minimal structural surface of Stripe.js v3 — the template ships no SDK dep. */
+interface StripeElementsHandle {
+  create: (kind: 'payment') => { mount: (node: HTMLElement) => void; unmount: () => void };
+}
+interface StripeHandle {
+  elements: (options: { clientSecret: string }) => StripeElementsHandle;
+  confirmPayment: (options: {
+    elements: StripeElementsHandle;
+    redirect: 'if_required';
+  }) => Promise<{
+    error?: { message?: string };
+    paymentIntent?: { id: string; status: string };
+  }>;
+}
+declare global {
+  interface Window {
+    Stripe?: (publishableKey: string) => StripeHandle;
+  }
+}
+
+/** Load the provider script once; concurrent callers share the same promise. */
+let scriptPromise: Promise<void> | null = null;
+function loadProviderScript(scriptUrl: string): Promise<void> {
+  if (window.Stripe) return Promise.resolve();
+  scriptPromise ??= new Promise<void>((resolve, reject) => {
+    const script = document.createElement('script');
+    script.src = scriptUrl;
+    script.async = true;
+    script.onload = () => resolve();
+    script.onerror = () => {
+      scriptPromise = null;
+      reject(new Error('Payment provider script failed to load'));
+    };
+    document.head.appendChild(script);
+  });
+  return scriptPromise;
+}
+
+export function PaymentElementForm({
+  publishableKey,
+  scriptUrl,
+  clientSecret,
+  payLabel,
+  onSuccess,
+  onError,
+}: {
+  publishableKey: string;
+  scriptUrl: string;
+  clientSecret: string;
+  /** Themed button label, e.g. `Pay €42.00` — the PAGE owns the chrome. */
+  payLabel: string;
+  onSuccess: (status: string, paymentIntentId: string) => void;
+  onError: (message: string) => void;
+}) {
+  const mountRef = useRef<HTMLDivElement | null>(null);
+  const stripeRef = useRef<StripeHandle | null>(null);
+  const elementsRef = useRef<StripeElementsHandle | null>(null);
+  const [mounted, setMounted] = useState(false);
+  const [paying, setPaying] = useState(false);
+  // Callbacks ride a ref so the mount effect binds once per secret.
+  const handlersRef = useRef({ onError });
+  handlersRef.current = { onError };
+
+  useEffect(() => {
+    let cancelled = false;
+    let element: { unmount: () => void } | null = null;
+    void loadProviderScript(scriptUrl)
+      .then(() => {
+        if (cancelled || !window.Stripe || !mountRef.current) return;
+        const stripe = window.Stripe(publishableKey);
+        const elements = stripe.elements({ clientSecret });
+        const paymentElement = elements.create('payment');
+        paymentElement.mount(mountRef.current);
+        stripeRef.current = stripe;
+        elementsRef.current = elements;
+        element = paymentElement;
+        setMounted(true);
+      })
+      .catch((error: Error) => {
+        if (!cancelled) handlersRef.current.onError(error.message);
+      });
+    return () => {
+      cancelled = true;
+      element?.unmount();
+    };
+  }, [scriptUrl, publishableKey, clientSecret]);
+
+  async function pay(): Promise<void> {
+    const stripe = stripeRef.current;
+    const elements = elementsRef.current;
+    if (!stripe || !elements || paying) return;
+    setPaying(true);
+    const result = await stripe.confirmPayment({ elements, redirect: 'if_required' });
+    setPaying(false);
+    if (result.error) {
+      onError(result.error.message ?? 'Payment failed');
+      return;
+    }
+    if (result.paymentIntent) {
+      onSuccess(result.paymentIntent.status, result.paymentIntent.id);
+    }
+  }
+
+  return (
+    <div className="space-y-4">
+      {!mounted && <p className="text-sm text-muted-foreground">Loading payment form…</p>}
+      <div ref={mountRef} />
+      <Button
+        type="button"
+        onClick={() => void pay()}
+        disabled={!mounted || paying}
+        data-fc-track="checkout-pay"
+        className="w-full"
+      >
+        {paying ? 'Processing…' : payLabel}
+      </Button>
+    </div>
+  );
+}

package/templates/storefront-shadcn/src/components/checkout/PaymentFormEmbed.tsx

@@ -0,0 +1,89 @@
+'use client';
+
+import { useEffect, useRef, useState } from 'react';
+
+/**
+ * Provider-agnostic host for the shop API's hosted payment form
+ * (`PaymentFormTemplate.html` — Stripe, Mollie, … the template carries all
+ * provider code; this component contains none).
+ *
+ * The handshake is the #865 contract, extended with in-band secret delivery:
+ * the hosted form posts `iframe-ready`, `payment-success` and
+ * `payment-error` to its embedder, and the embedder answers `iframe-ready`
+ * by posting `client-secret` back INTO the frame — the session's secret
+ * never rides the rendered HTML (which may be logged or cached
+ * server-side); the provider template mounts its payment element only once
+ * the secret arrives. Every message in both directions is pinned to the
+ * page's own origin: the srcdoc iframe is same-origin with this page (no
+ * sandbox), so legitimate traffic carries `window.location.origin` — any
+ * other origin (another iframe, an extension, a foreign embed) is ignored.
+ */
+export interface PaymentFormMessage {
+  type: 'iframe-ready' | 'payment-success' | 'payment-error';
+  error?: string;
+  paymentIntentId?: string;
+  status?: string;
+}
+
+export function PaymentFormEmbed({
+  html,
+  clientSecret,
+  onSuccess,
+  onError,
+}: {
+  html: string;
+  /** The payment session's secret, delivered to the frame post-`iframe-ready`. */
+  clientSecret?: string;
+  onSuccess: (message: PaymentFormMessage) => void;
+  onError: (message: string) => void;
+}) {
+  const [ready, setReady] = useState(false);
+  const frameRef = useRef<HTMLIFrameElement | null>(null);
+  // Callbacks ride a ref so the message listener binds once per html.
+  const handlersRef = useRef({ onSuccess, onError });
+  handlersRef.current = { onSuccess, onError };
+
+  useEffect(() => {
+    function onMessage(event: MessageEvent<PaymentFormMessage>): void {
+      if (event.origin !== window.location.origin) return;
+      const data = event.data;
+      if (!data || typeof data !== 'object') return;
+      if (data.type === 'iframe-ready') {
+        setReady(true);
+        return;
+      }
+      if (data.type === 'payment-success') {
+        handlersRef.current.onSuccess(data);
+        return;
+      }
+      if (data.type === 'payment-error') {
+        handlersRef.current.onError(data.error ?? 'Payment failed');
+      }
+    }
+    window.addEventListener('message', onMessage);
+    return () => window.removeEventListener('message', onMessage);
+  }, [html]);
+
+  // Deliver the secret once the frame is listening. Embedded-confirm
+  // templates (Stripe's Payment Element) mount on receipt; templates with no
+  // client-side secret (redirect models) simply never consume the message.
+  useEffect(() => {
+    if (!ready || !clientSecret) return;
+    frameRef.current?.contentWindow?.postMessage(
+      { type: 'client-secret', clientSecret },
+      window.location.origin,
+    );
+  }, [ready, clientSecret]);
+
+  return (
+    <div className="space-y-2">
+      {!ready && <p className="text-sm text-muted-foreground">Loading payment form…</p>}
+      <iframe
+        ref={frameRef}
+        title="Payment form"
+        srcDoc={html}
+        className="min-h-96 w-full rounded-md border bg-card"
+      />
+    </div>
+  );
+}

package/templates/storefront-shadcn/src/components/checkout/RatesStep.tsx

@@ -0,0 +1,115 @@
+'use client';
+
+import type { ExtractedError } from '@forgecart/sdk/shop';
+
+import type { ShippingRateGroup } from '../../lib/forgecart';
+import { formatPrice } from '../../lib/format';
+import { Alert, AlertDescription } from '../ui/alert';
+import { Button } from '../ui/button';
+import { Card } from '../ui/card';
+import { cn } from '../ui/utils';
+
+/**
+ * Shipping-rate selection: one card group per shipment (rates arrive grouped
+ * by stock location), radio-cards per rate, per-group `lastRateErrors`
+ * alerts (a refusing carrier never hides its siblings' quotes). The CUSTOMER
+ * picks — nothing auto-selects; the ArrangingPayment transition requires a
+ * selection in every group (#863's `hasSelectedRates` gate).
+ */
+export function RatesStep({
+  groups,
+  onSelect,
+  onContinue,
+  pending,
+  refreshing,
+  error,
+}: {
+  groups: ShippingRateGroup[];
+  onSelect: (rateGroupId: string, rateId: string) => void;
+  onContinue: () => void;
+  pending: boolean;
+  refreshing: boolean;
+  error: ExtractedError | null;
+}) {
+  if (refreshing) {
+    return <p className="text-sm text-muted-foreground">Fetching shipping rates…</p>;
+  }
+
+  const allSelected =
+    groups.length > 0 && groups.every((group) => group.rates.some((rate) => rate.selected));
+
+  return (
+    <div className="space-y-4">
+      {groups.length === 0 && (
+        <Alert role="alert" variant="warning">
+          <AlertDescription>No shipping rates are available for this address yet.</AlertDescription>
+        </Alert>
+      )}
+
+      {groups.map((group, index) => (
+        <Card key={group.id} className="gap-2 p-4">
+          <h3 className="text-sm font-medium text-foreground/80">
+            {groups.length > 1 ? `Shipment ${index + 1}` : 'Shipping method'}
+            {group.stockLocationName ? ` — ships from ${group.stockLocationName}` : ''}
+          </h3>
+
+          {group.lastRateErrors.length > 0 && (
+            <Alert role="alert" variant="warning">
+              <AlertDescription>
+                {group.lastRateErrors
+                  .map((failure) => `${failure.providerName}: quotes unavailable`)
+                  .join(' · ')}
+              </AlertDescription>
+            </Alert>
+          )}
+
+          <div className="flex flex-col gap-2">
+            {group.rates.map((rate) => (
+              <button
+                key={rate.id}
+                type="button"
+                onClick={() => onSelect(group.id, rate.id)}
+                disabled={pending}
+                aria-pressed={rate.selected}
+                data-fc-track="checkout-select-rate"
+                className={cn(
+                  'flex items-center justify-between gap-3 rounded-md border px-3 py-2 text-left text-sm transition disabled:opacity-50',
+                  rate.selected ? 'border-primary ring-1 ring-primary' : 'hover:border-primary',
+                )}
+              >
+                <span className="min-w-0">
+                  <span className="block font-medium text-foreground">
+                    {rate.carrier} {rate.service}
+                  </span>
+                  {rate.estimatedDays !== null && rate.estimatedDays !== undefined && (
+                    <span className="block text-xs text-muted-foreground">
+                      ~{rate.estimatedDays} day{rate.estimatedDays === 1 ? '' : 's'}
+                    </span>
+                  )}
+                </span>
+                <span className="shrink-0 font-medium text-foreground">
+                  {formatPrice(rate.amount, rate.currency)}
+                </span>
+              </button>
+            ))}
+          </div>
+        </Card>
+      ))}
+
+      {error && (
+        <Alert role="alert" variant="destructive">
+          <AlertDescription>{error.message ?? error.code}</AlertDescription>
+        </Alert>
+      )}
+
+      <Button
+        type="button"
+        onClick={onContinue}
+        disabled={pending || !allSelected}
+        data-fc-track="checkout-to-payment"
+      >
+        {pending ? 'Saving…' : 'Continue to payment'}
+      </Button>
+    </div>
+  );
+}

package/templates/storefront-shadcn/src/components/ui/alert.tsx

@@ -0,0 +1,75 @@
+import { cva, type VariantProps } from 'class-variance-authority';
+import type { ComponentProps } from 'react';
+
+import { cn } from './utils';
+
+/**
+ * The shadcn/ui alert, with the status variants this variant declares.
+ *
+ * shadcn/ui ships `default` and `destructive`; the storefront also speaks
+ * success, warning and info, so those three are variants here, each filled
+ * with its own `--success` / `--warning` / `--info` token and the
+ * `-foreground` that stays legible on it (see the mapping table in
+ * `src/app/globals.css`). An alert is `role="alert"` unless the caller says
+ * otherwise — a polite outcome passes `role="status"`.
+ */
+const alertVariants = cva(
+  'relative grid w-full grid-cols-[0_1fr] items-start gap-y-0.5 rounded-lg border px-4 py-3 text-sm has-[>svg]:grid-cols-[calc(var(--spacing)*4)_1fr] has-[>svg]:gap-x-3 [&>svg]:size-4 [&>svg]:translate-y-0.5 [&>svg]:text-current',
+  {
+    variants: {
+      variant: {
+        default: 'bg-card text-card-foreground',
+        destructive:
+          'bg-card text-destructive [&>svg]:text-current *:data-[slot=alert-description]:text-destructive/90',
+        success:
+          'border-success bg-success text-success-foreground *:data-[slot=alert-description]:text-success-foreground/90',
+        warning:
+          'border-warning bg-warning text-warning-foreground *:data-[slot=alert-description]:text-warning-foreground/90',
+        info: 'border-info bg-info text-info-foreground *:data-[slot=alert-description]:text-info-foreground/90',
+      },
+    },
+    defaultVariants: {
+      variant: 'default',
+    },
+  },
+);
+
+function Alert({
+  className,
+  variant,
+  ...props
+}: ComponentProps<'div'> & VariantProps<typeof alertVariants>) {
+  return (
+    <div
+      data-slot="alert"
+      role="alert"
+      className={cn(alertVariants({ variant }), className)}
+      {...props}
+    />
+  );
+}
+
+function AlertTitle({ className, ...props }: ComponentProps<'div'>) {
+  return (
+    <div
+      data-slot="alert-title"
+      className={cn('col-start-2 min-h-4 font-medium tracking-tight', className)}
+      {...props}
+    />
+  );
+}
+
+function AlertDescription({ className, ...props }: ComponentProps<'div'>) {
+  return (
+    <div
+      data-slot="alert-description"
+      className={cn(
+        'col-start-2 grid justify-items-start gap-1 text-sm text-muted-foreground [&_p]:leading-relaxed',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export { Alert, AlertDescription, AlertTitle };

package/templates/storefront-shadcn/src/components/ui/badge.tsx

@@ -0,0 +1,40 @@
+import { Slot } from '@radix-ui/react-slot';
+import { cva, type VariantProps } from 'class-variance-authority';
+import type { ComponentProps } from 'react';
+
+import { cn } from './utils';
+
+/**
+ * The shadcn/ui badge — the cart count, a subscription line's label, an
+ * applied coupon. As with the button, the variant shadcn/ui paints with a raw
+ * `text-white` is not vendored: every colour here is a token.
+ */
+const badgeVariants = cva(
+  'inline-flex w-fit shrink-0 items-center justify-center gap-1 overflow-hidden whitespace-nowrap rounded-md border px-2 py-0.5 text-xs font-medium transition-[color,box-shadow] focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 aria-invalid:border-destructive aria-invalid:ring-destructive/20 [&>svg]:pointer-events-none [&>svg]:size-3',
+  {
+    variants: {
+      variant: {
+        default: 'border-transparent bg-primary text-primary-foreground [a&]:hover:bg-primary/90',
+        secondary:
+          'border-transparent bg-secondary text-secondary-foreground [a&]:hover:bg-secondary/90',
+        outline: 'text-foreground [a&]:hover:bg-accent [a&]:hover:text-accent-foreground',
+      },
+    },
+    defaultVariants: {
+      variant: 'default',
+    },
+  },
+);
+
+function Badge({
+  className,
+  variant,
+  asChild = false,
+  ...props
+}: ComponentProps<'span'> & VariantProps<typeof badgeVariants> & { asChild?: boolean }) {
+  const Comp = asChild ? Slot : 'span';
+
+  return <Comp data-slot="badge" className={cn(badgeVariants({ variant }), className)} {...props} />;
+}
+
+export { Badge, badgeVariants };

package/templates/storefront-shadcn/src/components/ui/button.tsx

@@ -0,0 +1,64 @@
+import { Slot } from '@radix-ui/react-slot';
+import { cva, type VariantProps } from 'class-variance-authority';
+import type { ComponentProps } from 'react';
+
+import { cn } from './utils';
+
+/**
+ * The shadcn/ui button. `buttonVariants` is exported on its own so a link
+ * styled as a button keeps its own element — `<LocaleLink className={
+ * buttonVariants()}>` stays one crawlable `<a>` — and `asChild` hands the
+ * classes to whatever single child it wraps instead.
+ *
+ * Every colour is a token of the `:root` block in `src/app/globals.css`; the
+ * template has no destructive action, so the variant shadcn/ui paints with a
+ * raw `text-white` is not vendored.
+ */
+const buttonVariants = cva(
+  "inline-flex shrink-0 items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium transition-all outline-none focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 disabled:pointer-events-none disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-destructive/20 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+  {
+    variants: {
+      variant: {
+        default: 'bg-primary text-primary-foreground shadow-xs hover:bg-primary/90',
+        secondary: 'bg-secondary text-secondary-foreground shadow-xs hover:bg-secondary/80',
+        outline:
+          'border bg-background shadow-xs hover:bg-accent hover:text-accent-foreground',
+        ghost: 'hover:bg-accent hover:text-accent-foreground',
+        link: 'text-primary underline-offset-4 hover:underline',
+      },
+      size: {
+        default: 'h-9 px-4 py-2 has-[>svg]:px-3',
+        sm: 'h-8 gap-1.5 rounded-md px-3 has-[>svg]:px-2.5',
+        lg: 'h-10 rounded-md px-6 has-[>svg]:px-4',
+        icon: 'size-9',
+      },
+    },
+    defaultVariants: {
+      variant: 'default',
+      size: 'default',
+    },
+  },
+);
+
+function Button({
+  className,
+  variant,
+  size,
+  asChild = false,
+  ...props
+}: ComponentProps<'button'> &
+  VariantProps<typeof buttonVariants> & {
+    asChild?: boolean;
+  }) {
+  const Comp = asChild ? Slot : 'button';
+
+  return (
+    <Comp
+      data-slot="button"
+      className={cn(buttonVariants({ variant, size, className }))}
+      {...props}
+    />
+  );
+}
+
+export { Button, buttonVariants };

package/templates/storefront-shadcn/src/components/ui/card.tsx

@@ -0,0 +1,28 @@
+import type { ComponentProps } from 'react';
+
+import { cn } from './utils';
+
+/**
+ * The shadcn/ui card: a raised `bg-card` surface with its border and radius.
+ * The template's cards carry their own headings — a product tile's `<h3>`, a
+ * cart panel's `<h2>` — so the heading level stays the page's decision, and
+ * `CardContent` pads whatever sits inside.
+ */
+function Card({ className, ...props }: ComponentProps<'div'>) {
+  return (
+    <div
+      data-slot="card"
+      className={cn(
+        'flex flex-col gap-6 rounded-xl border bg-card py-6 text-card-foreground shadow-sm',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+function CardContent({ className, ...props }: ComponentProps<'div'>) {
+  return <div data-slot="card-content" className={cn('px-6', className)} {...props} />;
+}
+
+export { Card, CardContent };

package/templates/storefront-shadcn/src/components/ui/input.tsx

@@ -0,0 +1,26 @@
+import type { ComponentProps } from 'react';
+
+import { cn } from './utils';
+
+/**
+ * The shadcn/ui text input. An invalid field is marked by `aria-invalid` —
+ * the attribute a screen reader announces is the one that paints the
+ * destructive border, so the two can never disagree.
+ */
+function Input({ className, type, ...props }: ComponentProps<'input'>) {
+  return (
+    <input
+      type={type}
+      data-slot="input"
+      className={cn(
+        'flex h-9 w-full min-w-0 rounded-md border border-input bg-transparent px-3 py-1 text-base shadow-xs transition-[color,box-shadow] outline-none selection:bg-primary selection:text-primary-foreground file:inline-flex file:h-7 file:border-0 file:bg-transparent file:text-sm file:font-medium file:text-foreground placeholder:text-muted-foreground disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-50 md:text-sm',
+        'focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50',
+        'aria-invalid:border-destructive aria-invalid:ring-destructive/20',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export { Input };

package/templates/storefront-shadcn/src/components/ui/label.tsx

@@ -0,0 +1,22 @@
+'use client';
+
+import * as LabelPrimitive from '@radix-ui/react-label';
+import type { ComponentProps } from 'react';
+
+import { cn } from './utils';
+
+/** The shadcn/ui form label, on Radix's label primitive. */
+function Label({ className, ...props }: ComponentProps<typeof LabelPrimitive.Root>) {
+  return (
+    <LabelPrimitive.Root
+      data-slot="label"
+      className={cn(
+        'flex items-center gap-2 text-sm leading-none font-medium select-none group-data-[disabled=true]:pointer-events-none group-data-[disabled=true]:opacity-50 peer-disabled:cursor-not-allowed peer-disabled:opacity-50',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export { Label };

package/templates/storefront-shadcn/src/components/ui/native-select.tsx

@@ -0,0 +1,27 @@
+import type { ComponentProps } from 'react';
+
+import { cn } from './utils';
+
+/**
+ * A native `<select>` dressed as a shadcn/ui field. The checkout's country
+ * select stays the browser's own control — it takes part in the form's
+ * `required` validation and in the platform's address autofill, which a
+ * custom listbox would have to rebuild — and only borrows the input's
+ * border, focus ring and `aria-invalid` treatment.
+ */
+function NativeSelect({ className, ...props }: ComponentProps<'select'>) {
+  return (
+    <select
+      data-slot="native-select"
+      className={cn(
+        'flex h-9 w-full min-w-0 rounded-md border border-input bg-transparent px-3 py-1 text-base shadow-xs transition-[color,box-shadow] outline-none disabled:cursor-not-allowed disabled:opacity-50 md:text-sm',
+        'focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50',
+        'aria-invalid:border-destructive aria-invalid:ring-destructive/20',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export { NativeSelect };

package/templates/storefront-shadcn/src/components/ui/skeleton.tsx

@@ -0,0 +1,21 @@
+import type { ComponentProps } from 'react';
+
+import { cn } from './utils';
+
+/**
+ * The shadcn/ui loading placeholder. It pulses on `bg-muted`, the quiet
+ * surface, rather than on `bg-accent`: this variant's accent carries the
+ * daisyUI baseline's strong highlight, which would turn every loading block
+ * near-black.
+ */
+function Skeleton({ className, ...props }: ComponentProps<'div'>) {
+  return (
+    <div
+      data-slot="skeleton"
+      className={cn('animate-pulse rounded-md bg-muted', className)}
+      {...props}
+    />
+  );
+}
+
+export { Skeleton };

package/templates/storefront-shadcn/src/components/ui/utils.ts

@@ -0,0 +1,16 @@
+import { clsx, type ClassValue } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+
+/**
+ * shadcn/ui's class helper: joins conditional classes (`clsx`) and lets a
+ * later utility win over an earlier one of the same group (`tailwind-merge`),
+ * so a component's own classes can be overridden from its `className`.
+ *
+ * It lives beside the vendored components rather than under `src/lib/`: the
+ * library holds the storefront's logic, which every row of the template set
+ * shares byte for byte, and this helper belongs to the shadcn/ui components
+ * alone. `components.json` points the shadcn/ui CLI's `utils` alias here.
+ */
+export function cn(...inputs: ClassValue[]): string {
+  return twMerge(clsx(inputs));
+}