dispersa 0.4.3 → 1.1.0

package/dist/builders.d.cts

@@ -1,8 +1,9 @@
-import { F as FileFunction, L as LifecycleHooks, C as CssRendererOptions, O as OutputConfig, T as TailwindRendererOptions, I as IosRendererOptions, A as AndroidRendererOptions } from './index-CNT2Meyf.cjs';
-import { F as Filter } from './types-DWKq-eJj.cjs';
-import { T as Transform } from './types-BAv39mum.cjs';
-import { a as JsonRendererOptions, J as JsModuleRendererOptions } from './types-CussyWwe.cjs';
-import './types-Bc0kA7De.cjs';
+import { F as FileFunction, L as LifecycleHooks, C as CssRendererOptions, O as OutputConfig } from './index-De6SjZYH.cjs';
+import { F as Filter } from './types-CAdUV-fa.cjs';
+import { T as Transform } from './types-BltzwVYK.cjs';
+import { a as JsonRendererOptions, J as JsModuleRendererOptions } from './types-BHBHRm0a.cjs';
+import { T as TailwindRendererOptions, I as IosRendererOptions, A as AndroidRendererOptions } from './android-CRDfSB3_.cjs';
+import './types-TQHV1MrY.cjs';
 import 'json-schema-to-ts';
 
 /**
@@ -52,7 +53,7 @@ type CssBuilderConfig = BuilderConfigBase & CssRendererOptions;
  *
  * The `file` property is optional. When omitted, content is returned in-memory instead
  * of being written to disk. The `file` property is required when `buildPath` is provided
- * to `dispersa.build()`.
+ * to `build()`.
  *
  * @example Basic CSS bundle with transforms
  * ```typescript
@@ -93,7 +94,7 @@ type CssBuilderConfig = BuilderConfigBase & CssRendererOptions;
  *   selector: ':root'
  * })
  * // Use without buildPath to get content in-memory
- * const result = await dispersa.build({ outputs: [config] })
+ * const result = await build({ outputs: [config] })
  * console.log(result.outputs[0].content)
  * ```
  */
@@ -118,7 +119,7 @@ type JsonBuilderConfig = BuilderConfigBase & JsonRendererOptions;
  *
  * The `file` property is optional. When omitted, content is returned in-memory instead
  * of being written to disk. The `file` property is required when `buildPath` is provided
- * to `dispersa.build()`.
+ * to `build()`.
  *
  * @example Standalone JSON with flat structure
  * ```typescript
@@ -155,7 +156,7 @@ type JsonBuilderConfig = BuilderConfigBase & JsonRendererOptions;
  *   structure: 'flat'
  * })
  * // Use without buildPath to get content in-memory
- * const result = await dispersa.build({ outputs: [config] })
+ * const result = await build({ outputs: [config] })
  * console.log(result.outputs[0].content)
  * ```
  */
@@ -181,7 +182,7 @@ type JsBuilderConfig = BuilderConfigBase & JsModuleRendererOptions;
  *
  * The `file` property is optional. When omitted, content is returned in-memory instead
  * of being written to disk. The `file` property is required when `buildPath` is provided
- * to `dispersa.build()`.
+ * to `build()`.
  *
  * @example Bundle JS with helper function
  * ```typescript
@@ -220,7 +221,7 @@ type JsBuilderConfig = BuilderConfigBase & JsModuleRendererOptions;
  *   structure: 'flat'
  * })
  * // Use without buildPath to get content in-memory
- * const result = await dispersa.build({ outputs: [config] })
+ * const result = await build({ outputs: [config] })
  * console.log(result.outputs[0].content)
  * ```
  */

package/dist/builders.d.ts

