Docyrus App Dev React

Docyrus App Dev React

Build Docyrus React TypeScript applications end-to-end. This skill combines app architecture, authentication, data access, query patterns, and production-grade UI guidance in one place.

Tech Stack

• React 19 + TypeScript + Vite
• TanStack Router (code-based), TanStack Query (server state), TanStack Form
• Tailwind CSS v4, shadcn/ui components
• @docyrus/api-client + @docyrus/signin + @docyrus/app-utils
• Auto-generated collections from OpenAPI spec
• Preferred UI libraries: shadcn, diceui, animate-ui, docyrus-ui, reui

When to Use This Skill

Use this skill when you are:

• Building or modifying a Docyrus-backed React app
• Setting up authentication with @docyrus/signin
• Bootstrapping tenant-aware runtime utilities with @docyrus/app-utils
• Fetching or mutating data with generated collections or @docyrus/api-client
• Persisting app-level config or user-level config or saved grid views with AppConfig, UserAppConfig, and DataViews
• Building record sharing, role management, or ACL-driven UI flows
• Designing feature UIs such as dashboards, forms, tables, layouts, dialogs, analytics, or detail pages
• Selecting between shadcn, diceui, animate-ui, docyrus-ui, and reui components
• Implementing complete feature flows that combine data access and polished UI

End-to-End Feature Workflow

1. Set up app auth, routing, and query providers. 2. Bootstrap TenantPreferences, date/number utilities, and shared app runtime helpers from @docyrus/app-utils. 3. Use generated Docyrus collection hooks or the REST client for data access. 4. Define columns, filters, formulas, child queries, and mutations correctly. 5. Use AppConfig for per-app persisted settings, UserAppConfig for per-user per-app settings, and DataViews for saved grid views. 6. Check preferred UI components before building anything custom. 7. Use Docyrus form and detail patterns for create, edit, item detail, and editable grid flows. 8. Connect UI actions to TanStack Query mutations and invalidate relevant queries.

Quick Start: App Bootstrap

Root provider setup

import { DocyrusAuthProvider } from '@docyrus/signin'

<DocyrusAuthProvider
  apiUrl={import.meta.env.VITE_API_BASE_URL}
  clientId={import.meta.env.VITE_OAUTH2_CLIENT_ID}
  redirectUri={import.meta.env.VITE_OAUTH2_REDIRECT_URI}
  scopes={['offline_access', 'Read.All', 'DS.ReadWrite.All', 'Users.Read']}
  callbackPath="/auth/callback"
>
  <QueryClientProvider client={queryClient}>
    <RouterProvider router={router} />
  </QueryClientProvider>
</DocyrusAuthProvider>

Auth gate and current-user access

const { status, user, hasRole, hasPermission } = useDocyrusAuth()

if (status === 'loading') return <Spinner />
if (status === 'unauthenticated') return <SignInButton />

// user is auto-fetched from /v1/users/me after authentication
// hasRole('super_admin') — check role by slug or uid
// hasPermission('edit', dataSourceId) — check ACL permission on a data source

Tenant-aware app utilities

Use @docyrus/app-utils as the default runtime layer for tenant-level formatting and persisted app/grid preferences.

import {
  createAppConfigClient,
  createUserAppConfigClient,
  createDataViewClient,
  createDateUtils,
  createNumberUtils,
  getTenantPreferences,
} from '@docyrus/app-utils'

function useAppRuntime(appId: string) {
  const client = useDocyrusClient()
  const { getMyInfo } = useUsersCollection()

  return useQuery({
    queryKey: ['app-runtime', appId],
    enabled: !!client && !!appId,
    queryFn: async () => {
      const [preferences, me] = await Promise.all([
        getTenantPreferences(client!),
        getMyInfo(),
      ])

      return {
        preferences,
        me,
        dateUtils: createDateUtils({
          preferences,
          userTimezone: me.timeZone?.id,
        }),
        numberUtils: createNumberUtils({ preferences }),
        appConfig: createAppConfigClient(client!, appId),
        userConfig: createUserAppConfigClient(client!, appId),
        dataViews: createDataViewClient(client!, appId),
      }
    },
  })
}

Use this runtime to:

• Format dates and datetimes with tenant format strings and the user's timezone.
• Format numbers, currency-like values, and decimals using tenant separators and precision.
• Read and upsert the app's single persisted AppConfig document.
• Read and upsert the current user's UserAppConfig document (per-user per-app settings).
• Read and persist saved grid views through DataViews.

Data fetching with generated collections

const { list } = useBaseProjectCollection()

const { data: projects } = useQuery({
  queryKey: ['projects'],
  queryFn: () =>
    list({
      columns: ['name', 'status', 'record_owner(firstname,lastname)'],
      filters: { rules: [{ field: 'status', operator: '!=', value: 'archived' }] },
      orderBy: 'created_on DESC',
      limit: 50,
    }),
})

ACL, roles, and record sharing

Use direct useDocyrusClient() calls for ACL features. These routes may be hidden from generated OpenAPI output, so they are typically not available through generated collection hooks.

const client = useDocyrusClient()

const { data: roles } = useQuery({
  queryKey: ['acl', 'roles'],
  queryFn: () => client!.get('/v1/users/acl/roles'),
})

const replaceUserRoles = useMutation({
  mutationFn: ({ userId, roleIds }: { userId: string; roleIds: string[] }) =>
    client!.put(`/v1/users/acl/users/${userId}/roles`, { roleIds }),
})

const createRoleQuery = useMutation({
  mutationFn: (payload: Record<string, unknown>) =>
    client!.post('/v1/users/acl/role-queries', payload),
})

Prefer role uid values returned by the API when sending roleIds for user-role updates or role-query payloads.

Saved data grid views

Use DataGridViewSelect as the default saved-view UI for Docyrus grids, and persist those views with createDataViewClient(client, appId).

• DataGridViewSelect is the default component for showing and editing saved grid views.
• Pass the TanStack table instance via table so the selector/editor can read column definitions.
• Pass fields when you want the built-in filter builder enabled in the editor.
• Back views, onViewCreate, onViewSave, onViewDelete, onViewHide, and onViewUnhide with DataViews CRUD.
• Use DataGridViewEditor separately only when you need a standalone editor outside the selector.

Critical App/Data Rules

