css-utility-functions 1.0.1

package/src/logic/xnor.css

@@ -0,0 +1,30 @@
+/**
+ * --xnor() — Exclusive NOR Operation (NOT XOR)
+ *
+ * Returns 1 if both operands are the same, otherwise returns 0.
+ * The opposite of XOR - checks for equality.
+ *
+ * Truth table:
+ * - 0 XNOR 0 = 1 (both same)
+ * - 0 XNOR 1 = 0 (different)
+ * - 1 XNOR 0 = 0 (different)
+ * - 1 XNOR 1 = 1 (both same)
+ *
+ * @param {number} --a - First switch variable (0 or 1)
+ * @param {number} --b - Second switch variable (0 or 1)
+ * @returns {number} - Result (0 or 1)
+ *
+ * @example
+ * .sync-indicator {
+ *   --local-state: 1;
+ *   --remote-state: 1;
+ *   opacity: --xnor(var(--local-state), var(--remote-state));
+ * }
+ *
+ * @see https://css-tricks.com/logical-operations-with-css-variables/
+ */
+
+@function --xnor(--a <number>, --b <number>) returns <number> {
+  result: calc(1 - (var(--a) - var(--b)) * (var(--a) - var(--b)));
+}
+

package/src/logic/xor.css

@@ -0,0 +1,30 @@
+/**
+ * --xor() — Exclusive OR Operation
+ *
+ * Returns 1 if exactly one operand is 1, otherwise returns 0.
+ * Uses subtraction squared to get absolute value: (a - b)²
+ *
+ * Truth table:
+ * - 0 XOR 0 = 0 (both same)
+ * - 0 XOR 1 = 1 (different)
+ * - 1 XOR 0 = 1 (different)
+ * - 1 XOR 1 = 0 (both same)
+ *
+ * @param {number} --a - First switch variable (0 or 1)
+ * @param {number} --b - Second switch variable (0 or 1)
+ * @returns {number} - Result (0 or 1)
+ *
+ * @example
+ * .highlight-when-different {
+ *   --user-theme: 1;
+ *   --system-theme: 0;
+ *   opacity: --xor(var(--user-theme), var(--system-theme));
+ * }
+ *
+ * @see https://css-tricks.com/logical-operations-with-css-variables/
+ */
+
+@function --xor(--a <number>, --b <number>) returns <number> {
+  result: calc((var(--a) - var(--b)) * (var(--a) - var(--b)));
+}
+

package/src/math/circle.css

@@ -0,0 +1,46 @@
+/**
+ * --circle-x() — Circle X Position
+ *
+ * Calculate X coordinate on a circle using radius and angle.
+ * Uses cosine: r * cos(deg)
+ *
+ * @param {length} --radius - Circle radius
+ * @param {angle} --angle - Angle in degrees, default: 0deg
+ * @returns {length} - X coordinate offset from center
+ *
+ * @example
+ * .orbit {
+ *   left: calc(50% + --circle-x(100px, 45deg));  // 45° position
+ * }
+ */
+
+@function --circle-x(
+  --radius <length>,
+  --angle <angle>: 0deg
+) returns <length> {
+  result: calc(var(--radius) * cos(var(--angle)));
+}
+
+/**
+ * --circle-y() — Circle Y Position
+ *
+ * Calculate Y coordinate on a circle using radius and angle.
+ * Uses sine: r * sin(deg)
+ *
+ * @param {length} --radius - Circle radius
+ * @param {angle} --angle - Angle in degrees, default: 0deg
+ * @returns {length} - Y coordinate offset from center
+ *
+ * @example
+ * .orbit {
+ *   top: calc(50% + --circle-y(100px, 45deg));  // 45° position
+ * }
+ */
+
+@function --circle-y(
+  --radius <length>,
+  --angle <angle>: 0deg
+) returns <length> {
+  result: calc(var(--radius) * sin(var(--angle)));
+}
+

package/src/math/lerp.css

@@ -0,0 +1,29 @@
+/**
+ * --lerp() — Linear Interpolation
+ *
+ * Interpolates between two values using a t parameter (0-1).
+ * When t=0, returns a; when t=1, returns b; when t=0.5, returns midpoint.
+ * Hides the complex calc expression: calc(a + (b - a) * t)
+ *
+ * @param {length-percentage} --a - Start value
+ * @param {length-percentage} --b - End value
+ * @param {number} --t - Interpolation factor (0-1), default: 0.5
+ * @returns {length-percentage} - Interpolated value
+ *
+ * @example
+ * .animated {
+ *   width: --lerp(100px, 500px, 0.3);  // 30% between 100px and 500px
+ * }
+ * .transition {
+ *   width: --lerp(10%, 80%, 0.75);  // 75% between 10% and 80%
+ * }
+ */
+
+@function --lerp(
+  --a <length-percentage>,
+  --b <length-percentage>,
+  --t <number>: 0.5
+) returns <length-percentage> {
+  result: calc(var(--a) * (1 - var(--t)) + var(--b) * var(--t));
+}
+

