sass 1.63.6 → 1.64.0

package/sass.default.js

@@ -13,6 +13,9 @@ export const compileStringAsync = _cliPkgExports.compileStringAsync;
 export const Logger = _cliPkgExports.Logger;
 export const SassArgumentList = _cliPkgExports.SassArgumentList;
 export const SassBoolean = _cliPkgExports.SassBoolean;
+export const SassCalculation = _cliPkgExports.SassCalculation;
+export const CalculationOperation = _cliPkgExports.CalculationOperation;
+export const CalculationInterpolation = _cliPkgExports.CalculationInterpolation;
 export const SassColor = _cliPkgExports.SassColor;
 export const SassFunction = _cliPkgExports.SassFunction;
 export const SassList = _cliPkgExports.SassList;

package/sass.node.mjs

@@ -7,6 +7,9 @@ export const compileStringAsync = cjs.compileStringAsync;
 export const Logger = cjs.Logger;
 export const SassArgumentList = cjs.SassArgumentList;
 export const SassBoolean = cjs.SassBoolean;
+export const SassCalculation = cjs.SassCalculation;
+export const CalculationOperation = cjs.CalculationOperation;
+export const CalculationInterpolation = cjs.CalculationInterpolation;
 export const SassColor = cjs.SassColor;
 export const SassFunction = cjs.SassFunction;
 export const SassList = cjs.SassList;
@@ -67,6 +70,18 @@ export default {
     defaultExportDeprecation();
     return cjs.SassBoolean;
   },
