@yahoo/uds-create-utils 1.1.1

package/dist/motion-utils/resolveMotionState.js

@@ -0,0 +1,33 @@
+//#region src/motion-utils/resolveMotionState.ts
+function isInterpolateMarker(value) {
+	return typeof value === "object" && value !== null && value.__type === "interpolate";
+}
+/**
+* Resolve a single `interpolate({ output, extrapolate })` marker against
+* an integer-ish `index`. Output is a discrete lookup by index for
+* `index < output.length`; beyond that, `extrapolate` chooses the
+* extension rule (clamp / linear-extend / identity).
+*/
+function resolveInterpolate(marker, index) {
+	const { output, extrapolate } = marker;
+	if (index < output.length) return output[index];
+	if (extrapolate === "clamp") return output[output.length - 1];
+	if (extrapolate === "identity") return index;
+	const last = output[output.length - 1];
+	return last + (last - (output[output.length - 2] ?? last)) * (index - (output.length - 1));
+}
+/**
+* Resolve every InterpolateMarker in a state keyframe object against
+* `index`, leaving non-marker values unchanged. Used by codegen-emitted
+* `__rms(...)` call sites — see
+* `packages/codegen/src/build/get-styles/motion-transform.ts` for the
+* call-site generation.
+*/
+function resolveMotionState(stateKeyframe, index) {
+	const resolved = {};
+	for (const [key, value] of Object.entries(stateKeyframe)) if (isInterpolateMarker(value)) resolved[key] = resolveInterpolate(value, index);
+	else resolved[key] = value;
+	return resolved;
+}
+//#endregion
+export { resolveInterpolate, resolveMotionState };

package/dist/object-utils/entries.d.ts

@@ -0,0 +1,4 @@
+//#region src/object-utils/entries.d.ts
+declare function entries<T>(item: T): [Extract<keyof T, string> extends never ? string : Extract<keyof T, string>, T[keyof T]][];
+//#endregion
+export { entries };

package/dist/object-utils/entries.js

@@ -0,0 +1,6 @@
+//#region src/object-utils/entries.ts
+function entries(item) {
+	return Object.entries(item);
+}
+//#endregion
+export { entries };

package/dist/object-utils/flattenObj.d.ts

@@ -0,0 +1,12 @@
+//#region src/object-utils/flattenObj.d.ts
+type Prev = [never, 0, 1, 2, 3, 4];
+type FlattenDepth<T, D extends Prev[number] = Prev[number], Sep extends string = '-', P extends string = ''> = [D] extends [0] ? Record<P, T> : T extends Record<string, unknown> ? { [K in keyof T & string]: FlattenDepth<T[K], Prev[D], Sep, P extends '' ? K : `${P}${Sep}${K}`> }[keyof T & string] : Record<P, T>;
+type Merge<U> = (U extends unknown ? (_x: U) => void : never) extends ((_x: infer I) => void) ? { [K in keyof I]: I[K] } : never;
+type Flattened<T, D extends Prev[number] = Prev[number], Sep extends string = '-', P extends string = ''> = Merge<FlattenDepth<T, D, Sep, P>>;
+declare function flattenObj<T, D extends Prev[number] = Prev[number], Sep extends string = '-', P extends string = ''>(obj: T, params?: {
+  prefix?: P;
+  separator?: Sep;
+  depth?: D;
+}): Flattened<T, D, Sep, P>;
+//#endregion
+export { flattenObj };

package/dist/object-utils/flattenObj.js

@@ -0,0 +1,21 @@
+//#region src/object-utils/flattenObj.ts
+function flattenObj(obj, params = {}) {
+	const MAX_DEPTH = 5;
+	const { prefix = "", separator = "-", depth = MAX_DEPTH } = params;
+	const runDepth = depth;
+	const result = {};
+	function recurse(current, currentKey, remainingDepth) {
+		if (remainingDepth <= 0 || typeof current !== "object" || current === null || Array.isArray(current)) {
+			result[currentKey] = current;
+			return;
+		}
+		for (const key of Object.keys(current)) {
+			const nextKey = currentKey ? `${currentKey}${separator}${key}` : key;
+			recurse(current[key], nextKey, remainingDepth - 1);
+		}
+	}
+	recurse(obj, prefix, runDepth);
+	return result;
+}
+//#endregion
+export { flattenObj };

