create-magic-storefront 0.1.0

package/template/components/buy-box.tsx

@@ -0,0 +1,86 @@
+'use client';
+
+import {
+  MagicStoreError,
+  Money,
+  useAnalytics,
+  useCart,
+  useVariantSelection,
+  useWishlist,
+} from '@magicstoreai/hydrogen';
+import type { Schema } from '@magicstoreai/storefront-client';
+import { useEffect, useState } from 'react';
+
+export function BuyBox({ product }: { product: Schema<'ProductDetail'> }) {
+  const { selectedOptions, selectedVariant, setOption, isAvailable } = useVariantSelection(product);
+  const { addLine, status } = useCart();
+  const wishlist = useWishlist();
+  const analytics = useAnalytics();
+  const [error, setError] = useState<string | null>(null);
+  const [added, setAdded] = useState(false);
+
+  useEffect(
+    () => analytics.productView(product.id, selectedVariant?.id),
+    [analytics, product.id, selectedVariant?.id],
+  );
+
+  // A product without options has one variant; a product without variants is bought as itself.
+  const variantId = product.variants.length > 0 ? (selectedVariant?.id ?? null) : null;
+  const forSale =
+    product.variants.length > 0
+      ? Boolean(selectedVariant?.availableForSale)
+      : product.availableForSale;
+
+  async function add() {
+    setError(null);
+    try {
+      await addLine({ productId: product.id, variantId, quantity: 1 });
+      setAdded(true);
+    } catch (e) {
+      setError(e instanceof MagicStoreError ? (e.detail ?? e.message) : 'Could not add.');
+    }
+  }
+
+  return (
+    <div className="stack">
+      <div className="row">
+        <Money data={selectedVariant?.price ?? product.price} />
+        {(selectedVariant?.compareAtPrice ?? product.compareAtPrice) && (
+          <s className="muted">
+            <Money data={selectedVariant?.compareAtPrice ?? product.compareAtPrice} />
+          </s>
+        )}
+      </div>
+      {product.options
+        .filter((option) => option.values.length > 1)
+        .map((option) => (
+          <fieldset key={option.name}>
+            <legend>{option.name}</legend>
+            <div className="row">
+              {option.values.map((value) => (
+                <button
+                  key={value}
+                  type="button"
+                  aria-pressed={selectedOptions[option.name] === value}
+                  disabled={!isAvailable(option.name, value)}
+                  onClick={() => setOption(option.name, value)}
+                >
+                  {value}
+                </button>
+              ))}
+            </div>
+          </fieldset>
+        ))}
+      <div className="row">
+        <button className="primary" disabled={!forSale || status === 'updating'} onClick={add}>
+          {forSale ? 'Add to cart' : 'Sold out'}
+        </button>
+        <button type="button" onClick={() => void wishlist.toggle(product.id)}>
+          {wishlist.has(product.id) ? '♥ Saved' : '♡ Save'}
+        </button>
+      </div>
+      {added && <p className="muted">Added to cart.</p>}
+      {error && <p className="error">{error}</p>}
+    </div>
+  );
+}

package/template/components/cart-link.tsx

@@ -0,0 +1,9 @@
+'use client';
+
+import { useCart } from '@magicstoreai/hydrogen';
+import Link from 'next/link';
+
+export function CartLink() {
+  const { totalQuantity } = useCart();
+  return <Link href="/cart">Cart ({totalQuantity})</Link>;
+}

package/template/components/pager.tsx

@@ -0,0 +1,25 @@
+import { paginationState, type Pagination } from '@magicstoreai/hydrogen';
+import Link from 'next/link';
+
+/** Server-rendered page links (`paginationState` is plain arithmetic, no hooks). */
+export function Pager({ meta, href }: { meta: Pagination; href: (page: number) => string }) {
+  if (meta.totalPages <= 1) {
+    return null;
+  }
+  const state = paginationState(meta);
+  return (
+    <nav className="pager" aria-label="Pages">
+      {state.pages.map((page, index) =>
+        page === null ? (
+          <span key={`gap-${index}`}>…</span>
+        ) : page === state.page ? (
+          <strong key={page}>{page}</strong>
+        ) : (
+          <Link key={page} href={href(page)}>
+            {page}
+          </Link>
+        ),
+      )}
+    </nav>
+  );
+}

