@reykjavik/webtools 0.1.31 → 0.1.33

package/errorhandling.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Result = exports.asError = exports.ErrorFromPayload = void 0;
+/**
+ * Error subclass for thrown values that got cought and turned into an actual
+ * Error, with the thrown value as the `payload` property.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#aserror
+ */
+class ErrorFromPayload extends Error {
+    constructor(payload) {
+        if (process.env.NODE_ENV !== 'production' && payload instanceof Error) {
+            throw new Error('Do not pass an Error instance as payload, just use it directly');
+        }
+        const message = (payload != null ? String(payload) : '') || 'Threw a falsy/empty value';
+        super(message);
+        this.name = 'ErrorFromPayload';
+        this.payload = payload;
+    }
+}
+exports.ErrorFromPayload = ErrorFromPayload;
+/**v
+ * Guarantees that a caught (`catch (e)`) value of `unknown` type,
+ * is indeed an `Error` instance.
+ *
+ *If the input is an `Error` instance, it is returned as-is. If the input is
+ * something else it is wrapped in a new `ErrorFromPayload` instance, and the
+ * original value is stored in a `payload`
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#aserror
+ */
+const asError = (maybeError) => {
+    if (maybeError instanceof Error) {
+        return maybeError;
+    }
+    return new ErrorFromPayload(maybeError);
+};
+exports.asError = asError;
+const Success = (result) => {
+    const tuple = [undefined, result];
+    tuple.result = result;
+    return tuple;
+};
+const Fail = (e) => {
+    const tuple = [(0, exports.asError)(e)];
+    tuple.error = tuple[0];
+    return tuple;
+};
+function catch_(something) {
+    if (something instanceof Promise) {
+        return something.then((result) => Success(result), (e) => Fail(e));
+    }
+    try {
+        return Success(something());
+    }
+    catch (e) {
+        return Fail(e);
+    }
+}
+/**
+ * Singleton object with small methods for creating, mapping or handling
+ * `ResultTupleObj` instances.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#result-singleton
+ */
+exports.Result = {
+    /**
+     * Factory for creating a successful `Result.TupleObj`.
+     *
+     * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#resultsuccess
+     */
+    Success,
+    /**
+     * Factory for creating a failed `Result.TupleObj`.
+     *
+     * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#resultsfail
+     */
+    Fail,
+    // NOTE: The JSDoc must be placed above the `catch_` function above.
+    catch: catch_,
+    /**
+     * Helper to map a `ResultTuple`-like object to a new `ResultTupleObj`
+     * object, applying a transformation function to the result, but retaining
+     * the error as-is.
+     *
+     * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#resulmap
+     */
+    map: (result, mapFn) => {
+        const [error, resultValue] = result;
+        if (error) {
+            return Fail(error);
+        }
+        return Success(mapFn(resultValue));
+    },
+    /**
+     * Unwraps a discriminated [error, result] `Result.Tuple`-like object
+     * and throws if there's an error, but returns the result otherwise.
+     *
+     * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#resulthrow
+     */
+    throw: (result) => {
+        if (result[0]) {
+            throw result[0];
+        }
+        return result[1];
+    },
+};