1. Always send `columns` in .list() and .get() calls. Without it, only id is returned. 2. Collections are React hooks — call useBaseProjectCollection(), useUsersCollection(), and similar hooks inside React components. 3. Data source endpoints are dynamic — they only exist if the data source is defined in the tenant OpenAPI spec. 4. Use `id` for `count` calculations. Use actual field slugs for sum, avg, min, and max. 5. Child query keys must appear in `columns`. 6. Formula keys must appear in `columns`. 7. Use `useUsersCollection().getMyInfo()` for current user profile instead of making a direct profile call. 8. Initialize `TenantPreferences` once per app runtime and create shared dateUtils / numberUtils instances from @docyrus/app-utils. 9. Formatting functions from `@docyrus/app-utils` are regionalized — do not hardcode locale, date format, decimal separator, thousand separator, or decimal precision when tenant preferences should drive them. 10. Use `createAppConfigClient(client, appId)` for the app's single persisted config document; upsert is the default write path. 11. Use `createUserAppConfigClient(client, appId)` for the current user's persisted config document scoped to an app (e.g. theme, layout preferences, sidebar state); upsert is the default write path. 12. Use `createDataViewClient(client, appId)` for saved grid-view CRUD. 13. Use `DataViews` with `DataGridViewSelect` to show, create, edit, reorder, hide, unhide, soft-delete, and hard-delete saved data grid views. 14. `DataGridViewSelect` needs a TanStack table instance and should receive fields when you want the built-in filter builder/editor experience. 15. Data view creation requires `name` and `tenant_data_source_id`. 16. Use `dataViews.update(viewId, { archived: true })` for soft-delete and dataViews.remove(viewId) only for irreversible hard-delete. 17. Regenerate collections after schema changes by rebuilding the tenant OpenAPI spec, downloading the latest openapi.json, and re-running the collection generator. 18. ACL endpoints are usually raw-client integrations — use useDocyrusClient() or RestApiClient for roles, user-role assignments, role queries, record sharing, and ownership transfer. 19. Prefer role `uid` values for ACL role writes, user-role roleIds, and role-query roleIds. 20. Treat `PUT /v1/users/acl/users/:userId/roles` as full replacement and POST /v1/users/acl/users/:userId/roles as additive. 21. Send role-query `query` as raw JSON and omit tenantAppId when dataSourceId is present; backend derives it. 22. After deleting a role, invalidate dependent app queries for role lists, user-role lists, role-query lists, and any UI that renders primary-role labels.

Critical UI/UX Rules

1. Always check preferred components first before creating anything custom. 2. Use `AwesomeCard` for dashboards unless the user explicitly wants a different card style. 3. Use animate-ui `Sidebar` for app layouts unless another layout is requested. 4. Prefer Recharts for charts. shadcn chart primitives are the default wrapper. 5. Use icons in this order: hugeicons, then fontawesome light, then lucide. 6. Use `AwesomeDialog` for item create forms.

• Small/simple forms: container="sheet" with side="right"
• Long/complex forms: container="modal" or container="drawer"

7. Choose detail containers based on item complexity.

• Large items: dedicated page
• Small items: AwesomeDialog right sheet

8. All forms must use TanStack Form + the Docyrus form system. Do not build feature forms with plain HTML forms or React Hook Form directly. 9. Use `EditableRecordDetail` for inline editing in item detail views. 10. Always enable `trackChanges` for editable detail and grid experiences. 11. Use `DataGridViewSelect` for saved grid views and back it with DataViews from @docyrus/app-utils. 12. Prefer `DataGridViewEditor` only when you need a standalone grid-view editor outside the selector component.

Default UI Choices

Quick UI Patterns

Item create form

<AwesomeDialog open={open} onOpenChange={setOpen} container="sheet" side="right" size="default">
  <AwesomeDialogHeader title="Create Task" icon="far-plus" />
  <AwesomeDialogBody>
    <form.Field name="title">{(field) => <TextFormField field={field} label="Title" />}</form.Field>
    <form.Field name="status">{(field) => <SelectFormField field={field} label="Status" />}</form.Field>
  </AwesomeDialogBody>
  <AwesomeDialogFooter>
    <Button variant="outline" onClick={() => setOpen(false)}>Cancel</Button>
    <Button onClick={handleSubmit}>Create</Button>
  </AwesomeDialogFooter>
</AwesomeDialog>

Item detail with inline editing

<AwesomeDialog open={open} onOpenChange={setOpen} container="sheet" side="right" size="lg" fullscreenable>
  <AwesomeDialogHeader
    title="Task Detail"
    description="Review and edit task fields inline"
    headerButtons={<Button variant="outline" size="sm" onClick={switchToFullForm}>Edit All</Button>}
  />
  <AwesomeDialogBody>
    <EditableRecordDetail fields={fields} record={record} onSave={handleSave} trackChanges>
      <EditableRecordDetailField slug="title" />
      <EditableRecordDetailField slug="status" />
      <EditableRecordDetailField slug="assignee" />
      <EditableRecordDetailField slug="due_date" />
    </EditableRecordDetail>
  </AwesomeDialogBody>
</AwesomeDialog>

TanStack Query Pattern

function useProjects(params?: ICollectionListParams) {
  const { list } = useBaseProjectCollection()
  return useQuery({
    queryKey: ['projects', 'list', params],
    queryFn: () => list({ columns: PROJECT_COLUMNS, ...params }),
  })
}

function useCreateProject() {
  const { create } = useBaseProjectCollection()
  const qc = useQueryClient()
  return useMutation({
    mutationFn: (data: Record<string, unknown>) => create(data),
    onSuccess: () => {
      void qc.invalidateQueries({ queryKey: ['projects'] })
    },
  })
}

Collection CRUD Methods

const { list, get, create, update, delete: deleteOne, deleteMany } = useBaseProjectCollection()

list(params?: ICollectionListParams)
get(id, { columns })
create(data)
update(id, data)
deleteOne(id)
deleteMany({ recordIds })

API endpoint pattern: /v1/apps/{appSlug}/data-sources/{slug}/items

Query Capabilities Summary

The .list() method supports:

• columns
• filters
• filterKeyword
• orderBy
• limit and offset
• fullCount
• calculations
• formulas
• childQueries
• pivot
• expand

Component Installation Pattern

pnpm dlx shadcn@latest add button
pnpm dlx shadcn@latest add @diceui/data-table
pnpm dlx shadcn@latest add @animate-ui/sidebar
pnpm dlx @docyrus/cli add @docyrus/ui-awesome-card
pnpm dlx shadcn@latest add @reui/file-upload-default

References

For deep dives, read:

• references/README.md — merged reference map for app development and UI design
• references/api-client-and-auth.md
• references/collections-and-patterns.md
• the docyrus-acl-design skill — ACL roles, permissions, and role-queries (docyrus acl); plus the ACL REST endpoints in docyrus-api-dev's SKILL.md
• ../docyrus-api-dev/references/data-source-query-guide.md
• ../docyrus-api-dev/references/formula-design-guide-llm.md
• ../docyrus-api-dev/references/query-guide.md
• references/preferred-components-catalog.md
• references/component-selection-guide.md
• references/icon-usage-guide.md

@docyrus/api-client & @docyrus/signin Reference

Table of Contents

1. RestApiClient 2. Authentication with @docyrus/signin 3. Authorization (Roles & Permissions) 4. API Client Access Pattern 5. Interceptors 6. Error Handling 7. Advanced Features

---

RestApiClient

Type-safe REST API client from @docyrus/api-client.

HTTP Methods

import { RestApiClient } from '@docyrus/api-client'

client.get<T>(endpoint, params?)    // GET
client.post<T>(endpoint, data)      // POST
client.patch<T>(endpoint, data)     // PATCH
client.put(endpoint, data)          // PUT
client.delete(endpoint, data?)      // DELETE

Typed Responses

interface User { id: string; name: string; email: string }
const response = await client.get<User[]>('/v1/users')

Config Options

interface ApiClientConfig {
  baseURL?: string
  tokenManager?: TokenManager
  headers?: Record<string, string>
  timeout?: number
  fetch?: typeof fetch
  FormData?: typeof FormData
  AbortController?: typeof AbortController
  storage?: Storage
}

---

Authentication with @docyrus/signin

Package: @docyrus/signin (peer dep: @docyrus/api-client >= 0.0.10, react >= 18)

DocyrusAuthProvider Setup

Wrap application root:

import { DocyrusAuthProvider } from '@docyrus/signin'

