@csszyx/vars 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 csszyx contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@csszyx/vars",
+  "version": "0.1.0",
+  "description": "CSS custom property helpers — inject and patch CSS variables for runtime-driven styling",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./src/index.ts",
+      "types": "./src/index.ts"
+    },
+    "./react": {
+      "import": "./src/react.ts",
+      "types": "./src/react.ts"
+    }
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "keywords": [
+    "csszyx",
+    "css-variables",
+    "css-custom-properties",
+    "runtime-styling"
+  ],
+  "license": "MIT"
+}

package/src/index.ts

@@ -0,0 +1,65 @@
+/**
+ * @csszyx/vars — CSS custom property helpers for runtime-driven styling.
+ *
+ * Zero-runtime CSSzyx handles static sz props at build time.
+ * This package handles values that come from an API, CMS, or user config
+ * at runtime, injected as CSS custom properties so Tailwind-generated
+ * classes like `bg-(--cfg-bg)` resolve correctly.
+ *
+ * Works standalone (no React required). React hook: @csszyx/vars/react
+ */
+
+/**
+ *
+ */
+export type SzVars = Record<string, string | number>;
+
+/**
+ * Apply CSS custom properties to an element.
+ * Keys are auto-prefixed with `--` if not already.
+ * Returns a cleanup function that removes all applied properties.
+ *
+ * @param vars - Record of CSS var name → value. Keys auto-prefixed with `--`.
+ * @param element - Target element. Defaults to `document.documentElement` (`:root`).
+ * @returns Cleanup function that removes all applied properties.
+ *
+ * @example
+ * const cleanup = applySzVars({ 'form-bg': '#fff', 'form-p': '24px' }, formEl);
+ * // → formEl.style: --form-bg: #fff; --form-p: 24px
+ * // cleanup() → removes them
+ */
+export function applySzVars(
+    vars: SzVars,
+    element: HTMLElement = document.documentElement,
+): () => void {
+    const applied: string[] = [];
+
+    for (const [key, value] of Object.entries(vars)) {
+        const name = key.startsWith('--') ? key : `--${key}`;
+        element.style.setProperty(name, String(value));
+        applied.push(name);
+    }
+
+    return () => {
+        for (const name of applied) {
+            element.style.removeProperty(name);
+        }
+    };
+}
+
+/**
+ * Update CSS custom properties on an element without full re-apply.
+ * Only sets changed values — useful for frequent updates (drag sliders, etc.)
+ *
+ * @param vars - Record of CSS var name → value. Keys auto-prefixed with `--`.
+ * @param element - Target element. Defaults to `document.documentElement` (`:root`).
+ */
+export function patchSzVars(
+    vars: SzVars,
+    element: HTMLElement = document.documentElement,
+): void {
+    for (const [key, value] of Object.entries(vars)) {
+        const name = key.startsWith('--') ? key : `--${key}`;
+        element.style.setProperty(name, String(value));
+    }
+}

package/src/react.ts

@@ -0,0 +1,34 @@
+/**
+ * @csszyx/dynamic/react — React hook for CSS variable injection.
+ * Requires React >=18. Import from "@csszyx/dynamic/react".
+ */
+
+import { type RefObject, useEffect, useRef } from 'react';
+
+import { patchSzVars, type SzVars } from './index.js';
+
+/**
+ * Reactively apply CSS custom properties to an element.
+ * Re-applies whenever `vars` content changes.
+ *
+ * @param vars  - Record of CSS var name → value. Keys auto-prefixed with `--`.
+ * @param ref   - Target element ref. Defaults to document.documentElement (:root).
+ *
+ * @example
+ * const formRef = useRef<HTMLDivElement>(null);
+ * useSzVars({ 'form-bg': config.bg, 'form-p': config.padding }, formRef);
+ * // → <div ref={formRef}> gets --form-bg and --form-p on every config change
+ */
+export function useSzVars(vars: SzVars, ref?: RefObject<HTMLElement | null>): void {
+    // Keep a ref to latest vars to avoid stale closure in effect
+    const latestVars = useRef(vars);
+    latestVars.current = vars;
+
+    useEffect(() => {
+        const el = ref?.current ?? document.documentElement;
+        if (!el) {return;}
+        patchSzVars(latestVars.current, el);
+    });
+    // No dep array — runs after every render, intentional:
+    // patchSzVars only calls setProperty for entries that changed (cheap DOM op).
+}