create-brainerce-store 1.36.0 → 1.39.0

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">

package/templates/nextjs/base/src/components/content/announcement-bar.tsx.ejs

@@ -0,0 +1,125 @@
+/**
+ * Storefront announcement bar — fully driven by the merchant's dashboard.
+ *
+ * The merchant configures announcements in the Brainerce dashboard under
+ *   Sell → Content → Announcement
+ *
+ * Everything below is generic rendering logic — it adapts automatically to
+ * any announcement shape returned by the API, so **you should not hardcode
+ * the message or severity here**.
+ *
+ * API contract:
+ *   GET → client.content.announcement.list(locale) → Content<'ANNOUNCEMENT'>[]
+ *   Empty array → renders nothing (page layout stays intact).
+ *
+ * Time-bounded: each announcement may have `startsAt` / `endsAt` ISO
+ * timestamps. We filter client-side so the cached server response can be
+ * shared across visitors regardless of the current time.
+ */
+'use client';
+
+import * as React from 'react';
+import type { Content } from 'brainerce';
+
+interface AnnouncementBarProps {
+  /** Pre-fetched list from the server. Pass `[]` to render nothing. */
+  announcements: Content<'ANNOUNCEMENT'>[];
+}
+
+const SEVERITY_STYLES: Record<'info' | 'warning' | 'success', string> = {
+  info: 'bg-blue-600 text-white',
+  warning: 'bg-amber-500 text-amber-950',
+  success: 'bg-emerald-600 text-white',
+};
+
+const STORAGE_KEY = 'brainerce_dismissed_announcements';
+
+export function AnnouncementBar({ announcements }: AnnouncementBarProps) {
+  const [dismissed, setDismissed] = React.useState<Set<string>>(() => new Set());
+
+  // Hydrate dismissals from localStorage on mount (avoids SSR/CSR mismatch).
+  React.useEffect(() => {
+    if (typeof window === 'undefined') return;
+    try {
+      const raw = window.localStorage.getItem(STORAGE_KEY);
+      if (raw) setDismissed(new Set(JSON.parse(raw) as string[]));
+    } catch {
+      // ignore malformed storage
+    }
+  }, []);
+
+  const dismiss = (id: string) => {
+    setDismissed((prev) => {
+      const next = new Set(prev);
+      next.add(id);
+      if (typeof window !== 'undefined') {
+        try {
+          window.localStorage.setItem(STORAGE_KEY, JSON.stringify([...next]));
+        } catch {
+          // ignore quota errors
+        }
+      }
+      return next;
+    });
+  };
+
+  const now = Date.now();
+  const visible = announcements.filter((a) => {
+    if (dismissed.has(a.id)) return false;
+    const startOk = !a.data.startsAt || new Date(a.data.startsAt).getTime() <= now;
+    const endOk = !a.data.endsAt || new Date(a.data.endsAt).getTime() >= now;
+    return startOk && endOk;
+  });
+
+  if (visible.length === 0) return null;
+
+  return (
+    <div role="region" aria-label="Site announcements">
+      {visible.map((announcement) => {
+        const severity = announcement.data.severity;
+        const tone = SEVERITY_STYLES[severity] ?? SEVERITY_STYLES.info;
+        return (
+          <div
+            key={announcement.id}
+            className={`flex items-center justify-center gap-3 px-4 py-2 text-sm ${tone}`}
+          >
+            <span className="flex-1 text-center">
+              {announcement.data.message}
+              {announcement.data.ctaHref && announcement.data.ctaLabel ? (
+                <>
+                  {' '}
+                  <a
+                    href={announcement.data.ctaHref}
+                    className="underline underline-offset-2"
+                  >
+                    {announcement.data.ctaLabel}
+                  </a>
+                </>
+              ) : null}
+            </span>
+            {announcement.data.dismissible ? (
+              <button
+                type="button"
+                onClick={() => dismiss(announcement.id)}
+                aria-label="Dismiss announcement"
+                className="text-current opacity-80 transition-opacity hover:opacity-100"
+              >
+                <svg
+                  xmlns="http://www.w3.org/2000/svg"
+                  viewBox="0 0 24 24"
+                  fill="none"
+                  stroke="currentColor"
+                  strokeWidth="2"
+                  className="h-4 w-4"
+                  aria-hidden="true"
+                >
+                  <path strokeLinecap="round" strokeLinejoin="round" d="M6 18L18 6M6 6l12 12" />
+                </svg>
+              </button>
+            ) : null}
+          </div>
+        );
+      })}
+    </div>
+  );
+}

package/templates/nextjs/base/src/components/content/faq-section.tsx.ejs

