> 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-pt/guias-do-contribuidor/padroes-de-web-ui/migration.md). # Guia de Migração Este guia cobre o processo de migração de componentes de UI1 (`decentraland-ui`) para UI2 (`decentraland-ui2`). ## Quando Migrar As migrações podem começar por três razões válidas: ### 1. Melhoria Técnica Você quer migrar um componente por: * Melhor suporte a temas * Melhorias nos tipos TypeScript * Consistência com outros componentes UI2 * Otimização de desempenho * Melhorias de acessibilidade ### 2. Atualizando um Componente * Um componente UI1 precisa ser atualizado * Ainda não existe um equivalente em UI2 * **Requisito**: Crie-o primeiro em UI2, depois use-o ### 3. Necessidades do Projeto * O componente será usado em um projeto novo ou existente * Há tempo disponível para migrá-lo corretamente * Recursos do projeto permitem uma migração completa {% hint style="warning" %} **Não** migre componentes "apenas porque." Cada migração deve ter uma justificativa comercial ou técnica clara. {% endhint %} *** ## Processo de Migração ### Passo 1: Planejamento Antes de iniciar a migração: 1. **Identificar dependências** * Quais outros componentes ele usa? * Quais projetos atualmente o utilizam? * Há mudanças incompatíveis planejadas? 2. **Revisar uso atual** * Quantos projetos usam este componente? * Quais props são mais comumente usadas? * Existe algum problema conhecido? 3. **Definir escopo** * Esta será uma migração 1:1? * Há melhorias planejadas? * Qual é o cronograma? ### Passo 2: Criar Componente UI2 Siga o [Componentes Personalizados](/contributor/contributor-pt/guias-do-contribuidor/padroes-de-web-ui/custom-components.md) guia para componentes candidatos a UI2. **Requisitos:** * Use sintaxe de objeto para styled-components * Use apenas valores do tema (sem valores arbitrários) * Adicione histórias abrangentes no Storybook * Escreva testes completos * Documente todas as props e comportamentos **Exemplo de estrutura:** ``` ui2/src/components/Button/ ├── Button.tsx ├── Button.styles.ts ├── Button.stories.tsx ├── Button.test.tsx ├── types.ts ├── index.ts └── README.md ``` ### Passo 3: Manter Compatibilidade O componente UI2 **DEVE** expor as mesmas props e comportamentos que a versão UI1. #### Mesmas Props ```tsx // UI1 Button interface ButtonProps { primary?: boolean; size?: 'small' | 'medium' | 'large'; onClick?: () => void; disabled?: boolean; children: React.ReactNode; } // UI2 Button - DEVE suportar as mesmas props interface ButtonProps { primary?: boolean; size?: 'small' | 'medium' | 'large'; onClick?: () => void; disabled?: boolean; children: React.ReactNode; // Pode adicionar novas props opcionais variant?: 'text' | 'outlined' | 'contained'; } ``` #### Alterações Compatíveis Retroativamente Se você precisar alterar ou adicionar props: 1. **Primeiro**, adicione as novas props ao UI1 como opcionais 2. **Em seguida**, migre os consumidores do UI1 para usar as novas props 3. **Finalmente**, crie o componente UI2 com a nova API ```tsx // Passo 1: Adicionar prop opcional ao UI1 interface ButtonProps { primary?: boolean; // Nova prop opcional variant?: 'primary' | 'secondary'; } // Passo 2: Atualizar implementação do UI1 export function Button({ primary, variant = primary ? 'primary' : 'secondary' }: ButtonProps) { // Use variant em vez de primary internamente } // Passo 3: Criar UI2 com nova API interface ButtonProps { // variant agora é a prop principal variant?: 'primary' | 'secondary'; // Mantenha primary para compatibilidade, marque como deprecated /** @deprecated Use variant instead */ primary?: boolean; } ``` ### Passo 4: Depreciar Componente UI1 Adicione um aviso de depreciação ao componente UI1: ````tsx /** * @deprecated Este componente foi migrado para UI2. * Importe de 'decentraland-ui2' em vez disso: * * ```tsx * import { Button } from 'decentraland-ui2'; * ``` * * Veja o guia de migração: https://docs.decentraland.org/contributor-guides/web-ui-standards/migration */ export function Button(props: ButtonProps) { // ... implementação existente } ```` ### Passo 5: Adoção Gradual Não force a migração imediata. Permita a adoção gradual: 1. **Publicar** componente UI2 2. **Documentar** caminho de migração 3. **Atualizar** novos projetos para usar UI2 4. **Migrar** projetos existentes de forma oportunista 5. **Planejar** eventual remoção do UI1 (com aviso) *** ## Exemplos de Migração ### Exemplo 1: Componente Simples Migrando um básico `Card` componente: #### Versão 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}
); } ``` #### Versão 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} ); } ``` ### Exemplo 2: Componente com Variantes Migrando um `Button` com variantes: #### Versão 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