package/esm/errorhandling.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Error subclass for thrown values that got cought and turned into an actual
+ * Error, with the thrown value as the `payload` property.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#aserror
+ */
+export declare class ErrorFromPayload extends Error {
+    payload?: unknown;
+    constructor(payload: unknown);
+    name: string;
+}
+/**v
+ * Guarantees that a caught (`catch (e)`) value of `unknown` type,
+ * is indeed an `Error` instance.
+ *
+ *If the input is an `Error` instance, it is returned as-is. If the input is
+ * something else it is wrapped in a new `ErrorFromPayload` instance, and the
+ * original value is stored in a `payload`
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#aserror
+ */
+export declare const asError: (maybeError: unknown) => ErrorFromPayload;
+type SuccessResult<T> = [error: undefined, result: T] & {
+    error?: undefined;
+    result: T;
+};
+type FailResult<E extends Error> = [error: E] & {
+    error: E;
+    result?: undefined;
+};
+/**
+ * Simple bare-bones discriminated tuple type for a [error, result] pair.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#type-resulttuple
+ */
+export type ResultTuple<T, E extends Error = Error> = [error: undefined, result: T] | [error: E];
+/**
+ * Discriminated tuple type for a `[error, result]` pair (same as `ResultTuple`)
+ * but with named properties `error` and `result` attached for dev convenience.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#type-resulttupleobj
+ */
+export type ResultTupleObj<T, E extends Error = Error> = SuccessResult<T> | FailResult<E>;
+/**
+ * Error handling utility that wraps a promise or a callback function.
+ *
+ * Catches errors and returns a `ResultTupleObj` — a nice discriminated
+ * `[error, results]` tuple with the `result` and `error` also attached as
+ * named properties.
+ *
+ * Works on both promises and sync callback functions.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#resultcatch
+ */
+declare function catch_<T, E extends Error = ErrorFromPayload>(promise: Promise<T>): Promise<ResultTupleObj<T, E>>;
+declare function catch_<T, E extends Error = ErrorFromPayload>(callback: () => T): ResultTupleObj<T, E>;
+/**
+ * Singleton object with small methods for creating, mapping or handling
+ * `ResultTupleObj` instances.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#result-singleton
+ */
+export declare const Result: {
+    /**
+     * Factory for creating a successful `Result.TupleObj`.
+     *
+     * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#resultsuccess
+     */
+    Success: <T>(result: T) => SuccessResult<T>;
+    /**
+     * Factory for creating a failed `Result.TupleObj`.
+     *
+     * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#resultsfail
+     */
+    Fail: <E extends Error = Error>(e: unknown) => FailResult<E>;
+    catch: typeof catch_;
+    /**
+     * Helper to map a `ResultTuple`-like object to a new `ResultTupleObj`
+     * object, applying a transformation function to the result, but retaining
+     * the error as-is.
+     *
+     * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#resulmap
+     */
+    map: <T_1, T2, E_1 extends Error>(result: ResultTuple<T_1, E_1>, mapFn: (resultValue: T_1) => T2) => ResultTupleObj<T2, E_1>;
+    /**
+     * Unwraps a discriminated [error, result] `Result.Tuple`-like object
+     * and throws if there's an error, but returns the result otherwise.
+     *
+     * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#resulthrow
+     */
+    throw: <T_2>(result: ResultTuple<T_2, Error>) => T_2;
+};
+export declare namespace Result {
+    type Tuple<T, E extends Error = Error> = ResultTuple<T, E>;
+    type TupleObj<T, E extends Error = Error> = ResultTupleObj<T, E>;
+    type SuccessObj<T> = SuccessResult<T>;
+    type FailObj<E extends Error> = FailResult<E>;
+}
+export {};

package/esm/errorhandling.js

