@dmitryvim/form-builder 0.6.4 → 0.7.0

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/instance/FormBuilderInstance.d.ts

@@ -126,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
      */

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

@@ -13,8 +13,18 @@ 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
@@ -25,6 +35,7 @@ export interface ComponentContext {
      */
     validateElement?: (element: Element, ctx: {
         path: string;
+        inheritedReadonly?: boolean;
     }, customScopeRoot?: HTMLElement | null) => {
         value: any;
         spread: 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()

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

@@ -1,18 +1,79 @@
 import type { State } from "../types/index.js";
 /**
- * Mark an input's validity: toggle the `invalid` class/title and create,
+ * 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): void;
+export declare function markFieldValidity(input: HTMLElement | null, errorMessage: string | null, scope: ValidityScope): 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.
+ * 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
@@ -28,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.
  */

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.6.4",
+  "version": "0.7.0",
   "description": "A reusable JSON schema form builder library",
   "main": "./dist/cjs/index.cjs",
   "module": "./dist/esm/index.js",