@dmitryvim/form-builder 0.2.26 → 0.2.28

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

@@ -0,0 +1,62 @@
+import type { FileAccept } from "../../types/schema.js";
+export interface FileUploadConstraints {
+    maxCount: number;
+    allowedExtensions: string[];
+    allowedMimes: string[];
+    maxSize: number;
+}
+/**
+ * Extract allowed file extensions from the `accept` schema property.
+ * Returns lowercase extension strings without leading dots.
+ * Convention: this getter normalizes to lowercase; checkers assume the list is normalized.
+ */
+export declare function getAllowedExtensions(accept: FileAccept | undefined): string[];
+/**
+ * Return true if fileName's extension is in the allowed list,
+ * or if the list is empty (no restriction).
+ */
+export declare function isFileExtensionAllowed(fileName: string, allowedExtensions: string[]): boolean;
+/**
+ * Return true if a byte count is within the size limit.
+ * maxSizeMB === Infinity means no limit.
+ */
+export declare function isSizeWithinLimit(bytes: number, maxSizeMB: number): boolean;
+/**
+ * Return true if file is within the size limit.
+ * maxSizeMB === Infinity means no limit.
+ */
+export declare function isFileSizeAllowed(file: File, maxSizeMB: number): boolean;
+/**
+ * Extract allowed MIME types from the `accept` schema property.
+ * Returns empty array for the legacy string form (no mime in that form).
+ * Returns empty array when accept is undefined or has no mime key.
+ * Convention: this getter normalizes to lowercase; checkers assume the list is normalized.
+ */
+export declare function getAllowedMimes(accept: FileAccept | undefined): string[];
+/**
+ * Return true if mimeType is allowed by the allowedMimes list.
+ * Empty allowedMimes = no mime restriction → always return true.
+ * Supports wildcards (image/*, application/*, etc.).
+ * Comparison is case-insensitive per RFC 2045.
+ *
+ * Convention: allowedMimes is assumed to be pre-normalized to lowercase
+ * (by getAllowedMimes). Only mimeType (the host-provided input) is lowercased here.
+ */
+export declare function isMimeAllowed(mimeType: string, allowedMimes: string[]): boolean;
+/**
+ * Infer MIME type from a resource ID's filename extension.
+ * Returns "application/octet-stream" when the extension is unrecognised.
+ * This is the single source of truth for the extension→mime mapping used by
+ * prefill, handleInitialFileData, and the API-update path.
+ */
+export declare function inferMimeFromResourceId(resourceId: string): string;
+/**
+ * Seed resourceIndex with inferred metadata for a single resource ID.
+ * Skips IDs that already have an entry (does not overwrite authoritative data).
+ * Sets inferredFromExtension: true so that mime validation is skipped at submit time.
+ */
+export declare function seedInferredResource(resourceId: string, resourceIndex: Map<string, any>): void;
+/**
+ * Add prefill resource IDs to resourceIndex with type inferred from filename extension.
+ */
+export declare function addPrefillFilesToIndex(initialFiles: string[], resourceIndex: Map<string, any>): void;

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

@@ -0,0 +1,44 @@
+import type { State } from "../../types/state.js";
+export declare const TILE_SIZE = "160px";
+/**
+ * Create a base square tile element (TILE_SIZE × TILE_SIZE).
+ * Applies .fb-tile so theme variables control background/radius.
+ */
+export declare function createFileTile(): HTMLElement;
+/**
+ * Show an inline error message below the nearest .space-y-2 ancestor.
+ */
+export declare function showFileError(container: HTMLElement, message: string): void;
+/**
+ * Remove any inline file error message below the nearest .space-y-2 ancestor.
+ */
+export declare function clearFileError(container: HTMLElement): void;
+/**
+ * Render (or replace) a delete-overlay with a centred "Delete" button on a tile.
+ * Used by the single-file edit-mode path.
+ */
+export declare function addDeleteButton(container: HTMLElement, state: State, onDelete: () => void): void;
+/**
+ * Find the hidden <input type="file"> picker by traversing up to the
+ * nearest [data-files-wrapper] ancestor.
+ */
+export declare function findFilePicker(container: HTMLElement): HTMLInputElement | null;
+/**
+ * Build a compact uploading-state tile (spinner + filename label).
+ */
+export declare function createUploadingTile(fileName: string, state: State): HTMLElement;
+/**
+ * Ensure a .fb-tiles-wrap + .fb-add-tile scaffold exists inside `list`.
+ * When the field starts empty, the list only has a .fb-file-dropzone; this
+ * function replaces it with the tile-row layout so upload placeholders land
+ * in the correct flex container.
+ */
+export declare function ensureTilesWrap(list: HTMLElement): HTMLElement;
+/**
+ * Render a placeholder empty-container (single-file edit mode).
+ */
+export declare function setEmptyFileContainer(fileContainer: HTMLElement, state: State, hint?: string): void;
+/**
+ * Set up drag-and-drop on an element, calling dropHandler with the dropped FileList.
+ */
+export declare function setupDragAndDrop(element: HTMLElement, dropHandler: (files: FileList) => void): void;

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