package/template/components/product-grid.tsx

@@ -0,0 +1,32 @@
+import { Image, Money } from '@magicstoreai/hydrogen';
+import type { Schema } from '@magicstoreai/storefront-client';
+import Link from 'next/link';
+
+export function ProductGrid({ products }: { products: Schema<'Product'>[] }) {
+  if (products.length === 0) {
+    return <p className="muted">Nothing here yet.</p>;
+  }
+  return (
+    <div className="grid">
+      {products.map((product) => (
+        <Link key={product.id} href={`/products/${product.handle}`} className="card">
+          <Image
+            data={product.featuredImage}
+            alt={product.title}
+            fallback={<div className="noimg" />}
+          />
+          <span>{product.title}</span>
+          <span className="row">
+            <Money data={product.price} fallback={<span className="muted">—</span>} />
+            {product.compareAtPrice && (
+              <s className="muted">
+                <Money data={product.compareAtPrice} />
+              </s>
+            )}
+          </span>
+          {!product.availableForSale && <span className="muted">Sold out</span>}
+        </Link>
+      ))}
+    </div>
+  );
+}

package/template/components/sections/announcement-bar.tsx

@@ -0,0 +1,13 @@
+import type { SectionOf } from './types';
+
+export function AnnouncementBar({ section }: { section: SectionOf<'ANNOUNCEMENT_BAR'> }) {
+  const { text, backgroundColor, textColor, animation } = section.settings;
+  return (
+    <p
+      className={`announcement announcement-${animation.toLowerCase()}`}
+      style={{ background: backgroundColor ?? undefined, color: textColor ?? undefined }}
+    >
+      <span>{text}</span>
+    </p>
+  );
+}

package/template/components/sections/banner.tsx

@@ -0,0 +1,41 @@
+import { Image } from '@magicstoreai/hydrogen';
+import Link from 'next/link';
+
+import type { SectionOf } from './types';
+
+type Slide = SectionOf<'BANNER'>['settings']['slides'][number];
+
+/** Where a slide leads; `null` when it leads nowhere or to a URL that is neither a path nor http(s). */
+function slideHref(link: Slide['link']): string | null {
+  if (link === null) {
+    return null;
+  }
+  switch (link.type) {
+    case 'PRODUCT':
+      return link.product ? `/products/${link.product.handle}` : null;
+    case 'COLLECTION':
+      return link.collection ? `/collections/${link.collection.handle}` : null;
+    case 'URL':
+      return link.url && /^(\/(?!\/)|https?:\/\/)/.test(link.url) ? link.url : null;
+  }
+}
+
+export function Banner({ section }: { section: SectionOf<'BANNER'> }) {
+  return (
+    <section className="banner">
+      {section.settings.slides.map((slide, index) => {
+        const image = (
+          <Image data={slide.image} loading={index === 0 ? 'eager' : 'lazy'} alt="Banner" />
+        );
+        const href = slideHref(slide.link);
+        return href === null ? (
+          <div key={index}>{image}</div>
+        ) : (
+          <Link key={index} href={href}>
+            {image}
+          </Link>
+        );
+      })}
+    </section>
+  );
+}

package/template/components/sections/collections.tsx

