@cimplify/sdk 0.40.1 → 0.42.0

package/templates/storefront-fashion/README.md

@@ -0,0 +1,77 @@
+# __STOREFRONT_NAME__
+
+A Cimplify storefront scaffolded from the **retail** template — Next.js 16 (App Router), React 19, Tailwind v4. Cool navy + electric blue palette, Inter + JetBrains Mono typography, modern electronics-store aesthetic.
+
+## Run
+
+```bash
+bun install
+bun dev
+```
+
+Two things start in parallel:
+
+- `bunx @cimplify/sdk --seed retail` — the Cimplify mock API on `http://127.0.0.1:8787`, seeded with Currents Electronics.
+- `next dev` — this storefront on `http://localhost:3000`.
+
+Open the storefront in your browser. Edit `app/page.tsx` to start customising.
+
+## Structure
+
+```
+app/
+  layout.tsx              # root layout, fonts, providers, header/footer/modal
+  page.tsx                # home
+  shop/page.tsx           # full catalogue (SDK <CataloguePage/>)
+  collections/[slug]/     # collection landing
+  categories/[slug]/      # category landing
+  cart/page.tsx           # SDK <CartPage/>
+  checkout/page.tsx       # SDK <CheckoutPage/>
+  orders/[id]/page.tsx    # post-checkout thank-you
+  about, faq, terms, privacy
+  globals.css             # Tailwind import + theme tokens
+components/
+  providers.tsx           # CimplifyProvider client wrapper
+  header.tsx, footer.tsx, hero.tsx
+  store-product-card.tsx  # SDK <ProductCard/> wired to URL-driven modal
+  product-modal.tsx       # ?product=<slug> deep-linkable modal
+  collection-strip.tsx    # horizontal product strip
+  category-grid.tsx       # SDK <CategoryGrid/> with router navigation
+lib/
+  cart.ts                 # useCartCount() for the header pill
+```
+
+## Switch the seed
+
+This template is wired to the `retail` seed. To preview a different industry without re-scaffolding:
+
+```bash
+bunx @cimplify/sdk --seed restaurant   # Mama's Kitchen
+bunx @cimplify/sdk --seed services     # Serene Spa
+bunx @cimplify/sdk --seed grocery      # FreshMart
+```
+
+Update `NEXT_PUBLIC_CIMPLIFY_BUSINESS_ID` in `.env.local` to match the seeded business.
+
+For a fresh scaffold with another design altogether:
+
+```bash
+bunx @cimplify/sdk init my-store --template bakery     # warm food/pastry
+bunx @cimplify/sdk init my-store --template restaurant # coming soon
+bunx @cimplify/sdk init my-store --template services   # coming soon
+bunx @cimplify/sdk init my-store --template grocery    # coming soon
+```
+
+## Go live
+
+```diff
+# .env.local
+- NEXT_PUBLIC_CIMPLIFY_API_URL=http://127.0.0.1:8787
++ NEXT_PUBLIC_CIMPLIFY_API_URL=https://api.cimplify.io
+- NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY=mock-dev
++ NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY=<your tenant key>
+- NEXT_PUBLIC_CIMPLIFY_BUSINESS_ID=bus_currents_electronics
++ NEXT_PUBLIC_CIMPLIFY_BUSINESS_ID=<your business id>
+```
+
+Deploy to Vercel with one click — `next.config.ts` already whitelists the SDK image hosts under `images.remotePatterns`.

package/templates/storefront-fashion/app/about/page.tsx