@@ -0,0 +1,102 @@
+/**
+ * Error subclass for thrown values that got cought and turned into an actual
+ * Error, with the thrown value as the `payload` property.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#aserror
+ */
+export class ErrorFromPayload extends Error {
+    constructor(payload) {
+        if (process.env.NODE_ENV !== 'production' && payload instanceof Error) {
+            throw new Error('Do not pass an Error instance as payload, just use it directly');
+        }
+        const message = (payload != null ? String(payload) : '') || 'Threw a falsy/empty value';
+        super(message);
+        this.name = 'ErrorFromPayload';
+        this.payload = payload;
+    }
+}
+/**v
+ * Guarantees that a caught (`catch (e)`) value of `unknown` type,
+ * is indeed an `Error` instance.
+ *
+ *If the input is an `Error` instance, it is returned as-is. If the input is
+ * something else it is wrapped in a new `ErrorFromPayload` instance, and the
+ * original value is stored in a `payload`
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#aserror
+ */
+export const asError = (maybeError) => {
+    if (maybeError instanceof Error) {
+        return maybeError;
+    }
+    return new ErrorFromPayload(maybeError);
+};
+const Success = (result) => {
+    const tuple = [undefined, result];
+    tuple.result = result;
+    return tuple;
+};
+const Fail = (e) => {
+    const tuple = [asError(e)];
+    tuple.error = tuple[0];
+    return tuple;
+};
+function catch_(something) {
+    if (something instanceof Promise) {
+        return something.then((result) => Success(result), (e) => Fail(e));
+    }
+    try {
+        return Success(something());
+    }
+    catch (e) {
+        return Fail(e);
+    }
+}
+/**
+ * Singleton object with small methods for creating, mapping or handling
+ * `ResultTupleObj` instances.
+ *
+ * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#result-singleton
+ */
+export const Result = {
+    /**
+     * Factory for creating a successful `Result.TupleObj`.
+     *
+     * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#resultsuccess
+     */
+    Success,
+    /**
+     * Factory for creating a failed `Result.TupleObj`.
+     *
+     * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#resultsfail
+     */
+    Fail,
+    // NOTE: The JSDoc must be placed above the `catch_` function above.
+    catch: catch_,
+    /**
+     * Helper to map a `ResultTuple`-like object to a new `ResultTupleObj`
+     * object, applying a transformation function to the result, but retaining
+     * the error as-is.
+     *
+     * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#resulmap
+     */
+    map: (result, mapFn) => {
+        const [error, resultValue] = result;
+        if (error) {
+            return Fail(error);
+        }
+        return Success(mapFn(resultValue));
+    },
+    /**
+     * Unwraps a discriminated [error, result] `Result.Tuple`-like object
+     * and throws if there's an error, but returns the result otherwise.
+     *
+     * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#resulthrow
+     */
+    throw: (result) => {
+        if (result[0]) {
+            throw result[0];
+        }
+        return result[1];
+    },
+};

package/esm/index.d.ts

@@ -2,6 +2,7 @@
 /// <reference path="./http.d.ts" />
 /// <reference path="./async.d.ts" />
 /// <reference path="./fixIcelandicLocale.d.ts" />
+/// <reference path="./errorhandling.d.ts" />
 /// <reference path="./remix/http.d.ts" />
 /// <reference path="./SiteImprove.d.tsx" />
 /// <reference path="./CookieHubConsent.d.tsx" />

package/esm/vanillaExtract.d.ts

