From 8e8e9d7d5ee96e2ff141bca6bb1ab79931abc2aa Mon Sep 17 00:00:00 2001 From: Israel-4Ever Date: Thu, 17 Aug 2023 12:05:40 -0700 Subject: [PATCH] Revert "Merge pull request #755 from sass/calcfunctions" This reverts commit 495d514a215712089ad1de89c1533c7f534260ee, reversing changes made to e058a658523aad64b45a9b81a13b16574cdbb2da. --- source/_data/documentation.yml | 1 - .../breaking-changes/abs-percent.md | 21 -- .../documentation/breaking-changes/index.md | 4 - source/documentation/values/calculations.md | 243 +++--------------- 4 files changed, 39 insertions(+), 230 deletions(-) delete mode 100644 source/documentation/breaking-changes/abs-percent.md diff --git a/source/_data/documentation.yml b/source/_data/documentation.yml index 342b1888c..3f43cb64a 100644 --- a/source/_data/documentation.yml +++ b/source/_data/documentation.yml @@ -71,7 +71,6 @@ toc: - CSS Variable Syntax: /documentation/breaking-changes/css-vars/ - Duplicate Variable Flags: /documentation/breaking-changes/duplicate-var-flags/ - Default Exports: /documentation/breaking-changes/default-export/ - - abs() Percentage: /documentation/breaking-changes/abs-percent/ - Command Line: /documentation/cli/ :children: - Dart Sass: /documentation/cli/dart-sass/ diff --git a/source/documentation/breaking-changes/abs-percent.md b/source/documentation/breaking-changes/abs-percent.md deleted file mode 100644 index d1aeddeca..000000000 --- a/source/documentation/breaking-changes/abs-percent.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: 'Breaking Change: abs() Percentage' -introduction: > - Sass has historically supported the `abs()` function. After CSS supported - calculations in Values and Units Level 4, we had to workaround - backwards-compatibility. However, for the `abs()` function we posses a - compatibility problem supporting the `%` unit. ---- - -The `abs()` global function in Sass supported the `%` unit as an input and would -resolve the `abs()` function before resolving the `%` value. For instance, if -the input was `abs(10%)` the function will return `10%`. As a result, if the -value of `10%` represented `-50px` the function would return `-50px`. - -However, the CSS `abs()` abs function will resolve the `%` before resolving the -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()` instead. - diff --git a/source/documentation/breaking-changes/index.md b/source/documentation/breaking-changes/index.md index 3ab76a5e5..09985f339 100644 --- a/source/documentation/breaking-changes/index.md +++ b/source/documentation/breaking-changes/index.md @@ -22,10 +22,6 @@ 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. diff --git a/source/documentation/values/calculations.md b/source/documentation/values/calculations.md index bfe7c22c3..af477d821 100644 --- a/source/documentation/values/calculations.md +++ b/source/documentation/values/calculations.md @@ -156,119 +156,59 @@ CSS to unitless numbers: @debug calc(-infinity) < math.$min-number // true {% endcodeExample %} -## Calculation Functions +## `min()` and `max()` -{% 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()`]. -* 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()`]: 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 -[`asin()`]: https://developer.mozilla.org/en-US/docs/Web/CSS/asin -[`acos()`]: https://developer.mozilla.org/en-US/docs/Web/CSS/acos -[`atan()`]: https://developer.mozilla.org/en-US/docs/Web/CSS/atan -[`atan2()`]: https://developer.mozilla.org/en-US/docs/Web/CSS/atan2 -[`pow()`]: https://developer.mozilla.org/en-US/docs/Web/CSS/pow -[`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 -[`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 -[`sign()`]: https://developer.mozilla.org/en-US/docs/Web/CSS/sign - -### Legacy Global Functions - -CSS added support for [mathematical expressions] in Values and Units Level -4. However, Sass supported its own [`round()`], [`abs()`], [`min()`] and -[`max()`] long before this, and it needed to be backwards-compatible with all -those existing stylesheets. This led to the need for extra-special syntactic -cleverness. - -[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 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"' %} +{% compatibility 'dart: ">=1.11.0 <1.42.0"', 'libsass: false', 'ruby: false', 'feature: "Special function 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 `max()` call for those implementations, you can write something like `unquote("min(#{$padding}, env(safe-area-inset-left))")` instead. - CSS added support for [`min()` and `max()` functions] in Values and Units - Level 4, from where they were quickly adopted by Safari [to support the iPhoneX]. - Since we already supported `min()` and `max()` as legacy Sass functions, we - had to implement logic for backwards-compatibility and for support as CSS - functions. - - Versions of Dart Sass between 1.11.0 and 1.40.0, and between 1.40.1 - and 1.42.0 parse `min()` and `max()` functions as [special functions] if - they're valid plain CSS, but parse them as Sass functions if they contain Sass - features other than interpolation, like variables or function calls. + Versions of Dart Sass between 1.11.0 and 1.40.0, and between 1.40.1 and 1.42.0 + parse `min()` and `max()` functions as [special functions] if they're valid + plain CSS, but parse them as Sass functions if they contain Sass features + other than interpolation, like variables or function calls. Dart Sass 1.41.0 parses `min()` and `max()` functions as calculations, but doesn't allow unitless numbers to be combined with numbers with units. This 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/ + [special functions]: /documentation/syntax/special-functions {% endcompatibility %} +CSS added support for [`min()` and `max()` functions] in Values and Units Level +4, from where they were quickly adopted by Safari [to support the iPhoneX]. But +Sass supported its own [`min()`] and [`max()`] functions long before this, and +it needed to be backwards-compatible with all those existing stylesheets. This +led to the need for extra-special syntactic cleverness. + +[`min()` and `max()` functions]: https://drafts.csswg.org/css-values-4/#calc-notation +[to support the iPhoneX]: https://webkit.org/blog/7929/designing-websites-for-iphone-x/ +[`min()`]: /documentation/modules/math#min +[`max()`]: /documentation/modules/math#max + +If a `min()` or `max()` 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 Sass's core `min()` or `max()` 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()` 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. +{% endheadsUp %} + {% codeExample 'min-max' %} $padding: 12px; @@ -285,7 +225,6 @@ combined at build time, so `min(12px % 10, 10%)` will throw an error. padding-left: max($padding % 10, 20px); padding-right: max($padding % 10, 20px); } - === $padding: 12px @@ -301,108 +240,4 @@ combined at build time, so `min(12px % 10, 10%)` will throw an error. // SassScript function calls. padding-left: max($padding % 10, 20px) padding-right: max($padding % 10, 20px) - - === - .post { - padding-left: max(12px, env(safe-area-inset-left)); - padding-right: max(12px, env(safe-area-inset-right)); - } - - .sidebar { - padding-left: 20px; - padding-right: 20px; - } {% endcodeExample %} - -#### `round()` - -{% 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. -{% endcompatibility %} - -The [`round(, number, step)`] function accepts an optional rounding -strategy, a value to be rounded and a rounding interval `step`. `strategy` -should be `nearest`, `up`, `down`, or `to-zero`. - -[`round(, 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.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()` 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. - -[`abs(value)`]: https://developer.mozilla.org/en-US/docs/Web/CSS/abs - -{% 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 %} \ No newline at end of file