@nikkory/vibe-engine 4.0.0

package/dist/types/section.types.d.ts

@@ -0,0 +1,326 @@
+/**
+ * Section Architecture Types
+ * Core type definitions for Section configuration
+ *
+ * @packageDocumentation
+ * @module types/section
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+import type { DesignSystem, Tier, ComponentType } from './index';
+/**
+ * Section categories - 10 total
+ */
+export type SectionCategory = 'hero' | 'features' | 'testimonials' | 'pricing' | 'cta' | 'faq' | 'team' | 'contact' | 'gallery' | 'stats';
+/**
+ * Layout types for sections
+ *
+ * @remarks
+ * Base layout types:
+ * - grid: Grid-based layout
+ * - flex: Flexbox layout
+ * - stack: Vertical stacked layout
+ * - masonry: Pinterest-style masonry
+ * - carousel: Horizontal scrolling carousel
+ *
+ * Section-specific layouts:
+ * - centered: Content centered on page
+ * - split: Two-column split (content + media)
+ * - fullwidth: Full-width edge-to-edge
+ * - alternating: Alternating left/right pattern
+ * - sidebar: Main content with sidebar
+ * - asymmetric: Non-uniform grid layout
+ */
+export type LayoutType = 'grid' | 'flex' | 'stack' | 'masonry' | 'carousel' | 'centered' | 'split' | 'fullwidth' | 'alternating' | 'sidebar' | 'asymmetric';
+/**
+ * Spacing levels
+ */
+export type SpacingLevel = 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
+/**
+ * Typography scales
+ */
+export type TypographyScale = 'compact' | 'default' | 'relaxed' | 'spacious';
+/**
+ * Border radius levels
+ */
+export type RadiusLevel = 'none' | 'sm' | 'md' | 'lg' | 'xl' | 'full';
+/**
+ * Elevation/shadow levels
+ */
+export type ElevationLevel = 'none' | 'sm' | 'md' | 'lg' | 'xl';
+/**
+ * Alignment types
+ */
+export type AlignmentType = 'start' | 'center' | 'end' | 'stretch' | 'between';
+/**
+ * Max width constraints
+ */
+export type MaxWidthLevel = 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'full';
+/**
+ * Animation presets
+ */
+export type AnimationPreset = 'none' | 'subtle' | 'smooth' | 'dynamic' | 'playful';
+/**
+ * Accessibility levels
+ */
+export type A11yLevel = 'standard' | 'enhanced' | 'maximum';
+/**
+ * Responsive configuration
+ */
+export interface ResponsiveConfig {
+    readonly mobile: LayoutType;
+    readonly tablet: LayoutType;
+    readonly desktop: LayoutType;
+}
+/**
+ * Style overrides for customization
+ */
+export interface StyleOverrides {
+    readonly className?: string;
+    readonly style?: Record<string, string>;
+    readonly tailwindClasses?: string;
+}
+/**
+ * Slot position within section
+ */
+export type SlotPosition = 'header' | 'content' | 'footer' | 'sidebar' | 'overlay';
+/**
+ * Slot configuration
+ */
+export interface SlotConfig {
+    /** Slot identifier */
+    readonly slotId: string;
+    /** Slot position */
+    readonly position: SlotPosition;
+    /** Allowed component types */
+    readonly allowedComponents: readonly ComponentType[];
+    /** Maximum components in slot */
+    readonly maxComponents: number;
+    /** Default component to place */
+    readonly defaultComponent?: ComponentType;
+}
+/**
+ * Stored component instance in slot
+ *
+ * @remarks
+ * Represents a component placed in a section slot with user customizations.
+ * This allows users to customize component props while maintaining the base
+ * component definition.
+ *
+ * @example
+ * ```typescript
+ * const storedButton: StoredComponentInSlot = {
+ *   componentRef: 'button',
+ *   instanceId: 'hero-cta-button-1',
+ *   propOverrides: {
+ *     variant: 'filled',
+ *     size: 'lg',
+ *     label: 'Get Started'
+ *   },
+ *   order: 0,
+ *   visible: true
+ * };
+ * ```
+ */
+export interface StoredComponentInSlot {
+    /** Reference to component definition (ComponentType) */
+    readonly componentRef: ComponentType;
+    /** Instance ID for this placement (unique within section) */
+    readonly instanceId: string;
+    /** User's prop overrides for this instance */
+    readonly propOverrides: Record<string, unknown>;
+    /** Position within slot (order, 0-indexed) */
+    readonly order: number;
+    /** Visibility in this section */
+    readonly visible: boolean;
+}
+/**
+ * Section-Level Fields (6 fields)
+ *
+ * @remarks
+ * Core identification and configuration for a section.
+ *
+ * Field Mapping from RegistrySectionDefinition:
+ * - `sectionId` ← Registry `id` (unique identifier)
+ * - `sectionType` ← Registry `category` (hero, features, pricing, etc.)
+ *
+ * Use `toSectionConfig()` from `converters/section-converter` to convert
+ * a RegistrySectionDefinition to SectionConfig automatically.
+ */
+export interface SectionLevelFields {
+    /**
+     * Unique section identifier
+     * @remarks Maps from Registry `id` field
+     */
+    readonly sectionId: string;
+    /**
+     * Section type (hero, features, pricing, etc.)
+     * @remarks Maps from Registry `category` field
+     */
+    readonly sectionType: SectionCategory;
+    /** Title displayed in section */
+    readonly title: string;
+    /** Subtitle/description */
+    readonly subtitle?: string;
+    /** Design system to use */
+    readonly designSystem: DesignSystem;
+    /** Quality tier */
+    readonly tier: Tier;
+}
+/**
+ * Layout Fields (3 fields)
+ *
+ * @remarks
+ * Controls the visual arrangement of section content.
+ *
+ * Field Mapping from RegistrySectionDefinition:
+ * - `layout` ← Registry `sectionLayout` (grid, flex, stack, etc.)
+ *
+ * Note: Registry has two layout fields:
+ * - `sectionLayout` (LayoutType) - used for generation
+ * - `layout` (display pattern) - used for UI preview only
+ */
+export interface LayoutFields {
+    /**
+     * Grid/Flex layout type
+     * @remarks Maps from Registry `sectionLayout` field
+     */
+    readonly layout: LayoutType;
+    /** Number of columns (for grid) */
+    readonly columns: 1 | 2 | 3 | 4 | 6;
+    /** Spacing between elements */
+    readonly spacing: SpacingLevel;
+}
+/**
+ * Generation Fields (2 fields)
+ *
+ * @remarks
+ * Configuration for dynamic content generation
+ */
+export interface GenerationFields {
+    /** Optional slots configuration */
+    readonly slots?: readonly SlotConfig[];
+    /** Number of items to generate */
+    readonly itemCount?: number;
+}
+/**
+ * Component-Specific Fields (3 fields)
+ *
+ * @remarks
+ * Optional features for section rendering
+ */
+export interface ComponentSpecificFields {
+    /** Show CTA button */
+    readonly showCta?: boolean;
+    /** Show images/media */
+    readonly showMedia?: boolean;
+    /** Custom styling overrides */
+    readonly styleOverrides?: StyleOverrides;
+}
+/**
+ * Complete SectionConfig - 14 Fields
+ *
+ * @remarks
+ * Intersection of all 4 groups forming the complete section configuration.
+ * This is the primary interface for defining section behavior and appearance.
+ *
+ * @example
+ * ```typescript
+ * const heroConfig: SectionConfig = {
+ *   // Section-Level (6)
+ *   sectionId: 'hero-1',
+ *   sectionType: 'hero',
+ *   title: 'Welcome to Our Platform',
+ *   subtitle: 'Build amazing experiences',
+ *   designSystem: 'material-design',
+ *   tier: 'enterprise',
+ *   // Layout (3)
+ *   layout: 'flex',
+ *   columns: 2,
+ *   spacing: 'lg',
+ *   // Generation (2)
+ *   slots: [],
+ *   itemCount: 1,
+ *   // Component-Specific (3)
+ *   showCta: true,
+ *   showMedia: true,
+ *   styleOverrides: { className: 'hero-custom' }
+ * };
+ * ```
+ */
+export interface SectionConfig extends SectionLevelFields, LayoutFields, GenerationFields, ComponentSpecificFields {
+}
+/**
+ * 13 Factors that Section defines for Components
+ *
+ * @remarks
+ * When Section sets these, Components inherit automatically.
+ * This enables consistent styling across all components within a section.
+ *
+ * @example
+ * ```typescript
+ * const factors: SectionFactors = {
+ *   // Visual (6)
+ *   colorPrimary: '#2196f3',
+ *   colorText: '#1a1a1a',
+ *   colorBackground: '#ffffff',
+ *   typography: 'default',
+ *   borderRadius: 'md',
+ *   elevation: 'sm',
+ *   // Layout (4)
+ *   padding: 'lg',
+ *   gap: 'md',
+ *   alignment: 'center',
+ *   maxWidth: 'xl',
+ *   // Behavior (3)
+ *   animation: 'smooth',
+ *   responsive: { mobile: 'stack', tablet: 'grid', desktop: 'grid' },
+ *   a11yLevel: 'enhanced'
+ * };
+ * ```
+ */
+export interface SectionFactors {
+    /** Factor 1: Primary color palette */
+    readonly colorPrimary: string;
+    /** Factor 2: Text color */
+    readonly colorText: string;
+    /** Factor 3: Background color */
+    readonly colorBackground: string;
+    /** Factor 4: Typography scale */
+    readonly typography: TypographyScale;
+    /** Factor 5: Border radius */
+    readonly borderRadius: RadiusLevel;
+    /** Factor 6: Shadow level */
+    readonly elevation: ElevationLevel;
+    /** Factor 7: Padding level */
+    readonly padding: SpacingLevel;
+    /** Factor 8: Gap between items */
+    readonly gap: SpacingLevel;
+    /** Factor 9: Alignment */
+    readonly alignment: AlignmentType;
+    /** Factor 10: Max width constraint */
+    readonly maxWidth: MaxWidthLevel;
+    /** Factor 11: Animation preset */
+    readonly animation: AnimationPreset;
+    /** Factor 12: Responsive breakpoint behavior */
+    readonly responsive: ResponsiveConfig;
+    /** Factor 13: Accessibility level */
+    readonly a11yLevel: A11yLevel;
+}
+/**
+ * Partial section factors for overrides
+ */
+export type PartialSectionFactors = Partial<SectionFactors>;
+/**
+ * Section configuration with factors
+ *
+ * @remarks
+ * Combines SectionConfig with SectionFactors for complete section definition.
+ * Use this when you need both configuration and styling factors.
+ */
+export interface SectionWithFactors extends SectionConfig {
+    /** Section styling factors */
+    readonly factors: SectionFactors;
+}
+//# sourceMappingURL=section.types.d.ts.map

