material-web/sass/_elevation.scss

//
// Copyright 2021 Google LLC
// SPDX-License-Identifier: Apache-2.0
//

// go/keep-sorted start
@use 'sass:map';
@use 'sass:meta';
// go/keep-sorted end
// go/keep-sorted start
@use './color';
@use './var';
// go/keep-sorted end

/// Returns the appropriate elevation theme for the given args.
///
/// @throw If elevation or shadow color is provided and the other is null.
/// @throw If a required resolver is missing.
/// @param {Number} $elevation - The elevation in dp.
/// @param {Color} $shadow-color - The elevation's shadow color.
/// @param {Map} $resolvers - Sass resolvers map. Requires `elevation-dp`,
///     `elevation-shadow`, and `elevation-overlay-opacity` resolvers.
/// @return {Map} The resolved elevation theme with a `shadow` box-shadow and
///     `overlay-opacity` for the given elevation and shadow color.
@function resolver($args...) {
  $args: meta.keywords($args);

  $dp: map.get($args, elevation);
  $level: _resolve-dp($dp);
  $shadow-color: map.get($args, shadow-color);

  @return (
    shadow: _resolve-box-shadow($level, $shadow-color),
    overlay-opacity: _resolve-overlay-opacity($level)
  );
}

/// Maps elevation dps to elevation levels.
$_dp-to-level-map: (
  // TODO: pull the keys from tokens
  0: 0,
  1: 1,
  3: 2,
  6: 3,
  8: 4,
  12: 5
);

/// Returns the appropriate elevation level for a given dp.
///
/// @throw If the provided dp does not map to an elevation level.
/// @param {Number} $dp - The dp to convert to an elevation level.
/// @return {Number} The level of the elevation system, or null if the dp is
///     null.
@function _resolve-dp($dp) {
  @if $dp == null {
    @return null;
  }

  $level: map.get($_dp-to-level-map, $dp);
  @if $level == null {
    @error '#{$dp} is not a valid elevation dp level. Must be one of #{map.keys($_dp-to-level-map)}.';
  }

  @return $level;
}

// TODO: pull these values from tokens
$_key-opacity: 0.3;
$_ambient-opacity: 0.15;
$_shadow-map: (
  0: (
    key: '0px 0px 0px 0px',
    ambient: '0px 0px 0px 0px',
  ),
  1: (
    key: '0px 1px 2px 0px',
    ambient: '0px 1px 3px 1px',
  ),
  2: (
    key: '0px 1px 2px 0px',
    ambient: '0px 2px 6px 2px',
  ),
  3: (
    key: '0px 1px 3px 0px',
    ambient: '0px 4px 8px 3px',
  ),
  4: (
    key: '0px 2px 3px 0px',
    ambient: '0px 6px 10px 4px',
  ),
  5: (
    key: '0px 4px 4px 0px',
    ambient: '0px 8px 12px 6px',
  ),
);

/// Returns the appropriate box-shadow for the given level and shadow color.
///
/// @throw If level or shadow-color are provided and one is null.
/// @param {Number} $level - The level of the elevation system.
/// @param {Color} $shadow-color - The color of the shadow.
/// @return {List|String} - The constructed box-shadow, none (for elevation 0),
///     or null
@function _resolve-box-shadow($level, $shadow-color) {
  @if $level == null and $shadow-color == null {
    @return null;
  }

  @if $level == 0 {
    @return none;
  }

  @if $level == null {
    @error '$elevation is required when $shadow-color is provided';
  }

  @if $shadow-color == null {
    @error '$shadow-color is required when $elevation is provided';
  }

  $key-spread: map.get($_shadow-map, $level, key);
  $ambient-spread: map.get($_shadow-map, $level, ambient);

  $key-color: rgba($shadow-color, $_key-opacity);
  $ambient-color: rgba($shadow-color, $_ambient-opacity);

  @if var.is-var($shadow-color) {
    // TODO(b/213331407): Convert color from hex to rgba CSS color format to
    // enable mixing rgb value with alpha using custom properties.
    // (e.g., rgb(var(--foo-sys-color-on-surface-rgb, 31,31,31), 0.38))
    // Remove once the attached bug is resolved.
    $key-color: color.color-var-hex-to-rgba($shadow-color, $_key-opacity);
    $ambient-color: color.color-var-hex-to-rgba(
      $shadow-color,
      $_ambient-opacity
    );
  }

  @return (#{$key-spread} #{$key-color}, #{$ambient-spread} #{$ambient-color});
}

// TODO: pull these values from tokens
$_overlay-opacity: (
  0: 0,
  1: 0.05,
  2: 0.08,
  3: 0.11,
  4: 0.12,
  5: 0.14,
);

/// Returns the appropriate overlay opacity for the given level.
///
/// @param {Number} $level - The level of the elevation system.
/// @return {Number} The opacity or null.
@function _resolve-overlay-opacity($level) {
  @return map.get($_overlay-opacity, $level);
}