@dmitryvim/form-builder 0.2.34 → 0.3.1

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

@@ -0,0 +1,4 @@
+import type { BooleanElement, RenderContext, ComponentContext, ValidationResult, Element } from "../types/index.js";
+export declare function renderBooleanElement(element: BooleanElement, ctx: RenderContext, wrapper: HTMLElement, pathKey: string): void;
+export declare function validateBooleanElement(element: Element, key: string, context: ComponentContext): ValidationResult;
+export declare function updateBooleanField(_element: Element, fieldPath: string, value: any, context: ComponentContext): void;

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

@@ -1,27 +1,51 @@
 import type { FormBuilderInstance } from "../../instance/FormBuilderInstance.js";
 import type { State } from "../../types/state.js";
 import type { FileElement, FilesElement } from "../../types/index.js";
+import type { BatchCoordinator } from "./upload.js";
+export interface HandleLibraryPickMultiOptions {
+    state: State;
+    element: FileElement | FilesElement;
+    /** The `[data-files-wrapper]` element — used as the error-message target. */
+    wrapper: HTMLElement;
+    /** Bracket-notation field path (e.g. "slides[2].image"). */
+    fieldPath: string;
+    /** The mutable live array of current resource IDs (mutated in-place). */
+    resourceIds: string[];
+    /** Maximum files allowed (Infinity = no limit). */
+    maxCount: number;
+    /** Re-render callback (same role as in setupFilesPickerHandler). */
+    updateCallback: () => void;
+    instance: FormBuilderInstance;
+    /**
+     * Coordinator shared with the upload handlers. Used to read the true
+     * occupied count (committed + in-flight), commit picked rids instantly,
+     * and detect whether peer batches are still uploading so we can avoid a
+     * full rebuild that would wipe their in-flight tiles.
+     */
+    coordinator: BatchCoordinator;
+    /** The grid container (`.files-list`) where picked tiles are appended when peer batches are in flight. */
+    list: HTMLElement;
+    /** Builds the per-rid preview tile (same callback used by uploadBatch's in-place swap). */
+    buildSuccessTile: (rid: string) => HTMLElement;
+}
 /**
  * Handle a library pick action for a MULTI-file field.
  *
- * End-to-end handler (mirrors upload.ts pattern):
- *   1. Calls pickExistingFiles with context
- *   2. Validates, deduplicates, enforces slot limit
- *   3. Registers in resourceIndex, mutates resourceIds array
- *   4. Updates data-resource-ids attribute
- *   5. Calls updateCallback() to re-render tiles
- *   6. Fires triggerOnChange
+ * Goes through the same coordinator queue as uploadBatch — `beginBatch`
+ * claims an ordinal at the moment of click, `setResults` stages the picked
+ * rids at that ordinal, and `end` releases the reservation. Library tiles
+ * are appended to the DOM right away so the user sees them, but their rids
+ * only land in resourceIds once every earlier-started batch has also
+ * committed. This is what keeps the final form data in user-selection order
+ * when a library pick is interleaved with an in-flight upload batch — the
+ * upload's ordinal drains first regardless of which one settled later.
  *
- * @param state           Form builder state
- * @param element         File / FilesElement schema definition
- * @param wrapper         The [data-files-wrapper] element
- * @param fieldPath       Bracket-notation field path (e.g. "slides[2].image")
- * @param resourceIds     The mutable live array of current resource IDs (mutated in-place)
- * @param maxCount        Maximum files allowed (Infinity = no limit)
- * @param updateCallback  Re-render callback (same pattern as upload.ts)
- * @param instance        FormBuilderInstance (for onChange events)
+ * `getOccupiedCount` (committed + in-flight) gates both the pre-picker
+ * `remainingSlots` and the post-picker `freshRemaining` so a host UI can't
+ * accept more files than maxCount even with a concurrent upload reserving
+ * slots invisibly.
  */
