Skip to content

Commit

Permalink
Final review corrections
Browse files Browse the repository at this point in the history
  • Loading branch information
@pamelalozano16
pamelalozano16 committed Aug 9, 2023
1 parent a68f607 commit 4ea8198
Show file tree
Hide file tree
Showing 3 changed files with 113 additions and 84 deletions.
2 changes: 1 addition & 1 deletion source/documentation/breaking-changes/abs-percent.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,5 +17,5 @@ function. Therefore if the value of `10%` represented `-50px`, `abs(10%)` would
return `-10%` which in the browser would be `50px`.

For this reason, we are deprecating the global abs() function with a percentage.
To preserve the current behavior, use `math.abs()` or `abs(#{})` instead.
To preserve the current behavior, use `math.abs()` instead.

4 changes: 4 additions & 0 deletions source/documentation/breaking-changes/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,10 @@ time-sensitive, so they may be released with new minor version numbers instead.

These breaking changes are coming soon or have recently been released:

* [Passing a percentage unit to the global `abs()` is
  deprecated](/documentation/breaking-changes/abs-percent/) beginning in Dart
Sass 1.65.0.

* [Passing `null` as an alpha channel to `new SassColor()` is changing
behavior](/documentation/breaking-changes/null-alpha) beginning in Dart
Sass 1.64.3.
Expand Down
191 changes: 108 additions & 83 deletions source/documentation/values/calculations.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ introduction: >
much as possible, even if they're combined with one another.
---

{% compatibility 'dart: "1.40.0"','libsass: false', 'ruby: false'%}
{% compatibility 'dart: "1.40.0"', 'libsass: false', 'ruby: false' %}
LibSass, Ruby Sass, and versions of Dart Sass prior to 1.40.0 parse `calc()`
as a [special function] like `element()`.

Expand Down Expand Up @@ -158,24 +158,27 @@ CSS to unitless numbers:

## Calculation Functions

{% compatibility 'dart: "1.64.0"', 'libsass: false', 'ruby: false', 'feature: "Special function syntax"' %}
LibSass, Ruby Sass, and versions of Dart Sass subsequent to 1.64.0 support the
following calculation functions, with the exception of `min()`, `max()`, and
`clamp()`.
{% compatibility 'dart: "1.65.0"', 'libsass: false', 'ruby: false', 'feature: "Additional functions"' %}
Versions of Dart Sass subsequent to 1.65.0 handle the execution of these
calculation functions: `round()`, `mod()`, `rem()`, `sin()`, `cos()`, `tan()`,
`asin()`, `acos()`, `atan()`, `atan2()`, `pow()`, `sqrt()`, `hypot()`,
`log()`, `exp()`, `abs()`, and `sign()`.
{% endcompatibility %}

Sass parses the following functions as [calculations]:
* Comparison Functions: [`min()`], [`max()`], and [`clamp()`]
* Stepped Value Functions: [`round()`], [`mod()`], and [`rem()`].
* Trigonometric Functions: [`sin()`], [`cos()`], [`tan()`], [`asin()`], [`acos()`], [`atan()`], and [`atan2()`].
* Trigonometric Functions: [`sin()`], [`cos()`], [`tan()`], [`asin()`], [`acos()`],
[`atan()`], and [`atan2()`].
* Exponential Functions: [`pow()`], [`sqrt()`], [`hypot()`], [`log()`], and [`exp()`].
* Sign-Related Functions: [`abs()`] and [`sign()`].

[calculations]: https://www.w3.org/TR/css-values-4/#math
[`min()`]: #min-and-max
[`max()`]: #min-and-max
[`clamp()`]: /documentation/modules/math/#clamp
[`round()`]: #round
[`min()`]: https://developer.mozilla.org/en-US/docs/Web/CSS/min
[`max()`]: https://developer.mozilla.org/en-US/docs/Web/CSS/max
[`clamp()`]: https://developer.mozilla.org/en-US/docs/Web/CSS/clamp
[`round()`]: https://developer.mozilla.org/en-US/docs/Web/CSS/round
[`abs()`]: https://developer.mozilla.org/en-US/docs/Web/CSS/abs
[`sin()`]: https://developer.mozilla.org/en-US/docs/Web/CSS/sin
[`cos()`]: https://developer.mozilla.org/en-US/docs/Web/CSS/cos
[`tan()`]: https://developer.mozilla.org/en-US/docs/Web/CSS/tan
Expand All @@ -187,7 +190,6 @@ Sass parses the following functions as [calculations]:
[`sqrt()`]: https://developer.mozilla.org/en-US/docs/Web/CSS/sqrt
[`hypot()`]: https://developer.mozilla.org/en-US/docs/Web/CSS/hypot
[`log()`]: https://developer.mozilla.org/en-US/docs/Web/CSS/log
[`abs()`]: #abs
[`exp()`]: https://developer.mozilla.org/en-US/docs/Web/CSS/exp
[`mod()`]: https://developer.mozilla.org/en-US/docs/Web/CSS/mod
[`rem()`]: https://developer.mozilla.org/en-US/docs/Web/CSS/rem
Expand All @@ -201,26 +203,45 @@ CSS added support for [mathematical expressions] in Values and Units Level
those existing stylesheets. This led to the need for extra-special syntactic
cleverness.

