@bagelink/blox 1.5.3

package/README.md

@@ -0,0 +1,844 @@
+# @bagelink/blox
+
+Blox is a Vue 3 library for building drag-and-drop page builders and managing static data for web applications. It provides a complete solution for creating external preview systems and rendering dynamic page content.
+
+## Features
+
+- 🎨 **Page Builder Integration** - Full support for drag-and-drop page building
+- 📄 **Static Page Management** - Manage JSON-based static page data
+- 🔌 **Component Registry** - Flexible component registration system
+- 📡 **Communication System** - Built-in messaging for builder-preview communication
+- 🎯 **Type-Safe** - Full TypeScript support
+- 🖼️ **Base Components** - Pre-built components (Button, Text, Image, etc.)
+- 📱 **Responsive** - Mobile and desktop support
+
+## Installation
+
+```bash
+npm install @bagelink/blox
+# or
+pnpm add @bagelink/blox
+# or
+yarn add @bagelink/blox
+```
+
+## Quick Start
+
+### 1. Register Base Components
+
+```typescript
+import { createApp } from 'vue'
+import { registerBaseComponents } from '@bagelink/blox'
+
+const app = createApp(App)
+
+// Register all base components
+registerBaseComponents(app)
+
+app.mount('#app')
+```
+
+### 2. Use the RenderPage Component
+
+```vue
+<template>
+  <RenderPage :page-data="pageData" />
+</template>
+
+<script setup lang="ts">
+import { RenderPage } from '@bagelink/blox'
+
+const pageData = {
+  components: [...],
+  pageSettings: {...}
+}
+</script>
+```
+
+### 3. Use ExternalPreview for Page Builder
+
+```vue
+<template>
+  <ExternalPreview :origin="editorOrigin" />
+</template>
+
+<script setup lang="ts">
+import { ExternalPreview } from '@bagelink/blox'
+
+const editorOrigin = 'https://your-editor.com'
+</script>
+```
+
+## Core Concepts
+
+### Component Registry
+
+Register your custom components to make them available in the page builder:
+
+```typescript
+import { registerComponent, registerComponents } from '@bagelink/blox'
+import MyButton from './MyButton.vue'
+
+// Register a single component
+registerComponent('Button', MyButton)
+
+// Or register multiple components at once
+registerComponents({
+  Button: MyButton,
+  Hero: MyHero,
+  Text: MyText,
+})
+```
+
+### Communication System
+
+Blox includes a built-in communication system for coordinating between the builder and preview:
+
+```typescript
+import { createCommunicationBridge } from '@bagelink/blox'
+
+// Create a communication bridge
+const bridge = createCommunicationBridge({
+  origin: 'https://editor.com',
+  targetWindow: window.parent,
+})
+
+// Listen for messages
+bridge.on('update', ({ data }) => {
+  console.log('Received update:', data)
+})
+
+// Send messages
+bridge.send('ready', { components: ['Button', 'Hero'] })
+```
+
+### Styling Utilities
+
+Use the built-in styling utilities to apply consistent styles:
+
+```typescript
+import { generateBlockStyles, getResponsiveClasses } from '@bagelink/blox'
+
+const styles = generateBlockStyles(blockData, false)
+const classes = getResponsiveClasses(blockData)
+```
+
+## Base Components
+
+The library includes these pre-built components:
+
+- **Button** - Customizable button with variants
+- **Container** - Layout container with spacing
+- **Image** - Responsive image component
+- **Spacer** - Vertical/horizontal spacing
+- **Text** - Rich text content
+- **Title** - Heading component
+
+---
+
+## API Reference
+
+### Registry API
+
+#### `registerComponent(type: string, component: ComponentConstructor)`
+
+Register a single component.
+
+```typescript
+import { registerComponent } from '@bagelink/blox'
+import MyButton from './MyButton.vue'
+
+registerComponent('Button', MyButton)
+```
+
+**Parameters:**
+- `type` - The block type identifier (e.g., 'Button', 'Hero')
+- `component` - Vue component constructor or async import
+
+---
+
+#### `registerComponents(components: ComponentRegistry)`
+
+Register multiple components at once.
+
+```typescript
+import { registerComponents } from '@bagelink/blox'
+
+registerComponents({
+  Button: MyButton,
+  Hero: MyHero,
+  Text: MyText,
+})
+```
+
+**Parameters:**
+- `components` - Object mapping type names to components
+
+---
+
+#### `getComponent(type: string): ComponentConstructor | undefined`
+
+Get a registered component by type.
+
+```typescript
+const ButtonComponent = getComponent('Button')
+```
+
+---
+
+#### `hasComponent(type: string): boolean`
+
+Check if a component type is registered.
+
+```typescript
+if (hasComponent('Button')) {
+  // Button is registered
+}
+```
+
+---
+
+#### `getAllComponents(): ComponentRegistry`
+
+Get all registered components.
+
+```typescript
+const allComponents = getAllComponents()
+```
+
+---
+
+#### `unregisterComponent(type: string)`
+
+Remove a component from the registry.
+
+```typescript
+unregisterComponent('Button')
+```
+
+---
+
+#### `clearRegistry()`
+
+Remove all registered components.
+
+```typescript
+clearRegistry()
+```
+
+---
+
+#### `getRegisteredTypes(): string[]`
+
+Get array of all registered type names.
+
+```typescript
+const types = getRegisteredTypes()
+// ['Button', 'Hero', 'Text']
+```
+
+---
+
+#### `createNamespacedRegistry(namespace: string)`
+
+Create a namespaced registry for multi-tenant scenarios.
+
+```typescript
+const siteA = createNamespacedRegistry('site-a')
+siteA.register('Button', ButtonA)
+
+const siteB = createNamespacedRegistry('site-b')
+siteB.register('Button', ButtonB)
+```
+
+**Returns:** Object with methods:
+- `register(type, component)` - Register to namespace
+- `get(type)` - Get from namespace
+- `getAll()` - Get all from namespace
+
+---
+
+### Communication API
+
+#### `createCommunicationBridge(config: CommunicationConfig): CommunicationBridge`
+
+Create a communication bridge for postMessage communication.
+
+```typescript
+import { createCommunicationBridge } from '@bagelink/blox'
+
+const bridge = createCommunicationBridge({
+  origin: 'https://editor.com',
+  targetWindow: window.parent,
+})
+```
+
+**Parameters:**
+- `config.origin` - Allowed origin (string or '*')
+- `config.targetWindow` - Target window (default: window.parent)
+- `config.onMessage` - Optional global message handler
+
+---
+
+#### `CommunicationBridge.on(type: MessageType, handler: MessageHandler): () => void`
+
+Register a message handler.
+
+```typescript
+const unsubscribe = bridge.on('update', ({ data }) => {
+  console.log('Received update:', data)
+})
+
+// Later: unsubscribe()
+```
+
+**Parameters:**
+- `type` - Message type or '*' for all messages
+- `handler` - Handler function
+
+**Returns:** Unsubscribe function
+
+---
+
+#### `CommunicationBridge.off(type: MessageType, handler: MessageHandler)`
+
+Unregister a message handler.
+
+```typescript
+bridge.off('update', myHandler)
+```
+
+---
+
+#### `CommunicationBridge.send(type: MessageType, message?: any, data?: any)`
+
+Send a message to the target window.
+
+```typescript
+bridge.send('focus', 'block-123')
+bridge.send('update', null, { components: [...] })
+```
+
+**Parameters:**
+- `type` - Message type
+- `message` - Optional message payload
+- `data` - Optional data payload
+
+---
+
+#### `CommunicationBridge.destroy()`
+
+Clean up and remove all listeners.
+
+```typescript
+bridge.destroy()
+```
+
+---
+
+#### `sendMessage(type, message?, targetWindow?, origin?)`
+
+Send a one-off message without creating a bridge.
+
+```typescript
+import { sendMessage } from '@bagelink/blox'
+
+sendMessage('ready', { components: ['Button', 'Hero'] })
+```
+
+---
+
+### Renderer API
+
+#### `initializePage(pageData: PageData): Promise<void>`
+
+Initialize a page with all settings and assets.
+
+```typescript
+import { initializePage } from '@bagelink/blox'
+
+await initializePage(pageData)
+```
+
+**What it does:**
+- Injects responsive CSS
+- Applies page settings
+- Loads Google Fonts
+- Injects custom code
+
+---
+
+#### `injectResponsiveCSS()`
+
+Inject the responsive CSS system.
+
+```typescript
+import { injectResponsiveCSS } from '@bagelink/blox'
+
+injectResponsiveCSS()
+```
+
+---
+
+#### `injectCode(code: string | undefined, target: 'head' | 'body')`
+
+Inject custom code into head or body.
+
+```typescript
+injectCode('<script>console.log("Hello")</script>', 'head')
+```
+
+---
+
+#### `loadGoogleFont(fontName: string): Promise<void>`
+
+Load a Google Font.
+
+```typescript
+await loadGoogleFont('Roboto')
+```
+
+---
+
+#### `loadComponentFonts(components: ComponentData[]): Promise<void>`
+
+Load all fonts used in components.
+
+```typescript
+await loadComponentFonts(pageData.components)
+```
+
+---
+
+#### `applyGlobalFont(fontName: string)`
+
+Apply a font globally to the page.
+
+```typescript
+applyGlobalFont('Inter')
+```
+
+---
+
+#### `applyPageSettings(pageData: PageData)`
+
+Apply all page settings to the document.
+
+```typescript
+applyPageSettings(pageData)
+```
+
+---
+
+### Styles API
+
+#### `generateBlockStyles(data: Record<string, any>, isMobile?: boolean): Record<string, string>`
+
+Generate CSS styles from block data.
+
+```typescript
+import { generateBlockStyles } from '@bagelink/blox'
+
+const styles = generateBlockStyles(blockData, false)
+// { 'margin-top': '2rem', 'padding': '1rem', ... }
+```
+
+**Parameters:**
+- `data` - Block data object
+- `isMobile` - Whether to use mobile overrides (default: false)
+
+**Returns:** CSS styles object
+
+---
+
+#### `getResponsiveClasses(data: Record<string, any>): string[]`
+
+Get responsive CSS classes for a block.
+
+```typescript
+const classes = getResponsiveClasses(blockData)
+// ['blox-block', 'responsive-colors', 'full-width-mobile']
+```
+
+---
+
+#### `getResponsiveCSS(): string`
+
+Get the responsive CSS to inject.
+
+```typescript
+const css = getResponsiveCSS()
+```
+
+---
+
+### Normalizer API
+
+#### `normalizeComponentData(data: Record<string, any>): Record<string, any>`
+
+Normalize component data (convert string booleans, numbers, etc.).
+
+```typescript
+import { normalizeComponentData } from '@bagelink/blox'
+
+const normalized = normalizeComponentData({
+  width: '800',
+  fullWidth: 'true',
+  title: 'Hello',
+})
+// { width: 800, fullWidth: true, title: 'Hello' }
+```
+
+---
+
+#### `deepClone<T>(obj: T): T`
+
+Deep clone an object.
+
+```typescript
+const cloned = deepClone(originalData)
+```
+
+---
+
+#### `deepMerge(target: any, source: any): any`
+
+Deep merge two objects.
+
+```typescript
+const merged = deepMerge(defaults, customSettings)
+```
+
+---
+
+## Components
+
+### ExternalPreview
+
+Preview component for external sites.
+
+```vue
+<ExternalPreview 
+  :origin="editorOrigin"
+  :initial-page-data="pageData"
+/>
+```
+
+**Props:**
+- `origin?: string` - Allowed editor origin (default: '*')
+- `initialPageData?: PageData` - Optional initial page data
+
+**Events:**
+Communicates via postMessage with these message types:
+- `ready` - Sent when preview is ready
+- `focus` - Sent when block is focused
+- `highlight` - Sent when block is highlighted
+
+---
+
+### RenderPage
+
+Production render component.
+
+```vue
+<RenderPage 
+  :page-data="pageData"
+  :mobile-breakpoint="910"
+/>
+```
+
+**Props:**
+- `pageData: PageData` - **Required** page data to render
+- `mobileBreakpoint?: number` - Window width for mobile (default: 910)
+
+---
+
+## TypeScript Types
+
+### ComponentData
+
+```typescript
+interface ComponentData {
+  id: string
+  type: string
+  data: Record<string, any>
+}
+```
+
+---
+
+### PageData
+
+```typescript
+interface PageData {
+  id?: string
+  components: ComponentData[]
+  pageSettings?: PageSettings
+  header_code?: string
+  body_code?: string
+  language?: Record<string, any>
+}
+```
+
+---
+
+### PageSettings
+
+```typescript
+interface PageSettings {
+  selectedGoogleFont?: string
+  pageLanguage?: string
+  pageDirection?: 'ltr' | 'rtl'
+  additionalHeadCode?: string
+  additionalBodyCode?: string
+  customFavicon?: string
+  customOgImage?: string
+  customKeywords?: string
+  customRobotsMeta?: string
+  customAnalyticsCode?: string
+  disableGlobalHeadCode?: boolean
+  disableGlobalBodyCode?: boolean
+  disableGoogleAnalytics?: boolean
+  disableFacebookPixel?: boolean
+}
+```
+
+---
+
+### GlobalSettings
+
+```typescript
+interface GlobalSettings {
+  selectedGoogleFont?: string
+  pageLanguage?: string
+  pageDirection?: 'ltr' | 'rtl'
+  globalHeadCode?: string
+  globalBodyCode?: string
+  favicon?: string
+  ogImage?: string
+  siteKeywords?: string
+  googleAnalyticsId?: string
+  facebookPixelId?: string
+}
+```
+
+---
+
+### MessageType
+
+```typescript
+type MessageType =
+  | 'ready'
+  | 'update'
+  | 'focus'
+  | 'highlight'
+  | 'preview'
+  | 'meta'
+  | 'delete'
+  | 'disableLinks'
+  | 'newBlock'
+```
+
+---
+
+### EditorMessage
+
+```typescript
+interface EditorMessage {
+  type: MessageType
+  message?: any
+  data?: any
+  isMobile?: boolean
+}
+```
+
+---
+
+### BlockProps
+
+```typescript
+interface BlockProps {
+  isMobile?: boolean
+  [key: string]: any
+}
+```
+
+---
+
+### StyleConfig
+
+```typescript
+interface StyleConfig {
+  // Spacing
+  marginTop?: number
+  marginBottom?: number
+  marginTopMobile?: number
+  marginBottomMobile?: number
+  padding?: number
+  paddingMobile?: number
+
+  // Width
+  width?: number
+  widthMobile?: number
+  widthPercent?: number
+  widthPercentMobile?: number
+  fullWidth?: boolean
+  fullWidthMobile?: boolean
+
+  // Colors
+  backgroundColor?: string
+  backgroundColorMobile?: string
+  textColor?: string
+  textColorMobile?: string
+
+  // Border
+  borderWidth?: number
+  borderWidthMobile?: number
+  borderStyle?: string
+  borderStyleMobile?: string
+  borderColor?: string
+  borderColorMobile?: string
+  borderRadius?: number
+  borderRadiusMobile?: number
+
+  // Typography
+  fontFamily?: string
+  fontFamilyMobile?: string
+  center?: boolean
+  centerMobile?: boolean
+
+  // Effects
+  shadowType?: 'none' | 'sm' | 'md' | 'lg' | 'xl' | 'custom'
+  shadowTypeMobile?: 'none' | 'sm' | 'md' | 'lg' | 'xl' | 'custom'
+  zIndex?: number
+  zIndexMobile?: number
+
+  // Visibility
+  showDesktop?: boolean
+  showMobile?: boolean
+
+  // Custom
+  customId?: string
+  customCSS?: string
+}
+```
+
+---
+
+## Message Protocol
+
+### Editor → Preview
+
+#### `update`
+Update components data.
+
+```typescript
+{
+  type: 'update',
+  data: ComponentData[],
+  isMobile: boolean
+}
+```
+
+#### `focus`
+Focus a specific block.
+
+```typescript
+{
+  type: 'focus',
+  message: 'block-id-123'
+}
+```
+
+#### `highlight`
+Highlight a specific block.
+
+```typescript
+{
+  type: 'highlight',
+  message: 'block-id-123'
+}
+```
+
+#### `preview`
+Toggle preview mode.
+
+```typescript
+{
+  type: 'preview',
+  message: true | false
+}
+```
+
+#### `disableLinks`
+Disable link navigation.
+
+```typescript
+{
+  type: 'disableLinks',
+  message: true | false
+}
+```
+
+---
+
+### Preview → Editor
+
+#### `ready`
+Preview is ready.
+
+```typescript
+{
+  type: 'ready',
+  message: {
+    registeredTypes: string[]
+  }
+}
+```
+
+#### `focus`
+User focused a block.
+
+```typescript
+{
+  type: 'focus',
+  message: 'block-id-123'
+}
+```
+
+#### `highlight`
+User highlighted a block.
+
+```typescript
+{
+  type: 'highlight',
+  message: 'block-id-123'
+}
+```
+
+#### `delete`
+User wants to delete a block.
+
+```typescript
+{
+  type: 'delete',
+  message: 'block-id-123'
+}
+```
+
+---
+
+## Contributing
+
+Contributions are welcome! Please read our [Contributing Guide](../../CONTRIBUTING.md) for details.
+
+## License
+
+MIT © [Bagel Studio](https://bagelstudio.co.il)
+
+## Links
+
+- [GitHub Repository](https://github.com/bageldb/bagelink)
+- [Documentation](https://github.com/bageldb/bagelink/tree/master/packages/blox)
+- [Issues](https://github.com/bageldb/bagelink/issues)
+