@nikkory/vibe-engine 4.0.0

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

@@ -0,0 +1,164 @@
+/**
+ * Spacing Mappings - Shorthand for Internal Spacing
+ *
+ * Maps SpacingShorthand values to Factor24Config.
+ * Controls padding, gaps, and overall density.
+ *
+ * @packageDocumentation
+ * @module resolution/shorthand/spacing-mappings
+ * @since 2.1.0
+ *
+ * Powered by Nikkory
+ */
+import type { Factor24Config, SpacingShorthand } from '../types';
+/**
+ * Spacing shorthand to Factor24Config mappings.
+ *
+ * @since 2.1.0
+ */
+export declare const SPACING_MAPPINGS: Record<SpacingShorthand, Partial<Factor24Config>>;
+/**
+ * Expand spacing shorthand to Factor24Config.
+ *
+ * @param spacing - The spacing shorthand value
+ * @returns Partial Factor24Config with spacing-related factors
+ *
+ * @example
+ * ```typescript
+ * const config = expandSpacingShorthand('tight');
+ * // Result: { spacing: 'xs', density: 'compact' }
+ * ```
+ *
+ * @since 2.1.0
+ */
+export declare function expandSpacingShorthand(spacing: SpacingShorthand): Partial<Factor24Config>;
+/**
+ * All valid spacing shorthand values.
+ *
+ * @since 2.1.0
+ */
+export declare const VALID_SPACING_SHORTHAND_VALUES: ReadonlyArray<SpacingShorthand>;
+/**
+ * Check if a value is a valid spacing shorthand.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a valid spacing shorthand
+ * @since 2.1.0
+ */
+export declare function isValidSpacingShorthand(value: unknown): value is SpacingShorthand;
+/**
+ * Get all available spacing values with their descriptions.
+ *
+ * @returns Array of spacing values with descriptions
+ * @since 2.1.0
+ */
+export declare function getSpacingDescriptions(): Array<{
+    value: SpacingShorthand;
+    description: string;
+}>;
+/**
+ * Get the spacing multiplier for a shorthand.
+ *
+ * @param spacing - The spacing shorthand
+ * @returns Spacing multiplier (0.5-2.0)
+ * @since 2.1.0
+ */
+export declare function getSpacingMultiplier(spacing: SpacingShorthand): number;
+/**
+ * Get the base spacing value in rem.
+ *
+ * @param spacing - The spacing shorthand
+ * @returns Spacing value in rem
+ * @since 2.1.0
+ */
+export declare function getSpacingValue(spacing: SpacingShorthand): string;
+/**
+ * Get padding CSS value for a spacing shorthand.
+ *
+ * @param spacing - The spacing shorthand
+ * @returns CSS padding value
+ * @since 2.1.0
+ */
+export declare function getPaddingValue(spacing: SpacingShorthand): string;
+/**
+ * Get gap CSS value for a spacing shorthand.
+ *
+ * @param spacing - The spacing shorthand
+ * @returns CSS gap value
+ * @since 2.1.0
+ */
+export declare function getGapValue(spacing: SpacingShorthand): string;
+/**
+ * Get the density level (1-4 scale).
+ *
+ * @param spacing - The spacing shorthand
+ * @returns Density level from 1 (compact) to 4 (loose)
+ * @since 2.1.0
+ */
+export declare function getDensityLevel(spacing: SpacingShorthand): number;
+/**
+ * Find the best spacing for a given density level.
+ *
+ * @param level - Target density level (1-4)
+ * @returns The most appropriate spacing shorthand
+ * @since 2.1.0
+ */
+export declare function getSpacingForDensity(level: number): SpacingShorthand;
+/**
+ * Get a tighter spacing for the given spacing.
+ *
+ * @param spacing - The current spacing
+ * @returns A tighter spacing shorthand
+ * @since 2.1.0
+ */
+export declare function getTighterSpacing(spacing: SpacingShorthand): SpacingShorthand;
+/**
+ * Get a looser spacing for the given spacing.
+ *
+ * @param spacing - The current spacing
+ * @returns A looser spacing shorthand
+ * @since 2.1.0
+ */
+export declare function getLooserSpacing(spacing: SpacingShorthand): SpacingShorthand;
+/**
+ * Check if spacing is considered compact.
+ *
+ * @param spacing - The spacing shorthand
+ * @returns True if spacing is compact (tight)
+ * @since 2.1.0
+ */
+export declare function isCompactSpacing(spacing: SpacingShorthand): boolean;
+/**
+ * Check if spacing is considered comfortable.
+ *
+ * @param spacing - The spacing shorthand
+ * @returns True if spacing is comfortable (relaxed or loose)
+ * @since 2.1.0
+ */
+export declare function isComfortableSpacing(spacing: SpacingShorthand): boolean;
+/**
+ * Get inline spacing value (horizontal).
+ *
+ * @param spacing - The spacing shorthand
+ * @returns CSS inline spacing value
+ * @since 2.1.0
+ */
+export declare function getInlineSpacing(spacing: SpacingShorthand): string;
+/**
+ * Get block spacing value (vertical).
+ *
+ * @param spacing - The spacing shorthand
+ * @returns CSS block spacing value
+ * @since 2.1.0
+ */
+export declare function getBlockSpacing(spacing: SpacingShorthand): string;
+/**
+ * Calculate responsive spacing based on viewport.
+ *
+ * @param spacing - The spacing shorthand
+ * @param viewport - Viewport size ('sm' | 'md' | 'lg')
+ * @returns Adjusted spacing shorthand
+ * @since 2.1.0
+ */
+export declare function getResponsiveSpacing(spacing: SpacingShorthand, viewport: 'sm' | 'md' | 'lg'): SpacingShorthand;
+//# sourceMappingURL=spacing-mappings.d.ts.map

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

