@cyprnet/node-red-contrib-uibuilder-formgen 0.5.29 → 0.5.35

package/CHANGELOG.md

@@ -51,6 +51,31 @@ All notable changes to this package will be documented in this file.
 
 - Schema Builder: make field move controls always visible by using text arrows (↑/↓) instead of relying on Font Awesome icon rendering.
 
+## 0.5.30
+
+- Schema Builder: Regex validation now always shows a dedicated pattern input, and existing <code>validate:"regex:&lt;pattern&gt;"</code> fields correctly load the pattern for editing.
+
+## 0.5.31
+
+- Schema Builder: fixed Vue 2 reactivity when editing older fields that did not include <code>validate</code>/<code>validateMessage</code> properties. Selecting “Regex Pattern” now reliably reveals the pattern input.
+
+## 0.5.32
+
+- Schema Builder: Regex Pattern input is now rendered as its own form group (not an inline block), avoiding cases where the input existed in the DOM but was not visible due to modal layout/CSS interactions.
+
+## 0.5.33
+
+- Validation: Vue 3 portals now support <code>validate</code> (email/phone/regex) the same way Vue 2 portals do.
+- Validation: regex validators now accept both <code>regex:&lt;pattern&gt;</code> and <code>regex:/&lt;pattern&gt;/&lt;flags&gt;</code>. Invalid regex patterns now surface a visible validation error instead of silently passing.
+
+## 0.5.34
+
+- Schema Builder: Regex Pattern placeholder text now shows the user-typed form (<code>\.</code>) instead of the JSON-escaped form (<code>\\.</code>).
+
+## 0.5.35
+
+- Docs: README + offline user guide now explicitly call out that generated portals require copying <code>form.schema.json</code> alongside <code>index.html</code>/<code>index.js</code>.
+
 ## 0.5.21
 
 - Legacy uibuilder 2.x: fixed vendor library paths (<code>../vendor/...</code>) in the uib2 portal template and uib2 Schema Builder so uibuilder comms work and <code>lookup:get</code> messages emit correctly.

package/README.md

@@ -38,6 +38,16 @@ Then restart Node-RED.
 2. Send a schema into `uibuilder-formgen` (legacy Vue 2) or `uibuilder-formgen-v3` (Vue 3) as `msg.schema` (or use the example flow).
 3. Open `/uibuilder/<instance>/` in your browser.
 
+### Important: the portal needs `form.schema.json`
+
+Generated portals are a 3-file set that must stay together in the uibuilder instance’s served folder:
+
+- `src/index.html`
+- `src/index.js`
+- `src/form.schema.json`
+
+If you copy a portal to another uibuilder instance (or commit/restore from git), make sure you copy **all three**. The portal loads the schema at runtime and will not work correctly if `form.schema.json` is missing.
+
 ### Node differences (legacy vs v3)
 
 - **`uibuilder-formgen` (legacy)**: generates portals using **Vue 2 + Bootstrap 4**

package/docs/user-guide.html

@@ -162,9 +162,11 @@
           <li><a href="#install">Install & upgrade</a></li>
           <li><a href="#licensing">Licensing (Free vs Licensed)</a></li>
           <li><a href="#folders">Folder locations (standard + Projects)</a></li>
+          <li><a href="#portalsmith-setup">PortalSmith setup (end-to-end)</a></li>
           <li><a href="#schema-builder">Schema Builder (form designer)</a></li>
           <li><a href="#schemas">Schema examples library (industry templates)</a></li>
           <li><a href="#schema-reference">Schema reference (field types)</a></li>
+          <li><a href="#lookup-contracts">Lookup / Auto-fill (message contracts)</a></li>
           <li><a href="#generate">Generating a portal (uibuilder-formgen)</a></li>
           <li><a href="#customize">Customization options (theme, logo, submit, API proxy)</a></li>
           <li><a href="#submit-results">Submitting & results page</a></li>
@@ -272,19 +274,49 @@
 
         <section id="install">
           <h2>Install & upgrade</h2>
-          <h3>Install the node</h3>
-          <ol>
-            <li>In Node-RED: Menu → Manage palette → Install</li>
-            <li>Install <code>@cyprnet/node-red-contrib-uibuilder-formgen</code> (or install from a <code>.tgz</code> file)</li>
-            <li><strong>Restart Node-RED</strong></li>
-          </ol>
+          <h3>Prerequisites</h3>
+          <ul>
+            <li><strong>Node-RED is installed</strong> and you know your <code>userDir</code> (commonly <code>~/.node-red</code>).</li>
+            <li><strong>Node.js + npm</strong> are installed on the host that runs Node-RED.</li>
+            <li><strong>uibuilder</strong> is installed (v7+ recommended; uibuilder 2.x supported via the legacy generator node).</li>
+          </ul>
 
-          <h3>Install/upgrade uibuilder</h3>
+          <h3>Install via the Node-RED palette (UI)</h3>
           <ol>
-            <li>In Node-RED: Menu → Manage palette → Install</li>
-            <li>Install/upgrade <code>node-red-contrib-uibuilder</code></li>
-            <li>Restart Node-RED if prompted</li>
+            <li>Node-RED menu → <strong>Manage palette</strong> → <strong>Install</strong></li>
+            <li>Search and install: <code>@cyprnet/node-red-contrib-uibuilder-formgen</code></li>
+            <li>Install/upgrade: <code>node-red-contrib-uibuilder</code></li>
+            <li><strong>Restart Node-RED</strong> after installs/upgrades</li>
           </ol>
