@nikkory/vibe-engine 4.0.0

package/dist/styling/factor-migration.d.ts

@@ -0,0 +1,192 @@
+/**
+ * Factor Migration Utility
+ *
+ * Utility for migrating components from 16-Factor to 24-Factor system.
+ * Provides tools for detecting, validating, and updating factor configurations.
+ *
+ * @packageDocumentation
+ * @module generator/factor-migration
+ * @since 2.1.0
+ *
+ * Powered by Nikkory
+ */
+import { type Factors17to24Config } from './factors-17-24';
+import type { FactorSpacing, FactorTypography, FactorBorder, FactorOpacity, FactorOverflow, FactorCursor, FactorZIndex, FactorTransition } from './types';
+/**
+ * 16-Factor configuration interface (legacy).
+ * @since 2.1.0
+ */
+export interface Factor16Config {
+    size?: string;
+    variant?: string;
+    colorScheme?: string;
+    shape?: string;
+    position?: string;
+    iconPosition?: string;
+    state?: string;
+    animation?: string;
+    elevation?: string;
+    a11y?: string;
+    justify?: string;
+    align?: string;
+    orientation?: string;
+    density?: string;
+    loadingState?: string;
+    theme?: string;
+}
+/**
+ * 24-Factor configuration interface (current).
+ * @since 2.1.0
+ */
+export interface Factor24Config extends Factor16Config {
+    spacing?: FactorSpacing;
+    typography?: FactorTypography;
+    border?: FactorBorder;
+    opacity?: FactorOpacity;
+    overflow?: FactorOverflow;
+    cursor?: FactorCursor;
+    zIndex?: FactorZIndex;
+    transition?: FactorTransition;
+}
+/**
+ * Migration result interface.
+ * @since 2.1.0
+ */
+export interface MigrationResult {
+    /** Whether migration was successful */
+    success: boolean;
+    /** Original 16-Factor config */
+    original: Factor16Config;
+    /** Migrated 24-Factor config */
+    migrated: Factor24Config;
+    /** Factors that were added with defaults */
+    addedFactors: Array<keyof Factors17to24Config>;
+    /** Any warnings during migration */
+    warnings: string[];
+}
+/**
+ * Migration options interface.
+ * @since 2.1.0
+ */
+export interface MigrationOptions {
+    /** Whether to apply defaults for missing Factor 17-24 */
+    applyDefaults?: boolean;
+    /** Custom defaults to use instead of FACTOR_17_24_DEFAULTS */
+    customDefaults?: Partial<Factors17to24Config>;
+    /** Whether to validate the result */
+    validate?: boolean;
+    /** Component type for context-aware defaults */
+    componentType?: string;
+}
+/**
+ * Component-specific default overrides for Factor 17-24.
+ * @since 2.1.0
+ */
+export declare const COMPONENT_DEFAULTS: Record<string, Partial<Factors17to24Config>>;
+/**
+ * Detect if a config is using 16-Factor (legacy) format.
+ *
+ * @param config - Configuration to check
+ * @returns True if config is 16-Factor format
+ *
+ * @example
+ * ```typescript
+ * const is16Factor = is16FactorConfig({ size: 'md', variant: 'filled' });
+ * // => true (no Factor 17-24 present)
+ * ```
+ *
+ * @since 2.1.0
+ */
+export declare function is16FactorConfig(config: Factor16Config | Factor24Config): boolean;
+/**
+ * Detect if a config is using 24-Factor (current) format.
+ *
+ * @param config - Configuration to check
+ * @returns True if config has any Factor 17-24 present
+ *
+ * @since 2.1.0
+ */
+export declare function is24FactorConfig(config: Factor16Config | Factor24Config): boolean;
+/**
+ * Get missing Factor 17-24 keys from a config.
+ *
+ * @param config - Configuration to check
+ * @returns Array of missing Factor 17-24 keys
+ *
+ * @since 2.1.0
+ */
+export declare function getMissingFactor17to24(config: Partial<Factor24Config>): Array<keyof Factors17to24Config>;
+/**
+ * Migrate a 16-Factor config to 24-Factor config.
+ *
+ * @param config - 16-Factor configuration to migrate
+ * @param options - Migration options
+ * @returns Migration result with migrated config
+ *
+ * @example
+ * ```typescript
+ * const result = migrate16to24(
+ *   { size: 'md', variant: 'filled' },
+ *   { applyDefaults: true, componentType: 'button' }
+ * );
+ * // Result includes migrated config with Factor 17-24 defaults
+ * ```
+ *
+ * @since 2.1.0
+ */
+export declare function migrate16to24(config: Factor16Config, options?: MigrationOptions): MigrationResult;
+/**
+ * Batch migrate multiple 16-Factor configs to 24-Factor.
+ *
+ * @param configs - Array of 16-Factor configurations
+ * @param options - Migration options
+ * @returns Array of migration results
+ *
+ * @since 2.1.0
+ */
+export declare function batchMigrate16to24(configs: Factor16Config[], options?: MigrationOptions): MigrationResult[];
+/**
+ * Validate a Factor 24 config completeness.
+ *
+ * @param config - Configuration to validate
+ * @returns Validation result with missing factors
+ *
+ * @since 2.1.0
+ */
+export declare function validateFactor24Completeness(config: Partial<Factor24Config>): {
+    isComplete: boolean;
+    missingFactors: string[];
+    completeness: number;
+};
+/**
+ * Create a complete Factor 24 config from a partial config.
+ *
+ * @param partial - Partial configuration
+ * @param componentType - Component type for context-aware defaults
+ * @returns Complete Factor 24 config with all factors defined
+ *
+ * @since 2.1.0
+ */
+export declare function completeFactorConfig(partial: Partial<Factor24Config>, componentType?: string): Factor24Config;
+/**
+ * Generate a migration report for a batch of configs.
+ *
+ * @param results - Array of migration results
+ * @returns Formatted report string
+ *
+ * @since 2.1.0
+ */
+export declare function generateMigrationReport(results: MigrationResult[]): string;
+export declare const FactorMigration: {
+    is16FactorConfig: typeof is16FactorConfig;
+    is24FactorConfig: typeof is24FactorConfig;
+    getMissingFactor17to24: typeof getMissingFactor17to24;
+    migrate16to24: typeof migrate16to24;
+    batchMigrate16to24: typeof batchMigrate16to24;
+    validateFactor24Completeness: typeof validateFactor24Completeness;
+    completeFactorConfig: typeof completeFactorConfig;
+    generateMigrationReport: typeof generateMigrationReport;
+    COMPONENT_DEFAULTS: Record<string, Partial<Factors17to24Config>>;
+};
+export default FactorMigration;
+//# sourceMappingURL=factor-migration.d.ts.map

