dispersa 1.2.0 → 1.3.0

package/dist/types-BxDEUCos.d.ts

@@ -0,0 +1,453 @@
+import { F as Filter } from './types-ebxDimRz.js';
+import { a as ResolvedTokens } from './types-TQHV1MrY.js';
+import { T as Transform } from './types-DztXKlka.js';
+
+/**
+ * @fileoverview DTCG Resolver types (2025.10 specification)
+ *
+ * The resolver system allows defining token sources, modifiers (themes, modes),
+ * and the order in which they should be resolved and merged.
+ *
+ * ResolverDocument type is defined here to match DTCG 2025.10.
+ */
+type ReferenceObject = {
+    $ref: string;
+};
+type TokenSource = ReferenceObject | Record<string, unknown>;
+type Set = {
+    sources: TokenSource[];
+    description?: string;
+    $extensions?: Record<string, unknown>;
+};
+type Modifier = {
+    contexts: Record<string, TokenSource[]>;
+    description?: string;
+    default?: string;
+    $extensions?: Record<string, unknown>;
+};
+type InlineSet = Set & {
+    name: string;
+    type: 'set';
+};
+type InlineModifier = Modifier & {
+    name: string;
+    type: 'modifier';
+};
+type ResolverDocument = {
+    $schema?: string;
+    name?: string;
+    version: '2025.10';
+    description?: string;
+    sets?: Record<string, Set>;
+    modifiers?: Record<string, Modifier>;
+    resolutionOrder: (ReferenceObject | InlineSet | InlineModifier)[];
+    $defs?: Record<string, unknown>;
+};
+/**
+ * Map of modifier names to selected context values
+ *
+ * Used to specify which variation of each modifier to use when resolving tokens.
+ * Can be made type-safe by providing a generic type parameter.
+ *
+ * @template T - Optional specific type for modifier values (defaults to generic Record)
+ *
+ * @example
+ * ```typescript
+ * // Generic (default):
+ * const inputs: ModifierInputs = {
+ *   theme: 'dark',
+ *   platform: 'mobile'
+ * }
+ *
+ * // Type-safe:
+ * type MyModifiers = { theme: 'light' | 'dark', platform: 'web' | 'mobile' }
+ * const inputs: ModifierInputs<MyModifiers> = {
+ *   theme: 'dark',  // ✅ Autocomplete!
+ *   platform: 'mobile'
+ * }
+ * ```
+ */
+type ModifierInputs<T extends Record<string, string> = Record<string, string>> = T;
+
+/**
+ * @fileoverview Renderer system types for token output generation
+ *
+ * Note: outputs/types has types for both renderers (Renderer, RenderContext)
+ * and output configuration (OutputConfig, LifecycleHooks). This works because
+ * they're all related to the output phase of token processing.
+ */
+
+/**
+ * Generic options object for renderers
+ *
+ * Each renderer can define its own specific options that extend this base type.
+ */
+type FormatOptions = Record<string, unknown>;
+/**
+ * Data for a single permutation (combination of modifier values)
+ */
+type PermutationData = {
+    tokens: ResolvedTokens;
+    modifierInputs: ModifierInputs;
+};
+/**
+ * Metadata for renderers to reason about modifier dimensions.
+ */
+type RenderMeta = {
+    dimensions: string[];
+    defaults: Record<string, string>;
+    basePermutation: ModifierInputs;
+};
+/**
+ * Context provided to renderer formatters.
+ */
+type RenderContext<TOptions extends FormatOptions = FormatOptions> = {
+    permutations: PermutationData[];
+    output: OutputConfig<TOptions>;
+    resolver: ResolverDocument;
+    meta: RenderMeta;
+    buildPath?: string;
+};
+/**
+ * Multi-file output representation for renderers.
+ */
+type OutputTree = {
+    kind: 'outputTree';
+    files: Record<string, string>;
+};
+type RenderOutput = string | OutputTree;
+/**
+ * Output from a build operation
+ */
+type BuildOutput = {
+    name: string;
+    /** File path where output was written (undefined for in-memory mode) */
+    path?: string;
+    content: string;
+};
+/**
+ * Renderer definition for converting tokens to output format
+ *
+ * Renderers implement a single `format()` method that can return either
+ * a single string or an OutputTree for multi-file outputs.
+ *
+ * @example Simple renderer with format()
+ * ```typescript
+ * const scssRenderer: Renderer = {
+ *   format: (context) => {
+ *     const tokens = context.permutations[0]?.tokens ?? {}
+ *     return Object.entries(tokens)
+ *       .map(([name, token]) => `$${name}: ${token.$value};`)
+ *       .join('\n')
+ *   },
+ * }
+ * ```
+ */
+type Renderer<TOptions extends FormatOptions = FormatOptions> = {
+    /**
+     * Preset identifier (e.g., 'bundle', 'standalone', 'modifier')
+     * Indicates which variant of the renderer this is
+     */
+    preset?: string;
+    /**
+     * Convert tokens to output content.
+     *
+     * Renderers receive all resolved permutations and modifier metadata via context.
+     * They can return either a single string (single output file) or an OutputTree
+     * for multi-file outputs.
+     */
+    format: (context: RenderContext<TOptions>, options?: TOptions) => RenderOutput | Promise<RenderOutput>;
+};
+/**
+ * Helper for defining custom renderers with full type inference.
+ *
+ * Works like Vue's `defineComponent()` or Vite's `defineConfig()` --
+ * an identity function that enables TypeScript to infer the options type
+ * from the generic parameter, giving you autocomplete and type-checking
+ * on both `context` and `options` inside `format()`.
+ *
+ * @example
+ * ```typescript
+ * import { defineRenderer } from 'dispersa/outputs'
+ *
+ * type MyOptions = { prefix: string; minify?: boolean }
+ *
+ * const myRenderer = defineRenderer<MyOptions>({
+ *   format(context, options) {
+ *     // options is typed as MyOptions | undefined
+ *     // context.output.options is typed as MyOptions | undefined
+ *     const prefix = options?.prefix ?? 'token'
+ *     return Object.entries(context.permutations[0]?.tokens ?? {})
+ *       .map(([name, token]) => `${prefix}-${name}: ${token.$value}`)
+ *       .join('\n')
+ *   },
+ * })
+ * ```
+ */
+declare function defineRenderer<T extends FormatOptions>(renderer: Renderer<T>): Renderer<T>;
+/**
+ * Function type for dynamically generating CSS selectors based on modifier context
+ *
+ * @param modifierName - Name of the modifier (e.g., 'theme', 'breakpoint')
+ * @param context - Context value of the modifier (e.g., 'dark', 'mobile')
+ * @param isBase - Whether this is the base permutation
+ * @param allModifierInputs - All modifier inputs for this permutation
+ * @returns CSS selector string (e.g., '[data-theme="dark"]')
+ */
+type SelectorFunction = (modifierName: string, context: string, isBase: boolean, allModifierInputs: Record<string, string>) => string;
+/**
+ * Function type for dynamically generating media queries based on modifier context
+ *
+ * @param modifierName - Name of the modifier (e.g., 'theme', 'breakpoint')
+ * @param context - Context value of the modifier (e.g., 'dark', 'mobile')
+ * @param isBase - Whether this is the base permutation
+ * @param allModifierInputs - All modifier inputs for this permutation
+ * @returns Media query string (e.g., '(max-width: 768px)') or empty string for no media query
+ */
+type MediaQueryFunction = (modifierName: string, context: string, isBase: boolean, allModifierInputs: Record<string, string>) => string;
+/**
+ * Options for CSS custom properties renderer
+ *
+ * Controls how tokens are converted to CSS custom properties (CSS variables).
+ *
+ * **Note:** Token naming is controlled through transforms, not renderer options.
+ * Use `nameKebabCase()` and `namePrefix()` for naming control.
+ *
+ * @example String-based selectors
+ * ```typescript
+ * css({
+ *   name: 'tokens',
+ *   file: 'tokens.css',
+ *   transforms: [nameKebabCase(), namePrefix('ds-')],
+ *   preset: 'bundle',
+ *   selector: ':root',
+ * })
+ * ```
+ *
+ * @example Function-based selectors
+ * ```typescript
+ * outputs: [{
+ *   renderer: cssRenderer(),
+ *   options: {
+ *     preset: 'bundle',
+ *     selector: (modifier, context, isBase, allInputs) => {
+ *       if (isBase) return ':root'
+ *       return `[data-${modifier}="${context}"]`
+ *     },
+ *     mediaQuery: (modifier, context) => {
+ *       if (modifier === 'breakpoint' && context === 'mobile') {
+ *         return '(max-width: 768px)'
+ *       }
+ *       return ''
+ *     }
+ *   }
+ * }]
+ * ```
+ */
+type CssRendererOptions = {
+    preset?: 'bundle' | 'standalone' | 'modifier';
+    selector?: string | SelectorFunction;
+    mediaQuery?: string | MediaQueryFunction;
+    minify?: boolean;
+    preserveReferences?: boolean;
+};
+
+/**
+ * Result of a token build operation
+ *
+ * Contains success status, generated output files, and any errors encountered.
+ *
+ * @example
+ * ```typescript
+ * const result = await build(config)
+ * if (result.success) {
+ *   result.outputs.forEach(output => {
+ *     console.log(`Generated ${output.name}: ${output.path}`)
+ *   })
+ * } else {
+ *   console.error('Build errors:', result.errors)
+ * }
+ * ```
+ */
+/**
+ * Error code identifying the type of build error
+ */
+type ErrorCode = 'TOKEN_REFERENCE' | 'CIRCULAR_REFERENCE' | 'VALIDATION' | 'FILE_OPERATION' | 'CONFIGURATION' | 'BASE_PERMUTATION' | 'MODIFIER' | 'UNKNOWN';
+/**
+ * Structured error from a build operation
+ *
+ * Preserves typed context from the error hierarchy so consumers
+ * can programmatically react to specific failure modes.
+ */
+type BuildError = {
+    /** Human-readable error message */
+    message: string;
+    /** Machine-readable error code identifying the failure type */
+    code: ErrorCode;
+    /** File path where the error occurred (for file operation errors) */
+    path?: string;
+    /** Token path where the error occurred (e.g. 'color.primary') */
+    tokenPath?: string;
+    /** Error severity */
+    severity: 'error' | 'warning';
+    /** Suggested alternatives (e.g. similar token names for TOKEN_REFERENCE errors) */
+    suggestions?: string[];
+};
+type BuildResult = {
+    /** Whether the build completed successfully */
+    success: boolean;
+    /** Array of generated output files */
+    outputs: BuildOutput[];
+    /** Array of errors encountered during build (only present if success is false) */
+    errors?: BuildError[];
+};
+/**
+ * Lifecycle hooks for the build process.
+ *
+ * The same hook type is used on both global build config (BuildConfig.hooks) and
+ * per-output config (OutputConfig.hooks). All hooks are optional and support
+ * both sync and async functions.
+ *
+ * **Execution order:**
+ * 1. Global `onBuildStart`
+ * 2. For each output: per-output `onBuildStart` → process → per-output `onBuildEnd`
+ * 3. Global `onBuildEnd`
+ */
+type LifecycleHooks = {
+    /** Called before permutation resolution and output processing begins */
+    onBuildStart?: (context: {
+        config: unknown;
+        resolver: string | ResolverDocument;
+    }) => void | Promise<void>;
+    /** Called after all outputs have been processed (success or failure) */
+    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
+ *
+ * Defines how tokens should be formatted and output for a specific target
+ * format (CSS, JSON, JavaScript, etc.).
+ *
+ * **Processing Order:**
+ * - Global filters (from BuildConfig) are applied first to all outputs
+ * - Then output-specific filters are applied (AND logic with global filters)
+ * - Global transforms are applied next
+ * - Finally output-specific transforms are applied
+ *
+ * **Output File Names:**
+ * The `file` field supports subdirectories and dynamic naming patterns.
+ * Parent directories are created automatically.
+ *
+ * @example Using builder helpers (recommended)
+ * ```typescript
+ * import { css, json } from 'dispersa'
+ * import { colorToHex, dimensionToPx } from 'dispersa/transforms'
+ *
+ * // CSS output with transforms
+ * css({
+ *   name: 'css',
+ *   file: 'css/tokens.css',
+ *   preset: 'bundle',
+ *   selector: ':root',
+ *   transforms: [colorToHex(), dimensionToPx()],
+ * })
+ *
+ * // JSON output with static filename
+ * json({
+ *   name: 'json',
+ *   file: 'json/tokens.json',
+ *   preset: 'standalone',
+ *   structure: 'flat',
+ * })
+ * ```
+ *
+ * @example Pattern-based and function-based filenames
+ * ```typescript
+ * import { css } from 'dispersa'
+ *
+ * // Standalone mode with pattern-based filename
+ * css({
+ *   name: 'css-standalone',
+ *   file: 'tokens-{theme}-{platform}.css', // → tokens-light-web.css, tokens-dark-mobile.css
+ *   preset: 'standalone',
+ *   selector: ':root',
+ * })
+ *
+ * // Function-based filename
+ * css({
+ *   name: 'css-custom',
+ *   preset: 'standalone',
+ *   selector: ':root',
+ *   file: (modifierInputs) => {
+ *     const parts = Object.entries(modifierInputs).map(([k, v]) => `${k}-${v}`)
+ *     return `tokens-${parts.join('-')}.css`
+ *   },
+ * })
+ * ```
+ *
+ * @see CssRendererOptions
+ * @see JsonRendererOptions
+ * @see JsModuleRendererOptions
+ */
+type OutputConfig<TOptions extends FormatOptions = FormatOptions> = {
+    /** Unique identifier for this output */
+    name: string;
+    /** Renderer instance (created via renderer factory function) */
+    renderer: Renderer<TOptions>;
+    /**
+     * Array of filter objects to apply
+     * Filters are applied before transforms (to select which tokens to process)
+     */
+    filters?: Filter[];
+    /** Array of transform objects to apply */
+    transforms?: Transform[];
+    /**
+     * Output file path, can be static or dynamic
+     *
+     * Supports subdirectories (e.g., "css/tokens.css").
+     * In standalone preset (one file per permutation), supports:
+     * - Pattern strings with placeholders: `tokens-{theme}-{platform}.css`
+     * - Function that receives modifierInputs: `(modifierInputs) => \`tokens-${...}.css\``
+     * - Plain string (applies default pattern with all modifiers)
+     *
+     * @example
+     * ```typescript
+     * // Static filename (bundle preset or single permutation)
+     * file: 'tokens.css'
+     *
+     * // With subdirectory
+     * file: 'css/tokens.css'
+     *
+     * // Pattern with placeholders (standalone preset)
+     * file: 'tokens-{theme}-{platform}.css'
+     *
+     * // Function for complex logic (standalone preset)
+     * file: (modifierInputs) => {
+     *   const parts = Object.entries(modifierInputs).map(([k, v]) => `${k}-${v}`)
+     *   return `output/${parts.join('-')}/tokens.css`
+     * }
+     * ```
+     */
+    file?: string | FileFunction;
+    /**
+     * Renderer-specific options passed to the formatter.
+     */
+    options?: TOptions;
+    /**
+     * Lifecycle hooks for this output.
+     *
+     * Per-output hooks fire in addition to global hooks on BuildConfig.
+     * `onBuildStart` fires before this output is processed,
+     * `onBuildEnd` fires after this output finishes (success or failure).
+     */
+    hooks?: LifecycleHooks;
+};
+
+export { type BuildError as B, type CssRendererOptions as C, type ErrorCode as E, type FileFunction as F, type LifecycleHooks as L, type MediaQueryFunction as M, type OutputConfig as O, type PermutationData as P, type Renderer as R, type SelectorFunction as S, type BuildOutput as a, type BuildResult as b, type FormatOptions as c, type OutputTree as d, type RenderContext as e, type RenderMeta as f, type RenderOutput as g, type ModifierInputs as h, type ResolverDocument as i, defineRenderer as j };

package/dist/types-DUc4vLZH.d.cts

@@ -0,0 +1,36 @@
+import { K as InternalTokenDocument } from './types-TQHV1MrY.cjs';
+import { P as PreprocessorPluginBase } from './config-schemas-DnEBhIg0.cjs';
+
+/**
+ * @fileoverview Preprocessor system types for raw token transformation
+ */
+
+/**
+ * Preprocessor definition for transforming raw token data
+ *
+ * Preprocessors operate on the raw token object before parsing and resolution.
+ * They are useful for normalizing data, stripping metadata, or adapting tokens
+ * from external sources to match expected formats.
+ *
+ * @example
+ * ```typescript
+ * const stripMetadata: Preprocessor = {
+ *   name: 'strip-metadata',
+ *   preprocess: (rawTokens) => {
+ *     const { _metadata, ...tokens } = rawTokens
+ *     return tokens
+ *   }
+ * }
+ * ```
+ */
+type Preprocessor = Pick<PreprocessorPluginBase, 'name'> & {
+    /**
+     * Function that transforms raw token data
+     *
+     * @param rawTokens - Raw token object before parsing
+     * @returns Transformed token object (can be async)
+     */
+    preprocess: (rawTokens: InternalTokenDocument) => InternalTokenDocument | Promise<InternalTokenDocument>;
+};
+
+export type { Preprocessor as P };

package/dist/types-s3UoDRKl.d.ts

@@ -0,0 +1,36 @@
+import { K as InternalTokenDocument } from './types-TQHV1MrY.js';
+import { P as PreprocessorPluginBase } from './config-schemas-DnEBhIg0.js';
+
+/**
+ * @fileoverview Preprocessor system types for raw token transformation
+ */
+
+/**
+ * Preprocessor definition for transforming raw token data
+ *
+ * Preprocessors operate on the raw token object before parsing and resolution.
+ * They are useful for normalizing data, stripping metadata, or adapting tokens
+ * from external sources to match expected formats.
+ *
+ * @example
+ * ```typescript
+ * const stripMetadata: Preprocessor = {
+ *   name: 'strip-metadata',
+ *   preprocess: (rawTokens) => {
+ *     const { _metadata, ...tokens } = rawTokens
+ *     return tokens
+ *   }
+ * }
+ * ```
+ */
+type Preprocessor = Pick<PreprocessorPluginBase, 'name'> & {
+    /**
+     * Function that transforms raw token data
+     *
+     * @param rawTokens - Raw token object before parsing
+     * @returns Transformed token object (can be async)
+     */
+    preprocess: (rawTokens: InternalTokenDocument) => InternalTokenDocument | Promise<InternalTokenDocument>;
+};
+
+export type { Preprocessor as P };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dispersa",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Core library for processing DTCG design tokens",
   "author": "Tim Gesemann",
   "license": "MIT",
@@ -48,62 +48,52 @@
     },
     "./transforms": {
       "import": {
-        "types": "./dist/transforms.d.ts",
-        "default": "./dist/transforms.js"
+        "types": "./dist/processing/transforms/index.d.ts",
+        "default": "./dist/processing/transforms/index.js"
       },
       "require": {
-        "types": "./dist/transforms.d.cts",
-        "default": "./dist/transforms.cjs"
+        "types": "./dist/processing/transforms/index.d.cts",
+        "default": "./dist/processing/transforms/index.cjs"
       }
     },
     "./filters": {
       "import": {
-        "types": "./dist/filters.d.ts",
-        "default": "./dist/filters.js"
+        "types": "./dist/processing/filters/index.d.ts",
+        "default": "./dist/processing/filters/index.js"
       },
       "require": {
-        "types": "./dist/filters.d.cts",
-        "default": "./dist/filters.cjs"
+        "types": "./dist/processing/filters/index.d.cts",
+        "default": "./dist/processing/filters/index.cjs"
       }
     },