+  get SassCalculation() {
+    defaultExportDeprecation();
+    return cjs.SassCalculation;
+  },
+  get CalculationOperation() {
+    defaultExportDeprecation();
+    return cjs.CalculationOperation;
+  },
+  get CalculationInterpolation() {
+    defaultExportDeprecation();
+    return cjs.CalculationInterpolation;
+  },
   get SassColor() {
     defaultExportDeprecation();
     return cjs.SassColor;

package/types/index.d.ts

@@ -23,9 +23,14 @@ export {
 } from './options';
 export {PromiseOr} from './util/promise_or';
 export {
+  CalculationInterpolation,
+  CalculationOperation,
+  CalculationOperator,
+  CalculationValue,
   ListSeparator,
   SassArgumentList,
   SassBoolean,
+  SassCalculation,
   SassColor,
   SassFunction,
   SassList,

package/types/legacy/options.d.ts

@@ -390,9 +390,8 @@ export interface LegacySharedOptions<sync extends 'sync' | 'async'> {
    * whose values are {@link LegacyFunction}s. Each function should take the
    * same arguments as its signature.
    *
-   * Functions are passed JavaScript representations of [Sass value
-   * types](https://sass-lang.com/documentation/js-api#value-types), and must
-   * return the same.
+   * Functions are passed subclasses of {@link LegacyValue}, and must return the
+   * same.
    *
    * **Heads up!** When writing custom functions, it’s important to ensure that
    * all the arguments are the types you expect. Otherwise, users’ stylesheets

package/types/options.d.ts

@@ -129,9 +129,9 @@ export interface Options<sync extends 'sync' | 'async'> {
    * rule`](https://sass-lang.com/documentation/at-rules/function) and whose
    * values are {@link CustomFunction}s.
    *
-   * Functions are passed JavaScript representations of [Sass value
-   * types](https://sass-lang.com/documentation/js-api#value-types), and must
-   * return the same.
+   * Functions are passed subclasses of {@link Value}, and must return the same.
+   * If the return value includes {@link SassCalculation}s they will be
+   * simplified before being returned.
    *
    * When writing custom functions, it's important to make them as user-friendly
    * and as close to the standards set by Sass's core functions as possible. Some

package/types/value/calculation.d.ts

@@ -0,0 +1,137 @@
+import {List, ValueObject} from 'immutable';
+import {Value, SassNumber, SassString} from './index';
+
+/**
+ * The type of values that can be arguments to a {@link SassCalculation}.
+ * @category Custom Function
+ * */
+export type CalculationValue =
+  | SassNumber
+  | SassCalculation
+  | SassString
+  | CalculationOperation
+  | CalculationInterpolation;
+
+/**
+ * Sass's [calculation
+ * type](https://sass-lang.com/documentation/values/calculations).
+ *
+ * Note: in the JS API calculations are not simplified eagerly. This also means
+ * that unsimplified calculations are not equal to the numbers they would be
+ * simplified to.
+ *
+ * @category Custom Function
+ */
+export class SassCalculation extends Value {
+  /**
+   * Creates a value that represents `calc(argument)`.
+   *
+   * @throws `Error` if `argument` is a quoted {@link SassString}
+   * @returns A calculation with the name `calc` and `argument` as its single
+   * argument.
+   */
+  static calc(argument: CalculationValue): SassCalculation;
+
+  /**
+   * Creates a value that represents `min(arguments...)`.
+   *
+   * @throws `Error` if `arguments` contains a quoted {@link SassString}
+   * @returns A calculation with the name `min` and `arguments` as its
+   * arguments.
+   */
+  static min(
+    arguments: CalculationValue[] | List<CalculationValue>
+  ): SassCalculation;
+
+  /**
+   * Creates a value that represents `max(arguments...)`.
+   *
+   * @throws `Error` if `arguments` contains a quoted {@link SassString}
+   * @returns A calculation with the name `max` and `arguments` as its
+   * arguments.
+   */
+  static max(
+    arguments: CalculationValue[] | List<CalculationValue>
+  ): SassCalculation;
+
+  /**
+   * Creates a value that represents `clamp(value, min, max)`.
+   *
+   * @throws `Error` if any of `value`, `min`, or `max` are  a quoted
+   * {@link SassString}.
+   * @throws `Error` if `value` is undefined and `max` is not undefined.
+   * @throws `Error` if either `value` or `max` is undefined and neither `min`
+     nor `value` is a {@link SassString} or {@link CalculationInterpolation}.
+     @returns A calculation with the name `clamp` and `min`, `value`, and `max`
+     as it's arguments, excluding any arguments that are undefined.
+   */
+  static clamp(
+    min: CalculationValue,
+    value?: CalculationValue,
+    max?: CalculationValue
+  ): SassCalculation;
+
+  /** Returns the calculation's `name` field. */
+  get name(): string;
+
+  /** Returns a list of the calculation's `arguments` */
+  get arguments(): List<CalculationValue>;
+}
+
+/**
+ * The set of possible operators in a Sass calculation.
+ * @category Custom Function
+ */
+export type CalculationOperator = '+' | '-' | '*' | '/';
+
+/**
+ * A binary operation that can appear in a {@link SassCalculation}.
+ * @category Custom Function
+ */
+export class CalculationOperation implements ValueObject {
+  /**
+   * Creates a Sass CalculationOperation with the given `operator`, `left`, and
+   * `right` values.
+   * @throws `Error` if `left` or `right` are quoted {@link SassString}s.
+   */
+  constructor(
+    operator: CalculationOperator,
+    left: CalculationValue,
+    right: CalculationValue
+  );
+
+  /** Returns the operation's `operator` field. */
+  get operator(): CalculationOperator;
+
+  /** Returns the operation's `left` field. */
+  get left(): CalculationValue;
+
+  /** Returns the operation's `right` field. */
+  get right(): CalculationValue;
+
+  equals(other: unknown): boolean;
+
+  hashCode(): number;
+}
+
+/**
+ * A string injected into a {@link SassCalculation} using interpolation. Unlike
+ * unquoted strings, interpolations are always surrounded in parentheses when
+ * they appear in {@link CalculationOperation}s.
+ * @category Custom Function
+ */
+export class CalculationInterpolation implements ValueObject {
+  /**
+   * Creates a Sass CalculationInterpolation with the given `value`.
+   */
+  constructor(value: string);
+
+  /**
+   * Returns the interpolation's `value` field.
+   */
+  get value(): string;
+
+  equals(other: unknown): boolean;
+
+  hashCode(): number;
+}

package/types/value/index.d.ts

@@ -1,6 +1,7 @@
 import {List, ValueObject} from 'immutable';
 
 import {SassBoolean} from './boolean';
+import {SassCalculation} from './calculation';
 import {SassColor} from './color';
 import {SassFunction} from './function';
 import {ListSeparator} from './list';
@@ -10,6 +11,13 @@ import {SassString} from './string';
 
 export {SassArgumentList} from './argument_list';
 export {SassBoolean, sassTrue, sassFalse} from './boolean';
+export {
+  SassCalculation,
+  CalculationValue,
+  CalculationOperator,
+  CalculationOperation,
+  CalculationInterpolation,
+} from './calculation';
 export {SassColor} from './color';
 export {SassFunction} from './function';
 export {SassList, ListSeparator} from './list';
@@ -116,6 +124,14 @@ export abstract class Value implements ValueObject {
    */
   assertBoolean(name?: string): SassBoolean;
 
+  /**
+   * Throws if `this` isn't a {@link SassCalculation}.
+   *
+   * @param name - The name of the function argument `this` came from (without
+   * the `$`) if it came from an argument. Used for error reporting.
+   */
+  assertCalculation(name?: string): SassCalculation;
+
   /**
    * Throws if `this` isn't a {@link SassColor}.
    *