@nikkory/vibe-engine 4.0.0

package/dist/tokens/schema.d.ts

@@ -0,0 +1,486 @@
+/**
+ * Design Token Schema
+ *
+ * Defines the complete structure for design system tokens.
+ * This schema is the foundation of the Dynamic Matrix architecture,
+ * enabling infinite design system variations from a single token configuration.
+ *
+ * @packageDocumentation
+ * @module tokens/schema
+ * @since 2.0.0
+ *
+ * Powered by Nikkory
+ */
+/**
+ * Color scale with 10 shades from lightest (50) to darkest (900/950)
+ *
+ * @example
+ * ```typescript
+ * const primaryColor: ColorScale = {
+ *   50: '#F3E5F5',
+ *   100: '#E1BEE7',
+ *   // ...
+ *   500: '#6750A4', // Primary shade
+ *   // ...
+ *   900: '#4527A0',
+ * };
+ * ```
+ */
+export interface ColorScale {
+    readonly 50: string;
+    readonly 100: string;
+    readonly 200: string;
+    readonly 300: string;
+    readonly 400: string;
+    readonly 500: string;
+    readonly 600: string;
+    readonly 700: string;
+    readonly 800: string;
+    readonly 900: string;
+    readonly 950?: string;
+}
+/**
+ * Semantic color palette for consistent meaning across the application
+ */
+export interface SemanticColors {
+    /** Primary brand color */
+    readonly primary: ColorScale;
+    /** Secondary brand color */
+    readonly secondary: ColorScale;
+    /** Accent color for highlights */
+    readonly accent: ColorScale;
+    /** Neutral gray tones */
+    readonly neutral: ColorScale;
+    /** Success/positive states */
+    readonly success: ColorScale;
+    /** Warning states */
+    readonly warning: ColorScale;
+    /** Error/destructive states */
+    readonly error: ColorScale;
+    /** Informational states */
+    readonly info: ColorScale;
+}
+/**
+ * Surface colors for backgrounds, text, and borders
+ */
+export interface SurfaceColors {
+    /** Background color variants */
+    readonly background: {
+        readonly default: string;
+        readonly paper: string;
+        readonly elevated: string;
+        readonly overlay: string;
+    };
+    /** Foreground/text color variants */
+    readonly foreground: {
+        readonly default: string;
+        readonly muted: string;
+        readonly subtle: string;
+        readonly disabled: string;
+        readonly inverse: string;
+    };
+    /** Border color variants */
+    readonly border: {
+        readonly default: string;
+        readonly muted: string;
+        readonly strong: string;
+    };
+}
+/**
+ * Complete color token structure
+ */
+export interface ColorTokens {
+    readonly semantic: SemanticColors;
+    readonly surface: SurfaceColors;
+}
+/**
+ * Spacing scale following Tailwind-like conventions
+ * Keys are numeric multipliers (1 = 0.25rem = 4px)
+ */
+export interface SpacingScale {
+    readonly 0: string;
+    readonly px: string;
+    readonly 0.5: string;
+    readonly 1: string;
+    readonly 1.5: string;
+    readonly 2: string;
+    readonly 2.5: string;
+    readonly 3: string;
+    readonly 3.5: string;
+    readonly 4: string;
+    readonly 5: string;
+    readonly 6: string;
+    readonly 7: string;
+    readonly 8: string;
+    readonly 9: string;
+    readonly 10: string;
+    readonly 11: string;
+    readonly 12: string;
+    readonly 14: string;
+    readonly 16: string;
+    readonly 20: string;
+    readonly 24: string;
+    readonly 28: string;
+    readonly 32: string;
+    readonly 36: string;
+    readonly 40: string;
+    readonly 44: string;
+    readonly 48: string;
+    readonly 52: string;
+    readonly 56: string;
+    readonly 60: string;
+    readonly 64: string;
+    readonly 72: string;
+    readonly 80: string;
+    readonly 96: string;
+}
+/**
+ * Component size tokens (xs to 3xl)
+ */
+export interface SizeTokens {
+    readonly xs: string;
+    readonly sm: string;
+    readonly md: string;
+    readonly lg: string;
+    readonly xl: string;
+    readonly '2xl'?: string;
+    readonly '3xl'?: string;
+}
+/**
+ * Font family definitions
+ */
+export interface FontFamilyTokens {
+    /** Sans-serif font stack */
+    readonly sans: string;
+    /** Serif font stack */
+    readonly serif: string;
+    /** Monospace font stack */
+    readonly mono: string;
+    /** Display/heading font (optional) */
+    readonly display?: string;
+    /** Handwriting/script font (optional) */
+    readonly handwriting?: string;
+}
+/**
+ * Font size scale
+ */
+export interface FontSizeTokens {
+    readonly xs: string;
+    readonly sm: string;
+    readonly base: string;
+    readonly lg: string;
+    readonly xl: string;
+    readonly '2xl': string;
+    readonly '3xl': string;
+    readonly '4xl': string;
+    readonly '5xl': string;
+    readonly '6xl': string;
+    readonly '7xl': string;
+    readonly '8xl': string;
+    readonly '9xl': string;
+}
+/**
+ * Font weight scale (100-900)
+ */
+export interface FontWeightTokens {
+    readonly thin: number;
+    readonly extralight: number;
+    readonly light: number;
+    readonly normal: number;
+    readonly medium: number;
+    readonly semibold: number;
+    readonly bold: number;
+    readonly extrabold: number;
+    readonly black: number;
+}
+/**
+ * Line height scale
+ */
+export interface LineHeightTokens {
+    readonly none: number;
+    readonly tight: number;
+    readonly snug: number;
+    readonly normal: number;
+    readonly relaxed: number;
+    readonly loose: number;
+}
+/**
+ * Letter spacing scale
+ */
+export interface LetterSpacingTokens {
+    readonly tighter: string;
+    readonly tight: string;
+    readonly normal: string;
+    readonly wide: string;
+    readonly wider: string;
+    readonly widest: string;
+}
+/**
+ * Complete typography token structure
+ */
+export interface TypographyTokens {
+    readonly fontFamily: FontFamilyTokens;
+    readonly fontSize: FontSizeTokens;
+    readonly fontWeight: FontWeightTokens;
+    readonly lineHeight: LineHeightTokens;
+    readonly letterSpacing: LetterSpacingTokens;
+}
+/**
+ * Border radius scale
+ */
+export interface BorderRadiusTokens {
+    readonly none: string;
+    readonly sm: string;
+    readonly base: string;
+    readonly md: string;
+    readonly lg: string;
+    readonly xl: string;
+    readonly '2xl': string;
+    readonly '3xl': string;
+    readonly full: string;
+}
+/**
+ * Border width scale
+ */
+export interface BorderWidthTokens {
+    readonly 0: string;
+    readonly 1: string;
+    readonly 2: string;
+    readonly 4: string;
+    readonly 8: string;
+}
+/**
+ * Border style type
+ */
+export type BorderStyle = 'solid' | 'dashed' | 'dotted' | 'double' | 'none';
+/**
+ * Complete border token structure
+ */
+export interface BorderTokens {
+    readonly radius: BorderRadiusTokens;
+    readonly width: BorderWidthTokens;
+    readonly style: BorderStyle;
+}
+/**
+ * Shadow token scale with design-system-specific variants
+ */
+export interface ShadowTokens {
+    readonly none: string;
+    readonly sm: string;
+    readonly base: string;
+    readonly md: string;
+    readonly lg: string;
+    readonly xl: string;
+    readonly '2xl': string;
+    readonly inner: string;
+    /** Glow effect shadow (Cyberpunk) */
+    readonly glow?: string;
+    /** Sharp offset shadow (Brutalism) */
+    readonly sharp?: string;
+    /** Soft outer shadow (Neumorphism) */
+    readonly soft?: string;
+    /** Soft inset shadow for pressed state (Neumorphism) */
+    readonly softInset?: string;
+}
+/**
+ * Animation duration scale
+ */
+export interface DurationTokens {
+    readonly 0: string;
+    readonly 75: string;
+    readonly 100: string;
+    readonly 150: string;
+    readonly 200: string;
+    readonly 300: string;
+    readonly 500: string;
+    readonly 700: string;
+    readonly 1000: string;
+}
+/**
+ * Animation easing functions
+ */
+export interface EasingTokens {
+    readonly linear: string;
+    readonly in: string;
+    readonly out: string;
+    readonly inOut: string;
+    readonly bounce?: string;
+    readonly elastic?: string;
+}
+/**
+ * Complete animation token structure
+ */
+export interface AnimationTokens {
+    readonly duration: DurationTokens;
+    readonly easing: EasingTokens;
+    /** Whether to respect prefers-reduced-motion */
+    readonly respectMotionPreference: boolean;
+}
+/**
+ * Blur effect scale
+ */
+export interface BlurTokens {
+    readonly none: string;
+    readonly sm: string;
+    readonly base: string;
+    readonly md: string;
+    readonly lg: string;
+    readonly xl: string;
+    readonly '2xl': string;
+    readonly '3xl': string;
+}
+/**
+ * Opacity scale (0-100)
+ */
+export interface OpacityTokens {
+    readonly 0: number;
+    readonly 5: number;
+    readonly 10: number;
+    readonly 20: number;
+    readonly 25: number;
+    readonly 30: number;
+    readonly 40: number;
+    readonly 50: number;
+    readonly 60: number;
+    readonly 70: number;
+    readonly 75: number;
+    readonly 80: number;
+    readonly 90: number;
+    readonly 95: number;
+    readonly 100: number;
+}
+/**
+ * Backdrop filter settings (for glassmorphism)
+ */
+export interface BackdropTokens {
+    readonly blur: string;
+    readonly saturate: string;
+    readonly brightness: string;
+}
+/**
+ * Gradient definitions
+ */
+export interface GradientTokens {
+    readonly primary: string;
+    readonly secondary: string;
+    readonly accent: string;
+}
+/**
+ * Complete effect token structure
+ */
+export interface EffectTokens {
+    readonly blur: BlurTokens;
+    readonly opacity: OpacityTokens;
+    readonly backdrop?: BackdropTokens;
+    readonly gradient?: GradientTokens;
+}
+/**
+ * Z-index scale for layering
+ */
+export interface ZIndexTokens {
+    readonly auto: string;
+    readonly 0: number;
+    readonly 10: number;
+    readonly 20: number;
+    readonly 30: number;
+    readonly 40: number;
+    readonly 50: number;
+    readonly dropdown: number;
+    readonly sticky: number;
+    readonly fixed: number;
+    readonly modalBackdrop: number;
+    readonly modal: number;
+    readonly popover: number;
+    readonly tooltip: number;
+    readonly toast: number;
+}
+/**
+ * Component-specific token overrides
+ */
+export interface ComponentTokens {
+    readonly background?: string;
+    readonly border?: string;
+    readonly shadow?: string;
+    readonly textColor?: string;
+    readonly padding?: Record<string, string>;
+    readonly borderRadius?: string;
+    readonly transition?: string;
+    readonly hover?: Partial<ComponentTokens>;
+    readonly active?: Partial<ComponentTokens>;
+    readonly disabled?: Partial<ComponentTokens>;
+    readonly focus?: Partial<ComponentTokens>;
+}
+/**
+ * Complete Design Token Structure
+ *
+ * This interface defines all tokens for a design system.
+ * Each design system (Material, iOS, Glassmorphism, etc.) implements this interface.
+ *
+ * @example
+ * ```typescript
+ * const myTokens: DesignTokens = {
+ *   id: 'my-brand',
+ *   name: 'My Brand Design System',
+ *   version: '1.0.0',
+ *   description: 'Custom design system for My Brand',
+ *   colors: { ... },
+ *   spacing: { ... },
+ *   // ... all other tokens
+ * };
+ * ```
+ */
+export interface DesignTokens {
+    /** Unique identifier for this design system */
+    readonly id: string;
+    /** Human-readable display name */
+    readonly name: string;
+    /** Semantic version */
+    readonly version: string;
+    /** Description of the design system */
+    readonly description: string;
+    /** Color tokens */
+    readonly colors: ColorTokens;
+    /** Spacing scale */
+    readonly spacing: SpacingScale;
+    /** Component sizing */
+    readonly sizes: SizeTokens;
+    /** Typography tokens */
+    readonly typography: TypographyTokens;
+    /** Border tokens */
+    readonly borders: BorderTokens;
+    /** Shadow tokens */
+    readonly shadows: ShadowTokens;
+    /** Animation tokens */
+    readonly animations: AnimationTokens;
+    /** Effect tokens */
+    readonly effects: EffectTokens;
+    /** Z-index tokens */
+    readonly zIndex: ZIndexTokens;
+    /** Component-specific overrides (optional) */
+    readonly components?: Record<string, Partial<ComponentTokens>>;
+}
+/**
+ * Type guard to check if a value is a valid ColorScale
+ *
+ * @param value - Value to check
+ * @returns True if value is a valid ColorScale
+ */
+export declare function isColorScale(value: unknown): value is ColorScale;
+/**
+ * Type guard to check if a value is a valid DesignTokens object
+ *
+ * @param value - Value to check
+ * @returns True if value is a valid DesignTokens object
+ */
+export declare function isDesignTokens(value: unknown): value is DesignTokens;
+/**
+ * Deep partial type for token overrides
+ */
+export type DeepPartial<T> = {
+    [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
+/**
+ * Partial design tokens for overrides
+ */
+export type PartialDesignTokens = DeepPartial<DesignTokens>;
+//# sourceMappingURL=schema.d.ts.map

package/dist/types/Option.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Option Type - Null Safety
+ *
+ * Represents a value that may or may not exist.
+ * Eliminates null/undefined errors at compile time.
+ *
+ * @example
+ * ```ts
+ * function findUser(id: string): Option<User> {
+ *   const user = database.find(id);
+ *   return Option.of(user);
+ * }
+ *
+ * const userOption = findUser('123');
+ * const userName = userOption
+ *   .map(user => user.name)
+ *   .getOrElse('Anonymous');
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export declare class Option<T> {
+    private readonly value?;
+    private constructor();
+    /**
+     * Create Option from value
+     * Returns Some if value exists, None if null/undefined
+     *
+     * @param value - Value to wrap
+     * @returns Option containing the value or None
+     */
+    static of<T>(value?: T | null): Option<T>;
+    /**
+     * Create Some (value exists)
+     *
+     * @param value - The value
+     * @returns Option containing the value
+     */
+    static some<T>(value: T): Option<T>;
+    /**
+     * Create None (no value)
+     *
+     * @returns Empty Option
+     */
+    static none<T>(): Option<T>;
+    /**
+     * Check if value exists (Some)
+     */
+    isSome(): boolean;
+    /**
+     * Check if value doesn't exist (None)
+     */
+    isNone(): boolean;
+    /**
+     * Get the value (throws if None)
+     *
+     * @throws {Error} If Option is None
+     */
+    get(): T;
+    /**
+     * Get value or default
+     *
+     * @param defaultValue - Value to return if None
+     */
+    getOrElse(defaultValue: T): T;
+    /**
+     * Get value or compute default
+     *
+     * @param fn - Function to compute default value
+     */
+    getOrElseCompute(fn: () => T): T;
+    /**
+     * Get value or throw custom error
+     *
+     * @param error - Error to throw if None
+     * @throws {E} If Option is None
+     */
+    getOrThrow<E extends Error>(error: E): T;
+    /**
+     * Get value or null
+     */
+    getOrNull(): T | null;
+    /**
+     * Get value or undefined
+     */
+    getOrUndefined(): T | undefined;
+    /**
+     * Map value if exists
+     *
+     * @param fn - Mapping function
+     * @returns New Option with mapped value or None
+     */
+    map<U>(fn: (value: T) => U): Option<U>;
+    /**
+     * Flat map (chain) operations
+     *
+     * @param fn - Function returning an Option
+     * @returns Flattened Option
+     */
+    flatMap<U>(fn: (value: T) => Option<U>): Option<U>;
+    /**
+     * Filter by predicate
+     *
+     * @param predicate - Test function
+     * @returns This Option if predicate passes, None otherwise
+     */
+    filter(predicate: (value: T) => boolean): Option<T>;
+    /**
+     * Execute callback if Some
+     *
+     * @param fn - Callback function
+     * @returns This Option for chaining
+     */
+    onSome(fn: (value: T) => void): Option<T>;
+    /**
+     * Execute callback if None
+     *
+     * @param fn - Callback function
+     * @returns This Option for chaining
+     */
+    onNone(fn: () => void): Option<T>;
+    /**
+     * Match pattern for Option
+     *
+     * @param patterns - Some and None handlers
+     * @returns Result of the matched pattern
+     */
+    match<U>(patterns: {
+        some: (value: T) => U;
+        none: () => U;
+    }): U;
+    /**
+     * Provide alternative Option if None
+     *
+     * @param alternative - Alternative Option
+     * @returns This Option if Some, alternative if None
+     */
+    or(alternative: Option<T>): Option<T>;
+    /**
+     * Provide alternative Option computed lazily
+     *
+     * @param fn - Function returning alternative Option
+     * @returns This Option if Some, computed alternative if None
+     */
+    orElse(fn: () => Option<T>): Option<T>;
+    /**
+     * Zip two Options together
+     *
+     * @param other - Other Option
+     * @returns Option containing tuple of both values or None
+     */
+    zip<U>(other: Option<U>): Option<[T, U]>;
+    /**
+     * Convert Option to array
+     *
+     * @returns Array with value if Some, empty array if None
+     */
+    toArray(): T[];
+    /**
+     * Convert Option to JSON
+     */
+    toJSON(): object;
+    /**
+     * Try to execute a function and wrap result
+     *
+     * @param fn - Function to execute
+     * @returns Option containing result or None if error
+     */
+    static try<T>(fn: () => T): Option<T>;
+    /**
+     * Combine multiple Options
+     *
+     * @param options - Array of Options
+     * @returns Option containing array of values or None if any is None
+     */
+    static combine<T>(options: Option<T>[]): Option<T[]>;
+}
+//# sourceMappingURL=Option.d.ts.map