@nikkory/vibe-engine 4.0.0

package/dist/resolution/resolveProps.d.ts

@@ -0,0 +1,235 @@
+/**
+ * Resolution Engine - 5-Level Abstraction API
+ *
+ * Main resolution function that converts MultiLevelProps to Factor24Config.
+ * Implements the 5-level priority system:
+ *
+ * Priority: Level 1 (raw) > Level 2 (groups) > Level 3 (shorthand) > Level 4 (preset) > Level 5 (intent)
+ *
+ * @packageDocumentation
+ * @module resolution/resolveProps
+ * @since 2.1.0
+ *
+ * Powered by Nikkory
+ */
+import { type ShorthandProps } from './shorthand';
+import type { Factor24Config, MultiLevelProps, ResolutionResult, SemanticIntent, SemanticMood, IntentDefinition, MoodModifierDefinition, PresetDefinition } from './types';
+/**
+ * Built-in intent definitions.
+ *
+ * @since 2.1.0
+ */
+export declare const INTENT_DEFINITIONS: Record<SemanticIntent, IntentDefinition>;
+/**
+ * Built-in mood modifier definitions.
+ *
+ * @since 2.1.0
+ */
+export declare const MOOD_DEFINITIONS: Record<SemanticMood, MoodModifierDefinition>;
+/**
+ * Register a preset.
+ *
+ * @param preset - The preset to register
+ * @since 2.1.0
+ */
+export declare function registerPreset(preset: PresetDefinition): void;
+/**
+ * Get a preset by ID.
+ *
+ * @param id - The preset ID
+ * @returns The preset or undefined
+ * @since 2.1.0
+ */
+export declare function getPreset(id: string): PresetDefinition | undefined;
+/**
+ * Check if a preset exists.
+ *
+ * @param id - The preset ID
+ * @returns True if the preset exists
+ * @since 2.1.0
+ */
+export declare function hasPreset(id: string): boolean;
+/**
+ * Get all registered presets.
+ *
+ * @returns Map of all presets
+ * @since 2.1.0
+ */
+export declare function getAllPresets(): Map<string, PresetDefinition>;
+/**
+ * Clear all registered presets.
+ *
+ * @since 2.1.0
+ */
+export declare function clearPresets(): void;
+/**
+ * Detect which levels are present in MultiLevelProps.
+ *
+ * @param props - The multi-level props to analyze
+ * @returns Object indicating which levels are present
+ * @since 2.1.0
+ */
+export declare function detectLevels(props: MultiLevelProps): {
+    hasLevel5: boolean;
+    hasLevel4: boolean;
+    hasLevel3: boolean;
+    hasLevel2: boolean;
+    hasLevel1: boolean;
+    levels: number[];
+};
+/**
+ * Validation result for resolution.
+ *
+ * @since 2.1.0
+ */
+export interface ResolutionValidationResult {
+    /** Overall validation status */
+    valid: boolean;
+    /** Errors */
+    errors: string[];
+    /** Warnings (non-blocking) */
+    warnings: string[];
+}
+/**
+ * Validate MultiLevelProps before resolution.
+ *
+ * @param props - The props to validate
+ * @returns Validation result
+ * @since 2.1.0
+ */
+export declare function validateMultiLevelProps(props: MultiLevelProps): ResolutionValidationResult;
+/**
+ * Options for the resolution process.
+ *
+ * @since 2.1.0
+ */
+export interface ResolutionOptions {
+    /** Whether to include debug information */
+    debug?: boolean;
+    /** Whether to validate props before resolution */
+    validate?: boolean;
+    /** Whether to apply defaults for missing factors */
+    applyDefaults?: boolean;
+    /** Custom preset registry */
+    presets?: Map<string, PresetDefinition>;
+}
+/**
+ * Default resolution options.
+ *
+ * @since 2.1.0
+ */
+export declare const DEFAULT_RESOLUTION_OPTIONS: Required<ResolutionOptions>;
+/**
+ * Resolve MultiLevelProps to Factor24Config.
+ *
+ * This is the main entry point for the 5-Level Abstraction API.
+ * It takes props at any combination of levels and produces a
+ * complete Factor24Config with correct priority merging.
+ *
+ * Priority order (highest to lowest):
+ * 1. Level 1: Raw factors (size, variant, etc.)
+ * 2. Level 2: Factor groups (visual, motion, layout, experience)
+ * 3. Level 3: Shorthands (look, feel, surface, spacing)
+ * 4. Level 4: Named presets
+ * 5. Level 5: Semantic intents and moods
+ *
+ * @param props - MultiLevelProps to resolve
+ * @param options - Resolution options
+ * @returns Resolution result with config and metadata
+ *
+ * @example
+ * ```typescript
+ * // Using Level 5 (Intent)
+ * const result = resolveProps({ intent: 'cta', mood: 'playful' });
+ *
+ * // Using Level 3 (Shorthands) with Level 1 override
+ * const result = resolveProps({
+ *   look: 'bold',
+ *   feel: 'snappy',
+ *   size: 'lg', // Level 1 override
+ * });
+ *
+ * // Mixing all levels
+ * const result = resolveProps({
+ *   intent: 'primary',          // Level 5
+ *   look: 'elevated',           // Level 3
+ *   visual: { shape: 'lg' },    // Level 2
+ *   colorScheme: 'secondary',   // Level 1 (overrides all)
+ * });
+ * ```
+ *
+ * @since 2.1.0
+ */
+export declare function resolveProps(props: MultiLevelProps, options?: ResolutionOptions): ResolutionResult;
+/**
+ * Resolve props with defaults applied.
+ *
+ * @param props - MultiLevelProps to resolve
+ * @returns Complete Factor24Config with all defaults
+ * @since 2.1.0
+ */
+export declare function resolveWithDefaults(props: MultiLevelProps): Factor24Config;
+/**
+ * Resolve props and return only the config.
+ *
+ * @param props - MultiLevelProps to resolve
+ * @returns Factor24Config
+ * @since 2.1.0
+ */
+export declare function resolveToConfig(props: MultiLevelProps): Factor24Config;
+/**
+ * Resolve props with debug information.
+ *
+ * @param props - MultiLevelProps to resolve
+ * @returns Resolution result with debug info
+ * @since 2.1.0
+ */
+export declare function resolveWithDebug(props: MultiLevelProps): ResolutionResult;
+/**
+ * Quick resolve from intent and optional mood.
+ *
+ * @param intent - Semantic intent
+ * @param mood - Optional mood modifier
+ * @returns Factor24Config
+ * @since 2.1.0
+ */
+export declare function resolveIntent(intent: SemanticIntent, mood?: SemanticMood): Factor24Config;
+/**
+ * Quick resolve from shorthands.
+ *
+ * @param shorthands - Shorthand props
+ * @returns Factor24Config
+ * @since 2.1.0
+ */
+export declare function resolveShorthands(shorthands: ShorthandProps): Factor24Config;
+/**
+ * Get all available intents.
+ *
+ * @returns Array of intent definitions
+ * @since 2.1.0
+ */
+export declare function getAllIntents(): IntentDefinition[];
+/**
+ * Get all available moods.
+ *
+ * @returns Array of mood definitions
+ * @since 2.1.0
+ */
+export declare function getAllMoods(): MoodModifierDefinition[];
+/**
+ * Get intent definition by ID.
+ *
+ * @param id - Intent ID
+ * @returns Intent definition or undefined
+ * @since 2.1.0
+ */
+export declare function getIntent(id: SemanticIntent): IntentDefinition | undefined;
+/**
+ * Get mood definition by ID.
+ *
+ * @param id - Mood ID
+ * @returns Mood definition or undefined
+ * @since 2.1.0
+ */
+export declare function getMood(id: SemanticMood): MoodModifierDefinition | undefined;
+//# sourceMappingURL=resolveProps.d.ts.map

