@nikkory/vibe-engine 4.0.0

package/dist/resolution/performance.d.ts

@@ -0,0 +1,264 @@
+/**
+ * Resolution Performance Utilities
+ *
+ * Provides caching, memoization, and performance optimization
+ * for the resolution engine.
+ *
+ * @packageDocumentation
+ * @module resolution/performance
+ * @since 2.1.0
+ *
+ * Powered by Nikkory
+ */
+import type { MultiLevelProps, Factor24Config, ResolutionResult } from './types';
+/**
+ * LRU Cache for resolution results.
+ * Caches resolved configs to avoid redundant resolution.
+ *
+ * @since 2.1.0
+ */
+export declare class ResolutionCache {
+    private cache;
+    private readonly maxSize;
+    private hits;
+    private misses;
+    /**
+     * Create a new resolution cache.
+     *
+     * @param maxSize - Maximum cache size (default: 100)
+     */
+    constructor(maxSize?: number);
+    /**
+     * Generate cache key from props.
+     * Uses JSON stringification with sorted keys for consistency.
+     */
+    private generateKey;
+    /**
+     * Get cached result or resolve and cache.
+     *
+     * @param props - Input props
+     * @returns Cached or freshly resolved result
+     */
+    get(props: MultiLevelProps): ResolutionResult;
+    /**
+     * Check if props are cached.
+     */
+    has(props: MultiLevelProps): boolean;
+    /**
+     * Clear the cache.
+     */
+    clear(): void;
+    /**
+     * Get cache statistics.
+     */
+    getStats(): {
+        size: number;
+        maxSize: number;
+        hits: number;
+        misses: number;
+        hitRate: number;
+    };
+    /**
+     * Invalidate specific entry.
+     */
+    invalidate(props: MultiLevelProps): boolean;
+}
+/**
+ * Memoized resolve function.
+ * Caches results based on props.
+ *
+ * @param cacheSize - Maximum cache size
+ * @returns Memoized resolve function
+ *
+ * @example
+ * ```typescript
+ * const memoizedResolve = createMemoizedResolver(50);
+ * const result1 = memoizedResolve({ intent: 'cta' });
+ * const result2 = memoizedResolve({ intent: 'cta' }); // Cached
+ * ```
+ *
+ * @since 2.1.0
+ */
+export declare function createMemoizedResolver(cacheSize?: number): (props: MultiLevelProps) => ResolutionResult;
+/**
+ * Memoize a factor expansion function.
+ *
+ * @param fn - Function to memoize
+ * @param cacheSize - Maximum cache size
+ * @returns Memoized function
+ *
+ * @since 2.1.0
+ */
+export declare function memoizeExpansion<T, R>(fn: (input: T) => R, cacheSize?: number): (input: T) => R;
+/**
+ * Resolve multiple props in batch.
+ * More efficient than resolving one by one.
+ *
+ * @param propsArray - Array of props to resolve
+ * @returns Array of resolution results
+ *
+ * @example
+ * ```typescript
+ * const results = batchResolve([
+ *   { intent: 'cta' },
+ *   { intent: 'primary' },
+ *   { look: 'bold' },
+ * ]);
+ * ```
+ *
+ * @since 2.1.0
+ */
+export declare function batchResolve(propsArray: MultiLevelProps[]): ResolutionResult[];
+/**
+ * Resolve props asynchronously.
+ * Useful for large batch operations.
+ *
+ * @param props - Props to resolve
+ * @returns Promise of resolution result
+ *
+ * @since 2.1.0
+ */
+export declare function resolveAsync(props: MultiLevelProps): Promise<ResolutionResult>;
+/**
+ * Resolve batch asynchronously with concurrency control.
+ *
+ * @param propsArray - Array of props
+ * @param concurrency - Max concurrent resolutions
+ * @returns Promise of results
+ *
+ * @since 2.1.0
+ */
+export declare function batchResolveAsync(propsArray: MultiLevelProps[], concurrency?: number): Promise<ResolutionResult[]>;
+/**
+ * Create a lazy resolver that defers resolution until needed.
+ *
+ * @param props - Props to resolve
+ * @returns Object with lazy access to config
+ *
+ * @example
+ * ```typescript
+ * const lazy = createLazyResolver({ intent: 'cta' });
+ * // Resolution happens only when accessed
+ * console.log(lazy.config.variant);
+ * ```
+ *
+ * @since 2.1.0
+ */
+export declare function createLazyResolver(props: MultiLevelProps): {
+    readonly config: Partial<Factor24Config>;
+    readonly isResolved: boolean;
+    resolve: () => ResolutionResult;
+};
+/**
+ * Performance metrics for resolution.
+ *
+ * @since 2.1.0
+ */
+export interface PerformanceMetrics {
+    /** Number of resolutions */
+    count: number;
+    /** Total time in ms */
+    totalTime: number;
+    /** Average time per resolution in ms */
+    averageTime: number;
+    /** Min time in ms */
+    minTime: number;
+    /** Max time in ms */
+    maxTime: number;
+    /** Resolutions per second */
+    throughput: number;
+}
+/**
+ * Performance profiler for resolution.
+ *
+ * @since 2.1.0
+ */
+export declare class ResolutionProfiler {
+    private measurements;
+    private startTime;
+    /**
+     * Start measuring.
+     */
+    start(): void;
+    /**
+     * End measurement and record.
+     */
+    end(): number;
+    /**
+     * Measure a resolution.
+     */
+    measure(props: MultiLevelProps): ResolutionResult;
+    /**
+     * Get performance metrics.
+     */
+    getMetrics(): PerformanceMetrics;
+    /**
+     * Reset measurements.
+     */
+    reset(): void;
+    /**
+     * Run benchmark with N iterations.
+     */
+    benchmark(props: MultiLevelProps, iterations?: number): PerformanceMetrics;
+}
+/**
+ * Global resolution cache instance.
+ * Use for application-wide caching.
+ *
+ * @since 2.1.0
+ */
+export declare const globalCache: ResolutionCache;
+/**
+ * Global memoized resolver.
+ *
+ * @since 2.1.0
+ */
+export declare const memoizedResolve: (props: MultiLevelProps) => ResolutionResult;
+/**
+ * Global profiler instance.
+ *
+ * @since 2.1.0
+ */
+export declare const profiler: ResolutionProfiler;
+/**
+ * Check if two configs are equal.
+ * Useful for avoiding re-renders.
+ *
+ * @param config1 - First config
+ * @param config2 - Second config
+ * @returns True if equal
+ *
+ * @since 2.1.0
+ */
+export declare function areConfigsEqual(config1: Partial<Factor24Config>, config2: Partial<Factor24Config>): boolean;
+/**
+ * Create a shallow comparison function for configs.
+ * Optimized for repeated comparisons.
+ *
+ * @param baseline - Baseline config to compare against
+ * @returns Comparison function
+ *
+ * @since 2.1.0
+ */
+export declare function createConfigComparator(baseline: Partial<Factor24Config>): (config: Partial<Factor24Config>) => boolean;
+/**
+ * Resolve only specific factors from props.
+ * More efficient when you only need a subset.
+ *
+ * @param props - Input props
+ * @param factors - Factors to resolve
+ * @returns Partial config with only requested factors
+ *
+ * @example
+ * ```typescript
+ * const partial = resolveFactors(
+ *   { intent: 'cta', look: 'bold' },
+ *   ['variant', 'colorScheme']
+ * );
+ * // Only variant and colorScheme are resolved
+ * ```
+ *
+ * @since 2.1.0
+ */
+export declare function resolveFactors<K extends keyof Factor24Config>(props: MultiLevelProps, factors: K[]): Pick<Factor24Config, K>;
+//# sourceMappingURL=performance.d.ts.map

