@clhaas/palette-kit 0.1.8 → 0.3.0

package/planning/roadmap-v0.3.md

@@ -0,0 +1,284 @@
+# Palette Kit — Roadmap v0.3
+
+> Roadmap técnico e executável para implementação da v0.3 do Palette Kit.
+> Este documento transforma a SPEC v0.3 em fases claras, incrementais e verificáveis,
+> com foco em DX, baixo risco e PRs pequenos.
+
+## Objetivos da v0.3
+
+- Tornar o Palette Kit excelente por padrão para qualquer desenvolvedor.
+- Manter o core runtime-first.
+- Adicionar tooling opcional (serializer, exporters, CLI, codegen).
+- Garantir autocomplete total e contratos explícitos.
+- Evitar big-bang refactors.
+
+## Princípios do roadmap
+
+- PRs pequenos e revisáveis.
+- Cada fase entrega valor isoladamente.
+- Nenhuma fase depende de comportamento implícito.
+- DX validada a cada etapa (autocomplete + JSDoc).
+
+## Fase 0 — Preparação (fundação)
+
+### Fase 0 — Objetivo
+
+Preparar a base do repositório para a v0.3 sem alterar comportamento público.
+
+### Fase 0 — Tarefas
+
+- [x] Criar branch `v0.3`.
+- [x] Congelar v0.2 (tag + changelog).
+- [x] Criar `src/planning/spec-v0.3.md`.
+- [x] Criar `src/planning/roadmap-v0.3.md`.
+- [x] Revisar `package.json` (exports atuais).
+- [x] Garantir build limpo.
+
+### Fase 0 — Critério de aceite
+
+- Nenhuma mudança funcional.
+- CI verde.
+
+## Fase 1 — Serializer público (núcleo da v0.3)
+
+### Fase 1 — Objetivo
+
+Criar a ponte oficial entre o resolver e outputs reais (CSS/RN/JSON).
+
+Referência: `src/planning/spec-serializer-v0.3.md`.
+
+### Fase 1 — Entregas
+
+- Novo módulo: `src/serialize/`.
+- Funções públicas: `serializeColor`, `serializeResolved`, `theme.serialize`.
+
+### Fase 1 — Tarefas
+
+- [x] Definir `ResolvedColor` público.
+- [x] Implementar serialização OKLCH.
+- [x] Implementar sRGB (hex / rgb / rgba).
+- [x] Implementar Display-P3.
+- [x] Implementar precision + strict.
+- [x] Implementar gamut mapping (`preferP3ThenCompress`).
+- [x] JSDoc completo (trade-offs + exemplos).
+
+### Fase 1 — Critério de aceite
+
+- Resolver continua retornando `BaseResolvedColor`.
+- Serializer funciona isoladamente.
+- API pública documentada.
+
+## Fase 2 — Helpers DX no runtime
+
+### Fase 2 — Objetivo
+
+Reduzir boilerplate para casos comuns sem esconder o core.
+
+### Fase 2 — Entregas
+
+- `theme.colorCss(...)`.
+- `theme.onSolidCss(...)`.
+- `resolveMany(...)`.
+- `withContext(...)` bound.
+
+### Fase 2 — Tarefas
+
+- [x] Implementar `resolveMany`.
+- [x] Implementar tema bound por contexto.
+- [x] Adicionar helpers CSS.
+- [x] Garantir typings corretos.
+- [x] JSDoc focado em DX.
+
+### Fase 2 — Critério de aceite
+
+- Menos código para casos comuns.
+- Zero breaking change.
+
+## Fase 3 — Token Registry (modelo deluxe)
+
+### Fase 3 — Objetivo
+
+Introduzir tokens declarativos sem acoplar ao runtime.
+
+### Fase 3 — Entregas
+
+- Modelo de token.
+- Estrutura de registry.
+- Validação básica.
+
+### Fase 3 — Tarefas
+
+- [x] Definir interface `TokenDefinition`.
+- [x] Definir `TokenRegistry`.
+- [x] Validar queries por token.
+- [x] Resolver tokens via `theme.resolve`.
+- [x] Garantir que tokens não carregam cor.
+
+### Fase 3 — Critério de aceite
+
+- Registry é puramente declarativo.
+- Runtime continua independente.
+
+## Fase 4 — Presets oficiais de tokens
+
+### Fase 4 — Objetivo
+
+Fornecer caminhos prontos para adoção rápida.
+
+### Fase 4 — Presets
+
+- `minimal-ui`.
+- `radixLike-ui`.
+- `modern-ui`.
+
+### Fase 4 — Tarefas
+
+- [x] Definir escopo de cada preset.
+- [x] Criar tokens base.
+- [x] Definir estados suportados.
+- [x] Documentar intenção semântica.
+- [x] Testar export + runtime.
+
+### Fase 4 — Critério de aceite
+
+- Presets utilizáveis sem configuração extra.
+- Tokens coerentes entre si.
+
+## Fase 5 — Exporters públicos (CSS / JSON)
+
+### Fase 5 — Objetivo
+
+Gerar artefatos determinísticos para build-time.
+
+### Fase 5 — Entregas
+
+- `exportThemeCss`.
+- `exportThemeJson`.
+
+### Fase 5 — Tarefas
+
+- [x] Definir opções de export.
+- [x] Implementar CSS vars com fallback.
+- [x] Implementar JSON estruturado.
+- [x] Garantir ordem determinística.
+- [x] Testes de snapshot.
+
+### Fase 5 — Critério de aceite
+
+- Outputs reproduzíveis.
+- Sem dependência do CLI.
+- Status: concluida.
+
+## Fase 6 — CLI tooling
+
+### Fase 6 — Objetivo
+
+Facilitar adoção em projetos médios e grandes.
+
+### Fase 6 — Comandos
+
+- `palette-kit init`.
+- `palette-kit build`.
+
+### Fase 6 — Tarefas
+
+- [x] Implementar `init`.
+- [x] Gerar `palette.config.ts`.
+- [x] Implementar `build`.
+- [x] Integrar exporters.
+- [x] Gerar artefatos em `dist/palette/`.
+- [x] Flags básicas (no magic).
+
+### Fase 6 — Critério de aceite
+
+- CLI previsível.
+- Nenhuma ação implícita.
+
+## Fase 7 — Codegen de types (DX máximo)
+
+### Fase 7 — Objetivo
+
+Autocomplete total sem amarrar o core.
+
+### Fase 7 — Entregas
+
+- `tokens.ts`.
+- `tokens.d.ts`.
+
+### Fase 7 — Tarefas
+
+- [x] Gerar objeto navegável.
+- [x] Gerar unions (`TokenName`, `ColorRole`).
+- [x] JSDoc por token.
+- [x] Integração com CLI build.
+
+### Fase 7 — Critério de aceite
+
+- Autocomplete funcionando out-of-the-box.
+- Zero impacto em runtime.
+
+## Fase 8 — Inferência forte e validações DX
+
+### Fase 8 — Objetivo
+
+Reduzir configuração obrigatória sem perder segurança.
+
+### Fase 8 — Tarefas
+
+- [x] Inferir `usage` por prefixo.
+- [x] Inferir `surface` quando óbvio.
+- [x] Implementar strict vs non-strict.
+- [x] Mensagens de erro didáticas.
+
+### Fase 8 — Critério de aceite
+
+- Menos parâmetros manuais.
+- Erros claros e acionáveis.
+
+## Fase 9 — Packaging e exports finais
+
+### Fase 9 — Objetivo
+
+Finalizar o shape público do pacote.
+
+### Fase 9 — Tarefas
+
+- [x] Definir subpath exports.
+- [x] Validar tree-shaking.
+- [x] Garantir compatibilidade ESM.
+- [x] Atualizar README.
+
+### Fase 9 — Critério de aceite
+
+- Um único pacote npm.
+- Imports claros e estáveis.
+
+## Fase 10 — QA final e release
+
+### Fase 10 — Objetivo
+
+Garantir qualidade antes do release.
+
+### Fase 10 — Checklist
+
+- [x] Testes unitários críticos.
+- [x] Testes de snapshot (exporters).
+- [x] Revisão de DX (autocomplete + docs).
+- [x] Atualizar changelog.
+- [x] Release v0.3.0.
+
+## Resultado esperado
+
+Ao final da v0.3, o Palette Kit será:
+
+- Fácil de usar no runtime.
+- Poderoso para projetos grandes.
+- Tipado, documentado e previsível.
+- Preparado para evolução (v0.4+).
+
+## Próximos passos (v0.4+)
+
+- Theming dinâmico por usuário.
+- Data-driven color APIs.
+- Plugins de framework (opcional).
+- Visual tooling / inspector.

