Node Property Panels (UI Blocks)

When a node is selected in the builder, its property panel is what the user fills in to configure an operation. By default that panel is a single Adaptive Card declared in the node manifest.

The UI Blocks system lets an operation compose its panel from an ordered list of blocks instead — mixing Adaptive Card sections with purpose-built widgets such as an expression editor, a key/value editor, or a JSON editor.

Adding a UI block to a manifest

Edit your node's manifest.json and add a ui key to any operation:

{
  "name": "executeQuery",
  "input_fields": {
    "query":  { "type": "string", "required": true },
    "params": { "type": "array",  "required": false }
  },

  "adaptive_card": { /* ... fallback ... */ },

  "ui": {
    "version": 1,
    "blocks": [
      {
        "id": "query",
        "type": "custom",
        "component": "expression-editor",
        "props": {
          "path": "query",
          "language": "sql",
          "label": "SQL Query",
          "placeholder": "SELECT * FROM users WHERE id = $1",
          "rows": 6
        }
      },
      {
        "id": "params",
        "type": "adaptive_card",
        "card": {
          "type": "AdaptiveCard",
          "version": "1.5",
          "body": [
            { "type": "TextBlock", "text": "Parameters (JSON array)" },
            {
              "type": "Input.Text",
              "id": "args.state.params",
              "value": "${params}"
            }
          ]
        }
      }
    ]
  }
}

Built-in custom blocks

expression-editor

A single-line/multi-line editor for one string field, with quick-insert chips for {{input}}, {{output}}, and {{$node}} template expressions.

Prop	Type	Notes
path	string	Required. args.state key to edit.
label	string	Field label.
placeholder	string	Placeholder text.
rows	number	Textarea height.
language	string	Shown as a hint (e.g. sql).
helpText	string	Helper text below the field.
default	any	Seed value when args.state has none yet.

key-value

An editable list of string key/value pairs, stored as a flat object.

Prop	Type	Notes
path	string	Required.
label	string	Field label.
keyPlaceholder	string	Placeholder for key inputs.
valuePlaceholder	string	Placeholder for value inputs.

json

A JSON editor with live validation.

Prop	Type	Notes
path	string	Required.
label	string	Field label.
placeholder	string	Placeholder text.
rows	number	Textarea height.
helpText	string	Helper text below the field.
default	any	Seed value when args.state has none yet.

Rules

• Keep the legacy adaptive_card. It is the fallback when an app build predates UI Blocks support.
• Don't add Action.Submit buttons to cards inside a composed panel. In multi-block mode submit actions are stripped automatically — the panel's single Apply button handles saving.
• Manifests are pure data. A custom block can only reference a component by name; it can never ship code.
• Malformed ui is safe. An invalid version, duplicate block ids, or a missing component cause the panel to log a warning and fall back to the legacy adaptive_card.

Deploying a manifest change

After editing a manifest, re-seed the local registry and reload the builder:

cd fluidgrids-nodes
bun scripts/seed-nodes.ts

In alpha and production, manifest changes flow through the normal node deploy pipeline.

Source

• Repository: github.com/algoshred/fluidgrids-nodes

Next steps

• Custom Nodes
• Examples