@msbci/form-editor 1.3.0 → 1.3.1

package/dist/index.d.mts

@@ -1,8 +1,9 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { ReactNode, ComponentType } from 'react';
-import { IFormDefinition, IFormPage, IFormRoster, IFormVariable, IVariableTemplate, IVariableTemplateOverrides, IFormType, IDataSourceConnector, IConditionRule, IRosterVariableRef } from '@msbci/form-core';
+import React, { ReactNode, ComponentType } from 'react';
+import { IFormDefinition, IFormPage, IFormRoster, IFormVariable, IVariableTemplate, IVariableTemplateOverrides, IFormType, IDataSourceConnector, VariableType, RosterType, IConditionRule, IRosterVariableRef } from '@msbci/form-core';
 export { IDataSourceConnector, IFormDefinition, IFormPage, IFormRoster, IFormVariable, IMosobiThemeBase } from '@msbci/form-core';
 import * as zustand from 'zustand';
+import { DragEndEvent } from '@dnd-kit/core';
 
 /**
  * Editor store types.
@@ -442,11 +443,25 @@ interface FormEditorProps {
         dataSources?: Record<string, IDataSourceConnector>;
         mode?: string;
     }>;
-    /** Custom Toolbox component (e.g. with drag & drop) */
+    /**
+     * Override the default DnD-enabled Toolbox. Most consumers should leave
+     * this undefined and rely on the default `Toolbox` component, which
+     * already supports drag & drop and the click-to-add flow.
+     */
     ToolboxComponent?: ComponentType<any>;
-    /** Custom Canvas component (e.g. with sortable drag & drop) */
+    /**
+     * Override the default DnD-enabled Canvas. Most consumers should leave
+     * this undefined; the default `Canvas` component handles reordering and
+     * cross-container drops automatically.
+     */
     CanvasComponent?: ComponentType<any>;
-    /** Wrapper around the entire editor (e.g. DndContext) */
+    /**
+     * @deprecated Drag & drop is now provided by `DndManager` internally.
+     * If you still pass a `Wrapper`, it is applied AROUND the internal
+     * `<DndManager>` so your wrapper keeps running, but you no longer need
+     * to mount your own `<DndContext>`. A one-time console warning is
+     * emitted to make the deprecation visible.
+     */
     Wrapper?: ComponentType<any>;
 }
 declare function FormEditor({ theme, dataSources, adapter, initialForm, formId, onChange, onSave, labels, PreviewComponent, ToolboxComponent, CanvasComponent, Wrapper, }: FormEditorProps): react_jsx_runtime.JSX.Element;
@@ -463,6 +478,67 @@ interface EditorToolbarProps {
 }
 declare function EditorToolbar({ onSave, onExport, onImport }: EditorToolbarProps): react_jsx_runtime.JSX.Element;
 
