dispersa 0.1.1

package/dist/types-C1GpiJ6q.d.ts

@@ -0,0 +1,368 @@
+/**
+ * @fileoverview Token types - extended from schema-generated types
+ *
+ * Base token types are defined manually to match DTCG 2025.10.
+ * This keeps TypeScript types stable while runtime validation relies on
+ * the vendored DTCG JSON Schemas.
+ */
+type JsonPointerReferenceObject = {
+    $ref: string;
+};
+type TokenValueReference = string | JsonPointerReferenceObject;
+type Token = {
+    $value?: TokenValue | TokenValueReference;
+    $ref?: string;
+    $type?: TokenType;
+    $description?: string;
+    $deprecated?: boolean | string;
+    $extensions?: Record<string, unknown>;
+};
+/**
+ * Internal token shape used by the resolver pipeline
+ */
+type InternalToken = Token & {
+    /** Internal: Source modifier tag for bundle outputs (not part of DTCG spec) */
+    _sourceModifier?: string;
+};
+type TokenGroupMetadataValue = string | boolean | Record<string, unknown> | undefined;
+type TokenGroupBase = {
+    $type?: TokenType;
+    $description?: string;
+    $deprecated?: boolean | string;
+    $extensions?: Record<string, unknown>;
+    $extends?: string;
+    $root?: Token;
+};
+interface TokenGroup extends TokenGroupBase {
+    [key: string]: Token | InternalToken | TokenGroup | TokenGroupMetadataValue;
+}
+/**
+ * Token type discriminator - union of all valid token type strings
+ *
+ * Represents the possible values for the $type property in DTCG tokens.
+ */
+type TokenType = 'color' | 'dimension' | 'fontFamily' | 'fontWeight' | 'duration' | 'cubicBezier' | 'number' | 'shadow' | 'typography' | 'border' | 'strokeStyle' | 'transition' | 'gradient';
+/**
+ * Token value types - any valid value that can appear in a token
+ *
+ * Represents the possible types for the $value property in tokens.
+ * Can be primitives, objects, or arrays depending on the token type.
+ */
+type TokenValue = string | number | boolean | Record<string, unknown> | unknown[];
+/**
+ * Valid DTCG color space identifiers
+ * All 14 color spaces from DTCG Color Module 2025-10
+ */
+type ColorSpace = 'srgb' | 'srgb-linear' | 'hsl' | 'hwb' | 'lab' | 'lch' | 'oklab' | 'oklch' | 'display-p3' | 'a98-rgb' | 'prophoto-rgb' | 'rec2020' | 'xyz-d65' | 'xyz-d50';
+/**
+ * Color component value: number or the "none" keyword for missing channels
+ * Token references are handled separately via alias resolution
+ */
+type ColorComponent = number | 'none';
+/**
+ * DTCG color object format with colorSpace and components
+ * Each color space has different component meanings and ranges:
+ * - RGB-based (srgb, srgb-linear, display-p3, a98-rgb, prophoto-rgb, rec2020): [R: 0-1, G: 0-1, B: 0-1]
+ * - HSL: [H: angle, S: 0-100, L: 0-100]
+ * - HWB: [H: angle, W: 0-100, B: 0-100]
+ * - Lab/CIELab: [L: 0-100, a: -125 to 125, b: -125 to 125]
+ * - LCH: [L: 0-100, C: 0-150, H: angle]
+ * - OKLab: [L: 0-1, a: -0.4 to 0.4, b: -0.4 to 0.4]
+ * - OKLCH: [L: 0-1, C: 0-0.4, H: angle]
+ * - XYZ: [X: unbounded, Y: unbounded, Z: unbounded]
+ */
+type ColorValueObject = {
+    colorSpace: ColorSpace;
+    components: [ColorComponent, ColorComponent, ColorComponent];
+    alpha?: number;
+    hex?: string;
+};
+/**
+ * DTCG 2025-10 compliant color value
+ *
+ * Per DTCG spec, color values must be one of:
+ * 1. **Color object** with colorSpace and components (e.g., `{ colorSpace: 'srgb', components: [1, 0, 0] }`)
+ * 2. **Token reference** using `{token.path}` or JSON Pointer object (e.g., `"{color.brand.primary}"`)
+ *
+ * ⚠️ **Important**: Arbitrary CSS color strings like `"#ff0000"`, `"rgb(255, 0, 0)"`, or `"red"`
+ * are NOT valid per DTCG spec. String values MUST be alias references.
+ *
+ * @see {@link https://www.designtokens.org/tr/2025.10/color/ | DTCG Color Module}
+ * @see {@link https://www.designtokens.org/tr/2025.10/format/#color-0 | DTCG Format: Color Type}
+ *
+ * @example Valid color values
+ * ```typescript
+ * // Object format (preferred)
+ * const color1: ColorValue = {
+ *   colorSpace: 'srgb',
+ *   components: [1, 0, 0],
+ *   alpha: 1
+ * }
+ *
+ * // Alias reference (resolves to another token)
+ * const color2: ColorValue = "{color.brand.primary}"
+ * ```
+ */
+type ColorValue = ColorValueObject | TokenValueReference;
+/**
+ * DTCG 2025-10 compliant dimension value
+ *
+ * Per DTCG spec, dimension values MUST use object format with
+ * numeric value and string unit properties.
+ *
+ * ⚠️ **Important**: String values like `"16px"` are NOT valid per DTCG spec.
+ * Dimensions MUST be objects with separate value and unit properties.
+ *
+ * @see {@link https://www.designtokens.org/tr/2025.10/format/#dimension-0 | DTCG Format: Dimension Type}
+ *
+ * @example Valid dimension values
+ * ```typescript
+ * const spacing: DimensionValue = { value: 16, unit: 'px' }
+ * const fontSize: DimensionValue = { value: 1.5, unit: 'rem' }
+ * const borderWidth: DimensionValue = { value: 2, unit: 'px' }
+ * ```
+ */
+type DimensionValue = {
+    value: number;
+    unit: 'px' | 'rem';
+};
+/**
+ * Font family value - single string or array of fallback fonts
+ */
+type FontFamilyValue = string | string[];
+/**
+ * Font weight value - numeric (1-1000) or named value
+ */
+type FontWeightValue = number | string;
+/**
+ * Duration value - DTCG duration object
+ */
+type DurationValue = {
+    value: number;
+    unit: 'ms' | 's';
+};
+/**
+ * Cubic bezier value - 4-number array for animation easing
+ */
+type CubicBezierValue = [number, number, number, number];
+/**
+ * Shadow value object (DTCG 2025.10 composite type - Section 9.6)
+ *
+ * Represents a shadow effect with color, offset, blur, and optional spread.
+ * Uses proper ColorValue and DimensionValue types per DTCG spec.
+ *
+ * @example
+ * ```json
+ * {
+ *   "$type": "shadow",
+ *   "$value": {
+ *     "color": { "colorSpace": "srgb", "components": [0, 0, 0], "alpha": 0.5 },
+ *     "offsetX": { "value": 0, "unit": "px" },
+ *     "offsetY": { "value": 4, "unit": "px" },
+ *     "blur": { "value": 8, "unit": "px" },
+ *     "spread": { "value": 0, "unit": "px" }
+ *   }
+ * }
+ * ```
+ */
+type ShadowValueObject = {
+    /** Shadow color (color object or alias reference) */
+    color: ColorValue;
+    /** Horizontal offset */
+    offsetX: DimensionValue;
+    /** Vertical offset */
+    offsetY: DimensionValue;
+    /** Blur radius */
+    blur: DimensionValue;
+    /** Spread radius */
+    spread: DimensionValue;
+    /** Whether shadow is inset */
+    inset?: boolean;
+};
+/**
+ * Stroke style value object
+ */
+type StrokeStyleValueObject = {
+    dashArray: DimensionValue[];
+    lineCap: 'round' | 'butt' | 'square';
+};
+/**
+ * Stroke style value
+ */
+type StrokeStyleValue = string | StrokeStyleValueObject;
+/**
+ * Border value object
+ */
+type BorderValue = {
+    color: ColorValue;
+    width: DimensionValue;
+    style: StrokeStyleValue;
+};
+/**
+ * Typography value object
+ */
+type TypographyValue = {
+    fontFamily: FontFamilyValue;
+    fontSize: DimensionValue;
+    fontWeight: FontWeightValue;
+    letterSpacing: DimensionValue;
+    lineHeight: number;
+};
+/**
+ * Transition value object
+ */
+type TransitionValue = {
+    duration: DurationValue;
+    delay: DurationValue;
+    timingFunction: CubicBezierValue;
+};
+/**
+ * Gradient stop value object
+ */
+type GradientStop = {
+    color: ColorValue;
+    position: number;
+};
+/**
+ * Gradient value
+ */
+type GradientValue = GradientStop[];
+/**
+ * Union of all known DTCG token value types.
+ *
+ * Provides narrower typing than `TokenValue` for consumers who want
+ * better autocomplete and type checking when working with resolved tokens.
+ *
+ * Use the type guard helpers (`isColorToken`, `isDimensionToken`, etc.)
+ * to narrow a `ResolvedToken` to a specific value type.
+ *
+ * @example
+ * ```typescript
+ * import type { ResolvedToken } from 'dispersa'
+ * import { isColorToken, isDimensionToken } from 'dispersa'
+ *
+ * function process(token: ResolvedToken) {
+ *   if (isColorToken(token)) {
+ *     // token.$value is narrowed to ColorValue
+ *   }
+ *   if (isDimensionToken(token)) {
+ *     // token.$value is narrowed to DimensionValue
+ *   }
+ * }
+ * ```
+ */
+type DesignTokenValue = ColorValueObject | DimensionValue | DurationValue | CubicBezierValue | ShadowValueObject | ShadowValueObject[] | TypographyValue | BorderValue | StrokeStyleValueObject | StrokeStyleValue | TransitionValue | GradientValue | FontFamilyValue | FontWeightValue | number | boolean;
+/** Type-narrowed token whose `$value` is a `ColorValueObject` or color string */
+type ColorToken = ResolvedToken & {
+    $type: 'color';
+};
+/** Type-narrowed token whose `$value` is a `DimensionValue` */
+type DimensionToken = ResolvedToken & {
+    $type: 'dimension';
+};
+/** Type-narrowed token whose `$value` is a `ShadowValue` */
+type ShadowToken = ResolvedToken & {
+    $type: 'shadow';
+};
+/** Type-narrowed token whose `$value` is a `TypographyValue` */
+type TypographyTokenNarrowed = ResolvedToken & {
+    $type: 'typography';
+};
+/** Type-narrowed token whose `$value` is a `BorderValue` */
+type BorderTokenNarrowed = ResolvedToken & {
+    $type: 'border';
+};
+/** Type-narrowed token whose `$value` is a `DurationValue` */
+type DurationToken = ResolvedToken & {
+    $type: 'duration';
+};
+/** Type-narrowed token whose `$value` is a `TransitionValue` */
+type TransitionTokenNarrowed = ResolvedToken & {
+    $type: 'transition';
+};
+/** Type-narrowed token whose `$value` is a `GradientValue` */
+type GradientTokenNarrowed = ResolvedToken & {
+    $type: 'gradient';
+};
+/** Check if a resolved token is a color token */
+declare function isColorToken(token: ResolvedToken): token is ColorToken;
+/** Check if a resolved token is a dimension token */
+declare function isDimensionToken(token: ResolvedToken): token is DimensionToken;
+/** Check if a resolved token is a shadow token */
+declare function isShadowToken(token: ResolvedToken): token is ShadowToken;
+/** Check if a resolved token is a typography token */
+declare function isTypographyToken(token: ResolvedToken): token is TypographyTokenNarrowed;
+/** Check if a resolved token is a border token */
+declare function isBorderToken(token: ResolvedToken): token is BorderTokenNarrowed;
+/** Check if a resolved token is a duration token */
+declare function isDurationToken(token: ResolvedToken): token is DurationToken;
+/** Check if a resolved token is a transition token */
+declare function isTransitionToken(token: ResolvedToken): token is TransitionTokenNarrowed;
+/** Check if a resolved token is a gradient token */
+declare function isGradientToken(token: ResolvedToken): token is GradientTokenNarrowed;
+/**
+ * Internal token document nodes used during resolution
+ */
+type InternalTokenNode = InternalToken | TokenGroup;
+/**
+ * Internal token document structure (pre-resolution, with internal metadata)
+ */
+type InternalTokenDocument = Record<string, InternalTokenNode>;
+/**
+ * Fully resolved token with computed metadata
+ *
+ * After resolution, tokens include additional metadata like their
+ * full path in the token hierarchy and the original value before
+ * any alias or reference resolution.
+ *
+ * @example
+ * ```typescript
+ * {
+ *   $value: "#ff0000",
+ *   $type: "color",
+ *   path: ["color", "brand", "primary"],
+ *   name: "color.brand.primary",
+ *   originalValue: "{color.red.500}" // Before alias resolution
+ * }
+ * ```
+ */
+type ResolvedToken = Token & {
+    /** Hierarchical path segments (e.g., ['color', 'brand', 'primary']) */
+    path: string[];
+    /** Fully qualified token name (e.g., 'color.brand.primary') */
+    name: string;
+    /**
+     * The raw value before any alias or reference resolution.
+     *
+     * For alias tokens this contains the alias reference string
+     * (e.g., `"{color.primary}"`) or a composite value with embedded
+     * alias references. For non-alias tokens this equals `$value`.
+     *
+     * Use the built-in `isAlias()` / `isBase()` filters or inspect
+     * this value with `getPureAliasReferenceName()` to determine
+     * whether the token was originally an alias.
+     */
+    originalValue: TokenValue;
+};
+/**
+ * Collection of resolved tokens indexed by name
+ *
+ * Maps token names to their resolved definitions. This is the primary
+ * format used throughout Dispersa after token resolution.
+ *
+ * @example
+ * ```typescript
+ * {
+ *   "color.brand.primary": {
+ *     $value: "#ff0000",
+ *     $type: "color",
+ *     path: ["color", "brand", "primary"],
+ *     name: "color.brand.primary",
+ *     originalValue: "#ff0000"
+ *   }
+ * }
+ * ```
+ */
+type ResolvedTokens = Record<string, ResolvedToken>;
+
+export { type BorderValue as B, type ColorToken as C, type DesignTokenValue as D, type GradientValue as G, type InternalTokenDocument as I, type ResolvedTokens as R, type ShadowToken as S, type TokenType as T, type ResolvedToken as a, type DimensionToken as b, type DurationToken as c, type ColorValueObject as d, type DimensionValue as e, type ShadowValueObject as f, type TypographyValue as g, type TransitionValue as h, isColorToken as i, isDimensionToken as j, isShadowToken as k, isTypographyToken as l, isBorderToken as m, isDurationToken as n, isTransitionToken as o, isGradientToken as p };

package/dist/types-Cl-1UYGD.d.ts

@@ -0,0 +1,30 @@
+import { a as ResolvedToken } from './types-C1GpiJ6q.js';
+
+/**
+ * @fileoverview Filter system types for token selection
+ */
+
+/**
+ * Filter definition for selecting tokens
+ *
+ * Filters determine which tokens should be included in output configuration.
+ * They are applied before transforms.
+ *
+ * @example
+ * ```typescript
+ * const colorsOnly: Filter = {
+ *   filter: (token) => token.$type === 'color'
+ * }
+ * ```
+ */
+type Filter = {
+    /**
+     * Function that determines if a token should be included
+     *
+     * @param token - Token to test
+     * @returns true if token should be included in output, false otherwise
+     */
+    filter: (token: ResolvedToken) => boolean;
+};
+
+export type { Filter as F };