@walkeros/explorer 0.0.7 → 0.3.0

package/README.md

@@ -1,476 +1,748 @@
-# WalkerOS Explorer
+# walkerOS Explorer
 
-Interactive code editor and preview components for walkerOS development,
-testing, and debugging. Built with functional factory patterns, zero external
-dependencies, and comprehensive TypeScript support.
+Interactive React components for walkerOS documentation and exploration.
+Provides ready-to-use demo components with Monaco Editor integration for live
+code editing and event visualization.
 
-## 🎯 Overview
+## Installation
 
-WalkerOS Explorer is a complete toolkit for building interactive development
-environments. It provides a set of composable components that can be used
-individually or combined to create powerful code editing and preview
-experiences.
+```bash
+npm install @walkeros/explorer
+```
 
-### ✨ Key Features
+## Usage
 
-- 🧩 **Functional Factory Pattern** - Clean, composable component architecture
-- 🚀 **Zero Dependencies** - No external libraries except for React peer
-  dependencies
-- 💎 **Full TypeScript Support** - Complete type definitions and IntelliSense
-- 🎨 **Theme-aware** - Built-in light/dark theme support
-- 📱 **Responsive Design** - Works on all screen sizes
-- ⚡ **High Performance** - Optimized for speed and memory efficiency
-- 🧪 **Fully Tested** - 101 comprehensive tests with Jest and JSDOM
+```tsx
+import { MappingDemo } from '@walkeros/explorer';
+import '@walkeros/explorer/styles.css';
+```
 
-## 📦 Installation
+## Architecture
 
-```bash
-# In walkerOS monorepo (already included)
-npm install
+Components follow atomic design principles:
 
-# As external dependency (future)
-npm install @walkeros/explorer
-```
+- **Atoms**: Basic UI elements (Box, Button, Header, ButtonGroup, Toggle, etc.)
+- **Molecules**: Component combinations (AutoSelect, MappingEditor, TreeSidebar)
+- **Organisms**: Complex components (MappingBox, CodeBox, MappingEditorTabs)
+- **Demos**: Ready-to-use complete demos (MappingDemo, DestinationDemo)
 
-## 🏗️ Architecture
+### Design Principles
 
-The explorer is built in phases, each building upon the previous:
+**Component Reusability**
 
-### Phase 1: Foundation
+- All components are composable and reusable
+- Shared components over duplicate code
+- Atomic design ensures scalability
 
-- **Component Factory** - Base component system with lifecycle management
-- **Event Bus** - Global communication system
-- **DOM Utilities** - Safe DOM manipulation and event handling
-- **Performance Utilities** - Debounce, throttle, and memoization
-- **Syntax Highlighting** - Code syntax detection and highlighting
+**No Inline Styles**
 
-### Phase 2: Individual Components
+- All styling via CSS classes and CSS variables
+- Inline styles are forbidden
+- Use CSS modules or SCSS for styling
 
-- **CodeEditor** - Interactive code editor with syntax highlighting
-- **Preview** - HTML preview with iframe sandboxing
-- **ResultDisplay** - Execution results with multiple result types
+**Theme Support Required**
 
-### Phase 3: Composite Components
+- All components support light/dark themes
+- Theme switching via `data-theme` attribute
+- CSS variables automatically adapt
 
-- **LiveCode** - Combined editor and preview for live development
-- **EventFlow** - walkerOS event visualization and debugging
-- **Destination** - walkerOS destination testing and configuration
+## Components
 
-## 🚀 Quick Start
+### Demos (Ready-to-Use)
 
-### Individual Components
+#### MappingDemo
 
-```typescript
-import {
-  createCodeEditor,
-  createPreview,
-  createResultDisplay,
-} from '@walkeros/explorer';
+Interactive three-panel editor: input → config → output transformation.
 
-// Create a code editor
-const editor = createCodeEditor('#editor', {
-  language: 'javascript',
-  value: 'console.log("Hello World");',
-  height: '400px',
-  onChange: (value) => console.log('Code changed:', value),
-});
-
-// Create a preview
-const preview = createPreview('#preview', {
-  html: '<h1>Hello World</h1>',
-  height: '400px',
-});
-
-// Create a results display
-const results = createResultDisplay('#results', {
-  maxResults: 100,
-});
+```tsx
+<MappingDemo
+  input='{"name": "example"}'
+  config='{"transform": "uppercase"}'
+  labelInput="Event"
+  labelConfig="Rules"
+  labelOutput="Result"
+  fn={async (input, config) => {
+    const data = JSON.parse(input);
+    const rules = JSON.parse(config);
+    return JSON.stringify(result, null, 2);
+  }}
+/>
 ```
 
-### Composite Components
+#### DestinationDemo
 
-```typescript
-import {
-  createLiveCode,
-  createEventFlow,
-  createDestination,
-} from '@walkeros/explorer';
+Interactive destination testing with event processing and mapping. Automatically captures destination.push() calls and displays the output.
 
