dispersa 0.3.1 → 0.4.1

package/dist/renderers.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/renderers/types.ts","../src/renderers/output-tree.ts"],"names":[],"mappings":";;;AA8HO,SAAS,eAAwC,QAAA,EAAoC;AAC1F,EAAA,OAAO,QAAA;AACT;;;ACrGO,IAAM,UAAA,GAAa,CAAC,KAAA,KAA8C;AACvE,EAAA,OAAO;AAAA,IACL,IAAA,EAAM,YAAA;AAAA,IACN;AAAA,GACF;AACF;AAQO,IAAM,YAAA,GAAe,CAAC,KAAA,KAAwC;AACnE,EAAA,OACE,OAAO,KAAA,KAAU,QAAA,IACjB,KAAA,KAAU,IAAA,IACT,MAA6B,IAAA,KAAS,YAAA;AAE3C","file":"renderers.cjs","sourcesContent":["/**\n * @fileoverview Renderer system types for token output generation\n */\n\nimport type { ModifierInputs, OutputConfig, ResolverDocument } from '@config/index'\nimport type { ResolvedTokens } from '@tokens/types'\n\n/**\n * Generic options object for renderers\n *\n * Each renderer can define its own specific options that extend this base type.\n */\nexport type FormatOptions = Record<string, unknown>\n\n/**\n * Data for a single permutation (combination of modifier values)\n */\nexport type PermutationData = {\n  tokens: ResolvedTokens\n  modifierInputs: ModifierInputs\n}\n\n/**\n * Metadata for renderers to reason about modifier dimensions.\n */\nexport type RenderMeta = {\n  dimensions: string[]\n  defaults: Record<string, string>\n  basePermutation: ModifierInputs\n}\n\n/**\n * Context provided to renderer formatters.\n */\nexport type RenderContext<TOptions extends FormatOptions = FormatOptions> = {\n  permutations: PermutationData[]\n  output: OutputConfig<TOptions>\n  resolver: ResolverDocument\n  meta: RenderMeta\n  buildPath?: string\n}\n\n/**\n * Multi-file output representation for renderers.\n */\nexport type OutputTree = {\n  kind: 'outputTree'\n  files: Record<string, string>\n}\n\nexport type RenderOutput = string | OutputTree\n\n/**\n * Output from a build operation\n */\nexport type BuildOutput = {\n  name: string\n  /** File path where output was written (undefined for in-memory mode) */\n  path?: string\n  content: string\n}\n\n/**\n * Renderer definition for converting tokens to output format\n *\n * Renderers implement a single `format()` method that can return either\n * a single string or an OutputTree for multi-file outputs.\n *\n * @example Simple renderer with format()\n * ```typescript\n * const scssRenderer: Renderer = {\n *   format: (context) => {\n *     const tokens = context.permutations[0]?.tokens ?? {}\n *     return Object.entries(tokens)\n *       .map(([name, token]) => `$${name}: ${token.$value};`)\n *       .join('\\n')\n *   },\n * }\n * ```\n */\nexport type Renderer<TOptions extends FormatOptions = FormatOptions> = {\n  /**\n   * Preset identifier (e.g., 'bundle', 'standalone', 'modifier')\n   * Indicates which variant of the renderer this is\n   */\n  preset?: string\n\n  /**\n   * Convert tokens to output content.\n   *\n   * Renderers receive all resolved permutations and modifier metadata via context.\n   * They can return either a single string (single output file) or an OutputTree\n   * for multi-file outputs.\n   */\n  format: (\n    context: RenderContext<TOptions>,\n    options?: TOptions,\n  ) => RenderOutput | Promise<RenderOutput>\n}\n\n/**\n * Helper for defining custom renderers with full type inference.\n *\n * Works like Vue's `defineComponent()` or Vite's `defineConfig()` --\n * an identity function that enables TypeScript to infer the options type\n * from the generic parameter, giving you autocomplete and type-checking\n * on both `context` and `options` inside `format()`.\n *\n * @example\n * ```typescript\n * import { defineRenderer } from 'dispersa/renderers'\n *\n * type MyOptions = { prefix: string; minify?: boolean }\n *\n * const myRenderer = defineRenderer<MyOptions>({\n *   format(context, options) {\n *     // options is typed as MyOptions | undefined\n *     // context.output.options is typed as MyOptions | undefined\n *     const prefix = options?.prefix ?? 'token'\n *     return Object.entries(context.permutations[0]?.tokens ?? {})\n *       .map(([name, token]) => `${prefix}-${name}: ${token.$value}`)\n *       .join('\\n')\n *   },\n * })\n * ```\n */\nexport function defineRenderer<T extends FormatOptions>(renderer: Renderer<T>): Renderer<T> {\n  return renderer\n}\n\n/**\n * Function type for dynamically generating CSS selectors based on modifier context\n *\n * @param modifierName - Name of the modifier (e.g., 'theme', 'breakpoint')\n * @param context - Context value of the modifier (e.g., 'dark', 'mobile')\n * @param isBase - Whether this is the base permutation\n * @param allModifierInputs - All modifier inputs for this permutation\n * @returns CSS selector string (e.g., '[data-theme=\"dark\"]')\n */\nexport type SelectorFunction = (\n  modifierName: string,\n  context: string,\n  isBase: boolean,\n  allModifierInputs: Record<string, string>,\n) => string\n\n/**\n * Function type for dynamically generating media queries based on modifier context\n *\n * @param modifierName - Name of the modifier (e.g., 'theme', 'breakpoint')\n * @param context - Context value of the modifier (e.g., 'dark', 'mobile')\n * @param isBase - Whether this is the base permutation\n * @param allModifierInputs - All modifier inputs for this permutation\n * @returns Media query string (e.g., '(max-width: 768px)') or empty string for no media query\n */\nexport type MediaQueryFunction = (\n  modifierName: string,\n  context: string,\n  isBase: boolean,\n  allModifierInputs: Record<string, string>,\n) => string\n\n/**\n * Options for CSS custom properties renderer\n *\n * Controls how tokens are converted to CSS custom properties (CSS variables).\n *\n * **Note:** Token naming is controlled through transforms, not renderer options.\n * Use `nameKebabCase()` and `namePrefix()` for naming control.\n *\n * @example String-based selectors\n * ```typescript\n * css({\n *   name: 'tokens',\n *   file: 'tokens.css',\n *   transforms: [nameKebabCase(), namePrefix('ds-')],\n *   preset: 'bundle',\n *   selector: ':root',\n * })\n * ```\n *\n * @example Function-based selectors\n * ```typescript\n * outputs: [{\n *   renderer: cssRenderer(),\n *   options: {\n *     preset: 'bundle',\n *     selector: (modifier, context, isBase, allInputs) => {\n *       if (isBase) return ':root'\n *       return `[data-${modifier}=\"${context}\"]`\n *     },\n *     mediaQuery: (modifier, context) => {\n *       if (modifier === 'breakpoint' && context === 'mobile') {\n *         return '(max-width: 768px)'\n *       }\n *       return ''\n *     }\n *   }\n * }]\n * ```\n */\nexport type CssRendererOptions = {\n  preset?: 'bundle' | 'standalone' | 'modifier'\n  selector?: string | SelectorFunction\n  mediaQuery?: string | MediaQueryFunction\n  minify?: boolean\n  preserveReferences?: boolean\n}\n\n/**\n * Options for JSON renderer\n *\n * Controls the structure and formatting of JSON token output.\n *\n * @example\n * ```typescript\n * {\n *   structure: 'flat',\n *   minify: true,\n *   includeMetadata: true\n * }\n * ```\n */\nexport type { JsonRendererOptions } from '@validation/config-schemas'\n\n/**\n * Options for JavaScript module renderer\n *\n * Generates JavaScript modules for direct import in applications.\n * Aligned with JSON renderer options for consistency.\n *\n * @example\n * ```typescript\n * {\n *   structure: 'nested',\n *   minify: false,\n *   moduleName: 'designTokens'\n * }\n * ```\n */\nexport type { JsModuleRendererOptions } from '@validation/config-schemas'\n\n/**\n * Options for Tailwind CSS v4 renderer\n *\n * Generates CSS with @theme blocks for Tailwind v4+ design token integration.\n */\nexport type { TailwindRendererOptions } from './tailwind'\n\n/**\n * Options for iOS/SwiftUI renderer\n *\n * Generates Swift code targeting SwiftUI (iOS 17+, Swift 6).\n */\nexport type { IosRendererOptions } from './ios'\n\n/**\n * Options for Android/Jetpack Compose renderer\n *\n * Generates Kotlin code targeting Jetpack Compose with Material 3.\n *\n * @experimental This type is experimental. Properties and behavior may change.\n */\nexport type { AndroidRendererOptions } from './android'\n\n/**\n * Result of a token build operation\n *\n * Contains success status, generated output files, and any errors encountered.\n *\n * @example\n * ```typescript\n * const result = await dispersa.build(config)\n * if (result.success) {\n *   result.outputs.forEach(output => {\n *     console.log(`Generated ${output.name}: ${output.path}`)\n *   })\n * } else {\n *   console.error('Build errors:', result.errors)\n * }\n * ```\n */\n/**\n * Error code identifying the type of build error\n */\nexport type ErrorCode =\n  | 'TOKEN_REFERENCE'\n  | 'CIRCULAR_REFERENCE'\n  | 'VALIDATION'\n  | 'COLOR_PARSE'\n  | 'DIMENSION_FORMAT'\n  | 'FILE_OPERATION'\n  | 'CONFIGURATION'\n  | 'BASE_PERMUTATION'\n  | 'MODIFIER'\n  | 'UNKNOWN'\n\n/**\n * Structured error from a build operation\n *\n * Preserves typed context from the error hierarchy so consumers\n * can programmatically react to specific failure modes.\n */\nexport type BuildError = {\n  /** Human-readable error message */\n  message: string\n\n  /** Machine-readable error code identifying the failure type */\n  code: ErrorCode\n\n  /** File path where the error occurred (for file operation errors) */\n  path?: string\n\n  /** Token path where the error occurred (e.g. 'color.primary') */\n  tokenPath?: string\n\n  /** Error severity */\n  severity: 'error' | 'warning'\n\n  /** Suggested alternatives (e.g. similar token names for TOKEN_REFERENCE errors) */\n  suggestions?: string[]\n}\n\nexport type BuildResult = {\n  /** Whether the build completed successfully */\n  success: boolean\n\n  /** Array of generated output files */\n  outputs: BuildOutput[]\n\n  /** Array of errors encountered during build (only present if success is false) */\n  errors?: BuildError[]\n}\n","/**\n * @fileoverview Output tree helpers for custom renderers\n */\n\nimport type { OutputTree } from './types'\n\n/**\n * Create an {@link OutputTree} from a map of file paths to content strings.\n *\n * Use this when building a custom renderer that produces multiple output files\n * (e.g. one file per theme or permutation).\n *\n * @param files - Record mapping relative file paths to their string content\n * @returns An `OutputTree` that the build orchestrator can write to disk or return in-memory\n *\n * @example\n * ```typescript\n * import { defineRenderer, outputTree } from 'dispersa/renderers'\n *\n * const myRenderer = defineRenderer((context) => {\n *   return outputTree({\n *     'light.css': '/* light tokens *\\/',\n *     'dark.css': '/* dark tokens *\\/',\n *   })\n * })\n * ```\n */\nexport const outputTree = (files: Record<string, string>): OutputTree => {\n  return {\n    kind: 'outputTree',\n    files,\n  }\n}\n\n/**\n * Type guard that checks whether a value is an {@link OutputTree}.\n *\n * @param value - The value to check\n * @returns `true` if the value is an `OutputTree`\n */\nexport const isOutputTree = (value: unknown): value is OutputTree => {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    (value as { kind?: unknown }).kind === 'outputTree'\n  )\n}\n"]}
+{"version":3,"sources":["../src/renderers/types.ts","../src/renderers/output-tree.ts"],"names":[],"mappings":";;;AA8HO,SAAS,eAAwC,QAAA,EAAoC;AAC1F,EAAA,OAAO,QAAA;AACT;;;ACrGO,IAAM,UAAA,GAAa,CAAC,KAAA,KAA8C;AACvE,EAAA,OAAO;AAAA,IACL,IAAA,EAAM,YAAA;AAAA,IACN;AAAA,GACF;AACF;AAQO,IAAM,YAAA,GAAe,CAAC,KAAA,KAAwC;AACnE,EAAA,OACE,OAAO,KAAA,KAAU,QAAA,IACjB,KAAA,KAAU,IAAA,IACT,MAA6B,IAAA,KAAS,YAAA;AAE3C","file":"renderers.cjs","sourcesContent":["/**\n * @fileoverview Renderer system types for token output generation\n */\n\nimport type { ModifierInputs, OutputConfig, ResolverDocument } from '@config/index'\nimport type { ResolvedTokens } from '@tokens/types'\n\n/**\n * Generic options object for renderers\n *\n * Each renderer can define its own specific options that extend this base type.\n */\nexport type FormatOptions = Record<string, unknown>\n\n/**\n * Data for a single permutation (combination of modifier values)\n */\nexport type PermutationData = {\n  tokens: ResolvedTokens\n  modifierInputs: ModifierInputs\n}\n\n/**\n * Metadata for renderers to reason about modifier dimensions.\n */\nexport type RenderMeta = {\n  dimensions: string[]\n  defaults: Record<string, string>\n  basePermutation: ModifierInputs\n}\n\n/**\n * Context provided to renderer formatters.\n */\nexport type RenderContext<TOptions extends FormatOptions = FormatOptions> = {\n  permutations: PermutationData[]\n  output: OutputConfig<TOptions>\n  resolver: ResolverDocument\n  meta: RenderMeta\n  buildPath?: string\n}\n\n/**\n * Multi-file output representation for renderers.\n */\nexport type OutputTree = {\n  kind: 'outputTree'\n  files: Record<string, string>\n}\n\nexport type RenderOutput = string | OutputTree\n\n/**\n * Output from a build operation\n */\nexport type BuildOutput = {\n  name: string\n  /** File path where output was written (undefined for in-memory mode) */\n  path?: string\n  content: string\n}\n\n/**\n * Renderer definition for converting tokens to output format\n *\n * Renderers implement a single `format()` method that can return either\n * a single string or an OutputTree for multi-file outputs.\n *\n * @example Simple renderer with format()\n * ```typescript\n * const scssRenderer: Renderer = {\n *   format: (context) => {\n *     const tokens = context.permutations[0]?.tokens ?? {}\n *     return Object.entries(tokens)\n *       .map(([name, token]) => `$${name}: ${token.$value};`)\n *       .join('\\n')\n *   },\n * }\n * ```\n */\nexport type Renderer<TOptions extends FormatOptions = FormatOptions> = {\n  /**\n   * Preset identifier (e.g., 'bundle', 'standalone', 'modifier')\n   * Indicates which variant of the renderer this is\n   */\n  preset?: string\n\n  /**\n   * Convert tokens to output content.\n   *\n   * Renderers receive all resolved permutations and modifier metadata via context.\n   * They can return either a single string (single output file) or an OutputTree\n   * for multi-file outputs.\n   */\n  format: (\n    context: RenderContext<TOptions>,\n    options?: TOptions,\n  ) => RenderOutput | Promise<RenderOutput>\n}\n\n/**\n * Helper for defining custom renderers with full type inference.\n *\n * Works like Vue's `defineComponent()` or Vite's `defineConfig()` --\n * an identity function that enables TypeScript to infer the options type\n * from the generic parameter, giving you autocomplete and type-checking\n * on both `context` and `options` inside `format()`.\n *\n * @example\n * ```typescript\n * import { defineRenderer } from 'dispersa/renderers'\n *\n * type MyOptions = { prefix: string; minify?: boolean }\n *\n * const myRenderer = defineRenderer<MyOptions>({\n *   format(context, options) {\n *     // options is typed as MyOptions | undefined\n *     // context.output.options is typed as MyOptions | undefined\n *     const prefix = options?.prefix ?? 'token'\n *     return Object.entries(context.permutations[0]?.tokens ?? {})\n *       .map(([name, token]) => `${prefix}-${name}: ${token.$value}`)\n *       .join('\\n')\n *   },\n * })\n * ```\n */\nexport function defineRenderer<T extends FormatOptions>(renderer: Renderer<T>): Renderer<T> {\n  return renderer\n}\n\n/**\n * Function type for dynamically generating CSS selectors based on modifier context\n *\n * @param modifierName - Name of the modifier (e.g., 'theme', 'breakpoint')\n * @param context - Context value of the modifier (e.g., 'dark', 'mobile')\n * @param isBase - Whether this is the base permutation\n * @param allModifierInputs - All modifier inputs for this permutation\n * @returns CSS selector string (e.g., '[data-theme=\"dark\"]')\n */\nexport type SelectorFunction = (\n  modifierName: string,\n  context: string,\n  isBase: boolean,\n  allModifierInputs: Record<string, string>,\n) => string\n\n/**\n * Function type for dynamically generating media queries based on modifier context\n *\n * @param modifierName - Name of the modifier (e.g., 'theme', 'breakpoint')\n * @param context - Context value of the modifier (e.g., 'dark', 'mobile')\n * @param isBase - Whether this is the base permutation\n * @param allModifierInputs - All modifier inputs for this permutation\n * @returns Media query string (e.g., '(max-width: 768px)') or empty string for no media query\n */\nexport type MediaQueryFunction = (\n  modifierName: string,\n  context: string,\n  isBase: boolean,\n  allModifierInputs: Record<string, string>,\n) => string\n\n/**\n * Options for CSS custom properties renderer\n *\n * Controls how tokens are converted to CSS custom properties (CSS variables).\n *\n * **Note:** Token naming is controlled through transforms, not renderer options.\n * Use `nameKebabCase()` and `namePrefix()` for naming control.\n *\n * @example String-based selectors\n * ```typescript\n * css({\n *   name: 'tokens',\n *   file: 'tokens.css',\n *   transforms: [nameKebabCase(), namePrefix('ds-')],\n *   preset: 'bundle',\n *   selector: ':root',\n * })\n * ```\n *\n * @example Function-based selectors\n * ```typescript\n * outputs: [{\n *   renderer: cssRenderer(),\n *   options: {\n *     preset: 'bundle',\n *     selector: (modifier, context, isBase, allInputs) => {\n *       if (isBase) return ':root'\n *       return `[data-${modifier}=\"${context}\"]`\n *     },\n *     mediaQuery: (modifier, context) => {\n *       if (modifier === 'breakpoint' && context === 'mobile') {\n *         return '(max-width: 768px)'\n *       }\n *       return ''\n *     }\n *   }\n * }]\n * ```\n */\nexport type CssRendererOptions = {\n  preset?: 'bundle' | 'standalone' | 'modifier'\n  selector?: string | SelectorFunction\n  mediaQuery?: string | MediaQueryFunction\n  minify?: boolean\n  preserveReferences?: boolean\n}\n\n/**\n * Options for JSON renderer\n *\n * Controls the structure and formatting of JSON token output.\n *\n * @example\n * ```typescript\n * {\n *   structure: 'flat',\n *   minify: true,\n *   includeMetadata: true\n * }\n * ```\n */\nexport type { JsonRendererOptions } from '@validation/config-schemas'\n\n/**\n * Options for JavaScript module renderer\n *\n * Generates JavaScript modules for direct import in applications.\n * Aligned with JSON renderer options for consistency.\n *\n * @example\n * ```typescript\n * {\n *   structure: 'nested',\n *   minify: false,\n *   moduleName: 'designTokens'\n * }\n * ```\n */\nexport type { JsModuleRendererOptions } from '@validation/config-schemas'\n\n/**\n * Options for Tailwind CSS v4 renderer\n *\n * Generates CSS with @theme blocks for Tailwind v4+ design token integration.\n */\nexport type { TailwindRendererOptions } from './tailwind'\n\n/**\n * Options for iOS/SwiftUI renderer\n *\n * Generates Swift code targeting SwiftUI (iOS 17+, Swift 6).\n */\nexport type { IosRendererOptions } from './ios'\n\n/**\n * Options for Android/Jetpack Compose renderer\n *\n * Generates Kotlin code targeting Jetpack Compose with Material 3.\n *\n * @experimental This type is experimental. Properties and behavior may change.\n */\nexport type { AndroidRendererOptions } from './android'\n\n/**\n * Result of a token build operation\n *\n * Contains success status, generated output files, and any errors encountered.\n *\n * @example\n * ```typescript\n * const result = await dispersa.build(config)\n * if (result.success) {\n *   result.outputs.forEach(output => {\n *     console.log(`Generated ${output.name}: ${output.path}`)\n *   })\n * } else {\n *   console.error('Build errors:', result.errors)\n * }\n * ```\n */\n/**\n * Error code identifying the type of build error\n */\nexport type ErrorCode =\n  | 'TOKEN_REFERENCE'\n  | 'CIRCULAR_REFERENCE'\n  | 'VALIDATION'\n  | 'FILE_OPERATION'\n  | 'CONFIGURATION'\n  | 'BASE_PERMUTATION'\n  | 'MODIFIER'\n  | 'UNKNOWN'\n\n/**\n * Structured error from a build operation\n *\n * Preserves typed context from the error hierarchy so consumers\n * can programmatically react to specific failure modes.\n */\nexport type BuildError = {\n  /** Human-readable error message */\n  message: string\n\n  /** Machine-readable error code identifying the failure type */\n  code: ErrorCode\n\n  /** File path where the error occurred (for file operation errors) */\n  path?: string\n\n  /** Token path where the error occurred (e.g. 'color.primary') */\n  tokenPath?: string\n\n  /** Error severity */\n  severity: 'error' | 'warning'\n\n  /** Suggested alternatives (e.g. similar token names for TOKEN_REFERENCE errors) */\n  suggestions?: string[]\n}\n\nexport type BuildResult = {\n  /** Whether the build completed successfully */\n  success: boolean\n\n  /** Array of generated output files */\n  outputs: BuildOutput[]\n\n  /** Array of errors encountered during build (only present if success is false) */\n  errors?: BuildError[]\n}\n","/**\n * @fileoverview Output tree helpers for custom renderers\n */\n\nimport type { OutputTree } from './types'\n\n/**\n * Create an {@link OutputTree} from a map of file paths to content strings.\n *\n * Use this when building a custom renderer that produces multiple output files\n * (e.g. one file per theme or permutation).\n *\n * @param files - Record mapping relative file paths to their string content\n * @returns An `OutputTree` that the build orchestrator can write to disk or return in-memory\n *\n * @example\n * ```typescript\n * import { defineRenderer, outputTree } from 'dispersa/renderers'\n *\n * const myRenderer = defineRenderer((context) => {\n *   return outputTree({\n *     'light.css': '/* light tokens *\\/',\n *     'dark.css': '/* dark tokens *\\/',\n *   })\n * })\n * ```\n */\nexport const outputTree = (files: Record<string, string>): OutputTree => {\n  return {\n    kind: 'outputTree',\n    files,\n  }\n}\n\n/**\n * Type guard that checks whether a value is an {@link OutputTree}.\n *\n * @param value - The value to check\n * @returns `true` if the value is an `OutputTree`\n */\nexport const isOutputTree = (value: unknown): value is OutputTree => {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    (value as { kind?: unknown }).kind === 'outputTree'\n  )\n}\n"]}

