@material/web 0.1.0-alpha.0

package/compat/theme/_keys.scss

@@ -0,0 +1,507 @@
+//
+// Copyright 2022 Google LLC
+// SPDX-License-Identifier: Apache-2.0
+//
+
+@use 'sass:list';
+@use 'sass:map';
+@use 'sass:meta';
+@use 'sass:string';
+@use './custom-properties';
+
+/// A flat Map of keys and their values. Keys may be set to any static CSS
+/// value, or another key's name to resolve to that key's value.
+///
+/// @example - scss
+///   $_store: (
+///     primary: purple, // keys may be set to CSS values...
+///     button-color: primary, // ...or resolve to another key's value
+///   );
+///
+/// @type {Map}
+$_store: ();
+/// A flat Map of relationship links between keys. While key values may
+/// resolve to another key's value in the key store, the store does not
+/// preserve or infer relationships between keys.
+///
+/// Instead, this link Map records the original relationship between keys as
+/// their values are updated and potentially overridden with customizations.
+///
+/// @example - scss
+///   // Given these keys...
+///   $primary: purple;
+///   $button-color: $primary; // ...button-color is linked to the primary key
+///
+///   // A key store with value customizations may look like this:
+///   $_store: (
+///     primary: amber,
+///     button-color: teal, // the relationship is lost with a customization
+///   );
+///
+///   // The links Map preserves the relationship for custom property
+///   // generation, while the store Map is only focused on values.
+///   $_links: (
+///     button-color: primary,
+///   );
+///
+/// @type {Map}
+$_links: ();
+/// A map of key options. If a key has options, it will have an entry in this
+/// variable with a Map value with options for the key.
+///
+/// @example - scss
+///   // Option structure
+///   $_options: (
+///     key-name: (
+///       // An additional prefix to add when generating the varname of a
+///       // key's custom property
+///       // --mdc-<prefix>-key-name
+///       custom-property-prefix: prefix
+///     )
+///   );
+///
+/// @type {Map}
+$_options: ();
+
+/// Indicates whether or not the provided value is a registered key.
+///
+/// @param {String} $key - One or more key parts to check
+/// @return {Bool} True if the key is registered, or false if it is not.
+@function is-key($key...) {
+  $key: combine($key...);
+  @return map.has-key($_store, $key);
+}
+
+/// Retrieves a List of all keys matching the provided key group prefix.
+///
+/// @example - scss
+///   $keys: get-keys(typography);
+///   // (typography-headline,
+///   //  typography-body,
+///   //  typography-body-font,
+///   //  typography-body-size)
+///
+/// @param {String} $group - Optional group prefix to search by. If ommitted,
+///     all registered keys will be returned.
+/// @return {List} A List of all keys matching the group prefix.
+@function get-keys($group: '') {
+  $keys: ();
+  @each $key in map.keys($_store) {
+    @if string.index($key, $group) == 1 {
+      $keys: list.append($keys, $key);
+    }
+  }
+
+  @return $keys;
+}
+
+/// Registers a Map of keys and their values with the key store. Key values may
+/// either be CSS values or other key strings.
+///
+/// @example - scss
+///   @include set-values((
+///     primary: teal,
+///     label-color: primary
+///   ));
+///
+/// Options may also be added for each key by providing an `$options` parameter.
+///
+/// @example - scss
+///   @include set-values(
+///     $key-map,
+///     $options: (
+///       // An additional prefix to add when generating the varname of a
+///       // key's custom property
+///       // --mdc-<prefix>-key-name
+///       custom-property-prefix: prefix
+///     )
+///   );
+///
+/// Note that this mixin only sets key values. If a key points to another key,
+/// it does not link those keys when custom properties are emitted. Use
+/// `add-link()` or `register-theme()` to create links between keys.
+///
+/// @see {mixin} set-value
+/// @see {mixin} add-link
+/// @see {mixin} register-theme
+///
+/// @param {Map} $key-map - A Map of keys to register.
+/// @param {Map} $options [null] - Optional Map of options to add for each key.
+@mixin set-values($key-map, $options: null) {
+  $unused: set-values($key-map, $options: $options);
+}
+
+/// Function version of `set-values()`.
+///
+/// Mixins cannot be invoked within functions in Sass. Use this when
+/// `set-values()` must be used within a function. The return value may be
+/// discarded or re-assigned to the `$key-map` provided.
+///
+/// @example - scss
+///   @function foo() {
+///     $unused: set-values((primary: teal));
+///   }
+///
+///   @function bar() {
+///     $key-map: (primary: teal);
+///     $key-map: set-values($key-map);
+///   }
+///
+/// @see {mixin} set-values
+///
+/// @return {Map} `$key-map`, unmodified, for convenience.
+@function set-values($key-map, $options: null) {
+  @each $key, $value in $key-map {
+    $key: set-value($key, $value, $options: $options);
+  }
+
+  @return $key-map;
+}
+
+/// Sets the value of a key. Key values may either be CSS values or other key
+/// strings.
+///
+/// @example - scss
+///   @include set-value(primary, teal);
+///   @include set-value(label-color, primary);
+///
+/// Options may also be added for each key by providing an `$options` parameter.
+///
+/// @example - scss
+///   @include set-value(key-name, teal, $options: (
+///     // An additional prefix to add when generating the varname of a
+///     // key's custom property
+///     // --mdc-<prefix>-key-name
+///     custom-property-prefix: prefix
+///   ));
+///
+/// Note that this mixin only sets the key's value. If the key points to another
+/// key, it does not link those keys when custom properties are emitted. Use
+/// `add-link()` or `register-theme()` to create links between keys.
+///
+/// @see {mixin} add-link
+/// @see {mixin} register-theme
+///
+/// @param {String} $key - The key to set a value for.
+/// @param {*} $value - The value of the key.
+/// @param {Map} $options [null] - Optional Map of options to add for each key.
+@mixin set-value($key, $value, $options: null) {
+  $unused: set-value($key, $value, $options: $options);
+}
+
+/// Function version of `set-value()`.
+///
+/// Mixins cannot be invoked within functions in Sass. Use this when
+/// `set-value()` must be used within a function. The return value may be
+/// discarded or re-assigned to the `$key` provided.
+///
+/// @example - scss
+///   @function foo() {
+///     $unused: set-value(primary, teal);
+///   }
+///
+///   @function bar() {
+///     $key: primary;
+///     $key: set-value($key, teal);
+///   }
+///
+/// @see {mixin} set-value
+///
+/// @return {String} `$key`, unmodified, for convenience.
+@function set-value($key, $value, $options: null) {
+  // Use !global to avoid shadowing
+  // https://sass-lang.com/documentation/variables#shadowing
+  $_store: map.set($_store, $key, $value) !global;
+  @if $options {
+    $_options: map.set($_options, $key, $options) !global;
+  }
+
+  @return $key;
+}
+
+/// Add a link between two keys.
+///
+/// When keys are linked and chained custom properties are emitted, the value
+/// of `$key` will always include the `var()` function of its linked key, even
+/// if it overrides its linked key's value.
+///
+/// @example - scss
+///   @include add-link(label-color, primary);
+///   @include set-values((
+///     primary: teal,
+///     label-color: amber
+///   ));
+///
+///   .primary {
+///     @include theme.property(color, primary);
+///   }
+///
+///   .label-color {
+///     @include theme.property(color, label-color);
+///   }
+///
+/// @example - css
+///   .primary {
+///     color: var(--primary, teal);
+///   }
+///
+///   .label-color {
+///     color: var(--label-color, var(--primary, amber));
+///   }
+///
+///
+/// If a key does not already have a value set, its value will be set to the
+/// linked key provided.
+///
+/// @param {String} $key - The key to add a link to.
+/// @param {String} $link - The name to link to `$key`.
+/// @throw When attempting to change the link of a key that has already been
+///     linked.
+@mixin add-link($key, $link) {
+  $unused: add-link($key, $link);
+}
+
+/// Function version of `add-link()`.
+///
+/// Mixins cannot be invoked within functions in Sass. Use this when
+/// `add-link()` must be used within a function. The return value may be
+/// discarded or re-assigned to the `$key` provided.
+///
+/// @example - scss
+///   @function foo() {
+///     $unused: add-link(label-color, primary);
+///   }
+///
+///   @function bar() {
+///     $key: label-color;
+///     $key: set-value($key, primary);
+///   }
+///
+/// @see {mixin} `add-link()`
+///
+/// @return {String} `$key` for convenience.
+@function add-link($key, $link) {
+  @if map.has-key($_links, $key) {
+    @error '#{$key} already has a link';
+  }
+
+  // Use !global to avoid shadowing
+  // https://sass-lang.com/documentation/variables#shadowing
+  $_links: map.set($_links, $key, $link) !global;
+  @if not map.has-key($_store, $key) {
+    $key: set-value($key, $link);
+  }
+
+  @return $key;
+}
+
+/// Resolve a key to its CSS value. This may be a static CSS value or a dynamic
+/// `var()` value.
+///
+/// The value that this function returns may change depending on configuration
+/// options if a key's value points to another key.
+///
+/// To always retrieve the static CSS value a key resolves to, even if it points
+/// to another key, provide `$deep: true` as a parameter to the function.
+///
+/// @param {String...} $key - One or more key parts to resolve to a CSS value.
+/// @param {Bool} $deep [false] - Set to true as a named parameter to always
+///     resolve the key to its static CSS value and not a dynamic `var()` value.
+/// @return {*} The value the key resolves to. This may be `null` if the key
+///     (or the key it points to) has not been registered.
+@function resolve($key...) {
+  $deep: map.get(meta.keywords($key), deep);
+  $key: combine($key...);
+
+  $value: map.get($_store, $key);
+  @if is-key($value) {
+    $value: resolve($value);
+  }
+
+  @return $value;
+}
+
+/// Register a `$theme` Map variable's keys. This should only be done once in
+/// the `theme-styles()` mixin with the canonical `$theme` Map to initialize
+/// default values and linked keys.
+///
+/// @example - scss
+///   @mixin theme-styles($theme: button-filled-theme.$light-theme) {
+///     @include keys.register-theme($theme, button-filled);
+///     @include button-filled-theme.theme($theme);
+///   }
+///
+/// A component's `$theme` Map may have shared keys (such as color, shape, and
+/// typography) that need linked before user customization with the `theme()`
+/// mixin.
+///
+/// The `register-theme()` mixin handles adding these links with `add-link()`
+/// dynamically from a canonical `$theme` configuration provided by a trusted
+/// source in `theme-styles()`. Subsequent calls to `theme()` will not invoke
+/// `register-theme()` or change the linked keys' registration.
+///
+/// @param {Map} $theme - The theme Map to register keys for.
+/// @param {String} $prefix [null] - Optional prefix to prepend before each key.
+/// @param {Map} $options [null] - Optional Map of options to add for each key.
+@mixin register-theme($theme, $prefix: null, $options: null) {
+  // The first $theme Map received in theme-styles() should be used to
+  // register keys.
+  // Subsequent calls to theme() to customize key values will not be
+  // wrapped within theme-styles() and will not change the registered
+  // key values (or more importantly, their links), since
+  // customizations may be simple one-offs.
+  @each $key, $value in $theme {
+    @if $value != null {
+      $key: combine($prefix, $key);
+      @include set-value($key, $value, $options: $options);
+      @if is-key($value) {
+        @include add-link($key, $link: $value);
+      }
+    }
+  }
+}
+
+/// Create and resolve custom properties from a user-provided `$theme` Map
+/// variable. The created custom properties are returned in a Map that matches
+/// the key structure of `$theme`.
+///
+/// This function should be used within a `theme()` mixin after validation and
+/// before providing any values to subsequent mixins. This will ensure that all
+/// values are custom properties to support runtime theming.
+///
+/// @example - scss
+///   $light-theme: (
+///     label-color: on-primary
+///   );
+///
+///   @mixin theme($theme) {
+///     $theme: keys.create-theme-properties($theme, button-filled);
+///     /*(
+///       label-color: (
+///         varname: --mdc-button-filled-label-color,
+///         fallback: (
+///           varname: --mdc-theme-on-primary,
+///           fallback: white,
+///         )
+///       )
+///     )*/
+///   }
+///
+/// @param {Map} $theme - The theme Map to create custom properties for.
+/// @param {String} $prefix [null] - Optional prefix to prepend for each key's
+///     custom property.
+/// @return {Map} A similar `$theme` Map whose values are replaced with the
+///     newly created and resolved custom properties.
+@function create-theme-properties($theme, $prefix: null) {
+  $theme-with-props: ();
+  @each $name, $value in $theme {
+    @if $value != null {
+      @if is-key($value) {
+        $value: create-custom-property($value);
+      }
+
+      $key: combine($prefix, $name);
+
+      @if _is-map($value) {
+        @each $k, $v in $value {
+          $theme-with-props: map.set(
+            $theme-with-props,
+            $name,
+            $k,
+            custom-properties.create(_create-varname(combine($key, $k)), $v)
+          );
+        }
+      } @else {
+        $theme-with-props: map.set(
+          $theme-with-props,
+          $name,
+          custom-properties.create(_create-varname($key), $value)
+        );
+      }
+    }
+  }
+
+  @return $theme-with-props;
+}
+
+/// Create a custom property for a key that represents the key's linked
+/// relationships and final resolved static value.
+///
+/// This function ignores customization options and is intended to return the
+/// most accurate data structure representation of a key. Customization options
+/// (such as custom property configuration) will change how the returned value
+/// is emitted.
+///
+/// @param {$tring...} $key - One or more key parts to create a custom property
+///     for.
+/// @return {Map} A custom property Map for the key.
+@function create-custom-property($key...) {
+  $key: combine($key...);
+  $prop: custom-properties.create(_create-varname($key));
+  $link: map.get($_links, $key);
+  @if $link {
+    $prop: custom-properties.set-fallback($prop, create-custom-property($link));
+  }
+
+  @return custom-properties.set-fallback($prop, resolve($key, $deep: true));
+}
+
+@mixin declare-custom-properties($theme, $prefix: null) {
+  $theme: create-theme-properties($theme, $prefix);
+
+  @each $key, $value in $theme {
+    @if _is-map($value) {
+      @each $k, $v in $value {
+        @include custom-properties.declaration($v);
+      }
+    } @else {
+      @include custom-properties.declaration($value);
+    }
+  }
+}
+
+/// Creates a custom property varname for a key. This function will add a key's
+/// option's `custom-property-prefix` if it exists.
+///
+/// @param {String...} $key - One or more key parts to create a varname for.
+/// @return {String} The key's custom property varname.
+@function _create-varname($key...) {
+  $key: combine($key...);
+  $prefix: map.get($_options, $key, custom-property-prefix);
+  @if $prefix {
+    $key: combine($prefix, $key);
+  }
+
+  @return custom-properties.create-varname($key);
+}
+
+/// Combines one or more key parts into a key.
+///
+/// @example - scss
+///   $key: combine(body, font-size);
+///   // body-font-size
+///
+/// @param {String...} $parts - Arbitrary number of string key parts to combine.
+/// @return {String} A combined key string.
+@function combine($parts...) {
+  // Allow extra keywords to be passed to other functions without impacting this
+  // function, which does not expect any keywords.
+  $unused: meta.keywords($parts);
+  $key: '';
+  @each $part in $parts {
+    @if $part {
+      @if $key == '' {
+        $key: $part;
+      } @else {
+        $key: #{$key}-#{$part};
+      }
+    }
+  }
+
+  @return $key;
+}
+
+@function _is-map($map) {
+  @return meta.type-of($map) == 'map' and not
+    custom-properties.is-custom-prop($map);
+}