package/src/math/modular.css

@@ -0,0 +1,32 @@
+/**
+ * --modular() — Modular Scale (Typographic Scale)
+ *
+ * Calculate values using a modular scale (typographic ratio).
+ * Hides the pow calculation: base * pow(ratio, step)
+ *
+ * @param {number} --step - Scale step (can be negative for smaller values)
+ * @param {length|number} --base - Base value, default: 1rem
+ * @param {number} --ratio - Scale ratio, default: 1.25 (major third)
+ * @returns {length|number} - Scaled value
+ *
+ * @example
+ * :root {
+ *   --type-base: 1rem;
+ *   --type-ratio: 1.25;
+ * }
+ * h1 {
+ *   font-size: --modular(4, var(--type-base), var(--type-ratio));  // Large scale
+ * }
+ * small {
+ *   font-size: --modular(-1, var(--type-base), var(--type-ratio));  // Smaller
+ * }
+ */
+
+@function --modular(
+  --step <number>,
+  --base <length|number>: 1rem,
+  --ratio <number>: 1.25
+) returns <length|number> {
+  result: calc(var(--base) * pow(var(--ratio), var(--step)));
+}
+

package/src/math/poly-angle.css

@@ -0,0 +1,27 @@
+/**
+ * --poly-angle() — Polygon Vertex Angle
+ *
+ * Calculate the angle for a vertex in a regular polygon.
+ * Useful for creating polygon shapes with CSS transforms.
+ * Formula: (360deg / sides * index) - 90deg
+ *
+ * @param {number} --sides - Number of sides in polygon
+ * @param {number} --index - Vertex index (0-based), default: 0
+ * @returns {angle} - Angle in degrees
+ *
+ * @example
+ * .hexagon-vertex-0 {
+ *   transform: rotate(--poly-angle(6, 0));  // First vertex of hexagon
+ * }
+ * .pentagon-vertex-2 {
+ *   transform: rotate(--poly-angle(5, 2));  // Third vertex of pentagon
+ * }
+ */
+
+@function --poly-angle(
+  --sides <number>,
+  --index <number>: 0
+) returns <angle> {
+  result: calc(360deg / var(--sides) * var(--index) - 90deg);
+}
+

package/src/spacing/fluid.css

@@ -0,0 +1,72 @@
+/**
+ * --fluid() — Fluid Viewport-Based Sizing
+ *
+ * Generates a clamp() value that scales smoothly between viewport widths.
+ * Use this for global, viewport-dependent responsive sizing.
+ *
+ * @param {length} --min - Minimum size
+ * @param {length} --max - Maximum size
+ * @param {length} --min-vw - Minimum viewport width, default: 375px
+ * @param {length} --max-vw - Maximum viewport width, default: 1440px
+ * @returns {length} - Fluid clamp value based on viewport width
+ *
+ * @example
+ * h1 {
+ *   font-size: --fluid(1.5rem, 4rem);
+ * }
+ * .container {
+ *   padding: --fluid(1rem, 3rem, 320px, 1200px);
+ * }
+ *
+ * @see --fluid-container() for container-based fluid sizing
+ */
+
+@function --fluid(
+  --min <length>,
+  --max <length>,
+  --min-vw <length>: 375px,
+  --max-vw <length>: 1440px
+) returns <length> {
+  --slope: calc((var(--max) - var(--min)) / (var(--max-vw) - var(--min-vw)));
+  --intercept: calc(var(--min) - var(--slope) * var(--min-vw));
+  result: clamp(var(--min), calc(var(--intercept) + var(--slope) * 100vw), var(--max));
+}
+
+/**
+ * --fluid-container() — Fluid Container-Based Sizing
+ *
+ * Generates a clamp() value that scales smoothly based on container width.
+ * Requires the parent element to have container-type: inline-size or container: name / inline-size.
+ * Perfect for component-level responsive design independent of viewport size.
+ *
+ * @param {length} --min - Minimum size
+ * @param {length} --max - Maximum size
+ * @param {length} --min-cqw - Minimum container width, default: 20ch
+ * @param {length} --max-cqw - Maximum container width, default: 65ch
+ * @returns {length} - Fluid clamp value based on container width
+ *
+ * @example
+ * .card {
+ *   container-type: inline-size;
+ * }
+ *
+ * .card h2 {
+ *   font-size: --fluid-container(1rem, 2rem);
+ * }
+ *
+ * .card p {
+ *   font-size: --fluid-container(0.875rem, 1.125rem, 30ch, 60ch);
+ * }
+ */
+
+@function --fluid-container(
+  --min <length>,
+  --max <length>,
+  --min-cqw <length>: 20ch,
+  --max-cqw <length>: 65ch
+) returns <length> {
+  --slope: calc((var(--max) - var(--min)) / (var(--max-cqw) - var(--min-cqw)));
+  --intercept: calc(var(--min) - var(--slope) * var(--min-cqw));
+  result: clamp(var(--min), calc(var(--intercept) + var(--slope) * 100cqw), var(--max));
+}
+