-export declare function handleLibraryPickMulti(state: State, element: FileElement | FilesElement, wrapper: HTMLElement, fieldPath: string, resourceIds: string[], maxCount: number, updateCallback: () => void, instance: FormBuilderInstance): Promise<void>;
+export declare function handleLibraryPickMulti(opts: HandleLibraryPickMultiOptions): Promise<void>;
 /**
  * Handle a library pick action for a SINGLE-file field.
  *

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

@@ -31,5 +31,114 @@ export interface UploadBatchFailure {
     file: File;
     error: Error;
 }
-export declare function setupFilesDropHandler(filesContainer: HTMLElement, resourceIds: string[], state: State, updateCallback: () => void, constraints: FileUploadConstraints, pathKey?: string, instance?: FormBuilderInstance | null): void;
-export declare function setupFilesPickerHandler(filesPicker: HTMLInputElement, resourceIds: string[], state: State, updateCallback: () => void, constraints: FileUploadConstraints, pathKey?: string, instance?: FormBuilderInstance | null): void;
+export interface UploadBatchOptions {
+    /** Files that have already passed extension / mime / size / count filtering. */
+    accepted: File[];
+    /** Container that hosts the tile grid (`.files-list`); receives uploading tiles. */
+    listEl: HTMLElement | null;
+    state: State;
+    /**
+     * Whether to hide the add-tile while this batch is in flight. Computed by
+     * the caller from `coordinator.getOccupiedCount() >= maxCount` *after*
+     * reserving slots, so concurrent batches that together saturate maxCount
+     * still hide the trigger.
+     */
+    shouldHideAddTile: boolean;
+    /**
+     * Builds the real preview tile to swap in-place when each upload resolves.
+     * When omitted, the placeholder is simply removed and the file only becomes
+     * visible after the caller re-renders the grid — used by paths that don't
+     * own a per-rid render strategy.
+     */
+    buildSuccessTile?: (rid: string) => HTMLElement;
+    /**
+     * Runs once after add-tile visibility is settled but before any upload
+     * promise starts. Hook for the caller to dispose of empty placeholders and
+     * the placeholder ResizeObserver — they would otherwise compete with the
+     * uploading tiles and the observer would immediately re-add removed slots.
+     */
+    prepareForUpload?: () => void;
+}
+export interface UploadBatchResult {
+    failures: UploadBatchFailure[];
+    /**
+     * One slot per `accepted[i]`, filled with the uploaded resource id when its
+     * upload succeeded and `null` when it failed. Callers commit these into
+     * `resourceIds` themselves so they can filter out IDs the user removed
+     * mid-batch (see `BatchCoordinator.wasRemovedDuringBatch`).
+     */
+    orderedIds: (string | null)[];
+}
+/**
+ * Owns the cross-batch invariants the handlers can't enforce on their own:
+ * tracking how many slots are reserved by in-flight uploads, preserving
+ * user-selection order across concurrent batches that settle out-of-start
+ * order, filtering out resources the user removed before a batch settles,
+ * and gating the final grid rebuild until the last concurrent batch finishes.
+ *
+ * Both the drop and picker handlers share a single coordinator instance per
+ * field so that batches started while another batch is still pending can't
+ * bypass maxCount, scramble the form-data order, or have their tiles wiped
+ * by a peer's rebuild.
+ */
+export interface BatchCoordinator {
+    /** Settled resource count plus in-flight reservations. */
+    getOccupiedCount: () => number;
+    /**
+     * Snapshot of every rid currently in the system: committed in resourceIds
+     * plus rids staged behind an earlier ordinal awaiting drain. Used by the
+     * library picker to dedupe against — committed-only would let a staged rid
+     * be re-picked and committed twice.
+     */
+    getAllKnownRids: () => string[];
+    /** True if any batches are currently in flight (used to gate full rebuilds). */
+    hasInFlightBatches: () => boolean;
+    /** True if `rid` was removed during the current in-flight period. */
+    wasRemovedDuringBatch: (rid: string) => boolean;
+    /**
+     * Reserve N slots and begin a new batch. The returned handle is the only
+     * way to stage results and release the reservation — staging through a
+     * handle keyed by batch ordinal is what guarantees start-order commits
+     * even when batches settle out of order. Both the upload path and the
+     * library picker go through this so they share the same ordering queue.
+     */
+    beginBatch: (count: number) => BatchHandle;
+}
+/**
+ * Per-batch handle. `setResults` stages the batch's `orderedIds` keyed by its
+ * start ordinal; the coordinator then commits the contiguous prefix of
+ * already-settled batches into the field's resourceIds. `end` releases the
+ * reservation and reports whether no other batches remain in flight.
+ */
+export interface BatchHandle {
+    setResults: (orderedIds: (string | null)[]) => void;
+    end: () => {
+        wasLast: boolean;
+    };
+}
+/**
+ * Shared inputs for both drop and picker handlers — the only difference is
+ * which DOM event source feeds files into the batch upload.
+ */
+export interface MultiFileHandlerOptions {
+    resourceIds: string[];
+    state: State;
+    /** Re-renders the grid after the *last* batch settles (counter, placeholders, etc.). */
+    updateCallback: () => void;
+    constraints: FileUploadConstraints;
+    pathKey?: string;
+    instance?: FormBuilderInstance | null;
+    /** Forwarded into uploadBatch — builds the per-rid preview tile. */
+    buildSuccessTile?: (rid: string) => HTMLElement;
+    /** Forwarded into uploadBatch — runs once before any upload starts. */
+    prepareForUpload?: () => void;
+    coordinator: BatchCoordinator;
+}
+export interface SetupFilesDropHandlerOptions extends MultiFileHandlerOptions {
+    filesContainer: HTMLElement;
+}
+export declare function setupFilesDropHandler(opts: SetupFilesDropHandlerOptions): void;
+export interface SetupFilesPickerHandlerOptions extends MultiFileHandlerOptions {
+    filesPicker: HTMLInputElement;
+}
+export declare function setupFilesPickerHandler(opts: SetupFilesPickerHandlerOptions): void;

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

