@dmitryvim/form-builder 0.5.3 → 0.6.4

package/dist/types/components/container.d.ts

@@ -1,14 +1,7 @@
 import type { ContainerElement, RenderContext, ComponentContext, ValidationResult, Element } from "../types/index.js";
 export declare function setRenderElement(fn: (element: any, ctx: RenderContext) => HTMLElement): void;
 export declare function renderSingleContainerElement(element: ContainerElement, ctx: RenderContext, wrapper: HTMLElement, pathKey: string): void;
-export declare function renderMultipleContainerElement(element: ContainerElement, ctx: RenderContext, wrapper: HTMLElement, _pathKey: string): void;
-export declare function setValidateElement(fn: (element: Element, ctx: {
-    path: string;
-}, customScopeRoot?: HTMLElement | null) => {
-    value: any;
-    spread: boolean;
-    skip?: boolean;
-}): void;
+export declare function renderMultipleContainerElement(element: ContainerElement, ctx: RenderContext, wrapper: HTMLElement, pathKey: string): void;
 /**
  * Validate container field and return extracted value with errors
  */

package/dist/types/components/index.d.ts

@@ -7,10 +7,9 @@ import { renderSwitcherElement, renderMultipleSwitcherElement } from "./switcher
 import { renderFileElement, renderFilesElement, renderMultipleFileElement } from "./file.js";
 import { renderColourElement, renderMultipleColourElement } from "./colour.js";
 import { renderSliderElement, renderMultipleSliderElement } from "./slider.js";
-import { renderSingleContainerElement, renderMultipleContainerElement, setValidateElement as setContainerValidateElement } from "./container.js";
+import { renderSingleContainerElement, renderMultipleContainerElement } from "./container.js";
 import { renderGroupElement } from "./group.js";
 import { renderTableElement } from "./table.js";
 import { renderRichInputElement } from "./richinput.js";
 export declare function renderElement(element: Element, ctx: RenderContext): HTMLElement;
-export { setContainerValidateElement };
 export { renderTextElement, renderMultipleTextElement, renderTextareaElement, renderMultipleTextareaElement, renderNumberElement, renderMultipleNumberElement, renderSelectElement, renderMultipleSelectElement, renderSwitcherElement, renderMultipleSwitcherElement, renderFileElement, renderFilesElement, renderMultipleFileElement, renderColourElement, renderMultipleColourElement, renderSliderElement, renderMultipleSliderElement, renderSingleContainerElement, renderMultipleContainerElement, renderGroupElement, renderTableElement, renderRichInputElement, };

package/dist/types/instance/FormBuilderInstance.d.ts

@@ -1,4 +1,4 @@
-import type { Schema, ExternalAction, FormData as FormDataResult, Config, State } from "../types/index.js";
+import type { Schema, ExternalAction, FormData as FormDataResult, Config, Locale, State } from "../types/index.js";
 /**
  * FormBuilderInstance - Encapsulates all form state and operations
  * Allows multiple independent forms on the same page without state collisions
@@ -6,6 +6,7 @@ import type { Schema, ExternalAction, FormData as FormDataResult, Config, State
 export declare class FormBuilderInstance {
     private state;
     private instanceId;
+    private prefillHintHandler;
     constructor(config?: Partial<Config>);
     /**
      * Get instance ID (useful for debugging and resource prefixing)
@@ -20,7 +21,9 @@ export declare class FormBuilderInstance {
      */
     setFormRoot(element: HTMLElement): void;
     /**
-     * Configure the form builder
+     * Configure the form builder. Translations deep-merge per locale (same as
+     * the constructor); a locale without translations — configured or default —
+     * is rejected, matching setLocale.
      */
     configure(config: Partial<Config>): void;
     /**
@@ -44,15 +47,33 @@ export declare class FormBuilderInstance {
      */
     setMode(mode: "edit" | "readonly"): void;
     /**
-     * Set locale
+     * Set locale. Custom locales are allowed — their translations must have
+     * been provided via the constructor or configure() first.
      */
-    setLocale(locale: "en" | "ru"): void;
+    setLocale(locale: Locale): void;
     /**
      * Trigger onChange callbacks with debouncing
      * @param fieldPath - Optional field path for field-specific change events
-     * @param fieldValue - Optional field value for field-specific change events
+     * @param fieldValue - Optional field value for field-specific change events.
+     *   When omitted while fieldPath is given, the value is read from the
+     *   freshly extracted form data at debounce time — used by structural
+     *   changes (multi-item add/remove), where the handler has no cheap
+     *   current value but the array is trivially derivable after the fact.
      */
     triggerOnChange(fieldPath?: string, fieldValue?: any): void;
