@wix/agent-skills 1.19.2 → 1.20.0

package/skills/wix-headless-fast/references/storefront/app/components/storefront/FilterPanel.tsx

@@ -0,0 +1,266 @@
+// The gallery's filter layout — wire as-is, your grid goes inside:
+//
+//   <FilterPanel shop={shop}>
+//     …your loading / empty / error states and your grid of tiles…
+//   </FilterPanel>
+//
+// Renders: a toolbar (result count, sort, and under `md` a Filters button); active-filter chips;
+// then on `md`+ a two-column layout — a 16rem sidebar of collapsible groups (Price as a two-handle
+// slider with numeric fields, Availability, one group per option facet with swatches or pills) beside
+// your results, so expanded facets never push the products below the fold. Under `md` the same
+// groups live in a bottom sheet: changes are staged and commit on Apply; dismissing keeps the
+// current results. Sidebar changes commit immediately (a price pair on release/blur, valid only).
+// Styled from the @theme tokens.
+import { useEffect, useRef, useState, type ReactNode } from "react";
+import { SORTS, type ShopFilters, type UseShop } from "../../hooks/storefront/useShop";
+import type { CatalogSort } from "../../wix/storefront/catalog";
+
+interface Draft {
+  min: string;
+  max: string;
+  inStockOnly: boolean;
+  choiceIds: string[];
+}
+
+const draftFrom = (shop: UseShop): Draft => ({
+  min: String(shop.filters.minPrice ?? ""),
+  max: String(shop.filters.maxPrice ?? ""),
+  inStockOnly: !!shop.filters.inStockOnly,
+  choiceIds: shop.selectedChoiceIds,
+});
+
+function validPricePair(min: string, max: string): boolean {
+  if (min && !Number.isFinite(Number(min))) return false;
+  if (max && !Number.isFinite(Number(max))) return false;
+  if (min && max && Number(min) > Number(max)) return false;
+  return true;
+}
+
+export default function FilterPanel({ shop, children }: { shop: UseShop; children?: ReactNode }) {
+  const [sheetOpen, setSheetOpen] = useState(false);
+  const [staged, setStaged] = useState<Draft>(() => draftFrom(shop));
+  const panelRef = useRef<HTMLElement>(null);
+
+  // The sheet is an overlay: root-level, scrim, scroll lock, Escape, focus in and back.
+  useEffect(() => {
+    if (!sheetOpen) return;
+    setStaged(draftFrom(shop));
+    const opener = document.activeElement;
+    const previousOverflow = document.body.style.overflow;
+    document.body.style.overflow = "hidden";
+    panelRef.current?.focus();
+    const onKey = (e: KeyboardEvent) => e.key === "Escape" && setSheetOpen(false);
+    document.addEventListener("keydown", onKey);
+    return () => {
+      document.removeEventListener("keydown", onKey);
+      document.body.style.overflow = previousOverflow;
+      if (opener instanceof HTMLElement) opener.focus();
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [sheetOpen]);
+
+  const commit = (d: Draft) => {
+    if (!validPricePair(d.min, d.max)) return;
+    const next: ShopFilters = {
+      ...shop.filters,
+      minPrice: d.min || undefined,
+      maxPrice: d.max || undefined,
+      inStockOnly: d.inStockOnly || undefined,
+    };
+    const same =
+      next.minPrice === shop.filters.minPrice &&
+      next.maxPrice === shop.filters.maxPrice &&
+      !!next.inStockOnly === !!shop.filters.inStockOnly;
+    if (!same) shop.setFilters(next);
+    for (const id of d.choiceIds) if (!shop.selectedChoiceIds.includes(id)) shop.toggleChoice(id);
+    for (const id of shop.selectedChoiceIds) if (!d.choiceIds.includes(id)) shop.toggleChoice(id);
+  };
+
+  const activeCount =
+    shop.selectedChoiceIds.length + (shop.filters.inStockOnly ? 1 : 0) + (shop.filters.minPrice || shop.filters.maxPrice ? 1 : 0);
+  const choiceName = (id: string) => shop.facets.flatMap((f) => f.choices).find((c) => c.id === id)?.name ?? id;
+
+  return (
+    <div className="flex flex-col gap-4">
+      {/* Toolbar */}
+      <div className="flex flex-wrap items-center justify-between gap-3">
+        <p className="text-sm text-muted-foreground" aria-live="polite">
+          {shop.total != null ? `${shop.total} ${shop.total === 1 ? "product" : "products"}` : ""}
+        </p>
+        <div className="flex items-center gap-2">
+          <button type="button" onClick={() => setSheetOpen(true)} className="rounded-md border border-border px-3 py-1.5 text-sm md:hidden">
+            Filters{activeCount ? ` (${activeCount})` : ""}
+          </button>
+          <label className="sr-only" htmlFor="shop-sort">Sort by</label>
+          <select id="shop-sort" value={shop.sort} onChange={(e) => shop.setSort(e.target.value as CatalogSort)}
+            className="rounded-md border border-border bg-background px-2 py-1.5 text-sm">
+            {Object.entries(SORTS).map(([key, { label }]) => <option key={key} value={key}>{label}</option>)}
+          </select>
+        </div>
+      </div>
+
+      {/* Active chips */}
+      {shop.hasActiveFilters && (
+        <div className="flex flex-wrap items-center gap-1.5" aria-label="Active filters">
+          {shop.selectedChoiceIds.map((id) => (
+            <button key={id} type="button" onClick={() => shop.toggleChoice(id)} className="rounded-full bg-secondary px-2.5 py-1 text-xs text-foreground">
+              {choiceName(id)} ×
+            </button>
+          ))}
+          {shop.filters.inStockOnly && (
+            <button type="button" onClick={() => shop.setFilters({ ...shop.filters, inStockOnly: undefined })} className="rounded-full bg-secondary px-2.5 py-1 text-xs">In stock ×</button>
+          )}
+          {(shop.filters.minPrice || shop.filters.maxPrice) && (
+            <button type="button" onClick={() => shop.setFilters({ ...shop.filters, minPrice: undefined, maxPrice: undefined })} className="rounded-full bg-secondary px-2.5 py-1 text-xs">
+              Price {shop.filters.minPrice ?? shop.priceRange?.min ?? "…"}–{shop.filters.maxPrice ?? shop.priceRange?.max ?? "…"} ×
+            </button>
+          )}
+          <button type="button" onClick={shop.clearFilters} className="text-xs text-muted-foreground underline">Clear all</button>
+        </div>
+      )}
+
+      {/* Sidebar + results */}
+      <div className="md:grid md:grid-cols-[16rem_minmax(0,1fr)] md:gap-8">
+        <aside className="hidden md:block" aria-label="Filters">
+          <Groups shop={shop} draft={draftFrom(shop)} onChange={commit} immediate />
+        </aside>
+        <div className="min-w-0">{children}</div>
+      </div>
+
+      {/* Sheet — small screens; staged until Apply */}
+      {sheetOpen && (
+        <div className="fixed inset-0 z-50 flex items-end bg-foreground/40 md:hidden" onClick={() => setSheetOpen(false)}>
+          <section ref={panelRef} tabIndex={-1} role="dialog" aria-modal="true" aria-label="Filters" onClick={(e) => e.stopPropagation()}
+            className="flex max-h-[85vh] w-full flex-col rounded-t-2xl bg-background text-foreground outline-none">
+            <div className="flex items-center justify-between px-5 pt-5">
+              <h2 className="text-base font-semibold">Filters</h2>
+              <button type="button" aria-label="Close filters" onClick={() => setSheetOpen(false)} className="text-xl leading-none">×</button>
+            </div>
+            <div className="min-h-0 flex-1 overflow-y-auto px-5 py-4">
+              <Groups shop={shop} draft={staged} onChange={setStaged} />
+            </div>
+            <div className="flex gap-2 border-t border-border bg-background px-5 py-3">
+              <button type="button" onClick={() => setStaged({ min: "", max: "", inStockOnly: false, choiceIds: [] })}
+                className="flex-1 rounded-full border border-border py-2.5 text-sm">Clear</button>
+              <button type="button" onClick={() => { commit(staged); setSheetOpen(false); }}
+                className="flex-1 rounded-full bg-primary py-2.5 text-sm font-semibold text-primary-foreground">Apply</button>
+            </div>
+          </section>
+        </div>
+      )}
+    </div>
+  );
+}
+
+// The filter groups — one markup for the sidebar (immediate commit) and the sheet (staged).
+function Groups({ shop, draft, onChange, immediate = false }: { shop: UseShop; draft: Draft; onChange: (d: Draft) => void; immediate?: boolean }) {
+  const toggle = (id: string) =>
+    onChange({ ...draft, choiceIds: draft.choiceIds.includes(id) ? draft.choiceIds.filter((x) => x !== id) : [...draft.choiceIds, id] });
+  return (
+    <div className="flex flex-col divide-y divide-border">
+      <Group title="Price">
+        <PriceControl
+          range={shop.priceRange}
+          min={draft.min}
+          max={draft.max}
+          onCommit={(min, max) => onChange({ ...draft, min, max })}
+          immediate={immediate}
+        />
+      </Group>
+      <Group title="Availability">
+        <label className="flex items-center gap-2 text-sm">
+          <input type="checkbox" checked={draft.inStockOnly} onChange={(e) => onChange({ ...draft, inStockOnly: e.target.checked })} />
+          In stock only
+        </label>
+      </Group>
+      {shop.facets.map((facet) => (
+        <Group key={facet.name} title={facet.name} count={facet.choices.filter((c) => draft.choiceIds.includes(c.id)).length}>
+          <div className="flex flex-wrap gap-1.5">
+            {facet.choices.map((c) => {
+              const on = draft.choiceIds.includes(c.id);
+              return facet.isColor && c.colorCode ? (
+                <button key={c.id} type="button" aria-pressed={on} aria-label={c.name} title={c.name} onClick={() => toggle(c.id)}
+                  className={`h-7 w-7 rounded-full border-2 ${on ? "border-foreground" : "border-border"}`} style={{ backgroundColor: c.colorCode }} />
+              ) : (
+                <button key={c.id} type="button" aria-pressed={on} onClick={() => toggle(c.id)}
+                  className={`rounded-full border px-3 py-1 text-sm ${on ? "border-foreground bg-foreground text-background" : "border-border bg-background text-foreground"}`}>
+                  {c.name}
+                </button>
+              );
+            })}
+          </div>
+        </Group>
+      ))}
+    </div>
+  );
+}
+
+// A collapsible group — native <details>, open by default, the selected count on the summary.
+function Group({ title, count = 0, children }: { title: string; count?: number; children: ReactNode }) {
+  return (
+    <details open className="group py-3">
+      <summary className="flex cursor-pointer list-none items-center justify-between text-sm font-medium">
+        <span>{title}{count ? <span className="ml-1.5 text-xs text-muted-foreground">({count})</span> : null}</span>
+        <span aria-hidden="true" className="text-muted-foreground transition-transform group-open:rotate-180">⌄</span>
+      </summary>
+      <div className="pt-3">{children}</div>
+    </details>
+  );
+}
+
+// Two-handle range slider bounded by the scope's real prices, with the numeric pair under it.
+// Local drafts while dragging/typing; a VALID pair commits on release / blur / Enter (immediate mode)
+// or on every change (staged mode, where Apply commits later).
+function PriceControl({ range, min, max, onCommit, immediate }: {
+  range: UseShop["priceRange"]; min: string; max: string; onCommit: (min: string, max: string) => void; immediate: boolean;
+}) {
+  const [lo, setLo] = useState(min);
+  const [hi, setHi] = useState(max);
+  useEffect(() => { setLo(min); setHi(max); }, [min, max]);
+  const bounds = range ?? null;
+  const loN = lo === "" ? (bounds?.min ?? 0) : Number(lo);
+  const hiN = hi === "" ? (bounds?.max ?? 0) : Number(hi);
+  const step = bounds ? Math.max(1, Math.round((bounds.max - bounds.min) / 100)) : 1;
+  const pct = (v: number) => (bounds ? ((v - bounds.min) / (bounds.max - bounds.min)) * 100 : 0);
+  const publish = (a: string, b: string) => {
+    // at the bounds the filter is "no bound" — omit it rather than sending the catalog's own extremes
+    const A = bounds && a !== "" && Number(a) <= bounds.min ? "" : a;
+    const B = bounds && b !== "" && Number(b) >= bounds.max ? "" : b;
+    if (validPricePair(A, B)) onCommit(A, B);
+  };
+  const setFromSlider = (which: "lo" | "hi", v: number) => {
+    const a = which === "lo" ? String(Math.min(v, hiN)) : lo;
+    const b = which === "hi" ? String(Math.max(v, loN)) : hi;
+    setLo(a); setHi(b);
+    if (!immediate) publish(a, b);
+  };
+  const release = () => immediate && publish(lo, hi);
+  const thumb = "pointer-events-none absolute inset-x-0 top-0 h-6 w-full appearance-none bg-transparent [&::-webkit-slider-thumb]:pointer-events-auto [&::-webkit-slider-thumb]:h-4 [&::-webkit-slider-thumb]:w-4 [&::-webkit-slider-thumb]:appearance-none [&::-webkit-slider-thumb]:rounded-full [&::-webkit-slider-thumb]:border-2 [&::-webkit-slider-thumb]:border-foreground [&::-webkit-slider-thumb]:bg-background [&::-moz-range-thumb]:pointer-events-auto [&::-moz-range-thumb]:h-4 [&::-moz-range-thumb]:w-4 [&::-moz-range-thumb]:rounded-full [&::-moz-range-thumb]:border-2 [&::-moz-range-thumb]:border-foreground [&::-moz-range-thumb]:bg-background";
+  return (
+    <div className="flex flex-col gap-3">
+      {bounds && (
+        <div className="relative h-6" aria-hidden={false}>
+          <div className="absolute inset-x-0 top-1/2 h-1 -translate-y-1/2 rounded bg-secondary" />
+          <div className="absolute top-1/2 h-1 -translate-y-1/2 rounded bg-foreground" style={{ left: `${pct(loN)}%`, right: `${100 - pct(hiN)}%` }} />
+          <input type="range" aria-label="Minimum price" min={bounds.min} max={bounds.max} step={step} value={loN}
+            onChange={(e) => setFromSlider("lo", Number(e.target.value))} onPointerUp={release} onKeyUp={release} className={thumb} />
+          <input type="range" aria-label="Maximum price" min={bounds.min} max={bounds.max} step={step} value={hiN}
+            onChange={(e) => setFromSlider("hi", Number(e.target.value))} onPointerUp={release} onKeyUp={release} className={thumb} />
+        </div>
+      )}
+      <div className="flex items-center gap-2">
+        <label className="sr-only" htmlFor="filter-min">Minimum price</label>
+        <input id="filter-min" inputMode="decimal" placeholder={bounds ? String(bounds.min) : "Min"} value={lo}
+          onChange={(e) => { setLo(e.target.value); if (!immediate) publish(e.target.value, hi); }}
+          onBlur={release} onKeyDown={(e) => e.key === "Enter" && release()}
+          className="w-full min-w-0 rounded-md border border-border bg-background px-2 py-1.5 text-sm" />
+        <span className="text-muted-foreground">–</span>
+        <label className="sr-only" htmlFor="filter-max">Maximum price</label>
+        <input id="filter-max" inputMode="decimal" placeholder={bounds ? String(bounds.max) : "Max"} value={hi}
+          onChange={(e) => { setHi(e.target.value); if (!immediate) publish(lo, e.target.value); }}
+          onBlur={release} onKeyDown={(e) => e.key === "Enter" && release()}
+          className="w-full min-w-0 rounded-md border border-border bg-background px-2 py-1.5 text-sm" />
+      </div>
+    </div>
+  );
+}

package/skills/wix-headless-fast/references/storefront/app/components/storefront/QuickAdd.tsx

@@ -0,0 +1,165 @@
+// The card's purchase control — the three gallery purchase paths, decided from the product:
+//   • no options            → Direct Add: one click, the cheapest variant, quantity 1
+//   • options / choice mods → Quick Add: a picker on the card (bottom sheet on small screens)
+//   • free-text modifier    → the product page (the gallery can't collect the text)
+// Mount as the LAST ROW of the tile's text block (under name and price), as a direct child of the
+// tile root that carries `relative` — the picker anchors to that root and takes its width. Never
+// overlay it on the image, never wrap it in a narrower positioned box.
+//   <QuickAdd product={p} />   Wire as-is; style via the tokens.
+import { useEffect, useRef, useState } from "react";
+import { useCart } from "../../hooks/storefront/useCart";
+import { useProductDetail } from "../../hooks/storefront/useProductDetail";
+import type { ProductSummary } from "../../wix/storefront/types";
+
+export default function QuickAdd({ product }: { product: ProductSummary }) {
+  const { addToCart, busy } = useCart();
+  const [open, setOpen] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  if (product.availability === "OUT_OF_STOCK" && !product.preorder) {
+    return <span className="text-sm text-muted-foreground">Out of stock</span>;
+  }
+  if (product.quickAddable) {
+    return (
+      <div>
+        <button
+          type="button"
+          disabled={busy}
+          onClick={() =>
+            addToCart(product.id, product.minPriceVariantId, 1).catch((e) => setError(e instanceof Error ? e.message : String(e)))
+          }
+          className="w-full rounded-full border border-foreground py-2 text-sm font-medium transition-colors hover:bg-foreground hover:text-background disabled:opacity-50"
+        >
+          {product.preorder ? "Pre-order" : "Add to cart"}
+        </button>
+        {error && <p className="mt-1 text-xs text-red-600">{error}</p>}
+      </div>
+    );
+  }
+  // Options to pick, or a single variant that isn't plainly in stock (pre-order, partial stock):
+  // the picker resolves it through useProductDetail, exactly as the PDP would.
+  return (
+    <>
+      <button
+        type="button"
+        onClick={() => setOpen(true)}
+        className="w-full rounded-full border border-foreground py-2 text-sm font-medium transition-colors hover:bg-foreground hover:text-background"
+      >
+        {product.optionsSummary ? "Choose options" : product.preorder ? "Pre-order" : "Add to cart"}
+      </button>
+      {open && <QuickAddPicker product={product} onClose={() => setOpen(false)} />}
+    </>
+  );
+}
+
+// The picker fetches the full product only when it opens — cards never carry PDP data.
+function QuickAddPicker({ product, onClose }: { product: ProductSummary; onClose: () => void }) {
+  const d = useProductDetail({ slug: product.slug });
+  const panelRef = useRef<HTMLElement>(null);
+
+  // Overlay contract: Escape closes, scroll locks under md, focus moves in and back.
+  useEffect(() => {
+    const opener = document.activeElement;
+    const isSmall = window.matchMedia("(max-width: 767px)").matches;
+    const previousOverflow = document.body.style.overflow;
+    if (isSmall) document.body.style.overflow = "hidden";
+    panelRef.current?.focus();
+    const onKey = (e: KeyboardEvent) => e.key === "Escape" && onClose();
+    document.addEventListener("keydown", onKey);
+    return () => {
+      document.removeEventListener("keydown", onKey);
+      document.body.style.overflow = previousOverflow;
+      if (opener instanceof HTMLElement) opener.focus();
+    };
+  }, [onClose]);
+
+  const needsPdp = (d.product?.modifiers ?? []).some((m) => m.type === "text");
+
+  return (
+    <>
+      <div className="fixed inset-0 z-40 bg-foreground/40 md:hidden" onClick={onClose} />
+      <section
+        ref={panelRef}
+        tabIndex={-1}
+        role="dialog"
+        aria-modal="true"
+        aria-label={`Choose options for ${product.name}`}
+        // md+: anchored to the tile (its nearest `relative` ancestor), the tile's full width — and never
+        // narrower than 18rem even when mounted inside a small wrapper.
+        className="fixed inset-x-0 bottom-0 z-50 max-h-[85vh] overflow-y-auto rounded-t-2xl bg-background p-5 text-foreground shadow-2xl outline-none md:absolute md:inset-x-auto md:bottom-0 md:right-0 md:w-[max(100%,18rem)] md:max-h-none md:rounded-lg md:p-4"
+      >
+        <div className="mb-3 flex items-start justify-between gap-3">
+          <div className="min-w-0">
+            <p className="truncate text-sm font-semibold">{product.name}</p>
+            <p className="text-sm">
+              {d.price}
+              {d.compareAtPrice && <span className="ml-2 text-muted-foreground line-through">{d.compareAtPrice}</span>}
+            </p>
+          </div>
+          <button type="button" aria-label="Close" onClick={onClose} className="text-xl leading-none text-muted-foreground">×</button>
+        </div>
+
+        {!d.product && !d.notFound && <p className="text-sm text-muted-foreground">Loading options…</p>}
+        {d.notFound && <p className="text-sm text-muted-foreground">This product isn't available anymore.</p>}
+
+        {d.product && needsPdp && (
+          <a href={`/products/${product.slug}`} className="block rounded-full bg-primary py-2.5 text-center text-sm font-semibold text-primary-foreground">
+            Customize on the product page
+          </a>
+        )}
+
+        {d.product && !needsPdp && (
+          <div className="flex flex-col gap-3">
+            {d.optionGroups.map((g) => (
+              <fieldset key={g.id}>
+                <legend className="mb-1.5 text-xs font-medium uppercase tracking-wide text-muted-foreground">{g.name}</legend>
+                <div className="flex flex-wrap gap-1.5">
+                  {g.choices.map((c) =>
+                    g.isColor && c.colorCode ? (
+                      <button key={c.choiceId} type="button" aria-label={c.name} title={c.name} aria-pressed={c.selected}
+                        disabled={!c.inStock} onClick={() => d.selectOption(g.name, c.name)}
+                        className={`h-8 w-8 rounded-full border-2 disabled:opacity-30 ${c.selected ? "border-foreground" : "border-border"}`}
+                        style={{ backgroundColor: c.colorCode }} />
+                    ) : (
+                      <button key={c.choiceId} type="button" aria-pressed={c.selected} disabled={!c.inStock}
+                        onClick={() => d.selectOption(g.name, c.name)}
+                        className={`rounded-full border px-3 py-1 text-sm disabled:line-through disabled:opacity-40 ${c.selected ? "border-foreground bg-foreground text-background" : "border-border"}`}>
+                        {c.name}
+                      </button>
+                    ),
+                  )}
+                </div>
+              </fieldset>
+            ))}
+            {d.product.modifiers.filter((m) => m.type === "choices").map((m) => (
+              <fieldset key={m.key}>
+                <legend className="mb-1.5 text-xs font-medium uppercase tracking-wide text-muted-foreground">
+                  {m.name}{m.mandatory ? " *" : ""}
+                </legend>
+                <div className="flex flex-wrap gap-1.5">
+                  {m.choices.map((c) => (
+                    <button key={c.key} type="button" aria-pressed={d.modifierValues[m.key] === c.key}
+                      onClick={() => d.setModifier(m.key, c.key)}
+                      className={`rounded-full border px-3 py-1 text-sm ${d.modifierValues[m.key] === c.key ? "border-foreground bg-foreground text-background" : "border-border"}`}>
+                      {c.name}
+                    </button>
+                  ))}
+                </div>
+              </fieldset>
+            ))}
+            <button
+              type="button"
+              disabled={!d.canAdd || d.adding}
+              onClick={() => d.add().then(onClose).catch(() => {})}
+              className="rounded-full bg-primary py-2.5 text-sm font-semibold text-primary-foreground disabled:opacity-50"
+            >
+              {d.adding ? "Adding…" : d.isPreorder ? "Pre-order" : "Add to cart"}
+            </button>
+            {d.blockedReason && !d.canAdd && <p className="text-xs text-muted-foreground">{d.blockedReason}</p>}
+            {d.error && <p className="text-xs text-red-600">{d.error}</p>}
+          </div>
+        )}
+      </section>
+    </>
+  );
+}

package/skills/wix-headless-fast/references/storefront/app/hooks/storefront/useProductDetail.ts

@@ -30,11 +30,22 @@ export interface UseProductDetail {
   setModifier: (key: string, value: string) => void;
   /** The resolved variant; null while the selection is incomplete. */
   variant: ProductVariant | null;
-  /** Price to display right now (variant price once resolved, else the product range). */
+  /**
+   * Price to display right now: the product RANGE ("€24.99 – €34.99", one value when equal) until
+   * every option is picked, then the selected variant's price (an automatic discount applied).
+   */
   price: string;
+  /** Struck "was" price — only once a variant is resolved (or for a single-price product), never beside a range. */
   compareAtPrice: string | null;
-  /** False until every option is selected (and the resolved variant is in stock). */
+  /** The resolved variant is out of stock but pre-orderable — label the action "Pre-order". */
+  isPreorder: boolean;
+  /** False until every option is selected and the resolved variant is in stock or pre-orderable. */
   canAdd: boolean;
+  /**
+   * Why the action is disabled — neutral guidance to render beside it ("Choose Size"), not an
+   * error; null when the buyer can add. Promote to error styling only after they try to buy.
+   */
+  blockedReason: string | null;
   quantity: number;
   setQuantity: (n: number) => void;
   /** Adds the resolved variant to the cart (opens the drawer). Throws on refusal. */
@@ -83,16 +94,33 @@ export function useProductDetail({ initial, slug }: UseProductDetailOptions): Us
     [product, selections],
   );
 
-  const mandatoryModifiersFilled = (product?.modifiers ?? [])
-    .filter((m) => m.mandatory)
-    .every((m) => (modifierValues[m.key] ?? "").length > 0);
+  const missingModifier = (product?.modifiers ?? []).find(
+    (m) => m.mandatory && (modifierValues[m.key] ?? "").length === 0,
+  );
+  const missingOptions = (product?.options ?? []).filter((o) => !selections[o.name]).map((o) => o.name);
+  const selectionComplete = missingOptions.length === 0;
+
+  // In stock OR pre-orderable counts as buyable; a preorder add carries preOrderRequested.
+  const isPreorder = !!variant && !variant.inStock && variant.preorderEnabled;
+  const available = !!variant && (variant.inStock || variant.preorderEnabled);
+
+  const canAdd = !!product && available && !missingModifier;
+
+  const blockedReason: string | null = !product
+    ? null
+    : !selectionComplete
+      ? `Choose ${missingOptions.join(" and ")}`
+      : !variant
+        ? "This combination isn't available"
+        : !available
+          ? "Out of stock"
+          : missingModifier
+            ? `Add ${missingModifier.name}`
+            : null;
 
-  const canAdd =
-    !!product &&
-    product.availability !== "OUT_OF_STOCK" &&
-    variant !== null &&
-    variant.inStock &&
-    mandatoryModifiersFilled;
+  // Before every option is picked, the range — never an empty price, never a lone struck minimum.
+  const isRange = !!product && product.price !== product.maxPrice && !!product.maxPrice;
+  const rangeDisplay = product ? (isRange ? `${product.price} – ${product.maxPrice}` : product.price) : "";
 
   async function add(): Promise<void> {
     if (!product || !variant) return;
@@ -110,6 +138,7 @@ export function useProductDetail({ initial, slug }: UseProductDetailOptions): Us
       await addToCart(product.id, variant.variantId, quantity, {
         modifierChoices: choiceModifiers,
         customTextFields: textModifiers,
+        preorder: isPreorder,
       });
     } catch (e) {
       setError(e instanceof Error ? e.message : String(e));
@@ -123,14 +152,18 @@ export function useProductDetail({ initial, slug }: UseProductDetailOptions): Us
     product,
     notFound,
     optionGroups,
-    selectOption: (optionName, choiceName) =>
-      setSelections((s) => ({ ...s, [optionName]: choiceName })),
+    selectOption: (optionName, choiceName) => {
+      setSelections((s) => ({ ...s, [optionName]: choiceName }));
+      setQuantity(1); // the ceiling belongs to the newly resolved variant
+    },
     modifierValues,
     setModifier: (key, value) => setModifierValues((v) => ({ ...v, [key]: value })),
     variant,
-    price: variant?.price || product?.price || "",
-    compareAtPrice: variant ? variant.compareAtPrice : (product?.compareAtPrice ?? null),
+    price: variant?.price || rangeDisplay,
+    compareAtPrice: variant ? variant.compareAtPrice : isRange ? null : (product?.compareAtPrice ?? null),
+    isPreorder,
     canAdd,
+    blockedReason,
     quantity,
     setQuantity,
     add,