@digiform/builder 0.1.7 → 0.2.4

package/store/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Form Builder Store
+ * Zustand-based store for form wizard admin functionality
+ */
+export type { ComponentConfig, FormSectionConfig, FormStepConfig, FormWizardConfig, StepNavigation, StepNavigationItem, } from '../../../core/src/index.ts';
+export { generateId, useActionSheetOpen, useCanUndo, useCreatingActionTrigger, useCurrentSection, useCurrentStep, useCurrentStepLockState, useFormBuilderActions, useFormBuilderStore, useFormConfig, useFormFieldNodes, useFormFlowData, useFormSteps, useHasUnsavedChanges, useIsSaving, useLastSavedAt, useSaveError, useSelectedActionId, useSelectedComponentId, useSelectedSectionId, useSelectedStepId, useVisualMappings, } from './formBuilderStore';
+export type { StepTemplate, TemplateHistoryEntry, } from './initialState/templates';

package/store/initialState/templates.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Template initial state definitions
+ * Contains the template types and initial state for template management
+ */
+export interface StepTemplate {
+    id: string;
+    name: string;
+    description?: string;
+}
+export interface TemplateHistoryEntry {
+    id: string;
+    type: string;
+    timestamp: number;
+    operationData: {
+        templateId: string;
+        category: string;
+        templateName: string;
+        [key: string]: unknown;
+    };
+}
+export declare const initialTemplates: StepTemplate[];
+export declare const initialTemplateHistory: TemplateHistoryEntry[];

package/utils/configInitializer.d.ts

@@ -0,0 +1,11 @@
+import { FormWizardConfig } from '../../../core/src/index.ts';
+/**
+ * Initialize the form configuration service
+ * This function sets up any necessary services, validates configuration,
+ * and prepares the system for form operations
+ */
+export declare function initializeFormConfiguration(): Promise<void>;
+/**
+ * Create a new form configuration with default settings
+ */
+export declare function createDefaultFormConfig(title: string, formId: string): FormWizardConfig;

package/utils/configReader.d.ts

@@ -0,0 +1,13 @@
+import { FormConfig } from '../config/types';
+/**
+ * Resolves environment variables in configuration
+ * Supports ${VAR_NAME} syntax
+ *
+ * @param config - Raw configuration object that may contain environment variables
+ * @returns Resolved configuration with environment variables substituted
+ */
+export declare function resolveConfigVariables(config: unknown): FormConfig;
+/**
+ * Gets database configuration from a FormConfig
+ */
+export declare function getDatabaseConfig(config: FormConfig): import('../config/types').DatabaseConfig | null | undefined;

