@ikas/component-cli 0.83.0 → 0.85.0

package/templates/create/README.md

@@ -0,0 +1,50 @@
+# {{PROJECT_NAME}}
+
+An ikas code components project.
+
+## Getting Started
+
+1. Install dependencies:
+   ```bash
+   npm install
+   ```
+
+2. Start the development server:
+   ```bash
+   npm run dev
+   ```
+
+3. Open the ikas editor and connect to the dev server from the Dev Components panel.
+
+## Commands
+
+- `npm run dev` - Start development server with live editor updates
+- `npm run build` - Build components for production
+- `npm run add` - Add a new component to the project
+
+## Project Structure
+
+```
+{{PROJECT_NAME}}/
+├── src/
+│   ├── components/
+│   │   ├── ExampleComponent/  # A child component (type: "component")
+│   │   │   ├── index.tsx
+│   │   │   ├── styles.css
+│   │   │   └── types.ts
+│   │   ├── ExampleSection/    # A page-level section (type: "section")
+│   │   │   ├── index.tsx
+│   │   │   ├── styles.css
+│   │   │   └── types.ts
+│   │   └── index.ts
+│   ├── global.css             # Unscoped global styles
+│   └── global-types.ts        # Auto-generated shared enum types
+├── ikas.config.json
+├── package.json
+├── tsconfig.json
+└── vite.config.ts
+```
+
+## Building for Production
+
+Run `npm run build` to compile your components. The output will be ready to upload to the ikas editor.

package/templates/create/cursorrules