package/dist/styling/factor-validators.d.ts

@@ -0,0 +1,327 @@
+/**
+ * 24-Factor Validation System
+ *
+ * Runtime type guards and validators for all 24 customization factors.
+ * These utilities ensure type safety and provide helpful error messages.
+ *
+ * @packageDocumentation
+ * @module generator/factor-validators
+ * @since 2.0.0
+ * @updated 2.1.0 - Extended to 24 factors
+ *
+ * Powered by Nikkory
+ */
+import type { FactorShape, FactorPosition, FactorIconPosition, FactorState, FactorAnimation, FactorElevation, FactorA11y, FactorAlignment, FactorOrientation, FactorDensity, FactorLoadingState, FactorResponsiveBreakpoint, FactorResponsiveConfig, FactorTheme, ColorScheme, ComponentSize, FactorSpacing, FactorTypography, FactorBorder, FactorOpacity, FactorOverflow, FactorCursor, FactorZIndex, FactorTransition } from './types';
+/** Valid color scheme values */
+export declare const VALID_COLOR_SCHEMES: readonly ColorScheme[];
+/** Valid component size values */
+export declare const VALID_SIZES: readonly ComponentSize[];
+/** Valid shape values (Factor 4) */
+export declare const VALID_SHAPES: readonly FactorShape[];
+/** Valid position values (Factor 5) */
+export declare const VALID_POSITIONS: readonly FactorPosition[];
+/** Valid icon position values (Factor 6) */
+export declare const VALID_ICON_POSITIONS: readonly FactorIconPosition[];
+/** Valid state values (Factor 7) */
+export declare const VALID_STATES: readonly FactorState[];
+/** Valid animation values (Factor 8) */
+export declare const VALID_ANIMATIONS: readonly FactorAnimation[];
+/** Valid elevation values (Factor 9) */
+export declare const VALID_ELEVATIONS: readonly FactorElevation[];
+/** Valid a11y level values (Factor 10) */
+export declare const VALID_A11Y_LEVELS: readonly FactorA11y[];
+/** Valid alignment values (Factor 11) */
+export declare const VALID_ALIGNMENTS: readonly FactorAlignment[];
+/** Valid orientation values (Factor 12) */
+export declare const VALID_ORIENTATIONS: readonly FactorOrientation[];
+/** Valid density values (Factor 13) */
+export declare const VALID_DENSITIES: readonly FactorDensity[];
+/** Valid loading state values (Factor 14) */
+export declare const VALID_LOADING_STATES: readonly FactorLoadingState[];
+/** Valid responsive breakpoint values (Factor 15) */
+export declare const VALID_BREAKPOINTS: readonly FactorResponsiveBreakpoint[];
+/** Valid theme values (Factor 16) */
+export declare const VALID_THEMES: readonly FactorTheme[];
+/** Valid spacing values (Factor 17) */
+export declare const VALID_SPACINGS: readonly FactorSpacing[];
+/** Valid typography values (Factor 18) */
+export declare const VALID_TYPOGRAPHIES: readonly FactorTypography[];
+/** Valid border values (Factor 19) */
+export declare const VALID_BORDERS: readonly FactorBorder[];
+/** Valid opacity values (Factor 20) */
+export declare const VALID_OPACITIES: readonly FactorOpacity[];
+/** Valid overflow values (Factor 21) */
+export declare const VALID_OVERFLOWS: readonly FactorOverflow[];
+/** Valid cursor values (Factor 22) */
+export declare const VALID_CURSORS: readonly FactorCursor[];
+/** Valid z-index values (Factor 23) */
+export declare const VALID_Z_INDICES: readonly FactorZIndex[];
+/** Valid transition values (Factor 24) */
+export declare const VALID_TRANSITIONS: readonly FactorTransition[];
+/**
+ * Check if value is a valid color scheme.
+ * @since 2.0.0
+ */
+export declare function isValidColorScheme(value: unknown): value is ColorScheme;
+/**
+ * Check if value is a valid component size.
+ * @since 2.0.0
+ */
+export declare function isValidSize(value: unknown): value is ComponentSize;
+/**
+ * Check if value is a valid shape (Factor 4).
+ * @since 2.0.0
+ */
+export declare function isValidShape(value: unknown): value is FactorShape;
+/**
+ * Check if value is a valid position (Factor 5).
+ * @since 2.0.0
+ */
+export declare function isValidPosition(value: unknown): value is FactorPosition;
+/**
+ * Check if value is a valid icon position (Factor 6).
+ * @since 2.0.0
+ */
+export declare function isValidIconPosition(value: unknown): value is FactorIconPosition;
+/**
+ * Check if value is a valid state (Factor 7).
+ * @since 2.0.0
+ */
+export declare function isValidState(value: unknown): value is FactorState;
+/**
+ * Check if value is a valid animation (Factor 8).
+ * @since 2.0.0
+ */
+export declare function isValidAnimation(value: unknown): value is FactorAnimation;
+/**
+ * Check if value is a valid elevation (Factor 9).
+ * @since 2.0.0
+ */
+export declare function isValidElevation(value: unknown): value is FactorElevation;
+/**
+ * Check if value is a valid a11y level (Factor 10).
+ * @since 2.0.0
+ */
+export declare function isValidA11yLevel(value: unknown): value is FactorA11y;
+/**
+ * Check if value is a valid alignment (Factor 11).
+ * @since 2.0.0
+ */
+export declare function isValidAlignment(value: unknown): value is FactorAlignment;
+/**
+ * Check if value is a valid orientation (Factor 12).
+ * @since 2.0.0
+ */
+export declare function isValidOrientation(value: unknown): value is FactorOrientation;
+/**
+ * Check if value is a valid density (Factor 13).
+ * @since 2.0.0
+ */
+export declare function isValidDensity(value: unknown): value is FactorDensity;
+/**
+ * Check if value is a valid loading state (Factor 14).
+ * @since 2.0.0
+ */
+export declare function isValidLoadingState(value: unknown): value is FactorLoadingState;
+/**
+ * Check if value is a valid responsive breakpoint (Factor 15).
+ * @since 2.0.0
+ */
+export declare function isValidBreakpoint(value: unknown): value is FactorResponsiveBreakpoint;
+/**
+ * Check if value is a valid responsive config (Factor 15).
+ * @since 2.0.0
+ */
+export declare function isValidResponsiveConfig(value: unknown): value is FactorResponsiveConfig;
+/**
+ * Check if value is a valid theme (Factor 16).
+ * @since 2.0.0
+ */
+export declare function isValidTheme(value: unknown): value is FactorTheme;
+/**
+ * Check if value is a valid spacing (Factor 17).
+ * @since 2.1.0
+ */
+export declare function isValidSpacing(value: unknown): value is FactorSpacing;
+/**
+ * Check if value is a valid typography (Factor 18).
+ * @since 2.1.0
+ */
+export declare function isValidTypography(value: unknown): value is FactorTypography;
+/**
+ * Check if value is a valid border (Factor 19).
+ * @since 2.1.0
+ */
+export declare function isValidBorder(value: unknown): value is FactorBorder;
+/**
+ * Check if value is a valid opacity (Factor 20).
+ * @since 2.1.0
+ */
+export declare function isValidOpacity(value: unknown): value is FactorOpacity;
+/**
+ * Check if value is a valid overflow (Factor 21).
+ * @since 2.1.0
+ */
+export declare function isValidOverflow(value: unknown): value is FactorOverflow;
+/**
+ * Check if value is a valid cursor (Factor 22).
+ * @since 2.1.0
+ */
+export declare function isValidCursor(value: unknown): value is FactorCursor;
+/**
+ * Check if value is a valid z-index (Factor 23).
+ * @since 2.1.0
+ */
+export declare function isValidZIndex(value: unknown): value is FactorZIndex;
+/**
+ * Check if value is a valid transition (Factor 24).
+ * @since 2.1.0
+ */
+export declare function isValidTransition(value: unknown): value is FactorTransition;
+/**
+ * Validation result interface.
+ * @since 2.0.0
+ */
+export interface FactorValidationResult {
+    /** Whether the value is valid */
+    valid: boolean;
+    /** Factor name */
+    factor: string;
+    /** The value that was validated */
+    value: unknown;
+    /** Error message if invalid */
+    error?: string;
+    /** Suggested valid values */
+    suggestions?: readonly string[];
+}
+/**
+ * Validate a factor value and return detailed result.
+ *
+ * @param factor - Factor name (1-24)
+ * @param value - Value to validate
+ * @returns Validation result with error details if invalid
+ *
+ * @example
+ * ```typescript
+ * const result = validateFactor('shape', 'invalid');
+ * // { valid: false, factor: 'shape', value: 'invalid',
+ * //   error: 'Invalid shape value', suggestions: ['none', 'sm', ...] }
+ *
+ * const result2 = validateFactor('spacing', 'lg');
+ * // { valid: true, factor: 'spacing', value: 'lg' }
+ * ```
+ *
+ * @since 2.0.0
+ * @updated 2.1.0 - Extended to 24 factors
+ */
+export declare function validateFactor(factor: string, value: unknown): FactorValidationResult;
+/**
+ * Validate multiple factors at once.
+ *
+ * @param config - Object with factor name keys and values to validate
+ * @returns Array of validation results (only invalid ones)
+ *
+ * @example
+ * ```typescript
+ * const errors = validateFactors({
+ *   shape: 'pill',
+ *   animation: 'invalid',
+ *   theme: 'system'
+ * });
+ * // Returns: [{ valid: false, factor: 'animation', ... }]
+ * ```
+ *
+ * @since 2.0.0
+ */
+export declare function validateFactors(config: Record<string, unknown>): FactorValidationResult[];
+/**
+ * Assert that a factor value is valid, throwing if not.
+ *
+ * @param factor - Factor name
+ * @param value - Value to validate
+ * @throws Error if value is invalid
+ *
+ * @example
+ * ```typescript
+ * assertValidFactor('shape', 'pill'); // OK
+ * assertValidFactor('shape', 'invalid'); // Throws Error
+ * ```
+ *
+ * @since 2.0.0
+ */
+export declare function assertValidFactor(factor: string, value: unknown): void;
+/**
+ * Coerce a value to a valid factor value, returning default if invalid.
+ *
+ * @param factor - Factor name
+ * @param value - Value to coerce
+ * @param defaultValue - Default value if invalid
+ * @returns Valid factor value or default
+ *
+ * @example
+ * ```typescript
+ * coerceFactorValue('shape', 'invalid', 'md')
+ * // => 'md' (default, because 'invalid' is not valid)
+ *
+ * coerceFactorValue('shape', 'pill', 'md')
+ * // => 'pill' (valid value)
+ * ```
+ *
+ * @since 2.0.0
+ */
+export declare function coerceFactorValue<T>(factor: string, value: unknown, defaultValue: T): T;
+export declare const FactorValidators: {
+    VALID_COLOR_SCHEMES: readonly ColorScheme[];
+    VALID_SIZES: readonly ComponentSize[];
+    VALID_SHAPES: readonly FactorShape[];
+    VALID_POSITIONS: readonly FactorPosition[];
+    VALID_ICON_POSITIONS: readonly FactorIconPosition[];
+    VALID_STATES: readonly FactorState[];
+    VALID_ANIMATIONS: readonly FactorAnimation[];
+    VALID_ELEVATIONS: readonly FactorElevation[];
+    VALID_A11Y_LEVELS: readonly FactorA11y[];
+    VALID_ALIGNMENTS: readonly FactorAlignment[];
+    VALID_ORIENTATIONS: readonly FactorOrientation[];
+    VALID_DENSITIES: readonly FactorDensity[];
+    VALID_LOADING_STATES: readonly FactorLoadingState[];
+    VALID_BREAKPOINTS: readonly FactorResponsiveBreakpoint[];
+    VALID_THEMES: readonly FactorTheme[];
+    VALID_SPACINGS: readonly FactorSpacing[];
+    VALID_TYPOGRAPHIES: readonly FactorTypography[];
+    VALID_BORDERS: readonly FactorBorder[];
+    VALID_OPACITIES: readonly FactorOpacity[];
+    VALID_OVERFLOWS: readonly FactorOverflow[];
+    VALID_CURSORS: readonly FactorCursor[];
+    VALID_Z_INDICES: readonly FactorZIndex[];
+    VALID_TRANSITIONS: readonly FactorTransition[];
+    isValidColorScheme: typeof isValidColorScheme;
+    isValidSize: typeof isValidSize;
+    isValidShape: typeof isValidShape;
+    isValidPosition: typeof isValidPosition;
+    isValidIconPosition: typeof isValidIconPosition;
+    isValidState: typeof isValidState;
+    isValidAnimation: typeof isValidAnimation;
+    isValidElevation: typeof isValidElevation;
+    isValidA11yLevel: typeof isValidA11yLevel;
+    isValidAlignment: typeof isValidAlignment;
+    isValidOrientation: typeof isValidOrientation;
+    isValidDensity: typeof isValidDensity;
+    isValidLoadingState: typeof isValidLoadingState;
+    isValidBreakpoint: typeof isValidBreakpoint;
+    isValidResponsiveConfig: typeof isValidResponsiveConfig;
+    isValidTheme: typeof isValidTheme;
+    isValidSpacing: typeof isValidSpacing;
+    isValidTypography: typeof isValidTypography;
+    isValidBorder: typeof isValidBorder;
+    isValidOpacity: typeof isValidOpacity;
+    isValidOverflow: typeof isValidOverflow;
+    isValidCursor: typeof isValidCursor;
+    isValidZIndex: typeof isValidZIndex;
+    isValidTransition: typeof isValidTransition;
+    validateFactor: typeof validateFactor;
+    validateFactors: typeof validateFactors;
+    assertValidFactor: typeof assertValidFactor;
+    coerceFactorValue: typeof coerceFactorValue;
+};
+export default FactorValidators;
+//# sourceMappingURL=factor-validators.d.ts.map