@adobe/design-data-wasm 0.4.0

package/pkg/node/design_data_wasm.d.ts

@@ -0,0 +1,439 @@
+/* tslint:disable */
+/* eslint-disable */
+/**
+ * A list of suggestion results from `Dataset.suggest()`. Typed as `SuggestResult[]` in TypeScript.
+ */
+export type SuggestResultArray = SuggestResult[];
+
+/**
+ * A list of token results from a query. Typed as `TokenResult[]` in TypeScript.
+ */
+export type TokenResultArray = TokenResult[];
+
+/**
+ * A mode-set context for token resolution.
+ *
+ * Maps mode-set names (e.g. `\"colorScheme\"`, `\"scale\"`) to their active mode
+ * values (e.g. `\"dark\"`, `\"medium\"`).
+ *
+ * ```ts
+ * const result = ds.resolve(\"background\", { colorScheme: \"dark\", scale: \"medium\" });
+ * ```
+ */
+export type ResolutionContext = Map<string, string>;
+
+/**
+ * A registry vocabulary object as read from `registry/*.json`.
+ */
+export interface RegistryObject {
+    values: RegistryEntry[];
+}
+
+/**
+ * A single entry in a registry vocabulary (e.g. a size, state, or variant).
+ *
+ * Mirrors the shape of each object in `registry/*.json#values`.
+ */
+export interface RegistryEntry {
+    id: string;
+    label?: string;
+    description?: string;
+    aliases?: string[];
+    default?: boolean;
+    deprecated?: boolean;
+}
+
+/**
+ * A single key→value change within a token\'s properties.
+ */
+export interface PropertyChange {
+    path: string;
+    changeType: string;
+    newValue?: Value;
+    originalValue?: Value;
+}
+
+/**
+ * A single ranked suggestion result from `Dataset.suggest()`.
+ */
+export interface SuggestResult {
+    tokenUuid?: string;
+    tokenName: string;
+    file: string;
+    layer: string;
+    confidence: number;
+    nameObject?: Value;
+    value?: Value;
+}
+
+/**
+ * A single resolved token result from `Dataset.resolve()`.
+ */
+export interface ResolveResult {
+    token: TokenResult;
+    specificity: number;
+}
+
+/**
+ * A single validation diagnostic.
+ */
+export interface Diagnostic {
+    severity: Severity;
+    message: string;
+    ruleId?: string;
+    path?: string;
+}
+
+/**
+ * A token record as returned by query results.
+ *
+ * Reflects `design_data_core::graph::TokenRecord` — the canonical token object
+ * including its `name`, `value`, `uuid`, `$schema`, etc. in `raw`.
+ */
+export interface TokenResult {
+    name: string;
+    /**
+     * The token\'s full source JSON (all fields: name, value, uuid, $schema, etc.)
+     */
+    raw: Value;
+    uuid?: string;
+    schemaUrl?: string;
+    aliasTarget?: string;
+    layer: string;
+}
+
+/**
+ * A token that gained a `deprecated` marker.
+ */
+export interface DeprecatedToken {
+    name: string;
+    uuid?: string;
+}
+
+/**
+ * A token that had its `deprecated` marker removed.
+ */
+export interface RevertedToken {
+    name: string;
+    uuid?: string;
+}
+
+/**
+ * A token that had property-level changes (same name, same UUID).
+ */
+export interface UpdatedToken {
+    name: string;
+    uuid?: string;
+    propertyChanges: PropertyChange[];
+}
+
+/**
+ * A token that was added.
+ */
+export interface AddedToken {
+    name: string;
+    uuid?: string;
+}
+
+/**
+ * A token that was deleted.
+ */
+export interface DeletedToken {
+    name: string;
+    uuid?: string;
+}
+
+/**
+ * A token that was renamed (same UUID, different name).
+ */
+export interface RenamedToken {
+    oldName: string;
+    newName: string;
+    uuid?: string;
+    propertyChanges: PropertyChange[];
+}
+
+/**
+ * Severity level of a validation diagnostic.
+ */
+export type Severity = "error" | "warning" | "info";
+
+/**
+ * The result of `Dataset.diff()`.
+ *
+ * Mirrors `design_data_core::diff::DiffReport` with typed arrays for each change category.
+ */
+export interface DiffResult {
+    renamed: RenamedToken[];
+    deprecated: DeprecatedToken[];
+    reverted: RevertedToken[];
+    added: AddedToken[];
+    deleted: DeletedToken[];
+    updated: UpdatedToken[];
+}
+
+/**
+ * The result of `Dataset.resolveReference()`.
+ *
+ * Contains the resolved terminal value and the full chain of names/references
+ * traversed to reach it — mirrors the `getResolutionChain()` behaviour from
+ * the legacy inline `TokenResolver` in `docs/s2-tokens-viewer/index.html`.
+ *
+ * ```ts
+ * const r = ds.resolveReference(\"{accent-color-100}\", { colorScheme: \"light\" });
+ * // r.chain → [\"{accent-color-100}\", \"{blue-100}\", \"rgb(245, 249, 255)\"]
+ * // r.value → \"rgb(245, 249, 255)\
+ * ```
+ */
+export interface ReferenceChainResult {
+    /**
+     * The resolved terminal value (absent if the chain is empty or all aliases dangle).
+     */
+    value?: Value;
+    /**
+     * Ordered list from original reference → intermediate names → final value string.
+     */
+    chain: string[];
+}
+
+/**
+ * The result of `Dataset.validate()`.
+ */
+export interface ValidationResult {
+    valid: boolean;
+    errors: Diagnostic[];
+    warnings: Diagnostic[];
+}
+
+
+/**
+ * A loaded token dataset you can query, validate, resolve, and diff.
+ *
+ * ```js
+ * import init, { Dataset } from "@adobe/design-data-wasm";
+ * await init();
+ *
+ * // Use the canonical embedded Spectrum dataset:
+ * const ds = Dataset.embedded();
+ * const results = ds.query("property=color,colorScheme=dark");
+ *
+ * // Or load your own tokens:
+ * const tokens = await fetch("/tokens.json").then(r => r.json());
+ * const ds2 = Dataset.fromTokens(tokens);
+ * ```
+ */
+export class Dataset {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Compute the semantic diff between this dataset and another.
+     *
+     * Returns a [`DiffResult`] with arrays of renamed, deprecated, reverted, added,
+     * deleted, and updated tokens.
+     *
+     * ```js
+     * const oldDs = Dataset.fromTokens(oldTokens);
+     * const newDs = Dataset.fromTokens(newTokens);
+     * const diff = oldDs.diff(newDs);
+     * console.log(`${diff.added.length} tokens added`);
+     * ```
+     */
+    diff(other: Dataset): DiffResult;
+    /**
+     * Open the canonical embedded Spectrum dataset from the prebuilt cache.
+     *
+     * The cache is opened once and reused; subsequent calls are cheap.
+     *
+     * Throws if the embedded cache was not generated (run `moon run sdk-wasm:cache-build`).
+     */
+    static embedded(): Dataset;
+    /**
+     * Build a dataset from an array of raw token JSON objects.
+     *
+     * Accepts the same format as the cascade token JSON files — an array of token
+     * objects each with a `name` object (e.g. `{ "name": { "property": "..." }, "value": ... }`).
+     *
+     * ```js
+     * const tokens = await fetch("/spectrum-tokens.json").then(r => r.json());
+     * const ds = Dataset.fromTokens(tokens);
+     * ```
+     */
+    static fromTokens(tokens_json: any): Dataset;
+    /**
+     * Emit a structural overview of the dataset for agent session start.
+     *
+     * Returns a plain JS object with the same shape as `design-data primer --format json`:
+     * `{ specVersion, tokenCount, modeSets, components, taxonomyFields, manifest, provenance }`.
+     *
+     * For the embedded Spectrum dataset (`Dataset.embedded()`), `taxonomyFields` and
+     * `manifest` are baked into the prebuilt `.redb` blob by the `cache-build` task.
+     * For in-memory datasets (`Dataset.fromTokens()`), both are empty / null.
+     *
+     * `provenance.source` is:
+     * - `"embedded"` when created via `Dataset.embedded()` (includes `designDataVersion`)
+     * - `"in-memory"` when created via `Dataset.fromTokens()`
+     */
+    primer(): any;
+    /**
+     * Filter tokens using a query expression.
+     *
+     * **Syntax:** `key=value` pairs separated by `,` (AND) or `|` (OR).
+     * Use `!=` for negation and `*` as a wildcard suffix or prefix.
+     * Valid keys: `property`, `component`, `variant`, `state`, `colorScheme`,
+     * `scale`, `contrast`, `uuid`, `$schema`.
+     *
+     * ```js
+     * const results = ds.query("property=color,colorScheme=dark");
+     * const all = ds.query("");   // returns all tokens
+     * ```
+     */
+    query(filter_expr: string): TokenResultArray;
+    /**
+     * Resolve a token for a given property in a specific context.
+     *
+     * The `context` object maps mode-set names to their active mode values —
+     * e.g. `{ colorScheme: "dark", scale: "medium" }`.
+     *
+     * Returns the winning token record plus its specificity, or `undefined` if
+     * no token matches the property+context combination.
+     *
+     * ```js
+     * const result = ds.resolve("background", { colorScheme: "dark", scale: "medium" });
+     * if (result) console.log(result.token.raw.value);
+     * ```
+     */
+    resolve(property: string, context: ResolutionContext): ResolveResult | undefined;
+    /**
+     * Resolve a legacy token reference by slug in a given context, returning
+     * the terminal value and the full alias chain.
+     *
+     * Bridges the legacy *object-map* slug model used by `docs/s2-tokens-viewer`
+     * to the cascade dataset.  The wasm `resolve()` method resolves by *property*
+     * name in a mode-set context; this method resolves by *legacy slug* and a flat
+     * context map matching name-object fields.
+     *
+     * Context keys mirror cascade name-object fields:
+     * - `{ colorScheme: "light" | "dark" | "wireframe" }`
+     * - `{ scale: "desktop" | "mobile" }`
+     *
+     * The candidate with the most matching context fields wins; tie-breaking is
+     * stable (secondary sort by uuid ascending).  When an alias chain passes through
+     * a set-level UUID, the context-appropriate child is selected so that e.g.
+     * `{accent-color-900}` under `{ colorScheme: "dark" }` correctly resolves to
+     * the dark variant of `{blue-900}`.
+     *
+     * Dangling aliases (a `$ref` target absent from the embedded dataset) are
+     * handled gracefully: the walk stops and the partial chain is returned with
+     * `value: undefined`.
+     *
+     * ```js
+     * const r = ds.resolveReference("{accent-color-100}", { colorScheme: "light" });
+     * // r.chain → ["{accent-color-100}", "{blue-100}", "rgb(245, 249, 255)"]
+     * // r.value → "rgb(245, 249, 255)"
+     * ```
+     */
+    resolveReference(token_ref: string, context: ResolutionContext): ReferenceChainResult | undefined;
+    /**
+     * Rank existing tokens by similarity to a natural-language `intent` string.
+     *
+     * Uses Jaccard similarity over the bag-of-words formed from each token's
+     * key segments, name-object field values, and description text.  Optionally
+     * filter to tokens matching a specific `propertyHint` (e.g. `"color"`).
+     *
+     * ```js
+     * const results = ds.suggest("primary button background", undefined, 5);
+     * ```
+     */
+    suggest(intent: string, property_hint: string | null | undefined, limit: number): SuggestResultArray;
+    /**
+     * Return the number of tokens in the dataset.
+     */
+    tokenCount(): number;
+    /**
+     * Run relational validation rules over the dataset.
+     *
+     * Returns a [`ValidationResult`] with `valid`, `errors`, and `warnings`.
+     * This runs the same rules as `design-data validate` but without structural
+     * (JSON Schema) checks — those require filesystem access unavailable in wasm.
+     *
+     * ```js
+     * const result = ds.validate();
+     * if (!result.valid) console.error(result.errors);
+     * ```
+     */
+    validate(): ValidationResult;
+}
+
+/**
+ * Find a registry entry by its ID or one of its aliases.
+ *
+ * Returns `undefined` if not found.
+ * Equivalent to `@adobe/design-system-registry`'s `findValue(registry, searchTerm)`.
+ */
+export function findValue(registry: any, search_term: string): any;
+
+/**
+ * Return all non-deprecated value entries.
+ *
+ * Equivalent to `@adobe/design-system-registry`'s `getActiveValues(registry)`.
+ */
+export function getActiveValues(registry: any): any;
+
+/**
+ * Return the list of advisory field names (fields whose values are informational,
+ * not normative — e.g. `"variant"`, `"state"`).
+ */
+export function getAdvisoryFields(): string[];
+
+/**
+ * Return the default value entry, or `undefined` if none is marked as default.
+ *
+ * Equivalent to `@adobe/design-system-registry`'s `getDefault(registry)`.
+ */
+export function getDefault(registry: any): any;
+
+/**
+ * Return all IDs (and aliases) registered for a given field name.
+ *
+ * `fieldName` should be the canonical field key as used in token `name` objects —
+ * e.g. `"property"`, `"component"`, `"variant"`, `"state"`.
+ *
+ * Returns `undefined` if the field is not in the embedded registry.
+ */
+export function getFieldValues(field_name: string): string[] | undefined;
+
+/**
+ * Return the list of field names that can be used as filter keys in query
+ * expressions (e.g. `"property"`, `"component"`, `"$schema"`).
+ *
+ * This is the canonical set maintained in `design_data_core::query::ALLOWED_KEYS`,
+ * exposed here so callers do not need to hard-code it.
+ */
+export function getIndexedFields(): string[];
+
+/**
+ * Return all value IDs from a registry vocabulary object.
+ *
+ * Equivalent to `@adobe/design-system-registry`'s `getValues(registry)`.
+ */
+export function getValues(registry: any): string[];
+
+/**
+ * Return `true` if `value` (an ID or alias) is registered for `fieldName`.
+ */
+export function hasFieldValue(field_name: string, value: string): boolean;
+
+/**
+ * Return `true` if `searchTerm` matches any value ID or alias in the registry.
+ *
+ * Equivalent to `@adobe/design-system-registry`'s `hasValue(registry, searchTerm)`.
+ */
+export function hasValue(registry: any, search_term: string): boolean;
+
+/**
+ * Initialise the panic hook so that Rust panics are forwarded to the browser console.
+ *
+ * Call this once when the wasm module loads. Idempotent.
+ */
+export function init(): void;