form-page-builder 2.2.0 → 2.4.0

package/README.md

@@ -107,6 +107,7 @@ Every optional UI surface can be switched on or off independently through one `f
 | Key | Type | Default | Controls |
 |---|---|---|---|
 | `naming` | `boolean` | `true` | The editable form-title input in the toolbar. |
+| `formTitle` | `boolean` | `false` | Renders the form title as an `<h2>` heading above the fields in Preview. Off by default — the host app usually shows the form's name in its own chrome, so leave this off to avoid a duplicate. |
 | `templates` | `boolean \| { manage?: boolean; max?: number }` | `true` | The Templates library and the "Save" button. `true` = full library (browse / apply / save / overwrite / delete). `false` = no template UI. `{ manage: false }` = pick-and-apply only: the library lists templates and the user can apply one as a starting point, but can't create, overwrite, or delete them and the "Save" button is hidden. `{ max: n }` caps how many templates can be stored (default 5). |
 | `newForm` | `boolean` | `true` | The "New Form" reset button. |
 | `autosave` | `boolean` | `true` | Autosaving the draft to `storage`. The initial draft *load* always happens regardless — this only gates the write path. |
@@ -122,10 +123,24 @@ Every optional UI surface can be switched on or off independently through one `f
 | `sectionBackground` | `boolean` | inherits `sections` | Per-section background-color swatches + custom-color picker in the section header. Independent of `sections` — set it `false` to lock section backgrounds while keeping the structural controls, or leave it unset and it follows whatever `sections` is. |
 | `dragReorder` | `boolean` | `true` | Drag-to-reorder fields within a section. |
 | `deviceToggle` | `boolean` | `true` | The Laptop/Tablet/Mobile width switcher above the Preview canvas. When `false`, Preview always renders at the Laptop (full) width. |
-| `maxFields` | `number` | `undefined` (unlimited) | Caps the total number of input-type fields (not content blocks) addable across the whole document. Once reached, the Form Fields palette buttons disable until a field is removed. |
+| `maxFields` | `number` | `undefined` (unlimited) | Caps the total number of input-type fields (not content blocks) addable across the whole document. The palette shows a live "Fields: n / max" count; once reached, the Form Fields buttons disable and a limit message replaces the count until a field is removed. |
 
 Disabling `contentBlocks`/`fieldTypes` for a given type only hides it from the palette going forward — if a document loaded via `initialDocument` (or a saved template) already contains fields of a now-disabled type, they still render and remain editable in Build mode; nothing is stripped or hidden.
 
+### Styling hooks
+
+The widget styles itself with inline styles and CSS custom properties (see theming below), but the rendered form also carries stable, rule-free class names so a host stylesheet can target it:
+
+| Class | On |
+|---|---|
+| `.fb-form` | The Preview form container. |
+| `.fb-section` | Each section wrapper (also `data-section-id`). |
+| `.fb-field` | Every field wrapper, in Preview and on the Build canvas (also `data-field-id`). |
+| `.fb-field--<type>` | Same wrapper, by field type — `fb-field--input`, `fb-field--select`, `fb-field--button`, … |
+| `.fb-field--<id>` | Same wrapper, by field id (`fb-field--field_1`). Field ids are sequential (`field_1`, `field_2`, …) and stable across reloads. |
+
+These are additive hooks only — the package ships no rules for them, so anything you write wins without `!important`.
+
 ### Features vs. theming
 
 `features` and `theme` are separate, composable concerns: `features.design` decides whether the Design tab's color/spacing *controls* are shown at all, while `theme` (and the Design tab, when shown) decide what those colors/spacing values *are*. You can, for instance, pass a fixed `theme` with `features.design` and `features.blockStyling` both `false` to lock a form to your brand's colors with zero styling UI exposed to the builder's user.
