create-nymbal-app 0.3.0 → 0.5.0

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

@@ -1,13 +1,8 @@
 ---
 import '../../styles/pages/pdp.css'
 import BaseLayout from '../../layouts/BaseLayout.astro'
-import Breadcrumb from '../../components/Breadcrumb.astro'
-import ImageGallery from '../../components/ImageGallery.astro'
-import PriceDisplay from '../../components/PriceDisplay.astro'
-import StockBadge from '../../components/StockBadge.astro'
-import ReviewList from '../../components/ReviewList.astro'
-import ReviewForm from '../../components/ReviewForm.astro'
-import RelatedProducts from '../../components/RelatedProducts.astro'
+import NymbalElement from '@nymbalhq/web-components/astro'
+import { cardProductOf } from '@nymbalhq/web-components/ssr'
 import { fetchProduct, fetchReviews, fetchProducts } from '../../lib/api'
 import { productJsonLd, breadcrumbJsonLd } from '../../lib/seo'
 
@@ -20,7 +15,7 @@ const [reviewsResult, relatedResult] = await Promise.all([
   fetchReviews(product.id),
   fetchProducts({
     limit: 4,
-    category: product.categoryIds?.[0] ?? undefined,
+    category: product.categories?.[0]?.slug,
   }),
 ])
 
@@ -35,7 +30,8 @@ const images = Array.isArray(product.media) && product.media.length > 0
   : [{ url: `https://picsum.photos/seed/${product.slug}/600/600`, alt: product.name }]
 
 const defaultVariant = product.variants?.[0]
