create-cartbase 0.1.15 → 0.1.17

package/template/app/docs/components.md

@@ -603,10 +603,21 @@ Domain doc for every call: [carts.md](carts.md); gift-card tender:
   no metadata on update; quantity 0 deletes), `deleteLineItem`. Every
   mutation returns the FULL decorated cart, which becomes the confirmed
   snapshot — no page refetch needed.
+- **The instant cart (since 0.18.0)** — every change shows at once and
+  reaches the platform through ONE queue (`cart-drawer/mutation-queue`,
+  `createCartMutationQueue`): one call at a time, each reading the cart the
+  answer before it left, so two answers never overwrite each other and a
+  second add never creates a second cart. Fast quantity clicks on one line
+  send the number the shopper stopped at; the stepper never locks. A line
+  added a moment ago carries `pending: true` and a placeholder id
+  (`isPendingLine(line)`); its quantity and removal work at once and are
+  sent to the real line when the platform has confirmed it.
 - **Props contract** — `cart?: Cart|null` (server-fetched snapshot; prop
-  updates win), `client?: StorefrontClient` (enables `addItem`/
-  `updateQuantity`/`removeItem`/`refresh`), `cartId?` (retrieve-on-mount
-  when no snapshot), `onCartChange?(cart)` (fires on every confirmed
+  updates win unless a change of the provider's own is on its way; leave it
+  out and pass `cartId` so the page never waits for the cart),
+  `client?: StorefrontClient` (enables `addLine`/`addItem`/
+  `updateQuantity`/`removeItem`/`refresh`), `cartId?` (read in the browser
+  on mount, through the queue, when no snapshot), `onCartChange?(cart)` (fires on every confirmed
   change INCLUDING first-add cart creation — persist `cart.id` here),
   `onOptimisticError?(failure)` (the ops funnel for every failed
   optimistic mutation — wire to store logging; replaces the source's
@@ -614,10 +625,13 @@ Domain doc for every call: [carts.md](carts.md); gift-card tender:
   the language mounted by `StorefrontLocaleProvider` is the default),
   `hrefs?: {checkout, browse, productPrefix}`.
 - **Hook** — `useCartDrawer()` → `{isOpen, open, close, toggle, cart,
-  addItem(variantId, qty?, display?), updateQuantity(lineId, qty),
-  removeItem(lineId), refresh, applyOptimistic, dispatchOptimistic,
-  labels, hrefs}`. `applyOptimistic(action, serverAction)` stays for
-  store-owned server actions (PDP add via RSC).
+  addLine(variantId, qty?, display?)` (answers `{ok: true, cart}` or
+  `{ok: false, error}`, the platform's refusal with its `code`),
+  `addItem(variantId, qty?, display?)` (the same, answering a boolean),
+  `updateQuantity(lineId, qty), removeItem(lineId), refresh, canMutate,
+  applyOptimistic, dispatchOptimistic, labels, hrefs}`.
+  `applyOptimistic(action, serverAction)` stays for store-owned server
+  actions; the SDK methods are the fast path.
 - **Settings** — store default region + enabled currencies (cart create),
   B2B price lists via attached customer, gift-card product flags
   (`is_giftcard` lines are non-discountable), automatic promotions,
@@ -664,7 +678,7 @@ Domain doc for every call: [carts.md](carts.md); gift-card tender:
   per-item upsell slot.
 - Subcomponents: `item/quantity` (`<CartItemQuantity lineId quantity
   maxQuantity? />` — stepper floor 1, calls `updateQuantity` with
-  `{quantity}`), `item/variant` (`<CartItemVariant variantTitle
+  `{quantity}` on every click and never locks), `item/variant` (`<CartItemVariant variantTitle
   options? />` — Cartbase lines carry the flat `variant_title` string, not
   an embedded variant object), `item/upsell` (`<CartItemUpsell products
   onAdd />` — feed from `listRelatedProducts`, `variantId` included so
@@ -765,8 +779,12 @@ components read copy only through the context or explicit `labels` props).
 - **SDK calls** — none (props: `product.thumbnail` / `product.images`).
 - **Props** — `size: "small"|"medium"|"large"|"full"|"square"` (aspect +
   width), `isFeatured` (11/14 aspect), `className`.
