create-nymbal-app 0.3.0 → 0.5.0

package/scaffold/templates/nextjs/app/(catalog)/product/[slug]/page.tsx

@@ -0,0 +1,182 @@
+import type { Metadata } from 'next'
+import { notFound } from 'next/navigation'
+import { preload } from 'react-dom'
+import { fetchProduct, fetchProducts, fetchReviews } from '@/lib/api'
+import { cardProductOf, renderNymbal } from '@/lib/render'
+import { productJsonLd } from '@/lib/seo'
+import {
+  Breadcrumb,
+  ImageGallery,
+  ProductGrid,
+  ReviewForm,
+  ReviewList,
+} from '@/components/client/elements'
+import { ProductInteractive } from '@/components/client/ProductInteractive'
+import styles from '@/styles/pages/pdp.module.css'
+
+// Next caches each product page on its first request and regenerates it in the background every 60 s; the build
+// prerenders none, since the API may be down then.
+export const revalidate = 60
+
+export function generateStaticParams(): Array<{ slug: string }> {
+  return []
+}
+
+interface ProductPageProps {
+  params: Promise<{ slug: string }>
+}
+
+export async function generateMetadata({ params }: ProductPageProps): Promise<Metadata> {
+  const { slug } = await params
+  const product = await fetchProduct(slug, revalidate)
+
+  if (!product) {
+    return { title: 'Product Not Found' }
+  }
+
+  return {
+    title: product.name,
+    description: product.shortDescription ?? product.description ?? `Buy ${product.name}.`,
+  }
+}
+
+export default async function ProductPage({ params }: ProductPageProps) {
+  const { slug } = await params
+  const product = await fetchProduct(slug, revalidate)
+
+  if (!product) notFound()
+
+  const [{ items: reviews }, { items: relatedProducts }] = await Promise.all([
+    fetchReviews(product.id),
+    fetchProducts({ limit: 4 }),
+  ])
+
+  const related = relatedProducts
+    .filter((p) => p.id !== product.id)
+    .slice(0, 4)
+    .map(cardProductOf)
+
+  // The product's elements as the server renders them for its first variant, which ProductInteractive shows first.
+  const variant = product.variants?.[0]
+  const serverHtml = {
+    price: renderNymbal('nymbal-product-price', {
+      'product-id': product.id,
+      'price-minor': String(variant?.priceMinor ?? product.priceMinor ?? 0),
+      currency: product.currency ?? 'GBP',
+    }).__html,
+    stock: renderNymbal('nymbal-stock-badge', {
+      'product-id': product.id,
+      stock: String(variant?.stock ?? 0),
+    }).__html,
+    variantSelector: renderNymbal('nymbal-variant-selector', { product: JSON.stringify(product) })
+      .__html,
+    quantity: renderNymbal('nymbal-quantity-selector', { value: '1', min: '1', max: '99' }).__html,
+    addToCart: renderNymbal('nymbal-add-to-cart', {
+      'variant-id': variant?.id ?? product.id,
+      qty: '1',
+      ...((variant?.stock ?? 0) <= 0 && { disabled: '' }),
+    }).__html,
+  }
+
+  const baseUrl = process.env.NEXT_PUBLIC_SITE_URL ?? 'http://localhost:3000'
+  const jsonLd = productJsonLd(product, baseUrl)
+
+  const mediaArray = Array.isArray(product.media) ? product.media : []
+  const images =
+    mediaArray.length > 0
+      ? mediaArray.map((m: Record<string, string>) => ({
+          url: m.url,
+          alt: m.alt ?? product.name,
+        }))
+      : [{ url: `https://picsum.photos/seed/${product.slug}/600/600`, alt: product.name }]
+  const crumbs = [
+    { label: 'Home', href: '/' },
+    { label: 'Products', href: '/products' },
+    { label: product.name },
+  ]
+
+  // The gallery's main image is the page's LCP: a preload in the head starts it before the browser parses the body.
+  // React's preload(), not a <link> element: a cached render writes an element and its preload both.
+  preload(images[0]!.url, { as: 'image', fetchPriority: 'high' })
+
+  return (
+    <>
+      <script
+        type="application/ld+json"
+        dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }}
+      />
+
+      <div className={`container ${styles.page}`}>
+        <Breadcrumb
+          items={crumbs}
+          serverHtml={renderNymbal('nymbal-breadcrumb', { items: JSON.stringify(crumbs) }).__html}
+        />
+
+        <div className={styles.productLayout}>
+          <ImageGallery
+            className={styles.gallery}
+            images={images}
+            serverHtml={
+              renderNymbal('nymbal-image-gallery', { images: JSON.stringify(images) }).__html
+            }
+          />
+
+          <div className={styles.info}>
+            <ProductInteractive product={product} serverHtml={serverHtml} />
+
+            {product.description && (
+              <div className={styles.description}>
+                <p>{product.description}</p>
+              </div>
+            )}
+
+            <div className={styles.detailsSection}>
+              <details className={styles.detailsItem}>
+                <summary className={styles.detailsSummary}>Details</summary>
+                <div className={styles.detailsContent}>
+                  {product.description ?? 'No additional details available.'}
+                </div>
+              </details>
+              <details className={styles.detailsItem}>
+                <summary className={styles.detailsSummary}>Shipping & Returns</summary>
+                <div className={styles.detailsContent}>
+                  Free standard shipping on orders over $50. Returns accepted within 30 days of
+                  purchase.
+                </div>
+              </details>
+            </div>
+          </div>
+        </div>
+
+        <section className={styles.reviewsSection}>
+          <h2 className={styles.reviewsTitle}>Customer Reviews</h2>
+          <ReviewList
+            reviews={reviews}
+            serverHtml={
+              renderNymbal('nymbal-review-list', { reviews: JSON.stringify(reviews) }).__html
+            }
+          />
+          <ReviewForm
+            className={styles.reviewForm}
+            productId={product.id}
+            serverHtml={renderNymbal('nymbal-review-form', { 'product-id': product.id }).__html}
+          />
+        </section>
+
+        {related.length > 0 && (
+          <section className="section">
+            <h2 className="section-title">You may also like</h2>
+            <ProductGrid
+              products={related}
+              lazy
+              serverHtml={
+                renderNymbal('nymbal-product-grid', { products: JSON.stringify(related), lazy: '' })
+                  .__html
+              }
+            />
+          </section>
+        )}
+      </div>
+    </>
+  )
+}