@@ -0,0 +1,67 @@
+import { Image } from '@magicstoreai/hydrogen';
+import type { Schema } from '@magicstoreai/storefront-client';
+import Link from 'next/link';
+
+import { api } from '@/lib/api';
+
+import type { SectionOf } from './types';
+
+function CollectionTiles({
+  collections,
+  className = '',
+}: {
+  collections: Schema<'Collection'>[];
+  className?: string;
+}) {
+  if (collections.length === 0) {
+    return null;
+  }
+  return (
+    <div className={`grid ${className}`}>
+      {collections.map((collection) => (
+        <Link key={collection.id} href={`/collections/${collection.handle}`} className="card">
+          <Image
+            data={collection.image}
+            alt={collection.title}
+            fallback={<div className="noimg" />}
+          />
+          <span>{collection.title}</span>
+        </Link>
+      ))}
+    </div>
+  );
+}
+
+/** The collections the merchant flagged for the main navigation (`featured`). */
+export async function FeaturedCollections(_: { section: SectionOf<'FEATURED_COLLECTIONS'> }) {
+  const { data } = await api.collectionsIndex({
+    query: { 'filter[featured]': 'true', perPage: 12 },
+  });
+  return <CollectionTiles collections={data} />;
+}
+
+/** Top-level collections; `cardStyle` is a hint the theme may honour — here a CSS class. */
+export async function Collections({ section }: { section: SectionOf<'COLLECTIONS'> }) {
+  const { data } = await api.collectionsIndex({ query: { 'filter[root]': 'true', perPage: 24 } });
+  const style = section.settings.cardStyle;
+  return (
+    <CollectionTiles
+      collections={data}
+      className={style ? `cards-${style.toLowerCase().replaceAll('_', '-')}` : ''}
+    />
+  );
+}
+
+/** Tiles the merchant picked by hand, each with an optional image of its own. */
+export function CollectionGrid({ section }: { section: SectionOf<'COLLECTION_GRID'> }) {
+  return (
+    <div className="grid">
+      {section.settings.tiles.map(({ collection, image }) => (
+        <Link key={collection.id} href={`/collections/${collection.handle}`} className="card">
+          <Image data={image} alt={collection.title} fallback={<div className="noimg" />} />
+          <span>{collection.title}</span>
+        </Link>
+      ))}
+    </div>
+  );
+}

package/template/components/sections/deal-of-day.tsx

@@ -0,0 +1,48 @@
+import { Image, Money } from '@magicstoreai/hydrogen';
+import Link from 'next/link';
+
+import type { SectionOf } from './types';
+
+export function DealOfDay({ section }: { section: SectionOf<'DEAL_OF_DAY'> }) {
+  const { product, image, price, compareAtPrice, endsAt, accentColor, badgeText, stock } =
+    section.settings;
+  return (
+    <section className="deal" style={{ borderColor: accentColor ?? undefined }}>
+      <Link href={`/products/${product.handle}`}>
+        <Image data={image} alt={product.title} fallback={<div className="noimg" />} />
+      </Link>
+      <div className="stack">
+        {badgeText && (
+          <span className="badge" style={{ background: accentColor ?? undefined }}>
+            {badgeText}
+          </span>
+        )}
+        <h2>
+          <Link href={`/products/${product.handle}`}>{product.title}</Link>
+        </h2>
+        <span className="row">
+          <Money data={price} />
+          {compareAtPrice && (
+            <s className="muted">
+              <Money data={compareAtPrice} />
+            </s>
+          )}
+        </span>
+        {/* The merchant's "N of M left" bar — not the product's real stock. */}
+        {stock && (
+          <label className="stack">
+            <span className="muted">
+              {stock.remaining} of {stock.initial} left
+            </span>
+            <progress value={stock.remaining} max={Math.max(stock.initial, stock.remaining, 1)} />
+          </label>
+        )}
+        {endsAt && (
+          <span className="muted">
+            Ends <time dateTime={endsAt}>{new Date(endsAt).toUTCString()}</time>
+          </span>
+        )}
+      </div>
+    </section>
+  );
+}

package/template/components/sections/index.tsx

