form-page-builder 0.1.0 → 1.0.0

package/dist/index.d.cts

@@ -28,13 +28,15 @@ declare const ICON_LIBRARY: {
 };
 type IconKey = keyof typeof ICON_LIBRARY;
 
-type FieldType = "paragraph" | "image" | "input" | "textarea" | "select" | "radio" | "checkboxGroup" | "checkbox" | "toggle";
+type FieldType = "paragraph" | "image" | "button" | "input" | "textarea" | "select" | "radio" | "checkboxGroup" | "checkbox" | "toggle";
 
 declare const CHROME: {
     en: {
         contentBlocks: string;
         formFields: string;
         addingTo: string;
+        paletteTabBlocks: string;
+        paletteTabDesign: string;
         properties: string;
         selectFieldHint: string;
         label: string;
@@ -80,14 +82,14 @@ declare const CHROME: {
         build: string;
         preview: string;
         newForm: string;
-        myForms: string;
+        templates: string;
         save: string;
         viewJson: string;
         saving: string;
         saved: string;
         saveFailed: string;
         startNewForm: string;
-        openSavedForm: string;
+        openTemplatesTitle: string;
         saveToLibraryTitle: string;
         sectionTitlePlaceholder: (n: number) => string;
         noFieldsInSection: string;
@@ -101,22 +103,17 @@ declare const CHROME: {
         formJson: string;
         copy: string;
         copied: string;
-        nothingSaved: string;
+        noTemplates: string;
         updated: string;
         open: string;
         saveForm: string;
         formName: string;
         saveToLibrary: string;
         loadingDraft: string;
+        templatesLimitReached: string;
         current: string;
         customColor: string;
         fieldsCount: (n: number) => string;
-        formSettings: string;
-        submitLabel: string;
-        submitMode: string;
-        combined: string;
-        perSection: string;
-        settings: string;
         fieldTypeInput: string;
         fieldTypeTextarea: string;
         fieldTypeSelect: string;
@@ -126,6 +123,7 @@ declare const CHROME: {
         fieldTypeToggle: string;
         fieldTypeParagraph: string;
         fieldTypeImage: string;
+        fieldTypeButton: string;
         subtypeText: string;
         subtypeEmail: string;
         subtypePhone: string;
@@ -138,8 +136,17 @@ declare const CHROME: {
         shapeBanner: string;
         tagBody: string;
         tagCaption: string;
-        submitSectionTitle: string;
-        submitStyle: string;
+        buttonText: string;
+        buttonActionTitle: string;
+        buttonAction: string;
+        actionLink: string;
+        actionSubmit: string;
+        openIn: string;
+        sameTab: string;
+        newTab: string;
+        submitScope: string;
+        thisSection: string;
+        wholeForm: string;
         buttonSize: string;
         theme: string;
         primaryColor: string;
@@ -164,6 +171,8 @@ declare const CHROME: {
         contentBlocks: string;
         formFields: string;
         addingTo: string;
+        paletteTabBlocks: string;
+        paletteTabDesign: string;
         properties: string;
         selectFieldHint: string;
         label: string;
@@ -209,14 +218,14 @@ declare const CHROME: {
         build: string;
         preview: string;
         newForm: string;
-        myForms: string;
+        templates: string;
         save: string;
         viewJson: string;
         saving: string;
         saved: string;
         saveFailed: string;
         startNewForm: string;
-        openSavedForm: string;
+        openTemplatesTitle: string;
         saveToLibraryTitle: string;
         sectionTitlePlaceholder: (n: number) => string;
         noFieldsInSection: string;
@@ -230,22 +239,17 @@ declare const CHROME: {
         formJson: string;
         copy: string;
         copied: string;
-        nothingSaved: string;
+        noTemplates: string;
         updated: string;
         open: string;
         saveForm: string;
         formName: string;
         saveToLibrary: string;
         loadingDraft: string;
+        templatesLimitReached: string;
         current: string;
         customColor: string;
         fieldsCount: (n: number) => string;
-        formSettings: string;
-        submitLabel: string;
-        submitMode: string;
-        combined: string;
-        perSection: string;
-        settings: string;
         fieldTypeInput: string;
         fieldTypeTextarea: string;
         fieldTypeSelect: string;
@@ -255,6 +259,7 @@ declare const CHROME: {
         fieldTypeToggle: string;
         fieldTypeParagraph: string;
         fieldTypeImage: string;
+        fieldTypeButton: string;
         subtypeText: string;
         subtypeEmail: string;
         subtypePhone: string;
@@ -267,8 +272,17 @@ declare const CHROME: {
         shapeBanner: string;
         tagBody: string;
         tagCaption: string;
-        submitSectionTitle: string;
-        submitStyle: string;
+        buttonText: string;
+        buttonActionTitle: string;
+        buttonAction: string;
+        actionLink: string;
+        actionSubmit: string;
+        openIn: string;
+        sameTab: string;
+        newTab: string;
+        submitScope: string;
+        thisSection: string;
+        wholeForm: string;
         buttonSize: string;
         theme: string;
         primaryColor: string;
@@ -416,7 +430,17 @@ interface ImageField extends BaseField {
     link: string;
     shape: "square" | "circle" | "banner";
 }
-type FormField = InputField | TextareaField | SelectField | RadioField | CheckboxGroupField | CheckboxField | ToggleField | ParagraphField | ImageField;
+interface ButtonField extends BaseField {
+    type: "button";
+    action: "link" | "submit";
+    buttonStyle: SubmitStyle;
+    /** Used when `action === "link"`. */
+    href: string;
+    target: "_self" | "_blank";
+    /** Used when `action === "submit"`. */
+    submitScope: "section" | "form";
+}
+type FormField = InputField | TextareaField | SelectField | RadioField | CheckboxGroupField | CheckboxField | ToggleField | ParagraphField | ImageField | ButtonField;
 /**
  * Flat, fully-optional patch type for updateField/updateOption call sites.
  * A strict `Partial<FormField>` doesn't typecheck for cross-type shallow
@@ -450,6 +474,11 @@ interface FieldPatch {
     alt?: LocalizedString;
     link?: string;
     shape?: ImageField["shape"];
+    action?: ButtonField["action"];
+    buttonStyle?: SubmitStyle;
+    href?: string;
+    target?: ButtonField["target"];
+    submitScope?: ButtonField["submitScope"];
 }
 interface SubmitStyle {
     color: string;
@@ -460,20 +489,18 @@ interface Section {
     title: LocalizedString;
     background: string;
     collapsed: boolean;
-    submitStyle: SubmitStyle | null;
     fields: FormField[];
 }
 interface DocumentFields {
     title: LocalizedString;
-    submitLabel: LocalizedString;
-    submitMode: "combined" | "perSection";
-    submitStyle: SubmitStyle;
     themeOverrides: ThemeOverrides;
     sections: Section[];
 }
 /** Shape used only for the "View JSON" export (stamped with a version). */
 interface FormDocument extends DocumentFields {
-    version: 4;
+    version: 5;
+    /** Fully resolved theme (DEFAULT_THEME merged with `themeOverrides`) — lets a host re-render this document's styling without needing its own copy of the defaults. */
+    theme: Theme;
 }
 interface SavedFormMeta {
     id: string;
@@ -511,6 +538,31 @@ interface StorageAdapter {
     set(key: string, value: string): Promise<void>;
     delete(key: string): Promise<void>;
 }
+interface SubmitPayload {
+    /** id of the button field that triggered this submission. */
+    buttonId: string;
+    /** Whether the triggering button's scope was the whole form or just its own section. */
+    scope: "form" | "section";
+    /** Set when `scope === "section"`. */
+    sectionId?: string;
+    /** fieldId -> raw value, scoped to whatever was just submitted (the whole form for "combined", one section for "section"). */
+    values: Record<string, unknown>;
+    /** Section-wise breakdown of the *entire* form, regardless of scope. */
+    sections: {
+        sectionId: string;
+        values: Record<string, unknown>;
+    }[];
+    /** Flattened fieldId -> raw value across every section, for convenience. */
+    all: Record<string, unknown>;
+}
+interface FormBuilderHandle {
+    /** The current document, fully resolved (same shape as the "View JSON" export). */
+    getDocument(): FormDocument;
+    /** Replaces the current document — e.g. a form fetched from your own backend. Routes through the same migration path as opening a saved template, so older/looser JSON shapes are tolerated. */
+    loadDocument(doc: FormDocument): void;
+    /** Convenience for `JSON.stringify(getDocument())`. */
+    exportJson(): string;
+}
 interface FormBuilderProps {
     theme?: Partial<Theme>;
     language?: string;
@@ -519,16 +571,25 @@ interface FormBuilderProps {
     chrome?: Record<string, Partial<ChromeShape>>;
     themeEditable?: boolean;
     storage?: StorageAdapter;
+    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;
 }
 
-declare function FormBuilder({ theme: themeOverrideProp, language: languageOverride, languages, strings: stringsOverride, chrome: chromeOverride, themeEditable, storage: storageProp, }?: FormBuilderProps): react.JSX.Element;
+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.
  */
 declare const localStorageAdapter: StorageAdapter;
 
-export { type CheckboxField, type CheckboxGroupField, type ChromeShape, type DocumentFields, type FieldPatch, type FieldType, FormBuilder, type FormBuilderProps, type FormDocument, type FormField, type ImageField, type InputField, type LanguageOption, type LocalizedString, type Option, type ParagraphField, type RadioField, type SavedFormMeta, type Section, type SelectField, type StorageAdapter, type StringsShape, type SubmitStyle, type TextareaField, type Theme, type ThemeLayout, type ThemeOverrides, type ToggleField, FormBuilder as default, localStorageAdapter };
+export { type CheckboxField, type CheckboxGroupField, type ChromeShape, type DocumentFields, type FieldPatch, type FieldType, FormBuilder, type FormBuilderHandle, type FormBuilderProps, type FormDocument, type FormField, type ImageField, type InputField, 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 };

package/dist/index.d.ts

@@ -28,13 +28,15 @@ declare const ICON_LIBRARY: {
 };
 type IconKey = keyof typeof ICON_LIBRARY;
 
-type FieldType = "paragraph" | "image" | "input" | "textarea" | "select" | "radio" | "checkboxGroup" | "checkbox" | "toggle";
+type FieldType = "paragraph" | "image" | "button" | "input" | "textarea" | "select" | "radio" | "checkboxGroup" | "checkbox" | "toggle";
 
 declare const CHROME: {
     en: {
         contentBlocks: string;
         formFields: string;
         addingTo: string;
+        paletteTabBlocks: string;
+        paletteTabDesign: string;
         properties: string;
         selectFieldHint: string;
         label: string;
@@ -80,14 +82,14 @@ declare const CHROME: {
         build: string;
         preview: string;
         newForm: string;
-        myForms: string;
+        templates: string;
         save: string;
         viewJson: string;
         saving: string;
         saved: string;
         saveFailed: string;
         startNewForm: string;
-        openSavedForm: string;
+        openTemplatesTitle: string;
         saveToLibraryTitle: string;
         sectionTitlePlaceholder: (n: number) => string;
         noFieldsInSection: string;
@@ -101,22 +103,17 @@ declare const CHROME: {
         formJson: string;
         copy: string;
         copied: string;
-        nothingSaved: string;
+        noTemplates: string;
         updated: string;
         open: string;
         saveForm: string;
         formName: string;
         saveToLibrary: string;
         loadingDraft: string;
+        templatesLimitReached: string;
         current: string;
         customColor: string;
         fieldsCount: (n: number) => string;
-        formSettings: string;
-        submitLabel: string;
-        submitMode: string;
-        combined: string;
-        perSection: string;
-        settings: string;
         fieldTypeInput: string;
         fieldTypeTextarea: string;
         fieldTypeSelect: string;
@@ -126,6 +123,7 @@ declare const CHROME: {
         fieldTypeToggle: string;
         fieldTypeParagraph: string;
         fieldTypeImage: string;
+        fieldTypeButton: string;
         subtypeText: string;
         subtypeEmail: string;
         subtypePhone: string;
@@ -138,8 +136,17 @@ declare const CHROME: {
         shapeBanner: string;
         tagBody: string;
         tagCaption: string;
-        submitSectionTitle: string;
-        submitStyle: string;
+        buttonText: string;
+        buttonActionTitle: string;
+        buttonAction: string;
+        actionLink: string;
+        actionSubmit: string;
+        openIn: string;
+        sameTab: string;
+        newTab: string;
+        submitScope: string;
+        thisSection: string;
+        wholeForm: string;
         buttonSize: string;
         theme: string;
         primaryColor: string;
@@ -164,6 +171,8 @@ declare const CHROME: {
         contentBlocks: string;
         formFields: string;
         addingTo: string;
+        paletteTabBlocks: string;
+        paletteTabDesign: string;
         properties: string;
         selectFieldHint: string;
         label: string;
@@ -209,14 +218,14 @@ declare const CHROME: {
         build: string;
         preview: string;
         newForm: string;
-        myForms: string;
+        templates: string;
         save: string;
         viewJson: string;
         saving: string;
         saved: string;
         saveFailed: string;
         startNewForm: string;
-        openSavedForm: string;
+        openTemplatesTitle: string;
         saveToLibraryTitle: string;
         sectionTitlePlaceholder: (n: number) => string;
         noFieldsInSection: string;
@@ -230,22 +239,17 @@ declare const CHROME: {
         formJson: string;
         copy: string;
         copied: string;
-        nothingSaved: string;
+        noTemplates: string;
         updated: string;
         open: string;
         saveForm: string;
         formName: string;
         saveToLibrary: string;
         loadingDraft: string;
+        templatesLimitReached: string;
         current: string;
         customColor: string;
         fieldsCount: (n: number) => string;
-        formSettings: string;
-        submitLabel: string;
-        submitMode: string;
-        combined: string;
-        perSection: string;
-        settings: string;
         fieldTypeInput: string;
         fieldTypeTextarea: string;
         fieldTypeSelect: string;
@@ -255,6 +259,7 @@ declare const CHROME: {
         fieldTypeToggle: string;
         fieldTypeParagraph: string;
         fieldTypeImage: string;
+        fieldTypeButton: string;
         subtypeText: string;
         subtypeEmail: string;
         subtypePhone: string;
@@ -267,8 +272,17 @@ declare const CHROME: {
         shapeBanner: string;
         tagBody: string;
         tagCaption: string;
-        submitSectionTitle: string;
-        submitStyle: string;
+        buttonText: string;
+        buttonActionTitle: string;
+        buttonAction: string;
+        actionLink: string;
+        actionSubmit: string;
+        openIn: string;
+        sameTab: string;
+        newTab: string;
+        submitScope: string;
+        thisSection: string;
+        wholeForm: string;
         buttonSize: string;
         theme: string;
         primaryColor: string;
@@ -416,7 +430,17 @@ interface ImageField extends BaseField {
     link: string;
     shape: "square" | "circle" | "banner";
 }
-type FormField = InputField | TextareaField | SelectField | RadioField | CheckboxGroupField | CheckboxField | ToggleField | ParagraphField | ImageField;
+interface ButtonField extends BaseField {
+    type: "button";
+    action: "link" | "submit";
+    buttonStyle: SubmitStyle;
+    /** Used when `action === "link"`. */
+    href: string;
+    target: "_self" | "_blank";
+    /** Used when `action === "submit"`. */
+    submitScope: "section" | "form";
+}
+type FormField = InputField | TextareaField | SelectField | RadioField | CheckboxGroupField | CheckboxField | ToggleField | ParagraphField | ImageField | ButtonField;
 /**
  * Flat, fully-optional patch type for updateField/updateOption call sites.
  * A strict `Partial<FormField>` doesn't typecheck for cross-type shallow
@@ -450,6 +474,11 @@ interface FieldPatch {
     alt?: LocalizedString;
     link?: string;
     shape?: ImageField["shape"];
+    action?: ButtonField["action"];
+    buttonStyle?: SubmitStyle;
+    href?: string;
+    target?: ButtonField["target"];
+    submitScope?: ButtonField["submitScope"];
 }
 interface SubmitStyle {
     color: string;
@@ -460,20 +489,18 @@ interface Section {
     title: LocalizedString;
     background: string;
     collapsed: boolean;
-    submitStyle: SubmitStyle | null;
     fields: FormField[];
 }
 interface DocumentFields {
     title: LocalizedString;
-    submitLabel: LocalizedString;
-    submitMode: "combined" | "perSection";
-    submitStyle: SubmitStyle;
     themeOverrides: ThemeOverrides;
     sections: Section[];
 }
 /** Shape used only for the "View JSON" export (stamped with a version). */
 interface FormDocument extends DocumentFields {
-    version: 4;
+    version: 5;
+    /** Fully resolved theme (DEFAULT_THEME merged with `themeOverrides`) — lets a host re-render this document's styling without needing its own copy of the defaults. */
+    theme: Theme;
 }
 interface SavedFormMeta {
     id: string;
@@ -511,6 +538,31 @@ interface StorageAdapter {
     set(key: string, value: string): Promise<void>;
     delete(key: string): Promise<void>;
 }
+interface SubmitPayload {
+    /** id of the button field that triggered this submission. */
+    buttonId: string;
+    /** Whether the triggering button's scope was the whole form or just its own section. */
+    scope: "form" | "section";
+    /** Set when `scope === "section"`. */
+    sectionId?: string;
+    /** fieldId -> raw value, scoped to whatever was just submitted (the whole form for "combined", one section for "section"). */
+    values: Record<string, unknown>;
+    /** Section-wise breakdown of the *entire* form, regardless of scope. */
+    sections: {
+        sectionId: string;
+        values: Record<string, unknown>;
+    }[];
+    /** Flattened fieldId -> raw value across every section, for convenience. */
+    all: Record<string, unknown>;
+}
+interface FormBuilderHandle {
+    /** The current document, fully resolved (same shape as the "View JSON" export). */
+    getDocument(): FormDocument;
+    /** Replaces the current document — e.g. a form fetched from your own backend. Routes through the same migration path as opening a saved template, so older/looser JSON shapes are tolerated. */
+    loadDocument(doc: FormDocument): void;
+    /** Convenience for `JSON.stringify(getDocument())`. */
+    exportJson(): string;
+}
 interface FormBuilderProps {
     theme?: Partial<Theme>;
     language?: string;
@@ -519,16 +571,25 @@ interface FormBuilderProps {
     chrome?: Record<string, Partial<ChromeShape>>;
     themeEditable?: boolean;
     storage?: StorageAdapter;
+    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;
 }
 
-declare function FormBuilder({ theme: themeOverrideProp, language: languageOverride, languages, strings: stringsOverride, chrome: chromeOverride, themeEditable, storage: storageProp, }?: FormBuilderProps): react.JSX.Element;
+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.
  */
 declare const localStorageAdapter: StorageAdapter;
 
-export { type CheckboxField, type CheckboxGroupField, type ChromeShape, type DocumentFields, type FieldPatch, type FieldType, FormBuilder, type FormBuilderProps, type FormDocument, type FormField, type ImageField, type InputField, type LanguageOption, type LocalizedString, type Option, type ParagraphField, type RadioField, type SavedFormMeta, type Section, type SelectField, type StorageAdapter, type StringsShape, type SubmitStyle, type TextareaField, type Theme, type ThemeLayout, type ThemeOverrides, type ToggleField, FormBuilder as default, localStorageAdapter };
+export { type CheckboxField, type CheckboxGroupField, type ChromeShape, type DocumentFields, type FieldPatch, type FieldType, FormBuilder, type FormBuilderHandle, type FormBuilderProps, type FormDocument, type FormField, type ImageField, type InputField, 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 };