@bagelink/blox 1.5.15 → 1.5.17

package/setup.ts

@@ -1,26 +1,428 @@
 /**
  * Blox Setup and Registration
  *
- * Handles automatic registration of base components and provides
- * configuration helpers for external projects.
+ * Provides a simple, fluent API for setting up the Blox library
  */
 
+import type { App } from 'vue'
+import type { Router } from 'vue-router'
 import { baseComponentConfigs, type ComponentConfig } from './config/baseComponents'
-import { registerComponent, registerComponents } from './core/registry'
+import { registerComponent, registerComponents as registerComponentsInRegistry } from './core/registry'
+import ExternalPreview from './views/ExternalPreview.vue'
+import RenderPage from './views/RenderPage.vue'
+
+export interface BloxInstance {
+	/**
+	 * Register one or more components with the Blox library
+	 * Accepts either a single component config or an array of component configs
+	 */
+	registerComponents: (
+		components: ComponentConfig | ComponentConfig[],
+		options?: RegisterOptions
+	) => BloxInstance
+
+	/**
+	 * Register routes for preview pages with your Vue Router
+	 */
+	registerRoutes: (router: Router, options?: RouteOptions) => BloxInstance
+
+	/**
+	 * Get all registered component configurations
+	 */
+	getRegisteredComponents: () => ComponentConfig[]
+
+	/**
+	 * Get components by category
+	 */
+	getComponentsByCategory: (category: string) => ComponentConfig[]
+
+	/**
+	 * Get a list of registered component IDs
+	 */
+	getComponentIds: () => string[]
+
+	/**
+	 * Check if a component is registered
+	 */
+	hasComponent: (id: string) => boolean
+
+	/**
+	 * Install the Blox plugin into your Vue app
+	 */
+	install: (app: App) => void
+}
+
+export interface RegisterOptions {
+	/**
+	 * Category to assign to the components
+	 */
+	category?: string
+
+	/**
+	 * Skip validation for component configs
+	 * @default false
+	 */
+	skipValidation?: boolean
+}
+
+export interface RouteOptions {
+	/**
+	 * Base path for the preview routes
+	 * @default '/blox'
+	 */
+	basePath?: string
+
+	/**
+	 * Path for the external preview route
+	 * @default '/preview/:pageId?'
+	 */
+	previewPath?: string
+
+	/**
+	 * Path for the render page route
+	 * @default '/render/:pageId?'
+	 */
+	renderPath?: string
+
+	/**
+	 * Additional route meta properties
+	 */
+	meta?: Record<string, any>
+}
+
+export interface BloxOptions {
+	/**
+	 * Enable debug mode for additional logging
+	 * @default false
+	 */
+	debug?: boolean
+
+	/**
+	 * Automatically register base components on first registerComponents call
+	 * @default true
+	 */
+	autoRegisterBaseComponents?: boolean
+}
 
 /**
- * Register all base components from the library
- * Call this in your project's setup to make base components available
+ * Validation error class
  */
