QueryBuilder Component

The QueryBuilder is a versatile utility component designed for constructing database queries. it supports multiple operation modes, including a visual UI builder and direct SQL entry. It is designed to be highly compact and embeddable within sidebar settings or small UI subsections.

Location

valstorm-components-15/components/AppBuilder/components/Utility/QueryBuilder

---

Features

• Multiple Editor Modes:
  • UI Builder: A human-readable interface for building queries without writing code.
  • Custom SQL: A direct text-entry area for advanced SQL queries.
  • Mongo Query: (Coming Soon) Direct MongoDB query support.
• Collapsible Interface: Can be collapsed to save space, showing a truncated preview of the compiled query in the header.
• Smart SQL Compiler: Automatically converts UI configurations into valid SQL strings, handling operator-specific syntax (e.g., LIKE '%val%', IN (a, b)).
• Live Preview: Displays the resulting SQL query in real-time as you use the visual builder.
• Debounced Updates: Typing in custom SQL or rule values is debounced by 750ms to prevent overwhelming backends with partial queries during active editing.
• Controlled & Uncontrolled Support: Can be used as a standalone App Builder node or as a controlled input within other components (like ListViewSettings).

---

Props

Prop	Type	Default	Description
props	object	-	Standard App Builder props including appId, node, and handleClick.
value	object	-	(Optional) The current state object. Including this makes the component controlled.
onChange	function	-	(Optional) Callback fired when the query configuration changes.
showRunButton	boolean	true	Whether to display the "Run Query" button.
defaultCollapsed	boolean	false	Whether the component should start in a collapsed state.

---

State Structure (value)

The component manages a complex JSON object that represents both the UI state and the compiled output:

{
  "query_mode": "UI Builder",
  "sql_query": "SELECT * FROM users WHERE status = 'active' LIMIT 25 OFFSET 0",
  "ui_configuration": {
    "select": ["*"],
    "from": "users",
    "where": {
      "logical_operator": "AND",
      "rules": [
        { "field": "status", "operator": "=", "value": "active" }
      ]
    },
    "limit": 25,
    "offset": 0
  }
}

---

Usage Examples

1. Controlled Usage (Inside another component)

import { QueryBuilder } from "./QueryBuilder.component";

const MySettings = ({ filter, onUpdate }) => {
  return (
    <QueryBuilder
      value={{
        query_mode: filter.query_mode,
        sql_query: filter.query,
        ui_configuration: filter.ui_configuration
      }}
      onChange={(newValue) => {
        onUpdate({
          query_mode: newValue.query_mode,
          query: newValue.sql_query,
          ui_configuration: newValue.ui_configuration
        });
      }}
      defaultCollapsed={true}
      showRunButton={false}
    />
  );
}

2. Standard App Builder Node

When added to an App Builder page, the component uses the node.props.data for its state and behaves as an interactive widget.

---

Key Sub-Components

VisualQueryBuilder

Handles the rendering of the "UI Builder" mode.

• Select Fields: Multi-select autocomplete for table properties.
• From Table: Selection of available system schemas.
• Filters (Where): Dynamic list of rule rows.
• Adjustments: Vertical stack for Limit and Offset inputs.

Header Actions

The header includes an expand/collapse toggle and an Editor Mode selector. The mode selector allows users to "Eject" from the UI builder into Custom SQL.

Note: Switching from UI Builder to Custom SQL will populate the textarea with the compiled SQL. However, manually editing the SQL and then switching back to the UI Builder may result in a loss of manual SQL changes as the UI Builder state takes precedence when re-active.

ListViewSettings Component

The ListViewSettings component provides a comprehensive management interface for list_filter records. It allows users to configure how data is queried, displayed, and interacted with across various view modes (Table, List, Kanban).

Location

valstorm-components-15/components/AppBuilder/components/Utility/ListViewSettings

---

Features

• Filter Management:
  • Save/Update: Persist changes to the list_filter record.
  • Clone: Create a new copy of the current filter configuration.
  • Delete: Remove the current filter record.
• Dynamic Schema Integration: Automatically fetches and maps fields based on the selected target object.
• Multi-View Support:
  • General: Configure filter name and the underlying data object.
  • Query: Integrated QueryBuilder for visual or SQL-based data sourcing.
  • Default View: Set the starting view mode (Table, Kanban, List, or JSON).
  • Field Selection: Choose which fields appear in List and Table views.
  • Table Tweaks: Adjust column selection and individual column widths.
  • Kanban Mapping: Define grouping columns (Picklists only), swimlanes, and card content.
