dispersa 0.3.1 → 0.4.1

package/dist/{index-DJ_UHSQG.d.ts → index-Bkedvob6.d.ts}

@@ -325,7 +325,7 @@ type CssRendererOptions = {
 /**
  * Error code identifying the type of build error
  */
-type ErrorCode = 'TOKEN_REFERENCE' | 'CIRCULAR_REFERENCE' | 'VALIDATION' | 'COLOR_PARSE' | 'DIMENSION_FORMAT' | 'FILE_OPERATION' | 'CONFIGURATION' | 'BASE_PERMUTATION' | 'MODIFIER' | 'UNKNOWN';
+type ErrorCode = 'TOKEN_REFERENCE' | 'CIRCULAR_REFERENCE' | 'VALIDATION' | 'FILE_OPERATION' | 'CONFIGURATION' | 'BASE_PERMUTATION' | 'MODIFIER' | 'UNKNOWN';
 /**
  * Structured error from a build operation
  *
@@ -473,6 +473,13 @@ type LifecycleHooks = {
     onBuildEnd?: (result: BuildResult) => void | Promise<void>;
 };
 
+/**
+ * Function that generates an output file path based on modifier inputs.
+ *
+ * Used as the `file` property on `OutputConfig` and builder configs when
+ * the file name needs to vary per permutation.
+ */
+type FileFunction = (modifierInputs: ModifierInputs) => string;
 /**
  * Output configuration for a single build target
  *
@@ -577,7 +584,7 @@ type OutputConfig<TOptions extends FormatOptions = FormatOptions> = Omit<OutputC
      * }
      * ```
      */
-    file?: string | ((modifierInputs: ModifierInputs) => string);
+    file?: string | FileFunction;
     /**
      * Renderer-specific options passed to the formatter.
      */
@@ -701,4 +708,4 @@ type DispersaOptions = Omit<DispersaOptionsBase, 'validation'> & {
     validation?: ValidationOptions;
 };
 
-export { type AndroidRendererOptions as A, type BuildConfig as B, type CssRendererOptions as C, type DispersaOptions as D, type ErrorCode as E, type FormatOptions as F, type IosRendererOptions as I, type LifecycleHooks as L, type ModifierInputs as M, type OutputConfig as O, type PermutationData as P, type ResolverDocument as R, type SelectorFunction as S, type TailwindRendererOptions as T, type ValidationOptions as V, type BuildResult as a, type ValidationMode as b, type BuildError as c, type BuildOutput as d, type MediaQueryFunction as e, type OutputTree as f, type Renderer as g, type RenderContext as h, type RenderMeta as i, type RenderOutput as j, defineRenderer as k };
+export { type AndroidRendererOptions as A, type BuildConfig as B, type CssRendererOptions as C, type DispersaOptions as D, type ErrorCode as E, type FileFunction as F, type IosRendererOptions as I, type LifecycleHooks as L, type ModifierInputs as M, type OutputConfig as O, type PermutationData as P, type ResolverDocument as R, type SelectorFunction as S, type TailwindRendererOptions as T, type ValidationOptions as V, type BuildResult as a, type ValidationMode as b, type BuildError as c, type BuildOutput as d, type FormatOptions as e, type MediaQueryFunction as f, type OutputTree as g, type Renderer as h, type RenderContext as i, type RenderMeta as j, type RenderOutput as k, defineRenderer as l };

package/dist/{index-BkvV7Z54.d.cts → index-dwm-xYbQ.d.cts}

@@ -325,7 +325,7 @@ type CssRendererOptions = {
 /**
  * Error code identifying the type of build error
  */
-type ErrorCode = 'TOKEN_REFERENCE' | 'CIRCULAR_REFERENCE' | 'VALIDATION' | 'COLOR_PARSE' | 'DIMENSION_FORMAT' | 'FILE_OPERATION' | 'CONFIGURATION' | 'BASE_PERMUTATION' | 'MODIFIER' | 'UNKNOWN';
+type ErrorCode = 'TOKEN_REFERENCE' | 'CIRCULAR_REFERENCE' | 'VALIDATION' | 'FILE_OPERATION' | 'CONFIGURATION' | 'BASE_PERMUTATION' | 'MODIFIER' | 'UNKNOWN';
 /**
  * Structured error from a build operation
  *
@@ -473,6 +473,13 @@ type LifecycleHooks = {
     onBuildEnd?: (result: BuildResult) => void | Promise<void>;
 };
 
+/**
+ * Function that generates an output file path based on modifier inputs.
+ *
+ * Used as the `file` property on `OutputConfig` and builder configs when
+ * the file name needs to vary per permutation.
+ */
+type FileFunction = (modifierInputs: ModifierInputs) => string;
 /**
  * Output configuration for a single build target
  *
@@ -577,7 +584,7 @@ type OutputConfig<TOptions extends FormatOptions = FormatOptions> = Omit<OutputC
      * }
      * ```
      */
-    file?: string | ((modifierInputs: ModifierInputs) => string);
+    file?: string | FileFunction;
     /**
      * Renderer-specific options passed to the formatter.
      */
@@ -701,4 +708,4 @@ type DispersaOptions = Omit<DispersaOptionsBase, 'validation'> & {
     validation?: ValidationOptions;
 };
 
-export { type AndroidRendererOptions as A, type BuildConfig as B, type CssRendererOptions as C, type DispersaOptions as D, type ErrorCode as E, type FormatOptions as F, type IosRendererOptions as I, type LifecycleHooks as L, type ModifierInputs as M, type OutputConfig as O, type PermutationData as P, type ResolverDocument as R, type SelectorFunction as S, type TailwindRendererOptions as T, type ValidationOptions as V, type BuildResult as a, type ValidationMode as b, type BuildError as c, type BuildOutput as d, type MediaQueryFunction as e, type OutputTree as f, type Renderer as g, type RenderContext as h, type RenderMeta as i, type RenderOutput as j, defineRenderer as k };
+export { type AndroidRendererOptions as A, type BuildConfig as B, type CssRendererOptions as C, type DispersaOptions as D, type ErrorCode as E, type FileFunction as F, type IosRendererOptions as I, type LifecycleHooks as L, type ModifierInputs as M, type OutputConfig as O, type PermutationData as P, type ResolverDocument as R, type SelectorFunction as S, type TailwindRendererOptions as T, type ValidationOptions as V, type BuildResult as a, type ValidationMode as b, type BuildError as c, type BuildOutput as d, type FormatOptions as e, type MediaQueryFunction as f, type OutputTree as g, type Renderer as h, type RenderContext as i, type RenderMeta as j, type RenderOutput as k, defineRenderer as l };

package/dist/index.cjs

@@ -86,7 +86,7 @@ var init_token_utils = __esm({
 });
 
 // src/shared/errors/index.ts
-exports.DispersaError = void 0; exports.TokenReferenceError = void 0; exports.CircularReferenceError = void 0; exports.ValidationError = void 0; exports.ColorParseError = void 0; exports.DimensionFormatError = void 0; exports.FileOperationError = void 0; exports.ConfigurationError = void 0; exports.BasePermutationError = void 0; exports.ModifierError = void 0;
+exports.DispersaError = void 0; exports.TokenReferenceError = void 0; exports.CircularReferenceError = void 0; exports.ValidationError = void 0; exports.FileOperationError = void 0; exports.ConfigurationError = void 0; exports.BasePermutationError = void 0; exports.ModifierError = void 0;
 var init_errors = __esm({
   "src/shared/errors/index.ts"() {
     exports.DispersaError = class extends Error {
@@ -137,20 +137,6 @@ var init_errors = __esm({
         this.name = "ValidationError";
       }
     };
-    exports.ColorParseError = class extends exports.DispersaError {
-      constructor(colorValue) {
-        super(`Color parsing failed: '${colorValue}'. Provide a valid CSS color or DTCG color object.`);
-        this.colorValue = colorValue;
-        this.name = "ColorParseError";
-      }
-    };
-    exports.DimensionFormatError = class extends exports.DispersaError {
-      constructor(dimensionValue) {
-        super(`Dimension parsing failed: '${dimensionValue}'. Provide a valid DTCG dimension object.`);
-        this.dimensionValue = dimensionValue;
-        this.name = "DimensionFormatError";
-      }
-    };
     exports.FileOperationError = class extends exports.DispersaError {
       constructor(operation, filePath, originalError) {
         super(`Failed to ${operation} file: ${filePath}. ${originalError.message}`);
@@ -3907,12 +3893,6 @@ function toBuildError(error, outputName) {
   if (error instanceof exports.ValidationError) {
     return { message, code: "VALIDATION", severity: "error" };
   }
-  if (error instanceof exports.ColorParseError) {
-    return { message, code: "COLOR_PARSE", severity: "error" };
-  }
-  if (error instanceof exports.DimensionFormatError) {
-    return { message, code: "DIMENSION_FORMAT", severity: "error" };
-  }
   if (error instanceof exports.FileOperationError) {
     return { message, code: "FILE_OPERATION", path: error.filePath, severity: "error" };
   }
@@ -5907,6 +5887,32 @@ var TokenParser = class {
 };
 
 // src/build/pipeline/token-pipeline.ts
+var ROOT_REF_PATTERN = /\.\$root\}/g;
+function rewriteRootReferences(value) {
+  if (typeof value === "string") {
+    return ROOT_REF_PATTERN.test(value) ? value.replace(ROOT_REF_PATTERN, "}") : value;
+  }
+  if (Array.isArray(value)) {
+    let changed = false;
+    const mapped = value.map((item) => {
+      const rewritten = rewriteRootReferences(item);
+      if (rewritten !== item) changed = true;
+      return rewritten;
+    });
+    return changed ? mapped : value;
+  }
+  if (typeof value === "object" && value !== null) {
+    let changed = false;
+    const result = {};
+    for (const [k, v] of Object.entries(value)) {
+      const rewritten = rewriteRootReferences(v);
+      if (rewritten !== v) changed = true;
+      result[k] = rewritten;
+    }
+    return changed ? result : value;
+  }
+  return value;
+}
 var TokenPipeline = class {
   options;
   validationHandler;
@@ -5931,8 +5937,9 @@ var TokenPipeline = class {
    * 5. Resolve JSON Pointer references
    * 6. Parse and flatten token structure
    * 7. Resolve alias references
-   * 8. Apply filters (if provided) — runs first to remove tokens before transforms
-   * 9. Apply transforms (if provided) — runs on the already-filtered token set
+   * 8. Strip $root from token names/paths (DTCG structural mechanism, transparent in output)
+   * 9. Apply filters (if provided) — runs first to remove tokens before transforms
+   * 10. Apply transforms (if provided) — runs on the already-filtered token set
    *
    * Each stage is explicitly typed to ensure correct order and prevent temporal coupling.
    *
@@ -5972,7 +5979,8 @@ var TokenPipeline = class {
     const refResolved = await this.resolveReferences(preprocessed);
     const flattened = this.flattenTokens(refResolved);
     const aliasResolved = this.resolveAliases(flattened);
-    const filtered = this.applyFilterStage(aliasResolved, filterList);
+    const rootStripped = this.stripRootTokenNames(aliasResolved);
+    const filtered = this.applyFilterStage(rootStripped, filterList);
     return this.applyTransformStage(filtered, transformList);
   }
   /**
@@ -6057,8 +6065,34 @@ var TokenPipeline = class {
     return { ...rest, aliasResolvedTokens };
   }
   /**
-   * Stage 8: Apply filters to final tokens (before transforms to skip unnecessary work)
+   * Stage 8: Strip `$root` from token names and paths.
+   *
+   * `$root` is a DTCG structural mechanism that allows a group to carry a
+   * default value alongside child tokens. References must use the full path
+   * (`{color.action.brand.$root}`) for alias resolution, but `$root` should
+   * be transparent in output. This stage re-keys tokens so downstream
+   * consumers (filters, transforms, renderers) see clean names.
    */
+  stripRootTokenNames(stage) {
+    const tokens = stage.aliasResolvedTokens;
+    const result = {};
+    for (const [key, token] of Object.entries(tokens)) {
+      const rewrittenOriginal = rewriteRootReferences(token.originalValue);
+      if (!key.endsWith(".$root")) {
+        result[key] = rewrittenOriginal !== token.originalValue ? { ...token, originalValue: rewrittenOriginal } : token;
+        continue;
+      }
+      const strippedPath = token.path.filter((segment) => segment !== "$root");
+      const strippedName = strippedPath.join(".");
+      result[strippedName] = {
+        ...token,
+        path: strippedPath,
+        name: strippedName,
+        originalValue: rewrittenOriginal
+      };
+    }
+    return { ...stage, aliasResolvedTokens: result };
+  }
   applyFilterStage(stage, filterList) {
     let tokens = stage.aliasResolvedTokens;
     if (filterList !== void 0 && filterList.length > 0) {