@digiform/builder 0.1.7 → 0.2.1

package/providers/FormSaveProvider.d.ts

@@ -0,0 +1,93 @@
+import { FormWizardConfig } from '../../../core/src/index.ts';
+import { FormConfig, FormStorageConfig } from '../config/types';
+/**
+ * Save operation result
+ */
+export interface SaveResult {
+    success: boolean;
+    error?: {
+        message: string;
+        code?: string;
+    };
+    metadata?: {
+        filePath?: string;
+        savedAt?: Date;
+        size?: number;
+    };
+}
+/**
+ * Load operation result
+ */
+export interface LoadResult {
+    success: boolean;
+    data?: FormWizardConfig;
+    error?: {
+        message: string;
+        code?: string;
+    };
+    metadata?: {
+        source?: "filesystem" | "api" | "cache";
+        lastModified?: Date;
+        size?: number;
+    };
+}
+/**
+ * Form save provider interface - implement this for different frameworks
+ */
+export interface FormSaveProvider {
+    /**
+     * Save a form configuration
+     */
+    saveForm(projectId: string, wizardId: string, config: FormWizardConfig, storageConfig: FormStorageConfig): Promise<SaveResult>;
+    /**
+     * Load a form configuration
+     */
+    loadForm(projectId: string, wizardId: string, storageConfig: FormStorageConfig): Promise<LoadResult>;
+    /**
+     * Check if a form exists
+     */
+    formExists?(projectId: string, wizardId: string, storageConfig: FormStorageConfig): Promise<boolean>;
+    /**
+     * Delete a form
+     */
+    deleteForm?(projectId: string, wizardId: string, storageConfig: FormStorageConfig): Promise<SaveResult>;
+    /**
+     * List forms in a project
+     */
+    listForms?(projectId: string, storageConfig: FormStorageConfig): Promise<{
+        forms: string[];
+        success: boolean;
+        error?: {
+            message: string;
+        };
+    }>;
+}
+/**
+ * Default file system save provider (works with Vite dev server and similar setups)
+ * This is the fallback implementation that uses HTTP endpoints
+ */
+export declare class HttpEndpointSaveProvider implements FormSaveProvider {
+    saveForm(projectId: string, wizardId: string, config: FormWizardConfig, storageConfig: FormStorageConfig): Promise<SaveResult>;
+    loadForm(projectId: string, wizardId: string, storageConfig: FormStorageConfig): Promise<LoadResult>;
+    formExists(projectId: string, wizardId: string, storageConfig: FormStorageConfig): Promise<boolean>;
+    deleteForm(projectId: string, wizardId: string, storageConfig: FormStorageConfig): Promise<SaveResult>;
+}
+/**
+ * Form configuration loader - reads from form.config.json
+ */
+export declare class FormConfigLoader {
+    private static instance;
+    private configCache;
+    private configPromise;
+    static getInstance(): FormConfigLoader;
+    /**
+     * Load form configuration from form.config.json
+     */
+    loadConfig(): Promise<FormConfig>;
+    private fetchConfig;
+    private getDefaultConfig;
+    /**
+     * Clear cached config (useful for testing or hot reloading)
+     */
+    clearCache(): void;
+}

package/providers/ThemeProvider.d.ts

@@ -0,0 +1,2 @@
+export { ThemeProvider, useTheme, useThemeConfig } from '../../../ui/src/index.ts';
+export type { ThemeConfig, ThemeProviderProps } from '../../../ui/src/index.ts';

package/providers/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Framework-agnostic form save providers
+ * Export all providers and utilities for easy importing
+ */
+export type { FormConfig, FormStorageConfig } from '../config/types';
+export * from './FormSaveContext';
+export type { FormSaveProvider, LoadResult, SaveResult, } from './FormSaveProvider';
+export * from './FormSaveProvider';
+export { ThemeProvider, useTheme, useThemeConfig } from './ThemeProvider';

