@base44/app-plugin-commerce 0.2.1 → 0.2.2

package/src/commerce/utils/variants.js

@@ -11,8 +11,8 @@
  *
  * Framework-free, dependency-free, no I/O — feed them the `{ product,
  * variations }` pair from `commerce/storefront-catalog` `get-product` (the
- * admin's variation editor can use them too). See
- * `.agents/skills/commerce/references/catalog-rendering.md` for the UI rules.
+ * admin's variation editor can use them too). See the commerce skill's
+ * references/catalog-rendering.md for the UI rules.
  *
  * A `selection` throughout is a plain object keyed by axis key (see
  * `attributeKey`): `{ "<color-attr-id>": "Red", "<size-attr-id>": "M" }`.
@@ -435,3 +435,50 @@ export function selectionFromParams(product, variations, params) {
   }
   return selection;
 }
+
+/**
+ * A resolved view's axes as a render-ready model for the variant selector *you*
+ * write: one entry per axis, one entry per option, with selected / stock /
+ * disabled state already derived. All markup and styling are yours; the two
+ * rules this model encodes are **one control per axis** (never a flat list of
+ * variations) and **an unbuyable option renders disabled, not hidden** — a
+ * customer who can't see that a size exists assumes the store doesn't carry it.
+ *
+ *   const { view, pick } = useProduct(slug);
+ *   variantAxes(view, pick).map(axis =>
+ *     // axis.name, axis.selectedOption
+ *     axis.options.map(o =>
+ *       // o.value, o.selected, o.disabled (don't render clickable),
+ *       // o.outOfStock (strike through / mark, still visible), o.pick()
+ *     ));
+ *
+ * @param {object|null} view from `resolveSelection` / `useProduct().view`
+ * @param {(axisKey: string, option: string) => void} [pick] click handler to
+ *   bind per option (`useProduct().pick`)
+ * @returns {Array<{key: string, name: string, selectedOption: string|null,
+ *   options: Array<{value: string, selected: boolean, state: string,
+ *     outOfStock: boolean, disabled: boolean, pick: () => void}>}>}
+ *   `[]` for a product without variants — render nothing.
+ */
+export function variantAxes(view, pick) {
+  if (!view?.isVariable) return [];
+  return (view.axes ?? []).map((axis) => {
+    const selectedOption = view.selection?.[axis.key] || null;
+    return {
+      key: axis.key,
+      name: axis.name,
+      selectedOption,
+      options: (axis.options ?? []).map((option) => {
+        const state = view.availability?.[axis.key]?.[option] ?? OPTION_AVAILABLE;
+        return {
+          value: option,
+          selected: option === selectedOption,
+          state,
+          outOfStock: state === OPTION_OUT_OF_STOCK,
+          disabled: state === OPTION_UNAVAILABLE,
+          pick: () => pick?.(axis.key, option),
+        };
+      }),
+    };
+  });
+}

package/src/commerce/storefront/blocks/AddToCartBlock.jsx

