@clhaas/palette-kit 0.1.8 → 0.3.0

package/planning/spec-v0.3.md

@@ -0,0 +1,305 @@
+# Palette Kit — SPEC v0.3
+
+> Especificação formal da versão v0.3 do Palette Kit.  
+> Documento orientado à implementação, com foco absoluto em Developer Experience (DX), contratos explícitos e evolução sustentável do produto.
+
+---
+
+## 1. Visão geral
+
+A v0.3 transforma o Palette Kit em uma biblioteca **runtime-first**, com **DX elevada por padrão**, contratos públicos claros e **tooling opcional** (serializers, exporters, CLI e codegen).
+
+A biblioteca passa a atender bem:
+
+- desenvolvedores comuns (uso direto no runtime)
+- times grandes (token registry, exporters, codegen)
+- ambientes web e mobile (web / React Native)
+
+---
+
+## 2. Produto
+
+- **Runtime-first** é o caminho oficial
+- CLI, exporters e codegen são **helpers**, não dependências obrigatórias
+- A lib deve ser **útil imediatamente após instalar**
+
+---
+
+## 3. Resolver (core)
+
+### 3.1 Contrato
+
+- `createTheme()` permanece como entrypoint
+- `theme.resolve()` e `theme.onSolid()` retornam **BaseResolvedColor**
+- `BaseResolvedColor`:
+  - **não é exportado como type**
+  - **tem shape estável garantido em toda a linha v0.x**
+- Strings de cor **não** são retornadas automaticamente
+
+### 3.2 Justificativa
+
+- Mantém o core agnóstico de output
+- Evita acoplamento com CSS, React Native ou JSON
+- Facilita evolução futura (novos formatos, novos targets)
+
+---
+
+## 4. Serializer público (camadas de DX)
+
+### 4.1 Objetivo
+
+Fornecer uma **ponte oficial e tipada** entre o resolver e o mundo real (CSS, RN, JSON), sem esconder decisões importantes do desenvolvedor.
+
+### 4.2 APIs obrigatórias
+
+```ts
+serializeColor(oklch, options?) -> ResolvedColor
+serializeResolved(baseResolved, options?) -> ResolvedColor
+theme.serialize(query, options?) -> ResolvedColor
+```
+
+### 4.3 Requisitos
+
+- Suporte a:
+  - `oklch()`
+  - `hex`, `rgb()`, `rgba()`
+  - `color(display-p3 ...)`
+- Opções:
+  - `preferSpace`
+  - `includeSpaces`
+  - `precision`
+  - `strict`
+- Estratégia de gamut mapping default:
+  - `preferP3ThenCompress`
+- `ResolvedColor`:
+  - contém strings serializadas
+  - pode incluir múltiplos espaços
+  - pode incluir metadados opcionais
+- **JSDoc obrigatório**, explicando:
+  - trade-offs entre espaços de cor
+  - implicações de gamut mapping
+  - impacto de precisão e strict mode
+
+---
+
+## 5. Exporters públicos (CSS / JSON)
+
+### 5.1 Objetivo
+
+Gerar artefatos determinísticos para projetos que desejam tokens persistentes, sem obrigar esse modelo no runtime.
+
+### 5.2 APIs públicas
+
+```ts
+exportThemeCss(theme, tokenMap, options)
+exportThemeJson(theme, tokenMap, options)
+```
+
+### 5.3 Regras
+
+- Exporters **não são obrigatórios** para uso do runtime
+- Outputs devem ser:
+  - determinísticos
+  - ordenados
+  - previsíveis
+- CSS:
+  - CSS variables com fallback
+  - override progressivo via `@supports`
+- JSON:
+  - estrutura estável
+  - separação explícita por contexto (`light` / `dark`)
+
+---
+
+## 6. Token Registry (caminho deluxe)
+
+### 6.1 Modelo
+
+Tokens são definidos como **objetos ricos**, não apenas nomes:
+
+```ts
+{
+  name: "bg.app",
+  description: "Application background",
+  query: { role, usage, surface },
+  category: "background",
+  states?: {
+    hover?: boolean
+    active?: boolean
+  }
+}
+```
+
+### 6.2 Regras
+
+- Registry é **declarativo**
+- Tokens:
+  - não carregam valores de cor
+  - sempre resolvem via `theme.resolve`
+- Registry é consumido por:
+  - exporters
+  - CLI
+  - codegen
+
+---
+
+## 7. Estados — modelo híbrido
+
+- Token registry define **tokens base**
+- Estados (`hover`, `active`, etc.) são **operadores**
+- CLI e exporters:
+  - podem gerar tokens derivados
+  - nunca duplicam lógica de resolução
+
+---
+
+## 8. Presets de token map (obrigatórios)
+
+### Presets oficiais
+
+1. `minimal-ui`
+2. `radixLike-ui`
+3. `modern-ui`
+
+Cada preset define:
+
+- tokens base
+- categorias
+- estados suportados
+- documentação embutida (descrições e intenção semântica)
+
+---
+
+## 9. CLI tooling
+
+### 9.1 `palette-kit init`
+
+- Cria `palette.config.ts`
+- Arquivo totalmente tipado
+- Com JSDoc explicativo
+- Sem comportamento mágico
+- Não gera tokens automaticamente
+
+### 9.2 `palette-kit build`
+
+- Gera artefatos em `dist/palette/`:
+  - `tokens.css`
+  - `tokens.json`
+  - `tokens.ts`
+  - `tokens.d.ts`
+- Pode gerar:
+  - `report.md` (opcional)
+- Flag `--watch` é opcional e **não MVP**
+
+---
+
+## 10. Codegen de types (DX máximo)
+
+### 10.1 Objetivos
+
+- Autocomplete completo
+- Navegação por objeto
+- Zero custo em runtime
+
+### 10.2 Outputs
+
+- Objeto navegável:
+
+  ```ts
+  tokens.bg.app
+  tokens.text.primary
+  ```
+
+- Unions:
+
+  ```ts
+  type TokenName = ...
+  type ColorRole = ...
+  ```
+
+### 10.3 Regras
+
+- JSDoc por token
+- Compatível com editores comuns
+- Core runtime continua aceitando `string`
+
+---
+
+## 11. Autocomplete sem amarrar o core
+
+- Runtime:
+  - aceita `string`
+- Tooling:
+  - gera types específicos por projeto
+- APIs automaticamente se beneficiam desses tipos
+
+---
+
+## 12. `theme.color(role, options)` com inferência forte
+
+### Comportamento
+
+- Inferir automaticamente:
+  - `usage`
+  - `surface`
+  - `variant`
+- Inferência baseada no prefixo do role
+
+### Strict mode
+
+- `strict: true`
+  - erro claro, didático e acionável
+- `strict: false`
+  - fallback seguro
+  - warning explícito
+
+---
+
+## 13. Ergonomia adicional
+
+### APIs
+
+- `resolveMany(queries[])`
+- `withContext("light" | "dark")` retorna um tema bound
+
+### Helpers
+
+- `theme.colorCss(...)`
+- `theme.onSolidCss(...)`
+
+---
+
+## 14. Packaging
+
+- Um único pacote npm
+- Uso de **subpath exports**:
+
+```json
+{
+  "exports": {
+    ".": "./dist/index.js",
+    "./serialize": "./dist/serialize.js",
+    "./export": "./dist/export.js",
+    "./cli": "./dist/cli.js"
+  }
+}
+```
+
+---
+
+## 15. Princípios de DX
+
+- Runtime-first por default
+- Contratos explícitos e previsíveis
+- Zero comportamento oculto
+- JSDoc tratado como parte da API
+- Determinismo acima de “conveniência mágica”
+
+---
+
+## 16. Critérios de aceite
+
+- Build passa
+- Nenhum import circular
+- API pública corresponde integralmente à spec
+- DX validável apenas via autocomplete + hover docs

