@nikkory/vibe-engine 4.0.0

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

@@ -0,0 +1,196 @@
+/**
+ * Factor Groups - Level 2 Abstraction
+ *
+ * Provides grouped factor configurations that map to multiple Factor24 properties.
+ * Each group represents a logical collection of related factors.
+ *
+ * Groups:
+ * - VisualGroup: Shape, border, opacity, elevation, color scheme
+ * - MotionGroup: Animation, transition
+ * - LayoutGroup: Position, orientation, density, spacing, overflow, alignment
+ * - ExperienceGroup: Accessibility, cursor, z-index, loading state
+ *
+ * @packageDocumentation
+ * @module resolution/groups
+ * @since 2.1.0
+ *
+ * Powered by Nikkory
+ */
+import type { Factor24Config, FactorGroups } from '../types';
+export * from './visual-group';
+export * from './motion-group';
+export * from './layout-group';
+export * from './experience-group';
+/**
+ * Expand all factor groups to Factor24Config.
+ * Merges all group configurations into a single partial config.
+ *
+ * @param groups - The factor groups to expand
+ * @returns Partial Factor24Config with all group factors
+ *
+ * @example
+ * ```typescript
+ * const config = expandGroups({
+ *   visual: { shape: 'lg', elevation: 'md' },
+ *   motion: { animation: 'smooth' },
+ *   layout: { orientation: 'horizontal' },
+ *   experience: { cursor: 'pointer' },
+ * });
+ * ```
+ *
+ * @since 2.1.0
+ */
+export declare function expandGroups(groups: FactorGroups): Partial<Factor24Config>;
+/**
+ * Validation result for factor groups.
+ *
+ * @since 2.1.0
+ */
+export interface GroupValidationResult {
+    /** Overall validation status */
+    valid: boolean;
+    /** Errors by group */
+    errors: {
+        visual: string[];
+        motion: string[];
+        layout: string[];
+        experience: string[];
+    };
+    /** All errors flattened */
+    allErrors: string[];
+}
+/**
+ * Validate all factor groups.
+ *
+ * @param groups - The factor groups to validate
+ * @returns Validation result with errors by group
+ *
+ * @example
+ * ```typescript
+ * const result = validateGroups({
+ *   visual: { shape: 'invalid' },
+ * });
+ * if (!result.valid) {
+ *   console.error(result.allErrors);
+ * }
+ * ```
+ *
+ * @since 2.1.0
+ */
+export declare function validateGroups(groups: FactorGroups): GroupValidationResult;
+/**
+ * Merge multiple FactorGroups configurations.
+ * Later values override earlier ones within each group.
+ *
+ * @param groupsList - Factor groups to merge
+ * @returns Merged factor groups
+ *
+ * @example
+ * ```typescript
+ * const merged = mergeFactorGroups(
+ *   { visual: { shape: 'sm' } },
+ *   { visual: { shape: 'lg', elevation: 'md' } }
+ * );
+ * // Result: { visual: { shape: 'lg', elevation: 'md' } }
+ * ```
+ *
+ * @since 2.1.0
+ */
+export declare function mergeFactorGroups(...groupsList: FactorGroups[]): FactorGroups;
+/**
+ * Extract all factor groups from a Factor24Config.
+ *
+ * @param config - The full Factor24Config
+ * @returns Extracted factor groups
+ *
+ * @example
+ * ```typescript
+ * const groups = extractAllGroups({
+ *   shape: 'lg',
+ *   animation: 'smooth',
+ *   orientation: 'horizontal',
+ *   cursor: 'pointer',
+ * });
+ * // Result: {
+ * //   visual: { shape: 'lg' },
+ * //   motion: { animation: 'smooth' },
+ * //   layout: { orientation: 'horizontal' },
+ * //   experience: { cursor: 'pointer' }
+ * // }
+ * ```
+ *
+ * @since 2.1.0
+ */
+export declare function extractAllGroups(config: Partial<Factor24Config>): FactorGroups;
+/**
+ * Check if an object contains any visual group properties.
+ *
+ * @param obj - Object to check
+ * @returns True if object has visual group properties
+ * @since 2.1.0
+ */
+export declare function hasVisualGroupProps(obj: Record<string, unknown>): boolean;
+/**
+ * Check if an object contains any motion group properties.
+ *
+ * @param obj - Object to check
+ * @returns True if object has motion group properties
+ * @since 2.1.0
+ */
+export declare function hasMotionGroupProps(obj: Record<string, unknown>): boolean;
+/**
+ * Check if an object contains any layout group properties.
+ *
+ * @param obj - Object to check
+ * @returns True if object has layout group properties
+ * @since 2.1.0
+ */
+export declare function hasLayoutGroupProps(obj: Record<string, unknown>): boolean;
+/**
+ * Check if an object contains any experience group properties.
+ *
+ * @param obj - Object to check
+ * @returns True if object has experience group properties
+ * @since 2.1.0
+ */
+export declare function hasExperienceGroupProps(obj: Record<string, unknown>): boolean;
+/**
+ * Detect which groups are present in an object.
+ *
+ * @param obj - Object to check
+ * @returns Object indicating which groups are present
+ * @since 2.1.0
+ */
+export declare function detectGroups(obj: Record<string, unknown>): {
+    hasVisual: boolean;
+    hasMotion: boolean;
+    hasLayout: boolean;
+    hasExperience: boolean;
+};
+/**
+ * All group names.
+ *
+ * @since 2.1.0
+ */
+export declare const GROUP_NAMES: readonly ["visual", "motion", "layout", "experience"];
+/**
+ * Group name type.
+ *
+ * @since 2.1.0
+ */
+export type GroupName = (typeof GROUP_NAMES)[number];
+/**
+ * Map of group names to their factor keys.
+ *
+ * @since 2.1.0
+ */
+export declare const GROUP_FACTOR_KEYS: Record<GroupName, ReadonlyArray<keyof Factor24Config>>;
+/**
+ * Get the group name for a given factor key.
+ *
+ * @param factorKey - The factor key to look up
+ * @returns The group name or undefined if not found
+ * @since 2.1.0
+ */
+export declare function getGroupForFactor(factorKey: keyof Factor24Config): GroupName | undefined;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,192 @@
+/**
+ * Layout Group - Factor Group for Layout and Positioning
+ *
+ * Maps LayoutGroup props to Factor24Config factors.
+ * Handles position, orientation, density, spacing, overflow, and alignment.
+ *
+ * @packageDocumentation
+ * @module resolution/groups/layout-group
+ * @since 2.1.0
+ *
+ * Powered by Nikkory
+ */
+import type { LayoutGroup, Factor24Config, FactorPosition, FactorOrientation, FactorDensity, FactorSpacing, FactorOverflow, FactorAlignment } from '../types';
+/**
+ * Expand LayoutGroup to Factor24Config.
+ *
+ * @param layout - The layout group configuration
+ * @returns Partial Factor24Config with layout-related factors
+ *
+ * @example
+ * ```typescript
+ * const config = expandLayoutGroup({
+ *   orientation: 'horizontal',
+ *   density: 'compact',
+ *   spacing: 'sm',
+ * });
+ * // Result: { orientation: 'horizontal', density: 'compact', spacing: 'sm' }
+ * ```
+ *
+ * @since 2.1.0
+ */
+export declare function expandLayoutGroup(layout: LayoutGroup): Partial<Factor24Config>;
+/**
+ * Predefined layout presets for common use cases.
+ *
+ * @since 2.1.0
+ */
+export declare const LAYOUT_PRESETS: Record<string, LayoutGroup>;
+/**
+ * Valid position values.
+ *
+ * @since 2.1.0
+ */
+export declare const VALID_POSITIONS: ReadonlyArray<FactorPosition>;
+/**
+ * Valid orientation values.
+ *
+ * @since 2.1.0
+ */
+export declare const VALID_ORIENTATIONS: ReadonlyArray<FactorOrientation>;
+/**
+ * Valid density values.
+ *
+ * @since 2.1.0
+ */
+export declare const VALID_DENSITIES: ReadonlyArray<FactorDensity>;
+/**
+ * Valid spacing values.
+ *
+ * @since 2.1.0
+ */
+export declare const VALID_SPACINGS: ReadonlyArray<FactorSpacing>;
+/**
+ * Valid overflow values.
+ *
+ * @since 2.1.0
+ */
+export declare const VALID_OVERFLOWS: ReadonlyArray<FactorOverflow>;
+/**
+ * Valid alignment values.
+ *
+ * @since 2.1.0
+ */
+export declare const VALID_ALIGNMENTS: ReadonlyArray<FactorAlignment>;
+/**
+ * Check if a value is a valid position.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a valid position
+ * @since 2.1.0
+ */
+export declare function isValidPosition(value: unknown): value is FactorPosition;
+/**
+ * Check if a value is a valid orientation.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a valid orientation
+ * @since 2.1.0
+ */
+export declare function isValidOrientation(value: unknown): value is FactorOrientation;
+/**
+ * Check if a value is a valid density.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a valid density
+ * @since 2.1.0
+ */
+export declare function isValidDensity(value: unknown): value is FactorDensity;
+/**
+ * Check if a value is a valid spacing.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a valid spacing
+ * @since 2.1.0
+ */
+export declare function isValidSpacing(value: unknown): value is FactorSpacing;
+/**
+ * Check if a value is a valid overflow.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a valid overflow
+ * @since 2.1.0
+ */
+export declare function isValidOverflow(value: unknown): value is FactorOverflow;
+/**
+ * Check if a value is a valid alignment.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a valid alignment
+ * @since 2.1.0
+ */
+export declare function isValidAlignment(value: unknown): value is FactorAlignment;
+/**
+ * Validate a LayoutGroup configuration.
+ *
+ * @param layout - The layout group to validate
+ * @returns Validation result with errors if any
+ * @since 2.1.0
+ */
+export declare function validateLayoutGroup(layout: LayoutGroup): {
+    valid: boolean;
+    errors: string[];
+};
+/**
+ * Get a layout preset by name.
+ *
+ * @param presetName - The name of the preset
+ * @returns The layout preset or undefined
+ * @since 2.1.0
+ */
+export declare function getLayoutPreset(presetName: string): LayoutGroup | undefined;
+/**
+ * Merge multiple LayoutGroup configurations.
+ * Later values override earlier ones.
+ *
+ * @param groups - Layout groups to merge
+ * @returns Merged layout group
+ * @since 2.1.0
+ */
+export declare function mergeLayoutGroups(...groups: LayoutGroup[]): LayoutGroup;
+/**
+ * Create a LayoutGroup from Factor24Config.
+ * Extracts layout-related factors from a full config.
+ *
+ * @param config - The full Factor24Config
+ * @returns Extracted LayoutGroup
+ * @since 2.1.0
+ */
+export declare function extractLayoutGroup(config: Partial<Factor24Config>): LayoutGroup;
+/**
+ * Get CSS gap value from spacing factor.
+ *
+ * @param spacing - The spacing factor
+ * @returns CSS gap value string
+ * @since 2.1.0
+ */
+export declare function getSpacingValue(spacing: FactorSpacing): string;
+/**
+ * Get flexbox direction based on orientation.
+ *
+ * @param orientation - The orientation factor
+ * @returns CSS flex-direction value
+ * @since 2.1.0
+ */
+export declare function getFlexDirection(orientation: FactorOrientation): string;
+/**
+ * Get CSS justify-content value from alignment factor.
+ *
+ * @param alignment - The alignment factor
+ * @returns CSS justify-content value
+ * @since 2.1.0
+ */
+export declare function getJustifyContent(alignment: FactorAlignment): string;
+/**
+ * Get CSS align-items value from alignment factor.
+ *
+ * @param alignment - The alignment factor
+ * @returns CSS align-items value
+ * @since 2.1.0
+ */
+export declare function getAlignItems(alignment: FactorAlignment): string;
+//# sourceMappingURL=layout-group.d.ts.map

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

