clarus-css 0.1.0 → 0.1.1

package/docs/definitions.md

@@ -88,7 +88,7 @@ O escopo inicial inclui:
 - Layout e containers.
 - Grid baseado em Flexbox.
 - Utilitários de espaçamento, display, alinhamento, visibilidade e tipografia.
-- Formulários e campos de entrada.
+- Formulários e campos de entrada (incluindo validação visual, select customizado e upload de arquivo estilizado).
 - Botões.
 - Cards.
 - Alertas.
@@ -209,6 +209,10 @@ As seguintes decisões estão definidas:
 - Distribuição: npm desde o início.
 - Licença: MIT.
 - Tom do projeto: técnico, estratégico e com posicionamento de produto.
+- Convenção de nomenclatura de classes: definida na seção 19.
+- API JavaScript dos componentes interativos: definida na seção 20.
+- Ordem de implementação dos componentes: definida na seção 21.
+- Estratégia de testes visuais e funcionais: definida na seção 22.
 
 ## 18. Pontos a Definir Posteriormente
 
@@ -216,19 +220,112 @@ Apesar das decisões principais estarem firmadas, ainda precisam ser definidos e
 
 - Paleta de cores oficial.
 - Família tipográfica final.
-- Convenção exata de nomes de classes.
-- Estrutura definitiva dos arquivos SCSS.
-- API JavaScript dos componentes interativos.
-- Ordem de implementação dos componentes.
-- Estratégia de testes visuais e funcionais.
 
