@dicebear/core 10.0.0-rc.2 → 10.0.0-rc.4

package/lib/Style/Element.js

@@ -10,24 +10,49 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
     return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
 };
 var _Element_data, _Element_children;
+/**
+ * Read-only view over a single render-tree element from a style definition.
+ *
+ * The same node type covers SVG elements, text, and component references —
+ * `type()` discriminates between them.
+ */
 export class Element {
     constructor(data) {
         _Element_data.set(this, void 0);
         _Element_children.set(this, void 0);
         __classPrivateFieldSet(this, _Element_data, data, "f");
     }
+    /**
+     * Returns the element type discriminator (`svg`, `text`, `component`, …).
+     */
     type() {
         return __classPrivateFieldGet(this, _Element_data, "f").type;
     }
+    /**
+     * Returns the element's tag/component name, or `undefined` for elements
+     * that don't have one.
+     */
     name() {
         return __classPrivateFieldGet(this, _Element_data, "f").name;
     }
+    /**
+     * Returns the element's textual value (for `text` elements) or template
+     * fragment, or `undefined` when not applicable.
+     */
     value() {
         return __classPrivateFieldGet(this, _Element_data, "f").value;
     }
+    /**
+     * Returns the element's raw attribute map, or `undefined` when no
+     * attributes are defined.
+     */
     attributes() {
         return __classPrivateFieldGet(this, _Element_data, "f").attributes;
     }
+    /**
+     * Returns the element's children, lazily wrapped as {@link Element}
+     * instances on first access.
+     */
     children() {
         __classPrivateFieldSet(this, _Element_children, __classPrivateFieldGet(this, _Element_children, "f") ?? (__classPrivateFieldGet(this, _Element_data, "f").children ?? []).map((child) => new Element(child)), "f");
         return __classPrivateFieldGet(this, _Element_children, "f");

package/lib/Style/Meta.d.ts

@@ -2,10 +2,26 @@ import type { StyleDefinitionMeta } from '../StyleDefinition.js';
 import { MetaLicense } from './MetaLicense.js';
 import { MetaCreator } from './MetaCreator.js';
 import { MetaSource } from './MetaSource.js';
+/**
+ * Lazily-constructed view over a style definition's `meta` block, exposing
+ * the license, creator, and source descriptors.
+ */
 export declare class Meta {
     #private;
     constructor(data: StyleDefinitionMeta);
+    /**
+     * Returns the license descriptor, defaulting to an empty object when the
+     * style definition omits the field.
+     */
     license(): MetaLicense;
+    /**
+     * Returns the creator descriptor, defaulting to an empty object when the
+     * style definition omits the field.
+     */
     creator(): MetaCreator;
+    /**
+     * Returns the source descriptor, defaulting to an empty object when the
+     * style definition omits the field.
+     */
     source(): MetaSource;
 }

package/lib/Style/Meta.js

@@ -13,6 +13,10 @@ var _Meta_data, _Meta_license, _Meta_creator, _Meta_source;
 import { MetaLicense } from './MetaLicense.js';
 import { MetaCreator } from './MetaCreator.js';
 import { MetaSource } from './MetaSource.js';
+/**
+ * Lazily-constructed view over a style definition's `meta` block, exposing
+ * the license, creator, and source descriptors.
+ */
 export class Meta {
     constructor(data) {
         _Meta_data.set(this, void 0);
@@ -21,14 +25,26 @@ export class Meta {
         _Meta_source.set(this, void 0);
         __classPrivateFieldSet(this, _Meta_data, data, "f");
     }
+    /**
+     * Returns the license descriptor, defaulting to an empty object when the
+     * style definition omits the field.
+     */
     license() {
         __classPrivateFieldSet(this, _Meta_license, __classPrivateFieldGet(this, _Meta_license, "f") ?? new MetaLicense(__classPrivateFieldGet(this, _Meta_data, "f").license ?? {}), "f");
         return __classPrivateFieldGet(this, _Meta_license, "f");
     }
+    /**
+     * Returns the creator descriptor, defaulting to an empty object when the
+     * style definition omits the field.
+     */
     creator() {
         __classPrivateFieldSet(this, _Meta_creator, __classPrivateFieldGet(this, _Meta_creator, "f") ?? new MetaCreator(__classPrivateFieldGet(this, _Meta_data, "f").creator ?? {}), "f");
         return __classPrivateFieldGet(this, _Meta_creator, "f");
     }
+    /**
+     * Returns the source descriptor, defaulting to an empty object when the
+     * style definition omits the field.
+     */
     source() {
         __classPrivateFieldSet(this, _Meta_source, __classPrivateFieldGet(this, _Meta_source, "f") ?? new MetaSource(__classPrivateFieldGet(this, _Meta_data, "f").source ?? {}), "f");
         return __classPrivateFieldGet(this, _Meta_source, "f");

package/lib/Style/MetaCreator.d.ts

@@ -1,7 +1,16 @@
 import type { StyleDefinitionMetaCreator } from '../StyleDefinition.js';
+/**
+ * Read-only view over the `meta.creator` block of a style definition.
+ */
 export declare class MetaCreator {
     #private;
     constructor(data: StyleDefinitionMetaCreator);
+    /**
+     * Returns the creator's display name, or `undefined` when not set.
+     */
     name(): string | undefined;
+    /**
+     * Returns the creator's homepage URL, or `undefined` when not set.
+     */
     url(): string | undefined;
 }

package/lib/Style/MetaCreator.js

@@ -10,14 +10,23 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
     return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
 };
 var _MetaCreator_data;
+/**
+ * Read-only view over the `meta.creator` block of a style definition.
+ */
 export class MetaCreator {
     constructor(data) {
         _MetaCreator_data.set(this, void 0);
         __classPrivateFieldSet(this, _MetaCreator_data, data, "f");
     }
+    /**
+     * Returns the creator's display name, or `undefined` when not set.
+     */
     name() {
         return __classPrivateFieldGet(this, _MetaCreator_data, "f").name;
     }
+    /**
+     * Returns the creator's homepage URL, or `undefined` when not set.
+     */
     url() {
         return __classPrivateFieldGet(this, _MetaCreator_data, "f").url;
     }

package/lib/Style/MetaLicense.d.ts

@@ -1,8 +1,20 @@
 import type { StyleDefinitionMetaLicense } from '../StyleDefinition.js';
+/**
+ * Read-only view over the `meta.license` block of a style definition.
+ */
 export declare class MetaLicense {
     #private;
     constructor(data: StyleDefinitionMetaLicense);
+    /**
+     * Returns the license name (e.g. `"CC BY 4.0"`), or `undefined` when not set.
+     */
     name(): string | undefined;
+    /**
+     * Returns the license URL, or `undefined` when not set.
+     */
     url(): string | undefined;
+    /**
+     * Returns the full license text, or `undefined` when not set.
+     */
     text(): string | undefined;
 }

package/lib/Style/MetaLicense.js

@@ -10,17 +10,29 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
     return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
 };
 var _MetaLicense_data;
+/**
+ * Read-only view over the `meta.license` block of a style definition.
+ */
 export class MetaLicense {
     constructor(data) {
         _MetaLicense_data.set(this, void 0);
         __classPrivateFieldSet(this, _MetaLicense_data, data, "f");
     }
+    /**
+     * Returns the license name (e.g. `"CC BY 4.0"`), or `undefined` when not set.
+     */
     name() {
         return __classPrivateFieldGet(this, _MetaLicense_data, "f").name;
     }
+    /**
+     * Returns the license URL, or `undefined` when not set.
+     */
     url() {
         return __classPrivateFieldGet(this, _MetaLicense_data, "f").url;
     }
+    /**
+     * Returns the full license text, or `undefined` when not set.
+     */
     text() {
         return __classPrivateFieldGet(this, _MetaLicense_data, "f").text;
     }

package/lib/Style/MetaSource.d.ts

@@ -1,7 +1,17 @@
 import type { StyleDefinitionMetaSource } from '../StyleDefinition.js';
+/**
+ * Read-only view over the `meta.source` block of a style definition.
+ */
 export declare class MetaSource {
     #private;
     constructor(data: StyleDefinitionMetaSource);
+    /**
+     * Returns the source name (e.g. the original work title), or `undefined`
+     * when not set.
+     */
     name(): string | undefined;
+    /**
+     * Returns the URL of the source, or `undefined` when not set.
+     */
     url(): string | undefined;
 }

package/lib/Style/MetaSource.js

@@ -10,14 +10,24 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
     return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
 };
 var _MetaSource_data;
+/**
+ * Read-only view over the `meta.source` block of a style definition.
+ */
 export class MetaSource {
     constructor(data) {
         _MetaSource_data.set(this, void 0);
         __classPrivateFieldSet(this, _MetaSource_data, data, "f");
     }
+    /**
+     * Returns the source name (e.g. the original work title), or `undefined`
+     * when not set.
+     */
     name() {
         return __classPrivateFieldGet(this, _MetaSource_data, "f").name;
     }
+    /**
+     * Returns the URL of the source, or `undefined` when not set.
+     */
     url() {
         return __classPrivateFieldGet(this, _MetaSource_data, "f").url;
     }

package/lib/Style.d.ts

@@ -1,18 +1,54 @@
-import type { StyleDefinitionAttributes } from './StyleDefinition.js';
+import type { StyleDefinition, StyleDefinitionAttributes } from './StyleDefinition.js';
 import { Meta } from './Style/Meta.js';
 import { Canvas } from './Style/Canvas.js';
 import { Component } from './Style/Component.js';
 import { Color } from './Style/Color.js';
 export type { StyleDefinition } from './StyleDefinition.js';
+/**
+ * Validated, lazily-decomposed wrapper around a style definition. Construction
+ * runs the JSON Schema validator and stores a deep clone of the input so that
+ * later mutation of the source object cannot leak into the rendered avatar.
+ */
 export declare class Style<D = unknown> {
     #private;
     constructor(data: D);
+    /**
+     * Returns the definition's `$id`, or `undefined` when not set.
+     */
     id(): string | undefined;
+    /**
+     * Returns the definition's `$schema` URI, or `undefined` when not set.
+     */
     schema(): string | undefined;
+    /**
+     * Returns the definition's `$comment`, or `undefined` when not set.
+     */
     comment(): string | undefined;
+    /**
+     * Returns the {@link Meta} view, lazily constructed on first access.
+     */
     meta(): Meta;
+    /**
+     * Returns a deep clone of the root SVG attributes from the definition,
+     * defaulting to an empty object.
+     */
     attributes(): StyleDefinitionAttributes;
+    /**
+     * Returns a deep clone of the underlying definition.
+     */
+    definition(): StyleDefinition;
+    /**
+     * Returns the {@link Canvas} view, lazily constructed on first access.
+     */
     canvas(): Canvas;
+    /**
+     * Returns a name → {@link Component} map for all defined components, built
+     * lazily on first access.
+     */
     components(): ReadonlyMap<string, Component>;
+    /**
+     * Returns a name → {@link Color} map for all defined colors, built lazily
+     * on first access.
+     */
     colors(): ReadonlyMap<string, Color>;
 }

package/lib/Style.js

@@ -9,14 +9,21 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
     if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
     return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
 };
-var _Style_data, _Style_meta, _Style_canvas, _Style_components, _Style_colors;
+var _Style_instances, _a, _Style_data, _Style_meta, _Style_canvas, _Style_components, _Style_colors, _Style_validateAliases, _Style_isAlias;
 import { StyleValidator } from './Validator/StyleValidator.js';
+import { StyleValidationError } from './Error/StyleValidationError.js';
 import { Meta } from './Style/Meta.js';
 import { Canvas } from './Style/Canvas.js';
 import { Component } from './Style/Component.js';
 import { Color } from './Style/Color.js';
+/**
+ * Validated, lazily-decomposed wrapper around a style definition. Construction
+ * runs the JSON Schema validator and stores a deep clone of the input so that
+ * later mutation of the source object cannot leak into the rendered avatar.
+ */
 export class Style {
     constructor(data) {
+        _Style_instances.add(this);
         _Style_data.set(this, void 0);
         _Style_meta.set(this, void 0);
         _Style_canvas.set(this, void 0);
@@ -24,34 +31,80 @@ export class Style {
         _Style_colors.set(this, void 0);
         StyleValidator.validate(data);
         __classPrivateFieldSet(this, _Style_data, structuredClone(data), "f");
+        __classPrivateFieldGet(this, _Style_instances, "m", _Style_validateAliases).call(this);
     }
+    /**
+     * Returns the definition's `$id`, or `undefined` when not set.
+     */
     id() {
         return __classPrivateFieldGet(this, _Style_data, "f").$id;
     }
+    /**
+     * Returns the definition's `$schema` URI, or `undefined` when not set.
+     */
     schema() {
         return __classPrivateFieldGet(this, _Style_data, "f").$schema;
     }
+    /**
+     * Returns the definition's `$comment`, or `undefined` when not set.
+     */
     comment() {
         return __classPrivateFieldGet(this, _Style_data, "f").$comment;
     }
+    /**
+     * Returns the {@link Meta} view, lazily constructed on first access.
+     */
     meta() {
         __classPrivateFieldSet(this, _Style_meta, __classPrivateFieldGet(this, _Style_meta, "f") ?? new Meta(__classPrivateFieldGet(this, _Style_data, "f").meta ?? {}), "f");
         return __classPrivateFieldGet(this, _Style_meta, "f");
     }
+    /**
+     * Returns a deep clone of the root SVG attributes from the definition,
+     * defaulting to an empty object.
+     */
     attributes() {
         return structuredClone(__classPrivateFieldGet(this, _Style_data, "f").attributes ?? {});
     }
+    /**
+     * Returns a deep clone of the underlying definition.
+     */
+    definition() {
+        return structuredClone(__classPrivateFieldGet(this, _Style_data, "f"));
+    }
+    /**
+     * Returns the {@link Canvas} view, lazily constructed on first access.
+     */
     canvas() {
         __classPrivateFieldSet(this, _Style_canvas, __classPrivateFieldGet(this, _Style_canvas, "f") ?? new Canvas(__classPrivateFieldGet(this, _Style_data, "f").canvas), "f");
         return __classPrivateFieldGet(this, _Style_canvas, "f");
     }
+    /**
+     * Returns a name → {@link Component} map for all defined components, built
+     * lazily on first access.
+     */
     components() {
-        __classPrivateFieldSet(this, _Style_components, __classPrivateFieldGet(this, _Style_components, "f") ?? new Map(Object.entries(__classPrivateFieldGet(this, _Style_data, "f").components ?? {}).map(([name, data]) => [
-            name,
-            new Component(data),
-        ])), "f");
+        if (__classPrivateFieldGet(this, _Style_components, "f")) {
+            return __classPrivateFieldGet(this, _Style_components, "f");
+        }
+        const entries = Object.entries(__classPrivateFieldGet(this, _Style_data, "f").components ?? {});
+        const map = new Map();
+        for (const [name, data] of entries) {
+            if (!__classPrivateFieldGet(_a, _a, "m", _Style_isAlias).call(_a, data)) {
+                map.set(name, new Component(name, data));
+            }
+        }
+        for (const [name, data] of entries) {
+            if (__classPrivateFieldGet(_a, _a, "m", _Style_isAlias).call(_a, data)) {
+                map.set(name, new Component(name, data, map.get(data.extends)));
+            }
+        }
+        __classPrivateFieldSet(this, _Style_components, map, "f");
         return __classPrivateFieldGet(this, _Style_components, "f");
     }
+    /**
+     * Returns a name → {@link Color} map for all defined colors, built lazily
+     * on first access.
+     */
     colors() {
         __classPrivateFieldSet(this, _Style_colors, __classPrivateFieldGet(this, _Style_colors, "f") ?? new Map(Object.entries(__classPrivateFieldGet(this, _Style_data, "f").colors ?? {}).map(([name, data]) => [
             name,
@@ -60,4 +113,35 @@ export class Style {
         return __classPrivateFieldGet(this, _Style_colors, "f");
     }
 }
-_Style_data = new WeakMap(), _Style_meta = new WeakMap(), _Style_canvas = new WeakMap(), _Style_components = new WeakMap(), _Style_colors = new WeakMap();
+_a = Style, _Style_data = new WeakMap(), _Style_meta = new WeakMap(), _Style_canvas = new WeakMap(), _Style_components = new WeakMap(), _Style_colors = new WeakMap(), _Style_instances = new WeakSet(), _Style_validateAliases = function _Style_validateAliases() {
+    const components = __classPrivateFieldGet(this, _Style_data, "f").components;
+    if (!components) {
+        return;
+    }
+    const errors = [];
+    for (const [name, data] of Object.entries(components)) {
+        if (!__classPrivateFieldGet(_a, _a, "m", _Style_isAlias).call(_a, data)) {
+            continue;
+        }
+        const target = data.extends;
+        const targetData = components[target];
+        if (!targetData) {
+            errors.push({
+                instancePath: `/components/${name}/extends`,
+                message: `references unknown component "${target}"`,
+            });
+            continue;
+        }
+        if (__classPrivateFieldGet(_a, _a, "m", _Style_isAlias).call(_a, targetData)) {
+            errors.push({
+                instancePath: `/components/${name}/extends`,
+                message: `references alias "${target}" — alias chains are not allowed`,
+            });
+        }
+    }
+    if (errors.length > 0) {
+        throw new StyleValidationError(errors);
+    }
+}, _Style_isAlias = function _Style_isAlias(data) {
+    return 'extends' in data;
+};

package/lib/StyleDefinition.d.ts

@@ -18,11 +18,11 @@ export interface StyleDefinitionMeta {
 }
 export interface StyleDefinitionVariableReference {
     readonly type: 'variable';
-    readonly value: 'initial' | 'initials' | 'fontWeight' | 'fontFamily';
+    readonly name: 'initial' | 'initials' | 'fontWeight' | 'fontFamily';
 }
 export interface StyleDefinitionColorReference {
     readonly type: 'color';
-    readonly value: string;
+    readonly name: string;
 }
 export type StyleDefinitionColorAttributeValue = string | StyleDefinitionColorReference;
 export type StyleDefinitionElementValue = string | StyleDefinitionVariableReference;
@@ -63,14 +63,19 @@ export interface StyleDefinitionComponentVariant {
     readonly elements: readonly StyleDefinitionElement[];
     readonly weight?: number;
 }
-export interface StyleDefinitionComponent {
+export interface StyleDefinitionComponentBase {
     readonly width: number;
     readonly height: number;
     readonly probability?: number;
     readonly rotate?: readonly number[];
+    readonly scale?: readonly number[];
     readonly translate?: StyleDefinitionComponentTranslate;
     readonly variants: Readonly<Record<string, StyleDefinitionComponentVariant>>;
 }
+export interface StyleDefinitionComponentAlias {
+    readonly extends: string;
+}
+export type StyleDefinitionComponent = StyleDefinitionComponentBase | StyleDefinitionComponentAlias;
 export interface StyleDefinition {
     readonly $id?: string;
     readonly $schema?: string;

package/lib/StyleOptions.d.ts

@@ -7,11 +7,14 @@ type ColorNames<D> = D extends {
     colors: Record<infer K extends string, unknown>;
 } ? string extends K ? never : K : never;
 type AllColorNames<D> = ColorNames<D> | 'background';
-type VariantNames<D, C extends string> = D extends {
+type ResolveComponent<D, C extends string> = D extends {
     components: Record<string, unknown>;
 } ? C extends keyof D['components'] ? D['components'][C] extends {
+    extends: infer P extends string;
+} ? P extends keyof D['components'] ? D['components'][P] : never : D['components'][C] : never : never;
+type VariantNames<D, C extends string> = ResolveComponent<D, C> extends {
     variants: Record<infer V extends string, unknown>;
-} ? string extends V ? string : V : string : string : string;
+} ? string extends V ? string : V : string;
 type HasSpecificKeys<D> = [ComponentNames<D>] extends [never] ? [ColorNames<D>] extends [never] ? false : true : true;
 export interface StyleOptionsBase {
     readonly seed?: string;
@@ -28,16 +31,15 @@ export interface StyleOptionsBase {
     readonly translateY?: number | readonly [number, number];
 }
 type ComponentVariantOption<D, K extends string> = VariantNames<D, K> | readonly VariantNames<D, K>[] | Readonly<Partial<Record<VariantNames<D, K>, number>>>;
+type IsAlias<D, C extends string> = D extends {
+    components: Record<string, unknown>;
+} ? C extends keyof D['components'] ? D['components'][C] extends {
+    extends: string;
+} ? true : false : false : false;
 type ComponentOptions<D, C extends string> = [C] extends [never] ? unknown : {
-    readonly [K in C as `${K}Variant`]?: ComponentVariantOption<D, K>;
-} & {
-    readonly [K in C as `${K}Probability`]?: number;
-} & {
-    readonly [K in C as `${K}Rotate`]?: number | readonly [number, number];
-} & {
-    readonly [K in C as `${K}TranslateX`]?: number | readonly [number, number];
+    readonly [K in C as IsAlias<D, K> extends true ? never : `${K}Variant`]?: ComponentVariantOption<D, K>;
 } & {
-    readonly [K in C as `${K}TranslateY`]?: number | readonly [number, number];
+    readonly [K in C as IsAlias<D, K> extends true ? never : `${K}Probability`]?: number;
 };
 type ColorOptions<C extends string> = [C] extends [never] ? unknown : {
     readonly [K in C as `${K}Color`]?: string | readonly string[];

package/lib/Utils/Color.d.ts

@@ -1,9 +1,37 @@
+/**
+ * Color helpers used by the renderer and option resolver.
+ */
 export declare class Color {
     #private;
+    /**
+     * Normalizes any hex format to 6- or 8-digit lowercase with `#` prefix.
+     */
     static toHex(hex: string): string;
+    /**
+     * Like {@link toHex}, but strips the alpha channel and always returns
+     * 6-digit hex.
+     */
     static toRgbHex(hex: string): string;
+    /**
+     * Parses a hex color into an `[r, g, b]` triple of 8-bit channel values.
+     */
     static parseHex(hex: string): [number, number, number];
+    /**
+     * WCAG 2.1 relative luminance with sRGB linearization.
+     *
+     * @see https://www.w3.org/WAI/GL/wiki/Relative_luminance
+     */
     static luminance(hex: string): number;
+    /**
+     * Returns a new array sorted by descending contrast against the reference
+     * color.
+     *
+     * @see https://www.w3.org/WAI/GL/wiki/Contrast_ratio
+     */
     static sortByContrast(candidates: readonly string[], refColor: string): string[];
+    /**
+     * Returns a new array with excluded colors removed. Falls back to the
+     * original candidates when filtering would empty the list.
+     */
     static filterNotEqualTo(candidates: readonly string[], excluded: readonly string[]): string[];
 }

package/lib/Utils/Color.js

@@ -4,8 +4,13 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
     return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
 };
 var _a, _Color_linearize;
+/**
+ * Color helpers used by the renderer and option resolver.
+ */
 export class Color {
-    // Normalizes any hex format to 6- or 8-digit lowercase with '#' prefix.
+    /**
+     * Normalizes any hex format to 6- or 8-digit lowercase with `#` prefix.
+     */
     static toHex(hex) {
         const h = hex.replace(/^#/, '').toLowerCase();
         if (h.length === 3) {
@@ -16,11 +21,17 @@ export class Color {
         }
         return '#' + h;
     }
-    // Like toHex, but strips the alpha channel to always return 6-digit hex.
+    /**
+     * Like {@link toHex}, but strips the alpha channel and always returns
+     * 6-digit hex.
+     */
     static toRgbHex(hex) {
         const h = this.toHex(hex);
         return h.length > 7 ? h.slice(0, 7) : h;
     }
+    /**
+     * Parses a hex color into an `[r, g, b]` triple of 8-bit channel values.
+     */
     static parseHex(hex) {
         const h = this.toHex(hex).slice(1);
         return [
@@ -29,8 +40,11 @@ export class Color {
             parseInt(h.slice(4, 6), 16),
         ];
     }
-    // WCAG 2.1 relative luminance with sRGB linearization.
-    // https://www.w3.org/WAI/GL/wiki/Relative_luminance
+    /**
+     * WCAG 2.1 relative luminance with sRGB linearization.
+     *
+     * @see https://www.w3.org/WAI/GL/wiki/Relative_luminance
+     */
     static luminance(hex) {
         const rgb = this.parseHex(hex);
         const linearR = __classPrivateFieldGet(this, _a, "m", _Color_linearize).call(this, rgb[0]);
@@ -38,8 +52,12 @@ export class Color {
         const linearB = __classPrivateFieldGet(this, _a, "m", _Color_linearize).call(this, rgb[2]);
         return 0.2126 * linearR + 0.7152 * linearG + 0.0722 * linearB;
     }
-    // Returns a new array sorted by descending contrast against the reference color.
-    // https://www.w3.org/WAI/GL/wiki/Contrast_ratio
+    /**
+     * Returns a new array sorted by descending contrast against the reference
+     * color.
+     *
+     * @see https://www.w3.org/WAI/GL/wiki/Contrast_ratio
+     */
     static sortByContrast(candidates, refColor) {
         const refLum = this.luminance(refColor);
         const withRatio = candidates.map((c) => {
@@ -50,8 +68,10 @@ export class Color {
         withRatio.sort((a, b) => b.ratio - a.ratio);
         return withRatio.map((e) => e.color);
     }
-    // Returns a new array with excluded colors removed.
-    // Returns the original candidates if filtering would empty the list.
+    /**
+     * Returns a new array with excluded colors removed. Falls back to the
+     * original candidates when filtering would empty the list.
+     */
     static filterNotEqualTo(candidates, excluded) {
         const normalized = new Set(excluded.map((c) => this.toRgbHex(c)));
         const filtered = candidates.filter((c) => !normalized.has(this.toRgbHex(c)));

package/lib/Utils/Initials.d.ts

@@ -1,3 +1,13 @@
+/**
+ * Derives display initials from a seed string.
+ *
+ * @see https://www.regular-expressions.info/unicode.html
+ */
 export declare class Initials {
+    /**
+     * Returns one or two uppercase initials for the given seed. By default
+     * strips `@...` so email addresses yield a single initial instead of being
+     * treated as two words.
+     */
     static fromSeed(seed: string, discardAtSymbol?: boolean): string;
 }