@@ -0,0 +1,127 @@
+/**
+ * Motion Group - Factor Group for Animation and Transitions
+ *
+ * Maps MotionGroup props to Factor24Config factors.
+ * Handles animation presets and transition timing.
+ *
+ * @packageDocumentation
+ * @module resolution/groups/motion-group
+ * @since 2.1.0
+ *
+ * Powered by Nikkory
+ */
+import type { MotionGroup, Factor24Config, FactorAnimation, FactorTransition } from '../types';
+/**
+ * Expand MotionGroup to Factor24Config.
+ *
+ * @param motion - The motion group configuration
+ * @returns Partial Factor24Config with motion-related factors
+ *
+ * @example
+ * ```typescript
+ * const config = expandMotionGroup({
+ *   animation: 'smooth',
+ *   transition: 'fast',
+ * });
+ * // Result: { animation: 'smooth', transition: 'fast' }
+ * ```
+ *
+ * @since 2.1.0
+ */
+export declare function expandMotionGroup(motion: MotionGroup): Partial<Factor24Config>;
+/**
+ * Predefined motion presets for common use cases.
+ *
+ * @since 2.1.0
+ */
+export declare const MOTION_PRESETS: Record<string, MotionGroup>;
+/**
+ * Valid animation values.
+ *
+ * @since 2.1.0
+ */
+export declare const VALID_ANIMATIONS: ReadonlyArray<FactorAnimation>;
+/**
+ * Valid transition values.
+ *
+ * @since 2.1.0
+ */
+export declare const VALID_TRANSITIONS: ReadonlyArray<FactorTransition>;
+/**
+ * Check if a value is a valid animation.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a valid animation
+ * @since 2.1.0
+ */
+export declare function isValidAnimation(value: unknown): value is FactorAnimation;
+/**
+ * Check if a value is a valid transition.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a valid transition
+ * @since 2.1.0
+ */
+export declare function isValidTransition(value: unknown): value is FactorTransition;
+/**
+ * Validate a MotionGroup configuration.
+ *
+ * @param motion - The motion group to validate
+ * @returns Validation result with errors if any
+ * @since 2.1.0
+ */
+export declare function validateMotionGroup(motion: MotionGroup): {
+    valid: boolean;
+    errors: string[];
+};
+/**
+ * Get a motion preset by name.
+ *
+ * @param presetName - The name of the preset
+ * @returns The motion preset or undefined
+ * @since 2.1.0
+ */
+export declare function getMotionPreset(presetName: string): MotionGroup | undefined;
+/**
+ * Merge multiple MotionGroup configurations.
+ * Later values override earlier ones.
+ *
+ * @param groups - Motion groups to merge
+ * @returns Merged motion group
+ * @since 2.1.0
+ */
+export declare function mergeMotionGroups(...groups: MotionGroup[]): MotionGroup;
+/**
+ * Create a MotionGroup from Factor24Config.
+ * Extracts motion-related factors from a full config.
+ *
+ * @param config - The full Factor24Config
+ * @returns Extracted MotionGroup
+ * @since 2.1.0
+ */
+export declare function extractMotionGroup(config: Partial<Factor24Config>): MotionGroup;
+/**
+ * Get animation duration in milliseconds based on transition setting.
+ *
+ * @param transition - The transition setting
+ * @returns Duration in milliseconds
+ * @since 2.1.0
+ */
+export declare function getTransitionDuration(transition: FactorTransition): number;
+/**
+ * Get CSS easing function based on animation type.
+ *
+ * @param animation - The animation type
+ * @returns CSS easing function string
+ * @since 2.1.0
+ */
+export declare function getAnimationEasing(animation: FactorAnimation): string;
+/**
+ * Check if motion should be reduced based on configuration.
+ *
+ * @param motion - The motion group
+ * @returns True if motion should be reduced
+ * @since 2.1.0
+ */
+export declare function shouldReduceMotion(motion: MotionGroup): boolean;
+//# sourceMappingURL=motion-group.d.ts.map

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