-## 19. Próximo Marco
+## 19. Convenção de Nomenclatura de Classes
+
+- Sem prefixo global: as classes seguem o padrão Bootstrap já em uso (`.btn`,
+  `.card`, `.container`), sem prefixo `clarus-`.
+- Variantes de cor/estilo por sufixo direto: `.btn-primary`, `.alert-danger`,
+  `.badge-success`, seguindo os nomes já usados em `$theme-colors`
+  (`scss/settings/_colors.scss`).
+- Tamanhos por sufixo `-sm`/`-lg` consistente em todos os componentes que
+  tiverem variação de tamanho (botões, badges, cards, inputs), generalizando
+  o padrão já usado em `.form-control-sm`/`.form-control-lg`.
+- Estados controlados por JavaScript usam classes `is-*` (`.is-open`,
+  `.is-active`, `.is-expanded`), nunca atributos `data-state` customizados.
+- Utilitários mantêm abreviações curtas estilo Bootstrap (`.d-flex`, `.mt-3`,
+  `.gx-2`, `.p-2`), como já implementado em `scss/utilities/`.
+- Responsividade em utilitários e grid segue sempre o formato fixo
+  `{propriedade}-{breakpoint}-{valor}` (ex.: `.col-md-6`, `.d-md-none`,
+  `.mt-lg-3`).
+
+## 20. API JavaScript dos Componentes Interativos
+
+- Inicialização sempre automática via atributo HTML (ex.:
+  `data-clarus="modal" data-target="#meuModal"`), sem exigir `new` manual
+  para o uso básico — alinhado com "uso direto em HTML sem build" (seção 7).
+- Toda instância criada automaticamente continua acessível para controle
+  programático via método estático de recuperação (ex.:
+  `Clarus.Modal.getInstance(el)`), permitindo chamar seus métodos sem
+  precisar instanciar manualmente.
+- Namespace global único: `window.Clarus`, com cada componente como
+  propriedade (`Clarus.Modal`, `Clarus.Tooltip`, `Clarus.Dropdown`, etc.),
+  em vez de globais separados.
+- API de instância padronizada para todo componente interativo: `.show()`,
+  `.hide()`, `.toggle()`, `.dispose()`.
+- Comunicação com a aplicação via eventos DOM customizados (ex.:
+  `clarus:modal:shown`, `clarus:tab:changed`), disparados com
+  `CustomEvent` nativo — sem exigir callbacks de construtor.
+- Acessibilidade (ARIA, foco, teclado) é requisito obrigatório da API desde
+  a v0.1 para todo componente interativo, não um extra a ser adicionado
+  depois.
+- Além do bundle único (`dist/js/clarus.js`), haverá import granular por
+  componente (ex.: `import { Modal } from "clarus-css/js/modal"`), para uso
+  com bundlers.
+
+## 21. Ordem de Implementação dos Componentes
+
+Critério de priorização: dependência técnica primeiro (o que outros
+componentes reaproveitam é implementado antes), respeitando que todo
+componente 100% CSS (sem JavaScript) seja concluído antes de iniciar os que
+exigem JavaScript.
+
+**Fase A — Componentes CSS-only, por dependência técnica:**
+
+1. Botões — reaproveitados por cards, alertas, modal e navbar.
+2. Badges — pequeno e reaproveitado por cards, navbar e tabelas.
+3. Alertas — formaliza o padrão de variante de cor de estado
+   (success/warning/danger/info) que badges e tabelas também usam.
+4. Cards — combina botões, badges e tipografia base num contêiner.
+5. Tabelas — reaproveita as cores de estado definidas em alertas/badges.
+6. Navbar (versão estática, sem dropdown/collapse) — reaproveita botões e
+   badges.
+7. Paginação — reaproveita o padrão de item ativo/desabilitado dos botões.
+8. Breadcrumbs — mais simples, sem dependência de outros componentes.
+9. Formulários avançados, parte CSS-only: estados de validação
+   (`.is-valid`/`.is-invalid`, reaproveitando as cores de estado de
+   alertas/badges) e upload de arquivo estilizado (label + input nativo
+   oculto).
+
+**Fase B — Infraestrutura JS compartilhada (antes de qualquer componente
+interativo):**
+
+1. Posicionamento/overlay — usado por dropdown, tooltip e modal.
+2. Foco e teclado (focus trap + tecla Escape) — usado por modal e
+   dropdown.
+3. Transição/collapse — usado por accordion, tabs e toast.
+
+**Fase C — Componentes com JS, por dependência técnica:**
+
+1. Dropdown — consumidor mais simples da infraestrutura de posicionamento.
+2. Tooltip — reaproveita a mesma infraestrutura de posicionamento do
+   dropdown, com show/hide por hover/focus.
+3. Modal — reaproveita posicionamento e foco/teclado; mais complexo que
+   dropdown/tooltip.
+4. Select customizado (formulários avançados) — é um dropdown aplicado a
+   um campo de formulário; depende do dropdown já existir.
+5. Accordion — reaproveita a infraestrutura de transição/collapse.
+6. Tabs — reaproveita o mesmo padrão de alternância de painel do
+   accordion.
+7. Toast — reaproveita a infraestrutura de transição/collapse e adiciona
+   timers de auto-dismiss.
+
+## 22. Estratégia de Testes Visuais e Funcionais
+
+- Teste visual (regressão de CSS): Playwright com comparação de
+  screenshots, rodando local e no CI já existente — sem dependência de
+  serviço externo pago.
+- Teste funcional de JavaScript: Vitest com `jsdom`, cobrindo estado,
+  atributos ARIA e eventos disparados por cada componente interativo.
+- Os arquivos em `mockup/*.html` são as fixtures oficiais dos testes
+  visuais — cada componente/grupo implementado ganha (ou já usa) um mockup
+  dedicado, mantido atualizado.
+- Testes (visuais e funcionais) rodam automaticamente no GitHub Actions a
+  cada push/PR, como um novo step em `.github/workflows/ci.yml`, além do
+  lint e build já existentes.
+
+## 23. Próximo Marco
 
 O próximo marco do projeto é transformar estas definições em uma estrutura técnica inicial:
 
-1. Criar ou ajustar `package.json`.
-2. Definir a arquitetura SCSS.
-3. Criar pipeline de build.
-4. Organizar `dist`.
-5. Documentar instalação e uso inicial no `README.md`.
-6. Implementar layout, grid, utilitários e formulários como base da versão inicial.
+1. Implementar layout, grid, utilitários e formulários como base da versão inicial.

package/docs/guia-comandos.md

