create-nymbal-app 0.3.0 → 0.4.0

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 ? (

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

@@ -1,7 +1,9 @@
 'use client'
 
-import type { DenormalisedProduct, DenormalisedVariant } from '@nymbalhq/sdk'
-import { useProduct, VariantSelector, AddToCart } from '@nymbalhq/react'
+import { useRef, useState } from 'react'
+import type { DenormalisedProduct } from '@nymbalhq/sdk'
+import { STOCK_LABELS, stockLevel } from '@nymbalhq/types'
+import { useProduct, VariantSelector, AddToCart, QuantitySelector } from '@nymbalhq/react'
 import { formatPrice } from '@/lib/format'
 import styles from '@/styles/pages/pdp.module.css'
 
@@ -15,18 +17,23 @@ export function ProductInteractive({ product }: ProductInteractiveProps) {
   const variant = selectedVariant ?? product.variants?.[0]
   const price = variant?.priceMinor ?? product.priceMinor ?? 0
   const currency = product.currency ?? 'GBP'
-  const stock = variant?.stock ?? (product.inStock ? 10 : 0)
+  // A product with no variants has nothing to sell, so it reads as out of stock.
+  const stock = variant?.stock ?? 0
+  const level = stockLevel(stock)
+
+  // The quantity belongs to the variant it was chosen for, so a variant change starts again at 1.
+  const [chosen, setChosen] = useState<{ variantId: string | undefined; qty: number }>({
+    variantId: variant?.id,
+    qty: 1,
+  })
+  // Reset on the change itself, so a quantity left on a variant is not there again when the shopper comes back to it.
+  if (chosen.variantId !== variant?.id) setChosen({ variantId: variant?.id, qty: 1 })
+  const qty = chosen.variantId === variant?.id ? chosen.qty : 1
+  const addToCartRef = useRef<HTMLElement>(null)
 
   // The selector derives its option groups from the product's variants.
   const hasVariantChoice = (product.variants?.length ?? 0) > 1
 
-  const handleVariantSelected = (e: CustomEvent<{ variant: unknown }>) => {
-    const v = e.detail.variant as DenormalisedVariant | undefined
-    if (v) {
-      // The product store handles variant selection internally
-    }
-  }
-
   return (
     <div>
       <h1 className={styles.productTitle} data-testid="product-title">
@@ -37,24 +44,38 @@ export function ProductInteractive({ product }: ProductInteractiveProps) {
         {formatPrice(price, currency)}
       </div>
 
-      <div className={styles.stockBadge} data-testid="stock-badge">
-        {stock === 0 ? (
-          <span style={{ color: 'var(--nymbal-color-error)' }}>Out of Stock</span>
-        ) : stock < 5 ? (
-          <span style={{ color: 'var(--nymbal-color-warning)' }}>Low Stock — {stock} left</span>
-        ) : (
-          <span style={{ color: 'var(--nymbal-color-success)' }}>In Stock</span>
-        )}
+      <div className={styles.stockBadge} data-testid="stock-badge" data-level={level}>
+        <span className={styles.stockDot} aria-hidden="true" />
+        {STOCK_LABELS[level]}
       </div>
 
       {hasVariantChoice && (
         <div className={styles.variantSection}>
-          <VariantSelector onVariantSelected={handleVariantSelected} />
+          <VariantSelector />
         </div>
       )}
 
       <div className={styles.addToCartSection}>
-        <AddToCart variantId={variant?.id ?? product.id} disabled={stock === 0} />
+        <div className={styles.quantityWrapper}>
+          <QuantitySelector
+            key={variant?.id}
+            value={1}
+            min={1}
+            max={99}
+            onQuantityChange={(e) => {
+              // A typed quantity changes on blur, and the press on Add is what blurs it: the wrapper's effect lands
+              // after a fast click has already read `qty`, so the element gets it here, in the same event.
+              addToCartRef.current?.setAttribute('qty', String(e.detail.value))
+              setChosen({ variantId: variant?.id, qty: e.detail.value })
+            }}
+          />
+        </div>
+        <AddToCart
+          ref={addToCartRef}
+          variantId={variant?.id ?? product.id}
+          qty={qty}
+          disabled={stock <= 0}
+        />
       </div>
     </div>
   )

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

@@ -1,23 +1,42 @@
 'use client'
 
-import { useEffect } from 'react'
+import { useCallback, useEffect } from 'react'
 import { useSearchParams } from 'next/navigation'
 import Link from 'next/link'
 import Image from 'next/image'
-import { useSearch } from '@nymbalhq/react'
+import { ProductFilter, useSearch } from '@nymbalhq/react'
 import { formatPrice } from '@/lib/format'
 import styles from '@/styles/pages/search.module.css'
 
 export function SearchResults() {
   const searchParams = useSearchParams()
   const query = searchParams.get('q') ?? ''
-  const { results, loading, search } = useSearch()
+  const category = searchParams.get('category')
+  const {
+    results,
+    total,
+    nextCursor,
+    facets,
+    loading,
+    query: searched,
+    category: searchedCategory,
+    search,
+    loadMore,
+  } = useSearch()
 
   useEffect(() => {
-    if (query) {
-      search(query)
+    // Runs when the URL changes; the filter has already searched the category it writes there.
+    if (query && (query !== searched || category !== searchedCategory)) {
+      void search(query, { category })
     }
-  }, [query, search])
+  }, [query, category, search])
+
+  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())
+  }, [])
 
   return (
     <div className={`container ${styles.page}`}>
@@ -30,7 +49,7 @@ export function SearchResults() {
         )}
       </div>
 