<DocyrusAuthProvider
  apiUrl={import.meta.env.VITE_API_BASE_URL}
  clientId={import.meta.env.VITE_OAUTH2_CLIENT_ID}
  redirectUri={import.meta.env.VITE_OAUTH2_REDIRECT_URI}
  scopes={['offline_access', 'Read.All', 'DS.ReadWrite.All', 'Users.Read']}
  callbackPath="/auth/callback"
>
  <App />
</DocyrusAuthProvider>

Provider Props

Auth Modes

• Standalone: OAuth2 Authorization Code + PKCE via page redirect. Tokens stored in localStorage, auto-refreshed.
• Iframe: Receives tokens via window.postMessage from *.docyrus.app hosts. Requests refresh from host when expired.

useDocyrusAuth() Hook

const {
  status,        // 'loading' | 'authenticated' | 'unauthenticated'
  mode,          // 'standalone' | 'iframe'
  client,        // RestApiClient | null
  tokens,        // { accessToken, refreshToken, ... } | null
  user,          // DocyrusUser | null — auto-fetched from /v1/users/me
  signIn,        // () => void — redirects to Docyrus login
  signOut,       // () => void — logout and clear tokens
  hasRole,       // (role: string | string[]) => boolean — check role by slug or uid
  hasPermission, // (operation: string, dataSourceId?: string) => boolean — check ACL permission
  refreshUser,   // () => Promise<void> — re-fetch user from API
  error,         // Error | null
} = useDocyrusAuth()

useDocyrusClient() Hook

const client = useDocyrusClient() // RestApiClient | null

SignInButton Component

// Basic
<SignInButton />

// Styled
<SignInButton className="btn" label="Log in with Docyrus" />

// Render prop
<SignInButton>
  {({ signIn, isLoading }) => (
    <button onClick={signIn} disabled={isLoading}>
      {isLoading ? 'Redirecting...' : 'Sign in'}
    </button>
  )}
</SignInButton>

Environment Variables (.env)

VITE_API_BASE_URL=https://localhost:3366
VITE_OAUTH2_CLIENT_ID=your-client-id
VITE_OAUTH2_REDIRECT_URI=http://localhost:3000/auth/callback
VITE_OAUTH2_SCOPES=openid profile offline_access Users.Read DS.ReadWrite.All

---

Authorization (Roles & Permissions)

The provider auto-fetches the current user from /v1/users/me after authentication. The user, hasRole, and hasPermission are available on the useDocyrusAuth() hook.

Role-Based UI Gating

function Dashboard({ dataSourceId }: { dataSourceId: string }) {
  const { user, hasRole, hasPermission } = useDocyrusAuth()

  if (!user) return <Spinner />

  const canEdit = hasPermission('edit', dataSourceId)
  const canDelete = hasPermission('delete', dataSourceId)
  const isAdmin = hasRole('super_admin')

  return (
    <div>
      {canEdit && <Button>Edit</Button>}
      {canDelete && <Button variant="destructive">Delete</Button>}
      {isAdmin && <AdminPanel />}
    </div>
  )
}

Permission Resolution Order

1. super_admin role → always granted 2. global_editor role → granted for: view, create, edit, delete, create_bulk, export, import, print 3. global_viewer role → granted only for: view 4. Always-permitted system data sources (reports, todos, notes, etc.) 5. User's aclRules array (merged from all roles by the server)

Pure Functions (No React)

import { hasRole, hasPermission } from '@docyrus/signin/core'
import type { DocyrusUser } from '@docyrus/signin/core'

hasRole(user, 'super_admin')
hasPermission(user, 'edit', 'some-ds-id')

---

API Client Access Pattern

Generated collections are React hooks that use useDocyrusClient() internally to get the authenticated RestApiClient from DocyrusAuthProvider. No manual client syncing is needed.

// Collections get the client automatically via useDocyrusClient()
function useBaseProjectCollection() {
  const client = useDocyrusClient()
  return {
    list: (params?) => client!.get('/v1/apps/base/data-sources/project/items', params),
    // ... other CRUD methods
  }
}

// In your component — just call the collection hook
function ProjectList() {
  const { list } = useBaseProjectCollection()
  const { data } = useQuery({
    queryKey: ['projects'],
    queryFn: () => list({ columns: ['name', 'status'] }),
  })
}

For direct API access outside collections, use the useDocyrusClient() hook:

const client = useDocyrusClient()
const data = await client!.get<MyType>('/v1/custom-endpoint')

---

Interceptors

Add request/response interceptors via client.use():

client.use({
  request: (config) => {
    // Transform columns array to comma-separated string
    if (config.params?.columns && Array.isArray(config.params.columns)) {
      config.params.columns = config.params.columns.join(',')
    }
    return config
  },
  response: (response) => {
    // Unwrap nested .data property
    if (response.data?.data && !Array.isArray(response.data)) {
      response.data = response.data.data
    }
    return response
  },
  error: (error, request, response) => {
    if (error.status === 401) { /* handle auth error */ }
    return { error, request, response }
  },
})

---

Error Handling

import {
  ApiError, NetworkError, TimeoutError,
  AuthenticationError, AuthorizationError,
  NotFoundError, RateLimitError, ValidationError,
  OAuth2Error, InvalidGrantError,
} from '@docyrus/api-client'

try {
  await client.get('/resource')
} catch (error) {
  if (error instanceof AuthenticationError) { /* 401 */ }
  else if (error instanceof AuthorizationError) { /* 403 */ }
  else if (error instanceof NotFoundError) { /* 404 */ }
  else if (error instanceof RateLimitError) { /* 429 - error.retryAfter */ }
  else if (error instanceof NetworkError) { /* network issue */ }
  else if (error instanceof TimeoutError) { /* timeout */ }
}

---

Advanced Features

SSE (Server-Sent Events)

const eventSource = client.sse('/events', {
  onMessage(data) { console.log(data) },
  onError(error) { console.error(error) },
  onComplete() { console.log('done') },
})
eventSource.close()

File Upload

const formData = new FormData()
formData.append('file', fileInput.files[0])
await client.post('/upload', formData)

File Download

const response = await client.get('/download/file.pdf', { responseType: 'blob' })
const url = URL.createObjectURL(response.data)

HTML to PDF

await client.html2pdf({
  html: '<html><body>Content</body></html>',
  options: { format: 'A4', margin: { top: 10, bottom: 10 } },
})

Retry Logic

import { withRetry } from '@docyrus/api-client'
const response = await withRetry(() => client.get('/endpoint'), {
  retries: 3, retryDelay: 1000,
  retryCondition: (error) => error.status >= 500,
})

Collections & App Patterns Reference

Table of Contents

1. Collection Architecture 2. Generated Collection Structure 3. Collection Types 4. useUsersCollection 5. TanStack Query Hooks Pattern 6. Query Key Factory Pattern 7. Mutation Pattern 8. App Bootstrap Flow 9. Routing Setup 10. API Endpoints

---

Collection Architecture

Collections are auto-generated from openapi.json using @docyrus/tanstack-db-generator. They provide type-safe CRUD operations for each data source.

Generate command: pnpm generate-orm (runs @docyrus/tanstack-db-generator openapi.json)

Key files:

• src/collections/<app>-<entity>.collection.ts — generated React hooks with CRUD methods + entity types
• src/collections/types.ts — shared query types (filters, calculations, formulas, etc.)
• src/collections/users.collection.ts — special system users collection hook

---

Generated Collection Structure

Each collection exports an entity interface and a React hook that returns CRUD methods:

// Generated collection for base/project
import { useDocyrusClient } from '@docyrus/signin'
import type { ICollectionListParams } from './types'

