@tribe-nest/forge 3.11.0 → 3.17.0

package/src/ui/styled/ProductDetail.tsx

@@ -1,7 +1,8 @@
 import { useEffect, useMemo, useRef, useState } from "react";
 import { Play, Pause, Music, Star } from "lucide-react";
-import { ProductCategory } from "../../types/models";
+import { ProductType } from "../../types/models";
 import type { IPublicProduct, IPublicProductTrack, IPublicProductVariant } from "../../types/models";
+import { useVariantSelection } from "../headless/useVariantSelection";
 import { useGetProduct } from "../../data/queries/useProducts";
 import { useCart } from "../../contexts/CartContext";
 import { useAudioPlayer } from "../../contexts/AudioPlayerContext";
@@ -27,18 +28,34 @@ export interface ProductDetailProps {
   style?: React.CSSProperties;
   /** Server-fetched product used as initial data (SSR), avoids client loading spinner. */
   initialProduct?: IPublicProduct;
+  /**
+   * Make the product's categories/collections links. Router-agnostic, like
+   * `ProductGrid.hrefFor` — Forge has no router, so the host owns the path.
+   * Omit and they render as plain text.
+   */
+  hrefForCategory?: (category: { id: string; slug: string; title: string }) => string;
+  hrefForCollection?: (collection: { id: string; slug: string; title: string }) => string;
 }
 
 const a = (hex: string, al: number) => hex + Math.round(al * 255).toString(16).padStart(2, "0");
 
 /**
- * Drop-in product page. **Music** products (category `Music`) get an album/single
+ * Drop-in product page. **Music** products (productType `Music`) get an album/single
  * preview with per-track playback; everything else — including Digital products
  * (whose downloadable file is stored as a track) — gets the standard product
  * layout. Renders the description as sanitized-by-source HTML with responsive
  * media (no horizontal overflow from embedded video/images).
  */
