@nikkory/vibe-engine 4.0.0

package/dist/utils/stringify.d.ts

@@ -0,0 +1,28 @@
+/**
+ * String Utilities
+ *
+ * Safe stringification for any value type.
+ *
+ * @packageDocumentation
+ * @module utils/stringify
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+/**
+ * Safely convert any value to string.
+ * Handles objects, arrays, primitives.
+ *
+ * @param value - Value to stringify
+ * @returns String representation
+ *
+ * @example
+ * ```typescript
+ * safeStringify({ foo: 'bar' }) // '{"foo":"bar"}'
+ * safeStringify('hello') // 'hello'
+ * safeStringify(123) // '123'
+ * safeStringify(undefined) // 'undefined'
+ * ```
+ */
+export declare function safeStringify(value: unknown): string;
+//# sourceMappingURL=stringify.d.ts.map

package/dist/validators/component-validator.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Component Validator
+ * Input validation for component type parameters
+ *
+ * @packageDocumentation
+ * @module validators/component-validator
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+import type { ComponentType } from '../types';
+import type { ValidationResult } from '../types/algorithm-engine.types';
+/**
+ * All valid component types
+ */
+export declare const VALID_COMPONENT_TYPES: readonly ComponentType[];
+/**
+ * Check if a value is a valid component type
+ *
+ * @param value - Value to check
+ * @returns True if value is a valid component type
+ *
+ * @example
+ * ```typescript
+ * isValidComponentType('button')  // true
+ * isValidComponentType('invalid') // false
+ * ```
+ */
+export declare function isValidComponentType(value: unknown): value is ComponentType;
+/**
+ * Validate component type input
+ *
+ * @param componentType - Component type to validate
+ * @returns Validation result
+ *
+ * @example
+ * ```typescript
+ * validateComponentType('button')
+ * // { valid: true, errors: [], warnings: [] }
+ *
+ * validateComponentType('invalid')
+ * // { valid: false, errors: ['Invalid component type...'], warnings: [] }
+ * ```
+ */
+export declare function validateComponentType(componentType: unknown): ValidationResult;
+/**
+ * Assert that a value is a valid component type
+ *
+ * @param value - Value to check
+ * @throws Error if value is not a valid component type
+ */
+export declare function assertValidComponentType(value: unknown): asserts value is ComponentType;
+/**
+ * Parse and validate component type
+ *
+ * @param value - Value to parse
+ * @returns Valid component type or undefined
+ */
+export declare function parseComponentType(value: unknown): ComponentType | undefined;
+/**
+ * Get component type with fallback
+ *
+ * @param value - Value to check
+ * @param defaultType - Default component type
+ * @returns Valid component type
+ */
+export declare function getComponentTypeOrDefault(value: unknown, defaultType: ComponentType): ComponentType;
+/**
+ * Suggest similar component type for typos
+ *
+ * @param input - User input
+ * @returns Suggested component type or undefined
+ */
+export declare function suggestComponentType(input: string): ComponentType | undefined;
+/**
+ * Get component types by category
+ *
+ * @param category - Category to filter by
+ * @returns Array of component types in the category
+ */
+export declare function getComponentTypesByCategory(category: 'basic' | 'feedback' | 'navigation' | 'data-display' | 'overlay' | 'date-time' | 'media'): ComponentType[];
+/**
+ * Get all component type categories
+ */
+export declare function getAllComponentCategories(): string[];
+//# sourceMappingURL=component-validator.d.ts.map

