@dmitryvim/form-builder 0.3.0 → 0.3.2

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/utils/styles.d.ts

@@ -22,13 +22,36 @@ 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
  *
  * 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.
+ * 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.
+ *
+ * Deferred-layout recovery (v0.3.2):
+ * A `ResizeObserver` re-runs `resize()` whenever the textarea's content-box
+ * WIDTH changes. Two host patterns the one-shot `setTimeout(0)` below can't
+ * survive on its own:
+ *   1. Form mounted inside a still-hidden / 0-width container (e.g. inactive
+ *      tab, collapsed accordion, modal that isn't open yet). At setTimeout
+ *      firing time `scrollHeight === 0` → height collapses to ~borderY (~2px).
+ *      Once the host reveals the container, width transitions 0 → real and we
+ *      re-measure.
+ *   2. Responsive width changes (host resizes the column). Wrapped content
+ *      re-flows so the textarea grows/shrinks to fit.
+ * Loop guard: `resize()` only writes the HEIGHT, so we ignore observer fires
+ * where width hasn't moved — otherwise our own height writes would feed back
+ * into the observer.
  */
 export declare function applyAutoExpand(textarea: HTMLTextAreaElement): void;
 /**

package/package.json

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