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

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

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:18:27.436Z",
   "functions": [
     {
       "name": "apiListProductBrand",

package/data/storefront-types.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-08-19T09:39:30.880Z",
+  "generatedAt": "2026-08-19T12:18:27.461Z",
   "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.167",
   "description": "MCP server for ikas code components documentation",
   "type": "module",
   "main": "dist/index.js",