@nikkory/vibe-engine 4.0.0

package/dist/resolution/examples.d.ts

@@ -0,0 +1,486 @@
+/**
+ * Resolution Examples - Practical Usage Examples
+ *
+ * This file provides ready-to-use examples for the 5-Level Abstraction API.
+ * Each example demonstrates different levels and their combinations.
+ *
+ * @packageDocumentation
+ * @module resolution/examples
+ * @since 2.1.0
+ *
+ * Powered by Nikkory
+ */
+import type { MultiLevelProps } from './types';
+/**
+ * Level 5 examples using intent and mood.
+ * Highest abstraction level - just describe what you want.
+ *
+ * @since 2.1.0
+ */
+export declare const LEVEL_5_EXAMPLES: {
+    /**
+     * Primary CTA button with playful mood
+     */
+    readonly ctaPlayful: MultiLevelProps;
+    /**
+     * Destructive action with serious mood
+     */
+    readonly destructiveSerious: MultiLevelProps;
+    /**
+     * Hero section with bold mood
+     */
+    readonly heroBold: MultiLevelProps;
+    /**
+     * Navigation link with minimal mood
+     */
+    readonly navMinimal: MultiLevelProps;
+    /**
+     * Success feedback with friendly mood
+     */
+    readonly successFriendly: MultiLevelProps;
+    /**
+     * Premium button with luxurious mood
+     */
+    readonly premiumLuxurious: MultiLevelProps;
+    /**
+     * Info display with professional mood
+     */
+    readonly infoProfessional: MultiLevelProps;
+};
+/**
+ * Level 3 examples using shorthands.
+ * Simple, expressive props for common styling.
+ *
+ * @since 2.1.0
+ */
+export declare const LEVEL_3_EXAMPLES: {
+    /**
+     * Bold button with snappy feel
+     */
+    readonly boldSnappy: MultiLevelProps;
+    /**
+     * Subtle card with smooth feel
+     */
+    readonly subtleSmooth: MultiLevelProps;
+    /**
+     * Elevated surface with raised appearance
+     */
+    readonly elevatedRaised: MultiLevelProps;
+    /**
+     * Floating modal with overlay surface
+     */
+    readonly floatingOverlay: MultiLevelProps;
+    /**
+     * Ghost button with bouncy feel
+     */
+    readonly ghostBouncy: MultiLevelProps;
+    /**
+     * Outlined input with responsive feel
+     */
+    readonly outlinedResponsive: MultiLevelProps;
+    /**
+     * Soft card with relaxed spacing
+     */
+    readonly softRelaxed: MultiLevelProps;
+    /**
+     * Minimal text with tight spacing
+     */
+    readonly minimalTight: MultiLevelProps;
+};
+/**
+ * Level 2 examples using factor groups.
+ * Organized groups of related factors.
+ *
+ * @since 2.1.0
+ */
+export declare const LEVEL_2_EXAMPLES: {
+    /**
+     * Visual group for primary button
+     */
+    readonly visualPrimaryButton: MultiLevelProps;
+    /**
+     * Motion group for smooth transitions
+     */
+    readonly motionSmooth: MultiLevelProps;
+    /**
+     * Layout group for horizontal flex
+     */
+    readonly layoutHorizontalFlex: MultiLevelProps;
+    /**
+     * Experience group for interactive element
+     */
+    readonly experienceInteractive: MultiLevelProps;
+    /**
+     * Combined groups for card component
+     */
+    readonly cardCombined: MultiLevelProps;
+    /**
+     * Combined groups for modal dialog
+     */
+    readonly modalCombined: MultiLevelProps;
+};
+/**
+ * Level 1 examples using raw factors.
+ * Direct control over individual Factor24 properties.
+ *
+ * @since 2.1.0
+ */
+export declare const LEVEL_1_EXAMPLES: {
+    /**
+     * Custom button with specific factors
+     */
+    readonly customButton: MultiLevelProps;
+    /**
+     * Custom input with specific factors
+     */
+    readonly customInput: MultiLevelProps;
+    /**
+     * Custom card with specific factors
+     */
+    readonly customCard: MultiLevelProps;
+    /**
+     * Custom tooltip with specific factors
+     */
+    readonly customTooltip: MultiLevelProps;
+};
+/**
+ * Mixed level examples combining multiple abstraction levels.
+ * Demonstrates how to mix and match levels for fine-tuned control.
+ *
+ * @since 2.1.0
+ */
+export declare const MIXED_LEVEL_EXAMPLES: {
+    /**
+     * Intent + Override: CTA with custom shape
+     * Level 5 provides base, Level 1 overrides shape
+     */
+    readonly ctaWithPillShape: MultiLevelProps;
+    /**
+     * Shorthand + Group: Bold look with custom motion
+     * Level 3 provides look, Level 2 provides motion
+     */
+    readonly boldWithCustomMotion: MultiLevelProps;
+    /**
+     * Intent + Shorthand + Factor: Complete customization
+     * All levels working together
+     */
+    readonly fullStack: MultiLevelProps;
+    /**
+     * Mood override with specific elevation
+     * Level 5 mood + Level 1 elevation
+     */
+    readonly playfulWithShadow: MultiLevelProps;
+    /**
+     * Shorthand + Experience group
+     * Level 3 look + Level 2 experience
+     */
+    readonly accessibleGhost: MultiLevelProps;
+};
+/**
+ * Button component examples at various levels.
+ *
+ * @since 2.1.0
+ */
+export declare const BUTTON_EXAMPLES: {
+    /** Primary action button */
+    readonly primary: MultiLevelProps;
+    /** Secondary action button */
+    readonly secondary: MultiLevelProps;
+    /** Ghost/text button */
+    readonly ghost: MultiLevelProps;
+    /** Icon button */
+    readonly icon: MultiLevelProps;
+    /** Loading button */
+    readonly loading: MultiLevelProps;
+    /** Disabled button */
+    readonly disabled: MultiLevelProps;
+};
+/**
+ * Card component examples at various levels.
+ *
+ * @since 2.1.0
+ */
+export declare const CARD_EXAMPLES: {
+    /** Default content card */
+    readonly content: MultiLevelProps;
+    /** Featured card with emphasis */
+    readonly featured: MultiLevelProps;
+    /** Interactive clickable card */
+    readonly interactive: MultiLevelProps;
+    /** Minimal card */
+    readonly minimal: MultiLevelProps;
+    /** Glass effect card */
+    readonly glass: MultiLevelProps;
+};
+/**
+ * Input component examples at various levels.
+ *
+ * @since 2.1.0
+ */
+export declare const INPUT_EXAMPLES: {
+    /** Default outlined input */
+    readonly default: MultiLevelProps;
+    /** Filled input */
+    readonly filled: MultiLevelProps;
+    /** Search input */
+    readonly search: MultiLevelProps;
+    /** Error state input */
+    readonly error: MultiLevelProps;
+    /** Success state input */
+    readonly success: MultiLevelProps;
+    /** Disabled input */
+    readonly disabled: MultiLevelProps;
+};
+/**
+ * Accessibility-focused examples.
+ *
+ * @since 2.1.0
+ */
+export declare const A11Y_EXAMPLES: {
+    /** Enhanced accessibility button */
+    readonly enhancedButton: MultiLevelProps;
+    /** Maximum accessibility for critical actions */
+    readonly maxA11yAction: MultiLevelProps;
+    /** Reduced motion variant */
+    readonly reducedMotion: MultiLevelProps;
+    /** High contrast variant */
+    readonly highContrast: MultiLevelProps;
+};
+/**
+ * Responsive design examples.
+ *
+ * @since 2.1.0
+ */
+export declare const RESPONSIVE_EXAMPLES: {
+    /** Mobile-first compact button */
+    readonly mobileButton: MultiLevelProps;
+    /** Desktop card with more space */
+    readonly desktopCard: MultiLevelProps;
+    /** Compact mobile navigation */
+    readonly mobileNav: MultiLevelProps;
+};
+/**
+ * All examples grouped by category.
+ *
+ * @since 2.1.0
+ */
+export declare const ALL_EXAMPLES: {
+    readonly level5: {
+        /**
+         * Primary CTA button with playful mood
+         */
+        readonly ctaPlayful: MultiLevelProps;
+        /**
+         * Destructive action with serious mood
+         */
+        readonly destructiveSerious: MultiLevelProps;
+        /**
+         * Hero section with bold mood
+         */
+        readonly heroBold: MultiLevelProps;
+        /**
+         * Navigation link with minimal mood
+         */
+        readonly navMinimal: MultiLevelProps;
+        /**
+         * Success feedback with friendly mood
+         */
+        readonly successFriendly: MultiLevelProps;
+        /**
+         * Premium button with luxurious mood
+         */
+        readonly premiumLuxurious: MultiLevelProps;
+        /**
+         * Info display with professional mood
+         */
+        readonly infoProfessional: MultiLevelProps;
+    };
+    readonly level3: {
+        /**
+         * Bold button with snappy feel
+         */
+        readonly boldSnappy: MultiLevelProps;
+        /**
+         * Subtle card with smooth feel
+         */
+        readonly subtleSmooth: MultiLevelProps;
+        /**
+         * Elevated surface with raised appearance
+         */
+        readonly elevatedRaised: MultiLevelProps;
+        /**
+         * Floating modal with overlay surface
+         */
+        readonly floatingOverlay: MultiLevelProps;
+        /**
+         * Ghost button with bouncy feel
+         */
+        readonly ghostBouncy: MultiLevelProps;
+        /**
+         * Outlined input with responsive feel
+         */
+        readonly outlinedResponsive: MultiLevelProps;
+        /**
+         * Soft card with relaxed spacing
+         */
+        readonly softRelaxed: MultiLevelProps;
+        /**
+         * Minimal text with tight spacing
+         */
+        readonly minimalTight: MultiLevelProps;
+    };
+    readonly level2: {
+        /**
+         * Visual group for primary button
+         */
+        readonly visualPrimaryButton: MultiLevelProps;
+        /**
+         * Motion group for smooth transitions
+         */
+        readonly motionSmooth: MultiLevelProps;
+        /**
+         * Layout group for horizontal flex
+         */
+        readonly layoutHorizontalFlex: MultiLevelProps;
+        /**
+         * Experience group for interactive element
+         */
+        readonly experienceInteractive: MultiLevelProps;
+        /**
+         * Combined groups for card component
+         */
+        readonly cardCombined: MultiLevelProps;
+        /**
+         * Combined groups for modal dialog
+         */
+        readonly modalCombined: MultiLevelProps;
+    };
+    readonly level1: {
+        /**
+         * Custom button with specific factors
+         */
+        readonly customButton: MultiLevelProps;
+        /**
+         * Custom input with specific factors
+         */
+        readonly customInput: MultiLevelProps;
+        /**
+         * Custom card with specific factors
+         */
+        readonly customCard: MultiLevelProps;
+        /**
+         * Custom tooltip with specific factors
+         */
+        readonly customTooltip: MultiLevelProps;
+    };
+    readonly mixed: {
+        /**
+         * Intent + Override: CTA with custom shape
+         * Level 5 provides base, Level 1 overrides shape
+         */
+        readonly ctaWithPillShape: MultiLevelProps;
+        /**
+         * Shorthand + Group: Bold look with custom motion
+         * Level 3 provides look, Level 2 provides motion
+         */
+        readonly boldWithCustomMotion: MultiLevelProps;
+        /**
+         * Intent + Shorthand + Factor: Complete customization
+         * All levels working together
+         */
+        readonly fullStack: MultiLevelProps;
+        /**
+         * Mood override with specific elevation
+         * Level 5 mood + Level 1 elevation
+         */
+        readonly playfulWithShadow: MultiLevelProps;
+        /**
+         * Shorthand + Experience group
+         * Level 3 look + Level 2 experience
+         */
+        readonly accessibleGhost: MultiLevelProps;
+    };
+    readonly button: {
+        /** Primary action button */
+        readonly primary: MultiLevelProps;
+        /** Secondary action button */
+        readonly secondary: MultiLevelProps;
+        /** Ghost/text button */
+        readonly ghost: MultiLevelProps;
+        /** Icon button */
+        readonly icon: MultiLevelProps;
+        /** Loading button */
+        readonly loading: MultiLevelProps;
+        /** Disabled button */
+        readonly disabled: MultiLevelProps;
+    };
+    readonly card: {
+        /** Default content card */
+        readonly content: MultiLevelProps;
+        /** Featured card with emphasis */
+        readonly featured: MultiLevelProps;
+        /** Interactive clickable card */
+        readonly interactive: MultiLevelProps;
+        /** Minimal card */
+        readonly minimal: MultiLevelProps;
+        /** Glass effect card */
+        readonly glass: MultiLevelProps;
+    };
+    readonly input: {
+        /** Default outlined input */
+        readonly default: MultiLevelProps;
+        /** Filled input */
+        readonly filled: MultiLevelProps;
+        /** Search input */
+        readonly search: MultiLevelProps;
+        /** Error state input */
+        readonly error: MultiLevelProps;
+        /** Success state input */
+        readonly success: MultiLevelProps;
+        /** Disabled input */
+        readonly disabled: MultiLevelProps;
+    };
+    readonly a11y: {
+        /** Enhanced accessibility button */
+        readonly enhancedButton: MultiLevelProps;
+        /** Maximum accessibility for critical actions */
+        readonly maxA11yAction: MultiLevelProps;
+        /** Reduced motion variant */
+        readonly reducedMotion: MultiLevelProps;
+        /** High contrast variant */
+        readonly highContrast: MultiLevelProps;
+    };
+    readonly responsive: {
+        /** Mobile-first compact button */
+        readonly mobileButton: MultiLevelProps;
+        /** Desktop card with more space */
+        readonly desktopCard: MultiLevelProps;
+        /** Compact mobile navigation */
+        readonly mobileNav: MultiLevelProps;
+    };
+};
+/**
+ * Get example by category and name.
+ *
+ * @param category - The example category
+ * @param name - The example name
+ * @returns The MultiLevelProps example or undefined
+ * @since 2.1.0
+ */
+export declare function getExample(category: keyof typeof ALL_EXAMPLES, name: string): MultiLevelProps | undefined;
+/**
+ * List all available examples in a category.
+ *
+ * @param category - The example category
+ * @returns Array of example names
+ * @since 2.1.0
+ */
+export declare function listExamples(category: keyof typeof ALL_EXAMPLES): string[];
+/**
+ * List all example categories.
+ *
+ * @returns Array of category names
+ * @since 2.1.0
+ */
+export declare function listCategories(): (keyof typeof ALL_EXAMPLES)[];
+//# sourceMappingURL=examples.d.ts.map

