design-token-library 0.3.1 → 0.4.0

package/dist/lib/library.d.ts

@@ -22,7 +22,18 @@ declare const TOKEN: unique symbol;
 export declare namespace Library {
     export interface Library<T extends {}, R extends {} = T> {
         tokens: TokenLibrary<T, R>;
-        subscribe(subscriber: Library.Subscriber<R>): void;
+        /**
+         * Adds a subscriber, which is told of each change made after it's
+         * added.
+         *
+         * @remarks
+         * A library with a subscriber resolves its tokens, and a `set()`
+         * resolves again the tokens it reaches. An extension resolves its
+         * own tokens, and its subscriber is told of them; with
+         * `origin: "ancestor"` or `"all"`, it resolves its ancestor's tokens
+         * too, and the subscriber is told of those whose values change.
+         */
+        subscribe(subscriber: Library.Subscriber<R>, options?: Library.SubscribeOptions): void;
         unsubscribe(subscriber: Library.Subscriber<R>): void;
         /**
          * Creates a library with the values of the tokens replaced, and
@@ -36,7 +47,7 @@ export declare namespace Library {
          * extension that nothing refers to is collected, along with its
          * subscribers.
          */
-        extend(config: ExtendConfig<T, R>, options?: ExtendOptions): Library<T, R>;
+        extend(config: ExtendConfig<T, R>, ...options: ExtendArgs<{}, T>): Library<T, R>;
         /**
          * Creates a library with the values of tokens replaced, new tokens,
          * and recipes overridden.
@@ -46,7 +57,7 @@ export declare namespace Library {
          * extension that nothing refers to is collected, along with its
          * subscribers.
          */
-        extend<K extends NoRoot<K> = {}>(config: ExtendConfig<T, R & NewTokens<K, T>> & Config<K, R & NewTokens<K, T>, never, T> & NoInfer<ConfigValueCheck<K, R & NewTokens<K, T>>> & (ConfigTypeHint | {}), options?: ExtendOptions): Library<T & NewTokens<K, T>, R & NewTokens<K, T>>;
+        extend<K extends NoRoot<K> = {}>(config: ExtendConfig<T, R & NewTokens<K, T>> & Config<K, R & NewTokens<K, T>, never, T> & NoInfer<ConfigValueCheck<K, R & NewTokens<K, T>>> & (ConfigTypeHint | {}), ...options: ExtendArgs<NewTokens<K, T>, T>): Library<T & NewTokens<K, T>, R & NewTokens<K, T>>;
     }
     /**
      * The tokens and groups of `K` that are new relative to a source library
@@ -125,8 +136,64 @@ export declare namespace Library {
          */
         filter?(entry: EntryOf<S, R>): FilterResult;
     }