package/scaffold/templates/nextjs/app/(catalog)/products/page.tsx

@@ -0,0 +1,62 @@
+import type { Metadata } from 'next'
+import { fetchProducts, fetchCapabilities, sortFromSearchParams } from '@/lib/api'
+import { cardImageOf, cardProductOf, renderNymbal } from '@/lib/render'
+import { Breadcrumb, ProductGrid } from '@/components/client/elements'
+import { ListingControls } from '@/components/client/ListingControls'
+import styles from '@/styles/pages/plp.module.css'
+
+export const metadata: Metadata = {
+  title: 'All Products',
+  description: 'Browse our full collection of products.',
+}
+
+// The page reads `?sort=`, so it renders per request; said here, the build does not render it with the API down. Its
+// catalog reads still go through Next's data cache.
+export const dynamic = 'force-dynamic'
+
+interface ProductsPageProps {
+  searchParams: Promise<{ sort?: string | string[] }>
+}
+
+const CRUMBS = [{ label: 'Home', href: '/' }, { label: 'Products' }]
+
+export default async function ProductsPage({ searchParams }: ProductsPageProps) {
+  const capabilities = await fetchCapabilities()
+  const sort = sortFromSearchParams(await searchParams, capabilities?.catalog)
+  const { items, nextCursor, facets } = await fetchProducts({ limit: 24, sort })
+  const cards = items.map(cardProductOf)
+  // The first card's image is the page's LCP, and the preload scanner never reaches it inside the grid's shadow root:
+  // a preload link, which React hoists into the head, starts it.
+  const firstImage = cards[0] === undefined ? null : cardImageOf(cards[0]).url
+  const grid = {
+    products: JSON.stringify(cards),
+    source: 'product-list',
+    ...(nextCursor !== null && { 'has-more': '' }),
+  }
+
+  return (
+    <div className={`container ${styles.page}`}>
+      {firstImage !== null && (
+        <link rel="preload" as="image" href={firstImage} fetchPriority="high" />
+      )}
+      <Breadcrumb
+        items={CRUMBS}
+        serverHtml={renderNymbal('nymbal-breadcrumb', { items: JSON.stringify(CRUMBS) }).__html}
+      />
+      <h1 className={styles.pageTitle}>All Products</h1>
+      <ListingControls
+        sort={sort}
+        facets={facets ?? []}
+        sortKeys={capabilities?.catalog.sortKeys ?? []}
+        defaultSort={capabilities?.catalog.defaultSort}
+      >
+        <ProductGrid
+          products={cards}
+          source="product-list"
+          hasMore={nextCursor !== null}
+          serverHtml={renderNymbal('nymbal-product-grid', grid).__html}
+        />
+      </ListingControls>
+    </div>
+  )
+}

