Project Overview

Este documento proporciona una visión general completa del proyecto Responsive Widget Editor.

Metadatos del Proyecto

name: responsive-widget-editor
version: 1.0.0
framework: Angular 20
architecture: Monorepo (Nx)
style: Tailwind CSS
global_state: NGXS
local_state: Signals
testing: Jest, Cypress
linting: ESLint, Prettier

Estructura del Monorepo

Aplicaciones Principales

interface Apps {
  'editor-web': 'Aplicación principal del editor visual';
  'viewer-web': 'Visor de páginas publicadas';
  'admin-panel': 'Panel de administración';
  'ux-test': 'Aplicación de pruebas de UX';
  docs: 'Documentación del proyecto';
}

Librerías Core

interface CoreLibs {
  core: 'Modelos base, interfaces y estados';
  widgets: 'Componentes de widgets disponibles';
  'shared-ui': 'Directivas y componentes UI compartidos';
  'editor-ui': 'Componentes específicos del editor';
  'ux-widgets': 'Widgets específicos para UX';
}

Librerías de Características

interface FeatureLibs {
  'page-management': 'Gestión de páginas y jerarquía';
  'component-library': 'Sistema de componentes reutilizables';
  navigation: 'Sistema de navegación y menús';
  'data-binding': 'Conexión con fuentes de datos';
  auth: 'Autenticación y gestión de sesiones';
  permissions: 'Control de acceso granular';
  history: 'Sistema de historial y versionado';
  storage: 'Persistencia y sincronización';
  viewer: 'Componentes del visor';
}

Modelos de Datos

Widget Base

interface Widget {
  id: string;
  type: WidgetType;
  name: string;
  position: Position | ResponsiveValue<Position>;
  size: Size | ResponsiveValue<Size>;
  rotation: number | ResponsiveValue<number>;
  zIndex: number;
  styles: WidgetStyles | ResponsiveValue<WidgetStyles>;
  properties: Record<string, any>;
  dataBindings?: DataBinding[];
  parentId?: string;
  children?: Widget[];
  locked?: boolean;
  visible?: boolean | ResponsiveValue<boolean>;
  createdAt: Date;
  updatedAt: Date;
}

Estilos Normalizados

interface WidgetStyles {
  // Propiedades Base
  backgroundColor: string;
  color: string;
  opacity: number;

  // Bordes
  borderWidth: number;
  borderStyle: string;
  borderColor: string;
  borderRadius: number;

  // Espaciado
  padding: number | string;
  margin: number | string;

  // Tipografía
  fontSize: number;
  fontFamily: string;
  fontWeight: string;
  fontStyle: string;
  textAlign: string;

  // Layout
  display?: 'block' | 'flex' | 'grid' | 'inline' | 'inline-block' | 'inline-flex';
  position?: 'static' | 'relative' | 'absolute' | 'fixed' | 'sticky';

  // Flexbox
  flexDirection?: 'row' | 'column' | 'row-reverse' | 'column-reverse';
  justifyContent?: 'flex-start' | 'flex-end' | 'center' | 'space-between' | 'space-around';
  alignItems?: 'flex-start' | 'flex-end' | 'center' | 'stretch' | 'baseline';

  // Grid
  gridTemplateColumns?: string;
  gridTemplateRows?: string;
  gridGap?: string | number;

  // Efectos
  boxShadow?: string;
  transform?: string;
  filter?: string;
  backdropFilter?: string;

  // Estados
  hoverStyles?: Partial<WidgetStyles>;
  focusStyles?: Partial<WidgetStyles>;
  activeStyles?: Partial<WidgetStyles>;

  // Animaciones y Transiciones
  animation?: string;
  animations?: AnimationModel[];
  transition?: string;
  transitions?: TransitionModel[];

  // CSS Personalizado
  customCss?: Record<string, string>;
}

Componente

interface Component {
  id: string;
  name: string;
  description?: string;
  category: string;
  tags: string[];
  thumbnail?: string;
  widgets: Widget[];
  inputs: ComponentInput[];
  outputs: ComponentOutput[];
  version: string;
  author?: string;
  createdAt: Date;
  updatedAt: Date;
}

Página

interface Page {
  id: string;
  title: string;
  slug: string;
  description?: string;
  widgets: Widget[];
  parentId?: string;
  children?: Page[];
  layout: ResponsivePageLayout;
  meta: PageMeta;
  permissions: PagePermissions;
  status: PageStatus;
  version: number;
  createdAt: Date;
  updatedAt: Date;
  publishedAt?: Date;
  devicePreferences?: DevicePreferences;
}

Servicios Principales

ViewportService

interface ViewportService {
  currentBreakpoint: Signal<Breakpoint>;
  orientation: Signal<Orientation>;
  viewportSize: Signal<ViewportSize>;
  isBreakpoint(breakpoint: Breakpoint): boolean;
  getResponsiveValue<T>(value: ResponsiveValue<T>): T;
}

