@embeddables/cli 0.7.0 → 0.7.2

package/.prompts/embeddables-cli.md

@@ -44,7 +44,7 @@ Pages are stored in `Flow.pages` and transform to React page files. The `FlowPag
 
 **File Mapping**: `pages/{pageKey}.page.tsx` (e.g., `pages/welcome_page.page.tsx`)
 
-**React Structure**: Each page file exports a React component that renders the page's components as JSX.
+**React Structure**: Each page file must start with `'use client'` at the top, then imports, then export a default React component that renders the page's components as JSX.
 
 ## Global Components Structure
 
@@ -76,7 +76,7 @@ All component types are derived from `src/types-builder.ts`. The relevant typing
 
 **Key Base Properties** (all components have these):
 
-- `id: string` - Unique identifier - this must be unique across the entire Embeddable JSON. Always snake_case.
+- `id: string` - Unique identifier — must be unique across the entire Embeddable JSON. Always snake*case. Use the ID format convention (e.g. `comp*` + 10 digits for components; see Important Notes).
 - `key: string` - Unique identifier, used in React as key prop - unique in general but duplicate keys can be used in certain cases (e.g. two `email` fields, each hidden by conditions). Always snake_case. **Keys must not start with a digit** (invalid in JS/JSON). When deriving a key from text that would start with a number (e.g. "1 to 2 weeks" → "1_to_2_weeks"), use a semantic prefix instead: e.g. `range_1_to_2_weeks`, `option_1_to_2_weeks`, or the component key like `delivery_time_1_to_2_weeks`.
 - `type: ComponentType` - Component type
 - `tags?: string[]` - Used for CSS styling
@@ -191,7 +191,7 @@ This pattern improves readability and makes the buttons array easier to maintain
 
 Styles are stored in `Flow.styles` as a map of CSS selectors to style objects. The `FlowStyles` type is defined in `src/types-builder.ts`.
 
-**File Mapping**: A single `styles.css` file
+**File Mapping**: `styles/index.css` — a single CSS file containing all selectors for this flow.
 
 ### CSS Selector System
 
@@ -578,6 +578,7 @@ The `config.json` file contains the reduced Embeddable JSON with:
 ### React Files (Pages)
 
 - Location: `pages/{pageKey}.page.tsx`
+- Directive: Start the file with `'use client'` at the top
 - Export: **Default export** of React component (e.g., `export default function PageName()`)
 - Props: Component props match JSON properties
 - Keys: All components must have `id` and `key` props matching component `id` and `key` properties respectively
@@ -591,7 +592,7 @@ The `config.json` file contains the reduced Embeddable JSON with:
 
 ### CSS Files
 
-- Location: `styles/{selector}.css` or organized by tag/component
+- Location: `styles/index.css` — a single CSS file for the flow (do not create multiple CSS files)
 - Format: Standard CSS with selector as class name
 - Content: Style properties from `Flow.styles[selector]`
 
@@ -619,7 +620,7 @@ The `config.json` file contains the reduced Embeddable JSON with:
 3. **Component Types**:
    - Use `PlainText` by default
    - Use `RichTextMarkdown` only for mixed formatting (bold, italic, lists, links, colors)
-   - Use `CustomHTML` for any other styling or formatting needs
+   - Use `CustomHTML` for presentational content only (overlays, inline SVGs, decorative HTML). **Caution**: CustomHTML is for presentational content only. For interactive elements like buttons or selectable options, always use `CustomButton` or `OptionSelector` — CustomHTML elements have no access to flow actions or user data outputs.
 
 4. **Nested Components**: Containers can have `components[]` array with child components. Render as nested JSX.
 
@@ -637,6 +638,13 @@ The `config.json` file contains the reduced Embeddable JSON with:
 
 ## Common Patterns
 
+### Adding a New Page
+
+1. Create `pages/{pageKey}.page.tsx` with `'use client'` at the top and a default export.
+2. Add an entry to `config.json` under `pages[]` — required fields: `id`, `key`, `tags[]`.
+3. Add CSS for the page tag in `styles/index.css` if new layout styles are needed.
+4. Use a unique page ID: generate a numeric string like `"page_1234567890"` (see **ID format** under Important Notes). Must be unique across the flow.
+
 ### Adding a Component to a Page
 
 1. Update the page's React file (`pages/{pageKey}.page.tsx`)
@@ -672,7 +680,7 @@ The `config.json` file contains the reduced Embeddable JSON with:
 
 ## Important Notes
 
-- **IDs**: All components, pages, computed fields, actions, and buttons inside OptionSelectors have unique `id` properties. These are preserved in config.json and used for internal references, except for component and button ids which should always be written in React
+- **IDs**: All components, pages, computed fields, actions, and buttons inside OptionSelectors have unique `id` properties. These are preserved in config.json and used for internal references, except for component and button ids which should always be written in React. **ID format**: Use a prefix plus 10 digits so generated IDs don't collide with real ones: pages → `page_` + 10 digits (e.g. `page_1234567890`); components → `comp_` + 10 digits; option buttons → `button_` prefix (e.g. `button_plan_basic`). Must be unique across the flow.
 
 - **Keys**: Component and page `key` properties are used for file naming and must be valid file names (no special characters, use underscores).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@embeddables/cli",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "type": "module",
   "bin": {
     "embeddables": "./bin/embeddables.mjs"