+    /**
+     * Resolve a DOM field path against the extracted form data.
+     *
+     * A plain getValueByPath is wrong for paths inside a multiple container:
+     * row markers keep gaps after a deletion (`s[2]` may be the first surviving
+     * row) while the extracted array is re-packed contiguously — the naive
+     * lookup would read a different row, or nothing. Each `[N]` segment is
+     * mapped from its marker to the row's position among the container's
+     * rendered rows, the same DOM order extraction used to build the array.
+     * A bracketed segment that is not a container marker (a multi-value leaf
+     * like `tags[1]`, whose indices are contiguous) falls back to the index.
+     */
+    private resolveDomPathValue;
     /**
      * Register an external action that will be displayed as a button
      * External actions can be form-level (no related_field) or field-level (with related_field)
@@ -122,6 +143,13 @@ export declare class FormBuilderInstance {
      * Save draft without validation
      */
     saveDraft(): FormDataResult;
+    /**
+     * Post form data to the parent frame — only when the host opted in via
+     * `postMessageTarget`. Outside an iframe `window.parent === window`, so an
+     * unconditional post broadcast form data and the full schema to any
+     * embedding page (targetOrigin "*") on every submit. See CHANGELOG 0.6.0.
+     */
+    private postToParent;
     /**
      * Clear the form - reset all field values to empty while preserving form structure
      * This is done by re-rendering the form with empty data
@@ -174,4 +202,7 @@ export declare class FormBuilderInstance {
      */
     destroy(): void;
     private disconnectEnableIfObservers;
+    private disconnectAutoExpandObservers;
+    private removePrefillHintListener;
+    private removeTooltipElements;
 }

package/dist/types/instance/state.d.ts

@@ -3,6 +3,14 @@ import type { State, Config } from "../types/index.js";
  * Default configuration for new instances
  */
 export declare const defaultConfig: Config;
+/**
+ * Merge user-provided translations over a base map, per locale — the base
+ * packs survive, and each provided locale merges over the base's same-locale
+ * pack. Used by the constructor and configure(); a wholesale replacement
+ * (Object.assign) dropped the default en/ru packs and made t() return key
+ * names.
+ */
+export declare function mergeTranslations(base: Config["translations"], overrides: Partial<Config>["translations"]): Config["translations"];
 /**
  * Create a new isolated state object for a FormBuilderInstance
  * Uses deep merge for translations to preserve default en/ru fallbacks

package/dist/types/types/component-operations.d.ts

@@ -15,6 +15,21 @@ export interface ComponentContext {
     path: string;
     /** Skip validation checks (for draft mode) */
     skipValidation?: boolean;
+    /**
+     * Recursive element validator, threaded per validateForm pass by
+     * FormBuilderInstance. Containers use it to validate children with the
+     * instance's full context. Threaded through the context — never a module
+     * global — so per-instance state cannot leak between instances (the old
+     * setContainerValidateElement setter only worked because validateForm is
+     * synchronous and re-set it before every pass).
+     */
+    validateElement?: (element: Element, ctx: {
+        path: string;
+    }, customScopeRoot?: HTMLElement | null) => {
+        value: any;
+        spread: boolean;
+        skip?: boolean;
+    };
 }
 /**
  * Validation result from a component validator

package/dist/types/types/config.d.ts

@@ -23,6 +23,7 @@ export interface Translations {
     openInNewTab: string;
     changeButton: string;
     placeholderText: string;
+    selectPlaceholder?: string;
     previewAlt: string;
     previewUnavailable: string;
     previewError: string;
@@ -110,6 +111,7 @@ export interface Config {
     onDownloadError: ((error: Error, resourceId: string, fileName: string) => void) | null;
     debounceMs: number;
     verboseErrors: boolean;
+    postMessageTarget: string | null;
     enableFilePreview: boolean;
     maxPreviewSize: string;
     readonly: boolean;

package/dist/types/types/state.d.ts

@@ -23,4 +23,19 @@ export interface State {
      * with a torn-down ctx. Reproducible under React StrictMode (double mount).
      */
     enableIfObservers: Set<MutationObserver>;
+    /**
+     * ResizeObservers created by applyAutoExpand (text/textarea/richinput
+     * auto-height). Each observer's own callback disconnects it when its
+     * textarea has left the DOM — but that check only runs if the observer ever
+     * fires again, so a silently removed field held its observer forever.
+     * destroy() and every renderForm() disconnect the whole set.
+     */
+    autoExpandObservers: Set<ResizeObserver>;
+    /**
+     * Info-button tooltip nodes created by this instance. They live on
+     * document.body (position: fixed, moved there so tile overflow can't clip
+     * them), so clearing formRoot does not remove them — destroy() and every
+     * renderForm() must, or each render cycle leaks its tooltips.
+     */
+    tooltipElements: Set<HTMLElement>;
 }

