// RIVER Design-System: System - Functions / Utilities //

// Functionality for interacting with our design system utilities.


// UTILITIES
// Update utilities

// Get the design utilities
@function design-utilities() {
    @return $design-utilities;
}

// Set new design utilities based on the given utilities map
// This clears the existing utilities completely
// NOTE, you need to update the existing $design-utilities with the updated utilities returned
// eg, $design-utilities: design-utilities-set((...));
@function design-utilities-set($utilitiesMap: ()) {
    // Validate
    @if(
        not(type-of($utilitiesMap) == 'map')
        and not(type-of($utilitiesMap) == 'list' and length($utilitiesMap) == 0)
    ) {
        @error("design-utilities-set() invalid utilities map");
    }

    // Return new map as-is
    @return $utilitiesMap;
}

// Add new utilities to the utilities map, and override existing utilities.
// NOTE, you need to update the existing $design-utilities with the updated utilities returned
// eg, $design-utilities: design-utilities-add((...));
@function design-utilities-add($utilitiesMap: ()) {
    // Validate
    @if(not(type-of($utilitiesMap) == 'map')) {
        @error("design-utilities-add() invalid utilities map");
    }

    // Merge in
    $design-utilities: map-merge(
        design-utilities(),
        $utilitiesMap
    );

    @return $design-utilities;
}

// Apply new utilities to the existing utilities map
// This returns the updated list of utilities, and needs to be called as:
// $design-utilities: design-utilities-apply(...)
// eg, $design-utilities: design-utilities-apply(( 'color': ..., 'type': ... ));
// This merges in your defined utilities, so you only need to define what you want to update.
@function design-utilities-apply($utilitiesMap: ()) {
    // Note the current utilities
    $utilities: design-utilities();

    // Validate
    @if(length($utilitiesMap) == 0) {
        @warn("design-utilities-apply() an empty list was provided");
        @return $utilities;
    }
    @if(not(type-of($utilitiesMap) == 'map')) {
        @error("design-utilities-apply() invalid utilities map");
    }

    // Loop through each utility to update
    @each $utility, $values in $utilitiesMap {
        // Apply and extend the new utilities
        @if(map-has-key($utilities, $utility)) {
            $values: map-merge(map-get($utilities, $utility), $values);
        }
        $utilities: map-set($utilities, $utility, $values);
    }

    @return $utilities;
}

// Normalise utititlities for output
// This merges in default utility settings to ensure utility mixins run correctly
@function design-utilities-normalise($utilityName, $utilitySettings) {
    // Update the utility settings to apply all defaults
    // Defaults are taken from $design-settings for 'utilities'
    $utilitySettingsNormalised: (
        name:                   $utilityName,
        enabled:                if(map-has-key($utilitySettings, 'enabled'), map-get($utilitySettings, 'enabled'), design-setting('utilities.enabled', false)),
        properties:             map-get($utilitySettings, 'properties'),
        values:                 map-get($utilitySettings, 'values'),
        responsive:             if(map-has-key($utilitySettings, 'responsive'), map-get($utilitySettings, 'responsive'), design-setting('utilities.responsive', false)),
        responsiveAt:           if(map-has-key($utilitySettings, 'responsiveAt'), map-get($utilitySettings, 'responsiveAt'), design-setting('utilities.responsiveAt', false)),
        responsiveDown:         if(map-has-key($utilitySettings, 'responsiveDown'), map-get($utilitySettings, 'responsiveDown'), design-setting('utilities.responsiveDown', false)),
        states:                 if(map-has-key($utilitySettings, 'states'), map-get($utilitySettings, 'states'), design-setting('utilities.states', false)),
        media:                  if(map-has-key($utilitySettings, 'media'), map-get($utilitySettings, 'media'), design-setting('utilities.media', false)),
        calculation:            if(map-has-key($utilitySettings, 'calculation'), map-get($utilitySettings, 'calculation'), design-setting('utilities.calculation', false)),
        important:              if(map-has-key($utilitySettings, 'important'), map-get($utilitySettings, 'important'), design-setting('utilities.important', false)),
        importantVariation:     if(map-has-key($utilitySettings, 'importantVariation'), map-get($utilitySettings, 'importantVariation'), design-setting('utilities.importantVariation', false)),
        valuePrefix:            if(map-has-key($utilitySettings, 'valuePrefix'), map-get($utilitySettings, 'valuePrefix'), design-setting('utilities.valuePrefix', false)),
        valueSuffix:            if(map-has-key($utilitySettings, 'valueSuffix'), map-get($utilitySettings, 'valueSuffix'), design-setting('utilities.valueSuffix', false)),
        defaultValue:           if(map-has-key($utilitySettings, 'defaultValue'), map-get($utilitySettings, 'defaultValue'), design-setting('utilities.defaultValue', false)),
        includeRange:           if(map-has-key($utilitySettings, 'includeRange'), map-get($utilitySettings, 'includeRange'), design-setting('utilities.includeRange', false)),
        includeXero:            if(map-has-key($utilitySettings, 'includeXero'), map-get($utilitySettings, 'includeXero'), design-setting('utilities.includeXero', false)),
    );

    // Return the normalised utility settings
    @return $utilitySettingsNormalised;
}