@@ -1,8 +1,9 @@
-import { F as FileFunction, L as LifecycleHooks, C as CssRendererOptions, O as OutputConfig, T as TailwindRendererOptions, I as IosRendererOptions, A as AndroidRendererOptions } from './index-CqdaN3X0.js';
-import { F as Filter } from './types-BzNcG-rI.js';
-import { T as Transform } from './types-CzHa7YkW.js';
-import { a as JsonRendererOptions, J as JsModuleRendererOptions } from './types-CZb19kiq.js';
-import './types-Bc0kA7De.js';
+import { F as FileFunction, L as LifecycleHooks, C as CssRendererOptions, O as OutputConfig } from './index-Dajm5rvM.js';
+import { F as Filter } from './types-ebxDimRz.js';
+import { T as Transform } from './types-DztXKlka.js';
+import { a as JsonRendererOptions, J as JsModuleRendererOptions } from './types-8MLtztK3.js';
+import { T as TailwindRendererOptions, I as IosRendererOptions, A as AndroidRendererOptions } from './android-DANJjjPO.js';
+import './types-TQHV1MrY.js';
 import 'json-schema-to-ts';
 
 /**
@@ -52,7 +53,7 @@ type CssBuilderConfig = BuilderConfigBase & CssRendererOptions;
  *
  * The `file` property is optional. When omitted, content is returned in-memory instead
  * of being written to disk. The `file` property is required when `buildPath` is provided
- * to `dispersa.build()`.
+ * to `build()`.
  *
  * @example Basic CSS bundle with transforms
  * ```typescript
@@ -93,7 +94,7 @@ type CssBuilderConfig = BuilderConfigBase & CssRendererOptions;
  *   selector: ':root'
  * })
  * // Use without buildPath to get content in-memory
- * const result = await dispersa.build({ outputs: [config] })
+ * const result = await build({ outputs: [config] })
  * console.log(result.outputs[0].content)
  * ```
  */
@@ -118,7 +119,7 @@ type JsonBuilderConfig = BuilderConfigBase & JsonRendererOptions;
  *
  * The `file` property is optional. When omitted, content is returned in-memory instead
  * of being written to disk. The `file` property is required when `buildPath` is provided
- * to `dispersa.build()`.
+ * to `build()`.
  *
  * @example Standalone JSON with flat structure
  * ```typescript
@@ -155,7 +156,7 @@ type JsonBuilderConfig = BuilderConfigBase & JsonRendererOptions;
  *   structure: 'flat'
  * })
  * // Use without buildPath to get content in-memory
- * const result = await dispersa.build({ outputs: [config] })
+ * const result = await build({ outputs: [config] })
  * console.log(result.outputs[0].content)
  * ```
  */
@@ -181,7 +182,7 @@ type JsBuilderConfig = BuilderConfigBase & JsModuleRendererOptions;
  *
  * The `file` property is optional. When omitted, content is returned in-memory instead
  * of being written to disk. The `file` property is required when `buildPath` is provided
- * to `dispersa.build()`.
+ * to `build()`.
  *
  * @example Bundle JS with helper function
  * ```typescript
@@ -220,7 +221,7 @@ type JsBuilderConfig = BuilderConfigBase & JsModuleRendererOptions;
  *   structure: 'flat'
  * })
  * // Use without buildPath to get content in-memory
- * const result = await dispersa.build({ outputs: [config] })
+ * const result = await build({ outputs: [config] })
  * console.log(result.outputs[0].content)
  * ```
  */

package/dist/builders.js

@@ -41,19 +41,6 @@ var init_errors = __esm({
 });
 
 // src/shared/utils/token-utils.ts