@@ -0,0 +1,66 @@
+import type { ReactNode } from 'react';
+
+import { AnnouncementBar } from './announcement-bar';
+import { Banner } from './banner';
+import { CollectionGrid, Collections, FeaturedCollections } from './collections';
+import { DealOfDay } from './deal-of-day';
+import {
+  Bestsellers,
+  CollectionProducts,
+  FlashSale,
+  ForYou,
+  NewArrivals,
+  OnSale,
+  PreOrders,
+  Trending,
+} from './product-shelves';
+import { ShoppableStories } from './shoppable-stories';
+import { StoreReviews } from './store-reviews';
+import type { HomeSection, HomeSectionType, SectionOf } from './types';
+
+type SectionRenderer<Type extends HomeSectionType> = (props: {
+  section: SectionOf<Type>;
+}) => ReactNode | Promise<ReactNode>;
+
+/**
+ * One renderer per `GET /home` section type. Typed against the generated `HomeSectionType`, so a
+ * type the backend adds (after `pnpm sync:spec` + generate) fails the typecheck until it is here.
+ */
+export const SECTION_RENDERERS: { [Type in HomeSectionType]: SectionRenderer<Type> } = {
+  ANNOUNCEMENT_BAR: AnnouncementBar,
+  BANNER: Banner,
+  FEATURED_COLLECTIONS: FeaturedCollections,
+  COLLECTIONS: Collections,
+  COLLECTION_GRID: CollectionGrid,
+  NEW_ARRIVALS: NewArrivals,
+  ON_SALE: OnSale,
+  TRENDING: Trending,
+  BESTSELLERS: Bestsellers,
+  PRE_ORDERS: PreOrders,
+  FOR_YOU: ForYou,
+  COLLECTION_PRODUCTS: CollectionProducts,
+  FLASH_SALE: FlashSale,
+  DEAL_OF_DAY: DealOfDay,
+  SHOPPABLE_STORIES: ShoppableStories,
+  STORE_REVIEWS: StoreReviews,
+};
+
+/**
+ * The renderer for a section, or `null` for a type this storefront does not know yet — a live API
+ * may send a newer type than the spec it was built from, and an unknown section renders nothing.
+ */
+export function sectionRenderer(section: HomeSection): SectionRenderer<HomeSectionType> | null {
+  if (!Object.hasOwn(SECTION_RENDERERS, section.type)) {
+    return null;
+  }
+  // The map is keyed by `type`, so the renderer always matches the section it is picked for.
+  return SECTION_RENDERERS[section.type] as SectionRenderer<HomeSectionType>;
+}
+
+/** The home page's sections in the merchant's order. */
+export function HomeSections({ sections }: { sections: HomeSection[] }) {
+  return sections.map((section) => {
+    const Renderer = sectionRenderer(section);
+    return Renderer === null ? null : <Renderer key={section.id} section={section} />;
+  });
+}

package/template/components/sections/product-shelves.tsx

