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
• Canonical 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.
• For a short list, give it options or a dataSource with useFor: "option"; it filters them as the user types.
• For a list that lives on a server, set searchDataSourceName to a source whose URL uses {query}, plus searchLabelKey and, usually, searchValueKey.
• Value shape: the option value, or the value key of the picked record. With a search source and no searchValueKey, the whole record object.

fileUpload

• Use for file uploads.
• storageMode: "base64" (default, the file content goes into the value, no backend needed) or "server" (uploaded through uploadDataSourceName). Set "server" explicitly whenever you configure upload/download/delete sources.
• Value shape, the same in both modes (an array when multiple): { name, size, type, lastModified, contentType } plus base64 or fileKey. In server mode the name, type, size and key are read from the response using fileKeyField/fileNameField/fileTypeField/fileSizeField.
• With base64, set maxFileSizeMb: the value is about a third larger than the file.
• 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 and File upload requests.

button

• Use to trigger an action.
• Not intended for form value storage.
• Common properties: text, variant, tone, textColor, events, disabled.
• The caption goes in text. A button has no field label: set label to "", otherwise a label row with the same words is drawn above the button.
• A solid button on a dark fill needs light text. That covers the default primary tone, success, info, risk, and any dark custom color: set textColor to "var(--nvb-color-neutral-000)". A host stylesheet can otherwise leave the caption dark on the dark fill. outline and text buttons, and the light warning tone, keep their default text color.

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:

{
  "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:

{
  "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.
• To stop adding or deleting under a condition use disallowAddRowsIf / disallowDeleteRowsIf (JEXL), not a disableIf on the whole table. disallowDeleteRowsIf is judged per row: {row.status} == "approved" keeps approved rows and lets the rest be deleted.

table

• Use for displaying data from a datasource.
• Supports sorting, filtering, paging, rowActions, and export, but start basic: columns, paging and quick search, with showDetailedSearch and showExport set to false (both default to true). Add detailed search, export, column settings, saved filters, selection, expandable rows or inline editing only when the user asks.
• Row actions go in the three-dots menu, rowActionsDisplayMode: "dropdown", unless the user explicitly asks for separate buttons, and the actions column shows no header text: showActionsHeaderLabel: false (it defaults to true). When the user does not say how a record opens, it opens from a Preview action in that menu, not from a row click.
• 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 and Table: server-side paging & filtering.
• 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.
• chartType: bar and horizontalBar compare categories (horizontal for long names), line and area show change over time, pie and donut show parts of a whole with at most six slices (more fold into "Other").
• showLegend and legendLayout apply to pie and donut only; single series charts have no legend, so put what is plotted in title.
• Click actions (events with trigger: "click") receive the clicked point as {item.label}, {item.value} and {index}.

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.

objectPanel

• Use when several fields should be saved as one object: an address, a contact person, company details.
• Children are laid out in column.rows like a panel's, but defined in the panel's template map, like a dynamicPanel's. Their names only have to be unique inside that panel.
• Their values land at <objectPanel>.<name>. Value shape: one object. Refer to its fields as {objectPanelName.fieldName}, or {panel.fieldName} from inside the same panel.
• No add or remove controls: it is always exactly one object.
• If the user should add several such groups, use dynamicPanel instead.

dynamicPanel

• Use for repeating sets of blocks.
• Value shape is typically: array of objects.
• Suitable for addresses, family members, and education records.
• disallowAddRowsIf and disallowDeleteRowsIf work the same as on dynamicTable: the add button is disabled while the first is true, and an entry where the second is true has no remove button.

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:

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:

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

Correct usage:

{
  "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:

{
  "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.