@ikas/code-components-mcp 1.4.0-beta.23 → 1.4.0-beta.230

package/data/migration.json

@@ -17,7 +17,7 @@
     "prop-type-mapping": {
       "title": "Prop Type Mapping: Old → New",
       "description": "Complete mapping of old theme.json prop types to new ikas.config.json prop types",
-      "content": "## IMPORTANT: Different Systems, Different Types\n\n**The old prop type system (theme.json) and the new prop type system (ikas.config.json) are completely separate.** Even when a prop type has the same name in both systems (e.g., `IMAGE`, `LINK`, `PRODUCT_LIST`), the underlying TypeScript types come from different packages (`@ikas/storefront` vs `@ikas/bp-storefront`) and may have different properties, methods, and nullability. Always use the MCP tools (`get_type_definition`, `get_model_guide`) to look up the exact new-system types — never assume old-system knowledge applies.\n\n## Direct Mappings (1:1)\n\nThese prop types have similar equivalents, but remember the TypeScript types are from different packages:\n\n| Old Type | New Type | TypeScript (Old) | TypeScript (New) | Notes |\n|----------|----------|-----------------|-----------------|-------|\n| `TEXT` | `TEXT` | `string` | `string` | |\n| `RICH_TEXT` | `RICH_TEXT` | `string` | `string` | |\n| `BOOLEAN` | `BOOLEAN` | `boolean` | `boolean` | |\n| `IMAGE` | `IMAGE` | `IkasImage` | `IkasImage \\| null` | New type is nullable |\n| `IMAGE_LIST` | `IMAGE_LIST` | `IkasImage[]` | `IkasImageList` | Slight type difference |\n| `LINK` | `LINK` | `IkasNavigationLink` | `IkasNavigationLink` | |\n| `LIST_OF_LINK` | `LIST_OF_LINK` | `IkasNavigationLink[]` | `IkasNavigationLinkList` | Slight type difference |\n| `COLOR` | `COLOR` | `string` | `string` | |\n| `VIDEO` | `VIDEO` | `IkasVideo` | `IkasVideo \\| null` | New type is nullable |\n| `PRODUCT_LIST` | `PRODUCT_LIST` | `IkasProductList` | `IkasProductList` | |\n| `CATEGORY` | `CATEGORY` | `IkasCategory` | `IkasCategory \\| null` | |\n| `CATEGORY_LIST` | `CATEGORY_LIST` | `IkasCategoryList` | `IkasCategoryList` | |\n| `BRAND` | `BRAND` | `IkasBrand` | `IkasBrand \\| null` | |\n| `BRAND_LIST` | `BRAND_LIST` | — | `IkasBrandList` | |\n| `BLOG` | `BLOG` | `IkasBlog` | `IkasBlog \\| null` | |\n| `BLOG_LIST` | `BLOG_LIST` | `IkasBlogList` | `IkasBlogList` | |\n| `BLOG_CATEGORY` | `BLOG_CATEGORY` | `IkasBlogCategory` | `IkasBlogCategory \\| null` | |\n| `BLOG_CATEGORY_LIST` | `BLOG_CATEGORY_LIST` | `IkasBlogCategoryList` | `IkasBlogCategoryList` | |\n| `PRODUCT_ATTRIBUTE` | `PRODUCT_ATTRIBUTE` | `IkasAttributeDetail` | `IkasProductAttributeValue \\| null` | Type renamed |\n| `PRODUCT_ATTRIBUTE_LIST` | `PRODUCT_ATTRIBUTE_LIST` | `IkasAttributeList` | `IkasProductAttributeValue[]` | Type renamed |\n| `COMPONENT_LIST` | `COMPONENT_LIST` | `IkasComponentRenderer` | `any` (rendered via `<IkasComponentRenderer>`) | |\n\n## Renamed Types\n\n| Old Type | New Type | Notes |\n|----------|----------|-------|\n| `PRODUCT_DETAIL` | `PRODUCT` | Same concept, just renamed. Old: `IkasProduct`, New: `IkasProduct \\| null` |\n\n## Types Requiring Conversion\n\n### SLIDER → NUMBER\nOld `SLIDER` type used `IkasSlider` with `{ value: number }`. The new system uses `NUMBER` which maps to plain `number`.\n\n**Old theme.json:**\n```json\n{\n  \"name\": \"logoWidth\",\n  \"type\": \"SLIDER\",\n  \"sliderData\": { \"min\": 80, \"max\": 300, \"interval\": 1 }\n}\n```\n\n**New ikas.config.json:**\n```json\n{\n  \"name\": \"logoWidth\",\n  \"displayName\": \"Logo Width\",\n  \"type\": \"NUMBER\",\n  \"required\": false,\n  \"defaultValue\": 120\n}\n```\n\n**Code change:** Replace `logoWidth?.value` or `logoWidth.value` with just `logoWidth` (it's already a number).\n\n### CUSTOM → Multiple approaches\nSee `get_migration_guide(\"custom-data-conversion\")` for the full guide. Summary:\n\n| Old customData type | New approach |\n|--------------------|--------------|\n| DYNAMIC_LIST (list of objects) | `COMPONENT_LIST` + child component |\n| OBJECT (≤3 simple fields) | Flatten into direct props on parent |\n| OBJECT (>3 fields or complex) | `COMPONENT_LIST` + child component |\n| STATIC_LIST (fixed count items) | `COMPONENT_LIST` (store owner manages count) |\n| ENUM (enumOptions) | `ENUM` with custom enum via `config add-enum` |\n\n### ENUM → ENUM\nOld ENUM type with `enumOptions` maps to new ENUM with `enumTypeId`. Create custom enums first:\n```bash\nnpx ikas-component config add-enum --name \"AspectRatio\" --options '{\"Square\":\"1:1\",\"Landscape\":\"16:9\",\"Portrait\":\"3:4\"}'\n# Use returned enumId in prop definition\n```\n\n## Types Not Available in New System\n\nThese old types do not exist in the new system and need workarounds:\n\n| Old Type | Workaround |\n|----------|------------|\n| `SLIDER` | Use `NUMBER`. Access value directly instead of `.value` |\n| `OBJECT` (customData) | Flatten into parent props or use COMPONENT_LIST |\n| `STATIC_LIST` (customData) | Use COMPONENT_LIST |\n\n## New Types Not in Old System\n\n| New Type | Description |\n|----------|-------------|\n| `NUMBER` | Numeric input (replaces SLIDER) |\n| `NUMBER_RANGE` | Two-number range (IkasNumberRange) |\n| `DATE` | Date picker |\n| `FUNCTION` | Function prop (callback) |\n| `TYPE` | Structured style type (padding, margin, etc.) |\n| `COMPONENT` | Single child component slot |\n| `RAFFLE` / `RAFFLE_LIST` | Raffle references |",
+      "content": "## IMPORTANT: Different Systems, Different Types\n\n**The old prop type system (theme.json) and the new prop type system (ikas.config.json) are completely separate.** Even when a prop type has the same name in both systems (e.g., `IMAGE`, `LINK`, `PRODUCT_LIST`), the underlying TypeScript types come from different packages (`@ikas/storefront` vs `@ikas/bp-storefront`) and may have different properties, methods, and nullability. Always use the MCP tools (`get_type_definition`, `get_model_guide`) to look up the exact new-system types — never assume old-system knowledge applies.\n\n## Direct Mappings (1:1)\n\nThese prop types have similar equivalents, but remember the TypeScript types are from different packages:\n\n| Old Type | New Type | TypeScript (Old) | TypeScript (New) | Notes |\n|----------|----------|-----------------|-----------------|-------|\n| `TEXT` | `TEXT` | `string` | `string` | |\n| `RICH_TEXT` | `RICH_TEXT` | `string` | `string` | |\n| `BOOLEAN` | `BOOLEAN` | `boolean` | `boolean` | |\n| `IMAGE` | `IMAGE` | `IkasImage` | `IkasImage \\| null` | New type is nullable |\n| `IMAGE_LIST` | `IMAGE_LIST` | `IkasImage[]` | `IkasImageList` | Slight type difference |\n| `LINK` | `LINK` | `IkasNavigationLink` | `IkasNavigationLink` | |\n| `LIST_OF_LINK` | `LIST_OF_LINK` | `IkasNavigationLink[]` | `IkasNavigationLinkList` | Slight type difference |\n| `COLOR` | `COLOR` | `string` | `string` | |\n| `VIDEO` | `VIDEO` | `IkasVideo` | `IkasVideo \\| null` | New type is nullable |\n| `PRODUCT_LIST` | `PRODUCT_LIST` | `IkasProductList` | `IkasProductList` | |\n| `CATEGORY` | `CATEGORY` | `IkasCategory` | `IkasCategory \\| null` | |\n| `CATEGORY_LIST` | `CATEGORY_LIST` | `IkasCategoryList` | `IkasCategoryList` | |\n| `BRAND` | `BRAND` | `IkasBrand` | `IkasBrand \\| null` | |\n| `BRAND_LIST` | `BRAND_LIST` | — | `IkasBrandList` | |\n| `BLOG` | `BLOG` | `IkasBlog` | `IkasBlog \\| null` | |\n| `BLOG_LIST` | `BLOG_LIST` | `IkasBlogList` | `IkasBlogList` | |\n| `BLOG_CATEGORY` | `BLOG_CATEGORY` | `IkasBlogCategory` | `IkasBlogCategory \\| null` | |\n| `BLOG_CATEGORY_LIST` | `BLOG_CATEGORY_LIST` | `IkasBlogCategoryList` | `IkasBlogCategoryList` | |\n| `PRODUCT_ATTRIBUTE` | `PRODUCT_ATTRIBUTE` | `IkasAttributeDetail` | `IkasProductAttributeDetail \\| null` | Renamed only — same wrapper shape `{ product, attributePropValue }`; read values with `getAttributeDetailValues()` |\n| `PRODUCT_ATTRIBUTE_LIST` | `PRODUCT_ATTRIBUTE_LIST` | `IkasAttributeList` | `IkasProductAttributeList` | Renamed only — still a single wrapper object (NOT an array); read values with `getAttributeListValues()` |\n| `COMPONENT_LIST` | `COMPONENT_LIST` | `IkasComponentRenderer` | `any` (rendered via `<IkasComponentRenderer>`) | |\n\n## Renamed Types\n\n| Old Type | New Type | Notes |\n|----------|----------|-------|\n| `PRODUCT_DETAIL` | `PRODUCT` | Same concept, just renamed. Old: `IkasProduct`, New: `IkasProduct \\| null` |\n\n## Types Requiring Conversion\n\n### SLIDER → NUMBER\nOld `SLIDER` type used `IkasSlider` with `{ value: number }`. The new system uses `NUMBER` which maps to plain `number`.\n\n**Old theme.json:**\n```json\n{\n  \"name\": \"logoWidth\",\n  \"type\": \"SLIDER\",\n  \"sliderData\": { \"min\": 80, \"max\": 300, \"interval\": 1 }\n}\n```\n\n**New ikas.config.json:**\n```json\n{\n  \"name\": \"logoWidth\",\n  \"displayName\": \"Logo Width\",\n  \"type\": \"NUMBER\",\n  \"required\": false,\n  \"defaultValue\": 120\n}\n```\n\n**Code change:** Replace `logoWidth?.value` or `logoWidth.value` with just `logoWidth` (it's already a number).\n\n### CUSTOM → Multiple approaches\nSee `get_migration_guide(\"custom-data-conversion\")` for the full guide. Summary:\n\n| Old customData type | New approach |\n|--------------------|--------------|\n| DYNAMIC_LIST (list of objects) | `COMPONENT_LIST` + child component |\n| OBJECT (≤3 simple fields) | Flatten into direct props on parent |\n| OBJECT (>3 fields or complex) | `COMPONENT_LIST` + child component |\n| STATIC_LIST (fixed count items) | `COMPONENT_LIST` (store owner manages count) |\n| ENUM (enumOptions) | `ENUM` with custom enum via `config add-enum` |\n\n### ENUM → ENUM\nOld ENUM type with `enumOptions` maps to new ENUM with `enumTypeId`. Create custom enums first:\n```bash\nnpx ikas-component config add-enum --name \"AspectRatio\" --options '{\"Square\":\"1:1\",\"Landscape\":\"16:9\",\"Portrait\":\"3:4\"}'\n# Use returned enumId in prop definition\n```\n\n## Types Not Available in New System\n\nThese old types do not exist in the new system and need workarounds:\n\n| Old Type | Workaround |\n|----------|------------|\n| `SLIDER` | Use `NUMBER`. Access value directly instead of `.value` |\n| `OBJECT` (customData) | Flatten into parent props or use COMPONENT_LIST |\n| `STATIC_LIST` (customData) | Use COMPONENT_LIST |\n\n## New Types Not in Old System\n\n| New Type | Description |\n|----------|-------------|\n| `NUMBER` | Numeric input (replaces SLIDER) |\n| `NUMBER_RANGE` | Two-number range (IkasNumberRange) |\n| `DATE` | Date picker |\n| `FUNCTION` | Function prop (callback) |\n| `TYPE` | Structured style type (padding, margin, etc.) |\n| `COMPONENT` | Single child component slot |\n| `RAFFLE` / `RAFFLE_LIST` | Raffle references |",
       "tags": [
         "migration",
         "props",
@@ -88,7 +88,7 @@
     "storefront-import-mapping": {
       "title": "Import Mapping: @ikas/storefront → @ikas/bp-storefront",
       "description": "Maps old @ikas/storefront imports to new @ikas/bp-storefront equivalents",
-      "content": "## Old Package → New Package\n\nAll imports change from `@ikas/storefront` to `@ikas/bp-storefront`. **This is NOT a find-and-replace.** Even types with the same name (`IkasImage`, `IkasProduct`, etc.) come from different packages and may have different shapes. Always verify with `get_type_definition` or `get_model_guide` before assuming compatibility.\n\n## Type Rename Table\n\n| Old Import (`@ikas/storefront`) | New Import (`@ikas/bp-storefront`) | Notes |\n|-----------|-----------|-------|\n| `IkasImage`, `IkasVideo`, `IkasNavigationLink`, `IkasProduct`, `IkasProductList`, `IkasCategory`, `IkasCategoryList`, `IkasBrand`, `IkasBlog`, `IkasBlogList`, `IkasBlogCategory`, `IkasBlogCategoryList` | Same name | Different package — shape may differ; verify before assuming. |\n| `IkasSlider` | *(removed)* | Use plain `number`. |\n| `IkasAttributeDetail` | `IkasProductAttributeValue` | Renamed. |\n| `IkasAttributeList` | `IkasProductAttributeValue[]` | Renamed; now a plain array. |\n| `IkasComponentRenderer` | `IkasComponentRenderer` | Same name, different usage — see below. |\n\n## Function / Pattern Rename Table\n\n| Old | New | Notes |\n|-----|-----|-------|\n| `<Image>` component | `getDefaultSrc()` / `getSrc()` + native `<img>` | See `react-to-preact` for image patterns. |\n| `useStore()` hook | Direct imports (`cartStore`, `customerStore`, ...) | Stores are MobX observables; no wrapper hook. |\n| `<IkasComponentRenderer>{children}</...>` | `<IkasComponentRenderer id=\"...\" components={list as any[]} parentProps={props} />` | New props-based API. |\n\nFor all import/observer/hook/event-handling behavior changes, see `get_migration_guide(\"react-to-preact\")` — this topic is intentionally a quick rename reference.\n",
+      "content": "## Old Package → New Package\n\nAll imports change from `@ikas/storefront` to `@ikas/bp-storefront`. **This is NOT a find-and-replace.** Even types with the same name (`IkasImage`, `IkasProduct`, etc.) come from different packages and may have different shapes. Always verify with `get_type_definition` or `get_model_guide` before assuming compatibility.\n\n## Type Rename Table\n\n| Old Import (`@ikas/storefront`) | New Import (`@ikas/bp-storefront`) | Notes |\n|-----------|-----------|-------|\n| `IkasImage`, `IkasVideo`, `IkasNavigationLink`, `IkasProduct`, `IkasProductList`, `IkasCategory`, `IkasCategoryList`, `IkasBrand`, `IkasBlog`, `IkasBlogList`, `IkasBlogCategory`, `IkasBlogCategoryList` | Same name | Different package — shape may differ; verify before assuming. |\n| `IkasSlider` | *(removed)* | Use plain `number`. |\n| `IkasAttributeDetail` | `IkasProductAttributeDetail` | Renamed only; still the `{ product, attributePropValue }` wrapper. `IkasProductAttributeValue` is a DIFFERENT type — the resolved value returned by `getAttributeDetailValues()`. |\n| `IkasAttributeList` | `IkasProductAttributeList` | Renamed only; still a single `{ product, attributeListPropValue }` wrapper, NOT an array. Values come from `getAttributeListValues()`. |\n| `IkasComponentRenderer` | `IkasComponentRenderer` | Same name, different usage — see below. |\n\n## Function / Pattern Rename Table\n\n| Old | New | Notes |\n|-----|-----|-------|\n| `<Image>` component | `getDefaultSrc()` / `getSrc()` + native `<img>` | See `react-to-preact` for image patterns. |\n| `useStore()` hook | Direct imports (`cartStore`, `customerStore`, ...) | Stores are MobX observables; no wrapper hook. |\n| `<IkasComponentRenderer>{children}</...>` | `<IkasComponentRenderer id=\"...\" components={list as any[]} parentProps={props} />` | New props-based API. |\n\nFor all import/observer/hook/event-handling behavior changes, see `get_migration_guide(\"react-to-preact\")` — this topic is intentionally a quick rename reference.\n",
       "tags": [
         "migration",
         "imports",
@@ -212,13 +212,19 @@
     "prop-runtime-shapes": {
       "title": "Runtime Shapes of Prop Types",
       "description": "Exact TypeScript shapes your component receives at runtime for each prop type. Covers common confusions (.data vs .links, .variant vs .product).",
-      "content": "When you declare a prop in `ikas.config.json`, the component receives a specific runtime shape. This table documents what you actually get — which is often different from the editor UI suggests and from naive expectations.\n\n## Reference Table\n\n| PropType | Runtime Shape | Key Access Pattern |\n|----------|---------------|--------------------|\n| `TEXT` | `string` | `props.myText` |\n| `RICH_TEXT` | `string` (HTML) | `<div dangerouslySetInnerHTML={{ __html: props.html }} />` |\n| `NUMBER` | `number` | `props.width` (direct number, NOT `.value`) |\n| `BOOLEAN` | `boolean` | `props.enabled` |\n| `COLOR` | `string` (CSS color) | `style={{ color: props.textColor }}` |\n| `IMAGE` | `IkasImage \\| null` | `getDefaultSrc(props.image)` or `getSrc(props.image, { width: 400 })` |\n| `IMAGE_LIST` | `IkasImageList` | `props.images.map(img => getDefaultSrc(img))` |\n| `VIDEO` | `IkasVideo \\| null` | Check `.url`, `.type` (EMBED vs FILE) |\n| `LINK` | `IkasNavigationLink` | `props.link.href`, `props.link.label`, `props.link.subLinks`, `props.link.openInNewTab` |\n| `LIST_OF_LINK` | `IkasNavigationLinkList` | **`props.links.links`** — access via `.links` property (NOT `.data`) |\n| `PRODUCT` | `IkasProduct \\| null` | `props.product.name`, `.prices`, etc. |\n| `PRODUCT_LIST` | `IkasProductList` | **`props.productList.data`** — array of products via `.data` property |\n| `CATEGORY` | `IkasCategory \\| null` | `props.category.name`, `.href` |\n| `CATEGORY_LIST` | `IkasCategoryList` | Check shape with `get_type_definition(\"IkasCategoryList\")` |\n| `BRAND` / `BRAND_LIST` | `IkasBrand \\| null` / `IkasBrandList` | Use `get_model_guide(\"IkasBrand\")` |\n| `BLOG` / `BLOG_LIST` | `IkasBlog \\| null` / `IkasBlogList` | Blog list uses `.data` |\n| `PRODUCT_ATTRIBUTE` | `IkasProductAttributeValue \\| null` | Direct single value |\n| `PRODUCT_ATTRIBUTE_LIST` | `IkasProductAttributeValue[]` | Plain array (NOT wrapped) |\n| `ENUM` | `string` (the enum value) | Compare directly: `props.type === \"email\"` |\n| `COMPONENT` | `any` | Pass to `<IkasComponentRenderer components={[comp] as any[]} />` |\n| `COMPONENT_LIST` | `any[]` | Pass to `<IkasComponentRenderer components={list as any[]} />` |\n\n## Critical: Inconsistent Access Patterns\n\nThe most common mistakes come from **list-type props having inconsistent access patterns**:\n\n- `PRODUCT_LIST` → `.data` (array of products)\n- `BLOG_LIST` → `.data` (array of blogs)\n- `LIST_OF_LINK` → `.links` (NOT `.data`)\n- `PRODUCT_ATTRIBUTE_LIST` → plain array (no wrapper)\n- `IMAGE_LIST` → plain array via `.data` (check with `get_type_definition`)\n\n**When in doubt, call `get_model_guide(\"IkasProductList\")` etc. for the exact shape.**\n\n## Image Sizing: getDefaultSrc vs getSrc\n\n- `getDefaultSrc(image)` — returns the default-sized URL. Use for small images, thumbnails, or when size doesn't matter.\n- `getSrc(image, { width: 400 })` — returns a URL at a specific width. Use for performance-critical images where you know the rendered size.\n- `createMediaSrcset(image)` — generates a responsive `srcset` string for `<img srcset={...}>`.\n\n**Rule of thumb:** Use `getSrc` with a concrete width for large images; use `getDefaultSrc` for icons/small images.\n\n## Store Data Shapes (cartStore, customerStore, etc.)\n\nStore data is NOT a prop type — you import stores directly from `@ikas/bp-storefront`. Their runtime shapes are:\n\n- `cartStore.cart` → `IkasCart`: `.orderLineItems` is the array; each item has **`.variant`** (not `.product`), `.quantity`, `.totalPrice`\n- `customerStore.customer` → `IkasCustomer | null`: null when logged out, has `.firstName`, `.lastName`, `.email`, `.id`\n- `customerStore.isAuthenticated` → boolean\n\n**For full store shapes, always use `get_model_guide(\"IkasCart\")`, `get_model_guide(\"IkasCustomer\")`, etc. — do not guess.**\n\n## Old → New Runtime Shape Changes\n\nWhen migrating, remember these runtime changes:\n\n- Old `IkasSlider` (with `.value`) → New `number` (plain). Replace `width?.value` with just `width`.\n- Old `<Image>` component (renders itself) → New `getDefaultSrc(image)` + native `<img>`.\n- Old `useStore()` hook → New direct import: `import { cartStore } from '@ikas/bp-storefront'`.\n- Old `IkasAttributeDetail` / `IkasAttributeList` → New `IkasProductAttributeValue` / array.\n\n\n\n## Order Line Item Shapes (cart, order pages)\n\nThese come up when iterating over `IkasCart.orderLineItems` or `IkasOrder.orderLineItems`. They trip up LLMs because the field names don't match scalar intuition:\n\n- **`IkasOrderLineItemOption.values`** — this is an **array** of `IkasOrderLineItemOptionValue`, NOT a scalar `.value`. Iterate it with `.map`:\n\n  ```tsx\n  // WRONG — there is no .value on IkasOrderLineItemOption\n  <span>{option.value}</span>\n\n  // RIGHT — .values is an array, each item has its own .name/.value/.formattedPrice\n  {option.values.map((v) => (\n    <span key={v.name}>{v.name}: {v.value}</span>\n  ))}\n  ```\n\n- **`IkasOrderAdjustment` has no `.formattedAmount` property.** Call the helper instead: `getOrderAdjustmentFormattedAmount(adjustment)` from `@ikas/bp-storefront`. The helper returns the formatted currency string and handles the sign (negated for decrements). See `get_function_doc(\"getOrderAdjustmentFormattedAmount\")`.\n\n## See Also\n- `get_model_guide(\"<TypeName>\")` — one-stop shop for type definition + utility functions + examples\n- `get_type_definition(\"<TypeName>\")` — raw type definition\n- `get_framework_guide(\"common-pitfalls\")` — runtime shape mistakes (point #9 covers `.data`)\n- `get_framework_guide(\"imports\")` — where each type/function comes from",
+      "content": "When you declare a prop in `ikas.config.json`, the component receives a specific runtime shape. This table documents what you actually get — which is often different from the editor UI suggests and from naive expectations.\n\n## Reference Table\n\n| PropType | Runtime Shape | Key Access Pattern |\n|----------|---------------|--------------------|\n| `TEXT` | `string` | `props.myText` |\n| `RICH_TEXT` | `string` (HTML) | `<div dangerouslySetInnerHTML={{ __html: props.html }} />` |\n| `NUMBER` | `number` | `props.width` (direct number, NOT `.value`) |\n| `BOOLEAN` | `boolean` | `props.enabled` |\n| `COLOR` | `string` (CSS color) | `style={{ color: props.textColor }}` |\n| `IMAGE` | `IkasImage \\| null` | `getDefaultSrc(props.image)` or `getSrc(props.image, { width: 400 })` |\n| `IMAGE_LIST` | `IkasImageList` | `props.images.map(img => getDefaultSrc(img))` |\n| `VIDEO` | `IkasVideo \\| null` | Check `.url`, `.type` (EMBED vs FILE) |\n| `LINK` | `IkasNavigationLink` | `props.link.href`, `props.link.label`, `props.link.subLinks`, `props.link.openInNewTab` |\n| `LIST_OF_LINK` | `IkasNavigationLinkList` | **`props.links.links`** — access via `.links` property (NOT `.data`) |\n| `PRODUCT` | `IkasProduct \\| null` | `props.product.name`, `.prices`, etc. |\n| `PRODUCT_LIST` | `IkasProductList` | **`props.productList.data`** — array of products via `.data` property |\n| `CATEGORY` | `IkasCategory \\| null` | `props.category.name`, `.href` |\n| `CATEGORY_LIST` | `IkasCategoryList` | Check shape with `get_type_definition(\"IkasCategoryList\")` |\n| `BRAND` / `BRAND_LIST` | `IkasBrand \\| null` / `IkasBrandList` | Use `get_model_guide(\"IkasBrand\")` |\n| `BLOG` / `BLOG_LIST` | `IkasBlog \\| null` / `IkasBlogList` | Blog list uses `.data` |\n| `PRODUCT_ATTRIBUTE` | `IkasProductAttributeDetail \\| null` | Wrapper `{ product, attributePropValue }` — **NOT** the value; `getAttributeDetailValues(prop)` |\n| `PRODUCT_ATTRIBUTE_LIST` | `IkasProductAttributeList` | Wrapper `{ product, attributeListPropValue }` — a single object, **NOT** an array; `getAttributeListValues(prop)` |\n| `ENUM` | `string` (the enum value) | Compare directly: `props.type === \"email\"` |\n| `COMPONENT` | `any` | Pass to `<IkasComponentRenderer components={[comp] as any[]} />` |\n| `COMPONENT_LIST` | `any[]` | Pass to `<IkasComponentRenderer components={list as any[]} />` |\n\n## Authored `defaultValue` ≠ runtime read shape (LINK / LIST_OF_LINK)\n\nThe shapes above are what your component RECEIVES (read access: `props.link.href`). They are NOT what you write as a prop `defaultValue` in `ikas.config.json`. The authored default is a typed object:\n- `LINK` → `{ \"linkType\": \"EXTERNAL\", \"label\": \"Shop\", \"externalLink\": \"https://…\", \"subLinks\": [] }` (or `\"linkType\": \"PAGE\"` with `\"pageType\"`).\n- `LIST_OF_LINK` → `{ \"links\": [ <link>, … ] }`.\n\nDo NOT author a default as `{ href, label }` (legacy shape) or as a JSON string — the CLI rejects both. Full reference: `get_framework_guide(\"prop-types\")` → \"LINK and LIST_OF_LINK props\".\n\n## Three shapes, one prop (PRODUCT_ATTRIBUTE / PRODUCT_ATTRIBUTE_LIST)\n\nSame trap as LINK, but worse: the prop you receive is a **wrapper**, not a value, and accessing the value you expect fails silently — `check`/`build` pass, every field is `undefined`, the component renders nothing. The editor stores `{ attributeId, usePageData }`, your component receives the `{ product, attributePropValue }` wrapper, and the values only come out of the helpers:\n\n```tsx\nimport { getAttributeDetailValues, getAttributeListValues } from \"@ikas/bp-storefront\";\n\n// WRONG — no such field at runtime; compiles clean, renders nothing\nreturn attribute?.value ?? null;\n\n// RIGHT — PRODUCT_ATTRIBUTE\nif (!attribute?.attributePropValue?.attributeId) return null;\nconst html = getAttributeDetailValues(attribute).map((v) => v.value).filter(Boolean).join(\"\");\n\n// RIGHT — PRODUCT_ATTRIBUTE_LIST (a single object, never `.map` it directly)\nconst groups = getAttributeListValues(attributeList); // IkasProductAttributeMap[]: { attribute, values }\n```\n\nFull reference: `get_framework_guide(\"prop-types\")` → \"PRODUCT_ATTRIBUTE and PRODUCT_ATTRIBUTE_LIST props\".\n\n## Critical: Inconsistent Access Patterns\n\nThe most common mistakes come from **list-type props having inconsistent access patterns**:\n\n- `PRODUCT_LIST` → `.data` (array of products)\n- `BLOG_LIST` → `.data` (array of blogs)\n- `LIST_OF_LINK` → `.links` (NOT `.data`)\n- `PRODUCT_ATTRIBUTE_LIST` → a single wrapper object (NOT an array): `.attributeListPropValue.attributeIds` holds the selection; values come from `getAttributeListValues(prop)` (grouped `{ attribute, values }` maps)\n- `PRODUCT_ATTRIBUTE` → a single wrapper object too: `.attributePropValue.attributeId`; values come from `getAttributeDetailValues(prop)`\n- `IMAGE_LIST` → plain array via `.data` (check with `get_type_definition`)\n\n**When in doubt, call `get_model_guide(\"IkasProductList\")` etc. for the exact shape.**\n\n## Image Sizing: getDefaultSrc vs getSrc\n\n- `getDefaultSrc(image)` — returns the default-sized URL. Use for small images, thumbnails, or when size doesn't matter.\n- `getSrc(image, { width: 400 })` — returns a URL at a specific width. Use for performance-critical images where you know the rendered size.\n- `createMediaSrcset(image)` — generates a responsive `srcset` string for `<img srcset={...}>`.\n\n**Rule of thumb:** Use `getSrc` with a concrete width for large images; use `getDefaultSrc` for icons/small images.\n\n## Store Data Shapes (cartStore, customerStore, etc.)\n\nStore data is NOT a prop type — you import stores directly from `@ikas/bp-storefront`. Their runtime shapes are:\n\n- `cartStore.cart` → `IkasCart`: `.orderLineItems` is the array; each item has **`.variant`** (not `.product`), `.quantity`, `.totalPrice`\n- `customerStore.customer` → `IkasCustomer | null`: null when logged out, has `.firstName`, `.lastName`, `.email`, `.id`\n- `customerStore.isAuthenticated` → boolean\n\n**For full store shapes, always use `get_model_guide(\"IkasCart\")`, `get_model_guide(\"IkasCustomer\")`, etc. — do not guess.**\n\n## Old → New Runtime Shape Changes\n\nWhen migrating, remember these runtime changes:\n\n- Old `IkasSlider` (with `.value`) → New `number` (plain). Replace `width?.value` with just `width`.\n- Old `<Image>` component (renders itself) → New `getDefaultSrc(image)` + native `<img>`.\n- Old `useStore()` hook → New direct import: `import { cartStore } from '@ikas/bp-storefront'`.\n- Old `IkasAttributeDetail` / `IkasAttributeList` → New `IkasProductAttributeDetail` / `IkasProductAttributeList`. **Rename only — the wrapper shape did NOT change.** See `get_framework_guide(\"prop-types\")` → \"PRODUCT_ATTRIBUTE and PRODUCT_ATTRIBUTE_LIST props\".\n\n\n\n## Order Line Item Shapes (cart, order pages)\n\nThese come up when iterating over `IkasCart.orderLineItems` or `IkasOrder.orderLineItems`. They trip up LLMs because the field names don't match scalar intuition:\n\n- **`IkasOrderLineItemOption.values`** — this is an **array** of `IkasOrderLineItemOptionValue`, NOT a scalar `.value`. Iterate it with `.map`:\n\n  ```tsx\n  // WRONG — there is no .value on IkasOrderLineItemOption\n  <span>{option.value}</span>\n\n  // RIGHT — .values is an array, each item has its own .name/.value/.formattedPrice\n  {option.values.map((v) => (\n    <span key={v.name}>{v.name}: {v.value}</span>\n  ))}\n  ```\n\n- **`IkasOrderAdjustment` has no `.formattedAmount` property.** Call the helper instead: `getOrderAdjustmentFormattedAmount(adjustment)` from `@ikas/bp-storefront`. The helper returns the formatted currency string and handles the sign (negated for decrements). See `get_function_doc(\"getOrderAdjustmentFormattedAmount\")`.\n\n## See Also\n- `get_model_guide(\"<TypeName>\")` — one-stop shop for type definition + utility functions + examples\n- `get_type_definition(\"<TypeName>\")` — raw type definition\n- `get_framework_guide(\"common-pitfalls\")` — runtime shape mistakes (point #9 covers `.data`)\n- `get_framework_guide(\"imports\")` — where each type/function comes from",
       "tags": [
         "migration",
         "runtime",
         "shapes",
         "PRODUCT_LIST",
         "LIST_OF_LINK",
+        "PRODUCT_ATTRIBUTE",
+        "PRODUCT_ATTRIBUTE_LIST",
+        "IkasProductAttributeDetail",
+        "IkasProductAttributeList",
+        "getAttributeDetailValues",
+        "getAttributeListValues",
         "IkasCart",
         "getDefaultSrc",
         "getSrc",
@@ -230,7 +236,7 @@
     "link-prop-decision-guide": {
       "title": "LINK Prop Decision Guide",
       "description": "When to use LINK, LIST_OF_LINK, LINK with subLinks, or COMPONENT_LIST for link-related data. Addresses common confusion between similar prop types.",
-      "content": "Several prop types can represent \"links\" in the new system. Choosing the right one depends on the shape of the data and what the store owner should control.\n\n## Decision Tree\n\n**Is it a single link?**\n→ Use `LINK`. Runtime: `IkasNavigationLink { href, label, subLinks, openInNewTab, ... }`\n\n**Is it a flat list of sibling links (no extra data per link)?**\n→ Use `LIST_OF_LINK`. Runtime: `IkasNavigationLinkList` with `.links: IkasNavigationLink[]`\n\n**Is it a hierarchical menu (links with sub-links, no extra data)?**\n→ Use `LIST_OF_LINK`. Each `IkasNavigationLink` already has `.subLinks: IkasNavigationLink[]`. The editor handles sub-link nesting natively.\n\n**Is it a list of links WITH extra per-link data (image, color, badge, mega-menu content)?**\n→ Use `COMPONENT_LIST` with a child component that has one `LINK` prop + the extra fields.\n\n**Is it a list of products/categories/blogs (not generic links)?**\n→ Use the specific prop type (`PRODUCT_LIST`, `CATEGORY_LIST`, `BLOG_LIST`), NOT `LIST_OF_LINK`.\n\n## Examples\n\n### Footer bottom bar: \"Privacy | Terms | Contact\"\nSimple flat list → `LIST_OF_LINK`:\n```json\n{ \"name\": \"bottomLinks\", \"type\": \"LIST_OF_LINK\" }\n```\nAccess: `props.bottomLinks.links.map(link => <a href={link.href}>{link.label}</a>)`\n\n### Main nav menu with dropdowns: \"Women (→ Tops, Bottoms, Shoes)\"\nHierarchical but just labels + links → `LIST_OF_LINK` (sub-links built-in):\n```json\n{ \"name\": \"menu\", \"type\": \"LIST_OF_LINK\" }\n```\nAccess: `props.menu.links.map(link => (<div>{link.label}{link.subLinks?.map(...)}</div>))`\n\n### Mega menu with images per column\nLinks PLUS image + custom layout per menu item → `COMPONENT_LIST`:\n```json\n// Parent:\n{ \"name\": \"menuItems\", \"type\": \"COMPONENT_LIST\", \"filteredComponentIds\": [\"my-theme-mega-menu-item\"] }\n// Child MegaMenuItem:\n{ \"props\": [\n  { \"name\": \"mainLink\", \"type\": \"LINK\" },\n  { \"name\": \"columnImage\", \"type\": \"IMAGE\" },\n  { \"name\": \"subLinks\", \"type\": \"LIST_OF_LINK\" }\n]}\n```\n\n### Social icons: \"Instagram | Facebook | Twitter\" each with its own icon image\nList of links with an image each → `COMPONENT_LIST`:\n```json\n// Parent:\n{ \"name\": \"socials\", \"type\": \"COMPONENT_LIST\", \"filteredComponentIds\": [\"my-theme-social-link\"] }\n// Child SocialLink:\n{ \"props\": [\n  { \"name\": \"link\", \"type\": \"LINK\" },\n  { \"name\": \"icon\", \"type\": \"IMAGE\" }\n]}\n```\n\n## Old CUSTOM → Which Link Prop?\n\nWhen migrating an old CUSTOM/DYNAMIC_LIST:\n\n| Old customData shape | New prop |\n|----------------------|----------|\n| `OBJECT { link: LINK }` | `LINK` (flatten) |\n| `DYNAMIC_LIST of OBJECT { link: LINK }` | `LIST_OF_LINK` (if just label+href) or `COMPONENT_LIST` (if more fields) |\n| `DYNAMIC_LIST of OBJECT { link, image }` | `COMPONENT_LIST` + child component |\n| `DYNAMIC_LIST of OBJECT { mainlink, sublinks: LIST_OF_LINK }` | `LIST_OF_LINK` (subLinks are native) |\n| `DYNAMIC_LIST of OBJECT { mainlink, sublinks: DYNAMIC_LIST of OBJECT { links, images, cols } }` | `COMPONENT_LIST` + `MenuItem` child + nested `COMPONENT_LIST` for columns |\n\n## See Also\n- `get_migration_guide(\"component-composition-decision-guide\")` — when COMPONENT_LIST is overkill vs. repeated scalars vs. domain LIST types\n- `get_migration_guide(\"prop-runtime-shapes\")` — exact shapes for each link type\n- `get_migration_guide(\"component-renderer-limitations\")` — COMPONENT_LIST constraints\n- `get_framework_guide(\"navigation-patterns\")` — Router.navigate usage, link handling",
+      "content": "Several prop types can represent \"links\" in the new system. Choosing the right one depends on the shape of the data and what the store owner should control.\n\n## Decision Tree\n\n**Is it a single link?**\n→ Use `LINK`. Runtime: `IkasNavigationLink { href, label, subLinks, openInNewTab, ... }`\n\n**Is it a flat list of sibling links (no extra data per link)?**\n→ Use `LIST_OF_LINK`. Runtime: `IkasNavigationLinkList` with `.links: IkasNavigationLink[]`\n\n**Is it a hierarchical menu (links with sub-links, no extra data)?**\n→ Use `LIST_OF_LINK`. Each `IkasNavigationLink` already has `.subLinks: IkasNavigationLink[]`. The editor handles sub-link nesting natively.\n\n**Is it a list of links WITH extra per-link data (image, color, badge, mega-menu content)?**\n→ Use `COMPONENT_LIST` with a child component that has one `LINK` prop + the extra fields.\n\n**Is it a list of products/categories/blogs (not generic links)?**\n→ Use the specific prop type (`PRODUCT_LIST`, `CATEGORY_LIST`, `BLOG_LIST`), NOT `LIST_OF_LINK`.\n\n## Examples\n\n### Footer bottom bar: \"Privacy | Terms | Contact\"\nSimple flat list → `LIST_OF_LINK`:\n```json\n{ \"name\": \"bottomLinks\", \"type\": \"LIST_OF_LINK\" }\n```\nAccess: `props.bottomLinks.links.map(link => <a href={link.href}>{link.label}</a>)`\n\n### Main nav menu with dropdowns: \"Women (→ Tops, Bottoms, Shoes)\"\nHierarchical but just labels + links → `LIST_OF_LINK` (sub-links built-in):\n```json\n{ \"name\": \"menu\", \"type\": \"LIST_OF_LINK\" }\n```\nAccess: `props.menu.links.map(link => (<div>{link.label}{link.subLinks?.map(...)}</div>))`\n\n### Mega menu with images per column\nLinks PLUS image + custom layout per menu item → `COMPONENT_LIST`:\n```json\n// Parent:\n{ \"name\": \"menuItems\", \"type\": \"COMPONENT_LIST\", \"filteredComponentIds\": [\"my-theme-mega-menu-item\"] }\n// Child MegaMenuItem:\n{ \"props\": [\n  { \"name\": \"mainLink\", \"type\": \"LINK\" },\n  { \"name\": \"columnImage\", \"type\": \"IMAGE\" },\n  { \"name\": \"subLinks\", \"type\": \"LIST_OF_LINK\" }\n]}\n```\n\n### Social icons: \"Instagram | Facebook | Twitter\" each with its own icon image\nList of links with an image each → `COMPONENT_LIST`:\n```json\n// Parent:\n{ \"name\": \"socials\", \"type\": \"COMPONENT_LIST\", \"filteredComponentIds\": [\"my-theme-social-link\"] }\n// Child SocialLink:\n{ \"props\": [\n  { \"name\": \"link\", \"type\": \"LINK\" },\n  { \"name\": \"icon\", \"type\": \"IMAGE\" }\n]}\n```\n\n## Old CUSTOM → Which Link Prop?\n\nWhen migrating an old CUSTOM/DYNAMIC_LIST:\n\n| Old customData shape | New prop |\n|----------------------|----------|\n| `OBJECT { link: LINK }` | `LINK` (flatten) |\n| `DYNAMIC_LIST of OBJECT { link: LINK }` | `LIST_OF_LINK` (if just label+href) or `COMPONENT_LIST` (if more fields) |\n| `DYNAMIC_LIST of OBJECT { link, image }` | `COMPONENT_LIST` + child component |\n| `DYNAMIC_LIST of OBJECT { mainlink, sublinks: LIST_OF_LINK }` | `LIST_OF_LINK` (subLinks are native) |\n| `DYNAMIC_LIST of OBJECT { mainlink, sublinks: DYNAMIC_LIST of OBJECT { links, images, cols } }` | `COMPONENT_LIST` + `MenuItem` child + nested `COMPONENT_LIST` for columns |\n\n## Authoring the default value (config shape)\n\nWhichever type you pick, the `defaultValue` in `ikas.config.json` is the typed object — NOT the runtime `.href` read shape, and NOT a JSON string:\n- `LINK` → `{ \"linkType\": \"EXTERNAL\", \"label\": \"Shop\", \"externalLink\": \"https://…\", \"subLinks\": [] }` (or `\"linkType\": \"PAGE\"` + `\"pageType\"`; `\"FILE\"` + `\"fileUrl\"`).\n- `LIST_OF_LINK` → `{ \"links\": [ { \"linkType\": \"PAGE\", \"label\": \"Home\", \"pageType\": \"INDEX\", \"subLinks\": [] } ] }`.\n\nThe legacy `{ label, href }` shape is rejected by the CLI. Full reference: `get_framework_guide(\"prop-types\")` → \"LINK and LIST_OF_LINK props\".\n\n## See Also\n- `get_migration_guide(\"component-composition-decision-guide\")` — when COMPONENT_LIST is overkill vs. repeated scalars vs. domain LIST types\n- `get_migration_guide(\"prop-runtime-shapes\")` — exact shapes for each link type\n- `get_migration_guide(\"component-renderer-limitations\")` — COMPONENT_LIST constraints\n- `get_framework_guide(\"navigation-patterns\")` — Router.navigate usage, link handling",
       "tags": [
         "migration",
         "LINK",

package/data/section-templates/account-info-section/children/AccountFavorites/ikas-config-snippet.json

@@ -34,6 +34,19 @@
       "displayName": "Components",
       "type": "COMPONENT_LIST",
       "required": false,
+      "defaultValue": {
+        "components": [
+          {
+            "codeComponentId": "nb34u3yu-card-product-name"
+          },
+          {
+            "codeComponentId": "nb34u3yu-card-product-variants"
+          },
+          {
+            "codeComponentId": "nb34u3yu-card-product-price"
+          }
+        ]
+      },
       "privateVarMap": {
         "product": {
           "id": "pvm_1772803530689_1",

package/data/section-templates/account-info-section/children/AccountOrders/index.tsx

@@ -80,7 +80,7 @@ export function AccountOrders({
           <Button
             variant="primary"
             size="s"
-            onClick={() => Router.navigate("/")}
+            onClick={() => Router.navigateToPage("INDEX")}
           >
             {shopButtonText}
           </Button>

package/data/section-templates/account-info-section/ikas-config-snippet.json

@@ -50,6 +50,25 @@
       "displayName": "Components",
       "type": "COMPONENT_LIST",
       "required": false,
+      "defaultValue": {
+        "components": [
+          {
+            "codeComponentId": "nb34u3yu-account-info-content"
+          },
+          {
+            "codeComponentId": "nb34u3yu-account-orders"
+          },
+          {
+            "codeComponentId": "nb34u3yu-account-addresses"
+          },
+          {
+            "codeComponentId": "nb34u3yu-account-favorites"
+          },
+          {
+            "codeComponentId": "nb34u3yu-account-order-detail"
+          }
+        ]
+      },
       "filteredComponentIds": [
         "<id-of-AccountInfoContent>",
         "<id-of-AccountOrders>",

package/data/section-templates/add-to-cart/ikas-config-snippet.json

@@ -40,6 +40,10 @@
       "displayName": "Top Spacing",
       "type": "TYPE",
       "required": false,
+      "defaultValue": {
+        "value": 0,
+        "unit": "px"
+      },
       "groupId": "mobile",
       "typeId": "@ikas/bp-storefront-models-MarginTopStyleType"
     },
@@ -48,6 +52,10 @@
       "displayName": "Bottom Spacing",
       "type": "TYPE",
       "required": false,
+      "defaultValue": {
+        "value": 0,
+        "unit": "px"
+      },
       "groupId": "mobile",
       "typeId": "@ikas/bp-storefront-models-MarginBottomStyleType"
     },
@@ -56,6 +64,10 @@
       "displayName": "Top Spacing",
       "type": "TYPE",
       "required": false,
+      "defaultValue": {
+        "value": 0,
+        "unit": "px"
+      },
       "groupId": "desktop",
       "typeId": "@ikas/bp-storefront-models-MarginTopStyleType"
     },
@@ -64,6 +76,10 @@
       "displayName": "Bottom Spacing",
       "type": "TYPE",
       "required": false,
+      "defaultValue": {
+        "value": 0,
+        "unit": "px"
+      },
       "groupId": "desktop",
       "typeId": "@ikas/bp-storefront-models-MarginBottomStyleType"
     },
@@ -72,6 +88,7 @@
       "displayName": "Hide Quantity Selector",
       "type": "BOOLEAN",
       "required": false,
+      "defaultValue": false,
       "groupId": "settings"
     },
     {

package/data/section-templates/add-to-cart/index.tsx

@@ -10,13 +10,14 @@ import {
   IkasBundleSettings,
   IkasStorefrontConfig,
 } from "@ikas/bp-storefront";
-import { useState } from "preact/hooks";
+import { useEffect, useState } from "preact/hooks";
 import { Props } from "./types";
 import Button from "../../sub-components/Button";
 import QuantitySelector from "../../sub-components/QuantitySelector";
 import PayWithIkas from "./components/PayWithIkas";
 import { isBundleOutOfStock } from "../../utils/bundle";
 import { validateOptionSet } from "../../utils/optionSet";
+import { getProductCartLimits } from "../../utils/cartLimits";
 import { showToast } from "../../utils/toast";
 
 export function ProductDetailAddToCart({
@@ -37,6 +38,12 @@ export function ProductDetailAddToCart({
   const [quantity, setQuantity] = useState(1);
   const [isAddingToCart, setIsAddingToCart] = useState(false);
 
+  // Seed the quantity to the product's minimum-per-cart when the product changes.
+  useEffect(() => {
+    if (!product) return;
+    setQuantity(getProductCartLimits(product).min);
+  }, [product?.id]);
+
   if (!product) return null;
 
   const editLineID =
@@ -59,6 +66,8 @@ export function ProductDetailAddToCart({
 
   const isDisabled = isOutOfStock || isAddingToCart;
 
+  const { min: minQuantity, max: maxQuantity } = getProductCartLimits(product);
+
   const payWithIkasUrl = IkasStorefrontConfig.getPayWithIkasUrl();
   const routing = IkasStorefrontConfig.getCurrentRouting();
   const showPayWithIkas =
@@ -119,7 +128,12 @@ export function ProductDetailAddToCart({
     >
       <div className="kombos-pd-atc__actions">
         {!hideQuantityInput && !isOutOfStock && (
-          <QuantitySelector value={quantity} onChange={setQuantity} />
+          <QuantitySelector
+            value={quantity}
+            onChange={setQuantity}
+            min={minQuantity}
+            max={maxQuantity}
+          />
         )}
         <Button
           variant="primary"

package/data/section-templates/add-to-cart/sub-components/QuantitySelector/index.tsx

@@ -5,20 +5,27 @@ interface Props {
   value: number;
   onChange: (value: number) => void;
   size?: "default" | "sm";
+  min?: number;
+  max?: number;
 }
 
 export default function QuantitySelector({
   value,
   onChange,
   size = "default",
+  min = 1,
+  max,
 }: Props) {
+  const canDecrease = value > min;
+  const canIncrease = max == null || value < max;
+
   return (
     <div className={cx("kombos-pd__qty", size === "sm" && "kombos-pd__qty--sm")}>
       <button
         type="button"
         className="kombos-pd__qty-btn"
-        onClick={() => onChange(Math.max(1, value - 1))}
-        disabled={value <= 1}
+        onClick={() => onChange(Math.max(min, value - 1))}
+        disabled={!canDecrease}
         aria-label="Decrease quantity"
       >
         <MinusSVG />
@@ -31,7 +38,8 @@ export default function QuantitySelector({
       <button
         type="button"
         className="kombos-pd__qty-btn"
-        onClick={() => onChange(value + 1)}
+        onClick={() => onChange(max == null ? value + 1 : Math.min(max, value + 1))}
+        disabled={!canIncrease}
         aria-label="Increase quantity"
       >
         <PlusSVG />

package/data/section-templates/add-to-cart/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/blog-home-section/ikas-config-snippet.json

@@ -56,6 +56,7 @@
       "displayName": "Aspect Ratio",
       "type": "ENUM",
       "required": false,
+      "defaultValue": "Square",
       "groupId": "image-settings",
       "enumTypeId": "{{ENUM_ID:AspectRatio}}"
     },
@@ -64,6 +65,7 @@
       "displayName": "Image Fit",
       "type": "ENUM",
       "required": false,
+      "defaultValue": "Cover",
       "groupId": "image-settings",
       "enumTypeId": "{{ENUM_ID:ObjectFit}}"
     },

package/data/section-templates/blog-home-section/index.tsx

@@ -6,6 +6,7 @@ import {
   hasBlogListPrevPage,
   hasBlogListNextPage,
   getIkasBlogCategoryHref,
+  withRoutePrefix,
 } from "@ikas/bp-storefront";
 import { observer } from "@ikas/component-utils";
 import { cx } from "../../utils/cx";
@@ -47,7 +48,7 @@ export function BlogHome({
         {categories.length > 0 && (
           <div className="kombos-blog-home__categories">
             <a
-              href="/blog"
+              href={withRoutePrefix("/blog")}
               className={cx(
                 "kombos-blog-home__cat-btn",
                 "text-sm-medium",

package/data/section-templates/blog-post-section/ikas-config-snippet.json

@@ -41,6 +41,7 @@
       "displayName": "Aspect Ratio",
       "type": "ENUM",
       "required": false,
+      "defaultValue": "Square",
       "groupId": "appearance",
       "enumTypeId": "{{ENUM_ID:AspectRatio}}"
     },
@@ -49,6 +50,7 @@
       "displayName": "Image Fit",
       "type": "ENUM",
       "required": false,
+      "defaultValue": "Cover",
       "groupId": "appearance",
       "enumTypeId": "{{ENUM_ID:ObjectFit}}"
     },

package/data/section-templates/blog-post-section/index.tsx

@@ -2,6 +2,7 @@ import {
   getIkasBlogFormattedDate,
   getIkasBlogCategoryHref,
   getDefaultSrc,
+  withRoutePrefix,
 } from "@ikas/bp-storefront";
 
 import { Props } from "./types";
@@ -31,8 +32,8 @@ export function BlogPost({
   const writerName = getFullName(blogPost.writer?.firstName, blogPost.writer?.lastName);
 
   const breadcrumbItems: BreadcrumbItem[] = [
-    { label: homeText, href: "/" },
-    { label: blogText, href: "/blog" },
+    { label: homeText, href: withRoutePrefix("/") },
+    { label: blogText, href: withRoutePrefix("/blog") },
   ];
   if (categoryName && categoryHref) {
     breadcrumbItems.push({ label: categoryName, href: categoryHref });

package/data/section-templates/bundle-products/hooks/useBundleProducts.ts

@@ -9,15 +9,16 @@ import {
   cartStore,
   waitForCartStoreInit,
 } from "@ikas/bp-storefront";
-import { runInAction } from "mobx";
 import { adjustBundleProductQuantity } from "../utils/bundle";
 
+// No mobx action wrapper needed: adjustments go through the public
+// setBundleProductQuantity API (plain mutation, same as the SDK's own usage
+// examples), and keeping the theme free of direct mobx imports lets the
+// scaffold install cleanly under pnpm's strict node_modules layout.
 function adjustBundleQuantities(products: IkasBundleProduct[]) {
-  runInAction(() => {
-    for (const bp of products) {
-      adjustBundleProductQuantity(bp);
-    }
-  });
+  for (const bp of products) {
+    adjustBundleProductQuantity(bp);
+  }
 }
 
 export function useBundleProducts(product: IkasProduct | null | undefined) {

package/data/section-templates/bundle-products/ikas-config-snippet.json

@@ -16,6 +16,10 @@
       "displayName": "Top Spacing",
       "type": "TYPE",
       "required": false,
+      "defaultValue": {
+        "value": 0,
+        "unit": "px"
+      },
       "groupId": "mobile",
       "typeId": "@ikas/bp-storefront-models-MarginTopStyleType"
     },
@@ -24,6 +28,10 @@
       "displayName": "Bottom Spacing",
       "type": "TYPE",
       "required": false,
+      "defaultValue": {
+        "value": 0,
+        "unit": "px"
+      },
       "groupId": "mobile",
       "typeId": "@ikas/bp-storefront-models-MarginBottomStyleType"
     },
@@ -32,6 +40,10 @@
       "displayName": "Top Spacing",
       "type": "TYPE",
       "required": false,
+      "defaultValue": {
+        "value": 0,
+        "unit": "px"
+      },
       "groupId": "desktop",
       "typeId": "@ikas/bp-storefront-models-MarginTopStyleType"
     },
@@ -40,6 +52,10 @@
       "displayName": "Bottom Spacing",
       "type": "TYPE",
       "required": false,
+      "defaultValue": {
+        "value": 0,
+        "unit": "px"
+      },
       "groupId": "desktop",
       "typeId": "@ikas/bp-storefront-models-MarginBottomStyleType"
     },
@@ -48,6 +64,7 @@
       "displayName": "Furniture Bundle Mode",
       "type": "BOOLEAN",
       "required": false,
+      "defaultValue": false,
       "groupId": "settings"
     },
     {
@@ -55,6 +72,7 @@
       "displayName": "Disable Product Link",
       "type": "BOOLEAN",
       "required": false,
+      "defaultValue": false,
       "groupId": "settings"
     },
     {
@@ -86,6 +104,7 @@
       "displayName": "Aspect Ratio",
       "type": "ENUM",
       "required": false,
+      "defaultValue": "Square",
       "groupId": "appearance",
       "enumTypeId": "{{ENUM_ID:AspectRatio}}"
     },
@@ -94,6 +113,7 @@
       "displayName": "Image Fit",
       "type": "ENUM",
       "required": false,
+      "defaultValue": "Cover",
       "groupId": "appearance",
       "enumTypeId": "{{ENUM_ID:ObjectFit}}"
     }

package/data/section-templates/cart-section/components/EmptyState/index.tsx

@@ -12,7 +12,7 @@ export default function EmptyState({
   continueShoppingText,
 }: Props) {
   const handleContinueShopping = () => {
-    Router.navigate("/");
+    Router.navigateToPage("INDEX");
   };
 
   return (