@nikkory/vibe-engine 4.0.0

package/dist/storage/index.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Storage Module
+ * Hybrid storage system with visibility-based routing
+ *
+ * @packageDocumentation
+ * @module storage
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+/**
+ * Section Storage Manager
+ *
+ * @remarks
+ * The main storage manager provides visibility-based routing:
+ * - private: Local JSON file only
+ * - team: Local JSON + Cloud sync
+ * - public: Local JSON + Cloud sync + Marketplace
+ *
+ * @example
+ * ```typescript
+ * import { saveTemplate, loadTemplate } from '@nikkory/engine/storage';
+ *
+ * // Save with auto-routing based on visibility
+ * const saveResult = await saveTemplate(myTemplate);
+ *
+ * // Load from appropriate source
+ * const loadResult = await loadTemplate('hero-001', 'team');
+ * ```
+ */
+export { saveTemplate, loadTemplate, deleteTemplate, listTemplates, forceSync, getSyncStatus, batchSync, createStorageConfig, getVisibilityRules, serializeTemplate, parseTemplate, generateFilename, isValidTemplateId, getTemplatePath, DEFAULT_LOCAL_STORAGE_PATH, TEMPLATE_SCHEMA_VERSION, isSyncEnabled, isMarketplaceEnabled, VISIBILITY_SYNC_RULES, } from './section-storage';
+/**
+ * Storage types for external use
+ */
+export type { StorageConfig, StorageManagerOptions, SaveResult, LoadResult, TemplateListResult, StorageResult, TemplateFileData, SyncResult, SyncStatus, SyncOptions, BatchSyncResult, } from './section-storage';
+/**
+ * Local Storage Module
+ *
+ * @remarks
+ * Direct access to local JSON file storage.
+ * Use section-storage for visibility-based routing instead.
+ *
+ * @example
+ * ```typescript
+ * import { saveToJSON, loadFromJSON } from '@nikkory/engine/storage';
+ *
+ * // Direct local save (no sync)
+ * const result = await saveToJSON(template, '/path/to/storage');
+ * ```
+ */
+export { saveToJSON, loadFromJSON, listLocalTemplates, deleteFromLocal } from './local-storage';
+/**
+ * Cloud Sync Module
+ *
+ * @remarks
+ * Direct access to cloud synchronization.
+ * Use section-storage for visibility-based routing instead.
+ *
+ * @example
+ * ```typescript
+ * import { syncToCloud, fetchFromCloud } from '@nikkory/engine/storage';
+ *
+ * // Direct cloud sync
+ * const result = await syncToCloud(template);
+ * ```
+ */
+export { syncToCloud, fetchFromCloud, deleteFromCloud, batchSyncToCloud, checkSyncStatus, resolveConflict, } from './cloud-sync';
+export type { SyncConflict } from './cloud-sync';
+//# sourceMappingURL=index.d.ts.map

