@ikas/component-cli 0.93.0 → 0.94.0

package/templates/create-full/cursorrules

@@ -0,0 +1,103 @@
+# 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`** — it is 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 BOTH `ikas.config.json` AND `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`
+- 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
+- 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-full/gitignore

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