@@ -0,0 +1,108 @@
+# ikas Code Components
+
+You are building **Preact + TypeScript components for an e-commerce storefront**.
+**ALWAYS query MCP tools before writing code that uses storefront APIs.**
+
+## CRITICAL: Auto-Generated Files
+
+**NEVER manually create or edit `types.ts` or `global-types.ts`** — they are auto-generated by CLI commands.
+Use `npx ikas-component config add-component --props '[...]'` or `npx ikas-component config add-prop` to manage props.
+These commands update `ikas.config.json`, `types.ts`, and `global-types.ts` automatically.
+
+## MCP Tools (12 tools)
+
+### Starting a New Section
+- get_section_template(sectionType) — **Start here** — production-ready starter template for common sections (header, footer, product-detail, product-list, cart, login, hero-banner, blog-post, faq, etc.)
+- get_framework_guide(topic) — Framework docs ("ai-workflow", "common-pitfalls", "prop-types", "css-scoping", "form-handling", "imports")
+- get_code_example(task) — Code examples ("add to cart", "variant selection", "image-handling")
+
+### Looking Up APIs
+- search_docs(query) — Search all storefront API docs and framework guides
+- get_function_doc(name) — Full docs for a function (e.g. "addItemToCart", "Router.navigate")
+- list_functions(category?) — List functions by category (ProductDetail, Cart, ProductList, Navigation, Customer, Order, Image, Blog, Brand, Pricing, Form, Validation, Pagination, Filtering)
+- get_prop_types() — All available ikas.config.json prop types
+
+### Exploring Types
+- get_model_guide(model) — **One-stop-shop** — type def + utility functions + examples for a model (e.g. "IkasProduct", "IkasOrder")
+- get_type_definition(name) — Full definition of a type or enum
+- get_functions_for_type(typeName) — All utility functions for a type
+- search_types(query) — Search types/enums by keyword ("price", "address", "status")
+- list_types(domain?, kind?) — List all types, filter by domain or kind ("type"/"enum")
+
+## CLI Commands (never edit ikas.config.json or types.ts manually)
+- npx ikas-component config add-component --name "Name" --type section --props '[...]' — **Primary** — create with all props in one command
+- npx ikas-component config add-component --name "Name" --type section — Create component with no props
+- npx ikas-component config add-prop --component "Name" --name title --displayName "Title" --type TEXT --required [--group content] — Add a prop incrementally
+- npx ikas-component config update-prop --component "Name" --prop title --type RICH_TEXT [--group colors] — Update a prop or group
+- npx ikas-component config remove-prop --component "Name" --prop title — Remove a prop
+- npx ikas-component config remove-component --name "Name" — Remove a component
+- npx ikas-component config add-prop-group --component "Name" --id colors --name "Colors" [--parent style] — Create a prop group
+- npx ikas-component config update-prop-group --component "Name" --id colors [--name "..."] — Update a prop group
+- npx ikas-component config remove-prop-group --component "Name" --id colors — Remove a prop group
+- npx ikas-component config list — List all components and their props
+- npx ikas-component check --json — Type-check all components
+- npx ikas-component build — Compile server.js + client.js + styles.css per component
+- npx ikas-component dev — Start dev server (Vite 5200 + WebSocket 5201)
+
+## Workflow: Building a New Section
+1. get_section_template("product-detail") → get starter files + CLI command with --props
+2. Run the CLI command (creates component + props + types.ts in one step)
+3. Write index.tsx and styles.css using the template (do NOT edit types.ts — it's already generated)
+4. Look up APIs: get_model_guide("IkasProduct"), get_function_doc("addItemToCart")
+5. npx ikas-component check --json → fix type errors
+6. npx ikas-component build → verify clean build
+
+## Sub-Component Structure
+**ALWAYS create sub-components in `src/sub-components/` with their own folder containing `index.tsx` and `styles.css`.**
+- `src/components/` = registered in ikas.config.json. `src/sub-components/` = internal helpers (NOT in ikas.config.json)
+- Sub-components do NOT have `types.ts` — define `Props` inline in `index.tsx`
+- Custom enum types are exported from `src/global-types.ts` (auto-generated). Sub-components can import them: `import type { MyEnum } from "../../global-types";`
+- CSS: `@import "../../sub-components/ProductCard/styles.css";` in parent styles.css
+- TSX: `import ProductCard from "../../sub-components/ProductCard";`
+- Sub-components that read MobX stores need `observer()`, others don't
+- Sub-components can be shared across multiple parent sections
+- NEVER create flat .tsx files inside a component folder
+
+## Key Patterns
+- Root components are automatically reactive (ikas runtime uses autorun). Do NOT use observer() on root exports.
+  Pattern: `export function MySection({ title }: Props) { ... }` + `export default MySection;`
+  Only use observer() on extracted sub-components that independently read MobX stores.
+- Null safety: storefront models can be null — always check before accessing
+- Mutations: addItemToCart() etc. mutate MobX observables in-place — no return capture needed
+- COMPONENT & COMPONENT_LIST props: slot-based child components rendered via `<IkasComponentRenderer>`
+  `import { IkasComponentRenderer } from "@ikas/bp-storefront"`
+  `<IkasComponentRenderer components={myList as any[]} parentProps={props} />`
+  Always pass `parentProps={props}` so children can access parent data. Cast with `as any[]`.
+- CSS: write plain class names — auto-scoped with .cc_{componentId} at build time
+- Events: use onInput (not onChange) for text inputs (Preact behavior)
+- Imports: `import { addItemToCart, IkasProduct } from "@ikas/bp-storefront"`
+
+## No Static Text Rule
+**CRITICAL: Never hardcode user-visible text in JSX.** All text strings (headings, button labels,
+empty states, loading messages, form labels) MUST be TEXT props with defaultValues.
+Wrong: `<h1>Sign In</h1>`
+Correct: `<h1>{title}</h1>` with `title` as TEXT prop (defaultValue: "Sign In")
+For button loading states, use two separate props (e.g., `submitButtonText` + `submittingButtonText`).
+Group text props under a "Texts" propGroup when the component has 5+ props.
+
+## Sections vs Components
+- Sections = page-level containers (Header, Hero, Product Grid, Footer)
+  Set "type": "section" via CLI. Use <section> root element. Props interface: Props.
+  **Sections MUST always include a `backgroundColor` COLOR prop** (default: `#ffffff`).
+  Apply via inline style: `style={backgroundColor ? { backgroundColor } : undefined}`
+  Consider also adding `textColor` COLOR props for text elements directly on the section background.
+- Components = child elements inside sections (buttons, cards, badges)
+  Defaults to "component". Use <div> root element. Props interface: Props.
+
+## Prop Groups
+Organize 5+ props into collapsible groups in editor sidebar.
+- Define groups in `propGroups` on component in ikas.config.json
+- Assign props via `groupId` on each prop
+- Nest 1 level deep with `children`
+- Group IDs must be unique within a component
+- CLI: add-prop-group, update-prop-group, remove-prop-group
+- Add prop to group: add-prop --group <groupId> or update-prop --group <groupId>
+
+## Build Verification
+IMPORTANT: After completing any task, always run `npx ikas-component build` (or `npm run build`)
+to check for TypeScript and build errors. Fix any errors before considering the task done.

package/templates/create/gitignore

@@ -0,0 +1,5 @@
+node_modules/
+dist/
+.DS_Store
+*.log
+asd

package/templates/create/ikas.config.json

@@ -0,0 +1,95 @@
+{
+  "name": "{{PROJECT_NAME}}",
+  "version": "1.0.0",
+  "projectId": "{{PROJECT_ID}}",
+  "globalStyles": "./src/global.css",
+  "components": [
+    {
+      "id": "{{EXAMPLE_COMPONENT_ID}}",
+      "name": "Example Component",
+      "entry": "./src/components/ExampleComponent/index.tsx",
+      "styles": "./src/components/ExampleComponent/styles.css",
+      "props": [
+        {
+          "name": "title",
+          "displayName": "Title",
+          "type": "TEXT",
+          "required": true,
+          "defaultValue": "Hello World",
+          "description": "The main title text"
+        },
+        {
+          "name": "description",
+          "displayName": "Description",
+          "type": "TEXT",
+          "required": false,
+          "defaultValue": "This is an example ikas code component built with Preact.",
+          "description": "The description text below the title"
+        },
+        {
+          "name": "showButton",
+          "displayName": "Show Button",
+          "type": "BOOLEAN",
+          "required": false,
+          "defaultValue": true,
+          "description": "Whether to show the action button"
+        },
+        {
+          "name": "buttonText",
+          "displayName": "Button Text",
+          "type": "TEXT",
+          "required": false,
+          "defaultValue": "Click Me",
+          "description": "The text displayed on the button"
+        }
+      ]
+    },
+    {
+      "id": "{{EXAMPLE_SECTION_ID}}",
+      "name": "Example Section",
+      "entry": "./src/components/ExampleSection/index.tsx",
+      "styles": "./src/components/ExampleSection/styles.css",
+      "type": "section",
+      "props": [
+        {
+          "name": "heading",
+          "displayName": "Heading",
+          "type": "TEXT",
+          "required": true,
+          "defaultValue": "Welcome to Our Store",
+          "description": "The section heading text",
+          "groupId": "content"
+        },
+        {
+          "name": "subtitle",
+          "displayName": "Subtitle",
+          "type": "TEXT",
+          "required": false,
+          "defaultValue": "Discover our latest products and collections.",
+          "description": "The subtitle text below the heading",
+          "groupId": "content"
+        },
+        {
+          "name": "backgroundColor",
+          "displayName": "Background Color",
+          "type": "COLOR",
+          "required": false,
+          "description": "The section background color",
+          "groupId": "appearance"
+        }
+      ],
+      "propGroups": [
+        {
+          "id": "content",
+          "name": "Content",
+          "description": "Text and copy settings"
+        },
+        {
+          "id": "appearance",
+          "name": "Appearance",
+          "description": "Colors and visual style"
+        }
+      ]
+    }
+  ]
+}

package/templates/create/mcp.json

@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "ikas-code-components": {
+      "command": "npx",
+      "args": [
+        "ikas-mcp"
+      ]
+    }
+  }
+}