-// Live code editor with preview
-const liveCode = createLiveCode('#livecode', {
-  layout: 'horizontal',
-  showTabs: true,
-  initialHTML: '<h1>Hello World</h1>',
-  initialCSS: 'h1 { color: blue; }',
-  initialJS: 'console.log("Hello");',
-});
-
-// Event flow visualization
-const eventFlow = createEventFlow('#events', {
-  maxEvents: 1000,
-  showMetrics: true,
-  onEventCapture: (event) => console.log('Event:', event),
-});
-
-// Destination testing
-const destination = createDestination('#destination', {
-  showTemplates: true,
-  enableValidation: true,
-});
-```
+**Simple Usage** (Recommended):
 
-## 📚 Components Reference
-
-### CodeEditor
-
-Interactive code editor with syntax highlighting and multiple language support.
-
-```typescript
-const editor = createCodeEditor(elementOrSelector, {
-  language: 'javascript' | 'typescript' | 'html' | 'css' | 'json' | 'markdown',
-  value: string,
-  height: string,
-  readOnly: boolean,
-  onChange: (value: string, language: string) => void
-});
-
-// API Methods
-editor.getValue()           // Get current code
-editor.setValue(code)       // Set code content
-editor.getLanguage()        // Get current language
-editor.setLanguage(lang)    // Set programming language
-editor.focus()              // Focus the editor
-editor.selectAll()          // Select all content
-editor.insertText(text)     // Insert text at cursor
-```
+```tsx
+import { DestinationDemo } from '@walkeros/explorer';
+import { getEvent } from '@walkeros/core';
+import destinationPlausible from '@walkeros/web-destination-plausible';
+import { examples } from '@walkeros/web-destination-plausible';
 
-### Preview
-
-HTML preview component with iframe sandboxing and error handling.
-
-```typescript
-const preview = createPreview(elementOrSelector, {
-  html: string,
-  height: string,
-  sandbox: boolean,
-  showErrors: boolean,
-  onLoad: (iframe) => void,
-  onError: (error) => void
-});
-
-// API Methods
-preview.setHTML(html)                    // Set HTML content
-preview.getHTML()                        // Get current HTML
-preview.refresh()                        // Refresh preview
-preview.executeScript(script)            // Execute script in preview
-preview.injectCSS(css)                   // Inject CSS into preview
+// Attach examples to destination for auto-capture
+const destination = { ...destinationPlausible, examples };
+
+<DestinationDemo
+  destination={destination}
+  event={getEvent('order complete')}
+  mapping={examples.mapping.purchase}
+  settings={{ domain: 'elbwalker.com' }}
+  generic={true}
+/>
 ```
 