+/**
+ * Toolbox panel (DnD) — left side of the editor.
+ * Two tabs:
+ *   - Champs    : variable types + roster variants (draggable).
+ *   - Variables : reusable templates from the current scope (draggable
+ *                 with data.type='new-variable-from-template').
+ */
+declare function Toolbox(): react_jsx_runtime.JSX.Element;
+
+/**
+ * Canvas panel — center of the editor.
+ * Displays the form structure as pages with a unified list of items
+ * (variables + rosters). Items share a single SortableContext so the
+ * drag & drop reordering works across both kinds.
+ */
+declare function Canvas(): react_jsx_runtime.JSX.Element;
+
+/**
+ * Subset of the editor store the drag-end logic actually needs. Decoupling
+ * makes the handler trivially mockable in unit tests.
+ */
+interface DragEndActions {
+    addVariable: (pageCode: string, variable: IFormVariable, rosterCode?: string) => void;
+    addRoster: (pageCode: string, roster: IFormRoster) => void;
+    addVariableFromTemplate: (pageCode: string, template: IVariableTemplate, rosterCode?: string) => void;
+    moveItem: (pageCode: string, fromIndex: number, toIndex: number) => void;
+    moveVariable: (fromPageCode: string, toPageCode: string, variableCode: string, newOrder: number, fromRosterCode?: string, toRosterCode?: string) => void;
+    reorderPages: (orderedCodes: string[]) => void;
+}
+/** Active draggable payload — what Canvas / Toolbox put under `data.current`. */
+interface ActiveDragData {
+    type?: 'new-variable' | 'new-roster' | 'new-variable-from-template' | 'variable' | 'roster' | 'page';
+    variableType?: VariableType;
+    rosterType?: RosterType;
+    template?: IVariableTemplate;
+    pageCode?: string;
+    variableCode?: string;
+    rosterCode?: string;
+}
+/** Over (drop-target) payload. */
+interface OverDropData {
+    type?: 'page' | 'variable' | 'roster' | 'roster-drop';
+    pageCode?: string;
+    rosterCode?: string;
+}
+/**
+ * Build a pure drag-end handler. Given a snapshot accessor for the form
+ * and the store actions, returns a function that translates a DragEndEvent
+ * into the right action call. Exported for unit tests.
+ */
+declare function createDragEndHandler(actions: DragEndActions, getForm: () => IFormDefinition): (event: DragEndEvent) => void;
+/**
+ * Wraps the editor tree in a `<DndContext>` configured with pointer +
+ * keyboard sensors and the drag-end handler returned by
+ * {@link createDragEndHandler}. A `<DragOverlay>` shows a label while
+ * something is being dragged.
+ */
+declare function DndManager({ children }: {
+    children: React.ReactNode;
+}): react_jsx_runtime.JSX.Element;
+
 /**
  * Toolbox — left panel. Two tabs:
  *   - Champs    : variable types + roster variants (original content).
@@ -528,4 +604,4 @@ interface DataSourceSelectorProps {
 }
 declare function DataSourceSelector({ dataSourceId, dependencies, availableConnectors, availableVariables, onConnectorChange, onDependenciesChange, }: DataSourceSelectorProps): react_jsx_runtime.JSX.Element;
 
-export { CanvasSimple as Canvas, ConditionBuilder, type ConditionBuilderProps, DataSourceSelector, type DataSourceSelectorProps, type DeepPartial, type EditorActions, EditorLabelsProvider, type EditorSelection, type EditorState, type EditorStore, EditorToolbar, type EditorView, FormEditor, type FormEditorProps, type HistoryEntry, type IEditorAdapter, type IEditorLabels, PropertiesPanel, ToolboxSimple as Toolbox, frLabels as defaultLabels, enLabels, frLabels, mergeLabels, useEditorStore, useLabels };
+export { type ActiveDragData, Canvas, Canvas as CanvasDnd, CanvasSimple, ConditionBuilder, type ConditionBuilderProps, DataSourceSelector, type DataSourceSelectorProps, type DeepPartial, DndManager, type DragEndActions, type EditorActions, EditorLabelsProvider, type EditorSelection, type EditorState, type EditorStore, EditorToolbar, type EditorView, FormEditor, type FormEditorProps, type HistoryEntry, type IEditorAdapter, type IEditorLabels, type OverDropData, PropertiesPanel, Toolbox, Toolbox as ToolboxDnd, ToolboxSimple, createDragEndHandler, frLabels as defaultLabels, enLabels, frLabels, mergeLabels, useEditorStore, useLabels };

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { ReactNode, ComponentType } from 'react';
-import { IFormDefinition, IFormPage, IFormRoster, IFormVariable, IVariableTemplate, IVariableTemplateOverrides, IFormType, IDataSourceConnector, IConditionRule, IRosterVariableRef } from '@msbci/form-core';
+import React, { ReactNode, ComponentType } from 'react';
+import { IFormDefinition, IFormPage, IFormRoster, IFormVariable, IVariableTemplate, IVariableTemplateOverrides, IFormType, IDataSourceConnector, VariableType, RosterType, IConditionRule, IRosterVariableRef } from '@msbci/form-core';
 export { IDataSourceConnector, IFormDefinition, IFormPage, IFormRoster, IFormVariable, IMosobiThemeBase } from '@msbci/form-core';
 import * as zustand from 'zustand';
+import { DragEndEvent } from '@dnd-kit/core';
 
 /**
  * Editor store types.
@@ -442,11 +443,25 @@ interface FormEditorProps {
         dataSources?: Record<string, IDataSourceConnector>;
         mode?: string;
     }>;
-    /** Custom Toolbox component (e.g. with drag & drop) */
+    /**
+     * Override the default DnD-enabled Toolbox. Most consumers should leave
+     * this undefined and rely on the default `Toolbox` component, which
+     * already supports drag & drop and the click-to-add flow.
+     */
     ToolboxComponent?: ComponentType<any>;
-    /** Custom Canvas component (e.g. with sortable drag & drop) */
+    /**
+     * Override the default DnD-enabled Canvas. Most consumers should leave
+     * this undefined; the default `Canvas` component handles reordering and
+     * cross-container drops automatically.
+     */
     CanvasComponent?: ComponentType<any>;
-    /** Wrapper around the entire editor (e.g. DndContext) */
+    /**
+     * @deprecated Drag & drop is now provided by `DndManager` internally.
+     * If you still pass a `Wrapper`, it is applied AROUND the internal
+     * `<DndManager>` so your wrapper keeps running, but you no longer need
+     * to mount your own `<DndContext>`. A one-time console warning is
+     * emitted to make the deprecation visible.
+     */
     Wrapper?: ComponentType<any>;
 }
 declare function FormEditor({ theme, dataSources, adapter, initialForm, formId, onChange, onSave, labels, PreviewComponent, ToolboxComponent, CanvasComponent, Wrapper, }: FormEditorProps): react_jsx_runtime.JSX.Element;