@@ -20,27 +20,131 @@ export declare const vanillaProps: (css: string) => GlobalStyleRule;
 export declare function vanillaClass(css: string | ((className: string) => string)): string;
 export declare function vanillaClass(debugId: string, css: string | ((className: string) => string)): string;
 /**
+ * @deprecated  (Will be removed in v0.2)
+ *
  * Replaces all `&` tokens with the given selector string, in a direct
  * (read. "dumb") way. It's mainly useful when used with style-mixins, etc.
  *
- * NOTE: It does NOT support deeply nested blocks, or anything so fancy.
- * It will also replace "&" characters inside values, comments, etc.
+ * **NOTE:** `vanillaNest` does NOT support deeply nested blocks, or anything
+ * so fancy. It will also replace `&` characters inside values, comments, etc.
  * If you need something more sophisticated, use a custom `postcss` config.
  *
+ * ```ts
+ * // someCssHelper.ts
+ * import { vanillaNest } from '@reykjavik/webtools/vanillaExtract';
+ *
+ * export const hoverGlow = (
+ *   ampSelector: string,
+ *   glowiness?: 'normal' | 'insane'
+ * ) =>
+ *   vanillaNest(
+ *     ampSelector,
+ *     `
+ *     &:hover {
+ *       box-shadow: 0 0 20px 5px ${
+ *         glowiness === 'insane' ? 'hotpink' : 'salmon'
+ *       };
+ *     }
+ *   `
+ *   );
+ *
+ * // ...then, somewhere else in a *.css.ts file:
+ *
+ * import { hoverGlow } from '~/someCssHelper.js';
+ * import { vanillaGlobal } from '@reykjavik/webtools/vanillaExtract';
+ *
+ * vanillaGlobal(`
+ *   .MyComponent {
+ *     border: 1px solid #ccc;
+ *     padding: 1em;
+ *   }
+ *   ${hoverGlow('.MyComponent')}
+ *
+ *   .MyOtherComponent {
+ *     border: 1px solid #ccc;
+ *     padding: 1em;
+ *   }
+ *   ${hoverGlow('.MyOtherComponent', 'insane')}
+ * `);
+ * ```
  *
- * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#vanillanest
+ * (This low-level utility function is used internally by `vanillaClassNested`.
  */
 export declare const vanillaNest: (ampSelector: string, css: string) => string;
 /**
+ * @deprecated  (Will be removed in v0.2)
+ *
  * Returns a scoped cssClassName styled with free-form CSS.
  *
  * It also automatically replaces all `&`-tokens with
  * the selector for the auto-generated class-name.
  *
- * NOTE: All "bare" (un-nested) style properties must come first,
+ * ```ts
+ * // someFile.css.ts
+ * import { vanillaClassNested } from '@reykjavik/webtools/vanillaExtract';
+ *
+ * export const myClass = vanillaClassNested(`
+ *   background-color: #ccc;
+ *   padding: .5em 1em;
+ *
+ *   /* Nested blocks begin: *​​/
+ *   &:hover {
+ *     background-color: #666;
+ *     color: white;
+ *   }
+ *   & > strong {
+ *     color: maroon;
+ *   }
+ *   html[data-color-theme="unicorn"] & {
+ *     background-color: pink;
+ *   }
+ * `);
+ * ```
+ *
+ * **NOTE:** All "bare" (un-nested) style properties **must come first**,
  * before any nested blocks.
  *
- * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#vanillaclassnested
+ * **NOTE 2:** `vanillaClassNested` does NOT support deeply nested blocks, or
+ * anything so fancy. It will also replace `&` characters inside values,
+ * comments, etc. If you need something more sophisticated, use a custom
+ * `postcss` config.
  */
 export declare function vanillaClassNested(css: string): string;
+/** @deprecated  (Will be removed in v0.2) */
+/**
+ * Returns a scoped cssClassName styled with free-form CSS.
+ *
+ * It also automatically replaces all `&`-tokens with
+ * the selector for the auto-generated class-name.
+ *
+ * ```ts
+ * // someFile.css.ts
+ * import { vanillaClassNested } from '@reykjavik/webtools/vanillaExtract';
+ *
+ * export const myClass = vanillaClassNested(`
+ *   background-color: #ccc;
+ *   padding: .5em 1em;
+ *
+ *   /* Nested blocks begin: *​​/
+ *   &:hover {
+ *     background-color: #666;
+ *     color: white;
+ *   }
+ *   & > strong {
+ *     color: maroon;
+ *   }
+ *   html[data-color-theme="unicorn"] & {
+ *     background-color: pink;
+ *   }
+ * `);
+ * ```
+ *
+ * **NOTE:** All "bare" (un-nested) style properties **must come first**,
+ * before any nested blocks.
+ *
+ * **NOTE 2:** `vanillaClassNested` does NOT support deeply nested blocks, or
+ * anything so fancy. It will also replace `&` characters inside values,
+ * comments, etc. If you need something more sophisticated, use a custom
+ * `postcss` config.
+ */
 export declare function vanillaClassNested(debugId: string, css: string): string;

package/esm/vanillaExtract.js