@@ -0,0 +1,41 @@
+import type { Metadata } from "next";
+import { brand } from "@/lib/brand";
+
+export const metadata: Metadata = {
+  title: `About — ${brand.name}`,
+  description: brand.description,
+};
+
+export default function AboutPage() {
+  const a = brand.about;
+  // Title supports a single \n for a hard line break.
+  const titleParts = a.title.split("\n");
+  return (
+    <article className="max-w-3xl mx-auto px-8 py-16">
+      <p className="text-[11px] font-mono uppercase tracking-[0.16em] text-primary mb-2">
+        {a.eyebrow}
+      </p>
+      <h1 className="text-[clamp(2.25rem,5vw,3.5rem)] font-bold mb-6 -tracking-[0.025em] leading-tight">
+        {titleParts.map((line, i) => (
+          <span key={i}>
+            {line}
+            {i < titleParts.length - 1 && <br />}
+          </span>
+        ))}
+      </h1>
+      <div className="prose prose-lg max-w-none space-y-5 text-foreground/90 leading-relaxed">
+        {a.paragraphs.map((p, i) => (
+          <p key={i}>{p}</p>
+        ))}
+        {a.sections.map((s) => (
+          <div key={s.heading}>
+            <h2 className="text-2xl font-semibold mt-10 mb-3 -tracking-[0.02em]">
+              {s.heading}
+            </h2>
+            <p>{s.body}</p>
+          </div>
+        ))}
+      </div>
+    </article>
+  );
+}

package/templates/storefront-fashion/app/accessibility/page.tsx

@@ -0,0 +1,11 @@
+import type { Metadata } from "next";
+import { brand } from "@/lib/brand";
+import { PolicyPage } from "@/components/policy-page";
+
+export const metadata: Metadata = {
+  title: `${brand.accessibility.title} — ${brand.name}`,
+};
+
+export default function AccessibilityPage() {
+  return <PolicyPage policy={brand.accessibility} />;
+}

package/templates/storefront-fashion/app/account/addresses/page.tsx

@@ -0,0 +1,21 @@
+import type { Metadata } from "next";
+import { AccountIframe } from "@/components/account-iframe";
+import { brand } from "@/lib/brand";
+
+export const metadata: Metadata = {
+  title: `Addresses — ${brand.name}`,
+};
+
+export default function AddressesPage() {
+  return (
+    <article className="max-w-5xl mx-auto px-6 sm:px-8 py-12">
+      <p className="text-[11px] font-semibold uppercase tracking-[0.16em] text-primary mb-2">
+        Account
+      </p>
+      <h1 className="font-serif text-[clamp(2rem,4vw,2.75rem)] font-semibold mb-8 -tracking-[0.02em]">
+        Your addresses
+      </h1>
+      <AccountIframe section="addresses" />
+    </article>
+  );
+}

package/templates/storefront-fashion/app/account/orders/page.tsx

@@ -0,0 +1,21 @@
+import type { Metadata } from "next";
+import { AccountIframe } from "@/components/account-iframe";
+import { brand } from "@/lib/brand";
+
+export const metadata: Metadata = {
+  title: `Orders — ${brand.name}`,
+};
+
+export default function OrdersPage() {
+  return (
+    <article className="max-w-5xl mx-auto px-6 sm:px-8 py-12">
+      <p className="text-[11px] font-semibold uppercase tracking-[0.16em] text-primary mb-2">
+        Account
+      </p>
+      <h1 className="font-serif text-[clamp(2rem,4vw,2.75rem)] font-semibold mb-8 -tracking-[0.02em]">
+        Your orders
+      </h1>
+      <AccountIframe section="orders" />
+    </article>
+  );
+}

package/templates/storefront-fashion/app/account/page.tsx

@@ -0,0 +1,22 @@
+import type { Metadata } from "next";
+import { AccountIframe } from "@/components/account-iframe";
+import { brand } from "@/lib/brand";
+
+export const metadata: Metadata = {
+  title: `Account — ${brand.name}`,
+  description: brand.account.signupSubtitle,
+};
+
+export default function AccountPage() {
+  return (
+    <article className="max-w-5xl mx-auto px-6 sm:px-8 py-12">
+      <p className="text-[11px] font-semibold uppercase tracking-[0.16em] text-primary mb-2">
+        {brand.account.accountEyebrow}
+      </p>
+      <h1 className="font-serif text-[clamp(2rem,4vw,2.75rem)] font-semibold mb-8 -tracking-[0.02em]">
+        {brand.account.accountTitle}
+      </h1>
+      <AccountIframe />
+    </article>
+  );
+}

package/templates/storefront-fashion/app/account/settings/page.tsx