@@ -0,0 +1,49 @@
+import type { FormBuilderInstance } from "../../instance/FormBuilderInstance.js";
+import type { State } from "../../types/state.js";
+import type { FileElement, FilesElement } from "../../types/index.js";
+/**
+ * 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
+ *
+ * @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)
+ */
+export declare function handleLibraryPickMulti(state: State, element: FileElement | FilesElement, wrapper: HTMLElement, fieldPath: string, resourceIds: string[], maxCount: number, updateCallback: () => void, instance: FormBuilderInstance): Promise<void>;
+/**
+ * Handle a library pick action for a SINGLE-file field.
+ *
+ * End-to-end handler (mirrors upload.ts and handleLibraryPickMulti patterns):
+ *   1. Calls pickExistingFiles with context
+ *   2. Validates the first returned resource
+ *   3. Registers in resourceIndex
+ *   4. Creates/updates the hidden input inside fileWrapper (only on success — not on cancel)
+ *   5. Calls renderCallback(resourceId) to render the tile
+ *   6. Fires triggerOnChange
+ *
+ * The hidden input is managed here (not in the caller) to mirror how
+ * handleFileSelect in upload.ts manages it, and to match the multi-file
+ * pattern where data-resource-ids is updated inside handleLibraryPickMulti.
+ *
+ * @param state          Form builder state
+ * @param element        FileElement schema definition
+ * @param container      The .file-preview-container element
+ * @param fileWrapper    The .space-y-2 wrapper that contains the hidden input
+ * @param pathKey        Field name / bracket-notation path for the hidden input
+ * @param fieldPath      Bracket-notation field path (for onChange context)
+ * @param renderCallback Called with the accepted resource ID; caller renders the tile
+ * @param instance       FormBuilderInstance (for onChange events)
+ */
+export declare function handleLibraryPickSingle(state: State, element: FileElement, container: HTMLElement, fileWrapper: HTMLElement, pathKey: string, fieldPath: string, renderCallback: (resourceId: string) => Promise<void>, instance: FormBuilderInstance): Promise<void>;

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