@@ -25,15 +25,55 @@ export function vanillaClass(cssOrDebugId, css) {
 }
 // ---------------------------------------------------------------------------
 /**
+ * @deprecated  (Will be removed in v0.2)
+ *
  * Replaces all `&` tokens with the given selector string, in a direct
  * (read. "dumb") way. It's mainly useful when used with style-mixins, etc.
  *
- * NOTE: It does NOT support deeply nested blocks, or anything so fancy.
- * It will also replace "&" characters inside values, comments, etc.
+ * **NOTE:** `vanillaNest` does NOT support deeply nested blocks, or anything
+ * so fancy. It will also replace `&` characters inside values, comments, etc.
  * If you need something more sophisticated, use a custom `postcss` config.
  *
+ * ```ts
+ * // someCssHelper.ts
+ * import { vanillaNest } from '@reykjavik/webtools/vanillaExtract';
+ *
+ * export const hoverGlow = (
+ *   ampSelector: string,
+ *   glowiness?: 'normal' | 'insane'
+ * ) =>
+ *   vanillaNest(
+ *     ampSelector,
+ *     `
+ *     &:hover {
+ *       box-shadow: 0 0 20px 5px ${
+ *         glowiness === 'insane' ? 'hotpink' : 'salmon'
+ *       };
+ *     }
+ *   `
+ *   );
+ *
+ * // ...then, somewhere else in a *.css.ts file:
+ *
+ * import { hoverGlow } from '~/someCssHelper.js';
+ * import { vanillaGlobal } from '@reykjavik/webtools/vanillaExtract';
+ *
+ * vanillaGlobal(`
+ *   .MyComponent {
+ *     border: 1px solid #ccc;
+ *     padding: 1em;
+ *   }
+ *   ${hoverGlow('.MyComponent')}
+ *
+ *   .MyOtherComponent {
+ *     border: 1px solid #ccc;
+ *     padding: 1em;
+ *   }
+ *   ${hoverGlow('.MyOtherComponent', 'insane')}
+ * `);
+ * ```
  *
- * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#vanillanest
+ * (This low-level utility function is used internally by `vanillaClassNested`.
  */
 export const vanillaNest = (ampSelector, css) => css.replace(/&/g, ampSelector);
 export function vanillaClassNested(cssOrDebugId, css) {

package/index.d.ts

@@ -2,6 +2,7 @@
 /// <reference path="./http.d.ts" />
 /// <reference path="./async.d.ts" />
 /// <reference path="./fixIcelandicLocale.d.ts" />
+/// <reference path="./errorhandling.d.ts" />
 /// <reference path="./remix/http.d.ts" />
 /// <reference path="./SiteImprove.d.tsx" />
 /// <reference path="./CookieHubConsent.d.tsx" />

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@reykjavik/webtools",
-	"version": "0.1.31",
+	"version": "0.1.33",
 	"description": "Misc. JS/TS helpers used by Reykjavík City's web dev teams.",
 	"main": "index.js",
 	"repository": "ssh://git@github.com:reykjavikcity/webtools.git",
@@ -64,6 +64,10 @@
 			"import": "./esm/fixIcelandicLocale.js",
 			"require": "./fixIcelandicLocale.js"
 		},