@@ -0,0 +1,146 @@
+/**
+ * Visual Group - Factor Group for Visual Appearance
+ *
+ * Maps VisualGroup props to Factor24Config factors.
+ * Handles shape, border, opacity, elevation, and color scheme.
+ *
+ * @packageDocumentation
+ * @module resolution/groups/visual-group
+ * @since 2.1.0
+ *
+ * Powered by Nikkory
+ */
+import type { VisualGroup, Factor24Config, FactorShape, FactorBorder, FactorOpacity, FactorElevation, ColorScheme } from '../types';
+/**
+ * Expand VisualGroup to Factor24Config.
+ *
+ * @param visual - The visual group configuration
+ * @returns Partial Factor24Config with visual-related factors
+ *
+ * @example
+ * ```typescript
+ * const config = expandVisualGroup({
+ *   shape: 'lg',
+ *   elevation: 'md',
+ *   colorScheme: 'primary',
+ * });
+ * // Result: { shape: 'lg', elevation: 'md', colorScheme: 'primary' }
+ * ```
+ *
+ * @since 2.1.0
+ */
+export declare function expandVisualGroup(visual: VisualGroup): Partial<Factor24Config>;
+/**
+ * Predefined visual presets for common use cases.
+ *
+ * @since 2.1.0
+ */
+export declare const VISUAL_PRESETS: Record<string, VisualGroup>;
+/**
+ * Valid shape values.
+ *
+ * @since 2.1.0
+ */
+export declare const VALID_SHAPES: ReadonlyArray<FactorShape>;
+/**
+ * Valid border values.
+ *
+ * @since 2.1.0
+ */
+export declare const VALID_BORDERS: ReadonlyArray<FactorBorder>;
+/**
+ * Valid opacity values.
+ *
+ * @since 2.1.0
+ */
+export declare const VALID_OPACITIES: ReadonlyArray<FactorOpacity>;
+/**
+ * Valid elevation values.
+ *
+ * @since 2.1.0
+ */
+export declare const VALID_ELEVATIONS: ReadonlyArray<FactorElevation>;
+/**
+ * Valid color scheme values.
+ *
+ * @since 2.1.0
+ */
+export declare const VALID_COLOR_SCHEMES: ReadonlyArray<ColorScheme>;
+/**
+ * Check if a value is a valid shape.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a valid shape
+ * @since 2.1.0
+ */
+export declare function isValidShape(value: unknown): value is FactorShape;
+/**
+ * Check if a value is a valid border.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a valid border
+ * @since 2.1.0
+ */
+export declare function isValidBorder(value: unknown): value is FactorBorder;
+/**
+ * Check if a value is a valid opacity.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a valid opacity
+ * @since 2.1.0
+ */
+export declare function isValidOpacity(value: unknown): value is FactorOpacity;
+/**
+ * Check if a value is a valid elevation.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a valid elevation
+ * @since 2.1.0
+ */
+export declare function isValidElevation(value: unknown): value is FactorElevation;
+/**
+ * Check if a value is a valid color scheme.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a valid color scheme
+ * @since 2.1.0
+ */
+export declare function isValidColorScheme(value: unknown): value is ColorScheme;
+/**
+ * Validate a VisualGroup configuration.
+ *
+ * @param visual - The visual group to validate
+ * @returns Validation result with errors if any
+ * @since 2.1.0
+ */
+export declare function validateVisualGroup(visual: VisualGroup): {
+    valid: boolean;
+    errors: string[];
+};
+/**
+ * Get a visual preset by name.
+ *
+ * @param presetName - The name of the preset
+ * @returns The visual preset or undefined
+ * @since 2.1.0
+ */
+export declare function getVisualPreset(presetName: string): VisualGroup | undefined;
+/**
+ * Merge multiple VisualGroup configurations.
+ * Later values override earlier ones.
+ *
+ * @param groups - Visual groups to merge
+ * @returns Merged visual group
+ * @since 2.1.0
+ */
+export declare function mergeVisualGroups(...groups: VisualGroup[]): VisualGroup;
+/**
+ * Create a VisualGroup from Factor24Config.
+ * Extracts visual-related factors from a full config.
+ *
+ * @param config - The full Factor24Config
+ * @returns Extracted VisualGroup
+ * @since 2.1.0
+ */
+export declare function extractVisualGroup(config: Partial<Factor24Config>): VisualGroup;
+//# sourceMappingURL=visual-group.d.ts.map