Seções novas em ui/

Esta página é para quem contribui com o slash-kit: o repositório do CLI, dos templates e dos componentes. Quem só usa o slash pode pular para Começar.

A pasta ui/ tem os componentes que os templates copiam para cada projeto gerado. Uma seção nova entra nela em cinco passos, depois de conferir as regras da pasta.

Regras da pasta

O teste de arquitetura do repositório confere estas regras a cada bun test:

• ui/ é portátil. Ela não importa nada de cli/, templates/, panel/, modules/ nem do slash-ssg.
• As seções, os documentos e o núcleo (ui/sections, ui/document e ui/core) não importam ui/panel.
• Larguras vêm só das classes do grid. width, max-width e afins com comprimento fixo, em px, rem ou outra unidade, são recusados fora de ui/grid/, com uma exceção: as miniaturas de tamanho fixo de ui/core/media.module.css.
• O espaçamento entre irmãos usa gap. O seletor * + * é proibido no CSS das seções.
• Cor literal só existe no tema-base, ui/theme/base.ts. O resto usa var(--…).
• Não há @keyframes em CSS Module.
• Comentários de CSS não têm aspa simples, porque o extrator de classes do slash-ssg para ao encontrá-la.
• unsafeHtml só aparece nos arquivos de uma lista fechada, com conteúdo confiável.

Passo a passo

1. Crie a pasta ui/sections/<nome>/, com o componente <nome>.ts, o estilo <nome>.module.css e os testes <nome>.test.ts. Use minúsculas e hífen, como em feature-split.
2. Crie <nome>.gallery.ts, que exporta as entradas da galeria. Cada entrada é um GalleryEntry com id, component, variant, tone e render. A galeria mostra cada entrada em /entry/<id>. Rode bun run gallery para abri-la.
3. Acrescente as entradas à lista catalog em ui/gallery/catalog.ts: importe o …Gallery e espalhe-o na lista.
4. Exporte o componente e os tipos públicos em ui/index.ts. Os dados da galeria e os auxiliares de teste ficam de fora desse arquivo.
5. Rode bun run typecheck. Ele gera os arquivos .module.css.d.ts das pastas de CSS e confere os tipos.

As entradas da galeria podem pedir verificações extras, com as opções grid, islands, unmasked e standalone. Elas estão descritas em ui/gallery/catalog.ts.

Testes e guardas

• Teste o componente em <nome>.test.ts, no padrão AAA: arranjo, ação e verificação separados.
• ui/gallery/catalog.test.ts confere as entradas da galeria que têm opções próprias.
• ui/api-compat.test.ts é a guarda de API. Ele confere que cada valor e cada tipo gravado nas fixtures ui/__fixtures__/api-<versão>.json continua exportado por ui/index.ts. Acrescentar uma exportação não quebra o teste. Remover ou renomear uma, quebra.
• Para gravar a API atual numa fixture nova, rode bun scripts/api-snapshot.ts ui/__fixtures__/api-<versão>.json. As fixtures antigas não se editam. Uma versão nova ganha um arquivo novo.
• bun run gate roda as camadas de verificação do repositório: typecheck, lint, testes unitários e os testes de ponta a ponta.

Cópia para o projeto gerado

O slash create copia ui/ para o projeto sem a galeria, os fixtures, os testes, os arquivos *.gallery.ts, os *.gallery.module.css e os tipos gerados. Por isso a seção nova chega só aos projetos criados depois dela. Projetos já gerados não recebem o componente sozinhos: a 1.1.0 não tem comando de atualização. Veja Limites da 1.1.0.