-function formatDeprecationMessage(token, description = "", format = "bracket") {
-  if (token.$deprecated == null || token.$deprecated === false) {
-    return description;
-  }
-  const deprecationMsg = typeof token.$deprecated === "string" ? token.$deprecated : "";
-  if (format === "comment") {
-    const msg2 = deprecationMsg ? ` ${deprecationMsg}` : "";
-    return `DEPRECATED${msg2}`;
-  }
-  const msg = deprecationMsg ? `: ${deprecationMsg}` : "";
-  const prefix = `[DEPRECATED${msg}]`;
-  return description ? `${prefix} ${description}` : prefix;
-}
 function stripInternalTokenMetadata(tokens) {
   const cleaned = {};
   for (const [name, token] of Object.entries(tokens)) {
@@ -331,6 +318,94 @@ var init_utils = __esm({
   }
 });
 
+// src/renderers/metadata.ts
+function sanitizeText(text, format) {
+  switch (format) {
+    case "css":
+    case "tailwind":
+      return text.replace(/\*\//g, "*\\/").replace(/\r?\n/g, " ").trim();
+    case "kotlin":
+      return text.replace(/\*\//g, "* /").replace(/\r?\n/g, " ").trim();
+    case "js":
+    case "swift":
+      return text.replace(/\r?\n/g, " ").trim();
+    default:
+      return text.trim();
+  }
+}
+function buildDeprecationText(token) {
+  if (token.$deprecated == null || token.$deprecated === false) {
+    return "";
+  }
+  const msg = typeof token.$deprecated === "string" ? token.$deprecated : "";
+  return msg ? `DEPRECATED: ${msg}` : "DEPRECATED";
+}
+function buildTokenDescriptionComment(token, format) {
+  if (!token.$description || token.$description === "") {
+    return void 0;
+  }
+  const text = sanitizeText(token.$description, format);
+  switch (format) {
+    case "css":
+    case "tailwind":
+      return `/* ${text} */`;
+    case "js":
+      return `// ${text}`;
+    case "swift":
+      return `/// ${text}`;
+    case "kotlin":
+      return `/** ${text} */`;
+    default:
+      return void 0;
+  }
+}
+function buildTokenDeprecationComment(token, format) {
+  const text = buildDeprecationText(token);
+  if (!text) {
+    return void 0;
+  }
+  switch (format) {
+    case "css":
+    case "tailwind":
+      return `/* ${text} */`;
+    case "js":
+      return `// ${text}`;
+    case "swift":
+      return `/// ${text}`;
+    case "kotlin":
+      return `/** ${text} */`;
+    default:
+      return void 0;
+  }
+}
+function buildModifierComment(modifier, context) {
+  return `/* Modifier: ${modifier}=${context} */`;
+}
+function buildSwiftDeprecationAttribute(token) {
+  if (token.$deprecated == null || token.$deprecated === false) {
+    return void 0;
+  }
+  const msg = typeof token.$deprecated === "string" ? token.$deprecated : "";
+  if (msg) {
+    return `@available(*, deprecated, message: "${sanitizeText(msg, "swift")}")`;
+  }
+  return "@available(*, deprecated)";
+}
+function buildKotlinDeprecationAnnotation(token) {
+  if (token.$deprecated == null || token.$deprecated === false) {
+    return void 0;
+  }
+  const msg = typeof token.$deprecated === "string" ? token.$deprecated : "";
+  if (msg) {
+    return `@Deprecated(message = "${sanitizeText(msg, "kotlin")}")`;
+  }
+  return "@Deprecated";
+}
+var init_metadata = __esm({
+  "src/renderers/metadata.ts"() {
+  }
+});
+
 // src/renderers/bundlers/js.ts
 var js_exports = {};
 __export(js_exports, {
@@ -435,7 +510,7 @@ async function bundleAsJsModule(bundleData, resolver, options, formatTokens) {
   }
   const metadata = buildMetadata(resolver);
   const jsBlocks = [];
-  for (const { tokens, modifierInputs } of bundleData) {
+  for (const { tokens, modifierInputs, isBase } of bundleData) {
     const cleanTokens = stripInternalMetadata(tokens);
     const key = buildStableDashKey({
       modifierInputs,
@@ -443,10 +518,30 @@ async function bundleAsJsModule(bundleData, resolver, options, formatTokens) {
       defaults: metadata.defaults
     });
     const camelKey = toCamelKey(key);
+    const normalizedInputs = normalizeModifierInputs(modifierInputs);
+    const modifierParts = [];
+    for (const dim of metadata.dimensions) {
+      const value = normalizedInputs[dim.toLowerCase()];
+      if (value) {
+        modifierParts.push(`${dim}=${value}`);
+      }
+    }
     const formattedJs = await formatTokens(cleanTokens);
     const tokenObject = extractObjectFromJsModule(formattedJs);
     const indentedObject = tokenObject.replace(/\n/g, "\n  ");
-    jsBlocks.push(`  // ${key}
+    let comment;
+    if (modifierParts.length > 0) {
+      const modifierPart = modifierParts[0];
+      const eqIndex = modifierPart.indexOf("=");
+      const modifier = modifierPart.slice(0, eqIndex);
+      const context = modifierPart.slice(eqIndex + 1);
+      comment = buildModifierComment(modifier, context);
+    } else if (isBase) {
+      comment = "// Base permutation";
+    } else {
+      comment = `// ${key}`;
+    }
+    jsBlocks.push(`  ${comment}
   ${JSON.stringify(camelKey)}: ${indentedObject}`);
   }
   return assembleJsBundle(metadata, jsBlocks, options?.generateHelper ?? false);
@@ -454,6 +549,7 @@ async function bundleAsJsModule(bundleData, resolver, options, formatTokens) {
 var init_js = __esm({
   "src/renderers/bundlers/js.ts"() {
     init_errors();
+    init_metadata();
     init_utils();
   }
 });
@@ -573,6 +669,7 @@ function durationObjectToString(duration) {
 init_errors();
 init_token_utils();
 init_utils();
+init_metadata();
 
 // src/renderers/output-tree.ts
 var outputTree = (files) => {
@@ -633,9 +730,6 @@ function resolveColorFormat(format) {
 function escapeKotlinString(str) {
   return str.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n").replace(/\$/g, "\\$");
 }
-function escapeKDoc(str) {
-  return str.replace(/\*\//g, "* /").replace(/\r?\n/g, " ").trim();
-}
 function formatKotlinNumber(value) {
   return Number.isInteger(value) ? `${value}.0` : String(value);
 }
@@ -767,8 +861,13 @@ var AndroidRenderer = class {
         const kotlinName = this.buildFlatKotlinName(token);
         const kotlinValue = this.formatKotlinValue(token, options, baseDepth + 1);
         const annotation = this.typeAnnotationSuffix(token);
-        if (token.$description) {
-          lines.push(`${valIndent}/** ${escapeKDoc(token.$description)} */`);
+        const descriptionComment = buildTokenDescriptionComment(token, "kotlin");
+        if (descriptionComment) {
+          lines.push(`${valIndent}${descriptionComment}`);
+        }
+        const deprecation = buildKotlinDeprecationAnnotation(token);
+        if (deprecation) {
+          lines.push(`${valIndent}${deprecation}`);
         }
         lines.push(
           `${valIndent}${options.visPrefix}val ${kotlinName}${annotation} = ${kotlinValue}`
@@ -804,8 +903,13 @@ var AndroidRenderer = class {
     const kotlinName = toSafeIdentifier(key, KOTLIN_KEYWORDS, false);
     const kotlinValue = this.formatKotlinValue(token, options, depth);
     const annotation = this.typeAnnotationSuffix(token);
-    if (token.$description) {
-      lines.push(`${pad}/** ${escapeKDoc(token.$description)} */`);
+    const descriptionComment = buildTokenDescriptionComment(token, "kotlin");
+    if (descriptionComment) {
+      lines.push(`${pad}${descriptionComment}`);
+    }
+    const deprecation = buildKotlinDeprecationAnnotation(token);
+    if (deprecation) {
+      lines.push(`${pad}${deprecation}`);
     }
     lines.push(`${pad}${options.visPrefix}val ${kotlinName}${annotation} = ${kotlinValue}`);
   }
@@ -1582,10 +1686,8 @@ function stableInputsKey(modifierInputs) {
 
 // src/renderers/css.ts
 init_utils();
+init_metadata();
 var CssRenderer = class _CssRenderer {
-  sanitizeCssCommentText(text) {
-    return text.replace(/\*\//g, "*\\/").replace(/\r?\n/g, " ").trim();
-  }
   async format(context, options) {
     const opts = {
       preset: options?.preset ?? "bundle",
@@ -1665,12 +1767,13 @@ var CssRenderer = class _CssRenderer {
   }
   pushTokenLines(lines, token, tokens, referenceTokens, preserveReferences, indent, newline, space) {
     const entries = this.buildCssEntries(token, tokens, referenceTokens, preserveReferences);
-    if (token.$deprecated != null && token.$deprecated !== false) {
-      const deprecationMsg = formatDeprecationMessage(token, "", "comment");
-      lines.push(`${indent}/* ${this.sanitizeCssCommentText(deprecationMsg)} */${newline}`);
+    const deprecationComment = buildTokenDeprecationComment(token, "css");
+    if (deprecationComment) {
+      lines.push(`${indent}${deprecationComment}${newline}`);
     }
-    if (token.$description && token.$description !== "") {
-      lines.push(`${indent}/* ${this.sanitizeCssCommentText(token.$description)} */${newline}`);
+    const descriptionComment = buildTokenDescriptionComment(token, "css");
+    if (descriptionComment) {
+      lines.push(`${indent}${descriptionComment}${newline}`);
     }
     for (const entry of entries) {
       lines.push(`${indent}--${entry.name}:${space}${entry.value};${newline}`);
@@ -2321,6 +2424,7 @@ function isBorderToken(token) {
 
 // src/renderers/ios.ts
 init_utils();
+init_metadata();
 var toSRGB2 = converter("rgb");
 var toP32 = converter("p3");
 var SWIFT_TYPE_GROUP_MAP = {
@@ -2464,9 +2568,13 @@ var IosRenderer = class {
       const swiftValue = this.formatSwiftValue(token, options);
       const typeAnnotation = this.getTypeAnnotation(token);
       const annotation = typeAnnotation ? `: ${typeAnnotation}` : "";
-      const docComment = this.buildDocComment(token, indent);
+      const docComment = buildTokenDescriptionComment(token, "swift");
       if (docComment) {
-        lines.push(docComment);
+        lines.push(`${indent}${docComment}`);
+      }
+      const deprecationAttr = buildSwiftDeprecationAttribute(token);
+      if (deprecationAttr) {
+        lines.push(`${indent}${deprecationAttr}`);
       }
       lines.push(`${indent}${access} ${staticPrefix}${swiftName}${annotation} = ${swiftValue}`);
     }
@@ -2481,15 +2589,6 @@ var IosRenderer = class {
     }
     return Array.from(imports).sort();
   }
-  /**
-   * Builds a `///` doc comment from a token's `$description`, if present.
-   */
-  buildDocComment(token, indent) {
-    if (!token.$description) {
-      return void 0;
-    }
-    return `${indent}/// ${token.$description}`;
-  }
   /**
    * Builds a qualified Swift name from a token's path, preserving parent
    * hierarchy segments to avoid duplicate identifiers.
@@ -2880,6 +2979,7 @@ function iosRenderer() {
 // src/renderers/js-module.ts
 init_utils();
 init_token_utils();
+init_metadata();
 var JsModuleRenderer = class {
   async format(context, options) {
     const opts = {
@@ -2917,17 +3017,10 @@ var JsModuleRenderer = class {
     return outputTree(files);
   }
   async formatTokens(tokens, options) {
-    const opts = {
-      preset: options.preset ?? "standalone",
-      structure: options.structure ?? "nested",
-      minify: options.minify ?? false,
-      moduleName: options.moduleName ?? "tokens",
-      generateHelper: options.generateHelper ?? false
-    };
     const lines = [];
-    lines.push(...this.formatAsObject(tokens, opts));
+    lines.push(...this.formatAsObject(tokens, options));
     const code = lines.join("\n");
-    if (opts.minify) {
+    if (options.minify) {
       return code;
     }
     return await prettier.format(code, {
@@ -2940,20 +3033,53 @@ var JsModuleRenderer = class {
       trailingComma: "es5"
     });
   }
-  /**
-   * Format as default export object
-   */
   formatAsObject(tokens, options) {
     const lines = [];
-    const tokenObj = this.tokensToPlainObject(tokens, options.structure);
+    const tokenMap = this.buildTokenMap(tokens);
     const varName = options.moduleName !== "" ? options.moduleName : "tokens";
-    lines.push(`const ${varName} = {`);
-    this.addObjectProperties(lines, tokenObj, 1);
-    lines.push("}");
+    if (options.structure === "flat") {
+      lines.push(`const ${varName} = {`);
+      this.addFlatProperties(lines, tokens, 1);
+      lines.push("}");
+    } else {
+      lines.push(`const ${varName} = {`);
+      const tokenObj = this.tokensToPlainObject(tokens, "nested");
+      this.addNestedProperties(lines, tokenObj, tokenMap, 1);
+      lines.push("}");
+    }
     lines.push("");
     lines.push(`export default ${varName}`);
     return lines;
   }
+  buildTokenMap(tokens) {
+    const map = /* @__PURE__ */ new Map();
+    for (const [name, token] of Object.entries(tokens)) {
+      map.set(name, token);
+    }
+    return map;
+  }
+  addFlatProperties(lines, tokens, indent) {
+    const indentStr2 = "  ".repeat(indent);
+    const sortedEntries = getSortedTokenEntries(tokens);
+    for (let i = 0; i < sortedEntries.length; i++) {
+      const [name, token] = sortedEntries[i];
+      const isLast = i === sortedEntries.length - 1;
+      this.pushTokenComments(lines, token, indentStr2);
+      lines.push(
+        `${indentStr2}${this.quoteKey(name)}: ${JSON.stringify(token.$value)}${isLast ? "" : ","}`
+      );
+    }
+  }
+  pushTokenComments(lines, token, indent) {
+    const deprecationComment = buildTokenDeprecationComment(token, "js");
+    if (deprecationComment) {
+      lines.push(`${indent}${deprecationComment}`);
+    }
+    const descriptionComment = buildTokenDescriptionComment(token, "js");
+    if (descriptionComment) {
+      lines.push(`${indent}${descriptionComment}`);
+    }
+  }
   tokensToPlainObject(tokens, structure) {
     if (structure === "nested") {
       return buildNestedTokenObject(tokens, (token) => token.$value);
@@ -2964,7 +3090,7 @@ var JsModuleRenderer = class {
     }
     return result;
   }
-  addObjectProperties(lines, obj, indent) {
+  addNestedProperties(lines, obj, tokenMap, indent) {
     const indentStr2 = "  ".repeat(indent);
     const entries = Object.entries(obj).sort(([keyA], [keyB]) => keyA.localeCompare(keyB));
     for (let i = 0; i < entries.length; i++) {
@@ -2976,19 +3102,20 @@ var JsModuleRenderer = class {
       const isLast = i === entries.length - 1;
       const isNestedObject = typeof value === "object" && value !== null && !Array.isArray(value);
       if (!isNestedObject) {
+        const token = tokenMap.get(key);
+        if (token) {
+          this.pushTokenComments(lines, token, indentStr2);
+        }
         lines.push(
           `${indentStr2}${this.quoteKey(key)}: ${JSON.stringify(value)}${isLast ? "" : ","}`
         );
         continue;
       }
       lines.push(`${indentStr2}${this.quoteKey(key)}: {`);
-      this.addObjectProperties(lines, value, indent + 1);
+      this.addNestedProperties(lines, value, tokenMap, indent + 1);
       lines.push(`${indentStr2}}${isLast ? "" : ","}`);
     }
   }
-  /**
-   * Quote key if necessary
-   */
   quoteKey(key) {
     if (/^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(key)) {
       return key;
@@ -3224,6 +3351,7 @@ function resolveOptions(options) {
 
 // src/renderers/tailwind.ts
 init_utils();
+init_metadata();
 var TAILWIND_NAMESPACE_MAP = {
   color: "color",
   dimension: "spacing",
@@ -3277,6 +3405,14 @@ var TailwindRenderer = class {
     for (const [, token] of getSortedTokenEntries(tokens)) {
       const varName = this.buildVariableName(token);
       const varValue = this.formatValue(token);
+      const deprecationComment = buildTokenDeprecationComment(token, "tailwind");
+      if (deprecationComment) {
+        lines.push(`${indent}${deprecationComment}${newline}`);
+      }
+      const descriptionComment = buildTokenDescriptionComment(token, "tailwind");
+      if (descriptionComment) {
+        lines.push(`${indent}${descriptionComment}${newline}`);
+      }
       lines.push(`${indent}--${varName}:${space}${varValue};${newline}`);
     }
     lines.push(`}${newline}`);
@@ -3303,6 +3439,14 @@ var TailwindRenderer = class {
     for (const [, token] of getSortedTokenEntries(tokens)) {
       const varName = this.buildVariableName(token);
       const varValue = this.formatValue(token);
+      const deprecationComment = buildTokenDeprecationComment(token, "tailwind");
+      if (deprecationComment) {
+        lines.push(`${tokenIndent}${deprecationComment}${newline}`);
+      }
+      const descriptionComment = buildTokenDescriptionComment(token, "tailwind");
+      if (descriptionComment) {
+        lines.push(`${tokenIndent}${descriptionComment}${newline}`);
+      }
       lines.push(`${tokenIndent}--${varName}:${space}${varValue};${newline}`);
     }
     if (hasMediaQuery) {