package/utils/fieldChangeValidation.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Field Change Validation System Types and Configurations
+ * Following SOLID principles for extensible validation architecture
+ */
+export interface FieldChangeValidationConfig {
+    id: string;
+    fieldId: string;
+    changeDetection: {
+        enabled: boolean;
+        compareStrategy: "strict" | "loose" | "custom";
+        customComparator?: (original: any, current: any) => boolean;
+    };
+    warningAlert?: {
+        enabled: boolean;
+        message: string;
+        type: "info" | "warning" | "error";
+        position: "inline" | "tooltip" | "sidebar";
+        dismissible: boolean;
+        showDelay?: number;
+    };
+    saveVerification?: {
+        enabled: boolean;
+        triggerConditions: {
+            onlyIfChanged: boolean;
+            requiresValidation: boolean;
+            customCondition?: string;
+        };
+        verificationConfig: {
+            type: "email" | "sms" | "custom";
+            dialogTemplate: string;
+            templateConfig: Record<string, any>;
+        };
+    };
+    conditions?: {
+        operator: "AND" | "OR";
+        rules: Array<{
+            field: string;
+            operator: "equals" | "notEquals" | "contains" | "empty" | "notEmpty";
+            value: any;
+        }>;
+    };
+}
+export interface FieldChangeState {
+    originalValue: any;
+    currentValue: any;
+    hasChanged: boolean;
+    changeTimestamp?: number;
+    validationWarnings: Array<{
+        id: string;
+        message: string;
+        type: string;
+        timestamp: number;
+        dismissible: boolean;
+    }>;
+}
+export interface FieldWarning {
+    id: string;
+    fieldId: string;
+    message: string;
+    type: "info" | "warning" | "error";
+    position: "inline" | "tooltip" | "sidebar";
+    dismissible: boolean;
+    timestamp: number;
+}
+export interface VerificationStatus {
+    status: "pending" | "success" | "failed";
+    timestamp: number;
+    result?: any;
+}
+export interface FieldValidationState {
+    activeWarnings: string[];
+    pendingVerifications: string[];
+    verificationResults: Record<string, VerificationStatus>;
+}
+export interface FieldChangeContext {
+    fieldId: string;
+    originalValue: any;
+    currentValue: any;
+    hasChanged: boolean;
+    formData: Record<string, any>;
+    sectionId?: string;
+    stepId?: string;
+}
+export interface ValidationResult {
+    fieldId: string;
+    shouldShowWarning: boolean;
+    warning?: FieldWarning;
+    shouldTriggerVerification: boolean;
+    verificationConfig?: FieldChangeValidationConfig["saveVerification"];
+}
+export interface SectionFieldValidationConfig {
+    enabled: boolean;
+    validationRules: FieldChangeValidationConfig[];
+    globalSettings?: {
+        warningThrottle: number;
+        autoSaveOnVerification: boolean;
+        fallbackErrorHandling: "block" | "warn" | "ignore";
+    };
+}
+export interface VerificationConfig {
+    type: "email" | "sms" | "custom";
+    dialogTemplate: string;
+    templateConfig: Record<string, any>;
+    onSuccess?: (result: any) => void;
+    onError?: (error: Error) => void;
+    onCancel?: () => void;
+}
+export interface IFieldChangeDetector {
+    registerComparator(strategy: string, comparator: (a: any, b: any) => boolean): void;
+    detectChange(fieldId: string, originalValue: any, currentValue: any, strategy?: string): boolean;
+}
+export interface IFieldValidationEngine {
+    registerRule(rule: FieldChangeValidationConfig): void;
+    removeRule(fieldId: string): void;
+    evaluateFieldChange(fieldId: string, changeContext: FieldChangeContext): ValidationResult;
+}
+export interface IWarningManager {
+    showWarning(warning: FieldWarning): void;
+    dismissWarning(fieldId: string, warningId?: string): void;
+    getActiveWarnings(fieldId: string): FieldWarning[];
+    clearAllWarnings(fieldId?: string): void;
+}
+export interface IVerificationManager {
+    startVerification(fieldId: string, config: VerificationConfig): Promise<any>;
+    getVerificationStatus(fieldId: string): VerificationStatus | null;
+    clearVerificationResult(fieldId: string): void;
+}

package/utils/fileStorage.d.ts