@@ -0,0 +1,139 @@
+/**
+ * Surface Mappings - Shorthand for Background and Elevation
+ *
+ * Maps SurfaceShorthand values to Factor24Config.
+ * Controls depth perception, layering, and visual hierarchy.
+ *
+ * @packageDocumentation
+ * @module resolution/shorthand/surface-mappings
+ * @since 2.1.0
+ *
+ * Powered by Nikkory
+ */
+import type { Factor24Config, SurfaceShorthand } from '../types';
+/**
+ * Surface shorthand to Factor24Config mappings.
+ *
+ * @since 2.1.0
+ */
+export declare const SURFACE_MAPPINGS: Record<SurfaceShorthand, Partial<Factor24Config>>;
+/**
+ * Expand surface shorthand to Factor24Config.
+ *
+ * @param surface - The surface shorthand value
+ * @returns Partial Factor24Config with surface-related factors
+ *
+ * @example
+ * ```typescript
+ * const config = expandSurface('floating');
+ * // Result: { elevation: 'xl', border: 'none', opacity: 'full', zIndex: 'sticky' }
+ * ```
+ *
+ * @since 2.1.0
+ */
+export declare function expandSurface(surface: SurfaceShorthand): Partial<Factor24Config>;
+/**
+ * All valid surface shorthand values.
+ *
+ * @since 2.1.0
+ */
+export declare const VALID_SURFACE_VALUES: ReadonlyArray<SurfaceShorthand>;
+/**
+ * Check if a value is a valid surface shorthand.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a valid surface shorthand
+ * @since 2.1.0
+ */
+export declare function isValidSurface(value: unknown): value is SurfaceShorthand;
+/**
+ * Get all available surface values with their descriptions.
+ *
+ * @returns Array of surface values with descriptions
+ * @since 2.1.0
+ */
+export declare function getSurfaceDescriptions(): Array<{
+    value: SurfaceShorthand;
+    description: string;
+}>;
+/**
+ * Get the depth level of a surface (0-4 scale).
+ *
+ * @param surface - The surface shorthand
+ * @returns Depth level from 0 (sunken) to 4 (floating)
+ * @since 2.1.0
+ */
+export declare function getSurfaceDepth(surface: SurfaceShorthand): number;
+/**
+ * Check if a surface has elevation (shadow).
+ *
+ * @param surface - The surface shorthand
+ * @returns True if the surface has elevation
+ * @since 2.1.0
+ */
+export declare function hasSurfaceElevation(surface: SurfaceShorthand): boolean;
+/**
+ * Check if a surface creates an overlay (blocks content below).
+ *
+ * @param surface - The surface shorthand
+ * @returns True if the surface is an overlay
+ * @since 2.1.0
+ */
+export declare function isOverlaySurface(surface: SurfaceShorthand): boolean;
+/**
+ * Get the z-index value for a surface.
+ *
+ * @param surface - The surface shorthand
+ * @returns Numeric z-index value
+ * @since 2.1.0
+ */
+export declare function getSurfaceZIndex(surface: SurfaceShorthand): number;
+/**
+ * Find the best surface for a given depth level.
+ *
+ * @param depth - Target depth level (0-4)
+ * @returns The most appropriate surface shorthand
+ * @since 2.1.0
+ */
+export declare function getSurfaceForDepth(depth: number): SurfaceShorthand;
+/**
+ * Get a lower surface (less elevated) for the given surface.
+ *
+ * @param surface - The current surface
+ * @returns A lower surface shorthand
+ * @since 2.1.0
+ */
+export declare function getLowerSurface(surface: SurfaceShorthand): SurfaceShorthand;
+/**
+ * Get a higher surface (more elevated) for the given surface.
+ *
+ * @param surface - The current surface
+ * @returns A higher surface shorthand
+ * @since 2.1.0
+ */
+export declare function getHigherSurface(surface: SurfaceShorthand): SurfaceShorthand;
+/**
+ * Get the CSS box-shadow value for a surface.
+ *
+ * @param surface - The surface shorthand
+ * @returns CSS box-shadow value
+ * @since 2.1.0
+ */
+export declare function getSurfaceShadow(surface: SurfaceShorthand): string;
+/**
+ * Check if content below this surface should be dimmed.
+ *
+ * @param surface - The surface shorthand
+ * @returns True if a backdrop should be shown
+ * @since 2.1.0
+ */
+export declare function needsBackdrop(surface: SurfaceShorthand): boolean;
+/**
+ * Get appropriate aria role for surface.
+ *
+ * @param surface - The surface shorthand
+ * @returns ARIA role or undefined
+ * @since 2.1.0
+ */
+export declare function getSurfaceRole(surface: SurfaceShorthand): string | undefined;
+//# sourceMappingURL=surface-mappings.d.ts.map

