@supernova-studio/supernova-sdk-beta 2.4.6 → 2.4.11

package/build/types/tools/design-tokens/utilities/SDKDTJSONConverter.d.ts

@@ -1,22 +1,48 @@
 import { Brand } from "../../../model/base/SDKBrand";
 import { DTOriginalTokenType } from "../../../model/enums/SDKTokenType";
 import { AnyToken } from "../../../model/tokens/SDKTokenValue";
-import { DTParsedNode } from "./SDKDTJSONLoader";
-import { DTPluginToSupernovaMapPack } from "./SDKDTMapLoader";
+import { DTParsedNode, DTParsedThemeSetPriority, DTParsedTokenSet } from "./SDKDTJSONLoader";
+import { DTPluginSourceMode, DTPluginToSupernovaMapPack, DTPluginUnresolvableFallback, DTPluginUnresolvableRefMode } from "./SDKDTMapLoader";
 import { DTTokenReferenceResolver } from "./SDKDTTokenReferenceResolver";
 export type DTProcessedTokenNode<T extends AnyToken = AnyToken> = {
     token: T;
     originalType: DTOriginalTokenType;
     path: Array<string>;
     key: string;
+    /** Originating set's status in `$themes.json`; absent for explicit-`tokenSets` mappings */
+    sourcePriority?: DTParsedThemeSetPriority;
+};
+export type DTJSONConverterOptions = {
+    /** How to handle references that can't resolve; defaults to `strict` (throw). */
+    unresolvableRefMode?: DTPluginUnresolvableRefMode;
+    /** Per-type fallback values used by `placeholder` and `lenientResolve` modes. */
+    unresolvableFallback?: Required<DTPluginUnresolvableFallback>;
+    /** Full input token sets — used only by `lenientResolve` for wider-scope lookup. */
+    allLoadedSets?: Array<DTParsedTokenSet>;
+    /** Attribution label included in warnings — usually `"<brand>/<theme>"`. */
+    mappingKey?: string;
+    /** How to handle `source`-statused sets (Fix B). Defaults to `emit`. */
+    sourceMode?: DTPluginSourceMode;
 };
 /** Utility to DS Tokens plugin JSON to Supernova entities */
 export declare class DTJSONConverter {
     versionId: string;
     mapping: DTPluginToSupernovaMapPack;
     referenceResolver: DTTokenReferenceResolver;
-    constructor(versionId: string, mapping: DTPluginToSupernovaMapPack);
+    unresolvableRefMode: DTPluginUnresolvableRefMode;
+    unresolvableFallback: Required<DTPluginUnresolvableFallback>;
+    allLoadedSets: Array<DTParsedTokenSet>;
+    mappingKey: string;
+    sourceMode: DTPluginSourceMode;
+    /** Warnings surfaced during resolution (emitted by non-strict unresolvable modes). Consumed by the plugin and folded into logs[]. */
+    warnings: Array<string>;
+    /** Keys of processed nodes that should be dropped before emission (populated by `preserve` mode and Fix B source filtering). */
+    skippedKeys: Set<string>;
+    constructor(versionId: string, mapping: DTPluginToSupernovaMapPack, options?: DTJSONConverterOptions);
     convertNodesToTokens(nodes: Array<DTParsedNode>, brand: Brand): Array<DTProcessedTokenNode>;
+    private applySourceModeSkip;
+    /** Single-pass cascade: mark tokens whose referencedTokenId targets are in `skipIds`. Returns true if any new skip was added. */
+    private markCascadingSkips;
     private restoreInitialTokenOrder;
     private remapRootNodeKey;
     private remapRootNodeKeys;

package/build/types/tools/design-tokens/utilities/SDKDTJSONLoader.d.ts

@@ -7,6 +7,8 @@ export type DTParsedNode = {
     type: DTOriginalTokenType;
     value: JSONValue;
     description: string | null;
+    /** Originating set's status in `$themes.json`; absent for explicit-`tokenSets` mappings */
+    sourcePriority?: DTParsedThemeSetPriority;
 };
 export type DTParsedTokenSet = {
     name: string;

package/build/types/tools/design-tokens/utilities/SDKDTMapLoader.d.ts

@@ -15,6 +15,31 @@ export declare enum DTPluginPreciseCopyStrategy {
     deleteAll = "deleteAll",// preciseCopy = true
     keepManualTokens = "keepManualTokens"
 }
+/** Controls how `source`-statused sets in `$themes.json` are handled during sync. */
+export declare enum DTPluginSourceMode {
+    /** Source sets contribute tokens AND resolve references (current SDK behavior) */
+    emit = "emit",
+    /** Source sets are used for reference resolution only; their tokens are inlined into referring enabled tokens and not emitted separately */
+    referenceOnly = "referenceOnly"
+}
+/** Controls what happens when a `{...}` reference can't be resolved within the mapping's set pool. */
+export declare enum DTPluginUnresolvableRefMode {
+    /** Throw the enriched error listing missing refs (current SDK behavior) */
+    strict = "strict",
+    /** Substitute unresolvable refs with configured fallback values; emit warnings to logs */
+    placeholder = "placeholder",
+    /** Keep the `{...}` literal in the token value; self-heals on next sync when target exists */
+    preserve = "preserve",
+    /** Try to resolve against all loaded sets (not just mapping's subset); fall back to placeholder if still unresolvable */
+    lenientResolve = "lenientResolve"
+}
+/** Per-type fallback values used by `placeholder` mode (and `lenientResolve` fallback). */
+export type DTPluginUnresolvableFallback = {
+    color?: string;
+    dimension?: number;
+    string?: string;
+};
+export declare const DEFAULT_UNRESOLVABLE_FALLBACK: Required<DTPluginUnresolvableFallback>;
 export declare const isPreciseCopyEnabled: (preciseCopy: DTPluginPreciseCopyStrategy) => preciseCopy is DTPluginPreciseCopyStrategy.deleteAll | DTPluginPreciseCopyStrategy.keepManualTokens;
 export declare const toPreciseCopyStrategy: (preciseCopy?: boolean | DTPluginPreciseCopyStrategy) => DTPluginPreciseCopyStrategy;
 export type DTPluginToSupernovaMap = {
@@ -42,6 +67,9 @@ export type DTPluginToSupernovaMappingFile = {
         dryRun?: boolean;
         preciseCopy?: boolean | DTPluginPreciseCopyStrategy;
         themeOverridesStrategy?: DTPluginThemeOverrideStrategy;
+        sourceMode?: DTPluginSourceMode;
+        unresolvableRefMode?: DTPluginUnresolvableRefMode;
+        unresolvableFallback?: DTPluginUnresolvableFallback;
     };
 };
 export type DTPluginToSupernovaSettings = {
@@ -49,4 +77,7 @@ export type DTPluginToSupernovaSettings = {
     dryRun: boolean;
     preciseCopy: DTPluginPreciseCopyStrategy;
     themeOverridesStrategy: DTPluginThemeOverrideStrategy;
+    sourceMode: DTPluginSourceMode;
+    unresolvableRefMode: DTPluginUnresolvableRefMode;
+    unresolvableFallback: Required<DTPluginUnresolvableFallback>;
 };

package/build/types/tools/design-tokens/utilities/SDKDTTokenReferenceResolver.d.ts

@@ -45,4 +45,6 @@ export declare class DTTokenReferenceResolver {
         dollarTypeReference: boolean;
     }[];
     isDollarIdentifier(value: string): boolean;
+    /** Extract references appearing in `value` that aren't defined in the atomic table. Returns bracket-normalized keys (e.g. `{color.base.foo}`). */
+    unresolvedReferencesIn(value: unknown): Array<string>;
 }

package/build/types/tools/design-tokens/utilities/unresolvable-modes/index.d.ts

@@ -0,0 +1,4 @@
+import { DTPluginUnresolvableRefMode } from "../SDKDTMapLoader";
+import { UnresolvableModeHandler } from "./types";
+export * from "./types";
+export declare const UNRESOLVABLE_MODE_HANDLERS: Record<DTPluginUnresolvableRefMode, UnresolvableModeHandler>;

package/build/types/tools/design-tokens/utilities/unresolvable-modes/lenient-resolve.d.ts

@@ -0,0 +1,2 @@
+import { UnresolvableModeHandler } from "./types";
+export declare const lenientResolveHandler: UnresolvableModeHandler;

package/build/types/tools/design-tokens/utilities/unresolvable-modes/placeholder.d.ts

@@ -0,0 +1,2 @@
+import { UnresolvableModeHandler } from "./types";
+export declare const placeholderHandler: UnresolvableModeHandler;

package/build/types/tools/design-tokens/utilities/unresolvable-modes/preserve.d.ts

@@ -0,0 +1,2 @@
+import { UnresolvableModeHandler } from "./types";
+export declare const preserveHandler: UnresolvableModeHandler;

package/build/types/tools/design-tokens/utilities/unresolvable-modes/strict.d.ts

@@ -0,0 +1,2 @@
+import { UnresolvableModeHandler } from "./types";
+export declare const strictHandler: UnresolvableModeHandler;

package/build/types/tools/design-tokens/utilities/unresolvable-modes/types.d.ts

@@ -0,0 +1,33 @@
+import { Brand } from "../../../../model/base/SDKBrand";
+import { DTParsedNode, DTParsedTokenSet } from "../SDKDTJSONLoader";
+import { DTPluginUnresolvableFallback } from "../SDKDTMapLoader";
+import { DTTokenReferenceResolver } from "../SDKDTTokenReferenceResolver";
+/** Context passed to each unresolvable-ref handler. */
+export type UnresolvableModeContext = {
+    /** Nodes that failed to resolve within the depth limit, paired with their original processing index. */
+    unresolvedTokens: Array<[DTParsedNode, number]>;
+    /** All token sets loaded from the input file (used by `lenientResolve`; other handlers ignore). */
+    allLoadedSets: Array<DTParsedTokenSet>;
+    /** The atomic-token table built during resolution; used to check what IS known. */
+    atomicResolver: DTTokenReferenceResolver;
+    /** Fully-populated fallback values (defaults merged with any user overrides). */
+    fallback: Required<DTPluginUnresolvableFallback>;
+    /** Brand context — passed to per-token conversion. */
+    brand: Brand;
+    /** Short label used in warning strings for attribution (e.g. "Jetstar/jq-web-light"). */
+    mappingKey: string;
+};
+/**
+ * Result from a handler. Instead of directly writing tokens, handlers return
+ * substituted nodes (whose values may have been rewritten) and/or skipped nodes.
+ * The caller re-runs the atomic-conversion path on substituted nodes.
+ */
+export type UnresolvableModeResult = {
+    /** Nodes whose values were substituted; re-run conversion on these. */
+    substitutedNodes: Array<[DTParsedNode, number]>;
+    /** Nodes to skip entirely — not emitted this sync. */
+    skippedNodes: Array<[DTParsedNode, number]>;
+    /** `[WARN]`-prefixed lines appended to the existing `logs[]` return value. */
+    warnings: Array<string>;
+};
+export type UnresolvableModeHandler = (context: UnresolvableModeContext) => UnresolvableModeResult;

package/build/types/tools/docs-block-builder/SDKDocsBlockBuilder.d.ts

@@ -10,6 +10,7 @@ import { DocsBlockCodePropertyDefinition, DocsBlockCodePropertyOptions } from ".
 import { DocsBlockCodeSandboxPropertyDefinition, DocsBlockCodeSandboxPropertyOptions } from "../../model/docs/blocks/properties/SDKDocsBlockCodeSandboxProperty";
 import { DocsBlockComponentPropertyDefinition, DocsBlockComponentPropertyOptions } from "../../model/docs/blocks/properties/SDKDocsBlockComponentProperty";
 import { DocsBlockComponentPropertyPropertyDefinition, DocsBlockComponentPropertyPropertyOptions } from "../../model/docs/blocks/properties/SDKDocsBlockComponentPropertyProperty";
+import { DocsBlockContextPropertyDefinition, DocsBlockContextPropertyOptions } from "../../model/docs/blocks/properties/SDKDocsBlockContextProperty";
 import { DocsBlockDividerPropertyDefinition, DocsBlockDividerPropertyOptions } from "../../model/docs/blocks/properties/SDKDocsBlockDividerProperty";
 import { DocsBlockEmbedUrlPropertyDefinition, DocsBlockEmbedUrlPropertyOptions } from "../../model/docs/blocks/properties/SDKDocsBlockEmbedUrlProperty";
 import { DocsBlockFigmaComponentPropertyDefinition, DocsBlockFigmaComponentPropertyOptions } from "../../model/docs/blocks/properties/SDKDocsBlockFigmaComponentProperty";
@@ -392,4 +393,12 @@ export declare class DocsBlockBuilder {
         options: DocsBlockFilePropertyOptions;
         variants?: Record<string, DocsBlockFilePropertyOptions>;
     }): DocsBlockFilePropertyDefinition;
+    /** Create a block property with type .context and its specific options */
+    contextProperty(configuration: {
+        id: string;
+        name: string;
+        description?: string;
+        options?: DocsBlockContextPropertyOptions;
+        variants?: Record<string, DocsBlockContextPropertyOptions>;
+    }): DocsBlockContextPropertyDefinition;
 }

