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

package/compat/theme/_state.scss

@@ -1,752 +0,0 @@
-//
-// Copyright 2022 Google LLC
-// SPDX-License-Identifier: Apache-2.0
-//
-
-@use 'sass:list';
-@use 'sass:map';
-@use 'sass:meta';
-@use 'sass:selector';
-@use 'sass:string';
-@use './custom-properties';
-@use './selector-ext';
-
-/// List of all valid states. When adding new state functions, add the name of
-/// the state to this List.
-$_valid-states: (
-  enabled,
-  disabled,
-  dragged,
-  error,
-  focus,
-  hover,
-  opened,
-  pressed,
-  selected,
-  unselected
-);
-
-/// Retrieves the default state from the provided parameter. The parameter may
-/// be the state's default value or a state Map. A state Map has individual keys
-/// describing each state's value.
-///
-/// @example
-///   get-default-state(blue); // blue
-///   get-default-state((default: blue)); // blue
-///   get-default-state((hover: red)); // null
-///
-/// @param {*} $default-or-map - The state's default value or a state Map.
-/// @return The default state if present, or null.
-@function get-default-state($default-or-map) {
-  $state: _get-state($default-or-map, default);
-  @if $state == null and not _is-state-map($default-or-map) {
-    @return $default-or-map;
-  }
-
-  @return $state;
-}
-
-/// Retrieves the enabled state from the provided parameter. The parameter may
-/// be the state's default value or a state Map. A state Map has individual keys
-/// describing each state's value.
-///
-/// @example
-///   get-enabled-state(blue); // blue
-///   get-enabled-state((enabled: blue)); // blue
-///   get-enabled-state((hover: red)); // null
-///
-/// @param {*} $default-or-map - The state's default value or a state Map.
-/// @return The enabled state if present, or null.
-@function get-enabled-state($default-or-map) {
-  @return _get-state($default-or-map, enabled);
-}
-
-/// Retrieves the disabled state from the provided parameter. The parameter may
-/// be the state's default value or a state Map. A state Map has individual keys
-/// describing each state's value.
-///
-/// @example
-///   get-disabled-state(blue); // null
-///   get-disabled-state((disabled: red)); // red
-///   get-disabled-state((default: blue)); // null
-///
-/// @param {*} $default-or-map - The state's default value or a state Map.
-/// @return The disabled state if present, or null.
-@function get-disabled-state($default-or-map) {
-  @return _get-state($default-or-map, disabled);
-}
-
-/// Retrieves the dragged state from the provided parameter. The parameter may
-/// be the state's default value or a state Map. A state Map has individual keys
-/// describing each state's value.
-///
-/// @example
-///   get-dragged-state(blue); // null
-///   get-dragged-state((dragged: red)); // red
-///   get-dragged-state((default: blue)); // null
-///
-/// @param {*} $default-or-map - The state's default value or a state Map.
-/// @return The dragged state if present, or null.
-@function get-dragged-state($default-or-map) {
-  @return _get-state($default-or-map, dragged);
-}
-
-/// Retrieves the error state from the provided parameter. The parameter may
-/// be the state's default value or a state Map. A state Map has individual keys
-/// describing each state's value.
-///
-/// @example
-///   get-error-state(blue); // null
-///   get-error-state((error: red)); // red
-///   get-error-state((default: blue)); // null
-///
-/// @param {*} $default-or-map - The state's default value or a state Map.
-/// @return The error state if present, or null.
-@function get-error-state($default-or-map) {
-  @return _get-state($default-or-map, error);
-}
-
-/// Retrieves the focus state from the provided parameter. The parameter may
-/// be the state's default value or a state Map. A state Map has individual keys
-/// describing each state's value.
-///
-/// @example
-///   get-focus-state(blue); // null
-///   get-focus-state((focus: red)); // red
-///   get-focus-state((default: blue)); // null
-///
-/// @param {*} $default-or-map - The state's default value or a state Map.
-/// @return The focus state if present, or null.
-@function get-focus-state($default-or-map) {
-  @return _get-state($default-or-map, focus);
-}
-
-/// Retrieves the hover state from the provided parameter. The parameter may
-/// be the state's default value or a state Map. A state Map has individual keys
-/// describing each state's value.
-///
-/// @example
-///   get-hover-state(blue); // null
-///   get-hover-state((hover: red)); // red
-///   get-hover-state((default: blue)); // null
-///
-/// @param {*} $default-or-map - The state's default value or a state Map.
-/// @return The hover state if present, or null.
-@function get-hover-state($default-or-map) {
-  @return _get-state($default-or-map, hover);
-}
-
-/// Retrieves the opened state from the provided parameter. The parameter may
-/// be the state's default value or a state Map. A state Map has individual keys
-/// describing each state's value.
-///
-/// @example
-///   get-opened-state(blue); // null
-///   get-opened-state((opened: red)); // red
-///   get-opened-state((default: blue)); // null
-///
-/// @param {*} $default-or-map - The state's default value or a state Map.
-/// @return The opened state if present, or null.
-@function get-opened-state($default-or-map) {
-  @return _get-state($default-or-map, opened);
-}
-
-/// Retrieves the pressed state from the provided parameter. The parameter may
-/// be the state's default value or a state Map. A state Map has individual keys
-/// describing each state's value.
-///
-/// @example
-///   get-pressed-state(blue); // null
-///   get-pressed-state((pressed: red)); // red
-///   get-pressed-state((default: blue)); // null
-///
-/// @param {*} $default-or-map - The state's default value or a state Map.
-/// @return The pressed state if present, or null.
-@function get-pressed-state($default-or-map) {
-  @return _get-state($default-or-map, pressed);
-}
-
-/// Retrieves the selected state from the provided parameter. The parameter may
-/// be the state's default value or a state Map. A state Map has individual keys
-/// describing each state's value.
-///
-/// @example
-///   get-selected-state(blue); // null
-///   get-selected-state((selected: red)); // red
-///   get-selected-state((default: blue)); // null
-///
-/// @param {*} $default-or-map - The state's default value or a state Map.
-/// @return The selected state if present, or null.
-@function get-selected-state($default-or-map) {
-  @return _get-state($default-or-map, selected);
-}
-
-/// Retrieves the unselected state from the provided parameter. The parameter
-/// may be the state's default value or a state Map. A state Map has individual
-/// key describing each state's value.
-///
-/// @example
-///   get-unselected-state(blue); // null
-///   get-unselected-state((unselected: red)); // red
-///   get-unselected-state((default: blue)); // null
-///
-/// @param {*} $default-or-map - The state's default value or a state Map.
-/// @return The unselected state if present, or null.
-@function get-unselected-state($default-or-map) {
-  @return _get-state($default-or-map, unselected);
-}
-
-@function _get-state($default-or-map, $state) {
-  @if _is-state-map($default-or-map) {
-    @return map.get($default-or-map, $state);
-  } @else {
-    @return null;
-  }
-}
-
-@function _is-state-map($default-or-map) {
-  @return meta.type-of($default-or-map) == 'map' and not
-    custom-properties.is-custom-prop($default-or-map);
-}
-
-/// Appends the default state selector to the current parent.
-///
-/// @example - scss
-///   .mdc-foo {
-///     @include default($selectors) {
-///       color: teal;
-///     }
-///   }
-///
-/// @example - css
-///   .mdc-foo:enabled {
-///     color: teal;
-///   }
-///
-/// @param {Map} $selectors A Map whose keys are states and values are string
-///     selectors.
-@mixin default($selectors) {
-  @include enabled($selectors) {
-    @content;
-  }
-}
-
-/// Appends the enabled state selector to the current parent.
-///
-/// @example - scss
-///   .mdc-foo {
-///     @include enabled($selectors) {
-///       color: teal;
-///     }
-///   }
-///
-/// @example - css
-///   .mdc-foo:enabled {
-///     color: teal;
-///   }
-///
-/// @param {Map} $selectors A Map whose keys are states and values are string
-///     selectors.
-@mixin enabled($selectors) {
-  @include _selector($selectors, enabled) {
-    @content;
-  }
-}
-
-/// Appends the disabled state selector to the current parent.
-///
-/// @example - scss
-///   .mdc-foo {
-///     @include disabled($selectors) {
-///       color: teal;
-///     }
-///   }
-///
-/// @example - css
-///   .mdc-foo:disabled {
-///     color: teal;
-///   }
-///
-/// @param {Map} $selectors A Map whose keys are states and values are string
-///     selectors.
-@mixin disabled($selectors) {
-  @include _selector($selectors, disabled) {
-    @content;
-  }
-}
-
-/// Appends the dragged state selector to the current parent.
-///
-/// @example - scss
-///   .mdc-foo {
-///     @include dragged($selectors) {
-///       color: teal;
-///     }
-///   }
-///
-/// @example - css
-///   .mdc-foo:enabled.mdc-foo--dragged {
-///     color: teal;
-///   }
-///
-/// @param {Map} $selectors A Map whose keys are states and values are string
-///     selectors.
-@mixin dragged($selectors) {
-  @include enabled($selectors) {
-    @include _selector($selectors, dragged) {
-      @content;
-    }
-  }
-}
-
-/// Appends the error state selector to the current parent.
-///
-/// @example - scss
-///   .mdc-foo {
-///     @include error($selectors) {
-///       color: teal;
-///     }
-///   }
-///
-/// @example - css
-///   .mdc-foo:invalid {
-///     color: teal;
-///   }
-///
-/// @param {Map} $selectors A Map whose keys are states and values are string
-///     selectors.
-@mixin error($selectors) {
-  @include _selector($selectors, error) {
-    @content;
-  }
-}
-
-/// Appends the focus state selector to the current parent.
-///
-/// @example - scss
-///   .mdc-foo {
-///     @include focus($selectors) {
-///       color: teal;
-///     }
-///   }
-///
-/// @example - css
-///   .mdc-foo:enabled:focus:not(:active) {
-///     color: teal;
-///   }
-///
-/// @param {Map} $selectors A Map whose keys are states and values are string
-///     selectors.
-@mixin focus($selectors) {
-  @include enabled($selectors) {
-    @include _selector($selectors, focus) {
-      @content;
-    }
-  }
-}
-
-/// Appends the hover state selector to the current parent.
-///
-/// @example - scss
-///   .mdc-foo {
-///     @include hover($selectors) {
-///       color: teal;
-///     }
-///   }
-///
-/// @example - css
-///   .mdc-foo:enabled:hover:not(:focus):not(:active) {
-///     color: teal;
-///   }
-///
-/// @param {Map} $selectors A Map whose keys are states and values are string
-///     selectors.
-@mixin hover($selectors) {
-  @include enabled($selectors) {
-    @include _selector($selectors, hover) {
-      @content;
-    }
-  }
-}
-
-/// Appends the opened state selector to the current parent.
-///
-/// @example - scss
-///   .mdc-foo {
-///     @include opened($selectors) {
-///       color: teal;
-///     }
-///   }
-///
-/// @example - css
-///   .mdc-foo.mdc-foo--opened {
-///     color: teal;
-///   }
-///
-/// @param {Map} $selectors A Map whose keys are states and values are string
-///     selectors.
-@mixin opened($selectors) {
-  @include _selector($selectors, opened) {
-    @content;
-  }
-}
-
-/// Appends the pressed state selector to the current parent.
-///
-/// @example - scss
-///   .mdc-foo {
-///     @include pressed($selectors) {
-///       color: teal;
-///     }
-///   }
-///
-/// @example - css
-///   .mdc-foo:enabled:active {
-///     color: teal;
-///   }
-///
-/// @param {Map} $selectors A Map whose keys are states and values are string
-///     selectors.
-@mixin pressed($selectors) {
-  @include enabled($selectors) {
-    @include _selector($selectors, pressed) {
-      @content;
-    }
-  }
-}
-
-/// Appends the selected state selector to the current parent.
-///
-/// @example - scss
-///   .mdc-foo {
-///     @include selected($selectors) {
-///       color: teal;
-///     }
-///   }
-///
-/// @example - css
-///   .mdc-foo.mdc-foo--selected {
-///     color: teal;
-///   }
-///
-/// @param {Map} $selectors A Map whose keys are states and values are string
-///     selectors.
-@mixin selected($selectors) {
-  @include _selector($selectors, selected) {
-    @content;
-  }
-}
-
-/// Appends the unselected state selector to the current parent.
-///
-/// @example - scss
-///   .mdc-foo {
-///     @include unselected($selectors) {
-///       color: teal;
-///     }
-///   }
-///
-/// @example - css
-///   .mdc-foo.mdc-foo--unselected {
-///     color: teal;
-///   }
-///
-/// @param {Map} $selectors A Map whose keys are states and values are string
-///     selectors.
-@mixin unselected($selectors) {
-  @include _selector($selectors, unselected) {
-    @content;
-  }
-}
-
-/// Creates and returns a Map of independent selectors from a Map of simple
-/// selectors.
-///
-/// This function ensures that each selector is independent given all possible
-/// states provided. An "independent" selector does not rely on CSS override
-/// order or specificity.
-///
-/// @example - scss
-///   $selectors: state.create-selectors(
-///     (
-///       disabled: ':disabled',
-///       hover: ':hover',
-///       focus: ':focus',
-///       pressed: ':active',
-///     )
-///   );
-///   // (
-///   //   enabled: ':enabled',
-///   //   disabled: ':disabled',
-///   //   hover: ':hover:not(:focus):not(:active)',
-///   //   focus: ':focus:not(:active)',
-///   //   pressed: ':active',
-///   // )
-///
-/// @see {function} _create-independent-selector
-///
-/// @param {Map} $selectors A Map whose keys are states and values are string
-///     selectors.
-/// @return {Map} A Map of state selectors.
-@function _create-selectors($selectors) {
-  $new-selectors: ();
-  @each $state, $selector in $selectors {
-    @if not list.index($_valid-states, $state) {
-      @error 'Unsupported state #{$state}, must be one of #{$_valid-states}.';
-    }
-
-    // Check if there are any dependent states for this state that we need to
-    // add to the selector with :not()
-    $dependent-states: ();
-    @each $group in $_dependent-state-groups {
-      $index: list.index($group, $state);
-      @if $index and $index < list.length($group) {
-        // State is part of this group. Add any remaining selectors as
-        // dependents, only if they haven't already been added (the state may be
-        // part of multiple groups with shared state dependents, like
-        // :hover:focus:active and :link:visited:hover:active)
-        @for $i from $index + 1 through list.length($group) {
-          $dependent: list.nth($group, $i);
-          @if not list.index($dependent-states, $dependent) {
-            $dependent-states: list.append($dependent-states, $dependent);
-          }
-        }
-      }
-    }
-
-    $dependents: ();
-    @each $dependent-state in $dependent-states {
-      $dependent: map.get($selectors, $dependent-state);
-      @if $dependent and not list.index($_independent-states, $dependent-state)
-      {
-        $dependents: list.append($dependents, $dependent);
-      }
-    }
-
-    // Make the selector independent (if any dependents were found)
-    $selector: _create-independent-selector($selector, $dependents...);
-    $new-selectors: map.set($new-selectors, $state, $selector);
-  }
-
-  $new-selectors: _add-default-enabled-selector($new-selectors);
-
-  @return $new-selectors;
-}
-
-/// Adds a default selector for the "enabled" state if one does not exist and if
-/// it is possible to infer one from the provided Map of selectors.
-///
-/// @example - scss
-///   _add-default-enabled-selector((disabled: ':disabled'));
-///   // (
-///   //   disabled: ':disabled',
-///   //   enabled: ':enabled',
-///   // )
-///
-///   _add-default-enabled-selector((disabled: '.mdc-foo--disabled'));
-///   // (
-///   //   disabled: '.mdc-foo--disabled',
-///   //   enabled: ':not(.mdc-foo--disabled)',
-///   // )
-///
-/// @param {Map} $selectors - A Map of state selectors.
-/// @return {Map} The same Map of selectors, potentially with an additional
-///     "enabled" key with the enabled selector value.
-@function _add-default-enabled-selector($selectors) {
-  $enabled: map.get($selectors, enabled);
-  $disabled: map.get($selectors, disabled);
-  @if $disabled == ':disabled' {
-    @if $enabled and $enabled != ':enabled' {
-      // TODO(b/232779012): Clean up instances of :not(:disabled)
-      // Enabled selector was provided, but it was not :enabled. These
-      // can be cleaned up, but don't change them right now.
-      @warn 'Use :enabled instead of #{$enabled} when using :disabled.';
-      @return $selectors;
-    }
-
-    // For :disabled, use :enabled instead of the :not() variant
-    @return map.set($selectors, enabled, ':enabled');
-  }
-
-  @if $disabled and not $enabled {
-    @return map.set($selectors, enabled, selector-ext.negate($disabled));
-  }
-
-  @return $selectors;
-}
-
-/// A Map of override selectors. This can be used to temporarily change and
-/// configure state selectors.
-/// @type {Map}
-/// @see {mixin} override-selectors
-$_override-selectors: ();
-
-/// Override the current selectors provided to a state mixin for the provided
-/// content.
-///
-/// @example - scss
-///   // Change theme so that focus styles only show during keyboard navigation
-///   @include state.override-selectors((focus: ':focus-within')) {
-///     @include foo.theme($theme);
-///   }
-///
-/// @param {Map} $selectors A Map whose keys are states and values are string
-///     selectors.
-/// @content The styles to override state selectors for.
-@mixin override-selectors($selectors) {
-  $reset: $_override-selectors;
-  $_override-selectors: $selectors !global;
-  @content;
-  $_override-selectors: $reset !global;
-}
-
-$_independent-states: ();
-
-/// Indicates that for the given content of state mixins, the provided states
-/// are on their own independent elements and that they should ignore typical
-/// dependent groupings, such as `:hover`, `:focus`, and `:active`.
-///
-/// This mixin is useful when multiple states within a typical dependency group
-/// need to be visible at the same time (such as `:focus` and `:active`). To
-/// achieve this, the states must be on their own independent elements (such as
-/// separate `::before` and `::after` pseudo elements).
-///
-/// @example - scss
-///   .broken-ripple {
-///     @include state.hover {
-///       &::before { opacity: 0.1; }
-///     }
-///     @include state.focus {
-///       &::before { opacity: 0.2; }
-///     }
-///     @include state.pressed {
-///       &::after { opacity: 0.3; }
-///     }
-///   }
-///
-///   .fixed-ripple {
-///     @include state.independent-elements(pressed) {
-///       @include state.hover {
-///         &::before { opacity: 0.1; }
-///       }
-///       @include state.focus {
-///         &::before { opacity: 0.2; }
-///       }
-///       @include state.pressed {
-///         &::before { opacity: 0.3; }
-///       }
-///     }
-///   }
-///
-///  @example - css
-///   .broken-ripple:hover:not(:focus):not(:active)::before {
-///     opacity: 0.1;
-///   }
-///   .broken-ripple:focus:not(:active)::before {
-///     /* Focus styles will not be visible due to :not(:active)!! */
-///     opacity: 0.2;
-///   }
-///   .broken-ripple:active::after {
-///     opacity: 0.3;
-///   }
-///
-///   .fixed-ripple:hover:not(:focus)::before {
-///     opacity: 0.1;
-///   }
-///   .fixed-ripple:focus::before {
-///     /* Both focus and pressed styles are visible during press. Only hover
-///        and focus need to be independent of each other since they share an
-///        element. */
-///     opacity: 0.2;
-///   }
-///   .fixed-ripple:active::after {
-///     opacity: 0.3;
-///   }
-///
-/// @param {String...} $states - One or more states that should be considered
-///     independent and on its own element.
-/// @content Two or more state mixins that are part of a dependency group
-///     involving the provided independent states.
-@mixin independent-elements($states...) {
-  $reset: $_independent-states;
-  $_independent-states: $states !global;
-  @content;
-  $_independent-states: $reset !global;
-}
-
-/// A List of state groups that are dependent on each other for CSS override
-/// order. These are used to determine which state selectors are needed for
-/// `_create-independent-selector()`.
-// Note: Sass syntax does not allow declaring nested Lists; an empty second List
-// placeholder is added for the correct data structure.
-$_dependent-state-groups: ((hover, focus, pressed), ());
-
-/// Creates a selector that will be independent based on the other selectors
-/// that are dependents of it.
-///
-/// Selector dependencies are selector groups that must follow a certain order
-/// for CSS overrides. For example: `:hover`, `:focus`, `:active` or `:link`,
-/// `:visited`, `:hover`, `:active`.
-///
-/// Selectors at the start of a group are dependencies of selectors at the end
-/// of a group.
-///
-/// @example - scss
-///   #{_create-independent-selector(':hover', ':focus', ':active')} {
-///     color: teal;
-///   }
-///
-///   #{_create-independent-selector(':focus', ':active')} {
-///     color: magenta;
-///   }
-///
-/// @example - css
-///   :hover:not(:focus):not(:active) {
-///     color: teal;
-///   }
-///
-///   :focus:not(:active) {
-///     color: magenta;
-///   }
-///
-/// The returned selector is considered "independent" and does not rely on CSS
-/// override order or specificity within its group. In other words, "hover"
-/// styles can be customized after "focus" styles without hiding default focus
-/// styles.
-///
-/// @example - css
-///   /* Default focus styles */
-///   :focus:not(:active) { color: magenta; }
-///
-///   /* New hover styles, does not prevent focus styles from being visible */
-///   :hover:not(:focus):not(:active) { color: orange; }
-///
-/// @param {String} $selector - The main selector to target.
-/// @param {String...} $dependents - Additional group dependents of the main
-///     selector. They will be added as `:not()` selectors.
-/// @return {List} A new independent selector in selector value format.
-@function _create-independent-selector($selector, $dependents...) {
-  @each $dependent in $dependents {
-    @if $dependent {
-      $selector: selector-ext.append-strict(
-        $selector,
-        selector-ext.negate($dependent)
-      );
-    }
-  }
-
-  @return $selector;
-}
-
-@mixin _selector($selectors, $state) {
-  $selectors: _create-selectors(map.merge($selectors, $_override-selectors));
-  @if not map.has-key($selectors, $state) {
-    @error 'Missing #{$state} from #{$selectors}';
-  }
-
-  @at-root {
-    #{selector-ext.append-strict(&, map.get($selectors, $state))} {
-      @content;
-    }
-  }
-}