package/dist/renderers.d.cts

@@ -1,5 +1,5 @@
-import { f as OutputTree } from './index-BkvV7Z54.cjs';
-export { A as AndroidRendererOptions, c as BuildError, a as BuildResult, C as CssRendererOptions, E as ErrorCode, F as FormatOptions, I as IosRendererOptions, e as MediaQueryFunction, P as PermutationData, h as RenderContext, i as RenderMeta, j as RenderOutput, g as Renderer, S as SelectorFunction, T as TailwindRendererOptions, k as defineRenderer } from './index-BkvV7Z54.cjs';
+import { g as OutputTree } from './index-dwm-xYbQ.cjs';
+export { A as AndroidRendererOptions, c as BuildError, d as BuildOutput, a as BuildResult, C as CssRendererOptions, E as ErrorCode, e as FormatOptions, I as IosRendererOptions, f as MediaQueryFunction, P as PermutationData, i as RenderContext, j as RenderMeta, k as RenderOutput, h as Renderer, S as SelectorFunction, T as TailwindRendererOptions, l as defineRenderer } from './index-dwm-xYbQ.cjs';
 export { J as JsModuleRendererOptions, a as JsonRendererOptions } from './types-CussyWwe.cjs';
 import './types-DWKq-eJj.cjs';
 import './types-Bc0kA7De.cjs';

