@framingui/core 0.4.0

package/dist/theme.d.ts

@@ -0,0 +1,60 @@
+/**
+ * @framingui/core - Theme Module
+ * v2.1 Theme System - Load themes from .moai/themes/generated/
+ *
+ * MIGRATION NOTICE:
+ * - v1 themes (packages/core/themes/) have been removed
+ * - All themes now use v2.1 schema from .moai/themes/generated/
+ * - Use loadThemeV2() and ThemeV2 type for new code
+ */
+export { type ThemeV2, type ThemeMetaV2, type DesignDNA, type AtomicTokensV2, type SemanticTokensV2, type ComponentTokensV2, type StateLayerTokens, type MotionTokens, type ElevationTokens, type BorderTokens, type TypographyTokens, type DensityTokens, type EffectsTokens, type AIContext, type DarkModeOverrides, type OKLCHColorV2, loadThemeV2, listThemesV2, themeExistsV2, oklchToCSSV2, resolveTokenRef, getWhiteColor, CSS_VARIABLE_MAP, type CSSVariableName, } from './theme-v2.js';
+import { type ThemeV2, type ThemeMetaV2, type OKLCHColorV2 } from './theme-v2.js';
+/**
+ * Load a theme by ID
+ * @param themeId - Theme identifier (e.g., "atlantic-magazine-v1")
+ * @returns Theme object or null if not found
+ *
+ * @example
+ * ```typescript
+ * const theme = loadTheme('atlantic-magazine-v1');
+ * if (theme) {
+ *   console.log(theme.brandTone); // "professional"
+ * }
+ * ```
+ */
+export declare function loadTheme(themeId: string): ThemeV2 | null;
+/**
+ * List all available themes
+ * @returns Array of theme metadata
+ */
+export declare function listThemes(): ThemeMetaV2[];
+/**
+ * Check if a theme exists
+ * @param themeId - Theme identifier
+ */
+export declare function themeExists(themeId: string): boolean;
+/**
+ * Convert OKLCH color to CSS string
+ */
+export declare function oklchToCSS(color: OKLCHColorV2): string;
+export type Theme = ThemeV2;
+export type ThemeMeta = ThemeMetaV2;
+export type OKLCHColor = OKLCHColorV2;
+/**
+ * @deprecated v1 built-in themes have been removed. Use themes from .moai/themes/generated/
+ */
+export declare const BUILTIN_THEMES: readonly string[];
+/**
+ * @deprecated v1 built-in themes have been removed
+ */
+export type BuiltinThemeId = never;
+/**
+ * @deprecated v1 built-in themes have been removed
+ */
+export declare function isBuiltinTheme(_themeId: string): _themeId is BuiltinThemeId;
+/**
+ * @deprecated Use theme tokens directly. This function provided minimal v1 CSS output.
+ * For v2.1, use generateThemeCSS() from css-generator.ts with proper token resolution.
+ */
+export declare function generateCSSVariables(_theme: ThemeV2): Record<string, string>;
+//# sourceMappingURL=theme.d.ts.map

package/dist/theme.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme.d.ts","sourceRoot":"","sources":["../src/theme.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAEL,KAAK,OAAO,EACZ,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,SAAS,EACd,KAAK,iBAAiB,EACtB,KAAK,YAAY,EAGjB,WAAW,EACX,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,eAAe,EACf,aAAa,EAEb,gBAAgB,EAChB,KAAK,eAAe,GACrB,MAAM,eAAe,CAAC;AAMvB,OAAO,EAKL,KAAK,OAAO,EACZ,KAAK,WAAW,EAChB,KAAK,YAAY,EAClB,MAAM,eAAe,CAAC;AAEvB;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CAEzD;AAED;;;GAGG;AACH,wBAAgB,UAAU,IAAI,WAAW,EAAE,CAE1C;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAEtD;AAGD,MAAM,MAAM,KAAK,GAAG,OAAO,CAAC;AAC5B,MAAM,MAAM,SAAS,GAAG,WAAW,CAAC;AACpC,MAAM,MAAM,UAAU,GAAG,YAAY,CAAC;AAMtC;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,SAAS,MAAM,EAAO,CAAC;AAEpD;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,KAAK,CAAC;AAEnC;;GAEG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ,IAAI,cAAc,CAG3E;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAG5E"}

