feat: Show multiple formula expression examples (baserow#5981)

* Added support for multiple examples in formula expression help tooltip.

* Show an icon to indicate that an example can be inserted.

Author: paljort

changelog/entries/unreleased/feature/5442_added_support_for_multiple_examples_in_formula_expression_he.json

@@ -0,0 +1,9 @@
+{
+    "type": "feature",
+    "message": "Added support for multiple examples in formula expression help tooltip.",
+    "issue_origin": "github",
+    "issue_number": 5442,
+    "domain": "core",
+    "bullet_points": [],
+    "created_at": "2026-09-03"
+}

web-frontend/locales/en.json

@@ -686,6 +686,7 @@
     "minuteDescription": "Returns the minute from the date time argument.",
     "secondDescription": "Returns the second from the date time argument.",
     "todayDescription": "Returns the current date.",
+    "nowDescription": "Returns the current date and time.",
     "getPropertyDescription": "Returns the property from the object.",
     "randomIntDescription": "Returns a random integer from the range specified by the arguments.",
     "randomFloatDescription": "Returns a random float from the range specified by the arguments.",

web-frontend/modules/core/assets/scss/components/node_help_tooltip.scss

@@ -42,6 +42,75 @@
 
     @extend %mb-16;
   }
+
+  &__examples {
+    display: flex;
+    flex-direction: column;
+    gap: 12px;
+
+    // Fits three examples, including the extra padding of the clickable
+    // variant. Longer lists scroll.
+    max-height: 260px;
+    overflow-y: auto;
+
+    // Clickable examples carry their own padding so the hover background can
+    // bleed past the snippet. Offset the container by the same amount so the
+    // snippets stay aligned with the label above.
+    &--clickable {
+      margin: 0 -6px;
+      padding: 0 6px;
+    }
+  }
+
+  &__example-footer {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 8px;
+    margin-top: 12px;
+    font-size: 12px;
+    color: $palette-neutral-1100;
+  }
+
+  &__example-result {
+    min-width: 0;
+    overflow-wrap: anywhere;
+  }
+
+  // Signals that clicking the example inserts it into the formula. Pushed to
+  // the far end of the footer so it sits opposite the result, and stays there
+  // when the example has no result.
+  &__example-insert-icon {
+    margin-left: auto;
+    flex-shrink: 0;
+    font-size: 12px;
+    color: $palette-neutral-700;
+  }
+
+  &__example--clickable {
+    cursor: pointer;
+    padding: 6px;
+
+    @include rounded($rounded);
+
+    &:hover {
+      background: $palette-neutral-200;
+
+      .node-help-tooltip__example-insert-icon {
+        color: $palette-neutral-1200;
+      }
+    }
+
+    .node-help-tooltip__example-code {
+      pointer-events: none;
+    }
+  }
+
+  &__examples-hint {
+    margin: 8px 0 0;
+    font-size: 11px;
+    color: $palette-neutral-700;
+  }
 }
 
 .node-help-tooltip-context {

web-frontend/modules/core/components/formula/FormulaInputExplorerContext.vue

@@ -15,6 +15,7 @@
       :loading="loading"
       @node-selected="$emit('node-selected', $event)"
       @node-unselected="$emit('node-unselected')"
+      @example-click="$emit('example-click', $event)"
     />
     <div
       v-if="advancedModeEnabled"
@@ -113,14 +114,10 @@ export default {
       required: true,
     },
   },
-  emits: ['mode-changed', 'node-selected', 'node-unselected'],
+  emits: ['mode-changed', 'node-selected', 'node-unselected', 'example-click'],
   data() {
     return {
       searchQuery: '',
-      tooltip: {
-        functionData: null,
-      },
-      tooltipTimer: null,
       tabs: [],
       isModalVisible: false,
     }
@@ -141,7 +138,6 @@ export default {
     },
     activeTabIndex() {
       this.searchQuery = ''
-      this.hideTooltip()
     },
   },
   created() {
@@ -165,7 +161,6 @@ export default {
     },
     hide() {
       this.$refs.context.hide()
-      this.hideTooltip()
     },
     getTabTitle(tabName) {
       const titleMap = {
@@ -203,48 +198,6 @@ export default {
         this.$emit('mode-changed', 'advanced')
       }
     },
-    onFunctionHover(item, tabName, event) {
-      if (tabName !== 'Functions') {
-        return
-      }
-
-      if (this.tooltipTimer) {
-        clearTimeout(this.tooltipTimer)
-      }
-
-      this.tooltip.functionData = {
-        name: item.name,
-        description: item.description,
-        example: item.example,
-        icon: item.icon,
-      }
-
-      this.tooltipTimer = setTimeout(() => {
-        if (this.$refs.functionHelpTooltip) {
-          this.$refs.functionHelpTooltip.show(
-            event.target,
-            'bottom',
-            'right',
-            5,
-            10
-          )
-        }
-      }, 300)
-    },
-    onFunctionLeave() {
-      if (this.tooltipTimer) {
-        clearTimeout(this.tooltipTimer)
-        this.tooltipTimer = null
-      }
-
-      this.hideTooltip()
-    },
-    hideTooltip() {
-      if (this.$refs.functionHelpTooltip) {
-        this.$refs.functionHelpTooltip.hide()
-      }
-      this.tooltip.functionData = null
-    },
     showAdvancedModeModal() {
       this.$refs.advancedModeModal.show()
     },

web-frontend/modules/core/components/formula/FormulaInputField.vue

@@ -69,11 +69,13 @@
       :enabled-modes="enabledModes"
       @node-selected="handleNodeSelected"
       @node-unselected="unSelectNode"
+      @example-click="handleExampleSelected"
       @mode-changed="handleModeChange"
       @mousedown="onContextMouseDown"
     />
 
     <NodeHelpTooltip
+      v-if="!readOnly"
       ref="nodeHelpTooltip"
       :node="hoveredFunctionNode"
       :nodes-hierarchy="nodesHierarchy"
@@ -398,17 +400,24 @@ export default {
             this.$refs.formulaInputExplorerContext?.hide()
           },
         }),
