@nikkory/vibe-engine 4.0.0

package/dist/ui-studio/composition/section-orchestrator.d.ts

@@ -0,0 +1,306 @@
+/**
+ * Section Generator
+ * Coordinates ComponentGenerator calls for each slot in a section
+ *
+ * @packageDocumentation
+ * @module generators/section-generator
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+import type { SectionConfig, SectionFactors, SlotConfig, StoredComponentInSlot, ComponentType, DesignSystem, Tier } from '../types';
+import type { ComponentGenerator } from '../ComponentGenerator';
+import type { FactorPropagator } from './FactorPropagator';
+import type { ResolvedFactors } from '../../types/algorithm-engine.types';
+/**
+ * Input for section generation
+ *
+ * @remarks
+ * Contains all information needed to generate components
+ * for a section including config, factors, and slot definitions.
+ */
+export interface SectionGenerationInput {
+    /** Section configuration (14 fields) */
+    readonly sectionConfig: SectionConfig;
+    /** Section factors (13 factors) */
+    readonly sectionFactors: SectionFactors;
+    /** Slot configurations */
+    readonly slots: readonly SlotConfig[];
+    /** Components stored in slots */
+    readonly storedComponents: readonly StoredComponentInSlot[];
+}
+/**
+ * Options for section generation behavior
+ */
+export interface SectionGenerationOptions {
+    /** Generate components in parallel (default: true) */
+    readonly parallel?: boolean;
+    /** Include CSS variables in output (default: true) */
+    readonly includeCssVariables?: boolean;
+    /** Include wrapper component (default: true) */
+    readonly includeWrapper?: boolean;
+    /** Custom class name for section wrapper */
+    readonly wrapperClassName?: string;
+}
+/**
+ * Generated component in a slot
+ */
+export interface GeneratedSlotComponent {
+    /** Slot ID */
+    readonly slotId: string;
+    /** Component instance ID */
+    readonly instanceId: string;
+    /** Component type */
+    readonly componentType: ComponentType;
+    /** Generated component code */
+    readonly code: string;
+    /** Generated styles */
+    readonly styles: string;
+    /** Resolved component factors */
+    readonly factors: ResolvedFactors;
+    /** Generation metadata */
+    readonly metadata: GeneratedComponentMetadata;
+}
+/**
+ * Metadata for generated component
+ */
+export interface GeneratedComponentMetadata {
+    /** Component type */
+    readonly componentType: ComponentType;
+    /** Design system used */
+    readonly designSystem: DesignSystem;
+    /** Quality tier */
+    readonly tier: Tier;
+    /** Generation timestamp */
+    readonly generatedAt: Date;
+    /** Lines of code */
+    readonly linesOfCode: number;
+}
+/**
+ * Result of section generation
+ */
+export interface SectionGenerationResult {
+    /** Whether generation was successful */
+    readonly success: boolean;
+    /** Generated slot components */
+    readonly components: readonly GeneratedSlotComponent[];
+    /** Combined CSS variables */
+    readonly cssVariables: string;
+    /** Section wrapper code (if includeWrapper) */
+    readonly wrapperCode: string;
+    /** Complete composed section code */
+    readonly composedCode: string;
+    /** Generation metadata */
+    readonly metadata: SectionGenerationMetadata;
+    /** Errors encountered (if any) */
+    readonly errors: readonly string[];
+}
+/**
+ * Metadata for section generation result
+ */
+export interface SectionGenerationMetadata {
+    /** Section ID */
+    readonly sectionId: string;
+    /** Section type */
+    readonly sectionType: string;
+    /** Number of slots processed */
+    readonly slotsProcessed: number;
+    /** Number of components generated */
+    readonly componentsGenerated: number;
+    /** Total lines of code */
+    readonly totalLinesOfCode: number;
+    /** Generation duration in milliseconds */
+    readonly durationMs: number;
+    /** Design system used */
+    readonly designSystem: DesignSystem;
+    /** Quality tier */
+    readonly tier: Tier;
+}
+/**
+ * Section Generator
+ *
+ * @remarks
+ * Coordinates the generation of all components within a section:
+ * 1. Resolves slots to component instances
+ * 2. Propagates section factors to each component
+ * 3. Generates components in parallel or sequentially
+ * 4. Composes the final section output
+ *
+ * @example
+ * ```typescript
+ * const generator = createSectionGenerator();
+ * const result = await generator.generateSection({
+ *   sectionConfig,
+ *   sectionFactors,
+ *   slots,
+ *   storedComponents
+ * });
+ *
+ * if (result.success) {
+ *   console.log(result.composedCode);
+ * }
+ * ```
+ */
+export declare class SectionGenerator {
+    private readonly componentGenerator;
+    private readonly factorPropagator;
+    /**
+     * Creates a new SectionGenerator instance
+     *
+     * @param componentGenerator - ComponentGenerator instance
+     * @param factorPropagator - FactorPropagator instance
+     */
+    constructor(componentGenerator?: ComponentGenerator, factorPropagator?: FactorPropagator);
+    /**
+     * Generate components for a section
+     *
+     * @param input - Section generation input
+     * @param options - Section generation options
+     * @returns Section generation result with generated components
+     */
+    generateSection(input: SectionGenerationInput, options?: SectionGenerationOptions): Promise<SectionGenerationResult>;
+    /**
+     * Generate components in parallel using Promise.all
+     *
+     * @param input - Orchestration input
+     * @param errors - Array to collect errors
+     * @returns Array of generated slot components
+     */
+    private generateParallel;
+    /**
+     * Generate components sequentially
+     *
+     * @param input - Orchestration input
+     * @param errors - Array to collect errors
+     * @returns Array of generated slot components
+     */
+    private generateSequential;
+    /**
+     * Generate a single slot component
+     *
+     * @param stored - Stored component configuration
+     * @param slot - Slot configuration
+     * @param sectionConfig - Section configuration
+     * @param sectionFactors - Section factors
+     * @param errors - Array to collect errors
+     * @returns Generated slot component or null on failure
+     */
+    private generateSlotComponent;
+    /**
+     * Generate section wrapper component
+     *
+     * @param input - Orchestration input
+     * @param customClassName - Optional custom class name
+     * @returns Section wrapper code
+     */
+    private generateSectionWrapper;
+    /**
+     * Compose the final section code
+     *
+     * @param input - Orchestration input
+     * @param components - Generated slot components
+     * @param wrapperCode - Section wrapper code
+     * @param cssVariables - CSS variables
+     * @returns Composed section code
+     */
+    private composeSection;
+    /**
+     * Merge CSS variables from all components
+     *
+     * @param components - Generated components
+     * @param factors - Section factors
+     * @returns Merged CSS variables string
+     */
+    private mergeCssVariables;
+    /**
+     * Generate import statements for components
+     *
+     * @param components - Generated components
+     * @returns Import statements
+     */
+    private generateImports;
+    /**
+     * Create an empty result for error cases
+     *
+     * @param input - Orchestration input
+     * @param errors - Error messages
+     * @param durationMs - Duration in milliseconds
+     * @returns Empty orchestration result
+     */
+    private createEmptyResult;
+    /**
+     * Count total lines of code
+     *
+     * @param components - Generated components
+     * @param wrapperCode - Wrapper code
+     * @returns Total line count
+     */
+    private countTotalLines;
+    /**
+     * Convert string to PascalCase
+     *
+     * @param str - Input string
+     * @returns PascalCase string
+     */
+    private toPascalCase;
+    /**
+     * Get spacing value from level
+     *
+     * @param level - Spacing level
+     * @returns CSS spacing value
+     */
+    private getSpacingValue;
+    /**
+     * Get max width value from level
+     *
+     * @param level - Max width level
+     * @returns CSS max-width value
+     */
+    private getMaxWidthValue;
+    /**
+     * Get border radius value from level
+     *
+     * @param level - Radius level
+     * @returns CSS border-radius value
+     */
+    private getRadiusValue;
+    /**
+     * Get elevation/shadow value from level
+     *
+     * @param level - Elevation level
+     * @returns CSS box-shadow value
+     */
+    private getElevationValue;
+}
+/**
+ * Create a new SectionGenerator instance
+ *
+ * @param componentGenerator - Optional ComponentGenerator
+ * @param factorPropagator - Optional FactorPropagator
+ * @returns SectionGenerator instance
+ *
+ * @example
+ * ```typescript
+ * const generator = createSectionGenerator();
+ * ```
+ */
+export declare function createSectionGenerator(componentGenerator?: ComponentGenerator, factorPropagator?: FactorPropagator): SectionGenerator;
+/**
+ * Convenience function to generate section components
+ *
+ * @param input - Section generation input
+ * @param options - Section generation options
+ * @returns Section generation result
+ *
+ * @example
+ * ```typescript
+ * const result = await generateSectionComponents({
+ *   sectionConfig,
+ *   sectionFactors,
+ *   slots,
+ *   storedComponents
+ * });
+ * ```
+ */
+export declare function generateSectionComponents(input: SectionGenerationInput, options?: SectionGenerationOptions): Promise<SectionGenerationResult>;
+//# sourceMappingURL=section-orchestrator.d.ts.map