package/dist/ui-studio/ComponentGenerator.d.ts

@@ -0,0 +1,219 @@
+/**
+ * Component Generator - Orchestrator
+ * Uses Matrix Multiplication system (M1×M2×M3×M4) for complete component generation
+ *
+ * @packageDocumentation
+ * @module generators/ComponentGenerator
+ * @since 4.0.0
+ *
+ * The ComponentGenerator is the main orchestrator that:
+ * 1. Validates input (component, design system, tier)
+ * 2. Uses MatrixResolver for M1×M2×M3×M4 multiplication
+ * 3. Uses TemplateEngine for code generation
+ * 4. Wraps output in legacy format for backward compatibility
+ *
+ * Powered by Nikkory
+ */
+import type { Tier, DesignSystem, ComponentType } from '../types';
+import type { GenerationInput, GenerationOutput, GenerationMetadata, FactorId, ResolvedFactors } from '../types/algorithm-engine.types';
+/**
+ * Style Output
+ * Contains all style-related generation output
+ */
+export interface StyleOutput {
+    /** Combined Tailwind classes */
+    readonly tailwindClasses: string;
+    /** CSS variables for theme integration */
+    readonly cssVariables: Record<string, string>;
+    /** Data attributes for state-based styling */
+    readonly dataAttributes: string[];
+    /** Generated theme CSS (@theme block for Tailwind v4) */
+    readonly themeCss?: string;
+}
+/**
+ * Code Output
+ * Contains all code-related generation output
+ */
+export interface CodeOutput {
+    /** Component code */
+    readonly componentCode: string;
+    /** Types file content (if requested) */
+    readonly typesCode?: string;
+    /** Test file content (if requested) */
+    readonly testCode?: string;
+    /** Storybook story content (if requested) */
+    readonly storyCode?: string;
+}
+/**
+ * Component Generation Result
+ * Extended result including both code and style outputs
+ */
+export interface ComponentGenerationResult {
+    /** Whether generation succeeded */
+    readonly success: boolean;
+    /** Error message if failed */
+    readonly error?: string;
+    /** Generated code output */
+    readonly code: CodeOutput;
+    /** Generated style output */
+    readonly style: StyleOutput;
+    /** Resolved factors used in generation */
+    readonly resolvedFactors: ResolvedFactors;
+    /** Generation metadata */
+    readonly metadata: GenerationMetadata;
+}
+/**
+ * Component Generator
+ *
+ * Main orchestrator that uses Matrix Multiplication system (System 3)
+ * for component generation with full backward compatibility.
+ *
+ * @example
+ * ```typescript
+ * const generator = new ComponentGenerator();
+ *
+ * const result = generator.generate({
+ *   componentType: 'button',
+ *   designSystem: 'material-design',
+ *   tier: 'enterprise',
+ *   factorOverrides: { 2: 'lg' }, // Override size
+ * });
+ *
+ * console.log(result.code.componentCode);  // 45 lines, clean code
+ * console.log(result.style.tailwindClasses);
+ * ```
+ */
+export declare class ComponentGenerator {
+    private readonly factorResolver;
+    private readonly matrixResolver;
+    private readonly tierGenerator;
+    private readonly typesGenerator;
+    private readonly testGenerator;
+    /**
+     * Create a new ComponentGenerator instance
+     */
+    constructor();
+    /**
+     * Generate a complete component with code and styles
+     * REFACTORED to use Matrix Multiplication system (System 3)
+     *
+     * @param input - Generation input parameters
+     * @returns Complete generation result with code and styles
+     *
+     * @remarks
+     * Generation flow (NEW):
+     * 1. Validate input (component, design system, tier)
+     * 2. Convert to Matrix input format
+     * 3. Resolve using MatrixResolver (M1×M2×M3×M4)
+     * 4. Generate code using TemplateEngine
+     * 5. Wrap in legacy format for backward compatibility
+     */
+    generate(input: GenerationInput): ComponentGenerationResult;
+    /**
+     * Generate component output in the standard format
+     *
+     * @param input - Generation input
+     * @returns GenerationOutput compatible with existing interfaces
+     */
+    generateOutput(input: GenerationInput): GenerationOutput;
+    /**
+     * Get Tailwind classes for a component configuration
+     *
+     * @param input - Generation input
+     * @returns Tailwind class string
+     */
+    getTailwindClasses(input: GenerationInput): string;
+    /**
+     * Get CSS variables for a component configuration
+     *
+     * @param input - Generation input
+     * @returns CSS variables object
+     */
+    getCssVariables(input: GenerationInput): Record<string, string>;
+    /**
+     * Get data attributes for a component configuration
+     *
+     * @param input - Generation input
+     * @returns Array of data attribute strings
+     */
+    getDataAttributes(input: GenerationInput): string[];
+    /**
+     * Generate theme CSS for Tailwind v4 @theme block
+     *
+     * @param designSystem - Design system to generate theme for
+     * @returns CSS string with @theme block
+     */
+    generateThemeCss(designSystem: DesignSystem): string;
+    /**
+     * Validate generation input
+     *
+     * @param componentType - Component type
+     * @param designSystem - Design system
+     * @param tier - Quality tier
+     * @returns Validation result
+     */
+    validateInput(componentType: ComponentType, designSystem: DesignSystem, tier: Tier): {
+        valid: boolean;
+        error?: string;
+    };
+    /**
+     * Build data attributes for Hybrid integration
+     */
+    private buildDataAttributes;
+    /**
+     * Get data attribute name for a factor
+     *
+     * @param factorId - Factor ID (1-24)
+     * @returns Data attribute name (e.g., 'color', 'size') or 'factor-N' fallback for unknown IDs
+     */
+    getDataAttributeName(factorId: FactorId): string;
+    /**
+     * Convert GenerationInput → MatrixResolverInput
+     * Translates legacy API format to Matrix system format
+     *
+     * @param input - Legacy generation input
+     * @returns Matrix resolver input
+     */
+    private convertToMatrixInput;
+    /**
+     * Wrap Matrix output → ComponentGenerationResult (legacy format)
+     * Maintains backward compatibility with existing API consumers
+     *
+     * @param componentCode - Generated TypeScript component code
+     * @param typesCode - Generated TypeScript types code
+     * @param testCode - Generated test code
+     * @param resolved - Resolved component configuration from Matrix
+     * @param input - Original generation input (for metadata)
+     * @returns Legacy-format generation result
+     */
+    private wrapInLegacyFormat;
+    /**
+     * Format component name from type, design system, and tier
+     */
+    private formatComponentName;
+    /**
+     * Create error result
+     */
+    private createErrorResult;
+}
+/**
+ * Create a new ComponentGenerator instance
+ *
+ * @returns New ComponentGenerator instance
+ */
+export declare function createComponentGenerator(): ComponentGenerator;
+/**
+ * Generate a component with default options (convenience wrapper)
+ *
+ * @param input - Generation input
+ * @returns Component generation result
+ */
+export declare function generateComponent(input: GenerationInput): ComponentGenerationResult;
+/**
+ * Generate a component and return standard output format
+ *
+ * @param input - Generation input
+ * @returns GenerationOutput
+ */
+export declare function generateComponentOutput(input: GenerationInput): GenerationOutput;
+//# sourceMappingURL=ComponentGenerator.d.ts.map