dispersa 1.2.0 → 1.3.0

package/README.md

@@ -800,8 +800,7 @@ When calling `build()` or `buildOrThrow()`, pass a `BuildConfig` object:
 | `dispersa`               | Core functions (`build`, `lint`, etc.), builder functions, types       |
 | `dispersa/transforms`    | Built-in transform factories                                           |
 | `dispersa/filters`       | Built-in filter factories                                              |
-| `dispersa/builders`      | Output builder functions                                               |
-| `dispersa/renderers`     | Renderer types, `defineRenderer`, and `outputTree` helper              |
+| `dispersa/outputs`       | Renderer types, builder functions, `defineRenderer`, and `outputTree`  |
 | `dispersa/preprocessors` | Preprocessor type                                                      |
 | `dispersa/errors`        | Error classes (`DispersaError`, `TokenReferenceError`, etc.)           |
 | `dispersa/config`        | `defineConfig` helper for CLI config files                             |

package/dist/{builders.d.cts → builders-B7_pBy58.d.cts}

@@ -1,10 +1,184 @@
-import { F as FileFunction, L as LifecycleHooks, C as CssRendererOptions, O as OutputConfig } from './index-De6SjZYH.cjs';
+import { S as SelectorFunction, M as MediaQueryFunction, R as Renderer, F as FileFunction, L as LifecycleHooks, C as CssRendererOptions, O as OutputConfig } from './types-B0cI70Bt.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';
+import { a as JsonRendererOptions, J as JsModuleRendererOptions } from './config-schemas-DnEBhIg0.cjs';
+
+/**
+ * @license MIT
+ * Copyright (c) 2025-present Dispersa Contributors
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * Options for Tailwind CSS v4 renderer
+ *
+ * Controls how tokens are converted to Tailwind v4 @theme CSS variables.
+ *
+ * @example Bundle with dark mode overrides
+ * ```typescript
+ * tailwind({
+ *   name: 'tailwind',
+ *   file: 'theme.css',
+ *   preset: 'bundle',
+ *   selector: (modifier, context, isBase) => {
+ *     if (isBase) return ':root'
+ *     return `[data-${modifier}="${context}"]`
+ *   },
+ * })
+ * ```
+ */
+type TailwindRendererOptions = {
+    preset?: 'bundle' | 'standalone';
+    includeImport?: boolean;
+    namespace?: string;
+    minify?: boolean;
+    selector?: string | SelectorFunction;
+    mediaQuery?: string | MediaQueryFunction;
+};
+/**
+ * Tailwind CSS v4 renderer factory function.
+ *
+ * @example
+ * ```typescript
+ * outputs: [{
+ *   name: 'tailwind',
+ *   renderer: tailwindRenderer(),
+ *   options: {
+ *     preset: 'bundle',
+ *     includeImport: true,
+ *   },
+ *   file: 'theme.css'
+ * }]
+ * ```
+ */
+declare function tailwindRenderer(): Renderer<TailwindRendererOptions>;
+
+/**
+ * @license MIT
+ * Copyright (c) 2025-present Dispersa Contributors
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * Options for iOS/SwiftUI renderer
+ */
+type IosRendererOptions = {
+    preset?: 'standalone';
+    accessLevel?: 'public' | 'internal';
+    /**
+     * Output structure:
+     * - `'enum'` — nested enums inside a single root enum
+     * - `'grouped'` — namespace enum with separate extensions per token group
+     */
+    structure?: 'enum' | 'grouped';
+    enumName?: string;
+    /** Namespace enum name used in grouped mode (default: 'DesignTokens') */
+    extensionNamespace?: string;
+    colorSpace?: 'sRGB' | 'displayP3';
+    /**
+     * Target Swift language version.
+     * - `'5.9'` (default) — standard static let declarations
+     * - `'6.0'` — adds `nonisolated(unsafe)` to static properties for
+     *   Swift 6 strict concurrency compliance
+     */
+    swiftVersion?: '5.9' | '6.0';
+    /** Number of spaces per indentation level (default 4) */
+    indent?: number;
+    /** Add @frozen annotation to enums and structs for ABI stability (default false) */
+    frozen?: boolean;
+};
+/**
+ * iOS/SwiftUI renderer factory function.
+ *
+ * @example
+ * ```typescript
+ * outputs: [{
+ *   name: 'ios',
+ *   renderer: iosRenderer(),
+ *   options: {
+ *     accessLevel: 'public',
+ *     structure: 'enum',  // or 'grouped' for extension-based layout
+ *     enumName: 'DesignTokens',
+ *     colorSpace: 'sRGB',
+ *   },
+ *   file: 'DesignTokens-{theme}.swift'
+ * }]
+ * ```
+ */
+declare function iosRenderer(): Renderer<IosRendererOptions>;
+
+/**
+ * @license MIT
+ * Copyright (c) 2025-present Dispersa Contributors
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * Options for Android/Jetpack Compose renderer
+ *
+ * Note: `packageName` is marked optional for type compatibility with the Renderer
+ * generic, but is validated as required at runtime in the renderer's format() method.
+ *
+ * @experimental This type is experimental. Properties and behavior may change.
+ */
+type AndroidRendererOptions = {
+    preset?: 'standalone' | 'bundle';
+    packageName?: string;
+    objectName?: string;
+    /**
+     * Color output format for Kotlin Color initializers.
+     * - `'argb_hex'` (default) — `Color(0xAARRGGBB)` hex literal
+     * - `'argb_float'` — `Color(r, g, b, a)` float components
+     *
+     * Legacy aliases: `'argb8'` maps to `'argb_hex'`, `'argb_floats'` maps to `'argb_float'`.
+     */
+    colorFormat?: 'argb_hex' | 'argb_float' | 'argb8' | 'argb_floats';
+    /**
+     * Color space for generated Color values.
+     * - `'sRGB'` (default) — standard sRGB color space
+     * - `'displayP3'` — Display P3 wide gamut via `ColorSpaces.DisplayP3`
+     */
+    colorSpace?: 'sRGB' | 'displayP3';
+    /**
+     * Structure mode for token organization.
+     * - `'nested'` (default) — mirror token path hierarchy as nested objects
+     * - `'flat'` — group tokens by $type into semantic sub-objects (Colors, Spacing, etc.)
+     */
+    structure?: 'nested' | 'flat';
+    /**
+     * Kotlin visibility modifier for the generated object and its members.
+     * - `undefined` (default) — no explicit modifier, which means `public` in Kotlin
+     * - `'public'` — explicit `public object` / `public val`
+     * - `'internal'` — `internal object` / `internal val` (useful for KMP / multi-module)
+     */
+    visibility?: 'public' | 'internal';
+    /** Number of spaces per indentation level (default 4) */
+    indent?: number;
+};
+/**
+ * Android/Jetpack Compose renderer factory function.
+ *
+ * @example
+ * ```typescript
+ * outputs: [{
+ *   name: 'android',
+ *   renderer: androidRenderer(),
+ *   options: {
+ *     packageName: 'com.example.tokens',
+ *     objectName: 'DesignTokens',
+ *     colorFormat: 'argb_hex',
+ *   },
+ *   file: 'DesignTokens-{theme}.kt'
+ * }]
+ * ```
+ */
+declare function androidRenderer(): Renderer<AndroidRendererOptions>;
 
 /**
  * @license
@@ -376,4 +550,4 @@ type AndroidBuilderConfig = BuilderConfigBase & AndroidRendererOptions;
  */
 declare function android(config: AndroidBuilderConfig): OutputConfig<AndroidRendererOptions>;
 