package/dist/storage/local-storage.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Local Storage Module
+ * JSON file-based storage for section templates
+ *
+ * @packageDocumentation
+ * @module storage/local-storage
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+import type { SectionTemplate, SectionTemplateWithFactors } from '../types/section-template.types';
+/**
+ * Storage operation result
+ */
+export interface StorageResult<T> {
+    /** Whether operation succeeded */
+    readonly success: boolean;
+    /** Result data if successful */
+    readonly data?: T;
+    /** Error message if failed */
+    readonly error?: string;
+}
+/**
+ * Template file structure for JSON storage
+ */
+export interface TemplateFileData {
+    /** Schema version for migrations */
+    readonly schemaVersion: string;
+    /** Template data */
+    readonly template: SectionTemplate | SectionTemplateWithFactors;
+    /** Created timestamp */
+    readonly createdAt: string;
+    /** Last modified timestamp */
+    readonly updatedAt: string;
+}
+/**
+ * Default local storage directory (relative to user data)
+ */
+export declare const DEFAULT_LOCAL_STORAGE_PATH = ".nikkory/templates";
+/**
+ * Current schema version for template files
+ */
+export declare const TEMPLATE_SCHEMA_VERSION = "1.0.0";
+/**
+ * Save template to JSON file
+ *
+ * @param template - Template to save
+ * @param basePath - Base directory path for storage
+ * @returns Storage result with file path
+ *
+ * @example
+ * ```typescript
+ * const result = await saveToJSON(myTemplate, '/home/user/.nikkory/templates');
+ * if (result.success) {
+ *   console.log('Saved to:', result.data);
+ * }
+ * ```
+ */
+export declare function saveToJSON(template: SectionTemplate | SectionTemplateWithFactors, basePath?: string): Promise<StorageResult<string>>;
+/**
+ * Serialize template to JSON string
+ *
+ * @param template - Template to serialize
+ * @returns Serialized JSON string
+ */
+export declare function serializeTemplate(template: SectionTemplate | SectionTemplateWithFactors): string;
+/**
+ * Load template from JSON file
+ *
+ * @param templateId - Template identifier to load
+ * @param visibility - Template visibility (determines folder)
+ * @param basePath - Base directory path for storage
+ * @returns Storage result with template data
+ *
+ * @example
+ * ```typescript
+ * const result = await loadFromJSON('hero-001', 'private');
+ * if (result.success && result.data) {
+ *   console.log('Loaded template:', result.data.templateName);
+ * }
+ * ```
+ */
+export declare function loadFromJSON(templateId: string, visibility: 'private' | 'team' | 'public', basePath?: string): Promise<StorageResult<SectionTemplate | SectionTemplateWithFactors>>;
+/**
+ * Parse JSON string to template
+ *
+ * @param jsonContent - JSON string to parse
+ * @returns Storage result with parsed template
+ */
+export declare function parseTemplate(jsonContent: string): StorageResult<SectionTemplate | SectionTemplateWithFactors>;
+/**
+ * List all templates in a visibility folder
+ *
+ * @param visibility - Template visibility to list
+ * @param basePath - Base directory path for storage
+ * @returns Storage result with template IDs
+ */
+export declare function listLocalTemplates(visibility: 'private' | 'team' | 'public', basePath?: string): Promise<StorageResult<readonly string[]>>;
+/**
+ * Delete template from local storage
+ *
+ * @param templateId - Template identifier to delete
+ * @param visibility - Template visibility
+ * @param basePath - Base directory path for storage
+ * @returns Storage result with success status
+ */
+export declare function deleteFromLocal(templateId: string, visibility: 'private' | 'team' | 'public', basePath?: string): Promise<StorageResult<boolean>>;
+/**
+ * Generate filename from template ID
+ *
+ * @param templateId - Template identifier
+ * @returns Sanitized filename with .json extension
+ */
+export declare function generateFilename(templateId: string): string;
+/**
+ * Validate template ID format
+ *
+ * @param templateId - Template identifier to validate
+ * @returns Whether the ID is valid
+ */
+export declare function isValidTemplateId(templateId: string): boolean;
+/**
+ * Generate storage path for template
+ *
+ * @param visibility - Template visibility
+ * @param templateId - Template identifier
+ * @param basePath - Base directory path
+ * @returns Full storage path
+ */
+export declare function getTemplatePath(visibility: 'private' | 'team' | 'public', templateId: string, basePath?: string): string;
+//# sourceMappingURL=local-storage.d.ts.map

package/dist/storage/section-storage.d.ts