export interface BaseProjectEntity {
  id?: string
  record_owner?: string
  created_on?: string
  created_by?: string
  last_modified_on?: string
  last_modified_by?: string
  name: string
  description?: Record<string, any>
  status?: { id: string; name: string } | any
  organization?: { id: string; name: string } | string
}

export function useBaseProjectCollection() {
  const client = useDocyrusClient()

  return {
    list: (params?: ICollectionListParams): Promise<Array<BaseProjectEntity>> =>
      client!.get('/v1/apps/base/data-sources/project/items', params as any),

    get: (recordId: string, params?: { columns?: Array<string> }): Promise<BaseProjectEntity> =>
      client!.get(`/v1/apps/base/data-sources/project/items/${recordId}`, params),

    create: (data: Record<string, any>): Promise<BaseProjectEntity> =>
      client!.post('/v1/apps/base/data-sources/project/items', data),

    update: (recordId: string, data: Record<string, any>): Promise<BaseProjectEntity> =>
      client!.patch(`/v1/apps/base/data-sources/project/items/${recordId}`, data),

    delete: (recordId: string): Promise<void> =>
      client!.delete(`/v1/apps/base/data-sources/project/items/${recordId}`),

    deleteMany: (data: { recordIds: Array<string> }): Promise<void> =>
      client!.delete('/v1/apps/base/data-sources/project/items', data),
  }
}

Collections are hooks because they use useDocyrusClient() internally, which provides the authenticated RestApiClient from DocyrusAuthProvider. This means collections must be called inside React components.

Default Fields (always present)

Every data source entity includes: id, record_owner, created_on, created_by, last_modified_on, last_modified_by, name

---

Collection Types

Shared query parameter types in src/collections/types.ts:

• ICollectionListParams — full query payload with columns, filters, calculations, formulas, childQueries, pivot, orderBy, limit, offset, fullCount, expand
• ICollectionFilterRule — single filter rule
• ICollectionFilterGroup — nested filter group
• ICollectionCalculation — aggregation rule
• ICollectionFormula — simple formula
• ICollectionBlockFormula — block/subquery formula
• ICollectionChildQuery — child query definition
• ICollectionPivot / ICollectionPivotMatrix — pivot configuration
• ICollectionOrderBy — sort specification

---

useUsersCollection

System users collection hook with special methods:

export function useUsersCollection() {
  const client = useDocyrusClient()

  return {
    getUsers: (): Promise<Array<UserEntity>> =>
      client!.get('/v1/users'),

    getMyInfo: (): Promise<UserEntity> =>
      client!.get('/v1/users/me'),

    createUser: (data: UserCreateParams): Promise<UserEntity> =>
      client!.post('/v1/users', data),

    updateMe: (data: UserUpdateParams): Promise<UserEntity> =>
      client!.patch('/v1/users/me', data),

    updateUser: (userId: string, data: UserUpdateParams): Promise<UserEntity> =>
      client!.patch(`/v1/users/${userId}`, data),

    changeUserStatus: (userId: string, status: number) =>
      client!.put(`/v1/users/${userId}/status/${status}`),

    saveUserDevice: (data: UserDeviceDto) =>
      client!.post('/v1/users/device', data),

    getMyTenants: () =>
      client!.get('/v1/users/me/tenants'),
  }
}

Use useUsersCollection().getMyInfo() for current user profile.

---

TanStack Query Hooks Pattern

Wrap collection hook methods in TanStack Query hooks. Since collections are themselves hooks, call them inside the component/hook, then pass the returned methods to TanStack Query:

import { useQuery } from '@tanstack/react-query'
import { useBaseProjectCollection } from '@/collections/base-project.collection'
import { queryKeys } from '@/lib/query-keys'

const PROJECT_COLUMNS = ['name', 'status', 'description', 'record_owner(id,firstname,lastname)']

export function useProjects(params?: ICollectionListParams) {
  const { list } = useBaseProjectCollection()
  return useQuery({
    queryKey: queryKeys.projects.list(params ?? {}),
    queryFn: () =>
      list({
        columns: PROJECT_COLUMNS,  // ALWAYS specify columns
        ...params,
      }),
  })
}

export function useProject(projectId: string) {
  const { get } = useBaseProjectCollection()
  return useQuery({
    queryKey: queryKeys.projects.detail(projectId),
    queryFn: () =>
      get(projectId, {
        columns: PROJECT_COLUMNS,
      }),
    enabled: !!projectId,
  })
}

---

Query Key Factory Pattern

export const queryKeys = {
  projects: {
    all: ['projects'] as const,
    lists: () => [...queryKeys.projects.all, 'list'] as const,
    list: (params: object) => [...queryKeys.projects.lists(), params] as const,
    detail: (id: string) => [...queryKeys.projects.all, 'detail', id] as const,
  },
  tasks: {
    all: ['tasks'] as const,
    lists: () => [...queryKeys.tasks.all, 'list'] as const,
    list: (params: object) => [...queryKeys.tasks.lists(), params] as const,
    detail: (id: string) => [...queryKeys.tasks.all, 'detail', id] as const,
  },
}

---

Mutation Pattern

import { useMutation, useQueryClient } from '@tanstack/react-query'
import { useBaseProjectCollection } from '@/collections/base-project.collection'

export function useCreateProject() {
  const { create } = useBaseProjectCollection()
  const queryClient = useQueryClient()
  return useMutation({
    mutationFn: (data: Record<string, unknown>) => create(data),
    onSuccess: () => {
      void queryClient.invalidateQueries({
        queryKey: queryKeys.projects.all,
      })
    },
  })
}

export function useUpdateProject() {
  const { update } = useBaseProjectCollection()
  const queryClient = useQueryClient()
  return useMutation({
    mutationFn: ({ id, data }: { id: string; data: Record<string, unknown> }) =>
      update(id, data),
    onSuccess: (_data, { id }) => {
      void queryClient.invalidateQueries({ queryKey: queryKeys.projects.detail(id) })
      void queryClient.invalidateQueries({ queryKey: queryKeys.projects.lists() })
    },
  })
}

export function useDeleteProject() {
  const { delete: deleteProject } = useBaseProjectCollection()
  const queryClient = useQueryClient()
  return useMutation({
    mutationFn: (id: string) => deleteProject(id),
    onSuccess: () => {
      void queryClient.invalidateQueries({ queryKey: queryKeys.projects.all })
    },
  })
}

---

App Bootstrap Flow

1. main.tsx: Mount DocyrusAuthProvider → QueryClientProvider → RouterProvider 2. App.tsx: Check useDocyrusAuth() status — user is auto-fetched from /v1/users/me 3. Use hasRole() / hasPermission() from useDocyrusAuth() for authorization checks 4. Use collection hooks (e.g., useUsersCollection()) for data access — they get the authenticated client via useDocyrusClient() internally 5. Render protected routes

// App.tsx
function App() {
  const { status, user, hasRole, hasPermission } = useDocyrusAuth()

  if (status === 'loading') return <LoadingSpinner />
  if (status === 'unauthenticated') return <LoginPage />

  // user auto-fetched, hasRole/hasPermission ready
  return <AppLayout />
}

---

Routing Setup

TanStack Router with code-based routes:

import { createRouter, createRoute, createRootRoute } from '@tanstack/react-router'

const rootRoute = createRootRoute({ component: () => <Outlet /> })

