@kustomizer/visual-editor 0.0.1

package/README.md

@@ -0,0 +1,641 @@
+# Visual Editor
+
+Librería Angular para crear editores visuales drag & drop estilo Shopify Customizer. Permite registrar componentes personalizados desde la aplicación consumidora con schema de propiedades y soporte para slots/children.
+
+## Instalación
+
+La librería requiere NgRx como peer dependency:
+
+```bash
+npm install @ngrx/store @ngrx/effects
+```
+
+## Configuración Inicial
+
+### 1. Configurar providers en app.config.ts
+
+```typescript
+import { ApplicationConfig } from '@angular/core';
+import { provideStore } from '@ngrx/store';
+import { provideStoreDevtools } from '@ngrx/store-devtools';
+import {
+  provideVisualEditorStore,
+  provideEditorComponents,
+} from '@kustomizer/visual-editor';
+
+// Importar definiciones de componentes
+import { heroSectionDefinition } from './editor-components/hero-section.definition';
+import { textBlockDefinition } from './editor-components/text-block.definition';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    // NgRx Store (requerido)
+    provideStore(),
+    provideStoreDevtools({ maxAge: 25 }),
+
+    // Visual Editor Store
+    provideVisualEditorStore(),
+
+    // Registrar componentes del editor
+    provideEditorComponents([
+      heroSectionDefinition,
+      textBlockDefinition,
+    ]),
+  ],
+};
+```
+
+## Crear Componentes para el Editor
+
+### Paso 1: Crear el componente Angular
+
+```typescript
+// hero-section.component.ts
+import { Component, ChangeDetectionStrategy, input, computed } from '@angular/core';
+import { SlotRendererComponent, EditorElement } from '@kustomizer/visual-editor';
+
+@Component({
+  selector: 'app-hero-section',
+  imports: [SlotRendererComponent],
+  template: `
+    <section
+      class="hero"
+      [style.backgroundColor]="backgroundColor()"
+      [style.color]="textColor()"
+      [style.minHeight.vh]="height()"
+    >
+      <div class="hero-content">
+        <h1>{{ title() }}</h1>
+        @if (subtitle()) {
+          <p>{{ subtitle() }}</p>
+        }
+        @if (ctaText()) {
+          <a [href]="ctaUrl()" class="cta-button">
+            {{ ctaText() }}
+          </a>
+        }
+
+        <!-- Renderizar children en el slot -->
+        @if (_children()?.length) {
+          <div class="hero-extra">
+            <lib-slot-renderer
+              [slot]="contentSlot"
+              [children]="_children()!"
+              [parentElementId]="_elementId()"
+            />
+          </div>
+        }
+      </div>
+    </section>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class HeroSectionComponent {
+  // Props editables (vienen del editor)
+  readonly title = input('Welcome');
+  readonly subtitle = input('');
+  readonly backgroundColor = input('#1a1a2e');
+  readonly textColor = input('#ffffff');
+  readonly height = input(80);
+  readonly ctaText = input('');
+  readonly ctaUrl = input('/');
+
+  // Props especiales del editor (opcionales)
+  readonly _elementId = input('');
+  readonly _children = input<EditorElement[] | undefined>(undefined);
+  readonly _context = input<Record<string, unknown>>({});
+
+  // Definición del slot para el renderer
+  readonly contentSlot = {
+    name: 'content',
+    label: 'Additional Content',
+    constraints: { maxItems: 3 },
+  };
+}
+```
+
+### Paso 2: Crear la definición del componente
+
+```typescript
+// hero-section.definition.ts
+import { ComponentDefinition } from '@kustomizer/visual-editor';
+import { HeroSectionComponent } from './hero-section.component';
+
+export const heroSectionDefinition: ComponentDefinition = {
+  // Identificador único (debe coincidir con EditorSection.type)
+  type: 'hero-section',
+
+  // Metadata para el panel de componentes
+  name: 'Hero Section',
+  description: 'Banner principal con título, subtítulo y CTA',
+  category: 'layout',
+  icon: 'panorama',
+  tags: ['hero', 'banner', 'header'],
+  order: 1,
+
+  // Referencia al componente Angular
+  component: HeroSectionComponent,
+
+  // Indica que es una sección (contenedor principal)
+  isSection: true,
+
+  // Permisos
+  draggable: true,
+  deletable: true,
+  duplicable: true,
+
+  // Schema de propiedades editables
+  props: {
+    title: {
+      type: 'string',
+      label: 'Título',
+      description: 'Texto principal del hero',
+      defaultValue: 'Welcome',
+      placeholder: 'Ingresa el título...',
+      validation: {
+        required: true,
+        maxLength: 100,
+      },
+      group: 'Contenido',
+      order: 1,
+    },
+    subtitle: {
+      type: 'string',
+      label: 'Subtítulo',
+      defaultValue: '',
+      placeholder: 'Texto secundario...',
+      validation: { maxLength: 200 },
+      group: 'Contenido',
+      order: 2,
+    },
+    backgroundColor: {
+      type: 'color',
+      label: 'Color de fondo',
+      defaultValue: '#1a1a2e',
+      group: 'Apariencia',
+      order: 1,
+    },
+    textColor: {
+      type: 'color',
+      label: 'Color de texto',
+      defaultValue: '#ffffff',
+      group: 'Apariencia',
+      order: 2,
+    },
+    height: {
+      type: 'range',
+      label: 'Altura (vh)',
+      defaultValue: 80,
+      validation: { min: 30, max: 100 },
+      step: 5,
+      group: 'Layout',
+      order: 1,
+    },
+    ctaText: {
+      type: 'string',
+      label: 'Texto del botón',
+      defaultValue: '',
+      placeholder: 'Shop Now',
+      group: 'CTA',
+      order: 1,
+    },
+    ctaUrl: {
+      type: 'url',
+      label: 'URL del botón',
+      defaultValue: '/',
+      placeholder: 'https://...',
+      group: 'CTA',
+      order: 2,
+    },
+  },
+
+  // Slots para componentes hijos
+  slots: [
+    {
+      name: 'content',
+      label: 'Contenido adicional',
+      description: 'Elementos extra debajo del CTA',
+      constraints: {
+        allowedTypes: ['text-block', 'button', 'image'],
+        maxItems: 3,
+      },
+      emptyPlaceholder: 'Arrastra elementos aquí',
+    },
+  ],
+};
+```
+
+## Usar el Editor
+
+### VisualEditorFacade
+
+El facade es el punto de entrada principal para interactuar con el editor:
+
+```typescript
+import { Component, inject } from '@angular/core';
+import {
+  VisualEditorFacade,
+  DynamicRendererComponent,
+} from '@kustomizer/visual-editor';
+
+@Component({
+  selector: 'app-editor',
+  imports: [DynamicRendererComponent],
+  template: `
+    <div class="editor-layout">
+      <!-- Panel de componentes -->
+      <aside class="components-panel">
+        <h3>Secciones</h3>
+        @for (def of facade.availableSections(); track def.type) {
+          <button (click)="facade.addSection(def.type)">
+            {{ def.name }}
+          </button>
+        }
+
+        <h3>Elementos</h3>
+        @for (def of facade.availableElements(); track def.type) {
+          <button (click)="addElementToSelected(def.type)">
+            {{ def.name }}
+          </button>
+        }
+      </aside>
+
+      <!-- Canvas del editor -->
+      <main class="editor-canvas">
+        @for (section of facade.sections(); track section.id) {
+          <div
+            class="section-wrapper"
+            [class.selected]="facade.selectedSection()?.id === section.id"
+            (click)="facade.selectElement(section.id, null)"
+          >
+            <lib-dynamic-renderer
+              [element]="section"
+              [context]="{ isEditor: true }"
+            />
+          </div>
+        }
+      </main>
+
+      <!-- Panel de propiedades -->
+      <aside class="properties-panel">
+        @if (facade.selectedSectionDefinition(); as def) {
+          <h3>{{ def.name }}</h3>
+          <!-- Renderizar inputs según def.props -->
+        }
+      </aside>
+    </div>
+
+    <!-- Controles de historial -->
+    <div class="toolbar">
+      <button [disabled]="!facade.canUndo()" (click)="facade.undo()">
+        Undo
+      </button>
+      <button [disabled]="!facade.canRedo()" (click)="facade.redo()">
+        Redo
+      </button>
+    </div>
+  `,
+})
+export class EditorComponent {
+  readonly facade = inject(VisualEditorFacade);
+
+  addElementToSelected(type: string): void {
+    const section = this.facade.selectedSection();
+    if (section) {
+      this.facade.addElement(section.id, type);
+    }
+  }
+}
+```
+
+### Métodos del Facade
+
+```typescript
+// === Crear ===
+facade.addSection('hero-section');              // Agrega sección con props por defecto
+facade.addSection('hero-section', 0);           // Agrega en índice específico
+facade.addElement(sectionId, 'text-block');     // Agrega elemento a sección
+facade.addElement(sectionId, 'text-block', 2);  // Agrega en índice específico
+
+// === Eliminar ===
+facade.removeSection(sectionId);
+facade.removeElement(sectionId, elementId);
+
+// === Mover ===
+facade.moveSection(sectionId, newIndex);
+facade.moveElement(sourceSectionId, targetSectionId, elementId, newIndex);
+
+// === Selección ===
+facade.selectElement(sectionId, elementId);
+facade.selectElement(sectionId, null);  // Selecciona solo la sección
+facade.clearSelection();
+
+// === Actualizar props ===
+facade.updateSectionProps(sectionId, { title: 'New Title' });
+facade.updateElementProps(sectionId, elementId, { text: 'Updated' });
+
+// === Historial ===
+facade.undo();
+facade.redo();
+
+// === Cargar/Reset ===
+facade.loadSections(sectionsArray);  // Carga estado inicial
+facade.resetEditor();                // Limpia todo
+
+// === Consultas ===
+facade.getDefinition('hero-section');  // Obtiene ComponentDefinition
+facade.searchComponents('hero');       // Busca por nombre/tags
+```
+
+### Signals Disponibles
+
+```typescript
+facade.sections()                    // EditorSection[]
+facade.selectedSection()             // EditorSection | null
+facade.selectedElement()             // EditorElement | null
+facade.selectedSectionDefinition()   // ComponentDefinition | null
+facade.selectedElementDefinition()   // ComponentDefinition | null
+facade.availableSections()           // ComponentDefinition[]
+facade.availableElements()           // ComponentDefinition[]
+facade.canUndo()                     // boolean
+facade.canRedo()                     // boolean
+facade.isDragging()                  // boolean
+```
+
+## API Reference
+
+### ComponentDefinition
+
+```typescript
+interface ComponentDefinition {
+  type: string;                    // Identificador único
+  name: string;                    // Nombre visible
+  description?: string;            // Descripción
+  category: ComponentCategory;     // 'layout' | 'content' | 'media' | 'form' | 'navigation' | 'commerce' | 'custom'
+  icon?: string;                   // Nombre de icono o URL
+  component: Type<unknown>;        // Componente Angular
+  props: PropSchemaMap;            // Schema de propiedades
+  slots?: SlotDefinition[];        // Slots para children
+  isSection?: boolean;             // true = contenedor principal
+  draggable?: boolean;             // Permite reordenar
+  deletable?: boolean;             // Permite eliminar
+  duplicable?: boolean;            // Permite duplicar
+  thumbnail?: string;              // URL de preview
+  tags?: string[];                 // Tags para búsqueda
+  order?: number;                  // Orden en lista (menor = primero)
+}
+```
+
+### PropSchema
+
+```typescript
+interface PropSchema<T = unknown> {
+  type: PropType;                  // Tipo de la propiedad
+  label: string;                   // Label en el panel
+  description?: string;            // Tooltip/ayuda
+  defaultValue: T;                 // Valor por defecto
+  placeholder?: string;            // Placeholder para inputs
+  validation?: PropValidation;     // Reglas de validación
+  condition?: PropCondition;       // Mostrar/ocultar condicionalmente
+  group?: string;                  // Agrupar en el panel
+  order?: number;                  // Orden dentro del grupo
+  options?: SelectOption[];        // Para type: 'select'
+  step?: number;                   // Para type: 'range'
+  accept?: string[];               // Para type: 'image' (mime types)
+}
+
+type PropType =
+  | 'string'     // Input de texto
+  | 'number'     // Input numérico
+  | 'boolean'    // Checkbox/toggle
+  | 'color'      // Color picker
+  | 'image'      // Selector de imagen
+  | 'url'        // Input de URL
+  | 'richtext'   // Editor de texto rico
+  | 'select'     // Dropdown
+  | 'range'      // Slider
+  | 'json';      // Editor JSON
+```
+
+### SlotDefinition
+
+```typescript
+interface SlotDefinition {
+  name: string;                    // ID único del slot
+  label: string;                   // Label visible
+  description?: string;            // Descripción
+  constraints?: SlotConstraints;   // Restricciones
+  emptyPlaceholder?: string;       // Texto cuando está vacío
+  droppable?: boolean;             // Permite drop (default: true)
+}
+
+interface SlotConstraints {
+  allowedTypes?: string[];         // Tipos permitidos
+  disallowedTypes?: string[];      // Tipos prohibidos
+  minItems?: number;               // Mínimo de elementos
+  maxItems?: number;               // Máximo de elementos
+}
+```
+
+### ComponentRegistryService
+
+Acceso directo al registro (el Facade lo usa internamente):
+
+```typescript
+import { ComponentRegistryService } from '@kustomizer/visual-editor';
+
+@Component({...})
+export class MyComponent {
+  private registry = inject(ComponentRegistryService);
+
+  ngOnInit() {
+    // Obtener definición
+    const def = this.registry.get('hero-section');
+
+    // Obtener componente Angular
+    const component = this.registry.getComponent('hero-section');
+
+    // Obtener schema de props
+    const propsSchema = this.registry.getPropsSchema('hero-section');
+
+    // Obtener slots
+    const slots = this.registry.getSlots('hero-section');
+
+    // Generar props por defecto
+    const defaults = this.registry.getDefaultProps('hero-section');
+
+    // Validar props
+    const errors = this.registry.validateProps('hero-section', {
+      title: '',  // Faltaría si es required
+    });
+
+    // Buscar componentes
+    const results = this.registry.search('hero');
+
+    // Filtrar por categoría
+    const layouts = this.registry.getByCategory('layout');
+
+    // Obtener todos
+    const all = this.registry.getAll();
+    const sections = this.registry.getSections();
+    const elements = this.registry.getElements();
+  }
+}
+```
+
+## Renderizado Dinámico
+
+### DynamicRendererComponent
+
+Renderiza cualquier `EditorElement` o `EditorSection` basándose en su `type`:
+
+```typescript
+import { DynamicRendererComponent } from '@kustomizer/visual-editor';
+
+@Component({
+  imports: [DynamicRendererComponent],
+  template: `
+    @for (section of sections; track section.id) {
+      <lib-dynamic-renderer
+        [element]="section"
+        [context]="{ mode: 'preview' }"
+      />
+    }
+  `,
+})
+export class PreviewComponent {
+  sections: EditorSection[] = [];
+}
+```
+
+### SlotRendererComponent
+
+Renderiza children dentro de un slot específico:
+
+```typescript
+import { SlotRendererComponent, EditorElement } from '@kustomizer/visual-editor';
+
+@Component({
+  imports: [SlotRendererComponent],
+  template: `
+    <div class="my-component">
+      <h1>{{ title() }}</h1>
+
+      <!-- Slot para contenido -->
+      <div class="content-area">
+        <lib-slot-renderer
+          [slot]="contentSlot"
+          [children]="_children() ?? []"
+          [parentElementId]="_elementId()"
+        />
+      </div>
+    </div>
+  `,
+})
+export class MyComponent {
+  readonly title = input('');
+  readonly _elementId = input('');
+  readonly _children = input<EditorElement[]>();
+
+  readonly contentSlot = {
+    name: 'content',
+    label: 'Content',
+    constraints: { allowedTypes: ['text', 'image'] },
+    emptyPlaceholder: 'Drop content here',
+  };
+}
+```
+
+## Estado del Store (NgRx)
+
+### Estructura del State
+
+```typescript
+interface VisualEditorState {
+  sections: EditorSection[];           // Secciones del editor
+  selectedElementId: string | null;    // ID del elemento seleccionado
+  selectedSectionId: string | null;    // ID de la sección seleccionada
+  isDragging: boolean;                 // Estado de drag
+  draggedElementId: string | null;     // ID del elemento siendo arrastrado
+  history: HistoryEntry[];             // Historial para undo/redo
+  historyIndex: number;                // Posición actual en el historial
+  maxHistorySize: number;              // Máximo de entradas (default: 50)
+}
+
+interface EditorSection {
+  id: string;
+  type: string;                        // Referencia a ComponentDefinition.type
+  props: Record<string, unknown>;
+  elements: EditorElement[];
+}
+
+interface EditorElement {
+  id: string;
+  type: string;                        // Referencia a ComponentDefinition.type
+  props: Record<string, unknown>;
+  children?: EditorElement[];          // Para slots anidados
+}
+```
+
+### Acciones Disponibles
+
+```typescript
+import { VisualEditorActions } from '@kustomizer/visual-editor';
+
+// Secciones
+VisualEditorActions.addSection({ section, index? })
+VisualEditorActions.removeSection({ sectionId })
+VisualEditorActions.moveSection({ sectionId, newIndex })
+VisualEditorActions.updateSection({ sectionId, changes })
+VisualEditorActions.updateSectionProps({ sectionId, props })
+
+// Elementos
+VisualEditorActions.addElement({ sectionId, element, index? })
+VisualEditorActions.removeElement({ sectionId, elementId })
+VisualEditorActions.moveElement({ sourceSectionId, targetSectionId, elementId, newIndex })
+VisualEditorActions.updateElement({ sectionId, elementId, changes })
+VisualEditorActions.updateElementProps({ sectionId, elementId, props })
+
+// Selección
+VisualEditorActions.selectElement({ sectionId, elementId })
+VisualEditorActions.clearSelection()
+
+// Drag & Drop
+VisualEditorActions.startDrag({ elementId })
+VisualEditorActions.endDrag()
+
+// Historial
+VisualEditorActions.undo()
+VisualEditorActions.redo()
+VisualEditorActions.clearHistory()
+
+// Bulk
+VisualEditorActions.loadSections({ sections })
+VisualEditorActions.resetEditor()
+```
+
+### Selectores
+
+```typescript
+import {
+  selectSections,
+  selectSelectedElement,
+  selectSelectedSection,
+  selectSelectedElementType,
+  selectSelectedSectionType,
+  selectCanUndo,
+  selectCanRedo,
+  selectIsDragging,
+  selectHistory,
+  selectSectionById,
+  selectElementById,
+} from '@kustomizer/visual-editor';
+```
+
+## Build
+
+```bash
+ng build visual-editor
+```
+
+Los artefactos se generan en `dist/visual-editor`.