identity-admin 1.28.28 → 1.28.30

package/skills/identity-admin/resource-file.md

@@ -0,0 +1,654 @@
+# Resource File Reference (`IResourceFile`)
+
+This is the companion reference for the **identity-admin** skill. It documents every property of the `IResourceFile` interface that defines how a Mongoose model appears and behaves in the admin dashboard.
+
+```typescript
+export interface IResourceFile {
+  properties: { /* see below */ };
+  listProperties?: string[];
+  showProperties?: string[];
+  formProperties?: string[];
+  filterProperties?: string[];
+  quickFilterProperties?: string[];
+}
+```
+
+---
+
+## Required Properties
+
+```typescript
+properties: {
+  resource: Model<any, any>;  // the compiled Mongoose model
+  modelName: string;           // database collection name
+}
+```
+
+- `resource` — The Mongoose model instance (e.g., `User` from `mongoose.model('User', schema)`)
+- `modelName` — The collection name in MongoDB (e.g., `'users'`). Used for API route generation and permission lookups.
+
+---
+
+## Identity & Display
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `properties.name` | `string` | `modelName` | Display name in nav bar, page titles, and breadcrumbs |
+| `properties.title` | `string` | Auto-detected | Field used as the clickable record link. Auto-detects `name`, `title`, or `email` on the schema; falls back to `_id`. Also used as the search bar target. |
+| `properties.defaultOrderBy` | `string` | Schema title field | Sort field for the list view |
+| `properties.defaultOrder` | `'asc' \| 'desc'` | `'asc'` | Sort direction |
+| `properties.defaultrowsPerPage` | `number` | `10` | Default pagination size |
+
+## Navigation
+
+```typescript
+properties: {
+  parent?: {
+    name: string;  // nav group label (e.g., "Content", "Users")
+    icon: string;  // MUI icon name (e.g., "People", "Settings")
+  };
+}
+```
+
+Resources with the same `parent.name` are grouped under one nav section. Icons come from [Material UI icons](https://mui.com/material-ui/material-icons/).
+
+## Visibility & Access Control
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `properties.isAllowed` | `(currentUser) => Promise<boolean>` | `true` | Whether the user can access this resource at all |
+| `properties.isVisible` | `(currentUser) => Promise<boolean>` | `true` | Whether the resource appears in the nav bar |
+| `properties.enableLog` | `(currentUser) => Promise<boolean>` | `false` | Whether to log changes to this resource |
+| `properties.hiddenProperties` | `string[]` | `[]` | Fields completely hidden from all pages |
+
+## Display Property Arrays
+
+Control exactly which fields appear on each view:
+
+| Array | Purpose |
+|-------|---------|
+| `listProperties` | Table columns in the list/index view. Shows first 4 by default. |
+| `showProperties` | Read-only fields in the detail view |
+| `formProperties` | Editable fields in create/edit forms |
+| `filterProperties` | Fields available in the advanced filter panel |
+| `quickFilterProperties` | Fields shown as quick filter chips above the table |
+
+If not specified, **all schema fields** (`list/show/form/filter`) or **none** (`quickFilter`) are shown.
+
+## Field Overrides (`properties.model`)
+
+```typescript
+properties: {
+  model?: { [fieldName: string]: IFieldValue } | IModel;
+}
+```
+
+Override any schema field's behavior, or add virtual fields. Each key is a field name from the Mongoose schema.
+
+### `IFieldValue` Reference
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `type` | `FieldTypes` | Same as schema | Override the field type. See enums below. |
+| `required` | `boolean` | Same as schema | Override whether the field is required in forms |
+| `isEditable` | `boolean` | `true` | Whether the field can be edited |
+| `enumValues` | `string[] \| { [key]: { label, color?, labelColor? } }` | Same as schema | Custom enum labels and chip colors |
+| `countryCodes` | `string[]` | — | Allowed country codes for phone number fields (e.g., `['sa', 'eg']`) |
+| `defaultCountryCode` | `string` | First country or `'sa'` | Default selected country for phone fields |
+| `mediaUploader` | `boolean` | — | Enable media upload for reference fields pointing to the Image collection |
+| `fileType` | `FileTypes` | `'IMAGE'` | Restrict media uploader to specific file types |
+| `imageOptimizingCategory` | `ImageOptimizingCategories` | `'NORMAL'` | Image compression level (`'NORMAL'` or `'BANNERS'`) |
+| `disableImageOptimization` | `boolean` | `false` | Skip image optimization |
+| `imageBackgroundHexColor` | `string` | — | Background color for image display |
+| `withTime` | `boolean` | `false` | Show time picker alongside date picker |
+| `apiRoute` | `string` | — | API endpoint for fetching reference options |
+| `valuePath` | `string` | — | Path to the value inside a referenced document |
+| `isClickable` | `boolean` | — | Whether the field value is clickable in the list |
+| `path` | `string` | — | Resource path to navigate to on click |
+| `keys` | `string[]` | — | Keys to show within a nested schema field |
+| `schema` | `IModel \| { [key]: IFieldValue }` | — | Define nested schema structure |
+| `multipleInFilter` | `boolean` | — | Enable multi-value selection for this quick filter |
+| `yupValidationSchema` | `Yup.Schema` | Same as schema | Custom Yup validation |
+| `enableCreateNewButtonOnReference` | `boolean` | `false` | Show "Create New" button inside reference selector |
+| `textArea` | `boolean` | `false` | Render text field as a multi-line textarea |
+| `relatedFields` | `string[]` | — | Show related fields from a referenced document |
+| `minWidth` | `number` | — | Minimum column width in the list view |
+| `filter` | `{ formList?, filterList? }` | — | Filter options for reference selectors (`Record<string, any>`) |
+| `arrayType` | `FieldTypes` | Same as schema | Element type for array fields |
+| `isDraggable` | `boolean` | `true` | Whether array items are reorderable by drag-and-drop |
+
+### Virtual Fields (`IModel.virtuals`)
+
+Add fields that don't exist in the database but are needed in the UI:
+
+```typescript
+model?: {
+  virtuals?: {
+    [virtualName: string]: IVirtualValue;
+  };
+}
+```
+
+### `IVirtualValue` Reference
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `type` | `'password' \| 'ref' \| 'Array'` | Virtual field type |
+| `filterBy` | `string` | For `ref` type: the foreign key field for one-to-many relations |
+| `arrayType` | `string` | For `Array` type: the element type |
+| `showIn` | `Virtuals` | Where to display: `'SHOW'`, `'LIST'`, `'FORM'`, or `'FILTER'` |
+| `required` | `boolean` | Whether the virtual is required in forms |
+| `resource` | `Model` | For `ref`/`Array` type: the related Mongoose model |
+| `handler` | `(filterQuery, value) => filterQuery` | Custom filter query logic when used in filters |
+
+**Use cases:**
+
+- `password` — Add a password field to the creation form without storing it in the model
+- `ref` — Display related child records (e.g., all posts by a user) in the show page
+- `Array` — Display an array of related items
+
+## Actions (`properties.actions`)
+
+```typescript
+properties: {
+  actions?: ActionOptions;
+}
+```
+
+Control built-in CRUD actions and add custom extra actions:
+
+```typescript
+interface ActionOptions {
+  show?: Action;
+  new?: Action;
+  edit?: Action;
+  delete?: Action;
+  import?: Action;
+  bulkDelete?: Action;
+  duplicate?: Action;
+  extras?: ExtraAction[];
+}
+```
+
+### `Action` Interface (for built-in actions)
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `isAccessible` | `boolean` | `true` (except bulkDelete/import: `false`) | Whether the action is available |
+| `reloadAfterAction` | `boolean` | `false` | Reload page after action execution |
+| `isAllowed` | `(currentUser) => boolean` | Same as `isAccessible` | Role-based permission check |
+| `isMainAction` | `boolean` | `true` for show/edit, `false` for others | Whether action appears as a primary button vs. menu item |
+| `isVisible` | `(data: ActionData) => Promise<boolean>` | Same as `isAccessible` | Per-record visibility check |
+
+### `ExtraAction` Interface (custom actions)
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `key` | `string` | — | Unique identifier within the resource |
+| `name` | `string` | — | Button label |
+| `icon` | `string` | — | MUI icon name |
+| `color` | `string \| ButtonColors` | `'inherit'` (bulk) / `'black'` (record) | Button color |
+| `size` | `ButtonSizes` | `'small'` | Button size (bulk actions only) |
+| `variant` | `ButtonVariants` | `'contained'` | Button variant (bulk actions only) |
+| `actionType` | `'record' \| 'resource'` | — | `'record'` = per-row action, `'resource'` = top-level button |
+| `guardTitle` | `string` | — | Confirmation dialog title |
+| `guard` | `string` | — | Confirmation dialog message |
+| `message` | `string` | `'Action was executed successfully'` | Success alert message |
+| `showAlertMessage` | `boolean` | `true` | Whether to show the success alert |
+| `severity` | `'success' \| 'info' \| 'warning' \| 'error'` | `'success'` | Alert severity/color |
+| `fullScreen` | `boolean` | `false` | Whether the custom component dialog is full screen |
+| `isVisible` | `(data: ActionData) => Promise<boolean>` | Always visible | Per-record visibility |
+| `isMainAction` | `boolean` | `true` for show/edit | Whether it's a primary button vs. menu item |
+| `handler` | `(req, res, data) => Promise<IActionHandlerResponse>` | — | The action logic |
+| `handlerStrategy` | `HandlerStrategy` | — | `'NORMAL'`, `'FILE_DOWNLOAD'`, or `'CUSTOM_COMPONENT'` |
+
+### `IActionHandlerResponse`
+
+```typescript
+interface IActionHandlerResponse {
+  action: ActionNames;   // 'SHOW' | 'LIST' | 'NEW' | 'EDIT'
+  path: string;          // resource.path to redirect to
+  recordId?: string;     // for SHOW/EDIT redirections
+  filePath?: string;     // for FILE_DOWNLOAD strategy
+}
+```
+
+### `ActionData` (passed to `isVisible` and `handler`)
+
+```typescript
+interface ActionData {
+  record: any;                              // the document
+  currentUser: Document;                    // authenticated user
+  resource: {
+    name: string;                           // modelName
+    path: string;                           // resource route path
+    repository: IRepository<Document>;      // the repository instance
+  };
+}
+```
+
+## Filters (`properties.filters`)
+
+```typescript
+properties: {
+  filters?: IFilters;
+}
+```
+
+### Scopes
+
+Scope filters add tabs above the list view:
+
+```typescript
+scopes?: {
+  isAccessible: boolean;   // default false
+  showAll?: boolean;       // show "All" tab (default true)
+
+  // Auto scope — filters by a schema key with predefined values
+  auto?: {
+    key: string;           // schema field name (e.g., 'status')
+    options: string[];     // values that become tabs
+  };
+
+  // Manual scope — full control with a handler
+  manual?: {
+    options: string[];     // tab labels
+    handler: (filter, scope, currentUser) => Promise<filter>;
+  };
+}
+```
+
+**Auto scope example** — creates tabs for each `status` value:
+```typescript
+scopes: { isAccessible: true, auto: { key: 'status', options: ['active', 'inactive', 'pending'] } }
+```
+
+**Manual scope example** — custom logic per tab:
+```typescript
+scopes: {
+  isAccessible: true,
+  manual: {
+    options: ['Today', 'This Week', 'This Month'],
+    handler: async (filter, scope) => {
+      const now = new Date();
+      switch (scope) {
+        case 'Today':
+          filter.createdAt = { $gte: new Date(now.setHours(0,0,0,0)) };
+          break;
+        case 'This Week':
+          filter.createdAt = { $gte: new Date(now.setDate(now.getDate() - now.getDay())) };
+          break;
+      }
+      return filter;
+    },
+  },
+}
+```
+
+### Search Bar
+
+```typescript
+searchBar?: {
+  isAccessible: boolean;   // default true
+}
+```
+
+## CRUD Operations (`properties.crudOperations`)
+
+Intercept any CRUD lifecycle stage. Each hook receives different arguments and must return a specific type — pay close attention to parameter order and return types.
+
+```typescript
+properties: {
+  crudOperations?: ICrudOperations;
+}
+```
+
+---
+
+### `index` — List view
+
+#### `index.before`
+```typescript
+before?: (
+  req: IRequest,
+  filter: { [key: string]: any },
+  currentUser: Document
+) => Promise<{ [key: string]: any }>
+```
+Modify the MongoDB filter object before the query runs. Return the (possibly modified) filter.
+
+#### `index.after`
+```typescript
+after?: (
+  req: IRequest,
+  documents: Document[],
+  currentUser: Document
+) => Promise<Document[]>
+```
+Transform the result array after the query completes. Return the modified documents array.
+
+#### `index.index` (custom query)
+```typescript
+index?: (
+  req: IRequest,
+  filter: { [key: string]: any },
+  sortQuery: { [key: string]: any },
+  paginateParams: PaginateParams | undefined,
+  populate: any,
+  currentUser: Document
+) => Promise<{ records: Document[]; pageInfo?: PageInfo }>
+```
+Replace the entire list query with custom logic. You receive the raw filter, sort, pagination, and populate params. Return `{ records, pageInfo? }`.
+
+---
+
+### `create` — Create record
+
+#### `create.before`
+```typescript
+before?: (
+  req: IRequest,
+  params: any,
+  currentUser: Document
+) => Promise<any>
+```
+Modify the request body params before the document is saved. Return the (possibly modified) params. Common use: inject `createdBy` from `currentUser._id`.
+
+#### `create.after`
+```typescript
+after?: (
+  req: IRequest,
+  document: Document,
+  currentUser: Document,
+  params: any
+) => Promise<Document>
+```
+Called after the document is saved. Receives both the saved document and the original params. Return the (possibly modified) document.
+
+**Argument order:** `req, document, currentUser, params` — note `currentUser` comes before `params`.
+
+#### `create.validators`
+```typescript
+validators?: ValidationChain[]
+```
+Array of [express-validator](https://express-validator.github.io) chains run before the save query.
+
+---
+
+### `update` — Update record
+
+#### `update.before`
+```typescript
+before?: (
+  req: IRequest,
+  params: any,
+  currentUser: Document
+) => Promise<any>
+```
+Modify the request body params before the document is updated. Return the (possibly modified) params.
+
+#### `update.after`
+```typescript
+after?: (
+  req: IRequest,
+  document: Document,
+  params: any,
+  currentUser: Document
+) => Promise<Document>
+```
+Called after the document is updated. Receives the updated document, the submitted params, and the current user.
+
+**Argument order:** `req, document, params, currentUser` — different from `create.after` where `currentUser` comes before `params`.
+
+#### `update.update` (custom update)
+```typescript
+update?: (
+  req: IRequest,
+  record: Document,
+  recordParams: any,
+  currentUser: Document
+) => Promise<SaveResult<any>>
+```
+Replace the entire update logic. Receives the existing `record`, the `recordParams` from the request, and the current user. Return a `SaveResult<any>`.
+
+#### `update.validators`
+```typescript
+validators?: ValidationChain[]
+```
+Array of express-validator chains run before the update query.
+
+---
+
+### `show` — Detail view
+
+#### `show.before`
+```typescript
+before?: (
+  req: IRequest,
+  filter: { [key: string]: any },
+  currentUser: Document
+) => Promise<{ [key: string]: any }>
+```
+Modify the lookup filter before the record is fetched. Return the (possibly modified) filter.
+
+#### `show.after`
+```typescript
+after?: (
+  req: IRequest,
+  record: Document
+) => Promise<{ record: Document; [key: string]: any }>
+```
+Add extra data to the show response. **Note:** this hook does NOT receive `currentUser`. Return an object containing the `record` plus any additional fields.
+
+```typescript
+// Example: attach related data to the response
+show: {
+  after: async (req, record) => {
+    const stats = await Stats.findOne({ userId: record._id });
+    return { record, stats };
+  },
+},
+```
+
+#### `show.nextPreviousButtonHandler`
+```typescript
+nextPreviousButtonHandler?: (
+  req: IRequest,
+  filter: { [key: string]: any },
+  currentUser: Document,
+  direction: NeighborTypes   // 'NEXT' | 'PREVIOUS'
+) => Promise<{ [key: string]: any }>
+```
+Custom logic for navigating to the next or previous record. Modify the filter to scope which records are eligible for neighbor navigation. Return the filter.
+
+## Population (`properties.populate`)
+
+Control how referenced fields are populated:
+
+```typescript
+populate?: {
+  all?: PopulateFunction;     // applied to all endpoints
+  list?: PopulateFunction;    // applied only to list endpoint
+  show?: PopulateFunction;    // applied to show, create, update
+}
+
+// PopulateFunction = (populatedString: any) => Promise<any>
+```
+
+The function receives the current populate string and can modify it before execution.
+
+## Localization
+
+```typescript
+keysTranslations?: { [key: string]: any };     // field label translations
+actionsTranslations?: { [key: string]: any };  // action button translations
+```
+
+Structure mirrors the locale JSON (see `src/locales/en.json`). Used when `enableLocalization: true` is set in the app configuration.
+
+## Additional Options
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `disableNextPreviousButtonsInShowPage` | `boolean` | `false` | Hide prev/next navigation in show |
+| `disableNextPreviousButtonsInEditPage` | `boolean` | `false` | Hide prev/next navigation in edit |
+| `displayEditPageInShowPage` | `boolean` | `false` | Open edit form instead of show view |
+| `imageOnReferencePath` | `string` | — | Field path for thumbnail image in reference selectors |
+| `disableImageOnReference` | `boolean` | `false` | Hide thumbnail images in reference selectors |
+| `extras` | `{ [key]: any }` | — | Arbitrary extra data passed to the frontend |
+| `sendDraftMail` | `(data: { to, subject, html }) => Promise<void>` | — | Handler for sending draft emails from mail log |
+| `afterImport` | `(req, currentUser, data) => Promise<any>` | — | Post-import processing hook |
+
+---
+
+## Enums
+
+### `FieldTypes`
+
+| Value | Description |
+|-------|-------------|
+| `'String'` | Text input |
+| `'Number'` | Number input |
+| `'enum'` | Dropdown / chips |
+| `'ref'` | Reference to another model |
+| `'Date'` | Date picker |
+| `'password'` | Masked password input |
+| `'Boolean'` | Toggle switch |
+| `'ObjectID'` | Object ID display |
+| `'nestedSchema'` | Embedded sub-document |
+| `'Array'` | Array of values |
+| `'image'` | Image upload with preview |
+| `'localizedString'` | Multi-language string |
+| `'phoneNumber'` | Phone input with country code |
+| `'color'` | Color picker |
+| `'timePicker'` | Time selector |
+| `'File'` | File upload |
+| `'LOCATION'` | Map location picker |
+| `'HTML'` | HTML rich text editor |
+| `'RICH_TEXT_I'` | Rich text editor (type I) |
+| `'RICH_TEXT_II'` | Rich text editor (type II) |
+| `'JSON_RICH_TEXT'` | JSON-based rich text |
+| `'EXTERNAL_LINK'` | External URL input |
+| `'MULTIPLE_TEXT'` | Multiple text values |
+
+### `ActionTypes`
+
+- `'record'` — Per-row action in the list
+- `'resource'` — Top-level action button
+
+### `ActionNames`
+
+- `'SHOW'`, `'LIST'`, `'NEW'`, `'EDIT'` — Redirection targets
+
+### `Virtuals`
+
+- `'SHOW'`, `'LIST'`, `'FORM'`, `'FILTER'` — Where a virtual field appears
+
+### `HandlerStrategy`
+
+- `'NORMAL'` — Standard handler execution
+- `'FILE_DOWNLOAD'` — Returns a file for download
+- `'CUSTOM_COMPONENT'` — Opens a custom React component dialog
+
+### `FileTypes`
+
+`'ALL'`, `'IMAGE'`, `'3D'`, `'PDF'`, `'EXCEL'`, `'WORD'`, `'VIDEO'`, `'TEXT'`, `'ZIP'`, `'POWER_POINT'`, `'AUDIO'`
+
+### `ImageOptimizingCategories`
+
+- `'NORMAL'` — Standard compression
+- `'BANNERS'` — Banner-level compression
+
+---
+
+## Complete Example
+
+```typescript
+import { Model, Schema } from 'mongoose';
+import { IResourceFile } from 'identity-admin/lib/types/IResourceFile';
+import { FieldTypes, Virtuals, ActionTypes } from 'identity-admin/lib/types/helpers';
+
+const UserResource: IResourceFile = {
+  properties: {
+    resource: User,
+    modelName: 'users',
+    name: 'Users',
+    title: 'fullName',
+    parent: { name: 'Access Control', icon: 'People' },
+    defaultOrderBy: 'createdAt',
+    defaultOrder: 'desc',
+    defaultrowsPerPage: 25,
+    isAllowed: async (user) => user.role === 'admin',
+    isVisible: async (user) => user.role !== 'viewer',
+    hiddenProperties: ['__v', 'encryptedPassword'],
+    model: {
+      fullName: { type: 'String' as FieldTypes, required: true },
+      email: { type: 'String' as FieldTypes, isEditable: false },
+      role: {
+        type: 'enum' as FieldTypes,
+        enumValues: {
+          admin: { label: 'Admin', color: '#FF6B6B', labelColor: '#FFF' },
+          editor: { label: 'Editor', color: '#4ECDC4', labelColor: '#FFF' },
+          viewer: { label: 'Viewer', color: '#95E1D3', labelColor: '#333' },
+        },
+      },
+      avatar: { type: 'image' as FieldTypes, mediaUploader: true, imageOptimizingCategory: 'NORMAL' as any },
+      phone: { type: 'phoneNumber' as FieldTypes, countryCodes: ['sa', 'eg', 'us'] },
+      bio: { type: 'HTML' as FieldTypes },
+      virtuals: {
+        password: { type: 'password', showIn: Virtuals.FORM, required: true },
+        posts: { type: 'ref', filterBy: 'author', showIn: Virtuals.SHOW, resource: Post },
+      },
+    },
+    actions: {
+      delete: { isAccessible: false },
+      bulkDelete: { isAccessible: true },
+      extras: [
+        {
+          key: 'sendWelcomeEmail',
+          name: 'Send Welcome',
+          icon: 'Email',
+          actionType: 'record' as ActionTypes,
+          handler: async (req, res, data) => {
+            await sendEmail(data.record.email, 'Welcome!');
+            return { action: 'LIST', path: data.resource.path };
+          },
+        },
+      ],
+    },
+    filters: {
+      scopes: {
+        isAccessible: true,
+        auto: { key: 'role', options: ['admin', 'editor', 'viewer'] },
+      },
+    },
+    crudOperations: {
+      create: {
+        before: async (req, params, currentUser) => {
+          params.createdBy = currentUser._id;
+          return params;
+        },
+      },
+      index: {
+        before: async (req, filter) => {
+          if (req.query.search) filter.$text = { $search: req.query.search };
+          return filter;
+        },
+      },
+    },
+    populate: {
+      all: async (populateStr) => `${populateStr} createdBy`,
+    },
+    keysTranslations: {
+      fullName: { en: 'Full Name', ar: 'الاسم الكامل' },
+      email: { en: 'Email', ar: 'البريد الإلكتروني' },
+    },
+    disableNextPreviousButtonsInShowPage: true,
+  },
+  listProperties: ['fullName', 'email', 'role', 'createdAt'],
+  showProperties: ['fullName', 'email', 'role', 'avatar', 'bio', 'createdAt'],
+  formProperties: ['fullName', 'email', 'role', 'avatar', 'phone', 'bio', 'password'],
+  filterProperties: ['role', 'createdAt'],
+  quickFilterProperties: ['role'],
+};
+```