-### ResultDisplay
-
-Display execution results with multiple result types and formatting.
-
-```typescript
-const results = createResultDisplay(elementOrSelector, {
-  maxResults: number,
-  height: string,
-  autoScroll: boolean
-});
-
-// API Methods
-results.addValue(value, label?)          // Add value result
-results.addError(error, label?)          // Add error result
-results.addLog(message, label?)          // Add log result
-results.addWarning(message, label?)      // Add warning result
-results.addInfo(message, label?)         // Add info result
-results.clear()                          // Clear all results
-results.getResults()                     // Get all results
+The component auto-detects `destination.examples.env.push` and uses it to capture function calls.
+
+**Props:**
+- `destination`: Destination instance with `examples.env.push` export
+- `event`: walkerOS event to process
+- `mapping`: Optional mapping rules (object or JSON string)
+- `settings`: Destination-specific settings
+- `generic`: If true, wraps mapping in `{ '*': { '*': mapping } }`
+- `labelEvent`: Label for event panel (default: 'Event')
+- `labelMapping`: Label for mapping panel (default: 'Mapping')
+- `labelOutput`: Label for output panel (default: 'Result')
+
+#### DestinationInitDemo
+
+Interactive destination initialization testing. Automatically captures destination.init() calls and displays the output (script loading, configuration calls).
+
+**Simple Usage** (Recommended):
+
+```tsx
+import { DestinationInitDemo } from '@walkeros/explorer';
+import destinationGtag from '@walkeros/web-destination-gtag';
+import { examples } from '@walkeros/web-destination-gtag';
+
+// Attach examples to destination for auto-capture
+const destination = { ...destinationGtag, examples };
+
+<DestinationInitDemo
+  destination={destination}
+  settings={{
+    ga4: {
+      measurementId: 'G-XXXXXXXXXX',
+      debug: false,
+      pageview: false,
+    },
+  }}
+/>
 ```
 
-### LiveCode
-
-Combined code editor and preview for live HTML/CSS/JS development.
-
-```typescript
-const liveCode = createLiveCode(elementOrSelector, {
-  layout: 'horizontal' | 'vertical' | 'tabs',
-  showTabs: boolean,
-  showResults: boolean,
-  autoRun: boolean,
-  initialHTML: string,
-  initialCSS: string,
-  initialJS: string,
-  enableConsoleCapture: boolean,
-  onRun: (code) => void
-});
-
-// API Methods
-liveCode.getHTML()                       // Get HTML content
-liveCode.setHTML(html)                   // Set HTML content
-liveCode.getCSS()                        // Get CSS content
-liveCode.setCSS(css)                     // Set CSS content
-liveCode.getJS()                         // Get JavaScript content
-liveCode.setJS(js)                       // Set JavaScript content
-liveCode.run()                           // Execute code manually
-liveCode.clear()                         // Clear all editors
-liveCode.setLayout(layout)               // Change layout
+The component auto-detects `destination.examples.env.init` and uses it to capture function calls during initialization.
+
+**Props:**
+- `destination`: Destination instance with `examples.env.init` export
+- `settings`: Destination-specific settings (object or JSON string)
+- `labelSettings`: Label for settings panel (default: 'Settings')
+- `labelOutput`: Label for output panel (default: 'Result')
+
+**Use Cases:**
+- Testing destination initialization (script loading, gtag config calls)
+- Documenting initialization behavior
+- Debugging destination setup
+
+#### PromotionPlayground
+
+Interactive playground for walkerOS promotion events (used in documentation).
+
+### Organisms
+
+#### MappingBox
+
+Visual mapping configuration editor with code view toggle.
+
+```tsx
+import { MappingBox } from '@walkeros/explorer';
+
+<MappingBox
+  mapping={{
+    product: {
+      view: { name: 'view_item', data: { map: { value: 'data.price' } } },
+    },
+  }}
+  onMappingChange={setMapping}
+  label="GA4 Mapping"
+  useNewEditor={true}
+  showTree={true}
+/>;
 ```
 
-### EventFlow
-
-WalkerOS event visualization and debugging component.
-
-```typescript
-const eventFlow = createEventFlow(elementOrSelector, {
-  maxEvents: number,
-  showTimeline: boolean,
-  showFilters: boolean,
-  showMetrics: boolean,
-  groupByEntity: boolean,
-  onEventCapture: (event) => void,
-  onEventSelect: (event) => void
-});
-
-// API Methods
-eventFlow.addEvent(event)                // Add new event
-eventFlow.getEvents()                    // Get all events
-eventFlow.clearEvents()                  // Clear all events
-eventFlow.filterEvents(filter)           // Filter events
-eventFlow.exportEvents()                 // Export filtered events
-eventFlow.getMetrics()                   // Get performance metrics
+Features:
+
+- Visual/Code view toggle
+- Tab-based navigation
+- Tree sidebar with breadcrumbs
+- Property-focused editing panels
+- RJSF-based forms with custom widgets
+
+#### MappingEditorTabs
+
+Advanced tab-based mapping editor with tree navigation.
+
+```tsx
+import { MappingEditorTabs } from '@walkeros/explorer';
+
+<MappingEditorTabs
+  initialMapping={config}
+  onChange={handleChange}
+  layout="responsive"
+  showTree={true}
+/>;
 ```
 
-### Destination
-
-WalkerOS destination testing and configuration component.
-
-```typescript
-const destination = createDestination(elementOrSelector, {
-  initialConfig: DestinationConfig,
-  showTemplates: boolean,
-  showTesting: boolean,
-  enableValidation: boolean,
-  onConfigChange: (config) => void,
-  onTest: (config, event) => void
-});
-
-// API Methods
-destination.getConfig()                  // Get current configuration
-destination.setConfig(config)            // Set configuration
-destination.testDestination(event)       // Test with event
-destination.validateConfig()             // Validate configuration
-destination.exportConfig()               // Export config as JSON
-destination.importConfig(json)           // Import config from JSON
-destination.loadTemplate(name)           // Load predefined template
-destination.getAvailableTemplates()      // Get available templates
+Layouts:
+
+- `compact`: Single column, mobile-optimized (< 800px)
+- `medium`: Two columns with collapsible sidebar (800-1200px)
+- `wide`: Three columns with persistent sidebar (> 1200px)
+- `responsive`: Auto-detects based on viewport
+
+#### LiveCode
+
+Generic live code execution with input/config/output panels.
+
+```tsx
+<LiveCode
+  input={{ name: 'test event', data: {} }}
+  config={{ mapping: 'rules' }}
+  fn={async (input, config, log) => {
+    log('Processing...', input);
+  }}
+  fnName="myFunction"
+/>
 ```
 
