dispersa 0.1.1

package/dist/index-CPB9Ea9U.d.ts

@@ -0,0 +1,581 @@
+import { F as Filter } from './types-Cl-1UYGD.js';
+import { B as BuildConfigBase, O as OutputConfigBase, P as Preprocessor, D as DispersaOptionsBase } from './types-DJH6_4U9.js';
+import { T as Transform } from './types-DdPWYkgh.js';
+import { R as ResolvedTokens } from './types-C1GpiJ6q.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
+ */
+
+/**
+ * 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/renderers'
+ *
+ * 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 dispersa.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' | 'COLOR_PARSE' | 'DIMENSION_FORMAT' | '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[];
+};
+
+/**
+ * @fileoverview Validation configuration types
+ */
+/** Controls how validation issues are reported */
+type ValidationMode = 'error' | 'warn' | 'off';
+/**
+ * Options that control token and resolver validation behavior.
+ *
+ * @example
+ * ```typescript
+ * const dispersa = new Dispersa({
+ *   validation: { mode: 'warn' },
+ * })
+ * ```
+ */
+type ValidationOptions = {
+    /**
+     * Validation mode.
+     * - `'error'` (default) – throw on validation failures
+     * - `'warn'` – log warnings via `console.warn` but continue processing
+     * - `'off'` – skip validation entirely
+     */
+    mode?: ValidationMode;
+};
+
+/**
+ * @fileoverview Configuration types for Dispersa
+ */
+
+/**
+ * Lifecycle hooks for the build process.
+ *
+ * The same hook type is used on both `BuildConfig.hooks` (global) and
+ * `OutputConfig.hooks` (per-output). 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: BuildConfig;
+        resolver: string | ResolverDocument;
+    }) => void | Promise<void>;
+    /** Called after all outputs have been processed (success or failure) */
+    onBuildEnd?: (result: BuildResult) => void | Promise<void>;
+};
+
+/**
+ * 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> = Omit<OutputConfigBase, 'renderer' | 'transforms' | 'filters' | 'file'> & {
+    /** 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 | ((modifierInputs: ModifierInputs) => string);
+    /**
+     * 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;
+};
+/**
+ * Complete build configuration for Dispersa
+ *
+ * Defines all aspects of the token build process including input sources,
+ * output targets, transforms, and permutation handling.
+ *
+ * **Complete Token Processing Pipeline:**
+ *
+ * 1. **Preprocessors** (BuildConfig.preprocessors)
+ *    - Operate on raw JSON before parsing
+ *    - Transform raw data structures
+ *    - Example: strip custom metadata, inject env vars
+ *
+ * 2. **Parse & Resolve**
+ *    - Parse token files according to DTCG spec
+ *    - Resolve references between tokens
+ *    - Apply modifiers (themes, modes, etc.)
+ *    - Output: ResolvedTokens
+ *
+ * 3. **Global Filters** (BuildConfig.filters)
+ *    - Applied to all tokens for all outputs
+ *    - Example: exclude deprecated tokens globally
+ *
+ * 4. **Global Transforms** (BuildConfig.transforms)
+ *    - Applied to all tokens for all outputs
+ *    - Example: global naming conventions
+ *
+ * 5. **Per-Output Processing** (for each OutputConfig):
+ *    a. **Output Filters** - Select which tokens to include (AND logic)
+ *    b. **Output Transforms** - Modify selected tokens only
+ *    c. **Renderer** - Generate output format and bundle output
+ *
+ * All transforms and filters are applied in array order.
+ *
+ * @example Basic usage with global filters and transforms
+ * ```typescript
+ * import { Dispersa, css, json } from 'dispersa'
+ * import { byType } from 'dispersa/filters'
+ * import { colorToHex, nameKebabCase } from 'dispersa/transforms'
+ *
+ * await dispersa.build({
+ *   outputs: [
+ *     css({ name: 'css', preset: 'bundle', selector: ':root' }),
+ *     json({ name: 'json', preset: 'standalone', structure: 'flat' }),
+ *   ],
+ *   filters: [byType('color')], // Global filter - only include color tokens for all outputs
+ *   transforms: [nameKebabCase(), colorToHex()], // Global transforms for all outputs
+ * })
+ * ```
+ *
+ * @example Combining global and output-specific filters
+ * ```typescript
+ * import { css, json } from 'dispersa'
+ * import { byType } from 'dispersa/filters'
+ * import { nameKebabCase } from 'dispersa/transforms'
+ *
+ * await dispersa.build({
+ *   outputs: [
+ *     css({
+ *       name: 'css',
+ *       preset: 'bundle',
+ *       selector: ':root',
+ *     }),
+ *     json({
+ *       name: 'json',
+ *       preset: 'standalone',
+ *       structure: 'flat',
+ *     }),
+ *   ],
+ *   filters: [byType('color')],
+ *   transforms: [nameKebabCase()],
+ * })
+ * ```
+ */
+type BuildConfig = Omit<BuildConfigBase, 'outputs' | 'filters' | 'transforms' | 'preprocessors' | 'permutations'> & {
+    /** Resolver configuration - file path or inline ResolverDocument */
+    resolver?: string | ResolverDocument;
+    /** Output directory for generated files */
+    buildPath?: string;
+    /** Array of output configurations defining target formats */
+    outputs: OutputConfig[];
+    /** Global filters to apply to all outputs before output-specific filters */
+    filters?: Filter[];
+    /** Global transforms to apply to all tokens before output-specific transforms */
+    transforms?: Transform[];
+    /** Global preprocessors to apply to raw token data before parsing */
+    preprocessors?: Preprocessor[];
+    /** Explicit permutations to build (modifier inputs) */
+    permutations?: ModifierInputs[];
+    /** Global lifecycle hooks for the build process */
+    hooks?: LifecycleHooks;
+};
+/**
+ * Global options for Dispersa instance behavior
+ *
+ * Uses the generated base type from schemas - all properties match exactly.
+ */
+/**
+ * Dispersa options with runtime-only validation helpers
+ *
+ * Schema validation supports "validation.mode" but cannot validate functions.
+ */
+type DispersaOptions = Omit<DispersaOptionsBase, 'validation'> & {
+    /** Resolver configuration - file path or inline ResolverDocument */
+    resolver?: string | ResolverDocument;
+    /** Default output directory for generated files */
+    buildPath?: string;
+    validation?: ValidationOptions;
+};
+
+export { type BuildConfig as B, type CssRendererOptions as C, type DispersaOptions as D, type ErrorCode as E, type FormatOptions as F, 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 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 };