> 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-para-colaboradores/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 Quer migrar um componente por: * Melhor suporte a temas * Tipos TypeScript melhorados * Consistência com outros componentes UI2 * Otimização de desempenho * Melhorias de acessibilidade ### 2. Atualização de um Componente * É necessário atualizar um componente UI1 * Ainda não existe um equivalente em UI2 * **Requisito**: Crie-o primeiro em UI2 e depois utilize-o ### 3. Necessidades do Projeto * O componente será usado num projeto novo ou existente * Há tempo disponível para o migrar corretamente * Os recursos do projeto permitem uma migração completa {% hint style="warning" %} **Não** migre componentes "só porque sim". Cada migração deve ter uma justificação de negócio ou técnica clara. {% endhint %} *** ## Processo de Migração ### Passo 1: Planeamento Antes de iniciar a migração: 1. **Identifique dependências** * Que outros componentes ele usa? * Que projetos o usam atualmente? * Há alguma breaking change planeada? 2. **Reveja o uso atual** * Quantos projetos usam este componente? * Quais props são mais usadas? * Há algum problema conhecido? 3. **Defina o âmbito** * Será esta uma migração 1:1? * Há melhorias planeadas? * Qual é o cronograma? ### Passo 2: Criar o componente UI2 Siga o [Componentes personalizados](/contributor/contributor-pt/guias-para-colaboradores/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 stories abrangentes no Storybook * Escreva testes completos * Documente todas as props e comportamentos **Estrutura de exemplo:** ``` ui2/src/components/Button/ ├── Button.tsx ├── Button.styles.ts ├── Button.stories.tsx ├── Button.test.tsx ├── types.ts ├── index.ts └── README.md ``` ### Passo 3: Manter a Compatibilidade O componente UI2 **DEVE** deve expor as mesmas props e comportamentos da 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 com Versões Anteriores Se precisar alterar ou adicionar props: 1. **Primeiro**, adicione as novas props ao UI1 como opcionais 2. **Depois**, migre os consumidores de UI1 para usar as novas props 3. **Por fim**, 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 a implementação do UI1 export function Button({ primary, variant = primary ? 'primary' : 'secondary' }: ButtonProps) { // Usar variant em vez de primary internamente } // Passo 3: Criar UI2 com a nova API interface ButtonProps { // variant é agora a prop principal variant?: 'primary' | 'secondary'; // Manter primary para compatibilidade, marcar como descontinuada /** @deprecated Use variant instead */ primary?: boolean; } ``` ### Passo 4: Descontinuar o Componente UI1 Adicione um aviso de descontinuaçã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'; * ``` * * Consulte 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** o caminho de migração 3. **Atualizar** novos projetos para usar UI2 4. **Migrar** projetos existentes à medida que surgirem oportunidades 5. **Planear** a remoção eventual de UI1 (com aviso) *** ## Exemplos de Migração ### Exemplo 1: Componente Simples A migrar um componente 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 A migrar 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