package/dist/resolution/presets/button-presets.d.ts

@@ -0,0 +1,243 @@
+/**
+ * Button Presets - Pre-configured 24-Factor Configurations
+ *
+ * Named presets for buttons covering common use cases:
+ * - Hero/CTA presets for marketing and conversion
+ * - Form presets for actions (submit, cancel, delete)
+ * - Navigation presets for menus and links
+ * - Icon presets for icon-only buttons
+ * - Special presets for unique styles
+ *
+ * @packageDocumentation
+ * @module resolution/presets/button-presets
+ * @since 2.1.0
+ *
+ * Powered by Nikkory
+ */
+import type { PresetDefinition } from '../types';
+/**
+ * Hero Primary Button Preset
+ *
+ * High-impact primary CTA for hero sections and landing pages.
+ * Features bold styling, prominent elevation, and engaging animation.
+ *
+ * @since 2.1.0
+ */
+export declare const BUTTON_HERO_PRIMARY: PresetDefinition;
+/**
+ * Hero Secondary Button Preset
+ *
+ * Secondary CTA for hero sections, typically paired with primary.
+ * Uses outlined style with subtle animation.
+ *
+ * @since 2.1.0
+ */
+export declare const BUTTON_HERO_SECONDARY: PresetDefinition;
+/**
+ * CTA Gradient Button Preset
+ *
+ * Eye-catching gradient CTA for maximum visual impact.
+ * Features premium feel with elevated shadow and smooth animation.
+ *
+ * @since 2.1.0
+ */
+export declare const BUTTON_CTA_GRADIENT: PresetDefinition;
+/**
+ * CTA Minimal Button Preset
+ *
+ * Clean, minimal CTA for sophisticated designs.
+ * Features subtle animation and refined aesthetics.
+ *
+ * @since 2.1.0
+ */
+export declare const BUTTON_CTA_MINIMAL: PresetDefinition;
+/**
+ * Form Submit Button Preset
+ *
+ * Primary form submission button.
+ * Uses accessible styling with clear visual hierarchy.
+ *
+ * @since 2.1.0
+ */
+export declare const BUTTON_FORM_SUBMIT: PresetDefinition;
+/**
+ * Form Cancel Button Preset
+ *
+ * Cancel/dismiss button for forms.
+ * Uses subtle styling to avoid accidental clicks.
+ *
+ * @since 2.1.0
+ */
+export declare const BUTTON_FORM_CANCEL: PresetDefinition;
+/**
+ * Form Delete Button Preset
+ *
+ * Destructive action button for delete operations.
+ * Uses danger color scheme with confirmation-ready styling.
+ *
+ * @since 2.1.0
+ */
+export declare const BUTTON_FORM_DELETE: PresetDefinition;
+/**
+ * Form Save Button Preset
+ *
+ * Save action button for forms and editors.
+ * Uses success-oriented styling with feedback animation.
+ *
+ * @since 2.1.0
+ */
+export declare const BUTTON_FORM_SAVE: PresetDefinition;
+/**
+ * Form Reset Button Preset
+ *
+ * Reset/clear button for forms.
+ * Uses muted styling with warning undertones.
+ *
+ * @since 2.1.0
+ */
+export declare const BUTTON_FORM_RESET: PresetDefinition;
+/**
+ * Navigation Menu Button Preset
+ *
+ * Standard navigation menu item button.
+ * Uses minimal styling with clear hover states.
+ *
+ * @since 2.1.0
+ */
+export declare const BUTTON_NAV_MENU: PresetDefinition;
+/**
+ * Navigation Link Button Preset
+ *
+ * Link-styled button for navigation.
+ * Appears as a text link with button semantics.
+ *
+ * @since 2.1.0
+ */
+export declare const BUTTON_NAV_LINK: PresetDefinition;
+/**
+ * Breadcrumb Button Preset
+ *
+ * Breadcrumb navigation button.
+ * Compact styling for navigation paths.
+ *
+ * @since 2.1.0
+ */
+export declare const BUTTON_BREADCRUMB: PresetDefinition;
+/**
+ * Tab Button Preset
+ *
+ * Tab navigation button.
+ * Clear active/inactive states for tab interfaces.
+ *
+ * @since 2.1.0
+ */
+export declare const BUTTON_TAB: PresetDefinition;
+/**
+ * Icon Button Default Preset
+ *
+ * Standard icon-only button.
+ * Square shape optimized for icons.
+ *
+ * @since 2.1.0
+ */
+export declare const BUTTON_ICON_DEFAULT: PresetDefinition;
+/**
+ * Icon Button Circle Preset
+ *
+ * Circular icon button.
+ * Perfect for FABs and action buttons.
+ *
+ * @since 2.1.0
+ */
+export declare const BUTTON_ICON_CIRCLE: PresetDefinition;
+/**
+ * Icon Button Subtle Preset
+ *
+ * Subtle icon button for toolbars.
+ * Minimal visual presence until hovered.
+ *
+ * @since 2.1.0
+ */
+export declare const BUTTON_ICON_SUBTLE: PresetDefinition;
+/**
+ * Compact Button Preset
+ *
+ * Compact button for dense UIs.
+ * Minimal padding with clear hit targets.
+ *
+ * @since 2.1.0
+ */
+export declare const BUTTON_COMPACT: PresetDefinition;
+/**
+ * Pill Button Preset
+ *
+ * Pill-shaped button for tags and filters.
+ * Fully rounded ends with comfortable spacing.
+ *
+ * @since 2.1.0
+ */
+export declare const BUTTON_PILL: PresetDefinition;
+/**
+ * Loading Button Preset
+ *
+ * Button in loading state.
+ * Includes loading animation and disabled interaction.
+ *
+ * @since 2.1.0
+ */
+export declare const BUTTON_LOADING: PresetDefinition;
+/**
+ * Floating Action Button (FAB) Preset
+ *
+ * Material Design-style floating action button.
+ * Prominent elevation and circular shape.
+ *
+ * @since 2.1.0
+ */
+export declare const BUTTON_FAB: PresetDefinition;
+/**
+ * Split Button Preset
+ *
+ * Button with dropdown trigger.
+ * Used for primary action with additional options.
+ *
+ * @since 2.1.0
+ */
+export declare const BUTTON_SPLIT: PresetDefinition;
+/**
+ * All button presets as an array.
+ *
+ * @since 2.1.0
+ */
+export declare const BUTTON_PRESETS: ReadonlyArray<PresetDefinition>;
+/**
+ * Button presets as a map for quick lookup.
+ *
+ * @since 2.1.0
+ */
+export declare const BUTTON_PRESETS_MAP: ReadonlyMap<string, PresetDefinition>;
+/**
+ * Get a button preset by ID.
+ *
+ * @param id - The preset ID
+ * @returns The preset definition or undefined if not found
+ * @since 2.1.0
+ */
+export declare function getButtonPreset(id: string): PresetDefinition | undefined;
+/**
+ * Get all button presets matching given tags.
+ *
+ * @param tags - Tags to match (ANY match)
+ * @returns Array of matching presets
+ * @since 2.1.0
+ */
+export declare function getButtonPresetsByTags(tags: string[]): PresetDefinition[];
+/**
+ * Check if a preset ID is a valid button preset.
+ *
+ * @param id - The preset ID to check
+ * @returns True if the ID is a valid button preset
+ * @since 2.1.0
+ */
+export declare function isButtonPreset(id: string): boolean;
+//# sourceMappingURL=button-presets.d.ts.map