[`min()` and `max()` functions]: https://www.w3.org/TR/css-values-4/#math
[to support the iPhoneX]: https://webkit.org/blog/7929/designing-websites-for-iphone-x/
[mathematical expressions]: https://www.w3.org/TR/css-values-4/#math
[`round()`]: ../modules/math#round
[`abs()`]: ../modules/math#abs
[`min()`]: ../modules/math#min
[`max()`]: ../modules/math#max

If a calculation function call is a valid calculation expression, it will
be parsed as a calculation. But as soon as any part of the call contains a
SassScript feature that isn't supported in a calculation, like the [modulo
operator], it's parsed as a call to the appropriate Sass math function
instead.
If a call to `round()`, `abs()`, `min()`, or `max()` is a valid calculation
expression, it will be parsed as a calculation. But as soon as any part of the
call contains a SassScript feature that isn't supported in a calculation, like
the [modulo operator], it's parsed as a call to the appropriate Sass math
function instead.

Since calculations are simplified to numbers when possible anyway, the only
substantive difference is that the Sass functions only support units that can be
combined at build time, so `min(12px % 10, 10%)` will throw an error.

[modulo operator]: /documentation/operators/numeric/

{% headsUp %}
Other calculations don't allow unitless numbers to be added to, subtracted
from, or compared to numbers with units. [`min()`], [`max()`], [`abs()`] and
[single-argument `round()`] are different, though: for backwards-compatibility
with the global Sass legacy functions which allow unit/unitless mixing for
historical reasons, these units can be mixed as long as they're contained
directly within a `min()`, `max()`, `abs()`, or single-argument `round()`
calculation.

For instance, `min(5 + 10px, 20px)` will result in `15px`. However
`sqrt(5 + 10px)` will throw an error, as `sqrt(5 + 10px)` was never a global
Sass function, and these are incompatible units.

[single-argument `round()`]: https://developer.mozilla.org/en-US/docs/Web/CSS/round
[`abs()`]: https://developer.mozilla.org/en-US/docs/Web/CSS/abs
[`min()`]: https://developer.mozilla.org/en-US/docs/Web/CSS/min
[`max()`]: https://developer.mozilla.org/en-US/docs/Web/CSS/max
{% endheadsUp %}

#### `min()` and `max()`

{% compatibility 'dart: ">=1.11.0 <1.42.0"', 'libsass: false', 'ruby: false', 'feature: "min and max syntax"' %}
LibSass, Ruby Sass, and versions of Dart Sass prior to 1.11.0 *always* parse
`min()` and `max()` as Sass functions. To create a plain CSS `min()` or
Expand All @@ -243,32 +264,13 @@ combined at build time, so `min(12px % 10, 10%)` will throw an error.
was backwards-incompatible with the global `min()` and `max()` functions, so
that behavior was reverted.

[`min()` and `max()` functions]: https://www.w3.org/TR/css-values-4/#math
[to support the iPhoneX]: https://webkit.org/blog/7929/designing-websites-for-iphone-x/
[special functions]: /documentation/syntax/special-functions/
{% endcompatibility %}

{% headsUp %}
Other calculations don't allow unitless numbers to be added to, subtracted
from, or compared to numbers with units. [`min()`] and [`max()`] are different,
though: for backwards-compatibility with the global Sass `min()` and `max()`
functions which allow unit/unitless mixing for historical reasons, these units
can be mixed as long as they're contained directly within a `min()` or `max()`
calculation.

For instance, `min(5 + 10px, 20px)` will result in `15px`. However
`sqrt(5 + 10px)` will throw an error, as `sqrt(5 + 10px)` was never a global
Sass function, and these are incompatible units.
{% endheadsUp %}

[`min()`] and [`max()`] functions take one or more comma-separated expressions
as parameters.

[`min()`]: https://sass-lang.com/documentation/modules/math#min
[`max()`]: https://sass-lang.com/documentation/modules/math#max

{% codeExample 'min-max' %}
$padding: 12px;
$number: 12.5px;
$step: 15px;

.post {
// Since these max() calls are valid calculation expressions, they're
Expand All @@ -284,22 +286,8 @@ as parameters.
padding-right: max($padding % 10, 20px);
}

.post-image {
// Since these round() calls are valid calculation expressions, they're
// parsed as calculations.
padding-left: round(nearest, $number, $step);
padding-right: round($number + 10px);
padding-bottom: round($number + 10px, $step + 10%);
}

