@nikkory/vibe-engine 4.0.0

package/dist/resolution/types.d.ts

@@ -0,0 +1,461 @@
+/**
+ * Resolution Types - 5-Level Abstraction API
+ *
+ * Type definitions for the resolution system that converts high-level
+ * semantic props (intents, presets, moods) into complete 24-Factor configurations.
+ *
+ * @packageDocumentation
+ * @module resolution/types
+ * @since 2.1.0
+ *
+ * Powered by Nikkory
+ */
+import type { FactorShape, FactorPosition, FactorIconPosition, FactorState, FactorAnimation, FactorElevation, FactorA11y, FactorAlignment, FactorOrientation, FactorDensity, FactorLoadingState, FactorResponsiveConfig, FactorTheme, FactorSpacing, FactorTypography, FactorBorder, FactorOpacity, FactorOverflow, FactorCursor, FactorZIndex, FactorTransition, ComponentSize, ColorScheme } from '../styling/types';
+/**
+ * Complete 24-Factor configuration.
+ * This is the normalized output of the resolution engine.
+ *
+ * @since 2.1.0
+ */
+export interface Factor24Config {
+    /** Factor 1: Size */
+    size?: ComponentSize;
+    /** Factor 2: Variant (component-specific) */
+    variant?: string;
+    /** Factor 3: Color scheme */
+    colorScheme?: ColorScheme;
+    /** Factor 4: Shape */
+    shape?: FactorShape;
+    /** Factor 5: Position */
+    position?: FactorPosition;
+    /** Factor 6: Icon Position */
+    iconPosition?: FactorIconPosition;
+    /** Factor 7: State */
+    state?: FactorState;
+    /** Factor 8: Animation */
+    animation?: FactorAnimation;
+    /** Factor 9: Elevation */
+    elevation?: FactorElevation;
+    /** Factor 10: Accessibility */
+    a11y?: FactorA11y;
+    /** Factor 11: Justify alignment */
+    justify?: FactorAlignment;
+    /** Factor 11: Cross-axis alignment */
+    align?: FactorAlignment;
+    /** Factor 12: Orientation */
+    orientation?: FactorOrientation;
+    /** Factor 13: Density */
+    density?: FactorDensity;
+    /** Factor 14: Loading State */
+    loadingState?: FactorLoadingState;
+    /** Factor 15: Responsive config */
+    responsive?: FactorResponsiveConfig;
+    /** Factor 16: Theme */
+    theme?: FactorTheme;
+    /** Factor 17: Spacing */
+    spacing?: FactorSpacing;
+    /** Factor 18: Typography */
+    typography?: FactorTypography;
+    /** Factor 19: Border */
+    border?: FactorBorder;
+    /** Factor 20: Opacity */
+    opacity?: FactorOpacity;
+    /** Factor 21: Overflow */
+    overflow?: FactorOverflow;
+    /** Factor 22: Cursor */
+    cursor?: FactorCursor;
+    /** Factor 23: Z-Index */
+    zIndex?: FactorZIndex;
+    /** Factor 24: Transition */
+    transition?: FactorTransition;
+}
+/**
+ * Semantic intent - Highest level abstraction.
+ * Describes the PURPOSE of the component.
+ *
+ * @since 2.1.0
+ */
+export type SemanticIntent = 'cta' | 'primary' | 'secondary' | 'tertiary' | 'destructive' | 'confirm' | 'cancel' | 'nav' | 'navActive' | 'navSubtle' | 'link' | 'success' | 'warning' | 'error' | 'info' | 'ghost' | 'subtle' | 'hero' | 'premium' | 'brand' | 'inputText' | 'inputEmail' | 'inputPassword' | 'inputSearch' | 'inputCode' | 'inputNumber' | 'inputPhone' | 'inputUrl' | 'inputDate' | 'inputCurrency' | 'inputSelect' | 'inputMultiselect' | 'inputAutocomplete' | 'inputCheckbox' | 'inputSwitch' | 'inputRadio' | 'inputSlider' | 'inputRating' | 'inputTextarea' | 'inputRichtext' | 'inputError' | 'inputSuccess' | 'inputDisabled' | 'cardContent' | 'cardFeatured' | 'cardArticle' | 'cardInteractive' | 'cardSelectable' | 'cardDraggable' | 'cardProduct' | 'cardPricing' | 'cardProfile' | 'cardTestimonial' | 'cardStats' | 'cardNotification' | 'cardGlass' | 'cardNeumorphic' | 'alertInfo' | 'alertSuccess' | 'alertWarning' | 'alertError' | 'toastDefault' | 'toastSuccess' | 'toastError' | 'toastAction' | 'progressLinear' | 'progressCircular' | 'skeleton' | 'badgeDefault' | 'badgeStatus' | 'badgeCount' | 'chipDefault' | 'chipSelectable' | 'chipDeletable' | 'tooltipDefault' | 'tooltipRich';
+/**
+ * Semantic mood - Modifies the emotional tone.
+ * Adjusts animation, spacing, and visual weight.
+ *
+ * @since 2.1.0
+ */
+export type SemanticMood = 'professional' | 'friendly' | 'playful' | 'serious' | 'luxurious' | 'minimal' | 'bold';
+/**
+ * Intent definition for resolution.
+ *
+ * @since 2.1.0
+ */
+export interface IntentDefinition {
+    /** Unique intent identifier */
+    id: SemanticIntent;
+    /** Human-readable name */
+    name: string;
+    /** Description of when to use */
+    description: string;
+    /** Base 24-factor configuration */
+    config: Partial<Factor24Config>;
+    /** Mood modifiers - adjustments per mood */
+    moodModifiers?: Partial<Record<SemanticMood, Partial<Factor24Config>>>;
+    /** Compatible component types (empty = all) */
+    componentTypes?: string[];
+}
+/**
+ * Mood modifier definition.
+ *
+ * @since 2.1.0
+ */
+export interface MoodModifierDefinition {
+    /** Unique mood identifier */
+    id: SemanticMood;
+    /** Human-readable name */
+    name: string;
+    /** Description */
+    description: string;
+    /** Factor adjustments applied by this mood */
+    adjustments: Partial<Factor24Config>;
+}
+/**
+ * Preset category for organization.
+ *
+ * @since 2.1.0
+ */
+export type PresetCategory = 'button' | 'card' | 'input' | 'navigation' | 'feedback' | 'overlay' | 'dataDisplay' | 'layout' | 'form' | 'utility';
+/**
+ * Named preset definition.
+ *
+ * @since 2.1.0
+ */
+export interface PresetDefinition {
+    /** Unique preset identifier (e.g., 'hero-primary', 'form-input') */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Description of the preset's purpose */
+    description: string;
+    /** Category for organization */
+    category: PresetCategory;
+    /** Complete 24-factor configuration */
+    config: Partial<Factor24Config>;
+    /** Tags for searchability */
+    tags?: string[];
+    /** Preview image URL (optional) */
+    previewUrl?: string;
+    /** Compatible component types (empty = all) */
+    componentTypes?: string[];
+}
+/**
+ * Look shorthand - Visual appearance.
+ *
+ * @since 2.1.0
+ */
+export type LookShorthand = 'bold' | 'subtle' | 'minimal' | 'elevated' | 'outlined' | 'ghost' | 'solid' | 'soft';
+/**
+ * Feel shorthand - Interaction behavior.
+ *
+ * @since 2.1.0
+ */
+export type FeelShorthand = 'snappy' | 'smooth' | 'bouncy' | 'static' | 'responsive';
+/**
+ * Surface shorthand - Background and elevation.
+ *
+ * @since 2.1.0
+ */
+export type SurfaceShorthand = 'flat' | 'raised' | 'floating' | 'sunken' | 'overlay';
+/**
+ * Spacing shorthand - Internal spacing.
+ *
+ * @since 2.1.0
+ */
+export type SpacingShorthand = 'tight' | 'normal' | 'relaxed' | 'loose';
+/**
+ * Shorthand mappings collection.
+ *
+ * @since 2.1.0
+ */
+export interface ShorthandMappings {
+    look: Record<LookShorthand, Partial<Factor24Config>>;
+    feel: Record<FeelShorthand, Partial<Factor24Config>>;
+    surface: Record<SurfaceShorthand, Partial<Factor24Config>>;
+    spacing: Record<SpacingShorthand, Partial<Factor24Config>>;
+}
+/**
+ * Visual factor group - Appearance-related factors.
+ *
+ * @since 2.1.0
+ */
+export interface VisualGroup {
+    /** Shape (Factor 4) */
+    shape?: FactorShape;
+    /** Border (Factor 19) */
+    border?: FactorBorder;
+    /** Opacity (Factor 20) */
+    opacity?: FactorOpacity;
+    /** Elevation (Factor 9) */
+    elevation?: FactorElevation;
+    /** Color scheme */
+    colorScheme?: ColorScheme;
+}
+/**
+ * Motion factor group - Animation-related factors.
+ *
+ * @since 2.1.0
+ */
+export interface MotionGroup {
+    /** Animation preset (Factor 8) */
+    animation?: FactorAnimation;
+    /** Transition timing (Factor 24) */
+    transition?: FactorTransition;
+}
+/**
+ * Layout factor group - Layout-related factors.
+ *
+ * @since 2.1.0
+ */
+export interface LayoutGroup {
+    /** Position (Factor 5) */
+    position?: FactorPosition;
+    /** Orientation (Factor 12) */
+    orientation?: FactorOrientation;
+    /** Density (Factor 13) */
+    density?: FactorDensity;
+    /** Spacing (Factor 17) */
+    spacing?: FactorSpacing;
+    /** Overflow (Factor 21) */
+    overflow?: FactorOverflow;
+    /** Justify alignment */
+    justify?: FactorAlignment;
+    /** Cross alignment */
+    align?: FactorAlignment;
+}
+/**
+ * Experience factor group - UX-related factors.
+ *
+ * @since 2.1.0
+ */
+export interface ExperienceGroup {
+    /** Accessibility level (Factor 10) */
+    a11y?: FactorA11y;
+    /** Cursor (Factor 22) */
+    cursor?: FactorCursor;
+    /** Z-Index (Factor 23) */
+    zIndex?: FactorZIndex;
+    /** Loading state (Factor 14) */
+    loadingState?: FactorLoadingState;
+}
+/**
+ * Combined factor groups for Level 2 props.
+ *
+ * @since 2.1.0
+ */
+export interface FactorGroups {
+    /** Visual appearance factors */
+    visual?: VisualGroup;
+    /** Motion/animation factors */
+    motion?: MotionGroup;
+    /** Layout factors */
+    layout?: LayoutGroup;
+    /** Experience/UX factors */
+    experience?: ExperienceGroup;
+}
+/**
+ * Multi-level props input.
+ * Users can provide props at any combination of levels.
+ * Resolution engine will merge them with correct priority.
+ *
+ * Priority: Level 1 (raw) > Level 2 (groups) > Level 3 (shorthand) > Level 4 (preset) > Level 5 (intent)
+ *
+ * @since 2.1.0
+ */
+export interface MultiLevelProps {
+    /** Semantic intent */
+    intent?: SemanticIntent;
+    /** Mood modifier */
+    mood?: SemanticMood;
+    /** Named preset */
+    preset?: string;
+    /** Visual look shorthand */
+    look?: LookShorthand;
+    /** Interaction feel shorthand */
+    feel?: FeelShorthand;
+    /** Surface/elevation shorthand */
+    surface?: SurfaceShorthand;
+    /** Spacing shorthand */
+    spacingPreset?: SpacingShorthand;
+    /** Visual factors group */
+    visual?: VisualGroup;
+    /** Motion factors group */
+    motion?: MotionGroup;
+    /** Layout factors group */
+    layout?: LayoutGroup;
+    /** Experience factors group */
+    experience?: ExperienceGroup;
+    /** All individual 24 factors can be specified directly */
+    size?: ComponentSize;
+    variant?: string;
+    colorScheme?: ColorScheme;
+    shape?: FactorShape;
+    position?: FactorPosition;
+    iconPosition?: FactorIconPosition;
+    state?: FactorState;
+    animation?: FactorAnimation;
+    elevation?: FactorElevation;
+    a11y?: FactorA11y;
+    justify?: FactorAlignment;
+    align?: FactorAlignment;
+    orientation?: FactorOrientation;
+    density?: FactorDensity;
+    loadingState?: FactorLoadingState;
+    responsive?: FactorResponsiveConfig;
+    theme?: FactorTheme;
+    spacing?: FactorSpacing;
+    typography?: FactorTypography;
+    border?: FactorBorder;
+    opacity?: FactorOpacity;
+    overflow?: FactorOverflow;
+    cursor?: FactorCursor;
+    zIndex?: FactorZIndex;
+    transition?: FactorTransition;
+}
+/**
+ * Resolution result with complete configuration.
+ *
+ * @since 2.1.0
+ */
+export interface ResolutionResult {
+    /** Complete 24-factor configuration */
+    config: Factor24Config;
+    /** Source levels that contributed to the result */
+    sources: {
+        level5Intent?: SemanticIntent;
+        level5Mood?: SemanticMood;
+        level4Preset?: string;
+        level3Shorthands?: string[];
+        level2Groups?: string[];
+        level1Factors?: string[];
+    };
+    /** Debug information (only in development) */
+    debug?: {
+        mergeOrder: string[];
+        overrides: Record<string, {
+            from: string;
+            to: string;
+            level: number;
+        }>;
+    };
+}
+/**
+ * Preset registry interface.
+ *
+ * @since 2.1.0
+ */
+export interface PresetRegistry {
+    /** All registered presets */
+    presets: Map<string, PresetDefinition>;
+    /** Total number of presets */
+    size: number;
+    /** Get preset by ID */
+    get(id: string): PresetDefinition | undefined;
+    /** Check if preset exists */
+    has(id: string): boolean;
+    /** Register a new preset */
+    register(preset: PresetDefinition): void;
+    /** Unregister a preset */
+    unregister(id: string): boolean;
+    /** Clear all presets */
+    clear(): void;
+    /** Get presets by category */
+    getByCategory(category: PresetCategory): PresetDefinition[];
+    /** Get presets by component type */
+    getByComponentType(componentType: string): PresetDefinition[];
+    /** Search presets by tag */
+    searchByTag(tag: string): PresetDefinition[];
+    /** Search presets by multiple tags */
+    searchByTags(tags: string[]): PresetDefinition[];
+    /** Text search in presets */
+    search(query: string): PresetDefinition[];
+    /** Get all presets */
+    getAll(): PresetDefinition[];
+    /** Get category counts */
+    getCategoryCounts(): Map<PresetCategory, number>;
+}
+/**
+ * Intent registry interface.
+ *
+ * @since 2.1.0
+ */
+export interface IntentRegistry {
+    /** All registered intents */
+    intents: Map<SemanticIntent, IntentDefinition>;
+    /** All registered mood modifiers */
+    moods: Map<SemanticMood, MoodModifierDefinition>;
+    /** Get intent by ID */
+    getIntent(id: SemanticIntent): IntentDefinition | undefined;
+    /** Get mood modifier by ID */
+    getMood(id: SemanticMood): MoodModifierDefinition | undefined;
+    /** Register a new intent */
+    registerIntent(intent: IntentDefinition): void;
+    /** Register a mood modifier */
+    registerMood(mood: MoodModifierDefinition): void;
+}
+/**
+ * Default Factor24 configuration values.
+ * Used when factors are not specified during resolution.
+ *
+ * @since 2.1.0
+ */
+export declare const DEFAULT_FACTOR24_CONFIG: Required<Factor24Config>;
+/**
+ * Get default value for a specific factor.
+ *
+ * @param factorKey - The factor key to get default for
+ * @returns The default value for the factor
+ * @since 2.1.0
+ */
+export declare function getDefaultFactorValue<K extends keyof Factor24Config>(factorKey: K): Required<Factor24Config>[K];
+/**
+ * List of all Factor24 keys for validation and iteration.
+ *
+ * @since 2.1.0
+ */
+export declare const FACTOR24_KEYS: ReadonlyArray<keyof Factor24Config>;
+/**
+ * Check if a key is a valid Factor24 key.
+ *
+ * @param key - The key to check
+ * @returns True if the key is a valid Factor24 key
+ * @since 2.1.0
+ */
+export declare function isValidFactor24Key(key: string): key is keyof Factor24Config;
+/**
+ * All available semantic intents.
+ *
+ * @since 2.1.0
+ */
+export declare const SEMANTIC_INTENTS: ReadonlyArray<SemanticIntent>;
+/**
+ * All available semantic moods.
+ *
+ * @since 2.1.0
+ */
+export declare const SEMANTIC_MOODS: ReadonlyArray<SemanticMood>;
+/**
+ * Check if a value is a valid semantic intent.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a valid intent
+ * @since 2.1.0
+ */
+export declare function isValidIntent(value: string): value is SemanticIntent;
+/**
+ * Check if a value is a valid semantic mood.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a valid mood
+ * @since 2.1.0
+ */
+export declare function isValidMood(value: string): value is SemanticMood;
+export type { FactorShape, FactorPosition, FactorIconPosition, FactorState, FactorAnimation, FactorElevation, FactorA11y, FactorAlignment, FactorOrientation, FactorDensity, FactorLoadingState, FactorResponsiveConfig, FactorTheme, FactorSpacing, FactorTypography, FactorBorder, FactorOpacity, FactorOverflow, FactorCursor, FactorZIndex, FactorTransition, ComponentSize, ColorScheme, };
+//# sourceMappingURL=types.d.ts.map