@@ -0,0 +1,69 @@
+import type { State } from "../../types/state.js";
+import type { ResourceMetadata } from "../../types/config.js";
+import type { FileDeps } from "./upload.js";
+export interface TileActionOptions {
+    canRemove: boolean;
+    removeHandler: (() => void) | null;
+    state: State;
+    resourceId: string;
+    fileName: string;
+    /**
+     * The resource metadata. Used both to drive capability gating (a local
+     * `meta.file` is a valid download/open source even without network handlers)
+     * and as a fallback at click time so the user can always download/open a
+     * just-uploaded file.
+     */
+    meta?: ResourceMetadata;
+}
+/**
+ * Build a horizontal row of icon-only action buttons for a file tile.
+ * Download and Open-in-new-tab are capability-gated — they're rendered only
+ * when the configured handlers (or a local meta.file) can fulfil them.
+ * Remove is rendered only in edit mode.
+ */
+export declare function createTileActions(options: TileActionOptions): HTMLElement;
+export declare function releaseLocalFileUrl(file: File | undefined | null): void;
+/**
+ * Populate a single-file edit-mode container with a file preview.
+ * Handles both local (pre-upload) Files and uploaded resource IDs.
+ */
+export declare function renderFilePreview(container: HTMLElement, resourceId: string, state: State, options?: {
+    fileName?: string;
+    isReadonly?: boolean;
+    deps?: FileDeps | null;
+}): Promise<void>;
+/**
+ * Build and return a compact 160×160 readonly tile for a single resource.
+ * Click opens the resource via getDownloadUrl / getThumbnail / downloadFile.
+ * Action icon buttons (download, open, optional remove) appear on hover.
+ */
+export declare function renderFilePreviewReadonly(resourceId: string, state: State, fileName?: string, options?: {
+    canRemove?: boolean;
+    removeHandler?: (() => void) | null;
+}): Promise<HTMLElement>;
+/**
+ * Render (or replace) the single-file edit container with a compact 160×160 tile.
+ * Called after a file is selected/uploaded, or when the field has prefill data.
+ * Mirrors renderFilePreviewReadonly but always includes a remove (✕) action button.
+ *
+ * Delegates entirely to renderFilePreviewReadonly with canRemove:true.
+ * getThumbnail (if configured) provides image/video thumbnails; otherwise the
+ * standard icon fallback is shown — same UX as the post-upload path had before.
+ *
+ * Local image files (just-uploaded, meta.file still set) are treated as uploaded
+ * resources: getThumbnail is tried first; if absent the 🖼️ icon is shown.
+ * This avoids running FileReader in single-file edit mode (consistent behaviour).
+ *
+ * Video files (local or uploaded) are NOT handled here; the caller keeps them
+ * on the old native-<video> path (see render-edit.ts and upload.ts).
+ *
+ * The outer `fileContainer` wrapper is cleared and the tile inserted as its only child.
+ * Removing the tile restores the dropzone via deps.onRemove().
+ */
+export declare function renderSingleFileEditTile(fileContainer: HTMLElement, resourceId: string, state: State, deps: FileDeps): Promise<void>;
+/**
+ * Populate a tile element with thumbnail / icon content for a resource.
+ * Used by renderResourcePills for both edit and readonly multi-file tiles.
+ * actionsEl: pre-built action button group to attach to the tile (and zoom popup).
+ */
+export declare function fillTileContent(tile: HTMLElement, rid: string, meta: ResourceMetadata | undefined, state: State, actionsEl?: HTMLElement): Promise<void>;

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

@@ -0,0 +1,18 @@
+import type { State } from "../../types/state.js";
+import type { FileElement, FilesElement, RenderContext } from "../../types/index.js";
+export { TILE_SIZE } from "./dom.js";
+export interface RenderPillsOptions {
+    container: HTMLElement;
+    rids: string[] | null;
+    state: State;
+    onRemove: ((rid: string) => void) | null;
+    hint?: string;
+    countInfo?: string;
+    maxCount?: number;
+    isReadonly?: boolean;
+    onLibraryPick?: (() => void) | null;
+}
+export declare function renderResourcePills(opts: RenderPillsOptions): void;
+export declare function renderFileElementEdit(element: FileElement, ctx: RenderContext, wrapper: HTMLElement, pathKey: string): void;
+export declare function renderFilesElementEdit(element: FilesElement, ctx: RenderContext, wrapper: HTMLElement, pathKey: string): void;
+export declare function renderMultipleFileElementEdit(element: FileElement, ctx: RenderContext, wrapper: HTMLElement, pathKey: string): void;

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

@@ -0,0 +1,23 @@
+import type { State } from "../../types/state.js";
+import type { FileElement, FilesElement, RenderContext } from "../../types/index.js";
+/**
+ * Render a compact 160×160 readonly tile for a single-file field.
+ * If no prefill: shows a styled empty placeholder.
+ */
+export declare function renderFileElementReadonly(element: FileElement, ctx: RenderContext, wrapper: HTMLElement, pathKey: string): void;
+/**
+ * Render a tile row for a readonly multi-file field.
+ *
+ * Issue 2 fix: exactly N tile elements for N files — no hidden pill stubs.
+ * The [data-files-wrapper] element carries data-resource-ids so validation
+ * can read IDs without touching the tile DOM.
+ */
+export declare function renderMultiFileReadonly(rids: string[], state: State, wrapper: HTMLElement, pathKey: string, marginTop?: string): void;
+/**
+ * Render legacy `files` element in readonly mode.
+ */
+export declare function renderFilesElementReadonly(element: FilesElement, ctx: RenderContext, wrapper: HTMLElement, pathKey: string): void;
+/**
+ * Render `file` element with `multiple:true` in readonly mode.
+ */
+export declare function renderMultipleFileElementReadonly(element: FileElement, ctx: RenderContext, wrapper: HTMLElement, pathKey: string): void;

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