package/compat/theme/_map-ext.scss

@@ -0,0 +1,68 @@
+//
+// Copyright 2022 Google LLC
+// SPDX-License-Identifier: Apache-2.0
+//
+
+@use 'sass:list';
+@use 'sass:map';
+
+// A collection of extensions to the sass:map module
+// https://sass-lang.com/documentation/modules/map
+
+/// Splits a Map into two separate Maps: one without the provided keys and one
+/// exclusively with the provided keys.
+///
+/// @example - scss
+///   $map: (
+///     focus: blue,
+///     focus-within: blue,
+///     hover: teal,
+///     active: green,
+///   );
+///
+///   $pair: split($map, focus, focus-within);
+///   // (
+///   //   (hover: teal, active: green),
+///   //   (focus: blue, focus-within: blue)
+///   // );
+///
+/// @param {Map} $map - The Map to split.
+/// @param {String...} $keys - Keys to split the Map by.
+/// @return {List} A List pair with two new Maps: the first with the keys
+///     removed and the second exclusively with the keys.
+@function split($map, $keys...) {
+  $map1: ();
+  $map2: ();
+  @each $key, $value in $map {
+    @if list.index($keys, $key) {
+      $map2: map.set($map2, $key, $value);
+    } @else {
+      $map1: map.set($map1, $key, $value);
+    }
+  }
+
+  @return ($map1, $map2);
+}
+
+/// Picks provided keys from a Map.
+///
+/// @example - scss
+///   $map: (
+///     focus: blue,
+///     focus-within: blue,
+///     hover: teal,
+///     active: green,
+///   );
+///
+///   pick($map, hover, active);
+///   // (hover: teal, active: green),
+///
+///   pick($map, (hover, active)...);
+///   // (hover: teal, active: green),
+///
+/// @param {Map} $map - The Map to pick.
+/// @param {String...} $keys - Keys to pick from the Map.
+/// @return {List} Map with only the keys provided.
+@function pick($map, $keys...) {
+  @return list.nth(split($map, $keys...), 2);
+}