package/dist/resolution/presets/card-presets.d.ts

@@ -0,0 +1,216 @@
+/**
+ * Card Presets - Pre-configured 24-Factor Configurations
+ *
+ * Named presets for cards covering common use cases:
+ * - Content cards for articles and posts
+ * - Product cards for e-commerce
+ * - Profile cards for user information
+ * - Interactive cards with hover effects
+ * - Special cards for unique layouts
+ *
+ * @packageDocumentation
+ * @module resolution/presets/card-presets
+ * @since 2.1.0
+ *
+ * Powered by Nikkory
+ */
+import type { PresetDefinition } from '../types';
+/**
+ * Content Card Default Preset
+ *
+ * Standard content card for articles and blog posts.
+ * Clean layout with subtle elevation.
+ *
+ * @since 2.1.0
+ */
+export declare const CARD_CONTENT_DEFAULT: PresetDefinition;
+/**
+ * Content Card Featured Preset
+ *
+ * Featured content card with larger presence.
+ * Higher elevation and prominent styling.
+ *
+ * @since 2.1.0
+ */
+export declare const CARD_CONTENT_FEATURED: PresetDefinition;
+/**
+ * Content Card Minimal Preset
+ *
+ * Minimal content card with clean aesthetics.
+ * No elevation, subtle borders.
+ *
+ * @since 2.1.0
+ */
+export declare const CARD_CONTENT_MINIMAL: PresetDefinition;
+/**
+ * Product Card Default Preset
+ *
+ * Standard product card for e-commerce listings.
+ * Optimized for product images and pricing.
+ *
+ * @since 2.1.0
+ */
+export declare const CARD_PRODUCT_DEFAULT: PresetDefinition;
+/**
+ * Product Card Featured Preset
+ *
+ * Featured product card with promotional styling.
+ * Eye-catching design for special offers.
+ *
+ * @since 2.1.0
+ */
+export declare const CARD_PRODUCT_FEATURED: PresetDefinition;
+/**
+ * Product Card Compact Preset
+ *
+ * Compact product card for grid layouts.
+ * Smaller footprint for dense product listings.
+ *
+ * @since 2.1.0
+ */
+export declare const CARD_PRODUCT_COMPACT: PresetDefinition;
+/**
+ * Profile Card Default Preset
+ *
+ * Standard profile card for user information.
+ * Centered layout optimized for avatars.
+ *
+ * @since 2.1.0
+ */
+export declare const CARD_PROFILE_DEFAULT: PresetDefinition;
+/**
+ * Profile Card Horizontal Preset
+ *
+ * Horizontal profile card for team listings.
+ * Side-by-side layout with avatar and info.
+ *
+ * @since 2.1.0
+ */
+export declare const CARD_PROFILE_HORIZONTAL: PresetDefinition;
+/**
+ * Profile Card Compact Preset
+ *
+ * Compact profile card for inline displays.
+ * Minimal styling for lists and mentions.
+ *
+ * @since 2.1.0
+ */
+export declare const CARD_PROFILE_COMPACT: PresetDefinition;
+/**
+ * Interactive Card Default Preset
+ *
+ * Clickable card with hover effects.
+ * Clear interactive affordance.
+ *
+ * @since 2.1.0
+ */
+export declare const CARD_INTERACTIVE_DEFAULT: PresetDefinition;
+/**
+ * Interactive Card Selection Preset
+ *
+ * Selectable card for multi-select interfaces.
+ * Clear selected/unselected states.
+ *
+ * @since 2.1.0
+ */
+export declare const CARD_INTERACTIVE_SELECTION: PresetDefinition;
+/**
+ * Interactive Card Draggable Preset
+ *
+ * Draggable card for sortable lists.
+ * Visual feedback for drag interactions.
+ *
+ * @since 2.1.0
+ */
+export declare const CARD_INTERACTIVE_DRAGGABLE: PresetDefinition;
+/**
+ * Glass Card Preset
+ *
+ * Glassmorphism-style card with frosted effect.
+ * Modern aesthetic for overlay content.
+ *
+ * @since 2.1.0
+ */
+export declare const CARD_GLASS: PresetDefinition;
+/**
+ * Neumorphic Card Preset
+ *
+ * Neumorphism-style card with soft shadows.
+ * Subtle depth effect.
+ *
+ * @since 2.1.0
+ */
+export declare const CARD_NEUMORPHIC: PresetDefinition;
+/**
+ * Stats Card Preset
+ *
+ * Statistics/metrics card for dashboards.
+ * Optimized for number display.
+ *
+ * @since 2.1.0
+ */
+export declare const CARD_STATS: PresetDefinition;
+/**
+ * Pricing Card Preset
+ *
+ * Pricing tier card for subscription pages.
+ * Prominent CTA placement.
+ *
+ * @since 2.1.0
+ */
+export declare const CARD_PRICING: PresetDefinition;
+/**
+ * Testimonial Card Preset
+ *
+ * Customer testimonial card.
+ * Quote-friendly layout.
+ *
+ * @since 2.1.0
+ */
+export declare const CARD_TESTIMONIAL: PresetDefinition;
+/**
+ * Notification Card Preset
+ *
+ * Notification/alert card with status colors.
+ * Compact and informative.
+ *
+ * @since 2.1.0
+ */
+export declare const CARD_NOTIFICATION: PresetDefinition;
+/**
+ * All card presets as an array.
+ *
+ * @since 2.1.0
+ */
+export declare const CARD_PRESETS: ReadonlyArray<PresetDefinition>;
+/**
+ * Card presets as a map for quick lookup.
+ *
+ * @since 2.1.0
+ */
+export declare const CARD_PRESETS_MAP: ReadonlyMap<string, PresetDefinition>;
+/**
+ * Get a card preset by ID.
+ *
+ * @param id - The preset ID
+ * @returns The preset definition or undefined if not found
+ * @since 2.1.0
+ */
+export declare function getCardPreset(id: string): PresetDefinition | undefined;
+/**
+ * Get all card presets matching given tags.
+ *
+ * @param tags - Tags to match (ANY match)
+ * @returns Array of matching presets
+ * @since 2.1.0
+ */
+export declare function getCardPresetsByTags(tags: string[]): PresetDefinition[];
+/**
+ * Check if a preset ID is a valid card preset.
+ *
+ * @param id - The preset ID to check
+ * @returns True if the ID is a valid card preset
+ * @since 2.1.0
+ */
+export declare function isCardPreset(id: string): boolean;
+//# sourceMappingURL=card-presets.d.ts.map