create-magic-storefront 0.5.0 → 0.6.0

package/template/components/product/buy-box.tsx

@@ -0,0 +1,148 @@
+'use client';
+
+import {
+  MagicStoreError,
+  useAnalytics,
+  useCart,
+  useMagicStore,
+  useWishlist,
+} from '@magicstoreai/hydrogen';
+import { useEffect, useState } from 'react';
+
+import { useCartDrawer } from '@/components/cart/cart-drawer';
+import { Button } from '@/components/ui/button';
+import { Icon } from '@/components/ui/icon';
+import { Price } from '@/components/ui/price';
+import { QuantityStepper } from '@/components/ui/quantity-stepper';
+import { messages, type Messages } from '@/lib/i18n';
+
+import { PreOrderForm } from './pre-order-form';
+import { useProductSelection } from './product-selection';
+import { VariantPicker } from './variant-picker';
+
+/** At or below this many in stock, the buy box says how many are left (the API's number). */
+const LOW_STOCK = 5;
+
+/**
+ * The price, the variant picker, the stock the API reports, a quantity and add to cart (which
+ * opens the cart drawer) — or a pre-order form for a product open for pre-order — the wishlist
+ * toggle, and the shop's delivery terms.
+ */
+export function BuyBox({
+  wishlist: wishlistEnabled,
+  deliveryText,
+}: {
+  wishlist: boolean;
+  deliveryText: string | null;
+}) {
+  const { product, selectedVariant } = useProductSelection();
+  const { addLine, status } = useCart();
+  const wishlist = useWishlist();
+  const analytics = useAnalytics();
+  const cartDrawer = useCartDrawer();
+  const t = messages(useMagicStore().locale);
+  const [quantity, setQuantity] = useState(1);
+  const [adding, setAdding] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(
+    () => analytics.productView(product.id, selectedVariant?.id),
+    [analytics, product.id, selectedVariant?.id],
+  );
+  useEffect(() => setQuantity(1), [selectedVariant?.id]);
+
+  // A product without options has one variant; a product without variants is bought as itself.
+  const hasVariants = product.variants.length > 0;
+  const variant = hasVariants ? selectedVariant : null;
+  const forSale = hasVariants
+    ? Boolean(selectedVariant?.availableForSale)
+    : product.availableForSale;
+  const stock = hasVariants
+    ? (selectedVariant?.quantityAvailable ?? null)
+    : product.quantityAvailable;
+  const saved = wishlist.has(product.id);
+
+  async function add() {
+    setError(null);
+    setAdding(true);
+    try {
+      await addLine({ productId: product.id, variantId: variant?.id ?? null, quantity });
+      cartDrawer.added();
+    } catch (e) {
+      setError(e instanceof MagicStoreError ? (e.detail ?? e.message) : t.couldNotAdd);
+    } finally {
+      setAdding(false);
+    }
+  }
+
+  return (
+    <div className="buy-box">
+      <Price
+        price={variant?.price ?? product.price}
+        compareAtPrice={variant ? variant.compareAtPrice : product.compareAtPrice}
+        size="lg"
+      />
+      <VariantPicker />
+      {!product.preOrder && <StockNote forSale={forSale} stock={stock} t={t} />}
+      {product.preOrder && variant ? (
+        <PreOrderForm productId={product.id} variantId={variant.id} t={t} />
+      ) : (
+        <div className="buy-box__actions">
+          {forSale && (
+            <QuantityStepper
+              value={quantity}
+              onChange={setQuantity}
+              max={stock}
+              label={t.quantity}
+              decreaseLabel={t.decreaseQuantity}
+              increaseLabel={t.increaseQuantity}
+            />
+          )}
+          <Button
+            variant="primary"
+            size="lg"
+            className="buy-box__add"
+            disabled={!forSale || status === 'updating'}
+            loading={adding}
+            onClick={add}
+          >
+            {forSale ? t.addToCart : t.soldOut}
+          </Button>
+          {wishlistEnabled && (
+            <button
+              type="button"
+              className="icon-button buy-box__wishlist"
+              aria-label={saved ? t.saved : t.save}
+              aria-pressed={saved}
+              onClick={() => void wishlist.toggle(product.id)}
+            >
+              <Icon name="heart" />
+            </button>
+          )}
+        </div>
+      )}
+      {error && (
+        <p className="error" role="alert">
+          {error}
+        </p>
+      )}
+      <p className="buy-box__delivery">
+        <Icon name="truck" />
+        <span>{deliveryText ?? t.deliveryAtCheckout}</span>
+      </p>
+    </div>
+  );
+}
+
+/** Stock only as the API reports it: nothing when it is not tracked, never an invented number. */
+function StockNote({ forSale, stock, t }: { forSale: boolean; stock: number | null; t: Messages }) {
+  if (!forSale || stock === null) {
+    return null;
+  }
+  return (
+    <p className={stock <= LOW_STOCK ? 'stock-note stock-note--low' : 'stock-note'}>
+      <span className="stock-note__dot" aria-hidden="true" />
+      {stock <= LOW_STOCK ? t.lowStock(stock) : t.inStock}
+    </p>
+  );
+}

