_theme-accessor.scss

/*
 * FILE: _theme-accessor.scss
 *
 * This file contains a function and configurations for accessing theme tokens.
 * It includes a function for retrieving CSS variables based on the theme
 * configuration.
 * 
 * FUNCTION:
 * - get: Retrieves the CSS variable for a given property and value.
 *
 * VARIABLES:
 * - $exception-property-names: Maps property names to their exceptions.
 * - $exception-order: Defines the categorization and order of properties to
 *   be listed.
 * - $exception-exclude-base-suffix: List of tokens excluding the base suffix
 *   from CSS custom property names.
 * - $exception-utility-properties: Defines exceptions for certain properties,
 *   allowing alternative names and modifications to the property.
 *
 * Ensure any changes to property names in $exception-property-names are also
 * reflected in $exception-order to maintain consistency.
 *
 * Ensure group properties are set to their token keys for specific groups
 * to allow access to their values, especially when they share properties
 * with other keys or lack assigned properties.
 */

// Import theme configuration and tokens
@use "../00-settings/theme-config" as config;
@use "../20-mixins/theme-applier" as applier;
@use "../00-settings/color-theme" as color;

// Import helper functions
@use "../10-functions/helpers/handle-string" as help-str;
@use "../10-functions/helpers/handle-list" as help-lst;

// Define property name exceptions
$exception-property-names: (
  "background-color": "background",
  "box-shadow": "box-shadow",
  "margin": "spacing",
  "padding": "spacing",
  "border-radius": "radius",
);

// Define the categorization and order of properties to be listed
$exception-order: (
  "css-properties": (
    "color",
    "background",
    "box-shadow",
    "font-size",
    "font-family",
    "font-weight",
    "line-height",
    "letter-spacing",
  ),
  "design-properties": (
    "palette",
    "spacing",
    "space-gutter",
    "space-region",
    "step-size",
    "measure",
    "radius",
  ),
);

/**
 * Function: get
 * Retrieves the CSS variable for a given property and value.
 *
 * @param {String|null} $property - The property to retrieve the CSS variable for.
 * @param {String|null} $value - The value of the property.
 * @return {String|null} - The CSS variable or null if not found.
 */