@@ -0,0 +1,191 @@
+/**
+ * Section Storage Manager
+ * Hybrid storage manager with visibility-based routing
+ *
+ * @packageDocumentation
+ * @module storage/section-storage
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+import { isSyncEnabled, isMarketplaceEnabled, VISIBILITY_SYNC_RULES } from './cloud-sync';
+import { serializeTemplate, parseTemplate, generateFilename, isValidTemplateId, getTemplatePath, DEFAULT_LOCAL_STORAGE_PATH, TEMPLATE_SCHEMA_VERSION } from './local-storage';
+import type { SyncResult, SyncStatus, SyncOptions, BatchSyncResult } from './cloud-sync';
+import type { StorageResult, TemplateFileData } from './local-storage';
+import type { SectionTemplate, SectionTemplateWithFactors, TemplateVisibility } from '../types/section-template.types';
+/**
+ * Storage configuration for templates
+ */
+export interface StorageConfig {
+    /** Template visibility determines storage location */
+    readonly visibility: TemplateVisibility;
+    /** Local storage base path */
+    readonly localPath: string;
+    /** Whether cloud sync is enabled */
+    readonly cloudSyncEnabled: boolean;
+    /** Last sync timestamp */
+    readonly lastSyncedAt?: Date;
+}
+/**
+ * Storage manager options
+ */
+export interface StorageManagerOptions {
+    /** Base path for local storage */
+    readonly basePath?: string;
+    /** Auto-sync on save */
+    readonly autoSync?: boolean;
+    /** Cloud sync options */
+    readonly syncOptions?: SyncOptions;
+}
+/**
+ * Save operation result
+ */
+export interface SaveResult {
+    /** Whether save succeeded */
+    readonly success: boolean;
+    /** Local file path */
+    readonly localPath?: string;
+    /** Whether cloud sync was triggered */
+    readonly syncTriggered: boolean;
+    /** Sync result if triggered */
+    readonly syncResult?: SyncResult<string> | SyncResult<boolean>;
+    /** Error message if failed */
+    readonly error?: string;
+}
+/**
+ * Load operation result
+ */
+export interface LoadResult {
+    /** Whether load succeeded */
+    readonly success: boolean;
+    /** Loaded template */
+    readonly template?: SectionTemplate | SectionTemplateWithFactors;
+    /** Source: 'local' or 'cloud' */
+    readonly source?: 'local' | 'cloud';
+    /** Error message if failed */
+    readonly error?: string;
+}
+/**
+ * Save template with visibility-based routing
+ *
+ * @param template - Template to save
+ * @param options - Storage manager options
+ * @returns Save result
+ *
+ * @remarks
+ * Routes storage based on visibility:
+ * - private: Local JSON file only
+ * - team: Local JSON + Cloud sync
+ * - public: Local JSON + Cloud sync + Marketplace
+ *
+ * @example
+ * ```typescript
+ * // Save private template (local only)
+ * const result = await saveTemplate({
+ *   ...config,
+ *   visibility: 'private',
+ * });
+ *
+ * // Save team template (local + cloud sync)
+ * const result = await saveTemplate({
+ *   ...config,
+ *   visibility: 'team',
+ * });
+ * ```
+ */
+export declare function saveTemplate(template: SectionTemplate | SectionTemplateWithFactors, options?: StorageManagerOptions): Promise<SaveResult>;
+/**
+ * Load template with visibility-based routing
+ *
+ * @param templateId - Template identifier
+ * @param visibility - Template visibility
+ * @param options - Storage manager options
+ * @returns Load result
+ *
+ * @remarks
+ * Attempts to load from local first, then cloud if not found.
+ * Private templates only check local storage.
+ *
+ * @example
+ * ```typescript
+ * const result = await loadTemplate('hero-001', 'private');
+ * if (result.success && result.template) {
+ *   console.log('Loaded:', result.template.templateName);
+ * }
+ * ```
+ */
+export declare function loadTemplate(templateId: string, visibility: TemplateVisibility, options?: StorageManagerOptions): Promise<LoadResult>;
+/**
+ * Delete template from storage
+ *
+ * @param templateId - Template identifier
+ * @param visibility - Template visibility
+ * @param options - Storage manager options
+ * @returns Delete result
+ */
+export declare function deleteTemplate(templateId: string, visibility: TemplateVisibility, options?: StorageManagerOptions): Promise<SaveResult>;
+/**
+ * List templates by visibility
+ */
+export interface TemplateListResult {
+    /** Whether list succeeded */
+    readonly success: boolean;
+    /** Template IDs */
+    readonly templateIds?: readonly string[];
+    /** Error message if failed */
+    readonly error?: string;
+}
+/**
+ * List all templates for a visibility
+ *
+ * @param visibility - Template visibility to list
+ * @param options - Storage manager options
+ * @returns List of template IDs
+ */
+export declare function listTemplates(visibility: TemplateVisibility, options?: StorageManagerOptions): Promise<TemplateListResult>;
+/**
+ * Force sync template to cloud
+ *
+ * @param template - Template to sync
+ * @param options - Sync options
+ * @returns Sync result
+ */
+export declare function forceSync(template: SectionTemplate | SectionTemplateWithFactors, options?: SyncOptions): Promise<SyncResult<string>>;
+/**
+ * Get sync status for a template
+ *
+ * @param templateId - Template identifier
+ * @param localVersion - Local version
+ * @param options - Sync options
+ * @returns Sync status
+ */
+export declare function getSyncStatus(templateId: string, localVersion: string, options?: SyncOptions): Promise<SyncResult<SyncStatus>>;
+/**
+ * Batch sync multiple templates
+ *
+ * @param templates - Templates to sync
+ * @param options - Sync options
+ * @returns Batch sync result
+ */
+export declare function batchSync(templates: readonly (SectionTemplate | SectionTemplateWithFactors)[], options?: SyncOptions): Promise<BatchSyncResult>;
+/**
+ * Create storage config for a template
+ *
+ * @param visibility - Template visibility
+ * @param basePath - Local storage path
+ * @returns Storage configuration
+ */
+export declare function createStorageConfig(visibility: TemplateVisibility, basePath?: string): StorageConfig;
+/**
+ * Get visibility rules
+ */
+export declare function getVisibilityRules(visibility: TemplateVisibility): {
+    readonly syncEnabled: boolean;
+    readonly marketplaceListing: boolean;
+    readonly requiresAuth: boolean;
+};
+export { serializeTemplate, parseTemplate, generateFilename, isValidTemplateId, getTemplatePath, DEFAULT_LOCAL_STORAGE_PATH, TEMPLATE_SCHEMA_VERSION, };
+export { isSyncEnabled, isMarketplaceEnabled, VISIBILITY_SYNC_RULES };
+export type { StorageResult, TemplateFileData };
+export type { SyncResult, SyncStatus, SyncOptions, BatchSyncResult };
+//# sourceMappingURL=section-storage.d.ts.map

