@ikas/code-components-mcp 0.15.0

package/data/framework.json

@@ -0,0 +1,134 @@
+{
+  "generatedAt": "2025-01-01T00:00:00.000Z",
+  "topics": {
+    "project-structure": {
+      "title": "Project Structure",
+      "description": "How an ikas code components project is organized",
+      "content": "An ikas code components project follows this structure:\n\n```\nmy-project/\n\u251c\u2500\u2500 src/\n\u2502   \u2514\u2500\u2500 components/\n\u2502       \u251c\u2500\u2500 MyComponent/\n\u2502       \u2502   \u251c\u2500\u2500 index.tsx      # Component implementation (Preact)\n\u2502       \u2502   \u251c\u2500\u2500 types.ts       # TypeScript props interface\n\u2502       \u2502   \u2514\u2500\u2500 styles.css     # Scoped component styles\n\u2502       \u2514\u2500\u2500 index.ts           # Component exports barrel\n\u251c\u2500\u2500 ikas.config.json           # Component definitions, props, metadata\n\u251c\u2500\u2500 package.json\n\u251c\u2500\u2500 tsconfig.json\n\u2514\u2500\u2500 vite.config.ts\n```\n\nEach component lives in its own directory under `src/components/`. The component's entry point is `index.tsx`, which exports a default Preact function component. The `types.ts` file defines the props interface matching the props declared in `ikas.config.json`. The `styles.css` file contains CSS that is automatically scoped to the component.",
+      "tags": [
+        "structure",
+        "project",
+        "directory",
+        "files",
+        "layout"
+      ]
+    },
+    "ikas-config": {
+      "title": "ikas.config.json Schema",
+      "description": "Configuration file that defines components, their props, and metadata",
+      "content": "The `ikas.config.json` file is the central configuration for your code components project.\n\n```json\n{\n  \"name\": \"my-project\",\n  \"version\": \"1.0.0\",\n  \"components\": [\n    {\n      \"id\": \"my-component\",\n      \"name\": \"My Component\",\n      \"entry\": \"./src/components/MyComponent/index.tsx\",\n      \"styles\": \"./src/components/MyComponent/styles.css\",\n      \"props\": [\n        {\n          \"name\": \"title\",\n          \"displayName\": \"Title\",\n          \"type\": \"TEXT\",\n          \"required\": true,\n          \"defaultValue\": \"Hello\",\n          \"description\": \"The main heading text\"\n        }\n      ]\n    },\n    {\n      \"id\": \"hero-banner\",\n      \"name\": \"Hero Banner\",\n      \"type\": \"section\",\n      \"entry\": \"./src/components/HeroBanner/index.tsx\",\n      \"styles\": \"./src/components/HeroBanner/styles.css\",\n      \"props\": [\n        {\n          \"name\": \"heading\",\n          \"displayName\": \"Heading\",\n          \"type\": \"TEXT\",\n          \"required\": true,\n          \"defaultValue\": \"Welcome\"\n        }\n      ]\n    }\n  ]\n}\n```\n\n### Top-level fields:\n- `name` (string): Project name\n- `version` (string): Project version\n- `components` (array): List of component definitions\n\n### Component fields:\n- `id` (string): Unique identifier (kebab-case)\n- `name` (string): Display name in the editor\n- `type` (string, optional): `\"component\"` (default) or `\"section\"` \u2014 sections are page-level containers (e.g. header, hero banner, footer), components are child elements placed inside sections (e.g. button, card, badge)\n- `entry` (string): Path to the component's entry file (index.tsx)\n- `styles` (string): Path to the component's CSS file\n- `props` (array): List of prop definitions\n\n### Prop fields:\n- `name` (string): Prop name used in code (camelCase)\n- `displayName` (string): Label shown in the editor UI\n- `type` (string): One of the available prop types\n- `required` (boolean): Whether the prop must be set\n- `defaultValue` (any): Default value matching the prop type\n- `description` (string): Help text shown in editor\n- `options` (array, SELECT only): Array of `{ label, value }` for SELECT type",
+      "tags": [
+        "config",
+        "configuration",
+        "ikas.config",
+        "props",
+        "schema",
+        "components"
+      ]
+    },
+    "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| `NUMBER` | Number input | `number` | Numeric value |\n| `BOOLEAN` | Toggle switch | `boolean` | True/false toggle |\n| `IMAGE` | Image picker | `{ src: string; alt?: string }` | Image with upload/URL |\n| `LINK` | Link editor | `{ href: string; label?: string; target?: string }` | URL link |\n| `LIST_OF_LINK` | Link list editor | `IkasNavigationLinkList` | List of navigation links |\n| `COLOR` | Color picker | `string` | CSS color value (hex, rgb, etc.) |\n| `SELECT` | Dropdown | `string` | Single selection from options list |\n| `PRODUCT` | Product picker | `IkasProduct` | Single product reference |\n| `PRODUCT_LIST` | Product list picker | `IkasProduct[]` | Multiple product references |\n| `CATEGORY` | Category picker | `IkasCategory` | Single category reference |\n| `CATEGORY_LIST` | Category list picker | `IkasCategory[]` | Multiple category references |\n| `BRAND` | Brand picker | `IkasBrand` | Single brand reference |\n| `BRAND_LIST` | Brand list picker | `IkasBrand[]` | Multiple brand references |\n| `BLOG_POST` | Blog post picker | `IkasBlogPost` | Single blog post reference |\n| `BLOG_POST_LIST` | Blog post list picker | `IkasBlogPost[]` | Multiple blog post references |\n| `FONT_STYLE_TYPE` | Font style editor | `IkasFontStyle` | Font family, size, weight, etc. |\n\n### SELECT type example:\n```json\n{\n  \"name\": \"layout\",\n  \"displayName\": \"Layout\",\n  \"type\": \"SELECT\",\n  \"options\": [\n    { \"label\": \"Grid\", \"value\": \"grid\" },\n    { \"label\": \"List\", \"value\": \"list\" }\n  ],\n  \"defaultValue\": \"grid\"\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: `props.heroImage?.src`",
+      "tags": [
+        "props",
+        "types",
+        "TEXT",
+        "NUMBER",
+        "BOOLEAN",
+        "IMAGE",
+        "LINK",
+        "LIST_OF_LINK",
+        "COLOR",
+        "SELECT",
+        "PRODUCT",
+        "CATEGORY",
+        "BRAND",
+        "BLOG_POST",
+        "FONT_STYLE_TYPE"
+      ]
+    },
+    "component-structure": {
+      "title": "Component Structure",
+      "description": "How to write a Preact component for ikas",
+      "content": "Each component consists of three files. There are two patterns: **components** (child elements) and **sections** (page-level containers).\n\n## Component Pattern (child elements like buttons, cards, badges)\n\n### index.tsx - Component Implementation\n```tsx\nimport { Props } from \"./types\";\n\nexport default function MyComponent({ title, showButton }: Props) {\n  return (\n    <div className=\"my-component\">\n      <h1>{title}</h1>\n      {showButton && <button>Click me</button>}\n    </div>\n  );\n}\n```\n\n### types.ts - Props Interface\n```typescript\nexport interface Props {\n  title: string;          // TEXT prop -> string\n  showButton?: boolean;   // optional BOOLEAN prop\n  count: number;          // NUMBER prop -> number\n}\n```\n\n### styles.css\n```css\n.my-component {\n  padding: 16px;\n}\n\n.my-component h1 {\n  font-size: 24px;\n}\n```\n\n## Section Pattern (page-level containers like headers, hero banners, footers)\n\nSections use a `<section>` root element, full-width styling, and a `Props` interface. In `ikas.config.json` they have `\"type\": \"section\"`.\n\n### index.tsx - Section Implementation\n```tsx\nimport { Props } from \"./types\";\n\nexport default function HeroBanner({ heading, subtitle, backgroundColor }: Props) {\n  return (\n    <section className=\"hero-banner\" style={backgroundColor ? { backgroundColor } : undefined}>\n      <div className=\"hero-banner-inner\">\n        <h2>{heading}</h2>\n        {subtitle && <p>{subtitle}</p>}\n      </div>\n    </section>\n  );\n}\n```\n\n### types.ts - Section Props Interface\n```typescript\nexport interface Props {\n  heading: string;\n  subtitle?: string;\n  backgroundColor?: string;\n}\n```\n\n### styles.css - Full-width section styles\n```css\n.hero-banner {\n  width: 100%;\n  padding: 64px 24px;\n}\n\n.hero-banner-inner {\n  max-width: 1200px;\n  margin: 0 auto;\n}\n```\n\n## Key Rules\n- Export the component as `default export`\n- Use Preact (not React) - but JSX syntax is the same\n- Import types from `./types` for props\n- Use `className` not `class` for CSS classes\n- Storefront functions and types come from `@ikas/bp-storefront`\n- CSS classes are automatically scoped to your component at build time. Use plain CSS class selectors - they won't conflict with other components or the page.",
+      "tags": [
+        "component",
+        "preact",
+        "tsx",
+        "types",
+        "css",
+        "structure",
+        "implementation"
+      ]
+    },
+    "build-system": {
+      "title": "Build System",
+      "description": "How components are built and bundled",
+      "content": "The build system uses Vite + esbuild to compile components.\n\n### Development\n```bash\nnpm run dev\n```\nStarts a dev server that:\n- Watches for file changes\n- Compiles components on the fly\n- Communicates with the ikas editor via WebSocket\n- Provides live updates in the editor preview\n\n### Production Build\n```bash\nnpm run build\n```\nBuilds optimized bundles:\n- Creates separate server and client bundles\n- Server bundle: used for SSR (no browser APIs)\n- Client bundle: used for hydration and interactivity\n- CSS is extracted and scoped per component\n- Tree-shakes unused code\n\n### What happens during build:\n1. TypeScript is compiled to JavaScript\n2. JSX is transformed (Preact's h function)\n3. CSS is scoped with unique prefixes\n4. Code is bundled per-component\n5. Externals (`preact`, `@ikas/component-utils`) are not bundled\n\n### Publishing\n```bash\nnpm run publish\n```\nUploads the built components to the ikas platform.",
+      "tags": [
+        "build",
+        "vite",
+        "esbuild",
+        "dev",
+        "production",
+        "bundle",
+        "compile",
+        "publish"
+      ]
+    },
+    "css-scoping": {
+      "title": "CSS Scoping Rules",
+      "description": "How CSS is scoped to prevent conflicts between components",
+      "content": "CSS files referenced in `ikas.config.json` are automatically scoped at build time.\n\n### How it works:\n- Each component's CSS selectors are prefixed with a unique scope identifier\n- `.my-class` becomes `.[scope]-my-class` in the output\n- This prevents style conflicts between different components on the same page\n\n### Best practices:\n- Use class selectors (`.my-class`) rather than element selectors (`div`, `h1`)\n- Avoid using `!important` - scoping handles isolation\n- Don't use global selectors or `@global` - they won't be scoped\n- Keep CSS in the component's `styles.css` file referenced in config\n- Nested selectors work: `.parent .child` both get scoped\n\n### Example:\n```css\n/* What you write */\n.product-card {\n  padding: 16px;\n  border: 1px solid #eee;\n}\n\n.product-card .title {\n  font-size: 18px;\n  font-weight: bold;\n}\n\n.product-card .price {\n  color: #e53e3e;\n}\n```\n\nThe build system transforms this so your `.product-card`, `.title`, and `.price` classes are unique to your component and won't clash with any other component or theme styles.",
+      "tags": [
+        "css",
+        "scoping",
+        "styles",
+        "isolation",
+        "classes"
+      ]
+    },
+    "dev-server": {
+      "title": "Dev Server Usage",
+      "description": "How to use the development server with the ikas editor",
+      "content": "The dev server enables live development with the ikas editor.\n\n### Starting the dev server:\n```bash\nnpm run dev\n```\n\nThis starts a local server (default port 3000) that:\n1. Compiles your components\n2. Opens a WebSocket connection for live reload\n3. Watches file changes and recompiles automatically\n\n### Connecting to the editor:\n1. Open the ikas editor (editor.ikas.com)\n2. Go to your store's theme editor\n3. Open the \"Dev Components\" panel\n4. Enter your dev server URL (e.g., `http://localhost:3000`)\n5. Your components will appear in the component picker\n\n### Development workflow:\n1. Start dev server with `npm run dev`\n2. Connect the editor to your dev server\n3. Add/modify components in your code\n4. Changes appear automatically in the editor\n5. Use the editor to configure prop values and preview\n\n### Adding a new component:\n```bash\nnpm run add\n```\nThis interactive command:\n- Asks for component name\n- Creates the component directory and files\n- Updates `ikas.config.json` with the new component entry",
+      "tags": [
+        "dev",
+        "server",
+        "development",
+        "editor",
+        "live-reload",
+        "websocket",
+        "workflow"
+      ]
+    },
+    "imports": {
+      "title": "Import Patterns",
+      "description": "How to import storefront functions and types",
+      "content": "### Storefront Functions & Types\nImport API functions and TypeScript types from `@ikas/bp-storefront`:\n```typescript\nimport {\n  // Product functions\n  getSelectedProductVariant,\n  getDisplayedProductVariantTypes,\n  selectVariantValue,\n  hasProductVariantStock,\n  getProductVariantFormattedFinalPrice,\n  \n  // Cart functions\n  addItemToCart,\n  cartStore,\n  \n  // Navigation\n  Router,\n  \n  // Customer\n  customerStore,\n  customerLogin,\n  hasCustomer,\n  \n  // Favorites\n  addIkasProductToFavorites,\n  isFavoriteIkasProduct,\n\n  // Type models\n  IkasProduct,\n  IkasProductVariant,\n  IkasCart,\n  IkasOrderLineItem,\n  IkasCustomer,\n  IkasOrder,\n  IkasCategory,\n  IkasBrand,\n  IkasBlogPost\n} from \"@ikas/bp-storefront\";\n```\n\n### Store Instances\nPre-initialized MobX stores:\n```typescript\nimport { cartStore, customerStore } from \"@ikas/bp-storefront\";\n\n// Cart data\ncartStore.cart?.orderLineItems\n\n// Customer data  \ncustomerStore.customer?.email\n```\n\n### Observer (for reactive updates)\n```typescript\nimport { observer } from \"@ikas/component-utils\";\n\nconst MyComponent = observer(function MyComponent(props: Props) {\n  // Component re-renders when observed store data changes\n  const itemCount = cartStore.cart?.orderLineItems.length ?? 0;\n  return <span>Cart: {itemCount}</span>;\n});\n\nexport default MyComponent;\n```\n\nWrap components with `observer()` when they read from stores (`cartStore`, `customerStore`) to get automatic re-renders on data changes.",
+      "tags": [
+        "import",
+        "storefront",
+        "models",
+        "types",
+        "observer",
+        "stores"
+      ]
+    },
+    "sections-vs-components": {
+      "title": "Sections vs Components",
+      "description": "The difference between sections (page-level containers) and components (child elements)",
+      "content": "ikas code components have two types: **sections** and **components**.\n\n## Sections\nSections are page-level, full-width containers that make up the structure of a page. Examples: Header, Hero Banner, Footer, Product Grid, Featured Collection.\n\n- Set `\"type\": \"section\"` in `ikas.config.json`\n- Use a `<section>` root element with full-width styling\n- Name the props interface `Props` in `types.ts`\n- Typically have full-width layout with inner max-width container\n- Styles: `width: 100%; padding: 64px 24px;` with `.inner { max-width: 1200px; margin: 0 auto; }`\n\n## Components\nComponents are child elements that are placed inside sections. Examples: Button, Product Card, Badge, Price Display, Image Gallery.\n\n- No `type` field needed in `ikas.config.json` (defaults to `\"component\"`)\n- Use a `<div>` root element\n- Name the props interface `Props` in `types.ts`\n- Sized by their content or parent container\n\n## Config Difference\nThe only config difference is the `type` field on the component definition:\n\n```json\n{\n  \"components\": [\n    {\n      \"id\": \"product-card\",\n      \"name\": \"Product Card\",\n      \"entry\": \"./src/components/ProductCard/index.tsx\",\n      \"styles\": \"./src/components/ProductCard/styles.css\",\n      \"props\": []\n    },\n    {\n      \"id\": \"hero-banner\",\n      \"name\": \"Hero Banner\",\n      \"type\": \"section\",\n      \"entry\": \"./src/components/HeroBanner/index.tsx\",\n      \"styles\": \"./src/components/HeroBanner/styles.css\",\n      \"props\": []\n    }\n  ]\n}\n```\n\n## How to Decide\n- Will it span the full width of the page and sit at the top level? \u2192 **Section**\n- Will it be placed inside another container or repeated in a list? \u2192 **Component**",
+      "tags": [
+        "section",
+        "component",
+        "type",
+        "page-level",
+        "container",
+        "child",
+        "structure"
+      ]
+    }
+  }
+}