@dmitryvim/form-builder 0.5.4 → 0.7.0

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

@@ -2,13 +2,6 @@ import type { ContainerElement, RenderContext, ComponentContext, ValidationResul
 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;
 /**
  * Validate container field and return extracted value with errors
  */

package/dist/types/components/file/dom.d.ts

@@ -1,17 +1,29 @@
 import type { State } from "../../types/state.js";
+import type { ValidityScope } from "../../utils/styles.js";
 /**
  * Create a base square tile element. Sizing comes from CSS — `.fb-tile` and
  * its descendants resolve aspect-ratio/dimensions via the theme variables.
  */
 export declare function createFileTile(): HTMLElement;
 /**
- * Show an inline error message below the nearest [data-files-wrapper] ancestor.
+ * Who raised a file field's message. "action": an upload or library pick;
+ * "limit": the render-owned over-limit notice; "validation": a validation
+ * pass.
  */
-export declare function showFileError(container: HTMLElement, message: string): void;
+export type FileErrorKind = "action" | "limit" | "validation";
 /**
- * Remove any inline file error message below the nearest [data-files-wrapper] ancestor.
+ * Show an inline error message below the nearest [data-files-wrapper]
+ * ancestor. Only an "action" message — the direct result of the user's
+ * upload or pick — is announced as an alert.
  */
-export declare function clearFileError(container: HTMLElement): void;
+export declare function showFileError(container: HTMLElement, message: string, state: State, kind?: FileErrorKind): void;
+/**
+ * Remove the inline file error message of `kind` below the nearest
+ * [data-files-wrapper] ancestor; a message of another kind stays.
+ */
+export declare function clearFileError(container: HTMLElement, kind?: FileErrorKind): void;
+/** Validation's write into the slot, under the shared mark decision. */
+export declare function markFileValidity(wrapper: HTMLElement, message: string | null, scope: ValidityScope): void;
 /**
  * Render (or replace) a delete-overlay with a centred "Delete" button on a tile.
  * Used by the single-file edit-mode path.

package/dist/types/components/file/render-edit.d.ts

@@ -6,7 +6,6 @@ export interface RenderPillsOptions {
     state: State;
     onRemove: ((rid: string) => void) | null;
     hint?: string;
-    countInfo?: string;
     maxCount?: number;
     isReadonly?: boolean;
     onLibraryPick?: (() => void) | null;
@@ -15,7 +14,9 @@ export interface RenderPillsOptions {
 }
 export declare function renderResourcePills(opts: RenderPillsOptions): void;
 export declare function renderFileElementEdit(element: FileElement, ctx: RenderContext, wrapper: HTMLElement, pathKey: string): void;
-/** Legacy `files` element — multi-file with no upper bound. */
-export declare function renderFilesElementEdit(element: FilesElement, ctx: RenderContext, wrapper: HTMLElement, pathKey: string): void;
-/** `file` element with `multiple: true` — multi-file honouring maxCount. */
-export declare function renderMultipleFileElementEdit(element: FileElement, ctx: RenderContext, wrapper: HTMLElement, pathKey: string): void;
+/**
+ * Multi-file edit-mode renderer for both the legacy `files` element and the
+ * `file` type with `multiple: true` — they behave identically, `maxCount`
+ * included.
+ */
+export declare function renderMultiFileElementEdit(element: FileElement | FilesElement, ctx: RenderContext, wrapper: HTMLElement, pathKey: string): void;

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,9 +47,10 @@ 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
@@ -122,15 +126,43 @@ export declare class FormBuilderInstance {
      */
     renderForm(root: HTMLElement, schema: Schema, prefill?: Record<string, any>, actions?: ExternalAction[]): void;
     /**
-     * Validate form and extract data
-     * This is a complete copy of the validateForm logic from form-builder.ts
-     * but uses instance state instead of global state
+     * Validate the form and extract its data. `skipValidation` is the draft
+     * contract of saveDraft() and the onChange payload: marks are only
+     * refreshed or cleared, and the result reports `valid: true, errors: []`.
      */
     validateForm(skipValidation?: boolean): FormDataResult;
     /**
-     * Get form data
+     * Run every rule and return the real result. `marks` decides only what is
+     * painted: "full" raises and clears marks and records reported fields;
+     * "draft" refreshes or clears marks of reported fields and raises none
+     * (see ValidityScope in utils/styles.ts).
+     */
+    private runValidation;
+    /**
+     * Read the form: every rule runs and the result is the real
+     * `{valid, errors, data}`. Safe to poll — it never paints a new error
+     * mark (so a pristine form never turns red), it only refreshes or clears
+     * marks that showErrors()/submitForm() drew, and a repeated call on
+     * unchanged state touches no DOM at all.
      */
     getFormData(): FormDataResult;
+    /**
+     * Paint every validation error next to its field (and clear marks of
+     * fields that are now valid), then return the same result as
+     * getFormData(). Call it when the user asks to submit, followed by
+     * focusFirstError() to take them to the first problem.
+     */
+    showErrors(): FormDataResult;
+    /**
+     * Focus the first field marked invalid, in DOM order, and scroll it into
+     * view. A marked group (container, multi-value field, file field) gets
+     * focus on its first focusable control, else on the group itself.
+     * Does not validate: marks are drawn by showErrors() (or submitForm()),
+     * so call showErrors() first. Fields hidden by enableIf are skipped, as is
+     * any field that cannot take focus (e.g. inside a hidden slide).
+     * @returns true only when focus actually landed on an invalid field
+     */
+    focusFirstError(): boolean;
     /**
      * Submit form with validation
      */
@@ -139,6 +171,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
@@ -191,5 +230,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

@@ -13,8 +13,34 @@ export interface ComponentContext {
     instance: FormBuilderInstance;
     /** Path prefix for nested fields */
     path: string;
-    /** Skip validation checks (for draft mode) */
-    skipValidation?: boolean;
+    /**
+     * Draft marking (getFormData, debounced onChange, saveDraft): every rule
+     * runs, but only fields a full pass (showErrors, submitForm) reported may
+     * be marked. Affects painting only, never the returned errors. See
+     * ValidityScope in utils/styles.ts.
+     */
+    draftMarks?: boolean;
+    /**
+     * The element being validated is readonly (itself, form-wide, or through a
+     * readonly ancestor container): its errors are reported, never marked.
+     */
+    readonly?: 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;
+        inheritedReadonly?: boolean;
+    }, 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

@@ -1,6 +1,16 @@
 import type { Schema, ExternalAction, Element } from "./schema.js";
 import type { Config, ResourceMetadata } from "./config.js";
 export interface State {
+    /** `inst-{timestamp}-{random}`; prefixes ids of nodes the instance creates. */
+    instanceId: string;
+    /** Sequence for instance-unique ids of nodes the instance creates. */
+    domIdCounter: number;
+    /**
+     * Marked elements a full validation pass reported invalid. Draft passes
+     * (debounced onChange, saveDraft) may only raise marks for these — see
+     * ValidityScope in utils/styles.ts.
+     */
+    reportedInvalid: WeakSet<HTMLElement>;
     schema: Schema | null;
     formRoot: HTMLElement | null;
     resourceIndex: Map<string, ResourceMetadata>;
@@ -13,6 +23,13 @@ export interface State {
     syntheticElementIds: WeakMap<Element, string>;
     /** Counter for generating unique synthetic IDs. */
     syntheticElementIdCounter: number;
+    /**
+     * Replaces the file list of an edit-mode multi-file field, keyed by its
+     * [data-files-wrapper] element. setFormData/updateField must go through the
+     * field's own list — writing only the DOM attribute was reverted by the next
+     * add/remove, which re-serializes that list.
+     */
+    multiFileSetters: WeakMap<HTMLElement, (resourceIds: string[]) => void>;
     /**
      * Pending MutationObservers from setupEnableIfListeners that are waiting for a
      * dependency input to appear in the DOM. They must be disconnected on destroy()
@@ -23,6 +40,14 @@ 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

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

@@ -47,11 +47,16 @@ 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.
- * null/undefined → "", everything else → JSON.
+ * 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;
 /**
@@ -62,6 +67,18 @@ export declare function serializeHiddenValue(value: any): string;
  * (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,13 +1,79 @@
 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.
+ * What a validation pass may change on screen. A full pass (showErrors,
+ * submitForm) raises and clears marks and records each field it reported
+ * invalid. A draft pass (`draftMarks`: getFormData, the debounced onChange,
+ * saveDraft) raises, refreshes or clears marks only for fields a full pass
+ * reported — polling or typing must not light up fields the user has not
+ * submitted — and still clears any mark whose field became valid. Every
+ * write below is skipped when the DOM already holds the value, so a
+ * repeated pass on unchanged state produces no mutation records (hosts
+ * poll getFormData() from MutationObservers). A readonly field
+ * (`readonly`) is never marked: the user could not fix it. A field that
+ * enableIf hides and shows again is re-rendered as a new element and so
+ * comes back unmarked until the next full pass — intended: it reappears
+ * clean.
+ * ComponentContext satisfies this shape.
+ */
+export interface ValidityScope {
+    state: State;
+    draftMarks?: boolean;
+    readonly?: boolean;
+}
+/**
+ * The single mark decision shared by input, field and file marks: the
+ * message to draw, null to clear, or undefined to leave `target` as it is.
+ * Reported fields are tracked by their marked element rather than by path:
+ * chip rows renumber their names on removal, which would hand a path-keyed
+ * flag to a neighbouring row.
+ */
+export declare function resolveMark(target: HTMLElement, message: string | null, scope: ValidityScope): string | null | undefined;
+/** Several rule messages of one field, shown as one line. */
+export declare function joinErrorMessages(messages: string[]): string | null;
+/**
+ * Error node shared by input, field and file marks. The id is
+ * instance-prefixed so aria-describedby cannot resolve into another form on
+ * the page, even one loaded from a second copy of the bundle. No live-region
+ * role: a validation message is reached through aria-describedby, and only
+ * the direct result of a user action is announced (see showFileError).
+ */
+export declare function createErrorNode(state: State, className: string): HTMLElement;
+/** setAttribute, skipped when unchanged (a same-value write still notifies observers). */
+export declare function setAttr(el: Element, name: string, value: string): void;
+/** Point `target` at `node` through aria-describedby, once. */
+export declare function linkDescription(target: HTMLElement, node: HTMLElement): void;
+/** Flag `target` invalid and point it at `node` (null = invalid without text). */
+export declare function setInvalidMark(target: HTMLElement, node: HTMLElement | null, state: State): void;
+/**
+ * Drop the invalid state (aria-invalid and what exposeAsGroup added) but
+ * keep any description link — for a notice that is not a field state.
+ */
+export declare function unsetInvalidState(target: HTMLElement): void;
+/** Undo setInvalidMark and remove `node`; attributes a host set stay. */
+export declare function clearInvalidMark(target: HTMLElement, node: HTMLElement | null): void;
+/**
+ * Mark an input's validity: toggle `invalid`/title/aria-invalid 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, scope: ValidityScope): void;
+/**
+ * Clear an input's mark entirely. 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;
+/**
+ * Field-level counterpart of markFieldValidity for rules that belong to the
+ * field as a whole — item counts of multi-value fields and containers, table
+ * and richinput rules. The mark sits on the element whose `data-field-path`
+ * is `fieldPath` — the `.fb-field-wrapper` — with its message as the
+ * wrapper's last child. A field hidden by enableIf (its wrapper, or the
+ * placeholder that replaced it) is not marked.
+ */
+export declare function markFieldGroupValidity(scopeRoot: HTMLElement, fieldPath: string, errorMessage: string | null, scope: ValidityScope): void;
 /**
  * Shared trash-can icon used by every per-item remove button (multi-text
  * chips, multi-container items, etc.). Stays as one inline SVG so a single
@@ -23,6 +89,7 @@ export declare const BIN_ICON_SVG = "<svg width=\"14\" height=\"14\" viewBox=\"0
  * - `[data-fb-slide-card]` — items inside `container.displayMode:"slides"`
  * - `[data-fb-label-row]`  — every standard field-label container
  * - `.fb-prefill-hint`     — schema-driven prefill suggestion pills
+ * - `[aria-invalid]`       — controls marked invalid by validation
  *
  * Idempotent via a flag attribute on the document head.
  */
@@ -53,8 +120,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/dist/types/utils/validation.d.ts

@@ -1,3 +1,17 @@
+import type { ComponentContext, Element } from "../types/index.js";
 import type { State } from "../types/state.js";
+/**
+ * required / minCount / maxCount over a field's `count` items. The message
+ * keys differ per field family: files say "files", everything else "items".
+ */
+export declare function countRuleMessages(element: Element, count: number, state: State, keys?: {
+    min: string;
+    max: string;
+}): string[];
+/**
+ * Count rules of a multi-value field or container over its `filledCount`
+ * items: pushes "path: message" errors and marks the field with all of them.
+ */
+export declare function validateItemCount(element: Element, key: string, filledCount: number, context: ComponentContext, errors: string[]): void;
 export declare function makeFieldHint(element: any, state: State): string;
 export declare function validateSchema(schema: any): string[];

package/package.json

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