package/scaffold/templates/nextjs/app/(catalog)/search/SearchView.tsx

@@ -0,0 +1,90 @@
+'use client'
+
+import { useCallback, useEffect } from 'react'
+import { useSearchParams } from 'next/navigation'
+import Link from 'next/link'
+import type { DenormalisedProduct } from '@nymbalhq/sdk'
+import { ProductFilter, SearchResults, useSearch } from '@nymbalhq/react'
+import styles from '@/styles/pages/search.module.css'
+
+const POPULAR = ['Shirts', 'Shoes', 'Jackets', 'Accessories', 'New Arrivals']
+
+/**
+ * The URL owns the term and the category; `SearchResults` renders the store's answer, and until the store has one, the
+ * results the server fetched for the URL (`given`, rendered in `serverHtml`).
+ */
+export function SearchView({
+  given,
+  serverHtml,
+}: {
+  given: { results: DenormalisedProduct[]; query: string } | null
+  serverHtml: string
+}) {
+  const searchParams = useSearchParams()
+  const query = searchParams.get('q') ?? ''
+  const category = searchParams.get('category')
+  const {
+    results,
+    facets,
+    query: searched,
+    category: searchedCategory,
+    search,
+    clearSearch,
+  } = useSearch()
+
+  useEffect(() => {
+    // Runs when the URL changes; the filter has already searched the category it writes there. The store outlives
+    // the page on a client-side navigation, so a URL with no term clears what an earlier visit searched.
+    if (!query) {
+      if (searched) clearSearch()
+    } else if (query !== searched || category !== searchedCategory) {
+      void search(query, { category })
+    }
+  }, [query, category, search, clearSearch])
+
+  const onFilterChange = useCallback((event: CustomEvent<{ name: string; value: string }>) => {
+    const url = new URL(window.location.href)
+    if (event.detail.value) url.searchParams.set('category', event.detail.value)
+    else url.searchParams.delete('category')
+    window.history.replaceState(null, '', url.toString())
+  }, [])
+
+  const filtered = facets.length > 0 && results.length > 0
+
+  return (
+    <div className={`container ${styles.page}`}>
+      <div className={styles.header}>
+        <h1 className={styles.pageTitle}>Search Results</h1>
+      </div>
+
+      <div className={filtered ? styles.layout : undefined}>
+        {filtered && (
+          <aside className={styles.sidebar}>
+            <ProductFilter source="search" onFilterChange={onFilterChange} />
+          </aside>
+        )}
+        <SearchResults
+          data-testid="search-results"
+          results={given?.results}
+          query={given?.query}
+          serverHtml={serverHtml}
+        />
+      </div>
+
+      <div className={styles.suggestions}>
+        <h3 className={styles.suggestionsTitle}>Popular searches</h3>
+        <div className={styles.suggestionTags}>
+          {POPULAR.map((term) => (
+            <Link
+              key={term}
+              href={`/search?q=${encodeURIComponent(term)}`}
+              className={styles.suggestionTag}
+            >
+              {term}
+            </Link>
+          ))}
+        </div>
+      </div>
+    </div>
+  )
+}

