prototipo-cls-ui

Prototipo de framework CSS para o projeto TCloud da TOTVS, com proposta semelhante a frameworks como Bootstrap, porem focado nas necessidades de design system, padronizacao visual e escalabilidade do ecossistema TCloud.

Repositorio oficial: https://github.com/tcloud-dev/prototipo-cls-ui.git

Contexto do Projeto

Este projeto esta no inicio e, neste momento, ainda nao possui implementacao da nova framework CSS.

Atualmente, o repositorio contem apenas o diretorio de referencia reference/tcloud-ui, que representa a base anterior a ser estudada e evoluida.

Finalidade

A finalidade deste repositorio e construir uma grande evolucao da solucao anterior, criando uma nova fundacao para estilos, utilitarios e componentes CSS do TCloud.

Objetivos desta fase inicial:

• Definir a base arquitetural da nova framework CSS.
• Identificar pontos de melhoria da referencia atual.
• Estabelecer padroes de nomenclatura, organizacao e manutencao.
• Evoluir consistencia visual, produtividade e escalabilidade.

Estrutura Atual

• reference/tcloud-ui: referencia do projeto anterior.
• README.md: documentacao inicial do prototipo.

Como Clonar

Clone do projeto com submodulos:

git clone --recurse-submodules https://github.com/tcloud-dev/prototipo-cls-ui.git
cd prototipo-cls-ui

Se ja clonou sem submodulos:

git submodule update --init --recursive

Como Usar

Instalação Inicial

Após clonar o projeto, instale as dependências:

npm install

Desenvolvimento

Execute o build em modo watch para desenvolvimento:

npm run dev

Este comando irá monitorar alterações no diretório src/ e recompilar automaticamente.

Build para Produção

Para gerar o build final no diretório dist/:

npm run build

O build gera:

• ESM (ES Modules): dist/index.mjs
• CJS (CommonJS): dist/index.js
• Types: dist/index.d.ts
• Source Maps: arquivos .map

Scripts Disponíveis

• npm run dev - Build em modo watch para desenvolvimento
• npm run build - Build de produção (ESM + CJS + tipos)
• npm run clean - Limpa o diretório dist/
• npm test - Executa testes
• npm run lint - Executa linting do código
• npm run format - Formata código com Prettier
• npm run docs - Gera documentação em /docs
• npm run docs:serve - Gera e serve documentação localmente

Gerar Documentação

Para gerar a documentação técnica do projeto:

npm run docs

Para visualizar a documentação localmente:

npm run docs:serve

A documentação será gerada no diretório /docs e pode ser publicada automaticamente no GitHub Pages.

Publicar no NPM

Via GitHub Actions (Recomendado)

1. Acesse o repositório no GitHub
2. Vá em Actions > NPM Publish
3. Clique em Run workflow
4. Selecione a tag desejada (latest, beta ou alpha)
5. Confirme a execução

Via Linha de Comando (Manual)

npm publish --tag latest --access public

Sobre a Documentação

Este projeto utiliza TypeDoc para gerar documentação técnica automaticamente a partir dos comentários no código.

Por que TypeDoc?

• ✅ Nativo para TypeScript - Suporte completo a tipos e interfaces
• ✅ Geração Automática - Cria documentação a partir dos comentários JSDoc
• ✅ Site Estático - Gera páginas HTML navegáveis e pesquisáveis
• ✅ GitHub Pages - Integração fácil para publicação online
• ✅ Temas Personalizáveis - Suporta customização visual
• ✅ Exportação de Tipos - Documenta toda a API pública

Como Documentar o Código

Use comentários JSDoc no código TypeScript:

/**
 * Componente de botão do Claus UI
 * @public
 */
export interface ButtonProps {
  /** Texto do botão */
  label: string;
  /** Variante visual */
  variant?: 'primary' | 'secondary' | 'tertiary';
  /** Estado desabilitado */
  disabled?: boolean;
}

/**
 * Classe do componente Button
 * @example
 * ```typescript
 * const button = new Button({ 
 *   label: 'Clique aqui', 
 *   variant: 'primary' 
 * });
 * ```
 */
export class Button {
  constructor(private props: ButtonProps) {}
  
  render(): HTMLButtonElement {
    // implementação
  }
}

Visualizar Documentação

A documentação é publicada automaticamente no GitHub Pages a cada push na branch principal.

Acesse em: https://tcloud-dev.github.io/prototipo-cls-ui/

Diretorio de Referencia

O diretorio reference/tcloud-ui deve ser utilizado como referencia tecnica para comparacao e apoio durante a evolucao do novo prototipo.

Para atualizar o conteudo da referencia quando necessario:

git submodule update --remote --merge

Status Atual

Projeto em fase de bootstrap inicial.

• Sem implementacao funcional da nova framework CSS ate o momento.
• Estrutura inicial preparada para evolucao incremental.

Proximos Passos Sugeridos

• Definir design tokens (cores, tipografia, espacamento, sombras).
• Definir convencoes de classes e arquitetura CSS.
• Criar os primeiros modulos base (layout, grid, tipografia, botoes, formularios e utilitarios).
• Estruturar documentacao tecnica e exemplos de uso.