-## 🧪 Testing
+#### CodePanel
 
-The project includes comprehensive testing with Jest and JSDOM:
+Monaco editor with label and formatting controls.
 
-```bash
-# Run all tests
-npm run test
+```tsx
+<CodePanel
+  label="Configuration"
+  value='{"key": "value"}'
+  language="json"
+  onChange={setValue}
+/>
+```
 
-# Run tests in watch mode
-npm run test:watch
+#### BrowserBox
 
-# Run specific test file
-npm run test foundation.test.ts
+Multi-tab code editor (HTML/CSS/JS) with live preview.
 
-# Run tests with coverage
-npm run test:coverage
+```tsx
+<BrowserBox
+  html="<div>Hello</div>"
+  css="div { color: red; }"
+  js="console.log('loaded')"
+  onHtmlChange={setHtml}
+  showPreview={true}
+  initialTab="preview"
+/>
 ```
 
-### Test Coverage
+#### CollectorBox
+
+Displays collector processing with mapping and destination output.
 
-- **101 total tests** across 4 test suites
-- **Foundation tests (27)** - Core utilities and base components
-- **Phase 2 tests (47)** - Individual component functionality
-- **Phase 3 tests (27)** - Composite component integration
-- **Quick tests** - Fast smoke tests for CI/CD
+```tsx
+<CollectorBox
+  event='{"name": "page view"}'
+  mapping='{"page": {"view": {"name": "pageview"}}}'
+  destination={destination}
+/>
+```
 
-## 🎨 Demos
+### Molecules
 
-Interactive demos are included to showcase all components:
+#### CodeEditor
 
-### Phase 2 Demo
+Monaco Editor wrapper.
 
-```bash
-# Serves demo-phase2.html
-npm run demo:phase2
+```tsx
+<CodeEditor
+  value="console.log('hello')"
+  language="javascript"
+  onChange={setValue}
+/>
 ```
 
-Features individual components with interactive controls.
+#### Preview
 
-### Phase 3 Demo
+HTML preview in isolated iframe with walkerOS event capture.
 
-```bash
-# Serves demo-phase3.html
-npm run demo:phase3
+```tsx
+<Preview
+  html="<div data-elb='product'>Item</div>"
+  css="div { padding: 20px; }"
+  onEvent={(event) => console.log(event)}
+/>
 ```
 
-Features composite components with real-world examples.
+#### MappingTreeSidebar
 
-## 🔧 Development
+Hierarchical tree view for mapping navigation.
 
-### Project Structure
+```tsx
+import { MappingTreeSidebar } from '@walkeros/explorer';
 
+<MappingTreeSidebar
+  config={mappingConfig}
+  currentPath={['product', 'view']}
+  expandedPaths={expandedPaths}
+  visible={true}
+  onToggle={handleToggle}
+  onNavigate={handleNavigate}
+  onAddAction={handleAddAction}
+  onAddEntity={handleAddEntity}
+/>;
 ```
-src/
-├── core/                 # Foundation components
-│   ├── Component.ts      # Base component factory
-│   └── EventBus.ts       # Global event system
-├── components/           # All components
-│   ├── CodeEditor.ts     # Code editor component
-│   ├── Preview.ts        # HTML preview component
-│   ├── ResultDisplay.ts  # Results display component
-│   ├── LiveCode.ts       # Live coding component
-│   ├── EventFlow.ts      # Event visualization component
-│   └── Destination.ts    # Destination testing component
-├── utils/                # Utility functions
-│   ├── dom.ts            # DOM manipulation utilities
-│   ├── debounce.ts       # Performance utilities
-│   └── syntax.ts         # Syntax highlighting
-└── __tests__/            # Test suites
-    ├── foundation.test.ts
-    ├── phase2-components.test.ts
-    └── phase3-composites.test.ts
+
+#### AutoSelect
+
+Dropdown with autocomplete for key selection.
+
+```tsx
+import { AutoSelect } from '@walkeros/explorer';
+
+<AutoSelect
+  value={selectedKey}
+  options={['data.id', 'data.name', 'user.email']}
+  onChange={setValue}
+  placeholder="Select property..."
+/>;
 ```
 
-### Build System
+### Atoms
 
-```bash
-# Development build with watch
-npm run dev
+#### Box, Header, Button, ButtonGroup
 
-# Production build
-npm run build
+Basic UI building blocks. See exported types for prop details.
 
-# Type checking
-npm run type-check
+```tsx
+import { Box, Button, ButtonGroup } from '@walkeros/explorer';
 
-# Linting
-npm run lint
+<Box header="Title" resizable={true}>
+  <ButtonGroup
+    buttons={[
+      { label: 'Option 1', value: '1', active: true },
+      { label: 'Option 2', value: '2', active: false },
+    ]}
+    onButtonClick={handleClick}
+  />
+</Box>;
 ```
 