package/dist/validators/design-system-validator.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Design System Validator
+ * Input validation for design system parameters
+ *
+ * @packageDocumentation
+ * @module validators/design-system-validator
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+import type { DesignSystem } from '../types';
+import type { ValidationResult } from '../types/algorithm-engine.types';
+/**
+ * All valid design systems (12 total)
+ */
+export declare const VALID_DESIGN_SYSTEMS: readonly DesignSystem[];
+/**
+ * Check if a value is a valid design system
+ *
+ * @param value - Value to check
+ * @returns True if value is a valid design system
+ *
+ * @example
+ * ```typescript
+ * isValidDesignSystem('material-design') // true
+ * isValidDesignSystem('invalid')         // false
+ * ```
+ */
+export declare function isValidDesignSystem(value: unknown): value is DesignSystem;
+/**
+ * Validate design system input
+ *
+ * @param designSystem - Design system to validate
+ * @returns Validation result
+ *
+ * @example
+ * ```typescript
+ * validateDesignSystem('material-design')
+ * // { valid: true, errors: [], warnings: [] }
+ *
+ * validateDesignSystem('invalid')
+ * // { valid: false, errors: ['Invalid design system...'], warnings: [] }
+ * ```
+ */
+export declare function validateDesignSystem(designSystem: unknown): ValidationResult;
+/**
+ * Assert that a value is a valid design system
+ *
+ * @param value - Value to check
+ * @throws Error if value is not a valid design system
+ */
+export declare function assertValidDesignSystem(value: unknown): asserts value is DesignSystem;
+/**
+ * Parse and validate design system
+ *
+ * @param value - Value to parse
+ * @returns Valid design system or undefined
+ */
+export declare function parseDesignSystem(value: unknown): DesignSystem | undefined;
+/**
+ * Get design system with fallback
+ *
+ * @param value - Value to check
+ * @param defaultDs - Default design system
+ * @returns Valid design system
+ */
+export declare function getDesignSystemOrDefault(value: unknown, defaultDs: DesignSystem): DesignSystem;
+/**
+ * Suggest similar design system for typos
+ *
+ * @param input - User input
+ * @returns Suggested design system or undefined
+ */
+export declare function suggestDesignSystem(input: string): DesignSystem | undefined;
+/**
+ * Get design system display name
+ *
+ * @param designSystem - Design system ID
+ * @returns Human-readable display name
+ */
+export declare function getDesignSystemDisplayName(designSystem: DesignSystem): string;
+/**
+ * Get design system company/origin
+ *
+ * @param designSystem - Design system ID
+ * @returns Company or origin of the design system
+ */
+export declare function getDesignSystemOrigin(designSystem: DesignSystem): string;
+/**
+ * Get all design system IDs
+ *
+ * @returns Array of all design system IDs
+ */
+export declare function getAllDesignSystems(): DesignSystem[];
+//# sourceMappingURL=design-system-validator.d.ts.map

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

@@ -0,0 +1,101 @@
+/**
+ * Factor Validator
+ * Input validation for factor parameters
+ *
+ * @packageDocumentation
+ * @module validators/factor-validator
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+import type { FactorId, ValidationResult } from '../types/algorithm-engine.types';
+/**
+ * All valid factor IDs (1-24)
+ */
+export declare const VALID_FACTOR_IDS: readonly FactorId[];
+/**
+ * Check if a value is a valid factor ID
+ *
+ * @param value - Value to check
+ * @returns True if value is a valid factor ID (1-24)
+ *
+ * @example
+ * ```typescript
+ * isValidFactorId(1)  // true
+ * isValidFactorId(24) // true
+ * isValidFactorId(0)  // false
+ * isValidFactorId(25) // false
+ * ```
+ */
+export declare function isValidFactorId(value: unknown): value is FactorId;
+/**
+ * Validate factor ID input
+ *
+ * @param factorId - Factor ID to validate
+ * @returns Validation result
+ *
+ * @example
+ * ```typescript
+ * validateFactorId(1)
+ * // { valid: true, errors: [], warnings: [] }
+ *
+ * validateFactorId(25)
+ * // { valid: false, errors: ['Invalid factor ID...'], warnings: [] }
+ * ```
+ */
+export declare function validateFactorId(factorId: unknown): ValidationResult;
+/**
+ * Validate a factor value for a specific factor ID
+ *
+ * @param factorId - Factor ID to validate value for
+ * @param value - Value to validate
+ * @returns Validation result
+ *
+ * @example
+ * ```typescript
+ * validateFactorValueInput(1, 'primary')
+ * // { valid: true, errors: [], warnings: [] }
+ *
+ * validateFactorValueInput(1, 'invalid')
+ * // { valid: false, errors: ['Invalid value...'], warnings: [] }
+ * ```
+ */
+export declare function validateFactorValueInput(factorId: unknown, value: unknown): ValidationResult;
+/**
+ * Validate factor overrides object
+ *
+ * @param overrides - Factor overrides to validate
+ * @returns Validation result
+ *
+ * @example
+ * ```typescript
+ * validateFactorOverrides({ 1: 'secondary', 2: 'lg' })
+ * // { valid: true, errors: [], warnings: [] }
+ *
+ * validateFactorOverrides({ 1: 'invalid', 99: 'value' })
+ * // { valid: false, errors: [...], warnings: [] }
+ * ```
+ */
+export declare function validateFactorOverrides(overrides: unknown): ValidationResult;
+/**
+ * Assert that a value is a valid factor ID
+ *
+ * @param value - Value to check
+ * @throws Error if value is not a valid factor ID
+ */
+export declare function assertValidFactorId(value: unknown): asserts value is FactorId;
+/**
+ * Parse and validate factor ID
+ *
+ * @param value - Value to parse
+ * @returns Valid factor ID or undefined
+ */
+export declare function parseFactorId(value: unknown): FactorId | undefined;
+/**
+ * Suggest similar factor names for typos
+ *
+ * @param input - User input
+ * @returns Array of suggested factor names
+ */
+export declare function suggestFactorName(input: string): string[];
+//# sourceMappingURL=factor-validator.d.ts.map

