create-nymbal-app 0.2.0 → 0.4.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"

package/scaffold/templates/nextjs/lib/api.ts

@@ -1,6 +1,7 @@
+import { unstable_rethrow } from 'next/navigation'
 import type { DenormalisedProduct, ProductListResult, ReviewsListResult } from '@nymbalhq/sdk'
 import { DEFAULT_PRODUCT_SORT, PRODUCT_SORT_KEYS } from '@nymbalhq/types'
-import type { Category, Order, ProductSortKey } from '@nymbalhq/types'
+import type { Category, Order, ProductSortKey, StoreCapabilities } from '@nymbalhq/types'
 
 const API_URL = process.env.NYMBAL_API_URL ?? 'http://localhost:3001'
 
@@ -27,10 +28,29 @@ export async function fetchProducts(params?: {
   }
 }
 
-/** The sort a listing URL asks for; a missing or unknown `?sort=` is the default. */
-export function sortFromSearchParams(params: { sort?: string | string[] }): ProductSortKey {
+/** What the store can do, which decides what the page renders; null when the API did not answer. */
+export async function fetchCapabilities(): Promise<StoreCapabilities | null> {
+  try {
+    const res = await fetch(`${API_URL}/api/capabilities`, { cache: 'no-store' })
+    if (!res.ok) return null
+    const envelope = (await res.json()) as { data: StoreCapabilities }
+    return envelope.data ?? null
+  } catch (err) {
+    // Next signals a request-time render by throwing from fetch at build; that must reach Next, not become null.
+    unstable_rethrow(err)
+    console.error('[api] fetchCapabilities failed', err)
+    return null
+  }
+}
+
+/** The sort a listing URL asks for, among the store's keys; a missing or unknown `?sort=` is the store's default. */
+export function sortFromSearchParams(
+  params: { sort?: string | string[] },
+  catalog?: StoreCapabilities['catalog'],
+): ProductSortKey {
   const sort = Array.isArray(params.sort) ? params.sort[0] : params.sort
-  return PRODUCT_SORT_KEYS.find((key) => key === sort) ?? DEFAULT_PRODUCT_SORT
+  const keys = catalog?.sortKeys ?? PRODUCT_SORT_KEYS
+  return keys.find((key) => key === sort) ?? catalog?.defaultSort ?? DEFAULT_PRODUCT_SORT
 }
 
 export async function fetchProduct(slug: string): Promise<DenormalisedProduct | null> {

package/scaffold/templates/nextjs/lib/client.ts

@@ -1,5 +1,8 @@
 import { createNymbalClient, type NymbalClient } from '@nymbalhq/sdk'
 
+// A payment driver of the project's own is registered here, at module load, before any checkout renders:
+// registerPaymentDriver(name, driver) from @nymbalhq/sdk, named by the driver of the payments adapter's client half.
+
 let instance: NymbalClient | null = null
 let restoring: Promise<void> | null = null
 

package/scaffold/templates/nextjs/package.json

@@ -17,19 +17,17 @@
     "seed": "nymbal seed"
   },
   "dependencies": {
-    "nymbal": "0.2.0",
-    "@nymbalhq/config": "0.2.0",
-    "@nymbalhq/platform": "0.2.0",
-    "@nymbalhq/stack": "0.2.0",
+    "nymbal": "1.1.0",
+    "@nymbalhq/config": "1.1.0",
+    "@nymbalhq/platform": "1.1.0",
+    "@nymbalhq/stack": "1.1.0",
     "next": "^16.4.2",
     "react": "^19.3.1",
     "react-dom": "^19.3.1",
-    "@nymbalhq/sdk": "0.2.0",
-    "@nymbalhq/react": "0.2.0",
-    "@nymbalhq/web-components": "0.2.0",
-    "@nymbalhq/types": "0.2.0",
-    "@stripe/stripe-js": "^4.0.0",
-    "@stripe/react-stripe-js": "^3.0.0"
+    "@nymbalhq/sdk": "1.1.0",
+    "@nymbalhq/react": "1.1.0",
+    "@nymbalhq/web-components": "1.1.0",
+    "@nymbalhq/types": "1.1.0"
   },
   "devDependencies": {
     "@types/node": "^22.9.0",
@@ -39,26 +37,26 @@
   },
   "pnpm": {
     "overrides": {
-      "nymbal": "0.2.0",
-      "@nymbalhq/config": "0.2.0",
-      "@nymbalhq/http": "0.2.0",
-      "@nymbalhq/platform": "0.2.0",
-      "@nymbalhq/react": "0.2.0",
-      "@nymbalhq/sdk": "0.2.0",
-      "@nymbalhq/stack": "0.2.0",
-      "@nymbalhq/types": "0.2.0",
-      "@nymbalhq/web-components": "0.2.0"
+      "nymbal": "1.1.0",
+      "@nymbalhq/config": "1.1.0",
+      "@nymbalhq/http": "1.1.0",
+      "@nymbalhq/platform": "1.1.0",
+      "@nymbalhq/react": "1.1.0",
+      "@nymbalhq/sdk": "1.1.0",
+      "@nymbalhq/stack": "1.1.0",
+      "@nymbalhq/types": "1.1.0",
+      "@nymbalhq/web-components": "1.1.0"
     }
   },
   "overrides": {
-    "nymbal": "0.2.0",
-    "@nymbalhq/config": "0.2.0",
-    "@nymbalhq/http": "0.2.0",
-    "@nymbalhq/platform": "0.2.0",
-    "@nymbalhq/react": "0.2.0",
-    "@nymbalhq/sdk": "0.2.0",
-    "@nymbalhq/stack": "0.2.0",
-    "@nymbalhq/types": "0.2.0",
-    "@nymbalhq/web-components": "0.2.0"
+    "nymbal": "1.1.0",
+    "@nymbalhq/config": "1.1.0",
+    "@nymbalhq/http": "1.1.0",
+    "@nymbalhq/platform": "1.1.0",
+    "@nymbalhq/react": "1.1.0",
+    "@nymbalhq/sdk": "1.1.0",
+    "@nymbalhq/stack": "1.1.0",
+    "@nymbalhq/types": "1.1.0",
+    "@nymbalhq/web-components": "1.1.0"
   }
 }

