create-nymbal-app 0.3.0 → 0.4.0

package/scaffold/templates/astro/src/scripts/checkout.ts

@@ -1,3 +1,5 @@
+import type { PaymentConfirmContext, PaymentConfirmation } from '@nymbalhq/sdk'
+import type { NymbalPaymentElement } from '@nymbalhq/web-components'
 import { client } from '../lib/client.js'
 import { formatPrice } from '../lib/format.js'
 import { submitOnce } from '../lib/submit-once.js'
@@ -152,60 +154,55 @@ shippingForm?.addEventListener('submit', (e) => {
   showStep('payment')
 })
 
-// Stripe setup. The env says only whether a Stripe client exists; the payment flow follows the server's answer.
-let stripe: any = null
-let cardElement: any = null
-
-const stripeKey = import.meta.env.PUBLIC_STRIPE_PUBLISHABLE_KEY
-const isStubPayments =
-  import.meta.env.PUBLIC_NYMBAL_PAYMENTS_PROVIDER === 'native-stub' || !stripeKey
+// The payment step is the store's: the element renders the payments adapter's client half through its driver.
+const paymentForm = document.getElementById('payment-form') as HTMLFormElement | null
+const paymentEl = paymentForm?.querySelector<NymbalPaymentElement>('nymbal-payment-element') ?? null
+const placeOrderBtn = paymentForm?.querySelector<HTMLButtonElement>('[data-testid="place-order"]')
+const paymentBlocked = () => paymentEl?.status === 'error'
 
