Merge branch 'wip.reference' into function-return

helpers/sass_helpers.rb

@@ -300,17 +300,27 @@ module SassHelpers
 
   # Renders a status dashboard for each implementation's support for a feature.
   #
-  # Each implementation's value can be `true`, indicating that that
-  # implementation fully supports the feature; `false`, indicating that it does
-  # not yet support the feature; or a string, indicating the version it started
-  # supporting the feature.
+  # Each implementation's value can be:
+  #
+  # * `true`, indicating that that implementation fully supports the feature;
+  # * `false`, indicating that it does not yet support the feature at all;
+  # * `:partial`, indicating that it has limited or incorrect support for the
+  #   feature;
+  # * or a string, indicating the version it started supporting the feature.
   #
   # When possible, prefer using the start version rather than `true`.
   #
+  # If `feature` is passed, it should be a terse (one- to three-word)
+  # description of the particular feature whose compatibility is described. This
+  # should be used whenever the status isn't referring to the entire feature
+  # being described by the surrounding prose.
+  #
   # This takes an optional Markdown block that should provide more information
   # about the implementation differences or the old behavior.
-  def impl_status(dart: nil, libsass: nil, ruby: nil, node: nil)
-    contents = []
+  def impl_status(dart: nil, libsass: nil, ruby: nil, node: nil, feature: nil)
+    compatibility = feature ? "Compatibility (#{feature}):" : "Compatibility:"
+
+    contents = [content_tag(:div, compatibility, class: "compatibility")]
     contents << _impl_status_row('Dart Sass', dart) unless dart.nil?
     contents << _impl_status_row('LibSass', libsass) unless libsass.nil?
     contents << _impl_status_row('Node Sass', node) unless node.nil?
@@ -324,7 +334,7 @@ module SassHelpers
 
     if block_given?
       # Get rid of extra whitespace to avoid more bogus <p> tags.
-      _concat(content_tag :div, _render_markdown(_capture {yield}).strip, class: 'sl-c-callout')
+      _concat(content_tag :div, _render_markdown(_capture {yield}).strip, class: 'sl-c-callout sl-c-callout--impl-status')
     end
   end
 
@@ -335,6 +345,8 @@ module SassHelpers
         "✓"
       elsif status == false
         "✗"
+      elsif status == :partial
+        "partial"
       else
         "since #{status}"
       end
@@ -386,7 +398,10 @@ MARKDOWN
 
     html = content_tag :div, [
       content_tag(:pre, [
-        content_tag(:code, merged_signatures)
+        # Make sure there's no whitespace between these two, since they're in a
+        # <pre>.
+        content_tag(:a, '', class: 'anchor', href: "##{names.first}") +
+          content_tag(:code, merged_signatures)
       ], class: 'signature highlight scss'),
 
       _render_markdown(_capture {yield})

source/assets/css/components/_callouts.scss

@@ -21,6 +21,9 @@
     };
 
     .signature {
+      // Make sure permalinks are visible.
+      overflow: visible;
+
       margin: {
         right: -1rem;
         left: -1rem;
@@ -28,6 +31,16 @@
     }
   }
 
+  &--impl-status {
+    font-size: 0.8em;
+    margin-top: -1rem;
+    padding: 0.8rem;
+
+    .sl-c-callout & {
+      background: lighten($sl-color--pale-sky, 53%);
+    }
+  }
+
   > *:first-child { margin-top: 0; }
 
   > *:last-child { margin-bottom: 0; }

source/assets/css/components/_link-header.scss.erb

