Skip to content

Commit 55c7a7c

Browse files
committed
addressed more feedback
1 parent 359bec6 commit 55c7a7c

File tree

3 files changed

+84
-31
lines changed

3 files changed

+84
-31
lines changed

src/material-experimental/theming/_theming.scss

Lines changed: 45 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -3,11 +3,15 @@
33
@use 'sass:meta';
44
@use '@angular/material' as mat;
55

6-
// Whether to throw an error when a required dep is not configured. If false, the dep will be
7-
// automatically configured instead.
6+
/// Whether to throw an error when a required dep is not configured. If false, the dep will be
7+
/// automatically configured instead.
88
$_error-on-missing-dep: false;
99

10-
// Applies the theme for the given component configuration.
10+
/// Applies the theme for the given component configuration.
11+
/// @param {Map} $tokens A map containing the default values to use for tokens not explicitly
12+
/// customized in the component config object.
13+
/// @param {List} $component The component config object to emit theme tokens for.
14+
/// @output CSS variables representing the theme tokens for this component.
1115
@mixin _apply-theme($tokens, $component) {
1216
$id: map.get($component, id);
1317
$tokens: map.deep-merge($tokens, map.get($component, customizations));
@@ -25,7 +29,16 @@ $_error-on-missing-dep: false;
2529
}
2630
}
2731