package/scaffold/templates/nextjs/styles/pages/pdp.module.css

@@ -148,12 +148,16 @@
   margin-bottom: var(--nymbal-spacing-md);
 }
 
-.inStock {
+.stockBadge[data-level='in'] {
   background-color: #dcfce7;
   color: var(--nymbal-color-success);
 }
 
-.outOfStock {
+.stockBadge[data-level='low'] {
+  color: var(--nymbal-color-warning);
+}
+
+.stockBadge[data-level='out'] {
   background-color: #fef2f2;
   color: var(--nymbal-color-error);
 }

package/scaffold/templates/nextjs/styles/pages/plp.module.css

@@ -118,7 +118,8 @@
   color: var(--nymbal-color-text-muted);
 }
 
-.sortSelect {
+/* The sort element renders the select. */
+.sortSelect select {
   padding: 0.5rem 0.75rem;
   font-size: var(--nymbal-font-size-sm);
   border: 1px solid var(--nymbal-color-border);
@@ -129,7 +130,7 @@
   min-width: 10rem;
 }
 
-.sortSelect:focus {
+.sortSelect select:focus {
   outline: none;
   border-color: var(--nymbal-color-accent);
   box-shadow: 0 0 0 3px rgba(37, 99, 235, 0.15);

package/scaffold/templates/nextjs/styles/pages/search.module.css

@@ -143,6 +143,30 @@
   margin-inline: auto;
 }
 
+/* ── Category filter and load more ───────────────────────────────── */
+
+.layout {
+  display: grid;
+  grid-template-columns: 1fr;
+  gap: var(--nymbal-spacing-lg);
+}
+
+@media (min-width: 769px) {
+  .layout {
+    grid-template-columns: 240px minmax(0, 1fr);
+  }
+}
+
+.sidebar {
+  align-self: start;
+}
+
+.pagination {
+  display: flex;
+  justify-content: center;
+  margin-top: var(--nymbal-spacing-xl);
+}
+
 /* ── Loading ──────────────────────────────────────────────────────── */
 
 .loading {

package/scaffold/templates/astro/src/components/SortDropdown.astro

@@ -1,26 +0,0 @@
----
-import type { ProductSortKey } from '@nymbalhq/types'
-
-interface Props {
-  sort: ProductSortKey
-}
-
-const { sort } = Astro.props
-
-const OPTIONS: Array<{ value: ProductSortKey; label: string }> = [
-  { value: 'newest', label: 'Newest' },
-  { value: 'price-asc', label: 'Price: Low to High' },
-  { value: 'price-desc', label: 'Price: High to Low' },
-  { value: 'name-asc', label: 'Name: A to Z' },
-  { value: 'name-desc', label: 'Name: Z to A' },
-]
----
-
-<div class="plp-sort-bar">
-  <label for="sort-select">Sort by</label>
-  <select id="sort-select" data-testid="sort-dropdown">
-    {OPTIONS.map((option) => (
-      <option value={option.value} selected={option.value === sort}>{option.label}</option>
-    ))}
-  </select>
-</div>

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

@@ -1,35 +0,0 @@
-'use client'
-
-import type { ProductSortKey } from '@nymbalhq/types'
-import styles from '@/styles/pages/plp.module.css'
-
-const OPTIONS: Array<{ value: ProductSortKey; label: string }> = [
-  { value: 'newest', label: 'Newest' },
-  { value: 'price-asc', label: 'Price: Low to High' },
-  { value: 'price-desc', label: 'Price: High to Low' },
-  { value: 'name-asc', label: 'Name: A to Z' },
-  { value: 'name-desc', label: 'Name: Z to A' },
-]
-
-interface SortDropdownProps {
-  value: ProductSortKey
-  onChange: (sort: ProductSortKey) => void
-}
-
-export function SortDropdown({ value, onChange }: SortDropdownProps) {
-  return (
-    <select
-      className={styles.sortSelect}
-      value={value}
-      onChange={(e) => onChange(e.target.value as ProductSortKey)}
-      data-testid="sort-dropdown"
-      aria-label="Sort products"
-    >
-      {OPTIONS.map((option) => (
-        <option key={option.value} value={option.value}>
-          {option.label}
-        </option>
-      ))}
-    </select>
-  )
-}

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

@@ -1,19 +0,0 @@
-import styles from '@/styles/pages/pdp.module.css'
-
-interface StockBadgeProps {
-  stock: number
-}
-
-export function StockBadge({ stock }: StockBadgeProps) {
-  const inStock = stock > 0
-
-  return (
-    <span
-      className={`${styles.stockBadge} ${inStock ? styles.inStock : styles.outOfStock}`}
-      data-testid="stock-badge"
-    >
-      <span className={styles.stockDot} aria-hidden="true" />
-      {inStock ? (stock <= 5 ? `Only ${stock} left` : 'In Stock') : 'Out of Stock'}
-    </span>
-  )
-}