package/dist/renderers.d.ts

@@ -1,5 +1,5 @@
-import { f as OutputTree } from './index-DJ_UHSQG.js';
-export { A as AndroidRendererOptions, c as BuildError, a as BuildResult, C as CssRendererOptions, E as ErrorCode, F as FormatOptions, I as IosRendererOptions, e as MediaQueryFunction, P as PermutationData, h as RenderContext, i as RenderMeta, j as RenderOutput, g as Renderer, S as SelectorFunction, T as TailwindRendererOptions, k as defineRenderer } from './index-DJ_UHSQG.js';
+import { g as OutputTree } from './index-Bkedvob6.js';
+export { A as AndroidRendererOptions, c as BuildError, d as BuildOutput, a as BuildResult, C as CssRendererOptions, E as ErrorCode, e as FormatOptions, I as IosRendererOptions, f as MediaQueryFunction, P as PermutationData, i as RenderContext, j as RenderMeta, k as RenderOutput, h as Renderer, S as SelectorFunction, T as TailwindRendererOptions, l as defineRenderer } from './index-Bkedvob6.js';
 export { J as JsModuleRendererOptions, a as JsonRendererOptions } from './types-CZb19kiq.js';
 import './types-BzNcG-rI.js';
 import './types-Bc0kA7De.js';

