@real1ty-obsidian-plugins/utils 2.9.0 → 2.11.0

package/dist/core/color-utils.d.ts

@@ -0,0 +1,17 @@
+export declare function parseColor(color: string): {
+    h: number;
+    s: number;
+    l: number;
+} | null;
+/**
+ * Generates an array of evenly distributed HSL colors for visualization.
+ * Uses the HSL color space to create visually distinct colors by distributing
+ * them evenly around the color wheel.
+ *
+ * @param count - Number of colors to generate
+ * @param saturation - Saturation percentage (0-100), defaults to 70
+ * @param lightness - Lightness percentage (0-100), defaults to 60
+ * @returns Array of HSL color strings
+ */
+export declare function generateColors(count: number, saturation?: number, lightness?: number): string[];
+//# sourceMappingURL=color-utils.d.ts.map

package/dist/core/color-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"color-utils.d.ts","sourceRoot":"","sources":["../../src/core/color-utils.ts"],"names":[],"mappings":"AAEA,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAMpF;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,SAAK,EAAE,SAAS,SAAK,GAAG,MAAM,EAAE,CAQvF"}

package/dist/core/color-utils.js

@@ -0,0 +1,29 @@
+import { colord } from "colord";
+export function parseColor(color) {
+    const parsed = colord(color);
+    if (!parsed.isValid()) {
+        return null;
+    }
+    return parsed.toHsl();
+}
+/**
+ * Generates an array of evenly distributed HSL colors for visualization.
+ * Uses the HSL color space to create visually distinct colors by distributing
+ * them evenly around the color wheel.
+ *
+ * @param count - Number of colors to generate
+ * @param saturation - Saturation percentage (0-100), defaults to 70
+ * @param lightness - Lightness percentage (0-100), defaults to 60
+ * @returns Array of HSL color strings
+ */
+export function generateColors(count, saturation = 70, lightness = 60) {
+    if (count <= 0)
+        return [];
+    const colors = [];
+    for (let i = 0; i < count; i++) {
+        const hue = (i * 360) / count;
+        colors.push(`hsl(${hue}, ${saturation}%, ${lightness}%)`);
+    }
+    return colors;
+}
+//# sourceMappingURL=color-utils.js.map

package/dist/core/color-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"color-utils.js","sourceRoot":"","sources":["../../src/core/color-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,MAAM,UAAU,UAAU,CAAC,KAAa;IACvC,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IAC7B,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,CAAC;QACvB,OAAO,IAAI,CAAC;IACb,CAAC;IACD,OAAO,MAAM,CAAC,KAAK,EAAE,CAAC;AACvB,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,cAAc,CAAC,KAAa,EAAE,UAAU,GAAG,EAAE,EAAE,SAAS,GAAG,EAAE;IAC5E,IAAI,KAAK,IAAI,CAAC;QAAE,OAAO,EAAE,CAAC;IAC1B,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC;QAChC,MAAM,GAAG,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,KAAK,CAAC;QAC9B,MAAM,CAAC,IAAI,CAAC,OAAO,GAAG,KAAK,UAAU,MAAM,SAAS,IAAI,CAAC,CAAC;IAC3D,CAAC;IACD,OAAO,MAAM,CAAC;AACf,CAAC","sourcesContent":["import { colord } from \"colord\";\n\nexport function parseColor(color: string): { h: number; s: number; l: number } | null {\n\tconst parsed = colord(color);\n\tif (!parsed.isValid()) {\n\t\treturn null;\n\t}\n\treturn parsed.toHsl();\n}\n\n/**\n * Generates an array of evenly distributed HSL colors for visualization.\n * Uses the HSL color space to create visually distinct colors by distributing\n * them evenly around the color wheel.\n *\n * @param count - Number of colors to generate\n * @param saturation - Saturation percentage (0-100), defaults to 70\n * @param lightness - Lightness percentage (0-100), defaults to 60\n * @returns Array of HSL color strings\n */\nexport function generateColors(count: number, saturation = 70, lightness = 60): string[] {\n\tif (count <= 0) return [];\n\tconst colors: string[] = [];\n\tfor (let i = 0; i < count; i++) {\n\t\tconst hue = (i * 360) / count;\n\t\tcolors.push(`hsl(${hue}, ${saturation}%, ${lightness}%)`);\n\t}\n\treturn colors;\n}\n"]}