package/dist/object-utils/fromEntries.d.ts

@@ -0,0 +1,4 @@
+//#region src/object-utils/fromEntries.d.ts
+declare function fromEntries<const T extends ReadonlyArray<readonly [PropertyKey, unknown]>>(entries: T): { [K in T[number] as K[0]]: K[1] };
+//#endregion
+export { fromEntries };

package/dist/object-utils/fromEntries.js

@@ -0,0 +1,6 @@
+//#region src/object-utils/fromEntries.ts
+function fromEntries(entries) {
+	return Object.fromEntries(entries);
+}
+//#endregion
+export { fromEntries };

package/dist/object-utils/keys.d.ts

@@ -0,0 +1,4 @@
+//#region src/object-utils/keys.d.ts
+declare function keys<T extends object>(obj: T): (keyof T)[];
+//#endregion
+export { keys };

package/dist/object-utils/keys.js

@@ -0,0 +1,6 @@
+//#region src/object-utils/keys.ts
+function keys(obj) {
+	return Object.keys(obj);
+}
+//#endregion
+export { keys };

package/dist/object-utils/mapKeys.d.ts

@@ -0,0 +1,5 @@
+//#region src/object-utils/mapKeys.d.ts
+type AnyObject = Record<string, unknown>;
+declare function mapKeys<T extends AnyObject, K extends (value: T[keyof T], key: keyof T, obj: T) => PropertyKey>(obj: T, callbackFn: K): { [key in ReturnType<K>]: T[keyof T] };
+//#endregion
+export { mapKeys };

package/dist/object-utils/mapKeys.js

@@ -0,0 +1,10 @@
+//#region src/object-utils/mapKeys.ts
+function mapKeys(obj, callbackFn) {
+	return Object.keys(obj).reduce((acc, key) => {
+		const newKey = callbackFn(obj[key], key, obj);
+		acc[newKey] = obj[key];
+		return acc;
+	}, {});
+}
+//#endregion
+export { mapKeys };

package/dist/object-utils/mapValues.d.ts

@@ -0,0 +1,5 @@
+//#region src/object-utils/mapValues.d.ts
+type AnyObject = Record<string, unknown>;
+declare function mapValues<T extends AnyObject, K extends (value: T[keyof T], key: Extract<keyof T, string>, i: number) => unknown>(obj: T, callbackFn: K): { [key in keyof T]: ReturnType<K> };
+//#endregion
+export { mapValues };

package/dist/object-utils/mapValues.js

@@ -0,0 +1,9 @@
+//#region src/object-utils/mapValues.ts
+function mapValues(obj, callbackFn) {
+	return Object.keys(obj).reduce((acc, key, i) => {
+		acc[key] = callbackFn(obj[key], key, i);
+		return acc;
+	}, {});
+}
+//#endregion
+export { mapValues };

package/dist/string-utils/arrayToUnion.d.ts

@@ -0,0 +1,4 @@
+//#region src/string-utils/arrayToUnion.d.ts
+declare function arrayToUnion<T extends string[]>(array: T): `'${T[number]}'`;
+//#endregion
+export { arrayToUnion };

package/dist/string-utils/arrayToUnion.js

@@ -0,0 +1,6 @@
+//#region src/string-utils/arrayToUnion.ts
+function arrayToUnion(array) {
+	return array.map((item) => `'${item}'`).join(" | ");
+}
+//#endregion
+export { arrayToUnion };

package/dist/string-utils/capitalize.d.ts

@@ -0,0 +1,4 @@
+//#region src/string-utils/capitalize.d.ts
+declare function capitalize(s: string): string;
+//#endregion
+export { capitalize };

package/dist/string-utils/capitalize.js

@@ -0,0 +1,6 @@
+//#region src/string-utils/capitalize.ts
+function capitalize(s) {
+	return s.charAt(0).toUpperCase() + s.slice(1);
+}
+//#endregion
+export { capitalize };