@@ -0,0 +1,124 @@
+# Guia Interno de Comandos — Clarus CSS
+
+Guia de referência rápida para uso pessoal no terminal: git/GitHub, npm e
+build. Não é documentação pública do projeto (isso é papel do README).
+
+## Ambiente
+
+Node.js está instalado em `C:\Users\jwmenezes\node`, mas pode não estar no
+`PATH` da sessão do terminal. Se `node -v` / `npm -v` derem "command not
+found", rode antes (PowerShell):
+
+```powershell
+$env:PATH = "C:\Users\jwmenezes\node;$env:PATH"
+```
+
+Para não repetir isso sempre, adicione `C:\Users\jwmenezes\node` de forma
+permanente ao PATH do Windows (Configurações > Sistema > Variáveis de
+Ambiente).
+
+Remote configurado no repositório: `work` → `https://github.com/jorgewreis/clarus-css.git`.
+
+## Fluxo diário (git)
+
+```bash
+# ver o que mudou
+git status
+git diff
+
+# stage seletivo (evite "git add -A" se não revisou tudo)
+git add caminho/do/arquivo
+
+# commit
+git commit -m "mensagem no imperativo, explicando o porquê"
+
+# sincronizar com o GitHub
+git fetch work
+git push work main
+```
+
+Se `git fetch work` mostrar `behind`, rode `git pull work main` antes do
+push (ou `git merge work/main` se preferir revisar antes).
+
+## Branches
+
+```bash
+# nova branch a partir da main
+git checkout -b feature/nome-da-mudanca
+
+# voltar pra main e atualizar
+git checkout main
+git pull work main
+
+# apagar branch local já mergeada
+git branch -d feature/nome-da-mudanca
+```
+
+## Build, lint e watch
+
+```bash
+npm install       # instala dependências (roda depois de clonar ou puxar mudanças no package.json)
+npm run build     # gera dist/css e dist/js a partir de scss/ e js/
+npm run watch     # rebuild automático ao salvar arquivos em scss/ ou js/
+npm run lint      # stylelint em scss/**/*.scss
+```
+
+`npm run build` sempre limpa `dist/` antes (script `clean`), então não
+precisa rodar `clean` manualmente.
+
+## Versionamento (semver)
+
+```bash
+# bump de versão (atualiza package.json, package-lock.json e cria tag git vX.Y.Z)
+npm version patch   # correções   0.1.0 -> 0.1.1
+npm version minor   # features   0.1.0 -> 0.2.0
+npm version major   # breaking   0.1.0 -> 1.0.0
+
+# depois do bump, subir o commit + a tag
+git push work main --follow-tags
+```
+
+## Publicação no npm
+
+Rodar sempre a partir da branch `main` já sincronizada e com o build
+funcionando (`npm run build` e `npm run lint` sem erro).
+
+```bash
+# login (uma vez por máquina, ou quando expirar)
+npm login
+
+# conferir com qual usuário está logado
+npm whoami
+
+# ver exatamente o que seria publicado (sem publicar)
+npm pack --dry-run
+
+# publicar de fato (publishConfig.access já está "public" no package.json)
+npm publish
+
+# publicar uma pré-release (ex: 0.2.0-beta.1), sem virar "latest"
+npm publish --tag beta
+```
+
+`prepublishOnly` já roda `npm run build && npm test` automaticamente antes
+de qualquer `npm publish` — se o build ou o lint falhar, a publicação é
+abortada.
+
+**Nunca rode `npm unpublish` em pacotes com mais de 72h publicados** — o
+npm restringe/impede isso por padrão; trate erros de publicação com uma
+nova versão de patch em vez de tentar apagar a anterior.
+
+## Atalho: commit + sync numa linha
+
+```bash
+git add caminho1 caminho2 && git commit -m "mensagem" && git push work main
+```
+
+## Checklist antes de publicar uma nova versão
+
+1. `git status` limpo (nada pendente).
+2. `npm run lint` e `npm run build` passando.
+3. `CHANGELOG.md` atualizado com o que mudou.
+4. `npm version <patch|minor|major>`.
+5. `git push work main --follow-tags`.
+6. `npm publish`.

package/docs/scss-architecture.md