const layoutRoute = createRoute({
  getParentRoute: () => rootRoute,
  id: 'layout',
  component: AppLayout,
})

const indexRoute = createRoute({
  getParentRoute: () => layoutRoute,
  path: '/',
  component: DashboardPage,
})

const projectsRoute = createRoute({
  getParentRoute: () => layoutRoute,
  path: '/projects',
  component: ProjectsPage,
})

const projectDetailRoute = createRoute({
  getParentRoute: () => layoutRoute,
  path: '/projects/$projectId',
  component: ProjectDetailPage,
})

// Auth routes (public)
const authCallbackRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: '/auth/callback',
  component: () => <div>Processing login...</div>,
})

const routeTree = rootRoute.addChildren([
  layoutRoute.addChildren([indexRoute, projectsRoute, projectDetailRoute]),
  authCallbackRoute,
])

const router = createRouter({
  routeTree,
  defaultPreload: 'intent',
  scrollRestoration: true,
})

---

API Endpoints

Data Source Items (Dynamic)

GET    /v1/apps/{appSlug}/data-sources/{slug}/items          — List (with query payload)
GET    /v1/apps/{appSlug}/data-sources/{slug}/items/{id}     — Get one
POST   /v1/apps/{appSlug}/data-sources/{slug}/items          — Create
PATCH  /v1/apps/{appSlug}/data-sources/{slug}/items/{id}     — Update
DELETE /v1/apps/{appSlug}/data-sources/{slug}/items/{id}     — Delete one
DELETE /v1/apps/{appSlug}/data-sources/{slug}/items          — Delete many

Endpoints are dynamic — they exist only if a data source is defined in the tenant. The openapi.json spec enumerates all available data sources.

System Endpoints (Always Available)

GET    /v1/users                    — List users
POST   /v1/users                    — Create user
GET    /v1/users/me                 — Current user profile
PATCH  /v1/users/me                 — Update current user
PATCH  /v1/users/{userId}           — Update user
PUT    /v1/users/{userId}/status/{s} — Change user status
POST   /v1/users/device             — Save push notification device

Other Standard Endpoints

GET  /v1/api/openapi.json           — Generate OpenAPI spec
HEAD /v1/oauth2                     — Check rate limits
PUT  reports/runCustomQuery/{id}    — Run custom query/report

Component Selection Guide

Decision trees and best practices for choosing the right component for each use case.

Table of Contents

1. UX Design Patterns 2. Selection Process 3. Common Use Case Decision Trees 4. Library-Specific Strengths 5. Default Choices 6. When to Use Each Library

---

UX Design Patterns

These patterns are mandatory and must be followed in all Docyrus applications.

Pattern 1: Item Create Forms → AwesomeDialog

All item creation and editing forms use the AwesomeDialog system. Choose the container type based on form complexity:

Form complexity → Container choice:

Small/simple form (3-6 fields)     → container="sheet" side="right"
Long/complex form (7+ fields)      → container="modal" size="lg"
Mobile-first form                  → container="drawer" side="bottom"

AwesomeDialog props reference:

• container: 'modal' | 'sheet' | 'drawer' — determines the dialog presentation
• side: 'left' | 'right' | 'top' | 'bottom' — positioning for sheet/drawer
• size: 'sm' | 'default' | 'lg' | 'xl' | 'full' — size preset
• pattern: boolean — show decorative pattern background (default: true)
• patternStyle: 'stripes' | 'dots' | 'grid' | 'crosshatch' | 'zigzag'
• fullscreenable: boolean — allow fullscreen toggle
• minimizable: boolean — allow minimize (requires GlobalDialogProvider)
• resizable: boolean — allow resize handles
• dialogId: string — unique ID for global dialog tracking

Sub-components: AwesomeDialogHeader, AwesomeDialogBody, AwesomeDialogFooter, AwesomeDialogToolbar

Example — Small create form (task):

<AwesomeDialog open={open} onOpenChange={setOpen} container="sheet" side="right">
  <AwesomeDialogHeader title="Create Task" icon="far-plus" />
  <AwesomeDialogBody>{/* TanStack Form fields */}</AwesomeDialogBody>
  <AwesomeDialogFooter>
    <Button variant="outline" onClick={() => setOpen(false)}>Cancel</Button>
    <Button onClick={handleSubmit}>Create</Button>
  </AwesomeDialogFooter>
</AwesomeDialog>

Example — Large create form (project):

<AwesomeDialog open={open} onOpenChange={setOpen} container="modal" size="lg" fullscreenable>
  <AwesomeDialogHeader title="Create Project" icon="far-folder-plus" />
  <AwesomeDialogBody>{/* Many form fields — body scrolls */}</AwesomeDialogBody>
  <AwesomeDialogFooter>
    <Button variant="outline" onClick={() => setOpen(false)}>Cancel</Button>
    <Button onClick={handleSubmit}>Create Project</Button>
  </AwesomeDialogFooter>
</AwesomeDialog>

Pattern 2: Item Detail Pages → New Page vs AwesomeDialog

Choose the right container based on item complexity:

Item complexity → Detail view choice:

Large items (projects, workspaces, reports)  → Dedicated new page (full route)
Small items (tasks, contacts, comments)      → AwesomeDialog with container="sheet" side="right"

Decision tree:

Does the item have:
  - Multiple tabs/sections?
  - Sub-items or child lists?
  - Complex layout with sidebar?
  → YES: Create a dedicated page route

  - Simple field list?
  - Quick view/edit pattern?
  - Opened from a list or table?
  → YES: Use AwesomeDialog right drawer

Example — Task detail in AwesomeDialog:

<AwesomeDialog open={open} onOpenChange={setOpen} container="sheet" side="right" size="lg" fullscreenable>
  <AwesomeDialogHeader
    title={task.title}
    description={`${task.status} · ${task.assignee}`}
    headerButtons={
      <Button variant="outline" size="sm" onClick={switchToFullForm}>Edit All</Button>
    }
  />
  <AwesomeDialogBody>
    <EditableRecordDetail fields={fields} record={record} onSave={handleSave}>
      <EditableRecordDetailField slug="title" />
      <EditableRecordDetailField slug="status" />
      <EditableRecordDetailField slug="assignee" />
      <EditableRecordDetailField slug="due_date" />
    </EditableRecordDetail>
  </AwesomeDialogBody>
</AwesomeDialog>

Pattern 3: Form System → TanStack Form + Docyrus Form Fields

All forms must use TanStack Form with the Docyrus form field system. Never use plain HTML forms or React Hook Form directly.

Key components:

• DynamicFormField — Auto-dispatches to the correct field type based on IField.type
• 47+ field types: text, number, email, url, phone, date, dateTime, time, select, multiSelect, status, relation, file, image, code, docEditor, and more
• Each field type has a dedicated *FormField component (e.g., TextFormField, SelectFormField, DateFormField)

Form field pattern:

import { useForm } from '@tanstack/react-form'
import { TextFormField, SelectFormField, DateFormField } from '@docyrus/ui/components/form-fields'

const form = useForm({ defaultValues: { title: '', status: '', dueDate: '' } })

<form.Field name="title">
  {(field) => <TextFormField field={field} label="Title" />}
</form.Field>
<form.Field name="status">
  {(field) => <SelectFormField field={field} label="Status" options={statusOptions} />}
</form.Field>

Pattern 4: Inline Editing → EditableRecordDetail

Use EditableRecordDetail for detail views where users can edit individual fields inline without opening a full form page. Always enable `trackChanges` to highlight changed fields and show a floating ActionBar. Always include an "Edit All" button in the header to switch to a full form editing experience.

