sass 1.72.0 → 1.75.0

package/sass.default.js

@@ -43,3 +43,5 @@ export const FALSE = _cliPkgExports.FALSE;
 export const NULL = _cliPkgExports.NULL;
 export const types = _cliPkgExports.types;
 export const NodePackageImporter = _cliPkgExports.NodePackageImporter;
+export const deprecations = _cliPkgExports.deprecations;
+export const Version = _cliPkgExports.Version;

package/sass.node.mjs

@@ -37,6 +37,8 @@ export const FALSE = cjs.FALSE;
 export const NULL = cjs.NULL;
 export const types = cjs.types;
 export const NodePackageImporter = cjs.NodePackageImporter;
+export const deprecations = cjs.deprecations;
+export const Version = cjs.Version;
 
 let printedDefaultExportDeprecation = false;
 function defaultExportDeprecation() {
@@ -196,4 +198,12 @@ export default {
     defaultExportDeprecation();
     return cjs.NodePackageImporter;
   },
+  get deprecations() {
+    defaultExportDeprecation();
+    return cjs.deprecations;
+  },
+  get Version() {
+    defaultExportDeprecation();
+    return cjs.Version;
+  },
 };

package/types/deprecations.d.ts

@@ -0,0 +1,209 @@
+/**
+ * All of the deprecation types currently used by Sass.
+ *
+ * Any of these IDs or the deprecation objects they point to can be passed to
+ * `fatalDeprecations`, `futureDeprecations`, or `silenceDeprecations`.
+ */
+export interface Deprecations {
+  /**
+   * Deprecation for passing a string to `call` instead of using `get-function`.
+   *
+   * This deprecation has been active in all versions of Dart Sass.
+   */
+  'call-string': Deprecation<'call-string'>;
+
+  /**
+   * Deprecation for `@elseif`.
+   *
+   * This deprecation became active in Dart Sass 1.3.2.
+   */
+  elseif: Deprecation<'elseif'>;
+
+  /**
+   * Deprecation for parsing `@-moz-document`.
+   *
+   * This deprecation became active in Dart Sass 1.7.2.
+   */
+  'moz-document': Deprecation<'moz-document'>;
+
+  /**
+   * Deprecation for imports using relative canonical URLs.
+   *
+   * This deprecation became active in Dart Sass 1.17.2.
+   */
+  'relative-canonical': Deprecation<'relative-canonical'>;
+
+  /**
+   * Deprecation for declaring new variables with `!global`.
+   *
+   * This deprecation became active in Dart Sass 1.17.2.
+   */
+  'new-global': Deprecation<'new-global'>;
+
+  /**
+   * Deprecation for using color module functions in place of plain CSS
+   * functions.
+   *
+   * This deprecation became active in Dart Sass 1.23.0.
+   */
+  'color-module-compat': Deprecation<'color-module-compat'>;
+
+  /**
+   * Deprecation for treating `/` as division.
+   *
+   * This deprecation became active in Dart Sass 1.33.0.
+   */
+  'slash-div': Deprecation<'slash-div'>;
+
+  /**
+   * Deprecation for leading, trailing, and repeated combinators.
+   *
+   * This deprecation became active in Dart Sass 1.54.0.
+   */
+  'bogus-combinators': Deprecation<'bogus-combinators'>;
+
+  /**
+   * Deprecation for ambiguous `+` and `-` operators.
+   *
+   * This deprecation became active in Dart Sass 1.55.0.
+   */
+  'strict-unary': Deprecation<'strict-unary'>;
+
+  /**
+   * Deprecation for passing invalid units to certain built-in functions.
+   *
+   * This deprecation became active in Dart Sass 1.56.0.
+   */
+  'function-units': Deprecation<'function-units'>;
+
+  /**
+   * Deprecation for using `!default` or `!global` multiple times for one
+   * variable.
+   *
+   * This deprecation became active in Dart Sass 1.62.0.
+   */
+  'duplicate-var-flags': Deprecation<'duplicate-var-flags'>;
+
+  /**
+   * Deprecation for passing null as alpha in the JS API.
+   *
+   * This deprecation became active in Dart Sass 1.62.3.
+   */
+  'null-alpha': Deprecation<'null-alpha'>;
+
+  /**
+   * Deprecation for passing percentages to the Sass `abs()` function.
+   *
+   * This deprecation became active in Dart Sass 1.65.0.
+   */
+  'abs-percent': Deprecation<'abs-percent'>;
+
+  /**
+   * Deprecation for using the current working directory as an implicit load
+   * path.
+   *
+   * This deprecation became active in Dart Sass 1.73.0.
+   */
+  'fs-importer-cwd': Deprecation<'fs-importer-cwd'>;
+
+  /**
+   * Deprecation for `@import` rules.
+   *
+   * This deprecation is not yet active, but will be soon.
+   */
+  import: Deprecation<'import'>;
+
+  /**
+   * Used for any user-emitted deprecation warnings.
+   */
+  'user-authored': Deprecation<'user-authored', 'user'>;
+}
+
+/**
+ * Either a deprecation or its ID, either of which can be passed to any of
+ * the relevant compiler options.
+ *
+ * @category Messages
+ * @compatibility dart: "1.74.0", node: false
+ */
+export type DeprecationOrId = Deprecation | keyof Deprecations;
+
+/**
+ * The possible statuses that each deprecation can have.
+ *
+ * "active" deprecations are currently emitting deprecation warnings.
+ * "future" deprecations are not yet active, but will be in the future.
+ * "obsolete" deprecations were once active, but no longer are.
+ *
+ * The only "user" deprecation is "user-authored", which is used for deprecation
+ * warnings coming from user code.
+ *
+ * @category Messages
+ * @compatibility dart: "1.74.0", node: false
+ */
+export type DeprecationStatus = 'active' | 'user' | 'future' | 'obsolete';
+
+/**
+ * A deprecated feature in the language.
+ *
+ * @category Messages
+ * @compatibility dart: "1.74.0", node: false
+ */
+export interface Deprecation<
+  id extends keyof Deprecations = keyof Deprecations,
+  status extends DeprecationStatus = DeprecationStatus
+> {
+  /** The unique ID of this deprecation. */
+  id: id;
+
+  /** The current status of this deprecation. */
+  status: status;
+
+  /** A human-readable description of this deprecation. */
+  description?: string;
+
+  /** The version this deprecation first became active in. */
+  deprecatedIn: status extends 'future' | 'user' ? null : Version;
+
+  /** The version this deprecation became obsolete in. */
+  obsoleteIn: status extends 'obsolete' ? Version : null;
+}
+
+/**
+ * A semantic version of the compiler.
+ *
+ * @category Messages
+ * @compatibility dart: "1.74.0", node: false
+ */
+export class Version {
+  /**
+   * Constructs a new version.
+   *
+   * All components must be non-negative integers.
+   *
+   * @param major - The major version.
+   * @param minor - The minor version.
+   * @param patch - The patch version.
+   */
+  constructor(major: number, minor: number, patch: number);
+  readonly major: number;
+  readonly minor: number;
+  readonly patch: number;
+
+  /**
+   * Parses a version from a string.
+   *
+   * This throws an error if a valid version can't be parsed.
+   *
+   * @param version - A string in the form "major.minor.patch".
+   */
+  static parse(version: string): Version;
+}
+
+/**
+ * An object containing all deprecation types.
+ *
+ * @category Messages
+ * @compatibility dart: "1.74.0", node: false
+ */
+export const deprecations: Deprecations;