@@ -1,6 +1,17 @@
 import type { TextElement, RenderContext, ComponentContext, ValidationResult } from "../types/index.js";
-export declare function createCharCounter(element: TextElement, input: HTMLInputElement | HTMLTextAreaElement, isTextarea?: boolean): HTMLElement;
+export declare function createCharCounter(element: TextElement, input: HTMLInputElement | HTMLTextAreaElement): HTMLElement;
 export declare function renderTextElement(element: TextElement, ctx: RenderContext, wrapper: HTMLElement, pathKey: string): void;
+/**
+ * `text.multiple` is always rendered as a vertical list of chip rows:
+ *   [● input          🗑]
+ * Each chip = colored dot marker + single-line input + trash button that
+ * fades in on hover. Tint and dot color are pure CSS via --fb-chip-* vars;
+ * per-field overrides go through `[data-field-key="..."]` (see theming.md).
+ *
+ * Why no character-counter / no soft-wrap textarea like single-text:
+ *  - chip rows are deliberately one-line; long values are unusual here.
+ *  - min/max length still validate at field level via `validateTextElement`.
+ */
 export declare function renderMultipleTextElement(element: TextElement, ctx: RenderContext, wrapper: HTMLElement, pathKey: string): void;
 /**
  * Validate text input field and return extracted value with errors

package/dist/types/index.d.ts

@@ -5,7 +5,7 @@
  */
 import { FormBuilderInstance } from "./instance/FormBuilderInstance.js";
 import { validateSchema } from "./utils/validation.js";
