@ikas/code-components-mcp 1.4.0-beta.166 → 1.4.0-beta.168

package/data/framework.json

@@ -249,7 +249,7 @@
     "async-data-patterns": {
       "title": "Async Data & Loading Patterns",
       "description": "How to handle async operations, loading states, and store data in ikas components",
-      "content": "## Async Data & Loading Patterns\n\n### 1. Store State is Null Until Initialized\n\n**Note:** Root component exports are automatically reactive via the ikas runtime's `autorun()` — no `observer()` needed. The examples below show `observer()` on **sub-components** that independently read store data.\n\nStore data (`cartStore.cart`, `customerStore.customer`) is `null` until the store initializes. Use null-safe access:\n\n```tsx\nimport { observer } from \"@ikas/component-utils\";\nimport { cartStore } from \"@ikas/bp-storefront\";\n\n// Sub-component: needs observer() for independent reactivity\nconst CartBadge = observer(function CartBadge() {\n  // cart is null until initialized — use optional chaining\n  const itemCount = cartStore.cart?.orderLineItems.length ?? 0;\n  return <span className=\"cart-badge\">{itemCount}</span>;\n});\n```\n\n### 2. Loading Pattern for Async Operations\n\nUse `useState` for local loading flags. Always use `try/finally` to clear the loading state:\n\n```tsx\nimport { useState } from \"preact/hooks\";\nimport { addItemToCart } from \"@ikas/bp-storefront\";\n\nconst [isLoading, setIsLoading] = useState(false);\n\nconst handleAddToCart = async () => {\n  if (isLoading) return; // prevent double-click\n  setIsLoading(true);\n  try {\n    await addItemToCart(variant, product, 1);\n  } finally {\n    setIsLoading(false);\n  }\n};\n\n// In JSX:\n<button disabled={isLoading} onClick={handleAddToCart}>\n  {isLoading ? \"Adding...\" : \"Add to Cart\"}\n</button>\n```\n\n### 3. Cart Operation Results\n\n`addItemToCart` returns a result object. Check for validation errors:\n\n```tsx\nconst result = await addItemToCart(variant, product, 1);\nif (result.success) {\n  // Item added successfully\n} else if (result.validationError === \"INSUFFICIENT_STOCK\") {\n  // Not enough stock\n} else if (result.validationError === \"INVALID_PRODUCT_OPTION_VALUES\") {\n  // Variant options not fully selected\n}\n```\n\n### 4. Form Submission Results\n\nForm submit functions return `boolean` and set status flags on the form:\n\n```tsx\nconst success = await submitLoginForm(loginForm);\nif (success) {\n  // loginForm.isSuccess is true\n  Router.navigate(\"/account\");\n} else {\n  // loginForm.isFailure is true\n  // loginForm.responseMessage has the error message\n  console.log(loginForm.responseMessage);\n}\n```\n\n### 5. Observer Auto Re-rendering\n\nStore updates automatically trigger re-renders. Root components get this via `autorun()`, sub-components via `observer()`. You do NOT need manual state management for store-derived values:\n\n```tsx\n// WRONG — unnecessary useState for store data\nconst [cartItems, setCartItems] = useState([]);\nuseEffect(() => { setCartItems(cartStore.cart?.orderLineItems ?? []); }, [cartStore.cart]);\n\n// CORRECT — observer sub-component for independent reactivity\nconst CartList = observer(function CartList() {\n  const items = cartStore.cart?.orderLineItems ?? [];\n  return (\n    <div>\n      {items.map((item) => (\n        <div key={item.id}>{item.variant?.name}</div>\n      ))}\n    </div>\n  );\n});\n\n// Root export uses CartList — no observer needed on root\nexport function CartPage({ title }: Props) {\n  return (\n    <section>\n      <h1>{title}</h1>\n      <CartList />\n    </section>\n  );\n}\n\nexport default CartPage;\n```\n\n### 6. Pagination / Data Fetching\n\nList stores (blog, brand, category) use async pagination functions:\n\n```tsx\nimport { hasBlogListNextPage, getBlogListNextPage } from \"@ikas/bp-storefront\";\n\n// Check if more pages exist\nif (hasBlogListNextPage(blogList)) {\n  // Fetch next page — mutates blogList in place, observer re-renders\n  await getBlogListNextPage(blogList);\n}\n```\n\nThese functions mutate the list model in place. If your component uses `observer()`, it will re-render automatically when new data arrives.",
+      "content": "## Async Data & Loading Patterns\n\n### 1. Store State is Null Until Initialized\n\n**Note:** Root component exports are automatically reactive via the ikas runtime's `autorun()` — no `observer()` needed. The examples below show `observer()` on **sub-components** that independently read store data.\n\nStore data (`cartStore.cart`, `customerStore.customer`) is `null` until the store initializes. Use null-safe access:\n\n```tsx\nimport { observer } from \"@ikas/component-utils\";\nimport { cartStore } from \"@ikas/bp-storefront\";\n\n// Sub-component: needs observer() for independent reactivity\nconst CartBadge = observer(function CartBadge() {\n  // cart is null until initialized — use optional chaining\n  const itemCount = cartStore.cart?.orderLineItems.length ?? 0;\n  return <span className=\"cart-badge\">{itemCount}</span>;\n});\n```\n\n### 2. Loading Pattern for Async Operations\n\nUse `useState` for local loading flags. Always use `try/finally` to clear the loading state:\n\n```tsx\nimport { useState } from \"preact/hooks\";\nimport { addItemToCart } from \"@ikas/bp-storefront\";\n\nconst [isLoading, setIsLoading] = useState(false);\n\nconst handleAddToCart = async () => {\n  if (isLoading) return; // prevent double-click\n  setIsLoading(true);\n  try {\n    await addItemToCart(variant, product, 1);\n  } finally {\n    setIsLoading(false);\n  }\n};\n\n// In JSX:\n<button disabled={isLoading} onClick={handleAddToCart}>\n  {isLoading ? \"Adding...\" : \"Add to Cart\"}\n</button>\n```\n\n### 3. Cart Operation Results\n\n`addItemToCart` returns a result object. Check for validation errors:\n\n```tsx\nconst result = await addItemToCart(variant, product, 1);\nif (result.success) {\n  // Item added successfully\n} else if (result.validationError === \"INSUFFICIENT_STOCK\") {\n  // Not enough stock\n} else if (result.validationError === \"INVALID_PRODUCT_OPTION_VALUES\") {\n  // Variant options not fully selected\n}\n```\n\n### 4. Form Submission Results\n\nForm submit functions return `boolean` and set status flags on the form:\n\n```tsx\nconst success = await submitLoginForm(loginForm);\nif (success) {\n  // loginForm.isSuccess is true\n  Router.navigate(\"/account\");\n} else {\n  // loginForm.isFailure is true\n  // loginForm.responseMessage has the error message\n  console.log(loginForm.responseMessage);\n}\n```\n\n### 5. Observer Auto Re-rendering\n\nStore updates automatically trigger re-renders. Root components get this via `autorun()`, sub-components via `observer()`. You do NOT need manual state management for store-derived values:\n\n```tsx\n// WRONG — unnecessary useState for store data\nconst [cartItems, setCartItems] = useState([]);\nuseEffect(() => { setCartItems(cartStore.cart?.orderLineItems ?? []); }, [cartStore.cart]);\n\n// CORRECT — observer sub-component for independent reactivity\nconst CartList = observer(function CartList() {\n  const items = cartStore.cart?.orderLineItems ?? [];\n  return (\n    <div>\n      {items.map((item) => (\n        <div key={item.id}>{item.variant?.name}</div>\n      ))}\n    </div>\n  );\n});\n\n// Root export uses CartList — no observer needed on root\nexport function CartPage({ title }: Props) {\n  return (\n    <section>\n      <h1>{title}</h1>\n      <CartList />\n    </section>\n  );\n}\n\nexport default CartPage;\n```\n\n### 6. Pagination / Data Fetching\n\nList stores (blog, brand, category) use async pagination functions:\n\n```tsx\nimport { hasBlogListNextPage, getBlogListNextPage } from \"@ikas/bp-storefront\";\n\n// Check if more pages exist\nif (hasBlogListNextPage(blogList)) {\n  // Fetch next page — mutates blogList in place, observer re-renders\n  await getBlogListNextPage(blogList);\n}\n```\n\nThese functions mutate the list model in place. If your component uses `observer()`, it will re-render automatically when new data arrives.\n\nTo batch-fetch full products by id — e.g. enriching cart lines with the `salesChannels` limits or per-variant `stock` they don't carry — use `bs_searchProductsById(baseStore, { productIds })`: one request for all ids. See the \"Enforcing Limits on Cart Lines\" section in the `cart-patterns` guide for the full pattern.",
       "tags": [
         "async",
         "loading",
@@ -326,7 +326,7 @@
     "cart-patterns": {
       "title": "Cart Management Patterns (Serel Reference)",
       "description": "Serel CartPage section with CartItem sub-component, OrderSummary/CouponCode/EmptyState local components, cartStore patterns, and checkout flow",
-      "content": "## Cart Management Patterns (Serel Reference)\n\nThe serel CartPage is a section that uses local internal components (OrderSummary, CouponCode, EmptyState) and the shared `CartItem` sub-component from `src/sub-components/CartItem/`. Unlike most sections, CartPage does NOT use IkasComponentRenderer — it directly composes its UI from sub-components.\n\n### CartPage Section Structure\n\n```tsx\nimport { cartStore } from \"@ikas/bp-storefront\";\nimport CartItem from \"../../sub-components/CartItem\";\nimport { Props } from \"./types\";\n\nexport function CartPage({ backgroundColor, emptyCartText, ...props }: Props) {\n  const cart = cartStore.cart;\n  const lineItems = cart?.orderLineItems ?? [];\n  const isEmpty = lineItems.length === 0;\n\n  if (isEmpty) return <EmptyState text={emptyCartText} />;\n\n  return (\n    <section className=\"cart-page\" style={backgroundColor ? { backgroundColor } : undefined}>\n      <div className=\"cart-page-inner\">\n        <div className=\"cart-items\">\n          {lineItems.map((item) => (\n            <CartItem key={item.id} item={item} />\n          ))}\n        </div>\n        <div className=\"cart-sidebar\">\n          <CouponCode cart={cart} />\n          <OrderSummary cart={cart} />\n        </div>\n      </div>\n    </section>\n  );\n}\nexport default CartPage;\n```\n\n### CartItem Sub-Component\n\nThe `CartItem` sub-component (in `src/sub-components/CartItem/`) displays a single line item with image, variant name, quantity controls, price, and remove button:\n\n```tsx\nimport {\n  getOrderLineItemFormattedFinalPrice,\n  getOrderLineItemFormattedUnitPrice,\n  getIkasOrderLineVariantMainImage,\n  getDefaultSrc,\n  changeItemQuantity,\n  removeItem,\n  IkasOrderLineItem,\n} from \"@ikas/bp-storefront\";\nimport QuantitySelector from \"../QuantitySelector\";\n\ninterface Props { item: IkasOrderLineItem; }\n\nexport default function CartItem({ item }: Props) {\n  const image = item.variant ? getIkasOrderLineVariantMainImage(item.variant) : null;\n\n  return (\n    <div className=\"cart-item\">\n      {image && <img src={getDefaultSrc(image)} alt={item.variant?.name} />}\n      <div className=\"cart-item-info\">\n        <span>{item.variant?.name}</span>\n        <span>{getOrderLineItemFormattedUnitPrice(item)}</span>\n      </div>\n      <QuantitySelector\n        quantity={item.quantity}\n        onIncrement={() => changeItemQuantity(item, item.quantity + 1)}\n        onDecrement={() => changeItemQuantity(item, Math.max(1, item.quantity - 1))}\n      />\n      <span>{getOrderLineItemFormattedFinalPrice(item)}</span>\n      <button onClick={() => removeItem(item)}>Remove</button>\n    </div>\n  );\n}\n```\n\n### OrderSummary Local Component\n\nDisplays cart totals using `getIkasOrderFormattedTotalFinalPrice(cart)` and `getIkasOrderFormattedTotalPrice(cart)`, plus a checkout button:\n\n```tsx\nimport { Router, getIkasOrderFormattedTotalFinalPrice } from \"@ikas/bp-storefront\";\n\nfunction OrderSummary({ cart }) {\n  return (\n    <div className=\"order-summary\">\n      <span>Total: {getIkasOrderFormattedTotalFinalPrice(cart)}</span>\n      <button onClick={() => Router.navigateToPage(\"CHECKOUT\")}>Checkout</button>\n    </div>\n  );\n}\n```\n\n### CouponCode Local Component\n\nCoupon code uses the standard form model. Get the form from `customerStore` via `getCouponCodeForm`, init it once, drive the input with `setCouponCodeFormCouponCode`, and submit/remove with the form helpers. Do NOT call `saveCart`/`apiSaveCart` or any deep `@ikas/bp-storefront/dist/...` import — the coupon has dedicated public exports:\n\n```tsx\nimport { useEffect } from \"preact/hooks\";\nimport {\n  customerStore,\n  getCouponCodeForm,\n  initCouponCodeForm,\n  setCouponCodeFormCouponCode,\n  submitCouponCodeForm,\n  removeCouponCodeForm,\n} from \"@ikas/bp-storefront\";\nimport { observer } from \"@ikas/component-utils\";\n\n// observer() because this sub-component reads the MobX coupon form\nconst CouponCode = observer(function CouponCode({ appliedCoupon }) {\n  const couponForm = getCouponCodeForm(customerStore);\n\n  useEffect(() => {\n    initCouponCodeForm(couponForm);\n  }, [couponForm]);\n\n  const handleSubmit = async (e: Event) => {\n    e.preventDefault();\n    await submitCouponCodeForm(couponForm);\n  };\n\n  if (appliedCoupon) {\n    return (\n      <div className=\"coupon\">\n        <span>{appliedCoupon}</span>\n        <button type=\"button\" onClick={() => removeCouponCodeForm(couponForm)}>Remove</button>\n      </div>\n    );\n  }\n\n  return (\n    <form className=\"coupon\" onSubmit={handleSubmit}>\n      <input\n        placeholder={couponForm.couponCode?.placeholder ?? \"Coupon code\"}\n        value={couponForm.couponCode?.value ?? \"\"}\n        onInput={(e) =>\n          setCouponCodeFormCouponCode(couponForm, (e.target as HTMLInputElement).value)\n        }\n      />\n      <button type=\"submit\" disabled={couponForm.isSubmitting}>\n        {couponForm.isSubmitting ? \"Applying...\" : \"Apply\"}\n      </button>\n      {couponForm.isFailure && couponForm.responseMessage && (\n        <p className=\"coupon-error\">{couponForm.responseMessage}</p>\n      )}\n    </form>\n  );\n});\n```\n\n### cartStore Usage Patterns\n\nThe `cartStore` is a MobX store available globally. Root components are automatically reactive via autorun, so reads from `cartStore.cart` trigger re-renders:\n\n```tsx\nimport { cartStore } from \"@ikas/bp-storefront\";\n\n// Always null-safe:\nconst cart = cartStore.cart;\nconst lineItems = cart?.orderLineItems ?? [];\nconst itemCount = lineItems.length;\nconst isEmpty = itemCount === 0;\n```\n\n### Quantity Limits (min/max per cart)\n\nA product's sales channel can cap how many units go into one cart. The limits live on the product's `salesChannels`, matched to the active channel:\n\n```tsx\nimport { IkasStorefrontConfig } from \"@ikas/bp-storefront\";\n\nconst channel = product.salesChannels?.find((sc) => sc.id === IkasStorefrontConfig.salesChannelId);\nconst min = channel?.minQuantityPerCart ?? 1;\nconst max = channel?.maxQuantityPerCart; // null/undefined = no cap\n```\n\nApply these to the quantity stepper: seed the initial quantity to `min`, and cap increments at `max`. `addItemToCart(variant, product, qty)` clamps to the same limits internally only when it creates a **new** cart line — and silently, so enforce them in the UI too or the customer sees the number snap with no explanation.\n\n> **The internal clamp only runs when a NEW cart line is created.** If the variant already has a line in the cart, `addItemToCart` delegates to `changeItemQuantity(existing, existing.quantity + qty)` before the clamp is reached — and `changeItemQuantity` never clamps. Cart page / cart drawer steppers therefore get no SDK enforcement at all; enforce the limits in the UI (see \"Enforcing Limits on Cart Lines\" below).\n\n> `IkasStorefrontConfig.salesChannelId` is a property. The older `getSalesChannelId()` method does not exist in this SDK.\n\n### Cart Operation validationError (complete list)\n\n`addItemToCart` / `changeItemQuantity` return `IkasCartOperationResult` — `{ success, validationError?, response? }`. The `validationError` union has exactly three values, but at runtime only `addItemToCart` ever sets it (client-side pre-validation before the API call). `changeItemQuantity` does no client-side validation and never returns a `validationError` — branch on `success` (and `response.errorCodes` for details), not on `validationError`, for cart-line quantity changes:\n\n| Value | Meaning |\n|-------|---------|\n| `INSUFFICIENT_STOCK` | Not enough stock for the requested quantity |\n| `INVALID_PRODUCT_OPTION_VALUES` | Required product options not fully or validly selected |\n| `EMPTY_CART` | The operation needs a non-empty cart (declared in the type union, but no current code path emits it) |\n\nQuantity limits are never surfaced as a `validationError` — there is **no** `MAX_QUANTITY_PER_CART_*` / `MIN_QUANTITY_PER_CART_*` value beyond the three above. Note the distinction: legacy v1 themes branched on the GraphQL error code `MAX_QUANTITY_PER_CART_LIMIT_REACHED` (an `extensions.code` value, which the API client copies into `response.errorCodes` unfiltered), but that code is not a documented contract of this SDK — do not rely on it. Prevent limit violations in the stepper instead (see \"Quantity Limits\" above and \"Enforcing Limits on Cart Lines\" below).\n\n### Enforcing Limits on Cart Lines\n\nCart lines cannot tell you the limits: `IkasOrderLineItem.variant` is an `IkasOrderLineVariant`, which carries **neither** `salesChannels` nor `stock` — both live only on `IkasProduct` / `IkasProductVariant`. To enforce `minQuantityPerCart` / `maxQuantityPerCart` (or stock caps) on the cart page / drawer, batch-fetch the line products once with `bs_searchProductsById` and map the limits by product id:\n\n```tsx\nimport { baseStore, bs_searchProductsById, cartStore, IkasStorefrontConfig } from \"@ikas/bp-storefront\";\n\n// Collect the distinct productIds of the cart lines and fetch them in ONE request:\nconst productIds = [\n  ...new Set(\n    (cartStore.cart?.orderLineItems ?? [])\n      .map((item) => item.variant.productId)\n      .filter((id): id is string => !!id)\n  ),\n];\nconst { products } = await bs_searchProductsById(baseStore, { productIds });\n\nconst limitsByProductId = new Map<string, { min: number; max: number | null }>();\nfor (const product of products ?? []) {\n  const channel = product.salesChannels?.find((sc) => sc.id === IkasStorefrontConfig.salesChannelId);\n  limitsByProductId.set(product.id, {\n    min: channel?.minQuantityPerCart ?? 1,\n    max: channel?.maxQuantityPerCart ?? null,\n  });\n}\n\n// In the line's stepper:\nconst limits = limitsByProductId.get(item.variant.productId ?? \"\");\nconst atMax = limits?.max != null && item.quantity >= limits.max;\n// disable the + button when atMax; block decrements below limits.min the same way\n```\n\n`bs_searchProductsById` returns full `IkasProduct` objects, so `salesChannels` (already filtered to the active sales channel) and per-variant `stock` (summed over the sales channel's configured stock locations) come in the same response — one fetch covers both quantity limits and stock caps. Fetch once per cart open and cache by product id rather than fetching per line; when lines render independently, collect the ids over a tick and flush a single batched request.\n\n### Campaign Offer Lines in the Cart\n\nCampaign discounts surface as order-level adjustment rows, not as edits on the line items. Format the adjustment amount with `formatCurrency` — the root export that applies the merchant's currency format settings:\n\n```tsx\nimport { formatCurrency } from \"@ikas/bp-storefront\";\n\n{cart.orderAdjustments?.map((adj) => (\n  <div key={adj.name} className=\"cart-adjustment\">\n    <span>{adj.name}</span>\n    <span>{formatCurrency(adj.amount, adj.currencyCode, adj.currencySymbol)}</span>\n  </div>\n))}\n```\n\nWhen a campaign auto-adds a bundled or gift line (a \"buy 1 get N\" offer), `isOrderLineItemAutoCreated(cart, item)` returns `true` for that line. Use it to badge the line and hide its quantity/remove controls — the customer cannot edit an auto-created line directly:\n\n```tsx\nimport { isOrderLineItemAutoCreated } from \"@ikas/bp-storefront\";\n\n{lineItems.map((item) => (\n  <CartItem key={item.id} item={item} readOnly={isOrderLineItemAutoCreated(cart, item)} />\n))}\n```\n\n### Key Pattern: Section Without IkasComponentRenderer\n\nCartPage demonstrates that not all sections need COMPONENT_LIST slots. Simple sections can directly compose sub-components and local components when the layout is fixed and does not need editor-level child component placement.",
+      "content": "## Cart Management Patterns (Serel Reference)\n\nThe serel CartPage is a section that uses local internal components (OrderSummary, CouponCode, EmptyState) and the shared `CartItem` sub-component from `src/sub-components/CartItem/`. Unlike most sections, CartPage does NOT use IkasComponentRenderer — it directly composes its UI from sub-components.\n\n### CartPage Section Structure\n\n```tsx\nimport { cartStore } from \"@ikas/bp-storefront\";\nimport CartItem from \"../../sub-components/CartItem\";\nimport { Props } from \"./types\";\n\nexport function CartPage({ backgroundColor, emptyCartText, ...props }: Props) {\n  const cart = cartStore.cart;\n  const lineItems = cart?.orderLineItems ?? [];\n  const isEmpty = lineItems.length === 0;\n\n  if (isEmpty) return <EmptyState text={emptyCartText} />;\n\n  return (\n    <section className=\"cart-page\" style={backgroundColor ? { backgroundColor } : undefined}>\n      <div className=\"cart-page-inner\">\n        <div className=\"cart-items\">\n          {lineItems.map((item) => (\n            <CartItem key={item.id} item={item} />\n          ))}\n        </div>\n        <div className=\"cart-sidebar\">\n          <CouponCode cart={cart} />\n          <OrderSummary cart={cart} />\n        </div>\n      </div>\n    </section>\n  );\n}\nexport default CartPage;\n```\n\n### CartItem Sub-Component\n\nThe `CartItem` sub-component (in `src/sub-components/CartItem/`) displays a single line item with image, variant name, quantity controls, price, and remove button:\n\n```tsx\nimport {\n  getOrderLineItemFormattedFinalPrice,\n  getOrderLineItemFormattedUnitPrice,\n  getIkasOrderLineVariantMainImage,\n  getDefaultSrc,\n  changeItemQuantity,\n  removeItem,\n  IkasOrderLineItem,\n} from \"@ikas/bp-storefront\";\nimport QuantitySelector from \"../QuantitySelector\";\n\ninterface Props { item: IkasOrderLineItem; }\n\nexport default function CartItem({ item }: Props) {\n  const image = item.variant ? getIkasOrderLineVariantMainImage(item.variant) : null;\n\n  return (\n    <div className=\"cart-item\">\n      {image && <img src={getDefaultSrc(image)} alt={item.variant?.name} />}\n      <div className=\"cart-item-info\">\n        <span>{item.variant?.name}</span>\n        <span>{getOrderLineItemFormattedUnitPrice(item)}</span>\n      </div>\n      <QuantitySelector\n        quantity={item.quantity}\n        onIncrement={() => changeItemQuantity(item, item.quantity + 1)}\n        onDecrement={() => changeItemQuantity(item, Math.max(1, item.quantity - 1))}\n      />\n      <span>{getOrderLineItemFormattedFinalPrice(item)}</span>\n      <button onClick={() => removeItem(item)}>Remove</button>\n    </div>\n  );\n}\n```\n\n### OrderSummary Local Component\n\nDisplays cart totals using `getIkasOrderFormattedTotalFinalPrice(cart)` and `getIkasOrderFormattedTotalPrice(cart)`, plus a checkout button:\n\n```tsx\nimport { Router, getIkasOrderFormattedTotalFinalPrice } from \"@ikas/bp-storefront\";\n\nfunction OrderSummary({ cart }) {\n  return (\n    <div className=\"order-summary\">\n      <span>Total: {getIkasOrderFormattedTotalFinalPrice(cart)}</span>\n      <button onClick={() => Router.navigateToPage(\"CHECKOUT\")}>Checkout</button>\n    </div>\n  );\n}\n```\n\n### CouponCode Local Component\n\nCoupon code uses the standard form model. Get the form from `customerStore` via `getCouponCodeForm`, init it once, drive the input with `setCouponCodeFormCouponCode`, and submit/remove with the form helpers. Do NOT call `saveCart`/`apiSaveCart` or any deep `@ikas/bp-storefront/dist/...` import — the coupon has dedicated public exports:\n\n```tsx\nimport { useEffect } from \"preact/hooks\";\nimport {\n  customerStore,\n  getCouponCodeForm,\n  initCouponCodeForm,\n  setCouponCodeFormCouponCode,\n  submitCouponCodeForm,\n  removeCouponCodeForm,\n} from \"@ikas/bp-storefront\";\nimport { observer } from \"@ikas/component-utils\";\n\n// observer() because this sub-component reads the MobX coupon form\nconst CouponCode = observer(function CouponCode({ appliedCoupon }) {\n  const couponForm = getCouponCodeForm(customerStore);\n\n  useEffect(() => {\n    initCouponCodeForm(couponForm);\n  }, [couponForm]);\n\n  const handleSubmit = async (e: Event) => {\n    e.preventDefault();\n    await submitCouponCodeForm(couponForm);\n  };\n\n  if (appliedCoupon) {\n    return (\n      <div className=\"coupon\">\n        <span>{appliedCoupon}</span>\n        <button type=\"button\" onClick={() => removeCouponCodeForm(couponForm)}>Remove</button>\n      </div>\n    );\n  }\n\n  return (\n    <form className=\"coupon\" onSubmit={handleSubmit}>\n      <input\n        placeholder={couponForm.couponCode?.placeholder ?? \"Coupon code\"}\n        value={couponForm.couponCode?.value ?? \"\"}\n        onInput={(e) =>\n          setCouponCodeFormCouponCode(couponForm, (e.target as HTMLInputElement).value)\n        }\n      />\n      <button type=\"submit\" disabled={couponForm.isSubmitting}>\n        {couponForm.isSubmitting ? \"Applying...\" : \"Apply\"}\n      </button>\n      {couponForm.isFailure && couponForm.responseMessage && (\n        <p className=\"coupon-error\">{couponForm.responseMessage}</p>\n      )}\n    </form>\n  );\n});\n```\n\n### cartStore Usage Patterns\n\nThe `cartStore` is a MobX store available globally. Root components are automatically reactive via autorun, so reads from `cartStore.cart` trigger re-renders:\n\n```tsx\nimport { cartStore } from \"@ikas/bp-storefront\";\n\n// Always null-safe:\nconst cart = cartStore.cart;\nconst lineItems = cart?.orderLineItems ?? [];\nconst itemCount = lineItems.length;\nconst isEmpty = itemCount === 0;\n```\n\n### Quantity Limits (min/max per cart)\n\nA product's sales channel can cap how many units go into one cart. The limits live on the product's `salesChannels`, matched to the active channel:\n\n```tsx\nimport { IkasStorefrontConfig } from \"@ikas/bp-storefront\";\n\nconst channel = product.salesChannels?.find((sc) => sc.id === IkasStorefrontConfig.salesChannelId);\nconst min = channel?.minQuantityPerCart ?? 1;\nconst max = channel?.maxQuantityPerCart; // null/undefined = no cap\n```\n\nApply these to the quantity stepper: seed the initial quantity to `min`, and cap increments at `max`. `addItemToCart(variant, product, qty)` clamps to the same limits internally only when it creates a **new** cart line — and silently, so enforce them in the UI too or the customer sees the number snap with no explanation.\n\n> **The internal clamp only runs when a NEW cart line is created.** If the variant already has a line in the cart, `addItemToCart` delegates to `changeItemQuantity(existing, existing.quantity + qty)` before the clamp is reached — and `changeItemQuantity` never clamps. Cart page / cart drawer steppers therefore get no SDK enforcement at all; enforce the limits in the UI (see \"Enforcing Limits on Cart Lines\" below).\n\n> `IkasStorefrontConfig.salesChannelId` is a property. The older `getSalesChannelId()` method does not exist in this SDK.\n\n### Cart Operation validationError (complete list)\n\n`addItemToCart` / `changeItemQuantity` return `IkasCartOperationResult` — `{ success, validationError?, response? }`. The `validationError` union has exactly three values, but at runtime only `addItemToCart` ever sets it (client-side pre-validation before the API call). `changeItemQuantity` does no client-side validation and never returns a `validationError` — branch on `success` (and `response.errorCodes` for details), not on `validationError`, for cart-line quantity changes:\n\n| Value | Meaning |\n|-------|---------|\n| `INSUFFICIENT_STOCK` | Not enough stock for the requested quantity |\n| `INVALID_PRODUCT_OPTION_VALUES` | Required product options not fully or validly selected |\n| `EMPTY_CART` | The operation needs a non-empty cart (declared in the type union, but no current code path emits it) |\n\nQuantity limits are never surfaced as a `validationError` — there is **no** `MAX_QUANTITY_PER_CART_*` / `MIN_QUANTITY_PER_CART_*` value beyond the three above. They surface one level lower instead: when a mutation would push a line past `maxQuantityPerCart`, the API rejects it with the GraphQL error code `MAX_QUANTITY_PER_CART_LIMIT_REACHED` (an `extensions.code` value the API client copies into `response.errorCodes`). `addItemToCart` and `changeItemQuantity` go through the same mutation, so this is the reactive signal on the cart-line path — exactly where the SDK never clamps:\n\n```tsx\nimport { APIErrorCode, changeItemQuantity } from \"@ikas/bp-storefront\";\n\nconst result = await changeItemQuantity(item, qty);\nif (!result.success && result.response?.errorCodes?.includes(APIErrorCode.MAX_QUANTITY_PER_CART_LIMIT_REACHED)) {\n  // The sales channel's per-cart cap rejected the quantity — tell the customer.\n}\n```\n\nTreat the error code as the fallback, not the UX: prevent limit violations proactively in the stepper (see \"Quantity Limits\" above and \"Enforcing Limits on Cart Lines\" below) so the customer never hits the rejection in the first place.\n\n### Enforcing Limits on Cart Lines\n\nCart lines cannot tell you the limits: `IkasOrderLineItem.variant` is an `IkasOrderLineVariant`, which carries **neither** `salesChannels` nor `stock` — both live only on `IkasProduct` / `IkasProductVariant`. To enforce `minQuantityPerCart` / `maxQuantityPerCart` (or stock caps) on the cart page / drawer, batch-fetch the line products once with `bs_searchProductsById` and map the limits by product id:\n\n```tsx\nimport { baseStore, bs_searchProductsById, cartStore, IkasStorefrontConfig } from \"@ikas/bp-storefront\";\n\n// Collect the distinct productIds of the cart lines and fetch them in ONE request:\nconst productIds = [\n  ...new Set(\n    (cartStore.cart?.orderLineItems ?? [])\n      .map((item) => item.variant.productId)\n      .filter((id): id is string => !!id)\n  ),\n];\nconst { products } = await bs_searchProductsById(baseStore, { productIds });\n\nconst limitsByProductId = new Map<string, { min: number; max: number | null }>();\nfor (const product of products ?? []) {\n  const channel = product.salesChannels?.find((sc) => sc.id === IkasStorefrontConfig.salesChannelId);\n  limitsByProductId.set(product.id, {\n    min: channel?.minQuantityPerCart ?? 1,\n    max: channel?.maxQuantityPerCart ?? null,\n  });\n}\n\n// In the line's stepper:\nconst limits = limitsByProductId.get(item.variant.productId ?? \"\");\nconst atMax = limits?.max != null && item.quantity >= limits.max;\n// disable the + button when atMax; block decrements below limits.min the same way\n```\n\n`bs_searchProductsById` returns full `IkasProduct` objects, so `salesChannels` (already filtered to the active sales channel) and per-variant `stock` (summed over the sales channel's configured stock locations) come in the same response — one fetch covers both quantity limits and stock caps. Fetch once per cart open and cache by product id rather than fetching per line; when lines render independently, collect the ids over a tick and flush a single batched request.\n\n### Campaign Offer Lines in the Cart\n\nCampaign discounts surface as order-level adjustment rows, not as edits on the line items. Format the adjustment amount with `formatCurrency` — the root export that applies the merchant's currency format settings:\n\n```tsx\nimport { formatCurrency } from \"@ikas/bp-storefront\";\n\n{cart.orderAdjustments?.map((adj) => (\n  <div key={adj.name} className=\"cart-adjustment\">\n    <span>{adj.name}</span>\n    <span>{formatCurrency(adj.amount, adj.currencyCode, adj.currencySymbol)}</span>\n  </div>\n))}\n```\n\nWhen a campaign auto-adds a bundled or gift line (a \"buy 1 get N\" offer), `isOrderLineItemAutoCreated(cart, item)` returns `true` for that line. Use it to badge the line and hide its quantity/remove controls — the customer cannot edit an auto-created line directly:\n\n```tsx\nimport { isOrderLineItemAutoCreated } from \"@ikas/bp-storefront\";\n\n{lineItems.map((item) => (\n  <CartItem key={item.id} item={item} readOnly={isOrderLineItemAutoCreated(cart, item)} />\n))}\n```\n\n### Key Pattern: Section Without IkasComponentRenderer\n\nCartPage demonstrates that not all sections need COMPONENT_LIST slots. Simple sections can directly compose sub-components and local components when the layout is fixed and does not need editor-level child component placement.",
       "tags": [
         "cart",
         "checkout",

package/data/section-templates/add-to-cart/utils/cartLimits.ts

@@ -8,9 +8,10 @@ export interface CartQuantityLimits {
 /**
  * Resolve the per-cart quantity limits for a product from its active sales
  * channel. Falls back to a minimum of 1 and no maximum when the channel or its
- * limits are not set. `addItemToCart` clamps to the same limits internally, so
- * applying these in the stepper keeps the UI honest instead of letting the
- * quantity snap silently.
+ * limits are not set. `addItemToCart` clamps to the same limits internally only
+ * when it creates a NEW cart line — incrementing an existing line goes through
+ * `changeItemQuantity`, which never clamps — so enforcing these in the stepper
+ * is the only guard that covers both paths.
  */
 export function getProductCartLimits(product: IkasProduct): CartQuantityLimits {
   const channel = product.salesChannels?.find(

package/data/section-templates/cart-section/sub-components/CartItem/index.tsx

@@ -1,4 +1,5 @@
 import { observer } from "@ikas/component-utils";
+import { useEffect, useState } from "preact/hooks";
 import { TrashSVG, NoProductSVG } from "../icons";
 import QuantitySelector from "../QuantitySelector";
 import BundleProducts from "./components/BundleProducts";
@@ -19,6 +20,11 @@ import {
 } from "@ikas/bp-storefront";
 import { resolveAspectRatio, resolveObjectFit } from "../../utils/media";
 import { cx } from "../../utils/cx";
+import {
+  ensureCartLineLimits,
+  getCartLineLimits,
+  subscribeCartLineLimits,
+} from "../../utils/cartLineLimits";
 import type { AspectRatio, ObjectFit } from "../../global-types";
 
 interface CartItemProps {
@@ -40,6 +46,23 @@ const CartItem = observer(function CartItem({
 }: CartItemProps) {
   const isPage = variant === "page";
 
+  // The line's IkasOrderLineVariant carries no salesChannels, so the per-cart
+  // quantity limits come from a batched product fetch shared across all lines.
+  const productId = item.variant?.productId ?? null;
+  const [, setLimitsVersion] = useState(0);
+  useEffect(() => {
+    // Subscribe BEFORE registering the id: a batch already in flight can
+    // resolve between render and this effect, and its emit must not be missed.
+    const unsubscribe = subscribeCartLineLimits(() => setLimitsVersion((v) => v + 1));
+    if (productId) {
+      ensureCartLineLimits([productId]);
+      // Re-check once for a result that landed before the subscription armed.
+      if (getCartLineLimits(productId)) setLimitsVersion((v) => v + 1);
+    }
+    return unsubscribe;
+  }, [productId]);
+  const limits = getCartLineLimits(productId);
+
   // Lines a campaign added automatically (e.g. a "buy 1 get 1" gift) cannot be
   // edited or removed on their own, so render them read-only with a badge.
   const isAutoCreated =
@@ -180,6 +203,8 @@ const CartItem = observer(function CartItem({
               <QuantitySelector
                 size="sm"
                 value={item.quantity}
+                min={limits?.min ?? 1}
+                max={limits?.max}
                 onChange={(qty) => changeItemQuantity(item, qty)}
               />
             )}
@@ -227,6 +252,8 @@ const CartItem = observer(function CartItem({
                   <QuantitySelector
                     size="sm"
                     value={item.quantity}
+                    min={limits?.min ?? 1}
+                    max={limits?.max}
                     onChange={(qty) => changeItemQuantity(item, qty)}
                   />
                   <button

package/data/section-templates/cart-section/utils/cartLimits.ts

@@ -0,0 +1,24 @@
+import { IkasProduct, IkasStorefrontConfig } from "@ikas/bp-storefront";
+
+export interface CartQuantityLimits {
+  min: number;
+  max?: number;
+}
+
+/**
+ * Resolve the per-cart quantity limits for a product from its active sales
+ * channel. Falls back to a minimum of 1 and no maximum when the channel or its
+ * limits are not set. `addItemToCart` clamps to the same limits internally only
+ * when it creates a NEW cart line — incrementing an existing line goes through
+ * `changeItemQuantity`, which never clamps — so enforcing these in the stepper
+ * is the only guard that covers both paths.
+ */
+export function getProductCartLimits(product: IkasProduct): CartQuantityLimits {
+  const channel = product.salesChannels?.find(
+    (sc) => sc.id === IkasStorefrontConfig.salesChannelId,
+  );
+  return {
+    min: channel?.minQuantityPerCart ?? 1,
+    max: channel?.maxQuantityPerCart ?? undefined,
+  };
+}

package/data/section-templates/cart-section/utils/cartLineLimits.ts

@@ -0,0 +1,82 @@
+import { baseStore, bs_searchProductsById } from "@ikas/bp-storefront";
+import { CartQuantityLimits, getProductCartLimits } from "./cartLimits";
+
+/**
+ * Per-cart quantity limits for cart lines.
+ *
+ * A cart line's `IkasOrderLineVariant` carries no `salesChannels`, so the
+ * min/max per-cart limits can only be read from the full `IkasProduct`. This
+ * store batch-fetches the line products with `bs_searchProductsById` (lines
+ * register their productId one by one; the ids are flushed as ONE request on
+ * the next tick) and maps the resolved limits by product id for the cart
+ * steppers to read. Each product is fetched at most once; results stay cached
+ * for the session.
+ */
+
+const limitsByProductId = new Map<string, CartQuantityLimits>();
+const requestedProductIds = new Set<string>();
+const listeners = new Set<() => void>();
+
+let pendingProductIds: string[] = [];
+let flushTimer: ReturnType<typeof setTimeout> | null = null;
+
+function emit() {
+  for (const listener of listeners) listener();
+}
+
+async function flush() {
+  flushTimer = null;
+  const batch = pendingProductIds;
+  pendingProductIds = [];
+  if (!batch.length) return;
+
+  // bs_searchProductsById never throws — API/network failures resolve with
+  // isSuccess: false — so the retry unmark must live on the result check.
+  const result = await bs_searchProductsById(baseStore, { productIds: batch }).catch(
+    () => null,
+  );
+  if (!result?.isSuccess || !result.products) {
+    // Limits stay unenforced for now; unmark the batch so a later
+    // ensureCartLineLimits call (e.g. the next cart open) can retry.
+    for (const id of batch) requestedProductIds.delete(id);
+    return;
+  }
+
+  for (const product of result.products) {
+    limitsByProductId.set(product.id, getProductCartLimits(product));
+  }
+  emit();
+}
+
+/**
+ * Register cart-line productIds for limit resolution. Ids already requested
+ * are skipped; new ids are collected and fetched in a single batched request
+ * on the next tick, so per-line calls do not fan out into per-line requests.
+ */
+export function ensureCartLineLimits(productIds: (string | null | undefined)[]) {
+  const missing = productIds.filter(
+    (id): id is string => !!id && !requestedProductIds.has(id),
+  );
+  if (!missing.length) return;
+
+  for (const id of missing) {
+    requestedProductIds.add(id);
+    pendingProductIds.push(id);
+  }
+  if (!flushTimer) flushTimer = setTimeout(flush, 0);
+}
+
+/** Resolved limits for a product — undefined until the batch fetch lands. */
+export function getCartLineLimits(
+  productId: string | null | undefined,
+): CartQuantityLimits | undefined {
+  return productId ? limitsByProductId.get(productId) : undefined;
+}
+
+/** Subscribe to limit resolutions; returns the unsubscribe function. */
+export function subscribeCartLineLimits(listener: () => void) {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}

package/data/section-templates/header-section/sub-components/CartItem/index.tsx

@@ -1,4 +1,5 @@
 import { observer } from "@ikas/component-utils";
+import { useEffect, useState } from "preact/hooks";
 import { TrashSVG, NoProductSVG } from "../icons";
 import QuantitySelector from "../QuantitySelector";
 import BundleProducts from "./components/BundleProducts";
@@ -19,6 +20,11 @@ import {
 } from "@ikas/bp-storefront";
 import { resolveAspectRatio, resolveObjectFit } from "../../utils/media";
 import { cx } from "../../utils/cx";
+import {
+  ensureCartLineLimits,
+  getCartLineLimits,
+  subscribeCartLineLimits,
+} from "../../utils/cartLineLimits";
 import type { AspectRatio, ObjectFit } from "../../global-types";
 
 interface CartItemProps {
@@ -40,6 +46,23 @@ const CartItem = observer(function CartItem({
 }: CartItemProps) {
   const isPage = variant === "page";
 
+  // The line's IkasOrderLineVariant carries no salesChannels, so the per-cart
+  // quantity limits come from a batched product fetch shared across all lines.
+  const productId = item.variant?.productId ?? null;
+  const [, setLimitsVersion] = useState(0);
+  useEffect(() => {
+    // Subscribe BEFORE registering the id: a batch already in flight can
+    // resolve between render and this effect, and its emit must not be missed.
+    const unsubscribe = subscribeCartLineLimits(() => setLimitsVersion((v) => v + 1));
+    if (productId) {
+      ensureCartLineLimits([productId]);
+      // Re-check once for a result that landed before the subscription armed.
+      if (getCartLineLimits(productId)) setLimitsVersion((v) => v + 1);
+    }
+    return unsubscribe;
+  }, [productId]);
+  const limits = getCartLineLimits(productId);
+
   // Lines a campaign added automatically (e.g. a "buy 1 get 1" gift) cannot be
   // edited or removed on their own, so render them read-only with a badge.
   const isAutoCreated =
@@ -180,6 +203,8 @@ const CartItem = observer(function CartItem({
               <QuantitySelector
                 size="sm"
                 value={item.quantity}
+                min={limits?.min ?? 1}
+                max={limits?.max}
                 onChange={(qty) => changeItemQuantity(item, qty)}
               />
             )}
@@ -227,6 +252,8 @@ const CartItem = observer(function CartItem({
                   <QuantitySelector
                     size="sm"
                     value={item.quantity}
+                    min={limits?.min ?? 1}
+                    max={limits?.max}
                     onChange={(qty) => changeItemQuantity(item, qty)}
                   />
                   <button

package/data/section-templates/header-section/utils/cartLimits.ts

@@ -0,0 +1,24 @@
+import { IkasProduct, IkasStorefrontConfig } from "@ikas/bp-storefront";
+
+export interface CartQuantityLimits {
+  min: number;
+  max?: number;
+}
+
+/**
+ * Resolve the per-cart quantity limits for a product from its active sales
+ * channel. Falls back to a minimum of 1 and no maximum when the channel or its
+ * limits are not set. `addItemToCart` clamps to the same limits internally only
+ * when it creates a NEW cart line — incrementing an existing line goes through
+ * `changeItemQuantity`, which never clamps — so enforcing these in the stepper
+ * is the only guard that covers both paths.
+ */
+export function getProductCartLimits(product: IkasProduct): CartQuantityLimits {
+  const channel = product.salesChannels?.find(
+    (sc) => sc.id === IkasStorefrontConfig.salesChannelId,
+  );
+  return {
+    min: channel?.minQuantityPerCart ?? 1,
+    max: channel?.maxQuantityPerCart ?? undefined,
+  };
+}

package/data/section-templates/header-section/utils/cartLineLimits.ts

@@ -0,0 +1,82 @@
+import { baseStore, bs_searchProductsById } from "@ikas/bp-storefront";
+import { CartQuantityLimits, getProductCartLimits } from "./cartLimits";
+
+/**
+ * Per-cart quantity limits for cart lines.
+ *
+ * A cart line's `IkasOrderLineVariant` carries no `salesChannels`, so the
+ * min/max per-cart limits can only be read from the full `IkasProduct`. This
+ * store batch-fetches the line products with `bs_searchProductsById` (lines
+ * register their productId one by one; the ids are flushed as ONE request on
+ * the next tick) and maps the resolved limits by product id for the cart
+ * steppers to read. Each product is fetched at most once; results stay cached
+ * for the session.
+ */
+
+const limitsByProductId = new Map<string, CartQuantityLimits>();
+const requestedProductIds = new Set<string>();
+const listeners = new Set<() => void>();
+
+let pendingProductIds: string[] = [];
+let flushTimer: ReturnType<typeof setTimeout> | null = null;
+
+function emit() {
+  for (const listener of listeners) listener();
+}
+
+async function flush() {
+  flushTimer = null;
+  const batch = pendingProductIds;
+  pendingProductIds = [];
+  if (!batch.length) return;
+
+  // bs_searchProductsById never throws — API/network failures resolve with
+  // isSuccess: false — so the retry unmark must live on the result check.
+  const result = await bs_searchProductsById(baseStore, { productIds: batch }).catch(
+    () => null,
+  );
+  if (!result?.isSuccess || !result.products) {
+    // Limits stay unenforced for now; unmark the batch so a later
+    // ensureCartLineLimits call (e.g. the next cart open) can retry.
+    for (const id of batch) requestedProductIds.delete(id);
+    return;
+  }
+
+  for (const product of result.products) {
+    limitsByProductId.set(product.id, getProductCartLimits(product));
+  }
+  emit();
+}
+
+/**
+ * Register cart-line productIds for limit resolution. Ids already requested
+ * are skipped; new ids are collected and fetched in a single batched request
+ * on the next tick, so per-line calls do not fan out into per-line requests.
+ */
+export function ensureCartLineLimits(productIds: (string | null | undefined)[]) {
+  const missing = productIds.filter(
+    (id): id is string => !!id && !requestedProductIds.has(id),
+  );
+  if (!missing.length) return;
+
+  for (const id of missing) {
+    requestedProductIds.add(id);
+    pendingProductIds.push(id);
+  }
+  if (!flushTimer) flushTimer = setTimeout(flush, 0);
+}
+
+/** Resolved limits for a product — undefined until the batch fetch lands. */
+export function getCartLineLimits(
+  productId: string | null | undefined,
+): CartQuantityLimits | undefined {
+  return productId ? limitsByProductId.get(productId) : undefined;
+}
+
+/** Subscribe to limit resolutions; returns the unsubscribe function. */
+export function subscribeCartLineLimits(listener: () => void) {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}

package/data/section-templates/navigation/sub-components/CartItem/index.tsx

@@ -1,4 +1,5 @@
 import { observer } from "@ikas/component-utils";
+import { useEffect, useState } from "preact/hooks";
 import { TrashSVG, NoProductSVG } from "../icons";
 import QuantitySelector from "../QuantitySelector";
 import BundleProducts from "./components/BundleProducts";
@@ -19,6 +20,11 @@ import {
 } from "@ikas/bp-storefront";
 import { resolveAspectRatio, resolveObjectFit } from "../../utils/media";
 import { cx } from "../../utils/cx";
+import {
+  ensureCartLineLimits,
+  getCartLineLimits,
+  subscribeCartLineLimits,
+} from "../../utils/cartLineLimits";
 import type { AspectRatio, ObjectFit } from "../../global-types";
 
 interface CartItemProps {
@@ -40,6 +46,23 @@ const CartItem = observer(function CartItem({
 }: CartItemProps) {
   const isPage = variant === "page";
 
+  // The line's IkasOrderLineVariant carries no salesChannels, so the per-cart
+  // quantity limits come from a batched product fetch shared across all lines.
+  const productId = item.variant?.productId ?? null;
+  const [, setLimitsVersion] = useState(0);
+  useEffect(() => {
+    // Subscribe BEFORE registering the id: a batch already in flight can
+    // resolve between render and this effect, and its emit must not be missed.
+    const unsubscribe = subscribeCartLineLimits(() => setLimitsVersion((v) => v + 1));
+    if (productId) {
+      ensureCartLineLimits([productId]);
+      // Re-check once for a result that landed before the subscription armed.
+      if (getCartLineLimits(productId)) setLimitsVersion((v) => v + 1);
+    }
+    return unsubscribe;
+  }, [productId]);
+  const limits = getCartLineLimits(productId);
+
   // Lines a campaign added automatically (e.g. a "buy 1 get 1" gift) cannot be
   // edited or removed on their own, so render them read-only with a badge.
   const isAutoCreated =
@@ -180,6 +203,8 @@ const CartItem = observer(function CartItem({
               <QuantitySelector
                 size="sm"
                 value={item.quantity}
+                min={limits?.min ?? 1}
+                max={limits?.max}
                 onChange={(qty) => changeItemQuantity(item, qty)}
               />
             )}
@@ -227,6 +252,8 @@ const CartItem = observer(function CartItem({
                   <QuantitySelector
                     size="sm"
                     value={item.quantity}
+                    min={limits?.min ?? 1}
+                    max={limits?.max}
                     onChange={(qty) => changeItemQuantity(item, qty)}
                   />
                   <button

package/data/section-templates/navigation/utils/cartLimits.ts

@@ -0,0 +1,24 @@
+import { IkasProduct, IkasStorefrontConfig } from "@ikas/bp-storefront";
+
+export interface CartQuantityLimits {
+  min: number;
+  max?: number;
+}
+
+/**
+ * Resolve the per-cart quantity limits for a product from its active sales
+ * channel. Falls back to a minimum of 1 and no maximum when the channel or its
+ * limits are not set. `addItemToCart` clamps to the same limits internally only
+ * when it creates a NEW cart line — incrementing an existing line goes through
+ * `changeItemQuantity`, which never clamps — so enforcing these in the stepper
+ * is the only guard that covers both paths.
+ */
+export function getProductCartLimits(product: IkasProduct): CartQuantityLimits {
+  const channel = product.salesChannels?.find(
+    (sc) => sc.id === IkasStorefrontConfig.salesChannelId,
+  );
+  return {
+    min: channel?.minQuantityPerCart ?? 1,
+    max: channel?.maxQuantityPerCart ?? undefined,
+  };
+}

package/data/section-templates/navigation/utils/cartLineLimits.ts

@@ -0,0 +1,82 @@
+import { baseStore, bs_searchProductsById } from "@ikas/bp-storefront";
+import { CartQuantityLimits, getProductCartLimits } from "./cartLimits";
+
+/**
+ * Per-cart quantity limits for cart lines.
+ *
+ * A cart line's `IkasOrderLineVariant` carries no `salesChannels`, so the
+ * min/max per-cart limits can only be read from the full `IkasProduct`. This
+ * store batch-fetches the line products with `bs_searchProductsById` (lines
+ * register their productId one by one; the ids are flushed as ONE request on
+ * the next tick) and maps the resolved limits by product id for the cart
+ * steppers to read. Each product is fetched at most once; results stay cached
+ * for the session.
+ */
+
+const limitsByProductId = new Map<string, CartQuantityLimits>();
+const requestedProductIds = new Set<string>();
+const listeners = new Set<() => void>();
+
+let pendingProductIds: string[] = [];
+let flushTimer: ReturnType<typeof setTimeout> | null = null;
+
+function emit() {
+  for (const listener of listeners) listener();
+}
+
+async function flush() {
+  flushTimer = null;
+  const batch = pendingProductIds;
+  pendingProductIds = [];
+  if (!batch.length) return;
+
+  // bs_searchProductsById never throws — API/network failures resolve with
+  // isSuccess: false — so the retry unmark must live on the result check.
+  const result = await bs_searchProductsById(baseStore, { productIds: batch }).catch(
+    () => null,
+  );
+  if (!result?.isSuccess || !result.products) {
+    // Limits stay unenforced for now; unmark the batch so a later
+    // ensureCartLineLimits call (e.g. the next cart open) can retry.
+    for (const id of batch) requestedProductIds.delete(id);
+    return;
+  }
+
+  for (const product of result.products) {
+    limitsByProductId.set(product.id, getProductCartLimits(product));
+  }
+  emit();
+}
+
+/**
+ * Register cart-line productIds for limit resolution. Ids already requested
+ * are skipped; new ids are collected and fetched in a single batched request
+ * on the next tick, so per-line calls do not fan out into per-line requests.
+ */
+export function ensureCartLineLimits(productIds: (string | null | undefined)[]) {
+  const missing = productIds.filter(
+    (id): id is string => !!id && !requestedProductIds.has(id),
+  );
+  if (!missing.length) return;
+
+  for (const id of missing) {
+    requestedProductIds.add(id);
+    pendingProductIds.push(id);
+  }
+  if (!flushTimer) flushTimer = setTimeout(flush, 0);
+}
+
+/** Resolved limits for a product — undefined until the batch fetch lands. */
+export function getCartLineLimits(
+  productId: string | null | undefined,
+): CartQuantityLimits | undefined {
+  return productId ? limitsByProductId.get(productId) : undefined;
+}
+
+/** Subscribe to limit resolutions; returns the unsubscribe function. */
+export function subscribeCartLineLimits(listener: () => void) {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}

package/data/section-templates/product-detail-section/utils/cartLimits.ts

@@ -8,9 +8,10 @@ export interface CartQuantityLimits {
 /**
  * Resolve the per-cart quantity limits for a product from its active sales
  * channel. Falls back to a minimum of 1 and no maximum when the channel or its
- * limits are not set. `addItemToCart` clamps to the same limits internally, so
- * applying these in the stepper keeps the UI honest instead of letting the
- * quantity snap silently.
+ * limits are not set. `addItemToCart` clamps to the same limits internally only
+ * when it creates a NEW cart line — incrementing an existing line goes through
+ * `changeItemQuantity`, which never clamps — so enforcing these in the stepper
+ * is the only guard that covers both paths.
  */
 export function getProductCartLimits(product: IkasProduct): CartQuantityLimits {
   const channel = product.salesChannels?.find(

package/data/storefront-api.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-08-19T09:39:30.854Z",
+  "generatedAt": "2026-08-19T12:35:16.476Z",
   "functions": [
     {
       "name": "apiListProductBrand",
@@ -12756,7 +12756,7 @@
       "name": "changeItemQuantity",
       "displayName": "changeQuantityOnCart",
       "signature": "async function changeItemQuantity(item: IkasOrderLineItem, quantity: number, offers?: IkasProductOffer[], product?: IkasProduct): Promise<IkasCartOperationResult>",
-      "description": "Change the quantity of an item in the cart.\nUse quantity=0 to remove the item.",
+      "description": "Change the quantity of an item in the cart.\nUse quantity=0 to remove the item.\n\nPerforms no client-side clamping or validation: a quantity above the sales channel's\n`maxQuantityPerCart` is rejected by the API with the `MAX_QUANTITY_PER_CART_LIMIT_REACHED`\ncode in `result.response.errorCodes` (never as a `validationError`). Prevent violations in\nthe stepper and treat the error code as the fallback.",
       "params": [
         {
           "name": "item",
@@ -12777,7 +12777,7 @@
       ],
       "returns": "Result with success flag",
       "returnType": "Promise<IkasCartOperationResult>",
-      "example": "```typescript\nimport { cartStore, changeItemQuantity } from \"@ikas/bp-storefront\";\n\n// Increment quantity\nasync function handleIncrement(itemId: string) {\n  const item = cartStore.cart?.orderLineItems.find(i => i.id === itemId);\n  if (item) {\n    const result = await changeItemQuantity(item, item.quantity + 1);\n    if (!result.success) {\n      showToast(\"Failed to update quantity\");\n    }\n  }\n}\n\n// Decrement quantity\nasync function handleDecrement(itemId: string) {\n  const item = cartStore.cart?.orderLineItems.find(i => i.id === itemId);\n  if (item && item.quantity > 1) {\n    await changeItemQuantity(item, item.quantity - 1);\n  }\n}\n```",
+      "example": "```typescript\nimport { APIErrorCode, cartStore, changeItemQuantity } from \"@ikas/bp-storefront\";\n\n// Increment quantity\nasync function handleIncrement(itemId: string) {\n  const item = cartStore.cart?.orderLineItems.find(i => i.id === itemId);\n  if (item) {\n    const result = await changeItemQuantity(item, item.quantity + 1);\n    if (!result.success) {\n      const limitHit = result.response?.errorCodes?.includes(\n        APIErrorCode.MAX_QUANTITY_PER_CART_LIMIT_REACHED\n      );\n      showToast(limitHit ? \"Per-cart quantity limit reached\" : \"Failed to update quantity\");\n    }\n  }\n}\n\n// Decrement quantity\nasync function handleDecrement(itemId: string) {\n  const item = cartStore.cart?.orderLineItems.find(i => i.id === itemId);\n  if (item && item.quantity > 1) {\n    await changeItemQuantity(item, item.quantity - 1);\n  }\n}\n```",
       "categories": [
         "Cart"
       ],

package/data/storefront-types.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-08-19T09:39:30.880Z",
+  "generatedAt": "2026-08-19T12:35:16.642Z",
   "types": [
     {
       "name": "TextElementTagTypes",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikas/code-components-mcp",
-  "version": "1.4.0-beta.166",
+  "version": "1.4.0-beta.168",
   "description": "MCP server for ikas code components documentation",
   "type": "module",
   "main": "dist/index.js",