+
+          <h3>Install via npm (recommended for servers)</h3>
+          <div class="note">
+            Stop Node-RED before running npm installs. After installation, start/restart Node-RED so it loads the new nodes.
+          </div>
+
+          <h4>Install from npm registry</h4>
+          <pre># Standard userDir
+cd ~/.node-red
+npm install @cyprnet/node-red-contrib-uibuilder-formgen
+
+# Install/upgrade uibuilder (v7+ recommended)
+npm install node-red-contrib-uibuilder</pre>
+
+          <h4>Install from a local build (.tgz)</h4>
+          <pre># Example: install a specific build artifact
+cd ~/.node-red
+npm install /absolute/path/to/cyprnet-node-red-contrib-uibuilder-formgen-0.5.29.tgz</pre>
+
+          <h4>Upgrade (npm)</h4>
+          <pre>cd ~/.node-red
+npm update @cyprnet/node-red-contrib-uibuilder-formgen
+npm update node-red-contrib-uibuilder</pre>
+
+          <div class="note ok">
+            <strong>Verification:</strong> After restart, you should see the generator nodes in the palette:
+            <code>uibuilder-formgen</code>, <code>uibuilder-formgen-v3</code>, and <code>uibuilder-formgen-uib2</code>,
+            plus the <code>portalsmith-license</code> config node.
+          </div>
         </section>
 
         <section id="licensing">
@@ -348,6 +380,102 @@
           </div>
         </section>
 