package/server.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Server entry point for @formbuilder/builder
+ * Contains storage providers that require Node.js APIs (node:fs, node:path).
+ * Only import this in server-side code (Node.js, Next.js Server Components, API routes).
+ */
+export { FilesystemStorageProvider } from './storage/FilesystemStorageProvider';
+export { type DataConsistencyProvider, type ProviderCapabilities, StorageProviderFactory, } from './storage/StorageProviderFactory';
+export type { CreateFormRequest, CreateProjectRequest, FormMetadata, FormStorageConfig, FormStorageProvider, StorageResult, } from './storage/types';

package/storage/FilesystemStorageProvider.d.ts

@@ -0,0 +1,19 @@
+import { FormConfig } from '../config/types';
+import { CreateProjectRequest, FormMetadata, FormStorageConfig, FormStorageProvider, StorageResult } from './types';
+export declare class FilesystemStorageProvider implements FormStorageProvider {
+    private config;
+    private basePath;
+    initialize(config: FormStorageConfig): Promise<void>;
+    listForms(): Promise<StorageResult<FormMetadata[]>>;
+    loadForm(projectId: string, wizardId: string): Promise<StorageResult<FormConfig>>;
+    saveForm(projectId: string, wizardId: string, config: FormConfig): Promise<StorageResult>;
+    createProject(request: CreateProjectRequest): Promise<StorageResult>;
+    deleteForm(projectId: string, wizardId: string): Promise<StorageResult>;
+    getType(): string;
+    private ensureDirectoryExists;
+    /**
+     * Set the base path for the storage provider
+     * This allows applications to configure where forms are stored
+     */
+    setBasePath(basePath: string): void;
+}

package/storage/NullStorageProvider.d.ts

@@ -0,0 +1,15 @@
+import { FormStorageConfig, FormStorageProvider, StorageResult } from './types';
+export declare class NullStorageProvider implements FormStorageProvider {
+    getType(): string;
+    initialize(_config: FormStorageConfig): Promise<void>;
+    listForms(): Promise<StorageResult>;
+    loadForm(_projectId: string, _wizardId: string): Promise<StorageResult>;
+    saveForm(_projectId: string, _wizardId: string, _config: Record<string, unknown>): Promise<StorageResult>;
+    deleteForm(_projectId: string, _wizardId: string): Promise<StorageResult>;
+    listProjects(): Promise<StorageResult>;
+    createProject(_request: {
+        name: string;
+        directoryName?: string;
+    }): Promise<StorageResult>;
+    deleteProject(_projectId: string): Promise<StorageResult>;
+}

package/storage/PgLiteSyncProvider.d.ts

@@ -0,0 +1,41 @@
+import { CreateProjectRequest, FormMetadata, FormStorageConfig, FormStorageProvider, StorageResult } from './types';
+export interface PgLiteSyncConfig {
+    persistence?: "indexeddb" | "memory";
+}
+export declare class PgLiteSyncProvider implements FormStorageProvider {
+    private localDb;
+    private config;
+    private isInitialized;
+    constructor(config: PgLiteSyncConfig);
+    initialize(_config: FormStorageConfig): Promise<void>;
+    init(): Promise<void>;
+    private migrateSchemaIfNeeded;
+    private migrateExistingData;
+    private createTables;
+    /**
+     * Initialize SERIAL sequences to handle any existing data
+     */
+    private initializeSequences;
+    saveForm(projectId: string, wizardId: string, config: Record<string, unknown>): Promise<StorageResult>;
+    loadForm(projectId: string, wizardId: string): Promise<StorageResult<Record<string, unknown>>>;
+    listProjects(): Promise<StorageResult<Array<{
+        id: string;
+        name: string;
+        description?: string;
+        created_at: string;
+        updated_at: string;
+    }>>>;
+    listForms(): Promise<StorageResult<FormMetadata[]>>;
+    deleteForm(projectId: string, wizardId: string): Promise<StorageResult>;
+    createProject(request: CreateProjectRequest): Promise<StorageResult>;
+    deleteProject(projectId: string): Promise<StorageResult>;
+    private ensureProject;
+    private ensureInitialized;
+    getStats(): Promise<{
+        projects: number;
+        forms: number;
+    }>;
+    exportData(): Promise<string>;
+    getType(): string;
+    close(): Promise<void>;
+}