package/src/cli/args.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vitest";
+
+import { CliUsageError, parseArgs } from "./args.js";
+
+describe("cli args", () => {
+  it("parses init command", () => {
+    const parsed = parseArgs(["init"]);
+    expect(parsed.command).toBe("init");
+  });
+
+  it("parses build command with flags", () => {
+    const parsed = parseArgs(["build", "--config", "custom.ts", "--outDir", "out", "--report"]);
+    expect(parsed.command).toBe("build");
+    expect(parsed.flags.config).toBe("custom.ts");
+    expect(parsed.flags.outDir).toBe("out");
+    expect(parsed.flags.report).toBe(true);
+  });
+
+  it("recognizes help and version flags", () => {
+    expect(parseArgs(["--help"]).help).toBe(true);
+    expect(parseArgs(["--version"]).version).toBe(true);
+  });
+
+  it("throws on unknown arguments", () => {
+    expect(() => parseArgs(["build", "wat"])).toThrow(CliUsageError);
+  });
+});
+

package/src/cli/args.ts

@@ -0,0 +1,66 @@
+export class CliUsageError extends Error {
+  override name = "CliUsageError";
+}
+
+export const HELP_TEXT = `palette-kit <command>
+
+Commands:
+  palette-kit init [--force] [--path <dir>]
+  palette-kit build [--config <path>] [--outDir <dir>] [--report]
+
+Options:
+  -h, --help       Show help
+  -v, --version    Show version
+`;
+
+export type ParsedArgs = {
+  command?: string;
+  help: boolean;
+  version: boolean;
+  flags: Record<string, string | boolean>;
+};
+
+export const COMMANDS = ["init", "build"] as const;
+
+export const parseArgs = (argv: string[]): ParsedArgs => {
+  const first = argv[0];
+  const command = first && !first.startsWith("-") ? first : undefined;
+  const rest = command ? argv.slice(1) : argv;
+  const flags: Record<string, string | boolean> = {};
+
+  let i = 0;
+  while (i < rest.length) {
+    const value = rest[i];
+    if (value === undefined) break;
+    if (value === "-h" || value === "--help") {
+      flags.help = true;
+      i += 1;
+      continue;
+    }
+    if (value === "-v" || value === "--version") {
+      flags.version = true;
+      i += 1;
+      continue;
+    }
+    if (value.startsWith("--")) {
+      const key = value.slice(2);
+      const next = rest[i + 1];
+      if (next && !next.startsWith("--")) {
+        flags[key] = next;
+        i += 2;
+      } else {
+        flags[key] = true;
+        i += 1;
+      }
+      continue;
+    }
+    throw new CliUsageError(`Unknown argument: ${value}`);
+  }
+
+  return {
+    command,
+    help: Boolean(flags.help),
+    version: Boolean(flags.version),
+    flags,
+  };
+};