package/dist/resolution/standard/groups-standard.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Groups Resolution - Standard Tier (Pattern A+a)
+ *
+ * Adds validation on top of core group expansion.
+ * Validates groups before expanding, returns config with validation result.
+ * Used by standard tier components.
+ *
+ * @composition Standard = A + a (core + validation)
+ *
+ * @packageDocumentation
+ * @module resolution/standard/groups-standard
+ * @since 3.0.0
+ *
+ * Powered by Nikkory
+ */
+import type { Factor24Config, VisualGroup, MotionGroup, LayoutGroup, ExperienceGroup, FactorGroups, MultiLevelProps } from '../core/types-core';
+/**
+ * Standard result with validation.
+ * @since 3.0.0
+ */
+export interface StandardGroupResult {
+    readonly config: Partial<Factor24Config>;
+    readonly valid: boolean;
+    readonly errors: readonly string[];
+    readonly warnings?: readonly string[];
+}
+/**
+ * Expand visual group to Factor24Config (standard tier).
+ * Adds validation before calling core.
+ *
+ * @param visual - The visual group to expand
+ * @returns Config with validation result
+ * @since 3.0.0
+ */
+export declare function expandVisualGroup(visual: VisualGroup): StandardGroupResult;
+/**
+ * Expand motion group to Factor24Config (standard tier).
+ * Adds validation before calling core.
+ *
+ * @param motion - The motion group to expand
+ * @returns Config with validation result
+ * @since 3.0.0
+ */
+export declare function expandMotionGroup(motion: MotionGroup): StandardGroupResult;
+/**
+ * Expand layout group to Factor24Config (standard tier).
+ * Adds validation before calling core.
+ *
+ * @param layout - The layout group to expand
+ * @returns Config with validation result
+ * @since 3.0.0
+ */
+export declare function expandLayoutGroup(layout: LayoutGroup): StandardGroupResult;
+/**
+ * Expand experience group to Factor24Config (standard tier).
+ * Adds validation before calling core.
+ *
+ * @param experience - The experience group to expand
+ * @returns Config with validation result
+ * @since 3.0.0
+ */
+export declare function expandExperienceGroup(experience: ExperienceGroup): StandardGroupResult;
+/**
+ * Expand all groups to Factor24Config (standard tier).
+ * Adds validation before calling core.
+ *
+ * @param groups - The factor groups to expand
+ * @returns Config with validation result
+ * @since 3.0.0
+ */
+export declare function expandGroups(groups: FactorGroups): StandardGroupResult;
+/**
+ * Merge multiple FactorGroups (standard tier).
+ * Adds validation before calling core.
+ *
+ * @param groups - Groups to merge
+ * @returns Merged groups with validation
+ * @since 3.0.0
+ */
+export declare function mergeFactorGroups(...groups: Array<FactorGroups | undefined>): {
+    readonly groups: FactorGroups;
+    readonly valid: boolean;
+    readonly errors: readonly string[];
+};
+/**
+ * Extract all groups from MultiLevelProps (standard tier).
+ * Adds validation after extraction.
+ *
+ * @param props - The multi-level props
+ * @returns Extracted groups with validation
+ * @since 3.0.0
+ */
+export declare function extractAllGroups(props: MultiLevelProps): {
+    readonly groups: FactorGroups;
+    readonly valid: boolean;
+    readonly errors: readonly string[];
+};
+//# sourceMappingURL=groups-standard.d.ts.map

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