+    /**
+     * What changed of a token, in a batch.
+     *
+     * @public
+     */
+    export interface Change<R extends {}> {
+        /**
+         * The token, of the library subscribed to.
+         */
+        readonly token: TokenRecord<R>;
+        /**
+         * Its value changed.
+         */
+        readonly valueChanged: boolean;
+        /**
+         * Where its value comes from: an extension's own token, or one whose
+         * value is its ancestor's. Always `"own"` in a library made by
+         * `create()`.
+         */
+        readonly origin: "ancestor" | "own";
+        /**
+         * Its origin changed: an extension's token became its own.
+         */
+        readonly originChanged: boolean;
+    }
+    /**
+     * @public
+     */
+    export interface SubscribeOptions {
+        /**
+         * Which tokens a subscriber is told of, by where their values come
+         * from, as {@link (Library:namespace).Change.origin} says: the
+         * library's own (the default), its ancestor's, or all. A library
+         * made by `create()` has only its own.
+         */
+        readonly origin?: "own" | "ancestor" | "all";
+    }
+    /**
+     * @public
+     */
     export interface Subscriber<R extends {}> {
-        onChange(records: ReadonlyArray<Library.TokenRecord<R>>): void;
+        /**
+         * Called with what changed, once for the changes made before a
+         * microtask runs. Each change has its value or its origin changed.
+         */
+        onChange(changes: ReadonlyArray<Library.Change<R>>): void;
+        /**
+         * Called with an error that a token threw as the library resolved
+         * it on its own: as it was subscribed, or after a change. Reading
+         * the token throws to its reader instead.
+         *
+         * @remarks
+         * It's called in a microtask after the batch the error was found
+         * in, once for each error, and the subscriber is still told of
+         * later changes. An error that no subscriber with `onError` is told
+         * of is thrown from a microtask.
+         */
+        onError?(error: TokenResolutionError): void;
     }
     /**
      * A union of all tokens in a library of shape `T`.
@@ -289,6 +356,42 @@ export declare namespace Library {
         readonly recipe: Recipe<any, unknown>;
         readonly fn: (...args: any[]) => unknown;
     }
+    /**
+     * What a library knows of a custom type: how to tell whether two of its
+     * values are equal.
+     *
+     * @public
+     */
+    export interface TypeOptions<V = unknown> {
+        /**
+         * Tells whether a value a token of the type resolved to is equal to
+         * the one it had. When it is, the token keeps the value it had, so it
+         * is the same object. It's called only by a library with a
+         * subscriber, and not when a token resolves its first value.
+         */
+        isEqual(previous: V, next: V): boolean;
+    }
+    /**
+     * The custom types a library registers, by name. A DTCG type has its own
+     * equality, so it can't be registered.
+     *
+     * @public
+     */
+    export type Types = {
+        readonly [name: string]: TypeOptions<any>;
+    };
+    /**
+     * Options of `create()`.
+     *
+     * @public
+     */
+    export interface CreateOptions {
+        /**
+         * The custom types of the library's tokens. Every custom type a token
+         * has must be registered.
+         */
+        readonly types?: Types;
+    }
     /**
      * Options of `extend()`.
      *
@@ -301,7 +404,73 @@ export declare namespace Library {
          * doesn't restate.
          */
         readonly recipes?: readonly RecipeOverride[];
+        /**
+         * The custom types that the extension's new tokens have and the
+         * library it extends doesn't register. A type the library registers
+         * is inherited, and can't be registered again.
+         */
+        readonly types?: Types;
     }
+    /**
+     * The custom type names in a library of shape `T`: the `$type` of each
+     * of its tokens and groups that isn't a DTCG type.
+     *
+     * @public
+     */
+    export type CustomTypeNamesOf<T> = 0 extends 1 & T ? never : T extends readonly unknown[] | Function ? never : T extends object ? {
+        [K in keyof T]-?: K extends "$type" ? T[K] extends string ? string extends T[K] ? never : Exclude<T[K], DesignToken.Type | DesignToken.ReservedTypeName> : never : K extends `$${string}` ? never : CustomTypeNamesOf<T[K]>;
+    }[keyof T] : never;
+    /**
+     * The values of the tokens of type `N` in a library of shape `T`, as a
+     * token gives them. `G` is the type inherited from ancestor groups.
+     *
+     * @public
+     */
+    export type ValueOfType<T, N extends string, G extends string = never> = {
+        [K in keyof T]-?: K extends `$${string}` ? never : T[K] extends DesignToken.Shape ? DesignToken.TypeByToken<T[K], G> extends N ? DesignToken.ReadonlyValueByToken<T[K]> : never : T[K] extends object ? ValueOfType<T[K], N, GroupType<T[K], G>> : never;
+    }[keyof T];
+    /**
+     * The `types` a library of shape `T` registers: each of the custom
+     * types `N` that `I`, the types it inherits, leave out.
+     *
+     * @public
+     */
+    export type TypesOf<T, N extends string, I extends string = never> = {
+        readonly [P in Exclude<N, I>]: TypeOptions<ValueOfType<T, P>>;
+    } & {
+        readonly [P in DesignToken.ReservedTypeName | I]?: never;
+    } & Types;
+    /**
+     * The options of `create()` for a library of shape `T`: required, with
+     * its custom types, when it has any.
+     *
+     * @public
+     */
+    export type CreateArgs<T> = [CustomTypeNamesOf<T>] extends [never] ? [options?: CreateOptions & {
+        readonly types?: TypesOf<T, never>;
+    }] : [
+        options: CreateOptions & {
+            readonly types: TypesOf<T, CustomTypeNamesOf<T>>;
+        }
+    ];
+    /**
+     * The options of `extend()` for new tokens of shape `K` in a library of
+     * shape `T`: required, with the custom types `T` doesn't have, when they
+     * have any.
+     *
+     * @public
+     */
+    export type ExtendArgs<K, T> = [
+        Exclude<CustomTypeNamesOf<K>, CustomTypeNamesOf<T>>
+    ] extends [never] ? [
+        options?: ExtendOptions & {
+            readonly types?: TypesOf<K, never, CustomTypeNamesOf<T>>;
+        }
+    ] : [
+        options: ExtendOptions & {
+            readonly types: TypesOf<K, CustomTypeNamesOf<K>, CustomTypeNamesOf<T>>;
+        }
+    ];
     /**
      * A {@link (Library:namespace).Ref} to each token of a library of shape
      * `R`, at the path of the token in `T`, the shape of a group of it. Made by
@@ -453,7 +622,7 @@ export declare namespace Library {
     /**
      * @public
      */