-export type { SelectOption, ElementAction, BaseElement, TextElement, TextareaElement, NumberElement, SelectElement, FileElement, FilesElement, ContainerElement, GroupElement, MarkdownElement, RichInputElement, Element, Schema, ExternalAction, FormData, RenderContext, Translations, Locale, Config, ResourceMetadata, PickedResource, State, } from "./types/index.js";
+export type { SelectOption, ElementAction, BaseElement, TextElement, TextareaElement, NumberElement, SelectElement, BooleanElement, FileElement, FilesElement, ContainerElement, GroupElement, MarkdownElement, RichInputElement, Element, Schema, ExternalAction, FormData, RenderContext, Translations, Locale, Config, ResourceMetadata, PickedResource, State, } from "./types/index.js";
 export type { Theme } from "./styles/theme.js";
 export { defaultTheme, exampleThemes } from "./styles/theme.js";
 /**

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

@@ -60,7 +60,20 @@ export declare class FormBuilderInstance {
      */
     registerAction(action: ExternalAction): void;
     /**
-     * Find the DOM element corresponding to a field path (instance-scoped)
+     * Find the DOM element corresponding to a field path (instance-scoped).
+     *
+     * Strategy:
+     *  1. Try a `[name="…"]` lookup first — works for any field that renders
+     *     an input/hidden with the path as its name, in either mode. Some
+     *     readonly renderers still emit a hidden input (boolean, switcher),
+     *     so this path must run regardless of `state.config.readonly`. A
+     *     prior version gated this on edit mode only, which made
+     *     `updateField` / `setFormData` silently miss readonly boolean
+     *     fields whose component also opts out of the standard label row
+     *     (`ownsLabel: true`).
+     *  2. If no input matched, fall back to locating the field wrapper by
+     *     its visible label text — needed for readonly previews that don't
+     *     emit any `name=` attribute (e.g. file/markdown previews).
      */
     private findFormElementByFieldPath;
     /**

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

@@ -1,17 +1,41 @@
 export interface Theme {
     primaryColor: string;
     primaryHoverColor: string;
+    /** Light tint of primary — used for chip backgrounds, hover surfaces, focused-state backgrounds. */
+    primarySoftColor: string;
+    /** Slightly stronger tint of primary — used for chip borders and hovered soft surfaces. */
+    primarySoftHoverColor: string;
     errorColor: string;
     errorHoverColor: string;
     successColor: string;
+    /** Secondary accent color (e.g. amber) used for highlights distinct from primary. */
+    accentColor: string;
+    /** Soft tint of accent for chip/badge backgrounds. */
+    accentSoftColor: string;
+    /** Border color paired with accentSoftColor. */
+    accentBorderColor: string;
+    /** Text color used on accent-tinted surfaces. */
+    accentTextColor: string;
     borderColor: string;
     borderHoverColor: string;
     borderFocusColor: string;
+    /** Stronger border for inputs/dropzones that need more contrast. */
+    borderStrongColor: string;
     backgroundColor: string;
     backgroundHoverColor: string;
     backgroundReadonlyColor: string;
+    /** Page-level background (the surface the form card sits on). */
+    pageBackgroundColor: string;
+    /** Soft tinted surface (mix of primary and white) for inset blocks. */
+    surfaceSoftColor: string;
+    /** Subtle tinted surface for very-light backgrounds. */
+    surfaceTintColor: string;
     textColor: string;
     textSecondaryColor: string;
+    /** Lighter text tone (between secondary and disabled). */
+    textMutedColor: string;
+    /** Faintest text tone, used for small uppercase group labels. */
+    textFaintColor: string;
     textPlaceholderColor: string;
     textDisabledColor: string;
     buttonBgColor: string;