package/dist/core/css-utils.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Prefixes class names with the standard plugin prefix.
+ * Handles multiple class names and automatically adds the prefix.
+ *
+ * @example
+ * cls("calendar-view") => "prisma-calendar-view"
+ * cls("button", "active") => "prisma-button prisma-active"
+ * cls("modal calendar") => "prisma-modal prisma-calendar"
+ */
+export declare function cls(...classNames: string[]): string;
+/**
+ * Adds prefixed class names to an element.
+ *
+ * @example
+ * addCls(element, "active", "selected")
+ */
+export declare function addCls(element: HTMLElement, ...classNames: string[]): void;
+/**
+ * Removes prefixed class names from an element.
+ *
+ * @example
+ * removeCls(element, "active", "selected")
+ */
+export declare function removeCls(element: HTMLElement, ...classNames: string[]): void;
+/**
+ * Toggles prefixed class names on an element.
+ *
+ * @example
+ * toggleCls(element, "active")
+ */
+export declare function toggleCls(element: HTMLElement, className: string, force?: boolean): boolean;
+/**
+ * Checks if element has a prefixed class.
+ *
+ * @example
+ * hasCls(element, "active")
+ */
+export declare function hasCls(element: HTMLElement, className: string): boolean;
+//# sourceMappingURL=css-utils.d.ts.map

package/dist/core/css-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"css-utils.d.ts","sourceRoot":"","sources":["../../src/core/css-utils.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,wBAAgB,GAAG,CAAC,GAAG,UAAU,EAAE,MAAM,EAAE,GAAG,MAAM,CAMnD;AAED;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,OAAO,EAAE,WAAW,EAAE,GAAG,UAAU,EAAE,MAAM,EAAE,GAAG,IAAI,CAK1E;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,WAAW,EAAE,GAAG,UAAU,EAAE,MAAM,EAAE,GAAG,IAAI,CAK7E;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,OAAO,CAE3F;AAED;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAEvE"}

package/dist/core/css-utils.js

@@ -0,0 +1,60 @@
+const CSS_PREFIX = "prisma-";
+/**
+ * Prefixes class names with the standard plugin prefix.
+ * Handles multiple class names and automatically adds the prefix.
+ *
+ * @example
+ * cls("calendar-view") => "prisma-calendar-view"
+ * cls("button", "active") => "prisma-button prisma-active"
+ * cls("modal calendar") => "prisma-modal prisma-calendar"
+ */
+export function cls(...classNames) {
+    return classNames
+        .flatMap((name) => name.split(/\s+/))
+        .filter((name) => name.length > 0)
+        .map((name) => `${CSS_PREFIX}${name}`)
+        .join(" ");
+}
+/**
+ * Adds prefixed class names to an element.
+ *
+ * @example
+ * addCls(element, "active", "selected")
+ */
+export function addCls(element, ...classNames) {
+    const classes = cls(...classNames);
+    if (classes) {
+        element.classList.add(...classes.split(/\s+/));
+    }
+}
+/**
+ * Removes prefixed class names from an element.
+ *
+ * @example
+ * removeCls(element, "active", "selected")
+ */
+export function removeCls(element, ...classNames) {
+    const classes = cls(...classNames);
+    if (classes) {
+        element.classList.remove(...classes.split(/\s+/));
+    }
+}
+/**
+ * Toggles prefixed class names on an element.
+ *
+ * @example
+ * toggleCls(element, "active")
+ */
+export function toggleCls(element, className, force) {
+    return element.classList.toggle(cls(className), force);
+}
+/**
+ * Checks if element has a prefixed class.
+ *
+ * @example
+ * hasCls(element, "active")
+ */
+export function hasCls(element, className) {
+    return element.classList.contains(cls(className));
+}
+//# sourceMappingURL=css-utils.js.map