@@ -0,0 +1,184 @@
+# Arquitetura SCSS do Clarus CSS
+
+## Objetivo
+
+A arquitetura SCSS do Clarus CSS organiza o framework em módulos pequenos, previsíveis e alinhados a uma abordagem híbrida: componentes prontos, utilitários reutilizáveis e tokens customizáveis por CSS Custom Properties.
+
+O arquivo de entrada oficial é:
+
+```text
+scss/clarus.scss
+```
+
+Esse arquivo deve reunir os módulos na ordem correta de geração do CSS final.
+
+## Estrutura
+
+```text
+scss/
+├── clarus.scss
+├── settings/
+├── tools/
+├── tokens/
+├── base/
+├── layout/
+├── forms/
+├── components/
+├── utilities/
+└── themes/
+```
+
+## Camadas
+
+### settings
+
+Define valores Sass usados em tempo de compilação:
+
+- Breakpoints.
+- Larguras de containers.
+- Escala de espaçamento.
+- Cores base.
+- Tipografia.
+- Raios de borda.
+
+Esses arquivos não devem gerar CSS diretamente.
+
+### tools
+
+Define mixins e funções Sass reutilizáveis.
+
+Exemplos:
+
+- `media-breakpoint-up`
+- `focus-ring`
+- `truncate`
+
+Esses arquivos também não devem gerar CSS diretamente.
+
+### tokens
+
+Gera CSS Custom Properties públicas em `:root`.
+
+Essa camada permite customização em CSS sem recompilar o framework.
+
+### base
+
+Define estilos globais mínimos:
+
+- `box-sizing`
+- `body`
+- tipografia base
+- fontes externas
+
+Essa camada deve permanecer pequena para evitar efeitos colaterais.
+
+### layout
+
+Define a base estrutural do framework:
+
+- Containers.
+- Rows.
+- Colunas.
+- Grid baseado em Flexbox.
+- Breakpoints compatíveis com a experiência do Bootstrap.
+
+O gutter do grid (`.row`/`.col-*`) é implementado via padding + margin negativo
+controlados pelas CSS Custom Properties `--clarus-gutter-x`/`--clarus-gutter-y`
+(não via `gap` do flexbox), porque `gap` não é descontado da largura em
+porcentagem das colunas numeradas (`.col-6`, `.col-md-4`), o que causaria
+estouro de linha. As classes `.g-*`/`.gx-*`/`.gy-*` (em `utilities/_spacing.scss`)
+controlam essas variáveis e só têm efeito dentro de uma `.row`. Para `gap`
+literal em qualquer container flex/grid fora do sistema de colunas, use
+`.gap-*`/`.gap-x-*`/`.gap-y-*`.
+
+### forms
+
+Agrupa estilos de formulários:
+
+- Linhas e colunas de formulário.
+- Labels.
+- Textos auxiliares.
+- Inputs.
+- Tamanhos de campo.
+- Estados de foco, desabilitado e leitura.
+
+### components
+
+Agrupa componentes prontos.
+
+Cada componente deve ter seu próprio arquivo parcial:
+
+- Buttons.
+- Cards.
+- Alerts.
+- Badges.
+- Tables.
+- Navbar.
+- Dropdown.
+- Modal.
+- Accordion.
+- Tabs.
+- Tooltips.
+- Toasts.
+- Pagination.
+- Breadcrumbs.
+
+### utilities
+
+Agrupa classes utilitárias reutilizáveis:
+
+- Display.
+- Flex alignment.
+- Spacing.
+- Visibility.
+
+Utilitários devem ser previsíveis, pequenos e combináveis.
+
+### themes
+
+Agrupa temas e variações globais.
+
+O primeiro tema obrigatório é o dark mode via:
+
+```html
+<html data-theme="dark">
+```
+
+## Convenções
+
+- Usar arquivos parciais com prefixo `_`.
+- Usar `@use` e `@forward`, evitando `@import` para módulos internos.
+- Manter `scss/clarus.scss` como único ponto de entrada público para o bundle completo.
+- Evitar estilos globais agressivos.
+- Preferir CSS Custom Properties para valores que usuários podem sobrescrever.
+- Preferir variáveis Sass para valores usados em geração de classes.
+
+## Pipeline de Build
+
+O build (`npm run build`) compila SCSS para CSS via Dart Sass, aplica PostCSS
+com Autoprefixer e gera versões minificadas com source maps em `dist/css/`.
+
+Para preservar a distribuição em arquivos separados (`layout.css`, `forms.css`,
+`components.css`, `helpers.css`), existem pontos de entrada auxiliares em
+`scss/entries/`, cada um combinando `tokens` + `base` + `themes` com o módulo
+correspondente, garantindo que qualquer um dos arquivos possa ser usado de
+forma isolada (com variáveis, reset e dark mode funcionando). Esses arquivos
+são exclusivos do processo de build e não substituem `scss/clarus.scss` como
+entrada pública para quem deseja o bundle completo.
+
+`scss/clarus.scss` também é compilado diretamente para `dist/css/clarus.css`
+(+ `.min.css`), como opção de import único para quem não precisa da distribuição
+granular. É esse bundle que o campo `style` do `package.json` aponta por padrão.
+
+Os nomes em `scss/entries/` usam o sufixo `-entry` (ex: `layout-entry.scss`)
+para evitar colisão com os módulos de mesmo nome (`@use "layout"` dentro de
+`scss/layout.scss` causaria um loop de importação).
+
+## Regra de Evolução
+
+Novos componentes devem seguir este fluxo:
+
+1. Criar `scss/components/_nome-do-componente.scss`.
+2. Adicionar o arquivo em `scss/components/_index.scss`.
+3. Documentar a API de classes em Markdown.
+4. Adicionar exemplo em `mockup/` quando fizer sentido.

