Clarify that base importer resolution does not require a URL (#3832)

See sass/dart-sass#2208

Co-authored-by: Carlos (Goodwine) <2022649+Goodwine@users.noreply.github.com>

js-api-doc/importer.d.ts

@@ -42,7 +42,7 @@ export interface CanonicalizeContext {
  * Like all importers, this implements custom Sass loading logic for [`@use`
  * rules](https://sass-lang.com/documentation/at-rules/use) and [`@import`
  * rules](https://sass-lang.com/documentation/at-rules/import). It can be passed
- * to {@link Options.importers} or {@link StringOptionsWithImporter.importer}.
+ * to {@link Options.importers} or {@link StringOptions.importer}.
  *
  * @typeParam sync - A `FileImporter<'sync'>`'s {@link findFileUrl} must return
  * synchronously, but in return it can be passed to {@link compile} and {@link
@@ -122,7 +122,7 @@ export interface FileImporter<
  * An object that implements custom Sass loading logic for [`@use`
  * rules](https://sass-lang.com/documentation/at-rules/use) and [`@import`
  * rules](https://sass-lang.com/documentation/at-rules/import). It can be passed
- * to {@link Options.importers} or {@link StringOptionsWithImporter.importer}.
+ * to {@link Options.importers} or {@link StringOptions.importer}.
  *
  * Importers that simply redirect to files on disk are encouraged to use the
  * {@link FileImporter} interface instead.

js-api-doc/options.d.ts

@@ -292,10 +292,10 @@ export interface Options<sync extends 'sync' | 'async'> {
    * so that they can get fixed as soon as possible!
    *
    * **Heads up!** If {@link compileString} or {@link compileStringAsync} is
-   * called without {@link StringOptionsWithoutImporter.url}, <em>all</em>
+   * called without {@link StringOptions.url}, <em>all</em> stylesheets it loads
-   * stylesheets it loads will be considered dependencies. Since it doesn’t have
+   * will be considered dependencies. Since it doesn’t have a path of its own,
-   * a path of its own, everything it loads is coming from a load path rather
+   * everything it loads is coming from a load path rather than a relative
-   * than a relative import.
+   * import.
    *
    * @defaultValue `false`
    * @category Messages
@@ -388,9 +388,10 @@ export interface Options<sync extends 'sync' | 'async'> {
  * Options that can be passed to {@link compileString} or {@link
  * compileStringAsync}.
  *
- * If the {@link StringOptionsWithImporter.importer} field isn't passed, the
+ * If the {@link StringOptions.importer} field isn't passed, the entrypoint file
- * entrypoint file can load files relative to itself if a `file://` URL is
+ * can load files relative to itself if a `file://` URL is passed to the {@link
- * passed to the {@link url} field.
+ * url} field. If it is passed, the entrypoint file uses it 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
@@ -398,7 +399,7 @@ export interface Options<sync extends 'sync' | 'async'> {
  *
  * @category Options
  */
-export interface StringOptionsWithoutImporter<sync extends 'sync' | 'async'>
+export interface StringOptions<sync extends 'sync' | 'async'>
   extends Options<sync> {
   /**
    * The {@link Syntax} to use to parse the entrypoint stylesheet.
@@ -409,6 +410,19 @@ export interface StringOptionsWithoutImporter<sync extends 'sync' | 'async'>
    */
   syntax?: Syntax;
 
+  /**
+   * The importer to use to handle loads that are 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}.
+   *
+   * @category Input
+   */
+  importer?: Importer<sync> | FileImporter<sync>;
+
   /**
    * The canonical URL of the entrypoint stylesheet.
    *
@@ -418,62 +432,24 @@ export interface StringOptionsWithoutImporter<sync extends 'sync' | 'async'>
    * loadPaths}.
    *
    * @category Input
+   * @compatibility feature: "Undefined URL with importer", dart: "1.75.0", node: false
+   *
+   * Earlier versions of Dart Sass required {@link url} to be defined when
+   * passing {@link StringOptions.importer}.
    */
   url?: URL;
 }
 
 /**
- * Options that can be passed to {@link compileString} or {@link
- * compileStringAsync}.
- *
- * If the {@link StringOptionsWithImporter.importer} field is passed, the
- * entrypoint file uses it to load files relative to itself and the {@link url}
- * field is mandatory.
- *
- * @typeParam sync - This lets the TypeScript checker verify that asynchronous
- * {@link Importer}s, {@link FileImporter}s, and {@link CustomFunction}s aren't
- * passed to {@link compile} or {@link compileString}.
- *
  * @category Options
+ * @deprecated Use {@link StringOptions} instead.
  */
-export interface StringOptionsWithImporter<sync extends 'sync' | 'async'>
+type StringOptionsWithoutImporter<sync extends 'sync' | 'async'> =
-  extends StringOptionsWithoutImporter<sync> {
+  StringOptions<sync>;
-  /**
-   * The importer to use to handle loads that are relative to the entrypoint
-   * stylesheet.
-   *
-   * A relative load's URL is first resolved relative to {@link url}, then
-   * passed to {@link importer}. If the importer doesn't recognize it, it's then
-   * passed to {@link importers} and {@link loadPaths}.
-   *
-   * @category Input
-   */
-  importer: Importer<sync> | FileImporter<sync>;
-
-  /**
-   * The canonical URL of the entrypoint stylesheet. If this is passed along
-   * with {@link importer}, it's used to resolve relative loads in the
-   * entrypoint stylesheet.
-   *
-   * @category Input
-   */
-  url: URL;
-}
 
 /**
- * Options that can be passed to {@link compileString} or {@link
- * compileStringAsync}.
- *
- * This is a {@link StringOptionsWithImporter} if it has a {@link
- * StringOptionsWithImporter.importer} field, and a {@link
- * StringOptionsWithoutImporter} otherwise.
- *
- * @typeParam sync - This lets the TypeScript checker verify that asynchronous
- * {@link Importer}s, {@link FileImporter}s, and {@link CustomFunction}s aren't
- * passed to {@link compile} or {@link compileString}.
- *
  * @category Options
+ * @deprecated Use {@link StringOptions} instead.
  */
-export type StringOptions<sync extends 'sync' | 'async'> =
+type StringOptionsWithImporter<sync extends 'sync' | 'async'> =
-  | StringOptionsWithImporter<sync>
+  StringOptions<sync>;
-  | StringOptionsWithoutImporter<sync>;

spec/js-api/options.d.ts.md

@@ -35,13 +35,12 @@ import {PromiseOr} from './util/promise_or';
   * [`sourceMapIncludeSources`](#sourcemapincludesources)
   * [`style`](#style)
   * [`verbose`](#verbose)
-* [`StringOptionsWithoutImporter`](#stringoptionswithoutimporter)
-  * [`syntax`](#syntax)
-  * [`url`](#url)
-* [`StringOptionsWithImporter`](#stringoptionswithimporter)
-  * [`importer`](#importer)
-  * [`url`](#url-1)
 * [`StringOptions`](#stringoptions)
+  * [`syntax`](#syntax)
+  * [`importer`](#importer)
+  * [`url`](#url)
+* [`StringOptionsWithoutImporter`](#stringoptionswithoutimporter)
+* [`StringOptionsWithImporter`](#stringoptionswithimporter)
 
 ## Types
 
@@ -338,17 +337,16 @@ verbose?: boolean;
 } // Options
 ```
 
-### `StringOptionsWithoutImporter`
+### `StringOptions`
 
 > This interface is used for calls to [`compileString()`] and
-> [`compileStringAsync()`] that don't pass the `importer` parameter, and so
+> [`compileStringAsync()`].
-> don't support relative imports.
 >
 > [`compileString()`]: compile.d.ts.md#compilestring
 > [`compileStringAsync()`]: compile.d.ts.md#compilestringasync
 
 ```ts
-export interface StringOptionsWithoutImporter<sync extends 'sync' | 'async'>
+export interface StringOptions<sync extends 'sync' | 'async'>
   extends Options<sync> {
 ```
 
@@ -360,61 +358,61 @@ The compiler must parse `source` using this syntax. Defaults to `'scss'`.
 syntax?: Syntax;
 ```
 
-#### `url`
-
-The URL of the stylesheet being parsed.
-
-> When `importer` isn't passed, this is purely advisory and only used for error
-> reporting.
-
-```ts
-url?: URL;
-```
-
-```ts
-} // StringOptionsWithoutImporter
-```
-
-### `StringOptionsWithImporter`
-
-> This interface is used for calls to [`compileString()`] and
-> [`compileStringAsync()`] that *do* pass the `importer` parameter, and so *do*
-> support relative imports.
-
-```ts
-export interface StringOptionsWithImporter<sync extends 'sync' | 'async'>
-  extends StringOptionsWithoutImporter<sync> {
-```
-
 #### `importer`
 
 The [importer] to use to resolve relative imports in the entrypoint.
 
 [importer]: importer.d.ts.md
 
+> Relative entrypoint imports are resolved differently depending on whether the
+> `url` parameter is also passed:
+>
+> * If `url` *is* passed, relative URLs are first resolved relative to that URL
+>   and then passed to `importer`. This is the same behavior that's used when
+>   resolving relative URLs in any other Sass file.
+>
+> * If `url` *is not* passed, relative URLs are passed directly to `importer`
+>   without being resolved. This is a bit of a hack that relies on the fact that
+>   some importers work like "load paths", resolving relative URLs based on some
+>   implicit base URL. It's useful for situations like evaluating a stylesheet
+>   passed via stdin and giving it access to relative loads in the working
+>   directory without *also* giving it a fake canonical URL that would show up
+>   in error messages and source maps.
+
 ```ts
-importer: Importer<sync> | FileImporter<sync>;
+importer?: Importer<sync> | FileImporter<sync>;
 ```
 
 #### `url`
 
-The canonical URL of the entrypoint.
+The canonical URL of the stylesheet being parsed.
 
-> This *must* be passed when `importer` is passed, since otherwise there's
+> When `importer` isn't passed, this is purely advisory and only used for error
-> nothing to resolve relative URLs relative to.
+> reporting. When it is, it's used as the base URL of the relative imports
+> within the entrypoint.
 
 ```ts
-url: URL;
+url?: URL;
 ```
 
 ```ts
-} // StringOptionsWithImporter
+} // StringOptions
 ```
 
-### `StringOptions`
+### `StringOptionsWithoutImporter`
+
+> This alias exists for backwards-compatibility only.
 
 ```ts
-export type StringOptions<sync extends 'sync' | 'async'> =
+type StringOptionsWithoutImporter<sync extends 'sync' | 'async'> =
-  | StringOptionsWithImporter<sync>
+  StringOptions<sync>;
-  | StringOptionsWithoutImporter<sync>;
+```
+
+### `StringOptionsWithImporter`
+
+> This alias exists for backwards-compatibility only.
+
+```ts
+type StringOptionsWithImporter<sync extends 'sync' | 'async'> =
+  StringOptions<sync>;
 ```

spec/modules.md

@@ -377,13 +377,19 @@ This algorithm takes a string `argument` and [configuration](#configuration)
 This algorithm takes a string, `argument`, and returns either a [source file] or
 null.
 
-* If `argument` is a relative URL:
+* If `argument` is a relative URL and the [current source file] has an
+  [importer] `importer`:
 
-  * Let `resolved` be the result of [parsing `argument` as a URL][parsing a URL]
+  * If the current source file has a canonical URL `canonical`, let `url` be the
-    with the [current source file]'s canonical URL as the base URL.
+    result of [parsing `argument` as a URL][parsing a URL] with `canonical` as
+    the base URL. Otherwise, let `url` be `argument`.
 
-  * Let `result` be the result of passing `resolved` to the current source
+    > Allowing `url` to remain relative here in the absence of a canonical URL
-    file's [importer](#importer).
+    > is a bit of a hack, but it's useful in that many importers (including
+    > [filesystem importer]s) act as "load paths", resolving URLs relative to
+    > some implicit base URL rather than expecting all inputs to be absolute.
+
+  * Let `result` be the result of passing `url` to `base`.
 
   * If `result` is not null:
 
@@ -406,6 +412,7 @@ null.
 
 * Return null.
 
+[filesystem importer]: #filesystem-importer
 [parsing]: syntax.md#parsing-text
 
 ### Resolving a `file:` URL