@msbci/form-editor 1.2.0 → 1.3.0

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode, ComponentType } from 'react';
-import { IFormDefinition, IFormPage, IFormRoster, IFormVariable, IFormType, IDataSourceConnector, IConditionRule, IRosterVariableRef } from '@msbci/form-core';
+import { IFormDefinition, IFormPage, IFormRoster, IFormVariable, IVariableTemplate, IVariableTemplateOverrides, IFormType, IDataSourceConnector, IConditionRule, IRosterVariableRef } from '@msbci/form-core';
 export { IDataSourceConnector, IFormDefinition, IFormPage, IFormRoster, IFormVariable, IMosobiThemeBase } from '@msbci/form-core';
 import * as zustand from 'zustand';
 
@@ -40,6 +40,12 @@ interface IEditorAdapter {
     saveForm?: (form: IFormDefinition) => Promise<void>;
     loadFormTypes?: () => Promise<IFormType[]>;
     saveFormType?: (type: IFormType) => Promise<void>;
+    /**
+     * Optional — fetch the variable templates of a scope.
+     * When absent, the editor's "Variables" toolbox tab stays empty and
+     * shows the {@link IEditorLabels.toolbox.noTemplates} message.
+     */
+    loadTemplates?: (scopeId: string) => Promise<IVariableTemplate[]>;
 }
 /** Complete editor state */
 interface EditorState {
@@ -52,6 +58,13 @@ interface EditorState {
     history: HistoryEntry[];
     historyIndex: number;
     adapter: IEditorAdapter | null;
+    /**
+     * Variable templates surfaced to the "Variables" toolbox tab. Populated
+     * via `setAvailableTemplates` (typically by `FormEditor` after
+     * `adapter.loadTemplates(form.scopeId)`). Out of the undo/redo history —
+     * this is editor-UI state, not form state.
+     */
+    availableTemplates: IVariableTemplate[];
 }
 /** Editor actions */
 interface EditorActions {
@@ -67,7 +80,33 @@ interface EditorActions {
     addVariable: (pageCode: string, variable: IFormVariable, rosterCode?: string) => void;
     updateVariable: (pageCode: string, variableCode: string, updates: Partial<IFormVariable>, rosterCode?: string) => void;
     removeVariable: (pageCode: string, variableCode: string, rosterCode?: string) => void;
+    /**
+     * Insert a variable that inherits from a `IVariableTemplate`. Template
+     * fields are denormalised onto the new variable; `code` and `name` come
+     * from the template; `templateOverrides` starts empty.
+     */
+    addVariableFromTemplate: (pageCode: string, template: IVariableTemplate, rosterCode?: string) => void;
+    /**
+     * Override a single field of a template-linked variable. Writes the new
+     * value into `templateOverrides[key]` AND mirrors it on the variable so
+     * the canvas can render without invoking the resolver.
+     */
+    setVariableOverride: <K extends keyof IVariableTemplateOverrides>(pageCode: string, variableCode: string, key: K, value: IVariableTemplateOverrides[K], rosterCode?: string) => void;
+    /**
+     * Drop one override key — removes it from `templateOverrides` and
+     * restores the variable's mirrored field from the linked template.
+     */
+    resetVariableOverride: (pageCode: string, variableCode: string, key: keyof IVariableTemplateOverrides, rosterCode?: string) => void;
+    /**
+     * Cross-page / cross-roster move (kept for the existing dnd flow). Use
+     * {@link moveItem} for intra-page reordering of `page.items[]`.
+     */
     moveVariable: (fromPageCode: string, toPageCode: string, variableCode: string, newOrder: number, fromRosterCode?: string, toRosterCode?: string) => void;
+    /**
+     * Reorder the items of a page (variables + rosters mixed) by index.
+     * Updates each item's `order` to its new position.
+     */
+    moveItem: (pageCode: string, fromIndex: number, toIndex: number) => void;
     select: (selection: EditorSelection) => void;
     clearSelection: () => void;
     setView: (view: EditorView) => void;
@@ -78,6 +117,8 @@ interface EditorActions {
     addFormType: (type: Omit<IFormType, 'id'>) => void;
     updateFormType: (id: string, patch: Partial<IFormType>) => void;
     removeFormType: (id: string) => void;
+    /** Replace the variable-template list shown in the Variables tab. */
+    setAvailableTemplates: (templates: IVariableTemplate[]) => void;
     setAdapter: (adapter: IEditorAdapter) => void;
     save: () => Promise<void>;
     load: (formId: string) => Promise<void>;
@@ -120,11 +161,26 @@ interface IEditorLabels {
     toolbox: {
         searchPlaceholder: string;
         addPageFirst: string;
+        /** Label of the first tab (existing variable/roster types). */
+        tabFields: string;
+        /** Label of the second tab (variable library from current scope). */
+        tabVariables: string;
+        /** Empty state for the Variables tab when the form has a scope but no templates. */
+        noTemplates: string;
+        /** Empty state for the Variables tab when the form has no scope at all. */
+        noScope: string;
         groupText: string;
         groupSelection: string;
         groupDateTime: string;
         groupMedia: string;
         groupAdvanced: string;
+        /** Section label for the four roster variants, displayed after ADVANCED. */
+        groupRoster: string;
+        /** Roster type labels — surface the four supported variants. */
+        typeRosterCheck: string;
+        typeRosterList: string;
+        typeRosterCollection: string;
+        typeRosterCollectionExtend: string;
         /**
          * Shared variable-type labels. Re-used by both Toolbox(Simple) and
          * VariableProperties (single source of truth).
@@ -211,6 +267,14 @@ interface IEditorLabels {
             collection: string;
             collection_extend: string;
         };
+        /** Banner title shown on top of VariableProperties when the variable links to a template. */
+        linkedTemplate: string;
+        /** Label for the read-only code field on a linked variable. */
+        templateCode: string;
+        /** Label for the read-only name field on a linked variable. */
+        templateName: string;
+        /** Per-override reset button label. */
+        resetOverride: string;
         type: string;
         ratingStyle: string;
         ratingStyles: {
@@ -400,14 +464,19 @@ interface EditorToolbarProps {
 declare function EditorToolbar({ onSave, onExport, onImport }: EditorToolbarProps): react_jsx_runtime.JSX.Element;
 
 /**
- * Toolbox — left panel. Click to add variables to selected page.
- * No drag & drop dependency.
+ * Toolbox — left panel. Two tabs:
+ *   - Champs    : variable types + roster variants (original content).
+ *   - Variables : reusable templates from the current scope.
+ *
+ * Click to add. No drag & drop dependency (see Toolbox.tsx for DnD).
  */
 declare function ToolboxSimple(): react_jsx_runtime.JSX.Element;
 
 /**
  * Canvas — center panel. Displays form structure.
- * Click to select. Supports roster creation and variable management.
+ * Click to select. Variables and rosters share a single ordered list
+ * (`page.items[]`) and are rendered together; rosters always break the
+ * current multi-column row and span the full width.
  */
 declare function CanvasSimple(): react_jsx_runtime.JSX.Element;
 

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode, ComponentType } from 'react';
-import { IFormDefinition, IFormPage, IFormRoster, IFormVariable, IFormType, IDataSourceConnector, IConditionRule, IRosterVariableRef } from '@msbci/form-core';
+import { IFormDefinition, IFormPage, IFormRoster, IFormVariable, IVariableTemplate, IVariableTemplateOverrides, IFormType, IDataSourceConnector, IConditionRule, IRosterVariableRef } from '@msbci/form-core';
 export { IDataSourceConnector, IFormDefinition, IFormPage, IFormRoster, IFormVariable, IMosobiThemeBase } from '@msbci/form-core';
 import * as zustand from 'zustand';
 
@@ -40,6 +40,12 @@ interface IEditorAdapter {
     saveForm?: (form: IFormDefinition) => Promise<void>;
     loadFormTypes?: () => Promise<IFormType[]>;
     saveFormType?: (type: IFormType) => Promise<void>;
+    /**
+     * Optional — fetch the variable templates of a scope.
+     * When absent, the editor's "Variables" toolbox tab stays empty and
+     * shows the {@link IEditorLabels.toolbox.noTemplates} message.
+     */
+    loadTemplates?: (scopeId: string) => Promise<IVariableTemplate[]>;
 }
 /** Complete editor state */
 interface EditorState {
@@ -52,6 +58,13 @@ interface EditorState {
     history: HistoryEntry[];
     historyIndex: number;
     adapter: IEditorAdapter | null;
+    /**
+     * Variable templates surfaced to the "Variables" toolbox tab. Populated
+     * via `setAvailableTemplates` (typically by `FormEditor` after
+     * `adapter.loadTemplates(form.scopeId)`). Out of the undo/redo history —
+     * this is editor-UI state, not form state.
+     */
+    availableTemplates: IVariableTemplate[];
 }
 /** Editor actions */
 interface EditorActions {
@@ -67,7 +80,33 @@ interface EditorActions {
     addVariable: (pageCode: string, variable: IFormVariable, rosterCode?: string) => void;
     updateVariable: (pageCode: string, variableCode: string, updates: Partial<IFormVariable>, rosterCode?: string) => void;
     removeVariable: (pageCode: string, variableCode: string, rosterCode?: string) => void;
+    /**
+     * Insert a variable that inherits from a `IVariableTemplate`. Template
+     * fields are denormalised onto the new variable; `code` and `name` come
+     * from the template; `templateOverrides` starts empty.
+     */
+    addVariableFromTemplate: (pageCode: string, template: IVariableTemplate, rosterCode?: string) => void;
+    /**
+     * Override a single field of a template-linked variable. Writes the new
+     * value into `templateOverrides[key]` AND mirrors it on the variable so
+     * the canvas can render without invoking the resolver.
+     */
+    setVariableOverride: <K extends keyof IVariableTemplateOverrides>(pageCode: string, variableCode: string, key: K, value: IVariableTemplateOverrides[K], rosterCode?: string) => void;
+    /**
+     * Drop one override key — removes it from `templateOverrides` and
+     * restores the variable's mirrored field from the linked template.
+     */
+    resetVariableOverride: (pageCode: string, variableCode: string, key: keyof IVariableTemplateOverrides, rosterCode?: string) => void;
+    /**
+     * Cross-page / cross-roster move (kept for the existing dnd flow). Use
+     * {@link moveItem} for intra-page reordering of `page.items[]`.
+     */
     moveVariable: (fromPageCode: string, toPageCode: string, variableCode: string, newOrder: number, fromRosterCode?: string, toRosterCode?: string) => void;
+    /**
+     * Reorder the items of a page (variables + rosters mixed) by index.
+     * Updates each item's `order` to its new position.
+     */
+    moveItem: (pageCode: string, fromIndex: number, toIndex: number) => void;
     select: (selection: EditorSelection) => void;
     clearSelection: () => void;
     setView: (view: EditorView) => void;
@@ -78,6 +117,8 @@ interface EditorActions {
     addFormType: (type: Omit<IFormType, 'id'>) => void;
     updateFormType: (id: string, patch: Partial<IFormType>) => void;
     removeFormType: (id: string) => void;
+    /** Replace the variable-template list shown in the Variables tab. */
+    setAvailableTemplates: (templates: IVariableTemplate[]) => void;
     setAdapter: (adapter: IEditorAdapter) => void;
     save: () => Promise<void>;
     load: (formId: string) => Promise<void>;
@@ -120,11 +161,26 @@ interface IEditorLabels {
     toolbox: {
         searchPlaceholder: string;
         addPageFirst: string;
+        /** Label of the first tab (existing variable/roster types). */
+        tabFields: string;
+        /** Label of the second tab (variable library from current scope). */
+        tabVariables: string;
+        /** Empty state for the Variables tab when the form has a scope but no templates. */
+        noTemplates: string;
+        /** Empty state for the Variables tab when the form has no scope at all. */
+        noScope: string;
         groupText: string;
         groupSelection: string;
         groupDateTime: string;
         groupMedia: string;
         groupAdvanced: string;
+        /** Section label for the four roster variants, displayed after ADVANCED. */
+        groupRoster: string;
+        /** Roster type labels — surface the four supported variants. */
+        typeRosterCheck: string;
+        typeRosterList: string;
+        typeRosterCollection: string;
+        typeRosterCollectionExtend: string;
         /**
          * Shared variable-type labels. Re-used by both Toolbox(Simple) and
          * VariableProperties (single source of truth).
@@ -211,6 +267,14 @@ interface IEditorLabels {
             collection: string;
             collection_extend: string;
         };
+        /** Banner title shown on top of VariableProperties when the variable links to a template. */
+        linkedTemplate: string;
+        /** Label for the read-only code field on a linked variable. */
+        templateCode: string;
+        /** Label for the read-only name field on a linked variable. */
+        templateName: string;
+        /** Per-override reset button label. */
+        resetOverride: string;
         type: string;
         ratingStyle: string;
         ratingStyles: {
@@ -400,14 +464,19 @@ interface EditorToolbarProps {
 declare function EditorToolbar({ onSave, onExport, onImport }: EditorToolbarProps): react_jsx_runtime.JSX.Element;
 
 /**
- * Toolbox — left panel. Click to add variables to selected page.
- * No drag & drop dependency.
+ * Toolbox — left panel. Two tabs:
+ *   - Champs    : variable types + roster variants (original content).
+ *   - Variables : reusable templates from the current scope.
+ *
+ * Click to add. No drag & drop dependency (see Toolbox.tsx for DnD).
  */
 declare function ToolboxSimple(): react_jsx_runtime.JSX.Element;
 
 /**
  * Canvas — center panel. Displays form structure.
- * Click to select. Supports roster creation and variable management.
+ * Click to select. Variables and rosters share a single ordered list
+ * (`page.items[]`) and are rendered together; rosters always break the
+ * current multi-column row and span the full width.
  */
 declare function CanvasSimple(): react_jsx_runtime.JSX.Element;