@@ -0,0 +1,123 @@
+import type { Schema } from '@magicstoreai/storefront-client';
+import Link from 'next/link';
+import type { ReactNode } from 'react';
+
+import { ProductGrid } from '@/components/product-grid';
+import { api } from '@/lib/api';
+
+import { SHELF_SIZE, type SectionOf } from './types';
+
+function Shelf({
+  title,
+  href,
+  products,
+  children,
+}: {
+  title: string;
+  href?: string;
+  products: Schema<'Product'>[];
+  children?: ReactNode;
+}) {
+  // The server drops a section that would show nothing, but a shelf can empty between the two reads.
+  if (products.length === 0) {
+    return null;
+  }
+  return (
+    <section className="stack">
+      <div className="row">
+        <h2>{title}</h2>
+        {children}
+        {href && <Link href={href}>See all</Link>}
+      </div>
+      <ProductGrid products={products} />
+    </section>
+  );
+}
+
+type ShelfSection = SectionOf<
+  'NEW_ARRIVALS' | 'ON_SALE' | 'TRENDING' | 'BESTSELLERS' | 'PRE_ORDERS'
+>;
+
+export async function NewArrivals({ section }: { section: ShelfSection }) {
+  const { data } = await api.productsIndex({
+    query: { sort: '-createdAt', perPage: section.settings.limit ?? SHELF_SIZE },
+  });
+  return <Shelf title="New arrivals" products={data} />;
+}
+
+export async function OnSale({ section }: { section: ShelfSection }) {
+  const { data } = await api.productsIndex({
+    query: { 'filter[onSale]': 'true', perPage: section.settings.limit ?? SHELF_SIZE },
+  });
+  return <Shelf title="On sale" products={data} />;
+}
+
+export async function Trending({ section }: { section: ShelfSection }) {
+  const { data } = await api.productsIndex({
+    query: { 'filter[trending]': 'true', perPage: section.settings.limit ?? SHELF_SIZE },
+  });
+  return <Shelf title="Trending" products={data} />;
+}
+
+export async function Bestsellers({ section }: { section: ShelfSection }) {
+  const { data } = await api.productsIndex({
+    query: { sort: '-bestSellers', perPage: section.settings.limit ?? SHELF_SIZE },
+  });
+  return <Shelf title="Bestsellers" products={data} />;
+}
+
+export async function PreOrders({ section }: { section: ShelfSection }) {
+  const { data } = await api.productsIndex({
+    query: { 'filter[preOrder]': 'true', perPage: section.settings.limit ?? SHELF_SIZE },
+  });
+  return <Shelf title="Pre-order" products={data} />;
+}
+
+/**
+ * Renders nothing on purpose: v2 has no product-independent personal shelf yet
+ * (`/products/{handle}/recommendations?intent=FOR_YOU` needs a product in context), and this page
+ * is cached for every visitor, so it must not be personal.
+ */
+export function ForYou(_: { section: SectionOf<'FOR_YOU'> }) {
+  return null;
+}
+
+export async function CollectionProducts({
+  section,
+}: {
+  section: SectionOf<'COLLECTION_PRODUCTS'>;
+}) {
+  const { collection, limit, title } = section.settings;
+  const { data } = await api.collectionsProducts({
+    path: { handle: collection.handle },
+    query: { perPage: limit ?? SHELF_SIZE },
+  });
+  return (
+    <Shelf
+      title={title ?? collection.title}
+      href={`/collections/${collection.handle}`}
+      products={data}
+    />
+  );
+}
+
+export async function FlashSale({ section }: { section: SectionOf<'FLASH_SALE'> }) {
+  const { collection, limit, title, endsAt } = section.settings;
+  const { data } = await api.collectionsProducts({
+    path: { handle: collection.handle },
+    query: { perPage: limit ?? SHELF_SIZE },
+  });
+  return (
+    <Shelf
+      title={title ?? collection.title}
+      href={`/collections/${collection.handle}`}
+      products={data}
+    >
+      {endsAt && (
+        <span className="muted">
+          Ends <time dateTime={endsAt}>{new Date(endsAt).toUTCString()}</time>
+        </span>
+      )}
+    </Shelf>
+  );
+}

package/template/components/sections/shoppable-stories.tsx

@@ -0,0 +1,39 @@
+import { Image } from '@magicstoreai/hydrogen';
+import Link from 'next/link';
+
+import type { SectionOf } from './types';
+
+/**
+ * Story bubbles. The starter has no story player: a bubble leads to the first product its frames
+ * tag, or shows no link when none does. A theme adds the player (frames, `autoplay`) on top.
+ */
+export function ShoppableStories({ section }: { section: SectionOf<'SHOPPABLE_STORIES'> }) {
+  const { layout, stories } = section.settings;
+  return (
+    <section className={`stories stories-${layout.toLowerCase()}`}>
+      {stories.map((story, index) => {
+        const product = story.frames.find((frame) => frame.product !== null)?.product ?? null;
+        const bubble = (
+          <>
+            <Image
+              data={story.thumbnail}
+              alt={story.title ?? ''}
+              fallback={<div className="noimg" />}
+            />
+            {story.title && <span>{story.title}</span>}
+          </>
+        );
+        const key = story.id ?? index;
+        return product === null ? (
+          <div key={key} className="story">
+            {bubble}
+          </div>
+        ) : (
+          <Link key={key} href={`/products/${product.handle}`} className="story">
+            {bubble}
+          </Link>
+        );
+      })}
+    </section>
+  );
+}

package/template/components/sections/store-reviews.tsx