package/dist/theme.js

@@ -0,0 +1,78 @@
+/**
+ * @framingui/core - Theme Module
+ * v2.1 Theme System - Load themes from .moai/themes/generated/
+ *
+ * MIGRATION NOTICE:
+ * - v1 themes (packages/core/themes/) have been removed
+ * - All themes now use v2.1 schema from .moai/themes/generated/
+ * - Use loadThemeV2() and ThemeV2 type for new code
+ */
+// Re-export all v2.1 theme functionality
+export { 
+// Functions
+loadThemeV2, listThemesV2, themeExistsV2, oklchToCSSV2, resolveTokenRef, getWhiteColor, 
+// Constants
+CSS_VARIABLE_MAP, } from './theme-v2.js';
+// ============================================================================
+// Convenience Aliases (Primary API)
+// ============================================================================
+import { loadThemeV2, listThemesV2, themeExistsV2, oklchToCSSV2, } from './theme-v2.js';
+/**
+ * Load a theme by ID
+ * @param themeId - Theme identifier (e.g., "atlantic-magazine-v1")
+ * @returns Theme object or null if not found
+ *
+ * @example
+ * ```typescript
+ * const theme = loadTheme('atlantic-magazine-v1');
+ * if (theme) {
+ *   console.log(theme.brandTone); // "professional"
+ * }
+ * ```
+ */
+export function loadTheme(themeId) {
+    return loadThemeV2(themeId);
+}
+/**
+ * List all available themes
+ * @returns Array of theme metadata
+ */
+export function listThemes() {
+    return listThemesV2();
+}
+/**
+ * Check if a theme exists
+ * @param themeId - Theme identifier
+ */
+export function themeExists(themeId) {
+    return themeExistsV2(themeId);
+}
+/**
+ * Convert OKLCH color to CSS string
+ */
+export function oklchToCSS(color) {
+    return oklchToCSSV2(color);
+}
+// ============================================================================
+// Deprecated - Remove in next major version
+// ============================================================================
+/**
+ * @deprecated v1 built-in themes have been removed. Use themes from .moai/themes/generated/
+ */
+export const BUILTIN_THEMES = [];
+/**
+ * @deprecated v1 built-in themes have been removed
+ */
+export function isBuiltinTheme(_themeId) {
+    console.warn('isBuiltinTheme() is deprecated. All themes now come from .moai/themes/generated/');
+    return false;
+}
+/**
+ * @deprecated Use theme tokens directly. This function provided minimal v1 CSS output.
+ * For v2.1, use generateThemeCSS() from css-generator.ts with proper token resolution.
+ */
+export function generateCSSVariables(_theme) {
+    console.warn('generateCSSVariables() is deprecated. Use generateThemeCSS() for v2.1 themes.');
+    return {};
+}
+//# sourceMappingURL=theme.js.map

package/dist/theme.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme.js","sourceRoot":"","sources":["../src/theme.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,yCAAyC;AACzC,OAAO;AAmBL,YAAY;AACZ,WAAW,EACX,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,eAAe,EACf,aAAa;AACb,YAAY;AACZ,gBAAgB,GAEjB,MAAM,eAAe,CAAC;AAEvB,+EAA+E;AAC/E,oCAAoC;AACpC,+EAA+E;AAE/E,OAAO,EACL,WAAW,EACX,YAAY,EACZ,aAAa,EACb,YAAY,GAIb,MAAM,eAAe,CAAC;AAEvB;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,SAAS,CAAC,OAAe;IACvC,OAAO,WAAW,CAAC,OAAO,CAAC,CAAC;AAC9B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU;IACxB,OAAO,YAAY,EAAE,CAAC;AACxB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,OAAe;IACzC,OAAO,aAAa,CAAC,OAAO,CAAC,CAAC;AAChC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,UAAU,CAAC,KAAmB;IAC5C,OAAO,YAAY,CAAC,KAAK,CAAC,CAAC;AAC7B,CAAC;AAOD,+EAA+E;AAC/E,4CAA4C;AAC5C,+EAA+E;AAE/E;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAsB,EAAE,CAAC;AAOpD;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,QAAgB;IAC7C,OAAO,CAAC,IAAI,CAAC,kFAAkF,CAAC,CAAC;IACjG,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAe;IAClD,OAAO,CAAC,IAAI,CAAC,+EAA+E,CAAC,CAAC;IAC9F,OAAO,EAAE,CAAC;AACZ,CAAC"}