package/storage/StorageProviderFactory.d.ts

@@ -0,0 +1,77 @@
+import { FormStorageConfig, FormStorageProvider } from './types';
+/**
+ * Provider capabilities interface for UI components
+ */
+export interface ProviderCapabilities {
+    strategy: "filesystem" | "database" | "none";
+    isLive: boolean;
+    hasSync: boolean;
+    isZeroConfig: boolean;
+    supportsOffline: boolean;
+}
+/**
+ * Interface for providers that support data consistency validation
+ */
+export interface DataConsistencyProvider {
+    validateDataConsistency(): Promise<boolean>;
+    reconcileConflicts(): Promise<boolean>;
+    resetLocalData(): Promise<boolean>;
+    getDataIntegrityStatus(): {
+        status: "consistent" | "inconsistent" | "unknown";
+        reconciling: boolean;
+        lastValidation: string | null;
+    };
+}
+export declare class StorageProviderFactory {
+    private static instance;
+    private currentProvider;
+    private currentConfig;
+    private isInitializing;
+    private initializationPromise;
+    /**
+     * Get singleton instance
+     */
+    static getInstance(): StorageProviderFactory;
+    /**
+     * Create and initialize a storage provider based on configuration
+     */
+    createProvider(config: FormStorageConfig): Promise<FormStorageProvider>;
+    /**
+     * Internal provider creation method
+     */
+    private doCreateProvider;
+    /**
+     * Type guard to check if provider supports data consistency validation
+     */
+    private isDataConsistencyProvider;
+    /**
+     * Check if the current configuration is compatible with a new config
+     */
+    private isConfigCompatible;
+    /**
+     * Create a filesystem provider based on environment
+     * Uses dynamic import for FilesystemStorageProvider to avoid bundling node:fs in client code
+     */
+    private createFilesystemProvider;
+    /**
+     * Create a database provider - always uses PgLiteSyncProvider for local-first approach
+     * Database connection is mandatory - no offline-only mode
+     */
+    private createDatabaseProvider;
+    /**
+     * Get the current provider
+     */
+    getCurrentProvider(): FormStorageProvider | null;
+    /**
+     * Get the current provider with data consistency capabilities
+     */
+    getCurrentDataConsistencyProvider(): DataConsistencyProvider | null;
+    /**
+     * Get capabilities of the current provider for UI components
+     */
+    getProviderCapabilities(): ProviderCapabilities | null;
+    /**
+     * Create a provider without caching it (useful for testing or migration)
+     */
+    static createStandaloneProvider(config: FormStorageConfig): Promise<FormStorageProvider>;
+}

package/storage/ZeroConfigFilesystemStorageProvider.d.ts

