@styleframe/core 3.0.1 → 3.2.0

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # @styleframe/core
 
+## 3.2.0
+
+### Minor Changes
+
+- [#155](https://github.com/styleframe-dev/styleframe/pull/155) [`cc4f170`](https://github.com/styleframe-dev/styleframe/commit/cc4f170c56ad2e246b94ab4d64b7f6c3097c7223) Thanks [@alexgrozav](https://github.com/alexgrozav)! - Refactor recipes, improve modifier at-rule support, and forward variables through modifier factories
+  - Refactor recipes and utilities with improved color theming composables
+  - Add at-rule support for modifiers (e.g. media preference modifiers)
+  - Forward variables and children through all modifier factory functions
+  - Restructure docs for components, utilities, and modifiers into composable subdirectories
+  - Add Button composable recipe documentation
+  - Update plugin scanner for improved recipe handling
+
+## 3.1.0
+
+### Minor Changes
+
+- [#129](https://github.com/styleframe-dev/styleframe/pull/129) [`2610041`](https://github.com/styleframe-dev/styleframe/commit/2610041beb03a8afc8de17af8857b9931f3359b0) Thanks [@alexgrozav](https://github.com/alexgrozav)! - Add custom utility syntax support and separate class name generation from CSS escaping
+  - Extract `defaultUtilitySelectorFn` to `@styleframe/core` returning raw class names; add `classNameToCssSelector` for consistent CSS escaping
+  - Add `ScannerUtilitiesConfig` with pluggable `pattern`, `parse`, and `selector` functions for custom utility naming conventions
+  - Thread custom utilities config through extractor, matcher, scanner, and plugin layers
+
+- [#133](https://github.com/styleframe-dev/styleframe/pull/133) [`ce62d31`](https://github.com/styleframe-dev/styleframe/commit/ce62d318275deed277d828fdd8d2500c1a9d767f) Thanks [@alexgrozav](https://github.com/alexgrozav)! - Add unique id and parent-child traversal to token types, validate @ references, and resolve utility sibling keys
+  - Add unique `id` field to Root, Selector, AtRule, Theme, Utility, Modifier, and Variable token types for stable identity tracking
+  - Add `parentId` to track parent-child relationships across the token tree
+  - Add `root._registry` for efficient id-based lookups and tree traversal
+  - Validate `@`-prefixed string references against root-level variables in `parseDeclarationsBlock`, throwing descriptive errors for undefined variables
+  - Add null/undefined guard to `ref()` with clear error messages
+  - Support `@`-prefixed values in utility entries that resolve to sibling keys (e.g., `{ default: "@solid", solid: "solid" }`)
+
+### Patch Changes
+
+- [#141](https://github.com/styleframe-dev/styleframe/pull/141) [`295f04e`](https://github.com/styleframe-dev/styleframe/commit/295f04e6fdd011df6437986cc179e17efd8cd1be) Thanks [@alexgrozav](https://github.com/alexgrozav)! - Add `@variablename` notation support in `css` template literals
+  - `@variablename` strings in static parts of `css` template literals are automatically converted to variable references: `` css`1px solid @color.primary` `` resolves `@color.primary` to `ref("color.primary")`
+  - Supports dotted names (e.g., `@color.primary.500`) and multiple references per segment (e.g., `` css`@spacing.x @spacing.y` ``)
+
+- [#128](https://github.com/styleframe-dev/styleframe/pull/128) [`71009c2`](https://github.com/styleframe-dev/styleframe/commit/71009c2c0a07a0bfd240e70e61020c8b7e923edb) Thanks [@alexgrozav](https://github.com/alexgrozav)! - Add auto-resolve for variables and at-rules in `css` template literal interpolations
+  - Variables interpolated directly in `css` are automatically converted to references: `` css`${variable}` `` is equivalent to `` css`${ref(variable)}` ``
+  - AtRule and keyframes instances interpolated in `css` resolve to their rule name: `` css`${keyframeInstance}` `` is equivalent to `` css`${keyframeInstance.rule}` ``
+
+- [#140](https://github.com/styleframe-dev/styleframe/pull/140) [`7a61df0`](https://github.com/styleframe-dev/styleframe/commit/7a61df083bc534caa9271a1ef4535f7be979d7c2) Thanks [@alexgrozav](https://github.com/alexgrozav)! - Add `@variablename` reference support in `variable()` values, `ref()` fallbacks, and `selector()` declaration values
+  - `variable('name', '1px solid @color.primary')` resolves embedded `@` references to a CSS object with mixed text and reference parts
+  - `ref('name', '@fallbackvar')` resolves `@`-prefixed fallback values to nested references
+  - `selector({ border: "1px solid @color.primary" })` resolves embedded `@` references in declaration values
+  - Extract shared `resolvePropertyValue()` utility for consistent `@` reference resolution across all contexts
+
 ## 3.0.1
 
 ### Patch Changes

package/dist/styleframe.d.ts

@@ -4,6 +4,8 @@ export declare function applyModifiers<InstanceType extends Container>(baseInsta
 
 export declare type AtRule = {
     type: "at-rule";
+    id: string;
+    parentId?: string;
     identifier: string;
     rule: string;
     declarations: DeclarationsBlock;
@@ -18,6 +20,12 @@ export declare type CapitalizeFirst<T extends string> = T extends `${infer First
  */
 export declare function capitalizeFirst(str: string): string;
 
+/**
+ * Convert a raw class name to a CSS selector by adding a `.` prefix
+ * and escaping special characters.
+ */
+export declare function classNameToCssSelector(className: string): string;
+
 /**
  * Deep clone a value.
  *
@@ -28,8 +36,6 @@ export declare function capitalizeFirst(str: string): string;
  */
 declare type CloneFunction<T = any> = (obj: T) => T;
 
-export declare function combineKeys(groups: string[][]): string[][];
-
 declare type ConstructorHandler<T = any> = (obj: T, fn: CloneFunction) => T;
 
 declare type ConstructorHandlerTuple<T = any> = [
@@ -38,6 +44,8 @@ ConstructorHandler<T>
 ];
 
 export declare type Container = {
+    id: string;
+    parentId?: string;
     children: ContainerChild[];
     variables: Variable[];
     declarations: DeclarationsBlock;
@@ -45,18 +53,28 @@ export declare type Container = {
 
 export declare type ContainerChild = Variable | Selector | AtRule | Utility;
 
-export declare function createAtRuleFunction(parent: Container, root: Root): (identifier: string, rule: string, declarationsOrCallback?: DeclarationsBlock | DeclarationsCallback) => AtRule;
+export declare type ContainerInput = Pick<Container, "declarations" | "variables" | "children">;
 
-export declare function createCssFunction(_parent: Container, _root: Root): (strings: TemplateStringsArray, ...interpolations: TokenValue[]) => CSS_2;
+export declare function createAtRuleFunction(parent: Container, root: Root): (identifier: string, rule: string, declarationsOrCallback?: DeclarationsBlock | ContainerInput | DeclarationsCallback) => AtRule;
+
+export declare function createCssFunction(_parent: Container, _root: Root): (strings: TemplateStringsArray, ...interpolations: (TokenValue | Variable | AtRule)[]) => CSS_2;
 
 export declare function createDeclarationsCallbackContext(parent: Container, root: Root): DeclarationsCallbackContext;
 
 export declare function createKeyframesFunction(parent: Container, root: Root): (name: string, declarations: Record<string, DeclarationsBlock>) => AtRule;
 
-export declare function createMediaFunction(parent: Container, root: Root): (query: string, declarationsOrCallback?: DeclarationsBlock | DeclarationsCallback) => AtRule;
+export declare function createMediaFunction(parent: Container, root: Root): (query: string, declarationsOrCallback?: DeclarationsBlock | ContainerInput | DeclarationsCallback) => AtRule;
 
 export declare function createModifierFunction(_parent: Container, root: Root): <Key extends string>(key: Key | Key[], factory: ModifierFactory["factory"]) => ModifierFactory;
 
+/**
+ * Creates a resolver that converts @-prefixed variable references in string values.
+ * - Exact match "@name" → Reference object
+ * - Embedded "1px solid @name" → CSS object with mixed parts
+ * - Non-string or no @ → returns value unchanged
+ */
+export declare function createPropertyValueResolver(parent: Container, root: Root): (value: TokenValue) => TokenValue;
+
 /**
  * Creates a recipe function to define design system recipes with variants.
  *
@@ -212,20 +230,20 @@ export declare function createModifierFunction(_parent: Container, root: Root):
  */
 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>;
+export declare function createRefFunction(parent: Container, root: Root): <Name extends string>(variable: Variable<Name> | Name, fallback?: string) => Reference<Name>;
 
 export declare function createRoot(): Root;
 
-export declare function createSelectorFunction(parent: Container, root: Root): (query: string, declarationsOrCallback: DeclarationsBlock | Container | DeclarationsCallback) => Selector;
+export declare function createSelectorFunction(parent: Container, root: Root): (query: string, declarationsOrCallback: DeclarationsBlock | ContainerInput | DeclarationsCallback) => Selector;
 
-export declare function createThemeFunction(_parent: Container, root: Root): (name: string, callback: DeclarationsCallback) => Theme;
+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, options?: {
     autogenerate?: UtilityAutogenerateFn;
     namespace?: string | string[];
 }) => UtilityCreatorFn;
 
-export declare function createVariableFunction(parent: Container, _root: Root): <Name extends string>(nameOrInstance: Name | Variable<Name>, value: TokenValue, options?: {
+export declare function createVariableFunction(parent: Container, root: Root): <Name extends string>(nameOrInstance: Name | Variable<Name>, value: TokenValue, options?: {
     default: boolean;
 }) => Variable<Name>;
 
@@ -240,7 +258,7 @@ declare type CSSValueWithReference<T> = T extends string | number | undefined ?
 export declare type DeclarationsBlock = {
     [K in keyof Properties]: CSSValueWithReference<Properties[K]>;
 } & {
-    [key: string]: CSSValueWithReference<Properties[keyof Properties]> | DeclarationsBlock;
+    [key: string]: CSSValueWithReference<Properties[keyof Properties]> | DeclarationsBlock | ContainerInput;
 };
 
 export declare type DeclarationsCallback<Context extends DeclarationsCallbackContext = DeclarationsCallbackContext> = (context: Context) => DeclarationsBlock | void;
@@ -257,6 +275,14 @@ export declare type DeclarationsCallbackContext = {
 
 export declare const deepClone: CloneFunction<any>;
 
+export declare const defaultUtilitySelectorFn: UtilitySelectorFn;
+
+/**
+ * Checks whether a variable with the given name exists in the scope chain,
+ * walking from the given scope up through ancestors via parentId.
+ */
+export declare function findVariableInScope(name: string, scope: Container, root: Root): boolean;
+
 /**
  * Generates a random ID string
  *
@@ -295,8 +321,12 @@ export declare function isAtRule(value: unknown): value is AtRule;
 
 export declare function isContainer(value: unknown): value is Container;
 
+export declare function isContainerInput(value: unknown): value is ContainerInput;
+
 export declare function isCSS(value: unknown): value is CSS_2;
 
+export declare function isKeyReferenceValue(value: unknown): value is `@${string}`;
+
 export declare function isModifier(value: unknown): value is ModifierFactory;
 
 export declare function isObject(value: unknown): value is object;
@@ -346,7 +376,9 @@ export declare type ModifierFactory = {
     factory: ModifierCallbackFn;
 };
 
-export declare function parseDeclarationsBlock(declarations: DeclarationsBlock, context: DeclarationsCallbackContext): DeclarationsBlock;
+export declare function parseAtReferences(str: string): TokenValue[];
+
+export declare function parseDeclarationsBlock(declarations: DeclarationsBlock, context: DeclarationsCallbackContext, parent: Container, root: Root): DeclarationsBlock;
 
 export declare type PrimitiveTokenValue = number | string | boolean | null | undefined;
 
@@ -387,6 +419,8 @@ export declare type PrimitiveTokenValue = number | string | boolean | null | und
  */
 export declare function processRecipeUtilities(recipe: Recipe, root: Root): void;
 
+export declare function rebuildRegistry(root: Root): void;
+
 export declare type Recipe<Name extends string = string, Variants extends VariantsBase = VariantsBase> = {
     type: "recipe";
     name: Name;
@@ -429,6 +463,8 @@ export declare type Reference<Name extends string = string> = {
     fallback?: TokenValue;
 };
 
+export declare type RefFunction = (variable: string, fallback?: string) => Reference;
+
 export declare function rfdc<T = any>(opts?: RfdcOptions): CloneFunction<T>;
 
 declare interface RfdcOptions {
@@ -439,6 +475,8 @@ declare interface RfdcOptions {
 
 export declare type Root = {
     type: "root";
+    id: string;
+    parentId?: string;
     declarations: DeclarationsBlock;
     utilities: UtilityFactory[];
     modifiers: ModifierFactory[];
@@ -446,6 +484,7 @@ export declare type Root = {
     variables: Variable[];
     children: ContainerChild[];
     themes: Theme[];
+    _registry: Map<string, Container | Root | Theme>;
 };
 
 export declare type RuntimeModifierDeclarationsBlock = Record<string, PrimitiveTokenValue>;
@@ -456,6 +495,8 @@ export declare type RuntimeVariantDeclarationsValue = PrimitiveTokenValue | Runt
 
 export declare type Selector = {
     type: "selector";
+    id: string;
+    parentId?: string;
     query: string;
     declarations: DeclarationsBlock;
     variables: Variable[];
@@ -497,6 +538,8 @@ export declare type StyleframeOptions = {
 
 export declare type Theme = {
     type: "theme";
+    id: string;
+    parentId?: string;
     name: string;
     declarations: DeclarationsBlock;
     variables: Variable[];
@@ -522,6 +565,8 @@ export declare interface TransformUtilityKeyOptions {
 
 export declare type Utility<Name extends string = string> = {
     type: "utility";
+    id: string;
+    parentId?: string;
     name: Name;
     value: string;
     declarations: DeclarationsBlock;
@@ -536,7 +581,7 @@ export declare type UtilityCallbackFn = DeclarationsCallback<DeclarationsCallbac
     value: TokenValue;
 }>;
 
-export declare type UtilityCreatorFn = (values: Record<string, TokenValue> | TokenValue[], modifiers?: ModifierFactory[]) => void;
+export declare type UtilityCreatorFn = (values: Record<string, TokenValue> | TokenValue[], modifiers?: (ModifierFactory | ModifierFactory[])[]) => void;
 
 export declare type UtilityFactory<Name extends string = string> = {
     type: "utility";
@@ -552,14 +597,25 @@ export declare type UtilityFactory<Name extends string = string> = {
     create: UtilityCreatorFn;
 };
 
-export declare type UtilitySelectorFn = (options: {
+export declare type UtilitySelectorFn = (options: UtilitySelectorOptions) => string;
+
+export declare interface UtilitySelectorOptions {
     name: string;
     value: string;
     modifiers: string[];
-}) => string;
+}
+
+/**
+ * Validates that a variable name exists in the scope chain.
+ * Walks from the given scope up through ancestors to root.
+ * Throws if the variable is not defined.
+ */
+export declare function validateReference(name: string, scope: Container, root: Root): void;
 
 export declare type Variable<Name extends string = string> = {
     type: "variable";
+    id: string;
+    parentId?: string;
     name: Name;
     value: TokenValue;
 };