-    export const create: <T extends NoRoot<T> = any>(config: Library.Config<T, T> & NoInfer<ConfigValueCheck<T, T>> & (ConfigTypeHint | {})) => Library.Library<T>;
+    export const create: <T extends NoRoot<T> = any>(config: Library.Config<T, T> & NoInfer<ConfigValueCheck<T, T>> & (ConfigTypeHint | {}), ...options: NoInfer<CreateArgs<T>>) => Library.Library<T>;
     export {};
 }
 /**
@@ -471,6 +640,25 @@ export declare class CircularReferenceError extends Error {
     readonly chain: string[];
     constructor(chain: string[]);
 }
+/**
+ * Given to a subscriber's `onError` when a token throws as a subscribed
+ * library resolves it on its own. The error thrown is its `cause`.
+ *
+ * @public
+ */
+export declare class TokenResolutionError extends Error {
+    readonly name = "TokenResolutionError";
+    /**
+     * The name of the token that threw.
+     */
+    readonly tokenName: string;
+    /**
+     * What threw: its type's `isEqual`, comparing the value it resolved with
+     * the one it had, or resolving its value.
+     */
+    readonly phase: "isEqual" | "resolve";
+    constructor(tokenName: string, phase: "isEqual" | "resolve", cause: unknown);
+}
 /**
  * A token's value as it was configured, or last given to `set()`, with its
  * refs and computed values unresolved. A token of a library made by
@@ -600,14 +788,12 @@ export declare function entriesOf<T extends {}, R extends {}>(library: Library.L
  *
  * This reads the configured values and not the values, so it resolves no
  * token, and so it is known of a library whose tokens have not been read. It
- * is found for the whole library once and kept until a token is set to a
- * different value, so each call after the first is a lookup. A value a recipe
+ * is found for the whole library once, kept as tokens are set, and shared
+ * with the libraries that extend it, so each call after the first is a
+ * lookup, and an extension makes only the tokens it lists. A value a recipe
  * reads other than through its arguments is not seen, as for
  * {@link dependenciesOf}.
  *
- * It throws when a ref in a token of the library isn't a token of it, as
- * reading the token's `$value` does.
- *
  * @example
  * ```ts
  * // hover: { $value: Recipes.darken(theme.colors.primary, 0.2) }
@@ -630,4 +816,29 @@ export declare function entriesOf<T extends {}, R extends {}>(library: Library.L
  * @public
  */
 export declare const dependentsOf: <T extends DesignToken.Shape, R extends {}, G extends string = never>(token: Library.Token<T, R, G>) => ReadonlyArray<Library.TokenRecord<R>>;
+/**
+ * The tokens of a library whose values are its own, in the order of the
+ * library: every token of a library made by `create()`, and an extension's
+ * tokens that don't come from its ancestors.
+ *
+ * @remarks
+ * An extension's token is its own when it has a value of its own (one its
+ * config gives, one that is set, or a token new in it), when it calls a
+ * recipe the extension overrides, or when a token it depends on is its own.
+ * A token depends on the tokens its configured value refers to, and on
+ * those a ref in a recipe's result is to, so tokens of its ancestors that
+ * call recipes may be resolved to find them.
+ *
+ * It's what a first render of an extension writes, such as with
+ * {@link toCSS}'s `filter`.
+ *
+ * @example
+ * ```ts
+ * const own = new Set(ownTokensOf(extension));
+ * toCSS(extension, { filter: (token) => own.has(token) });
+ * ```
+ *
+ * @public
+ */
+export declare const ownTokensOf: <R extends {}>(library: Library.Library<any, R>) => ReadonlyArray<Library.TokenRecord<R>>;
 export {};