package/dist/token-resolver.d.ts

@@ -0,0 +1,69 @@
+/**
+ * @framingui/core - Token Resolution Engine
+ * Resolves token references to final values with fallback chain support
+ * [SPEC-COMPONENT-001-A] [TOKEN-RESOLUTION]
+ */
+import type { ThemeWithTokens } from './tokens.js';
+/** Token reference in dot notation: "atomic.color.blue.500" */
+export type TokenReference = string;
+/**
+ * Resolves a token reference to its final value
+ *
+ * Supports:
+ * - Dot-notation references: "atomic.color.blue.500"
+ * - Multi-level references: "component.button.primary.background" → "semantic.foreground.accent" → "atomic.color.blue.500"
+ * - Direct values: "#3b82f6" (returned as-is)
+ * - Circular reference detection
+ *
+ * @param ref - Token reference or direct value
+ * @param tokens - Theme token structure
+ * @param visited - Internal tracking for circular reference detection
+ * @returns Resolved token value
+ * @throws Error if token not found or circular reference detected
+ *
+ * @example
+ * ```typescript
+ * resolveToken('atomic.color.blue.500', tokens) // → '#3b82f6'
+ * resolveToken('semantic.background.page', tokens) // → '#f9fafb' (via atomic.color.neutral.50)
+ * resolveToken('#3b82f6', tokens) // → '#3b82f6' (direct value)
+ * ```
+ */
+export declare function resolveToken(ref: TokenReference, tokens: ThemeWithTokens['tokens'], visited?: Set<string>): string;
+/**
+ * Resolves token with fallback chain: Component → Semantic → Atomic
+ *
+ * Attempts to resolve tokens in order of specificity:
+ * 1. Component-level token (most specific)
+ * 2. Semantic-level token (medium specificity)
+ * 3. Atomic-level token (least specific, guaranteed to exist)
+ *
+ * This enables graceful degradation when component or semantic tokens are missing.
+ *
+ * @param componentRef - Component-level token reference
+ * @param semanticRef - Semantic-level token reference (fallback)
+ * @param atomicRef - Atomic-level token reference (final fallback)
+ * @param tokens - Theme token structure
+ * @returns Resolved token value from first successful resolution
+ * @throws Error if all fallback attempts fail
+ *
+ * @example
+ * ```typescript
+ * // Returns component token if exists
+ * resolveWithFallback(
+ *   'component.button.primary.background',
+ *   'semantic.foreground.accent',
+ *   'atomic.color.blue.500',
+ *   tokens
+ * ) // → '#3b82f6'
+ *
+ * // Falls back to semantic if component missing
+ * resolveWithFallback(
+ *   'component.button.nonexistent.background',
+ *   'semantic.foreground.accent',
+ *   'atomic.color.blue.500',
+ *   tokens
+ * ) // → '#3b82f6' (via semantic)
+ * ```
+ */
+export declare function resolveWithFallback(componentRef: string, semanticRef: string, atomicRef: string, tokens: ThemeWithTokens['tokens']): string;
+//# sourceMappingURL=token-resolver.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"token-resolver.d.ts","sourceRoot":"","sources":["../src/token-resolver.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAMnD,+DAA+D;AAC/D,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC;AAMpC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,YAAY,CAC1B,GAAG,EAAE,cAAc,EACnB,MAAM,EAAE,eAAe,CAAC,QAAQ,CAAC,EACjC,OAAO,GAAE,GAAG,CAAC,MAAM,CAAa,GAC/B,MAAM,CA0CR;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,mBAAmB,CACjC,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,eAAe,CAAC,QAAQ,CAAC,GAChC,MAAM,CAmBR"}