-export { type AndroidBuilderConfig, type CssBuilderConfig, type IosBuilderConfig, type JsBuilderConfig, type JsonBuilderConfig, type TailwindBuilderConfig, android, css, ios, js, json, tailwind };
+export { type AndroidRendererOptions as A, type CssBuilderConfig as C, type IosRendererOptions as I, type JsBuilderConfig as J, type TailwindRendererOptions as T, js as a, android as b, css as c, type AndroidBuilderConfig as d, type IosBuilderConfig as e, type JsonBuilderConfig as f, type TailwindBuilderConfig as g, tailwindRenderer as h, ios as i, json as j, iosRenderer as k, androidRenderer as l, tailwind as t };

package/dist/{builders.d.ts → builders-BEoMaLal.d.ts}

@@ -1,10 +1,184 @@
-import { F as FileFunction, L as LifecycleHooks, C as CssRendererOptions, O as OutputConfig } from './index-Dajm5rvM.js';
+import { S as SelectorFunction, M as MediaQueryFunction, R as Renderer, F as FileFunction, L as LifecycleHooks, C as CssRendererOptions, O as OutputConfig } from './types-BxDEUCos.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';
+import { a as JsonRendererOptions, J as JsModuleRendererOptions } from './config-schemas-DnEBhIg0.js';
+
+/**
+ * @license MIT
+ * Copyright (c) 2025-present Dispersa Contributors
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * Options for Tailwind CSS v4 renderer
+ *
+ * Controls how tokens are converted to Tailwind v4 @theme CSS variables.
+ *
+ * @example Bundle with dark mode overrides
+ * ```typescript
+ * tailwind({
+ *   name: 'tailwind',
+ *   file: 'theme.css',
+ *   preset: 'bundle',
+ *   selector: (modifier, context, isBase) => {
+ *     if (isBase) return ':root'
+ *     return `[data-${modifier}="${context}"]`
+ *   },
+ * })
+ * ```
+ */
+type TailwindRendererOptions = {
+    preset?: 'bundle' | 'standalone';
+    includeImport?: boolean;
+    namespace?: string;
+    minify?: boolean;
+    selector?: string | SelectorFunction;
+    mediaQuery?: string | MediaQueryFunction;
+};
+/**
+ * Tailwind CSS v4 renderer factory function.
+ *
+ * @example
+ * ```typescript
+ * outputs: [{
+ *   name: 'tailwind',
+ *   renderer: tailwindRenderer(),
+ *   options: {
+ *     preset: 'bundle',
+ *     includeImport: true,
+ *   },
+ *   file: 'theme.css'
+ * }]
+ * ```
+ */
+declare function tailwindRenderer(): Renderer<TailwindRendererOptions>;
+
+/**
+ * @license MIT
+ * Copyright (c) 2025-present Dispersa Contributors
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * Options for iOS/SwiftUI renderer
+ */
+type IosRendererOptions = {
+    preset?: 'standalone';
+    accessLevel?: 'public' | 'internal';
+    /**
+     * Output structure:
+     * - `'enum'` — nested enums inside a single root enum
+     * - `'grouped'` — namespace enum with separate extensions per token group
+     */
+    structure?: 'enum' | 'grouped';
+    enumName?: string;
+    /** Namespace enum name used in grouped mode (default: 'DesignTokens') */
+    extensionNamespace?: string;
+    colorSpace?: 'sRGB' | 'displayP3';
+    /**
+     * Target Swift language version.
+     * - `'5.9'` (default) — standard static let declarations
+     * - `'6.0'` — adds `nonisolated(unsafe)` to static properties for
+     *   Swift 6 strict concurrency compliance
+     */
+    swiftVersion?: '5.9' | '6.0';
+    /** Number of spaces per indentation level (default 4) */
+    indent?: number;
+    /** Add @frozen annotation to enums and structs for ABI stability (default false) */
+    frozen?: boolean;
+};
+/**
+ * iOS/SwiftUI renderer factory function.
+ *
+ * @example
+ * ```typescript
+ * outputs: [{
+ *   name: 'ios',
+ *   renderer: iosRenderer(),
+ *   options: {
+ *     accessLevel: 'public',
+ *     structure: 'enum',  // or 'grouped' for extension-based layout
+ *     enumName: 'DesignTokens',
+ *     colorSpace: 'sRGB',
+ *   },
+ *   file: 'DesignTokens-{theme}.swift'
+ * }]
+ * ```
+ */
+declare function iosRenderer(): Renderer<IosRendererOptions>;
+
+/**
+ * @license MIT
+ * Copyright (c) 2025-present Dispersa Contributors
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * Options for Android/Jetpack Compose renderer
+ *
+ * Note: `packageName` is marked optional for type compatibility with the Renderer
+ * generic, but is validated as required at runtime in the renderer's format() method.
+ *
+ * @experimental This type is experimental. Properties and behavior may change.
+ */
+type AndroidRendererOptions = {
+    preset?: 'standalone' | 'bundle';
+    packageName?: string;
+    objectName?: string;
+    /**
+     * Color output format for Kotlin Color initializers.
+     * - `'argb_hex'` (default) — `Color(0xAARRGGBB)` hex literal
+     * - `'argb_float'` — `Color(r, g, b, a)` float components
+     *
+     * Legacy aliases: `'argb8'` maps to `'argb_hex'`, `'argb_floats'` maps to `'argb_float'`.
+     */
+    colorFormat?: 'argb_hex' | 'argb_float' | 'argb8' | 'argb_floats';
+    /**
+     * Color space for generated Color values.
+     * - `'sRGB'` (default) — standard sRGB color space
+     * - `'displayP3'` — Display P3 wide gamut via `ColorSpaces.DisplayP3`
+     */
+    colorSpace?: 'sRGB' | 'displayP3';
+    /**
+     * Structure mode for token organization.
+     * - `'nested'` (default) — mirror token path hierarchy as nested objects
+     * - `'flat'` — group tokens by $type into semantic sub-objects (Colors, Spacing, etc.)
+     */
+    structure?: 'nested' | 'flat';
+    /**
+     * Kotlin visibility modifier for the generated object and its members.
+     * - `undefined` (default) — no explicit modifier, which means `public` in Kotlin
+     * - `'public'` — explicit `public object` / `public val`
+     * - `'internal'` — `internal object` / `internal val` (useful for KMP / multi-module)
+     */
+    visibility?: 'public' | 'internal';
+    /** Number of spaces per indentation level (default 4) */
+    indent?: number;
+};
+/**
+ * Android/Jetpack Compose renderer factory function.
+ *
+ * @example
+ * ```typescript
+ * outputs: [{
+ *   name: 'android',
+ *   renderer: androidRenderer(),
+ *   options: {
+ *     packageName: 'com.example.tokens',
+ *     objectName: 'DesignTokens',
+ *     colorFormat: 'argb_hex',
+ *   },
+ *   file: 'DesignTokens-{theme}.kt'
+ * }]
+ * ```
+ */
+declare function androidRenderer(): Renderer<AndroidRendererOptions>;
 
 /**
  * @license
@@ -376,4 +550,4 @@ type AndroidBuilderConfig = BuilderConfigBase & AndroidRendererOptions;
  */
 declare function android(config: AndroidBuilderConfig): OutputConfig<AndroidRendererOptions>;
 