package/dist/ui-studio/granularity/FactorCascade.d.ts

@@ -0,0 +1,328 @@
+/**
+ * FactorCascade - Factor cascade algorithm implementation
+ *
+ * This module implements the factor cascade algorithm for the Unified
+ * Granularity Architecture. Factors cascade DOWN from higher levels
+ * (template → layout → page → section → component → atom) based on
+ * their cascadeDown property.
+ *
+ * Key Features:
+ * - Dynamic factor resolution based on level and cascadeDown
+ * - Factor override priority: Child > Parent > Defaults
+ * - Batch operations for cascading multiple factors
+ * - Design system-aware defaults
+ *
+ * Factor Distribution by Level:
+ * - Template (level 6): 8 factors - cascadeDown=true
+ * - Page (level 4): 5 additional factors
+ * - Section (level 3): 5 additional factors
+ * - Component (level 2): 6 additional factors
+ * - Total: 24 factors
+ *
+ * @packageDocumentation
+ * @module generators
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+import type { DesignSystem } from '../types';
+import type { GranularityLevel, GranularityFactorValues, GranularityFactorDefinition } from '../../types/granularity';
+/**
+ * Input for cascading factors from parent to child
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+export interface CascadeFactorsInput {
+    /** Parent's resolved factors */
+    readonly parentFactors: GranularityFactorValues;
+    /** Child's granularity level */
+    readonly childLevel: GranularityLevel;
+    /** Child's explicit factor overrides (highest priority) */
+    readonly childOverrides?: GranularityFactorValues;
+    /** Design system for defaults */
+    readonly designSystem: DesignSystem;
+}
+/**
+ * Result of factor cascade operation
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+export interface CascadeFactorsResult {
+    /** Cascaded factors for the child */
+    readonly factors: GranularityFactorValues;
+    /** Factor IDs that were cascaded from parent */
+    readonly cascadedFromParent: readonly string[];
+    /** Factor IDs that were overridden by child */
+    readonly overriddenByChild: readonly string[];
+    /** Factor IDs that used design system defaults */
+    readonly fromDefaults: readonly string[];
+}
+/**
+ * Options for FactorCascade operations
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+export interface FactorCascadeOptions {
+    /** Whether to include unknown factors (not in registry) */
+    readonly includeUnknownFactors?: boolean;
+    /** Whether to apply design system defaults for missing factors */
+    readonly applyDefaults?: boolean;
+    /** Verbose logging */
+    readonly verbose?: boolean;
+}
+/**
+ * FactorCascade - Handles factor cascading between granularity levels
+ *
+ * This class implements the factor cascade algorithm that propagates
+ * factors from parent levels down to child levels based on the
+ * cascadeDown property of each factor.
+ *
+ * @category generators
+ * @since 4.0.0
+ *
+ * @example
+ * ```typescript
+ * const cascade = new FactorCascade();
+ *
+ * // Cascade template factors to page level
+ * const result = cascade.cascadeFactors({
+ *   parentFactors: { spacing: 'lg', colorPrimary: '#3B82F6' },
+ *   childLevel: 'page',
+ *   childOverrides: { spacing: 'xl' },
+ *   designSystem: 'material-design',
+ * });
+ *
+ * console.log(result.factors);
+ * // { spacing: 'xl', colorPrimary: '#3B82F6', ... }
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export declare class FactorCascade {
+    private readonly options;
+    constructor(options?: FactorCascadeOptions);
+    /**
+     * Cascade factors from parent to child with proper priority
+     *
+     * Priority order (highest to lowest):
+     * 1. Child's explicit overrides (childOverrides)
+     * 2. Parent's cascading factors (parentFactors with cascadeDown=true)
+     * 3. Design system defaults
+     *
+     * @param input - Cascade input parameters
+     * @returns Cascade result with factors and metadata
+     *
+     * @example
+     * ```typescript
+     * const result = cascade.cascadeFactors({
+     *   parentFactors: { spacing: 'lg', gridColumns: 12 },
+     *   childLevel: 'section',
+     *   childOverrides: { spacing: 'xl' },
+     *   designSystem: 'material-design',
+     * });
+     *
+     * // spacing='xl' (from childOverrides)
+     * // gridColumns not included (cascadeDown=false for section)
+     * ```
+     *
+     * Powered by Nikkory
+     */
+    cascadeFactors(input: CascadeFactorsInput): CascadeFactorsResult;
+    /**
+     * Filter factors that should cascade to a target level
+     *
+     * Only includes factors that:
+     * 1. Have cascadeDown=true
+     * 2. Are defined at or above the target level
+     *
+     * @param factors - Source factors to filter
+     * @param targetLevel - Target granularity level
+     * @returns Filtered factors that cascade to target
+     *
+     * @example
+     * ```typescript
+     * const cascading = cascade.filterCascadingFactors(
+     *   { spacing: 'lg', gridColumns: 12, colorPrimary: '#3B82F6' },
+     *   'section'
+     * );
+     * // { spacing: 'lg', colorPrimary: '#3B82F6' }
+     * // gridColumns excluded because cascadeDown=false
+     * ```
+     *
+     * Powered by Nikkory
+     */
+    filterCascadingFactors(factors: GranularityFactorValues, targetLevel: GranularityLevel): GranularityFactorValues;
+    /**
+     * Apply overrides to base factors with proper priority
+     *
+     * Override priority (highest to lowest):
+     * 1. Explicit overrides parameter
+     * 2. Base factors
+     *
+     * @param baseFactors - Base factor values
+     * @param overrides - Override values (highest priority)
+     * @returns Merged factors with overrides applied
+     *
+     * @example
+     * ```typescript
+     * const merged = cascade.applyFactorOverrides(
+     *   { spacing: 'lg', colorPrimary: '#3B82F6' },
+     *   { spacing: 'xl' }
+     * );
+     * // { spacing: 'xl', colorPrimary: '#3B82F6' }
+     * ```
+     *
+     * Powered by Nikkory
+     */
+    applyFactorOverrides(baseFactors: GranularityFactorValues, overrides: GranularityFactorValues): GranularityFactorValues;
+    /**
+     * Get all factors applicable at a given granularity level
+     *
+     * Includes factors defined at this level AND factors from higher
+     * levels that have cascadeDown enabled.
+     *
+     * @param level - The granularity level to query
+     * @returns Array of factor definitions applicable at this level
+     *
+     * Powered by Nikkory
+     */
+    getFactorsForLevel(level: GranularityLevel): readonly GranularityFactorDefinition[];
+    /**
+     * Get factor count for each granularity level
+     *
+     * @returns Map of level to factor count
+     *
+     * @example
+     * ```typescript
+     * const counts = cascade.getFactorCountByLevel();
+     * console.log(counts);
+     * // { template: 8, layout: 10, page: 13, section: 18, component: 24, atom: 24 }
+     * ```
+     *
+     * Powered by Nikkory
+     */
+    getFactorCountByLevel(): Record<GranularityLevel, number>;
+    /**
+     * Check if a factor cascades to a target level
+     *
+     * @param factorId - Factor ID to check
+     * @param targetLevel - Target level
+     * @returns True if factor cascades to target
+     *
+     * Powered by Nikkory
+     */
+    doesFactorCascadeTo(factorId: string, targetLevel: GranularityLevel): boolean;
+    /**
+     * Log message if verbose mode is enabled
+     *
+     * @param message - Message to log
+     *
+     * Powered by Nikkory
+     */
+    private log;
+}
+/**
+ * Create a new FactorCascade instance
+ *
+ * @param options - Cascade options
+ * @returns FactorCascade instance
+ *
+ * @example
+ * ```typescript
+ * const cascade = createFactorCascade({ verbose: true });
+ * const result = cascade.cascadeFactors({ ... });
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export declare function createFactorCascade(options?: FactorCascadeOptions): FactorCascade;
+/**
+ * Cascade factors from parent to child (standalone function)
+ *
+ * @param input - Cascade input parameters
+ * @param options - Cascade options
+ * @returns Cascade result
+ *
+ * @example
+ * ```typescript
+ * import { cascadeFactors } from '@nikkory/vibe-engine';
+ *
+ * const result = cascadeFactors({
+ *   parentFactors: { spacing: 'lg' },
+ *   childLevel: 'section',
+ *   designSystem: 'material-design',
+ * });
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export declare function cascadeFactors(input: CascadeFactorsInput, options?: FactorCascadeOptions): CascadeFactorsResult;
+/**
+ * Filter cascading factors (standalone function)
+ *
+ * @param factors - Source factors
+ * @param targetLevel - Target level
+ * @param options - Cascade options
+ * @returns Filtered factors
+ *
+ * @example
+ * ```typescript
+ * import { filterCascadingFactors } from '@nikkory/vibe-engine';
+ *
+ * const cascading = filterCascadingFactors(
+ *   { spacing: 'lg', gridColumns: 12 },
+ *   'section'
+ * );
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export declare function filterCascadingFactors(factors: GranularityFactorValues, targetLevel: GranularityLevel, options?: FactorCascadeOptions): GranularityFactorValues;
+/**
+ * Apply factor overrides (standalone function)
+ *
+ * @param baseFactors - Base factors
+ * @param overrides - Override factors
+ * @returns Merged factors
+ *
+ * @example
+ * ```typescript
+ * import { applyFactorOverrides } from '@nikkory/vibe-engine';
+ *
+ * const merged = applyFactorOverrides(
+ *   { spacing: 'lg' },
+ *   { spacing: 'xl' }
+ * );
+ * // { spacing: 'xl' }
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export declare function applyFactorOverrides(baseFactors: GranularityFactorValues, overrides: GranularityFactorValues): GranularityFactorValues;
+/**
+ * Get factors applicable at a level (standalone function)
+ *
+ * @param level - Granularity level
+ * @returns Array of factor definitions
+ *
+ * @example
+ * ```typescript
+ * import { getFactorsForLevel } from '@nikkory/vibe-engine';
+ *
+ * const pageFactors = getFactorsForLevel('page');
+ * console.log(pageFactors.length); // ~13
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export declare function getFactorsForLevel(level: GranularityLevel): readonly GranularityFactorDefinition[];
+//# sourceMappingURL=FactorCascade.d.ts.map