From 23d4c35161c6f6c3807b83e96f1c5f14fe882f6d Mon Sep 17 00:00:00 2001 From: Pamela Lozano Date: Thu, 10 Aug 2023 11:25:15 -0700 Subject: [PATCH] Calc functions breaking change page --- source/_data/documentation.yml | 1 + source/documentation/at-rules/function.md | 28 ++-- .../breaking-changes/calc-functions.md | 123 ++++++++++++++++++ 3 files changed, 138 insertions(+), 14 deletions(-) create mode 100644 source/documentation/breaking-changes/calc-functions.md diff --git a/source/_data/documentation.yml b/source/_data/documentation.yml index 342b1888c..c142e87fe 100644 --- a/source/_data/documentation.yml +++ b/source/_data/documentation.yml @@ -72,6 +72,7 @@ toc: - Duplicate Variable Flags: /documentation/breaking-changes/duplicate-var-flags/ - Default Exports: /documentation/breaking-changes/default-export/ - abs() Percentage: /documentation/breaking-changes/abs-percent/ + - Calc Functions: /documentation/breaking-changes/calc-functions/ - Command Line: /documentation/cli/ :children: - Dart Sass: /documentation/cli/dart-sass/ diff --git a/source/documentation/at-rules/function.md b/source/documentation/at-rules/function.md index 3ffcbaf79..748b5281e 100644 --- a/source/documentation/at-rules/function.md +++ b/source/documentation/at-rules/function.md @@ -18,30 +18,30 @@ Functions are called using the normal CSS function syntax. [`@return` at-rule]: #return {% codeExample 'functions' %} - @function pow($base, $exponent) { - $result: 1; - @for $_ from 1 through $exponent { - $result: $result * $base; + @function fibbonacci($n) { + $sequence: 0 1; + @for $_ from 1 through $n { + $new: nth($sequence, length($sequence)) + nth($sequence, length($sequence) - 1); + $sequence: append($sequence, $new); } - @return $result; + @return nth($sequence, length($sequence)); } .sidebar { float: left; - margin-left: pow(4, 3) * 1px; + margin-left: fibbonacci(4)+px; } === - @function pow($base, $exponent) - $result: 1 - @for $_ from 1 through $exponent - $result: $result * $base - - @return $result - + @function fibbonacci($n) + $sequence: 0 1 + @for $_ from 1 through $n + $new: nth($sequence, length($sequence)) + nth($sequence, length($sequence) - 1) + $sequence: append($sequence, $new) + @return nth($sequence, length($sequence)) .sidebar float: left - margin-left: pow(4, 3) * 1px + margin-left: fibbonacci(4)+px {% endcodeExample %} {% funFact %} diff --git a/source/documentation/breaking-changes/calc-functions.md b/source/documentation/breaking-changes/calc-functions.md new file mode 100644 index 000000000..1cb542640 --- /dev/null +++ b/source/documentation/breaking-changes/calc-functions.md @@ -0,0 +1,123 @@ +--- +title: 'Breaking Change: Calc functions' +introduction: > + Sass has added support for the CSS Values and Units Level 4 specification. + These global functions are now reserved: `round()`, `mod()`, `rem()`, + `sin()`, `cos()`, `tan()`, `asin()`, `acos()`, `atan()`, `atan2()`, `pow()`, + `sqrt()`, `hypot()`, `log()`, `exp()`, `abs()`, and `sign()`. +------------------------------------------------------------------------------- +{% compatibility 'dart: "1.65.0"', 'libsass: false', 'ruby: false' %}{% endcompatibility %} + +The new calc functions are now reserved as global functions. These function +calls will be parsed CSS calculations instead of functions: [`round()`], [`mod()`], +[`rem()`], [`sin()`], [`cos()`], [`tan()`], [`asin()`], [`acos()`], [`atan()`], [`atan2()`], +[`pow()`], [`sqrt()`], [`hypot()`], [`log()`], [`exp()`], [`abs()`], or [`sign()`]. +User-defined functions named after any of these may no longer be called without +a namespace. + +[`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 + +{% codeExample 'calc-function-bad', false %} +@function rem($number) { + @return $number % 10; +} + +.sidebar { + // WRONG, Sass parses `rem()` as a calculation, not as a call to the function + // declared above. This throws an error because `rem()` requires two parameters. + margin-left: rem(9) * 1px; +} +=== +@function rem($number) + @return $number % 10 + +.sidebar + // WRONG, Sass parses `rem()` as a calculation, not as a call to the function + // declared above. This throws an error because `rem()` requires two parameters. + margin-left: rem(9) * 1px +{% endcodeExample %} + +However, if the function is loaded from another file and called with a namespace +it is parsed as a function call. + +{% codeExample 'calc-function-import' %} + // _library.scss + @function rem($number) { + @return $number % 10; + } + --- + // style.scss + @use 'library'; + + .sidebar { + // RIGHT, Sass parses `library.rem()` as a function call rather than + // a calculation because of the namespace. + margin: library.rem(11); + } + === + // _library.sass + @function rem($number) + @return $number % 10 + --- + // style.sass + @use 'library' + + .sidebar + // RIGHT, Sass parses `library.rem()` as a function call rather than + // a calculation because of the namespace. + a: library.rem(11) * 1px + === + .sidebar { + margin: 1; + } +{% endcodeExample %} + +{% headsUp %} + Because calling a function from a module loaded [_without a namespace_] by + writing `@use as *` has the same syntax as calling a global function, + Sass will parse these function calls as calculations, not as calls to the + function defined in the module! + +[_without a namespace_]: /documentation/at-rules/use/#choosing-a-namespace +{% endheadsUp %} + +To preserve the current behavior, use [`meta.call()`] and [`meta.get-function()`]. + +[`meta.get-function()`]: /documentation/modules/meta/#get-function +[`meta.call()`]: /documentation/modules/meta/#call + +{% codeExample 'function-using-meta'%} +@use 'sass:meta'; + +@function rem($number) { + @return $number % 10; +} + +.sidebar { + margin-left: meta.call(meta.get-function("rem"), 9) * 1px; +} +=== +@use 'sass:meta' + +@function rem($number) + @return $number % 10 + +.sidebar + margin-left: meta.call(meta.get-function("rem"), 9) * 1px +{% endcodeExample %} \ No newline at end of file