package/dist/string-utils/componentClassName.d.ts

@@ -0,0 +1,58 @@
+//#region src/string-utils/componentClassName.d.ts
+/**
+ * The four class-name accessors for a single component, with the config
+ * prefix + component name bound. The single source of truth for "what does
+ * this component's CSS class look like" — the resolved `Component` exposes
+ * one (`component.derived.classNames`) and the codegen emitters read it
+ * instead of re-deriving names, so the emitted CSS selectors and the
+ * generated TSX `className` strings can never drift.
+ */
+interface ComponentClassNames {
+  layer(layer: string): string;
+  variant(layer: string, axis: string, value: string): string;
+  defaultProp(layer: string, prop: string): string;
+  compound(layer: string, conditions: Record<string, string>): string;
+}
+/**
+ * Build the {@link ComponentClassNames} accessor set for a component, binding
+ * `prefix` + `name` so callers supply only the per-class arguments. The prefix
+ * is applied here (once), wrapping the unprefixed shape the helpers below
+ * define — so the helpers stay the single definition of the class-name *shape*
+ * and this factory is the single definition of *namespacing*.
+ */
+declare function componentClassNames(prefix: string, name: string): ComponentClassNames;
+/**
+ * Build the base class name for a component layer.
+ *
+ * @example componentLayerClass('Switch', 'root') // "switch-root"
+ */
+declare function componentLayerClass(componentName: string, layer: string): string;
+/**
+ * Build the variant class name for a component layer.
+ *
+ * @example componentVariantClass('Switch', 'root', 'size', 'lg') // "switch-root--size-lg"
+ */
+declare function componentVariantClass(componentName: string, layer: string, axis: string, value: string): string;
+/**
+ * Build the class name carrying a component's own `defaultProps` styling for a
+ * prop, on a layer. Emitted in `@layer base` (so it loses to an embedding
+ * component's anatomy in `@layer components`) and applied by the generated impl
+ * only when the prop is absent — so an embedded sub-component's default
+ * `variant`/`color` no longer overrides the parent's anatomy, while an explicit
+ * prop still wins via its atomic/variant class in a later layer.
+ *
+ * @example componentDefaultClass('Text', 'root', 'color') // "text-root-color-default"
+ */
+declare function componentDefaultClass(componentName: string, layer: string, prop: string): string;
+/**
+ * Build the compound-variant class name for a component layer.
+ *
+ * Conditions are sorted by key to guarantee a stable, deterministic name.
+ *
+ * @example
+ * componentCompoundClass('Switch', 'root', { size: 'lg', color: 'primary' })
+ * // "switch-root--color-primary_size-lg"
+ */
+declare function componentCompoundClass(componentName: string, layer: string, conditions: Record<string, string>): string;
+//#endregion
+export { ComponentClassNames, componentClassNames, componentCompoundClass, componentDefaultClass, componentLayerClass, componentVariantClass };

package/dist/string-utils/componentClassName.js