package/dist/renderers.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/renderers/types.ts","../src/renderers/output-tree.ts"],"names":[],"mappings":";AA8HO,SAAS,eAAwC,QAAA,EAAoC;AAC1F,EAAA,OAAO,QAAA;AACT;;;ACrGO,IAAM,UAAA,GAAa,CAAC,KAAA,KAA8C;AACvE,EAAA,OAAO;AAAA,IACL,IAAA,EAAM,YAAA;AAAA,IACN;AAAA,GACF;AACF;AAQO,IAAM,YAAA,GAAe,CAAC,KAAA,KAAwC;AACnE,EAAA,OACE,OAAO,KAAA,KAAU,QAAA,IACjB,KAAA,KAAU,IAAA,IACT,MAA6B,IAAA,KAAS,YAAA;AAE3C","file":"renderers.js","sourcesContent":["/**\n * @fileoverview Renderer system types for token output generation\n */\n\nimport type { ModifierInputs, OutputConfig, ResolverDocument } from '@config/index'\nimport type { ResolvedTokens } from '@tokens/types'\n\n/**\n * Generic options object for renderers\n *\n * Each renderer can define its own specific options that extend this base type.\n */\nexport type FormatOptions = Record<string, unknown>\n\n/**\n * Data for a single permutation (combination of modifier values)\n */\nexport type PermutationData = {\n  tokens: ResolvedTokens\n  modifierInputs: ModifierInputs\n}\n\n/**\n * Metadata for renderers to reason about modifier dimensions.\n */\nexport type RenderMeta = {\n  dimensions: string[]\n  defaults: Record<string, string>\n  basePermutation: ModifierInputs\n}\n\n/**\n * Context provided to renderer formatters.\n */\nexport type RenderContext<TOptions extends FormatOptions = FormatOptions> = {\n  permutations: PermutationData[]\n  output: OutputConfig<TOptions>\n  resolver: ResolverDocument\n  meta: RenderMeta\n  buildPath?: string\n}\n\n/**\n * Multi-file output representation for renderers.\n */\nexport type OutputTree = {\n  kind: 'outputTree'\n  files: Record<string, string>\n}\n\nexport type RenderOutput = string | OutputTree\n\n/**\n * Output from a build operation\n */\nexport type BuildOutput = {\n  name: string\n  /** File path where output was written (undefined for in-memory mode) */\n  path?: string\n  content: string\n}\n\n/**\n * Renderer definition for converting tokens to output format\n *\n * Renderers implement a single `format()` method that can return either\n * a single string or an OutputTree for multi-file outputs.\n *\n * @example Simple renderer with format()\n * ```typescript\n * const scssRenderer: Renderer = {\n *   format: (context) => {\n *     const tokens = context.permutations[0]?.tokens ?? {}\n *     return Object.entries(tokens)\n *       .map(([name, token]) => `$${name}: ${token.$value};`)\n *       .join('\\n')\n *   },\n * }\n * ```\n */\nexport type Renderer<TOptions extends FormatOptions = FormatOptions> = {\n  /**\n   * Preset identifier (e.g., 'bundle', 'standalone', 'modifier')\n   * Indicates which variant of the renderer this is\n   */\n  preset?: string\n\n  /**\n   * Convert tokens to output content.\n   *\n   * Renderers receive all resolved permutations and modifier metadata via context.\n   * They can return either a single string (single output file) or an OutputTree\n   * for multi-file outputs.\n   */\n  format: (\n    context: RenderContext<TOptions>,\n    options?: TOptions,\n  ) => RenderOutput | Promise<RenderOutput>\n}\n\n/**\n * Helper for defining custom renderers with full type inference.\n *\n * Works like Vue's `defineComponent()` or Vite's `defineConfig()` --\n * an identity function that enables TypeScript to infer the options type\n * from the generic parameter, giving you autocomplete and type-checking\n * on both `context` and `options` inside `format()`.\n *\n * @example\n * ```typescript\n * import { defineRenderer } from 'dispersa/renderers'\n *\n * type MyOptions = { prefix: string; minify?: boolean }\n *\n * const myRenderer = defineRenderer<MyOptions>({\n *   format(context, options) {\n *     // options is typed as MyOptions | undefined\n *     // context.output.options is typed as MyOptions | undefined\n *     const prefix = options?.prefix ?? 'token'\n *     return Object.entries(context.permutations[0]?.tokens ?? {})\n *       .map(([name, token]) => `${prefix}-${name}: ${token.$value}`)\n *       .join('\\n')\n *   },\n * })\n * ```\n */\nexport function defineRenderer<T extends FormatOptions>(renderer: Renderer<T>): Renderer<T> {\n  return renderer\n}\n\n/**\n * Function type for dynamically generating CSS selectors based on modifier context\n *\n * @param modifierName - Name of the modifier (e.g., 'theme', 'breakpoint')\n * @param context - Context value of the modifier (e.g., 'dark', 'mobile')\n * @param isBase - Whether this is the base permutation\n * @param allModifierInputs - All modifier inputs for this permutation\n * @returns CSS selector string (e.g., '[data-theme=\"dark\"]')\n */\nexport type SelectorFunction = (\n  modifierName: string,\n  context: string,\n  isBase: boolean,\n  allModifierInputs: Record<string, string>,\n) => string\n\n/**\n * Function type for dynamically generating media queries based on modifier context\n *\n * @param modifierName - Name of the modifier (e.g., 'theme', 'breakpoint')\n * @param context - Context value of the modifier (e.g., 'dark', 'mobile')\n * @param isBase - Whether this is the base permutation\n * @param allModifierInputs - All modifier inputs for this permutation\n * @returns Media query string (e.g., '(max-width: 768px)') or empty string for no media query\n */\nexport type MediaQueryFunction = (\n  modifierName: string,\n  context: string,\n  isBase: boolean,\n  allModifierInputs: Record<string, string>,\n) => string\n\n/**\n * Options for CSS custom properties renderer\n *\n * Controls how tokens are converted to CSS custom properties (CSS variables).\n *\n * **Note:** Token naming is controlled through transforms, not renderer options.\n * Use `nameKebabCase()` and `namePrefix()` for naming control.\n *\n * @example String-based selectors\n * ```typescript\n * css({\n *   name: 'tokens',\n *   file: 'tokens.css',\n *   transforms: [nameKebabCase(), namePrefix('ds-')],\n *   preset: 'bundle',\n *   selector: ':root',\n * })\n * ```\n *\n * @example Function-based selectors\n * ```typescript\n * outputs: [{\n *   renderer: cssRenderer(),\n *   options: {\n *     preset: 'bundle',\n *     selector: (modifier, context, isBase, allInputs) => {\n *       if (isBase) return ':root'\n *       return `[data-${modifier}=\"${context}\"]`\n *     },\n *     mediaQuery: (modifier, context) => {\n *       if (modifier === 'breakpoint' && context === 'mobile') {\n *         return '(max-width: 768px)'\n *       }\n *       return ''\n *     }\n *   }\n * }]\n * ```\n */\nexport type CssRendererOptions = {\n  preset?: 'bundle' | 'standalone' | 'modifier'\n  selector?: string | SelectorFunction\n  mediaQuery?: string | MediaQueryFunction\n  minify?: boolean\n  preserveReferences?: boolean\n}\n\n/**\n * Options for JSON renderer\n *\n * Controls the structure and formatting of JSON token output.\n *\n * @example\n * ```typescript\n * {\n *   structure: 'flat',\n *   minify: true,\n *   includeMetadata: true\n * }\n * ```\n */\nexport type { JsonRendererOptions } from '@validation/config-schemas'\n\n/**\n * Options for JavaScript module renderer\n *\n * Generates JavaScript modules for direct import in applications.\n * Aligned with JSON renderer options for consistency.\n *\n * @example\n * ```typescript\n * {\n *   structure: 'nested',\n *   minify: false,\n *   moduleName: 'designTokens'\n * }\n * ```\n */\nexport type { JsModuleRendererOptions } from '@validation/config-schemas'\n\n/**\n * Options for Tailwind CSS v4 renderer\n *\n * Generates CSS with @theme blocks for Tailwind v4+ design token integration.\n */\nexport type { TailwindRendererOptions } from './tailwind'\n\n/**\n * Options for iOS/SwiftUI renderer\n *\n * Generates Swift code targeting SwiftUI (iOS 17+, Swift 6).\n */\nexport type { IosRendererOptions } from './ios'\n\n/**\n * Options for Android/Jetpack Compose renderer\n *\n * Generates Kotlin code targeting Jetpack Compose with Material 3.\n *\n * @experimental This type is experimental. Properties and behavior may change.\n */\nexport type { AndroidRendererOptions } from './android'\n\n/**\n * Result of a token build operation\n *\n * Contains success status, generated output files, and any errors encountered.\n *\n * @example\n * ```typescript\n * const result = await dispersa.build(config)\n * if (result.success) {\n *   result.outputs.forEach(output => {\n *     console.log(`Generated ${output.name}: ${output.path}`)\n *   })\n * } else {\n *   console.error('Build errors:', result.errors)\n * }\n * ```\n */\n/**\n * Error code identifying the type of build error\n */\nexport type ErrorCode =\n  | 'TOKEN_REFERENCE'\n  | 'CIRCULAR_REFERENCE'\n  | 'VALIDATION'\n  | 'COLOR_PARSE'\n  | 'DIMENSION_FORMAT'\n  | 'FILE_OPERATION'\n  | 'CONFIGURATION'\n  | 'BASE_PERMUTATION'\n  | 'MODIFIER'\n  | 'UNKNOWN'\n\n/**\n * Structured error from a build operation\n *\n * Preserves typed context from the error hierarchy so consumers\n * can programmatically react to specific failure modes.\n */\nexport type BuildError = {\n  /** Human-readable error message */\n  message: string\n\n  /** Machine-readable error code identifying the failure type */\n  code: ErrorCode\n\n  /** File path where the error occurred (for file operation errors) */\n  path?: string\n\n  /** Token path where the error occurred (e.g. 'color.primary') */\n  tokenPath?: string\n\n  /** Error severity */\n  severity: 'error' | 'warning'\n\n  /** Suggested alternatives (e.g. similar token names for TOKEN_REFERENCE errors) */\n  suggestions?: string[]\n}\n\nexport type BuildResult = {\n  /** Whether the build completed successfully */\n  success: boolean\n\n  /** Array of generated output files */\n  outputs: BuildOutput[]\n\n  /** Array of errors encountered during build (only present if success is false) */\n  errors?: BuildError[]\n}\n","/**\n * @fileoverview Output tree helpers for custom renderers\n */\n\nimport type { OutputTree } from './types'\n\n/**\n * Create an {@link OutputTree} from a map of file paths to content strings.\n *\n * Use this when building a custom renderer that produces multiple output files\n * (e.g. one file per theme or permutation).\n *\n * @param files - Record mapping relative file paths to their string content\n * @returns An `OutputTree` that the build orchestrator can write to disk or return in-memory\n *\n * @example\n * ```typescript\n * import { defineRenderer, outputTree } from 'dispersa/renderers'\n *\n * const myRenderer = defineRenderer((context) => {\n *   return outputTree({\n *     'light.css': '/* light tokens *\\/',\n *     'dark.css': '/* dark tokens *\\/',\n *   })\n * })\n * ```\n */\nexport const outputTree = (files: Record<string, string>): OutputTree => {\n  return {\n    kind: 'outputTree',\n    files,\n  }\n}\n\n/**\n * Type guard that checks whether a value is an {@link OutputTree}.\n *\n * @param value - The value to check\n * @returns `true` if the value is an `OutputTree`\n */\nexport const isOutputTree = (value: unknown): value is OutputTree => {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    (value as { kind?: unknown }).kind === 'outputTree'\n  )\n}\n"]}
+{"version":3,"sources":["../src/renderers/types.ts","../src/renderers/output-tree.ts"],"names":[],"mappings":";AA8HO,SAAS,eAAwC,QAAA,EAAoC;AAC1F,EAAA,OAAO,QAAA;AACT;;;ACrGO,IAAM,UAAA,GAAa,CAAC,KAAA,KAA8C;AACvE,EAAA,OAAO;AAAA,IACL,IAAA,EAAM,YAAA;AAAA,IACN;AAAA,GACF;AACF;AAQO,IAAM,YAAA,GAAe,CAAC,KAAA,KAAwC;AACnE,EAAA,OACE,OAAO,KAAA,KAAU,QAAA,IACjB,KAAA,KAAU,IAAA,IACT,MAA6B,IAAA,KAAS,YAAA;AAE3C","file":"renderers.js","sourcesContent":["/**\n * @fileoverview Renderer system types for token output generation\n */\n\nimport type { ModifierInputs, OutputConfig, ResolverDocument } from '@config/index'\nimport type { ResolvedTokens } from '@tokens/types'\n\n/**\n * Generic options object for renderers\n *\n * Each renderer can define its own specific options that extend this base type.\n */\nexport type FormatOptions = Record<string, unknown>\n\n/**\n * Data for a single permutation (combination of modifier values)\n */\nexport type PermutationData = {\n  tokens: ResolvedTokens\n  modifierInputs: ModifierInputs\n}\n\n/**\n * Metadata for renderers to reason about modifier dimensions.\n */\nexport type RenderMeta = {\n  dimensions: string[]\n  defaults: Record<string, string>\n  basePermutation: ModifierInputs\n}\n\n/**\n * Context provided to renderer formatters.\n */\nexport type RenderContext<TOptions extends FormatOptions = FormatOptions> = {\n  permutations: PermutationData[]\n  output: OutputConfig<TOptions>\n  resolver: ResolverDocument\n  meta: RenderMeta\n  buildPath?: string\n}\n\n/**\n * Multi-file output representation for renderers.\n */\nexport type OutputTree = {\n  kind: 'outputTree'\n  files: Record<string, string>\n}\n\nexport type RenderOutput = string | OutputTree\n\n/**\n * Output from a build operation\n */\nexport type BuildOutput = {\n  name: string\n  /** File path where output was written (undefined for in-memory mode) */\n  path?: string\n  content: string\n}\n\n/**\n * Renderer definition for converting tokens to output format\n *\n * Renderers implement a single `format()` method that can return either\n * a single string or an OutputTree for multi-file outputs.\n *\n * @example Simple renderer with format()\n * ```typescript\n * const scssRenderer: Renderer = {\n *   format: (context) => {\n *     const tokens = context.permutations[0]?.tokens ?? {}\n *     return Object.entries(tokens)\n *       .map(([name, token]) => `$${name}: ${token.$value};`)\n *       .join('\\n')\n *   },\n * }\n * ```\n */\nexport type Renderer<TOptions extends FormatOptions = FormatOptions> = {\n  /**\n   * Preset identifier (e.g., 'bundle', 'standalone', 'modifier')\n   * Indicates which variant of the renderer this is\n   */\n  preset?: string\n\n  /**\n   * Convert tokens to output content.\n   *\n   * Renderers receive all resolved permutations and modifier metadata via context.\n   * They can return either a single string (single output file) or an OutputTree\n   * for multi-file outputs.\n   */\n  format: (\n    context: RenderContext<TOptions>,\n    options?: TOptions,\n  ) => RenderOutput | Promise<RenderOutput>\n}\n\n/**\n * Helper for defining custom renderers with full type inference.\n *\n * Works like Vue's `defineComponent()` or Vite's `defineConfig()` --\n * an identity function that enables TypeScript to infer the options type\n * from the generic parameter, giving you autocomplete and type-checking\n * on both `context` and `options` inside `format()`.\n *\n * @example\n * ```typescript\n * import { defineRenderer } from 'dispersa/renderers'\n *\n * type MyOptions = { prefix: string; minify?: boolean }\n *\n * const myRenderer = defineRenderer<MyOptions>({\n *   format(context, options) {\n *     // options is typed as MyOptions | undefined\n *     // context.output.options is typed as MyOptions | undefined\n *     const prefix = options?.prefix ?? 'token'\n *     return Object.entries(context.permutations[0]?.tokens ?? {})\n *       .map(([name, token]) => `${prefix}-${name}: ${token.$value}`)\n *       .join('\\n')\n *   },\n * })\n * ```\n */\nexport function defineRenderer<T extends FormatOptions>(renderer: Renderer<T>): Renderer<T> {\n  return renderer\n}\n\n/**\n * Function type for dynamically generating CSS selectors based on modifier context\n *\n * @param modifierName - Name of the modifier (e.g., 'theme', 'breakpoint')\n * @param context - Context value of the modifier (e.g., 'dark', 'mobile')\n * @param isBase - Whether this is the base permutation\n * @param allModifierInputs - All modifier inputs for this permutation\n * @returns CSS selector string (e.g., '[data-theme=\"dark\"]')\n */\nexport type SelectorFunction = (\n  modifierName: string,\n  context: string,\n  isBase: boolean,\n  allModifierInputs: Record<string, string>,\n) => string\n\n/**\n * Function type for dynamically generating media queries based on modifier context\n *\n * @param modifierName - Name of the modifier (e.g., 'theme', 'breakpoint')\n * @param context - Context value of the modifier (e.g., 'dark', 'mobile')\n * @param isBase - Whether this is the base permutation\n * @param allModifierInputs - All modifier inputs for this permutation\n * @returns Media query string (e.g., '(max-width: 768px)') or empty string for no media query\n */\nexport type MediaQueryFunction = (\n  modifierName: string,\n  context: string,\n  isBase: boolean,\n  allModifierInputs: Record<string, string>,\n) => string\n\n/**\n * Options for CSS custom properties renderer\n *\n * Controls how tokens are converted to CSS custom properties (CSS variables).\n *\n * **Note:** Token naming is controlled through transforms, not renderer options.\n * Use `nameKebabCase()` and `namePrefix()` for naming control.\n *\n * @example String-based selectors\n * ```typescript\n * css({\n *   name: 'tokens',\n *   file: 'tokens.css',\n *   transforms: [nameKebabCase(), namePrefix('ds-')],\n *   preset: 'bundle',\n *   selector: ':root',\n * })\n * ```\n *\n * @example Function-based selectors\n * ```typescript\n * outputs: [{\n *   renderer: cssRenderer(),\n *   options: {\n *     preset: 'bundle',\n *     selector: (modifier, context, isBase, allInputs) => {\n *       if (isBase) return ':root'\n *       return `[data-${modifier}=\"${context}\"]`\n *     },\n *     mediaQuery: (modifier, context) => {\n *       if (modifier === 'breakpoint' && context === 'mobile') {\n *         return '(max-width: 768px)'\n *       }\n *       return ''\n *     }\n *   }\n * }]\n * ```\n */\nexport type CssRendererOptions = {\n  preset?: 'bundle' | 'standalone' | 'modifier'\n  selector?: string | SelectorFunction\n  mediaQuery?: string | MediaQueryFunction\n  minify?: boolean\n  preserveReferences?: boolean\n}\n\n/**\n * Options for JSON renderer\n *\n * Controls the structure and formatting of JSON token output.\n *\n * @example\n * ```typescript\n * {\n *   structure: 'flat',\n *   minify: true,\n *   includeMetadata: true\n * }\n * ```\n */\nexport type { JsonRendererOptions } from '@validation/config-schemas'\n\n/**\n * Options for JavaScript module renderer\n *\n * Generates JavaScript modules for direct import in applications.\n * Aligned with JSON renderer options for consistency.\n *\n * @example\n * ```typescript\n * {\n *   structure: 'nested',\n *   minify: false,\n *   moduleName: 'designTokens'\n * }\n * ```\n */\nexport type { JsModuleRendererOptions } from '@validation/config-schemas'\n\n/**\n * Options for Tailwind CSS v4 renderer\n *\n * Generates CSS with @theme blocks for Tailwind v4+ design token integration.\n */\nexport type { TailwindRendererOptions } from './tailwind'\n\n/**\n * Options for iOS/SwiftUI renderer\n *\n * Generates Swift code targeting SwiftUI (iOS 17+, Swift 6).\n */\nexport type { IosRendererOptions } from './ios'\n\n/**\n * Options for Android/Jetpack Compose renderer\n *\n * Generates Kotlin code targeting Jetpack Compose with Material 3.\n *\n * @experimental This type is experimental. Properties and behavior may change.\n */\nexport type { AndroidRendererOptions } from './android'\n\n/**\n * Result of a token build operation\n *\n * Contains success status, generated output files, and any errors encountered.\n *\n * @example\n * ```typescript\n * const result = await dispersa.build(config)\n * if (result.success) {\n *   result.outputs.forEach(output => {\n *     console.log(`Generated ${output.name}: ${output.path}`)\n *   })\n * } else {\n *   console.error('Build errors:', result.errors)\n * }\n * ```\n */\n/**\n * Error code identifying the type of build error\n */\nexport type ErrorCode =\n  | 'TOKEN_REFERENCE'\n  | 'CIRCULAR_REFERENCE'\n  | 'VALIDATION'\n  | 'FILE_OPERATION'\n  | 'CONFIGURATION'\n  | 'BASE_PERMUTATION'\n  | 'MODIFIER'\n  | 'UNKNOWN'\n\n/**\n * Structured error from a build operation\n *\n * Preserves typed context from the error hierarchy so consumers\n * can programmatically react to specific failure modes.\n */\nexport type BuildError = {\n  /** Human-readable error message */\n  message: string\n\n  /** Machine-readable error code identifying the failure type */\n  code: ErrorCode\n\n  /** File path where the error occurred (for file operation errors) */\n  path?: string\n\n  /** Token path where the error occurred (e.g. 'color.primary') */\n  tokenPath?: string\n\n  /** Error severity */\n  severity: 'error' | 'warning'\n\n  /** Suggested alternatives (e.g. similar token names for TOKEN_REFERENCE errors) */\n  suggestions?: string[]\n}\n\nexport type BuildResult = {\n  /** Whether the build completed successfully */\n  success: boolean\n\n  /** Array of generated output files */\n  outputs: BuildOutput[]\n\n  /** Array of errors encountered during build (only present if success is false) */\n  errors?: BuildError[]\n}\n","/**\n * @fileoverview Output tree helpers for custom renderers\n */\n\nimport type { OutputTree } from './types'\n\n/**\n * Create an {@link OutputTree} from a map of file paths to content strings.\n *\n * Use this when building a custom renderer that produces multiple output files\n * (e.g. one file per theme or permutation).\n *\n * @param files - Record mapping relative file paths to their string content\n * @returns An `OutputTree` that the build orchestrator can write to disk or return in-memory\n *\n * @example\n * ```typescript\n * import { defineRenderer, outputTree } from 'dispersa/renderers'\n *\n * const myRenderer = defineRenderer((context) => {\n *   return outputTree({\n *     'light.css': '/* light tokens *\\/',\n *     'dark.css': '/* dark tokens *\\/',\n *   })\n * })\n * ```\n */\nexport const outputTree = (files: Record<string, string>): OutputTree => {\n  return {\n    kind: 'outputTree',\n    files,\n  }\n}\n\n/**\n * Type guard that checks whether a value is an {@link OutputTree}.\n *\n * @param value - The value to check\n * @returns `true` if the value is an `OutputTree`\n */\nexport const isOutputTree = (value: unknown): value is OutputTree => {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    (value as { kind?: unknown }).kind === 'outputTree'\n  )\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dispersa",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "Core library for processing DTCG design tokens",
   "author": "Tim Gesemann",
   "license": "MIT",