sass 1.43.4 → 1.45.0-rc.2

package/types/util/promise_or.d.ts

@@ -0,0 +1,17 @@
+/**
+ * A utility type for choosing between synchronous and asynchronous return
+ * values.
+ *
+ * This is used as the return value for plugins like [[CustomFunction]],
+ * [[Importer]], and [[FileImporter]] so that TypeScript enforces that
+ * asynchronous plugins are only passed to [[compileAsync]] and
+ * [[compileStringAsync]], not [[compile]] or [[compileString]].
+ *
+ * @typeParam sync - If this is `'sync'`, this can only be a `T`. If it's
+ * `'async'`, this can be either a `T` or a `Promise<T>`.
+ *
+ * @category Other
+ */
+export type PromiseOr<T, sync extends 'sync' | 'async'> = sync extends 'async'
+  ? T | Promise<T>
+  : T;

package/types/value/argument_list.d.ts

@@ -0,0 +1,47 @@
+import {List, OrderedMap} from 'immutable';
+
+import {Value} from './index';
+import {SassList, ListSeparator} from './list';
+
+/**
+ * Sass's [argument list
+ * type](https://sass-lang.com/documentation/values/lists#argument-lists).
+ *
+ * An argument list comes from a rest argument. It's distinct from a normal
+ * [[SassList]] in that it may contain a keyword map as well as the positional
+ * arguments.
+ *
+ * @category Custom Function
+ */
+export class SassArgumentList extends SassList {
+  /**
+   * Creates a new argument list.
+   *
+   * @param contents - The positional arguments that make up the primary
+   * contents of the list. This may be either a plain JavaScript array or an
+   * immutable [[List]] from the [`immutable`
+   * package](https://immutable-js.com/).
+   *
+   * @param keywords - The keyword arguments attached to this argument list,
+   * whose names should exclude `$`. This can be either a plain JavaScript
+   * object with argument names as fields, or an immutable [[OrderedMap]] from
+   * the [`immutable` package](https://immutable-js.com/)
+   *
+   * @param separator - The separator for this list. Defaults to `','`.
+   */
+  constructor(
+    contents: Value[] | List<Value>,
+    keywords: Record<string, Value> | OrderedMap<string, Value>,
+    separator?: ListSeparator
+  );
+
+  /**
+   * The keyword arguments attached to this argument list.
+   *
+   * The argument names don't include `$`.
+   *
+   * @returns An immutable [[OrderedMap]] from the [`immutable`
+   * package](https://immutable-js.com/).
+   */
+  get keywords(): OrderedMap<string, Value>;
+}

package/types/value/boolean.d.ts

@@ -0,0 +1,29 @@
+import {Value} from './index';
+
+/**
+ * Sass's [`true` value](https://sass-lang.com/documentation/values/booleans).
+ *
+ * @category Custom Function
+ */
+export const sassTrue: SassBoolean;
+
+/**
+ * Sass's [`false` value](https://sass-lang.com/documentation/values/booleans).
+ *
+ * @category Custom Function
+ */
+export const sassFalse: SassBoolean;
+
+/**
+ * Sass's [boolean type](https://sass-lang.com/documentation/values/booleans).
+ *
+ * @category Custom Function
+ */
+export class SassBoolean extends Value {
+  private constructor();
+
+  /**
+   * Whether this value is `true` or `false`.
+   */
+  get value(): boolean;
+}

package/types/value/color.d.ts

