@ortha/admin-users

Users UI plugin for the Ortha admin application — provides user management pages with server-delegated filtering, cursor-based pagination, user detail profiles with sub-routing, and project assignment management.

Installation

Internal monorepo dependency — import directly:

import { usersPlugin, fetchUsers } from '@ortha/admin-users';
import type { User, UsersResponse, UsersParams } from '@ortha/admin-users';

Usage

Registering the plugin

import { bootstrap } from '@ortha/admin-platform-bootstrap';
import { usersPlugin } from '@ortha/admin-users';

bootstrap(document.getElementById('root')!, [
    usersPlugin()
    // ...other plugins
]);

Using API hooks

import {
    useUsers,
    useUser,
    useUpdateUser,
    useResetUserPassword
} from '@ortha/admin-users';

const UsersList = () => {
    const { data } = useUsers({ page: 1, limit: 20 });
    // data.items, data.pagination
};

const UserProfile = ({ id }: { id: string }) => {
    const { data: user } = useUser(id);
    const updateUser = useUpdateUser();
    const resetPassword = useResetUserPassword();
};

Cross-package user fetching

import { fetchUsers } from '@ortha/admin-users';

// Plain fetch function — used by other packages (e.g. projects team step)
const users = await fetchUsers({ search: 'john', limit: 10 });

Routes

| Path | Page | Description | | --------------------- | ----------------- | ------------------------------- | | /users | Users list page | Table with filters + pagination | | /users/:id/general | User general info | Profile sub-route | | /users/:id/projects | User projects | Project assignments |

API Reference

Plugin

| Export | Kind | Description | | --------------- | ------- | ------------------------------------------------- | | usersPlugin() | factory | Admin plugin — registers user routes and nav slot | | fetchUsers | fn | Plain fetch function for cross-package use |

Hooks

| Export | Kind | Description | | ----------------------- | ---- | ------------------------------------------ | | useUsers | hook | Users list query with pagination/filtering | | useUser | hook | Single user query | | useUsersStats | hook | Users stats query | | useUpdateUser | hook | Update user mutation | | useUpdateUserStatus | hook | Update user status mutation | | useUpdateUserProjects | hook | Bulk update user projects mutation | | useAddUserProject | hook | Add project to user mutation | | useRemoveUserProject | hook | Remove project from user mutation | | useResetUserPassword | hook | Reset user password mutation |

Query Keys

| Export | Kind | Description | | --------------- | ---- | --------------------------------------- | | usersKey | fn | Query key factory for users list cache | | usersStatsKey | fn | Query key factory for users stats cache | | userKey | fn | Query key factory for single user cache |

Types

| Export | Kind | Description | | --------------- | ---- | ------------------------------- | | User | type | User entity | | UserRole | type | User's role | | UserProject | type | User's project assignment | | UsersResponse | type | Paginated users response | | UsersParams | type | Query parameters for users list |

Filtering

The users table supports server-delegated filtering via QueryBuilder:

• Status filter: active (isActive), inactive (deactivated, excludes pending), pending (has InviteCode)
• Project filter: array column type with $exists + projectId conditions on UserProject relation
• Filters are translated from QueryBuilder format to Sequelize-style JSON via filterTranslator

URL search params are the single source of truth for table state.

Internal Structure

src/lib/
├── usersPlugin/index.ts            # Plugin factory with route and slot registration
├── types/index.ts                  # Shared types (User, UserRole, UsersParams, etc.)
├── api/
│   ├── fetchUsers/index.ts         # Plain fetch function (cross-package use)
│   ├── useUsers/index.ts           # usersKey + useUsers query
│   ├── useUser/index.ts            # userKey + useUser query
│   ├── useUsersStats/index.ts      # usersStatsKey + useUsersStats query
│   ├── useUpdateUser/index.ts      # UpdateUserBody + mutation
│   ├── useUpdateUserStatus/index.ts
│   ├── useUpdateUserProjects/index.ts
│   ├── useAddUserProject/index.ts
│   ├── useRemoveUserProject/index.ts
│   └── useResetUserPassword/index.ts
├── hooks/
│   └── useUsersTable/index.ts      # Main table state hook (server-delegated)
├── utils/
│   └── filterTranslator/index.ts   # QueryBuilder → server filter JSON translation
├── pages/
│   └── UsersPage/index.tsx         # Main page component
└── components/                     # UI components (table, filters, stats, etc.)

Key Patterns

• Route components are lazy-loaded with React.lazy().
• API hooks use TanStack React Query and httpClient from @ortha/admin-platform-core.
• Cursor-based pagination with prev/next navigation.
• URL search params drive all table state (filters, sort, cursor).
• Forms use react-hook-form with ajvResolver from @ortha/admin-utils.
• Depends on the home plugin (uses the authenticated root layout).

Dependencies

• @ortha/admin-platform-core — httpClient, slot constants, auth store
• @ortha/admin-platform-plugin-registry — plugin types
• @ortha/admin-utils — ajvResolver, handleMutationError
• @ortha/design-system — theme and UI components

Building

nx build admin-users