-- **Mount rules** — server-safe; uses `next/image` (host must allow the
-  media domain in `next.config` images).
+- **Mount rules** — server-safe; renders through `StoreImage`
+  (`@cartbase/storefront/lib/media-image`), `next/image` with resizing on
+  for the Cartbase media CDN (`cartbase.cloud`, allowed in the scaffold's
+  `next.config` images) and off for any other host, so a picture from
+  elsewhere renders as it is instead of failing the page. Use `StoreImage`
+  for your own pictures too, or add your hosts to `remotePatterns`.
 
 ### `<PreviewPrice price />` — `products/preview-price`
 
@@ -795,7 +813,7 @@ components read copy only through the context or explicit `labels` props).
 
 ### The product page contract — `products/variant-url`, `products/use-product-actions`
 
-Five rules every buy panel is held to, the package's own and a store's:
+Six rules every buy panel is held to, the package's own and a store's:
 
 1. **The address is the state.** The chosen variant is named in the URL as
    `?variant=<id>`, Shopify's parameter, so a link copied from an email, an
@@ -817,11 +835,17 @@ Five rules every buy panel is held to, the package's own and a store's:
    the admin shows; never the wire's first variant, which is the database's
    scan order.
 5. **The server is asked only for what needs it:** adding to the cart.
+6. **The add is instant** (since 0.18.0). With no `addToCart` passed, the
+   add goes through the mounted `CartDrawerProvider` (`addLine`): the
+   drawer opens at the click with the product already in it, the platform
+   confirms behind it, and no page render runs. A store that passes its
+   own `addToCart` server action keeps the old path (await it, open the
+   cart, refresh the page so a server-rendered cart follows).
 
 `products/variant-url` is the pure half (`VARIANT_PARAM`,
 `variantParamValue`, `findVariantByParam`, `defaultVariant`, `variantHref`;
 unit-tested in tests/unit/storefront-product-page-contract.test.ts).
