| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757 |
- import {LegacyPluginThis} from './plugin_this';
- /**
- * A synchronous callback that implements a custom Sass function. This can be
- * passed to {@link LegacySharedOptions.functions} for either {@link render} or
- * {@link renderSync}.
- *
- * If this throws an error, Sass will treat that as the function failing with
- * that error message.
- *
- * ```js
- * const result = sass.renderSync({
- * file: 'style.scss',
- * functions: {
- * "sum($arg1, $arg2)": (arg1, arg2) => {
- * if (!(arg1 instanceof sass.types.Number)) {
- * throw new Error("$arg1: Expected a number");
- * } else if (!(arg2 instanceof sass.types.Number)) {
- * throw new Error("$arg2: Expected a number");
- * }
- * return new sass.types.Number(arg1.getValue() + arg2.getValue());
- * }
- * }
- * });
- * ```
- *
- * @param args - One argument for each argument that's declared in the signature
- * that's passed to {@link LegacySharedOptions.functions}. If the signature
- * [takes arbitrary
- * arguments](https://sass-lang.com/documentation/at-rules/function#taking-arbitrary-arguments),
- * they're passed as a single argument list in the last argument.
- *
- * @category Legacy
- * @deprecated This only works with the legacy {@link render} and {@link
- * renderSync} APIs. Use {@link CustomFunction} with {@link compile}, {@link
- * compileString}, {@link compileAsync}, and {@link compileStringAsync} instead.
- */
- export type LegacySyncFunction = (
- this: LegacyPluginThis,
- ...args: LegacyValue[]
- ) => LegacyValue;
- /**
- * An asynchronous callback that implements a custom Sass function. This can be
- * passed to {@link LegacySharedOptions.functions}, but only for {@link render}.
- *
- * An asynchronous function must return `undefined`. Its final argument will
- * always be a callback, which it should call with the result of the function
- * once it's done running.
- *
- * If this throws an error, Sass will treat that as the function failing with
- * that error message.
- *
- * ```js
- * sass.render({
- * file: 'style.scss',
- * functions: {
- * "sum($arg1, $arg2)": (arg1, arg2, done) => {
- * if (!(arg1 instanceof sass.types.Number)) {
- * throw new Error("$arg1: Expected a number");
- * } else if (!(arg2 instanceof sass.types.Number)) {
- * throw new Error("$arg2: Expected a number");
- * }
- * done(new sass.types.Number(arg1.getValue() + arg2.getValue()));
- * }
- * }
- * }, (result, error) => {
- * // ...
- * });
- * ```
- *
- * This is passed one argument for each argument that's declared in the
- * signature that's passed to {@link LegacySharedOptions.functions}. If the
- * signature [takes arbitrary
- * arguments](https://sass-lang.com/documentation/at-rules/function#taking-arbitrary-arguments),
- * they're passed as a single argument list in the last argument before the
- * callback.
- *
- * @category Legacy
- * @deprecated This only works with the legacy {@link render} and {@link
- * renderSync} APIs. Use {@link CustomFunction} with {@link compile}, {@link
- * compileString}, {@link compileAsync}, and {@link compileStringAsync} instead.
- */
- export type LegacyAsyncFunction =
- | ((this: LegacyPluginThis, done: (result: LegacyValue) => void) => void)
- | ((
- this: LegacyPluginThis,
- arg1: LegacyValue,
- done: LegacyAsyncFunctionDone
- ) => void)
- | ((
- this: LegacyPluginThis,
- arg1: LegacyValue,
- arg2: LegacyValue,
- done: LegacyAsyncFunctionDone
- ) => void)
- | ((
- this: LegacyPluginThis,
- arg1: LegacyValue,
- arg2: LegacyValue,
- arg3: LegacyValue,
- done: LegacyAsyncFunctionDone
- ) => void)
- | ((
- this: LegacyPluginThis,
- arg1: LegacyValue,
- arg2: LegacyValue,
- arg3: LegacyValue,
- arg4: LegacyValue,
- done: LegacyAsyncFunctionDone
- ) => void)
- | ((
- this: LegacyPluginThis,
- arg1: LegacyValue,
- arg2: LegacyValue,
- arg3: LegacyValue,
- arg4: LegacyValue,
- arg5: LegacyValue,
- done: LegacyAsyncFunctionDone
- ) => void)
- | ((
- this: LegacyPluginThis,
- arg1: LegacyValue,
- arg2: LegacyValue,
- arg3: LegacyValue,
- arg4: LegacyValue,
- arg5: LegacyValue,
- arg6: LegacyValue,
- done: LegacyAsyncFunctionDone
- ) => void)
- | ((
- this: LegacyPluginThis,
- ...args: [...LegacyValue[], LegacyAsyncFunctionDone]
- ) => void);
- /**
- * The function called by a {@link LegacyAsyncFunction} to indicate that it's
- * finished.
- *
- * @param result - If this is a {@link LegacyValue}, that indicates that the
- * function call completed successfully. If it's a {@link types.Error}, that
- * indicates that the function call failed.
- *
- * @category Legacy
- * @deprecated This only works with the legacy {@link render} and {@link
- * renderSync} APIs. Use {@link CustomFunction} with {@link compile}, {@link
- * compileString}, {@link compileAsync}, and {@link compileStringAsync} instead.
- */
- export type LegacyAsyncFunctionDone = (
- result: LegacyValue | types.Error
- ) => void;
- /**
- * A callback that implements a custom Sass function. For {@link renderSync},
- * this must be a {@link LegacySyncFunction} which returns its result directly;
- * for {@link render}, it may be either a {@link LegacySyncFunction} or a {@link
- * LegacyAsyncFunction} which calls a callback with its result.
- *
- * See {@link LegacySharedOptions.functions} for more details.
- *
- * @category Legacy
- * @deprecated This only works with the legacy {@link render} and {@link
- * renderSync} APIs. Use {@link CustomFunction} with {@link compile}, {@link
- * compileString}, {@link compileAsync}, and {@link compileStringAsync} instead.
- */
- export type LegacyFunction<sync extends 'sync' | 'async'> = sync extends 'async'
- ? LegacySyncFunction | LegacyAsyncFunction
- : LegacySyncFunction;
- /**
- * A type representing all the possible values that may be passed to or returned
- * from a {@link LegacyFunction}.
- *
- * @category Legacy
- * @deprecated This only works with the legacy {@link render} and {@link
- * renderSync} APIs. Use {@link Value} with {@link compile}, {@link
- * compileString}, {@link compileAsync}, and {@link compileStringAsync} instead.
- */
- export type LegacyValue =
- | types.Null
- | types.Number
- | types.String
- | types.Boolean
- | types.Color
- | types.List
- | types.Map;
- /**
- * A shorthand for `sass.types.Boolean.TRUE`.
- *
- * @category Legacy
- * @deprecated This only works with the legacy {@link render} and {@link
- * renderSync} APIs. Use {@link sassTrue} with {@link compile}, {@link
- * compileString}, {@link compileAsync}, and {@link compileStringAsync} instead.
- */
- export const TRUE: types.Boolean<true>;
- /**
- * A shorthand for `sass.types.Boolean.FALSE`.
- *
- * @category Legacy
- * @deprecated This only works with the legacy {@link render} and {@link
- * renderSync} APIs. Use {@link sassFalse} with {@link compile}, {@link
- * compileString}, {@link compileAsync}, and {@link compileStringAsync} instead.
- */
- export const FALSE: types.Boolean<false>;
- /**
- * A shorthand for `sass.types.Null.NULL`.
- *
- * @category Legacy
- * @deprecated This only works with the legacy {@link render} and {@link
- * renderSync} APIs. Use {@link sassNull} with {@link compile}, {@link
- * compileString}, {@link compileAsync}, and {@link compileStringAsync} instead.
- */
- export const NULL: types.Null;
- /**
- * The namespace for value types used in the legacy function API.
- *
- * @category Legacy
- * @deprecated This only works with the legacy {@link render} and {@link
- * renderSync} APIs. Use {@link Value} with {@link compile}, {@link
- * compileString}, {@link compileAsync}, and {@link compileStringAsync} instead.
- */
- export namespace types {
- /**
- * The class for Sass's singleton [`null`
- * value](https://sass-lang.com/documentation/values/null). The value itself
- * can be accessed through the {@link NULL} field.
- */
- export class Null {
- /** Sass's singleton `null` value. */
- static readonly NULL: Null;
- }
- /**
- * Sass's [number type](https://sass-lang.com/documentation/values/numbers).
- */
- export class Number {
- /**
- * @param value - The numeric value of the number.
- *
- * @param unit - If passed, the number's unit.
- *
- * Complex units can be represented as
- * `<unit>*<unit>*.../<unit>*<unit>*...`, with numerator units on the
- * left-hand side of the `/` and denominator units on the right. A number
- * with only numerator units may omit the `/` and the units after it, and a
- * number with only denominator units may be represented
- * with no units before the `/`.
- *
- * @example
- *
- * ```scss
- * new sass.types.Number(0.5); // == 0.5
- * new sass.types.Number(10, "px"); // == 10px
- * new sass.types.Number(10, "px*px"); // == 10px * 1px
- * new sass.types.Number(10, "px/s"); // == math.div(10px, 1s)
- * new sass.types.Number(10, "px*px/s*s"); // == 10px * math.div(math.div(1px, 1s), 1s)
- * ```
- */
- constructor(value: number, unit?: string);
- /**
- * Returns the value of the number, ignoring units.
- *
- * **Heads up!** This means that `96px` and `1in` will return different
- * values, even though they represent the same length.
- *
- * @example
- *
- * ```js
- * const number = new sass.types.Number(10, "px");
- * number.getValue(); // 10
- * ```
- */
- getValue(): number;
- /**
- * Destructively modifies this number by setting its numeric value to
- * `value`, independent of its units.
- *
- * @deprecated Use {@link constructor} instead.
- */
- setValue(value: number): void;
- /**
- * Returns a string representation of this number's units. Complex units are
- * returned in the same format that {@link constructor} accepts them.
- *
- * @example
- *
- * ```js
- * // number is `10px`.
- * number.getUnit(); // "px"
- *
- * // number is `math.div(10px, 1s)`.
- * number.getUnit(); // "px/s"
- * ```
- */
- getUnit(): string;
- /**
- * Destructively modifies this number by setting its units to `unit`,
- * independent of its numeric value. Complex units are specified in the same
- * format as {@link constructor}.
- *
- * @deprecated Use {@link constructor} instead.
- */
- setUnit(unit: string): void;
- }
- /**
- * Sass's [string type](https://sass-lang.com/documentation/values/strings).
- *
- * **Heads up!** This API currently provides no way of distinguishing between
- * a [quoted](https://sass-lang.com/documentation/values/strings#quoted) and
- * [unquoted](https://sass-lang.com/documentation/values/strings#unquoted)
- * string.
- */
- export class String {
- /**
- * Creates an unquoted string with the given contents.
- *
- * **Heads up!** This API currently provides no way of creating a
- * [quoted](https://sass-lang.com/documentation/values/strings#quoted)
- * string.
- */
- constructor(value: string);
- /**
- * Returns the contents of the string. If the string contains escapes,
- * those escapes are included literally if it’s
- * [unquoted](https://sass-lang.com/documentation/values/strings#unquoted),
- * while the values of the escapes are included if it’s
- * [quoted](https://sass-lang.com/documentation/values/strings#quoted).
- *
- * @example
- *
- * ```
- * // string is `Arial`.
- * string.getValue(); // "Arial"
- *
- * // string is `"Helvetica Neue"`.
- * string.getValue(); // "Helvetica Neue"
- *
- * // string is `\1F46D`.
- * string.getValue(); // "\\1F46D"
- *
- * // string is `"\1F46D"`.
- * string.getValue(); // "👭"
- * ```
- */
- getValue(): string;
- /**
- * Destructively modifies this string by setting its numeric value to
- * `value`.
- *
- * **Heads up!** Even if the string was originally quoted, this will cause
- * it to become unquoted.
- *
- * @deprecated Use {@link constructor} instead.
- */
- setValue(value: string): void;
- }
- /**
- * Sass's [boolean type](https://sass-lang.com/documentation/values/booleans).
- *
- * Custom functions should respect Sass’s notion of
- * [truthiness](https://sass-lang.com/documentation/at-rules/control/if#truthiness-and-falsiness)
- * by treating `false` and `null` as falsey and everything else as truthy.
- *
- * **Heads up!** Boolean values can't be constructed, they can only be
- * accessed through the {@link TRUE} and {@link FALSE} constants.
- */
- export class Boolean<T extends boolean = boolean> {
- /**
- * Returns `true` if this is Sass's `true` value and `false` if this is
- * Sass's `false` value.
- *
- * @example
- *
- * ```js
- * // boolean is `true`.
- * boolean.getValue(); // true
- * boolean === sass.types.Boolean.TRUE; // true
- *
- * // boolean is `false`.
- * boolean.getValue(); // false
- * boolean === sass.types.Boolean.FALSE; // true
- * ```
- */
- getValue(): T;
- /** Sass's `true` value. */
- static readonly TRUE: Boolean<true>;
- /** Sass's `false` value. */
- static readonly FALSE: Boolean<false>;
- }
- /**
- * Sass's [color type](https://sass-lang.com/documentation/values/colors).
- */
- export class Color {
- /**
- * Creates a new Sass color with the given red, green, blue, and alpha
- * channels. The red, green, and blue channels must be integers between 0
- * and 255 (inclusive), and alpha must be between 0 and 1 (inclusive).
- *
- * @example
- *
- * ```js
- * new sass.types.Color(107, 113, 127); // #6b717f
- * new sass.types.Color(0, 0, 0, 0); // rgba(0, 0, 0, 0)
- * ```
- */
- constructor(r: number, g: number, b: number, a?: number);
- /**
- * Creates a new Sass color with alpha, red, green, and blue channels taken
- * from respective two-byte chunks of a hexidecimal number.
- *
- * @example
- *
- * ```js
- * new sass.types.Color(0xff6b717f); // #6b717f
- * new sass.types.Color(0x00000000); // rgba(0, 0, 0, 0)
- * ```
- */
- constructor(argb: number);
- /**
- * Returns the red channel of the color as an integer from 0 to 255.
- *
- * @example
- *
- * ```js
- * // color is `#6b717f`.
- * color.getR(); // 107
- *
- * // color is `#b37399`.
- * color.getR(); // 179
- * ```
- */
- getR(): number;
- /**
- * Sets the red channel of the color. The value must be an integer between 0
- * and 255 (inclusive).
- *
- * @deprecated Use {@link constructor} instead.
- */
- setR(value: number): void;
- /**
- * Returns the green channel of the color as an integer from 0 to 255.
- *
- * @example
- *
- * ```js
- * // color is `#6b717f`.
- * color.getG(); // 113
- *
- * // color is `#b37399`.
- * color.getG(); // 115
- * ```
- */
- getG(): number;
- /**
- * Sets the green channel of the color. The value must be an integer between
- * 0 and 255 (inclusive).
- *
- * @deprecated Use {@link constructor} instead.
- */
- setG(value: number): void;
- /**
- * Returns the blue channel of the color as an integer from 0 to 255.
- *
- * @example
- *
- * ```js
- * // color is `#6b717f`.
- * color.getB(); // 127
- *
- * // color is `#b37399`.
- * color.getB(); // 153
- * ```
- */
- getB(): number;
- /**
- * Sets the blue channel of the color. The value must be an integer between
- * 0 and 255 (inclusive).
- *
- * @deprecated Use {@link constructor} instead.
- */
- setB(value: number): void;
- /**
- * Returns the alpha channel of the color as a number from 0 to 1.
- *
- * @example
- *
- * ```js
- * // color is `#6b717f`.
- * color.getA(); // 1
- *
- * // color is `transparent`.
- * color.getA(); // 0
- * ```
- */
- getA(): number;
- /**
- * Sets the alpha channel of the color. The value must be between 0 and 1
- * (inclusive).
- *
- * @deprecated Use {@link constructor} instead.
- */
- setA(value: number): void;
- }
- /**
- * Sass's [list type](https://sass-lang.com/documentation/values/lists).
- *
- * **Heads up!** This list type’s methods use 0-based indexing, even though
- * within Sass lists use 1-based indexing. These methods also don’t support
- * using negative numbers to index backwards from the end of the list.
- */
- export class List {
- /**
- * Creates a new Sass list.
- *
- * **Heads up!** The initial values of the list elements are undefined.
- * These elements must be set using {@link setValue} before accessing them
- * or passing the list back to Sass.
- *
- * @example
- *
- * ```js
- * const list = new sass.types.List(3);
- * list.setValue(0, new sass.types.Number(10, "px"));
- * list.setValue(1, new sass.types.Number(15, "px"));
- * list.setValue(2, new sass.types.Number(32, "px"));
- * list; // 10px, 15px, 32px
- * ```
- *
- * @param length - The number of (initially undefined) elements in the list.
- * @param commaSeparator - If `true`, the list is comma-separated; otherwise,
- * it's space-separated. Defaults to `true`.
- */
- constructor(length: number, commaSeparator?: boolean);
- /**
- * Returns the element at `index`, or `undefined` if that value hasn't yet
- * been set.
- *
- * @example
- *
- * ```js
- * // list is `10px, 15px, 32px`
- * list.getValue(0); // 10px
- * list.getValue(2); // 32px
- * ```
- *
- * @param index - A (0-based) index into this list.
- * @throws `Error` if `index` is less than 0 or greater than or equal to the
- * number of elements in this list.
- */
- getValue(index: number): LegacyValue | undefined;
- /**
- * Sets the element at `index` to `value`.
- *
- * @example
- *
- * ```js
- * // list is `10px, 15px, 32px`
- * list.setValue(1, new sass.types.Number(18, "px"));
- * list; // 10px, 18px, 32px
- * ```
- *
- * @param index - A (0-based) index into this list.
- * @throws `Error` if `index` is less than 0 or greater than or equal to the
- * number of elements in this list.
- */
- setValue(index: number, value: LegacyValue): void;
- /**
- * Returns `true` if this list is comma-separated and `false` otherwise.
- *
- * @example
- *
- * ```js
- * // list is `10px, 15px, 32px`
- * list.getSeparator(); // true
- *
- * // list is `1px solid`
- * list.getSeparator(); // false
- * ```
- */
- getSeparator(): boolean;
- /**
- * Sets whether the list is comma-separated.
- *
- * @param isComma - `true` to make the list comma-separated, `false` otherwise.
- */
- setSeparator(isComma: boolean): void;
- /**
- * Returns the number of elements in the list.
- *
- * @example
- *
- * ```js
- * // list is `10px, 15px, 32px`
- * list.getLength(); // 3
- *
- * // list is `1px solid`
- * list.getLength(); // 2
- * ```
- */
- getLength(): number;
- }
- /**
- * Sass's [map type](https://sass-lang.com/documentation/values/maps).
- *
- * **Heads up!** This map type is represented as a list of key-value pairs
- * rather than a mapping from keys to values. The only way to find the value
- * associated with a given key is to iterate through the map checking for that
- * key. Maps created through this API are still forbidden from having duplicate
- * keys.
- */
- export class Map {
- /**
- * Creates a new Sass map.
- *
- * **Heads up!** The initial keys and values of the map are undefined. They
- * must be set using {@link setKey} and {@link setValue} before accessing
- * them or passing the map back to Sass.
- *
- * @example
- *
- * ```js
- * const map = new sass.types.Map(2);
- * map.setKey(0, new sass.types.String("width"));
- * map.setValue(0, new sass.types.Number(300, "px"));
- * map.setKey(1, new sass.types.String("height"));
- * map.setValue(1, new sass.types.Number(100, "px"));
- * map; // (width: 300px, height: 100px)
- * ```
- *
- * @param length - The number of (initially undefined) key/value pairs in the map.
- */
- constructor(length: number);
- /**
- * Returns the value in the key/value pair at `index`.
- *
- * @example
- *
- * ```js
- * // map is `(width: 300px, height: 100px)`
- * map.getValue(0); // 300px
- * map.getValue(1); // 100px
- * ```
- *
- * @param index - A (0-based) index of a key/value pair in this map.
- * @throws `Error` if `index` is less than 0 or greater than or equal to the
- * number of pairs in this map.
- */
- getValue(index: number): LegacyValue;
- /**
- * Sets the value in the key/value pair at `index` to `value`.
- *
- * @example
- *
- * ```js
- * // map is `("light": 200, "medium": 400, "bold": 600)`
- * map.setValue(1, new sass.types.Number(300));
- * map; // ("light": 200, "medium": 300, "bold": 600)
- * ```
- *
- * @param index - A (0-based) index of a key/value pair in this map.
- * @throws `Error` if `index` is less than 0 or greater than or equal to the
- * number of pairs in this map.
- */
- setValue(index: number, value: LegacyValue): void;
- /**
- * Returns the key in the key/value pair at `index`.
- *
- * @example
- *
- * ```js
- * // map is `(width: 300px, height: 100px)`
- * map.getKey(0); // width
- * map.getKey(1); // height
- * ```
- *
- * @param index - A (0-based) index of a key/value pair in this map.
- * @throws `Error` if `index` is less than 0 or greater than or equal to the
- * number of pairs in this map.
- */
- getKey(index: number): LegacyValue;
- /**
- * Sets the value in the key/value pair at `index` to `value`.
- *
- * @example
- *
- * ```js
- * // map is `("light": 200, "medium": 400, "bold": 600)`
- * map.setValue(1, new sass.types.String("lighter"));
- * map; // ("lighter": 200, "medium": 300, "bold": 600)
- * ```
- *
- * @param index - A (0-based) index of a key/value pair in this map.
- * @throws `Error` if `index` is less than 0 or greater than or equal to the
- * number of pairs in this map.
- */
- setKey(index: number, key: LegacyValue): void;
- /**
- * Returns the number of key/value pairs in this map.
- *
- * @example
- *
- * ```js
- * // map is `("light": 200, "medium": 400, "bold": 600)`
- * map.getLength(); // 3
- *
- * // map is `(width: 300px, height: 100px)`
- * map.getLength(); // 2
- * ```
- */
- getLength(): number;
- }
- /**
- * An error that can be returned from a Sass function to signal that it
- * encountered an error. This is the only way to signal an error
- * asynchronously from a {@link LegacyAsyncFunction}.
- */
- export class Error {
- constructor(message: string);
- }
- }
|