sass 1.87.0 → 1.88.0

package/types/deprecations.d.ts

@@ -6,7 +6,7 @@
  */
 export interface Deprecations {
   // START AUTOGENERATED LIST
-  // Checksum: 3639e60773866019c018ae16267c8f23e4df86cf
+  // Checksum: c57ab2eb07ab1df48581b8484ef9bdbad0ddceaa
 
   /**
    * Deprecation for passing a string directly to meta.call().
@@ -169,6 +169,13 @@ export interface Deprecations {
    */
   'type-function': Deprecation<'type-function'>;
 
+  /**
+   * Deprecation for passing a relative url to compileString().
+   *
+   * This deprecation became active in Dart Sass 1.88.0.
+   */
+  'compile-string-relative-url': Deprecation<'compile-string-relative-url'>;
+
   // END AUTOGENERATED LIST
 
   /**

package/types/importer.d.ts

@@ -226,12 +226,13 @@ export interface Importer<sync extends 'sync' | 'async' = 'sync' | 'async'> {
    * the same result. Calling {@link canonicalize} with a URL returned by a
    * previous call to {@link canonicalize} must return that URL.
    *
-   * Relative loads in stylesheets loaded from an importer are handled by
-   * resolving the loaded URL relative to the canonical URL of the stylesheet
-   * that contains it, and passing that URL back to the importer's {@link
-   * canonicalize} method. For example, suppose the "Resolving a Load" example
-   * {@link Importer | above} returned a stylesheet that contained `@use
-   * "mixins"`:
+   * #### Relative URLs
+   *
+   * Relative loads in stylesheets loaded from an importer are first resolved
+   * relative to the canonical URL of the stylesheet that contains it and passed
+   * back to the {@link canonicalize} method for the local importer that loaded
+   * that stylesheet. For example, suppose the "Resolving a Load" example {@link
+   * Importer | above} returned a stylesheet that contained `@use "mixins"`:
    *
    * - The compiler resolves the URL `mixins` relative to the current
    *   stylesheet's canonical URL `db:foo/bar/baz/_index.scss` to get
@@ -243,6 +244,11 @@ export interface Importer<sync extends 'sync' | 'async' = 'sync' | 'async'> {
    * called with a URL relative to one returned by an earlier call to {@link
    * canonicalize}.
    *
+   * If the local importer's `canonicalize` method returns `null`, the relative
+   * URL is then passed to each of {@link Options.importers}' `canonicalize()`
+   * methods in turn until one returns a canonical URL. If none of them do, the
+   * load fails.
+   *
    * @param url - The loaded URL. Since this might be relative, it's represented
    * as a string rather than a {@link URL} object.
    *

package/types/options.d.ts

@@ -231,8 +231,25 @@ export interface Options<sync extends 'sync' | 'async'> {
    *
    * Loads are resolved by trying, in order:
    *
-   * - The importer that was used to load the current stylesheet, with the
-   *   loaded URL resolved relative to the current stylesheet's canonical URL.
+   * - **For relative URLs only:** the URL resolved relative to the current
+   *   stylesheet's canonical URL, passed to the importer that loaded the current
+   *   stylesheet.
+   *
+   *   When calling {@link compileString} or {@link compileStringAsync}, the
+   *   entrypoint file isn't "loaded" in the same sense as other files. In that
+   *   case:
+   *
+   *   - {@link StringOptions.url} is the canonical URL and {@link
+   *     StringOptions.importer} is the importer that loaded it.
+   *
+   *   - If {@link StringOptions.importer} isn't passed and {@link
+   *     StringOptions.url} is a `file:` URL, the URL is loaded from the
+   *     filesystem by default. (You can disable this by passing `{canonicalize:
+   *     url => null}` as {@link StringOptions.importer}.)
+   *
+   *   - If {@link StringOptions.url} isn't passed but {@link
+   *     StringOptions.importer} is, the relative URL is passed to {@link
+   *     StringOptions.importer} as-is.
    *
    * - Each {@link Importer}, {@link FileImporter}, or
    *   {@link NodePackageImporter} in {@link importers}, in order.
@@ -390,8 +407,8 @@ export interface Options<sync extends 'sync' | 'async'> {
  *
  * If the {@link StringOptions.importer} field isn't passed, the entrypoint file
  * can load files relative to itself if a `file://` URL is passed to the {@link
- * url} field. If it is passed, the entrypoint file uses it to load files
- * relative to itself.
+ * url} field. If `importer` is passed, the entrypoint file uses that importer
+ * to load files relative to itself.
  *
  * @typeParam sync - This lets the TypeScript checker verify that asynchronous
  * {@link Importer}s, {@link FileImporter}s, and {@link CustomFunction}s aren't
@@ -411,13 +428,11 @@ export interface StringOptions<sync extends 'sync' | 'async'>
   syntax?: Syntax;
 
   /**
-   * The importer to use to handle loads that are relative to the entrypoint
-   * stylesheet.
+   * The importer to use to handle relative URL loads in the entrypoint
+   * stylesheet and stylesheets loaded relative to the entrypoint stylesheet.
    *
-   * A relative load's URL is first resolved relative to {@link url}, then
-   * passed to {@link importer}. (It's passed as-is if {@link url} isn't
-   * passed.) If the importer doesn't recognize it, it's then passed to {@link
-   * importers} and {@link loadPaths}.
+   * See {@link Options.importers} for details on how loads are resolved for the
+   * entrypoint stylesheet.
    *
    * @category Input
    */
@@ -426,10 +441,8 @@ export interface StringOptions<sync extends 'sync' | 'async'>
   /**
    * The canonical URL of the entrypoint stylesheet.
    *
-   * A relative load's URL is first resolved relative to {@link url}, then
-   * resolved to a file on disk if it's a `file://` URL. If it can't be resolved
-   * to a file on disk, it's then passed to {@link importers} and {@link
-   * loadPaths}.
+   * See {@link Options.importers} for details on how loads are resolved for the
+   * entrypoint stylesheet.
    *
    * @category Input
    * @compatibility feature: "Undefined URL with importer", dart: "1.75.0", node: false