package/types/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.

package/types/index.d.ts

@@ -13,6 +13,14 @@ export {
   initCompiler,
   initAsyncCompiler,
 } from './compile';
+export {
+  deprecations,
+  Deprecation,
+  Deprecations,
+  DeprecationOrId,
+  DeprecationStatus,
+  Version,
+} from './deprecations';
 export {Exception} from './exception';
 export {
   CanonicalizeContext,

package/types/logger/index.d.ts

@@ -1,3 +1,4 @@
+import {Deprecation} from '../deprecations';
 import {SourceSpan} from './source_span';
 
 export {SourceLocation} from './source_location';
@@ -43,17 +44,21 @@ export interface Logger {
    *
    * @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: boolean;
-      span?: SourceSpan;
-      stack?: string;
-    }
+    options: (
+      | {
+          deprecation: true;
+          deprecationType: Deprecation;
+        }
+      | {deprecation: false}
+    ) & {span?: SourceSpan; stack?: string}
   ): void;
 
   /**

package/types/options.d.ts

@@ -1,3 +1,4 @@
+import {DeprecationOrId, Version} from './deprecations';
 import {FileImporter, Importer, NodePackageImporter} from './importer';
 import {Logger} from './logger';
 import {Value} from './value';
@@ -122,6 +123,20 @@ export interface Options<sync extends 'sync' | 'async'> {
    */
   charset?: boolean;
 
+  /**
+   * A set of deprecations to treat as fatal.
+   *
+   * If a deprecation warning of any provided type is encountered during
+   * compilation, the compiler will error instead.
+   *
+   * If a `Version` is provided, then all deprecations that were active in that
+   * compiler version will be treated as fatal.
+   *
+   * @category Messages
+   * @compatiblity dart: "1.74.0", node: false
+   */
+  fatalDeprecations?: (DeprecationOrId | Version)[];
+
   /**
    * Additional built-in Sass functions that are available in all stylesheets.
    * This option takes an object whose keys are Sass function signatures like
@@ -198,6 +213,17 @@ export interface Options<sync extends 'sync' | 'async'> {
    */
   functions?: Record<string, CustomFunction<sync>>;
 
+  /**
+   * A set of future deprecations to opt into early.
+   *
+   * Future deprecations passed here will be treated as active by the compiler,
+   * emitting warnings as necessary.
+   *
+   * @category Messages
+   * @compatiblity dart: "1.74.0", node: false
+   */
+  futureDeprecations?: DeprecationOrId[];
+
   /**
    * Custom importers that control how Sass resolves loads from rules like
    * [`@use`](https://sass-lang.com/documentation/at-rules/use) and
@@ -266,16 +292,30 @@ 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
    */
   quietDeps?: boolean;
 
+  /**
+   * A set of active deprecations to ignore.
+   *
+   * If a deprecation warning of any provided type is encountered during
+   * compilation, the compiler will ignore it instead.
+   *
+   * **Heads up!** The deprecated functionality you're depending on will
+   * eventually break.
+   *
+   * @category Messages
+   * @compatiblity dart: "1.74.0", node: false
+   */
+  silenceDeprecations?: DeprecationOrId[];
+
   /**
    * Whether or not Sass should generate a source map. If it does, the source
    * map will be available as {@link CompileResult.sourceMap}.
@@ -348,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
@@ -358,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.
@@ -369,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.
    *
@@ -378,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>;