Add comprehensive JSDoc and template documentation

README.md

@@ -1,6 +1,36 @@
 # Fliplet Form Builder
 
-Documentation is available at https://developers.fliplet.com/API/components/form-builder.html
+Fliplet **Form Builder** is an open-source Fliplet component (widget) that lets app authors visually assemble complex forms and store or edit records in Fliplet Data Sources.
+
+• End-user documentation lives at **https://developers.fliplet.com/API/components/form-builder.html** – this README focuses on the source code in this repository and how to extend it.
+
+---
+
+## Repository layout
+
+```text
+js/                  # JavaScript source
+  libs/              # Shared helpers (builder.js, core.js, form.js, ...)
+  components/        # Vue components mounted in apps (runtime)
+  configurations/    # Vue components used by the form builder interface
+css/                 # CSS for builder and runtime UIs
+templates/           # Handlebars templates
+  components/        # Mark-up used by runtime components
+  configurations/    # Mark-up used by the builder interface
+vendor/              # 3rd-party libs that are **not** loaded via Fliplet dependencies
+build.html           # Empty shell injected in published apps (runtime)
+interface.html       # Builder interface loaded in Fliplet Studio
+widget.json          # Manifest – lists asset paths & dependency names
+```
+
+### Builder vs Runtime
+
+Fliplet separates code that runs **inside Fliplet Studio** (“builder”) from the code that runs **inside users' devices** (the published app). The manifest distinguishes these contexts:
+
+| Manifest section | Loaded where | Key files |
+|------------------|--------------|-----------|
+| `interface.assets` | Fliplet Studio only | `interface.html`, `js/libs/builder.js`, `css/builder.css`, etc. |
+| `build.assets`      | Mobile / Web runtime | `build.html`, `js/libs/form.js`, `css/form.css`, etc. |
 
 ---
 

js/components/address.js