package/templates/create/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "{{PROJECT_NAME}}",
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "ikas-component dev",
+    "build": "ikas-component build",
+    "add": "ikas-component add",
+    "publish": "ikas-component publish"
+  },
+  "dependencies": {
+    "preact": "^10.19.3"
+  },
+  "devDependencies": {
+    "@ikas/component-cli": "*",
+    "@ikas/bp-storefront": "*",
+    "@ikas/code-components-mcp": "*",
+    "typescript": "^5.3.0",
+    "vite": "^5.0.0"
+  }
+}

package/templates/create/src/components/ExampleComponent/index.tsx

@@ -0,0 +1,22 @@
+import { Props } from "./types";
+
+export function ExampleComponent({
+  title,
+  description = "This is an example ikas code component built with Preact.",
+  showButton,
+  buttonText = "Click Me",
+}: Props) {
+  return (
+    <div className="example-component">
+      <h1 className="example-title">{title}</h1>
+      <p className="example-description">{description}</p>
+      {showButton && (
+        <button className="example-button">
+          {buttonText}
+        </button>
+      )}
+    </div>
+  );
+}
+
+export default ExampleComponent;

package/templates/create/src/components/ExampleComponent/styles.css

@@ -0,0 +1,36 @@
+.example-component {
+  padding: 24px;
+  border-radius: 8px;
+  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+  color: white;
+  font-family: system-ui, -apple-system, sans-serif;
+}
+
+.example-title {
+  margin: 0 0 12px 0;
+  font-size: 28px;
+  font-weight: 700;
+}
+
+.example-description {
+  margin: 0 0 20px 0;
+  font-size: 16px;
+  opacity: 0.9;
+}
+
+.example-button {
+  padding: 12px 24px;
+  border: none;
+  border-radius: 6px;
+  background: white;
+  color: #667eea;
+  font-size: 16px;
+  font-weight: 600;
+  cursor: pointer;
+  transition: transform 0.2s, box-shadow 0.2s;
+}
+
+.example-button:hover {
+  transform: translateY(-2px);
+  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.2);
+}

package/templates/create/src/components/ExampleComponent/types.ts

@@ -0,0 +1,7 @@
+// Auto-generated types based on ikas.config.json props
+export interface Props {
+  title: string;
+  description?: string;
+  showButton?: boolean;
+  buttonText?: string;
+}