@@ -0,0 +1,28 @@
+/**
+ * Resolution Standard Tier - Barrel Export
+ *
+ * Central export point for standard tier resolution modules.
+ * Core logic + validation (A+a pattern).
+ *
+ * @composition Standard = A + a (core + validation)
+ *
+ * @packageDocumentation
+ * @module resolution/standard
+ * @since 3.0.0
+ *
+ * Powered by Nikkory
+ */
+export type { Factor24Config, MultiLevelProps, SemanticIntent, SemanticMood, IntentDefinition, MoodModifierDefinition, PresetDefinition, LookShorthand, FeelShorthand, SurfaceShorthand, SpacingShorthand, VisualGroup, MotionGroup, LayoutGroup, ExperienceGroup, FactorGroups, } from '../core/types-core';
+export type { ValidationResult } from './validators';
+export { validationSuccess, validationFailure, validateFactor24Config, validateVisualGroup, validateMotionGroup, validateLayoutGroup, validateExperienceGroup, validateFactorGroups, validateShorthands, validatePresetDefinition, validatePresetId, validateIntentDefinition, validateMoodDefinition, validateIntentId, validateMoodId, } from './validators';
+export type { StandardGroupResult } from './groups-standard';
+export { expandVisualGroup, expandMotionGroup, expandLayoutGroup, expandExperienceGroup, expandGroups, mergeFactorGroups, extractAllGroups, } from './groups-standard';
+export type { StandardShorthandResult, ShorthandProps } from './shorthands-standard';
+export { LOOK_MAPPINGS, FEEL_MAPPINGS, SURFACE_MAPPINGS, SPACING_MAPPINGS, expandLook, expandFeel, expandSurface, expandSpacingShorthand, expandShorthands, } from './shorthands-standard';
+export type { PresetRegistrationResult, PresetResolutionResult } from './presets-standard';
+export { PRESET_STORAGE, registerPreset, registerPresets, resolvePreset, hasPreset, unregisterPreset, clearPresets, getAllPresetIds, getPresetCount, getAllPresetConfigs, } from './presets-standard';
+export type { IntentRegistrationResult, IntentResolutionResult } from './intents-standard';
+export { INTENT_STORAGE, MOOD_STORAGE, registerIntent, registerIntents, registerMood, registerMoods, resolveIntent, resolveMood, hasIntent, hasMood, applyMood, resolveIntentWithMood, unregisterIntent, unregisterMood, clearIntents, clearMoods, getAllIntentIds, getAllMoodIds, getIntentCount, getMoodCount, getAllIntentConfigs, getAllMoodAdjustments, } from './intents-standard';
+export type { StandardResolutionResult, LevelDetectionResult } from './resolver-standard';
+export { extractLevel1Factors, extractLevel2Groups, extractLevel3Shorthands, extractLevel4Preset, extractLevel5Intent, mergeConfigs, resolveProps, detectLevels, } from './resolver-standard';
+//# sourceMappingURL=index.d.ts.map