@@ -0,0 +1,253 @@
+import { FormStepConfig, FormWizardConfig } from '../../../core/src/index.ts';
+/**
+ * File-based storage types for FormBuilder
+ */
+export interface FormBuilderSettings {
+    /** Base directory where form configurations are stored */
+    formsDirectory: string;
+    /** Default form template to use when creating new forms */
+    defaultTemplate?: string;
+    /** Auto-save interval in milliseconds (0 to disable) */
+    autoSaveInterval?: number;
+    /** Whether to create backups before saving */
+    createBackups?: boolean;
+}
+export interface FormFile {
+    /** Unique identifier for the form */
+    id: string;
+    /** Display name of the form */
+    name: string;
+    /** Relative path to the JSON file */
+    filePath: string;
+    /** Last modified timestamp */
+    lastModified?: number;
+    /** File size in bytes */
+    size?: number;
+}
+export interface FormDirectory {
+    /** List of available forms */
+    forms: FormFile[];
+    /** Settings for the form builder */
+    settings: FormBuilderSettings;
+}
+export interface FileStorageError {
+    type: "READ_ERROR" | "WRITE_ERROR" | "PARSE_ERROR" | "NOT_FOUND" | "PERMISSION_ERROR" | "VALIDATION_ERROR" | "CONFIGURATION_ERROR";
+    message: string;
+    filePath?: string;
+}
+export type FileStorageResult<T> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: FileStorageError;
+};
+/**
+ * Template storage configuration
+ */
+export interface TemplateStorageConfig {
+    /** Team template storage location (configured by developers) */
+    team: string;
+    /** Generic/organization template storage location (built-in path, not configurable) */
+    generic?: string;
+}
+/**
+ * Template metadata interface
+ */
+export interface TemplateMetadata {
+    /** Unique identifier for the template */
+    id: string;
+    /** Display name of the template */
+    name: string;
+    /** Detailed description of the template */
+    description?: string;
+    /** Template category */
+    category: TemplateCategory;
+    /** Tags for organizing and searching templates */
+    tags?: string[];
+    /** Creator information */
+    createdBy?: string;
+    /** Creation timestamp */
+    createdAt: number;
+    /** Last modified timestamp */
+    lastModified: number;
+    /** Template version */
+    version?: string;
+    /** Usage count for analytics */
+    usageCount?: number;
+}
+/**
+ * Template categories
+ */
+export type TemplateCategory = "team" | "generic" | "personal" | "shared";
+/**
+ * Base template interface
+ */
+export interface BaseTemplate {
+    /** Template metadata */
+    metadata: TemplateMetadata;
+    /** Step configuration data */
+    stepsData: FormStepConfig;
+    /** Template preview data */
+    preview?: {
+        componentCount: number;
+        sectionCount: number;
+        previewImage?: string;
+    };
+}
+/**
+ * Personal template (editable by individual users)
+ */
+export interface PersonalTemplate extends BaseTemplate {
+    metadata: TemplateMetadata & {
+        category: "personal";
+    };
+}
+/**
+ * Shared template (editable by authorized users)
+ */
+export interface SharedTemplate extends BaseTemplate {
+    metadata: TemplateMetadata & {
+        category: "shared";
+    };
+    /** Sharing configuration for collaborative templates */
+    sharing: {
+        /** Template owner */
+        owner: string;
+        /** Edit permissions */
+        editPermissions: "owner" | "team" | "public";
+        /** List of collaborators who can edit */
+        collaborators?: string[];
+    };
+}
+/**
+ * Team template (editable by team members)
+ */
+export interface TeamTemplate extends BaseTemplate {
+    metadata: TemplateMetadata & {
+        category: "team";
+    };
+}
+/**
+ * Generic/Organization template (read-only)
+ */
+export interface GenericTemplate extends BaseTemplate {
+    metadata: TemplateMetadata & {
+        category: "generic";
+    };
+    /** Governance information */
+    governance: {
+        /** Approval status */
+        approved: boolean;
+        /** Approval date */
+        approvedAt?: number;
+        /** Approver information */
+        approvedBy?: string;
+        /** Compliance tags */
+        complianceTags?: string[];
+        /** Is this template deprecated */
+        deprecated?: boolean;
+        /** Deprecation reason */
+        deprecationReason?: string;
+    };
+}
+/**
+ * Union type for all template types
+ */
+export type Template = PersonalTemplate | SharedTemplate | TeamTemplate | GenericTemplate;
+/**
+ * Template file reference (for indexing)
+ */
+export interface TemplateFile {
+    /** Unique identifier for the template */
+    id: string;
+    /** Display name of the template */
+    name: string;
+    /** Detailed description of the template */
+    description?: string;
+    /** Template category */
+    category: TemplateCategory;
+    /** Tags for organizing and searching templates */
+    tags?: string[];
+    /** Creator information */
+    createdBy?: string;
+    /** Creation timestamp */
+    createdAt: number;
+    /** Last modified timestamp */
+    lastModified: number;
+    /** Template version */
+    version?: string;
+    /** Usage count for analytics */
+    usageCount?: number;
+    /** Relative path to the template JSON file */
+    filePath?: string;
+    /** File size in bytes */
+    size?: number;
+}
+/**
+ * Template directory structure
+ */
+export interface TemplateDirectory {
+    /** Template category */
+    category: TemplateCategory;
+    /** List of available templates */
+    templates: TemplateFile[];
+    /** Directory path */
+    path: string;
+}
+/**
+ * Default settings for file-based storage
+ */
+export declare const DEFAULT_SETTINGS: FormBuilderSettings;
+/**
+ * Load settings from a settings.json file
+ */
+export declare function loadSettings(settingsPath?: string): Promise<FileStorageResult<FormBuilderSettings>>;
+/**
+ * Save settings to a settings.json file
+ */
+export declare function saveSettings(settings: FormBuilderSettings, settingsPath?: string): Promise<FileStorageResult<void>>;
+/**
+ * Load a form configuration from a JSON file
+ */
+export declare function loadForm(filePath: string): Promise<FileStorageResult<FormWizardConfig>>;
+/**
+ * Save a form configuration to a JSON file
+ */
+export declare function saveForm(config: FormWizardConfig, filePath: string, createBackup?: boolean): Promise<FileStorageResult<void>>;
+/**
+ * Create a backup of a form file
+ */
+export declare function createFormBackup(filePath: string): Promise<FileStorageResult<string>>;
+/**
+ * List all forms in the forms directory
+ */
+export declare function listForms(settings: FormBuilderSettings): Promise<FileStorageResult<FormFile[]>>;
+/**
+ * Create a new form file
+ */
+export declare function createForm(config: FormWizardConfig, settings: FormBuilderSettings): Promise<FileStorageResult<string>>;
+/**
+ * Delete a form file
+ */
+export declare function deleteForm(formId: string, settings: FormBuilderSettings): Promise<FileStorageResult<void>>;
+/**
+ * Load template storage configuration from form.config.json
+ */
+export declare function loadTemplateStorageConfig(): Promise<FileStorageResult<TemplateStorageConfig>>;
+/**
+ * Save a template to the appropriate storage location
+ */
+export declare function saveTemplate(template: Template, storageConfig: TemplateStorageConfig): Promise<FileStorageResult<string>>;
+/**
+ * Load a template from storage
+ */
+export declare function loadTemplate(templateId: string, category: TemplateCategory, storageConfig: TemplateStorageConfig): Promise<FileStorageResult<Template>>;
+/**
+ * List all templates in a category
+ */
+export declare function listTemplates(category: TemplateCategory, storageConfig: TemplateStorageConfig): Promise<FileStorageResult<TemplateFile[]>>;
+/**
+ * Delete a template
+ */
+export declare function deleteTemplate(templateId: string, category: TemplateCategory, storageConfig: TemplateStorageConfig): Promise<FileStorageResult<void>>;