@@ -1,12 +1,9 @@
-h1, h2, h3, h4, h5, h6 {
+h1, h2, h3, h4, h5, h6, .signature {
   a.anchor {
     display: block;
     float: left;
     vertical-align: middle;
-    margin: {
-      left: -1.5rem;
-      top: -3px;
-    }
+    margin-top: -3px;
     width: 1.5rem;
     background: none;
     border: 0;
@@ -24,6 +21,12 @@ h1, h2, h3, h4, h5, h6 {
   &:hover a.anchor::after {
     visibility: visible;
   }
+}
+
+h1, h2, h3, h4, h5, h6 {
+  a.anchor {
+    margin-left: -1.5rem;
+  }
 
   &:target {
     animation-name: highlight-header;
@@ -40,3 +43,24 @@ h1, h2, h3, h4, h5, h6 {
     background-color: unset;
   }
 }
+
+.signature {
+  a.anchor {
+    margin-left: -2.5rem;
+  }
+
+  .sl-c-callout--function:target & {
+    animation-name: highlight-signature;
+    animation-duration: 5s;
+  }
+}
+
+@keyframes highlight-signature {
+  from {
+    background-color: $sl-color--dawn-pink;
+  }
+
+  to {
+    background-color: <%= Rouge::Themes::Github.get_style(Rouge::Token::Tokens::Text)[:bg] %>;
+  }
+}

source/assets/css/components/_lists.scss

@@ -57,10 +57,34 @@
     &:first-child { border: 0; }
   }
 
+  .compatibility {
+    font-weight: 600;
+    opacity: 0.5;
+
+    + div { border: 0; }
+  }
+
   dt,
   dd {
     padding-left: 1rem;
 
     &:first-child { padding-left: 0; }
   }
+
+  &.impl-status {
+    font-size: 0.8em;
+    margin-top: -1em;
+
+    a {
+      transition: transform 0.1s;
+      border-bottom: none;
+      background: none;
+      cursor: pointer;
+      width: 19px;
+      text-align: center;
+      transform-origin: 8px 11px;
+
+      &.expanded { transform: rotate(90deg); }
+    }
+  }
 }

source/assets/js/sass.js

@@ -47,7 +47,7 @@ $(function() {
                 .prepend("<a href='#example-" + id + "-css'>CSS</a>"));
     }
 
-    figure.prepend(ul).tabs({active: hasCssTab ? 1 : 0});
+    figure.prepend(ul).tabs({active: 0});
   });
 
   // Switch ALL the tabs (Sass/SCSS) together
@@ -83,7 +83,7 @@ $(function() {
     details.hide();
     expandLink.click(function() {
       details.toggle();
-      expandLink.text(expandLink.text() == "▶" ? "▼" : "▶");
+      expandLink.toggleClass("expanded");
     });
   });
 });

source/documentation/at-rules/css.html.md.erb

@@ -3,7 +3,7 @@ title: CSS At-Rules
 table_of_contents: true
 ---
 
-<% impl_status dart: '1.15.0', libsass: false, ruby: false do %>
+<% impl_status dart: '1.15.0', libsass: false, ruby: false, feature: "Name Interpolation" do %>
   LibSass, Ruby Sass, and older versions of Dart Sass don't support
   [interpolation][] in at-rule names. They do support interpolation in values.
 
@@ -64,7 +64,7 @@ having to rewrite the style rule's selector.
 
 ## `@media`
 
-<% impl_status dart: '1.11.0', libsass: false, ruby: '3.7.0' do %>
+<% impl_status dart: '1.11.0', libsass: false, ruby: '3.7.0', feature: 'Range Syntax' do %>
   LibSass and older versions of Dart Sass and Ruby Sass don't support media
   queries with features written in a [range context][]. They do support other
   standard media queries.

source/documentation/at-rules/extend.html.md.erb

@@ -238,7 +238,7 @@ avoid cascade headaches and make it easier to configure down the line.
 
 ### Disallowed Selectors
 
-<% impl_status dart: true, libsass: false, ruby: false do %>
+<% impl_status dart: true, libsass: false, ruby: false, feature: "No Compound Extensions" do %>
   LibSass and Ruby Sass currently allow complex selectors like `.message.info` to
   be extended. However, this behavior didn't match the definition of `@extend`:
   instead of styling elements that matched the extending selector as though it had

source/documentation/at-rules/import.html.md.erb

@@ -314,7 +314,7 @@ nested import are still defined globally, though.
 
 ## Importing CSS
 
-<% impl_status dart: '1.11.0', libsass: false, ruby: false do %>
+<% impl_status dart: '1.11.0', libsass: :partial, ruby: false do %>
   LibSass supports importing files with the extension `.css`, but contrary to
   the specification they're treated as SCSS files rather than being parsed as
   CSS. This behavior has been deprecated, and an update is in the works to

source/documentation/at-rules/mixin.html.md.erb

@@ -364,10 +364,7 @@ the `@content` rule.
 
 ### Passing Arguments to Content Blocks
 
-<% impl_status dart: '1.15.0', libsass: false, ruby: false do %>
-  LibSass, Ruby Sass, and older versions of Dart Sass don't support passing
-  arguments to content blocks.
-<% end %>
+<% impl_status dart: '1.15.0', libsass: false, ruby: false %>
 
 A mixin can pass arguments to its content block the same way it would pass
 arguments to another mixin by writing `@content(<arguments...>)`. The user

source/documentation/functions/color.html.md.erb

@@ -344,7 +344,7 @@ SIGNATURE
             'hsla($hue $saturation $lightness / $alpha)',
             'hsla($hue, $saturation, $lightness, $alpha: 1)',
             returns: 'color' do %>