-      {loading ? (
+      {loading && results.length === 0 ? (
         <div className={styles.loading}>
           <div className="spinner spinner-lg" role="status">
             <span className="visually-hidden">Searching...</span>
@@ -57,48 +76,69 @@ export function SearchResults() {
             Use the search bar above to find what you are looking for.
           </p>
         </div>
-      ) : results && results.length > 0 ? (
-        <>
-          <p className={styles.resultCount}>
-            {results.length} result{results.length !== 1 ? 's' : ''} found
-          </p>
-          <div className={styles.grid}>
-            {results.map((product) => {
-              const media = Array.isArray(product.media) ? product.media : []
-              const imageUrl = media.length > 0 && typeof (media[0] as Record<string, unknown>)?.url === 'string'
-                ? (media[0] as Record<string, string>).url
-                : null
-              return (
-                <Link
-                  key={product.id}
-                  href={`/product/${product.slug}`}
-                  className={styles.productCard}
-                  data-testid={`product-card-${product.slug}`}
+      ) : results.length > 0 ? (
+        <div className={facets.length > 0 ? styles.layout : undefined}>
+          {facets.length > 0 && (
+            <aside className={styles.sidebar}>
+              <ProductFilter source="search" onFilterChange={onFilterChange} />
+            </aside>
+          )}
+          <div>
+            <p className={styles.resultCount} data-testid="search-total">
+              {total} result{total !== 1 ? 's' : ''} found
+            </p>
+            <div className={styles.grid}>
+              {results.map((product) => {
+                const media = Array.isArray(product.media) ? product.media : []
+                const imageUrl =
+                  media.length > 0 && typeof (media[0] as Record<string, unknown>)?.url === 'string'
+                    ? (media[0] as Record<string, string>).url
+                    : null
+                return (
+                  <Link
+                    key={product.id}
+                    href={`/product/${product.slug}`}
+                    className={styles.productCard}
+                    data-testid={`product-card-${product.slug}`}
+                  >
+                    <div className={styles.productImage}>
+                      {imageUrl && (
+                        <Image
+                          src={imageUrl}
+                          alt={product.name}
+                          width={400}
+                          height={400}
+                          sizes="(max-width: 639px) 100vw, (max-width: 1023px) 50vw, 25vw"
+                        />
+                      )}
+                    </div>
+                    <div className={styles.productInfo}>
+                      <p className={styles.productName}>{product.name}</p>
+                      {product.priceMinor != null && product.currency && (
+                        <p className={styles.productPrice}>
+                          {formatPrice(product.priceMinor, product.currency)}
+                        </p>
+                      )}
+                    </div>
+                  </Link>
+                )
+              })}
+            </div>
+            {nextCursor !== null && (
+              <div className={styles.pagination}>
+                <button
+                  type="button"
+                  className="btn btn-secondary"
+                  onClick={() => void loadMore()}
+                  disabled={loading}
+                  data-testid="search-load-more"
                 >
-                  <div className={styles.productImage}>
-                    {imageUrl && (
-                      <Image
-                        src={imageUrl}
-                        alt={product.name}
-                        width={400}
-                        height={400}
-                        sizes="(max-width: 639px) 100vw, (max-width: 1023px) 50vw, 25vw"
-                      />
-                    )}
-                  </div>
-                  <div className={styles.productInfo}>
-                    <p className={styles.productName}>{product.name}</p>
-                    {product.priceMinor != null && product.currency && (
-                      <p className={styles.productPrice}>
-                        {formatPrice(product.priceMinor, product.currency)}
-                      </p>
-                    )}
-                  </div>
-                </Link>
-              )
-            })}
+                  {loading ? 'Loading...' : 'Load more'}
+                </button>
+              </div>
+            )}
           </div>
-        </>
+        </div>
       ) : (
         <div className={styles.empty}>
           <div className={styles.emptyIcon}>

package/scaffold/templates/nextjs/components/server/Header.tsx

@@ -1,6 +1,7 @@
 import Link from 'next/link'
 import { SearchBarWrapper } from '@/components/client/SearchBarWrapper'
 import { MiniCartWrapper } from '@/components/client/MiniCartWrapper'
+import { fetchCapabilities } from '@/lib/api'
 import styles from './Header.module.css'
 
 const NAV_LINKS = [
@@ -9,7 +10,9 @@ const NAV_LINKS = [
   { href: '/products?category=sale', label: 'Sale' },
 ]
 
-export function Header() {
+export async function Header() {
+  const capabilities = await fetchCapabilities()
+  const canSearch = capabilities?.search.capabilities.includes('search') ?? false
   return (
     <header className={styles.header} data-testid="site-header">
       <div className={`container ${styles.inner}`}>
@@ -30,9 +33,11 @@ export function Header() {
         </nav>
 
         <div className={styles.actions}>
-          <div className={styles.search}>
-            <SearchBarWrapper />
-          </div>
+          {canSearch && (
+            <div className={styles.search}>
+              <SearchBarWrapper />
+            </div>
+          )}
           <Link href="/account" className={styles.iconLink} aria-label="Account">
             <svg
               width="20"