@base44/app-plugin-commerce 0.1.20 → 0.2.1

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

@@ -0,0 +1,129 @@
+import React from "react";
+import { orderLines } from "@/commerce/utils";
+import { useOrderReturn } from "../useOrderReturn";
+import { useFormatMoney } from "../StorefrontProvider";
+import { useStorefrontSeo, orderSeo } from "../useStorefrontSeo";
+import { TotalsBlock } from "./TotalsBlock";
+
+/**
+ * The `/order-received` page. Mounting this route is **mandatory** — every
+ * payment link returns here, and confirming is what marks a card order paid.
+ *
+ *   export default function OrderReceived() {
+ *     return <main className="mx-auto max-w-2xl px-6 py-20">
+ *       <OrderReceivedBlock />
+ *     </main>;
+ *   }
+ *
+ * It renders all five states, including the two that hand-written pages drop:
+ * **`paymentInstructions` for a manual/offline order** — the default gateway, so
+ * without them the store's normal customer is told nothing about how to pay —
+ * and the pay-now link for an unpaid card order. The page is also `noindex`, as
+ * a receipt carrying an order key should be.
+ *
+ * @param {{className?: string, slots?: {paid?, unpaid?, cancelled?, loading?},
+ *   showSummary?: boolean}} props
+ */
+export function OrderReceivedBlock({ className = "", slots = {}, showSummary = true }) {
+  const { status, order, paymentLink, paymentInstructions, error, reload } = useOrderReturn();
+  useStorefrontSeo(orderSeo(order));
+  const formatMoney = useFormatMoney();
+
+  if (status === "loading") {
+    return slots.loading ?? <p data-commerce="order-loading" className="text-sm text-muted-foreground">Confirming your order…</p>;
+  }
+
+  if (status === "error") {
+    return (
+      <div data-commerce="order-error" role="alert" className={className}>
+        <p className="text-sm text-destructive">{error?.message}</p>
+        <button type="button" onClick={() => reload()} className="mt-3 border border-border px-4 py-2 text-sm">
+          Try again
+        </button>
+      </div>
+    );
+  }
+
+  const lines = orderLines(order);
+
+  return (
+    <div data-commerce="order-received" data-commerce-status={status} className={className}>
+      {status === "paid" && (slots.paid ?? <h2 className="text-2xl">Thank you — your order is confirmed.</h2>)}
+
+      {status === "unpaid" &&
+        (slots.unpaid ?? (
+          <div>
+            <h2 className="text-2xl">Your order is awaiting payment.</h2>
+            {paymentLink?.url && (
+              <a
+                href={paymentLink.url}
+                data-commerce="pay-now"
+                className="mt-4 inline-block bg-primary px-6 py-3 text-sm text-primary-foreground"
+              >
+                Pay now
+              </a>
+            )}
+          </div>
+        ))}
+
+      {status === "cancelled" &&
+        (slots.cancelled ?? (
+          <div>
+            <h2 className="text-2xl">Payment was cancelled.</h2>
+            {paymentLink?.url && (
+              <a href={paymentLink.url} data-commerce="pay-now" className="mt-4 inline-block border border-border px-6 py-3 text-sm">
+                Try payment again
+              </a>
+            )}
+          </div>
+        ))}
+
+      {order?.order_number && (
+        <p data-commerce="order-number" className="mt-2 text-sm text-muted-foreground">
+          Order {order.order_number}
+        </p>
+      )}
+
+      {/* A manual gateway settles outside the store: these ARE the instructions
+          for how the customer pays, so they must never be dropped. */}
+      {paymentInstructions && (
+        <section data-commerce="payment-instructions" className="mt-6 border border-border p-4">
+          <h3 className="text-xs uppercase tracking-wide text-muted-foreground">How to pay</h3>
+          {paymentInstructions.description && (
+            <p className="mt-2 whitespace-pre-line text-sm">{paymentInstructions.description}</p>
+          )}
+          {paymentInstructions.account_details && (
+            <dl className="mt-3 space-y-1 text-sm">
+              {Object.entries(paymentInstructions.account_details).map(([k, v]) => (
+                <div key={k} className="flex gap-2">
+                  <dt className="text-muted-foreground">{k.replace(/_/g, " ")}:</dt>
+                  <dd>{String(v)}</dd>
+                </div>
+              ))}
+            </dl>
+          )}
+        </section>
+      )}
+
+      {showSummary && lines.length > 0 && (
+        <section className="mt-8">
+          <ul className="divide-y divide-border">
+            {lines.map((l, i) => (
+              <li key={l.item_key ?? `${l.name}-${i}`} data-commerce="order-line" className="flex justify-between gap-4 py-3 text-sm">
+                <span>
+                  {l.name}
+                  {l.attributesLabel && <span className="text-muted-foreground"> · {l.attributesLabel}</span>}
+                  <span className="text-muted-foreground"> × {l.quantity}</span>
+                </span>
+                <span>{formatMoney(l.total)}</span>
+              </li>
+            ))}
+          </ul>
+          <div className="mt-4">
+            <TotalsBlock order={order} />
+          </div>
+        </section>
+      )}
+    </div>
+  );
+}

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