-  <% impl_status dart: '1.15.0', libsass: false, ruby: false do %>
+  <% impl_status dart: '1.15.0', libsass: false, ruby: false, feature: "Level 4 Syntax" do %>
     LibSass and Ruby Sass only support the following signatures:
 
     * `hsl($hue, $saturation, $lightness)`
@@ -355,7 +355,7 @@ SIGNATURE
     `hsl()` is used.
   <% end %>
 
-  <% impl_status dart: true, libsass: false, ruby: '3.7.0' do %>
+  <% impl_status dart: true, libsass: false, ruby: '3.7.0', feature: "Percent Alpha" do %>
     LibSass and older versions of Ruby Sass don't support alpha values specified as
     percentages.
   <% end %>
@@ -644,7 +644,7 @@ SIGNATURE
             'rgba($red, $green, $blue, $alpha: 1)',
             'rgba($color, $alpha)',
             returns: 'color' do %>
-  <% impl_status dart: '1.15.0', libsass: false, ruby: false do %>
+  <% impl_status dart: '1.15.0', libsass: false, ruby: false, feature: "Level 4 Syntax" do %>
     LibSass and Ruby Sass only support the following signatures:
 
     * `rgb($red, $green, $blue)`
@@ -656,7 +656,7 @@ SIGNATURE
     `rgb()` is used.
   <% end %>
 
-  <% impl_status dart: true, libsass: false, ruby: '3.7.0' do %>
+  <% impl_status dart: true, libsass: false, ruby: '3.7.0', feature: "Percent Alpha" do %>
     LibSass and older versions of Ruby Sass don't support alpha values specified
     as percentages.
   <% end %>

source/documentation/interpolation.html.md.erb

@@ -44,7 +44,7 @@ introduction: >
 
 ## In SassScript
 
-<% impl_status dart: true, libsass: false, ruby: '4.0.0 (unreleased)' do %>
+<% impl_status dart: true, libsass: false, ruby: '4.0.0 (unreleased)', feature: "Modern Syntax" do %>
   LibSass and Ruby Sass currently use an older syntax for parsing interpolation
   in SassScript. For most practical purposes it works the same, but it can
   behave strangely around [operators][]. See [this document][] for details.

source/documentation/js-api.html.md.erb

@@ -219,7 +219,7 @@ These options control how Sass loads it input files.
 
 #### `file`
 
-<% impl_status dart: '1.11.0', node: false do %>
+<% impl_status dart: '1.11.0', node: :partial, feature: "Plain CSS Files" do %>
   Node Sass and older versions of Dart Sass support loading files with the
   extension `.css`, but contrary to the specification they're treated as SCSS
   files rather than being parsed as CSS. This behavior has been deprecated in
@@ -284,7 +284,7 @@ h1
 
 ### `includePaths`
 
-<% impl_status dart: '1.15.0', node: '3.9.0' do %>
+<% impl_status dart: '1.15.0', node: '3.9.0', feature: "SASS_PATH" do %>
   Earlier versions of Dart Sass and Node Sass didn't support the `SASS_PATH`
   environment variable.
 <% end %>
@@ -719,7 +719,7 @@ h1 {
 
 #### `importer`
 
-<% impl_status dart: false, node: '3.0.0' do %>
+<% impl_status dart: true, node: '3.0.0' do %>
   Versions of Node Sass before 3.0.0 don't support arrays of importers,
   nor do they support importers that return `Error` objects.
 

source/documentation/operators/equality.html.md.erb

@@ -2,7 +2,7 @@
 title: Equality Operators
 ---
 
-<% impl_status dart: true, libsass: false, ruby: '4.0.0 (unreleased)' do %>
+<% impl_status dart: true, libsass: false, ruby: '4.0.0 (unreleased)', feature: "Unitless Equality" do %>
   LibSass and older versions of Ruby Sass consider numbers without units to be
   equal to the same numbers with any units. This behavior was deprecated and has
   been removed from more recently releases because it violates [transitivity][].

source/documentation/operators/numeric.html.md.erb

@@ -129,7 +129,7 @@ is met:
 * The result is stored in a variable or returned by a function.
 * The operation is surrounded by parentheses, unless those parentheses are
   outside a list that contains the operation.
-* The result is used as part of another operation.
+* The result is used as part of another operation (other than `/`).
 
 If you want to force `/` to be used as a separator, you can write it as
 `#{<expression>} / #{<expression>}`.

source/documentation/snippets/_call-impl-status.html.erb

@@ -1,4 +1,4 @@
-<% impl_status dart: true, libsass: '3.5.0', ruby: '3.5.0' do %>
+<% impl_status dart: true, libsass: '3.5.0', ruby: '3.5.0', feature: 'Argument Type' do %>
   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

source/documentation/style-rules/declarations.html.md.erb

@@ -130,7 +130,7 @@ compile that declaration to CSS at all.
 
 ## Custom Properties
 
-<% impl_status dart: true, libsass: '3.5.0', ruby: '3.5.0' do %>
+<% impl_status dart: true, libsass: '3.5.0', ruby: '3.5.0', feature: 'SassScript Syntax' do %>
   Older versions of LibSass and Ruby Sass parsed custom property declarations
   just like any other property declaration, allowing the full range of
   SassScript expressions as values. Even when using these versions, it's

source/documentation/syntax/parsing.html.md.erb

@@ -7,7 +7,7 @@ introduction: >
 
 ## Input Encoding
 
-<% impl_status(dart: false, libsass: true, ruby: true) do %>
+<% impl_status dart: false, libsass: true, ruby: true do %>
   Dart Sass currently *only* supports the UTF-8 encoding. As such, it's safest
   to encode all Sass stylesheets as UTF-8.
 <% end %>

source/documentation/syntax/special-functions.html.md.erb

@@ -124,7 +124,7 @@ Nothing is interpreted as a SassScript expression, with the exception that
 
 ## `min()` and `max()`
 
-<% impl_status(dart: "1.11.0", libsass: false, ruby: false) do %>
+<% impl_status dart: "1.11.0", libsass: false, ruby: false do %>
   LibSass and Ruby Sass currently *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},

