create-nymbal-app 0.2.0 → 0.4.0

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

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

@@ -1,19 +1,14 @@
 'use client'
 
-import { useState, useCallback, type FormEvent } from 'react'
+import { useState, useCallback, useEffect, useRef, type FormEvent } from 'react'
 import { useRouter } from 'next/navigation'
-import { useCheckout, useCart, useNymbalClient } from '@nymbalhq/react'
-import { Elements, CardElement, useStripe, useElements } from '@stripe/react-stripe-js'
-import { loadStripe } from '@stripe/stripe-js'
+import { PaymentElement, useCheckout, useCart, useNymbalClient } from '@nymbalhq/react'
+import type { PaymentConfirmation } from '@nymbalhq/sdk'
+import type { NymbalPaymentElement } from '@nymbalhq/web-components'
 import { formatPrice } from '@/lib/format'
 import styles from '@/styles/pages/checkout.module.css'
 
-// The env says only whether a Stripe client exists; the payment flow follows the server's answer.
-const stripeKey = process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY ?? ''
-const isStub = process.env.NEXT_PUBLIC_NYMBAL_PAYMENTS_PROVIDER === 'native-stub' || !stripeKey
-const stripePromise = isStub ? null : loadStripe(stripeKey)
-
-import type { Address } from '@nymbalhq/types'
+import type { Address, StoreCapabilities } from '@nymbalhq/types'
 type AddressFields = Pick<
   Address,
   'firstName' | 'lastName' | 'addressLine1' | 'city' | 'region' | 'postalCode' | 'country'
@@ -159,13 +154,16 @@ function AddressFormFields({
   )
 }
 