-export function registerBaseComponents(): void {
-	const componentMap: Record<string, any> = {}
+export class ComponentValidationError extends Error {
+	constructor(message: string, public componentId?: string) {
+		super(message)
+		this.name = 'ComponentValidationError'
+	}
+}
 
-	baseComponentConfigs.forEach((config) => {
-		componentMap[config.id] = config.component
-	})
+/**
+ * Validate a component configuration
+ */
+function validateComponentConfig(config: ComponentConfig): void {
+	const errors: string[] = []
 
-	registerComponents(componentMap)
-	console.log('✅ Registered base components:', Object.keys(componentMap))
+	if (!config.id || typeof config.id !== 'string') {
+		errors.push('Component must have a valid "id" (string)')
+	}
+
+	if (!config.label || typeof config.label !== 'string') {
+		errors.push('Component must have a valid "label" (string)')
+	}
+
+	if (!config.component) {
+		errors.push('Component must have a "component" property (Vue component or async function)')
+	}
+
+	if (config.component && typeof config.component !== 'function' && typeof config.component !== 'object') {
+		errors.push('Component "component" must be a Vue component or async function')
+	}
+
+	if (config.content && !Array.isArray(config.content)) {
+		errors.push('Component "content" must be an array')
+	}
+
+	if (config.settings && !Array.isArray(config.settings)) {
+		errors.push('Component "settings" must be an array')
+	}
+
+	if (errors.length > 0) {
+		throw new ComponentValidationError(
+			`Invalid component configuration for "${config.id || 'unknown'}":\n${errors.map(e => `  - ${e}`).join('\n')}`,
+			config.id
+		)
+	}
+}
+
+/**
+ * Calculate Levenshtein distance between two strings
+ * Used for "did you mean" suggestions
+ */
+function levenshteinDistance(a: string, b: string): number {
+	const matrix: number[][] = []
+
+	for (let i = 0; i <= b.length; i++) {
+		matrix[i] = [i]
+	}
+
+	for (let j = 0; j <= a.length; j++) {
+		matrix[0][j] = j
+	}
+
+	for (let i = 1; i <= b.length; i++) {
+		for (let j = 1; j <= a.length; j++) {
+			if (b.charAt(i - 1) === a.charAt(j - 1)) {
+				matrix[i][j] = matrix[i - 1][j - 1]
+			} else {
+				matrix[i][j] = Math.min(
+					matrix[i - 1][j - 1] + 1,
+					matrix[i][j - 1] + 1,
+					matrix[i - 1][j] + 1
+				)
+			}
+		}
+	}
+
+	return matrix[b.length][a.length]
+}
+
+/**
+ * Find similar component IDs (for "did you mean" suggestions)
+ */
+function findSimilarIds(targetId: string, allIds: string[], maxSuggestions: number = 3): string[] {
+	return allIds
+		.map(id => ({ id, distance: levenshteinDistance(targetId.toLowerCase(), id.toLowerCase()) }))
+		.filter(item => item.distance <= 3) // Only show suggestions within 3 edits
+		.sort((a, b) => a.distance - b.distance)
+		.slice(0, maxSuggestions)
+		.map(item => item.id)
+}
+
+/**
+ * Create better error message for missing component
+ */
+function createMissingComponentError(id: string, registeredIds: string[]): Error {
+	const suggestions = findSimilarIds(id, registeredIds)
+	let message = `Component "${id}" is not registered.`
+
+	if (suggestions.length > 0) {
+		message += `\n\nDid you mean: ${suggestions.map(s => `"${s}"`).join(', ')}?`
+	}
+
+	message += `\n\nAvailable components: ${registeredIds.join(', ')}`
+
+	return new Error(message)
+}
+
+/**
+ * Create a new Blox instance with a fluent API
+ *
+ * @param options - Configuration options for the Blox instance
+ *
+ * @example
+ * ```ts
+ * import { createBlox, ButtonConfig, TextConfig } from '@bagelink/blox'
+ * import { MyCustomComp } from './components'
+ *
+ * const blox = createBlox({ debug: true })
+ * blox.registerComponents([ButtonConfig, TextConfig, MyCustomComp])
+ * blox.registerRoutes(router)
+ *
+ * app.use(blox)
+ * ```
+ */
+export function createBlox(options: BloxOptions = {}): BloxInstance {
+	const {
+		debug = false,
+		autoRegisterBaseComponents = true,
+	} = options
+
+	const registeredConfigs: ComponentConfig[] = []
+	let hasRegisteredBaseComponents = false
+
+	const log = (...args: any[]) => {
+		if (debug) {
+			console.log('[Blox]', ...args)
+		}
+	}
+
+	const instance: BloxInstance = {
+		registerComponents(
+			components: ComponentConfig | ComponentConfig[],
+			registerOptions: RegisterOptions = {}
+		) {
+			const { category, skipValidation = false } = registerOptions
+			const configs = Array.isArray(components) ? components : [components]
+
+			// Auto-register base components on first call if enabled
+			if (!hasRegisteredBaseComponents && autoRegisterBaseComponents) {
+				const componentMap: Record<string, any> = {}
+				baseComponentConfigs.forEach((config) => {
+					componentMap[config.id] = config.component
+					registeredConfigs.push(config)
+				})
+				registerComponentsInRegistry(componentMap)
+				hasRegisteredBaseComponents = true
+				log('Registered base components:', Object.keys(componentMap))
+				if (!debug) {
+					console.log('✅ Registered base components:', Object.keys(componentMap))
+				}
+			}
+
+			// Register the provided components
+			configs.forEach((config) => {
+				// Validate config
+				if (!skipValidation) {
+					try {
+						validateComponentConfig(config)
+					} catch (error) {
+						if (error instanceof ComponentValidationError) {
+							console.error('❌ Component validation failed:')
+							console.error(error.message)
+							if (debug) {
+								console.error('Component config:', config)
+							}
+							throw error
+						}
+						throw error
+					}
+				}
+
+				// Apply category if provided in options
+				const finalConfig = category ? { ...config, category } : config
+
+				// Check for duplicate IDs
+				if (registeredConfigs.some(c => c.id === finalConfig.id)) {
+					const msg = `Component "${finalConfig.id}" is already registered. Overwriting...`
+					console.warn(`⚠️  ${msg}`)
+					const index = registeredConfigs.findIndex(c => c.id === finalConfig.id)
+					registeredConfigs.splice(index, 1)
+				}
+
+				// For async components, store the factory function
+				// They will be resolved when actually needed
+				registerComponent(finalConfig.id, finalConfig.component)
+				registeredConfigs.push(finalConfig)
+
+				const categoryMsg = finalConfig.category ? ` (${finalConfig.category})` : ''
+				log(`Registered component: ${finalConfig.id}${categoryMsg}`)
+				if (!debug) {
+					console.log(`✅ Registered component: ${finalConfig.id}${categoryMsg}`)
+				}
+			})
+
+			return instance
+		},
+
+		registerRoutes(router: Router, routeOptions: RouteOptions = {}) {
+			const {
+				basePath = '/blox',
+				previewPath = '/preview/:pageId?',
+				renderPath = '/render/:pageId?',
+				meta = {},
+			} = routeOptions
+
+			// Add the external preview route
+			router.addRoute({
+				path: `${basePath}${previewPath}`,
+				name: 'blox-preview',
+				component: ExternalPreview,
+				meta: { blox: true, ...meta },
+			})
+
+			// Add the render page route
+			router.addRoute({
+				path: `${basePath}${renderPath}`,
+				name: 'blox-render',
+				component: RenderPage,
+				meta: { blox: true, ...meta },
+			})
+
+			const routes = {
+				preview: `${basePath}${previewPath}`,
+				render: `${basePath}${renderPath}`,
+			}
+			log('Registered Blox routes:', routes)
+			if (!debug) {
+				console.log('✅ Registered Blox routes:', routes)
+			}
+
+			return instance
+		},
+
+		getRegisteredComponents() {
+			return [...registeredConfigs]
+		},
+
+		getComponentsByCategory(category: string) {
+			return registeredConfigs.filter(config => config.category === category)
+		},
+
+		getComponentIds() {
+			return registeredConfigs.map(config => config.id)
+		},
+
+		hasComponent(id: string) {
+			return registeredConfigs.some(config => config.id === id)
+		},
+
+		install(app: App) {
+			// Make the registered configs available globally
+			app.config.globalProperties.$blox = {
+				configs: registeredConfigs,
+				getComponent: (id: string) => {
+					const config = registeredConfigs.find(c => c.id === id)
+					if (!config && debug) {
+						const error = createMissingComponentError(id, this.getComponentIds())
+						console.error(error.message)
+					}
+					return config
+				},
+				getComponentsByCategory: (category: string) => this.getComponentsByCategory(category),
+				hasComponent: (id: string) => registeredConfigs.some(c => c.id === id),
+			}
+
+			// Provide for composition API
+			app.provide('blox', {
+				configs: registeredConfigs,
+				getComponent: (id: string) => {
+					const config = registeredConfigs.find(c => c.id === id)
+					if (!config && debug) {
+						const error = createMissingComponentError(id, this.getComponentIds())
+						console.error(error.message)
+					}
+					return config
+				},
+				getComponentsByCategory: (category: string) => this.getComponentsByCategory(category),
+				hasComponent: (id: string) => registeredConfigs.some(c => c.id === id),
+			})
+
+			log('Blox plugin installed with', registeredConfigs.length, 'components')
+			if (!debug) {
+				console.log('✅ Blox plugin installed')
+			}
+
+			if (debug) {
+				console.log('[Blox] Registered components:', this.getComponentIds())
+				const categories = [
+					...new Set(
+						registeredConfigs
+							.map(c => c.category)
+							.filter((cat): cat is string => Boolean(cat))
+					)
+				]
+				console.log('[Blox] Categories:', categories)
+				console.log('[Blox] Debug mode enabled')
+			}
+		},
+	}
+
+	return instance
+}
+
+/**
+ * Helper to create a custom component configuration with better TypeScript inference
+ */
+export function createComponentConfig<T extends ComponentConfig>(config: T): T {
+	return config
 }
 
 /**
@@ -32,14 +434,26 @@ export function getAllComponentConfigs(customConfigs: ComponentConfig[] = []): C
 }
 
 /**
- * Helper to create a custom component configuration
+ * Register all base components from the library
+ * Call this in your project's setup to make base components available
+ *
+ * @deprecated Use `createBlox().registerComponents()` instead for a simpler API
  */
-export function createComponentConfig(config: ComponentConfig): ComponentConfig {
-	return config
+export function registerBaseComponents(): void {
+	const componentMap: Record<string, any> = {}
+
+	baseComponentConfigs.forEach((config) => {
+		componentMap[config.id] = config.component
+	})
+
+	registerComponentsInRegistry(componentMap)
+	console.log('✅ Registered base components:', Object.keys(componentMap))
 }
 
 /**
  * Register a single custom component
+ *
+ * @deprecated Use `createBlox().registerComponents()` instead for a simpler API
  */
 export function registerCustomComponent(config: ComponentConfig): void {
 	registerComponent(config.id, config.component)
@@ -48,6 +462,8 @@ export function registerCustomComponent(config: ComponentConfig): void {
 
 /**
  * Register multiple custom components
+ *
+ * @deprecated Use `createBlox().registerComponents()` instead for a simpler API
  */
 export function registerCustomComponents(configs: ComponentConfig[]): void {
 	configs.forEach((config) => {

package/views/ExternalPreview.vue

@@ -44,7 +44,8 @@ const registeredComponents = getAllComponents()
 
 // Reactive computed for block styles
 const getBlockStyles = computed(() => {
-	const _ = updateCounter.value
+	// Access updateCounter to trigger reactivity
+	console.log('updateCounter', updateCounter.value)
 	return (data: Record<string, any>, mobile: boolean = false) => generateBlockStyles(data, mobile)
 })
 
@@ -258,13 +259,10 @@ onUnmounted(() => {
 
 		<template v-for="comp in components" :key="comp.id">
 			<div
-				class="blox-block-wrapper"
-				:class="{
+				class="blox-block-wrapper" :class="{
 					'blox-highlight': !previewMode && highlightID === comp.id,
 					'blox-selected': !previewMode && selectedID === comp.id,
-				}"
-				:data-block-id="comp.id"
-				@click="!previewMode ? setFocus(comp.id, true) : null"
+				}" :data-block-id="comp.id" @click="!previewMode ? setFocus(comp.id, true) : null"
 				@mouseenter="!previewMode ? setHighlight(comp.id, true) : null"
 				@focus="!previewMode ? setHighlight(comp.id, true) : null"
 			>
@@ -276,14 +274,11 @@ onUnmounted(() => {
 
 				<!-- Block content -->
 				<div
-					:id="comp.data.customId"
-					:key="`${comp.id}-${updateCounter}`"
-					:style="getBlockStyles(comp.data, isMobile)"
-					:class="getResponsiveClasses(comp.data)"
+					:id="comp.data.customId" :key="`${comp.id}-${updateCounter}`"
+					:style="getBlockStyles(comp.data, isMobile)" :class="getResponsiveClasses(comp.data)"
 				>
 					<component
-						:is="registeredComponents[comp.type]"
-						v-if="registeredComponents[comp.type]"
+						:is="registeredComponents[comp.type]" v-if="registeredComponents[comp.type]"
 						v-bind="{ ...normalizeComponentData(comp.data), isMobile }"
 					/>
 					<div v-else class="blox-missing-component">

package/views/RenderPage.vue

@@ -32,8 +32,8 @@ const registeredComponents = getAllComponents()
 
 // Reactive computed for block styles
 const getBlockStyles = computed(() => {
-	// eslint-disable-next-line no-unused-vars
-	const _ = updateCounter.value
+	// Access updateCounter to trigger reactivity
+	console.log('updateCounter', updateCounter.value)
 	return (data: Record<string, any>, mobile: boolean = false) => generateBlockStyles(data, mobile)
 })