package/utils/formSaver.d.ts

@@ -0,0 +1,22 @@
+import { FormWizardConfig } from '../../../core/src/index.ts';
+export interface SaveResult {
+    success: boolean;
+    error?: {
+        message: string;
+        code?: string;
+    };
+    metadata?: {
+        filePath?: string;
+        timestamp?: number;
+    };
+}
+/**
+ * Save form configuration using the pluggable save provider system
+ * This is a self-contained function that doesn't rely on external utilities
+ */
+export declare function saveFormConfig(projectId: string, wizardId: string, config: FormWizardConfig): Promise<SaveResult>;
+/**
+ * Load form configuration
+ * Companion function to saveFormConfig for loading saved forms
+ */
+export declare function loadFormConfig(projectId: string, wizardId: string): Promise<FormWizardConfig | null>;

package/utils/formsExplorer.d.ts

@@ -0,0 +1,128 @@
+import { CreateFormRequest, CreateProjectRequest, FormMetadata, FormsIndex, FormWizardConfig, ProjectMetadata } from '../../../core/src/index.ts';
+import { FormConfig } from '../config/types';
+import { FormSaveProvider } from '../providers';
+import { FormStorageConfig, FormStorageProvider } from '../storage/types';
+/**
+ * Form operations configuration interface
+ * Uses unified FormConfig throughout the system
+ */
+export interface FormOperationsConfig {
+    /** Form configuration from context or props */
+    formConfig?: FormConfig;
+    /** Custom API base URL override */
+    apiBaseUrl?: string;
+    /** Custom storage provider override */
+    storageProvider?: "filesystem" | "database" | "memory";
+}
+/**
+ * Storage strategy abstraction for future extensibility
+ */
+export interface StorageStrategy {
+    name: "filesystem" | "database" | "memory";
+    saveForm(projectId: string, wizardId: string, config: FormWizardConfig, options?: FormOperationsConfig): Promise<boolean>;
+    loadForm(projectId: string, wizardId: string, options?: FormOperationsConfig): Promise<FormWizardConfig | null>;
+    deleteForm(projectId: string, wizardId: string, options?: FormOperationsConfig): Promise<boolean>;
+    createProject(request: CreateProjectRequest, options?: FormOperationsConfig): Promise<boolean>;
+}
+/**
+ * Register a custom storage strategy
+ */
+export declare function registerStorageStrategy(name: string, strategy: StorageStrategy): void;
+/**
+ * Set a global save provider for the forms explorer
+ * This allows framework-specific implementations to be plugged in
+ */
+export declare function setGlobalFormSaveProvider(provider: FormSaveProvider): void;
+/**
+ * Get the current save provider using the storage provider system
+ */
+export declare function getFormSaveProvider(): Promise<FormSaveProvider>;
+/**
+ * Get form configuration - framework agnostic
+ * Supports both legacy and enhanced configuration
+ */
+export declare function getFormConfig(): Promise<FormConfig>;
+/**
+ * Get base path for forms directory from configuration
+ */
+export declare function getFormsBasePath(options?: FormOperationsConfig): Promise<string>;
+/**
+ * Clear the scan cache - useful after data mutations
+ */
+export declare function clearScanCache(): void;
+/**
+ * Scan the forms directory structure and build an index with caching
+ */
+export declare function scanFormsDirectory(options?: FormOperationsConfig): Promise<FormsIndex>;
+/**
+ * Load project index from project directory
+ */
+export declare function loadProjectIndex(projectId: string, options?: FormOperationsConfig): Promise<{
+    project: {
+        name?: string;
+        description?: string;
+        lastModified?: number;
+    };
+    forms: FormMetadata[];
+} | null>;
+/**
+ * Scan a specific project directory
+ */
+export declare function scanProjectDirectory(projectId: string, options?: FormOperationsConfig): Promise<ProjectMetadata | null>;
+/**
+ * Format project ID to display name
+ */
+export declare function formatProjectName(projectId: string): string;
+/**
+ * Load a form configuration using the configured storage strategy
+ */
+export declare function loadFormConfigFromExplorer(projectId: string, wizardId: string, options?: FormOperationsConfig): Promise<FormWizardConfig | null>;
+/**
+ * Save a form configuration using the pluggable save provider
+ */
+export declare function saveFormConfig(projectId: string, wizardId: string, config: FormWizardConfig, options?: FormOperationsConfig): Promise<boolean>;
+/**
+ * Create a new project
+ */
+export declare function createProject(request: CreateProjectRequest): Promise<{
+    success: true;
+    projectId: string;
+    name: string;
+    description?: string;
+} | {
+    success: false;
+}>;
+/**
+ * Create a new form in a project
+ */
+export declare function createForm(request: CreateFormRequest, options?: FormOperationsConfig): Promise<FormWizardConfig | null>;
+/**
+ * Delete a form from a project
+ */
+export declare function deleteForm(projectId: string, wizardId: string, options?: FormOperationsConfig): Promise<boolean>;
+/**
+ * Get form URL for editing
+ */
+export declare function getFormEditUrl(projectId: string, wizardId: string): string;
+/**
+ * Parse form URL parameters
+ */
+export declare function parseFormUrl(pathname: string): {
+    projectId: string;
+    wizardId: string;
+} | null;
+/**
+ * Get the current storage provider for operations
+ */
+export declare function getCurrentStorageProvider(options?: FormOperationsConfig): Promise<FormStorageProvider | null>;
+/**
+ * Get storage provider from configuration.
+ * Recommended replacement for getCurrentStorageProvider().
+ *
+ * Usage:
+ *   const provider = await getStorageProvider(formConfig.storage);
+ *
+ * @param storageConfig - Storage configuration from form.config.ts
+ * @returns FormStorageProvider or null if initialization fails
+ */
+export declare function getStorageProvider(storageConfig: FormStorageConfig): Promise<FormStorageProvider | null>;