@function get($property: null, $value: null) {
  // Store the original property value
  $original-property: $property;

  // Store the original value before any modifications
  $original-value: $value;

  // Convert $value to a string if it's a number
  $value: if(type-of($value) == "number", "#{ $value }", $value);

  // Apply property name exceptions
  @if map-has-key($exception-property-names, $property) {
    $property: map-get($exception-property-names, $property);
  }

  // Collect all properties that map to a token
  $valid-properties: ();
  $property-exists: false;

  // Iterate over each group in config.$groups
  @each $group in config.$groups {
    $group-token-key: map-get($group, "key");
    $group-properties: map-get($group, "properties");

    // Ensure theme can access values instead of shadow
    @if $group-token-key == "shadow" {
      $group-properties: null;
    }

    // Skip processing if $group-properties is null
    @if $group-properties != null {
      // Handle properties based on their type
      @if type-of($group-properties) == "map" {
        $group-properties: map-keys($group-properties);
      } @else if type-of($group-properties) == "string" {
        $group-properties: ($group-properties);
      }

      // Handle exceptions for specific groups by setting group properties.
      // This ensures that certain $group-token-keys can access their values,
      // particularly when they share properties with other keys or lack
      // assigned properties.
      @if $group-token-key == "palette" {
        $group-properties: $group-token-key;
      }

      // Ensure spacing can access margin and padding properties
      @if $group-token-key == "spacing" {
        $group-properties: ("margin", "padding");
      }

      @if $group-token-key == "step-size" {
        $group-properties: $group-token-key;
      }

      @if $group-token-key == "space-gutter" {
        $group-properties: $group-token-key;
      }

      @if $group-token-key == "space-region" {
        $group-properties: $group-token-key;
      }

      @if $group-token-key == "measure" {
        $group-properties: $group-token-key;
      }

      // Apply property name exceptions to group properties
      $modified-group-properties: ();
      @each $group-property in $group-properties {
        @if map-has-key($exception-property-names, $group-property) {
          $modified-group-properties: append(
            $modified-group-properties,
            map-get($exception-property-names, $group-property)
          );
        } @else {
          $modified-group-properties: append(
            $modified-group-properties,
            $group-property
          );
        }
      }
      $group-properties: $modified-group-properties;

      // Join the properties to the valid properties list
      $valid-properties: join($valid-properties, $group-properties);

      // Check if property exists in the map or list
      $property-exists: index($group-properties, $property);

      // If the property exists, check if the value exists in the items
      @if $property-exists {
        $group-prefix: map-get($group, "prefix");
        $items: map-get(config.$theme, $group-token-key);

        // Convert color values to a string
        $value: if(type-of($value) == "color", inspect($value), $value);

        // Initialize $alt-name
        $alt-name: if(
          map-has-key(applier.$exception-utility-properties, $property),
          map-get(
            map-get(applier.$exception-utility-properties, $property),
            "alt-name"
          ),
          $property
        );

        // Store the original $alt-name
        $original-alt-name: $alt-name;

        // If the prefix is "theme", preprocess the items
        @if $group-token-key == "theme" {
          // Extract theme names from the color token map
          $themes: ();
          @each $item in map-get(color.$token, "items") {
            $theme-name: to-lower-case(map-get($item, "name"));
            $themes: append($themes, $theme-name);
          }

          // Remove theme prefixes and filter based on the passed $property value
          $processed-items: ();
          @each $item-name, $item-value in $items {
            // Remove theme prefixes from item names
            @each $theme in $themes {
              $item-name: help-str.stringReplace($item-name, "#{$theme}-", "");
            }

            // Filter items by prop matching $property or its alternate name
            $category: nth(help-str.stringToList($item-name, "-"), 1);
            $item-name: help-str.stringTrimAfter($item-name, "-", 1);
            $item-name-prop: nth(help-str.stringToList($item-name, "-"), 1);

            @if $item-name-prop == $alt-name {
              // Store the original item name with the prefix
              $processed-items: map-merge(
                $processed-items,
                (
                  "#{$category}-#{$item-name}": $item-value,
                )
              );
            }
          }
          $items: $processed-items;

          // Append suffix from $value after "-" to $alt-name
          @if $value != null and str-index($value, "-") {
            $suffix: help-str.stringTrimAfter($value, "-", 1);
            $alt-name: #{$alt-name}-#{$suffix};
            $value: nth(help-str.stringToList($value, "-"), 1);
          }
        }

        // Preprocess the value to include the prefix if necessary
        @if map-has-key($items, "#{$value}-#{$alt-name}") {
          $value: "#{$value}-#{$alt-name}";
        }

        // Main condition block
        @if $group-prefix and map-has-key($items, $value) {
          // Handle base exceptions for CSS custom properties
          @if $value ==
            "base" and
            index(applier.$exception-exclude-base-suffix, $group-token-key)
          {
            @return var(--#{$group-prefix});
          } @else {
            @return var(--#{$group-prefix}-#{$value});
          }
        } @else {
          // Extract available values without the prefix
          $available-values: ();
          @each $item-key in map-keys($items) {
            // If the group token key is "theme", trim the item key
            @if $group-token-key == "theme" {
              $available-values: append(
                $available-values,
                help-str.stringReplace($item-key, "-#{$original-alt-name}", "")
              );
            } @else {
              $available-values: append($available-values, $item-key);
            }
          }
          // Use listToString to format available values correctly
          $available-values: help-str.listToString($available-values, ", ");
          @warn "Invalid value `#{$original-value}` for property `#{$property}`. Available values are: #{$available-values}.";
          @return null;
        }
      }
    }
  }

  // If the property does not exist, print a warning message
  @if not $property-exists {
    $unique-valid-properties: help-lst.unique($valid-properties);

    // Sort the valid properties based on the exception order
    $css-properties: ();
    $design-properties: ();
    @each $exception in map-get($exception-order, "css-properties") {
      @if index($unique-valid-properties, $exception) {
        $css-properties: append($css-properties, $exception);
      }
    }
    @each $exception in map-get($exception-order, "design-properties") {
      @if index($unique-valid-properties, $exception) {
        $design-properties: append($design-properties, $exception);
      }
    }

    // Join the sorted properties with commas
    $css-properties: help-str.listToString($css-properties, ", ");
    $design-properties: help-str.listToString($design-properties, ", ");

    $unique-valid-properties: "#{$css-properties} | #{$design-properties}";

    @if $property == null {
      @warn "No property provided. Available properties are: #{$unique-valid-properties}.";
    } @else {
      @warn "Invalid property `#{$property}`. Available properties are: #{$unique-valid-properties}.";
    }
  }

  @return null;
}