-export function ProductDetail({ slug, formatAmount, checkoutPath = "/i/checkout", className, style, initialProduct }: ProductDetailProps) {
+export function ProductDetail({
+  slug,
+  formatAmount,
+  checkoutPath = "/i/checkout",
+  className,
+  style,
+  initialProduct,
+  hrefForCategory,
+  hrefForCollection,
+}: ProductDetailProps) {
   const t = useThemeTokens();
   const { data: product, isLoading } = useGetProduct(slug, { initialData: initialProduct });
   const fmt = useAmountFormatter(formatAmount);
@@ -46,14 +63,22 @@ export function ProductDetail({ slug, formatAmount, checkoutPath = "/i/checkout"
   if (isLoading) return <Loading fullPage />;
   if (!product) return <p style={{ color: t.text }}>Product not found.</p>;
 
-  // Classify on the product's category, NOT "has tracks" — a Digital product
+  // Classify on the product's TYPE, NOT "has tracks" — a Digital product
   // stores its download as a track too, so track-presence would misrender it as
   // music (audio player over a PDF, etc.).
-  const isMusic = product.category === ProductCategory.Music;
+  const isMusic = product.productType === ProductType.Music;
   return isMusic ? (
     <MusicDetail product={product} fmt={fmt} checkoutPath={checkoutPath} className={className} style={style} />
   ) : (
-    <StandardDetail product={product} fmt={fmt} checkoutPath={checkoutPath} className={className} style={style} />
+    <StandardDetail
+      product={product}
+      fmt={fmt}
+      checkoutPath={checkoutPath}
+      className={className}
+      style={style}
+      hrefForCategory={hrefForCategory}
+      hrefForCollection={hrefForCollection}
+    />
   );
 }
 
@@ -87,6 +112,14 @@ function useBuy(product: IPublicProduct, cover: string | undefined, checkoutPath
       quantity: opts?.quantity ?? 1,
       canIncreaseQuantity: opts?.canIncreaseQuantity ?? true,
       payWhatYouWant: !!variant.payWhatYouWant,
+      // Which version was chosen, carried onto the line so the cart, the
+      // checkout and the receipt can all say so. `color`/`size` stay for a
+      // moment longer: they are what a cart saved before this holds.
+      options: (variant.options ?? []).map((option) => ({
+        axis: option.axis,
+        value: option.value,
+        swatchHex: option.swatchHex,
+      })),
       color: variant.color,
       size: variant.size,
       deliveryType: variant.deliveryType,
@@ -106,12 +139,16 @@ function StandardDetail({
   checkoutPath,
   className,
   style,
+  hrefForCategory,
+  hrefForCollection,
 }: {
   product: IPublicProduct;
   fmt: (n: number) => string;
   checkoutPath: string;
   className?: string;
   style?: React.CSSProperties;
+  hrefForCategory?: (category: { id: string; slug: string; title: string }) => string;
+  hrefForCollection?: (collection: { id: string; slug: string; title: string }) => string;
 }) {
   const t = useThemeTokens();
   // Inclusive stores caption the price as tax-inclusive (display only).
@@ -120,39 +157,13 @@ function StandardDetail({
   const { add } = useBuy(product, cover, checkoutPath);
   const { isCartOpen } = useCart();
 
-  const [selectedColor, setSelectedColor] = useState<string | null>(null);
-  const [selectedSize, setSelectedSize] = useState<string | null>(null);
   const [quantity, setQuantity] = useState(1);
   const [imageIndex, setImageIndex] = useState(0);
 
-  // Colors that exist across variants (each flagged if it has any in-stock size).
-  const availableColors = useMemo(() => {
-    const colors = Array.from(new Set(product.variants.map((v) => v.color)));
-    return colors
-      .map((color) => ({
-        name: color,
-        hasAvailableSize: product.variants.some((v) => v.color === color && v.availabilityStatus === "active"),
-      }))
-      .filter((c) => c.name);
-  }, [product.variants]);
-
-  // Sizes for the chosen color.
-  const availableSizes = useMemo(() => {
-    if (!selectedColor) return [];
-    return product.variants
-      .filter((v) => v.color === selectedColor)
-      .map((v) => ({ name: v.size, isAvailable: v.availabilityStatus === "active" }))
-      .filter((s) => s.name);
-  }, [selectedColor, product.variants]);
-
-  // Products without color/size options (digital, service, simple physical) just
-  // use the default variant; otherwise the buyer must pick color + size.
-  const hasOptions = availableColors.length > 0;
-  const selectedVariant = useMemo(() => {
-    if (!hasOptions) return product.variants?.find((v) => v.isDefault) ?? product.variants?.[0];
-    if (!selectedColor || !selectedSize) return undefined;
-    return product.variants.find((v) => v.color === selectedColor && v.size === selectedSize);
-  }, [hasOptions, selectedColor, selectedSize, product.variants]);
+  // Any number of axes, narrowed left to right. Was a hardcoded colour → size
+  // cascade, which had nowhere to put "Format" and read a column that holds a
+  // hex from one writer and a name from another.
+  const { axes, selection, select, selectedVariant, hasOptions } = useVariantSelection(product.variants);
 
   // Prefer the selected variant's own images; fall back to the product's.
   const images = useMemo(() => {
@@ -160,19 +171,6 @@ function StandardDetail({
     return vImgs.length > 0 ? vImgs : product.media?.filter((m) => m.type === "image") ?? [];
   }, [selectedVariant, product.media]);
 
-  // Auto-select the first available color, then its first available size.
-  useEffect(() => {
-    if (!selectedColor && availableColors.length > 0) {
-      const first = availableColors.find((c) => c.hasAvailableSize) ?? availableColors[0];
-      setSelectedColor(first.name);
-    }
-  }, [availableColors, selectedColor]);
-  useEffect(() => {
-    if (selectedColor && !selectedSize && availableSizes.length > 0) {
-      const first = availableSizes.find((s) => s.isAvailable) ?? availableSizes[0];
-      setSelectedSize(first.name);
-    }
-  }, [selectedColor, selectedSize, availableSizes]);
   useEffect(() => setImageIndex(0), [selectedVariant]);
 
   // Mobile: once the inline Add-to-cart scrolls out of view, surface a sticky
@@ -257,73 +255,67 @@ function StandardDetail({
             {selectedVariant?.payWhatYouWant && <span style={{ fontSize: 13, opacity: 0.7 }}> (Pay what you want)</span>}
           </p>
 
-          {/* Color */}
-          {availableColors.length > 0 && (
-            <div style={{ marginTop: 18 }}>
-              <p style={{ fontSize: 15, marginBottom: 8 }}>Color</p>
+          {/* Options — one block per axis the product actually uses. */}
+          {axes.map((axis) => (
+            <div key={axis.optionTypeId} style={{ marginTop: 18 }}>
+              <p style={{ fontSize: 15, marginBottom: 8 }}>{axis.axis}</p>
               <div style={{ display: "flex", flexWrap: "wrap", gap: 10, alignItems: "center", minHeight: 40 }}>
-                {availableColors.map((c) => {
-                  const isHex = /^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$/.test(c.name);
-                  const on = selectedColor === c.name;
-                  return (
+                {axis.values.map((v) => {
+                  const on = selection[axis.optionTypeId] === v.optionValueId;
+                  // A swatch only when the value genuinely carries a colour, or
+                  // when it reads as one. Everything else is a text chip —
+                  // guessing a colour for "Stems" would render a black circle
+                  // with no label.
+                  const hex = v.swatchHex ?? (/^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$/.test(v.value) ? v.value : null);
+                  return hex ? (
                     <button
-                      key={c.name}
+                      key={v.optionValueId}
                       type="button"
-                      title={c.name}
-                      disabled={!c.hasAvailableSize}
-                      onClick={() => {
-                        setSelectedColor(c.name);
-                        setSelectedSize(null);
-                      }}
+                      title={v.value}
+                      aria-label={`${axis.axis}: ${v.value}`}
+                      aria-pressed={on}
+                      disabled={!v.isAvailable}
+                      onClick={() => select(axis.optionTypeId, v.optionValueId)}
                       style={{
                         position: "relative",
                         width: on ? 34 : 30,
                         height: on ? 34 : 30,
                         borderRadius: "50%",
-                        cursor: c.hasAvailableSize ? "pointer" : "not-allowed",
-                        opacity: c.hasAvailableSize ? 1 : 0.5,
-                        background: isHex ? c.name : c.name.toLowerCase(),
+                        cursor: v.isAvailable ? "pointer" : "not-allowed",
+                        opacity: v.isAvailable ? 1 : 0.5,
+                        background: hex,
                         border: `2px solid ${on ? t.primary : a(t.text, 0.25)}`,
                         boxShadow: on ? "0 2px 8px -2px rgba(0,0,0,0.3)" : "none",
                         transition: "all .15s",
                       }}
                     />
-                  );
-                })}
-              </div>
-            </div>
-          )}
-
-          {/* Size */}
-          {selectedColor && availableSizes.length > 0 && (
-            <div style={{ marginTop: 18 }}>
-              <p style={{ fontSize: 15, marginBottom: 8 }}>Size</p>
-              <div style={{ display: "flex", flexWrap: "wrap", gap: 10 }}>
-                {availableSizes.map((s) => {
-                  const on = selectedSize === s.name;
-                  return (
+                  ) : (
                     <button
-                      key={s.name}
+                      key={v.optionValueId}
                       type="button"
-                      disabled={!s.isAvailable}
-                      onClick={() => setSelectedSize(s.name)}
+                      aria-pressed={on}
+                      // Same accessible name as the swatch form, so one locator
+                      // — and one screen-reader announcement — covers both.
+                      aria-label={`${axis.axis}: ${v.value}`}
+                      disabled={!v.isAvailable}
+                      onClick={() => select(axis.optionTypeId, v.optionValueId)}
                       style={{
                         padding: "8px 16px",
                         borderRadius: t.cornerRadius,
-                        cursor: s.isAvailable ? "pointer" : "not-allowed",
+                        cursor: v.isAvailable ? "pointer" : "not-allowed",
                         fontWeight: 600,
-                        color: s.isAvailable ? t.text : a(t.text, 0.4),
-                        background: on ? a(t.primary, 0.1) : s.isAvailable ? "transparent" : a(t.text, 0.06),
+                        color: v.isAvailable ? t.text : a(t.text, 0.4),
+                        background: on ? a(t.primary, 0.1) : v.isAvailable ? "transparent" : a(t.text, 0.06),
                         border: `2px solid ${on ? t.primary : a(t.text, 0.2)}`,
                       }}
                     >
-                      {s.name}
+                      {v.value}
                     </button>
                   );
                 })}
               </div>
             </div>
-          )}
+          ))}
 
           {/* Quantity */}
           {selectedVariant && (
@@ -354,8 +346,44 @@ function StandardDetail({
           {selectedVariant && (
             <div style={{ marginTop: 20, paddingTop: 16, borderTop: `1px solid ${a(t.text, 0.15)}` }}>
               <p style={{ fontWeight: 700, fontSize: 13, opacity: 0.7, marginBottom: 6 }}>Product details</p>
-              <p style={{ fontSize: 14, opacity: 0.75 }}>Category: {product.category}</p>
+              {/* "Type", not "Category" — the two were the same thing until the
+                  taxonomy split, and the creator's real categories are below. */}
+              <p style={{ fontSize: 14, opacity: 0.75 }}>Type: {product.productType}</p>
               <p style={{ fontSize: 14, opacity: 0.75 }}>SKU: {selectedVariant.upcCode || "N/A"}</p>
+              {!!product.categories?.length && (
+                <p style={{ fontSize: 14, opacity: 0.75 }}>
+                  {product.categories.length === 1 ? "Category: " : "Categories: "}
+                  {product.categories.map((c, i) => (
+                    <span key={c.id}>
+                      {i > 0 && ", "}
+                      {hrefForCategory ? (
+                        <a href={hrefForCategory(c)} style={{ color: t.primary, textDecoration: "none" }}>
+                          {c.title}
+                        </a>
+                      ) : (
+                        c.title
+                      )}
+                    </span>
+                  ))}
+                </p>
+              )}
+              {!!product.collections?.length && (
+                <p style={{ fontSize: 14, opacity: 0.75 }}>
+                  {product.collections.length === 1 ? "Collection: " : "Collections: "}
+                  {product.collections.map((c, i) => (
+                    <span key={c.id}>
+                      {i > 0 && ", "}
+                      {hrefForCollection ? (
+                        <a href={hrefForCollection(c)} style={{ color: t.primary, textDecoration: "none" }}>
+                          {c.title}
+                        </a>
+                      ) : (
+                        c.title
+                      )}
+                    </span>
+                  ))}
+                </p>
+              )}
             </div>
           )}
 
@@ -437,7 +465,13 @@ function MusicDetail({
   const pricesIncludeTax = usePricesIncludeTax();
   const { pause, loadAndPlay, currentTrack, play, isPlaying } = useAudioPlayer();
 
-  const defaultVariant = product.variants.find((v) => v.isDefault) || product.variants[0];
+  // A release can be sold in several forms — MP3 and FLAC, vinyl and cassette —
+  // so this page can no longer assume one version. With no axes the hook returns
+  // exactly what this used to: the default variant.
+  const { axes, selection, select, selectedVariant } = useVariantSelection(product.variants);
+  const defaultVariant = selectedVariant ?? product.variants.find((v) => v.isDefault) ?? product.variants[0];
+  // The TRACKLIST is the release's contents and does not depend on which
+  // version is selected — every version of an album has the same songs.
   const tracks = defaultVariant?.tracks ?? [];
   const isSingle = tracks.length === 1;
   const firstTrack = tracks[0];
@@ -536,6 +570,39 @@ function MusicDetail({
               <div style={{ fontSize: 20, fontWeight: 700, color: t.primary }}>
                 <PriceDisplay amount={defaultVariant.price} pricesIncludeTax={pricesIncludeTax} formatAmount={fmt} mutedColor={t.text} captionStyle={{ opacity: 0.65 }} />
               </div>
+
+              {/* One row per axis, only when the release actually has formats. */}
+              {axes.map((axis) => (
+                <div key={axis.optionTypeId} style={{ display: "flex", alignItems: "center", gap: 8, flexWrap: "wrap" }}>
+                  <span style={{ fontSize: 13, opacity: 0.7, color: t.text }}>{axis.axis}</span>
+                  {axis.values.map((v) => {
+                    const on = selection[axis.optionTypeId] === v.optionValueId;
+                    return (
+                      <button
+                        key={v.optionValueId}
+                        type="button"
+                        aria-pressed={on}
+                        aria-label={`${axis.axis}: ${v.value}`}
+                        disabled={!v.isAvailable}
+                        onClick={() => select(axis.optionTypeId, v.optionValueId)}
+                        style={{
+                          padding: "6px 12px",
+                          fontSize: 13,
+                          borderRadius: t.cornerRadius,
+                          cursor: v.isAvailable ? "pointer" : "not-allowed",
+                          opacity: v.isAvailable ? 1 : 0.5,
+                          color: t.text,
+                          background: on ? a(t.primary, 0.1) : "transparent",
+                          border: `1px solid ${on ? t.primary : a(t.text, 0.25)}`,
+                        }}
+                      >
+                        {v.value}
+                      </button>
+                    );
+                  })}
+                </div>
+              ))}
+
               <div style={{ display: "flex", gap: 10, flexWrap: "wrap", marginTop: 4 }}>
                 <Button onClick={() => buyNow(defaultVariant, { canIncreaseQuantity: false })}>Buy now</Button>
                 <Button variant="outline" onClick={() => add(defaultVariant, { canIncreaseQuantity: false })}>

package/src/ui/styled/ProductGrid.tsx

@@ -1,5 +1,5 @@
 import { useGetProducts, useGetProductsByIds } from "../../data/queries/useProducts";
-import type { IPublicProduct } from "../../types/models";
+import type { IPublicProduct, ProductType } from "../../types/models";
 import { useThemeTokens } from "../theme/ForgeThemeProvider";
 import { useAmountFormatter } from "../format/useFormatCurrency";
 import { PriceDisplay } from "../format/PriceDisplay";
@@ -15,6 +15,17 @@ export interface ProductGridProps {
    * "the first N products".
    */
   productIds?: string[];
+  /**
+   * Show only products filed under this category. **Descendant-inclusive** —
+   * passing "Apparel" returns everything beneath it at any depth, which is what
+   * makes a parent category a usable browse destination rather than an empty
+   * page.
+   */
+  categoryId?: string;
+  /** Show only products in this collection, in the creator's curated order. */
+  collectionId?: string;
+  /** Show only products of this kind (Music / Merch / Digital / Service). */
+  productType?: ProductType[];
   formatAmount?: (amount: number) => string;
   onSelect?: (product: IPublicProduct) => void;
   /**
@@ -39,6 +50,9 @@ export function ProductGrid({
   columns = 3,
   limit,
   productIds,
+  categoryId,
+  collectionId,
+  productType,
   formatAmount,
   onSelect,
   hrefFor,
@@ -52,7 +66,7 @@ export function ProductGrid({
   const byIds = !!productIds?.length;
   // Both hooks are called unconditionally (rules of hooks); each disables
   // itself when it isn't the one in use.
-  const listQuery = useGetProducts({ page: 1 }, !byIds);
+  const listQuery = useGetProducts({ page: 1, categoryId, collectionId, productType }, !byIds);
   const idsQuery = useGetProductsByIds(byIds ? productIds! : []);
 
   const isLoading = byIds ? idsQuery.isLoading : listQuery.isLoading;