@@ -0,0 +1,21 @@
+import type { Metadata } from "next";
+import { AccountIframe } from "@/components/account-iframe";
+import { brand } from "@/lib/brand";
+
+export const metadata: Metadata = {
+  title: `Settings — ${brand.name}`,
+};
+
+export default function SettingsPage() {
+  return (
+    <article className="max-w-5xl mx-auto px-6 sm:px-8 py-12">
+      <p className="text-[11px] font-semibold uppercase tracking-[0.16em] text-primary mb-2">
+        Account
+      </p>
+      <h1 className="font-serif text-[clamp(2rem,4vw,2.75rem)] font-semibold mb-8 -tracking-[0.02em]">
+        Settings
+      </h1>
+      <AccountIframe section="settings" />
+    </article>
+  );
+}

package/templates/storefront-fashion/app/cart/page.tsx

@@ -0,0 +1,9 @@
+"use client";
+
+import { useRouter } from "next/navigation";
+import { CartPage as SdkCartPage } from "@cimplify/sdk/react";
+
+export default function CartPage() {
+  const router = useRouter();
+  return <SdkCartPage onCheckout={() => router.push("/checkout")} />;
+}

package/templates/storefront-fashion/app/categories/[slug]/listing-client.tsx

@@ -0,0 +1,19 @@
+"use client";
+
+import { ProductGrid } from "@cimplify/sdk/react";
+import type { Product } from "@cimplify/sdk";
+import { StoreProductCard } from "@/components/store-product-card";
+
+/**
+ * Client island for the category listing. Receives server-fetched products
+ * as props (serializable) and owns the `renderCard` function.
+ */
+export function ListingClient({ products }: { products: Product[] }) {
+  return (
+    <ProductGrid
+      products={products}
+      emptyMessage="No products in this category yet."
+      renderCard={(p) => <StoreProductCard product={p} />}
+    />
+  );
+}

package/templates/storefront-fashion/app/categories/[slug]/page.tsx

