@nikkory/vibe-engine 4.0.0

package/dist/ui-studio/composition/SectionGenerator.d.ts

@@ -0,0 +1,312 @@
+/**
+ * Section Generator
+ * Generates complete sections from SectionConfig with slot resolution and factor propagation
+ *
+ * @packageDocumentation
+ * @module generators/SectionGenerator
+ * @since 4.0.0
+ *
+ * The SectionGenerator:
+ * 1. Takes a SectionConfig with 14 fields
+ * 2. Resolves slots to components
+ * 3. Propagates 13 section factors to child components
+ * 4. Generates complete JSX output
+ *
+ * Powered by Nikkory
+ */
+import { type SectionGenerationResult as ComponentSectionGenerationResult } from './section-orchestrator';
+import type { SectionConfig, SectionFactors, SectionWithFactors, LayoutType, SpacingLevel, Tier, DesignSystem, ComponentType, StoredComponentInSlot } from '../types';
+/**
+ * Section generation input
+ */
+export interface SectionGenerationInput {
+    /** Section configuration (14 fields) */
+    readonly config: SectionConfig;
+    /** Section factors for propagation (13 factors) */
+    readonly factors: SectionFactors;
+    /** Additional generation options */
+    readonly options?: SectionGeneratorOptions;
+    /** Stored components in slots (for orchestrator) */
+    readonly storedComponents?: readonly StoredComponentInSlot[];
+}
+/**
+ * Section generator options
+ */
+export interface SectionGeneratorOptions {
+    /** Include wrapper div */
+    readonly includeWrapper?: boolean;
+    /** Custom wrapper class */
+    readonly wrapperClass?: string;
+    /** Generate TypeScript or JavaScript */
+    readonly typescript?: boolean;
+    /** Include CSS variables inline */
+    readonly inlineCssVariables?: boolean;
+    /** Add data attributes for factor values */
+    readonly includeDataAttributes?: boolean;
+}
+/**
+ * Generated slot content
+ */
+export interface GeneratedSlot {
+    /** Slot identifier */
+    readonly slotId: string;
+    /** Generated JSX content */
+    readonly content: string;
+    /** Components used in this slot */
+    readonly components: readonly ComponentType[];
+}
+/**
+ * Section generation result
+ */
+export interface SectionGenerationResult {
+    /** Whether generation succeeded */
+    readonly success: boolean;
+    /** Error message if failed */
+    readonly error?: string;
+    /** Generated JSX code */
+    readonly jsx: string;
+    /** Generated CSS (Tailwind classes) */
+    readonly css: string;
+    /** CSS variables for theming */
+    readonly cssVariables: Record<string, string>;
+    /** Data attributes applied */
+    readonly dataAttributes: readonly string[];
+    /** Generated slots */
+    readonly slots: readonly GeneratedSlot[];
+    /** Metadata about generation */
+    readonly metadata: SectionGenerationMetadata;
+}
+/**
+ * Section generation metadata
+ */
+export interface SectionGenerationMetadata {
+    /** Section ID */
+    readonly sectionId: string;
+    /** Section type */
+    readonly sectionType: string;
+    /** Design system used */
+    readonly designSystem: DesignSystem;
+    /** Quality tier */
+    readonly tier: Tier;
+    /** Factors applied count */
+    readonly factorsApplied: number;
+    /** Components generated */
+    readonly componentsGenerated: number;
+    /** Lines of code */
+    readonly linesOfCode: number;
+    /** Generation timestamp */
+    readonly generatedAt: Date;
+    /** Section generation result (if section generator was used) */
+    readonly sectionGenerationResult?: ComponentSectionGenerationResult;
+}
+/**
+ * Section Generator
+ *
+ * Generates complete section JSX from SectionConfig and SectionFactors.
+ * Handles slot resolution and factor propagation to child components.
+ *
+ * @example
+ * ```typescript
+ * const generator = new SectionGenerator();
+ *
+ * const result = generator.generate({
+ *   config: {
+ *     sectionId: 'hero-1',
+ *     sectionType: 'hero',
+ *     title: 'Welcome',
+ *     designSystem: 'material-design',
+ *     tier: 'enterprise',
+ *     layout: 'flex',
+ *     columns: 2,
+ *     spacing: 'lg',
+ *   },
+ *   factors: {
+ *     colorPrimary: '#2196f3',
+ *     // ... other 12 factors
+ *   },
+ * });
+ *
+ * console.log(result.jsx);
+ * ```
+ */
+export declare class SectionGenerator {
+    private readonly defaultOptions;
+    private readonly orchestrator;
+    /**
+     * Create a new SectionGenerator instance
+     *
+     * @param options - Default generator options
+     */
+    constructor(options?: SectionGeneratorOptions);
+    /**
+     * Generate a section from config and factors
+     *
+     * @param input - Section generation input
+     * @returns Section generation result
+     */
+    generate(input: SectionGenerationInput): SectionGenerationResult;
+    /**
+     * Generate a section asynchronously with full orchestration support
+     *
+     * @param input - Section generation input (must include storedComponents)
+     * @returns Promise of section generation result with orchestration
+     */
+    generateAsync(input: SectionGenerationInput): Promise<SectionGenerationResult>;
+    /**
+     * Enhance generation with orchestrator (internal async helper)
+     */
+    private enhanceWithSectionGenerator;
+    /**
+     * Convert section generation result to GeneratedSlot array
+     */
+    private convertSectionGenerationToSlots;
+    /**
+     * Generate section from SectionWithFactors interface
+     *
+     * @param sectionWithFactors - Section with embedded factors
+     * @returns Section generation result
+     */
+    generateFromSectionWithFactors(sectionWithFactors: SectionWithFactors): SectionGenerationResult;
+    /**
+     * Transform SectionConfig to JSX string
+     *
+     * @param config - Section configuration
+     * @param factors - Section factors
+     * @returns JSX string
+     */
+    transformToJsx(config: SectionConfig, factors: SectionFactors): string;
+    /**
+     * Get layout classes for a section
+     *
+     * @param layout - Layout type
+     * @param columns - Column count
+     * @param spacing - Spacing level
+     * @returns Tailwind class string
+     */
+    getLayoutClasses(layout: LayoutType, columns: 1 | 2 | 3 | 4 | 6, spacing: SpacingLevel): string;
+    /**
+     * Validate generation input
+     */
+    private validateInput;
+    /**
+     * Build CSS classes from config and factors
+     */
+    private buildCssClasses;
+    /**
+     * Build CSS variables from factors
+     */
+    private buildCssVariables;
+    /**
+     * Build data attributes from config and factors
+     */
+    private buildDataAttributes;
+    /**
+     * Generate slots from config
+     */
+    private generateSlots;
+    /**
+     * Generate a single slot
+     */
+    private generateSlot;
+    /**
+     * Generate slot content placeholder
+     */
+    private generateSlotContent;
+    /**
+     * Get slot classes based on position
+     */
+    private getSlotClasses;
+    /**
+     * Generate complete JSX
+     */
+    private generateJsx;
+    /**
+     * Generate file header
+     */
+    private generateHeader;
+    /**
+     * Generate imports based on tier
+     */
+    private generateImports;
+    /**
+     * Generate props interface
+     */
+    private generatePropsInterface;
+    /**
+     * Generate component body based on tier
+     */
+    private generateComponentBody;
+    /**
+     * Generate basic tier component body
+     */
+    private generateBasicBody;
+    /**
+     * Generate standard tier component body
+     */
+    private generateStandardBody;
+    /**
+     * Generate enterprise tier component body
+     */
+    private generateEnterpriseBody;
+    /**
+     * Build style object string from CSS variables
+     */
+    private buildStyleObject;
+    /**
+     * Get component name from config
+     */
+    private getComponentName;
+    /**
+     * Build generation metadata
+     */
+    private buildMetadata;
+    /**
+     * Create error result
+     */
+    private createErrorResult;
+}
+/**
+ * Create a new SectionGenerator instance
+ *
+ * @param options - Generator options
+ * @returns New SectionGenerator instance
+ */
+export declare function createSectionGenerator(options?: SectionGeneratorOptions): SectionGenerator;
+/**
+ * Generate a section with default options (convenience wrapper)
+ *
+ * @param input - Section generation input
+ * @returns Section generation result
+ */
+export declare function generateSection(input: SectionGenerationInput): SectionGenerationResult;
+/**
+ * Transform SectionConfig to JSX (convenience wrapper)
+ *
+ * @param config - Section configuration
+ * @param factors - Section factors
+ * @returns JSX string
+ */
+export declare function transformSectionToJsx(config: SectionConfig, factors: SectionFactors): string;
+/**
+ * Generate a section with full orchestration support (async)
+ *
+ * @param input - Section generation input with storedComponents
+ * @returns Promise of section generation result
+ *
+ * @example
+ * ```typescript
+ * const result = await generateSectionAsync({
+ *   config: sectionConfig,
+ *   factors: sectionFactors,
+ *   storedComponents: [
+ *     { instanceId: 'header-1', componentRef: 'button', visible: true },
+ *   ],
+ * });
+ *
+ * if (result.success) {
+ *   console.log(result.metadata.sectionGenerationResult?.composedCode);
+ * }
+ * ```
+ */
+export declare function generateSectionAsync(input: SectionGenerationInput): Promise<SectionGenerationResult>;
+//# sourceMappingURL=SectionGenerator.d.ts.map

