> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/contributor/contributor-es/guias-para-colaboradores/estandares-de-ui-web/migration.md). # Guía de migración Esta guía cubre el proceso de migración de componentes desde UI1 (`decentraland-ui`) a UI2 (`decentraland-ui2`). ## Cuándo Migrar Las migraciones pueden comenzar por tres razones válidas: ### 1. Mejora técnica Deseas migrar un componente por: * Mejor soporte de theming * Mejores tipos de TypeScript * Consistencia con otros componentes de UI2 * Optimización de rendimiento * Mejoras de accesibilidad ### 2. Actualización de un Componente * Un componente de UI1 necesita ser actualizado * Aún no existe un equivalente en UI2 * **Requisito**: Créalo primero en UI2, luego úsalo ### 3. Necesidades del Proyecto * El componente será usado en un proyecto nuevo o existente * Hay tiempo disponible para migrarlo correctamente * Los recursos del proyecto permiten una migración exhaustiva {% hint style="warning" %} **No** migres componentes “solo porque.” Cada migración debe tener una justificación comercial o técnica clara. {% endhint %} *** ## Proceso de Migración ### Paso 1: Planificación Antes de iniciar la migración: 1. **Identificar dependencias** * ¿Qué otros componentes utiliza? * ¿Qué proyectos lo usan actualmente? * ¿Hay cambios incompatibles planificados? 2. **Revisar uso actual** * ¿Cuántos proyectos usan este componente? * ¿Qué props se usan con mayor frecuencia? * ¿Hay problemas conocidos? 3. **Definir alcance** * ¿Será esta una migración 1:1? * ¿Hay mejoras planificadas? * ¿Cuál es el cronograma? ### Paso 2: Crear Componente UI2 Sigue la [Componentes personalizados](/contributor/contributor-es/guias-para-colaboradores/estandares-de-ui-web/custom-components.md) guía para componentes candidatos de UI2. **Requisitos:** * Usar sintaxis de objeto para styled-components * Usar solo valores del theme (no valores arbitrarios) * Agregar historias completas en Storybook * Escribir pruebas completas * Documentar todas las props y comportamientos **Estructura de ejemplo:** ``` ui2/src/components/Button/ ├── Button.tsx ├── Button.styles.ts ├── Button.stories.tsx ├── Button.test.tsx ├── types.ts ├── index.ts └── README.md ``` ### Paso 3: Mantener Compatibilidad El componente UI2 **DEBE** debe exponer las mismas props y comportamientos que la versión UI1. #### Mismas Props ```tsx // UI1 Button interface ButtonProps { primary?: boolean; size?: 'small' | 'medium' | 'large'; onClick?: () => void; disabled?: boolean; children: React.ReactNode; } // UI2 Button - DEBE soportar las mismas props interface ButtonProps { primary?: boolean; size?: 'small' | 'medium' | 'large'; onClick?: () => void; disabled?: boolean; children: React.ReactNode; // Se pueden agregar nuevas props opcionales variant?: 'text' | 'outlined' | 'contained'; } ``` #### Cambios Compatibles hacia Atrás Si necesitas cambiar o agregar props: 1. **Primero**, agrega las nuevas props a UI1 como opcionales 2. **Luego**, migra a los consumidores de UI1 para usar las nuevas props 3. **Finalmente**, crea el componente UI2 con la nueva API ```tsx // Paso 1: Agregar prop opcional a UI1 interface ButtonProps { primary?: boolean; // Nueva prop opcional variant?: 'primary' | 'secondary'; } // Paso 2: Actualizar implementación de UI1 export function Button({ primary, variant = primary ? 'primary' : 'secondary' }: ButtonProps) { // Usar variant en lugar de primary internamente } // Paso 3: Crear UI2 con la nueva API interface ButtonProps { // variant ahora es la prop principal variant?: 'primary' | 'secondary'; // Mantener primary por compatibilidad, marcar como obsoleta /** @deprecated Use variant instead */ primary?: boolean; } ``` ### Paso 4: Deprecar el Componente UI1 Agregar un aviso de deprecación al componente UI1: ````tsx /** * @deprecated Este componente ha sido migrado a UI2. * Importar desde 'decentraland-ui2' en su lugar: * * ```tsx * import { Button } from 'decentraland-ui2'; * ``` * * Ver la guía de migración: https://docs.decentraland.org/contributor-guides/web-ui-standards/migration */ export function Button(props: ButtonProps) { // ... implementación existente } ```` ### Paso 5: Adopción Gradual No fuerces la migración inmediata. Permite una adopción gradual: 1. **Publicar** componente UI2 2. **Documentar** ruta de migración 3. **Actualizar** proyectos nuevos para usar UI2 4. **Migrar** proyectos existentes de forma oportunista 5. **Planificar** eventual eliminación de UI1 (con aviso) *** ## Ejemplos de Migración ### Ejemplo 1: Componente Simple Migrando un básico `Card` componente: #### Versión UI1 ```tsx // decentraland-ui/src/components/Card/Card.tsx import React from 'react'; import './Card.css'; export interface CardProps { className?: string; children: React.ReactNode; } export function Card({ className, children }: CardProps) { return (
{children}
); } ``` #### Versión UI2 ```tsx // decentraland-ui2/src/components/Card/Card.tsx import { styled } from '@mui/material/styles'; export interface CardProps { className?: string; children: React.ReactNode; } const StyledCard = styled('div')(({ theme }) => ({ backgroundColor: theme.palette.background.paper, borderRadius: theme.shape.borderRadius, padding: theme.spacing(2), boxShadow: theme.shadows[1], [theme.breakpoints.down('sm')]: { padding: theme.spacing(1), }, })); export function Card({ className, children }: CardProps) { return ( {children} ); } ``` ### Ejemplo 2: Componente con Variantes Migrando un `Button` con variantes: #### Versión UI1 ```tsx // UI1 import './Button.css'; interface ButtonProps { primary?: boolean; secondary?: boolean; size?: 'small' | 'medium' | 'large'; } export function Button({ primary, secondary, size = 'medium', ...props }: ButtonProps) { const classes = [ 'dcl-button', primary && 'primary', secondary && 'secondary', `size-${size}`, ].filter(Boolean).join(' '); return