package/dist/token-resolver.js

@@ -0,0 +1,122 @@
+/**
+ * @framingui/core - Token Resolution Engine
+ * Resolves token references to final values with fallback chain support
+ * [SPEC-COMPONENT-001-A] [TOKEN-RESOLUTION]
+ */
+// ============================================================================
+// Token Resolution Functions
+// ============================================================================
+/**
+ * Resolves a token reference to its final value
+ *
+ * Supports:
+ * - Dot-notation references: "atomic.color.blue.500"
+ * - Multi-level references: "component.button.primary.background" → "semantic.foreground.accent" → "atomic.color.blue.500"
+ * - Direct values: "#3b82f6" (returned as-is)
+ * - Circular reference detection
+ *
+ * @param ref - Token reference or direct value
+ * @param tokens - Theme token structure
+ * @param visited - Internal tracking for circular reference detection
+ * @returns Resolved token value
+ * @throws Error if token not found or circular reference detected
+ *
+ * @example
+ * ```typescript
+ * resolveToken('atomic.color.blue.500', tokens) // → '#3b82f6'
+ * resolveToken('semantic.background.page', tokens) // → '#f9fafb' (via atomic.color.neutral.50)
+ * resolveToken('#3b82f6', tokens) // → '#3b82f6' (direct value)
+ * ```
+ */
+export function resolveToken(ref, tokens, visited = new Set()) {
+    // Prevent circular references
+    if (visited.has(ref)) {
+        throw new Error(`Circular token reference detected: ${ref}`);
+    }
+    visited.add(ref);
+    // If not a reference (doesn't contain dot or doesn't start with layer name), return as-is
+    if (!ref.includes('.')) {
+        return ref;
+    }
+    // Check if it's a token reference (starts with atomic, semantic, or component)
+    const startsWithLayer = ref.startsWith('atomic.') || ref.startsWith('semantic.') || ref.startsWith('component.');
+    if (!startsWithLayer) {
+        return ref; // Return direct value like "#3b82f6"
+    }
+    // Parse reference path
+    const parts = ref.split('.');
+    const [layer, ...path] = parts;
+    // Navigate token tree
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    let value = tokens;
+    for (const part of [layer, ...path]) {
+        value = value?.[part];
+        if (value === undefined) {
+            throw new Error(`Token not found: ${ref}`);
+        }
+    }
+    // If value is another reference, resolve recursively
+    if (typeof value === 'string' &&
+        (value.startsWith('atomic.') || value.startsWith('semantic.') || value.startsWith('component.'))) {
+        return resolveToken(value, tokens, visited);
+    }
+    return value;
+}
+/**
+ * Resolves token with fallback chain: Component → Semantic → Atomic
+ *
+ * Attempts to resolve tokens in order of specificity:
+ * 1. Component-level token (most specific)
+ * 2. Semantic-level token (medium specificity)
+ * 3. Atomic-level token (least specific, guaranteed to exist)
+ *
+ * This enables graceful degradation when component or semantic tokens are missing.
+ *
+ * @param componentRef - Component-level token reference
+ * @param semanticRef - Semantic-level token reference (fallback)
+ * @param atomicRef - Atomic-level token reference (final fallback)
+ * @param tokens - Theme token structure
+ * @returns Resolved token value from first successful resolution
+ * @throws Error if all fallback attempts fail
+ *
+ * @example
+ * ```typescript
+ * // Returns component token if exists
+ * resolveWithFallback(
+ *   'component.button.primary.background',
+ *   'semantic.foreground.accent',
+ *   'atomic.color.blue.500',
+ *   tokens
+ * ) // → '#3b82f6'
+ *
+ * // Falls back to semantic if component missing
+ * resolveWithFallback(
+ *   'component.button.nonexistent.background',
+ *   'semantic.foreground.accent',
+ *   'atomic.color.blue.500',
+ *   tokens
+ * ) // → '#3b82f6' (via semantic)
+ * ```
+ */
+export function resolveWithFallback(componentRef, semanticRef, atomicRef, tokens) {
+    // Try component token first
+    try {
+        return resolveToken(componentRef, tokens);
+    }
+    catch {
+        // Fallback to semantic token
+        try {
+            return resolveToken(semanticRef, tokens);
+        }
+        catch {
+            // Final fallback to atomic token
+            try {
+                return resolveToken(atomicRef, tokens);
+            }
+            catch {
+                throw new Error(`Failed to resolve token with fallback: ${componentRef} → ${semanticRef} → ${atomicRef}`);
+            }
+        }
+    }
+}
+//# sourceMappingURL=token-resolver.js.map