package/src/cli/codegen/__snapshots__/tokens.test.ts.snap

@@ -0,0 +1,87 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`codegen tokens > generates navigable tokens.ts and tokens.d.ts 1`] = `
+"/* This file is generated by palette-kit build (Phase 7). */
+
+export const tokens = {
+bg: {
+  /**
+   * App background.
+   * @token bg.app
+   * @category bg
+   */
+  app: "bg.app",
+  },
+border: {
+  /**
+   * Default border color.
+   * @token border.default
+   * @category border
+   */
+  "default": "border.default",
+  },
+text: {
+  /**
+   * Primary text on standard surfaces.
+   * @token text.primary
+   * @category text
+   * @states hover
+   */
+  primary: "text.primary",
+  },
+} as const;
+
+export const tokenNames = [
+  "bg.app",
+  "border.default",
+  "text.primary"
+] as const;
+
+export type TokenName = (typeof tokenNames)[number];
+
+export type ColorRole = TokenName;
+"
+`;
+
+exports[`codegen tokens > generates navigable tokens.ts and tokens.d.ts 2`] = `
+"/* This file is generated by palette-kit build (Phase 7). */
+
+export declare const tokens: {
+bg: {
+  /**
+   * App background.
+   * @token bg.app
+   * @category bg
+   */
+  app: "bg.app";
+  };
+border: {
+  /**
+   * Default border color.
+   * @token border.default
+   * @category border
+   */
+  "default": "border.default";
+  };
+text: {
+  /**
+   * Primary text on standard surfaces.
+   * @token text.primary
+   * @category text
+   * @states hover
+   */
+  primary: "text.primary";
+  };
+};
+
+export declare const tokenNames: readonly [
+  "bg.app",
+  "border.default",
+  "text.primary"
+];
+
+export type TokenName = (typeof tokenNames)[number];
+
+export type ColorRole = TokenName;
+"
+`;

package/src/cli/codegen/tokens.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it } from "vitest";
+
+import type { TokenRegistry } from "../../types/index.js";
+import { generateTokenArtifacts } from "./tokens.js";
+
+describe("codegen tokens", () => {
+  const registry: TokenRegistry = {
+    tokens: {
+      "bg.app": {
+        name: "bg.app",
+        description: "App background.",
+        category: "bg",
+        query: { role: "bg.app", usage: "bg", surface: "app" },
+      },
+      "text.primary": {
+        name: "text.primary",
+        description: "Primary text on standard surfaces.",
+        category: "text",
+        query: { role: "text.primary", usage: "text", surface: "surface" },
+        states: { hover: true },
+      },
+      "border.default": {
+        name: "border.default",
+        description: "Default border color.",
+        category: "border",
+        query: { role: "border.default", usage: "border", surface: "surface" },
+      },
+    },
+  };
+
+  it("generates navigable tokens.ts and tokens.d.ts", () => {
+    const { tokensTs, tokensDts } = generateTokenArtifacts(registry);
+
+    expect(tokensTs).toContain('export const tokens = {');
+    expect(tokensTs).toContain('bg: {');
+    expect(tokensTs).toContain('app: "bg.app"');
+    expect(tokensTs).toContain('text: {');
+    expect(tokensTs).toContain('primary: "text.primary"');
+
+    expect(tokensTs).toMatchSnapshot();
+    expect(tokensDts).toMatchSnapshot();
+  });
+
+  it("is deterministic regardless of registry object order", () => {
+    const shuffled: TokenRegistry = {
+      tokens: {
+        "text.primary": registry.tokens["text.primary"],
+        "bg.app": registry.tokens["bg.app"],
+        "border.default": registry.tokens["border.default"],
+      },
+    };
+
+    const a = generateTokenArtifacts(registry);
+    const b = generateTokenArtifacts(shuffled);
+
+    expect(b.tokenNames).toEqual(a.tokenNames);
+    expect(b.tokensTs).toBe(a.tokensTs);
+    expect(b.tokensDts).toBe(a.tokensDts);
+  });
+});
+