3
3
@use ' sass:meta' ;
4
4
@use ' @angular/material' as mat ;
5
5
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.
8
8
$_error-on-missing-dep : false;
9
9
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.
11
15
@mixin _apply-theme ($tokens , $component ) {
12
16
$id : map .get ($component , id );
13
17
$tokens : map .deep-merge ($tokens , map .get ($component , customizations ));
@@ -25,7 +29,16 @@ $_error-on-missing-dep: false;
25
29
}
26
30
}
27
31
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.
29
42
@function _get-transitive-deps ($components , $configured : ()) {
30
43
// Mark the given components as configured.
31
44
@each $component in $components {
@@ -35,7 +48,12 @@ $_error-on-missing-dep: false;
35
48
36
49
// Check each of the given components for new deps.
37
50
@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 )) {
39
57
$dep : meta .call ($dep-getter );
40
58
$dep-id : map .get ($dep , id );
41
59
@if not (map .has-key ($configured , $dep-id )) {
@@ -58,32 +76,45 @@ $_error-on-missing-dep: false;
58
76
@return $components ;
59
77
}
60
78
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.
61
84
@mixin _theme ($tokens , $components ) {
62
85
// Call the theme mixin for each configured component.
63
86
@each $component in $components {
64
87
@include _apply-theme ($tokens , $component );
65
88
}
66
89
}
67
90
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
70
98
@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 )));
72
100
}
73
101
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.
74
106
// TODO(mmalerba): What should we call this?
75
107
// - update-theme
76
108
// - adjust-theme
77
109
// - edit-theme
78
110
// - override-theme
79
111
// - 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 ) {
83
113
@include _theme ((), $components );
84
114
}
85
115
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.
87
118
@function card ($customizations : ()) {
88
119
@return (
89
120
id: ' mat.card' ,
@@ -92,7 +123,8 @@ $_error-on-missing-dep: false;
92
123
);
93
124
}
94
125
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.
96
128
@function checkbox ($customizations : ()) {
97
129
@return (
98
130
id: ' mat.checkbox' ,
0 commit comments