create-brainerce-store 1.36.0 → 1.37.0

package/dist/index.js

@@ -31,7 +31,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "create-brainerce-store",
-      version: "1.36.0",
+      version: "1.37.0",
       description: "Scaffold a production-ready e-commerce storefront connected to Brainerce",
       bin: {
         "create-brainerce-store": "dist/index.js"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-brainerce-store",
-  "version": "1.36.0",
+  "version": "1.37.0",
   "description": "Scaffold a production-ready e-commerce storefront connected to Brainerce",
   "bin": {
     "create-brainerce-store": "dist/index.js"

package/templates/nextjs/base/src/app/products/page.tsx

@@ -1,10 +1,9 @@
 'use client';
 
-import { Suspense, useEffect, useState, useCallback, useRef } from 'react';
+import { Suspense, useEffect, useMemo, useState, useCallback, useRef } from 'react';
 import { useSearchParams } from 'next/navigation';
 import { useRouter } from '@/lib/navigation';
-import type { Product } from 'brainerce';
-import type { ProductQueryParams } from 'brainerce';
+import type { Product, ProductQueryParams, PublicMetafieldDefinition } from 'brainerce';
 import { getClient } from '@/lib/brainerce';
 import { ProductGrid } from '@/components/products/product-grid';
 import { LoadingSpinner } from '@/components/shared/loading-spinner';
@@ -13,6 +12,18 @@ import { cn } from '@/lib/utils';
 
 const PAGE_SIZE = 20;
 
+/**
+ * Metafield (custom-field) values are passed in the URL as `mf_<key>=v1,v2`
+ * for readability (no JSON encoding). The SDK assembles them back into
+ * `{ [key]: string[] }` before calling `client.getProducts`.
+ *
+ * Only definitions with `filterable: true` of type SELECT / MULTI_SELECT /
+ * BOOLEAN are honored server-side — the storefront renders facets only for
+ * those.
+ */
+const METAFIELD_URL_PREFIX = 'mf_';
+const FILTERABLE_TYPES = new Set(['SELECT', 'MULTI_SELECT', 'BOOLEAN']);
+
 type SortOption = {
   labelKey: 'sortNewest' | 'sortNameAZ' | 'sortNameZA' | 'sortPriceLow' | 'sortPriceHigh';
   sortBy: ProductQueryParams['sortBy'];
@@ -239,26 +250,52 @@ function ProductsContent() {
   const [categories, setCategories] = useState<CategoryNode[]>([]);
   const [brands, setBrands] = useState<Array<{ id: string; name: string }>>([]);
   const [tags, setTags] = useState<Array<{ id: string; name: string }>>([]);
+  const [metafieldDefs, setMetafieldDefs] = useState<PublicMetafieldDefinition[]>([]);
 
   const sortIndex = parseInt(sortParam, 10) || 0;
   const currentSort = sortOptions[sortIndex] || sortOptions[0];
 
-  // Load categories, brands, and tags
+  // Load categories, brands, tags, and metafield definitions (for custom-field facets).
+  // The metafield-definitions endpoint already returns only definitions
+  // published to this sales channel; we filter client-side to the ones flagged
+  // `filterable: true` and of a UI-renderable type.
   useEffect(() => {
     async function loadFilters() {
       const client = getClient();
-      const [catRes, brandRes, tagRes] = await Promise.allSettled([
+      const [catRes, brandRes, tagRes, mfRes] = await Promise.allSettled([
         client.getCategories(),
         client.getBrands(),
         client.getTags(),
+        client.getPublicMetafieldDefinitions(),
       ]);
       if (catRes.status === 'fulfilled') setCategories(catRes.value.categories as CategoryNode[]);
       if (brandRes.status === 'fulfilled') setBrands(brandRes.value.brands);
       if (tagRes.status === 'fulfilled') setTags(tagRes.value.tags);
+      if (mfRes.status === 'fulfilled') {
+        setMetafieldDefs(
+          mfRes.value.definitions.filter(
+            (d) => d.filterable === true && FILTERABLE_TYPES.has(d.type)
+          )
+        );
+      }
     }
     loadFilters();
   }, []);
 
+  // Stable serialized signature of the selected metafield facets — used as
+  // the `loadProducts` dependency (and to derive the SDK shape). When no
+  // facets are selected, this is `''` so the SDK call omits `metafields`
+  // entirely and the backend short-circuits the filter branch.
+  const metafieldsKey = useMemo(() => {
+    if (metafieldDefs.length === 0) return '';
+    const parts: string[] = [];
+    for (const def of metafieldDefs) {
+      const raw = searchParams.get(`${METAFIELD_URL_PREFIX}${def.key}`);
+      if (raw) parts.push(`${def.key}=${raw}`);
+    }
+    return parts.sort().join('&');
+  }, [metafieldDefs, searchParams]);
+
   // Load products when filters change
   const loadProducts = useCallback(
     async (pageNum: number, append: boolean) => {
@@ -281,6 +318,24 @@ function ProductsContent() {
         if (categoryId) params.categories = categoryId;
         if (brandId) params.brands = brandId;
         if (tagId) params.tags = tagId;
+        // Build the `metafields` shape from `metafieldsKey` (each segment is
+        // `key=v1,v2`). Equivalent to reading the URL params directly but
+        // tied to the stable signature already in this callback's deps.
+        if (metafieldsKey) {
+          const mf: Record<string, string[]> = {};
+          for (const segment of metafieldsKey.split('&')) {
+            const eq = segment.indexOf('=');
+            if (eq < 0) continue;
+            const k = segment.slice(0, eq);
+            const v = segment
+              .slice(eq + 1)
+              .split(',')
+              .map((s) => s.trim())
+              .filter(Boolean);
+            if (v.length > 0) mf[k] = v;
+          }
+          if (Object.keys(mf).length > 0) params.metafields = mf;
+        }
 
         const result = await client.getProducts(params);
 
@@ -299,7 +354,15 @@ function ProductsContent() {
         setLoadingMore(false);
       }
     },
-    [searchQuery, categoryId, brandId, tagId, currentSort.sortBy, currentSort.sortOrder]
+    [
+      searchQuery,
+      categoryId,
+      brandId,
+      tagId,
+      currentSort.sortBy,
+      currentSort.sortOrder,
+      metafieldsKey,
+    ]
   );
 
   useEffect(() => {
@@ -326,6 +389,24 @@ function ProductsContent() {
     updateParam('category', id);
   }
 
+  /** Read the currently-selected values for a given metafield definition. */
+  function getSelectedMetafieldValues(key: string): string[] {
+    const raw = searchParams.get(`${METAFIELD_URL_PREFIX}${key}`);
+    if (!raw) return [];
+    return raw
+      .split(',')
+      .map((v) => v.trim())
+      .filter(Boolean);
+  }
+
+  /**
+   * Toggle one value on/off in a metafield facet's URL param. Multi-select
+   * adds/removes from the list; single-select / boolean replace the value.
+   */
+  function setMetafieldValue(key: string, values: string[]) {
+    updateParam(`${METAFIELD_URL_PREFIX}${key}`, values.join(','));
+  }
+
   return (
     <div className="mx-auto max-w-7xl px-4 py-8 sm:px-6 lg:px-8">
       {/* Page Header */}
@@ -402,6 +483,88 @@ function ProductsContent() {
             </select>
           )}
 
+          {/* Custom-field (metafield) facets — rendered per definition type.
+              Only definitions flagged `filterable: true` and published to
+              this sales channel reach this list (see `metafieldDefs` filter
+              above). The merchant's display name (`def.name`) is shown as-is
+              — `enumValues` come from the merchant's dashboard config. */}
+          {metafieldDefs.map((def) => {
+            const selected = getSelectedMetafieldValues(def.key);
+
+            if (def.type === 'BOOLEAN') {
+              const isOn = selected.includes('true');
+              return (
+                <label
+                  key={def.id}
+                  className="border-border text-foreground hover:border-primary inline-flex h-9 cursor-pointer items-center gap-2 rounded border px-3 text-sm transition-colors"
+                >
+                  <input
+                    type="checkbox"
+                    checked={isOn}
+                    onChange={(e) => setMetafieldValue(def.key, e.target.checked ? ['true'] : [])}
+                    className="accent-primary h-4 w-4"
+                  />
+                  {def.name}
+                </label>
+              );
+            }
+
+            if (def.type === 'SELECT') {
+              return (
+                <select
+                  key={def.id}
+                  value={selected[0] || ''}
+                  onChange={(e) =>
+                    setMetafieldValue(def.key, e.target.value ? [e.target.value] : [])
+                  }
+                  aria-label={def.name}
+                  className="border-border bg-background text-foreground focus:ring-primary/20 focus:border-primary h-9 rounded border px-3 text-sm focus:outline-none focus:ring-2"
+                >
+                  <option value="">{`${tc('all')} ${def.name}`}</option>
+                  {(def.enumValues || []).map((v) => (
+                    <option key={v} value={v}>
+                      {v}
+                    </option>
+                  ))}
+                </select>
+              );
+            }
+
+            // MULTI_SELECT — chip toggles. Each click adds/removes one value.
+            return (
+              <div
+                key={def.id}
+                className="border-border inline-flex items-center gap-1 rounded border px-2 py-1"
+                aria-label={def.name}
+              >
+                <span className="text-muted-foreground px-1 text-xs">{def.name}:</span>
+                {(def.enumValues || []).map((v) => {
+                  const active = selected.includes(v);
+                  return (
+                    <button
+                      key={v}
+                      type="button"
+                      onClick={() =>
+                        setMetafieldValue(
+                          def.key,
+                          active ? selected.filter((s) => s !== v) : [...selected, v]
+                        )
+                      }
+                      className={cn(
+                        'rounded-full border px-2 py-0.5 text-xs transition-colors',
+                        active
+                          ? 'bg-primary text-primary-foreground border-primary'
+                          : 'border-border text-muted-foreground hover:border-primary hover:text-foreground'
+                      )}
+                    >
+                      {v}
+                    </button>
+                  );
+                })}
+              </div>
+            );
+          })}
+
           {/* Sort */}
           <div className="flex items-center gap-2 sm:ms-auto">
             <label htmlFor="sort" className="text-muted-foreground whitespace-nowrap text-sm">