@@ -0,0 +1,157 @@
+import { CreateProjectRequest, FormMetadata, FormStorageConfig, FormStorageProvider, StorageResult } from './types';
+/**
+ * Capabilities of the current environment
+ */
+interface EnvironmentCapabilities {
+    /** Whether File System Access API is available */
+    hasFileSystemAccess: boolean;
+    /** Whether we're in a secure context (required for File System Access API) */
+    isSecureContext: boolean;
+    /** Whether we're in development mode */
+    isDevelopment: boolean;
+    /** Primary storage method to use */
+    primaryMethod: "file-system-access" | "localstorage-download";
+}
+export declare class ZeroConfigFilesystemStorageProvider implements FormStorageProvider {
+    private config;
+    private capabilities;
+    private directoryHandle;
+    private userMessage;
+    constructor();
+    /**
+     * Detect what filesystem capabilities are available in this environment
+     */
+    private detectEnvironmentCapabilities;
+    /**
+     * Generate user-friendly message about current capabilities
+     */
+    private generateUserMessage;
+    initialize(config: FormStorageConfig): Promise<void>;
+    /**
+     * Check if localStorage is available and working
+     */
+    private ensureLocalStorageAvailable;
+    /**
+     * Request directory access for File System Access API
+     * @param userInitiated - Whether this request is user-initiated (required for SecurityError handling)
+     */
+    private requestDirectoryAccess;
+    listForms(): Promise<StorageResult<FormMetadata[]>>;
+    /**
+     * List forms from server/filesystem via HTTP (for existing files)
+     */
+    private listFormsFromServer;
+    /**
+     * Discover forms by trying common project/form combinations
+     */
+    private discoverFormsFromServer;
+    /**
+     * Process forms from a manifest file
+     */
+    private processManifestForms;
+    /**
+     * Merge forms lists, with server forms taking priority over local storage
+     */
+    private mergeFormsLists;
+    /**
+     * List forms using LocalStorage
+     */
+    private listFormsLocalStorage;
+    loadForm(projectId: string, wizardId: string): Promise<StorageResult<Record<string, unknown>>>;
+    /**
+     * Load form using File System Access API
+     */
+    private loadFormFileSystemAccess;
+    /**
+     * Load form using HTTP from the server filesystem
+     */
+    private loadFormHttp;
+    /**
+     * Load form using LocalStorage
+     */
+    private loadFormLocalStorage;
+    saveForm(projectId: string, wizardId: string, config: Record<string, unknown>): Promise<StorageResult>;
+    /**
+     * Save form using File System Access API
+     */
+    private saveFormFileSystemAccess;
+    /**
+     * Save form using HTTP to the server filesystem
+     */
+    private saveFormHttp;
+    /**
+     * Delete form using HTTP DELETE request
+     */
+    private deleteFormHttp;
+    /**
+     * Save form using LocalStorage with automatic download
+     */
+    private saveFormLocalStorage;
+    /**
+     * Download form as a file (backup for localStorage method)
+     */
+    private downloadFormAsFile;
+    createProject(request: CreateProjectRequest): Promise<StorageResult>;
+    /**
+     * Create project using File System Access API
+     */
+    private createProjectFileSystemAccess;
+    /**
+     * Create project using HTTP to the server filesystem
+     */
+    private createProjectHttp;
+    /**
+     * Create project using LocalStorage (no-op since directories don't exist)
+     */
+    private createProjectLocalStorage;
+    deleteForm(projectId: string, wizardId: string): Promise<StorageResult>;
+    /**
+     * Delete form using File System Access API
+     */
+    private deleteFormFileSystemAccess;
+    /**
+     * Delete form using LocalStorage
+     */
+    private deleteFormLocalStorage;
+    /**
+     * Delete an entire project and all its forms
+     */
+    deleteProject(projectId: string): Promise<StorageResult>;
+    /**
+     * Delete project using HTTP DELETE request
+     */
+    private deleteProjectHttp;
+    /**
+     * Delete project using File System Access API
+     */
+    private deleteProjectFileSystemAccess;
+    /**
+     * Delete project using LocalStorage (removes all forms in project)
+     */
+    private deleteProjectLocalStorage;
+    getType(): string;
+    /**
+     * Manually enable filesystem access (user-initiated)
+     */
+    enableFilesystemAccess(): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /**
+     * Get current capabilities and user message
+     */
+    getCapabilities(): {
+        capabilities: EnvironmentCapabilities;
+        userMessage: string;
+        hasDirectoryAccess: boolean;
+        canUpgradeToFilesystem: boolean;
+    };
+    /**
+     * Export all forms as a downloadable backup
+     */
+    exportFormsBackup(): Promise<StorageResult<{
+        fileName: string;
+        count: number;
+    }>>;
+}
+export {};