@@ -0,0 +1,70 @@
+import { kebabCase } from "./kebabCase.js";
+//#region src/string-utils/componentClassName.ts
+/**
+* Prepend the configured prefix to a component class-name body, mirroring how
+* CSS variables are namespaced (`--<prefix>-…`). An empty prefix yields the
+* bare, unprefixed form — parallel to the CSS-variable path's empty-prefix
+* handling — so `prefix: ''` opts every component class out of namespacing.
+*/
+function withPrefix(prefix, body) {
+	return prefix ? `${prefix}-${body}` : body;
+}
+/**
+* Build the {@link ComponentClassNames} accessor set for a component, binding
+* `prefix` + `name` so callers supply only the per-class arguments. The prefix
+* is applied here (once), wrapping the unprefixed shape the helpers below
+* define — so the helpers stay the single definition of the class-name *shape*
+* and this factory is the single definition of *namespacing*.
+*/
+function componentClassNames(prefix, name) {
+	return {
+		layer: (layer) => withPrefix(prefix, componentLayerClass(name, layer)),
+		variant: (layer, axis, value) => withPrefix(prefix, componentVariantClass(name, layer, axis, value)),
+		defaultProp: (layer, prop) => withPrefix(prefix, componentDefaultClass(name, layer, prop)),
+		compound: (layer, conditions) => withPrefix(prefix, componentCompoundClass(name, layer, conditions))
+	};
+}
+/**
+* Build the base class name for a component layer.
+*
+* @example componentLayerClass('Switch', 'root') // "switch-root"
+*/
+function componentLayerClass(componentName, layer) {
+	return `${kebabCase(componentName)}-${layer}`;
+}
+/**
+* Build the variant class name for a component layer.
+*
+* @example componentVariantClass('Switch', 'root', 'size', 'lg') // "switch-root--size-lg"
+*/
+function componentVariantClass(componentName, layer, axis, value) {
+	return `${kebabCase(componentName)}-${layer}--${axis}-${value}`;
+}
+/**
+* Build the class name carrying a component's own `defaultProps` styling for a
+* prop, on a layer. Emitted in `@layer base` (so it loses to an embedding
+* component's anatomy in `@layer components`) and applied by the generated impl
+* only when the prop is absent — so an embedded sub-component's default
+* `variant`/`color` no longer overrides the parent's anatomy, while an explicit
+* prop still wins via its atomic/variant class in a later layer.
+*
+* @example componentDefaultClass('Text', 'root', 'color') // "text-root-color-default"
+*/
+function componentDefaultClass(componentName, layer, prop) {
+	return `${kebabCase(componentName)}-${layer}-${prop}-default`;
+}
+/**
+* Build the compound-variant class name for a component layer.
+*
+* Conditions are sorted by key to guarantee a stable, deterministic name.
+*
+* @example
+* componentCompoundClass('Switch', 'root', { size: 'lg', color: 'primary' })
+* // "switch-root--color-primary_size-lg"
+*/
+function componentCompoundClass(componentName, layer, conditions) {
+	const suffix = Object.entries(conditions).sort(([a], [b]) => a.localeCompare(b)).map(([a, v]) => `${a}-${v}`).join("_");
+	return `${kebabCase(componentName)}-${layer}--${suffix}`;
+}
+//#endregion
+export { componentClassNames, componentCompoundClass, componentDefaultClass, componentLayerClass, componentVariantClass };

package/dist/string-utils/createTemplate.d.ts

@@ -0,0 +1,16 @@
+//#region src/string-utils/createTemplate.d.ts
+type CreateTemplateParams = {
+  sort?: boolean;
+  sortMapKeys?: boolean;
+  sortObjectKeys?: boolean;
+  sortSetValues?: boolean;
+  sortArrayValues?: boolean;
+  formatAsTypes?: boolean;
+  formatAsInterfaces?: boolean;
+};
+declare function createTemplate(params?: CreateTemplateParams): (strings: TemplateStringsArray, ...expr: unknown[]) => string;
+declare const typeTemplate: (strings: TemplateStringsArray, ...expr: unknown[]) => string;
+declare const interfaceTemplate: (strings: TemplateStringsArray, ...expr: unknown[]) => string;
+declare const template: (strings: TemplateStringsArray, ...expr: unknown[]) => string;
+//#endregion
+export { createTemplate, interfaceTemplate, template, typeTemplate };

package/dist/string-utils/createTemplate.js