+		"./errorhandling": {
+			"import": "./esm/errorhandling.js",
+			"require": "./errorhandling.js"
+		},
 		"./remix/http": {
 			"import": "./esm/remix/http.js",
 			"require": "./remix/http.js"

package/vanillaExtract.d.ts

@@ -20,27 +20,131 @@ export declare const vanillaProps: (css: string) => GlobalStyleRule;
 export declare function vanillaClass(css: string | ((className: string) => string)): string;
 export declare function vanillaClass(debugId: string, css: string | ((className: string) => string)): string;
 /**
+ * @deprecated  (Will be removed in v0.2)
+ *
  * Replaces all `&` tokens with the given selector string, in a direct
  * (read. "dumb") way. It's mainly useful when used with style-mixins, etc.
  *
- * NOTE: It does NOT support deeply nested blocks, or anything so fancy.
- * It will also replace "&" characters inside values, comments, etc.
+ * **NOTE:** `vanillaNest` does NOT support deeply nested blocks, or anything
+ * so fancy. It will also replace `&` characters inside values, comments, etc.
  * If you need something more sophisticated, use a custom `postcss` config.
  *
+ * ```ts
+ * // someCssHelper.ts
+ * import { vanillaNest } from '@reykjavik/webtools/vanillaExtract';
+ *
+ * export const hoverGlow = (
+ *   ampSelector: string,
+ *   glowiness?: 'normal' | 'insane'
+ * ) =>
+ *   vanillaNest(
+ *     ampSelector,
+ *     `
+ *     &:hover {
+ *       box-shadow: 0 0 20px 5px ${
+ *         glowiness === 'insane' ? 'hotpink' : 'salmon'
+ *       };
+ *     }
+ *   `
+ *   );
+ *
+ * // ...then, somewhere else in a *.css.ts file:
+ *
+ * import { hoverGlow } from '~/someCssHelper.js';
+ * import { vanillaGlobal } from '@reykjavik/webtools/vanillaExtract';
+ *
+ * vanillaGlobal(`
+ *   .MyComponent {
+ *     border: 1px solid #ccc;
+ *     padding: 1em;
+ *   }
+ *   ${hoverGlow('.MyComponent')}
+ *
+ *   .MyOtherComponent {
+ *     border: 1px solid #ccc;
+ *     padding: 1em;
+ *   }
+ *   ${hoverGlow('.MyOtherComponent', 'insane')}
+ * `);
+ * ```
  *
- * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#vanillanest
+ * (This low-level utility function is used internally by `vanillaClassNested`.
  */
 export declare const vanillaNest: (ampSelector: string, css: string) => string;
 /**
+ * @deprecated  (Will be removed in v0.2)
+ *
  * Returns a scoped cssClassName styled with free-form CSS.
  *
  * It also automatically replaces all `&`-tokens with
  * the selector for the auto-generated class-name.
  *
- * NOTE: All "bare" (un-nested) style properties must come first,
+ * ```ts
+ * // someFile.css.ts
+ * import { vanillaClassNested } from '@reykjavik/webtools/vanillaExtract';
+ *
+ * export const myClass = vanillaClassNested(`
+ *   background-color: #ccc;
+ *   padding: .5em 1em;
+ *
+ *   /* Nested blocks begin: *​​/
+ *   &:hover {
+ *     background-color: #666;
+ *     color: white;
+ *   }
+ *   & > strong {
+ *     color: maroon;
+ *   }
+ *   html[data-color-theme="unicorn"] & {
+ *     background-color: pink;
+ *   }
+ * `);
+ * ```
+ *
+ * **NOTE:** All "bare" (un-nested) style properties **must come first**,
  * before any nested blocks.
  *
- * @see https://github.com/reykjavikcity/webtools/blob/v0.1/README.md#vanillaclassnested
+ * **NOTE 2:** `vanillaClassNested` does NOT support deeply nested blocks, or
+ * anything so fancy. It will also replace `&` characters inside values,
+ * comments, etc. If you need something more sophisticated, use a custom
+ * `postcss` config.
  */
 export declare function vanillaClassNested(css: string): string;
+/** @deprecated  (Will be removed in v0.2) */
+/**
+ * Returns a scoped cssClassName styled with free-form CSS.
+ *
+ * It also automatically replaces all `&`-tokens with
+ * the selector for the auto-generated class-name.
+ *
+ * ```ts
+ * // someFile.css.ts
+ * import { vanillaClassNested } from '@reykjavik/webtools/vanillaExtract';
+ *
+ * export const myClass = vanillaClassNested(`
+ *   background-color: #ccc;
+ *   padding: .5em 1em;
+ *
+ *   /* Nested blocks begin: *​​/
+ *   &:hover {
+ *     background-color: #666;
+ *     color: white;
+ *   }
+ *   & > strong {
+ *     color: maroon;
+ *   }
+ *   html[data-color-theme="unicorn"] & {
+ *     background-color: pink;
+ *   }
+ * `);
+ * ```
+ *
+ * **NOTE:** All "bare" (un-nested) style properties **must come first**,
+ * before any nested blocks.
+ *
+ * **NOTE 2:** `vanillaClassNested` does NOT support deeply nested blocks, or
+ * anything so fancy. It will also replace `&` characters inside values,
+ * comments, etc. If you need something more sophisticated, use a custom
+ * `postcss` config.
+ */
 export declare function vanillaClassNested(debugId: string, css: string): string;