create-magic-storefront 0.1.2 → 0.2.0

package/template/app/blog/page.tsx

@@ -0,0 +1,97 @@
+import type { Metadata } from 'next';
+import Link from 'next/link';
+import { breadcrumbJsonLd, jsonLdScript, pageMeta } from '@magicstoreai/hydrogen/seo';
+import { ArticleGrid } from '@/components/article-card';
+import { ArticleListing, CategoryNav, pageParam, sortParam } from '@/components/blog-listing';
+import { api, locale } from '@/lib/api';
+import { messages } from '@/lib/i18n';
+
+type Props = { searchParams: Promise<{ q?: string; sort?: string; page?: string }> };
+
+export async function generateMetadata({ searchParams }: Props): Promise<Metadata> {
+  const { data: shop } = await api.shop();
+  const { q, sort } = await searchParams;
+  const meta = pageMeta({
+    title: shop.blog?.title || messages(locale).blog,
+    description: shop.blog?.description ?? null,
+    shop,
+  });
+  return {
+    title: meta.title,
+    description: meta.description,
+    // Search results are endless and a sort repeats the same articles: keep both out of the index.
+    ...((q || sort) && { robots: { index: false, follow: true } }),
+  };
+}
+
+/** The blog home: the merchant's heading, categories, editor's picks, then every article. */
+export default async function BlogPage({ searchParams }: Props) {
+  const { q = '', sort: sortValue, page: pageValue } = await searchParams;
+  const sort = sortParam(sortValue);
+  const page = pageParam(pageValue);
+  const t = messages(locale);
+  const { data: shop } = await api.shop();
+  const showFeatured = page === 1 && !q && !sort;
+  const featured = showFeatured
+    ? (await api.blogArticlesIndex({ query: { 'filter[featured]': 'true', perPage: 3 } })).data
+    : [];
+  const href = (p: number) => {
+    const params = new URLSearchParams({
+      ...(q && { q }),
+      ...(sort && { sort }),
+      ...(p > 1 && { page: String(p) }),
+    });
+    return params.size > 0 ? `/blog?${params}` : '/blog';
+  };
+
+  return (
+    <div className="stack">
+      <script
+        type="application/ld+json"
+        dangerouslySetInnerHTML={{
+          __html: jsonLdScript(
+            breadcrumbJsonLd([
+              { name: t.home, url: '/' },
+              { name: shop.blog?.title || t.blog, url: '/blog' },
+            ]),
+          ),
+        }}
+      />
+      <h1>{shop.blog?.title || t.blog}</h1>
+      {shop.blog?.description && <p className="muted">{shop.blog.description}</p>}
+      <CategoryNav />
+      <form className="row" action="/blog">
+        <input name="q" defaultValue={q} placeholder={t.searchArticles} maxLength={200} />
+        <button className="primary">{t.search}</button>
+      </form>
+      <nav className="row chips" aria-label={t.sortNewest}>
+        <Link
+          href={q ? `/blog?q=${encodeURIComponent(q)}` : '/blog'}
+          aria-current={!sort ? 'page' : undefined}
+        >
+          {t.sortNewest}
+        </Link>
+        <Link
+          href={`/blog?${new URLSearchParams({ ...(q && { q }), sort: '-recentViews' })}`}
+          aria-current={sort === '-recentViews' ? 'page' : undefined}
+        >
+          {t.sortPopular}
+        </Link>
+      </nav>
+      {featured.length > 0 && (
+        <section className="stack">
+          <h2>{t.featured}</h2>
+          <ArticleGrid articles={featured} timeZone={shop.timezone} />
+        </section>
+      )}
+      {/* The picks are not repeated below; a blog of only picks shows no second list. */}
+      <ArticleListing
+        query={{ page, ...(q && { q }), ...(sort && { sort }) }}
+        exclude={featured.map((article) => article.id)}
+        {...(featured.length > 0 && { heading: t.allArticles })}
+        href={href}
+        timeZone={shop.timezone}
+      />
+    </div>
+  );
+}