-const stock = defaultVariant?.stock ?? (product.inStock ? 10 : 0)
+// A product with no variants has nothing to sell, so it reads as out of stock.
+const stock = defaultVariant?.stock ?? 0
 
 const jsonLd = productJsonLd(product, Astro.url.origin)
 const breadcrumb = breadcrumbJsonLd([
@@ -49,38 +45,51 @@ const hasVariantChoice = (product.variants?.length ?? 0) > 1
 ---
 
 <BaseLayout title={`${product.name} | Nymbal`} description={product.shortDescription ?? product.description ?? ''} jsonLd={jsonLd}>
+  <!-- The gallery's main image is the page's LCP: the browser starts it before it parses the body. -->
+  <link slot="head" rel="preload" as="image" href={images[0]!.url} fetchpriority="high" />
   <div class="container section" data-product-slug={product.slug}>
-    <Breadcrumb
-      items={[
-        { label: 'Home', href: '/' },
-        { label: 'Products', href: '/products' },
-        { label: product.name },
-      ]}
+    <NymbalElement
+      tag="nymbal-breadcrumb"
+      attributes={{
+        items: JSON.stringify([
+          { label: 'Home', href: '/' },
+          { label: 'Products', href: '/products' },
+          { label: product.name },
+        ]),
+      }}
     />
 
     <div class="pdp-layout">
-      <ImageGallery images={images} />
+      <NymbalElement tag="nymbal-image-gallery" attributes={{ class: 'pdp-gallery', images: JSON.stringify(images) }} />
 
       <div class="pdp-info">
         <h1 class="pdp-title" data-testid="product-title">{product.name}</h1>
 
-        <PriceDisplay
-          priceMinor={defaultVariant?.priceMinor ?? product.priceMinor}
-          currency={product.currency ?? 'GBP'}
+        <NymbalElement
+          tag="nymbal-product-price"
+          attributes={{
+            'product-id': product.id,
+            'price-minor': String(defaultVariant?.priceMinor ?? product.priceMinor ?? 0),
+            currency: product.currency ?? 'GBP',
+          }}
         />
-
-        <StockBadge stock={stock} />
+        <NymbalElement tag="nymbal-stock-badge" attributes={{ 'product-id': product.id, stock: String(stock) }} />
 
         <div class="pdp-actions">
           {hasVariantChoice && (
-            <nymbal-variant-selector></nymbal-variant-selector>
+            <NymbalElement tag="nymbal-variant-selector" attributes={{ product: JSON.stringify(product) }} />
           )}
 
           <div class="pdp-add-row">
-            <nymbal-quantity-selector value="1" min="1" max="99"></nymbal-quantity-selector>
-            <nymbal-add-to-cart
-              variant-id={defaultVariant?.id ?? product.id}
-            ></nymbal-add-to-cart>
+            <NymbalElement tag="nymbal-quantity-selector" attributes={{ value: '1', min: '1', max: '99' }} />
+            <NymbalElement
+              tag="nymbal-add-to-cart"
+              attributes={{
+                'variant-id': defaultVariant?.id ?? product.id,
+                qty: '1',
+                ...(stock <= 0 && { disabled: '' }),
+              }}
+            />
           </div>
         </div>
 
@@ -94,11 +103,19 @@ const hasVariantChoice = (product.variants?.length ?? 0) > 1
 
     <section class="pdp-reviews">
       <h2 class="pdp-reviews-title">Customer Reviews</h2>
-      <ReviewList reviews={reviews} />
-      <ReviewForm productId={product.id} />
+      <NymbalElement tag="nymbal-review-list" attributes={{ reviews: JSON.stringify(reviews) }} />
+      <NymbalElement tag="nymbal-review-form" attributes={{ class: 'pdp-review-form', 'product-id': product.id }} />
     </section>
 
-    <RelatedProducts products={relatedProducts} />
+    {relatedProducts.length > 0 && (
+      <section class="section">
+        <h2 class="section-title">You may also like</h2>
+        <NymbalElement
+          tag="nymbal-product-grid"
+          attributes={{ products: JSON.stringify(relatedProducts.map(cardProductOf)), lazy: '' }}
+        />
+      </section>
+    )}
   </div>
 </BaseLayout>
 

package/scaffold/templates/astro/src/pages/products/index.astro

@@ -1,57 +1,71 @@
 ---
 import '../../styles/pages/plp.css'
-import '../../styles/pages/home.css'
 import BaseLayout from '../../layouts/BaseLayout.astro'
-import Breadcrumb from '../../components/Breadcrumb.astro'
-import ProductCard from '../../components/ProductCard.astro'
-import SortDropdown from '../../components/SortDropdown.astro'
-import Pagination from '../../components/Pagination.astro'
-import { fetchProducts, fetchCategories, sortFromUrl } from '../../lib/api'
+import NymbalElement from '@nymbalhq/web-components/astro'
+import { cardImageOf, cardProductOf } from '@nymbalhq/web-components/ssr'
+import { PRODUCT_SORT_LABELS } from '@nymbalhq/types'
+import { fetchProducts, fetchCategories, fetchCapabilities, sortFromUrl } from '../../lib/api'
 
-const sort = sortFromUrl(Astro.url)
+const capabilities = await fetchCapabilities()
+const sortKeys = capabilities?.catalog.sortKeys ?? []
+const sort = sortFromUrl(Astro.url, capabilities?.catalog)
 
 const [productResult, categories] = await Promise.all([
   fetchProducts({ limit: 24, sort }),
   fetchCategories(),
 ])
 
-const products = productResult.items
+const products = productResult.items.map(cardProductOf)
+// The first card's image is the page's LCP, and the preload scanner never reaches it inside the grid's shadow root:
+// the head starts it.
+const firstImage = products[0] === undefined ? null : cardImageOf(products[0]).url
 const facets = productResult.facets ?? []
 ---
 
 <BaseLayout title="All Products | Nymbal" description="Browse our full product collection.">
+  {firstImage && <link slot="head" rel="preload" as="image" href={firstImage} fetchpriority="high" />}
   <div class="container section">
-    <Breadcrumb items={[{ label: 'Home', href: '/' }, { label: 'Products' }]} />
+    <NymbalElement tag="nymbal-breadcrumb" attributes={{ items: JSON.stringify([{ label: 'Home', href: '/' }, { label: 'Products' }]) }} />
 
     <div class="plp-header">
       <h1 class="plp-title">All Products</h1>
-      <p class="plp-count" id="product-count">{products.length} products</p>
     </div>
 
     <div class="plp-layout">
       <aside class="plp-sidebar">
-        <nymbal-product-filter
-          facets={JSON.stringify(facets)}
-        ></nymbal-product-filter>
+        {facets.length > 0 && (
+          <nymbal-product-filter
+            facets={JSON.stringify(facets)}
+          ></nymbal-product-filter>
+        )}
       </aside>
 
       <div class="plp-grid-area">
-        <SortDropdown sort={sort} />
-
-        <div class="product-grid" id="product-grid">
-          {products.map((product) => (
-            <ProductCard product={product} />
-          ))}
-        </div>
-
-        {products.length === 0 && (
-          <div class="plp-empty">
-            <h2 class="plp-empty-title">No products found</h2>
-            <p class="plp-empty-text">Try adjusting your filters.</p>
+        {sortKeys.length > 0 && (
+          <div class="plp-sort-bar">
+            <label for="sort-select">Sort by</label>
+            <nymbal-sort-dropdown
+              sort-keys={JSON.stringify(sortKeys)}
+              value={sort}
+              default-sort={capabilities?.catalog.defaultSort}
+            >
+              <select id="sort-select" data-testid="sort-dropdown">
+                {sortKeys.map((key) => (
+                  <option value={key} selected={key === sort}>{PRODUCT_SORT_LABELS[key]}</option>
+                ))}
+              </select>
+            </nymbal-sort-dropdown>
           </div>
         )}
 
-        <Pagination />
+        <NymbalElement
+          tag="nymbal-product-grid"
+          attributes={{
+            products: JSON.stringify(products),
+            source: 'product-list',
+            ...(productResult.nextCursor !== null && { 'has-more': '' }),
+          }}
+        />
       </div>
     </div>
   </div>

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

@@ -1,7 +1,14 @@
 ---
 import '../styles/pages/search.css'
-import '../styles/pages/home.css'
+import NymbalElement from '@nymbalhq/web-components/astro'
 import BaseLayout from '../layouts/BaseLayout.astro'
+import { fetchSearch } from '../lib/api'
+
+const q = Astro.url.searchParams.get('q')?.trim() ?? ''
+const search = q === '' ? null : await fetchSearch(q, Astro.url.searchParams.get('category'))
+// The results the page's search would show, so they are in the HTML; the search store takes over once it answers.
+const results: Record<string, string> =
+  search === null ? {} : { results: JSON.stringify(search.items), query: q }
 ---
 
 <BaseLayout title="Search | Nymbal" description="Search our product catalogue.">
@@ -21,13 +28,11 @@ import BaseLayout from '../layouts/BaseLayout.astro'
   </div>
 
   <div class="container section">
-    <p class="search-query-label" id="search-query-label" style="display:none; margin-bottom: var(--nymbal-spacing-md, 1rem);"></p>
-    <div id="search-results" data-testid="search-results">
-      <div class="search-empty">
-        <div class="search-empty-icon" aria-hidden="true">&#128269;</div>
-        <h2 class="search-empty-title">Search our store</h2>
-        <p class="search-empty-text">Type a keyword to find products.</p>
-      </div>
+    <div class="search-layout">
+      <aside class="search-sidebar">
+        <nymbal-product-filter source="search" empty></nymbal-product-filter>
+      </aside>
+      <NymbalElement tag="nymbal-search-results" attributes={{ 'data-testid': 'search-results', ...results }} />
     </div>
   </div>
 </BaseLayout>

package/scaffold/templates/astro/src/scripts/init-client.ts

@@ -1,4 +1,18 @@
 import '../lib/client.js'
+import { NymbalCartDrawer } from '@nymbalhq/web-components/elements/nymbal-cart-drawer'
+import { NymbalMiniCart } from '@nymbalhq/web-components/elements/nymbal-mini-cart'
+import { NymbalSearchBar } from '@nymbalhq/web-components/elements/nymbal-search-bar'
+import { NymbalSiteFooter } from '@nymbalhq/web-components/elements/nymbal-site-footer'
+import { NymbalSiteHeader } from '@nymbalhq/web-components/elements/nymbal-site-header'
+import { NymbalToast } from '@nymbalhq/web-components/elements/nymbal-toast'
+
+// The layout's elements; each page script defines the ones its page renders.
+NymbalSiteHeader.define()
+NymbalSiteFooter.define()
+NymbalSearchBar.define()
+NymbalMiniCart.define()
+NymbalCartDrawer.define()
+NymbalToast.define()
 
 // Navigate to checkout when the cart drawer checkout button is clicked
 document.addEventListener('nymbal:cart:checkout-clicked', () => {

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

@@ -1,67 +1,61 @@
+import { NymbalAddToCart } from '@nymbalhq/web-components/elements/nymbal-add-to-cart'
+import { NymbalBreadcrumb } from '@nymbalhq/web-components/elements/nymbal-breadcrumb'
+import { NymbalImageGallery } from '@nymbalhq/web-components/elements/nymbal-image-gallery'
+import { NymbalProductGrid } from '@nymbalhq/web-components/elements/nymbal-product-grid'
+import { NymbalProductPrice } from '@nymbalhq/web-components/elements/nymbal-product-price'
+import { NymbalQuantitySelector } from '@nymbalhq/web-components/elements/nymbal-quantity-selector'
+import { NymbalReviewForm } from '@nymbalhq/web-components/elements/nymbal-review-form'
+import { NymbalReviewList } from '@nymbalhq/web-components/elements/nymbal-review-list'
+import { NymbalStockBadge } from '@nymbalhq/web-components/elements/nymbal-stock-badge'
+import { NymbalVariantSelector } from '@nymbalhq/web-components/elements/nymbal-variant-selector'
 import { client } from '../lib/client.js'
-import { formatPrice } from '../lib/format.js'
 
-const slug = document.querySelector<HTMLElement>('[data-product-slug]')?.dataset.productSlug
-
-if (slug) {
-  client.product.loadBySlug(slug)
+NymbalBreadcrumb.define()
+NymbalImageGallery.define()
+NymbalProductPrice.define()
+NymbalStockBadge.define()
+NymbalVariantSelector.define()
+NymbalQuantitySelector.define()
+NymbalAddToCart.define()
+NymbalReviewList.define()
+NymbalReviewForm.define()
+// The related grid is there only when the product has relations.
+if (document.querySelector('nymbal-product-grid') !== null) NymbalProductGrid.define()
 
-  client.product.subscribe(() => {
-    const state = client.product.getState()
-    if (!state.product) return
+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')
 
-    const product = state.product
-    const selectedVariant = state.selectedVariant ?? product.variants?.[0]
+function setQuantity(qty: number): void {
+  quantity?.setAttribute('value', String(qty))
+  addToCart?.setAttribute('qty', String(qty))
+}
 
-    // Update price display
-    const priceEl = document.querySelector('[data-testid="product-price"]')
-    if (priceEl && selectedVariant) {
-      const price = formatPrice(
-        selectedVariant.priceMinor ?? product.priceMinor,
-        product.currency ?? 'GBP',
-      )
-      priceEl.innerHTML = `<span>${price}</span>`
-    }
+if (slug) {
+  // The server rendered variants[0]; a change from it resets the quantity.
+  let shownVariantId = addToCart?.getAttribute('variant-id') ?? null
 
-    // 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
+  addRow?.addEventListener('nymbal:quantity:changed', ((e: CustomEvent<{ value: number }>) => {
+    addToCart?.setAttribute('qty', String(e.detail.value))
+  }) as EventListener)
 
-      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'
-      }
+  // The price and the stock badge follow the store themselves; the add row is the page's.
+  client.product.subscribe(() => {
+    const { product, selectedVariant } = client.product.getState()
+    if (!product) return
+    const variant = selectedVariant ?? product.variants?.[0]
 
-      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', (variant.stock ?? 0) <= 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

@@ -1,109 +1,32 @@
 import type { ProductSortKey } from '@nymbalhq/types'
+import { NymbalBreadcrumb } from '@nymbalhq/web-components/elements/nymbal-breadcrumb'
+import { NymbalProductFilter } from '@nymbalhq/web-components/elements/nymbal-product-filter'
+import { NymbalProductGrid } from '@nymbalhq/web-components/elements/nymbal-product-grid'
+import { NymbalSortDropdown } from '@nymbalhq/web-components/elements/nymbal-sort-dropdown'
 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 loadMoreBtn = document.getElementById('load-more-btn')
-const countEl = document.getElementById('product-count')
+NymbalBreadcrumb.define()
+NymbalProductFilter.define()
+NymbalSortDropdown.define()
+NymbalProductGrid.define()
 
-// 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.
-const urlParams = new URLSearchParams(window.location.search)
-const initialCategory = gridContainer?.dataset.category ?? urlParams.get('category') ?? undefined
-const initialSort = (sortSelect?.value ?? 'newest') as ProductSortKey
-
-function renderProductCard(product: any): string {
-  const imageUrl =
-    product.imageUrl ??
-    (Array.isArray(product.media) && product.media[0]?.url) ??
-    `https://picsum.photos/seed/${product.slug}/600/600`
-  // The "from" price, which the price sorts order by.
-  const fromMinor = product.priceRange?.minMinor ?? product.priceMinor
-  const price = fromMinor != null ? formatPrice(fromMinor, product.currency ?? 'GBP') : ''
-
-  const slug = escapeHtml(product.slug)
-  const name = escapeHtml(product.name)
-
-  return `
-    <a href="/product/${slug}" class="product-card" data-testid="product-card-${slug}">
-      <img
-        src="${escapeHtml(imageUrl)}"
-        alt="${name}"
-        class="product-card-image"
-        loading="lazy"
-        width="600"
-        height="600"
-      />
-      <div class="product-card-body">
-        <span class="product-card-name">${name}</span>
-        ${price ? `<span class="product-card-price">${escapeHtml(price)}</span>` : ''}
-      </div>
-    </a>
-  `
-}
-
-function renderGrid() {
-  const state = client.productList.getState()
-  const products = state.products ?? []
-
-  if (!gridContainer) return
-
-  // Don't overwrite the grid with an empty state while a load is in flight.
-  // This prevents the SSR content from being replaced by "No products found"
-  // during the brief window between applyFilter setting filters and the API
-  // responding with the filtered set.
-  if (products.length === 0 && state.loading) return
-
-  if (products.length === 0) {
-    gridContainer.innerHTML = `
-      <div class="plp-empty">
-        <h2 class="plp-empty-title">No products found</h2>
-        <p class="plp-empty-text">Try adjusting your filters or search terms.</p>
-      </div>
-    `
-  } else {
-    gridContainer.innerHTML = products.map(renderProductCard).join('')
-  }
-
-  // Update count
-  if (countEl) {
-    countEl.textContent = `${products.length} product${products.length === 1 ? '' : 's'}`
-  }
-
-  // Toggle load more
-  if (loadMoreBtn) {
-    loadMoreBtn.style.display = state.pagination.hasMore ? '' : 'none'
-  }
-}
-
-// The first load's own answer is the server-rendered grid, so it is not re-rendered: subscribing after it keeps the
-// subscription to re-renders (sort, filter, load-more). A sort or filter chosen while it was in flight reached the
-// store with nothing subscribed, so that state is rendered here.
-async function init() {
-  await client.productList.load({ limit: 24, category: initialCategory, sort: initialSort })
-  client.productList.subscribe(renderGrid)
-  const state = client.productList.getState()
-  const filters = Object.entries(state.filters)
-  const changed =
-    state.sort !== initialSort ||
-    filters.length !== (initialCategory === undefined ? 0 : 1) ||
-    filters.some(([name, value]) => name !== 'category' || value !== initialCategory)
-  if (state.loading || changed) renderGrid()
-}
-
-void init()
+const grid = document.querySelector<HTMLElement>('nymbal-product-grid')
+const sortDropdown = document.querySelector('nymbal-sort-dropdown')
 
+// 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 puts the sort it resolved from the URL on the dropdown's `value`. The grid shows
+// the server's page until this load settles, then follows the store (sort, filter, load more).
+const initialCategory =
+  grid?.dataset.category ?? new URLSearchParams(window.location.search).get('category') ?? undefined
+const initialSort = (sortDropdown?.getAttribute('value') || 'newest') as ProductSortKey
+void client.productList.load({ limit: 24, category: initialCategory, sort: initialSort })
+
+// 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)
   void client.productList.setSort(sort)
 })
-
-// Load more handler
-loadMoreBtn?.addEventListener('click', () => {
-  client.productList.loadMore()
-})