@@ -1,86 +0,0 @@
-import React from "react";
-import { useAddToCart } from "../useProduct";
-
-/**
- * The buy button, with quantity, stock state and every add-to-cart failure
- * handled.
- *
- *   const p = useProduct(slug);
- *   <AddToCartBlock product={p} onAdded={() => navigate("/bag")} />
- *
- * Pass the whole `useProduct` result as `product` and it wires itself: the
- * button is gated on `view.purchasable`, the quantity respects
- * `sold_individually` and tracked stock, a rejected add (sold out, stale
- * variant) renders inline instead of leaving the button stuck on "Adding…", and
- * a stale-variant error reloads the product.
- *
- * @param {{product: object, className?: string, label?: string,
- *   addingLabel?: string, showQuantity?: boolean,
- *   onAdded?: (cart: object) => void}} props
- */
-export function AddToCartBlock({
-  product,
-  className = "",
-  label = "Add to bag",
-  addingLabel = "Adding…",
-  showQuantity = true,
-  onAdded,
-}) {
-  const { add, adding, error } = useAddToCart();
-  if (!product?.view) return null;
-
-  const { view, quantity, incQuantity, decQuantity, canIncrease, maxQuantity, reload } = product;
-  const soldOut = view.isVariable ? view.complete && !view.purchasable : !view.purchasable;
-
-  const onClick = async () => {
-    const res = await add(view.addToCart, quantity);
-    if (res.ok) onAdded?.(res.cart);
-    else if (res.error?.shouldReload) reload?.();
-  };
-
-  return (
-    <div data-commerce="add-to-cart-block" className={className}>
-      {showQuantity && maxQuantity > 1 && (
-        <div className="mb-3 flex items-center gap-1">
-          <button
-            type="button"
-            data-commerce="product-quantity-decrease"
-            onClick={decQuantity}
-            disabled={quantity <= 1}
-            aria-label="Decrease quantity"
-            className="h-9 w-9 border border-border disabled:opacity-40"
-          >
-            −
-          </button>
-          <span data-commerce="product-quantity" className="w-10 text-center text-sm">{quantity}</span>
-          <button
-            type="button"
-            data-commerce="product-quantity-increase"
-            onClick={incQuantity}
-            disabled={!canIncrease}
-            aria-label="Increase quantity"
-            className="h-9 w-9 border border-border disabled:opacity-40"
-          >
-            +
-          </button>
-        </div>
-      )}
-
-      <button
-        type="button"
-        data-commerce="add-to-cart"
-        onClick={onClick}
-        disabled={!view.purchasable || adding}
-        className="w-full bg-primary px-6 py-3 text-sm text-primary-foreground disabled:opacity-50"
-      >
-        {adding ? addingLabel : soldOut ? "Sold out" : !view.complete ? "Select options" : label}
-      </button>
-
-      {error && (
-        <p data-commerce="add-to-cart-error" role="alert" className="mt-2 text-sm text-destructive">
-          {error.message}
-        </p>
-      )}
-    </div>
-  );
-}

package/src/commerce/storefront/blocks/AddressFieldsBlock.jsx

@@ -1,96 +0,0 @@
-import React from "react";
-import { useAddressForm } from "../useAddressForm";
-import { useCheckoutContext } from "../useCheckout";
-
-/**
- * The checkout address form, rendered from the field spec — so `state` is
- * collected (rates and taxes match on country + state), the country select
- * never maps a null list, and browser autofill works.
- *
- *   <AddressFieldsBlock />                       // billing
- *   <AddressFieldsBlock which="shipping" />      // a separate delivery address
- *
- * Needs a `<CheckoutProvider>` above it (`<CheckoutBlock/>` supplies one).
- *
- * @param {{which?: "billing"|"shipping", className?: string, legend?: string,
- *   includeCompany?: boolean, includePhone?: boolean}} props
- */
-export function AddressFieldsBlock({
-  which = "billing",
-  className = "",
-  legend,
-  includeCompany = false,
-  includePhone = true,
-}) {
-  const { fields, set, countriesLoading } = useAddressForm(which, { includeCompany, includePhone });
-
-  return (
-    <fieldset data-commerce={`address-${which}`} className={className}>
-      {legend && <legend className="mb-3 text-xs uppercase tracking-wide text-muted-foreground">{legend}</legend>}
-      <div className="grid grid-cols-2 gap-3">
-        {fields.map((f) => (
-          <label
-            key={f.key}
-            className={f.colSpan === 2 ? "col-span-2" : "col-span-2 sm:col-span-1"}
-          >
-            <span className="block text-xs text-muted-foreground">
-              {f.label}
-              {f.required && <span aria-hidden> *</span>}
-            </span>
-            {f.type === "select" ? (
-              <select
-                data-commerce={`address-field-${f.key}`}
-                value={f.value}
-                required={f.required}
-                onChange={(e) => set(f.key, e.target.value)}
-                autoComplete={f.autoComplete}
-                disabled={f.key === "country" && countriesLoading}
-                className="mt-1 w-full border border-border bg-transparent px-3 py-2 text-sm"
-              >
-                <option value="">
-                  {f.key === "country" && countriesLoading ? "Loading…" : `Select ${f.label.toLowerCase()}`}
-                </option>
-                {f.options.map((o) => (
-                  <option key={o.value} value={o.value}>
-                    {o.label}
-                  </option>
-                ))}
-              </select>
-            ) : (
-              <input
-                data-commerce={`address-field-${f.key}`}
-                type={f.type}
-                value={f.value}
-                required={f.required}
-                onChange={(e) => set(f.key, e.target.value)}
-                autoComplete={f.autoComplete}
-                className="mt-1 w-full border border-border bg-transparent px-3 py-2 text-sm"
-              />
-            )}
-            {f.error && (
-              <span role="alert" className="mt-1 block text-xs text-destructive">
-                {f.error}
-              </span>
-            )}
-          </label>
-        ))}
-      </div>
-      {which === "billing" && <ShipToDifferentToggle />}
-    </fieldset>
-  );
-}
-
-function ShipToDifferentToggle() {
-  const { shipToDifferent, setShipToDifferent } = useCheckoutContext();
-  return (
-    <label className="mt-3 flex items-center gap-2 text-sm">
-      <input
-        type="checkbox"
-        data-commerce="ship-to-different"
-        checked={shipToDifferent}
-        onChange={(e) => setShipToDifferent(e.target.checked)}
-      />
-      Deliver to a different address
-    </label>
-  );
-}