-The project uses:
+#### Toggle
+
+Theme-aware toggle switch component.
 
-- **tsup** for building with multiple output formats (ESM, CJS, IIFE)
-- **TypeScript** for type safety and IntelliSense
-- **Jest** with JSDOM for testing
-- **ESLint** for code quality
+```tsx
+import { Toggle } from '@walkeros/explorer';
 
-## 🎯 Use Cases
+<Toggle checked={isEnabled} onChange={setIsEnabled} label="Enable feature" />;
+```
 
-### Development Tools
+### Helpers
 
-Create interactive code playgrounds and documentation with live examples.
+#### Destination Creators
 
-```typescript
-const playground = createLiveCode('#playground', {
-  layout: 'horizontal',
-  initialHTML: '<div>Interactive example</div>',
-  onRun: (code) => console.log('Code executed:', code),
-});
+```tsx
+import {
+  createGtagDestination,
+  createFbqDestination,
+  createPlausibleDestination,
+} from '@walkeros/explorer';
+
+const gtag = createGtagDestination();
+gtag.env = { elb: (output) => console.log(output) };
 ```
 
-### Event Debugging
+## Styling
+
+**Complete styling documentation:** [STYLE.md](./STYLE.md)
 
-Monitor and debug walkerOS events in real-time.
+### Quick Start
 
-```typescript
-const debugger = createEventFlow('#debugger', {
-  showMetrics: true,
-  onEventCapture: (event) => {
-    console.log('Event captured:', event);
-    // Send to analytics, log to server, etc.
-  }
-});
+```tsx
+import '@walkeros/explorer/styles.css';
 ```
 
-### Destination Testing
+```html
+<!-- Theme switching -->
+<html data-theme="dark">...</html>
+```
 
-Test and configure walkerOS destinations with built-in templates.
+### Customization
 