package/scaffold/templates/nextjs/app/(catalog)/search/page.tsx

@@ -0,0 +1,46 @@
+import type { Metadata } from 'next'
+import { Suspense } from 'react'
+import { fetchSearch } from '@/lib/api'
+import { renderNymbal } from '@/lib/render'
+import { SearchView } from './SearchView'
+
+export const metadata: Metadata = {
+  title: 'Search',
+  description: 'Search our product catalog.',
+}
+
+// The page reads `?q=`, so it renders per request; said here, the build does not render it with the API down. The
+// header's catalog reads still go through Next's data cache.
+export const dynamic = 'force-dynamic'
+
+const first = (value: string | string[] | undefined): string | null =>
+  (Array.isArray(value) ? value[0] : value) ?? null
+
+export default async function SearchPage({
+  searchParams,
+}: {
+  searchParams: Promise<Record<string, string | string[] | undefined>>
+}) {
+  const params = await searchParams
+  const q = first(params['q'])?.trim() ?? ''
+  const search = q === '' ? null : await fetchSearch(q, first(params['category']))
+  // The results the page's search would show, so they are in the HTML; the search store takes over once it answers.
+  const given = search === null ? null : { results: search.items, query: q }
+  const serverHtml = renderNymbal(
+    'nymbal-search-results',
+    given === null ? {} : { results: JSON.stringify(given.results), query: given.query },
+  ).__html
+  return (
+    <Suspense
+      fallback={
+        <div className="loading-center">
+          <div className="spinner spinner-lg" role="status">
+            <span className="visually-hidden">Loading...</span>
+          </div>
+        </div>
+      }
+    >
+      <SearchView given={given} serverHtml={serverHtml} />
+    </Suspense>
+  )
+}

package/scaffold/templates/nextjs/app/(shopper)/account/addresses/AddressesView.tsx

@@ -0,0 +1,5 @@
+'use client'
+
+import { AddressBook } from '@nymbalhq/react'
+
+export default AddressBook

package/scaffold/templates/nextjs/app/(shopper)/account/addresses/page.tsx

@@ -0,0 +1,17 @@
+import type { Metadata } from 'next'
+import { renderNymbal } from '@/lib/render'
+import AddressBook from './AddressesView'
+import styles from '@/styles/pages/account.module.css'
+
+export const metadata: Metadata = {
+  title: 'Addresses',
+}
+
+export default function AddressesPage() {
+  return (
+    <div>
+      <h2 className={styles.pageTitle}>Addresses</h2>
+      <AddressBook serverHtml={renderNymbal('nymbal-address-book').__html} />
+    </div>
+  )
+}

package/scaffold/templates/nextjs/app/(shopper)/account/login/LoginView.tsx

@@ -0,0 +1,28 @@
+'use client'
+
+import { useCallback } from 'react'
+import { useRouter } from 'next/navigation'
+import Link from 'next/link'
+import { LoginForm } from '@nymbalhq/react'
+import styles from '@/styles/pages/account.module.css'
+
+/** `serverHtml` is the form as the server rendered it, `redirect` where to go once signed in (page.tsx). */
+export function LoginView({ serverHtml, redirect }: { serverHtml: string; redirect?: string }) {
+  const router = useRouter()
+  const onSignedIn = useCallback(() => {
+    router.push(redirect ?? '/account')
+  }, [router, redirect])
+
+  return (
+    <div className={styles.authPage}>
+      <div className={styles.authCard}>
+        <h1 className={styles.authTitle}>Sign In</h1>
+        <p className={styles.authSubtitle}>Welcome back. Enter your credentials to continue.</p>
+        <LoginForm onSignedIn={onSignedIn} serverHtml={serverHtml} />
+        <p className={styles.authFooter}>
+          Don&apos;t have an account? <Link href="/account/register">Create one</Link>
+        </p>
+      </div>
+    </div>
+  )
+}

