@design-token-kit/core 0.2.0 → 0.3.0

package/lib/index.d.ts

@@ -109,10 +109,23 @@ export declare class DesignTokens {
  */
 export declare class Dtcg {
     #private;
-    constructor(root: TokenGroup);
-    /** Returns the top-level child token or group with the given name, or undefined. */
+    /**
+     * The origin of this token document.
+     *
+     * Can be a file path ({@code "tokens.json"}), a URL, or
+     * {@code "-"} for stdin.
+     * Used in validation diagnostics as the {@code sourcePath}.
+     */
+    readonly source?: string;
+    constructor(root: TokenGroup, source?: string);
+    /**
+     * 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. */
+    /**
+     * 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>]>;
@@ -124,7 +137,7 @@ export declare class Dtcg {
      *   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[];
+    validate(base?: Dtcg): ValidationIssue[];
 }
 
 /**
@@ -137,7 +150,7 @@ export declare class Dtcg {
  */
 export declare class DtcgJsonReader {
     #private;
-    parse(content: string): Dtcg;
+    parse(content: string, source?: string): Dtcg;
 }
 
 /**
@@ -169,7 +182,28 @@ export declare class DtcgList {
     readonly base: Dtcg;
     readonly themes: ReadonlyMap<string, Dtcg>;
     constructor(base: Dtcg, themes?: Map<string, Dtcg>);
-    validate(): DtcgValidationIssue[];
+    validate(): ValidationIssue[];
+}
+
+/**
+ * Loads and validates token sources, assembling a {@link DtcgList}.
+ *
+ * The first document is the base token set, subsequent documents are theme
+ * overrides.
+ *
+ * Sources in different formats may be mixed.
+ */
+export declare class DtcgListLoader {
+    #private;
+    /**
+     * Validates and loads all sources into a {@link DtcgList}.
+     *
+     * @param sources - Paths to token files or {@code "-"} for stdin.
+     * @param forcedFormat - When set, all sources are treated as this
+     *   format instead of auto-detecting from content.
+     * @throws TokenSyntaxError when schema validation fails.
+     */
+    load(sources: string[], forcedFormat?: Format): Promise<DtcgList>;
 }
 
 /**
@@ -182,7 +216,16 @@ export declare class DtcgSchemaValidator implements TokenValidator {
     validate(sources: string[]): Promise<ValidationIssue[]>;
 }
 
+/**
+ * Converts token documents in any supported format to CSS custom properties.
+ *
+ * The first document is treated as the base token set, all subsequent
+ * documents as theme overrides.
+ * Base tokens are emitted under {@code :root}.
+ * Theme tokens are emitted under {@code :root[data-theme="name"]}.
+ */
 export declare class DtcgTokenCssConverter implements TokenCssConverter {
+    #private;
     convert(sources: string[]): Promise<string>;
     convertDocument(doc: Dtcg): string;
     convertList(list: DtcgList): string;
@@ -193,20 +236,69 @@ export declare class DtcgTokenCssConverter implements TokenCssConverter {
  *
  * Accepts one base file plus optional theme files. Validates references,
  * cycles, type mismatches, and deprecated token usage.
+ *
+ * Format is detected from content, not from file extension.
+ * HRDT sources may contain multiple YAML documents separated by {@code ---}.
+ * The first document is the base, subsequent documents are themes.
  */
 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;
+/**
+ * Token formats.
+ */
+export declare enum Format {
+    /**
+     * DTCG (Design Tokens Community Group) JSON token format.
+     *
+     * @see https://tr.designtokens.org/format/
+     */
+    DTCG = "dtcg",
+    /**
+     * HRDT (Human-Readable Design Tokens) YAML token format.
+     */
+    HRDT = "hrdt",
+    /**
+     * CSS custom properties.
+     */
+    CSS = "css"
 }
 
-export declare type DtcgValidationSeverity = "error" | "warning";
+/**
+ * Detects the token format from raw content by inspecting the content
+ * structure rather than relying on file extensions.
+ *
+ * Supported formats: {@link Format.DTCG} (JSON), {@link Format.HRDT} (YAML),
+ * and {@link Format.CSS}.
+ */
+export declare class FormatDetector {
+    /**
+     * Detects the format of the given content.
+     *
+     * Detection rules:
+     * - If content starts with `{` and is valid JSON it is treated as DTCG.
+     * - If content contains CSS-specific patterns (`:root`, custom properties,
+     *   `@layer`) it is treated as CSS.
+     * - Otherwise it is treated as HRDT.
+     */
+    static detect(content: string): Format;
+    /**
+     * Returns `true` when the content looks like a DTCG JSON document.
+     *
+     * The check is structural: content must start with `{` and be parseable
+     * as JSON.
+     */
+    static isDtcg(content: string): boolean;
+    /**
+     * Returns `true` when the content looks like CSS.
+     *
+     * Detects the presence of CSS custom properties (`--name:`),
+     * {@code :root} selector, or {@code @layer} at-rules.
+     */
+    static isCss(content: string): boolean;
+}
 
 /**
  * Reads an HRDT token file and parses it directly into a {@link Dtcg} model.
@@ -218,7 +310,15 @@ export declare type DtcgValidationSeverity = "error" | "warning";
 export declare class HrdtTokenReader {
     #private;
     parseRaw(hrdtContent: string): unknown;
-    parse(hrdtContent: string): Dtcg;
+    parse(hrdtContent: string, source?: string): Dtcg;
+    /**
+     * Parses a YAML string that may contain multiple documents separated by
+     * {@code ---} and returns a {@link Dtcg} for each document.
+     *
+     * If the content contains a single document the result is a single-element
+     * array.
+     */
+    parseAll(hrdtContent: string, source?: string): Dtcg[];
     parseFile(filePath: string): Promise<Dtcg>;
 }
 
@@ -268,7 +368,7 @@ declare type ScopedTokenEntry = TokenEntry & {
 
 /**
  * Data source.
- * Wraps URL, File or content.
+ * Wraps URL, File, stdin ({@code "-"}) or raw content.
  *
  * Allows returning any of these data sources as a file.
  * Used in tool implementations to simplify the interface.
@@ -278,6 +378,7 @@ export declare class Source {
     constructor(input: string);
     getInput(): string;
     getType(): SourceType;
+    getFormat(): Promise<Format>;
     getContent(): Promise<string>;
     getFile(): Promise<string>;
 }
@@ -285,7 +386,8 @@ export declare class Source {
 declare enum SourceType {
     URL = "url",
     FILE = "file",
-    CONTENT = "content"
+    CONTENT = "content",
+    STDIN = "stdin"
 }
 
 declare type ThemeBucket = {
@@ -561,6 +663,17 @@ export declare class TokenReference {
     toString(): string;
 }
 
+/**
+ * Thrown by {@link DtcgListLoader.load} when schema validation fails.
+ *
+ * The {@link issues} field contains individual validation diagnostics.
+ */
+export declare class TokenSyntaxError extends Error {
+    readonly issues: ValidationIssue[];
+    constructor(issues: ValidationIssue[]);
+    formatIssues(): string;
+}
+
 /**
  * All token types defined in the DTCG 2025.10 specification.
  *
@@ -590,9 +703,11 @@ export declare interface TokenValidator {
  */
 export declare interface ValidationIssue {
     /** Name of the validator that issued the diagnostic. */
-    name: string;
+    name?: string;
     /** Path to the source file. */
-    sourcePath: string;
+    sourcePath?: string;
+    /** Dot-separated path to the token or group where the issue was found. */
+    tokenPath?: string;
     /** Message text. */
     message: string;
     /** Severity level. */