package/dist/token-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-resolver.js","sourceRoot":"","sources":["../src/token-resolver.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAWH,+EAA+E;AAC/E,6BAA6B;AAC7B,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,YAAY,CAC1B,GAAmB,EACnB,MAAiC,EACjC,UAAuB,IAAI,GAAG,EAAE;IAEhC,8BAA8B;IAC9B,IAAI,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;QACrB,MAAM,IAAI,KAAK,CAAC,sCAAsC,GAAG,EAAE,CAAC,CAAC;IAC/D,CAAC;IACD,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAEjB,0FAA0F;IAC1F,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QACvB,OAAO,GAAG,CAAC;IACb,CAAC;IAED,+EAA+E;IAC/E,MAAM,eAAe,GACnB,GAAG,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,WAAW,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;IAC3F,IAAI,CAAC,eAAe,EAAE,CAAC;QACrB,OAAO,GAAG,CAAC,CAAC,qCAAqC;IACnD,CAAC;IAED,uBAAuB;IACvB,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC7B,MAAM,CAAC,KAAK,EAAE,GAAG,IAAI,CAAC,GAAG,KAAK,CAAC;IAE/B,sBAAsB;IACtB,8DAA8D;IAC9D,IAAI,KAAK,GAAQ,MAAM,CAAC;IACxB,KAAK,MAAM,IAAI,IAAI,CAAC,KAAK,EAAE,GAAG,IAAI,CAAC,EAAE,CAAC;QACpC,KAAK,GAAG,KAAK,EAAE,CAAC,IAAI,CAAC,CAAC;QACtB,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CAAC,oBAAoB,GAAG,EAAE,CAAC,CAAC;QAC7C,CAAC;IACH,CAAC;IAED,qDAAqD;IACrD,IACE,OAAO,KAAK,KAAK,QAAQ;QACzB,CAAC,KAAK,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI,KAAK,CAAC,UAAU,CAAC,WAAW,CAAC,IAAI,KAAK,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC,EAChG,CAAC;QACD,OAAO,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9C,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,UAAU,mBAAmB,CACjC,YAAoB,EACpB,WAAmB,EACnB,SAAiB,EACjB,MAAiC;IAEjC,4BAA4B;IAC5B,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;IAC5C,CAAC;IAAC,MAAM,CAAC;QACP,6BAA6B;QAC7B,IAAI,CAAC;YACH,OAAO,YAAY,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;QAC3C,CAAC;QAAC,MAAM,CAAC;YACP,iCAAiC;YACjC,IAAI,CAAC;gBACH,OAAO,YAAY,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;YACzC,CAAC;YAAC,MAAM,CAAC;gBACP,MAAM,IAAI,KAAK,CACb,0CAA0C,YAAY,MAAM,WAAW,MAAM,SAAS,EAAE,CACzF,CAAC;YACJ,CAAC;QACH,CAAC;IACH,CAAC;AACH,CAAC"}