@@ -0,0 +1 @@
+export declare function ensureFileStyles(): void;

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

@@ -0,0 +1,25 @@
+import type { State } from "../../types/state.js";
+import type { FormBuilderInstance } from "../../instance/FormBuilderInstance.js";
+import { type FileUploadConstraints } from "./constraints.js";
+export interface FileDeps {
+    picker: HTMLInputElement;
+    fileUploadHandler: () => void;
+    dragHandler: (files: FileList) => void;
+    setupDrop?: (container: HTMLElement) => void;
+    /** Called by the tile's remove button in single-file edit mode */
+    onRemove?: () => void;
+}
+export interface HandleFileSelectOptions {
+    file: File;
+    container: HTMLElement;
+    fieldName: string;
+    state: State;
+    deps?: FileDeps | null;
+    instance?: FormBuilderInstance | null;
+    allowedExtensions?: string[];
+    allowedMimes?: string[];
+    maxSizeMB?: number;
+}
+export declare function handleFileSelect(opts: HandleFileSelectOptions): Promise<void>;
+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;

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

@@ -0,0 +1,13 @@
+import type { Element, ValidationResult } from "../../types/index.js";
+import type { ComponentContext } from "../../types/index.js";
+/**
+ * Read the resource ID list for a multi-file field.
+ * Source of truth: `data-resource-ids` JSON attribute on [data-files-wrapper].
+ * Throws if the attribute is present but unparseable — that indicates a render bug.
+ */
+export declare function readMultiFileResourceIds(scopeRoot: HTMLElement, fullKey: string): string[];
+/**
+ * Validate file field and return extracted value with errors.
+ * Reads from state (resourceIndex + data-resource-ids attribute) — no DOM shape dependency.
+ */
+export declare function validateFileElement(element: Element, key: string, context: ComponentContext): ValidationResult;

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

@@ -1,31 +1,9 @@
-import type { FileElement, FilesElement, RenderContext, ComponentContext, ValidationResult, Element } from "../types/index.js";
-import type { State } from "../types/state.js";
-interface FileDeps {
-    picker: HTMLInputElement;
-    fileUploadHandler: () => void;
-    dragHandler: (files: FileList) => void;
-}
-export declare function getAllowedExtensions(accept: string | {
-    extensions: string[];
-} | undefined): string[];
-export declare function isFileExtensionAllowed(fileName: string, allowedExtensions: string[]): boolean;
-export declare function isFileSizeAllowed(file: File, maxSizeMB: number): boolean;
-export declare function renderFilePreview(container: HTMLElement, resourceId: string, state: State, options?: {
-    fileName?: string;
-    isReadonly?: boolean;
-    deps?: FileDeps | null;
-}): Promise<void>;
-export declare function renderFilePreviewReadonly(resourceId: string, state: State, fileName?: string): Promise<HTMLElement>;
-export declare function renderResourcePills(container: HTMLElement, rids: string[] | null, state: State, onRemove: ((rid: string) => void) | null, hint?: string, countInfo?: string): void;
+import type { FileElement, FilesElement, RenderContext, ComponentContext, Element } from "../types/index.js";
+export { getAllowedExtensions, isFileExtensionAllowed, isFileSizeAllowed } from "./file/constraints.js";
+export { renderFilePreview, renderFilePreviewReadonly } from "./file/preview.js";
+export { renderResourcePills } from "./file/render-edit.js";
+export { validateFileElement } from "./file/validate.js";
 export declare function renderFileElement(element: FileElement, ctx: RenderContext, wrapper: HTMLElement, pathKey: string): void;
 export declare function renderFilesElement(element: FilesElement, ctx: RenderContext, wrapper: HTMLElement, pathKey: string): void;
 export declare function renderMultipleFileElement(element: FileElement, ctx: RenderContext, wrapper: HTMLElement, pathKey: string): void;
-/**
- * Validate file field and return extracted value with errors
- */
-export declare function validateFileElement(element: Element, key: string, context: ComponentContext): ValidationResult;
-/**
- * Update file field value in DOM without re-render
- */
 export declare function updateFileField(element: Element, fieldPath: string, value: any, context: ComponentContext): void;
