@yahoo/uds-v5-wip 0.0.1

package/dist/types.d.ts

@@ -0,0 +1 @@
+export * from "@uds/types";

package/dist/types.js

@@ -0,0 +1 @@
+export * from "@uds/types";

package/dist/utils/dist/array-utils/closestItem.d.ts

@@ -0,0 +1,5 @@
+//#region ../utils/dist/array-utils/closestItem.d.ts
+//#region src/array-utils/closestItem.d.ts
+declare function closestItem<T>(arr: T[], item: T): T; //#endregion
+//#endregion
+export { closestItem };

package/dist/utils/dist/array-utils/closestItem.js

@@ -0,0 +1,9 @@
+//#region ../utils/dist/array-utils/closestItem.js
+function closestItem(arr, item) {
+	const index = arr.indexOf(item);
+	if (index === -1) return arr[0];
+	if (index === arr.length - 1) return arr[arr.length - 2];
+	return arr[index + 1];
+}
+//#endregion
+export { closestItem };

package/dist/utils/dist/array-utils/removeItem.d.ts

@@ -0,0 +1,5 @@
+//#region ../utils/dist/array-utils/removeItem.d.ts
+//#region src/array-utils/removeItem.d.ts
+declare function removeItem<T>([...arr]: T[], item: T): T[]; //#endregion
+//#endregion
+export { removeItem };

package/dist/utils/dist/array-utils/removeItem.js

@@ -0,0 +1,8 @@
+//#region ../utils/dist/array-utils/removeItem.js
+function removeItem([ ...arr], item) {
+	const index = arr.indexOf(item);
+	index > -1 && arr.splice(index, 1);
+	return arr;
+}
+//#endregion
+export { removeItem };

package/dist/utils/dist/component-style-defaults.d.ts

@@ -0,0 +1,6 @@
+//#region ../utils/dist/component-style-defaults.d.ts
+//#region src/component-style-defaults.d.ts
+type ComponentStyleDefaultsInput = Record<string, unknown>;
+declare function applyComponentStyleDefaults(componentName: string, styleProps: ComponentStyleDefaultsInput): ComponentStyleDefaultsInput; //#endregion
+//#endregion
+export { ComponentStyleDefaultsInput, applyComponentStyleDefaults };

package/dist/utils/dist/component-style-defaults.js

@@ -0,0 +1,68 @@
+//#region ../utils/dist/component-style-defaults.js
+function toStringValue(value) {
+	return typeof value === "string" ? value : String(value);
+}
+function applyComponentStyleDefaults(componentName, styleProps) {
+	if (componentName === "HStack") {
+		const { gap, display = "flex", flexDirection = display === "flex" ? "row" : void 0, alignItems = display === "flex" ? "center" : void 0, ...rest } = styleProps;
+		return {
+			flexDirection,
+			display,
+			alignItems,
+			gapX: gap,
+			...rest
+		};
+	}
+	if (componentName === "VStack") {
+		const { gap, display = "flex", flexDirection = display === "flex" ? "col" : void 0, ...rest } = styleProps;
+		return {
+			flexDirection,
+			display,
+			gapY: gap,
+			...rest
+		};
+	}
+	if (componentName === "Grid") {
+		const { columns, rows, autoFit, autoFill, inline, display, gridTemplateColumns, gridTemplateRows, ...rest } = styleProps;
+		return {
+			display: display ?? (inline ? "inline-grid" : "grid"),
+			gridTemplateColumns: gridTemplateColumns ?? (autoFit ? `[repeat(auto-fit,minmax(${toStringValue(autoFit)},1fr))]` : autoFill ? `[repeat(auto-fill,minmax(${toStringValue(autoFill)},1fr))]` : columns),
+			gridTemplateRows: gridTemplateRows ?? rows,
+			...rest
+		};
+	}
+	if (componentName === "GridItem") {
+		const { colSpan, rowSpan, colStart, colEnd, rowStart, rowEnd, gridColumnSpan, gridRowSpan, gridColumnStart, gridColumnEnd, gridRowStart, gridRowEnd, ...rest } = styleProps;
+		return {
+			gridColumnSpan: gridColumnSpan ?? colSpan,
+			gridRowSpan: gridRowSpan ?? rowSpan,
+			gridColumnStart: gridColumnStart ?? colStart,
+			gridColumnEnd: gridColumnEnd ?? colEnd,
+			gridRowStart: gridRowStart ?? rowStart,
+			gridRowEnd: gridRowEnd ?? rowEnd,
+			...rest
+		};
+	}
+	if (componentName === "Button") return {
+		cursor: "pointer",
+		...styleProps
+	};
+	if (componentName === "Avatar") {
+		const { shape, ...rest } = styleProps;
+		return {
+			borderRadius: shape,
+			...rest
+		};
+	}
+	if (componentName === "Svg") {
+		const { viewBox, width, height, strokeWidth, ...rest } = styleProps;
+		return {
+			minWidth: viewBox && width && height ? "fit" : void 0,
+			...rest,
+			strokeWidth
+		};
+	}
+	return styleProps;
+}
+//#endregion
+export { applyComponentStyleDefaults };