@@ -0,0 +1,142 @@
+import { entries } from "../object-utils/entries.js";
+import { arrayToUnion } from "./arrayToUnion.js";
+import { objectToInterface } from "./objectToInterface.js";
+//#region src/string-utils/createTemplate.ts
+function isPrimitiveArray(items) {
+	return items.every((val) => typeof val === "string" || typeof val === "number" || typeof val === "boolean");
+}
+function sortByAlphabet(prev, next) {
+	const prevValue = Array.isArray(prev) ? prev[0] : prev;
+	const nextValue = Array.isArray(next) ? next[0] : next;
+	/** @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator/Collator */
+	return prevValue.localeCompare(nextValue, void 0, {
+		numeric: true,
+		sensitivity: "base"
+	});
+}
+function objectToString(obj, indent = 2) {
+	return `{\n${entries(obj).map(([key, value]) => {
+		const space = " ".repeat(indent);
+		if (typeof value === "object" && value !== null && !Array.isArray(value)) return `${space}${key}: ${objectToString(value, indent + 2)}`;
+		if (Object.getOwnPropertyDescriptor(obj, key)?.get) return `${space}get ${key}() ${obj[key].toString()}`;
+		return `${space}${key}: ${JSON.stringify(value)}`;
+	}).join(",\n")}\n${" ".repeat(indent - 2)}}`;
+}
+function createTemplate(params) {
+	const { sort = false, sortMapKeys = sort, sortObjectKeys = sort, sortSetValues = sort, sortArrayValues = sort, formatAsTypes = false, formatAsInterfaces = false } = params ?? {
+		sort: false,
+		sortMapKeys: false,
+		sortObjectKeys: false,
+		sortSetValues: false,
+		sortArrayValues: false,
+		formatAsTypes: false,
+		formatAsInterfaces: false
+	};
+	function template(strings, ...expr) {
+		let str = "";
+		/**
+		* Tagged template function for formatting codegenerated typescript types.
+		* This util will automatically join array of items as a union.
+		*
+		* You will use similiar to how we use the `css` tagged template function
+		* from linaria.
+		*
+		* import { writePrettyFile } from './writePrettyFile';
+		* import { createTemplate } from 'uds/utils';
+		*
+		* const template = createTemplate({ formatAsTypes: true });
+		* const paletteNames = ['foreground', 'background'];
+		*
+		* const paletteNameContent = template`
+		*  type PaletteName = ${paletteNames};
+		* `
+		*
+		* writePrettyFile('packages/common/types/PaletteName', paletteNameContent);
+		*
+		* OUTPUT
+		*
+		* type PaletteName = 'foreground' | 'background';
+		*
+		*/
+		if (formatAsTypes) expr.forEach((item) => {
+			if (item && typeof item === "object") {
+				let stringResult;
+				if (item && Array.isArray(item)) stringResult = arrayToUnion(item);
+				if (item instanceof Set) stringResult = arrayToUnion(Array.from(item));
+				Object.defineProperty(item, "toString", { value() {
+					return stringResult;
+				} });
+			}
+		});
+		if (formatAsInterfaces) expr.forEach((item) => {
+			if (item && typeof item === "object") {
+				let stringResult;
+				if (item && typeof item === "object") stringResult = objectToInterface(item);
+				Object.defineProperty(item, "toString", { value() {
+					return stringResult;
+				} });
+			}
+		});
+		/**
+		* A template function to serialize objects, arrays, Sets, and Maps.
+		*
+		* Benefits:
+		* - Directly handle exports within the template.
+		* - Manage type consistency for better type safety.
+		* - Supports complex data structures like Map and Set.
+		* - Custom sorting for various collections.
+		*
+		* @example
+		* ```ts
+		* const template = createTemplate();
+		* const blueToken = {
+		*   hue: 'blue',
+		*   step: 50,
+		*   get name() {
+		*     return `${this.hue}-${this.step}`
+		*   }
+		* }
+		* const output = template`
+		*   export const blue = ${blueToken}
+		* `
+		*
+		* // output will contain:
+		* // "export const blue = { hue: 'blue', step: 50, name: 'hue-50' }"
+		* ```
+		*/
+		expr.forEach((item) => {
+			let result;
+			if (item && typeof item === "object") {
+				if (!Array.isArray(item) && Object.values(item).some((v) => typeof v === "object" && Object.getOwnPropertyDescriptor(v, "get")?.get)) result = objectToString(item);
+				else if (Array.isArray(item) && isPrimitiveArray(item) && sortArrayValues) result = item.sort();
+				else if (item instanceof Map) {
+					const itemMap = item;
+					let itemEntries = Array.from(itemMap.entries());
+					if (sortMapKeys) itemEntries = itemEntries.sort(sortByAlphabet);
+					result = Object.fromEntries(itemEntries);
+				} else if (item instanceof Set) {
+					const itemSet = item;
+					let itemValues = Array.from(itemSet.values());
+					if (sortSetValues) itemValues = itemValues.sort(sortByAlphabet);
+					result = itemValues;
+				} else if (!(item instanceof Map) && !(item instanceof Set)) if (sortObjectKeys) {
+					const sortedByKeys = entries(item).sort(sortByAlphabet);
+					result = Object.fromEntries(sortedByKeys);
+				} else result = item;
+				if (result && typeof result !== "string" && !Object.getOwnPropertyDescriptor(item, "toString")) Object.defineProperty(item, "toString", { value() {
+					return JSON.stringify(result);
+				} });
+			}
+		});
+		strings.forEach((string, i) => {
+			str = `${str}${string}${expr[i] || ""}`;
+		});
+		return str;
+	}
+	return template;
+}
+const typeTemplate = createTemplate({ formatAsTypes: true });
+const interfaceTemplate = createTemplate({ formatAsInterfaces: true });
+const template = createTemplate();
+//#endregion
+export { createTemplate, interfaceTemplate, template, typeTemplate };