package/template/app/blog/tag/[handle]/page.tsx

@@ -0,0 +1,51 @@
+import type { Metadata } from 'next';
+import { notFound } from 'next/navigation';
+import { ArticleGrid } from '@/components/article-card';
+import { ARTICLES_PER_PAGE, pageParam } from '@/components/blog-listing';
+import { Pager } from '@/components/pager';
+import { api, locale } from '@/lib/api';
+import { messages } from '@/lib/i18n';
+
+type Props = { params: Promise<{ handle: string }>; searchParams: Promise<{ page?: string }> };
+
+/**
+ * Articles with a tag. There is no tag list in the API: the tag's title comes from its articles,
+ * and a tag without any (in this language) is a 404.
+ */
+async function tagged(handle: string, page: number) {
+  const articles = await api.blogArticlesIndex({
+    query: { page, perPage: ARTICLES_PER_PAGE, 'filter[tag]': handle },
+  });
+  if (articles.data.length === 0) {
+    notFound();
+  }
+  const detail = await api.blogArticlesShow({ path: { handle: articles.data[0]!.handle } });
+  const title = detail.data.tags.find((tag) => tag.handle === handle)?.title ?? handle;
+  return { articles, title };
+}
+
+export async function generateMetadata({ params, searchParams }: Props): Promise<Metadata> {
+  const { handle } = await params;
+  const { title } = await tagged(handle, pageParam((await searchParams).page));
+  return { title: `${messages(locale).tag}: ${title}`, robots: { index: false, follow: true } };
+}
+
+export default async function BlogTagPage({ params, searchParams }: Props) {
+  const { handle } = await params;
+  const page = pageParam((await searchParams).page);
+  const [{ articles, title }, { data: shop }] = await Promise.all([
+    tagged(handle, page),
+    api.shop(),
+  ]);
+
+  return (
+    <div className="stack">
+      <h1>#{title}</h1>
+      <ArticleGrid articles={articles.data} timeZone={shop.timezone} />
+      <Pager
+        meta={articles.meta.pagination}
+        href={(p) => `/blog/tag/${handle}${p > 1 ? `?page=${p}` : ''}`}
+      />
+    </div>
+  );
+}

package/template/app/globals.css

@@ -72,6 +72,8 @@ header.site .brand img {
 .card img,
 .card .noimg {
   width: 100%;
+  /* The intrinsic width/height attributes (no layout shift) must not override the ratio. */
+  height: auto;
   aspect-ratio: 1;
   object-fit: cover;
   background: #f3f3f6;
@@ -308,3 +310,69 @@ footer.site nav {
   gap: 16px;
   flex-wrap: wrap;
 }
+.articles {
+  grid-template-columns: repeat(auto-fill, minmax(260px, 1fr));
+}
+.article-card img,
+.article-card .noimg {
+  aspect-ratio: 16 / 9;
+}
+.article-card .badge {
+  align-self: flex-start;
+}
+.chips a {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  min-height: 44px;
+  padding: 0 14px;
+  border: 1px solid var(--line);
+  border-radius: 999px;
+  text-decoration: none;
+}
+.chips a[aria-current='page'] {
+  background: var(--accent);
+  border-color: var(--accent);
+  color: var(--on-accent);
+}
+.article {
+  max-width: 760px;
+  margin: 0 auto;
+}
+.article-cover {
+  width: 100%;
+  height: auto;
+  border-radius: 8px;
+}
+.prose {
+  line-height: 1.65;
+}
+.prose img {
+  max-width: 100%;
+  height: auto;
+}
+.prose table {
+  display: block;
+  overflow-x: auto;
+}
+.article-product {
+  max-width: 260px;
+  margin: 16px 0;
+}
+.callout {
+  margin: 16px 0;
+  padding: 12px 16px;
+  border-left: 4px solid var(--accent);
+  border-radius: 8px;
+  background: #f6f7fb;
+}
+.callout[data-callout='warning'] {
+  border-left-color: var(--danger);
+}
+.author img {
+  border-radius: 50%;
+  object-fit: cover;
+}
+.author h1 {
+  margin: 0;
+}

package/template/app/layout.tsx

@@ -49,6 +49,8 @@ export default async function RootLayout({ children }: { children: ReactNode })
                   {collection.title}
                 </Link>
               ))}