package/dist/styling/StyleGenerator.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Style Generator
+ *
+ * Core style generation engine that creates component styles from design tokens.
+ * This module provides the main API for generating component-specific CSS classes.
+ *
+ * @packageDocumentation
+ * @module generator/StyleGenerator
+ * @since 2.0.0
+ *
+ * Powered by Nikkory
+ */
+import type { ComponentType, StyleConfig, GeneratedStyles } from './types';
+import type { DesignTokens } from '../tokens/schema';
+/**
+ * Combine class names, filtering out falsy values.
+ *
+ * @param classes - Class names to combine
+ * @returns Combined class string
+ *
+ * @example
+ * ```typescript
+ * cn('btn', isActive && 'btn-active', size === 'lg' && 'btn-lg')
+ * // => "btn btn-active btn-lg" or "btn" depending on conditions
+ * ```
+ *
+ * @since 2.0.0
+ */
+export declare function cn(...classes: (string | undefined | null | false)[]): string;
+/**
+ * Generate component styles from design tokens.
+ *
+ * @param component - Component type
+ * @param tokens - Design tokens from the token system
+ * @param config - Style configuration
+ * @returns Generated styles with combined className
+ *
+ * @example
+ * ```typescript
+ * const styles = generateStyles('button', tokens, {
+ *   variant: 'filled',
+ *   size: 'md',
+ *   colorScheme: 'primary',
+ * });
+ *
+ * return <button className={styles.className}>Click me</button>;
+ * ```
+ *
+ * @since 2.0.0
+ */
+export declare function generateStyles(component: ComponentType, tokens: DesignTokens, config?: StyleConfig): GeneratedStyles;
+/**
+ * Check if a component type is supported.
+ *
+ * @param component - Component type to check
+ * @returns true if supported
+ *
+ * @since 2.0.0
+ */
+export declare function isComponentSupported(component: string): component is ComponentType;
+/**
+ * Get all supported component types.
+ *
+ * @returns Array of supported component types
+ *
+ * @since 2.0.0
+ */
+export declare function getSupportedComponents(): ComponentType[];
+export declare const StyleGenerator: {
+    generate: typeof generateStyles;
+    isSupported: typeof isComponentSupported;
+    getSupported: typeof getSupportedComponents;
+    cn: typeof cn;
+};
+export default StyleGenerator;
+//# sourceMappingURL=StyleGenerator.d.ts.map