Key components:

• EditableRecordDetail — Provider/wrapper that manages field state, change tracking, and save/cancel
• EditableRecordDetailField — Individual field that reads config from context, renders label + inline-editable value
• EditableValue — Lower-level single-field inline editor (used internally by EditableRecordDetailField)
• useEditableRecordDetail() — Hook to access form, values, changes, and save/cancel from within the provider

How it works (with `trackChanges` enabled): 1. Fields render as read-only DynamicValue display 2. Click a field → switches to DynamicFormField editor inline 3. Changed fields get highlighted with amber background 4. Floating ActionBar appears showing "N fields changed" with Save/Cancel buttons 5. Save commits only changed fields; Cancel reverts all changes

Important: Always pass trackChanges prop when using EditableRecordDetail or DataGrid with cell editing. Without it, users have no visual feedback about which fields they've modified and no centralized Save/Cancel flow.

Field change tracking types:

interface RecordDetailField {
  field: IField           // Field configuration (name, slug, type)
  enumOptions?: EnumOption[] // Options for select-based fields
  readOnly?: boolean      // Per-field read-only override
  appSlug?: string        // For dynamic enum loading
  dataSourceSlug?: string // For dynamic enum loading
}

interface FieldChange {
  fieldSlug: string
  fieldName: string
  originalValue: unknown
  newValue: unknown
}

Example — Detail view with inline editing and "Edit All" button:

<AwesomeDialogHeader
  title="Task Detail"
  headerButtons={<Button variant="outline" size="sm" onClick={switchToFullForm}>Edit All</Button>}
/>
<AwesomeDialogBody>
  <EditableRecordDetail fields={fields} record={record} onSave={handleSave} onCancel={handleCancel} trackChanges>
    <div className="space-y-3">
      <h4 className="border-b pb-1.5 text-xs font-semibold uppercase tracking-wider text-muted-foreground">
        General Info
      </h4>
      <EditableRecordDetailField slug="title" />
      <EditableRecordDetailField slug="status" />
      <EditableRecordDetailField slug="priority" />
      <EditableRecordDetailField slug="assignee" />
      <EditableRecordDetailField slug="due_date" />
    </div>
  </EditableRecordDetail>
</AwesomeDialogBody>

---

Selection Process

Follow this process when selecting a component:

1. Check if there's a default preference for the use case
   ↓
2. If no default, search for matching components by:
   - Name match (exact or similar)
   - Functionality match
   - Category match (form, data, navigation, etc.)
   ↓
3. If multiple matches found, apply library priority:
   - docyrus (if Docyrus-specific data handling needed)
   - shadcn (for basic/common components)
   - diceui (for advanced/specialized features)
   - animate-ui (when animation/transitions are important)
   - reui (for specific utility needs)
   ↓
4. Verify the component meets requirements by checking docs
   ↓
5. Install and implement

---

Common Use Case Decision Trees

Dashboard & Data Visualization

Navigation & Layout

Data Display & Tables

When using Data Grid View Select, back its views, onViewCreate, onViewSave, onViewDelete, onViewHide, and onViewUnhide flows with createDataViewClient(client, appId) from @docyrus/app-utils. Always pass the TanStack table instance, and pass fields when you want the editor's built-in filter builder enabled.

Forms & Inputs

Always use TanStack Form + Docyrus form fields. The DynamicFormField component auto-dispatches to the correct field type.

Dialogs & Overlays

Specialized Components

---

Library-Specific Strengths

shadcn (43 components)

Best for: Core UI primitives, forms, basic layout

Strengths:

• Well-tested, accessible components
• Great documentation
• Broad browser support
• Foundation for other libraries

Use when: You need a standard, reliable component without special features

diceui (42 components)

Best for: Advanced interactions, specialized data components

Strengths:

• Rich feature sets (filtering, sorting, virtualization)
• Advanced input types (phone, color, mask)
• Drag-drop capabilities
• Data visualization components

Use when: You need advanced functionality beyond basic components

animate-ui (21 components)

Best for: Animated transitions, polished UX

Strengths:

• Smooth, professional animations
• Enhanced visual feedback
• Composable animated patterns

Use when: Animation/transitions are important to the UX

docyrus (51 components)

Best for: Docyrus-specific data handling, forms, dialogs, inline editing, scheduling, chat, AI agents, and business logic

Strengths:

• Deep Docyrus platform integration
• AwesomeDialog system for item creation and detail views
• EditableRecordDetail for inline field editing with change tracking
• 47 form field types with TanStack Form integration
• 44 value renderer types
• Data source query builders
• Scheduling: Gantt, Resource Scheduler, Time Slot Scheduler, Calendar
• Communication: Team Chat Channel, Email Composer, Comments Panel
• AI integration: Docyrus Agent (chat, action panel, trigger modes)
• Business: Pricing Engine, Record Sharing, Contact Activity
• Selection: Mega Select, Create Record Dialog
• Kanban board, notifications, maps, markdown editor, and more

Use when: Working with Docyrus data sources, building item create/detail flows, forms, scheduling, chat, AI features, or queries

reui (2 components)

Best for: Specific utility needs

Strengths:

• Focused implementations
• Lightweight alternatives

Use when: The specific component matches your exact need

---

Default Choices

These are the recommended defaults unless the user specifies otherwise:

---

When to Use Each Library

Use shadcn when:

• Building basic forms with standard inputs
• Creating simple layouts with cards, buttons, badges
• Need reliable, accessible primitives
• No special animation or advanced features required

Use diceui when:

• Building complex data tables with sorting/filtering
• Need advanced input types (phone, color, tags)
• Implementing drag-drop (kanban, sortable lists)
• Creating rich data visualizations (gauges, timelines)

Use animate-ui when:

• Animation/transitions are important to the design
• Building navigation with smooth interactions
• Creating polished dialog/overlay experiences
• Need animated feedback for user actions

Use docyrus when:

• Building item create forms (AwesomeDialog, Create Record Dialog)
• Building item detail views (AwesomeDialog + EditableRecordDetail)
• Working directly with Docyrus data sources
• Building forms that map to Docyrus fields (TanStack Form + DynamicFormField)
• Displaying Docyrus record data in tables/cards
• Need inline editing with change tracking
• Building scheduling UIs (Resource Scheduler, Time Slot Scheduler, Gantt, Calendar)
• Building communication features (Team Chat, Email Composer, Comments Panel)
• Integrating AI agents (Docyrus Agent with chat/action modes)
• Need pricing/quoting (Pricing Engine Panel)
• Need record sharing with permissions (Record Sharing)
• Need rich item selectors (Mega Select, Kanban)
• Need Docyrus-specific components (query builder, activity panel, notifications)

Use reui when:

• The specific component (file upload or sortable) matches your exact need
• Want a lightweight alternative to diceui versions

---

Icon Selection Guide

Priority order for icons:

1. hugeicons (first choice)

• Modern, consistent style
• Large icon set
• Use for: All general-purpose icons

2. fontawesome light (second choice)

• Professional appearance
• Familiar to users
• Use for: When hugeicons doesn't have the needed icon

3. lucide-icons (third choice)

• Clean, minimalist style
• Use for: Fallback when neither hugeicons nor fontawesome have the icon

Example:

import { HugeIconDollarCircle } from '@/components/icons/hugeicons'
import { FaLightChartLine } from '@/components/icons/fontawesome'
import { LucideActivity } from 'lucide-react'