@@ -0,0 +1,107 @@
+import {Value} from './index';
+
+/**
+ * Sass's [color type](https://sass-lang.com/documentation/values/colors).
+ *
+ * No matter what representation was originally used to create this color, all
+ * of its channels are accessible.
+ *
+ * @category Custom Function
+ */
+export class SassColor extends Value {
+  /**
+   * Creates an RGB color.
+   *
+   * @throws `Error` if `red`, `green`, and `blue` aren't between `0` and
+   * `255`, or if `alpha` isn't between `0` and `1`.
+   */
+  constructor(options: {
+    red: number;
+    green: number;
+    blue: number;
+    alpha?: number;
+  });
+
+  /**
+   * Creates an HSL color.
+   *
+   * @throws `Error` if `saturation` or `lightness` aren't between `0` and
+   * `100`, or if `alpha` isn't between `0` and `1`.
+   */
+  constructor(options: {
+    hue: number;
+    saturation: number;
+    lightness: number;
+    alpha?: number;
+  });
+
+  /**
+   * Creates an HWB color.
+   *
+   * @throws `Error` if `whiteness` or `blackness` aren't between `0` and `100`,
+   * or if `alpha` isn't between `0` and `1`.
+   */
+  constructor(options: {
+    hue: number;
+    whiteness: number;
+    blackness: number;
+    alpha?: number;
+  });
+
+  /** This color's red channel, between `0` and `255`. */
+  get red(): number;
+
+  /** This color's green channel, between `0` and `255`. */
+  get green(): number;
+
+  /** This color's blue channel, between `0` and `255`. */
+  get blue(): number;
+
+  /** This color's hue, between `0` and `360`. */
+  get hue(): number;
+
+  /** This color's saturation, between `0` and `100`. */
+  get saturation(): number;
+
+  /** This color's lightness, between `0` and `100`. */
+  get lightness(): number;
+
+  /** This color's whiteness, between `0` and `100`. */
+  get whiteness(): number;
+
+  /** This color's blackness, between `0` and `100`. */
+  get blackness(): number;
+
+  /** This color's alpha channel, between `0` and `1`. */
+  get alpha(): number;
+
+  /**
+   * Changes one or more of this color's RGB channels and returns the result.
+   */
+  change(options: {
+    red?: number;
+    green?: number;
+    blue?: number;
+    alpha?: number;
+  }): SassColor;
+
+  /**
+   * Changes one or more of this color's HSL channels and returns the result.
+   */
+  change(options: {
+    hue?: number;
+    saturation?: number;
+    lightness?: number;
+    alpha?: number;
+  }): SassColor;
+
+  /**
+   * Changes one or more of this color's HWB channels and returns the result.
+   */
+  change(options: {
+    hue?: number;
+    whiteness?: number;
+    blackness?: number;
+    alpha?: number;
+  }): SassColor;
+}

package/types/value/function.d.ts

@@ -0,0 +1,22 @@
+import {Value} from './index';
+
+/**
+ * Sass's [function type](https://sass-lang.com/documentation/values/functions).
+ *
+ * **Heads up!** Although first-class Sass functions can be processed by custom
+ * functions, there's no way to invoke them outside of a Sass stylesheet.
+ *
+ * @category Custom Function
+ */
+export class SassFunction extends Value {
+  /**
+   * Creates a new first-class function that can be invoked using
+   * [`meta.call()`](https://sass-lang.com/documentation/modules/meta#call).
+   *
+   * @param signature - The function signature, like you'd write for the
+   * [`@function rule`](https://sass-lang.com/documentation/at-rules/function).
+   * @param callback - The callback that's invoked when this function is called,
+   * just like for a [[CustomFunction]].
+   */
+  constructor(signature: string, callback: (args: Value[]) => Value);
+}

package/types/value/index.d.ts