-`useProductActions({product, addToCart, initialVariantId?, onAddToCart?,
+`useProductActions({product, addToCart?, initialVariantId?, onAddToCart?,
 openCart?, syncAddress?})` is the behaviour as a headless hook: the chosen
 values, `choose`, the resolved `variant`, `quantity`/`setQuantity`,
 `inStock` (the server's `in_stock` predicate, never re-derived;
@@ -831,6 +855,19 @@ hook and inherits every rule; `ProductActions` below is the package's own
 panel on the same hook. Client hook; it reads `useSearchParams`, so mount it
 under a `<Suspense>` boundary on a static page (a dynamic page needs none).
 
+### Pure: `products/sets` (sets from kit links)
+
+A set is an inventory kit: its variant draws on the stock items of the
+products inside it. Pass `fields: SET_FIELDS` to `listProducts` or
+`retrieveProduct` and every variant carries `inventory_items`; then
+`setContents(product, variant)` names what a set holds (product, variant,
+title, handle, picture, how many), `setContentsByVariant(products)` keys
+that by variant for a page of products, and `setsContaining(product,
+variant)` names the products holding this variant's own item, the sets it
+is in. `linkOwner(link, productId)` is the rule underneath: an item's owner
+is the other product's variant carrying the item's SKU. Unit-tested
+(tests/unit/storefront-sets.test.ts).
+
 ### Pure: `products/variant-matching` (extra module, Cartbase addition)
 
 `optionsAsKeymap` / `optionsMatch` / `findMatchingVariant` — the
@@ -846,7 +883,7 @@ with a legacy flat-row fallback. Unit-tested
   images `priority`.
 - **SDK calls** — none (props: `product.images`). Server-safe.
 
-### `<ProductActions product addToCart initialVariantId? disabled? onAddToCart? openCart? showQuantity? />` — `products/product-actions`
+### `<ProductActions product addToCart? initialVariantId? disabled? onAddToCart? openCart? showQuantity? />` — `products/product-actions`
 
 - **Purpose** — the package's own buy panel on `useProductActions`: option
   rows, price, the quantity stepper (`showQuantity`, on by default), the

package/template/app/docs/consent.md

@@ -1,91 +1,91 @@
-# Consent
-
-The store's CMP configuration for the built-in Consent Mode v2 banner
-(consent-management card). Defaults are **always applied server-side**, so
-the payload is complete and renderable even for an unconfigured store
-(compliant built-in modal, BG + EN copy shipped).
-
-## Storefront wiring (the trap that matters)
-
-- Mount `<ConsentInit required={consent.enabled}>` as the **first child of
-  `<body>`** — it sets the synchronous Consent Mode v2 DEFAULT and must
-  **never wait on this fetch in the browser** (async default = first-hit
-  consent race). Resolve this config server-side (RSC) and inline the
-  setting into the document; the prop is required, a layout without it
-  does not compile.
-- **The switch decides the default; a stored choice wins.** `enabled: true`
-  is a store that collects consent: every visitor starts DENIED until they
-  choose on the banner. `enabled: false` is a store with no consent gate:
-  every visitor starts GRANTED, and every configured pixel fires. Either
-  way a choice already in the `_1c_consent` cookie is what counts, so a
-  visitor who declined keeps that decision if the banner is switched off.
-- Render the built-in banner only when `enabled && mode === "builtin"`.
-- `mode: "external"` = the merchant's CMP owns the UI and must write the
-  same `_1c_consent` cookie (or call `setConsent()`) — all Cartbase-side tag
-  gating works off that one seam.
-- Choices persist 12 months in the cookie. Rybbit (platform analytics)
-  stays outside consent by design.
-- Pair with [integrations.md](integrations.md): `tracking.consent_required`
-  mirrors `enabled` here, and `<StorefrontTags>` hands it to every pixel
-  that gates its own SDK (Meta, TikTok, ChatGPT). Google reads the
-  `<ConsentInit>` default.
-
-## GET /api/store/consent — the CMP config
-
-- **Purpose**: everything the banner needs to render, per locale.
-- **Auth**: anon (`x-client-id`).
-- **Request**: no params.
-- **Response** — the EXACT allowlist (nothing else will ever appear here):
-
-```jsonc
-{
-  "consent": {
-    "enabled": true,
-    "mode": "builtin",              // "builtin" | "external"
-    "layout": "modal",              // "modal" (blocking) | "banner-bottom" (non-blocking)
-    "privacy_href": "/cookies",
-    "reject_on_first_layer": false,
-    "copy": {
-      "bg": {
-        "title": "Преди да продължиш",
-        "body": "…",
-        "privacy_link_label": "…",
-        "accept_label": "…", "settings_label": "…", "reject_label": "…",
-        "settings_title": "…",
-        "accept_all_label": "…", "save_label": "…", "reject_all_label": "…",
-        "necessary_label": "…", "necessary_description": "…",
-        "analytics_label": "…", "analytics_description": "…",
-        "ads_label": "…", "ads_description": "…"
-      },
-      "en": { /* same 16 keys — every field always present per locale */ }
-    }
-  }
-}
-```
-
-- **Errors**: `400 missing_client_id` only — the payload itself always
-  succeeds (a corrupt/missing stored config degrades to defaults, never to
-  a broken banner).
-- **SDK**: `consent.getConsent(client)`
-- **Components**: `<ConsentInit required={consent.enabled}>` +
-  `<ConsentBanner copy={copy[locale]} layout privacyHref
-  rejectOnFirstLayer>` (consent family; reference impl
-  `src/components/storefront/consent/`).
-- **Settings**: admin → Settings → Consent (enabled/mode/layout/
-  privacy_href/copy per locale).
-
-```bash
-# Complete, renderable config — even on an unconfigured store the defaults
-# make every documented key present.
-BODY=$(curl -sf "$BASE/api/store/consent" -H "x-client-id: $CLIENT_ID")
-echo "$BODY" | grep -q '"consent"'
-echo "$BODY" | grep -q '"mode"'
-echo "$BODY" | grep -q '"layout"'
-echo "$BODY" | grep -q '"privacy_href"'
-echo "$BODY" | grep -q '"reject_on_first_layer"'
-echo "$BODY" | grep -q '"analytics_label"'
-echo "$BODY" | grep -q '"ads_description"'
-# Missing tenant header → the standard 400.
-STATUS=$(curl -s -o /dev/null -w '%{http_code}' "$BASE/api/store/consent")
-test "$STATUS" = 400
-```
+# Consent
+
+The store's CMP configuration for the built-in Consent Mode v2 banner
+(consent-management card). Defaults are **always applied server-side**, so
+the payload is complete and renderable even for an unconfigured store
+(compliant built-in modal, BG + EN copy shipped).
+
+## Storefront wiring (the trap that matters)
+
+- Mount `<ConsentInit required={consent.enabled}>` as the **first child of
+  `<body>`** — it sets the synchronous Consent Mode v2 DEFAULT and must
+  **never wait on this fetch in the browser** (async default = first-hit
+  consent race). Resolve this config server-side (RSC) and inline the
+  setting into the document; the prop is required, a layout without it
+  does not compile.
+- **The switch decides the default; a stored choice wins.** `enabled: true`
+  is a store that collects consent: every visitor starts DENIED until they
+  choose on the banner. `enabled: false` is a store with no consent gate:
+  every visitor starts GRANTED, and every configured pixel fires. Either
+  way a choice already in the `_1c_consent` cookie is what counts, so a
+  visitor who declined keeps that decision if the banner is switched off.
+- Render the built-in banner only when `enabled && mode === "builtin"`.
+- `mode: "external"` = the merchant's CMP owns the UI and must write the
+  same `_1c_consent` cookie (or call `setConsent()`) — all Cartbase-side tag
+  gating works off that one seam.
+- Choices persist 12 months in the cookie. Rybbit (platform analytics)
+  stays outside consent by design.
+- Pair with [integrations.md](integrations.md): `tracking.consent_required`
+  mirrors `enabled` here, and `<StorefrontTags>` hands it to every pixel
+  that gates its own SDK (Meta, TikTok, ChatGPT). Google reads the
+  `<ConsentInit>` default.
+
+## GET /api/store/consent — the CMP config
+
+- **Purpose**: everything the banner needs to render, per locale.
+- **Auth**: anon (`x-client-id`).
+- **Request**: no params.
+- **Response** — the EXACT allowlist (nothing else will ever appear here):
+
+```jsonc
+{
+  "consent": {
+    "enabled": true,
+    "mode": "builtin",              // "builtin" | "external"
+    "layout": "modal",              // "modal" (blocking) | "banner-bottom" (non-blocking)
+    "privacy_href": "/cookies",
+    "reject_on_first_layer": false,
+    "copy": {
+      "bg": {
+        "title": "Преди да продължиш",
+        "body": "…",
+        "privacy_link_label": "…",
+        "accept_label": "…", "settings_label": "…", "reject_label": "…",
+        "settings_title": "…",
+        "accept_all_label": "…", "save_label": "…", "reject_all_label": "…",
+        "necessary_label": "…", "necessary_description": "…",
+        "analytics_label": "…", "analytics_description": "…",
+        "ads_label": "…", "ads_description": "…"
+      },
+      "en": { /* same 16 keys — every field always present per locale */ }
+    }
+  }
+}
+```
+
+- **Errors**: `400 missing_client_id` only — the payload itself always
+  succeeds (a corrupt/missing stored config degrades to defaults, never to
+  a broken banner).
+- **SDK**: `consent.getConsent(client)`
+- **Components**: `<ConsentInit required={consent.enabled}>` +
+  `<ConsentBanner copy={copy[locale]} layout privacyHref
+  rejectOnFirstLayer>` (consent family; reference impl
+  `src/components/storefront/consent/`).
+- **Settings**: admin → Settings → Consent (enabled/mode/layout/
+  privacy_href/copy per locale).
+
+```bash
+# Complete, renderable config — even on an unconfigured store the defaults
+# make every documented key present.
+BODY=$(curl -sf "$BASE/api/store/consent" -H "x-client-id: $CLIENT_ID")
+echo "$BODY" | grep -q '"consent"'
+echo "$BODY" | grep -q '"mode"'
+echo "$BODY" | grep -q '"layout"'
+echo "$BODY" | grep -q '"privacy_href"'
+echo "$BODY" | grep -q '"reject_on_first_layer"'
+echo "$BODY" | grep -q '"analytics_label"'
+echo "$BODY" | grep -q '"ads_description"'
+# Missing tenant header → the standard 400.
+STATUS=$(curl -s -o /dev/null -w '%{http_code}' "$BASE/api/store/consent")
+test "$STATUS" = 400
+```