@ikas/code-components-mcp 2.1.0 → 2.2.1

package/data/framework.json

@@ -35,7 +35,7 @@
     "prop-types": {
       "title": "Available Prop Types",
       "description": "All prop types that can be used in ikas.config.json",
-      "content": "Props define what the store editor can configure for each component. Each prop has a `type` that determines the editor UI and the TypeScript type received in your component.\n\n| Type | Editor UI | TypeScript Type | Description |\n|------|-----------|----------------|-------------|\n| `TEXT` | Text input | `string` | Single-line text |\n| `RICH_TEXT` | Rich text editor | `string` | HTML rich text content |\n| `NUMBER` | Number input | `number` | Numeric value |\n| `NUMBER_RANGE` | Number range input | `IkasNumberRange` | Number range with min, max, interval, and unit |\n| `BOOLEAN` | Toggle switch | `boolean` | True/false toggle |\n| `IMAGE` | Image picker | `IkasImage | null` | Image from editor. Use `getDefaultSrc(image)` for URL |\n| `IMAGE_LIST` | Image list picker | `IkasImageList` | Multiple images from editor |\n| `VIDEO` | Video picker | `IkasVideo | null` | Video from editor |\n| `DATE` | Date picker | `Date | string` | Date value |\n| `LINK` | Link editor | `IkasNavigationLink | null` | Navigation link with href, label, subLinks |\n| `LIST_OF_LINK` | Link list editor | `IkasNavigationLinkList` | List of navigation links |\n| `COLOR` | Color picker | `string` | CSS color value (hex, rgb, etc.) |\n| `PRODUCT` | Product picker | `IkasProduct | null` | Single product reference |\n| `PRODUCT_LIST` | Product list picker | `IkasProductList` | Product list with `.data` (products array), `.filters`, `.sort`, `.page`, etc. |\n| `PRODUCT_ATTRIBUTE` | Product attribute picker | `IkasProductAttributeValue | null` | Single product attribute value |\n| `PRODUCT_ATTRIBUTE_LIST` | Product attribute list picker | `IkasProductAttributeValue[]` | Multiple product attribute values |\n| `CATEGORY` | Category picker | `IkasCategory | null` | Single category reference |\n| `CATEGORY_LIST` | Category list picker | `IkasCategoryList` | Multiple category references |\n| `BRAND` | Brand picker | `IkasBrand | null` | Single brand reference |\n| `BRAND_LIST` | Brand list picker | `IkasBrandList` | Multiple brand references |\n| `BLOG` | Blog post picker | `IkasBlog | null` | Single blog post reference |\n| `BLOG_LIST` | Blog post list picker | `IkasBlogList` | Multiple blog post references |\n| `BLOG_CATEGORY` | Blog category picker | `IkasBlogCategory | null` | Single blog category reference |\n| `BLOG_CATEGORY_LIST` | Blog category list picker | `IkasBlogCategoryList` | Multiple blog category references |\n| `TYPE` | Type selector | Depends on typeId | Structured type (padding, margin, size, etc.). Available for both components and sections (sections have a restricted whitelist). |\n| `ENUM` | Dropdown selector | `string` | Enum-based style type (flex-direction, justify-content, align-items, etc.). Uses `enumTypeId`. Available for both components and sections. |\n| `COMPONENT` | Component slot | `any` | A single child component slot. Store owners can place a component in this slot from the editor. Render with `<IkasComponentRenderer>`. |\n| `COMPONENT_LIST` | Component list slot | `any` | A list of child components. Store owners can add multiple components from the editor. Render with `<IkasComponentRenderer>`. |\n\n### COMPONENT & COMPONENT_LIST props (child component slots)\n\nThese prop types enable **slot-based** architectures where store owners can drag child components into your section/component from the editor.\n\n- `COMPONENT` — a single child component slot\n- `COMPONENT_LIST` — a list of child components\n\n**Rendering:** Use the `<IkasComponentRenderer>` wrapper from `@ikas/bp-storefront`:\n```tsx\nimport { IkasComponentRenderer } from \"@ikas/bp-storefront\";\nimport { Props } from \"./types\";\n\nexport function MySection({ title, cardList, ...props }: Props) {\n  return (\n    <section>\n      <h2>{title}</h2>\n      <div className=\"cards\">\n        {/* COMPONENT_LIST — render a list of child components */}\n        <IkasComponentRenderer\n          id=\"card-list\"\n          components={cardList as any[]}\n          parentProps={props}\n        />\n      </div>\n    </section>\n  );\n}\nexport default MySection;\n```\n\n**Key rules:**\n- Always pass `parentProps={props}` so child components can access parent data via dynamic values\n- Cast the prop value: `components={myList as any[]}` for COMPONENT_LIST, `components={[myComp] as any[]}` for COMPONENT\n- `<IkasComponentRenderer>` handles rendering, styling, and reactivity of child components automatically\n\n**Config example (COMPONENT_LIST):**\n```json\n{\n  \"name\": \"cardList\",\n  \"displayName\": \"Card List\",\n  \"type\": \"COMPONENT_LIST\"\n}\n```\n\n**Config example (COMPONENT):**\n```json\n{\n  \"name\": \"headerSlot\",\n  \"displayName\": \"Header Slot\",\n  \"type\": \"COMPONENT\"\n}\n```\n\n### IMAGE type example:\n```json\n{\n  \"name\": \"heroImage\",\n  \"displayName\": \"Hero Image\",\n  \"type\": \"IMAGE\",\n  \"required\": false\n}\n```\nAccess in component: `getDefaultSrc(props.heroImage)` (import `getDefaultSrc` from `@ikas/bp-storefront`)\n\n### Prop grouping\nProps can be assigned to groups via `groupId` for organized editor sidebar display. See `get_framework_guide(\"prop-groups\")` for details.\n\n### Style Props: TYPE and ENUM\n\nThere are two prop types for style values:\n\n- **TYPE** — Structured types with numeric values and units (padding, margin, border-radius, sizes, etc.). Uses `typeId`.\n- **ENUM** — Enum types rendered as dropdown selectors (flex-direction, justify-content, align-items, etc.). Uses `enumTypeId`.\n\nBoth are available for components and sections. For sections, TYPE props are limited to a whitelist of style types. Use `list-types --component-type section` to see section-allowed types.\n\n### TYPE prop (structured types)\nThe `TYPE` prop lets you use structured storefront types like PaddingStyleType, MarginStyleType, SizeStyleType, etc. Available for both components and sections (sections have a restricted whitelist of style types).\n\n**Workflow:**\n1. Run `npx ikas-component config list-types` to get available types (requires dev server running with editor connected)\n2. Use the `typeId` from the output when adding the prop\n3. For sections: `npx ikas-component config list-types --component-type section` to see only section-allowed types\n\n**Example config:**\n```json\n{\n  \"name\": \"spacing\",\n  \"displayName\": \"Spacing\",\n  \"type\": \"TYPE\",\n  \"typeId\": \"@ikas/bp-storefront-models-PaddingStyleType\"\n}\n```\n\n**Array example** (append `_array` to typeId):\n```json\n{\n  \"name\": \"margins\",\n  \"displayName\": \"Margins\",\n  \"type\": \"TYPE\",\n  \"typeId\": \"@ikas/bp-storefront-models-MarginStyleType_array\"\n}\n```\nThis generates `margins?: MarginStyleType[]` in types.ts.\n\n**CLI command:**\n```bash\nnpx ikas-component config add-prop --component MyComp --name spacing --displayName Spacing --type TYPE --typeId \"@ikas/bp-storefront-models-PaddingStyleType\"\n```\n\n### ENUM prop (enum style types)\nThe `ENUM` prop lets you use enum-based types that render as dropdown selectors. There are two kinds of enum types:\n\n1. **Built-in enums** (prefix `@ikas/`): FlexDirectionStyleType, JustifyContentStyleType, AlignItemsStyleType, etc. Available from `list-types` when editor is connected.\n2. **Custom enums**: Created with `config add-enum`. Works offline, no editor needed.\n\n**IMPORTANT:** `add-prop --type ENUM` validates that the `enumTypeId` references an existing enum. You MUST create custom enums first with `config add-enum` before using them. The command will reject unknown enum IDs.\n\n**Custom enum workflow (recommended for AI-driven generation):**\n```bash\n# Step 1: Create the enum FIRST\nnpx ikas-component config add-enum --name \"AspectRatio\" --options '{\"Square\":\"1/1\",\"Landscape\":\"16/9\",\"Portrait\":\"3/4\"}'\n# Returns: {\"success\":true,\"enumId\":\"aBcDeFgHiJ\",...}\n\n# Step 2: Use the returned enumId in add-prop\nnpx ikas-component config add-prop --component MyComp --name aspectRatio --displayName \"Aspect Ratio\" --type ENUM --enumTypeId aBcDeFgHiJ\n```\n\n**Built-in enum workflow:**\n1. Run `npx ikas-component config list-types` — enum types have `category: \"enum\"` in the output\n2. Use the `enumTypeId` from the output when adding the prop\n\n**Example config (built-in enum):**\n```json\n{\n  \"name\": \"direction\",\n  \"displayName\": \"Direction\",\n  \"type\": \"ENUM\",\n  \"enumTypeId\": \"@ikas/bp-storefront-models-FlexDirectionStyleType\"\n}\n```\nThis generates `direction?: string` in types.ts.\n\n**CLI command (built-in enum):**\n```bash\nnpx ikas-component config add-prop --component MyComp --name direction --displayName Direction --type ENUM --enumTypeId \"@ikas/bp-storefront-models-FlexDirectionStyleType\"\n```\n\n**Note:** `list-types` requires dev server with editor connected. Custom enums (`config add-enum`) work offline.",
+      "content": "Props define what the store editor can configure for each component. Each prop has a `type` that determines the editor UI and the TypeScript type received in your component.\n\n| Type | Editor UI | TypeScript Type | Description |\n|------|-----------|----------------|-------------|\n| `TEXT` | Text input | `string` | Single-line text |\n| `RICH_TEXT` | Rich text editor | `string` | HTML rich text content |\n| `NUMBER` | Number input | `number` | Numeric value |\n| `NUMBER_RANGE` | Number range input | `IkasNumberRange` | Number range with min, max, interval, and unit |\n| `BOOLEAN` | Toggle switch | `boolean` | True/false toggle |\n| `IMAGE` | Image picker | `IkasImage | null` | Image from editor. Use `getDefaultSrc(image)` for URL |\n| `IMAGE_LIST` | Image list picker | `IkasImageList` | Multiple images from editor |\n| `VIDEO` | Video picker | `IkasVideo | null` | Video from editor |\n| `DATE` | Date picker | `Date | string` | Date value |\n| `LINK` | Link editor | `IkasNavigationLink | null` | Navigation link with href, label, subLinks |\n| `LIST_OF_LINK` | Link list editor | `IkasNavigationLinkList` | List of navigation links |\n| `COLOR` | Color picker | `string` | CSS color value (hex, rgb, etc.) |\n| `PRODUCT` | Product picker | `IkasProduct | null` | Single product reference |\n| `PRODUCT_LIST` | Product list picker | `IkasProductList` | Product list with `.data` (products array), `.filters`, `.sort`, `.page`, etc. |\n| `PRODUCT_ATTRIBUTE` | Product attribute picker | `IkasProductAttributeValue | null` | Single product attribute value |\n| `PRODUCT_ATTRIBUTE_LIST` | Product attribute list picker | `IkasProductAttributeValue[]` | Multiple product attribute values |\n| `CATEGORY` | Category picker | `IkasCategory | null` | Single category reference |\n| `CATEGORY_LIST` | Category list picker | `IkasCategoryList` | Multiple category references |\n| `BRAND` | Brand picker | `IkasBrand | null` | Single brand reference |\n| `BRAND_LIST` | Brand list picker | `IkasBrandList` | Multiple brand references |\n| `BLOG` | Blog post picker | `IkasBlog | null` | Single blog post reference |\n| `BLOG_LIST` | Blog post list picker | `IkasBlogList` | Multiple blog post references |\n| `BLOG_CATEGORY` | Blog category picker | `IkasBlogCategory | null` | Single blog category reference |\n| `BLOG_CATEGORY_LIST` | Blog category list picker | `IkasBlogCategoryList` | Multiple blog category references |\n| `TYPE` | Type selector | Depends on typeId | Structured type (padding, margin, size, etc.). Available for both components and sections (sections have a restricted whitelist). |\n| `ENUM` | Dropdown selector | `string` | Enum-based style type (flex-direction, justify-content, align-items, etc.). Uses `enumTypeId`. Available for both components and sections. |\n| `COMPONENT` | Component slot | `any` | A single child component slot. Store owners can place a component in this slot from the editor. Render with `<IkasComponentRenderer>`. Before using, see `get_migration_guide(\"component-composition-decision-guide\")`. |\n| `COMPONENT_LIST` | Component list slot | `any` | A list of child components. Store owners can add multiple components from the editor. Render with `<IkasComponentRenderer>`. Before using, see `get_migration_guide(\"component-composition-decision-guide\")`. |\n\n### COMPONENT & COMPONENT_LIST props (child component slots)\n\nThese prop types enable **slot-based** architectures where store owners can drag child components into your section/component from the editor.\n\n- `COMPONENT` — a single child component slot\n- `COMPONENT_LIST` — a list of child components\n\n**Rendering:** Use the `<IkasComponentRenderer>` wrapper from `@ikas/bp-storefront`:\n```tsx\nimport { IkasComponentRenderer } from \"@ikas/bp-storefront\";\nimport { Props } from \"./types\";\n\nexport function MySection({ title, cardList, ...props }: Props) {\n  return (\n    <section>\n      <h2>{title}</h2>\n      <div className=\"cards\">\n        {/* COMPONENT_LIST — render a list of child components */}\n        <IkasComponentRenderer\n          id=\"card-list\"\n          components={cardList as any[]}\n          parentProps={props}\n        />\n      </div>\n    </section>\n  );\n}\nexport default MySection;\n```\n\n**Key rules:**\n- Always pass `parentProps={props}` so child components can access parent data via dynamic values\n- Cast the prop value: `components={myList as any[]}` for COMPONENT_LIST, `components={[myComp] as any[]}` for COMPONENT\n- `<IkasComponentRenderer>` handles rendering, styling, and reactivity of child components automatically\n\n**Config example (COMPONENT_LIST):**\n```json\n{\n  \"name\": \"cardList\",\n  \"displayName\": \"Card List\",\n  \"type\": \"COMPONENT_LIST\"\n}\n```\n\n**Config example (COMPONENT):**\n```json\n{\n  \"name\": \"headerSlot\",\n  \"displayName\": \"Header Slot\",\n  \"type\": \"COMPONENT\"\n}\n```\n\n### Restricting which components can appear (`filteredComponentIds`)\n\nA COMPONENT or COMPONENT_LIST prop may include a `filteredComponentIds: string[]` field to limit which sibling components can be placed inside it. Each entry must be the **opaque random id** of a component already defined in `ikas.config.json` — e.g. `\"7ojrigep-Eml9n5sN3i\"`.\n\n**Ids are not derivable from component names. Do NOT compose them as `${projectId}-${name}`.** The CLI will reject any unknown id with a structured error listing the valid `{id, name}` pairs.\n\n**Recommended workflow:**\n\n1. Create the child component(s) first. The CLI prints the new id in its JSON response:\n   ```bash\n   npx ikas-component config add-component --name Navbar --type component\n   # → { \"success\": true, \"componentId\": \"7ojrigep-Eml9n5sN3i\", ... }\n   ```\n2. Capture the `componentId` and reuse it in the parent's `filteredComponentIds`:\n   ```bash\n   npx ikas-component config add-component --name Header --type section \\\n     --props '[{\"name\":\"components\",\"type\":\"COMPONENT_LIST\",\"filteredComponentIds\":[\"7ojrigep-Eml9n5sN3i\"]}]'\n   ```\n\nOr create the parent first without `filteredComponentIds`, then attach it once children exist:\n```bash\nnpx ikas-component config add-prop Header components --type COMPONENT_LIST \\\n  --filteredComponentIds '[\"7ojrigep-Eml9n5sN3i\"]'\n```\n\n**Discovering existing ids:** `npx ikas-component config list` returns a JSON document with every component's `{ id, name, type, props… }`. Use that when joining a project mid-flight.\n\n### IMAGE type example:\n```json\n{\n  \"name\": \"heroImage\",\n  \"displayName\": \"Hero Image\",\n  \"type\": \"IMAGE\",\n  \"required\": false\n}\n```\nAccess in component: `getDefaultSrc(props.heroImage)` (import `getDefaultSrc` from `@ikas/bp-storefront`)\n\n### Prop grouping\nProps can be assigned to groups via `groupId` for organized editor sidebar display. See `get_framework_guide(\"prop-groups\")` for details.\n\n### Style Props: TYPE and ENUM\n\nThere are two prop types for style values:\n\n- **TYPE** — Structured types with numeric values and units (padding, margin, border-radius, sizes, etc.). Uses `typeId`.\n- **ENUM** — Enum types rendered as dropdown selectors (flex-direction, justify-content, align-items, etc.). Uses `enumTypeId`.\n\nBoth are available for components and sections. For sections, TYPE props are limited to a whitelist of style types. Use `list-types --component-type section` to see section-allowed types.\n\n### TYPE prop (structured types)\nThe `TYPE` prop lets you use structured storefront types like PaddingStyleType, MarginStyleType, SizeStyleType, etc. Available for both components and sections (sections have a restricted whitelist of style types).\n\n**Workflow:**\n1. Run `npx ikas-component config list-types` to get available types (requires dev server running with editor connected)\n2. Use the `typeId` from the output when adding the prop\n3. For sections: `npx ikas-component config list-types --component-type section` to see only section-allowed types\n\n**Example config:**\n```json\n{\n  \"name\": \"spacing\",\n  \"displayName\": \"Spacing\",\n  \"type\": \"TYPE\",\n  \"typeId\": \"@ikas/bp-storefront-models-PaddingStyleType\"\n}\n```\n\n**Array example** (append `_array` to typeId):\n```json\n{\n  \"name\": \"margins\",\n  \"displayName\": \"Margins\",\n  \"type\": \"TYPE\",\n  \"typeId\": \"@ikas/bp-storefront-models-MarginStyleType_array\"\n}\n```\nThis generates `margins?: MarginStyleType[]` in types.ts.\n\n**CLI command:**\n```bash\nnpx ikas-component config add-prop --component MyComp --name spacing --displayName Spacing --type TYPE --typeId \"@ikas/bp-storefront-models-PaddingStyleType\"\n```\n\n### ENUM prop (enum style types)\nThe `ENUM` prop lets you use enum-based types that render as dropdown selectors. There are two kinds of enum types:\n\n1. **Built-in enums** (prefix `@ikas/`): FlexDirectionStyleType, JustifyContentStyleType, AlignItemsStyleType, etc. Available from `list-types` when editor is connected.\n2. **Custom enums**: Created with `config add-enum`. Works offline, no editor needed.\n\n**IMPORTANT:** `add-prop --type ENUM` validates that the `enumTypeId` references an existing enum. You MUST create custom enums first with `config add-enum` before using them. The command will reject unknown enum IDs.\n\n**Custom enum workflow (recommended for AI-driven generation):**\n```bash\n# Step 1: Create the enum FIRST\nnpx ikas-component config add-enum --name \"AspectRatio\" --options '{\"Square\":\"1/1\",\"Landscape\":\"16/9\",\"Portrait\":\"3/4\"}'\n# Returns: {\"success\":true,\"enumId\":\"aBcDeFgHiJ\",...}\n\n# Step 2: Use the returned enumId in add-prop\nnpx ikas-component config add-prop --component MyComp --name aspectRatio --displayName \"Aspect Ratio\" --type ENUM --enumTypeId aBcDeFgHiJ\n```\n\n**Built-in enum workflow:**\n1. Run `npx ikas-component config list-types` — enum types have `category: \"enum\"` in the output\n2. Use the `enumTypeId` from the output when adding the prop\n\n**Example config (built-in enum):**\n```json\n{\n  \"name\": \"direction\",\n  \"displayName\": \"Direction\",\n  \"type\": \"ENUM\",\n  \"enumTypeId\": \"@ikas/bp-storefront-models-FlexDirectionStyleType\"\n}\n```\nThis generates `direction?: string` in types.ts.\n\n**CLI command (built-in enum):**\n```bash\nnpx ikas-component config add-prop --component MyComp --name direction --displayName Direction --type ENUM --enumTypeId \"@ikas/bp-storefront-models-FlexDirectionStyleType\"\n```\n\n**Note:** `list-types` requires dev server with editor connected. Custom enums (`config add-enum`) work offline.",
       "tags": [
         "props",
         "types",
@@ -155,7 +155,7 @@
     "sections-vs-components": {
       "title": "Sections vs Components",
       "description": "The difference between sections (page-level containers) and components (child elements)",
-      "content": "ikas code components have two types: **sections** and **components**.\n\n## Sections\nSections are page-level, full-width containers that make up the structure of a page. Examples: Header, Hero Banner, Footer, Product Grid, Featured Collection.\n\n- Set `\"type\": \"section\"` in `ikas.config.json`\n- Use a `<section>` root element with full-width styling\n- Name the props interface `Props` in `types.ts`\n- Typically have full-width layout with inner max-width container\n- Styles: `width: 100%; padding: 64px 24px;` with `.inner { max-width: 1200px; margin: 0 auto; }`\n- **MUST include a `backgroundColor` COLOR prop** (default: `#ffffff`). Apply via inline style on the `<section>` element: `style={backgroundColor ? { backgroundColor } : undefined}`\n- Consider adding `textColor` COLOR props for text elements sitting directly on the section background, so they remain readable when the background changes\n\n## Components\nComponents are child elements that are placed inside sections. Examples: Button, Product Card, Badge, Price Display, Image Gallery.\n\n- No `type` field needed in `ikas.config.json` (defaults to `\"component\"`)\n- Use a `<div>` root element\n- Name the props interface `Props` in `types.ts`\n- Sized by their content or parent container\n\n## Config Difference\nThe only config difference is the `type` field on the component definition:\n\n```json\n{\n  \"components\": [\n    {\n      \"id\": \"product-card\",\n      \"name\": \"Product Card\",\n      \"entry\": \"./src/components/ProductCard/index.tsx\",\n      \"styles\": \"./src/components/ProductCard/styles.css\",\n      \"props\": []\n    },\n    {\n      \"id\": \"hero-banner\",\n      \"name\": \"Hero Banner\",\n      \"type\": \"section\",\n      \"entry\": \"./src/components/HeroBanner/index.tsx\",\n      \"styles\": \"./src/components/HeroBanner/styles.css\",\n      \"props\": []\n    }\n  ]\n}\n```\n\n## Required Section Prop: backgroundColor\n\nEvery section MUST include a `backgroundColor` COLOR prop so store owners can customize the section background.\n\n### Config:\n```json\n{ \"name\": \"backgroundColor\", \"displayName\": \"Background Color\", \"type\": \"COLOR\", \"defaultValue\": \"#ffffff\" }\n```\n\n### Usage in index.tsx:\n```tsx\nexport function MySection({ title, backgroundColor = \"#ffffff\" }: Props) {\n  return (\n    <section className=\"my-section\" style={backgroundColor ? { backgroundColor } : undefined}>\n      <div className=\"my-section-inner\">\n        <h1>{title}</h1>\n      </div>\n    </section>\n  );\n}\n```\n\nOptionally, also add `textColor` and/or `headingColor` COLOR props for text elements sitting directly on the section background. This ensures text remains readable when the store owner changes the background color.\n\n## Header & Footer Sections\n\nTo designate a section as the store's header or footer, add `isHeader: true` or `isFooter: true` in `ikas.config.json`. This tells the editor to treat the section as a common header/footer that appears on all pages automatically.\n\n```json\n{\n  \"id\": \"header\",\n  \"name\": \"Header\",\n  \"type\": \"section\",\n  \"isHeader\": true,\n  \"entry\": \"./src/components/Header/index.tsx\",\n  \"styles\": \"./src/components/Header/styles.css\",\n  \"props\": [...]\n}\n```\n\nOnly one component should have `isHeader: true` and one should have `isFooter: true`. These flags only apply to section-type components.\n\n## How to Decide\n- Will it span the full width of the page and sit at the top level? → **Section**\n- Will it be placed inside another container or repeated in a list? → **Component**\n- Is it the store's main header or footer? → **Section** with `isHeader`/`isFooter`",
+      "content": "ikas code components have two types: **sections** and **components**.\n\n## Sections\nSections are page-level, full-width containers that make up the structure of a page. Examples: Header, Hero Banner, Footer, Product Grid, Featured Collection.\n\n- Set `\"type\": \"section\"` in `ikas.config.json`\n- Use a `<section>` root element with full-width styling\n- Name the props interface `Props` in `types.ts`\n- Typically have full-width layout with inner max-width container\n- Styles: `width: 100%; padding: 64px 24px;` with `.inner { max-width: 1200px; margin: 0 auto; }`\n- **MUST include a `backgroundColor` COLOR prop** (default: `#ffffff`). Apply via inline style on the `<section>` element: `style={backgroundColor ? { backgroundColor } : undefined}`\n- Consider adding `textColor` COLOR props for text elements sitting directly on the section background, so they remain readable when the background changes\n\n## Components\nComponents are child elements that are placed inside sections. Examples: Button, Product Card, Badge, Price Display, Image Gallery.\n\n- No `type` field needed in `ikas.config.json` (defaults to `\"component\"`)\n- Use a `<div>` root element\n- Name the props interface `Props` in `types.ts`\n- Sized by their content or parent container\n\n## Config Difference\nThe only config difference is the `type` field on the component definition:\n\n```json\n{\n  \"components\": [\n    {\n      \"id\": \"product-card\",\n      \"name\": \"Product Card\",\n      \"entry\": \"./src/components/ProductCard/index.tsx\",\n      \"styles\": \"./src/components/ProductCard/styles.css\",\n      \"props\": []\n    },\n    {\n      \"id\": \"hero-banner\",\n      \"name\": \"Hero Banner\",\n      \"type\": \"section\",\n      \"entry\": \"./src/components/HeroBanner/index.tsx\",\n      \"styles\": \"./src/components/HeroBanner/styles.css\",\n      \"props\": []\n    }\n  ]\n}\n```\n\n## Required Section Prop: backgroundColor\n\nEvery section MUST include a `backgroundColor` COLOR prop so store owners can customize the section background.\n\n### Config:\n```json\n{ \"name\": \"backgroundColor\", \"displayName\": \"Background Color\", \"type\": \"COLOR\", \"defaultValue\": \"#ffffff\" }\n```\n\n### Usage in index.tsx:\n```tsx\nexport function MySection({ title, backgroundColor = \"#ffffff\" }: Props) {\n  return (\n    <section className=\"my-section\" style={backgroundColor ? { backgroundColor } : undefined}>\n      <div className=\"my-section-inner\">\n        <h1>{title}</h1>\n      </div>\n    </section>\n  );\n}\n```\n\nOptionally, also add `textColor` and/or `headingColor` COLOR props for text elements sitting directly on the section background. This ensures text remains readable when the store owner changes the background color.\n\n## Header & Footer Sections\n\nTo designate a section as the store's header or footer, add `isHeader: true` or `isFooter: true` in `ikas.config.json`. This tells the editor to treat the section as a common header/footer that appears on all pages automatically.\n\n```json\n{\n  \"id\": \"header\",\n  \"name\": \"Header\",\n  \"type\": \"section\",\n  \"isHeader\": true,\n  \"entry\": \"./src/components/Header/index.tsx\",\n  \"styles\": \"./src/components/Header/styles.css\",\n  \"props\": [...]\n}\n```\n\nOnly one component should have `isHeader: true` and one should have `isFooter: true`. These flags only apply to section-type components.\n\n## Container Sections (sections that host children via COMPONENT_LIST)\n\nSome sections are **containers** — they don't render content directly, they host other components in editable slots. Headers, footers, and product-detail sections are the canonical examples.\n\nA container section's config has a `COMPONENT_LIST` (or `COMPONENT`) prop with `filteredComponentIds` restricting which siblings can be placed in the slot:\n\n```json\n{\n  \"name\": \"components\",\n  \"type\": \"COMPONENT_LIST\",\n  \"filteredComponentIds\": [\"<NAVBAR_ID>\", \"<ANNOUNCEMENTS_ID>\"]\n}\n```\n\nBuilding a container section is **always** a 3-step recipe — you cannot do it in one CLI call because the parent's `filteredComponentIds` must reference child ids that don't exist until the children are created:\n\n1. **Create each child component first** with `config add-component --type component`. Capture the `componentId` returned in each JSON response — those are the opaque ids you'll wire into the parent.\n2. **Create the parent section** with `config add-component --type section` (omit `filteredComponentIds` at this point — they're wired in step 3).\n3. **Wire the slot** with `config update-prop --component <Parent> --prop <slotName> --filteredComponentIds '[\"<CHILD_1_ID>\", \"<CHILD_2_ID>\"]'`.\n\nSkipping step 3 leaves the slot unrestricted and the section non-functional. The CLI rejects unknown ids with a structured error listing valid `{id, name}` pairs, so there is no silent failure mode. See `get_framework_guide(\"header-footer-patterns\")` for a complete worked example, or call `get_section_template(\"header-section\")` for an auto-generated recipe.\n\n## How to Decide\n- Will it span the full width of the page and sit at the top level? → **Section**\n- Will it be placed inside another container or repeated in a list? → **Component**\n- Is it the store's main header or footer, or a multi-slot layout? → **Container section** with one or more COMPONENT_LIST props — follow the 3-step recipe above\n- Is it the store's main header or footer? → **Section** with `isHeader`/`isFooter`",
       "tags": [
         "section",
         "component",
@@ -173,7 +173,7 @@
     "common-pitfalls": {
       "title": "Common Pitfalls",
       "description": "Frequent mistakes LLMs and developers make when building ikas code components",
-      "content": "## Common Pitfalls\n\nThese are the most common mistakes when building ikas code components. Avoid them for correct, working code.\n\n### 1. Root Component Should NOT Use observer\n\nThe ikas runtime wraps root component renders in `autorun()`, making them automatically reactive. Wrapping a root export with `observer()` is redundant and misleading.\n\n**Wrong** — observer on root export:\n```tsx\nimport { observer } from \"@ikas/component-utils\";\nimport { cartStore } from \"@ikas/bp-storefront\";\n\nconst CartSection = observer(function CartSection({ title }: Props) {\n  const items = cartStore.cart?.orderLineItems ?? [];\n  return <section>{title}: {items.length} items</section>;\n});\nexport default CartSection;\n```\n\n**Correct** — plain named export:\n```tsx\nimport { cartStore } from \"@ikas/bp-storefront\";\n\nexport function CartSection({ title }: Props) {\n  const items = cartStore.cart?.orderLineItems ?? [];\n  return <section>{title}: {items.length} items</section>;\n}\n\nexport default CartSection;\n```\n\n### 2. Observer Sub-Component Naming\n\nWhen using `observer()` on **sub-components**, use a named function expression — not an arrow function — for proper DevTools display names.\n\n**Wrong** — arrow function loses display name:\n```tsx\nconst CartBadge = observer(() => {\n  return <span>{cartStore.cart?.orderLineItems.length ?? 0}</span>;\n});\n```\n\n**Correct** — named function expression:\n```tsx\nconst CartBadge = observer(function CartBadge() {\n  return <span>{cartStore.cart?.orderLineItems.length ?? 0}</span>;\n});\n```\n\n### 3. Mutation Semantics\n\nMany storefront functions (122+) return `void` and **mutate their arguments in place**. Do NOT try to capture a return value:\n\n```tsx\n// WRONG — selectVariantValue returns void, not a new product\nconst updated = selectVariantValue(product, value);\n\n// CORRECT — mutates product in place, observer re-renders automatically\nselectVariantValue(product, dvv.variantValue);\n```\n\nOther mutation functions: `initLoginForm()`, `setLoginFormEmail()`, `clearFilter()`, `selectFilterValue()`.\n\n### 4. CSS Scoping Limits\n\nOnly **class selectors** in `styles.css` are reliably scoped. Element selectors are NOT scoped:\n\n```css\n/* SAFE — scoped to your component */\n.product-card { padding: 16px; }\n.product-card .title { font-size: 18px; }\n\n/* UNSAFE — NOT reliably scoped, may affect other components */\ndiv { margin: 0; }\nh1 { font-size: 24px; }\n```\n\nAlways use class selectors for all styles.\n\n### 5. Prop Null Handling\n\nProps from the editor can be `undefined` when the store owner hasn't set them. Always use optional chaining:\n\n```tsx\n// WRONG — will crash if product is undefined\n<h1>{props.product.name}</h1>\n\n// CORRECT\n<h1>{props.product?.name}</h1>\n{props.heroImage && <img src={getDefaultSrc(props.heroImage)} />}\n```\n\n### 6. IkasProductImage vs IkasImage\n\n`variant.images` is `IkasProductImage[]`, NOT `IkasImage[]`. You must access the `.image` property to get the `IkasImage` needed by CDN helpers:\n\n```tsx\n// WRONG — productImage is IkasProductImage, not IkasImage\ngetDefaultSrc(productImage);\n\n// CORRECT — access .image to get IkasImage\ngetDefaultSrc(productImage.image);\n\n// Full pattern:\nconst images: IkasImage[] = variant.images\n  .map((pi) => pi.image)\n  .filter((img): img is IkasImage => img != null);\n```\n\n### 7. Type Assertion Pattern\n\nSome storefront functions have type inference gaps. Use `as unknown as` casts when needed — this is a known pattern:\n\n```tsx\nconst inStock = hasProductStock(product) as unknown as boolean;\nconst finalPrice = getProductVariantFormattedFinalPrice(variant) as unknown as string;\nconst canAddToCart = isAddToCartEnabled(product) as unknown as boolean;\n```\n\nThis applies to functions like `hasProductStock`, `hasProductVariantStock`, `isAddToCartEnabled`, `hasProductVariantDiscount`, `getProductVariantDiscountPercentage`, `getProductVariantFormattedFinalPrice`, `getProductVariantFormattedSellPrice`, `getProductVariantFormattedDiscountAmount`, and `getProductVariantFormattedCampaignPrice`.\n\nNote: `getProductVariantMainImage` returns `IkasProductImage | undefined` (NOT `IkasImage`). Access `.image` to get the `IkasImage` for CDN helpers like `getDefaultSrc()`.\n\n### 8. Store Data Null Safety\n\nStore data (`customerStore.customer`, `cartStore.cart`, `baseStore`) is `null` before initialization completes. Always guard access:\n\n```tsx\n// WRONG — crashes if customer is null\n<h1>{customerStore.customer.firstName}</h1>\n\n// CORRECT — null check first\nif (!customerStore.customer) return <div>Loading...</div>;\n<h1>{customerStore.customer.firstName}</h1>\n\n// Also correct — optional chaining\n<h1>{customerStore.customer?.firstName ?? \"Guest\"}</h1>\n```\n\nSame for `cartStore.cart` — always use `cartStore.cart?.orderLineItems ?? []`.\n\n### 9. ProductList/BlogList Data Access\n\n`productList.data` is the correct way to access products in a product list. Similarly, `blogList.data` for blogs. The display names `.products` / `.blogs` are only used by the blueprint editor — they do NOT exist at runtime:\n\n```tsx\n// CORRECT — use .data for both product lists and blog lists\nconst products = productList?.data ?? [];\nconst blogs = blogList?.data ?? [];\n\n// WRONG — .products / .blogs are display names, not actual fields\nconst products = productList?.products ?? [];\nconst blogs = blogList?.blogs ?? [];\n```\n\n### 10. Form Field Access Pattern\n\nForm fields are objects with `.value`, `.label`, `.hasError`, `.message`. Never access the field directly as a primitive:\n\n```tsx\n// WRONG — loginForm.email is a field object, not a string\n<input value={loginForm.email} />\n\n// CORRECT — access .value for the actual value\n<input value={loginForm.email.value} />\n{loginForm.email.hasError && <span>{loginForm.email.message}</span>}\n```\n\n### 11. Optional Chaining for Editor Props\n\nAll props from `ikas.config.json` can be `undefined` in the editor before the store owner sets them. Always use optional chaining and defaults:\n\n```tsx\n// WRONG — will crash in the editor\n<h1>{props.title}</h1>\n<img src={getDefaultSrc(props.image)} />\n{props.links.links.map(...)}\n\n// CORRECT — safe access with defaults\n<h1>{props.title ?? \"Default Title\"}</h1>\n{props.image && <img src={getDefaultSrc(props.image)} />}\n{(props.links?.links ?? []).map(...)}\n```\n\n### 12. Event Handler Typing\n\nPreact uses different event types than React. Use `(e: Event)` not `(e: React.ChangeEvent)`. Access values with casting. Preact uses `onInput` not `onChange` for text inputs:\n\n```tsx\n// WRONG — React patterns don't work in Preact\nonChange={(e: React.ChangeEvent<HTMLInputElement>) => setValue(e.target.value)}\n\n// CORRECT — Preact event handling\nonInput={(e: Event) => setValue((e.target as HTMLInputElement).value)}\n```\n\nFor select elements:\n```tsx\nonChange={(e: Event) => setOption((e.target as HTMLSelectElement).value)}\n```\n\n### 13. Function Parameter Order\n\nMany storefront functions take specific parameter orders. Always verify with `get_function_doc()` before using:\n\n```tsx\n// WRONG — submitLoginForm only takes the form, not the store\nsubmitLoginForm(customerStore, loginForm);\n\n// CORRECT\nsubmitLoginForm(loginForm);\n\n// WRONG — wrong parameter order for addItemToCart\naddItemToCart(product, variant, 1);\n\n// CORRECT — variant first, then product, then quantity\naddItemToCart(variant, product, 1);\n\n// WRONG — selectVariantValue takes product and variantValue\nselectVariantValue(variant, value);\n\n// CORRECT\nselectVariantValue(product, dvv.variantValue);\n```\n\nWhen in doubt, use the `get_function_doc(functionName)` MCP tool to check the exact signature.\n\n### 14. Missing backgroundColor Prop on Sections\n\nEvery section MUST include a `backgroundColor` COLOR prop so store owners can customize the section background. Without it, the section has a hardcoded background that cannot be changed in the editor.\n\n**Wrong** — section with no backgroundColor prop:\n```json\n// ikas.config.json\n{ \"id\": \"my-section\", \"type\": \"section\", \"props\": [\n  { \"name\": \"title\", \"type\": \"TEXT\" }\n]}\n```\n```tsx\nexport function MySection({ title }: Props) {\n  return <section className=\"my-section\"><h1>{title}</h1></section>;\n}\n```\n\n**Correct** — section with backgroundColor prop:\n```json\n// ikas.config.json\n{ \"id\": \"my-section\", \"type\": \"section\", \"props\": [\n  { \"name\": \"title\", \"type\": \"TEXT\" },\n  { \"name\": \"backgroundColor\", \"displayName\": \"Background Color\", \"type\": \"COLOR\", \"defaultValue\": \"#ffffff\" }\n]}\n```\n```tsx\nexport function MySection({ title, backgroundColor = \"#ffffff\" }: Props) {\n  return (\n    <section className=\"my-section\" style={backgroundColor ? { backgroundColor } : undefined}>\n      <h1>{title}</h1>\n    </section>\n  );\n}\n```\n\nOptionally, also consider adding `textColor` COLOR props for text elements sitting directly on the section background, so they remain readable when the store owner changes the background color.\n\n### 15. Forgetting to Group Props for Complex Sections\n\nSections with 5+ props should use prop groups to organize the editor sidebar. Without groups, store owners see a long flat list of unrelated props.\n\n**Better** — organize related props into groups:\n```json\n{\n  \"propGroups\": [\n    { \"id\": \"content\", \"name\": \"Content\" },\n    { \"id\": \"appearance\", \"name\": \"Appearance\" }\n  ],\n  \"props\": [\n    { \"name\": \"heading\", \"groupId\": \"content\", ... },\n    { \"name\": \"bgColor\", \"groupId\": \"appearance\", ... }\n  ]\n}\n```\n\nSee `get_framework_guide(\"prop-groups\")` for full details.\n\n### 16. Hardcoded Static Text in Components\n\nAll user-visible text MUST be TEXT props — never hardcode strings in JSX. Hardcoded text cannot be translated for multilingual storefronts.\n\n**Wrong** — hardcoded strings:\n```tsx\nexport function LoginSection({ backgroundColor }: Props) {\n  return (\n    <section style={backgroundColor ? { backgroundColor } : undefined}>\n      <h1>Sign In</h1>\n      <button>{form.isSubmitting ? \"Signing in...\" : \"Sign In\"}</button>\n      <p>Don't have an account? <a href=\"/register\">Create one</a></p>\n    </section>\n  );\n}\n```\n\n**Correct** — all text as TEXT props with defaultValues:\n```json\n// ikas.config.json\n{ \"props\": [\n  { \"name\": \"title\", \"type\": \"TEXT\", \"defaultValue\": \"Sign In\", \"groupId\": \"texts\" },\n  { \"name\": \"submitButtonText\", \"type\": \"TEXT\", \"defaultValue\": \"Sign In\", \"groupId\": \"texts\" },\n  { \"name\": \"submittingButtonText\", \"type\": \"TEXT\", \"defaultValue\": \"Signing in...\", \"groupId\": \"texts\" },\n  { \"name\": \"noAccountText\", \"type\": \"TEXT\", \"defaultValue\": \"Don't have an account?\", \"groupId\": \"texts\" },\n  { \"name\": \"createAccountLinkText\", \"type\": \"TEXT\", \"defaultValue\": \"Create one\", \"groupId\": \"texts\" }\n],\n\"propGroups\": [{ \"id\": \"texts\", \"name\": \"Texts\" }]}\n```\n```tsx\nexport function LoginSection({ title = \"Sign In\", submitButtonText = \"Sign In\",\n  submittingButtonText = \"Signing in...\", noAccountText = \"Don't have an account?\",\n  createAccountLinkText = \"Create one\", backgroundColor }: Props) {\n  return (\n    <section style={backgroundColor ? { backgroundColor } : undefined}>\n      <h1>{title}</h1>\n      <button>{form.isSubmitting ? submittingButtonText : submitButtonText}</button>\n      <p>{noAccountText} <a href=\"/register\">{createAccountLinkText}</a></p>\n    </section>\n  );\n}\n```\n\nFor button loading states, use two separate TEXT props (e.g., `submitButtonText` + `submittingButtonText`). Group text props under a \"Texts\" propGroup when the component has 5+ props.",
+      "content": "## Common Pitfalls\n\nThese are the most common mistakes when building ikas code components. Avoid them for correct, working code.\n\n### 1. Root Component Should NOT Use observer\n\nThe ikas runtime wraps root component renders in `autorun()`, making them automatically reactive. Wrapping a root export with `observer()` is redundant and misleading.\n\n**Wrong** — observer on root export:\n```tsx\nimport { observer } from \"@ikas/component-utils\";\nimport { cartStore } from \"@ikas/bp-storefront\";\n\nconst CartSection = observer(function CartSection({ title }: Props) {\n  const items = cartStore.cart?.orderLineItems ?? [];\n  return <section>{title}: {items.length} items</section>;\n});\nexport default CartSection;\n```\n\n**Correct** — plain named export:\n```tsx\nimport { cartStore } from \"@ikas/bp-storefront\";\n\nexport function CartSection({ title }: Props) {\n  const items = cartStore.cart?.orderLineItems ?? [];\n  return <section>{title}: {items.length} items</section>;\n}\n\nexport default CartSection;\n```\n\n### 2. Observer Sub-Component Naming\n\nWhen using `observer()` on **sub-components**, use a named function expression — not an arrow function — for proper DevTools display names.\n\n**Wrong** — arrow function loses display name:\n```tsx\nconst CartBadge = observer(() => {\n  return <span>{cartStore.cart?.orderLineItems.length ?? 0}</span>;\n});\n```\n\n**Correct** — named function expression:\n```tsx\nconst CartBadge = observer(function CartBadge() {\n  return <span>{cartStore.cart?.orderLineItems.length ?? 0}</span>;\n});\n```\n\n### 3. Mutation Semantics\n\nMany storefront functions (122+) return `void` and **mutate their arguments in place**. Do NOT try to capture a return value:\n\n```tsx\n// WRONG — selectVariantValue returns void, not a new product\nconst updated = selectVariantValue(product, value);\n\n// CORRECT — mutates product in place, observer re-renders automatically\nselectVariantValue(product, dvv.variantValue);\n```\n\nOther mutation functions: `initLoginForm()`, `setLoginFormEmail()`, `clearFilter()`, `selectFilterValue()`.\n\n### 4. CSS Scoping Limits\n\nOnly **class selectors** in `styles.css` are reliably scoped. Element selectors are NOT scoped:\n\n```css\n/* SAFE — scoped to your component */\n.product-card { padding: 16px; }\n.product-card .title { font-size: 18px; }\n\n/* UNSAFE — NOT reliably scoped, may affect other components */\ndiv { margin: 0; }\nh1 { font-size: 24px; }\n```\n\nAlways use class selectors for all styles.\n\n### 5. Prop Null Handling\n\nProps from the editor can be `undefined` when the store owner hasn't set them. Always use optional chaining:\n\n```tsx\n// WRONG — will crash if product is undefined\n<h1>{props.product.name}</h1>\n\n// CORRECT\n<h1>{props.product?.name}</h1>\n{props.heroImage && <img src={getDefaultSrc(props.heroImage)} />}\n```\n\n### 6. IkasProductImage vs IkasImage\n\n`variant.images` is `IkasProductImage[]`, NOT `IkasImage[]`. You must access the `.image` property to get the `IkasImage` needed by CDN helpers:\n\n```tsx\n// WRONG — productImage is IkasProductImage, not IkasImage\ngetDefaultSrc(productImage);\n\n// CORRECT — access .image to get IkasImage\ngetDefaultSrc(productImage.image);\n\n// Full pattern:\nconst images: IkasImage[] = variant.images\n  .map((pi) => pi.image)\n  .filter((img): img is IkasImage => img != null);\n```\n\n### 7. Type Assertion Pattern\n\nSome storefront functions have type inference gaps. Use `as unknown as` casts when needed — this is a known pattern:\n\n```tsx\nconst inStock = hasProductStock(product) as unknown as boolean;\nconst finalPrice = getProductVariantFormattedFinalPrice(variant) as unknown as string;\nconst canAddToCart = isAddToCartEnabled(product) as unknown as boolean;\n```\n\nThis applies to functions like `hasProductStock`, `hasProductVariantStock`, `isAddToCartEnabled`, `hasProductVariantDiscount`, `getProductVariantDiscountPercentage`, `getProductVariantFormattedFinalPrice`, `getProductVariantFormattedSellPrice`, `getProductVariantFormattedDiscountAmount`, and `getProductVariantFormattedCampaignPrice`.\n\nNote: `getProductVariantMainImage` returns `IkasProductImage | undefined` (NOT `IkasImage`). Access `.image` to get the `IkasImage` for CDN helpers like `getDefaultSrc()`.\n\n### 8. Store Data Null Safety\n\nStore data (`customerStore.customer`, `cartStore.cart`, `baseStore`) is `null` before initialization completes. Always guard access:\n\n```tsx\n// WRONG — crashes if customer is null\n<h1>{customerStore.customer.firstName}</h1>\n\n// CORRECT — null check first\nif (!customerStore.customer) return <div>Loading...</div>;\n<h1>{customerStore.customer.firstName}</h1>\n\n// Also correct — optional chaining\n<h1>{customerStore.customer?.firstName ?? \"Guest\"}</h1>\n```\n\nSame for `cartStore.cart` — always use `cartStore.cart?.orderLineItems ?? []`.\n\n### 9. ProductList/BlogList Data Access\n\n`productList.data` is the correct way to access products in a product list. Similarly, `blogList.data` for blogs. The display names `.products` / `.blogs` are only used by the blueprint editor — they do NOT exist at runtime:\n\n```tsx\n// CORRECT — use .data for both product lists and blog lists\nconst products = productList?.data ?? [];\nconst blogs = blogList?.data ?? [];\n\n// WRONG — .products / .blogs are display names, not actual fields\nconst products = productList?.products ?? [];\nconst blogs = blogList?.blogs ?? [];\n```\n\n### 10. Form Field Access Pattern\n\nForm fields are objects with `.value`, `.label`, `.hasError`, `.message`. Never access the field directly as a primitive:\n\n```tsx\n// WRONG — loginForm.email is a field object, not a string\n<input value={loginForm.email} />\n\n// CORRECT — access .value for the actual value\n<input value={loginForm.email.value} />\n{loginForm.email.hasError && <span>{loginForm.email.message}</span>}\n```\n\n### 11. Optional Chaining for Editor Props\n\nAll props from `ikas.config.json` can be `undefined` in the editor before the store owner sets them. Always use optional chaining and defaults:\n\n```tsx\n// WRONG — will crash in the editor\n<h1>{props.title}</h1>\n<img src={getDefaultSrc(props.image)} />\n{props.links.links.map(...)}\n\n// CORRECT — safe access with defaults\n<h1>{props.title ?? \"Default Title\"}</h1>\n{props.image && <img src={getDefaultSrc(props.image)} />}\n{(props.links?.links ?? []).map(...)}\n```\n\n### 12. Event Handler Typing\n\nPreact uses different event types than React. Use `(e: Event)` not `(e: React.ChangeEvent)`. Access values with casting. Preact uses `onInput` not `onChange` for text inputs:\n\n```tsx\n// WRONG — React patterns don't work in Preact\nonChange={(e: React.ChangeEvent<HTMLInputElement>) => setValue(e.target.value)}\n\n// CORRECT — Preact event handling\nonInput={(e: Event) => setValue((e.target as HTMLInputElement).value)}\n```\n\nFor select elements:\n```tsx\nonChange={(e: Event) => setOption((e.target as HTMLSelectElement).value)}\n```\n\n### 13. Function Parameter Order\n\nMany storefront functions take specific parameter orders. Always verify with `get_function_doc()` before using:\n\n```tsx\n// WRONG — submitLoginForm only takes the form, not the store\nsubmitLoginForm(customerStore, loginForm);\n\n// CORRECT\nsubmitLoginForm(loginForm);\n\n// WRONG — wrong parameter order for addItemToCart\naddItemToCart(product, variant, 1);\n\n// CORRECT — variant first, then product, then quantity\naddItemToCart(variant, product, 1);\n\n// WRONG — selectVariantValue takes product and variantValue\nselectVariantValue(variant, value);\n\n// CORRECT\nselectVariantValue(product, dvv.variantValue);\n```\n\nWhen in doubt, use the `get_function_doc(functionName)` MCP tool to check the exact signature.\n\n### 14. Missing backgroundColor Prop on Sections\n\nEvery section MUST include a `backgroundColor` COLOR prop so store owners can customize the section background. Without it, the section has a hardcoded background that cannot be changed in the editor.\n\n**Wrong** — section with no backgroundColor prop:\n```json\n// ikas.config.json\n{ \"id\": \"my-section\", \"type\": \"section\", \"props\": [\n  { \"name\": \"title\", \"type\": \"TEXT\" }\n]}\n```\n```tsx\nexport function MySection({ title }: Props) {\n  return <section className=\"my-section\"><h1>{title}</h1></section>;\n}\n```\n\n**Correct** — section with backgroundColor prop:\n```json\n// ikas.config.json\n{ \"id\": \"my-section\", \"type\": \"section\", \"props\": [\n  { \"name\": \"title\", \"type\": \"TEXT\" },\n  { \"name\": \"backgroundColor\", \"displayName\": \"Background Color\", \"type\": \"COLOR\", \"defaultValue\": \"#ffffff\" }\n]}\n```\n```tsx\nexport function MySection({ title, backgroundColor = \"#ffffff\" }: Props) {\n  return (\n    <section className=\"my-section\" style={backgroundColor ? { backgroundColor } : undefined}>\n      <h1>{title}</h1>\n    </section>\n  );\n}\n```\n\nOptionally, also consider adding `textColor` COLOR props for text elements sitting directly on the section background, so they remain readable when the store owner changes the background color.\n\n### 15. Forgetting to Group Props for Complex Sections\n\nSections with 5+ props should use prop groups to organize the editor sidebar. Without groups, store owners see a long flat list of unrelated props.\n\n**Better** — organize related props into groups:\n```json\n{\n  \"propGroups\": [\n    { \"id\": \"content\", \"name\": \"Content\" },\n    { \"id\": \"appearance\", \"name\": \"Appearance\" }\n  ],\n  \"props\": [\n    { \"name\": \"heading\", \"groupId\": \"content\", ... },\n    { \"name\": \"bgColor\", \"groupId\": \"appearance\", ... }\n  ]\n}\n```\n\nSee `get_framework_guide(\"prop-groups\")` for full details.\n\n### 16. Hardcoded Static Text in Components\n\nAll user-visible text MUST be TEXT props — never hardcode strings in JSX. Hardcoded text cannot be translated for multilingual storefronts.\n\n**Wrong** — hardcoded strings:\n```tsx\nexport function LoginSection({ backgroundColor }: Props) {\n  return (\n    <section style={backgroundColor ? { backgroundColor } : undefined}>\n      <h1>Sign In</h1>\n      <button>{form.isSubmitting ? \"Signing in...\" : \"Sign In\"}</button>\n      <p>Don't have an account? <a href=\"/register\">Create one</a></p>\n    </section>\n  );\n}\n```\n\n**Correct** — all text as TEXT props with defaultValues:\n```json\n// ikas.config.json\n{ \"props\": [\n  { \"name\": \"title\", \"type\": \"TEXT\", \"defaultValue\": \"Sign In\", \"groupId\": \"texts\" },\n  { \"name\": \"submitButtonText\", \"type\": \"TEXT\", \"defaultValue\": \"Sign In\", \"groupId\": \"texts\" },\n  { \"name\": \"submittingButtonText\", \"type\": \"TEXT\", \"defaultValue\": \"Signing in...\", \"groupId\": \"texts\" },\n  { \"name\": \"noAccountText\", \"type\": \"TEXT\", \"defaultValue\": \"Don't have an account?\", \"groupId\": \"texts\" },\n  { \"name\": \"createAccountLinkText\", \"type\": \"TEXT\", \"defaultValue\": \"Create one\", \"groupId\": \"texts\" }\n],\n\"propGroups\": [{ \"id\": \"texts\", \"name\": \"Texts\" }]}\n```\n```tsx\nexport function LoginSection({ title = \"Sign In\", submitButtonText = \"Sign In\",\n  submittingButtonText = \"Signing in...\", noAccountText = \"Don't have an account?\",\n  createAccountLinkText = \"Create one\", backgroundColor }: Props) {\n  return (\n    <section style={backgroundColor ? { backgroundColor } : undefined}>\n      <h1>{title}</h1>\n      <button>{form.isSubmitting ? submittingButtonText : submitButtonText}</button>\n      <p>{noAccountText} <a href=\"/register\">{createAccountLinkText}</a></p>\n    </section>\n  );\n}\n```\n\nFor button loading states, use two separate TEXT props (e.g., `submitButtonText` + `submittingButtonText`). Group text props under a \"Texts\" propGroup when the component has 5+ props.\n\n### 17. IkasOrderLineItemOption.values is an Array, Not a Scalar\n\n`IkasOrderLineItemOption` (the per-item options on cart/order line items) has a `.values` field that is an **array** of `IkasOrderLineItemOptionValue`, NOT a scalar `.value`. Each value in the array has its own `.name` / `.value` / `.formattedPrice`.\n\n```tsx\n// WRONG — there is no .value on IkasOrderLineItemOption\n<span>{option.value}</span>\n\n// CORRECT — .values is an array; map over it\n{option.values.map((v) => (\n  <span key={v.name}>{v.name}: {v.value}</span>\n))}\n```\n\nThis is the most common confusion when rendering order summary lines or cart line item options. See `get_migration_guide(\"prop-runtime-shapes\")` for the broader catalog of order-shape gotchas.\n\n### 18. IkasOrderAdjustment Has No .formattedAmount — Use the Helper\n\n`IkasOrderAdjustment` does not expose a `.formattedAmount` property directly. Call the helper `getOrderAdjustmentFormattedAmount(adjustment)` from `@ikas/bp-storefront` — it returns the formatted currency string with the correct sign (negated for decrements).\n\n```tsx\nimport { getOrderAdjustmentFormattedAmount } from \"@ikas/bp-storefront\";\n\n// WRONG — .formattedAmount does not exist\n<td>{adjustment.formattedAmount}</td>\n\n// CORRECT\n<td>{getOrderAdjustmentFormattedAmount(adjustment)}</td>\n```\n\nSee `get_function_doc(\"getOrderAdjustmentFormattedAmount\")` for the exact signature.\n\n### 19. Old-System Property Patterns That Don't Exist in the New System\n\nSeveral `@ikas/storefront` properties look like they should still work but don't exist on the corresponding `@ikas/bp-storefront` types. Use the helper function instead. **If TypeScript reports TS2339 (\"Property X does not exist on type Y\") on a `.selectedVariant`, `.mainImage`, `.href`, or `.checkoutUrl` access, you're hitting one of these.**\n\n| Old pattern | New replacement |\n|---|---|\n| `product.selectedVariant` | `getSelectedProductVariant(product)` → `IkasProductVariant \\| undefined` |\n| `product.href` | `getProductHref(product)` (one of several `get*Href` helpers — see `navigation-patterns`) |\n| `variant.mainImage` | `getProductVariantMainImage(variant)` → `IkasProductImage`, then access `.image` for the `IkasImage` |\n| `cartStore.checkoutUrl` | `getCheckoutUrlFromCartStore(cartStore)` (handles auth-state branching internally) |\n\nThe variant-to-image chain is 4 hops (each carries metadata the next doesn't). See `get_framework_guide(\"image-handling\")` for the canonical recipe.",
       "tags": [
         "pitfalls",
         "gotchas",
@@ -313,7 +313,7 @@
     "header-footer-patterns": {
       "title": "Header & Footer Patterns (Serel Reference)",
       "description": "IkasComponentRenderer-based Header with Navbar/Announcements/CookieBar children, Footer with SocialMediaIcon children, Toast system, isHeader/isFooter flags",
-      "content": "## Header & Footer Patterns (Serel Reference)\n\nIn the serel theme, the Header and Footer are sections that use `IkasComponentRenderer` to render child components. This is the recommended production pattern.\n\n### Header Architecture\n\nThe serel Header section declares a `COMPONENT_LIST` prop with `filteredComponentIds` restricting it to three child components: **Navbar**, **Announcements**, and **CookieBar**.\n\n```tsx\nimport { IkasComponentRenderer } from \"@ikas/bp-storefront\";\nimport { Props } from \"./types\";\n\nexport function Header({ components, backgroundColor, ...props }: Props) {\n  return (\n    <header className=\"header\" style={backgroundColor ? { backgroundColor } : undefined}>\n      <IkasComponentRenderer id=\"header-components\" components={components} parentProps={props} />\n      <ToastContainer />\n    </header>\n  );\n}\nexport default Header;\n```\n\nConfig setup with `isHeader: true` and `filteredComponentIds`:\n```json\n{\n  \"id\": \"nb34u3yu-header\",\n  \"name\": \"Header\",\n  \"type\": \"section\",\n  \"isHeader\": true,\n  \"props\": [\n    {\n      \"name\": \"components\",\n      \"type\": \"COMPONENT_LIST\",\n      \"filteredComponentIds\": [\"nb34u3yu-navbar\", \"nb34u3yu-announcements\", \"nb34u3yu-cookie-bar\"]\n    }\n  ]\n}\n```\n\nThe `isHeader: true` flag ensures this section appears on every page automatically.\n\n### Toast Notification System\n\nThe serel Header hosts a `ToastContainer` component. The `useToast` hook provides a global notification system:\n\n```tsx\nimport { useToast } from \"../../hooks/useToast\";\n\n// In any component:\nconst { showToast } = useToast();\nshowToast({ message: \"Added to cart!\", type: \"success\" });\n```\n\nThe ToastContainer renders as a portal to ensure toasts appear above all content. Toasts stack vertically and auto-dismiss after a timeout.\n\n### Navbar Child Component\n\nThe Navbar child component handles: logo display, navigation links (`LIST_OF_LINK`), cart badge (reads `cartStore`), account icon (reads `customerStore`), search functionality, and a mobile hamburger menu. It also has its own `COMPONENT_LIST` slot for product search results using CardProductName/CardProductVariants/CardProductPrice with `privateVarMap` for the product variable.\n\n### Announcements Child Component\n\nThe Announcements child component uses `IkasThemeSlider` for a rotating announcement bar. It has its own child component slot for individual Announcement items.\n\n### CookieBar Child Component\n\nThe CookieBar manages cookie consent with accept/decline actions and persists the choice to localStorage.\n\n### Footer Architecture\n\nThe serel Footer section uses `IkasComponentRenderer` with a `COMPONENT_LIST` filtered to **SocialMediaIcon** children:\n\n```tsx\nimport { IkasComponentRenderer } from \"@ikas/bp-storefront\";\nimport { Props } from \"./types\";\n\nexport function Footer({ components, backgroundColor, ...props }: Props) {\n  return (\n    <footer className=\"footer\" style={backgroundColor ? { backgroundColor } : undefined}>\n      <div className=\"footer-inner\">\n        {/* Logo, link columns, contact info */}\n        <div className=\"footer-social\">\n          <IkasComponentRenderer id=\"footer-components\" components={components} parentProps={props} />\n        </div>\n        {/* Copyright */}\n      </div>\n    </footer>\n  );\n}\nexport default Footer;\n```\n\nConfig with `isFooter: true`:\n```json\n{\n  \"id\": \"nb34u3yu-footer\",\n  \"name\": \"Footer\",\n  \"type\": \"section\",\n  \"isFooter\": true,\n  \"props\": [\n    {\n      \"name\": \"components\",\n      \"type\": \"COMPONENT_LIST\",\n      \"filteredComponentIds\": [\"nb34u3yu-social-media-icon\"]\n    }\n  ]\n}\n```\n\n### Key Patterns\n\n- Headers and footers use `IkasComponentRenderer` with `filteredComponentIds` for controlled child composition\n- `isHeader: true` / `isFooter: true` flags in config make them appear on all pages\n- Root exports are automatically reactive (cartStore/customerStore tracked by autorun)\n- Toast system lives in the Header for global accessibility\n- `parentProps` passes section data to child components\n- The Navbar child component itself nests additional child components via its own COMPONENT_LIST",
+      "content": "## How to build a container section (Header/Footer pattern)\n\nContainer sections are NOT self-contained. The pattern is **always** 3 steps:\n\n1. **Create each child component first.** Capture the `componentId` from each CLI response:\n   ```bash\n   npx ikas-component config add-component --name Navbar --type component --props '[...]'\n   # → { \"success\": true, \"componentId\": \"7ojrigep-Eml9n5sN3i\", ... }\n   npx ikas-component config add-component --name Announcements --type component --props '[...]'\n   npx ikas-component config add-component --name CookieBar --type component --props '[...]'\n   ```\n\n2. **Create the parent section** (without `filteredComponentIds` — those reference ids that don't exist yet):\n   ```bash\n   npx ikas-component config add-component --name Header --type section --isHeader \\\n     --props '[{\"name\":\"components\",\"type\":\"COMPONENT_LIST\"},{\"name\":\"backgroundColor\",\"type\":\"COLOR\"}]'\n   ```\n\n3. **Wire the parent's COMPONENT_LIST slot** to the captured child ids:\n   ```bash\n   npx ikas-component config update-prop --component Header --prop components \\\n     --filteredComponentIds '[\"7ojrigep-Eml9n5sN3i\", \"<ANNOUNCEMENTS_ID>\", \"<COOKIEBAR_ID>\"]'\n   ```\n\nIf you skip Step 3 the slot is empty and the editor will let the store owner drag in ANY component — usually not what you want. Component ids are opaque random strings; you cannot guess or derive them from names. Use `config list` to look up existing ids at any time.\n\n---\n\n## Header & Footer Patterns (Serel Reference)\n\nIn the serel theme, the Header and Footer are sections that use `IkasComponentRenderer` to render child components. This is the recommended production pattern.\n\n### Header Architecture\n\nThe serel Header section declares a `COMPONENT_LIST` prop with `filteredComponentIds` restricting it to three child components: **Navbar**, **Announcements**, and **CookieBar**.\n\n```tsx\nimport { IkasComponentRenderer } from \"@ikas/bp-storefront\";\nimport { Props } from \"./types\";\n\nexport function Header({ components, backgroundColor, ...props }: Props) {\n  return (\n    <header className=\"header\" style={backgroundColor ? { backgroundColor } : undefined}>\n      <IkasComponentRenderer id=\"header-components\" components={components} parentProps={props} />\n      <ToastContainer />\n    </header>\n  );\n}\nexport default Header;\n```\n\nConfig setup with `isHeader: true` and `filteredComponentIds`:\n```json\n{\n  \"id\": \"7ojrigep-IBBg5nI1PC\",\n  \"name\": \"Header\",\n  \"type\": \"section\",\n  \"isHeader\": true,\n  \"props\": [\n    {\n      \"name\": \"components\",\n      \"type\": \"COMPONENT_LIST\",\n      \"filteredComponentIds\": [\"<NAVBAR_ID>\", \"<ANNOUNCEMENTS_ID>\", \"<COOKIEBAR_ID>\"]\n    }\n  ]\n}\n```\n\nThe `isHeader: true` flag ensures this section appears on every page automatically.\n\n### Toast Notification System\n\nThe serel Header hosts a `ToastContainer` component. The `useToast` hook provides a global notification system:\n\n```tsx\nimport { useToast } from \"../../hooks/useToast\";\n\n// In any component:\nconst { showToast } = useToast();\nshowToast({ message: \"Added to cart!\", type: \"success\" });\n```\n\nThe ToastContainer renders as a portal to ensure toasts appear above all content. Toasts stack vertically and auto-dismiss after a timeout.\n\n### Navbar Child Component\n\nThe Navbar child component handles: logo display, navigation links (`LIST_OF_LINK`), cart badge (reads `cartStore`), account icon (reads `customerStore`), search functionality, and a mobile hamburger menu. It also has its own `COMPONENT_LIST` slot for product search results using CardProductName/CardProductVariants/CardProductPrice with `privateVarMap` for the product variable.\n\n### Announcements Child Component\n\nThe Announcements child component uses `IkasThemeSlider` for a rotating announcement bar. It has its own child component slot for individual Announcement items.\n\n### CookieBar Child Component\n\nThe CookieBar manages cookie consent with accept/decline actions and persists the choice to localStorage.\n\n### Footer Architecture\n\nThe serel Footer section uses `IkasComponentRenderer` with a `COMPONENT_LIST` filtered to **SocialMediaIcon** children:\n\n```tsx\nimport { IkasComponentRenderer } from \"@ikas/bp-storefront\";\nimport { Props } from \"./types\";\n\nexport function Footer({ components, backgroundColor, ...props }: Props) {\n  return (\n    <footer className=\"footer\" style={backgroundColor ? { backgroundColor } : undefined}>\n      <div className=\"footer-inner\">\n        {/* Logo, link columns, contact info */}\n        <div className=\"footer-social\">\n          <IkasComponentRenderer id=\"footer-components\" components={components} parentProps={props} />\n        </div>\n        {/* Copyright */}\n      </div>\n    </footer>\n  );\n}\nexport default Footer;\n```\n\nConfig with `isFooter: true`:\n```json\n{\n  \"id\": \"7ojrigep-fTZb2qP9aV\",\n  \"name\": \"Footer\",\n  \"type\": \"section\",\n  \"isFooter\": true,\n  \"props\": [\n    {\n      \"name\": \"components\",\n      \"type\": \"COMPONENT_LIST\",\n      \"filteredComponentIds\": [\"<SOCIALMEDIAICON_ID>\"]\n    }\n  ]\n}\n```\n\n### Key Patterns\n\n- Headers and footers use `IkasComponentRenderer` with `filteredComponentIds` for controlled child composition\n- `isHeader: true` / `isFooter: true` flags in config make them appear on all pages\n- Root exports are automatically reactive (cartStore/customerStore tracked by autorun)\n- Toast system lives in the Header for global accessibility\n- `parentProps` passes section data to child components\n- The Navbar child component itself nests additional child components via its own COMPONENT_LIST\n\n### Mega-Menu / MenuItem (When Per-Link Items Are Rich)\n\nIf the header needs items with metadata beyond `href + label` (image, badge, column count, etc.), `LIST_OF_LINK` cannot carry it. Build a `MenuItem` child and wire it into a `COMPONENT_LIST` slot exactly like Navbar/Announcements/CookieBar above. For the full pick-the-right-prop-type tree (and when `LIST_OF_LINK` IS sufficient), see `get_migration_guide(\"link-prop-decision-guide\")` and `get_migration_guide(\"component-composition-decision-guide\")`.\n",
       "tags": [
         "header",
         "footer",
@@ -378,7 +378,7 @@
     "navigation-patterns": {
       "title": "Navigation & Routing Patterns",
       "description": "Router.navigate, page navigation, href getters, breadcrumbs, and query parameters",
-      "content": "## Navigation & Routing Patterns\n\nikas provides a `Router` utility and various href getter functions for navigation.\n\n### Basic Navigation\n\n```tsx\nimport { Router } from \"@ikas/bp-storefront\";\n\n// Navigate to a URL\nRouter.navigate(\"/products\");\n\n// Navigate with options\nRouter.navigate(\"/products\", true); // shallow navigation (no full page reload)\nRouter.navigate(\"/products\", false, true); // open in new tab\n// Signature: Router.navigate(path: string, shallow?: boolean, openInNewTab?: boolean)\n\n// Navigate to a named page\nRouter.navigateToPage(\"LOGIN\");\nRouter.navigateToPage(\"REGISTER\");\nRouter.navigateToPage(\"FORGOT_PASSWORD\");\nRouter.navigateToPage(\"ACCOUNT\");\nRouter.navigateToPage(\"CART\");\nRouter.navigateToPage(\"CHECKOUT\");\n\n// Navigate with options\nRouter.navigateToPage(\"CATEGORY\", {\n  queryParams: { sort: \"price_asc\" },\n  shallow: false,\n  newTab: false,\n});\n\n// Go back\nRouter.goBack();\n```\n\n### Page Type Constants\n\nAvailable page types for `navigateToPage()`:\n- `INDEX` — Home page\n- `CATEGORY` — Category listing\n- `PRODUCT_DETAIL` — Product detail\n- `BLOG` — Blog listing\n- `BLOG` — Blog post detail\n- `CART` — Shopping cart\n- `CHECKOUT` — Checkout flow\n- `LOGIN` — Login page\n- `REGISTER` — Registration page\n- `FORGOT_PASSWORD` — Password recovery\n- `ACCOUNT` — Customer account\n- `SEARCH` — Search results\n- `CUSTOM` — Custom pages\n\n### Href Getter Functions\n\nThese return URL strings for use in `<a href>` tags:\n\n```tsx\nimport {\n  getSelectedProductVariantHref,\n  getIkasCategoryHref,\n  getIkasOrderHref,\n  getIkasBlogHref,\n  getIkasBrandHref,\n} from \"@ikas/bp-storefront\";\n\n// Product link\n<a href={getSelectedProductVariantHref(product)}>{product.name}</a>\n\n// Category link\n<a href={getIkasCategoryHref(category)}>{category.name}</a>\n\n// Order link\n<a href={getIkasOrderHref(order)}>Order #{order.orderNumber}</a>\n\n// Blog link\n<a href={getIkasBlogHref(blog)}>{blog.title}</a>\n\n// Brand link\n<a href={getIkasBrandHref(brand)}>{brand.name}</a>\n```\n\n### Breadcrumbs\n\n```tsx\nimport {\n  getCategoryPath,\n  getProductCategoryPath,\n  getIkasCategoryHref,\n} from \"@ikas/bp-storefront\";\n\n// For category pages\nconst categoryPath = getCategoryPath(category);\n\n// For product pages\nconst productPath = getProductCategoryPath(product);\n\n<nav className=\"breadcrumbs\">\n  <a href=\"/\">Home</a>\n  {categoryPath?.map((cat, i) => (\n    <span key={cat.id}>\n      <span className=\"separator\">/</span>\n      <a href={getIkasCategoryHref(cat)}>{cat.name}</a>\n    </span>\n  ))}\n</nav>\n```\n\n### Using Links vs Navigation\n\n- Use `<a href={getXxxHref(...)}>` for standard links (SEO-friendly, right-click works)\n- Use `Router.navigate()` for programmatic navigation after form submission or actions\n- Use `Router.navigateToPage()` for navigating to known page types\n- Use `Router.goBack()` for back buttons",
+      "content": "## Navigation & Routing Patterns\n\nikas provides a `Router` utility and various href getter functions for navigation.\n\n### Basic Navigation\n\n```tsx\nimport { Router } from \"@ikas/bp-storefront\";\n\n// Navigate to a URL\nRouter.navigate(\"/products\");\n\n// Navigate with options\nRouter.navigate(\"/products\", true); // shallow navigation (no full page reload)\nRouter.navigate(\"/products\", false, true); // open in new tab\n// Signature: Router.navigate(path: string, shallow?: boolean, openInNewTab?: boolean)\n\n// Navigate to a named page\nRouter.navigateToPage(\"LOGIN\");\nRouter.navigateToPage(\"REGISTER\");\nRouter.navigateToPage(\"FORGOT_PASSWORD\");\nRouter.navigateToPage(\"ACCOUNT\");\nRouter.navigateToPage(\"CART\");\nRouter.navigateToPage(\"CHECKOUT\");\n\n// Navigate with options\nRouter.navigateToPage(\"CATEGORY\", {\n  queryParams: { sort: \"price_asc\" },\n  shallow: false,\n  newTab: false,\n});\n\n// Go back\nRouter.goBack();\n```\n\n### Page Type Constants\n\nAvailable page types for `navigateToPage()`:\n- `INDEX` — Home page\n- `CATEGORY` — Category listing\n- `PRODUCT_DETAIL` — Product detail\n- `BLOG` — Blog listing\n- `BLOG` — Blog post detail\n- `CART` — Shopping cart\n- `CHECKOUT` — Checkout flow\n- `LOGIN` — Login page\n- `REGISTER` — Registration page\n- `FORGOT_PASSWORD` — Password recovery\n- `ACCOUNT` — Customer account\n- `SEARCH` — Search results\n- `CUSTOM` — Custom pages\n\n### Href Getter Functions\n\nThese return URL strings for use in `<a href>` tags:\n\n```tsx\nimport {\n  getSelectedProductVariantHref,\n  getIkasCategoryHref,\n  getIkasOrderHref,\n  getIkasBlogHref,\n  getIkasBrandHref,\n} from \"@ikas/bp-storefront\";\n\n// Product link\n<a href={getSelectedProductVariantHref(product)}>{product.name}</a>\n\n// Category link\n<a href={getIkasCategoryHref(category)}>{category.name}</a>\n\n// Order link\n<a href={getIkasOrderHref(order)}>Order #{order.orderNumber}</a>\n\n// Blog link\n<a href={getIkasBlogHref(blog)}>{blog.title}</a>\n\n// Brand link\n<a href={getIkasBrandHref(brand)}>{brand.name}</a>\n```\n\n### Breadcrumbs\n\n```tsx\nimport {\n  getCategoryPath,\n  getProductCategoryPath,\n  getIkasCategoryHref,\n} from \"@ikas/bp-storefront\";\n\n// For category pages\nconst categoryPath = getCategoryPath(category);\n\n// For product pages\nconst productPath = getProductCategoryPath(product);\n\n<nav className=\"breadcrumbs\">\n  <a href=\"/\">Home</a>\n  {categoryPath?.map((cat, i) => (\n    <span key={cat.id}>\n      <span className=\"separator\">/</span>\n      <a href={getIkasCategoryHref(cat)}>{cat.name}</a>\n    </span>\n  ))}\n</nav>\n```\n\n### Using Links vs Navigation\n\n- Use `<a href={getXxxHref(...)}>` for standard links (SEO-friendly, right-click works)\n- Use `Router.navigate()` for programmatic navigation after form submission or actions\n- Use `Router.navigateToPage()` for navigating to known page types\n- Use `Router.goBack()` for back buttons\n\n### Rich Navigation Items (When LIST_OF_LINK Is Insufficient)\n\n`LIST_OF_LINK` gives you `IkasNavigationLinkList` → an array of `IkasNavigationLink` items with `{ href, label, subLinks, openInNewTab, itemId, type }`. There is **no slot for an image, color, icon, column count, or any other custom field per link**.\n\nIf the navigation needs richer per-item data — a mega-menu with thumbnails, colored category chips, multi-column submenus, badges, custom icons — `LIST_OF_LINK` is the wrong tool. Build a dedicated component instead:\n\n```bash\nnpx ikas-component config add-component --name \"MenuItem\" --type component \\\n  --props '[{\"name\":\"link\",\"type\":\"LINK\"},{\"name\":\"image\",\"type\":\"IMAGE\"},{\"name\":\"title\",\"type\":\"TEXT\"}]'\n```\n\nThen wire the parent header/navbar with a `COMPONENT_LIST` prop and `filteredComponentIds: [\"<MenuItem id>\"]`. Each menu item becomes a self-contained component instance with its own link, image, and title.\n\nSee `get_framework_guide(\"header-footer-patterns\")` for the COMPONENT_LIST recipe and `get_migration_guide(\"custom-data-conversion\")` for the broader enum-vs-component decision framework (the mega-menu case is one of the worked examples).\n",
       "tags": [
         "navigation",
         "router",
@@ -528,6 +528,23 @@
         "offline",
         "CLI"
       ]
+    },
+    "image-handling": {
+      "title": "Image Handling",
+      "description": "How to render images from IkasImage, IkasProduct variants, and IkasProductImage wrappers. Covers the canonical variant-to-image chain, all-variant-images mapping, non-product images, background images, and responsive srcsets.",
+      "content": "## Image Handling\n\nThe canonical recipe for rendering an image. The product-variant case is 4 hops because each step carries metadata the next doesn't (variant selection → that variant's image set → metadata wrapper → CDN-ready image):\n\n```tsx\nimport {\n  getSelectedProductVariant,\n  getProductVariantMainImage,\n  getDefaultSrc,\n  getSrc,\n  createMediaSrcset,\n  IkasImage,\n} from \"@ikas/bp-storefront\";\n\nconst variant = getSelectedProductVariant(product);                    // IkasProductVariant | undefined\nconst productImage = variant && getProductVariantMainImage(variant);   // IkasProductImage | undefined\nconst image = productImage?.image;                                     // IkasImage | undefined — what CDN helpers need\n\nif (image) {\n  return (\n    <>\n      <img src={getDefaultSrc(image)} alt={product.name} />            {/* default size */}\n      <img src={getSrc(image, { width: 400 })} alt=\"\" />               {/* explicit width */}\n      <img srcSet={createMediaSrcset(image)} alt=\"\" />                 {/* responsive srcset */}\n    </>\n  );\n}\n```\n\n## All Variant Images (gallery)\n\nMap over `variant.images` and unwrap each `.image`. `IkasProductImage` carries metadata like `order` and `isMain`; the actual `IkasImage` (what the CDN helpers need) is the `.image` property on each.\n\n```tsx\nconst images: IkasImage[] = (variant?.images ?? [])\n  .map((pi) => pi.image)\n  .filter((img): img is IkasImage => img != null);\n```\n\n## Non-Product Images (logo, banner, IMAGE prop)\n\nThese skip the variant hop — they're already `IkasImage`:\n\n```tsx\n{props.logo && <img src={getDefaultSrc(props.logo)} alt=\"\" />}\n```\n\n## Background Images\n\n```tsx\n<div style={{ backgroundImage: image ? `url(${getDefaultSrc(image)})` : \"none\" }} />\n```\n\n## See Also\n\n- `get_framework_guide(\"common-pitfalls\")` §19 — full property-rename catalog (`selectedVariant`, `mainImage`, `href`, `checkoutUrl`)\n- `get_section_template(\"image-handling\")` — full Product Detail section with gallery + zoom + srcset\n- `get_function_doc(\"getDefaultSrc\")` / `get_function_doc(\"getSrc\")` / `get_function_doc(\"createMediaSrcset\")` — exact signatures\n- `get_type_definition(\"IkasImage\")` / `get_type_definition(\"IkasProductImage\")` — exact shapes",
+      "tags": [
+        "image",
+        "rendering",
+        "getDefaultSrc",
+        "getSrc",
+        "createMediaSrcset",
+        "IkasImage",
+        "IkasProductImage",
+        "variant",
+        "srcset",
+        "gallery"
+      ]
     }
   }
 }

package/data/migration-examples/complex-header-migration/_meta.json

@@ -0,0 +1,4 @@
+{
+  "title": "Complex Header Migration (Navbar → HeaderSection)",
+  "description": "Converts a complex Navbar component with CUSTOM props (menu links, cookie, contact), SLIDER props, Swiper usage, and Headless UI into a HeaderSection with COMPONENT_LIST children."
+}

package/data/migration-examples/complex-header-migration/after-config-snippet.json

@@ -0,0 +1,55 @@
+{
+  "components": [
+    {
+      "id": "my-theme-header",
+      "name": "HeaderSection",
+      "type": "section",
+      "isHeader": true,
+      "entry": "./src/components/HeaderSection/index.tsx",
+      "styles": "./src/components/HeaderSection/styles.css",
+      "props": [
+        { "name": "logo", "displayName": "Logo", "type": "IMAGE", "required": true },
+        { "name": "logoWidth", "displayName": "Logo Width (px)", "type": "NUMBER", "required": false, "defaultValue": 120 },
+        { "name": "mobileLogoWidth", "displayName": "Mobile Logo Width (px)", "type": "NUMBER", "required": false, "defaultValue": 80 },
+        { "name": "menuLinks", "displayName": "Menu Links", "type": "COMPONENT_LIST", "required": false, "filteredComponentIds": ["my-theme-menu-link"] },
+        { "name": "rightIcons", "displayName": "Right Icons", "type": "COMPONENT_LIST", "required": false, "filteredComponentIds": ["my-theme-icon-link"] },
+        { "name": "announcement", "displayName": "Announcement", "type": "TEXT", "required": false },
+        { "name": "announcementLink", "displayName": "Announcement Link", "type": "LINK", "required": false },
+        { "name": "announcementBg", "displayName": "Announcement Background", "type": "COLOR", "required": false },
+        { "name": "searchPlaceholder", "displayName": "Search Placeholder", "type": "TEXT", "required": false, "defaultValue": "Search..." },
+        { "name": "navBackground", "displayName": "Nav Background", "type": "COLOR", "required": false },
+        { "name": "stickyNav", "displayName": "Sticky Navigation", "type": "BOOLEAN", "required": false, "defaultValue": true },
+        { "name": "searchProducts", "displayName": "Search Popular Products", "type": "PRODUCT_LIST", "required": false }
+      ],
+      "propGroups": [
+        { "id": "appearance", "name": "Appearance" },
+        { "id": "search", "name": "Search" }
+      ]
+    },
+    {
+      "id": "my-theme-menu-link",
+      "name": "MenuLink",
+      "type": "component",
+      "entry": "./src/components/MenuLink/index.tsx",
+      "styles": "./src/components/MenuLink/styles.css",
+      "props": [
+        { "name": "link", "displayName": "Link", "type": "LINK", "required": true },
+        { "name": "icon", "displayName": "Icon", "type": "IMAGE", "required": false },
+        { "name": "color", "displayName": "Text Color", "type": "COLOR", "required": false },
+        { "name": "subLinks", "displayName": "Sub Links", "type": "LIST_OF_LINK", "required": false }
+      ]
+    },
+    {
+      "id": "my-theme-icon-link",
+      "name": "IconLink",
+      "type": "component",
+      "entry": "./src/components/IconLink/index.tsx",
+      "styles": "./src/components/IconLink/styles.css",
+      "props": [
+        { "name": "image", "displayName": "Icon Image", "type": "IMAGE", "required": true },
+        { "name": "link", "displayName": "Link", "type": "LINK", "required": true },
+        { "name": "aspectRatio", "displayName": "Aspect Ratio", "type": "TEXT", "required": false, "defaultValue": "1/1" }
+      ]
+    }
+  ]
+}

package/data/migration-examples/complex-header-migration/after-section.tsx

@@ -0,0 +1,64 @@
+import { useState } from "preact/hooks";
+import { getDefaultSrc, IkasComponentRenderer } from "@ikas/bp-storefront";
+import { Props } from "./types";
+
+export default function HeaderSection({
+  logo,
+  logoWidth,
+  mobileLogoWidth,
+  menuLinks,
+  rightIcons,
+  announcement,
+  announcementLink,
+  announcementBg,
+  searchPlaceholder,
+  navBackground,
+  stickyNav,
+  ...props
+}: Props) {
+  const [mobileMenuOpen, setMobileMenuOpen] = useState(false);
+
+  return (
+    <header className={`header ${stickyNav ? "header--sticky" : ""}`}>
+      {announcement && (
+        <div className="announcement-bar" style={{ backgroundColor: announcementBg || "#000" }}>
+          {announcementLink ? (
+            <a href={announcementLink.href} className="announcement-link">{announcement}</a>
+          ) : (
+            <span>{announcement}</span>
+          )}
+        </div>
+      )}
+
+      <nav className="nav-bar" style={{ backgroundColor: navBackground || "#fff" }}>
+        <div className="nav-inner">
+          <button className="mobile-menu-btn" onClick={() => setMobileMenuOpen(!mobileMenuOpen)}>
+            <span className="hamburger-icon" />
+          </button>
+
+          {logo && (
+            <a href="/" className="logo-link" style={{ "--logo-w": `${logoWidth || 120}px`, "--logo-mw": `${mobileLogoWidth || 80}px` }}>
+              <img src={getDefaultSrc(logo)} alt="Logo" className="logo-image" />
+            </a>
+          )}
+
+          <div className="menu-links">
+            <IkasComponentRenderer id="menu-links" components={menuLinks as any[]} parentProps={props} />
+          </div>
+
+          <div className="right-icons">
+            <IkasComponentRenderer id="right-icons" components={rightIcons as any[]} parentProps={props} />
+          </div>
+        </div>
+      </nav>
+
+      {mobileMenuOpen && (
+        <div className="mobile-menu-overlay" onClick={() => setMobileMenuOpen(false)}>
+          <div className="mobile-menu" onClick={(e) => e.stopPropagation()}>
+            <IkasComponentRenderer id="mobile-menu-links" components={menuLinks as any[]} parentProps={props} />
+          </div>
+        </div>
+      )}
+    </header>
+  );
+}

package/data/migration-examples/complex-header-migration/before-props-summary.json

@@ -0,0 +1,42 @@
+{
+  "component": "Navbar",
+  "displayName": "Navbar",
+  "isHeader": true,
+  "props": [
+    { "name": "logo", "type": "IMAGE" },
+    { "name": "logoWidth", "type": "SLIDER", "sliderData": { "min": 80, "max": 300 } },
+    { "name": "mobLogoWidth", "type": "SLIDER", "sliderData": { "min": 0, "max": 200 } },
+    { "name": "menuLinks", "type": "CUSTOM", "customDataRef": "MenLink (DYNAMIC_LIST)" },
+    { "name": "extraRightLinks", "type": "CUSTOM", "customDataRef": "GrselveLinkObj (DYNAMIC_LIST)" },
+    { "name": "announcement", "type": "TEXT" },
+    { "name": "announcementLink", "type": "LINK" },
+    { "name": "announcementBg", "type": "COLOR" },
+    { "name": "searchPlaceholder", "type": "TEXT" },
+    { "name": "showGold", "type": "BOOLEAN" },
+    { "name": "navBg", "type": "COLOR" },
+    { "name": "mobileMenuBg", "type": "COLOR" },
+    { "name": "searchPopularProducts", "type": "PRODUCT_LIST", "groupId": "search-group" },
+    { "name": "closeInMobile", "type": "BOOLEAN" },
+    { "name": "stickyNav", "type": "BOOLEAN" }
+  ],
+  "customDataSummary": {
+    "MenLink": {
+      "type": "DYNAMIC_LIST/OBJECT",
+      "fields": [
+        { "key": "mainlink", "type": "LINK" },
+        { "key": "icon", "type": "IMAGE" },
+        { "key": "color", "type": "COLOR" },
+        { "key": "images", "type": "DYNAMIC_LIST", "nestedType": "GrselObjesi (image + link + viewType)" },
+        { "key": "sublinks", "type": "DYNAMIC_LIST", "nestedType": "AltLink (links + cols)" }
+      ]
+    },
+    "GrselveLinkObj": {
+      "type": "DYNAMIC_LIST/OBJECT",
+      "fields": [
+        { "key": "image", "type": "IMAGE" },
+        { "key": "aspect", "type": "TEXT" },
+        { "key": "link", "type": "LINK" }
+      ]
+    }
+  }
+}

package/data/migration-examples/custom-dynamic-list-to-component-list/_meta.json

@@ -0,0 +1,4 @@
+{
+  "title": "CUSTOM (DYNAMIC_LIST) → COMPONENT_LIST + Child Component",
+  "description": "Converts an old component with a CUSTOM prop referencing a DYNAMIC_LIST customData into a section with COMPONENT_LIST prop and a separate child component. This is the most common migration pattern."
+}

package/data/migration-examples/custom-dynamic-list-to-component-list/after-child-styles.css

@@ -0,0 +1,38 @@
+.store-card {
+  display: block;
+  overflow: hidden;
+  border-radius: 0.5rem;
+  border: 1px solid #e5e5e5;
+  text-decoration: none;
+  color: inherit;
+}
+
+.store-image-wrapper {
+  aspect-ratio: 16/9;
+  overflow: hidden;
+}
+
+.store-image {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+
+.store-content {
+  padding: 1rem;
+}
+
+.store-title {
+  font-size: 1.125rem;
+  font-weight: 500;
+}
+
+.store-location {
+  font-size: 0.875rem;
+  color: #6b7280;
+}
+
+.store-phone {
+  margin-top: 0.25rem;
+  font-size: 0.875rem;
+}

package/data/migration-examples/custom-dynamic-list-to-component-list/after-child.tsx

@@ -0,0 +1,22 @@
+import { getDefaultSrc } from "@ikas/bp-storefront";
+import { Props } from "./types";
+
+export default function StoreCard({ title, location, district, phone, image, link }: Props) {
+  const Tag = link ? "a" : "div";
+  const linkProps = link ? { href: link.href } : {};
+
+  return (
+    <Tag {...linkProps} className="store-card">
+      {image && (
+        <div className="store-image-wrapper">
+          <img src={getDefaultSrc(image)} alt={title || ""} className="store-image" />
+        </div>
+      )}
+      <div className="store-content">
+        <h3 className="store-title">{title}</h3>
+        <p className="store-location">{location}{district ? `, ${district}` : ""}</p>
+        {phone && <p className="store-phone">{phone}</p>}
+      </div>
+    </Tag>
+  );
+}

package/data/migration-examples/custom-dynamic-list-to-component-list/after-config-snippet.json

@@ -0,0 +1,31 @@
+{
+  "components": [
+    {
+      "id": "my-theme-stores-section",
+      "name": "StoresSection",
+      "type": "section",
+      "entry": "./src/components/StoresSection/index.tsx",
+      "styles": "./src/components/StoresSection/styles.css",
+      "props": [
+        { "name": "heading", "displayName": "Heading", "type": "TEXT", "required": false },
+        { "name": "columns", "displayName": "Columns", "type": "NUMBER", "required": false, "defaultValue": 3 },
+        { "name": "stores", "displayName": "Stores", "type": "COMPONENT_LIST", "required": false, "filteredComponentIds": ["my-theme-store-card"] }
+      ]
+    },
+    {
+      "id": "my-theme-store-card",
+      "name": "StoreCard",
+      "type": "component",
+      "entry": "./src/components/StoreCard/index.tsx",
+      "styles": "./src/components/StoreCard/styles.css",
+      "props": [
+        { "name": "title", "displayName": "Title", "type": "TEXT", "required": false },
+        { "name": "location", "displayName": "Location", "type": "TEXT", "required": false },
+        { "name": "district", "displayName": "District", "type": "TEXT", "required": false },
+        { "name": "phone", "displayName": "Phone", "type": "TEXT", "required": false },
+        { "name": "image", "displayName": "Image", "type": "IMAGE", "required": false },
+        { "name": "link", "displayName": "Link", "type": "LINK", "required": false }
+      ]
+    }
+  ]
+}

package/data/migration-examples/custom-dynamic-list-to-component-list/after-section-styles.css

@@ -0,0 +1,25 @@
+.stores-section {
+  max-width: 1700px;
+  margin: 2.5rem auto 0;
+  padding: 0 20px;
+}
+
+@media (min-width: 1024px) {
+  .stores-section {
+    margin-top: 5rem;
+    padding: 0 60px;
+  }
+}
+
+.stores-heading {
+  margin-bottom: 1.5rem;
+  text-align: center;
+  font-size: 1.5rem;
+  font-weight: 600;
+}
+
+.stores-grid {
+  display: grid;
+  grid-template-columns: repeat(var(--cols, 3), 1fr);
+  gap: 1.5rem;
+}

package/data/migration-examples/custom-dynamic-list-to-component-list/after-section.tsx

@@ -0,0 +1,17 @@
+import { IkasComponentRenderer } from "@ikas/bp-storefront";
+import { Props } from "./types";
+
+export default function StoresSection({ heading, columns, stores, ...props }: Props) {
+  return (
+    <section className="stores-section" style={{ "--cols": columns || 3 }}>
+      {heading && <h2 className="stores-heading">{heading}</h2>}
+      <div className="stores-grid">
+        <IkasComponentRenderer
+          id="stores"
+          components={stores as any[]}
+          parentProps={props}
+        />
+      </div>
+    </section>
+  );
+}

package/data/migration-examples/custom-dynamic-list-to-component-list/before-component.tsx

@@ -0,0 +1,32 @@
+import { Image } from '@ikas/storefront';
+import { observer } from 'mobx-react-lite';
+import { StoresPageProps } from '../__generated__/types';
+
+const StoresPage = ({ heading, stores, columns }: StoresPageProps) => {
+  return (
+    <div
+      style={{ '--cols': columns?.value || 3 } as React.CSSProperties}
+      className="wrapper mt-10 lg:mt-20"
+    >
+      {heading && <h2 className="mb-6 text-center text-2xl font-semibold">{heading}</h2>}
+      <div className="grid gap-6" style={{ gridTemplateColumns: `repeat(var(--cols), 1fr)` }}>
+        {stores.map((store, i) => (
+          <a key={i} href={store.link?.href} className="group overflow-hidden rounded-lg border">
+            {store.image && (
+              <div className="relative aspect-video">
+                <Image image={store.image} layout="fill" objectFit="cover" />
+              </div>
+            )}
+            <div className="p-4">
+              <h3 className="text-lg font-medium">{store.title}</h3>
+              <p className="text-sm text-gray-500">{store.location}, {store.district}</p>
+              <p className="mt-1 text-sm">{store.phone}</p>
+            </div>
+          </a>
+        ))}
+      </div>
+    </div>
+  );
+};
+
+export default observer(StoresPage);