Skip to content

Commit ab81566

Browse files
asynclizcopybara-github
asyncliz
authored and
copybara-github
committed
chore: add var utilities to sass-ext
PiperOrigin-RevId: 836343515
1 parent 563da62 commit ab81566

File tree

3 files changed

+241
-91
lines changed

3 files changed

+241
-91
lines changed

internal/sass/_var.scss renamed to sass/ext/_var.scss

Lines changed: 79 additions & 91 deletions
Original file line numberDiff line numberDiff line change
@@ -3,90 +3,79 @@
33
// SPDX-License-Identifier: Apache-2.0
44
//
55

6-
// go/keep-sorted start
6+
// Utility functions for "var()" custom property string manipulation.
7+
8+
// go/keep-sorted start by_regex='(.+) prefix_order=sass:
79
@use 'sass:map';
810
@use 'sass:meta';
911
@use 'sass:string';
10-
// go/keep-sorted end
11-
// go/keep-sorted start
12-
@use '../../sass/ext/string_ext';
12+
@use 'assert';
13+
@use 'string_ext';
14+
@use 'throw';
1315
// go/keep-sorted end
1416

1517
/// Creates a custom property `var()` string.
1618
///
17-
/// @param {String} $name - The name of the custom property.
19+
/// @example scss
20+
/// @debug var.create(--foo); // "var(--foo)"
21+
/// @debug var.create(--foo, 8px); // "var(--foo, 8px)"
22+
///
23+
/// @param {string} $name - The name of the custom property.
1824
/// @param {*} $fallback [null] - Optional `var()` fallback value.
19-
/// @return {String} A custom property `var()` string.
25+
/// @return {string} A custom property `var()` string.
2026
@function create($name, $fallback: null) {
21-
$name: create-name($name);
22-
@if $fallback == null {
23-
@return var(#{$name});
27+
$name: assert.is-type($name, 'string');
28+
@if throw.get-error($name) {
29+
@return $name;
2430
}
25-
26-
@if is-var($fallback) {
27-
$fallback-name: name($fallback);
28-
$fallback-fallback: fallback($fallback);
29-
@return var(#{$name}, create($fallback-name, $fallback-fallback));
31+
@if not string_ext.starts-with($name, '--') {
32+
@return throw.error(
33+
'Custom property names must start with "--". $name: #{meta.inspect($name)}',
34+
$source: 'var.create'
35+
);
3036
}
3137

32-
@return var(#{$name}, $fallback);
33-
}
34-
35-
/// Create a custom property variable name.
36-
///
37-
/// Providing a custom property name with `--*` will ignore the global prefix.
38-
///
39-
/// @example - scss
40-
/// .foo {
41-
/// color: var(#{var.create-name(foo)});
42-
/// background: var(#{var.create-name(--bar)});
43-
/// }
44-
///
45-
/// @example - css
46-
/// .foo {
47-
/// color: var(--md-foo);
48-
/// background: var(--bar);
49-
/// }
50-
///
51-
/// @param {String} $name - The name of the custom property.
52-
/// @return {String} The full valid CSS custom property variable name.
53-
@function create-name($name) {
54-
@if string_ext.starts-with($name, '--') {
55-
@return $name;
38+
@if $fallback == null {
39+
@return var(#{$name});
5640
}
5741

58-
@return string.unquote('--md-#{$name}');
42+
@return var(#{$name}, #{$fallback});
5943
}
6044

6145
/// Returns the custom property variable name of `var()` string.
6246
///
47+
/// @example scss
48+
/// $var: var(--foo);
49+
/// @debug var.name($var); // "foo"
50+
///
51+
/// @param {string} $var - A custom property `var()` string.
52+
/// @return {string} The custom property variable name.
6353
/// @throw If the value is not a custom property.
64-
/// @param {String} $var - A custom property `var()` string.
65-
/// @return {String} The custom property variable name.
6654
@function name($var) {
6755
$var: _parse-and-validate($var);
68-
@return map.get($var, name);
56+
@if throw.get-error($var) {
57+
@return $var;
58+
}
59+
@return map.get($var, 'name');
6960
}
7061

7162
/// Returns the fallback value of a custom property `var()` string. The value
7263
/// may be null if the `var()` does not have a fallback value.
7364
///
74-
/// @example - scss
75-
/// $fallback: var.fallback(var(--foo, var(--bar, 8px));
76-
/// // "var(--bar, 8px)"
65+
/// @example scss
66+
/// $var: var(--foo, var(--bar, 8px));
67+
/// @debug var.fallback($var); // "var(--bar, 8px)"
7768
///
78-
/// @throw If the value is not a custom property.
79-
/// @param {String} $var - A custom property `var()` string.
80-
/// @return {String} The fallback value of the `var()` string. May be null if
69+
/// @param {string} $var - A custom property `var()` string.
70+
/// @return {string} The fallback value of the `var()` string. May be null if
8171
/// the `var()` does not have a fallback value.
72+
/// @throw If the value is not a custom property.
8273
@function fallback($var) {
8374
$var: _parse-and-validate($var);
84-
$fallback: map.get($var, fallback);
85-
@if is-var($fallback) {
86-
@return create(name($fallback), fallback($fallback));
75+
@if throw.get-error($var) {
76+
@return $var;
8777
}
88-
89-
@return $fallback;
78+
@return map.get($var, 'fallback');
9079
}
9180

9281
/// Returns the deep fallback value of a custom property `var()` string. The
@@ -95,18 +84,18 @@
9584
/// If a fallback value is another `var()`, this function will return the final
9685
/// concrete value in the chain.
9786
///
98-
/// @example - scss
99-
/// $fallback: var.deep-fallback(var(--foo, var(--bar, 8px));
100-
/// // "8px"
87+
/// @example scss
88+
/// $var: var(--foo, var(--bar, 8px));
89+
/// @debug var.deep-fallback($var); // "8px"
10190
///
102-
/// @throw If the value is not a custom property.
103-
/// @param {String} $var - A custom property `var()` string.
104-
/// @return {String} The deep fallback value of the `var()` string. May be null
91+
/// @param {string} $var - A custom property `var()` string.
92+
/// @return {string} The deep fallback value of the `var()` string. May be null
10593
/// if the `var()` does not have a fallback value.
94+
/// @throw If the value is not a custom property.
10695
@function deep-fallback($var) {
10796
$fallback: fallback($var);
108-
@if is-var($fallback) {
109-
@return deep-fallback($fallback);
97+
@while is-var($fallback) {
98+
$fallback: fallback($fallback);
11099
}
111100

112101
@return $fallback;
@@ -115,16 +104,17 @@
115104
/// Creates a new custom property `var()` string and returns it with the
116105
/// specified new fallback value.
117106
///
118-
/// @example - scss
119-
/// $new-var: set-fallback(var(--foo, var(--bar, 8px)), 16px);
120-
/// // "var(--foo, 16px)"
107+
/// @example scss
108+
/// $var: var(--foo, var(--bar, 8px));
109+
/// $new-var: set-fallback($var, 16px);
110+
/// @debug $new-var; // "var(--foo, 16px)"
121111
///
122-
/// @throw If the value is not a custom property.
123-
/// @param {String} $var - A custom property `var()` string.
112+
/// @param {string} $var - A custom property `var()` string.
124113
/// @param {*} $new-fallback - The new fallback value. May be null to remove a
125114
/// value.
126-
/// @return {String} A custom property `var()` string with the new fallback
115+
/// @return {string} A custom property `var()` string with the new fallback
127116
/// value.
117+
/// @throw If the value is not a custom property.
128118
@function set-fallback($var, $new-fallback) {
129119
$name: name($var);
130120
@return create($name, $new-fallback);
@@ -136,16 +126,17 @@
136126
/// If the provided `var()` string's fallback value is another `var()`, this
137127
/// function will set the final fallback value in the chain.
138128
///
139-
/// @example - scss
140-
/// $new-var: deep-set-fallback(var(--foo, var(--bar, 8px)), 16px);
141-
/// // "var(--foo, var(--bar, 16px))"
129+
/// @example scss
130+
/// $var: var(--foo, var(--bar, 8px));
131+
/// $new-var: var.deep-set-fallback($var, 16px);
132+
/// @debug $new-var; // "var(--foo, var(--bar, 16px))"
142133
///
143-
/// @throw If the value is not a custom property.
144-
/// @param {String} $var - A custom property `var()` string.
134+
/// @param {string} $var - A custom property `var()` string.
145135
/// @param {*} $new-fallback - The new fallback value. May be null to remove a
146136
/// value.
147-
/// @return {String} A custom property `var()` string with the new deep
137+
/// @return {string} A custom property `var()` string with the new deep
148138
/// fallback value.
139+
/// @throw If the value is not a custom property.
149140
@function deep-set-fallback($var, $new-fallback) {
150141
$old-fallback: fallback($var);
151142
@if is-var($old-fallback) {
@@ -157,11 +148,12 @@
157148

158149
/// Indicates whether or not a value is a custom property `var()` string.
159150
///
160-
/// @example - scss
161-
/// $is-var: var.is-var('var(--foo)'); // true
151+
/// @example scss
152+
/// $var: var(--foo);
153+
/// @debug var.is-var($var); // true
162154
///
163155
/// @param {*} $var - The value to test.
164-
/// @return {Bool} True if the value is a custom property `var()` string, or
156+
/// @return {boolean} True if the value is a custom property `var()` string, or
165157
/// false if not.
166158
@function is-var($var) {
167159
@return _parse($var) != null;
@@ -170,7 +162,7 @@
170162
/// Indicates whether or not a value is a `var()` string.
171163
///
172164
/// @param {*} $var - The value to test.
173-
/// @return {Bool} True if the value is a custom property `var()` string, or
165+
/// @return {boolean} True if the value is a custom property `var()` string, or
174166
/// false if not.
175167
@function _is-var-string($var) {
176168
@return meta.type-of($var) == 'string' and
@@ -181,14 +173,14 @@
181173
/// function returns null if the value is invalid.
182174
///
183175
/// @param {*} $var - The value to parse.
184-
/// @return {Map} A Map containing a string `name` key with the custom property
176+
/// @return {map} A Map containing a string `name` key with the custom property
185177
/// name and a `fallback` key with the fallback value (which may be null).
186178
/// The returned Map itself may be null if the provided value is not valid.
187179
@function _parse($var) {
188180
@if meta.type-of($var) ==
189181
'map' and
190-
map.has-key($var, name) and
191-
map.has-key($var, fallback)
182+
map.has-key($var, 'name') and
183+
map.has-key($var, 'fallback')
192184
{
193185
@return $var;
194186
}
@@ -207,32 +199,28 @@
207199
@if $comma != null {
208200
$name: string_ext.trim(string.slice($var, 1, $comma - 1));
209201
$fallback: string_ext.trim(string.slice($var, $comma + 1));
210-
@if _is-var-string($fallback) {
211-
$fallback: _parse($fallback);
212-
@if $fallback == null {
213-
// Invalid var() fallback string
214-
@return null;
215-
}
216-
}
217202
}
218203

219204
@if $name == '' or $fallback == '' {
220205
@return null;
221206
}
222207

223-
@return (name: $name, fallback: $fallback);
208+
@return ('name': $name, 'fallback': $fallback);
224209
}
225210

226211
/// Parses a `var()` string into a Map with `name` and `fallback` keys.
227212
///
228-
/// @throw If the value is not a custom property.
229213
/// @param {*} $var - The value to parse.
230-
/// @return {Map} A Map containing a string `name` key with the custom property
214+
/// @return {map} A Map containing a string `name` key with the custom property
231215
/// name and a `fallback` key with the fallback value (which may be null).
216+
/// @throw If the value is not a custom property.
232217
@function _parse-and-validate($var) {
233218
$var-map: _parse($var);
234219
@if $var-map == null {
235-
@error '"#{$var}" is not a valid var() string';
220+
@return throw.error(
221+
'#{meta.inspect($var)} is not a valid var() string',
222+
$source: 'var._parse-and-validate'
223+
);
236224
}
237225

238226
@return $var-map;

0 commit comments

Comments
 (0)