-export {};

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, RichInputElement, Element, Schema, ExternalAction, FormData, RenderContext, Translations, Locale, Config, ResourceMetadata, State, } from "./types/index.js";
+export type { SelectOption, ElementAction, BaseElement, TextElement, TextareaElement, NumberElement, SelectElement, FileElement, FilesElement, ContainerElement, GroupElement, 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/types/config.d.ts

@@ -1,5 +1,15 @@
 import type { Theme } from "../styles/theme.js";
 import type { TableMerge } from "./schema.js";
+/**
+ * A file resource returned by the host's library picker.
+ * The host validates/provides these fields; the library re-validates on resolve.
+ */
+export interface PickedResource {
+    resourceId: string;
+    name: string;
+    type: string;
+    size: number;
+}
 export interface Translations {
     removeElement: string;
     clickDragText: string;
@@ -7,6 +17,8 @@ export interface Translations {
     noFileSelected: string;
     noFilesSelected: string;
     downloadButton: string;
+    downloadFile: string;
+    openInNewTab: string;
     changeButton: string;
     placeholderText: string;
     previewAlt: string;
@@ -27,6 +39,12 @@ export interface Translations {
     fileCountSingle: string;
     fileCountPlural: string;
     fileCountRange: string;
+    uploadingFile: string;
+    filesCounter: string;
+    fromLibrary: string;
+    libraryEmpty: string;
+    libraryHint: string;
+    pickerError: string;
     required: string;
     minItems: string;
     maxItems: string;
@@ -41,6 +59,7 @@ export interface Translations {
     minFiles: string;
     maxFiles: string;
     invalidFileExtension: string;
+    invalidFileMime: string;
     fileTooLarge: string;
     filesLimitExceeded: string;
     unsupportedFieldType: string;
@@ -86,6 +105,17 @@ export interface Config {
     readonly: boolean;
     locale: Locale;
     translations: Record<string, Partial<Translations>>;
+    pickExistingFiles: ((context: {
+        fieldPath: string;
+        mode: "single" | "multiple";
+        accept?: {
+            extensions?: string[];
+            mime?: string[];
+        };
+        maxSizeMB?: number;
+        remainingSlots?: number;
+        selectedResourceIds?: string[];
+    }) => Promise<PickedResource[]>) | null;
     parseTableFile: ((file: File) => Promise<{
         cells: string[][];
         merges?: TableMerge[];
@@ -98,4 +128,11 @@ export interface ResourceMetadata {
     size: number;
     uploadedAt: Date;
     file?: File;
+    /**
+     * True when `type` was inferred from the filename extension rather than
+     * provided authoritatively by the host (e.g. via uploadFile or pickExistingFiles).
+     * When true, mime validation is skipped at submit time because we cannot
+     * validate against fabricated data — extension validation still applies.
+     */
+    inferredFromExtension?: 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, Element, Schema, ExternalAction, FormData, RenderContext, } from "./schema.js";
-export type { Translations, Locale, Config, ResourceMetadata, } from "./config.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

@@ -76,24 +76,31 @@ export interface SelectElement extends BaseElement {
     minCount?: number;
     maxCount?: number;
 }
+/**
+ * File accept constraint — either a legacy comma-separated string (e.g. ".jpg,.png")
+ * or a structured object with extension list, mime list, or both.
+ * `undefined` on the schema field is handled by the optional `?` marker.
+ */
+export type FileAccept = string | {
+    extensions?: string[];
+    mime?: string[];
+};
 export interface FileElement extends BaseElement {
     type: "file";
-    accept?: string | {
-        extensions: string[];
-    };
+    accept?: FileAccept;
     maxSize?: number;
     multiple?: boolean;
     minCount?: number;
     maxCount?: number;
+    disableLibrary?: boolean;
 }
 export interface FilesElement extends BaseElement {
     type: "files";
-    accept?: string | {
-        extensions: string[];
-    };
+    accept?: FileAccept;
     maxSize?: number;
     minCount?: number;
     maxCount?: number;
+    disableLibrary?: boolean;
 }
 export interface ContainerElement extends BaseElement {
     type: "container";

package/package.json

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