@@ -258,6 +273,20 @@ const json = serializeTemplate(ref.current.getDocument());
 const doc = parseTemplate(json);               // also accepts bare "View JSON" output; null if not a document
 ```
 
+### Smaller stored documents
+
+Drafts and saved templates written through `storage` are compacted automatically: props equal to their default (`hideLabel`, `width`, `verticalAlign`, `labelPosition`, `showIcon`, `required`, the type's default icon, empty placeholders/default values, empty non-`en` translations) are omitted and the document is stamped `compact: 1`. Loading restores them, so older full documents still load unchanged.
+
+`getDocument()` still returns the full document. If you store it yourself, compact it first:
+
+```tsx
+import { compactDocument } from "form-page-builder";
+
+await save(JSON.stringify(compactDocument(ref.current.getDocument())));
+```
+
+Documents saved in the compact form need this package version (or newer) to be read back correctly, so upgrade every app that reads them together.
+
 ## Using in a plain HTML page (no bundler)
 
 There's intentionally no UMD/IIFE global-script build (see below), but you don't need a bundler to use this package — a browser-native ES module setup works too, via an [import map](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap) and a CDN like [esm.sh](https://esm.sh/):

package/dist/index.cjs

@@ -24,9 +24,11 @@ __export(index_exports, {
   CLIPBOARD_KEY: () => CLIPBOARD_KEY,
   DARK_THEME: () => DARK_THEME,
   DEFAULT_THEME: () => DEFAULT_THEME,
+  DOCUMENT_VERSION: () => DOCUMENT_VERSION,
   DRAFT_KEY: () => DRAFT_KEY,
   FormBuilder: () => FormBuilder_default,
   INDEX_KEY: () => INDEX_KEY,
+  compactDocument: () => compactDocument,
   default: () => FormBuilder_default,
   formKey: () => formKey,
   localStorageAdapter: () => localStorageAdapter,
@@ -221,6 +223,8 @@ var CHROME = {
     loadingDraft: "Loading your draft...",
     templatesLimitReached: (max) => `You can save up to ${max} template${max === 1 ? "" : "s"}. Delete one to save another.`,
     templatesLimitTitle: "Template limit reached",
+    fieldCount: (n, max) => `Fields: ${n} / ${max}`,
+    fieldLimitReached: (max) => `Field limit reached (${max}). Delete a field to add another.`,
     confirm: "Confirm",
     cancel: "Cancel",
     dismiss: "OK",
@@ -374,6 +378,8 @@ var CHROME = {
     loadingDraft: "\u4E0B\u66F8\u304D\u3092\u8AAD\u307F\u8FBC\u3093\u3067\u3044\u307E\u3059...",
     templatesLimitReached: (max) => `\u30C6\u30F3\u30D7\u30EC\u30FC\u30C8\u306F${max}\u4EF6\u307E\u3067\u4FDD\u5B58\u3067\u304D\u307E\u3059\u30021\u4EF6\u524A\u9664\u3057\u3066\u304B\u3089\u4FDD\u5B58\u3057\u3066\u304F\u3060\u3055\u3044\u3002`,
     templatesLimitTitle: "\u30C6\u30F3\u30D7\u30EC\u30FC\u30C8\u306E\u4E0A\u9650\u306B\u9054\u3057\u307E\u3057\u305F",
+    fieldCount: (n, max) => `\u9805\u76EE\u6570: ${n} / ${max}`,
+    fieldLimitReached: (max) => `\u9805\u76EE\u6570\u306E\u4E0A\u9650\uFF08${max}\u4EF6\uFF09\u306B\u9054\u3057\u307E\u3057\u305F\u3002\u8FFD\u52A0\u3059\u308B\u306B\u306F\u9805\u76EE\u3092\u524A\u9664\u3057\u3066\u304F\u3060\u3055\u3044\u3002`,
     confirm: "\u78BA\u5B9A",
     cancel: "\u30AD\u30E3\u30F3\u30BB\u30EB",
     dismiss: "OK",
@@ -583,12 +589,8 @@ function defaultSection(titleEn = "") {
   return { id: genSectionId(), title: bi(titleEn, ""), background: "", collapsed: false, fields: [] };
 }
 
-// src/lib/submittable.ts
-function sectionHasFormFields(section) {
-  return section.fields.some((f) => !getMeta(f.type).isContent);
-}
-
 // src/lib/migrate.ts
+var DOCUMENT_VERSION = 5;
 function migrateField(field) {
   let f = { ...field };
   if (LEGACY_INPUT_TYPES.includes(f.type)) f = { ...f, type: "input", inputType: f.type };
@@ -614,30 +616,21 @@ function migrateField(field) {
     f.submitScope = f.submitScope === "section" ? "section" : "form";
   }
   f.verticalAlign = f.verticalAlign || "top";
+  const meta = getMeta(f.type);
+  f.width = f.width || "1/1";
+  f.labelPosition = f.labelPosition || "top";
+  f.showIcon = !!f.showIcon;
+  f.displayIcon = f.displayIcon || meta.defaultIcon;
+  if (!meta.isContent) {
+    f.required = !!f.required;
+    if (meta.placeholder && !f.placeholder) f.placeholder = bi();
+    if (f.defaultValue === void 0) f.defaultValue = meta.boolean ? false : meta.multiValue ? [] : "";
+  }
   return f;
 }
 function migrateFields(fields) {
   return (fields || []).map(migrateField);
 }
-function synthesizeButtonField(label, style, scope) {
-  const resolvedLabel = typeof label === "string" && label ? bi(label) : label && typeof label === "object" && (label.en || label.ja) ? label : bi("Submit", "");
-  return {
-    id: nextId(),
-    type: "button",
-    label: resolvedLabel,
-    hideLabel: false,
-    width: "1/1",
-    verticalAlign: "top",
-    labelPosition: "top",
-    showIcon: false,
-    displayIcon: "Type",
-    action: "submit",
-    submitScope: scope,
-    buttonStyle: style || { color: "", size: "md" },
-    href: "",
-    target: "_self"
-  };
-}
 function migrateDocument(raw) {
   if (!raw) return null;
   const title = typeof raw.title === "string" ? bi(raw.title) : raw.title || bi();
@@ -654,25 +647,6 @@ function migrateDocument(raw) {
   } else {
     sections = [{ ...defaultSection(), fields: migrateFields(raw.fields || []) }];
   }
-  const legacy = raw.version === void 0 || raw.version < 5;
-  if (legacy) {
-    resyncIdCounter(sections.flatMap((s) => s.fields));
-    const submitMode = raw.submitMode === "perSection" ? "perSection" : "combined";
-    const submitLabel = raw.submitLabel;
-    const submitStyle = raw.submitStyle || { color: "", size: "md" };
-    if (submitMode === "perSection" && raw.sections) {
-      sections = sections.map((s, i) => {
-        if (!sectionHasFormFields(s)) return s;
-        const rawSection = raw.sections[i] || {};
-        const label = rawSection.submitLabel || submitLabel;
-        const style = rawSection.submitStyle || submitStyle;
-        return { ...s, fields: [...s.fields, synthesizeButtonField(label, style, "section")] };
-      });
-    } else if (sections.some(sectionHasFormFields)) {
-      const lastIdx = sections.length - 1;
-      sections = sections.map((s, i) => i === lastIdx ? { ...s, fields: [...s.fields, synthesizeButtonField(submitLabel, submitStyle, "form")] } : s);
-    }
-  }
   return { title, themeOverrides, sections };
 }
 
@@ -700,6 +674,7 @@ function parseTemplate(raw) {
 var DEFAULT_MAX_TEMPLATES = 5;
 var DEFAULT_FEATURES = {
   naming: true,
+  formTitle: false,
   templates: { enabled: true, manage: true, max: DEFAULT_MAX_TEMPLATES },
   templateClipboard: true,
   newForm: true,
@@ -903,7 +878,9 @@ function useFormDocument({ language, chrome }) {
       ...s,
       fields: s.fields.map((f) => {
         if (f.id !== fieldId || !("options" in f) || !f.options) return f;
-        const n = f.options.length + 1;
+        const used = new Set(f.options.map((o) => o.value));
+        let n = f.options.length + 1;
+        while (used.has(`option_${n}`)) n++;
         return { ...f, options: [...f.options, { label: withLang(bi(), language, chrome.optionSeed(n)), value: `option_${n}` }] };
       })
     })));
@@ -911,7 +888,14 @@ function useFormDocument({ language, chrome }) {
   function removeOption(fieldId, optIdx) {
     setSections((prev) => prev.map((s) => ({
       ...s,
-      fields: s.fields.map((f) => f.id !== fieldId || !("options" in f) || !f.options ? f : { ...f, options: f.options.filter((_, i) => i !== optIdx) })
+      fields: s.fields.map((f) => {
+        if (f.id !== fieldId || !("options" in f) || !f.options) return f;
+        const removed = f.options[optIdx]?.value;
+        const options = f.options.filter((_, i) => i !== optIdx);
+        if (f.type === "checkboxGroup") return { ...f, options, defaultValue: f.defaultValue.filter((v) => v !== removed) };
+        if ((f.type === "select" || f.type === "radio") && f.defaultValue === removed) return { ...f, options, defaultValue: "" };
+        return { ...f, options };
+      })
     })));
   }
   function loadDocument(doc) {
@@ -971,6 +955,51 @@ var formKey = (id) => `form-page-builder:saved:${id}`;
 var savedFormId = (key) => key.startsWith("form-page-builder:saved:") ? key.slice("form-page-builder:saved:".length) : null;
 var CLIPBOARD_KEY = "form-page-builder:clipboard";
 
+// src/lib/compact.ts
+var BASE_DEFAULTS = {
+  hideLabel: false,
+  width: "1/1",
+  verticalAlign: "top",
+  labelPosition: "top",
+  showIcon: false,
+  required: false
+};
+var COMPACT_VERSION = 1;
+var slimLocalized = (v) => v && typeof v === "object" ? Object.fromEntries(Object.entries(v).filter(([lang, s]) => lang === "en" || s !== "")) : v;
+var isEmptyLocalized = (v) => !!v && typeof v === "object" && Object.values(v).every((s) => !s);
+var isEmptyDefault = (v) => v === "" || v === false || Array.isArray(v) && v.length === 0;
+function compactField(field) {
+  const out = {};
+  const meta = getMeta(field.type);
+  for (const [key, value] of Object.entries(field)) {
+    if (key in BASE_DEFAULTS && value === BASE_DEFAULTS[key]) continue;
+    if (key === "displayIcon" && value === meta.defaultIcon) continue;
+    if (key === "placeholder" && isEmptyLocalized(value)) continue;
+    if (key === "defaultValue" && !meta.isContent && isEmptyDefault(value)) continue;
+    if (key === "label" || key === "placeholder" || key === "content" || key === "alt") out[key] = slimLocalized(value);
+    else if (key === "options" && Array.isArray(value)) out[key] = value.map((o) => ({ ...o, label: slimLocalized(o.label) }));
+    else out[key] = value;
+  }
+  return out;
+}
+function compactDocument(doc) {
+  return {
+    ...doc,
+    compact: COMPACT_VERSION,
+    ...doc.title !== void 0 ? { title: slimLocalized(doc.title) } : {},
+    sections: doc.sections.map((s) => {
+      const { background, collapsed, fields, ...rest } = s;
+      return {
+        ...rest,
+        ...s.title !== void 0 ? { title: slimLocalized(s.title) } : {},
+        ...background ? { background } : {},
+        ...collapsed ? { collapsed } : {},
+        fields: fields.map(compactField)
+      };
+    })
+  };
+}
+
 // src/hooks/usePersistence.ts
 function snapshotOf(d) {
   return JSON.stringify({ title: d.title, themeOverrides: d.themeOverrides, sections: d.sections });
@@ -1063,7 +1092,7 @@ function usePersistence({
     if (autosaveTimer.current) clearTimeout(autosaveTimer.current);
     autosaveTimer.current = setTimeout(async () => {
       try {
-        await storage.set(DRAFT_KEY, JSON.stringify({ ...document2, currentFormId }));
+        await storage.set(DRAFT_KEY, JSON.stringify({ version: DOCUMENT_VERSION, ...compactDocument(document2), currentFormId }));
         setSaveState("saved");
       } catch {
         setSaveState("error");
@@ -1086,7 +1115,7 @@ function usePersistence({
     try {
       const newTitle = bi(name, "");
       const docToSave = { ...document2, title: newTitle };
-      await storage.set(formKey(id), JSON.stringify({ ...docToSave, id, updatedAt: now }));
+      await storage.set(formKey(id), JSON.stringify({ version: DOCUMENT_VERSION, ...compactDocument(docToSave), id, updatedAt: now }));
       const next = [...savedForms, { id, title: name, updatedAt: now }];
       await storage.set(INDEX_KEY, JSON.stringify(next));
       setSavedForms(next);
@@ -1109,7 +1138,7 @@ function usePersistence({
     const now = Date.now();
     setTemplateState("saving");
     try {
-      await storage.set(formKey(currentFormId), JSON.stringify({ ...document2, id: currentFormId, updatedAt: now }));
+      await storage.set(formKey(currentFormId), JSON.stringify({ version: DOCUMENT_VERSION, ...compactDocument(document2), id: currentFormId, updatedAt: now }));
       const next = savedForms.map((f) => f.id === currentFormId ? { ...f, title: t(document2.title, "en"), updatedAt: now } : f);
       setSavedForms(next);
       await storage.set(INDEX_KEY, JSON.stringify(next));
@@ -1125,11 +1154,13 @@ function usePersistence({
     try {
       const raw = await storage.get(formKey(id));
       if (!raw) {
+        console.error(`[form-page-builder] loadForm(${id}): storage returned no data for this id`);
         setTemplateState("error");
         return false;
       }
       const doc = migrateDocument(JSON.parse(raw));
       if (!doc) {
+        console.error(`[form-page-builder] loadForm(${id}): stored data failed migrateDocument()`, raw);
         setTemplateState("error");
         return false;
       }
@@ -1141,7 +1172,8 @@ function usePersistence({
       setTemplateState("idle");
       onTemplateChange?.({ id, title: t(doc.title, language), source: "applied" });
       return true;
-    } catch {
+    } catch (err) {
+      console.error(`[form-page-builder] loadForm(${id}) threw`, err);
       setTemplateState("error");
       return false;
     }
@@ -1149,6 +1181,7 @@ function usePersistence({
   async function deleteForm(id) {
     if (!templateManage) return;
     const removed = savedForms.find((f) => f.id === id);
+    setTemplateState("loading");
     try {
       await storage.delete(formKey(id));
       const next = savedForms.filter((f) => f.id !== id);
@@ -1158,6 +1191,7 @@ function usePersistence({
         setCurrentFormId(null);
         savedSnapshot.current = null;
       }
+      setTemplateState("idle");
       onTemplateChange?.({ id: currentFormId === id ? null : id, title: removed?.title ?? "", source: "deleted" });
     } catch {
       setTemplateState("error");
@@ -1665,6 +1699,7 @@ function Palette({
       ] }),
       formTypes.length > 0 && /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)(import_jsx_runtime5.Fragment, { children: [
         /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("div", { style: { ...styles.panelHeading, marginTop: 16 }, children: chrome.formFields }),
+        typeof features.maxFields === "number" && /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("div", { role: "status", style: { ...styles.activeSectionHint, marginBottom: 8, ...atFieldCap ? { color: "var(--fb-danger)" } : {} }, children: atFieldCap ? chrome.fieldLimitReached(features.maxFields) : chrome.fieldCount(fieldCount, features.maxFields) }),
         /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("div", { style: styles.paletteList, children: formTypes.map((f) => {
           const Icon = f.icon;
           const itemStyle = atFieldCap ? { ...styles.paletteItem, opacity: 0.45, cursor: "not-allowed" } : styles.paletteItem;
@@ -1910,6 +1945,8 @@ function FieldTicket({
     {
       ...dropZoneHandlers,
       onClick: onSelect,
+      className: `fb-field fb-field--${field.type} fb-field--${field.id}`,
+      "data-field-id": field.id,
       style: {
         ...styles.ticket,
         flex: `1 1 calc(${widthPct} - 10px)`,
@@ -2439,16 +2476,16 @@ function PreviewPane({ title, sections, onFieldChange, language, strings, chrome
   return /* @__PURE__ */ (0, import_jsx_runtime14.jsxs)("div", { style: styles.previewWrap, children: [
     /* @__PURE__ */ (0, import_jsx_runtime14.jsxs)("div", { style: { width: "100%", maxWidth, display: "flex", flexDirection: "column", alignItems: "center" }, children: [
       features.deviceToggle && /* @__PURE__ */ (0, import_jsx_runtime14.jsx)("div", { style: styles.previewToolbar, children: /* @__PURE__ */ (0, import_jsx_runtime14.jsx)(Segmented, { options: deviceOptions, value: device, onChange: setDevice }) }),
-      /* @__PURE__ */ (0, import_jsx_runtime14.jsxs)("div", { style: { ...styles.previewCard, maxWidth, width: "100%" }, children: [
-        /* @__PURE__ */ (0, import_jsx_runtime14.jsx)("h2", { style: styles.previewTitle, children: t(title, language) }),
+      /* @__PURE__ */ (0, import_jsx_runtime14.jsxs)("div", { className: "fb-form", style: { ...styles.previewCard, maxWidth, width: "100%" }, children: [
+        features.formTitle && /* @__PURE__ */ (0, import_jsx_runtime14.jsx)("h2", { style: styles.previewTitle, children: t(title, language) }),
         allFields.length === 0 && /* @__PURE__ */ (0, import_jsx_runtime14.jsx)("p", { style: { color: "var(--fb-muted)", fontSize: 14 }, children: strings.addFieldsHint }),
         sections.map((section) => {
-          return /* @__PURE__ */ (0, import_jsx_runtime14.jsxs)("div", { style: { background: section.background || "transparent", padding: section.background ? 16 : 0, borderRadius: section.background ? 10 : 0, marginBottom: "var(--fb-space-section)" }, children: [
+          return /* @__PURE__ */ (0, import_jsx_runtime14.jsxs)("div", { className: "fb-section", "data-section-id": section.id, style: { background: section.background || "transparent", padding: section.background ? 16 : 0, borderRadius: section.background ? 10 : 0, marginBottom: "var(--fb-space-section)" }, children: [
             t(section.title, language) && /* @__PURE__ */ (0, import_jsx_runtime14.jsx)("h3", { style: styles.sectionRuntimeTitle, children: t(section.title, language) }),
             /* @__PURE__ */ (0, import_jsx_runtime14.jsx)("div", { style: styles.previewGrid, children: section.fields.map((field) => {
               const width = effectiveWidth(field.width, device);
               const flexBasis = `1 1 calc(${WIDTH_PERCENT[width]} - 14px)`;
-              return /* @__PURE__ */ (0, import_jsx_runtime14.jsxs)("div", { style: { flex: flexBasis, minWidth: 0, alignSelf: ALIGN_MAP[field.verticalAlign || "top"] }, children: [
+              return /* @__PURE__ */ (0, import_jsx_runtime14.jsxs)("div", { className: `fb-field fb-field--${field.type} fb-field--${field.id}`, "data-field-id": field.id, style: { flex: flexBasis, minWidth: 0, alignSelf: ALIGN_MAP[field.verticalAlign || "top"] }, children: [
                 /* @__PURE__ */ (0, import_jsx_runtime14.jsx)(FieldBlock, { field, lang: language, onFieldChange, strings, chrome, error: errors[field.id], onButtonAction: handleButtonAction }),
                 field.type === "button" && field.id === attemptedButtonId && Object.keys(errors).length > 0 && /* @__PURE__ */ (0, import_jsx_runtime14.jsxs)("p", { style: styles.formErrorNote, children: [
                   /* @__PURE__ */ (0, import_jsx_runtime14.jsx)(import_lucide_react14.CircleAlert, { size: 13 }),
@@ -2743,7 +2780,7 @@ var FormBuilder = (0, import_react10.forwardRef)(function FormBuilder2({
     ensureActiveSection: () => doc.setActiveSectionId((prev) => prev ?? doc.sections[0]?.id ?? null)
   });
   const jsonDoc = (0, import_react10.useMemo)(() => ({
-    version: 5,
+    version: DOCUMENT_VERSION,
     title: doc.title,
     theme,
     themeOverrides,
@@ -3021,9 +3058,11 @@ var DARK_THEME = {
   CLIPBOARD_KEY,
   DARK_THEME,
   DEFAULT_THEME,
+  DOCUMENT_VERSION,
   DRAFT_KEY,
   FormBuilder,
   INDEX_KEY,
+  compactDocument,
   formKey,
   localStorageAdapter,
   parseTemplate,