@@ -0,0 +1,67 @@
+import Link from 'next/link';
+
+import { api } from '@/lib/api';
+
+import type { SectionOf } from './types';
+
+const SOURCE_LABELS = { GOOGLE: 'Google', YANDEX: 'Yandex', TWO_GIS: '2GIS', CUSTOM: '' } as const;
+
+/** Reviews of the shop itself (`GET /reviews/site`), dressed with what the merchant entered. */
+export async function StoreReviews({ section }: { section: SectionOf<'STORE_REVIEWS'> }) {
+  const settings = section.settings;
+  const { data: reviews, meta } = await api.reviewsSite({
+    query: { perPage: settings.limit, sort: '-createdAt' },
+  });
+  const { rating } = meta;
+
+  return (
+    <section className="stack">
+      {settings.overline && <span className="muted">{settings.overline}</span>}
+      <h2>{settings.title ?? 'What our customers say'}</h2>
+      {settings.subtitle && <p className="muted">{settings.subtitle}</p>}
+
+      <div className="row">
+        {rating.average !== null && (
+          <strong>
+            {rating.average} / 5 · {rating.count} reviews
+          </strong>
+        )}
+        {settings.recommendPercent !== null && (
+          <span>{settings.recommendPercent}% recommend us</span>
+        )}
+        {settings.externalRatings.map((external, index) => (
+          <span key={index} className="muted">
+            {external.label ?? SOURCE_LABELS[external.source]} {external.score}
+          </span>
+        ))}
+      </div>
+
+      {settings.showDistribution && rating.breakdown.length > 0 && (
+        <ul className="muted">
+          {rating.breakdown.map(({ rating: stars, count }) => (
+            <li key={stars}>
+              {stars}★ — {count}
+            </li>
+          ))}
+        </ul>
+      )}
+
+      <div className="grid">
+        {reviews.map((review) => (
+          <blockquote key={review.id} className="stack">
+            <span>{'★'.repeat(review.rating)}</span>
+            <p>{review.body}</p>
+            <footer className="muted">{review.author.name}</footer>
+          </blockquote>
+        ))}
+      </div>
+
+      {settings.showLeaveReview && (
+        // Leaving a site review needs a signed-in customer (POST /reviews/site).
+        <Link href="/account" className="button">
+          Leave a review
+        </Link>
+      )}
+    </section>
+  );
+}

package/template/components/sections/types.ts

@@ -0,0 +1,10 @@
+import type { Schema } from '@magicstoreai/storefront-client';
+
+export type HomeSection = Schema<'HomeSection'>;
+export type HomeSectionType = Schema<'HomeSectionType'>;
+
+/** The `GET /home` section of one type, with that type's own `settings`. */
+export type SectionOf<Type extends HomeSectionType> = Extract<HomeSection, { type: Type }>;
+
+/** Products a shelf shows when the merchant left `limit` empty (`null` = the storefront's default). */
+export const SHELF_SIZE = 8;

package/template/lib/api.ts

@@ -0,0 +1,35 @@
+import 'server-only';
+import { MagicStoreError, createStorefrontClient } from '@magicstoreai/storefront-client';
+import { nextCacheFetch } from '@magicstoreai/hydrogen/server';
+import { notFound } from 'next/navigation';
+
+import { upstreamBaseUrl } from './upstream';
+
+const baseUrl = upstreamBaseUrl();
+if (baseUrl === null) {
+  throw new Error('Set MAGICSTORE_SHOP_DOMAIN or MAGICSTORE_API_URL (see .env.example).');
+}
+
+export const locale = process.env.NEXT_PUBLIC_MAGICSTORE_LOCALE || 'ru';
+
+/**
+ * The server-side client. Public reads are cached under the tags the webhook revalidates; nothing
+ * personal is ever called from here.
+ */
+export const api = createStorefrontClient({
+  baseUrl,
+  locale,
+  fetch: nextCacheFetch({ revalidate: 600 }),
+});
+
+/** Runs a read and turns the API's NOT_FOUND into the page's 404. */
+export async function orNotFound<T>(read: Promise<T>): Promise<T> {
+  try {
+    return await read;
+  } catch (error) {
+    if (error instanceof MagicStoreError && error.code === 'NOT_FOUND') {
+      notFound();
+    }
+    throw error;
+  }
+}