// Prefer hugeicons
<HugeIconDollarCircle className="h-5 w-5" />

// Use fontawesome if not in hugeicons
<FaLightChartLine className="h-5 w-5" />

// Use lucide as fallback
<LucideActivity className="h-5 w-5" />

---

Quick Reference: Component Categories

Dialogs & Item Flows

• Item create forms: docyrus AwesomeDialog (sheet for small, modal for large)
• Quick record create: docyrus Create Record Dialog (popover with subject/mentions)
• Item detail (small): docyrus AwesomeDialog (sheet right)
• Item detail (large): Dedicated page route
• Inline editing: docyrus EditableRecordDetail
• Confirmation: animate-ui Alert Dialog
• Responsive: diceui Responsive Dialog

Data & Display

• Tables: docyrus Data Grid, diceui Data Table, shadcn Table
• Pivot table: docyrus PivotGrid (hierarchies, subtotals, drilldown, export)
• Grid saved views: docyrus Data Grid View Select + DataViews from @docyrus/app-utils
• Cards: docyrus AwesomeCard, shadcn Card
• Stat dashboards: docyrus AwesomeStats (grid/flex/tabs, mini-charts, comparisons)
• Charts: shadcn Chart + Recharts
• Stats: diceui Stat, diceui Gauge, shadcn Progress
• Gantt: docyrus Gantt
• Tree: docyrus TreeView

Forms & Input

• Dynamic forms: docyrus Form Fields + TanStack Form (always use)
• Inline editing: docyrus EditableRecordDetail, EditableValue
• Text: shadcn Input, Textarea
• Markdown: docyrus Simple Markdown Editor
• Selection: shadcn Select, diceui Combobox
• Rich selection: docyrus Mega Select (grid picker with categories)
• Radio cards: docyrus Radio Group (card variant with icons/descriptions)
• Dates: docyrus Date Time Picker, docyrus Date Time Range Picker, shadcn Calendar
• Files: diceui File Upload
• Special: diceui Phone Input, Color Picker, Tags Input

Navigation

• Sidebar: animate-ui Sidebar
• Menus: animate-ui Dropdown Menu, shadcn Menubar
• Breadcrumbs: shadcn Breadcrumb
• Tabs: animate-ui Tabs

Overlays

• Item forms/details: docyrus AwesomeDialog (preferred)
• Popovers: animate-ui Popover, Tooltip, Hover Card
• Drawers: shadcn Drawer, animate-ui Sheet

Communication

• Team chat: docyrus Team Chat Channel (threads, reactions, mentions)
• Email composing: docyrus Email Composer (To/Cc/Bcc, toolbar, attachments)
• Comments: docyrus Comments Panel (threaded conversations)
• Contact activities: docyrus Contact Activity Panel (calls, meetings, emails)
• Activity logging: docyrus Log Activity Form (calls, emails, meetings, tasks, statuses)

Scheduling

• Project timelines: docyrus Gantt
• Resource scheduling: docyrus Resource Scheduler Panel (horizontal timeline)
• Appointment booking: docyrus Time Slot Scheduler (columns/month views)
• Calendar events: docyrus Calendar (month/week/day views)

AI & Agents

• AI chat: docyrus Docyrus Agent (chat mode)
• AI actions: docyrus Docyrus Agent (action-panel mode)
• AI trigger: docyrus Docyrus Agent (floating trigger button)

Business Logic

• Pricing/quoting: docyrus Pricing Engine Panel (line items, VAT, discounts)
• Record sharing: docyrus Record Sharing (permissions, users/teams/roles)

Specialized

• Kanban: docyrus Kanban (drag-drop columns)
• Timeline: diceui Timeline
• Stepper / wizard: docyrus Stepper (6 variants, horizontal/vertical, animated)
• Query: docyrus Query Builder
• Notifications: docyrus NotificationStack
• Maps: docyrus Map
• Search: docyrus SearchInput
• Repeating rows: docyrus SchemaRepeater (dynamic structured data lists)

Icon Usage Guide

Comprehensive guide for using icon libraries in Docyrus applications: hugeicons, fontawesome light, and lucide-icons.

Table of Contents

1. Icon Library Preferences 2. Installation 3. Usage Patterns 4. Selection Strategy 5. Common Icon Mappings 6. Sizing & Styling 7. Best Practices

---

Icon Library Preferences

Priority order:

1. hugeicons (first choice)

• Modern, comprehensive icon set
• Consistent design language
• Wide coverage of common use cases

2. fontawesome light (second choice)

• Professional, familiar appearance
• Extensive icon collection
• Well-established library

3. lucide-icons (third choice)

• Clean, minimalist style
• Fallback option
• Good coverage of basic icons

Selection rule: Always try hugeicons first. If the icon doesn't exist, check fontawesome light. Use lucide-icons only as a last resort.

---

Installation

hugeicons

npm install @hugeicons/react
# or
pnpm add @hugeicons/react

Import pattern:

import { IconName } from '@hugeicons/react'

fontawesome light

npm install @fortawesome/fontawesome-svg-core
npm install @fortawesome/free-solid-svg-icons
npm install @fortawesome/react-fontawesome
# For light icons (pro):
npm install @fortawesome/pro-light-svg-icons

Import pattern:

import { FontAwesomeIcon } from '@fortawesome/react-fontawesome'
import { faIconName } from '@fortawesome/pro-light-svg-icons'

lucide-icons

npm install lucide-react
# or
pnpm add lucide-react

Import pattern:

import { IconName } from 'lucide-react'

---

Usage Patterns

hugeicons (Preferred)

import { Home01, User01, Settings01, ChartLineData01 } from '@hugeicons/react'

// Basic usage
<Home01 />

// With className
<User01 className="h-5 w-5 text-muted-foreground" />

// In a button
<Button>
  <Settings01 className="mr-2 h-4 w-4" />
  Settings
</Button>

// In AwesomeCard
<AwesomeCard
  icon={<ChartLineData01 className="h-8 w-8" />}
  title="Revenue"
  value="$124,500"
/>

fontawesome light (Second Choice)

import { FontAwesomeIcon } from '@fortawesome/react-fontawesome'
import { faHome, faUser, faCog, faChartLine } from '@fortawesome/pro-light-svg-icons'

// Basic usage
<FontAwesomeIcon icon={faHome} />

// With className
<FontAwesomeIcon icon={faUser} className="h-5 w-5 text-muted-foreground" />

// In a button
<Button>
  <FontAwesomeIcon icon={faCog} className="mr-2 h-4 w-4" />
  Settings
</Button>

lucide-icons (Fallback)

import { Home, User, Settings, TrendingUp } from 'lucide-react'

// Basic usage
<Home />

// With className
<User className="h-5 w-5 text-muted-foreground" />

// In a button
<Button>
  <Settings className="mr-2 h-4 w-4" />
  Settings
</Button>

---

Selection Strategy

Decision Process

1. Determine what icon you need (e.g., "home", "user", "chart")
   ↓
2. Check hugeicons documentation/search
   - Found? ✓ Use it
   - Not found? → Continue to step 3
   ↓
3. Check fontawesome light documentation/search
   - Found? ✓ Use it
   - Not found? → Continue to step 4
   ↓
4. Check lucide-icons documentation/search
   - Found? ✓ Use it
   - Not found? → Use closest alternative from any library

Example Search Flow

Scenario: Need a "dashboard" icon