package/dist/styling/TokenStyleResolver.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Token Style Resolver
+ *
+ * Resolves design tokens to Tailwind CSS classes.
+ * This is the bridge between the token system and generated component styles.
+ *
+ * @packageDocumentation
+ * @module generator/TokenStyleResolver
+ * @since 2.0.0
+ *
+ * Powered by Nikkory
+ */
+import type { ColorScheme, ComponentSize } from './types';
+import type { DesignTokens } from '../tokens/schema';
+/**
+ * Token resolution options.
+ */
+export interface TokenResolveOptions {
+    /** Design system tokens */
+    tokens: DesignTokens;
+    /** Color scheme to use */
+    colorScheme?: ColorScheme;
+    /** Component size */
+    size?: ComponentSize;
+    /** Variant type */
+    variant?: string;
+    /** Whether component is disabled */
+    disabled?: boolean;
+    /** Whether component is loading */
+    loading?: boolean;
+}
+/**
+ * Resolved token values.
+ */
+export interface ResolvedTokenValues {
+    /** Background color class */
+    bgColor: string;
+    /** Text color class */
+    textColor: string;
+    /** Border color class */
+    borderColor: string;
+    /** Hover background class */
+    hoverBgColor: string;
+    /** Active background class */
+    activeBgColor: string;
+    /** Focus ring class */
+    focusRingColor: string;
+    /** Shadow class (base) */
+    shadow: string;
+    /** Hover shadow class (state) */
+    hoverShadow: string;
+    /** Border radius class */
+    borderRadius: string;
+    /** Padding classes */
+    padding: string;
+    /** Height class */
+    height: string;
+    /** Font size class */
+    fontSize: string;
+    /** Transition class */
+    transition: string;
+}
+/**
+ * Clear style cache.
+ */
+export declare function clearStyleCache(): void;
+/**
+ * Resolve all token values to Tailwind classes.
+ *
+ * @param options - Resolution options
+ * @returns Resolved token values
+ *
+ * @example
+ * ```typescript
+ * const values = resolveTokens({
+ *   tokens: materialDesignTokens,
+ *   colorScheme: 'primary',
+ *   size: 'md',
+ *   variant: 'filled',
+ * });
+ *
+ * console.log(values.bgColor); // "bg-[#6750A4]"
+ * console.log(values.textColor); // "text-[#FFFFFF]"
+ * ```
+ */
+export declare function resolveTokenStyles(options: TokenResolveOptions): ResolvedTokenValues;
+/**
+ * Build combined class string from resolved values.
+ *
+ * @param values - Resolved token values
+ * @param includeStates - Whether to include hover/active states
+ * @returns Combined class string
+ */
+export declare function buildClassName(values: ResolvedTokenValues, includeStates?: boolean): string;
+/**
+ * Tailwind responsive breakpoints.
+ */
+export type ResponsiveBreakpoint = 'sm' | 'md' | 'lg' | 'xl' | '2xl';
+/**
+ * Responsive value type - can be a single value or an object with breakpoint keys.
+ */
+export type ResponsiveValue<T> = T | Partial<Record<ResponsiveBreakpoint, T>>;
+/**
+ * Apply responsive prefix to a class.
+ *
+ * @param breakpoint - The responsive breakpoint
+ * @param className - The class to prefix
+ * @returns Prefixed class string
+ *
+ * @example
+ * ```typescript
+ * applyResponsivePrefix('md', 'px-4'); // "md:px-4"
+ * applyResponsivePrefix('lg', 'text-lg'); // "lg:text-lg"
+ * ```
+ */
+export declare function applyResponsivePrefix(breakpoint: ResponsiveBreakpoint, className: string): string;
+/**
+ * Build responsive classes from a responsive value.
+ *
+ * @param value - Single value or object with breakpoint values
+ * @param resolver - Function to convert value to class
+ * @returns Array of responsive classes
+ *
+ * @example
+ * ```typescript
+ * // Single value
+ * buildResponsiveClasses('md', resolveSize);
+ * // Returns: ['h-10', 'px-4', 'text-sm']
+ *
+ * // Responsive object
+ * buildResponsiveClasses({ sm: 'sm', md: 'md', lg: 'lg' }, resolveSize);
+ * // Returns: ['sm:h-8', 'sm:px-3', 'h-10', 'px-4', 'lg:h-11', 'lg:px-5']
+ * ```
+ */
+export declare function buildResponsiveClasses<T>(value: ResponsiveValue<T>, resolver: (val: T) => string): string[];
+/**
+ * Build responsive size classes.
+ *
+ * @param size - Responsive size value
+ * @returns Responsive class string
+ *
+ * @example
+ * ```typescript
+ * // Single size
+ * buildResponsiveSizeClasses('md');
+ * // Returns: "h-10 px-4 text-sm"
+ *
+ * // Responsive sizes
+ * buildResponsiveSizeClasses({ sm: 'sm', lg: 'lg' });
+ * // Returns: "sm:h-8 sm:px-3 sm:text-sm lg:h-11 lg:px-5 lg:text-base"
+ * ```
+ */
+export declare function buildResponsiveSizeClasses(size: ResponsiveValue<ComponentSize>): string;
+export declare const TokenStyleResolver: {
+    resolve: typeof resolveTokenStyles;
+    buildClassName: typeof buildClassName;
+    clearCache: typeof clearStyleCache;
+    applyResponsivePrefix: typeof applyResponsivePrefix;
+    buildResponsiveClasses: typeof buildResponsiveClasses;
+    buildResponsiveSizeClasses: typeof buildResponsiveSizeClasses;
+};
+export default TokenStyleResolver;
+//# sourceMappingURL=TokenStyleResolver.d.ts.map