# NGX View Builder

> NGX View Builder is a visual builder for complete Angular views: forms, dashboards, data tables, and guided flows are designed in a drag-and-drop builder, stored as JSON, and rendered natively in an Angular app.

This file contains the full text of every documentation page, concatenated for AI agents and tools that cannot crawl links. See https://ngxviewbuilder.io/llms.txt for a linked index instead.

---

## Live builder command API

Source: https://ngxviewbuilder.io/ai/command-api

# Live builder command API

Everything else in this section teaches you to **write** structure JSON. This page is about the other mode: when a builder is open in a browser you can reach, you can **read and edit the live view directly**, one JSON command at a time, and see the result immediately.

## Detect the mode first

The live mode arrives as an MCP server. If your client has the `nvb_*` tools, call `nvb_status`.

| Result | What it means | What to do |
| --- | --- | --- |
| `paired` and `builder_attached` are `true` | A builder is open and the API is armed | Drive it with commands. Do not hand back raw JSON for a person to paste. |
| `builder_attached` is `false` | The tab is connected but the builder is not on screen | Ask the user to open the builder. |
| `browser_connected` is `false` | The paired tab was closed or lost its socket | Ask the user to reopen the builder and re-pair. |
| An error mentioning a pair code | Nothing is paired yet | Ask the user for the code shown in the builder settings, under AI access (MCP). |
| No `nvb_*` tools at all | Runtime only host, or no MCP server configured | Fall back to authoring structure JSON as the rest of this section describes. |

The bridge is open only while the builder component is mounted. It closes when the user leaves the builder, so re-check before a long sequence.

## Bootstrap sequence

Run these before writing anything. They cost one round trip and remove almost every source of error.

```text
nvb_status                    1. is the door open
nvb_get_instructions          2. the contract as text, plus the command catalog
nvb_describe_element_types    3. real element types and their real property keys
nvb_get_tree                  4. what already exists, and the row indexes you need
```

`nvb_get_instructions` is the fastest way in: it states what the API is, the working order, the rules, the capabilities this builder has, and the templates already in the library. It returns `help()` in the same call, so `help.guidelines` carries the rules on their own and `help.capabilities` tells you which optional features are present.

`help()` is authoritative and versioned. If it disagrees with this page, follow `help()`.

**Never guess a property name.** `describeElementTypes(type)` returns the exact keys the builder accepts for that type. Guessing produces a warning and a property the runtime ignores, which is worse than an error because it looks like it worked.

## The one write door

```js
const result = await api.execute(commandOrArray, options);
```

Over MCP that is `nvb_execute`, with the array under `commands` and the options as flat
arguments (`dry_run`, `return_tree`, `return_structure`). The snippets below show the command
shapes, which are the same either way.

Hard rules:

1. **An array is atomic.** If one command fails, none are applied. Prefer one batch over a sequence of single calls, so a partial build cannot happen.
2. **Use `{ dryRun: true }` first** for anything large or destructive. It runs every check and reports `changed` without touching the view.
3. **Read `warnings`, not just `errors`.** `ok: true` with warnings means something landed that the builder does not recognise.
4. **Act on `hint`.** Errors carry a concrete correction. One retry using the hint should succeed; if it does not, stop and ask rather than looping.
5. **There is no save.** You can build and edit freely, but a person commits the view. Do not claim you saved anything, and do not try to reach a save through a trigger or an element event: automation actions have no submit or save type, and an element `submit` still needs a human click.
6. **Re-check `available()` after anything slow.** The API disarms the moment the user leaves the builder, and every command then fails with `apiClosed` while every read returns null. That is expected, not a fault.

### Result shape

```json
{
  "ok": true,
  "version": 1,
  "dryRun": false,
  "applied": 3,
  "changed": ["contact", "email", "phone"],
  "errors": [],
  "warnings": ["[2] addElement: 'select' has no registered property 'placeholder'."]
}
```

### Error codes

| Code | Meaning | Recovery |
| --- | --- | --- |
| `apiClosed` | The builder is not on screen | Ask the user to open it |
| `unknownType` | Element type does not exist | Use the `hint`, or call `describeElementTypes()` |
| `unknownElement` | No element with that name | Use the `hint`, or call `getTree()` |
| `notAContainer` | The parent cannot hold children | Pick a container from the hint list |
| `missingTab` | Tab style container needs a section | Pass `tab` |
| `nameTaken` | Name already used | Pick another, or use `updateElement` |
| `invalidName` | Name is not a valid identifier | Letters, digits, underscores, starting with a letter |
| `cycle` | The target sits inside the element being moved | Pick a different parent |
| `capabilityMissing` | The command needs a feature pack this builder does not have | Build without it, per the hint |
| `unknownTemplate` | No template with that name | Call `describeTemplates()`, or create it with `upsertTemplate` |

## Layout is the part that goes wrong

A view is rows, and each row holds one or more columns. **A new element gets its own row by default, so elements stack.** To place two fields side by side, name the existing `row`.

```js
await api.execute([
  { op: 'addElement', type: 'text', name: 'firstName', parent: 'contact', properties: { label: 'First name' } },
  { op: 'addElement', type: 'text', name: 'lastName',  parent: 'contact', row: 0, properties: { label: 'Last name' } },
]);
```

Row indexes come from `getTree()` or from `addRow`. Target fields are `parent`, `page`, `tab`, `index`, `row`, `column`. See [Layout model](https://ngxviewbuilder.io/ai/layout-model) for how the same tree looks as raw JSON.

**Do not set a percentage `width` on fields you want side by side.** Columns already share the row, and a fixed width fights it. Use `mobileWidth: '100%'` to make a pair stack on phones.

For a whole section at once, `insertJson` takes the elements and the nested layout together, which is usually one command instead of five:

```js
await api.execute({
  op: 'insertJson',
  root: 'contact',
  elements: {
    contact:   { type: 'panel', label: 'Contact' },
    firstName: { type: 'text', label: 'First name', required: true },
    lastName:  { type: 'text', label: 'Last name', required: true },
  },
  rows: [{ columns: [{ elementRef: 'firstName' }, { elementRef: 'lastName' }] }],
});
```

## What you can change

Mutations: `addElement`, `insertJson`, `upsertTemplate`, `useTemplate`, `updateElement`, `deleteElement`, `moveElement`, `renameElement`, `duplicateElement`, `addRow`, `deleteRow`, `addPage`, `deletePage`, `renamePage`, `updatePage`, `setSettings`, `setHeader`, `upsertDataSource`, `deleteDataSource`, `upsertVariable`, `deleteVariable`, `upsertTrigger`, `deleteTrigger`, `upsertRule`, `deleteRule`, `upsertFragment`, `deleteFragment`, `setProcess`, `setLocalization`, `replaceStructure`.

Actions: `switchTab`, `focusElement`, `setData`, `validate`, `setLanguage`, `setUiTranslations`, `setTheme`, `saveTemplate`, `deleteTemplate`, `saveSidebarGroup`, `deleteSidebarGroup`, `setTableSettings`, `setTableFilters`, `setRuntimeVariableContext`, `reloadDataSource`, `undo`, `redo`.

Mutations are applied to a draft in order and committed together. Actions run afterwards, in order. Call `help()` for the parameters of each.

## Reuse before you invent

Two habits save most of the rework.

**Pick the element type that already does the job.** Call `describeElementTypes()` and choose from it. `customHtml` and hand written template markup carry no options, no validation and no events, so anything assembled that way has to be rebuilt later. The case that comes up most is a table column showing a status or a badge: that is a hosted element, `type: 'element'` with `elementType: 'badge'`, not markup.

**Look in the template library before creating a template.** When `help().capabilities` includes `templates`, the view has one:

```js
api.describeTemplates();   // { available, hosts, templates: [{ name, slots, hasCss, ... }] }
```

If the user names a card and that name is already in the library, reuse it. Create a missing one with `upsertTemplate` and bind it with `useTemplate`, which resolves the right reference property for the element type on its own:

```js
await api.execute([
  { op: 'upsertTemplate', name: 'person card', content: '<div><b>{{row[0]}}</b> {{row[1]}}</div>' },
  { op: 'useTemplate', name: 'peopleGrid', template: 'person card', fieldMap: { '0': 'fullName', '1': 'email' } },
]);
```

Both need the `templates` capability and fail with `capabilityMissing` without it, because the reference properties are hidden then and the binding would render nothing.

## Checking your own work

```js
await api.execute([
  { op: 'switchTab', tab: 'preview' },
  { op: 'setData', data: { age: 25 } },
  { op: 'validate' },
]);
```

`setData` pushes values through the same pipeline as typing, so `visibleIf`, `requireIf` and computed expressions re-evaluate. `validate` returns the issues.

**Do not use `validate` to test whether a section is visible.** It runs on a fresh copy and does not apply container visibility to children, so a field inside a hidden panel is still reported as required. Read the preview instead.

Note that a mutation rebuilds the view, which clears working data. Set data after your last structural change, not before.

## Your changes are one undo step

Each `execute()` call is bracketed with a history checkpoint, so a whole batch collapses into a single undo for the user. `getAuditLog()` shows every call you made this session, which is worth reading back before you claim what you did.

## What gets checked

Element types, property names, layout targets, name collisions and cycles are checked. So are the properties whose value is structured: `options` entries need a `value`, `validators` need a known `type` (and `custom` also needs a `condition`), `events` need a known action `type`, and nested elements in `columns` or `template` need a known type and a name.

Everything else in an element body passes through untouched. That is why warnings matter: a misspelled property still lands and the runtime ignores it.

## Rules that still apply

Everything in [JSON authoring rules](https://ngxviewbuilder.io/ai/json-authoring-rules), [Element rules](https://ngxviewbuilder.io/ai/element-rules) and [Properties reference](https://ngxviewbuilder.io/ai/properties-reference) applies unchanged. The command API changes how the JSON gets in, not what valid JSON looks like.

---

## AI reference

Source: https://ngxviewbuilder.io/ai/

# AI reference

This section is the **single indexed knowledge base for AI agents** that generate or modify NGX View Builder structure JSON. It is written for machine consumption first: an agent driving the builder over [MCP](https://ngxviewbuilder.io/developers/ai-command-api) loads slices of these pages into its prompts, and any other LLM setup (ChatGPT, Claude, a custom pipeline) can use the same pages as system-prompt material.

Everything here has one goal: the agent must behave as a **strict NGX View Builder JSON author**, using real elements, documented properties and valid references, never as a generic frontend generator.

## Reading order

An agent (or a person building prompts) should consume the pages in this order:

0. [Live builder command API](https://ngxviewbuilder.io/ai/command-api): check this first. If a builder is open and reachable, you edit it directly with JSON commands instead of handing back structure JSON. The authoring rules below still apply either way.
1. [Generation contract](https://ngxviewbuilder.io/ai/generation-contract): the core rules of engagement and output modes.
2. [Layout model](https://ngxviewbuilder.io/ai/layout-model): how `pages`, `rows`, `columns` and `elementRef` relate to the flat `elements` map. **Non-negotiable prerequisite for writing any structure JSON.**
3. [JSON authoring rules](https://ngxviewbuilder.io/ai/json-authoring-rules): the structure skeleton and hard rules.
4. [Element selection map](https://ngxviewbuilder.io/ai/element-selection-map): mapping user intent to the right element type.
5. [Logic & expression properties](https://ngxviewbuilder.io/ai/logic-and-expressions): `visibleIf`, `expression`, and friends.
6. [Element rules & value shapes](https://ngxviewbuilder.io/ai/element-rules): per-element expectations.
7. [Canonical properties reference](https://ngxviewbuilder.io/ai/properties-reference): the authoritative property list.
8. [Common mistakes](https://ngxviewbuilder.io/ai/common-mistakes): anti-patterns to avoid.
9. [Verified examples](https://ngxviewbuilder.io/ai/examples): complete, source-checked JSON for every element family, the full `table` feature set, dynamic tables and panels, data sources, variables and expressions.
10. [Legacy form migration](https://ngxviewbuilder.io/ai/legacy-form-migration): only when converting forms from a legacy form-builder JSON format.

## Index

| Page | What it answers | Load when |
| --- | --- | --- |
| [Live builder command API](https://ngxviewbuilder.io/ai/command-api) | Driving an open builder directly: detection, bootstrap sequence, the `execute` contract, error recovery, row targeting | First, whenever the `nvb_*` MCP tools are available |
| [Generation contract](https://ngxviewbuilder.io/ai/generation-contract) | How the agent must behave; output modes; prompt templates | Always |
| [Layout model](https://ngxviewbuilder.io/ai/layout-model) | The layout tree: `pages` → `rows` → `columns` → `elementRef`, container nesting, `tabRows`, where widths live, full worked example | Always, before any JSON is written |
| [JSON authoring rules](https://ngxviewbuilder.io/ai/json-authoring-rules) | Skeleton, `pages`/`elements` rules, naming, layout, value shapes | Always |
| [Canonical properties reference](https://ngxviewbuilder.io/ai/properties-reference) | Every supported property per element type, settings, data sources | Always |
| [Element rules & value shapes](https://ngxviewbuilder.io/ai/element-rules) | Per-element usage rules and value shapes | Always |
| [Common mistakes](https://ngxviewbuilder.io/ai/common-mistakes) | Known anti-patterns with corrections | Always; especially in review mode |
| [Verified examples](https://ngxviewbuilder.io/ai/examples) | Complete working JSON: layout, all element families, `table` end to end, `dynamicTable`, `dynamicPanel`, data sources, variables, expressions, actions | When building anything non-trivial; always for `table` |
| [Element selection map](https://ngxviewbuilder.io/ai/element-selection-map) | Which element type fits the user's intent | When element choice is ambiguous |
| [Logic & expression properties](https://ngxviewbuilder.io/ai/logic-and-expressions) | Expression fields, syntax rules, correct/incorrect examples | When the request involves logic |
| [Legacy form migration](https://ngxviewbuilder.io/ai/legacy-form-migration) | Element/property/expression mapping from a legacy form-builder JSON format | When converting legacy form JSON |
| [API service reference](https://ngxviewbuilder.io/developers/api-service), [Events reference](https://ngxviewbuilder.io/developers/events) | What every host API method / event does, its parameters, payloads and return values | When the user asks a development or integration question |

Every JSON block on those pages is machine-checked against the library source by `npm run validate:ai-json` in this repo: element types against the element registry, property names against the builder property datasets, sub-objects against their TypeScript interfaces. If a property appears in these docs, it exists.

## Using this with ChatGPT, Claude or Gemini

Three single-file bundles are published, in increasing size:

| File | Contains | Use it when |
| --- | --- | --- |
| [`/llms.txt`](https://ngxviewbuilder.io/llms.txt) | a linked index, a few KB | the model can fetch URLs itself |
| [`/llms-authoring.txt`](https://ngxviewbuilder.io/llms-authoring.txt) | **every page in this AI section**, roughly 55k tokens | the task is writing or fixing structure JSON. This is the one to paste into a chat |
| [`/llms-full.txt`](https://ngxviewbuilder.io/llms-full.txt) | the whole site, roughly 135k tokens | the question also covers embedding, the host API, events, theming or plugins |

`llms-authoring.txt` is deliberately the smaller bundle: it drops the creator guides, pricing and host-integration pages, which are noise when the only deliverable is JSON. Paste it once at the start of a session, then describe the view you want.

A caveat worth stating plainly: a pasted file is reference material, not a guarantee. Models still skim long context. The two habits that matter most are asking for the layout tree to be stated in words before the JSON, and running the result back through the [pre-return checklist](https://ngxviewbuilder.io/ai/json-authoring-rules#pre-return-checklist).

The agent does more than write JSON. It also **consults developers**: what an API method means, what it returns, how to wire an event, how to embed the builder or runtime. For those answers the retrieval map has a dedicated `developer` source group pointing at the developer documentation.

The agent also draws on the human documentation ([element pages](https://ngxviewbuilder.io/creators/elements/), [expressions](https://ngxviewbuilder.io/creators/expressions), [conditional logic](https://ngxviewbuilder.io/creators/conditional-logic), [validation](https://ngxviewbuilder.io/creators/validation), [events & actions](https://ngxviewbuilder.io/creators/events-actions), [data sources](https://ngxviewbuilder.io/creators/data-sources) and [variables](https://ngxviewbuilder.io/creators/variables)) and on library source files: interfaces, enums and property datasets, which are always the final source of truth.

## The machine index: `retrieval-map.json`

[`retrieval-map.json`](https://ngxviewbuilder.io/ai/retrieval-map.json) (next to this page) is the machine-readable index. It maps request profiles and element types to the exact files the agent should load, with per-file character budgets:

- **`roots`**: where the docs and the library live, relative to the workspace root (the folder that contains all `ngx-view-builder*` projects).
- **`universal`**: sources injected into every prompt.
- **`types`**: per element type, which docs page, interface, and property dataset to load.
- **`selection`, `review`, `legacyForms`, `logic`, `validators`, `events`, `actions`, `data`**: sources added when the request profile matches.
- **`groupFallback`**: group-level docs used when no concrete element type was resolved.

Paths use two prefixes: `docs:` (resolved against `roots.docs`, i.e. this documentation) and `lib:` (resolved against `roots.library`, i.e. the library source). An agent loads this file at startup, so when documentation moves, updating this map is the only change needed.

---

## AI: Generation contract

Source: https://ngxviewbuilder.io/ai/generation-contract

# AI: Generation contract

This page defines the rules of engagement for `ChatGPT`, `Claude`, and other agents that generate or fix NGX View Builder structures, or consult developers about the library.

The core idea is simple: when producing structures, the agent must operate not as a generic frontend generator, but as a strict **NGX View Builder JSON** author.

## Core contract

- Generate only NGX View Builder JSON if the user explicitly asked to generate or modify a form or view.
- Do not generate custom `Angular`, `HTML`, `CSS`, `TypeScript`, an API layer, or non-existent NGX View Builder properties.
- Use only real built-in elements and documented fields.
- If the user asks for a review, a comment, or suggestions, you may respond in prose, but do not change the JSON without an explicit request.
- If the user asks to extend an existing form, the priority is to preserve the existing structure and change only what was requested.
- If the user asks a **development or integration question** (host API, events, embedding, theming, data sources), answer in prose with concrete code examples based on the developer documentation. Do not invent methods or events that are not documented.

## What the agent should read first

1. [Layout model](https://ngxviewbuilder.io/ai/layout-model)
2. [JSON authoring rules](https://ngxviewbuilder.io/ai/json-authoring-rules)
3. [Element selection map](https://ngxviewbuilder.io/ai/element-selection-map)
4. [Logic and expression properties](https://ngxviewbuilder.io/ai/logic-and-expressions)
5. [Element rules and value shapes](https://ngxviewbuilder.io/ai/element-rules)
6. [Common mistakes](https://ngxviewbuilder.io/ai/common-mistakes)

After that, consult the general reference pages:

- [Structure JSON overview](https://ngxviewbuilder.io/developers/structure-json)
- [Layout & containers](https://ngxviewbuilder.io/creators/layout)
- [Element catalog](https://ngxviewbuilder.io/creators/elements/)
- [Expressions](https://ngxviewbuilder.io/creators/expressions)
- [Canonical properties reference](https://ngxviewbuilder.io/ai/properties-reference)

For developer-consulting answers, the sources of truth are:

- [API service reference](https://ngxviewbuilder.io/developers/api-service): every host API method, its parameters and return values
- [Events reference](https://ngxviewbuilder.io/developers/events): every event the builder and runtime emit, with payloads
- [Embedding the builder](https://ngxviewbuilder.io/developers/builder-integration) and [Rendering views](https://ngxviewbuilder.io/developers/runtime-integration)
- [Data source integration](https://ngxviewbuilder.io/developers/data-sources) and [Runtime variables](https://ngxviewbuilder.io/developers/runtime-variables)

## Mandatory rules

- `pages` describes layout. `elements` describes configuration. Neither ever does the other's job.
- `elements` is a **flat** map where the key matches `element.name`. It never nests.
- `pages[*].rows[*].columns[*].elementRef` is a string that must point to an existing `elements` entry.
- Every `page` must have a corresponding `elements[pageName]` entry with `type: "page"`.
- **A container element never contains its children.** The children of a `panel`, `dynamicPanel`, `dialog` or `emptyBlock` are attached to the column that references it, in `column.rows`; for `tabs`, `tabsPro`, `accordion`, `splitter` and `progressFlow`, in `column.tabRows`. Writing `rows` (or `children`, `items`, `fields`) inside an element definition produces an empty container and orphaned fields, with no error anywhere.
- A row object has only `columns`. A column object has only `elementRef` plus `rows` / `tabRows`. Widths and other properties on a column are silently dropped; they belong on the element.
- Columns with no width split their row evenly. Do not add `"width": "50%"` to get halves.
- If there is interdependency logic between fields, use `visibleIf`, `disableIf`, `requireIf`, `readonlyIf`, `resetIf`, `expression`, and, when needed, `logicExecutionMode: "onChange"`.
- If there is a datasource scenario, use documented `dataSources` and real `dataSourceName` references.
- Do not use self-reference expressions, e.g. `"{el2} == 'x' ? 'y' : {el2}"`.
- Do not return explanatory text around the JSON if the user asked for a structure.

## Recommended system prompt template

```text
You are a strict NGX View Builder JSON generator and integration consultant.

Work only with the NGX View Builder documented JSON model and documented host API.
Do not use custom Angular, custom components, or invented properties.
If the user asks to generate or modify a form, return only valid JSON.
If the user asks for a review, comment, suggestions, or an integration/API
question, respond in prose with documented examples.

The structure has two independent halves:
- "pages" is a layout tree: pages -> rows -> columns, each column carrying an
  "elementRef" STRING.
- "elements" is a FLAT map of definitions, keyed by element name. It never nests.

Container elements (page, panel, dynamicPanel, dialog, emptyBlock, tabs, tabsPro,
accordion, splitter, progressFlow) do NOT contain their children. The children are
attached to the COLUMN that references the container, in column.rows (or
column.tabRows for the tab-like ones). Writing "rows"/"children"/"items" inside an
element definition renders an empty container and drops the fields silently.

A row object has only "columns". A column object has only "elementRef" plus
"rows"/"tabRows". Widths (width, tabletWidth, mobileWidth, fitContent) go on the
ELEMENT, and only when the split must be uneven: columns with no width already
split their row evenly.

A page is a step or screen. Titled sections on one screen are panel elements
inside a single page, never separate pages.

Before generating:
1. Decide which NGX View Builder elements best match the task.
2. List the visual rows top to bottom and count the fields per row before writing JSON.
3. Verify the required value shape and mandatory properties.
4. Verify that logic is not self-referential and that all elementRefs point to existing elements.
5. Verify that no element definition contains a rows/children/items array and that no
   column carries anything besides elementRef/rows/tabRows.
6. If extending an existing form, do not modify unrelated parts.
```

## Recommended user prompt format

Instead of a vague "create a form", give the agent these signals:

- goal: what the form should allow the user to do
- data: which fields are needed
- logic: which fields hide, compute, fill, or validate others
- data sources: what is loaded from an API or another datasource
- update mode: new form or extension of an existing one

Example:

```text
Extend an existing NGX View Builder form.
Required:
- if first name is John, last name is automatically set to Doe
- date of birth cannot be in the future
- add a dynamicTable for family members with add row and delete row
- use only NGX View Builder JSON, no comments
```

## What to do if the user's request is ambiguous

- If a term is ambiguous, decide based on the [Element selection map](https://ngxviewbuilder.io/ai/element-selection-map).
- If the user says "dynamic table", it is almost always `dynamicTable`, not `table`.
- If the user says "server-side table", "filtering", "paging", "row actions", it is almost always `table`.
- If the user wants a review or architectural assessment, do not generate new JSON without a request.

## Output modes

### 1. Generation mode

- Return only JSON.
- No markdown.
- No explanation before or after the JSON.

### 2. Review mode

- You may provide a brief analysis.
- If you suggest fixes, clearly separate comments from the proposed JSON.

### 3. Extension mode

- Preserve the entire existing form.
- Change only what is needed.
- Do not remove `settings`, `pages`, `elements`, `localization`, or `dataSources` just because they were not mentioned in the latest prompt.

### 4. Consulting mode

- The user asks how something works: a host API method, an event, embedding, theming, a data source, an expression function.
- Answer in prose with short, correct code examples (TypeScript for host API, JSON for structures).
- State what a method returns and when an event fires, exactly as documented. If the documentation does not describe it, say so instead of guessing.
- Do not generate a whole structure unless asked.

---

## AI: Layout model (pages, rows, columns, elementRef)

Source: https://ngxviewbuilder.io/ai/layout-model

# AI: Layout model (pages, rows, columns, elementRef)

This is the page that stops the single most damaging class of generated-JSON errors: getting the layout tree wrong. Read it before writing any structure JSON. If anything on this page contradicts your intuition about form builders, this page wins.

## The one rule that explains everything

NGX View Builder splits a view into **two independent halves**:

| Half | What it is | What it contains |
|---|---|---|
| `pages` | The **layout tree**. Position only. | Nested `rows` and `columns`. Each column carries one `elementRef` string. |
| `elements` | A **flat dictionary** of element definitions. Configuration only. | One entry per element, keyed by its `name`. No nesting, no children, no position. |

`elementRef` is the only bridge between them. It is a **string key into `elements`**, nothing else.

```
pages[0]                              elements
└─ rows[0]                            ┌──────────────────────────────────┐
   └─ columns[0]                      │ "firstName": { type: "text", ... }│
      └─ elementRef: "firstName" ────►│                                   │
                                      │ "lastName":  { type: "text", ... }│
   └─ columns[1]                      │                                   │
      └─ elementRef: "lastName"  ────►│ "page1": { type: "page", ... }    │
                                      └──────────────────────────────────┘
```

Two consequences that agents get wrong constantly:

1. **Structure lives only in `pages`.** An element definition never contains its children.
2. **Configuration lives only in `elements`.** A column never contains element properties.

## Exact object shapes

These are the real TypeScript interfaces (`core/shared/interfaces/structure.interface.ts`). Keys not listed here are ignored by the renderer.

```typescript
interface IStructure {
  schemaVersion?: number;
  settings: ISettings;
  header?: IHeader;
  pages: IPage[];
  elements: { [name: string]: IBaseElement };
  dataSources?: IDataSource[];
  localization?: ILocalization;
}

interface IPage {
  name: string;              // must match an elements[name] entry with type "page"
  rows: IRow[];
  status?: 'default' | 'readonly';
  disabled?: boolean;
  readOnly?: boolean;
}

interface IRow {
  columns: IColumn[];        // this is the ONLY key on a row
}

interface IColumn {
  elementRef: string;                    // required, points into elements
  rows?: IRow[];                         // children of a container element
  tabRows?: Record<string, IRow[]>;      // children of tabs/accordion/splitter/progressFlow
  fragmentRef?: string;                  // platform fragments only
  fragmentBindings?: Record<string, string>;
  fragmentMode?: 'append' | 'replace';
}
```

**A row object has exactly one key: `columns`.**
**A column object has `elementRef` plus, when the element is a container, `rows` or `tabRows`. Nothing else.**

Anything you are tempted to write on a column (`width`, `mobileWidth`, `label`, `type`, `span`, `size`, `flex`, `colSpan`) does not exist there. It is silently dropped.

## How a row renders

- A `row` is a **horizontal band**. Its `columns` sit side by side, left to right.
- Vertical order comes from the order of `rows` in the array. There is no `order` property.
- **A column with no width takes an equal share of the row.** The renderer applies `flex: 1 1 0` when the element has no `width` (`core/shared/utils/responsive-width.ts`).

So a 50/50 pair is just two columns in one row, with no widths at all:

```json
{ "columns": [{ "elementRef": "firstName" }, { "elementRef": "lastName" }] }
```

Three equal fields: three columns. One full-width field: one column. **Do not write `"width": "50%"` to get halves.** Equal split is the default, and writing widths on columns does nothing anyway.

## Where widths belong

Width is a property of the **element**, in the `elements` map:

| Property | Meaning |
|---|---|
| `width` | Desktop width, e.g. `"100%"`, `"320px"`, `"calc(50% - 8px)"` |
| `tabletWidth` | Overrides `width` on tablet |
| `mobileWidth` | Overrides `width` and `tabletWidth` on mobile |
| `fitContent` | Shrink to content instead of filling |

A bare number is treated as pixels. A percentage, `calc()`, `min()`, `max()` or `clamp()` is treated as relative and pinned exactly; a fixed size is allowed to shrink (`min(width, 100%)`).

Only set these when you need something **other** than an equal split, for example a narrow field beside a wide one:

```json
{
  "postCode": { "name": "postCode", "label": "Post code", "type": "text", "width": "160px" },
  "street":   { "name": "street",   "label": "Street",    "type": "text" }
}
```

Mobile stacking happens by giving the element `"mobileWidth": "100%"`, again on the element, never on the column.

## Nesting: the mistake that breaks everything

Container elements do **not** hold their children. The **column that references the container** holds them, in its own `rows` array.

### Wrong (children inside the element definition)

<!-- deliberately incorrect: kept as the counter-example -->

```json
{
  "pages": [
    { "name": "page1", "rows": [{ "columns": [{ "elementRef": "panelGeneral" }] }] }
  ],
  "elements": {
    "panelGeneral": {
      "name": "panelGeneral",
      "type": "panel",
      "label": "General",
      "rows": [
        { "columns": [{ "elementRef": "firstName" }, { "elementRef": "lastName" }] }
      ]
    }
  }
}
```

The panel renders **empty**. `IBaseElement` has no `rows`, so the array is ignored, and `firstName` / `lastName` are never placed anywhere.

### Right (children inside the column)

```json
{
  "pages": [
    {
      "name": "page1",
      "rows": [
        {
          "columns": [
            {
              "elementRef": "panelGeneral",
              "rows": [
                { "columns": [{ "elementRef": "firstName" }, { "elementRef": "lastName" }] }
              ]
            }
          ]
        }
      ]
    }
  ],
  "elements": {
    "page1": { "name": "page1", "type": "page", "label": "Page 1" },
    "panelGeneral": { "name": "panelGeneral", "type": "panel", "label": "General" },
    "firstName": { "name": "firstName", "type": "text", "label": "First name" },
    "lastName": { "name": "lastName", "type": "text", "label": "Last name" }
  }
}
```

Nesting is recursive: a nested column may itself carry `rows`, to any depth.

Note that `parentName` exists on `IBaseElement` but is **not** how you build the tree. Never use it to declare parentage; the layout tree is the only source of structure.

## Which element types accept children

Exactly these ten types are containers (`runtime-preview.ts`, `isContainerElement`):

| Type | Children go in | Notes |
|---|---|---|
| `page` | `page.rows` | The page itself; its rows are the top level |
| `panel` | `column.rows` | The normal grouping box, with a title from `label` |
| `dynamicPanel` | `column.rows` | Repeatable group; value is an array of objects |
| `dialog` | `column.rows` | An in-view modal element |
| `emptyBlock` | `column.rows` | Unstyled layout box with flex/grid controls |
| `tabs` | `column.tabRows` | Keyed by tab value |
| `tabsPro` | `column.tabRows` | Keyed by item value |
| `accordion` | `column.tabRows` | Keyed by item value |
| `splitter` | `column.tabRows` | Keyed by panel value |
| `progressFlow` | `column.tabRows` | Keyed by step value |

**Every other type is a leaf.** `text`, `select`, `table`, `dynamicTable`, `messageCard`, `statsCard`, `richText` and the rest never receive `rows`.

The two tables are the exception that proves the rule: their cells are declared on the element, not in the layout tree, and the two do not use the same property. `table` uses `columnsConfig`, and each entry is a column keyed by `key`. `dynamicTable` uses `columns`, and each entry is a full element definition keyed by `name`, because every cell is an editable control. Neither uses `column.rows`.

### `tabRows` keys

For tab-like containers, `tabRows` is an object keyed by the **`value` of each declared tab / item / panel / step** (falling back to `id`, then `tab1`, `tab2`, ...). The keys must match the container's own list property:

| Type | List property | Key source |
|---|---|---|
| `tabs` | `tabs` | `tabs[i].value` |
| `tabsPro` | `items` | `items[i].value` |
| `accordion` | `items` | `items[i].value` |
| `splitter` | `panels` | `panels[i].value` |
| `progressFlow` | `items` | `items[i].value` |

```json
{
  "columns": [
    {
      "elementRef": "personTabs",
      "tabRows": {
        "general": [{ "columns": [{ "elementRef": "firstName" }] }],
        "contact": [{ "columns": [{ "elementRef": "email" }] }]
      }
    }
  ]
}
```

with

```json
{
  "personTabs": {
    "name": "personTabs",
    "type": "tabs",
    "label": "Person",
    "tabs": [
      { "value": "general", "label": "General" },
      { "value": "contact", "label": "Contact" }
    ]
  }
}
```

## Pages are not sections

A `page` is a **step or screen**, not a visual section. Multiple entries in `pages` produce a multi-step view, navigated by the built-in pager or stepper (`settings.pageNavigationMode`).

To draw titled sections stacked on one screen, use **one page containing several `panel` elements**. Do not create one page per section.

Every page needs its twin in `elements`:

```json
{
  "pages": [{ "name": "personPage", "rows": [] }],
  "elements": {
    "personPage": { "name": "personPage", "label": "Person", "type": "page", "hideHeader": true }
  }
}
```

Page element properties: `name`, `label`, `description`, `type`, `visibleIf`, `disableIf`, `readonlyIf`, `hideHeader`, `removeBackgraund` (spelled exactly like that), `pageBackgroundColor`, `pagePadding`, `mobilePadding`. Nothing else.

## Building a layout from a screenshot or description

Follow this order every time. Do not start writing JSON at step 1.

1. **Read the visual top to bottom.** List every field, in order, with its label.
2. **Find the section headings.** Each heading becomes one `panel` element whose `label` is that heading.
3. **Slice each section into horizontal bands.** Fields on the same visual line belong to the same `row`. A field on its own line is its own `row` with one column.
4. **Count the columns per band.** Two fields side by side is two columns. Three is three. Equal split is free; only reach for widths when the visual is clearly uneven.
5. **Write `elements` first.** Every panel, every field, the page. Flat, keyed by `name`, each with `name`, `label`, `type`.
6. **Write `pages` second.** Panels at the top level; each panel's column carries the section's `rows`.
7. **Verify** with the checklist below.

Counting rows and columns before touching JSON is what keeps the output faithful to the picture.

## Verification checklist

Run all of these mentally before returning JSON.

1. Every `elementRef` string resolves to a key in `elements`.
2. Every key in `elements` appears exactly once as some `elementRef` (or is a `page`).
3. Every entry of `pages` has a matching `elements[name]` with `type: "page"`.
4. No object in `elements` has a `rows`, `columns` or `children` key. The two exceptions are `table.columnsConfig` and `dynamicTable.columns`.
5. No column object has any key other than `elementRef`, `rows`, `tabRows`, `fragmentRef`, `fragmentBindings`, `fragmentMode`.
6. No row object has any key other than `columns`.
7. `rows` on a column appears only when the referenced element is one of the ten container types.
8. `tabRows` keys match the container's declared tab/item/panel/step values.
9. Widths, if present at all, are on elements, not columns.
10. `name` values are unique across the whole structure.

## Full worked example

A dialog with four titled sections, mixed one-, two- and three-field rows, conditional document fields, and a footer button pair. Every property used below exists in [the properties reference](https://ngxviewbuilder.io/ai/properties-reference).

```json
{
  "schemaVersion": 1,
  "settings": {
    "language": "en",
    "locale": "lt-LT",
    "width": "640px",
    "widthUnit": "px",
    "renderMode": "dialog",
    "dialogTitle": "Add a new person",
    "dialogWidth": "640px",
    "dialogShowCloseButton": true,
    "showSubmitButton": false
  },
  "pages": [
    {
      "name": "personPage",
      "rows": [
        {
          "columns": [
            {
              "elementRef": "panelGeneral",
              "rows": [
                { "columns": [{ "elementRef": "firstName" }, { "elementRef": "lastName" }] },
                { "columns": [{ "elementRef": "personalCode" }, { "elementRef": "birthDate" }] },
                { "columns": [{ "elementRef": "citizenship" }, { "elementRef": "gender" }] },
                { "columns": [{ "elementRef": "isStudent" }] }
              ]
            }
          ]
        },
        {
          "columns": [
            {
              "elementRef": "panelContact",
              "rows": [
                { "columns": [{ "elementRef": "email" }] },
                { "columns": [{ "elementRef": "phone" }] },
                { "columns": [{ "elementRef": "declaredAddress" }] },
                { "columns": [{ "elementRef": "country" }] },
                { "columns": [{ "elementRef": "locality" }, { "elementRef": "street" }] },
                {
                  "columns": [
                    { "elementRef": "houseNumber" },
                    { "elementRef": "flatNumber" },
                    { "elementRef": "postCode" }
                  ]
                }
              ]
            }
          ]
        },
        {
          "columns": [
            {
              "elementRef": "panelBank",
              "rows": [
                { "columns": [{ "elementRef": "bankAccount" }] },
                { "columns": [{ "elementRef": "bankName" }] },
                { "columns": [{ "elementRef": "bankSwift" }] },
                { "columns": [{ "elementRef": "bankAddress" }] }
              ]
            }
          ]
        },
        {
          "columns": [
            {
              "elementRef": "panelDocument",
              "rows": [
                { "columns": [{ "elementRef": "hasDocument" }] },
                { "columns": [{ "elementRef": "documentType" }] },
                {
                  "columns": [
                    { "elementRef": "documentNumber" },
                    { "elementRef": "documentValidUntil" }
                  ]
                }
              ]
            }
          ]
        },
        {
          "columns": [
            {
              "elementRef": "panelActions",
              "rows": [
                { "columns": [{ "elementRef": "cancelButton" }, { "elementRef": "saveButton" }] }
              ]
            }
          ]
        }
      ]
    }
  ],
  "elements": {
    "personPage": {
      "name": "personPage",
      "label": "Add a new person",
      "type": "page",
      "hideHeader": true
    },

    "panelGeneral": {
      "name": "panelGeneral",
      "label": "Bendri asmens duomenys",
      "type": "panel",
      "showBorder": false,
      "panelPadding": "0px",
      "titleUnderline": true
    },
    "firstName": {
      "name": "firstName",
      "label": "Vardas",
      "type": "text",
      "required": true,
      "requiredMessage": "Enter the first name"
    },
    "lastName": {
      "name": "lastName",
      "label": "Last name",
      "type": "text",
      "required": true,
      "requiredMessage": "Enter the last name"
    },
    "personalCode": {
      "name": "personalCode",
      "label": "Asmens kodas",
      "type": "text",
      "maskType": "digits",
      "maxlength": 11,
      "required": true,
      "requiredMessage": "Enter the personal code"
    },
    "birthDate": {
      "name": "birthDate",
      "label": "Gimimo data",
      "type": "datepicker",
      "placeholder": "Pasirinkti",
      "pickerMode": "date",
      "format": "YYYY-MM-DD",
      "required": true
    },
    "citizenship": {
      "name": "citizenship",
      "label": "Citizenship",
      "type": "select",
      "showSearch": true,
      "strictOptions": true,
      "required": true,
      "options": [
        { "value": "LT", "label": "Lietuva" },
        { "value": "LV", "label": "Latvija" },
        { "value": "EE", "label": "Estija" }
      ]
    },
    "gender": {
      "name": "gender",
      "label": "Lytis",
      "type": "select",
      "strictOptions": true,
      "required": true,
      "options": [
        { "value": "M", "label": "Vyras" },
        { "value": "F", "label": "Moteris" }
      ]
    },
    "isStudent": {
      "name": "isStudent",
      "label": "",
      "type": "singleCheckbox",
      "checkboxLabel": "Person qualifies as a student",
      "defaultValue": false
    },

    "panelContact": {
      "name": "panelContact",
      "label": "Kontaktiniai duomenys",
      "type": "panel",
      "showBorder": false,
      "panelPadding": "0px",
      "titleUnderline": true
    },
    "email": {
      "name": "email",
      "label": "Email",
      "type": "text",
      "inputMode": "email",
      "required": true,
      "validators": [
        { "type": "email", "message": "Invalid email format" }
      ]
    },
    "phone": {
      "name": "phone",
      "label": "Tel. Nr.",
      "type": "phoneInput",
      "defaultCountryCode": "LT"
    },
    "declaredAddress": {
      "name": "declaredAddress",
      "label": "Deklaruotos gyvenamosios vietos adresas",
      "type": "text",
      "readOnly": true,
      "expression": "{street} + ' ' + {houseNumber} + ', ' + {locality}",
      "logicExecutionMode": "onChange"
    },
    "country": {
      "name": "country",
      "label": "Country",
      "type": "select",
      "showSearch": true,
      "strictOptions": true,
      "options": [
        { "value": "LT", "label": "Lietuva" },
        { "value": "LV", "label": "Latvija" },
        { "value": "EE", "label": "Estija" }
      ]
    },
    "locality": { "name": "locality", "label": "Locality", "type": "text" },
    "street": { "name": "street", "label": "Street", "type": "text" },
    "houseNumber": {
      "name": "houseNumber",
      "label": "Namo numeris",
      "type": "text",
      "mobileWidth": "100%"
    },
    "flatNumber": {
      "name": "flatNumber",
      "label": "Buto numeris",
      "type": "text",
      "mobileWidth": "100%"
    },
    "postCode": {
      "name": "postCode",
      "label": "Post code",
      "type": "text",
      "mobileWidth": "100%"
    },

    "panelBank": {
      "name": "panelBank",
      "label": "Bank account details",
      "type": "panel",
      "showBorder": false,
      "panelPadding": "0px",
      "titleUnderline": true
    },
    "bankAccount": { "name": "bankAccount", "label": "Bank account number", "type": "text" },
    "bankName": { "name": "bankName", "label": "Banko pavadinimas", "type": "text" },
    "bankSwift": {
      "name": "bankSwift",
      "label": "Banko SWIFT (BIC) kodas",
      "type": "text",
      "minlength": 8,
      "maxlength": 11
    },
    "bankAddress": { "name": "bankAddress", "label": "Banko adresas", "type": "text" },

    "panelDocument": {
      "name": "panelDocument",
      "label": "Asmens dokumento duomenys",
      "type": "panel",
      "showBorder": false,
      "panelPadding": "0px",
      "titleUnderline": true
    },
    "hasDocument": {
      "name": "hasDocument",
      "label": "Dokumentas",
      "type": "radio",
      "showInline": true,
      "defaultValue": "Y",
      "required": true,
      "options": [
        { "value": "Y", "label": "Taip" },
        { "value": "N", "label": "Ne" }
      ]
    },
    "documentType": {
      "name": "documentType",
      "label": "Dokumento tipas",
      "type": "select",
      "strictOptions": true,
      "visibleIf": "{hasDocument} == 'Y'",
      "requireIf": "{hasDocument} == 'Y'",
      "logicExecutionMode": "onChange",
      "options": [
        { "value": "PASSPORT", "label": "Pasas" },
        { "value": "ID_CARD", "label": "ID card" }
      ]
    },
    "documentNumber": {
      "name": "documentNumber",
      "label": "Dokumento numeris",
      "type": "text",
      "visibleIf": "{hasDocument} == 'Y'",
      "requireIf": "{hasDocument} == 'Y'",
      "logicExecutionMode": "onChange"
    },
    "documentValidUntil": {
      "name": "documentValidUntil",
      "label": "Dok. galioja iki",
      "type": "datepicker",
      "placeholder": "Pasirinkti",
      "pickerMode": "date",
      "format": "YYYY-MM-DD",
      "visibleIf": "{hasDocument} == 'Y'",
      "logicExecutionMode": "onChange"
    },

    "panelActions": {
      "name": "panelActions",
      "label": "",
      "type": "panel",
      "showBorder": false,
      "panelPadding": "0px",
      "contentJustify": "flex-end",
      "contentGap": "8px"
    },
    "cancelButton": {
      "name": "cancelButton",
      "label": "",
      "type": "button",
      "text": "Cancel",
      "variant": "outline",
      "tone": "neutral",
      "fitContent": true
    },
    "saveButton": {
      "name": "saveButton",
      "label": "",
      "type": "button",
      "text": "Save",
      "variant": "solid",
      "tone": "primary",
      "fitContent": true,
      "events": [{ "trigger": "click", "type": "submit", "validateForm": true }]
    }
  },
  "localization": {
    "defaultLanguage": "en",
    "languages": ["en"]
  }
}
```

Read that example structurally, not as a template to copy verbatim. The shape is what matters: four panels at the top level of `pages`, each panel's column carrying the section's rows, and every field defined once, flat, in `elements`.

## Quick reference card

```
pages[]           → { name, rows[] }
  rows[]          → { columns[] }                       (only key: columns)
    columns[]     → { elementRef, rows?, tabRows? }     (no widths, no props)
      rows[]      → recursion, containers only

elements{}        → flat map, key === element.name
  every element   → { name, label, type, ...properties }
  containers      → hold NO children
  widths          → width / tabletWidth / mobileWidth / fitContent, here only
```

Related: [JSON authoring rules](https://ngxviewbuilder.io/ai/json-authoring-rules), [Common mistakes](https://ngxviewbuilder.io/ai/common-mistakes), [Canonical properties reference](https://ngxviewbuilder.io/ai/properties-reference).

---

## AI: JSON authoring rules

Source: https://ngxviewbuilder.io/ai/json-authoring-rules

# AI: JSON authoring rules

This page defines how an agent must construct NGX View Builder JSON.

::: warning Read the layout model first
A structure has two independent halves: `pages` is a **layout tree of positions**, `elements` is a **flat dictionary of definitions**, and `elementRef` is the only bridge between them. Containers do not hold their children; the column that references a container holds them in its own `rows`. Widths belong to elements, never to columns. The complete rules, with the exact object shapes and a full worked example, are in [Layout model](https://ngxviewbuilder.io/ai/layout-model). Do not write layout JSON before reading it.
:::

## Minimal skeleton

```json
{
  "settings": {
    "language": "en",
    "locale": "en-US",
    "renderMode": "page"
  },
  "pages": [
    {
      "name": "page1",
      "rows": [
        {
          "columns": [
            { "elementRef": "field1" }
          ]
        }
      ]
    }
  ],
  "elements": {
    "page1": {
      "name": "page1",
      "label": "Page 1",
      "type": "page"
    },
    "field1": {
      "name": "field1",
      "label": "Field 1",
      "type": "text"
    }
  },
  "localization": {
    "defaultLanguage": "en",
    "languages": ["en"]
  }
}
```

## Element type name rules

**Type strings are case-sensitive. Copy them exactly.** Never invent casing variants.

| Correct | Wrong (do not use) |
|---|---|
| `"datepicker"` | `"datePicker"`, `"DatePicker"`, `"date-picker"` |
| `"singleCheckbox"` | `"SingleCheckbox"`, `"single_checkbox"` |
| `"dynamicTable"` | `"DynamicTable"`, `"dynamic-table"` |
| `"dynamicPanel"` | `"DynamicPanel"` |
| `"multiSelect"` | `"MultiSelect"`, `"multi-select"` |
| `"toggleSwitch"` | `"ToggleSwitch"`, `"toggle-switch"` |
| `"richText"` | `"richtext"`, `"RichText"` |
| `"fileUpload"` | `"fileupload"`, `"FileUpload"` |
| `"phoneInput"` | `"PhoneInput"`, `"phone-input"` |
| `"listGrid"` | `"ListGrid"`, `"list-grid"` |

The canonical full list is in [Common mistakes, entry 14](https://ngxviewbuilder.io/ai/common-mistakes#_14-wrong-element-type-casing).

## Structure rules

### `settings`

- Keep only settings that are actually used.
- If the user does not request a complex modal/dialog mode, `language`, `locale`, and `renderMode` are sufficient.
- Do not invent unnecessary `dialog*`, `stepper*`, or `pageNavigation*` properties if they are not in use.

### `pages`

- `pages` describes layout only.
- Every page must have a `name` and a `rows` array. Those are its only structural keys.
- A row object has exactly one key: `columns`.
- A column object has `elementRef`, plus `rows` or `tabRows` when it references a container. Nothing else. `width`, `mobileWidth`, `span`, `label`, `type` on a column are silently dropped.
- `rows[*].columns[*].elementRef` is a **string key** into the `elements` map, not an object.
- Do not embed full element objects inside `pages`.
- A `page` is a step or screen. Titled sections on one screen are `panel` elements inside a single page, not separate pages.

### `elements`

- `elements` is an object, not an array, and it is **flat**. It never nests.
- The key must match `element.name`.
- Every element must have at least `name`, `label`, and `type`.
- If `pages[*].name = "pageCustomer"`, there must be an `elements.pageCustomer` entry with `type: "page"`.
- **No element definition lists its children.** `rows`, `columns`, `children`, `items`, `fields` on a `panel` / `dynamicPanel` / `tabs` / `dialog` do not exist and are ignored. The exception is the two tables, whose cells are not layout: `table` declares them in `columnsConfig` keyed by `key`, and `dynamicTable` declares them in `columns` keyed by `name`.

### `localization`

- For a single-language form, the minimum is:
  - `defaultLanguage`
  - `languages`
- For multi-language forms, a `texts` section may also be present.

### `dataSources`

- Create only when the user genuinely needs external data or actions.
- `dataSourceName` references in elements must point to a real datasource.
- If the form has no integration scenarios, it is better to omit `dataSources`.

## Name and reference rules

- All `name` values must be unique throughout the structure.
- `elementRef` must point to an existing `elements` entry.
- If an element is a container with inner fields, those child elements must also have unique `name` values.
- Do not reuse the same `name` for multiple different elements.

## What the agent must do when extending an existing form

- Preserve existing `settings`, `pages`, `elements`, `localization`, and `dataSources` unless the user explicitly asks to rebuild everything from scratch.
- Modify only the related sections.
- When adding a new element, you must:
  - add it to `elements`
  - insert the `elementRef` in the appropriate `page/row/column`
- When adding logic between fields, verify that both fields already exist.

## Layout rules

- A single `row` is a horizontal band; its `columns` sit side by side. Vertical order is the order of `rows`.
- **A column with no width takes an equal share of the row.** For a two-column layout, one `row` with two `columns` and no widths is sufficient. Never write `"width": "50%"` to get halves.
- Widths (`width`, `tabletWidth`, `mobileWidth`, `fitContent`) are **element** properties, set in the `elements` map, and only when the split must be uneven.
- Exactly ten types accept children: `page`, `panel`, `dynamicPanel`, `dialog`, `emptyBlock` (via `column.rows`) and `tabs`, `tabsPro`, `accordion`, `splitter`, `progressFlow` (via `column.tabRows`, keyed by each tab/item/panel/step `value`). Every other type is a leaf.
- Container inner layouts must remain in the NGX View Builder model, not via custom HTML.
- `parentName` is not how parentage is declared. The layout tree is.

Worked examples and the exact interfaces: [Layout model](https://ngxviewbuilder.io/ai/layout-model).

## Value shape rules

- `text`, `textarea`, `richText` typically store a `string`.
- `number`, `slider` store a `number` or `string` depending on `valueStorageType`.
- `singleCheckbox`, `toggleSwitch`, `toggleButton` typically store a `boolean`.
- `checkbox`, `multiSelect` typically store an array.
- `select`, `radio`, `autocomplete` typically store a single value.
- `dateRange` must return an object with `dateFrom` and `dateTo`.
- `dynamicPanel` and `dynamicTable` typically store an array of objects.
- `numberStepper` stores a `number`; `timePicker` stores a time string.
- `signaturePad` stores signature image data keyed under the element's `name`.
- `listBox`, `selectButton` store a single value, or an array when multi-select/`multiple` is enabled.
- `progressBar` stores a `number`.

## Logic rules

- Use `visibleIf`, `disableIf`, `requireIf`, `readonlyIf`, `resetIf` for boolean conditions.
- Use `expression` to compute and write a value.
- When logic depends on changes in another field, typically add `logicExecutionMode: "onChange"`.
- Do not use self-reference `expression`.

## Validator field rules

Validators are separate sub-objects in the `validators` array. They have their own field names that differ from element-level logic fields:

| Element-level (correct placement) | Validator-level (correct placement) |
|---|---|
| `element.visibleIf` | `validator.condition` |
| `element.requireIf` | `validator.applyIf` |
| `element.expression` | _(does not exist on validators)_ |

Never put `visibleIf`, `requireIf`, `readonlyIf`, `disableIf`, `expression`, or `resetIf` inside a validator object. Never use the field name `expression` on a validator; the correct field is `condition`.

**Polarity:** `condition` is the *failing* check. The validator error is shown while `condition` evaluates to `true`. Use `applyIf` to run a validator only in certain cases (it runs while `applyIf` is truthy).

Correct:

```json
{
  "name": "age",
  "type": "number",
  "visibleIf": "{skipAge} != true",
  "validators": [
    { "type": "min", "value": 0, "message": "Cannot be negative" },
    { "type": "max", "value": 120, "message": "Invalid age", "applyIf": "{country} == 'LT'" }
  ]
}
```

## What must not be generated

- Custom `Angular` components.
- Non-existent NGX View Builder properties.
- Full element objects embedded in `pages`.
- Pseudo-code instead of real JSON.
- Empty wrappers or meta-properties with no real purpose.

## Pre-return checklist

1. Do all `elementRef` values point to an existing element.
2. Does every `page` have a corresponding `elements[pageName]` entry.
3. Do logic fields return the correct type.
4. Are there no self-reference expressions.
5. Is the correct element chosen for the task.
6. Are there no unnecessary properties added.
7. Are all `type` strings exact-cased (e.g. `datepicker`, not `datePicker`)?
8. Do validators use `condition` (error when `true`) and `applyIf`, rather than `expression`, `visibleIf`, or other element-level field names?
9. Is every container's content attached to the referencing **column**, and does no element definition contain a `rows` / `children` / `items` array?
10. Do all column objects carry only `elementRef` (plus `rows` / `tabRows` where applicable), with no widths or other properties?

---

## AI: Element selection map

Source: https://ngxviewbuilder.io/ai/element-selection-map

# AI: Element selection map

This page helps the agent decide which NGX View Builder element to use based on the user's intent.

## Quick reference

- "dynamic table", "editable rows", "add row", "delete row" -> `dynamicTable`
- "server-side table", "paging", "sorting", "filtering", "export", "row actions" -> `table`
- "repeating block", "repeatable section" -> `dynamicPanel`
- "single choice from a list" -> `select` or `radio`
- "search in a large list" -> `autocomplete`
- "multiple choices" -> `multiSelect` or `checkbox`
- "yes/no toggle" -> `singleCheckbox`, `toggleSwitch`, or `toggleButton`
- "handwritten signature" -> `signaturePad`
- "time of day" -> `timePicker`
- "quantity with +/- buttons" -> `numberStepper`

## Text and input elements

| User intent | Choose | When not to choose |
| --- | --- | --- |
| A single short text value | `text` | Do not use for long descriptions |
| Longer comment or notes | `textarea` | Do not use if rich content is needed |
| Formatted content | `richText` | Do not use for plain single-line text |
| Number | `number` | Do not use if it is only a text code |
| Sliding numeric value | `slider` | Do not use for precise financial amounts |
| Phone number | `phoneInput` | Do not use plain `text` if country-code UX is required |
| Large searchable list | `autocomplete` | Do not use for small static lists |
| File upload | `fileUpload` | Do not use for plain link text |
| Triggering an action | `button` | Do not use for data input |
| Code or JSON fragment | `textarea` | There is no `code` element type |
| Small bounded quantity with +/- buttons | `numberStepper` | Do not use for large or precise ranges; prefer `number` |
| Handwritten signature capture | `signaturePad` | Do not use for typed text |

## Choice elements

| User intent | Choose | When not to choose |
| --- | --- | --- |
| Single choice from several options | `select` | If all options must always be visible, prefer `radio` |
| Single choice with all options visible | `radio` | Do not use if there are very many options |
| Multiple choices from a list | `multiSelect` | Do not use for a yes/no scenario |
| Multiple choices as a checkbox group | `checkbox` | Do not use for a single boolean field |
| Single boolean checkbox | `singleCheckbox` | Do not use if a button-style switch is desired |
| Boolean toggle switch | `toggleSwitch` | Do not use if checkbox semantics are required |
| Boolean button-style toggle | `toggleButton` | Do not use if a standard checkbox is needed |
| Date selection | `datepicker` | Do not use for a date range |
| Date range | `dateRange` | Do not use for a single date |
| Time of day | `timePicker` | Combine with `datepicker` if both are needed |
| Simple dropdown menu | `button` with `menuActions` | There is no `dropdown` element type; `select` is the closed choice control |
| Always-visible scrollable selection list | `listBox` | Do not use if a compact closed control is preferred; use `select` |
| Connected button row for 2-4 short options | `selectButton` | Do not use for long option lists; prefer `radio` or `select` |

## Tables and repeating data

| User intent | Choose | Note |
| --- | --- | --- |
| User must add, delete, and edit rows inline | `dynamicTable` | This is not `table` |
| Repeat an entire block with multiple fields | `dynamicPanel` | Better than `dynamicTable` if it is not a table |
| Server-side table with paging, sorting, filtering, row actions | `table` | This is the main data grid |
| Simple list or card grid display | `listGrid` | Not for an editable table |
| Chart | `chart` | Not for a table or repeating input |

## Containers and UI structure

| User intent | Choose | Note |
| --- | --- | --- |
| Simple block with inner fields | `panel` | Most common container |
| Content divided into tabs | `tabs` or `tabsPro` | Do not use if multiple pages are sufficient |
| Collapsible sections | `accordion` | Good for longer forms |
| Step flow or progress | `progressFlow` | Not for a plain panel layout |
| Modal-style content | `dialog` | Not as the primary page-level form container |
| Two-zone layout with a divider | `splitter` | Only when two separate regions are needed |
| Empty placeholder block for a drop zone | `emptyBlock` | Internal layout helper |
| Visual separator | `divider` | Do not use for data storage |
| Spacing | `spacer` | Do not use as a structural container |

## Display and media elements

| User intent | Choose | Note |
| --- | --- | --- |
| Static HTML template | `customHtml` or `htmlSnippet` | Only when template HTML is truly needed |
| Rich text viewer | `richTextViewer` | Not for editing |
| Image | `image` | Not for file upload |
| Video | `video` | Media viewing only |
| External page or content | `iframe` | Only if the host allows it |
| Avatar | `avatar` | Not for general images |
| Icon | `icon` | Small UI symbol |
| Navigation path | `breadcrumbs` | Navigation context |
| Page heading | `pageTitle` | Hero or page top |
| Badge | `badge` | Short status or label |
| Informational card | `messageCard` | Message, warning, info |
| Statistics card | `statsCard` | KPI or summary |
| Toast notification | `toast` | Temporary notifications |
| Completion percentage | `progressBar` | Not for step/page navigation; use `progressFlow` |

## Internal or system types

The agent should not normally generate these directly as user form elements:

- `row`
- `column`
- `visibility`
- `choices`
- `validators`
- `dataSourceArguments`

They belong to the internal model, property editing, or builder infrastructure.

## Keyword map

| Prompt phrase | Choose |
| --- | --- |
| `dynamic table`, `editable rows`, `add row`, `delete row` | `dynamicTable` |
| `repeating block`, `repeatable section`, `repeatable group` | `dynamicPanel` |
| `data table`, `server-side table`, `paging`, `sorting`, `filtering` | `table` |
| `search in list`, `searchable select`, `autocomplete` | `autocomplete` |
| `multiple checkboxes`, `select multiple` | `checkbox` or `multiSelect` |
| `yes/no`, `toggle`, `switch` | `singleCheckbox`, `toggleSwitch`, or `toggleButton` |

## If you are unsure between two options

- `dynamicTable` vs `table`: does the user edit rows inline, or work with a datasource data grid?
- `dynamicPanel` vs `dynamicTable`: does the data look more like a form/block or like a row-based table?
- `select` vs `autocomplete`: are there few options, or many that require search?
- `singleCheckbox` vs `toggleSwitch`: does checkbox semantics matter, or is a switch style preferred?

---

## AI: Logic and expression properties

Source: https://ngxviewbuilder.io/ai/logic-and-expressions

# AI: Logic and expression properties

This page defines which expression fields the agent may use and which rules it must follow.

## Primary expression properties

| Property | When to use | Must return |
| --- | --- | --- |
| `visibleIf` | Show an element (native field; return `false` to hide) | `true` or `false` |
| `disableIf` | Make an element inactive | `true` or `false` |
| `requireIf` | Make an element required | `true` or `false` |
| `readonlyIf` | Make an element read-only | `true` or `false` |
| `resetIf` | Clear an element under a condition | `true` or `false` |
| `expression` | Compute and write a value | `string`, `number`, `boolean`, `array`, or `object` |
| `validators[].applyIf` | Enable a validator conditionally | `true` or `false` |
| `validators[].condition` | Failing check, error shown while `true` | `true` or `false` |

## Other expression usage points

The agent must know that expression logic does not live only in the main fields.

### Data source parameters

The field is called `params`, never `paramMap`:

- an element's `dataSource.params[*].value`, shaped `[{ "name": ..., "value": ... }]`
- an action's `params[*].value`, the same shape
- a `table`'s own lazy-load request params, which are different: `[{ "paramName": ..., "paramValue": ... }]`
- `{placeholder}` tokens inside a REST source's `params.url` and `params.body`

These can use expression fragments such as:

```
{personCode}
{row.id}
{__variables.route.mode}
```

### Table columns

`table.columnsConfig[*]` can use:

- `visibleIf`
- `controlActiveIf`
- `controlEnabledIf`

Inside a column of `type: "element"`, the hosted element's own texts, templates, and event params resolve against the row it renders: `{row.field}`, a bare `{field}` for a sibling of the same row, `{index}`, and `{value}`. The same tokens work in a `dynamicTable` cell and a `dynamicPanel` row.

### Event and action logic

Expressions are often used in actions in:

- `params[*].value`
- `condition`, which gates whether the action runs at all (per row for a table row action)
- `setValueValue` when `setValueMode` is `template` or `expression`

## When to use `logicExecutionMode`

If there is a dependency between fields, especially when `expression` is used, you typically need:

```json
{
  "logicExecutionMode": "onChange"
}
```

This is especially important when:

- one field fills another
- one field changes another's required state
- one field hides or disables another

## Core writing rules

- Use only NGX View Builder expression syntax, not full `JavaScript`.
- Read field values via `{fieldName}` or `{object.field}`.
- Use quotes for string values.
- Do not add `toNumber(...)` by reflex. Number elements already hold numbers, so `{price} * {quantity}` works as written. Reach for it only when the value genuinely arrives as text: a `text` element, a data source field, a select whose values are strings, or a number element with `valueStorageType: "string"`.
- Use `isEmpty(...)` and `notEmpty(...)` for empty checks.
- Use `contains`, `containsAny`, `containsAll`, and `len` for arrays.

## Correct examples

### Auto-fill

```json
{
  "name": "lastName",
  "type": "text",
  "expression": "{firstName} == 'John' ? 'Doe' : ''",
  "logicExecutionMode": "onChange"
}
```

### Conditional required

```json
{
  "name": "companyCode",
  "type": "text",
  "requireIf": "{personType} == 'company'",
  "logicExecutionMode": "onChange"
}
```

### Show/hide

```json
{
  "name": "vatCode",
  "type": "text",
  "visibleIf": "{country} == 'LT'"
}
```

### Calculation

```json
{
  "name": "totalAmount",
  "type": "number",
  "expression": "{price} * {quantity}",
  "logicExecutionMode": "onChange"
}
```

## Bad examples

### Self-reference expression

Incorrect:

```json
{
  "name": "el2",
  "expression": "{el1} == 'John' ? 'Doe' : {el2}"
}
```

Why it is wrong:

- the element references itself
- this leads to unstable or non-functioning logic

Correct:

```json
{
  "name": "el2",
  "expression": "{el1} == 'John' ? 'Doe' : ''",
  "logicExecutionMode": "onChange"
}
```

### Wrong type for a boolean property

Incorrect:

```json
{
  "visibleIf": "'yes'"
}
```

`visibleIf` must return `true` or `false`, not a string.

### Reference to a non-existent field

Incorrect:

```json
{
  "disableIf": "{customerType} == 'vip'"
}
```

if `customerType` does not exist in the form.

## Expression property map by need

| Need | Property |
| --- | --- |
| Show/hide a field | `visibleIf` (return `false` to hide) |
| Show but prevent editing | `disableIf` or `readonlyIf` |
| Make required only in certain cases | `requireIf` |
| Reset value when condition changes | `resetIf` |
| Automatically compute a value | `expression` |
| Enable a validator conditionally | `validators[].applyIf` |
| Flag a custom validation error | `validators[].condition` (error while `true`) |

## Working with arrays and element metadata

Conditions inside collection functions are written unquoted and evaluated once per entry. Entry fields are referenced bare, everything else in the view stays reachable through `{...}`:

```text
countInArray({tasks}, status == "OPEN")
filterArray({users}, role == {__variables.requiredRole})
findInArray({products}, id == {selectedId})
existsInArray({items}, status == "ACTIVE")
sumArray({orderItems}, price)
joinInArray(mapArray(filterArray({tasks}, status == "OPEN"), title), "", ", ")
```

Also available: `avgArray`, `getFirst(source, condition?)`, `getLast(source, condition?)`. `countInArray` still accepts a plain field selector, so older structures keep working.

For element metadata rather than values:

| Call | Returns |
| --- | --- |
| `getValue({select1})` | stored value, e.g. `OPEN` |
| `getLabel({select1})` | displayed option label, e.g. `Open issue` |
| `getLabel("select1", "CLOSED")` | label of a specific value |
| `getElementProperty("el1", "label")` | any configured property, nested keys allowed |
| `getProp({el1}, "placeholder")` | alias of `getElementProperty` |
| `translate({row.status})` | value translated through `localization.texts[<language>]` |
| `currentLanguage()` | active language code |

In `getLabel`, `getValue`, and `getProp` the token names the element, it is not replaced by that element's value.

## Writing values from an expression

| Call | Does |
| --- | --- |
| `setValue({variable1}, value)` | writes into a variable or an element data path |
| `sumValue({variable1}, value)` | adds a number to the current value, returns the new total |
| `pushValue({variable1}, value)` | appends to the target's array |
| `flattenArray(source)` | flattens nested arrays into one level |

`setVar`, `sumVar`, and `pushVar` are the same calls with the target always read as a variable name. `addValue` is an alias of `sumValue`.

Shorthand, where the leftmost token is the target and the right side reads normally:

```text
{variable1} = {row.column3} + 40
{variable1} += {row.column3}
```

Rules for the agent:

- The first argument names the target, do not replace it with a value.
- `setValue` is safe in a recalculated expression, writing an unchanged value does nothing.
- `sumValue` and `pushValue` add again on every run, so put them in an action, never in `visibleIf`, `disableIf`, or an `expression` property.
- For a table inside a dynamic panel prefer one aggregate over accumulation: `setValue({variable1}, sumArray({el1}, el5[].column3))`.
- A published column total is read as `{el4.column1-total}`, always in braces.

## Contexts the agent may encounter

### General form context

- `{fieldName}`
- `{nested.field}`
- `{__variables.*}`

### Dynamic blocks and tables

- `{row.field}` inside a `table` cell, a `dynamicTable` row, a row action or a column template
- `{panel.field}` inside a `dynamicPanel` entry
- `{item.field}` for the candidate option in `filterOptionsBy`
- `{index}` and `{value}` inside a cell
- a published `dynamicTable` column total, `{el1.column4-total}`

### A table's own live state

A `table` publishes its state so other elements can read it. `__table.<tableName>.*` is that table, bare `__table.*` is the last one touched:

`rows` `allRows` `rowCount` `totalRecords` `page` `size` `sortField` `sortDirection` `quickSearch` `detailedFilters` `request` `selectedRows` `selectedKeys` `selectedItems` `selectedCount` `selectedRow` `selectedRowKey` `selectedRowIndex` `activeRow` `activeRowKey`

```text
{__table.el2.selectedCount} > 0
notEmpty({__table.el2.selectedRowKey})
{__table.el2.selectedRow}.column2
```

This is what drives selection-aware buttons, counters and master/detail screens. Full examples: [Verified examples, 6.5 and 6.6](https://ngxviewbuilder.io/ai/examples#_6-5-the-table-s-live-state-table).

In such cases, do not guess. If `table` or `dynamicPanel` is used, consult:

- [Expressions](https://ngxviewbuilder.io/creators/expressions)
- [Tables & lists](https://ngxviewbuilder.io/creators/elements/tables)

## When to avoid `expression`

- When the user only wants a static default text.
- When `defaultValue` is sufficient.
- When you only need to show or hide a section, not compute new data.

## Final checklist

1. Does the condition reference existing fields.
2. Do boolean properties return a boolean value.
3. Does `expression` not return the wrong type.
4. Is there no self-reference.
5. Is `logicExecutionMode: "onChange"` added where needed.

---

## AI: Element rules and value shapes

Source: https://ngxviewbuilder.io/ai/element-rules

# AI: Element rules and value shapes

This page is an AI-oriented summary of the primary NGX View Builder elements. For the full property list always consult:

- [Element catalog](https://ngxviewbuilder.io/creators/elements/)
- [Canonical properties reference](https://ngxviewbuilder.io/ai/properties-reference)

## General rules for all elements

- Every user-facing element must have `name`, `label`, and `type`.
- `name` must be unique.
- If an element participates in logic, its `name` must be stable and meaningful.
- Do not use properties that are not found in the documentation or catalog.

## Input elements

### `text`

- Use for short text.
- Typical value shape: `string`.
- Common properties: `placeholder`, `defaultValue`, `required`, `expression`.

### `textarea`

- Use for longer text, comments, and descriptions.
- Value shape: `string`.
- Do not use if formatted rich content is needed.

### `number`

- Use for numbers, amounts, and quantities.
- Value shape: `number` or `string`, depending on `valueStorageType`.
- Do not wrap it in `toNumber(...)` in calculations. A `number` element already stores a number, so `{price} * {quantity}` is correct and `toNumber({price}) * toNumber({quantity})` only adds noise. The exception is `valueStorageType: "string"`, which really does store text.

### `slider`

- Use for ranges or bounded numeric values with a slider.
- Value shape: `number` or `string`.
- Do not use for precise manual financial input.

### `numberStepper`

- Use for small bounded quantities with increment/decrement buttons (passengers, rooms, items).
- Value shape: `number`.
- Use `min`/`max` to bound it. Do not use for large or precise numeric ranges; prefer `number`.

### `signaturePad`

- Use to capture a handwritten signature (mouse or touch).
- Value shape: signature image data (per `exportFormat`, e.g. `png`/`jpeg`), keyed under the element's `name`.
- Do not use as a substitute for typed text input.

### `phoneInput`

- Use for phone numbers with country code.
- Value shape is often an object with country and number parts.
- Do not use plain `text` if a standard phone UX is required.

### `autocomplete`

- Use for a large list of options with search.
- Value shape depends on the option mapping.
- Often requires a datasource or options mapping.

### `fileUpload`

- Use for file uploads.
- Value shape: the upload endpoint's response object, stored verbatim (or an array when `multiple`), never file bytes/base64. Depends on `fileKeyField`/`fileNameField`/`fileTypeField`/`fileSizeField`.
- Do not treat it as a plain text URL field.
- Consulting mode: for the exact upload/download/delete request and response contract, see [Properties reference](https://ngxviewbuilder.io/ai/properties-reference#fileupload) and [File upload requests](https://ngxviewbuilder.io/developers/data-sources#file-upload-requests).

### `button`

- Use to trigger an action.
- Not intended for form value storage.
- Common properties: `variant`, `events`, `actions`, `disabled`.

### `richText` / `richTextViewer`

- `richText` edits formatted HTML; `richTextViewer` only renders it.
- Value shape is an HTML `string`.
- There is no `code` element type. For a code or JSON fragment use `textarea`, or `customHtml` / `htmlSnippet` for read-only markup.

## Choice elements

### `select`

- Single choice from a list.
- Value shape: single value.
- Works with static or datasource options.

### `multiSelect`

- Multiple choices from a list.
- Value shape: array.
- Suitable when there are many options and a compact UI is needed.

### `radio`

- Single choice when all options must be visible at once.
- Value shape: single value.

### `checkbox`

- Multiple choices as a checkbox group.
- Value shape: array.
- Do not use for a single boolean field.

### `singleCheckbox`

- Single boolean checkbox.
- Value shape: `boolean`.

### `toggleSwitch`

- Single boolean switch.
- Value shape: `boolean`.
- Good for active/inactive scenarios.

### `toggleButton`

- Boolean or small-choice button-style control.
- Value shape is typically `boolean`.

### `datepicker`

- **Exact type string: `"datepicker"`** (all lowercase, never `datePicker`, `DatePicker`, or `date-picker`).
- Single date.
- Value shape is typically a date string or documented date format.
- Do not use for a date range.

Canonical example:

```json
{
  "name": "birthDate",
  "type": "datepicker",
  "label": "Date of Birth",
  "placeholder": "Select date",
  "required": true,
  "validators": [
    {
      "type": "maxDate",
      "value": "today",
      "message": "Cannot be in the future"
    }
  ]
}
```

### `dateRange`

- Date range.
- Value shape:

```json
{
  "dateFrom": "2026-03-01",
  "dateTo": "2026-03-09"
}
```

- Do not use for a single date.

### `timePicker`

- Selects a time of day.
- Value shape is typically a time string.
- Combine with `datepicker` when both a date and a time are needed, or use a `text` element with a date-time input mask for single-field entry.

### `dropdown` does not exist

- There is no `dropdown` element type. `select` is the closed dropdown control.
- For an action menu use `button` with `menuActions`, or `table.rowActions` with `rowActionsDisplayMode: "dropdown"`.

### `listBox`

- Always-visible scrollable selection list, single or multiple via `selectionMode`.
- Value shape: single value (`selectionMode: "single"`) or array (`selectionMode: "multiple"`).
- Use when choosing is the primary task on screen; otherwise prefer `select`.

### `selectButton`

- A row of connected buttons, a visual alternative to `radio` for 2-4 short options.
- Value shape: single value, or array when `multiple` is `true`.
- Do not use for long option lists; prefer `radio` or `select`.

## Table and repeating data elements

### `dynamicTable`

- Use for editable rows.
- The user must be able to add, delete, and edit rows.
- Value shape is typically: array of objects.
- This is not a server-side data grid.

### `table`

- Use for displaying data from a datasource.
- Supports `sorting`, `filtering`, `paging`, `rowActions`, and `export`.
- Requires `columnsConfig` and often datasource properties.
- Use `key`, not `name`, for `columnsConfig[*]` columns.
- A column either prints text (`type: "text"`) or hosts a real element (`type: "element"` plus `elementType` and `element`). Use the element form whenever the cell needs a control, a badge, a button, or an event.
- Server-side paging/search (`lazyLoad: true` + a `TABLE-POST` datasource method) has its own request/response contract, so do not invent one. Consulting mode: see [Properties reference](https://ngxviewbuilder.io/ai/properties-reference#table) and [Table: server-side paging & filtering](https://ngxviewbuilder.io/developers/data-sources#table-server-side-paging-filtering-table-post).
- If `key` is empty or absent, the column will not be rendered at runtime.
- This is not an editable `dynamicTable`.

### `listGrid`

- Use for displaying a list or card grid.
- Do not use if full table functionality is needed.

### `chart`

- Use for graphical visualization.
- Do not use as a data input element.

## Container and layout elements

### `page`

- Every `pages[*]` entry must have a corresponding `elements[pageName]` entry with `type: "page"`.
- `page` itself is the top-level form page.

### `panel`

- The most common container for grouping fields.
- Suitable for sections with an inner layout.

### `dynamicPanel`

- Use for repeating sets of blocks.
- Value shape is typically: array of objects.
- Suitable for addresses, family members, and education records.

### `tabs` and `tabsPro`

- Use to divide content into tabs.
- Suitable when multiple clearly separated areas are needed on a single page.

### `accordion`

- Use for collapsible sections.
- Suitable for longer forms.

### `progressFlow`

- Use to display steps or progress.
- Not for primary data input.

### `dialog`

- Use for modal content.
- Not every form needs `dialog*` settings.

### `splitter`

- Use for a two-zone layout with a divider.

### `emptyBlock`

- Internal helper placeholder for layout scenarios.

### `row` and `column`

- These are internal layout concepts.
- The agent typically does not generate them as top-level elements in the `elements` map.

## Display and media elements

### `richText`

- Formatted content or a longer rich editor scenario.
- Value shape: `string`.

### `richTextViewer`

- For rich text viewing.
- Not for editing.

### `customHtml`

- Use only when template HTML is genuinely needed, based on documented NGX View Builder capability.
- Do not use as an excuse to generate custom Angular.

### `htmlSnippet`

- Use for short HTML fragments.

### `image`

- For displaying images.

### `video`

- For displaying video.

### `iframe`

- For embedding external content.
- Suitable only if the host allows it.

### `avatar`

- For small user or object representations.

### `icon`

- For a UI icon.

### `divider`

- For visual separation.

### `spacer`

- For spacing.

### `breadcrumbs`

- For navigation path.

### `pageTitle`

- For page or section headings.

### `badge`

- For a short label or status.

### `messageCard`

- For an informational, success, or warning card.

### `statsCard`

- For KPI or summary blocks.

### `toast`

- For temporary notifications.
- Often tied to actions, not permanent layout.

### `progressBar`

- Completion indicator; value 0-100 (or a custom `max`) from `expression`, `defaultValue`, or a bound datasource.
- Value shape: `number`.
- Not for step/page navigation; use `progressFlow` for that.

## Validators

Validators belong in the `validators` array on any element. The exact interface is:

```typescript
interface IValidator {
  type: string;       // validator type (required)
  value?: string | number;   // threshold (minLength, maxLength, min, max, minDate, maxDate, etc.)
  message?: string;   // error text shown to user
  condition?: string; // expression, the FAILING check; the error is shown while it evaluates to true
  applyIf?: string;   // expression, validator only runs while this evaluates to true
}
```

**Field names that do NOT exist on `IValidator`: `expression`, `visibleIf`, `disableIf`, `requireIf`, `readonlyIf`, `resetIf`.**
Those are element-level logic fields. Never place them inside a validator object.

When writing a custom `condition`, express the failing state, for example:

```json
{
  "type": "custom",
  "condition": "dateDiffDays({startDate}, {endDate}) < 1",
  "message": "End date must be after start date"
}
```

Correct usage:

```json
{
  "name": "firstName",
  "type": "text",
  "label": "First Name",
  "requireIf": "{step} == 'personal'",
  "validators": [
    {
      "type": "minLength",
      "value": 2,
      "message": "At least 2 characters required"
    },
    {
      "type": "maxLength",
      "value": 64,
      "message": "Must not exceed 64 characters",
      "applyIf": "{firstName} != ''"
    }
  ]
}
```

Wrong, do not do this:

```json
{
  "validators": [
    {
      "type": "minLength",
      "expression": "{firstName}.length >= 2",
      "visibleIf": "{skip} == true"
    }
  ]
}
```

## Internal and system types

Do not normally generate these as user form elements unless working with builder infrastructure:

- `visibility`
- `choices`
- `validators`
- `dataSourceArguments`

## Per-element AI checklist

Before generating an element, the agent must answer:

1. What is the purpose of this element.
2. What must the value shape be.
3. Is a datasource needed.
4. Are logic properties needed.
5. Does the user want input, display, repetition, or a data grid.

---

## AI: Canonical properties reference

Source: https://ngxviewbuilder.io/ai/properties-reference

# AI: Canonical properties reference

This is the authoritative property reference for AI JSON generation. Only properties listed here are supported. Do not invent or guess properties not found in this document.

---

## Base properties (all elements)

Every element must have these three fields:

```json
{
  "name": "fieldName",
  "label": "Field Label",
  "type": "text"
}
```

Additional base properties available on all element types:

| Property | Type | Description |
|---|---|---|
| `description` | `string` | Subtitle or help text shown below the label |
| `hidden` | `boolean` | Statically hides the element |
| `width` | `string` | Width (e.g. `"100%"`, `"300px"`) |
| `tabletWidth` | `string` | Width on tablet |
| `mobileWidth` | `string` | Width on mobile |
| `dependsOn` | `string[]` | Limit expression recalculation to these field names |
| `logicExecutionMode` | `"onBlur" \| "onChange" \| "onInput"` | When logic/expression is re-evaluated |
| `validationExecutionMode` | `"onBlur" \| "onChange" \| "onInput"` | When validators are re-evaluated |
| `status` | `"default" \| "readonly"` | Interaction status override |
| `labelTooltip` | `string` | Tooltip shown on label hover |
| `fitContent` | `boolean` | Width fits content |

---

## Logic fields (element level only, never inside validators)

These fields accept JEXL expressions using `{fieldName}` placeholder syntax.

| Field | Return type | Behavior |
|---|---|---|
| `visibleIf` | `boolean` | Element visible when `true` |
| `disableIf` | `boolean` | Element disabled when `true` |
| `requireIf` | `boolean` | Element required when `true` |
| `readonlyIf` | `boolean` | Element readonly when `true` |
| `resetIf` | `boolean` | Element value cleared when `true` |
| `expression` | `any` | Result is set as element value; also for `setElementProperty` calls |

**All logic fields must contain valid JEXL expressions only.**

**There is no `hideIf`, and no `readOnlyIf` with a capital O.** These six keys are the entire list and they are matched exactly. Anything else is an ordinary property as far as the runtime is concerned: it is stored, it is never evaluated, and no dependency is registered for it. What you get is a form that looks correct in the JSON and does nothing at all, with no error anywhere to point at. Write the visible condition rather than the hidden one, because `visibleIf` states when the element **is** shown, so a hide condition has to be inverted, not renamed.

### Execution mode

| Field | Default | Behavior |
|---|---|---|
| `logicExecutionMode` | `onBlur` | When the logic fields above are re-evaluated |
| `validationExecutionMode` | `onBlur` | When validators are re-evaluated |

Both fall back to `onBlur` when the property is missing, so logic only re-runs after the field loses focus. To anyone typing in the form that reads as broken logic, so set `onChange` on every element whose logic or validation has to follow the typing, unless another mode was asked for.

---

## Static state fields

| Field | Type | Description |
|---|---|---|
| `required` | `boolean` | Always required |
| `disabled` | `boolean` | Always disabled |
| `readOnly` | `boolean` | Always read-only |

---

## Validators

`validators` is an array of `IValidator` objects. Exact interface:

```typescript
interface IValidator {
  type?: string;         // validator type (required)
  message?: string;      // error message shown to user
  value?: string | number; // threshold (minLength, maxLength, min, max, minDate, maxDate)
  condition?: string;    // JEXL, the FAILING check; error shown while this evaluates to true
  applyIf?: string;      // JEXL, validator runs only when this is truthy
}
```

**Forbidden inside validators: `expression`, `visibleIf`, `requireIf`, `disableIf`, `readonlyIf`, `resetIf`.**

```json
{
  "validators": [
    { "type": "minLength", "value": 3, "message": "At least 3 characters" },
    { "type": "maxLength", "value": 100, "message": "Too long", "applyIf": "notEmpty({name})" },
    { "type": "min", "value": 0, "message": "Cannot be negative" },
    { "type": "max", "value": 999, "message": "Too large" },
    { "type": "minDate", "value": "today", "message": "Cannot be in the past" },
    { "type": "maxDate", "value": "today", "message": "Cannot be in the future" }
  ]
}
```

---

## Events / Actions

`events` is an array of `IElementActionConfig` objects. Key fields:

| Field | Type | Values / Notes |
|---|---|---|
| `trigger` | `string` | `click` `submit` `input` `change` `blur` `focus` `beforeLoad` `onLoad` `afterLoad` `always`. Prefer a named trigger; `always` skips trigger filtering entirely and is only for host elements whose events are not gestures (a router outlet's `activate`/`deactivate`), so on a normal element it fires on load and on every gesture. |
| `type` | `string` | `navigate` `dataSource` `setValue` `setOptions` `reloadElements` `toast` `dialog` `validate` `submit` |
| `label` | `string` | Button label (when rendered as action button) |
| `icon` | `string` | Icon name |
| `condition` | `string` | JEXL, action runs only when truthy |
| `validateForm` | `boolean` | Validate before executing |
| `confirmEnabled` | `boolean` | Show confirmation dialog before action |
| `confirmTitle` | `string` | Confirm dialog title |
| `confirmMessage` | `string` | Confirm dialog body |

**By action type:**

`navigate`: `navigateTo` (URL/route), `openInNewTab` (boolean)

`dataSource`: `dataSourceName`, `responseMode` (`none` `download` `setValue`), `responseDataPath`, `responseTargetElement`, `reloadCurrentElementAfterSuccess`, `reloadOnReturnElementNames`

`toast`: `toastTitle`, `toastMessage`, `toastVariant` (`error` `warning` `info` `success`), `toastPosition` (`top-left` `top-center` `top-right` `bottom-left` `bottom-center` `bottom-right`), `toastAutoHide`, `toastAutoHideMs`

`dialog`: `dialogName`, `dialogOperation` (`open` `close` `toggle`)

`setValue`: `setValueTargetPath`, `setValueMode` (`contextPath` `template` `json`), `setValueValue`

`setOptions`: `setOptionsTargetElement`, `setOptionsMode` (`contextPath` `template` `json`), `setOptionsValue`

`reloadElements`: `reloadElementNames` (comma-separated)

`validate`: no extra fields. Validates the whole form and shows field errors, same as the built-in Validate toolbar button

`submit`: no extra fields. Validates the form, then fires `onComplete` with `{ isValid, data, issues }`, same as the built-in Submit toolbar button

Button appearance for action: `buttonVariant` (`filled` `outlined` `text`), `buttonTone` (`primary` `risk` `neutral`), `hideText`, `useCustomButtonStyle`

---

## Per-type additional properties

### `text`

| Property | Type | Notes |
|---|---|---|
| `placeholder` | `string` | |
| `minlength` | `number` | |
| `maxlength` | `number` | |
| `showMaxLengthCounter` | `boolean` | Show counter when maxlength is set |
| `pattern` | `string` | Regex pattern |
| `maskType` | `string` | Exactly: `none` `phoneIntl` `date` `time` `dateTime` `digits` `custom`. No other mask names exist |
| `maskPattern` | `string` | Custom mask (when maskType is `custom`) |
| `inputMode` | `string` | `text` `search` `email` `tel` `url` `numeric` `decimal` |
| `spellcheck` | `boolean` | |
| `autocomplete` | `string` | Browser autocomplete hint |
| `requiredMessage` | `string` | Custom required error message |

### `textarea`

Same as `text` plus:
| Property | Type | Notes |
|---|---|---|
| `rows` | `number` | Visible row count |

### `number`

| Property | Type | Notes |
|---|---|---|
| `placeholder` | `string` | |
| `min` | `number` | Minimum value |
| `max` | `number` | Maximum value |
| `step` | `number` | Increment step |
| `inputMode` | `string` | `numeric` `decimal` |
| `valueStorageType` | `string` | `number` (default) or `string` |
| `visualFormatEnabled` | `boolean` | Enable visual number formatting |
| `visualFormatLocale` | `string` | Locale for formatting (e.g. `"lt-LT"`) |
| `visualFormatUseGrouping` | `boolean` | Thousands separator |
| `visualFormatMinFractionDigits` | `number` | |
| `visualFormatMaxFractionDigits` | `number` | |
| `requiredMessage` | `string` | |

### `datepicker`

**Exact type string: `"datepicker"` (all lowercase)**

| Property | Type | Notes |
|---|---|---|
| `placeholder` | `string` | |
| `pickerMode` | `string` | `date` (default) or `datetime` |
| `includeSeconds` | `boolean` | For datetime mode |
| `format` | `string` | Output format. Exactly one of `""` (locale) `YYYY-MM-DD` `DD/MM/YYYY` `MM/DD/YYYY` `DD.MM.YYYY` `YYYY/MM/DD` `custom`. Lowercase Angular-style patterns such as `yyyy-MM-dd` are **not** valid |
| `customFormat` | `string` | The pattern used when `format` is `custom` |
| `minValue` | `string` | Min selectable date (JEXL or static) |
| `maxValue` | `string` | Max selectable date (JEXL or static) |
| `requiredMessage` | `string` | |

### `dateRange`

| Property | Type | Notes |
|---|---|---|
| `placeholder` | `string` | |
| `format` | `string` | |
| `minValue` | `string` | |
| `maxValue` | `string` | |
| `requiredMessage` | `string` | |

Value shape: `{ "dateFrom": "YYYY-MM-DD", "dateTo": "YYYY-MM-DD" }`

### `select` / `multiSelect` / `radio` / `checkbox` / `autocomplete`

| Property | Type | Notes |
|---|---|---|
| `placeholder` | `string` | Real on `autocomplete`, `listBox`, `selectButton`. On `select` / `multiSelect` it sets **only the search box hint** inside the open dropdown, and only when `showSearch` is on; the closed-state "Select..." text comes from the UI translation `select.placeholder` / `multiSelect.placeholder`, not from this property |
| `options` | `IOption[]` | Static options: `[{ "value": "x", "label": "X" }]` |
| `dataSource` | `IElementDataSource` | Dynamic options from datasource |
| `showSearch` | `boolean` | Search box in dropdown (select) |
| `strictOptions` | `boolean` | Value must be from options list |
| `filterIfEqual` | `string` | Filter options when datasource field equals value |
| `filterIfNotEqual` | `string` | Filter options when datasource field not equals value |
| `optionTemplate` | `string` | Inline HTML template for each option |
| `optionTemplateName` | `string` | Template name reference |
| `showInline` | `boolean` | Lay the choices out in a row (`radio`, `checkbox`) |
| `requiredMessage` | `string` | |

Value shapes:
- `select` / `radio` / `autocomplete`: single value
- `multiSelect` / `checkbox`: array

### `singleCheckbox` / `toggleSwitch` / `toggleButton`

Value shape: `boolean`

| Property | Type | Notes |
|---|---|---|
| `checkboxLabel` | `string` | Text rendered **next to the box** (`singleCheckbox`). `label` is the field label above it; for a bare checkbox row set `label` to `""` and put the wording here |
| `checkedValue` | `any` | Value when checked (`toggleButton` only) |
| `uncheckedValue` | `any` | Value when unchecked (`toggleButton` only) |

`singleCheckbox` has no `checkedValue` / `uncheckedValue`. It always stores `true` / `false`.

### `phoneInput`

| Property | Type | Notes |
|---|---|---|
| `placeholder` | `string` | |
| `defaultCountryCode` | `string` | ISO code of the preselected country: `LT` `LV` `EE` `PL` `DE` `SE` `NO` `DK` `FI` `GB` `IE` `US` |
| `allowedCountryCodes` | `string[]` | Restrict the country dropdown to these ISO codes |
| `maxlength` | `number` | |
| `autocomplete` | `string` | |
| `requiredMessage` | `string` | |

`phoneInput` has its own country dropdown. It has **no** `maskType`, `maskPattern` or `inputMode`, and the dial code is not set via `defaultValue`.

### `button`

| Property | Type | Notes |
|---|---|---|
| `text` | `string` | Button text |
| `icon` | `string` | Icon name |
| `iconPosition` | `string` | `left` `right` `top` `bottom` |
| `iconOnly` | `boolean` | Show icon only |
| `variant` | `string` | `solid` `outline` `text` |
| `tone` | `string` | `primary` `neutral` `success` `info` `warning` `risk` |
| `size` | `string` | `small` `normal` `large` |
| `loading` | `boolean` | Show loading spinner |
| `badge` | `string` | Badge text |
| `events` | `IElementActionConfig[]` | Primary click actions |
| `menuActions` | `IElementActionConfig[]` | Dropdown menu actions |

### `fileUpload`

| Property | Type | Notes |
|---|---|---|
| `accept` | `string` | Accepted MIME types or extensions, e.g. `.pdf,image/*` |
| `multiple` | `boolean` | Allow multiple files |
| `maxFiles` | `number` | Max number of attached files (default `5`) |
| `maxFileSizeMb` | `number` | Max file size **in megabytes**, not bytes |
| `uploadDataSourceName` / `downloadDataSourceName` / `deleteDataSourceName` | `string` | Names of REST data sources; empty `uploadDataSourceName` means files never leave the browser (local metadata only) |
| `uploadFormFieldName` | `string` | `multipart/form-data` field name for the file (default `file`). Upload always sends single-field `FormData`, never JSON/base64 |
| `fileKeyField` / `fileNameField` / `fileTypeField` / `fileSizeField` | `string` | Field names read from the server's response object (defaults `key`, `name`, `contentType`, `size`; the older `fil_key`/`fil_name`/`fil_content_type`/`fil_size` names are still recognized as fallback aliases) |

Value shape: the upload response object stored verbatim (or an array of them when `multiple`), keyed under the element's `name`, never file bytes/base64. Full request/response wire contract: [File upload requests](https://ngxviewbuilder.io/developers/data-sources#file-upload-requests).

### `page`

The complete list. A `page` element accepts nothing else.

| Property | Type | Notes |
|---|---|---|
| `name` | `string` | Must match the `pages[*].name` entry |
| `label` | `string` | Page / step title |
| `description` | `string` | Subtitle |
| `type` | `"page"` | Required |
| `hideHeader` | `boolean` | Hide the page title block |
| `removeBackgraund` | `boolean` | Drop the page background. Spelled exactly like this, the typo is part of the schema |
| `pageBackgroundColor` | `string` | |
| `pagePadding` | `string` | |
| `mobilePadding` | `string` | |
| `visibleIf` / `disableIf` / `readonlyIf` | `string` | JEXL |

A page's children are **not** listed here. They live in `pages[*].rows`; see [Layout model](https://ngxviewbuilder.io/ai/layout-model).

### `panel`

| Property | Type | Notes |
|---|---|---|
| `headerTemplate` | `string` | Inline HTML for panel header |
| `headerTemplateName` | `string` | Template name reference |
| `maxHeight` | `string` | Max panel height |
| `panelPadding` | `string` | Internal padding |
| `mobilePadding` | `string` | Mobile padding |
| `panelRadius` | `string` | Border radius |
| `panelShadow` | `string` | Box shadow CSS |
| `showBorder` | `boolean` | Show panel border |
| `panelBorderWidth` | `string` | Border width (when showBorder) |
| `panelBorderColor` | `string` | Border color (when showBorder) |
| `panelBackgroundColor` | `string` | Background color |
| `titleUnderline` | `boolean` | Show underline below title |
| `contentJustify` | `string` | Flexbox justify: `flex-start` `center` `flex-end` `space-between` `space-around` `space-evenly` |
| `contentAlign` | `string` | Flexbox align: `flex-start` `center` `flex-end` `stretch` |
| `contentGap` | `string` | Gap between child elements |
| `titleUnderlineColor` | `string` | Underline color (when `titleUnderline`) |
| `titleUnderlineWidth` | `string` | Underline thickness (when `titleUnderline`) |
| `resetChildrenOnHide` | `boolean` | Clear descendant field values when the panel becomes hidden |

**A panel never lists its children.** There is no `rows`, `columns`, `children`, `elements` or `items` property on `panel`. Child fields are attached in the layout tree, on the column that references the panel. See [Layout model](https://ngxviewbuilder.io/ai/layout-model#nesting-the-mistake-that-breaks-everything).

### `dynamicPanel`

Same as `panel` plus repeatable container behavior (`addRowButtonText`, `removeRowButtonText`, `emptyMessage`, `disallowAddRows`, `disallowDeleteRows`, `maxRows`, `confirmRowDeletion`, `hideHeader`). Value shape: array of objects. Children are attached the same way as for `panel`, via `column.rows`.

### `dynamicTable`

| Property | Type | Notes |
|---|---|---|
| `emptyMessage` | `string` | Message when no rows |
| `addRowButtonText` | `string` | Add row button label |
| `itemsPath` | `string` | Data path for pre-populating rows |
| `disallowAddRows` | `boolean` | |
| `disallowDeleteRows` | `boolean` | |
| `maxRows` | `number` | |
| `confirmRowDeletion` | `boolean` | |
| `confirmDeleteTitle` | `string` | |
| `confirmDeleteMessage` | `string` | |
| `confirmDeleteConfirmLabel` | `string` | |
| `confirmDeleteCancelLabel` | `string` | |
| `hideRowIf` | `string` | JEXL, hides individual rows |
| `columns` | `IDynamicTableColumn[]` | Column definitions |
| `dataSource` | `IElementDataSource` | Pre-populate from datasource |

Column-level totals:

| Property | Type | Notes |
|---|---|---|
| `columns[*].useTotals` | `boolean` | Sum in the footer row, also published to data |
| `columns[*].totalToData` | `boolean` | Publish the sum without a footer row |

A published sum lands in the data as `<table>.<column>-total`, for example `el4.column1-total`, and is read in expressions as `{el4.column1-total}`. Inside a dynamic panel the key carries the entry index: `el1[0].el5.column3-total`.

Value shape: array of objects.

### `table`

`columnsConfig` entries use `key` (NOT `name`). Minimum column:

```json
{
  "key": "firstName",
  "label": "First Name",
  "showInTable": true
}
```

Column type values the builder offers: `text`, `date`, `dateTime`, `number`, and `element`. The renderer still understands `boolean` `html` `status` `toggleSwitch` `singleCheckbox` so older structures keep working, but do not author new columns with them; use `element` with the matching `elementType` instead.

`date`, `dateTime`, and `number` format the raw value in place, no template or cell element needed:

```json
{
  "key": "created",
  "label": "Created",
  "type": "dateTime",
  "dateIncludeSeconds": true,
  "showInTable": true
}
```

| Property | Type | Notes |
|---|---|---|
| `formatLocale` | `string` | `lt-LT`, `en-US`. Empty follows the view locale |
| `dateFormatPattern` | `string` | `yyyy-MM-dd HH:mm:ss`. Tokens `yyyy yy MM dd HH hh mm ss SSS a`. Wins over the locale format |
| `dateIncludeSeconds` | `boolean` | `dateTime` only |
| `numberMinFractionDigits` | `number` | Decimal places, minimum |
| `numberMaxFractionDigits` | `number` | Decimal places, maximum |
| `numberUseGrouping` | `boolean` | Thousands separator, defaults to `true` |

A column of `type: "element"` renders a real element in every row:

```json
{
  "key": "status",
  "label": "Status",
  "type": "element",
  "showInTable": true,
  "elementType": "select",
  "element": {
    "options": [{ "label": "New", "value": "new" }, { "label": "Done", "value": "done" }],
    "events": [
      { "trigger": "change", "type": "dataSource", "dataSourceName": "saveStatus",
        "params": [
          { "name": "id", "value": "{row.id}" },
          { "name": "status", "value": "{value}" }
        ] }
    ]
  }
}
```

`elementType` is the element type id (`select`, `button`, `badge`, `datepicker`, `progressBar`, `customHtml`, `richTextViewer`, and so on). Use `richTextViewer` when the row field already holds HTML and only needs rendering. `element` is that element's own configuration, the same keys it would have as a page element. Inside it, `{row.*}`, a bare sibling field name, `{index}`, and `{value}` all resolve against the row the cell belongs to.

| Property | Type | Notes |
|---|---|---|
| `columnsConfig` | `ITableColumnConfig[]` | Column definitions, use `key` not `name` |
| `columnsConfig[*].elementType` | `string` | Element type rendered in the cells, when `type` is `element` |
| `columnsConfig[*].element` | `object` | Configuration of that hosted element (options, dataSource, events, validators) |
| `dataSource` | `IElementDataSource` | The table's source, for both client-side and server-side tables. With `lazyLoad: false` it must return **all** rows in one response; with `lazyLoad: true` it must accept the `TABLE-POST` paging/filter contract below |
| `tableDataSourceName` | `string` | Legacy server-side binding, still read for older structures. New structures put the source in `dataSource` |
| `lazyLoad` | `boolean` | `true` = server-side paging/sort/search per request; `false` = load everything once |
| `tableItemsPath` / `tableTotalPath` | `string` | Response paths for rows / total count, both optional. Common shapes (`items`/`data`/`results`/`rows`, `total`/`totalCount`/`totalRecords`/`count`/`cnt`) are auto-detected |
| `pageSize` | `number` | Default page size |
| `rowActions` | `ITableRowActionConfig[]` | Row action buttons. These go through the generic action/data-source pipeline, not this contract |

**Do not use `ITableDataSourceConfig`.** It exists in the type definitions but is dead code, never wired to anything; the real per-table binding is the flat `tableDataSourceName`/`tableItemsPath`/`tableTotalPath` trio above.

When `lazyLoad: true` and the data source's `method` is the literal string `TABLE-POST` (sent over the wire as a real `POST`), NGX View Builder auto-merges the current page/sort/search state into the request body:

```json
{
  "pagingParams": { "cnt": null, "orderClause": "lastName DESC", "pageSize": 25, "skipRows": 50, "totalCountUsed": false },
  "params": [ ["tenantId", "42"] ],
  "extendedParams": [
    { "paramName": "quickSearch", "paramValue": { "condition": "%-%", "value": "acme" } },
    { "paramName": "status", "paramValue": { "condition": "=", "value": "active" } }
  ]
}
```

`condition` values: `%-%` contains, `!%-%` not contains, `%-` starts with, `-%` ends with, `=`/`!=` equals/not equals, `>`/`>=`/`<`/`<=` for numbers and dates. Full contract, response shape, row-action/inline-edit context, and export behavior: [Table: server-side paging & filtering](https://ngxviewbuilder.io/developers/data-sources#table-server-side-paging-filtering-table-post).

### `tabs` / `tabsPro`

Contains named tab sections. Child rows assigned via `column.tabRows`.

### `accordion`

Collapsible sections with `label` per panel.

### `dialog`

Modal element. Configure via `settings.dialog*` fields:

| Setting | Notes |
|---|---|
| `settings.renderMode` | `"dialog"` |
| `settings.dialogTitle` | Dialog title |
| `settings.dialogDescription` | Subtitle |
| `settings.dialogWidth` | Width |
| `settings.dialogShowCloseButton` | boolean |
| `settings.dialogPadding` | CSS padding |
| `settings.dialogMaxWidth` | Max width |
| `settings.dialogMaxHeight` | Max height |

### `richText` / `richTextViewer`

Value shape: `string` (HTML).

### `messageCard`

| Property | Type | Notes |
|---|---|---|
| `tone` | `string` | `primary` `success` `warning` `risk` `neutral` `info` |
| `icon` | `string` | Icon name |
| `text` | `string` | Card message text |

### `statsCard`

| Property | Type | Notes |
|---|---|---|
| `value` | `string` | Main numeric/text value |
| `trend` | `string` | Trend direction |
| `trendValue` | `string` | Trend amount |

### `badge`

| Property | Type | Notes |
|---|---|---|
| `text` | `string` | Badge content |
| `tone` | `string` | `primary` `success` `warning` `risk` `neutral` `info` |

### `image`

| Property | Type | Notes |
|---|---|---|
| `src` | `string` | Image URL or JEXL expression |
| `alt` | `string` | Alt text |
| `objectFit` | `string` | CSS object-fit |

### `icon`

| Property | Type | Notes |
|---|---|---|
| `icon` | `string` | Icon name |
| `size` | `string` | Icon size |
| `tone` | `string` | Color tone |

### `divider`

No additional properties beyond base.

### `spacer`

| Property | Type | Notes |
|---|---|---|
| `height` | `string` | Spacer height |

### `pageTitle`

| Property | Type | Notes |
|---|---|---|
| `title` | `string` | Heading text |
| `subtitle` | `string` | Subheading text |

### `breadcrumbs`

| Property | Type | Notes |
|---|---|---|
| `items` | `array` | Breadcrumb items |

### `iframe`

| Property | Type | Notes |
|---|---|---|
| `src` | `string` | Source URL |
| `height` | `string` | Frame height |
| `scrolling` | `boolean` | |

### `slider`

| Property | Type | Notes |
|---|---|---|
| `min` | `number` | |
| `max` | `number` | |
| `step` | `number` | |
| `valueStorageType` | `string` | `number` or `string` |

### `numberStepper`

| Property | Type | Notes |
|---|---|---|
| `step` | `number` | Increment/decrement step |
| `min` | `number` | Min value |
| `max` | `number` | Max value |

Value shape: `number`.

### `timePicker`

| Property | Type | Notes |
|---|---|---|
| `placeholder` | `string` | |
| `minuteStep` | `number` | Minute increment shown in the picker |

Value shape: time string.

### `signaturePad`

| Property | Type | Notes |
|---|---|---|
| `canvasHeight` | `number` | Canvas height in px |
| `clearLabel` | `string` | Clear button label |
| `strokeColor` / `strokeWidth` / `backgroundColor` | `string` / `number` / `string` | Drawing style |
| `exportFormat` | `string` | `png` or `jpeg` |

Value shape: signature image data (per `exportFormat`), keyed under the element's `name`.

### `listBox`

| Property | Type | Notes |
|---|---|---|
| `selectionMode` | `string` | `single` or `multiple` |
| `dataSource` | `IElementDataSource` | Options from a datasource |
| `options` | `array` | Static options |
| `maxHeight` | `number` | List height in px |

Value shape: single value (`selectionMode: "single"`) or array (`selectionMode: "multiple"`).

### `selectButton`

| Property | Type | Notes |
|---|---|---|
| `multiple` | `boolean` | Allow selecting more than one option |
| `allowEmpty` | `boolean` | Allow deselecting to no value |
| `variant` | `string` | `buttons` or `segmented` |
| `orientation` | `string` | `horizontal` or `vertical` |
| `size` | `string` | `small` `normal` `large` |
| `tone` | `string` | `primary` `neutral` `success` `info` `warning` `risk` |

Value shape: single value, or array when `multiple` is `true`.

### `progressBar`

| Property | Type | Notes |
|---|---|---|
| `min` / `max` | `number` | Value bounds |
| `expression` | `string` | Computes the current value |
| `dataSource` / `progressDataPath` / `progressValuePath` / `progressMaxPath` | - | Drive the value from a datasource |
| `displayType` | `string` | `linear` or `circular` |
| `valueLabelMode` | `string` | `percent` `value` `fraction` |

Value shape: `number` (0 to `max`, default 100).

---

## `ISettings` fields

Only include settings actually needed by the form.

| Field | Type | Notes |
|---|---|---|
| `language` | `string` | Required. E.g. `"en"`, `"de"` |
| `locale` | `string` | E.g. `"en-US"`, `"lt-LT"` |
| `width` | `string` | Form width |
| `widthUnit` | `"px" \| "%"` | |
| `renderMode` | `"page" \| "dialog"` | |
| `theme` | `"light" \| "dark"` | |
| `pageNavigationMode` | `"default" \| "stepper"` | |
| `allowStepWithoutValidation` | `boolean` | |
| `pageNavigationPosition` | `"top" \| "bottom" \| "both" \| "none"` | |
| `stepperPosition` | `"top" \| "bottom" \| "both" \| "none"` | |
| `actionButtonsPosition` | `"top" \| "bottom" \| "both" \| "none"` | |
| `showSubmitButton` | `boolean` | |
| `showValidateButton` | `boolean` | |
| `showValidationIssuesModal` | `boolean` | |
| `elementSpacing` | `string` | Gap between rows |
| `customCss` | `string` | Raw CSS injected |
| `lazyElementRendering` | `boolean` | Lazy-render off-screen elements |

---

## `IDataSource` fields (top-level dataSources array)

`{ name, title, type, params }`. `type` is one of `rest` `local` `route` `websocket`, and `params` is a plain object whose keys depend on that type.

```json
{
  "dataSources": [
    { "name": "ds1", "title": "List", "type": "rest",
      "params": { "url": "/api/items", "method": "GET" } },

    { "name": "ds2", "title": "Save", "type": "rest",
      "params": { "url": "/api/items/{id}", "method": "PUT", "body": { "name": "{el1}" } } },

    { "name": "ds3", "title": "Paged table", "type": "rest",
      "params": { "url": "/api/items/search", "method": "TABLE-POST" } },

    { "name": "ds4", "title": "Static list", "type": "local",
      "params": { "localMode": "json", "dataJson": "[{\"id\":1,\"name\":\"A\"}]" } },

    { "name": "ds5", "title": "From form data", "type": "local",
      "params": { "localMode": "dataPath", "dataPath": "el9.items" } },

    { "name": "ds6", "title": "Route data", "type": "route",
      "params": { "routeDataKey": "record", "routeDataPath": "data" } },

    { "name": "ds7", "title": "Live feed", "type": "websocket",
      "params": { "url": "wss://host/feed", "protocols": "", "message": "{}",
                  "messagePath": "payload", "messageMode": "pushValuesInArray" } }
  ]
}
```

| `type` | `params` keys |
|---|---|
| `rest` | `url` (required), `method` (`GET` `POST` `PUT` `PATCH` `DELETE`, or `TABLE-POST` for a lazy `table`), `body` (alias `payload`) |
| `local` | `localMode` (`json` or `dataPath`), then `dataJson` (a JSON **string**) and `dataFunction`, or `dataPath` |
| `route` | `routeDataKey`, `routeDataPath` |
| `websocket` | `url`, `protocols`, `message`, `messagePath`, `messageMode` (`replaceCurrent` or `pushValuesInArray`) |

URL and body templates use **single** braces: `{el1}`, `{row.id}`, `{__variables.tenantId}`.

---

## `IElementDataSource` (element-level dataSource field)

```json
{
  "dataSource": {
    "name": "loadCities",
    "useFor": "option",
    "optionValue": "id",
    "optionLabel": "name",
    "refreshPaths": ["countryField"],
    "params": [{ "name": "country", "value": "{countryField}" }]
  }
}
```

| Field | Type | Notes |
|---|---|---|
| `name` | `string` | References a top-level dataSource name |
| `useFor` | `"option" \| "value"` | Whether datasource feeds options or element value |
| `optionValue` | `string` | Property path for option value |
| `optionLabel` | `string` | Property path for option label |
| `filterOptionsBy` | `string` | JEXL expression using `item.*` to filter options |
| `params` | `IDataSourceParamMapping[]` | `[{ "name": "key", "value": "{field}" }]` |
| `refreshOnChange` | `boolean` | Re-fetch when any dependency changes |
| `refreshPaths` | `string[]` | Re-fetch only when these fields change |

---

## Canonical type string list

```
text | textarea | number | slider | phoneInput | fileUpload | button | numberStepper | signaturePad
select | multiSelect | radio | checkbox | singleCheckbox | toggleSwitch | toggleButton | autocomplete | selectButton | listBox
datepicker | dateRange | timePicker
panel | dynamicPanel | tabs | tabsPro | accordion | dialog | splitter | progressFlow | emptyBlock
dynamicTable | table | listGrid | chart
richText | richTextViewer | customHtml | htmlSnippet | image | video | iframe | avatar | icon | routerOutlet
divider | spacer | breadcrumbs | pageTitle | badge | messageCard | statsCard | toast | progressBar
page
```

Type strings are exact and case-sensitive. Never alter capitalization.

---

## AI: Common mistakes and anti-patterns

Source: https://ngxviewbuilder.io/ai/common-mistakes

# AI: Common mistakes and anti-patterns

This page exists so that the agent does not keep repeating the same mistakes when generating NGX View Builder JSON.

## 1. Wrong element selection

### Mistake

The user asks for a "dynamic table" and the agent generates `table`.

### What to do correctly

- Use `dynamicTable` for editable rows with `add row` and `delete row`.
- Use `table` for server-side data grid scenarios.

## 2. Self-reference expression

### Mistake

```json
{
  "name": "lastName",
  "expression": "{firstName} == 'John' ? 'Doe' : {lastName}"
}
```

### Problem

- the element references itself
- the logic may not work or may behave unpredictably

### Correct

```json
{
  "name": "lastName",
  "expression": "{firstName} == 'John' ? 'Doe' : ''",
  "logicExecutionMode": "onChange"
}
```

## 3. Mixing `pages` and `elements`

### Mistake

- the agent places a full element object directly in `pages.rows.columns`

### Correct

- `pages` holds only layout
- `columns[*].elementRef` points to `elements`

## 4. Missing `page` entry in the `elements` map

### Mistake

Present:

```json
{
  "pages": [{ "name": "page1", "rows": [] }]
}
```

but missing:

```json
{
  "elements": {
    "page1": {
      "name": "page1",
      "type": "page",
      "label": "Page 1"
    }
  }
}
```

## 5. Generating non-existent properties

### Mistake

- the agent invents custom properties that NGX View Builder does not have

### Rule

- if you cannot find a property in the documentation or catalog, do not use it

## 6. Too much metadata

### Mistake

- unnecessary `settings` or extra wrappers are added

### Rule

- keep only properties that are actually used
- if a feature is not active, it is better to omit its child properties

## 7. Wrong value shape

Typical mistakes:

- `dateRange` returns a string instead of `{ dateFrom, dateTo }`
- `multiSelect` returns a single value instead of an array
- `singleCheckbox` returns a string instead of `boolean`
- `dynamicPanel` or `dynamicTable` does not return an array

## 8. Logic without `onChange` when recalculation is needed

### Symptom

- the form renders, but the interdependency logic does not work as expected

### Why

- the execution mode is missing, and the default is `onBlur`

With `onBlur` the logic only re-runs once the field loses focus, so someone typing in the form sees nothing happen and reports the logic as broken.

### Rule

- if one field's value must immediately affect another field, set `logicExecutionMode: "onChange"`
- if validation has to follow the typing, set `validationExecutionMode: "onChange"` as well

## 8b. `hideIf` and other logic keys that do not exist

### Mistake

```json
{
  "name": "companyCode",
  "hideIf": "{customerType} != 'company'"
}
```

### Problem

There is no `hideIf`. The logic keys are exactly `visibleIf`, `disableIf`, `requireIf`, `readonlyIf`, `resetIf` and `expression`, and they are matched exactly, so `readOnlyIf` with a capital O misses too.

This is the worst kind of mistake to debug, because nothing complains. The property is stored, the JSON reviews as correct, no dependency is ever registered for it, and the field simply stays visible forever. Deleting the element and adding the same rule by hand in the builder makes it work, which sends everyone hunting for a bug that is not there.

### Correct

`visibleIf` states when the element **is** shown, so invert the condition instead of renaming the key.

```json
{
  "name": "companyCode",
  "visibleIf": "{customerType} == 'company'",
  "logicExecutionMode": "onChange"
}
```

## 9. Overly aggressive rewrite of an existing form

### Mistake

- the user asks to add one field, and the agent rebuilds the entire form from scratch

### Rule

- in extension mode, change only what is relevant to the task
- do not remove `dataSources`, `localization`, `settings`, or other sections without reason

## 10. Broken datasource references

### Mistake

- an element references `dataSourceName` but no such datasource exists
- a datasource exists but the item path or value/label mapping is wrong

### Rule

- every datasource reference must point to a real, documented object

## 11. Using `name` instead of `key` in `table` columns

### Mistake

```json
{
  "type": "table",
  "columnsConfig": [
    {
      "name": "firstName",
      "label": "First Name",
      "type": "text"
    }
  ]
}
```

### Problem

- `table` renders columns by `columnsConfig[*].key`
- if only `name` is present, the column may not be rendered at all

### Correct

```json
{
  "type": "table",
  "columnsConfig": [
    {
      "key": "firstName",
      "label": "First Name",
      "type": "text",
      "showInTable": true
    }
  ]
}
```

## 12. Custom frontend instead of NGX View Builder

### Mistake

- the agent starts suggesting `Angular` components, custom templates, or an API layer, even though an NGX View Builder form was requested

### Rule

- the first choice is always the built-in NGX View Builder JSON model

## 13. Prose instead of JSON

### Mistake

- the user asks to generate a form, and the agent writes an explanation followed by JSON

### Rule

- in generation mode, return only JSON

## 14. Wrong element type casing

### Mistake

<!-- deliberately incorrect: kept as the counter-example -->

```json
{ "type": "datePicker" }
{ "type": "SingleCheckbox" }
{ "type": "DynamicTable" }
{ "type": "richtext" }
{ "type": "fileupload" }
```

### Rule

Type strings are **exact lowercase camelCase**. The canonical list:

```
text | textarea | number | slider | phoneInput | fileUpload | button | numberStepper | signaturePad
select | multiSelect | radio | checkbox | singleCheckbox | toggleSwitch | toggleButton | autocomplete | selectButton | listBox
datepicker | dateRange | timePicker
panel | dynamicPanel | tabs | tabsPro | accordion | dialog | splitter | progressFlow | emptyBlock
dynamicTable | table | listGrid | chart
richText | richTextViewer | customHtml | htmlSnippet | image | video | iframe | avatar | icon | routerOutlet
divider | spacer | breadcrumbs | pageTitle | badge | messageCard | statsCard | toast | progressBar
page
```

Never invent capitalization variants. Copy from the list above.

## 15. Wrong validator field names

### Mistake

```json
{
  "validators": [
    {
      "type": "minLength",
      "expression": "{firstName}.length > 0",
      "message": "Required"
    }
  ]
}
```

### Problem

- `expression` does not exist on `IValidator`
- `visibleIf` does not exist on `IValidator`

### Correct validator schema

```json
{
  "validators": [
    {
      "type": "minLength",
      "value": 3,
      "message": "Minimum 3 characters",
      "applyIf": "{otherField} != ''"
    },
    {
      "type": "custom",
      "condition": "dateDiffDays({startDate}, {endDate}) < 1",
      "message": "End date must be after start date"
    }
  ]
}
```

Exact fields allowed on a validator:
- `type`: validator type string (required)
- `value`: threshold value when applicable (`number | string`)
- `message`: error message shown to user
- `condition`: JEXL expression, the *failing* check. The validator error is shown while it evaluates to `true`
- `applyIf`: JEXL expression, the validator runs only when this is truthy

**Never use `expression`, `visibleIf`, `disableIf`, or any other logic field on a validator object.**

## 16. Using logic field names that belong to elements on validators

### Mistake

Copying `visibleIf`, `requireIf`, `readonlyIf`, `disableIf`, `expression`, `resetIf` from element-level logic into a validator object. Those fields do not exist on `IValidator`.

### Rule

Element-level logic (`visibleIf`, `disableIf`, `requireIf`, `readonlyIf`, `resetIf`, `expression`) belongs directly on the element, not inside the `validators` array.

```json
{
  "name": "birthDate",
  "type": "datepicker",
  "requireIf": "{needsBirthDate} == true",
  "validators": [
    {
      "type": "maxDate",
      "value": "today",
      "message": "Cannot be in the future"
    }
  ]
}
```

## 17. Wrapping logic fields in a `logic` object

### Mistake

```json
{
  "name": "totalAmount",
  "type": "number",
  "logic": {
    "expression": "{price} * {qty}",
    "logicExecutionMode": "onChange"
  }
}
```

### Problem

- There is no `logic` key in the NGX View Builder element schema.
- The renderer ignores the `logic` wrapper, so the expression never runs.

### Correct

Logic fields are **direct element-level properties**, never nested:

```json
{
  "name": "totalAmount",
  "type": "number",
  "expression": "{price} * {qty}",
  "logicExecutionMode": "onChange"
}
```

The same rule applies to `visibleIf`, `disableIf`, `requireIf`, `readonlyIf`, and `resetIf`.

## 18. Putting a container's children inside the element definition

This is the single most damaging generation error. The panel renders, and it is **empty**.

### Mistake

<!-- deliberately incorrect: kept as the counter-example -->

```json
{
  "elements": {
    "panelGeneral": {
      "name": "panelGeneral",
      "type": "panel",
      "label": "General",
      "rows": [
        { "columns": [{ "elementRef": "firstName" }, { "elementRef": "lastName" }] }
      ]
    }
  }
}
```

### Problem

- `IBaseElement` has no `rows` property. The array is ignored.
- `firstName` and `lastName` are never placed in the layout tree, so they never render.
- The same applies to invented keys such as `children`, `elements`, `items`, `content`, `fields`.

### Correct

Children belong to the **column that references the container**, in `pages`:

```json
{
  "pages": [
    {
      "name": "page1",
      "rows": [
        {
          "columns": [
            {
              "elementRef": "panelGeneral",
              "rows": [
                { "columns": [{ "elementRef": "firstName" }, { "elementRef": "lastName" }] }
              ]
            }
          ]
        }
      ]
    }
  ],
  "elements": {
    "page1": { "name": "page1", "type": "page", "label": "Page 1" },
    "panelGeneral": { "name": "panelGeneral", "type": "panel", "label": "General" },
    "firstName": { "name": "firstName", "type": "text", "label": "First name" },
    "lastName": { "name": "lastName", "type": "text", "label": "Last name" }
  }
}
```

`elements` is a **flat map**. It never nests. Full rules: [Layout model](https://ngxviewbuilder.io/ai/layout-model).

## 19. Widths written on columns

### Mistake

```json
{
  "columns": [
    { "elementRef": "firstName", "width": "50%", "mobileWidth": "100%" },
    { "elementRef": "lastName", "width": "50%", "mobileWidth": "100%" }
  ]
}
```

### Problem

- `IColumn` has exactly these keys: `elementRef`, `rows`, `tabRows`, `fragmentRef`, `fragmentBindings`, `fragmentMode`. Everything else is dropped.
- The width was never applied, and the JSON is now noisier and harder to review.
- Worse, it hides the real intent: two columns in one row **already** split evenly (`flex: 1 1 0`).

### Correct

For an even split, write nothing:

```json
{ "columns": [{ "elementRef": "firstName" }, { "elementRef": "lastName" }] }
```

For an uneven split, put `width` / `tabletWidth` / `mobileWidth` on the **element**:

```json
{
  "postCode": { "name": "postCode", "label": "Post code", "type": "text", "width": "160px" }
}
```

## 20. Using `parentName` to declare structure

### Mistake

```json
{ "name": "firstName", "type": "text", "parentName": "panelGeneral" }
```

### Problem

`parentName` exists on `IBaseElement`, but it is runtime bookkeeping, not the structure declaration. Setting it does not place the element anywhere.

### Rule

The layout tree in `pages` is the **only** source of parentage.

## 21. One page per visual section

### Mistake

A screenshot shows four titled sections, and the agent emits four entries in `pages`.

### Problem

A `page` is a **step or screen**, navigated by the pager or stepper. Four pages means a four-step wizard, not four sections stacked on one screen.

### Correct

One page, four `panel` elements at the top level of its `rows`, each panel's `label` being the section heading.

## 22. Invented properties that look plausible

Every one of these has been generated by an agent and none of them exists:

| Invented | What is actually there |
|---|---|
| `panel.rows`, `panel.children`, `panel.items` | children go in `column.rows` |
| `column.width`, `column.mobileWidth`, `column.span` | width goes on the element |
| `singleCheckbox.checkedValue` / `uncheckedValue` | `singleCheckbox` stores `true`/`false`; the side text is `checkboxLabel` |
| `phoneInput.maskType`, `phoneInput.inputMode`, `phoneInput.defaultValue` | `defaultCountryCode` (ISO code such as `"LT"`), `allowedCountryCodes` |
| `text.maskType: "personalCodeLt"` / `"phoneLt"` | masks are exactly `none` `phoneIntl` `date` `time` `dateTime` `digits` `custom` |
| `datepicker.format: "yyyy-MM-dd"` | uppercase tokens only: `YYYY-MM-DD`, `DD.MM.YYYY`, ... |
| `element.logic { ... }` wrapper | logic fields sit directly on the element |
| `validator.expression` | `validator.condition` |
| `"type": "code"`, `"type": "dropdown"` | neither element type exists; use `textarea` and `select` |
| `select.placeholder` for the closed-state text | that text is the UI translation `select.placeholder`; the property only sets the dropdown's search hint |
| `dataSources[*].paramMap` | the field is `params` |
| `"params": [["id", "{row.id}"]]` | `"params": [{ "name": "id", "value": "{row.id}" }]` |
| `table.params: [{ "name", "value" }]` | table request params are `[{ "paramName", "paramValue" }]` |
| `table.columnsConfig[*].name` | `key` |
| `dynamicTable.columns[*].key` | `name` |

### Rule

If a property is not in [the properties reference](https://ngxviewbuilder.io/ai/properties-reference), it does not exist. Omitting a nicety is always better than inventing a property: an invented property is silently ignored, so the form ships subtly broken with no error anywhere.

## Final anti-pattern checklist

Before returning a response, the agent must verify:

1. Is the correct element chosen.
2. Are `pages` and `elements` not mixed up.
3. Do all `elementRef` values point to valid entries.
4. Is there no self-reference expression.
5. Is the value shape correct.
6. Are there no invented properties.
7. Do `table.columnsConfig[*]` entries use `key`, and `dynamicTable.columns[*]` entries use `name`. The two tables do not share a column shape.
8. Is the existing form context preserved.
9. Are logic fields (`expression`, `visibleIf`, `disableIf`, `requireIf`, `readonlyIf`, `resetIf`, `logicExecutionMode`) placed directly on the element, not inside a `logic` wrapper, and spelled exactly. No `hideIf`, no `readOnlyIf`.
9b. Does every element carrying logic or typing dependent validation set `logicExecutionMode` or `validationExecutionMode` to `onChange`, since both default to `onBlur`.
10. Does any object in `elements` contain `rows`, `columns`, `children` or `items` as a way of holding child elements. It must not.
11. Does any column object carry a key other than `elementRef`, `rows`, `tabRows`, `fragmentRef`, `fragmentBindings`, `fragmentMode`.
12. Are widths on elements rather than columns, and absent entirely wherever an even split is wanted.
13. Is the number of `pages` equal to the number of real steps, not the number of visual sections.

---

## AI: Verified example structures

Source: https://ngxviewbuilder.io/ai/examples

# AI: Verified example structures

Every JSON block on this page is checked against the library source: element type strings against the element registry, property names against the builder property datasets, sub-object fields against the TypeScript interfaces. Copy the **shapes** from here; invent nothing that is not shown or listed in [the properties reference](https://ngxviewbuilder.io/ai/properties-reference).

Names are deliberately generic (`el1`, `column1`, `ds1`) so the structure is what stands out, not the naming.

## How to read these examples

1. Layout is always `pages` → `rows` → `columns` → `elementRef`. Configuration is always the flat `elements` map. See [Layout model](https://ngxviewbuilder.io/ai/layout-model) first.
2. Anything a container holds is attached to the **column** that references it, never inside the element.
3. A property that does not appear on this page or in the properties reference does not exist. An invented property is dropped silently, so the view ships subtly broken with no error.

---

## 1. Skeleton and layout grammar

One page, four bands: full width, even halves, uneven thirds, and a mobile-stacking trio.

```json
{
  "schemaVersion": 1,
  "settings": {
    "language": "en",
    "locale": "en-US",
    "width": "900px",
    "widthUnit": "px",
    "renderMode": "page",
    "elementSpacing": "12px"
  },
  "pages": [
    {
      "name": "page1",
      "rows": [
        { "columns": [{ "elementRef": "el1" }] },
        { "columns": [{ "elementRef": "el2" }, { "elementRef": "el3" }] },
        { "columns": [{ "elementRef": "el4" }, { "elementRef": "el5" }] },
        {
          "columns": [
            { "elementRef": "el6" },
            { "elementRef": "el7" },
            { "elementRef": "el8" }
          ]
        }
      ]
    }
  ],
  "elements": {
    "page1": { "name": "page1", "label": "Page 1", "type": "page", "hideHeader": true },

    "el1": { "name": "el1", "label": "Full width", "type": "text" },

    "el2": { "name": "el2", "label": "Half", "type": "text" },
    "el3": { "name": "el3", "label": "Half", "type": "text" },

    "el4": { "name": "el4", "label": "Narrow", "type": "text", "width": "160px" },
    "el5": { "name": "el5", "label": "Takes the rest", "type": "text" },

    "el6": { "name": "el6", "label": "Third", "type": "text", "mobileWidth": "100%" },
    "el7": { "name": "el7", "label": "Third", "type": "text", "mobileWidth": "100%" },
    "el8": { "name": "el8", "label": "Third", "type": "text", "mobileWidth": "100%" }
  },
  "localization": { "defaultLanguage": "en", "languages": ["en"] }
}
```

What to take from it:

- `el2` / `el3` split 50/50 with **no width property at all**. Columns with no width get `flex: 1 1 0`.
- `el4` is fixed at `160px`, so `el5` absorbs the remainder. Width is on the element, never on the column.
- `mobileWidth: "100%"` is what makes a row stack on phones.

---

## 2. Containers

### 2.1 Panels as titled sections

```json
{
  "pages": [
    {
      "name": "page1",
      "rows": [
        {
          "columns": [
            {
              "elementRef": "panel1",
              "rows": [
                { "columns": [{ "elementRef": "el1" }, { "elementRef": "el2" }] },
                { "columns": [{ "elementRef": "el3" }] }
              ]
            }
          ]
        },
        {
          "columns": [
            {
              "elementRef": "panel2",
              "rows": [{ "columns": [{ "elementRef": "el4" }, { "elementRef": "el5" }] }]
            }
          ]
        }
      ]
    }
  ],
  "elements": {
    "page1": { "name": "page1", "label": "Page 1", "type": "page" },
    "panel1": {
      "name": "panel1",
      "label": "Section one",
      "type": "panel",
      "showBorder": false,
      "panelPadding": "0px",
      "titleUnderline": true
    },
    "panel2": {
      "name": "panel2",
      "label": "Section two",
      "type": "panel",
      "showBorder": true,
      "panelBorderWidth": "1px",
      "panelRadius": "8px",
      "panelPadding": "16px",
      "contentGap": "12px"
    },
    "el1": { "name": "el1", "label": "Field 1", "type": "text" },
    "el2": { "name": "el2", "label": "Field 2", "type": "text" },
    "el3": { "name": "el3", "label": "Field 3", "type": "textarea", "rows": 3 },
    "el4": { "name": "el4", "label": "Field 4", "type": "text" },
    "el5": { "name": "el5", "label": "Field 5", "type": "text" }
  }
}
```

### 2.2 Tabs (`tabRows`, keyed by tab value)

```json
{
  "pages": [
    {
      "name": "page1",
      "rows": [
        {
          "columns": [
            {
              "elementRef": "el1",
              "tabRows": {
                "tab1": [{ "columns": [{ "elementRef": "el2" }, { "elementRef": "el3" }] }],
                "tab2": [{ "columns": [{ "elementRef": "el4" }] }]
              }
            }
          ]
        }
      ]
    }
  ],
  "elements": {
    "page1": { "name": "page1", "label": "Page 1", "type": "page" },
    "el1": {
      "name": "el1",
      "label": "Details",
      "type": "tabs",
      "tabsPosition": "top",
      "tabsVariant": "underline",
      "fullWidthTabs": false,
      "tabs": [
        { "value": "tab1", "label": "General" },
        { "value": "tab2", "label": "Address" }
      ]
    },
    "el2": { "name": "el2", "label": "First name", "type": "text" },
    "el3": { "name": "el3", "label": "Last name", "type": "text" },
    "el4": { "name": "el4", "label": "Street", "type": "text" }
  }
}
```

`tabsPro` is the same element with the same properties; its list property is `items` instead of `tabs`.

### 2.3 Accordion and splitter

Both key their `tabRows` by the `value` of each entry in their own list property (`items` for accordion, `panels` for splitter).

```json
{
  "pages": [
    {
      "name": "page1",
      "rows": [
        {
          "columns": [
            {
              "elementRef": "el1",
              "tabRows": {
                "item1": [{ "columns": [{ "elementRef": "el3" }] }],
                "item2": [{ "columns": [{ "elementRef": "el4" }] }]
              }
            }
          ]
        },
        {
          "columns": [
            {
              "elementRef": "el2",
              "tabRows": {
                "left": [{ "columns": [{ "elementRef": "el5" }] }],
                "right": [{ "columns": [{ "elementRef": "el6" }] }]
              }
            }
          ]
        }
      ]
    }
  ],
  "elements": {
    "page1": { "name": "page1", "label": "Page 1", "type": "page" },
    "el1": {
      "name": "el1",
      "label": "Sections",
      "type": "accordion",
      "allowMultiple": false,
      "openFirst": true,
      "items": [
        { "value": "item1", "label": "Contact" },
        { "value": "item2", "label": "Billing" }
      ]
    },
    "el2": {
      "name": "el2",
      "label": "Workspace",
      "type": "splitter",
      "orientation": "horizontal",
      "allowResize": true,
      "gutterSize": "6px",
      "minPanelSize": "160px",
      "showPanelHeaders": true,
      "panels": [
        { "value": "left", "label": "Filters" },
        { "value": "right", "label": "Results" }
      ]
    },
    "el3": { "name": "el3", "label": "Email", "type": "text" },
    "el4": { "name": "el4", "label": "IBAN", "type": "text" },
    "el5": { "name": "el5", "label": "Search", "type": "text" },
    "el6": { "name": "el6", "label": "Notes", "type": "textarea" }
  }
}
```

### 2.4 `emptyBlock` as a CSS grid

`emptyBlock` is the unstyled layout box. Use it when a `panel` would add unwanted chrome, or when you need real grid/flex control.

```json
{
  "pages": [
    {
      "name": "page1",
      "rows": [
        {
          "columns": [
            {
              "elementRef": "el1",
              "rows": [
                {
                  "columns": [
                    { "elementRef": "el2" },
                    { "elementRef": "el3" },
                    { "elementRef": "el4" }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  ],
  "elements": {
    "page1": { "name": "page1", "label": "Page 1", "type": "page" },
    "el1": {
      "name": "el1",
      "type": "emptyBlock",
      "contentDisplay": "grid",
      "gridTemplateColumns": "repeat(3, minmax(0, 1fr))",
      "contentGap": "16px",
      "panelPadding": "16px",
      "panelBackgroundColor": "#f6f8fa",
      "panelRadius": "10px"
    },
    "el2": { "name": "el2", "label": "Open", "type": "statsCard", "valueText": "128", "variant": "info" },
    "el3": { "name": "el3", "label": "Closed", "type": "statsCard", "valueText": "47", "variant": "success" },
    "el4": { "name": "el4", "label": "Overdue", "type": "statsCard", "valueText": "9", "variant": "risk" }
  }
}
```

### 2.5 In-view `dialog` element

The `dialog` **element** is a modal that lives inside a page, opened by an action or `openIf`. It is not the same as `settings.renderMode: "dialog"`, which renders the whole view as a modal.

```json
{
  "pages": [
    {
      "name": "page1",
      "rows": [
        { "columns": [{ "elementRef": "el1" }] },
        {
          "columns": [
            {
              "elementRef": "el2",
              "rows": [
                { "columns": [{ "elementRef": "el3" }] },
                { "columns": [{ "elementRef": "el4" }] }
              ]
            }
          ]
        }
      ]
    }
  ],
  "elements": {
    "page1": { "name": "page1", "label": "Page 1", "type": "page" },
    "el1": {
      "name": "el1",
      "label": "",
      "type": "button",
      "text": "Edit record",
      "variant": "solid",
      "tone": "primary",
      "fitContent": true,
      "events": [
        { "trigger": "click", "type": "dialog", "dialogName": "el2", "dialogOperation": "open" }
      ]
    },
    "el2": {
      "name": "el2",
      "label": "Edit record",
      "type": "dialog",
      "showTriggerButton": false,
      "showCloseButton": true,
      "closeOnBackdrop": true,
      "dialogWidth": "560px"
    },
    "el3": { "name": "el3", "label": "Title", "type": "text", "required": true },
    "el4": {
      "name": "el4",
      "label": "",
      "type": "button",
      "text": "Save",
      "variant": "solid",
      "tone": "primary",
      "fitContent": true,
      "events": [
        {
          "trigger": "click",
          "type": "dataSource",
          "dataSourceName": "ds1",
          "validateForm": true,
          "showToastAfter": true,
          "toastTitle": "Saved",
          "toastVariant": "success"
        },
        { "trigger": "click", "type": "dialog", "dialogName": "el2", "dialogOperation": "close" }
      ]
    }
  }
}
```

---

## 3. Input elements

Every property below is real. Notice what each element does **not** have: `phoneInput` has no mask, `singleCheckbox` has no `checkedValue`, `datepicker` formats use uppercase tokens.

```json
{
  "elements": {
    "el1": {
      "name": "el1",
      "label": "Text",
      "type": "text",
      "placeholder": "Type here",
      "minlength": 2,
      "maxlength": 60,
      "showMaxLengthCounter": true,
      "inputMode": "text",
      "spellcheck": false,
      "autocomplete": "off",
      "required": true,
      "requiredMessage": "This field is required"
    },
    "el2": {
      "name": "el2",
      "label": "Masked text",
      "type": "text",
      "maskType": "custom",
      "maskPattern": "AA-0000",
      "placeholder": "AB-1234"
    },
    "el3": {
      "name": "el3",
      "label": "Textarea",
      "type": "textarea",
      "rows": 4,
      "maxlength": 500,
      "showMaxLengthCounter": true
    },
    "el4": {
      "name": "el4",
      "label": "Number",
      "type": "number",
      "min": 0,
      "max": 1000000,
      "step": 0.01,
      "inputMode": "decimal",
      "valueStorageType": "number",
      "visualFormatEnabled": true,
      "visualFormatLocale": "lt-LT",
      "visualFormatUseGrouping": true,
      "visualFormatMinFractionDigits": 2,
      "visualFormatMaxFractionDigits": 2
    },
    "el5": {
      "name": "el5",
      "label": "Slider",
      "type": "slider",
      "min": 0,
      "max": 100,
      "step": 5,
      "showValueLabel": true,
      "defaultValue": 20
    },
    "el6": {
      "name": "el6",
      "label": "Stepper",
      "type": "numberStepper",
      "min": 1,
      "max": 20,
      "step": 1,
      "defaultValue": 1
    },
    "el7": {
      "name": "el7",
      "label": "Phone",
      "type": "phoneInput",
      "defaultCountryCode": "LT",
      "allowedCountryCodes": ["LT", "LV", "EE"],
      "placeholder": "600 00000"
    },
    "el8": {
      "name": "el8",
      "label": "Date",
      "type": "datepicker",
      "placeholder": "Pick a date",
      "pickerMode": "date",
      "format": "YYYY-MM-DD",
      "minValue": "today",
      "validators": [{ "type": "maxDate", "value": "today", "message": "Cannot be in the future" }]
    },
    "el9": {
      "name": "el9",
      "label": "Date and time",
      "type": "datepicker",
      "pickerMode": "datetime",
      "includeSeconds": false,
      "format": "YYYY-MM-DD HH:mm"
    },
    "el10": {
      "name": "el10",
      "label": "Date range",
      "type": "dateRange",
      "format": "YYYY-MM-DD",
      "placeholder": "From - to"
    },
    "el11": { "name": "el11", "label": "Time", "type": "timePicker", "minuteStep": 15 },
    "el12": {
      "name": "el12",
      "label": "Attachments",
      "type": "fileUpload",
      "accept": ".pdf,image/*",
      "multiple": true,
      "maxFiles": 5,
      "maxFileSizeMb": 10,
      "showPreview": true,
      "dropzoneText": "Drop files here",
      "uploadDataSourceName": "ds1",
      "downloadDataSourceName": "ds2",
      "deleteDataSourceName": "ds3",
      "uploadFormFieldName": "file",
      "fileKeyField": "key",
      "fileNameField": "name",
      "fileTypeField": "contentType",
      "fileSizeField": "size"
    },
    "el13": {
      "name": "el13",
      "label": "Signature",
      "type": "signaturePad",
      "canvasHeight": "180px",
      "strokeColor": "#111827",
      "strokeWidth": 2,
      "backgroundColor": "#ffffff",
      "exportFormat": "png",
      "clearLabel": "Clear"
    },
    "el14": {
      "name": "el14",
      "label": "Rich text",
      "type": "richText",
      "toolbarTools": ["bold", "italic", "underline", "bulletList", "link"]
    }
  }
}
```

Value shapes: `text` / `textarea` / `richText` store a string, `number` / `slider` / `numberStepper` a number, `dateRange` an object `{ dateFrom, dateTo }`, `fileUpload` the upload response object (or an array of them), `timePicker` a time string.

---

## 4. Choice elements

```json
{
  "elements": {
    "el1": {
      "name": "el1",
      "label": "Select",
      "type": "select",
      "showSearch": true,
      "strictOptions": true,
      "defaultValue": "a",
      "options": [
        { "value": "a", "label": "Option A" },
        { "value": "b", "label": "Option B" },
        { "value": "c", "label": "Option C" }
      ]
    },
    "el2": {
      "name": "el2",
      "label": "Multi select",
      "type": "multiSelect",
      "showSearch": true,
      "strictOptions": true,
      "options": [
        { "value": "a", "label": "Option A" },
        { "value": "b", "label": "Option B" }
      ]
    },
    "el3": {
      "name": "el3",
      "label": "Radio",
      "type": "radio",
      "showInline": true,
      "defaultValue": "y",
      "options": [
        { "value": "y", "label": "Yes" },
        { "value": "n", "label": "No" }
      ]
    },
    "el4": {
      "name": "el4",
      "label": "Checkbox group",
      "type": "checkbox",
      "showInline": false,
      "options": [
        { "value": "a", "label": "Option A" },
        { "value": "b", "label": "Option B" }
      ]
    },
    "el5": {
      "name": "el5",
      "label": "",
      "type": "singleCheckbox",
      "checkboxLabel": "I accept the terms",
      "defaultValue": false,
      "required": true,
      "requiredMessage": "You must accept the terms"
    },
    "el6": {
      "name": "el6",
      "label": "Toggle",
      "type": "toggleSwitch",
      "trueLabel": "On",
      "falseLabel": "Off",
      "trueValue": true,
      "falseValue": false,
      "defaultValue": false
    },
    "el7": {
      "name": "el7",
      "label": "Segmented",
      "type": "selectButton",
      "orientation": "horizontal",
      "multiple": false,
      "allowEmpty": false,
      "variant": "outline",
      "size": "normal",
      "showSelectedIcon": true,
      "options": [
        { "value": "day", "label": "Day" },
        { "value": "week", "label": "Week" },
        { "value": "month", "label": "Month" }
      ]
    },
    "el8": {
      "name": "el8",
      "label": "List box",
      "type": "listBox",
      "selectionMode": "multiple",
      "maxHeight": "220px",
      "options": [
        { "value": "a", "label": "Option A" },
        { "value": "b", "label": "Option B" },
        { "value": "c", "label": "Option C" }
      ]
    },
    "el9": {
      "name": "el9",
      "label": "Autocomplete",
      "type": "autocomplete",
      "placeholder": "Start typing",
      "minSearchLength": 2,
      "debounceMs": 300,
      "maxSuggestions": 20,
      "forceSelection": true,
      "lazyLoad": true,
      "queryContextKey": "query",
      "dataSource": {
        "name": "ds1",
        "useFor": "option",
        "optionValue": "id",
        "optionLabel": "name"
      }
    }
  }
}
```

Value shapes: `select` / `radio` / `selectButton` / `autocomplete` store a single value; `multiSelect` / `checkbox` store an array; `listBox` stores a single value or an array depending on `selectionMode`; `singleCheckbox` / `toggleSwitch` store a boolean.

---

## 5. Content and feedback elements

```json
{
  "elements": {
    "el1": {
      "name": "el1",
      "label": "",
      "type": "pageTitle",
      "title": "Customer records",
      "subtitle": "Everything the support desk needs",
      "level": 2,
      "align": "left",
      "showDivider": true
    },
    "el2": {
      "name": "el2",
      "label": "",
      "type": "messageCard",
      "title": "Heads up",
      "descriptionText": "Changes are applied immediately.",
      "variant": "info",
      "showIcon": true,
      "dismissible": true,
      "initiallyVisible": true
    },
    "el3": {
      "name": "el3",
      "label": "",
      "type": "statsCard",
      "title": "Open tickets",
      "valueText": "128",
      "variant": "info",
      "icon": "inbox",
      "trendDirection": "up",
      "trendText": "+12 this week"
    },
    "el4": {
      "name": "el4",
      "label": "",
      "type": "badge",
      "text": "Beta",
      "variant": "warning",
      "pill": true,
      "size": "small"
    },
    "el5": {
      "name": "el5",
      "label": "",
      "type": "progressBar",
      "min": 0,
      "max": 100,
      "displayType": "bar",
      "variant": "success",
      "showValueLabel": true,
      "valueLabelMode": "percent"
    },
    "el6": { "name": "el6", "label": "", "type": "divider", "orientation": "horizontal", "thickness": "1px", "spacing": "16px" },
    "el7": { "name": "el7", "label": "", "type": "spacer", "axis": "vertical", "size": "24px" },
    "el8": {
      "name": "el8",
      "label": "",
      "type": "image",
      "src": "/assets/cover.png",
      "alt": "Cover",
      "fit": "cover",
      "aspectRatio": "16/9",
      "radius": "8px",
      "showPreview": true
    },
    "el9": {
      "name": "el9",
      "label": "",
      "type": "customHtml",
      "htmlTemplate": "<p class=\"note\">Reference: <b>{el1}</b></p>"
    },
    "el10": {
      "name": "el10",
      "label": "",
      "type": "richTextViewer",
      "htmlSourcePath": "el11"
    },
    "el11": {
      "name": "el11",
      "label": "",
      "type": "chart",
      "chartType": "bar",
      "chartHeight": "280px",
      "showLegend": true,
      "legendLayout": "horizontal",
      "labelKey": "label",
      "valueKey": "value",
      "chartDataPath": "stats.byMonth",
      "dataSource": { "name": "ds1", "useFor": "value" }
    }
  }
}
```

---

## 6. `table`: client-side data grid

This is the shape to reach for when the endpoint returns every row in one response. The table sorts, searches, filters, paginates and exports entirely in the browser.

```json
{
  "schemaVersion": 1,
  "settings": { "language": "en", "locale": "en-US", "width": "1180px", "widthUnit": "px" },
  "pages": [
    {
      "name": "page1",
      "rows": [
        { "columns": [{ "elementRef": "el1" }] },
        { "columns": [{ "elementRef": "el3" }] },
        { "columns": [{ "elementRef": "el2" }] }
      ]
    }
  ],
  "elements": {
    "page1": { "name": "page1", "label": "Customers", "type": "page", "hideHeader": true },
    "el1": { "name": "el1", "label": "", "type": "pageTitle", "title": "Customers", "level": 2 },
    "el2": {
      "name": "el2",
      "label": "All customers",
      "type": "table",

      "dataSource": {
        "name": "ds1",
        "useFor": "value",
        "refreshOnChange": true,
        "refreshPaths": ["el3"]
      },
      "tableItemsPath": "data.items",

      "lazyLoad": false,
      "pageSize": 25,
      "pageSizeOptions": "10,25,50,100",
      "paginator": true,
      "paginatorStyle": "default",
      "paginatorVariant": "full",
      "paginatorAlign": "end",
      "paginatorMaxButtons": 7,
      "showPageSizeSelector": true,

      "tableStyle": "striped",
      "stickyHeader": true,
      "rowHover": true,
      "responsiveMode": "auto",
      "flatHeaderSurface": false,
      "flatFooterSurface": false,
      "emptyMessage": "No customers found",
      "loadingLabel": "Loading...",

      "showHeaderControls": true,
      "showQuickSearch": true,
      "quickSearchPlaceholder": "Search customers",
      "quickSearchCondition": "%-%",
      "quickSearchCaseMode": "caseInsensitiveLatin",
      "searchDebounceMs": 300,
      "showDetailedSearch": true,
      "detailedSearchCaseMode": "caseInsensitiveLatin",

      "showExport": true,
      "exportFileName": "customers",
      "exportUseColumnPicker": true,

      "showColumnSettings": true,
      "columnSettingsMode": "localStorage",
      "columnSettingsStorageKey": "customersTableColumns",
      "columnSettingsDialogTitle": "Visible columns",

      "orderClause": "column2 ASC",
      "orderDirection": "asc",

      "columnsConfig": [
        {
          "key": "column1",
          "label": "ID",
          "type": "number",
          "sortable": true,
          "width": "90px",
          "align": "right",
          "numberUseGrouping": false,
          "showInTable": true,
          "showInDetails": true
        },
        {
          "key": "column2",
          "label": "Name",
          "type": "text",
          "sortable": true,
          "showInTable": true,
          "filterControlType": "text"
        },
        {
          "key": "column3",
          "label": "Email",
          "type": "text",
          "sortable": true,
          "showInTable": true,
          "mobileLabel": "Mail"
        },
        {
          "key": "column4",
          "label": "Balance",
          "type": "number",
          "sortable": true,
          "align": "right",
          "formatLocale": "lt-LT",
          "numberMinFractionDigits": 2,
          "numberMaxFractionDigits": 2,
          "numberUseGrouping": true,
          "showInTable": true,
          "filterControlType": "number"
        },
        {
          "key": "column5",
          "label": "Created",
          "type": "dateTime",
          "sortable": true,
          "dateFormatPattern": "yyyy-MM-dd HH:mm",
          "dateIncludeSeconds": false,
          "showInTable": true,
          "filterControlType": "date"
        },
        {
          "key": "column6",
          "label": "Country",
          "type": "text",
          "showInTable": true,
          "filterControlType": "select",
          "filterOptionsSourceType": "static",
          "filterOptions": [
            { "value": "LT", "label": "Lithuania" },
            { "value": "LV", "label": "Latvia" }
          ],
          "filterOptionValueKey": "value",
          "filterOptionLabelKey": "label"
        },
        {
          "key": "column7",
          "label": "Internal note",
          "type": "text",
          "showInTable": false,
          "showInDetails": true,
          "detailLabel": "Note (internal)"
        }
      ]
    },
    "el3": { "name": "el3", "label": "Segment", "type": "select", "options": [] }
  },
  "dataSources": [
    {
      "name": "ds1",
      "title": "Customers",
      "type": "rest",
      "params": { "url": "/api/customers", "method": "GET" }
    }
  ],
  "localization": { "defaultLanguage": "en", "languages": ["en"] }
}
```

Points that decide whether this works:

- **`columnsConfig[*].key`, never `name`.** A column with only `name` does not render.
- `type` for a column is one of `text` `date` `dateTime` `number` `element`. The renderer still understands the legacy `boolean` `html` `status` `toggleSwitch` `singleCheckbox` so old views keep working, but author new columns with `element` instead.
- `tableItemsPath` is only needed when the rows are not the response root and not under `items` / `data` / `results` / `rows`.
- `refreshPaths` on the element `dataSource` makes the table reload when another field changes.
- `showInTable: false` + `showInDetails: true` keeps a field out of the grid but available in the details panel.

### 6.1 Row, header and selection actions

```json
{
  "el2": {
    "name": "el2",
    "label": "All customers",
    "type": "table",
    "dataSource": { "name": "ds1", "useFor": "value" },
    "columnsConfig": [
      { "key": "column1", "label": "ID", "type": "number", "showInTable": true },
      { "key": "column2", "label": "Name", "type": "text", "showInTable": true }
    ],

    "enableSelection": true,
    "selectionKey": "column1",
    "selectLabel": "Select",
    "selectAllLabel": "Select all",
    "selectionActionsLabel": "With selected",
    "autoSelectCondition": "row.column3 == 'active'",
    "selectionActions": [
      {
        "label": "Archive selected",
        "type": "dataSource",
        "dataSourceName": "ds2",
        "buttonTone": "neutral",
        "confirmEnabled": true,
        "confirmTitle": "Archive",
        "confirmMessage": "Archive every selected record?",
        "reloadCurrentElementAfterSuccess": true
      }
    ],

    "headerActionsPosition": "end",
    "headerActionsDisplayMode": "buttons",
    "headerActions": [
      {
        "label": "New customer",
        "icon": "add",
        "type": "navigate",
        "navigateTo": "/customers/new",
        "buttonVariant": "filled",
        "buttonTone": "primary"
      },
      {
        "label": "Reload",
        "icon": "refresh",
        "type": "reloadElements",
        "reloadElementNames": ["el2"],
        "buttonVariant": "text"
      }
    ],

    "showActionsHeaderLabel": true,
    "actionsLabel": "Actions",
    "rowActionsDisplayMode": "dropdown",
    "rowActionsDropdownButtonStyle": "borderless",
    "rowActionVisibilityPath": "column4",
    "rowActions": [
      {
        "label": "Open",
        "icon": "open_in_new",
        "type": "navigate",
        "navigateTo": "/customers/{row.column1}"
      },
      {
        "label": "Deactivate",
        "icon": "block",
        "type": "dataSource",
        "dataSourceName": "ds3",
        "condition": "row.column3 == 'active'",
        "reloadCurrentElementAfterSuccess": true,
        "showToastAfter": true,
        "toastTitle": "Customer deactivated",
        "toastVariant": "success",
        "toastPosition": "bottom-right",
        "toastAutoHide": true,
        "toastAutoHideMs": 4000
      },
      {
        "label": "Delete",
        "icon": "delete",
        "type": "dataSource",
        "dataSourceName": "ds4",
        "buttonTone": "risk",
        "confirmEnabled": true,
        "confirmTitle": "Delete customer",
        "confirmMessage": "This cannot be undone. Continue?",
        "confirmConfirmLabel": "Delete",
        "confirmCancelLabel": "Cancel",
        "reloadCurrentElementAfterSuccess": true
      }
    ],

    "rowClickActions": [
      { "type": "navigate", "navigateTo": "/customers/{row.column1}" }
    ]
  },
  "dataSources": [
    { "name": "ds1", "title": "Customers", "type": "rest", "params": { "url": "/api/customers", "method": "GET" } },
    { "name": "ds2", "title": "Archive", "type": "rest", "params": { "url": "/api/customers/archive", "method": "POST", "body": { "ids": "{selectedKeys}" } } },
    { "name": "ds3", "title": "Deactivate", "type": "rest", "params": { "url": "/api/customers/{row.column1}", "method": "PUT", "body": { "active": false } } },
    { "name": "ds4", "title": "Delete", "type": "rest", "params": { "url": "/api/customers/{row.column1}", "method": "DELETE" } }
  ]
}
```

Context available to actions:

| Action kind | Sees |
| --- | --- |
| `rowActions[*]`, `rowClickActions[*]` | `{row.*}` for the clicked row |
| `selectionActions[*]` | `{selectedRows}`, `{selectedKeys}`, `{rows}`, `{items}` |
| `headerActions[*]` | the surrounding form context, no row |
| inline edit save | `{row.*}` plus `{changedValues}` (only the columns that changed) |

`rowActions[*].condition` is evaluated per row against `row.*`. `rowActionVisibilityPath` names a row field that hides the whole action column for rows where it is falsy.

### 6.2 Element columns, status badges and templates

A column of `type: "element"` renders a real builder element in every cell. `element` holds that element's own configuration, with the same property names it would have as a page element.

```json
{
  "el2": {
    "name": "el2",
    "label": "Orders",
    "type": "table",
    "dataSource": { "name": "ds1", "useFor": "value" },
    "columnsConfig": [
      {
        "key": "column1",
        "label": "Order",
        "type": "text",
        "showInTable": true,
        "template": "<b>#{row.column1}</b><br><small>{row.column2}</small>"
      },
      {
        "key": "column3",
        "label": "State",
        "type": "status",
        "statusShowIcon": true,
        "showInTable": true,
        "statusRules": [
          { "condition": "value == 'new'", "label": "New", "tone": "info", "icon": "fiber_new", "rounded": true },
          { "condition": "value == 'paid'", "label": "Paid", "tone": "success", "icon": "check_circle", "rounded": true },
          { "condition": "value == 'late'", "label": "Late", "tone": "risk", "icon": "error", "rounded": true }
        ]
      },
      {
        "key": "column4",
        "label": "Assignee",
        "type": "element",
        "elementType": "select",
        "showInTable": true,
        "controlEnabledIf": "row.column3 != 'paid'",
        "element": {
          "placeholder": "Unassigned",
          "strictOptions": true,
          "options": [
            { "value": "u1", "label": "Anna" },
            { "value": "u2", "label": "Ben" }
          ],
          "events": [
            {
              "trigger": "change",
              "type": "dataSource",
              "dataSourceName": "ds2",
              "params": [
                { "name": "id", "value": "{row.column1}" },
                { "name": "assignee", "value": "{value}" }
              ]
            }
          ]
        }
      },
      {
        "key": "column5",
        "label": "Progress",
        "type": "element",
        "elementType": "progressBar",
        "showInTable": true,
        "element": { "min": 0, "max": 100, "showValueLabel": true, "displayType": "bar" }
      },
      {
        "key": "column6",
        "label": "Description",
        "type": "element",
        "elementType": "richTextViewer",
        "showInTable": false,
        "showInDetails": true,
        "element": {}
      },
      {
        "key": "column7",
        "label": "",
        "type": "text",
        "showInTable": true,
        "cellActionsEnabled": true,
        "cellActionsDisplayMode": "iconButtons",
        "cellActions": [
          { "label": "Copy", "icon": "content_copy", "type": "setValue", "setValueTargetPath": "el3", "setValueMode": "template", "setValueValue": "{row.column2}" }
        ]
      }
    ]
  }
}
```

Rules for these:

- **`statusRules[*].condition` reads the cell value as `value`**, not as the column key. `status == 'paid'` never matches; `value == 'paid'` does. `row.otherColumn` also works.
- `statusRules[*].tone` is one of `neutral` `success` `warning` `risk` `primary` `danger` `info`.
- Inside `template` and inside a hosted `element`, the row is reachable as `{row.*}`, a bare sibling key, `{index}` and `{value}`.
- `visibleIf`, `controlEnabledIf` and `controlActiveIf` on a column are evaluated per row.
- Action `params` are always `[{ "name": ..., "value": ... }]`. An array of pairs is dropped silently.

### 6.3 Server-side paging: `lazyLoad` and `TABLE-POST`

With `lazyLoad: true` and the data source method set to the literal string `TABLE-POST`, the table merges paging, sorting and filter state into the request body for you.

```json
{
  "elements": {
    "el2": {
      "name": "el2",
      "label": "Customers",
      "type": "table",

      "lazyLoad": true,
      "dataSource": { "name": "ds1", "useFor": "value" },
      "tableItemsPath": "data.items",
      "tableTotalPath": "data.total",

      "params": [
        { "paramName": "tenantId", "paramValue": "{__variables.tenantId}" },
        { "paramName": "segment", "paramValue": "{el3}" }
      ],

      "pageSize": 50,
      "pageSizeOptions": "25,50,100",
      "orderClause": "column2 ASC",
      "showQuickSearch": true,
      "quickSearchParamName": "quickSearch",
      "quickSearchCondition": "%-%",
      "showDetailedSearch": true,
      "showExport": true,
      "exportAllPageSize": 10000,

      "virtualScroll": true,
      "virtualScrollRowHeight": 44,
      "virtualScrollViewportHeight": "600px",
      "virtualScrollBuffer": 10,

      "columnsConfig": [
        { "key": "column1", "label": "ID", "type": "number", "sortable": true, "showInTable": true },
        { "key": "column2", "label": "Name", "type": "text", "sortable": true, "showInTable": true, "filterControlType": "text" },
        { "key": "column3", "label": "Active", "type": "element", "elementType": "badge", "showInTable": true, "filterControlType": "boolean", "filterToggleTrueValue": "true", "filterToggleFalseValue": "false", "element": {} }
      ]
    }
  },
  "dataSources": [
    {
      "name": "ds1",
      "title": "Customers (paged)",
      "type": "rest",
      "params": { "url": "/api/customers/search", "method": "TABLE-POST" }
    }
  ]
}
```

The body your endpoint receives:

```json
{
  "pagingParams": {
    "cnt": null,
    "orderClause": "column2 ASC",
    "pageSize": 50,
    "skipRows": 100,
    "totalCountUsed": false
  },
  "params": [["tenantId", "42"], ["segment", "vip"]],
  "extendedParams": [
    { "paramName": "quickSearch", "paramValue": { "condition": "%-%", "value": "acme", "upperLower": "caseInsensitiveLatin" } },
    { "paramName": "column2", "paramValue": { "condition": "%-", "value": "Ac" } },
    { "paramName": "column3", "paramValue": { "condition": "=", "value": true } }
  ]
}
```

- On the wire `params` becomes `[name, value]` tuples, but **you author it as `[{ "paramName": ..., "paramValue": ... }]`** on the element. Up to five rows.
- `condition` vocabulary: `%-%` contains, `!%-%` does not contain, `%-` starts with, `-%` ends with, `=`, `!=`, `>`, `>=`, `<`, `<=`.
- Response: rows come from `tableItemsPath`, or `items` / `data` / `results` / `rows`. Total comes from `tableTotalPath`, or `total` / `totalCount` / `totalRecords` / `count` / `cnt` / `paging.*`. Without a recognizable total the pager looks stuck.
- Export "all" re-issues the same request with `pagingParams.pageSize` set to `exportAllPageSize`, then builds the file in the browser.

### 6.4 Inline edit, expandable rows, details panel, saved filters

```json
{
  "elements": {
    "el2": {
      "name": "el2",
      "label": "Orders",
      "type": "table",
      "dataSource": { "name": "ds1", "useFor": "value" },

      "enableInlineEdit": true,
      "inlineEditStartMode": "doubleClick",
      "inlineEditSaveDataSourceName": "ds2",
      "inlineEditCancelOnReload": true,

      "expandableRows": true,
      "expandedDisplayMode": "inline",
      "showExpandChevron": true,
      "alwaysShowExpandChevron": false,
      "expandLabel": "Show items",
      "collapseLabel": "Hide items",
      "expandedEmptyMessage": "This order has no lines",
      "expandedDataSourceName": "ds3",
      "expandedDataSourceItemsPath": "data.lines",
      "expandedColumnsConfig": [
        { "key": "column10", "label": "Product", "type": "text", "showInTable": true },
        { "key": "column11", "label": "Qty", "type": "number", "align": "right", "showInTable": true },
        { "key": "column12", "label": "Price", "type": "number", "align": "right", "numberMinFractionDigits": 2, "showInTable": true }
      ],
      "expandedRowActions": [
        { "label": "Remove line", "icon": "delete", "type": "dataSource", "dataSourceName": "ds4", "buttonTone": "risk" }
      ],

      "rowClickOpensDetails": true,
      "detailsPanelTitle": "Order details",

      "enableSavedFilters": true,
      "savedFiltersMode": "dataSource",
      "savedFiltersDataSourceName": "ds5",
      "savedFiltersItemsPath": "data.items",
      "saveFilterDataSourceName": "ds6",
      "deleteFilterDataSourceName": "ds7",
      "savedFilterIdKey": "id",
      "savedFilterNameKey": "name",
      "savedFilterCodeKey": "code",
      "savedFilterDescriptionKey": "description",
      "savedFilterPayloadKey": "payload",

      "columnsConfig": [
        { "key": "column1", "label": "Order", "type": "text", "showInTable": true },
        {
          "key": "column2",
          "label": "Status",
          "type": "text",
          "showInTable": true,
          "editable": true,
          "editorType": "select",
          "editorOptions": [
            { "value": "new", "label": "New" },
            { "value": "paid", "label": "Paid" }
          ],
          "editorOptionValueKey": "value",
          "editorOptionLabelKey": "label"
        },
        {
          "key": "column3",
          "label": "Note",
          "type": "text",
          "showInTable": true,
          "editable": true,
          "editorType": "textarea",
          "editorPlaceholder": "Internal note"
        }
      ]
    }
  }
}
```

The inline-edit save data source receives `{row.*}` (the whole edited row) **and** `{changedValues}`, a flat object holding only the columns that actually changed, which is what a PATCH endpoint wants.

### 6.5 The table's live state: `__table.*`

Every `table` continuously publishes its own state into the form data, so **any other element can read it without knowing how the table is fed**. This is the mechanism behind selection-driven toolbars, counters, master/detail screens and conditional buttons.

Two roots exist. `__table.<tableName>.*` is that specific table. Bare `__table.*` is the last table the user touched, useful when there is only one.

| Path | Holds |
| --- | --- |
| `__table.<name>.rows` | rows currently visible (the active page, after filtering) |
| `__table.<name>.allRows` | every loaded row |
| `__table.<name>.rowCount` | number of visible rows |
| `__table.<name>.totalRecords` | total according to the server (lazy) or the loaded set |
| `__table.<name>.page` | current page, 1-based |
| `__table.<name>.size` | current page size |
| `__table.<name>.sortField` | sorted column key, or `""` |
| `__table.<name>.sortDirection` | `asc` or `desc` |
| `__table.<name>.quickSearch` | current quick-search term |
| `__table.<name>.detailedFilters` | active per-column filters (lazy) |
| `__table.<name>.request` | the exact request payload last sent (lazy) |
| `__table.<name>.selectedRows` | array of checkbox-selected row objects |
| `__table.<name>.selectedKeys` | array of their `selectionKey` values |
| `__table.<name>.selectedItems` | the same selection rendered through `selectionItemTemplate` |
| `__table.<name>.selectedCount` | how many are selected |
| `__table.<name>.selectedRow` | the single row the user is working on: first selected, else expanded/active, else last clicked |
| `__table.<name>.selectedRowKey` | its key, or `null` |
| `__table.<name>.selectedRowIndex` | its index, or `-1` |
| `__table.<name>.activeRow` / `.activeRowKey` | the expanded / detail row |

These are read in braces like any other path: `{__table.el2.selectedCount}`.

### 6.6 Selection-driven toolbar

A counter, a bulk button that only enables with a selection, and a panel that mirrors the row being worked on. Nothing here is wired by hand; everything reads `__table.*`.

```json
{
  "schemaVersion": 1,
  "settings": { "language": "en", "locale": "en-US", "width": "1180px", "widthUnit": "px" },
  "pages": [
    {
      "name": "page1",
      "rows": [
        { "columns": [{ "elementRef": "el1" }, { "elementRef": "el2" }, { "elementRef": "el3" }] },
        { "columns": [{ "elementRef": "el4" }] },
        {
          "columns": [
            {
              "elementRef": "el5",
              "rows": [
                { "columns": [{ "elementRef": "el6" }, { "elementRef": "el7" }] }
              ]
            }
          ]
        }
      ]
    }
  ],
  "elements": {
    "page1": { "name": "page1", "label": "Orders", "type": "page", "hideHeader": true },

    "el1": {
      "name": "el1",
      "label": "",
      "type": "badge",
      "text": "Selected: {__table.el4.selectedCount}",
      "variant": "info",
      "pill": true,
      "visibleIf": "{__table.el4.selectedCount} > 0"
    },
    "el2": {
      "name": "el2",
      "label": "",
      "type": "button",
      "text": "Approve selected",
      "variant": "solid",
      "tone": "primary",
      "fitContent": true,
      "disableIf": "{__table.el4.selectedCount} == 0",
      "events": [
        {
          "trigger": "click",
          "type": "dataSource",
          "dataSourceName": "ds2",
          "confirmEnabled": true,
          "confirmTitle": "Approve",
          "confirmMessage": "Approve every selected order?",
          "reloadElementNames": ["el4"],
          "showToastAfter": true,
          "toastTitle": "Approved",
          "toastVariant": "success"
        }
      ]
    },
    "el3": {
      "name": "el3",
      "label": "",
      "type": "button",
      "text": "Clear search",
      "variant": "text",
      "tone": "neutral",
      "fitContent": true,
      "visibleIf": "notEmpty({__table.el4.quickSearch})",
      "events": [{ "trigger": "click", "type": "reloadElements", "reloadElementNames": ["el4"] }]
    },

    "el4": {
      "name": "el4",
      "label": "Orders",
      "type": "table",
      "dataSource": { "name": "ds1", "useFor": "value" },
      "enableSelection": true,
      "selectionKey": "column1",
      "selectionItemTemplate": "#{row.column1} ({row.column2})",
      "showQuickSearch": true,
      "pageSize": 25,
      "columnsConfig": [
        { "key": "column1", "label": "Order", "type": "text", "showInTable": true, "sortable": true },
        { "key": "column2", "label": "Customer", "type": "text", "showInTable": true },
        { "key": "column3", "label": "Total", "type": "number", "align": "right", "numberMinFractionDigits": 2, "showInTable": true, "sortable": true }
      ]
    },

    "el5": {
      "name": "el5",
      "label": "Current order",
      "type": "panel",
      "titleUnderline": true,
      "panelPadding": "0px",
      "showBorder": false,
      "visibleIf": "notEmpty({__table.el4.selectedRowKey})"
    },
    "el6": {
      "name": "el6",
      "label": "Order",
      "type": "text",
      "readOnly": true,
      "expression": "{__table.el4.selectedRow}.column1",
      "logicExecutionMode": "onChange"
    },
    "el7": {
      "name": "el7",
      "label": "Customer",
      "type": "text",
      "readOnly": true,
      "expression": "{__table.el4.selectedRow}.column2",
      "logicExecutionMode": "onChange"
    }
  },
  "dataSources": [
    { "name": "ds1", "title": "Orders", "type": "rest", "params": { "url": "/api/orders", "method": "GET" } },
    {
      "name": "ds2",
      "title": "Approve selected",
      "type": "rest",
      "params": {
        "url": "/api/orders/approve",
        "method": "POST",
        "body": { "ids": "{__table.el4.selectedKeys}" }
      }
    }
  ],
  "localization": { "defaultLanguage": "en", "languages": ["en"] }
}
```

`selectionKey` names the row field used as the identity of a selection; it defaults to `id`. `selectionItemTemplate` shapes each entry of `selectedItems`, which is what you send when the endpoint wants labels rather than raw rows.

### 6.7 Master and detail: one table drives another

The detail table reloads whenever the master's selected row changes, because its data source declares that dependency in `refreshPaths`.

```json
{
  "pages": [
    {
      "name": "page1",
      "rows": [
        { "columns": [{ "elementRef": "el1" }] },
        { "columns": [{ "elementRef": "el2" }] }
      ]
    }
  ],
  "elements": {
    "page1": { "name": "page1", "label": "Orders", "type": "page" },
    "el1": {
      "name": "el1",
      "label": "Orders",
      "type": "table",
      "dataSource": { "name": "ds1", "useFor": "value" },
      "rowHover": true,
      "columnsConfig": [
        { "key": "column1", "label": "Order", "type": "text", "showInTable": true },
        { "key": "column2", "label": "Customer", "type": "text", "showInTable": true }
      ]
    },
    "el2": {
      "name": "el2",
      "label": "Lines of the selected order",
      "type": "table",
      "emptyMessage": "Pick an order above",
      "visibleIf": "notEmpty({__table.el1.selectedRowKey})",
      "dataSource": {
        "name": "ds2",
        "useFor": "value",
        "params": [{ "name": "orderId", "value": "{__table.el1.selectedRowKey}" }],
        "refreshOnChange": true,
        "refreshPaths": ["__table.el1.selectedRowKey"]
      },
      "columnsConfig": [
        { "key": "column10", "label": "Product", "type": "text", "showInTable": true },
        { "key": "column11", "label": "Qty", "type": "number", "align": "right", "showInTable": true }
      ]
    }
  },
  "dataSources": [
    { "name": "ds1", "title": "Orders", "type": "rest", "params": { "url": "/api/orders", "method": "GET" } },
    { "name": "ds2", "title": "Order lines", "type": "rest", "params": { "url": "/api/orders/{orderId}/lines", "method": "GET" } }
  ]
}
```

Clicking a row is enough: `selectedRow` falls back to the last clicked row when there is no selection column.

### 6.8 A filter toolbar above the table

Real fields drive the request. `params` decides what is sent, and each field change re-issues it.

```json
{
  "pages": [
    {
      "name": "page1",
      "rows": [
        {
          "columns": [
            {
              "elementRef": "el1",
              "rows": [
                {
                  "columns": [
                    { "elementRef": "el2" },
                    { "elementRef": "el3" },
                    { "elementRef": "el4" }
                  ]
                }
              ]
            }
          ]
        },
        { "columns": [{ "elementRef": "el5" }] }
      ]
    }
  ],
  "elements": {
    "page1": { "name": "page1", "label": "Reports", "type": "page" },
    "el1": {
      "name": "el1",
      "label": "Filters",
      "type": "panel",
      "showBorder": true,
      "panelRadius": "8px",
      "panelPadding": "12px",
      "contentGap": "12px"
    },
    "el2": {
      "name": "el2",
      "label": "Status",
      "type": "select",
      "strictOptions": true,
      "defaultValue": "",
      "options": [
        { "value": "", "label": "All" },
        { "value": "open", "label": "Open" },
        { "value": "closed", "label": "Closed" }
      ]
    },
    "el3": { "name": "el3", "label": "Period", "type": "dateRange", "format": "YYYY-MM-DD" },
    "el4": { "name": "el4", "label": "Owner", "type": "text" },
    "el5": {
      "name": "el5",
      "label": "Results",
      "type": "table",
      "lazyLoad": true,
      "dataSource": { "name": "ds1", "useFor": "value" },
      "tableItemsPath": "data.items",
      "tableTotalPath": "data.total",
      "params": [
        { "paramName": "status", "paramValue": "{el2}" },
        { "paramName": "from", "paramValue": "{el3.dateFrom}" },
        { "paramName": "to", "paramValue": "{el3.dateTo}" },
        { "paramName": "owner", "paramValue": "{el4}" }
      ],
      "showQuickSearch": true,
      "pageSize": 50,
      "columnsConfig": [
        { "key": "column1", "label": "Ref", "type": "text", "showInTable": true, "sortable": true },
        { "key": "column2", "label": "Opened", "type": "date", "showInTable": true, "sortable": true },
        { "key": "column3", "label": "Owner", "type": "text", "showInTable": true }
      ]
    }
  },
  "dataSources": [
    { "name": "ds1", "title": "Report search", "type": "rest", "params": { "url": "/api/reports/search", "method": "TABLE-POST" } }
  ]
}
```

A `dateRange` value is an object, so its parts are `{el3.dateFrom}` and `{el3.dateTo}`.

### 6.9 Column filter options loaded from a data source

Per-column filters do not have to be hardcoded. A column can pull its own option list.

```json
{
  "elements": {
    "el1": {
      "name": "el1",
      "label": "Tickets",
      "type": "table",
      "dataSource": { "name": "ds1", "useFor": "value" },
      "showDetailedSearch": true,
      "columnsConfig": [
        { "key": "column1", "label": "Ref", "type": "text", "showInTable": true },
        {
          "key": "column2",
          "label": "Assignee",
          "type": "text",
          "showInTable": true,
          "filterControlType": "multiSelect",
          "filterOptionsSourceType": "datasource",
          "filterOptionsDataSourceName": "ds2",
          "filterOptionsDataSourceItemsPath": "data.items",
          "filterOptionValueKey": "id",
          "filterOptionLabelKey": "name",
          "filterMultiValueDelimiter": ","
        },
        {
          "key": "column3",
          "label": "Archived",
          "type": "text",
          "showInTable": true,
          "filterControlType": "toggle",
          "filterToggleTrueValue": "true",
          "filterToggleFalseValue": "false"
        },
        {
          "key": "column4",
          "label": "Priority",
          "type": "text",
          "showInTable": true,
          "filterControlType": "select",
          "filterOptionsSourceType": "static",
          "filterOptionValueKey": "value",
          "filterOptionLabelKey": "label",
          "filterOptions": [
            { "value": "low", "label": "Low" },
            { "value": "high", "label": "High" }
          ]
        }
      ]
    }
  },
  "dataSources": [
    { "name": "ds1", "title": "Tickets", "type": "rest", "params": { "url": "/api/tickets", "method": "GET" } },
    { "name": "ds2", "title": "Users", "type": "rest", "params": { "url": "/api/users", "method": "GET" } }
  ]
}
```

### 6.10 Header dropdown

Beside the header buttons a table can host one dropdown, either with static options or fed by a data source, whose selection runs actions.

```json
{
  "elements": {
    "el1": {
      "name": "el1",
      "label": "Tickets",
      "type": "table",
      "dataSource": { "name": "ds1", "useFor": "value" },
      "showHeaderControls": true,
      "headerActionsPosition": "end",
      "headerMenuEnabled": true,
      "headerMenuPlaceholder": "Switch queue",
      "headerMenuDataSourceName": "ds2",
      "headerMenuItemsPath": "data.items",
      "headerMenuLabelKey": "name",
      "headerMenuValueKey": "id",
      "headerMenuActions": [
        { "trigger": "change", "type": "reloadElements", "reloadElementNames": ["el1"] }
      ],
      "columnsConfig": [
        { "key": "column1", "label": "Ref", "type": "text", "showInTable": true }
      ]
    }
  },
  "dataSources": [
    { "name": "ds1", "title": "Tickets", "type": "rest", "params": { "url": "/api/tickets", "method": "GET" } },
    { "name": "ds2", "title": "Queues", "type": "rest", "params": { "url": "/api/queues", "method": "GET" } }
  ]
}
```

For static options instead of a source, drop `headerMenuDataSourceName` / `headerMenuItemsPath` / `headerMenuLabelKey` / `headerMenuValueKey` and set `headerMenuOptions: [{ "value": "a", "label": "A" }]`.

### 6.11 Templates and mobile behaviour

`headerTemplate` fills the centre of the header, `rowTemplate` replaces the whole row, `expandedTemplate` renders the expanded area. Row-level templates see `{row.*}`; all of them can read `{__table.<name>.*}`.

```json
{
  "elements": {
    "el1": {
      "name": "el1",
      "label": "Tickets",
      "type": "table",
      "dataSource": { "name": "ds1", "useFor": "value" },

      "headerTemplate": "<span class=\"muted\">Showing {__table.el1.rowCount} of {__table.el1.totalRecords}</span>",
      "headerCenterElementsPosition": "center",

      "responsiveMode": "stack",
      "stickyHeader": true,
      "tableStyle": "grid",

      "expandableRows": true,
      "expandedDisplayMode": "inline",
      "expandedTemplate": "<div class=\"detail\"><b>{row.column2}</b><p>{row.column3}</p></div>",

      "columnsConfig": [
        {
          "key": "column1",
          "label": "Ticket",
          "type": "text",
          "showInTable": true,
          "mobileLabel": "Ref",
          "template": "<b>#{row.column1}</b>"
        },
        { "key": "column2", "label": "Subject", "type": "text", "showInTable": true },
        { "key": "column3", "label": "Body", "type": "text", "showInTable": false, "showInDetails": true }
      ]
    }
  },
  "dataSources": [
    { "name": "ds1", "title": "Tickets", "type": "rest", "params": { "url": "/api/tickets", "method": "GET" } }
  ]
}
```

`responsiveMode: "stack"` turns each row into a stacked card on narrow screens, where `mobileLabel` becomes the visible field label.

### 6.12 Column settings stored on the server

`columnSettingsMode: "localStorage"` needs only `columnSettingsStorageKey`. Per-user layouts kept server-side use the data-source mode instead.

```json
{
  "elements": {
    "el1": {
      "name": "el1",
      "label": "Tickets",
      "type": "table",
      "dataSource": { "name": "ds1", "useFor": "value" },
      "showColumnSettings": true,
      "columnSettingsDialogTitle": "Columns",
      "columnSettingsMode": "dataSource",
      "columnSettingsDataSourceName": "ds2",
      "columnSettingsDataSourcePath": "data.layout",
      "saveColumnSettingsDataSourceName": "ds3",
      "resetColumnSettingsDataSourceName": "ds4",
      "columnsConfig": [
        { "key": "column1", "label": "Ref", "type": "text", "showInTable": true },
        { "key": "column2", "label": "Subject", "type": "text", "showInTable": true },
        { "key": "column3", "label": "Owner", "type": "text", "showInTable": false }
      ]
    }
  },
  "dataSources": [
    { "name": "ds1", "title": "Tickets", "type": "rest", "params": { "url": "/api/tickets", "method": "GET" } },
    { "name": "ds2", "title": "Load layout", "type": "rest", "params": { "url": "/api/me/table-layout", "method": "GET" } },
    { "name": "ds3", "title": "Save layout", "type": "rest", "params": { "url": "/api/me/table-layout", "method": "PUT" } },
    { "name": "ds4", "title": "Reset layout", "type": "rest", "params": { "url": "/api/me/table-layout", "method": "DELETE" } }
  ]
}
```

### 6.13 Full CRUD loop: table, dialog editor, reload

The pattern most admin screens need, end to end.

```json
{
  "schemaVersion": 1,
  "settings": { "language": "en", "locale": "en-US", "width": "1180px", "widthUnit": "px" },
  "pages": [
    {
      "name": "page1",
      "rows": [
        { "columns": [{ "elementRef": "el1" }] },
        { "columns": [{ "elementRef": "el2" }] },
        {
          "columns": [
            {
              "elementRef": "el3",
              "rows": [
                { "columns": [{ "elementRef": "el4" }, { "elementRef": "el5" }] },
                { "columns": [{ "elementRef": "el6" }] },
                {
                  "columns": [
                    {
                      "elementRef": "el7",
                      "rows": [
                        { "columns": [{ "elementRef": "el8" }, { "elementRef": "el9" }] }
                      ]
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  ],
  "elements": {
    "page1": { "name": "page1", "label": "Customers", "type": "page", "hideHeader": true },

    "el1": {
      "name": "el1",
      "label": "",
      "type": "button",
      "text": "New customer",
      "icon": "add",
      "variant": "solid",
      "tone": "primary",
      "fitContent": true,
      "events": [
        { "trigger": "click", "type": "setValue", "setValueTargetPath": "el4", "setValueMode": "template", "setValueValue": "" },
        { "trigger": "click", "type": "setValue", "setValueTargetPath": "el5", "setValueMode": "template", "setValueValue": "" },
        { "trigger": "click", "type": "setValue", "setValueTargetPath": "el6", "setValueMode": "template", "setValueValue": "" },
        { "trigger": "click", "type": "dialog", "dialogName": "el3", "dialogOperation": "open" }
      ]
    },

    "el2": {
      "name": "el2",
      "label": "Customers",
      "type": "table",
      "dataSource": { "name": "ds1", "useFor": "value" },
      "selectionKey": "column1",
      "pageSize": 25,
      "showQuickSearch": true,
      "rowActionsDisplayMode": "iconButtons",
      "columnsConfig": [
        { "key": "column1", "label": "ID", "type": "number", "showInTable": true, "width": "80px" },
        { "key": "column2", "label": "Name", "type": "text", "showInTable": true, "sortable": true },
        { "key": "column3", "label": "Email", "type": "text", "showInTable": true }
      ],
      "rowActions": [
        {
          "label": "Edit",
          "icon": "edit",
          "type": "setValue",
          "setValueTargetPath": "el4",
          "setValueMode": "template",
          "setValueValue": "{row.column1}"
        },
        {
          "label": "Edit",
          "icon": "edit",
          "hideText": true,
          "type": "setValue",
          "setValueTargetPath": "el5",
          "setValueMode": "template",
          "setValueValue": "{row.column2}"
        },
        {
          "label": "Edit",
          "icon": "edit",
          "hideText": true,
          "type": "setValue",
          "setValueTargetPath": "el6",
          "setValueMode": "template",
          "setValueValue": "{row.column3}"
        },
        {
          "label": "Edit",
          "icon": "edit",
          "hideText": true,
          "type": "dialog",
          "dialogName": "el3",
          "dialogOperation": "open"
        },
        {
          "label": "Delete",
          "icon": "delete",
          "type": "dataSource",
          "dataSourceName": "ds3",
          "buttonTone": "risk",
          "confirmEnabled": true,
          "confirmTitle": "Delete customer",
          "confirmMessage": "This cannot be undone.",
          "reloadCurrentElementAfterSuccess": true
        }
      ]
    },

    "el3": {
      "name": "el3",
      "label": "Customer",
      "type": "dialog",
      "showTriggerButton": false,
      "showCloseButton": true,
      "dialogWidth": "520px"
    },
    "el4": { "name": "el4", "label": "ID", "type": "text", "readOnly": true },
    "el5": { "name": "el5", "label": "Name", "type": "text", "required": true },
    "el6": { "name": "el6", "label": "Email", "type": "text", "inputMode": "email", "required": true },

    "el7": {
      "name": "el7",
      "label": "",
      "type": "panel",
      "showBorder": false,
      "panelPadding": "0px",
      "contentJustify": "flex-end",
      "contentGap": "8px"
    },
    "el8": {
      "name": "el8",
      "label": "",
      "type": "button",
      "text": "Cancel",
      "variant": "outline",
      "tone": "neutral",
      "fitContent": true,
      "events": [{ "trigger": "click", "type": "dialog", "dialogName": "el3", "dialogOperation": "close" }]
    },
    "el9": {
      "name": "el9",
      "label": "",
      "type": "button",
      "text": "Save",
      "variant": "solid",
      "tone": "primary",
      "fitContent": true,
      "events": [
        {
          "trigger": "click",
          "type": "dataSource",
          "dataSourceName": "ds2",
          "validateForm": true,
          "reloadElementNames": ["el2"],
          "showToastAfter": true,
          "toastTitle": "Saved",
          "toastVariant": "success"
        },
        { "trigger": "click", "type": "dialog", "dialogName": "el3", "dialogOperation": "close" }
      ]
    }
  },
  "dataSources": [
    { "name": "ds1", "title": "Customers", "type": "rest", "params": { "url": "/api/customers", "method": "GET" } },
    {
      "name": "ds2",
      "title": "Save customer",
      "type": "rest",
      "params": {
        "url": "/api/customers/{el4}",
        "method": "PUT",
        "body": { "name": "{el5}", "email": "{el6}" }
      }
    },
    { "name": "ds3", "title": "Delete customer", "type": "rest", "params": { "url": "/api/customers/{row.column1}", "method": "DELETE" } }
  ],
  "localization": { "defaultLanguage": "en", "languages": ["en"] }
}
```

One action carries one `type`, so filling three fields and opening the dialog is four actions on the same row-action button. They run in order, and only the first needs a visible label; give the rest `hideText: true` so the toolbar stays clean.

### 6.14 Dashboard: one table feeding KPI cards and a chart

The table is the single source of data; the cards and the chart read its published state. No second request is issued: a `local` source in `dataPath` mode simply points at `__table.el3.allRows`.

```json
{
  "schemaVersion": 1,
  "settings": { "language": "en", "locale": "en-US", "width": "1180px", "widthUnit": "px" },
  "pages": [
    {
      "name": "page1",
      "rows": [
        {
          "columns": [
            { "elementRef": "el1" },
            { "elementRef": "el2" }
          ]
        },
        { "columns": [{ "elementRef": "el5" }] },
        { "columns": [{ "elementRef": "el4" }] },
        { "columns": [{ "elementRef": "el3" }] }
      ]
    }
  ],
  "elements": {
    "page1": { "name": "page1", "label": "Sales", "type": "page", "hideHeader": true },

    "el1": {
      "name": "el1",
      "label": "",
      "type": "statsCard",
      "title": "Orders",
      "valueText": "{__table.el3.totalRecords}",
      "variant": "info",
      "icon": "receipt_long"
    },
    "el2": {
      "name": "el2",
      "label": "",
      "type": "statsCard",
      "title": "Revenue",
      "valueText": "{el5}",
      "variant": "success",
      "icon": "payments"
    },

    "el4": {
      "name": "el4",
      "label": "Revenue by month",
      "type": "chart",
      "chartType": "bar",
      "chartHeight": "260px",
      "showLegend": false,
      "labelKey": "column2",
      "valueKey": "column3",
      "dataSource": {
        "name": "ds2",
        "useFor": "value",
        "refreshOnChange": true,
        "refreshPaths": ["__table.el3.allRows"]
      }
    },

    "el3": {
      "name": "el3",
      "label": "Orders",
      "type": "table",
      "dataSource": { "name": "ds1", "useFor": "value" },
      "pageSize": 25,
      "showQuickSearch": true,
      "columnsConfig": [
        { "key": "column1", "label": "Order", "type": "text", "showInTable": true },
        { "key": "column2", "label": "Month", "type": "text", "showInTable": true },
        { "key": "column3", "label": "Total", "type": "number", "align": "right", "numberMinFractionDigits": 2, "showInTable": true }
      ]
    },

    "el5": {
      "name": "el5",
      "label": "Revenue",
      "type": "number",
      "hidden": true,
      "readOnly": true,
      "expression": "sumArray({__table.el3.allRows}, column3)",
      "logicExecutionMode": "onChange"
    }
  },
  "dataSources": [
    { "name": "ds1", "title": "Orders", "type": "rest", "params": { "url": "/api/orders", "method": "GET" } },
    {
      "name": "ds2",
      "title": "Orders already loaded by the table",
      "type": "local",
      "params": { "localMode": "dataPath", "dataPath": "__table.el3.allRows" }
    }
  ],
  "localization": { "defaultLanguage": "en", "languages": ["en"] }
}
```

`statsCard.title`, `valueText` and `trendText`, and `badge.text`, all interpolate `{...}` tokens, so a card can display live table state directly. A hidden `number` element is the usual place to park an aggregate that several other elements want to reuse.

**`hidden: true` still needs a place in the layout tree.** `hidden` only suppresses the rendering; an element that is absent from `pages` is never instantiated at all, so its `expression` never runs and everything reading it stays empty. Give the helper element its own row and hide it there.

### 6.15 Aggregates under a table

`allRows` is the whole loaded set, `rows` is only what the current page shows after filtering. Pick deliberately: a "total" that changes when the user pages is almost always a bug.

```json
{
  "elements": {
    "el1": {
      "name": "el1",
      "label": "Invoices",
      "type": "table",
      "dataSource": { "name": "ds1", "useFor": "value" },
      "columnsConfig": [
        { "key": "column1", "label": "Invoice", "type": "text", "showInTable": true },
        { "key": "column2", "label": "Status", "type": "text", "showInTable": true },
        { "key": "column3", "label": "Amount", "type": "number", "align": "right", "showInTable": true }
      ]
    },
    "el2": {
      "name": "el2",
      "label": "Rows loaded",
      "type": "number",
      "readOnly": true,
      "expression": "len({__table.el1.allRows})",
      "logicExecutionMode": "onChange"
    },
    "el3": {
      "name": "el3",
      "label": "Total amount",
      "type": "number",
      "readOnly": true,
      "expression": "sumArray({__table.el1.allRows}, column3)",
      "logicExecutionMode": "onChange"
    },
    "el4": {
      "name": "el4",
      "label": "Average amount",
      "type": "number",
      "readOnly": true,
      "expression": "avgArray({__table.el1.allRows}, column3)",
      "logicExecutionMode": "onChange"
    },
    "el5": {
      "name": "el5",
      "label": "Unpaid",
      "type": "number",
      "readOnly": true,
      "expression": "countInArray({__table.el1.allRows}, column2 == \"unpaid\")",
      "logicExecutionMode": "onChange"
    },
    "el6": {
      "name": "el6",
      "label": "Unpaid total",
      "type": "number",
      "readOnly": true,
      "expression": "sumArray(filterArray({__table.el1.allRows}, column2 == \"unpaid\"), column3)",
      "logicExecutionMode": "onChange"
    },
    "el7": {
      "name": "el7",
      "label": "Largest invoice",
      "type": "text",
      "readOnly": true,
      "expression": "getFirst(filterArray({__table.el1.allRows}, column3 > 1000), column1)",
      "logicExecutionMode": "onChange"
    }
  },
  "dataSources": [
    { "name": "ds1", "title": "Invoices", "type": "rest", "params": { "url": "/api/invoices", "method": "GET" } }
  ]
}
```

Inside a collection function the row fields are written **bare and unquoted** (`column2 == "unpaid"`); everything outside the collection keeps its braces.

### 6.16 Details side panel instead of an inline expand

The same expand machinery renders in a drawer when `expandedDisplayMode` is `sidePanel`. `rowClickOpensDetails` means the whole row opens it, so no chevron column is needed.

```json
{
  "elements": {
    "el1": {
      "name": "el1",
      "label": "Applications",
      "type": "table",
      "dataSource": { "name": "ds1", "useFor": "value" },

      "expandableRows": true,
      "expandedDisplayMode": "sidePanel",
      "detailsPanelTitle": "Application details",
      "rowClickOpensDetails": true,
      "showExpandChevron": false,
      "rowHover": true,

      "rowExpandActions": [
        {
          "type": "dataSource",
          "dataSourceName": "ds2",
          "params": [{ "name": "id", "value": "{row.column1}" }]
        }
      ],

      "columnsConfig": [
        { "key": "column1", "label": "Ref", "type": "text", "showInTable": true },
        { "key": "column2", "label": "Applicant", "type": "text", "showInTable": true },
        { "key": "column3", "label": "Submitted", "type": "date", "showInTable": true },
        { "key": "column4", "label": "Motivation", "type": "text", "showInTable": false, "showInDetails": true, "detailLabel": "Why they applied" },
        { "key": "column5", "label": "Reviewer notes", "type": "text", "showInTable": false, "showInDetails": true }
      ]
    }
  },
  "dataSources": [
    { "name": "ds1", "title": "Applications", "type": "rest", "params": { "url": "/api/applications", "method": "GET" } },
    { "name": "ds2", "title": "Mark as viewed", "type": "rest", "params": { "url": "/api/applications/{id}/viewed", "method": "POST" } }
  ]
}
```

`rowExpandActions` fire when a row is expanded, which is where "mark as read" or "load the heavy part now" belongs. Columns with `showInTable: false` and `showInDetails: true` are exactly what fills the panel.

### 6.17 Row action that downloads a file

`responseMode: "download"` turns the response into a file instead of data.

```json
{
  "elements": {
    "el1": {
      "name": "el1",
      "label": "Invoices",
      "type": "table",
      "dataSource": { "name": "ds1", "useFor": "value" },
      "rowActionsDisplayMode": "iconButtons",
      "columnsConfig": [
        { "key": "column1", "label": "Invoice", "type": "text", "showInTable": true },
        { "key": "column2", "label": "Issued", "type": "date", "showInTable": true }
      ],
      "rowActions": [
        {
          "label": "Download PDF",
          "icon": "download",
          "type": "dataSource",
          "dataSourceName": "ds2",
          "responseMode": "download",
          "responseFileName": "invoice-{row.column1}.pdf"
        },
        {
          "label": "Email a copy",
          "icon": "mail",
          "type": "dataSource",
          "dataSourceName": "ds3",
          "condition": "notEmpty({row.column3})",
          "showToastAfter": true,
          "toastTitle": "Sent",
          "toastVariant": "success"
        }
      ]
    }
  },
  "dataSources": [
    { "name": "ds1", "title": "Invoices", "type": "rest", "params": { "url": "/api/invoices", "method": "GET" } },
    { "name": "ds2", "title": "Invoice PDF", "type": "rest", "params": { "url": "/api/invoices/{row.column1}/pdf", "method": "GET" } },
    { "name": "ds3", "title": "Email invoice", "type": "rest", "params": { "url": "/api/invoices/{row.column1}/email", "method": "POST" } }
  ]
}
```

CSV/Excel/PDF export of the grid itself is different: it is `showExport` and happens entirely in the browser, with no endpoint to implement.

### 6.18 Export configuration

```json
{
  "elements": {
    "el1": {
      "name": "el1",
      "label": "Customers",
      "type": "table",
      "lazyLoad": true,
      "dataSource": { "name": "ds1", "useFor": "value" },
      "tableItemsPath": "data.items",
      "tableTotalPath": "data.total",
      "pageSize": 50,

      "showExport": true,
      "exportFileName": "customers-2026",
      "exportUseColumnPicker": true,
      "exportAllPageSize": 20000,

      "columnsConfig": [
        { "key": "column1", "label": "ID", "type": "number", "showInTable": true },
        { "key": "column2", "label": "Name", "type": "text", "showInTable": true },
        { "key": "column3", "label": "Created", "type": "dateTime", "dateFormatPattern": "yyyy-MM-dd", "showInTable": true },
        { "key": "column4", "label": "Internal score", "type": "number", "showInTable": false, "showInDetails": true }
      ]
    }
  },
  "dataSources": [
    { "name": "ds1", "title": "Customers", "type": "rest", "params": { "url": "/api/customers/search", "method": "TABLE-POST" } }
  ]
}
```

With `exportUseColumnPicker` the user chooses which columns land in the file. "Export all" re-issues the same table request with `pagingParams.pageSize` set to `exportAllPageSize`, so that number is a real memory decision, not decoration.

### 6.19 A live table over a websocket

```json
{
  "elements": {
    "el1": {
      "name": "el1",
      "label": "Live events",
      "type": "table",
      "dataSource": { "name": "ds1", "useFor": "value" },
      "pageSize": 50,
      "stickyHeader": true,
      "virtualScroll": true,
      "virtualScrollRowHeight": 40,
      "virtualScrollViewportHeight": "520px",
      "orderClause": "column1 DESC",
      "columnsConfig": [
        { "key": "column1", "label": "Time", "type": "dateTime", "dateIncludeSeconds": true, "showInTable": true, "sortable": true },
        {
          "key": "column2",
          "label": "Level",
          "type": "status",
          "showInTable": true,
          "statusShowIcon": true,
          "statusRules": [
            { "condition": "value == 'error'", "label": "Error", "tone": "risk", "icon": "error", "rounded": true },
            { "condition": "value == 'warn'", "label": "Warning", "tone": "warning", "icon": "warning", "rounded": true },
            { "condition": "value == 'info'", "label": "Info", "tone": "info", "rounded": true }
          ]
        },
        { "key": "column3", "label": "Message", "type": "text", "showInTable": true }
      ]
    }
  },
  "dataSources": [
    {
      "name": "ds1",
      "title": "Event stream",
      "type": "websocket",
      "params": {
        "url": "wss://example.test/events",
        "protocols": "",
        "message": "{\"subscribe\":\"events\"}",
        "messagePath": "payload",
        "messageMode": "pushValuesInArray"
      }
    }
  ]
}
```

`messageMode: "pushValuesInArray"` appends each message to the accumulated array, which is what a log-style table wants; `replaceCurrent` swaps the whole set instead. The buffer is capped at 500 entries, so a view left open overnight cannot grow without end. `virtualScroll` keeps a long list cheap to render.

### 6.20 Tables nested in containers

A table is a leaf element, so it sits in a column like any other. Inside `tabs` that column lives in `tabRows`; inside a `dynamicPanel` each entry renders its own copy of the table.

```json
{
  "schemaVersion": 1,
  "settings": { "language": "en", "locale": "en-US", "width": "1100px", "widthUnit": "px" },
  "pages": [
    {
      "name": "page1",
      "rows": [
        {
          "columns": [
            {
              "elementRef": "el1",
              "tabRows": {
                "active": [{ "columns": [{ "elementRef": "el2" }] }],
                "archived": [{ "columns": [{ "elementRef": "el3" }] }]
              }
            }
          ]
        },
        {
          "columns": [
            {
              "elementRef": "el4",
              "rows": [
                { "columns": [{ "elementRef": "el5" }] },
                { "columns": [{ "elementRef": "el6" }] }
              ]
            }
          ]
        }
      ]
    }
  ],
  "elements": {
    "page1": { "name": "page1", "label": "Projects", "type": "page", "hideHeader": true },

    "el1": {
      "name": "el1",
      "label": "Projects",
      "type": "tabs",
      "tabsPosition": "top",
      "tabs": [
        { "value": "active", "label": "Active" },
        { "value": "archived", "label": "Archived" }
      ]
    },
    "el2": {
      "name": "el2",
      "label": "Active projects",
      "type": "table",
      "dataSource": { "name": "ds1", "useFor": "value" },
      "columnsConfig": [
        { "key": "column1", "label": "Project", "type": "text", "showInTable": true },
        { "key": "column2", "label": "Owner", "type": "text", "showInTable": true }
      ]
    },
    "el3": {
      "name": "el3",
      "label": "Archived projects",
      "type": "table",
      "dataSource": { "name": "ds2", "useFor": "value" },
      "columnsConfig": [
        { "key": "column1", "label": "Project", "type": "text", "showInTable": true },
        { "key": "column3", "label": "Archived", "type": "date", "showInTable": true }
      ]
    },

    "el4": {
      "name": "el4",
      "label": "Teams",
      "type": "dynamicPanel",
      "addRowButtonText": "Add team",
      "panelPadding": "16px",
      "panelBorderWidth": "1px",
      "panelRadius": "8px"
    },
    "el5": { "name": "el5", "label": "Team name", "type": "text", "required": true },
    "el6": {
      "name": "el6",
      "label": "Members",
      "type": "dynamicTable",
      "addRowButtonText": "Add member",
      "columns": [
        { "name": "column1", "label": "Name", "type": "text" },
        { "name": "column2", "label": "Role", "type": "select", "options": [
          { "value": "dev", "label": "Developer" },
          { "value": "qa", "label": "QA" }
        ] }
      ]
    }
  },
  "dataSources": [
    { "name": "ds1", "title": "Active", "type": "rest", "params": { "url": "/api/projects?state=active", "method": "GET" } },
    { "name": "ds2", "title": "Archived", "type": "rest", "params": { "url": "/api/projects?state=archived", "method": "GET" } }
  ],
  "localization": { "defaultLanguage": "en", "languages": ["en"] }
}
```

Note which repeating element goes where: a **grid of editable cells** inside a repeating block is `dynamicTable`; a **read-only view of server data** would be `table`. A `table` inside a `dynamicPanel` publishes its state under one shared `__table.<name>` key, so prefer `dynamicTable` when each entry needs its own independent state.

### 6.21 A localized table

Column labels, action labels and messages all go through `localization.texts` when a `translate()` call or a translated key is used. The simplest route is to author the labels in the default language and let the host supply the rest.

```json
{
  "schemaVersion": 1,
  "settings": { "language": "en", "locale": "en-US", "width": "1100px", "widthUnit": "px" },
  "pages": [{ "name": "page1", "rows": [{ "columns": [{ "elementRef": "el1" }] }] }],
  "elements": {
    "page1": { "name": "page1", "label": "Orders", "type": "page", "hideHeader": true },
    "el1": {
      "name": "el1",
      "label": "Orders",
      "type": "table",
      "dataSource": { "name": "ds1", "useFor": "value" },
      "emptyMessage": "No records found",
      "loadingLabel": "Kraunama...",
      "quickSearchPlaceholder": "Search",
      "actionsLabel": "Veiksmai",
      "showQuickSearch": true,
      "columnsConfig": [
        { "key": "column1", "label": "Numeris", "type": "text", "showInTable": true },
        {
          "key": "column2",
          "label": "Suma",
          "type": "number",
          "align": "right",
          "formatLocale": "lt-LT",
          "numberMinFractionDigits": 2,
          "numberUseGrouping": true,
          "showInTable": true
        },
        {
          "key": "column3",
          "label": "Status",
          "type": "element",
          "elementType": "customHtml",
          "showInTable": true,
          "element": { "htmlTemplate": "<span>{translate({row.column3})}</span>" }
        }
      ]
    }
  },
  "dataSources": [
    { "name": "ds1", "title": "Orders", "type": "rest", "params": { "url": "/api/orders", "method": "GET" } }
  ],
  "localization": {
    "defaultLanguage": "en",
    "languages": ["en", "de"],
    "texts": {
      "de": { "new": "Neu", "paid": "Bezahlt", "late": "Überfällig" },
      "en": { "new": "New", "paid": "Paid", "late": "Late" }
    }
  }
}
```

`translate(value)` looks the raw value up in `localization.texts[<current language>]`, which is how a raw server code such as `paid` becomes a readable label without a lookup table in the view.

### 6.22 Choosing the right table

| The screen needs | Use |
| --- | --- |
| Users type into every row, add and delete rows | `dynamicTable` |
| A read-only or lightly interactive grid over server data | `table` |
| Server owns paging, sorting and filtering | `table` with `lazyLoad: true` and `TABLE-POST` |
| Cards instead of rows | `listGrid` |
| A repeating block of fields rather than a grid of cells | `dynamicPanel` |

`table` never uses `column.rows`; its cells are `columnsConfig`, keyed by `key`. `dynamicTable` never uses `columnsConfig`; its cells are `columns`, keyed by `name`.

### 6.23 `table` property map

Grouped so nothing has to be guessed.

| Group | Properties |
| --- | --- |
| Data | `dataSource` `tableItemsPath` `tableTotalPath` `lazyLoad` `params` `orderClause` `orderDirection` |
| Columns | `columnsConfig` `showColumnSettings` `columnSettingsMode` `columnSettingsStorageKey` `columnSettingsDialogTitle` `columnSettingsDataSourceName` `columnSettingsDataSourcePath` `saveColumnSettingsDataSourceName` `resetColumnSettingsDataSourceName` |
| Paging | `pageSize` `pageSizeOptions` `paginator` `paginatorStyle` `paginatorVariant` `paginatorAlign` `paginatorMaxButtons` `showPageSizeSelector` `prevLabel` `nextLabel` |
| Search & filters | `showQuickSearch` `quickSearchPlaceholder` `quickSearchParamName` `quickSearchCondition` `quickSearchCaseMode` `searchDebounceMs` `showDetailedSearch` `detailedSearchCaseMode` `enableSavedFilters` `savedFiltersMode` `savedFiltersDataSourceName` `savedFiltersItemsPath` `saveFilterDataSourceName` `deleteFilterDataSourceName` `savedFilterIdKey` `savedFilterNameKey` `savedFilterCodeKey` `savedFilterDescriptionKey` `savedFilterPayloadKey` |
| Actions | `rowActions` `rowActionsDisplayMode` `rowActionsDropdownButtonStyle` `rowActionVisibilityPath` `rowClickActions` `rowExpandActions` `headerActions` `headerActionsPosition` `headerActionsDisplayMode` `headerMenuEnabled` `headerMenuActions` `headerMenuOptions` `headerMenuPlaceholder` `headerMenuDataSourceName` `headerMenuDataSourceItemsPath` `headerMenuItemsPath` `headerMenuLabelKey` `headerMenuValueKey` `actionsLabel` `showActionsHeaderLabel` |
| Selection | `enableSelection` `selectionKey` `selectionActions` `selectionActionsLabel` `selectionItemTemplate` `selectLabel` `selectAllLabel` `selectRowLabel` `autoSelectCondition` |
| Inline edit | `enableInlineEdit` `inlineEditStartMode` `inlineEditSaveDataSourceName` `inlineEditCancelOnReload` |
| Expand & details | `expandableRows` `expandedDisplayMode` `expandedColumnsConfig` `expandedDataSourceName` `expandedDataSourceItemsPath` `expandedItemsPath` `expandedTemplate` `expandedEmptyMessage` `expandedRowActions` `showExpandChevron` `alwaysShowExpandChevron` `expandLabel` `collapseLabel` `rowClickOpensDetails` `detailsPanelTitle` |
| Export | `showExport` `exportFileName` `exportUseColumnPicker` `exportAllPageSize` |
| Appearance | `tableStyle` `stickyHeader` `rowHover` `responsiveMode` `flatHeaderSurface` `flatFooterSurface` `showHeaderControls` `headerCenterElementsPosition` `headerTemplate` `rowTemplate` `rowTemplateName` `emptyMessage` `loadingLabel` `width` `tabletWidth` `mobileWidth` `hidden` `visibleIf` |
| Virtual scroll | `virtualScroll` `virtualScrollRowHeight` `virtualScrollViewportHeight` `virtualScrollBuffer` |

Column (`columnsConfig[*]`) properties:

| Group | Properties |
| --- | --- |
| Identity | `key` (required) `label` `showHeaderLabel` `mobileLabel` `type` `showInTable` `showInDetails` `detailLabel` `sortable` `width` `align` `visibleIf` |
| Formatting | `formatLocale` `dateFormatPattern` `dateIncludeSeconds` `numberMinFractionDigits` `numberMaxFractionDigits` `numberUseGrouping` |
| Element cells | `elementType` `element` `controlActiveIf` `controlEnabledIf` |
| Status cells | `statusRules` `statusShowIcon` |
| Templates | `template` `templateName` `templateFieldMap` |
| Filters | `filterControlType` `filterOptionsSourceType` `filterOptions` `filterOptionsJson` `filterOptionsPath` `filterOptionsDataSourceName` `filterOptionsDataSourceItemsPath` `filterOptionLabelKey` `filterOptionValueKey` `filterMultiValueDelimiter` `filterToggleTrueValue` `filterToggleFalseValue` |
| Inline edit | `editable` `editorType` `editorPlaceholder` `editorOptions` `editorOptionLabelKey` `editorOptionValueKey` |
| Cell actions | `cellActionsEnabled` `cellActions` `cellActionsDisplayMode` `cellActionsPlaceholder` |

Enumerations, exact values:

| Property | Values |
| --- | --- |
| `columnsConfig[*].type` | `text` `date` `dateTime` `number` `element` (legacy, still rendered: `boolean` `html` `status` `toggleSwitch` `singleCheckbox`) |
| `columnsConfig[*].align` | `left` `center` `right` |
| `columnsConfig[*].filterControlType` | `auto` `text` `number` `date` `dateTime` `boolean` `select` `multiSelect` `toggle` |
| `columnsConfig[*].editorType` | `auto` `text` `number` `date` `textarea` `checkbox` `toggle` `select` |
| `columnsConfig[*].filterOptionsSourceType` | `static` `datasource` |
| `statusRules[*].tone` | `neutral` `success` `warning` `risk` `primary` `danger` `info` |
| `tableStyle` | `default` `grid` `striped` |
| `responsiveMode` | `auto` `stack` |
| `rowActionsDisplayMode` | `dropdown` `iconButtons` `buttons` |
| `rowActionsDropdownButtonStyle` | `borderless` `default` |
| `headerActionsDisplayMode` | `buttons` `dropdown` |
| `headerActionsPosition` | `start` `center` `end` |
| `headerCenterElementsPosition` | `left` `center` `right` |
| `paginatorStyle` | `default` `compact` `segmented` |
| `paginatorVariant` | `full` `pager` `numbers` `simple` |
| `paginatorAlign` | `start` `center` `end` |
| `quickSearchCondition` | `%-%` `!%-%` `%-` `-%` `=` `!=` |
| `quickSearchCaseMode`, `detailedSearchCaseMode` | `caseInsensitiveLatin` `caseSensitive` `uppercase` `lowercase` |
| `columnSettingsMode` | `none` `localStorage` `dataSource` `host` |
| `savedFiltersMode` | `localStorage` `dataSource` `host` |
| `expandedDisplayMode` | `sidePanel` `inline` |
| `inlineEditStartMode` | `action` `doubleClick` |
| `orderDirection` | `asc` `desc` |

---

## 7. `dynamicTable`: editable repeating rows

`dynamicTable` is the editable grid: users add and delete rows and type into cells. Its cells are declared in its own `columns` array, where **each entry is a full element definition**.

```json
{
  "pages": [
    {
      "name": "page1",
      "rows": [
        { "columns": [{ "elementRef": "el1" }] },
        { "columns": [{ "elementRef": "el2" }] }
      ]
    }
  ],
  "elements": {
    "page1": { "name": "page1", "label": "Invoice", "type": "page" },
    "el1": {
      "name": "el1",
      "label": "Invoice lines",
      "type": "dynamicTable",
      "addRowButtonText": "Add line",
      "emptyMessage": "No lines yet",
      "maxRows": 50,
      "disallowAddRows": false,
      "disallowDeleteRows": false,
      "confirmRowDeletion": true,
      "confirmDeleteTitle": "Remove line",
      "confirmDeleteMessage": "Remove this invoice line?",
      "confirmDeleteConfirmLabel": "Remove",
      "confirmDeleteCancelLabel": "Keep",
      "hideRowIf": "{row.column5} == true",
      "columns": [
        {
          "name": "column1",
          "label": "Product",
          "type": "select",
          "strictOptions": true,
          "options": [
            { "value": "p1", "label": "Widget" },
            { "value": "p2", "label": "Gadget" }
          ]
        },
        {
          "name": "column2",
          "label": "Qty",
          "type": "number",
          "min": 1,
          "step": 1,
          "defaultValue": 1,
          "valueStorageType": "number"
        },
        {
          "name": "column3",
          "label": "Unit price",
          "type": "number",
          "step": 0.01,
          "valueStorageType": "number",
          "visualFormatEnabled": true,
          "visualFormatMinFractionDigits": 2,
          "visualFormatMaxFractionDigits": 2
        },
        {
          "name": "column4",
          "label": "Line total",
          "type": "number",
          "readOnly": true,
          "valueStorageType": "number",
          "expression": "{row.column2} * {row.column3}",
          "logicExecutionMode": "onChange",
          "useTotals": true,
          "totalUseGrouping": true,
          "totalFractionDigits": 2,
          "totalLocale": "lt-LT"
        },
        {
          "name": "column5",
          "label": "Cancelled",
          "type": "singleCheckbox",
          "checkboxLabel": "Cancelled",
          "defaultValue": false
        }
      ]
    },
    "el2": {
      "name": "el2",
      "label": "Invoice total",
      "type": "number",
      "readOnly": true,
      "expression": "{el1.column4-total}",
      "logicExecutionMode": "onChange"
    }
  }
}
```

The rules that make this work:

- **Inside a row, other cells of the same row are `{row.columnX}`.** A bare `{column3}` reads a top-level form field with that name, not the cell.
- `useTotals: true` publishes a footer sum. That sum is readable elsewhere as `{el1.column4-total}`: the table name, a dot, the column name, `-total`. `totalToData: true` publishes the sum without drawing the footer row.
- `hideRowIf` is evaluated per row, also against `{row.*}`.
- Column entries are element definitions, so any leaf element type and its own properties are valid there (`select` with `options`, `datepicker` with `format`, `text` with `maskType`, and so on).

Value shape: an array of objects, one per row, keyed by column `name`.

---

## 8. `dynamicPanel`: repeating groups, with nesting

`dynamicPanel` repeats a whole layout block. Its children live in the layout tree exactly like a `panel`'s, in `column.rows`. Each rendered entry gets its own copy.

```json
{
  "schemaVersion": 1,
  "settings": { "language": "en", "locale": "en-US", "width": "1000px", "widthUnit": "px" },
  "pages": [
    {
      "name": "page1",
      "rows": [
        {
          "columns": [
            {
              "elementRef": "el1",
              "rows": [
                { "columns": [{ "elementRef": "el2" }, { "elementRef": "el3" }] },
                { "columns": [{ "elementRef": "el4" }] },
                { "columns": [{ "elementRef": "el5" }] }
              ]
            }
          ]
        },
        { "columns": [{ "elementRef": "el6" }] },
        { "columns": [{ "elementRef": "el7" }] }
      ]
    }
  ],
  "elements": {
    "page1": { "name": "page1", "label": "Projects", "type": "page" },

    "el1": {
      "name": "el1",
      "label": "Projects",
      "type": "dynamicPanel",
      "addRowButtonText": "Add project",
      "removeRowButtonText": "Remove project",
      "emptyMessage": "No projects yet",
      "maxRows": 10,
      "confirmRowDeletion": true,
      "confirmDeleteTitle": "Remove project",
      "confirmDeleteMessage": "Remove this project and all of its tasks?",
      "panelPadding": "16px",
      "panelRadius": "8px",
      "panelBorderWidth": "1px",
      "contentGap": "12px",
      "resetChildrenOnHide": true
    },

    "el2": { "name": "el2", "label": "Project name", "type": "text", "required": true },
    "el3": {
      "name": "el3",
      "label": "Status",
      "type": "select",
      "strictOptions": true,
      "options": [
        { "value": "open", "label": "Open" },
        { "value": "done", "label": "Done" }
      ]
    },

    "el4": {
      "name": "el4",
      "label": "Tasks",
      "type": "dynamicTable",
      "addRowButtonText": "Add task",
      "columns": [
        { "name": "column1", "label": "Task", "type": "text" },
        {
          "name": "column2",
          "label": "Hours",
          "type": "number",
          "step": 0.5,
          "valueStorageType": "number",
          "useTotals": true,
          "totalFractionDigits": 1
        },
        {
          "name": "column3",
          "label": "Rate",
          "type": "number",
          "step": 0.01,
          "valueStorageType": "number"
        },
        {
          "name": "column4",
          "label": "Cost",
          "type": "number",
          "readOnly": true,
          "valueStorageType": "number",
          "expression": "{row.column2} * {row.column3}",
          "logicExecutionMode": "onChange",
          "useTotals": true,
          "totalFractionDigits": 2
        }
      ]
    },

    "el5": {
      "name": "el5",
      "label": "Project cost",
      "type": "number",
      "readOnly": true,
      "expression": "{panel.el4.column4-total}",
      "logicExecutionMode": "onChange"
    },

    "el6": {
      "name": "el6",
      "label": "Total cost of all projects",
      "type": "number",
      "readOnly": true,
      "expression": "sumArray({el1}, el5)",
      "logicExecutionMode": "onChange"
    },

    "el7": {
      "name": "el7",
      "label": "Open projects",
      "type": "number",
      "readOnly": true,
      "expression": "countInArray({el1}, el3 == \"open\")",
      "logicExecutionMode": "onChange"
    }
  },
  "localization": { "defaultLanguage": "en", "languages": ["en"] }
}
```

Context rules for nested structures, in one place:

| Where you are | How you reach a value |
| --- | --- |
| Top level of the form | `{el1}` |
| Inside a `dynamicTable` row | `{row.column2}` for a sibling cell |
| Inside a `dynamicPanel` entry | `{panel.el3}` for a sibling field of the same entry |
| A `dynamicTable` column total | `{el1.column4-total}` at top level |
| A total inside a panel entry | `{panel.el4.column4-total}` |
| A specific panel entry from outside | `{el1[0].el4.column4-total}` |
| Across all entries of a panel | `sumArray({el1}, el5)`, `countInArray({el1}, el3 == "open")` |
| A runtime variable | `{__variables.tenantId}` |
| A table's own live state | `{__table.el2.selectedRows}`, `{__table.el2.totalRecords}` (see 6.5) |
| Host-supplied external context | `{__external.userName}` |

Inside collection functions the entry fields are written **bare and unquoted** (`el3 == "open"`), while anything outside the collection still uses braces (`role == {__variables.requiredRole}`).

Prefer one aggregate over repeated accumulation. `setValue({var1}, sumArray({el1}, el5[].column3))` is safe on every recalculation; `sumValue` adds again on every run and belongs in an action, never in an `expression`.

---

## 9. Data sources and runtime variables

### 9.1 Every source type

`dataSources[*]` is `{ name, title, type, params }`, where `params` differs per `type`. `type` is `rest`, `local`, `route` or `websocket`.

```json
{
  "dataSources": [
    {
      "name": "ds1",
      "title": "Customers (GET)",
      "type": "rest",
      "params": { "url": "/api/customers", "method": "GET" }
    },
    {
      "name": "ds2",
      "title": "Save customer (POST)",
      "type": "rest",
      "params": {
        "url": "/api/customers/{id}",
        "method": "POST",
        "body": { "name": "{el1}", "segment": "{el2}", "tenantId": "{__variables.tenantId}" }
      }
    },
    {
      "name": "ds3",
      "title": "Server-side table",
      "type": "rest",
      "params": { "url": "/api/customers/search", "method": "TABLE-POST" }
    },
    {
      "name": "ds4",
      "title": "Static options",
      "type": "local",
      "params": {
        "localMode": "json",
        "dataJson": "[{\"id\":\"LT\",\"name\":\"Lithuania\"},{\"id\":\"LV\",\"name\":\"Latvia\"}]"
      }
    },
    {
      "name": "ds5",
      "title": "Options already in the form data",
      "type": "local",
      "params": { "localMode": "dataPath", "dataPath": "el9.items" }
    },
    {
      "name": "ds6",
      "title": "Resolved route data",
      "type": "route",
      "params": { "routeDataKey": "customer", "routeDataPath": "data" }
    },
    {
      "name": "ds7",
      "title": "Live feed",
      "type": "websocket",
      "params": {
        "url": "wss://example.test/feed",
        "protocols": "",
        "message": "{\"subscribe\":\"orders\"}",
        "messagePath": "payload",
        "messageMode": "pushValuesInArray"
      }
    }
  ]
}
```

REST URL and body templates use **single** braces: `{el1}`, `{row.id}`, `{__variables.tenantId}`. Method is one of `GET` `POST` `PUT` `PATCH` `DELETE`, plus the special `TABLE-POST` for lazy tables.

### 9.2 Element-level `dataSource` and cascading selects

The element-level `dataSource` object is `IElementDataSource`: `name`, `useFor`, `optionValue`, `optionLabel`, `filterOptionsBy`, `params`, `refreshOnChange`, `refreshPaths`. Nothing else.

```json
{
  "elements": {
    "el1": {
      "name": "el1",
      "label": "Country",
      "type": "select",
      "showSearch": true,
      "strictOptions": true,
      "dataSource": {
        "name": "ds1",
        "useFor": "option",
        "optionValue": "id",
        "optionLabel": "name"
      }
    },
    "el2": {
      "name": "el2",
      "label": "City",
      "type": "select",
      "strictOptions": true,
      "disableIf": "isEmpty({el1})",
      "resetIf": "isEmpty({el1})",
      "logicExecutionMode": "onChange",
      "dataSource": {
        "name": "ds2",
        "useFor": "option",
        "optionValue": "id",
        "optionLabel": "name",
        "params": [{ "name": "country", "value": "{el1}" }],
        "refreshOnChange": true,
        "refreshPaths": ["el1"]
      }
    },
    "el3": {
      "name": "el3",
      "label": "Warehouse",
      "type": "select",
      "strictOptions": true,
      "dataSource": {
        "name": "ds3",
        "useFor": "option",
        "optionValue": "id",
        "optionLabel": "title",
        "filterOptionsBy": "item.cityId == {el2} && item.active == true",
        "refreshPaths": ["el2"]
      }
    },
    "el4": {
      "name": "el4",
      "label": "Loaded name",
      "type": "text",
      "expression": "{__variables.recordData}.name",
      "logicExecutionMode": "onChange"
    }
  },
  "dataSources": [
    { "name": "ds1", "title": "Countries", "type": "rest", "params": { "url": "/api/countries", "method": "GET" } },
    { "name": "ds2", "title": "Cities", "type": "rest", "params": { "url": "/api/countries/{country}/cities", "method": "GET" } },
    { "name": "ds3", "title": "Warehouses", "type": "rest", "params": { "url": "/api/warehouses", "method": "GET" } },
    { "name": "ds4", "title": "Record", "type": "rest", "params": { "url": "/api/records/{__variables.recordId}", "method": "GET" } }
  ]
}
```

- `useFor: "option"` feeds the option list; `useFor: "value"` feeds the element's value.
- `params[*].value` resolves form fields, `{row.*}` and `{__variables.*}`; the resolved values also fill `{placeholder}` tokens in the source URL.
- `filterOptionsBy` filters the fetched list client-side. The candidate option is `item.*`; form fields stay in braces.

### 9.3 Runtime variables

```json
{
  "settings": {
    "language": "en",
    "variables": [
      { "name": "recordId", "title": "Record id", "sourceType": "route", "source": "id" },
      { "name": "tenantId", "title": "Tenant", "sourceType": "external", "source": "tenantId", "fallbackValue": "" },
      { "name": "apiBase", "title": "API base", "sourceType": "constant", "constantValue": "/api/v2" },
      {
        "name": "isEdit",
        "title": "Edit mode",
        "sourceType": "expression",
        "expression": "notEmpty({__variables.recordId})",
        "refreshPaths": []
      },
      {
        "name": "settingsData",
        "title": "Settings",
        "sourceType": "dataSource",
        "source": "ds1",
        "fallbackValue": {},
        "includeInDataJson": false
      },
      {
        "name": "draftName",
        "title": "Draft name",
        "sourceType": "manual",
        "targetPath": "el1",
        "includeInDataJson": true
      }
    ]
  }
}
```

`sourceType` is exactly one of `route` `external` `constant` `expression` `dataSource` `manual`. Read a variable anywhere as `{__variables.name}`, never as `{name}`. A `dataSource` variable needs an explicit `source`.

---

## 10. Expression cookbook

Every logic field is a **direct property of the element**. There is no `logic` wrapper. All of them take JEXL.

```json
{
  "elements": {
    "el1": { "name": "el1", "label": "Price", "type": "number", "valueStorageType": "number" },
    "el2": { "name": "el2", "label": "Quantity", "type": "number", "valueStorageType": "number" },

    "el3": {
      "name": "el3",
      "label": "Total",
      "type": "number",
      "readOnly": true,
      "expression": "{el1} * {el2}",
      "logicExecutionMode": "onChange",
      "dependsOn": ["el1", "el2"]
    },

    "el4": {
      "name": "el4",
      "label": "Customer type",
      "type": "radio",
      "showInline": true,
      "defaultValue": "person",
      "options": [
        { "value": "person", "label": "Person" },
        { "value": "company", "label": "Company" }
      ]
    },
    "el5": {
      "name": "el5",
      "label": "Company code",
      "type": "text",
      "visibleIf": "{el4} == 'company'",
      "requireIf": "{el4} == 'company'",
      "resetIf": "{el4} != 'company'",
      "logicExecutionMode": "onChange"
    },

    "el6": {
      "name": "el6",
      "label": "Discount %",
      "type": "number",
      "disableIf": "{el3} < 100",
      "readonlyIf": "{__variables.isEdit} != true",
      "logicExecutionMode": "onChange",
      "validators": [
        { "type": "min", "value": 0, "message": "Cannot be negative" },
        { "type": "max", "value": 50, "message": "50% is the maximum", "applyIf": "{el4} == 'person'" },
        {
          "type": "custom",
          "condition": "{el6} > 0 && isEmpty({el7})",
          "message": "Give a reason for the discount"
        }
      ]
    },
    "el7": { "name": "el7", "label": "Discount reason", "type": "textarea", "rows": 2 },

    "el8": {
      "name": "el8",
      "label": "Starts",
      "type": "datepicker",
      "format": "YYYY-MM-DD"
    },
    "el9": {
      "name": "el9",
      "label": "Ends",
      "type": "datepicker",
      "format": "YYYY-MM-DD",
      "minValue": "{el8}",
      "validators": [
        {
          "type": "custom",
          "condition": "notEmpty({el8}) && notEmpty({el9}) && dateDiffDays({el8}, {el9}) < 1",
          "message": "End date must be after the start date"
        }
      ]
    },

    "el10": {
      "name": "el10",
      "label": "Summary",
      "type": "text",
      "readOnly": true,
      "expression": "getLabel({el4}) + ': ' + {el3} + ' EUR'",
      "logicExecutionMode": "onChange"
    },

    "el11": {
      "name": "el11",
      "label": "Tags",
      "type": "multiSelect",
      "options": [
        { "value": "a", "label": "A" },
        { "value": "b", "label": "B" }
      ]
    },
    "el12": {
      "name": "el12",
      "label": "Has tag A",
      "type": "singleCheckbox",
      "checkboxLabel": "Tagged A",
      "readOnly": true,
      "expression": "contains({el11}, 'a')",
      "logicExecutionMode": "onChange"
    }
  }
}
```

Operators JEXL supports: `&& || ! == != > >= < <= + - * / // % ^ in`, the ternary `a ? b : c`, and the Elvis `a ?: b`. It does **not** support `??`, `?.`, arrow functions or any other JavaScript-only syntax.

Built-in functions: `isEmpty` `notEmpty` `toNumber` `inRange` `len` `contains` `containsAny` `containsAll` `inArray` `collectValuesFrom` `sumInArray` `avgInArray` `minInArray` `maxInArray` `countInArray` `firstInArray` `lastInArray` `joinInArray` `filterArray` `mapArray` `findInArray` `existsInArray` `sumArray` `avgArray` `getFirst` `getLast` `flattenArray` `today` `now` `date` `day` `month` `year` `weekDay` `weekDayIndex` `isWeekend` `addDays` `dateDiffDays` `startOfWeek` `endOfWeek` `getVal` `getValue` `getLabel` `getElementProperty` `getProp` `translate` `currentLanguage` `setValue` `sumValue` `pushValue` `setVar` `sumVar` `pushVar` `setElementProperty` `runDataSource` `dbg`.

Validator objects accept exactly `type`, `value`, `message`, `condition`, `applyIf`. `condition` is the **failing** check: the error shows while it is `true`.

---

## 11. Actions and events

`events` is an array of `IElementActionConfig`. Same shape for `button.events`, `table.rowActions`, `table.headerActions`, `table.selectionActions`, cell actions and dialog footer actions.

```json
{
  "elements": {
    "el1": {
      "name": "el1",
      "label": "",
      "type": "button",
      "text": "Save",
      "variant": "solid",
      "tone": "primary",
      "icon": "save",
      "iconPosition": "left",
      "size": "normal",
      "fitContent": true,
      "events": [
        {
          "trigger": "click",
          "type": "dataSource",
          "dataSourceName": "ds1",
          "validateForm": true,
          "confirmEnabled": true,
          "confirmTitle": "Save changes",
          "confirmMessage": "Write these changes to the server?",
          "confirmConfirmLabel": "Save",
          "confirmCancelLabel": "Cancel",
          "params": [
            { "name": "id", "value": "{__variables.recordId}" },
            { "name": "name", "value": "{el3}" }
          ],
          "responseMode": "setValue",
          "responseDataPath": "data.id",
          "responseTargetPath": "el4",
          "reloadOnReturnElementNames": ["el5"],
          "showToastAfter": true,
          "toastTitle": "Saved",
          "toastMessage": "The record was stored",
          "toastVariant": "success",
          "toastPosition": "bottom-right",
          "toastAutoHide": true,
          "toastAutoHideMs": 3000
        }
      ],
      "menuActions": [
        { "label": "Save and close", "type": "submit", "validateForm": true },
        { "label": "Discard", "type": "navigate", "navigateTo": "/records" }
      ]
    },

    "el2": {
      "name": "el2",
      "label": "",
      "type": "button",
      "text": "Download report",
      "variant": "outline",
      "tone": "neutral",
      "fitContent": true,
      "events": [
        {
          "trigger": "click",
          "type": "dataSource",
          "dataSourceName": "ds2",
          "responseMode": "download",
          "responseFileName": "report.pdf"
        }
      ]
    },

    "el3": { "name": "el3", "label": "Name", "type": "text" },
    "el4": { "name": "el4", "label": "Saved id", "type": "text", "readOnly": true },
    "el5": { "name": "el5", "label": "History", "type": "table", "columnsConfig": [] },

    "el6": {
      "name": "el6",
      "label": "Segment",
      "type": "select",
      "options": [
        { "value": "a", "label": "A" },
        { "value": "b", "label": "B" }
      ],
      "events": [
        {
          "trigger": "change",
          "type": "setOptions",
          "setOptionsTargetElement": "el7",
          "setOptionsMode": "contextPath",
          "setOptionsValue": "lookup.subSegments"
        },
        {
          "trigger": "change",
          "type": "reloadElements",
          "reloadElementNames": ["el5"],
          "condition": "notEmpty({el6})"
        }
      ]
    },
    "el7": { "name": "el7", "label": "Sub-segment", "type": "select", "options": [] }
  }
}
```

Action fields by `type`:

| `type` | Required / typical fields |
| --- | --- |
| `navigate` | `navigateTo`, `openInNewTab`, `beforeNavigateDataSourceName` |
| `dataSource` | `dataSourceName`, `params`, `responseMode` (`none` `download` `setValue`), `responseDataPath`, `responseTargetElement`, `responseTargetPath`, `responseFileName`, `reloadCurrentElementAfterSuccess`, `reloadOnReturnElementNames`, `reloadDataSourceNames` |
| `setValue` | `setValueTargetPath`, `setValueMode` (`contextPath` `template` `json` `expression`), `setValueValue` |
| `setOptions` | `setOptionsTargetElement`, `setOptionsMode`, `setOptionsValue` |
| `reloadElements` | `reloadElementNames` |
| `toast` | `toastTitle`, `toastMessage`, `toastVariant`, `toastPosition`, `toastAutoHide`, `toastAutoHideMs`, `toastShowIcon`, `toastIcon` |
| `dialog` | `dialogName`, `dialogOperation` (`open` `close` `toggle`) |
| `sendMessage` | `dataSourceName` (a `websocket` source), `messagePayload` |
| `validate` | none; validates the whole form |
| `submit` | none; validates, then fires `onComplete` with `{ isValid, data, issues }` |

Common to all: `trigger` (`click` `submit` `input` `change` `blur` `focus` `beforeLoad` `onLoad` `afterLoad` `always`), `label`, `icon`, `hideText`, `condition`, `validateForm`, `debounceMs`, `confirmEnabled`, `confirmOnDirty`, `confirmTitle`, `confirmMessage`, `confirmConfirmLabel`, `confirmCancelLabel`, `buttonVariant` (`filled` `outlined` `text`), `buttonTone` (`primary` `risk` `neutral`), `useCustomButtonStyle`, `showToastAfter` and the `toast*` fields.

Note the two different button vocabularies: a `button` **element** uses `variant` (`solid` `outline` `text`) and `tone` (`primary` `neutral` `success` `info` `warning` `risk`); an **action** rendered as a button uses `buttonVariant` (`filled` `outlined` `text`) and `buttonTone` (`primary` `risk` `neutral`).

---

## 12. Multi-page stepper

Several entries in `pages` become steps. Each still needs its twin in `elements`.

```json
{
  "schemaVersion": 1,
  "settings": {
    "language": "en",
    "locale": "en-US",
    "width": "760px",
    "widthUnit": "px",
    "pageNavigationMode": "stepper",
    "stepperPosition": "top",
    "pageNavigationPosition": "bottom",
    "allowStepWithoutValidation": false,
    "actionButtonsPosition": "bottom",
    "showSubmitButton": true,
    "showValidateButton": false,
    "showValidationIssuesModal": true
  },
  "pages": [
    { "name": "page1", "rows": [{ "columns": [{ "elementRef": "el1" }, { "elementRef": "el2" }] }] },
    { "name": "page2", "rows": [{ "columns": [{ "elementRef": "el3" }] }] },
    { "name": "page3", "rows": [{ "columns": [{ "elementRef": "el4" }] }] }
  ],
  "elements": {
    "page1": { "name": "page1", "label": "Applicant", "type": "page" },
    "page2": { "name": "page2", "label": "Address", "type": "page" },
    "page3": {
      "name": "page3",
      "label": "Review",
      "type": "page",
      "visibleIf": "notEmpty({el1}) && notEmpty({el2})"
    },
    "el1": { "name": "el1", "label": "First name", "type": "text", "required": true },
    "el2": { "name": "el2", "label": "Last name", "type": "text", "required": true },
    "el3": { "name": "el3", "label": "Street", "type": "text", "required": true },
    "el4": {
      "name": "el4",
      "label": "",
      "type": "customHtml",
      "htmlTemplate": "<p>Submitting as <b>{el1} {el2}</b>, {el3}</p>"
    }
  },
  "localization": {
    "defaultLanguage": "en",
    "languages": ["en", "de"],
    "texts": {
      "en": { "submitButtonText": "Submit" },
      "de": { "submitButtonText": "Absenden" }
    }
  }
}
```

---

## 13. Pre-return checklist for any of these

1. Every `elementRef` resolves; every `elements` key equals its `name`.
2. Every `pages[*].name` has an `elements` twin with `type: "page"`.
3. No element definition holds children (`rows`, `columns`, `children`, `items`); the exception is `dynamicTable.columns` and `table.columnsConfig`, which are cell definitions, not layout.
4. No column object holds anything besides `elementRef`, `rows`, `tabRows`.
5. `table` columns use `key`. `dynamicTable` columns use `name`.
6. `statusRules[*].condition` uses `value`; `rowActions[*].condition` uses `row.*`.
7. Action and element-datasource `params` are `[{ "name", "value" }]`; table request params are `[{ "paramName", "paramValue" }]`.
8. Runtime variables are read as `{__variables.x}`.
9. Logic fields sit directly on the element; validators use `condition` / `applyIf`.
10. Every type string matches the canonical list exactly, casing included.

---

## AI: Legacy form migration

Source: https://ngxviewbuilder.io/ai/legacy-form-migration

# AI: Legacy form migration

This page is intended for the AI agent when a user asks to convert a form defined in a legacy form-builder JSON format to NGX View Builder JSON.

## Core rule

- Do not copy the source JSON 1:1.
- First recognize the semantics of the source form.
- Then map them to the closest supported NGX View Builder structure.

## Element map

| Source JSON | NGX View Builder |
| --- | --- |
| `text` | `text` or `number` / `phoneInput` depending on `inputType` |
| `comment` | `textarea` |
| `radiogroup` | `radio` |
| `dropdown` | `select` |
| `dropdown_list` | `autocomplete` |
| `tagbox` | `multiSelect` |
| `checkbox` | `checkbox` or `singleCheckbox` |
| `boolean` | `singleCheckbox` |
| `date` / `date_picker` | `datepicker` |
| `file_uploader` / `file_list` | `fileUpload` |
| `html` | `customHtml` |
| `message_box` | `messageCard` |
| `panel` | `panel` |
| `paneldynamic` | `dynamicPanel` |
| `matrixdynamic` / `matrixdropdown` | `dynamicTable` |
| `dialog` | `dialog` |

## Property map

- `visibleIf` maps directly to `visibleIf`: same field name, same polarity, no inversion needed.
- `enableIf` is typically mapped to `disableIf`, but the logic must be inverted.
- `requiredIf` maps to `requireIf`.
- `resetValueIf` maps to `resetIf`.
- `setValueExpression` typically maps to `expression`.
- `defaultValue` stays as `defaultValue` if it is a static value.
- `defaultValueExpression` can become `defaultValue` if it is a literal, or `expression` if it is a computed value.
- `choices` maps to `options`.
- `validators` maps to `validators`.

## Expression translation rules

In the final NGX View Builder JSON, use NGX View Builder / `JEXL`-style syntax.

### Operators

- `and` -> `&&`
- `or` -> `||`
- `<>` -> `!=`
- `=` in comparisons -> `==`
- `iif(cond, a, b)` -> `cond ? a : b`

### Empty values

- `x notempty` -> `notEmpty(x)`
- `x empty` -> `isEmpty(x)`

### Collections

- `anyof` -> `containsAny(left, values)`
- `allof` -> `containsAll(left, values)`
- `contains` -> `contains(left, value)`
- `{field.length}` -> `len({field})`

### Dynamic contexts

- `{panelIndex}` -> `panel.index`
- `{rowIndex}` -> `row.index`
- `{parentIndex}` -> `parentIndex`
- `{panel.field}` -> `panel.field`
- `{row.field}` -> `row.field`

## Important safeguards

- Do not use source-library property names in the final NGX View Builder JSON if NGX View Builder does not have that property.
- Do not use `and`, `or`, `notempty`, `empty`, `<>`, or `iif(...)` in final NGX View Builder expression strings.
- Do not use self-reference expressions. A field must not reference itself in a fallback branch.
- If `expression`, `visibleIf`, `disableIf`, `requireIf`, `readonlyIf`, or `resetIf` is added, `logicExecutionMode: "onChange"` is typically required.

## When a 1:1 mapping is not possible

- If a source-library feature has no direct NGX View Builder equivalent, produce the closest safe result.
- In that case, briefly explain in a `warnings` section what was simplified or lost.

---

## Angular form & view builder for developers

Source: https://ngxviewbuilder.io/developers/

# Introduction for developers

NGX View Builder is an Angular library with two halves:

- **Builder**: the visual editor your creators use to design views.
- **Runtime**: the engine that renders a saved view definition (JSON) to end users.

You embed one or both as standalone components, persist the JSON wherever you like, and control everything else (data, theming, custom elements, plugins) through providers and a typed API service.

## The five components

| Component | Selector | Purpose |
| --- | --- | --- |
| Builder | `<ngx-view-builder-builder>` | Full editing shell: canvas, sidebars, tabs, history |
| Runtime | `<ngx-view-builder-runtime>` | Renders a view definition with live logic and data |
| Unified | `<ngx-view-builder>` | Runtime-oriented host that can also take a `BuilderModel` |
| Renderer | `<ngx-view-builder-renderer>` | Low-level renderer used by the unified wrapper |
| Validator | `<ngx-view-builder-validator>` | Headless validation for server-side scenarios |

## The flow

```
Creator designs in <ngx-view-builder-builder>
        │  (structureChanged) → IStructure JSON
        ▼
Your backend / storage
        │  [pageJson]
        ▼
<ngx-view-builder-runtime> renders to end users
        │  values, events, validation
        ▼
Your app (via outputs and NgxViewBuilderApiService)
```

## What you can extend

| Extension | How |
| --- | --- |
| Custom elements (component + model + properties) | [Custom elements](https://ngxviewbuilder.io/developers/custom-elements) |
| Expression functions | [Custom functions](https://ngxviewbuilder.io/developers/custom-functions) |
| Extra/changed element properties | [Custom properties](https://ngxviewbuilder.io/developers/custom-properties) |
| SVG icons | [Icons](https://ngxviewbuilder.io/developers/icons) |
| Theme tokens, light/dark palettes | [Theming](https://ngxviewbuilder.io/developers/theming) |
| Builder UI language | [UI translations](https://ngxviewbuilder.io/developers/ui-translations) |
| Whole builder tabs | [Plugins](https://ngxviewbuilder.io/developers/plugin-development) |

## Reading order

1. [Installation](https://ngxviewbuilder.io/developers/installation): package, providers, initialization.
2. [Embedding the builder](https://ngxviewbuilder.io/developers/builder-integration) and [Rendering views](https://ngxviewbuilder.io/developers/runtime-integration).
3. [API service overview](https://ngxviewbuilder.io/developers/api-service): the programmatic surface.
4. [Extensions overview](https://ngxviewbuilder.io/developers/extensions): one config object for everything custom.

---

## AI command API

Source: https://ngxviewbuilder.io/developers/ai-command-api

# AI command API

The AI command API is a design time surface that lets an agent inspect and edit the view a user is currently designing. Everything crosses the boundary as plain JSON, so nothing Angular shaped leaks out and the whole contract survives a trip through a websocket.

An agent reaches it over MCP. The browser dials out to the MCP server and the server forwards each method call back down that socket, so the user's machine never has to accept an inbound connection.

It exposes one write door and a handful of read methods, one MCP tool each:

| Method | MCP tool | What it does |
| --- | --- | --- |
| `available()` | part of `nvb_status` | false whenever the builder is not on screen |
| `help()` | `nvb_get_instructions` | the full command catalog, with schemas |
| `getSystemInstructions()` | `nvb_get_instructions` | the contract as one prompt ready block |
| `describeElementTypes(type?)` | `nvb_describe_element_types` | element types and their properties |
| `describeTemplates(name?)` | `nvb_describe_templates` | the template library, and what can host a template |
| `getTree()` | `nvb_get_tree` | compact outline of pages and elements |
| `getStructure()` | `nvb_get_structure` | the whole view JSON |
| `getElement(name)` | `nvb_get_element` | one element body |
| `getElementProperty(name, key)` | `nvb_get_element_property` | one property value |
| `getData()` | `nvb_get_data` | current working data |
| `getAuditLog()` | `nvb_get_audit_log` | every batch applied this session |
| `execute(commands, options?)` | `nvb_execute` | the only way to change anything |

## When it exists

The bridge connects only while `<ngx-view-builder-builder>` is mounted, and only when the host opted in. A runtime only host never opens one, no matter who calls what. Leaving the builder closes it again.

```ts
import { bootstrapApplication } from '@angular/platform-browser';
import { provideNgxViewBuilderRuntime, provideNgxViewBuilderMcp } from 'ngx-view-builder';

bootstrapApplication(AppComponent, {
  providers: [
    provideNgxViewBuilderRuntime(),
    provideNgxViewBuilderMcp({ url: 'wss://mcp.ngx-view-builder.io/bridge' }),
  ],
});
```

| Option | Description |
| --- | --- |
| `enabled` | Default `true`. Set `false` to keep the provider registered but leave the API closed. |
| `url` | Bridge endpoint of the MCP server. An `http(s)` URL is upgraded to `ws(s)`. |
| `autoConnect` | Default `true`. Set `false` to connect by hand through `NgxViewBuilderMcpBridgeService`. |
| `client` | App and page labels, shown in `nvb_status` so a user with several tabs open can tell which one an agent is attached to. |
| `sessionKey` | A key your own backend issued, string or resolver. Supply it and the pair code disappears: your backend already knows the key, so it can hand the same one to whatever AI client it wires up. |
| `auth` | Token your MCP server's authorization service understands. Forwarded untouched, never interpreted. |
| `metadata` | Anything your authorization service should see: tenant, user, plan hint. Echoed back in `nvb_status`. |

Without a `sessionKey`, the builder shows a pair code in its settings, under AI access (MCP), and an agent reaches the view only after a person has typed that code into their MCP client. With one, your backend has already decided who may connect, so no code is shown and nobody types anything. Either way the session lasts only as long as that tab stays open, and the panel says so once a client is attached.

The MCP server itself holds no user table. It asks whatever authorization service you configure and does what it is told, which is what lets you run it next to your own product and drive it from your own backend. See its README for the auth webhook contract.

## The two guarantees

**It runs only while the builder is on screen.** Three things must all hold: the host registered the provider, the builder component is mounted, and a person paired a code. Leaving the builder disarms the API and drops the socket. Disarming is what matters: closing the socket alone would leave the surface open to anything that had captured it. A disarmed API refuses every command with `apiClosed` and every read returns `null` or empty, so a captured reference is worth nothing on a runtime page.

**It cannot save.** There is no save, publish or submit command, and none of the mutation commands reach the host's save path. `saveTemplate` and `saveSidebarGroup` write reusable builder library items, not the view.

Automation an agent writes cannot commit the view either. Triggers and rules run a deliberately narrower action set than element events: `navigate`, `dataSource`, `toast`, `dialog`, `setValue`, `setElementProperty`, `transitionProcess`, `setProcessState` and `refreshRuntimeVariables`. There is no submit and no save among them, so an agent cannot author a rule that saves on load. An element `events` entry may use `submit`, but that still needs a person to click the element.

::: warning This is a design time tool
The worst a runaway agent can do is leave unsaved edits in an open tab, which a reload undoes. Keep it out of production builds, and let a person press Save.

A trigger bound to `onLoad` does run by itself when the view is rebuilt, so an agent can cause a data source call or a navigation without a click. That is a side effect, not a commit, but it is worth knowing when reviewing what an agent wrote.
:::

## Try it on the public demo

The bridge is armed on [demo.ngxviewbuilder.io/builder](https://demo.ngxviewbuilder.io/builder). Open the builder settings, copy the pair code from AI access (MCP), point your MCP client at `https://mcp.ngx-view-builder.io/mcp?code=NVB-XXXX-XXXX`, and watch it build.

Nothing there can be saved to anything of yours: the demo keeps its view in your own browser storage, and the API has no save command in the first place. Reloading the page restores the demo view.

## Start with getSystemInstructions()

`getSystemInstructions()` returns the whole contract as one block of text: what the API is, the working order, the rules worth following, which capabilities this builder has, and which templates are on hand. It is meant to go straight into a system prompt.

It exists because of a failure that has nothing to do with the schema. An agent told to "build this form through the AI API" often answers by describing the JSON it would send, or hands it over for someone to paste, because nothing in its context said the API is live and reachable right now. The instructions say that in the first line.

Call `nvb_get_instructions` first in a session. It returns both the prompt ready text and the machine readable `help()` object in one round trip.

`help()` is the machine readable version of the same thing: the command catalog with parameters and a worked example per command, the tab codes, behaviour notes, and three fields worth reading on their own.

| Field | What it carries |
| --- | --- |
| `notes` | How to call the API: batching, dry runs, idempotent names. |
| `guidelines` | How to decide what to build. Kept apart from `notes` so a host can put these in a prompt without the call mechanics. |
| `capabilities` | What the registered feature packs contribute, such as `templates`. |
| `featurePacks` | The packs themselves, by id and title. |

`describeElementTypes()` is the other one to call before writing anything. It returns every registered type, whether it can hold children, and the real property keys for each. Without it a model guesses property names and every command comes back with an error.

```json
// nvb_get_instructions -> result.help
{ "commands": [ /* 47 entries */ ], "capabilities": ["templates"] }

// nvb_describe_element_types { "type": "select" }
{ "properties": ["options", "showSearch", "required", "..."] }
```

## Build from element types first

The guidelines exist because an agent with a blank canvas reaches for markup far too early. Markup is the expensive answer: a `customHtml` element or a hand written template carries no options, no validation and no events, so everything built that way has to be rebuilt by hand later.

The case that comes up most is a status column. A table column that shows a badge, a status, a toggle or a checkbox is a hosted element, not markup:

```js
await api.execute({
  op: 'updateElement',
  name: 'ordersTable',
  properties: {
    columnsConfig: [
      { key: 'status', label: 'Status', type: 'element', elementType: 'badge' },
    ],
  },
});
```

The command layer reports both of these as warnings rather than errors, since an agent that was explicitly asked for custom markup is right to carry on. Read the warnings anyway:

- adding a `customHtml` element
- a column that sets `templateName` while its `type` is not `element`

## execute()

`execute()` takes one command or an array. An array is atomic: commands are folded into a draft copy of the structure, and if any of them fails, none of them are applied.

Over MCP this is `nvb_execute`, with the array under `commands` and the options as flat arguments (`dry_run`, `return_tree`, `return_structure`). The snippets on this page show the command shapes, which are the same either way.

```js
const result = await api.execute([
  { op: 'addElement', type: 'panel', name: 'contact', properties: { label: 'Contact' } },
  { op: 'addElement', type: 'text', name: 'email', parent: 'contact', properties: { label: 'Email', required: true } },
]);
```

| Option | Description |
| --- | --- |
| `dryRun` | Runs every check and reports what would change, then throws the draft away. |
| `returnStructure` | Includes the resulting view JSON in the result. |
| `returnTree` | Includes the resulting outline in the result. |

Commands come in two kinds. **Mutations** change the view and are applied to the draft in order. **Actions** do something to the running builder instead, and they run after the draft is committed, in the order they appear. `help()` labels each command with its `kind`.

### The result

Errors are data, never exceptions, because a thrown error does not survive a trip through a bridge.

```json
{
  "ok": false,
  "version": 1,
  "dryRun": false,
  "applied": 0,
  "changed": [],
  "errors": [
    {
      "index": 1,
      "op": "addElement",
      "code": "unknownType",
      "message": "Unknown element type 'txt'.",
      "hint": "Did you mean 'text'? Call describeElementTypes() for the full list."
    }
  ],
  "warnings": []
}
```

The `hint` field matters more than it looks. It is what lets an agent correct itself in one retry instead of looping.

Unknown property keys are reported as warnings rather than errors, because an element body is an open record and custom fields are legitimate. A misspelled property still lands, so read the warnings.

## Layout: rows and columns

This is the part worth understanding, because it decides whether fields stack or sit side by side.

A view is a list of rows, and each row holds one or more columns. By default a new element gets a row of its own, so elements stack. Naming an existing `row` in the target puts the element into that row instead, next to whatever is already there.

```js
await api.execute([
  { op: 'addElement', type: 'text', name: 'firstName', parent: 'contact', properties: { label: 'First name' } },
  // same row, so the two sit side by side
  { op: 'addElement', type: 'text', name: 'lastName', parent: 'contact', row: 0, properties: { label: 'Last name' } },
  // explicit position inside that row
  { op: 'addElement', type: 'text', name: 'title', parent: 'contact', row: 0, column: 0 },
]);
```

Every placement command shares the same target fields:

| Field | Description |
| --- | --- |
| `parent` | Name of a container element. Leave it out to place at page level. |
| `page` | Page name. Defaults to the first page. |
| `tab` | Required when the parent is a tab style container such as `tabs` or `accordion`. |
| `index` | Position of the new row. |
| `row` | Put the element into this existing row instead of creating one. |
| `column` | Position inside `row`. Appends when left out. |

Containers that hold children directly are `panel`, `dialog`, `splitter`, `dynamicPanel`, `emptyBlock`, `messageCard`, `statsCard` and `listGrid`. Containers that hold children per section, and therefore need a `tab`, are `tabs`, `tabsPro`, `accordion` and `progressFlow`. Targeting anything else returns a `notAContainer` error with the list.

Do not set a percentage `width` on fields you want side by side. Columns in a row already share the space, and a fixed width fights that. Use `mobileWidth: '100%'` when you want a pair to stack on narrow screens.

## Templates

When the [templates plugin](https://ngxviewbuilder.io/developers/plugin-templates) is registered, the view carries a template library and several element types can render a template instead of their own markup. The API surfaces the library so an agent can reuse what is already there rather than inventing a second version of the same card.

```js
api.describeTemplates();
// {
//   available: true,
//   capability: 'templates',
//   hosts: [
//     { type: 'listGrid',   property: 'cardTemplateName', fieldMap: 'cardTemplateFieldMap' },
//     { type: 'customHtml', property: 'htmlTemplateName', fieldMap: 'htmlTemplateFieldMap' },
//   ],
//   templates: [
//     { name: 'person card', slots: ['0', '1'], hasCss: true, contentPreview: '<div class="person">...' },
//   ],
// }
```

`available` is the gate. It is false when the plugin is not registered, and then the reference properties stay hidden in the builder, so writing one would bind a template nothing renders. Both template commands refuse with `capabilityMissing` in that case rather than writing a property that goes nowhere.

`hosts` is read from the property catalog rather than hard coded, so an element type a host registers with its own template property shows up there too.

Two commands go with it:

| Command | What it does |
| --- | --- |
| `upsertTemplate` | Creates or replaces a template by name. It lands in the draft, so a `useTemplate` later in the same batch can already reference it. |
| `useTemplate` | Points an element at a template and maps its slots. |

`useTemplate` resolves the reference property itself. A `listGrid` keeps it in `cardTemplateName` and a `customHtml` in `htmlTemplateName`, and expecting a caller to know that mapping is how bindings end up on the wrong key.

```js
await api.execute([
  {
    op: 'upsertTemplate',
    name: 'person card',
    content: '<div class="person"><b>{{row[0]}}</b><span>{{row[1]}}</span></div>',
    css: '.person { display: grid; gap: 4px; }',
  },
  { op: 'addElement', type: 'listGrid', name: 'peopleGrid', properties: { label: 'People' } },
  {
    op: 'useTemplate',
    name: 'peopleGrid',
    template: 'person card',
    fieldMap: { '0': 'fullName', '1': 'email' },
  },
]);
```

The order matters and the batch is atomic, so either the template and its binding both land or neither does.

A few details worth knowing:

- Slots are positional. Markup addresses its fields as `row[0]`, `item[1]` and so on, and the field map binds each slot to a data path. Do not bake values into the markup.
- Ask for a template by name before creating one. If `describeTemplates('person card')` returns it, reuse it.
- `column` binds one table column instead of the element itself, matched by `key`, and it comes with the warning above about hosted elements being the better answer.
- Passing an empty `template` clears the binding and its field map.
- Templates live in the view JSON, so saving the view persists them. Committing a batch also fires the template saved event, which is what a host mirroring the library into its own storage listens for.

## Mutation commands

| Command | What it does |
| --- | --- |
| `addElement` | Creates an element and places it. Pass `name` to make the command idempotent. |
| `upsertTemplate` | Creates or replaces a library template. Needs the `templates` capability. |
| `useTemplate` | Binds a library template to an element or a table column. Needs the `templates` capability. |
| `insertJson` | Inserts a whole subtree: elements keyed by name, which one is the root, and the layout under it. Renames colliding names unless `rename: false`. |
| `updateElement` | Patches an element body. `merge: false` replaces it instead. |
| `deleteElement` | Removes an element, its layout slot, and everything nested under it. |
| `moveElement` | Moves an element with its children to another parent, row or position. |
| `renameElement` | Renames an element and rewrites every reference to it, including expressions. |
| `duplicateElement` | Copies an element with its subtree. |
| `addRow`, `deleteRow` | Adds an empty row, or removes one. A non empty row needs `force: true`. |
| `addPage`, `deletePage`, `renamePage`, `updatePage` | Page level operations. A page carries an element entry of the same name, and these keep the two in step. |
| `setSettings`, `setHeader` | Patches view settings and the view header. |
| `upsertDataSource`, `deleteDataSource` | Data sources by name. |
| `upsertVariable`, `deleteVariable` | Runtime variables in `settings.variables`. |
| `upsertTrigger`, `deleteTrigger` | Triggers in `settings.triggers`. |
| `upsertRule`, `deleteRule` | Rules in `settings.rules`. |
| `upsertFragment`, `deleteFragment` | Fragments in `settings.fragments`. |
| `setProcess` | The process definition, or `null` to remove it. |
| `setLocalization` | Content translations for the view. |
| `replaceStructure` | Replaces the whole view JSON. |

## Action commands

| Command | What it does |
| --- | --- |
| `switchTab` | Moves the builder to another tab, preview included. |
| `focusElement` | Selects an element so its properties open in the sidebar. |
| `setData` | Sets working data. Values that belong to real elements go through the value pipeline, so expressions and conditions re-evaluate. |
| `validate` | Validates the current view against data and returns the issues. |
| `setLanguage` | Switches the active language and re-applies content translations. |
| `setUiTranslations` | Overrides built in control text such as select placeholders, per language. |
| `setTheme` | Theme mode, CSS variables, custom CSS, stylesheet urls, custom theme. |
| `saveTemplate`, `deleteTemplate` | Templates in the Templates tab. |
| `saveSidebarGroup`, `deleteSidebarGroup` | Reusable groups in the builder sidebar library. |
| `setTableSettings`, `setTableFilters` | Table column settings and filters. |
| `setRuntimeVariableContext` | External values that runtime variables can map from. |
| `reloadDataSource` | Re-runs a data source. |
| `undo`, `redo` | Steps the builder history. Warns when there is nothing to step to. |

## Two languages in one view

The structure itself holds the default language. Every other language lives in `localization.texts`, keyed by structure path.

```js
await api.execute([
  {
    op: 'setLocalization',
    defaultLanguage: 'en',
    languages: ['en', 'de'],
    texts: {
      de: {
        'header.label': 'Neue Person hinzufügen',
        'elements.firstName.label': 'Vorname',
        'elements.gender.options[0].label': 'Männlich',
      },
    },
  },
  {
    op: 'setUiTranslations',
    dictionaries: { de: { 'select.placeholder': 'Auswählen' } },
  },
  { op: 'setLanguage', language: 'de' },
]);
```

`setLocalization` covers the text you authored. `setUiTranslations` covers the control text the library ships, such as select placeholders and table labels.

::: warning Supply a full UI dictionary
The library ships an English UI dictionary only. Some call sites pass the translation key as their own fallback, which means a language with a partial dictionary can render raw keys instead of falling back to English. Provide the keys you need for any language you switch to.
:::

## Undo and audit

Each `execute()` call is bracketed with a history checkpoint, so a batch of twenty commands collapses into a single undo step no matter how many elements it touched. A person can revert an agent's whole change with one Ctrl+Z, and the `undo` and `redo` commands step the same history.

`getAuditLog()` returns every `execute()` call this session with its ops, outcome, applied count and the names it changed. The log is capped at 200 entries.

## What is checked, and what is not

The command layer checks the structure it can see: element types against the registry, property names against the property catalog, layout targets, name collisions, and cycles. It also checks the inside of the properties whose value is itself structured:

| Property | Checked |
| --- | --- |
| `options` | Must be an array, and every entry needs a `value`. |
| `validators` | Every entry needs a known `type`, and `custom` also needs a `condition`. |
| `events` | Every entry needs a known action `type`. |
| `columns`, `template` | Nested elements are checked for a known type, a name, and valid property names. |

Everything else in an element body passes through untouched, because the body is an open record and custom fields are legitimate. Unknown keys are reported as warnings, so read them.

## Known limits

`validate` runs on a freshly built copy of the structure and does not apply container visibility to children. A field inside a hidden panel is still reported as required, so do not use validation results to test whether a section is visible. Read the preview instead.

The exporter drops empty objects and arrays, so a command that writes `{ steps: [] }` leaves nothing behind. Write real content.

A structural change rebuilds the view and clears working data, so set data after your last mutation, not before.

---

## API service reference

Source: https://ngxviewbuilder.io/developers/api-service

# API service reference

`NgxViewBuilderApiService` is a root-provided façade. Inject it anywhere in the host app to read, mutate, and observe the active view. This page lists **every public method**; events are listed separately in the [Events reference](https://ngxviewbuilder.io/developers/events).

```ts
import { inject } from '@angular/core';
import { NgxViewBuilderApiService } from 'ngx-view-builder';

private api = inject(NgxViewBuilderApiService);
```

::: tip Scoped instances
When several runtime views render at once (e.g. a view inside a dialog), each gets a scoped child API. Data calls on the root service (`setData`, `getData`, `setValue`, table settings/filters) automatically delegate to the most recently created scoped child, so host code usually just talks to the root instance.
:::

## Structure & settings

| Method | Description |
| --- | --- |
| `getStructure(): IStructure \| null` | Returns the current view definition as plain JSON (the source snapshot if one was captured, otherwise serialized from the live model). |
| `getStructureModel(): IStructure \| null` | Returns the **live structure model** (signal-based class instances) instead of plain JSON. |
| `setStructure(structure: IStructure): void` | Replaces the whole view: rebuilds the model, syncs the builder, applies runtime-variable definitions, and re-runs init rules. |
| `updateStructure(updater: (s: IStructure) => void): boolean` | Mutates the structure in place and notifies/rebuilds. Changes flow into Undo history and `structureChanged`. |
| `getSettings(): IStructure['settings'] \| null` | Copy of the view-wide settings object. |
| `getSetting(key: string): unknown` | One setting by key; supports nested paths (`'header.title'`). |
| `setSetting(key: string, value: unknown): boolean` | Sets one setting (nested paths supported). No-op when the value is already equal. |
| `patchSettings(patch: Record<string, unknown>): boolean` | Sets several settings at once; keys may be nested paths. |
| `replaceSettings(settings): boolean` | Replaces the settings object wholesale. |
| `updateSettings(updater: (settings) => void): boolean` | Mutates settings via callback. |
| `notifyStructureChanged(): void` | Emits `onStructureChanged` manually (rarely needed, since mutation methods call it for you). |
| `captureStructureSource(structure): void` | Stores a structure snapshot used as the mutable source for `updateStructure`/`setSetting`. Called automatically by `setStructure`. |
| `clearCapturedStructureSource(): void` | Drops the captured snapshot. |
| `markPristine(): void` | Resets the dirty flag (e.g. right after saving). |
| `isDirty(): boolean` | Whether form data changed since load / last `markPristine()`. |

```ts
api.updateStructure((s) => {
  s.settings.header = { ...s.settings.header, title: 'Client onboarding' };
});
api.markPristine();
```

## Data & values

| Method | Description |
| --- | --- |
| `getData(): Record<string, unknown>` | Current form data snapshot. |
| `setData(data): void` | Replaces the form data. |
| `setElementsData(data): void` | Merges several values into the current data (partial update). |
| `setValue(dataPath, value): Promise<void>` | Sets one value by data path (`'addresses[0].city'`), running the same change pipeline as user input (expressions, dependencies, events). |
| `setElementValue(elementDataPath, value): Promise<void>` | Alias of `setValue` targeted at an element's data path. |
| `getElementValue(elementDataPath): unknown` | Reads a value by element data path. |
| `setElementErrors(nameOrPath, errors: string[]): boolean` | Attaches external error messages to an element (e.g. server-side validation). |
| `clearElementErrors(nameOrPath): boolean` | Removes external errors from an element. |
| `getElementErrors(nameOrPath): string[]` | Current external errors of an element. |

```ts
await api.setValue('client.country', 'LT');
api.setElementErrors('email', ['This e-mail is already registered']);
```

## Element lookup & manipulation

All lookup methods accept an element **name, data path, or schema path**.

| Method | Description |
| --- | --- |
| `getElement(nameOrPath): unknown` | Raw element model (untyped). |
| `getElementModel(nameOrPath): ElementBaseModel \| null` | Typed element model. |
| `getElementByDataPath(dataPath)` / `getElementBySchemaPath(schemaPath)` | Lookup by a specific path kind. |
| `getElementLookup(nameOrPath): INgxViewBuilderElementLookupResult \| null` | Full lookup record: name, paths, type, id, testId, model, and DOM node. |
| `getRenderedElements(): INgxViewBuilderElementLookupResult[]` | Lookup records for everything currently rendered. |
| `getElementName(nameOrPath)` / `getElementDataPath(...)` / `getElementSchemaPath(...)` / `getElementType(...)` / `getElementId(...)` / `getElementTestId(...)` | Convenience accessors for individual lookup fields. |
| `getElementProperty(nameOrPath, propertyKey): unknown` | Reads one element property (`'hidden'`, `'label'`, …). |
| `setElementProperty(nameOrPath, propertyKey, value): boolean` | Sets one element property and re-renders. |
| `setElementProperties(nameOrPath, props: Record<string, unknown>): boolean` | Sets several properties at once. |
| `updateElement(nameOrPath, updater: (el) => void): boolean` | Mutates the element model via callback. |
| `refreshElement(nameOrPath): boolean` | Forces the element to re-render. |

```ts
api.setElementProperty('email', 'disabled', true);
api.updateElement('summaryPanel', (el: any) => { el.title = 'Order summary'; });
```

## Render root & DOM access

| Method | Description |
| --- | --- |
| `registerRenderRoot(root: HTMLElement \| ShadowRoot \| null): void` | Registers the root node views render into (the runtime component does this for you). Also hosts toast styles. |
| `getRenderRoot(): HTMLElement \| ShadowRoot \| null` | The registered render root. |
| `getElementDom(nameOrPath): HTMLElement \| null` | DOM node of a rendered element. |
| `getElementDomById(id)` / `getElementDomByTestId(testId)` | DOM lookup by element id / test id. |
| `queryRenderDom(selector): HTMLElement \| null` | `querySelector` scoped to the render root. |
| `queryRenderDomAll(selector): HTMLElement[]` | `querySelectorAll` scoped to the render root. |

## Validation, completion & lifecycle

| Method | Description |
| --- | --- |
| `validateData(formJson, dataJson, options?): Promise<INgxViewBuilderValidationEvent>` | **Headless validation**: builds the structure, applies data, evaluates expressions and validators, and returns `{ isValid, issues[] }`, with no UI needed. See [Headless validation](https://ngxviewbuilder.io/developers/validator). |
| `showToast(payload: INgxViewBuilderToastPayload): void` | Shows a runtime toast (`title`, `message`, `variant`, `position`, `autoHideMs`, `icon`…). |
| `notifyValidationResult(isValid, issues): void` | Emits `onValidated`/`onValidating` and fires the `validated` platform trigger. Called by the runtime after UI validation. |
| `notifyComplete(isValid, data, issues): void` | Emits `onComplete` and the `completed` trigger. Called on Submit. |
| `notifySaveRequested(source?): void` | Emits `onSaveRequested` (`source`: `'header' \| 'api'`), a programmatic "Save" click. |
| `notifyBeforeRender(tab)` / `notifyRender(tab)` / `notifyAfterRender(tab)` | Emit the render-phase events and matching `beforeLoad`/`onLoad`/`afterLoad` triggers. The builder/runtime call these; hosts rarely need to. |
| `notifyTabChanged(tab): void` | Announces that the builder tab changed (emits `onTabChanged`). |
| `notifyCurrentPageChanged(pageIndex, pageName): void` | Announces a page switch (emits `onCurrentPageChanged` + `pageChanged` trigger). |
| `notifyDialogClosed(pageIndex, pageName, dialogTitle?, reason?): void` | Announces a dialog-mode close (emits `onDialogClosed` + `dialogClosed` trigger). |

```ts
const result = await api.validateData(structureJson, dataJson);
if (!result.isValid) console.table(result.issues);
```

## Data sources

| Method | Description |
| --- | --- |
| `reloadDataSource(elementNameOrPath, dataSourceName?, runtimeContext?): Promise<unknown \| null>` | Reloads the data source bound to an element (or a named source), with optional extra runtime context for placeholders. |
| `reloadElementDataSource(elementNameOrPath, runtimeContext?): Promise<unknown \| null>` | Shorthand: reload whatever source the element uses. |
| `reloadElementsByDataSource(dataSourceName, runtimeContext?): Promise<unknown[]>` | Reloads **every element** consuming the named source (falls back to the raw source when nothing consumes it). |
| `setDefaultDataSources(dataSources: IDataSource[], overwriteExisting?): void` | Injects host-defined sources into the current structure so every view can use them (by name; existing names kept unless `overwriteExisting`). |
| `setDataSourceTypeSettings(settings): void` | Enables optional source types in the builder UI: `{ enableWebsocket }`. |
| `getDataSourceTypeSettings(): INgxViewBuilderDataSourceTypeSettings` | Current source-type switches. |
| `setWebsocketAuthorizer(authorizer): void` | Puts this runtime instance's websocket connections under host control: rewrite the url or the subprotocols to carry credentials. Runs before every connection and reconnection, and may return a promise. See [WebSocket security](https://ngxviewbuilder.io/developers/data-sources#security-authorizing-the-connection). |

```ts
await api.reloadElementsByDataSource('loadClients');
api.setDefaultDataSources([{ name: 'countries', type: 'rest', url: '/api/countries' }]);
```

## Runtime variables

| Method | Description |
| --- | --- |
| `setRuntimeVariableDefinitions(definitions, replace = true): void` | Writes the variable definitions into `structure.settings` and (re)binds them. |
| `getRuntimeVariableDefinitions(): IRuntimeVariableDefinition[]` | Current definitions. |
| `setRuntimeVariableContext(values, merge = true): void` | Sets the **external context** available as `{__external.*}` in expressions. |
| `getRuntimeVariableContext(): Record<string, unknown>` | Current external context. |
| `clearRuntimeVariableContext(): void` | Clears the external context. |
| `configureRuntimeVariables({ mappings?, external?, mergeExternal? }): void` | One-call setup: definitions + external context. |

Details: [Runtime variables](https://ngxviewbuilder.io/developers/runtime-variables).

## Language, locale & translations

| Method | Description |
| --- | --- |
| `getLanguage(): string` | Active content/UI language. |
| `setLanguage(language): void` | Switches the language (UI dictionaries + structure `settings.language`; registers the language in localization if new). |
| `resolveHostLanguage(options?): INgxViewBuilderResolvedLanguage` | Resolves the best `{ language, locale }` from document/system language against `supportedLanguages` with a `fallbackLanguage`. |
| `applyHostLanguage(options?): INgxViewBuilderResolvedLanguage` | `resolveHostLanguage` + applies it (`setLanguage`, and `setApplicationLocale` unless `applyLocale: false`). |
| `startLanguageSync(options?): INgxViewBuilderLanguageSyncHandle` | Keeps the view in sync with the host page language: watches `<html lang>` and the browser `languagechange` event. Returns `{ refresh, stop }`. |
| `setApplicationLocale(locale): void` | Overrides the locale used for number/date formatting (e.g. `'de-DE'`), independent of the UI language. Until called, formatting falls back to the structure's `settings.language`, then the visitor's browser locale. |
| `getApplicationLocale(): string` | The explicitly-set application locale, or `''` if `setApplicationLocale` was never called (formatting is still active via the fallback chain above). |
| `setLocale(locale): void` | Convenience: sets the locale in both the application locale service and structure settings. |
| `setContentTranslations(translations, merge = true): void` | Adds content translations (`{ lt: { 'First name': 'Vardas' } }`) into the structure's localization. |
| `setUiDictionaries(dictionaries, merge = true): void` | Overrides builder/runtime UI dictionaries (see [UI translations](https://ngxviewbuilder.io/developers/ui-translations)). |
| `setUiTranslations(dictionaries, merge = true): void` | Alias of `setUiDictionaries`. |
| `translateUi(key, fallback?): string` | Translates a UI dictionary key. |
| `setPropertyHints(hints): void` | Overrides the help texts shown next to builder properties. |
| `setPropertyTypeHints(hints): void` | Overrides the help texts for property *types* (text, options, validators…). |

```ts
const handle = api.startLanguageSync({
  supportedLanguages: ['en', 'de'],
  fallbackLanguage: 'en',
});
// later: handle.stop();
```

## Theme & CSS

| Method | Description |
| --- | --- |
| `setThemeMode(theme: 'light' \| 'dark'): void` | Switches light/dark mode. |
| `getThemeMode(): 'light' \| 'dark' \| null` | Current mode (null until first set). |
| `setTheme(theme): void` | Accepts either a mode string (`'dark'`) or a CSS-variable map, one call for both cases. |
| `setCustomTheme(theme): void` | Registers a custom theme: `{ mergeWithDefaults?, shared?, light?, dark? }` variable maps. Re-applies variables for the active mode. |
| `getCustomTheme(): INgxViewBuilderCustomThemeDefinition \| null` | Current custom theme. |
| `setCssVariables(cssVariables): void` | Sets raw CSS custom properties (names are auto-prefixed with `--`). |
| `getCssVariables(): Record<string, string>` | Currently applied variables. |
| `setCustomCss(cssText): void` | Injects a raw CSS string into the render scope. |
| `getCustomCss(): string` | Current custom CSS. |
| `setCustomCssUrls(urls): void` | Loads external stylesheets into the render scope. |
| `getCustomCssUrls(): string[]` | Current stylesheet URLs. |

Details: [Theming & design tokens](https://ngxviewbuilder.io/developers/theming), [Custom CSS](https://ngxviewbuilder.io/developers/custom-css).

## Extensions & registration

Everything from [`provideNgxViewBuilderExtensions`](https://ngxviewbuilder.io/developers/extensions) is also callable imperatively:

| Method | Description |
| --- | --- |
| `registerExtensions(config): void` | Registers a whole extensions config (icons, dictionaries, elements, functions, properties…) at runtime. |
| `registerExtensionsAsync(config): Promise<void>` | Same, but awaits async icon directories. |
| `registerElementGroup(group): void` | Adds a custom group to the elements sidebar. |
| `registerCustomElement(definition): void` | Registers one [custom element](https://ngxviewbuilder.io/developers/custom-elements). |
| `registerCustomElements(definitions): void` | Registers several custom elements. |
| `registerElementProperties(type, properties, merge = true): void` | Adds/overrides builder properties for one element type ([custom properties](https://ngxviewbuilder.io/developers/custom-properties)). |
| `registerElementPropertiesMap(map, merge = true): void` | Properties for several types at once. |
| `registerGlobalElementProperties(properties, merge = true): void` | Properties added to **every** element type. |
| `registerExpressionFunction(fn)` / `registerExpressionFunctions(fns)` | Adds [custom expression functions](https://ngxviewbuilder.io/developers/custom-functions) to the expression language. |
| `registerSvgIcon(name, svgMarkup, overwrite = true): boolean` | Registers one inline [SVG icon](https://ngxviewbuilder.io/developers/icons). |
| `registerSvgIcons(icons, overwrite = true): string[]` | Registers a map of icons; returns the registered names. |
| `clearRegisteredSvgIcons(): void` | Removes all registered SVG icons. |
| `registerSvgIconDirectory(config): Promise<{ loaded, failed }>` | Loads a directory of `.svg` files by URL manifest. |
| `registerSvgIconDirectories(configs): Promise<...[]>` | Several directories at once. |
| `getTableHeaderCenterExtensions(): INgxViewBuilderCustomElementDefinition[]` | Custom elements flagged `allowInTableHeader` (usable in table header bars). |
| `registerTableCellElementType(type): void` | Adds an element type to the **Cell element** picker of a table column ([cell elements](https://ngxviewbuilder.io/creators/elements/tables#cell-elements)). Takes a type id or `{ type, label, order }`. Elements registered with `allowInTableCell: true` are added for you. |
| `registerTableCellElementTypes(types): void` | Several at once. |
| `removeTableCellElementType(type): void` | Takes one back out of the picker. |
| `getTableCellElementTypes(): ITableCellElementType[]` | Built-in cell element types plus everything registered by the host. |
| `attachBuilderAdapter(adapter): void` | Internal bridge between this service and the builder UI. The builder component attaches itself; hosts don't call this. |

## Templates & sidebar library

| Method | Description |
| --- | --- |
| `getTemplates(): ITemplateDefinition[]` | Templates of the current structure. |
| `setTemplates(templates, replace = true)` / `loadTemplates(...)` | Loads host-persisted templates into the builder (both names do the same; `loadTemplates` reads more naturally on startup). |
| `upsertTemplate(template)` / `saveTemplate(template, previousCode?)` | Adds or updates one template (`saveTemplate` also handles renames via `previousCode`). |
| `removeTemplate(name)` / `deleteTemplate(code)` | Deletes a template. |
| `setTemplateActionMap(map): void` | Maps template `action('...')` names to action handlers. |
| `registerTemplateActionDataSource(functionName, dataSourceName): void` | Binds a template function call (e.g. `loadData(id)`) to a data source. |
| `setSidebarTemplates(templates, replace = true)` / `setSidebarGroups(groups, replace = true)` / `loadSidebarGroups(groups, replace = true)` | Loads saved element-library items (the reusable elements/groups panel in the sidebar). |
| `saveSidebarGroup(group, previousCode?)` / `upsertSidebarGroup(group)` | Adds or updates a sidebar library item. |
| `deleteSidebarGroup(code)` / `removeSidebarGroup(code)` | Deletes a sidebar library item. |

Persistence pattern: listen to `onTemplateSaved` / `onSidebarGroupSaved` etc., store items wherever you want, and call `loadTemplates` / `loadSidebarGroups` on startup.

## Tables

| Method | Description |
| --- | --- |
| `setTableSettings(identifier, settings, options?): void` | Applies column settings (visibility/order/width) to a table. `options`: `tableName`, `elementName`, `source` (`'host' \| 'localStorage' \| 'dataSource' \| 'user'`). |
| `getTableSettings(identifier)` | Stored settings for a table. |
| `requestTableSettings(tableName, elementName, currentSettings): void` | Fires `onTableSettingsRequested` so the host can supply persisted settings. |
| `requestTableSettingsSave(tableName, elementName, settings): void` | Fires `onTableSettingsSaveRequested` so the host can persist settings. |
| `setTableFilters(identifier, filters, options?): void` | Applies active detailed-search filters. `options.source`: `'host' \| 'user' \| 'savedFilter'`; may carry the applied `savedFilter`. |
| `getTableFilters(identifier)` | Stored active filters. |
| `setTableSavedFilters(identifier, filters, options?): void` | Supplies the saved-filter list for a table. |
| `getTableSavedFilters(identifier)` | Stored saved filters. |
| `requestTableSavedFilters(tableName, elementName, currentFilters): void` | Fires `onTableSavedFiltersRequested` (host should respond with `setTableSavedFilters`). |
| `requestTableSavedFilterSave(tableName, elementName, filter, currentFilters): void` | Fires `onTableSavedFilterSaveRequested` so the host can persist one saved filter. |

Use together with the table events to persist per-user column layouts and saved filters.

## Builder UI control

| Method | Description |
| --- | --- |
| `switchToTab(tab): void` | Switches the builder to a tab (`'editor'`, `'preview'`, `'jsonEditor'`, `'formSettings'`, `'translations'`, `'variables'`, or a plugin tab code). |
| `requestTabChange(tab): void` | Emits `onTabChangeRequested`. The builder decides whether to honour it (useful when the host wraps tab navigation). |

---

## Architecture

Source: https://ngxviewbuilder.io/developers/architecture

# Architecture

## Package layout

```
ngx-view-builder
├─ ngx-view-builder-builder/    builder shell (tabs, sidebars, history)
├─ ngx-view-builder-runtime/    runtime shell (rendering + runtime services)
├─ ngx-view-builder/            unified host component
├─ ngx-view-builder-renderer/   low-level renderer
├─ ngx-view-builder-validator/  headless validation component
└─ core/
   ├─ builder/    builder-only: drag & drop, property editing, registries, datasets
   ├─ runtime/    runtime-only: rendering helpers, lazy element loading
   └─ shared/     both sides: models, elements, services, providers, expressions
```

Optional plugins are sibling npm packages (`ngx-view-builder-plugin-*`) that register builder tabs and feature packs through the extensions API. The core never auto-loads them.

## Key concepts

### Structure (`IStructure`)

The single JSON document that describes a view: `settings`, `pages` (layout as rows/columns), `elements` (flat map of element configs keyed by name), `dataSources`, and `localization`. The builder edits it; the runtime executes it. Reference: [Structure JSON](https://ngxviewbuilder.io/developers/structure-json).

### Element model

Every element type has a model class extending `ElementBaseModel` (name, label, type, widths, logic fields, value) and an Angular component that renders it. Built-ins live in `core/shared/elements`; you add your own via [custom elements](https://ngxviewbuilder.io/developers/custom-elements).

### Data

Runtime values live in a data object keyed by element name (nested for repeaters: `addresses[0].city`). Reads and writes flow through the data service, which fires value-change events that drive expression re-evaluation.

### Expressions

Logic strings (`visibleIf`, `expression`, …) are evaluated with [JEXL](https://github.com/TomFrost/Jexl). The expression service tracks dependencies between elements and re-evaluates dependents in topological order when a value changes. `{tokens}` compile to `getVal()` lookups; `row.`/`panel.` prefixes resolve against the element's position in repeaters.

### Host API

`NgxViewBuilderApiService` (root-provided) is the façade the host app uses: get/set structure and data, look up elements, react to 59 typed events, register extensions at runtime, control theming and language. Reference: [API service](https://ngxviewbuilder.io/developers/api-service).

## Render pipeline

1. Structure JSON is parsed into element models (`flatModelMap`).
2. Runtime variables resolve (route, external, constants, data sources).
3. Default values apply; expressions evaluate in dependency order.
4. Pages render rows → columns → element components (optionally lazily).
5. User input → data service → dependent expressions → validation → events.

## Builder vs. runtime boundary

Builder-side code (property sidebars, drag & drop, datasets) is never needed to *render* a view. If your end-user app only displays views, you ship the runtime component and pay no builder cost at runtime (lazy element rendering and preloading are tunable).

---

## Embedding the builder

Source: https://ngxviewbuilder.io/developers/builder-integration

# Embedding the builder

## Minimal setup

```ts
import { Component } from '@angular/core';
import { BuilderModel, IStructure, NgxViewBuilderBuilder } from 'ngx-view-builder';

@Component({
  selector: 'app-builder-page',
  imports: [NgxViewBuilderBuilder],
  template: `
    <ngx-view-builder-builder
      [model]="builderModel"
      (structureChanged)="onStructureChanged($event)"
      (saveRequested)="onSave()"
    />
  `,
})
export class BuilderPageComponent {
  builderModel = new BuilderModel();

  ngOnInit(): void {
    const saved = localStorage.getItem('my-view');
    if (saved) {
      this.builderModel.setJson(saved); // takes a JSON string
    }
  }

  onStructureChanged(structure: IStructure): void {
    localStorage.setItem('my-view', JSON.stringify(structure)); // autosave
  }

  onSave(): void {
    // user clicked Save in the builder header
  }
}
```

`BuilderModel` wraps the structure: `setJson(jsonString)`, `getJson(): IStructure`, plus `setDataJson`/`getDataJson` for preview data. An empty model starts with one blank page.

## Inputs

| Input | Type | Purpose |
| --- | --- | --- |
| `model` | `BuilderModel` | The structure being edited |
| `language` | `string` | Builder UI + content language |
| `theme` | `'light' \| 'dark'` | Color scheme |
| `runtimeSettings` | `INgxViewBuilderBuilderSettings` | The big config object (below) |
| `headerActions` | `INgxViewBuilderHeaderAction[]` | Extra header buttons |
| `hideSaveAction` | `boolean` | Hide the built-in Save |
| `hideHeaderTabs` | `boolean` | Chrome-less embedding |
| `activeTab` | tab code | Preselect a tab |
| `uiDictionaries` | `UiDictionaries` | Builder UI translations |
| `contentTranslations` | `Record<lang, Record<key,string>>` | Content translations |
| `cssVariables` | `Record<string,string>` | Token overrides |
| `viewportSettings` | `{ mobile?, tablet?, desktop? }` | Preview breakpoint widths |
| `externalConfig` / `externalConfigUrl` | config object / URL | Load host config as an object or JSON file |

## `runtimeSettings` highlights

```ts
readonly builderSettings: INgxViewBuilderBuilderSettings = {
  theme: 'light',
  language: 'en',
  builderPageDisplayMode: 'single',        // canvas shows one page at a time
  dataSources: { enableWebsocket: true },
  defaultDataSources: [...],               // sources every view gets
  runtimeVariableContext: { userRole: 'admin' },
  propertyHints: { name: 'Unique data key' },  // extra hint texts in the sidebar
  licenseKey: 'NVB-...',
};
```

## Outputs

| Output | Fires when |
| --- | --- |
| `structureChanged` | any edit changes the structure (autosave hook) |
| `saveRequested` | Save is clicked |
| `valueChanged` | a preview value changes |
| `tabChanged` / `languageChanged` | navigation events |
| `templateSaved` / `templateDeleted` / `templatesLoaded` | template library persistence (host-side storage) |
| `sidebarGroupSaved` / `sidebarGroupDeleted` / `sidebarGroupsLoaded` | element-library persistence |
| `headerActionRequested` | one of your `headerActions` was clicked |

## Custom header actions

```ts
readonly headerActions: INgxViewBuilderHeaderAction[] = [
  { id: 'save', label: 'Save', icon: 'save', tone: 'primary',
    onClick: () => this.saveToBackend() },
  { id: 'publish', label: 'Publish', onClick: () => this.publish() },
];
```

## Persisting templates and library items

When creators save templates or sidebar library groups, the builder emits events instead of assuming storage. Listen, persist wherever you like, and feed items back on startup:

```ts
ngAfterViewInit(): void {
  queueMicrotask(() => {
    this.api.loadTemplates(this.templatesFromBackend);
    this.api.loadSidebarGroups(this.groupsFromBackend);
  });
}
```

(`api` is [`NgxViewBuilderApiService`](https://ngxviewbuilder.io/developers/api-service).)

---

## Custom CSS

Source: https://ngxviewbuilder.io/developers/custom-css

# Custom CSS

Tokens ([Theming](https://ngxviewbuilder.io/developers/theming)) restyle the system consistently. Custom CSS is the escape hatch for anything more specific.

## Three injection points

| Where | Scope | Set by |
| --- | --- | --- |
| **Form settings → Custom CSS** | one view | creator (stored in `settings.customCss`) |
| `api.setCustomCss(css)` | current session | host |
| `api.setCustomCssUrls([url])` | current session, external files | host |

```ts
api.setCustomCss(`
  .nvb-panel { border-radius: 12px; }
  .invoice-total { font-weight: 700; font-size: 18px; }
`);

api.setCustomCssUrls(['/assets/builder-overrides.css']);
```

Declarative equivalents exist on `runtimeSettings` (`customCss`, `customCssUrls`) and in the structure itself.

## Targeting elements

- Every class the library renders starts with `nvb-`, so `nvb-field`, `nvb-panel`, `nvb-dropdown`. Anything without that prefix in a view belongs to you or to a template. Views written before 0.4.0 used unprefixed names and need updating.
- Custom CSS is injected without a cascade layer, so it beats the library's own rules without needing `!important`.
- Elements render with stable identity hooks, so prefer targeting by the element's id/test-id attributes or by classes you add in templates, rather than by internal DOM structure.
- Template HTML ([template library](https://ngxviewbuilder.io/creators/templates)) carries its own scoped CSS, so for card layouts prefer a template's CSS over global custom CSS.
- Custom-HTML elements can include class names that your custom CSS styles.

## Sanitisation

Injected CSS is passed through markup security processing. Keep it to plain rules; imports of arbitrary origins should go through `customCssUrls` where the host controls the list.

## Recommended layering

1. **Tokens** for colors, fonts, radii → whole-system consistency.
2. **Template CSS** for repeatable card/option layouts.
3. **View Custom CSS** for one-off tweaks a creator owns.
4. **Host CSS URLs** for org-wide overrides versioned with the app.

Track changes via `onCustomCssChanged` / `onCustomCssUrlsChanged`.

---

## Custom elements

Source: https://ngxviewbuilder.io/developers/custom-elements

# Custom elements

A custom element is three parts:

1. a **model** class extending `ElementBaseModel` holding the element's data/config fields,
2. a **component** that renders it (receives the model as an input),
3. a **registration** describing type, label, icon, sidebar group, and editable properties.

The library's own demo (`projects/test-app/src/app/demo/`) contains this exact example.

## 1. Model

```ts
import { ElementBaseModel } from 'ngx-view-builder';

export class NoteElementModel extends ElementBaseModel {
  text = '';
  variant: 'neutral' | 'info' | 'success' | 'warn' = 'warn';
  showEditButton = true;

  constructor(data?: Partial<NoteElementModel>) {
    super();
    this.type = 'noteCard' as any;
    this.label = 'Note card';
    this.width = '100%';
    if (data) Object.assign(this, data);
  }
}
```

Fields you declare here are persisted in the structure JSON and editable through the properties you register in step 3.

## 2. Component

```ts
import { ChangeDetectionStrategy, Component, computed, inject, input, signal } from '@angular/core';
import { NgxViewBuilderApiService, TemplateEngineService } from 'ngx-view-builder';
import { NoteElementModel } from './note-element.model';

@Component({
  selector: 'app-note-element',
  standalone: true,
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    <section class="note" [attr.data-variant]="model().variant">
      <div [innerHTML]="renderedText()"></div>
    </section>
  `,
})
export class NoteElementComponent {
  model = input.required<NoteElementModel>();   // the library passes the model in

  private templates = inject(TemplateEngineService);
  private api = inject(NgxViewBuilderApiService);
  private version = signal(0);

  readonly renderedText = computed(() => {
    this.version();
    return this.templates.renderTemplate(this.model().text ?? '', {
      element: this.model(),
    });
  });

  ngOnInit(): void {
    // re-render when form values change so {{placeholders}} stay live
    this.disposer = this.api.onValueChanged.add(() => this.version.update((v) => v + 1));
  }
  ngOnDestroy(): void { this.disposer?.(); }
  private disposer?: () => void;
}
```

Useful services inside element components:

| Service | For |
| --- | --- |
| `TemplateEngineService.renderTemplate(tpl, ctx)` | <code v-pre>{{placeholder}}</code> rendering |
| `ElementActionService.runActions(model, model.events, 'click', ctx)` | firing the element's configured actions |
| `NgxViewBuilderApiService` | values, events, everything |
| `EventService.afterPropertyChanged` | react to property edits in the builder |

For value-producing elements, write through the data service path (`api.setValue(model.dataPath, v)`) so expressions and validation react. Extending the input base classes in `core/shared/base-elements` gives you label/description/error chrome for free.

## 3. Registration

```ts
import { provideNgxViewBuilderExtensions } from 'ngx-view-builder';
import { NoteElementComponent } from './note-element.component';
import { NoteElementModel } from './note-element.model';

provideNgxViewBuilderExtensions({
  elementGroups: [{ code: 'custom', label: 'Custom', icon: 'extension', order: 90 }],
  elements: [{
    type: 'noteCard',            // unique type id (stored in JSON)
    label: 'Note card',          // sidebar caption
    icon: 'noteIcon',            // registered SVG icon name
    groupCode: 'custom',         // which sidebar group
    component: NoteElementComponent,
    model: NoteElementModel,
    properties: {
      name:  { label: 'Name',  type: 'text',     category: 'general' },
      label: { label: 'Label', type: 'text',     category: 'general' },
      text:  { label: 'Text',  type: 'textarea', category: 'general',
               hint: 'Supports {{firstName}}-style placeholders.' },
      variant: { label: 'Variant', type: 'select', category: 'general',
                 choices: [
                   { label: 'Info', value: 'info' },
                   { label: 'Success', value: 'success' },
                   { label: 'Warn', value: 'warn' },
                 ] },
      events: { label: 'Events', type: 'eventActions', category: 'events' },
      width:       { label: 'Width', type: 'size', category: 'design' },
      mobileWidth: { label: 'Mobile width', type: 'size', category: 'design' },
    },
  }],
});
```

`properties` drives the properties sidebar; each key maps a model field to an editor. Available editor `type`s and categories: [Custom properties](https://ngxviewbuilder.io/developers/custom-properties).

Optional registration fields: `aliases` (alternative type ids), `order` (position in group), `allowInTableHeader`, `allowInTableCell`.

## Using a custom element in a table cell

A table column whose type is `Element (control)` renders a real element in every row ([Cell elements](https://ngxviewbuilder.io/creators/elements/tables#cell-elements)). Add `allowInTableCell: true` and your element joins the built-in ones in that column's **Cell element** picker:

```ts
provideNgxViewBuilderExtensions({
  elements: [{
    type: 'ratingWidget',
    label: 'Rating',
    groupCode: 'custom',
    allowInTableCell: true,
    component: RatingWidgetComponent,
    model: RatingWidgetModel,
    properties: { /* … */ },
  }],
});
```

The same list is editable at runtime through the [API service](https://ngxviewbuilder.io/developers/api-service#extensions-registration), which is handy when the component is registered somewhere else, or when you want a built-in type back that the picker does not offer by default:

```ts
api.registerTableCellElementType({ type: 'ratingWidget', label: 'Rating', order: 2500 });
api.registerTableCellElementTypes(['autocomplete', 'listBox']);
api.removeTableCellElementType('fileUpload');
api.getTableCellElementTypes();          // built-ins plus everything you registered
```

### Reading the row

Nothing extra is needed for values and events: the library gives the cell model its row data path, mirrors the table's disabled/read-only state onto it, and merges the row into the runtime context of every action your element runs, so `{row.id}` and `{index}` resolve in the action editor.

If your component renders its own text template, resolve it against the row explicitly:

```ts
import { buildElementRowRuntimeContext, resolveElementRowScope } from 'ngx-view-builder';

const context = buildElementRowRuntimeContext(this.model(), (path) =>
  this.dataService.getValue(path),
);
// context.row, context.index, and every field of the row addressable by name
```

`resolveElementRowScope()` returns the raw scope (`rowPath`, `rowIndex`, `rowValue`, sibling names) when you need the pieces rather than a ready context. Both work for table cells, dynamic-table rows, and dynamic-panel rows, so writing against them once covers every repeater.

## Behaviour you get for free

Once registered, the element supports everything generic: drag & drop, responsive widths, `visibleIf`/`disableIf` logic, events (if you expose an `events` property and run them), translations of its text properties, and JSON round-tripping.

## Checklist

- [ ] `type` is unique and stable (it lives in saved JSON forever).
- [ ] Model defaults are sensible, so the element looks right when first dropped.
- [ ] Component is `OnPush` and reacts to value/property change events.
- [ ] Colors use the library's CSS variables so light/dark themes work ([Theming](https://ngxviewbuilder.io/developers/theming)).
- [ ] `properties` covers every model field creators should edit.

---

## Custom expression functions

Source: https://ngxviewbuilder.io/developers/custom-functions

# Custom expression functions

Creators write expressions like `isEmpty({email})`. You can add your own functions so they can write `vatAmount({netPrice})` or `isWorkday({date})`.

## Registration

```ts
import { provideNgxViewBuilderExtensions, IJexlFunctionRegistration } from 'ngx-view-builder';

const functions: IJexlFunctionRegistration[] = [
  {
    name: 'vatAmount',
    args: ['net', 'rate(optional)'],
    description: 'Net price + VAT (default 21%)',
    example: 'vatAmount({netPrice})',
    handler: (net: unknown, rate?: unknown) =>
      Number(net || 0) * (1 + (Number(rate) || 0.21)),
  },
  {
    name: 'formatIban',
    args: ['iban'],
    description: 'Groups an IBAN into blocks of 4',
    example: 'formatIban({accountNumber})',
    handler: (iban: unknown) =>
      String(iban ?? '').replace(/\s+/g, '').replace(/(.{4})/g, '$1 ').trim(),
  },
];

providers: [
  provideNgxViewBuilderExtensions({ expressionFunctions: functions }),
]
```

Or at runtime: `api.registerExpressionFunction(fn)` / `api.registerExpressionFunctions(fns)`.

## Registration fields

| Field | Purpose |
| --- | --- |
| `name` | The identifier used in expressions (re-registering a name replaces it) |
| `handler` | The implementation. May return a value or a `Promise` |
| `args` | Argument names, shown in the expression editor's help |
| `description` / `example` | Shown in the editor's function list. Write them well; creators rely on this |

Custom functions are flagged `isCustom` and appear alongside the [built-ins](https://ngxviewbuilder.io/creators/functions) in the editor's help panel.

## Async functions

Handlers may be async (the built-in `runDataSource` is). Note that *synchronous* evaluation contexts (e.g. inline default-value evaluation) skip expressions containing async functions, so keep functions used in `defaultValue` synchronous.

## Guidelines

- **Be forgiving with inputs.** Creators will pass empty strings and `null`, so coerce (`Number(x) || 0`, `String(x ?? '')`) instead of throwing. A thrown error silently fails the whole expression.
- **Return simple types** (string, number, boolean, array, plain object) that JSON-serialise cleanly.
- **Keep them pure** where possible. Functions with side effects (like `setElementProperty`) are powerful but make views harder to reason about.
- **Namespace by convention** if you register many: `acmeVat()`, `acmeRound()`. Function names are global.

---

## Custom properties

Source: https://ngxviewbuilder.io/developers/custom-properties

# Custom properties

Property definitions drive the properties sidebar. You can add new properties (persisted into the structure JSON automatically) or override built-in ones.

## Add to every element

```ts
provideNgxViewBuilderExtensions({
  globalProperties: {
    trackingId: {
      label: 'Tracking ID',
      type: 'text',
      category: 'general',
      hint: 'Analytics identifier rendered as data-tracking-id.',
    },
  },
});
```

## Add or override per element type

```ts
provideNgxViewBuilderExtensions({
  elementProperties: {
    button: {                       // element type
      analyticsEvent: {             // new property
        label: 'Analytics event', type: 'text', category: 'general',
      },
      label: { hidden: true },      // hide a built-in property
    },
  },
});
```

Runtime equivalents: `api.registerElementProperties(type, props)`, `api.registerGlobalElementProperties(props)`, `api.registerElementPropertiesMap(map)`.

## Property definition fields

| Field | Purpose |
| --- | --- |
| `label` | Caption in the sidebar |
| `type` | Which editor renders it (table below) |
| `category` | Sidebar section: `general`, `texts`, `dataSet`, `options`, `columns`, `restrictions`, `validators`, `logic`, `events`, `design` |
| `order` | Position within the category |
| `hint` | Help text under the editor |
| `choices` | Options for `select`-style editors (`{ label, value }[]`) |
| `hiddenIf` | Expression over sibling properties that hides the editor conditionally (e.g. `!maskType \|\| maskType.value != "custom"`) |
| `applyConditions` | Other property keys to re-evaluate when this one changes |
| `section` | Optional sub-grouping inside a category |
| `component` | A custom Angular editor component (fully custom editors) |
| `loadChoices` | Async choice loader `(properties) => Promise<ChoiceModel[]>` |

## Editor types

The `type` string picks one of the built-in attribute editors:

| Type | Editor |
| --- | --- |
| `text` / `textarea` / `number` | plain inputs |
| `checkbox` | boolean toggle |
| `select` | dropdown (uses `choices`) |
| `color` | color picker |
| `size` | size with units (px/%/…) |
| `padding` | four-sided padding editor |
| `options` | option-list editor (label/value rows) |
| `validators` | validators rule editor |
| `eventActions` | events & actions editor |
| `sourceMapper` | data source binding editor |
| `variantRules` | conditional variant rules |
| `columns` / `tableColumns` | column schema editors |
| `htmlCode` | code editor |
| `file` | file picker |
| `checklist`, `logic`, `templateName`, `sourceName`, and others | specialised editors used by built-in elements |

For anything unique, supply your own `component`. It receives the property and element context and writes the value back like any built-in editor.

## How values reach the element

A property with key `analyticsEvent` is stored on the element JSON as `"analyticsEvent": ...` and appears on the model at runtime (`model().analyticsEvent` in your component, `getElementProperty(name, 'analyticsEvent')` from the host).

## Property hints

To only *clarify* existing properties (no structural change), set hint texts from the host:

```ts
api.setPropertyHints({ name: 'Unique key, becomes the data field name.' });
api.setPropertyTypeHints({ sourceMapper: 'Binds this element to a data source.' });
```

---

## Custom validator types

Source: https://ngxviewbuilder.io/developers/custom-validators

# Custom validator types

The built-in validator types (`required`, `minLength`, `pattern`, `email`, …) are deliberately generic. Anything country-specific a personal code, a tax ID, a phone number, a bank account differs per market, so those rules live in _your_ application, not in the library.

A registered type appears in the builder's **Type** list next to the built-ins, and from then on a creator picks _LT personal code_ the same way they pick _email_. No regular expression, no expression language.

## Registration

```ts
import {
  provideNgxViewBuilderExtensions,
  INgxViewBuilderValidatorTypeRegistration,
} from "ngx-view-builder";

const validatorTypes: INgxViewBuilderValidatorTypeRegistration[] = [
  {
    type: "ltPersonalCode",
    label: "LT personal code",
    defaultMessage: "Invalid personal code",
    appliesTo: ["text"],
    isValid: ({ value }) => isValidLtPersonalCode(String(value ?? "")),
  },
  {
    type: "minWords",
    label: "Minimum words",
    defaultMessage: "Please write at least {value} words",
    hasValue: true,
    valueLabel: "Words",
    valuePlaceholder: "20",
    appliesTo: ["textarea"],
    isValid: ({ value, validatorValue }) =>
      String(value ?? "")
        .trim()
        .split(/\s+/)
        .filter(Boolean).length >= Number(validatorValue || 0),
  },
];

providers: [provideNgxViewBuilderExtensions({ validatorTypes })];
```

Or at runtime: `api.registerValidatorType(definition)` / `api.registerValidatorTypes(definitions)`. Register early in an `APP_INITIALIZER` or the host component's `ngOnInit` so the types exist before a view is rendered.

## Registration fields

| Field                             | Purpose                                                                                                                                                      |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `type`                            | The identifier stored in the view JSON. Lower-cased on save, so `ltPersonalCode` and `ltpersonalcode` are the same rule. Built-in names cannot be overridden |
| `isValid`                         | The check. **Returns `true` when the value is valid** the opposite polarity of a `custom` rule's condition. May return a `Promise`                           |
| `label`                           | Text shown in the Type list (defaults to `type`)                                                                                                             |
| `defaultMessage`                  | Pre-filled into the rule's _Error message_ field when a creator picks the type, and used at runtime when the message is left empty                           |
| `hasValue`                        | Set `true` when the rule needs a setting, which shows the **Value** input (like `minLength`)                                                                 |
| `valueLabel` / `valuePlaceholder` | Label and placeholder for that Value input                                                                                                                   |
| `appliesTo`                       | Element types the rule is offered for, e.g. `['text', 'textarea']`. Omit to offer it everywhere                                                              |
| `validateEmpty`                   | By default an empty value passes (matching `email` and `pattern`) so the rule stays optional; set `true` to check empty values too                           |

::: warning Polarity
`isValid` returns **true = valid**. A `custom` rule's _Condition_ field is the other way round it describes the **error** and fires while it is true. The names match the behaviour in both cases; do not copy a condition expression into an `isValid` handler unchanged.
:::

## What `isValid` receives

```ts
isValid: ({ value, validatorValue, validator, element, data }) =>
  boolean | Promise<boolean>;
```

| Field            | Contents                                                                   |
| ---------------- | -------------------------------------------------------------------------- |
| `value`          | The current value of the field being validated                             |
| `validatorValue` | The rule's **Value** setting (present when `hasValue` is on)               |
| `validator`      | The whole rule object (`type`, `message`, `value`, `condition`, `applyIf`) |
| `element`        | The element model being validated                                          |
| `data`           | The full runtime data object, for rules that depend on other fields        |

Everything else keeps working as usual: the creator can still set a per-rule error message, translate it, and guard the rule with **Apply if**.

## Async rules

`isValid` may return a `Promise`, which makes server-side checks possible (verifying a VAT number against a registry, for example):

```ts
{
  type: 'vatNumber',
  label: 'VAT number',
  defaultMessage: 'This VAT number was not found',
  isValid: async ({ value }) => {
    const response = await fetch(`/api/vat/${encodeURIComponent(String(value ?? ''))}`);
    return response.ok;
  },
}
```

If you do this, set the element's **Validation execution mode** to `onBlur` (the default) rather than `onInput`, or every keystroke becomes a request.

## Portability

The rule _definition_ lives in your application; the view JSON only stores the name:

```json
{ "type": "ltPersonalCode", "message": "Invalid personal code" }
```

That keeps views portable, but it also means a view using `ltPersonalCode` needs that type registered wherever it is rendered. In an application where it is not registered the rule is **skipped** (the field validates as if the rule were absent) and a warning is logged to the console once per unknown type. The builder still shows the rule and marks it `(not registered)` instead of silently rewriting it, so opening a view in another app never destroys the rule.

If several applications share views, register the shared types from one small library rather than copy-pasting the handlers.

## Guidelines

- **Be forgiving with input.** Creators and users will hand you `null`, `''`, and stray whitespace. Coerce (`String(value ?? '').trim()`) instead of throwing a handler that throws is treated as invalid and logs an error.
- **Keep the message useful.** `Company code must be 9 digits` beats `Invalid value`. See [good error messages](https://ngxviewbuilder.io/creators/validation#good-error-messages).
- **Namespace country rules** by prefix (`ltPersonalCode`, `lvPersonalCode`) so the Type list stays readable as it grows.
- **Do not re-implement the built-ins.** Length, range, pattern, and email are already there; a custom type is for logic those cannot express.

## Related

- [Validation](https://ngxviewbuilder.io/creators/validation) how creators use validators, including `custom` conditions and _Apply if_
- [Custom expression functions](https://ngxviewbuilder.io/developers/custom-functions) when the rule is better expressed as an expression creators can reuse
- [Headless validation](https://ngxviewbuilder.io/developers/validator) running the same rules outside the UI

---

## Data source integration

Source: https://ngxviewbuilder.io/developers/data-sources

# Data source integration

Creators configure data sources inside views ([creator guide](https://ngxviewbuilder.io/creators/data-sources)). This page covers what the host application controls.

## Requests go through Angular HttpClient

REST sources use the host's `HttpClient`, so your existing **interceptors apply automatically**: auth tokens, tenant headers, error mapping, logging. That's the recommended way to secure view-issued requests.

```ts
// app.config.ts
provideHttpClient(withInterceptors([authInterceptor, apiPrefixInterceptor])),
```

An `apiPrefix` interceptor also lets creators use short relative URLs (`/clients`) while the host decides the actual host per environment.

## Table: server-side paging & filtering (`TABLE-POST`)

This only applies to a **`table`** element with **Lazy load** on (creator-side property, `tableDataSourceName`). With Lazy load off, the table's data source is a plain source that must return every row in one response. The table paginates/sorts/filters in the browser and none of the contract below applies.

With Lazy load on, set the source's **Method** to the literal string **`TABLE-POST`** in the DataSources tab. NGX View Builder sends a real `POST` over the wire, but first merges the current page/sort/search state into the request body automatically, so you don't write this merging logic yourself.

- If the source's **Request body** is left empty, the body sent to your endpoint is exactly the object below.
- If you *do* configure a body template (e.g. `{"tenantId":"{el1}"}`), your fields are kept and `pagingParams`/`params`/`extendedParams` are added on top.

### Request body shape

```json
{
  "pagingParams": {
    "cnt": null,
    "orderClause": "lastName DESC",
    "pageSize": 25,
    "skipRows": 50,
    "totalCountUsed": false
  },
  "params": [
    ["tenantId", "42"]
  ],
  "extendedParams": [
    { "paramName": "quickSearch", "paramValue": { "condition": "%-%", "value": "acme", "upperLower": "caseInsensitiveLatin" } },
    { "paramName": "status", "paramValue": { "condition": "=", "value": "active" } },
    { "paramName": "createdAt", "paramValue": { "condition": ">=", "value": "2026-01-01" } }
  ]
}
```

- **`pagingParams`**: `pageSize` and `skipRows` (offset, not page number) drive the page window; `orderClause` is a ready-to-use string like `"lastName DESC"` (column key + `ASC`/`DESC`, taken from whichever column is actively sorted, or the **Order clause** property otherwise). `cnt` and `totalCountUsed` are always sent as `null`/`false`, because the frontend never fills them in; your endpoint owns computing the total.
- **`params`**: an array of `[paramName, value]` **tuples** (not `{name, value}` objects), one per row configured in the element's **Request params** property (up to 5). Values may resolve `{path}`/`{{expression}}` tokens from the form before sending.
- **`extendedParams`**: one entry per active search/filter, each `{ paramName, paramValue: { condition, value, upperLower? } }`:
  - The **quick search** box (if enabled) always contributes one entry; `paramName` is the **Quick search param name** property (default `quickSearch`).
  - **Detailed search** contributes one entry per column that has an active filter; `paramName` is that column's `key`. `value` is already typed for you: a real `boolean`/`number` for boolean/number columns, an array of strings for multi-select filters, otherwise a string.

**Search/filter `condition` values** (same vocabulary for quick search and every per-column filter):

| Value | Meaning (text columns) | Meaning (number/date columns) |
| --- | --- | --- |
| `%-%` | contains | - |
| `!%-%` | does not contain | - |
| `%-` | starts with | - |
| `-%` | ends with | - |
| `=` | equals | equals |
| `!=` | not equals | not equals |
| `>` | - | greater than / after |
| `>=` | - | on/after |
| `<` | - | less than / before |
| `<=` | - | on/before |

### Response shape your endpoint must return

No wrapper is mandatory; the table tries several common shapes automatically before giving up:

```json
{ "items": [ { "id": 101, "lastName": "Smith", "status": "active" } ], "total": 187 }
```

- **Rows**: the whole response if it's already an array; otherwise the **Items path** property if set (e.g. `data.items`); otherwise the first of `items`, `data`, `results`, `rows` that is itself an array.
- **Total** (only read when Lazy load is on): the **Total path** property if set (e.g. `meta.total`); otherwise the first present of `total`, `totalCount`, `totalRecords`, `count`, `cnt`, `paging.total`, `paging.totalCount`, `paging.totalRecords`, `paging.count`, `paging.cnt`. **Total path is optional**: leave it empty, use any of those key names, and it's picked up automatically. If nothing matches, the total silently falls back to the current page's row count (pagination will look "stuck", so set one of the recognized keys, or Total path, to avoid that).

So `{ "data": [...], "totalCount": 187 }` or `{ "results": [...], "paging": { "total": 187 } }` work with zero extra configuration.

### Row actions, inline edit, and export are not part of this contract

- **Row/selection/header actions** and **inline edit save** go through the same generic [action → data source](https://ngxviewbuilder.io/creators/events-actions) mechanism as any button; there is no table-specific request shape for them. What reaches your endpoint is whatever URL/body you configured on that action's data source, populated from the action's own runtime context: a row action sees `row`, `selectedRows`, `selectedKeys`; a bulk selection action sees `rows`/`items` for every selected record; inline edit save sees `row` (the full edited row) **and** `changedValues`, a flat `{ "status": "active" }`-style object containing only the columns that actually changed, handy for a PATCH-style endpoint.
- **CSV/Excel/PDF export happens entirely in the browser.** There is no server-side export endpoint to implement; "export all" re-issues the same table request with a much larger `pagingParams.pageSize` (the **Export all page size** property, default 10000) to fetch every matching row, then builds the file client-side.

## File upload requests

`fileUpload` can bind up to three independent data sources (**Upload data source**, **Download data source**, **Delete data source**), each a normal REST source. If **Upload data source** is left empty, files never leave the browser: only local metadata (`name`/`size`/`type`/`lastModified`) is kept as the field's value, which is a common foot-gun for a field that otherwise looks "filled in".

### Upload

Always sent as raw `multipart/form-data` with exactly **one** field, never JSON, never base64:

```
POST {upload data source URL}
Content-Type: multipart/form-data; boundary=...

------WebKitFormBoundary...
Content-Disposition: form-data; name="file"; filename="resume.pdf"
Content-Type: application/pdf

<binary bytes>
------WebKitFormBoundary...--
```

- The field name is the **Upload form field name** property (default `file`).
- Any **Request body** template configured on the upload source is **ignored**; only `{placeholder}` tokens in the **URL** are resolved (against `value`, `file`, `fileName`, `fileType`, `fileSize`, plus the usual form context).
- With **Max files** > 1, each file is uploaded as its **own sequential request**. There is no multi-file batch endpoint and no chunked or resumable upload.
- There is no upload-progress percentage available, only a pending/ready/error state per file.

Your endpoint should respond with an object describing the stored file:

```json
{ "key": "9f2c1e6a-...", "name": "resume.pdf", "size": 245678, "contentType": "application/pdf" }
```

Field names are configurable via the **File key / name / size / type field** properties (defaults shown above: `key`, `name`, `size`, `contentType`); if your backend already uses different keys (including the older `fil_key`/`fil_name`/`fil_size`/`fil_content_type` convention from earlier versions), the parser also recognizes common aliases automatically (`fileKey`/`filKey`/`fil_key`/`id`/`fileId`/`uuid` for the key, `fileName`/`fil_name` for the name, `mimeType`/`fil_content_type` for the type, `fil_size` for the size). The response can also come wrapped as `{ "data": {...} } `/`{ "items": [...] }`/etc., and the first record found is used.

**The entire response object is stored verbatim as the field's value** (or an array of responses when **Max files** > 1). There is never a file-bytes/base64 field in the form's own JSON result, only whatever metadata your endpoint returned.

### Download

Defaults to `GET`. If the source has no configured **Request body**, the fallback request body is `{ "<file key field>": "<fileKey>" }` (only sent for non-`GET` methods). Your response can be **either**:

- a raw binary stream (any `Content-Type` other than JSON, or an `attachment` `Content-Disposition`), or
- a small JSON envelope such as `{ "url": "https://cdn.example.com/files/abc123.pdf" }` or `{ "content": "<base64>", "contentType": "application/pdf" }`.

Both are handled without extra configuration.

### Delete

Defaults to `DELETE`. If no **Request body** template is configured, the fallback body sends the file key under every common alias at once, so it matches almost any backend field naming without extra setup:

```json
{ "key": "9f2c1e6a-...", "fileKey": "9f2c1e6a-...", "filKey": "9f2c1e6a-...", "fil_key": "9f2c1e6a-...", "id": "9f2c1e6a-...", "fileId": "9f2c1e6a-...", "uuid": "9f2c1e6a-..." }
```

Any 2xx response counts as success; the response body itself is ignored.

## Default data sources

Give every view a base catalogue of sources so creators don't retype URLs:

```ts
this.api.setDefaultDataSources([
  { name: 'loadCountries', title: 'Countries', type: 'rest',
    params: { url: '/api/countries', method: 'GET' } },
  { name: 'saveForm', title: 'Save form', type: 'rest',
    params: { url: '/api/forms', method: 'POST' } },
]);
```

Or via `runtimeSettings.defaultDataSources` / `dataSourceDefinitions`.

## Observability

Subscribe to the data source events for global loading states and error handling:

```ts
api.onDataSourceLoading.add(({ sourceName }) => this.spinner.show(sourceName));
api.onDataSourceLoaded.add(({ sourceName, durationMs }) => this.spinner.hide(sourceName));
api.onDataSourceLoadFailed.add(({ sourceName, errorMessage }) => {
  this.spinner.hide(sourceName);
  this.api.showToast({ title: 'Load failed', message: errorMessage, variant: 'error' });
});
```

## Programmatic reloads

```ts
await api.reloadDataSource('loadClients');          // by source name
await api.reloadElementDataSource('clientsTable');  // one element's binding
await api.reloadElementsByDataSource('loadClients');// every element using it
```

Call these after host-side mutations so tables and dropdowns reflect new data.

## Caching & skipped requests

- Responses are cached per request signature (URL + method + payload); identical concurrent requests are coalesced. Force fresh data with the reload APIs.
- A request whose URL/body still contains an **unresolved `{placeholder}`** is skipped and yields empty data. That's by design (dependent dropdowns before their parent has a value).

## WebSocket sources

A `websocket` source is a live connection rather than a request. The runtime opens it the first time anything on the page uses that source, keeps it open, and pushes every message into the bound elements and variables. Creators configure it in the [DataSources tab](https://ngxviewbuilder.io/creators/data-sources#websocket); this section is about what the host controls.

Enable the type in the builder UI first, otherwise creators cannot pick it:

```ts
api.setDataSourceTypeSettings({ enableWebsocket: true });
```

The runtime is not gated by that flag. A stored view containing a websocket source connects even if the builder never offered the type.

### Your server side

Plain WebSocket, the kind `new WebSocket(url)` speaks. Not STOMP, not SockJS. Text frames that contain JSON are parsed automatically, anything else is delivered as-is.

### One connection per endpoint

Connections are shared by url, subprotocols, and handshake message. Two sources pointing at the same endpoint with different `messagePath` values use one socket, and so do two elements reading the same source. The socket closes when the last subscriber goes away.

This matters for capacity planning: the number of connections your server sees is the number of distinct endpoints your views use, not the number of bound elements.

### Reconnecting

A closed or failed connection is retried automatically with a growing delay of 1s, 2s, 5s, 10s, then 30s for as long as it takes. The delay resets after a successful connection. Subscribers stay attached throughout, so a view recovers on its own after a deploy or a network blip, with no page refresh.

Each attempt is authorized again, which is what makes token refresh possible.

### Connection status

The runtime publishes each source's state under `__socket.<sourceName>`, which creators can bind to and expressions can read:

```
{__socket.liveFeed.connected}       // boolean
{__socket.liveFeed.lastMessageAt}   // epoch milliseconds
{__socket.liveFeed.reconnects}      // how many times it came back
{__socket.liveFeed.url}             // endpoint actually connected to
```

Use it to show an offline banner. A frozen live view that still looks live is the failure mode worth designing against.

### Security: authorizing the connection

REST sources go through Angular `HttpClient`, so your interceptors add tokens automatically. **A browser `WebSocket` cannot send headers**, which means nothing you installed for HTTP applies to it. That leaves two ways to authenticate, and both are the host's decision: a query parameter on the url, or a subprotocol entry.

Register an authorizer once, at app level, and every runtime instance uses it:

```ts
// app.config.ts
provideNgxViewBuilderProjectLayer({
  id: 'websocket-security',
  authorizeWebsocket: async ({ sourceName, url, protocols }) => {
    const token = await auth.getFreshToken();
    return { url: `${url}${url.includes('?') ? '&' : '?'}token=${encodeURIComponent(token)}` };
  },
});
```

The hook runs before every connection and before every reconnection, and it may return a promise, so an expired token can be refreshed before the socket is opened again. Return `{ url }`, `{ protocols }`, both, or nothing at all to connect exactly as configured.

Subprotocols are the alternative when you would rather keep tokens out of urls:

```ts
authorizeWebsocket: async ({ protocols }) => ({
  protocols: [...protocols, `auth.${await auth.getFreshToken()}`],
});
```

Your server reads it from the `Sec-WebSocket-Protocol` header during the handshake and must echo back one of the offered values.

::: warning A token in a url is a token in a log
Query strings end up in access logs, proxy logs, and referrer headers. Prefer short-lived tokens issued for this purpose, validate them at the handshake, and reject unauthorized handshakes with a 401 before the connection is established.
:::

`NgxViewBuilderApiService.setWebsocketAuthorizer()` sets the same hook on a single runtime instance, which is useful when one embedded view needs different credentials than the rest of the app. An authorizer set that way wins over the project layer for that instance.

### Proxies and timeouts

Sockets die for reasons that have nothing to do with your code. Load balancers and reverse proxies need WebSocket upgrade enabled on the route, and their idle timeout decides how long a quiet connection survives. A server-side heartbeat keeps long-lived views connected instead of relying on the reconnect loop.

## Mock data in development

Use an interceptor to fake endpoints while the backend is in flight. The demo app's `demo-data.interceptor.ts` in `projects/test-app` is a working example that pattern-matches URLs and returns canned JSON.

---

## Events reference

Source: https://ngxviewbuilder.io/developers/events

# Events reference

All events live on `NgxViewBuilderApiService` and share a lightweight emitter API:

```ts
const sub = api.onValueChanged.subscribe((e) => { ... });  // {unsubscribe()}
const dispose = api.onValueChanged.add(handler);           // returns disposer
api.onValueChanged.once(handler);
api.onValueChanged.remove(handler);
```

These are library emitters (not RxJS): `subscribe` returns `{ unsubscribe, closed }`. Always detach in `ngOnDestroy`.

::: tip Events work the same in the runtime and renderer
`<ngx-view-builder-runtime>` and `<ngx-view-builder-renderer>` run on an isolated internal API instance, but every event they fire is automatically forwarded to the root `NgxViewBuilderApiService` your application injects, so the subscriptions below work identically on builder and runtime pages. (If you embed several runtimes on one page, use the payload's `elementName`/`elementDataPath` to tell them apart, or bridge instances yourself with the exported `bridgeNgxViewBuilderApiEvents(source, target)`.)
:::

## Values & data

| Event | Fires |
| --- | --- |
| `onValueChanging` / `onValueChanged` | a field value is about to change / changed (`dataPath`, `newValue`, `oldValue`, `sender`, `trigger`) |
| `onElementValueChanging` / `onElementValueChanged` | same, enriched with element lookup + an `api` handle for the element |
| `onElementPropertyChanging` / `onElementPropertyChanged` | an element property (label, hidden, disabled…) changes |

```ts
api.onElementValueChanged.add(({ elementDataPath, newValue, api: el }) => {
  if (elementDataPath === 'country') {
    void el.reloadDataSource('loadCities');
  }
});
```

## Validation & completion

| Event | Fires |
| --- | --- |
| `onValidating` / `onValidated` | validation runs / finishes (`isValid`, `issues[]`) |
| `onComplete` | the form completes (Submit): `{ isValid, data, issues }` |
| `onSaveRequested` | Save is requested from header or API |

## Structure & navigation

| Event | Fires |
| --- | --- |
| `onStructureChanged` | the structure was edited |
| `onCurrentPageChanged` | the visible page changed |
| `onDialogClosed` | a dialog-mode view closed (`reason: 'close-button' \| 'api'`) |
| `onTabChanged` / `onTabChangeRequested` | builder tab navigation |
| `onLanguageChanged` | active language switched |

## Rendering

| Event | Fires |
| --- | --- |
| `onBeforeRender` / `onRender` / `onAfterRender` | view render phases (with render root) |
| `onElementRender` / `onElementAfterRender` | per-element render, with model + DOM handles |

Use these for DOM-level integrations (tooltips, analytics attributes, measuring).

## Element interactions

| Event | Fires |
| --- | --- |
| `onDynamicTableRowAdded` / `onDynamicTableRowRemoved` | a `dynamicTable` row was added / removed (`elementName`, `rowIndex`, `row`, `rows`, `total`) |
| `onDynamicPanelItemAdded` / `onDynamicPanelItemRemoved` | a `dynamicPanel` item was added / removed (same payload shape) |
| `onFileUploadFilesAdded` / `onFileUploadFileRemoved` | files were attached / a file was removed on a `fileUpload` (`files`, `addedFiles` / `removedFile`, `removedIndex`) |
| `onElementTabChanged` | the active tab of a `tabs` / `tabsPro` element changed (`previousTabValue`, `tabValue`, `tabIndex`) |
| `onAccordionItemToggled` | an `accordion` section expanded or collapsed (`itemIndex`, `itemValue`, `expanded`) |

All payloads carry `elementName`, `elementDataPath`, the element model, and a `timestamp`, so one subscription can serve many elements:

```ts
api.onDynamicTableRowAdded.add(({ elementName, rowIndex, total }) => {
  if (elementName === 'familyMembers' && total >= 5) {
    api.showToast({ title: 'Limit', message: 'Max 5 members', variant: 'warning' });
  }
});

api.onDynamicPanelItemRemoved.add(({ elementDataPath, row }) => {
  this.audit.log('panel item removed', elementDataPath, row);
});
```

## Data sources

| Event | Fires |
| --- | --- |
| `onDataSourceLoading` | request started |
| `onDataSourceLoaded` | success (`result`, `durationMs`, `fromCache`) |
| `onDataSourceLoadFailed` | failure (`error`, `errorMessage`) |
| `onDataSourceReloaded` | explicit reload happened |

Perfect for global spinners and error toasts:

```ts
api.onDataSourceLoadFailed.add(({ sourceName, errorMessage }) =>
  api.showToast({ title: sourceName, message: errorMessage, variant: 'error' }));
```

## Appearance & configuration

| Event | Fires |
| --- | --- |
| `onThemeModeChanged` / `onCustomThemeChanged` | theme switches |
| `onCssVariablesChanged` / `onCustomCssChanged` / `onCustomCssUrlsChanged` | style updates |

## Templates & sidebar library

| Event | Fires |
| --- | --- |
| `onTemplateSaved` / `onTemplateDeleted` / `onTemplatesLoaded` | template persistence hooks |
| `onSidebarTemplateSaved`, `onSidebarGroupSaved` / `onSidebarGroupDeleted` / `onSidebarGroupsLoaded` | element-library hooks |

## Tables

| Event | Fires |
| --- | --- |
| `onTableSettingsChanged` / `Applied` / `Requested` / `SaveRequested` | column layout lifecycle |
| `onTableFiltersChanged` / `Applied` | active filters |
| `onTableSavedFiltersChanged` / `Requested`, `onTableSavedFilterSaveRequested` | saved filter sets |

## Automation (plugins)

| Event | Fires |
| --- | --- |
| `onTriggerHandling` / `onTriggerHandled` | platform triggers execute |
| `onRuleEvaluating` / `onRuleEvaluated` | rules engine runs (`executedBranch`) |

## Example: full save pipeline

```ts
ngOnInit(): void {
  this.disposers.push(
    this.api.onComplete.add(async ({ isValid, data }) => {
      if (!isValid) return;
      const saved = await firstValueFrom(this.http.post('/api/forms', data));
      this.api.showToast({ title: 'Saved', variant: 'success' });
    }),
    this.api.onDataSourceLoadFailed.add((e) =>
      this.logger.error('DS failed', e.sourceName, e.errorMessage)),
  );
}

ngOnDestroy(): void {
  this.disposers.forEach((d) => d());
}
```

---

## Extensions overview

Source: https://ngxviewbuilder.io/developers/extensions

# Extensions overview

All customisation funnels through a single config type, `INgxViewBuilderExtensionsConfig`, registered either at bootstrap or at runtime.

## Registering

**At bootstrap (recommended):**

```ts
import { provideNgxViewBuilderExtensions } from 'ngx-view-builder';

providers: [
  provideNgxViewBuilderExtensions({
    elements: [...],
    expressionFunctions: [...],
    svgIcons: {...},
  }),
]
```

The provider also accepts a factory (sync or async), which helps when the config comes from an API:

```ts
provideNgxViewBuilderExtensions(async () => {
  const cfg = await fetch('/api/builder-config').then((r) => r.json());
  return { runtimeVariableContext: cfg.context, svgIcons: cfg.icons };
}),
```

**At runtime:**

```ts
api.registerExtensions(config);
await api.registerExtensionsAsync(config);   // resolves icon directories etc.
```

Multiple `provideNgxViewBuilderExtensions(...)` calls compose; plugins use the same mechanism.

## What the config can contain

| Key | Registers | Details |
| --- | --- | --- |
| `elements` | custom element types | [Custom elements](https://ngxviewbuilder.io/developers/custom-elements) |
| `elementGroups` | new sidebar groups | id, label, icon, order |
| `expressionFunctions` | JEXL functions | [Custom functions](https://ngxviewbuilder.io/developers/custom-functions) |
| `globalProperties` | properties added to *every* element | [Custom properties](https://ngxviewbuilder.io/developers/custom-properties) |
| `elementProperties` | per-type property overrides/additions | [Custom properties](https://ngxviewbuilder.io/developers/custom-properties) |
| `svgIcons` / `svgIconDirectory` / `svgIconDirectories` | icons by name / from asset folders | [Icons](https://ngxviewbuilder.io/developers/icons) |
| `builderTabs` | extra builder tabs | [Building a plugin](https://ngxviewbuilder.io/developers/plugin-development) |
| `featurePacks` | bundles of tabs + capabilities | [Building a plugin](https://ngxviewbuilder.io/developers/plugin-development) |
| `runtimeVariables` / `runtimeVariableContext` | variables for expressions | [Runtime variables](https://ngxviewbuilder.io/developers/runtime-variables) |
| `uiDictionaries` | builder UI translations | [UI translations](https://ngxviewbuilder.io/developers/ui-translations) |
| `triggers` / `rules` / `process` / `fragments` | automation definitions | consumed by the automation plugins |

## Example: a project preset

```ts
provideNgxViewBuilderExtensions({
  elementGroups: [{ code: 'acme', label: 'ACME widgets', icon: 'acmeLogo', order: 10 }],
  elements: [acmeCardElement, acmeRatingElement],
  expressionFunctions: [
    { name: 'vatAmount', args: ['net'], description: 'Adds 21% VAT',
      example: 'vatAmount({netPrice})',
      handler: (net: unknown) => Number(net || 0) * 1.21 },
  ],
  globalProperties: {
    trackingId: { label: 'Tracking ID', type: 'text', category: 'general' },
  },
  svgIcons: { acmeLogo: '<svg ...>...</svg>' },
  runtimeVariableContext: { brand: 'acme' },
});
```

Everything a creator then sees (the ACME group, the elements, the `vatAmount()` function, the extra property) comes from this one object.

---

## Custom SVG icons

Source: https://ngxviewbuilder.io/developers/icons

# Custom SVG icons

Icons are referenced by **name** everywhere (element `icon` properties, buttons, sidebar groups, header actions). Register your own names once; creators then use them like built-ins.

## Inline registration

```ts
provideNgxViewBuilderExtensions({
  svgIcons: {
    acmeLogo: `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor">…</svg>`,
    rocket:   `<svg viewBox="0 0 24 24">…</svg>`,
  },
});
```

Runtime: `api.registerSvgIcon(name, svg)` / `api.registerSvgIcons(map)` (both accept `overwrite`).

## Loading from asset folders

```ts
provideNgxViewBuilderExtensions({
  svgIconDirectory: {
    basePath: '/assets/icons',
    names: ['invoice', 'shipment', 'warehouse'],
    extension: 'svg',        // default
    prefix: 'acme',          // registered as acmeInvoice, acmeShipment, …
  },
});
```

Multiple folders via `svgIconDirectories: [...]`. Runtime loading (`await api.registerSvgIconDirectory(cfg)`) resolves fetches and returns `{ loaded, failed }`.

## Using icons

- **Creators**: type the icon name into any `Icon` property (button icon, Icon element, sidebar group…).
- **In your components**: the exported `NvbIcon` component renders any registered icon:

```html
<nvb-icon name="acmeLogo" />
```

## SVG guidelines

- Use `viewBox` and no fixed `width`/`height`; the host sizes the icon.
- Use `currentColor` for strokes/fills so icons follow text color and theme.
- Keep markup minimal; icons are inlined into the DOM.
- Registered SVG is sanitised, so keep icons to plain vector markup (no scripts or foreignObject).

---

## Installation

Source: https://ngxviewbuilder.io/developers/installation

# Installation

## Requirements

- Angular 22+ (`@angular/common`, `@angular/core`, `@angular/cdk` as peer dependencies)
- Node.js 22.22+ (or 24.15+ / 26+)

The library works with zoneless change detection and standalone components.

## Install

```bash
npm install ngx-view-builder
```

The optional Templates plugin is a separate package, version-locked to the core:

```bash
npm install ngx-view-builder-plugin-templates
```

## Minimal app config

```ts
// app.config.ts
import { ApplicationConfig } from '@angular/core';
import { provideHttpClient } from '@angular/common/http';
import { provideRouter } from '@angular/router';
import { routes } from './app.routes';

export const appConfig: ApplicationConfig = {
  providers: [
    provideHttpClient(),   // required for REST data sources
    provideRouter(routes), // required for route variables & navigate actions
  ],
};
```

## Stylesheet

Each component carries its own scoped styles, but the design tokens and the shared element rules live in one global stylesheet. Import it once:

```css
@import 'ngx-view-builder/styles/index.css';
```

Leaving it out does not blank the UI, which is what makes it easy to miss. The components still render and still have their own layout, they simply lose every token: inputs come out around 26px instead of 40px, labels fall back to plain black, and surfaces turn transparent.

### Layer order

Everything in the stylesheet lives in `@layer reset, tokens, components, fpUtilities, elements`. Cascade layers only help if the host takes part in them, and two rules decide whether it does.

Unlayered CSS beats layered CSS whatever the specificity. A host that writes its styles outside any layer, which is the default for Tailwind v3 and for most hand written stylesheets, will override every rule the library ships.

A plain CSS `@import` is always hoisted to the top of the bundle, so the layer order cannot be fixed by moving the import line around. Declare the order yourself, in a stylesheet loaded before everything else:

```css
/* src/layers.css, with Tailwind as the example host */
@layer theme, base, reset, tokens, components, fpUtilities, elements, utilities;
```

```json
"styles": ["src/layers.css", "src/styles.scss"]
```

Our layers now sit after the host's base and reset, and the host's utilities still win over element styles, which is usually what you want.

### Name collisions

Every class and every custom property the library ships is prefixed with `nvb-`, so `nvb-field`, `nvb-dropdown`, `--nvb-color-neutral-300`. Nothing in the package answers to a generic name any more, and a host is free to keep its own `.field` or `--color-neutral-300` meaning whatever it likes. Before 0.4.0 those names were shared, which broke both directions at once.

## Initialization

Runtime services can be pre-warmed either with a provider:

```ts
import { provideNgxViewBuilderRuntime } from 'ngx-view-builder';

providers: [
  provideNgxViewBuilderRuntime({ preloadRuntimeServices: true }),
]
```

…or imperatively in a component:

```ts
import { ForgeInitializerService } from 'ngx-view-builder';

constructor() {
  inject(ForgeInitializerService).load({ preloadRuntimeServices: true });
}
```

Options:

| Option | What it does |
| --- | --- |
| `preloadRuntimeServices` | Instantiates structure/expression/validator services upfront |
| `exposeHeadlessValidationApi` | Publishes a global validation API (for headless/E2E use) |
| `headlessValidationApiKey` | The global key it registers under |

## Registering plugins

Installing a plugin package does nothing by itself. Register its provider:

```ts
import { provideNgxViewBuilderTemplates } from 'ngx-view-builder-plugin-templates';

providers: [
  provideNgxViewBuilderTemplates(),
]
```

Each registered plugin adds its tab to the builder automatically. See [Using plugins](https://ngxviewbuilder.io/developers/plugins).

## Import rule

Import only from package roots (`ngx-view-builder`, `ngx-view-builder-plugin-*`). Deep imports into `src/lib/...` are internal and break between releases.

---

## Licensing

Source: https://ngxviewbuilder.io/developers/licensing

# Licensing

> NGX View Builder is in public beta, so licenses aren't for sale yet. See [Pricing](https://ngxviewbuilder.io/pricing) for current status. Everything below describes the license model you'll buy into at launch.

**The runtime is free forever and never requires a license key, at 1.0.0 or any version after.** Everything on this page describes the commercial license for the builder only.

## Is this open source?

**No.** NGX View Builder is commercial software, not open source (not MIT, Apache, GPL, or any OSI-approved license). Installing it from npm gives you the right to use it under the terms below. It does not grant a license to fork, redistribute, or build a competing product from it.

If you've used commercial component libraries before, the model will feel familiar: install from the public npm registry, evaluate for free with a watermark, unlock full use with a paid key.

**Attempting to remove, disable, or circumvent the license check (the watermark, the signature validation, or the server check) is a breach of the license agreement**, regardless of how it's done (patching the package, monkey-patching at runtime, stripping the check at build time, etc.). See [Restrictions](https://ngxviewbuilder.io/developers/licensing#license-terms) below.

## Supplying the key

Pass the license key through `runtimeSettings`:

```ts
readonly builderSettings: INgxViewBuilderBuilderSettings = {
  licenseKey: 'NVB-eyJjdXN0b21lcklkIjo...',
};
```

```html
<ngx-view-builder-builder [runtimeSettings]="builderSettings" ... />
```

## How validation works

1. **Local check**: the key embeds `customerId`, `plan`, and `expiresAt`; version coverage is checked immediately (see below).
2. **Offline signature check**: keys are ECDSA P-256 signed; the builder verifies the signature against an embedded public key (WebCrypto). Tampered or self-made keys are treated as invalid. No network required.
3. **Server check**: the builder additionally calls the official license service (fixed, non-configurable URL) with `{ key, domain }`. The result is cached in localStorage for 7 days; network failures fall back silently to the local checks, so air-gapped environments keep working. A revoked key always shows the watermark.

## Version coverage (perpetual fallback)

Every published build embeds its release date. A license covers **all versions released before its `expiresAt`**, permanently:

- While the license is active, every update is covered.
- After the license expires, the versions you already use **keep working forever, without a watermark**.
- Versions released *after* the license expired run in degraded mode (watermark) until the license is renewed, so installing the latest package from npm without an active license does not grant access to new features.

## What users see

| State | UI |
| --- | --- |
| Valid for this version | Nothing |
| **No key supplied** | A diagonal “NO LICENSE” watermark across the builder canvas + a banner |
| Version not covered (released after license expiry) | The canvas watermark + a banner + a reminder modal (at most once per 24 h) |
| Invalid / tampered / unparseable / revoked | The canvas watermark + an invalid-license banner + modal (at most once per 24 h) |

**The runtime never shows any license UI.** Rendering views in production is unaffected; license messaging is builder-facing only.

## License terms

NGX View Builder is **commercial software**, distributed under the NGX View Builder Commercial License Agreement, and the full text ships as `LICENSE.md` inside every published npm package (also shown on the npm package page). In short: a paid key covers all versions released during your license term perpetually; **client work is included and either side can hold the license**: an agency's key covers the applications it builds for its clients, or the end customer buys the key and it covers contractors developing their application (operating a delivered application never needs a key); evaluation without a key is free but watermarked; redistributing the library on its own or circumventing license enforcement is prohibited. The open-source dependencies the package installs (CodeMirror, Jexl, Prettier and Lodash under MIT; tslib under 0BSD) keep their own licenses.

## Notes

- Keep the key out of client repositories where possible; inject it from environment configuration.
- The `domain` sent to the validation server is `window.location.hostname`; issue keys per environment if you validate domains.

Licensing questions: **[support@ngxviewbuilder.io](mailto:support@ngxviewbuilder.io)**.

---

## Building a plugin

Source: https://ngxviewbuilder.io/developers/plugin-development

# Building a plugin

A plugin is just a package (or app module) that calls `provideNgxViewBuilderExtensions()` with a **feature pack**: an id, optional capabilities, and one or more builder tabs backed by Angular components.

## Anatomy: the real Templates plugin

```ts
import { EnvironmentProviders } from '@angular/core';
import { provideNgxViewBuilderExtensions } from 'ngx-view-builder';
import { MyStudio } from './my-studio/my-studio';

export const MY_FEATURE_PACK_ID = 'acme-audit';

export function provideAcmeAuditStudio(): EnvironmentProviders {
  return provideNgxViewBuilderExtensions({
    featurePacks: [
      {
        id: MY_FEATURE_PACK_ID,
        title: 'Audit studio',
        capabilities: ['acme.audit'],        // optional gating keys
        builderTabs: [
          {
            id: 'acmeAudit',                 // tab code
            label: 'tab.audit',              // UI-dictionary key (or plain text)
            component: MyStudio,             // any standalone component
            order: 900,                      // position among tabs
          },
        ],
      },
    ],
  });
}
```

That's the whole registration. The official Templates plugin (`ngx-view-builder-plugin-templates`) is exactly this thin.

## The tab component

Your component renders inside the builder shell and talks to the same services as everything else:

```ts
@Component({ standalone: true, template: `...` })
export class MyStudio {
  private api = inject(NgxViewBuilderApiService);

  structure = computed(() => this.api.getStructure());

  addAuditNote(): void {
    this.api.updateStructure((s) => {
      (s.settings as any).auditNotes = [...(s.settings as any).auditNotes ?? [], { at: Date.now() }];
    });
  }
}
```

Useful building blocks:

- `api.getStructure()` / `api.updateStructure(fn)`: read/write the view (updates flow to Undo history and `structureChanged`).
- `api.onStructureChanged.add(...)`: refresh when the creator edits elsewhere.
- Custom data can live in `structure.settings` under your own key, and unknown settings keys are preserved by the core.
- `api.translateUi(key, fallback)` + `uiDictionaries` in your extensions config: localise your tab.
- Tab labels starting with `tab.` resolve through UI dictionaries automatically.

## Capabilities

`capabilities` are opaque strings other code can require. Property definitions support `requiredFeaturePacks` / `requiredCapabilities`: a property (or other gated UI) shows only when a matching pack is registered. Use this to make core-side features light up when your plugin is installed.

## Packaging checklist

- [ ] Ship as an Angular library with a single `provideX()` entry point.
- [ ] Peer-depend on `ngx-view-builder` (never bundle it).
- [ ] Version-lock releases to the core version you built against.
- [ ] Keep tab `id` stable, since hosts may persist the active tab.
- [ ] Style with the design tokens so themes work ([Theming](https://ngxviewbuilder.io/developers/theming)).

---

## Templates plugin reference

Source: https://ngxviewbuilder.io/developers/plugin-templates

# Templates plugin reference

`ngx-view-builder-plugin-templates` adds the **Templates** tab: a library of reusable HTML/CSS snippets that List grid card templates, Select option templates, row templates, and header templates reference by name. The [creator guide](https://ngxviewbuilder.io/creators/templates) covers the tab from a form-builder's point of view; this page is the developer reference the exact template syntax, how the plugin decides where templates are read from, and (the part hosts always ask about) how to wire template Save/Delete to your own backend and database.

## Install & register

```bash
npm install ngx-view-builder-plugin-templates
```

```ts
import { provideNgxViewBuilderTemplates } from 'ngx-view-builder-plugin-templates';

providers: [ provideNgxViewBuilderTemplates() ],
```

That's the whole plugin: one feature pack (`ngx-view-builder-templates`), one capability (`templates`), one builder tab (tab code `templates`). See [Using plugins](https://ngxviewbuilder.io/developers/plugins) for the general install/registration mechanism.

## Template syntax

A template's **HTML content** is rendered by a small purpose-built engine, not the real Angular compiler it accepts an Angular-flavoured syntax (so it looks familiar to anyone who knows Angular templates) but only understands what's documented below.

### Interpolation <code v-pre>{{ expression }}</code>

```html
<strong>{{ item.name }}</strong>
<span>Row {{ index + 1 }} of {{ $count }}</span>
```

The expression runs against the template's runtime context: `item` / `row` / `value` (the bound record all three names point at the same object), `index`, every field in the current form data, and (inside `@for`) the loop variables below. Output is HTML-escaped automatically.

### Legacy single-brace tokens `{path}`

`{status.code}` also works as a shorthand for a plain data-path lookup (no operators allowed). Prefer <code v-pre>{{ }}</code> for anything that isn't a bare path <code v-pre>{{ }}</code> supports real expressions, `{ }` doesn't.

### Translations `[[ key ]]` and `t()` / `tr()`

```html
<h4>[[ card.title | Card title ]]</h4>
<button>{{ t('actions.approve') }}</button>
```

- `[[ key | fallback ]]` looks the key up in the view's `localization.texts` for the active language (falling back to the default language, then the fallback text, then the raw key). See [Translations](https://ngxviewbuilder.io/creators/translations) for how `localization` gets populated.
- `t('key')` / `tr('key', 'fallback')` do the same lookup from inside any expression position <code v-pre>{{ }}</code>, `@if (...)`, `@switch (...)`, click handlers.
- `[[ someField ]]` (no literal key) evaluates `someField` as an expression first if the data has a value there, _that value_ becomes the translation key, so `[[ status ]]` looks up whatever `status` currently holds (e.g. `"ACTIVE"`). Use a path that resolves to nothing when you want a literal key instead of a dynamic one.

### Control flow `@if` / `@for` / `@switch` / `@let`

```html
@if (item.status == "Active") {
<span class="ok">Active</span>
} @else if (item.status == "Pending") {
<span class="pending">Pending</span>
} @else {
<span class="muted">{{ item.status }}</span>
} @for (line of item.lines; track $index) {
<li>{{ line.label }} {{ line.qty }}</li>
} @empty {
<li class="muted">No lines</li>
} @switch (item.tier) { @case ('gold') {
<span class="tier tier--gold">Gold</span> } @case ('silver') {
<span class="tier tier--silver">Silver</span> } @default {
<span class="tier">Standard</span> } } @let total = sumInArray(item.lines,
'qty'); <span>Total: {{ total }}</span>
```

Loop variables inside `@for`: `$index`, `$count`, `$first`, `$last`, `$even`, `$odd`, plus any `let x = expr` aliases declared in the loop header. Conditions and iterable expressions use the same expression language as **Visible if** / logic properties elsewhere in the builder see [Expressions basics](https://ngxviewbuilder.io/creators/expressions) evaluated against the runtime context above.

`===` / `!==` are accepted and treated as `==` / `!=`; `?.` is treated as `.`. There's no real Angular pipe system, no `*ngIf` / `*ngFor`, no arbitrary JavaScript only the constructs on this page.

### Conditional classes `[class.name]="expr"`

```html
<div
  [class.overdue]="item.dueDate < today()"
  [class.paid]="item.status == 'paid'"
>
  {{ item.label }}
</div>
```

Each matching class is added to the element's `class` attribute when its expression is truthy; the binding itself is stripped from the rendered output.

### Click actions `(click)="..."`

```html
<button (click)="approve(item.id)">Approve</button>
```

`(click)` is rewritten to a `data-nvb-event-click` attribute at render time and intercepted by the engine directly (no Angular event binding involved). See [Wiring template actions](https://ngxviewbuilder.io/developers/plugin-templates#wiring-template-actions-to-your-backend) below for what the call inside the quotes can do.

### Icons `<nvb-icon>`

```html
<nvb-icon name="check_circle"></nvb-icon>
```

Renders the same inline SVG set used by the rest of the builder (see [Custom SVG icons](https://ngxviewbuilder.io/developers/icons)); the `name` / `icon` / `data-icon` attribute or the tag's own text content picks the icon. Legacy `<span class="material-symbols-outlined">check_circle</span>` markup is upgraded automatically too.

### CSS the template's own `<style>` block

Write the **CSS** field as plain CSS, with SCSS-like nesting if you want it:

```css
.client-card {
  display: flex;
  gap: 4px;
  padding: 12px;
  border: 1px solid #ddd;
  border-radius: 8px;
  .badge {
    color: #0a7;
    font-size: 12px;
  }
  &:hover {
    border-color: #0a7;
  }
}
@media (max-width: 480px) {
  .client-card {
    padding: 8px;
  }
}
```

Nesting (`&`, `:host`, plain descendant selectors) is flattened, and the whole block is scoped to the template's own host element at render/preview time it can't leak onto the rest of the page, and you never write a host selector yourself.

### What gets stripped (sanitization)

Template HTML goes through a sanitizing pass before rendering, and the rendered output through a second full-HTML sanitizer pass. In practice:

- `<script>`, `<iframe>`, `<object>`, `<embed>`, `<link>`, `<meta>`, `<base>` are removed entirely.
- Any `on*` attribute (`onclick`, `onmouseover`, …) is stripped use `(click)="..."` instead.
- Inline `style="..."` attributes are stripped put styles in the template's own CSS block, or use classes, not `style=`.
- `srcdoc` is stripped.

## Template field slots

Bracket-indexed references in the content `row[0]`, `item['status']`, `value[2]` are surfaced in the editor as **Template fields**, so a List grid or Select can map its own data onto those slots without touching the template markup. At render time the mapping rewrites `row` / `item` / `value` on the runtime context before the template renders.

## Where templates are read from at runtime

Every view has these structure settings (set via the JSON editor, `api.patchSettings()`, or `api.updateStructure()` there's no dedicated builder field for them yet):

| Setting                         | What it does                                                                                     |
| ------------------------------- | ------------------------------------------------------------------------------------------------ |
| `templateStorageMode`           | `'localStorage'` (default) or `'dataSource'`                                                     |
| `templateStorageLocalKey`       | Browser storage key for local mode (default `ngx-view-builder.templates.v1`)                     |
| `templateStorageDataSourceName` | Which registered [data source](https://ngxviewbuilder.io/creators/data-sources) supplies templates in `dataSource` mode |
| `templateStorageDataPath`       | Path into that source's response where the template array lives                                  |

::: warning This is a read path, not your database integration
`dataSource` mode reliably **writes** only when the named source is a `local` (in-structure JSON) source anything backed by a real REST/websocket source silently falls back to writing into `localStorage` under a per-source key instead of hitting your API. Reading works for any source type (via the _Load from data source_ action). So treat `templateStorageMode: 'dataSource'` as a way to **seed/refresh** templates from a live source, not as the mechanism that persists edits to your database that's the API-level integration below, which every Save/Delete in the Templates tab already goes through regardless of this setting.
:::

## Persisting templates to your database

Templates always live in `structure.settings.templates`, and the Templates tab's Save/Delete buttons always go through `NgxViewBuilderApiService` so this is the one integration point to wire up, independent of the storage-mode setting above.

### Load your templates in

On startup, fetch your saved templates and push them into the builder:

```ts
private api = inject(NgxViewBuilderApiService);

async ngOnInit(): Promise<void> {
  const templates = await firstValueFrom(this.http.get<ITemplateDefinition[]>('/api/templates'));
  this.api.loadTemplates(templates); // replace = true by default
}
```

`loadTemplates(templates, replace = true)` (alias `setTemplates`) accepts objects shaped like `ITemplateDefinition` (`name`, `title?`, `description?`, `content`, `css?`, `tags?`, …) pass `replace: false` to merge instead of overwrite. It fires `onTemplatesLoaded`.

### React to Save / Delete

Two equivalent ways to hear about edits pick whichever fits how your app is wired:

**A. Component outputs**, if you embed `<ngx-view-builder-builder>` directly:

```html
<ngx-view-builder-builder
  [model]="builderModel"
  (templateSaved)="onTemplateSaved($event)"
  (templateDeleted)="onTemplateDeleted($event)"
  (templatesLoaded)="onTemplatesLoaded($event)"
/>
```

**B. `NgxViewBuilderApiService` events**, anywhere else (they fire identically the outputs above just forward these):

```ts
private api = inject(NgxViewBuilderApiService);

ngOnInit(): void {
  this.api.onTemplateSaved.add(({ template, previousCode }) => {
    const request = previousCode
      ? this.http.put(`/api/templates/${previousCode}`, template)  // renamed: previousCode -> template.code
      : this.http.put(`/api/templates/${template.code}`, template);
    firstValueFrom(request).catch((err) => this.api.showToast({
      title: 'Template not saved', message: err.message, variant: 'error',
    }));
  });

  this.api.onTemplateDeleted.add(({ code }) => {
    void firstValueFrom(this.http.delete(`/api/templates/${code}`));
  });
}
```

`onTemplateSaved`'s payload uses `code` for the template's unique name (same value as `template.name`, under the API's field name); `previousCode` is only set when the Save renamed an existing template, so you know to update rather than insert.

You can also read the current list on demand e.g. right before your own "save form" call with `api.getTemplates()`, and push/remove one template imperatively with `api.upsertTemplate(template)` / `api.saveTemplate(template, previousCode?)` and `api.removeTemplate(name)` / `api.deleteTemplate(code)`.

## Wiring template actions to your backend

The expression inside `(click)="..."` is a single function-style call `name(arg1, arg2)` or a bare `name` resolved in this order:

1. **An element action.** If the element hosting the template (the List grid, Select, table, …) has an [Events & actions](https://ngxviewbuilder.io/creators/events-actions) entry whose `actionCode` (or `id` / `label`) matches, that action runs with the call's arguments available as context:
   ```html
   <button (click)="approveRow(item.id)">Approve</button>
   <!-- or, if you'd rather keep the action reference explicit: -->
   <button (click)="action('approveRow', item.id)">Approve</button>
   ```
   (`runAction` / `eventAction` are accepted aliases for `action`.)
2. **A data source**, otherwise. The call name is looked up in the map set by `api.setTemplateActionMap({...})` / `api.registerTemplateActionDataSource(fnName, dataSourceName)` (or the structure's `settings.templateActionMap`, or the builder's `templateActionMap` runtime setting), and the resolved [data source](https://ngxviewbuilder.io/developers/data-sources) runs directly no element action needed:
   ```ts
   this.api.setTemplateActionMap({ approve: "approveRequest" });
   ```
   ```html
   <button (click)="approve(item.id)">Approve</button>
   <!-- or call the data source name directly, with no map entry: -->
   <button (click)="dataSource('approveRequest', item.id)">Approve</button>
   ```
   (`runSource` / `runDataSource` / `loadDataSource` are accepted aliases for `dataSource`.)

Either way, the call's arguments are exposed to whatever runs as `{arg0}`, `{arg1}`, … (so a REST data source's URL can be `/api/requests/{arg0}/approve`), and as `{__action.name}`, `{__action.args}`, `{__action.item}`, `{__action.row}` everywhere else in the view for the duration of the call.

## Events at a glance

| Event               | Fires                                                                    |
| ------------------- | ------------------------------------------------------------------------ |
| `onTemplateSaved`   | a template was added or updated `{ template, previousCode?, timestamp }` |
| `onTemplateDeleted` | a template was removed `{ code, timestamp }`                             |
| `onTemplatesLoaded` | `loadTemplates` / `setTemplates` ran `{ templates, replace, timestamp }` |

Full list (including the sidebar-library equivalents used by the reusable-elements panel) in the [Events reference](https://ngxviewbuilder.io/developers/events#templates-sidebar-library).

## Related

- [Using plugins](https://ngxviewbuilder.io/developers/plugins) the general plugin/capability mechanism
- [Dynamic text & templates](https://ngxviewbuilder.io/creators/templates) the creator-facing guide to the Templates tab
- [Events & actions](https://ngxviewbuilder.io/creators/events-actions) `actionCode` and the action editor
- [Data source integration](https://ngxviewbuilder.io/developers/data-sources) host-side data source concerns
- [API service reference](https://ngxviewbuilder.io/developers/api-service#templates-sidebar-library) / [Events reference](https://ngxviewbuilder.io/developers/events#templates-sidebar-library)

---

## Using plugins

Source: https://ngxviewbuilder.io/developers/plugins

# Using plugins

Plugins are separate npm packages that add builder tabs and capabilities. The core never bundles or auto-loads them: install what you need, register its provider, done.

```bash
npm install ngx-view-builder-plugin-templates
```

```ts
import { provideNgxViewBuilderTemplates } from 'ngx-view-builder-plugin-templates';

providers: [ provideNgxViewBuilderTemplates() ],
```

## Official plugins

| Package                             | Provider                           | Adds                                                                                                                                                                                                                                                              |
| ----------------------------------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ngx-view-builder-plugin-templates` | `provideNgxViewBuilderTemplates()` | The **Templates** tab, holding the reusable HTML [template library](https://ngxviewbuilder.io/creators/templates) used by option templates, card templates, row templates, and header templates full syntax and host persistence in the [Templates plugin reference](https://ngxviewbuilder.io/developers/plugin-templates) |

## How gating works

A plugin registers a **feature pack** (id + capabilities + tabs). Parts of the core UI are capability-aware: the _Option template_ property on Select elements, for example, appears only when the Templates feature pack is present. So an uninstalled plugin cleanly hides everything that depends on it.

## Version rule

Keep every `ngx-view-builder-plugin-*` version aligned with the core `ngx-view-builder` version. Mixed versions are unsupported.

Want to build your own tab? See [Building a plugin](https://ngxviewbuilder.io/developers/plugin-development).

---

## Rendering views (runtime)

Source: https://ngxviewbuilder.io/developers/runtime-integration

# Rendering views (runtime)

## Minimal setup

```ts
import { Component, ViewChild, signal } from '@angular/core';
import { IStructure, NgxViewBuilderRuntime } from 'ngx-view-builder';

@Component({
  selector: 'app-client-form',
  imports: [NgxViewBuilderRuntime],
  template: `
    <ngx-view-builder-runtime
      [pageJson]="structure()"
      [dataJson]="initialData()"
      [theme]="'light'"
      [language]="'en'"
    />
  `,
})
export class ClientFormComponent {
  @ViewChild(NgxViewBuilderRuntime) runtime?: NgxViewBuilderRuntime;

  structure = signal<IStructure>(/* loaded from your backend */);
  initialData = signal<Record<string, unknown>>({ clientType: 'person' });

  save(): void {
    const data = this.runtime?.getDataSnapshot() ?? {};
    // send to backend
  }
}
```

`pageJson` and `dataJson` accept an object or a JSON string.

## Inputs

| Input | Type | Purpose |
| --- | --- | --- |
| `pageJson` | `IStructure \| string` | The view definition |
| `dataJson` | `Record<string, unknown> \| string` | Initial form data (edit scenarios) |
| `language` / `theme` | `string` / `'light'\|'dark'` | Localisation & scheme |
| `runtimeSettings` | `INgxViewBuilderBuilderSettings` | Variables, data sources, license… |
| `contentTranslations` / `uiDictionaries` | dictionaries | Translations |
| `cssVariables` | `Record<string,string>` | Token overrides |
| `externalConfig` / `externalConfigUrl` | object / URL | Host config |

## Getting data out

Three complementary channels:

1. **Snapshot**: `runtime.getDataSnapshot()` whenever you need the current object.
2. **Outputs**: `(valueChanged)` per-field, `(structureChanged)` if the runtime mutates structure.
3. **API service**: the full event set:

```ts
import { NgxViewBuilderApiService } from 'ngx-view-builder';

private api = inject(NgxViewBuilderApiService);

ngOnInit(): void {
  this.api.onComplete.subscribe(({ isValid, data, issues }) => {
    if (isValid) this.clientService.save(data);
  });

  this.api.onValidated.subscribe(({ isValid, issues }) => { /* ... */ });
  this.api.onElementValueChanged.subscribe((e) => { /* per-field hook */ });
}
```

`onComplete` fires when the built-in Submit button finishes; it carries validity, the data object, and any issues. Full list: [Events reference](https://ngxviewbuilder.io/developers/events).

The runtime keeps its own isolated API instance internally, but every event it fires is forwarded to the root `NgxViewBuilderApiService` automatically, so the root-injected subscriptions above receive everything, including render lifecycle (`onAfterRender`, `onElementAfterRender`) and element interaction events (`onDynamicTableRowAdded`, `onDynamicPanelItemRemoved`, …).

## Programmatic control

```ts
await this.api.validateData();                        // run validation
await this.api.setValue('clientType', 'company');     // set a field
this.api.setData({ ...bigObject });                   // replace all data
this.api.setElementProperty('step2', 'disabled', true);
await this.api.reloadDataSource('loadClients');
this.api.showToast({ title: 'Saved', variant: 'success' });
```

## Table personalisation events

Tables emit column-settings and saved-filters events so hosts can persist per-user preferences (`tableSettingsChanged`, `tableSavedFiltersChanged`, and their request/save counterparts). Store them by `tableName` + user, feed them back with `api.setTableSettings(...)` / `api.setTableSavedFilters(...)`.

## Dialog render mode

If the view's settings use `renderMode: 'dialog'`, the runtime renders it as a modal. Track closure via `api.onDialogClosed`.

## Renderer & unified components

`<ngx-view-builder>` (unified) exposes the same runtime inputs plus optional builder-tab chrome; `<ngx-view-builder-renderer>` is the raw renderer beneath it. Prefer `<ngx-view-builder-runtime>` unless you are composing something unusual.

---

## Runtime variables

Source: https://ngxviewbuilder.io/developers/runtime-variables

# Runtime variables

Views reference host context through variables: `{__variables.name}` and `{__external.name}` in expressions. The host controls what those resolve to.

## External context (simplest)

Push any object; every key becomes `{__external.key}`:

```ts
this.api.setRuntimeVariableContext({
  userId: 'u-42',
  userRole: 'admin',
  tenantId: 'acme',
});
```

```text
disableIf:  {__external.userRole} != "admin"
Default value: {__external.userId}
```

`setRuntimeVariableContext(values, merge = true)` merges by default; `clearRuntimeVariableContext()` resets.

## Variable definitions

Definitions add typed, named variables with fallbacks and refresh rules. Creators can manage them in the **Variables** tab; hosts can also supply them:

```ts
this.api.setRuntimeVariableDefinitions([
  { name: 'clientId', sourceType: 'route',     source: 'id' },
  { name: 'apiBase',  sourceType: 'constant',  constantValue: '/api/v2' },
  { name: 'isEdit',   sourceType: 'expression', expression: 'notEmpty({__variables.clientId})' },
  { name: 'settings', sourceType: 'dataSource', source: 'loadSettings',
    fallbackValue: {} },
]);
```

| `sourceType` | Resolves from |
| --- | --- |
| `route` | Angular route/query params |
| `external` | the external context object |
| `constant` | `constantValue` |
| `expression` | evaluated expression (`refreshPaths` re-evaluates) |
| `dataSource` | a named data source's result |
| `manual` | left to be set at runtime |

Useful definition flags: `fallbackValue`, `targetPath` (mirror into form data), `includeInDataJson` (ship with submits), `refreshOnChange` / `refreshPaths`.

Two things to keep in mind when defining them by hand:

- An `expression` variable resolves element references the same way an element expression does, so `{el1} + {el2}` reads those fields even before the user has touched them. Its dependencies are tracked automatically and it recomputes whenever one of them changes, along with anything reading the variable.
- A `dataSource` variable needs an explicit `source`. If it is missing, the variable stays unresolved rather than picking up whichever source happens to be first in the structure.

## One-call configuration

```ts
this.api.configureRuntimeVariables({
  mappings: [...definitions],
  external: { userRole: 'admin' },
  mergeExternal: true,
});
```

Or declaratively via `runtimeSettings`:

```ts
runtimeSettings = {
  runtimeVariables: [...definitions],
  runtimeVariableContext: { userRole: 'admin' },
};
```

## Typical pattern: route-driven edit form

```ts
// /clients/:id/edit
ngOnInit(): void {
  this.api.configureRuntimeVariables({
    mappings: [{ name: 'clientId', sourceType: 'route', source: 'id' }],
    external: { userName: this.auth.userName },
  });
}
```

Inside the view: a data source `GET /api/clients/{id}` with param `id = {__variables.clientId}` loads the record; `{__external.userName}` prefills the author field.

## Timing

Set context **before** the view renders (constructor / `ngOnInit` ahead of passing `pageJson`). Later updates propagate (expressions referencing `__variables` re-evaluate on change) but avoid churn during initial load.

---

## Schema versioning

Source: https://ngxviewbuilder.io/developers/schema-versioning

# Schema versioning

Views live in your database, sometimes for years. The library keeps evolving. `schemaVersion` is the contract that keeps those two facts from colliding: every structure records the format it was saved in, and the runtime upgrades anything older before it renders.

```json
{
  "schemaVersion": 1,
  "settings": { "language": "en" },
  "pages": [],
  "elements": {}
}
```

Nothing is required of you for this to work. Load an old view under a new library version and it renders correctly. The rest of this page is for the cases where you want control.

## What a version bump means

The number goes up by one when a change to the structure format is not backward compatible: a field is renamed or removed, a field changes type, a node is reshaped, or the meaning of an existing default changes.

Adding a new optional field or a whole new element type is not a bump. Old JSON keeps rendering under the new runtime, because nothing it relied on moved.

Structures saved before `schemaVersion` existed carry no version at all. Those are read as version 1, which is the oldest format the library still knows.

## What happens on load

Every entry point that accepts a structure runs the same chain, including the JSON editor and the MCP command API:

1. Read the version the JSON declares.
2. Apply each migration in order until the structure reaches the version the runtime speaks.
3. Hand the result to the renderer.

The migration happens in memory. The library never writes to your storage. A migrated view stays migrated only for as long as it is open, unless you save it yourself.

```ts
const model = new BuilderModel(storedJson);
model.getJson();             // migrated, current format
model.getSourceJson();       // exactly what you passed in, or null when nothing was migrated
model.getMigrationResult();  // what the last load did, or null
```

That distinction matters when you audit or diff. Save `getJson()` when you want the upgrade persisted, and keep `getSourceJson()` if you need to prove what was stored before.

## In the builder

When a creator opens a view saved in an older format, the builder header shows an upgrade action with the two versions in its tooltip. The view is already migrated in memory, so the button is really a save prompt: pressing it emits `saveRequested` and rewrites the stored copy in the new format.

The runtime shows nothing. A person filling in a form has no decision to make about a schema.

## Configuring it

`provideNgxViewBuilderMigrations()` is optional. Reach for it to log upgrades, to register migrations for your own custom fields, or to opt out.

```ts
// app.config.ts
provideNgxViewBuilderMigrations({
  onMigrated: (result) =>
    logger.info(`view migrated v${result.fromVersion} to v${result.toVersion}`, {
      applied: result.appliedDescriptions,
      warnings: result.warnings,
    }),
});
```

| Option | What it does |
| --- | --- |
| `enabled` | Default `true`. Setting it to `false` hands the structure to the renderer untouched. Correct only when you run your own migration pipeline first. A stale structure rendered as-is means missing or misconfigured elements. |
| `onUnsupported` | What to do when the JSON declares a **newer** version than this runtime knows. `error` (default) refuses to render, `renderAsIs` tries anyway. Migrating forward is impossible, so both options are damage control. |
| `onMigrated` | Called once per migrated structure. Useful for audit logs. |
| `migrations` | Your own migrations, merged with the built-in ones. |

The provider writes module-level configuration rather than a DI token, because `BuilderModel` is constructed by hosts with `new BuilderModel()`, outside any injection context.

## Newer JSON than the runtime

This happens during a staged rollout: someone saves a view on the new version, then opens it on a server still running the old one. The old runtime cannot know what changed, so by default it refuses and reports the problem instead of rendering something subtly wrong.

If a partial render is better than none for your product, switch it:

```ts
provideNgxViewBuilderMigrations({ onUnsupported: 'renderAsIs' });
```

Deploying the library before the views that depend on it avoids the situation entirely.

## Writing your own migration

Custom elements and custom properties are yours, so their format changes are yours to handle. A migration reads one version and always produces the next one.

```ts
import { IStructureMigration } from 'ngx-view-builder';

const renameNoteText: IStructureMigration = {
  from: 1,
  description: 'sprCard.text -> sprCard.body',
  migrate: (structure) => {
    Object.values(structure.elements ?? {}).forEach((element: any) => {
      if (element?.type === 'sprCard' && element.text !== undefined) {
        element.body = element.text;
        delete element.text;
      }
    });
    return structure;
  },
};

provideNgxViewBuilderMigrations({ migrations: [renameNoteText] });
```

Return warnings when a change needs a human to look at it:

```ts
migrate: (structure) => ({
  structure,
  warnings: ['Two columns bound to the same key were merged, check the totals row.'],
});
```

Warnings reach you through `onMigrated` and through `StructureMigrationService.inspect()`.

## Inspecting without loading

`StructureMigrationService` answers questions about a structure without rendering it, which is what a migration script or a health check needs:

```ts
const migration = inject(StructureMigrationService);

migration.currentVersion;              // version this runtime speaks
migration.versionOf(storedJson);       // version that JSON declares
migration.needsMigration(storedJson);  // true when they differ
migration.inspect(storedJson);         // full result, no side effects
```

A batch upgrade of stored views is then a loop over your table: `inspect`, save the returned structure when `migrated` is true, and log `appliedDescriptions` as you go. Doing it once offline means no view pays the migration cost at request time.

---

## Standalone element examples

Source: https://ngxviewbuilder.io/developers/standalone-elements-examples

# Examples

Each recipe below is complete enough to paste into a component. They assume the setup from
[Overview](https://ngxviewbuilder.io/developers/standalone-elements): runtime providers registered, stylesheet
imported, icon font available.

## A single field

The smallest useful case. One input, one signal, nothing else.

```ts
import { Component, signal } from '@angular/core';
import { NvbElement, NvbScope } from 'ngx-view-builder';

@Component({
  selector: 'app-search-bar',
  imports: [NvbScope, NvbElement],
  template: `
    <nvb-scope [(data)]="filters">
      <nvb-element type="text" [config]="queryConfig" />
    </nvb-scope>
  `,
})
export class SearchBarComponent {
  filters = signal<Record<string, unknown>>({ query: '' });

  queryConfig = {
    name: 'query',
    label: 'Search',
    placeholder: 'Order number, customer, VAT code',
  };
}
```

`filters()` always holds the current value, so a computed can filter a list off it without
any subscription.

## Reacting to one field

When you care about a single value rather than the whole object.

```html
<nvb-scope [(data)]="form">
  <nvb-element type="select" [config]="warehouseConfig" (valueChange)="onWarehouse($event)" />
</nvb-scope>
```

```ts
warehouseConfig = {
  name: 'warehouse',
  label: 'Warehouse',
  options: [
    { label: 'Vilnius', value: 'VNO' },
    { label: 'Kaunas', value: 'KUN' },
  ],
};

onWarehouse(event: INvbElementValueChange): void {
  this.loadStock(event.value as string);
}
```

The event also fires when an expression writes the value, which is usually what you want.
If you only care about what a person typed, compare `event.previousValue` or listen on the
scope instead.

## A button that runs your code

Actions are declarative, so a button that should call your service gets an `actionCode` and
no `type`. The library then does nothing on its own and simply reports it.

```ts
submitConfig = {
  name: 'submit',
  text: 'Create invoice',
  icon: 'check',
  tone: 'primary',
  events: [{ trigger: 'click', actionCode: 'createInvoice' }],
};
```

```html
<nvb-element type="button" [config]="submitConfig" (action)="onAction($event)" />
```

```ts
onAction(event: IElementActionRunEvent): void {
  if (event.actionCode === 'createInvoice') {
    this.invoices.create(this.form());
  }
}
```

To confirm first, keep it in the configuration rather than in your handler. The action only
reaches you if the user agreed:

```ts
events: [
  {
    trigger: 'click',
    actionCode: 'deleteInvoice',
    confirmEnabled: true,
    confirmTitle: 'Delete invoice',
    confirmMessage: 'This cannot be undone.',
  },
],
```

## A form section with conditional fields

The reason to put several elements in one scope: they can see each other.

```html
<nvb-scope [(data)]="form">
  <nvb-element type="panel" [config]="deliveryPanel">
    <nvb-element type="selectButton" [config]="methodConfig" />
    <nvb-element type="text" [config]="addressConfig" />
    <nvb-element type="select" [config]="pickupPointConfig" />
  </nvb-element>
</nvb-scope>
```

```ts
deliveryPanel = { name: 'deliveryPanel', label: 'Delivery' };

methodConfig = {
  name: 'method',
  label: 'Method',
  options: [
    { label: 'Courier', value: 'courier' },
    { label: 'Pickup point', value: 'pickup' },
  ],
};

addressConfig = {
  name: 'address',
  label: 'Address',
  visibleIf: "method == 'courier'",
  requireIf: "method == 'courier'",
  resetOnHide: true,
};

pickupPointConfig = {
  name: 'pickupPoint',
  label: 'Pickup point',
  visibleIf: "method == 'pickup'",
  options: [
    { label: 'Vilnius, Gedimino 1', value: 'vno-1' },
    { label: 'Kaunas, Laisvės 10', value: 'kun-1' },
  ],
};
```

`resetOnHide` matters here. Without it the address the user typed stays in the data after
they switch to pickup, and you post a shipment with both.

## Calculated totals

An expression writes into an element, and a validator guards the result.

```html
<nvb-scope [(data)]="order">
  <nvb-element type="number" [config]="qtyConfig" />
  <nvb-element type="number" [config]="priceConfig" />
  <nvb-element type="number" [config]="totalConfig" />
</nvb-scope>
```

```ts
order = signal({ qty: 1, price: 49.9 });

qtyConfig = { name: 'qty', label: 'Quantity', min: 1 };
priceConfig = { name: 'price', label: 'Unit price' };

totalConfig = {
  name: 'total',
  label: 'Total',
  readOnly: true,
  expression: '{qty} * {price}',
  validators: [{ type: 'max', value: 10000, message: 'Order too large for self service' }],
};
```

Both operands are number elements, so they already hold numbers and the expression needs no
conversion. `toNumber()` belongs where a value arrives as text, or where an empty field
should count as zero.

## A tabbed form

Each tab declares its own children.

```html
<nvb-scope [(data)]="product">
  <nvb-element type="tabs" [config]="tabsConfig">
    <nvb-tab value="general">
      <nvb-element type="text" [config]="nameConfig" />
      <nvb-element type="textarea" [config]="descriptionConfig" />
    </nvb-tab>
    <nvb-tab value="pricing">
      <nvb-element type="number" [config]="priceConfig" />
      <nvb-element type="number" [config]="vatConfig" />
    </nvb-tab>
  </nvb-element>
</nvb-scope>
```

```ts
tabsConfig = {
  name: 'productTabs',
  tabs: [
    { label: 'General', value: 'general' },
    { label: 'Pricing', value: 'pricing' },
  ],
};
```

Values from a tab that is not open are still in the data and still visible to expressions,
so a condition on the general tab can depend on the price.

Give tabs room. Below roughly 768 pixels of container width they switch to the stacked
layout, which inside a narrow column looks like a bug but is the responsive behaviour.

## A dialog

The trigger and the content are one element.

```html
<nvb-scope [(data)]="form">
  <nvb-element type="dialog" [config]="addressDialog">
    <nvb-element type="text" [config]="streetConfig" />
    <nvb-element type="text" [config]="cityConfig" />
  </nvb-element>
</nvb-scope>
```

```ts
addressDialog = { name: 'addressDialog', label: 'Edit address' };
```

The dialog renders its own button, opens over the page and keeps its state under
`__dialog.addressDialog` in the data, which you can read if you need to know whether it is
open.

## An editable line item table

`dynamicTable` builds its columns from the configuration, and every column is an element,
so each cell is a real control.

```ts
order = signal({
  lines: [
    { product: 'Keyboard', qty: 2, unit: 'pcs' },
    { product: 'Coffee', qty: 1, unit: 'kg' },
  ],
});

linesConfig = {
  name: 'lines',
  label: 'Order lines',
  addRowButtonText: 'Add line',
  confirmRowDeletion: true,
  columns: [
    { type: 'text', name: 'product', label: 'Product' },
    { type: 'number', name: 'qty', label: 'Qty' },
    {
      type: 'select',
      name: 'unit',
      label: 'Unit',
      options: [
        { label: 'pcs', value: 'pcs' },
        { label: 'kg', value: 'kg' },
      ],
    },
  ],
};
```

`order().lines` is an array of row objects, so posting it needs no transformation.

## A read only data table

`table` without a data source reads its rows from the scope data. Sorting, search and paging
run in the browser.

```ts
data = signal({
  invoices: [
    { number: '2026-011', customer: 'Alfa UAB', issued: '2026-08-02', total: 1240.5 },
    { number: '2026-012', customer: 'Beta AB', issued: '2026-08-05', total: 890 },
  ],
});

invoicesConfig = {
  name: 'invoices',
  paginator: true,
  pageSize: 10,
  showQuickSearch: true,
  quickSearchPlaceholder: 'Search invoices',
  columnsConfig: [
    { key: 'number', label: 'Number', sortable: true, width: 120 },
    { key: 'customer', label: 'Customer', sortable: true },
    { key: 'issued', label: 'Issued', type: 'date', sortable: true },
    {
      key: 'total',
      label: 'Total',
      type: 'number',
      align: 'right',
      sortable: true,
      numberMinFractionDigits: 2,
      numberMaxFractionDigits: 2,
    },
  ],
};
```

Replacing the array in the signal replaces the rows, so this works just as well with data
you fetched yourself.

Watch the property names. `table` uses `columnsConfig` with a `key` per column,
`dynamicTable` uses `columns` with a `name` per column. They are not interchangeable.

## Validation before saving

Validators live on the elements. To block a save, check the data yourself or let a
`validateForm` action do it.

```ts
emailConfig = {
  name: 'email',
  label: 'Email',
  required: true,
  requiredMessage: 'We need an email to send the invoice',
  validators: [{ type: 'email', message: 'That does not look like an email' }],
};

saveConfig = {
  name: 'save',
  text: 'Save',
  tone: 'primary',
  events: [{ trigger: 'click', actionCode: 'save', validateForm: true }],
};
```

With `validateForm: true` the action stops when the form is invalid, so your `(action)`
handler only runs on valid data.

## A themed section

Themes are CSS variables on the scope element, which keeps them local to that part of the
screen.

```html
<nvb-scope [(data)]="form" [attr.style]="compactTheme">
  <nvb-element type="text" [config]="codeConfig" />
</nvb-scope>
```

```ts
compactTheme = [
  '--nvb-control-height: 28px',
  '--nvb-input-height: 28px',
  '--nvb-input-font-size: 12px',
  '--nvb-input-radius: 2px',
].join('; ');
```

Written as an attribute string rather than an object binding, because Angular's style object
binding does not pass CSS custom properties through. It has to sit on the scope element
itself, not on a wrapper around it.

## A translated form

```html
<nvb-scope [(data)]="form" [language]="lang()" [translations]="texts">
  <nvb-element type="text" [config]="emailConfig" />
</nvb-scope>
```

```ts
lang = signal('lt');

texts = {
  lt: {
    'elements.email.label': 'El. paštas',
    'elements.email.placeholder': 'jonas@imone.lt',
  },
};
```

Keys are structure paths, the same ones the builder exports. Anything without a translation
keeps the text from the configuration, so a partial dictionary is fine.

## Two independent forms on one screen

Each scope is its own namespace, so the same field name in both is two unrelated keys.

```html
<nvb-scope [(data)]="sender">
  <nvb-element type="text" [config]="addressConfig" />
</nvb-scope>

<nvb-scope [(data)]="receiver">
  <nvb-element type="text" [config]="addressConfig" />
</nvb-scope>
```

The same `addressConfig` object can be reused, because the name only has to be unique inside
one scope. Expressions cannot cross the boundary either, which is exactly what you want
here.

---

## Standalone elements

Source: https://ngxviewbuilder.io/developers/standalone-elements

# Standalone elements

The runtime renders a whole saved view. Sometimes you only want one element, or a handful,
placed inside a screen you wrote by hand. `<nvb-element>` does that: it takes the same
configuration JSON the builder saves and renders that single element wherever you put it.

This is meant for the screens you keep writing yourself. The checkout page, the settings
form, the admin tool that never fitted the builder. Those screens can now use the same
controls, the same tokens and the same conditional logic as everything else in your app,
instead of a second set of components that only look similar.

## Setup

Register the runtime providers once, exactly as you would for the runtime component, and
import the stylesheet:

```ts
import { bootstrapApplication } from '@angular/platform-browser';
import { provideNgxViewBuilderRuntime } from 'ngx-view-builder';

bootstrapApplication(AppComponent, {
  providers: [provideNgxViewBuilderRuntime()],
});
```

```css
@import 'ngx-view-builder/styles/index.css';
```

Icons need no setup. The plus and minus of a number stepper, the chevron of an accordion,
the calendar of a datepicker: every glyph a built-in element draws is inline SVG that ships
with the package, swapped in as the element renders. There is no icon font to install and
nothing to load over the network. Your own icons go in through
[Custom SVG icons](https://ngxviewbuilder.io/developers/icons), the same way they do in the runtime.

The stylesheet is not optional here. Element components carry their own layout, but every
size, colour and radius comes from tokens that only this file declares, so without it the
controls render at the wrong height with no theme at all. If your application already uses
cascade layers, read [Layer order](https://ngxviewbuilder.io/developers/installation#layer-order) as well: ours has to be
placed among yours or unlayered host CSS quietly wins over all of it.

## One element

```ts
import { Component, signal } from '@angular/core';
import { NvbElement, NvbScope } from 'ngx-view-builder';

@Component({
  selector: 'app-quick-form',
  imports: [NvbScope, NvbElement],
  template: `
    <nvb-scope [(data)]="form">
      <nvb-element type="text" [config]="emailConfig" />
    </nvb-scope>
  `,
})
export class QuickFormComponent {
  form = signal<Record<string, unknown>>({});

  emailConfig = {
    name: 'email',
    label: 'Email',
    placeholder: 'jane@company.com',
    required: true,
  };
}
```

`type` is the element type, the same string the builder writes in a view. `config` is that
element's own JSON. You can copy a definition out of a saved view and paste it here
unchanged, which also means the property reference in these docs applies as is.

## Scopes

`<nvb-scope>` gives the elements inside it one shared data object and one shared namespace.
That is what lets them see each other:

```html
<nvb-scope [(data)]="form">
  <nvb-element type="select" [config]="countryConfig" />
  <nvb-element type="text" [config]="vatConfig" />
</nvb-scope>
```

```ts
countryConfig = {
  name: 'country',
  label: 'Country',
  options: [
    { label: 'Lithuania', value: 'LT' },
    { label: 'Latvia', value: 'LV' },
  ],
};

vatConfig = {
  name: 'vat',
  label: 'VAT code',
  visibleIf: "country == 'LT'",
};
```

The element name is the key in the data object and the name expressions refer to. Rename an
element and every expression pointing at the old name quietly stops matching, so treat the
name as part of the contract.

Use one scope per screen. Two scopes never see each other, which means two different pages
can both have a field called `amount` without any risk of collision. An element written
without a surrounding scope falls back to a shared application wide scope, which is fine for
a single isolated control but becomes a trap as soon as names repeat, so prefer to always
write the scope.

## Getting data out

Three ways, from the broadest to the narrowest.

**The whole scope.** `[(data)]` is a two way binding to your own signal. It updates after
every change, including values written by an expression rather than typed by a person, and
writing to the signal pushes the values back into the elements.

**One element.** `(valueChange)` fires when that element's own value changes, whoever
changed it:

```html
<nvb-element type="select" [config]="countryConfig" (valueChange)="onCountry($event)" />
```

```ts
onCountry(event: INvbElementValueChange): void {
  // event.name, event.value, event.previousValue
}
```

**Actions.** Buttons and other elements run the actions configured in their `events`. Give
an action an `actionCode` and listen for it, which is how you run your own code from a
button:

```ts
saveConfig = {
  name: 'save',
  text: 'Save',
  tone: 'primary',
  events: [{ trigger: 'click', actionCode: 'saveInvoice' }],
};
```

```html
<nvb-element type="button" [config]="saveConfig" (action)="onAction($event)" />
```

The event carries `actionCode`, `trigger`, the whole action configuration and whether it
succeeded. Actions with a built in `type`, such as `navigate` or `dataSource`, still do
their own work; the output simply lets you react to them as well.

Reactive forms are not supported yet. There is no `ControlValueAccessor`, so
`formControlName` will not bind. Use `[(data)]` or `(valueChange)` instead.

## Containers

Nest the tags to express containment:

```html
<nvb-scope [(data)]="form">
  <nvb-element type="panel" [config]="addressPanel">
    <nvb-element type="text" [config]="streetConfig" />
    <nvb-element type="text" [config]="zipConfig" />
  </nvb-element>
</nvb-scope>
```

A nested tag renders nothing by itself. It contributes its definition and its position in
the tree, and the container decides where and how many times its children appear. That is
why an accordion shows its content inside the open section and a dialog shows it inside the
overlay, without you arranging anything.

`panel`, `dialog`, `accordion`, `progressFlow` and `emptyBlock` all work this way.

### Tabs

Tabs keep their children per tab, so the tab each child belongs to has to be stated:

```html
<nvb-element type="tabs" [config]="tabsConfig">
  <nvb-tab value="details">
    <nvb-element type="text" [config]="titleConfig" />
  </nvb-tab>
  <nvb-tab value="pricing">
    <nvb-element type="number" [config]="priceConfig" />
  </nvb-tab>
</nvb-element>
```

```ts
tabsConfig = {
  name: 'productTabs',
  tabs: [
    { label: 'Details', value: 'details' },
    { label: 'Pricing', value: 'pricing' },
  ],
};
```

The `value` of an `<nvb-tab>` has to match the `value` of one of the tabs in the config.

### Not supported yet

`dynamicPanel` and `splitter` are runtime only for now. The repeater builds a model per
data row, and the splitter needs a marker per pane in the same way tabs do. For a screen
that leans on either of them, render a saved view with `<ngx-view-builder-runtime>`
instead.

## Tables

Both table elements work, and they take their data from different places.

`dynamicTable` is the editable one. Its columns come from the configuration, and each
column is an element definition:

```ts
linesConfig = {
  name: 'lines',
  label: 'Order lines',
  addRowButtonText: 'Add line',
  columns: [
    { type: 'text', name: 'product', label: 'Product' },
    { type: 'number', name: 'qty', label: 'Qty' },
  ],
};
```

`table` is the read only one. Without a data source it reads its rows straight from the
scope data, so an array is all it needs. Sorting, quick search and paging then run in the
browser:

```ts
form = signal({
  invoices: [
    { number: '2026-011', customer: 'Alfa UAB', total: 1240.5 },
    { number: '2026-012', customer: 'Beta AB', total: 890 },
  ],
});

invoicesConfig = {
  name: 'invoices',
  paginator: true,
  pageSize: 5,
  showQuickSearch: true,
  columnsConfig: [
    { key: 'number', label: 'Number', sortable: true },
    { key: 'customer', label: 'Customer', sortable: true },
    {
      key: 'total',
      label: 'Total',
      type: 'number',
      align: 'right',
      numberMinFractionDigits: 2,
      numberMaxFractionDigits: 2,
    },
  ],
};
```

The two use different property names on purpose. `dynamicTable` has `columns`, and every
entry is an element with a `name`, because each cell is an editable control. `table` has
`columnsConfig`, and every entry is a column with a `key` naming the field to read from the
row object.

## Logic

Everything the builder offers in the logic panel works here, because it is the same engine.
Conditions live on the element and refer to other elements by name:

```ts
{ name: 'vat', visibleIf: "country == 'LT'" }
{ name: 'discount', disableIf: 'total < 100' }
{ name: 'total', expression: '{price} * {quantity}' }
{ name: 'shipping', requireIf: "delivery == 'courier'" }
```

Expressions read the shared data object, not the element models. A field whose value sits
in the data still resolves even when the element that owns it is not on screen, for example
because it lives in a tab that is currently closed. A name that is not in the data at all
resolves to `undefined`, which is not an error, just a condition that comes out false.

Validators are configured the same way and run automatically, including on values that an
expression computed rather than a person typed:

```ts
{
  name: 'total',
  expression: '{price} * {quantity}',
  validators: [{ type: 'max', value: 400, message: 'Must not exceed 400' }],
}
```

## Theming

The elements read their appearance from CSS variables. Set them on the element container
and the whole set follows, with no build step:

```css
.nvb-root {
  --nvb-color-primary-500: #0f7b7b;
  --nvb-input-radius: 12px;
  --nvb-control-height: 44px;
}
```

Two things are worth knowing before writing a theme.

The variables have to sit on the element container itself or on something inside it.
`.nvb-root` is where the tokens are declared, so a value set on an ancestor of it loses to
that declaration. Putting the override on the `<nvb-scope>` element works, because an
inline style wins over a class rule.

The neutral ramp is a surface system, not only text. `--nvb-color-neutral-000` paints the
background of panels, tab strips and accordions, `--nvb-color-neutral-300` draws their borders
and `--nvb-color-neutral-800` colours the field labels. A dark theme that sets only the
`--nvb-color-text-*` variables leaves all of those light and ends up half converted.

The full token list is in [Theming and design tokens](https://ngxviewbuilder.io/developers/theming).

## Translations

Two separate systems, and both are driven from the scope.

The strings the library ships with, such as the add row button or the confirmation dialog,
come from the UI dictionary registered once in your application:

```ts
provideNgxViewBuilderUiTranslations({
  lt: { 'confirm.confirm': 'Tęsti' },
});
```

The labels and placeholders you wrote in the configuration are translated from a dictionary
you pass to the scope, keyed by the structure path exactly as the builder exports it:

```html
<nvb-scope [(data)]="form" [language]="lang()" [translations]="texts">
```

```ts
texts = {
  lt: {
    'elements.email.label': 'El. paštas',
    'elements.email.placeholder': 'jonas@imone.lt',
  },
};
```

`language` switches both at once. A key with no translation keeps its original text.

## Layout and width

Several elements change their layout when their container gets narrow, and that is a
measurement of the container, not of the window. Tabs stack vertically and tables switch to
a label and value list below roughly 768 pixels of container width. On a wide screen inside
a narrow column that still counts as narrow, so if a table or a tab strip suddenly looks
like its mobile form, check how much width its column actually has.

## Alongside the runtime

A runtime component and standalone elements can sit on the same page. Each runtime creates
its own services, and so does each scope, so identical names on both sides are unrelated
keys and nothing collides. Styling is separate too, because the runtime renders inside a
shadow root and re-declares its tokens there.

One thing is shared. The runtime reports its measured content width to the whole
application, and that is what the width based layout switching reads. A runtime inside a
narrow column therefore makes every standalone element on the page believe the viewport is
that narrow. If you combine the two at very different widths, check the result.

## Reference

| Tag | Input | Purpose |
| --- | --- | --- |
| `<nvb-scope>` | `[(data)]` | Two way binding to the shared data object |
| | `[language]` | Language for both translation systems |
| | `[translations]` | Label translations, keyed by structure path |
| `<nvb-element>` | `[type]` | Element type, as written in a saved view |
| | `[config]` | The element's own configuration JSON |
| | `(valueChange)` | This element's value changed |
| | `(action)` | This element ran one of its actions |
| `<nvb-tab>` | `[value]` | Which tab of the parent tabs element the children belong to |

---

## Structure JSON

Source: https://ngxviewbuilder.io/developers/structure-json

# Structure JSON

`IStructure` is the single document that defines a view. The builder produces it; the runtime consumes it. It is plain JSON, safe to store in a database column, version, and diff.

```ts
interface IStructure {
  schemaVersion?: number;
  settings: ISettings;
  header?: IHeader;
  pages: IPage[];
  elements: Record<string, IBaseElement>;
  dataSources?: IDataSource[];
  localization?: ILocalization;
}
```

`schemaVersion` records the format the view was saved in, and the runtime upgrades anything older before rendering it. A document without the field is read as version 1. See [Schema versioning](https://ngxviewbuilder.io/developers/schema-versioning) for migrations and for what happens when the JSON is newer than the runtime.

## `pages`: layout

Layout is a tree of rows and columns; columns point at elements by name:

```json
"pages": [
  {
    "name": "page1",
    "rows": [
      { "columns": [ { "elementRef": "firstName" }, { "elementRef": "lastName" } ] },
      { "columns": [ { "elementRef": "detailsPanel",
                       "rows": [ { "columns": [ { "elementRef": "email" } ] } ] } ] }
    ]
  }
]
```

- Two `columns` in one row = side-by-side elements.
- Container columns nest their own `rows` (tabs use `tabRows` keyed by tab).
- Pages can carry `status`, `disabled`, `readOnly`.

## `elements`: configuration

A flat map keyed by element name. Every entry has at least `name`, `label`, `type`; everything else depends on the type:

```json
"elements": {
  "page1":     { "name": "page1", "label": "Page 1", "type": "page" },
  "firstName": {
    "name": "firstName", "label": "First name", "type": "text",
    "required": true, "width": "50%", "mobileWidth": "100%",
    "visibleIf": "{clientType} == \"person\""
  }
}
```

Common keys across types: `width`/`tabletWidth`/`mobileWidth`, `hidden`, `disabled`, `readOnly`, `required`, logic strings (`visibleIf`, `disableIf`, `requireIf`, `readonlyIf`, `resetIf`, `expression`, `defaultValue`), `validators`, `events`, `logicExecutionMode`, `validationExecutionMode`, `inheritParentState`. Element `type` values match `ElementTypesEnum` (`text`, `select`, `dynamicPanel`, `table`, …).

## `settings`: view-wide configuration

Everything from the Form settings tab: `width`/`widthUnit`, `language`, `locale`, `theme`, `elementSpacing`, page navigation (`pageNavigationMode`, positions, `showValidateButton`, `showSubmitButton`, `showValidationIssuesModal`), render mode (`renderMode: 'page' | 'dialog'` + `dialog*` keys), `customCss`, `customCssUrls`, `lazyElementRendering`, plus advanced blocks:

| Key | Holds |
| --- | --- |
| `variables` | [Runtime variable definitions](https://ngxviewbuilder.io/developers/runtime-variables) |
| `templates` + `templateStorage*` | Template library and its storage mode |
| `triggers` / `rules` / `process` / `fragments` | Platform automation definitions (used by plugins) |

## `dataSources`

```json
"dataSources": [
  { "name": "loadCountries", "title": "Countries", "type": "rest",
    "params": { "url": "https://api.example.com/countries", "method": "GET" } }
]
```

`type` ∈ `rest | route | local`; `params` are type-specific (see [Data sources](https://ngxviewbuilder.io/creators/data-sources)).

## `localization`

```json
"localization": {
  "defaultLanguage": "en",
  "languages": ["lt", "en"],
  "texts": { "en": { "elements.firstName.label": "First name" } }
}
```

## Working with structures in code

```ts
const model = new BuilderModel();
model.setJson(jsonString);            // load (normalises + fills defaults)
const structure = model.getJson();    // IStructure

// live, through the API service:
api.getStructure();
api.updateStructure((s) => { s.settings.theme = 'dark'; });
api.setStructure(newStructure);
```

## Versioning advice

- Treat the JSON as an artifact: store immutable versions, publish explicitly.
- Element **names are contracts**. Renaming one changes the submitted data shape and breaks expressions referencing it.
- Validate JSON against a staging runtime before publishing to production.

---

## Theming & design tokens

Source: https://ngxviewbuilder.io/developers/theming

# Theming & design tokens

All visuals derive from CSS custom properties (design tokens): color scales, fonts, radii. Theming = overriding tokens.

## Token families

| Family | Tokens | Used for |
| --- | --- | --- |
| Primary | `--nvb-color-primary-050 … 950` | brand, focus, active states |
| Neutral | `--nvb-color-neutral-000 … 950` | surfaces, borders, text |
| Risk / Warning / Caution | `--nvb-color-risk-*`, `--nvb-color-warning-*` | destructive & warning states |
| Success / Info | `--nvb-color-success-*`, `--nvb-color-info-*` | positive & informational states |
| Typography | `--nvb-font-family-base` | base font stack |

Values are `oklch(...)` colors on an 050-950 scale (050 lightest). Components mix tokens with `color-mix()`, so overriding a scale re-colors everything consistently.

## Where the tokens live

Every name carries the `nvb-` prefix, and the declarations sit on `.nvb-root` and on the runtime's shadow host, never on `:root`. Both parts matter for a host application.

The prefix keeps our palette out of yours. A design system that stores its colors as HSL channel triplets for Tailwind writes `--color-neutral-300: 214 32% 91%`, and before 0.4.0 we declared that same name as an oklch color. Ours won inside the view, so any host rule that still applied there computed `hsl(oklch(...))`, which is not a color at all, and the declaration fell back to `currentColor`. Inputs came out with thick black borders and nothing in the browser pointed at the cause.

Not putting them on `:root` keeps the reverse true: importing our stylesheet cannot change how the rest of your application looks.

`--nvb-surface` is the one token meant for the host rather than for us. `.nvb-root` paints its own background so a light theme stays readable on a dark page, and setting `--nvb-surface: transparent` turns that off when the view already sits on a surface you control.

## Light / dark mode

```html
<ngx-view-builder-builder [theme]="'dark'" ... />
<ngx-view-builder-runtime  [theme]="theme()" ... />
```

or `api.setThemeMode('dark')`. Creators can also set a default in Form settings.

## Overriding tokens

**Quick overrides**, a flat map applied on top of the active theme:

```ts
api.setCssVariables({
  '--nvb-color-primary-500': 'oklch(64% 0.19 145)',   // brand green
  '--nvb-font-family-base': "'Inter', sans-serif",
});
```

or declaratively: `[cssVariables]="{ '--nvb-color-primary-500': '...' }"`.

**Full custom theme**, with per-mode token sets:

```ts
api.setCustomTheme({
  shared: { '--nvb-font-family-base': "'Inter', sans-serif" },
  light:  { '--nvb-color-primary-500': 'oklch(64% 0.19 145)' },
  dark:   { '--nvb-color-primary-500': 'oklch(72% 0.17 145)' },
  mergeWithDefaults: true,     // start from the built-in theme
});
```

`runtimeSettings.customTheme` accepts the same object at bootstrap.

## Custom elements & theming

Write custom element styles against the tokens and they follow every theme automatically:

```css
.note {
  background: color-mix(in oklab, var(--nvb-color-info-100) 24%, var(--nvb-color-neutral-000));
  border: 1px solid var(--nvb-color-neutral-300);
  color: var(--nvb-color-neutral-900);
}
```

Never hardcode hex colors in element components; dark mode will break.

## Related events

`onThemeModeChanged`, `onCustomThemeChanged`, `onCssVariablesChanged` fire on every change, which is handy for syncing the host app's own chrome.

For per-view CSS (rather than tokens), see [Custom CSS](https://ngxviewbuilder.io/developers/custom-css).

---

## UI translations

Source: https://ngxviewbuilder.io/developers/ui-translations

# UI translations

Two translation systems exist. Don't mix them up:

| System | Translates | Managed by |
| --- | --- | --- |
| **Content translations** | the view's labels, options, messages | creators, in the [Translations tab](https://ngxviewbuilder.io/creators/translations) |
| **UI dictionaries** | the builder/runtime chrome: tabs, buttons, property editor labels | developers (this page) |

## Providing dictionaries

```ts
import { provideNgxViewBuilderUiTranslations } from 'ngx-view-builder';
import { LT_UI_DICTIONARY } from './i18n/lt';

providers: [
  provideNgxViewBuilderUiTranslations({ lt: LT_UI_DICTIONARY }, { language: 'lt' }),
]
```

## Starting from the built-in English dictionary

The library exports its own complete English dictionary, every translatable key with its default text, so you don't have to hunt them down one by one:

```ts
import { EN_UI_DICTIONARY } from 'ngx-view-builder';

console.log(Object.keys(EN_UI_DICTIONARY).length); // every translatable key
```

Copy it, translate the values, keep the keys:

```ts
// i18n/de.ts
import { EN_UI_DICTIONARY } from 'ngx-view-builder';

export const DE_UI_DICTIONARY: Record<string, string> = {
  ...EN_UI_DICTIONARY,
  'eventAction.action.validate': 'Validieren',
  'eventAction.action.submit': 'Absenden',
  // ...translate the rest
};
```

This is also the fastest way to spot **missing** translations in a dictionary you already maintain: diff its keys against `Object.keys(EN_UI_DICTIONARY)`.

A dictionary is a nested/flat map of key → text, keyed by language code. Other channels:

```ts
api.setUiDictionaries({ lt: LT_UI_DICTIONARY }, /* merge */ true);
// or per component: [uiDictionaries]="dicts"
// or inside extensions config: { uiDictionaries: { lt: {...} } }
```

## Using translations in host code

Host UI that lives next to the builder (header actions, toolbars) can reuse the same dictionaries:

```ts
label: this.api.translateUi('host.actions.save.label', 'Save'),
```

`translateUi(key, fallback)` returns the fallback when the key is missing, so it is always safe to call. A `uiTranslate` pipe is exported for templates.

## Language resolution & sync

Match the builder language to your app automatically:

```ts
const handle = this.api.startLanguageSync({
  hostLanguageResolver: () => this.i18n.currentLang,
  supportedLanguages: ['lt', 'en'],
  fallbackLanguage: 'en',
  watchDocumentLanguage: true,   // follows <html lang="">
  applyLocale: true,             // also sets number/date locale
});
// handle.refresh(); handle.stop();
```

One-off resolution: `api.resolveHostLanguage(...)` / `api.applyHostLanguage(...)`; direct control: `api.setLanguage('lt')`, `api.setApplicationLocale('lt-LT')`.

## Workflow for a new language

1. Start from `EN_UI_DICTIONARY` (exported by the library, see above), or the demo app's complete `lt` dictionary in `projects/test-app/.../lt.ts` for a worked example.
2. Translate the values; keep the keys.
3. Register via the provider; set `language` or wire `startLanguageSync`.
4. Untranslated keys fall back to built-in English texts.

---

## Upgrading to 0.4.0

Source: https://ngxviewbuilder.io/developers/upgrading-0-4-0

# Upgrading to 0.4.0

One idea runs through this release: nothing the library puts into your stylesheet answers to a generic name any more. 1145 classes and 144 custom properties gained an `nvb-` prefix.

The rename is mechanical, but it is not cosmetic. Sharing names with a host application broke real applications in ways that were hard to trace back, and the two bugs fixed alongside it were both symptoms of the same idea being applied too loosely.

## What changed

| Before | After |
| --- | --- |
| `.field`, `.field__label` | `.nvb-field`, `.nvb-field__label` |
| `.box`, `.panel`, `.row`, `.column` | `.nvb-box`, `.nvb-panel`, `.nvb-row`, `.nvb-column` |
| `.dropdown`, `.input-wrapper`, `.select-container` | `.nvb-dropdown`, `.nvb-input-wrapper`, `.nvb-select-container` |
| `.preview-form-body`, `.page__header` | `.nvb-preview-form-body`, `.nvb-page__header` |
| `--color-primary-500`, `--color-neutral-300` | `--nvb-color-primary-500`, `--nvb-color-neutral-300` |
| `--radius-md`, `--space-3`, `--text-body1` | `--nvb-radius-md`, `--nvb-space-3`, `--nvb-text-body1` |

Names that were never ours are untouched, so `cdk-*`, `ng-*`, `cm-*` and `material-symbols-outlined` stay exactly as they were.

## Why the custom properties mattered most

The class rename fixes an ordinary collision: a host rule such as `.field { border: 2px solid }` used to land on our fields, because our `.field` set no border of its own and nothing was there to compete.

The token rename fixes something less obvious. A design system that feeds Tailwind stores its palette as HSL channel triplets:

```css
:root {
  --color-neutral-300: 214 32% 91%;
}
```

We declared the same name as an oklch color on `.nvb-root`, and inside a view ours won. Any host rule that still applied there, a global `input` style for instance, then resolved to `hsl(oklch(86.94% 0.0199 253.37) / 1)`. That is not a color, so the whole declaration fell back to `currentColor`, and inputs appeared with thick black borders that matched the text. Nothing in the browser pointed at the palette.

Both palettes now coexist, because they no longer share a single name.

## Fixing your integration

Search your own code for the old names. Most projects have only a handful of hits, usually in one place.

```bash
grep -rnE "\.(field|box|panel|row|column|dropdown|page|view|preview-[a-z-]+)\b" src
grep -rn -- "--color-\|--radius-\|--space-\|--text-" src
```

Four places tend to have them:

**Host stylesheets and directives** that reach into a rendered view. Add the prefix.

**Saved views**, in `settings.customCss`. These live in your database rather than your repository, so they are the easiest to forget. There is no automatic migration, because rewriting CSS a creator wrote is not something a migration should do quietly.

**Theme variables** passed through `api.setCssVariables()`, `setCustomTheme()` or `runtimeSettings`. Keys have to match the new names or the override does nothing.

**Custom element and template CSS** that reads tokens, such as `var(--color-neutral-300)`.

If you have to support both versions for a while, list both spellings side by side. A selector list costs nothing and lets the change land before the package bump:

```css
.nvb-page__header,
.page__header {
  display: none;
}
```

## Two fixes worth knowing about

**Floating panels no longer open in the wrong place.** Menus use `position: fixed` and were positioned from viewport coordinates, which the browser resolves against the nearest ancestor that establishes a containing block. Host applications create one routinely with `transform`, `filter` or `will-change`, and the menu then landed off by the whole scroll offset. On a long form that is hundreds of pixels, far enough to look as though clicking did nothing at all. Select, multi select, autocomplete, phone country, datepicker, date range, time picker and label tooltips now resolve their real containing block first.

**Views stay readable on a dark page.** `.nvb-root` now paints its own surface and declares its color scheme rather than borrowing whatever the host uses. Previously the near black labels disappeared into a dark background while the inputs kept their own white fill and looked correct, which read as the labels being missing. Set `--nvb-surface: transparent` where a view already sits on a surface you control.

See [Theming](https://ngxviewbuilder.io/developers/theming) for the token families and [Layer order](https://ngxviewbuilder.io/developers/installation#layer-order) if your application uses cascade layers.

---

## Headless validation

Source: https://ngxviewbuilder.io/developers/validator

# Headless validation

Two tools cover validation outside the normal UI flow.

## In-app: `api.validateData()`

For a rendered view, validate programmatically through the API service:

```ts
const result = await this.api.validateData({
  emitValidationEvent: true,
  includeHidden: false,
  includeDisabled: false,
});
// result: { isValid: boolean, issues: [{ elementName, dataPath, errors[] }] }
```

## Standalone: `<ngx-view-builder-validator>`

A component with no visible UI that loads a structure + data, runs the full runtime validation (including expressions), and emits the result. Designed for validation services, e.g. a small Angular app rendered server-side or in a headless browser that your backend calls to verify submissions with the *same* rules the form used.

```html
<ngx-view-builder-validator
  [pageJson]="structure"
  [dataJson]="submittedData"
  [autoValidateOnInit]="true"
  (validated)="onValidated($event)"
  (validationError)="onError($event)"
/>
```

| Input | Default | Purpose |
| --- | --- | --- |
| `pageJson` / `dataJson` | - | Structure and data to validate |
| `autoValidateOnInit` | `true` | Validate immediately |
| `backendUrl` / `validatePath` | `http://127.0.0.1:8010` / `/validate` | Remote validation endpoint mode |
| `waitMs` / `timeoutMs` | `300` / `45000` | Stabilisation delay and timeout |
| `headlessApiKey` | `__NGX_VIEW_BUILDER__` | Global API key for headless drivers |
| `sessionHeaderName` / `sessionKey` / `requestHeaders` | - | Auth headers for the remote mode |

You can also call `validate()` on the component instance for on-demand runs.

## Global headless API

For E2E tests and headless automation, expose a global validation API at startup:

```ts
inject(ForgeInitializerService).load({
  exposeHeadlessValidationApi: true,
  headlessValidationApiKey: '__NGX_VIEW_BUILDER__',
});
```

The driver (Playwright, Puppeteer…) can then invoke validation through `window.__NGX_VIEW_BUILDER__`.

## Why server-side validation matters

Client-side rules protect UX, not integrity. Re-run the same structure + data through the validator on trusted infrastructure before persisting anything. The definitions are identical, so rules never drift between client and server.

---

## Angular form builder for creators

Source: https://ngxviewbuilder.io/creators/

# Introduction for creators

NGX View Builder is a visual builder. You drag elements onto a canvas, configure them in the properties sidebar, and the result is a complete view (a form, a data screen, or a multi-step flow) that the application renders to end users.

You never write Angular code. Everything you configure is stored as a view definition (JSON) that developers plug into the application.

## The mental model

Every view has three layers:

1. **Structure**: pages, panels, tabs, and other containers that organise the screen.
2. **Elements**: inputs, choices, buttons, tables, and content blocks placed inside the structure.
3. **Behaviour**: validation, conditional logic, expressions, events, and data sources.

At runtime, every element with a `name` writes its value into the form result under that name. If a text field is named `customerEmail`, the submitted data contains `{ "customerEmail": "..." }`.

::: tip Names matter
Give every value-producing element a short, stable name like `firstName` or `deliveryDate`. Names become data keys and are how expressions reference other fields, as in `{firstName}`.
:::

## What you can build

- **Forms**: registrations, applications, questionnaires, with validation and conditional sections.
- **Data screens**: tables with filters, editable rows, charts, status badges, and action buttons.
- **Guided flows**: multi-page steppers where each step validates before continuing.
- **Content pages**: rich text, images, video, and reusable HTML templates.
- **Dynamic views**: dropdowns, tables, and charts fed by live REST data.

## Where to go next

| I want to… | Read |
| --- | --- |
| See the builder screen areas | [The builder workspace](https://ngxviewbuilder.io/creators/workspace) |
| Build something right now | [Your first form](https://ngxviewbuilder.io/creators/first-form) |
| Find the right element | [Elements overview](https://ngxviewbuilder.io/creators/elements/) |
| Show/hide fields conditionally | [Conditional logic](https://ngxviewbuilder.io/creators/conditional-logic) |
| Load options from an API | [Data sources](https://ngxviewbuilder.io/creators/data-sources) |
| Validate user input | [Validation](https://ngxviewbuilder.io/creators/validation) |

Or open the [live demo](https://ngxviewbuilder.io/demo) from the **Demo** link in the top menu and explore as you read.

---

## Calculated values

Source: https://ngxviewbuilder.io/creators/calculated-values

# Calculated values

Two Logic properties produce values instead of true/false.

## Expression

**Expression** continuously calculates the element's value. Whenever a referenced field changes, the result is recomputed and written into the field.

```text
{price} * {quantity}                            line total
{firstName} + " " + {lastName}                  full name
{isCompany} ? {companyCode} : {personalCode}    pick one of two codes
sumInArray({orderLines}, "total")               sum over table rows
```

Rules of thumb:

- A field with an Expression is effectively computed, so combine it with **Read only** and users won't fight the recalculation.
- Never reference the field itself; self-referencing expressions are skipped with a console warning.
- On **Number** elements the result respects the element's formatting settings (fraction digits, locale).
- If the expression errors or returns nothing, the value is cleared.
- To land the result somewhere else instead of in this field, write it: `{variable1} = sumInArray({orderLines}, "total")`. See [Writing values back](https://ngxviewbuilder.io/creators/functions#writing-values-back).

## Default value

**Default value** sets the initial value once, on load. The user can overwrite it.

Three forms:

| Form | Example | Result |
| --- | --- | --- |
| Static text | `Draft` | literal "Draft" |
| Token | `{__variables.route.id}` | resolved at load |
| Expression (prefix `=`) | `=today()` | evaluated at load |

Common defaults:

```text
=today()                        today's date
{__external.userName}           current user from the host app
{__variables.route.clientId}    id from the URL
"LT"                            fixed country pre-selection
```

## Expression vs. Default value

| | Expression | Default value |
| --- | --- | --- |
| When it runs | continuously | once at load |
| User can override | no (recalculated) | yes |
| Use for | totals, derived fields | sensible starting values |

## Worked example: invoice line

| Element | Type | Setup |
| --- | --- | --- |
| `quantity` | Number | Default value `1` |
| `unitPrice` | Number | filled from a product data source |
| `discount` | Number | Default value `0` |
| `lineTotal` | Number, read-only | Expression: `{quantity} * {unitPrice} * (1 - {discount} / 100)` |

---

## Expression cheat sheet

Source: https://ngxviewbuilder.io/creators/cheat-sheet

# Cheat sheet

## Tokens

```text
{country}                     field value
{row.status}                  current table row
{panel.index}                 current dynamic-panel entry index
{parentIndex}                 index in the surrounding repeater
{__variables.route.id}        variable (route param)
{__external.userRole}         host-app context
{myTabs.selectedTab}          active tab name
{flow.selectedStepIndex}      active step index
```

## Quick patterns

```text
{country} == "US"
isEmpty({companyCode})
notEmpty({email}) && notEmpty({phone})
contains({roles}, "admin")
containsAny({roles}, ["admin", "manager"])
{price} * {quantity}
len({selectedItems}) > 0
inRange({age}, 18, 65)
```

## If / else (ternary)

```text
{isCompany} ? {companyCode} : {personalCode}
{country} == "US" ? "Domestic" : "International"
{quantity} > 0 ? {sum} / {quantity} : 0
```

Nested:

```text
{status} == "approved" ? ({isVip} ? "Priority" : "Standard") : "Draft"
contains({roles}, "admin") ? "Full access"
  : (contains({roles}, "editor") ? "Editing" : "Read only")
```

## Arrays & aggregation

```text
sumInArray({orderLines}, "amount")
countInArray({employees}, "id")
contains(collectValuesFrom({employees}, "role", true), "manager")
joinInArray({tags}, "name", ", ")
sumArray({el1}, el5[].column3)               through a dynamic panel
flattenArray(collectValuesFrom({el1}, el5[]))  all rows in one list
```

## Writing a value

```text
{variable1} = {price} * {quantity}           set
{variable1} += {row.column3}                 add, use from an action
setValue({variable1}, sumArray({el1}, el5[].column3))
pushValue({variable1}, {row})
{el4.column1-total}                          published column total
```

## Dates

```text
=today()                                     default value: today
addDays(today(), 14)                         two weeks from now
dateDiffDays({startDate}, {endDate}) >= 1    end after start
isWeekend({deliveryDate})                    weekend check
```

## Row & panel context

```text
row.status == "active"
panel.amount > 1000
{el1[parentIndex].country} == "US"
```

## Template placeholders

Inside option templates, card templates, and dynamic text (double braces):

```text
{{label}}   {{value}}   {{index}}   {{selected}}
{{ item.name }}   {{ item.status }}
@if (item.status == "Active") {<span>{{ item.status }}</span>}
```

## Debug

```text
dbg({clientType}, "clientType")     log to console, value passes through
```

---

## Conditional logic

Source: https://ngxviewbuilder.io/creators/conditional-logic

# Conditional logic

Five properties in the **Logic** category control element state. Each takes a true/false [expression](https://ngxviewbuilder.io/creators/expressions) and re-evaluates automatically when referenced fields change.

| Property | While the expression is true… |
| --- | --- |
| **Visible if** | the element is shown (hidden otherwise) |
| **Disable if** | the element is visible but inactive |
| **Require if** | the element is required |
| **Read only if** | the value is visible but locked |
| **Reset if** | *the moment it becomes true*, the value is cleared/reset to default |

## Visible if

```text
{clientType} == "company"            show for companies only
!isEmpty({email})                    show once email is entered
contains({services}, "delivery")     show when "delivery" was picked
```

Put `visibleIf` on a **panel** to toggle a whole section at once. A hidden element keeps its configuration but is skipped in validation by default.

## Disable if

```text
{approvalStatus} == "approved"       lock after approval
{age} < 18                           inactive for minors
!containsAny({roles}, ["admin", "editor"])
```

Use *disable* when the user should see that the option exists; use *visible* when it's irrelevant.

## Require if

```text
{personType} == "company"            company code required for companies
{amount} > 10000                     justification required for large sums
{country} != "LT"                    tax ID required for foreign clients
```

## Read only if

```text
{status} == "submitted"              freeze after submission
notEmpty({externalReference})        imported values can't be edited
{__variables.mode} == "view"         whole form in view mode
```

## Reset if

Clears stale answers when their premise disappears:

```text
{personType} != "company"            clear companyCode when switching to person
!contains({supportTypes}, "training")   clear trainingDate if training unselected
```

Without a reset rule, a hidden field keeps its old value, and that value is still submitted.

## Logic inside repeaters

Inside a **Dynamic panel** or a **Dynamic table**, the same five properties are evaluated once per row, against that row's own values. Write the condition with the row context rather than a field name:

```text
panel.dpDriver > 10        dynamic panel: this entry's field
row.quantity > 0           dynamic table: this row's cell
```

Each row then decides for itself. In a panel of order lines, `visibleIf: panel.quantity > 0` hides the discount field only in the lines that have no quantity, and leaves the other lines untouched. The same goes for **Require if**, so a row can be mandatory while its neighbours are not.

Referring to a plain field name inside a repeater still points at the form-level field of that name, which is what you want for conditions like `visibleIf: {orderType} == "wholesale"` applied to every row at once.

## When the rule re-runs

A rule is re-evaluated according to the element's **Logic execution mode**, in the Behavior category. Left alone it is **On blur**, so the rule waits until the field loses focus. That suits a heavy expression on a long text field and almost nothing else: someone typing an amount watches the dependent field sit still and concludes the logic is broken.

Set it to **On change** on any element whose rule should follow the typing. Validation has its own **Validation execution mode** with the same default, so set that one as well when an error should appear while the user types rather than after they leave the field.

## Several logic properties on one element

They are independent and all apply. An element can be visible, required, and read only at the same time, and the combination is resolved in one pass, so the field is correct on the first change rather than after a second edit.

```text
Visible if    {n1} > 10
Require if    {n1} > 10
Read only if  {approved} == true
```

## Complete example

Order form: *"Deliver to a different address?"* (single checkbox `otherAddress`) with a delivery panel:

| Element | Property | Expression |
| --- | --- | --- |
| Panel `deliveryPanel` | Visible if | `{otherAddress} == true` |
| Text `deliveryStreet` | Require if | `{otherAddress} == true` |
| Text `deliveryStreet` | Reset if | `{otherAddress} != true` |

Result: the section appears only when needed, is mandatory when shown, and cleans up after itself when hidden.

---

## Data sources

Source: https://ngxviewbuilder.io/creators/data-sources

# Data sources

A data source is a named connection to data, usually an API endpoint. You define sources once per view in the bottom **DataSources** tab, then bind elements to them. Sources are referenced everywhere by **name**.

## The source editor

Click **Add Source** in the bottom DataSources tab. Every source has:

| Field | What it does |
| --- | --- |
| **Name** | The technical name used everywhere else (`loadClients`, `saveOrder`). |
| **Title** | A friendly display title for the list. |
| **Type** | `REST`, `Route data`, `Local JSON`, or `WebSocket` when your developer has enabled it. |

### REST

| Field | What it does |
| --- | --- |
| **Url** | The endpoint, with optional `{placeholders}`: `https://api.example.com/clients/{clientId}`. Required: actions using a URL-less REST source warn in the editor. |
| **Method** | `GET`, `POST`, `PUT`, `DELETE`… or `TABLE-POST`, a special method for a **Table**'s data source that sends a real `POST` but automatically adds the current page, sort, and search state to the request body. Ask your developer to read [Table: server-side paging & filtering](https://ngxviewbuilder.io/developers/data-sources#table-server-side-paging-filtering-table-post) for the exact shape. |
| **Request body (optional)** | JSON template with `{…}` placeholders. Example: `{"rows":"{__table.el1.selectedRows}"}`. Use `{id}` style tokens for the URL and `{__table.el1.selectedRows}` style paths in the body. |
| **Data path** | Where the useful data lives in the response (e.g. `data.items`). |

`{placeholders}` are filled from the request params you map on the element or action. If a required placeholder has no value yet, the request is skipped: a city list bound to `{countryId}` stays empty until a country is picked.

### Route data

| Field | What it does |
| --- | --- |
| **Route data key** | Key in the Angular route's resolver/data object. |
| **Data path (optional)** | Path inside that object. |

### Local JSON

| Field | What it does |
| --- | --- |
| **Local mode** | `JSON` (inline data) or `Another question value` (points at existing form data). |
| **JSON data** | The inline JSON when mode is `JSON`. |
| **Local function** | Optionally call a JS function for the data. Example: `window.myFunction` or `this.myFunction`. |

### WebSocket

A REST source answers once, when something asks it. A WebSocket source stays connected and keeps handing you whatever the server sends, so the view moves on its own: a dashboard counter, a queue, an order that someone else just changed.

The connection opens the first time something on the page uses the source, and closes when the last thing using it goes away. Every message after that lands in the bound elements without anyone pressing anything.

| Field | What it does |
| --- | --- |
| **Url** | The endpoint, starting with `ws://` or `wss://`. Use `wss://` anywhere that is not your own machine. |
| **Protocols (optional)** | Comma separated subprotocol names, if your server asks for them. |
| **Message (optional)** | Sent once, right after the connection opens. This is where a subscribe or handshake payload goes. It is not sent again later. |
| **Message path (optional)** | Where the useful part of each message lives, for example `rows`. Leave it empty to take the whole message. |
| **Message mode** | `Replace current` keeps only the latest message, which is what a live value or a refreshing table wants. `Push values in array` collects messages into a growing list, for a feed or a log. The list keeps the most recent 500 entries. |

Binding works exactly like any other source. Point a table at it with **Use as: Value**, or feed a [variable](https://ngxviewbuilder.io/creators/variables) from it and read the variable in expressions.

::: tip Two sources, one connection
Several sources pointing at the same url share a single connection, so a page with a table on `rows` and a counter on the whole payload still opens one socket. Give each source its own **Message path** rather than duplicating the endpoint.
:::

#### Showing whether the data is live

Stale numbers that look live are worse than an honest gap, so the runtime publishes the state of every socket under `__socket.<source name>`:

| Path | What it holds |
| --- | --- |
| `{__socket.liveFeed.connected}` | `true` while the connection is up, `false` while it is not. |
| `{__socket.liveFeed.lastMessageAt}` | Timestamp of the last message received. |
| `{__socket.liveFeed.reconnects}` | How many times the connection came back by itself. |
| `{__socket.liveFeed.url}` | The endpoint actually connected to. |

A read-only text element with `visibleIf: {__socket.liveFeed.connected} == false` and a label like "Connection lost, values are from a moment ago" is usually all a form needs.

Reconnecting is automatic. A dropped connection is retried with a growing delay, and once the server is back the view carries on without a page refresh.

#### Sending something back

The **Message** field only fires at connection time. To push something later, put a **Send socket message** action on a button: pick the WebSocket source and write the payload. See [Actions](https://ngxviewbuilder.io/creators/events-actions#send-socket-message).

#### Object creator

For non-trivial JSON, the **Object creator** dialog builds a valid object visually instead of hand-typing:

| Field | What it does |
| --- | --- |
| **Root type** | Whether the root is an object or array. |
| **Add root field / Add field / Add nested field** | Grow the structure; objects and arrays can contain nested fields. |
| **Field name** | The JSON key. |
| **Type** | `Object`, `Array`, `Property`, or a plain value (`Text`, `Number`, `Boolean`, `Null`). |
| **Value / other field name** | The literal value, or a reference to another field. |
| **Binding path** | Use `{path}` to bind to live form data, or a static value. |
| **JSON preview** → **Insert into JSON** | Review the generated JSON, then insert it into the source. |

## Binding a source to an element

Choice elements, tables, list grids, and charts have a **Data source** binding in the **Primary source** section of the properties sidebar:

| Field | What it does |
| --- | --- |
| **Data source** | Which source feeds this element. Dependent fields are supported via the param map and refresh paths. |
| **Use as** | `Option` loads selectable options (select, radio, checkbox); `Value` loads the field's own value. |
| **Option value key / Option label key** | Which response fields become the stored value and the visible label. |
| **Items path** | Where the array lives in the response (e.g. `data.items`). |
| **Filter options by** | Legacy conditional filter, leave empty if unused. Prefer the *Filter if equal / not equal* option properties. |
| **Param mapping** | One row per `{placeholder}`: **Param** (the placeholder name) → **Value / `{path}`** (a form path, variable, or plain value). **Auto from params** pre-fills rows from the URL/body placeholders. Only used for REST URL/body placeholders. |
| **Reload source when mapped question value changes** (*React to change*) | Auto-reload when a mapped param's value changes. |
| **Listen fields** | Comma-separated extra paths to watch (e.g. `el1` or `panel.userId`). If empty, the system auto-detects from URL placeholders and the param mapping. |
| **Lazy load** | Fetch on demand: tables load per page/sort, autocomplete loads as the user types. |

## Example: country → city dropdowns

1. Define sources: `loadCountries` (`GET /api/countries`) and `loadCities` (`GET /api/cities?country={countryId}`).
2. Element `country` (Select): data source `loadCountries`, use as `Option`, value key `code`, label key `name`.
3. Element `city` (Select): data source `loadCities`, param `countryId = {country}`, **React to change** on.

Picking a country now reloads the city list automatically; before any pick, the city list stays empty because `{countryId}` is missing.

## Filling values (not options)

With **Use as: Value**, the response is written into the element. A whole panel of read-only fields can be populated by one `GET /api/clients/{id}` source whose params come from `{__variables.route.id}`.

## Saving data

Saving goes through [actions](https://ngxviewbuilder.io/creators/events-actions): a button's `dataSource` action calls a `POST`/`PUT` source, passing fields via **Placeholder mapping** or the whole form as the body template. Combine with *Validate whole form before action*, *Elements to reload*, and *Show toast after successful action*.

## Reloading from expressions

`runDataSource("loadUsers")` inside any expression re-runs a source, which is occasionally useful in advanced logic. Prefer element bindings with **React to change** for normal flows.

---

## Buttons & actions

Source: https://ngxviewbuilder.io/creators/elements/buttons

# Buttons & actions

## Button (`button`)

A button does nothing by itself. Its behaviour comes from the **actions** you attach in the **Actions** category. One button can run several actions in order.

### Content properties

| Property | What it does |
| --- | --- |
| **Text** | The visible caption |
| **Badge** | A small counter/label next to the caption |
| **Loading mode** | Shows a spinner instead of the icon (usually driven by logic) |

### Design properties

| Property | What it does |
| --- | --- |
| **Variant** | `solid`, `outline`, `text` |
| **Size** | `small`, `normal`, `large` |
| **Tone** | `primary`, `neutral`, `success`, `info`, `warning`, `risk` |
| **Icon** | Material Symbol or registered SVG icon code |
| **Icon position** | `left`, `right`, `top`, `bottom` |
| **Icon only** | Show only the icon, no text |
| **Color / Text color** | Manual color overrides (text color is handy on light backgrounds) |
| **Width / Mobile width / Fit content** | Sizing per breakpoint |

### Dropdown actions

The **Dropdown actions** property turns the button into a menu: each entry is its own action with a label and icon. Use it for secondary operations (*Export*, *Duplicate*, *Delete*).

## Typical buttons

**Submit button**

- Action: trigger `click`, **Validate form** on, type `dataSource` → your save endpoint.
- After success: `showToastAfter` with a success message, or a `navigate` action to a confirmation page.

**Cancel button**

- Variant `text`, tone `neutral`.
- Action: type `navigate` to the previous page, with **Confirm on dirty** enabled so unsaved changes prompt the user.

**Delete button**

- Tone `risk`.
- Action: type `dataSource` with **Confirm enabled**, title `Delete client?`, message `This cannot be undone.`

## Conditional buttons

Buttons support logic like any element:

```text
visibleIf:  {status} == "draft"        → show only for drafts
disableIf:  !{agreeTerms}              → inactive until terms accepted
```

For the full action reference (triggers, action types, confirmations, and response handling) see [Events & actions](https://ngxviewbuilder.io/creators/events-actions).

---

## Choice inputs

Source: https://ngxviewbuilder.io/creators/elements/choices

# Choice inputs

All choice elements share the same two ways of getting their options:

1. **Static options**, in the **Options** section: add label/value pairs by hand.
2. **Data source**, in the **Primary source** section: load options from an API and map which response fields become the value and label. See [Data sources](https://ngxviewbuilder.io/creators/data-sources).

The stored value is always the option **value** (not the label).

## Options: shared fields

Each manual option row has:

| Field | What it does |
| --- | --- |
| **Label** | Text the user sees. |
| **Value** | What is stored in the data. |
| **Condition** (*visibleIf*) | Show this option only when an expression is true, e.g. `{el1} == 1`. |
| **Icon** / **Badge** | Extra visuals where the element supports them (Select button). |

Shared option-related properties:

| Property | What it does |
| --- | --- |
| **Use as number** | Converts the option value to a number when storing. |
| **Filter if equal / Filter if not equal** | Show an option only if its value equals / does not equal the given value or `{field}`. Gives you quick dependent lists without a server call. |
| **Strict options** | Validates that the current value(s) still exist among the available options. |
| **Option template** / **Option template ref** | Custom HTML per option row (<code v-pre>{{label}}</code>, <code v-pre>{{value}}</code>, <code v-pre>{{selected}}</code>), inline or from the [template library](https://ngxviewbuilder.io/creators/templates); the ref wins. |

## Select (`select` / dropdown)

The standard dropdown. Best default for 5+ options.

| Property | What it does |
| --- | --- |
| **Show search** | Adds a search box inside the dropdown. |
| **Placeholder text** | Shown while nothing is selected. |
| **Option value key / Option label key** | Which response fields become value and label (data-source options). |

## Multi-choice menu (`multiSelect`)

Like Select, but stores an **array** of values. Use `contains({tags}, "vip")` in expressions to check membership. Has the same search/placeholder/template properties as Select, plus clear-selections controls.

## Autocomplete (`autocomplete`)

Type-ahead search. Best for long lists (clients, cities, products).

| Property | What it does |
| --- | --- |
| **Lazy load** | Fetch options as the user types instead of upfront. |
| **Min search length** | Characters required before a lazy search fires. |
| **Debounce (ms)** | Time between the last keystroke and the request. |
| **Max suggestions** | How many suggestions to show. |
| **Force selection** | Only values picked from the list are allowed; free-typed text is cleared. |

## Radio (`radio`)

All options visible, one selectable. Best for 2-5 options that users should compare side by side.

| Property | What it does |
| --- | --- |
| **Show inline** | Options in a single row instead of stacked. |

## Checkbox group (`checkbox`)

All options visible, many selectable. Stores an array. Also supports **Show inline**.

## Single checkbox (`singleCheckbox`)

One yes/no checkbox storing `true`/`false`. Use for confirmations: *"I agree to the terms"* + `required`/`requireIf`.

| Property | What it does |
| --- | --- |
| **Checkbox label** | The text next to the box. Make the option readable without extra context. |

## Toggle switch (`toggleSwitch`)

A styled on/off switch. Same data as Single checkbox, different look. Better suited to settings-style screens.

| Property | What it does |
| --- | --- |
| **Toggle mode** | `checkbox` returns `true`/`false`; `toggle` allows custom on/off values. |
| **True value / False value** | Custom stored values in toggle mode: text, number, or JSON. |
| **On label / Off label** | Texts for the two states. |

## Select button (`selectButton`)

A row of connected buttons, a visual alternative to Radio for 2-4 short options (e.g. `Person | Company`).

| Property | What it does |
| --- | --- |
| **Options** | Rows with `label`, `value`, `icon`, `badge`, and `visibleIf`. |
| **Multiple** | Allow several active buttons; the value becomes an array. |
| **Allow empty** | In single mode, clicking the active button again deselects it. |
| **Show selected icon** | Check mark on active buttons. |

## List box (`listBox`)

A permanently open scrollable list with selection. Useful when choosing is the main task of the screen.

## Choosing between them

| Situation | Element |
| --- | --- |
| 2-4 options, single choice | Radio or Select button |
| 5+ options, single choice | Select |
| Long list, single choice | Autocomplete |
| Few options, multiple choice | Checkbox group |
| Many options, multiple choice | Multi-choice menu |
| Yes/no | Single checkbox or Toggle switch |

---

## Containers

Source: https://ngxviewbuilder.io/creators/elements/containers

# Containers

Containers hold other elements. Most produce no data themselves; the exceptions are **Dynamic panel** (an array of entries) and **Tabs** (whose active tab can be read in expressions).

## Panel (`panel`)

A titled box that groups related fields.

| Property | What it does |
| --- | --- |
| **Label / Description** | Panel heading and sub-text. **Hide header** removes the heading row. |
| **Background color** | Panel surface color (e.g. `#ffffff`). **Remove background** disables it entirely. |
| **Border style / color / width** | `solid`, `dashed`, `dotted`, `double`; color like `#d9dce3`; thickness like `1px`. **Borderless** removes the border. |
| **Radius** | Corner radius (e.g. `12px`). |
| **Shadow** | CSS shadow (e.g. `0 8px 24px rgba(0,0,0,.12)`). |
| **Padding / Mobile padding** | Inner spacing per breakpoint (e.g. `12px` or `1rem`). |
| **Min height / Max height / Height / Fit content** | Sizing; content past *Max height* scrolls (see *Overflow*). |
| **Overflow** | `visible`, `auto`, `hidden`, `scroll`, `clip`. |
| **Opacity / Backdrop filter** | Transparency and glass-style effects. |
| **Background image (+ position, size, repeat, overlay color, blend mode)** | Full image-background support for hero panels and cards. |
| **Content display** | How children lay out: `flex` or `grid`. |
| **Flex direction / Content gap / Content justify / Content align / Content wrap / Align content / Row & column gap** | Flex composition of the children. |
| **Grid columns / Grid rows / Grid auto rows** | Grid composition, e.g. `repeat(2, minmax(0, 1fr))`, `minmax(120px, auto)`. |

A panel's `visibleIf` hides the whole group at once, which is usually cleaner than hiding fields one by one. Disabling or making a panel read-only cascades to children (children can opt out by turning off **Inherit parent state**).

## Tabs (`tabs`) and Tabs Pro (`tabsPro`)

Horizontal tabs, each with its own rows of elements. Tabs Pro adds richer header styling.

| Property | What it does |
| --- | --- |
| **Tabs** | The tab list: `value` is the tab ID, `label` the name, `visibleIf` hides a tab conditionally. |
| **Tabs data path** | Load the tab list dynamically from data or a source response. |
| **Active tab data path** | Data path that stores/controls the active tab from outside. |
| **Tabs position** | Headers on `top` or at the sides (left/right). |
| **Tabs variant** | Visual style: underline, pills… |
| **Full width tabs** | Tab buttons fill the row in equal blocks. |
| **Open first** | First tab opens automatically. |
| **Lazy content** | Tab content renders only when the user opens it. |
| **Tab template / Tab template ref** | Fully custom tab header markup, inline or from the [template library](https://ngxviewbuilder.io/creators/templates). |

The active tab is available to expressions:

```text
{myTabs.selectedTab}          → active tab name
{myTabs.selectedTabIndex}     → active tab index
```

Example: show a hint only on the second tab with `visibleIf: {myTabs.selectedTabIndex} == 1`.

## Accordion (`accordion`)

Vertically stacked collapsible sections. Good for optional/advanced settings that most users skip.

| Property | What it does |
| --- | --- |
| **Items** | The section list. |
| **Open first** | First section opens automatically. |
| **Allow multiple** | Several sections may stay open at once. |
| **Item template / Item template ref** | Custom section-header markup. |

## Dynamic panel (`dynamicPanel`)

A repeatable group. You design the fields once; users add, remove, and reorder entries. The value is an **array of objects**:

```json
"addresses": [
  { "city": "Vilnius", "street": "Gedimino pr. 1" },
  { "city": "Springfield",  "street": "Freedom Ave 10" }
]
```

| Property | What it does |
| --- | --- |
| **Add row button text / Remove row button text** | Button captions. |
| **Disallow adding / deleting rows** | Lock the entry count. |
| **Max rows** | Upper limit. The add button disables once it is reached. |
| **Confirm row deletion** (+ title, message, button texts) | Ask before removing an entry. |
| **Empty state text** | Shown when the panel has no entries. |

Inside a dynamic panel, expressions get extra context:

| Token | Meaning |
| --- | --- |
| `panel.fieldName` | A field in the *same* entry |
| `panel.index` | This entry's position (0-based) |
| `parentIndex` | Index of the surrounding repeater when nested |

Example, inside each address entry: `visibleIf: panel.country == "LT"`.

Aggregate over all entries from outside the panel: `sumInArray({orderLines}, "amount")`.

## Dialog (`dialog`)

A modal window designed in the builder like a normal container. It stays hidden until opened by an action or condition:

1. Add a Dialog element, give it a *Name* (e.g. `confirmDialog`) and content.
2. On any button add an action: type `dialog`, dialog name `confirmDialog`, operation `open` (also `close`, `toggle`).

| Property | What it does |
| --- | --- |
| **Dialog mode** | `modal`, `draggable`, or `fullscreen`. |
| **Dialog width / height / max width / max height** | Sizing (e.g. `720px`, `90%`, `90vh`). |
| **Title heading level** | `h1` to `h3` for the dialog title. |
| **Show close button** | X in the header. |
| **Close on backdrop** | Clicking outside closes the dialog. |
| **Initially open** | Open by default when the view loads. |
| **Open if** | Expression that opens the dialog while true. |
| **Open data path** | A boolean data path that controls opening. Set it from actions or the host app. |
| **Show trigger button** | A built-in button that opens the dialog. |
| **Trigger text / icon / icon position / icon only / variant / color / text color / width / mobile width / alignment** | Full styling of that trigger button. |

Use dialogs for confirmations, quick sub-forms, and detail previews.

## Splitter (`splitter`)

Two or more resizable side-by-side areas. Useful for list-detail layouts.

| Property | What it does |
| --- | --- |
| **Orientation** | `horizontal` or `vertical`. |
| **Panels** | The panel list: each `value` is the panel key and content identifier. |
| **Show panel headers** | A header for each panel. |
| **Allow resize** | Users drag the handle to resize. |
| **Gutter size** | Gap/handle size in pixels. |
| **Min panel size** | Minimum panel size as a percentage. |
| **Stateful** + **State key** | Persist panel sizes in localStorage under an optional custom key. |

## Spacer (`spacer`) and Divider (`divider`)

Pure layout elements.

| Property | What it does |
| --- | --- |
| **Axis** | Which direction the element occupies (vertical/horizontal). |
| **Height** (Spacer) | The gap size. |
| **Thickness** (Divider) | Line thickness. |

---

## Content & media

Source: https://ngxviewbuilder.io/creators/elements/content

# Content & media

Presentational elements. They display information and add nothing to the form data.

## Rich text (`richText` / `richTextViewer`)

Formatted text written in a WYSIWYG editor: headings, bold, lists, links, images, video. Use it for instructions, section intros, and legal text. The viewer variant renders content read-only at runtime.

| Property | What it does |
| --- | --- |
| **HTML content** | The content itself. Opens in a dialog you can move and resize, with a *Text editor* and an *HTML* tab. Placeholders render live values: <code v-pre>{{firstName}}</code> or `{user.name}`. See [Dynamic text & templates](https://ngxviewbuilder.io/creators/templates). |
| **HTML source path** | Viewer only: take the markup from a data path or a source response instead of the property. |
| **Visible tools** | Which toolbar buttons the editor offers: bold, italic, underline, strikethrough, headings, font family, text size, colors, highlight, alignment, lists, quote, inline code, link, image, horizontal rule, line spacing, sub/superscript, undo/redo, clear formatting. |

The viewer resolves placeholders too, so markup arriving from data can carry `{el2}`, `{variable1}`, or `{row.column3}` inside a table row.

Content written in a Custom HTML element renders the same way here. Both elements read the same `<style>` block and the same classes, so text colors, fonts, sizes, and alignment survive a copy from one to the other.

## Custom HTML (`customHtml` / `htmlSnippet`)

Raw HTML for layouts the rich text editor can't produce. HTML is sanitised at runtime, so scripts are stripped.

| Property | What it does |
| --- | --- |
| **HTML template** | Supports `@if`/`@for` blocks, <code v-pre>{{...}}</code> placeholders, and click bindings: `(click)="action('Open dialog')"` or `(click)="loadData(id)"`. |
| **Template ref** | Reference to a [Templates-tab](https://ngxviewbuilder.io/creators/templates) template. Wins over the inline HTML. |
| **HTML source path** | Take the markup from a data path or source response instead of a static property. |

## Image (`image`)

| Property | What it does |
| --- | --- |
| **Source URL** | Image address (can contain `{tokens}`). |
| **Local file** | Pick an image from your computer. It is stored as a data URL and takes priority over the URL. |
| **Alt text** | Accessibility text, also shown when the image fails to load. |
| **Fit** | How the image fills its box: `cover`, `contain`, `fill`, `none` (CSS `object-fit`). |
| **Object position** | Which part stays visible with `cover` (CSS `object-position`). |
| **Image height / Radius** | Sizing and corner rounding. |
| **Loading mode** | `eager` or `lazy`. |
| **Link URL** + **Open in new tab** | Make the image clickable. |
| **Caption** + **Caption alignment** | Short context or source line under the image. |

## Video (`video`)

Embedded video player.

| Property | What it does |
| --- | --- |
| **Provider** | `native`, `youtube`, or `vimeo`. Determines which extra settings apply. |
| **Source URL** | Video or YouTube/Vimeo URL. Insecure or missing URLs are blocked. |
| **Autoplay** | Browsers usually require **Muted** together with autoplay. |
| **Muted / Loop / Controls** | Playback basics; disable controls only with your own UI. |
| **Plays inline** | Play inline instead of fullscreen on mobile (important on iOS). |
| **Poster** | Preview image before playback. |
| **Privacy mode** | Reduced-tracking embed where the provider supports it. |
| **Aspect ratio** | Keeps a constant width-to-height ratio. |

## IFrame (`iframe`)

Embeds an external page: maps, dashboards, documents. The URL can include field tokens: `https://maps.example.com?q={city}`. Insecure sources are blocked.

| Property | What it does |
| --- | --- |
| **Source URL** | The embedded address. |
| **Frame height** | Base height for the frame. |
| **Allow** | The iframe `allow` attribute. Grant only what's needed (`fullscreen; clipboard-read`). |
| **Allow fullscreen** | Lets the embedded content go fullscreen. |
| **Sandbox** | The `sandbox` attribute. Restrict carefully; an overly strict sandbox can break the content. |
| **Referrer policy** | Only when the embedded host requires specific behaviour. |

## Icon (`icon`)

A single icon by name, for decoration or visual anchors.

| Property | What it does |
| --- | --- |
| **Icon** | Material Symbol code or a registered SVG icon name. Developers can register extra SVG icons; ask which names your project has. |
| **Icon color / Icon size** | Visual tuning. |

## Avatar (`avatar`)

A round profile image with fallback initials. Configure the image URL, the name text, size, and shape; an optional **Link URL** makes it clickable.

## Page title (`pageTitle`)

A styled heading for the top of a page, larger than a label.

| Property | What it does |
| --- | --- |
| **Title / Subtitle** | Heading and support text. |
| **Level** | Heading level (h1, h2…) for consistent document structure. |
| **Show divider** | A separator line under the title block. |
| **Title underline** (+ color, width) | Accent line under the title text. |

## Breadcrumbs (`breadcrumbs`)

A navigation trail (*Clients / Jonas / Edit*). Items can be static or built from the route and data.

| Property | What it does |
| --- | --- |
| **Show home** + **Home label** + **Home URL** | The leading home link. |
| **Separator** | The divider between items. |
| **Include current page** | Whether the current page appears as the last crumb. |
| **Route label data key** | Take item labels from a data-source object. |
| **Use path fallback** | Fall back to the URL segment when no label is found. |

## Chart (`chart`)

Renders a chart from a data source or expression-provided data.

| Property | What it does |
| --- | --- |
| **Chart type** | `bar`, `line`, `pie`, … Match it to the data shape. |
| **Data source / Chart data path** | Where the series data comes from; point the path at the dataset (`stats.points`). |
| **Points** | Data passed directly at the property level (instead of a source). |
| **Label / value mapping** | Which fields feed axes and series. |
| **Chart height** | Stable widget size for dashboards and cards. |
| **Show legend** | Explains colors/series. |

Charts refresh when their data source reloads. Combine that with **React to change** to make dashboards live.

---

## Date & time inputs

Source: https://ngxviewbuilder.io/creators/elements/date-time

# Date & time inputs

## Date picker (`datepicker`)

A calendar picker that stores a single date, a date-time, or a time.

| Property | What it does |
| --- | --- |
| **Picker mode** | `date` only, `date + time`, or `time` only. |
| **Output format** | Storage format, e.g. `YYYY-MM-DD`, `YYYY-MM-DD HH:mm:ss`, `HH:mm`. Empty = the mode's default. |
| **Min value (optional) / Max value (optional)** | Limit the selectable range with fixed dates or expressions. |
| **Include seconds** | Allows seconds in time/datetime modes. |

Common patterns:

```text
Default value:  today()
Min value:      today()                 → only future dates
```

To validate "delivery within 30 days", add a custom validator (the condition describes the **error**):

```text
Condition: dateDiffDays(today(), {deliveryDate}) > 30
Message:   "Delivery must be within 30 days"
```

## Date range (`dateRange`)

Two connected calendars that store a from/to pair. Use for booking periods, report filters, vacations.

The value is an object with a start and end date; expressions can reference the parts through the element name.

## Time picker (`timePicker`)

Selects a time of day. Combine a Datepicker and a Time picker when you need both, or use a Text element with the `dateTime` input mask for one-field entry.

## Working with dates in expressions

The expression language has ready-made date functions ([full list](https://ngxviewbuilder.io/creators/functions)):

| Function | Example |
| --- | --- |
| `today()` / `now()` | `Default value: today()` |
| `addDays(date, n)` | `addDays(today(), 14)` |
| `dateDiffDays(from, to)` | `dateDiffDays({startDate}, {endDate}) > 0` |
| `isWeekend(date)` | `visibleIf: isWeekend({deliveryDate})` |
| `weekDay(date)` | Display the weekday name |

Example: validate that the end date follows the start date. On `endDate` add a custom validator whose condition flags the **error**:

```text
dateDiffDays({startDate}, {endDate}) < 1
```

with the message `End date must be after start date`.

---

## Feedback & status

Source: https://ngxviewbuilder.io/creators/elements/feedback

# Feedback & status

## Badge (`badge`)

A small colored label: `Active`, `Draft`, `Overdue`.

| Property | What it does |
| --- | --- |
| **Text** | The label. |
| **Tone** | Semantic shade: `info`, `success`, `warning`, `risk`, `neutral`. |
| **Pill** | Fully rounded corners. |
| **Variant expression / Icon expression** | Drive the look from data, e.g. value `overdue` → risk tone. |
| **Link URL** | Make the badge clickable. |

## Message card (`messageCard`)

A highlighted box with icon, title, and text, for inline notices ("Your application is being reviewed").

| Property | What it does |
| --- | --- |
| **Title / Description text** | The heading and extended content. |
| **Variant** | `info`, `success`, `warning`, `error`. |
| **Show icon / Icon** | The leading icon. |
| **Dismissible** | The user can close the card manually. |
| **Primary / Secondary button text** | Optional CTA buttons (wire them with [actions](https://ngxviewbuilder.io/creators/events-actions)). |

Combine with `visibleIf` to show it only in the relevant state:

```text
visibleIf: {status} == "rejected"
```

## Toast (`toast`)

A temporary notification. Usually you don't place this element, because toasts are shown by [actions](https://ngxviewbuilder.io/creators/events-actions) (`showToastAfter` or a `toast` action). Place a Toast element only when you need a persistent, configured message area.

| Property | What it does |
| --- | --- |
| **Title / Description text** | The message. |
| **Variant / Position** | Type and screen corner. |
| **Auto hide** + **Auto hide timeout (ms)** | Self-dismissal, e.g. `4000`. |

## Stats card (`statsCard`)

A KPI tile: big number, label, and optional trend. Feed the value with an expression or a data source. Great in dashboard rows.

| Property | What it does |
| --- | --- |
| **Value text** | The primary displayed value. Expression example: `countInArray({orders}, "id")`. |
| **Trend direction** | `up`, `down`, or `neutral`. |
| **Trend text** | Short change explanation next to the indicator. |
| **Trend direction expression / Variant expression / Icon expression** | Drive trend, tone, and icon from data. |

## Progress bar (`progressBar`)

A completion indicator. Value 0-100 from a fixed number or expression:

```text
Expression: len({completedSteps}) / 5 * 100
```

| Property | What it does |
| --- | --- |
| **Display type** | Horizontal bar or circular indicator. |
| **Value label mode** | Show a percentage, the raw value, or `current/max`. |

## Stepper / Timeline (`progressFlow`)

Step indicator with named stages (*Submitted → Reviewed → Approved*).

Each item in the **Items** list has:

| Item field | What it does |
| --- | --- |
| **Step / Label / Description** | The stage identity and texts. |
| **Visible if** | Hide a stage conditionally. |
| **Active if / Completed if / Disabled if** | Conditions driving each state, e.g. `{el1} == 1` or `{score} > 80`. |

Element-level properties:

| Property | What it does |
| --- | --- |
| **Active index** | Default active step. |
| **Active step expression** | Calculate the active step from data, for business conditions across several fields. |
| **Active step data path** | Read the active index from external state. |
| **Steps data path** | Load the step list from data or a source response (`data.steps`). |
| **Show numbers / Show connector** | Numbering and the connecting line. |
| **Allow manual navigation** | Users can click between steps themselves. |
| **Step template / Step template ref** | Fully custom step markup, inline or from the [template library](https://ngxviewbuilder.io/creators/templates). |

The current step is readable in expressions:

```text
{approvalFlow.selectedStep}        → active step name
{approvalFlow.selectedStepIndex}   → active step index
```

Example: `visibleIf: {approvalFlow.selectedStep} == "Approved"` on a download button.

---

## Elements overview

Source: https://ngxviewbuilder.io/creators/elements/

# Elements overview

Elements are the building blocks of every view. This page is the index; each group has its own page with per-element details.

## Which element do I need?

| I need… | Use | Group |
| --- | --- | --- |
| A short text answer | Text | [Text & number inputs](https://ngxviewbuilder.io/creators/elements/inputs) |
| A long text answer | Textarea | [Text & number inputs](https://ngxviewbuilder.io/creators/elements/inputs) |
| A number | Number, Number stepper, Slider | [Text & number inputs](https://ngxviewbuilder.io/creators/elements/inputs) |
| A phone number | Phone input | [Text & number inputs](https://ngxviewbuilder.io/creators/elements/inputs) |
| A date | Datepicker | [Date & time](https://ngxviewbuilder.io/creators/elements/date-time) |
| A period (from/to) | Date range | [Date & time](https://ngxviewbuilder.io/creators/elements/date-time) |
| A time | Time picker | [Date & time](https://ngxviewbuilder.io/creators/elements/date-time) |
| One choice from a list | Select, Radio, Select button | [Choice inputs](https://ngxviewbuilder.io/creators/elements/choices) |
| Many choices from a list | Multi-select, Checkbox group, List box | [Choice inputs](https://ngxviewbuilder.io/creators/elements/choices) |
| Yes/no | Single checkbox, Toggle switch | [Choice inputs](https://ngxviewbuilder.io/creators/elements/choices) |
| Search-as-you-type choice | Autocomplete | [Choice inputs](https://ngxviewbuilder.io/creators/elements/choices) |
| A clickable action | Button | [Buttons & actions](https://ngxviewbuilder.io/creators/elements/buttons) |
| Group fields visually | Panel, Tabs, Accordion | [Containers](https://ngxviewbuilder.io/creators/elements/containers) |
| Repeatable entries (0 to n) | Dynamic panel, Dynamic table | [Containers](https://ngxviewbuilder.io/creators/elements/containers) / [Tables](https://ngxviewbuilder.io/creators/elements/tables) |
| A modal window | Dialog | [Containers](https://ngxviewbuilder.io/creators/elements/containers) |
| Read-only data rows | Table | [Tables & lists](https://ngxviewbuilder.io/creators/elements/tables) |
| Card-style records | List grid | [Tables & lists](https://ngxviewbuilder.io/creators/elements/tables) |
| Formatted text / HTML | Rich text, Custom HTML | [Content & media](https://ngxviewbuilder.io/creators/elements/content) |
| Pictures / video / embeds | Image, Video, Iframe | [Content & media](https://ngxviewbuilder.io/creators/elements/content) |
| A chart | Chart | [Content & media](https://ngxviewbuilder.io/creators/elements/content) |
| Status labels & KPIs | Badge, Stats card, Message card | [Feedback & status](https://ngxviewbuilder.io/creators/elements/feedback) |
| Progress indication | Progress bar, Progress flow | [Feedback & status](https://ngxviewbuilder.io/creators/elements/feedback) |
| File attachments | File upload | [Special inputs](https://ngxviewbuilder.io/creators/elements/special) |
| A handwritten signature | Signature pad | [Special inputs](https://ngxviewbuilder.io/creators/elements/special) |

## Value-producing vs. presentational

**Value-producing elements** (inputs, choices, editable tables) write into the form data under their `name`. **Presentational elements** (text, image, divider, badge…) only display; they add nothing to the submitted data.

## Every element shares

Regardless of type, elements share the [common properties](https://ngxviewbuilder.io/creators/properties): name, label, responsive widths, restrictions, logic conditions, validators (for inputs), and events. The group pages only describe what is *specific* to each element.

---

## Text & number inputs

Source: https://ngxviewbuilder.io/creators/elements/inputs

# Text & number inputs

## Text (`text`)

Single-line free text. The default field for names, codes, and short answers.

Specific properties:

| Property | What it does |
| --- | --- |
| **Input mode** | Hints the mobile keyboard: `text`, `email`, `tel`, `url`, `numeric`, `decimal`, `search` |
| **Input mask** | Forces a format while typing: international phone, date, time, date-time, digits, or custom |
| **Custom mask pattern** | Your own pattern when mask = `custom` |
| **Autocomplete** | Browser autofill hint (`email`, `name`, `postal-code`…) |
| **Min / Max length** | Character limits |
| **Show max length counter** | Live character counter under the field |
| **Spellcheck** | Browser spellcheck on/off |

Example: a Lithuanian company code field:

- *Name*: `companyCode`, *Input mode*: `numeric`, *Max length*: `9`
- *Validators*: `pattern` = `^[0-9]{9}$`, message `Company code is 9 digits`

## Textarea (`textarea`)

Multi-line text for comments and descriptions. Supports min/max length and the length counter.

## Number (`number`)

Numeric input that stores a number (or a formatted string when configured).

| Property | What it does |
| --- | --- |
| **Use visual number format** | Locale-aware display formatting (e.g. US: `12,345.67`). The stored value stays a clean number |
| **Format locale** | Locale override; empty = *Form settings → Locale* |
| **Min / Max fraction digits** | Digits shown after the decimal point |
| **Thousand separators** | Group digits by locale |
| **Store value as** | `number` (default) or `string` |
| **Number input alignment** | Text alignment inside the input (`left` default, or `right`) |
| **Number placeholder text** | Placeholder for the empty state |
| **Min / Max value** | Numeric bounds |

Use Number whenever the value is used in calculations, so `{price} * {quantity}` works without conversion.

## Number stepper (`numberStepper`)

A number with +/− buttons. Best for small quantities (passengers, rooms, items).

## Phone input (`phoneInput`)

Phone number with country-code selection and formatting.

| Property | What it does |
| --- | --- |
| **Default country code** | Pre-selected country, worth setting when most users share one market (e.g. `US`, `LT`) |
| **Allowed country codes** | Restrict the selector to specific markets |
| **Enable country search** | Search box inside the country dropdown |
| **Return country ISO code** | Store the ISO code together with the number |

## Slider (`slider`)

Drag to pick a number within a range. Good for ratings and percentage-style answers where precision is not critical.

| Property | What it does |
| --- | --- |
| **Min / Max value** | The range limits |
| **Step** | Increment (e.g. `1`, `0.5`) |
| **Show value label** | Displays the current value next to the control |

## Choosing between them

| Situation | Element |
| --- | --- |
| Any free text | Text |
| Value used in math | Number |
| Quantity 0-20 | Number stepper |
| Approximate value in a known range | Slider |
| Phone number | Phone input (not Text) |

---

## Special inputs

Source: https://ngxviewbuilder.io/creators/elements/special

# Special inputs

## File upload (`fileUpload`)

Lets users attach files. The element stores file metadata in the form data and can upload to a server through a data source.

| Property | What it does |
| --- | --- |
| **Accepted types** | Restrict extensions/MIME types per HTML `accept` rules (e.g. `.pdf,image/*`) |
| **Max files** | How many files may be attached; further uploads are blocked at the limit |
| **Max file size (MB)** | Oversized files are rejected before upload |
| **Dropzone text** | Caption of the drag-and-drop area. Keep it short and say what to do |
| **Upload data source** | Source that receives the file: a POST (or configured method) with `FormData` |
| **Upload form field name** | The `FormData` field name for the file (e.g. `file`) |
| **Download data source / Delete data source** | Sources for fetching and removing stored files; the file key is passed via the key field below |
| **File key / name / size / type field** | Field names in the server's file object (default: `key`, `name`, `size`, `contentType`) |

::: warning Without an upload data source, the file never leaves the browser
Only local metadata (name/size/type) is kept as the field's value, so the field can look "filled in" while your backend never receives the actual bytes. Set **Upload data source** whenever the file must be stored server-side.
:::

A few things worth knowing before you brief your developer:

- Uploads are always sent as `multipart/form-data` with a single field (its name is **Upload form field name**), never JSON, never base64. Any **Request body** template configured on the upload source is ignored; only `{placeholders}` in its URL are used.
- With **Max files** > 1, files upload as separate sequential requests, not one batch call.
- There's no upload progress percentage, only pending/ready/error per file, and no resumable or chunked upload.
- The field's value in the form result is whatever your endpoint's response contained (the **File key / name / size / type field** properties), never the file's bytes.

**For the exact request/response JSON your backend must implement, see [File upload requests](https://ngxviewbuilder.io/developers/data-sources#file-upload-requests) in the developer docs.**

Typical setup, CV upload:

- *Name*: `cvFile`, *Accepted types*: `.pdf`, *Max size*: `5 MB`, *Required*: on.
- Upload data source: `uploadDocument` (a REST source configured by your developer).

Check with expressions:

```text
visibleIf on "Continue" hint:  isEmpty({cvFile})
len({attachments}) > 0         → at least one file attached
```

## Signature pad (`signaturePad`)

A draw area for a handwritten signature (mouse or touch). The value is the signature image data, stored under the element's name and submitted with the form.

| Property | What it does |
| --- | --- |
| **Pen / background color** | Drawing style |
| **Clear button** | Lets the user retry |
| **Required** | Signature must be present before submit |

Use it at the end of agreements together with a Single checkbox (*"I confirm the data is correct"*).

---

## Data tables & lists

Source: https://ngxviewbuilder.io/creators/elements/tables

# Tables & lists

Three elements show record collections. Pick by task:

| Element | Data direction | Use for |
| --- | --- | --- |
| **Table** | Displays server data | Browsing, searching, and acting on records |
| **Dynamic table** | Collects user data | Editable rows the user adds/removes (part of the form result) |
| **List grid** | Displays data | Card-style record lists with a custom template |

## Table (`table`)

The full-featured data table. It reads rows from a [data source](https://ngxviewbuilder.io/creators/data-sources) and everything below is configurable from the properties sidebar.

::: tip Start simple
A working table needs only: a data source, *Items path*, and 2-3 columns. Add search, actions, and pagination once the data shows up.
:::

Row context in expressions and actions: `{row.fieldName}`, e.g. a row action with condition `{row.status} == "draft"`. Selected rows: `{__table.<tableName>.selectedRows}`.

A column either prints its value as text, or hosts a real element in every row. See [Cell elements](https://ngxviewbuilder.io/creators/elements/tables#cell-elements) for the second option, which covers what the old per-type renderers did (dates, badges, toggles, checkboxes) and adds events, data sources, and validation on top.

### Primary source & request

| Property | What it does |
| --- | --- |
| **Data source** | Primary source from the DataSources tab, e.g. `loadUsers`, together with its *Use as*, *React to change*, and *Listen fields* settings. The same picker is used whether Lazy load is on or off. |
| **Items path (optional)** | Path to the array in the response, e.g. `data.items`. Empty = auto-detection. |
| **Request params** | Additional TABLE-POST params (up to 5 rows): **Param name** + **Value / `{path}`**. |
| **Lazy load** | Load per page/sort from the server instead of everything upfront. |
| **Total path (lazy)** | Path to the total record count, e.g. `meta.total` or `totalCount`. Optional: `total`, `totalCount`, `totalRecords`, `count`, `cnt` (and the same names nested under `paging.*`) are auto-detected without setting this. |
| **Order clause** | Sort expression the backend expects. |
| **Order direction** | `asc` / `desc`, used with the order clause or column sorting. |

With **Lazy load** on, set the data source's **Method** to `TABLE-POST`. This sends a real `POST` but automatically merges the current page/sort/search state into the request body for you. **For the exact request/response JSON your backend must implement, see [Table: server-side paging & filtering](https://ngxviewbuilder.io/developers/data-sources#table-server-side-paging-filtering-table-post) in the developer docs**, and hand that section to whoever builds the endpoint.

### Search

| Property | What it does |
| --- | --- |
| **Show quick search** | One short field for quick filtering. |
| **Quick search placeholder** | Say what can be searched here. |
| **Quick search param name** | Request parameter for the value, e.g. `q` or `searchTerm`. |
| **Quick search condition** | Match mode: contains `%-%`, not contains `!%-%`, starts with `%-`, ends with `-%`, equals `=`, not equals `!=`. |
| **Quick search case mode** | Case-insensitive latin, case sensitive, uppercase, or lowercase comparison. |
| **Quick search debounce (ms)** | Time between the last keystroke and the request. |
| **Show detailed search** | The expanded block with per-column filters, operators, and values. |
| **Detailed search case mode** | Case handling for detailed search. |

Per-column filter settings live on each column; see [Columns](https://ngxviewbuilder.io/creators/elements/tables#columns) below.

### Columns

**Columns** holds the column schema. Each column has:

| Column field | What it does |
| --- | --- |
| **Key** | Data key in the row object; nested paths allowed (`user.name`, `status`). |
| **Label** / **Mobile label** | Header text; the mobile variant falls back to Label when empty. |
| **Type** | `text` prints the plain value. `Date`, `Date & time`, and `Number` format it, see [Formatted columns](https://ngxviewbuilder.io/creators/elements/tables#formatted-columns). `Element (control)` renders a real element in every cell, see [Cell elements](https://ngxviewbuilder.io/creators/elements/tables#cell-elements). |
| **Format locale** | Formatted columns only: `lt-LT`, `en-US`, and so on. Empty follows the view's locale. |
| **Date pattern** | Exact date shape, e.g. `yyyy-MM-dd HH:mm:ss`. Empty uses the locale's own format. |
| **Show seconds** | Whether a `Date & time` column includes seconds. |
| **Min decimals / Max decimals** | Decimal places on a `Number` column. |
| **Thousands separator** | Group digits on a `Number` column. |
| **Cell element** | Which element the cells host when Type is `Element (control)`: Select, Button, Badge, Date picker, Progress bar, and so on. |
| **Cell element text** | The hosted element's own label or caption (button text, badge text). Kept separate from **Label**, which stays the column header. |
| **Align** | Column text alignment. Applies to both plain and element columns. |
| **Sortable** | Whether sorting is allowed by this column. |
| **Show in table / Show in details** | Where the column appears (main table and/or the details view). |
| **Detail label** | Optional different name in the details view. |
| **Show header label** | Hide header text for action/checkbox/technical columns. |
| **Header group** | Group header above the column. Adjacent columns with the same name merge. |
| **Template** | Custom cell HTML, e.g. <code v-pre><strong>{{value}}</strong> {{row.status}}</code>. |
| **Template ref** | Reference to a [Templates-tab](https://ngxviewbuilder.io/creators/templates) template (takes priority over inline HTML). |
| **Filter control type** | Detailed-search control for this column: `auto`, `select`, `toggle`… |
| **Filter options / JSON / data source (+ items path, label key, value key)** | Where the filter's choices come from: manual list, JSON, or a data source. |
| **Filter toggle true/false value** | What a detailed-search toggle sends when on/off (`yes`/`no`, `T`/`N`). |
| **Filter multi-value delimiter** | Joins multiple filter values into one request param (`,` or `;`). |
| **Use totals (+ fraction digits, locale, grouping, mask, template)** | Show this column's sum in the footer row, with formatting controls and a `{total}` text template. |
| **Editable / Editor type / Editor options (+ label key, value key, placeholder)** | Inline-edit settings for this column: which control edits it (text, number, select, date) and where its choices come from. |

### Formatted columns

An API rarely sends a value ready to read. A timestamp arrives as `2026-07-25T07:11:43.724948Z` and an amount as `1234.5`. Set the column's **Type** to `Date`, `Date & time`, or `Number` and the raw value is rendered the way the reader expects, with no template and no cell element.

Formatting follows the view's locale, so the decimal mark and the thousands separator come from there. Override it per column with **Format locale** when one table has to differ.

With `locale: lt-LT`:

| Type | Settings | `2026-07-25T07:11:43.724948Z` renders as |
| --- | --- | --- |
| `Date` | none | `2026-07-25` |
| `Date & time` | Show seconds on | `2026-07-25 10:11:43` |
| `Date & time` | Date pattern `yyyy/MM/dd hh:mm a` | `2026/07/25 10:11 AM` |

And for `1234.5`:

| Type | Settings | Renders as |
| --- | --- | --- |
| `Number` | Min and max decimals 2 | `1 234,50` |
| `Number` | Thousands separator off | `1234,50` |

**Date pattern** takes priority over the locale format when you need an exact shape. Tokens are `yyyy`, `yy`, `MM`, `dd`, `HH` (24h), `hh` (12h), `mm`, `ss`, `SSS`, and `a` for AM/PM. Everything else in the pattern is printed as typed, so separators are yours to choose.

A value that is not a real date or number is printed unchanged rather than blanked, which keeps a stray `N/A` from a backend visible instead of silently disappearing.

### Cell elements

Set a column's **Type** to `Element (control)` and pick a **Cell element**. Every row of that column then renders a real builder element, configured exactly like one dropped on a page: its own options, data source, events, and validators. It is the same principle a [Dynamic table](https://ngxviewbuilder.io/creators/elements/tables#dynamic-table-dynamictable) uses for its columns, brought to the data table.

Pick the element and the properties sidebar grows the matching sections. A Select column gains **Data**, **Options**, **Validators**, and **Events**; a Button column gains **Events**; a Progress bar column gains its own appearance settings. The column keeps owning **Label**, **Width**, **Align**, and **Visible if**, so the header and the layout stay where you set them. The hosted element's own caption lives in **Cell element text**.

Available cell elements: Text input, Textarea, Number, Number stepper, Phone input, Select, Multi select, Select button, Radio, Checkbox group, Single checkbox, Toggle switch, Slider, Date picker, Date range, Time picker, Button, Badge, Image, Progress bar, File upload, Custom HTML, HTML viewer. Developers can add their own components to this list, see [Custom elements](https://ngxviewbuilder.io/developers/custom-elements#using-a-custom-element-in-a-table-cell).

**HTML viewer** is the one to reach for when the row already carries markup. It renders the cell's own value as HTML, so a `note` or `description` field holding `<b>Bold</b>` or a small list shows up formatted with nothing else to configure. Custom HTML is the other way round: you write the template and pull row fields into it.

::: warning Switching the element starts over
Choosing a different **Cell element** clears the previous element's configuration. Options, data source, and events belonging to the old element have no meaning for the new one, so the column starts fresh. Switch **Type** back to `text` and the hosted element is dropped entirely.
:::

#### The row is in scope

A cell element knows which row it sits in, so anything you write in it resolves against that row:

| Token | Resolves to |
| --- | --- |
| `{row.fieldName}` | A field of this row |
| `{fieldName}` | The same thing, short form for a sibling field of the row |
| `{index}` | Zero-based index of the row on the current page |
| `{value}` | The cell's own value |

This works in the places you would expect: a Button's text, a Badge's text, a Custom HTML template, and inside the element's events. A Select in a `status` column can fire an `onChange` toast reading `Row {row.name} changed to {value}`, and it reports the right row every time.

Editing a value through a cell element writes it back into the row, so a plain `text` column bound to the same key updates with it, and row actions and conditions see the new value.

::: tip Which one to reach for
Use a plain `text` column when you only print a value. Use a cell element when the cell has to *do* something: a status Select, a per-row Button, a Badge, a Progress bar, or a Custom HTML block that mixes several fields of the row.
:::

Example: a status column that saves on change.

- **Key** `status`, **Label** `Status`, **Type** `Element (control)`, **Cell element** `Select`.
- In **Options**, list the statuses, or point **Data** at a `statuses` data source.
- In **Events**, add an action with trigger `change`, type `dataSource`, source `saveStatus`, and a param `id = {row.id}`, `status = {value}`.

### Actions

| Property | What it does |
| --- | --- |
| **Row actions** | Actions for each row, as a dropdown or buttons. Quick presets: View, Edit, Copy, Delete. |
| **Row actions display** | `dropdown`, `iconButtons`, or `buttons` (icon + text). |
| **Row actions menu button style** | Default or borderless three-dot button. |
| **Row action visibility path** | Row field that decides whether actions show for that record. |
| **Row click actions** | Actions fired by clicking the whole row (navigate, open details, select). |
| **Row expand actions** | Actions for the expanded-row scenario. |
| **Selection actions** + **label** | Bulk actions applied to selected rows (export, delete, status change). |
| **Actions label** / **Show actions header label** | The actions column header text, and whether to show it. |

Every action uses the standard [action editor](https://ngxviewbuilder.io/creators/events-actions), so a row button can navigate to `/clients/{row.id}` or call an endpoint with `id = row.id`.

### Selection

| Property | What it does |
| --- | --- |
| **Enable multi select** | Checkbox selection. Selected records: `{__table.<name>.selectedRows}` (and `.selectedItems` with a template). |
| **Selection key path** | Unique field identifying rows, e.g. `id` or `classifier.id`. |
| **Auto select if** | Auto-select rows after refresh. Example: `{row.status} == "Y"`. |
| **Selected item template** | How each selected row becomes an entry in `selectedItems`: empty = whole row; `row.oraId` = an ID array; JSON like `{"oraId":"{row.oraId}"}` = custom objects. |

### Expanded rows & details

| Property | What it does |
| --- | --- |
| **Expandable rows** | Master switch. Without it neither inline nested tables nor the side panel work. |
| **Expanded display mode** | `inline` (below the row) or `sidePanel` (side details panel). |
| **Show expand chevron in first column** | Chevron appears only on rows that can actually expand. |
| **Always show expand chevron** | Puts the chevron on every row, including rows with nothing nested yet. Requires the chevron above. |
| **Open details on row click** | Row click opens details, with no separate button needed. |
| **Expanded rows path** | Path in the row object to the nested array (`orgList`, `details.items`). |
| **Expanded datasource** (+ **items path**) | Alternative: call a data source on expand instead of reading a nested array. Example: `organizationsByUser`. |
| **Expanded columns** | Nested-table columns (same schema as Columns). |
| **Expanded row actions** | Actions on nested records; context adds `parentRow` / `tableRow`. Example: `[{ "label": "Open", "type": "navigate", "navigateTo": "/org/{parentRow.id}/{row.id}" }]`. |
| **Expanded content template (HTML)** | Free-form details markup: <code v-pre>{{value}}</code>, <code v-pre>{{row.xxx}}</code>, <code v-pre>{{item.xxx}}</code>. |
| **Expanded empty message** | Text when a row has no nested records. |
| **Details panel title** | Title of the side details panel. |

**Open details on row click** and cell elements get along: clicking a Badge, an Image, a Progress bar, an HTML viewer, or a Custom HTML block counts as clicking the row, so the details open. Controls that own their click, a Select, an Input, or a Button, keep it to themselves, which is what you want when someone is picking a value rather than choosing a row.

Columns marked **Show in details** rebind to whichever row is open, so a Select in the details view always shows the selected record's value.

The chevron normally shows only where there is something to open, which is right when nested rows come from **Expanded rows path**. It reads badly when the details come from an **Expanded datasource** or an **Expanded content template**: the row object holds no nested array, so the table cannot know in advance that the row has details, and the column ends up half-empty. **Always show expand chevron** gives every row one, and a row with nothing to show opens the details area with your **Expanded empty message** instead of ignoring the click.

### Pagination

| Property | What it does |
| --- | --- |
| **Paginator** | Shows pagination controls. |
| **Page size** | Records per page. |
| **Page size options** + **Show page size selector** | Let users pick from e.g. `10,25,50,100`. List only values the backend supports. |
| **Paginator variant** | `full`, `pager`, `numbers`, `simple`. |
| **Paginator align** | Start / center / end. |
| **Paginator max buttons** | How many page buttons show at once. |
| **Show record count** | Total results summary near the paginator. |
| **Flat footer surface** | Footer without extra border/shadow accents. |

### Header controls

| Property | What it does |
| --- | --- |
| **Show header controls** | Master switch for the header bar (search, export, menu…). |
| **Show export buttons** | CSV / Excel / PDF export, generated entirely in the browser from the rows the table already has (or re-fetches with a larger page size for "export all"). There is no separate server-side export endpoint to build. |
| **Export column picker dialog** | Choose which columns to export. Handy for wide tables. |
| **Export file name** | Default download name. |
| **Export all page size** | Batch size when exporting all pages of a lazy table. |
| **Column settings** (*Show column settings*) | End users change visible columns, order, and widths. |
| **Column settings mode** | Where preferences live: local UI, localStorage, or host/server. |
| **Column settings storage key** | localStorage key when persisting between sessions. |
| **Column settings datasource / path / save datasource / dialog title** | Server-backed column settings: load source + response path, save source, and dialog title. |
| **Header template (HTML)** / **Header template ref** | Custom content in the header center, as inline HTML or a Templates-tab reference. |
| **Header added elements position** | Where drag-and-dropped header elements align: left / center / right. |
| **Header dropdown** (+ placeholder, items path, datasource, datasource items path, static options, label key, value key) | An extra dropdown in the header. Its options come from a path, data source, or manual list. |
| **Header dropdown actions** | Actions fired by menu items (navigate, data source…). |
| **Flat header surface** | Header without extra surface accents. |

### Inline edit

| Property | What it does |
| --- | --- |
| **Enable inline edit** | Edit cells in place, without a dialog. |
| **Inline edit start mode** | Single click, double click, or an action button. |
| **Inline edit save datasource** | Where changed rows are sent. |
| **Cancel inline edit on reload** | Drop unsaved edits when the table reloads. |

### Appearance & performance

| Property | What it does |
| --- | --- |
| **Table style** | `default`, `grid`, `striped`. |
| **Row hover** | Hover state for rows. |
| **Sticky header** | Header (with search/filters/export) sticks while scrolling. |
| **Responsive mode** | `auto` or stack on mobile. |
| **Empty state text** | Text when the table has no data. |
| **Virtual scroll** (+ buffer, row height, viewport height) | Renders only visible rows for huge datasets. Set an accurate row height; the buffer trades smoothness for DOM size. |

### Texts

| Property | What it does |
| --- | --- |
| **Prev / Next label** | Pagination button texts. |
| **Loading label** | Text during load. |
| **Select all / Select / Select row label** | Selection checkbox labels (also used for accessibility). |
| **Expand / Collapse label** | Expand-button texts. |

## Dynamic table (`dynamicTable`)

An **input** element: spreadsheet-like rows the user fills in. The value is an array of objects, exactly like a [Dynamic panel](https://ngxviewbuilder.io/creators/elements/containers#dynamic-panel-dynamicpanel) but in table form.

| Property | What it does |
| --- | --- |
| **Columns** | Each column is itself an element (text, number, select, multi-select, radio, checkbox, datepicker, textarea…) with its own validation. |
| **Add row button text** / **Remove row button text** | Button captions. |
| **Disallow adding rows** / **Disallow deleting rows** | Lock the row count. |
| **Max rows** | Upper limit. The add button disables when it is reached. |
| **Confirm row deletion** | Ask before removing, with **Delete confirm title / message / confirm & cancel button texts**. |
| **Hide row if** | Expression that hides matching rows: `{row.status} != "A"`. |
| **Status rules** | Condition + tone rules that color the whole cell background. |
| **Use totals** | Show the column's sum in the footer row. |
| **Total template** | Footer text with `{total}`, e.g. `Total: {total}`. |
| **Total to data** | Publish the sum into the data without showing a footer row. See [Column totals in data](https://ngxviewbuilder.io/creators/elements/tables#column-totals-in-data). |

Row context inside cells: `row.otherColumn`, `row.index`. Aggregates outside: `sumInArray({orderLines}, "amount")`.

### Column totals in data

A column sum can leave the table. Turn on **Total to data** (or **Use totals**, which publishes as well) and the sum appears in the data under the table's name and the column's name:

```text
el4.column1-total
```

From there it behaves like any other value. Read it anywhere, keep the braces so the minus sign is not read as subtraction:

```text
{el4.column1-total}                          in text, HTML, templates
{el4.column1-total} > 1000                   in visibleIf, disableIf, validators
{variable1} = {el4.column1-total}            into a variable
```

It travels with the submitted data JSON, and elements reading it refresh as soon as a row changes. Turning both switches off removes the key again.

Inside a dynamic panel the table exists once per entry, so the key carries the entry index: `el1[0].el5.column3-total`. For one number across all entries use an aggregate instead: `sumArray({el1}, el5[].column3)`.

Example: order lines:

- Columns: `product` (select with data source), `quantity` (number), `price` (number, read-only, filled by expression from the product), `total` (number, *Expression*: `{row.quantity} * {row.price}`).
- Below the table, a read-only Number named `orderTotal` with *Expression*: `sumInArray({orderLines}, "total")`.

## List grid (`listGrid`)

Renders each record of a data source as a card using an HTML template: product cards, employee directory, dashboards.

| Property | What it does |
| --- | --- |
| **Data source / Items path** | Where records come from. |
| **Card template** | HTML with <code v-pre>{{item.xxx}}</code> placeholders and `@if(...)` blocks, inline or from the [template library](https://ngxviewbuilder.io/creators/templates) via **Card template ref** (ref wins). |
| **Layout** | List or grid display. |
| **Grid column count** / **Grid minimum column width** / **Min card width** / **Gap** | Grid geometry. |
| **Quick search** (*Run search / Clear search / placeholder*) | Built-in search bar over the records. |
| **Sort control** (*Show sort control* + **Sort field**) | A sort button; requires the field to sort by (`name`, `createdAt`, `user.lastName`). |
| **Infinity scroll** | Loads the next page as the user nears the bottom, an alternative to a paginator for card lists. |
| **Total path** | Total record count in the response for lazy loading (`total`, `data.totalCount`, `paging.total`). |
| **Empty message** | Text when there are no records. |

Template example:

```html
<div class="card">
  <strong>{{ item.name }}</strong>
  <span>{{ item.city }}</span>
  @if (item.status == "Active") {<span class="ok">{{ item.status }}</span>}
</div>
```

---

## Events & actions

Source: https://ngxviewbuilder.io/creators/events-actions

# Events & actions

The **Actions** category attaches behaviour to elements. An event = **trigger** (when) + **action** (what) + options. One element can have several actions; they run in order. The same action editor is used for element events, table row actions, header actions, and selection actions.

In the view JSON every action is one object in the element's `events` array (or `rowActions`, `selectionActions`, … on tables):

```json
{
  "events": [
    {
      "trigger": "click",
      "type": "dataSource",
      "label": "Save",
      "dataSourceName": "saveOrder",
      "validateForm": true,
      "reloadElementNames": "ordersTable",
      "showToastAfter": true,
      "toastTitle": "Saved",
      "toastVariant": "success"
    }
  ]
}
```

## Triggers

**Trigger** is _when to run the action_ (JSON key: `trigger`).

| Trigger                               | Fires when                                                              |
| ------------------------------------- | ----------------------------------------------------------------------- |
| `click`                               | element is clicked (buttons, icons, cards, rows)                        |
| `change`                              | value changes                                                           |
| `input`                               | every keystroke (add **Debounce (ms)** to avoid flooding)               |
| `blur` / `focus`                      | field loses / gains focus                                               |
| `submit`                              | the form is submitted                                                   |
| `beforeLoad` / `onLoad` / `afterLoad` | element lifecycle when the view loads                                   |
| `always`                              | whatever the element fires the action is not filtered by trigger at all |

Use `always` (**Always (any trigger)** in the editor) for elements whose events are not user gestures. A custom element registered by the host app might emit `activate`, `deactivate`, `attach`, or `detach`; none of those map to a name in the list above, and a router outlet has no click or change to hook into. With `always`, the action simply runs whenever that element fires something.

The trade-off is that _any_ really means any. On an ordinary input, an `always` action runs on load **and** on every change, input, blur, and focus. Keep it for elements that fire one kind of event, and use a named trigger everywhere else.

## Fields shared by every action

| Field                                 | JSON key               | What it does                                                                                                                            |
| ------------------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| **Action**                            | `type`                 | What the action will do: `navigate`, `dataSource`, `setValue`, `setOptions`, `reloadElements`, `toast`, `dialog`, `validate`, `submit`. |
| **Label**                             | `label`                | Short action label shown in the action list and on generated buttons. Example: _Update table_.                                          |
| **Action code**                       | `actionCode`           | Optional technical code for the action. Useful when the host app or templates refer to actions by name (`action('Open dialog')`).       |
| **Icon**                              | `icon`                 | Material Symbols icon code shown on the generated button. Example: `refresh`, `save`, `visibility`.                                     |
| **Hide text, show icon only**         | `hideText`             | Renders the action as an icon-only button.                                                                                              |
| **Use custom button style**           | `useCustomButtonStyle` | Unlocks the two style fields below instead of the default styling.                                                                      |
| **Button style**                      | `buttonVariant`        | `filled`, `outlined`, or `text`.                                                                                                        |
| **Button tone**                       | `buttonTone`           | `primary`, `risk` (destructive), or `neutral`.                                                                                          |
| **Visible if**                        | `condition`            | Expression. The action runs (and its button is shown) only while true. Example: `{el1} == "ok"` or `{row.status} != "draft"`.           |
| **Debounce (ms)**                     | `debounceMs`           | Delay between the trigger and execution. Essential for `input`/`change` triggers. Example: `300`.                                       |
| **Validate whole form before action** | `validateForm`         | Runs validation first; the action is aborted when the form is invalid.                                                                  |

### Confirmation fields

| Field                                  | JSON key              | What it does                                                                  |
| -------------------------------------- | --------------------- | ----------------------------------------------------------------------------- |
| **Ask confirmation before action**     | `confirmEnabled`      | Shows an _"Are you sure?"_ dialog before running.                             |
| **Confirm only when form has changes** | `confirmOnDirty`      | Ask only if the form has unsaved changes. Handy for _Cancel_/_Leave_ buttons. |
| **Confirmation title (optional)**      | `confirmTitle`        | Dialog title. Example: _Confirm deletion?_                                    |
| **Confirmation message (optional)**    | `confirmMessage`      | Dialog body text. Example: _This action will change table data._              |
| **Confirm button label**               | `confirmConfirmLabel` | Example: _Yes, continue_.                                                     |
| **Cancel button label**                | `confirmCancelLabel`  | Example: _No, go back_.                                                       |

```json
{
  "trigger": "click",
  "type": "dataSource",
  "label": "Delete",
  "buttonTone": "risk",
  "dataSourceName": "deleteClient",
  "confirmEnabled": true,
  "confirmTitle": "Delete client?",
  "confirmMessage": "This cannot be undone.",
  "reloadElementNames": "clientsTable"
}
```

## Action type: `navigate`

Opens a URL or app route. Tokens in `{…}` are resolved from form data, row context, and variables.

| Field                                   | JSON key                       | What it does                                                                                                                                                                                         |
| --------------------------------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Navigate to**                         | `navigateTo`                   | Route or URL. Example: `/orders/{row.id}` or `https://example.com?id={item.id}`.                                                                                                                     |
| **Open in new tab**                     | `openInNewTab`                 | Opens the target in a new browser tab, so the user keeps the current form context.                                                                                                                   |
| **Run data source before navigation**   | `beforeNavigateDataSourceName` | An additional data source that runs **before** leaving, e.g. save a draft, resolve an ID, log the click. Example: `loadOrderDraft`.                                                                  |
| **Response data path (optional)**       | `responseDataPath`             | Which part of the before-navigate response to keep. Example: `data`, `result.item`, `payload`.                                                                                                       |
| **Use response path before navigation** | `responseTargetPath`           | Variable or data path where the before-navigate response is stored _before_ navigating, so the target page (or the return trip) can use it. Example: `__variables.customerDraft` or `customerDraft`. |
| **Reload elements on return**           | `reloadOnReturnElementNames`   | Elements refreshed when the user comes back from the navigation or dialog. Example: `filesTable`.                                                                                                    |

```json
{
  "trigger": "click",
  "type": "navigate",
  "label": "Open order",
  "navigateTo": "/orders/{row.id}",
  "beforeNavigateDataSourceName": "saveOrderDraft",
  "responseDataPath": "data",
  "responseTargetPath": "__variables.orderDraft",
  "reloadOnReturnElements": "ordersTable"
}
```

## Action type: `dataSource`

Calls a [data source](https://ngxviewbuilder.io/creators/data-sources). This is the workhorse for saving and loading.

| Field                                         | JSON key                           | What it does                                                                                                                                                                                                                 |
| --------------------------------------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Data source**                               | `dataSourceName`                   | Which source to call. Example: `saveOrder` or `loadPersons`. If a REST source has no URL, the editor warns you; set it in the DataSources tab.                                                                               |
| **Placeholder mapping (URL/body)**            | `params`                           | Maps each `{placeholder}` in the source URL/body to a context path or plain value. Example: body `{selectedRows}` → `__table.el1.selectedRows`, URL `{id}` → `row.id`. Shown only when the source actually has placeholders. |
| **Response action**                           | `responseMode`                     | What to do with the response: `none` (do nothing), `download` (save response as a file), `setValue` (write response into an element).                                                                                        |
| **Response data path (optional)**             | `responseDataPath`                 | Which part of the response to use. Example: `data`, `result.item`, `payload.items`.                                                                                                                                          |
| **Target element**                            | `responseTargetElement`            | Element that receives the response when `responseMode` = `setValue`.                                                                                                                                                         |
| **Target data path (optional)**               | `responseTargetPath`               | Alternative to a target element: write the response to any data path or variable.                                                                                                                                            |
| **Download file name (optional)**             | `responseFileName`                 | File name for `responseMode` = `download`. Tokens allowed: `report-{__variables.route.id}.pdf`.                                                                                                                              |
| **Reload current element data after success** | `reloadCurrentElementAfterSuccess` | The element that fired the action reloads its own data source afterwards.                                                                                                                                                    |
| **Reload data sources after success**         | `reloadDataSourceNames`            | Comma-separated source names re-fetched after success. Example: `loadPersons, loadSummary`.                                                                                                                                  |
| **Elements to reload**                        | `reloadElementNames`               | Comma-separated element names; each reloads its own data source. Example: `ordersTable, summaryCards`.                                                                                                                       |
| **Show toast after successful action**        | `showToastAfter`                   | Enables the [toast fields](https://ngxviewbuilder.io/creators/events-actions#action-type-toast) below the action.                                                                                                                                                             |

```json
{
  "trigger": "click",
  "type": "dataSource",
  "label": "Export",
  "dataSourceName": "exportPdf",
  "params": [{ "param": "year", "path": "reportYear" }],
  "responseMode": "download",
  "responseFileName": "report-{reportYear}.pdf"
}
```

## Action type: `sendMessage`

Pushes a message through a [WebSocket source](https://ngxviewbuilder.io/creators/data-sources#websocket) that is already connected. The source's own **Message** field only fires once, when the connection opens, so anything the user triggers later goes through this action.

| Field | JSON key | What it does |
| --- | --- | --- |
| **WebSocket data source** | `dataSourceName` | The source whose open connection carries the message. Only WebSocket sources work here. |
| **Message** | `messagePayload` | Text or JSON to send. Placeholders are filled in from the form: `{"action":"publish","label":"{el1}"}`. |

```json
{
  "trigger": "click",
  "type": "sendMessage",
  "label": "Notify everyone",
  "dataSourceName": "liveFeed",
  "messagePayload": "{ \"action\": \"publish\", \"label\": \"{userName}\" }"
}
```

Whatever the server broadcasts in reply arrives through the same source, so every window watching that feed updates at once, including the one that pressed the button. Nothing is sent when the connection is down at that moment.

## Action type: `setValue`

Writes a value into any field or variable.

| Field                            | JSON key             | What it does                                                                                                                                               |
| -------------------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Target variable or data path** | `setValueTargetPath` | Where to write. Use a variable name or `__variables.name` for variables, or any data path. Example: `__variables.selectedRow`, `selectedRow`, `client.id`. |
| **Value source**                 | `setValueMode`       | How the value is produced: `contextPath` (copy from another path), `template` (text with tokens), `json` (object/array literal).                           |
| **Value**                        | `setValueValue`      | The value itself, interpreted per mode, see below.                                                                                                         |

| Mode                | Value example                                  |
| ------------------- | ---------------------------------------------- |
| Context path        | `value`, `item`, `row.id`, `el3.selectedTab`   |
| Text template       | `Selected tab: el3.selectedTab`                |
| JSON object / array | `{ "id": "row.id", "tab": "el3.selectedTab" }` |

Values written to variables can then feed dialogs, expressions, and data source actions.

```json
{
  "trigger": "click",
  "type": "setValue",
  "label": "Remember row",
  "setValueTargetPath": "__variables.selectedRow",
  "setValueMode": "contextPath",
  "setValueValue": "row"
}
```

## Action type: `setOptions`

Replaces the option list of a choice element, so you can build dependent dropdowns without a server round-trip.

| Field              | JSON key                  | What it does                                                                     |
| ------------------ | ------------------------- | -------------------------------------------------------------------------------- |
| **Target element** | `setOptionsTargetElement` | The select/radio/checkbox element whose options are replaced.                    |
| **Options source** | `setOptionsMode`          | Same three modes as `setValue`: `contextPath`, `template`, `json`.               |
| **Options**        | `setOptionsValue`         | Provide an array, or a response object containing `items`, `data`, or `results`. |

| Mode         | Value example                                    |
| ------------ | ------------------------------------------------ |
| Context path | `items`, `response.items`, `__variables.options` |
| JSON         | `[{"label":"A","value":"a"}]`                    |
| Template     | `[{"label":"{row.name}","value":"{row.id}"}]`    |

```json
{
  "trigger": "change",
  "type": "setOptions",
  "setOptionsTargetElement": "citySelect",
  "setOptionsMode": "contextPath",
  "setOptionsValue": "__variables.citiesByCountry"
}
```

## Action type: `reloadElements`

Re-runs the data sources of the named elements. Use after anything that changes server data.

| Field                                    | JSON key             | What it does                                                                                                                                                                                                         |
| ---------------------------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Elements to reload (comma separated)** | `reloadElementNames` | Each listed element reloads its own data source. Example: `ordersTable, summaryCards`. The editor lists all reloadable elements; if none exist yet, first assign a data source to a table, list, or another element. |

```json
{
  "trigger": "click",
  "type": "reloadElements",
  "reloadElementNames": "ordersTable, summaryCards"
}
```

## Action type: `toast`

Shows a notification. The same fields appear on any `dataSource` action when **Show toast after successful action** is on.

| Field                      | JSON key          | What it does                                                                                            |
| -------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------- |
| **Toast title**            | `toastTitle`      | Short title. Example: _Data updated_.                                                                   |
| **Toast message**          | `toastMessage`    | Additional explanation. Example: _Table data reloaded_.                                                 |
| **Toast variant**          | `toastVariant`    | Visual type: `success`, `info`, `warning`, `error`.                                                     |
| **Toast position**         | `toastPosition`   | Where on screen: `top-left`, `top-center`, `top-right`, `bottom-left`, `bottom-center`, `bottom-right`. |
| **Show icon**              | `toastShowIcon`   | Whether the toast shows an icon at all.                                                                 |
| **Icon name**              | `toastIcon`       | Material Symbols icon. Example: `check_circle`, `info`.                                                 |
| **Auto hide**              | `toastAutoHide`   | Hide the toast automatically.                                                                           |
| **Auto hide timeout (ms)** | `toastAutoHideMs` | How long to show it. Example: `7000` = 7 seconds.                                                       |

```json
{
  "trigger": "click",
  "type": "toast",
  "toastTitle": "Saved",
  "toastMessage": "Your changes are stored.",
  "toastVariant": "success",
  "toastPosition": "top-right",
  "toastAutoHide": true,
  "toastAutoHideMs": 4000
}
```

## Action type: `dialog`

Opens, closes, or toggles a named [Dialog element](https://ngxviewbuilder.io/creators/elements/containers#dialog-dialog).

| Field                | JSON key          | What it does                                                                                                                                   |
| -------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| **Dialog name**      | `dialogName`      | The `name` of the Dialog element. The editor lists existing dialogs; if it says _No dialogs yet_, drop a Dialog element onto the canvas first. |
| **Dialog operation** | `dialogOperation` | `open`, `close`, or `toggle`.                                                                                                                  |

```json
{
  "trigger": "click",
  "type": "dialog",
  "dialogName": "clientDialog",
  "dialogOperation": "open"
}
```

## Action type: `validate`

Validates the whole form and shows field errors, the same check the built-in **Validate** toolbar button runs, available as an action on any button. No extra fields. Fires the host app's `onValidating`/`onValidated` events.

```json
{ "trigger": "click", "type": "validate", "label": "Check for errors" }
```

## Action type: `submit`

Validates the form, then fires the host app's `onComplete` event with `{ isValid, data, issues }`, the same behaviour as the built-in **Submit** toolbar button, available as an action on any button (a custom-styled submit button inside a panel, for example). No extra fields.

```json
{ "trigger": "click", "type": "submit", "label": "Submit application" }
```

## Row-action context (tables)

Actions attached to table rows (`rowActions`, `rowClickActions`, `expandedRowActions`, `selectionActions`) get extra context tokens:

| Token                           | Meaning                                        |
| ------------------------------- | ---------------------------------------------- |
| `{row.*}`                       | The clicked row object                         |
| `{parentRow.*}`                 | The parent row (in expanded/nested tables)     |
| `{value}`                       | The cell value (in cell actions)               |
| `{checked}`                     | Toggle/checkbox state (in interactive columns) |
| `{__table.<name>.selectedRows}` | Selected rows of a table                       |

Tables also offer **quick action** presets (_View_, _Edit_, _Copy_, _Delete_) that pre-fill a row action for you.

The same tokens reach the events of an element hosted in a table cell or in a dynamic-table row, plus two more: `{index}` for the row position, and a bare `{fieldName}` as a short form for a sibling field of the same row. A Select in a table column can therefore fire `Row {row.name} is now {value}` on change and name the correct row. See [Cell elements](https://ngxviewbuilder.io/creators/elements/tables#cell-elements).

## Recipes

**Save + refresh + notify** (button, `click`):

```json
{
  "trigger": "click",
  "type": "dataSource",
  "label": "Save",
  "dataSourceName": "saveClient",
  "validateForm": true,
  "reloadElementNames": "clientsTable",
  "showToastAfter": true,
  "toastTitle": "Saved",
  "toastVariant": "success"
}
```

**Dependent dropdowns** (country select, `change`): call `loadCities` with param `countryId = {country}` and `responseMode: "setValue"` into the city element, or bind the city element's own data source with **React to change** on `{country}`.

**Delete with confirmation** (table row action):

```json
{
  "label": "Delete",
  "type": "dataSource",
  "dataSourceName": "deleteClient",
  "params": [{ "param": "id", "path": "row.id" }],
  "confirmEnabled": true,
  "confirmTitle": "Delete client?",
  "confirmMessage": "This cannot be undone.",
  "reloadElementNames": "clientsTable",
  "buttonTone": "risk"
}
```

**Navigate with a saved draft** (button, `click`): `navigate` to `/orders/new` with **Run data source before navigation** = `saveOrderDraft` and **Use response path before navigation** = `__variables.orderDraft`. The draft is stored before the user leaves, and `reloadOnReturnElements` refreshes the list when they come back.

---

## Expressions basics

Source: https://ngxviewbuilder.io/creators/expressions

# Expressions basics

Expressions are short formulas used across the builder: in logic properties (`visibleIf`, `disableIf`…), calculated values, validators, action conditions, and option filters.

## Referencing fields

Wrap an element **name** in curly braces to get its current value:

```text
{country}                    value of the element named "country"
{clientType} == "company"    comparison
{price} * {quantity}         math
```

If the referenced field is empty, the token resolves to an empty value, so use `isEmpty()` / `notEmpty()` to test for that.

## Operators

| Kind | Operators |
| --- | --- |
| Comparison | `==` `!=` `>` `>=` `<` `<=` |
| Logic | `&&` (and), `\|\|` (or), `!` (not) |
| Math | `+` `-` `*` `/` |
| If/else in one line | `condition ? valueIfTrue : valueIfFalse` |

Examples:

```text
{age} >= 18 && {country} == "LT"
{isVip} ? {amount} * 0.9 : {amount}
!isEmpty({email}) || !isEmpty({phone})
```

## Functions

69 built-in functions cover text, arrays, numbers, and dates:

```text
isEmpty({companyCode})
contains({roles}, "admin")
{price} * {quantity}
dateDiffDays({startDate}, {endDate})
```

Full list with examples: [Function reference](https://ngxviewbuilder.io/creators/functions).

## Writing a value

An expression can also write. Put the target on the left and it becomes a write instead of a comparison:

```text
{variable1} = {price} * {quantity}
{variable1} += {row.column3}
```

`=` sets the value, `+=` adds to it. The same thing spelled out is `setValue()` and `sumValue()`. Use `+=` from an action, since it adds again on every run. See [Writing values back](https://ngxviewbuilder.io/creators/functions#writing-values-back).

## Context tokens

| Token | Available | Meaning |
| --- | --- | --- |
| `{fieldName}` | everywhere | Value of a named element |
| `row.fieldName` / `row.index` | inside tables | Current row's field / index |
| `panel.fieldName` / `panel.index` | inside dynamic panels | Current entry's field / index |
| `parentIndex` | nested repeaters | Index in the surrounding repeater |
| `{__variables.name}` | everywhere | A [variable](https://ngxviewbuilder.io/creators/variables) (route param, constant, computed) |
| `{__external.name}` | everywhere | Context provided by the host application (user, role…) |
| `{el1[parentIndex].country}` | nested repeaters | Indexed access into a repeater's data |

Runtime state of some containers is also addressable: `{myTabs.selectedTab}`, `{flow.selectedStepIndex}`.

## Boolean vs. value expressions

- **Condition properties** (`visibleIf`, `disableIf`, `requireIf`, `readonlyIf`, `resetIf`, validator conditions, action conditions) must return **true or false**.
- **Value properties** (`expression`, `defaultValue`) may return text, a number, a boolean, an array, or an object.

## When expressions run

An expression re-evaluates automatically whenever any field it references changes. For text inputs you can tune *when* with **Logic execution mode**: on input (every keystroke), on change, or on blur (leaving the field).

## Debugging

Wrap any part in `dbg(value, "label")`. It logs the value to the browser console and passes it through unchanged:

```text
visibleIf: dbg({clientType}, "clientType") == "company"
```

The expression editor also shows an inline help panel with tokens, functions, and example patterns for the property you are editing.

---

## Your first form

Source: https://ngxviewbuilder.io/creators/first-form

# Your first form

This walkthrough builds a small **client registration form**: name, email, client type, a company-only section, and a submit button. It touches the four skills you will use every day: placing elements, naming them, adding logic, and previewing.

## 1. Place the fields

From the **Single line inputs** group, drag onto the canvas:

- **Text**: set *Label* to `First name`, *Name* to `firstName`.
- **Text**: set *Label* to `Email`, *Name* to `email`.

From the **Choice inputs** group:

- **Radio**: set *Label* to `Client type`, *Name* to `clientType`. In the **Options** category add two options: `Private person` (value `person`) and `Company` (value `company`).

::: tip
Drag two elements next to each other to place them side by side in one row. Set their *Width* in the **Design** category, for example `50%` each.
:::

## 2. Make fields required

Select the email field and in the **Restrictions** category turn on **Required**. In **Validators**, set *Required message* to `Email is required`.

Then add a format check: in **Validators → Validators** add a rule of type `email` with the message `Enter a valid email address`.

## 3. Add a conditional section

From **Containers**, drag a **Panel** below the radio. Set its *Label* to `Company details`. Inside it place a **Text** element named `companyCode` with label `Company code`.

Select the panel and in the **Logic** category set:

```
visibleIf:  {clientType} == "company"
```

The panel now appears only when *Company* is selected. Expressions in `{curly braces}` reference other fields by name; see [Expressions basics](https://ngxviewbuilder.io/creators/expressions).

Make the company code mandatory only when visible. On the `companyCode` field set:

```
requireIf:  {clientType} == "company"
```

## 4. Add a submit button

From **Actions**, drag a **Button**. Set *Label* to `Register`. In the **Actions** category add an event:

- **Trigger**: `click`
- **Validate form**: on
- **Type**: `toast` with title `Done`, message `Registration saved`, variant `success`

In a real project the button would call a data source (`Type: dataSource`) to send the data to a server; see [Events & actions](https://ngxviewbuilder.io/creators/events-actions).

## 5. Preview

Switch to the **Preview** tab. Test that:

- Submitting an empty form shows the required messages.
- Choosing *Company* reveals the company panel and makes the code required.
- A valid submit shows the success toast.

## The result

Your form produces this data object at runtime:

```json
{
  "firstName": "Jonas",
  "email": "jonas@example.com",
  "clientType": "company",
  "companyCode": "305674321"
}
```

Every key is the `name` you gave an element. This is what the application receives when the form is submitted.

## Next steps

- [Pages & navigation](https://ngxviewbuilder.io/creators/pages): split long forms into steps.
- [Validation](https://ngxviewbuilder.io/creators/validation): all validator types.
- [Data sources](https://ngxviewbuilder.io/creators/data-sources): load the client types from an API instead of hardcoding them.

---

## Form settings

Source: https://ngxviewbuilder.io/creators/form-settings

# Form settings

The **Settings** tab holds everything that applies to the whole view rather than one element. It has four groups: **General**, **Form header**, **Navigation and actions**, and **Rendering and dialog**.

## General

| Setting | What it does |
| --- | --- |
| **Status** | `Default` (editable) or `Read only`. A read-only view displays values but blocks editing everywhere. Individual elements can opt out with *Inherit parent state*. |
| **Current language** | The content language shown right now in the builder and preview. |
| **Default language** | The language the view starts in at runtime. |
| **Supported languages (comma separated)** | Languages the view offers, e.g. `en, lt, de`. Texts for them are managed in the [Translations](https://ngxviewbuilder.io/creators/translations) tab. |
| **Locale** | Number/date formatting locale (e.g. `lt-LT`, `en-US`). Used by number formatting, date pickers, and table totals. |
| **Form width** + **Form width unit** | Maximum content width of the rendered view (`px` or `%`). |
| **Element spacing** | Vertical gap between element rows. |

## Form header

The optional header block rendered above the first page.

| Setting | What it does |
| --- | --- |
| **Show logo** | Toggles the logo. |
| **Logo URL or base64** | Image source: a URL or an inline base64 data URI. |
| **Upload logo file as base64** (*Add file*) | Pick a local file; it is embedded into the view JSON as base64. A **logo preview** is shown below. |
| **Logo alignment** | `Left`, `Center`, or `Right`. |
| **Show title** + **Title text** | The header heading. |
| **Show description** + **Description text** | Additional text under the title. |

## Navigation and actions

| Setting | What it does |
| --- | --- |
| **Page navigation mode** | `Default` (Prev/Next buttons) or `Stepper` (numbered steps). |
| **Page navigation position** | Where the Prev/Next controls render: `Top`, `Bottom`, `Both`, or `None`. |
| **Stepper position** | Where the stepper renders when stepper mode is on. |
| **Action buttons position** | Where Validate/Submit render: `Top`, `Bottom`, `Both`, or `None`. |
| **Allow step without validation** | Users may move between steps/pages even when the current page is invalid. |
| **Show submit button** | The built-in Submit button (fires completion with data + validation result). |
| **Show validate button** | The built-in Validate button (checks without submitting). |
| **Show table of contents** | Renders a contents panel for long views. |
| **Show validation issues modal** | After a failed submit, shows a dialog listing every validation issue with links to the fields. |

See [Pages & navigation](https://ngxviewbuilder.io/creators/pages).

## Rendering and dialog

| Setting | What it does |
| --- | --- |
| **Render mode** | `Page` (normal, in the document flow) or `Dialog`, where the whole view opens as a modal. |
| **Dialog header title** / **Dialog header description** | Modal header texts. |
| **Dialog width** + **Dialog width unit** | Modal width (e.g. `720` + `px`, or `90` + `%`). |
| **Dialog max width** / **Dialog max height** | Upper bounds (e.g. `90vh`). |
| **Dialog padding** | Inner padding of the modal content. |
| **Dialog font size** | Base font size inside the modal. |
| **Show close button** | Adds an X to the modal header. |
| **Close button actions** | Actions to run when the close button is pressed (same editor as [Events & actions](https://ngxviewbuilder.io/creators/events-actions)), e.g. confirm unsaved changes, notify the host. |
| **Dialog footer actions** | Buttons rendered in the modal footer, each a full action definition. |
| **Dialog footer alignment** | `Left`, `Center`, or `Right`. |

Dialog mode is useful when a developer embeds the view as a popup (e.g. "New client" from a table toolbar). The host is notified through `onDialogClosed` when it closes.

---

## Expression functions

Source: https://ngxviewbuilder.io/creators/functions

# Function reference

All functions available in expressions, grouped by purpose. Your project may add [custom functions](https://ngxviewbuilder.io/developers/custom-functions) on top; check the expression editor's help panel for the live list.

## Emptiness & text

| Function | Returns | Example |
| --- | --- | --- |
| `isEmpty(value)` | true if empty (`null`, `""`, `[]`) | `isEmpty({companyCode})` |
| `notEmpty(value)` | true if not empty | `notEmpty({email})` |
| `len(value)` | length of text or array | `len({items}) >= 3` |
| `startsWithAny(text, prefix)` | true if text starts with prefix | `startsWithAny({iban}, "LT")` |
| `endsWithAny(text, suffix)` | true if text ends with suffix | `endsWithAny({code}, "99")` |

## Collections

| Function | Returns | Example |
| --- | --- | --- |
| `contains(collection, value)` | true if array/text contains value | `contains({roles}, "admin")` |
| `includesAny(collection, value)` | alias of `contains` | `includesAny({tags}, "vip")` |
| `containsAny(collection, values)` | true if any of the values present | `containsAny({roles}, ["admin","editor"])` |
| `containsAll(collection, values)` | true if all values present | `containsAll({perms}, ["read","write"])` |
| `inArray(value, collection)` | true if value is in collection | `inArray({el2}, {el1})` |

## Numbers

| Function | Returns | Example |
| --- | --- | --- |
| `toNumber(value)` | value as number (invalid → 0) | `toNumber({codeFromApi}) > 10` |
| `inRange(value, min, max)` | true if min ≤ value ≤ max | `inRange({age}, 18, 65)` |

::: tip When toNumber is actually needed
A Number field already stores a number, so `{price} * {quantity}` is correct as written and
wrapping both sides adds nothing. Use `toNumber` when the value really arrives as text: a
Text field, a value from a data source, a select whose options carry string values, or a
Number field switched to *Store value as: string*.

It has a second, deliberate use. `toNumber` turns anything invalid into `0`, so an empty
field becomes zero instead of leaving the whole calculation empty. If that is the behaviour
you want, keep it, and know that you kept it for the default and not for the conversion.
:::

## Array aggregation

For dynamic panel / dynamic table values (arrays of objects). `selector` is the field name inside each entry.

| Function | Returns | Example |
| --- | --- | --- |
| `sumInArray(source, selector)` | sum | `sumInArray({orderLines}, "amount")` |
| `avgInArray(source, selector)` | average | `avgInArray({grades}, "score")` |
| `minInArray(source, selector)` | minimum | `minInArray({offers}, "price")` |
| `maxInArray(source, selector)` | maximum | `maxInArray({offers}, "price")` |
| `countInArray(source, selector)` | count | `countInArray({employees}, "id")` |
| `firstInArray(source, selector)` | first value | `firstInArray({history}, "status")` |
| `lastInArray(source, selector)` | last value | `lastInArray({history}, "status")` |
| `joinInArray(source, selector, separator)` | joined text | `joinInArray({tags}, "name", ", ")` |
| `collectValuesFrom(source, selector, unique)` | array of values | `collectValuesFrom({orders}, "id", true)` |

## Searching and filtering arrays

The functions above work on a field name. These ones take a **condition** instead, written the same way you write any other expression, and evaluate it once per entry.

| Function | Returns | Example |
| --- | --- | --- |
| `filterArray(source, condition)` | the matching entries | `filterArray({users}, role == "ADMIN")` |
| `findInArray(source, condition)` | the first matching entry, or nothing | `findInArray({products}, id == {selectedId})` |
| `existsInArray(source, condition)` | true if at least one entry matches | `existsInArray({items}, status == "ACTIVE")` |
| `countInArray(source, condition)` | how many entries match | `countInArray({tasks}, status == "OPEN")` |
| `getFirst(source, condition?)` | first entry, optionally the first match | `getFirst({tasks}, status == "OPEN")` |
| `getLast(source, condition?)` | last entry, optionally the last match | `getLast({history})` |
| `sumArray(source, selector)` | sum of a field | `sumArray({orderItems}, price)` |
| `avgArray(source, selector)` | average of a field | `avgArray({grades}, score)` |
| `minArray(source, selector?)` | smallest number over the entries | `minArray({orderItems}, price)` |
| `maxArray(source, selector?)` | largest number over the entries | `maxArray({orderItems}, price)` |
| `countArray(source, condition?)` | how many entries match, or the length without a condition | `countArray({tasks}, status == "OPEN")` |
| `joinArray(source, selector?, separator?)` | the projected values as text | `joinArray({users}, name, ", ")` |
| `mapArray(source, selector)` | one value per entry | `mapArray({users}, name)` |

Inside a condition you write the entry's own field names directly, with no braces. Everything else in the view stays visible, so you can compare against another element or a variable:

```text
countInArray({tasks}, status == {statusFilter})
filterArray({orders}, status == {el5} && total > {minTotal})
filterArray({users}, role == {__variables.requiredRole})
```

Calls nest, which is how you go from a filtered set to a single text:

```text
joinInArray(mapArray(filterArray({tasks}, status == "OPEN"), title), "", ", ")
```

`countInArray` also still accepts a plain field name, so older views keep working. Anything containing a comparison is treated as a condition.

## Dates

| Function | Returns | Example |
| --- | --- | --- |
| `today()` | today, `YYYY-MM-DD` | `Default value: =today()` |
| `now()` | current date-time (ISO) | timestamp fields |
| `date(value, mode)` | normalised date (`iso`, `datetime`, `timestamp`) | `date({created}, "iso")` |
| `day(value)` / `month(value)` / `year(value)` | date parts | `year({birthDate}) < 2000` |
| `weekDay(value, locale, style)` | weekday name | `weekDay({date}, "en", "long")` |
| `weekDayIndex(value)` | Monday=1 … Sunday=7 | `weekDayIndex({date}) <= 5` |
| `isWeekend(value)` | true on Sat/Sun | `visibleIf: isWeekend({deliveryDate})` |
| `addDays(value, days)` | date + n days | `addDays(today(), 14)` |
| `dateDiffDays(from, to)` | day difference | `dateDiffDays({start}, {end}) >= 1` |
| `startOfWeek(value)` / `endOfWeek(value)` | week boundaries | report period defaults |

## Data & element control

Advanced. These reach outside the current field:

| Function | Does | Example |
| --- | --- | --- |
| `getVal(path)` | reads any value by data path | `getVal("addresses[0].city")` |
| `setElementProperty(name, key, value)` | sets another element's property | `setElementProperty("step2", "disabled", true)` |
| `getElementProperty(name, key)` | reads another element's property | `getElementProperty("sel1", "label")` |
| `getProp(name, key)` | alias of `getElementProperty` | `getProp({sel1}, "placeholder")` |
| `setProp(name, key, value)` | alias of `setElementProperty` | `setProp({el1}, "label", "New label")` |
| `runDataSource(name)` | reloads a data source, returns its result | `runDataSource("loadUsers")` |
| `reloadDataSource(name)` | alias of `runDataSource` | |
| `dataSourceValue(name, contextElement?)` | the payload a data source loaded last, without waiting for a request | `len(dataSourceValue("loadUsers")) > 0` |

`getVal` also answers for a field the user has not touched yet, reading the value straight off the element, so `{price} * 2` no longer collapses the moment one side is still empty.

`getElementProperty` reaches any configured property, not just the value, and nested keys work:

```text
getProp("sel1", "placeholder")
getProp("sel1", "options[0].label")
getProp("orders", "dataSource.name")
```

## Writing values back

Everything above reads. These write, so a total or a collected list can be parked in a variable or in another field without leaving the expression language:

| Function | Does | Example |
| --- | --- | --- |
| `setValue(target, value)` | writes the value and returns it | `setValue({variable1}, sumArray({el1}, el5[].column3))` |
| `setVar(name, value)` | same, target always read as a variable name | `setVar({variable1}, {el2} + {el3})` |
| `sumValue(target, value)` | adds a number to what is already there, returns the new total | `sumValue({variable1}, {row.column3})` |
| `sumVar(name, value)` | same, for variables | `sumVar({variable1}, {row.column3} + 40)` |
| `addValue(target, value)` | alias of `sumValue` | `addValue({total}, {row.column3})` |
| `pushValue(target, value)` | appends to the target's array, returns it | `pushValue({variable1}, {row})` |
| `pushVar(name, value)` | same, for variables | `pushVar({selected}, {el2})` |
| `flattenArray(source)` | flattens nested arrays into one level | `flattenArray(collectValuesFrom({el1}, el5[]))` |

The target names a variable or an element, it is not replaced by its current value. If the name matches a declared variable the value goes to the variable, otherwise to that element's data path.

`sumValue` and `pushValue` change the result every time they run, so use them from an [action](https://ngxviewbuilder.io/creators/events-actions), not from a condition that recalculates on its own. `setValue` is safe anywhere: writing the value that is already there does nothing, which is what keeps an expression from looping on the change it caused itself.

An array argument is summed before it is added, so a whole column lands in one call:

```text
sumValue({variable1}, collectValuesFrom({el1}, el5[].column3))
```

### Assignment shorthand

The same two writers have a shorter form. Put the target on the left:

```text
{variable1} = {row.column3} + 40
{variable1} = ({variable1} + ({row.column3} + 40))
{variable1} += {row.column3}
```

`=` becomes `setValue`, `+=` becomes `sumValue`. Only the leftmost token is the target; on the right side `{variable1}` reads normally, which is how the second line adds to itself. Comparisons are untouched, `{el2} == 5` stays a condition.

### Totals across a dynamic panel

A table inside a dynamic panel exists once per panel entry, so its rows sit deeper in the data. The `[]` selector walks through every level:

```text
{variable1} = sumArray({el1}, el5[].column3)
{variable1} = flattenArray(collectValuesFrom({el1}, el5[]))
```

The first sums one column across all panels, the second gathers every row of every table into one list.

## Labels of choice elements

A Select, Radio, or Checkbox group stores a code and shows a label. Only the element knows the pairing, so these two functions ask it directly:

| Function | Returns | Example |
| --- | --- | --- |
| `getValue(element)` | the stored value | `getValue({status})` gives `OPEN` |
| `getLabel(element, value?)` | the displayed label | `getLabel({status})` gives `Open issue` |

Name the element either way you prefer, `getLabel({status})` or `getLabel("status")`. The token is treated as the element's name here, not as its value. Pass a second argument to translate some other value through the same option list: `getLabel("status", "CLOSED")`. For a multi select you get one label per selected value.

## Translating dynamic values

Values coming from an API never pass through the Translations tab, because that tab only knows the texts written into the view. `translate()` opens the same per-language dictionary to any key:

| Function | Returns | Example |
| --- | --- | --- |
| `translate(value, fallback?)` | the translated text | `translate({row.status})` |
| `t(value, fallback?)` | alias of `translate` | `t({row.status}, "Unknown")` |
| `currentLanguage()` | active language code | `currentLanguage() == "en"` |

See [Translations](https://ngxviewbuilder.io/creators/translations#translating-values-that-come-from-data) for where the keys live.

## Debugging

| Function | Does | Example |
| --- | --- | --- |
| `dbg(value, label?)` | logs to console, returns the value | `dbg({el2.selectedStep}, "step")` |
| `clog(value, label?)` | alias of `dbg` | `clog({price}, "price")` |

---

## JSON editor

Source: https://ngxviewbuilder.io/creators/json-editor

# JSON editor

The **JSON** tab shows the entire view definition, the same JSON the application loads at runtime. Everything you configure visually is stored here; everything you type here appears in the visual editor.

## When to use it

- **Bulk edits**: rename a value across many expressions with find & replace.
- **Copying**: move an element or a whole page between views.
- **Fixing**: resolve an odd state faster than clicking through properties.
- **Reviewing**: see exactly what will be handed to developers.

## Structure at a glance

```json
{
  "settings":     { "width": "1182", "language": "en" },
  "pages":        [ { "name": "page1", "rows": [ { "columns": [ { "elementRef": "firstName" } ] } ] } ],
  "elements":     {
    "page1":     { "name": "page1", "label": "Page 1", "type": "page" },
    "firstName": { "name": "firstName", "label": "First name", "type": "text", "required": true }
  },
  "dataSources":  [ { "name": "loadCountries", "type": "rest", "params": { "url": "..." } } ],
  "localization": { "defaultLanguage": "en", "languages": ["en"], "texts": {} }
}
```

Key ideas:

- `pages[].rows[].columns[]` describe **layout**; each column points at an element by `elementRef`.
- `elements` is a flat map of **every element's configuration**, keyed by name.
- Logic properties are plain strings: `"visibleIf": "{clientType} == \"company\""`.

Full field-by-field reference: [Structure JSON](https://ngxviewbuilder.io/developers/structure-json) (developer docs).

## Safety

- The editor validates JSON as you type, so syntax errors are flagged before they can break the view.
- An element referenced in `rows` must exist in `elements` (and vice versa), so keep both sides in sync when hand-editing.
- Copy the whole JSON to a scratch file before large manual edits.

---

## Layout & containers

Source: https://ngxviewbuilder.io/creators/layout

# Layout & containers

## Rows and columns

The canvas is a stack of **rows**. Each row holds one or more **columns**, and each column holds exactly one element. You create layout by dragging:

- Drop an element **below** another → new row.
- Drop an element **beside** another → same row, new column.
- Drop an element **into a container** → nested rows inside that container.

## Widths

Every element has three width properties in the **Design** category:

| Property | Applies on |
| --- | --- |
| Width | Desktop |
| Tablet width | Tablet viewport |
| Mobile width | Mobile viewport |

Use `%` for fluid layouts (`50%`, `33%`) or `px` for fixed sizes. **Fit content** makes the element only as wide as its content, which suits buttons.

Test each breakpoint with the viewport switcher in [Preview](https://ngxviewbuilder.io/creators/preview).

## Container elements at a glance

| Container | Use for |
| --- | --- |
| **Panel** | Grouping related fields under a heading, with background/border styling |
| **Tabs** / **Tabs Pro** | Switching between sections without leaving the page |
| **Accordion** | Collapsible sections |
| **Dynamic panel** | A repeatable group where the user adds and removes entries (e.g. several addresses) |
| **Dialog** | Content that opens in a modal window |
| **Splitter** | Two resizable side-by-side areas |
| **Spacer** | Empty vertical space |
| **Divider** | A horizontal separator line |

Details and properties for each: [Containers](https://ngxviewbuilder.io/creators/elements/containers).

## Element spacing

The global gap between rows is set in **Form settings → Element spacing**. Panels additionally have their own padding controls (desktop and mobile) in the **Design** category.

## Practical guidelines

- Group related fields into panels; users scan grouped forms faster.
- Prefer 2 columns maximum on data-entry forms; more becomes hard to scan.
- Set mobile widths to `100%` for nearly everything.
- Use a Dynamic panel instead of duplicating the same fields ("Address 1", "Address 2"…).

---

## Pages & navigation

Source: https://ngxviewbuilder.io/creators/pages

# Pages & navigation

A view can have one page or many. Pages appear in the footer strip under the canvas: click to switch, use **+** to add, drag to reorder.

## When to use multiple pages

- Long forms that would otherwise scroll forever.
- Step-by-step flows ("wizard") where each step must validate before the next.
- Screens with clearly separate stages: *Details → Documents → Review*.

## Navigation modes

Set in **Form settings → Page navigation mode**:

| Mode | Behaviour |
| --- | --- |
| `default` | Previous / Next buttons between pages |
| `stepper` | A visual stepper shows all pages; users move step by step |

By default a page must pass validation before the user can continue. Turn on **Allow step without validation** in Form settings to let users move freely.

## Positions

Form settings let you place navigation chrome where it suits the layout:

- **Page navigation position**: `top`, `bottom`, `both`, or `none`.
- **Stepper position**: where the step indicator renders.
- **Action buttons position**: where Validate/Submit buttons render.

## Page states

Select a page to set page-wide states:

- **Read only**: all elements on the page display values but reject edits.
- **Disabled**: all elements on the page are inactive.

Individual elements can opt out with **Ignore parent state**, or explicitly follow the parent with **Inherit parent state**.

## Submit and validate buttons

Form settings control the built-in buttons:

- **Show validate button**: runs validation without submitting.
- **Show submit button**: validates and completes the form.
- **Show validation issues modal**: lists all validation errors in a dialog after a failed submit.

If you build your own submit button (a Button element with actions), you can hide the built-in ones.

---

## Preview & testing

Source: https://ngxviewbuilder.io/creators/preview

# Preview & testing

The **Preview** tab runs the view with the real runtime engine, the same code end users get. Nothing is simulated: logic, validation, data sources, and actions all execute for real.

## Viewports

Switch between **desktop / tablet / mobile** widths to verify responsive settings (Width / Tablet width / Mobile width). Fix layout issues before publishing, not after.

## What to test

Work through this list on every view:

- **Empty submit**: required messages appear, the issues modal (if enabled) lists them all.
- **Conditional paths**: flip every field referenced by a `visibleIf`/`requireIf` and watch dependent sections appear, become required, and reset.
- **Wrong input**: invalid email, out-of-range numbers, bad patterns; every validator shows its own message.
- **Long values**: a 200-character name, a long option label; layout should not break.
- **Data sources**: dropdowns fill, dependent lists reload, tables page and search.
- **Actions**: buttons navigate, save, confirm, and toast as configured.
- **Languages**: switch each configured language; check for missing translations and overflowing texts.
- **All viewports**: especially multi-column rows on mobile.

## Inspecting the data

Preview shows the live form data as you type (the same object the application will receive). Verify that:

- every value lands under the expected key (element `name`),
- hidden-and-reset fields don't leave stale values behind,
- calculated fields produce the right numbers.

## Debugging expressions

If a rule doesn't fire, wrap the suspect part in `dbg()` and watch the browser console:

```text
visibleIf: dbg({clientType}, "clientType") == "company"
```

Common causes: a typo in the element name inside `{braces}`, comparing a number with a quoted string (`{amount} == "100"`), or referencing a field inside a repeater without `row.`/`panel.` context.

---

## Common properties

Source: https://ngxviewbuilder.io/creators/properties

# Common properties

Most elements share the same core properties. Element-specific properties are covered on each [element page](https://ngxviewbuilder.io/creators/elements/).

::: tip Finding a property
The properties sidebar has a **search box** (*Search in property list*): type part of a property name to filter. Every field also has a **help icon**: hover it for a short explanation with an example.
:::

## How the sidebar is organised

Properties are grouped into sections. Only sections relevant to the selected element appear:

| Section | What it holds |
| --- | --- |
| **Identity** | Name, label, and basic identifiers |
| **Content** | Visible texts, titles, placeholders, and content fields |
| **Input** | Input modes, autocomplete, and user input UX |
| **Formatting** | Masks, locale, and value formatting settings |
| **Primary source** | Data source binding and response paths |
| **Request** | Request params, lazy load, and backend request settings |
| **Search** | Quick or detailed search and their extra settings |
| **Saved filters** | Saved filters data source and payload schema |
| **Options schema** | Option lists, filtering, and selection modes |
| **Selection** | Table selection and selected item configuration |
| **Details** | Expanded rows, details panel, and nested views |
| **Pagination** | Paginator and footer control |
| **Header controls** | Header bar, export, and search controls |
| **Columns schema** | Main and expanded table columns |
| **Trigger button** | Button that opens a dialog or another action |
| **State** | Hidden, disabled, and readonly states |
| **Limits** | Min/max, lengths, counts, and other restrictions |
| **Deletion** | Delete flow and confirm settings |
| **Validation** | Required, validators, and strict options |
| **Visibility logic** | Visible-if and open conditions |
| **Interaction logic** | Disable, require, and readonly conditions |
| **Value logic** | Expression, default value, and reset conditions |
| **Execution modes** | Logic and validation execution mode settings |
| **Actions** | Events and action collections |
| **Layout** | Width, padding, orientation, gap, and overall layout |
| **Surface** | Borders, backgrounds, shadows, and page or panel surfaces |
| **Appearance** | Variants, colors, icons, and visual accents |
| **Advanced** | Rare or specialized properties |

## Identity & content

| Property | What it does |
| --- | --- |
| **Name (code)** | Unique element code in the JSON structure. The element's value is stored under this key, and logic, data paths, and other elements reference it as `{name}`. Change with care. Example: `el1` or `personFirstName`. |
| **Label** | The main caption visible to the user. Keep it clear in business terms. |
| **Field help tooltip** | Help text shown next to the label as a tooltip, for explanations that should be available on demand but not always visible. |
| **Description** | Help text below the label, for longer explanations that should always be visible at runtime. |
| **Placeholder text** | Text shown while the field is empty. Use as an example or short hint, not as the only explanation. |
| **Title** / **Subtitle** | Main heading text and secondary text for elements with their own header (cards, page titles, panels). |
| **Text** | Main text for content-style elements (button caption, badge text…). |
| **Icon** | Material Symbol or registered SVG icon code, used as a visual accent or a shorter way to present an action. |
| **Type** | Switches the element to a closely related type without recreating it (e.g. `text` → `number`), preserving shared properties. |

## State

| Property | What it does |
| --- | --- |
| **Hidden** | Element is completely hidden from the user (its value and logic still exist). |
| **Initially visible** | Whether the element is shown immediately when the form opens, before logic or user actions apply. |
| **Disabled** | Field is inactive; the user cannot change it. |
| **Read only** | Value is displayed but cannot be edited. |
| **Inherit parent state** | Element follows the read-only/disabled state of its parent container or page. Turn off to unlock one child inside a locked container. |
| **Ignore parent state** | Legacy compatibility field; use *Inherit parent state* instead. |
| **Status** | Legacy compatibility field; for new elements use the *Read only* checkbox. |

Static `Disabled`/`Hidden` are fixed choices. For state that depends on other fields, use the **logic** conditions below.

## Limits

| Property | What it does |
| --- | --- |
| **Min / Max length** | Character limits on text inputs. *Min length* means the field counts as filled/valid only from that many characters. |
| **Min / Max value** | Numeric or date/time boundaries (numbers, sliders, date pickers). |
| **Pattern** | Extra RegExp check on text values, for strict formats such as codes, registration numbers, identifiers. |
| **Max rows** | Row limit for dynamic tables/panels. The add button disables at the limit. |
| **Max files / Max file size (MB)** | Upload limits on file elements. |

## Validation

| Property | What it does |
| --- | --- |
| **Required** | Value must be filled before submit. Pair with a clear message. |
| **Required field message** | Error text shown when a required field is empty. Localise it on multilingual forms. |
| **Validators** | A list of extra rules: built-in (min/max, length, pattern, email) or a custom condition with its own error message. Each validator has **Type**, **Value**, **Error message**, **Condition** (error when true), and **Apply if** (optional guard). See [Validation](https://ngxviewbuilder.io/creators/validation). |
| **Strict options** | On choice elements: validates that the current value(s) still exist among the available options. |

## Logic

All conditions are expressions entered via **Edit code**; see [Expressions basics](https://ngxviewbuilder.io/creators/expressions).

| Property | Expects | What it does |
| --- | --- | --- |
| **Visible if** | true/false expression | Shows the element only while true. Example: `{el1} == "yes"` |
| **Disable if** | true/false expression | Disables while true. Example: `{el1} != "yes"` |
| **Require if** | true/false expression | Makes required while true. Example: `{el2} == 1` |
| **Read only if** | true/false expression | Locks editing while true. Example: `{status} == "locked"` |
| **Reset if** | true/false expression | Resets the value to *Default value* when the condition **becomes** true (fires on the transition). |
| **Expression** | any value | Calculates the element's value from other fields. Example: `{price} * {quantity}` |
| **Default value** | static value | Initial value on load and the value restored by *Reset if*. |

Details: [Conditional logic](https://ngxviewbuilder.io/creators/conditional-logic) and [Calculated values](https://ngxviewbuilder.io/creators/calculated-values).

## Actions

| Property | What it does |
| --- | --- |
| **Events** | The action list: click → navigate, click → dataSource, change → setValue, click → toast… Every field of the action editor is documented in [Events & actions](https://ngxviewbuilder.io/creators/events-actions). |

## Input & formatting (typed inputs)

| Property | What it does |
| --- | --- |
| **Autocomplete** | HTML `autocomplete` attribute, which lets the browser fill standard data. Example: `given-name`, `email`, `street-address`. |
| **Input mode** | HTML `inputmode` hint. Mobile browsers show a matching keyboard. Options: `text`, `email`, `numeric`, `decimal`, `search`, `tel`, `url`, browser default. |
| **Spellcheck** | Keep or disable the browser spell-checker on text fields. |
| **Input mask** | Mask template. Built-ins: date, date time, time, digits, phone, international phone, personal code, or `custom`. |
| **Mask pattern** | The custom mask: `#` digit, `A` letter, `*` letter or digit. Example: `####-##-##` or `+1 ##########`. |

## Design

| Property | What it does |
| --- | --- |
| **Width** | Field width in desktop/base mode, in `%`, `px`, or other CSS units. Example: `100%` or `320px`. |
| **Tablet width** | Width for tablet. Empty = falls back to the base width. |
| **Mobile width** | Width for mobile. Empty = falls back to tablet width, then base width. |
| **Fit content** | Shrink to content width instead of filling the row. |
| **Background color, padding, radius, shadow, border** | Available on visual/surface elements like panels, buttons, badges; see the element pages and [Layout](https://ngxviewbuilder.io/creators/layout). |

## Data

Select-style elements and data views have a **Data source** binding (section *Primary source*): which source to load, which response fields become option value/label, request parameters, and refresh rules. Dependent fields are supported through the parameter map and *Listen fields* (refresh paths). Every field of that editor is documented in [Data sources](https://ngxviewbuilder.io/creators/data-sources).

---

## Dynamic text & templates

Source: https://ngxviewbuilder.io/creators/templates

# Dynamic text & templates

## Dynamic text

Text-bearing properties (rich text, custom HTML, message cards, dialog titles, toast messages, set-value templates…) accept **double-brace placeholders** that render live values:

```text
Hello, {{firstName}} {{lastName}}!
Your order total is {{orderTotal}} €.
Application no. {{__variables.route.id}}
```

Placeholders re-render when the referenced values change. Inside repeaters, item context is available: <code v-pre>{{ item.name }}</code>, <code v-pre>{{ index }}</code>.

Simple logic is supported in template blocks:

```html
@if (item.status == "Active") {<span class="ok">Active</span>}
```

::: tip Single vs. double braces
`{name}` (single) is for **expressions**: logic properties, conditions, params.
<code v-pre>{{name}}</code> (double) is for **text templates**: content that renders on screen.
:::

## The template library

The **Templates** tab (plugin) manages reusable HTML templates. Define a card or option layout once, use it in any List grid, Select option template, or content block by picking its **name**, with no copy-pasting HTML between views.

A template has:

| Field                      | What it is                                                                                                                                    |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| **Name**                   | The identifier elements reference. Must be unique; the editor rejects duplicates.                                                             |
| **Title**                  | Human-friendly display title.                                                                                                                 |
| **Description**            | What the template is for.                                                                                                                     |
| **Tags (comma separated)** | For finding it later.                                                                                                                         |
| **HTML content**           | The markup, with <code v-pre>{{placeholders}}</code>. Required. A small **format** icon button (top-right corner of the box) tidies the HTML. |
| **CSS**                    | Styles scoped to the template, with its own **format** icon button.                                                                           |
| **Template fields**        | Declares the data fields the template expects (e.g. `jarStatus` or `status.code`) so pickers can map data onto slots.                         |

The preview panel next to the editor renders the template live against a fixed built-in sample object, so you can see card/option layouts update as you type there's nothing to configure for it.

### Storage settings

Where saved templates live (browser localStorage vs. a server-backed data source) isn't a field in this tab it's a setting your developer configures on the view. See [Templates plugin reference](https://ngxviewbuilder.io/developers/plugin-templates#where-templates-are-read-from-at-runtime) for the exact settings and how host persistence to your own database works.

### Example: client card

Template `clientCard`:

```html
<div class="client-card">
  <strong>{{ item.name }}</strong>
  <span>{{ item.email }}</span>
  <span class="badge">{{ item.status }}</span>
</div>
```

```css
.client-card {
  display: flex;
  flex-direction: column;
  gap: 4px;
  padding: 12px;
  border: 1px solid #ddd;
  border-radius: 8px;
}
.client-card .badge {
  color: #0a7;
  font-size: 12px;
}
```

Then on a List grid: _Card template_ → `clientCard`. Every view using the template updates when the template is edited.

## Where templates are stored

Depending on the **Storage mode** above, templates live in browser localStorage or on a server through a data source. The host application can also supply and persist templates through its own API including saving them into your own database. Your developer configures this (see the [Templates plugin reference](https://ngxviewbuilder.io/developers/plugin-templates) for the full syntax and integration details); as a creator you just save templates in the Templates tab.

## Template actions

Templates can contain clickable areas that trigger data sources (the template action map). If your project uses them, buttons inside template HTML can call server functions; ask your developer which action names are wired up.

---

## Translations

Source: https://ngxviewbuilder.io/creators/translations

# Translations

A view can serve several languages from one definition. Content texts (labels, descriptions, placeholders, messages, options) are translated in the **Translations** tab.

## How it works

1. **Form settings → Language** sets the default language.
2. The **Translations** tab lists all languages of the view. Add a language with **+**.
3. The tab shows every translatable text in a table: one row per text, one column per language. Fill in the empty cells.
4. At runtime, the host application (or the language switcher) selects which language renders.

The texts live in the view definition under `localization`:

```json
"localization": {
  "defaultLanguage": "lt",
  "languages": ["lt", "en"],
  "texts": {
    "en": { "elements.firstName.label": "First name" }
  }
}
```

## What gets translated

- Element labels, descriptions, placeholders, tooltips
- Option labels of choice elements
- Validation and required messages
- Page names, dialog titles, button texts

Untranslated texts fall back to the default language, so the view never shows blanks.

## Translating values that come from data

The Translations tab only sees texts written into the view. A status arriving from an API (`BUG`, `QUESTION`, `FEATURE`) is data, so it is never listed there, yet it still has to read properly in every language.

Put the raw value in the dictionary as its own key and wrap the token in `translate()`:

```json
"texts": {
  "en": { "BUG": "Bug", "QUESTION": "Question", "FEATURE": "Feature" },
  "lt": { "BUG": "Klaida", "QUESTION": "Klausimas", "FEATURE": "Funkcija" }
}
```

```text
translate({row.status})
```

Two things worth knowing. A `values.` prefix is checked as well, so `values.BUG` keeps these keys apart from element paths if you prefer that. And when the key is missing, the original value is shown unchanged, which means adding a new status to the backend never leaves an empty cell.

It works anywhere an expression does, most usefully in a table's Badge or text cell. Pass a second argument for a different fallback, `translate({row.status}, "Unknown")`, and read the active language with `currentLanguage()`.

For a Select or Radio you usually want [`getLabel()`](https://ngxviewbuilder.io/creators/functions#labels-of-choice-elements) instead, since the option list already holds the translated label.

## Locale vs. language

**Language** picks the text set. **Locale** (Form settings) controls number and date formatting: `lt-LT` renders `1 234,56`, `en-US` renders `1,234.56`. Set both for a fully localised view.

## Tips

- Finish the structure first, translate last. Renaming elements after translating creates orphaned texts.
- Keep messages short; translated German/Lithuanian text is often longer than the English draft and can break tight layouts.
- Test each language in [Preview](https://ngxviewbuilder.io/creators/preview) with the language switcher.

---

## Form validation

Source: https://ngxviewbuilder.io/creators/validation

# Validation

Validation runs when the user submits, when a page changes in stepper mode, and (depending on settings) while editing. Failing elements show their error message and block submission.

## Required

Turn on **Required** in the Validation section, or use **Require if** for conditional requirement. Set the error text in **Required field message**.

The red asterisk that marks a required field belongs to the label. An element with no label text and no help tooltip renders no label row at all, so the asterisk is not drawn either: floating above an empty space it marks nothing. The field is still required and still validated. When a bare field has to advertise that it is mandatory, give it a label, or say so in its placeholder or description.

## The validator editor

The **Validators** property holds a list of rules. Click **Add validator** to create one; each rule has these fields:

| Field | What it does |
| --- | --- |
| **Type** | Which check to run, see the table below. |
| **Value** | The rule's setting (a length, a bound, a pattern…). |
| **Error message** | Shown when this rule fails. Each rule carries its own message. |
| **Condition (error when true)** | For `custom` rules: an expression that flags an **error while it is true**. |
| **Apply if (optional)** | A guard expression: the whole rule is checked only while this is true. |

| Type | Checks | Example value |
| --- | --- | --- |
| `required` | value present | - |
| `minLength` / `maxLength` | text length | `3` / `50` |
| `min` / `max` | numeric bounds | `0` / `100` |
| `pattern` | regular expression | `^[0-9]{9}$` |
| `email` | email format | - |
| `strictOptions` | value exists in the option list | - |
| `custom` | your own condition | see below |

The list can be longer in your application: developers can register named rules such as *LT personal code* or *IBAN*, which then appear in **Type** exactly like the built-ins. See [custom validator types](https://ngxviewbuilder.io/developers/custom-validators). A rule shown as `(not registered)` comes from a view built in another application that had such a rule; it is skipped until that application registers it.

## Custom validators

A `custom` rule is a true/false [expression](https://ngxviewbuilder.io/creators/expressions) that describes the **error**: the message shows while the condition is true. You can write it directly or assemble it in the visual rule builder (field + operator + value, joined with and/or).

```text
dateDiffDays({startDate}, {endDate}) < 1        error: end date not after start
{password} != {passwordRepeat}                  error: fields don't match
{advance} > {total}                             error: advance exceeds total
len({phone}) > 0 && !startsWithAny({phone}, "+370")   error: filled but wrong prefix
```

The last pattern (*filled AND wrong*) makes a rule optional: it only fires once the user typed something.

**Apply if** solves the same thing declaratively: set *Apply if* to `len({phone}) > 0` and the condition to `!startsWithAny({phone}, "+370")`.

## When validation runs

**Validation execution mode** (per element, in *Execution modes*) controls the trigger:

| Mode | Validates |
| --- | --- |
| `onBlur` (default) | when leaving the field |
| `onChange` | when the value changes |
| `onInput` | on every keystroke |

## Input masks vs. validators

Masks (Text element) *prevent* wrong input while typing; validators *check* afterwards. For strict formats use both: a `date` mask plus a `pattern` validator.

## Error summary

**Form settings → Show validation issues modal** lists all failing fields in a dialog after a failed submit, which helps on long, multi-page forms.

## Server-side errors

Developers can attach extra errors to any element from the host application (`setElementErrors`), e.g. *"E-mail already registered"* after a backend check. They render exactly like validator errors.

## Good error messages

- Say what is expected, not just "invalid": `Company code is 9 digits`, not `Wrong format`.
- Keep the message next to the rule that triggers it; each validator has its own message.
- For translated views, provide messages in each language via the [Translations](https://ngxviewbuilder.io/creators/translations) tab.

---

## Variables

Source: https://ngxviewbuilder.io/creators/variables

# Variables

Variables are named values defined once (in the **Variables** tab) and readable from every expression as `{__variables.name}`, or just `{name}` when it doesn't clash with an element name.

## Variable types

The **Type** column decides where the value comes from:

| Type | Value comes from | Example |
| --- | --- | --- |
| `route` | the URL: `route.id`, `route.params.id`, `route.queryParams.xxx`, `route.data.xxx`, `route.url` | `/clients/42/edit` → `clientId = 42` |
| `external` | context the host application provides via API | `external.apiBaseUrl`, `external.user`, `external.features.list` |
| `constant` | a fixed value you type | `maxUploadMb = 10` |
| `expression` | computed from other data | `isEditMode = notEmpty({__variables.route.id})` |
| `dataSource` | the result of a [data source](https://ngxviewbuilder.io/creators/data-sources) | `settings` loaded from the API |
| `manual` | set at runtime by a **Set value** [action](https://ngxviewbuilder.io/creators/events-actions#action-type-setvalue) or host code, never recalculated automatically | wizard state, selected row |

## Definition fields

Each row in the Variables tab has:

| Field | What it does |
| --- | --- |
| **Name** | Identifier used in expressions: `{__variables.name}`. |
| **Title** | Human label for the list. |
| **Type** | One of the types above. |
| **Value / Source** | The route path, external path, constant, expression, or data source name, depending on type. |
| **Fallback** | Used when the source resolves to nothing (e.g. no route param on `/clients/new`). |
| **Target path** | Also write the value into the form data at this path. |
| **To data JSON** | Ship the value with the submitted data. |
| **Reload data source when fields change** | For `dataSource` variables: re-run the source when watched fields change. |
| **Listen fields** | Comma-separated paths that trigger the reload. Reload runs only when one of these changes. Example: `userId, data.user.type, filters.status`. |
| **Refresh** | Manually re-resolve variables after structure or source changes. |

## When variables recalculate

An `expression` variable behaves like any other calculated value. It watches every field it references and recomputes the moment one of them changes, and anything reading the variable updates in the same pass. A chain like `variable1 = {el1} + {el2}` feeding an element with `expression: {variable1}` settles immediately, with no need to leave and re-enter the view.

Referencing a field the user has not filled in yet is fine. The variable simply resolves to nothing and falls back to **Fallback** if you set one, rather than showing a broken value.

## Writing into a variable

Besides the **Set value** action, any expression can write into a variable:

```text
{variable1} = sumArray({el1}, el5[].column3)
{variable1} += {row.column3}
```

Handy for running totals and for collecting rows out of a dynamic panel. A `manual` variable is the right type here, since nothing recalculates it behind your back. Details and the function form in [Writing values back](https://ngxviewbuilder.io/creators/functions#writing-values-back).

A total collected this way belongs to one run of the form, not to the view. Leaving Preview clears it along with the rest of the working data, so coming back into Preview starts from the fallback again instead of carrying on from the previous total.

## Using variables

```text
visibleIf:      {__variables.route.mode} != "view"
Default value:  {__variables.route.clientId}
disableIf:      {__external.userRole} != "admin"
Data source param:  id = {__variables.route.clientId}
Navigate to:    /clients/{__variables.route.clientId}/history
```

`{__external.*}` is a shortcut to everything the host application passed as external context, with no definition needed.

## Example: edit vs. create mode

The same form serves `/clients/new` and `/clients/42/edit`:

1. Variable `clientId`: source `route`, fallback empty.
2. Variable `isEdit`: source `expression`, `notEmpty({__variables.clientId})`.
3. Load panel data with source `GET /api/clients/{id}`, param `id = {__variables.clientId}` (skipped automatically when empty, so nothing loads in create mode).
4. Page title element: dynamic text <code v-pre>{{isEdit ? "Edit client" : "New client"}}</code>.
5. Save button condition: `{__variables.isEdit}` → `PUT` action; otherwise `POST` action (two actions with opposite conditions).

---

## The builder workspace

Source: https://ngxviewbuilder.io/creators/workspace

# The builder workspace

The builder screen has four working areas:

| Area | Location | Purpose |
| --- | --- | --- |
| Elements sidebar | Left | Drag elements onto the canvas |
| Canvas | Center | The page you are building |
| Properties sidebar | Right | Configure the selected element |
| Header tabs | Top | Switch between builder modes |

![Builder workspace](https://ngxviewbuilder.io/first-look/builder.png)

## Elements sidebar

Elements are grouped so you can scan them quickly:

- **Single line inputs**: text, number, date, phone, and other typed fields.
- **Choice inputs**: dropdowns, checkboxes, radios, toggles.
- **Actions**: buttons and action-style controls.
- **Containers**: panels, tabs, accordions, dialogs, splitters.
- **Content**: text, images, video, icons, badges, cards.
- **Tables**: data tables, dynamic tables, list grids.

Use the search box at the top of the sidebar to filter by name. Drag any element into a row on the canvas or into a container.

You can also save your own configured elements (or whole groups of elements) back into the sidebar as reusable library items.

## Canvas

The canvas shows the current page. Elements are placed in **rows**; each row holds one or more **columns**, and each column holds one element. Drag elements to reorder them, drop them next to each other to share a row, or drop them inside containers.

Selecting an element highlights it and opens its settings on the right. The footer below the canvas lists all pages of the view: click to switch, add, or reorder pages.

## Properties sidebar

Every property of the selected element lives here, organised into categories:

| Category | What it holds |
| --- | --- |
| General | Name, label, placeholder, description, tooltips |
| Data | Data source bindings and request parameters |
| Options | Choice lists for select-style elements |
| Columns | Column schema for tables |
| Restrictions | Required, disabled, read-only, hidden, length limits |
| Validators | Required message and extra validation rules |
| Logic | `visibleIf`, `disableIf`, `requireIf`, expressions, default value |
| Actions | Events that run actions (navigate, load data, toast…) |
| Design | Width, responsive widths, colors, padding |

Only the categories relevant to the selected element are shown. See [Common properties](https://ngxviewbuilder.io/creators/properties) for the full reference.

## Header tabs

| Tab | Purpose |
| --- | --- |
| Builder | The visual editor (default) |
| Preview | Run the view exactly as end users will see it |
| JSON | Edit the raw view definition |
| Templates | Manage reusable HTML templates *(plugin)* |
| Form settings | View-wide settings: width, navigation, buttons, custom CSS |
| Translations | Translate labels and texts into other languages |
| Variables | Define runtime variables (route params, constants, computed values) |

Developers can add more tabs through plugins. If you see extra tabs, they come from plugins installed in your application.

## Undo and history

The builder tracks your edits. Use undo/redo in the header to step through recent changes before saving.

---

## Live demo

Source: https://ngxviewbuilder.io/demo

<div class="demo-page">

# Live demo

Build a view in the **Builder** tab; every change is auto-saved to your browser. Switch to **Runtime** to see it exactly as end users would. Use **Fullscreen** for the real workspace feel. The demo follows the documentation theme (light/dark) automatically.

::: tip Want to see the actual code?
This demo shows the finished product. To see the real Angular code behind it, and edit it live, <a href="https://stackblitz.com/~/github.com/GN-159/ngxviewbuilder-stackblitz?file=src/app/pages/builder-page/builder-page.component.ts" target="_blank" rel="noopener"><strong>open the starter project on StackBlitz →</strong></a>
:::

<DemoEmbed />

</div>

---

## Angular Form, View & Dashboard Builder | NGX View Builder

Source: https://ngxviewbuilder.io/

<section class="caps">
<header class="caps__intro">
<h2 class="caps__headline">Everything a real screen needs, in three moves.</h2>
<p class="caps__lede">A view is one JSON document. You compose it, connect it to your systems, and ship it inside your own Angular app, with no separate runtime to host and no black box.</p>
</header>
<div class="caps__grid">
<div class="caps__phase">
<div class="caps__phase-head">
<h3 class="caps__phase-title">Compose</h3>
</div>
<ul class="caps__list">
<li><strong>Whole pages, not just forms</strong><span>47 elements: inputs, choice controls, data tables, charts, KPI cards, tabs, dialogs, and steppers, with responsive layout per breakpoint.</span></li>
<li><strong>Enterprise-grade data tables</strong><span>Server-side paging, saved filters, per-user column settings, inline editing, row expansion, bulk actions, and status rules.</span></li>
<li><strong>Logic without code</strong><span>Show, hide, require, disable, and calculate with a concise expression language, 69 functions, and a visual condition builder.</span></li>
</ul>
</div>
<div class="caps__phase">
<div class="caps__phase-head">
<h3 class="caps__phase-title">Connect</h3>
</div>
<ul class="caps__list">
<li><strong>Live data, first-class</strong><span>REST, route, and local sources feed options, tables, and values. Dependent fields, lazy tables, param mapping, and auto-reload are built in.</span></li>
<li><strong>Extensible at every layer</strong><span>Register your own elements, expression functions, properties, icons, themes, and whole builder tabs. Capability gating hides absent features cleanly.</span></li>
<li><strong>AI-assisted building</strong><span>A built-in chat edits the view from plain-language requests, screenshots, or documents, wired to your own backend and model.</span></li>
</ul>
</div>
<div class="caps__phase">
<div class="caps__phase-head">
<h3 class="caps__phase-title">Ship</h3>
</div>
<ul class="caps__list">
<li><strong>Angular-native architecture</strong><span>Standalone components, signals, zoneless-ready. A typed API service exposes every structure, data, and lifecycle operation, with 59 events.</span></li>
<li><strong>Ready for real products</strong><span>Multi-language content, locale-aware formatting, light/dark theming with design tokens, headless validation, and a template library.</span></li>
<li><strong>Idea to production, fast</strong><span>Analysts build screens visually; developers embed them with one component. Version, review, and deploy a view like any other artifact.</span></li>
</ul>
</div>
</div>
</section>

## Built for both sides of the team

**Creators** get a professional visual workspace: drag elements onto pages, configure every property from a searchable sidebar, preview on desktop/tablet/mobile, and test with live data. No development environment required.

**Developers** get a serious integration surface instead of a black box:

```ts
import { NgxViewBuilderRuntime, NgxViewBuilderApiService } from 'ngx-view-builder';

@Component({
  imports: [NgxViewBuilderRuntime],
  template: `<ngx-view-builder-runtime [pageJson]="view" [dataJson]="data" theme="dark" />`,
})
export class ClientPage {
  private api = inject(NgxViewBuilderApiService);

  ngOnInit() {
    this.api.onComplete.add(async ({ isValid, data }) => {
      if (isValid) await this.save(data);
    });
  }
}
```

Everything the builder does is available programmatically: read and mutate structures, set values, reload data sources, switch themes and languages, validate headlessly, and observe 59 typed events. See the [API service reference](https://ngxviewbuilder.io/developers/api-service).

## The ideas it's built on

- **Views are data, not code.** A page is one JSON document, so you can store it in your database, template it, migrate it, diff it in code review, or generate it with AI. Nothing is compiled into your bundle at design time.
- **It runs in your app, not ours.** Views render inside *your* Angular app, using your router, your HTTP layer, your auth, and your design tokens. There is no hosted runtime to depend on and no vendor to route your data through.
- **The tedious parts are already solved.** Dependent dropdowns, server-side tables, wizard navigation, validation summaries, translations, and per-user table preferences are configured, not hand-coded for the hundredth time.
- **It scales from a form to an admin panel.** Start with a single contact form and grow into a builder-driven internal tool where your own domain elements sit in the sidebar next to the built-in ones.

Take the [5-minute first form tutorial](https://ngxviewbuilder.io/creators/first-form), embed the [runtime](https://ngxviewbuilder.io/developers/runtime-integration), or explore the [live demo](https://ngxviewbuilder.io/demo).

## Community & feedback

Everything public about NGX View Builder lives in the [community repository](https://github.com/ngxviewbuilder/ngx-view-builder-community):

- **Found a bug?** [Open an issue](https://github.com/ngxviewbuilder/ngx-view-builder-community/issues). A minimal structure JSON that reproduces it makes fixes much faster.
- **Have an idea or feature request?** File it as an issue too. Real-world use cases directly shape the roadmap.
- **Questions and discussions** are welcome in the same repository.

## Built on excellent open source

NGX View Builder stands on the shoulders of a small set of battle-tested open-source libraries. Thank you to their authors and maintainers.

<div class="oss-grid">
  <a class="oss-card" href="https://codemirror.net/" target="_blank" rel="noopener">
    <div class="oss-card__head"><span class="oss-card__name">CodeMirror 6</span><span class="oss-card__license">MIT</span></div>
    <p class="oss-card__text">Powers the JSON, HTML, and JavaScript editors inside the builder: syntax highlighting, autocompletion, and editing commands.</p>
  </a>
  <a class="oss-card" href="https://github.com/TomFrost/Jexl" target="_blank" rel="noopener">
    <div class="oss-card__head"><span class="oss-card__name">Jexl</span><span class="oss-card__license">MIT</span></div>
    <p class="oss-card__text">The engine behind the expression language. Every <code>visibleIf</code>, calculated value, and condition is evaluated by Jexl.</p>
  </a>
  <a class="oss-card" href="https://prettier.io/" target="_blank" rel="noopener">
    <div class="oss-card__head"><span class="oss-card__name">Prettier</span><span class="oss-card__license">MIT</span></div>
    <p class="oss-card__text">Formats structure JSON and code snippets in the editors so what you read is always tidy.</p>
  </a>
  <a class="oss-card" href="https://lodash.com/" target="_blank" rel="noopener">
    <div class="oss-card__head"><span class="oss-card__name">Lodash</span><span class="oss-card__license">MIT</span></div>
    <p class="oss-card__text">Utility functions (<code>lodash-es</code>) used across the library for safe, predictable data handling.</p>
  </a>
</div>

---

## Pricing

Source: https://ngxviewbuilder.io/pricing

<div class="pricing-page">

# Pricing

<p class="pricing-page__lede">The runtime that renders your views in production is free and never needs a license key. The builder is free to use today, and becomes a licensed product at the 1.0.0 release.</p>

<div class="plans">

<div class="plan">
  <p class="plan__name">Free</p>
  <p class="plan__price"><span class="plan__amount">€0</span></p>
  <p class="plan__terms">no license key, no expiry</p>
  <p class="plan__summary">The runtime. Everything that renders your views to your users, in production, at no cost.</p>
  <a class="plan__cta plan__cta--ghost" href="/developers/installation">Install it now</a>
  <p class="plan__features-head">The runtime, free forever</p>
  <ul class="plan__features">
    <li>The complete runtime, nothing held back</li>
    <li>Unlimited apps, views and end users</li>
    <li>Commercial and production use</li>
    <li>Every runtime version, forever</li>
    <li>Bug reports and questions on GitHub</li>
  </ul>
</div>

<div class="plan plan--featured">
  <p class="plan__name">Base<span class="plan__flag">Free until 1.0.0</span></p>
  <p class="plan__price"><span class="plan__amount">€399</span></p>
  <p class="plan__terms">once, per developer<br>includes updates and support for the first 12 months</p>
  <p class="plan__summary">The builder. The visual editor your team designs those views in, on top of everything in Free.</p>
  <button class="plan__cta" disabled>Available at 1.0.0</button>
  <p class="plan__features-head">Everything in Free, plus</p>
  <ul class="plan__features">
    <li>The complete builder, nothing held back</li>
    <li>No watermarks, nag screens or license banners</li>
    <li>Perpetual license<span>Every builder version released during your 12 months keeps working forever.</span></li>
    <li>Elements, functions or plugins built on request<span>When they make sense for everyone using the library.</span></li>
    <li>Support for 12 months</li>
  </ul>
</div>

</div>

<p class="plans__note"><strong>Nothing is for sale yet.</strong> Until the 1.0.0 release the builder is free for everyone, with no key and no watermark. The price is published now only so you can plan a budget around it. Checkout opens at 1.0.0.</p>

## What the license actually covers

The paid license does not unlock hidden features. The free build and the licensed build are the same package. What you pay for is the right to use the builder, the visual editor your team designs views in, without a watermark, and to keep the versions released during your license term.

The runtime is a separate matter. It renders your views to your end users, it never checks a license, and it never expires, in any version, before or after 1.0.0. Shipping it to production and to your customers costs nothing. That is not a beta promotion, it is the model.

## What changes at 1.0.0

- The builder starts requiring a license key. **The runtime is not affected and never will be.**
- Pre-1.0.0 builder versions stay free to keep using.
- Without a key, the builder still runs in full, with a watermark on the canvas and a banner above it. See [what users see](https://ngxviewbuilder.io/developers/licensing#what-users-see).
- Every builder version released during your 12 months keeps working, watermark-free, forever. Read the [full license terms](https://ngxviewbuilder.io/developers/licensing).

## Questions?

Email **[support@ngxviewbuilder.io](mailto:support@ngxviewbuilder.io)**. Happy to talk through your use case ahead of launch, including team and volume pricing.

<p class="pricing-page__note">For bigger conversations (strategic partnerships, exclusive licensing, or acquiring the product outright) the same address reaches us directly.</p>

</div>

---

## Privacy Policy

Source: https://ngxviewbuilder.io/privacy

# Privacy Policy

*Last updated: 18 July 2026*

This policy covers **ngxviewbuilder.io** and **demo.ngxviewbuilder.io** (together, "the Site"), operated by NGX View Builder ("we", "us"). For questions, contact **[support@ngxviewbuilder.io](mailto:support@ngxviewbuilder.io)**.

## What we collect

**Documentation site.** After you accept the cookie banner, we use Google Analytics 4 to understand how the docs are used: pages visited, approximate location (derived from a truncated/anonymized IP), device and browser type, referrer, on-site search terms, and a small number of custom interaction events (e.g. which code snippets get copied, which demo tab you open). If you decline or don't respond to the banner, no analytics script loads and no analytics cookie is set.

**Live demo.** The structure you build in the demo (`/demo`) is saved only in your browser's local storage. We do not receive, store, or process it on any server.

**Contacting us.** If you email us, we process your email address and message content only to respond to you.

## Cookies and local storage

| Name | Purpose | Set when |
| --- | --- | --- |
| `nvb-analytics-consent` | Remembers your cookie-banner choice | Always (strictly necessary, and not a tracking cookie) |
| Google Analytics cookies (`_ga`, `_ga_*`) | Distinguish visitors and sessions for analytics | Only after you accept |
| Demo structure (`localStorage`) | Auto-saves what you build in the live demo | When you use `/demo` |

## Legal basis

Analytics processing relies on your **consent** (GDPR Art. 6(1)(a)), which you can withdraw at any time by clearing your browser's site data for this domain, after which the banner reappears on your next visit. Responding to emails relies on our **legitimate interest** in providing support.

## Third parties

We use **Google Analytics** (Google Ireland Limited) as a data processor for the analytics described above. Google's own privacy policy and data-transfer safeguards apply to its processing: [policies.google.com/privacy](https://policies.google.com/privacy). We do not sell your data or share it with any other third party.

## Retention

Analytics data is retained according to our Google Analytics account settings. Emails are kept as long as needed to handle your inquiry and any follow-up.

## Your rights

Under GDPR you have the right to access, correct, delete, or export your data, to object to or restrict its processing, and to withdraw consent at any time. To exercise any of these, email **[support@ngxviewbuilder.io](mailto:support@ngxviewbuilder.io)**. You may also lodge a complaint with your local data protection authority: in Lithuania, the [State Data Protection Inspectorate (VDAI)](https://vdai.lrv.lt/).

## Children

The Site is not directed at children, and we do not knowingly collect data from them.

## Changes

We may update this policy as the product evolves (for example, once accounts or billing go live). The "last updated" date above will reflect any change.

---