package/dist/core/css-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"css-utils.js","sourceRoot":"","sources":["../../src/core/css-utils.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,GAAG,SAAS,CAAC;AAE7B;;;;;;;;GAQG;AACH,MAAM,UAAU,GAAG,CAAC,GAAG,UAAoB;IAC1C,OAAO,UAAU;SACf,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;SACpC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;SACjC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,UAAU,GAAG,IAAI,EAAE,CAAC;SACrC,IAAI,CAAC,GAAG,CAAC,CAAC;AACb,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,MAAM,CAAC,OAAoB,EAAE,GAAG,UAAoB;IACnE,MAAM,OAAO,GAAG,GAAG,CAAC,GAAG,UAAU,CAAC,CAAC;IACnC,IAAI,OAAO,EAAE,CAAC;QACb,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;IAChD,CAAC;AACF,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CAAC,OAAoB,EAAE,GAAG,UAAoB;IACtE,MAAM,OAAO,GAAG,GAAG,CAAC,GAAG,UAAU,CAAC,CAAC;IACnC,IAAI,OAAO,EAAE,CAAC;QACb,OAAO,CAAC,SAAS,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;IACnD,CAAC;AACF,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CAAC,OAAoB,EAAE,SAAiB,EAAE,KAAe;IACjF,OAAO,OAAO,CAAC,SAAS,CAAC,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,KAAK,CAAC,CAAC;AACxD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,MAAM,CAAC,OAAoB,EAAE,SAAiB;IAC7D,OAAO,OAAO,CAAC,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC;AACnD,CAAC","sourcesContent":["const CSS_PREFIX = \"prisma-\";\n\n/**\n * Prefixes class names with the standard plugin prefix.\n * Handles multiple class names and automatically adds the prefix.\n *\n * @example\n * cls(\"calendar-view\") => \"prisma-calendar-view\"\n * cls(\"button\", \"active\") => \"prisma-button prisma-active\"\n * cls(\"modal calendar\") => \"prisma-modal prisma-calendar\"\n */\nexport function cls(...classNames: string[]): string {\n\treturn classNames\n\t\t.flatMap((name) => name.split(/\\s+/))\n\t\t.filter((name) => name.length > 0)\n\t\t.map((name) => `${CSS_PREFIX}${name}`)\n\t\t.join(\" \");\n}\n\n/**\n * Adds prefixed class names to an element.\n *\n * @example\n * addCls(element, \"active\", \"selected\")\n */\nexport function addCls(element: HTMLElement, ...classNames: string[]): void {\n\tconst classes = cls(...classNames);\n\tif (classes) {\n\t\telement.classList.add(...classes.split(/\\s+/));\n\t}\n}\n\n/**\n * Removes prefixed class names from an element.\n *\n * @example\n * removeCls(element, \"active\", \"selected\")\n */\nexport function removeCls(element: HTMLElement, ...classNames: string[]): void {\n\tconst classes = cls(...classNames);\n\tif (classes) {\n\t\telement.classList.remove(...classes.split(/\\s+/));\n\t}\n}\n\n/**\n * Toggles prefixed class names on an element.\n *\n * @example\n * toggleCls(element, \"active\")\n */\nexport function toggleCls(element: HTMLElement, className: string, force?: boolean): boolean {\n\treturn element.classList.toggle(cls(className), force);\n}\n\n/**\n * Checks if element has a prefixed class.\n *\n * @example\n * hasCls(element, \"active\")\n */\nexport function hasCls(element: HTMLElement, className: string): boolean {\n\treturn element.classList.contains(cls(className));\n}\n"]}

package/dist/core/index.d.ts

@@ -1,5 +1,8 @@
+export * from "./color-utils";
+export * from "./css-utils";
 export * from "./evaluator";
 export * from "./expression-utils";
 export * from "./frontmatter-value";
 export * from "./generate";
+export * from "./validation";
 //# sourceMappingURL=index.d.ts.map

package/dist/core/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC"}

package/dist/core/index.js

@@ -1,5 +1,8 @@
+export * from "./color-utils";
+export * from "./css-utils";
 export * from "./evaluator";
 export * from "./expression-utils";
 export * from "./frontmatter-value";
 export * from "./generate";
+export * from "./validation";
 //# sourceMappingURL=index.js.map