-export { type AndroidBuilderConfig, type CssBuilderConfig, type IosBuilderConfig, type JsBuilderConfig, type JsonBuilderConfig, type TailwindBuilderConfig, android, css, ios, js, json, tailwind };
+export { type AndroidRendererOptions as A, type CssBuilderConfig as C, type IosRendererOptions as I, type JsBuilderConfig as J, type TailwindRendererOptions as T, js as a, android as b, css as c, type AndroidBuilderConfig as d, type IosBuilderConfig as e, type JsonBuilderConfig as f, type TailwindBuilderConfig as g, tailwindRenderer as h, ios as i, json as j, iosRenderer as k, androidRenderer as l, tailwind as t };

package/dist/{types-8MLtztK3.d.ts → config-schemas-DnEBhIg0.d.cts}

@@ -1,4 +1,3 @@
-import { K as InternalTokenDocument } from './types-TQHV1MrY.js';
 import { FromSchema, JSONSchema } from 'json-schema-to-ts';
 
 /**
@@ -88,123 +87,6 @@ declare const preprocessorPluginSchema: {
         };
     };
 };
-/**
- * Output Configuration Schema
- *
- * Validates output-specific configuration including renderer,
- * output file path, transforms, and filters.
- */
-declare const outputConfigSchema: {
-    readonly $schema: "http://json-schema.org/draft-07/schema#";
-    readonly type: "object";
-    readonly required: readonly ["name", "renderer"];
-    readonly properties: {
-        readonly name: {
-            readonly type: "string";
-            readonly minLength: 1;
-            readonly description: "Unique identifier for this output";
-        };
-        readonly renderer: {
-            readonly $schema: "http://json-schema.org/draft-07/schema#";
-            readonly type: "object";
-            readonly required: readonly ["format"];
-            readonly properties: {
-                readonly preset: {
-                    readonly type: "string";
-                    readonly description: "Preset identifier (e.g., \"bundle\", \"standalone\", \"modifier\")";
-                };
-                readonly format: {
-                    readonly description: "Format function for token-to-output conversion (validated at runtime)";
-                };
-                readonly name: {
-                    readonly type: "string";
-                    readonly minLength: 1;
-                    readonly description: "Unique identifier for the plugin";
-                };
-            };
-            readonly additionalProperties: true;
-            readonly errorMessage: {
-                readonly required: {
-                    readonly format: "Renderer must have a \"format\" function property";
-                };
-            };
-        };
-        readonly filters: {
-            readonly type: "array";
-            readonly items: {
-                readonly $schema: "http://json-schema.org/draft-07/schema#";
-                readonly type: "object";
-                readonly required: readonly ["filter"];
-                readonly properties: {
-                    readonly filter: {
-                        readonly description: "Filter function (validated at runtime)";
-                    };
-                    readonly name: {
-                        readonly type: "string";
-                        readonly minLength: 1;
-                        readonly description: "Unique identifier for the plugin";
-                    };
-                };
-                readonly additionalProperties: true;
-                readonly errorMessage: {
-                    readonly required: {
-                        readonly filter: "Filter must have a \"filter\" function property";
-                    };
-                };
-            };
-            readonly description: "Array of filter objects to apply";
-        };
-        readonly transforms: {
-            readonly type: "array";
-            readonly items: {
-                readonly $schema: "http://json-schema.org/draft-07/schema#";
-                readonly type: "object";
-                readonly required: readonly ["transform"];
-                readonly properties: {
-                    readonly matcher: {
-                        readonly description: "Optional filter function (validated at runtime)";
-                    };
-                    readonly transform: {
-                        readonly description: "Transform function (validated at runtime)";
-                    };
-                    readonly name: {
-                        readonly type: "string";
-                        readonly minLength: 1;
-                        readonly description: "Unique identifier for the plugin";
-                    };
-                };
-                readonly additionalProperties: true;
-                readonly errorMessage: {
-                    readonly required: {
-                        readonly name: "Transform must have a \"name\" property";
-                        readonly transform: "Transform must have a \"transform\" function property";
-                    };
-                };
-            };
-            readonly description: "Array of transform objects to apply";
-        };
-        readonly file: {
-            readonly description: "Output file path relative to buildPath. Supports subdirectories (e.g., \"css/tokens.css\"), pattern strings (e.g., \"tokens-{theme}.css\"), or function for dynamic naming";
-        };
-        readonly options: {
-            readonly type: "object";
-            readonly description: "Renderer-specific options passed to the formatter";
-            readonly additionalProperties: true;
-        };
-        readonly hooks: {
-            readonly type: "object";
-            readonly description: "Per-output lifecycle hooks (functions, validated at runtime)";
-            readonly additionalProperties: true;
-        };
-    };
-    readonly errorMessage: {
-        readonly required: {
-            readonly name: "Output must have a \"name\" property";
-            readonly renderer: "Output must have a \"renderer\" property";
-        };
-    };
-    readonly additionalProperties: false;
-};
 /**
  * Dispersa Options Schema
  *
@@ -427,13 +309,6 @@ type JsonRendererOptions = FromSchema<typeof jsonRendererOptionsSchema>;
  * JS Module Renderer Options type generated from jsModuleRendererOptionsSchema
  */
 type JsModuleRendererOptions = FromSchema<typeof jsModuleRendererOptionsSchema>;
-/**
- * Output Config type generated from outputConfigSchema
- *
- * Note: This is a base type. The actual OutputConfig type in config/index.ts
- * extends this with additional TypeScript features like conditional types for options.
- */
-type OutputConfigBase = FromSchema<typeof outputConfigSchema>;
 /**
  * Dispersa Options type generated from dispersaOptionsSchema
  */
@@ -450,36 +325,4 @@ type BuildConfigBase = FromSchema<typeof buildConfigSchema>;
  */
 type PreprocessorPluginBase = FromSchema<typeof preprocessorPluginSchema>;
 
-/**
- * @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 { BuildConfigBase as B, DispersaOptionsBase as D, JsModuleRendererOptions as J, OutputConfigBase as O, Preprocessor as P, JsonRendererOptions as a };
+export type { BuildConfigBase as B, DispersaOptionsBase as D, JsModuleRendererOptions as J, PreprocessorPluginBase as P, JsonRendererOptions as a };