create-nymbal-app 0.4.0 → 0.5.0

package/scaffold/templates/astro/src/lib/chrome.ts

@@ -0,0 +1,59 @@
+import { renderElement } from '@nymbalhq/web-components/ssr'
+import './server-elements'
+
+// The store's header and footer, rendered by nymbal-site-header and nymbal-site-footer: edit the links here.
+
+export const HEADER = {
+  logo: 'Nymbal',
+  'account-href': '/account',
+  links: JSON.stringify([
+    { label: 'Apparel', href: '/category/apparel' },
+    { label: 'Home', href: '/category/home' },
+    { label: 'Electronics', href: '/category/electronics' },
+    { label: 'Books', href: '/category/books' },
+    { label: 'All Products', href: '/products' },
+  ]),
+}
+
+export const FOOTER = {
+  columns: JSON.stringify([
+    {
+      heading: 'Shop',
+      links: [
+        { label: 'All Products', href: '/products' },
+        { label: 'Apparel', href: '/category/apparel' },
+        { label: 'Home', href: '/category/home' },
+        { label: 'Electronics', href: '/category/electronics' },
+        { label: 'Books', href: '/category/books' },
+      ],
+    },
+    {
+      heading: 'Account',
+      links: [
+        { label: 'Login', href: '/account/login' },
+        { label: 'Register', href: '/account/register' },
+        { label: 'Orders', href: '/account/orders' },
+      ],
+    },
+    {
+      heading: 'About',
+      text: 'Nymbal is a modern headless commerce platform built for developers. Fast, flexible, and fully customisable.',
+    },
+  ]),
+}
+
+/**
+ * The header's light-DOM children, each rendered by the server with the slot it fills: the search bar (when the store
+ * searches) and the mini-cart with the shopper's count (none in a shared, cached header). HTML, not markup: Astro
+ * would take `slot` on a component's child as a slot of NymbalElement's own.
+ */
+export function headerSlots(canSearch: boolean, cartCount?: number): string {
+  const search = canSearch
+    ? renderElement('nymbal-search-bar', {
+        attributes: { slot: 'search', placeholder: 'Search products...', 'debounce-ms': '300' },
+      })
+    : ''
+  const attributes: Record<string, string> = { slot: 'cart' }
+  if (cartCount !== undefined) attributes['count'] = String(cartCount)
+  return search + renderElement('nymbal-mini-cart', { attributes })
+}

package/scaffold/templates/astro/src/lib/client.ts

@@ -1,5 +1,6 @@
+import '../elements/index.js'
 import { createNymbalClient } from '@nymbalhq/sdk'
