@nikkory/vibe-engine 4.0.0

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

@@ -0,0 +1,268 @@
+/**
+ * Factor Propagator
+ * Propagates 13 section factors to child components
+ *
+ * @packageDocumentation
+ * @module generators/FactorPropagator
+ * @since 4.0.0
+ *
+ * The FactorPropagator:
+ * 1. Takes 13 SectionFactors
+ * 2. Maps factors to component props
+ * 3. Filters factors by tier availability
+ * 4. Generates CSS variables and data attributes
+ *
+ * Powered by Nikkory
+ */
+import type { Tier } from '../../types';
+import type { FactorId } from '../../types/algorithm-engine.types';
+import type { SectionFactors } from '../../types/section.types';
+/**
+ * Factor to prop mapping definition
+ */
+export interface FactorPropMapping {
+    /** Factor name (from SectionFactors) */
+    readonly factorName: keyof SectionFactors;
+    /** Component prop name */
+    readonly propName: string;
+    /** CSS variable name */
+    readonly cssVariable: string;
+    /** Data attribute name */
+    readonly dataAttribute: string;
+    /** Tailwind class prefix */
+    readonly tailwindPrefix?: string;
+    /** Factor ID (1-24) for tier filtering */
+    readonly factorId: FactorId;
+    /** Factor category */
+    readonly category: 'visual' | 'layout' | 'behavior';
+}
+/**
+ * Propagated factor result
+ */
+export interface PropagatedFactor {
+    /** Factor name */
+    readonly name: string;
+    /** Factor value */
+    readonly value: string;
+    /** Mapped prop name */
+    readonly propName: string;
+    /** CSS variable */
+    readonly cssVariable: string;
+    /** Data attribute */
+    readonly dataAttribute: string;
+    /** Generated Tailwind class (if applicable) */
+    readonly tailwindClass?: string;
+    /** Whether factor is enabled for the tier */
+    readonly enabledForTier: boolean;
+}
+/**
+ * Factor propagation result
+ */
+export interface FactorPropagationResult {
+    /** All propagated factors */
+    readonly factors: readonly PropagatedFactor[];
+    /** Factors enabled for tier */
+    readonly enabledFactors: readonly PropagatedFactor[];
+    /** Factors disabled for tier */
+    readonly disabledFactors: readonly PropagatedFactor[];
+    /** Props object for component */
+    readonly props: Record<string, unknown>;
+    /** CSS variables object */
+    readonly cssVariables: Record<string, string>;
+    /** Data attributes array */
+    readonly dataAttributes: readonly string[];
+    /** Tailwind classes string */
+    readonly tailwindClasses: string;
+}
+/**
+ * Factor propagation input
+ */
+export interface FactorPropagationInput {
+    /** Section factors (13 factors) */
+    readonly factors: SectionFactors;
+    /** Quality tier for filtering */
+    readonly tier: Tier;
+    /** Component type (for specific mappings) */
+    readonly componentType?: string;
+    /** Override specific factor mappings */
+    readonly mappingOverrides?: Partial<Record<keyof SectionFactors, string>>;
+}
+/**
+ * Factor propagator options
+ */
+export interface FactorPropagatorOptions {
+    /** Include disabled factors in output */
+    readonly includeDisabled?: boolean;
+    /** Prefix for CSS variables */
+    readonly cssVariablePrefix?: string;
+    /** Prefix for data attributes */
+    readonly dataAttributePrefix?: string;
+    /** Generate Tailwind classes */
+    readonly generateTailwind?: boolean;
+}
+/**
+ * Complete mapping of 13 section factors to component props
+ *
+ * @remarks
+ * Each section factor maps to:
+ * - Component prop name
+ * - CSS variable
+ * - Data attribute
+ * - Optional Tailwind prefix
+ */
+export declare const SECTION_FACTOR_MAPPINGS: readonly FactorPropMapping[];
+/**
+ * Factor Propagator
+ *
+ * Propagates 13 section factors to child components with tier-based filtering.
+ * Maps factors to props, CSS variables, data attributes, and Tailwind classes.
+ *
+ * @example
+ * ```typescript
+ * const propagator = new FactorPropagator();
+ *
+ * const result = propagator.propagate({
+ *   factors: {
+ *     colorPrimary: '#2196f3',
+ *     colorText: '#1a1a1a',
+ *     colorBackground: '#ffffff',
+ *     typography: 'default',
+ *     borderRadius: 'md',
+ *     elevation: 'sm',
+ *     padding: 'lg',
+ *     gap: 'md',
+ *     alignment: 'center',
+ *     maxWidth: 'xl',
+ *     animation: 'smooth',
+ *     responsive: { mobile: 'stack', tablet: 'grid', desktop: 'grid' },
+ *     a11yLevel: 'enhanced',
+ *   },
+ *   tier: 'enterprise',
+ * });
+ *
+ * console.log(result.props);
+ * console.log(result.tailwindClasses);
+ * ```
+ */
+export declare class FactorPropagator {
+    private readonly options;
+    /**
+     * Create a new FactorPropagator instance
+     *
+     * @param options - Propagator options
+     */
+    constructor(options?: FactorPropagatorOptions);
+    /**
+     * Propagate factors to component props
+     *
+     * @param input - Factor propagation input
+     * @returns Factor propagation result
+     */
+    propagate(input: FactorPropagationInput): FactorPropagationResult;
+    /**
+     * Get factors enabled for a specific tier
+     *
+     * @param tier - Quality tier
+     * @returns Factor IDs enabled for tier
+     */
+    getFactorsForTier(tier: Tier): readonly FactorId[];
+    /**
+     * Check if a factor is enabled for a tier
+     *
+     * @param factorName - Factor name
+     * @param tier - Quality tier
+     * @returns Whether factor is enabled
+     */
+    isFactorEnabled(factorName: keyof SectionFactors, tier: Tier): boolean;
+    /**
+     * Get all factor mappings
+     *
+     * @returns All 13 factor mappings
+     */
+    getAllMappings(): readonly FactorPropMapping[];
+    /**
+     * Get mappings by category
+     *
+     * @param category - Factor category
+     * @returns Factor mappings in category
+     */
+    getMappingsByCategory(category: 'visual' | 'layout' | 'behavior'): readonly FactorPropMapping[];
+    /**
+     * Get Tailwind class for a factor value
+     *
+     * @param factorName - Factor name
+     * @param value - Factor value
+     * @returns Tailwind class or undefined
+     */
+    getTailwindClass(factorName: keyof SectionFactors, value: unknown): string | undefined;
+    /**
+     * Map a single factor to component prop
+     *
+     * @param factorName - Factor name
+     * @param value - Factor value
+     * @returns Mapped prop object
+     */
+    mapFactorToProp(factorName: keyof SectionFactors, value: unknown): {
+        propName: string;
+        value: unknown;
+    } | undefined;
+    /**
+     * Convert a value to string representation
+     */
+    private valueToString;
+    /**
+     * Build props object from propagated factors
+     */
+    private buildPropsObject;
+    /**
+     * Build CSS variables object
+     */
+    private buildCssVariables;
+    /**
+     * Build data attributes array
+     */
+    private buildDataAttributes;
+    /**
+     * Build Tailwind classes string
+     */
+    private buildTailwindClasses;
+}
+/**
+ * Create a new FactorPropagator instance
+ *
+ * @param options - Propagator options
+ * @returns New FactorPropagator instance
+ */
+export declare function createFactorPropagator(options?: FactorPropagatorOptions): FactorPropagator;
+/**
+ * Propagate factors (convenience wrapper)
+ *
+ * @param input - Factor propagation input
+ * @returns Factor propagation result
+ */
+export declare function propagateFactors(input: FactorPropagationInput): FactorPropagationResult;
+/**
+ * Get Tailwind classes for section factors (convenience wrapper)
+ *
+ * @param factors - Section factors
+ * @param tier - Quality tier
+ * @returns Tailwind classes string
+ */
+export declare function getFactorTailwindClasses(factors: SectionFactors, tier: Tier): string;
+/**
+ * Get CSS variables for section factors (convenience wrapper)
+ *
+ * @param factors - Section factors
+ * @param tier - Quality tier
+ * @returns CSS variables object
+ */
+export declare function getFactorCssVariables(factors: SectionFactors, tier: Tier): Record<string, string>;
+/**
+ * Map factors to component props (convenience wrapper)
+ *
+ * @param factors - Section factors
+ * @param tier - Quality tier
+ * @returns Props object
+ */
+export declare function mapFactorsToProps(factors: SectionFactors, tier: Tier): Record<string, unknown>;
+//# sourceMappingURL=FactorPropagator.d.ts.map

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