package/dist/validators/index.d.ts

@@ -0,0 +1,263 @@
+/**
+ * Algorithm Engine Validators
+ * Barrel export for all validator modules
+ *
+ * @packageDocumentation
+ * @module validators
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+/**
+ * Tier validation utilities
+ *
+ * @example
+ * ```typescript
+ * import { isValidTier, validateTier, parseTier } from '@nikkory/vibe-engine/validators';
+ *
+ * // Type guard
+ * if (isValidTier(input)) {
+ *   // input is Tier
+ * }
+ *
+ * // Validation with errors
+ * const result = validateTier('basic');
+ * if (!result.valid) {
+ *   console.error(result.errors);
+ * }
+ *
+ * // Parse with fallback
+ * const tier = parseTier('basci') ?? 'basic';
+ * ```
+ */
+export { 
+/** All valid tier values: 'basic', 'standard', 'enterprise' */
+VALID_TIERS, 
+/** Type guard to check if value is a valid Tier */
+isValidTier, 
+/** Validate tier with detailed error messages */
+validateTier, 
+/** Assert tier is valid, throws if invalid */
+assertValidTier, 
+/** Parse and validate tier, returns undefined if invalid */
+parseTier, 
+/** Get tier or fallback to default */
+getTierOrDefault, 
+/** Suggest correct tier for typos */
+suggestTier, } from './tier-validator';
+/**
+ * Factor validation utilities for 24-Factor system
+ *
+ * @example
+ * ```typescript
+ * import { isValidFactorId, validateFactorOverrides } from '@nikkory/vibe-engine/validators';
+ *
+ * // Validate factor ID (1-24)
+ * if (isValidFactorId(5)) {
+ *   // factorId is FactorId type
+ * }
+ *
+ * // Validate factor overrides object
+ * const result = validateFactorOverrides({ 1: 'primary', 2: 'lg' });
+ * ```
+ */
+export { 
+/** All valid factor IDs (1-24) */
+VALID_FACTOR_IDS, 
+/** Type guard for valid factor ID */
+isValidFactorId, 
+/** Validate factor ID with detailed errors */
+validateFactorId, 
+/** Validate factor value for a specific factor */
+validateFactorValueInput, 
+/** Validate factor overrides object */
+validateFactorOverrides, 
+/** Assert factor ID is valid, throws if invalid */
+assertValidFactorId, 
+/** Parse factor ID from string or number */
+parseFactorId, 
+/** Suggest factor names for typos */
+suggestFactorName, } from './factor-validator';
+/**
+ * Component type validation utilities
+ *
+ * @example
+ * ```typescript
+ * import { isValidComponentType, validateComponentType } from '@nikkory/vibe-engine/validators';
+ *
+ * // Type guard
+ * if (isValidComponentType('button')) {
+ *   // type is ComponentType
+ * }
+ *
+ * // Get components by category
+ * const formComponents = getComponentTypesByCategory('form');
+ * ```
+ */
+export { 
+/** All valid component types (32 types) */
+VALID_COMPONENT_TYPES, 
+/** Type guard for valid component type */
+isValidComponentType, 
+/** Validate component type with detailed errors */
+validateComponentType, 
+/** Assert component type is valid, throws if invalid */
+assertValidComponentType, 
+/** Parse component type from string */
+parseComponentType, 
+/** Get component type or fallback to default */
+getComponentTypeOrDefault, 
+/** Suggest component types for typos */
+suggestComponentType, 
+/** Get component types by category */
+getComponentTypesByCategory, 
+/** Get all component categories */
+getAllComponentCategories, } from './component-validator';
+/**
+ * Design system validation utilities
+ *
+ * @example
+ * ```typescript
+ * import { isValidDesignSystem, validateDesignSystem } from '@nikkory/vibe-engine/validators';
+ *
+ * // Type guard
+ * if (isValidDesignSystem('material-design')) {
+ *   // ds is DesignSystem type
+ * }
+ *
+ * // Get display info
+ * const name = getDesignSystemDisplayName('ios-hig'); // "iOS HIG"
+ * const origin = getDesignSystemOrigin('material-design'); // "Google"
+ * ```
+ */
+export { 
+/** All valid design system identifiers (12 systems) */
+VALID_DESIGN_SYSTEMS, 
+/** Type guard for valid design system */
+isValidDesignSystem, 
+/** Validate design system with detailed errors */
+validateDesignSystem, 
+/** Assert design system is valid, throws if invalid */
+assertValidDesignSystem, 
+/** Parse design system from string */
+parseDesignSystem, 
+/** Get design system or fallback to default */
+getDesignSystemOrDefault, 
+/** Suggest design systems for typos */
+suggestDesignSystem, 
+/** Get human-readable display name */
+getDesignSystemDisplayName, 
+/** Get design system origin/company */
+getDesignSystemOrigin, 
+/** Get all design system identifiers */
+getAllDesignSystems, } from './design-system-validator';
+/**
+ * Section configuration validation utilities
+ *
+ * @example
+ * ```typescript
+ * import { validateSectionConfig, validateSectionFactors } from '@nikkory/vibe-engine/validators';
+ *
+ * // Validate SectionConfig
+ * const result = validateSectionConfig({
+ *   sectionId: 'hero-1',
+ *   sectionType: 'hero',
+ *   title: 'Welcome',
+ *   designSystem: 'material-design',
+ *   tier: 'enterprise',
+ *   layout: 'flex',
+ *   columns: 2,
+ *   spacing: 'lg',
+ * });
+ *
+ * if (!result.valid) {
+ *   console.error(result.errors);
+ * }
+ *
+ * // Validate SectionFactors
+ * const factorsResult = validateSectionFactors({
+ *   colorPrimary: '#6750a4',
+ *   // ... other factors
+ * });
+ * ```
+ */
+export { 
+/** Validate SectionConfig object */
+validateSectionConfig, 
+/** Validate SectionFactors object */
+validateSectionFactors, 
+/** Create validated SectionConfig (throws on error) */
+createValidatedConfig, 
+/** Create validated SectionFactors (throws on error) */
+createValidatedFactors, 
+/** Type guard for SectionCategory */
+isSectionCategory, 
+/** Type guard for LayoutType */
+isLayoutType, 
+/** Type guard for SpacingLevel */
+isSpacingLevel, 
+/** Type guard for DesignSystem (from section-validator) */
+isValidDesignSystem as isSectionDesignSystem, 
+/** Type guard for Tier (from section-validator) */
+isValidTier as isSectionTier, } from './section-validator';
+/**
+ * Slot configuration validation utilities
+ *
+ * @example
+ * ```typescript
+ * import { validateSlotConfig, validateStoredComponent } from '@nikkory/vibe-engine/validators';
+ *
+ * // Validate SlotConfig
+ * const result = validateSlotConfig({
+ *   slotId: 'header-slot',
+ *   position: 'header',
+ *   allowedComponents: ['button', 'badge'],
+ *   maxComponents: 5,
+ * });
+ *
+ * // Validate StoredComponentInSlot
+ * const componentResult = validateStoredComponent({
+ *   componentRef: 'button',
+ *   instanceId: 'btn-1',
+ *   propOverrides: { variant: 'primary' },
+ *   order: 0,
+ *   visible: true,
+ * });
+ * ```
+ */
+export { 
+/** Validate SlotConfig object */
+validateSlotConfig, 
+/** Validate multiple SlotConfig objects */
+validateSlotConfigs, 
+/** Validate StoredComponentInSlot object */
+validateStoredComponent, 
+/** Validate component placement in slot */
+validateComponentInSlot, 
+/** Validate multiple components in a slot */
+validateComponentsInSlot, 
+/** Create validated SlotConfig (throws on error) */
+createValidatedSlotConfig, 
+/** Create validated StoredComponentInSlot (throws on error) */
+createValidatedStoredComponent, 
+/** Type guard for SlotPosition */
+isSlotPosition, 
+/** Type guard for ComponentType */
+isComponentType, 
+/** Type guard for valid SlotConfig */
+isValidSlotConfig, 
+/** Type guard for valid StoredComponentInSlot */
+isValidStoredComponent, 
+/** Default header slot config */
+DEFAULT_HEADER_SLOT, 
+/** Default content slot config */
+DEFAULT_CONTENT_SLOT, 
+/** Default footer slot config */
+DEFAULT_FOOTER_SLOT, 
+/** Default sidebar slot config */
+DEFAULT_SIDEBAR_SLOT, 
+/** Default overlay slot config */
+DEFAULT_OVERLAY_SLOT, 
+/** Get default slot config by position */
+getDefaultSlotConfig, } from './slot-validator';
+//# sourceMappingURL=index.d.ts.map