source/documentation/values/colors.html.md.erb

@@ -2,9 +2,9 @@
 title: Colors
 ---
 
-<% impl_status dart: '1.14.0', libsass: '3.6.0', ruby: '3.6.0' do %>
-  Support for [hex colors with an alpha channel][] is not supported by LibSass
-  or older versions of Dart or Ruby Sass.
+<% impl_status dart: '1.14.0', libsass: '3.6.0', ruby: '3.6.0', feature: 'Level 4 Syntax' do %>
+  LibSass and older versions of Dart or Ruby Sass don't support [hex colors with
+  an alpha channel][].
 
   [hex colors with an alpha channel]: https://drafts.csswg.org/css-color/#hex-notation
 <% end %>

source/documentation/values/lists.html.md.erb

@@ -3,7 +3,7 @@ title: Lists
 table_of_contents: true
 ---
 
-<% impl_status dart: true, libsass: '3.5.0', ruby: '3.5.0' do %>
+<% impl_status dart: true, libsass: '3.5.0', ruby: '3.5.0', feature: 'Square Brackets' do %>
   Older implementations of LibSass and Ruby Sass didn't support lists with
   square brackets.
 <% end %>

source/documentation/values/numbers.html.md.erb

@@ -44,7 +44,7 @@ been spotty, Sass always compiles it to fully expanded numbers.
 
 ## Precision
 
-<% impl_status dart: true, libsass: false, ruby: '3.5.0' do %>
+<% impl_status dart: true, libsass: false, ruby: '3.5.0', feature: '10 Digit Default' do %>
   LibSass and older versions of Ruby Sass default to 5 digits of numeric
   precision, but can be configured to use a different number. It's recommended
   that users configure them for 10 digits for greater accuracy and

source/documentation/values/strings.html.md.erb

@@ -161,7 +161,7 @@ diagram below. They may include [interpolation][] anywhere.
 
 ### Escapes
 
-<% impl_status dart: '1.11.0', libsass: false, ruby: false do %>
+<% impl_status dart: '1.11.0', libsass: false, ruby: false, feature: 'Normalization' do %>
   LibSass, Ruby Sass, and older versions of Dart Sass don't normalize escapes in
   identifiers. Instead, the text in the unquoted string is the exact text the
   user wrote. For example, `\1F46D` and `👭` are not considered equivalent.

source/documentation/variables.html.md.erb

@@ -228,6 +228,19 @@ in a mixin), you can use the `!global` flag. A variable declaration flagged as
     value: $variable
 <% end %>
 
+<% heads_up do %>
+  <% impl_status dart: '2.0.0', libsass: false, ruby: false do %>
+    Older Sass versions allowed `!global` to be used for a variable that
+    doesn't exist yet. This behavior was deprecated to make sure each stylesheet
+    declares the same variables no matter how it's executed.
+  <% end %>
+
+  The `!global` flag may only be used to set a variable that has already been
+  declared at the top level of a file. It *may not* be used to declare a new
+  variable.
+
+<% end %>
+
 ### Flow Control Scope
 
 Variables declared in [flow control rules][] have special scoping rules: they