@ikas/code-components-mcp 1.4.0-beta.1 → 1.4.0-beta.3

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>`. |\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### 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",
@@ -530,4 +530,4 @@
       ]
     }
   }
-}
+}

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);

package/data/migration-examples/custom-dynamic-list-to-component-list/before-theme-snippet.json

@@ -0,0 +1,53 @@
+{
+  "components": [
+    {
+      "id": "stores-page",
+      "name": "StoresPage",
+      "displayName": "Stores Page",
+      "props": [
+        {
+          "key": "heading",
+          "type": "TEXT",
+          "displayName": "Heading"
+        },
+        {
+          "key": "stores",
+          "type": "CUSTOM",
+          "displayName": "Stores",
+          "customDataId": "cd_stores_list"
+        },
+        {
+          "key": "columns",
+          "type": "SLIDER",
+          "displayName": "Columns",
+          "sliderData": {
+            "min": 1,
+            "max": 4,
+            "defaultValue": 3
+          }
+        }
+      ]
+    }
+  ],
+  "customData": [
+    {
+      "id": "cd_stores_list",
+      "name": "Mağazalarımız",
+      "type": "DYNAMIC_LIST",
+      "objectTypeId": "cd_store_object"
+    },
+    {
+      "id": "cd_store_object",
+      "name": "Maaza",
+      "type": "OBJECT",
+      "fields": [
+        { "key": "title", "type": "TEXT", "displayName": "Title" },
+        { "key": "location", "type": "TEXT", "displayName": "Location" },
+        { "key": "district", "type": "TEXT", "displayName": "District" },
+        { "key": "phone", "type": "TEXT", "displayName": "Phone" },
+        { "key": "image", "type": "IMAGE", "displayName": "Image" },
+        { "key": "link", "type": "LINK", "displayName": "Link" }
+      ]
+    }
+  ]
+}

package/data/migration-examples/full-component-with-tailwind/_meta.json

@@ -0,0 +1,4 @@
+{
+  "title": "Tailwind CSS → Plain Scoped CSS",
+  "description": "Converts a component using Tailwind utility classes, prose, and classnames into a component with plain scoped CSS."
+}

package/data/migration-examples/full-component-with-tailwind/after-component.tsx

@@ -0,0 +1,43 @@
+import { getDefaultSrc } from "@ikas/bp-storefront";
+import { Props } from "./types";
+
+export default function CTASection({
+  image,
+  aspectRatio,
+  title,
+  content,
+  marginTop,
+  mobileMarginTop,
+  reverseLayout,
+  backgroundColor,
+  miniImage,
+  miniImageAspect,
+  imageMaxWidth,
+  textMaxWidth,
+}: Props) {
+  return (
+    <div className="cta-wrapper" style={{ backgroundColor: backgroundColor || "transparent" }}>
+      <div
+        className={`cta-grid ${reverseLayout ? "cta-grid--reversed" : ""}`}
+        style={{
+          "--mt": `${marginTop || 0}px`,
+          "--mt-mobile": `${mobileMarginTop || 0}px`,
+        }}
+      >
+        <div className="cta-image-col" style={{ aspectRatio: aspectRatio || "1/1", maxWidth: imageMaxWidth || "316px" }}>
+          {image && <img src={getDefaultSrc(image)} alt="" className="cta-image" />}
+        </div>
+
+        <div className="cta-text-col" style={{ maxWidth: textMaxWidth || "600px" }}>
+          {miniImage && (
+            <div className="cta-mini-image" style={{ aspectRatio: miniImageAspect }}>
+              <img src={getDefaultSrc(miniImage)} alt="" className="cta-mini-img" />
+            </div>
+          )}
+          {title && <div className="cta-title" dangerouslySetInnerHTML={{ __html: title }} />}
+          {content && <div className="cta-content" dangerouslySetInnerHTML={{ __html: content }} />}
+        </div>
+      </div>
+    </div>
+  );
+}

package/data/migration-examples/full-component-with-tailwind/after-config-snippet.json

@@ -0,0 +1,25 @@
+{
+  "components": [
+    {
+      "id": "my-theme-cta-section",
+      "name": "CTASection",
+      "type": "section",
+      "entry": "./src/components/CTASection/index.tsx",
+      "styles": "./src/components/CTASection/styles.css",
+      "props": [
+        { "name": "image", "displayName": "Image", "type": "IMAGE", "required": true },
+        { "name": "aspectRatio", "displayName": "Image Aspect Ratio", "type": "TEXT", "required": false, "defaultValue": "1/1" },
+        { "name": "title", "displayName": "Title (HTML)", "type": "RICH_TEXT", "required": false },
+        { "name": "content", "displayName": "Content (HTML)", "type": "RICH_TEXT", "required": true },
+        { "name": "marginTop", "displayName": "Margin Top (px)", "type": "NUMBER", "required": false, "defaultValue": 0 },
+        { "name": "mobileMarginTop", "displayName": "Mobile Margin Top (px)", "type": "NUMBER", "required": false, "defaultValue": 0 },
+        { "name": "reverseLayout", "displayName": "Reverse Image/Text", "type": "BOOLEAN", "required": false, "defaultValue": false },
+        { "name": "backgroundColor", "displayName": "Background Color", "type": "COLOR", "required": false },
+        { "name": "miniImage", "displayName": "Mini Image", "type": "IMAGE", "required": false },
+        { "name": "miniImageAspect", "displayName": "Mini Image Aspect", "type": "TEXT", "required": false },
+        { "name": "imageMaxWidth", "displayName": "Image Max Width", "type": "TEXT", "required": false, "defaultValue": "316px" },
+        { "name": "textMaxWidth", "displayName": "Text Max Width", "type": "TEXT", "required": false, "defaultValue": "600px" }
+      ]
+    }
+  ]
+}

package/data/migration-examples/full-component-with-tailwind/after-styles.css

@@ -0,0 +1,99 @@
+.cta-wrapper {
+  width: 100%;
+}
+
+.cta-grid {
+  max-width: 1700px;
+  margin: var(--mt-mobile, 0) auto 0;
+  padding: 60px 20px 0;
+  display: grid;
+  grid-template-columns: 1fr;
+  align-items: center;
+}
+
+@media (min-width: 1024px) {
+  .cta-grid {
+    margin-top: var(--mt, 0);
+    padding: 0 60px;
+    grid-template-columns: 1fr 1fr;
+  }
+}
+
+.cta-grid--reversed .cta-image-col {
+  order: 2;
+}
+
+.cta-image-col {
+  position: relative;
+  width: 100%;
+  margin: 0 auto;
+  overflow: hidden;
+}
+
+@media (min-width: 1024px) {
+  .cta-image-col {
+    margin-top: 60px;
+  }
+}
+
+.cta-image {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+
+.cta-text-col {
+  margin: 0 auto;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  height: 100%;
+  padding: 0 1.5rem 1.5rem;
+}
+
+@media (min-width: 1280px) {
+  .cta-text-col {
+    padding: 2.5rem;
+  }
+}
+
+.cta-mini-image {
+  width: 188px;
+  margin-bottom: 30px;
+}
+
+@media (min-width: 1024px) {
+  .cta-mini-image {
+    margin-bottom: 40px;
+  }
+}
+
+.cta-mini-img {
+  width: 100%;
+  height: 100%;
+  object-fit: contain;
+}
+
+.cta-title {
+  margin-bottom: 1rem;
+  text-align: center;
+  font-size: 20px;
+  font-weight: 300;
+  line-height: 1.2;
+  color: white;
+}
+
+@media (min-width: 1024px) {
+  .cta-title {
+    font-size: 30px;
+  }
+}
+
+.cta-content {
+  text-align: center;
+  font-size: 0.875rem;
+  font-weight: 300;
+  line-height: 1.2;
+  color: white;
+}