@@ -0,0 +1,176 @@
+/**
+ * PageGenerator - Composes pages from sections, layouts from pages
+ * @packageDocumentation
+ * @module generators/PageGenerator
+ * @since 4.0.0
+ *
+ * Pattern:
+ * - Slot Composition: Pages compose sections via named slots
+ * - Children Composition: Layouts compose pages via children prop
+ * - Template Composition: Templates compose multiple pages
+ *
+ * Powered by Nikkory
+ */
+import type { GenerationResult } from '../types';
+import type { RegistrySectionDefinition, RegistryPageDefinition, RegistryLayoutDefinition, RegistryTemplateDefinition } from '../presets/registry.types';
+import type { DesignSystem, Tier } from '../types';
+/**
+ * Composition strategy types
+ */
+export type CompositionStrategy = 'slots' | 'children' | 'template';
+/**
+ * Configuration for composition generation
+ */
+export interface CompositionConfig {
+    /**
+     * Parent component (page, layout, or template)
+     */
+    readonly parent: RegistryPageDefinition | RegistryLayoutDefinition | RegistryTemplateDefinition;
+    /**
+     * Child components to compose
+     */
+    readonly children: ReadonlyArray<RegistrySectionDefinition | RegistryPageDefinition>;
+    /**
+     * Composition strategy
+     */
+    readonly strategy: CompositionStrategy;
+    /**
+     * Design system to apply
+     */
+    readonly designSystem: DesignSystem;
+    /**
+     * Quality tier to generate
+     */
+    readonly tier: Tier;
+    /**
+     * Output directory for generated files
+     */
+    readonly outputDir: string;
+}
+/**
+ * Slot definition for slot-based composition
+ */
+export interface SlotDefinition {
+    /**
+     * Slot name (e.g., 'hero', 'features', 'footer')
+     */
+    readonly name: string;
+    /**
+     * Component to render in this slot
+     */
+    readonly component: RegistrySectionDefinition;
+    /**
+     * Whether slot is required
+     */
+    readonly required: boolean;
+    /**
+     * Default component if slot is empty
+     */
+    readonly defaultComponent?: RegistrySectionDefinition;
+}
+/**
+ * PageGenerator - Main page composition engine
+ *
+ * @example
+ * ```typescript
+ * const generator = new PageGenerator();
+ * const result = generator.generateComposition({
+ *   parent: LANDING_PAGE_DEFINITION,
+ *   children: [HERO_SECTION, FEATURES_SECTION, CTA_SECTION],
+ *   strategy: 'slots',
+ *   designSystem: 'material-design',
+ *   tier: 'enterprise',
+ *   outputDir: './src/pages',
+ * });
+ * ```
+ */
+export declare class PageGenerator {
+    /**
+     * Generate a composition (page from sections, layout from pages, etc.)
+     *
+     * @param config - Composition configuration
+     * @returns Generation result with file paths and metadata
+     */
+    generateComposition(config: CompositionConfig): GenerationResult;
+    /**
+     * Generate page from sections (slot-based composition)
+     *
+     * @param page - Page definition
+     * @param sections - Section definitions to compose
+     * @param designSystem - Design system to apply
+     * @param tier - Quality tier
+     * @param outputDir - Output directory
+     * @param features - Tier-specific features
+     * @returns Generation result
+     */
+    private generateSlotComposition;
+    /**
+     * Generate layout from pages (children-based composition)
+     *
+     * @param layout - Layout definition
+     * @param pages - Page definitions to compose
+     * @param designSystem - Design system to apply
+     * @param tier - Quality tier
+     * @param outputDir - Output directory
+     * @param features - Tier-specific features
+     * @returns Generation result
+     */
+    private generateChildrenComposition;
+    /**
+     * Generate template from multiple pages (template composition)
+     *
+     * @param template - Template definition
+     * @param pages - Page definitions to include
+     * @param designSystem - Design system to apply
+     * @param tier - Quality tier
+     * @param outputDir - Output directory
+     * @param features - Tier-specific features
+     * @returns Generation result
+     */
+    private generateTemplateComposition;
+    /**
+     * Build slots from page and sections
+     */
+    private buildSlots;
+    /**
+     * Generate component code for slot-based composition
+     */
+    private generateSlotComponentCode;
+    /**
+     * Generate component code for children-based composition
+     */
+    private generateChildrenComponentCode;
+    /**
+     * Generate component code for template composition
+     */
+    private generateTemplateComponentCode;
+    /**
+     * Build template data for page composition
+     */
+    private buildPageTemplateData;
+    /**
+     * Build template data for layout composition
+     */
+    private buildLayoutTemplateData;
+    /**
+     * Build template data for template composition
+     */
+    private buildTemplateTemplateData;
+    /**
+     * Build imports based on features
+     */
+    private buildImports;
+    /**
+     * Get component name from definition ID, design system, and tier
+     */
+    private getComponentName;
+    /**
+     * Get component file name
+     */
+    private getComponentFileName;
+    /**
+     * Capitalize first letter of string
+     */
+    private capitalizeFirst;
+}
+//# sourceMappingURL=PageGenerator.d.ts.map