From e157cc4a2d28a2bf5e28019a111fe966d135970a Mon Sep 17 00:00:00 2001
From: Pamela Lozano <pamelalozano16@gmail.com>
Date: Thu, 10 Aug 2023 11:25:15 -0700
Subject: [PATCH] Calc functions breaking change page

---
 source/_data/documentation.yml                |   1 +
 .../breaking-changes/calc-functions.md        | 121 ++++++++++++++++++
 2 files changed, 122 insertions(+)
 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/breaking-changes/calc-functions.md b/source/documentation/breaking-changes/calc-functions.md
new file mode 100644
index 000000000..c4f693290
--- /dev/null
+++ b/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 %}
\ No newline at end of file