package/dist/string-utils/cssVar.d.ts

@@ -0,0 +1,55 @@
+import { KebabCase } from "./kebabCase.js";
+
+//#region src/string-utils/cssVar.d.ts
+/**
+ * Sanitize a token name for use in CSS identifiers (variable names, class names).
+ * Dots become underscores, slashes become hyphens to avoid collisions (e.g. 1.5 vs 1/5).
+ *
+ * @example
+ * ```ts
+ * safeTokenName('always/black') // "always-black"
+ * safeTokenName('font.size.lg') // "font_size_lg"
+ * safeTokenName('1.5')          // "1_5"
+ * safeTokenName('1/5')          // "1-5"
+ * ```
+ */
+declare function safeTokenName(name: string): string;
+type CssVarName<Property extends string, Alias extends string> = `--${KebabCase<Property>}-${KebabCase<Alias>}`;
+type CssVar<Property extends string, Alias extends string> = `var(${CssVarName<Property, Alias>})`;
+/**
+ * Generate a CSS variable name from property and alias
+ *
+ * @example
+ * ```ts
+ * cssVarName('fontFamily', 'sans') // "--font-family-sans"
+ * cssVarName('textVariant', 'display1') // "--text-variant-display1"
+ * ```
+ */
+declare function cssVarName<Property extends string, Alias extends string>(property: Property, alias: Alias): CssVarName<Property, Alias>;
+/**
+ * Generate a CSS variable reference
+ *
+ * @example
+ * ```ts
+ * cssVar('fontFamily', 'sans') // "var(--font-family-sans)"
+ * ```
+ */
+declare function cssVar<Property extends string, Alias extends string>(property: Property, alias: Alias): CssVar<Property, Alias>;
+/**
+ * Generate CSS variable declarations from an object
+ *
+ * @example
+ * ```ts
+ * cssVarDeclarations({ color: 'red', fontSize: '16px' })
+ * // "--color: red;\n--font-size: 16px;"
+ * ```
+ *
+ * @example Keys already prefixed with -- are preserved
+ * ```ts
+ * cssVarDeclarations({ '--color-brand': 'blue', fontSize: '16px' })
+ * // "--color-brand: blue;\n--font-size: 16px;"
+ * ```
+ */
+declare function cssVarDeclarations(vars: Record<string, string | number>): string;
+//#endregion
+export { CssVar, CssVarName, cssVar, cssVarDeclarations, cssVarName, safeTokenName };

package/dist/string-utils/cssVar.js

