@sass/types 1.93.2

package/types/value/index.d.ts

@@ -0,0 +1,219 @@
+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';
+import {SassMap} from './map';
+import {SassMixin} from './mixin';
+import {SassNumber} from './number';
+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,
+  ColorSpaceHsl,
+  ChannelNameHsl,
+  ColorSpaceHwb,
+  ChannelNameHwb,
+  ColorSpaceLab,
+  ChannelNameLab,
+  ColorSpaceLch,
+  ChannelNameLch,
+  ColorSpaceRgb,
+  ChannelNameRgb,
+  ColorSpaceXyz,
+  ChannelNameXyz,
+  ChannelName,
+  GamutMapMethod,
+  KnownColorSpace,
+  PolarColorSpace,
+  RectangularColorSpace,
+  HueInterpolationMethod,
+} 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';
+
+/**
+ * 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 {@link CustomFunction}s, which are passed
+ * into the Sass implementation using {@link 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 {@link 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 {@link 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 {@link 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 {@link 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 {@link SassBoolean}.
+   *
+   * **Heads up!** Functions should generally use {@link 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 {@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}.
+   *
+   * @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 {@link 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 {@link 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 {@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}.
+   *
+   * @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 {@link 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 {@link 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 {@link 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 {@link Value.get}. */
+  get(index: number): SassList | undefined;
+
+  /** @hidden */
+  tryMap(): SassMap;
+}

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();
+}

package/types/value/number.d.ts