package/templates/create/src/components/ExampleSection/index.tsx

@@ -0,0 +1,14 @@
+import { Props } from "./types";
+
+export function ExampleSection({ heading, subtitle, backgroundColor }: Props) {
+  return (
+    <section className="example-section" style={backgroundColor ? { backgroundColor } : undefined}>
+      <div className="example-section-inner">
+        <h2 className="example-section-heading">{heading}</h2>
+        {subtitle && <p className="example-section-subtitle">{subtitle}</p>}
+      </div>
+    </section>
+  );
+}
+
+export default ExampleSection;

package/templates/create/src/components/ExampleSection/styles.css

@@ -0,0 +1,29 @@
+.example-section {
+  width: 100%;
+  padding: 64px 24px;
+  background: #f8f9fa;
+}
+
+.example-section-inner {
+  max-width: 1200px;
+  margin: 0 auto;
+  text-align: center;
+}
+
+.example-section-heading {
+  margin: 0 0 16px 0;
+  font-size: 36px;
+  font-weight: 700;
+  color: #1a1a2e;
+  font-family: system-ui, -apple-system, sans-serif;
+}
+
+.example-section-subtitle {
+  margin: 0;
+  font-size: 18px;
+  color: #6b7280;
+  font-family: system-ui, -apple-system, sans-serif;
+  max-width: 600px;
+  margin-left: auto;
+  margin-right: auto;
+}

package/templates/create/src/components/ExampleSection/types.ts

@@ -0,0 +1,6 @@
+// Auto-generated types based on ikas.config.json props
+export interface Props {
+  heading: string;
+  subtitle?: string;
+  backgroundColor?: string;
+}

package/templates/create/src/components/index.ts

@@ -0,0 +1,2 @@
+export { ExampleComponent } from "./ExampleComponent/index";
+export { ExampleSection } from "./ExampleSection/index";

package/templates/create/src/global-types.ts

@@ -0,0 +1,5 @@
+// Auto-generated global type definitions for ikas code components.
+// Custom enum types from the editor will appear here.
+// This file is regenerated automatically — do not edit manually.
+
+export {};

package/templates/create/src/global.css

@@ -0,0 +1,12 @@
+/*
+ * Global styles for your ikas code components project.
+ * These styles are NOT scoped — they apply across all components.
+ * Use this for CSS resets, base typography, utility classes, or CSS variables.
+ *
+ * Loading order:
+ *   1. Global CSS (this file) — lowest specificity
+ *   2. Shared chunk CSS — multi-scope (.cc_a .sel, .cc_b .sel)
+ *   3. Component CSS — single scope (.cc_id .sel) — highest specificity
+ *
+ * Component-scoped styles naturally override these globals.
+ */

package/templates/create/src/ikas-component-utils.d.ts

@@ -0,0 +1,3 @@
+declare module "@ikas/component-utils" {
+  export function observer<T extends (props: any) => any>(component: T): T;
+}

package/templates/create/tsconfig.json

@@ -0,0 +1,30 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": [
+      "DOM",
+      "DOM.Iterable",
+      "ES2022"
+    ],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "jsxImportSource": "preact",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": [
+    "src/**/*"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist"
+  ]
+}

package/templates/create/vite.config.ts

@@ -0,0 +1,15 @@
+import { defineConfig } from "vite";
+import preact from "@preact/preset-vite";
+
+export default defineConfig({
+  plugins: [preact()],
+  build: {
+    lib: {
+      entry: "./src/components/index.ts",
+      formats: ["es"]
+    },
+    rollupOptions: {
+      external: ["preact", "preact/hooks", "@ikas/component-utils"]
+    }
+  }
+});

package/templates/observer-runtime.js

@@ -0,0 +1,34 @@
+import { Reaction } from "mobx";
+import { useRef, useState, useEffect } from "preact/hooks";
+
+export function observer(Component) {
+  var wrapped = function(props) {
+    var hookState = useState(0);
+    var setTick = hookState[1];
+    var reactionRef = useRef(null);
+
+    if (!reactionRef.current) {
+      reactionRef.current = new Reaction(
+        "observer(" + (Component.displayName || Component.name || "Component") + ")",
+        function() { setTick(function(t) { return t + 1; }); }
+      );
+    }
+
+    useEffect(function() {
+      return function() {
+        if (reactionRef.current) {
+          reactionRef.current.dispose();
+          reactionRef.current = null;
+        }
+      };
+    }, []);
+
+    var result;
+    reactionRef.current.track(function() {
+      result = Component(props);
+    });
+    return result;
+  };
+  wrapped.displayName = "observer(" + (Component.displayName || Component.name || "Component") + ")";
+  return wrapped;
+}