package/scaffold/templates/nextjs/app/(shopper)/account/login/page.tsx

@@ -0,0 +1,23 @@
+import type { Metadata } from 'next'
+import { renderNymbal } from '@/lib/render'
+import { LoginView } from './LoginView'
+
+export const metadata: Metadata = {
+  title: 'Sign In',
+}
+
+interface LoginPageProps {
+  searchParams: Promise<{ redirect?: string | string[] }>
+}
+
+// The page reads `redirect` itself rather than the view reading the URL: a view that reads it needs a Suspense
+// boundary, which React may stream after the shell, and without JavaScript a streamed boundary is never shown.
+export default async function LoginPage({ searchParams }: LoginPageProps) {
+  const { redirect } = await searchParams
+  return (
+    <LoginView
+      redirect={typeof redirect === 'string' ? redirect : undefined}
+      serverHtml={renderNymbal('nymbal-login-form').__html}
+    />
+  )
+}

package/scaffold/templates/nextjs/app/(shopper)/account/profile/ProfileView.tsx

@@ -0,0 +1,5 @@
+'use client'
+
+import { ProfileForm } from '@nymbalhq/react'
+
+export default ProfileForm

package/scaffold/templates/nextjs/app/(shopper)/account/profile/page.tsx

@@ -0,0 +1,20 @@
+import type { Metadata } from 'next'
+import { renderNymbal } from '@/lib/render'
+import ProfileForm from './ProfileView'
+import styles from '@/styles/pages/account.module.css'
+
+export const metadata: Metadata = {
+  title: 'Profile',
+}
+
+export default function ProfilePage() {
+  return (
+    <div>
+      <h2 className={styles.pageTitle}>Profile</h2>
+      <div className={styles.formCard}>
+        <h3 className={styles.formCardTitle}>Personal Information</h3>
+        <ProfileForm serverHtml={renderNymbal('nymbal-profile-form').__html} />
+      </div>
+    </div>
+  )
+}

package/scaffold/templates/nextjs/app/(shopper)/account/register/RegisterView.tsx

@@ -0,0 +1,26 @@
+'use client'
+
+import { useCallback } from 'react'
+import { useRouter } from 'next/navigation'
+import Link from 'next/link'
+import { RegisterForm } from '@nymbalhq/react'
+import styles from '@/styles/pages/account.module.css'
+
+/** `serverHtml` is the form as the server rendered it (page.tsx). */
+export function RegisterView({ serverHtml }: { serverHtml: string }) {
+  const router = useRouter()
+  const onSignedIn = useCallback(() => router.push('/account'), [router])
+
+  return (
+    <div className={styles.authPage}>
+      <div className={styles.authCard}>
+        <h1 className={styles.authTitle}>Create Account</h1>
+        <p className={styles.authSubtitle}>Join us and start shopping.</p>
+        <RegisterForm onSignedIn={onSignedIn} serverHtml={serverHtml} />
+        <p className={styles.authFooter}>
+          Already have an account? <Link href="/account/login">Sign in</Link>
+        </p>
+      </div>
+    </div>
+  )
+}

package/scaffold/templates/nextjs/app/(shopper)/account/register/page.tsx

@@ -0,0 +1,11 @@
+import type { Metadata } from 'next'
+import { renderNymbal } from '@/lib/render'
+import { RegisterView } from './RegisterView'
+
+export const metadata: Metadata = {
+  title: 'Create Account',
+}
+
+export default function RegisterPage() {
+  return <RegisterView serverHtml={renderNymbal('nymbal-register-form').__html} />
+}

package/scaffold/templates/nextjs/app/(shopper)/cart/CartView.tsx

@@ -0,0 +1,5 @@
+'use client'
+
+import { CartPage } from '@nymbalhq/react'
+
+export default CartPage

package/scaffold/templates/nextjs/app/(shopper)/cart/page.tsx

