Reglas Editor

Vocabulario base (core/responsive)

• BreakpointKey: 'base' | 'sm' | 'md' | 'lg' | 'xl' | '2xl'
• DEFAULT_BREAKPOINTS: { base: 640, sm: 640, md: 768, lg: 1024, xl: 1280, '2xl': 1536 }
• ResponsiveValue: { base: T; sm?: T; md?: T; lg?: T; xl?: T; '2xl'?: T }
• Helpers: createResponsiveValue(base), createBaseResponsiveValue(base), isResponsiveValue(x), ensureResponsiveValue(x), getResponsiveValue(x, bp)

Regla de cascada de lectura: si no existe el valor en el breakpoint solicitado, se usa el más cercano definido hacia abajo, terminando en base.

Modelo Widget (core/models/widget.model.ts)

• Campos responsivos clave en Widget: position: ResponsiveValue<Position>, size: ResponsiveValue<Size>, styles: ResponsiveValue<WidgetStyles>, rotation: ResponsiveValue<number>, visible: ResponsiveValue<boolean>.
• createWidget(config) garantiza valores por defecto coherentes y responsivos.

Lectura y escritura de propiedades responsivas (core/utils + editor-ui/utils)

Lectura unificada por breakpoint (editor-ui/utils/responsive-widget-utils.ts)

• getCompletePositionForBreakpoint(widget, bp): Position
• getCompleteSizeForBreakpoint(widget, bp): Size
• getCompleteStylesForBreakpoint(widget, bp): WidgetStyles | undefined
• getSimplePropertyForBreakpoint(widget, 'rotation'|'visible', bp, default): T
• getWidgetProperty(widget, 'position'|'size'|'styles'|'rotation'|'visible', bp): any

Escritura unificada por breakpoint (editor-ui/utils/responsive-widget-utils.ts)

• updatePositionForBreakpoint(widget, position, bp): Widget
• updateSizeForBreakpoint(widget, size, bp): Widget
• updateStylesForBreakpoint(widget, styles, bp): Widget
• updateSimplePropertyForBreakpoint(widget, 'rotation'|'visible', value, bp): Widget
• updateWidgetProperty(widget, 'position'|'size'|'styles'|'rotation'|'visible', value, bp): Widget

Acceso fino a props (core/utils/responsive-helpers.ts)

• Posición: getWidgetPositionProp(widget, key, bp), setWidgetPositionProp(widget, key, value, bp)
• Tamaño: getWidgetSizeProp(widget, key, bp), setWidgetSizeProp(widget, key, value, bp)
• Estilos: getWidgetStyle(widget, key, bp), setWidgetStyle(widget, key, value, bp)
• Lecturas completas: getPositionForBreakpoint(widget, bp), getSizeForBreakpoint(widget, bp), getStylesForBreakpoint(widget, bp)
• Mapeos: mapWidgetSizeProps(widget, (prop,val)=>val2, bp), mapWidgetPositionProps(widget, (prop,val)=>val2, bp)
• Copia entre breakpoints: copyBreakpointProperties(widget, sourceBp, targetBp)

Unidades y formateo (core/utils/responsive-utils.ts y helpers.ts)

• Medidas: formatWithUnit(num, unit), parseValueAndUnit(str|num), convertUnit(value, from, to, contextSize)
• Tamaño en unidades: setWidgetWidth(widget, value, unit, bp), setWidgetHeight(widget, value, unit, bp)
• Lectura con unidad: getWidgetWidth(widget, bp) -> { value, unit }, getWidgetHeight(widget, bp)
• Conversión masiva: convertWidgetUnits(widget, fromUnit, toUnit, contextSize, bp)

Valores responsivos genéricos (core/utils/responsive-utils.ts)

• Lectura con cascada: getValueForBreakpoint(value, bp)
• Escritura de propiedad: setResponsiveProperty(responsiveValue, key, val, bp)
• Escritura de objeto completo: setResponsiveObject(responsiveValue, obj, bp)
• A utilitario responsivo: toResponsiveValue(x)
• Map general: mapResponsiveValue(value, (val,bp)=>res)
• Breakpoints: getAllBreakpoints(), getBreakpointForWidth(px, DEFAULT_BREAKPOINTS)

Layouts de página (core/utils/page-layout.utils.ts)

• Presets: createDefaultFreeLayout(), createDefaultFlowLayout(), createDefaultTemplateLayout(), createLayoutByType('free'|'flow'|'template')
• Personalizado: createCustomLayout(type, options)
• Lectura/Escritura por breakpoint: getLayoutPropertyForBreakpoint(layout, prop, bp), updateLayoutPropertyForBreakpoint(layout, prop, val, bp)
• Copia entre breakpoints: copyBreakpointProperties(layout, sourceBp, targetBp)
• Conversión: convertToResponsiveLayout(partial), isResponsiveLayout(layout)
• Resolución completa para render: getPageLayoutForBreakpoint(page, bp)

Patrones prescriptivos para generadores IA

1. Leer/mostrar propiedades de un widget en un breakpoint

const bp: BreakpointKey = 'md';
const pos = getCompletePositionForBreakpoint(widget, bp);
const size = getCompleteSizeForBreakpoint(widget, bp);
const styles = getCompleteStylesForBreakpoint(widget, bp);

2. Actualizar una propiedad puntual (inmutabilidad obligatoria)

const updated = setWidgetSizeProp(widget, 'width', '320px', 'md');

3. Actualizar varias props atómicas de posición/tamaño

const newPos = { x: 16, y: 24, constrainToParent: true };
const w1 = updatePositionForBreakpoint(widget, newPos, 'lg');
const newSize = { width: '50%', height: 'auto', minWidth: 10, minHeight: 10, responsive: true };
const w2 = updateSizeForBreakpoint(w1, newSize, 'lg');

4. Cambiar unidades de tamaño de px a % en un breakpoint

const wPct = convertWidgetUnits(widget, 'px', '%', /*contextSize*/ 1200, 'md');

5. Copiar configuración de un breakpoint a otro (clonar experiencia)

const wCloned = copyBreakpointProperties(widget, 'md', 'xl');

6. Layout responsivo rápido

const layout = createCustomLayout('template', { padding: createBaseResponsiveValue('16px') });
const layoutMd = updateLayoutPropertyForBreakpoint(layout, 'margin', '0 auto', 'md');

Reglas de oro

• Trabaja SIEMPRE de forma inmutable; todas las funciones devuelven nuevos objetos.
• Usa helpers de capa alta (updateWidgetProperty, getWidgetProperty) cuando corresponda; baja al acceso fino solo si es necesario.
• Mantén las unidades consistentes y válidas; usa formatWithUnit/parseValueAndUnit/convertUnit.
• Respeta la cascada de breakpoints en lecturas; define explícitamente el breakpoint en escrituras.
• Para UI Angular 20, prepara valores derivados vía computed() y no calcules en plantillas.

Anti‑patrones (evitar)

• Mutar objetos responsivos directamente (obj.md.width = ...).
• Condiciones complejas en plantillas; pre‑calcula con signals/computed.
• Escribir strings de medidas sin validar/parsear.

Referencias de import (resumen)

• libs/core-models/src/lib/models/responsive/*
• libs/core-models/src/lib/utils/responsive-utils.ts
• libs/core-models/src/lib/utils/responsive-helpers.ts
• libs/editor-ui/src/lib/utils/responsive-widget-utils.ts
• libs/core-models/src/lib/utils/page-layout.utils.ts
• libs/core-models/src/lib/models/widget.model.ts