-    "./builders": {
+    "./outputs": {
       "import": {
-        "types": "./dist/builders.d.ts",
-        "default": "./dist/builders.js"
+        "types": "./dist/outputs/index.d.ts",
+        "default": "./dist/outputs/index.js"
       },
       "require": {
-        "types": "./dist/builders.d.cts",
-        "default": "./dist/builders.cjs"
-      }
-    },
-    "./renderers": {
-      "import": {
-        "types": "./dist/renderers.d.ts",
-        "default": "./dist/renderers.js"
-      },
-      "require": {
-        "types": "./dist/renderers.d.cts",
-        "default": "./dist/renderers.cjs"
+        "types": "./dist/outputs/index.d.cts",
+        "default": "./dist/outputs/index.cjs"
       }
     },
     "./preprocessors": {
       "import": {
-        "types": "./dist/preprocessors.d.ts",
-        "default": "./dist/preprocessors.js"
+        "types": "./dist/processing/preprocessors/index.d.ts",
+        "default": "./dist/processing/preprocessors/index.js"
       },
       "require": {
-        "types": "./dist/preprocessors.d.cts",
-        "default": "./dist/preprocessors.cjs"
+        "types": "./dist/processing/preprocessors/index.d.cts",
+        "default": "./dist/processing/preprocessors/index.cjs"
       }
     },
     "./errors": {
       "import": {
-        "types": "./dist/errors.d.ts",
-        "default": "./dist/errors.js"
+        "types": "./dist/shared/errors/index.d.ts",
+        "default": "./dist/shared/errors/index.js"
       },
       "require": {
-        "types": "./dist/errors.d.cts",
-        "default": "./dist/errors.cjs"
+        "types": "./dist/shared/errors/index.d.cts",
+        "default": "./dist/shared/errors/index.cjs"
       }
     },
     "./config": {
@@ -120,12 +110,12 @@
     },
     "./lint": {
       "import": {
-        "types": "./dist/lint.d.ts",
-        "default": "./dist/lint.js"
+        "types": "./dist/lint/index.d.ts",
+        "default": "./dist/lint/index.js"
       },
       "require": {
-        "types": "./dist/lint.d.cts",
-        "default": "./dist/lint.cjs"
+        "types": "./dist/lint/index.d.cts",
+        "default": "./dist/lint/index.cjs"
       }
     }
   },