+        <section id="portalsmith-setup">
+          <h2>PortalSmith setup (end-to-end)</h2>
+
+          <p>
+            This is a detailed, step-by-step “cookbook” for a complete PortalSmith setup:
+            design a schema, generate a portal into a uibuilder instance, and wire up submit and lookup/autofill behavior.
+          </p>
+
+          <div class="note ok">
+            <strong>Terminology</strong>
+            <ul>
+              <li><strong>Builder instance</strong>: a uibuilder page running the Schema Builder UI (example URL: <code>formgen-builder</code>).</li>
+              <li><strong>Portal instance</strong>: a uibuilder page generated by FormGen (example URL: <code>my-portal</code>).</li>
+              <li><strong>Generator node</strong>: one of <code>uibuilder-formgen</code> / <code>uibuilder-formgen-v3</code> / <code>uibuilder-formgen-uib2</code>.</li>
+            </ul>
+          </div>
+
+          <h3>1) Create the uibuilder instance that will host the generated portal</h3>
+          <ol>
+            <li>Drag a <code>uibuilder</code> node into your flow.</li>
+            <li>Set <strong>URL</strong> (instance name) to something simple, e.g. <code>my-portal</code>.</li>
+            <li>Deploy once. This creates the instance folder on disk.</li>
+          </ol>
+
+          <div class="note">
+            <strong>Where FormGen writes files:</strong>
+            FormGen writes into the portal instance’s <code>src/</code> folder:
+            <code>src/index.html</code>, <code>src/index.js</code>, <code>src/form.schema.json</code>, plus <code>portalsmith.runtime.json</code>.
+          </div>
+
+          <div class="note ok">
+            <strong>Important (manual copying / git restores):</strong>
+            A generated portal is a 3-file set. If you copy a portal to another uibuilder instance (or restore it from git/backup),
+            you must copy <strong>all three</strong> runtime files together:
+            <code>src/index.html</code>, <code>src/index.js</code>, and <code>src/form.schema.json</code>.
+            The portal loads the schema at runtime; if <code>form.schema.json</code> is missing, the portal will not render correctly.
+          </div>
+
+          <h3>2) Generate a portal from a schema</h3>
+
+          <h4>Method A: Generate from an Inject node (recommended first test)</h4>
+          <ol>
+            <li>Add an <strong>Inject</strong> node and set it to send a JSON object.</li>
+            <li>Put your schema object in <code>msg.schema</code> (preferred). (Fallback: put the schema object in <code>msg.payload</code>.)</li>
+            <li>Wire: <strong>Inject → uibuilder-formgen (or v3/uib2) → Debug</strong>.</li>
+            <li>In the FormGen node, set <strong>Instance</strong> to your portal instance name (e.g. <code>my-portal</code>).</li>
+            <li>Deploy, then click Inject.</li>
+            <li>Open the portal URL: <code>/uibuilder/my-portal/</code> (or your configured uibuilder base path).</li>
+          </ol>
+
+          <h4>Method B: Generate from the Schema Builder UI (recommended day-to-day)</h4>
+          <ol>
+            <li>Host the Schema Builder UI in a uibuilder instance (see <a href="#schema-builder">Schema Builder</a>).</li>
+            <li>Design your schema in the UI.</li>
+            <li>Click <strong>Generate Form</strong>.</li>
+            <li>Your flow receives <code>{type:'generate', schema:{...}}</code> from the builder instance and must route it into a FormGen node.</li>
+          </ol>
+
+          <h3>Recommended Node-RED flow wiring for a portal instance (submit + lookup)</h3>
+          <p>
+            In most PortalSmith deployments, a single uibuilder instance handles both submits and lookup/autofill requests.
+            The cleanest pattern is to route by <code>msg.payload.type</code> from the uibuilder node’s output #1.
+          </p>
+          <pre>my-portal (uibuilder node) output #1
+  ↓
+Switch on msg.payload.type
+  ├─ "lookup:get" → lookup handler → (respond) my-portal (uibuilder input)
+  ├─ "submit"     → submit handler  → (respond) my-portal (uibuilder input)
+  └─ (other)      → Debug / ignore</pre>
+          <div class="note">
+            <strong>Important:</strong> Always send lookup/submit responses back into the <em>same</em> uibuilder instance that originated the request.
+            If you have separate builder + portal instances, make sure each response goes back to the correct uibuilder node.
+          </div>
+
+          <h3>3) Wire Submit (portal → Node-RED → portal)</h3>
+          <p>
+            By default, portals submit using <strong>uibuilder messages</strong>. The portal sends a submit request out of the uibuilder node (output #1).
+            Your flow should respond back into the same uibuilder node’s input so the portal can show results and clear spinners.
+          </p>
+          <pre>Portal (browser)
+  ↓ (uibuilder send)
+Node-RED: uibuilder node (output #1)
+  ↓
+Your flow logic (Function / HTTP / DB / API proxy)
+  ↓
+Node-RED: uibuilder node (input)
+  ↓
+Portal (browser) shows Table/JSON/Form results</pre>
+
+          <h3>4) Wire Lookup/Auto-fill (portal → Node-RED → portal)</h3>
+          <p>
+            Lookup/Auto-fill uses the same uibuilder channel. The portal emits <code>lookup:get</code> requests and expects <code>lookup:data</code> (or <code>lookup:error</code>) replies.
+            See <a href="#lookup-contracts">Lookup/Auto-fill: message contracts</a>.
+          </p>
+        </section>
+
         <section id="schema-builder">
           <h2>Schema Builder (form designer)</h2>
           <p>The Schema Builder is a uibuilder instance that you host like any other uibuilder page.</p>
@@ -362,45 +490,80 @@
             <li><strong>New Schema</strong> button resets your current schema</li>
           </ul>
 
-          <h3>How to host it</h3>
+          <h3>Hosting the Schema Builder (uibuilder v7+)</h3>
+          <p>
+            Use this when you are on modern uibuilder (v7+). You host the builder like any other uibuilder page.
+          </p>
           <ol>
-            <li>Create a uibuilder instance (example name: <code>formgen-builder</code>)</li>
-            <li>Copy the builder files into that instance’s <code>src/</code> folder</li>
-            <li>Deploy and open: <code>/uibuilder/formgen-builder/</code></li>
+            <li>Create a uibuilder instance (example URL: <code>formgen-builder</code>).</li>
+            <li>Deploy once (creates the instance folder).</li>
+            <li>Copy the builder files into the instance folder’s <code>src/</code>:</li>
+          </ol>
+          <pre># Standard userDir example
+cd ~/.node-red
+cp node_modules/@cyprnet/node-red-contrib-uibuilder-formgen/examples/formgen-builder/src/index.html uibuilder/formgen-builder/src/index.html
+cp node_modules/@cyprnet/node-red-contrib-uibuilder-formgen/examples/formgen-builder/src/index.js   uibuilder/formgen-builder/src/index.js</pre>
+          <ol start="4">
+            <li>Hard refresh your browser and open: <code>/uibuilder/formgen-builder/</code>.</li>
           </ol>
 
           <div class="note">
-            <strong>Builder dependencies:</strong> the builder’s HTML includes scripts for Vue/Bootstrap/Bootstrap-Vue/jQuery via CDN in the builder page itself.
+            <strong>Builder dependencies:</strong> the builder’s HTML includes Vue/Bootstrap/Bootstrap‑Vue/jQuery itself. Your uibuilder instance just needs to serve the files.
           </div>
 
+          <h3>Hosting the Schema Builder (legacy uibuilder 2.8)</h3>
+          <p>
+            Use this when you are on <strong>uibuilder 2.x</strong> (for example 2.8).
+            The legacy builder uses uibuilder 2.x’s frontend bundle (<code>uibuilderfe.min.js</code>) and loads Vue/Bootstrap/Bootstrap‑Vue from uibuilder’s <code>vendor/</code> folder.
+          </p>
+          <ol>
+            <li>Create a uibuilder instance (example URL: <code>formgen-builder</code> or <code>formgen-builder-uib2</code> — the name is not hard-coded).</li>
+            <li>Deploy once.</li>
+            <li>Copy the legacy builder files into that instance folder’s <code>src/</code>:</li>
+          </ol>
+          <pre># Example (adjust your userDir/projects path as needed)
+cd ~/.node-red
+cp node_modules/@cyprnet/node-red-contrib-uibuilder-formgen/examples/formgen-builder-uib2/src/index.html uibuilder/formgen-builder/src/index.html
+cp node_modules/@cyprnet/node-red-contrib-uibuilder-formgen/examples/formgen-builder-uib2/src/index.js   uibuilder/formgen-builder/src/index.js</pre>
           <div class="note ok">
-            <strong>Where to get the Schema Builder files:</strong>
-            After installing <code>@cyprnet/node-red-contrib-uibuilder-formgen</code>, copy these files from the package:
-            <ul>
-              <li><code>examples/formgen-builder/src/index.html</code></li>
-              <li><code>examples/formgen-builder/src/index.js</code></li>
-            </ul>
-            Into your uibuilder instance folder:
-            <ul>
-              <li><code>&lt;userDir&gt;/uibuilder/formgen-builder/src/</code></li>
-              <li>or Projects: <code>&lt;userDir&gt;/projects/&lt;projectName&gt;/uibuilder/formgen-builder/src/</code></li>
-            </ul>
+            <strong>uibuilder 2.8 serving behavior:</strong> uibuilder 2.8 serves directly from <code>src/</code>, so copying into <code>src/</code> is sufficient.
           </div>
 
-          <div class="note ok">
-            <strong>Legacy uibuilder 2.8 Schema Builder:</strong>
-            If you are running <strong>uibuilder 2.x</strong> (e.g., 2.8) use the legacy builder variant which loads
-            Vue/Bootstrap/Bootstrap-Vue from uibuilder’s <code>vendor/</code> folder and uses <code>uibuilderfe.min.js</code>.
-            Copy these files instead:
-            <ul>
-              <li><code>examples/formgen-builder-uib2/src/index.html</code></li>
-              <li><code>examples/formgen-builder-uib2/src/index.js</code></li>
-            </ul>
-            Into a uibuilder instance (example: <code>formgen-builder-uib2</code>):
-            <ul>
-              <li><code>&lt;userDir&gt;/uibuilder/formgen-builder-uib2/src/</code></li>
-              <li>or Projects: <code>&lt;userDir&gt;/projects/&lt;projectName&gt;/uibuilder/formgen-builder-uib2/src/</code></li>
-            </ul>
+          <h3>Wiring the Builder to the Generator node (required)</h3>
+          <p>
+            Clicking <strong>Generate Form</strong> in the builder sends a message to Node-RED via uibuilder:
+            <code>{type:'generate', schema:{...}}</code>.
+            Your flow must transform that into <code>msg.schema</code> and pass it into a FormGen generator node.
+          </p>
+          <pre>Builder uibuilder node (output #1)
+  ↓
+Function/Switch (route builder messages)
+  ↓
+uibuilder-formgen (or -v3 / -uib2)
+  ↓
+Debug + (optional) send status back to builder uibuilder (input)</pre>
+
+          <h4>Minimum Function node to route “Generate Form”</h4>
+          <pre>// Place this between the builder uibuilder node (output #1) and a uibuilder-formgen node
+const p = msg.payload || {};
+if (p.type !== 'generate') return null;
+
+msg.schema = p.schema;                 // what formgen expects
+// Optional: pick which uibuilder instance to generate into (otherwise configure the formgen node Instance field)
+// msg.uibuilder = 'my-portal';
+
+// Optional: generation options
+msg.options = Object.assign({}, msg.options, {
+  overwrite: true,
+  protectEdits: true
+});
+
+return msg;</pre>
+
+          <div class="note">
+            <strong>Returning status to the Builder UI:</strong>
+            If you wire the generator output back into the builder uibuilder node’s input, the builder will show a success/error alert.
+            It expects <code>msg.payload.type</code> to be <code>generated</code> or <code>error</code> and will display <code>msg.payload.url</code> if present.
           </div>
 
           <div class="note">
@@ -460,6 +623,118 @@
             </tbody>
           </table>
 
+          <h3>Common field properties (all types)</h3>
+          <p>These properties are available on most field types and are surfaced by the Schema Builder UI:</p>
+          <ul>
+            <li><code>id</code> (required): unique field identifier. This becomes the key in submitted JSON.</li>
+            <li><code>label</code>: display label.</li>
+            <li><code>type</code> (required): one of the supported field types.</li>
+            <li><code>required</code>: if true, the portal will block submit if empty.</li>
+            <li><code>placeholder</code>: placeholder text for inputs.</li>
+            <li><code>defaultValue</code>: initial value.</li>
+            <li><code>help</code> (optional): help text shown under the field (if enabled by the template).</li>
+            <li><code>validate</code> (optional): additional validators (see below).</li>
+            <li><code>validateMessage</code> (optional): error message override when validation fails.</li>
+          </ul>
+
+          <h3>Validation</h3>
+          <p>In addition to <code>required</code>, the generated portals support:</p>
+          <ul>
+            <li><code>validate: "email"</code></li>
+            <li><code>validate: "phone"</code></li>
+            <li><code>validate: "regex:&lt;pattern&gt;"</code> (JavaScript regex pattern source)</li>
+            <li><code>validate: "regex:/&lt;pattern&gt;/&lt;flags&gt;"</code> (optional slashes/flags for convenience, e.g. <code>regex:/^abc$/i</code>)</li>
+          </ul>
+          <pre>{
+  "id": "employeeId",
+  "type": "text",
+  "label": "Employee ID",
+  "required": true,
+  "validate": "regex:^[A-Z]{2}-\\d{6}$",
+  "validateMessage": "Expected format: AA-123456"
+}</pre>
+
+          <h3>Field type details & examples</h3>
+
+          <h4>text</h4>
+          <p>Common add-ons:</p>
+          <ul>
+            <li><code>inputType</code>: <code>text</code> (default), <code>password</code>, <code>email</code>, <code>tel</code>, <code>url</code></li>
+          </ul>
+          <pre>{
+  "id": "password",
+  "type": "text",
+  "label": "Password",
+  "required": true,
+  "inputType": "password",
+  "placeholder": "Enter password"
+}</pre>
+
+          <h4>textarea</h4>
+          <p>Common add-ons:</p>
+          <ul>
+            <li><code>rows</code>: textarea height (rows)</li>
+          </ul>
+          <pre>{
+  "id": "notes",
+  "type": "textarea",
+  "label": "Notes",
+  "rows": 6
+}</pre>
+
+          <h4>number</h4>
+          <p>Common add-ons:</p>
+          <ul>
+            <li><code>min</code>, <code>max</code>, <code>step</code></li>
+          </ul>
+          <pre>{
+  "id": "retryCount",
+  "type": "number",
+  "label": "Retry Count",
+  "min": 0,
+  "max": 10,
+  "step": 1,
+  "defaultValue": 3
+}</pre>
+
+          <h4>select / radio</h4>
+          <p>
+            Options are typically an array of objects. Use <code>value</code> for the submitted value and <code>label</code> for display text.
+            The user selection is stored as the option <code>value</code>.
+          </p>
+          <pre>{
+  "id": "os",
+  "type": "select",
+  "label": "Operating System",
+  "required": true,
+  "options": [
+    { "value": "win11", "label": "Windows 11" },
+    { "value": "ubuntu", "label": "Ubuntu" }
+  ]
+}</pre>
+          <div class="note">
+            <strong>Lookup/autofill tip:</strong> If you want a lookup rule to match what a select stores, set <code>matchKey</code> to the property that equals the selected <code>value</code>
+            (commonly <code>value</code>, not <code>label</code>).
+          </div>
+
+          <h4>checkbox</h4>
+          <p>Checkbox fields submit a boolean:</p>
+          <pre>{
+  "id": "acknowledged",
+  "type": "checkbox",
+  "label": "I understand",
+  "defaultValue": false
+}</pre>
+
+          <h4>date</h4>
+          <p>Date values are submitted as strings (implementation depends on template/browser):</p>
+          <pre>{
+  "id": "startDate",
+  "type": "date",
+  "label": "Start Date",
+  "required": true
+}</pre>
+
           <h3>Key/value fields (keyvalue)</h3>
           <p><strong>Pairs mode</strong> stores an array of objects:</p>
           <pre>{
@@ -804,6 +1079,144 @@ return msg;</pre>
           </div>
         </section>
 
+        <section id="lookup-contracts">
+          <h2>Lookup / Auto-fill (message contracts)</h2>
+
+          <p>
+            When you set <code>autoFill.source.type = "uibuilder"</code>, the portal uses uibuilder messages to ask Node-RED for lookup data.
+            The message namespace is carried in <code>msg.payload.type</code> using <code>lookup:*</code> strings.
+          </p>
+
+          <h3>How the portal routes messages (why <code>lookup:*</code> matters)</h3>
+          <p>
+            The generated portal watches incoming uibuilder messages and routes behavior based on <code>msg.payload.type</code>:
+          </p>
+          <ul>
+            <li><strong><code>lookup:data</code></strong>: cache lookup items and immediately re-apply any autofill rules that use that <code>lookupId</code>.</li>
+            <li><strong><code>lookup:error</code></strong>: show a warning and stop waiting for that lookup.</li>
+            <li><strong><code>submit:ok</code> / <code>submit:error</code></strong>: clear submit spinners and show results.</li>
+          </ul>
+          <div class="note">
+            <strong>Important:</strong> The portal does not “guess” what a lookup response is. It specifically checks for <code>payload.type === 'lookup:data'</code> (or <code>lookup:error</code>).
+            If your response uses a different <code>type</code> string, the UI will not update.
+          </div>
+
+          <h3>Request (portal → Node-RED)</h3>
+          <p>
+            When a user changes the source field for an autofill rule, the portal sends a message out of the uibuilder node (output #1).
+            For text typing, it uses debouncing and will also flush on blur.
+          </p>
+          <pre>{
+  "payload": {
+    "type": "lookup:get",
+    "lookupId": "ips",
+    "matchValue": "192.168.1.0/24"
+  }
+}</pre>
+          <ul>
+            <li><strong><code>lookupId</code></strong>: identifies the lookup service/list. You define this string in the schema and in your Node-RED flow.</li>
+            <li><strong><code>matchValue</code></strong>: the current value of the source field (trimmed). It may be <code>null</code> if the portal has no value yet.</li>
+          </ul>
+
+          <h3>Response (Node-RED → portal)</h3>
+          <p>
+            Your flow should respond back into the same uibuilder node’s input with one of these messages:
+          </p>
+          <h4>Success: lookup data</h4>
+          <pre>{
+  "payload": {
+    "type": "lookup:data",
+    "lookupId": "ips",
+    "matchValue": "192.168.1.0/24",
+    "items": [
+      {
+        "ip": "192.168.1.0/24",
+        "ips": ["192.168.1.0", "192.168.1.1", "192.168.1.2"]
+      }
+    ]
+  }
+}</pre>
+          <div class="note ok">
+            <strong>Golden rules:</strong>
+            <ul>
+              <li><strong><code>items</code> must be an array</strong>, even if you only have one record to return.</li>
+              <li>Each item must contain the properties referenced by your rule’s <code>matchKey</code> and each mapping’s <code>valueKey</code>.</li>
+              <li>Return the same <code>lookupId</code> you were asked for.</li>
+            </ul>
+          </div>
+
+          <h4>Error: lookup failed</h4>
+          <pre>{
+  "payload": {
+    "type": "lookup:error",
+    "lookupId": "ips",
+    "matchValue": "192.168.1.0/24",
+    "error": "Timed out calling backend"
+  }
+}</pre>
+
+          <h3>Match keys, value keys, and dot paths</h3>
+          <ul>
+            <li><strong><code>matchKey</code></strong> is the property path in each item used to compare with the user’s source field value.</li>
+            <li><strong><code>valueKey</code></strong> is the property path copied into the target field.</li>
+            <li>Both support dot notation (example: <code>meta.id</code> or <code>details.network.ips</code>).</li>
+          </ul>
+
+          <h3>Textarea targets and “array” values</h3>
+          <p>
+            If your mapping writes into a <code>textarea</code> (or a <code>keyvalue</code> field in delimiter mode), the portal can render:
+          </p>
+          <ul>
+            <li><strong>Array of strings</strong>: joined into newline-separated text.</li>
+            <li><strong>Array of objects</strong> like <code>{value,label}</code>: joined into newline-separated lines using the best available string per item.</li>
+          </ul>
+
+          <h3>Debounce / blur behavior (text field lookups)</h3>
+          <p>
+            For <code>text</code> and <code>textarea</code> source fields using dynamic lookup (<code>source.type="uibuilder"</code>),
+            the portal requests lookups in a user-friendly way:
+          </p>
+          <ul>
+            <li><strong>Debounced typing:</strong> it waits briefly after the user stops typing before requesting <code>lookup:get</code>.</li>
+            <li><strong>Blur flush:</strong> when the input loses focus, it triggers an immediate lookup for the final value.</li>
+          </ul>
+
+          <h3>Lookup caching (important for performance)</h3>
+          <p>
+            The portal caches dynamic lookup results by key:
+            <code>&lt;lookupId&gt;::&lt;matchValue&gt;</code> (and optionally by <code>&lt;lookupId&gt;</code> for “full list” responses).
+            This avoids repeatedly calling Node-RED for the same selection/value.
+          </p>
+
+          <h3>Example Node-RED handler (single Function node)</h3>
+          <p>
+            Wire: <strong>uibuilder (portal) output #1 → Function → uibuilder input</strong>.
+            This pattern supports multiple <code>lookupId</code> values in one place.
+          </p>
+          <pre>// Function node: handle lookup requests
+const p = msg.payload || {};
+if (p.type !== 'lookup:get') return null;
+
+if (p.lookupId === 'ips') {
+  // Example: p.matchValue holds the typed subnet/CIDR
+  msg.payload = {
+    type: 'lookup:data',
+    lookupId: 'ips',
+    matchValue: p.matchValue ?? null,
+    items: [
+      {
+        ip: String(p.matchValue || '').trim(),
+        ips: ['192.168.1.0', '192.168.1.1', '192.168.1.2']
+      }
+    ]
+  };
+  return msg;
+}
+
+msg.payload = { type: 'lookup:error', lookupId: p.lookupId, matchValue: p.matchValue ?? null, error: 'Unknown lookupId' };
+return msg;</pre>
+        </section>
+
         <section id="generate">
           <h2>Generating a portal (uibuilder-formgen / uibuilder-formgen-v3 / uibuilder-formgen-uib2)</h2>
           <p>
@@ -822,19 +1235,67 @@ return msg;</pre>
             <strong>How to confirm which runtime generated a portal:</strong> open the generated <code>portalsmith.runtime.json</code> file and check <code>generatorNode</code>.
           </div>
 
-          <h3>Minimum input</h3>
-          <pre>{
-  "schema": { ... }
-}</pre>
+          <h3>Minimum input (Node-RED message)</h3>
+          <p>The generator nodes read the schema from <code>msg.schema</code> (preferred) or <code>msg.payload</code> (fallback).</p>
+          <pre>// Minimum: send a schema object
+msg.schema = { ...schema json... };</pre>
 
-          <h3>Recommended input shape</h3>
-          <pre>{
-  "schema": { ...schema json... },
-  "uibuilder": "my-portal-instance",
-  "options": {
-    "overwrite": true
-  }
-}</pre>
+          <h3>Pick the uibuilder instance to generate into</h3>
+          <p>You can select the target instance in three ways (highest precedence first):</p>
+          <ol>
+            <li><code>msg.uibuilder</code></li>
+            <li><code>msg.options.instance</code></li>
+            <li>Node config field: <strong>Instance</strong> (<code>instanceName</code>)</li>
+          </ol>
+          <pre>// Example: generate into URL "/uibuilder/my-portal/"
+msg.uibuilder = "my-portal";</pre>
+
+          <h3>Options (<code>msg.options</code> overrides node config)</h3>
+          <p>
+            Generator nodes accept <code>msg.options</code> for path overrides, overwrite protection, theming, and submit behavior.
+            Common options include:
+          </p>
+          <ul>
+            <li><strong>Overwrite & protection</strong>:
+              <ul>
+                <li><code>overwrite</code>: boolean (default true)</li>
+                <li><code>protectEdits</code>: boolean (default true)</li>
+                <li><code>forceOverwrite</code>: boolean (default false) — override protection once (use with backups)</li>
+              </ul>
+            </li>
+            <li><strong>Paths</strong> (optional; useful for Projects or non-standard installs):
+              <ul>
+                <li><code>projectName</code>: use <code>&lt;userDir&gt;/projects/&lt;projectName&gt;/uibuilder</code></li>
+                <li><code>uibRootDir</code>: absolute path to the uibuilder root folder</li>
+                <li><code>instanceRootDir</code>: absolute path to the specific uibuilder instance folder</li>
+              </ul>
+            </li>
+            <li><strong>Portal UX</strong>:
+              <ul>
+                <li><code>themeMode</code>: <code>auto</code> | <code>light</code> | <code>dark</code></li>
+                <li><code>storageMode</code>: <code>file</code> | <code>localstorage</code></li>
+                <li><code>exportFormats</code>: array like <code>["json","csv","html"]</code></li>
+              </ul>
+            </li>
+          </ul>
+
+          <pre>// Example: full generation message
+msg.schema = { ...schema json... };
+msg.uibuilder = "my-portal";
+msg.options = {
+  overwrite: true,
+  protectEdits: true,
+  // forceOverwrite: true, // only if you intend to replace edited files
+  themeMode: "auto",
+  exportFormats: ["json","csv","html"]
+};
+return msg;</pre>
+
+          <div class="note">
+            <strong>uibuilder v7+ note (src vs dist):</strong>
+            FormGen writes to <code>src/</code>. If your uibuilder instance is configured to serve <code>dist/</code>,
+            either switch it to serve <code>src/</code> while developing, or copy/build into <code>dist/</code> as part of your deployment process.
+          </div>
 
           <h3>Protecting user customizations (important)</h3>
           <p>

package/examples/formgen-builder/src/index.html

@@ -786,18 +786,27 @@ email{{currentField.keyvalueDelimiter || '='}}john@example.com</code></pre>
           v-model="currentField.validate" 
           :options="validationTypes"
         />
-        <b-form-input 
-          v-if="currentField.validate === 'regex'"
-          v-model="currentField.validatePattern" 
-          placeholder="Regex pattern (e.g., ^[A-Z]{2}\\d{4}$)"
-          class="mt-2"
-        />
         <small class="form-text text-muted">
           <strong>Email:</strong> Validates email format (user@domain.com)<br>
           <strong>Phone:</strong> Validates phone number format (10+ digits)<br>
           <strong>Regex:</strong> Custom pattern validation (e.g., ^[A-Z]{2}\\d{4}$ for codes like AB1234)
         </small>
       </b-form-group>
+
+      <b-form-group
+        v-if="currentField.validate === 'regex'"
+        label="Regex pattern"
+        label-for="validate-pattern"
+      >
+        <b-form-input
+          id="validate-pattern"
+          v-model="currentField.validatePattern"
+          placeholder="e.g., ^([a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\.)+[a-zA-Z]{2,63}\.$"
+        />
+        <small class="form-text text-muted">
+          JavaScript RegExp source only (no <code>/.../</code> slashes). In this box you type a single backslash (e.g. <code>\.</code>). When exported to JSON, it will appear escaped as <code>\\.</code>.
+        </small>
+      </b-form-group>
       
       <b-form-group label="Validation Message" label-for="validate-msg" v-if="currentField.validate">
         <b-form-input 

package/examples/formgen-builder/src/index.js

@@ -901,6 +901,17 @@
           this.editingFieldLocation = { sectionIdx, fieldIdx };
           const field = this.schema.sections[sectionIdx].fields[fieldIdx];
           this.currentField = JSON.parse(JSON.stringify(field));
+
+          // Ensure validation fields are reactive even if the saved field object did not include them
+          if (!Object.prototype.hasOwnProperty.call(this.currentField, 'validate')) {
+            this.$set(this.currentField, 'validate', null);
+          }
+          if (!Object.prototype.hasOwnProperty.call(this.currentField, 'validatePattern')) {
+            this.$set(this.currentField, 'validatePattern', '');
+          }
+          if (!Object.prototype.hasOwnProperty.call(this.currentField, 'validateMessage')) {
+            this.$set(this.currentField, 'validateMessage', '');
+          }
           
           // Normalize options
           if (this.currentField.options && Array.isArray(this.currentField.options)) {
@@ -931,8 +942,9 @@
           
           // Handle validation
           if (this.currentField.validate && this.currentField.validate.startsWith('regex:')) {
+            const raw = String(this.currentField.validate);
             this.currentField.validate = 'regex';
-            this.currentField.validatePattern = this.currentField.validate.substring(6);
+            this.currentField.validatePattern = raw.substring(6);
           }
 
           // Normalize autoFill
@@ -985,6 +997,12 @@
           if (!this.currentField.id || !this.currentField.label) {
             return fail('Field ID and Label are required');
           }
+
+          // Validate regex pattern if selected
+          if (this.currentField.validate === 'regex') {
+            const pat = String(this.currentField.validatePattern || '').trim();
+            if (!pat) return fail('Regex validation requires a pattern');
+          }
           
           // Validate field ID
           if (!/^[a-zA-Z0-9._-]+$/.test(this.currentField.id)) {

package/examples/formgen-builder-uib2/src/index.html

@@ -785,18 +785,27 @@ email{{currentField.keyvalueDelimiter || '='}}john@example.com</code></pre>
           v-model="currentField.validate" 
           :options="validationTypes"
         />
-        <b-form-input 
-          v-if="currentField.validate === 'regex'"
-          v-model="currentField.validatePattern" 
-          placeholder="Regex pattern (e.g., ^[A-Z]{2}\\d{4}$)"
-          class="mt-2"
-        />
         <small class="form-text text-muted">
           <strong>Email:</strong> Validates email format (user@domain.com)<br>
           <strong>Phone:</strong> Validates phone number format (10+ digits)<br>
           <strong>Regex:</strong> Custom pattern validation (e.g., ^[A-Z]{2}\\d{4}$ for codes like AB1234)
         </small>
       </b-form-group>
+
+      <b-form-group
+        v-if="currentField.validate === 'regex'"
+        label="Regex pattern"
+        label-for="validate-pattern"
+      >
+        <b-form-input
+          id="validate-pattern"
+          v-model="currentField.validatePattern"
+          placeholder="e.g., ^([a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\.)+[a-zA-Z]{2,63}\.$"
+        />
+        <small class="form-text text-muted">
+          JavaScript RegExp source only (no <code>/.../</code> slashes). If hand-editing JSON, escape backslashes (e.g. write <code>\\.</code> not <code>\.</code>).
+        </small>
+      </b-form-group>
       
       <b-form-group label="Validation Message" label-for="validate-msg" v-if="currentField.validate">
         <b-form-input 

package/examples/formgen-builder-uib2/src/index.js

@@ -901,6 +901,17 @@
           this.editingFieldLocation = { sectionIdx, fieldIdx };
           const field = this.schema.sections[sectionIdx].fields[fieldIdx];
           this.currentField = JSON.parse(JSON.stringify(field));
+
+          // Ensure validation fields are reactive even if the saved field object did not include them
+          if (!Object.prototype.hasOwnProperty.call(this.currentField, 'validate')) {
+            this.$set(this.currentField, 'validate', null);
+          }
+          if (!Object.prototype.hasOwnProperty.call(this.currentField, 'validatePattern')) {
+            this.$set(this.currentField, 'validatePattern', '');
+          }
+          if (!Object.prototype.hasOwnProperty.call(this.currentField, 'validateMessage')) {
+            this.$set(this.currentField, 'validateMessage', '');
+          }
           
           // Normalize options
           if (this.currentField.options && Array.isArray(this.currentField.options)) {
@@ -931,8 +942,9 @@
           
           // Handle validation
           if (this.currentField.validate && this.currentField.validate.startsWith('regex:')) {
+            const raw = String(this.currentField.validate);
             this.currentField.validate = 'regex';
-            this.currentField.validatePattern = this.currentField.validate.substring(6);
+            this.currentField.validatePattern = raw.substring(6);
           }
 
           // Normalize autoFill
@@ -985,6 +997,12 @@
           if (!this.currentField.id || !this.currentField.label) {
             return fail('Field ID and Label are required');
           }
+
+          // Validate regex pattern if selected
+          if (this.currentField.validate === 'regex') {
+            const pat = String(this.currentField.validatePattern || '').trim();
+            if (!pat) return fail('Regex validation requires a pattern');
+          }
           
           // Validate field ID
           if (!/^[a-zA-Z0-9._-]+$/.test(this.currentField.id)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyprnet/node-red-contrib-uibuilder-formgen",
-  "version": "0.5.29",
+  "version": "0.5.35",
   "description": "PortalSmith: Generate schema-driven uibuilder form portals from JSON",
   "keywords": [
     "node-red",

package/templates/index.js.mustache

@@ -1213,14 +1213,34 @@
                 error = 'Please enter a valid phone number';
               }
             } else if (field.validate.startsWith('regex:')) {
-              const pattern = field.validate.substring(6);
+              const raw = String(field.validate).substring(6);
+              const s = String(raw || '').trim();
               try {
-                const regex = new RegExp(pattern);
-                if (!regex.test(value)) {
+                // Support both:
+                // - regex:<pattern>
+                // - regex:/<pattern>/<flags>
+                // (Note: slashes are NOT required; they are optional for user convenience.)
+                let regex;
+                if (s.startsWith('/') && s.lastIndexOf('/') > 0) {
+                  const lastSlash = s.lastIndexOf('/');
+                  const body = s.slice(1, lastSlash);
+                  const flags = s.slice(lastSlash + 1);
+                  if (/^[gimsuy]*$/.test(flags)) {
+                    regex = new RegExp(body, flags);
+                  } else {
+                    // Invalid flags - fall back to raw pattern (so we still fail visibly if invalid)
+                    regex = new RegExp(s);
+                  }
+                } else {
+                  regex = new RegExp(s);
+                }
+                if (!regex.test(String(value))) {
                   error = field.validateMessage || 'Invalid format';
                 }
               } catch (e) {
-                console.warn('Invalid regex pattern:', pattern);
+                console.warn('Invalid regex pattern:', s, e);
+                // Treat misconfigured regex as a validation error so it is visible
+                error = field.validateMessage || 'Invalid validation pattern (regex)';
               }
             }
           }

package/templates/index.v3.js.mustache

@@ -747,18 +747,62 @@
           if (!field || !field.id) return true;
           const v = this.formData[field.id];
           let err = '';
+
+          // Required validation
           if (field.required) {
             if (field.type === 'checkbox') {
-              if (!v) err = 'Required';
+              if (!v) err = field.validateMessage || 'Required';
             } else if (field.type === 'keyvalue' && field.keyvalueMode === 'delimiter') {
               const lines = keyvalueDelimiterLines(v);
-              if (!lines.length) err = 'Required';
+              if (!lines.length) err = field.validateMessage || 'Required';
             } else if (Array.isArray(v)) {
-              if (!v.length) err = 'Required';
+              if (!v.length) err = field.validateMessage || 'Required';
             } else {
-              if (v === null || v === undefined || String(v).trim() === '') err = 'Required';
+              if (v === null || v === undefined || String(v).trim() === '') err = field.validateMessage || 'Required';
+            }
+          }
+
+          // Skip other validations if field is empty and not required
+          if (!err && (!v || String(v).trim() === '') && !field.required) {
+            this.fieldErrors[field.id] = '';
+            return true;
+          }
+
+          // Custom validators (email/phone/regex:<pattern> or regex:/pattern/flags)
+          if (!err && field.validate) {
+            const validate = String(field.validate || '').trim();
+            if (validate === 'email') {
+              const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+              if (!emailRegex.test(String(v))) err = field.validateMessage || 'Please enter a valid email address';
+            } else if (validate === 'phone') {
+              const phoneRegex = /^[\d\s\-\+\(\)]+$/;
+              const s = String(v);
+              if (!phoneRegex.test(s) || s.replace(/\D/g, '').length < 10) err = field.validateMessage || 'Please enter a valid phone number';
+            } else if (validate.startsWith('regex:')) {
+              const raw = validate.substring(6);
+              const s = String(raw || '').trim();
+              try {
+                let regex;
+                if (s.startsWith('/') && s.lastIndexOf('/') > 0) {
+                  const lastSlash = s.lastIndexOf('/');
+                  const body = s.slice(1, lastSlash);
+                  const flags = s.slice(lastSlash + 1);
+                  if (/^[gimsuy]*$/.test(flags)) {
+                    regex = new RegExp(body, flags);
+                  } else {
+                    regex = new RegExp(s);
+                  }
+                } else {
+                  regex = new RegExp(s);
+                }
+                if (!regex.test(String(v))) err = field.validateMessage || 'Invalid format';
+              } catch (e) {
+                console.warn('Invalid regex pattern:', s, e);
+                err = field.validateMessage || 'Invalid validation pattern (regex)';
+              }
             }
           }
+
           this.fieldErrors[field.id] = err;
           return !err;
         },