package/js/clarus.js

@@ -0,0 +1 @@
+export {};

package/mockup/layout.html

@@ -6,24 +6,36 @@
     <title>Mockup - Layout</title>
 
     <!-- STYLES IMPORT -->
-    <link rel="stylesheet" href="../assets/css/layout.css">
-    <link rel="stylesheet" href="../assets/css/forms.css">
+    <link rel="stylesheet" href="../dist/css/layout.css">
+    <link rel="stylesheet" href="../dist/css/forms.css">
 </head>
 <body>
 
-    <div class="container-fluid p-2 gy-2">
-        <div class="row-fluid gx-2">
+    <div class="container p-2">
+        <!-- Grid numerada de 12 colunas, com gutter via .g-3 -->
+        <div class="row g-3">
+            <div class="col-md-8 p-2">col-md-8</div>
+            <div class="col-md-4 p-2">col-md-4</div>
+        </div>
+        <div class="row g-3 mt-3">
+            <div class="col-4 p-2">col-4</div>
+            <div class="col-4 p-2">col-4</div>
+            <div class="col-4 p-2">col-4</div>
+        </div>
+
+        <!-- Colunas de largura igual automática -->
+        <div class="row gx-2 mt-3">
             <div class="col-sm p-2">col 1</div>
             <div class="col-md p-2">col 2</div>
             <div class="col p-2">col 3</div>
         </div>
-        <div class="row row-fluid justify-content-start">
+        <div class="row row-fluid justify-content-start mt-3">
             <div class="col col-fluid p-2">col 1</div>
         </div>
     </div>
 
     <div class="container-fluid p-2">
-        <div class="form-row mt-3 gx-2">
+        <div class="form-row mt-3 gap-x-2">
             <div class="form-col">
                 <label for="input-text" class="form-label form-size-md">Nome completo</label>
                 <input type="text" class="form-control form-size-xxl" id="input-text" placeholder="Enter text" value="Jorge Reis">
@@ -31,7 +43,6 @@
             </div>
         </div>
     </div>