package/dist/core/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,YAAY,CAAC","sourcesContent":["export * from \"./evaluator\";\nexport * from \"./expression-utils\";\nexport * from \"./frontmatter-value\";\nexport * from \"./generate\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC","sourcesContent":["export * from \"./color-utils\";\nexport * from \"./css-utils\";\nexport * from \"./evaluator\";\nexport * from \"./expression-utils\";\nexport * from \"./frontmatter-value\";\nexport * from \"./generate\";\nexport * from \"./validation\";\n"]}

package/dist/core/validation.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Checks if a value is not empty.
+ * Returns false for: undefined, null, empty string, or empty arrays.
+ * Returns true for all other values.
+ */
+export declare function isNotEmpty(value: unknown): boolean;
+/**
+ * Parses a value to a positive integer.
+ * Handles both number and string types from frontmatter.
+ * Returns the parsed integer if valid and positive, otherwise returns the fallback value.
+ */
+export declare function parsePositiveInt(value: unknown, fallback: number): number;
+//# sourceMappingURL=validation.d.ts.map

package/dist/core/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/core/validation.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAQlD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAMzE"}

package/dist/core/validation.js

@@ -0,0 +1,27 @@
+/**
+ * Checks if a value is not empty.
+ * Returns false for: undefined, null, empty string, or empty arrays.
+ * Returns true for all other values.
+ */
+export function isNotEmpty(value) {
+    if (value === undefined || value === null || value === "") {
+        return false;
+    }
+    if (Array.isArray(value) && value.length === 0) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Parses a value to a positive integer.
+ * Handles both number and string types from frontmatter.
+ * Returns the parsed integer if valid and positive, otherwise returns the fallback value.
+ */
+export function parsePositiveInt(value, fallback) {
+    if (value === undefined || value === null) {
+        return fallback;
+    }
+    const parsed = typeof value === "number" ? Math.floor(value) : Number.parseInt(String(value), 10);
+    return !Number.isNaN(parsed) && parsed > 0 ? parsed : fallback;
+}
+//# sourceMappingURL=validation.js.map

package/dist/core/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../src/core/validation.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,KAAc;IACxC,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,EAAE,EAAE,CAAC;QAC3D,OAAO,KAAK,CAAC;IACd,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAChD,OAAO,KAAK,CAAC;IACd,CAAC;IACD,OAAO,IAAI,CAAC;AACb,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAc,EAAE,QAAgB;IAChE,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAC3C,OAAO,QAAQ,CAAC;IACjB,CAAC;IACD,MAAM,MAAM,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC;IAClG,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC;AAChE,CAAC","sourcesContent":["/**\n * Checks if a value is not empty.\n * Returns false for: undefined, null, empty string, or empty arrays.\n * Returns true for all other values.\n */\nexport function isNotEmpty(value: unknown): boolean {\n\tif (value === undefined || value === null || value === \"\") {\n\t\treturn false;\n\t}\n\tif (Array.isArray(value) && value.length === 0) {\n\t\treturn false;\n\t}\n\treturn true;\n}\n\n/**\n * Parses a value to a positive integer.\n * Handles both number and string types from frontmatter.\n * Returns the parsed integer if valid and positive, otherwise returns the fallback value.\n */\nexport function parsePositiveInt(value: unknown, fallback: number): number {\n\tif (value === undefined || value === null) {\n\t\treturn fallback;\n\t}\n\tconst parsed = typeof value === \"number\" ? Math.floor(value) : Number.parseInt(String(value), 10);\n\treturn !Number.isNaN(parsed) && parsed > 0 ? parsed : fallback;\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@real1ty-obsidian-plugins/utils",
-  "version": "2.9.0",
+  "version": "2.11.0",
   "description": "Shared utilities for Obsidian plugins",
   "type": "module",
   "main": "./dist/index.js",
@@ -49,6 +49,7 @@
     "vitest": "^2.0.5"
   },
   "dependencies": {
+    "colord": "^2.9.3",
     "gray-matter": "^4.0.3",
     "luxon": "^3.7.2",
     "obsidian": "^1.8.7",

package/src/core/color-utils.ts

@@ -0,0 +1,29 @@
+import { colord } from "colord";
+
+export function parseColor(color: string): { h: number; s: number; l: number } | null {
+	const parsed = colord(color);
+	if (!parsed.isValid()) {
+		return null;
+	}
+	return parsed.toHsl();
+}
+
+/**
+ * Generates an array of evenly distributed HSL colors for visualization.
+ * Uses the HSL color space to create visually distinct colors by distributing
+ * them evenly around the color wheel.
+ *
+ * @param count - Number of colors to generate
+ * @param saturation - Saturation percentage (0-100), defaults to 70
+ * @param lightness - Lightness percentage (0-100), defaults to 60
+ * @returns Array of HSL color strings
+ */
+export function generateColors(count: number, saturation = 70, lightness = 60): string[] {
+	if (count <= 0) return [];
+	const colors: string[] = [];
+	for (let i = 0; i < count; i++) {
+		const hue = (i * 360) / count;
+		colors.push(`hsl(${hue}, ${saturation}%, ${lightness}%)`);
+	}
+	return colors;
+}

package/src/core/css-utils.ts

@@ -0,0 +1,64 @@
+const CSS_PREFIX = "prisma-";
+
+/**
+ * Prefixes class names with the standard plugin prefix.
+ * Handles multiple class names and automatically adds the prefix.
+ *
+ * @example
+ * cls("calendar-view") => "prisma-calendar-view"
+ * cls("button", "active") => "prisma-button prisma-active"
+ * cls("modal calendar") => "prisma-modal prisma-calendar"
+ */
+export function cls(...classNames: string[]): string {
+	return classNames
+		.flatMap((name) => name.split(/\s+/))
+		.filter((name) => name.length > 0)
+		.map((name) => `${CSS_PREFIX}${name}`)
+		.join(" ");
+}
+
+/**
+ * Adds prefixed class names to an element.
+ *
+ * @example
+ * addCls(element, "active", "selected")
+ */
+export function addCls(element: HTMLElement, ...classNames: string[]): void {
+	const classes = cls(...classNames);
+	if (classes) {
+		element.classList.add(...classes.split(/\s+/));
+	}
+}
+
+/**
+ * Removes prefixed class names from an element.
+ *
+ * @example
+ * removeCls(element, "active", "selected")
+ */
+export function removeCls(element: HTMLElement, ...classNames: string[]): void {
+	const classes = cls(...classNames);
+	if (classes) {
+		element.classList.remove(...classes.split(/\s+/));
+	}
+}
+
+/**
+ * Toggles prefixed class names on an element.
+ *
+ * @example
+ * toggleCls(element, "active")
+ */
+export function toggleCls(element: HTMLElement, className: string, force?: boolean): boolean {
+	return element.classList.toggle(cls(className), force);
+}
+
+/**
+ * Checks if element has a prefixed class.
+ *
+ * @example
+ * hasCls(element, "active")
+ */
+export function hasCls(element: HTMLElement, className: string): boolean {
+	return element.classList.contains(cls(className));
+}

package/src/core/index.ts

@@ -1,4 +1,7 @@
+export * from "./color-utils";
+export * from "./css-utils";
 export * from "./evaluator";
 export * from "./expression-utils";
 export * from "./frontmatter-value";
 export * from "./generate";
+export * from "./validation";

package/src/core/validation.ts

@@ -0,0 +1,27 @@
+/**
+ * Checks if a value is not empty.
+ * Returns false for: undefined, null, empty string, or empty arrays.
+ * Returns true for all other values.
+ */
+export function isNotEmpty(value: unknown): boolean {
+	if (value === undefined || value === null || value === "") {
+		return false;
+	}
+	if (Array.isArray(value) && value.length === 0) {
+		return false;
+	}
+	return true;
+}
+
+/**
+ * Parses a value to a positive integer.
+ * Handles both number and string types from frontmatter.
+ * Returns the parsed integer if valid and positive, otherwise returns the fallback value.
+ */
+export function parsePositiveInt(value: unknown, fallback: number): number {
+	if (value === undefined || value === null) {
+		return fallback;
+	}
+	const parsed = typeof value === "number" ? Math.floor(value) : Number.parseInt(String(value), 10);
+	return !Number.isNaN(parsed) && parsed > 0 ? parsed : fallback;
+}