> ## 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: React Component Library for VeloIQ

> The @veloiq/ui package provides schema-driven CRUD pages, layout components, auth providers, and UI utilities for VeloIQ React frontends.

`@veloiq/ui` is the React component library for VeloIQ frontend applications. It is built on top of [Refine](https://refine.dev) and [Ant Design](https://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

```bash theme={null}
npm install @veloiq/ui
```

<Note>
  `@veloiq/ui` declares its Refine and Ant Design dependencies as peer dependencies. Install them alongside the package:

  ```bash theme={null}
  npm install @refinedev/core @refinedev/antd @refinedev/react-router-v6 antd axios react react-dom react-router-dom
  ```
</Note>

***

## Core components

| Export            | Description                                                                                           |
| ----------------- | ----------------------------------------------------------------------------------------------------- |
| `LayoutWrapper`   | Top-level layout with sidebar, header, and content area. Wraps the authenticated section of your app. |
| `MultiPaneLayout` | Resizable multi-pane layout for list + detail side-by-side views.                                     |
| `StandardShow`    | Standard detail page for a single record without schema-driven configuration.                         |
| `StandardList`    | Standard list page without schema-driven configuration.                                               |
| `HierarchyView`   | Tree-style hierarchical view for nested data structures.                                              |
| `GlobalSearch`    | Full-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.

| Export          | Description                                                                                  |
| --------------- | -------------------------------------------------------------------------------------------- |
| `DynamicList`   | Paginated, sortable, filterable list page with column configuration derived from `FieldDef`. |
| `DynamicShow`   | Detail page with field display, relation panels, tree views, and a relations explorer.       |
| `DynamicCreate` | Creation form built from `FieldDef` definitions.                                             |
| `DynamicEdit`   | Edit form built from `FieldDef` definitions.                                                 |

See [DynamicResource](/reference/ui-dynamic-resource) for the full schema reference.

***

## Types

| Export             | Description                                                                                     |
| ------------------ | ----------------------------------------------------------------------------------------------- |
| `FieldDef`         | Single field definition: key, label, type, access roles, options, and constraints.              |
| `RelationDef`      | Relation definition: target resource, display view type, cardinality, and Miller column config. |
| `ModelDef`         | Top-level model schema: name, label, fields, relations, and display options.                    |
| `BulkActionDef`    | Bulk action definition for list-page multi-select operations.                                   |
| `MillerLeafConfig` | Configuration for a Miller-columns leaf pane in tree-details relations.                         |

***

## Providers

| Export                  | Description                                                                                                                                         |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `authProvider`          | Refine `AuthProvider` implementation — handles login, logout, token storage, and identity. Passes a JWT Bearer token in every request.              |
| `accessControlProvider` | Refine `AccessControlProvider` implementation — reads role and resource permissions from the backend and hides or disables UI elements accordingly. |
| `httpClient`            | Pre-configured Axios instance that attaches the JWT from `localStorage` to every request. Pass it to `@refinedev/simple-rest`'s data provider.      |
| `API_URL`               | Base URL constant used by providers and the data provider. Defaults to `"/api"`.                                                                    |

See [Auth Providers](/reference/ui-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.

```typescript theme={null}
import { generateResources } from "@veloiq/ui";
import { taskModels } from "./taskSchema";

const resources = generateResources(taskModels, "tasks");
// Returns: [{ name: "module:tasks", ... }, { name: "task", list: "/task", ... }, ...]
```

| Parameter               | Type              | Description                                                                          |
| ----------------------- | ----------------- | ------------------------------------------------------------------------------------ |
| `models`                | `ModelDef[]`      | Array of model schemas for the module.                                               |
| `moduleName`            | `string`          | Module identifier used as the parent resource key (`module:<moduleName>`).           |
| `options.icon`          | `React.ReactNode` | Icon shown next to the module group in the sidebar.                                  |
| `options.hideRelations` | `boolean`         | Hide relation-only models from the sidebar. Defaults to `true`.                      |
| `options.moduleLabel`   | `string`          | Human-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.

```typescript theme={null}
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.

***

<CardGroup cols={2}>
  <Card title="DynamicResource" icon="layout-grid" href="/reference/ui-dynamic-resource">
    Schema-driven CRUD page components and the ModelDef type reference.
  </Card>

  <Card title="Auth Providers" icon="lock" href="/reference/ui-providers">
    Wire up authProvider, accessControlProvider, and httpClient in App.tsx.
  </Card>
</CardGroup>