package/template/components/product/gallery.tsx

@@ -0,0 +1,179 @@
+'use client';
+
+import { Image, useMagicStore } from '@magicstoreai/hydrogen';
+import type { Schema } from '@magicstoreai/storefront-client';
+import { useEffect, useRef, useState } from 'react';
+
+import { Icon } from '@/components/ui/icon';
+import { messages } from '@/lib/i18n';
+
+import { useProductSelection } from './product-selection';
+
+type ImageData = Schema<'Image'>;
+
+/**
+ * The product's images (and its video, last): a swipeable scroll-snap track with a counter on
+ * phones, thumbnails and arrows from 750px. Choosing a variant with an image shows that image. The
+ * first image loads eagerly with high priority, the rest lazily; slides keep the theme's ratio.
+ */
+export function Gallery({
+  images,
+  video,
+  title,
+}: {
+  images: ImageData[];
+  video: string | null;
+  title: string;
+}) {
+  const t = messages(useMagicStore().locale);
+  const { selectedVariant } = useProductSelection();
+  const variantImage = selectedVariant?.image ?? null;
+  // A variant image the product list does not hold goes first.
+  const slides =
+    variantImage && !images.some((image) => image.url === variantImage.url)
+      ? [variantImage, ...images]
+      : images;
+  const total = slides.length + (video ? 1 : 0);
+  const [active, setActive] = useState(0);
+  const track = useRef<HTMLDivElement>(null);
+  const thumbs = useRef<HTMLUListElement>(null);
+
+  function show(index: number) {
+    const element = track.current;
+    if (element) {
+      element.scrollTo({ left: index * element.clientWidth });
+    }
+    setActive(index);
+  }
+
+  useEffect(() => {
+    if (variantImage) {
+      show(
+        Math.max(
+          0,
+          slides.findIndex((image) => image.url === variantImage.url),
+        ),
+      );
+    }
+    // Only a new variant image moves the gallery, not a new slides array.
+  }, [variantImage?.url]);
+
+  useEffect(() => {
+    const list = thumbs.current;
+    const thumb = list?.children[active] as HTMLElement | undefined;
+    if (!list || !thumb) {
+      return;
+    }
+    const start = thumb.offsetLeft - list.offsetLeft;
+    if (start < list.scrollLeft || start + thumb.offsetWidth > list.scrollLeft + list.clientWidth) {
+      list.scrollTo({ left: start - list.clientWidth / 2 + thumb.offsetWidth / 2 });
+    }
+  }, [active]);
+
+  if (total === 0) {
+    return (
+      <div className="gallery">
+        <div className="gallery__slide">
+          <span className="media-fallback" />
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div className="gallery" role="region" aria-roledescription="carousel" aria-label={title}>
+      <div className="gallery__viewport">
+        <div
+          ref={track}
+          className="gallery__track"
+          onScroll={(event) => {
+            const element = event.currentTarget;
+            setActive(Math.round(element.scrollLeft / element.clientWidth));
+          }}
+        >
+          {slides.map((image, index) => (
+            <div
+              key={image.url}
+              className="gallery__slide"
+              role="group"
+              aria-roledescription="slide"
+              aria-label={t.imageOf(index + 1, total)}
+            >
+              <Image
+                data={image}
+                alt={index === 0 ? title : ''}
+                loading={index === 0 ? 'eager' : 'lazy'}
+                fetchPriority={index === 0 ? 'high' : undefined}
+              />
+            </div>
+          ))}
+          {video && (
+            <div
+              className="gallery__slide gallery__slide--video"
+              role="group"
+              aria-roledescription="slide"
+              aria-label={t.video}
+            >
+              <video src={video} controls playsInline preload="metadata" />
+            </div>
+          )}
+        </div>
+        {total > 1 && (
+          <>
+            <p className="gallery__counter" aria-hidden="true">
+              {active + 1} / {total}
+            </p>
+            <button
+              type="button"
+              className="icon-button gallery__arrow gallery__arrow--prev"
+              aria-label={t.previousImage}
+              disabled={active === 0}
+              onClick={() => show(active - 1)}
+            >
+              <Icon name="chevron-left" />
+            </button>
+            <button
+              type="button"
+              className="icon-button gallery__arrow gallery__arrow--next"
+              aria-label={t.nextImage}
+              disabled={active === total - 1}
+              onClick={() => show(active + 1)}
+            >
+              <Icon name="chevron-right" />
+            </button>
+          </>
+        )}
+      </div>
+      {total > 1 && (
+        <ul ref={thumbs} className="gallery__thumbs">
+          {slides.map((image, index) => (
+            <li key={image.url}>
+              <button
+                type="button"
+                className="gallery__thumb"
+                aria-label={t.imageOf(index + 1, total)}
+                aria-current={index === active || undefined}
+                onClick={() => show(index)}
+              >
+                <Image data={image} alt="" width={64} height={64} />
+              </button>
+            </li>
+          ))}
+          {video && (
+            <li>
+              <button
+                type="button"
+                className="gallery__thumb gallery__thumb--video"
+                aria-label={t.video}
+                aria-current={active === slides.length || undefined}
+                onClick={() => show(slides.length)}
+              >
+                <Icon name="play" />
+              </button>
+            </li>
+          )}
+        </ul>
+      )}
+    </div>
+  );
+}

package/template/components/product/pre-order-form.tsx

@@ -0,0 +1,93 @@
+'use client';
+
+import { MagicStoreError, useCustomer, useStorefrontClient } from '@magicstoreai/hydrogen';
+import { useState, type FormEvent } from 'react';
+
+import { Button } from '@/components/ui/button';
+import type { Messages } from '@/lib/i18n';
+
+/**
+ * A pre-order (`POST /pre-orders`): a button that opens a short form — name and phone; a signed-in
+ * customer sends none, the shop uses theirs. The phone goes in the request body only.
+ */
+export function PreOrderForm({
+  productId,
+  variantId,
+  t,
+}: {
+  productId: string;
+  variantId: string;
+  t: Messages;
+}) {
+  const client = useStorefrontClient();
+  const { isSignedIn } = useCustomer();
+  const [open, setOpen] = useState(false);
+  const [sending, setSending] = useState(false);
+  const [sent, setSent] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  async function submit(event: FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    const form = new FormData(event.currentTarget);
+    setError(null);
+    setSending(true);
+    try {
+      await client.preOrdersStore({
+        body: {
+          productId,
+          variantId,
+          quantity: 1,
+          ...(!isSignedIn && {
+            name: String(form.get('name')),
+            phone: String(form.get('phone')),
+          }),
+        },
+      });
+      setSent(true);
+    } catch (e) {
+      setError(e instanceof MagicStoreError ? (e.detail ?? e.message) : t.somethingWentWrong);
+    } finally {
+      setSending(false);
+    }
+  }
+
+  if (sent) {
+    return (
+      <p className="buy-box__note" role="status">
+        {t.preOrderSent}
+      </p>
+    );
+  }
+  if (!open && !isSignedIn) {
+    return (
+      <Button variant="primary" size="lg" full onClick={() => setOpen(true)}>
+        {t.preOrder}
+      </Button>
+    );
+  }
+  return (
+    <form className="pre-order stack" onSubmit={submit}>
+      {!isSignedIn && (
+        <>
+          <p className="muted text-sm">{t.preOrderHint}</p>
+          <label className="field">
+            <span className="field__label">{t.name}</span>
+            <input name="name" autoComplete="name" required maxLength={255} />
+          </label>
+          <label className="field">
+            <span className="field__label">{t.phone}</span>
+            <input name="phone" type="tel" autoComplete="tel" required maxLength={32} />
+          </label>
+        </>
+      )}
+      <Button type="submit" variant="primary" size="lg" full loading={sending}>
+        {isSignedIn ? t.preOrder : t.sendPreOrder}
+      </Button>
+      {error && (
+        <p className="error" role="alert">
+          {error}
+        </p>
+      )}
+    </form>
+  );
+}

package/template/components/product/product-selection.tsx

@@ -0,0 +1,31 @@
+'use client';
+
+import { useVariantSelection } from '@magicstoreai/hydrogen';
+import type { Schema } from '@magicstoreai/storefront-client';
+import { createContext, useContext, type ReactNode } from 'react';
+
+type Product = Schema<'ProductDetail'>;
+type Selection = ReturnType<typeof useVariantSelection> & { product: Product };
+
+const SelectionContext = createContext<Selection | null>(null);
+
+/**
+ * The chosen variant, shared by the parts of the product page that depend on it: the gallery shows
+ * its image, the picker and the buy box its options, price and stock.
+ */
+export function ProductSelection({ product, children }: { product: Product; children: ReactNode }) {
+  const selection = useVariantSelection(product);
+  return (
+    <SelectionContext.Provider value={{ ...selection, product }}>
+      {children}
+    </SelectionContext.Provider>
+  );
+}
+
+export function useProductSelection(): Selection {
+  const selection = useContext(SelectionContext);
+  if (selection === null) {
+    throw new Error('useProductSelection must be used inside <ProductSelection>.');
+  }
+  return selection;
+}

package/template/components/product/recommendations.tsx

@@ -0,0 +1,26 @@
+import type { Schema } from '@magicstoreai/storefront-client';
+
+import { ProductGrid } from '@/components/product-grid';
+
+/** A shelf of recommended products under the product; nothing when the API has none. */
+export function Recommendations({
+  title,
+  products,
+  locale,
+}: {
+  title: string;
+  products: Schema<'Product'>[];
+  locale: string;
+}) {
+  if (products.length === 0) {
+    return null;
+  }
+  return (
+    <section className="product-recommendations">
+      <div className="section-header">
+        <h2>{title}</h2>
+      </div>
+      <ProductGrid products={products} locale={locale} eager={false} />
+    </section>
+  );
+}

package/template/components/product/review-list.tsx

@@ -0,0 +1,159 @@
+'use client';
+
+import { Image, MagicStoreError, useMagicStore, useStorefrontClient } from '@magicstoreai/hydrogen';
+import type { Schema } from '@magicstoreai/storefront-client';
+import { useState } from 'react';
+
+import { Badge } from '@/components/ui/badge';
+import { Button } from '@/components/ui/button';
+import { Rating } from '@/components/ui/rating';
+import { messages, type Messages } from '@/lib/i18n';
+
+type Review = Schema<'Review'>;
+type Pagination = Schema<'Pagination'>;
+
+/**
+ * The review list: the server's first page, then "show more" and a filter by rating, both asked of
+ * the API (`productsReviews`, `filter[rating]`).
+ */
+export function ReviewList({
+  handle,
+  initial,
+  pagination,
+  perPage,
+  ratings,
+  locale,
+}: {
+  handle: string;
+  initial: Review[];
+  pagination: Pagination;
+  perPage: number;
+  ratings: number[];
+  locale: string;
+}) {
+  const client = useStorefrontClient();
+  const t = messages(useMagicStore().locale);
+  const [reviews, setReviews] = useState(initial);
+  const [page, setPage] = useState(pagination);
+  const [rating, setRating] = useState<number | null>(null);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  async function load(next: number, filter: number | null) {
+    setError(null);
+    setLoading(true);
+    try {
+      const result = await client.productsReviews({
+        path: { handle },
+        query: {
+          page: next,
+          perPage,
+          ...(filter !== null && { 'filter[rating]': String(filter) }),
+        },
+      });
+      setReviews((current) => (next === 1 ? result.data : [...current, ...result.data]));
+      setPage(result.meta.pagination);
+    } catch (e) {
+      setError(e instanceof MagicStoreError ? (e.detail ?? e.message) : t.somethingWentWrong);
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  function filterBy(next: number | null) {
+    setRating(next);
+    void load(1, next);
+  }
+
+  return (
+    <div className="review-list">
+      {ratings.length > 1 && (
+        <div className="chips review-list__filter" role="group" aria-label={t.reviews}>
+          <button type="button" aria-pressed={rating === null} onClick={() => filterBy(null)}>
+            {t.allRatings}
+          </button>
+          {[...ratings]
+            .sort((a, b) => b - a)
+            .map((stars) => (
+              <button
+                key={stars}
+                type="button"
+                aria-pressed={rating === stars}
+                onClick={() => filterBy(stars)}
+              >
+                {t.starsFilter(stars)}
+              </button>
+            ))}
+        </div>
+      )}
+      {reviews.length === 0 && !loading && <p className="muted">{t.noReviewsForRating}</p>}
+      <ul className="review-list__items" aria-busy={loading || undefined}>
+        {reviews.map((review) => (
+          <ReviewItem key={review.id} review={review} locale={locale} t={t} />
+        ))}
+      </ul>
+      {error && (
+        <p className="error" role="alert">
+          {error}
+        </p>
+      )}
+      {page.hasNextPage && (
+        <Button loading={loading} onClick={() => void load(page.page + 1, rating)}>
+          {t.showMoreReviews}
+        </Button>
+      )}
+    </div>
+  );
+}
+
+function ReviewItem({ review, locale, t }: { review: Review; locale: string; t: Messages }) {
+  const date = review.publishedAt ?? review.createdAt;
+  return (
+    <li className="review">
+      <div className="review__header">
+        <Rating
+          average={review.rating}
+          count={1}
+          label={t.ratedOutOf(review.rating)}
+          showCount={false}
+        />
+        <span className="review__author">{review.author.name}</span>
+        {date && (
+          <time className="muted text-sm" dateTime={date}>
+            {new Intl.DateTimeFormat(locale, { dateStyle: 'medium' }).format(new Date(date))}
+          </time>
+        )}
+        {review.isVerifiedBuyer && <Badge kind="neutral">{t.verifiedBuyer}</Badge>}
+      </div>
+      {review.variantTitle && <p className="muted text-sm">{review.variantTitle}</p>}
+      {review.body && <p className="review__body">{review.body}</p>}
+      {review.pros && (
+        <p>
+          <strong>{t.pros}:</strong> {review.pros}
+        </p>
+      )}
+      {review.cons && (
+        <p>
+          <strong>{t.cons}:</strong> {review.cons}
+        </p>
+      )}
+      {review.images.length > 0 && (
+        <ul className="review__images">
+          {review.images.map((image) => (
+            <li key={image.url}>
+              <a href={image.url} target="_blank" rel="noopener noreferrer">
+                <Image data={image} alt="" width={72} height={72} />
+              </a>
+            </li>
+          ))}
+        </ul>
+      )}
+      {review.reply && (
+        <div className="review__reply">
+          <p className="review__reply-title">{t.shopReply}</p>
+          <p>{review.reply}</p>
+        </div>
+      )}
+    </li>
+  );
+}