@@ -0,0 +1,75 @@
+/**
+ * FAQ accordion — fully driven by the merchant's dashboard configuration.
+ *
+ * The merchant configures FAQs in the Brainerce dashboard under
+ *   Sell → Content → FAQ
+ *
+ * Each FAQ row has a `key` (e.g. 'main', 'shipping', 'returns'). Pass the
+ * pre-fetched payload as `faq`; this component knows nothing about which
+ * key it came from.
+ *
+ * Security: FAQ answers may contain merchant-authored HTML — we sanitize
+ * via `sanitizeHtml` before injecting via dangerouslySetInnerHTML.
+ */
+'use client';
+
+import * as React from 'react';
+import type { Content } from 'brainerce';
+import { sanitizeHtml } from '@/lib/sanitize';
+
+interface FaqSectionProps {
+  /** Pre-fetched FAQ row. `null` triggers a minimal empty-state message. */
+  faq: Content<'FAQ'> | null;
+}
+
+export function FaqSection({ faq }: FaqSectionProps) {
+  const [openIdx, setOpenIdx] = React.useState<number | null>(0);
+
+  if (!faq || !faq.data.items?.length) {
+    return null;
+  }
+
+  return (
+    <section className="mx-auto max-w-3xl px-4 py-10 sm:px-6 lg:px-8">
+      <h1 className="text-foreground mb-6 text-2xl font-semibold sm:text-3xl">{faq.name}</h1>
+      <ul className="border-border divide-border divide-y rounded-lg border">
+        {faq.data.items.map((item, idx) => {
+          const open = openIdx === idx;
+          return (
+            <li key={idx}>
+              <button
+                type="button"
+                onClick={() => setOpenIdx(open ? null : idx)}
+                aria-expanded={open}
+                className="hover:bg-muted/40 flex w-full items-center justify-between gap-4 p-4 text-start transition-colors"
+              >
+                <span className="text-foreground text-sm font-medium sm:text-base">
+                  {item.question}
+                </span>
+                <svg
+                  xmlns="http://www.w3.org/2000/svg"
+                  viewBox="0 0 24 24"
+                  fill="none"
+                  stroke="currentColor"
+                  strokeWidth="2"
+                  className={`text-muted-foreground h-4 w-4 transition-transform ${
+                    open ? 'rotate-180' : ''
+                  }`}
+                  aria-hidden="true"
+                >
+                  <path strokeLinecap="round" strokeLinejoin="round" d="M19 9l-7 7-7-7" />
+                </svg>
+              </button>
+              {open ? (
+                <div
+                  className="text-muted-foreground prose prose-sm dark:prose-invert max-w-none px-4 pb-4 text-sm leading-relaxed"
+                  dangerouslySetInnerHTML={{ __html: sanitizeHtml(item.answer) }}
+                />
+              ) : null}
+            </li>
+          );
+        })}
+      </ul>
+    </section>
+  );
+}

package/templates/nextjs/base/src/components/content/rich-text-block.tsx.ejs

@@ -0,0 +1,32 @@
+/**
+ * Inline rich-text block — fully driven by the merchant's dashboard.
+ *
+ * The merchant configures rich-text blocks in the Brainerce dashboard
+ * under Sell → Content → Rich Text. Use this component anywhere on a page
+ * to drop a merchant-editable HTML block (intro copy, banner descriptions,
+ * inline announcements that aren't tied to the top-of-page Announcement
+ * bar, etc.).
+ *
+ * Security: HTML is sanitized via `sanitizeHtml` (isomorphic-dompurify)
+ * before injecting via dangerouslySetInnerHTML.
+ */
+import * as React from 'react';
+import type { Content } from 'brainerce';
+import { sanitizeHtml } from '@/lib/sanitize';
+
+interface RichTextBlockProps {
+  /** Pre-fetched RICH_TEXT row, e.g. via `client.content.richText.get(key, locale)`. */
+  block: Content<'RICH_TEXT'> | null;
+  /** Optional wrapper className for layout positioning. */
+  className?: string;
+}
+
+export function RichTextBlock({ block, className }: RichTextBlockProps) {
+  if (!block?.data?.html) return null;
+  return (
+    <div
+      className={className ?? 'prose prose-sm dark:prose-invert max-w-none'}
+      dangerouslySetInnerHTML={{ __html: sanitizeHtml(block.data.html) }}
+    />
+  );
+}

package/templates/nextjs/base/src/components/content/site-footer.tsx.ejs