package/src/commerce/storefront/blocks/BreadcrumbsBlock.jsx

@@ -1,52 +0,0 @@
-import React from "react";
-
-/**
- * Category breadcrumbs for a product page.
- *
- *   <BreadcrumbsBlock categories={categories} current={product.name} />
- *
- * Ribbons are deliberately NOT breadcrumbs — they are labels ("Best Seller"),
- * not places in the catalog. Pass `renderLink` to use your router's `<Link>`
- * instead of a plain anchor.
- *
- * @param {{categories?: Array<object>, current?: string, className?: string,
- *   homeLabel?: string, homeHref?: string, categoryHref?: (c: object) => string,
- *   renderLink?: (o: {href: string, label: string}) => React.ReactNode}} props
- */
-export function BreadcrumbsBlock({
-  categories = [],
-  current,
-  className = "",
-  homeLabel = "Home",
-  homeHref = "/",
-  categoryHref = (c) => `/collection?category_id=${c.id}`,
-  renderLink,
-}) {
-  const crumbs = [
-    { href: homeHref, label: homeLabel },
-    ...categories.map((c) => ({ href: categoryHref(c), label: c.name })),
-  ];
-
-  const link = ({ href, label }) =>
-    renderLink ? (
-      renderLink({ href, label })
-    ) : (
-      <a href={href} className="underline-offset-2 hover:underline">
-        {label}
-      </a>
-    );
-
-  return (
-    <nav data-commerce="breadcrumbs" aria-label="Breadcrumb" className={`text-xs text-muted-foreground ${className}`}>
-      <ol className="flex flex-wrap items-center gap-1.5">
-        {crumbs.map((c) => (
-          <li key={`${c.href}-${c.label}`} className="flex items-center gap-1.5">
-            {link(c)}
-            <span aria-hidden>/</span>
-          </li>
-        ))}
-        {current && <li aria-current="page">{current}</li>}
-      </ol>
-    </nav>
-  );
-}

package/src/commerce/storefront/blocks/CartLinesBlock.jsx