-function CheckoutFormInner() {
+/** The checkout, given the store's capabilities as the page's server component read them. */
+export function CheckoutForm({ capabilities }: { capabilities: StoreCapabilities }) {
   const router = useRouter()
   const client = useNymbalClient()
   const checkout = useCheckout()
   const cart = useCart()
-  const stripe = useStripe()
-  const elements = useElements()
+  const paymentClient = capabilities.payments.client
+  const paymentRef = useRef<NymbalPaymentElement | null>(null)
+  // An element that cannot take a payment (an unknown driver, a form that failed to load) holds Place Order.
+  const [paymentBlocked, setPaymentBlocked] = useState(false)
 
   const [step, setStep] = useState(0)
   const [email, setEmail] = useState('')
@@ -177,6 +175,16 @@ function CheckoutFormInner() {
 
   const cartCurrency = cart.currency ?? 'GBP'
 
+  // The element renders on the payment step; its status may already be settled when this runs.
+  useEffect(() => {
+    const el = paymentRef.current
+    if (step !== 2 || el === null) return
+    const sync = () => setPaymentBlocked(el.status === 'error')
+    sync()
+    el.addEventListener('nymbal:payment:status', sync)
+    return () => el.removeEventListener('nymbal:payment:status', sync)
+  }, [step])
+
   const updateShipping = useCallback((field: keyof AddressFields, value: string) => {
     setShippingAddress((prev) => ({ ...prev, [field]: value }))
   }, [])
@@ -237,22 +245,23 @@ function CheckoutFormInner() {
   const handlePlaceOrder = useCallback(
     async (e: FormEvent) => {
       e.preventDefault()
-      if (!isStub && (!stripe || !elements)) return
+      if (paymentBlocked) return
 
       setProcessing(true)
       setError(null)
 
-      const billing = sameAsShipping ? shippingAddress : billingAddress
-      checkout.setBillingAddress({
-        firstName: billing.firstName,
-        lastName: billing.lastName,
-        addressLine1: billing.addressLine1,
-        addressLine2: billing.addressLine2 || undefined,
-        city: billing.city,
-        region: billing.region,
-        postalCode: billing.postalCode,
-        country: billing.country,
-      })
+      const fields = sameAsShipping ? shippingAddress : billingAddress
+      const billing = {
+        firstName: fields.firstName,
+        lastName: fields.lastName,
+        addressLine1: fields.addressLine1,
+        addressLine2: fields.addressLine2 || undefined,
+        city: fields.city,
+        region: fields.region,
+        postalCode: fields.postalCode,
+        country: fields.country,
+      }
+      checkout.setBillingAddress(billing)
 
       const stay = (message: string) => {
         setError(message)
@@ -274,33 +283,14 @@ function CheckoutFormInner() {
         if (result.payment.status === 'failed') {
           return stay(client.checkout.getState().error ?? 'Payment failed.')
         }
-        // Without a Stripe client (a +stub-pending order) the order page shows it awaiting payment.
-        if (result.payment.status === 'requires_action' && !isStub && stripe && elements) {
-          const cardEl = elements.getElement(CardElement)
-          if (!cardEl) return stay('Card element not found.')
-
-          const { error: stripeError } = await stripe.confirmCardPayment(
+        // Confirmed only when the driver says the payment went through; otherwise the order page shows it pending.
+        if (result.payment.status === 'requires_action') {
+          const confirmation: PaymentConfirmation = (await paymentRef.current?.confirm(
             result.paymentIntent.clientSecret,
-            {
-              payment_method: {
-                card: cardEl,
-                billing_details: {
-                  email,
-                  address: {
-                    line1: billing.addressLine1,
-                    line2: billing.addressLine2 || undefined,
-                    city: billing.city,
-                    state: billing.region,
-                    postal_code: billing.postalCode,
-                    country: billing.country,
-                  },
-                },
-              },
-            },
-          )
-
-          if (stripeError) return stay(stripeError.message ?? 'Payment failed.')
-          checkout.markConfirmed()
+            { email: email || undefined, billing },
+          )) ?? { ok: true, confirmed: false }
+          if (!confirmation.ok) return stay(confirmation.error)
+          if (confirmation.confirmed) checkout.markConfirmed()
         }
         leaveFor(result.orderNumber)
       } catch (err) {
@@ -308,8 +298,7 @@ function CheckoutFormInner() {
       }
     },
     [
-      stripe,
-      elements,
+      paymentBlocked,
       email,
       shippingAddress,
       billingAddress,
@@ -328,7 +317,7 @@ function CheckoutFormInner() {
           <p className={styles.processingText}>Processing your order...</p>
         </div>
       )}
-      {/* Hidden, not unmounted, while processing: Stripe confirms with the mounted card element. */}
+      {/* Hidden, not unmounted, while processing: the payment driver confirms with what it mounted. */}
       <div
         className={`container ${styles.page}`}
         style={processing ? { display: 'none' } : undefined}
@@ -430,34 +419,12 @@ function CheckoutFormInner() {
                   className={styles.formSection}
                   style={{ marginTop: 'var(--nymbal-spacing-lg)' }}
                 >
-                  <h2 className={styles.formSectionTitle}>Payment</h2>
-                  {isStub ? (
-                    <div className={styles.paymentElement} data-testid="card-element">
-                      <p
-                        style={{
-                          color: 'var(--nymbal-color-text-muted, #9ca3af)',
-                          fontSize: '0.875rem',
-                          margin: 0,
-                        }}
-                      >
-                        Test mode — payment skipped
-                      </p>
-                    </div>
-                  ) : (
-                    <div className={styles.paymentElement} data-testid="card-element">
-                      <CardElement
-                        options={{
-                          style: {
-                            base: {
-                              fontSize: '16px',
-                              color: '#1a1a1a',
-                              '::placeholder': { color: '#9ca3af' },
-                            },
-                          },
-                        }}
-                      />
-                    </div>
-                  )}
+                  {paymentClient !== null && <h2 className={styles.formSectionTitle}>Payment</h2>}
+                  <PaymentElement
+                    ref={paymentRef}
+                    client={paymentClient}
+                    data-testid="payment-element"
+                  />
                 </div>
 
                 <div className={styles.formActions}>
@@ -467,7 +434,7 @@ function CheckoutFormInner() {
                   <button
                     type="submit"
                     className="btn btn-primary"
-                    disabled={(!isStub && !stripe) || processing}
+                    disabled={paymentBlocked || processing}
                     data-testid="place-order"
                   >
                     Place Order
@@ -513,11 +480,3 @@ function CheckoutFormInner() {
     </>
   )
 }
-
-export function CheckoutForm() {
-  return (
-    <Elements stripe={stripePromise}>
-      <CheckoutFormInner />
-    </Elements>
-  )
-}

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

@@ -2,44 +2,35 @@
 
 import { useEffect, useState, useCallback } from 'react'
 import type { DenormalisedProduct } from '@nymbalhq/sdk'
-import type { Category, Facet, ProductSortKey } from '@nymbalhq/types'
-import { useProductList } from '@nymbalhq/react'
-import { ProductFilter } from '@nymbalhq/react'
+import type { Facet, ProductSortKey } from '@nymbalhq/types'
+import { ProductFilter, SortDropdown, useProductList } from '@nymbalhq/react'
 import { ProductCard } from '@/components/server/ProductCard'
-import { SortDropdown } from './SortDropdown'
 import styles from '@/styles/pages/plp.module.css'
 
 interface ProductGridProps {
   initialProducts: DenormalisedProduct[]
   initialCursor: string | null
   initialSort: ProductSortKey
+  /** The server-rendered listing's facets: none when the store's search cannot facet, and then no filter. */
+  initialFacets: Facet[]
+  /** The sort keys the store reports, in order, and the one it lists by when none is asked. */
+  sortKeys: ProductSortKey[]
+  defaultSort?: ProductSortKey | undefined
   categorySlug?: string
-  categories: Category[]
 }
 
 export function ProductGrid({
   initialProducts,
   initialCursor,
   initialSort,
+  initialFacets,
+  sortKeys,
+  defaultSort,
   categorySlug,
-  categories,
 }: ProductGridProps) {
-  const { products, facets, pagination, loading, sort, load, loadMore, setSort } = useProductList()
+  const { products, pagination, loading, sort, load, loadMore, setSort } = useProductList()
   const [initialized, setInitialized] = useState(false)
   const [showMobileFilters, setShowMobileFilters] = useState(false)
-  // Preserve the widest facet list seen so filter options never disappear during a
-  // filtered query (the API always returns full facets, but this guards against regressions).
-  const [stableFacets, setStableFacets] = useState<Facet[]>(
-    categories.length > 0
-      ? [
-          {
-            field: 'category',
-            label: 'Category',
-            values: categories.map((c) => ({ value: c.slug, label: c.name })),
-          },
-        ]
-      : [],
-  )
 
   useEffect(() => {
     load({ limit: 24, category: categorySlug, sort: initialSort })
@@ -48,7 +39,8 @@ export function ProductGrid({
 
   // The URL carries the sort, so a reload or a shared link renders the same order server-side.
   const handleSort = useCallback(
-    (key: ProductSortKey) => {
+    (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)
@@ -57,17 +49,6 @@ export function ProductGrid({
     [setSort],
   )
 
-  // Keep stableFacets updated whenever the store returns a wider facet list.
-  useEffect(() => {
-    if (facets.length > 0) {
-      const incomingValues = facets.reduce((acc, f) => acc + f.values.length, 0)
-      const stableValues = stableFacets.reduce((acc, f) => acc + f.values.length, 0)
-      if (incomingValues >= stableValues) {
-        setStableFacets(facets)
-      }
-    }
-  }, [facets, stableFacets])
-
   const displayProducts = initialized && products.length > 0 ? products : initialProducts
   const hasMore = initialized ? pagination.hasMore : !!initialCursor
 
@@ -77,26 +58,26 @@ export function ProductGrid({
     }
   }, [hasMore, loading, loadMore])
 
-  // Use stableFacets (which always contains the full category list) so all filter
-  // options remain visible after a category filter is applied.
-  const displayFacets = stableFacets
-
   return (
     <div className={styles.layout}>
       <aside className={styles.sidebar}>
-        <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={displayFacets} />
-        </div>
+        {initialFacets.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={initialFacets} />
+            </div>
+          </>
+        )}
       </aside>
 
       <div className={styles.content}>
@@ -104,7 +85,15 @@ export function ProductGrid({
           <span className={styles.resultCount}>
             {displayProducts.length} product{displayProducts.length !== 1 ? 's' : ''}
           </span>
-          <SortDropdown value={initialized ? sort : initialSort} onChange={handleSort} />
+          {sortKeys.length > 0 && (
+            <SortDropdown
+              className={styles.sortSelect}
+              sortKeys={sortKeys}
+              value={initialized ? sort : initialSort}
+              defaultSort={defaultSort}
+              onSortChange={handleSort}
+            />
+          )}
         </div>
 
         {displayProducts.length > 0 ? (