npm package: @ortha/admin-users
Description: 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.
Latest version: 0.0.4

# @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:

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

## Usage

### Registering the plugin

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

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

### Using API hooks

```ts
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

```ts
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

```bash
nx build admin-users
```