@cimplify/sdk 0.44.12 → 0.44.14

package/registry/session-message-banner.json

@@ -0,0 +1,15 @@
+{
+  "name": "session-message-banner",
+  "title": "SessionMessageBanner",
+  "description": "Top-of-page banner for session-scoped messages (promo nudges, abandoned cart prompts, low-stock alerts) with dismiss tracking.",
+  "type": "component",
+  "registryDependencies": [
+    "cn"
+  ],
+  "files": [
+    {
+      "path": "session-message-banner.tsx",
+      "content": "\"use client\";\n\nimport React from \"react\";\nimport type { SessionMessage } from \"../activity\";\nimport { useActivityState } from \"./hooks/use-activity-state\";\nimport { cn } from \"@cimplify/sdk/react\";\n\nexport interface SessionMessageBannerClassNames {\n  root?: string;\n  message?: string;\n  text?: string;\n  dismissButton?: string;\n  empty?: string;\n}\n\nexport interface SessionMessageBannerProps {\n  /** Override messages (skips fetch). For SSR, pass pre-fetched messages. */\n  messages?: SessionMessage[];\n  /** Called when a message is dismissed. Receives the message code. */\n  onDismiss?: (code: string) => void;\n  /** Custom message renderer. */\n  renderMessage?: (message: SessionMessage) => React.ReactNode;\n  className?: string;\n  classNames?: SessionMessageBannerClassNames;\n}\n\n/**\n * SessionMessageBanner — renders activity-based session messages.\n *\n * Displays dismissible message cards with level-based styling (info, promotion, urgency, suggestion).\n * Returns `null` when there are no messages.\n */\nexport function SessionMessageBanner({\n  messages: messagesProp,\n  onDismiss,\n  renderMessage,\n  className,\n  classNames,\n}: SessionMessageBannerProps): React.ReactElement | null {\n  const { messages: fetched, isLoading, dismissMessage } = useActivityState({\n    enabled: messagesProp === undefined,\n  });\n\n  const messages = messagesProp ?? fetched;\n\n  const handleDismiss = async (code: string): Promise<void> => {\n    if (onDismiss) {\n      onDismiss(code);\n    } else {\n      await dismissMessage(code);\n    }\n  };\n\n  if (isLoading && messages.length === 0) {\n    return (\n      <div\n        data-cimplify-session-message-banner\n        aria-busy=\"true\"\n        className={cn(className, classNames?.root)}\n      />\n    );\n  }\n\n  if (messages.length === 0) {\n    return null;\n  }\n\n  return (\n    <div data-cimplify-session-message-banner className={cn(className, classNames?.root)}>\n      {messages.map((msg) => (\n        <div\n          key={msg.code}\n          data-cimplify-session-message\n          data-level={msg.level}\n          className={classNames?.message}\n        >\n          {renderMessage ? (\n            renderMessage(msg)\n          ) : (\n            <>\n              <span data-cimplify-session-message-text className={classNames?.text}>\n                {msg.text}\n              </span>\n              {msg.dismissible && (\n                <button\n                  type=\"button\"\n                  onClick={() => void handleDismiss(msg.code)}\n                  data-cimplify-session-message-dismiss\n                  className={classNames?.dismissButton}\n                  aria-label=\"Dismiss message\"\n                >\n                  &times;\n                </button>\n              )}\n            </>\n          )}\n        </div>\n      ))}\n    </div>\n  );\n}\n"
+    }
+  ]
+}

package/templates/storefront-bakery/AGENTS.md

@@ -98,6 +98,18 @@ app/
 - `components/newsletter.tsx` (homepage strip) similarly fakes submit. Wire to a real list provider.
 - Hero / lookbook imagery is Unsplash placeholder — replace with merchant assets.
 
