@embeddables/cli 0.1.0 → 0.3.0

package/.cursor/rules/embeddables-cli.md

@@ -0,0 +1,679 @@
+---
+globs:
+alwaysApply: true
+---
+
+# Cursor Rules for Embeddables CLI
+
+This document provides comprehensive context for Cursor AI when working with Embeddables in the CLI codebase. The CLI transforms Embeddable JSON into a local file structure for development, then compiles it back to JSON for saving.
+
+**Note**: All TypeScript types are defined in `src/types-builder.ts`. Refer to that file for complete type definitions. This document focuses on contextual information about how the system works.
+
+## Overview
+
+The CLI transforms an Embeddable JSON into:
+
+- **React files**: Pages and global components
+- **CSS files**: Styles organized by selectors
+- **JS files**: Computed fields and actions
+- **config.json**: Reduced JSON containing structure/metadata without file content
+
+## Embeddable JSON Structure (Flow)
+
+The root Embeddable object (called `Flow`) is defined in `src/types-builder.ts`. Key properties:
+
+- `pages: FlowPage[]` → React page files
+- `styles?: FlowStyles` → CSS files
+- `components?: Component[]` → React global component files, one file per 'location'
+- `dataOutputs?: Action[]` → JS action files
+- `computedFields?: ComputedField[]` → JS computed field files
+- All other properties → config.json
+
+## Pages Structure
+
+Pages are stored in `Flow.pages` and transform to React page files. The `FlowPage` type is defined in `src/types-builder.ts`.
+
+**Key Properties**:
+
+- `key: string` - Used for file naming (e.g., "welcome_page" → `pages/welcome_page.page.tsx`)
+- `components: Component[]` - Components on this page → React JSX
+- `tags?: string[]` - Used for CSS styling
+- `conditions?: Condition[]` - Visibility logic
+- `is_exit_page` - Whether a user viewing this page should be disallowed from proceeding any further (e.g. a disqualification page)
+- All other properties stored in config.json (along with key, tags, conditions).
+
+**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.
+
+## Global Components Structure
+
+Global components are stored in `Flow.components` (not in pages) and have a `_location` property indicating where they appear. The `GlobalComponentLocation` type is defined in `src/types-builder.ts`.
+
+**Global Component Locations**:
+
+<!-- todo - describe these better in terms of HTML elements -->
+
+- `"before_page"` - Before the page container
+- `"page_top"` - At the top of the page
+- `"before_components"` - Before page components
+- `"after_components"` - After page components
+- `"page_bottom"` - At the bottom of the page
+- `"after_page"` - After the page container
+
+**File Mapping**: `global-components/{locationKey}.location.tsx` (e.g., `global-components/after_page.location.tsx`)
+
+**Important**: Global components have `_location` property that determines where they render relative to pages. This is how they are grouped into files.
+
+## Component Types and Structure
+
+All component types are derived from `src/types-builder.ts`. The relevant typings are:
+
+- `Component` - Union type of all component interfaces
+- `ComponentType` - Union type of all component type strings
+- `Base` - Base interface that all components extend
+- Specific component interfaces, which correspons to the 'type' property in components: `Container`, `PlainText`, `RichTextMarkdown`, `CustomButton`, `InputBox`, `OptionSelector`, `MediaImage`, `StripeCheckout2`, `PaypalCheckout`, `FileUpload`, `ProgressBar`, `BookMeeting`, `Chart`, `Lottie`, `Rive`, `MediaEmbed`, etc.
+
+**Key Base Properties** (all components have these):
+
+- `id: string` - Unique identifier - this must be unique across the entire Embeddable JSON. Always snake_case.
+- `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.
+- `type: ComponentType` - Component type
+- `tags?: string[]` - Used for CSS styling
+- `parent_id?: string` - For nested components
+- `_location?: GlobalComponentLocation` - Only for global components
+- Many other optional properties - see `src/types-builder.ts` for complete list
+
+**Component-Specific Properties**: Each component type has additional properties. Refer to `src/types-builder.ts` for:
+
+- `CustomButton`
+  - `action`
+  - `actionUrl`
+  - `icon`
+  - `outputs_onclick`
+  - etc.
+- `InputBox`
+  - `input_type`
+  - `validation_formula`
+  - `outputs_onchange`
+  - etc.
+- `OptionSelector`
+  - `buttons`
+  - `multiple` - whether to allow multi-select
+  - `dropdown`
+  - `checkbox` - whether to add a (square/round) visual checkbox in each button (the checkbox will be added for you, no need to add it manually)
+  - `checkbox_location` whether to put the checkboxes at the start or end of the button contents
+  - etc.
+- `MediaImage`
+  - `caption`
+  - `alt_text`
+- `Container`
+  - `container_type`
+- And all other component types
+
+**Component hierarchy and nesting**: Components in the JSON are always in a flat array - the containment of other components is handled by the `parent_id` property, which corresponds to the `id` of another component.
+
+### React Component Rendering
+
+When transforming to React:
+
+- Each component becomes a JSX element with props matching the component's properties
+- Component `id` prop must match the component's `id` property
+- Component `key` prop must match the component's `key` property
+- Component `type` determines the React component to render
+- Nested components (from `parent_id`) are rendered as children
+- Tags are applied as CSS classes (e.g. `.ComponentTag-{tagName}` - see below)
+
+**Example React transformation**:
+
+```tsx
+// JSON:
+{
+  "id": "comp_123",
+  "key": "hero_title",
+  "type": "PlainText",
+  "text": "Welcome to our site",
+  "tags": ["hero_text"]
+}
+
+// React:
+<PlainText id="comp_123" key="hero_title" text="Welcome to our site" tags={["hero_text"]} />
+```
+
+**React file export convention**: All React page and global component files must use **default exports**:
+
+```tsx
+// Correct - use default export
+export default function PageName() {
+  return (...)
+}
+
+// Incorrect - do NOT use named export
+export function PageName() {
+  return (...)
+}
+```
+
+**OptionSelector buttons pattern**: When writing TSX files with `OptionSelector` components, define the buttons as constants before the JSX, then reference them in the `buttons` prop:
+
+```tsx
+'use client'
+
+import { OptionSelector } from '@embeddables/cli/components'
+import type { OptionSelectorButton } from '@embeddables/cli/types'
+
+const planButtons: OptionSelectorButton[] = [
+  { id: 'button_plan_basic', key: 'basic', text: 'Basic Plan', description: '$9/month' },
+  { id: 'button_plan_pro', key: 'pro', text: 'Pro Plan', description: '$19/month' },
+  {
+    id: 'button_plan_enterprise',
+    key: 'enterprise',
+    text: 'Enterprise',
+    description: 'Contact us',
+  },
+]
+
+export default function PlanPage() {
+  return (
+    <OptionSelector
+      id="comp_456"
+      key="plan_selector"
+      buttons={planButtons}
+      tags={['plan_options']}
+    />
+  )
+}
+```
+
+This pattern improves readability and makes the buttons array easier to maintain compared to defining it inline within the JSX.
+
+## Styles Structure (CSS)
+
+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
+
+### CSS Selector System
+
+CSS selectors follow a specific structure. The order is:
+
+<!-- todo - check this -->
+
+```
+[mainFlowElement][breakpoint][scope][element][tag][state][subElement][option][childElement]
+```
+
+#### 1. Main Flow Element
+
+- `.Flow-EntireFlow` - Wraps entire embeddable (used with breakpoints or global styles)
+
+#### 2. Breakpoint
+
+Note that these are desktop-first, not mobile-first (i.e. that the default styles are always applied, whereas mobile styles are only applied on small screen sizes).
+
+- Desktop (default): omitted
+- Tablet: `[max-width~='720px'] ` (note trailing space)
+- Mobile: `[max-width~='520px'] ` (note trailing space)
+
+Note: If you need to use any breakpoints other than 720px and 520px, you must add them in a top-level `breakpoints` (typing is Breakpoint[]) property in config.json.
+
+#### 3. Scope
+
+- Entire embeddable (default): omitted
+- This page: `.PageKey-{pageKey}`
+- Pages with tag: `.PageTag-{pageTag}`
+
+**Important**: `PageKey-{pageKey}` and `PageTag-{pageTag}` classes are applied to **every component** on that page to identify which page the component belongs to. To actually target the **page element itself** (not just components on that page), you must combine the scope class with `.Flow-Page` (e.g., `.Flow-Page.PageTag-{pageTag}`).
+
+#### 4. Element (Base Structure)
+
+- Component: `.Flow-Component` or `.Flow-Component.ComponentType-{Type}`
+- Page: `.Flow-Page` (must be combined with scope class like `.PageTag-{pageTag}` or `.PageKey-{pageKey}` to target the page element)
+- Element: `.Flow-Element` or `.Flow-Element.ElementType-{Type}`
+- Special: `.ElementType-PageContents`, `.InfoBox`, `.close`
+
+#### 5. Tag (REQUIRED if targeting component/page)
+
+- Component: `.ComponentTag-{tagName}`
+- Page: `.PageTag-{tagName}`
+
+#### 6. State
+
+- `always` → omitted (default)
+- `hover` → `:hover`
+- `selected` → `.selected` (NOT `:selected`)
+- `disabled` → `[disabled=disabled]` (NOT `:disabled`)
+- `active` → `:active`
+- `focus` → `:focus`
+- `hover_selected` → `.selected:hover`
+- `toggled` → `.isOn`
+- `hover_toggled` → `.isOn:hover`
+
+#### 7. Sub-Element (Descendant)
+
+- Format: ` .ElementType-{Type}` (leading space required!)
+- See the 'Component Sub-Element Types Reference' section below for details
+
+#### 8. Option (For Option Selectors)
+
+- Option selector: `.ElementKey-{key}`
+- Advanced dropdown: `[value='{key}']`
+
+#### 9. Child Element
+
+- Format: `>img`, `>span`, `>:first-child`
+
+### Selector Examples
+
+<!-- todo - check these -->
+
+```
+// Simple component with tag
+.Flow-Component.ComponentTag-primary_button
+
+// Component with hover state
+.Flow-Component.ComponentTag-primary_button:hover
+
+// Button text on hover
+.Flow-Component.ComponentType-CustomButton.ComponentTag-primary_button:hover.ElementType-ButtonText
+
+// Mobile breakpoint
+.Flow-EntireFlow[max-width~='1024px'] .Flow-Component.ComponentTag-landing_container
+
+// Page-scoped component (PageKey is on the component, not the page)
+.PageKey-checkout_page_1.Flow-Component.ComponentTag-checkout_button
+
+// Page Tag-scoped component (PageTag is related to the page but the class is present on the component)
+.PageTag-standard_page.Flow-Component.ComponentTag-header_container
+
+// Targeting the page element itself (requires both PageTag/PageKey AND Flow-Page)
+.Flow-Page.PageTag-intro
+.Flow-Page.PageKey-checkout_page_1
+
+// Option button inside OptionSelector
+.Flow-Element.ElementType-OptionButtonCard.ComponentTag-checkbox_options
+
+// Selected option button inside dropdown OptionSelector
+.Flow-Element.ElementType-DropdownListOption.ComponentTag-standard_dropdown.selected
+
+// Disabled button
+.Flow-Component.ComponentTag-standard_button[disabled=disabled]
+```
+
+## Images and Icons
+
+Whenever you need to insert an image or icon (e.g. a logo, an icon, a larger image) you have the following options:
+
+1. `emojiIcon` with an emoji when there is an appropriate emoji that you can use. This can be used in `imageUrl` in CustomButton, or `imageUrl` inside OptionSelector buttons
+2. Image URL. This can be used in `src` in MediaImage, `imageUrl` in CustomButton, or `imageUrl` inside OptionSelector buttons.
+
+For placeholder images, the recommended service is placehold.co:
+
+- https://placehold.co/600x400?text=My+Text+To+Display if there is text in the image (can't be emojis)
+- otherwise https://placehold.co/600x400
+
+(with the correct size specified in the URL in either case).
+
+Please be consistent with your choice out of those options within a particular component or section.
+
+## Component Sub-Element Types Reference
+
+### OptionSelector
+
+NOTE: button icons and checkboxes are before text in the button, unless you set the flex-direction to be row-reverse or column-reverse.
+NOTE: OptionSelectors are either dropdowns (`dropdown` is `true`, can use other dropdown-related properties) or they are not. There is no half and half.
+
+| ElementType                        | Element            | Condition                                            | Notes                                                             |
+| ---------------------------------- | ------------------ | ---------------------------------------------------- | ----------------------------------------------------------------- |
+| `Label`                            | `<label>`          | `label` set                                          |                                                                   |
+| `OptionButtonList`                 | `<div>`            | `dropdown: false`                                    |                                                                   |
+| `OptionButtonCard`                 | `<div>`            | `dropdown: false`                                    |                                                                   |
+| `OptionButtonCardText`             | `<div>`            | `dropdown: false` + button has `text`                |                                                                   |
+| `OptionButtonCardDescription`      | `<div>`            | `dropdown: false` + button has `description`         |                                                                   |
+| `OptionButtonCardIcon`             | `<span>`/`<div>`   | `dropdown: false` + button has `emojiIcon` or `icon` |                                                                   |
+| `OptionButtonCardIconImage`        | `<span>`           | `dropdown: false` + button has `imageUrl`            |                                                                   |
+| `OptionButtonCardIconImageElement` | `<img>`            | `dropdown: false` + button has `imageUrl`            |                                                                   |
+| `OptionButtonCardCheckbox`         | `<div>`            | `dropdown: false` + `checkbox: true`                 | The checkbox is added automatically as an svg inside this element |
+| `OptionDropdown`                   | `<select>`/`<div>` | `dropdown: true`                                     |                                                                   |
+| `DropdownMain`                     | `<div>`            | `dropdown: true` + advanced\*                        |                                                                   |
+| `DropdownMainContent`              | `<span>`           | `dropdown: true` + advanced\*                        |                                                                   |
+| `DropdownMainContentInput`         | `<input>`          | `dropdown: true` + advanced\* + `allow_typing: true` |                                                                   |
+| `DropdownList`                     | `<datalist>`       | `dropdown: true` + advanced\*                        |                                                                   |
+| `DropdownListOption`               | `<div>`            | `dropdown: true` + advanced\*                        |                                                                   |
+| `DropdownListOptionText`           | `<div>`            | `dropdown: true` + advanced\*                        |                                                                   |
+
+\*Advanced = `is_advanced_dropdown` (only if `dropdown` is `true`), `multiple`, or `allow_typing` (searchable, only if `dropdown` is `true`)
+
+### CustomButton
+
+Note: the component itself IS the button. There is no `button` element inside it.
+Note: button icons and checkboxes are before text in the button, unless you set the flex-direction to be row-reverse or column-reverse.
+
+| ElementType         | Element          | Condition                 | Notes                                                                                             |
+| ------------------- | ---------------- | ------------------------- | ------------------------------------------------------------------------------------------------- |
+| `ButtonTextWrapper` | `<div>`          | Always                    |                                                                                                   |
+| `ButtonText`        | `<div>`          | `text` set                |                                                                                                   |
+| `ButtonDescription` | `<div>`          | `description` set         |                                                                                                   |
+| `ButtonIcon`        | `<svg>`/`<span>` | `icon` or `emojiIcon` set | If `icon`, must be font-awesome icon name; if `emojiIcon` must be an emoji in text format like 😀 |
+| `ButtonIconImage`   | `<span>`         | `imageUrl` set            |                                                                                                   |
+
+### InputBox
+
+| ElementType       | Element      | Condition                              |
+| ----------------- | ------------ | -------------------------------------- |
+| `Label`           | `<label>`    | `label` set                            |
+| `InputElement`    | `<input>`    | NOT (`multiline` + `input_type: text`) |
+| `TextareaElement` | `<textarea>` | `multiline: true` + `input_type: text` |
+
+### ChatMessages
+
+| ElementType                        | Element      | Condition                    |
+| ---------------------------------- | ------------ | ---------------------------- |
+| `ChatMessagesContainer`            | `<div>`      | Always                       |
+| `ChatMessageInputContainer`        | `<div>`      | `use_external_inputs: false` |
+| `ChatMessageInput`                 | `<textarea>` | `use_external_inputs: false` |
+| `ChatSubmitButton`                 | `<button>`   | `use_external_inputs: false` |
+| `ChatMessageLoading`               | `<img>`      | `use_external_inputs: false` |
+| `ChatQuickInitialOptionsContainer` | `<div>`      | `quick_initial_options` set  |
+| `ChatQuickInitialOptions`          | `<button>`   | `quick_initial_options` set  |
+
+### MediaEmbed
+
+| ElementType        | Element    | Condition                                             |
+| ------------------ | ---------- | ----------------------------------------------------- |
+| `Video`            | `<video>`  | `src` ends with `.mp4`/`.mov`                         |
+| `PlaceholderImage` | `<img>`    | Video + `placeholder_image_url` + `centralPlayButton` |
+| `Embed`            | `<div>`    | `embed_code` set (not video)                          |
+| `IFrameContainer`  | `<div>`    | `src` set (not video, no embed_code)                  |
+| `IFrame`           | `<iframe>` | `src` set (not video, no embed_code)                  |
+| `PlayButton`       | `<button>` | `centralPlayButton: true` + controls shown            |
+
+### MediaImage
+
+| ElementType | Element | Condition     |
+| ----------- | ------- | ------------- |
+| `Image`     | `<img>` | Always        |
+| `Caption`   | `<div>` | `caption` set |
+
+### ProgressBar
+
+EXCEPTION: ProgressBarBackground does not currently exist so use the overall component for background color etc.
+EXCEPTION: for 'ProgressBarFilled', instead of adding the 'ElementType-ProgressBarFilled' class, just add the 'bar' class.
+NOTE: there is also a reset icon button with the class `reset` - hide this if you don't want to show it.
+
+| ElementType             | Element            | Condition                           |
+| ----------------------- | ------------------ | ----------------------------------- |
+| `ProgressBarBackground` | `<div>`/`<circle>` | `progress_type: simple` or `circle` |
+| `ProgressBarFilled`     | `<div>`/`<circle>` | `progress_type: simple` or `circle` |
+
+### FileUpload
+
+| ElementType | Element | Condition |
+| ----------- | ------- | --------- |
+| `Uploader`  | `<div>` | Always    |
+
+### StripeCheckout2
+
+| ElementType             | Element    | Condition                                |
+| ----------------------- | ---------- | ---------------------------------------- |
+| `StripeCheckout2Button` | `<button>` | `elements_to_display` includes `payment` |
+
+### Components with No ElementTypes
+
+`BookMeeting`, `Chart`, `ChildFlow`, `CustomHTML`, `Lottie`, `PaypalCheckout`, `PlainText`, `RichTextMarkdown`, `Rive`
+
+## Computed Fields Structure
+
+Computed fields are stored in `Flow.computedFields` and transform to JS files. The `ComputedField` type is defined in `src/types-builder.ts`.
+
+**Key Properties**:
+
+- `key: string` - Used for file naming (e.g., "total_price" → `computed-fields/total_price.js`)
+- `code?: string` - JavaScript function code → JS file content
+- `inputs?: string[]` - Keys from User Data that trigger recalculation
+- `input_triggers?: string[]` - Additional trigger keys
+- All other properties stored in config.json
+
+**File Mapping**: `computed-fields/{key}.js` (e.g., `computed-fields/total_price.js`)
+
+**Code Structure**: The `code` property contains JavaScript that must include a function called `result` that returns the computed value:
+
+```javascript
+function result() {
+  // Access user data via global userData object
+  const price = userData.price || 0
+  const quantity = userData.quantity || 0
+  return price * quantity
+}
+```
+
+**Important**:
+
+- Computed fields can reference other computed fields via their keys in `inputs`
+- The function has access to a global `userData` object containing all user data
+- If `async` is true, the function can return a Promise
+- `input_triggers` specify additional keys that trigger recalculation
+
+## Actions Structure
+
+Actions are stored in `Flow.dataOutputs` and transform to JS files. The `Action` type and extended action types (`AirtableAction`, `HubspotAction`, `GoogleSheetsAction`, `WebhookAction`, `SendgridAction`) are defined in `src/types-builder.ts`.
+
+**Key Properties**:
+
+- `name: string` - Used for file naming (e.g., "submit_form" → `actions/submit_form.js`)
+- `output: "custom" | "airtable" | "hubspot" | "google-sheets" | "sendgrid" | "diahook"`
+- `code?: string` - JavaScript function code → JS file content (for custom actions)
+- Extended action types have additional properties (mappings, base, table, etc.) - see `src/types-builder.ts`
+
+**File Mapping**: `actions/{name}.js` (e.g., `actions/submit_form.js`)
+
+**Code Structure**: For `output: "custom"`, the `code` property contains JavaScript that must include a function called `output`:
+
+```javascript
+function output() {
+  // Access user data via global userData object
+  const email = userData.email
+  const name = userData.name
+
+  // Perform action (API call, data transformation, etc.)
+  return {
+    success: true,
+    data: { email, name },
+  }
+}
+```
+
+**Important**:
+
+- Actions are triggered by various events (button clicks, page completion, etc.)
+- The function has access to a global `userData` object
+- For non-custom actions (airtable, hubspot, etc.), the action configuration is stored in config.json, not in the JS file
+
+## Conditions Structure
+
+Conditions control visibility of components and pages based on User Data. The `Condition`, `ConditionOperator`, `ConditionValue`, and `ConditionalTag` types are defined in `src/types-builder.ts`.
+
+**Valid Operators** (`ConditionOperator`):
+
+- `==` - equals (with multiple values = OR)
+- `!=` - not equals (with multiple values = neither A nor B)
+- `exists` / `!exists` - key exists or doesn't exist
+- `is-true` / `is-false` - boolean checks
+- `is-not-true` / `is-not-false` - negated boolean checks
+- `is-empty` / `is-not-empty` - empty value checks
+
+**Logic Rules**:
+
+- Multiple values in ONE condition = OR
+- Multiple SEPARATE conditions = AND
+- Conditional tags apply tags conditionally based on conditions
+
+**Storage**: Conditions are stored in the component/page JSON and preserved in config.json (not in React/CSS/JS files).
+
+## Config.json Structure
+
+The `config.json` file contains the reduced Embeddable JSON with:
+
+- All structural properties (id, title, builder_version, etc.)
+- Page metadata (id, key, properties) but NOT component content (components are in React files)
+- Style selectors but NOT style values (styles are in CSS files)
+- Computed field metadata (id, key, inputs, etc.) but NOT code (code is in JS files)
+- Action metadata (id, name, output, mappings, etc.) but NOT code (code is in JS files)
+- All other Flow properties (experiments, transitions, settings, etc.)
+
+**Example config.json structure**:
+
+```json
+{
+  "id": "flow_123",
+  "title": "My Embeddable",
+  "builder_version": 4,
+  "pages": [
+    {
+      "id": "page_1",
+      "key": "welcome_page",
+      "tags": ["intro"],
+      "is_exit_page": false
+      // components[] not included - stored in pages/welcome_page.page.tsx
+    }
+  ],
+  // 'components' property not included - all info stored in `global-components/{locationKey}.location.tsx`
+  "styles": {
+    ".Flow-Component.ComponentTag-primary_button": {}
+    // Style values not included - stored in CSS files
+  },
+  "computedFields": [
+    {
+      "id": "cf_1",
+      "key": "total_price",
+      "inputs": ["price", "quantity"]
+      // code not included - stored in computed-fields/total_price.js
+    }
+  ],
+  "dataOutputs": [
+    {
+      "id": "action_1",
+      "name": "submit_form",
+      "output": "custom"
+      // code not included - stored in actions/submit_form.js
+    }
+  ]
+}
+```
+
+## File Organization Rules
+
+### React Files (Pages)
+
+- Location: `pages/{pageKey}.page.tsx`
+- 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
+
+### React Files (Global Components)
+
+- Location: `global-components/{locationKey}.location.tsx`
+- Export: **Default export** of React component (e.g., `export default function GlobalComponents()`)
+- Props: Component props match JSON properties
+- Location: `_location` property not needed here since the filenames contain the location of that group of components
+
+### CSS Files
+
+- Location: `styles/{selector}.css` or organized by tag/component
+- Format: Standard CSS with selector as class name
+- Content: Style properties from `Flow.styles[selector]`
+
+### JS Files (Computed Fields)
+
+- Location: `computed-fields/{key}.js`
+- Export: Function named `result` that returns computed value
+- Access: Global `userData` object available
+
+### JS Files (Actions)
+
+- Location: `actions/{name}.js`
+- Export: Function named `output` for custom actions
+- Access: Global `userData` object available
+
+## Key Principles for Modifications
+
+1. **Component Keys**: Must be unique and descriptive. Keys become User Data keys for input components.
+
+2. **Tags**: Used for CSS styling. Apply tags consistently:
+   - Primary tag (required): Describes component type (e.g., `standard_button`, `price_card`)
+   - Secondary tag (optional): Variant of primary (e.g., `primary_button`, `outline_button`)
+   - Utility tag (optional): Only for margins that can't be applied via primary/secondary (e.g., `m_2`)
+
+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
+
+4. **Nested Components**: Containers can have `components[]` array with child components. Render as nested JSX.
+
+5. **Global Components**: Must use the filenames to replace the `_location` property.
+
+6. **Conditions**: Stored in config.json, applied at runtime. Multiple values in one condition = OR, multiple conditions = AND.
+
+7. **CSS Selectors**: Must follow exact structure with proper spacing (trailing space on breakpoints, leading space on sub-elements).
+
+8. **User Data Keys**: Input component keys become User Data keys. Choose descriptive names (e.g., `email` not `email_input`).
+
+9. **Computed Field Dependencies**: `inputs` array defines which User Data keys trigger recalculation. Can reference other computed fields.
+
+10. **Action Triggers**: Actions are triggered by events (button clicks, page completion, etc.). Configuration stored in config.json, code in JS files.
+
+## Common Patterns
+
+### Adding a Component to a Page
+
+1. Update the page's React file (`pages/{pageKey}.page.tsx`)
+2. Add component JSX with appropriate props
+3. If new tags are used, ensure CSS exists for those tags
+4. Update config.json if component metadata is needed (rarely)
+
+### Styling a Component
+
+1. Identify the component's tag
+2. Construct CSS selector following the selector system
+3. Add/update CSS file with styles
+4. Ensure selector matches the component's structure
+
+### Adding a Computed Field
+
+1. Create JS file: `computed-fields/{key}.js`
+2. Implement `result()` function
+3. Add metadata to config.json: `computedFields` array
+4. Specify `inputs` array for dependencies
+
+### Adding an Action
+
+1. Create JS file: `actions/{name}.js`
+2. Implement `output()` function (for custom actions)
+3. Add metadata to config.json: `dataOutputs` array
+4. Configure action type and mappings in config.json
+
+### Modifying Global Components
+
+1. Update React file: `global-components/{locationKey}.location.tsx`
+2. Update styles if needed
+
+## 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
+
+- **Keys**: Component and page `key` properties are used for file naming and must be valid file names (no special characters, use underscores).
+
+- **Parent-Child Relationships**: Components can be nested. Parent component has `components[]` array. Child components have `parent_id` property.
+
+- **Repeaters**: Components with `repeater_key` repeat based on array data in User Data.
+
+- **Conditions**: Applied at runtime. Components/pages with conditions that don't pass are hidden.
+
+- **Tags**: Multiple tags can be applied. CSS selectors can target by any tag.
+
+- **Breakpoints**: CSS supports responsive design via breakpoint selectors. Default is desktop, mobile/tablet use `[max-width~='{width}px'] ` syntax.
+
+- **States**: Interactive elements support states (hover, selected, disabled, etc.). CSS selectors include state syntax.
+
+- **Sub-elements**: Components have internal structure. CSS can target sub-elements using `.ElementType-{Type}` syntax.