package/build/types/tools/json-builder/elements-transformers/SDKToolsJSONElementTransformer.d.ts

@@ -63,7 +63,7 @@ export declare class TokenJSONElementTransformer {
     safeGroupName(group: TokenGroup): string;
     processedName(name: string, naming: JSONBuilderNamingOption): string;
     /** Retrieve human-readable token type in unified fashion, used both as token type and as token master group */
-    typeLabel(type: TokenType): "border" | "color" | "gradient" | "measure" | "shadow" | "text" | "textCase" | "textDecoration" | "visibility" | "typography";
+    typeLabel(type: TokenType): "visibility" | "border" | "color" | "gradient" | "measure" | "shadow" | "text" | "textCase" | "textDecoration" | "typography";
     /** Retrieve chain of groups up to a specified group, ordered from parent to children */
     referenceGroupChain(containingGroup: TokenGroup, allGroups: Array<TokenGroup>): Array<TokenGroup>;
 }

package/build/types/utils/TokenUtils.d.ts

@@ -305,7 +305,7 @@ export declare class TokenUtils {
     static buildFallbackKeyBack(node: Pick<DTProcessedTokenNode, "path" | "token">): string;
     static buildFallbackKey2(node: Pick<DTProcessedTokenNode, "path" | "token">): string;
     static getTokenByKeyOrFallbackKeys<T extends DTProcessedTokenNode | Token>(node: Pick<DTProcessedTokenNode, "path" | "token">, map: Map<string, T>): T | undefined;
-    static getKeysByKeyOrFallbackKeys<T extends DTProcessedTokenNode | Token>(node: Pick<DTProcessedTokenNode, "path" | "token">): string[];
+    static getKeysByKeyOrFallbackKeys(node: Pick<DTProcessedTokenNode, "path" | "token">): string[];
     static getTokenByKeyOrBackwardKey(node: Pick<DTProcessedTokenNode, "path" | "token">, map: Map<string, DTProcessedTokenNode>): DTProcessedTokenNode | undefined;
     static getTextCaseTokenValue(value: TextCase): "Uppercase" | "Lowercase" | "Capitalize" | "Small caps" | "Original";
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supernova-studio/supernova-sdk-beta",
-  "version": "2.4.6",
+  "version": "2.4.11",
   "description": "Supernova.io SDK",
   "main": "./build/supernova-sdk-typescript.js",
   "types": "./build/types/index.d.ts",
@@ -24,7 +24,6 @@
   "scripts-info": {
     "info": "Display information about the package scripts",
     "build": "Clean and rebuild the project",
-    "fix": "Try to automatically fix any linting problems",
     "test": "Lint and unit test the project",
     "watch": "Watch and rebuild the project on save, then rerun relevant tests",
     "cov": "Rebuild, run tests, then create and open the coverage report",
@@ -36,43 +35,41 @@
     "publish-packages": "Publish both SDK and Pulsar package to NPM"
   },
   "engines": {
-    "node": ">=8.9"
+    "node": ">=18"
   },
   "dependencies": {
-    "abab": "2.0.6",
     "async-mutex": "0.3.2",
     "color-string": "1.9.1",
-    "color2k": "2.0.2",
+    "color2k": "2.0.4",
     "fuse.js": "6.6.2",
-    "lodash": "4.17.23",
+    "lodash": "4.18.1",
     "parse-color": "1.0.0",
     "tinycolor2": "1.6.0",
     "uuid": "14.0.0",
-    "@supernova-studio/client": "1.96.6",
-    "@supernova-studio/model": "1.96.6"
+    "@supernova-studio/client": "1.96.10",
+    "@supernova-studio/model": "1.96.10"
   },
   "devDependencies": {
     "@istanbuljs/nyc-config-typescript": "0.1.3",
-    "@types/lodash": "4.17.23",
-    "@types/tinycolor2": "1.4.3",
+    "@types/lodash": "4.17.24",
+    "@types/parse-color": "1.0.3",
+    "@types/tinycolor2": "1.4.6",
     "dotenv": "16.0.3",
     "esm": "3.2.25",
-    "npm-run-all": "4.1.5",
     "nyc": "17.1.0",
     "readable-stream": "4.7.0",
     "trash-cli": "5.0.0",
-    "ts-loader": "9.4.2",
+    "ts-loader": "9.6.2",
     "tsconfig-paths-webpack-plugin": "4.2.0",
-    "tsx": "4.20.6",
-    "vitest": "4.0.14",
+    "tsx": "4.19.3",
+    "vitest": "4.1.4",
+    "webpack": "5.108.4",
     "webpack-cli": "6.0.1",
     "webpack-node-externals": "3.0.0",
-    "@supernovaio/typescript-with-config": "1.3.28"
+    "@supernovaio/typescript-with-config": "1.3.28",
+    "eslint-config-supernova": "0.0.0"
   },
   "config": {},
-  "overrides": {
-    "js-yaml": "3.14.2"
-  },
   "nyc": {
     "extends": "@istanbuljs/nyc-config-typescript",
     "exclude": [
@@ -80,17 +77,16 @@
     ]
   },
   "optionalDependencies": {
-    "@rollup/rollup-darwin-x64": "4.34.6"
+    "@rollup/rollup-darwin-x64": "4.59.0"
   },
   "scripts": {
     "build:production": "pnpm clean && webpack --mode production --config ./webpack.config.sdk.js && pnpm build:types",
     "build:types": "tsc --noCheck --declaration --emitDeclarationOnly --declarationMap false --skipLibCheck --module CommonJS --target ES2020 --moduleResolution node --esModuleInterop --outDir build/types src/index.ts",
     "build-sdk": "pnpm build:production",
     "clean": "trash build test",
-    "fix": "run-s fix:*",
     "lint": "eslint 'src/**/*.ts*'",
     "lint:fix": "eslint 'src/**/*.ts*' --fix",
-    "test": "run-s \"test:* -- {@}\" --",
+    "test": "pnpm test:unit",
     "test:unit": "vitest run --config vitest.config.ts --reporter verbose",
     "test:watch": "vitest --config vitest.config.ts --watch",
     "test-ci": "vitest run --config vitest.config-ci.ts",

package/build/types/model/enums/SDKDocsBlockTokenNameFormat.d.ts

@@ -1,10 +0,0 @@
-export declare enum DocsBlockTokenNameFormat {
-    /** Token name */
-    name = "Name",
-    /** Group and token name */
-    groupAndName = "GroupAndName",
-    /** Full path */
-    fullPath = "FullPath",
-    /** Custom property */
-    customProperty = "CustomProperty"
-}