package/dist/utils/dist/index.js

@@ -0,0 +1,23 @@
+import "./component-style-defaults.js";
+import "./array-utils/closestItem.js";
+import "./array-utils/removeItem.js";
+import "./math-utils/clamp.js";
+import "./motion-utils/interpolate.js";
+import "./object-utils/entries.js";
+import "./object-utils/flattenObj.js";
+import "./object-utils/fromEntries.js";
+import "./object-utils/keys.js";
+import "./object-utils/mapKeys.js";
+import "./object-utils/mapValues.js";
+import "./string-utils/arrayToUnion.js";
+import "./string-utils/capitalize.js";
+import "./string-utils/kebabCase.js";
+import "./string-utils/componentClassName.js";
+import "./string-utils/createTemplate.js";
+import "./string-utils/cssVar.js";
+import "./string-utils/cssVars.js";
+import "./string-utils/dedent.js";
+import "./string-utils/indent.js";
+import "./string-utils/join.js";
+import "./string-utils/split.js";
+import "./string-utils/tsProperties.js";

package/dist/utils/dist/math-utils/clamp.d.ts

@@ -0,0 +1,13 @@
+//#region ../utils/dist/math-utils/clamp.d.ts
+//#region src/math-utils/clamp.d.ts
+/**
+ * Clamps a value between a lower and upper bound.
+ *
+ * @param value - The value to clamp.
+ * @param lower - The lower bound.
+ * @param upper - The upper bound.
+ * @returns The clamped value.
+ */
+declare function clamp(value: number, lower: number, upper: number): number; //#endregion
+//#endregion
+export { clamp };

package/dist/utils/dist/math-utils/clamp.js

@@ -0,0 +1,14 @@
+//#region ../utils/dist/math-utils/clamp.js
+/**
+* Clamps a value between a lower and upper bound.
+*
+* @param value - The value to clamp.
+* @param lower - The lower bound.
+* @param upper - The upper bound.
+* @returns The clamped value.
+*/
+function clamp(value, lower, upper) {
+	return Math.max(lower, Math.min(value, upper));
+}
+//#endregion
+export { clamp };

package/dist/utils/dist/motion-utils/interpolate.d.ts

@@ -0,0 +1,11 @@
+//#region ../utils/dist/motion-utils/interpolate.d.ts
+//#region src/motion-utils/interpolate.d.ts
+type ExtrapolateType = 'extend' | 'identity' | 'clamp';
+declare function interpolate(input: number, inputRange: number[], outputRange: number[], options?: {
+  easing?: (input: number) => number;
+  extrapolate?: ExtrapolateType;
+  extrapolateLeft?: ExtrapolateType;
+  extrapolateRight?: ExtrapolateType;
+}): number; //#endregion
+//#endregion
+export { interpolate };

package/dist/utils/dist/motion-utils/interpolate.js

@@ -0,0 +1,25 @@
+import { clamp } from "../math-utils/clamp.js";
+//#region ../utils/dist/motion-utils/interpolate.js
+function interpolate(input, inputRange, outputRange, options = {}) {
+	const { easing, extrapolate = "extend", extrapolateLeft = extrapolate, extrapolateRight = extrapolate } = options;
+	if (inputRange.length !== outputRange.length) throw new Error("inputRange and outputRange must have the same length");
+	let segmentIndex = inputRange.findIndex((value, i) => input < value && i > 0) - 1;
+	if (segmentIndex === -2) segmentIndex = inputRange.length - 2;
+	let extrapolationType = extrapolate;
+	if (segmentIndex < 0) extrapolationType = extrapolateLeft;
+	else if (segmentIndex >= inputRange.length - 2) extrapolationType = extrapolateRight;
+	if (extrapolationType === "clamp") {
+		if (segmentIndex < 0) return outputRange[0];
+		if (segmentIndex >= inputRange.length - 2) return outputRange[outputRange.length - 1];
+	} else if (extrapolationType === "identity") return input;
+	const inputStart = inputRange[segmentIndex];
+	const inputEnd = inputRange[segmentIndex + 1];
+	const outputStart = outputRange[segmentIndex];
+	const outputEnd = outputRange[segmentIndex + 1];
+	let ratio = (input - inputStart) / (inputEnd - inputStart);
+	ratio = clamp(ratio, 0, 1);
+	if (easing) ratio = easing(ratio);
+	return outputStart + ratio * (outputEnd - outputStart);
+}
+//#endregion
+export { interpolate };

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

@@ -0,0 +1,5 @@
+//#region ../utils/dist/object-utils/entries.d.ts
+//#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
+//#endregion
+export { entries };

