@ikas/code-components-mcp 1.4.0-beta.5 → 1.4.0-beta.50
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/data/framework.json +67 -8
- package/data/migration.json +21 -7
- package/data/storefront-api.json +184 -1352
- package/data/storefront-types.json +32 -124
- package/dist/index.js +1471 -321
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/data/migration.json
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
"migration-overview": {
|
|
5
5
|
"title": "Old Theme → Code Component Migration Overview",
|
|
6
6
|
"description": "End-to-end workflow for converting an old ikas storefront theme into a new code-component project",
|
|
7
|
-
"content": "This guide covers converting themes built with the old ikas storefront system (React, theme.json, @ikas/storefront, Tailwind CSS) into the new code-component system (Preact, ikas.config.json, @ikas/bp-storefront, scoped CSS).\n\n## FIRST: Choose a Workflow\n\n### For themes with >5 sections: USE THE ITERATIVE WORKFLOW\n\nLarge themes cannot be migrated in a single LLM session. Use the four-phase resumable workflow:\n\n1. **Phase A (once):** Call `plan_migration(theme_json, old_source_dir)` — generates MIGRATION.md with extracted CSS vars, enums, detected shared sub-components, and an ordered section queue with canonical component IDs.\n2. **Phase B (once):** Execute the foundation checklist — create global.css, run enum CLI commands, build shared sub-components.\n3. **Phase C (loop):** For each section, call `get_section_migration_plan(theme_json, section_name)` → run CLI commands → write `index.tsx` and `styles.css` → mark `[x]` in MIGRATION.md.\n4. **Phase D (any session):** First read MIGRATION.md, find the first `[ ]` item, resume.\n\n**See `get_migration_guide(\"iterative-workflow\")` for the full protocol.**\n\n### For small themes (< 5 sections): ONE-PASS WORKFLOW\n\n1. Call `analyze_old_theme` to understand the structure\n2. Generate ikas.config.json and all component files in one pass\n3. Build and verify\n\n## MCP Responsibilities vs LLM Responsibilities\n\nA successful migration depends on understanding what the MCP can and cannot do for you:\n\n- **MCP writes:** The initial `MIGRATION.md` (once, when you call `plan_migration` with `project_root`). Never again.\n- **MCP provides:** Reference data via read-only tools — section templates, type docs, framework guides, per-section migration plans.\n- **LLM owns:** All ongoing edits to `MIGRATION.md` — checkboxes, custom-data decisions, source-code-analysis findings, notes. Use your standard file-editing tools.\n- **LLM must do:** Source code analysis. `theme.json` does NOT list atomic UI primitives (Button, Input, Card, icons, layout helpers). These live only in old `src/` and the MCP cannot see them. You scan; you log them in MIGRATION.md.\n- **LLM decides:** Every customData enum-vs-component choice. The MCP's auto-classification (flat scalars → enum, structured records → component) is a default — verify each one against the actual data semantics.\n\nThere is no `resume_migration`, `mark_section_complete`, or `record_custom_data_decision` tool. By design, the LLM uses its own Read/Edit tools to update MIGRATION.md. The MCP's job is to give you a high-quality starting scaffold and ongoing reference data.\n\n## CRITICAL: The Two Systems Are Completely Different\n\n**The old storefront system (`@ikas/storefront`) and the new code-component system (`@ikas/bp-storefront`) are entirely separate systems with different packages, different data types, different APIs, and different runtime behaviors.** Even when type names look the same (e.g., `IkasImage`, `IkasProduct`, `IkasNavigationLink`), they are **different types from different packages** with potentially different properties and methods.\n\n**NEVER assume** that because a type exists in the old system, it works the same way in the new system:\n- `IkasImage` from `@ikas/storefront` ≠ `IkasImage` from `@ikas/bp-storefront` — different properties, different helper functions\n- `IkasProduct` from `@ikas/storefront` ≠ `IkasProduct` from `@ikas/bp-storefront` — different data shape\n- `IkasNavigationLink` from `@ikas/storefront` ≠ `IkasNavigationLink` from `@ikas/bp-storefront` — different structure\n- `IkasSlider` from `@ikas/storefront` → **does not exist** in the new system (replaced by plain `number`)\n- The old `<Image>` component → **does not exist** in the new system (use `getDefaultSrc()` + native `<img>`)\n- The old `useStore()` hook → **does not exist** in the new system (import stores directly)\n- The old `observer()` from `mobx-react-lite` → **must not be used** on root components (use `observer` from `@ikas/component-utils` only on sub-components)\n\n**Similarly, the prop type systems are completely different:**\n- Old system prop types (in theme.json) are defined by `IkasThemeJsonComponentPropType` enum — a different set of strings with different semantics\n- New system prop types (in ikas.config.json) are defined by the code-component `PropType` enum\n- Prop types with the same name (e.g., `TEXT`, `IMAGE`, `BOOLEAN`) may seem identical but produce **different TypeScript types** and have **different editor UI behaviors**\n- The old system has types that don't exist in the new system (`SLIDER`, `CUSTOM`, `PRODUCT_DETAIL`)\n- The new system has types that don't exist in the old system (`NUMBER`, `NUMBER_RANGE`, `DATE`, `TYPE`, `FUNCTION`, `COMPONENT`)\n\n**Always use the MCP server's `get_prop_types`, `get_type_definition`, `get_function_doc`, and `get_model_guide` tools** to look up the correct new-system types, functions, and APIs. Never copy old-system type usage into new-system code.\n\n##
|
|
7
|
+
"content": "This guide covers converting themes built with the old ikas storefront system (React, theme.json, @ikas/storefront, Tailwind CSS) into the new code-component system (Preact, ikas.config.json, @ikas/bp-storefront, scoped CSS).\n\n## FIRST: Choose a Workflow\n\n### For themes with >5 sections: USE THE ITERATIVE WORKFLOW\n\nLarge themes cannot be migrated in a single LLM session. Use the four-phase resumable workflow:\n\n1. **Phase A (once):** Call `plan_migration(theme_json, old_source_dir)` — generates MIGRATION.md with extracted CSS vars, enums, detected shared sub-components, and an ordered section queue with canonical component IDs.\n2. **Phase B (once):** Execute the foundation checklist — create global.css, run enum CLI commands, build shared sub-components.\n3. **Phase C (loop):** For each section, call `get_section_migration_plan(theme_json, section_name)` → consult `get_migration_guide(\"custom-data-conversion\")` and `get_migration_guide(\"component-composition-decision-guide\")` for prop-shape choices → run CLI commands → write `index.tsx` and `styles.css` → mark `[x]` in MIGRATION.md.\n4. **Phase D (any session):** First read MIGRATION.md, find the first `[ ]` item, resume.\n\n**See `get_migration_guide(\"iterative-workflow\")` for the full protocol.**\n\n### For small themes (< 5 sections): ONE-PASS WORKFLOW\n\n1. Call `analyze_old_theme` to understand the structure\n2. Generate ikas.config.json and all component files in one pass\n3. Build and verify\n\n## MCP Responsibilities vs LLM Responsibilities\n\nA successful migration depends on understanding what the MCP can and cannot do for you:\n\n- **MCP writes:** The initial `MIGRATION.md` (once, when you call `plan_migration` with `project_root`). Never again.\n- **MCP provides:** Reference data via read-only tools — section templates, type docs, framework guides, per-section migration plans.\n- **LLM owns:** All ongoing edits to `MIGRATION.md` — checkboxes, custom-data decisions, source-code-analysis findings, notes. Use your standard file-editing tools.\n- **LLM must do:** Source code analysis. `theme.json` does NOT list atomic UI primitives (Button, Input, Card, icons, layout helpers). These live only in old `src/` and the MCP cannot see them. You scan; you log them in MIGRATION.md.\n- **LLM decides:** Every customData enum-vs-component choice. The MCP's auto-classification (flat scalars → enum, structured records → component) is a default — verify each one against the actual data semantics.\n\nThere is no `resume_migration`, `mark_section_complete`, or `record_custom_data_decision` tool. By design, the LLM uses its own Read/Edit tools to update MIGRATION.md. The MCP's job is to give you a high-quality starting scaffold and ongoing reference data.\n\n## CRITICAL: The Two Systems Are Completely Different\n\n**The old storefront system (`@ikas/storefront`) and the new code-component system (`@ikas/bp-storefront`) are entirely separate systems with different packages, different data types, different APIs, and different runtime behaviors.** Even when type names look the same (e.g., `IkasImage`, `IkasProduct`, `IkasNavigationLink`), they are **different types from different packages** with potentially different properties and methods.\n\n**NEVER assume** that because a type exists in the old system, it works the same way in the new system:\n- `IkasImage` from `@ikas/storefront` ≠ `IkasImage` from `@ikas/bp-storefront` — different properties, different helper functions\n- `IkasProduct` from `@ikas/storefront` ≠ `IkasProduct` from `@ikas/bp-storefront` — different data shape\n- `IkasNavigationLink` from `@ikas/storefront` ≠ `IkasNavigationLink` from `@ikas/bp-storefront` — different structure\n- `IkasSlider` from `@ikas/storefront` → **does not exist** in the new system (replaced by plain `number`)\n- The old `<Image>` component → **does not exist** in the new system (use `getDefaultSrc()` + native `<img>`)\n- The old `useStore()` hook → **does not exist** in the new system (import stores directly)\n- The old `observer()` from `mobx-react-lite` → **must not be used** on root components (use `observer` from `@ikas/component-utils` only on sub-components)\n\n**Similarly, the prop type systems are completely different:**\n- Old system prop types (in theme.json) are defined by `IkasThemeJsonComponentPropType` enum — a different set of strings with different semantics\n- New system prop types (in ikas.config.json) are defined by the code-component `PropType` enum\n- Prop types with the same name (e.g., `TEXT`, `IMAGE`, `BOOLEAN`) may seem identical but produce **different TypeScript types** and have **different editor UI behaviors**\n- The old system has types that don't exist in the new system (`SLIDER`, `CUSTOM`, `PRODUCT_DETAIL`)\n- The new system has types that don't exist in the old system (`NUMBER`, `NUMBER_RANGE`, `DATE`, `TYPE`, `FUNCTION`, `COMPONENT`)\n\n**Always use the MCP server's `get_prop_types`, `get_type_definition`, `get_function_doc`, and `get_model_guide` tools** to look up the correct new-system types, functions, and APIs. Never copy old-system type usage into new-system code.\n\n## Key Differences Summary\n\n| Old System | New System |\n|-----------|------------|\n| React 18 | Preact 10 |\n| @ikas/storefront | @ikas/bp-storefront |\n| theme.json | ikas.config.json |\n| Tailwind CSS | Scoped plain CSS |\n| External libraries allowed | No external libraries |\n| CUSTOM + customData | COMPONENT_LIST + child components |\n| SLIDER prop (IkasSlider) | NUMBER prop (number) |\n| PRODUCT_DETAIL | PRODUCT |\n| observer() on all components | observer() only on sub-components |\n| CSS Modules / Tailwind | .cc_{id} scoped CSS |\n| Next.js pages | Sections composed in editor |",
|
|
8
8
|
"tags": [
|
|
9
9
|
"migration",
|
|
10
10
|
"overview",
|
|
@@ -32,7 +32,7 @@
|
|
|
32
32
|
"custom-data-conversion": {
|
|
33
33
|
"title": "Converting CUSTOM Props and customData",
|
|
34
34
|
"description": "How to convert old CUSTOM prop types with customData definitions to new COMPONENT_LIST + child components",
|
|
35
|
-
"content": "The old system's `CUSTOM` prop type + `customData` definitions are the most complex part of any migration. Each old customData entry takes one of two paths in the new system — and the path is NOT a 1:1 mechanical conversion. **You must decide per type.**\n\n## The Heuristic\n\n> **Flat scalar set** (e.g. `\"left\" | \"right\" | \"center\"`) → new-system **enum prop** via `config add-enum`.\n>\n> **Structured record** (multi-field, especially if used as a list) → new-system **component** via `config add-component` + COMPONENT_LIST wiring on the parent.\n\nThe old system uses `customData` for both — a `Position` enum and a `Slide` record are both stored in `theme.customData[]`. The new system splits them: enums become a prop type, structured records become their own components. Old themes that flatten a record into an enum-like wrapper (e.g. a single-field customData with an image inside) need to be promoted into proper components in the new system.\n\n## When you call `get_section_migration_plan`\n\nThe MCP scans each prop and emits a **\"Custom Data Decisions to Make\"** callout for every prop that references a customData type. The callout shows the shape and the MCP's default classification. **Verify each default against the actual data semantics** — the MCP only sees shape, not usage. Log every final decision in `MIGRATION.md` under `## Custom Data Decisions`.\n\n## Worked Example 1: `Position` → enum prop\n\nA classic enum case. The old customData is a flat scalar set.\n\n### Old System\n\n```json\n// customData entry:\n{\n \"id\": \"...\",\n \"name\": \"Position\",\n \"type\": \"ENUM\",\n \"enumOptions\": [\n { \"displayName\": \"Left\", \"value\": \"left\" },\n { \"displayName\": \"Right\", \"value\": \"right\" },\n { \"displayName\": \"Center\", \"value\": \"center\" }\n ]\n}\n// Component prop:\n{ \"name\": \"alignment\", \"type\": \"CUSTOM\", \"customDataId\": \"...\" }\n```\n\n### New System (correct path: enum prop)\n\n```bash\nnpx ikas-component config add-enum --name \"Position\" --options '{\"Left\":\"left\",\"Right\":\"right\",\"Center\":\"center\"}'\n# → { \"success\": true, \"enumId\": \"enm_abc123\" }\n```\n\nThen on the parent section:\n\n```bash\nnpx ikas-component config add-prop --component <section-id> --name \"alignment\" --type ENUM --enumTypeId enm_abc123\n```\n\nIn TSX:\n\n```tsx\n<div style={{ textAlign: alignment }}>...</div>\n// `alignment` is a string with value \"left\" | \"right\" | \"center\"\n```\n\n## Worked Example 2: `Slide` → component + COMPONENT_LIST\n\nA repeating structured record. Multiple fields per item, used as a list.\n\n### Old System\n\n```json\n// customData entry:\n{\n \"name\": \"Slide\",\n \"type\": \"DYNAMIC_LIST\",\n \"nestedData\": [{\n \"type\": \"OBJECT\",\n \"nestedData\": [\n { \"key\": \"image\", \"type\": \"IMAGE\", \"name\": \"Image\" },\n { \"key\": \"title\", \"type\": \"TEXT\", \"name\": \"Title\" },\n { \"key\": \"link\", \"type\": \"LINK\", \"name\": \"Link\" }\n ]\n }]\n}\n// HeroSlider prop:\n{ \"name\": \"slides\", \"type\": \"CUSTOM\", \"customDataId\": \"...\" }\n```\n\n### New System (correct path: component + COMPONENT_LIST)\n\n```bash\n# 1. Create the Slide component\nnpx ikas-component config add-component --name \"Slide\" --type component \\\n --props '[{\"name\":\"image\",\"displayName\":\"Image\",\"type\":\"IMAGE\"},{\"name\":\"title\",\"displayName\":\"Title\",\"type\":\"TEXT\"},{\"name\":\"link\",\"displayName\":\"Link\",\"type\":\"LINK\"}]'\n# → { \"componentId\": \"cc_slide_xyz\" }\n\n# 2. Wire it into HeroSlider via COMPONENT_LIST + filteredComponentIds\nnpx ikas-component config add-component --name \"HeroSlider\" --type section \\\n --props '[{\"name\":\"slides\",\"displayName\":\"Slides\",\"type\":\"COMPONENT_LIST\",\"filteredComponentIds\":[\"cc_slide_xyz\"]}]'\n```\n\nIn TSX (HeroSlider renders Slide instances via IkasComponentRenderer):\n\n```tsx\n<IkasComponentRenderer id=\"slides\" components={slides as any[]} parentProps={props} />\n```\n\nIn TSX (Slide is a self-contained component with its three props):\n\n```tsx\nexport default function Slide({ image, title, link }: Props) {\n return (\n <a href={link?.href}>\n {image && <img src={getDefaultSrc(image)} alt={title} />}\n <h3>{title}</h3>\n </a>\n );\n}\n```\n\n## Worked Example 3: `MenuItem` (mega-menu) → component, NOT LIST_OF_LINK\n\nWhen the old theme has navigation links with **per-link metadata** (image, color, icon, submenu layout columns), `LIST_OF_LINK` cannot represent it. `IkasNavigationLink` only has `href`, `label`, `subLinks`, `openInNewTab`, `itemId`, `type` — there is **no slot for an image or any custom field**.\n\nThe correct conversion is the same pattern as `Slide`: build a dedicated component (`MenuItem`) with the per-link fields, then render an array of them via COMPONENT_LIST on the parent header/navbar.\n\n### Old System\n\n```json\n// customData entry:\n{\n \"name\": \"MenuItem\",\n \"type\": \"DYNAMIC_LIST\",\n \"nestedData\": [{\n \"type\": \"OBJECT\",\n \"nestedData\": [\n { \"key\": \"image\", \"type\": \"IMAGE\", \"name\": \"Image\" },\n { \"key\": \"title\", \"type\": \"TEXT\", \"name\": \"Title\" },\n { \"key\": \"link\", \"type\": \"LINK\", \"name\": \"Link\" }\n ]\n }]\n}\n// Header prop:\n{ \"name\": \"menuItems\", \"type\": \"CUSTOM\", \"customDataId\": \"...\" }\n```\n\n### New System (correct path: MenuItem component)\n\n```bash\nnpx ikas-component config add-component --name \"MenuItem\" --type component \\\n --props '[{\"name\":\"image\",\"displayName\":\"Image\",\"type\":\"IMAGE\"},{\"name\":\"title\",\"displayName\":\"Title\",\"type\":\"TEXT\"},{\"name\":\"link\",\"displayName\":\"Link\",\"type\":\"LINK\"}]'\n# → { \"componentId\": \"cc_menu_item_xyz\" }\n```\n\nThen wire into the Header section as a `COMPONENT_LIST` prop with `filteredComponentIds: [\"cc_menu_item_xyz\"]`.\n\n### Why NOT `LIST_OF_LINK`?\n\n```tsx\n// IkasNavigationLink — what LIST_OF_LINK gives you:\ntype IkasNavigationLink = {\n href: string;\n label: string;\n subLinks: IkasNavigationLink[];\n itemId: string;\n type: string;\n openInNewTab: boolean;\n};\n```\n\n**There is no `image` field.** If you flatten a mega-menu into `LIST_OF_LINK` you silently drop the image, color, custom icon, column count, and every other non-link field. Always prefer a `MenuItem`-style component when the old data is richer than href + label.\n\n## Supporting Cases (variations on the same patterns)\n\n### Simple OBJECT with ≤3 simple fields → flatten into parent props\n\nWhen a CUSTOM prop references an OBJECT with just 2-3 simple fields and is NOT used as a list, flattening into the parent's direct props is cleaner than building a child component:\n\n```json\n// Old customData OBJECT: { title: TEXT, color: COLOR }\n// Old prop: { \"name\": \"textData\", \"type\": \"CUSTOM\", \"customDataId\": \"...\" }\n\n// New: just expose two direct props on the parent\n[\n { \"name\": \"title\", \"displayName\": \"Title\", \"type\": \"TEXT\" },\n { \"name\": \"titleColor\", \"displayName\": \"Title Color\", \"type\": \"COLOR\" }\n]\n```\n\nThis is the **only** place where customData becomes neither an enum nor a component — purely because the old wrapping was an unnecessary abstraction.\n\n### Nested DYNAMIC_LIST inside an OBJECT → nested components\n\nE.g. a NavLink with `mainLink` (LINK) + `subLinks` (DYNAMIC_LIST of SubLink). Build a component per level (NavLink, SubLink), each with its own props, and nest COMPONENT_LIST slots.\n\n### STATIC_LIST → still a component\n\n`STATIC_LIST` differs from `DYNAMIC_LIST` only in editor UX (fixed count vs add/remove). In the new system, both are COMPONENT_LIST with a child component.\n\n## Two Ways to Render Lists — COMPONENT_LIST vs Data Props\n\nChoosing the wrong one is a common migration mistake.\n\n### Pattern 1: COMPONENT_LIST — store owner hand-picks items\n\nUse `COMPONENT_LIST` when the store owner should **manually select and arrange** individual items in the editor. Each item is a separate child component instance.\n\n**Example:** A curated product showcase where the merchant picks 4 featured products.\n- Parent section has `products` prop with type `COMPONENT_LIST`\n- Child **ProductCard** component (registered in ikas.config.json) has a `PRODUCT` prop\n- Store owner drags ProductCard instances into the slot and picks a product for each\n\nFor every COMPONENT_LIST prop, ensure a corresponding child component exists:\n- Product showcase → **ProductCard** child (PRODUCT prop)\n- Category grid → **CategoryCard** child (CATEGORY prop)\n- Blog highlights → **BlogCard** child (BLOG prop)\n- Mega menu → **MenuItem** child (LINK + IMAGE + TEXT props, per Example 3)\n- Slider/Carousel → **Slide** child (per Example 2)\n- Logo strip → **LogoItem** child (IMAGE prop)\n\nThe child component must be:\n1. Registered in `ikas.config.json` (via `config add-component --type component`)\n2. Listed in the parent's `filteredComponentIds`\n3. Capable of rendering a single item\n\n### Pattern 2: PRODUCT_LIST / BLOG_LIST / CATEGORY_LIST — data-driven rendering\n\nUse data prop types when items come from **dynamic data** — filtered, sorted, paginated, or automatically populated. The section renders items internally by mapping over the data.\n\n```tsx\nexport function CategoryPage({ products, ...props }: Props) {\n return (\n <section>\n <div className=\"product-grid\">\n {products?.data?.map((product, i) => (\n <ProductCard key={i} product={product} />\n ))}\n </div>\n </section>\n );\n}\n```\n\n### A Card Component Can Serve Both Patterns\n\nA single **registered** component like ProductCard can be used in BOTH ways: in a COMPONENT_LIST slot (merchant drags instances) AND imported directly into a data-driven section (mapped over `.data`). Register it once; reuse everywhere.\n\n### Decision Guide\n\n| Scenario | Pattern | Prop Type | Item Renderer |\n|----------|---------|-----------|---------------|\n| Merchant hand-picks items (curated grid, featured, mega-menu) | COMPONENT_LIST | `COMPONENT_LIST` | Registered child component via IkasComponentRenderer |\n| Data-driven list (category page, search results, blog archive) | Data prop | `PRODUCT_LIST` / `BLOG_LIST` / `CATEGORY_LIST` | Same registered component, imported directly and rendered via `.data.map()` |\n\n## Naming Convention for Child Components\n\n- Parent section: `{OldComponentName}Section` (e.g., `StoresSection`, `HeroSliderSection`)\n- Child component: `{ItemTypescriptName}` or `{ParentName}{ItemName}` (e.g., `StoreCard`, `Slide`, `MenuItem`)\n- Use `filteredComponentIds` on the COMPONENT_LIST prop to restrict which child components can be placed there\n\n## Logging Your Decision\n\nAfter every customData decision, append a row to `MIGRATION.md` under `## Custom Data Decisions`:\n\n```\n- `SlideData` → component `slide` (2026-05-11) — structured record {image, link, title}; wired into HeroSlider via COMPONENT_LIST.\n- `Position` → enum `Position` (2026-05-11) — flat scalar set left/right/center; enumId: enm_abc123.\n- `MenuItemData` → component `menu-item` (2026-05-12) — mega-menu links with image + title; LIST_OF_LINK would have dropped the image.\n```\n\nThis is how future sessions (and you, later) know which path was taken and avoid re-deciding inconsistently.\n",
|
|
35
|
+
"content": "The old system's `CUSTOM` prop type + `customData` definitions are the most complex part of any migration. Each old customData entry takes one of two paths in the new system — and the path is NOT a 1:1 mechanical conversion. **You must decide per type.**\n\n## The Feature-Parity Rule\n\nMigration is a port, not a redesign. If a customData type carries richer structure than the closest built-in prop type can hold, the answer is a new component — not flattening. Phrases like \"I'll add it later via COMPONENT_LIST\" are a red flag; the data is structured for a reason, and the cleanest time to model that structure is at migration time. Get explicit user approval before dropping any feature, and log the approval in `MIGRATION.md` → `## Notes`.\n\nThis is the rule the rest of this guide operationalizes.\n\n## The Heuristic (Short Version)\n\n- Flat scalar set (e.g. `\"left\" | \"right\" | \"center\"`) → enum prop via `config add-enum`.\n- Structured record with ≥3 fields → component via `config add-component` + `COMPONENT_LIST` on the parent.\n- Structured record with 1–2 fields → usually flatten to scalar props on the parent (and log the decision).\n\nFor the full decision tree (including domain LIST types like `LIST_OF_LINK`/`IMAGE_LIST` and the BOOLEAN-toggle anti-pattern), see `get_migration_guide(\"component-composition-decision-guide\")`.\n\n## When you call `get_section_migration_plan`\n\nThe MCP scans each prop and emits a **\"Custom Data Decisions to Make\"** callout for every prop that references a customData type. The callout shows the shape and the MCP's default classification. **Verify each default against the actual data semantics** — the MCP only sees shape, not usage. Log every final decision in `MIGRATION.md` under `## Custom Data Decisions`.\n\n## Worked Example 1: `Position` → enum prop\n\nA classic enum case. The old customData is a flat scalar set.\n\n### Old System\n\n```json\n// customData entry:\n{\n \"id\": \"...\",\n \"name\": \"Position\",\n \"type\": \"ENUM\",\n \"enumOptions\": [\n { \"displayName\": \"Left\", \"value\": \"left\" },\n { \"displayName\": \"Right\", \"value\": \"right\" },\n { \"displayName\": \"Center\", \"value\": \"center\" }\n ]\n}\n// Component prop:\n{ \"name\": \"alignment\", \"type\": \"CUSTOM\", \"customDataId\": \"...\" }\n```\n\n### New System (correct path: enum prop)\n\n```bash\nnpx ikas-component config add-enum --name \"Position\" --options '{\"Left\":\"left\",\"Right\":\"right\",\"Center\":\"center\"}'\n# → { \"success\": true, \"enumId\": \"enm_abc123\" }\n```\n\nThen on the parent section:\n\n```bash\nnpx ikas-component config add-prop --component <section-id> --name \"alignment\" --type ENUM --enumTypeId enm_abc123\n```\n\nIn TSX:\n\n```tsx\n<div style={{ textAlign: alignment }}>...</div>\n// `alignment` is a string with value \"left\" | \"right\" | \"center\"\n```\n\n## Worked Example 2: `Slide` → component + COMPONENT_LIST\n\nA repeating structured record. Multiple fields per item, used as a list.\n\n### Old System\n\n```json\n// customData entry:\n{\n \"name\": \"Slide\",\n \"type\": \"DYNAMIC_LIST\",\n \"nestedData\": [{\n \"type\": \"OBJECT\",\n \"nestedData\": [\n { \"key\": \"image\", \"type\": \"IMAGE\", \"name\": \"Image\" },\n { \"key\": \"title\", \"type\": \"TEXT\", \"name\": \"Title\" },\n { \"key\": \"link\", \"type\": \"LINK\", \"name\": \"Link\" }\n ]\n }]\n}\n// HeroSlider prop:\n{ \"name\": \"slides\", \"type\": \"CUSTOM\", \"customDataId\": \"...\" }\n```\n\n### New System (correct path: component + COMPONENT_LIST)\n\n```bash\n# 1. Create the Slide component\nnpx ikas-component config add-component --name \"Slide\" --type component \\\n --props '[{\"name\":\"image\",\"displayName\":\"Image\",\"type\":\"IMAGE\"},{\"name\":\"title\",\"displayName\":\"Title\",\"type\":\"TEXT\"},{\"name\":\"link\",\"displayName\":\"Link\",\"type\":\"LINK\"}]'\n# → { \"componentId\": \"cc_slide_xyz\" }\n\n# 2. Wire it into HeroSlider via COMPONENT_LIST + filteredComponentIds\nnpx ikas-component config add-component --name \"HeroSlider\" --type section \\\n --props '[{\"name\":\"slides\",\"displayName\":\"Slides\",\"type\":\"COMPONENT_LIST\",\"filteredComponentIds\":[\"cc_slide_xyz\"]}]'\n```\n\nIn TSX (HeroSlider renders Slide instances via IkasComponentRenderer):\n\n```tsx\n<IkasComponentRenderer id=\"slides\" components={slides as any[]} parentProps={props} />\n```\n\nIn TSX (Slide is a self-contained component with its three props):\n\n```tsx\nexport default function Slide({ image, title, link }: Props) {\n return (\n <a href={link?.href}>\n {image && <img src={getDefaultSrc(image)} alt={title} />}\n <h3>{title}</h3>\n </a>\n );\n}\n```\n\n## Worked Example 3: `MenuItem` (mega-menu) → component, NOT LIST_OF_LINK\n\nWhen the old theme has navigation links with **per-link metadata** (image, color, icon, submenu layout columns), `LIST_OF_LINK` cannot represent it. `IkasNavigationLink` only has `href`, `label`, `subLinks`, `openInNewTab`, `itemId`, `type` — there is **no slot for an image or any custom field**.\n\nThe correct conversion is the same pattern as `Slide`: build a dedicated component (`MenuItem`) with the per-link fields, then render an array of them via COMPONENT_LIST on the parent header/navbar.\n\n### Old System\n\n```json\n// customData entry:\n{\n \"name\": \"MenuItem\",\n \"type\": \"DYNAMIC_LIST\",\n \"nestedData\": [{\n \"type\": \"OBJECT\",\n \"nestedData\": [\n { \"key\": \"image\", \"type\": \"IMAGE\", \"name\": \"Image\" },\n { \"key\": \"title\", \"type\": \"TEXT\", \"name\": \"Title\" },\n { \"key\": \"link\", \"type\": \"LINK\", \"name\": \"Link\" }\n ]\n }]\n}\n// Header prop:\n{ \"name\": \"menuItems\", \"type\": \"CUSTOM\", \"customDataId\": \"...\" }\n```\n\n### New System (correct path: MenuItem component)\n\n```bash\nnpx ikas-component config add-component --name \"MenuItem\" --type component \\\n --props '[{\"name\":\"image\",\"displayName\":\"Image\",\"type\":\"IMAGE\"},{\"name\":\"title\",\"displayName\":\"Title\",\"type\":\"TEXT\"},{\"name\":\"link\",\"displayName\":\"Link\",\"type\":\"LINK\"}]'\n# → { \"componentId\": \"cc_menu_item_xyz\" }\n```\n\nThen wire into the Header section as a `COMPONENT_LIST` prop with `filteredComponentIds: [\"cc_menu_item_xyz\"]`.\n\n### Why NOT `LIST_OF_LINK`?\n\n```tsx\n// IkasNavigationLink — what LIST_OF_LINK gives you:\ntype IkasNavigationLink = {\n href: string;\n label: string;\n subLinks: IkasNavigationLink[];\n itemId: string;\n type: string;\n openInNewTab: boolean;\n};\n```\n\n**There is no `image` field.** If you flatten a mega-menu into `LIST_OF_LINK` you silently drop the image, color, custom icon, column count, and every other non-link field. Always prefer a `MenuItem`-style component when the old data is richer than href + label.\n\n## Supporting Cases (variations on the same patterns)\n\n### Simple OBJECT with ≤3 simple fields → flatten into parent props\n\nWhen a CUSTOM prop references an OBJECT with just 2-3 simple fields and is NOT used as a list, flattening into the parent's direct props is cleaner than building a child component:\n\n```json\n// Old customData OBJECT: { title: TEXT, color: COLOR }\n// Old prop: { \"name\": \"textData\", \"type\": \"CUSTOM\", \"customDataId\": \"...\" }\n\n// New: just expose two direct props on the parent\n[\n { \"name\": \"title\", \"displayName\": \"Title\", \"type\": \"TEXT\" },\n { \"name\": \"titleColor\", \"displayName\": \"Title Color\", \"type\": \"COLOR\" }\n]\n```\n\nThis is the **only** place where customData becomes neither an enum nor a component — purely because the old wrapping was an unnecessary abstraction.\n\n### Nested DYNAMIC_LIST inside an OBJECT → nested components\n\nE.g. a NavLink with `mainLink` (LINK) + `subLinks` (DYNAMIC_LIST of SubLink). Build a component per level (NavLink, SubLink), each with its own props, and nest COMPONENT_LIST slots.\n\n### STATIC_LIST → still a component\n\n`STATIC_LIST` differs from `DYNAMIC_LIST` only in editor UX (fixed count vs add/remove). In the new system, both are COMPONENT_LIST with a child component.\n\n## Rendering Lists — COMPONENT_LIST vs Data Props\n\nFor the COMPONENT_LIST (merchant hand-picks items) vs data-prop (`PRODUCT_LIST` / `BLOG_LIST` / `CATEGORY_LIST`, data-driven) distinction, see `get_framework_guide(\"component-renderer-patterns\")`. The same registered child component (e.g. `ProductCard`) is reusable across both patterns.\n\n## Naming Convention for Child Components\n\n- Parent section: `{OldComponentName}Section` (e.g., `StoresSection`, `HeroSliderSection`)\n- Child component: `{ItemTypescriptName}` or `{ParentName}{ItemName}` (e.g., `StoreCard`, `Slide`, `MenuItem`)\n- Use `filteredComponentIds` on the COMPONENT_LIST prop to restrict which child components can be placed there\n\n## Logging Your Decision\n\nAfter every customData decision, append a row to `MIGRATION.md` under `## Custom Data Decisions`:\n\n```\n- `SlideData` → component `slide` (2026-05-11) — structured record {image, link, title}; wired into HeroSlider via COMPONENT_LIST.\n- `Position` → enum `Position` (2026-05-11) — flat scalar set left/right/center; enumId: enm_abc123.\n- `MenuItemData` → component `menu-item` (2026-05-12) — mega-menu links with image + title; LIST_OF_LINK would have dropped the image.\n```\n\nThis is how future sessions (and you, later) know which path was taken and avoid re-deciding inconsistently.\n",
|
|
36
36
|
"tags": [
|
|
37
37
|
"migration",
|
|
38
38
|
"CUSTOM",
|
|
@@ -70,7 +70,7 @@
|
|
|
70
70
|
"react-to-preact": {
|
|
71
71
|
"title": "React to Preact Conversion Patterns",
|
|
72
72
|
"description": "Code patterns for converting old React components to new Preact code components",
|
|
73
|
-
"content": "## CRITICAL: Two Completely Different Systems\n\n**`@ikas/storefront` and `@ikas/bp-storefront` are entirely separate packages.** Types with the same name are NOT the same types — they come from different packages with different properties. Never copy old `@ikas/storefront` type usage patterns into new code. Always use the MCP tools (`get_type_definition`, `get_function_doc`, `get_model_guide`) to look up the correct API in the new system.\n\n## Import Changes\n\n### Remove React import\nOld: `import React from 'react';` or `import * as React from 'react';`\nNew: Remove entirely. Preact JSX is auto-imported.\n\n### Hook imports\nOld: `import { useState, useEffect, useRef, useMemo, useCallback } from 'react';`\nNew: `import { useState, useEffect, useRef, useMemo, useCallback } from 'preact/hooks';`\n\n### Storefront imports\nOld: `import { Image, ... } from '@ikas/storefront';`\nNew: `import { getDefaultSrc, ... } from '@ikas/bp-storefront';`\n\n**WARNING:** Do not assume that because `IkasImage` exists in both packages, it has the same shape. The old `IkasImage` from `@ikas/storefront` and the new `IkasImage` from `@ikas/bp-storefront` are different types. Always check the new type definition via `get_type_definition('IkasImage')` before using it.\n\nThe old `<Image>` component from `@ikas/storefront` does not exist in the new system. Use native `<img>` with `getDefaultSrc()
|
|
73
|
+
"content": "## CRITICAL: Two Completely Different Systems\n\n**`@ikas/storefront` and `@ikas/bp-storefront` are entirely separate packages.** Types with the same name are NOT the same types — they come from different packages with different properties. Never copy old `@ikas/storefront` type usage patterns into new code. Always use the MCP tools (`get_type_definition`, `get_function_doc`, `get_model_guide`) to look up the correct API in the new system.\n\n## Import Changes\n\n### Remove React import\nOld: `import React from 'react';` or `import * as React from 'react';`\nNew: Remove entirely. Preact JSX is auto-imported.\n\n### Hook imports\nOld: `import { useState, useEffect, useRef, useMemo, useCallback } from 'react';`\nNew: `import { useState, useEffect, useRef, useMemo, useCallback } from 'preact/hooks';`\n\n### Storefront imports\nOld: `import { Image, ... } from '@ikas/storefront';`\nNew: `import { getDefaultSrc, ... } from '@ikas/bp-storefront';`\n\n**WARNING:** Do not assume that because `IkasImage` exists in both packages, it has the same shape. The old `IkasImage` from `@ikas/storefront` and the new `IkasImage` from `@ikas/bp-storefront` are different types. Always check the new type definition via `get_type_definition('IkasImage')` before using it.\n\nThe old `<Image>` component from `@ikas/storefront` does not exist in the new system. Use native `<img>` with `getDefaultSrc()` — full image-rendering recipes (variant chain, gallery, srcsets, background) live in `get_framework_guide(\"image-handling\")`.\n\n### Observer pattern\nOld: `import { observer } from 'mobx-react-lite'; export default observer(MyComponent);`\nNew: Remove for root components. Only use on sub-components:\n```tsx\n// Root component (in src/components/) — NO observer:\nexport default function MySection(props: Props) { ... }\n\n// Sub-component (in src/sub-components/) — observer OK:\nimport { observer } from '@ikas/component-utils';\nfunction CartCounter() { ... }\nexport default observer(CartCounter);\n```\n\n## Component Declaration\n\nOld:\n```tsx\nconst MyComponent = ({ title, image }: MyComponentProps) => { return (...); };\nexport default observer(MyComponent);\n```\n\nNew:\n```tsx\nimport { Props } from './types';\n\nexport function MyComponent({ title, image }: Props) { return (...); }\nexport default MyComponent;\n```\n\n**CRITICAL: Components need BOTH a named export AND a default export.** The CLI auto-generates a barrel file (`src/components/index.ts`) that uses named imports: `export { MyComponent } from './MyComponent/index'`. If you only do `export default function MyComponent`, the barrel import will fail with type errors. Always declare the function with `export function Name(...)` and then add `export default Name;` below it.\n\nKey changes:\n- Named function export AND default export (both required)\n- Props type imported from `./types` (auto-generated by CLI)\n- No `observer()` wrapper on root components\n\n## Type Changes\n\n| Old Type | New Type | Notes |\n|----------|----------|-------|\n| `React.CSSProperties` | `Record<string, string>` | Inline-style object |\n| `React.FC<Props>` | Remove, use named function | |\n| `React.MouseEvent` | `Event` (cast `e.target` as needed) | `JSX.TargetedMouseEvent<T>` is not reliably resolvable in our tsconfig — prefer plain `Event`. |\n| `React.ChangeEvent<HTMLInputElement>` | `Event` + cast | Preact uses `onInput` (not `onChange`) for text inputs. |\n| `React.FormEvent` | `Event` + cast | |\n| `React.ReactNode` | `ComponentChildren` from `preact` | |\n| `IkasSlider` | `number` | Was `{ value: number }`, now plain number |\n\n## CSS Patterns\n\n### Tailwind → Scoped CSS\nOld: `<div className=\"flex items-center gap-4 p-6 text-center\">`\nNew: `<div className=\"my-container\">` with CSS:\n```css\n.my-container {\n display: flex;\n align-items: center;\n gap: 1rem;\n padding: 1.5rem;\n text-align: center;\n}\n```\n\n### CSS Modules → Scoped CSS\nOld: `import styles from './styles.module.css'; <div className={styles.container}>`\nNew: `<div className=\"container\">` — CSS is auto-scoped via `.cc_{componentId}` prefix.\n\n### Inline styles with CSS custom properties\nOld: `style={{ '--mth': \\`\\${marginTop?.value}px\\` } as React.CSSProperties}`\nNew: `style={{ '--mth': \\`\\${marginTop}px\\` }}` — Note: `marginTop` is now a plain number, not `IkasSlider`.\n\n## IkasSlider → number\n\nThis is one of the most common code changes. Every `IkasSlider` value access needs updating:\n\n```tsx\n// Old (IkasSlider has .value property):\nconst width = logoWidth?.value || 120;\nconst gap = `${spacing?.value || 0}px`;\nstyle={{ '--w': `${item.width?.value}px` }}\n\n// New (plain number):\nconst width = logoWidth || 120;\nconst gap = `${spacing || 0}px`;\nstyle={{ '--w': `${item.width}px` }}\n```\n\n## Image Handling\n\nThe old `<Image>` component does not exist in the new system. Replace with native `<img>` + `getDefaultSrc()` / `getSrc()` / `createMediaSrcset()`. The full recipe (single image, variant chain, gallery, background images, responsive srcsets) lives in `get_framework_guide(\"image-handling\")`.\n\n## Video Handling\n\n```tsx\n// Old (IkasVideo was often used with react-player):\nimport ReactPlayer from 'react-player';\n<ReactPlayer url={video.url} />\n\n// New (native video or iframe):\n{video && (\n video.type === 'EMBED'\n ? <iframe src={video.url} allowFullScreen />\n : <video src={video.url} controls poster={video.thumbnailUrl} />\n)}\n```\n\n## Event Handling\n\n```tsx\n// Old:\nconst handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {\n setValue(e.target.value);\n};\n\n// New — use plain `Event` and cast (works regardless of tsconfig JSX resolution):\nconst handleInput = (e: Event) => {\n setValue((e.target as HTMLInputElement).value);\n};\n\n// Preact uses `onInput` (not `onChange`) for text inputs:\n// <input onInput={handleInput} />\n```\n\n## dangerouslySetInnerHTML\n\nWorks the same in both:\n```tsx\n<div dangerouslySetInnerHTML={{ __html: richTextContent }} />\n```\n\n## useStore → Direct imports\n\nOld themes used `useStore()` from `@ikas/storefront` for accessing MobX stores:\n```tsx\n// Old:\nconst { cartStore, customerStore } = useStore();\n\n// New — import stores directly:\nimport { cartStore, customerStore } from '@ikas/bp-storefront';\n```\n\n## key prop\n\nSame in both systems. Always use `key` when mapping:\n```tsx\n{items.map((item, i) => <div key={item.id || i}>...</div>)}\n```",
|
|
74
74
|
"tags": [
|
|
75
75
|
"migration",
|
|
76
76
|
"react",
|
|
@@ -88,7 +88,7 @@
|
|
|
88
88
|
"storefront-import-mapping": {
|
|
89
89
|
"title": "Import Mapping: @ikas/storefront → @ikas/bp-storefront",
|
|
90
90
|
"description": "Maps old @ikas/storefront imports to new @ikas/bp-storefront equivalents",
|
|
91
|
-
"content": "##
|
|
91
|
+
"content": "## Old Package → New Package\n\nAll imports change from `@ikas/storefront` to `@ikas/bp-storefront`. **This is NOT a find-and-replace.** Even types with the same name (`IkasImage`, `IkasProduct`, etc.) come from different packages and may have different shapes. Always verify with `get_type_definition` or `get_model_guide` before assuming compatibility.\n\n## Type Rename Table\n\n| Old Import (`@ikas/storefront`) | New Import (`@ikas/bp-storefront`) | Notes |\n|-----------|-----------|-------|\n| `IkasImage`, `IkasVideo`, `IkasNavigationLink`, `IkasProduct`, `IkasProductList`, `IkasCategory`, `IkasCategoryList`, `IkasBrand`, `IkasBlog`, `IkasBlogList`, `IkasBlogCategory`, `IkasBlogCategoryList` | Same name | Different package — shape may differ; verify before assuming. |\n| `IkasSlider` | *(removed)* | Use plain `number`. |\n| `IkasAttributeDetail` | `IkasProductAttributeValue` | Renamed. |\n| `IkasAttributeList` | `IkasProductAttributeValue[]` | Renamed; now a plain array. |\n| `IkasComponentRenderer` | `IkasComponentRenderer` | Same name, different usage — see below. |\n\n## Function / Pattern Rename Table\n\n| Old | New | Notes |\n|-----|-----|-------|\n| `<Image>` component | `getDefaultSrc()` / `getSrc()` + native `<img>` | See `react-to-preact` for image patterns. |\n| `useStore()` hook | Direct imports (`cartStore`, `customerStore`, ...) | Stores are MobX observables; no wrapper hook. |\n| `<IkasComponentRenderer>{children}</...>` | `<IkasComponentRenderer id=\"...\" components={list as any[]} parentProps={props} />` | New props-based API. |\n\nFor all import/observer/hook/event-handling behavior changes, see `get_migration_guide(\"react-to-preact\")` — this topic is intentionally a quick rename reference.\n",
|
|
92
92
|
"tags": [
|
|
93
93
|
"migration",
|
|
94
94
|
"imports",
|
|
@@ -119,7 +119,7 @@
|
|
|
119
119
|
"component-decomposition-strategy": {
|
|
120
120
|
"title": "Component Decomposition Strategy",
|
|
121
121
|
"description": "How to break old monolithic components into section + child components in the new system",
|
|
122
|
-
"content": "## Overview\n\nOld themes typically have flat component lists where each component handles everything internally. The new system uses a section → child component hierarchy. Here's how to decompose.\n\n## Rule 1: Every Old Component Becomes a Section\n\nIn the new system, sections are page-level containers. Each old component maps to a `type: \"section\"` in ikas.config.json.\n\nException: If an old component was only used as an internal sub-component (e.g., a reusable ProductCard), it becomes a `type: \"component\"` (child) instead.\n\n## Rule 2: CUSTOM
|
|
122
|
+
"content": "## Overview\n\nOld themes typically have flat component lists where each component handles everything internally. The new system uses a section → child component hierarchy. Here's how to decompose.\n\n## Rule 1: Every Old Component Becomes a Section\n\nIn the new system, sections are page-level containers. Each old component maps to a `type: \"section\"` in ikas.config.json.\n\nException: If an old component was only used as an internal sub-component (e.g., a reusable ProductCard), it becomes a `type: \"component\"` (child) instead.\n\n## Rule 2: CUSTOM Props → Pick the Right Shape\n\nFor each CUSTOM prop, do NOT default to `COMPONENT_LIST`. See `get_migration_guide(\"component-composition-decision-guide\")` for the full decision tree. Short version:\n- DYNAMIC_LIST of structured records with ≥3 fields → `COMPONENT_LIST` + new child component (use `filteredComponentIds`).\n- DYNAMIC_LIST of items with 1–2 fields → repeated scalar props or a domain LIST type (`LIST_OF_LINK`, `IMAGE_LIST`, …).\n- OBJECT with ≤3 simple fields (TEXT/BOOLEAN/COLOR/NUMBER) → flatten into direct props on the parent.\n\nExample (flatten):\n- Old: `settings: { backgroundColor: string, showTitle: boolean }` via CUSTOM OBJECT\n- New: `backgroundColor` (COLOR) + `showTitle` (BOOLEAN) directly on section\n\n## Rule 4: Header and Footer\n\nIdentify header/footer components (usually named \"Navbar\", \"Header\", \"Footer\"):\n- Mark the section with `isHeader: true` or `isFooter: true`\n- These sections appear on every page automatically\n\n## Rule 5: Prop Groups\n\nOld `groups[]` array maps to `propGroups` on each component:\n```json\n// Old (global groups array):\n\"groups\": [{ \"id\": \"group-uuid\", \"name\": \"Slider\" }]\n// Component prop: { \"name\": \"delay\", \"groupId\": \"group-uuid\" }\n\n// New (per-component propGroups):\n\"propGroups\": [{ \"id\": \"slider\", \"name\": \"Slider\" }]\n// Component prop: { \"name\": \"delay\", \"groupId\": \"slider\" }\n```\n\n## Rule 6: Shared Sub-Components\n\nIf multiple sections share similar UI elements (buttons, modals, cards), create them in `src/sub-components/` instead of registering them in ikas.config.json.\n\n## Example Decomposition\n\n**Old: ProductGrid component** with props:\n- `products` (CUSTOM → DYNAMIC_LIST of `{ tab: string, products: IkasProductList }`)\n- `showedTags` (CUSTOM → DYNAMIC_LIST of `{ tag: string, color: string }`)\n- `columns` (SLIDER)\n- `gap` (SLIDER)\n\n**New structure:**\n1. **ProductGridSection** (section)\n - `tabs` → COMPONENT_LIST (filteredComponentIds: [\"my-project-product-tab\"])\n - `tags` → COMPONENT_LIST (filteredComponentIds: [\"my-project-product-tag\"])\n - `columns` → NUMBER\n - `gap` → NUMBER\n\n2. **ProductTab** (component)\n - `tabName` → TEXT\n - `products` → PRODUCT_LIST\n\n3. **ProductTag** (component)\n - `tag` → TEXT\n - `color` → COLOR\n - `backgroundColor` → COLOR\n\n## Estimating Child Components\n\nCount the number of CUSTOM props across all components that reference DYNAMIC_LIST customData. Each one typically needs 1 child component. Some may share child components if the structure is identical.",
|
|
123
123
|
"tags": [
|
|
124
124
|
"migration",
|
|
125
125
|
"decomposition",
|
|
@@ -212,7 +212,7 @@
|
|
|
212
212
|
"prop-runtime-shapes": {
|
|
213
213
|
"title": "Runtime Shapes of Prop Types",
|
|
214
214
|
"description": "Exact TypeScript shapes your component receives at runtime for each prop type. Covers common confusions (.data vs .links, .variant vs .product).",
|
|
215
|
-
"content": "When you declare a prop in `ikas.config.json`, the component receives a specific runtime shape. This table documents what you actually get — which is often different from the editor UI suggests and from naive expectations.\n\n## Reference Table\n\n| PropType | Runtime Shape | Key Access Pattern |\n|----------|---------------|--------------------|\n| `TEXT` | `string` | `props.myText` |\n| `RICH_TEXT` | `string` (HTML) | `<div dangerouslySetInnerHTML={{ __html: props.html }} />` |\n| `NUMBER` | `number` | `props.width` (direct number, NOT `.value`) |\n| `BOOLEAN` | `boolean` | `props.enabled` |\n| `COLOR` | `string` (CSS color) | `style={{ color: props.textColor }}` |\n| `IMAGE` | `IkasImage \\| null` | `getDefaultSrc(props.image)` or `getSrc(props.image, { width: 400 })` |\n| `IMAGE_LIST` | `IkasImageList` | `props.images.map(img => getDefaultSrc(img))` |\n| `VIDEO` | `IkasVideo \\| null` | Check `.url`, `.type` (EMBED vs FILE) |\n| `LINK` | `IkasNavigationLink` | `props.link.href`, `props.link.label`, `props.link.subLinks`, `props.link.openInNewTab` |\n| `LIST_OF_LINK` | `IkasNavigationLinkList` | **`props.links.links`** — access via `.links` property (NOT `.data`) |\n| `PRODUCT` | `IkasProduct \\| null` | `props.product.name`, `.prices`, etc. |\n| `PRODUCT_LIST` | `IkasProductList` | **`props.productList.data`** — array of products via `.data` property |\n| `CATEGORY` | `IkasCategory \\| null` | `props.category.name`, `.href` |\n| `CATEGORY_LIST` | `IkasCategoryList` | Check shape with `get_type_definition(\"IkasCategoryList\")` |\n| `BRAND` / `BRAND_LIST` | `IkasBrand \\| null` / `IkasBrandList` | Use `get_model_guide(\"IkasBrand\")` |\n| `BLOG` / `BLOG_LIST` | `IkasBlog \\| null` / `IkasBlogList` | Blog list uses `.data` |\n| `PRODUCT_ATTRIBUTE` | `IkasProductAttributeValue \\| null` | Direct single value |\n| `PRODUCT_ATTRIBUTE_LIST` | `IkasProductAttributeValue[]` | Plain array (NOT wrapped) |\n| `ENUM` | `string` (the enum value) | Compare directly: `props.type === \"email\"` |\n| `COMPONENT` | `any` | Pass to `<IkasComponentRenderer components={[comp] as any[]} />` |\n| `COMPONENT_LIST` | `any[]` | Pass to `<IkasComponentRenderer components={list as any[]} />` |\n\n## Critical: Inconsistent Access Patterns\n\nThe most common mistakes come from **list-type props having inconsistent access patterns**:\n\n- `PRODUCT_LIST` → `.data` (array of products)\n- `BLOG_LIST` → `.data` (array of blogs)\n- `LIST_OF_LINK` → `.links` (NOT `.data`)\n- `PRODUCT_ATTRIBUTE_LIST` → plain array (no wrapper)\n- `IMAGE_LIST` → plain array via `.data` (check with `get_type_definition`)\n\n**When in doubt, call `get_model_guide(\"IkasProductList\")` etc. for the exact shape.**\n\n## Image Sizing: getDefaultSrc vs getSrc\n\n- `getDefaultSrc(image)` — returns the default-sized URL. Use for small images, thumbnails, or when size doesn't matter.\n- `getSrc(image, { width: 400 })` — returns a URL at a specific width. Use for performance-critical images where you know the rendered size.\n- `createMediaSrcset(image)` — generates a responsive `srcset` string for `<img srcset={...}>`.\n\n**Rule of thumb:** Use `getSrc` with a concrete width for large images; use `getDefaultSrc` for icons/small images.\n\n## Store Data Shapes (cartStore, customerStore, etc.)\n\nStore data is NOT a prop type — you import stores directly from `@ikas/bp-storefront`. Their runtime shapes are:\n\n- `cartStore.cart` → `IkasCart`: `.orderLineItems` is the array; each item has **`.variant`** (not `.product`), `.quantity`, `.totalPrice`\n- `customerStore.customer` → `IkasCustomer | null`: null when logged out, has `.firstName`, `.lastName`, `.email`, `.id`\n- `customerStore.isAuthenticated` → boolean\n\n**For full store shapes, always use `get_model_guide(\"IkasCart\")`, `get_model_guide(\"IkasCustomer\")`, etc. — do not guess.**\n\n## Old → New Runtime Shape Changes\n\nWhen migrating, remember these runtime changes:\n\n- Old `IkasSlider` (with `.value`) → New `number` (plain). Replace `width?.value` with just `width`.\n- Old `<Image>` component (renders itself) → New `getDefaultSrc(image)` + native `<img>`.\n- Old `useStore()` hook → New direct import: `import { cartStore } from '@ikas/bp-storefront'`.\n- Old `IkasAttributeDetail` / `IkasAttributeList` → New `IkasProductAttributeValue` / array.\n\n\n\n## Order Line Item Shapes (cart, order pages)\n\nThese come up when iterating over `IkasCart.orderLineItems` or `IkasOrder.orderLineItems`. They trip up LLMs because the field names don't match scalar intuition:\n\n- **`IkasOrderLineItemOption.values`** — this is an **array** of `IkasOrderLineItemOptionValue`, NOT a scalar `.value`. Iterate it with `.map`:\n\n ```tsx\n // WRONG — there is no .value on IkasOrderLineItemOption\n <span>{option.value}</span>\n\n // RIGHT — .values is an array, each item has its own .name/.value/.formattedPrice\n {option.values.map((v) => (\n <span key={v.name}>{v.name}: {v.value}</span>\n ))}\n ```\n\n- **`IkasOrderAdjustment` has no `.formattedAmount` property.** Call the helper instead: `getOrderAdjustmentFormattedAmount(adjustment)` from `@ikas/bp-storefront`. The helper returns the formatted currency string and handles the sign (negated for decrements). See `get_function_doc(\"getOrderAdjustmentFormattedAmount\")`.\n\n## See Also\n- `get_model_guide(\"<TypeName>\")` — one-stop shop for type definition + utility functions + examples\n- `get_type_definition(\"<TypeName>\")` — raw type definition\n- `get_framework_guide(\"common-pitfalls\")` — runtime shape mistakes (point #9 covers `.data`)\n- `get_framework_guide(\"imports\")` — where each type/function comes from",
|
|
215
|
+
"content": "When you declare a prop in `ikas.config.json`, the component receives a specific runtime shape. This table documents what you actually get — which is often different from the editor UI suggests and from naive expectations.\n\n## Reference Table\n\n| PropType | Runtime Shape | Key Access Pattern |\n|----------|---------------|--------------------|\n| `TEXT` | `string` | `props.myText` |\n| `RICH_TEXT` | `string` (HTML) | `<div dangerouslySetInnerHTML={{ __html: props.html }} />` |\n| `NUMBER` | `number` | `props.width` (direct number, NOT `.value`) |\n| `BOOLEAN` | `boolean` | `props.enabled` |\n| `COLOR` | `string` (CSS color) | `style={{ color: props.textColor }}` |\n| `IMAGE` | `IkasImage \\| null` | `getDefaultSrc(props.image)` or `getSrc(props.image, { width: 400 })` |\n| `IMAGE_LIST` | `IkasImageList` | `props.images.map(img => getDefaultSrc(img))` |\n| `VIDEO` | `IkasVideo \\| null` | Check `.url`, `.type` (EMBED vs FILE) |\n| `LINK` | `IkasNavigationLink` | `props.link.href`, `props.link.label`, `props.link.subLinks`, `props.link.openInNewTab` |\n| `LIST_OF_LINK` | `IkasNavigationLinkList` | **`props.links.links`** — access via `.links` property (NOT `.data`) |\n| `PRODUCT` | `IkasProduct \\| null` | `props.product.name`, `.prices`, etc. |\n| `PRODUCT_LIST` | `IkasProductList` | **`props.productList.data`** — array of products via `.data` property |\n| `CATEGORY` | `IkasCategory \\| null` | `props.category.name`, `.href` |\n| `CATEGORY_LIST` | `IkasCategoryList` | Check shape with `get_type_definition(\"IkasCategoryList\")` |\n| `BRAND` / `BRAND_LIST` | `IkasBrand \\| null` / `IkasBrandList` | Use `get_model_guide(\"IkasBrand\")` |\n| `BLOG` / `BLOG_LIST` | `IkasBlog \\| null` / `IkasBlogList` | Blog list uses `.data` |\n| `PRODUCT_ATTRIBUTE` | `IkasProductAttributeValue \\| null` | Direct single value |\n| `PRODUCT_ATTRIBUTE_LIST` | `IkasProductAttributeValue[]` | Plain array (NOT wrapped) |\n| `ENUM` | `string` (the enum value) | Compare directly: `props.type === \"email\"` |\n| `COMPONENT` | `any` | Pass to `<IkasComponentRenderer components={[comp] as any[]} />` |\n| `COMPONENT_LIST` | `any[]` | Pass to `<IkasComponentRenderer components={list as any[]} />` |\n\n## Authored `defaultValue` ≠ runtime read shape (LINK / LIST_OF_LINK)\n\nThe shapes above are what your component RECEIVES (read access: `props.link.href`). They are NOT what you write as a prop `defaultValue` in `ikas.config.json`. The authored default is a typed object:\n- `LINK` → `{ \"linkType\": \"EXTERNAL\", \"label\": \"Shop\", \"externalLink\": \"https://…\", \"subLinks\": [] }` (or `\"linkType\": \"PAGE\"` with `\"pageType\"`).\n- `LIST_OF_LINK` → `{ \"links\": [ <link>, … ] }`.\n\nDo NOT author a default as `{ href, label }` (legacy shape) or as a JSON string — the CLI rejects both. Full reference: `get_framework_guide(\"prop-types\")` → \"LINK and LIST_OF_LINK props\".\n\n## Critical: Inconsistent Access Patterns\n\nThe most common mistakes come from **list-type props having inconsistent access patterns**:\n\n- `PRODUCT_LIST` → `.data` (array of products)\n- `BLOG_LIST` → `.data` (array of blogs)\n- `LIST_OF_LINK` → `.links` (NOT `.data`)\n- `PRODUCT_ATTRIBUTE_LIST` → plain array (no wrapper)\n- `IMAGE_LIST` → plain array via `.data` (check with `get_type_definition`)\n\n**When in doubt, call `get_model_guide(\"IkasProductList\")` etc. for the exact shape.**\n\n## Image Sizing: getDefaultSrc vs getSrc\n\n- `getDefaultSrc(image)` — returns the default-sized URL. Use for small images, thumbnails, or when size doesn't matter.\n- `getSrc(image, { width: 400 })` — returns a URL at a specific width. Use for performance-critical images where you know the rendered size.\n- `createMediaSrcset(image)` — generates a responsive `srcset` string for `<img srcset={...}>`.\n\n**Rule of thumb:** Use `getSrc` with a concrete width for large images; use `getDefaultSrc` for icons/small images.\n\n## Store Data Shapes (cartStore, customerStore, etc.)\n\nStore data is NOT a prop type — you import stores directly from `@ikas/bp-storefront`. Their runtime shapes are:\n\n- `cartStore.cart` → `IkasCart`: `.orderLineItems` is the array; each item has **`.variant`** (not `.product`), `.quantity`, `.totalPrice`\n- `customerStore.customer` → `IkasCustomer | null`: null when logged out, has `.firstName`, `.lastName`, `.email`, `.id`\n- `customerStore.isAuthenticated` → boolean\n\n**For full store shapes, always use `get_model_guide(\"IkasCart\")`, `get_model_guide(\"IkasCustomer\")`, etc. — do not guess.**\n\n## Old → New Runtime Shape Changes\n\nWhen migrating, remember these runtime changes:\n\n- Old `IkasSlider` (with `.value`) → New `number` (plain). Replace `width?.value` with just `width`.\n- Old `<Image>` component (renders itself) → New `getDefaultSrc(image)` + native `<img>`.\n- Old `useStore()` hook → New direct import: `import { cartStore } from '@ikas/bp-storefront'`.\n- Old `IkasAttributeDetail` / `IkasAttributeList` → New `IkasProductAttributeValue` / array.\n\n\n\n## Order Line Item Shapes (cart, order pages)\n\nThese come up when iterating over `IkasCart.orderLineItems` or `IkasOrder.orderLineItems`. They trip up LLMs because the field names don't match scalar intuition:\n\n- **`IkasOrderLineItemOption.values`** — this is an **array** of `IkasOrderLineItemOptionValue`, NOT a scalar `.value`. Iterate it with `.map`:\n\n ```tsx\n // WRONG — there is no .value on IkasOrderLineItemOption\n <span>{option.value}</span>\n\n // RIGHT — .values is an array, each item has its own .name/.value/.formattedPrice\n {option.values.map((v) => (\n <span key={v.name}>{v.name}: {v.value}</span>\n ))}\n ```\n\n- **`IkasOrderAdjustment` has no `.formattedAmount` property.** Call the helper instead: `getOrderAdjustmentFormattedAmount(adjustment)` from `@ikas/bp-storefront`. The helper returns the formatted currency string and handles the sign (negated for decrements). See `get_function_doc(\"getOrderAdjustmentFormattedAmount\")`.\n\n## See Also\n- `get_model_guide(\"<TypeName>\")` — one-stop shop for type definition + utility functions + examples\n- `get_type_definition(\"<TypeName>\")` — raw type definition\n- `get_framework_guide(\"common-pitfalls\")` — runtime shape mistakes (point #9 covers `.data`)\n- `get_framework_guide(\"imports\")` — where each type/function comes from",
|
|
216
216
|
"tags": [
|
|
217
217
|
"migration",
|
|
218
218
|
"runtime",
|
|
@@ -230,7 +230,7 @@
|
|
|
230
230
|
"link-prop-decision-guide": {
|
|
231
231
|
"title": "LINK Prop Decision Guide",
|
|
232
232
|
"description": "When to use LINK, LIST_OF_LINK, LINK with subLinks, or COMPONENT_LIST for link-related data. Addresses common confusion between similar prop types.",
|
|
233
|
-
"content": "Several prop types can represent \"links\" in the new system. Choosing the right one depends on the shape of the data and what the store owner should control.\n\n## Decision Tree\n\n**Is it a single link?**\n→ Use `LINK`. Runtime: `IkasNavigationLink { href, label, subLinks, openInNewTab, ... }`\n\n**Is it a flat list of sibling links (no extra data per link)?**\n→ Use `LIST_OF_LINK`. Runtime: `IkasNavigationLinkList` with `.links: IkasNavigationLink[]`\n\n**Is it a hierarchical menu (links with sub-links, no extra data)?**\n→ Use `LIST_OF_LINK`. Each `IkasNavigationLink` already has `.subLinks: IkasNavigationLink[]`. The editor handles sub-link nesting natively.\n\n**Is it a list of links WITH extra per-link data (image, color, badge, mega-menu content)?**\n→ Use `COMPONENT_LIST` with a child component that has one `LINK` prop + the extra fields.\n\n**Is it a list of products/categories/blogs (not generic links)?**\n→ Use the specific prop type (`PRODUCT_LIST`, `CATEGORY_LIST`, `BLOG_LIST`), NOT `LIST_OF_LINK`.\n\n## Examples\n\n### Footer bottom bar: \"Privacy | Terms | Contact\"\nSimple flat list → `LIST_OF_LINK`:\n```json\n{ \"name\": \"bottomLinks\", \"type\": \"LIST_OF_LINK\" }\n```\nAccess: `props.bottomLinks.links.map(link => <a href={link.href}>{link.label}</a>)`\n\n### Main nav menu with dropdowns: \"Women (→ Tops, Bottoms, Shoes)\"\nHierarchical but just labels + links → `LIST_OF_LINK` (sub-links built-in):\n```json\n{ \"name\": \"menu\", \"type\": \"LIST_OF_LINK\" }\n```\nAccess: `props.menu.links.map(link => (<div>{link.label}{link.subLinks?.map(...)}</div>))`\n\n### Mega menu with images per column\nLinks PLUS image + custom layout per menu item → `COMPONENT_LIST`:\n```json\n// Parent:\n{ \"name\": \"menuItems\", \"type\": \"COMPONENT_LIST\", \"filteredComponentIds\": [\"my-theme-mega-menu-item\"] }\n// Child MegaMenuItem:\n{ \"props\": [\n { \"name\": \"mainLink\", \"type\": \"LINK\" },\n { \"name\": \"columnImage\", \"type\": \"IMAGE\" },\n { \"name\": \"subLinks\", \"type\": \"LIST_OF_LINK\" }\n]}\n```\n\n### Social icons: \"Instagram | Facebook | Twitter\" each with its own icon image\nList of links with an image each → `COMPONENT_LIST`:\n```json\n// Parent:\n{ \"name\": \"socials\", \"type\": \"COMPONENT_LIST\", \"filteredComponentIds\": [\"my-theme-social-link\"] }\n// Child SocialLink:\n{ \"props\": [\n { \"name\": \"link\", \"type\": \"LINK\" },\n { \"name\": \"icon\", \"type\": \"IMAGE\" }\n]}\n```\n\n## Old CUSTOM → Which Link Prop?\n\nWhen migrating an old CUSTOM/DYNAMIC_LIST:\n\n| Old customData shape | New prop |\n|----------------------|----------|\n| `OBJECT { link: LINK }` | `LINK` (flatten) |\n| `DYNAMIC_LIST of OBJECT { link: LINK }` | `LIST_OF_LINK` (if just label+href) or `COMPONENT_LIST` (if more fields) |\n| `DYNAMIC_LIST of OBJECT { link, image }` | `COMPONENT_LIST` + child component |\n| `DYNAMIC_LIST of OBJECT { mainlink, sublinks: LIST_OF_LINK }` | `LIST_OF_LINK` (subLinks are native) |\n| `DYNAMIC_LIST of OBJECT { mainlink, sublinks: DYNAMIC_LIST of OBJECT { links, images, cols } }` | `COMPONENT_LIST` + `MenuItem` child + nested `COMPONENT_LIST` for columns |\n\n## See Also\n- `get_migration_guide(\"prop-runtime-shapes\")` — exact shapes for each link type\n- `get_migration_guide(\"component-renderer-limitations\")` — COMPONENT_LIST constraints\n- `get_framework_guide(\"navigation-patterns\")` — Router.navigate usage, link handling",
|
|
233
|
+
"content": "Several prop types can represent \"links\" in the new system. Choosing the right one depends on the shape of the data and what the store owner should control.\n\n## Decision Tree\n\n**Is it a single link?**\n→ Use `LINK`. Runtime: `IkasNavigationLink { href, label, subLinks, openInNewTab, ... }`\n\n**Is it a flat list of sibling links (no extra data per link)?**\n→ Use `LIST_OF_LINK`. Runtime: `IkasNavigationLinkList` with `.links: IkasNavigationLink[]`\n\n**Is it a hierarchical menu (links with sub-links, no extra data)?**\n→ Use `LIST_OF_LINK`. Each `IkasNavigationLink` already has `.subLinks: IkasNavigationLink[]`. The editor handles sub-link nesting natively.\n\n**Is it a list of links WITH extra per-link data (image, color, badge, mega-menu content)?**\n→ Use `COMPONENT_LIST` with a child component that has one `LINK` prop + the extra fields.\n\n**Is it a list of products/categories/blogs (not generic links)?**\n→ Use the specific prop type (`PRODUCT_LIST`, `CATEGORY_LIST`, `BLOG_LIST`), NOT `LIST_OF_LINK`.\n\n## Examples\n\n### Footer bottom bar: \"Privacy | Terms | Contact\"\nSimple flat list → `LIST_OF_LINK`:\n```json\n{ \"name\": \"bottomLinks\", \"type\": \"LIST_OF_LINK\" }\n```\nAccess: `props.bottomLinks.links.map(link => <a href={link.href}>{link.label}</a>)`\n\n### Main nav menu with dropdowns: \"Women (→ Tops, Bottoms, Shoes)\"\nHierarchical but just labels + links → `LIST_OF_LINK` (sub-links built-in):\n```json\n{ \"name\": \"menu\", \"type\": \"LIST_OF_LINK\" }\n```\nAccess: `props.menu.links.map(link => (<div>{link.label}{link.subLinks?.map(...)}</div>))`\n\n### Mega menu with images per column\nLinks PLUS image + custom layout per menu item → `COMPONENT_LIST`:\n```json\n// Parent:\n{ \"name\": \"menuItems\", \"type\": \"COMPONENT_LIST\", \"filteredComponentIds\": [\"my-theme-mega-menu-item\"] }\n// Child MegaMenuItem:\n{ \"props\": [\n { \"name\": \"mainLink\", \"type\": \"LINK\" },\n { \"name\": \"columnImage\", \"type\": \"IMAGE\" },\n { \"name\": \"subLinks\", \"type\": \"LIST_OF_LINK\" }\n]}\n```\n\n### Social icons: \"Instagram | Facebook | Twitter\" each with its own icon image\nList of links with an image each → `COMPONENT_LIST`:\n```json\n// Parent:\n{ \"name\": \"socials\", \"type\": \"COMPONENT_LIST\", \"filteredComponentIds\": [\"my-theme-social-link\"] }\n// Child SocialLink:\n{ \"props\": [\n { \"name\": \"link\", \"type\": \"LINK\" },\n { \"name\": \"icon\", \"type\": \"IMAGE\" }\n]}\n```\n\n## Old CUSTOM → Which Link Prop?\n\nWhen migrating an old CUSTOM/DYNAMIC_LIST:\n\n| Old customData shape | New prop |\n|----------------------|----------|\n| `OBJECT { link: LINK }` | `LINK` (flatten) |\n| `DYNAMIC_LIST of OBJECT { link: LINK }` | `LIST_OF_LINK` (if just label+href) or `COMPONENT_LIST` (if more fields) |\n| `DYNAMIC_LIST of OBJECT { link, image }` | `COMPONENT_LIST` + child component |\n| `DYNAMIC_LIST of OBJECT { mainlink, sublinks: LIST_OF_LINK }` | `LIST_OF_LINK` (subLinks are native) |\n| `DYNAMIC_LIST of OBJECT { mainlink, sublinks: DYNAMIC_LIST of OBJECT { links, images, cols } }` | `COMPONENT_LIST` + `MenuItem` child + nested `COMPONENT_LIST` for columns |\n\n## Authoring the default value (config shape)\n\nWhichever type you pick, the `defaultValue` in `ikas.config.json` is the typed object — NOT the runtime `.href` read shape, and NOT a JSON string:\n- `LINK` → `{ \"linkType\": \"EXTERNAL\", \"label\": \"Shop\", \"externalLink\": \"https://…\", \"subLinks\": [] }` (or `\"linkType\": \"PAGE\"` + `\"pageType\"`; `\"FILE\"` + `\"fileUrl\"`).\n- `LIST_OF_LINK` → `{ \"links\": [ { \"linkType\": \"PAGE\", \"label\": \"Home\", \"pageType\": \"INDEX\", \"subLinks\": [] } ] }`.\n\nThe legacy `{ label, href }` shape is rejected by the CLI. Full reference: `get_framework_guide(\"prop-types\")` → \"LINK and LIST_OF_LINK props\".\n\n## See Also\n- `get_migration_guide(\"component-composition-decision-guide\")` — when COMPONENT_LIST is overkill vs. repeated scalars vs. domain LIST types\n- `get_migration_guide(\"prop-runtime-shapes\")` — exact shapes for each link type\n- `get_migration_guide(\"component-renderer-limitations\")` — COMPONENT_LIST constraints\n- `get_framework_guide(\"navigation-patterns\")` — Router.navigate usage, link handling",
|
|
234
234
|
"tags": [
|
|
235
235
|
"migration",
|
|
236
236
|
"LINK",
|
|
@@ -241,6 +241,20 @@
|
|
|
241
241
|
"decision",
|
|
242
242
|
"COMPONENT_LIST"
|
|
243
243
|
]
|
|
244
|
+
},
|
|
245
|
+
"component-composition-decision-guide": {
|
|
246
|
+
"title": "When to Use COMPONENT / COMPONENT_LIST (Composition Decision Guide)",
|
|
247
|
+
"description": "Decision tree for choosing between scalar props, domain LIST types, and COMPONENT/COMPONENT_LIST. Applies to both greenfield component design and migration callouts.",
|
|
248
|
+
"content": "Default to the simplest prop shape that fits. Reach for `COMPONENT` / `COMPONENT_LIST` only when each item is a multi-field unit AND the count is dynamic. Over-used child components make themes harder to author.\n\n## Decision Tree (pick the first that matches)\n\n1. **Toggling whether to show optional pieces inside a section?** → `BOOLEAN` props on the parent (`showPrice`, `showVariants`). Do NOT wrap near-empty children in `COMPONENT_LIST` just to flip visibility.\n2. **Fixed, small count (≤4) of items, same shape?** → repeated scalar props on the parent (`title1`/`link1`, `title2`/`link2`, …).\n3. **Dynamic list where each item IS one domain object** (link, image, product, category, brand, blog, blog category, raffle)? → matching domain LIST prop type: `LIST_OF_LINK`, `IMAGE_LIST`, `PRODUCT_LIST`, `CATEGORY_LIST`, `BRAND_LIST`, `BLOG_LIST`, `BLOG_CATEGORY_LIST`, `RAFFLE_LIST`. No child component needed.\n4. **Dynamic list AND each item is a structured record (≥3 fields, or mixed types like image+text+link+color)?** → `COMPONENT_LIST` with a dedicated child.\n5. **Exactly one structured child, not a list?** → `COMPONENT` with one child.\n\n## Sizing Rule\n\n- Child would have **0–2 props** → almost never `COMPONENT_LIST`. Use Branch 1, 2, or 3.\n- Child would have **3–4 props** → `COMPONENT_LIST` is acceptable; check whether scalars or a domain LIST type covers it first.\n- Child would have **5+ props OR mixed prop types** → `COMPONENT_LIST` is correct.\n\n## Anti-Patterns\n\n- List of items where each item is one text field → repeated `TEXT` props.\n- Wrapping 2–3 leaf \"display card\" components purely to toggle visibility → `BOOLEAN` props.\n- List of `{icon, link}` items → `LIST_OF_LINK` (icon derivable from link) or repeated scalars.\n\n## Sanity Check Before You Commit to `COMPONENT_LIST`\n\nAll three should hold:\n- Each child meaningfully renders its own content (its own CSS, handlers, layout).\n- Reordering items in the editor is a real UX win for the store owner.\n- The same child is reusable in multiple parents (or could be).\n\n## Migration Carve-Out\n\nThe Feature-Parity Rule still applies — do NOT silently drop fields. But if an old `customData` has only **1–2 fields**, prefer flattening to scalar props on the parent and log it under `## Custom Data Decisions` in `MIGRATION.md`. An explicit, logged 1–2-field flatten is fine; silent simplification is not. For ≥3-field records, build the component.\n\n## See Also\n\n- `get_migration_guide(\"custom-data-conversion\")` — Feature-Parity Rule + worked ≥3-field examples\n- `get_migration_guide(\"link-prop-decision-guide\")` — link-shaped data specifically\n- `get_prop_types` — full prop type reference including all domain LIST types\n",
|
|
249
|
+
"tags": [
|
|
250
|
+
"composition",
|
|
251
|
+
"COMPONENT_LIST",
|
|
252
|
+
"COMPONENT",
|
|
253
|
+
"decision-guide",
|
|
254
|
+
"greenfield",
|
|
255
|
+
"migration",
|
|
256
|
+
"simplicity"
|
|
257
|
+
]
|
|
244
258
|
}
|
|
245
259
|
}
|
|
246
260
|
}
|