package/planning/spec-serializer-v0.3.md

@@ -0,0 +1,324 @@
+# Palette Kit — SPEC Técnica do Serializer (v0.3)
+
+> Documento técnico que especifica em detalhe o Serializer público da v0.3.
+> Esta é a parte mais sensível da arquitetura, pois define o contrato entre o resolver matemático
+> e os outputs consumíveis (CSS, React Native, JSON, etc.).
+
+## 1. Papel do Serializer na arquitetura
+
+O Serializer é a camada de fronteira entre:
+
+- o core matemático do Palette Kit (resolver em OKLCH)
+- os formatos finais exigidos por plataformas reais
+
+Ele não decide cores, não resolve semântica e não altera intenção visual.
+Sua função é transformar dados já resolvidos em representações utilizáveis.
+
+## 2. Princípios fundamentais
+
+1. Pureza
+   - Serializar não deve alterar a cor semanticamente.
+   - Ajustes só ocorrem por gamut mapping explícito.
+2. Previsibilidade
+   - Mesma entrada + mesmas opções = mesma saída.
+   - Ordem de propriedades determinística.
+3. DX explícita
+   - Nada é automágico.
+   - Toda decisão relevante é configurável ou documentada.
+4. Separação de responsabilidades
+   - Resolver -> decide cor.
+   - Serializer -> decide formato.
+
+## 3. Entradas suportadas
+
+### 3.1 OKLCH channels
+
+```ts
+type OklchChannels = {
+  l: number
+  c: number
+  h: number
+  alpha?: number
+}
+```
+
+- Representa o contrato matemático base.
+- Usado diretamente por `serializeColor`.
+
+### 3.2 BaseResolvedColor
+
+```ts
+{
+  oklch: OklchChannels
+  step: number
+  variantUsed: string
+  seedUsed: string
+}
+```
+
+- Shape estável garantido na linha v0.x.
+- Usado por `serializeResolved`.
+
+### 3.3 ColorQuery (atalho DX)
+
+```ts
+serialize(theme, query, options)
+```
+
+- Combina:
+  1. `theme.resolve(query)`
+  2. `serializeResolved(...)`
+
+## 4. APIs públicas
+
+### 4.1 serializeColor
+
+```ts
+serializeColor(
+  oklch: OklchChannels,
+  options?: SerializeOptions
+): ResolvedColor
+```
+
+Uso:
+
+- casos de baixo nível
+- integrações customizadas
+- testes
+
+### 4.2 serializeResolved
+
+```ts
+serializeResolved(
+  color: BaseResolvedColor,
+  options?: SerializeOptions
+): ResolvedColor
+```
+
+Uso:
+
+- caminho padrão após `resolve`
+- preserva meta do resolver
+
+### 4.3 theme.serialize
+
+```ts
+theme.serialize(
+  query: ColorQuery,
+  options?: SerializeOptions
+): ResolvedColor
+```
+
+Uso:
+
+- caminho DX máximo
+- menos boilerplate
+
+## 5. SerializeOptions
+
+```ts
+type SerializeOptions = {
+  preferSpace?: "oklch" | "srgb" | "p3"
+  includeSpaces?: Array<"oklch" | "srgb" | "p3">
+  precision?: {
+    l?: number
+    c?: number
+    h?: number
+    alpha?: number
+  }
+  gamutMapping?: "clip" | "compressChroma" | "preferP3ThenCompress"
+  strict?: boolean
+  includeMeta?: boolean
+}
+```
+
+### Defaults obrigatórios
+
+| Opção | Default |
+| --- | --- |
+| preferSpace | "oklch" |
+| gamutMapping | "preferP3ThenCompress" |
+| precision | { l: 1, c: 3, h: 1, alpha: 2 } |
+| strict | false |
+| includeMeta | false |
+
+## 6. Saída: ResolvedColor
+
+```ts
+type ResolvedColor = {
+  value: string
+  alpha: number
+  oklch?: string
+  srgb?: string
+  p3?: string
+  meta?: ColorMeta
+}
+```
+
+### Regras
+
+- `value`:
+  - sempre presente
+  - corresponde a `preferSpace`
+- Outros espaços:
+  - só incluídos se listados em `includeSpaces`
+- `alpha`:
+  - sempre normalizado `[0..1]`
+
+## 7. Espaços de cor
+
+### 7.1 OKLCH
+
+Formato:
+
+```css
+oklch(L% C H / A)
+```
+
+Regras:
+
+- L sempre em `%`
+- C com precisão configurável
+- H normalizado `[0..360)`
+
+### 7.2 sRGB
+
+Formatos aceitos:
+
+- `#RRGGBB`
+- `rgb(r g b)`
+- `rgba(r g b / a)`
+
+Regras:
+
+- Preferir `hex` por default
+- `rgb/rgba` apenas se explicitado
+
+### 7.3 Display-P3
+
+Formato:
+
+```css
+color(display-p3 r g b / a)
+```
+
+Regras:
+
+- Valores normalizados `[0..1]`
+- Só emitido se:
+  - solicitado
+  - gamutMapping permitir
+
+## 8. Gamut Mapping
+
+### Estratégias
+
+#### clip
+
+- Corta valores fora do gamut
+- Pode distorcer percepção
+- Só recomendado para debug
+
+#### compressChroma
+
+- Reduz C mantendo L/H
+- Preserva intenção perceptual
+- Estratégia segura
+
+#### preferP3ThenCompress (default)
+
+1. Tenta P3
+2. Se falhar, comprime C
+3. Nunca clippa sem aviso
+
+## 9. Precision e arredondamento
+
+- Arredondamento ocorre no final
+- Nunca durante cálculos intermediários
+- Evita drift cumulativo
+
+## 10. Strict mode
+
+### strict = false (default)
+
+- Best-effort
+- Warnings em casos limite
+- Nunca lança erro fatal
+
+### strict = true
+
+- Erros lançados quando:
+  - conversão falha
+  - gamut impossível
+  - parâmetros inválidos
+
+Mensagens devem ser:
+
+- claras
+- acionáveis
+- sem jargon matemático
+
+## 11. Meta e diagnósticos
+
+Se `includeMeta: true`, incluir:
+
+```ts
+meta: {
+  spaceUsed: "oklch" | "srgb" | "p3"
+  gamutMapping: string
+  clipped?: boolean
+  compressed?: boolean
+}
+```
+
+Meta nunca influencia `value`.
+
+## 12. Ordem interna do algoritmo
+
+1. Receber entrada
+2. Normalizar alpha
+3. Converter OKLCH -> espaço alvo
+4. Aplicar gamut mapping
+5. Arredondar canais
+6. Gerar strings
+7. Montar `ResolvedColor`
+
+## 13. Testes obrigatórios
+
+### Unitários
+
+- Cada espaço isoladamente
+- Cada estratégia de gamut
+
+### Snapshot
+
+- Serializações completas
+- Comparação determinística
+
+### DX
+
+- Autocomplete
+- JSDoc visível no editor
+
+## 14. Critérios de aceite
+
+- Serializer não altera intenção visual
+- API estável e previsível
+- Erros claros em strict mode
+- Funciona isoladamente do core
+
+## 15. Anti‑padrões explícitos
+
+- Resolver dentro do serializer
+- Decidir contraste
+- Ajustar L/H sem pedido explícito
+- Comportamento implícito não documentado
+
+## Status
+
+SPEC técnica fechada e pronta para implementação.
+
+Próximo passo natural:
+
+- dividir essa spec em PRs pequenos
+- ou iniciar implementação começando por `serializeColor`