@@ -0,0 +1,96 @@
+/**
+ * Storefront footer — fully driven by the merchant's dashboard configuration.
+ *
+ * The merchant configures the footer in the Brainerce dashboard under
+ *   Sell → Content → Footer
+ *
+ * Everything below is generic rendering logic — it adapts automatically to
+ * any footer shape returned by the API, so **you should not hardcode column
+ * titles or link labels here**.
+ *
+ * API contract:
+ *   GET → client.content.footer.get('main', locale) → Content<'FOOTER'> | null
+ *   Returns null on 404 — we render a minimal fallback so the layout never
+ *   crashes when the merchant hasn't seeded the footer yet.
+ *
+ * Security: this component renders text only. For RichText/Page HTML, use
+ *   <RichTextBlock> which sanitizes via isomorphic-dompurify.
+ */
+import * as React from 'react';
+import type { Content } from 'brainerce';
+
+interface SiteFooterProps {
+  /** Pre-fetched footer payload (server-side). `null` triggers fallback rendering. */
+  footer: Content<'FOOTER'> | null;
+  /** Store name shown in the fallback copyright when no footer is configured. */
+  storeName?: string;
+}
+
+export function SiteFooter({ footer, storeName }: SiteFooterProps) {
+  const data = footer?.data;
+  const columns = data?.columns ?? [];
+  const social = data?.social ?? [];
+
+  // Fallback when the merchant hasn't seeded a footer yet — keeps the layout
+  // visually complete without exposing "missing content" to shoppers.
+  if (!data || (columns.length === 0 && !data.copyright && social.length === 0)) {
+    const year = new Date().getFullYear();
+    return (
+      <footer className="border-border bg-muted/30 text-muted-foreground mt-12 border-t py-8 text-sm">
+        <div className="mx-auto max-w-7xl px-4 text-center sm:px-6 lg:px-8">
+          © {year} {storeName ?? 'Store'}
+        </div>
+      </footer>
+    );
+  }
+
+  return (
+    <footer className="border-border bg-muted/30 text-foreground mt-12 border-t">
+      <div className="mx-auto max-w-7xl px-4 py-10 sm:px-6 lg:px-8">
+        {columns.length > 0 ? (
+          <div className="grid grid-cols-1 gap-8 sm:grid-cols-2 md:grid-cols-3 lg:grid-cols-4">
+            {columns.map((col, idx) => (
+              <div key={`${col.title}-${idx}`}>
+                <h3 className="text-foreground mb-3 text-sm font-semibold">{col.title}</h3>
+                <ul className="space-y-2">
+                  {col.links.map((link, linkIdx) => (
+                    <li key={`${link.url}-${linkIdx}`}>
+                      <a
+                        href={link.url}
+                        className="text-muted-foreground hover:text-foreground text-sm transition-colors"
+                      >
+                        {link.label}
+                      </a>
+                    </li>
+                  ))}
+                </ul>
+              </div>
+            ))}
+          </div>
+        ) : null}
+
+        {social.length > 0 ? (
+          <div className="border-border mt-8 flex flex-wrap items-center gap-4 border-t pt-6">
+            {social.map((entry, idx) => (
+              <a
+                key={`${entry.platform}-${idx}`}
+                href={entry.url}
+                target="_blank"
+                rel="noopener noreferrer"
+                className="text-muted-foreground hover:text-foreground text-sm capitalize transition-colors"
+              >
+                {entry.platform}
+              </a>
+            ))}
+          </div>
+        ) : null}
+
+        {data.copyright ? (
+          <div className="border-border text-muted-foreground mt-6 border-t pt-4 text-center text-xs">
+            {data.copyright}
+          </div>
+        ) : null}
+      </div>
+    </footer>
+  );
+}

package/templates/nextjs/base/src/components/content/site-header.tsx.ejs

@@ -0,0 +1,65 @@
+/**
+ * Merchant-controlled site header.
+ *
+ * The merchant configures the header in the Brainerce dashboard under
+ *   Sell → Content → Header
+ *
+ * Renders logo (when set) + nav items + CTA. Everything is generic — you
+ * should NOT hardcode nav labels or logo paths here; the merchant edits
+ * them in the dashboard and the change propagates within ~5 minutes.
+ *
+ * Returns null on 404 — new stores are seeded with a default HEADER row
+ * by the backend (StoresService.seedDefaultContent) so this should be
+ * populated out of the box.
+ */
+import * as React from 'react';
+import type { Content } from 'brainerce';
+
+interface SiteHeaderProps {
+  /** Pre-fetched header payload (server-side). `null` renders nothing. */
+  header: Content<'HEADER'> | null;
+}
+
+export function SiteHeader({ header }: SiteHeaderProps) {
+  if (!header) return null;
+  const data = header.data;
+  const logo = data.logo;
+  const navItems = data.navItems ?? [];
+  const cta = data.cta;
+
+  return (
+    <div className="border-border bg-background border-b">
+      <div className="mx-auto flex h-14 max-w-7xl items-center justify-between gap-4 px-4 sm:px-6 lg:px-8">
+        <a href="/" className="flex items-center gap-2">
+          {logo ? (
+            // eslint-disable-next-line @next/next/no-img-element -- merchant-supplied URL, dynamic optimization handled by CDN
+            <img src={logo.src} alt={logo.alt} className="h-8 w-auto" />
+          ) : null}
+        </a>
+
+        {navItems.length > 0 ? (
+          <nav className="hidden items-center gap-6 md:flex">
+            {navItems.map((item, idx) => (
+              <a
+                key={`${item.url}-${idx}`}
+                href={item.url}
+                className="text-muted-foreground hover:text-foreground text-sm transition-colors"
+              >
+                {item.label}
+              </a>
+            ))}
+          </nav>
+        ) : null}
+
+        {cta ? (
+          <a
+            href={cta.url}
+            className="bg-primary text-primary-foreground inline-flex items-center justify-center rounded-md px-4 py-2 text-sm font-medium transition-colors hover:opacity-90"
+          >
+            {cta.label}
+          </a>
+        ) : null}
+      </div>
+    </div>
+  );
+}