package/utils/index.d.ts

@@ -0,0 +1,2 @@
+export * from './configInitializer';
+export * from './formsExplorer';

package/utils/routeUtils.d.ts

@@ -0,0 +1,85 @@
+import { FormConfig, RouteConfig } from '../config/types';
+/**
+ * Parameters that can be used in route patterns
+ */
+export interface RouteParams {
+    project?: string;
+    wizardId?: string;
+    [key: string]: string | undefined;
+}
+/**
+ * Gets route configuration from FormConfig, falling back to defaults
+ */
+export declare function getRouteConfig(config?: FormConfig): Required<RouteConfig>;
+/**
+ * Generates a URL from a route pattern by substituting parameters
+ *
+ * @param pattern - Route pattern with parameters (e.g., "/forms/:project/:wizardId")
+ * @param params - Parameters to substitute (e.g., { project: "myproject", wizardId: "form1" })
+ * @returns Generated URL with parameters substituted
+ *
+ * @example
+ * generateUrl("/forms/:project/:wizardId", { project: "myproject", wizardId: "form1" })
+ * // Returns: "/forms/myproject/form1"
+ */
+export declare function generateUrl(pattern: string, params?: RouteParams): string;
+/**
+ * Route generator functions that use the configured routes
+ */
+export declare class RouteGenerator {
+    private routes;
+    constructor(config?: FormConfig);
+    /**
+     * Generate URL for projects page
+     */
+    projects(): string;
+    /**
+     * Generate URL for forms page
+     */
+    forms(projectId: string): string;
+    /**
+     * Generate URL for form builder page
+     */
+    builder(projectId: string, wizardId: string): string;
+    /**
+     * Generate URL for form preview page
+     */
+    preview(projectId: string, wizardId: string): string;
+}
+/**
+ * Navigation functions that work with any router
+ * These functions generate URLs but don't perform navigation - that's left to the routing system
+ */
+export interface NavigationUrls {
+    projects(): string;
+    forms(projectId: string): string;
+    builder(projectId: string, wizardId: string): string;
+    preview(projectId: string, wizardId: string): string;
+}
+/**
+ * Creates navigation URL generators from configuration
+ */
+export declare function createNavigationUrls(config?: FormConfig): NavigationUrls;
+/**
+ * Hook-like interface for navigation (compatible with React Router's useNavigate)
+ */
+export type NavigationHandler = (path: string) => void;
+/**
+ * Creates navigation functions that use a provided navigation handler
+ * Works with any routing system that provides a navigation function
+ */
+export declare function createNavigationFunctions(navigate: NavigationHandler, config?: FormConfig): {
+    navigateToProjects: () => void;
+    navigateToForms: (projectId: string) => void;
+    navigateToBuilder: (projectId: string, wizardId: string) => void;
+    navigateToPreview: (projectId: string, wizardId: string) => void;
+};
+/**
+ * Utility to check if a route pattern matches a given path
+ * Useful for determining which page is currently active
+ */
+export declare function matchesRoute(pattern: string, path: string): boolean;
+/**
+ * Extract parameters from a path using a route pattern
+ */
+export declare function extractParams(pattern: string, path: string): RouteParams;