diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index f515b292..d4ab734e 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -72,7 +72,7 @@ jobs: steps: - uses: actions/checkout@v4 - - uses: bufbuild/buf-setup-action@v1.32.1 + - uses: bufbuild/buf-setup-action@v1.35.1 with: {github_token: "${{ github.token }}"} - name: Generate protobuf code run: buf generate @@ -138,7 +138,7 @@ jobs: - name: Find changed files in js-api-doc id: changed-files - uses: tj-actions/changed-files@03334d095e2739fa9ac4034ec16f66d5d01e9eba + uses: tj-actions/changed-files@c65cd883420fd2eb864698a825fc4162dd94482c with: {files: js-api-doc} - name: Deploy diff --git a/.markdownlint-cli2.yaml b/.markdownlint-cli2.yaml index a84ac9d3..53429d31 100644 --- a/.markdownlint-cli2.yaml +++ b/.markdownlint-cli2.yaml @@ -1,6 +1,17 @@ globs: ["**.md"] ignores: ["node_modules/**"] config: + code-block-style: {style: fenced} + code-fence-style: {style: backtick} + emphasis-style: {style: asterisk} + heading-style: {style: atx} + hr-style: {style: "---"} + link-image-style: {collapsed: false} + reference-links-images: {shortcut_syntax: true} + strong-style: {style: asterisk} + table-pipe-style: {style: leading_and_trailing} + ul-style: {style: asterisk} + # BNF syntax examples can go over length, and there's no way to exempt them # specifically. line-length: false @@ -11,9 +22,6 @@ config: # We use untagged code blocks for function definitions. fenced-code-language: false - emphasis-style: - style: asterisk - # We often have to have duplicate subheadings for different parents. no-duplicate-heading: false diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 372dc5e5..adea328e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -3,7 +3,7 @@ When we add a new feature to Sass, we want to make sure the feature is well-designed, clearly specified, feasible to implement, and that it meets the use-cases it's designed for. Although most features should follow the [full -process][], very small features can follow the [fast-track process][] instead. +process], very small features can follow the [fast-track process] instead. [full process]: #process [fast-track process]: #fast-track @@ -22,10 +22,10 @@ process][], very small features can follow the [fast-track process][] instead. The process for adding a new feature works as follows: -1. The feature is informally discussed on [the issue tracker][]. Most new - features come directly from use-cases brought up by Sass users, or new CSS - syntax that Sass needs to support. Once the Sass team has agreed that a - feature is desirable, it's marked as [Planned][] and can move to step 2. +1. The feature is informally discussed on [the issue tracker]. Most new features + come directly from use-cases brought up by Sass users, or new CSS syntax that + Sass needs to support. Once the Sass team has agreed that a feature is + desirable, it's marked as [Planned] and can move to step 2. [the issue tracker]: https://github.com/sass/sass/issues [Planned]: https://github.com/sass/sass/labels/Planned @@ -38,21 +38,21 @@ The process for adding a new feature works as follows: Step 2 is also where issues are opened for each individual implementation to add the feature. These issues should link to the feature's main issue in the - [sass/sass][] issue tracker, and that issue should link back to the + [sass/sass] issue tracker, and that issue should link back to the implementation issues. [sass/sass]: https://github.com/sass/sass 3. Public comments are solicited for the feature, usually via a tweet from - [@SassCSS][]. If the feature is big enough, a blog post soliciting feedback - may also be written. Then we await comments and iterate on feedback for an - amount of time that varies based on the size of the feature and the amount of + [@SassCSS]. If the feature is big enough, a blog post soliciting feedback may + also be written. Then we await comments and iterate on feedback for an amount + of time that varies based on the size of the feature and the amount of feedback received. [@SassCSS]: https://twitter.com/SassCSS As the proposal is updated based on feedback, its draft number should be - increased according to the [versioning policy][] and changes should be logged + increased according to the [versioning policy] and changes should be logged in a changelog file named `.changes.md`. Once enough time has elapsed and the Sass team is satisfied that all feedback is addressed, the feature moves to step 4. @@ -123,11 +123,11 @@ their sections. Everything in sections that aren't explicitly marked as non-normative should be construed as part of the specification of the feature. Non-normative notes can -be included inline in normative sections using [blockquotes][]. +be included inline in normative sections using [blockquotes]. [blockquotes]: https://daringfireball.net/projects/markdown/syntax#blockquote -See [the `accepted/` directory][] for examples of proposals that have been +See [the `accepted/` directory] for examples of proposals that have been accepted. * **Background** @@ -149,7 +149,7 @@ accepted. corner of the feature, it just needs to give users an idea of how it works and what use-cases it addresses. Code examples are encouraged. - See [Escapes in Identifiers][] for a good example of a Summary section. + See [Escapes in Identifiers] for a good example of a Summary section. [Escapes in Identifiers]: accepted/identifier-escapes.md#summary @@ -167,7 +167,7 @@ accepted. * **Syntax** This section describes the syntax of the feature being added, if it adds new - syntax to the language. The syntax should be written in [Backus-Naur form][], + syntax to the language. The syntax should be written in [Backus-Naur form], with regular expression-style operators and the convention that nonterminals are written in capitalized camel-case form. For example: @@ -187,7 +187,7 @@ accepted. Syntax definitions can also refer to productions from CSS specs. The proposal should link to the specs in question. - See [Range-Context Media Features][] for an good example of a Syntax section. + See [Range-Context Media Features] for an good example of a Syntax section. [Range-Context Media Features]: accepted/media-ranges.md @@ -205,7 +205,7 @@ accepted. * **Deprecation Process** All backwards-incompatible features should go through a deprecation process if - at all possible (see [Dart Sass's compatibility policy][]). This section + at all possible (see [Dart Sass's compatibility policy]). This section describes the details of that process, including what code will produce deprecation warnings and how those warnings will indicate what the user should do to make their stylesheet forwards-compatible. @@ -293,13 +293,13 @@ process, it must be moved so that it can have a full discussion. The fast-track process works as follows: -1. The feature is informally discussed on [the issue tracker][]. Once the Sass - team has agreed that a feature is desirable, it's marked as [Planned][] and - can move to step 2. +1. The feature is informally discussed on [the issue tracker]. Once the Sass + team has agreed that a feature is desirable, it's marked as [Planned] and can + move to step 2. 2. Issues are opened for each individual implementation to add the feature. - These issues should link to the feature's main issue in the [sass/sass][] - issue tracker, and that issue should link back to the implementation issues. + These issues should link to the feature's main issue in the [sass/sass] issue + tracker, and that issue should link back to the implementation issues. Three pull requests are sent out concurrently. @@ -308,7 +308,7 @@ The fast-track process works as follows: author. *Unlike the full proposal process*, this pull request directly modifies the appropriate spec in `specs/`. - 2. A pull request is sent to [sass-spec][] that adds or updates specs for the + 2. A pull request is sent to [sass-spec] that adds or updates specs for the new feature. The new specs should have an `options.yml` file that marks them as ignored for LibSass. For example: @@ -322,7 +322,7 @@ The fast-track process works as follows: cause it not to run Dart Sass tests, which would otherwise fail because the implementation of the new feature hasn't landed yet. - 3. A pull request is sent to [Dart Sass][] that implements the new feature. + 3. A pull request is sent to [Dart Sass] that implements the new feature. This pull request's message should link to the sass-spec pull request (for example, `See sass/sass-spec#1293`). This will cause it to run against the specs in that pull request and so test your new feature. diff --git a/EMBEDDED_PROTOCOL_CHANGELOG.md b/EMBEDDED_PROTOCOL_CHANGELOG.md index bd0c52fe..ee8498ba 100644 --- a/EMBEDDED_PROTOCOL_CHANGELOG.md +++ b/EMBEDDED_PROTOCOL_CHANGELOG.md @@ -4,6 +4,10 @@ * Remove `RgbColor`, `HslColor` and `HwbColor` SassScript values. +## 2.7.1 + +* Allow deprecation versions to be value of `fatal_deprecation` field. + ## 2.7.0 * Add `containing_url_unused` field to `CanonicalizeResponse` and diff --git a/README.md b/README.md index 69ade583..3c4cd3ed 100644 --- a/README.md +++ b/README.md @@ -47,14 +47,13 @@ nav { ## Install Sass You can install Sass on Windows, Mac, or Linux by downloading the package for -your operating system [from GitHub][] and [adding it to your `PATH`][PATH]. -That's all—there are no external dependencies and nothing else you need to -install. +your operating system [from GitHub] and [adding it to your `PATH`][PATH]. That's +all—there are no external dependencies and nothing else you need to install. [from GitHub]: https://github.com/sass/dart-sass/releases [PATH]: https://katiek2.github.io/path-doc/ -If you use Node.js, you can also install Sass using [npm][] by running +If you use Node.js, you can also install Sass using [npm] by running [npm]: https://www.npmjs.com/ @@ -85,16 +84,16 @@ learn Sass! ## This Repository This repository isn't an implementation of Sass. Those live in -[`sass/dart-sass`][] and [`sass/libsass`][]. Instead, it contains: +[`sass/dart-sass`] and [`sass/libsass`]. Instead, it contains: [`sass/dart-sass`]: https://github.com/sass/dart-sass [`sass/libsass`]: https://github.com/sass/libsass -* [`spec/`][], which contains specifications for language features. -* [`proposal/`][], which contains in-progress proposals for changes to the +* [`spec/`], which contains specifications for language features. +* [`proposal/`], which contains in-progress proposals for changes to the language. -* [`accepted/`][], which contains proposals that have been accepted and are - either implemented or in the process of being implemented. +* [`accepted/`], which contains proposals that have been accepted and are either + implemented or in the process of being implemented. [`spec/`]: https://github.com/sass/sass/tree/main/spec [`proposal/`]: https://github.com/sass/sass/tree/main/proposal diff --git a/accepted/calc-functions.md b/accepted/calc-functions.md index a1a72c79..90577534 100644 --- a/accepted/calc-functions.md +++ b/accepted/calc-functions.md @@ -816,6 +816,8 @@ compiler. A private property like [`Value.internal`] that refers to a Sass string. +[`Value.internal`]: ../spec/js-api/value/index.d.ts.md#internal + ##### Constructor Creates a `CalculationInterpolation` with its `internal` set to an unquoted Sass diff --git a/accepted/color-4-hwb.md b/accepted/color-4-hwb.md index 8f04164c..f4d700c3 100644 --- a/accepted/color-4-hwb.md +++ b/accepted/color-4-hwb.md @@ -125,12 +125,12 @@ All new functions are part of the `sass:color` built-in module. * Set `blackness` to `blackness / (whiteness + blackness)`. * Let `red`, `green`, and `blue` be the result of converting `hue`, - `whiteness`, and `blackness` [to RGB][]. + `whiteness`, and `blackness` [to RGB]. * Set `red`, `green`, and `blue` to their existing values multiplied by 255 and rounded to the nearest integers. - * Let `alpha` be the result of [percent-converting][] `$alpha` with a `max` of 1. + * Let `alpha` be the result of [percent-converting] `$alpha` with a `max` of 1. * Return a color with the given `red`, `green`, `blue`, and `alpha` channels. @@ -268,7 +268,7 @@ This function's new definition is as follows: * If `$lightness` isn't null, set `lightness` to `lightness + $lightness` clamped between 0 and 100. - * Return the result of calling [`hsl()`][] with `hue`, `saturation`, + * Return the result of calling [`hsl()`] with `hue`, `saturation`, `lightness`, and `alpha`. * Otherwise, if either `$hue`, `$whiteness`, or `$blackness` aren't null: @@ -356,7 +356,7 @@ This function's new definition is as follows: * Let `lightness` be the result of calling `lightness($color)` if `$lightness` is null, or `$lightness` otherwise. - * Return the result of calling [`hsl()`][] with `hue`, `saturation`, + * Return the result of calling [`hsl()`] with `hue`, `saturation`, `lightness`, and `alpha`. * Otherwise, if either `$hue`, `$whiteness`, or `$blackness` aren't null: @@ -398,7 +398,7 @@ This function's new definition is as follows: * Let `alpha` be `$color`'s alpha channel. -* If `$alpha` isn't null, set `alpha` to the result of [scaling][] `alpha` by +* If `$alpha` isn't null, set `alpha` to the result of [scaling] `alpha` by `$alpha` with `max` 1. [scaling]: #scaling-a-number @@ -410,13 +410,13 @@ This function's new definition is as follows: * Let `red`, `green`, and `blue` be `$color`'s red, green, and blue channels. - * If `$red` isn't null, set `red` to the result of [scaling][] `red` by `$red` + * If `$red` isn't null, set `red` to the result of [scaling] `red` by `$red` with `max` 255. - * If `$green` isn't null, set `green` to the result of [scaling][] `green` by + * If `$green` isn't null, set `green` to the result of [scaling] `green` by `$green` with `max` 255. - * If `$blue` isn't null, set `blue` to the result of [scaling][] `blue` by `$blue` + * If `$blue` isn't null, set `blue` to the result of [scaling] `blue` by `$blue` with `max` 255. * Return a color with `red`, `green`, `blue`, and `alpha` as the red, green, @@ -429,13 +429,13 @@ This function's new definition is as follows: * Let `hue`, `saturation`, and `lightness` be the result of calling `hue($color)`, `saturation($color)`, and `lightness($color)` respectively. - * If `$saturation` isn't null, set `saturation` to the result of [scaling][] + * If `$saturation` isn't null, set `saturation` to the result of [scaling] `saturation` by `$saturation` with `max` `100%`. - * If `$lightness` isn't null, set `lightness` to the result of [scaling][] + * If `$lightness` isn't null, set `lightness` to the result of [scaling] `lightness` by `$lightness` with `max` `100%`. - * Return the result of calling [`hsl()`][] with `hue`, `saturation`, + * Return the result of calling [`hsl()`] with `hue`, `saturation`, `lightness`, and `alpha`. * Otherwise, if either `$hue`, `$whiteness`, or `$blackness` aren't null: @@ -443,10 +443,10 @@ This function's new definition is as follows: * Let `hue`, `whiteness`, and `blackness` be the result of calling `hue($color)`, `whiteness($color)`, and `blackness($color)` respectively. - * If `$whiteness` isn't null, set `whiteness` to the result of [scaling][] + * If `$whiteness` isn't null, set `whiteness` to the result of [scaling] `whiteness` by `$whiteness` with `max` `100%`. - * If `$blackness` isn't null, set `blackness` to the result of [scaling][] + * If `$blackness` isn't null, set `blackness` to the result of [scaling] `blackness` by `$blackness` with `max` `100%`. * Return the result of calling `hwb()` with `hue`, `whiteness`, `blackness`, diff --git a/accepted/color-4-new-spaces.md b/accepted/color-4-new-spaces.md index 47a7d7c6..50b72ac7 100644 --- a/accepted/color-4-new-spaces.md +++ b/accepted/color-4-new-spaces.md @@ -1301,6 +1301,7 @@ normalized channel value otherwise. * Return `value`. [number-to-unit]: https://github.com/sass/sass/blob/main/spec/types/number.md#converting-a-number-to-a-unit +[`rgb()`, `lab()`, `lch()`, `oklab()`, `oklch()`, or `color()`]: #new-global-functions ### Normalizing Color Channels diff --git a/accepted/color-4-rgb-hsl.md b/accepted/color-4-rgb-hsl.md index 5e8af020..5d1f28de 100644 --- a/accepted/color-4-rgb-hsl.md +++ b/accepted/color-4-rgb-hsl.md @@ -3,7 +3,7 @@ *([Issue](https://github.com/sass/sass/issues/2564), [Changelog](color-4-rgb-hsl.changes.md))* This proposal expands Sass's built-in `rgb()`, `rgba()`, `hsl()`, and `hsla()` -functions to support the new terse syntax defined in [CSS Color Level 4][]. +functions to support the new terse syntax defined in [CSS Color Level 4]. [CSS Color Level 4]: https://drafts.csswg.org/css-color/ @@ -22,7 +22,7 @@ functions to support the new terse syntax defined in [CSS Color Level 4][]. Sass's `rgb()` and `hsl()` functions will add support for the Color Level 4 syntax, so `rgb(179 115 153)`, `rgb(70% 45% 60%)`, and `hsl(324deg 29% 57%)` will all return the same color. They'll also support the slash-separated alpha -syntax using [the normal rules][] for distinguishing between division and `/`, +syntax using [the normal rules] for distinguishing between division and `/`, so `rgb(179 115 153 / 50%)` will return a 50%-opacity color but `rgb(179 115 $blue / 50%)` will not. @@ -58,7 +58,7 @@ case-insensitive. ### Special Variable String -A *special variable string* is [special number string][] that begins with +A *special variable string* is [special number string] that begins with `var(`. This matching is case-insensitive. [special number string]: #special-number-string @@ -78,7 +78,7 @@ functions: rgb($channels) ``` - * If `$channels` is a [special variable string][], return a plain CSS function + * If `$channels` is a [special variable string], return a plain CSS function string with the name `"rgb"` and the argument `$channels`. * If `$channels` is not an unbracketed space-separated list, throw an error. @@ -87,7 +87,7 @@ functions: * If `$channels` has fewer than three elements: - * If any element of `$channels` is a [special variable string][], return a + * If any element of `$channels` is a [special variable string], return a plain CSS function string with the name `"rgb"` and the argument `$channels`. @@ -131,7 +131,7 @@ functions: rgb($color, $alpha) ``` - * If either argument is a [special variable string][], return a plain CSS + * If either argument is a [special variable string], return a plain CSS function string with the name `"rgb"` and the same arguments. * Call `rgba()` with the same arguments and return the result. @@ -140,7 +140,7 @@ functions: hsl($channels) ``` - * If `$channels` is a [special variable string][], return a plain CSS function + * If `$channels` is a [special variable string], return a plain CSS function string with the name `"hsl"` and the argument `$channels`. * If `$channels` is not an unbracketed space-separated list, throw an error. @@ -149,7 +149,7 @@ functions: * If `$channels` has fewer than three elements: - * If any element of `$channels` is a [special variable string][], return a + * If any element of `$channels` is a [special variable string], return a plain CSS function string with the name `"hsl"` and the argument `$channels`. diff --git a/accepted/content-args.md b/accepted/content-args.md index 0264fad6..38160149 100644 --- a/accepted/content-args.md +++ b/accepted/content-args.md @@ -67,7 +67,7 @@ We decided to use `using` as opposed to another word because it's relatively terse while still being clear. We considered `as` instead, but decided the meaning of the word didn't match the semantics; and we considered `with`, but decided that it was both semantically ambiguous and confusing because the -[module system proposal][] uses to declare an argument *invocation* rather than +[module system proposal] uses to declare an argument *invocation* rather than an argument *declaration*. [module system proposal]: module-system.md diff --git a/accepted/css-imports.md b/accepted/css-imports.md index 1d29a9cf..ca1ade8b 100644 --- a/accepted/css-imports.md +++ b/accepted/css-imports.md @@ -4,7 +4,7 @@ This proposal covers a long-awaited Sass feature: the ability to import plain CSS files from Sass. Although the original plan was to wait on this support -until the [module system][] was in place and support CSS imports only with +until the [module system] was in place and support CSS imports only with `@use`, it has become desirable to support them sooner in order to have compatibility with the existing LibSass implementation. See [Background](#background) for more details. @@ -33,7 +33,7 @@ compatibility with the existing LibSass implementation. See Historically, the reference implementations of Sass—first Ruby Sass, then Dart Sass—only supported importing other Sass files. However, LibSass supported importing CSS files as well, interpreting them as though they were SCSS. -Although this technically violated the [implementation guide][]'s prohibition on +Although this technically violated the [implementation guide]'s prohibition on unilaterally extending the language, these CSS imports were useful and were widely adopted in the Node.js community. @@ -162,7 +162,7 @@ To evaluate an `@import` rule: If this returns null, throw an error. - * If an AST with the same [canonical URL][] as `stylesheet` is currently being + * If an AST with the same [canonical URL] as `stylesheet` is currently being evaluated, throw an error. * Evaluate `stylesheet` in the global scope. @@ -173,7 +173,7 @@ To evaluate an `@import` rule: This algorithm takes a string, `argument`, and returns a Sass stylesheet. -* Let `root` be the current stylesheet's [canonical URL][] if its scheme is +* Let `root` be the current stylesheet's [canonical URL] if its scheme is `file`, otherwise null. * Let `bases` be a list beginning with `root` if it's non-null, followed by the @@ -181,7 +181,7 @@ This algorithm takes a string, `argument`, and returns a Sass stylesheet. * For each `base` in `bases`: - * Let `url` be the result of [parsing `argument` as a URL][] with `base` as + * Let `url` be the result of [parsing `argument` as a URL] with `base` as the base URL. If this returns a failure, throw that failure. @@ -213,7 +213,7 @@ This algorithm takes a string, `argument`, and returns a Sass stylesheet. > The algorithm for [resolving a `file:` URL](#resolving-a-file-url) > guarantees that `resolved` will have one of these extensions. - * Return `ast` with the [canonical URL][] `resolved`. + * Return `ast` with the [canonical URL] `resolved`. [parsing `argument` as a URL]: https://url.spec.whatwg.org/#concept-url-parser @@ -400,7 +400,7 @@ It returns a Sass stylesheet. > The algorithm for [resolving a `file:` URL](#resolving-a-file-url) > guarantees that `resolved` will have one of these extensions. -* Return `ast` with the [canonical URL][] `url`. +* Return `ast` with the [canonical URL] `url`. ## Deprecation process diff --git a/accepted/extend-specificity.md b/accepted/extend-specificity.md index 7e0cdc2a..4a5eebae 100644 --- a/accepted/extend-specificity.md +++ b/accepted/extend-specificity.md @@ -111,12 +111,12 @@ One optimization that we've been doing for a long time is `extend(a.foo, .foo, a) = a`, as discussed above. This violates the first law, since `a != a.foo`. -Another optimization added in [8f4869e][] is `extend(a, a, a.foo) = a`. This +Another optimization added in [8f4869e] is `extend(a, a, a.foo) = a`. This violates the second law, since `spec(a) < spec(a.foo)`. [8f4869e]: https://github.com/sass/ruby-sass/commit/8f4869e608e70d7f468bb463ebfe7a939d834e27 -However, many of the optimizations added in [8f4869e][] do still work. For +However, many of the optimizations added in [8f4869e] do still work. For example, `extend(.bar a, a, a.foo) = .bar a` works because `spec(.bar a) = spec(a.foo)`. diff --git a/accepted/first-class-mixins.d.ts.md b/accepted/first-class-mixins.d.ts.md index b4bbe5db..312c5718 100644 --- a/accepted/first-class-mixins.d.ts.md +++ b/accepted/first-class-mixins.d.ts.md @@ -163,10 +163,10 @@ meta.get-mixin($name, $module: null) * If `$module` is not a string, throw an error. - * Let `use` be the `@use` rule in [the current source file][] whose + * Let `use` be the `@use` rule in [the current source file] whose namespace is equal to `$module`. If no such rule exists, throw an error. - * Return [`use`'s module][]'s mixin named `$name`, or throw an error if no + * Return [`use`'s module]'s mixin named `$name`, or throw an error if no such mixin exists. [the current source file]: ../spec/spec.md#current-source-file @@ -182,11 +182,11 @@ meta.module-mixins($module) * If `$module` is not a string, throw an error. -* Let `use` be the `@use` rule in [the current source file][] whose namespace is +* Let `use` be the `@use` rule in [the current source file] whose namespace is equal to `$module`. If no such rule exists, throw an error. * Return a map whose keys are the quoted string names of mixins in - [`use`'s module][] and whose values are the corresponding mixins. + [`use`'s module] and whose values are the corresponding mixins. ### `meta.accepts-content()` diff --git a/accepted/forward-with.md b/accepted/forward-with.md index a8cd1812..f0f4db69 100644 --- a/accepted/forward-with.md +++ b/accepted/forward-with.md @@ -41,7 +41,7 @@ of the root module, without removing that option for end-users. Sass will add a `with` clause to `@forward`. The `@forward ... with` syntax is based on the `@use ... with` syntax, but allows the addition of `!default` flags -similar to a [variable declaration][]. Unlike `@use ... with`, unconfigured +similar to a [variable declaration]. Unlike `@use ... with`, unconfigured origin variables, and variables configured with a `!default` flag, will remain configurable by any file importing the combined module. For example: @@ -133,7 +133,7 @@ The new `WithClause` extends `@forward` to the follow grammar: ## Semantics The `@forward ... with` semantics builds on the existing proposal for -[Executing Files][], and should be understood as modifying and expanding upon +[Executing Files], and should be understood as modifying and expanding upon the existing execution process rather than being a comprehensive replacement. [Executing Files]: ../accepted/module-system.md#executing-files @@ -143,7 +143,7 @@ Given a source file `file`, a configuration `config`, and an import context * Let `module` be an empty module with the same URL as `file`. -* Let `uses` be an empty map from `@use` rules to [modules][]. +* Let `uses` be an empty map from `@use` rules to [modules]. * When a `@use` rule `rule` is encountered: @@ -161,7 +161,7 @@ Given a source file `file`, a configuration `config`, and an import context * Add a variable to `rule-config` with the same name as `argument`'s identifier and with `value` as its value. - * Let `module` be the result of [loading][] the module with `rule`'s URL + * Let `module` be the result of [loading] the module with `rule`'s URL and `rule-config`. * If `rule` has a `WithClause` that contains any variables that aren't part of @@ -200,7 +200,7 @@ Given a source file `file`, a configuration `config`, and an import context * Add a variable to `rule-config` with the same name as `argument`'s identifier, and with `value` as its value. - * Let `forwarded` be the result of [loading][] the module with `rule`'s URL + * Let `forwarded` be the result of [loading] the module with `rule`'s URL and `rule-config`. * If `rule` has a `WithClause` that contains any variables that aren't part of diff --git a/accepted/free-interpolation.md b/accepted/free-interpolation.md index df357b88..d60a8059 100644 --- a/accepted/free-interpolation.md +++ b/accepted/free-interpolation.md @@ -2,7 +2,7 @@ *([Issue](https://github.com/sass/sass/issues/1778))* -Spurred by [#1774][], I started thinking about how messy interpolation is in +Spurred by [#1774], I started thinking about how messy interpolation is in SassScript at the moment and how to clean it up. This issue is the result of that thought process. diff --git a/accepted/identifier-escapes.md b/accepted/identifier-escapes.md index f80c7583..dca992cf 100644 --- a/accepted/identifier-escapes.md +++ b/accepted/identifier-escapes.md @@ -24,7 +24,7 @@ CSS handles escapes. At time of writing, while Sass recognizes escaped code points in identifiers and other names, it doesn't resolve them into the code points they represent. This means that, for example, Sass considers the selector `.\!foo` and the selector -`.\21 foo` to be distinct. This is contrary to the [CSS Syntax Level 3][], which +`.\21 foo` to be distinct. This is contrary to the [CSS Syntax Level 3], which [says that][css: consume name] the value of an escaped code point should be included in the name rather than the syntax of the escape. @@ -94,12 +94,12 @@ intended to replace the existing algorithms. ### Consuming an Identifier -This algorithm consumes input from a stream of [code points][] and returns a +This algorithm consumes input from a stream of [code points] and returns a string. [code points]: https://infra.spec.whatwg.org/#code-point -This production has the same grammar as [``][]. +This production has the same grammar as [``]. [``]: https://drafts.csswg.org/css-syntax-3/#ident-token-diagram @@ -111,10 +111,10 @@ This production has the same grammar as [``][]. * If the stream starts with `-`, consume it and append it to `string`. - * If the stream starts with `\`, [consume an escaped code point][] with the + * If the stream starts with `\`, [consume an escaped code point] with the `start` flag set and append it to `string`. - * Otherwise, if the stream starts with a [name-start code point][], consume it + * Otherwise, if the stream starts with a [name-start code point], consume it and append it to `string`. * Otherwise, throw an error. @@ -128,7 +128,7 @@ This production has the same grammar as [``][]. ### Consuming an Interpolated Identifier -This algorithm consumes input from a stream of [code points][] and returns a +This algorithm consumes input from a stream of [code points] and returns a sequence of strings and/or expressions. The grammar for this production is: @@ -152,7 +152,7 @@ No whitespace is allowed between components of an `InterpolatedIdentifier`. * Otherwise, [consume an identifier](#consuming-an-identifier) and add its string to `components`. -* While the input starts with `#{`, a [name code point][], or `\`: +* While the input starts with `#{`, a [name code point], or `\`: [name code point]: https://drafts.csswg.org/css-syntax-3/#name-code-point @@ -166,52 +166,52 @@ No whitespace is allowed between components of an `InterpolatedIdentifier`. ### Consuming a Name -This algorithm consumes input from a stream of [code points][] and returns a +This algorithm consumes input from a stream of [code points] and returns a string. The grammar for this production is:
-**Name** ::= ([name code point][] | [escape][])+
+**Name** ::= ([name code point] | [escape])+
 
