create-nymbal-app 0.4.0 → 0.5.0

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>
+    </>
+  )
+}

package/scaffold/templates/nextjs/app/{order → (shopper)/order}/[orderNumber]/page.tsx

@@ -2,7 +2,8 @@ import type { Metadata } from 'next'
 import { notFound } from 'next/navigation'
 import Link from 'next/link'
 import { fetchOrder } from '@/lib/api'
-import { OrderSummary } from '@/components/server/OrderSummary'
+import { OrderSummary } from '@/components/client/elements'
+import { renderNymbal } from '@/lib/render'
 import { OrderStatusRefresh } from '@/components/client/OrderStatusRefresh'
 import { isPaid, orderHeading } from '@/lib/order-status'
 import styles from '@/styles/pages/confirmation.module.css'
@@ -59,6 +60,21 @@ export default async function OrderPage({ params }: OrderPageProps) {
 
   if (!order) notFound()
   const paid = isPaid(order.status)
+  const items = order.lineItems.map((item) => ({
+    name: `${item.productName}${item.variantName ? ` - ${item.variantName}` : ''}`,
+    qty: item.qty,
+    unitPriceMinor: item.unitPriceMinor,
+    lineTotalMinor: item.lineTotalMinor,
+  }))
+  const summary = {
+    items: JSON.stringify(items),
+    'subtotal-minor': String(order.subtotalMinor),
+    'discount-minor': String(order.discountTotalMinor ?? 0),
+    'shipping-minor': String(order.shippingTotalMinor ?? 0),
+    'tax-minor': String(order.taxTotalMinor ?? 0),
+    'total-minor': String(order.totalMinor),
+    currency: order.currency,
+  }
 
   return (
     <div className={`container ${styles.page}`}>
@@ -97,12 +113,15 @@ export default async function OrderPage({ params }: OrderPageProps) {
         </div>
 
         <OrderSummary
-          items={order.lineItems}
+          className={styles.summary}
+          items={items}
           subtotalMinor={order.subtotalMinor}
-          currency={order.currency}
-          shippingTotalMinor={order.shippingTotalMinor}
-          taxTotalMinor={order.taxTotalMinor}
+          discountMinor={order.discountTotalMinor ?? 0}
+          shippingMinor={order.shippingTotalMinor ?? 0}
+          taxMinor={order.taxTotalMinor ?? 0}
           totalMinor={order.totalMinor}
+          currency={order.currency}
+          serverHtml={renderNymbal('nymbal-order-summary', summary).__html}
         />
 
         <div className={styles.orderCard}>

package/scaffold/templates/nextjs/app/error.tsx

@@ -10,7 +10,7 @@ interface ErrorProps {
 
 export default function ErrorPage({ error: _error, reset }: ErrorProps) {
   return (
-    <div className={styles.page}>
+    <main id="main" className={styles.page}>
       <div className={styles.wrapper}>
         <div className={styles.icon}>
           <svg
@@ -35,15 +35,11 @@ export default function ErrorPage({ error: _error, reset }: ErrorProps) {
           <Link href="/" className={styles.homeLink}>
             Go Home
           </Link>
-          <button
-            type="button"
-            className={styles.retryButton}
-            onClick={reset}
-          >
+          <button type="button" className={styles.retryButton} onClick={reset}>
             Try Again
           </button>
         </div>
       </div>
-    </div>
+    </main>
   )
 }

package/scaffold/templates/nextjs/app/fragments/footer/route.ts

@@ -0,0 +1,13 @@
+import { FOOTER_COLUMNS } from '@/lib/chrome'
+import { fragment } from '@/lib/fragments'
+import { renderElement } from '@/lib/render'
+
+export const revalidate = 86400
+
+export function GET(): Response {
+  return fragment(
+    renderElement('nymbal-site-footer', {
+      attributes: { columns: JSON.stringify(FOOTER_COLUMNS) },
+    }),
+  )
+}

package/scaffold/templates/nextjs/app/fragments/header/[key]/route.ts

@@ -0,0 +1,18 @@
+import { fragment, noFragment } from '@/lib/fragments'
+import { canSearch, siteHeader } from '@/lib/header'
+import { renderElement } from '@/lib/render'
+
+export const revalidate = 3600
+// A dynamic segment, so the build prerenders nothing when the API may be down; next.config.mjs rewrites
+// `/fragments/<name>` to `/fragments/<name>/index`.
+export function generateStaticParams(): Array<{ key: string }> {
+  return []
+}
+
+export async function GET(
+  _request: Request,
+  { params }: { params: Promise<{ key: string }> },
+): Promise<Response> {
+  if ((await params).key !== 'index') return noFragment()
+  return fragment(renderElement('nymbal-site-header', siteHeader(await canSearch())))
+}

package/scaffold/templates/nextjs/app/fragments/nav/[key]/route.ts

@@ -0,0 +1,23 @@
+import { fetchCategories } from '@/lib/api'
+import { fragment, noFragment } from '@/lib/fragments'
+import { renderElement } from '@/lib/render'
+
+export const revalidate = 21600
+// A dynamic segment, so the build prerenders nothing when the API may be down; next.config.mjs rewrites
+// `/fragments/<name>` to `/fragments/<name>/index`.
+export function generateStaticParams(): Array<{ key: string }> {
+  return []
+}
+
+export async function GET(
+  _request: Request,
+  { params }: { params: Promise<{ key: string }> },
+): Promise<Response> {
+  if ((await params).key !== 'index') return noFragment()
+  const categories = await fetchCategories()
+  return fragment(
+    renderElement('nymbal-category-nav', {
+      attributes: { categories: JSON.stringify(categories) },
+    }),
+  )
+}

package/scaffold/templates/nextjs/app/fragments/product/[slug]/route.ts

@@ -0,0 +1,22 @@
+import { fetchProduct } from '@/lib/api'
+import { fragment, noFragment } from '@/lib/fragments'
+import { cardProductOf, renderElement } from '@/lib/render'
+
+export const revalidate = 300
+// The build prerenders no product, since the API may be down then.
+export function generateStaticParams(): Array<{ slug: string }> {
+  return []
+}
+
+export async function GET(
+  _request: Request,
+  { params }: { params: Promise<{ slug: string }> },
+): Promise<Response> {
+  const product = await fetchProduct((await params).slug)
+  if (product === null) return noFragment()
+  return fragment(
+    renderElement('nymbal-product-card', {
+      attributes: { product: JSON.stringify(cardProductOf(product)) },
+    }),
+  )
+}

package/scaffold/templates/nextjs/app/globals.css

@@ -1,4 +1,4 @@
-@import '@nymbalhq/web-components/tokens.css';
+@import './tokens.css';
 
 /* ── CSS Reset ─────────────────────────────────────────────────────── */
 
@@ -169,7 +169,8 @@ a:focus-visible {
   border: 1px solid transparent;
   border-radius: var(--nymbal-radius-md);
   cursor: pointer;
-  transition: background-color var(--nymbal-transition-fast),
+  transition:
+    background-color var(--nymbal-transition-fast),
     color var(--nymbal-transition-fast),
     border-color var(--nymbal-transition-fast),
     box-shadow var(--nymbal-transition-fast);
@@ -243,7 +244,8 @@ select {
   background-color: var(--nymbal-color-surface);
   border: 1px solid var(--nymbal-color-border);
   border-radius: var(--nymbal-radius-md);
-  transition: border-color var(--nymbal-transition-fast),
+  transition:
+    border-color var(--nymbal-transition-fast),
     box-shadow var(--nymbal-transition-fast);
   appearance: none;
 }
@@ -281,26 +283,6 @@ label {
   margin-top: var(--nymbal-spacing-xs);
 }
 
-/* ── Product Grid ──────────────────────────────────────────────────── */
-
-.product-grid {
-  display: grid;
-  grid-template-columns: 1fr;
-  gap: var(--nymbal-spacing-lg);
-}
-
-@media (min-width: 640px) {
-  .product-grid {
-    grid-template-columns: repeat(2, 1fr);
-  }
-}
-
-@media (min-width: 1024px) {
-  .product-grid {
-    grid-template-columns: repeat(4, 1fr);
-  }
-}
-
 /* ── Link Styles ───────────────────────────────────────────────────── */
 
 .link-muted {

package/scaffold/templates/nextjs/app/layout.tsx

@@ -2,25 +2,28 @@ import type { ReactNode } from 'react'
 import type { Metadata } from 'next'
 import './globals.css'
 import { NymbalSetup } from '@/components/client/NymbalSetup'
-import { Header } from '@/components/server/Header'
-import { Footer } from '@/components/server/Footer'
+import { SiteFooter } from '@/components/client/elements'
 import { SkipNav } from '@/components/server/SkipNav'
 import { CartDrawerToggle } from '@/components/client/CartDrawerToggle'
+import { FOOTER_COLUMNS } from '@/lib/chrome'
+import { renderNymbal } from '@/lib/render'
 
 export const metadata: Metadata = {
   title: { default: 'Nymbal Store', template: '%s | Nymbal' },
   description: 'Shop the Nymbal store',
 }
 
+// The root layout makes no API call: Next renders the 404 under it at build, when the API may be down. Each route
+// group's layout brings the header the group's pages share, (catalog)'s cached for every shopper, (shopper)'s per request.
 export default function RootLayout({ children }: { children: ReactNode }) {
+  const footer = renderNymbal('nymbal-site-footer', { columns: JSON.stringify(FOOTER_COLUMNS) })
   return (
     <html lang="en">
       <body>
         <NymbalSetup>
           <SkipNav />
-          <Header />
-          <main id="main">{children}</main>
-          <Footer />
+          {children}
+          <SiteFooter columns={FOOTER_COLUMNS} serverHtml={footer.__html} />
           <CartDrawerToggle />
         </NymbalSetup>
       </body>

package/scaffold/templates/nextjs/app/not-found.tsx

@@ -1,38 +1,14 @@
-import Link from 'next/link'
-import styles from '@/styles/pages/error.module.css'
+import { PlainHeader } from '@/components/server/Header'
+import { NotFoundView } from '@/components/server/NotFoundView'
 
+// A URL no route matches, and a shopper page with nothing to show.
 export default function NotFound() {
   return (
-    <div className={styles.page}>
-      <div className={styles.wrapper}>
-        <div className={`${styles.icon} ${styles.notFoundIcon}`}>
-          <svg
-            viewBox="0 0 24 24"
-            fill="none"
-            stroke="currentColor"
-            strokeWidth="2"
-            strokeLinecap="round"
-            strokeLinejoin="round"
-            aria-hidden="true"
-          >
-            <circle cx="11" cy="11" r="8" />
-            <line x1="21" y1="21" x2="16.65" y2="16.65" />
-          </svg>
-        </div>
-        <p className={styles.statusCode}>404</p>
-        <h1 className={styles.title}>Page Not Found</h1>
-        <p className={styles.message}>
-          The page you are looking for does not exist or may have been moved.
-        </p>
-        <div className={styles.actions}>
-          <Link href="/" className={styles.homeLink}>
-            Go Home
-          </Link>
-          <Link href="/products" className={styles.retryButton}>
-            Browse Products
-          </Link>
-        </div>
-      </div>
-    </div>
+    <>
+      <PlainHeader />
+      <main id="main">
+        <NotFoundView />
+      </main>
+    </>
   )
 }

package/scaffold/templates/nextjs/app/tokens.css

@@ -0,0 +1,56 @@
+/* ----------------------------------------------------------------
+   Design tokens: this store's file, edit it to restyle.
+   Every Nymbal element reads its look from these custom properties,
+   which cross into its shadow root. An element's `part`s can be
+   styled further with ::part(), e.g. nymbal-add-to-cart::part(button).
+   Defaults: @nymbalhq/web-components/tokens.css.
+   ---------------------------------------------------------------- */
+
+:root {
+  --nymbal-color-primary: #18181b;
+  --nymbal-color-primary-hover: #27272a;
+  --nymbal-color-accent: #2563eb;
+  --nymbal-color-accent-hover: #1d4ed8;
+  --nymbal-color-success: #16a34a;
+  --nymbal-color-error: #dc2626;
+  --nymbal-color-warning: #d97706;
+  --nymbal-color-text: #18181b;
+  --nymbal-color-text-muted: #71717a;
+  --nymbal-color-text-inverse: #ffffff;
+  --nymbal-color-border: #e4e4e7;
+  --nymbal-color-surface: #ffffff;
+  --nymbal-color-overlay: rgba(0, 0, 0, 0.4);
+
+  --nymbal-font-family: system-ui, -apple-system, sans-serif;
+  --nymbal-font-size-xs: 0.75rem;
+  --nymbal-font-size-sm: 0.875rem;
+  --nymbal-font-size-base: 1rem;
+  --nymbal-font-size-lg: 1.125rem;
+  --nymbal-font-size-xl: 1.25rem;
+  --nymbal-font-weight-normal: 400;
+  --nymbal-font-weight-medium: 500;
+  --nymbal-font-weight-bold: 700;
+
+  --nymbal-spacing-xs: 0.25rem;
+  --nymbal-spacing-sm: 0.5rem;
+  --nymbal-spacing-md: 1rem;
+  --nymbal-spacing-lg: 1.5rem;
+  --nymbal-spacing-xl: 2rem;
+
+  --nymbal-radius-sm: 0.25rem;
+  --nymbal-radius-md: 0.375rem;
+  --nymbal-radius-lg: 0.5rem;
+  --nymbal-radius-full: 9999px;
+
+  --nymbal-shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05);
+  --nymbal-shadow-md: 0 4px 6px rgba(0, 0, 0, 0.1);
+  --nymbal-shadow-lg: 0 10px 15px rgba(0, 0, 0, 0.1);
+
+  --nymbal-transition-fast: 150ms ease;
+  --nymbal-transition-normal: 200ms ease;
+  --nymbal-transition-slow: 300ms ease;
+
+  --nymbal-z-dropdown: 100;
+  --nymbal-z-drawer: 200;
+  --nymbal-z-toast: 300;
+}

package/scaffold/templates/nextjs/components/client/ListingControls.tsx

@@ -0,0 +1,87 @@
+'use client'
+
+import { useCallback, useEffect, useState, type ReactNode } from 'react'
+import type { Facet, ProductSortKey } from '@nymbalhq/types'
+import { ProductFilter, SortDropdown, useNymbalClient } from '@nymbalhq/react'
+import styles from '@/styles/pages/plp.module.css'
+
+interface ListingControlsProps {
+  /** The server-rendered listing's sort and category: the product-list store loads the same page on mount. */
+  sort: ProductSortKey
+  category?: string
+  /** The listing's facets: none when the store's search cannot facet, and then no filter. */
+  facets: Facet[]
+  /** The sort keys the store reports, in order, and the one it lists by when none is asked. */
+  sortKeys: ProductSortKey[]
+  defaultSort?: ProductSortKey | undefined
+  /** The listing's `nymbal-product-grid`, which follows the store once this load settles. */
+  children: ReactNode
+}
+
+/** A listing's filter and sort around its grid: they drive the product-list store, which the grid follows. */
+export function ListingControls({
+  sort,
+  category,
+  facets,
+  sortKeys,
+  defaultSort,
+  children,
+}: ListingControlsProps) {
+  const client = useNymbalClient()
+  const [showMobileFilters, setShowMobileFilters] = useState(false)
+
+  useEffect(() => {
+    void client.productList.load({ limit: 24, category, sort })
+  }, [client, category, sort])
+
+  // The URL carries the sort, so a reload or a shared link renders the same order server-side.
+  const handleSort = useCallback(
+    (event: CustomEvent<{ sort: string }>) => {
+      const key = event.detail.sort as ProductSortKey
+      const url = new URL(window.location.href)
+      url.searchParams.set('sort', key)
+      window.history.replaceState(window.history.state, '', url)
+      void client.productList.setSort(key)
+    },
+    [client],
+  )
+
+  return (
+    <div className={styles.layout}>
+      <aside className={styles.sidebar}>
+        {facets.length > 0 && (
+          <>
+            <button
+              className={styles.mobileFilterToggle}
+              onClick={() => setShowMobileFilters((v) => !v)}
+              type="button"
+            >
+              {showMobileFilters ? 'Hide Filters' : 'Show Filters'}
+            </button>
+            <div
+              className={styles.filterSection}
+              style={{ display: showMobileFilters ? 'block' : undefined }}
+            >
+              <ProductFilter facets={facets} />
+            </div>
+          </>
+        )}
+      </aside>
+
+      <div className={styles.content}>
+        {sortKeys.length > 0 && (
+          <div className={styles.sortBar}>
+            <SortDropdown
+              className={styles.sortSelect}
+              sortKeys={sortKeys}
+              value={sort}
+              defaultSort={defaultSort}
+              onSortChange={handleSort}
+            />
+          </div>
+        )}
+        {children}
+      </div>
+    </div>
+  )
+}

package/scaffold/templates/nextjs/components/client/NymbalSetup.tsx

@@ -1,24 +1,66 @@
 'use client'
 
-import { useEffect, useRef, type ReactNode } from 'react'
+import { useEffect, useLayoutEffect, useRef, type ReactNode } from 'react'
+import { useRouter } from 'next/navigation'
 import { NymbalProvider } from '@nymbalhq/react'
-import { registerClient, registerComponents } from '@nymbalhq/web-components'
-import '@nymbalhq/web-components/tokens.css'
+import '@/elements'
+import { registerClient } from '@nymbalhq/web-components'
+import { NymbalCartDrawer } from '@nymbalhq/web-components/elements/nymbal-cart-drawer'
+import { NymbalMiniCart } from '@nymbalhq/web-components/elements/nymbal-mini-cart'
+import { NymbalSearchBar } from '@nymbalhq/web-components/elements/nymbal-search-bar'
+import { NymbalSiteFooter } from '@nymbalhq/web-components/elements/nymbal-site-footer'
+import { NymbalSiteHeader } from '@nymbalhq/web-components/elements/nymbal-site-header'
 import { getNymbalClient, restoreSession } from '@/lib/client'
 
 export function NymbalSetup({ children }: { children: ReactNode }) {
   const client = getNymbalClient()
+  const router = useRouter()
   const initialized = useRef(false)
 
-  useEffect(() => {
+  // A layout effect runs before every passive effect of the commit, so the client is registered before any wrapper
+  // defines its element (each wrapper defines its own, so a route loads only the elements it renders). The cart starts
+  // loading first, so an element the server rendered from the cart keeps showing it until the load settles.
+  useLayoutEffect(() => {
     if (!initialized.current) {
       registerClient(client)
-      registerComponents()
-      client.cart.load()
+      void client.cart.load()
+      NymbalSiteHeader.define()
+      NymbalSiteFooter.define()
+      NymbalSearchBar.define()
+      NymbalMiniCart.define()
+      NymbalCartDrawer.define()
       void restoreSession()
       initialized.current = true
     }
   }, [client])
 
+  // The elements' links are plain anchors in shadow roots, which the router does not see: each asks with
+  // `nymbal:navigate`, and the router takes it. The header's search bar and mini-cart are in its server HTML, not
+  // React children, so their events are taken here too.
+  useEffect(() => {
+    const navigate = (event: Event): void => {
+      const href = (event as CustomEvent<{ href?: string }>).detail?.href
+      if (!href || new URL(href, window.location.href).origin !== window.location.origin) return
+      event.preventDefault()
+      router.push(href)
+    }
+    const searchSelected = (event: Event): void => {
+      const slug = (event as CustomEvent<{ product?: { slug?: string } }>).detail?.product?.slug
+      if (slug) router.push(`/product/${encodeURIComponent(slug)}`)
+    }
+    // Before the drawer's own listener toggles it, as the wrapper's listener on the mini-cart ran.
+    const miniCartClicked = (): void => {
+      window.dispatchEvent(new CustomEvent('nymbal:cart:open'))
+    }
+    document.addEventListener('nymbal:navigate', navigate)
+    document.addEventListener('nymbal:search:selected', searchSelected)
+    document.addEventListener('nymbal:mini-cart:clicked', miniCartClicked, true)
+    return () => {
+      document.removeEventListener('nymbal:navigate', navigate)
+      document.removeEventListener('nymbal:search:selected', searchSelected)
+      document.removeEventListener('nymbal:mini-cart:clicked', miniCartClicked, true)
+    }
+  }, [router])
+
   return <NymbalProvider client={client}>{children}</NymbalProvider>
 }