+              {/* Only when an article is readable in this language (`features.blog`). */}
+              {shop.features.blog && <Link href="/blog">{t.blog}</Link>}
               <Link href="/search">{t.search}</Link>
               <Link href="/account">{t.account}</Link>
               <CartLink />

package/template/app/sitemap.ts

@@ -1,7 +1,15 @@
 import type { MetadataRoute } from 'next';
+import type { Schema } from '@magicstoreai/storefront-client';
 import { api } from '@/lib/api';
+import { siteOrigin } from '@/lib/site';
 
-const PATHS = { PAGE: 'pages', COLLECTION: 'collections', PRODUCT: 'products' } as const;
+/** URL prefix per `SitemapEntry.type`; a type added to the API later is skipped, not linked. */
+const PATHS: Partial<Record<string, string>> & Record<Schema<'SitemapEntry'>['type'], string> = {
+  PAGE: 'pages',
+  COLLECTION: 'collections',
+  PRODUCT: 'products',
+  ARTICLE: 'blog',
+};
 /** The sitemap protocol allows 50 000 URLs in one file: 50 pages of `GET /sitemap`. */
 const PER_PAGE = 1000;
 const MAX_PAGES = 50;
@@ -10,21 +18,23 @@ const MAX_PAGES = 50;
 export const dynamic = 'force-dynamic';
 
 /**
- * Every published product, collection and page (`GET /sitemap`, up to 1000 rows a page). URLs are
+ * Every published product, collection, page and blog article (`GET /sitemap`, up to 1000 rows a page). URLs are
  * absolute on `SITE_URL`, else the shop's primary domain.
  */
 export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
   const { data: shop } = await api.shop();