@@ -0,0 +1,305 @@
+import {List} from 'immutable';
+
+import {Value} from './index';
+
+/**
+ * Sass's [number type](https://sass-lang.com/documentation/values/numbers).
+ *
+ * @category Custom Function
+ */
+export class SassNumber extends Value {
+  /**
+   * Creates a new number with more complex units than just a single numerator.
+   *
+   * Upon construction, any compatible numerator and denominator units are
+   * simplified away according to the conversion factor between them.
+   *
+   * @param value - The number's numeric value.
+   *
+   * @param unit - If this is a string, it's used as the single numerator unit
+   * for the number.
+   *
+   * @param unit.numeratorUnits - If passed, these are the numerator units to
+   * use for the number. This may be either a plain JavaScript array or an
+   * immutable {@link List} from the [`immutable`
+   * package](https://immutable-js.com/).
+   *
+   * @param unit.denominatorUnits - If passed, these are the denominator units
+   * to use for the number. This may be either a plain JavaScript array or an
+   * immutable {@link List} from the [`immutable`
+   * package](https://immutable-js.com/).
+   */
+  constructor(
+    value: number,
+    unit?:
+      | string
+      | {
+          numeratorUnits?: string[] | List<string>;
+          denominatorUnits?: string[] | List<string>;
+        }
+  );
+
+  /** This number's numeric value. */
+  get value(): number;
+
+  /** Whether {@link value} is an integer according to Sass's equality logic. */
+  get isInt(): boolean;
+
+  /**
+   * If {@link value} is an integer according to {@link isInt}, returns {@link
+   * value} rounded to that integer. If it's not an integer, returns `null`.
+   */
+  get asInt(): number | null;
+
+  /**
+   * This number's numerator units as an immutable {@link List} from the
+   * [`immutable` package](https://immutable-js.com/).
+   */
+  get numeratorUnits(): List<string>;
+
+  /**
+   * This number's denominator units as an immutable {@link List} from the
+   * [`immutable` package](https://immutable-js.com/).
+   */
+  get denominatorUnits(): List<string>;
+
+  /** Whether this number has any numerator or denominator units. */
+  get hasUnits(): boolean;
+
+  /**
+   * If {@link value} is an integer according to {@link isInt}, returns it
+   * rounded to that integer. Otherwise, throws an error.
+   *
+   * @param name - The name of the function argument `this` came from (without
+   * the `$`) if it came from an argument. Used for error reporting.
+   */
+  assertInt(name?: string): number;
+
+  /**
+   * Returns {@link value} if it's within `min` and `max`. If {@link value} is
+   * equal to `min` or `max` according to Sass's equality, returns `min` or
+   * `max` respectively. Otherwise, throws an error.
+   *
+   * @param name - The name of the function argument `this` came from (without
+   * the `$`) if it came from an argument. Used for error reporting.
+   */
+  assertInRange(min: number, max: number, name?: string): number;
+
+  /**
+   * If this number has no units, returns it. Otherwise, throws an error.
+   *
+   * @param name - The name of the function argument `this` came from (without
+   * the `$`) if it came from an argument. Used for error reporting.
+   */
+  assertNoUnits(name?: string): SassNumber;
+
+  /**
+   * If this number has `unit` as its only unit (and as a numerator), returns
+   * this number. Otherwise, throws an error.
+   *
+   * @param name - The name of the function argument `this` came from (without
+   * the `$`) if it came from an argument. Used for error reporting.
+   */
+  assertUnit(unit: string, name?: string): SassNumber;
+
+  /** Whether this number has `unit` as its only unit (and as a numerator). */
+  hasUnit(unit: string): boolean;
+
+  /**
+   * Whether this has exactly one numerator unit, and that unit is compatible
+   * with `unit`.
+   */
+  compatibleWithUnit(unit: string): boolean;
+
+  /**
+   * Returns a copy of this number, converted to the units represented by
+   * `newNumerators` and `newDenominators`.
+   *
+   * @throws `Error` if this number's units are incompatible with
+   * `newNumerators` and `newDenominators`; or if this number is unitless and
+   * either `newNumerators` or `newDenominators` are not empty, or vice-versa.
+   *
+   * @param newNumerators - The numerator units to convert this number to. This
+   * may be either a plain JavaScript array or an immutable {@link List} from
+   * the [`immutable` package](https://immutable-js.com/).
+   *
+   * @param newDenominators - The denominator units to convert this number to.
+   * This may be either a plain JavaScript array or an immutable {@link List}
+   * from the [`immutable` package](https://immutable-js.com/).
+   *
+   * @param name - The name of the function argument `this` came from (without
+   * the `$`) if it came from an argument. Used for error reporting.
+   */
+  convert(
+    newNumerators: string[] | List<string>,
+    newDenominators: string[] | List<string>,
+    name?: string
+  ): SassNumber;
+
+  /**
+   * Returns a copy of this number, converted to the same units as `other`.
+   *
+   * @throws `Error` if this number's units are incompatible with `other`'s
+   * units, or if either number is unitless but the other is not.
+   *
+   * @param name - The name of the function argument `this` came from (without
+   * the `$`) if it came from an argument. Used for error reporting.
+   *
+   * @param otherName - The name of the function argument `other` came from
+   * (without the `$`) if it came from an argument. Used for error reporting.
+   */
+  convertToMatch(
+    other: SassNumber,
+    name?: string,
+    otherName?: string
+  ): SassNumber;
+
+  /**
+   * Returns {@link value}, converted to the units represented by
+   * `newNumerators` and `newDenominators`.
+   *
+   * @throws `Error` if this number's units are incompatible with
+   * `newNumerators` and `newDenominators`; or if this number is unitless and
+   * either `newNumerators` or `newDenominators` are not empty, or vice-versa.
+   *
+   * @param newNumerators - The numerator units to convert {@link value} to.
+   * This may be either a plain JavaScript array or an immutable {@link List}
+   * from the [`immutable` package](https://immutable-js.com/).
+   *
+   * @param newDenominators - The denominator units to convert {@link value} to.
+   * This may be either a plain JavaScript array or an immutable {@link List}
+   * from the [`immutable` package](https://immutable-js.com/).
+   *
+   * @param name - The name of the function argument `this` came from (without
+   * the `$`) if it came from an argument. Used for error reporting.
+   */
+  convertValue(
+    newNumerators: string[] | List<string>,
+    newDenominators: string[] | List<string>,
+    name?: string
+  ): number;
+
+  /**
+   * Returns {@link value}, converted to the same units as `other`.
+   *
+   * @throws `Error` if this number's units are incompatible with `other`'s
+   * units, or if either number is unitless but the other is not.
+   *
+   * @param name - The name of the function argument `this` came from (without
+   * the `$`) if it came from an argument. Used for error reporting.
+   *
+   * @param otherName - The name of the function argument `other` came from
+   * (without the `$`) if it came from an argument. Used for error reporting.
+   */
+  convertValueToMatch(
+    other: SassNumber,
+    name?: string,
+    otherName?: string
+  ): number;
+
+  /**
+   * Returns a copy of this number, converted to the units represented by
+   * `newNumerators` and `newDenominators`.
+   *
+   * Unlike {@link convert} this does *not* throw an error if this number is
+   * unitless and either `newNumerators` or `newDenominators` are not empty, or
+   * vice-versa. Instead, it treats all unitless numbers as convertible to and
+   * from all units without changing the value.
+   *
+   * @throws `Error` if this number's units are incompatible with
+   * `newNumerators` and `newDenominators`.
+   *
+   * @param newNumerators - The numerator units to convert this number to. This
+   * may be either a plain JavaScript array or an immutable {@link List} from
+   * the [`immutable` package](https://immutable-js.com/).
+   *
+   * @param newDenominators - The denominator units to convert this number to.
+   * This may be either a plain JavaScript array or an immutable {@link List}
+   * from the [`immutable` package](https://immutable-js.com/).
+   *
+   * @param name - The name of the function argument `this` came from (without
+   * the `$`) if it came from an argument. Used for error reporting.
+   */
+  coerce(
+    newNumerators: string[] | List<string>,
+    newDenominators: string[] | List<string>,
+    name?: string
+  ): SassNumber;
+
+  /**
+   * Returns a copy of this number, converted to the units represented by
+   * `newNumerators` and `newDenominators`.
+   *
+   * Unlike {@link convertToMatch} this does *not* throw an error if this number
+   * is unitless and either `newNumerators` or `newDenominators` are not empty,
+   * or vice-versa. Instead, it treats all unitless numbers as convertible to
+   * and from all units without changing the value.
+   *
+   * @throws `Error` if this number's units are incompatible with `other`'s
+   * units.
+   *
+   * @param name - The name of the function argument `this` came from (without
+   * the `$`) if it came from an argument. Used for error reporting.
+   *
+   * @param otherName - The name of the function argument `other` came from
+   * (without the `$`) if it came from an argument. Used for error reporting.
+   */
+  coerceToMatch(
+    other: SassNumber,
+    name?: string,
+    otherName?: string
+  ): SassNumber;
+
+  /**
+   * Returns {@link value}, converted to the units represented by
+   * `newNumerators` and `newDenominators`.
+   *
+   * Unlike {@link convertValue} this does *not* throw an error if this number
+   * is unitless and either `newNumerators` or `newDenominators` are not empty,
+   * or vice-versa. Instead, it treats all unitless numbers as convertible to
+   * and from all units without changing the value.
+   *
+   * @throws `Error` if this number's units are incompatible with
+   * `newNumerators` and `newDenominators`.
+   *
+   * @param newNumerators - The numerator units to convert {@link value} to.
+   * This may be either a plain JavaScript array or an immutable {@link List}
+   * from the [`immutable` package](https://immutable-js.com/).
+   *
+   * @param newDenominators - The denominator units to convert {@link value} to.
+   * This may be either a plain JavaScript array or an immutable {@link List}
+   * from the [`immutable` package](https://immutable-js.com/).
+   *
+   * @param name - The name of the function argument `this` came from (without
+   * the `$`) if it came from an argument. Used for error reporting.
+   */
+  coerceValue(
+    newNumerators: string[] | List<string>,
+    newDenominators: string[] | List<string>,
+    name?: string
+  ): number;
+
+  /**
+   * Returns {@link value}, converted to the units represented by
+   * `newNumerators` and `newDenominators`.
+   *
+   * Unlike {@link convertValueToMatch} this does *not* throw an error if this
+   * number is unitless and either `newNumerators` or `newDenominators` are not
+   * empty, or vice-versa. Instead, it treats all unitless numbers as
+   * convertible to and from all units without changing the value.
+   *
+   * @throws `Error` if this number's units are incompatible with `other`'s
+   * units.
+   *
+   * @param name - The name of the function argument `this` came from (without
+   * the `$`) if it came from an argument. Used for error reporting.
+   *
+   * @param otherName - The name of the function argument `other` came from
+   * (without the `$`) if it came from an argument. Used for error reporting.
+   */
+  coerceValueToMatch(
+    other: SassNumber,
+    name?: string,
+    otherName?: string
+  ): number;
+}