* Let `string` be an empty string. -* While the input starts with a [name code point][] or `\`: +* While the input starts with a [name code point] or `\`: - * If the input starts with a [name code point][], consume it and append it to + * If the input starts with a [name code point], consume it and append it to `string`. - * Otherwise, [consume an escaped code point][] and append it to `string`. + * Otherwise, [consume an escaped code point] and append it to `string`. * Return `string`. ### Consuming an Escaped Code Point -This algorithm consumes input from a stream of [code points][]. It takes an +This algorithm consumes input from a stream of [code points]. It takes an optional boolean flag, `start`, which indicates whether it's at the beginning of an identifier and defaults to false. It returns a string. This production has the same grammar as [`escape`][escape] in CSS Syntax Level 3. -* If the stream doesn't [start with a valid escape][], throw an error. +* If the stream doesn't [start with a valid escape], throw an error. [start with a valid escape]: https://drafts.csswg.org/css-syntax-3/#starts-with-a-valid-escape -* Let `codepoint` be the result of [consuming an escaped code point][]. +* Let `codepoint` be the result of [consuming an escaped code point]. [consuming an escaped code point]: https://drafts.csswg.org/css-syntax-3/#consume-escaped-code-point * Let `character` be the string containing only `codepoint`. -* If `codepoint` is a [name-start code point][], return `character`. +* If `codepoint` is a [name-start code point], return `character`. -* Otherwise, if `codepoint` is a [name code point][] and the `start` flag is +* Otherwise, if `codepoint` is a [name code point] and the `start` flag is not set, return `character`. -* Otherwise, if `codepoint` is a [non-printable code point][], U+000A LINE FEED, +* Otherwise, if `codepoint` is a [non-printable code point], U+000A LINE FEED, U+000D CARRIAGE RETURN, or U+000C FORM FEED; *or* if `codepoint` is a - [digit][] and the `start` flag is set: + [digit] and the `start` flag is set: [non-printable code point]: https://drafts.csswg.org/css-syntax-3/#non-printable-code-point [digit]: https://drafts.csswg.org/css-syntax-3/#digit diff --git a/accepted/import-configuration.md b/accepted/import-configuration.md index 5919780e..dfcb1dcd 100644 --- a/accepted/import-configuration.md +++ b/accepted/import-configuration.md @@ -28,12 +28,12 @@ members that are behind a `@forward` rule. This makes it difficult for libraries with configurable variables to migrate to the module system without breaking downstream users that haven't migrated yet. This is especially true if the library removed a manual prefix from its members -during migration. When the [migrator][] does this, it creates an import-only file +during migration. When the [migrator] does this, it creates an import-only file that forwards the regular stylesheet with the prefix added back, but that `@forward` rule means configuration doesn't work. Because it is nearly impossible to migrate these cases incrementally, this -violates the module system's [backwards compatibility goal][]. Libraries with +violates the module system's [backwards compatibility goal]. Libraries with prefixes and configuration variables are common, and without an incremental migration solution, these libraries may be slow to start using the module system, limiting its adoption by the ecosystem as a whole. @@ -49,8 +49,8 @@ This proposal modifies the semantics for configuring a module when `@import` is involved to ensure that most downstream users of a library are not broken when the library migrates to the module system. -When a file is loaded by an `@import` rule, a [configuration][] is created that -includes all variables declared in the current [import context][]. This +When a file is loaded by an `@import` rule, a [configuration] is created that +includes all variables declared in the current [import context]. This implicitly created configuration is a special type that can be distinguished from other, explicitly created configurations. @@ -78,7 +78,7 @@ We considered a few alternatives in designing this proposal. One alternative did not involve any language changes at all, instead recommending that library authors add `@use` rules explicitly configuring their -variables to their [import-only files][] when migrating. For example: +variables to their [import-only files] when migrating. For example: ```scss // app.scss @@ -118,7 +118,7 @@ configuration between the two imports, the change will be ignored. However, this is an edge case that is (a) probably not intended by the user, (b) relatively easy to fix by moving all declared configuration variables before all library imports, and (c) very difficult to support for a library using the -module system without compromising the module system's [import once goal][], as +module system without compromising the module system's [import once goal], as handling this case would require modules in the library to be executed twice. [import-only files]: ../accepted/module-system.md#import-compatibility @@ -126,8 +126,8 @@ handling this case would require modules in the library to be executed twice. ## Definitions -This proposal modifies the definition of a [configuration][] within the -[module system spec][] to add the following: +This proposal modifies the definition of a [configuration] within the +[module system spec] to add the following: A configuration is either *explicit* or *implicit*. When a configuration is created, if the type is not specified, it is considered *explicit*. @@ -136,10 +136,10 @@ created, if the type is not specified, it is considered *explicit*. ## Procedures -This proposal modifies the fourth bullet of the [Loading Modules][] procedure -within the [module system spec][] to read as follows: +This proposal modifies the fourth bullet of the [Loading Modules] procedure +within the [module system spec] to read as follows: -* If `file` has already been [executed][]: +* If `file` has already been [executed]: * If `config` is **explicit and** not empty, throw an error. @@ -152,8 +152,8 @@ within the [module system spec][] to read as follows: ### Executing Files -This proposal modifies the first bullet of the semantics of [Executing Files][] -within the [module system spec][] to read as follows: +This proposal modifies the first bullet of the semantics of [Executing Files] +within the [module system spec] to read as follows: * If this file isn't being executed for a `@forward` **or `@import`** rule: @@ -183,10 +183,10 @@ This proposal also modifies the fifth bullet to read as follows: * Otherwise, let `rule-config` be `config`. - * Let `forwarded` be the result of [loading][] the module with `rule`'s URL + * Let `forwarded` be the result of [loading] the module with `rule`'s URL and `rule-config`. - * [Forward `forwarded`][] with `file` through `module`. + * [Forward `forwarded`] with `file` through `module`. [Executing Files]: ../accepted/module-system.md#executing-files [loading]: ../accepted/module-system.md#loading-modules @@ -194,11 +194,11 @@ This proposal also modifies the fifth bullet to read as follows: ### Importing Files -This proposal modifies the semantics for [Importing Files][] within the -[module system spec][] to read as follows: +This proposal modifies the semantics for [Importing Files] within the +[module system spec] to read as follows: -This algorithm takes a [source file][] `file`, an [import context][] `import`, -and a mutable [module][] `module`. +This algorithm takes a [source file] `file`, an [import context] `import`, +and a mutable [module] `module`. * If `file` is currently being executed, throw an error. @@ -209,19 +209,19 @@ and a mutable [module][] `module`. > used, so implementations may wish to skip this step and use the empty > configuration instead in that case for performance reasons. -* Let `imported` be the result of [executing][] `file` with ~~the empty +* Let `imported` be the result of [executing] `file` with ~~the empty configuration~~ **`config` as its configuration** and `import` as its import context, except that if the `@import` rule is nested within at-rules and/or style rules, that context is preserved when executing `file`. -* Let `css` be the result of [resolving extensions][] for +* Let `css` be the result of [resolving extensions] for `imported`, except that if the `@import` rule is nested within at-rules and/or style rules, that context is added to CSS that comes from modules loaded by `imported`. * Add `css` to `module`'s CSS. -* Add `imported`'s [extensions][] to `module`. +* Add `imported`'s [extensions] to `module`. * Add each member in `imported` to `import` and `module`. diff --git a/accepted/interleaved-declarations.changes.md b/accepted/interleaved-declarations.changes.md new file mode 100644 index 00000000..7fe4b764 --- /dev/null +++ b/accepted/interleaved-declarations.changes.md @@ -0,0 +1,5 @@ +## Draft 1.1 + +* Remove the `@nest` rule as it was removed from CSS. + +* Produce a deprecation warning for declarations in non-top-level contexts. diff --git a/proposal/interleaved-declarations.md b/accepted/interleaved-declarations.md similarity index 85% rename from proposal/interleaved-declarations.md rename to accepted/interleaved-declarations.md index f70d816e..5c5d502f 100644 --- a/proposal/interleaved-declarations.md +++ b/accepted/interleaved-declarations.md @@ -1,6 +1,7 @@ -# Interleaved Declarations: Draft 1 +# Interleaved Declarations: Draft 1.1 -*([Issue](https://github.com/sass/sass/issues/3846))* +*([Issue](https://github.com/sass/sass/issues/3846), +[Changelog](interleaved-declarations.changes.md))* ## Table of Contents @@ -11,8 +12,6 @@ * [Current Keyframe Block](#current-keyframe-block) * [Declarations](#declarations) * [Semantics](#semantics) -* [Unknown At-Rules](#unknown-at-rules) - * [Semantics](#semantics-1) * [Deprecation Process](#deprecation-process) ## Background @@ -122,24 +121,13 @@ before "Append `css` to `parent`": [current style rule]: #current-style-rule [keyframe block]: #current-keyframe-block -## Unknown At-Rules - -### Semantics - -Add the following to the semantics for executing an unknown at-rule `rule` after -"If `rule`'s name is 'font-face', or if its unprefixed name is 'keyframes', -append `css` to the current module's CSS": - -* If `rule`'s name is case-insensitively equal to "nest", append `css` to - `parent`. - ## Deprecation Process This proposal's change to the semantics of interleaved declarations is backwards-incompatible. Before changing to the new semantics, an implementation should have a period of deprecation in which it emits a deprecation warning for -a declaration whose `parent` is not the last statement in [the current module]'s -CSS without changing the existing behavior. +a declaration whose `parent` is not the last statement in its parent without +changing the existing behavior. > Authors can move interleaved declarations before any nested rules to preserve > existing behavior, or nest them in `& { ... }` style rules to anticipate the diff --git a/accepted/media-ranges.md b/accepted/media-ranges.md index 71ac1b83..b16fa778 100644 --- a/accepted/media-ranges.md +++ b/accepted/media-ranges.md @@ -3,7 +3,7 @@ *([Issue](https://github.com/sass/sass/issues/1864), [Changelog](media-ranges.changes.md))* This proposal defines how Sass handles media queries with features written in a -[range context][]. +[range context]. [range context]: https://www.w3.org/TR/mediaqueries-4/#mq-range-context @@ -34,7 +34,7 @@ complexity to media merging, for very limited benefits in terms of output size and readability. The values of media features with the "range" type are heterogeneous, including -a [``][] type value type that Sass has no existing knowledge of. If Sass +a [``] type value type that Sass has no existing knowledge of. If Sass were to support intelligent merging of these features, it would need to keep abreast of any new value types supported by "range"-type media features. This would violate Sass's general design principle of knowing as little about CSS as @@ -54,7 +54,7 @@ plain CSS. This proposal defines a new syntax for media queries in Sass stylesheets. It is intended to replace the existing syntax. -> Other than support for the [range context][] syntax, this syntax is designed +> Other than support for the [range context] syntax, this syntax is designed > to represent the current behavior of all Sass implementations.
@@ -76,13 +76,13 @@ operators `=`, `>`, `>=`, `<`, or `<=`, except within parentheses (including
 function calls and map literals) and square brackets.
 
 The ``, ``, and `` productions are defined in
-[Media Queries Level 4][].
+[Media Queries Level 4].
 
 [Media Queries Level 4]: https://drafts.csswg.org/mediaqueries-4/#mq-syntax
 
 > Note that Sass currently doesn't support parsing full media conditions
 > according to the level 4 specification, since no browsers support it yet. See