package/dist/resolution/shorthand/feel-mappings.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Feel Mappings - Shorthand for Interaction Behavior
+ *
+ * Maps FeelShorthand values to Factor24Config.
+ * Controls animation timing, transitions, and interactive feedback.
+ *
+ * @packageDocumentation
+ * @module resolution/shorthand/feel-mappings
+ * @since 2.1.0
+ *
+ * Powered by Nikkory
+ */
+import type { Factor24Config, FeelShorthand } from '../types';
+/**
+ * Feel shorthand to Factor24Config mappings.
+ *
+ * @since 2.1.0
+ */
+export declare const FEEL_MAPPINGS: Record<FeelShorthand, Partial<Factor24Config>>;
+/**
+ * Expand feel shorthand to Factor24Config.
+ *
+ * @param feel - The feel shorthand value
+ * @returns Partial Factor24Config with feel-related factors
+ *
+ * @example
+ * ```typescript
+ * const config = expandFeel('snappy');
+ * // Result: { animation: 'standard', transition: 'fast', cursor: 'pointer' }
+ * ```
+ *
+ * @since 2.1.0
+ */
+export declare function expandFeel(feel: FeelShorthand): Partial<Factor24Config>;
+/**
+ * All valid feel shorthand values.
+ *
+ * @since 2.1.0
+ */
+export declare const VALID_FEEL_VALUES: ReadonlyArray<FeelShorthand>;
+/**
+ * Check if a value is a valid feel shorthand.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a valid feel shorthand
+ * @since 2.1.0
+ */
+export declare function isValidFeel(value: unknown): value is FeelShorthand;
+/**
+ * Get all available feel values with their descriptions.
+ *
+ * @returns Array of feel values with descriptions
+ * @since 2.1.0
+ */
+export declare function getFeelDescriptions(): Array<{
+    value: FeelShorthand;
+    description: string;
+}>;
+/**
+ * Get the animation speed of a feel (in milliseconds).
+ *
+ * @param feel - The feel shorthand
+ * @returns Animation duration in milliseconds
+ * @since 2.1.0
+ */
+export declare function getFeelDuration(feel: FeelShorthand): number;
+/**
+ * Get the energy level of a feel (1-5 scale).
+ *
+ * @param feel - The feel shorthand
+ * @returns Energy level from 1 (calm) to 5 (energetic)
+ * @since 2.1.0
+ */
+export declare function getFeelEnergy(feel: FeelShorthand): number;
+/**
+ * Check if a feel has animations enabled.
+ *
+ * @param feel - The feel shorthand
+ * @returns True if the feel includes animations
+ * @since 2.1.0
+ */
+export declare function hasAnimations(feel: FeelShorthand): boolean;
+/**
+ * Check if a feel supports reduced motion.
+ * Static feel is considered reduced motion friendly.
+ *
+ * @param feel - The feel shorthand
+ * @returns True if the feel respects reduced motion
+ * @since 2.1.0
+ */
+export declare function supportsReducedMotion(feel: FeelShorthand): boolean;
+/**
+ * Get the reduced motion alternative for a feel.
+ *
+ * @param feel - The current feel
+ * @returns A reduced motion friendly feel
+ * @since 2.1.0
+ */
+export declare function getReducedMotionAlternative(feel: FeelShorthand): FeelShorthand;
+/**
+ * Find the best feel for a given energy level.
+ *
+ * @param energy - Target energy level (1-5)
+ * @returns The most appropriate feel shorthand
+ * @since 2.1.0
+ */
+export declare function getFeelForEnergy(energy: number): FeelShorthand;
+/**
+ * Get the CSS easing function for a feel.
+ *
+ * @param feel - The feel shorthand
+ * @returns CSS easing function string
+ * @since 2.1.0
+ */
+export declare function getFeelEasing(feel: FeelShorthand): string;
+/**
+ * Check if a feel is interactive (has cursor: pointer).
+ *
+ * @param feel - The feel shorthand
+ * @returns True if the feel is interactive
+ * @since 2.1.0
+ */
+export declare function isInteractive(feel: FeelShorthand): boolean;
+/**
+ * Get a calmer feel for the given feel.
+ *
+ * @param feel - The current feel
+ * @returns A calmer feel shorthand
+ * @since 2.1.0
+ */
+export declare function getCalmerFeel(feel: FeelShorthand): FeelShorthand;
+/**
+ * Get a more energetic feel for the given feel.
+ *
+ * @param feel - The current feel
+ * @returns A more energetic feel shorthand
+ * @since 2.1.0
+ */
+export declare function getMoreEnergeticFeel(feel: FeelShorthand): FeelShorthand;
+//# sourceMappingURL=feel-mappings.d.ts.map