-import { registerClient, registerComponents } from '@nymbalhq/web-components'
+import { registerClient } from '@nymbalhq/web-components'
 
 const client = createNymbalClient({
   baseUrl: import.meta.env.PUBLIC_NYMBAL_API_URL ?? 'http://localhost:3001',
@@ -7,9 +8,8 @@ const client = createNymbalClient({
 })
 
 registerClient(client)
-// A payment driver of the project's own goes here, before the components: registerPaymentDriver(name, driver) from
-// @nymbalhq/sdk, named by the driver of the payments adapter's client half.
-registerComponents()
+// A payment driver of the project's own goes here, before any element is defined: registerPaymentDriver(name, driver)
+// from @nymbalhq/sdk, named by the driver of the payments adapter's client half.
 client.cart.load()
 
 export { client }

package/scaffold/templates/astro/src/lib/fragments.ts

@@ -0,0 +1,48 @@
+import type { DenormalisedProduct } from '@nymbalhq/sdk'
+import type { Category } from '@nymbalhq/types'
+import { loadCapabilities, loadCategories, loadProduct } from './api'
+
+// A fragment is cached by a CDN for hours, so it carries only what the API sent: when the API fails, the fragment
+// answers an error no cache keeps, never a fallback (no categories, no search bar) a CDN would hold for its TTL.
+
+const NOT_STORED = { 'Content-Type': 'text/plain; charset=utf-8', 'Cache-Control': 'no-store' }
+
+function apiFailed(fragment: string, err: unknown): Response {
+  console.error(`[fragments] ${fragment}: the API failed`, err)
+  return new Response('The store API is unavailable', { status: 502, headers: NOT_STORED })
+}
+
+/** The header fragment's data: whether the store searches; a 502 `no-store` response when the API failed. */
+export async function headerFragment(): Promise<{ canSearch: boolean } | Response> {
+  try {
+    const capabilities = await loadCapabilities()
+    return { canSearch: capabilities.search.capabilities.includes('search') }
+  } catch (err) {
+    return apiFailed('header', err)
+  }
+}
+
+/** The nav fragment's data: the API's categories; a 502 `no-store` response when the API failed. */
+export async function navFragment(): Promise<{ categories: Category[] } | Response> {
+  try {
+    return { categories: await loadCategories() }
+  } catch (err) {
+    return apiFailed('nav', err)
+  }
+}
+
+/**
+ * The product fragment's data: the API's product; a 404 `no-store` response for a product the API does not have (a CDN
+ * would apply its default 404 TTL to a 404 with no Cache-Control), a 502 `no-store` one when the API failed.
+ */
+export async function productFragment(
+  slug: string,
+): Promise<{ product: DenormalisedProduct } | Response> {
+  try {
+    const product = await loadProduct(slug)
+    if (product === null) return new Response('Not found', { status: 404, headers: NOT_STORED })
+    return { product }
+  } catch (err) {
+    return apiFailed('product', err)
+  }
+}

package/scaffold/templates/astro/src/lib/server-elements.ts

@@ -0,0 +1,5 @@
+import { registerServerElements } from '@nymbalhq/web-components/ssr'
+import { serverElements } from '../elements/index.js'
+
+// The store's own elements render on the server under their tags, as the browser defines them there.
+registerServerElements(serverElements)

package/scaffold/templates/astro/src/middleware.ts

@@ -0,0 +1,37 @@
+import { defineMiddleware } from 'astro:middleware'
+
+/** Whether an `Accept-Encoding` value accepts gzip: a `gzip` entry (or, without one, `*`) with a q-value above 0. */
+function acceptsGzip(header: string): boolean {
+  let star = false
+  for (const entry of header.split(',')) {
+    const [coding = '', ...params] = entry.split(';').map((part) => part.trim().toLowerCase())
+    const q = params.find((param) => param.startsWith('q='))
+    const accepted = q === undefined || Number(q.slice(2)) > 0
+    if (coding === 'gzip' || coding === 'x-gzip') return accepted
+    if (coding === '*') star = accepted
+  }
+  return star
+}
+
+// The standalone Node adapter compresses nothing, so a page's HTML (its styles inlined) went over the wire whole.
+// An HTML response is gzipped as a stream when the client accepts it; everything else passes through unchanged, and a
+// proxy that compresses sees the encoding and passes it on. Every HTML response varies on Accept-Encoding, the
+// uncompressed one included, so a cache keeps both forms apart.
+export const onRequest = defineMiddleware(async (context, next) => {
+  const response = await next()
+  const type = response.headers.get('content-type') ?? ''
+  if (!type.startsWith('text/html') || response.headers.has('content-encoding')) return response
+  const headers = new Headers(response.headers)
+  headers.append('vary', 'Accept-Encoding')
+  let body = response.body
+  if (body !== null && acceptsGzip(context.request.headers.get('accept-encoding') ?? '')) {
+    headers.set('content-encoding', 'gzip')
+    headers.delete('content-length')
+    body = body.pipeThrough(new CompressionStream('gzip'))
+  }
+  return new Response(body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  })
+})

package/scaffold/templates/astro/src/pages/account/addresses.astro

@@ -1,110 +1,18 @@
 ---
 import '../../styles/pages/account.css'
-import '../../styles/pages/checkout.css'
+import NymbalElement from '@nymbalhq/web-components/astro'
 import AccountLayout from '../../layouts/AccountLayout.astro'
-import AddressForm from '../../components/AddressForm.astro'
 ---
 
 <AccountLayout title="Addresses">
   <h1 class="account-page-title">Addresses</h1>
 
-  <div id="addresses-container" data-testid="addresses-list">
-    <p style="color: var(--nymbal-color-text-muted, #71717a); font-size: var(--nymbal-font-size-sm, 0.875rem);">
-      Loading addresses...
-    </p>
-  </div>
-
-  <div style="margin-top: var(--nymbal-spacing-xl, 2rem);">
-    <h2 class="section-title">Add New Address</h2>
-    <form id="add-address-form" class="account-form" data-testid="add-address-form">
-      <AddressForm id="new-address" />
-      <div class="account-form-actions">
-        <button type="submit" class="btn btn-primary" data-testid="save-address">Save Address</button>
-      </div>
-    </form>
-    <p class="form-message" id="address-form-message" style="display:none; margin-top: var(--nymbal-spacing-md, 1rem); font-size: var(--nymbal-font-size-sm, 0.875rem);"></p>
-  </div>
+  <NymbalElement tag="nymbal-address-book" />
 </AccountLayout>
 
 <script>
-  import type { Address, CustomerAddress } from '@nymbalhq/types'
-  import { client } from '../../lib/client.js'
-  import { escapeHtml } from '../../lib/format.js'
-  import { submitOnce } from '../../lib/submit-once.js'
-
-  const container = document.getElementById('addresses-container')
-  const form = document.getElementById('add-address-form') as HTMLFormElement | null
-  const messageEl = document.getElementById('address-form-message')
-
-  function renderAddress(addr: CustomerAddress): string {
-    const isDefault = addr.isDefaultShipping || addr.isDefaultBilling
-    return `
-      <div class="address-card ${isDefault ? 'default' : ''}" data-testid="address-${escapeHtml(addr.id)}">
-        ${isDefault ? '<span class="address-card-badge">Default</span>' : ''}
-        <div class="address-card-line">${escapeHtml(`${addr.firstName} ${addr.lastName}`)}</div>
-        <div class="address-card-line">${escapeHtml(addr.addressLine1)}</div>
-        ${addr.addressLine2 ? `<div class="address-card-line">${escapeHtml(addr.addressLine2)}</div>` : ''}
-        <div class="address-card-line">${escapeHtml(`${addr.city}, ${addr.region} ${addr.postalCode}`)}</div>
-        <div class="address-card-line">${escapeHtml(addr.country)}</div>
-      </div>
-    `
-  }
-
-  async function loadAddresses() {
-    if (!container) return
-
-    try {
-      const addresses = await client.customer.addresses.list()
-
-      if (addresses.length === 0) {
-        container.innerHTML = `
-          <div class="account-empty">
-            <h2 class="account-empty-title">No saved addresses</h2>
-            <p class="account-empty-text">Add an address below to get started.</p>
-          </div>
-        `
-        return
-      }
-
-      container.innerHTML = `<div class="address-list">${addresses.map(renderAddress).join('')}</div>`
-    } catch {
-      container.innerHTML = `
-        <div class="account-empty">
-          <p class="account-empty-text">Unable to load addresses.</p>
-        </div>
-      `
-    }
-  }
-
-  submitOnce(form, async () => {
-    if (!form || !messageEl) return
-
-    const formData = new FormData(form)
-    const field = (name: string) => String(formData.get(name) ?? '').trim()
-    const address: Address = {
-      firstName: field('firstName'),
-      lastName: field('lastName'),
-      addressLine1: field('addressLine1'),
-      city: field('city'),
-      region: field('region'),
-      postalCode: field('postalCode'),
-      country: field('country'),
-      ...(field('addressLine2') && { addressLine2: field('addressLine2') }),
-    }
-
-    try {
-      await client.customer.addresses.create(address)
-      messageEl.textContent = 'Address saved successfully.'
-      messageEl.style.color = 'var(--nymbal-color-success, #16a34a)'
-      messageEl.style.display = 'block'
-      form.reset()
-      await loadAddresses()
-    } catch {
-      messageEl.textContent = 'Failed to save address. Please try again.'
-      messageEl.style.color = 'var(--nymbal-color-error, #dc2626)'
-      messageEl.style.display = 'block'
-    }
-  })
+  import '../../lib/client.js'
+  import { NymbalAddressBook } from '@nymbalhq/web-components/elements/nymbal-address-book'
 
-  loadAddresses()
+  NymbalAddressBook.define()
 </script>

package/scaffold/templates/astro/src/pages/account/login.astro

@@ -1,5 +1,6 @@
 ---
 import '../../styles/pages/account.css'
+import NymbalElement from '@nymbalhq/web-components/astro'
 import BaseLayout from '../../layouts/BaseLayout.astro'
 ---
 
@@ -9,39 +10,7 @@ import BaseLayout from '../../layouts/BaseLayout.astro'
       <h1 class="auth-card-title">Sign In</h1>
       <p class="auth-card-subtitle">Welcome back. Enter your credentials to continue.</p>
 
-      <div class="checkout-error" id="login-error" style="display:none; margin-bottom: var(--nymbal-spacing-md, 1rem);" role="alert"></div>
-
-      <form id="login-form" data-testid="login-form">
-        <div class="form-group">
-          <label for="login-email">Email</label>
-          <input
-            type="email"
-            id="login-email"
-            name="email"
-            required
-            autocomplete="email"
-            placeholder="you@example.com"
-            data-testid="login-email"
-          />
-        </div>
-
-        <div class="form-group">
-          <label for="login-password">Password</label>
-          <input
-            type="password"
-            id="login-password"
-            name="password"
-            required
-            autocomplete="current-password"
-            placeholder="Your password"
-            data-testid="login-password"
-          />
-        </div>
-
-        <button type="submit" class="btn btn-primary" data-testid="login-submit">
-          Sign In
-        </button>
-      </form>
+      <NymbalElement tag="nymbal-login-form" />
 
       <p class="auth-footer">
         Don't have an account? <a href="/account/register">Create one</a>
@@ -51,5 +20,9 @@ import BaseLayout from '../../layouts/BaseLayout.astro'
 </BaseLayout>
 
 <script>
-  import '../../scripts/auth-forms.js'
+  import '../../lib/client.js'
+  import { NymbalLoginForm } from '@nymbalhq/web-components/elements/nymbal-login-form'
+  import '../../scripts/signed-in-redirect.js'
+
+  NymbalLoginForm.define()
 </script>

package/scaffold/templates/astro/src/pages/account/profile.astro

@@ -1,5 +1,6 @@
 ---
 import '../../styles/pages/account.css'
+import NymbalElement from '@nymbalhq/web-components/astro'
 import AccountLayout from '../../layouts/AccountLayout.astro'
 ---
 
@@ -7,63 +8,12 @@ import AccountLayout from '../../layouts/AccountLayout.astro'
   <h1 class="account-page-title">Profile</h1>
   <p class="account-page-subtitle">Update your personal information.</p>
 
-  <form id="profile-form" class="account-form" data-testid="profile-form">
-    <div class="account-form-row">
-      <div class="form-group">
-        <label for="profile-firstName">First Name</label>
-        <input
-          type="text"
-          id="profile-firstName"
-          name="firstName"
-          autocomplete="given-name"
-          data-testid="profile-firstName"
-        />
-      </div>
-
-      <div class="form-group">
-        <label for="profile-lastName">Last Name</label>
-        <input
-          type="text"
-          id="profile-lastName"
-          name="lastName"
-          autocomplete="family-name"
-          data-testid="profile-lastName"
-        />
-      </div>
-    </div>
-
-    <div class="form-group">
-      <label for="profile-email">Email</label>
-      <input
-        type="email"
-        id="profile-email"
-        name="email"
-        disabled
-        autocomplete="email"
-        data-testid="profile-email"
-        style="opacity: 0.6; cursor: not-allowed;"
-      />
-    </div>
-
-    <div class="form-group">
-      <label for="profile-phone">Phone</label>
-      <input
-        type="tel"
-        id="profile-phone"
-        name="phone"
-        autocomplete="tel"
-        data-testid="profile-phone"
-      />
-    </div>
-
-    <div class="account-form-actions">
-      <button type="submit" class="btn btn-primary" data-testid="profile-save">Save Changes</button>
-    </div>
-
-    <p class="form-message" id="profile-message" style="display:none; margin-top: var(--nymbal-spacing-md, 1rem); font-size: var(--nymbal-font-size-sm, 0.875rem);"></p>
-  </form>
+  <NymbalElement tag="nymbal-profile-form" attributes={{ class: 'account-form' }} />
 </AccountLayout>
 
 <script>
-  import '../../scripts/profile-form.js'
+  import '../../lib/client.js'
+  import { NymbalProfileForm } from '@nymbalhq/web-components/elements/nymbal-profile-form'
+
+  NymbalProfileForm.define()
 </script>

package/scaffold/templates/astro/src/pages/account/register.astro

@@ -1,5 +1,6 @@
 ---
 import '../../styles/pages/account.css'
+import NymbalElement from '@nymbalhq/web-components/astro'
 import BaseLayout from '../../layouts/BaseLayout.astro'
 ---
 
@@ -9,78 +10,7 @@ import BaseLayout from '../../layouts/BaseLayout.astro'
       <h1 class="auth-card-title">Create Account</h1>
       <p class="auth-card-subtitle">Join us and start shopping.</p>
 
-      <div class="checkout-error" id="register-error" style="display:none; margin-bottom: var(--nymbal-spacing-md, 1rem);" role="alert"></div>
-
-      <form id="register-form" data-testid="register-form">
-        <div class="account-form-row">
-          <div class="form-group">
-            <label for="register-firstName">First Name</label>
-            <input
-              type="text"
-              id="register-firstName"
-              name="firstName"
-              autocomplete="given-name"
-              placeholder="First name"
-              data-testid="register-firstName"
-            />
-          </div>
-
-          <div class="form-group">
-            <label for="register-lastName">Last Name</label>
-            <input
-              type="text"
-              id="register-lastName"
-              name="lastName"
-              autocomplete="family-name"
-              placeholder="Last name"
-              data-testid="register-lastName"
-            />
-          </div>
-        </div>
-
-        <div class="form-group">
-          <label for="register-email">Email</label>
-          <input
-            type="email"
-            id="register-email"
-            name="email"
-            required
-            autocomplete="email"
-            placeholder="you@example.com"
-            data-testid="register-email"
-          />
-        </div>
-
-        <div class="form-group">
-          <label for="register-password">Password</label>
-          <input
-            type="password"
-            id="register-password"
-            name="password"
-            required
-            autocomplete="new-password"
-            placeholder="Choose a password"
-            minlength="8"
-            data-testid="register-password"
-          />
-        </div>
-
-        <div class="form-group">
-          <label for="register-phone">Phone (optional)</label>
-          <input
-            type="tel"
-            id="register-phone"
-            name="phone"
-            autocomplete="tel"
-            placeholder="+44 7700 900000"
-            data-testid="register-phone"
-          />
-        </div>
-
-        <button type="submit" class="btn btn-primary" data-testid="register-submit">
-          Create Account
-        </button>
-      </form>
+      <NymbalElement tag="nymbal-register-form" />
 
       <p class="auth-footer">
         Already have an account? <a href="/account/login">Sign in</a>
@@ -90,5 +20,9 @@ import BaseLayout from '../../layouts/BaseLayout.astro'
 </BaseLayout>
 
 <script>
-  import '../../scripts/auth-forms.js'
+  import '../../lib/client.js'
+  import { NymbalRegisterForm } from '@nymbalhq/web-components/elements/nymbal-register-form'
+  import '../../scripts/signed-in-redirect.js'
+
+  NymbalRegisterForm.define()
 </script>

package/scaffold/templates/astro/src/pages/cart.astro

@@ -1,16 +1,23 @@
 ---
-import '../styles/pages/cart.css'
+import NymbalElement from '@nymbalhq/web-components/astro'
 import BaseLayout from '../layouts/BaseLayout.astro'
+import { fetchCart } from '../lib/api'
+
+const cart = await fetchCart(Astro.request.headers.get('cookie'))
 ---
 
-<BaseLayout title="Your Cart | Nymbal" description="Review the items in your cart.">
-  <div class="container section" id="cart-content" data-testid="cart-page">
-    <div class="cart-empty">
-      <h1 class="cart-empty-title">Loading your cart...</h1>
-    </div>
+<BaseLayout title="Your Cart | Nymbal" description="Review the items in your cart." cart={cart}>
+  <div class="container section" data-testid="cart-page">
+    <NymbalElement
+      tag="nymbal-cart-page"
+      attributes={cart === null ? {} : { cart: JSON.stringify(cart) }}
+    />
   </div>
 </BaseLayout>
 
 <script>
-  import '../scripts/cart-page.js'
+  import '../lib/client.js'
+  import { NymbalCartPage } from '@nymbalhq/web-components/elements/nymbal-cart-page'
+
+  NymbalCartPage.define()
 </script>

package/scaffold/templates/astro/src/pages/category/[slug].astro

@@ -1,10 +1,8 @@
 ---
 import '../../styles/pages/plp.css'
-import '../../styles/pages/home.css'
 import BaseLayout from '../../layouts/BaseLayout.astro'
-import Breadcrumb from '../../components/Breadcrumb.astro'
-import ProductCard from '../../components/ProductCard.astro'
-import Pagination from '../../components/Pagination.astro'
+import NymbalElement from '@nymbalhq/web-components/astro'
+import { cardImageOf, cardProductOf } from '@nymbalhq/web-components/ssr'
 import { PRODUCT_SORT_LABELS } from '@nymbalhq/types'
 import { fetchProducts, fetchCategories, fetchCapabilities, sortFromUrl } from '../../lib/api'
 
@@ -18,7 +16,10 @@ const [productResult, categories] = await Promise.all([
   fetchCategories(),
 ])
 
-const products = productResult.items
+const products = productResult.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:
+// the head starts it.
+const firstImage = products[0] === undefined ? null : cardImageOf(products[0]).url
 const category = categories.find((c) => c.slug === slug)
 const categoryName = category?.name ?? slug ?? 'Category'
 const facets = productResult.facets ?? []
@@ -28,8 +29,9 @@ const facets = productResult.facets ?? []
   title={`${categoryName} | Nymbal`}
   description={category?.description ?? `Browse ${categoryName} products.`}
 >
+  {firstImage && <link slot="head" rel="preload" as="image" href={firstImage} fetchpriority="high" />}
   <div class="container section">
-    <Breadcrumb items={[{ label: 'Home', href: '/' }, { label: categoryName }]} />
+    <NymbalElement tag="nymbal-breadcrumb" attributes={{ items: JSON.stringify([{ label: 'Home', href: '/' }, { label: categoryName }]) }} />
 
     <div class="plp-header">
       <h1 class="plp-title">{categoryName}</h1>
@@ -38,7 +40,6 @@ const facets = productResult.facets ?? []
           {category.description}
         </p>
       )}
-      <p class="plp-count" id="product-count">{products.length} products</p>
     </div>
 
     <div class="plp-layout">
@@ -68,20 +69,15 @@ const facets = productResult.facets ?? []
           </div>
         )}
 
-        <div class="product-grid" id="product-grid" data-category={slug}>
-          {products.map((product) => (
-            <ProductCard product={product} />
-          ))}
-        </div>
-
-        {products.length === 0 && (
-          <div class="plp-empty">
-            <h2 class="plp-empty-title">No products found</h2>
-            <p class="plp-empty-text">Check back soon for new arrivals.</p>
-          </div>
-        )}
-
-        <Pagination />
+        <NymbalElement
+          tag="nymbal-product-grid"
+          attributes={{
+            products: JSON.stringify(products),
+            source: 'product-list',
+            ...(productResult.nextCursor !== null && { 'has-more': '' }),
+            'data-category': slug!,
+          }}
+        />
       </div>
     </div>
   </div>