@@ -31,6 +55,12 @@ export interface Theme {
     inputPaddingX: string;
     inputPaddingY: string;
     borderRadius: string;
+    /** Smaller corner radius (e.g. for chips and compact controls). */
+    borderRadiusSmall: string;
+    /** Larger corner radius for cards and dropzones. */
+    borderRadiusLarge: string;
+    /** Extra-large corner radius for section cards. */
+    borderRadiusXLarge: string;
     borderWidth: string;
     fontSize: string;
     fontSizeSmall: string;
@@ -38,10 +68,26 @@ export interface Theme {
     fontFamily: string;
     fontWeightNormal: string;
     fontWeightMedium: string;
+    /** Line height applied to text inputs and textarea/chip inputs. */
+    lineHeight: string;
+    /** Subtle card shadow. */
+    shadowCard: string;
+    /** Elevated popover/hover shadow. */
+    shadowPopover: string;
     focusRingWidth: string;
     focusRingColor: string;
     focusRingOpacity: string;
     transitionDuration: string;
+    slideCardBg: string;
+    slideCardShadow: string;
+    slideCardRadius: string;
+    /** Minimum card height — useful when content varies wildly across slides. */
+    slideCardMinHeight: string;
+    /** Inner padding of each slide card. Default sits a bit roomier than stack-mode. */
+    slideCardPadding: string;
+    labelSectionFontSize: string;
+    labelSectionLetterSpacing: string;
+    labelSectionTextTransform: string;
 }
 export declare const defaultTheme: Theme;
 /**
@@ -60,4 +106,5 @@ export declare const exampleThemes: {
     default: Theme;
     dark: Theme;
     klein: Theme;
+    picaz: Theme;
 };

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

@@ -49,4 +49,11 @@ export type ComponentUpdater = (element: Element, fieldPath: string, value: any,
 export interface ComponentOperations {
     validate: ComponentValidator;
     update: ComponentUpdater;
+    /**
+     * Set to true when the component renders its own title/label inline
+     * (e.g. boolean's `.toggle-row` puts the label next to the pill). When
+     * true, the main dispatcher skips `createLabelContainer` and lets the
+     * component own the entire field row.
+     */
+    ownsLabel?: boolean;
 }

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

@@ -1,4 +1,4 @@
-export type { SelectOption, ElementAction, EnableCondition, BaseElement, TextElement, TextareaElement, NumberElement, SelectElement, SwitcherElement, FileElement, FilesElement, ColourElement, SliderElement, ContainerElement, GroupElement, TableElement, TableMerge, TableData, RichInputElement, MarkdownElement, Element, Schema, ExternalAction, FormData, RenderContext, } from "./schema.js";
+export type { SelectOption, ElementAction, EnableCondition, BaseElement, TextElement, TextareaElement, NumberElement, SelectElement, SwitcherElement, BooleanElement, FileElement, FilesElement, ColourElement, SliderElement, ContainerElement, GroupElement, TableElement, TableMerge, TableData, RichInputElement, MarkdownElement, Element, Schema, ExternalAction, FormData, RenderContext, } from "./schema.js";
 export type { Translations, Locale, Config, ResourceMetadata, PickedResource, } from "./config.js";
 export type { State } from "./state.js";
 export type { ComponentContext, ValidationResult, ComponentValidator, ComponentUpdater, ComponentOperations, } from "./component-operations.js";

package/dist/types/types/schema.d.ts

