sass 1.67.0 → 1.69.0

package/sass.default.js

@@ -20,6 +20,7 @@ export const SassColor = _cliPkgExports.SassColor;
 export const SassFunction = _cliPkgExports.SassFunction;
 export const SassList = _cliPkgExports.SassList;
 export const SassMap = _cliPkgExports.SassMap;
+export const SassMixin = _cliPkgExports.SassMixin;
 export const SassNumber = _cliPkgExports.SassNumber;
 export const SassString = _cliPkgExports.SassString;
 export const Value = _cliPkgExports.Value;

package/sass.node.mjs

@@ -14,6 +14,7 @@ export const SassColor = cjs.SassColor;
 export const SassFunction = cjs.SassFunction;
 export const SassList = cjs.SassList;
 export const SassMap = cjs.SassMap;
+export const SassMixin = cjs.SassMixin;
 export const SassNumber = cjs.SassNumber;
 export const SassString = cjs.SassString;
 export const Value = cjs.Value;
@@ -98,6 +99,10 @@ export default {
     defaultExportDeprecation();
     return cjs.SassMap;
   },
+  get SassMixin() {
+    defaultExportDeprecation();
+    return cjs.SassMixin;
+  },
   get SassNumber() {
     defaultExportDeprecation();
     return cjs.SassNumber;

package/types/importer.d.ts

@@ -1,6 +1,38 @@
 import {Syntax} from './options';
 import {PromiseOr} from './util/promise_or';
 
+/**
+ * Contextual information passed to {@link Importer.canonicalize} and {@link
+ * FileImporter.findFileUrl}. Not all importers will need this information to
+ * resolve loads, but some may find it useful.
+ */
+export interface CanonicalizeContext {
+  /**
+   * Whether this is being invoked because of a Sass
+   * `@import` rule, as opposed to a `@use` or `@forward` rule.
+   *
+   * This should *only* be used for determining whether or not to load
+   * [import-only files](https://sass-lang.com/documentation/at-rules/import#import-only-files).
+   */
+  fromImport: boolean;
+
+  /**
+   * The canonical URL of the file that contains the load, if that information
+   * is available.
+   *
+   * For an {@link Importer}, this is only passed when the `url` parameter is a
+   * relative URL _or_ when its [URL scheme] is included in {@link
+   * Importer.nonCanonicalScheme}. This ensures that canonical URLs are always
+   * resolved the same way regardless of context.
+   *
+   * [URL scheme]: https://developer.mozilla.org/en-US/docs/Learn/Common_questions/Web_mechanics/What_is_a_URL#scheme
+   *
+   * For a {@link FileImporter}, this is always available as long as Sass knows
+   * the canonical URL of the containing file.
+   */
+  containingUrl: URL | null;
+}
+
 /**
  * A special type of importer that redirects all loads to existing files on
  * disk. Although this is less powerful than a full {@link Importer}, it
@@ -56,12 +88,6 @@ export interface FileImporter<
    * @param url - The loaded URL. Since this might be relative, it's represented
    * as a string rather than a {@link URL} object.
    *
-   * @param options.fromImport - Whether this is being invoked because of a Sass
-   * `@import` rule, as opposed to a `@use` or `@forward` rule.
-   *
-   * This should *only* be used for determining whether or not to load
-   * [import-only files](https://sass-lang.com/documentation/at-rules/import#import-only-files).
-   *
    * @returns An absolute `file:` URL if this importer recognizes the `url`.
    * This may be only partially resolved: the compiler will automatically look
    * for [partials](https://sass-lang.com/documentation/at-rules/use#partials),
@@ -85,7 +111,7 @@ export interface FileImporter<
    */
   findFileUrl(
     url: string,
-    options: {fromImport: boolean}
+    context: CanonicalizeContext
   ): PromiseOr<URL | null, sync>;
 
   /** @hidden */
@@ -220,12 +246,6 @@ export interface Importer<sync extends 'sync' | 'async' = 'sync' | 'async'> {
    * @param url - The loaded URL. Since this might be relative, it's represented
    * as a string rather than a {@link URL} object.
    *
-   * @param options.fromImport - Whether this is being invoked because of a Sass
-   * `@import` rule, as opposed to a `@use` or `@forward` rule.
-   *
-   * This should *only* be used for determining whether or not to load
-   * [import-only files](https://sass-lang.com/documentation/at-rules/import#import-only-files).
-   *
    * @returns An absolute URL if this importer recognizes the `url`, or `null`
    * if it doesn't. If this returns `null`, other importers or {@link
    * Options.loadPaths | load paths} may handle the load.
@@ -242,7 +262,7 @@ export interface Importer<sync extends 'sync' | 'async' = 'sync' | 'async'> {
    */
   canonicalize(
     url: string,
-    options: {fromImport: boolean}
+    context: CanonicalizeContext
   ): PromiseOr<URL | null, sync>;
 
   /**
@@ -272,6 +292,20 @@ export interface Importer<sync extends 'sync' | 'async' = 'sync' | 'async'> {
 
   /** @hidden */
   findFileUrl?: never;
+
+  /**
+   * A URL scheme or set of schemes (without the `:`) that this importer
+   * promises never to use for URLs returned by {@link canonicalize}. If it does
+   * return a URL with one of these schemes, that's an error.
+   *
+   * If this is set, any call to canonicalize for a URL with a non-canonical
+   * scheme will be passed {@link CanonicalizeContext.containingUrl} if it's
+   * known.
+   *
+   * These schemes may only contain lowercase ASCII letters, ASCII numerals,
+   * `+`, `-`, and `.`. They may not be empty.
+   */
+  nonCanonicalScheme?: string | string[];
 }
 
 /**

package/types/index.d.ts

@@ -10,7 +10,12 @@ export {
   compileStringAsync,
 } from './compile';
 export {Exception} from './exception';
-export {FileImporter, Importer, ImporterResult} from './importer';
+export {
+  CanonicalizeContext,
+  FileImporter,
+  Importer,
+  ImporterResult,
+} from './importer';
 export {Logger, SourceSpan, SourceLocation} from './logger';
 export {
   CustomFunction,
@@ -35,6 +40,7 @@ export {
   SassFunction,
   SassList,
   SassMap,
+  SassMixin,
   SassNumber,
   SassString,
   Value,

package/types/value/index.d.ts

@@ -6,6 +6,7 @@ import {SassColor} from './color';
 import {SassFunction} from './function';
 import {ListSeparator} from './list';
 import {SassMap} from './map';
+import {SassMixin} from './mixin';
 import {SassNumber} from './number';
 import {SassString} from './string';
 
@@ -22,6 +23,7 @@ export {SassColor} from './color';
 export {SassFunction} from './function';
 export {SassList, ListSeparator} from './list';
 export {SassMap} from './map';
+export {SassMixin} from './mixin';
 export {SassNumber} from './number';
 export {SassString} from './string';
 
@@ -156,6 +158,14 @@ export abstract class Value implements ValueObject {
    */
   assertMap(name?: string): SassMap;
 
+  /**
+   * Throws if `this` isn't a {@link SassMixin}.
+   *
+   * @param name - The name of the function argument `this` came from (without
+   * the `$`) if it came from an argument. Used for error reporting.
+   */
+  assertMixin(name?: string): SassMixin;
+
   /**
    * Throws if `this` isn't a {@link SassNumber}.
    *

package/types/value/mixin.d.ts

@@ -0,0 +1,14 @@
+import {Value} from './index';
+
+/**
+ * Sass's [mixin type](https://sass-lang.com/documentation/values/mixins).
+ *
+ * @category Custom Function
+ */
+export class SassMixin extends Value {
+  /**
+   * It is not possible to construct a Sass mixin outside of Sass. Attempting to
+   * construct one will throw an exception.
+   */
+  constructor();
+}