28-
// Gets the transitive dependency configurations for the given list of component configurations.
32+
/// Gets the transitive closure of the given list of component configuration dependencies.
33+
/// @param {List} $components The list of component config objects to get the transitive deps for.
34+
/// @param {Map} $configured [()] A map of already configured component IDs. Used for recursion,
35+
/// should not be passed when calling.
36+
/// @return {List} The transitive closure of configs for the given $components.
37+
// TODO(mmalerba): Currently we use the deps to determine if additional tokens, other than the
38+
// explicitly requested ones need to be emitted, but the deps do not affect the ordering in which
39+
// the various configs are processed. Before moving out of experimental we should think more about
40+
// the ordering behavior we want. For the most part the order shouldn't matter, unless we have 2
41+
// configs trying to set the same token.
2942
@function _get-transitive-deps($components, $configured: ()) {
3043
// Mark the given components as configured.
3144
@each $component in $components {
@@ -35,7 +48,12 @@ $_error-on-missing-dep: false;
3548

3649
// Check each of the given components for new deps.
3750
@each $component in $components {
38-
@each $dep-getter in mat.private-normalize-args-list(map.get($component, deps)) {
51+
// Note: Deps are specified as getter functions that return a config object rather than a direct
52+
// config object. This allows us to only call the getter if the dep has not yet been configured.
53+
// This can be useful if we have 2 components that want to require each other to be configured.
54+
// Example: form-field and input. If we used direct config objects in this case, it would cause
55+
// infinite co-recursion.
56+
@each $dep-getter in mat.private-coerce-to-list(map.get($component, deps)) {
3957
$dep: meta.call($dep-getter);
4058
$dep-id: map.get($dep, id);
4159
@if not (map.has-key($configured, $dep-id)) {
@@ -58,32 +76,45 @@ $_error-on-missing-dep: false;
5876
@return $components;
5977
}
6078

79+
/// Apply the themes for the given component configs with the given ste of fallback token values.
80+
/// @param {Map} $tokens A map of fallback values to use for tokens that are not explicitly
81+
/// customized by one of the component configs.
82+
/// @param {List} $components The list of component configurations to emit tokens for.
83+
/// @output CSS variables representing the theme tokens for the given component configs.
6184
@mixin _theme($tokens, $components) {
6285
// Call the theme mixin for each configured component.
6386
@each $component in $components {
6487
@include _apply-theme($tokens, $component);
6588
}
6689
}
6790

68-
// Takes the full list of tokens and a list of components to configure, and outputs all theme
69-
// tokens for the configured components.
91+
/// Takes the full list of tokens and a list of components to configure, and outputs all theme
92+
/// tokens for the configured components.
93+
/// @param {Map} $tokens A map of all tokens for the current design system.
94+
/// @param {List} $components The list of component configurations to emit tokens for.
95+
/// @output CSS variables representing the theme tokens for the given component configs.
96+
// TODO(mmalerba): Consider an alternate API where `$tokens` is not a separate argument,
97+
// but one of the configs in the `$components` list
7098
@mixin theme($tokens, $components) {
71-
@include _theme($tokens, _get-transitive-deps(mat.private-normalize-args-list($components)));
99+
@include _theme($tokens, _get-transitive-deps(mat.private-coerce-to-list($components)));
72100
}
73101

102+
/// Takes a list of components to configure, and outputs only the theme tokens that are explicitly
103+
/// customized by the configurations.
104+
/// @param {List} $components The list of component configurations to emit tokens for.
105+
/// @output CSS variables representing the theme tokens for the given component configs.
74106
// TODO(mmalerba): What should we call this?
75107
// - update-theme
76108
// - adjust-theme
77109
// - edit-theme
78110
// - override-theme
79111
// - retheme
80-
// Takes a list of components to configure, and outputs only the theme tokens that are explicitly
81-
// customized by the configurations.
82-
@mixin update-theme($components) {
112+
@mixin retheme($components) {
83113
@include _theme((), $components);
84114
}
85115

86-
// Configure the mat-card's theme.
116+
/// Configure the mat-card's theme.
117+
/// @param {Map} $customizations [()] A map of custom token values to use when theming mat-card.
87118
@function card($customizations: ()) {
88119
@return (
89120
id: 'mat.card',
@@ -92,7 +123,8 @@ $_error-on-missing-dep: false;
92123
);
93124
}
94125

95-
// Configure the mat-checkbox's theme.
126+
/// Configure the mat-checkbox's theme.
127+
/// @param {Map} $customizations [()] A map of custom token values to use when theming mat-checkbox.
96128
@function checkbox($customizations: ()) {
97129
@return (
98130
id: 'mat.checkbox',
Lines changed: 19 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,23 @@
11
@use 'sass:map';
22
@use 'sass:meta';
33

4-
// Include content under the current selector (&) or the document root if there is no current
5-
// selector.
4+
/// Include content under the current selector (&) or the document root if there is no current
5+
/// selector.
6+
/// @param {String} $root [html] The default root selector to use when there is no current selector.
7+
/// @output The given content under the current selector, or root selector if there is no current
8+
/// selector.
9+
/// @content Content to output under the current selector, or root selector if there is no current
10+
/// selector.
611
@mixin current-selector-or-root($root: html) {
712
@at-root #{& or $root} {
813
@content;
914
}
1015
}
1116

12-
// A version of the standard `map.deep-merge` function that takes a variable number of arguments.
13-
// Each argument is deep-merged into the final result from left to right.
17+
/// A version of the standard `map.deep-merge` function that takes a variable number of arguments.
18+
/// Each argument is deep-merged into the final result from left to right.
19+
/// @param {List} $maps The maps to combine with map.deep-merge
20+
/// @return {Map} The combined result of successively calling map.deep-merge with each parameter.
1421
@function deep-merge-all($maps...) {
1522
$result: ();
1623
@each $map in $maps {
@@ -19,9 +26,12 @@
1926
@return $result;
2027
}
2128

22-
// Normalizes a list of arguments to ensure it really is a list and not a single arg.
23-
// This should be used when dealing with user-passed lists of args to avoid confusing errors,
24-
// since Sass treats `($x)` as equivalent to `$x`.
25-
@function normalize-args-list($list) {
26-
@return if(meta.type-of($list) != 'list', ($list,), $list);
29+
/// Coerces the given value to a list, by converting any non-list value into a single-item list.
30+
/// This should be used when dealing with user-passed lists of args to avoid confusing errors,
31+
/// since Sass treats `($x)` as equivalent to `$x`.
32+
/// @param {Any} $value The value to coerce to a list.
33+
/// @return {List} The original $value if it was a list, otherwise a single-item list containing
34+
/// $value.
35+
@function coerce-to-list($value) {
36+
@return if(meta.type-of($value) != 'list', ($value,), $value);
2737
}

src/material/core/tokens/m2/_index.scss

Lines changed: 20 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -23,8 +23,13 @@
2323
@use './mdc/tab' as tokens-mdc-tab;
2424
@use './mdc/tab-indicator' as tokens-mdc-tab-indicator;
2525

26-
// Gets the tokens for the given theme, m2 tokens module, and theming system.
27-
// Valid theming systems are: unthemable, color, typography, density.
26+
/// Gets the tokens for the given theme, m2 tokens module, and theming system.
27+
/// @param {Map} $theme The Angular Material theme object to generate token values from.
28+
/// @param {String} $module The Sass module containing the token getter functions.
29+
/// @param {String} $system The theming system to get tokens for. Valid values are: unthemable,
30+
/// color, typography, density.
31+
/// @return {Map} The token map by calling the token getter for the given system in the given module
32+
/// with the given Angular Material theme. Token names are not fully-qualified.
2833
@function _get-tokens-for-module-and-system($theme, $module, $system) {
2934
@if $system == unthemable {
3035
@return meta.call(
@@ -37,7 +42,11 @@
3742
meta.get-function(get-#{$system}-tokens, $module: $module), map.get($theme, $system));
3843
}
3944

40-
// Gets the fully qualified tokens map for the given theme and m2 tokens module.
45+
/// Gets the fully qualified tokens map for the given theme and m2 tokens module.
46+
/// @param {Map} $theme The Angular Material theme object to generate token values from.
47+
/// @param {String} $module The Sass module containing the token getter functions.
48+
/// @return {Map} The token map by calling the token getters in the given module with the given
49+
/// Angular Material theme. Token names are fully-qualified.
4150
@function _get-tokens-for-module($theme, $module) {
4251
$tokens: sass-utils.deep-merge-all(
4352
_get-tokens-for-module-and-system($theme, $module, unthemable),
@@ -47,12 +56,14 @@
4756
@return map.set((), map.get(meta.module-variables($module), prefix), $tokens);
4857
}
4958

50-
// Gets the full set of m2 tokens for the given theme object. Returned format:
51-
// (
52-
// (fully, qualified, namespace): (
53-
// token: value
54-
// )
55-
// )
59+
/// Gets the full set of M2 tokens for the given theme object.
60+
/// @param {Map} $theme The Angular Material theme object to generate token values from.
61+
/// @return {Map} The token map for the given Angular Material theme. Returned format:
62+
/// (
63+
/// (fully, qualified, namespace): (
64+
/// token: value
65+
/// )
66+
/// )
5667
@function m2-tokens-from-theme($theme) {
5768
@return sass-utils.deep-merge-all(
5869
_get-tokens-for-module($theme, tokens-mat-card),

0 commit comments

Comments
 (0)