@material/web 0.1.0-alpha.0 → 0.1.0-alpha.1

package/compat/theme/_keys.scss

@@ -1,507 +0,0 @@
-//
-// 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

@@ -1,68 +0,0 @@
-//
-// 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

@@ -1,108 +0,0 @@
-//
-// 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;
-}