@@ -0,0 +1,22 @@
+import type { Metadata } from 'next'
+import { headers } from 'next/headers'
+import { fetchCart } from '@/lib/api'
+import { renderNymbal } from '@/lib/render'
+import CartPage from './CartView'
+
+export const metadata: Metadata = {
+  title: 'Shopping Cart',
+}
+
+export default async function CartRoute() {
+  const cart = await fetchCart((await headers()).get('cookie'))
+  const serverHtml = renderNymbal(
+    'nymbal-cart-page',
+    cart === null ? {} : { cart: JSON.stringify(cart) },
+  ).__html
+  return (
+    <div className="container section" data-testid="cart-page">
+      <CartPage cart={cart ?? undefined} serverHtml={serverHtml} />
+    </div>
+  )
+}

package/scaffold/templates/nextjs/app/(shopper)/checkout/CheckoutView.tsx

@@ -0,0 +1,27 @@
+'use client'
+
+import { useCallback, useEffect } from 'react'
+import { useRouter } from 'next/navigation'
+import { Checkout } from '@nymbalhq/react'
+import { NymbalPaymentElement } from '@nymbalhq/web-components/elements/nymbal-payment-element'
+import type { CartProjection } from '@/lib/api'
+
+/**
+ * The element places the order; the page only goes to it. The server rendered the checkout with its payment element
+ * as a light-DOM child (`serverHtml`), which is defined here: it stays mounted by its driver in the browser.
+ */
+export function CheckoutView({ cart, serverHtml }: { cart: CartProjection | null; serverHtml: string }) {
+  const router = useRouter()
+  const onPlaced = useCallback(
+    (event: CustomEvent<{ orderNumber: string }>) => {
+      router.push(`/order/${encodeURIComponent(event.detail.orderNumber)}`)
+    },
+    [router],
+  )
+
+  useEffect(() => {
+    NymbalPaymentElement.define()
+  }, [])
+
+  return <Checkout cart={cart ?? undefined} serverHtml={serverHtml} onPlaced={onPlaced} />
+}

package/scaffold/templates/nextjs/app/(shopper)/checkout/page.tsx

@@ -0,0 +1,39 @@
+import type { Metadata } from 'next'
+import { headers } from 'next/headers'
+import { fetchCapabilities, fetchCart } from '@/lib/api'
+import { renderNymbal } from '@/lib/render'
+import { CheckoutView } from './CheckoutView'
+
+export const metadata: Metadata = {
+  title: 'Checkout',
+}
+
+const escapeAttribute = (value: string): string =>
+  value.replaceAll('&', '&amp;').replaceAll('"', '&quot;').replaceAll('<', '&lt;')
+
+export default async function CheckoutRoute() {
+  const [capabilities, cart] = await Promise.all([
+    fetchCapabilities(),
+    headers().then((h) => fetchCart(h.get('cookie'))),
+  ])
+  if (capabilities === null) {
+    throw new Error(
+      'The store did not answer GET /api/capabilities, so checkout cannot tell how to take a payment.',
+    )
+  }
+  // The payments adapter's client half, as the checkout's light-DOM child in its payment slot; a driver the project
+  // registers in lib/client.ts renders it.
+  const payment = `<nymbal-payment-element slot="payment" client="${escapeAttribute(
+    JSON.stringify(capabilities.payments.client),
+  )}" data-testid="payment-element"></nymbal-payment-element>`
+  const serverHtml = renderNymbal(
+    'nymbal-checkout',
+    cart === null ? {} : { cart: JSON.stringify(cart) },
+    payment,
+  ).__html
+  return (
+    <div className="container section">
+      <CheckoutView cart={cart} serverHtml={serverHtml} />
+    </div>
+  )
+}

package/scaffold/templates/nextjs/app/(shopper)/layout.tsx

@@ -0,0 +1,12 @@
+import type { ReactNode } from 'react'
+import { Header } from '@/components/server/Header'
+
+// The shopper's own pages render per request: the header reads the cart cookie, so its count is in the HTML.
+export default function ShopperLayout({ children }: { children: ReactNode }) {
+  return (
+    <>
+      <Header shopper />
+      <main id="main">{children}</main>
+    </>
+  )
+}