package/dist/resolution/shorthand/index.d.ts

@@ -0,0 +1,172 @@
+/**
+ * Shorthand Mappings - Level 3 Abstraction
+ *
+ * Provides shorthand props that map to multiple Factor24 properties.
+ * Each shorthand represents a conceptual grouping of factors.
+ *
+ * Shorthands:
+ * - look: Visual appearance (bold, subtle, minimal, etc.)
+ * - feel: Interaction behavior (snappy, smooth, bouncy, etc.)
+ * - surface: Background and elevation (flat, raised, floating, etc.)
+ * - spacing: Internal spacing (tight, normal, relaxed, loose)
+ *
+ * @packageDocumentation
+ * @module resolution/shorthand
+ * @since 2.1.0
+ *
+ * Powered by Nikkory
+ */
+export * from './look-mappings';
+export * from './feel-mappings';
+export * from './surface-mappings';
+export * from './spacing-mappings';
+import type { Factor24Config, LookShorthand, FeelShorthand, SurfaceShorthand, SpacingShorthand, ShorthandMappings } from '../types';
+/**
+ * Shorthand props that can be expanded to Factor24Config.
+ *
+ * @since 2.1.0
+ */
+export interface ShorthandProps {
+    /** Visual appearance shorthand */
+    look?: LookShorthand;
+    /** Interaction feel shorthand */
+    feel?: FeelShorthand;
+    /** Surface/elevation shorthand */
+    surface?: SurfaceShorthand;
+    /** Spacing shorthand */
+    spacingPreset?: SpacingShorthand;
+}
+/**
+ * Expand all shorthands to Factor24Config.
+ * Merges all shorthand configurations into a single partial config.
+ *
+ * @param shorthands - The shorthand props to expand
+ * @returns Partial Factor24Config with all shorthand factors
+ *
+ * @example
+ * ```typescript
+ * const config = expandShorthands({
+ *   look: 'bold',
+ *   feel: 'snappy',
+ *   surface: 'raised',
+ *   spacingPreset: 'normal',
+ * });
+ * ```
+ *
+ * @since 2.1.0
+ */
+export declare function expandShorthands(shorthands: ShorthandProps): Partial<Factor24Config>;
+/**
+ * Complete shorthand mappings collection.
+ *
+ * @since 2.1.0
+ */
+export declare const ALL_SHORTHAND_MAPPINGS: ShorthandMappings;
+/**
+ * Validation result for shorthands.
+ *
+ * @since 2.1.0
+ */
+export interface ShorthandValidationResult {
+    /** Overall validation status */
+    valid: boolean;
+    /** Errors by shorthand */
+    errors: {
+        look: string[];
+        feel: string[];
+        surface: string[];
+        spacingPreset: string[];
+    };
+    /** All errors flattened */
+    allErrors: string[];
+}
+/**
+ * Validate all shorthand props.
+ *
+ * @param shorthands - The shorthand props to validate
+ * @returns Validation result with errors by shorthand
+ *
+ * @example
+ * ```typescript
+ * const result = validateShorthands({
+ *   look: 'invalid',
+ * });
+ * if (!result.valid) {
+ *   console.error(result.allErrors);
+ * }
+ * ```
+ *
+ * @since 2.1.0
+ */
+export declare function validateShorthands(shorthands: ShorthandProps): ShorthandValidationResult;
+/**
+ * Check if an object contains any shorthand properties.
+ *
+ * @param obj - Object to check
+ * @returns True if object has shorthand properties
+ * @since 2.1.0
+ */
+export declare function hasShorthandProps(obj: Record<string, unknown>): boolean;
+/**
+ * Extract shorthand props from an object.
+ *
+ * @param obj - Object to extract from
+ * @returns Extracted shorthand props
+ * @since 2.1.0
+ */
+export declare function extractShorthandProps(obj: Record<string, unknown>): ShorthandProps;
+/**
+ * Detect which shorthands are present in an object.
+ *
+ * @param obj - Object to check
+ * @returns Object indicating which shorthands are present
+ * @since 2.1.0
+ */
+export declare function detectShorthands(obj: Record<string, unknown>): {
+    hasLook: boolean;
+    hasFeel: boolean;
+    hasSurface: boolean;
+    hasSpacing: boolean;
+};
+/**
+ * All shorthand names.
+ *
+ * @since 2.1.0
+ */
+export declare const SHORTHAND_NAMES: readonly ["look", "feel", "surface", "spacingPreset"];
+/**
+ * Shorthand name type.
+ *
+ * @since 2.1.0
+ */
+export type ShorthandName = (typeof SHORTHAND_NAMES)[number];
+/**
+ * Map of shorthand names to their possible values.
+ *
+ * @since 2.1.0
+ */
+export declare const SHORTHAND_VALUES: Record<ShorthandName, ReadonlyArray<string>>;
+/**
+ * Common shorthand combinations for quick use.
+ *
+ * @since 2.1.0
+ */
+export declare const SHORTHAND_PRESETS: Record<string, ShorthandProps>;
+/**
+ * Get a predefined shorthand preset by name.
+ *
+ * @param presetName - The name of the preset
+ * @returns The shorthand props or undefined
+ * @since 2.1.0
+ */
+export declare function getShorthandPreset(presetName: string): ShorthandProps | undefined;
+/**
+ * Merge multiple ShorthandProps configurations.
+ * Later values override earlier ones.
+ *
+ * @param propsList - Shorthand props to merge
+ * @returns Merged shorthand props
+ * @since 2.1.0
+ */
+export declare function mergeShorthandProps(...propsList: ShorthandProps[]): ShorthandProps;
+//# sourceMappingURL=index.d.ts.map

