@design-token-kit/core 0.1.1

package/lib/index.d.ts

@@ -0,0 +1,608 @@
+export declare function createTokenCssConverter(): TokenCssConverter;
+
+export declare function createTokenHtmlShowcase(): TokenHtmlShowcase;
+
+/**
+ * Parses generated CSS variables into a structure for the HTML showcase.
+ *
+ * @remarks
+ * Finds `:root { ... }` blocks, extracts CSS custom properties from them
+ * and keeps the link to themes from `Set` and `Modifier` comments.
+ *
+ * Returns:
+ * - a full list of all found tokens;
+ * - a list of tokens grouped by themes.
+ */
+declare class CssTokenParser {
+    parse(cssString: string): ParsedTokenCss;
+    private extractModifierThemeName;
+    private extractBlockEntries;
+}
+
+/**
+ * A single design token, identified by file name.
+ *
+ * @remarks
+ * The theme is extracted from the file name:
+ * - `tokens.dark.json` → theme `dark`
+ * - `base.json` → theme `base`
+ * The first token in the {@link DesignTokens} collection is marked as base.
+ */
+export declare class DesignToken {
+    #private;
+    /** Theme name extracted from the file name. */
+    readonly themeName: string;
+    /**
+     * @param name - Path to the token file or its name.
+     * @param isBase - Whether the token is base.
+     */
+    constructor(name: string, isBase: boolean);
+    /** Whether the token is base. */
+    get isBase(): boolean;
+    /**
+     * Token theme name.
+     * @deprecated Use {@link DesignToken.themeName}.
+     */
+    get name(): string;
+    /**
+     * CSS selector for the token theme.
+     * @returns `:root` for base theme, `:root[data-theme="<theme>"]` for others.
+     */
+    get selector(): string;
+}
+
+/**
+ * Ordered collection of design tokens.
+ *
+ * @remarks
+ * The first token in the collection is always the base token.
+ * Use {@link DesignTokens.fromNames} to create from a list of file names
+ * or {@link DesignTokens.scan} to scan a directory.
+ */
+export declare class DesignTokens {
+    readonly tokens: DesignToken[];
+    private constructor();
+    /**
+     * Scans a directory and creates a collection from found token files.
+     *
+     * @param directory - Path to the directory to scan.
+     * @returns Collection of tokens sorted by file name.
+     * @throws Error if directory is empty.
+     */
+    static scan(directory: string): Promise<DesignTokens>;
+    /**
+     * Creates a token collection from an array of file names.
+     *
+     * @param names - Array of token file paths or names.
+     *   The first element is considered the base token.
+     * @returns Collection of tokens in the order of given names.
+     * @throws Error if the array is empty.
+     */
+    static fromNames(names: string[]): DesignTokens;
+    /** Whether the collection has a base token. */
+    get hasBaseToken(): boolean;
+    /** The base token of the collection (first token). */
+    get baseToken(): DesignToken;
+    /**
+     * Returns a token by theme name.
+     *
+     * @param themeName - Theme name (for example, `"dark"`, `"high-contrast"`).
+     * @returns Token with the given theme.
+     * @throws Error if the token with the given theme is not found.
+     */
+    getToken(themeName: string): DesignToken;
+    /**
+     * Returns a CSS selector for the given theme.
+     *
+     * @param themeName - Theme name.
+     * @param isBase - Whether the theme is base (`:root`).
+     * @returns CSS selector for the theme.
+     * @throws Error if the theme is not base and is not found in the collection.
+     */
+    getSelector(themeName: string, isBase: boolean): string;
+}
+
+/**
+ * The root of a DTCG token document, corresponding to a single `.json` file.
+ *
+ * @see https://tr.designtokens.org/format/#file-format
+ */
+export declare class Dtcg {
+    #private;
+    constructor(root: TokenGroup);
+    /** Returns the top-level child token or group with the given name, or undefined. */
+    get(name: string): TokenGroup | TokenNode<unknown> | undefined;
+    /** Returns all top-level child names in insertion order. */
+    keys(): IterableIterator<string>;
+    /** Returns all top-level child entries as [name, node] pairs in insertion order. */
+    entries(): IterableIterator<[string, TokenGroup | TokenNode<unknown>]>;
+    get size(): number;
+    /**
+     * Validates the document and returns all found issues.
+     *
+     * @param base - Optional base document to use as fallback when resolving references.
+     *   Pass the base document when validating a theme file, so that references to tokens
+     *   defined in the base are resolved correctly.
+     */
+    validate(base?: Dtcg): DtcgValidationIssue[];
+}
+
+/**
+ * Parses a DTCG 2025.10 JSON document into a {@link Dtcg}.
+ *
+ * A child object is treated as a token when it contains `$value` or `$ref`,
+ * and as a group otherwise.
+ *
+ * @see https://tr.designtokens.org/format/
+ */
+export declare class DtcgJsonReader {
+    #private;
+    parse(content: string): Dtcg;
+}
+
+/**
+ * Thrown when the input JSON does not conform to the expected DTCG structure.
+ */
+export declare class DtcgJsonReaderError extends Error {
+    constructor(message: string);
+}
+
+/**
+ * Serializes a {@link Dtcg} document to a DTCG JSON string.
+ *
+ * @see https://tr.designtokens.org/format/
+ */
+export declare class DtcgJsonWriter {
+    #private;
+    write(doc: Dtcg): string;
+}
+
+/**
+ * An ordered collection of DTCG documents representing a base token set and its theme overrides.
+ *
+ * The base document defines all tokens. Each theme document overrides a subset of them.
+ * When validating a theme, references are resolved against the theme first, then the base.
+ *
+ * @see https://tr.designtokens.org/format/#file-format
+ */
+export declare class DtcgList {
+    readonly base: Dtcg;
+    readonly themes: ReadonlyMap<string, Dtcg>;
+    constructor(base: Dtcg, themes?: Map<string, Dtcg>);
+    validate(): DtcgValidationIssue[];
+}
+
+/**
+ * Validates DTCG JSON sources against the official DTCG JSON Schema.
+ * Accepts DTCG JSON sources only.
+ */
+export declare class DtcgSchemaValidator implements TokenValidator {
+    #private;
+    readonly name = "dtcg";
+    validate(sources: string[]): Promise<ValidationIssue[]>;
+}
+
+export declare class DtcgTokenCssConverter implements TokenCssConverter {
+    convert(sources: string[]): Promise<string>;
+    convertDocument(doc: Dtcg): string;
+    convertList(list: DtcgList): string;
+}
+
+/**
+ * Validates DTCG JSON or HRDT token files using the internal model.
+ *
+ * Accepts one base file plus optional theme files. Validates references,
+ * cycles, type mismatches, and deprecated token usage.
+ */
+export declare class DtcgTokenValidator implements TokenValidator {
+    #private;
+    validate(sources: string[]): Promise<ValidationIssue[]>;
+}
+
+export declare interface DtcgValidationIssue {
+    /** Dot-separated path to the token or group where the issue was found. */
+    tokenPath: string;
+    severity: DtcgValidationSeverity;
+    message: string;
+}
+
+export declare type DtcgValidationSeverity = "error" | "warning";
+
+/**
+ * Reads an HRDT token file and parses it directly into a {@link Dtcg} model.
+ *
+ * The HRDT format uses YAML syntax and group path to infer token types
+ * (e.g. `primitive.color.*` -> color tokens). Non-primitive groups
+ * contain alias references to primitive tokens.
+ */
+export declare class HrdtTokenReader {
+    #private;
+    parseRaw(hrdtContent: string): unknown;
+    parse(hrdtContent: string): Dtcg;
+    parseFile(filePath: string): Promise<Dtcg>;
+}
+
+/**
+ * Thrown when the YAML content does not conform to the HRDT token format.
+ */
+export declare class HrdtTokenReaderError extends Error {
+    constructor(message: string);
+}
+
+/**
+ * Validator based on AJV and JSON Schema.
+ * Accepts HRDT sources only.
+ */
+export declare class HrdtTokenValidator implements TokenValidator {
+    #private;
+    readonly name = "hrdt";
+    validate(sources: string[]): Promise<ValidationIssue[]>;
+}
+
+/**
+ * Serializes a {@link Dtcg} document to the HRDT token format.
+ *
+ * The HRDT format uses YAML syntax and mirrors what {@link HrdtTokenReader} accepts:
+ * primitive tokens are grouped by type under `primitive.<type>`,
+ * all other groups contain only alias references.
+ */
+export declare class HrdtTokenWriter {
+    #private;
+    write(doc: Dtcg): string;
+}
+
+/**
+ * Severity level of a diagnostic.
+ */
+export declare type IssueSeverity = "error" | "warning";
+
+declare type ParsedTokenCss = {
+    entries: ScopedTokenEntry[];
+    themes: ThemeBucket[];
+};
+
+declare type ScopedTokenEntry = TokenEntry & {
+    scope: string;
+    themeName?: string;
+};
+
+/**
+ * Data source.
+ * Wraps URL, File or content.
+ *
+ * Allows returning any of these data sources as a file.
+ * Used in tool implementations to simplify the interface.
+ */
+export declare class Source {
+    #private;
+    constructor(input: string);
+    getInput(): string;
+    getType(): SourceType;
+    getContent(): Promise<string>;
+    getFile(): Promise<string>;
+}
+
+declare enum SourceType {
+    URL = "url",
+    FILE = "file",
+    CONTENT = "content"
+}
+
+declare type ThemeBucket = {
+    name: string;
+    entries: ScopedTokenEntry[];
+};
+
+/**
+ * Converter for design tokens to CSS.
+ *
+ * @remarks
+ * Each converter implements its own engine for turning DTCG tokens
+ * into CSS custom properties. Input is an array of paths to JSON token files,
+ * output is a CSS string or error.
+ */
+export declare interface TokenCssConverter {
+    /**
+     * Converts token files to CSS.
+     *
+     * @param sources - Array of paths to token files in DTCG JSON format
+     * @returns Generated CSS
+     * @throws Error if conversion failed
+     */
+    convert(sources: string[]): Promise<string>;
+}
+
+declare type TokenEntry = {
+    name: string;
+    value: string;
+};
+
+/**
+ * A named container for tokens and nested groups.
+ *
+ * Groups may declare a `$type` that is inherited by all descendant tokens
+ * unless overridden at a lower level. Groups may also extend another group
+ * via `$extends`.
+ *
+ * @see https://tr.designtokens.org/format/#groups
+ */
+export declare class TokenGroup {
+    #private;
+    /** Inherited token type for descendant tokens that do not declare their own `$type`. */
+    readonly type: TokenType | undefined;
+    readonly description: string | undefined;
+    readonly deprecated: boolean | string | undefined;
+    readonly extensions: Record<string, unknown> | undefined;
+    /** Reference to the group this group extends, if any. */
+    readonly extends: TokenReference | string | undefined;
+    /**
+     * Optional root token for this group. Provides a base value while
+     * allowing for variants via nested tokens.
+     *
+     * @see https://tr.designtokens.org/format/#groups
+     */
+    readonly root: TokenNode<unknown> | undefined;
+    constructor(options?: {
+        type?: TokenType;
+        description?: string;
+        deprecated?: boolean | string;
+        extensions?: Record<string, unknown>;
+        extends?: TokenReference | string;
+        root?: TokenNode<unknown>;
+        children?: Map<string, TokenGroup | TokenNode<unknown>>;
+    });
+    /** Returns the child token or group with the given name, or undefined. */
+    get(name: string): TokenGroup | TokenNode<unknown> | undefined;
+    /** Returns all child names in insertion order. */
+    keys(): IterableIterator<string>;
+    /** Returns all child entries as [name, node] pairs in insertion order. */
+    entries(): IterableIterator<[string, TokenGroup | TokenNode<unknown>]>;
+    /** Returns true if this group contains a child with the given name. */
+    has(name: string): boolean;
+    get size(): number;
+}
+
+/**
+ * Groups tokens for display in the HTML showcase.
+ *
+ * @remarks
+ * Sorts tokens by scope: `primitive`, `semantic`, `component`,
+ * separates primitive themes and sorts groups in a stable order.
+ *
+ * For visual sections uses simple heuristics by name and value
+ * of CSS variable: colors, typography, spacing, shadows, motion and others.
+ */
+declare class TokenGroupClassifier {
+    #private;
+    groupEntriesByScope(entries: ScopedTokenEntry[]): Map<string, TokenEntry[]>;
+    getPrimitiveThemes(themes: ThemeBucket[]): ThemeBucket[];
+    getOrderedScopes(scopes: Map<string, TokenEntry[]>): Array<[string, TokenEntry[]]>;
+    groupTokens(tokens: TokenEntry[]): Map<string, TokenEntry[]>;
+    private classifyTokenGroup;
+}
+
+/**
+ * HTML showcase for design tokens.
+ *
+ * @remarks
+ * Each implementation provides its own engine for building the HTML showcase:
+ * - from DTCG JSON tokens using validate -> convert -> render chain;
+ * - from ready CSS (for a single source) using direct render.
+ * Input is an array of source file paths, output is an HTML string or error.
+ */
+export declare interface TokenHtmlShowcase {
+    /**
+     * Builds an HTML page from token files.
+     *
+     * @param sources - Array of paths to source files
+     * @returns HTML string of the showcase
+     * @throws Error if building the showcase failed
+     */
+    showcase(sources: string[]): Promise<string>;
+}
+
+/**
+ * Builds an HTML showcase from JSON tokens or ready CSS.
+ *
+ * @remarks
+ * Implements the common showcase pipeline and gives validation, conversion,
+ * CSS parsing and HTML rendering to separate classes.
+ */
+export declare class TokenHtmlShowcaseBuilder implements TokenHtmlShowcase {
+    #private;
+    constructor(validator: TokenValidator, converter: TokenCssConverter, parser?: CssTokenParser, renderer?: TokenHtmlShowcaseRenderer);
+    showcase(sources: string[]): Promise<string>;
+}
+
+/**
+ * Renders an HTML page for the token showcase.
+ *
+ * @remarks
+ * Gets prepared token data and builds a complete HTML page:
+ * layout, sidebar, sections, cards, preview elements and navigation script.
+ */
+declare class TokenHtmlShowcaseRenderer {
+    #private;
+    constructor(classifier?: TokenGroupClassifier);
+    renderPage(parsed: ParsedTokenCss): string;
+    private getVisibleScopes;
+    private getVisibleThemes;
+    private renderMenu;
+    private renderThemedMenu;
+    private renderScopeMenu;
+    private renderSemanticMenuLinks;
+    private renderSidebarToggle;
+    private renderFolderIcon;
+    private renderThemeSummary;
+    private renderTokens;
+    private renderThemedTokens;
+    private renderSemanticTokens;
+    private groupSemanticTokens;
+    private renderSemanticRole;
+    private renderSemanticPreview;
+    private renderSemanticReferences;
+    private renderSemanticParts;
+    private renderLinkedTokenValue;
+    private getCompositePartName;
+    private getSemanticWarnings;
+    private resolveTokenValue;
+    private resolveAggregateTokenValue;
+    private resolveAggregateGradientTokenValue;
+    private collectGradientStops;
+    private resolveAggregateTypographyTokenValue;
+    private collectIndexedValues;
+    private normalizeFontWeight;
+    private escapeRegExp;
+    private extractVarReferences;
+    private createTokenMap;
+    private dedupeTokens;
+    private cssVariableToTokenPath;
+    private getSemanticGroupKey;
+    private getSemanticRoleName;
+    private getSemanticRoleType;
+    private isRenderableColor;
+    private renderGroupedTokens;
+    private getDisplayGroups;
+    private renderMenuGroupLinks;
+    private sectionId;
+    private tokenId;
+    private renderGroupItems;
+    private renderBorderItems;
+    private renderTypographyItems;
+    private renderShadowItems;
+    private renderGradientItems;
+    private renderMotionItems;
+    private getFontCollectionEntryLabel;
+    private toFontVariantCard;
+    private getFontCollectionMetaLabel;
+    private getFontVariantPreviewStyle;
+    private renderFontVariantCard;
+    private renderBorderItem;
+    private renderShadowItem;
+    private renderGradientItem;
+    private renderGradientStops;
+    private renderTransitionItem;
+    private renderMotionTokenItem;
+    private renderMotionCard;
+    private renderMetaLine;
+    private formatGradientValue;
+    private formatGradientPosition;
+    private formatTransitionTiming;
+    private extractDurationValue;
+    private getMotionPreviewDuration;
+    private getMotionPreviewTiming;
+    private getMotionResolvedValue;
+    private normalizeMotionDuration;
+    private toMotionTitle;
+    private formatShadowLayer;
+    private formatShadowColor;
+    private renderBorderWidthItem;
+    private renderStrokeStyleItem;
+    private renderDimensionItem;
+    private renderRadiusItem;
+    private renderOpacityItem;
+    private parseOpacityValue;
+    private toDimensionTitle;
+    private getDimensionMarkerStyle;
+    private toTitleCase;
+    private renderTokenItem;
+    private renderGradientStopsFromValue;
+    private renderGroupBadge;
+    private getTypographyStyleParts;
+    private extractTypographyInfo;
+    private esc;
+}
+
+/**
+ * Base class for all DTCG token nodes.
+ *
+ * A token node holds either a direct value (`$value`) or an alias to another token (`$ref`).
+ * The `$type` field is inherited from the containing group when not explicitly set.
+ * Alias tokens without an explicit or inherited `$type` have `type = undefined`.
+ *
+ * @see https://tr.designtokens.org/format/#design-token
+ */
+export declare abstract class TokenNode<T> {
+    #private;
+    readonly description: string | undefined;
+    readonly deprecated: boolean | string | undefined;
+    readonly extensions: Record<string, unknown> | undefined;
+    protected constructor(type: TokenType | undefined, value: T | TokenReference, description?: string, deprecated?: boolean | string, extensions?: Record<string, unknown>);
+    /**
+     * The token's DTCG type, or `undefined` for alias tokens without an explicit
+     * or inherited `$type`.
+     */
+    get type(): TokenType | undefined;
+    /**
+     * The token's value, or a {@link TokenReference} when this token is an alias.
+     *
+     * @see https://tr.designtokens.org/format/#aliases-references
+     */
+    get value(): T | TokenReference;
+    /** Returns true when this token is an alias to another token. */
+    isAlias(): boolean;
+}
+
+/**
+ * A reference to another token using curly-brace notation, e.g. `{color.base.red}`.
+ *
+ * References are not resolved at model level - resolution is the responsibility
+ * of the consumer (resolver, converter, etc.).
+ *
+ * @see https://tr.designtokens.org/format/#aliases-references
+ */
+export declare class TokenReference {
+    #private;
+    /** @param value - token path without curly braces, e.g. `color.base.red` */
+    constructor(value: string);
+    /** Token path without curly braces, e.g. `color.base.red`. */
+    get value(): string;
+    /** Serializes to canonical curly-brace notation, e.g. `{color.base.red}`. */
+    toString(): string;
+}
+
+/**
+ * All token types defined in the DTCG 2025.10 specification.
+ *
+ * @see https://tr.designtokens.org/format/#types
+ */
+export declare type TokenType = "color" | "dimension" | "fontFamily" | "fontWeight" | "number" | "duration" | "cubicBezier" | "strokeStyle" | "border" | "transition" | "shadow" | "gradient" | "typography";
+
+/**
+ * Design tokens validator.
+ *
+ * @remarks
+ * Each validator puts its own check method for DTCG tokens.
+ * Input is an array of token file paths, output is a collection of diagnostics.
+ */
+export declare interface TokenValidator {
+    /**
+     * Validates token files.
+     *
+     * @param sources - Array of paths to token files in DTCG JSON format
+     * @returns Collection of validation diagnostics
+     */
+    validate(sources: string[]): Promise<ValidationIssue[]>;
+}
+
+/**
+ * A single validation diagnostic from a validator.
+ */
+export declare interface ValidationIssue {
+    /** Name of the validator that issued the diagnostic. */
+    name: string;
+    /** Path to the source file. */
+    sourcePath: string;
+    /** Message text. */
+    message: string;
+    /** Severity level. */
+    severity: IssueSeverity;
+    /** Line number (if available). */
+    line?: number;
+    /** Column number (if available). */
+    column?: number;
+    /** Raw data for debugging. */
+    raw?: unknown;
+}
+
+export { }