@framingui/core 0.4.0

package/dist/token-validation.d.ts

@@ -0,0 +1,432 @@
+/**
+ * @framingui/core - Token Validation
+ * Runtime validation using Zod schemas for 3-layer token architecture
+ * [SPEC-COMPONENT-001-A] [TOKEN-VALIDATION]
+ */
+import { z } from 'zod';
+/**
+ * Theme with Tokens Schema
+ * Validates complete 3-layer token structure with optional dark mode
+ */
+export declare const ThemeWithTokensSchema: z.ZodObject<{
+    /** 3-layer token structure */
+    tokens: z.ZodObject<{
+        atomic: z.ZodObject<{
+            /** Color palettes with shades */
+            color: z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>>;
+            /** Spacing scale */
+            spacing: z.ZodRecord<z.ZodString, z.ZodString>;
+            /** Border radius values */
+            radius: z.ZodRecord<z.ZodString, z.ZodString>;
+            /** Typography definitions */
+            typography: z.ZodRecord<z.ZodString, z.ZodObject<{
+                fontSize: z.ZodString;
+                lineHeight: z.ZodString;
+                fontWeight: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                fontSize: string;
+                fontWeight: string;
+                lineHeight: string;
+            }, {
+                fontSize: string;
+                fontWeight: string;
+                lineHeight: string;
+            }>>;
+            /** Shadow definitions */
+            shadow: z.ZodRecord<z.ZodString, z.ZodString>;
+            /** Transition definitions (optional) */
+            transition: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        }, "strip", z.ZodTypeAny, {
+            spacing: Record<string, string>;
+            color: Record<string, Record<string, string>>;
+            shadow: Record<string, string>;
+            typography: Record<string, {
+                fontSize: string;
+                fontWeight: string;
+                lineHeight: string;
+            }>;
+            radius: Record<string, string>;
+            transition?: Record<string, string> | undefined;
+        }, {
+            spacing: Record<string, string>;
+            color: Record<string, Record<string, string>>;
+            shadow: Record<string, string>;
+            typography: Record<string, {
+                fontSize: string;
+                fontWeight: string;
+                lineHeight: string;
+            }>;
+            radius: Record<string, string>;
+            transition?: Record<string, string> | undefined;
+        }>;
+        semantic: z.ZodObject<{
+            /** Background colors with semantic meaning */
+            background: z.ZodObject<{
+                page: z.ZodString;
+                surface: z.ZodString;
+                elevated: z.ZodString;
+                muted: z.ZodString;
+                inverse: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                page: string;
+                muted: string;
+                inverse: string;
+                elevated: string;
+                surface: string;
+            }, {
+                page: string;
+                muted: string;
+                inverse: string;
+                elevated: string;
+                surface: string;
+            }>;
+            /** Foreground (text) colors with semantic meaning */
+            foreground: z.ZodObject<{
+                primary: z.ZodString;
+                secondary: z.ZodString;
+                muted: z.ZodString;
+                inverse: z.ZodString;
+                accent: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                primary: string;
+                secondary: string;
+                muted: string;
+                accent: string;
+                inverse: string;
+            }, {
+                primary: string;
+                secondary: string;
+                muted: string;
+                accent: string;
+                inverse: string;
+            }>;
+            /** Border colors with semantic meaning */
+            border: z.ZodObject<{
+                default: z.ZodString;
+                muted: z.ZodString;
+                focus: z.ZodString;
+                error: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                focus: string;
+                default: string;
+                error: string;
+                muted: string;
+            }, {
+                focus: string;
+                default: string;
+                error: string;
+                muted: string;
+            }>;
+            /** Surface colors with semantic meaning */
+            surface: z.ZodObject<{
+                primary: z.ZodString;
+                secondary: z.ZodString;
+                tertiary: z.ZodString;
+                inverse: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                primary: string;
+                secondary: string;
+                inverse: string;
+                tertiary: string;
+            }, {
+                primary: string;
+                secondary: string;
+                inverse: string;
+                tertiary: string;
+            }>;
+        }, "strip", z.ZodTypeAny, {
+            background: {
+                page: string;
+                muted: string;
+                inverse: string;
+                elevated: string;
+                surface: string;
+            };
+            foreground: {
+                primary: string;
+                secondary: string;
+                muted: string;
+                accent: string;
+                inverse: string;
+            };
+            border: {
+                focus: string;
+                default: string;
+                error: string;
+                muted: string;
+            };
+            surface: {
+                primary: string;
+                secondary: string;
+                inverse: string;
+                tertiary: string;
+            };
+        }, {
+            background: {
+                page: string;
+                muted: string;
+                inverse: string;
+                elevated: string;
+                surface: string;
+            };
+            foreground: {
+                primary: string;
+                secondary: string;
+                muted: string;
+                accent: string;
+                inverse: string;
+            };
+            border: {
+                focus: string;
+                default: string;
+                error: string;
+                muted: string;
+            };
+            surface: {
+                primary: string;
+                secondary: string;
+                inverse: string;
+                tertiary: string;
+            };
+        }>;
+        component: z.ZodRecord<z.ZodString, z.ZodAny>;
+    }, "strip", z.ZodTypeAny, {
+        component: Record<string, any>;
+        semantic: {
+            background: {
+                page: string;
+                muted: string;
+                inverse: string;
+                elevated: string;
+                surface: string;
+            };
+            foreground: {
+                primary: string;
+                secondary: string;
+                muted: string;
+                accent: string;
+                inverse: string;
+            };
+            border: {
+                focus: string;
+                default: string;
+                error: string;
+                muted: string;
+            };
+            surface: {
+                primary: string;
+                secondary: string;
+                inverse: string;
+                tertiary: string;
+            };
+        };
+        atomic: {
+            spacing: Record<string, string>;
+            color: Record<string, Record<string, string>>;
+            shadow: Record<string, string>;
+            typography: Record<string, {
+                fontSize: string;
+                fontWeight: string;
+                lineHeight: string;
+            }>;
+            radius: Record<string, string>;
+            transition?: Record<string, string> | undefined;
+        };
+    }, {
+        component: Record<string, any>;
+        semantic: {
+            background: {
+                page: string;
+                muted: string;
+                inverse: string;
+                elevated: string;
+                surface: string;
+            };
+            foreground: {
+                primary: string;
+                secondary: string;
+                muted: string;
+                accent: string;
+                inverse: string;
+            };
+            border: {
+                focus: string;
+                default: string;
+                error: string;
+                muted: string;
+            };
+            surface: {
+                primary: string;
+                secondary: string;
+                inverse: string;
+                tertiary: string;
+            };
+        };
+        atomic: {
+            spacing: Record<string, string>;
+            color: Record<string, Record<string, string>>;
+            shadow: Record<string, string>;
+            typography: Record<string, {
+                fontSize: string;
+                fontWeight: string;
+                lineHeight: string;
+            }>;
+            radius: Record<string, string>;
+            transition?: Record<string, string> | undefined;
+        };
+    }>;
+    /** Optional dark mode token overrides */
+    darkMode: z.ZodOptional<z.ZodObject<{
+        tokens: z.ZodObject<{
+            semantic: z.ZodRecord<z.ZodString, z.ZodAny>;
+            component: z.ZodRecord<z.ZodString, z.ZodAny>;
+        }, "strip", z.ZodTypeAny, {
+            component: Record<string, any>;
+            semantic: Record<string, any>;
+        }, {
+            component: Record<string, any>;
+            semantic: Record<string, any>;
+        }>;
+    }, "strip", z.ZodTypeAny, {
+        tokens: {
+            component: Record<string, any>;
+            semantic: Record<string, any>;
+        };
+    }, {
+        tokens: {
+            component: Record<string, any>;
+            semantic: Record<string, any>;
+        };
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    tokens: {
+        component: Record<string, any>;
+        semantic: {
+            background: {
+                page: string;
+                muted: string;
+                inverse: string;
+                elevated: string;
+                surface: string;
+            };
+            foreground: {
+                primary: string;
+                secondary: string;
+                muted: string;
+                accent: string;
+                inverse: string;
+            };
+            border: {
+                focus: string;
+                default: string;
+                error: string;
+                muted: string;
+            };
+            surface: {
+                primary: string;
+                secondary: string;
+                inverse: string;
+                tertiary: string;
+            };
+        };
+        atomic: {
+            spacing: Record<string, string>;
+            color: Record<string, Record<string, string>>;
+            shadow: Record<string, string>;
+            typography: Record<string, {
+                fontSize: string;
+                fontWeight: string;
+                lineHeight: string;
+            }>;
+            radius: Record<string, string>;
+            transition?: Record<string, string> | undefined;
+        };
+    };
+    darkMode?: {
+        tokens: {
+            component: Record<string, any>;
+            semantic: Record<string, any>;
+        };
+    } | undefined;
+}, {
+    tokens: {
+        component: Record<string, any>;
+        semantic: {
+            background: {
+                page: string;
+                muted: string;
+                inverse: string;
+                elevated: string;
+                surface: string;
+            };
+            foreground: {
+                primary: string;
+                secondary: string;
+                muted: string;
+                accent: string;
+                inverse: string;
+            };
+            border: {
+                focus: string;
+                default: string;
+                error: string;
+                muted: string;
+            };
+            surface: {
+                primary: string;
+                secondary: string;
+                inverse: string;
+                tertiary: string;
+            };
+        };
+        atomic: {
+            spacing: Record<string, string>;
+            color: Record<string, Record<string, string>>;
+            shadow: Record<string, string>;
+            typography: Record<string, {
+                fontSize: string;
+                fontWeight: string;
+                lineHeight: string;
+            }>;
+            radius: Record<string, string>;
+            transition?: Record<string, string> | undefined;
+        };
+    };
+    darkMode?: {
+        tokens: {
+            component: Record<string, any>;
+            semantic: Record<string, any>;
+        };
+    } | undefined;
+}>;
+/**
+ * Validation result with detailed error information
+ */
+export interface ValidationResult {
+    /** Whether validation passed */
+    valid: boolean;
+    /** Error messages if validation failed (undefined if valid) */
+    errors?: string[];
+}
+/**
+ * Validates a theme with token structure
+ *
+ * Uses Zod schema validation to ensure:
+ * - All required atomic tokens are present
+ * - All required semantic tokens are defined
+ * - Component tokens structure is valid
+ * - Dark mode tokens (if present) follow correct structure
+ *
+ * @param theme - Theme object to validate
+ * @returns Validation result with success status and error messages
+ *
+ * @example
+ * ```typescript
+ * const result = validateTheme(myTheme);
+ * if (!result.valid) {
+ *   console.error('Validation errors:', result.errors);
+ * }
+ * ```
+ */
+export declare function validateTheme(theme: unknown): ValidationResult;
+//# sourceMappingURL=token-validation.d.ts.map

package/dist/token-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-validation.d.ts","sourceRoot":"","sources":["../src/token-validation.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAiGxB;;;GAGG;AACH,eAAO,MAAM,qBAAqB;IAChC,8BAA8B;;;YA3F9B,iCAAiC;;YAGjC,oBAAoB;;YAGpB,2BAA2B;;YAG3B,6BAA6B;;;;;;;;;;;;;;YAS7B,yBAAyB;;YAGzB,wCAAwC;;;;;;;;;;;;;;;;;;;;;;;;;;YASxC,8CAA8C;;;;;;;;;;;;;;;;;;;;YAS9C,qDAAqD;;;;;;;;;;;;;;;;;;;;YASrD,0CAA0C;;;;;;;;;;;;;;;;;YAQ1C,2CAA2C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IA0C3C,yCAAyC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EASzC,CAAC;AAMH;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,gCAAgC;IAChC,KAAK,EAAE,OAAO,CAAC;IAEf,+DAA+D;IAC/D,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,CAc9D"}

package/dist/token-validation.js

@@ -0,0 +1,140 @@
+/**
+ * @framingui/core - Token Validation
+ * Runtime validation using Zod schemas for 3-layer token architecture
+ * [SPEC-COMPONENT-001-A] [TOKEN-VALIDATION]
+ */
+import { z } from 'zod';
+// ============================================================================
+// Zod Schema Definitions
+// ============================================================================
+/**
+ * Atomic Tokens Schema - Layer 1
+ * Validates raw design values (colors, spacing, typography, etc.)
+ */
+const AtomicTokensSchema = z.object({
+    /** Color palettes with shades */
+    color: z.record(z.record(z.string())),
+    /** Spacing scale */
+    spacing: z.record(z.string()),
+    /** Border radius values */
+    radius: z.record(z.string()),
+    /** Typography definitions */
+    typography: z.record(z.object({
+        fontSize: z.string(),
+        lineHeight: z.string(),
+        fontWeight: z.string(),
+    })),
+    /** Shadow definitions */
+    shadow: z.record(z.string()),
+    /** Transition definitions (optional) */
+    transition: z.record(z.string()).optional(),
+});
+/**
+ * Semantic Tokens Schema - Layer 2
+ * Validates meaning-based token mappings
+ */
+const SemanticTokensSchema = z.object({
+    /** Background colors with semantic meaning */
+    background: z.object({
+        page: z.string(),
+        surface: z.string(),
+        elevated: z.string(),
+        muted: z.string(),
+        inverse: z.string(),
+    }),
+    /** Foreground (text) colors with semantic meaning */
+    foreground: z.object({
+        primary: z.string(),
+        secondary: z.string(),
+        muted: z.string(),
+        inverse: z.string(),
+        accent: z.string(),
+    }),
+    /** Border colors with semantic meaning */
+    border: z.object({
+        default: z.string(),
+        muted: z.string(),
+        focus: z.string(),
+        error: z.string(),
+    }),
+    /** Surface colors with semantic meaning */
+    surface: z.object({
+        primary: z.string(),
+        secondary: z.string(),
+        tertiary: z.string(),
+        inverse: z.string(),
+    }),
+});
+/**
+ * Component Tokens Schema - Layer 3
+ * Validates component-specific token bindings
+ * Flexible to allow extensible component definitions
+ */
+const ComponentTokensSchema = z.record(z.any());
+/**
+ * Dark Mode Semantic Tokens Schema
+ * Allows partial overrides of semantic tokens for dark mode
+ * Uses flexible validation since dark mode is opt-in and can override any semantic token
+ */
+const DarkModeSemanticTokensSchema = z.record(z.any());
+/**
+ * Dark Mode Component Tokens Schema
+ * Allows partial overrides of component tokens for dark mode
+ * Uses flexible validation for extensibility
+ */
+const DarkModeComponentTokensSchema = z.record(z.any());
+/**
+ * Theme with Tokens Schema
+ * Validates complete 3-layer token structure with optional dark mode
+ */
+export const ThemeWithTokensSchema = z.object({
+    /** 3-layer token structure */
+    tokens: z.object({
+        atomic: AtomicTokensSchema,
+        semantic: SemanticTokensSchema,
+        component: ComponentTokensSchema,
+    }),
+    /** Optional dark mode token overrides */
+    darkMode: z
+        .object({
+        tokens: z.object({
+            semantic: DarkModeSemanticTokensSchema,
+            component: DarkModeComponentTokensSchema,
+        }),
+    })
+        .optional(),
+});
+/**
+ * Validates a theme with token structure
+ *
+ * Uses Zod schema validation to ensure:
+ * - All required atomic tokens are present
+ * - All required semantic tokens are defined
+ * - Component tokens structure is valid
+ * - Dark mode tokens (if present) follow correct structure
+ *
+ * @param theme - Theme object to validate
+ * @returns Validation result with success status and error messages
+ *
+ * @example
+ * ```typescript
+ * const result = validateTheme(myTheme);
+ * if (!result.valid) {
+ *   console.error('Validation errors:', result.errors);
+ * }
+ * ```
+ */
+export function validateTheme(theme) {
+    const result = ThemeWithTokensSchema.safeParse(theme);
+    if (!result.success) {
+        return {
+            valid: false,
+            errors: result.error.errors.map(e => {
+                const path = e.path.join('.');
+                return `${path}: ${e.message}`;
+            }),
+        };
+    }
+    return { valid: true };
+}
+//# sourceMappingURL=token-validation.js.map

package/dist/token-validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-validation.js","sourceRoot":"","sources":["../src/token-validation.ts"],"names":[],"mappings":"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"}