1. Check hugeicons: Dashboard01 ✓ Use this 2. ~~Check fontawesome~~ (already found) 3. ~~Check lucide~~ (already found)

Scenario: Need a "bell" icon

1. Check hugeicons: Notification01 ✓ Use this 2. ~~Check fontawesome~~ (already found) 3. ~~Check lucide~~ (already found)

Scenario: Need a specific icon not in hugeicons

1. Check hugeicons: Not found ✗ 2. Check fontawesome: faBell ✓ Use this 3. ~~Check lucide~~ (already found)

---

Common Icon Mappings

---

Sizing & Styling

Standard Sizes

// Extra small (navigation items, tight spaces)
<Icon className="h-3 w-3" />

// Small (buttons, inline with text)
<Icon className="h-4 w-4" />

// Medium (default for most UI elements)
<Icon className="h-5 w-5" />

// Large (emphasized actions, cards)
<Icon className="h-6 w-6" />

// Extra large (dashboard cards, hero sections)
<Icon className="h-8 w-8" />

// Hero (feature highlights)
<Icon className="h-12 w-12" />

Color & Style

// Inherit text color
<Icon className="h-5 w-5" />

// Muted/secondary
<Icon className="h-5 w-5 text-muted-foreground" />

// Primary color
<Icon className="h-5 w-5 text-primary" />

// Destructive/danger
<Icon className="h-5 w-5 text-destructive" />

// Success
<Icon className="h-5 w-5 text-green-600" />

// Warning
<Icon className="h-5 w-5 text-amber-600" />

// With opacity
<Icon className="h-5 w-5 text-foreground/50" />

Common Patterns

Icon with text (button):

<Button>
  <Icon className="mr-2 h-4 w-4" />
  Button Text
</Button>

Icon-only button:

<Button variant="ghost" size="icon">
  <Icon className="h-5 w-5" />
  <span className="sr-only">Accessible label</span>
</Button>

Icon in input:

<div className="relative">
  <Icon className="absolute left-3 top-3 h-4 w-4 text-muted-foreground" />
  <Input className="pl-9" />
</div>

Icon in card header:

<AwesomeCard
  icon={<Icon className="h-8 w-8 text-primary" />}
  title="Title"
  value="Value"
/>

---

Best Practices

1. Consistency

• Use the same icon library throughout a feature/page
• Don't mix hugeicons and fontawesome for similar concepts
• Maintain consistent sizing within the same context

2. Accessibility

• Always provide accessible labels for icon-only buttons:

  <Button variant="ghost" size="icon" aria-label="Settings">
    <Settings01 className="h-5 w-5" />
  </Button>

• Use <span className="sr-only"> for screen readers:

  <Button variant="ghost" size="icon">
    <Settings01 className="h-5 w-5" />
    <span className="sr-only">Open settings</span>
  </Button>

3. Performance

• Import only the icons you need (tree-shaking):

  // Good
  import { Home01, User01 } from '@hugeicons/react'

  // Avoid
  import * as HugeIcons from '@hugeicons/react'

4. Semantic Usage

• Use appropriate icons for actions:
• Delete: Trash/Delete icon
• Edit: Pencil/Edit icon
• View: Eye icon
• Download: Download arrow
• Maintain icon semantics across the app

5. Spacing

• Use consistent spacing with Tailwind classes:

  // Icon before text
  <Icon className="mr-2 h-4 w-4" />

  // Icon after text
  <Icon className="ml-2 h-4 w-4" />

  // Icon above text (flex column)
  <Icon className="mb-2 h-6 w-6" />

---

Library-Specific Tips

hugeicons

• Naming convention: IconName01, IconName02 for variants
• Often includes outlined and filled versions
• Check for numbered variants (01, 02, 03) for style options

fontawesome light

• Pro license required for light icons
• Use @fortawesome/free-solid-svg-icons for free versions
• Prefix: fa + camelCase name (e.g., faHome, faUserCircle)

lucide-icons

• PascalCase naming (e.g., Home, UserCircle)
• Minimal, consistent stroke width
• Great for clean, modern designs

---

Quick Reference: Priority Flow

Need an icon?
    ↓
Search hugeicons
    ↓
Found? → Use it ✓
    ↓
Not found?
    ↓
Search fontawesome light
    ↓
Found? → Use it ✓
    ↓
Not found?
    ↓
Search lucide-icons
    ↓
Found? → Use it ✓
    ↓
Not found?
    ↓
Use closest semantic match from any library

---

Example: Dashboard Page

import {
  Dashboard01,
  ChartLineData01,
  User01,
  ShoppingCart01
} from '@hugeicons/react'
import { AwesomeCard } from '@/components/ui/awesome-card'

export function DashboardPage() {
  return (
    <div className="grid gap-4 md:grid-cols-2 lg:grid-cols-4">
      <AwesomeCard
        icon={<ChartLineData01 className="h-8 w-8" />}
        title="Total Revenue"
        value="$124,500"
      />
      <AwesomeCard
        icon={<User01 className="h-8 w-8" />}
        title="Active Users"
        value="1,234"
      />
      <AwesomeCard
        icon={<ShoppingCart01 className="h-8 w-8" />}
        title="Orders"
        value="456"
      />
      <AwesomeCard
        icon={<Dashboard01 className="h-8 w-8" />}
        title="Conversion Rate"
        value="3.2%"
      />
    </div>
  )
}

All icons from hugeicons (first choice) ✓

Preferred Components Catalog

Complete reference of all 158 available components across shadcn, diceui, animate-ui, docyrus, and reui libraries.

Table of Contents

1. shadcn Components (43) 2. diceui Components (41) 3. animate-ui Components (21) 4. docyrus Components (51) 5. reui Components (2)

---

shadcn Components (43)

Core UI components for building accessible, well-designed interfaces.

---

diceui Components (41)

Advanced, specialized components for complex UI patterns.

---

animate-ui Components (21)

Animated components with smooth transitions and interactions.

---

docyrus Components (51)

Docyrus-specific components for data handling, forms, dialogs, editing, scheduling, chat, AI agents, and business logic.

---

reui Components (2)

Utility components for specialized file and sorting operations.

---

Docyrus UI Guide Documentation

Fetch these llms.txt endpoints for detailed guidance on installation, theming, and patterns:

---

Component Count Summary

• shadcn: 43 components
• diceui: 41 components
• animate-ui: 21 components
• docyrus: 51 components
• reui: 2 components

Total: 158 components

Docyrus App Dev React Reference Map

This directory contains the full reference set for docyrus-app-dev-react.

App Development References

Read these files for data access, auth, query design, and collection patterns:

• api-client-and-auth.md
• collections-and-patterns.md
• the docyrus-acl-design skill — ACL roles, permissions, and role-queries (docyrus acl); plus the ACL REST endpoints in docyrus-api-dev's SKILL.md
• ../../docyrus-api-dev/references/data-source-query-guide.md
• ../../docyrus-api-dev/references/formula-design-guide-llm.md
• ../../docyrus-api-dev/references/query-guide.md

UI Design References

Read these files for component selection, design patterns, and UI library guidance:

• preferred-components-catalog.md
• component-selection-guide.md
• icon-usage-guide.md

How to Use This Skill

1. Start with ../SKILL.md for the merged operating guidance. 2. Use the app-development references when working on auth, queries, collections, routing, and mutations. 3. Use the UI-design references when selecting components, designing layouts, or implementing polished feature flows. 4. Combine both when building end-to-end Docyrus React features.