package/dist/types/utils/helpers.d.ts

@@ -7,8 +7,13 @@ export declare function isElementReadonly(element: {
 }): boolean;
 export declare function isPlainObject(obj: any): obj is Record<string, any>;
 /**
- * Escape HTML special characters to prevent XSS
- * Use when inserting user-controlled or translated content via innerHTML
+ * Escape HTML special characters to prevent XSS.
+ * Use when inserting user-controlled or translated content via innerHTML.
+ *
+ * Escapes quotes as well as `&<>` because several call sites interpolate
+ * into attribute position (e.g. `alt="${escapeHtml(fileName)}"`) — the
+ * previous textContent/innerHTML trick left quotes intact, letting a file
+ * named `x" onerror="…` break out of the attribute.
  */
 export declare function escapeHtml(text: string): string;
 /**
@@ -42,14 +47,38 @@ export declare function clear(node: HTMLElement): void;
 export declare function formatFileSize(bytes: number): string;
 /**
  * Serialize a value for storage in a hidden input's value attribute.
- * Objects/arrays → JSON string, null/undefined → "", primitives → String().
+ * undefined → "", everything else — null included — → JSON.
+ *
+ * JSON for every type — including strings — so deserialization is exact.
+ * The previous String() form was lossy: a hidden text field prefilled with
+ * "true" or "123" came back from getFormData() as a boolean/number.
+ *
+ * null serializes as JSON "null" (not "") so that an explicit null survives
+ * the round-trip: "" used to be re-read as "unset", which let the hidden
+ * validator substitute element.default — updateField(key, null) on a field
+ * with a default could never actually produce null.
  */
 export declare function serializeHiddenValue(value: any): string;
 /**
  * Deserialize a hidden input's value attribute back to its original type.
- * Empty string → null, JSON-parseable → parsed value, otherwise → raw string.
+ * Empty string → null, JSON → parsed value.
+ *
+ * The raw-string fallback covers values written into the DOM directly
+ * (not through serializeHiddenValue) — hosts poking the input by hand.
  */
 export declare function deserializeHiddenValue(raw: string): any;
+/**
+ * Read an input's value the way typed extraction reports it — the DOM
+ * scrapers feeding enableIf (extractDOMValue, extractRootFormData) must
+ * agree with getFormData() for SCALAR fields, or a condition flips on the
+ * keystroke and is corrected only by the debounced pass (visible flicker):
+ * empty scalar -> null, number/range -> number (rounded per data-decimals),
+ * checkbox -> boolean, data-hidden-field -> JSON. Radio stays with the
+ * callers (needs a :checked query against a scope). Composite fields (file,
+ * table, richinput) extract arrays/objects that no single input carries —
+ * the parity guarantee does not extend to them.
+ */
+export declare function readTypedInputValue(input: HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement): any;
 /**
  * Create a hidden input element for a hidden form field.
  */

package/dist/types/utils/styles.d.ts

@@ -1,11 +1,16 @@
 import type { State } from "../types/index.js";
 /**
- * Strip the `.error-message` node paired with an input by id convention
- * (markValidity creates `error-${input.name}` across text/select/slider/
- * colour/switcher). Called from updateField paths so a programmatic update
- * to a valid value clears any stale error surface left over from the
- * previous validation pass — otherwise the field stays visibly "invalid"
- * until the next validate cycle.
+ * Mark an input's validity: toggle the `invalid` class/title and create,
+ * update or remove the paired `.error-message` node. Shared by every scalar
+ * component's validator — this used to be six near-identical copies, each
+ * with its own `error-${Math.random()}` fallback id.
+ */
+export declare function markFieldValidity(input: HTMLElement | null, errorMessage: string | null): void;
+/**
+ * Strip the `.error-message` node paired with an input. Called from
+ * updateField paths so a programmatic update to a valid value clears any
+ * stale error surface left over from the previous validation pass —
+ * otherwise the field stays visibly "invalid" until the next validate cycle.
  */
 export declare function clearFieldError(input: HTMLElement): void;
 /**
@@ -53,8 +58,9 @@ export declare function ensureThemingHooks(doc: Document): void;
  * where width hasn't moved — otherwise our own height writes would feed back
  * into the observer.
  */
-export declare function applyAutoExpand(textarea: HTMLTextAreaElement, options?: {
+export declare function applyAutoExpand(textarea: HTMLTextAreaElement, options: {
     minRows?: number;
+    observers: Set<ResizeObserver>;
 }): void;
 /**
  * Enforce single-line semantics on a textarea: block the Enter key and

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.5.3",
+  "version": "0.6.4",
   "description": "A reusable JSON schema form builder library",
   "main": "./dist/cjs/index.cjs",
   "module": "./dist/esm/index.js",