@@ -1,98 +0,0 @@
-import React from "react";
-import { useCart } from "../StorefrontProvider";
-import { useFormatMoney } from "../StorefrontProvider";
-import { QuantityStepper } from "./QuantityStepper";
-import { CouponFieldBlock } from "./CouponFieldBlock";
-
-/**
- * The bag's line items: image, name, variant label, quantity stepper, line
- * total — plus the notices that say what auto-dropped and why, and the coupon
- * field.
- *
- *   <CartLinesBlock />
- *
- * Branches on the cart's `status`, so it never flashes an empty state while the
- * cart is still loading. Pass `slots.empty` / `slots.loading` to brand those
- * two states, or `renderLine` to take over a row entirely.
- *
- * **The coupon field is on by default** (`showCoupon`). A store whose codes have
- * nowhere to be typed cannot honour its own discounts, and that has been the
- * most-repeated omission in hand-built storefronts — so the default is the safe
- * one. Turn it off for a store that has no coupons and doesn't want the field,
- * or when your checkout carries the only one.
- *
- * @param {{className?: string, showNotices?: boolean, showCoupon?: boolean,
- *   slots?: {empty?: React.ReactNode, loading?: React.ReactNode},
- *   renderLine?: (line: object) => React.ReactNode}} props
- */
-export function CartLinesBlock({
-  className = "",
-  showNotices = true,
-  showCoupon = true,
-  slots = {},
-  renderLine,
-}) {
-  const { status, lines, notices } = useCart();
-  const formatMoney = useFormatMoney();
-
-  if (status === "loading") {
-    return slots.loading ?? <p data-commerce="cart-loading" className="text-sm text-muted-foreground">Loading your bag…</p>;
-  }
-  if (status === "empty") {
-    return slots.empty ?? <p data-commerce="cart-empty" className="text-sm text-muted-foreground">Your bag is empty.</p>;
-  }
-
-  return (
-    <div data-commerce="cart-lines" className={className}>
-      {showNotices && notices.length > 0 && (
-        <ul data-commerce="cart-notices" className="mb-4 space-y-1">
-          {notices.map((n, i) => (
-            <li key={`${n.code}-${i}`} role="status" className="text-xs text-muted-foreground">
-              {n.message}
-            </li>
-          ))}
-        </ul>
-      )}
-
-      <ul className="divide-y divide-border">
-        {lines.map((line) =>
-          renderLine ? (
-            <React.Fragment key={line.item_key}>{renderLine(line)}</React.Fragment>
-          ) : (
-            <li
-              key={line.item_key}
-              data-commerce="line-item"
-              className="grid grid-cols-[64px_1fr_auto] items-start gap-4 py-4"
-            >
-              {line.image ? (
-                <img
-                  src={line.image.src}
-                  alt={line.image.alt}
-                  className="aspect-square w-16 object-cover"
-                  loading="lazy"
-                />
-              ) : (
-                <div aria-hidden className="aspect-square w-16 bg-muted" />
-              )}
-              <div className="min-w-0">
-                <p data-commerce="line-name" className="truncate text-sm">{line.name}</p>
-                {line.attributesLabel && (
-                  <p data-commerce="line-attributes" className="mt-0.5 text-xs text-muted-foreground">
-                    {line.attributesLabel}
-                  </p>
-                )}
-                {!line.purchasable && line.unavailableReason && (
-                  <p role="alert" className="mt-1 text-xs text-destructive">{line.unavailableReason}</p>
-                )}
-                <QuantityStepper line={line} className="mt-2" />
-              </div>
-              <p data-commerce="line-total" className="text-sm">{formatMoney(line.total)}</p>
-            </li>
-          ),
-        )}
-      </ul>
-
-      {showCoupon && <CouponFieldBlock className="mt-6" />}
-    </div>
-  );
-}

package/src/commerce/storefront/blocks/CheckoutBlock.jsx