package/dist/resolution/standard/intents-standard.d.ts

@@ -0,0 +1,232 @@
+/**
+ * Intents Resolution - Standard Tier (Pattern A+a)
+ *
+ * Adds validation on top of core intent resolution.
+ * Validates intents and moods before registration and resolution.
+ * Used by standard tier components.
+ *
+ * @composition Standard = A + a (core + validation)
+ *
+ * @packageDocumentation
+ * @module resolution/standard/intents-standard
+ * @since 3.0.0
+ *
+ * Powered by Nikkory
+ */
+import type { Factor24Config, IntentDefinition, MoodModifierDefinition, SemanticIntent, SemanticMood } from '../core/types-core';
+/**
+ * Intent storage (standard tier).
+ * @since 3.0.0
+ */
+export declare const INTENT_STORAGE: Map<SemanticIntent, Partial<Factor24Config>>;
+/**
+ * Mood storage (standard tier).
+ * @since 3.0.0
+ */
+export declare const MOOD_STORAGE: Map<SemanticMood, Partial<Factor24Config>>;
+/**
+ * Standard intent/mood registration result.
+ * @since 3.0.0
+ */
+export interface IntentRegistrationResult {
+    readonly success: boolean;
+    readonly errors: readonly string[];
+}
+/**
+ * Standard intent/mood resolution result.
+ * @since 3.0.0
+ */
+export interface IntentResolutionResult {
+    readonly config?: Partial<Factor24Config>;
+    readonly valid: boolean;
+    readonly errors: readonly string[];
+}
+/**
+ * Register an intent (standard tier).
+ * Adds validation before calling core.
+ *
+ * @param intent - The intent definition to register
+ * @returns Registration result with validation
+ * @since 3.0.0
+ */
+export declare function registerIntent(intent: IntentDefinition): IntentRegistrationResult;
+/**
+ * Register multiple intents (standard tier).
+ * Adds validation before calling core.
+ *
+ * @param intents - Array of intent definitions to register
+ * @returns Registration result with validation
+ * @since 3.0.0
+ */
+export declare function registerIntents(intents: ReadonlyArray<IntentDefinition | undefined>): IntentRegistrationResult;
+/**
+ * Register a mood modifier (standard tier).
+ * Adds validation before calling core.
+ *
+ * @param mood - The mood definition to register
+ * @returns Registration result with validation
+ * @since 3.0.0
+ */
+export declare function registerMood(mood: MoodModifierDefinition): IntentRegistrationResult;
+/**
+ * Register multiple moods (standard tier).
+ * Adds validation before calling core.
+ *
+ * @param moods - Array of mood definitions to register
+ * @returns Registration result with validation
+ * @since 3.0.0
+ */
+export declare function registerMoods(moods: ReadonlyArray<MoodModifierDefinition | undefined>): IntentRegistrationResult;
+/**
+ * Resolve an intent ID to Factor24Config (standard tier).
+ * Adds validation before calling core.
+ *
+ * @param intentId - The intent ID to resolve
+ * @returns Resolution result with validation
+ * @since 3.0.0
+ */
+export declare function resolveIntent(intentId: SemanticIntent): IntentResolutionResult;
+/**
+ * Resolve a mood ID to its adjustments (standard tier).
+ * Adds validation before calling core.
+ *
+ * @param moodId - The mood ID to resolve
+ * @returns Resolution result with validation
+ * @since 3.0.0
+ */
+export declare function resolveMood(moodId: SemanticMood): IntentResolutionResult;
+/**
+ * Check if an intent exists (standard tier).
+ * Adds validation before calling core.
+ *
+ * @param intentId - The intent ID to check
+ * @returns True if intent exists, with validation
+ * @since 3.0.0
+ */
+export declare function hasIntent(intentId: SemanticIntent): {
+    readonly exists: boolean;
+    readonly valid: boolean;
+    readonly errors: readonly string[];
+};
+/**
+ * Check if a mood exists (standard tier).
+ * Adds validation before calling core.
+ *
+ * @param moodId - The mood ID to check
+ * @returns True if mood exists, with validation
+ * @since 3.0.0
+ */
+export declare function hasMood(moodId: SemanticMood): {
+    readonly exists: boolean;
+    readonly valid: boolean;
+    readonly errors: readonly string[];
+};
+/**
+ * Apply mood adjustments to a base config (standard tier).
+ * Simple wrapper - delegates to core (configs already validated).
+ *
+ * @param baseConfig - The base configuration
+ * @param moodAdjustments - The mood adjustments to apply
+ * @returns Merged configuration
+ * @since 3.0.0
+ */
+export declare function applyMood(baseConfig: Partial<Factor24Config>, moodAdjustments: Partial<Factor24Config>): Partial<Factor24Config>;
+/**
+ * Resolve intent with mood application (standard tier).
+ * Adds validation before calling core.
+ *
+ * @param intentId - The intent ID to resolve
+ * @param moodId - The mood ID to apply (optional)
+ * @returns Resolution result with validation
+ * @since 3.0.0
+ */
+export declare function resolveIntentWithMood(intentId: SemanticIntent, moodId?: SemanticMood): IntentResolutionResult;
+/**
+ * Remove an intent (standard tier).
+ * Adds validation before calling core.
+ *
+ * @param intentId - The intent ID to remove
+ * @returns True if intent was removed, with validation
+ * @since 3.0.0
+ */
+export declare function unregisterIntent(intentId: SemanticIntent): {
+    readonly removed: boolean;
+    readonly valid: boolean;
+    readonly errors: readonly string[];
+};
+/**
+ * Remove a mood (standard tier).
+ * Adds validation before calling core.
+ *
+ * @param moodId - The mood ID to remove
+ * @returns True if mood was removed, with validation
+ * @since 3.0.0
+ */
+export declare function unregisterMood(moodId: SemanticMood): {
+    readonly removed: boolean;
+    readonly valid: boolean;
+    readonly errors: readonly string[];
+};
+/**
+ * Clear all intents (standard tier).
+ * Simple wrapper - no validation needed.
+ *
+ * @since 3.0.0
+ */
+export declare function clearIntents(): void;
+/**
+ * Clear all moods (standard tier).
+ * Simple wrapper - no validation needed.
+ *
+ * @since 3.0.0
+ */
+export declare function clearMoods(): void;
+/**
+ * Get all intent IDs (standard tier).
+ * Simple wrapper - no validation needed.
+ *
+ * @returns Array of all registered intent IDs
+ * @since 3.0.0
+ */
+export declare function getAllIntentIds(): SemanticIntent[];
+/**
+ * Get all mood IDs (standard tier).
+ * Simple wrapper - no validation needed.
+ *
+ * @returns Array of all registered mood IDs
+ * @since 3.0.0
+ */
+export declare function getAllMoodIds(): SemanticMood[];
+/**
+ * Get total intent count (standard tier).
+ * Simple wrapper - no validation needed.
+ *
+ * @returns Total number of registered intents
+ * @since 3.0.0
+ */
+export declare function getIntentCount(): number;
+/**
+ * Get total mood count (standard tier).
+ * Simple wrapper - no validation needed.
+ *
+ * @returns Total number of registered moods
+ * @since 3.0.0
+ */
+export declare function getMoodCount(): number;
+/**
+ * Get all intent configs (standard tier).
+ * Simple wrapper - no validation needed.
+ *
+ * @returns Array of all intent configs
+ * @since 3.0.0
+ */
+export declare function getAllIntentConfigs(): Array<Partial<Factor24Config>>;
+/**
+ * Get all mood adjustment configs (standard tier).
+ * Simple wrapper - no validation needed.
+ *
+ * @returns Array of all mood adjustment configs
+ * @since 3.0.0
+ */
+export declare function getAllMoodAdjustments(): Array<Partial<Factor24Config>>;
+//# sourceMappingURL=intents-standard.d.ts.map