package/dist/validators/section-validator.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Section Validator - Validates SectionConfig objects
+ *
+ * @packageDocumentation
+ * @module validators/section-validator
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+import type { DesignSystem } from '../constants/DesignSystems';
+import type { Tier } from '../constants/Tiers';
+import type { ValidationResult } from '../types/algorithm-engine.types';
+import type { SectionConfig, SectionCategory, LayoutType, SpacingLevel, SectionFactors } from '../types/section.types';
+/**
+ * Validate a SectionConfig object
+ *
+ * @param config - The SectionConfig to validate
+ * @returns ValidationResult indicating success or failure with error messages
+ *
+ * @example
+ * ```typescript
+ * const result = validateSectionConfig({
+ *   sectionId: 'hero-1',
+ *   sectionType: 'hero',
+ *   title: 'Welcome',
+ *   designSystem: 'material-design',
+ *   tier: 'enterprise',
+ *   layout: 'flex',
+ *   columns: 2,
+ *   spacing: 'lg',
+ * });
+ *
+ * if (result.valid) {
+ *   console.log('Config is valid');
+ * } else {
+ *   console.log('Errors:', result.errors);
+ * }
+ * ```
+ */
+export declare function validateSectionConfig(config: unknown): ValidationResult;
+/**
+ * Validate SectionFactors object
+ *
+ * @param factors - The SectionFactors to validate
+ * @returns ValidationResult indicating success or failure with error messages
+ *
+ * @example
+ * ```typescript
+ * const result = validateSectionFactors({
+ *   colorPrimary: '#6750a4',
+ *   colorText: '#1c1b1f',
+ *   colorBackground: '#fffbfe',
+ *   typography: 'default',
+ *   borderRadius: 'lg',
+ *   elevation: 'sm',
+ *   padding: 'lg',
+ *   gap: 'md',
+ *   alignment: 'center',
+ *   maxWidth: 'xl',
+ *   animation: 'smooth',
+ *   responsive: { mobile: 'stack', tablet: 'grid', desktop: 'grid' },
+ *   a11yLevel: 'enhanced',
+ * });
+ * ```
+ */
+export declare function validateSectionFactors(factors: unknown): ValidationResult;
+/**
+ * Create a validated SectionConfig
+ *
+ * @param config - Partial config to validate and return
+ * @returns The validated SectionConfig or throws on invalid
+ * @throws Error if validation fails
+ *
+ * @example
+ * ```typescript
+ * const config = createValidatedConfig({
+ *   sectionId: 'hero-1',
+ *   sectionType: 'hero',
+ *   // ... other fields
+ * });
+ * ```
+ */
+export declare function createValidatedConfig(config: unknown): SectionConfig;
+/**
+ * Create validated SectionFactors
+ *
+ * @param factors - Factors to validate and return
+ * @returns The validated SectionFactors or throws on invalid
+ * @throws Error if validation fails
+ *
+ * @example
+ * ```typescript
+ * const factors = createValidatedFactors({
+ *   colorPrimary: '#6750a4',
+ *   // ... other fields
+ * });
+ * ```
+ */
+export declare function createValidatedFactors(factors: unknown): SectionFactors;
+/**
+ * Type guard to check if a value is a valid SectionCategory
+ */
+export declare function isSectionCategory(value: unknown): value is SectionCategory;
+/**
+ * Type guard to check if a value is a valid LayoutType
+ */
+export declare function isLayoutType(value: unknown): value is LayoutType;
+/**
+ * Type guard to check if a value is a valid SpacingLevel
+ */
+export declare function isSpacingLevel(value: unknown): value is SpacingLevel;
+/**
+ * Type guard to check if a value is a valid DesignSystem
+ */
+export declare function isValidDesignSystem(value: unknown): value is DesignSystem;
+/**
+ * Type guard to check if a value is a valid Tier
+ */
+export declare function isValidTier(value: unknown): value is Tier;
+//# sourceMappingURL=section-validator.d.ts.map