.card {
padding-left: abs(-10px);
padding-right: math.abs(-7.5%);
}
===
$padding: 12px
$number: 12.5px
$step: 15px

.post
// Since these max() calls are valid calculation expressions, they're
Expand All @@ -314,16 +302,6 @@ as parameters.
padding-left: max($padding % 10, 20px)
padding-right: max($padding % 10, 20px)

.post-image
// Since these round() calls are valid calculation expressions, they're
// parsed as calculations.
padding-left: round(nearest, $number, $step)
padding-right: round($number + 10px)
padding-bottom: round($number + 10px, $step + 10%)

.card
padding-left: abs(-10px)
padding-right: math.abs(-7.5%)
===
.post {
padding-left: max(12px, env(safe-area-inset-left));
Expand All @@ -334,23 +312,12 @@ as parameters.
padding-left: 20px;
padding-right: 20px;
}

.post-image {
padding-left: 15px;
padding-right: 23px;
padding-bottom: round(22.5px, 15px + 10%);
}

.card {
padding-left: 10px;
padding-right: 7.5%;
}
{% endcodeExample %}

#### `round()`

{% compatibility 'dart: "1.64.0"', 'libsass: false', 'ruby: false', 'feature: "min and max syntax"' %}
LibSass, Ruby Sass, and versions of Dart Sass prior to 1.64.0 *always* parse
{% compatibility 'dart: "1.65.0"', 'libsass: false', 'ruby: false', 'feature: "min and max syntax"' %}
LibSass, Ruby Sass, and versions of Dart Sass prior to 1.65.0 *always* parse
`round()` as a Sass function. To create a plain CSS calculation for those
implementations, you can write something like
`round(#{$strategy, $number, $step})` instead.
Expand All @@ -362,22 +329,80 @@ should be `nearest`, `up`, `down`, or `to-zero`.

[`round(<strategy>, number, step)`]: https://developer.mozilla.org/en-US/docs/Web/CSS/round#parameter

{% codeExample 'round' %}
$number: 12.5px;
$step: 15px;

.post-image {
// Since these round() calls are valid calculation expressions, they're
// parsed as calculations.
padding-left: round(nearest, $number, $step);
padding-right: round($number + 10px);
padding-bottom: round($number + 10px, $step + 10%);
}

===
$number: 12.5px
$step: 15px

.post-image
// Since these round() calls are valid calculation expressions, they're
// parsed as calculations.
padding-left: round(nearest, $number, $step)
padding-right: round($number + 10px)
padding-bottom: round($number + 10px, $step + 10%)

===
.post-image {
padding-left: 15px;
padding-right: 23px;
padding-bottom: round(22.5px, 15px + 10%);
}
{% endcodeExample %}

#### `abs()`

{% compatibility 'dart: "1.64.0"', 'libsass: false', 'ruby: false', 'feature: "min and max syntax"' %}
LibSass, Ruby Sass, and versions of Dart Sass prior to 1.64.0 *always* parse
{% compatibility 'dart: "1.65.0"', 'libsass: false', 'ruby: false', 'feature: "min and max syntax"' %}
LibSass, Ruby Sass, and versions of Dart Sass prior to 1.65.0 *always* parse
`abs()` as a Sass function. To create a plain CSS calculation for those
implementations, you can write something like `abs(#{$number})` instead.
{% endcompatibility %}

{% headsUp %},
The global `abs(value)` function compatibiliy with [% unit parameters is deprecated].
{% headsUp %}
The global `abs()` function compatibiliy with [% unit parameters is deprecated].
In the future, this will emit a CSS abs() function to be resolved by the browser.

[% unit parameters is deprecated]: /documentation/breaking-changes/abs-percent/
{% endheadsUp %}

The [`abs(value)`] takes in a single expressiona as a parameter and returns the
absolute value of $value. If $value is negative, this returns -$value, and if
$value is positive, it returns $value as-is.
absolute value of `$value`. If `$value` is negative, this returns `-$value`, and if
`$value` is positive, it returns `$value` as-is.

[`abs(value)`]: https://developer.mozilla.org/en-US/docs/Web/CSS/abs
[% unit parameters is deprecated]: /documentation/breaking-changes/abs-percent/

{% codeExample 'abs' %}
.post-image {
// Since these abs() calls are valid calculation expressions, they're
// parsed as calculations.
padding-left: abs(10px);
padding-right: math.abs(-7.5%);
padding-top: abs(1 + 1px);
}

===
.post-image
// Since these abs() calls are valid calculation expressions, they're
// parsed as calculations.
padding-left: abs(-10px)
padding-right: math.abs(-7.5%)
padding-top: abs(1 + 1px)

===
.post-image {
padding-left: 10px;
padding-right: 7.5%;
padding-top: 2px;
}

{% endcodeExample %}

0 comments on commit 4ea8198

Please sign in to comment.