package/dist/utils/dist/object-utils/entries.js

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

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

@@ -0,0 +1,13 @@
+//#region ../utils/dist/object-utils/flattenObj.d.ts
+//#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
+//#endregion
+export { flattenObj };

package/dist/utils/dist/object-utils/flattenObj.js

@@ -0,0 +1,21 @@
+//#region ../utils/dist/object-utils/flattenObj.js
+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/utils/dist/object-utils/fromEntries.d.ts

@@ -0,0 +1,5 @@
+//#region ../utils/dist/object-utils/fromEntries.d.ts
+//#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
+//#endregion
+export { fromEntries };

package/dist/utils/dist/object-utils/fromEntries.js

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

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

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

package/dist/utils/dist/object-utils/keys.js

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

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

@@ -0,0 +1,6 @@
+//#region ../utils/dist/object-utils/mapKeys.d.ts
+//#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
+//#endregion
+export { mapKeys };

package/dist/utils/dist/object-utils/mapKeys.js

@@ -0,0 +1,10 @@
+//#region ../utils/dist/object-utils/mapKeys.js
+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/utils/dist/object-utils/mapValues.d.ts

@@ -0,0 +1,6 @@
+//#region ../utils/dist/object-utils/mapValues.d.ts
+//#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
+//#endregion
+export { mapValues };

package/dist/utils/dist/object-utils/mapValues.js

@@ -0,0 +1,9 @@
+//#region ../utils/dist/object-utils/mapValues.js
+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/utils/dist/string-utils/arrayToUnion.d.ts

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

package/dist/utils/dist/string-utils/arrayToUnion.js

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

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

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

package/dist/utils/dist/string-utils/capitalize.js

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

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

@@ -0,0 +1,26 @@
+//#region ../utils/dist/string-utils/componentClassName.d.ts
+//#region src/string-utils/componentClassName.d.ts
+/**
+ * Build the base class name for a component slot.
+ *
+ * @example componentSlotClass('Switch', 'root') // "switch-root"
+ */
+declare function componentSlotClass(componentName: string, slot: string): string;
+/**
+ * Build the variant class name for a component slot.
+ *
+ * @example componentVariantClass('Switch', 'root', 'size', 'lg') // "switch-root--size-lg"
+ */
+declare function componentVariantClass(componentName: string, slot: string, axis: string, value: string): string;
+/**
+ * Build the compound-variant class name for a component slot.
+ *
+ * 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, slot: string, conditions: Record<string, string>): string; //#endregion
+//#endregion
+export { componentCompoundClass, componentSlotClass, componentVariantClass };

package/dist/utils/dist/string-utils/componentClassName.js

@@ -0,0 +1,33 @@
+import { kebabCase } from "./kebabCase.js";
+//#region ../utils/dist/string-utils/componentClassName.js
+/**
+* Build the base class name for a component slot.
+*
+* @example componentSlotClass('Switch', 'root') // "switch-root"
+*/
+function componentSlotClass(componentName, slot) {
+	return `${kebabCase(componentName)}-${slot}`;
+}
+/**
+* Build the variant class name for a component slot.
+*
+* @example componentVariantClass('Switch', 'root', 'size', 'lg') // "switch-root--size-lg"
+*/
+function componentVariantClass(componentName, slot, axis, value) {
+	return `${kebabCase(componentName)}-${slot}--${axis}-${value}`;
+}
+/**
+* Build the compound-variant class name for a component slot.
+*
+* 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, slot, conditions) {
+	const suffix = Object.entries(conditions).sort(([a], [b]) => a.localeCompare(b)).map(([a, v]) => `${a}-${v}`).join("_");
+	return `${kebabCase(componentName)}-${slot}--${suffix}`;
+}
+//#endregion
+export { componentCompoundClass, componentSlotClass, componentVariantClass };

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

@@ -0,0 +1,17 @@
+//#region ../utils/dist/string-utils/createTemplate.d.ts
+//#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
+//#endregion
+export { createTemplate, interfaceTemplate, template, typeTemplate };

package/dist/utils/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 ../utils/dist/string-utils/createTemplate.js
+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/utils/dist/string-utils/cssVar.d.ts

@@ -0,0 +1,54 @@
+import { KebabCase } from "./kebabCase.js";
+
+//#region ../utils/dist/string-utils/cssVar.d.ts
+//#region src/string-utils/cssVar.d.ts
+/**
+ * Sanitize a token name for use in CSS identifiers (variable names, class names).
+ * Replaces dots and slashes with underscores.
+ *
+ * @example
+ * ```ts
+ * safeTokenName('always/black') // "always_black"
+ * safeTokenName('font.size.lg') // "font_size_lg"
+ * ```
+ */
+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
+//#endregion
+export { CssVar, CssVarName, cssVar, cssVarDeclarations, cssVarName, safeTokenName };