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.

@veloiq/ui is the React component library for VeloIQ frontend applications. It is built on top of Refine and Ant Design and provides everything you need to wire up a fully functional admin UI: schema-driven CRUD pages that render from ModelDef definitions without hand-written component code, layout components, JWT authentication providers, and role-based access control.

​
Installation

npm install @veloiq/ui
@veloiq/ui declares its Refine and Ant Design dependencies as peer dependencies. Install them alongside the package:
npm install @refinedev/core @refinedev/antd @refinedev/react-router-v6 antd axios react react-dom react-router-dom

​
Core components

ExportDescription
LayoutWrapperTop-level layout with sidebar, header, and content area. Wraps the authenticated section of your app.
MultiPaneLayoutResizable multi-pane layout for list + detail side-by-side views.
StandardShowStandard detail page for a single record without schema-driven configuration.
StandardListStandard list page without schema-driven configuration.
HierarchyViewTree-style hierarchical view for nested data structures.
GlobalSearchFull-text search across all indexed entity types and attributes.

​
DynamicResource

The DynamicResource components render complete CRUD pages from a ModelDef schema object. You do not write component code for each resource — the schema drives field rendering, relation display, form validation, and access control.
ExportDescription
DynamicListPaginated, sortable, filterable list page with column configuration derived from FieldDef.
DynamicShowDetail page with field display, relation panels, tree views, and a relations explorer.
DynamicCreateCreation form built from FieldDef definitions.
DynamicEditEdit form built from FieldDef definitions.
See DynamicResource for the full schema reference.

​
Types

ExportDescription
FieldDefSingle field definition: key, label, type, access roles, options, and constraints.
RelationDefRelation definition: target resource, display view type, cardinality, and Miller column config.
ModelDefTop-level model schema: name, label, fields, relations, and display options.
BulkActionDefBulk action definition for list-page multi-select operations.
MillerLeafConfigConfiguration for a Miller-columns leaf pane in tree-details relations.

​
Providers

ExportDescription
authProviderRefine AuthProvider implementation — handles login, logout, token storage, and identity. Passes a JWT Bearer token in every request.
accessControlProviderRefine AccessControlProvider implementation — reads role and resource permissions from the backend and hides or disables UI elements accordingly.
httpClientPre-configured Axios instance that attaches the JWT from localStorage to every request. Pass it to @refinedev/simple-rest’s data provider.
API_URLBase URL constant used by providers and the data provider. Defaults to "/api".
See Auth Providers for wiring instructions.

​
Utilities

​
generateResources(models, moduleName, options?)

Converts a ModelDef[] array into Refine ResourceDef[] definitions. Each module’s models are grouped under a shared parent resource so Refine renders a clean module label in the sidebar. Relation-only models (those whose name ends in _relation or _rela, or that have eid_from/eid_to fields) are hidden from the sidebar by default. 
import { generateResources } from "@veloiq/ui";
import { taskModels } from "./taskSchema";

const resources = generateResources(taskModels, "tasks");
// Returns: [{ name: "module:tasks", ... }, { name: "task", list: "/task", ... }, ...]
ParameterTypeDescription
modelsModelDef[]Array of model schemas for the module.
moduleNamestringModule identifier used as the parent resource key (module:<moduleName>).
options.iconReact.ReactNodeIcon shown next to the module group in the sidebar.
options.hideRelationsbooleanHide relation-only models from the sidebar. Defaults to true.
options.moduleLabelstringHuman-readable label for the module group. Defaults to the capitalized moduleName.

​
authSystemModels

A static ModelDef[] array with built-in definitions for the User, Role, and Tenant CRUD pages that correspond to the VeloIQ auth tables (veloiq_user, veloiq_role, veloiq_tenant). Pass these directly to generateResources to include an access-control section in your sidebar. 
import { authSystemModels, generateResources } from "@veloiq/ui";

const authResources = generateResources(authSystemModels, "access_control", {
    moduleLabel: "Access Control",
});

​
How it fits together

  1. Schema generation: veloiq generate creates {module}Schema.gen.ts for each backend module, containing ModelDef arrays that describe every model’s fields and relations.
  2. Resource registration: generateResources(models, moduleName) converts those ModelDef arrays into Refine resource definitions with correct list/show/create/edit paths.
  3. Routing: You map each resource path to the corresponding DynamicList, DynamicShow, DynamicCreate, and DynamicEdit components in your React Router routes.
  4. Auth: authProvider handles login against POST /auth/login, stores the JWT in localStorage, and redirects to /login on 401. accessControlProvider reads cached role permissions to hide unauthorized UI elements. httpClient attaches the token to every API call.

DynamicResource

Schema-driven CRUD page components and the ModelDef type reference.

Auth Providers

Wire up authProvider, accessControlProvider, and httpClient in App.tsx.