package/dist/resolution/shorthand/look-mappings.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Look Mappings - Shorthand for Visual Appearance
+ *
+ * Maps LookShorthand values to Factor24Config.
+ * Controls visual weight, contrast, and overall appearance.
+ *
+ * @packageDocumentation
+ * @module resolution/shorthand/look-mappings
+ * @since 2.1.0
+ *
+ * Powered by Nikkory
+ */
+import type { Factor24Config, LookShorthand } from '../types';
+/**
+ * Look shorthand to Factor24Config mappings.
+ *
+ * @since 2.1.0
+ */
+export declare const LOOK_MAPPINGS: Record<LookShorthand, Partial<Factor24Config>>;
+/**
+ * Expand look shorthand to Factor24Config.
+ *
+ * @param look - The look shorthand value
+ * @returns Partial Factor24Config with look-related factors
+ *
+ * @example
+ * ```typescript
+ * const config = expandLook('bold');
+ * // Result: { variant: 'filled', elevation: 'md', opacity: 'full', ... }
+ * ```
+ *
+ * @since 2.1.0
+ */
+export declare function expandLook(look: LookShorthand): Partial<Factor24Config>;
+/**
+ * All valid look shorthand values.
+ *
+ * @since 2.1.0
+ */
+export declare const VALID_LOOK_VALUES: ReadonlyArray<LookShorthand>;
+/**
+ * Check if a value is a valid look shorthand.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a valid look shorthand
+ * @since 2.1.0
+ */
+export declare function isValidLook(value: unknown): value is LookShorthand;
+/**
+ * Get all available look values with their descriptions.
+ *
+ * @returns Array of look values with descriptions
+ * @since 2.1.0
+ */
+export declare function getLookDescriptions(): Array<{
+    value: LookShorthand;
+    description: string;
+}>;
+/**
+ * Get the dominant visual characteristic of a look.
+ *
+ * @param look - The look shorthand
+ * @returns The dominant characteristic
+ * @since 2.1.0
+ */
+export declare function getLookCharacteristic(look: LookShorthand): 'elevation' | 'border' | 'opacity' | 'shape';
+/**
+ * Get the visual weight of a look (1-5 scale).
+ *
+ * @param look - The look shorthand
+ * @returns Visual weight from 1 (lightest) to 5 (heaviest)
+ * @since 2.1.0
+ */
+export declare function getLookWeight(look: LookShorthand): number;
+/**
+ * Find the best look for a given visual weight.
+ *
+ * @param weight - Target visual weight (1-5)
+ * @returns The most appropriate look shorthand
+ * @since 2.1.0
+ */
+export declare function getLookForWeight(weight: number): LookShorthand;
+/**
+ * Check if a look has visible borders.
+ *
+ * @param look - The look shorthand
+ * @returns True if the look includes visible borders
+ * @since 2.1.0
+ */
+export declare function hasVisibleBorder(look: LookShorthand): boolean;
+/**
+ * Check if a look has elevation/shadow.
+ *
+ * @param look - The look shorthand
+ * @returns True if the look includes elevation
+ * @since 2.1.0
+ */
+export declare function hasElevation(look: LookShorthand): boolean;
+/**
+ * Get a contrasting look for the given look.
+ *
+ * @param look - The current look
+ * @returns A contrasting look shorthand
+ * @since 2.1.0
+ */
+export declare function getContrastingLook(look: LookShorthand): LookShorthand;
+//# sourceMappingURL=look-mappings.d.ts.map