@@ -1,247 +0,0 @@
-import React from "react";
-import { CheckoutProvider, useCheckoutContext } from "../useCheckout";
-import { PaymentMethodPicker, ShippingMethodPicker } from "../pickers";
-import { useCart, useFormatMoney } from "../StorefrontProvider";
-import { useCheckoutBlockers } from "../useTotalsLines";
-import { AddressFieldsBlock } from "./AddressFieldsBlock";
-import { CouponFieldBlock } from "./CouponFieldBlock";
-import { TotalsBlock } from "./TotalsBlock";
-
-/**
- * The whole checkout: address → delivery → payment → summary → place order.
- * It supplies its own `<CheckoutProvider>`, so this is a complete page body:
- *
- *   export default function Checkout() {
- *     return <main className="mx-auto max-w-3xl px-6 py-16">
- *       <h1 className="font-heading text-5xl">Checkout</h1>
- *       <CheckoutBlock />
- *     </main>;
- *   }
- *
- * Correct with zero props in a default-seeded store (one manual gateway, one
- * shipping rate), and every branch a checkout must handle is already wired:
- * shipping recalculates from the address, a single shipping/payment option
- * reads as selected, a store with no enabled gateway says so instead of
- * rendering a dead button, the place-order gate explains itself, and an offline
- * order's payment instructions are shown on the confirmation.
- *
- * Restyle it with `className`, replace one region with `slots`, or drop to the
- * hooks (`useCheckout`, `useAddressForm`, the pickers, `useTotalsLines`) when
- * the design needs different structure — this component is nothing but a
- * composition of them.
- *
- * @param {{className?: string, showCoupon?: boolean, options?: object,
- *   onPlaced?: (result: object) => void, orderReceivedPath?: string,
- *   slots?: {address?, shipping?, payment?, summary?, submit?, empty?}}} props
- *   `onPlaced` overrides the default post-order behaviour (navigating to
- *   `orderReceivedPath` with the order's id + key, where `<OrderReceivedBlock/>`
- *   renders the confirmation and any payment instructions).
- */
-export function CheckoutBlock({
-  className = "",
-  showCoupon = true,
-  options,
-  onPlaced,
-  orderReceivedPath = "/order-received",
-  slots = {},
-}) {
-  return (
-    <CheckoutProvider options={options}>
-      <CheckoutBody
-        className={className}
-        showCoupon={showCoupon}
-        onPlaced={onPlaced}
-        orderReceivedPath={orderReceivedPath}
-        slots={slots}
-      />
-    </CheckoutProvider>
-  );
-}
-
-function CheckoutBody({ className, showCoupon, onPlaced, orderReceivedPath, slots }) {
-  const { status } = useCart();
-  const checkout = useCheckoutContext();
-
-  if (status === "loading") {
-    return <p data-commerce="checkout-loading" className="text-sm text-muted-foreground">Loading…</p>;
-  }
-  if (status === "empty") {
-    return (
-      slots.empty ?? (
-        <p data-commerce="checkout-empty" className="text-sm text-muted-foreground">
-          Your bag is empty — add something before checking out.
-        </p>
-      )
-    );
-  }
-
-  return (
-    <div data-commerce="checkout" className={`grid gap-10 md:grid-cols-[1fr_360px] ${className}`}>
-      <div className="space-y-8">
-        {slots.address ?? <AddressFieldsBlock legend="Your details" />}
-        {checkout.shipToDifferent && <AddressFieldsBlock which="shipping" legend="Delivery address" />}
-        {slots.shipping ?? <ShippingStep />}
-        {slots.payment ?? <PaymentStep />}
-      </div>
-
-      <aside className="space-y-6">
-        {slots.summary ?? (
-          <>
-            {showCoupon && <CouponFieldBlock />}
-            <TotalsBlock />
-          </>
-        )}
-        {slots.submit ?? <PlaceOrder onPlaced={onPlaced} orderReceivedPath={orderReceivedPath} />}
-      </aside>
-    </div>
-  );
-}
-
-function ShippingStep() {
-  const formatMoney = useFormatMoney();
-  return (
-    <ShippingMethodPicker>
-      {({ status, methods, chosen, choose, mustChoose, single, syncing }) => (
-        <fieldset data-commerce="shipping-step" className={syncing ? "opacity-60" : ""}>
-          <legend className="mb-3 text-xs uppercase tracking-wide text-muted-foreground">Delivery</legend>
-
-          {status === "missing_address" && (
-            <p className="text-sm text-muted-foreground">
-              Delivery options appear once your address is entered.
-            </p>
-          )}
-
-          {status === "none_available" && (
-            <p role="alert" className="text-sm text-destructive">
-              We don't deliver to that address yet.
-            </p>
-          )}
-
-          {mustChoose &&
-            methods.map((m) => (
-              <label key={m.id} data-commerce="shipping-method" data-commerce-cost={m.cost} className="flex items-center justify-between gap-4 py-1.5 text-sm">
-                <span className="flex items-center gap-2">
-                  <input
-                    type="radio"
-                    name="shipping_method"
-                    value={m.id}
-                    checked={chosen?.id === m.id}
-                    onChange={() => choose(m.id)}
-                  />
-                  {m.title}
-                </span>
-                <span>{formatMoney(m.cost)}</span>
-              </label>
-            ))}
-
-          {!mustChoose && chosen && (
-            <p data-commerce="shipping-method" data-commerce-cost={chosen.cost} className="flex justify-between gap-4 text-sm">
-              <span>{chosen.title}</span>
-              <span>{formatMoney(chosen.cost)}</span>
-            </p>
-          )}
-          {single && chosen && (
-            <p className="mt-1 text-xs text-muted-foreground">The only option for this address.</p>
-          )}
-        </fieldset>
-      )}
-    </ShippingMethodPicker>
-  );
-}
-
-function PaymentStep() {
-  return (
-    <PaymentMethodPicker>
-      {({ gateways, value, select, selected, single }) => (
-        <fieldset data-commerce="payment-step">
-          <legend className="mb-3 text-xs uppercase tracking-wide text-muted-foreground">Payment</legend>
-
-          {gateways.length === 0 && (
-            <p role="alert" className="text-sm text-destructive">
-              No payment method is available right now — please contact us to complete your order.
-            </p>
-          )}
-
-          {!single &&
-            gateways.map((g) => (
-              <label key={g.slug} data-commerce="payment-method" className="block py-1.5 text-sm">
-                <span className="flex items-center gap-2">
-                  <input
-                    type="radio"
-                    name="payment_method"
-                    value={g.slug}
-                    checked={value === g.slug}
-                    onChange={() => select(g.slug)}
-                  />
-                  {g.title}
-                </span>
-                {g.description && (
-                  <span className="ml-6 block text-xs text-muted-foreground">{g.description}</span>
-                )}
-              </label>
-            ))}
-
-          {single && selected && (
-            <div data-commerce="payment-method" className="text-sm">
-              <p>{selected.title}</p>
-              {selected.description && (
-                <p className="mt-0.5 text-xs text-muted-foreground">{selected.description}</p>
-              )}
-            </div>
-          )}
-        </fieldset>
-      )}
-    </PaymentMethodPicker>
-  );
-}
-
-function PlaceOrder({ onPlaced, orderReceivedPath }) {
-  const { canPlaceOrder, placing, placeOrder, orderError } = useCheckoutContext();
-  const blockers = useCheckoutBlockers();
-
-  const submit = async () => {
-    const res = await placeOrder();
-    if (!res.ok) return;
-    if (onPlaced) return onPlaced(res.result);
-    // An online gateway has already redirected. Everything else lands on the
-    // return page, which is also where a manual order's payment instructions
-    // are rendered — so the offline default confirms properly too.
-    if (!res.result.payment && typeof window !== "undefined") {
-      const q = new URLSearchParams({
-        order_id: res.result.order_id,
-        order_key: res.result.order_key,
-      });
-      window.location.assign(`${orderReceivedPath}?${q}`);
-    }
-  };
-
-  return (
-    <div>
-      <button
-        type="button"
-        data-commerce="place-order"
-        onClick={submit}
-        disabled={!canPlaceOrder || placing}
-        className="w-full bg-primary px-6 py-3 text-sm text-primary-foreground disabled:opacity-50"
-      >
-        {placing ? "Placing your order…" : "Place order"}
-      </button>
-
-      {orderError && (
-        <p data-commerce="order-error" role="alert" className="mt-2 text-sm text-destructive">
-          {orderError.message}
-        </p>
-      )}
-
-      {!canPlaceOrder && blockers.length > 0 && (
-        <ul data-commerce="checkout-blockers" className="mt-2 space-y-1">
-          {blockers.map((b) => (
-            <li key={b.code} className="text-xs text-muted-foreground">
-              {b.message}
-            </li>
-          ))}
-        </ul>
-      )}
-    </div>
-  );
-}