design-token-library 0.1.0 → 0.3.0

package/dist/lib/library.d.ts

@@ -1,80 +1,633 @@
+import { COMPUTED, RECIPE } from "./recipe.js";
+import { REF } from "./ref.js";
 import { DesignToken } from "./design-token.js";
-import { DeepPartial } from "./utilities.js";
+/**
+ * The key of the phantom type of a ref: what it resolves to, in a library of
+ * what shape. It's never set.
+ */
+declare const RESOLVES: unique symbol;
+/**
+ * The key of the phantom type of a computed value, apart from a ref's, so
+ * that a ref's type is never inferred from a computed value's.
+ */
+declare const COMPUTES: unique symbol;
+/**
+ * The key of the phantom type that marks a token in
+ * {@link (Library:namespace).TokenValues}. It's never set.
+ */
+declare const TOKEN: unique symbol;
 /**
  * @public
  */
 export declare namespace Library {
-    interface Library<T extends {}, R extends {} = T> {
+    export interface Library<T extends {}, R extends {} = T> {
         tokens: TokenLibrary<T, R>;
         subscribe(subscriber: Library.Subscriber<R>): void;
         unsubscribe(subscriber: Library.Subscriber<R>): void;
-        extend<K extends {} = any>(config: DeepPartial<T> & Config<K, R & K>): Library<T & K, R & K>;
+        /**
+         * Creates a library with the values of the tokens replaced, and
+         * recipes overridden.
+         *
+         * @remarks
+         * This has no tokens to add, so a value is checked against the type
+         * of its token wherever the token is.
+         *
+         * A token of the extension is made when it is first read, and an
+         * extension that nothing refers to is collected, along with its
+         * subscribers.
+         */
+        extend(config: ExtendConfig<T, R>, options?: ExtendOptions): Library<T, R>;
+        /**
+         * Creates a library with the values of tokens replaced, new tokens,
+         * and recipes overridden.
+         *
+         * @remarks
+         * A token of the extension is made when it is first read, and an
+         * 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>>;
+    }
+    /**
+     * The tokens and groups of `K` that are new relative to a source library
+     * of shape `T`. Overrides of tokens in `T` are removed so that they keep
+     * the source token's type.
+     *
+     * @public
+     */
+    export type NewTokens<K, T> = {
+        [P in keyof K as P extends keyof T ? T[P] extends DesignToken.Shape ? never : P : P]: P extends keyof T ? NewTokens<K[P], T[P]> : K[P];
+    };
+    /**
+     * `$root` is the token of a group, so a library cannot have one at its top
+     * level, where there is no group to name it for.
+     *
+     * @public
+     */
+    export type NoRoot<T> = {
+        [K in keyof T]: K extends "$root" ? never : T[K];
+    };
+    /**
+     * Which entries of a library {@link (entriesOf:3)} lists: its tokens, its
+     * groups, or both. Each is the `kind` of the entries it lists.
+     *
+     * @public
+     */
+    export type Show = "all" | "token" | "group";
+    /**
+     * A token of a library, with the path of keys that leads to it from the
+     * root. The path of a group's own token ends with `$root`.
+     *
+     * @public
+     */
+    export interface TokenEntry<R extends {}> {
+        readonly kind: "token";
+        readonly path: readonly string[];
+        readonly token: TokenRecord<R>;
     }
-    interface Subscriber<R extends {}> {
-        onChange(records: ReadonlyArray<Library.Token<DesignToken.Any, R>>): void;
+    /**
+     * A group of a library, with the path of keys that leads to it from the
+     * root. The group has the `$`-prefixed properties it was configured with.
+     *
+     * @public
+     */
+    export interface GroupEntry {
+        readonly kind: "group";
+        readonly path: readonly string[];
+        readonly group: Readonly<DesignToken.Group>;
     }
+    /**
+     * The entries that {@link (entriesOf:3)} lists for `S`.
+     *
+     * @public
+     */
+    export type EntryOf<S extends Show, R extends {}> = S extends "token" ? TokenEntry<R> : S extends "group" ? GroupEntry : TokenEntry<R> | GroupEntry;
+    /**
+     * What a {@link (entriesOf:3)} filter returns for an entry: `true` lists it,
+     * `false` leaves it out, and `"reject"` leaves it out along with
+     * everything under it.
+     *
+     * @public
+     */
+    export type FilterResult = boolean | "reject";
+    /**
+     * @public
+     */
+    export interface EntriesOptions<S extends Show, R extends {}> {
+        /**
+         * The kind of entries to list. Groups are visited, and their tokens
+         * listed, whichever it is. By default, all.
+         */
+        readonly whatToShow?: S;
+        /**
+         * Called with each entry of the kinds shown, before its children are
+         * visited.
+         */
+        filter?(entry: EntryOf<S, R>): FilterResult;
+    }
+    export interface Subscriber<R extends {}> {
+        onChange(records: ReadonlyArray<Library.TokenRecord<R>>): void;
+    }
+    /**
+     * A union of all tokens in a library of shape `T`.
+     *
+     * @public
+     */
+    export type TokensOf<T> = {
+        [K in keyof T]-?: T[K] extends DesignToken.Shape ? T[K] : K extends keyof DesignToken.Group ? never : T[K] extends object ? TokensOf<T[K]> : never;
+    }[keyof T];
+    /**
+     * A {@link (Library:namespace).Token} of any token in a library of shape `R`.
+     * The union is discriminated by `type`.
+     *
+     * @public
+     */
+    export type TokenRecord<R extends {}> = TokensOf<R> extends infer T ? T extends DesignToken.Shape ? Token<T, R> : never : never;
     /**
      * Defines a token library that can be interacted with
      * to mutate token values.
      *
+     * @remarks
+     * `G` is the type inherited from ancestor groups.
+     *
+     * @public
+     */
+    export type TokenLibrary<T extends {}, R extends {} = T, G extends string = never> = TokenGroup<T, R, GroupType<T, G>>;
+    type TokenGroup<T extends {}, R extends {}, G extends string> = {
+        [K in keyof Readonly<T>]: T[K] extends DesignToken.Shape ? Token<T[K], R, G> : K extends keyof DesignToken.Group ? T[K] : T[K] extends {} ? TokenLibrary<T[K], R, G> : never;
+    };
+    /**
+     * The value type of each token of a library of shape `T`, by its path.
+     * Refs and computed values are typed by it, so they're given only to a
+     * library that has their tokens, with values of the same types, whether
+     * its shape is declared or inferred from its config.
+     *
+     * @public
+     */
+    export type TokenValues<T> = {
+        [K in keyof T as K extends keyof DesignToken.Group ? never : K]: T[K] extends DesignToken.Shape ? TokenValue<DesignToken.ValueByToken<T[K]>> : T[K] extends object ? TokenValues<T[K]> : never;
+    };
+    /**
+     * A token with a value of type `V`, in
+     * {@link (Library:namespace).TokenValues}. It's only a type: it marks
+     * where a path ends at a token rather than going into its value.
+     *
+     * @public
+     */
+    export interface TokenValue<V> {
+        readonly [TOKEN]: V;
+    }
+    /**
+     * The dotted path of each token in `T`, the
+     * {@link (Library:namespace).TokenValues} of a library, whose value is a
+     * `V`. These are the paths {@link ref} takes where a `V` is expected.
+     *
+     * @public
+     */
+    export type TokenPath<T, V> = {
+        [K in keyof T & string]: T[K] extends TokenValue<infer W> ? [W] extends [V] ? K : never : `${K}.${TokenPath<T[K], V>}`;
+    }[keyof T & string];
+    /**
+     * A reference to a token whose value is of type `V`, in a library whose
+     * token values are `T`. It's resolved to the token's value when the token
+     * that has it is read. Made by {@link ref} and {@link refs}.
+     *
+     * @remarks
+     * A ref is data: the path of its token. `T`, the
+     * {@link (Library:namespace).TokenValues} of the library, is only in its
+     * type, so that a ref can only be given to a library that has its token.
+     *
+     * @public
+     */
+    export interface Ref<V, T> {
+        readonly [REF]: readonly string[];
+        readonly [RESOLVES]?: (library: T) => V;
+    }
+    /**
+     * A value of type `V` computed by a {@link (Library:namespace).Recipe}
+     * from its arguments, which may refer to the tokens of a library whose
+     * {@link (Library:namespace).TokenValues} are `T`. It's computed when the
+     * token that has it is read.
+     *
+     * @remarks
+     * A computed value is data: the recipe and its arguments.
+     *
+     * @public
+     */
+    export interface Computed<V, T> {
+        readonly [COMPUTED]: {
+            readonly recipe: Recipe<any, unknown>;
+            readonly args: readonly unknown[];
+        };
+        readonly [COMPUTES]?: (library: T) => V;
+    }
+    /**
+     * A value of type `V` in a configuration: the value, a
+     * {@link (Library:namespace).Ref}, a {@link (Library:namespace).Computed}
+     * value, or, when `V` is an object or an array, `V` with any of its
+     * properties and elements, at any depth, given as one of those.
+     *
+     * @remarks
+     * Its objects and arrays may be readonly, as a token's value is, so a
+     * token's value can be given where a config takes a value, as `set()`
+     * takes it. A computed value may be readonly, as a recipe's function that
+     * takes readonly arguments returns: the library copies and freezes a
+     * recipe's result.
+     *
      * @public
      */
-    type TokenLibrary<T extends {}, R extends {} = T> = {
-        [K in keyof Readonly<T>]: T[K] extends DesignToken.Any ? Token<T[K], R> : K extends "type" ? DesignToken.Type : T[K] extends {} ? TokenLibrary<T[K], R> : never;
+    export type DeepValue<V, T> = V | Ref<V, T> | Computed<DesignToken.DeepReadonly<V>, T> | (V extends object ? {
+        readonly [K in keyof V]: DeepValue<V[K], T>;
+    } : never);
+    /**
+     * The arguments of a {@link (Library:namespace).Recipe} whose function has
+     * the parameters `A`. Each may be a ref, a computed value, or a value with
+     * them in it.
+     *
+     * @public
+     */
+    export type RecipeArguments<A extends readonly unknown[], T> = {
+        [K in keyof A]: DeepValue<A[K], T>;
     };
     /**
-     * A token value that serves as an alias to another token value
+     * A function, made by {@link recipes}, that takes the arguments of a
+     * function with parameters `A` and result `V`, any of which may refer to
+     * tokens, and returns the {@link (Library:namespace).Computed} result.
+     * `T` is the token values of the library its arguments refer to.
+     *
+     * @remarks
+     * A recipe has its name and its function, which a library that extends
+     * another can override with {@link override}. The function gets each
+     * argument as a token gets its value: a ref's value, and a copy of plain
+     * data, which are frozen, and anything else as it is. So its parameters
+     * are typed readonly, as in `DesignToken.Values.Readonly.Color`.
      *
      * @public
      */
-    type Alias<T extends DesignToken.Any, R extends Context<any>> = (context: R) => T | DesignToken.ValueByToken<T>;
+    export type Recipe<A extends readonly unknown[], V> = (<T extends {} = {}>(...args: RecipeArguments<A, T>) => Computed<V, T>) & {
+        readonly [RECIPE]: {
+            readonly name: string;
+            readonly fn: (...args: A) => V;
+        };
+    };
     /**
-     * An {@link (Library:namespace).Alias} that supports complex token value types
-     * such as {@link DesignToken.Border}
+     * The {@link (Library:namespace).Recipe | recipes} of the functions of `F`,
+     * by the same keys. Made by {@link recipes}.
      *
      * @public
      */
-    type DeepAlias<V extends DesignToken.Values.Any, T extends Context<any>> = {
-        [K in keyof V]: V[K] extends DesignToken.Values.Any ? V[K] | Alias<DesignToken.TokenByValue<V[K]>, T> | DeepAlias<V[K], T> : never;
+    export type Recipes<F extends Record<string, (...args: any[]) => unknown>> = {
+        readonly [K in keyof F]: Recipe<Parameters<F[K]>, ReturnType<F[K]>>;
     };
     /**
-     * Context object provided to {@link (Library:namespace).Alias} values at runtime
+     * A function that replaces a recipe's in a library made by `extend()`.
+     * Made by {@link override}.
+     *
+     * @public
+     */
+    export interface RecipeOverride {
+        readonly recipe: Recipe<any, unknown>;
+        readonly fn: (...args: any[]) => unknown;
+    }
+    /**
+     * Options of `extend()`.
      *
      * @public
      */
-    type Context<T extends {}, R extends {} = T> = {
-        [K in keyof Readonly<T>]: T[K] extends DesignToken.Any ? Readonly<T[K]> : K extends "type" ? DesignToken.Type : T[K] extends {} ? Context<T[K], R> : never;
+    export interface ExtendOptions {
+        /**
+         * Recipes whose function is replaced in the new library, for every
+         * token that computes its value with them, including the tokens it
+         * doesn't restate.
+         */
+        readonly recipes?: readonly RecipeOverride[];
+    }
+    /**
+     * 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
+     * {@link refs}.
+     *
+     * @public
+     */
+    export type Refs<T extends {}, R extends {} = T> = {
+        readonly [K in keyof T as K extends keyof DesignToken.Group ? never : K]-?: T[K] extends DesignToken.Shape ? Ref<DesignToken.ValueByToken<T[K]>, TokenValues<R>> : T[K] extends {} ? Refs<T[K], R> : never;
     };
     /**
      * A token in a {@link (Library:namespace).TokenLibrary}
      *
+     * @remarks
+     * `G` is the type inherited from ancestor groups, used when
+     * `T` does not declare a `$type`.
+     *
      * @public
      */
-    type Token<T extends DesignToken.Any, C extends {}> = {
-        set(value: DesignToken.ValueByToken<T> | Alias<T, C>): void;
+    export type Token<T extends DesignToken.Shape, C extends {}, G extends string = never> = {
+        set(value: ConfigTokenValue<T, C> | DesignToken.ReadonlyValueByToken<T>): void;
+        /**
+         * A JSON representation of the token's name, type, resolved value,
+         * description, extensions and deprecation.
+         */
         toString(): string;
-        readonly type: DesignToken.TypeByToken<T>;
-        readonly extensions: Record<string, any>;
-        readonly value: DesignToken.ValueByToken<T>;
-        readonly description: string;
+        readonly $type: DesignToken.TypeByToken<T, G>;
+        readonly $extensions: Record<string, any>;
+        readonly $value: DesignToken.ReadonlyValueByToken<T>;
+        readonly $description: string;
+        /**
+         * `false`, `true`, or the explanation the token was deprecated with.
+         */
+        readonly $deprecated: boolean | string;
         readonly name: string;
     };
+    type IsUnion<T, U = T> = T extends unknown ? [U] extends [T] ? false : true : never;
+    /**
+     * The type a group passes on to its descendant tokens, following
+     * {@link https://www.designtokens.org/tr/2025.10/format/#type-1 | DTCG group type inheritance}.
+     *
+     * @remarks
+     * A group passes on its own `$type` only when the group's shape declares a
+     * required, single, literal `$type`. A group with an optional or non-literal
+     * `$type` may set any type at runtime, so it passes on nothing. A group
+     * without a `$type` passes on its ancestor's type, `G`.
+     *
+     * @public
+     */
+    export type GroupType<T, G extends string = never> = "$type" extends keyof T ? {} extends Pick<T, "$type"> ? never : T["$type"] extends string ? string extends T["$type"] ? never : true extends IsUnion<T["$type"]> ? never : T["$type"] : never : G;
+    /**
+     * The value of a token in a configuration object, in a library of shape
+     * `R`: a {@link (Library:namespace).DeepValue} of the token's value type.
+     *
+     * @public
+     */
+    export type ConfigTokenValue<T extends DesignToken.Shape, R extends {}> = DeepValue<DesignToken.ValueByToken<T>, TokenValues<R>>;
+    /**
+     * A token in a configuration object.
+     *
+     * @remarks
+     * The token's `$type` may only be omitted when it matches the type
+     * inherited from ancestor groups, `G`.
+     *
+     * @public
+     */
+    export type ConfigValue<T extends DesignToken.Shape, R extends {}, G extends string = never> = T | (Omit<T, "$type" | "$value"> & ([G] extends [never] ? {
+        $type: DesignToken.TypeByToken<T>;
+    } : [DesignToken.TypeByToken<T, G>] extends [G] ? {
+        $type?: DesignToken.TypeByToken<T, G>;
+    } : {
+        $type: DesignToken.TypeByToken<T>;
+    }) & {
+        $value: ConfigTokenValue<T, R>;
+    });
     /**
      * A configuration object provided to {@link Library.create}
      *
+     * @remarks
+     * `G` is the type inherited from ancestor groups. `S` is the shape of a
+     * source library being extended: its group types are inherited, and its
+     * tokens may be overridden without restating their type.
+     *
      * @public
      */
-    type Config<T extends {}, R extends {} = T> = {
-        [K in keyof T]: T[K] extends DesignToken.Any ? ConfigValue<T[K], R> : T[K] extends {} ? Config<T[K], R> : never;
+    export type Config<T extends {}, R extends {} = T, G extends string = never, S = {}> = ConfigGroup<T, R, GroupType<T, GroupType<S, G>>, S>;
+    type ConfigGroup<T extends {}, R extends {}, G extends string, S> = {
+        [K in keyof T]: K extends keyof S ? S[K] extends DesignToken.Shape ? unknown : ConfigEntry<T, R, G, S, K> : ConfigEntry<T, R, G, S, K>;
     };
+    type ConfigEntry<T extends {}, R extends {}, G extends string, S, K extends keyof T> = T[K] extends DesignToken.Shape ? ConfigValue<T[K], R, G> : K extends keyof DesignToken.Group ? T[K] : T[K] extends {} ? Config<T[K], R, G, K extends keyof S ? S[K] : {}> : T[K] extends null | undefined ? T[K] : never;
     /**
+     * Checks the `$value` of each token in a config of shape `T` against
+     * its `$type`. It's needed when `T` is inferred from the config, because
+     * the inferred `$value` is the config's own value, so
+     * {@link (Library:namespace).Config} alone can't reject it.
+     *
+     * @remarks
+     * Only the values of tokens that declare a {@link DesignToken.Type} are
+     * checked. A token can't have a child (a key without a `$` prefix).
+     *
+     * Tokens are found by their keys rather than by `T[K] extends Shape`,
+     * which TypeScript doesn't resolve for an inferred `T` with extra keys.
+     * An `any` config, such as `Library.create<any>()`, isn't checked.
+     *
      * @public
      */
-    type ConfigValue<T extends DesignToken.Any, R extends {}> = T | (Omit<T, "value"> & {
-        value: Library.Alias<T, Context<R>> | Library.DeepAlias<DesignToken.ValueByToken<T>, Context<R>>;
-    });
+    export type ConfigValueCheck<T, R extends {}> = 0 extends 1 & T ? unknown : {
+        [K in keyof T]: 0 extends 1 & T[K] ? unknown : "$value" extends keyof T[K] ? ("$type" extends keyof T[K] ? TokenValueCheck<T[K][Extract<"$type", keyof T[K]>], R> : unknown) & {
+            [P in Exclude<keyof T[K], `$${string}`>]?: never;
+        } : T[K] extends object ? ConfigValueCheck<T[K], R> : unknown;
+    };
+    type TokenValueCheck<Type, R extends {}> = [Type] extends [
+        keyof DesignToken.ValueByType
+    ] ? {
+        $value: ConfigTokenValue<{
+            $type: Type;
+            $value: DesignToken.ValueByType[Type];
+        }, R>;
+    } : unknown;
+    /**
+     * Gives each `$type` in a config literal a contextual type, so that
+     * TypeScript keeps an inferred `$type` literal, such as
+     * `DesignToken.Type.Color`, instead of widening it to `DesignToken.Type`.
+     * {@link (Library:namespace).ConfigValueCheck} needs the literal.
+     *
+     * @remarks
+     * Configs are typed `ConfigTypeHint | {}`, so a config without an index
+     * signature, such as a typed variable, is still accepted.
+     *
+     * @public
+     */
+    export type ConfigTypeHint = {
+        readonly [key: string]: ConfigTypeHint | DesignToken.Type | (string & {}) | number | boolean | object | null | undefined;
+    };
+    /**
+     * A configuration object provided to {@link (Library:namespace).Library.(extend:1)}.
+     * All tokens and groups of the source library are optional, and token
+     * values may be static values, refs or computed values. Token types are inherited
+     * from the source library.
+     *
+     * @public
+     */
+    export type ExtendConfig<T extends {}, R extends {} = T> = {
+        [K in keyof T]?: T[K] extends DesignToken.Shape ? Omit<T[K], "$type" | "$value"> & {
+            $type?: DesignToken.TypeByToken<T[K]>;
+            $value: ConfigTokenValue<T[K], R>;
+        } : K extends keyof DesignToken.Group ? T[K] : T[K] extends {} ? ExtendConfig<T[K], R> : never;
+    };
     /**
      * @public
      */
-    const create: <T extends {} = any>(config: Library.Config<T, T>) => Library.Library<T>;
+    export const create: <T extends NoRoot<T> = any>(config: Library.Config<T, T> & NoInfer<ConfigValueCheck<T, T>> & (ConfigTypeHint | {})) => Library.Library<T>;
+    export {};
 }
+/**
+ * Thrown when reading a token whose value refers back to itself through
+ * one or more refs or computed values.
+ *
+ * @public
+ */
+export declare class CircularReferenceError extends Error {
+    readonly name = "CircularReferenceError";
+    /**
+     * The names of the tokens in the cycle, starting and ending with the
+     * same token.
+     */
+    readonly chain: string[];
+    constructor(chain: string[]);
+}
+/**
+ * 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
+ * `extend()` that isn't given a value has its source token's.
+ *
+ * @remarks
+ * A token's `$value` is resolved, so it can't tell a value that is given from
+ * one that is derived from other tokens, or say where in a value a ref is. A
+ * tool that reads how a library is configured finds the refs in this value
+ * with {@link isRef} and the computed values with {@link isComputed}: a value
+ * with neither, at any depth, is given. A converter that writes a ref as a
+ * CSS `var()`, rather than its token's value, reads the ref here and its
+ * path with {@link pathOf}.
+ *
+ * It's the value the token holds, not a copy, so it isn't frozen. Changing it
+ * doesn't change the token: give a new value to `set()`. Refs and computed
+ * values are searched for in plain data, as the library resolves them, and
+ * not in a class instance or a function.
+ *
+ * @example
+ * ```ts
+ * const isGiven = (value: unknown): boolean =>
+ *     !isRef(value) &&
+ *     !isComputed(value) &&
+ *     (typeof value !== "object" || value === null ||
+ *         Object.values(value).every(isGiven));
+ *
+ * isGiven(configuredValueOf(library.tokens.colors.primary)); // true
+ * isGiven(configuredValueOf(library.tokens.colors.hover)); // false: a recipe
+ * ```
+ *
+ * @public
+ */
+export declare const configuredValueOf: <T extends DesignToken.Shape, R extends {}, G extends string = never>(token: Library.Token<T, R, G>) => Library.ConfigTokenValue<T, R> | DesignToken.ReadonlyValueByToken<T>;
+/**
+ * The tokens that a token's value refers to, through refs anywhere in its
+ * configured value, including the arguments of the recipes it's computed
+ * with, in the token's library. Each token is listed once, in the order its
+ * first ref is in the value.
+ *
+ * @remarks
+ * These are the tokens the value is made from, and not theirs in turn: a
+ * tool follows each with `dependenciesOf()` for the whole chain. A value
+ * computed by a recipe from literal arguments only has no dependencies,
+ * though it's derived: {@link configuredValueOf} tells that apart.
+ *
+ * It throws when a ref's path isn't a token of the library, as reading the
+ * token's `$value` does.
+ *
+ * @example
+ * ```ts
+ * // hover: { $value: Recipes.darken(theme.colors.primary, 0.2) }
+ * dependenciesOf(library.tokens.colors.hover).map((token) => token.name);
+ * // ["colors.primary"]
+ * ```
+ *
+ * @public
+ */
+export declare const dependenciesOf: <T extends DesignToken.Shape, R extends {}, G extends string = never>(token: Library.Token<T, R, G>) => ReadonlyArray<Library.TokenRecord<R>>;
+/**
+ * The tokens and groups of a library, each with its path, in the order of
+ * the config. A group is listed before the tokens and groups in it.
+ *
+ * @remarks
+ * This is the library's own rule for what is a token and what is a group, and
+ * for which keys are children, so a tool that visits every token (an index, a
+ * report, a list of the tokens to offer for a property) doesn't walk
+ * `library.tokens` and restate it. It walks as a DOM `TreeWalker` does: an
+ * entry that `whatToShow` leaves out is not passed to `filter`, but what is
+ * under it is still visited, and `filter` can return `"reject"` to leave out
+ * a group and everything under it.
+ *
+ * The library itself isn't listed, as a `TreeWalker`'s root isn't, so its own
+ * `$`-prefixed properties are not visited. A group's own token is listed with
+ * the path of its group and `$root`.
+ *
+ * The order is the order of the keys in a JavaScript object, so a name that
+ * is an array index (`"0"`, `"123"`) is listed before the other names of its
+ * group, in ascending order, whatever its place in the config.
+ *
+ * The listing is lazy and reads the
+ * library as it goes; a token's `$value` is not read.
+ *
+ * @example
+ * ```ts
+ * // The names of every token that isn't deprecated, in a group that isn't
+ * for (const { token } of entriesOf(library, {
+ *     whatToShow: "token",
+ *     filter: ({ token }) => !token.$deprecated,
+ * })) {
+ *     names.push(token.name);
+ * }
+ *
+ * // Everything, leaving out the deprecated groups
+ * const entries = [
+ *     ...entriesOf(library, {
+ *         filter: (entry) =>
+ *             entry.kind === "group" && entry.group.$deprecated
+ *                 ? "reject"
+ *                 : true,
+ *     }),
+ * ];
+ * ```
+ *
+ * @public
+ */
+export declare function entriesOf<T extends {}, R extends {}>(library: Library.Library<T, R>, options: Library.EntriesOptions<"token", R> & {
+    whatToShow: "token";
+}): Generator<Library.TokenEntry<R>, void, undefined>;
+/** @public */
+export declare function entriesOf<T extends {}, R extends {}>(library: Library.Library<T, R>, options: Library.EntriesOptions<"group", R> & {
+    whatToShow: "group";
+}): Generator<Library.GroupEntry, void, undefined>;
+/** @public */
+export declare function entriesOf<T extends {}, R extends {}>(library: Library.Library<T, R>, options?: Library.EntriesOptions<"all", R>): Generator<Library.EntryOf<"all", R>, void, undefined>;
+/**
+ * The tokens whose values refer to a token, through refs anywhere in their
+ * configured values, including the arguments of their recipes, in the
+ * token's library. It is the reverse of {@link dependenciesOf}: each token is
+ * listed once, in the order of the library.
+ *
+ * @remarks
+ * These are the tokens that refer to the token directly. A token whose value
+ * may change when this one is set is also one that refers to one of those: a
+ * tool follows each with `dependentsOf()` for the whole set, as it follows
+ * {@link dependenciesOf} for the chain the other way.
+ *
+ * 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
+ * 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) }
+ * dependentsOf(library.tokens.colors.primary).map((token) => token.name);
+ * // ["colors.hover"]
+ *
+ * // Every token that may change when a token is set
+ * const affected = new Set<Library.Token<any, any>>();
+ * const visit = (token: Library.Token<any, any>) => {
+ *     for (const dependent of dependentsOf(token)) {
+ *         if (!affected.has(dependent)) {
+ *             affected.add(dependent);
+ *             visit(dependent);
+ *         }
+ *     }
+ * };
+ * visit(extension.tokens.color.context);
+ * ```
+ *
+ * @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>>;
+export {};