package/src/spacing/ratio-height.css

@@ -0,0 +1,29 @@
+/**
+ * --ratio-height() — Aspect Ratio Height
+ *
+ * Calculate height from width and aspect ratio (useful for images/containers).
+ *
+ * @param {length} --width - Element width
+ * @param {number} --ratio-w - Ratio width part, default: 16
+ * @param {number} --ratio-h - Ratio height part, default: 9
+ * @returns {length} - Calculated height
+ *
+ * @example
+ * .video-thumb {
+ *   width: 320px;
+ *   height: --ratio-height(320px, 16, 9);
+ * }
+ * .square-avatar {
+ *   width: 48px;
+ *   height: --ratio-height(48px, 1, 1);
+ * }
+ */
+
+@function --ratio-height(
+  --width <length>,
+  --ratio-w <number>: 16,
+  --ratio-h <number>: 9
+) returns <length> {
+  result: calc(var(--width) * var(--ratio-h) / var(--ratio-w));
+}
+

package/src/spacing/space.css

@@ -0,0 +1,30 @@
+/**
+ * --space() — Spacing Scale
+ *
+ * Returns spacing based on a consistent multiplier scale.
+ * The base unit can be customized via the --space-base CSS custom property.
+ *
+ * @param {number} --multiplier - Scale multiplier
+ * @param {length} --base - Base spacing unit, default: var(--space-base, 0.25rem)
+ * @returns {length} - Calculated spacing
+ *
+ * @example
+ * :root {
+ *   --space-base: 0.25rem;
+ * }
+ *
+ * .card {
+ *   padding: --space(4);
+ *   margin-bottom: --space(6);
+ *   gap: --space(2);
+ * }
+ *
+ * .special {
+ *   padding: --space(4, 0.5rem);
+ * }
+ */
+
+@function --space(--multiplier <number>, --base <length>: var(--space-base, 0.25rem)) returns <length> {
+  result: calc(var(--base) * var(--multiplier));
+}
+

package/src/units/to-px.css

@@ -0,0 +1,19 @@
+/**
+ * --to-px() — REM to Pixel Conversion
+ *
+ * Convert a rem value to pixels (assumes 16px base).
+ *
+ * @param {number} --rem - REM value (unitless)
+ * @returns {length} - Pixel value
+ *
+ * @example
+ * .legacy-system {
+ *   width: --to-px(10);
+ *   height: --to-px(5);
+ * }
+ */
+
+@function --to-px(--rem <number>) returns <length> {
+  result: calc(var(--rem) * 16 * 1px);
+}
+

package/src/units/to-rem.css

@@ -0,0 +1,28 @@
+/**
+ * --to-rem() — Pixel to REM Conversion
+ *
+ * Convert a pixel value to rem units. Base pixel size defaults to --rem-base (or 16px).
+ *
+ * @param {number} --px - Pixel value (unitless)
+ * @param {number} --base - Base pixel size for conversion, defaults to var(--rem-base, 16)
+ * @returns {length} - REM value
+ *
+ * @example
+ * .legacy-compat {
+ *   font-size: --to-rem(18);
+ *   padding: --to-rem(24);
+ * }
+ *
+ * .custom-base {
+ *   font-size: --to-rem(18, 10);
+ * }
+ *
+ * :root {
+ *   --rem-base: 20;
+ * }
+ */
+
+@function --to-rem(--px <number>, --base <number>: var(--rem-base, 16)) returns <length> {
+  result: calc(var(--px) * 1rem / var(--base));
+}
+