form-page-builder 2.0.0 → 2.2.0

package/dist/index.d.cts

@@ -103,16 +103,33 @@ declare const CHROME: {
         formJson: string;
         copy: string;
         copied: string;
+        copyTemplate: string;
+        pasteTemplate: string;
+        copyTemplateTitle: string;
+        pasteTemplateTitle: string;
+        pasteTemplateConfirm: string;
         noTemplates: string;
+        noTemplatesReadonly: string;
         updated: string;
         open: string;
+        applyTemplate: string;
         saveForm: string;
         formName: string;
         saveToLibrary: string;
         loadingDraft: string;
-        templatesLimitReached: string;
+        templatesLimitReached: (max: number) => string;
+        templatesLimitTitle: string;
+        confirm: string;
+        cancel: string;
+        dismiss: string;
+        confirmReplace: string;
         current: string;
         customColor: string;
+        templateLabel: (name: string) => string;
+        templateEdited: string;
+        templateLoading: string;
+        templateLoadFailed: string;
+        templateSaveFailed: string;
         fieldsCount: (n: number) => string;
         fieldTypeInput: string;
         fieldTypeTextarea: string;
@@ -239,16 +256,33 @@ declare const CHROME: {
         formJson: string;
         copy: string;
         copied: string;
+        copyTemplate: string;
+        pasteTemplate: string;
+        copyTemplateTitle: string;
+        pasteTemplateTitle: string;
+        pasteTemplateConfirm: string;
         noTemplates: string;
+        noTemplatesReadonly: string;
         updated: string;
         open: string;
+        applyTemplate: string;
         saveForm: string;
         formName: string;
         saveToLibrary: string;
         loadingDraft: string;
-        templatesLimitReached: string;
+        templatesLimitReached: (max: number) => string;
+        templatesLimitTitle: string;
+        confirm: string;
+        cancel: string;
+        dismiss: string;
+        confirmReplace: string;
         current: string;
         customColor: string;
+        templateLabel: (name: string) => string;
+        templateEdited: string;
+        templateLoading: string;
+        templateLoadFailed: string;
+        templateSaveFailed: string;
         fieldsCount: (n: number) => string;
         fieldTypeInput: string;
         fieldTypeTextarea: string;
@@ -564,12 +598,37 @@ interface FormBuilderHandle {
     loadDocument(doc: FormDocument): void;
     /** Convenience for `JSON.stringify(getDocument())`. */
     exportJson(): string;
+    /** The current document as a portable `FormTemplate` — pass to another builder's `loadTemplate()` or persist it. */
+    getTemplate(): FormTemplate;
+    /** Loads a `FormTemplate` (or its JSON, or bare document JSON); `false` if it can't be parsed. */
+    loadTemplate(input: FormTemplate | string): boolean;
+}
+/** Self-describing `FormDocument` wrapper; the `__fpb` tag marks it as ours. See `serializeTemplate` / `parseTemplate`. */
+interface FormTemplate {
+    __fpb: "template";
+    v: number;
+    document: FormDocument;
+}
+interface TemplateChange {
+    /** Affected template's id; `null` when the active template was just deleted. */
+    id: string | null;
+    title: string;
+    /** `new` = created, `saved` = overwritten, `applied` = loaded as the working doc, `deleted`. */
+    source: "new" | "saved" | "applied" | "deleted";
 }
 interface FormBuilderFeatures {
     /** Editable form title input in the Toolbar. Default true. */
     naming?: boolean;
-    /** Templates library (browse/open/delete) + "Save" button. Default true. */
-    templates?: boolean;
+    /**
+     * Templates library. `true` (default) = full CRUD + toolbar "Save"; `false` = hidden.
+     * `{ manage: false }` = pick-and-apply only (no save/overwrite/delete). `{ max }` caps the count (default 5).
+     */
+    templates?: boolean | {
+        manage?: boolean;
+        max?: number;
+    };
+    /** "Copy template" / "Paste template" icons by "View JSON"; paste enables once another instance copies. Default true. */
+    templateClipboard?: boolean;
     /** "New Form" reset button. Default true. */
     newForm?: boolean;
     /** Autosave the draft to `storage`. The initial draft load always happens; this only gates the write path. Default true. */
@@ -588,10 +647,16 @@ interface FormBuilderFeatures {
     contentBlocks?: boolean | ContentBlockType[];
     /** Which form field types can be added from the palette. `true` = all, `false` = none, or an allowlist array. Default true. */
     fieldTypes?: boolean | InputFieldType[];
-    /** Add/duplicate/move/delete section controls + section background picker. Default true. */
+    /** Add/duplicate/move/delete section controls + the "Add section" button. Default true. */
     sections?: boolean;
+    /** Per-section background-color picker. Independent of `sections`; unset → follows `sections`, else true. */
+    sectionBackground?: boolean;
     /** Drag-to-reorder fields within a section. Default true. */
     dragReorder?: boolean;
+    /** Laptop/Tablet/Mobile width switcher above the Preview canvas. Default true. */
+    deviceToggle?: boolean;
+    /** Caps the number of input-type fields (not content blocks) addable across the whole document. Default undefined (unlimited). */
+    maxFields?: number;
 }
 interface FormBuilderProps {
     theme?: Partial<Theme>;
@@ -605,21 +670,22 @@ interface FormBuilderProps {
     onSubmit?: (payload: SubmitPayload) => void;
     /** Seeds the builder with this document on mount instead of the autosaved draft — e.g. a template fetched from your own backend. */
     initialDocument?: FormDocument;
+    /** Which mode the widget mounts into. Default "build". Pair with `features.previewMode: false` to lock a consumer to just one mode with no tabs. */
+    initialMode?: "build" | "preview";
+    /** Fires on mount and on every Build/Preview toggle — lets a host mirror the current mode without its own tab UI. */
+    onModeChange?: (mode: "build" | "preview") => void;
+    /** Fires on template create/overwrite/apply/delete — for syncing a host's own state/backend. */
+    onTemplateChange?: (change: TemplateChange) => void;
+    /** localStorage key behind copy/paste (default `"form-page-builder:clipboard"`); instances sharing it can paste to each other. */
+    templateClipboardKey?: string;
 }
 
 declare const FormBuilder: react.ForwardRefExoticComponent<FormBuilderProps & react.RefAttributes<FormBuilderHandle>>;
 
 /**
- * Default StorageAdapter, backed by window.localStorage. Availability is
- * checked inside each method (not once at module load) so the same module
- * behaves correctly whether it runs during SSR (no window) or later on the
- * client, within the same process.
- *
- * Values are compressed before writing (drafts/templates are JSON with a lot
- * of repeated keys, which compresses well) to reduce how much of the quota
- * they use. On read, a decompressed result is only trusted if it's valid
- * JSON — anything else falls back to the raw stored string, so drafts
- * written before compression was added keep loading correctly.
+ * Default StorageAdapter over window.localStorage. Availability is checked per-call so it survives SSR.
+ * Values are compressed on write; on read, a decompressed result is used only if it parses as JSON,
+ * else the raw string is returned (so pre-compression drafts still load).
  */
 declare const localStorageAdapter: StorageAdapter;
 
@@ -628,4 +694,16 @@ declare const DEFAULT_THEME: Theme;
 /** A ready-made dark palette — pass as the `theme` prop for a dark-mode `<FormBuilder />`. */
 declare const DARK_THEME: Theme;
 
-export { type CheckboxField, type CheckboxGroupField, type ChromeShape, type ContentBlockType, DARK_THEME, DEFAULT_THEME, type DocumentFields, type FieldPatch, type FieldType, FormBuilder, type FormBuilderFeatures, type FormBuilderHandle, type FormBuilderProps, type FormDocument, type FormField, type ImageField, type InputField, type InputFieldType, type LanguageOption, type LocalizedString, type Option, type ParagraphField, type RadioField, type SavedFormMeta, type Section, type SelectField, type StorageAdapter, type StringsShape, type SubmitPayload, type SubmitStyle, type TextareaField, type Theme, type ThemeLayout, type ThemeOverrides, type ToggleField, FormBuilder as default, localStorageAdapter };
+declare function serializeTemplate(document: FormDocument): string;
+/** Accepts a `serializeTemplate` envelope or a bare document (e.g. "View JSON" output); `null` if not a document. */
+declare function parseTemplate(raw: string | null | undefined): DocumentFields | null;
+
+declare const DRAFT_KEY = "form-page-builder:draft";
+declare const INDEX_KEY = "form-page-builder:index";
+declare const formKey: (id: string) => string;
+/** Template id from a `formKey` result, else null — lets a StorageAdapter route per-template keys. */
+declare const savedFormId: (key: string) => string | null;
+/** Copy/paste-template scratch slot — always localStorage, never the StorageAdapter. */
+declare const CLIPBOARD_KEY = "form-page-builder:clipboard";
+
+export { CLIPBOARD_KEY, type CheckboxField, type CheckboxGroupField, type ChromeShape, type ContentBlockType, DARK_THEME, DEFAULT_THEME, DRAFT_KEY, type DocumentFields, type FieldPatch, type FieldType, FormBuilder, type FormBuilderFeatures, type FormBuilderHandle, type FormBuilderProps, type FormDocument, type FormField, type FormTemplate, INDEX_KEY, type ImageField, type InputField, type InputFieldType, type LanguageOption, type LocalizedString, type Option, type ParagraphField, type RadioField, type SavedFormMeta, type Section, type SelectField, type StorageAdapter, type StringsShape, type SubmitPayload, type SubmitStyle, type TemplateChange, type TextareaField, type Theme, type ThemeLayout, type ThemeOverrides, type ToggleField, FormBuilder as default, formKey, localStorageAdapter, parseTemplate, savedFormId, serializeTemplate };

package/dist/index.d.ts

@@ -103,16 +103,33 @@ declare const CHROME: {
         formJson: string;
         copy: string;
         copied: string;
+        copyTemplate: string;
+        pasteTemplate: string;
+        copyTemplateTitle: string;
+        pasteTemplateTitle: string;
+        pasteTemplateConfirm: string;
         noTemplates: string;
+        noTemplatesReadonly: string;
         updated: string;
         open: string;
+        applyTemplate: string;
         saveForm: string;
         formName: string;
         saveToLibrary: string;
         loadingDraft: string;
-        templatesLimitReached: string;
+        templatesLimitReached: (max: number) => string;
+        templatesLimitTitle: string;
+        confirm: string;
+        cancel: string;
+        dismiss: string;
+        confirmReplace: string;
         current: string;
         customColor: string;
+        templateLabel: (name: string) => string;
+        templateEdited: string;
+        templateLoading: string;
+        templateLoadFailed: string;
+        templateSaveFailed: string;
         fieldsCount: (n: number) => string;
         fieldTypeInput: string;
         fieldTypeTextarea: string;
@@ -239,16 +256,33 @@ declare const CHROME: {
         formJson: string;
         copy: string;
         copied: string;
+        copyTemplate: string;
+        pasteTemplate: string;
+        copyTemplateTitle: string;
+        pasteTemplateTitle: string;
+        pasteTemplateConfirm: string;
         noTemplates: string;
+        noTemplatesReadonly: string;
         updated: string;
         open: string;
+        applyTemplate: string;
         saveForm: string;
         formName: string;
         saveToLibrary: string;
         loadingDraft: string;
-        templatesLimitReached: string;
+        templatesLimitReached: (max: number) => string;
+        templatesLimitTitle: string;
+        confirm: string;
+        cancel: string;
+        dismiss: string;
+        confirmReplace: string;
         current: string;
         customColor: string;
+        templateLabel: (name: string) => string;
+        templateEdited: string;
+        templateLoading: string;
+        templateLoadFailed: string;
+        templateSaveFailed: string;
         fieldsCount: (n: number) => string;
         fieldTypeInput: string;
         fieldTypeTextarea: string;
@@ -564,12 +598,37 @@ interface FormBuilderHandle {
     loadDocument(doc: FormDocument): void;
     /** Convenience for `JSON.stringify(getDocument())`. */
     exportJson(): string;
+    /** The current document as a portable `FormTemplate` — pass to another builder's `loadTemplate()` or persist it. */
+    getTemplate(): FormTemplate;
+    /** Loads a `FormTemplate` (or its JSON, or bare document JSON); `false` if it can't be parsed. */
+    loadTemplate(input: FormTemplate | string): boolean;
+}
+/** Self-describing `FormDocument` wrapper; the `__fpb` tag marks it as ours. See `serializeTemplate` / `parseTemplate`. */
+interface FormTemplate {
+    __fpb: "template";
+    v: number;
+    document: FormDocument;
+}
+interface TemplateChange {
+    /** Affected template's id; `null` when the active template was just deleted. */
+    id: string | null;
+    title: string;
+    /** `new` = created, `saved` = overwritten, `applied` = loaded as the working doc, `deleted`. */
+    source: "new" | "saved" | "applied" | "deleted";
 }
 interface FormBuilderFeatures {
     /** Editable form title input in the Toolbar. Default true. */
     naming?: boolean;
-    /** Templates library (browse/open/delete) + "Save" button. Default true. */
-    templates?: boolean;
+    /**
+     * Templates library. `true` (default) = full CRUD + toolbar "Save"; `false` = hidden.
+     * `{ manage: false }` = pick-and-apply only (no save/overwrite/delete). `{ max }` caps the count (default 5).
+     */
+    templates?: boolean | {
+        manage?: boolean;
+        max?: number;
+    };
+    /** "Copy template" / "Paste template" icons by "View JSON"; paste enables once another instance copies. Default true. */
+    templateClipboard?: boolean;
     /** "New Form" reset button. Default true. */
     newForm?: boolean;
     /** Autosave the draft to `storage`. The initial draft load always happens; this only gates the write path. Default true. */
@@ -588,10 +647,16 @@ interface FormBuilderFeatures {
     contentBlocks?: boolean | ContentBlockType[];
     /** Which form field types can be added from the palette. `true` = all, `false` = none, or an allowlist array. Default true. */
     fieldTypes?: boolean | InputFieldType[];
-    /** Add/duplicate/move/delete section controls + section background picker. Default true. */
+    /** Add/duplicate/move/delete section controls + the "Add section" button. Default true. */
     sections?: boolean;
+    /** Per-section background-color picker. Independent of `sections`; unset → follows `sections`, else true. */
+    sectionBackground?: boolean;
     /** Drag-to-reorder fields within a section. Default true. */
     dragReorder?: boolean;
+    /** Laptop/Tablet/Mobile width switcher above the Preview canvas. Default true. */
+    deviceToggle?: boolean;
+    /** Caps the number of input-type fields (not content blocks) addable across the whole document. Default undefined (unlimited). */
+    maxFields?: number;
 }
 interface FormBuilderProps {
     theme?: Partial<Theme>;
@@ -605,21 +670,22 @@ interface FormBuilderProps {
     onSubmit?: (payload: SubmitPayload) => void;
     /** Seeds the builder with this document on mount instead of the autosaved draft — e.g. a template fetched from your own backend. */
     initialDocument?: FormDocument;
+    /** Which mode the widget mounts into. Default "build". Pair with `features.previewMode: false` to lock a consumer to just one mode with no tabs. */
+    initialMode?: "build" | "preview";
+    /** Fires on mount and on every Build/Preview toggle — lets a host mirror the current mode without its own tab UI. */
+    onModeChange?: (mode: "build" | "preview") => void;
+    /** Fires on template create/overwrite/apply/delete — for syncing a host's own state/backend. */
+    onTemplateChange?: (change: TemplateChange) => void;
+    /** localStorage key behind copy/paste (default `"form-page-builder:clipboard"`); instances sharing it can paste to each other. */
+    templateClipboardKey?: string;
 }
 
 declare const FormBuilder: react.ForwardRefExoticComponent<FormBuilderProps & react.RefAttributes<FormBuilderHandle>>;
 
 /**
- * Default StorageAdapter, backed by window.localStorage. Availability is
- * checked inside each method (not once at module load) so the same module
- * behaves correctly whether it runs during SSR (no window) or later on the
- * client, within the same process.
- *
- * Values are compressed before writing (drafts/templates are JSON with a lot
- * of repeated keys, which compresses well) to reduce how much of the quota
- * they use. On read, a decompressed result is only trusted if it's valid
- * JSON — anything else falls back to the raw stored string, so drafts
- * written before compression was added keep loading correctly.
+ * Default StorageAdapter over window.localStorage. Availability is checked per-call so it survives SSR.
+ * Values are compressed on write; on read, a decompressed result is used only if it parses as JSON,
+ * else the raw string is returned (so pre-compression drafts still load).
  */
 declare const localStorageAdapter: StorageAdapter;
 
@@ -628,4 +694,16 @@ declare const DEFAULT_THEME: Theme;
 /** A ready-made dark palette — pass as the `theme` prop for a dark-mode `<FormBuilder />`. */
 declare const DARK_THEME: Theme;
 
-export { type CheckboxField, type CheckboxGroupField, type ChromeShape, type ContentBlockType, DARK_THEME, DEFAULT_THEME, type DocumentFields, type FieldPatch, type FieldType, FormBuilder, type FormBuilderFeatures, type FormBuilderHandle, type FormBuilderProps, type FormDocument, type FormField, type ImageField, type InputField, type InputFieldType, type LanguageOption, type LocalizedString, type Option, type ParagraphField, type RadioField, type SavedFormMeta, type Section, type SelectField, type StorageAdapter, type StringsShape, type SubmitPayload, type SubmitStyle, type TextareaField, type Theme, type ThemeLayout, type ThemeOverrides, type ToggleField, FormBuilder as default, localStorageAdapter };
+declare function serializeTemplate(document: FormDocument): string;
+/** Accepts a `serializeTemplate` envelope or a bare document (e.g. "View JSON" output); `null` if not a document. */
+declare function parseTemplate(raw: string | null | undefined): DocumentFields | null;
+
+declare const DRAFT_KEY = "form-page-builder:draft";
+declare const INDEX_KEY = "form-page-builder:index";
+declare const formKey: (id: string) => string;
+/** Template id from a `formKey` result, else null — lets a StorageAdapter route per-template keys. */
+declare const savedFormId: (key: string) => string | null;
+/** Copy/paste-template scratch slot — always localStorage, never the StorageAdapter. */
+declare const CLIPBOARD_KEY = "form-page-builder:clipboard";
+
+export { CLIPBOARD_KEY, type CheckboxField, type CheckboxGroupField, type ChromeShape, type ContentBlockType, DARK_THEME, DEFAULT_THEME, DRAFT_KEY, type DocumentFields, type FieldPatch, type FieldType, FormBuilder, type FormBuilderFeatures, type FormBuilderHandle, type FormBuilderProps, type FormDocument, type FormField, type FormTemplate, INDEX_KEY, type ImageField, type InputField, type InputFieldType, type LanguageOption, type LocalizedString, type Option, type ParagraphField, type RadioField, type SavedFormMeta, type Section, type SelectField, type StorageAdapter, type StringsShape, type SubmitPayload, type SubmitStyle, type TemplateChange, type TextareaField, type Theme, type ThemeLayout, type ThemeOverrides, type ToggleField, FormBuilder as default, formKey, localStorageAdapter, parseTemplate, savedFormId, serializeTemplate };