package/dist/resolution/groups/experience-group.d.ts

@@ -0,0 +1,197 @@
+/**
+ * Experience Group - Factor Group for User Experience
+ *
+ * Maps ExperienceGroup props to Factor24Config factors.
+ * Handles accessibility, cursor, z-index, and loading state.
+ *
+ * @packageDocumentation
+ * @module resolution/groups/experience-group
+ * @since 2.1.0
+ *
+ * Powered by Nikkory
+ */
+import type { ExperienceGroup, Factor24Config, FactorA11y, FactorCursor, FactorZIndex, FactorLoadingState } from '../types';
+/**
+ * Expand ExperienceGroup to Factor24Config.
+ *
+ * @param experience - The experience group configuration
+ * @returns Partial Factor24Config with experience-related factors
+ *
+ * @example
+ * ```typescript
+ * const config = expandExperienceGroup({
+ *   a11y: 'enhanced',
+ *   cursor: 'pointer',
+ *   loadingState: 'idle',
+ * });
+ * // Result: { a11y: 'enhanced', cursor: 'pointer', loadingState: 'idle' }
+ * ```
+ *
+ * @since 2.1.0
+ */
+export declare function expandExperienceGroup(experience: ExperienceGroup): Partial<Factor24Config>;
+/**
+ * Predefined experience presets for common use cases.
+ *
+ * @since 2.1.0
+ */
+export declare const EXPERIENCE_PRESETS: Record<string, ExperienceGroup>;
+/**
+ * Valid accessibility level values.
+ *
+ * @since 2.1.0
+ */
+export declare const VALID_A11Y_LEVELS: ReadonlyArray<FactorA11y>;
+/**
+ * Valid cursor values.
+ *
+ * @since 2.1.0
+ */
+export declare const VALID_CURSORS: ReadonlyArray<FactorCursor>;
+/**
+ * Valid z-index values.
+ *
+ * @since 2.1.0
+ */
+export declare const VALID_Z_INDEXES: ReadonlyArray<FactorZIndex>;
+/**
+ * Valid loading state values.
+ *
+ * @since 2.1.0
+ */
+export declare const VALID_LOADING_STATES: ReadonlyArray<FactorLoadingState>;
+/**
+ * Check if a value is a valid accessibility level.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a valid a11y level
+ * @since 2.1.0
+ */
+export declare function isValidA11y(value: unknown): value is FactorA11y;
+/**
+ * Check if a value is a valid cursor.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a valid cursor
+ * @since 2.1.0
+ */
+export declare function isValidCursor(value: unknown): value is FactorCursor;
+/**
+ * Check if a value is a valid z-index.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a valid z-index
+ * @since 2.1.0
+ */
+export declare function isValidZIndex(value: unknown): value is FactorZIndex;
+/**
+ * Check if a value is a valid loading state.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a valid loading state
+ * @since 2.1.0
+ */
+export declare function isValidLoadingState(value: unknown): value is FactorLoadingState;
+/**
+ * Validate an ExperienceGroup configuration.
+ *
+ * @param experience - The experience group to validate
+ * @returns Validation result with errors if any
+ * @since 2.1.0
+ */
+export declare function validateExperienceGroup(experience: ExperienceGroup): {
+    valid: boolean;
+    errors: string[];
+};
+/**
+ * Get an experience preset by name.
+ *
+ * @param presetName - The name of the preset
+ * @returns The experience preset or undefined
+ * @since 2.1.0
+ */
+export declare function getExperiencePreset(presetName: string): ExperienceGroup | undefined;
+/**
+ * Merge multiple ExperienceGroup configurations.
+ * Later values override earlier ones.
+ *
+ * @param groups - Experience groups to merge
+ * @returns Merged experience group
+ * @since 2.1.0
+ */
+export declare function mergeExperienceGroups(...groups: ExperienceGroup[]): ExperienceGroup;
+/**
+ * Create an ExperienceGroup from Factor24Config.
+ * Extracts experience-related factors from a full config.
+ *
+ * @param config - The full Factor24Config
+ * @returns Extracted ExperienceGroup
+ * @since 2.1.0
+ */
+export declare function extractExperienceGroup(config: Partial<Factor24Config>): ExperienceGroup;
+/**
+ * Get numeric z-index value from factor.
+ *
+ * @param zIndex - The z-index factor
+ * @returns Numeric z-index value
+ * @since 2.1.0
+ */
+export declare function getZIndexValue(zIndex: FactorZIndex): number;
+/**
+ * Get CSS cursor value from factor.
+ *
+ * @param cursor - The cursor factor
+ * @returns CSS cursor value
+ * @since 2.1.0
+ */
+export declare function getCursorValue(cursor: FactorCursor): string;
+/**
+ * Check if element should be focusable based on a11y level.
+ *
+ * @param a11y - The accessibility level
+ * @returns True if element should be focusable
+ * @since 2.1.0
+ */
+export declare function shouldBeFocusable(a11y: FactorA11y): boolean;
+/**
+ * Get ARIA attributes based on a11y level.
+ *
+ * @param a11y - The accessibility level
+ * @param options - Additional options
+ * @returns Object with ARIA attributes
+ * @since 2.1.0
+ */
+export declare function getAriaAttributes(a11y: FactorA11y, options?: {
+    role?: string;
+    label?: string;
+    description?: string;
+    expanded?: boolean;
+    pressed?: boolean;
+    disabled?: boolean;
+}): Record<string, string | boolean | undefined>;
+/**
+ * Get loading state message.
+ *
+ * @param loadingState - The loading state
+ * @param customMessages - Optional custom messages
+ * @returns Status message
+ * @since 2.1.0
+ */
+export declare function getLoadingStateMessage(loadingState: FactorLoadingState, customMessages?: Partial<Record<FactorLoadingState, string>>): string;
+/**
+ * Check if element is in a loading state.
+ *
+ * @param loadingState - The loading state
+ * @returns True if element is loading
+ * @since 2.1.0
+ */
+export declare function isLoading(loadingState: FactorLoadingState): boolean;
+/**
+ * Check if element has completed loading (success or error).
+ *
+ * @param loadingState - The loading state
+ * @returns True if loading has completed
+ * @since 2.1.0
+ */
+export declare function hasLoadingCompleted(loadingState: FactorLoadingState): boolean;
+//# sourceMappingURL=experience-group.d.ts.map