@@ -1,3 +1,18 @@
+ /**
+  * Address field component – renders a smart address autocomplete field in forms.
+  * Supports Google Places API integration and manual address input options.
+  *
+  * @component address
+  * @category Location & Map
+  * @description Autocomplete address field leveraging Google Places. Can
+  * optionally fall back to manual entry and split the selected address into
+  * separate sub-fields.
+  * @prop {String}  placeholder                Placeholder text
+  * @prop {Array}   countryRestrictions        ISO country codes to restrict search
+  * @prop {Boolean} manualInput                Allow free-text entry
+  * @prop {Boolean} storeInSeparateFields      Persist individual address parts
+  * @prop {Object}  selectedFieldOptions       Mapping of address parts → field names
+ */
 Fliplet.FormBuilder.field('address', {
   name: 'Address',
   category: 'Location & Map',

js/components/buttons.js

@@ -1,3 +1,16 @@
+/**
+ * @fileoverview Buttons field – renders form action buttons (Submit / Clear) for Fliplet forms.
+ *
+ * @component ButtonsField
+ * @vue-prop {Boolean} showLabel   – Toggle label visibility (default `false`).
+ * @vue-prop {Boolean} showSubmit  – Toggle Submit button (default `true`).
+ * @vue-prop {Boolean} showClear   – Toggle Clear button (default `true`).
+ * @vue-prop {String}  submitValue – Submit button label (default `'Submit'`).
+ * @vue-prop {String}  clearValue  – Clear button label (default `'Clear'`).
+ * @vue-prop {String}  submitType  – Submit button HTML type attribute (default `'submit'`).
+ * @vue-prop {String}  clearType   – Clear button HTML type attribute (default `'button'`).
+ * @vue-prop {String}  type        – Component type identifier (default `'flButtons'`).
+ */
 Fliplet.FormBuilder.field('buttons', {
   name: 'Form buttons',
   category: 'Buttons',

js/components/checkbox.js

@@ -1,3 +1,14 @@
+/**
+ * Checkbox field component.
+ *
+ * @component checkbox
+ * @category Multiple options
+ * @description Renders a list of checkboxes with optional “Select all”.
+ * @prop {Array}   value        Selected option values
+ * @prop {String}  defaultValue Initial value(s) separated by newline
+ * @prop {Array}   options      Array<{label,id}>
+ * @prop {Boolean} addSelectAll Show a “Select all” checkbox
+ */
 Fliplet.FormBuilder.field('checkbox', {
   name: 'Checkboxes (multi-select)',
   category: 'Multiple options',

js/components/codeScanner.js

@@ -1,3 +1,8 @@
+/** 
+ * A Fliplet Form Builder field component that provides barcode/QR code scanning functionality.
+ * Allows users to scan barcodes or QR codes using their device's camera and automatically
+ * populate form fields with the scanned data.
+ */
 Fliplet.FormBuilder.field('codeScanner', {
   name: 'Code scanner',
   category: 'Advanced',

js/components/customButton.js

@@ -1,3 +1,7 @@
+/**
+ * Custom button field component – renders configurable action buttons in forms.
+ * Supports custom styling, actions, and conditional display logic.
+ */
 Fliplet.FormBuilder.field('customButton', {
   name: 'Button',
   category: 'Buttons',

js/components/date.js

@@ -1,3 +1,7 @@
+/**
+ * Date field component – renders a date picker input in forms.
+ * Supports date validation and default value options.
+ */
 Fliplet.FormBuilder.field('date', {
   name: 'Date picker',
   category: 'Date & time',

js/components/dateRange.js

@@ -1,3 +1,7 @@
+/**
+ * Date range field component – renders a dual date picker for selecting date ranges.
+ * Allows selection of start and end dates with validation for proper ranges.
+ */
 Fliplet.FormBuilder.field('dateRange', {
   name: 'Date range',
   category: 'Date & time',

js/components/email.js

@@ -1,3 +1,7 @@
+/**
+ * Email field component – renders an email input field with validation in forms.
+ * Provides automatic email format validation and invalid character filtering.
+ */
 Fliplet.FormBuilder.field('email', {
   name: 'Email input',
   category: 'Text inputs',

js/components/file.js

@@ -1,5 +1,9 @@
 /* global loadImage, addThumbnailToCanvas */
 
+/**
+ * File field component – renders a file upload input with progress tracking.
+ * Supports multiple file types and media folder integration.
+ */
 Fliplet.FormBuilder.field('file', {
   i18n: window.VueI18Next,
   name: 'Attach a file',

js/components/geolocation.js

@@ -1,3 +1,7 @@
+/**
+ * Geolocation field component – captures and stores user's GPS coordinates in forms.
+ * Automatically detects location using device GPS with user permission.
+ */
 Fliplet.FormBuilder.field('geolocation', {
   name: 'Geolocation',
   category: 'Location & Map',

js/components/horizontalRule.js

@@ -1,3 +1,7 @@
+/**
+- * Horizontal rule (LIne Break) field component – renders a visual separator line in forms.
++ * Horizontal rule (Line Break) field component – renders a visual separator line in forms.
+ */
 Fliplet.FormBuilder.field('horizontalRule', {
   name: 'Line break',
   category: 'Formatting',

js/components/image.js

@@ -1,5 +1,9 @@
 /* global Camera, addThumbnailToCanvas, loadImage */
 
+/**
+ * Image field component – renders an image capture and upload input in forms.
+ * Supports camera capture, file upload.
+ */
 Fliplet.FormBuilder.field('image', {
   i18n: window.VueI18Next,
   name: 'Image upload',

js/components/input.js

@@ -1,3 +1,7 @@
+/**
+ * Input field component – renders a text input field in forms.
+ * Supports validation, placeholder text, and GUID generation.
+ */
 Fliplet.FormBuilder.field('input', {
   name: 'Text input',
   category: 'Text inputs',

js/components/map.js

@@ -1,3 +1,7 @@
+/**
+ * Map field component – renders an interactive map for location selection in forms.
+ * Supports marker placement, address lookup, and coordinate capture.
+ */
 Fliplet.FormBuilder.field('map', {
   name: 'Map',
   category: 'Location & Map',

js/components/matrix.js

@@ -1,3 +1,7 @@
+/**
+ * Matrix field component – renders a grid-based selection interface in forms.
+ * Supports multiple rows and columns with radio selection mode.
+ */
 Fliplet.FormBuilder.field('matrix', {
   name: 'Matrix',
   category: 'Multiple options',

js/components/number.js

@@ -1,3 +1,15 @@
+/**
+ * Number field component.
+ *
+ * @component number
+ * @category Text inputs
+ * @description Renders a numeric input with built-in validators for
+ * integers, decimal precision and also has positive-only mode.
+ * @prop {String}  placeholder   Placeholder text
+ * @prop {Boolean} positiveOnly  Restrict input to ≥ 0
+ * @prop {Number}  decimals      Allowed decimal places
+ * @prop {String}  description   Additional helper text
+ */
 Fliplet.FormBuilder.field('number', {
   i18n: window.VueI18Next,
   name: 'Number input',

js/components/paragraph.js

@@ -1,3 +1,7 @@
+/**
+ * Paragraph field component – renders static text content in forms.
+ * Supports HTML formatting and serves as informational text blocks.
+ */
 Fliplet.FormBuilder.field('paragraph', {
   name: 'Format Paragraph',
   category: 'Formatting',

js/components/password.js

@@ -1,3 +1,11 @@
+/**
+ * This component provides a password input field with advanced features including:
+ * - Password strength validation with customizable rules
+ * - Password confirmation field
+ * - Auto-generation of secure passwords
+ * - Password hashing support
+ * - Progress saving and population on update
+ */
 Fliplet.FormBuilder.field('password', {
   name: 'Password input',
   category: 'Text inputs',

js/components/radio.js

@@ -1,3 +1,15 @@
+/**
+ * A single-select radio button component that allows users to choose one option from a list.
+ * 
+ * @property {string} [description] - Optional description text displayed above the radio buttons
+ * @property {Array<Object>} options - Array of option objects with label and optional id properties
+ * @property {string} options[].label - Display text for the radio option
+ * @property {string} [options[].id] - Unique identifier for the option (optional, falls back to label)
+ * @property {boolean} [required=false] - Whether the field is required for form submission
+ * @property {boolean} [readonly=false] - Whether the field is read-only and cannot be modified
+ * @property {string} value - The currently selected option value (id or label)
+ * 
+ */
 Fliplet.FormBuilder.field('radio', {
   name: 'Radios (single-select)',
   category: 'Multiple options',

js/components/reorderList.js

@@ -1,3 +1,13 @@
+ /**
+ * @fileoverview Reorder-list field – draggable list for item prioritisation in Fliplet forms.
+ *
+ * Users can drag to establish custom ordering.
+ *
+ * @component ReorderListField
+ * @vue-prop {Array<Object>} options       – Default list items (`id`, `label`).
+ * @vue-prop {String}        optionsType   – 'dataSource' or 'static'.
+ * @vue-prop {Number}        dataSourceId  – Linked data-source ID when `optionsType` is 'dataSource'.
+ */
 Fliplet.FormBuilder.field('reorderList', {
   name: 'Reorder list',
   category: 'Multiple options',

js/components/select.js

@@ -1,3 +1,7 @@
+/**
+ * Select field component – renders a dropdown selection input in forms.
+ * Supports custom options, data source integration, and multiple selection modes.
+ */
 Fliplet.FormBuilder.field('select', {
   name: 'Dropdown (single-select)',
   category: 'Multiple options',

js/components/signature.js

@@ -1,4 +1,8 @@
 /* global SignaturePad */
+/**
+ * Signature field component – renders a signature capture pad in forms.
+ * Enables users to draw signatures using touch or mouse input with save functionality.
+ */
 Fliplet.FormBuilder.field('signature', {
   name: 'Signature',
   category: 'Advanced',

js/components/slider.js

@@ -1,3 +1,7 @@
+/**
+ * Slider field component – renders a range slider input for numeric selection in forms.
+ * Supports min/max values, step increments, and real-time value display.
+ */
 Fliplet.FormBuilder.field('slider', {
   name: 'Slider',
   category: 'Advanced',

js/components/starRating.js

@@ -1,3 +1,7 @@
+/**
+ * Star rating field component – renders interactive star rating selection in forms.
+ * Allows users to select ratings by clicking on star icons with customizable scales.
+ */
 Fliplet.FormBuilder.field('starRating', {
   name: 'Star rating',
   category: 'Advanced',

js/components/telephone.js

@@ -1,3 +1,6 @@
+/**
+ * Telephone field component – renders a phone number input with validation in forms.
+ */
 Fliplet.FormBuilder.field('telephone', {
   name: 'Telephone input',
   category: 'Text inputs',

js/components/textarea.js

@@ -1,3 +1,7 @@
+/**
+ * Textarea field component – renders a multi-line text input field in forms.
+ * Supports configurable rows, character limits, and validation in case the field is required.
+ */
 Fliplet.FormBuilder.field('textarea', {
   name: 'Multiple line input',
   category: 'Text inputs',

js/components/time.js

@@ -1,3 +1,6 @@
+/**
+ * Time field component – renders a time picker input for selecting hours and minutes.
+ */
 Fliplet.FormBuilder.field('time', {
   name: 'Time picker',
   category: 'Date & time',

js/components/timeRange.js

@@ -1,3 +1,7 @@
+/**
+ * Time range field component – renders dual time pickers for selecting time ranges.
+ * Allows selection of start and end times with validation for proper time sequences.
+ */
 Fliplet.FormBuilder.field('timeRange', {
   name: 'Time range',
   category: 'Date & time',

js/components/timeStamp.js

@@ -1,3 +1,7 @@
+/**
+ * Timestamp field component – automatically captures current date and time in forms.
+ * Records form submission timestamps with customizable display formats.
+ */
 Fliplet.FormBuilder.field('timeStamp', {
   name: 'Time Stamp',
   category: 'Date & time',

js/components/timer.js

@@ -1,3 +1,7 @@
+/**
+ * This component renders a stopwatch or countdown timer input.
+ * It can start automatically, track elapsed or remaining time, and store the value persistently.
+ */
 Fliplet.FormBuilder.field('timer', {
   name: 'Timer',
   category: 'Date & time',

js/components/title.js

@@ -1,3 +1,6 @@
+/**
+ * Title field component – renders formatted heading text in forms.
+ */
 Fliplet.FormBuilder.field('title', {
   name: 'Format Title',
   category: 'Formatting',

js/components/typeahead.js

@@ -1,3 +1,7 @@
+/**
+ * This component renders a typeahead (autocomplete) input that supports multi-selection.
+ * Options can be configured manually or fetched from a data source.
+ */
 Fliplet.FormBuilder.field('typeahead', {
   name: 'Typeahead (multi-select)',
   category: 'Multiple options',

js/components/url.js

@@ -1,3 +1,6 @@
+/**
+ * URL field component – renders a URL input field with validation in forms.
+ */
 Fliplet.FormBuilder.field('url', {
   name: 'URL input',
   category: 'Text inputs',

js/components/wysiwyg.js

@@ -1,3 +1,9 @@
+/**
+ * WYSIWYG field component - Renders a rich text editor powered by TinyMCE that allows users to create and edit
+ * formatted HTML content within forms. Supports text styling, links, tables, lists,
+ * and various formatting options with a comprehensive toolbar interface.
+ *
+ */
 Fliplet.FormBuilder.field('wysiwyg', {
   name: 'Rich text',
   category: 'Text inputs',

js/configurations/password.js

@@ -1,3 +1,8 @@
+/**
+ * Password field configuration – handles password validation and generation settings.
+ * Manages mutual exclusivity between password confirmation and autogeneration features.
+ * Enforces minimum password length validation (8 characters minimum).
+ */
 Fliplet.FormBuilder.configuration('password', {
   methods: {
     validatePasswordLength: function() {