-async function mountStripe() {
-  if (isStubPayments) {
-    const cardContainer = document.getElementById('stripe-card-element')
-    if (cardContainer) {
-      cardContainer.innerHTML =
-        '<p style="color: var(--nymbal-color-text-muted, #71717a); font-size: 0.875rem; margin: 0;">Test mode — payment skipped</p>'
-    }
-    return
-  }
-  try {
-    const { loadStripe } = await import('@stripe/stripe-js')
-    stripe = await loadStripe(stripeKey)
-    if (!stripe) return
+// While the element cannot take a payment (an unknown driver, a form that failed to load), no order is placed.
+let heldByPayment = false
+function syncPlaceOrder() {
+  if (!placeOrderBtn) return
+  const blocked = paymentBlocked()
+  if (blocked) placeOrderBtn.disabled = true
+  else if (heldByPayment) placeOrderBtn.disabled = false
+  heldByPayment = blocked
+}
+paymentEl?.addEventListener('nymbal:payment:status', syncPlaceOrder)
+syncPlaceOrder()
+paymentForm?.addEventListener(
+  'submit',
+  (e) => {
+    if (!paymentBlocked()) return
+    e.preventDefault()
+    e.stopImmediatePropagation()
+  },
+  true,
+)
 
-    const elements = stripe.elements()
-    cardElement = elements.create('card', {
-      style: {
-        base: {
-          fontSize: '14px',
-          color: '#18181b',
-          '::placeholder': { color: '#71717a' },
-        },
-      },
-    })
+// Place Order renders where Continue was, so the second click of a double-click on Continue lands on it. A click that
+// continues a multi-click is not a decision to pay: the first click of one on Place Order has already submitted.
+placeOrderBtn?.addEventListener('click', (e) => {
+  if (e.detail > 1) e.preventDefault()
+})
 
-    const cardContainer = document.getElementById('stripe-card-element')
-    if (cardContainer) cardElement.mount(cardContainer)
-  } catch {
-    // Stripe unavailable
-  }
+/** No element (a page without a payment step) has nothing to confirm, as a null client does. */
+function confirmPayment(
+  clientSecret: string,
+  context: PaymentConfirmContext,
+): Promise<PaymentConfirmation> {
+  return paymentEl?.confirm(clientSecret, context) ?? Promise.resolve({ ok: true, confirmed: false })
 }
 
-mountStripe()
-
 // Payment form
-const paymentForm = document.getElementById('payment-form') as HTMLFormElement | null
 submitOnce(paymentForm, async () => {
   hideError()
 
-  const submitBtn = paymentForm?.querySelector(
-    '[data-testid="place-order"]',
-  ) as HTMLButtonElement | null
-  if (submitBtn) submitBtn.textContent = 'Processing...'
+  if (placeOrderBtn) placeOrderBtn.textContent = 'Processing...'
   const stay = (message: string) => {
     showError(message)
-    if (submitBtn) submitBtn.textContent = 'Place Order'
+    if (placeOrderBtn) placeOrderBtn.textContent = 'Place Order'
   }
   const leaveFor = (orderNumber: string) => {
     client.checkout.reset()
@@ -243,13 +240,15 @@ submitOnce(paymentForm, async () => {
     if (result.payment.status === 'failed') {
       return stay(client.checkout.getState().error ?? 'Payment failed. Please try again.')
     }
-    // Without a Stripe client (a +stub-pending order) the order page shows it awaiting payment.
-    if (result.payment.status === 'requires_action' && stripe && cardElement) {
-      const { error } = await stripe.confirmCardPayment(result.paymentIntent.clientSecret, {
-        payment_method: { card: cardElement },
+    // Confirmed only when the driver says the payment went through; otherwise the order page shows it awaiting payment.
+    if (result.payment.status === 'requires_action') {
+      const { email, billingAddress } = client.checkout.getState()
+      const confirmation = await confirmPayment(result.paymentIntent.clientSecret, {
+        email: email || undefined,
+        billing: billingAddress ?? undefined,
       })
-      if (error) return stay(error.message ?? 'Payment failed.')
-      client.checkout.markConfirmed()
+      if (!confirmation.ok) return stay(confirmation.error)
+      if (confirmation.confirmed) client.checkout.markConfirmed()
     }
     return leaveFor(result.orderNumber)
   } catch (err: any) {

package/scaffold/templates/astro/src/scripts/pdp.ts

@@ -1,67 +1,58 @@
+import { STOCK_LABELS, stockLevel } from '@nymbalhq/types'
 import { client } from '../lib/client.js'
 import { formatPrice } from '../lib/format.js'
 
 const slug = document.querySelector<HTMLElement>('[data-product-slug]')?.dataset.productSlug
+const addRow = document.querySelector<HTMLElement>('.pdp-add-row')
+const quantity = addRow?.querySelector('nymbal-quantity-selector')
+const addToCart = addRow?.querySelector('nymbal-add-to-cart')
+
+function setQuantity(qty: number): void {
+  quantity?.setAttribute('value', String(qty))
+  addToCart?.setAttribute('qty', String(qty))
+}
 
 if (slug) {
-  client.product.loadBySlug(slug)
+  // The server rendered variants[0]; a change from it resets the quantity.
+  let shownVariantId = addToCart?.getAttribute('variant-id') ?? null
 
-  client.product.subscribe(() => {
-    const state = client.product.getState()
-    if (!state.product) return
+  addRow?.addEventListener('nymbal:quantity:changed', ((e: CustomEvent<{ value: number }>) => {
+    addToCart?.setAttribute('qty', String(e.detail.value))
+  }) as EventListener)
 
-    const product = state.product
-    const selectedVariant = state.selectedVariant ?? product.variants?.[0]
+  client.product.subscribe(() => {
+    const { product, selectedVariant } = client.product.getState()
+    if (!product) return
+    const variant = selectedVariant ?? product.variants?.[0]
 
-    // Update price display
     const priceEl = document.querySelector('[data-testid="product-price"]')
-    if (priceEl && selectedVariant) {
+    if (priceEl) {
       const price = formatPrice(
-        selectedVariant.priceMinor ?? product.priceMinor,
+        variant?.priceMinor ?? product.priceMinor ?? 0,
         product.currency ?? 'GBP',
       )
       priceEl.innerHTML = `<span>${price}</span>`
     }
 
-    // Update stock badge
-    const stockEl = document.querySelector('[data-testid="stock-badge"]')
-    if (stockEl && selectedVariant) {
-      const stock = selectedVariant.stock ?? 0
-      let statusClass: string
-      let label: string
-
-      if (stock <= 0) {
-        statusClass = 'out-of-stock'
-        label = 'Out of Stock'
-      } else if (stock < 5) {
-        statusClass = 'low-stock'
-        label = 'Low Stock'
-      } else {
-        statusClass = 'in-stock'
-        label = 'In Stock'
-      }
+    const stock = variant?.stock ?? 0
+    const level = stockLevel(stock)
+    const badge = document.querySelector<HTMLElement>('[data-testid="stock-badge"]')
+    if (badge) {
+      badge.dataset.level = level
+      const label = badge.querySelector('[data-stock-label]')
+      if (label) label.textContent = STOCK_LABELS[level]
+    }
 
-      stockEl.className = `pdp-stock ${statusClass}`
-      stockEl.innerHTML = `<span class="pdp-stock-dot" aria-hidden="true"></span>${label}`
+    if (addToCart && variant) {
+      addToCart.setAttribute('variant-id', variant.id)
+      addToCart.toggleAttribute('disabled', stock <= 0)
     }
 
-    // Update add-to-cart variant-id
-    const addToCart = document.querySelector('nymbal-add-to-cart')
-    if (addToCart && selectedVariant) {
-      addToCart.setAttribute('variant-id', selectedVariant.id)
-      if (selectedVariant.stock <= 0) {
-        addToCart.setAttribute('disabled', '')
-      } else {
-        addToCart.removeAttribute('disabled')
-      }
+    if (variant && variant.id !== shownVariantId) {
+      shownVariantId = variant.id
+      setQuantity(1)
     }
   })
 
-  // Listen for variant selection from the web component
-  document.addEventListener('nymbal:variant:selected', ((e: CustomEvent) => {
-    const variantId = e.detail?.variantId
-    if (variantId) {
-      client.product.selectVariant(variantId)
-    }
-  }) as EventListener)
+  client.product.loadBySlug(slug)
 }

package/scaffold/templates/astro/src/scripts/plp.ts

@@ -3,15 +3,15 @@ import { client } from '../lib/client.js'
 import { escapeHtml, formatPrice } from '../lib/format.js'
 
 const gridContainer = document.getElementById('product-grid')
-const sortSelect = document.getElementById('sort-select') as HTMLSelectElement | null
+const sortDropdown = document.querySelector('nymbal-sort-dropdown')
 const loadMoreBtn = document.getElementById('load-more-btn')
 const countEl = document.getElementById('product-count')
 
 // A category page carries its category in the path, which the server render puts on the grid; /products may carry
-// one in the query. The server render also selected the URL's sort in the dropdown.
+// one in the query. The server render puts the sort it resolved from the URL on the dropdown's `value`.
 const urlParams = new URLSearchParams(window.location.search)
 const initialCategory = gridContainer?.dataset.category ?? urlParams.get('category') ?? undefined
-const initialSort = (sortSelect?.value ?? 'newest') as ProductSortKey
+const initialSort = (sortDropdown?.getAttribute('value') || 'newest') as ProductSortKey
 
 function renderProductCard(product: any): string {
   const imageUrl =
@@ -94,9 +94,10 @@ async function init() {
 
 void init()
 
+// The element's event, not its select's `change`: the select may be the element's own rather than the server's.
 // The URL carries the sort, so a reload or a shared link renders the same order server-side.
-sortSelect?.addEventListener('change', () => {
-  const sort = sortSelect.value as ProductSortKey
+sortDropdown?.addEventListener('nymbal:sort:changed', (e) => {
+  const sort = (e as CustomEvent<{ sort: ProductSortKey }>).detail.sort
   const url = new URL(window.location.href)
   url.searchParams.set('sort', sort)
   window.history.replaceState(window.history.state, '', url)

package/scaffold/templates/astro/src/scripts/search.ts

@@ -57,7 +57,8 @@ function renderResults() {
   const state = client.search.getState()
   const results = state.results ?? []
   const query = state.query ?? ''
-  const isLoading = state.loading ?? false
+  // A load-more or category change keeps the results shown until its answer replaces them.
+  const isLoading = (state.loading ?? false) && results.length === 0
 
   if (!resultsContainer) return
 
@@ -100,34 +101,55 @@ function renderResults() {
     return
   }
 
-  resultsContainer.replaceChildren(
+  const total = state.total
+  const children: HTMLElement[] = [
     el(
       'div',
       { class: 'search-results-header' },
       el(
         'span',
-        { class: 'search-result-count' },
-        `${results.length} result${results.length === 1 ? '' : 's'}`,
+        { class: 'search-result-count', 'data-testid': 'search-total' },
+        `${total} result${total === 1 ? '' : 's'}`,
       ),
     ),
     el('div', { class: 'product-grid' }, ...results.map(renderProductCard)),
-  )
+  ]
+  if (state.nextCursor !== null) {
+    const loadMore = el(
+      'button',
+      { type: 'button', class: 'btn btn-secondary', 'data-testid': 'search-load-more' },
+      state.loading ? 'Loading...' : 'Load more',
+    ) as HTMLButtonElement
+    loadMore.disabled = state.loading
+    loadMore.addEventListener('click', () => void client.search.loadMore())
+    children.push(el('div', { class: 'plp-pagination' }, loadMore))
+  }
+  resultsContainer.replaceChildren(...children)
 }
 
 client.search.subscribe(renderResults)
 
-// Read initial query from URL
+// Read initial query and category from URL
 const urlParams = new URLSearchParams(window.location.search)
 const initialQuery = urlParams.get('q')
 
 if (initialQuery) {
   if (searchInput) searchInput.value = initialQuery
-  client.search.search(initialQuery)
+  client.search.search(initialQuery, { category: urlParams.get('category') })
 } else {
   renderResults()
 }
 
-// Listen for search input changes
+// The category filter has narrowed the search; the URL follows, beside ?q.
+document.addEventListener('nymbal:filter:changed', (event) => {
+  const { value } = (event as CustomEvent<{ name: string; value: string }>).detail
+  const url = new URL(window.location.href)
+  if (value) url.searchParams.set('category', value)
+  else url.searchParams.delete('category')
+  window.history.replaceState({}, '', url.toString())
+})
+
+// Listen for search input changes: a new query searches every category again.
 searchInput?.addEventListener('input', () => {
   const value = searchInput.value.trim()
   if (value.length >= 2) {
@@ -135,11 +157,13 @@ searchInput?.addEventListener('input', () => {
     // Update URL without reload
     const url = new URL(window.location.href)
     url.searchParams.set('q', value)
+    url.searchParams.delete('category')
     window.history.replaceState({}, '', url.toString())
   } else if (value.length === 0) {
     client.search.clearSearch()
     const url = new URL(window.location.href)
     url.searchParams.delete('q')
+    url.searchParams.delete('category')
     window.history.replaceState({}, '', url.toString())
   }
 })

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

@@ -110,34 +110,6 @@
   gap: var(--nymbal-spacing-sm, 0.5rem);
 }
 
-.cart-line-quantity-btn {
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  width: 32px;
-  height: 32px;
-  border: 1px solid var(--nymbal-color-border, #e4e4e7);
-  border-radius: var(--nymbal-radius-md, 0.5rem);
-  background: var(--nymbal-color-surface, #fff);
-  color: var(--nymbal-color-text, #18181b);
-  font-size: var(--nymbal-font-size-base, 1rem);
-  cursor: pointer;
-  transition: border-color var(--nymbal-transition-fast, 150ms) ease,
-    background-color var(--nymbal-transition-fast, 150ms) ease;
-}
-
-.cart-line-quantity-btn:hover {
-  border-color: var(--nymbal-color-primary, #18181b);
-  background-color: #f4f4f5;
-}
-
-.cart-line-quantity-value {
-  font-size: var(--nymbal-font-size-sm, 0.875rem);
-  font-weight: var(--nymbal-font-weight-medium, 500);
-  min-width: 24px;
-  text-align: center;
-}
-
 .cart-line-total {
   font-size: var(--nymbal-font-size-sm, 0.875rem);
   font-weight: var(--nymbal-font-weight-bold, 700);

package/scaffold/templates/astro/src/styles/pages/pdp.css

@@ -149,11 +149,15 @@
   font-weight: var(--nymbal-font-weight-medium, 500);
 }
 
-.pdp-stock.in-stock {
+.pdp-stock[data-level='in'] {
   color: var(--nymbal-color-success, #16a34a);
 }
 
-.pdp-stock.out-of-stock {
+.pdp-stock[data-level='low'] {
+  color: var(--nymbal-color-warning, #d97706);
+}
+
+.pdp-stock[data-level='out'] {
   color: var(--nymbal-color-error, #dc2626);
 }
 

package/scaffold/templates/astro/src/styles/pages/search.css

@@ -44,6 +44,25 @@
   box-shadow: 0 0 0 4px rgba(37, 99, 235, 0.12);
 }
 
+/* ---- Category filter beside the results ---- */
+
+.search-layout {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr);
+  gap: var(--nymbal-spacing-lg, 1.5rem);
+}
+
+/* The filter renders nothing when the search has no facets: the results take the width. */
+@media (min-width: 769px) {
+  .search-layout:has(nymbal-product-filter:not(:empty)) {
+    grid-template-columns: 240px minmax(0, 1fr);
+  }
+}
+
+.search-sidebar:has(nymbal-product-filter:empty) {
+  display: none;
+}
+
 /* ---- Results area ---- */
 
 .search-results {

package/scaffold/templates/nextjs/app/category/[slug]/page.tsx

@@ -1,6 +1,6 @@
 import type { Metadata } from 'next'
 import { notFound } from 'next/navigation'
-import { fetchProducts, fetchCategories, sortFromSearchParams } from '@/lib/api'
+import { fetchProducts, fetchCategories, fetchCapabilities, sortFromSearchParams } from '@/lib/api'
 import { Breadcrumb } from '@/components/server/Breadcrumb'
 import { ProductGrid } from '@/components/client/ProductGrid'
 import styles from '@/styles/pages/plp.module.css'
@@ -25,8 +25,9 @@ export async function generateMetadata({
 
 export default async function CategoryPage({ params, searchParams }: CategoryPageProps) {
   const { slug } = await params
-  const sort = sortFromSearchParams(await searchParams)
-  const [{ items, nextCursor }, categories] = await Promise.all([
+  const capabilities = await fetchCapabilities()
+  const sort = sortFromSearchParams(await searchParams, capabilities?.catalog)
+  const [{ items, nextCursor, facets }, categories] = await Promise.all([
     fetchProducts({ limit: 24, category: slug, sort }),
     fetchCategories(),
   ])
@@ -50,8 +51,10 @@ export default async function CategoryPage({ params, searchParams }: CategoryPag
         initialProducts={items}
         initialCursor={nextCursor}
         initialSort={sort}
+        initialFacets={facets ?? []}
+        sortKeys={capabilities?.catalog.sortKeys ?? []}
+        defaultSort={capabilities?.catalog.defaultSort}
         categorySlug={slug}
-        categories={categories}
       />
     </div>
   )

package/scaffold/templates/nextjs/app/checkout/page.tsx

@@ -1,10 +1,17 @@
 import type { Metadata } from 'next'
 import { CheckoutForm } from '@/components/client/CheckoutForm'
+import { fetchCapabilities } from '@/lib/api'
 
 export const metadata: Metadata = {
   title: 'Checkout',
 }
 
-export default function CheckoutRoute() {
-  return <CheckoutForm />
+export default async function CheckoutRoute() {
+  const capabilities = await fetchCapabilities()
+  if (capabilities === null) {
+    throw new Error(
+      'The store did not answer GET /api/capabilities, so checkout cannot tell how to take a payment.',
+    )
+  }
+  return <CheckoutForm capabilities={capabilities} />
 }

package/scaffold/templates/nextjs/app/products/page.tsx

@@ -1,5 +1,5 @@
 import type { Metadata } from 'next'
-import { fetchProducts, fetchCategories, sortFromSearchParams } from '@/lib/api'
+import { fetchProducts, fetchCapabilities, sortFromSearchParams } from '@/lib/api'
 import { Breadcrumb } from '@/components/server/Breadcrumb'
 import { ProductGrid } from '@/components/client/ProductGrid'
 import styles from '@/styles/pages/plp.module.css'
@@ -14,11 +14,9 @@ interface ProductsPageProps {
 }
 
 export default async function ProductsPage({ searchParams }: ProductsPageProps) {
-  const sort = sortFromSearchParams(await searchParams)
-  const [{ items, nextCursor }, categories] = await Promise.all([
-    fetchProducts({ limit: 24, sort }),
-    fetchCategories(),
-  ])
+  const capabilities = await fetchCapabilities()
+  const sort = sortFromSearchParams(await searchParams, capabilities?.catalog)
+  const { items, nextCursor, facets } = await fetchProducts({ limit: 24, sort })
 
   return (
     <div className={`container ${styles.page}`}>
@@ -33,7 +31,9 @@ export default async function ProductsPage({ searchParams }: ProductsPageProps)
         initialProducts={items}
         initialCursor={nextCursor}
         initialSort={sort}
-        categories={categories}
+        initialFacets={facets ?? []}
+        sortKeys={capabilities?.catalog.sortKeys ?? []}
+        defaultSort={capabilities?.catalog.defaultSort}
       />
     </div>
   )

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

@@ -76,6 +76,7 @@ export function CartPage() {
                       type="button"
                       className={styles.removeButton}
                       onClick={() => removeItem(item.variantId)}
+                      data-testid={`cart-remove-${item.variantId}`}
                       aria-label={`Remove ${item.productName} from cart`}
                     >
                       Remove