package/dist/ui-studio/composition/SlotResolver.d.ts

@@ -0,0 +1,295 @@
+/**
+ * Slot Resolver
+ * Resolves slots in sections to actual component instances
+ *
+ * @packageDocumentation
+ * @module generators/SlotResolver
+ * @since 4.0.0
+ *
+ * The SlotResolver:
+ * 1. Takes SlotConfig definitions
+ * 2. Looks up components from the component registry
+ * 3. Resolves stored component instances
+ * 4. Returns ready-to-render component configurations
+ *
+ * Powered by Nikkory
+ */
+import { getComponentEntry } from '../registries/components-registry';
+import type { SlotConfig, SlotPosition, ComponentType, DesignSystem, Tier } from '../types';
+/**
+ * Stored component instance in a slot
+ * Represents a user's customized component placement
+ */
+export interface StoredComponentInSlot {
+    /** Reference to component type */
+    readonly componentRef: ComponentType;
+    /** Unique instance ID for this placement */
+    readonly instanceId: string;
+    /** User's property overrides */
+    readonly propOverrides: Record<string, unknown>;
+    /** Order within the slot */
+    readonly order: number;
+    /** Whether visible in this section */
+    readonly visible: boolean;
+}
+/**
+ * Resolved component ready for rendering
+ */
+export interface ResolvedComponent {
+    /** Component type */
+    readonly componentType: ComponentType;
+    /** Instance ID */
+    readonly instanceId: string;
+    /** Display name */
+    readonly displayName: string;
+    /** Category */
+    readonly category: string;
+    /** Final props (merged from defaults and overrides) */
+    readonly props: Record<string, unknown>;
+    /** Whether component supports the design system */
+    readonly supportsDesignSystem: boolean;
+    /** Whether component supports the tier */
+    readonly supportsTier: boolean;
+    /** Render order */
+    readonly order: number;
+    /** Visibility */
+    readonly visible: boolean;
+}
+/**
+ * Resolved slot with all components
+ */
+export interface ResolvedSlot {
+    /** Slot ID */
+    readonly slotId: string;
+    /** Slot position */
+    readonly position: SlotPosition;
+    /** Resolved components */
+    readonly components: readonly ResolvedComponent[];
+    /** Number of components */
+    readonly componentCount: number;
+    /** Whether slot is empty */
+    readonly isEmpty: boolean;
+    /** Whether slot has room for more components */
+    readonly hasCapacity: boolean;
+    /** Remaining capacity */
+    readonly remainingCapacity: number;
+}
+/**
+ * Slot resolution input
+ */
+export interface SlotResolutionInput {
+    /** Slot configuration */
+    readonly slot: SlotConfig;
+    /** Stored components in slot */
+    readonly storedComponents: readonly StoredComponentInSlot[];
+    /** Design system context */
+    readonly designSystem: DesignSystem;
+    /** Tier context */
+    readonly tier: Tier;
+}
+/**
+ * Slot resolution result
+ */
+export interface SlotResolutionResult {
+    /** Whether resolution succeeded */
+    readonly success: boolean;
+    /** Error message if failed */
+    readonly error?: string;
+    /** Resolved slot */
+    readonly slot: ResolvedSlot;
+    /** Warnings (e.g., incompatible components) */
+    readonly warnings: readonly string[];
+}
+/**
+ * Batch slot resolution input
+ */
+export interface BatchSlotResolutionInput {
+    /** Slot configurations */
+    readonly slots: readonly SlotConfig[];
+    /** Map of slot ID to stored components */
+    readonly storedComponentsMap: Record<string, readonly StoredComponentInSlot[]>;
+    /** Design system context */
+    readonly designSystem: DesignSystem;
+    /** Tier context */
+    readonly tier: Tier;
+}
+/**
+ * Batch slot resolution result
+ */
+export interface BatchSlotResolutionResult {
+    /** Whether all resolutions succeeded */
+    readonly success: boolean;
+    /** Resolved slots by ID */
+    readonly slots: Record<string, ResolvedSlot>;
+    /** All warnings */
+    readonly warnings: readonly string[];
+    /** Total components resolved */
+    readonly totalComponentsResolved: number;
+}
+/**
+ * Slot resolver options
+ */
+export interface SlotResolverOptions {
+    /** Include default components if slot is empty */
+    readonly includeDefaults?: boolean;
+    /** Filter out invisible components */
+    readonly filterInvisible?: boolean;
+    /** Validate component compatibility */
+    readonly validateCompatibility?: boolean;
+    /** Strict mode - fail on incompatible components */
+    readonly strictMode?: boolean;
+}
+/**
+ * Slot Resolver
+ *
+ * Resolves slots in sections to actual component instances.
+ * Handles component lookup, validation, and prop merging.
+ *
+ * @example
+ * ```typescript
+ * const resolver = new SlotResolver();
+ *
+ * const result = resolver.resolve({
+ *   slot: {
+ *     slotId: 'header-slot',
+ *     position: 'header',
+ *     allowedComponents: ['button', 'input'],
+ *     maxComponents: 3,
+ *   },
+ *   storedComponents: [
+ *     {
+ *       componentRef: 'button',
+ *       instanceId: 'btn-1',
+ *       propOverrides: { variant: 'primary' },
+ *       order: 0,
+ *       visible: true,
+ *     }
+ *   ],
+ *   designSystem: 'material-design',
+ *   tier: 'enterprise',
+ * });
+ *
+ * console.log(result.slot.components);
+ * ```
+ */
+export declare class SlotResolver {
+    private readonly options;
+    /**
+     * Create a new SlotResolver instance
+     *
+     * @param options - Resolver options
+     */
+    constructor(options?: SlotResolverOptions);
+    /**
+     * Resolve a single slot
+     *
+     * @param input - Slot resolution input
+     * @returns Slot resolution result
+     */
+    resolve(input: SlotResolutionInput): SlotResolutionResult;
+    /**
+     * Resolve multiple slots in batch
+     *
+     * @param input - Batch resolution input
+     * @returns Batch resolution result
+     */
+    resolveBatch(input: BatchSlotResolutionInput): BatchSlotResolutionResult;
+    /**
+     * Check if a component is allowed in a slot
+     *
+     * @param componentType - Component type to check
+     * @param slot - Slot configuration
+     * @returns Whether component is allowed
+     */
+    isComponentAllowed(componentType: ComponentType, slot: SlotConfig): boolean;
+    /**
+     * Check if a component supports a design system
+     *
+     * @param componentType - Component type
+     * @param designSystem - Design system
+     * @returns Whether component supports the design system
+     */
+    componentSupportsDesignSystem(componentType: ComponentType, designSystem: DesignSystem): boolean;
+    /**
+     * Check if a component supports a tier
+     *
+     * @param componentType - Component type
+     * @param tier - Quality tier
+     * @returns Whether component supports the tier
+     */
+    componentSupportsTier(componentType: ComponentType, tier: Tier): boolean;
+    /**
+     * Get all allowed components for a slot that support a design system and tier
+     *
+     * @param slot - Slot configuration
+     * @param designSystem - Design system
+     * @param tier - Quality tier
+     * @returns Array of compatible component types
+     */
+    getCompatibleComponents(slot: SlotConfig, designSystem: DesignSystem, tier: Tier): ComponentType[];
+    /**
+     * Lookup a component by type
+     *
+     * @param componentType - Component type to lookup
+     * @returns Component entry or undefined
+     */
+    lookupComponent(componentType: ComponentType): ReturnType<typeof getComponentEntry>;
+    /**
+     * Get all available component types
+     *
+     * @returns Array of all component types
+     */
+    getAllComponentTypes(): ComponentType[];
+    /**
+     * Validate slot configuration
+     *
+     * @param slot - Slot configuration to validate
+     * @returns Validation result
+     */
+    validateSlot(slot: SlotConfig): {
+        valid: boolean;
+        errors: string[];
+    };
+    /**
+     * Resolve a single component
+     */
+    private resolveComponent;
+    /**
+     * Get default props for a component
+     */
+    private getDefaultProps;
+    /**
+     * Create an empty resolved slot
+     */
+    private createEmptySlot;
+}
+/**
+ * Create a new SlotResolver instance
+ *
+ * @param options - Resolver options
+ * @returns New SlotResolver instance
+ */
+export declare function createSlotResolver(options?: SlotResolverOptions): SlotResolver;
+/**
+ * Resolve a slot (convenience wrapper)
+ *
+ * @param input - Slot resolution input
+ * @returns Slot resolution result
+ */
+export declare function resolveSlot(input: SlotResolutionInput): SlotResolutionResult;
+/**
+ * Resolve multiple slots (convenience wrapper)
+ *
+ * @param input - Batch resolution input
+ * @returns Batch resolution result
+ */
+export declare function resolveSlots(input: BatchSlotResolutionInput): BatchSlotResolutionResult;
+/**
+ * Check if a component is allowed in a slot (convenience wrapper)
+ *
+ * @param componentType - Component type
+ * @param slot - Slot configuration
+ * @returns Whether component is allowed
+ */
+export declare function isComponentAllowedInSlot(componentType: ComponentType, slot: SlotConfig): boolean;
+//# sourceMappingURL=SlotResolver.d.ts.map