@styleframe/core 2.2.0 → 2.4.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @styleframe/core
 
+## 2.4.0
+
+### Minor Changes
+
+- [#63](https://github.com/styleframe-dev/styleframe/pull/63) [`ec430e1`](https://github.com/styleframe-dev/styleframe/commit/ec430e11502b3dba69c20ee10b24f0302008883c) Thanks [@alexgrozav](https://github.com/alexgrozav)! - feat: add styleframe runtime for recipes
+
+## 2.3.0
+
+### Minor Changes
+
+- [#68](https://github.com/styleframe-dev/styleframe/pull/68) [`653d1fc`](https://github.com/styleframe-dev/styleframe/commit/653d1fc4e8fb80f8c3371e728ffc962cf1fb1cec) Thanks [@alexgrozav](https://github.com/alexgrozav)! - feat: add support for dot notation in variable names
+
 ## 2.2.0
 
 ### Minor Changes

package/dist/styleframe.d.ts

@@ -55,14 +55,162 @@ export declare function createKeyframesFunction(parent: Container, root: Root):
 
 export declare function createMediaFunction(parent: Container, root: Root): (query: string, declarationsOrCallback?: DeclarationsBlock | DeclarationsCallback) => AtRule;
 
-export declare function createModifiedUtilityInstances(baseInstance: Utility, availableModifiers: ModifierFactory[], root: Root): Utility[];
-
 export declare function createModifierFunction(_parent: Container, root: Root): <Key extends string>(key: Key | Key[], factory: ModifierFactory["factory"]) => ModifierFactory;
 
-export declare function createRecipeFunction(_parent: Container, root: Root): <Name extends string, Variants extends Record<string, Record<string, VariantDeclarationsBlock>>>(name: Name, defaults: Recipe<Name, Variants>["defaults"], variants: Recipe<Name, Variants>["variants"], options?: {
-    defaultVariants?: Recipe<Name, Variants>["defaultVariants"];
-    compoundVariants?: Recipe<Name, Variants>["compoundVariants"];
-}) => Recipe<Name, Variants>;
+/**
+ * Creates a recipe function to define design system recipes with variants.
+ *
+ * @example ```ts
+ * recipe({
+ *     name: "button",
+ *     base: {
+ *         borderWidth: ref(borderWidth), // Token reference => Variable<'border-width'> => Auto-generate _border-width
+ *         borderStyle: ref(borderStyle), // Token reference => Variable<'border-style'> => Auto-generate _border-style
+ *  	   boxShadow: ref(boxShadowMd), // Token reference => Variable<'box-shadow.md'> => Auto-generate _box-shadow:md
+ *         'hover:focus': { // Applying hover and focus modifiers
+ *             boxShadow: ref(boxShadowSm), // Token reference => Variable<'box-shadow.sm'> => Auto-generate _hover:box-shadow:sm
+ *         }
+ *     },
+ *     variants: {
+ *         color: {
+ *             primary: {
+ *                 background: ref(colorPrimary), // Token reference => Variable<'color.primary'> => Auto-generate _background:primary
+ *                 color: ref(colorWhite), // Token reference => Variable<'color.white'> => Auto-generate _color:white
+ *                 borderColor: ref(colorPrimaryShade50), // Token reference => Variable<'color.primary-shade-50'> => Auto-generate _border-color:primary-shade-50,
+ *             },
+ *             secondary: {
+ *                 background: "@color.secondary", // Token path => Variable<'color.secondary'> => Auto-generate _background:secondary
+ *                 color: "@color.white", // Token path => Variable<'color.white'> => Auto-generate _color:white
+ *                 borderColor: "@color.secondary-shade-50", // Token path => Variable<'color.secondary-shade-50'> => Auto-generate _border-color:secondary
+ *             },
+ * 			   disabled: {
+ * 				   false: {},
+ * 				   true: {
+ * 					   opacity: "@opacity.50", // Token path => Variable<'opacity.50'> => Auto-generate _opacity:50
+ * 					   cursor: "not-allowed", // Arbitrary value => Auto-generate _cursor:[not-allowed]
+ * 				   }
+ *             }
+ *         },
+ *         size: {
+ *             sm: {
+ *                 padding: "@spacing.sm", // Token path => Variable<'spacing.sm'> => Auto-generate _padding:sm
+ *                 fontSize: "@font-size.sm", // Token path => Variable<'font-size.sm'> => Auto-generate _font-size:sm
+ *             },
+ *             md: {
+ *                 padding: "1rem", // Arbitrary value => Auto-generate _padding:[1rem]
+ *                 fontSize: "1rem", // Arbitrary value => Auto-generate _font-size:[1rem]
+ *             },
+ *             lg: {
+ *                 padding: "@spacing.lg", // Token path => Variable<'spacing.lg'> => Auto-generate _padding:lg
+ *                 fontSize: "1.25rem", // Arbitrary value => Auto-generate _font-size:[1.25rem]
+ *             },
+ *         },
+ *     },
+ *     defaultVariants: {
+ * 		   color: "primary",
+ * 	       size: "md",
+ *     },
+ *     compoundVariants: [
+ *         {
+ *             match: {
+ *                 color: "primary",
+ *                 disabled: false
+ *             },
+ *             css: {
+ * 				   hover: {
+ * 					   background: "@color.primary-shade-50", // Token path => Variable<'color.primary-shade-50'> => Auto-generate _hover:background:primary-shade-50
+ * 				   }
+ *             },
+ *         },
+ *         {
+ *             match: {
+ *                 color: "secondary",
+ *                 disabled: false
+ *             },
+ *             css: {
+ * 				   hover: {
+ * 					   background: ref(colorSecondaryShade50), // Token reference => Variable<'color.secondary-shade-50'> => Auto-generate _hover:background:secondary-shade-50
+ * 				   }
+ *             },
+ *         },
+ *     ],
+ *     _runtime: {
+ * 	       base: {
+ * 				borderWidth: 'default',
+ *         		borderStyle: 'default',
+ *  	   		boxShadow: 'md',
+ *         		'hover:focus': {
+ *             		boxShadow: 'sm',
+ *         		}
+ *         },
+ * 	   	   variants: {
+ * 			   color: {
+ * 				   primary: {
+ * 					   background: "primary",
+ * 					   color: "white",
+ * 					   borderColor: "primary-shade-50",
+ * 				   },
+ * 				   secondary: {
+ * 					   background: "secondary",
+ * 					   color: "white",
+ * 					   borderColor: "secondary-shade-50",
+ * 				   }
+ * 			   },
+ * 			   disabled: {
+ * 				   	false: {},
+ * 				   	true: {
+ * 					   	opacity: "50",
+ * 					   	cursor: "[not-allowed]",
+ * 				   	}
+ *            },
+ *            size: {
+ *             		sm: {
+ *                 		padding: "sm",
+ *                 		fontSize: "sm",
+ *             		},
+ *             		md: {
+ *                 		padding: "[1rem]",
+ *                 		fontSize: "[1rem]",
+ *             		},
+ *             		lg: {
+ *                 		padding: "lg",
+ *                 		fontSize: "[1.25rem]",
+ *             		},
+ *         		},
+ *          },
+ *     		defaultVariants: {
+ * 		   		color: "primary",
+ * 	       		size: "md",
+ *     		},
+ *     		compoundVariants: [
+ *         		{
+ *             		match: {
+ *                 		color: "primary",
+ *                 		disabled: false
+ *             		},
+ *             		css: {
+ * 				   		hover: {
+ * 					   		background: "primary-shade-50",
+ * 				   		}
+ *             		},
+ *         		},
+ *         		{
+ *             		match: {
+ *                 		color: "secondary",
+ *                 		disabled: false
+ *             		},
+ *             		css: {
+ * 				   		hover: {
+ * 					   		background: 'secondary-shade-50',
+ * 				   		}
+ *             		},
+ *         		},
+ *     		],
+ *     }
+ * });
+ * ```
+ */
+export declare function createRecipeFunction(_parent: Container, root: Root): <Name extends string, Variants extends VariantsBase>(options: Omit<Recipe<Name, Variants>, "type">) => Recipe<Name, Variants>;
 
 export declare function createRefFunction(_parent: Container, _root: Root): <Name extends string>(variable: Variable<Name> | Name, fallback?: string) => Reference<Name>;
 
@@ -72,7 +220,9 @@ export declare function createSelectorFunction(parent: Container, root: Root): (
 
 export declare function createThemeFunction(_parent: Container, root: Root): (name: string, callback: DeclarationsCallback) => Theme;
 
-export declare function createUtilityFunction(parent: Container, root: Root): <Name extends string>(name: Name, factory: UtilityCallbackFn) => UtilityCreatorFn;
+export declare function createUtilityFunction(parent: Container, root: Root): <Name extends string>(name: Name, factory: UtilityCallbackFn, options?: {
+    autogenerate?: UtilityAutogenerateFn;
+}) => UtilityCreatorFn;
 
 export declare function createVariableFunction(parent: Container, _root: Root): <Name extends string>(nameOrInstance: Name | Variable<Name>, value: TokenValue, options?: {
     default: boolean;
@@ -115,6 +265,16 @@ export declare const deepClone: CloneFunction<any>;
  */
 export declare function generateRandomId(prefix?: string, length?: number): string;
 
+/**
+ * Generates the runtime object for a recipe.
+ * This object contains resolved runtime keys for efficient class name lookups.
+ *
+ * @param recipe - The recipe to generate runtime for
+ * @param root - The root object containing utility factories
+ * @returns The runtime object
+ */
+export declare function generateRecipeRuntime<Name extends string, Variants extends VariantsBase>(recipe: Recipe<Name, Variants>, root: Root): RecipeRuntime<Variants>;
+
 export declare function getModifier(root: Root, name: string): ModifierFactory;
 
 export declare function getUtility(root: Root, name: string): UtilityFactory;
@@ -133,6 +293,8 @@ export declare function isObject(value: unknown): value is object;
 
 export declare function isPrimitiveTokenValue(value: unknown): value is PrimitiveTokenValue;
 
+export declare function isRecipe(value: unknown): value is Recipe;
+
 export declare function isRef<Name extends string = string>(value: unknown): value is Reference<Name>;
 
 export declare function isRoot(value: unknown): value is Root;
@@ -146,6 +308,8 @@ export declare function isTheme(value: unknown): value is Theme;
  */
 export declare function isToken<T>(value: unknown, type: TokenType): value is T;
 
+export declare function isTokenEqual(a: TokenValue, b: TokenValue): boolean;
+
 export declare function isTokenValue(value: unknown): value is TokenValue;
 
 export declare function isUtility<Name extends string = string>(value: unknown): value is Utility<Name>;
@@ -162,6 +326,8 @@ export declare function mergeVariablesArray(a: Variable[], b: Variable[]): Varia
 
 export declare type ModifierCallbackFn = DeclarationsCallback<DeclarationsCallbackContext & Pick<Utility, "declarations" | "variables" | "children">>;
 
+export declare type ModifierDeclarationsBlock = Record<string, TokenValue>;
+
 export declare type ModifierFactory = {
     type: "modifier";
     key: string[];
@@ -172,18 +338,75 @@ export declare function parseDeclarationsBlock(declarations: DeclarationsBlock,
 
 export declare type PrimitiveTokenValue = number | string | boolean | null | undefined;
 
-export declare type Recipe<Name extends string = string, Variants extends Record<string, Record<string, VariantDeclarationsBlock>> = Record<string, Record<string, VariantDeclarationsBlock>>> = {
+/**
+ * Processes a recipe and creates utilities for all style declarations.
+ *
+ * This function iterates through all style fields in a recipe:
+ * 1. `base` - Root level field key-value pairs
+ * 2. `variants.*.*` - Each variant group's options containing field key-value pairs
+ * 3. `compoundVariants.*.css` - Each compound variant's css declarations
+ *
+ * For efficiency, it:
+ * - Collects all values needed for each utility key across the entire recipe
+ * - Retrieves each utility factory only once
+ * - Creates all utility instances in a single call per utility
+ *
+ * @param recipe - The recipe to process
+ * @param root - The root object containing utility factories
+ *
+ * @example
+ * ```ts
+ * const buttonRecipe = recipe({
+ *   name: "button",
+ *   base: { borderWidth: "thin" },
+ *   variants: {
+ *     size: {
+ *       sm: { padding: "0.5rem" },
+ *       lg: { padding: "1rem" },
+ *     },
+ *   },
+ * });
+ *
+ * processRecipeUtilities(buttonRecipe, root);
+ * // Creates:
+ * // - borderWidth utility with value "thin"
+ * // - padding utility with values ["0.5rem", "1rem"]
+ * ```
+ */
+export declare function processRecipeUtilities(recipe: Recipe, root: Root): void;
+
+export declare type Recipe<Name extends string = string, Variants extends VariantsBase = VariantsBase> = {
     type: "recipe";
     name: Name;
-    defaults: VariantDeclarationsBlock;
-    variants: Variants;
+    base?: VariantDeclarationsBlock;
+    variants?: Variants;
     defaultVariants?: {
         [K in keyof Variants]?: keyof Variants[K] & string;
     };
     compoundVariants?: Array<{
+        match: {
+            [K in keyof Variants]?: keyof Variants[K] & string;
+        };
+        css: VariantDeclarationsBlock;
+    }>;
+    _runtime?: RecipeRuntime<Variants>;
+};
+
+export declare type RecipeRuntime<Variants extends VariantsBase = VariantsBase> = {
+    base?: RuntimeVariantDeclarationsBlock;
+    variants?: {
+        [K in keyof Variants]?: {
+            [O in keyof Variants[K]]?: RuntimeVariantDeclarationsBlock;
+        };
+    };
+    defaultVariants?: {
         [K in keyof Variants]?: keyof Variants[K] & string;
-    } & {
-        declarations: VariantDeclarationsBlock;
+    };
+    compoundVariants?: Array<{
+        match: {
+            [K in keyof Variants]?: keyof Variants[K] & string;
+        };
+        css?: RuntimeVariantDeclarationsBlock;
     }>;
 };
 
@@ -212,6 +435,12 @@ export declare type Root = {
     themes: Theme[];
 };
 
+export declare type RuntimeModifierDeclarationsBlock = Record<string, PrimitiveTokenValue>;
+
+export declare type RuntimeVariantDeclarationsBlock = Record<string, RuntimeVariantDeclarationsValue>;
+
+export declare type RuntimeVariantDeclarationsValue = PrimitiveTokenValue | RuntimeModifierDeclarationsBlock;
+
 export declare type Selector = {
     type: "selector";
     query: string;
@@ -247,7 +476,7 @@ export declare type StyleframeOptions = {
     utilities?: {
         selector?: UtilitySelectorFn;
     };
-    theme?: {
+    themes?: {
         selector?: ThemeSelectorFn;
     };
 };
@@ -268,6 +497,8 @@ export declare type TokenType = Variable["type"] | Reference["type"] | Selector[
 
 export declare type TokenValue = PrimitiveTokenValue | Reference | CSS_2 | Array<PrimitiveTokenValue | Reference | CSS_2>;
 
+export declare function transformUtilityKey(replacer?: (key: string) => string): (value: TokenValue) => Record<string, TokenValue>;
+
 export declare type Utility<Name extends string = string> = {
     type: "utility";
     name: Name;
@@ -278,16 +509,25 @@ export declare type Utility<Name extends string = string> = {
     modifiers: string[];
 };
 
+export declare type UtilityAutogenerateFn = (value: TokenValue) => Record<string, TokenValue>;
+
 export declare type UtilityCallbackFn = DeclarationsCallback<DeclarationsCallbackContext & {
     value: TokenValue;
 }>;
 
-export declare type UtilityCreatorFn = (values: Record<string, TokenValue>, modifiers?: ModifierFactory[]) => void;
+export declare type UtilityCreatorFn = (values: Record<string, TokenValue> | TokenValue[], modifiers?: ModifierFactory[]) => void;
 
 export declare type UtilityFactory<Name extends string = string> = {
     type: "utility";
     name: Name;
     factory: UtilityCallbackFn;
+    values: Array<{
+        key: string;
+        value: TokenValue;
+        modifiers: string[];
+    }>;
+    autogenerate: UtilityAutogenerateFn;
+    create: UtilityCreatorFn;
 };
 
 export declare type UtilitySelectorFn = (options: {
@@ -306,6 +546,10 @@ export declare type VariableNameFn = (options: {
     name: string;
 }) => string;
 
-export declare type VariantDeclarationsBlock = Record<string, string | true>;
+export declare type VariantDeclarationsBlock = Record<string, VariantDeclarationsValue>;
+
+export declare type VariantDeclarationsValue = TokenValue | ModifierDeclarationsBlock;
+
+export declare type VariantsBase = Record<string, Record<string, VariantDeclarationsBlock>>;
 
 export { }