@@ -463,6 +478,67 @@ interface EditorToolbarProps {
 }
 declare function EditorToolbar({ onSave, onExport, onImport }: EditorToolbarProps): react_jsx_runtime.JSX.Element;
 
+/**
+ * Toolbox panel (DnD) — left side of the editor.
+ * Two tabs:
+ *   - Champs    : variable types + roster variants (draggable).
+ *   - Variables : reusable templates from the current scope (draggable
+ *                 with data.type='new-variable-from-template').
+ */
+declare function Toolbox(): react_jsx_runtime.JSX.Element;
+
+/**
+ * Canvas panel — center of the editor.
+ * Displays the form structure as pages with a unified list of items
+ * (variables + rosters). Items share a single SortableContext so the
+ * drag & drop reordering works across both kinds.
+ */
+declare function Canvas(): react_jsx_runtime.JSX.Element;
+
+/**
+ * Subset of the editor store the drag-end logic actually needs. Decoupling
+ * makes the handler trivially mockable in unit tests.
+ */
+interface DragEndActions {
+    addVariable: (pageCode: string, variable: IFormVariable, rosterCode?: string) => void;
+    addRoster: (pageCode: string, roster: IFormRoster) => void;
+    addVariableFromTemplate: (pageCode: string, template: IVariableTemplate, rosterCode?: string) => void;
+    moveItem: (pageCode: string, fromIndex: number, toIndex: number) => void;
+    moveVariable: (fromPageCode: string, toPageCode: string, variableCode: string, newOrder: number, fromRosterCode?: string, toRosterCode?: string) => void;
+    reorderPages: (orderedCodes: string[]) => void;
+}
+/** Active draggable payload — what Canvas / Toolbox put under `data.current`. */
+interface ActiveDragData {
+    type?: 'new-variable' | 'new-roster' | 'new-variable-from-template' | 'variable' | 'roster' | 'page';
+    variableType?: VariableType;
+    rosterType?: RosterType;
+    template?: IVariableTemplate;
+    pageCode?: string;
+    variableCode?: string;
+    rosterCode?: string;
+}
+/** Over (drop-target) payload. */
+interface OverDropData {
+    type?: 'page' | 'variable' | 'roster' | 'roster-drop';
+    pageCode?: string;
+    rosterCode?: string;
+}
+/**
+ * Build a pure drag-end handler. Given a snapshot accessor for the form
+ * and the store actions, returns a function that translates a DragEndEvent
+ * into the right action call. Exported for unit tests.
+ */
+declare function createDragEndHandler(actions: DragEndActions, getForm: () => IFormDefinition): (event: DragEndEvent) => void;
+/**
+ * Wraps the editor tree in a `<DndContext>` configured with pointer +
+ * keyboard sensors and the drag-end handler returned by
+ * {@link createDragEndHandler}. A `<DragOverlay>` shows a label while
+ * something is being dragged.
+ */
+declare function DndManager({ children }: {
+    children: React.ReactNode;
+}): react_jsx_runtime.JSX.Element;
+
 /**
  * Toolbox — left panel. Two tabs:
  *   - Champs    : variable types + roster variants (original content).
@@ -528,4 +604,4 @@ interface DataSourceSelectorProps {
 }
 declare function DataSourceSelector({ dataSourceId, dependencies, availableConnectors, availableVariables, onConnectorChange, onDependenciesChange, }: DataSourceSelectorProps): react_jsx_runtime.JSX.Element;
 
-export { CanvasSimple as Canvas, ConditionBuilder, type ConditionBuilderProps, DataSourceSelector, type DataSourceSelectorProps, type DeepPartial, type EditorActions, EditorLabelsProvider, type EditorSelection, type EditorState, type EditorStore, EditorToolbar, type EditorView, FormEditor, type FormEditorProps, type HistoryEntry, type IEditorAdapter, type IEditorLabels, PropertiesPanel, ToolboxSimple as Toolbox, frLabels as defaultLabels, enLabels, frLabels, mergeLabels, useEditorStore, useLabels };
+export { type ActiveDragData, Canvas, Canvas as CanvasDnd, CanvasSimple, ConditionBuilder, type ConditionBuilderProps, DataSourceSelector, type DataSourceSelectorProps, type DeepPartial, DndManager, type DragEndActions, type EditorActions, EditorLabelsProvider, type EditorSelection, type EditorState, type EditorStore, EditorToolbar, type EditorView, FormEditor, type FormEditorProps, type HistoryEntry, type IEditorAdapter, type IEditorLabels, type OverDropData, PropertiesPanel, Toolbox, Toolbox as ToolboxDnd, ToolboxSimple, createDragEndHandler, frLabels as defaultLabels, enLabels, frLabels, mergeLabels, useEditorStore, useLabels };