-    
 
 </body>
 </html>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clarus-css",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "A modern, minimal CSS framework for building interfaces with HTML, CSS, and vanilla JavaScript.",
   "keywords": [
     "css",
@@ -23,26 +23,52 @@
   "author": "Jorge Reis",
   "sideEffects": [
     "*.css",
-    "assets/**/*.css"
+    "dist/**/*.css"
   ],
-  "style": "assets/css/layout.css",
+  "style": "dist/css/clarus.css",
   "exports": {
-    "./layout.css": "./assets/css/layout.css",
-    "./forms.css": "./assets/css/forms.css",
-    "./components.css": "./assets/css/components.css",
-    "./helpers.css": "./assets/css/helpers.css"
+    ".": "./dist/css/clarus.css",
+    "./scss": "./scss/clarus.scss",
+    "./scss/*": "./scss/*",
+    "./layout.css": "./dist/css/layout.css",
+    "./forms.css": "./dist/css/forms.css",
+    "./components.css": "./dist/css/components.css",
+    "./helpers.css": "./dist/css/helpers.css",
+    "./js": "./dist/js/clarus.js"
   },
   "files": [
-    "assets/css",
+    "dist",
+    "scss",
+    "js",
     "docs",
     "mockup",
     "LICENSE",
     "README.md"
   ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "npm run clean && node scripts/build.mjs",
+    "watch": "node scripts/watch.mjs",
+    "lint:scss": "stylelint \"scss/**/*.scss\"",
+    "lint": "npm run lint:scss",
+    "test": "echo \"No tests configured yet\"",
+    "prepublishOnly": "npm run build && npm test"
+  },
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "test": "echo \"No tests configured yet\""
+  "devDependencies": {
+    "autoprefixer": "^10.5.2",
+    "chokidar": "^5.0.0",
+    "cssnano": "^8.0.2",
+    "esbuild": "^0.28.1",
+    "postcss": "^8.5.16",
+    "rimraf": "^6.1.3",
+    "sass": "^1.101.0",
+    "stylelint": "^17.14.0",
+    "stylelint-config-standard-scss": "^17.0.0"
   }
-}
+}

package/scss/base/_index.scss

@@ -0,0 +1,2 @@
+@use "reset";
+@use "typography";

package/scss/base/_reset.scss

@@ -0,0 +1,16 @@
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+}
+
+html {
+  line-height: var(--clarus-line-height-base);
+  text-size-adjust: 100%;
+}
+
+body {
+  margin: 0;
+  color: var(--clarus-color-text);
+  background-color: var(--clarus-color-surface);
+}

package/scss/base/_typography.scss

@@ -0,0 +1,17 @@
+@import url("https://fonts.googleapis.com/css2?family=Source+Code+Pro:ital,wght@0,200..900;1,200..900&display=swap");
+@import url("https://fonts.googleapis.com/css2?family=Google+Sans+Flex:opsz,wght@6..144,1..1000&display=swap");
+
+body,
+button,
+input,
+select,
+textarea {
+  font-family: var(--clarus-font-sans);
+}
+
+code,
+kbd,
+pre,
+samp {
+  font-family: var(--clarus-font-mono);
+}

package/scss/clarus.scss

@@ -0,0 +1,8 @@
+@charset "UTF-8";
+@use "tokens";
+@use "base";
+@use "layout";
+@use "forms";
+@use "components";
+@use "utilities";
+@use "themes";

package/scss/components/_accordion.scss

@@ -0,0 +1,4 @@
+.accordion {
+  display: flex;
+  flex-direction: column;
+}

package/scss/components/_alerts.scss

@@ -0,0 +1,5 @@
+.alert {
+  padding: 12px 16px;
+  border: 1px solid var(--clarus-color-border);
+  border-radius: var(--clarus-radius-md);
+}

package/scss/components/_badges.scss

@@ -0,0 +1,8 @@
+.badge {
+  display: inline-flex;
+  align-items: center;
+  min-height: 20px;
+  padding: 0 8px;
+  border-radius: 999px;
+  font-size: 0.75rem;
+}

package/scss/components/_breadcrumbs.scss

@@ -0,0 +1,5 @@
+.breadcrumb {
+  display: flex;
+  flex-wrap: wrap;
+  list-style: none;
+}

package/scss/components/_buttons.scss

@@ -0,0 +1,12 @@
+.btn {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-height: 38px;
+  padding: 0 12px;
+  border: 1px solid transparent;
+  border-radius: var(--clarus-radius-sm);
+  color: var(--clarus-color-white);
+  background-color: var(--clarus-color-primary);
+  cursor: pointer;
+}

package/scss/components/_cards.scss

@@ -0,0 +1,7 @@
+.card {
+  display: flex;
+  flex-direction: column;
+  border: 1px solid var(--clarus-color-border);
+  border-radius: var(--clarus-radius-lg);
+  background-color: var(--clarus-color-surface);
+}

package/scss/components/_dropdown.scss

@@ -0,0 +1,4 @@
+.dropdown {
+  position: relative;
+  display: inline-flex;
+}