@@ -0,0 +1,173 @@
+import {List, ValueObject} from 'immutable';
+
+import {SassBoolean} from './boolean';
+import {SassColor} from './color';
+import {SassFunction} from './function';
+import {ListSeparator} from './list';
+import {SassMap} from './map';
+import {SassNumber} from './number';
+import {SassString} from './string';
+
+export {SassArgumentList} from './argument_list';
+export {SassBoolean, sassTrue, sassFalse} from './boolean';
+export {SassColor} from './color';
+export {SassFunction} from './function';
+export {SassList, ListSeparator} from './list';
+export {SassMap} from './map';
+export {SassNumber} from './number';
+export {SassString} from './string';
+
+/**
+ * Sass's [`null` value](https://sass-lang.com/documentation/values/null).
+ *
+ * @category Custom Function
+ */
+export const sassNull: Value;
+
+/**
+ * The abstract base class of Sass's value types.
+ *
+ * This is passed to and returned by [[CustomFunction]]s, which are passed into
+ * the Sass implementation using [[Options.functions]].
+ *
+ * @category Custom Function
+ */
+export abstract class Value implements ValueObject {
+  protected constructor();
+
+  /**
+   * This value as a list.
+   *
+   * All SassScript values can be used as lists. Maps count as lists of pairs,
+   * and all other values count as single-value lists.
+   *
+   * @returns An immutable [[List]] from the [`immutable`
+   * package](https://immutable-js.com/).
+   */
+  get asList(): List<Value>;
+
+  /**
+   * Whether this value as a list has brackets.
+   *
+   * All SassScript values can be used as lists. Maps count as lists of pairs,
+   * and all other values count as single-value lists.
+   */
+  get hasBrackets(): boolean;
+
+  /**
+   * Whether the value counts as `true` in an `@if` statement and other
+   * contexts.
+   */
+  get isTruthy(): boolean;
+
+  /**
+   * Returns JavaScript's `null` value if this is [[sassNull]], and returns
+   * `this` otherwise.
+   */
+  get realNull(): null | Value;
+
+  /**
+   * The separator for this value as a list.
+   *
+   * All SassScript values can be used as lists. Maps count as lists of pairs,
+   * and all other values count as single-value lists.
+   */
+  get separator(): ListSeparator;
+
+  /**
+   * Converts `sassIndex` into a JavaScript-style index into the list returned
+   * by [[asList]].
+   *
+   * Sass indexes are one-based, while JavaScript indexes are zero-based. Sass
+   * indexes may also be negative in order to index from the end of the list.
+   *
+   * @param sassIndex - The Sass-style index into this as a list.
+   * @param name - The name of the function argument `sassIndex` came from
+   * (without the `$`) if it came from an argument. Used for error reporting.
+   * @throws `Error` If `sassIndex` isn't a number, if that number isn't an
+   * integer, or if that integer isn't a valid index for [[asList]].
+   */
+  sassIndexToListIndex(sassIndex: Value, name?: string): number;
+
+  /**
+   * Returns the value at index `index` in this value as a list, or `undefined`
+   * if `index` isn't valid for this list.
+   *
+   * All SassScript values can be used as lists. Maps count as lists of pairs,
+   * and all other values count as single-value lists.
+   *
+   * This is a shorthand for `this.asList.get(index)`, although it may be more
+   * efficient in some cases.
+   *
+   * **Heads up!** This method uses the same indexing conventions as the
+   * `immutable` package: unlike Sass the index of the first element is 0, but
+   * like Sass negative numbers index from the end of the list.
+   */
+  get(index: number): Value | undefined;
+
+  /**
+   * Throws if `this` isn't a [[SassBoolean]].
+   *
+   * **Heads up!** Functions should generally use [[isTruthy]] rather than
+   * requiring a literal boolean.
+   *
+   * @param name - The name of the function argument `this` came from (without
+   * the `$`) if it came from an argument. Used for error reporting.
+   */
+  assertBoolean(name?: string): SassBoolean;
+
+  /**
+   * Throws if `this` isn't a [[SassColor]].
+   *
+   * @param name - The name of the function argument `this` came from (without
+   * the `$`) if it came from an argument. Used for error reporting.
+   */
+  assertColor(name?: string): SassColor;
+
+  /**
+   * Throws if `this` isn't a [[SassFunction]].
+   *
+   * @param name - The name of the function argument `this` came from (without
+   * the `$`) if it came from an argument. Used for error reporting.
+   */
+  assertFunction(name?: string): SassFunction;
+
+  /**
+   * Throws if `this` isn't a [[SassMap]].
+   *
+   * @param name - The name of the function argument `this` came from (without
+   * the `$`) if it came from an argument. Used for error reporting.
+   */
+  assertMap(name?: string): SassMap;
+
+  /**
+   * Throws if `this` isn't a [[SassNumber]].
+   *
+   * @param name - The name of the function argument `this` came from (without
+   * the `$`) if it came from an argument. Used for error reporting.
+   */
+  assertNumber(name?: string): SassNumber;
+
+  /**
+   * Throws if `this` isn't a [[SassString]].
+   *
+   * @param name - The name of the function argument `this` came from (without
+   * the `$`) if it came from an argument. Used for error reporting.
+   */
+  assertString(name?: string): SassString;
+
+  /**
+   * Returns `this` as a map if it counts as one (empty lists count as empty
+   * maps) or `null` if it doesn't.
+   */
+  tryMap(): SassMap | null;
+
+  /** Returns whether `this` represents the same value as `other`. */
+  equals(other: Value): boolean;
+
+  /** Returns a hash code that can be used to store `this` in a hash map. */
+  hashCode(): number;
+
+  /** @hidden */
+  toString(): string;
+}