@@ -0,0 +1,66 @@
+import React from "react";
+import { useProductGallery } from "../useProductGallery";
+
+/**
+ * The product gallery: main image, thumbnail strip, and the active image
+ * following the variant selection.
+ *
+ *   <ProductGalleryBlock product={product} view={view} />
+ *
+ * The image objects, the placeholder case and the follow-the-variant behaviour
+ * all come from `useProductGallery`; this adds the minimum markup. Style it
+ * with `className`/`imageClassName` (aspect ratio, crossfade, object-fit are
+ * yours), or pass `slots.placeholder` for a branded empty state.
+ *
+ * @param {{product: object, view?: object, className?: string,
+ *   imageClassName?: string, showThumbnails?: boolean,
+ *   slots?: {placeholder?: React.ReactNode}}} props
+ */
+export function ProductGalleryBlock({
+  product,
+  view = null,
+  className = "",
+  imageClassName = "aspect-[4/5] w-full object-cover",
+  showThumbnails = true,
+  slots = {},
+}) {
+  const g = useProductGallery(product, view);
+
+  if (!g.hasImages) {
+    return (
+      slots.placeholder ?? (
+        <div data-commerce="gallery-placeholder" aria-hidden className={`${imageClassName} bg-muted ${className}`} />
+      )
+    );
+  }
+
+  return (
+    <div data-commerce="gallery" className={className}>
+      <img
+        data-commerce="gallery-image"
+        key={g.active.src}
+        src={g.active.src}
+        alt={g.active.alt || product?.name || ""}
+        className={imageClassName}
+      />
+
+      {showThumbnails && g.images.length > 1 && (
+        <div data-commerce="gallery-thumbnails" className="mt-2 flex gap-2 overflow-x-auto">
+          {g.images.map((img, i) => (
+            <button
+              key={img.src}
+              type="button"
+              data-commerce="gallery-thumbnail"
+              aria-label={`View image ${i + 1}`}
+              aria-current={i === g.activeIndex}
+              onClick={() => g.setActiveIndex(i)}
+              className={`shrink-0 border ${i === g.activeIndex ? "border-foreground" : "border-transparent"}`}
+            >
+              <img src={img.src} alt="" className="h-16 w-14 object-cover" loading="lazy" />
+            </button>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}

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

@@ -0,0 +1,33 @@
+import React from "react";
+
+/**
+ * A product's descriptive properties as a spec table — Material, Care, Fit.
+ *
+ *   <ProductSpecsBlock product={product} />
+ *
+ * These live in `product.meta_data` (the admin's *Modifiers* section) and are
+ * **not** attributes and not ribbons: they describe the product, they don't
+ * select a variant. Hidden keys (leading `_`) are skipped.
+ *
+ * @param {{product: object, className?: string, title?: string}} props
+ */
+export function ProductSpecsBlock({ product, className = "", title }) {
+  const entries = (product?.meta_data ?? []).filter(
+    (m) => m?.key && !String(m.key).startsWith("_") && m.value != null && m.value !== "",
+  );
+  if (!entries.length) return null;
+
+  return (
+    <section data-commerce="product-specs" className={className}>
+      {title && <h3 className="mb-2 text-xs uppercase tracking-wide text-muted-foreground">{title}</h3>}
+      <dl className="divide-y divide-border">
+        {entries.map((m) => (
+          <div key={m.key} className="flex justify-between gap-4 py-2 text-sm">
+            <dt className="text-muted-foreground">{String(m.key).replace(/_/g, " ")}</dt>
+            <dd className="text-right">{String(m.value)}</dd>
+          </div>
+        ))}
+      </dl>
+    </section>
+  );
+}

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

@@ -0,0 +1,55 @@
+import React from "react";
+import { useProductList } from "../useProductList";
+
+/**
+ * A row of products — a featured rail, "new in", upsells beside a product, a
+ * few picks under an article.
+ *
+ *   <ProductStripBlock params={{ featured: true, per_page: 4 }}
+ *                      renderCard={(p) => <MyCard key={p.id} product={p} />} />
+ *
+ * **`renderCard` is required and has no default**: the product card is the most
+ * identity-defining component in a storefront, so the kit never ships one. What
+ * this block owns is everything around it — the query, the loading state, and
+ * the fact that any filter may legitimately match nothing (nobody has starred a
+ * product, nothing is on sale), in which case the strip renders nothing at all
+ * rather than an empty row with a heading.
+ *
+ * Give it `products` instead of `params` to render rows you already have (a
+ * product page's `upsells`/`crossSells`).
+ *
+ * @param {{renderCard: (product: object) => React.ReactNode, params?: object,
+ *   products?: Array<object>, title?: string, className?: string,
+ *   listClassName?: string, slots?: {loading?: React.ReactNode}}} props
+ */
+export function ProductStripBlock({
+  renderCard,
+  params,
+  products: given,
+  title,
+  className = "",
+  listClassName = "grid grid-cols-2 gap-6 md:grid-cols-4",
+  slots = {},
+}) {
+  const enabled = !given;
+  const list = useProductList(params ?? {}, { perPage: params?.per_page ?? 4 });
+  const rows = given ?? (enabled ? list.products : []);
+  const loading = enabled && list.loading;
+
+  if (loading) return slots.loading ?? null;
+  // A filter that matched nothing is normal — render nothing, not a bare heading.
+  if (!rows.length) return null;
+
+  return (
+    <section data-commerce="product-strip" className={className}>
+      {title && <h2 className="mb-4 text-xs uppercase tracking-wide text-muted-foreground">{title}</h2>}
+      <ul className={listClassName}>
+        {rows.map((p) => (
+          <li key={p.id} data-commerce="product-card">
+            {renderCard(p)}
+          </li>
+        ))}
+      </ul>
+    </section>
+  );
+}

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

@@ -0,0 +1,62 @@
+import React from "react";
+import { useCartLine } from "../useCartLine";
+
+/**
+ * A cart line's quantity control: − / value / + plus Remove, with stock
+ * rejections rendered inline and rapid clicks coalesced.
+ *
+ *   <QuantityStepper line={line} />
+ *
+ * @param {{line: object, className?: string, showRemove?: boolean,
+ *   removeLabel?: string}} props `line` comes from `useCart().lines`
+ */
+export function QuantityStepper({ line, className = "", showRemove = true, removeLabel = "Remove" }) {
+  const l = useCartLine(line);
+  if (!line) return null;
+
+  return (
+    <div data-commerce="quantity" className={className}>
+      <div className="flex items-center gap-1">
+        <button
+          type="button"
+          data-commerce="quantity-decrease"
+          onClick={l.decrease}
+          disabled={!l.canDecrease || l.pending}
+          aria-label="Decrease quantity"
+          className="h-8 w-8 border border-border disabled:opacity-40"
+        >
+          −
+        </button>
+        <span data-commerce="quantity-value" aria-live="polite" className="w-10 text-center text-sm">
+          {l.quantity}
+        </span>
+        <button
+          type="button"
+          data-commerce="quantity-increase"
+          onClick={l.increase}
+          disabled={!l.canIncrease || l.pending}
+          aria-label="Increase quantity"
+          className="h-8 w-8 border border-border disabled:opacity-40"
+        >
+          +
+        </button>
+        {showRemove && (
+          <button
+            type="button"
+            data-commerce="line-remove"
+            onClick={l.remove}
+            disabled={l.pending}
+            className="ml-3 text-xs uppercase tracking-wide text-muted-foreground underline disabled:opacity-40"
+          >
+            {removeLabel}
+          </button>
+        )}
+      </div>
+      {l.error && (
+        <p data-commerce="quantity-error" role="alert" className="mt-1 text-xs text-destructive">
+          {l.error.message}
+        </p>
+      )}
+    </div>
+  );
+}

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

@@ -0,0 +1,191 @@
+import React from "react";
+import { useProductReviews } from "../useProductReviews";
+
+/**
+ * The reviews section: the list, the aggregate rating, and the submit form —
+ * including the store's policy and the right confirmation copy.
+ *
+ *   <ReviewsBlock product={product} />                        // anyone with an email
+ *   <ReviewsBlock product={product} policy="login" user={user} />
+ *   <ReviewsBlock product={product} policy="verified_buyers" user={user} />
+ *
+ * The backend ships complete; what this adds is the whole UI contract that used
+ * to be hand-rolled: field-level validation matching the server's error codes,
+ * the email field hidden for a signed-in visitor (the session's email wins
+ * server-side anyway), paging, a refresh after an auto-approved submission, and
+ * confirmation text **taken from the response** — a store with auto-approval on
+ * is told "published", not "awaiting approval".
+ *
+ * @param {{product: object, policy?: "open"|"login"|"verified_buyers",
+ *   user?: object|null, requireRating?: boolean, className?: string,
+ *   title?: string, showForm?: boolean,
+ *   slots?: {blocked?: React.ReactNode}}} props
+ */
+export function ReviewsBlock({
+  product,
+  policy = "open",
+  user = null,
+  requireRating = false,
+  className = "",
+  title = "Reviews",
+  showForm = true,
+  slots = {},
+}) {
+  const r = useProductReviews(product, { policy, user, requireRating });
+
+  return (
+    <section data-commerce="reviews" className={className}>
+      <header className="flex items-baseline justify-between gap-4">
+        <h2 className="text-xs uppercase tracking-wide text-muted-foreground">{title}</h2>
+        {r.ratingCount > 0 && (
+          <p data-commerce="reviews-summary" className="text-sm">
+            {Number(r.averageRating).toFixed(1)} / 5
+            <span className="text-muted-foreground"> · {r.ratingCount} review{r.ratingCount === 1 ? "" : "s"}</span>
+          </p>
+        )}
+      </header>
+
+      {r.loading ? (
+        <p className="mt-4 text-sm text-muted-foreground">Loading reviews…</p>
+      ) : r.items.length === 0 ? (
+        <p data-commerce="reviews-empty" className="mt-4 text-sm text-muted-foreground">
+          No reviews yet.
+        </p>
+      ) : (
+        <ul className="mt-4 divide-y divide-border">
+          {r.items.map((review) => (
+            <li key={review.id} data-commerce="review" className="py-4">
+              <p className="text-sm">
+                <span className="font-medium">{review.reviewer}</span>
+                {review.rating ? <span className="text-muted-foreground"> · {review.rating}/5</span> : null}
+                {review.verified && (
+                  <span data-commerce="review-verified" className="text-muted-foreground"> · Verified buyer</span>
+                )}
+              </p>
+              <p className="mt-1 whitespace-pre-line text-sm">{review.review}</p>
+            </li>
+          ))}
+        </ul>
+      )}
+
+      {r.hasNext && (
+        <button
+          type="button"
+          data-commerce="reviews-more"
+          onClick={r.loadMore}
+          className="mt-4 border border-border px-4 py-2 text-sm"
+        >
+          Load more reviews
+        </button>
+      )}
+
+      {showForm && (
+        <div className="mt-8">
+          {r.submitted ? (
+            <p data-commerce="review-submitted" role="status" className="text-sm">{r.message}</p>
+          ) : r.reviewBlockedReason ? (
+            (slots.blocked ?? (
+              <p data-commerce="review-blocked" className="text-sm text-muted-foreground">
+                {r.reviewBlockedReason === "login_required"
+                  ? "Sign in to write a review."
+                  : "Only verified buyers can review this product."}
+              </p>
+            ))
+          ) : (
+            <ReviewForm r={r} />
+          )}
+        </div>
+      )}
+    </section>
+  );
+}
+
+function ReviewForm({ r }) {
+  const field = (key, label, node) => (
+    <label className="block">
+      <span className="block text-xs text-muted-foreground">{label}</span>
+      {node}
+      {r.fieldErrors[key] && (
+        <span role="alert" className="mt-1 block text-xs text-destructive">{r.fieldErrors[key]}</span>
+      )}
+    </label>
+  );
+
+  return (
+    <form
+      data-commerce="review-form"
+      onSubmit={(e) => {
+        e.preventDefault();
+        r.submit();
+      }}
+      className="space-y-3"
+    >
+      <h3 className="text-xs uppercase tracking-wide text-muted-foreground">Write a review</h3>
+
+      <div className="grid gap-3 sm:grid-cols-2">
+        {field(
+          "reviewer",
+          "Your name",
+          <input
+            data-commerce="review-name"
+            value={r.form.reviewer}
+            onChange={(e) => r.setField("reviewer", e.target.value)}
+            className="mt-1 w-full border border-border bg-transparent px-3 py-2 text-sm"
+          />,
+        )}
+        {r.requiresEmail &&
+          field(
+            "email",
+            "Email",
+            <input
+              data-commerce="review-email"
+              type="email"
+              value={r.form.email}
+              onChange={(e) => r.setField("email", e.target.value)}
+              className="mt-1 w-full border border-border bg-transparent px-3 py-2 text-sm"
+            />,
+          )}
+      </div>
+
+      {field(
+        "rating",
+        "Rating",
+        <select
+          data-commerce="review-rating"
+          value={r.form.rating}
+          onChange={(e) => r.setField("rating", Number(e.target.value))}
+          className="mt-1 w-full border border-border bg-transparent px-3 py-2 text-sm sm:w-32"
+        >
+          {[5, 4, 3, 2, 1].map((n) => (
+            <option key={n} value={n}>{n} / 5</option>
+          ))}
+        </select>,
+      )}
+
+      {field(
+        "review",
+        "Your review",
+        <textarea
+          data-commerce="review-text"
+          rows={4}
+          value={r.form.review}
+          onChange={(e) => r.setField("review", e.target.value)}
+          className="mt-1 w-full border border-border bg-transparent px-3 py-2 text-sm"
+        />,
+      )}
+
+      {r.fieldErrors.form && (
+        <p role="alert" className="text-xs text-destructive">{r.fieldErrors.form}</p>
+      )}
+
+      <button
+        type="submit"
+        data-commerce="review-submit"
+        disabled={!r.valid || r.submitting}
+        className="border border-border px-4 py-2 text-sm disabled:opacity-50"
+      >
+        {r.submitting ? "Submitting…" : "Submit review"}
+      </button>
+    </form>
+  );
+}

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

@@ -0,0 +1,42 @@
+import React from "react";
+import { useTotalsLines } from "../useTotalsLines";
+
+/**
+ * The order summary — subtotal, discount, shipping, tax, total.
+ *
+ *   <TotalsBlock />              // the shared cart
+ *   <TotalsBlock order={order} /> // a placed order
+ *
+ * Renders every line the store actually has, which is the point: a hand-written
+ * summary omits discount and tax (they are usually zero) and then stops adding
+ * up the day a coupon or a tax rate exists.
+ *
+ * @param {{order?: object, className?: string, showZero?: boolean,
+ *   labels?: Record<string, string>, renderLine?: (line: object) => React.ReactNode}} props
+ */
+export function TotalsBlock({ order, className = "", showZero = false, labels, renderLine }) {
+  const lines = useTotalsLines(order);
+  const visible = lines.filter((l) => showZero || !l.hidden);
+  if (!visible.length) return null;
+
+  return (
+    <div data-commerce="totals" className={`space-y-2 ${className}`}>
+      {visible.map((line) => {
+        const l = labels?.[line.key] ? { ...line, label: labels[line.key] } : line;
+        if (renderLine) return <React.Fragment key={l.key}>{renderLine(l)}</React.Fragment>;
+        return (
+          <div
+            key={l.key}
+            data-commerce={`totals-${l.key}`}
+            className={`flex items-baseline justify-between gap-4 ${
+              l.emphasis ? "border-t border-border pt-2 text-base font-medium" : "text-sm"
+            }`}
+          >
+            <span className={l.emphasis ? "" : "text-muted-foreground"}>{l.label}</span>
+            <span data-commerce-value={l.amount}>{l.formatted}</span>
+          </div>
+        );
+      })}
+    </div>
+  );
+}

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

@@ -0,0 +1,81 @@
+import React from "react";
+import { OPTION_OUT_OF_STOCK, OPTION_UNAVAILABLE } from "@/commerce/utils";
+
+/**
+ * One control per attribute axis — Size, Color — with availability shown rather
+ * than hidden.
+ *
+ *   const { view, pick } = useProduct(slug);
+ *   <VariantSelectorBlock view={view} onPick={pick} />
+ *
+ * The rule it encodes: **a selector per axis, never a list of variations**, and
+ * an option that isn't buyable is rendered *disabled*, not removed — a customer
+ * who can't see that a size exists assumes the store doesn't carry it. Pass
+ * `renderOption` for swatches or any other option UI.
+ *
+ * @param {{view: object, onPick: (axisKey: string, option: string) => void,
+ *   className?: string,
+ *   renderOption?: (o: {axis: object, option: string, selected: boolean,
+ *     state: string, disabled: boolean, pick: () => void}) => React.ReactNode}} props
+ */
+export function VariantSelectorBlock({ view, onPick, className = "", renderOption }) {
+  if (!view?.isVariable || !view.axes?.length) return null;
+
+  return (
+    <div data-commerce="variant-selector" className={`space-y-4 ${className}`}>
+      {view.axes.map((axis) => (
+        <fieldset key={axis.key} data-commerce="variant-axis" data-commerce-axis={axis.name}>
+          <legend className="mb-2 text-xs uppercase tracking-wide text-muted-foreground">
+            {axis.name}
+            {view.selection?.[axis.key] ? `: ${view.selection[axis.key]}` : ""}
+          </legend>
+          <div className="flex flex-wrap gap-2">
+            {axis.options.map((option) => {
+              const state = view.availability?.[axis.key]?.[option] ?? "available";
+              const selected = view.selection?.[axis.key] === option;
+              const disabled = state === OPTION_UNAVAILABLE;
+              const pick = () => onPick?.(axis.key, option);
+
+              if (renderOption) {
+                return (
+                  <React.Fragment key={option}>
+                    {renderOption({ axis, option, selected, state, disabled, pick })}
+                  </React.Fragment>
+                );
+              }
+              return (
+                <button
+                  key={option}
+                  type="button"
+                  data-commerce="variant-option"
+                  data-commerce-state={state}
+                  aria-pressed={selected}
+                  disabled={disabled}
+                  onClick={pick}
+                  title={
+                    state === OPTION_OUT_OF_STOCK
+                      ? "Out of stock"
+                      : disabled
+                        ? "Not available with your other choices"
+                        : undefined
+                  }
+                  className={`border px-3 py-1.5 text-sm ${
+                    selected ? "border-foreground" : "border-border"
+                  } ${state === OPTION_OUT_OF_STOCK ? "line-through opacity-60" : ""} disabled:opacity-40`}
+                >
+                  {option}
+                </button>
+              );
+            })}
+          </div>
+        </fieldset>
+      ))}
+
+      {view.missingAxes?.length > 0 && (
+        <p data-commerce="variant-hint" className="text-xs text-muted-foreground">
+          Choose {view.missingAxes.map((a) => a.name.toLowerCase()).join(" and ")} to continue.
+        </p>
+      )}
+    </div>
+  );
+}