@@ -0,0 +1,130 @@
+import type { Metadata } from "next";
+import { Suspense } from "react";
+import Link from "next/link";
+import { notFound } from "next/navigation";
+import { cacheTag, cacheLife } from "next/cache";
+import {
+  getServerClient,
+  tags,
+  type Category,
+  type Product,
+} from "@cimplify/sdk/server";
+import { ListingClient } from "./listing-client";
+import { brand } from "@/lib/brand";
+
+interface CategoryData {
+  category: Category;
+  products: Product[];
+}
+
+async function getCategory(slug: string): Promise<CategoryData | null> {
+  "use cache";
+  cacheTag(tags.categories());
+  cacheLife("hours");
+
+  const client = getServerClient();
+  const catRes = await client.catalogue.getCategoryBySlug(slug);
+  if (!catRes.ok) return null;
+
+  cacheTag(tags.category(catRes.value.id), tags.categoryProducts(catRes.value.id));
+  const r = await client.catalogue.getCategoryProducts(catRes.value.id);
+  const products = r.ok
+    ? ((r.value as { items?: Product[] }).items ?? (r.value as Product[]))
+    : [];
+  return { category: catRes.value, products };
+}
+
+export async function generateMetadata({
+  params,
+}: {
+  params: Promise<{ slug: string }>;
+}): Promise<Metadata> {
+  const { slug } = await params;
+  const data = await getCategory(slug);
+  if (!data) return {};
+  return {
+    title: `${data.category.name} — ${brand.name}`,
+    description: data.category.description ?? undefined,
+  };
+}
+
+export default async function CategoryPage({
+  params,
+}: {
+  params: Promise<{ slug: string }>;
+}) {
+  return (
+    <Suspense fallback={<CategorySkeleton />}>
+      <CategoryContent params={params} />
+    </Suspense>
+  );
+}
+
+async function CategoryContent({
+  params,
+}: {
+  params: Promise<{ slug: string }>;
+}) {
+  const { slug } = await params;
+  const data = await getCategory(slug);
+  if (!data) notFound();
+
+  const { category, products } = data;
+  return (
+    <>
+      <section className="bg-foreground text-background relative overflow-hidden">
+        <div className="absolute inset-0 opacity-[0.04] pointer-events-none [background-image:radial-gradient(circle_at_2px_2px,white_1px,transparent_0)] [background-size:32px_32px]" />
+        <div className="relative max-w-7xl mx-auto px-6 sm:px-8 py-12 sm:py-14">
+          <nav className="text-[12px] font-mono text-background/60 mb-3 flex items-center gap-2">
+            <Link href="/" className="hover:text-background transition-colors">Home</Link>
+            <span>/</span>
+            <Link href="/shop" className="hover:text-background transition-colors">Shop</Link>
+            <span>/</span>
+            <span className="text-background/90">{category.name}</span>
+          </nav>
+          <h1 className="text-[clamp(2rem,4vw,3rem)] font-bold m-0 -tracking-[0.025em]">
+            {category.name}
+          </h1>
+          {category.description && (
+            <p className="mt-3 max-w-2xl text-base text-background/75">
+              {category.description}
+            </p>
+          )}
+          <p className="mt-4 text-[11px] font-mono uppercase tracking-[0.16em] text-background/60 tabular-nums">
+            {products.length} {products.length === 1 ? "product" : "products"}
+          </p>
+        </div>
+      </section>
+      <section className="max-w-7xl mx-auto px-6 sm:px-8 py-10 sm:py-12">
+        <ListingClient products={products} />
+        {products.length === 0 && (
+          <p className="text-center mt-8">
+            <Link href="/shop" className="text-primary font-semibold hover:underline">
+              ← Browse all products
+            </Link>
+          </p>
+        )}
+      </section>
+    </>
+  );
+}
+
+function CategorySkeleton() {
+  return (
+    <>
+      <section className="bg-foreground py-12 sm:py-14">
+        <div className="max-w-7xl mx-auto px-6 sm:px-8">
+          <div className="h-3 w-32 bg-background/20 rounded mb-3 animate-pulse" />
+          <div className="h-12 w-72 bg-background/20 rounded animate-pulse" />
+        </div>
+      </section>
+      <section className="max-w-7xl mx-auto px-6 sm:px-8 py-10 sm:py-12">
+        <div className="grid grid-cols-2 md:grid-cols-3 lg:grid-cols-4 gap-3 sm:gap-4">
+          {Array.from({ length: 8 }).map((_, i) => (
+            <div key={i} className="aspect-[4/3] bg-muted rounded-2xl animate-pulse" />
+          ))}
+        </div>
+      </section>
+    </>
+  );
+}

package/templates/storefront-fashion/app/checkout/page.tsx

@@ -0,0 +1,17 @@
+"use client";
+
+import { useRouter } from "next/navigation";
+import { CheckoutPage as SdkCheckoutPage } from "@cimplify/sdk/react";
+
+export default function CheckoutPage() {
+  const router = useRouter();
+  return (
+    <SdkCheckoutPage
+      onComplete={(result) => {
+        if (result.success && result.order) {
+          router.push(`/orders/${result.order.id}`);
+        }
+      }}
+    />
+  );
+}

package/templates/storefront-fashion/app/collections/[slug]/listing-client.tsx

@@ -0,0 +1,20 @@
+"use client";
+
+import { ProductGrid } from "@cimplify/sdk/react";
+import type { Product } from "@cimplify/sdk";
+import { StoreProductCard } from "@/components/store-product-card";
+
+/**
+ * Client island for the collection listing. Receives server-fetched
+ * products as props (serializable) and owns the `renderCard` function
+ * (which can't cross the server/client boundary).
+ */
+export function ListingClient({ products }: { products: Product[] }) {
+  return (
+    <ProductGrid
+      products={products}
+      emptyMessage="No products in this collection yet."
+      renderCard={(p) => <StoreProductCard product={p} />}
+    />
+  );
+}

package/templates/storefront-fashion/app/collections/[slug]/page.tsx

