Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.veloiq.dev/llms.txt

Use this file to discover all available pages before exploring further.

DynamicResource is the core UI abstraction in @veloiq/ui. It provides four React components — DynamicList, DynamicShow, DynamicCreate, and DynamicEdit — that render complete CRUD pages entirely from a ModelDef schema object. You pass the schema and the full model registry; the components handle field rendering, relation display, form validation, pagination, sorting, filtering, and role-based field visibility automatically.

​
Components

​
DynamicList

Renders a paginated, sortable, filterable list page. Columns are derived from the model’s FieldDef array. The list integrates with Refine’s data provider for pagination (using _start/_end query parameters) and reads x-total-count from the response header. Bulk actions can be supplied via the BulkActionDef type. 
import { DynamicList } from "@veloiq/ui";

<DynamicList model={taskModel} allModels={allModels} />

​
DynamicShow

Renders a detail page for a single record. Displays all readable fields grouped by the model schema. Shows related records using the RelationDef configuration — each relation can render as a table, editable table, list, gallery, calendar, tree, or tree-details view depending on its showViewType. Also renders a relations explorer panel and supports side-by-side Miller-columns tree navigation. 
import { DynamicShow } from "@veloiq/ui";

<DynamicShow model={taskModel} allModels={allModels} />

​
DynamicCreate

Renders a creation form. Each form field is generated from the corresponding FieldDef: type determines the input widget, options populates select inputs, required adds validation, and writeRoles hides inputs that the current user cannot write. 
import { DynamicCreate } from "@veloiq/ui";

<DynamicCreate model={taskModel} allModels={allModels} />

​
DynamicEdit

Renders an edit form with the same field generation logic as DynamicCreate. Pre-populates fields from the fetched record. Read-only fields (those with readOnly: true or where the user lacks writeRoles) are displayed but not editable. 
import { DynamicEdit } from "@veloiq/ui";

<DynamicEdit model={taskModel} allModels={allModels} />

​
ModelDef type

ModelDef is the top-level schema object that describes a single resource. All four DynamicResource components accept model: ModelDef as their primary prop.
FieldTypeRequiredDescription
namestringYesModel identifier, matched against allModels for relation resolution.
labelstringYesHuman-readable label shown in page headings and the sidebar.
fieldsFieldDef[]YesOrdered list of field definitions. See FieldDef below.
relationsRelationDef[]NoRelated resources rendered in the show and edit pages. See RelationDef below.
resourcestringNoURL resource name. Defaults to name when absent.
modulestringNoModule identifier. Used to group resources in the sidebar via generateResources.
pkFieldstringNoPrimary key field name. Defaults to "id".
hideInMenubooleanNoExclude this model from the sidebar. Defaults to false.
descriptionstringNoShort description shown in the page header.
listViewType"table" | "gallery" | "calendar" | "totals-details"NoDefault view type for the list page. Defaults to "table".

​
FieldDef type

Each entry in ModelDef.fields is a FieldDef that controls how a single attribute is displayed and edited.
FieldTypeRequiredDescription
keystringYesColumn/attribute name matching the API response key.
labelstringYesDisplay label for the field.
type"string" | "number" | "boolean" | "date" | "datetime" | "time" | "image_url"YesData type. Controls the input widget and display formatter.
isPkbooleanNoMark this field as the primary key.
requiredbooleanNoAdds a required validator to the form field.
readOnlybooleanNoDisplay the field but prevent editing in forms.
referencestringNoResource name of a related model, enabling a select input that fetches options.
optionLabelstringNoField name to use as the display label when fetching reference options.
options{ label: string; value: any }[]NoStatic option list for select inputs.
optionsUrlstringNoURL to fetch dynamic options from.
valueColorsRecord<string, string>NoMaps field values to hex color strings for badge/tag display.
readRolesstring[]NoRoles allowed to read this field. Absent means all roles. Emitted by veloiq_field(read_roles=…).
writeRolesstring[]NoRoles allowed to write this field. Absent means all roles. Emitted by veloiq_field(write_roles=…).
descriptionstringNoTooltip text shown next to the field label.
nullablebooleanNoAllows the field to be empty in forms.
uniquebooleanNoDisplayed as a hint; not enforced client-side.
formulastringNoComputed field formula (display only).

​
RelationDef type

Each entry in ModelDef.relations describes a related resource rendered in the show and edit pages.
FieldTypeRequiredDescription
resourcestringYesResource name of the related model.
targetKeystringYesForeign key column on the related resource that points to this record’s PK.
labelstringYesSection heading for the relation block.
showViewType"table" | "editable-table" | "editable-list" | "list" | "csv" | "gallery" | "calendar" | "primary" | "totals-details" | "tree" | "tree-details"NoView type for the relation in the show page.
editViewTypeSame as showViewTypeNoView type for the relation in the edit page.
otherKeystringNoJoin table column pointing to the related resource’s PK (for many-to-many).
otherResourcestringNoIntermediate join resource name.
resourcePathstringNoAPI path override for the relation (e.g. "user_role" for the join table).
minItemsnumberNoMinimum cardinality (from jm_relationship).
maxItemsnumberNoMaximum cardinality (from jm_relationship).
showTabstringNoGroup this relation under a named tab in the show page.
editTabstringNoGroup this relation under a named tab in the edit page.
millerLeafConfigsMillerLeafConfig[]NoMultiple leaf pane configurations for tree-details Miller columns.

​
Auto-generated schemas

veloiq generate creates {module}Schema.gen.ts in each module’s frontend directory. This file contains the ModelDef array for all models in the module and is overwritten on every run — do not edit it directly. 
// tasks/taskSchema.gen.ts — AUTO-GENERATED. Run `veloiq generate` to update.
import type { ModelDef } from "@veloiq/ui";

export const taskModels: ModelDef[] = [
  {
    name: "Task",
    label: "Task",
    resource: "task",
    fields: [
      { key: "id", label: "ID", type: "number", isPk: true },
      { key: "title", label: "Title", type: "string", required: true },
      { key: "status", label: "Status", type: "string" },
    ],
    relations: [],
  },
];

​
Manual schema overrides

To extend or override the generated schema without losing your changes on the next veloiq generate run:
  1. Create {module}Schema.manual.ts in the same directory.
  2. Merge it into {module}Schema.ts, which you maintain by hand.
// tasks/taskSchema.ts — maintained manually
import { taskModels as generated } from "./taskSchema.gen";
import { taskOverrides } from "./taskSchema.manual";
import { deepMergeModels } from "@veloiq/ui"; // or your own merge utility

export const taskModels = deepMergeModels(generated, taskOverrides);

​
generateResources and authSystemModels

generateResources(models, moduleName) converts a ModelDef[] into a Refine ResourceDef[] array with list/show/create/edit paths set. authSystemModels is a static ModelDef[] with built-in definitions for User, Role, and Tenant. 
import { generateResources, authSystemModels } from "@veloiq/ui";
import { taskModels } from "./tasks/taskSchema";

const resources = [
    ...generateResources(taskModels, "tasks"),
    ...generateResources(authSystemModels, "access_control", {
        moduleLabel: "Access Control",
    }),
];

UI Overview

All exports from @veloiq/ui at a glance.

Auth Providers

Wire up authProvider, accessControlProvider, and httpClient.