@nikkory/vibe-engine 4.0.0

package/dist/types/Result.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Result Type - Railway-Oriented Programming
+ *
+ * Functional error handling without exceptions.
+ * Represents either a successful value or an error.
+ *
+ * @example
+ * ```ts
+ * function divide(a: number, b: number): Result<number, Error> {
+ *   if (b === 0) {
+ *     return Result.fail(new Error('Division by zero'));
+ *   }
+ *   return Result.ok(a / b);
+ * }
+ *
+ * const result = divide(10, 2);
+ * if (result.isSuccess()) {
+ *   console.log('Value:', result.getValue()); // 5
+ * } else {
+ *   console.error('Error:', result.getError());
+ * }
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export declare class Result<T, E = Error> {
+    private readonly success;
+    private readonly value?;
+    private readonly error?;
+    private constructor();
+    /**
+     * Create a successful Result
+     *
+     * @param value - The success value
+     * @returns Result containing the value
+     */
+    static ok<T, E = Error>(value?: T): Result<T, E>;
+    /**
+     * Create a failed Result
+     *
+     * @param error - The error
+     * @returns Result containing the error
+     */
+    static fail<T, E = Error>(error: E): Result<T, E>;
+    /**
+     * Check if Result is successful
+     */
+    isSuccess(): boolean;
+    /**
+     * Check if Result is failure
+     */
+    isFailure(): boolean;
+    /**
+     * Get the value (throws if failure)
+     *
+     * @throws {Error} If Result is a failure
+     */
+    getValue(): T;
+    /**
+     * Get the error (throws if success)
+     *
+     * @throws {Error} If Result is a success
+     */
+    getError(): E;
+    /**
+     * Get value or default
+     *
+     * @param defaultValue - Value to return if Result is failure
+     */
+    getOrElse(defaultValue: T): T;
+    /**
+     * Get value or compute default
+     *
+     * @param fn - Function to compute default value
+     */
+    getOrElseCompute(fn: (error: E) => T): T;
+    /**
+     * Map the value if successful
+     *
+     * @param fn - Mapping function
+     * @returns New Result with mapped value
+     */
+    map<U>(fn: (value: T) => U): Result<U, E>;
+    /**
+     * Map the error if failure
+     *
+     * @param fn - Error mapping function
+     * @returns New Result with mapped error
+     */
+    mapError<F>(fn: (error: E) => F): Result<T, F>;
+    /**
+     * Flat map (chain) operations
+     *
+     * @param fn - Function returning a Result
+     * @returns Flattened Result
+     */
+    flatMap<U>(fn: (value: T) => Result<U, E>): Result<U, E>;
+    /**
+     * Execute callback if successful
+     *
+     * @param fn - Callback function
+     * @returns This Result for chaining
+     */
+    onSuccess(fn: (value: T) => void): Result<T, E>;
+    /**
+     * Execute callback if failure
+     *
+     * @param fn - Callback function
+     * @returns This Result for chaining
+     */
+    onFailure(fn: (error: E) => void): Result<T, E>;
+    /**
+     * Match pattern for Result
+     *
+     * @param patterns - Success and failure handlers
+     * @returns Result of the matched pattern
+     */
+    match<U>(patterns: {
+        ok: (value: T) => U;
+        fail: (error: E) => U;
+    }): U;
+    /**
+     * Convert Result to JSON
+     */
+    toJSON(): object;
+    /**
+     * Combine multiple Results
+     *
+     * @param results - Array of Results
+     * @returns Result containing array of values or first error
+     */
+    static combine<T, E = Error>(results: Result<T, E>[]): Result<T[], E>;
+    /**
+     * Try to execute a function and wrap result
+     *
+     * @param fn - Function to execute
+     * @returns Result wrapping the function result or error
+     */
+    static try<T>(fn: () => T): Result<T, Error>;
+    /**
+     * Try to execute an async function and wrap result
+     *
+     * @param fn - Async function to execute
+     * @returns Promise of Result wrapping the function result or error
+     */
+    static tryAsync<T>(fn: () => Promise<T>): Promise<Result<T, Error>>;
+}
+//# sourceMappingURL=Result.d.ts.map

package/dist/types/algorithm-engine.types.d.ts

@@ -0,0 +1,298 @@
+/**
+ * Algorithm Engine Types
+ * Core types for the 24-Factor × 3-Tier × 12-Design-Systems generation engine
+ *
+ * @packageDocumentation
+ * @module types/algorithm-engine
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+import type { Tier, DesignSystem, ComponentType } from './index';
+/**
+ * Factor ID (1-24)
+ * Each factor represents a styling dimension in the 24-Factor system
+ */
+export type FactorId = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24;
+/**
+ * Factor Group
+ * Logical grouping of factors by purpose
+ */
+export type FactorGroup = 'visual' | 'layout' | 'motion' | 'experience';
+/**
+ * Factor Definition
+ * Complete definition of a single factor in the 24-Factor system
+ */
+export interface FactorDefinition {
+    /** Factor ID (1-24) */
+    readonly id: FactorId;
+    /** Human-readable name */
+    readonly name: string;
+    /** Detailed description of what this factor controls */
+    readonly description: string;
+    /** Logical group this factor belongs to */
+    readonly group: FactorGroup;
+    /** CSS property this factor maps to (if applicable) */
+    readonly cssProperty?: string;
+    /** Data attribute for Hybrid integration */
+    readonly dataAttribute?: string;
+    /** Default value when no design system value is provided */
+    readonly defaultValue: string;
+    /** All possible values this factor can have */
+    readonly possibleValues: readonly string[];
+}
+/**
+ * Factor Value from Design System
+ * Resolved value for a factor from a specific design system
+ */
+export interface FactorValue {
+    /** Factor ID this value is for */
+    readonly factorId: FactorId;
+    /** Semantic value name (e.g., 'md', 'lg', 'primary') */
+    readonly value: string;
+    /** Generated Tailwind CSS classes */
+    readonly tailwindClasses: string;
+    /** Optional CSS variables for Hybrid integration */
+    readonly cssVariables?: Record<string, string>;
+}
+/**
+ * Code Features by Tier
+ * Defines which React patterns are required for each tier
+ */
+export interface TierCodeFeatures {
+    /** Use React.forwardRef for ref forwarding */
+    readonly useForwardRef: boolean;
+    /** Use React.memo for performance optimization */
+    readonly useMemo: boolean;
+    /** Use useCallback for handler memoization */
+    readonly useCallback: boolean;
+    /** Set displayName for debugging */
+    readonly setDisplayName: boolean;
+    /** Include analytics event tracking */
+    readonly includeAnalytics: boolean;
+    /** Include ARIA attributes for accessibility */
+    readonly includeAria: boolean;
+}
+/**
+ * Lines of Code Range
+ * Expected LOC range for components in this tier
+ */
+export interface LocRange {
+    readonly min: number;
+    readonly max: number;
+}
+/**
+ * Factor Range
+ * Defines which factors (1-24) are enabled for a tier
+ */
+export interface FactorRange {
+    /** Starting factor ID (inclusive) */
+    readonly start: FactorId;
+    /** Ending factor ID (inclusive) */
+    readonly end: FactorId;
+}
+/**
+ * Tier Registry Entry
+ * Complete definition of a tier's capabilities and constraints
+ */
+export interface TierRegistryEntry {
+    /** Tier identifier */
+    readonly tier: Tier;
+    /** Which factors are enabled for this tier */
+    readonly factorRange: FactorRange;
+    /** Which code features are required for this tier */
+    readonly codeFeatures: TierCodeFeatures;
+    /** Expected lines of code range */
+    readonly locRange: LocRange;
+}
+/**
+ * Factor Applicability for Component
+ * Defines whether a factor applies to a specific component type
+ *
+ * - null: Factor not applicable (khuyết) - skip this factor
+ * - true: Factor applicable with design system default value
+ * - string: Factor applicable with specific override value
+ */
+export type FactorApplicability = null | true | string;
+/**
+ * Component Registry Entry
+ * Complete definition of a component's generation requirements
+ */
+export interface ComponentRegistryEntry {
+    /** Unique component ID (e.g., 'button', 'card', 'modal') */
+    readonly id: string;
+    /** Human-readable name */
+    readonly name: string;
+    /** Component category (e.g., 'basic', 'feedback', 'navigation') */
+    readonly category: string;
+    /** Base HTML element type (e.g., 'button', 'div', 'section') */
+    readonly elementType: string;
+    /** Factor applicability map - which factors apply to this component */
+    readonly factorApplicability: Partial<Record<FactorId, FactorApplicability>>;
+    /** Which design systems this component supports */
+    readonly designSystems: readonly DesignSystem[];
+    /** Which tiers this component supports */
+    readonly tiers: readonly Tier[];
+}
+/**
+ * Design System Registry Entry
+ * Complete definition of a design system's factor values
+ */
+export interface DesignSystemRegistryEntry {
+    /** Design system identifier */
+    readonly id: DesignSystem;
+    /** Human-readable name */
+    readonly name: string;
+    /** Description of design system aesthetic */
+    readonly description: string;
+    /** Factor values for this design system */
+    readonly factorValues: Partial<Record<FactorId, FactorValue>>;
+    /** CSS variables for Hybrid integration */
+    readonly cssVariables: Record<string, string>;
+    /** Optional Tailwind config extensions */
+    readonly tailwindConfig?: Record<string, unknown>;
+}
+/**
+ * Generation Input
+ * Input parameters for generating a component
+ */
+export interface GenerationInput {
+    /** Component type to generate */
+    readonly componentType: ComponentType;
+    /** Design system to use */
+    readonly designSystem: DesignSystem;
+    /** Quality tier */
+    readonly tier: Tier;
+    /** Optional factor value overrides */
+    readonly factorOverrides?: Partial<Record<FactorId, string>>;
+    /** Optional output directory */
+    readonly outputDir?: string;
+}
+/**
+ * Generation Metadata
+ * Metadata about the generated component
+ */
+export interface GenerationMetadata {
+    /** Generated component name (e.g., 'MaterialButtonEnterprise') */
+    readonly componentName: string;
+    /** Display name for React DevTools */
+    readonly displayName: string;
+    /** Factors that were applied */
+    readonly factorsApplied: FactorId[];
+    /** Total lines of code */
+    readonly linesOfCode: number;
+    /** Generation timestamp */
+    readonly generatedAt: Date;
+}
+/**
+ * Generation Output
+ * Complete output from component generation
+ */
+export interface GenerationOutput {
+    /** Generated component code */
+    readonly code: string;
+    /** Generated styles (Tailwind classes or CSS) */
+    readonly styles: string;
+    /** Optional TypeScript types file content */
+    readonly types?: string;
+    /** Optional test file content */
+    readonly tests?: string;
+    /** Generation metadata */
+    readonly metadata: GenerationMetadata;
+}
+/**
+ * Resolved Factors
+ * Result of 3-layer factor resolution
+ */
+export interface ResolvedFactors {
+    /** Tier that was used for resolution */
+    readonly tier: Tier;
+    /** Factors that were applied with their values */
+    readonly appliedFactors: Map<FactorId, FactorValue>;
+    /** Factors that were skipped (not applicable to component) */
+    readonly skippedFactors: FactorId[];
+    /** Factors that were overridden by user */
+    readonly overriddenFactors: FactorId[];
+}
+/**
+ * Factor Resolver Input
+ * Input for the 3-layer factor resolution process
+ */
+export interface FactorResolverInput {
+    /** Component type being generated */
+    readonly componentType: ComponentType;
+    /** Target design system */
+    readonly designSystem: DesignSystem;
+    /** Quality tier */
+    readonly tier: Tier;
+    /** Optional factor overrides */
+    readonly factorOverrides?: Partial<Record<FactorId, string>>;
+}
+/**
+ * Batch Generation Input
+ * Input for generating multiple components at once
+ */
+export interface BatchGenerationInput {
+    /** Component types to generate (or all if not specified) */
+    readonly componentTypes?: readonly ComponentType[];
+    /** Design systems to generate for (or all if not specified) */
+    readonly designSystems?: readonly DesignSystem[];
+    /** Tiers to generate (or all if not specified) */
+    readonly tiers?: readonly Tier[];
+    /** Output directory base path */
+    readonly outputDir: string;
+    /** Whether to overwrite existing files */
+    readonly overwrite?: boolean;
+}
+/**
+ * Batch Generation Result
+ * Result of batch component generation
+ */
+export interface BatchGenerationResult {
+    /** Total components requested */
+    readonly total: number;
+    /** Successfully generated count */
+    readonly successful: number;
+    /** Failed generation count */
+    readonly failed: number;
+    /** Total lines of code generated */
+    readonly totalLinesOfCode: number;
+    /** Individual generation results */
+    readonly results: readonly GenerationResultItem[];
+    /** Generation duration in milliseconds */
+    readonly durationMs: number;
+}
+/**
+ * Generation Result Item
+ * Result for a single component in batch generation
+ */
+export interface GenerationResultItem {
+    /** Component identifier */
+    readonly componentId: string;
+    /** Whether generation succeeded */
+    readonly success: boolean;
+    /** Error message if failed */
+    readonly error?: string;
+    /** Output file path if succeeded */
+    readonly outputPath?: string;
+    /** Lines of code if succeeded */
+    readonly linesOfCode?: number;
+}
+/**
+ * Validation Result
+ * Result of input validation
+ */
+export interface ValidationResult {
+    /** Whether validation passed */
+    readonly valid: boolean;
+    /** Validation error messages (if any) */
+    readonly errors: readonly string[];
+    /** Validation warning messages (if any) */
+    readonly warnings: readonly string[];
+}
+/**
+ * Validator Function Type
+ * Generic validator function signature
+ */
+export type ValidatorFn<T> = (input: T) => ValidationResult;
+//# sourceMappingURL=algorithm-engine.types.d.ts.map

package/dist/types/granularity/base.types.d.ts

@@ -0,0 +1,268 @@
+/**
+ * Base Types for Unified Granularity Architecture
+ *
+ * This file defines the core types for the 6-level granularity system,
+ * replacing duplicate Section/Page/Layout/Template patterns with a
+ * unified generic approach.
+ *
+ * @packageDocumentation
+ * @module types/granularity
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+import type { DesignSystem, Tier } from '../index';
+/**
+ * 6 Granularity Levels - Component hierarchy from smallest to largest
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * @example
+ * ```typescript
+ * const level: GranularityLevel = 'section';
+ * const config: GranularityConfig<'page'> = { ... };
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export type GranularityLevel = 'atom' | 'component' | 'section' | 'page' | 'layout' | 'template';
+/**
+ * Granularity hierarchy for cascade - ordered from highest to lowest
+ *
+ * Higher levels cascade factors DOWN to lower levels.
+ * Template is the highest level (6), Atom is the lowest (1).
+ *
+ * @category constants
+ * @since 4.0.0
+ *
+ * @example
+ * ```typescript
+ * // Iterate from highest to lowest
+ * for (const level of GRANULARITY_HIERARCHY) {
+ *   console.log(level); // template, layout, page, section, component, atom
+ * }
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export declare const GRANULARITY_HIERARCHY: readonly GranularityLevel[];
+/**
+ * Get numeric rank for a granularity level
+ *
+ * Returns a number where:
+ * - template = 6 (highest)
+ * - layout = 5
+ * - page = 4
+ * - section = 3
+ * - component = 2
+ * - atom = 1 (lowest)
+ *
+ * @category utils
+ * @since 4.0.0
+ *
+ * @param level - The granularity level to get rank for
+ * @returns Numeric rank (1-6)
+ *
+ * @example
+ * ```typescript
+ * getGranularityRank('template'); // 6
+ * getGranularityRank('atom');     // 1
+ * getGranularityRank('section');  // 3
+ *
+ * // Use for comparison
+ * if (getGranularityRank(a) > getGranularityRank(b)) {
+ *   // a is higher level than b
+ * }
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export declare function getGranularityRank(level: GranularityLevel): number;
+/**
+ * Factor categories for grouping related factors
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * @example
+ * ```typescript
+ * const category: FactorCategory = 'visual';
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export type GranularityFactorCategory = 'visual' | 'layout' | 'behavior' | 'responsive' | 'a11y';
+/**
+ * Factor definition with level and cascade behavior
+ *
+ * This REPLACES hardcoded 8/13/24 factor arrays with a dynamic
+ * registry-based approach where each factor specifies its minimum
+ * level and whether it cascades down to child granularities.
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * @example
+ * ```typescript
+ * const spacingFactor: GranularityFactorDefinition = {
+ *   id: 'spacing',
+ *   name: 'Spacing',
+ *   category: 'layout',
+ *   level: 'template',
+ *   cascadeDown: true,
+ *   defaults: {
+ *     'material-design': 'md',
+ *     'ios-hig': 'sm'
+ *   },
+ *   options: ['xs', 'sm', 'md', 'lg', 'xl'],
+ *   description: 'Controls spacing between elements'
+ * };
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export interface GranularityFactorDefinition {
+    /** Factor unique identifier */
+    readonly id: string;
+    /** Human-readable name */
+    readonly name: string;
+    /** Factor category */
+    readonly category: GranularityFactorCategory;
+    /** Minimum granularity level where this factor applies */
+    readonly level: GranularityLevel;
+    /** Whether factor cascades DOWN to child granularities */
+    readonly cascadeDown: boolean;
+    /** Default value per design system */
+    readonly defaults: Partial<Record<DesignSystem, unknown>>;
+    /** Possible values */
+    readonly options?: readonly unknown[];
+    /** Description for documentation */
+    readonly description: string;
+}
+/**
+ * Template visibility levels for sharing
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+export type GranularityTemplateVisibility = 'private' | 'team' | 'public';
+/**
+ * Layout configuration for slot arrangements
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * @example
+ * ```typescript
+ * const layout: LayoutConfig = {
+ *   type: 'grid',
+ *   columns: 3,
+ *   gap: 'md',
+ *   alignment: 'center'
+ * };
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export interface GranularityLayoutConfig {
+    readonly type: 'grid' | 'flex' | 'stack' | 'masonry' | 'carousel';
+    readonly columns?: 1 | 2 | 3 | 4 | 6;
+    readonly gap?: GranularitySpacingLevel;
+    readonly alignment?: GranularityAlignmentType;
+}
+/**
+ * Spacing levels for consistent spacing scale
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+export type GranularitySpacingLevel = 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
+/**
+ * Alignment types for layout positioning
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+export type GranularityAlignmentType = 'start' | 'center' | 'end' | 'stretch' | 'between';
+/**
+ * Style overrides for customization
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * @example
+ * ```typescript
+ * const styles: StyleOverrides = {
+ *   className: 'custom-section',
+ *   tailwindClasses: 'bg-gray-100 p-4 rounded-lg'
+ * };
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export interface GranularityStyleOverrides {
+    readonly className?: string;
+    readonly style?: Record<string, string>;
+    readonly tailwindClasses?: string;
+}
+/**
+ * Factor values map - key-value pairs for resolved factors
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * @example
+ * ```typescript
+ * const factors: FactorValues = {
+ *   spacing: 'md',
+ *   colorPrimary: '#3B82F6',
+ *   borderRadius: 'lg'
+ * };
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export type GranularityFactorValues = Record<string, unknown>;
+/**
+ * Base fields shared by ALL granularity levels
+ *
+ * This interface defines the common fields that every granularity
+ * config must have, regardless of whether it's an atom, component,
+ * section, page, layout, or template.
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * @typeParam G - The granularity level this config is for
+ *
+ * @example
+ * ```typescript
+ * interface MySectionConfig extends GranularityBaseFields<'section'> {
+ *   customField: string;
+ * }
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export interface GranularityBaseFields<G extends GranularityLevel> {
+    /** Unique identifier */
+    readonly id: string;
+    /** Granularity level */
+    readonly granularity: G;
+    /** Design system */
+    readonly designSystem: DesignSystem;
+    /** Quality tier */
+    readonly tier: Tier;
+    /** Display title */
+    readonly title: string;
+    /** Optional subtitle/description */
+    readonly subtitle?: string;
+}
+//# sourceMappingURL=base.types.d.ts.map