Merge pull request sass#54 from oddbird/builtin-modules

Port Built-in Modules docs

eleventy.config.js

@@ -16,6 +16,7 @@ const datesPlugin = require('./source/helpers/dates.ts').default;
 const { liquidEngine, markdownEngine } = require('./source/helpers/engines.ts');
 const pagesPlugin = require('./source/helpers/pages.ts').default;
 const typePlugin = require('./source/helpers/type.ts').default;
+const functionPlugin = require('./source/helpers/function.ts').default;
 
 /** @param {import('@11ty/eleventy').UserConfig} eleventyConfig */
 module.exports = (eleventyConfig) => {
@@ -43,6 +44,7 @@ module.exports = (eleventyConfig) => {
   eleventyConfig.addPlugin(datesPlugin);
   eleventyConfig.addPlugin(pagesPlugin);
   eleventyConfig.addPlugin(typePlugin);
+  eleventyConfig.addPlugin(functionPlugin);
 
   // rss plugin
   eleventyConfig.addLiquidFilter('absoluteUrl', absoluteUrl);

source/_includes/code_snippets/example-first-class-function.liquid

@@ -0,0 +1,59 @@
+{% comment -%}
+  TODO(nweiz): auto-generate this CSS once we're compiling with Dart Sass
+{%- endcomment -%}
+{% codeExample 'first-class-function' %}
+  @use "sass:list";
+  @use "sass:meta";
+  @use "sass:string";
+
+  /// Return a copy of $list with all elements for which $condition returns `true`
+  /// removed.
+  @function remove-where($list, $condition) {
+    $new-list: ();
+    $separator: list.separator($list);
+    @each $element in $list {
+      @if not meta.call($condition, $element) {
+        $new-list: list.append($new-list, $element, $separator: $separator);
+      }
+    }
+    @return $new-list;
+  }
+
+  $fonts: Tahoma, Geneva, "Helvetica Neue", Helvetica, Arial, sans-serif;
+
+  content {
+    @function contains-helvetica($string) {
+      @return string.index($string, "Helvetica");
+    }
+    font-family: remove-where($fonts, meta.get-function("contains-helvetica"));
+  }
+  ===
+  @use "sass:list"
+  @use "sass:meta"
+  @use "sass:string"
+
+  /// Return a copy of $list with all elements for which $condition returns `true`
+  /// removed.
+  @function remove-where($list, $condition)
+    $new-list: ()
+    $separator: list.separator($list)
+    @each $element in $list
+      @if not meta.call($condition, $element)
+        $new-list: list.append($new-list, $element, $separator: $separator)
+
+
+    @return $new-list
+
+
+  $fonts: Tahoma, Geneva, "Helvetica Neue", Helvetica, Arial, sans-serif
+
+  .content
+    @function contains-helvetica($string)
+      @return string.index($string, "Helvetica")
+
+    font-family: remove-where($fonts, meta.get-function("contains-helvetica"))
+  ===
+  .content {
+    font-family: Tahoma, Geneva, Arial, sans-serif;
+  }
+{% endcodeExample %}

source/_includes/code_snippets/example-list-index.liquid

@@ -0,0 +1,9 @@
+{% codeExample 'example-list-index', false %}
+  @debug list.index(1px solid red, 1px); // 1
+  @debug list.index(1px solid red, solid); // 2
+  @debug list.index(1px solid red, dashed); // null
+  ===
+  @debug list.index(1px solid red, 1px)  // 1
+  @debug list.index(1px solid red, solid)  // 2
+  @debug list.index(1px solid red, dashed)  // null
+{% endcodeExample %}

source/_includes/code_snippets/example-list-nth.liquid

@@ -0,0 +1,7 @@
+{% codeExample 'example-list-nth', false %}
+  @debug list.nth(10px 12px 16px, 2); // 12px
+  @debug list.nth([line1, line2, line3], -1); // line3
+  ===
+  @debug list.nth(10px 12px 16px, 2)  // 12px
+  @debug list.nth([line1, line2, line3], -1)  // line3
+{% endcodeExample %}

source/_includes/code_snippets/example-map-get.liquid

@@ -0,0 +1,11 @@
+{% codeExample 'map-get', false %}
+  $font-weights: ("regular": 400, "medium": 500, "bold": 700);
+
+  @debug map.get($font-weights, "medium"); // 500
+  @debug map.get($font-weights, "extra-bold"); // null
+  ===
+  $font-weights: ("regular": 400, "medium": 500, "bold": 700)
+
+  @debug map.get($font-weights, "medium")  // 500
+  @debug map.get($font-weights, "extra-bold")  // null
+{% endcodeExample %}

source/code-snippets/example-mixin-arbitrary-keyword-arguments.liquid → source/_includes/code_snippets/example-mixin-arbitrary-keyword-arguments.liquid

@@ -1,4 +1,4 @@
-{% codeExample 'mixin-arbitrary-keyword' %}
+{% codeExample 'mixin-arbitrary-kwargs' %}
   @use "sass:meta";
 
   @mixin syntax-colors($args...) {

source/_includes/doc_snippets/built-in-module-status.liquid

@@ -0,0 +1,4 @@
+{% compatibility 'dart: "1.23.0"', 'libsass: false', 'ruby: false' %}
+  Only Dart Sass currently supports loading built-in modules with `@use`. Users
+  of other implementations must call functions using their global names instead.
+{% endcompatibility %}

source/_includes/doc_snippets/call-impl-status.liquid

@@ -0,0 +1,11 @@
+{% compatibility 'dart: true', 'libsass: "3.5.0"', 'ruby: "3.5.0"', 'feature: "Argument Type"' %}
+  In older versions of LibSass and Ruby Sass, the [`call()` function][] took a
+  string representing a function's name. This was changed to take a function
+  value instead in preparation for a new module system where functions are no
+  longer global and so a given name may not always refer to the same function.
+
+  [`call()` function]: /documentation/modules/meta#call
+
+  Passing a string to `call()` still works in all implementations, but it's
+  deprecated and will be disallowed in future versions.
+{% endcompatibility %}

source/_includes/doc_snippets/module-system-function-status.liquid

@@ -0,0 +1,3 @@
+{% compatibility 'dart: "1.23.0"', 'libsass: false', 'ruby: false' %}
+  Only Dart Sass currently supports this function.
+{% endcompatibility %}

source/_includes/function.liquid

@@ -0,0 +1,5 @@
+{% for name in names offset: 1 %}<div id="{{ name }}">{% endfor -%}
+  <div class="sl-c-callout sl-c-callout--function" id="{{ names[0] }}"><pre class="signature language-scss"><a class="anchor" href="#{{ names[0] }}"></a><code class="language-scss">{{ signatures }}{% if returns %} <span class="token comment">//=&gt; {{ returns }}</span>{% endif %}</code></pre>
+    {{ content }}
+  </div>
+{%- for name in names offset: 1 %}</div>{% endfor %}

source/documentation/at-rules/at-root.liquid

@@ -10,7 +10,7 @@ introduction: >
   [selector functions](/documentation/modules/selector).
 ---
 
-{% render 'code-snippets/example-advanced-nesting' %}
+{% render 'code_snippets/example-advanced-nesting' %}
 
 {% markdown %}
   The `@at-root` rule is necessary here because Sass doesn't know what

source/documentation/at-rules/control/each.liquid

@@ -11,7 +11,7 @@ introduction: >
   the given variable name.
 ---
 
-{% render 'code-snippets/example-each-list' %}
+{% render 'code_snippets/example-each-list' %}
 
 {% markdown %}
   ## With Maps
@@ -22,7 +22,7 @@ introduction: >
   second.
 {% endmarkdown %}
 
-{% render 'code-snippets/example-each-map' %}
+{% render 'code_snippets/example-each-map' %}
 
 {% markdown %}
   ## Destructuring

source/documentation/at-rules/control/if.liquid

@@ -10,7 +10,7 @@ introduction: >
   it’s not.
 ---
 
-{% render 'code-snippets/example-if' %}
+{% render 'code_snippets/example-if' %}
 
 {% markdown %}
   ## `@else`
@@ -146,4 +146,4 @@ introduction: >
   }
 {% endcodeExample %}
 
-{% render 'documentation/snippets/truthiness-and-falsiness' %}
+{% render 'doc_snippets/truthiness-and-falsiness' %}

source/documentation/at-rules/control/while.liquid

@@ -52,4 +52,4 @@ introduction: >
   [`@for`]: /documentation/at-rules/control/for
 {% endheadsUp %}
 
-{% render 'documentation/snippets/truthiness-and-falsiness' %}
+{% render 'doc_snippets/truthiness-and-falsiness' %}

source/documentation/at-rules/extend.liquid

@@ -204,7 +204,7 @@ introduction: >
   [placeholder selectors]: /documentation/style-rules/placeholder-selectors
 {% endmarkdown %}
 
-{% render 'code-snippets/example-placeholder' %}
+{% render 'code_snippets/example-placeholder' %}
 
 {% markdown %}
   ### Private Placeholders

source/documentation/at-rules/import.liquid

@@ -484,7 +484,7 @@ introduction: >
 {% markdown %}
   ## Import and Modules
 
-  {% render 'documentation/snippets/module-system-status' %}
+  {% render 'doc_snippets/module-system-status' %}
 
   Sass's [module system][] integrates seamlessly with `@import`, whether you're
   importing a file that contains `@use` rules or loading a file that contains

source/documentation/at-rules/mixin.liquid

@@ -277,11 +277,12 @@ introduction: >
 
   [`meta.keywords()` function]: /documentation/modules/meta#keywords
   [map]: /documentation/values/maps
-
-  <!-- TODO(nweiz): auto-generate this CSS once we're compiling with Dart Sass -->
 {% endmarkdown %}
 
-{% render 'code-snippets/example-mixin-arbitrary-keyword-arguments' %}
+{% comment -%}
+  TODO(nweiz): auto-generate this CSS once we're compiling with Dart Sass
+{%- endcomment -%}
+{% render 'code_snippets/example-mixin-arbitrary-keyword-arguments' %}
 
 {% funFact %}
   If you don't ever pass an argument list to the [`meta.keywords()` function][],
@@ -408,7 +409,9 @@ introduction: >
   [map]: /documentation/values/maps
 {% endheadsUp %}
 
-<!-- TODO(nweiz): auto-generate this CSS once we're compiling with Dart Sass -->
+{% comment -%}
+  TODO(nweiz): auto-generate this CSS once we're compiling with Dart Sass
+{%- endcomment -%}
 {% codeExample 'passing-arguments-to-content-blocks', false %}
   @mixin media($types...) {
     @each $type in $types {

source/documentation/at-rules/use.liquid

@@ -3,7 +3,7 @@ title: "@use"
 table_of_contents: true
 eleventyComputed:
   before_introduction: >
-    {% render 'documentation/snippets/module-system-status' %}
+    {% render 'doc_snippets/module-system-status' %}
 introduction: >
   The `@use` rule loads [mixins](/documentation/at-rules/mixin),
   [functions](/documentation/at-rules/function), and
@@ -298,7 +298,7 @@ introduction: >
   [`!default` flag]: /documentation/variables#default-values
 {% endmarkdown %}
 
-{% render 'code-snippets/example-use-with' %}
+{% render 'code_snippets/example-use-with' %}
 
 {% markdown %}
   ### With Mixins

source/documentation/breaking-changes/bogus-combinators.liquid

@@ -57,7 +57,7 @@ introduction: >
   leading or trailing combinators that end up in selectors after nesting is
   resolved.
 
-  {% render 'documentation/snippets/silence-deprecations' %}
+  {% render 'doc_snippets/silence-deprecations' %}
 
   In addition, we'll immediately start omitting selectors that we know to be
   invalid CSS from the compiled CSS, with one exception: we _won't_ omit

source/documentation/breaking-changes/slash-div.liquid

@@ -61,7 +61,7 @@ introduction: >
   instead.
 {% endmarkdown %}
 
-{% render 'documentation/snippets/silence-deprecations' %}
+{% render 'doc_snippets/silence-deprecations' %}
 
 {% codeExample 'math-div', false %}
   @use "sass:math";

source/documentation/breaking-changes/strict-unary.liquid

@@ -51,7 +51,7 @@ introduction: >
   We'll make this an error in Dart Sass 2.0.0, but until then it'll just emit a
   deprecation warning.
 
-  {% render 'documentation/snippets/silence-deprecations' %}
+  {% render 'doc_snippets/silence-deprecations' %}
 
   ## Automatic Migration
 

source/documentation/cli/dart-sass.md

@@ -223,7 +223,7 @@ Compiled themes/light.scss to public/css/light.css.
 
 {% compatibility 'dart: "1.3.0"' %}{% endcompatibility %}
 
-{% render 'documentation/snippets/source-maps' %}
+{% render 'doc_snippets/source-maps' %}
 
 Dart Sass generates source maps by default for every CSS file it emits.
 

source/documentation/cli/migrator.md

@@ -33,7 +33,7 @@ see what changes will be made without actually saving them, you can pass
 [--dry-run]: #dry-run
 [--verbose]: #verbose
 
-{% render 'code-snippets/example-module-migrator' %}
+{% render 'code_snippets/example-module-migrator' %}
 
 ## Installation
 
@@ -259,7 +259,7 @@ before, including:
   [`--migrate-deps` option]: #migrate-deps
 {% endheadsUp %}
 
-{% render 'code-snippets/example-module-migrator' %}
+{% render 'code_snippets/example-module-migrator' %}
 
 #### Loading Dependencies