@@ -0,0 +1,130 @@
+import type { Metadata } from "next";
+import { Suspense } from "react";
+import Link from "next/link";
+import { notFound } from "next/navigation";
+import { cacheTag, cacheLife } from "next/cache";
+import {
+  getServerClient,
+  tags,
+  type Collection,
+  type Product,
+} from "@cimplify/sdk/server";
+import { ListingClient } from "./listing-client";
+import { brand } from "@/lib/brand";
+
+interface CollectionData {
+  collection: Collection;
+  products: Product[];
+}
+
+async function getCollection(slug: string): Promise<CollectionData | null> {
+  "use cache";
+  cacheTag(tags.collections());
+  cacheLife("hours");
+
+  const client = getServerClient();
+  const colRes = await client.catalogue.getCollectionBySlug(slug);
+  if (!colRes.ok) return null;
+
+  cacheTag(tags.collection(colRes.value.id), tags.collectionProducts(colRes.value.id));
+  const r = await client.catalogue.getCollectionProducts(colRes.value.id);
+  const products = r.ok
+    ? ((r.value as { items?: Product[] }).items ?? (r.value as Product[]))
+    : [];
+  return { collection: colRes.value, products };
+}
+
+export async function generateMetadata({
+  params,
+}: {
+  params: Promise<{ slug: string }>;
+}): Promise<Metadata> {
+  const { slug } = await params;
+  const data = await getCollection(slug);
+  if (!data) return {};
+  return {
+    title: `${data.collection.name} — ${brand.name}`,
+    description: data.collection.description ?? undefined,
+  };
+}
+
+export default async function CollectionPage({
+  params,
+}: {
+  params: Promise<{ slug: string }>;
+}) {
+  return (
+    <Suspense fallback={<CollectionSkeleton />}>
+      <CollectionContent params={params} />
+    </Suspense>
+  );
+}
+
+async function CollectionContent({
+  params,
+}: {
+  params: Promise<{ slug: string }>;
+}) {
+  const { slug } = await params;
+  const data = await getCollection(slug);
+  if (!data) notFound();
+
+  const { collection, products } = data;
+  return (
+    <>
+      <section className="bg-foreground text-background relative overflow-hidden">
+        <div className="absolute inset-0 opacity-[0.04] pointer-events-none [background-image:radial-gradient(circle_at_2px_2px,white_1px,transparent_0)] [background-size:32px_32px]" />
+        <div className="relative max-w-7xl mx-auto px-6 sm:px-8 py-12 sm:py-14">
+          <nav className="text-[12px] font-mono text-background/60 mb-3 flex items-center gap-2">
+            <Link href="/" className="hover:text-background transition-colors">Home</Link>
+            <span>/</span>
+            <span className="text-background/90">Collections</span>
+            <span>/</span>
+            <span className="text-background/90">{collection.name}</span>
+          </nav>
+          <h1 className="text-[clamp(2rem,4vw,3rem)] font-bold m-0 -tracking-[0.025em]">
+            {collection.name}
+          </h1>
+          {collection.description && (
+            <p className="mt-3 max-w-2xl text-base text-background/75">
+              {collection.description}
+            </p>
+          )}
+          <p className="mt-4 text-[11px] font-mono uppercase tracking-[0.16em] text-background/60 tabular-nums">
+            {products.length} {products.length === 1 ? "product" : "products"}
+          </p>
+        </div>
+      </section>
+      <section className="max-w-7xl mx-auto px-6 sm:px-8 py-10 sm:py-12">
+        <ListingClient products={products} />
+        {products.length === 0 && (
+          <p className="text-center mt-8">
+            <Link href="/shop" className="text-primary font-semibold hover:underline">
+              ← Browse all products
+            </Link>
+          </p>
+        )}
+      </section>
+    </>
+  );
+}
+
+function CollectionSkeleton() {
+  return (
+    <>
+      <section className="bg-foreground py-12 sm:py-14">
+        <div className="max-w-7xl mx-auto px-6 sm:px-8">
+          <div className="h-3 w-32 bg-background/20 rounded mb-3 animate-pulse" />
+          <div className="h-12 w-72 bg-background/20 rounded animate-pulse" />
+        </div>
+      </section>
+      <section className="max-w-7xl mx-auto px-6 sm:px-8 py-10 sm:py-12">
+        <div className="grid grid-cols-2 md:grid-cols-3 lg:grid-cols-4 gap-3 sm:gap-4">
+          {Array.from({ length: 8 }).map((_, i) => (
+            <div key={i} className="aspect-[4/3] bg-muted rounded-2xl animate-pulse" />
+          ))}
+        </div>
+      </section>
+    </>
+  );
+}