package/types/value/list.d.ts

@@ -0,0 +1,54 @@
+import {List} from 'immutable';
+
+import {Value} from './index';
+
+/**
+ * Possible separators used by Sass lists. The special separator `null` is only
+ * used for lists with fewer than two elements, and indicates that the separator
+ * has not yet been decided for this list.
+ *
+ * @category Custom Function
+ */
+export type ListSeparator = ',' | '/' | ' ' | null;
+
+/**
+ * Sass's [list type](https://sass-lang.com/documentation/values/lists).
+ *
+ * @category Custom Function
+ */
+export class SassList extends Value {
+  /**
+   * Creates a new list.
+   *
+   * @param contents - The contents of the list. This may be either a plain
+   * JavaScript array or an immutable [[List]] from the [`immutable`
+   * package](https://immutable-js.com/).
+   *
+   * @param options.separator - The separator to use between elements of this
+   * list. Defaults to `','`.
+   *
+   * @param options.brackets - Whether the list has square brackets. Defaults to
+   * `false`.
+   */
+  constructor(
+    contents: Value[] | List<Value>,
+    options?: {
+      separator?: ListSeparator;
+      brackets?: boolean;
+    }
+  );
+
+  /**
+   * Creates an empty list.
+   *
+   * @param options.separator - The separator to use between elements of this
+   * list. Defaults to `','`.
+   *
+   * @param options.brackets - Whether the list has square brackets. Defaults to
+   * `false`.
+   */
+  constructor(options?: {separator?: ListSeparator; brackets?: boolean});
+
+  /** @hidden */
+  get separator(): ListSeparator;
+}

package/types/value/map.d.ts

@@ -0,0 +1,41 @@
+import {OrderedMap} from 'immutable';
+
+import {SassList} from './list';
+import {Value} from './index';
+
+/**
+ * Sass's [map type](https://sass-lang.com/documentation/values/maps).
+ *
+ * @category Custom Function
+ */
+export class SassMap extends Value {
+  /**
+   * Creates a new map.
+   *
+   * @param contents - The contents of the map. This is an immutable
+   * [[OrderedMap]] from the [`immutable` package](https://immutable-js.com/).
+   * Defaults to an empty map.
+   */
+  constructor(contents?: OrderedMap<Value, Value>);
+
+  /**
+   * Returns the contents of this map as an immutable [[OrderedMap]] from the
+   * [`immutable` package](https://immutable-js.com/).
+   */
+  get contents(): OrderedMap<Value, Value>;
+
+  /**
+   * Returns the value associated with `key` in this map, or `undefined` if
+   * `key` isn't in the map.
+   *
+   * This is a shorthand for `this.contents.get(key)`, although it may be more
+   * efficient in some cases.
+   */
+  get(key: Value): Value | undefined;
+
+  /** Inherited from [[Value.get]]. */
+  get(index: number): SassList | undefined;
+
+  /** @hidden */
+  tryMap(): SassMap;
+}