Doxa provides a collection of utility functions to help with common styling calculations and transformations. These functions handle spacing, color manipulation, string operations, and map merging.
Functions for merging configuration maps, useful when combining default Doxa helpers with custom project-specific helpers.
Usage: mergeHelperMaps($doxa-helpers, $custom-helpers)
Description: Performs a shallow merge of two maps. If $custom-helpers is a valid map, it merges with $doxa-helpers. Otherwise, returns $doxa-helpers unchanged.
Example: $merged: mergeHelperMaps($doxa-helpers, $custom-helpers);
Usage: deepMergeHelperMaps($doxa-helpers, $custom-helpers)
Description: Performs a deep merge of nested maps. Useful when you need to merge complex nested configuration objects.
Example: $deep-merged: deepMergeHelperMaps($doxa-helpers, $custom-helpers);
Usage: spacer($modifier, $custom-base: 0)
Description: Calculates spacing values based on a base unit multiplied by a modifier. The default base is $base-spacing (1.2), but can be overridden with $custom-base.
Returns: A rem value
Examples:
margin-bottom: spacer(2); returns 2.4rem using default base (1.2)
padding: spacer(3, 1.6); returns 4.8rem using custom base
Functions for analyzing and manipulating colors, particularly useful for ensuring proper contrast and accessibility.
Usage: detectColorLuminance($color)
Description: Calculates the relative luminance of a color using the WCAG formula. Returns a value between 0 (darkest) and 1 (lightest).
Returns: A number representing luminance (0-1)
Example: $luminance: detectColorLuminance(#3498db); returns approximately 0.26
Usage: findColorInvert($color, $darkColorCase, $lightColorCase)
Description: Determines whether to use a dark or light color based on the luminance of a background color. Uses a threshold of 0.4 to decide.
Returns: Either $darkColorCase or $lightColorCase
Examples:
$text-color: findColorInvert(#f0f0f0, #000, #fff); returns #000 (dark text for light background)
$text-color: findColorInvert(#333, #000, #fff); returns #fff (light text for dark background)
Usage: getInnerArrowColor($backgroundColor, $darkColorCase, $lightColorCase)
Description: Determines the appropriate arrow color for a given background and returns it as a URL-encoded string suitable for SVG data URIs.
Returns: A URL-encoded color string (e.g., "%23000000")
Example: Used in SVG background images for proper contrast
Usage: powerNumber($number, $exp)
Description: Calculates a number raised to a power. Supports positive and negative exponents.
Returns: The calculated power result
Examples:
$result: powerNumber(2, 3); returns 8
$result: powerNumber(2, -2); returns 0.25
Usage: str-replace($string, $search, $replace: "")
Description: Replaces all occurrences of a substring within a string. If no replacement is provided, the substring is removed.
Returns: The modified string
Examples:
$result: str-replace("hello-world", "-", "_"); returns "hello_world"
$result: str-replace("#ff0000", "#", "%23"); returns "%23ff0000"
The following variables can be customized before importing the functions:
$base-spacing: 1.2 !default;
The base multiplier used by the spacer() function. Can be overridden in your project configuration.