package/templates/storefront-fashion/app/contact/contact-form.tsx

@@ -0,0 +1,109 @@
+"use client";
+
+import { useState } from "react";
+
+/**
+ * Local-only contact form. On submit, fakes a successful response so the
+ * template ships a usable interaction. Wire to a real handler (Server
+ * Action posting to your CRM, support inbox, or Cimplify Support API)
+ * before going to production.
+ */
+export function ContactForm({ reasons }: { reasons: string[] }) {
+  const [submitted, setSubmitted] = useState(false);
+  const [reason, setReason] = useState(reasons[0] ?? "");
+
+  if (submitted) {
+    return (
+      <div className="rounded-2xl border border-border bg-card p-8">
+        <p className="text-[11px] font-semibold uppercase tracking-[0.16em] text-primary mb-2">
+          ✓ Sent
+        </p>
+        <h2 className="font-serif text-2xl font-semibold mb-2">Thanks — we'll be in touch.</h2>
+        <p className="text-muted-foreground">
+          We respond within one business day. Check your spam folder if you don't see a
+          reply by tomorrow.
+        </p>
+      </div>
+    );
+  }
+
+  return (
+    <form
+      onSubmit={(e) => {
+        e.preventDefault();
+        setSubmitted(true);
+      }}
+      className="space-y-5"
+    >
+      <div className="grid grid-cols-1 sm:grid-cols-2 gap-4">
+        <Field label="Your name" name="name" required />
+        <Field label="Email" name="email" type="email" required />
+      </div>
+      <div>
+        <label className="text-xs font-semibold uppercase tracking-wider text-muted-foreground block mb-1.5">
+          What's it about?
+        </label>
+        <select
+          name="reason"
+          value={reason}
+          onChange={(e) => setReason(e.target.value)}
+          className="w-full px-4 py-2.5 rounded-md bg-background border border-border focus:border-primary focus:ring-2 focus:ring-primary/20 outline-none text-sm"
+        >
+          {reasons.map((r) => (
+            <option key={r} value={r}>
+              {r}
+            </option>
+          ))}
+        </select>
+      </div>
+      <Field label="Order number (optional)" name="order" />
+      <div>
+        <label className="text-xs font-semibold uppercase tracking-wider text-muted-foreground block mb-1.5">
+          Message
+        </label>
+        <textarea
+          name="message"
+          required
+          rows={6}
+          className="w-full px-4 py-2.5 rounded-md bg-background border border-border focus:border-primary focus:ring-2 focus:ring-primary/20 outline-none text-sm resize-y"
+        />
+      </div>
+      <button
+        type="submit"
+        className="inline-flex items-center justify-center px-5 py-3 rounded-md bg-primary text-primary-foreground font-semibold text-sm hover:bg-primary/90 transition-colors"
+      >
+        Send message
+      </button>
+    </form>
+  );
+}
+
+function Field({
+  label,
+  name,
+  type = "text",
+  required,
+}: {
+  label: string;
+  name: string;
+  type?: string;
+  required?: boolean;
+}) {
+  return (
+    <div>
+      <label
+        htmlFor={name}
+        className="text-xs font-semibold uppercase tracking-wider text-muted-foreground block mb-1.5"
+      >
+        {label}
+      </label>
+      <input
+        id={name}
+        name={name}
+        type={type}
+        required={required}
+        className="w-full px-4 py-2.5 rounded-md bg-background border border-border focus:border-primary focus:ring-2 focus:ring-primary/20 outline-none text-sm"
+      />
+    </div>
+  );
+}