package/compat/theme/_replace.scss

@@ -0,0 +1,108 @@
+//
+// Copyright 2022 Google LLC
+// SPDX-License-Identifier: Apache-2.0
+//
+
+@use 'sass:list';
+@use 'sass:meta';
+@use 'sass:string';
+
+/// Replaces all name instances in the provided string with values from the
+/// provided replacement Map whose keys correspond to the name instances.
+/// Returns a new string with the replacements applied.
+///
+/// @example
+///   replace-string('calc(x + y)', (x: 16px, y: 50%)); // 'calc(16px + 50%)'
+///
+/// @example
+///   $foo: custom-properties.create-var(custom-properties.create(--foo, 8px));
+///   replace-string('calc(foo)', (foo: $foo)); // 'calc(var(--foo, 8px))';
+///
+/// @access private
+/// @param {String} $string - The string to make replacements on.
+/// @param {Map} $replace-map - A Map of name/value replacements. The keys of
+///     the Map are names that will be replaced in the string with the keys'
+///     respective values.
+/// @return {String} The string with replacements made, if any.
+@function replace-string($string, $replace-map) {
+  @if meta.type-of($replace-map) != 'map' {
+    @error 'mdc-theme: Invalid replacement #{$replace-map}. Must be a Map.';
+  }
+
+  @each $name, $replacement in $replace-map {
+    // Since the replacement values may contain the name themselves (such as
+    // a custom property: name "foo" and value "var(--foo)"), gather the indices
+    // first before replacing.
+    $indices: ();
+    $substring: $string;
+    $prev-index: null;
+    $index: string.index($substring, $name);
+    @while $index {
+      $substring: string.slice($substring, $index + string.length($name));
+
+      @if $prev-index {
+        // Add previous index's value to switch from "substring index" to
+        // absolute string index. Also add length - 1 since slice removes
+        // the entire word as well as lists being 1 indexed
+        $index: $index + $prev-index + string.length($name) - 1;
+      }
+
+      // Use list.join() to "prepend" the index to the start of the list. This
+      // allows us to iterate "backwards" later.
+      $indices: list.join($index, $indices);
+      $prev-index: $index;
+      $index: string.index($substring, $name);
+    }
+
+    // Since we "prepended" the indices, the list is sorted backwards, with the
+    // last index first. Replacing values last index to first index removes the
+    // need for us to adjust the indices as we replace them.
+    @each $index in $indices {
+      $before: string.slice($string, 1, $index - 1);
+      $after: string.slice($string, $index + string.length($name));
+      $string: $before + $replacement + $after;
+    }
+  }
+
+  @return $string;
+}
+
+/// Replaces all value instances in the provided list with values from the
+/// provided replacement Map whose keys correspond to the name instances.
+/// Returns a new list with the replacements applied.
+///
+/// @example
+///   replace-list(0 value, (value: 16px)); // (0 16px)
+///
+/// @see {mixin} replace-string
+///
+/// @access private
+/// @param {List} $list - The list to make replacements on.
+/// @param {Map} $replace-map - A Map of name/value replacements. The keys of
+///     the Map are names that will be replaced in the list with the keys'
+///     respective values.
+///     property value replacements instead of the `var()` declaration.
+/// @return {List} A new list with replacements made, if any.
+@function replace-list($list, $replace-map) {
+  $separator: list.separator($list);
+  $replaced-list: ();
+  @each $value in $list {
+    @if meta.type-of($value) == 'string' {
+      $replaced-list: list.append(
+        $replaced-list,
+        replace-string($value, $replace-map),
+        $separator
+      );
+    } @else if meta.type-of($value) == 'list' {
+      $replaced-list: list.append(
+        $replaced-list,
+        replace-list($value, $replace-map),
+        $separator
+      );
+    } @else {
+      $replaced-list: list.append($replaced-list, $value, $separator);
+    }
+  }
+
+  @return $replaced-list;
+}