mirror of
https://github.com/sass/sass.git
synced 2024-09-21 02:27:30 +00:00
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>
This commit is contained in:
Natalie Weizenbaum
GitHub
parent
c0c25d5c28
commit
55514224ca
4
js-api-doc/importer.d.ts
vendored
4
js-api-doc/importer.d.ts
vendored
@ -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.
|
||||
|
||||
88
js-api-doc/options.d.ts
vendored
88
js-api-doc/options.d.ts
vendored
@ -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>
|
||||
* stylesheets it loads will be considered dependencies. Since it doesn’t have
|
||||
* a path of its own, everything it loads is coming from a load path rather
|
||||
* than a relative import.
|
||||
* called without {@link StringOptions.url}, <em>all</em> stylesheets it loads
|
||||
* will be considered dependencies. Since it doesn’t have a path of its own,
|
||||
* everything it loads is coming from a load path rather than a relative
|
||||
* 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
|
||||
* entrypoint file can load files relative to itself if a `file://` URL is
|
||||
* passed to the {@link url} field.
|
||||
* 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.
|
||||
*
|
||||
* @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'>
|
||||
extends StringOptionsWithoutImporter<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;
|
||||
}
|
||||
type StringOptionsWithoutImporter<sync extends 'sync' | 'async'> =
|
||||
StringOptions<sync>;
|
||||
|
||||
/**
|
||||
* 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'> =
|
||||
| StringOptionsWithImporter<sync>
|
||||
| StringOptionsWithoutImporter<sync>;
|
||||
type StringOptionsWithImporter<sync extends 'sync' | 'async'> =
|
||||
StringOptions<sync>;
|
||||
|
||||
@ -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
|
||||
> don't support relative imports.
|
||||
> [`compileStringAsync()`].
|
||||
>
|
||||
> [`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
|
||||
> nothing to resolve relative URLs relative to.
|
||||
> When `importer` isn't passed, this is purely advisory and only used for error
|
||||
> 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'> =
|
||||
| StringOptionsWithImporter<sync>
|
||||
| StringOptionsWithoutImporter<sync>;
|
||||
type StringOptionsWithoutImporter<sync extends 'sync' | 'async'> =
|
||||
StringOptions<sync>;
|
||||
```
|
||||
|
||||
### `StringOptionsWithImporter`
|
||||
|
||||
> This alias exists for backwards-compatibility only.
|
||||
|
||||
```ts
|
||||
type StringOptionsWithImporter<sync extends 'sync' | 'async'> =
|
||||
StringOptions<sync>;
|
||||
```
|
||||
|
||||
@ -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]
|
||||
with the [current source file]'s canonical URL as the base URL.
|
||||
* If the current source file has a canonical URL `canonical`, let `url` be the
|
||||
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
|
||||
file's [importer](#importer).
|
||||
> Allowing `url` to remain relative here in the absence of a canonical URL
|
||||
> 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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user