@entrypulse/builder 1.0.0

package/README.md

@@ -0,0 +1,330 @@
+# EntryPulse
+
+A customizable React form builder with drag-and-drop functionality and extensible toolbar actions.
+
+## Installation
+
+```bash
+npm install entry-pulse
+# or
+yarn add entry-pulse
+```
+
+## Quick Start
+
+```tsx
+import { EntryPulse } from 'entry-pulse';
+import 'entry-pulse/styles.css';
+
+function App() {
+  return <EntryPulse />;
+}
+```
+
+## Custom Toolbar Actions
+
+EntryPulse allows you to customize the toolbar by adding your own actions, overriding built-in actions, or hiding specific functionality.
+
+### Adding Custom Actions
+
+Use `createToolbarAction` to create custom toolbar buttons:
+
+```tsx
+import { EntryPulse, createToolbarAction } from 'entry-pulse';
+import { Save, Globe } from 'lucide-react';
+
+// Create a save action
+const saveAction = createToolbarAction({
+  id: 'save',
+  icon: Save,
+  label: 'Save Form',
+  position: 'right',
+  order: -2, // Negative order places it before built-in right actions
+  onClick: (ctx) => {
+    // Access the current schema
+    const { schema } = ctx;
+    
+    // Save to your backend
+    fetch('/api/forms', {
+      method: 'POST',
+      body: JSON.stringify(schema)
+    });
+  }
+});
+
+// Create a publish action with dynamic disabled state
+const publishAction = createToolbarAction({
+  id: 'publish',
+  icon: Globe,
+  label: 'Publish Form',
+  position: 'right',
+  order: -1,
+  // Disabled when form is empty
+  disabled: (ctx) => ctx.schema.elements.length === 0,
+  onClick: async (ctx) => {
+    await publishForm(ctx.schema);
+  }
+});
+
+function App() {
+  return (
+    <EntryPulse
+      toolbarActions={[saveAction, publishAction]}
+    />
+  );
+}
+```
+
+### Creating Multiple Actions
+
+Use `createToolbarActions` to create multiple actions at once:
+
+```tsx
+import { createToolbarActions } from 'entry-pulse';
+import { Cloud, Settings, Share } from 'lucide-react';
+
+const actions = createToolbarActions([
+  {
+    id: 'cloud-sync',
+    icon: Cloud,
+    label: 'Sync to Cloud',
+    position: 'right',
+    onClick: (ctx) => syncToCloud(ctx.schema)
+  },
+  {
+    id: 'settings',
+    icon: Settings,
+    label: 'Form Settings',
+    position: 'left',
+    onClick: (ctx) => openSettings()
+  },
+  {
+    id: 'share',
+    icon: Share,
+    label: 'Share Form',
+    position: 'right',
+    onClick: (ctx) => shareForm(ctx.schema.id)
+  }
+]);
+
+<EntryPulse toolbarActions={actions} />
+```
+
+### Toolbar Action Context
+
+Every action receives a context object with access to the form state and actions:
+
+```tsx
+interface ToolbarActionContext {
+  // Current form schema
+  schema: FormSchema;
+  
+  // Current mode ('design' or 'preview')
+  mode: 'design' | 'preview';
+  
+  // Undo/redo availability
+  canUndo: boolean;
+  canRedo: boolean;
+  
+  // Available actions
+  actions: {
+    undo: () => void;
+    redo: () => void;
+    loadSchema: (schema: FormSchema) => void;
+    exportSchema: () => FormSchema;
+    setMode: (mode: 'design' | 'preview') => void;
+    resetForm: () => void;
+  };
+}
+```
+
+### Action Configuration Options
+
+```tsx
+interface ToolbarAction {
+  // Unique identifier
+  id: string;
+  
+  // Icon component (lucide-react or custom)
+  icon: LucideIcon | ComponentType<{ className?: string }>;
+  
+  // Tooltip label
+  label: string;
+  
+  // Position: 'left' | 'center' | 'right'
+  position: ToolbarActionPosition;
+  
+  // Order within position (lower = earlier, default: 0)
+  order?: number;
+  
+  // Click handler
+  onClick: (context: ToolbarActionContext) => void | Promise<void>;
+  
+  // Static or dynamic disabled state
+  disabled?: boolean | ((context: ToolbarActionContext) => boolean);
+  
+  // Visual variant: 'default' | 'ghost' | 'destructive'
+  variant?: ToolbarActionVariant;
+  
+  // Static or dynamic hidden state
+  hidden?: boolean | ((context: ToolbarActionContext) => boolean);
+  
+  // Override a built-in action
+  override?: BuiltinToolbarActionId;
+}
+```
+
+### Overriding Built-in Actions
+
+Replace built-in actions with custom implementations:
+
+```tsx
+const customExportAction = createToolbarAction({
+  id: 'custom-export',
+  icon: Download,
+  label: 'Export to CSV',
+  position: 'right',
+  override: 'export', // Replaces the built-in export button
+  onClick: (ctx) => {
+    // Custom export logic
+    exportToCSV(ctx.schema);
+  }
+});
+```
+
+Available built-in action IDs to override:
+- `'undo'` - Undo button
+- `'redo'` - Redo button
+- `'export'` - Export button
+- `'import'` - Import button
+- `'reset'` - Reset/trash button
+- `'design-mode'` - Design mode toggle
+- `'preview-mode'` - Preview mode toggle
+
+### Advanced Toolbar Configuration
+
+Use `toolbarConfig` for more control:
+
+```tsx
+import { EntryPulse, ToolbarConfig } from 'entry-pulse';
+
+const toolbarConfig: ToolbarConfig = {
+  // Custom actions
+  actions: [saveAction, publishAction],
+  
+  // Hide specific built-in actions
+  hideBuiltinActions: ['reset', 'import'],
+  
+  // Or use boolean flags
+  showUndoRedo: true,      // default: true
+  showModeToggle: true,    // default: true
+  showImportExport: false, // default: true
+  showReset: false         // default: true
+};
+
+<EntryPulse toolbarConfig={toolbarConfig} />
+```
+
+## EntryPulse Props
+
+```tsx
+interface EntryPulseProps {
+  // Initial schema to load
+  initialSchema?: FormSchema;
+  
+  // Callback when schema changes
+  onSchemaChange?: (schema: FormSchema) => void;
+  
+  // Custom toolbar actions (shorthand)
+  toolbarActions?: ToolbarAction[];
+  
+  // Full toolbar configuration
+  toolbarConfig?: ToolbarConfig;
+  
+  // Callback for form submission in preview mode
+  onPreviewSubmit?: (data: Record<string, any>) => void;
+  
+  // Show/hide element sidebar (default: true)
+  showElementSidebar?: boolean;
+  
+  // Show/hide property panel (default: true)
+  showPropertyPanel?: boolean;
+  
+  // Custom CSS class
+  className?: string;
+}
+```
+
+## Examples
+
+### Auto-save on Change
+
+```tsx
+<EntryPulse
+  onSchemaChange={(schema) => {
+    localStorage.setItem('form-draft', JSON.stringify(schema));
+  }}
+/>
+```
+
+### Load Existing Form
+
+```tsx
+const existingSchema = await fetch('/api/forms/123').then(r => r.json());
+
+<EntryPulse
+  initialSchema={existingSchema}
+  toolbarActions={[saveAction]}
+/>
+```
+
+### Minimal Interface
+
+```tsx
+<EntryPulse
+  showElementSidebar={false}
+  showPropertyPanel={false}
+  toolbarConfig={{
+    showImportExport: false,
+    showReset: false
+  }}
+/>
+```
+
+## Using Preview Components Standalone
+
+You can use the form preview components independently:
+
+```tsx
+import { FormPreview, WizardForm, FormSchema } from 'entry-pulse';
+
+// Regular form preview
+<FormPreview
+  schema={mySchema}
+  onSubmit={(data) => handleSubmit(data)}
+/>
+
+// Wizard/multi-step form preview
+<WizardForm
+  schema={myWizardSchema}
+  onSubmit={(data) => handleSubmit(data)}
+/>
+```
+
+## TypeScript Support
+
+EntryPulse is written in TypeScript and exports all types:
+
+```tsx
+import type {
+  FormSchema,
+  FormElement,
+  ElementType,
+  ToolbarAction,
+  ToolbarConfig,
+  ToolbarActionContext,
+} from 'entry-pulse';
+```
+
+## License
+See [LICENSE](LICENCE) for details.