tokka 0.2.3 → 0.2.5

package/compiler/index.d.ts

@@ -0,0 +1,478 @@
+import { z } from 'zod';
+
+declare const tokenTypeSchema: z.ZodEnum<["color", "number", "dimension", "radius", "shadow", "typography", "motion", "opacity", "zIndex"]>;
+declare const tokenSourceSchema: z.ZodEnum<["primitive", "semantic", "component"]>;
+declare const tokenSchema: z.ZodEffects<z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodEnum<["color", "number", "dimension", "radius", "shadow", "typography", "motion", "opacity", "zIndex"]>;
+    description: z.ZodString;
+    source: z.ZodEnum<["primitive", "semantic", "component"]>;
+    value: z.ZodOptional<z.ZodAny>;
+    modes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    references: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    deprecated: z.ZodOptional<z.ZodBoolean>;
+    replacedBy: z.ZodOptional<z.ZodString>;
+    figma: z.ZodOptional<z.ZodObject<{
+        collection: z.ZodOptional<z.ZodString>;
+        scopes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        variableName: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        collection?: string | undefined;
+        scopes?: string[] | undefined;
+        variableName?: string | undefined;
+    }, {
+        collection?: string | undefined;
+        scopes?: string[] | undefined;
+        variableName?: string | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    description: string;
+    type: "number" | "radius" | "motion" | "color" | "dimension" | "shadow" | "typography" | "opacity" | "zIndex";
+    source: "primitive" | "semantic" | "component";
+    value?: any;
+    tags?: string[] | undefined;
+    modes?: Record<string, any> | undefined;
+    figma?: {
+        collection?: string | undefined;
+        scopes?: string[] | undefined;
+        variableName?: string | undefined;
+    } | undefined;
+    references?: string[] | undefined;
+    deprecated?: boolean | undefined;
+    replacedBy?: string | undefined;
+}, {
+    id: string;
+    description: string;
+    type: "number" | "radius" | "motion" | "color" | "dimension" | "shadow" | "typography" | "opacity" | "zIndex";
+    source: "primitive" | "semantic" | "component";
+    value?: any;
+    tags?: string[] | undefined;
+    modes?: Record<string, any> | undefined;
+    figma?: {
+        collection?: string | undefined;
+        scopes?: string[] | undefined;
+        variableName?: string | undefined;
+    } | undefined;
+    references?: string[] | undefined;
+    deprecated?: boolean | undefined;
+    replacedBy?: string | undefined;
+}>, {
+    id: string;
+    description: string;
+    type: "number" | "radius" | "motion" | "color" | "dimension" | "shadow" | "typography" | "opacity" | "zIndex";
+    source: "primitive" | "semantic" | "component";
+    value?: any;
+    tags?: string[] | undefined;
+    modes?: Record<string, any> | undefined;
+    figma?: {
+        collection?: string | undefined;
+        scopes?: string[] | undefined;
+        variableName?: string | undefined;
+    } | undefined;
+    references?: string[] | undefined;
+    deprecated?: boolean | undefined;
+    replacedBy?: string | undefined;
+}, {
+    id: string;
+    description: string;
+    type: "number" | "radius" | "motion" | "color" | "dimension" | "shadow" | "typography" | "opacity" | "zIndex";
+    source: "primitive" | "semantic" | "component";
+    value?: any;
+    tags?: string[] | undefined;
+    modes?: Record<string, any> | undefined;
+    figma?: {
+        collection?: string | undefined;
+        scopes?: string[] | undefined;
+        variableName?: string | undefined;
+    } | undefined;
+    references?: string[] | undefined;
+    deprecated?: boolean | undefined;
+    replacedBy?: string | undefined;
+}>;
+type Token = z.infer<typeof tokenSchema>;
+type TokenType = z.infer<typeof tokenTypeSchema>;
+type TokenSource = z.infer<typeof tokenSourceSchema>;
+declare const tokenFileSchema: z.ZodObject<{
+    tokens: z.ZodArray<z.ZodEffects<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodEnum<["color", "number", "dimension", "radius", "shadow", "typography", "motion", "opacity", "zIndex"]>;
+        description: z.ZodString;
+        source: z.ZodEnum<["primitive", "semantic", "component"]>;
+        value: z.ZodOptional<z.ZodAny>;
+        modes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+        references: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        deprecated: z.ZodOptional<z.ZodBoolean>;
+        replacedBy: z.ZodOptional<z.ZodString>;
+        figma: z.ZodOptional<z.ZodObject<{
+            collection: z.ZodOptional<z.ZodString>;
+            scopes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+            variableName: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            collection?: string | undefined;
+            scopes?: string[] | undefined;
+            variableName?: string | undefined;
+        }, {
+            collection?: string | undefined;
+            scopes?: string[] | undefined;
+            variableName?: string | undefined;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        description: string;
+        type: "number" | "radius" | "motion" | "color" | "dimension" | "shadow" | "typography" | "opacity" | "zIndex";
+        source: "primitive" | "semantic" | "component";
+        value?: any;
+        tags?: string[] | undefined;
+        modes?: Record<string, any> | undefined;
+        figma?: {
+            collection?: string | undefined;
+            scopes?: string[] | undefined;
+            variableName?: string | undefined;
+        } | undefined;
+        references?: string[] | undefined;
+        deprecated?: boolean | undefined;
+        replacedBy?: string | undefined;
+    }, {
+        id: string;
+        description: string;
+        type: "number" | "radius" | "motion" | "color" | "dimension" | "shadow" | "typography" | "opacity" | "zIndex";
+        source: "primitive" | "semantic" | "component";
+        value?: any;
+        tags?: string[] | undefined;
+        modes?: Record<string, any> | undefined;
+        figma?: {
+            collection?: string | undefined;
+            scopes?: string[] | undefined;
+            variableName?: string | undefined;
+        } | undefined;
+        references?: string[] | undefined;
+        deprecated?: boolean | undefined;
+        replacedBy?: string | undefined;
+    }>, {
+        id: string;
+        description: string;
+        type: "number" | "radius" | "motion" | "color" | "dimension" | "shadow" | "typography" | "opacity" | "zIndex";
+        source: "primitive" | "semantic" | "component";
+        value?: any;
+        tags?: string[] | undefined;
+        modes?: Record<string, any> | undefined;
+        figma?: {
+            collection?: string | undefined;
+            scopes?: string[] | undefined;
+            variableName?: string | undefined;
+        } | undefined;
+        references?: string[] | undefined;
+        deprecated?: boolean | undefined;
+        replacedBy?: string | undefined;
+    }, {
+        id: string;
+        description: string;
+        type: "number" | "radius" | "motion" | "color" | "dimension" | "shadow" | "typography" | "opacity" | "zIndex";
+        source: "primitive" | "semantic" | "component";
+        value?: any;
+        tags?: string[] | undefined;
+        modes?: Record<string, any> | undefined;
+        figma?: {
+            collection?: string | undefined;
+            scopes?: string[] | undefined;
+            variableName?: string | undefined;
+        } | undefined;
+        references?: string[] | undefined;
+        deprecated?: boolean | undefined;
+        replacedBy?: string | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    tokens: {
+        id: string;
+        description: string;
+        type: "number" | "radius" | "motion" | "color" | "dimension" | "shadow" | "typography" | "opacity" | "zIndex";
+        source: "primitive" | "semantic" | "component";
+        value?: any;
+        tags?: string[] | undefined;
+        modes?: Record<string, any> | undefined;
+        figma?: {
+            collection?: string | undefined;
+            scopes?: string[] | undefined;
+            variableName?: string | undefined;
+        } | undefined;
+        references?: string[] | undefined;
+        deprecated?: boolean | undefined;
+        replacedBy?: string | undefined;
+    }[];
+}, {
+    tokens: {
+        id: string;
+        description: string;
+        type: "number" | "radius" | "motion" | "color" | "dimension" | "shadow" | "typography" | "opacity" | "zIndex";
+        source: "primitive" | "semantic" | "component";
+        value?: any;
+        tags?: string[] | undefined;
+        modes?: Record<string, any> | undefined;
+        figma?: {
+            collection?: string | undefined;
+            scopes?: string[] | undefined;
+            variableName?: string | undefined;
+        } | undefined;
+        references?: string[] | undefined;
+        deprecated?: boolean | undefined;
+        replacedBy?: string | undefined;
+    }[];
+}>;
+type TokenFile = z.infer<typeof tokenFileSchema>;
+declare const systemSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodString;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    modes: z.ZodArray<z.ZodString, "many">;
+    policies: z.ZodOptional<z.ZodObject<{
+        radius: z.ZodOptional<z.ZodEnum<["sharp", "rounded", "pill"]>>;
+        density: z.ZodOptional<z.ZodEnum<["compact", "comfortable", "spacious"]>>;
+        contrast: z.ZodOptional<z.ZodEnum<["low", "medium", "high"]>>;
+        motion: z.ZodOptional<z.ZodEnum<["none", "subtle", "expressive"]>>;
+    }, "strip", z.ZodTypeAny, {
+        radius?: "sharp" | "rounded" | "pill" | undefined;
+        density?: "compact" | "comfortable" | "spacious" | undefined;
+        contrast?: "low" | "medium" | "high" | undefined;
+        motion?: "none" | "subtle" | "expressive" | undefined;
+    }, {
+        radius?: "sharp" | "rounded" | "pill" | undefined;
+        density?: "compact" | "comfortable" | "spacious" | undefined;
+        contrast?: "low" | "medium" | "high" | undefined;
+        motion?: "none" | "subtle" | "expressive" | undefined;
+    }>>;
+    defaults: z.ZodOptional<z.ZodObject<{
+        font: z.ZodOptional<z.ZodString>;
+        iconStyle: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        font?: string | undefined;
+        iconStyle?: string | undefined;
+    }, {
+        font?: string | undefined;
+        iconStyle?: string | undefined;
+    }>>;
+    figma: z.ZodOptional<z.ZodObject<{
+        collections: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        collections?: string[] | undefined;
+    }, {
+        collections?: string[] | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    name: string;
+    description: string;
+    modes: string[];
+    tags?: string[] | undefined;
+    policies?: {
+        radius?: "sharp" | "rounded" | "pill" | undefined;
+        density?: "compact" | "comfortable" | "spacious" | undefined;
+        contrast?: "low" | "medium" | "high" | undefined;
+        motion?: "none" | "subtle" | "expressive" | undefined;
+    } | undefined;
+    defaults?: {
+        font?: string | undefined;
+        iconStyle?: string | undefined;
+    } | undefined;
+    figma?: {
+        collections?: string[] | undefined;
+    } | undefined;
+}, {
+    id: string;
+    name: string;
+    description: string;
+    modes: string[];
+    tags?: string[] | undefined;
+    policies?: {
+        radius?: "sharp" | "rounded" | "pill" | undefined;
+        density?: "compact" | "comfortable" | "spacious" | undefined;
+        contrast?: "low" | "medium" | "high" | undefined;
+        motion?: "none" | "subtle" | "expressive" | undefined;
+    } | undefined;
+    defaults?: {
+        font?: string | undefined;
+        iconStyle?: string | undefined;
+    } | undefined;
+    figma?: {
+        collections?: string[] | undefined;
+    } | undefined;
+}>;
+type System = z.infer<typeof systemSchema>;
+interface ResolvedToken extends Token {
+    resolvedValue?: string;
+    resolvedModes?: Record<string, string>;
+}
+interface CompilationContext {
+    tokens: Token[];
+    system: System;
+    mode: "tier0" | "tier1" | "tier2";
+}
+interface CompilationResult {
+    tokens: ResolvedToken[];
+    errors: CompilationError[];
+    warnings: CompilationWarning[];
+}
+interface CompilationError {
+    type: "schema" | "reference" | "cycle" | "naming" | "layering";
+    message: string;
+    tokenId?: string;
+}
+interface CompilationWarning {
+    type: "unused" | "deprecated" | "missing-mode";
+    message: string;
+    tokenId?: string;
+}
+
+interface LoadOptions {
+    cwd: string;
+    tokensDir?: string;
+}
+interface LoadedTokens {
+    primitives: Token[];
+    semantics: Token[];
+    components: Token[];
+    all: Token[];
+}
+/**
+ * Load token files from a project directory
+ */
+declare function loadTokens(options: LoadOptions): Promise<LoadedTokens>;
+/**
+ * Load system metadata
+ */
+declare function loadSystem(options: LoadOptions): Promise<System>;
+/**
+ * Check if tokens directory exists
+ */
+declare function hasTokens(cwd: string): Promise<boolean>;
+/**
+ * Check if system.json exists
+ */
+declare function hasSystem(cwd: string): Promise<boolean>;
+
+/**
+ * Validate token naming conventions
+ */
+declare function validateTokenNaming(tokens: Token[]): CompilationError[];
+/**
+ * Validate token uniqueness
+ */
+declare function validateTokenUniqueness(tokens: Token[]): CompilationError[];
+/**
+ * Validate token references exist
+ */
+declare function validateTokenReferences(tokens: Token[]): CompilationError[];
+/**
+ * Validate token layering rules (Tier 2 only)
+ */
+declare function validateTokenLayering(tokens: Token[], strict?: boolean): CompilationError[];
+/**
+ * Validate mode coverage
+ */
+declare function validateModeCoverage(tokens: Token[], requiredModes: string[]): CompilationError[];
+/**
+ * Run all validations
+ */
+declare function validateTokens(tokens: Token[], requiredModes: string[], options?: {
+    strict?: boolean;
+}): CompilationError[];
+
+/**
+ * Build a dependency graph from token references
+ */
+declare function buildDependencyGraph(tokens: Token[]): Map<string, Set<string>>;
+/**
+ * Detect cycles in the dependency graph
+ */
+declare function detectCycles(graph: Map<string, Set<string>>): string[][];
+/**
+ * Topological sort of tokens by dependencies
+ */
+declare function topologicalSort(tokens: Token[], graph: Map<string, Set<string>>): Token[];
+/**
+ * Resolve token values (alias-only in v1)
+ */
+declare function resolveTokens(tokens: Token[], graph: Map<string, Set<string>>): {
+    resolved: ResolvedToken[];
+    errors: CompilationError[];
+};
+
+interface CSSGeneratorOptions {
+    modeSelector?: {
+        strategy: "class" | "data-attribute";
+        selectors?: {
+            light: string;
+            dark: string;
+            [key: string]: string;
+        };
+    };
+}
+/**
+ * Convert token ID to CSS variable name
+ * surface.brand → --surface-brand
+ * button.primary.bg → --button-primary-bg
+ */
+declare function tokenIdToCSSVar(id: string): string;
+/**
+ * Parse color value to HSL triplet format
+ * Supports: hsl(...), oklch(...), hex, rgb(...)
+ */
+declare function parseColorToHSLTriplet(value: string): string;
+/**
+ * Generate CSS variables for a mode
+ */
+declare function generateCSSForMode(tokens: ResolvedToken[], mode: string | "default", options?: CSSGeneratorOptions): string;
+/**
+ * Generate complete CSS output
+ */
+declare function generateCSS(tokens: ResolvedToken[], system: System, options?: CSSGeneratorOptions): string;
+/**
+ * Generate CSS output files
+ */
+interface CSSOutput {
+    "tokens.css": string;
+}
+declare function generateCSSOutput(tokens: ResolvedToken[], system: System, options?: CSSGeneratorOptions): CSSOutput;
+
+/**
+ * Generate Tailwind config mapping semantic tokens to CSS vars
+ */
+declare function generateTailwindConfig(tokens: ResolvedToken[], _system: System): Record<string, any>;
+/**
+ * Generate Tailwind config file content
+ */
+declare function generateTailwindOutput(tokens: ResolvedToken[], system: System): string;
+
+/**
+ * Generate TypeScript token map with full typing
+ */
+declare function generateTypeScript(tokens: ResolvedToken[], system: System): string;
+/**
+ * Generate TypeScript output
+ */
+interface TypeScriptOutput {
+    "tokens.ts": string;
+}
+declare function generateTypeScriptOutput(tokens: ResolvedToken[], system: System): TypeScriptOutput;
+
+/**
+ * Generate Tokens Studio compatible format
+ */
+declare function generateFigmaTokens(tokens: ResolvedToken[], _system: System): Record<string, any>;
+/**
+ * Generate Figma token export file
+ */
+interface FigmaTokenOutput {
+    "tokka.tokens.json": string;
+}
+declare function generateFigmaTokenOutput(tokens: ResolvedToken[], system: System): FigmaTokenOutput;
+
+/**
+ * Main compilation function
+ */
+declare function compile(options: LoadOptions): Promise<CompilationResult>;
+
+export { type CSSGeneratorOptions, type CSSOutput, type CompilationContext, type CompilationError, type CompilationResult, type CompilationWarning, type FigmaTokenOutput, type LoadOptions, type LoadedTokens, type ResolvedToken, type System, type Token, type TokenFile, type TokenSource, type TokenType, type TypeScriptOutput, buildDependencyGraph, compile, detectCycles, generateCSS, generateCSSForMode, generateCSSOutput, generateFigmaTokenOutput, generateFigmaTokens, generateTailwindConfig, generateTailwindOutput, generateTypeScript, generateTypeScriptOutput, hasSystem, hasTokens, loadSystem, loadTokens, parseColorToHSLTriplet, resolveTokens, systemSchema, tokenFileSchema, tokenIdToCSSVar, tokenSchema, tokenSourceSchema, tokenTypeSchema, topologicalSort, validateModeCoverage, validateTokenLayering, validateTokenNaming, validateTokenReferences, validateTokenUniqueness, validateTokens };