@esperanca-ui/premiacoes

Roleta e raspadinha em React, com temas, áudio e apresentação de resultados.

Usar · Componentes · Documentação · Publicação · Changelog

Biblioteca React em TypeScript, preparada para distribuição npm como JavaScript ESM, declarações de tipos e CSS. As modalidades suportadas são roleta e raspadinha.

O resultado vem decidido pelo backend. Os componentes apresentam esse resultado; não calculam chances, concedem prêmios ou consomem saldo.

Recursos

| Recurso | O que oferece | | --- | --- | | RodaClassica | Giro até o segmento correspondente, luzes, partículas, texto, imagens e botão central configuráveis | | Raspadinha | Cobertura em Canvas e revelação com acabamento sólido, imagem ou foil | | ModalResultado | Apresentação de vitória ou derrota com dados do prêmio | | PreviewRoleta | Simulação local com avisos de configuração | | TesteSomRoleta | Teste de clipes por evento e tick sintetizado | | Contratos e temas | Adaptadores de campanha e resultado, validação e seis presets visuais |

Usar no consumidor

Após a primeira publicação no registry:

npm install @esperanca-ui/premiacoes framer-motion@^11

O projeto consumidor deve usar React 18 e React DOM 18. Importe o CSS uma vez no ponto de entrada da aplicação:

import '@esperanca-ui/premiacoes/style.css';

Os componentes e os tipos são importados diretamente pelo nome do pacote, sem alias:

import { PreviewRoleta } from '@esperanca-ui/premiacoes';

export function Demonstracao() {
  return (
    <PreviewRoleta
      config={{
        segmentos: [
          { id: 'vale', label: 'Vale compras', tipo: 'produto' },
          { id: 'vazio', label: 'Tente novamente', tipo: 'vazio' },
        ],
        tema: { estilo: 'dourado' },
        som: { habilitado: false },
      }}
    />
  );
}

Para resultados reais, consulte o guia de integração. Antes da publicação, instale o .tgz local gerado por npm run pack:lib, conforme o guia de publicação.

Desenvolver

No checkout, use Node.js 22.12+ e npm:

npm ci
npm run check
npm run dev

Abra http://127.0.0.1:5173/exemplos/preview.html, ajustando a porta se o Vite informar outra. O laboratório permite editar aparência, simular resultados e observar avisos. As jogadas são locais; imagens e sons personalizados dependem das URLs configuradas. Não há .env, banco ou backend obrigatório.

Build e qualidade

| Comando | Finalidade | | --- | --- | | npm run check | Typecheck, lint e 124 testes atuais | | npm run build | Gera JavaScript ESM, tipos TypeScript e CSS em dist/ | | npm run test:package | Instala o tarball em um consumidor temporário e valida imports, tipos e build com CSS; execute após o build | | npm run pack:lib | Valida, recompila e gera o .tgz na raiz | | npm publish | Valida e recompila antes de publicar no npm; exige acesso à conta e ao scope |

O hook prepack executa check e build tanto em npm pack quanto na publicação normal. React, React DOM, Framer Motion e seus subpaths permanecem externos ao bundle.

A pipeline GitLab usa Node.js 22 e a tag de runner docker-test. Confere estrutura e versões, executa as validações, testa o pacote em um consumidor e disponibiliza o .tgz como artefato. A publicação no npm é manual.

Estrutura

.
├── .cz.toml                  # Commits e versões
├── .gitlab-ci.yml            # Validação e artefato npm
├── CHANGELOG.md
├── COMPONENTS.md
├── CONTRIBUTING.md
├── docs/                     # Integração, configuração e publicação
├── exemplos/                 # Laboratório visual
├── scripts/
│   ├── verificar-pacote.mjs   # Teste do pacote instalado
│   └── sincronizar.mjs       # Compatibilidade com consumidores por cópia
├── src/                      # Componentes, contratos, áudio e temas
├── tsconfig.build.json       # Configuração dos tipos de distribuição
├── vite.config.mjs           # Build da biblioteca
├── package.json
└── package-lock.json

O pacote inclui dist/ e documentação. Fontes, testes, exemplos, ferramentas locais, logs e dependências instaladas ficam fora do tarball. As referências a esses arquivos nos guias correspondem ao checkout de desenvolvimento.

Consumidores existentes

A sincronização por cópia continua disponível para projetos que ainda a utilizam. A migração para npm é descrita no guia de integração. Nenhum consumidor é alterado automaticamente.

Documentação

• Componentes públicos
• Desenvolvimento
• Integração
• Configuração
• Publicação npm
• Sincronização por cópia
• Contribuição e versões

Não há arquivo de licença neste checkout.