-  const origin =
-    process.env.SITE_URL?.replace(/\/+$/, '') ??
-    `https://${shop.primaryDomain ?? process.env.MAGICSTORE_SHOP_DOMAIN}`;
+  const origin = siteOrigin(shop);
 
   const entries: MetadataRoute.Sitemap = [{ url: `${origin}/` }];
   for (let page = 1; page <= MAX_PAGES; page++) {
     const { data, meta } = await api.sitemap({ query: { page, perPage: PER_PAGE } });
     for (const row of data) {
+      const prefix = PATHS[row.type];
+      if (!prefix) {
+        continue;
+      }
       entries.push({
-        url: `${origin}/${PATHS[row.type]}/${row.handle}`,
+        url: `${origin}/${prefix}/${row.handle}`,
         ...(row.updatedAt && { lastModified: row.updatedAt }),
       });
     }

package/template/components/analytics-views.tsx

@@ -16,3 +16,10 @@ export function SearchView({ query, resultsCount }: { query: string; resultsCoun
   useEffect(() => analytics.search(query, resultsCount), [analytics, query, resultsCount]);
   return null;
 }
+
+/** Reports an article read once per article (`ARTICLE_VIEW`); renders nothing. */
+export function ArticleView({ articleId }: { articleId: string }) {
+  const analytics = useAnalytics();
+  useEffect(() => analytics.articleView(articleId), [analytics, articleId]);
+  return null;
+}

package/template/components/article-body.tsx

@@ -0,0 +1,58 @@
+import { articleBodyBlocks, type ArticleBlock } from '@magicstoreai/hydrogen/core';
+import type { Schema } from '@magicstoreai/storefront-client';
+import { ProductCard } from '@/components/product-grid';
+
+type Product = Schema<'Product'>;
+
+/**
+ * An article body (`bodyHtml`, sanitized by the server) with its inert markup turned into
+ * components: product cards from `products` (a marker whose product the list did not return is
+ * dropped), media embeds as links, callouts as boxes.
+ */
+export function ArticleBody({
+  bodyHtml,
+  products,
+}: {
+  bodyHtml: string;
+  products: ReadonlyMap<string, Product>;
+}) {
+  return <Blocks blocks={articleBodyBlocks(bodyHtml)} products={products} />;
+}
+
+function Blocks({
+  blocks,
+  products,
+}: {
+  blocks: ArticleBlock[];
+  products: ReadonlyMap<string, Product>;
+}) {
+  return blocks.map((block, index) => {
+    switch (block.type) {
+      case 'html':
+        return <div key={index} dangerouslySetInnerHTML={{ __html: block.html }} />;
+      case 'product': {
+        const product = products.get(block.handle);
+        return product ? (
+          <div key={index} className="article-product">
+            <ProductCard product={product} />
+          </div>
+        ) : null;
+      }
+      case 'embed':
+        return (
+          <p key={index}>
+            <a href={block.url} target="_blank" rel="noopener nofollow">
+              {block.url}
+            </a>
+          </p>
+        );
+      case 'callout':
+        return (
+          <aside key={index} className="callout" data-callout={block.kind}>
+            {block.title && <strong>{block.title}</strong>}
+            <Blocks blocks={block.blocks} products={products} />
+          </aside>
+        );
+    }
+  });
+}

package/template/components/article-card.tsx

@@ -0,0 +1,54 @@
+import { Image } from '@magicstoreai/hydrogen';
+import type { Schema } from '@magicstoreai/storefront-client';
+import Link from 'next/link';
+import { locale } from '@/lib/api';
+import { messages } from '@/lib/i18n';
+
+type Article = Schema<'BlogArticle'>;
+
+/** A date in the shop's time zone, so a server elsewhere does not move it by a day. */
+export function ArticleDate({ iso, timeZone }: { iso: string; timeZone: string }) {
+  return <time dateTime={iso}>{formatDate(iso, timeZone)}</time>;
+}
+
+function formatDate(iso: string, timeZone: string): string {
+  try {
+    return new Intl.DateTimeFormat(locale, { dateStyle: 'long', timeZone }).format(new Date(iso));
+  } catch {
+    // A time zone this runtime does not know: the date in UTC beats a failed page.
+    return new Intl.DateTimeFormat(locale, { dateStyle: 'long', timeZone: 'UTC' }).format(
+      new Date(iso),
+    );
+  }
+}
+
+/** One article as a card: cover, category, title, excerpt, author, date and reading time. */
+export function ArticleCard({ article, timeZone }: { article: Article; timeZone: string }) {
+  const t = messages(locale);
+  return (
+    <Link href={`/blog/${article.handle}`} className="card article-card">
+      <Image data={article.image} alt={article.title} fallback={<div className="noimg" />} />
+      {article.category && <span className="badge">{article.category.title}</span>}
+      <strong>{article.title}</strong>
+      {article.excerpt && <span className="muted">{article.excerpt}</span>}
+      <span className="row muted">
+        {article.authorName && <span>{article.authorName}</span>}
+        <ArticleDate iso={article.publishedAt} timeZone={timeZone} />
+        <span>{t.readingTime(article.readingMinutes)}</span>
+      </span>
+    </Link>
+  );
+}
+
+export function ArticleGrid({ articles, timeZone }: { articles: Article[]; timeZone: string }) {
+  if (articles.length === 0) {
+    return <p className="muted">{messages(locale).nothingHere}</p>;
+  }
+  return (
+    <div className="grid articles">
+      {articles.map((article) => (
+        <ArticleCard key={article.id} article={article} timeZone={timeZone} />
+      ))}
+    </div>
+  );
+}

package/template/components/article-vote.tsx

@@ -0,0 +1,43 @@
+'use client';
+
+import { useArticleVote, useMagicStore } from '@magicstoreai/hydrogen';
+import { describe } from '@/lib/errors';
+import { messages } from '@/lib/i18n';
+
+/** «Was this helpful?»: a guest votes as this browser, a signed-in customer as themselves. */
+export function ArticleVote({ handle, helpfulCount }: { handle: string; helpfulCount: number }) {
+  const t = messages(useMagicStore().locale);
+  const vote = useArticleVote(handle, helpfulCount);
+  const choose = (value: 'HELPFUL' | 'NOT_HELPFUL') =>
+    void (vote.viewerVote === value ? vote.clear() : vote.vote(value)).catch(() => undefined);
+
+  return (
+    <section className="stack" aria-live="polite">
+      <strong>{t.wasHelpful}</strong>
+      <div className="row">
+        <button
+          aria-pressed={vote.viewerVote === 'HELPFUL'}
+          disabled={vote.status === 'pending'}
+          onClick={() => choose('HELPFUL')}
+        >
+          {t.helpful}
+        </button>
+        <button
+          aria-pressed={vote.viewerVote === 'NOT_HELPFUL'}
+          disabled={vote.status === 'pending'}
+          onClick={() => choose('NOT_HELPFUL')}
+        >
+          {t.notHelpful}
+        </button>
+        {vote.helpfulCount > 0 && (
+          <span className="muted">{t.helpfulCount(vote.helpfulCount)}</span>
+        )}
+      </div>
+      {vote.error ? (
+        <p className="error">{describe(vote.error, t.tryAgainLater)}</p>
+      ) : (
+        vote.viewerVote !== null && <p className="muted">{t.thanksForVote}</p>
+      )}
+    </section>
+  );
+}

package/template/components/blog-listing.tsx

@@ -0,0 +1,93 @@
+import { MagicStoreError } from '@magicstoreai/storefront-client';
+import Link from 'next/link';
+import { ArticleGrid } from '@/components/article-card';
+import { Pager } from '@/components/pager';
+import { api, locale } from '@/lib/api';
+import { describe } from '@/lib/errors';
+import { messages } from '@/lib/i18n';
+
+export type ArticlesQuery = NonNullable<
+  NonNullable<Parameters<typeof api.blogArticlesIndex>[0]>['query']
+>;
+
+/** 12 a page, the API's default: a blog page reads better short. */
+export const ARTICLES_PER_PAGE = 12;
+
+/**
+ * One page of articles with its pager. A query the API refuses (`422`: an unknown `sort`, a `q`
+ * over 200 characters) shows the API's message instead of failing the page. Articles in
+ * `exclude` (already shown above, e.g. editor's picks) are left out; when that leaves nothing on a
+ * single page, nothing renders — not even `heading`.
+ */
+export async function ArticleListing({
+  query,
+  href,
+  timeZone,
+  exclude = [],
+  heading,
+}: {
+  query: ArticlesQuery;
+  href: (page: number) => string;
+  timeZone: string;
+  exclude?: readonly string[];
+  heading?: string;
+}) {
+  try {
+    const { data, meta } = await api.blogArticlesIndex({
+      query: { perPage: ARTICLES_PER_PAGE, ...query },
+    });
+    const articles = data.filter((article) => !exclude.includes(article.id));
+    if (articles.length === 0 && data.length > 0 && meta.pagination.totalPages <= 1) {
+      return null;
+    }
+    return (
+      <>
+        {heading && <h2>{heading}</h2>}
+        <ArticleGrid articles={articles} timeZone={timeZone} />
+        <Pager meta={meta.pagination} href={href} />
+      </>
+    );
+  } catch (error) {
+    if (error instanceof MagicStoreError && error.code === 'VALIDATION_FAILED') {
+      return <p className="error">{describe(error, messages(locale).tryAgainLater)}</p>;
+    }
+    throw error;
+  }
+}
+
+/** The blog's categories as links; the current one is marked. Nothing when there are none. */
+export async function CategoryNav({ current }: { current?: string }) {
+  const t = messages(locale);
+  const { data: categories } = await api.blogCategoriesIndex();
+  if (categories.length === 0) {
+    return null;
+  }
+  return (
+    <nav className="row chips" aria-label={t.blog}>
+      <Link href="/blog" aria-current={current === undefined ? 'page' : undefined}>
+        {t.allArticles}
+      </Link>
+      {categories.map((category) => (
+        <Link
+          key={category.id}
+          href={`/blog/category/${category.handle}`}
+          aria-current={current === category.handle ? 'page' : undefined}
+        >
+          {category.title} <span className="muted">{category.articlesCount}</span>
+        </Link>
+      ))}
+    </nav>
+  );
+}
+
+const SORTS = ['-publishedAt', 'publishedAt', 'relevance', '-recentViews'] as const;
+
+/** `?sort=` when it is one the API knows; anything else means the default order. */
+export function sortParam(value: string | undefined): ArticlesQuery['sort'] {
+  return SORTS.find((sort) => sort === value);
+}
+
+/** `?page=` as a page number, 1 for anything else. */
+export function pageParam(value: string | undefined): number {
+  return Math.max(1, Number(value) || 1);
+}

package/template/components/pager.tsx

@@ -1,9 +1,15 @@
-import { paginationState, type Pagination } from '@magicstoreai/hydrogen';
+import { paginationState } from '@magicstoreai/hydrogen/core';
+import type { Schema } from '@magicstoreai/storefront-client';
 import Link from 'next/link';
 import { locale } from '@/lib/api';
 import { messages } from '@/lib/i18n';
 
-/** Server-rendered page links (`paginationState` is plain arithmetic, no hooks). */
+type Pagination = Schema<'Pagination'>;
+
+/**
+ * Server-rendered page links. `paginationState` comes from `/core`: the root entry is a client
+ * module, and a server component cannot call its functions.
+ */
 export function Pager({ meta, href }: { meta: Pagination; href: (page: number) => string }) {
   if (meta.totalPages <= 1) {
     return null;

package/template/components/product-grid.tsx

@@ -28,32 +28,39 @@ function ProductBadges({ product }: { product: Schema<'Product'> }) {
   );
 }
 
-export function ProductGrid({ products }: { products: Schema<'Product'>[] }) {
+/** One product as a card: the whole card is one link. */
+export function ProductCard({ product }: { product: Schema<'Product'> }) {
   const t = messages(locale);
+  return (
+    <Link href={`/products/${product.handle}`} className="card">
+      <Image
+        data={product.featuredImage}
+        alt={product.title}
+        fallback={<div className="noimg" />}
+      />
+      <ProductBadges product={product} />
+      <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">{t.soldOut}</span>}
+    </Link>
+  );
+}
+
+export function ProductGrid({ products }: { products: Schema<'Product'>[] }) {
   if (products.length === 0) {
-    return <p className="muted">{t.nothingHere}</p>;
+    return <p className="muted">{messages(locale).nothingHere}</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" />}
-          />
-          <ProductBadges product={product} />
-          <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">{t.soldOut}</span>}
-        </Link>
+        <ProductCard key={product.id} product={product} />
       ))}
     </div>
   );

package/template/lib/errors.ts

@@ -1,4 +1,5 @@
-import { MagicStoreError } from '@magicstoreai/hydrogen';
+// From the client package, not the "use client" hydrogen entry: this runs in server components too.
+import { MagicStoreError } from '@magicstoreai/storefront-client';
 
 /** What to tell the buyer: the API's localized detail when there is one. */
 export function describe(error: unknown, fallback: string): string {