@dmitryvim/form-builder 0.2.32 → 0.3.0

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

@@ -5,6 +5,7 @@ export interface ColourElement extends BaseElement {
     multiple?: boolean;
     minCount?: number;
     maxCount?: number;
+    addLabel?: string;
 }
 export declare function renderColourElement(element: ColourElement, ctx: RenderContext, wrapper: HTMLElement, pathKey: string): void;
 export declare function renderMultipleColourElement(element: ColourElement, ctx: RenderContext, wrapper: HTMLElement, pathKey: string): void;

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

@@ -27,5 +27,9 @@ export interface HandleFileSelectOptions {
     maxSizeMB?: number;
 }
 export declare function handleFileSelect(opts: HandleFileSelectOptions): Promise<void>;
+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;

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

@@ -1,6 +1,6 @@
 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 { 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;

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

@@ -65,6 +65,7 @@ export interface Translations {
     invalidFileExtension: string;
     invalidFileMime: string;
     fileTooLarge: string;
+    uploadFailed: string;
     filesLimitExceeded: string;
     unsupportedFieldType: string;
     invalidOption: string;

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;
@@ -44,6 +58,7 @@ export interface TextElement extends BaseElement {
     multiple?: boolean;
     minCount?: number;
     maxCount?: number;
+    addLabel?: string;
 }
 export interface TextareaElement extends BaseElement {
     type: "textarea";
@@ -56,6 +71,7 @@ export interface TextareaElement extends BaseElement {
     minCount?: number;
     maxCount?: number;
     autoExpand?: boolean;
+    addLabel?: string;
 }
 export interface NumberElement extends BaseElement {
     type: "number";
@@ -67,6 +83,13 @@ export interface NumberElement extends BaseElement {
     multiple?: boolean;
     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";
@@ -75,6 +98,7 @@ export interface SelectElement extends BaseElement {
     multiple?: boolean;
     minCount?: number;
     maxCount?: number;
+    addLabel?: string;
 }
 /**
  * File accept constraint — either a legacy comma-separated string (e.g. ".jpg,.png")
@@ -118,6 +142,7 @@ export interface ContainerElement extends BaseElement {
      * Ignored when `multiple: false`.
      */
     displayMode?: "stack" | "slides";
+    addLabel?: string;
 }
 export interface ColourElement extends BaseElement {
     type: "colour";
@@ -125,6 +150,7 @@ export interface ColourElement extends BaseElement {
     multiple?: boolean;
     minCount?: number;
     maxCount?: number;
+    addLabel?: string;
 }
 export interface SliderElement extends BaseElement {
     type: "slider";
@@ -135,6 +161,7 @@ export interface SliderElement extends BaseElement {
     multiple?: boolean;
     minCount?: number;
     maxCount?: number;
+    addLabel?: string;
 }
 export interface SwitcherElement extends BaseElement {
     type: "switcher";
@@ -142,6 +169,26 @@ export interface SwitcherElement extends BaseElement {
     multiple?: boolean;
     minCount?: number;
     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";
@@ -221,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,43 @@
 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
+ *
+ * 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.
+ */
+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
  */
@@ -7,6 +46,48 @@ export declare function applyInputStyles(element: HTMLInputElement | HTMLTextAre
  * Apply themed hint/description styles to a paragraph element
  */
 export declare function applyHintStyles(element: HTMLParagraphElement): void;
+/**
+ * Mount a counter element into the field's label row so it sits inline with
+ * the heading (e.g. `Tags  3/5`) instead of below the field. The label row is
+ * marked with `[data-fb-label-row]` by `createLabelContainer` — the data
+ * attribute is the stable hook; layout utility classes may change.
+ *
+ * No-op when the wrapper has no label row (e.g. nested anonymous wrappers).
+ */
+export declare function mountCounterInLabel(wrapper: HTMLElement, counter: HTMLElement): void;
+/**
+ * Visual: full-width dashed pill button, optional `+ {label}` centered.
+ * Used by every multi-value field type.
+ *
+ * The counter is returned separately so callers can place it inline with the
+ * field label (saving a row). At maxCount both the button and the row are
+ * hidden — the counter stays visible wherever the caller mounted it.
+ *
+ * `classNameSuffix` becomes `add-{suffix}-btn` to preserve test-targetable
+ * class names that the existing test suite already queries.
+ */
+export interface AddItemRowHandle {
+    row: HTMLDivElement;
+    button: HTMLButtonElement;
+    counter: HTMLSpanElement;
+    update: (current: number, max: number) => void;
+}
+export declare function createAddItemRow(classNameSuffix: string, onClick: () => void, options?: {
+    label?: string;
+    showCounter?: boolean;
+}): AddItemRowHandle;
+/**
+ * Slide-sized add tile rendered inside a slides-displayMode container grid.
+ * Sits as another grid cell next to existing slides at the same dimensions.
+ */
+export interface SlideAddTileHandle {
+    tile: HTMLButtonElement;
+    counter: HTMLSpanElement;
+    update: (current: number, max: number) => void;
+}
+export declare function createSlideAddTile(onClick: () => void, options?: {
+    label?: string;
+}): SlideAddTileHandle;
 /**
  * Create a styled add button with theme support
  */

package/package.json

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