-        FunctionHelpTooltipExtension.configure({
-          functionDefinitions: this.formulaRegistry.definitions,
-          onShowTooltip: (el, node) => {
-            this.hoveredFunctionNode = node
-            this.$refs.nodeHelpTooltip?.show(el, 'bottom', 'right', 6, 10)
-          },
-          onHideTooltip: () => {
-            this.$refs.nodeHelpTooltip?.hide()
-            this.hoveredFunctionNode = null
-          },
-        }),
+        // Read-only fields are display-only snippets (e.g. the examples
+        // rendered inside `NodeHelpTooltip` itself), so they must not spawn
+        // their own hover help tooltip.
+        ...(this.readOnly
+          ? []
+          : [
+              FunctionHelpTooltipExtension.configure({
+                functionDefinitions: this.formulaRegistry.definitions,
+                onShowTooltip: (el, node) => {
+                  this.hoveredFunctionNode = node
+                  this.$refs.nodeHelpTooltip?.show(el, 'bottom', 'right', 6, 10)
+                },
+                onHideTooltip: () => {
+                  this.$refs.nodeHelpTooltip?.hide()
+                  this.hoveredFunctionNode = null
+                },
+              }),
+            ]),
         ...this.formulaComponents,
       ]
 
@@ -598,7 +607,11 @@ export default {
      * renders without any error styling until the field is touched.
      */
     validateFormula(formula) {
-      if (this.isRawMode) {
+      // Raw mode holds plain text, not a formula. Read-only fields are
+      // display-only snippets (e.g. the examples in the help tooltip) that
+      // never show an error context, so don't paint them as errors either:
+      // an example may deliberately be incomplete, like `get()` without a path.
+      if (this.isRawMode || this.readOnly) {
         this.isFormulaInvalid = false
         this.formulaErrorContext = { scope: null, title: '', message: '' }
         return true
@@ -697,6 +710,22 @@ export default {
           break
       }
     },
+    /**
+     * Inserts a clicked help-tooltip example at the cursor. Only advanced
+     * mode can host the function nodes examples parse into; the explorer's
+     * function tab (and thus a clickable tooltip) only exists in that mode.
+     */
+    handleExampleSelected(example) {
+      if (this.mode !== 'advanced') {
+        return
+      }
+      const content = this.toContent(example.formula)
+      const fragment = content?.content?.[0]?.content
+      if (!fragment) {
+        return
+      }
+      this.editor.commands.insertFormulaFragment(fragment)
+    },
     onContextMouseDown() {
       this.editor?.commands.handleContextMouseDown()
     },

web-frontend/modules/core/components/formula/extensions/FormulaNodes.js

@@ -363,6 +363,17 @@ export const FormulaInsertionExtension = Extension.create({
 
           commands.focus()
 
+          return true
+        },
+      insertFormulaFragment:
+        (content) =>
+        ({ commands }) => {
+          // ZWS-bracketed like the other insert commands; ZWSManagementExtension
+          // removes any consecutive ZWS this may create.
+          commands.insertContent([zwsTextJSON(), ...content, zwsTextJSON()])
+
+          commands.focus()
+
           return true
         },
       insertOperator:

web-frontend/modules/core/components/nodeExplorer/NodeExplorer.vue

@@ -28,6 +28,7 @@
               :allow-node-selection="allowNodeSelection"
               @reset-search="resetSearch"
               @node-selected="$emit('node-selected', $event)"
+              @example-click="$emit('example-click', $event)"
               @toggle="toggleNode"
             />
           </Tab>
@@ -43,6 +44,7 @@
             :allow-node-selection="allowNodeSelection"
             @reset-search="resetSearch"
             @node-selected="$emit('node-selected', $event)"
+            @example-click="$emit('example-click', $event)"
             @toggle="toggleNode"
           />
         </template>
@@ -96,7 +98,7 @@ export default {
       validator: (value) => ['none', 'all', 'array', 'object'].includes(value),
     },
   },
-  emits: ['node-selected', 'node-toggled', 'node-unselected'],
+  emits: ['node-selected', 'node-toggled', 'node-unselected', 'example-click'],
   data() {
     return {
       activeTabIndex: 0,