+## Customizing SDK components
+
+For anything beyond `lib/brand.ts` + `app/globals.css`, lean on the SDK's prebuilt components rather than reinvent. **Especially for product customization** (variants, add-ons, bundles, composites, services with scheduling) — the SDK already gets price math, axis matching, and cart payload contracts right. Default to ejecting and restyling:
+
+```bash
+bunx @cimplify/sdk add cart-drawer
+bunx @cimplify/sdk add variant-selector
+bunx @cimplify/sdk add product-page
+```
+
+Then edit the local copy. **Don't change the cart payload shape** unless you're also touching the SDK mock + backend lens. Full ejection rules and the customizer contract are in the SDK-level [`AGENTS.md`](../../AGENTS.md) → "Don't reinvent product customization".
+
 ## Quick start
 
 ```bash

package/templates/storefront-fashion/AGENTS.md

@@ -94,7 +94,27 @@ app/
 
 ## Mock seed
 
-Wired to `--seed retail` (Currents Electronics catalogue — the closest stand-in until an apparel seed ships). Replace with apparel data in production.
+Wired to `--seed fashion` (Studio FRX apparel catalogue — 14 products with size variants XS–2XL, Drop 04 + Best Sellers collections, full-bleed product imagery served from `static-tmp.cimplify.io`).
+
+## Customizing SDK components
+
+For anything beyond `lib/brand.ts` + `app/globals.css`, you'll likely want to lean on the SDK's prebuilt components rather than reinvent. Particularly for **product customization** (variants, add-ons, bundles, composites, services with scheduling), the SDK already gets the price math, variant axis matching, and cart payload contracts right. Default to ejecting and restyling:
+
+```bash
+bunx @cimplify/sdk add variant-selector    # copies into ./components/
+bunx @cimplify/sdk add cart-drawer
+bunx @cimplify/sdk add product-page
+```
+
+Then edit the local copy. **Don't change the cart payload shape** unless you're also touching the SDK's mock and the backend lens.
+
+If you're considering a from-scratch rebuild of the customizer, read these SDK source files first to understand the contract you must reproduce:
+- `src/react/product-customizer.tsx` — top-level state machine + final `onAddToCart` payload assembly
+- `src/react/variant-selector.tsx` — multi-axis matching via `display_attributes`; default-variant init runs in a `useEffect` and is easy to break
+- `src/react/{add-on,bundle,composite}-selector.tsx` — group constraints, exclusivity rules, per-component variants
+- `src/mock/domain/cart/{index,pricing}.ts` — the contract: `computeUnitPrice`, `computeBundlePrice`, `computeCompositePrice` (4 modes), `computeLineKey`
+
+Full ejection + customization rules are in the SDK-level [`AGENTS.md`](../../AGENTS.md) under "Don't reinvent product customization".
 
 ## Quick start
 

package/templates/storefront-grocery/AGENTS.md

@@ -74,6 +74,18 @@ app/
 - Contact + newsletter fake submits.
 - Hero / category / product imagery is Unsplash placeholder — replace with merchant photography.
 
+## Customizing SDK components
+
+For anything beyond `lib/brand.ts` + `app/globals.css`, lean on the SDK's prebuilt components rather than reinvent. **Especially for product customization** (variants, add-ons, bundles, composites) — the SDK already gets price math, axis matching, and cart payload contracts right. Default to ejecting and restyling:
+
+```bash
+bunx @cimplify/sdk add cart-drawer
+bunx @cimplify/sdk add add-on-selector
+bunx @cimplify/sdk add product-page
+```
+
+Then edit the local copy. **Don't change the cart payload shape** unless you're also touching the SDK mock + backend lens. Full ejection rules and the customizer contract are in the SDK-level [`AGENTS.md`](../../AGENTS.md) → "Don't reinvent product customization".
+
 ## Quick start
 
 ```bash

package/templates/storefront-restaurant/AGENTS.md

@@ -80,6 +80,18 @@ app/
 - Contact form + newsletter fake their submits.
 - Hero / dish photography is Unsplash — replace with merchant photos.
 
+## Customizing SDK components
+
+For anything beyond `lib/brand.ts` + `app/globals.css`, lean on the SDK's prebuilt components rather than reinvent. **Especially for product customization** (variants, add-ons, bundles, composites, services with scheduling) — the SDK already gets price math, axis matching, and cart payload contracts right. Default to ejecting and restyling:
+
+```bash
+bunx @cimplify/sdk add cart-drawer
+bunx @cimplify/sdk add add-on-selector
+bunx @cimplify/sdk add product-page
+```
+
+Then edit the local copy. **Don't change the cart payload shape** unless you're also touching the SDK mock + backend lens. Full ejection rules and the customizer contract are in the SDK-level [`AGENTS.md`](../../AGENTS.md) → "Don't reinvent product customization".
+
 ## Quick start
 
 ```bash

package/templates/storefront-retail/AGENTS.md

@@ -95,6 +95,18 @@ app/
 
 Wired to `--seed retail` (Currents Electronics). Edit `dev:mock` in `package.json` to preview another seed.
 
+## Customizing SDK components
+
+For anything beyond `lib/brand.ts` + `app/globals.css`, lean on the SDK's prebuilt components rather than reinvent. **Especially for product customization** (variants, add-ons, bundles, composites, services with scheduling) — the SDK already gets price math, axis matching, and cart payload contracts right. Default to ejecting and restyling:
+
+```bash
+bunx @cimplify/sdk add cart-drawer
+bunx @cimplify/sdk add variant-selector
+bunx @cimplify/sdk add product-page
+```
+
+Then edit the local copy. **Don't change the cart payload shape** unless you're also touching the SDK mock + backend lens. Full ejection rules and the customizer contract are in the SDK-level [`AGENTS.md`](../../AGENTS.md) → "Don't reinvent product customization".
+
 ## Quick start
 
 ```bash

package/templates/storefront-services/AGENTS.md

@@ -79,6 +79,18 @@ app/
 - `/book` widget shows every slot as available. For production, wire `useAvailableSlots({ serviceId, date })` from `@cimplify/sdk/react` to filter to genuinely-free windows.
 - Contact + newsletter fake submits.
 
+## Customizing SDK components
+
+For anything beyond `lib/brand.ts` + `app/globals.css`, lean on the SDK's prebuilt components rather than reinvent. **Especially for service scheduling, booking widgets, and add-on selectors** — the SDK already gets price math, slot matching, and cart payload contracts right. Default to ejecting and restyling:
+
+```bash
+bunx @cimplify/sdk add cart-drawer
+bunx @cimplify/sdk add product-page
+bunx @cimplify/sdk add booking-card
+```
+
+Then edit the local copy. **Don't change the cart payload shape** (`scheduled_start`, `scheduled_end`, `staff_id`, `customer_inputs`, etc.) unless you're also touching the SDK mock + backend lens. Full ejection rules and the customizer contract are in the SDK-level [`AGENTS.md`](../../AGENTS.md) → "Don't reinvent product customization".
+
 ## Quick start
 
 ```bash