• Real-time Previews: Dispatches update_list_filter events to the system, allowing other components on the page to reflect configuration changes immediately without saving.

---

Props

Prop	Type	Default	Description
props	object	-	Standard App Builder props including appId, node, handleClick, and componentId.

---

Technical Details

State Management

The component uses a local filter state initialized from the selectedFilter provided by the useFilterState hook. It also listens to the eventSystem for edit_list_filter and switch_list_filter events to stay in sync with the user's focus.

Integration with QueryBuilder

The component leverages the QueryBuilder in controlled mode:

<QueryBuilder
  value={{
    query_mode: filter.query_mode,
    sql_query: filter.query,
    ui_configuration: filter.ui_configuration
  }}
  onChange={(newValue) => {
    // Updates filter state and dispatches update_list_filter event
  }}
  defaultCollapsed={true}
  showRunButton={false}
/>

Events

Event Type	Payload	Description
update_list_filter	filter record	Fired on any change to provide live previews.
open_clone_record_modal	{ record, schema }	Fired when clicking the Clone button.

---

Usage

Typically rendered in a sidebar or configuration panel within the App Builder or a Management interface to allow users to customize their data views.

---

TagCreator Component

The TagCreator is a specialized AppBuilder Utility component designed to manage the creation and modification of tag records within the Valstorm platform. It streamlines the process of defining picklist options, global tags, and conditional dependencies.

Purpose

In the Valstorm system, picklists and multi-select fields are driven by the tag object. Instead of manually editing JSON schemas or raw database records, this component provides a guided, two-step wizard to ensure tags are created with correct metadata, linking them to the right objects and fields.

Component Configuration (Schema)

When adding this component in the AppBuilder, the following properties can be configured:

Property	Type	Description
api_name	String	A unique identifier for this instance of the component.
class_name	String	Optional CSS classes for container styling (e.g., flex flex-col p-4).

AppBuilder Integration

The component is registered under the Utility category in the ComponentRegistry.ts.

State Management

It follows the standard AppBuilder architectural pattern:

• instanceState: It consumes record and editRecord from the appInstanceStateFamily(appId).
• Reactive UI: It automatically switches to Edit Mode if a record.id is present in the instance state.
• Injected Context: If opened from a ViewFieldMeta popup, it picks up injected metadata (Object and Field API name) to pre-fill the form.

Internal Logic

• Two-Step Wizard:
  1. Scope Selection: Choice between "Object Specific" (field-linked) and "Global" (reusable).
  2. Tag Details: Form for value, label, color, order, and dependencies.
• Dynamic Name Generation: The name field is automatically synced based on the scope (e.g., Lead - status - Lost).
• Tag Order Preview: A visual section that fetches existing tags in the same context and shows where the current tag will sit in the sequence, using the KanbanColumn top-border style.
• API Interactions: Uses useApiHook to perform POST for new tags and PATCH for updates.

Activity Feed Component

The Activity Feed component provides a centralized, real-time stream of high-priority items, including notifications (texts, calls, emails) and upcoming tasks.

🚀 Key Features

• Unified View: Combines unread system notifications with results from custom object queries (e.g., pending tasks).
• Real-time Updates: Listens to the global recordsState to instantly reflect changes, completions, or deletions made anywhere in the application.
• Quick Actions: Perform common tasks directly from the feed:
  • Dismiss: Mark notifications as read.
  • Complete: Update task status to "Completed" with one click.
  • Call Back: Initiate an outbound call for missed calls or tasks with phone numbers.
  • Details: Navigate directly to the record or associated URL.
• Dense Design: A modern, high-density Tailwind CSS layout optimized for homepages and dashboards.

🛠️ How to Use

1. Add to Canvas: Drag "Activity Feed" from the "Utility" category.
2. Configure Queries: Add sections in the "Additional Feed Items" setting to pull in specific records like "My Upcoming Tasks".
3. Style: Use the Class Name field to add Tailwind utility classes for custom spacing or borders.

⚙️ Settings Reference

Property	Description
API Name	A unique identifier for this component instance.
Show Notifications	Toggle to include unread system notifications in the feed.
Max Items	The maximum number of total items to display in the list.
Additional Feed Items	A list of custom SQL queries to pull in other objects (e.g., Tasks, Events).
Class Name	Custom Tailwind CSS classes for the container.