WidgetsStateService

interface WidgetsStateService {
  getAvailableWidgets(): Observable<WidgetDefinition[]>;
  createWidget(config: WidgetConfig): Observable<Widget>;
  updateWidget(id: string, widget: Widget): Observable<Widget>;
  deleteWidget(id: string): Observable<void>;
  cloneWidget(sourceWidget: Widget): Observable<Widget>;
  getWidgetById(id: string): Observable<Widget | null>;
}

EditorService

interface EditorService {
  selectedWidgets: Signal<Widget[]>;
  copySelectedWidgets(): void;
  pasteWidgets(): void;
  deleteSelectedWidgets(): void;
  updateWidgetById(id: string, updates: Partial<Widget>): void;
  updateWidgetResponsively(widget: Widget, property: string, value: any): void;
}

Sistema Responsivo

Breakpoints

type BreakpointKey = 'base' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';

interface Breakpoints {
  sm: number; // 640px
  md: number; // 768px
  lg: number; // 1024px
  xl: number; // 1280px
  '2xl': number; // 1536px
}

Valores Responsivos

interface ResponsiveValue<T> {
  base: T;
  sm?: T;
  md?: T;
  lg?: T;
  xl?: T;
  '2xl'?: T;
}

Exportación Multiplataforma

Formatos Soportados

interface ExportFormats {
  web: 'Componentes Angular';
  ios: 'SwiftUI/UIKit';
  android: 'Compose/XML';
  flutter: 'Widgets Flutter';
  'react-native': 'Componentes React Native';
}

Opciones de Exportación

interface ExportOptions {
  targetPlatform?: 'web' | 'ios' | 'android' | 'flutter' | 'react-native' | 'all';
  includeChildren?: boolean;
  normalizeUnits?: boolean;
  includeMetadata?: boolean;
  version?: string;
}

Reglas de Código

Reglas Generales

interface CodeRules {
  indentation: '2 espacios';
  quotes: 'comillas simples';
  strings: 'template literals';
  changeDetection: 'OnPush';
  state: {
    local: 'signals';
    global: 'NGXS';
  };
  typing: 'strict, sin any';
}

Orden de Importaciones

interface ImportOrder {
  1: '@angular/*';
  2: 'rxjs';
  3: '@widgets-editor/core';
  4: '@widgets-editor/shared-ui';
  5: 'feature-imports';
  6: './relative-paths';
}

Patrones Requeridos

interface RequiredPatterns {
  SOLID: true;
  DRY: true;
  componentStrategy: 'standalone';
  stateManagement: 'signals + NGXS';
  errorHandling: 'excepciones tipadas';
  asyncOperations: 'signals + observables';
}

Restricciones

interface Restrictions {
  noTimeouts: true;
  noAny: true;
  requireOnPush: true;
  requireTypeSafety: true;
  requireAtomicDesign: true;
}

Descripción Detallada del Proyecto

Visión General

Estamos desarrollando un editor de widgets modular altamente flexible y completamente responsivo, construido con Angular 20, que permite a los usuarios diseñar interfaces visuales mediante drag and drop. Esta herramienta permite la creación de páginas, componentes reutilizables y sistemas de navegación adaptables a cualquier dispositivo, con una arquitectura robusta que soporta extensibilidad, mantenibilidad y responsividad nativa.

Características Principales

1. Editor Visual Avanzado

   • Sistema de drag & drop optimizado
   • Soporte completo para responsividad
   • Gestión de estados por breakpoint
   • Sistema de grilla inteligente
   • Herramientas de alineación y distribución

2. Gestión de Estado

   • Estado global con NGXS
   • Estado local con Signals
   • Sistema de historial y deshacer/rehacer
   • Persistencia automática

3. Sistema Responsivo

   • Breakpoints predefinidos y personalizables
   • Herencia de valores entre breakpoints
   • Vista previa en tiempo real
   • Exportación multiplataforma

4. Componentes y Widgets

   • Biblioteca extensible de widgets
   • Sistema de componentes reutilizables
   • Propiedades y estilos responsivos
   • Validación por plataforma

5. Exportación y Compatibilidad

   • Exportación a múltiples plataformas
   • Normalización de unidades y estilos
   • Validación de compatibilidad
   • Generación de código nativo

Mejores Prácticas

1. Desarrollo

   • Componentes standalone
   • Detección de cambios OnPush
   • Tipado estricto
   • Pruebas unitarias y e2e

2. Rendimiento

   • Lazy loading de módulos
   • Optimización de renders
   • Memoización de cálculos
   • Virtual scrolling

3. Mantenibilidad

   • Arquitectura modular
   • Documentación inline
   • Convenciones de código
   • Sistema de logs

4. Seguridad

   • Sanitización de inputs
   • Validación de datos
   • Control de acceso
   • Auditoría de cambios