@@ -0,0 +1,63 @@
+import { entries } from "../object-utils/entries.js";
+import { kebabCase } from "./kebabCase.js";
+//#region src/string-utils/cssVar.ts
+/**
+* Sanitize a token name for use in CSS identifiers (variable names, class names).
+* Dots become underscores, slashes become hyphens to avoid collisions (e.g. 1.5 vs 1/5).
+*
+* @example
+* ```ts
+* safeTokenName('always/black') // "always-black"
+* safeTokenName('font.size.lg') // "font_size_lg"
+* safeTokenName('1.5')          // "1_5"
+* safeTokenName('1/5')          // "1-5"
+* ```
+*/
+function safeTokenName(name) {
+	return name.replace(/\./g, "_").replace(/\//g, "-");
+}
+/**
+* Generate a CSS variable name from property and alias
+*
+* @example
+* ```ts
+* cssVarName('fontFamily', 'sans') // "--font-family-sans"
+* cssVarName('textVariant', 'display1') // "--text-variant-display1"
+* ```
+*/
+function cssVarName(property, alias) {
+	return `--${kebabCase(property)}-${kebabCase(alias)}`;
+}
+/**
+* Generate a CSS variable reference
+*
+* @example
+* ```ts
+* cssVar('fontFamily', 'sans') // "var(--font-family-sans)"
+* ```
+*/
+function cssVar(property, alias) {
+	return `var(${cssVarName(property, alias)})`;
+}
+/**
+* Generate CSS variable declarations from an object
+*
+* @example
+* ```ts
+* cssVarDeclarations({ color: 'red', fontSize: '16px' })
+* // "--color: red;\n--font-size: 16px;"
+* ```
+*
+* @example Keys already prefixed with -- are preserved
+* ```ts
+* cssVarDeclarations({ '--color-brand': 'blue', fontSize: '16px' })
+* // "--color-brand: blue;\n--font-size: 16px;"
+* ```
+*/
+function cssVarDeclarations(vars) {
+	return entries(vars).map(([key, value]) => {
+		return `${key.startsWith("--") ? key : `--${kebabCase(key)}`}: ${value};`;
+	}).join("\n");
+}
+//#endregion
+export { cssVar, cssVarDeclarations, cssVarName, safeTokenName };

package/dist/string-utils/cssVars.d.ts

@@ -0,0 +1,81 @@
+//#region src/string-utils/cssVars.d.ts
+/**
+ * Tagged template function for CSS variable generation.
+ * Automatically converts objects to CSS variable declarations.
+ *
+ * Handles three types of inputs:
+ * 1. Flat objects → CSS variables
+ * 2. Nested objects → CSS blocks with selectors
+ * 3. Arrays → joined with double newlines
+ *
+ * @example Flat object (CSS variables)
+ * ```tsx
+ * const vars = { color: 'red', fontSize: '16px' };
+ *
+ * const output = cssVars`
+ *   :root {
+ *     ${vars}
+ *   }
+ * `;
+ *
+ * // Output:
+ * // :root {
+ * //   --color: red;
+ * //   --font-size: 16px;
+ * // }
+ * ```
+ *
+ * @example Nested object (CSS blocks)
+ * ```tsx
+ * const modeBlocks = {
+ *   dark: { colorPrimary: '#000', colorSecondary: '#333' },
+ *   light: { colorPrimary: '#fff', colorSecondary: '#eee' }
+ * };
+ *
+ * const output = cssVars`${modeBlocks}`;
+ *
+ * // Output:
+ * // .dark {
+ * //   --color-primary: #000;
+ * //   --color-secondary: #333;
+ * // }
+ * //
+ * // .light {
+ * //   --color-primary: #fff;
+ * //   --color-secondary: #eee;
+ * // }
+ * ```
+ *
+ * @example Media queries (special @media handling)
+ * ```tsx
+ * const mediaQueries = {
+ *   '@media (min-width: 768px)': { spacing: '2rem' },
+ *   '@media (min-width: 1024px)': { spacing: '3rem' }
+ * };
+ *
+ * const output = cssVars`${mediaQueries}`;
+ *
+ * // Output:
+ * // @media (min-width: 768px) {
+ * //   :root {
+ * //     --spacing: 2rem;
+ * //   }
+ * // }
+ * //
+ * // @media (min-width: 1024px) {
+ * //   :root {
+ * //     --spacing: 3rem;
+ * //   }
+ * // }
+ * ```
+ *
+ * @example Array (joined blocks)
+ * ```tsx
+ * const blocks = ['.dark { --color: black; }', '.light { --color: white; }'];
+ * const output = cssVars`${blocks}`;
+ * // Output: joined blocks with double newlines
+ * ```
+ */
+declare function cssVars(strings: TemplateStringsArray, ...expr: unknown[]): string;
+//#endregion
+export { cssVars };