@@ -1,6 +1,20 @@
 export interface SelectOption {
     value: string;
     label: string;
+    /**
+     * Optional secondary line under the label.
+     * Used by `switcher` to render preset-pill buttons (icon + name + subtitle).
+     * Ignored by `select` (native <option> shows label only).
+     */
+    subtitle?: string;
+    /**
+     * Optional image URL rendered to the left of the label.
+     * Accepts any `<img src>` value — typically a small SVG/PNG icon, or a
+     * `data:image/...;base64,...` URI for inline assets without a network round-trip.
+     * Used by `switcher` to show a visual preview (e.g. an aspect-ratio
+     * sketch for size presets). Ignored by `select`.
+     */
+    iconUrl?: string;
 }
 export interface ElementAction {
     key: string;
@@ -70,6 +84,12 @@ export interface NumberElement extends BaseElement {
     minCount?: number;
     maxCount?: number;
     addLabel?: string;
+    /**
+     * When true, renders a compact pill: `−` button, narrow input, `+` button.
+     * Native browser spinner arrows are hidden; range-hint chip is hidden.
+     * Clamped to `min`/`max`; uses `step` (default 1).
+     */
+    stepper?: boolean;
 }
 export interface SelectElement extends BaseElement {
     type: "select";
@@ -151,6 +171,25 @@ export interface SwitcherElement extends BaseElement {
     maxCount?: number;
     addLabel?: string;
 }
+/**
+ * Boolean / toggle element. Renders as a `.toggle-row` card: pill switch
+ * on the left, label + hint stacked to the right. Form data value is a
+ * real boolean (`true` / `false`).
+ *
+ * Field-text layout (matches the design reference):
+ *  - `label`    → bold title (t1) inside the row, replacing the standard
+ *                 label that other field types render above.
+ *  - `hint`     → grey subtitle (t2) directly under the title.
+ *  - `description` → text shown via a small info-icon tooltip next to the
+ *                    title (use a longer explanation here; keep `hint`
+ *                    short).
+ *
+ * `required` is ignored — `false` is a valid value.
+ */
+export interface BooleanElement extends BaseElement {
+    type: "boolean";
+    default?: boolean;
+}
 export interface GroupElement extends BaseElement {
     type: "group";
     elements: Element[];
@@ -229,7 +268,7 @@ export interface RichInputElement extends BaseElement {
     filesKey?: string;
     flatOutput?: boolean;
 }
-export type Element = TextElement | TextareaElement | NumberElement | SelectElement | SwitcherElement | FileElement | FilesElement | HiddenElement | ColourElement | SliderElement | ContainerElement | GroupElement | TableElement | RichInputElement | MarkdownElement;
+export type Element = TextElement | TextareaElement | NumberElement | SelectElement | SwitcherElement | BooleanElement | FileElement | FilesElement | HiddenElement | ColourElement | SliderElement | ContainerElement | GroupElement | TableElement | RichInputElement | MarkdownElement;
 export interface Schema {
     version?: string;
     elements: Element[];

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

@@ -1,4 +1,51 @@
 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.
+ */
+export declare function clearFieldError(input: HTMLElement): 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
+ * style sweep affects all remove affordances at once.
+ */
+export declare const BIN_ICON_SVG = "<svg width=\"14\" height=\"14\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"1.8\" stroke-linecap=\"round\" stroke-linejoin=\"round\" aria-hidden=\"true\"><polyline points=\"3 6 5 6 21 6\"/><path d=\"M19 6v14a2 2 0 0 1-2 2H7a2 2 0 0 1-2-2V6\"/><path d=\"M10 11v6\"/><path d=\"M14 11v6\"/><path d=\"M8 6V4a2 2 0 0 1 2-2h4a2 2 0 0 1 2 2v2\"/></svg>";
+/**
+ * Inject the theming-hook stylesheet: rules that map `data-fb-*` attributes
+ * to their CSS-variable counterparts. Without this, themes that set
+ * `Theme.slideCardBg` etc. have no effect — defaults live in `defaultTheme`,
+ * so the rules below pick them up automatically for every form instance.
+ *
+ * - `[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
+ *
+ * Idempotent via a flag attribute on the document head.
+ */
+export declare function ensureThemingHooks(doc: Document): void;
+/**
+ * Make a textarea grow vertically with its content. Starts at the height
+ * required by the current value; on each input, sets height to scrollHeight
+ * plus borders.
+ *
+ * Why add borders: `scrollHeight` includes padding but not border, and our
+ * textareas use `box-sizing: border-box`. Setting `height = scrollHeight`
+ * makes the total box (border + padding + content) equal scrollHeight, which
+ * leaves the content area short by `2 * border-width` — at compact density
+ * (8px padding, 21px line-height) that's enough to clip a single line.
+ */
+export declare function applyAutoExpand(textarea: HTMLTextAreaElement): void;
+/**
+ * Enforce single-line semantics on a textarea: block the Enter key and
+ * strip newlines from pasted content. Used to render <textarea rows=1> as
+ * a soft-wrapping single-line input — text wraps visually but the value
+ * never contains a newline.
+ */
+export declare function applySingleLineMode(textarea: HTMLTextAreaElement): void;
 /**
  * Apply themed input styles to an HTMLInputElement, HTMLTextAreaElement, or HTMLSelectElement
  */

package/package.json

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