@styleframe/core 3.0.0 → 3.1.0

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # @styleframe/core
 
+## 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
+
+- [#120](https://github.com/styleframe-dev/styleframe/pull/120) [`fa48802`](https://github.com/styleframe-dev/styleframe/commit/fa488027d32956e20fa26dc92ee1a3b3583671ad) Thanks [@alexgrozav](https://github.com/alexgrozav)! - Add hash-based utility class names for arbitrary CSS values containing whitespace. Values like `transition: 'all 0.3s ease'` now produce valid CSS class names using a deterministic hash (e.g., `_transition:2f7a3b1`) instead of invalid bracket notation with spaces.
+
 ## 3.0.0
 
 ### Major 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.
  *
@@ -38,6 +46,8 @@ ConstructorHandler<T>
 ];
 
 export declare type Container = {
+    id: string;
+    parentId?: string;
     children: ContainerChild[];
     variables: Variable[];
     declarations: DeclarationsBlock;
@@ -45,9 +55,11 @@ export declare type Container = {
 
 export declare type ContainerChild = Variable | Selector | AtRule | Utility;
 
+export declare type ContainerInput = Pick<Container, "declarations" | "variables" | "children">;
+
 export declare function createAtRuleFunction(parent: Container, root: Root): (identifier: string, rule: string, declarationsOrCallback?: DeclarationsBlock | DeclarationsCallback) => AtRule;
 
-export declare function createCssFunction(_parent: Container, _root: Root): (strings: TemplateStringsArray, ...interpolations: TokenValue[]) => CSS_2;
+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;
 
@@ -57,6 +69,14 @@ export declare function createMediaFunction(parent: Container, root: Root): (que
 
 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 +232,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>;
 
@@ -257,6 +277,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
  *
@@ -282,12 +310,25 @@ export declare function getUtility(root: Root, name: string): UtilityFactory;
 
 export declare function getVariable(root: Container, name: string): Variable;
 
+/**
+ * Generates a deterministic, CSS-safe hash string from an arbitrary value.
+ * Uses DJB2 algorithm for fast, low-collision hashing.
+ *
+ * @param value - The string value to hash
+ * @returns A lowercase hex string of 7 characters (e.g., "a1b2c3d")
+ */
+export declare function hashValue(value: string): string;
+
 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;
@@ -337,7 +378,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;
 
@@ -378,6 +421,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;
@@ -420,6 +465,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 {
@@ -430,6 +477,8 @@ declare interface RfdcOptions {
 
 export declare type Root = {
     type: "root";
+    id: string;
+    parentId?: string;
     declarations: DeclarationsBlock;
     utilities: UtilityFactory[];
     modifiers: ModifierFactory[];
@@ -437,6 +486,7 @@ export declare type Root = {
     variables: Variable[];
     children: ContainerChild[];
     themes: Theme[];
+    _registry: Map<string, Container | Root | Theme>;
 };
 
 export declare type RuntimeModifierDeclarationsBlock = Record<string, PrimitiveTokenValue>;
@@ -447,6 +497,8 @@ export declare type RuntimeVariantDeclarationsValue = PrimitiveTokenValue | Runt
 
 export declare type Selector = {
     type: "selector";
+    id: string;
+    parentId?: string;
     query: string;
     declarations: DeclarationsBlock;
     variables: Variable[];
@@ -488,6 +540,8 @@ export declare type StyleframeOptions = {
 
 export declare type Theme = {
     type: "theme";
+    id: string;
+    parentId?: string;
     name: string;
     declarations: DeclarationsBlock;
     variables: Variable[];
@@ -513,6 +567,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;
@@ -543,14 +599,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;
 };