-```typescript
-const tester = createDestination('#tester', {
-  showTemplates: true,
-  onTest: (config, event) => {
-    console.log('Testing destination:', config.name);
-  },
-});
+```css
+.my-app .elb-explorer {
+  --color-button-primary: #ff6b35;
+  --bg-box: #fafafa;
+  --font-size-base: 16px;
+}
 ```
 
-## 📖 Documentation
+**See [STYLE.md](./STYLE.md) for:**
+- Complete Theme Variables Reference (all CSS variables)
+- Grid System (height modes, implementation)
+- Monaco Editor (theming, tokens, IntelliSense)
+- SCSS Architecture & Design Rules
+- Common Tasks & Troubleshooting
+
+### Component Styling Guidelines
+
+When contributing components:
 
-- **[API Reference](./API.md)** - Complete API documentation
-- **[Testing Guide](./TESTING.md)** - Testing strategy and best practices
-- **[Development Guidelines](./DEVELOPMENT_GUIDELINES.md)** - Development best
-  practices
+**✅ DO:**
 
-## 🌟 Key Benefits
+- Use CSS classes with the `elb-` prefix
+- Use CSS variables for colors, spacing, typography
+- Support both light and dark themes
+- Use responsive design patterns
+- Reuse existing components and styles
 
-### For Developers
+**❌ DON'T:**
 
-- **Zero Learning Curve** - Familiar functional patterns
-- **Full TypeScript Support** - Complete IntelliSense and type safety
-- **Composable Architecture** - Use individual components or combine them
-- **Performance Optimized** - Debounced updates and efficient rendering
+- Use inline `style` attributes
+- Hardcode colors or spacing values
+- Create duplicate components
+- Use theme-specific selectors in component files
+- Use magic numbers (use CSS variables instead)
 
-### For Teams
+### SCSS Architecture (CRITICAL - Must Follow Exactly)
 
-- **Consistent Architecture** - Functional factory pattern across all components
-- **Comprehensive Testing** - High test coverage with automated CI/CD
-- **Documentation** - Complete API docs and usage examples
-- **Maintenance** - Clean, well-organized codebase
+**IMPORTANCE**: The explorer uses a strict, modular SCSS architecture. All new
+components MUST follow the established patterns. Non-compliance breaks the
+design system.
 
-### For Projects
+**Architecture:**
 
-- **Framework Agnostic** - Works with any framework or vanilla JS
-- **Theme Support** - Built-in light/dark mode compatibility
-- **Responsive Design** - Works on desktop, tablet, and mobile
-- **Accessibility** - ARIA support and keyboard navigation
+```
+src/styles/
+├── index.scss              # Main entry point (import new components here)
+├── theme/
+│   ├── _tokens.scss        # SCSS tokens ($spacing-md: 12px, $radius-sm: 3px)
+│   ├── _variables.scss     # CSS variables (--bg-input, --color-text, etc.)
+│   └── _dark.scss          # Dark theme overrides
+├── foundation/
+│   ├── _reset.scss
+│   ├── _typography.scss
+│   ├── _layout.scss        # Grid/flex mixins
+│   ├── _spacing.scss       # Spacing mixins
+│   └── _responsive.scss    # Breakpoint mixins
+└── components/
+    ├── atoms/              # _button.scss, _consent-widget.scss, etc.
+    ├── molecules/          # _rjsf-form.scss, _mapping-editor.scss, etc.
+    └── organisms/          # _box.scss, _mapping-box.scss, etc.
+```
+
+#### SCSS Compliance Rules (MANDATORY)
+
+**✅ DO:**
+
+1. **Use ONLY defined CSS variables** from `theme/_variables.scss`:
+   - `--bg-input`, `--border-input`, `--radius-button` (standard form elements)
+   - `--color-text`, `--color-text-muted`, `--color-text-label` (typography)
+   - `--font-family-base`, `--font-mono` (fonts)
+   - `--font-size-base` (base font size)
+2. **Use `calc()` for font size variations**:
+   - Small text: `calc(var(--font-size-base) - 1px)` (NOT `--font-size-sm`)
+   - Tiny text: `calc(var(--font-size-base) - 2px)` (NOT `--font-size-xs`)
+3. **Follow BEM naming**: `elb-{component}-{element}--{modifier}`
+   - Example: `.elb-settings-widget-wrapper`, `.elb-settings-widget-form`
+4. **Use standard gaps**: `12px` for vertical spacing in flex/grid layouts
+5. **One file per component**: Create `_component-name.scss` in appropriate
+   directory
+6. **Import alphabetically**: Add `@use './components/atoms/your-widget';` in
+   `index.scss`
+
+**❌ DON'T:**
+
+1. **NEVER use undefined CSS variables**:
+   - ❌ `--bg-secondary`, `--bg-code`, `--border-subtle`, `--radius-base` (don't
+     exist)
+   - ❌ `--font-size-sm`, `--font-size-xs` (don't exist as CSS variables)
+   - ❌ `--font-family-mono` (should be `--font-mono`)
+2. **NEVER hardcode values** that have CSS variable equivalents
+3. **NEVER skip the wrapper pattern**: All widgets need `elb-rjsf-widget` →
+   `elb-{name}-widget-wrapper`
+4. **NEVER create duplicate styles** - check existing components first
+
+#### CSS Variable Reference (Commonly Used)
+
+```scss
+// Backgrounds
+--bg-input: #ffffff; // Form inputs, fallback containers
+--bg-input-hover: #f9f9f9; // Hover states
+
+// Borders
+--border-input: #d1d5db; // Form inputs, containers
+--border-input-focus: #3b82f6; // Focus states
+
+// Border Radius
+--radius-button: 3px; // Forms, small elements
+--radius-box: 4px; // Boxes, containers
+
+// Typography
+--color-text: #000; // Primary text
+--color-text-muted: #666; // Secondary/hint text
+--color-text-label: #424242; // Labels
+--font-family-base: system-ui, ...; // Body text
+--font-mono: 'SF Mono', ...; // Code blocks
+--font-size-base: 14px; // Base size
+
+// Buttons
+--color-button-primary: #3b82f6; // Primary actions
+--color-button-danger: #ef4444; // Destructive actions
+```
+
+**Full list**: See `src/styles/theme/_variables.scss`
+
+#### Example: Widget SCSS (Correct Pattern)
+
+```scss
+// _my-widget.scss
+.elb-my-widget-wrapper {
+  width: 100%;
+}
+
+.elb-my-widget-form {
+  display: flex;
+  flex-direction: column;
+  gap: 12px; // Standard gap
+}
+
+.elb-my-widget-hint {
+  font-size: calc(var(--font-size-base) - 1px); // ✅ Correct
+  color: var(--color-text-muted); // ✅ Defined variable
+  margin: 0;
+}
+
+.elb-my-widget-code {
+  padding: 12px;
+  background-color: var(--bg-input); // ✅ Defined variable
+  border: 1px solid var(--border-input); // ✅ Defined variable
+  border-radius: var(--radius-button); // ✅ Defined variable
+  font-family: var(--font-mono); // ✅ Correct variable name
+}
+```
+
+#### Verification Checklist
+
+Before submitting SCSS changes:
+
+- [ ] All CSS variables exist in `theme/_variables.scss`
+- [ ] No hardcoded colors, spacing, or font sizes (use CSS variables)
+- [ ] BEM naming convention followed (`elb-{component}-{element}`)
+- [ ] File imported in `index.scss` (alphabetical order)
+- [ ] Build succeeds: `npm run build`
+- [ ] Component matches pattern of similar existing components
+- [ ] Tested in both light and dark themes
+
+See [LAYOUT.md](./LAYOUT.md) for the complete SCSS migration plan.
+
+## Development
+
+```bash
+npm install        # Install dependencies
+npm run start      # Start Vite dev server
+npm test           # Run tests
+npm run build      # Build package
+npm run lint       # Lint code
+```
+
+### Contributing Components
+
+Follow these principles when creating new components:
+
+1. **Atomic Design**: Place components in correct directory
+   (atoms/molecules/organisms)
+2. **Reusability**: Extract shared logic into hooks, shared styles into SCSS
+   modules
+3. **Theme Support**: Use CSS variables, test both light/dark themes
+4. **No Inline Styles**: All styling via CSS classes
+5. **TypeScript**: Strict typing, export all public types
+6. **Accessibility**: Semantic HTML, ARIA attributes, keyboard navigation
+7. **RJSF Patterns**: Follow Field/Widget separation for RJSF components (see
+   [PATTERNS.md](./PATTERNS.md))
+
+### RJSF Component Architecture (CRITICAL)
+
+**When creating RJSF custom components, you MUST follow the Field/Widget
+separation pattern.**
+
+See [PATTERNS.md](./PATTERNS.md) for comprehensive documentation of:
+
+- **Field/Widget Separation**: Mandatory two-layer architecture
+- **Component Composition**: MappingCollapsible, MappingFormWrapper, IconButton
+- **State Management**: Controlled state, external sync, deduplication
+- **Data Flow**: Schema passing via `ui:options`, props threading
+- **CSS Conventions**: BEM with `elb-` prefix
+- **Common Utilities**: `cleanFormData`, type guards, validators
+- **Anti-Patterns**: What NOT to do (with examples)
+
+**Quick Reference - All RJSF Components:**
+
+| Field                   | Widget                   | Purpose                   |
+| ----------------------- | ------------------------ | ------------------------- |
+| `MappingConsentField`   | `MappingConsentWidget`   | Consent states (checkbox) |
+| `MappingConditionField` | `MappingConditionWidget` | Condition code editor     |
+| `MappingDataField`      | `MappingDataWidget`      | Data transformation rows  |
+| `MappingGlobalsField`   | `MappingGlobalsWidget`   | Global properties         |
+| `MappingContextField`   | `MappingContextWidget`   | Context properties        |
+| `MappingNestedField`    | `MappingNestedWidget`    | Nested entities           |
+| `MappingSettingsField`  | `MappingSettingsWidget`  | Destination settings      |
+
+**Field responsibilities** (~20 lines):
+
+- Convert `FieldProps` → `WidgetProps`
+- Pass through props (id, value, onChange, schema, uiSchema, rawErrors,
+  disabled, readonly)
+- No UI logic
+
+**Widget responsibilities** (100-300 lines):
+
+- Implement full UI using standard building blocks
+- Manage component state (expand/collapse, show/hide, previous values)
+- Handle form changes and cleanup
+- Sync with external value changes via `useEffect`
+- Use `MappingCollapsible` for toggle/checkbox UI
+- Use `MappingFormWrapper` for nested forms
+- Use `IconButton` for actions
+- Use `cleanFormData` to remove empty values
+
+See [PATTERNS.md](./PATTERNS.md) for detailed examples and implementation
+checklist.
+
+### Component Checklist
+
+**Before submitting any component:**
+
+- [ ] Component placed in correct atomic layer (atoms/molecules/organisms)
+- [ ] TypeScript types exported from component file
+- [ ] **SCSS compliance verified** (see SCSS Architecture section above):
+  - [ ] All CSS variables exist in `theme/_variables.scss`
+  - [ ] BEM naming: `elb-{component}-{element}`
+  - [ ] SCSS file created in correct directory (`atoms/`, `molecules/`,
+        `organisms/`)
+  - [ ] SCSS imported in `index.scss` (alphabetical order)
+  - [ ] No hardcoded values (colors, spacing, fonts)
+  - [ ] Uses `calc(var(--font-size-base) - Npx)` for size variations
+- [ ] Light and dark theme tested
+- [ ] No inline `style` attributes
+- [ ] Responsive design considered
+- [ ] Reuses existing components where possible (MappingCollapsible, IconButton,
+      etc.)
+- [ ] **RJSF components follow Field/Widget separation pattern** (see
+      [PATTERNS.md](./PATTERNS.md))
+- [ ] Build succeeds: `npm run build`
+- [ ] Exported from `src/index.ts` (if public API)
+
+## Monaco Editor Height Management
+
+The explorer uses Monaco Editor with a flexible, responsive height system that works across all contexts.
+
+### Height Modes
+
+CodeBox supports three height modes:
+
+1. **Default (height="100%")**: Fills parent container
+   - Use in Grid contexts for equal row heights
+   - Use in Flex contexts to fill available space
+   - Requires parent with explicit height or bounded context
+
+2. **Auto-height (autoHeight prop)**: Dynamically sizes to content
+   - Grows/shrinks based on Monaco's content height
+   - Respects min/max boundaries (customizable)
+   - Eliminates blank space in standalone contexts
+   - Updates automatically when content changes
+
+3. **Explicit height**: Fixed pixel or viewport height
+   - Override with `height` prop (e.g., `height="600px"` or `height="50vh"`)
+
+### Usage Examples
+
+**Grid Context - Equal Heights:**
+```tsx
+// Don't use autoHeight - maintains equal row heights
+<Grid columns={3}>
+  <CodeBox code={event} label="Event" />
+  <CodeBox code={mapping} label="Mapping" />
+  <CodeBox code={output} label="Output" />
+</Grid>
+```
+
+**Standalone - Content-Based Height:**
+```tsx
+// Use autoHeight to eliminate blank space
+<CodeBox
+  code={setupExample}
+  label="Setup"
+  autoHeight={{ min: 100, max: 600 }}
+  disabled
+/>
+```
+
+**Flex Context - Fill Parent:**
+```tsx
+// Don't use autoHeight - fills available flex space
+<div style={{ display: 'flex', flexDirection: 'column', height: '100vh' }}>
+  <CodeBox code={largeConfig} onChange={setConfig} />
+</div>
+```
+
+**Explicit Height Override:**
+```tsx
+<CodeBox code={longCode} height="600px" />
+```
 
-## 🚀 Roadmap
+### How Auto-Height Works
 
-### Immediate (Phase 5)
+When `autoHeight` is enabled:
+1. Monaco Editor's `getContentHeight()` API measures actual content height
+2. Hook listens to `onDidContentSizeChange` events (debounced)
+3. Height calculated and bounded by min/max values
+4. Monaco receives explicit pixel height (e.g., `height="347px"`)
+5. Updates automatically on content changes, typing, or formatting
 
-- [x] Complete testing suite
-- [x] Comprehensive documentation
-- [x] Interactive demos
-- [ ] Performance optimizations
-- [ ] Accessibility improvements
+**Technical Details:**
+- Uses `useMonacoHeight` hook with Monaco's official APIs
+- Avoids infinite loops by not calling `layout()` in content change handler
+- Includes overhead calculation for header/borders (45px)
+- Default boundaries: min=100px, max=600px (customizable)
 
-### Short Term
+### Key Files
 
-- [ ] npm package publication
-- [ ] CDN builds for easy integration
-- [ ] React wrapper components
-- [ ] Storybook integration
+- `explorer/src/components/atoms/code.tsx` - Monaco wrapper with autoHeight integration
+- `explorer/src/hooks/useMonacoHeight.ts` - Content height calculation hook
+- `explorer/src/styles/components/atoms/_code.scss` - Flex-based Monaco container
+- `explorer/src/styles/components/organisms/_box.scss` - Context-specific height rules
 
-### Long Term
+### Troubleshooting
 
-- [ ] Browser extension for debugging
-- [ ] VS Code extension integration
-- [ ] Advanced theming system
-- [ ] Plugin architecture for extensibility
+**Monaco shows wrong height?**
+- Check parent context: Grid, Flex, or standalone?
+- Grid/Flex: Don't use autoHeight (use default height="100%")
+- Standalone: Add `autoHeight={{ min: 100, max: 600 }}`
+- Override with explicit `height` prop if needed
 
-## 🤝 Contributing
+**AutoHeight not working?**
+- Ensure Monaco has mounted (check browser console for errors)
+- Verify min/max boundaries aren't too restrictive
+- Check that content is actually rendering (empty code = min height)
 
-1. Follow the functional factory pattern established in the codebase
-2. Add comprehensive tests for new functionality
-3. Update documentation and type definitions
-4. Ensure all tests pass: `npm run test`
-5. Follow TypeScript best practices
+**Height grows infinitely?**
+- Should not happen with current implementation
+- Hook avoids calling `layout()` in content change handler
+- Report if you encounter this bug
 
-## 📄 License
+## Browser Support
 
-Part of the walkerOS project. See the main repository for license information.
+Chrome 80+, Firefox 75+, Safari 13+, Edge 80+
 
-## 🔗 Links
+## License
 
-- **walkerOS Documentation**: https://docs.walkerOS.com
-- **GitHub Repository**: https://github.com/elbwalker/walkerOS
-- **Issues**: https://github.com/elbwalker/walkerOS/issues
+MIT