-> [sass/sass#2538][] for details.
+> [sass/sass#2538] for details.
 
 [sass/sass#2538]: https://github.com/sass/sass/issues/2538
 
@@ -105,7 +105,7 @@ Plain CSS media queries are parsed using the following syntax:
 The `` production matches the [railroad diagram][ident-token]
 listed in CSS Syntax Level 3. The `` production uses
 [the definition][declaration-value] from CSS Syntax Level 3,
-[consuming tokens][] only as needed until the production terminates.
+[consuming tokens] only as needed until the production terminates.
 
 [ident-token]: https://drafts.csswg.org/css-syntax-3/#ident-token-diagram
 [declaration-value]: https://drafts.csswg.org/css-syntax-3/#typedef-declaration-value
diff --git a/accepted/min-max.md b/accepted/min-max.md
index ffa2bebc..35d72b57 100644
--- a/accepted/min-max.md
+++ b/accepted/min-max.md
@@ -3,7 +3,7 @@
 *([Issue](https://github.com/sass/sass/issues/2378), [Changelog](min-max.changes.md))*
 
 This proposal defines how Sass handles CSS's `min()` and `max()`
-[math functions][].
+[math functions].
 
 [math functions]: https://drafts.csswg.org/css-values/#math-function
 
@@ -20,7 +20,7 @@ This proposal defines how Sass handles CSS's `min()` and `max()`
 
 Since Ruby Sass 3.2, Sass has provided `min()` and `max()` functions that return
 the minimum or maximum values among a set of SassScript numbers. Later, CSS
-Values and Units Level 4 added support for additional [math functions][] with
+Values and Units Level 4 added support for additional [math functions] with
 special syntax like that in `calc()`, among which were `min()` and `max()`.
 
 This presents a problem for Sass: to retain backwards-compatibility with
@@ -29,7 +29,7 @@ functions. However, to provide compatibility with CSS, it must also support them
 as math functions with special syntax.
 
 Support for CSS's `min()` and `max()` has landed in real browsers and
-[Sass users want to use it][], so this should be solved with some urgency.
+[Sass users want to use it], so this should be solved with some urgency.
 
 [Sass users want to use it]: https://github.com/sass/sass/issues/2378#issuecomment-367490840
 
diff --git a/accepted/module-system.changes.md b/accepted/module-system.changes.md
index 987ee15c..3272adb5 100644
--- a/accepted/module-system.changes.md
+++ b/accepted/module-system.changes.md
@@ -203,7 +203,7 @@
   the current stylesheet.
 
 * Removed the low-level "using CSS files" goal, since this is now covered by
-  [the CSS Imports proposal][].
+  [the CSS Imports proposal].
 
   [the CSS Imports proposal]: ../accepted/css-imports.md
 
@@ -224,7 +224,7 @@
 
 * Refer to "namespaces" rather than "prefixes".
 
-* Refer to "URLs" rather than "URIs", per [the URL spec][].
+* Refer to "URLs" rather than "URIs", per [the URL spec].
 
   [the URL spec]: https://url.spec.whatwg.org/#goals
 
diff --git a/accepted/module-system.md b/accepted/module-system.md
index 4531a61c..ac3f9c4d 100644
--- a/accepted/module-system.md
+++ b/accepted/module-system.md
@@ -525,7 +525,7 @@ file](#source-file) identified by the module's canonical URL with a
 ### Module Graph
 
 Modules also track their `@use` and `@forward` at-rules, which point to other
-modules. In this sense, modules can be construed as a [directed acyclic graph][]
+modules. In this sense, modules can be construed as a [directed acyclic graph]
 where the vertices are modules and the edges are `@use` rules and/or `@forward`
 rules. We call this the *module graph*.
 
@@ -592,7 +592,7 @@ The new at-rule will be called `@use`. The grammar for this rule is as follows:
 
 `@use` rules must be at the top level of the document, and must come before any
 rules other than `@charset` or `@forward`. The `QuotedString`'s contents, known
-as the rule's *URL*, must be a [valid URL string][] (for non-[special][special
+as the rule's *URL*, must be a [valid URL string] (for non-[special][special
 URL scheme] base URL). No whitespace is allowed after `$` in `KeywordArgument`.
 
 [valid URL string]: https://url.spec.whatwg.org/#valid-url-string
@@ -637,7 +637,7 @@ grammar for this rule is as follows:
 
 `@forward` rules must be at the top level of the document, and must come before
 any rules other than `@charset` or `@use`. If they have a `QuotedString`, its
-contents, known as the rule's *URL*, must be a [valid URL string][] (for
+contents, known as the rule's *URL*, must be a [valid URL string] (for
 non-[special][special URL scheme] base URL). No whitespace is allowed after `$`
 in `MemberName`, or before `*` in `AsClause`.
 
@@ -648,7 +648,7 @@ mixins, this update affects only calls, not definitions. Variables, on the other
 hand, may use this syntax for either assignment or reference.
 
 
-**PublicIdentifier**     ::= [\][] that doesn't begin with '-' or '_'
+**PublicIdentifier**     ::= [\] that doesn't begin with '-' or '_'
 **Variable**             ::= '$' Identifier | Identifier '.$' PublicIdentifier
 **NamespacedIdentifier** ::= Identifier | Identifier '.' PublicIdentifier
 **FunctionCall**         ::= NamespacedIdentifier ArgumentInvocation
@@ -800,7 +800,7 @@ CSS for *all* modules transitively used or forwarded by `starting-module`.
 * Let `extended` be the subgraph of the [module graph](#module-graph) containing
   modules that are transitively reachable from `starting-module`.
 
-* For each module `domestic` in `extended`, in reverse [topological][] order:
+* For each module `domestic` in `extended`, in reverse [topological] order:
 
   * Let `downstream` be the set of modules that use or forward `domestic`.
 
@@ -832,7 +832,7 @@ CSS for *all* modules transitively used or forwarded by `starting-module`.
 
     * Set `new-selectors[rule]` to a selector that matches the union of all
       elements matched by selectors in `selector-lists`. This selector must obey
-      [the specificity laws of extend][] relative to the selectors from which it
+      [the specificity laws of extend] relative to the selectors from which it
       was generated. For the purposes of the first law of extend, "the original
       extendee" is considered only to refer to selectors that appear in
       `domestic`'s CSS, *not* selectors that were added by other modules'
@@ -891,7 +891,7 @@ CSS for *all* modules transitively used or forwarded by `starting-module`.
 
 ### Resolving a `file:` URL
 
-This algorithm is intended to replace [the existing algorithm][] for resolving a
+This algorithm is intended to replace [the existing algorithm] for resolving a
 `file:` URL to add support for `@import`-only files, and to allow imports that
 include a literal `.css` extension. This algorithm takes a URL, `url`, whose
 scheme must be `file` and returns either another URL that's guaranteed to point
@@ -1092,7 +1092,7 @@ Given a source file `file`, a [configuration](#configuration) `config`, and an
 
   * Let `css` be the result of executing the rule as normal.
 
-  * Remove any [complex selectors][] containing a placeholder selector that
+  * Remove any [complex selectors] containing a placeholder selector that
     begins with `-` or `_` from `css`.
 
   * Remove any style rules that now have no selector from `css`.
@@ -1180,7 +1180,7 @@ Given a source file `file`, a [configuration](#configuration) `config`, and an
     >
     > without needing to use `!global`.
 
-  * Otherwise, if no block containing `declaration` has a [scope][] with a
+  * Otherwise, if no block containing `declaration` has a [scope] with a
     variable named `name`, set the innermost block's scope's variable `name` to
     `value`.
 
@@ -1204,7 +1204,7 @@ Given a source file `file`, a [configuration](#configuration) `config`, and an
 
 * When a member use `member` is encountered:
 
-  * Let `scope` be the [scope][] of the innermost block containing `member` such
+  * Let `scope` be the [scope] of the innermost block containing `member` such
     that `scope` has a member of `member`'s name and type, or `null` if no such
     scope exists.
 
@@ -1223,14 +1223,14 @@ Given a source file `file`, a [configuration](#configuration) `config`, and an
       yet in `module`, set `variable` to `null` in `module`.
 
       > This isn't necessary for implementations that follow the most recent
-      > [variables spec][] and don't allow `!global` assignments to variables
+      > [variables spec] and don't allow `!global` assignments to variables
       > that don't yet exist. However, at time of writing, all existing
       > implementations are in the process of deprecating the old `!global`
       > behavior, which allowed `!global` declarations to create new
       > variables.
       >
       > Setting all `!global` variables to `null` if they weren't otherwise set
-      > guarantees [static analysis][] by ensuring that the set of variables a
+      > guarantees [static analysis] by ensuring that the set of variables a
       > module exposes doesn't depend on how it was executed.
 
   * Return `module`. Its functions, mixins, and CSS are now immutable.
@@ -1476,7 +1476,7 @@ context](#import-context) `import`, and a mutable [module](#module) `module`.
 * Add `imported`'s [extensions](#extension) to `module`.
 
 * If the `@import` rule is nested within at-rules and/or style rules, add each
-  member in `imported` to the local [scope][].
+  member in `imported` to the local [scope].
 
 * Otherwise, add each member in `imported` to `import` and `module`.
 
@@ -1552,7 +1552,7 @@ The built-in functions will be organized as follows:
 | `unquote`                |           | sass:string   |   | `type-of`                |                    | sass:meta     |
 | `quote`                  |           | sass:string   |   | `call`                   |                    | sass:meta     |
 | `str-length`             | `length`  | sass:string   |   | `content-exists`         |                    | sass:meta     |
-| `str-insert`             | `insert`  | sass:string   |   | `keywords`               |                    | sass:meta
+| `str-insert`             | `insert`  | sass:string   |   | `keywords`               |                    | sass:meta     |
 | `str-index`              | `index`   | sass:string   |   |                          | `module-variables` | sass:meta     |
 | `str-slice`              | `slice`   | sass:string   |   |                          | `module-functions` | sass:meta     |
 | `to-upper-case`          |           | sass:string   |   |                          |                    |               |
diff --git a/accepted/more-math-functions.md b/accepted/more-math-functions.md
index 99e49144..dcce5f34 100644
--- a/accepted/more-math-functions.md
+++ b/accepted/more-math-functions.md
@@ -44,7 +44,7 @@ available on the global namespace.
 > This section is non-normative.
 
 This proposal defines Sassified versions of all the mathematical functions in
-the [CSS Values and Units 4 Draft][], as well as logarithms and the constants
+the [CSS Values and Units 4 Draft], as well as logarithms and the constants
 `e` and `pi`. Each function is basically equivalent to its mathematical form,
 with stricter unit handling. Proper unit handling prevents these functions from
 creating meaningless units. For instance, consider `(1px)^(1/3)`—what does
@@ -56,7 +56,7 @@ To avoid issues like this, the exponential functions—`log()`, `pow()`, `sqrt()
 accept only a unitless number as input, and output a unitless number.
 
 The trig functions—`cos()`, `sin()`, `tan()`—accept a SassScript number with a
-unit, as long as that unit is an [angle][] type. If the input is a unitless
+unit, as long as that unit is an [angle] type. If the input is a unitless
 number, it is treated as though it were in `rad`. These functions output a
 unitless number.
 
@@ -66,7 +66,7 @@ The inverse trig functions—`acos()`, `asin()`, `atan()`—accept a unitless nu
 and output a SassScript number in `deg`. `atan2()` is similar, but it accepts
 two unitless numbers.
 
-`clamp()` accepts three SassScript numbers with [compatible][] units: the
+`clamp()` accepts three SassScript numbers with [compatible] units: the
 minimum value, preferred value, and maximum value. This function "clamps" the
 preferred value in between the minimum and maximum values, while preserving
 their units appropriately. For example, `clamp(1in, 15cm, 12in)` outputs `15cm`,
@@ -84,8 +84,8 @@ of the first input.
 ### Built-in Module Variables
 
 Variables defined in built-in modules are not modifiable. As such, this proposal
-modifies the semantics of [Executing a Variable Declaration][] within the
-[Variables spec][] to read as follows:
+modifies the semantics of [Executing a Variable Declaration] within the
+[Variables spec] to read as follows:
 
 [Executing a Variable Declaration]: ../spec/variables.md#executing-a-variable-declaration
 [Variables spec]: ../spec/variables.md
@@ -96,7 +96,7 @@ To execute a `VariableDeclaration` `declaration`:
 
 * Let `name` be `declaration`'s `Variable`.
 
-* **Let `resolved` be the result of [resolving a variable][] named `name`.**
+* **Let `resolved` be the result of [resolving a variable] named `name`.**
 
 [resolving a variable]: ../spec/modules.md#resolving-a-member
 
@@ -109,7 +109,7 @@ To execute a `VariableDeclaration` `declaration`:
 * Otherwise, if `declaration` is outside of any block of statements, *or*
   `declaration` has a `!global` flag, *or* `name` is a `NamespacedVariable`:
 
-  * ~~Let `resolved` be the result of [resolving a variable][] named `name` using
+  * ~~Let `resolved` be the result of [resolving a variable] named `name` using
     `file`, `uses`, and `import`.~~
 
   (...)
@@ -117,11 +117,11 @@ To execute a `VariableDeclaration` `declaration`:
 * Otherwise, if `declaration` is within one or more blocks associated with
   `@if`, `@each`, `@for`, and/or `@while` rules *and no other blocks*:
 
-  * ~~Let `resolved` be the result of [resolving a variable][] named `name`.~~
+  * ~~Let `resolved` be the result of [resolving a variable] named `name`.~~
 
   (...)
 
-* ~~Otherwise, if no block containing `declaration` has a [scope][] with a
+* ~~Otherwise, if no block containing `declaration` has a [scope] with a
   variable named `name`, set the innermost block's scope's variable `name` to
   `value`.~~
 
@@ -189,7 +189,7 @@ log($number, $base: null)
   * If `$number < 0`, return `NaN` as a unitless number.
   * If `$number == 0`, return `-Infinity` as a unitless number.
   * If `$number == Infinity`, return `Infinity` as a unitless number.
-  * Return the [natural log][] of `$number`, as a unitless number.
+  * Return the [natural log] of `$number`, as a unitless number.
 * Otherwise, return the natural log of `$number` divided by the natural log of
   `$base`, as a unitless number.
 
@@ -259,7 +259,7 @@ cos($number)
 * If `$number` is unitless, treat it as though its unit were `rad`.
 * If `$number == Infinity` or `$number == -Infinity`, return `NaN` as a unitless
   number.
-* Return the [cosine][] of `$number`, as a unitless number.
+* Return the [cosine] of `$number`, as a unitless number.
 
 [cosine]: https://en.wikipedia.org/wiki/Trigonometric_functions#Right-angled_triangle_definitions
 
@@ -275,7 +275,7 @@ sin($number)
   number.
 * If `$number == -0`, return `-0` as a unitless number.
 * If `$number == 0`, return `0` as a unitless number.
-* Return the [sine][] of `$number`, as a unitless number.
+* Return the [sine] of `$number`, as a unitless number.
 
 [sine]: https://en.wikipedia.org/wiki/Trigonometric_functions#Right-angled_triangle_definitions
 
@@ -295,7 +295,7 @@ tan($number)
   integer, return `Infinity` as a unitless number.
 * If `$number` is equivalent to `-90deg +/- 360deg * n`, where `n` is any
   integer, return `-Infinity` as a unitless number.
-* Return the [tangent][] of `$number`, as a unitless number.
+* Return the [tangent] of `$number`, as a unitless number.
 
 [tangent]: https://en.wikipedia.org/wiki/Trigonometric_functions#Right-angled_triangle_definitions
 
@@ -308,7 +308,7 @@ acos($number)
 * If `$number` has units, throw an error.
 * If `$number < -1` or `$number > 1`, return `NaN` as a number in `deg`.
 * If `$number == 1`, return `0deg`.
-* Return the [arccosine][] of `$number`, as a number in `deg`.
+* Return the [arccosine] of `$number`, as a number in `deg`.
 
 [arccosine]: https://en.wikipedia.org/wiki/Inverse_trigonometric_functions#Basic_properties
 
@@ -322,7 +322,7 @@ asin($number)
 * If `$number < -1` or `$number > 1`, return `NaN` as a number in `deg`.
 * If `$number == -0`, return `-0deg`.
 * If `$number == 0`, return `0deg`.
-* Return the [arcsine][] of `$number`, as a number in `deg`.
+* Return the [arcsine] of `$number`, as a number in `deg`.
 
 [arcsine]: https://en.wikipedia.org/wiki/Inverse_trigonometric_functions#Basic_properties
 
@@ -337,7 +337,7 @@ atan($number)
 * If `$number == 0`, return `0deg`.
 * If `$number == -Infinity`, return `-90deg`.
 * If `$number == Infinity`, return `90deg`.
-* Return the [arctangent][] of `$number`, as a number in `deg`.
+* Return the [arctangent] of `$number`, as a number in `deg`.
 
 [arctangent]: https://en.wikipedia.org/wiki/Inverse_trigonometric_functions#Basic_properties
 
@@ -355,7 +355,7 @@ atan2($y, $x)
 * If `$y` and `$x` are not compatible, throw an error.
 * If `$y` has units and `$x` does not, or vice-versa, throw an error.
 * If the inputs match one of the following edge cases, return the provided
-  number. Otherwise, return the [2-argument arctangent][] of `$y` and `$x`, as a
+  number. Otherwise, return the [2-argument arctangent] of `$y` and `$x`, as a
   number in `deg`.
 
 [2-argument arctangent]: https://en.wikipedia.org/wiki/Atan2
diff --git a/accepted/partial-namespace.md b/accepted/partial-namespace.md
index a0b1716c..12f7e82f 100644
--- a/accepted/partial-namespace.md
+++ b/accepted/partial-namespace.md
@@ -14,7 +14,7 @@
 
 > This section is non-normative.
 
-In the new Sass [module system][] as written, the implicit namespace of a `@use`
+In the new Sass [module system] as written, the implicit namespace of a `@use`
 rule that loads a partial with an explicit leading underscore contains that
 underscore. This was unintended and confusing, making the namespace look like a
 private identifier and making it different than the same file's namespace
@@ -34,7 +34,7 @@ have the implicit namespace `styles` rather than `_styles`.
 ### Determining a `@use` Rule's Namespace
 
 This modifies the existing algorithm for [Determining a `@use` Rule's
-Namespace][] to read as follows (new text in bold):
+Namespace] to read as follows (new text in bold):
 
 [Determining a `@use` Rule's Namespace]: ../spec/at-rules/use.md#determining-a-use-rules-namespace
 
diff --git a/accepted/plain-css-nesting.md b/accepted/plain-css-nesting.md
index f7e842ea..9a41f5b6 100644
--- a/accepted/plain-css-nesting.md
+++ b/accepted/plain-css-nesting.md
@@ -126,7 +126,7 @@ To execute a style rule `rule`:
 
   [bogus]: ../spec/selectors.md#bogus-selector
 
-* Remove any [complex selectors][] containing a placeholder selector that
+* Remove any [complex selectors] containing a placeholder selector that
   begins with `-` or `_` from `css`'s selector.
   
   [complex selectors]: https://drafts.csswg.org/selectors-4/#complex
diff --git a/accepted/prev-url.d.ts.md b/accepted/prev-url.d.ts.md
index a08f06d3..a1d50026 100644
--- a/accepted/prev-url.d.ts.md
+++ b/accepted/prev-url.d.ts.md
@@ -41,6 +41,8 @@ to access the URL of the stylesheet that contained the load, known in the legacy
 API as the "previous URL". This was an intentional design choice which enforced
 the invariant that the same canonical URL always refers to the same file.
 
+[new importer API]: new-js-importer.d.ts
+
 However, this restriction makes it difficult for importers to work as expected
 in certain contexts. For example, in the Node.js ecosystem JS loads depend on
 the structure of the `node_modules` directory closest to the containing file.
diff --git a/accepted/slash-separator.md b/accepted/slash-separator.md
index e7c0f91e..bbaa3344 100644
--- a/accepted/slash-separator.md
+++ b/accepted/slash-separator.md
@@ -44,13 +44,13 @@ Early on in Sass's history, the decision was made to use `/` as a division
 operator, since that was (and is) by far the most common representation across
 programming languages. The `/` character was used in very few plain CSS
 properties, and for those it was an optional shorthand. So Sass defined [a set
-of heuristics][] that defined when `/` would be rendered as a literal slash
+of heuristics] that defined when `/` would be rendered as a literal slash
 versus treated as an operator.
 
 [a set of heuristics]: https://sass-lang.com/documentation/operators/numeric#slash-separated-values
 
 For a long time, these heuristics worked pretty well. In recent years, however,
-new additions to CSS such as [CSS Grid][] and [CSS Color Level 4][] have been
+new additions to CSS such as [CSS Grid] and [CSS Color Level 4] have been
 using `/` as a separator increasingly often. Using the same character for both
 division and slash-separation is becoming more and more annoying to users, and
 will likely eventually become untenable.
@@ -124,7 +124,7 @@ efficient to write than a function call for many Sass users.
 We eventually want to add native Sass support for parsing `calc()` expressions,
 resolving them at compile-time if possible, and producing a new Sass value that
 can have arithmetic performed on it if necessary. This is known as [first-class
-`calc()`][], and it would mean that division could be written unambiguously
+`calc()`], and it would mean that division could be written unambiguously
 using `/` in the context of a `calc()` expression. For example, `$width / 2`
 would be instead written `calc($width / 2)`.
 
@@ -132,7 +132,7 @@ would be instead written `calc($width / 2)`.
 
 However, first-class `calc()` is likely to be a very complex feature to design
 and implement. Most of the resources available for large-scale language features
-are currently focused on [the new module system][], so it's likely that a full
+are currently focused on [the new module system], so it's likely that a full
 implementation of first-class `calc()` won't land until mid-to-late 2020. And
 the full implementation is a prerequisite for even *beginning* the deprecation
 cycle for `/`-as-division, which means we probably wouldn't fully support
@@ -236,7 +236,7 @@ support for slash-separated lists. The new grammar for this production is:
 > This defines `/` to bind tighter than `,` but looser than space-separated
 > lists. This was chosen because most common uses of `/` in CSS conceptually
 > bind looser than space-separated values. The only exception is the [`font`
-> shorthand syntax][], which is used much more rarely will still work (albeit
+> shorthand syntax], which is used much more rarely will still work (albeit
 > with an unintuitive SassScript representation) with a loose-binding `/`.
 >
 > [`font` shorthand syntax]: https://developer.mozilla.org/en-US/docs/Web/CSS/font
@@ -374,7 +374,7 @@ overload to be the following:
 
 [old rgb]: ../spec/functions.md#rgb-and-rgba
 
-* If `$channels` is a [special variable string][], return a plain CSS function
+* If `$channels` is a [special variable string], return a plain CSS function
   string with the name `"rgb"` and the argument `$channels`.
 
   [special variable string]: ../spec/functions.md#special-variable-string
@@ -393,7 +393,7 @@ overload to be the following:
 
   * If `rgb` has fewer than three elements:
 
-    * If any element of `rgb` is a [special variable string][], return a
+    * If any element of `rgb` is a [special variable string], return a
       plain CSS function string with the name `"rgb"` and the argument
       `$channels`.
 
@@ -418,7 +418,7 @@ overload to be the following:
 
 [old hsl]: ../spec/functions.md#hsl-and-hsla
 
-* If `$channels` is a [special variable string][], return a plain CSS function
+* If `$channels` is a [special variable string], return a plain CSS function
   string with the name `"hsl"` and the argument `$channels`.
 
 * If `$channels` is an unbracketed slash-separated list:
@@ -435,7 +435,7 @@ overload to be the following:
 
   * If `hsl` has fewer than three elements:
 
-    * If any element of `hsl` is a [special variable string][], return a
+    * If any element of `hsl` is a [special variable string], return a
       plain CSS function string with the name `"hsl"` and the argument
       `$channels`.
 
@@ -451,7 +451,7 @@ overload to be the following:
 ### Selector Functions
 
 This proposal modifies [the "Parse a Selector From a SassScript Object"
-procedure][] to throw an error whenever it encounters a slash-separated list.
+procedure] to throw an error whenever it encounters a slash-separated list.
 
 [the "Parse a Selector From a SassScript Object" procedure]: ../spec/built-in-modules/selector.md#parse-a-selector-from-a-sassscript-object
 
@@ -531,7 +531,7 @@ described above (so `math.div()` will only accept numbers). In phase 2, the
 `list.slash()` function will emit a deprecation warning whenever it's called.
 
 > It's recommended that implementations increment their major version numbers
-> with the release of phase 2, in accordance with [semantic versioning][].
+> with the release of phase 2, in accordance with [semantic versioning].
 >
 > [semantic versioning]: https://semver.org/
 
diff --git a/accepted/supports-general.md b/accepted/supports-general.md
index b3356840..4a2517a0 100644
--- a/accepted/supports-general.md
+++ b/accepted/supports-general.md
@@ -3,7 +3,7 @@
 *([Issue](https://github.com/sass/sass/issues/2780), [Changelog](supports-general.changes.md))*
 
 This proposal defines how Sass parses supports queries that use the
-[``][] production.
+[``] production.
 
 [``]: https://drafts.csswg.org/mediaqueries-4/#typedef-general-enclosed
 
@@ -24,13 +24,13 @@ This proposal defines how Sass parses supports queries that use the
 > This section is non-normative.
 
 Historically, Sass has supported the `@supports` condition syntax as defined in
-[the April 2013 CSS Conditional Rules Level 3 Candidate Recommendation][], with
+[the April 2013 CSS Conditional Rules Level 3 Candidate Recommendation], with
 the addition of supporting raw SassScript expressions in the declaration syntax.
-The [Editor's Draft][] (as published October 2019) expands this syntax with a
+The [Editor's Draft] (as published October 2019) expands this syntax with a
 `` production to ensure parser forwards-compatibility with
-future CSS, which Sass does not yet support. The [Level 4 Editor's Draft][] (as
+future CSS, which Sass does not yet support. The [Level 4 Editor's Draft] (as
 of March 2019) further adds a `selector()` function syntax (which is covered by
-``), which is [supported by Firefox][] as of version 69.
+``), which is [supported by Firefox] as of version 69.
 
 [the April 2013 CSS Conditional Rules Level 3 Candidate Recommendation]: https://www.w3.org/TR/2013/CR-css3-conditional-20130404/#at-supports
 [Editor's Draft]: https://drafts.csswg.org/css-conditional-3/#at-supports
@@ -93,10 +93,10 @@ expression. If not, Sass must continually update its syntax to support new CSS
 constructs.
 
 We've been burned by this in the past. Both this proposal and the [media ranges
-proposal][] would have been unnecessary (or at least much simpler) if the rules
+proposal] would have been unnecessary (or at least much simpler) if the rules
 in questions had only allowed SassScript via interpolation in the first place.
 And it's likely that this syntax *will* evolve in ways that aren't
-SassScript-compatible, as with the `selector()` function [mentioned above][].
+SassScript-compatible, as with the `selector()` function [mentioned above].
 
 [media ranges proposal]: ../accepted/media-ranges.md
 [mentioned above]: #background
@@ -139,8 +139,8 @@ ambiguous with a declaration and thus with raw SassScript.
 **SupportsInParens**    ::= '(' (SupportsCondition | SupportsDeclaration | SupportsAnything) ')'
                       | SupportsFunction | Interpolation
 **SupportsDeclaration** ::= Expression¹ ':' Expression
-**SupportsAnything**    ::= [InterpolatedIdentifier][]² [InterpolatedAnyValue][]³?
-**SupportsFunction**    ::= [InterpolatedIdentifier][]⁴ '(' [InterpolatedAnyValue][]? ')'
+**SupportsAnything**    ::= [InterpolatedIdentifier]² [InterpolatedAnyValue]³?
+**SupportsFunction**    ::= [InterpolatedIdentifier]⁴ '(' [InterpolatedAnyValue]? ')'
 
[InterpolatedIdentifier]: ../spec/syntax.md#interpolatedidentifier @@ -168,7 +168,7 @@ the purposes of this production. ### `InterpolatedAnyValue` -The `InterpolatedAnyValue` production is identical to CSS's [``][] +The `InterpolatedAnyValue` production is identical to CSS's [``] except that after it parses `"#{"`, it parses an `Expression` which must be followed by `"}"`. diff --git a/js-api-doc/deprecations.d.ts b/js-api-doc/deprecations.d.ts index 83eb8b5f..4abff530 100644 --- a/js-api-doc/deprecations.d.ts +++ b/js-api-doc/deprecations.d.ts @@ -6,7 +6,7 @@ */ export interface Deprecations { // START AUTOGENERATED LIST - // Checksum: eb5e3889156f5ed12e119f11786f06f91a5f05c2 + // Checksum: b87f31f543f52c97431cce85ef11e92b6a71cfde /** * Deprecation for passing a string directly to meta.call(). @@ -113,17 +113,24 @@ export interface Deprecations { */ 'css-function-mixin': Deprecation<'css-function-mixin'>; + /** + * Deprecation for declarations after or between nested rules. + * + * This deprecation became active in Dart Sass 1.77.7. + */ + 'mixed-decls': Deprecation<'mixed-decls'>; + /** * Deprecation for certain uses of built-in sass:color functions. * - * This deprecation became active in Dart Sass 1.78.0. + * This deprecation became active in Dart Sass 1.79.0. */ 'color-4-api': Deprecation<'color-4-api'>; /** * Deprecation for using global color functions instead of sass:color. * - * This deprecation became active in Dart Sass 1.78.0. + * This deprecation became active in Dart Sass 1.79.0. */ 'color-functions': Deprecation<'color-functions'>; diff --git a/js-api-doc/index.d.ts b/js-api-doc/index.d.ts index e1d8fd62..3520dda8 100644 --- a/js-api-doc/index.d.ts +++ b/js-api-doc/index.d.ts @@ -29,7 +29,7 @@ export { ImporterResult, NodePackageImporter, } from './importer'; -export {Logger, SourceSpan, SourceLocation} from './logger'; +export {Logger, LoggerWarnOptions, SourceSpan, SourceLocation} from './logger'; export { CustomFunction, Options, diff --git a/js-api-doc/logger/index.d.ts b/js-api-doc/logger/index.d.ts index 937051e7..84ee9c2b 100644 --- a/js-api-doc/logger/index.d.ts +++ b/js-api-doc/logger/index.d.ts @@ -4,6 +4,35 @@ import {SourceSpan} from './source_span'; export {SourceLocation} from './source_location'; export {SourceSpan} from './source_span'; +/** + * The options passed to {@link Logger.warn}. + * + * * `deprecation`: Whether this is a deprecation warning. + * + * * `deprecationType`: The type of deprecation. Only set if `deprecation` is + * true. + * + * * `span`: The location in the Sass source code that generated this warning. + * This may be unset if the warning didn't come from Sass source, for + * example if it's from a deprecated JavaScript option. + * + * * `stack`: The Sass stack trace at the point the warning was issued. This may + * be unset if the warning didn't come from Sass source, for example if it's + * from a deprecated JavaScript option. + * + * @category Logger + */ +export type LoggerWarnOptions = ( + | { + deprecation: true; + deprecationType: Deprecation; + } + | {deprecation: false} +) & { + span?: SourceSpan; + stack?: string; +}; + /** * An object that can be passed to {@link LegacySharedOptions.logger} to control * how Sass emits warnings and debug messages. @@ -42,24 +71,11 @@ export interface Logger { * * If this is `undefined`, Sass will print warnings to standard error. * + * `options` may contain the following fields: + * * @param message - The warning message. - * @param options.deprecation - Whether this is a deprecation warning. - * @param options.deprecationType - The type of deprecation this warning is - * for, if any. - * @param options.span - The location in the Sass source code that generated this - * warning. - * @param options.stack - The Sass stack trace at the point the warning was issued. */ - warn?( - message: string, - options: ( - | { - deprecation: true; - deprecationType: Deprecation; - } - | {deprecation: false} - ) & {span?: SourceSpan; stack?: string} - ): void; + warn?(message: string, options: LoggerWarnOptions): void; /** * This method is called when Sass emits a debug message due to a [`@debug` diff --git a/package-lock.json b/package-lock.json index e7edb87d..7abe8384 100644 --- a/package-lock.json +++ b/package-lock.json @@ -8,7 +8,6 @@ "dependencies": { "@types/diff": "^5.0.1", "@types/glob": "^7.1.4", - "@types/js-yaml": "^4.0.3", "@types/marked": "^4.0.8", "@types/node": "^14.11.2", "@types/prettier": "^2.4.1", @@ -18,17 +17,17 @@ "gts": "^3.1.0", "immutable": "^4.0.0", "indent-string": "^4.0.0", - "js-yaml": "^4.1.0", "markdown-link-check": "3.11.1", "markdown-toc": "^1.2.0", - "markdownlint-cli2": "^0.8.1", + "markdownlint-cli2": "^0.13.0", "marked": "^4.3.0", "prettier": "^2.4.1", "source-map-js": "^0.6.2", "ts-dedent": "^2.2.0", "ts-node": "^10.2.1", "typedoc": "^0.24.7", - "typescript": "^5.0.4" + "typescript": "^5.0.4", + "yaml": "^2.2.1" }, "engines": { "node": ">=14.0.0" @@ -306,6 +305,17 @@ "node": ">=14" } }, + "node_modules/@sindresorhus/merge-streams": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/@sindresorhus/merge-streams/-/merge-streams-2.3.0.tgz", + "integrity": "sha512-LtoMMhxAlorcGhmFYI+LhPgbPZCkgP6ra1YL604EeF6U98pLlQ3iWIGMdWSC+vWmPBWBNgmDBAhnAobLROJmwg==", + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, "node_modules/@tsconfig/node10": { "version": "1.0.8", "resolved": "https://registry.npmjs.org/@tsconfig/node10/-/node10-1.0.8.tgz", @@ -340,11 +350,6 @@ "@types/node": "*" } }, - "node_modules/@types/js-yaml": { - "version": "4.0.9", - "resolved": "https://registry.npmjs.org/@types/js-yaml/-/js-yaml-4.0.9.tgz", - "integrity": "sha512-k4MGaQl5TGo/iipqb2UDG2UwjXziSWkh0uysQelTlJpX1qGlpUZYm8PnO4DxG1qBomtJUdYJ6qR6xdIah10JLg==" - }, "node_modules/@types/json-schema": { "version": "7.0.9", "resolved": "https://registry.npmjs.org/@types/json-schema/-/json-schema-7.0.9.tgz", @@ -1574,9 +1579,9 @@ "integrity": "sha512-xJuoT5+L99XlZ8twedaRf6Ax2TgQVxvgZOYoPKqZufmJib0tL2tegPBOZb1pVNgIhlqDlA0eO0c3wBvQcmzx4w==" }, "node_modules/fast-glob": { - "version": "3.3.1", - "resolved": "https://registry.npmjs.org/fast-glob/-/fast-glob-3.3.1.tgz", - "integrity": "sha512-kNFPyjhh5cKjrUltxs+wFx+ZkbRaxxmZ+X0ZU31SOsxCEtP9VPgtq2teZw1DebupL5GmDaNQ6yKMMVcM41iqDg==", + "version": "3.3.2", + "resolved": "https://registry.npmjs.org/fast-glob/-/fast-glob-3.3.2.tgz", + "integrity": "sha512-oX2ruAFQwf/Orj8m737Y5adxDQO0LAB7/S5MnxCdTNDd4p6BsyIVsv9JQsATbTSq8KHRpLwIHbVlUNatxd+1Ow==", "dependencies": { "@nodelib/fs.stat": "^2.0.2", "@nodelib/fs.walk": "^1.2.3", @@ -2295,9 +2300,9 @@ } }, "node_modules/jsonc-parser": { - "version": "3.2.0", - "resolved": "https://registry.npmjs.org/jsonc-parser/-/jsonc-parser-3.2.0.tgz", - "integrity": "sha512-gfFQZrcTc8CnKXp6Y4/CBT3fTc0OVuDofpre4aEeEpSBPV5X5v4+Vmx+8snU7RLPrNHPKSgLxGo9YuQzz20o+w==" + "version": "3.2.1", + "resolved": "https://registry.npmjs.org/jsonc-parser/-/jsonc-parser-3.2.1.tgz", + "integrity": "sha512-AilxAyFOAcK5wA1+LeaySVBrHsGQvUFCDWXKpZjzaL0PqW+xfBOttn8GNtWKFWqneyMZj41MWF9Kl6iPWLwgOA==" }, "node_modules/kind-of": { "version": "3.2.2", @@ -2355,11 +2360,11 @@ "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==" }, "node_modules/linkify-it": { - "version": "4.0.1", - "resolved": "https://registry.npmjs.org/linkify-it/-/linkify-it-4.0.1.tgz", - "integrity": "sha512-C7bfi1UZmoj8+PQx22XyeXCuBlokoyWQL5pWSP+EI6nzRylyThouddufc2c1NDIcP9k5agmN9fLpA7VNJfIiqw==", + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/linkify-it/-/linkify-it-5.0.0.tgz", + "integrity": "sha512-5aHCbzQRADcdP+ATqnDuhhJ/MRIqDkZX5pyjFHRRysS8vZ5AbqGEoFIb6pYHPZ+L/OC2Lc+xT8uHVVR5CAK/wQ==", "dependencies": { - "uc.micro": "^1.0.1" + "uc.micro": "^2.0.0" } }, "node_modules/list-item": { @@ -2462,18 +2467,19 @@ } }, "node_modules/markdown-it": { - "version": "13.0.1", - "resolved": "https://registry.npmjs.org/markdown-it/-/markdown-it-13.0.1.tgz", - "integrity": "sha512-lTlxriVoy2criHP0JKRhO2VDG9c2ypWCsT237eDiLqi09rmbKoUetyGHq2uOIRoRS//kfoJckS0eUzzkDR+k2Q==", + "version": "14.1.0", + "resolved": "https://registry.npmjs.org/markdown-it/-/markdown-it-14.1.0.tgz", + "integrity": "sha512-a54IwgWPaeBCAAsv13YgmALOF1elABB08FxO9i+r4VFk5Vl4pKokRPeX8u5TCgSsPi6ec1otfLjdOpVcgbpshg==", "dependencies": { "argparse": "^2.0.1", - "entities": "~3.0.1", - "linkify-it": "^4.0.1", - "mdurl": "^1.0.1", - "uc.micro": "^1.0.5" + "entities": "^4.4.0", + "linkify-it": "^5.0.0", + "mdurl": "^2.0.0", + "punycode.js": "^2.3.1", + "uc.micro": "^2.1.0" }, "bin": { - "markdown-it": "bin/markdown-it.js" + "markdown-it": "bin/markdown-it.mjs" } }, "node_modules/markdown-it/node_modules/argparse": { @@ -2481,17 +2487,6 @@ "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz", "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==" }, - "node_modules/markdown-it/node_modules/entities": { - "version": "3.0.1", - "resolved": "https://registry.npmjs.org/entities/-/entities-3.0.1.tgz", - "integrity": "sha512-WiyBqoomrwMdFG1e0kqvASYfnlb0lp8M5o5Fw2OFq1hNZxxcNk8Ik0Xm7LxzBhuidnZB/UtBqVCgUz3kBOP51Q==", - "engines": { - "node": ">=0.12" - }, - "funding": { - "url": "https://github.com/fb55/entities?sponsor=1" - } - }, "node_modules/markdown-link": { "version": "0.1.1", "resolved": "https://registry.npmjs.org/markdown-link/-/markdown-link-0.1.1.tgz", @@ -2564,36 +2559,40 @@ } }, "node_modules/markdownlint": { - "version": "0.29.0", - "resolved": "https://registry.npmjs.org/markdownlint/-/markdownlint-0.29.0.tgz", - "integrity": "sha512-ASAzqpODstu/Qsk0xW5BPgWnK/qjpBQ4e7IpsSvvFXcfYIjanLTdwFRJK1SIEEh0fGSMKXcJf/qhaZYHyME0wA==", + "version": "0.34.0", + "resolved": "https://registry.npmjs.org/markdownlint/-/markdownlint-0.34.0.tgz", + "integrity": "sha512-qwGyuyKwjkEMOJ10XN6OTKNOVYvOIi35RNvDLNxTof5s8UmyGHlCdpngRHoRGNvQVGuxO3BJ7uNSgdeX166WXw==", "dependencies": { - "markdown-it": "13.0.1", - "markdownlint-micromark": "0.1.5" + "markdown-it": "14.1.0", + "markdownlint-micromark": "0.1.9" }, "engines": { - "node": ">=16" + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/DavidAnson" } }, "node_modules/markdownlint-cli2": { - "version": "0.8.1", - "resolved": "https://registry.npmjs.org/markdownlint-cli2/-/markdownlint-cli2-0.8.1.tgz", - "integrity": "sha512-y0Siwt+RApKxSSb0CT9p7z1DcAO+ncjrB9IpC/jflJRIet4namCFmxLTbfBBQdPF6EntPk5yyXKe7vcoPGlnXw==", + "version": "0.13.0", + "resolved": "https://registry.npmjs.org/markdownlint-cli2/-/markdownlint-cli2-0.13.0.tgz", + "integrity": "sha512-Pg4nF7HlopU97ZXtrcVISWp3bdsuc5M0zXyLp2/sJv2zEMlInrau0ZKK482fQURzVezJzWBpNmu4u6vGAhij+g==", "dependencies": { - "globby": "13.1.4", - "markdownlint": "0.29.0", + "globby": "14.0.1", + "js-yaml": "4.1.0", + "jsonc-parser": "3.2.1", + "markdownlint": "0.34.0", "markdownlint-cli2-formatter-default": "0.0.4", - "micromatch": "4.0.5", - "strip-json-comments": "5.0.0", - "yaml": "2.3.1" + "micromatch": "4.0.5" }, "bin": { - "markdownlint-cli2": "markdownlint-cli2.js", - "markdownlint-cli2-config": "markdownlint-cli2-config.js", - "markdownlint-cli2-fix": "markdownlint-cli2-fix.js" + "markdownlint-cli2": "markdownlint-cli2.js" }, "engines": { - "node": ">=16" + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/DavidAnson" } }, "node_modules/markdownlint-cli2-formatter-default": { @@ -2605,27 +2604,28 @@ } }, "node_modules/markdownlint-cli2/node_modules/globby": { - "version": "13.1.4", - "resolved": "https://registry.npmjs.org/globby/-/globby-13.1.4.tgz", - "integrity": "sha512-iui/IiiW+QrJ1X1hKH5qwlMQyv34wJAYwH1vrf8b9kBA4sNiif3gKsMHa+BrdnOpEudWjpotfa7LrTzB1ERS/g==", + "version": "14.0.1", + "resolved": "https://registry.npmjs.org/globby/-/globby-14.0.1.tgz", + "integrity": "sha512-jOMLD2Z7MAhyG8aJpNOpmziMOP4rPLcc95oQPKXBazW82z+CEgPFBQvEpRUa1KeIMUJo4Wsm+q6uzO/Q/4BksQ==", "dependencies": { - "dir-glob": "^3.0.1", - "fast-glob": "^3.2.11", - "ignore": "^5.2.0", - "merge2": "^1.4.1", - "slash": "^4.0.0" + "@sindresorhus/merge-streams": "^2.1.0", + "fast-glob": "^3.3.2", + "ignore": "^5.2.4", + "path-type": "^5.0.0", + "slash": "^5.1.0", + "unicorn-magic": "^0.1.0" }, "engines": { - "node": "^12.20.0 || ^14.13.1 || >=16.0.0" + "node": ">=18" }, "funding": { "url": "https://github.com/sponsors/sindresorhus" } }, - "node_modules/markdownlint-cli2/node_modules/slash": { - "version": "4.0.0", - "resolved": "https://registry.npmjs.org/slash/-/slash-4.0.0.tgz", - "integrity": "sha512-3dOsAHXXUkQTpOYcoAxLIorMTp4gIQr5IW3iVb7A7lFIp0VHhnynm9izx6TssdrIcVIESAlVjtnO2K8bg+Coew==", + "node_modules/markdownlint-cli2/node_modules/path-type": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/path-type/-/path-type-5.0.0.tgz", + "integrity": "sha512-5HviZNaZcfqP95rwpv+1HDgUamezbqdSYTyzjTvwtJSnIH+3vnbmWsItli8OFEndS984VT55M3jduxZbX351gg==", "engines": { "node": ">=12" }, @@ -2633,10 +2633,10 @@ "url": "https://github.com/sponsors/sindresorhus" } }, - "node_modules/markdownlint-cli2/node_modules/strip-json-comments": { - "version": "5.0.0", - "resolved": "https://registry.npmjs.org/strip-json-comments/-/strip-json-comments-5.0.0.tgz", - "integrity": "sha512-V1LGY4UUo0jgwC+ELQ2BNWfPa17TIuwBLg+j1AA/9RPzKINl1lhxVEu2r+ZTTO8aetIsUzE5Qj6LMSBkoGYKKw==", + "node_modules/markdownlint-cli2/node_modules/slash": { + "version": "5.1.0", + "resolved": "https://registry.npmjs.org/slash/-/slash-5.1.0.tgz", + "integrity": "sha512-ZA6oR3T/pEyuqwMgAKT0/hAv8oAXckzbkmR0UkUosQ+Mc4RxGoJkRmwHgHufaenlyAgE1Mxgpdcrf75y6XcnDg==", "engines": { "node": ">=14.16" }, @@ -2645,11 +2645,14 @@ } }, "node_modules/markdownlint-micromark": { - "version": "0.1.5", - "resolved": "https://registry.npmjs.org/markdownlint-micromark/-/markdownlint-micromark-0.1.5.tgz", - "integrity": "sha512-HvofNU4QCvfUCWnocQP1IAWaqop5wpWrB0mKB6SSh0fcpV0PdmQNS6tdUuFew1utpYlUvYYzz84oDkrD76GB9A==", + "version": "0.1.9", + "resolved": "https://registry.npmjs.org/markdownlint-micromark/-/markdownlint-micromark-0.1.9.tgz", + "integrity": "sha512-5hVs/DzAFa8XqYosbEAEg6ok6MF2smDj89ztn9pKkCtdKHVdPQuGMH7frFfYL9mLkvfFe4pTyAMffLbjf3/EyA==", "engines": { - "node": ">=16" + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/DavidAnson" } }, "node_modules/marked": { @@ -2669,9 +2672,9 @@ "integrity": "sha512-rUxjysqif/BZQH2yhd5Aaq7vXMSx9NdEsQcyA07uEzIvxgI7zIr33gGsh+RU0/XjmQpCW7RsVof1vlkvQVCK5A==" }, "node_modules/mdurl": { - "version": "1.0.1", - "resolved": "https://registry.npmjs.org/mdurl/-/mdurl-1.0.1.tgz", - "integrity": "sha512-/sKlQJCBYVY9Ers9hqzKou4H6V5UWc/M59TH2dvkt+84itfnq7uFOMLpOiOS4ujvHP4etln18fmIxA5R5fll0g==" + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/mdurl/-/mdurl-2.0.0.tgz", + "integrity": "sha512-Lf+9+2r+Tdp5wXDXC4PcIBjTDtq4UKjCPMQhKIuzpJNW0b96kVqSwW0bT7FhRSfmAiFYgP+SCRvdrDozfh0U5w==" }, "node_modules/meow": { "version": "9.0.0", @@ -3186,6 +3189,14 @@ "node": ">=6" } }, + "node_modules/punycode.js": { + "version": "2.3.1", + "resolved": "https://registry.npmjs.org/punycode.js/-/punycode.js-2.3.1.tgz", + "integrity": "sha512-uxFIHU0YlHYhDQtV4R9J6a52SLx28BCjT+4ieh7IGbgwVJWO+km431c4yRlREUAsAmt/uMjQUyQHNEPf0M39CA==", + "engines": { + "node": ">=6" + } + }, "node_modules/queue-microtask": { "version": "1.2.3", "resolved": "https://registry.npmjs.org/queue-microtask/-/queue-microtask-1.2.3.tgz", @@ -4043,9 +4054,20 @@ } }, "node_modules/uc.micro": { - "version": "1.0.6", - "resolved": "https://registry.npmjs.org/uc.micro/-/uc.micro-1.0.6.tgz", - "integrity": "sha512-8Y75pvTYkLJW2hWQHXxoqRgV7qb9B+9vFEtidML+7koHUFapnVJAZ6cKs+Qjz5Aw3aZWHMC6u0wJE3At+nSGwA==" + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/uc.micro/-/uc.micro-2.1.0.tgz", + "integrity": "sha512-ARDJmphmdvUk6Glw7y9DQ2bFkKBHwQHLi2lsaH6PPmz/Ka9sFOBsBluozhDltWmnv9u/cF6Rt87znRTPV+yp/A==" + }, + "node_modules/unicorn-magic": { + "version": "0.1.0", + "resolved": "https://registry.npmjs.org/unicorn-magic/-/unicorn-magic-0.1.0.tgz", + "integrity": "sha512-lRfVq8fE8gz6QMBuDM6a+LO3IAzTi05H6gCVaUpir2E1Rwpo4ZUog45KpNXKC/Mn3Yb9UDuHumeFTo9iV/D9FQ==", + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } }, "node_modules/uri-js": { "version": "4.4.1", @@ -4457,6 +4479,11 @@ "integrity": "sha512-+1VkjdD0QBLPodGrJUeqarH8VAIvQODIbwh9XpP5Syisf7YoQgsJKPNFoqqLQlu+VQ/tVSshMR6loPMn8U+dPg==", "optional": true }, + "@sindresorhus/merge-streams": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/@sindresorhus/merge-streams/-/merge-streams-2.3.0.tgz", + "integrity": "sha512-LtoMMhxAlorcGhmFYI+LhPgbPZCkgP6ra1YL604EeF6U98pLlQ3iWIGMdWSC+vWmPBWBNgmDBAhnAobLROJmwg==" + }, "@tsconfig/node10": { "version": "1.0.8", "resolved": "https://registry.npmjs.org/@tsconfig/node10/-/node10-1.0.8.tgz", @@ -4491,11 +4518,6 @@ "@types/node": "*" } }, - "@types/js-yaml": { - "version": "4.0.9", - "resolved": "https://registry.npmjs.org/@types/js-yaml/-/js-yaml-4.0.9.tgz", - "integrity": "sha512-k4MGaQl5TGo/iipqb2UDG2UwjXziSWkh0uysQelTlJpX1qGlpUZYm8PnO4DxG1qBomtJUdYJ6qR6xdIah10JLg==" - }, "@types/json-schema": { "version": "7.0.9", "resolved": "https://registry.npmjs.org/@types/json-schema/-/json-schema-7.0.9.tgz", @@ -5346,9 +5368,9 @@ "integrity": "sha512-xJuoT5+L99XlZ8twedaRf6Ax2TgQVxvgZOYoPKqZufmJib0tL2tegPBOZb1pVNgIhlqDlA0eO0c3wBvQcmzx4w==" }, "fast-glob": { - "version": "3.3.1", - "resolved": "https://registry.npmjs.org/fast-glob/-/fast-glob-3.3.1.tgz", - "integrity": "sha512-kNFPyjhh5cKjrUltxs+wFx+ZkbRaxxmZ+X0ZU31SOsxCEtP9VPgtq2teZw1DebupL5GmDaNQ6yKMMVcM41iqDg==", + "version": "3.3.2", + "resolved": "https://registry.npmjs.org/fast-glob/-/fast-glob-3.3.2.tgz", + "integrity": "sha512-oX2ruAFQwf/Orj8m737Y5adxDQO0LAB7/S5MnxCdTNDd4p6BsyIVsv9JQsATbTSq8KHRpLwIHbVlUNatxd+1Ow==", "requires": { "@nodelib/fs.stat": "^2.0.2", "@nodelib/fs.walk": "^1.2.3", @@ -5877,9 +5899,9 @@ "integrity": "sha512-XmOWe7eyHYH14cLdVPoyg+GOH3rYX++KpzrylJwSW98t3Nk+U8XOl8FWKOgwtzdb8lXGf6zYwDUzeHMWfxasyg==" }, "jsonc-parser": { - "version": "3.2.0", - "resolved": "https://registry.npmjs.org/jsonc-parser/-/jsonc-parser-3.2.0.tgz", - "integrity": "sha512-gfFQZrcTc8CnKXp6Y4/CBT3fTc0OVuDofpre4aEeEpSBPV5X5v4+Vmx+8snU7RLPrNHPKSgLxGo9YuQzz20o+w==" + "version": "3.2.1", + "resolved": "https://registry.npmjs.org/jsonc-parser/-/jsonc-parser-3.2.1.tgz", + "integrity": "sha512-AilxAyFOAcK5wA1+LeaySVBrHsGQvUFCDWXKpZjzaL0PqW+xfBOttn8GNtWKFWqneyMZj41MWF9Kl6iPWLwgOA==" }, "kind-of": { "version": "3.2.2", @@ -5930,11 +5952,11 @@ } }, "linkify-it": { - "version": "4.0.1", - "resolved": "https://registry.npmjs.org/linkify-it/-/linkify-it-4.0.1.tgz", - "integrity": "sha512-C7bfi1UZmoj8+PQx22XyeXCuBlokoyWQL5pWSP+EI6nzRylyThouddufc2c1NDIcP9k5agmN9fLpA7VNJfIiqw==", + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/linkify-it/-/linkify-it-5.0.0.tgz", + "integrity": "sha512-5aHCbzQRADcdP+ATqnDuhhJ/MRIqDkZX5pyjFHRRysS8vZ5AbqGEoFIb6pYHPZ+L/OC2Lc+xT8uHVVR5CAK/wQ==", "requires": { - "uc.micro": "^1.0.1" + "uc.micro": "^2.0.0" } }, "list-item": { @@ -6022,26 +6044,22 @@ "integrity": "sha512-hdN1wVrZbb29eBGiGjJbeP8JbKjq1urkHJ/LIP/NY48MZ1QVXUsQBV1G1zvYFHn1XE06cwjBsOI2K3Ulnj1YXQ==" }, "markdown-it": { - "version": "13.0.1", - "resolved": "https://registry.npmjs.org/markdown-it/-/markdown-it-13.0.1.tgz", - "integrity": "sha512-lTlxriVoy2criHP0JKRhO2VDG9c2ypWCsT237eDiLqi09rmbKoUetyGHq2uOIRoRS//kfoJckS0eUzzkDR+k2Q==", + "version": "14.1.0", + "resolved": "https://registry.npmjs.org/markdown-it/-/markdown-it-14.1.0.tgz", + "integrity": "sha512-a54IwgWPaeBCAAsv13YgmALOF1elABB08FxO9i+r4VFk5Vl4pKokRPeX8u5TCgSsPi6ec1otfLjdOpVcgbpshg==", "requires": { "argparse": "^2.0.1", - "entities": "~3.0.1", - "linkify-it": "^4.0.1", - "mdurl": "^1.0.1", - "uc.micro": "^1.0.5" + "entities": "^4.4.0", + "linkify-it": "^5.0.0", + "mdurl": "^2.0.0", + "punycode.js": "^2.3.1", + "uc.micro": "^2.1.0" }, "dependencies": { "argparse": { "version": "2.0.1", "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz", "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==" - }, - "entities": { - "version": "3.0.1", - "resolved": "https://registry.npmjs.org/entities/-/entities-3.0.1.tgz", - "integrity": "sha512-WiyBqoomrwMdFG1e0kqvASYfnlb0lp8M5o5Fw2OFq1hNZxxcNk8Ik0Xm7LxzBhuidnZB/UtBqVCgUz3kBOP51Q==" } } }, @@ -6101,48 +6119,49 @@ } }, "markdownlint": { - "version": "0.29.0", - "resolved": "https://registry.npmjs.org/markdownlint/-/markdownlint-0.29.0.tgz", - "integrity": "sha512-ASAzqpODstu/Qsk0xW5BPgWnK/qjpBQ4e7IpsSvvFXcfYIjanLTdwFRJK1SIEEh0fGSMKXcJf/qhaZYHyME0wA==", + "version": "0.34.0", + "resolved": "https://registry.npmjs.org/markdownlint/-/markdownlint-0.34.0.tgz", + "integrity": "sha512-qwGyuyKwjkEMOJ10XN6OTKNOVYvOIi35RNvDLNxTof5s8UmyGHlCdpngRHoRGNvQVGuxO3BJ7uNSgdeX166WXw==", "requires": { - "markdown-it": "13.0.1", - "markdownlint-micromark": "0.1.5" + "markdown-it": "14.1.0", + "markdownlint-micromark": "0.1.9" } }, "markdownlint-cli2": { - "version": "0.8.1", - "resolved": "https://registry.npmjs.org/markdownlint-cli2/-/markdownlint-cli2-0.8.1.tgz", - "integrity": "sha512-y0Siwt+RApKxSSb0CT9p7z1DcAO+ncjrB9IpC/jflJRIet4namCFmxLTbfBBQdPF6EntPk5yyXKe7vcoPGlnXw==", + "version": "0.13.0", + "resolved": "https://registry.npmjs.org/markdownlint-cli2/-/markdownlint-cli2-0.13.0.tgz", + "integrity": "sha512-Pg4nF7HlopU97ZXtrcVISWp3bdsuc5M0zXyLp2/sJv2zEMlInrau0ZKK482fQURzVezJzWBpNmu4u6vGAhij+g==", "requires": { - "globby": "13.1.4", - "markdownlint": "0.29.0", + "globby": "14.0.1", + "js-yaml": "4.1.0", + "jsonc-parser": "3.2.1", + "markdownlint": "0.34.0", "markdownlint-cli2-formatter-default": "0.0.4", - "micromatch": "4.0.5", - "strip-json-comments": "5.0.0", - "yaml": "2.3.1" + "micromatch": "4.0.5" }, "dependencies": { "globby": { - "version": "13.1.4", - "resolved": "https://registry.npmjs.org/globby/-/globby-13.1.4.tgz", - "integrity": "sha512-iui/IiiW+QrJ1X1hKH5qwlMQyv34wJAYwH1vrf8b9kBA4sNiif3gKsMHa+BrdnOpEudWjpotfa7LrTzB1ERS/g==", + "version": "14.0.1", + "resolved": "https://registry.npmjs.org/globby/-/globby-14.0.1.tgz", + "integrity": "sha512-jOMLD2Z7MAhyG8aJpNOpmziMOP4rPLcc95oQPKXBazW82z+CEgPFBQvEpRUa1KeIMUJo4Wsm+q6uzO/Q/4BksQ==", "requires": { - "dir-glob": "^3.0.1", - "fast-glob": "^3.2.11", - "ignore": "^5.2.0", - "merge2": "^1.4.1", - "slash": "^4.0.0" + "@sindresorhus/merge-streams": "^2.1.0", + "fast-glob": "^3.3.2", + "ignore": "^5.2.4", + "path-type": "^5.0.0", + "slash": "^5.1.0", + "unicorn-magic": "^0.1.0" } }, - "slash": { - "version": "4.0.0", - "resolved": "https://registry.npmjs.org/slash/-/slash-4.0.0.tgz", - "integrity": "sha512-3dOsAHXXUkQTpOYcoAxLIorMTp4gIQr5IW3iVb7A7lFIp0VHhnynm9izx6TssdrIcVIESAlVjtnO2K8bg+Coew==" - }, - "strip-json-comments": { + "path-type": { "version": "5.0.0", - "resolved": "https://registry.npmjs.org/strip-json-comments/-/strip-json-comments-5.0.0.tgz", - "integrity": "sha512-V1LGY4UUo0jgwC+ELQ2BNWfPa17TIuwBLg+j1AA/9RPzKINl1lhxVEu2r+ZTTO8aetIsUzE5Qj6LMSBkoGYKKw==" + "resolved": "https://registry.npmjs.org/path-type/-/path-type-5.0.0.tgz", + "integrity": "sha512-5HviZNaZcfqP95rwpv+1HDgUamezbqdSYTyzjTvwtJSnIH+3vnbmWsItli8OFEndS984VT55M3jduxZbX351gg==" + }, + "slash": { + "version": "5.1.0", + "resolved": "https://registry.npmjs.org/slash/-/slash-5.1.0.tgz", + "integrity": "sha512-ZA6oR3T/pEyuqwMgAKT0/hAv8oAXckzbkmR0UkUosQ+Mc4RxGoJkRmwHgHufaenlyAgE1Mxgpdcrf75y6XcnDg==" } } }, @@ -6153,9 +6172,9 @@ "requires": {} }, "markdownlint-micromark": { - "version": "0.1.5", - "resolved": "https://registry.npmjs.org/markdownlint-micromark/-/markdownlint-micromark-0.1.5.tgz", - "integrity": "sha512-HvofNU4QCvfUCWnocQP1IAWaqop5wpWrB0mKB6SSh0fcpV0PdmQNS6tdUuFew1utpYlUvYYzz84oDkrD76GB9A==" + "version": "0.1.9", + "resolved": "https://registry.npmjs.org/markdownlint-micromark/-/markdownlint-micromark-0.1.9.tgz", + "integrity": "sha512-5hVs/DzAFa8XqYosbEAEg6ok6MF2smDj89ztn9pKkCtdKHVdPQuGMH7frFfYL9mLkvfFe4pTyAMffLbjf3/EyA==" }, "marked": { "version": "4.3.0", @@ -6168,9 +6187,9 @@ "integrity": "sha512-rUxjysqif/BZQH2yhd5Aaq7vXMSx9NdEsQcyA07uEzIvxgI7zIr33gGsh+RU0/XjmQpCW7RsVof1vlkvQVCK5A==" }, "mdurl": { - "version": "1.0.1", - "resolved": "https://registry.npmjs.org/mdurl/-/mdurl-1.0.1.tgz", - "integrity": "sha512-/sKlQJCBYVY9Ers9hqzKou4H6V5UWc/M59TH2dvkt+84itfnq7uFOMLpOiOS4ujvHP4etln18fmIxA5R5fll0g==" + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/mdurl/-/mdurl-2.0.0.tgz", + "integrity": "sha512-Lf+9+2r+Tdp5wXDXC4PcIBjTDtq4UKjCPMQhKIuzpJNW0b96kVqSwW0bT7FhRSfmAiFYgP+SCRvdrDozfh0U5w==" }, "meow": { "version": "9.0.0", @@ -6541,6 +6560,11 @@ "resolved": "https://registry.npmjs.org/punycode/-/punycode-2.1.1.tgz", "integrity": "sha512-XRsRjdf+j5ml+y/6GKHPZbrF/8p2Yga0JPtdqTIY2Xe5ohJPD9saDJJLPvp9+NSBprVvevdXZybnj2cv8OEd0A==" }, + "punycode.js": { + "version": "2.3.1", + "resolved": "https://registry.npmjs.org/punycode.js/-/punycode.js-2.3.1.tgz", + "integrity": "sha512-uxFIHU0YlHYhDQtV4R9J6a52SLx28BCjT+4ieh7IGbgwVJWO+km431c4yRlREUAsAmt/uMjQUyQHNEPf0M39CA==" + }, "queue-microtask": { "version": "1.2.3", "resolved": "https://registry.npmjs.org/queue-microtask/-/queue-microtask-1.2.3.tgz", @@ -7147,9 +7171,14 @@ "integrity": "sha512-cW9T5W9xY37cc+jfEnaUvX91foxtHkza3Nw3wkoF4sSlKn0MONdkdEndig/qPBWXNkmplh3NzayQzCiHM4/hqw==" }, "uc.micro": { - "version": "1.0.6", - "resolved": "https://registry.npmjs.org/uc.micro/-/uc.micro-1.0.6.tgz", - "integrity": "sha512-8Y75pvTYkLJW2hWQHXxoqRgV7qb9B+9vFEtidML+7koHUFapnVJAZ6cKs+Qjz5Aw3aZWHMC6u0wJE3At+nSGwA==" + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/uc.micro/-/uc.micro-2.1.0.tgz", + "integrity": "sha512-ARDJmphmdvUk6Glw7y9DQ2bFkKBHwQHLi2lsaH6PPmz/Ka9sFOBsBluozhDltWmnv9u/cF6Rt87znRTPV+yp/A==" + }, + "unicorn-magic": { + "version": "0.1.0", + "resolved": "https://registry.npmjs.org/unicorn-magic/-/unicorn-magic-0.1.0.tgz", + "integrity": "sha512-lRfVq8fE8gz6QMBuDM6a+LO3IAzTi05H6gCVaUpir2E1Rwpo4ZUog45KpNXKC/Mn3Yb9UDuHumeFTo9iV/D9FQ==" }, "uri-js": { "version": "4.4.1", diff --git a/package.json b/package.json index 7a2e480e..662acf34 100644 --- a/package.json +++ b/package.json @@ -36,7 +36,7 @@ "indent-string": "^4.0.0", "markdown-link-check": "3.11.1", "markdown-toc": "^1.2.0", - "markdownlint-cli2": "^0.8.1", + "markdownlint-cli2": "^0.13.0", "marked": "^4.3.0", "prettier": "^2.4.1", "source-map-js": "^0.6.2", diff --git a/spec/README.md b/spec/README.md deleted file mode 120000 index 8e636713..00000000 --- a/spec/README.md +++ /dev/null @@ -1 +0,0 @@ -spec.md \ No newline at end of file diff --git a/spec/README.md b/spec/README.md new file mode 100644 index 00000000..b307b271 --- /dev/null +++ b/spec/README.md @@ -0,0 +1,230 @@ +# Sass Specification + +This directory contains the formal specification for the Sass language. + +Sass is a *living specification*, which means that it's actively updated over +time without having distinctions between numbered versions. Different +implementations may support different subsets of the specification, although all +implementations are expected to work towards full support. The *reference +implementation* (currently [Dart Sass]) will generally support as close to the +full spec as possible. + +[Dart Sass]: https://sass-lang.com/dart-sass + +This specification is incomplete, and is added to *lazily*. This means that +portions of the spec are only written when they're necessary as background for +new language proposals. The Sass team eventually hopes to specify every part of +the language this way. + +## Table of Contents + +* [Definitions](#definitions) + * [Scope](#scope) + * [Global Scope](#global-scope) + * [Current Source File](#current-source-file) + * [Current Configuration](#current-configuration) + * [Current Import Context](#current-import-context) + * [Current Module](#current-module) +* [Procedures](#procedures) + * [Running in a New Scope](#running-in-a-new-scope) +* [Semantics](#semantics) + * [Compiling a Path](#compiling-a-path) + * [Compiling a String](#compiling-a-string) + * [Executing a File](#executing-a-file) + +## Definitions + +### Scope + +A *scope* is a mutable structure that contains: + +* The scope's *variables*: a mapping from identifiers to SassScript values. +* The scope's *mixins*: a mapping from identifiers to mixins. +* The scope's *functions*: a mapping from identifiers to functions. +* The scope's *parent*: a reference to another scope, which may be unset. + +One scope at a time is designated the *current scope*. By default, this is the +[global scope](#global-scope). + +### Global Scope + +The *global scope* is the scope shared among the top level of all Sass files. It +has no parent. + +### Current Source File + +The *current source file* is the [source file] that was passed to the innermost +active invocation of [Executing a File](#executing-a-file). + +[source file]: syntax.md#source-file + +*All current source files* refer to all the source files passed to any active +invocation of Executing a File. + +### Current Configuration + +The *current configuration* is the [configuration] that was passed to the +innermost active invocation of [Executing a File](#executing-a-file). + +[configuration]: modules.md#configuration + +### Current Import Context + +The *current import context* is the [import context] that was passed to the +innermost active invocation of [Executing a File](#executing-a-file). + +[import context]: modules.md#import-context + +### Current Module + +The *current module* is the [module] that was created by the innermost active +invocation of [Executing a File](#executing-a-file). + +[module]: modules.md#module + +> Because a module is only made immutable (other than its variables) when +> execution has finished, the current module is always mutable. + +## Procedures + +### Running in a New Scope + +To run a set of steps *in a new scope*: + +* Let `parent` be the [current scope]. + + [current scope]: #scope + +* Return the result of running the given steps with the current scope set to an + empty scope with `parent` as its parent. + +## Semantics + +### Compiling a Path + +> This an entrypoint to the specification; it's up to each implementation how it +> exposes this to the user. + +This algorithm takes a local filesystem path `path`, an optional list of +[importers] `importers`, and an optional list of paths `load-paths`. It returns +a string. + +* Let `text` be the result of decoding the binary contents of the file at + `path`. + +* Let `syntax` be: + + * "indented" if `path` ends in `.sass`. + * "css" if `path` ends in `.css`. + * "scss" otherwise. + +* Let `url` be the absolute `file:` URL corresponding to `path`. + +* Let `importer` be a [filesystem importer] with an arbitrary `base`. + + > This importer will only ever be passed absolute URLs, so its base won't + > matter. + +* Return the result of [compiling](#compiling-a-string) `text` with `syntax`, + `url`, `importer`, `importers`, and `load-paths`. + +[importers]: modules.md#importer + +### Compiling a String + +> This an entrypoint to the specification; it's up to each implementation how it +> exposes this to the user. + +This algorithm takes: + +* a string `string`, +* a syntax `syntax` ("indented", "scss", or "css"), +* an optional URL `url`, +* an optional [importer] `importer`, +* an optional list of importers `importers`, +* and an optional list of paths `load-paths`. + +[importer]: modules.md#importer + +It runs as follows: + +* Set the [global importer list] to `importers`. + +* For each `path` in `load-paths`: + + * Let `base` be the absolute `file:` URL that refers to `path`. + + * Add a [filesystem importer] with base `base` to the global importer list. + +* Let `ast` be the result of [parsing] `text` as `syntax`. + +* If `url` is null: + + * If `importer` is not null, throw an error. + + * Set `url` to a unique value. + + > This ensures that all source files have a valid URL. When displaying this + > value, implementations should help users understand the source of the string + > if possible. + +* If `importer` is null: + + * If `url` is a `file:` URL, set `importer` to be a [filesystem importer] with an + arbitrary `base`. + + > This importer will only ever be passed absolute URLs, so its base won't + > matter. + + * If `url` is not a `file:` URL, set `importer` to be a function that always + returns null. + +* Let `file` be the [source file] with `ast`, canonical URL `url`, and + importer `importer`. + +* Let `module` be the result of [executing](#executing-a-file) `file`. + +* Let `css` be the result of [resolving `module`'s extensions]. + + [resolving `module`'s extensions]: at-rules/extend.md#resolving-a-modules-extensions + +* Return the result of converting `css` to a CSS string. + +[filesystem importer]: modules.md#filesystem-importer +[parsing]: syntax.md#parsing-text +[global importer list]: modules.md#global-importer-list + +### Executing a File + +This algorithm takes a [source file] `file`, a [configuration] `config`, an +[import context] `import`, and returns a [module]. + +* Let `module` be an empty module with source file `file`. + +* Let `uses` be an empty map from `@use` rules to modules. + +* Execute each top-level statement as described in that statement's + specification. + + > The semantics for executing each statement is defined in that statement's + > individual specification. + +* For each variable declaration `variable` with a `!global` flag in `file`, + whether or not it was evaluated: + + * If `variable`'s name *doesn't* begin with `-` or `_` and `variable` is not + yet in `module`, set `variable` to `null` in `module`. + + > This isn't necessary for implementations that follow the most recent + > [variables spec] and don't allow `!global` assignments to variables that + > don't yet exist. However, at time of writing, all existing implementations + > are in the process of deprecating the old `!global` behavior, which + > allowed `!global` declarations to create new variables. + > + > Setting all `!global` variables to `null` if they weren't otherwise set + > guarantees the stability of static analysis by ensuring that the set of + > variables a module exposes doesn't depend on how it was executed. + + [variables spec]: variables.md + +* Return `module`. Its functions, mixins, and CSS are now immutable. diff --git a/spec/at-rules/extend.md b/spec/at-rules/extend.md index dc0325d8..70af5655 100644 --- a/spec/at-rules/extend.md +++ b/spec/at-rules/extend.md @@ -41,14 +41,14 @@ use of `@extend`: ### Extender -An `@extend` rule's *extender* is the [selector list][] for the style rule in +An `@extend` rule's *extender* is the [selector list] for the style rule in which the `@extend` rule appears. [selector list]: https://drafts.csswg.org/selectors-4/#selector-list ### Target -An `@extend` rule's *target* is the [simple selector][] that's used as an +An `@extend` rule's *target* is the [simple selector] that's used as an argument to `@extend`. [simple selector]: https://drafts.csswg.org/selectors-4/#simple @@ -61,8 +61,8 @@ An *extension* is a collection of various properties. > an `@extend` rule. As such, all `@extend` rules define extensions, but not all > extensions directly correspond to `@extend` rules. -* The *extender*, a [selector list][]. -* The *target*, a [simple selector][]. +* The *extender*, a [selector list]. +* The *target*, a [simple selector]. ### Extendee @@ -103,7 +103,7 @@ that module's transitive dependencies. To execute an `@extend` rule `rule`: -* If there is no [current style rule][], throw an error. +* If there is no [current style rule], throw an error. [current style rule]: ../style-rules.md#current-style-rule @@ -119,7 +119,7 @@ To execute an `@extend` rule `rule`: * Let `extension` be an [extension](#extension) whose extender is the current style rule's selector and whose target is `target`. -* Add `extension` to [the current module][]'s extensions. +* Add `extension` to [the current module]'s extensions. [the current module]: ../spec.md#current-module @@ -129,7 +129,7 @@ To execute an `@extend` rule `rule`: ### Resolving a Module's Extensions -This algorithm takes a [module][] `starting-module` and returns a [CSS tree][] +This algorithm takes a [module] `starting-module` and returns a [CSS tree] that includes CSS for *all* modules transitively used or forwarded by `starting-module`. @@ -144,12 +144,12 @@ that includes CSS for *all* modules transitively used or forwarded by * Let `new-extensions` be an empty map from modules to sets of [extensions](#extension). -* Let `extended` be the subgraph of the [module graph][] containing +* Let `extended` be the subgraph of the [module graph] containing modules that are transitively reachable from `starting-module`. [module graph]: ../modules.md#module-graph -* For each module `domestic` in `extended`, in reverse [topological][] order: +* For each module `domestic` in `extended`, in reverse [topological] order: [topological]: https://en.wikipedia.org/wiki/Topological_sorting diff --git a/spec/at-rules/for.md b/spec/at-rules/for.md index 99d168b7..9f326fe0 100644 --- a/spec/at-rules/for.md +++ b/spec/at-rules/for.md @@ -8,7 +8,7 @@ ## Syntax
-**ForRule**            ::= '@for' [PlainVariable][] FromDeclaration
+**ForRule**            ::= '@for' [PlainVariable] FromDeclaration
                        (ToDeclaration | ThroughDeclaration) ForBlock
 **FromDeclaration**    ::= 'from' Expression
 **ToDeclaration**      ::= 'to' Expression
diff --git a/spec/at-rules/forward.md b/spec/at-rules/forward.md
index b09a8140..9dfcaaab 100644
--- a/spec/at-rules/forward.md
+++ b/spec/at-rules/forward.md
@@ -1,6 +1,6 @@
 # `@forward`
 
-The `@forward` rule loads a [module][] from a URL and adds its members to the
+The `@forward` rule loads a [module] from a URL and adds its members to the
 public API of the current module without making them available to use within the
 current stylesheet.
 
@@ -17,21 +17,21 @@ The grammar for the `@forward` rule is as follows:
 
 
 **ForwardRule**         ::= '@forward' QuotedString AsClause? (ShowClause | HideClause)?  WithClause?
-**AsClause**            ::= 'as' [\][] '\*'
+**AsClause**            ::= 'as' [\] '\*'
 **ShowClause**          ::= 'show' MemberName (',' MemberName)\*
 **HideClause**          ::= 'hide' MemberName (',' MemberName)\*
 **WithClause**          ::= 'with' '('
                       ForwardWithArgument (',' ForwardWithArgument)\* ','?
                     ')'
 **ForwardWithArgument** ::= '$' Identifier ':' Expression '!default'?
-**MemberName**          ::= '$'? [\][]
+**MemberName**          ::= '$'? [\]
 
[\]: https://drafts.csswg.org/css-syntax-3/#ident-token-diagram `@forward` rules must be at the top level of the document, and must come before any rules other than `@charset` or `@use`. The `QuotedString`'s contents, known -as the rule's *URL*, must be a [valid URL string][] (for non-[special][] base +as the rule's *URL*, must be a [valid URL string] (for non-[special] base URL). No whitespace is allowed after `$` in `MemberName`, or before `*` in `AsClause`. @@ -80,7 +80,7 @@ To execute a `@forward` rule `rule`: * Add a variable to `rule-config` with the same name as `argument`'s identifier, and with `value` as its value. -* Let `forwarded` be the result of [loading the module][] with `rule`'s URL +* Let `forwarded` be the result of [loading the module] with `rule`'s URL string and `rule-config`. [loading the module]: ../modules.md#loading-a-module @@ -101,7 +101,7 @@ To execute a `@forward` rule `rule`: * If `rule` has an `AsClause` `as`, prepend `as`'s identifier to `name` (after the `$` if `member` is a variable). - * If there's a member defined at the top level of [the current source file][] + * If there's a member defined at the top level of [the current source file] named `name` with the same type as `member`, do nothing. * Otherwise, if `rule` has a `show` clause that doesn't include `name` @@ -116,11 +116,11 @@ To execute a `@forward` rule `rule`: * If another `@forward` rule's module has a member named `name` with the same type as `member`: - * If the other member is [identical to][] `member`, do nothing. + * If the other member is [identical to] `member`, do nothing. * Otherwise, throw an error. - * Otherwise, add `member` to [the current module][] with the name `name`. + * Otherwise, add `member` to [the current module] with the name `name`. > It's possible for the same member to be added to a given module multiple > times if it's forwarded with different prefixes. All of these names refer diff --git a/spec/at-rules/function.md b/spec/at-rules/function.md index 14aa4ec2..63f6b282 100644 --- a/spec/at-rules/function.md +++ b/spec/at-rules/function.md @@ -8,7 +8,7 @@ ## Syntax
-**FunctionRule** ::= '@function' [\][] ArgumentDeclaration '{' Statements '}'
+**FunctionRule** ::= '@function' [\] ArgumentDeclaration '{' Statements '}'
 
[\]: https://drafts.csswg.org/css-syntax-3/#ident-token-diagram @@ -52,7 +52,7 @@ To execute a `@function` rule `rule`: * If `rule` is outside of any block of statements: - * If `name` *doesn't* begin with `-` or `_`, set [the current module][]'s + * If `name` *doesn't* begin with `-` or `_`, set [the current module]'s function `name` to `function`. > This overrides the previous definition, if one exists. diff --git a/spec/at-rules/import.md b/spec/at-rules/import.md index 755c9667..047210d6 100644 --- a/spec/at-rules/import.md +++ b/spec/at-rules/import.md @@ -1,7 +1,7 @@ # Import The `@import` rule is the legacy way of splitting styles across multiple files -in Sass. The [`@use` rule][] should generally be used instead, but `@import` is +in Sass. The [`@use` rule] should generally be used instead, but `@import` is still supported for backwards-compatibility. [`@use` rule]: use.md @@ -23,7 +23,7 @@ still supported for backwards-compatibility. | InterpolatedIdentifier (',' [MediaQueryList])\* **ImportSupports** ::= 'supports(' SupportsDeclaration ')' **ImportFunction** ::= [InterpolatedIdentifier]¹ '(' InterpolatedDeclarationValue? ')' -**ImportUrl** ::= QuotedString | [InterpolatedUrl][] +**ImportUrl** ::= QuotedString | [InterpolatedUrl]
[InterpolatedIdentifier]: ../syntax.md#interpolatedidentifier @@ -112,20 +112,20 @@ To execute an `@import` rule `rule`: * Add an `@import` with the evaluated modifiers to [the current module]'s CSS AST after the longest initial subsequence of comments and `@import` rules. - * Otherwise, let `file` be the result of [loading the file][] with + * Otherwise, let `file` be the result of [loading the file] with `argument`'s URL string. If this returns null, throw an error. * If `file`'s canonical URL is the same as that of any other [current source - file][], throw an error. + file], throw an error. - * Let `imported` be the result of [executing][] `file` with the empty - configuration and the [current import context][], except that if + * Let `imported` be the result of [executing] `file` with the empty + configuration and the [current import context], except that if `rule` is nested within at-rules and/or style rules, that context is preserved when executing `file`. > Note that this execution can mutate `import`. - * Let `css` be the result of [resolving `imported`'s extensions][], except + * Let `css` be the result of [resolving `imported`'s extensions], except that if `rule` is nested within at-rules and/or style rules, that context is added to CSS that comes from modules loaded by `imported`. @@ -135,7 +135,7 @@ To execute an `@import` rule `rule`: * Add `css` to the current module's CSS. - * Add `imported`'s [extensions][] to the current module. + * Add `imported`'s [extensions] to the current module. * If the `@import` rule is nested within at-rules and/or style rules, add each member in `imported` to the [current scope]. diff --git a/spec/at-rules/mixin.md b/spec/at-rules/mixin.md index 016608d0..99e9837c 100644 --- a/spec/at-rules/mixin.md +++ b/spec/at-rules/mixin.md @@ -17,7 +17,7 @@ ### Syntax
-**MixinRule** ::= '@mixin' [\][] ArgumentDeclaration? '{' Statements '}'
+**MixinRule** ::= '@mixin' [\] ArgumentDeclaration? '{' Statements '}'
 
[\]: https://drafts.csswg.org/css-syntax-3/#ident-token-diagram @@ -73,7 +73,7 @@ To execute a `@mixin` rule `rule`: ### Syntax
-**IncludeRule**      ::= '@include' [NamespacedIdentifier][] ArgumentInvocation?
+**IncludeRule**      ::= '@include' [NamespacedIdentifier] ArgumentInvocation?
                      ContentBlock?
 **ContentBlock**     ::= UsingDeclaration? '{' Statements '}'
 **UsingDeclaration** ::= 'using' ArgumentDeclaration
diff --git a/spec/at-rules/nest.md b/spec/at-rules/nest.md
new file mode 100644
index 00000000..b6aa1721
--- /dev/null
+++ b/spec/at-rules/nest.md
@@ -0,0 +1,33 @@
+# `@nest` Rule
+
+Sass has special semantics for the `@nest` rule. Although this rule is primarily
+intended to give the CSSOM a consistent representation for interleaved
+declarations and is never required to be written explicitly, it *is* valid CSS
+and Sass must ensure that its use preserves the existing CSS semantics.
+
+## Syntax
+
+
+**NestRule** ::= '@nest'¹ '{' Statements '}'
+
+ +1: This is case-insensitive. + +## Semantics + +To execute a `@nest` rule `rule`: + +* If there's a [current keyframe block], throw an error. + + [current keyframe block]: ../style-rules.md#current-keyframe-block + +* If there's a [current style rule], evaluate each child in `rule`'s + `Statement`s. + + [current style rule]: ../style-rules.md#current-style-rule + +* Otherwise, [evaluate `rule` as an unknown at-rule] with + `InterpolatedIdentifier` "nest", no `InterpolatedValue`, and the same + `Statements`. + + [evaluate `rule` as an unknown at-rule]: ../at-rules/unknown.md diff --git a/spec/at-rules/use.md b/spec/at-rules/use.md index 00f352af..ba53233f 100644 --- a/spec/at-rules/use.md +++ b/spec/at-rules/use.md @@ -1,6 +1,6 @@ # `@use` -The `@use` rule loads a [module][] from a URL, makes its members available to +The `@use` rule loads a [module] from a URL, makes its members available to the current stylesheet, and includes its CSS in the compilation output. [module]: ../modules.md#module @@ -18,7 +18,7 @@ the current stylesheet, and includes its CSS in the compilation output. ### A `@use` Rule's Module -A `@use` rule's *module* is a [module][] associated with a `@use` rule. This +A `@use` rule's *module* is a [module] associated with a `@use` rule. This module is only associated once the rule has been [executed](#semantics). ## Syntax @@ -27,24 +27,24 @@ The grammar for the `@use` rule is as follows:
 **UseRule**         ::= '@use' QuotedString AsClause? WithClause?
-**AsClause**        ::= 'as' ('\*' | [\][])
+**AsClause**        ::= 'as' ('\*' | [\])
 **WithClause**      ::= 'with' '('
                       KeywordArgument (',' KeywordArgument)\* ','?
                     ')'
-**KeywordArgument** ::= '$' [\][] ':' Expression
+**KeywordArgument** ::= '$' [\] ':' Expression
 
[\]: https://drafts.csswg.org/css-syntax-3/#ident-token-diagram `@use` rules must be at the top level of the document, and must come before any rules other than `@charset` or `@forward`. The `QuotedString`'s contents, known -as the rule's *URL*, must be a [valid URL string][] (for non-[special][] base +as the rule's *URL*, must be a [valid URL string] (for non-[special] base URL). No whitespace is allowed after `$` in `KeywordArgument`. [valid URL string]: https://url.spec.whatwg.org/#valid-url-string [special]: https://url.spec.whatwg.org/#special-scheme -> Because each `@use` rule affects the namespace of the entire [source file][] +> Because each `@use` rule affects the namespace of the entire [source file] > that contains it, whereas most other Sass constructs are purely imperative, > keeping it at the top of the file helps reduce confusion. > @@ -68,7 +68,7 @@ A `@use` rule's *namespace* is determined using [this algorithm](#determining-a-use-rules-namespace). If the algorithm for determining a namespace fails for a `@use` rule, that rule is invalid. If it returns `null`, that rule is called *global*. A namespace is used to identify the used -[module][]'s members within the current [source file][]. +[module]'s members within the current [source file]. ## Procedures @@ -108,7 +108,7 @@ This algorithm takes a `@use` rule `rule`, and returns either an identifier or To execute a `@use` rule `rule`: * If `rule` has a namespace that's the same as another `@use` rule's namespace - in [the current source file][], throw an error. + in [the current source file], throw an error. [the current source file]: ../spec.md#current-source-file @@ -123,7 +123,7 @@ To execute a `@use` rule `rule`: * Add a variable to `rule-config` with the same name as `argument`'s identifier and with `value` as its value. -* Let `module` be the result of [loading the module][] with `rule`'s URL string +* Let `module` be the result of [loading the module] with `rule`'s URL string and `rule-config`. [loading the module]: ../modules.md#loading-a-module diff --git a/spec/built-in-modules/color.md b/spec/built-in-modules/color.md index de715b04..4a11b7ac 100644 --- a/spec/built-in-modules/color.md +++ b/spec/built-in-modules/color.md @@ -142,7 +142,7 @@ This function is also available as a global function named `adjust-color()`. * If `$lightness` isn't null, set `lightness` to `lightness + $lightness` clamped between 0% and 100%. - * Return the result of calling [`hsl()`][] with `hue`, `saturation`, + * Return the result of calling [`hsl()`] with `hue`, `saturation`, `lightness`, and `alpha`. * Otherwise, if either `$hue`, `$whiteness`, or `$blackness` aren't null: @@ -189,7 +189,7 @@ alpha($color) This function is also available as a global function named `opacity()`. > There is also a global function named `alpha()`, but it supports an additional -> overload with different behavior that's defined with the [global functions][]. +> overload with different behavior that's defined with the [global functions]. > > [global functions]: ../functions.md#alpha @@ -297,7 +297,7 @@ This function is also available as a global function named `change-color()`. * Let `lightness` be the result of calling `lightness($color)` if `$lightness` is null, or `$lightness` otherwise. - * Return the result of calling [`hsl()`][] with `hue`, `saturation`, + * Return the result of calling [`hsl()`] with `hue`, `saturation`, `lightness`, and `alpha`. * Otherwise, if either `$hue`, `$whiteness`, or `$blackness` aren't null: @@ -430,12 +430,12 @@ This function is also available as a global function named `hue()`. * Set `blackness` to `blackness / (whiteness + blackness)`. * Let `red`, `green`, and `blue` be the result of converting `hue`, - `whiteness`, and `blackness` [to RGB][]. + `whiteness`, and `blackness` [to RGB]. * Set `red`, `green`, and `blue` to their existing values multiplied by 255 and rounded to the nearest integers. - * Let `alpha` be the result of [percent-converting][] `$alpha` with a `max` of 1. + * Let `alpha` be the result of [percent-converting] `$alpha` with a `max` of 1. * Return a color with the given `red`, `green`, `blue`, and `alpha` channels. @@ -670,7 +670,7 @@ This function is also available as a global function named `scale-color()`. * Let `alpha` be `$color`'s alpha channel. -* If `$alpha` isn't null, set `alpha` to the result of [scaling][] `alpha` by +* If `$alpha` isn't null, set `alpha` to the result of [scaling] `alpha` by `$alpha` with `max` 1. [scaling]: #scaling-a-number @@ -682,13 +682,13 @@ This function is also available as a global function named `scale-color()`. * Let `red`, `green`, and `blue` be `$color`'s red, green, and blue channels. - * If `$red` isn't null, set `red` to the result of [scaling][] `red` by `$red` + * If `$red` isn't null, set `red` to the result of [scaling] `red` by `$red` with `max` 255. - * If `$green` isn't null, set `green` to the result of [scaling][] `green` by + * If `$green` isn't null, set `green` to the result of [scaling] `green` by `$green` with `max` 255. - * If `$blue` isn't null, set `blue` to the result of [scaling][] `blue` by `$blue` + * If `$blue` isn't null, set `blue` to the result of [scaling] `blue` by `$blue` with `max` 255. * Return a color with `red`, `green`, `blue`, and `alpha` as the red, green, @@ -701,13 +701,13 @@ This function is also available as a global function named `scale-color()`. * Let `hue`, `saturation`, and `lightness` be the result of calling `hue($color)`, `saturation($color)`, and `lightness($color)` respectively. - * If `$saturation` isn't null, set `saturation` to the result of [scaling][] + * If `$saturation` isn't null, set `saturation` to the result of [scaling] `saturation` by `$saturation` with `max` `100%`. - * If `$lightness` isn't null, set `lightness` to the result of [scaling][] + * If `$lightness` isn't null, set `lightness` to the result of [scaling] `lightness` by `$lightness` with `max` `100%`. - * Return the result of calling [`hsl()`][] with `hue`, `saturation`, + * Return the result of calling [`hsl()`] with `hue`, `saturation`, `lightness`, and `alpha`. * Otherwise, if either `$hue`, `$whiteness`, or `$blackness` aren't null: @@ -715,10 +715,10 @@ This function is also available as a global function named `scale-color()`. * Let `hue`, `whiteness`, and `blackness` be the result of calling `hue($color)`, `whiteness($color)`, and `blackness($color)` respectively. - * If `$whiteness` isn't null, set `whiteness` to the result of [scaling][] + * If `$whiteness` isn't null, set `whiteness` to the result of [scaling] `whiteness` by `$whiteness` with `max` `100%`. - * If `$blackness` isn't null, set `blackness` to the result of [scaling][] + * If `$blackness` isn't null, set `blackness` to the result of [scaling] `blackness` by `$blackness` with `max` `100%`. * Return the result of calling `hwb()` with `hue`, `whiteness`, `blackness`, diff --git a/spec/built-in-modules/meta.md b/spec/built-in-modules/meta.md index 4b488b6d..76adc0ea 100644 --- a/spec/built-in-modules/meta.md +++ b/spec/built-in-modules/meta.md @@ -114,18 +114,18 @@ This function is also available as a global function named `function-exists()`. * If `$module` is null: - * Return whether [resolving a function][] named `$name` returns null. + * Return whether [resolving a function] named `$name` returns null. [resolving a function]: ../modules.md#resolving-a-member * Otherwise, if `$module` isn't a string, throw an error. -* Otherwise, let `use` be the `@use` rule in [the current source file][] whose +* Otherwise, let `use` be the `@use` rule in [the current source file] whose namespace is equal to `$module`. If no such rule exists, throw an error. [the current source file]: ../spec.md#current-source-file -* Return whether [`use`'s module][] contains a function named `$name`. +* Return whether [`use`'s module] contains a function named `$name`. [`use`'s module]: ../at-rules/use.md#a-use-rules-module @@ -145,7 +145,7 @@ This function is also available as a global function named `get-function()`. * If `$css` is falsey: - * Return the result of [resolving a function][] named `$name`. If this + * Return the result of [resolving a function] named `$name`. If this returns null, throw an error. * Otherwise, return a function object that takes arguments `($args...)`. When @@ -162,10 +162,10 @@ This function is also available as a global function named `get-function()`. * If `$css` is truthy, throw an error. - * Let `use` be the `@use` rule in [the current source file][] whose + * Let `use` be the `@use` rule in [the current source file] whose namespace is equal to `$module`. If no such rule exists, throw an error. - * Return [`use`'s module][]'s function named `$name`, or throw an error if no + * Return [`use`'s module]'s function named `$name`, or throw an error if no such function exists. ### `get-mixin()` @@ -211,19 +211,19 @@ This function is also available as a global function named `global-variable-exis * If `$module` is null: - * Return whether [resolving a variable][] named `$name`, ignoring local + * Return whether [resolving a variable] named `$name`, ignoring local scopes, returns null. [resolving a variable]: ../modules.md#resolving-a-member * Otherwise, if `$module` isn't a string, throw an error. -* Otherwise, let `use` be the `@use` rule in the [current source file][] whose +* Otherwise, let `use` be the `@use` rule in the [current source file] whose namespace is equal to `$module`. If no such rule exists, throw an error. [current source file]: ../spec.md#current-source-file -* Return whether [`use`'s module][] contains a function named `$name`. +* Return whether [`use`'s module] contains a function named `$name`. ### `inspect()` @@ -274,10 +274,10 @@ This function is also available as a global function named `module-functions()`. * If `$module` is not a string, throw an error. -* Let `use` be the `@use` rule in [the current source file][] whose namespace is +* Let `use` be the `@use` rule in [the current source file] whose namespace is equal to `$module`. If no such rule exists, throw an error. -* Return a map whose keys are the names of functions in [`use`'s module][] and +* Return a map whose keys are the names of functions in [`use`'s module] and whose values are the corresponding functions. ### `module-mixins()` @@ -306,11 +306,11 @@ This function is also available as a global function named `module-variables()`. * If `$module` is not a string, throw an error. -* Let `use` be the `@use` rule in [the current source file][] whose namespace is +* Let `use` be the `@use` rule in [the current source file] whose namespace is equal to `$module`. If no such rule exists, throw an error. * Return a map whose keys are the names (without `$`) of variables in [`use`'s - module][] and whose values are the corresponding values. + module] and whose values are the corresponding values. ### `type-of()` @@ -351,14 +351,14 @@ This function is also available as a global function named `variable-exists()`. * If `$module` is null: - * Return whether [resolving a variable][] named `$name` returns null. + * Return whether [resolving a variable] named `$name` returns null. * Otherwise, if `$module` isn't a string, throw an error. -* Otherwise, let `use` be the `@use` rule in [the current source file][] whose +* Otherwise, let `use` be the `@use` rule in [the current source file] whose namespace is equal to `$module`. If no such rule exists, throw an error. -* Return whether [`use`'s module][] contains a mixin named `$name`. +* Return whether [`use`'s module] contains a mixin named `$name`. ## Mixins @@ -391,11 +391,11 @@ load-css($url, $with: null) * Let `config` be a configuration whose variable names and values are given by `$with` if `$with` isn't null, or the empty configuration otherwise. -* Let `module` be the result of [loading][] `$url` with `config`. +* Let `module` be the result of [loading] `$url` with `config`. [loading]: ../modules.md#loading-a-module -* Let `css` be the result of [resolving `module`'s extensions][]. +* Let `css` be the result of [resolving `module`'s extensions]. [resolving `module`'s extensions]: ../at-rules/extend.md#resolving-a-modules-extensions diff --git a/spec/declarations.md b/spec/declarations.md index 17e66bc3..23220b45 100644 --- a/spec/declarations.md +++ b/spec/declarations.md @@ -75,5 +75,16 @@ To execute a declaration `declaration`: * Let `css` be a CSS declaration with name `name` and value `value`. * Append `css` to `parent`. + + * If `parent` isn't the last statement in its parent: + + * Let `copy` by a copy of `parent` without any children. + + * Append `copy` to `parent`'s parent. + + * Set the [current style rule], [keyframe block], or at-rule (according to + `copy`'s type) to `copy`, for the remaining duration of its previous value. + + * Set `parent` to `copy`. * Evaluate each child in `declaration`'s `Statements` if it exists. diff --git a/spec/deprecations.yaml b/spec/deprecations.yaml index 45192f98..d749e51d 100644 --- a/spec/deprecations.yaml +++ b/spec/deprecations.yaml @@ -106,17 +106,23 @@ css-function-mixin: status: active deprecated: 1.76.0 +mixed-decls: + description: Declarations after or between nested rules. + dart-sass: + status: active + deprecated: 1.77.7 + color-4-api: description: Certain uses of built-in sass:color functions. dart-sass: status: active - deprecated: 1.78.0 + deprecated: 1.79.0 color-functions: description: Using global color functions instead of sass:color. dart-sass: status: active - deprecated: 1.78.0 + deprecated: 1.79.0 import: description: "@import rules." diff --git a/spec/embedded-protocol.md b/spec/embedded-protocol.md index db6ad521..ad10c027 100644 --- a/spec/embedded-protocol.md +++ b/spec/embedded-protocol.md @@ -43,8 +43,8 @@ to CSS. The other, the *host*, is responsible for telling the compiler what to compile and for providing implementations of custom importers and functions. Messages are sent between the host and the compiler in the form of [protocol -buffers][], using a custom RPC system [defined below][]. The messages and -services that comprise this protocol are defined in [the `.proto` file][] +buffers], using a custom RPC system [defined below]. The messages and +services that comprise this protocol are defined in [the `.proto` file] included in this repository. Most messages are *requests* which require the other endpoint to produce a *response*, but some are *events* which require no response. @@ -92,7 +92,7 @@ For a length-delimited stream, each packet has the following structure: ### Type Definitions All RPCs are wrapped in an outer message that indicates the RPC's type using [a -oneof field][]. There are two wrapper messages: +oneof field]. There are two wrapper messages: [a oneof field]: https://developers.google.com/protocol-buffers/docs/proto3#oneof @@ -143,6 +143,8 @@ since they're not specific to any individual compilation. The compilation ID and normal request `id` `4294967295` is reserved for [error handling]. (This is the maximum number representable by a `uint32`.) +[error handling]: #error-handling + ### Optional and Mandatory Fields If a field is not optional, the the endpoint that sends that message must @@ -191,7 +193,7 @@ functions can be written in the host language. In order to ensure that custom functions will behave consistently with built-in Sass functions, the host language should provide APIs that meet the following guidelines. -The [Dart `Value` API][] is a good example of an object-oriented API that +The [Dart `Value` API] is a good example of an object-oriented API that follows these guidelines. [Dart `Value` API]: https://pub.dartlang.org/documentation/sass/latest/sass/Value-class.html @@ -211,7 +213,7 @@ or a number's units) should match that of the original object. SassScript values use index 1 to refer to the first element and -1 to refer to the final element. The index 0 is invalid. Furthermore, indexes in Sass strings -refer to [Unicode code points][], not bytes or UTF-16 code units. The API should +refer to [Unicode code points], not bytes or UTF-16 code units. The API should provide a means to convert between Sass's indexing scheme and the host language's indexing scheme, and should encourage authors to treat any indexes they're passed as Sass-style indexes rather than host-language-style indexes. @@ -238,7 +240,7 @@ is quoted or not. The API should provide additional assertions for numbers: * that the number doesn't have any units; -* that the number's units are [compatible][] with given expected units; +* that the number's units are [compatible] with given expected units; * that the number is an integer, which for the purposes of Sass numbers means that its numeric value is within 1e-11 of an integer; * that the number is in a given range, where being within 1e-11 of the top or @@ -250,7 +252,7 @@ The API should also provide means of converting a number to the equivalent number with different-but-compatible units, and for returning it as the host language's integer type if it is an integer. -Two numbers are equal if they have [compatible][] units, and if their numerical +Two numbers are equal if they have [compatible] units, and if their numerical value (with normalized units) are within 1e-11 of one another. A hash code with the same equality semantics can be generated for a number `x` by rounding `x * 1e11` to the nearest integer and taking the hash code of the result. diff --git a/spec/embedded_sass.proto b/spec/embedded_sass.proto index cb034b98..0f787240 100644 --- a/spec/embedded_sass.proto +++ b/spec/embedded_sass.proto @@ -159,7 +159,7 @@ message InboundMessage { // Whether to silently suppresses all `LogEvent`s. bool silent = 14; - // Deprecation IDs to treat as fatal. + // Deprecation IDs or versions to treat as fatal. repeated string fatal_deprecation = 15; // Deprecation IDs to ignore. diff --git a/spec/functions.md b/spec/functions.md index d2b21fe2..79bace6f 100644 --- a/spec/functions.md +++ b/spec/functions.md @@ -69,7 +69,7 @@ matching is case-insensitive. [`SpecialFunctionName`]: syntax.md#specialfunctionexpression
-**FunctionCall** ::= [NamespacedIdentifier][] ArgumentInvocation
+**FunctionCall** ::= [NamespacedIdentifier] ArgumentInvocation
 
No whitespace is allowed between the `NamespacedIdentifier` and the @@ -99,7 +99,7 @@ To evaluate a `FunctionCall` `call`: * Let `name` be `call`'s `NamespacedIdentifier`. -* Let `function` be the result of [resolving a function][] named `name`. +* Let `function` be the result of [resolving a function] named `name`. * If `function` is null and `name` is not a plain `Identifier`, throw an error. @@ -145,7 +145,7 @@ To evaluate a `FunctionCall` `call`: ## Global Functions -> While most built-in Sass functions are defined in [built-in modules][], a few +> While most built-in Sass functions are defined in [built-in modules], a few > are globally available with no `@use` necessary. These are mostly functions > that expand upon the behavior of plain CSS functions. > @@ -192,7 +192,7 @@ adjust-hue($color, $degrees) ``` > This overload exists to support Microsoft's proprietary [`alpha()` - > function][]. + > function]. [`alpha()` function]: https://blogs.msdn.microsoft.com/ie/2010/08/17/ie9-opacity-and-alpha/ @@ -223,7 +223,7 @@ plain CSS function named `"rgb"` that function is named `"rgba"` instead. * If any of `$red`, `$green`, `$blue`, or `$alpha` aren't numbers, throw an error. - * Let `red`, `green`, and `blue` be the result of [percent-converting][] + * Let `red`, `green`, and `blue` be the result of [percent-converting] `$red`, `$green`, and `$blue`, respectively, with a `max` of 255. * Let `alpha` be the result of percent-converting `$alpha` with a `max` of 1. @@ -246,7 +246,7 @@ plain CSS function named `"rgb"` that function is named `"rgba"` instead. rgb($color, $alpha) ``` - * If either argument is a [special variable string][], return a plain CSS + * If either argument is a [special variable string], return a plain CSS function string with the name `"rgb"` and the same arguments. * If `$color` isn't a color, throw an error. @@ -259,7 +259,7 @@ plain CSS function named `"rgb"` that function is named `"rgba"` instead. rgb($channels) ``` - * If `$channels` is a [special variable string][], return a plain CSS function + * If `$channels` is a [special variable string], return a plain CSS function string with the name `"rgb"` and the argument `$channels`. * If `$channels` is an unbracketed slash-separated list: @@ -280,7 +280,7 @@ plain CSS function named `"rgb"` that function is named `"rgba"` instead. * If `rgb` has fewer than three elements: - * If any element of `rgb` is a [special variable string][], return a + * If any element of `rgb` is a [special variable string], return a plain CSS function string with the name `"rgb"` and the argument `$channels`. @@ -302,7 +302,7 @@ plain CSS function named `"rgb"` that function is named `"rgba"` instead. * If `$channels` has fewer than three elements: - * If any element of `$channels` is a [special variable string][], return a + * If any element of `$channels` is a [special variable string], return a plain CSS function string with the name `"rgb"` and the argument `$channels`. @@ -358,12 +358,12 @@ plain CSS function named `"hsl"` that function is named `"hsla"` instead. `$lightness`, respectively, between `0%` and `100%` and dividing by `100%`. * Let `red`, `green`, and `blue` be the result of converting `hue`, - `saturation`, and `lightness` [to RGB][]. + `saturation`, and `lightness` [to RGB]. * Set `red`, `green`, and `blue` to their existing values multiplied by 255 and rounded to the nearest integers. - * Let `alpha` be the result of [percent-converting][] `$alpha` with a `max` of 1. + * Let `alpha` be the result of [percent-converting] `$alpha` with a `max` of 1. * Return a color with the given `red`, `green`, `blue`, and `alpha` channels. @@ -385,7 +385,7 @@ plain CSS function named `"hsl"` that function is named `"hsla"` instead. hsl($hue, $saturation) ``` - * If either argument is a [special variable string][], return a plain CSS + * If either argument is a [special variable string], return a plain CSS function string with the name `"hsl"` and the same arguments. * Otherwise, throw an error. @@ -394,7 +394,7 @@ plain CSS function named `"hsl"` that function is named `"hsla"` instead. hsl($channels) ``` - * If `$channels` is a [special variable string][], return a plain CSS function + * If `$channels` is a [special variable string], return a plain CSS function string with the name `"hsl"` and the argument `$channels`. * If `$channels` is an unbracketed slash-separated list: @@ -415,7 +415,7 @@ plain CSS function named `"hsl"` that function is named `"hsla"` instead. * If `hsl` has fewer than three elements: - * If any element of `hsl` is a [special variable string][], return a + * If any element of `hsl` is a [special variable string], return a plain CSS function string with the name `"hsl"` and the argument `$channels`. @@ -437,7 +437,7 @@ plain CSS function named `"hsl"` that function is named `"hsla"` instead. * If `$channels` has fewer than three elements: - * If any element of `$channels` is a [special variable string][], return a + * If any element of `$channels` is a [special variable string], return a plain CSS function string with the name `"hsl"` and the argument `$channels`. diff --git a/spec/js-api/deprecations.d.ts.md b/spec/js-api/deprecations.d.ts.md index 019f8ab7..67680fd5 100644 --- a/spec/js-api/deprecations.d.ts.md +++ b/spec/js-api/deprecations.d.ts.md @@ -29,7 +29,7 @@ ### `Deprecations` - + ```ts export interface Deprecations { 'call-string': Deprecation<'call-string'>; @@ -47,6 +47,7 @@ export interface Deprecations { 'abs-percent': Deprecation<'abs-percent'>; 'fs-importer-cwd': Deprecation<'fs-importer-cwd'>; 'css-function-mixin': Deprecation<'css-function-mixin'>; + 'mixed-decls': Deprecation<'mixed-decls'>; 'color-4-api': Deprecation<'color-4-api'>; 'color-functions': Deprecation<'color-functions'>; import: Deprecation<'import'>; diff --git a/spec/js-api/index.d.ts.md b/spec/js-api/index.d.ts.md index 22b14ccb..8d31aaa4 100644 --- a/spec/js-api/index.d.ts.md +++ b/spec/js-api/index.d.ts.md @@ -66,7 +66,7 @@ export { ImporterResult, NodePackageImporter, } from './importer'; -export {Logger, SourceSpan, SourceLocation} from './logger'; +export {Logger, LoggerWarnOptions, SourceSpan, SourceLocation} from './logger'; export { CustomFunction, Options, diff --git a/spec/js-api/logger/index.d.ts.md b/spec/js-api/logger/index.d.ts.md index 0b47b77e..1053cf1e 100644 --- a/spec/js-api/logger/index.d.ts.md +++ b/spec/js-api/logger/index.d.ts.md @@ -11,6 +11,7 @@ export {SourceSpan} from './source_span'; ## Table of Contents * [Types](#types) + * [`LoggerWarnOptions`](#loggerwarnoptions) * [`Logger`](#logger) * [`warn`](#warn) * [`debug`](#debug) @@ -20,6 +21,24 @@ export {SourceSpan} from './source_span'; ## Types +### `LoggerWarnOptions` + +The options passed to `Logger.warn`. These are split out for documentation +purposes. + +```ts +export type LoggerWarnOptions = ( + | { + deprecation: true; + deprecationType: Deprecation; + } + | {deprecation: false} +) & { + span?: SourceSpan; + stack?: string; +}; +``` + ### `Logger` An object that provides callbacks for handling messages from the compiler. @@ -67,16 +86,7 @@ If this field is defined, the compiler must not surface warnings in any way other than inkoving `warn`. ```ts -warn?( - message: string, - options: ( - | { - deprecation: true; - deprecationType: Deprecation; - } - | {deprecation: false} - ) & {span?: SourceSpan; stack?: string} -): void; +warn?(message: string, options: LoggerWarnOptions): void; ``` #### `debug` diff --git a/spec/js-api/value/calculation.d.ts.md b/spec/js-api/value/calculation.d.ts.md index 482d7c6b..9183e167 100644 --- a/spec/js-api/value/calculation.d.ts.md +++ b/spec/js-api/value/calculation.d.ts.md @@ -39,6 +39,8 @@ import {Value, SassNumber, SassString} from './index'; The type of values that can be arguments to a [`SassCalculation`]. +[`SassCalculation`]: #sasscalculation + ```ts export type CalculationValue = | SassNumber @@ -161,6 +163,8 @@ export type CalculationOperator = '+' | '-' | '*' | '/'; The JS API representation of a Sass [`CalculationOperation`]. +[`CalculationOperation`]: #calculationoperation + ```ts export class CalculationOperation implements ValueObject { ``` diff --git a/spec/js-api/value/index.d.ts.md b/spec/js-api/value/index.d.ts.md index d35f0cec..c1ffd694 100644 --- a/spec/js-api/value/index.d.ts.md +++ b/spec/js-api/value/index.d.ts.md @@ -296,6 +296,8 @@ Returns `this` interpreted as a map. * If `this` is a [`SassMap`], return `this`. + [`SassMap`]: map.d.ts.md + * Otherwise, if [`internal`] is an empty Sass list, return a `SassMap` with its `internal` set to an empty map. diff --git a/spec/js-api/value/string.d.ts.md b/spec/js-api/value/string.d.ts.md index 07c09c07..5624ef25 100644 --- a/spec/js-api/value/string.d.ts.md +++ b/spec/js-api/value/string.d.ts.md @@ -48,6 +48,8 @@ Creates a Sass string: * Set [`internal`] to a Sass string with contents set to `text` and quoted set to `quotes`. + [`internal`]: #internal + * Return `this`. ```ts diff --git a/spec/modules.md b/spec/modules.md index 38899436..ca98aae2 100644 --- a/spec/modules.md +++ b/spec/modules.md @@ -86,7 +86,7 @@ A *module* is a collection of various properties: > member names and signatures regardless of the context in which those modules > are loaded. -* A set of [extensions][]. +* A set of [extensions]. [extensions]: at-rules/extend.md#extension @@ -97,7 +97,7 @@ A *module* is a collection of various properties: > any plain CSS rules. * A list of references to other modules, known as the module's *dependencies*, - in the same order as their [`@use` rules][] and/or [`@forward` rules][] appear + in the same order as their [`@use` rules] and/or [`@forward` rules] appear in the module's source file. If a dependency is referred to from multiple rules, its order is determined by the first such rule. @@ -107,7 +107,7 @@ A *module* is a collection of various properties: [`@use` rules]: at-rules/use.md [`@forward` rules]: at-rules/forward.md -* An optional [source file][]. +* An optional [source file]. > Note that [built-in modules](#built-in-module) *do not* have source files > associated with them. @@ -117,7 +117,7 @@ A *module* is a collection of various properties: * An absolute URL, known as the module's *canonical URL*. If the module has a source file, this must be the same as the source file's canonical URL. -Once a user-defined module has been returned by [Executing a File][], it is +Once a user-defined module has been returned by [Executing a File], it is immutable except for its variable values. [Built-in modules](#built-in-module) are always immutable. @@ -126,8 +126,8 @@ are always immutable. ### Module Graph The set of [modules](#module) loaded in the course of processing a stylesheet -can be construed as a [directed acyclic graph][] where the vertices are modules -and the edges are [`@use` rules][] and/or [`@forward` rules][]. We call this the +can be construed as a [directed acyclic graph] where the vertices are modules +and the edges are [`@use` rules] and/or [`@forward` rules]. We call this the *module graph*. [directed acyclic graph]: https://en.wikipedia.org/wiki/Directed_acyclic_graph @@ -135,7 +135,7 @@ and the edges are [`@use` rules][] and/or [`@forward` rules][]. We call this the The module graph is not allowed to contain cycles because they make it impossible to guarantee that all dependencies of a module are available before that module is loaded. Although the names and APIs of a dependency's members can -be determined without [executing][] it, Sass allows code to be executed during +be determined without [executing] it, Sass allows code to be executed during load, so those members may not behave correctly when invoked before the dependency is executed. @@ -146,10 +146,10 @@ dependency is executed. An *import context* is a set of [members](#member) that contains at most one member of any given type and name. It's always mutable. -> Import contexts serve as glue between the old [`@import` rule][] and the +> Import contexts serve as glue between the old [`@import` rule] and the > module system. It serves as a shared global namespace for stylesheets loaded > using `@import` rules, while also preventing global names from leaking into or -> out of stylesheets loaded using [`@use` rules][] and/or [`@forward` rules][]. +> out of stylesheets loaded using [`@use` rules] and/or [`@forward` rules]. [`@import` rule]: at-rules/import.md @@ -158,7 +158,7 @@ member of any given type and name. It's always mutable. A *built-in module* is a module defined either by the Sass specification or by the host environment of the Sass compilation in some implementation-specific way. Modules defined by the Sass specification all have the scheme `sass:` and -are all described in [the `built-in-modules` directory][]. Modules defined +are all described in [the `built-in-modules` directory]. Modules defined outside the Sass compilation may not use the scheme `sass:`. [the `built-in-modules` directory]: built-in-modules @@ -329,8 +329,8 @@ The module system defines the following syntax for referring to names from other modules:
-**PublicIdentifier**     ::= [\][] that doesn't begin with '-' or '_'
-**NamespacedIdentifier** ::= [\][] | [\][] '.' PublicIdentifier
+**PublicIdentifier**     ::= [\] that doesn't begin with '-' or '_'
+**NamespacedIdentifier** ::= [\] | [\] '.' PublicIdentifier
 
[\]: https://drafts.csswg.org/css-syntax-3/#ident-token-diagram @@ -379,7 +379,7 @@ This algorithm takes a string `argument` and [configuration](#configuration) > This disallows circular `@use`s, which ensures that modules can't be used > until they're fully initialized. -* Otherwise, return the result of [executing][] `file` with `config` and a new +* Otherwise, return the result of [executing] `file` with `config` and a new [import context](#import-context). > For simplicity, the spec creates an import context for every module. @@ -538,11 +538,11 @@ and returns a member of type `type` or null. [current scope]: spec.md#scope * If `name` is a [`NamespacedIdentifier`](#syntax) of the form - `namespace.raw-name` or a [`Variable`][] of the form `namespace.$raw-name`: + `namespace.raw-name` or a [`Variable`] of the form `namespace.$raw-name`: [`Variable`]: variables.md#syntax - * Let `use` be the [`@use` rule][] in the [current source file][] whose + * Let `use` be the [`@use` rule] in the [current source file] whose namespace is `namespace`. If there isn't exactly one such rule, throw an error. @@ -551,7 +551,7 @@ and returns a member of type `type` or null. * If `use` hasn't been executed yet, throw an error. - * Otherwise, let `module` be [`use`'s module][]. + * Otherwise, let `module` be [`use`'s module]. * Return the member of `module` with type `type` and name `raw-name`. If there is no such member, throw an error. @@ -568,7 +568,7 @@ and returns a member of type `type` or null. > variable definition will set the module's variable value rather than > defining a new variable local to this module. - * If the [current import context][] contains a member `member` of type `type` + * If the [current import context] contains a member `member` of type `type` named `name`, return it. > This includes member definitions within the current module. @@ -581,8 +581,8 @@ and returns a member of type `type` or null. [current import context]: spec.md#current-import-context -* Let `members` be the set of [unique][] members of type `type` named `name` in - [modules of][] the global `@use` rules. +* Let `members` be the set of [unique] members of type `type` named `name` in + [modules of] the global `@use` rules. [unique]: #member [modules of]: at-rules/use.md#a-use-rules-module diff --git a/spec/spec.md b/spec/spec.md index b8d8b4f0..2db7df16 100644 --- a/spec/spec.md +++ b/spec/spec.md @@ -6,7 +6,7 @@ Sass is a *living specification*, which means that it's actively updated over time without having distinctions between numbered versions. Different implementations may support different subsets of the specification, although all implementations are expected to work towards full support. The *reference -implementation* (currently [Dart Sass][]) will generally support as close to the +implementation* (currently [Dart Sass]) will generally support as close to the full spec as possible. [Dart Sass]: https://sass-lang.com/dart-sass @@ -53,7 +53,7 @@ has no parent. ### Current Source File -The *current source file* is the [source file][] that was passed to the +The *current source file* is the [source file] that was passed to the innermost active invocation of [Executing a File](#executing-a-file). [source file]: syntax.md#source-file @@ -63,21 +63,21 @@ invocation of Executing a File. ### Current Configuration -The *current configuration* is the [configuration][] that was passed to the +The *current configuration* is the [configuration] that was passed to the innermost active invocation of [Executing a File](#executing-a-file). [configuration]: modules.md#configuration ### Current Import Context -The *current import context* is the [import context][] that was passed to the +The *current import context* is the [import context] that was passed to the innermost active invocation of [Executing a File](#executing-a-file). [import context]: modules.md#import-context ### Current Module -The *current module* is the [module][] that was created by the innermost active +The *current module* is the [module] that was created by the innermost active invocation of [Executing a File](#executing-a-file). [module]: modules.md#module @@ -179,12 +179,12 @@ It runs as follows: * If `url` is not a `file:` URL, set `importer` to be a function that always returns null. -* Let `file` be the [source file][] with `ast`, canonical URL `url`, and +* Let `file` be the [source file] with `ast`, canonical URL `url`, and importer `importer`. * Let `module` be the result of [executing](#executing-a-file) `file`. -* Let `css` be the result of [resolving `module`'s extensions][]. +* Let `css` be the result of [resolving `module`'s extensions]. [resolving `module`'s extensions]: at-rules/extend.md#resolving-a-modules-extensions @@ -196,8 +196,8 @@ It runs as follows: ### Executing a File -This algorithm takes a [source file][] `file`, a [configuration][] `config`, an -[import context][] `import`, and returns a [module][]. +This algorithm takes a [source file] `file`, a [configuration] `config`, an +[import context] `import`, and returns a [module]. * Let `module` be an empty module with source file `file`. @@ -216,7 +216,7 @@ This algorithm takes a [source file][] `file`, a [configuration][] `config`, an yet in `module`, set `variable` to `null` in `module`. > This isn't necessary for implementations that follow the most recent - > [variables spec][] and don't allow `!global` assignments to variables + > [variables spec] and don't allow `!global` assignments to variables > that don't yet exist. However, at time of writing, all existing > implementations are in the process of deprecating the old `!global` > behavior, which allowed `!global` declarations to create new diff --git a/spec/style-rules.md b/spec/style-rules.md index 817e8553..4c9f8f32 100644 --- a/spec/style-rules.md +++ b/spec/style-rules.md @@ -13,12 +13,15 @@ The *current style rule* is the CSS style rule that was created by the innermost [execution of a style rule](#semantics), `@media` rule, `@supports` rule, or -unknown at-rule. +unknown at-rule. This may be overridden by the [execution of a declaration]. + +[execution of a declaration]: declarations.md#semantics ### Current Keyframe Block The *current keyframe block* is the CSS keyframe block that was created by the -innermost [execution of a style rule](#semantics). +innermost [execution of a style rule](#semantics). This may be overridden by the +[execution of a declaration]. ## Semantics diff --git a/spec/syntax.md b/spec/syntax.md index 65778dc4..94c91484 100644 --- a/spec/syntax.md +++ b/spec/syntax.md @@ -60,7 +60,7 @@ representation of the intermediate production. ### `InterpolatedIdentifier`
-**InterpolatedIdentifier** ::= ([\][] | '-'? Interpolation) ([Name][] | Interpolation)*
+**InterpolatedIdentifier** ::= ([\] | '-'? Interpolation) ([Name] | Interpolation)*
 
[\]: https://drafts.csswg.org/css-syntax-3/#ident-token-diagram @@ -72,7 +72,7 @@ No whitespace is allowed between components of an `InterpolatedIdentifier`.
 **InterpolatedUrl**         ::= 'url(' (QuotedString | InterpolatedUnquotedUrlContents) ')'
-**InterpolatedUnquotedUrlContents** ::= ([unescaped url contents][] | [escape][] | Interpolation)*
+**InterpolatedUnquotedUrlContents** ::= ([unescaped url contents] | [escape] | Interpolation)*
 
[unescaped url contents]: https://www.w3.org/TR/css-syntax-3/#url-token-diagram @@ -82,7 +82,7 @@ No whitespace is allowed between components of an `InterpolatedUnquotedUrlConten ### `Name`
-**Name** ::= ([identifier code point][] | [escape][])+
+**Name** ::= ([identifier code point] | [escape])+
 
[identifier code point]: https://drafts.csswg.org/css-syntax-3/#identifier-code-point @@ -112,7 +112,7 @@ No whitespace is allowed between components of an `InterpolatedUnquotedUrlConten **PseudoSelector** ::= NormalPseudoSelector | SelectorPseudo | NthSelectorPseudo -**NormalPseudoSelector** ::= ':' ':'? VendorPrefix? [\][] +**NormalPseudoSelector** ::= ':' ':'? VendorPrefix? [\] ('(' [\] ')')? **SelectorPseudo** ::= SelectorPseudoName '(' Selector ')' **NthSelectorPseudo** ::= NthSelectorPseudoName '(' [\] 'of'¹ Selector ')' @@ -275,6 +275,8 @@ SCSS: adjacent `/`s in a [`SlashListExpression`] may have no whitespace between them, so `//` is parsed as two slash separators in a slash-separated list. + [`SlashListExpression`]: types/list.md#slashlistexpression + * A `ParentSelector` may appear anywhere in a `CompoundSelector`, rather than just as the first `SimpleSelector`. @@ -282,12 +284,12 @@ SCSS: ### Consuming an Identifier -This algorithm consumes input from a stream of [code points][] and returns a +This algorithm consumes input from a stream of [code points] and returns a string. [code points]: https://infra.spec.whatwg.org/#code-point -This production has the same grammar as [``][]. +This production has the same grammar as [``]. [``]: https://drafts.csswg.org/css-syntax-3/#ident-token-diagram @@ -299,10 +301,10 @@ This production has the same grammar as [``][]. * If the stream starts with `-`, consume it and append it to `string`. - * If the stream starts with `\`, [consume an escaped code point][] with the + * If the stream starts with `\`, [consume an escaped code point] with the `start` flag set and append it to `string`. - * Otherwise, if the stream starts with an [identifier-start code point][], + * Otherwise, if the stream starts with an [identifier-start code point], consume it and append it to `string`. * Otherwise, throw an error. @@ -316,9 +318,9 @@ This production has the same grammar as [``][]. ### Consuming an Interpolated Identifier -This algorithm consumes input from a stream of [code points][] and returns a +This algorithm consumes input from a stream of [code points] and returns a sequence of strings and/or expressions. It follows the grammar for an -[`InterpolatedIdentifier`][]. +[`InterpolatedIdentifier`]. [`InterpolatedIdentifier`]: #interpolatedidentifier @@ -333,7 +335,7 @@ sequence of strings and/or expressions. It follows the grammar for an * Otherwise, [consume an identifier](#consuming-an-identifier) and add its string to `components`. -* While the input starts with `#{`, a [identifier code point][], or `\`: +* While the input starts with `#{`, a [identifier code point], or `\`: * If the input starts with `#{`, consume an interpolation and add its expression to `components`. @@ -345,50 +347,50 @@ sequence of strings and/or expressions. It follows the grammar for an ### Consuming a Name -This algorithm consumes input from a stream of [code points][] and returns a +This algorithm consumes input from a stream of [code points] and returns a string. The grammar for this production is:
-**Name** ::= ([identifier code point][] | [escape][])+
+**Name** ::= ([identifier code point] | [escape])+
 
* Let `string` be an empty string. -* While the input starts with a [identifier code point][] or `\`: +* While the input starts with a [identifier code point] or `\`: - * If the input starts with a [identifier code point][], consume it and append + * If the input starts with a [identifier code point], consume it and append it to `string`. - * Otherwise, [consume an escaped code point][] and append it to `string`. + * Otherwise, [consume an escaped code point] and append it to `string`. * Return `string`. ### Consuming an Escaped Code Point -This algorithm consumes input from a stream of [code points][]. It takes an +This algorithm consumes input from a stream of [code points]. It takes an optional boolean flag, `start`, which indicates whether it's at the beginning of an identifier and defaults to false. It returns a string. This production has the same grammar as [`escape`][escape] in CSS Syntax Level 3. -* If the stream doesn't [start with a valid escape][], throw an error. +* If the stream doesn't [start with a valid escape], throw an error. [start with a valid escape]: https://drafts.csswg.org/css-syntax-3/#starts-with-a-valid-escape -* Let `codepoint` be the result of [consuming an escaped code point][]. +* Let `codepoint` be the result of [consuming an escaped code point]. [consuming an escaped code point]: https://drafts.csswg.org/css-syntax-3/#consume-escaped-code-point * Let `character` be the string containing only `codepoint`. -* If `codepoint` is a [identifier-start code point][], return `character`. +* If `codepoint` is a [identifier-start code point], return `character`. -* Otherwise, if `codepoint` is an [identifier code point][] and the `start` flag +* Otherwise, if `codepoint` is an [identifier code point] and the `start` flag is not set, return `character`. -* Otherwise, if `codepoint` is a [non-printable code point][], U+0009 CHARACTER +* Otherwise, if `codepoint` is a [non-printable code point], U+0009 CHARACTER TABULATION, U+000A LINE FEED, U+000D CARRIAGE RETURN, or U+000C FORM FEED; - *or* if `codepoint` is a [digit][] and the `start` flag is set: + *or* if `codepoint` is a [digit] and the `start` flag is set: [non-printable code point]: https://drafts.csswg.org/css-syntax-3/#non-printable-code-point diff --git a/spec/types/calculation.md b/spec/types/calculation.md index 49a49e90..5ff3bd2a 100644 --- a/spec/types/calculation.md +++ b/spec/types/calculation.md @@ -150,6 +150,8 @@ To serialize a `Number` within a `CalculationExpression`: This algorithm takes a [`FunctionCall`] `call` whose name is a plain identifier and returns a number or a calculation. +[`FunctionCall`]: ../functions.md#functioncall + * If `call`'s `ArgumentInvocation` contains one or more `KeywordArgument`s or one or more `RestArgument`s, throw an error. @@ -226,6 +228,8 @@ This algorithm takes an expression `expression` and returns a * If `expression` isn't [calculation-safe], throw an error. + [calculation-safe]: #calculation-safe-expression + * Otherwise, evaluate `expression` using the semantics defined in the [Semantics] section if available, or the standard semantics otherwise. @@ -416,7 +420,9 @@ This algorithm takes a calculation `calc` and returns a number or a calculation. * If `strategy`'s value is `"to-zero"`, return whichever of `upper` and `lower` has the smallest absolute difference from 0. + [exactly equal]: number.md#exact-equality [special variable string]: ../functions.md#special-variable-string + [matching units]: number.md#matching-two-numbers-units * If `calc`'s name is `"clamp"`: diff --git a/spec/types/list.md b/spec/types/list.md index 4d5aaa27..f266bfe3 100644 --- a/spec/types/list.md +++ b/spec/types/list.md @@ -51,7 +51,7 @@ absolute value is larger than the length of that list. ## Syntax
-**BracketedListExpression** ::= '[' ContainedListExpression ']'
+**BracketedListExpression** ::= '\[' ContainedListExpression ']'
 **ContainedListExpression** ::= CommaListExpression ','?
 **CommaListExpression**     ::= SlashListExpression (',' SlashListExpression)*
 **SlashListExpression**     ::= SpaceListExpression (('/' SpaceListExpression?)* '/' SpaceListExpression)?
diff --git a/spec/variables.md b/spec/variables.md
index c6801eff..2f1e47a4 100644
--- a/spec/variables.md
+++ b/spec/variables.md
@@ -9,10 +9,12 @@
 
 ## Syntax
 
+
+
 
 **Variable**            ::= PlainVariable | NamespacedVariable
-**PlainVariable**       ::= '$' [\][]
-**NamespacedVariable**  ::= [\][] '.$' [PublicIdentifier][]
+**PlainVariable**       ::= '\$' [\]
+**NamespacedVariable**  ::= [\] '.$' [PublicIdentifier]
 **VariableDeclaration** ::= Variable ':' Expression ('!global' | '!default')*
 
@@ -34,7 +36,7 @@ To execute a `VariableDeclaration` `declaration`: * Let `name` be `declaration`'s `Variable`. -* Let `resolved` be the result of [resolving a variable][] named `name`. +* Let `resolved` be the result of [resolving a variable] named `name`. [resolving a variable]: modules.md#resolving-a-member @@ -103,7 +105,7 @@ To execute a `VariableDeclaration` `declaration`: To evaluate a `Variable` `variable`: -* Let `definition` be the result of [resolving a variable][] named `variable`. +* Let `definition` be the result of [resolving a variable] named `variable`. If this returns null, throw an error. * Return `definition`'s value.