Calc functions breaking change page

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/

source/documentation/breaking-changes/calc-functions.md

@@ -0,0 +1,121 @@
+---
+title: 'Breaking Change: Calc functions'
+introduction: >
+  Versions of Dart Sass subsequent to 1.65.0 parse the following as calculation
+  functions: `round()`, `mod()`, `rem()`, `sin()`, `cos()`, `tan()`, `asin()`,
+  `acos()`, `atan()`, `atan2()`, `pow()`, `sqrt()`, `hypot()`, `log()`, `exp()`,
+  `abs()`, and `sign()`.
+--------------------------------------------------------------------------------
+
+These calc functions are now reserved words, which means any custom defined
+functions defined with: [`round()`], [`mod()`], [`rem()`], [`sin()`], [`cos()`], [`tan()`],
+[`asin()`], [`acos()`], [`atan()`], [`atan2()`], [`pow()`], [`sqrt()`], [`hypot()`],
+[`log()`], [`exp()`], [`abs()`], or [`sign()`] will be parsed as calculations
+instead of functions.
+
+[`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;
+}
+
+/* This example would parse `rem()` as a calc function, not as the declared
+function above. Since `rem()` requires two parameters, this would throw a
+parameter error. */
+.sidebar {
+  margin-left: rem(9) * 1px;
+}
+
+===
+@function rem($number)
+  @return $number % 10
+
+// This example would parse `rem()` as a calc function, not as the declared
+// function above. Since `rem()` requires two parameters, this would throw a
+// parameter error.
+.sidebar 
+  margin-left: rem(9) * 1px
+
+{% endcodeExample %}
+
+However, if the custom `rem()` function was imported to another file, it would
+be parsed as the declared function since it's assigned to a different namespace.
+
+{% codeExample 'calc-function-import', false %}
+<===> foo.scss
+@function rem($number) {
+  @return $number % 10;
+}
+
+<===> main.scss
+// This example would not throw an error.
+@use 'foo';
+
+.sidebar {
+  a: foo.rem(9) * 1px;
+}
+===
+<===> foo.scss
+@function rem($number)
+  @return $number % 10
+
+<===> main.scss
+// This example would not throw an error.
+@use 'foo'
+
+.sidebar
+  a: foo.rem(9) * 1px
+
+{% endcodeExample %}
+
+{% headsUp %}
+  If the module was imported [_without a namespace_] 
+  calc functions would override the custom declared functions.
+  For instance, `@use 'foo' as *` would change the call to `a: rem(10)`,
+  which would result in an error.
+
+[_without a namespace_]: /documentation/at-rules/use/#choosing-a-namespace
+{% endheadsUp %}
+
+To preserve the current behavior, use the [`call()`] and [`get-function()`] methods
+from the `meta` module.
+
+[`get-function()`]:http://localhost:8080/documentation/modules/meta/#get-function
+[`call()`]: /documentation/modules/meta/#call
+{% codeExample 'function-using-meta', false %}
+@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 %}