adminforth 2.17.0-next.6 → 2.17.0-next.61

package/dist/spa/src/types/Back.ts

@@ -1,7 +1,7 @@
 import type { Express, Request } from 'express';
 import type { Writable } from 'stream';
 
-import { ActionCheckSource, AdminForthFilterOperators, AdminForthSortDirections, AllowedActionsEnum, 
+import { ActionCheckSource, AdminForthFilterOperators, AdminForthSortDirections, AllowedActionsEnum, AdminForthResourcePages,
   type AdminForthComponentDeclaration, 
   type AdminForthResourceCommon, 
   type AdminUser, type AllowedActionsResolved, 
@@ -12,7 +12,6 @@ import { ActionCheckSource, AdminForthFilterOperators, AdminForthSortDirections,
   type AdminForthComponentDeclarationFull,
   type AdminForthConfigMenuItem,
   type AnnouncementBadgeResponse,
-  AdminForthResourcePages,
   type AdminForthResourceColumnInputCommon,
 } from './Common.js';
 
@@ -129,7 +128,7 @@ export interface IAdminForthSingleFilter {
   operator?: AdminForthFilterOperators.EQ | AdminForthFilterOperators.NE
   | AdminForthFilterOperators.GT | AdminForthFilterOperators.LT | AdminForthFilterOperators.GTE
   | AdminForthFilterOperators.LTE | AdminForthFilterOperators.LIKE | AdminForthFilterOperators.ILIKE
-  | AdminForthFilterOperators.IN | AdminForthFilterOperators.NIN;
+  | AdminForthFilterOperators.IN | AdminForthFilterOperators.NIN | AdminForthFilterOperators.IS_EMPTY | AdminForthFilterOperators.IS_NOT_EMPTY;
   value?: any;
   rightField?: string;
   insecureRawSQL?: string;
@@ -307,7 +306,7 @@ export interface IAdminForthAuth {
 
   removeCustomCookie({response, name}: {response: any, name: string}): void;
 
-  setCustomCookie({response, payload}: {response: any, payload: {name: string, value: string, expiry: number, expirySeconds: number, httpOnly: boolean}}): void;
+  setCustomCookie({response, payload}: {response: any, payload: {name: string, value: string, expiry?: number, expirySeconds: number, httpOnly: boolean}}): void;
 
   getCustomCookie({cookies, name}: {cookies: {key: string, value: string}[], name: string}): string | null;
 
@@ -360,17 +359,16 @@ export interface IAdminForth {
   tr(msg: string, category: string, lang: string, params: any, pluralizationNumber?: number): Promise<string>;
 
   createResourceRecord(
-    params: { resource: AdminForthResource, record: any, adminUser: AdminUser, extra?: HttpExtra }
-  ): Promise<{ error?: string, createdRecord?: any, newRecordId?: any }>;
+    params: CreateResourceRecordParams,
+  ): Promise<CreateResourceRecordResult>;
 
   updateResourceRecord(
-    params: { resource: AdminForthResource, recordId: any, record: any, oldRecord: any, adminUser: AdminUser, extra?: HttpExtra, updates?: never }
-    | { resource: AdminForthResource, recordId: any, record?: never, oldRecord: any, adminUser: AdminUser, extra?: HttpExtra, updates: any }
-  ): Promise<{ error?: string }>;
+    params: UpdateResourceRecordParams,
+  ): Promise<UpdateResourceRecordResult>;
 
   deleteResourceRecord(
-    params: { resource: AdminForthResource, recordId: string, adminUser: AdminUser, record: any, extra?: HttpExtra }
-  ): Promise<{ error?: string }>;
+    params: DeleteResourceRecordParams,
+  ): Promise<DeleteResourceRecordResult>;
 
   auth: IAdminForthAuth;
 
@@ -469,6 +467,13 @@ export interface IAdminForthPlugin {
   instanceUniqueRepresentation(pluginOptions: any) : string;
 
 
+  /**   
+   * If this method returns true, AdminForth will allow only one instance of plugin per whole app
+   * (only for case when we are creating copy of resource and activating plugins)
+   * If false, multiple instances of plugin can be installed on different resources.
+   */
+  shouldHaveSingleInstancePerWholeApp?(): boolean;
+
   /**
    * Optional method which will be called after AdminForth discovers all resources and their columns.
    * Can be used to validate types of columns, check if some columns are missing, etc.
@@ -528,49 +533,347 @@ export interface HttpExtra {
   cookies: Record<string, string>,
   requestUrl: string,
   meta?: any,
+  response: IAdminForthHttpResponse
 }
+
+/**
+ * Result of {@link IAdminForth.createResourceRecord}.
+ */
+export type CreateResourceRecordResult = {
+  /** Optional error message if creation failed. */
+  error?: string;
+
+  /** Created record as returned from the connector. */
+  createdRecord?: any;
+
+  /**
+   * Optional id of an existing record to redirect to
+   * (used when a beforeSave hook aborts creation and supplies newRecordId, allows to implement programmatic creation via API).
+   */
+  newRecordId?: any;
+};
+
+/**
+ * Parameters for {@link IAdminForth.createResourceRecord}.
+ */
+export type CreateResourceRecordParams = {
+  /**
+   * Resource configuration used to create a record.
+   */
+  resource: AdminForthResource;
+
+  /**
+   * Record data to create.
+   */
+  record: any;
+
+  /**
+   * Admin user performing the action.
+   */
+  adminUser: AdminUser;
+
+  /**
+   * HTTP response object.
+   *
+   * @deprecated Since 1.2.9. Will be removed in 2.0.0. Use extra.response instead.
+   */
+  response?: IAdminForthHttpResponse;
+
+  /**
+   * Extra HTTP information. Prefer using extra.response over the top-level response field.
+   */
+  extra?: HttpExtra;
+};
+
+/**
+ * Parameters for {@link IAdminForth.updateResourceRecord}.
+ */
+export type UpdateResourceRecordParams =
+  | {
+      /**
+       * Resource configuration used to update a record.
+       */
+      resource: AdminForthResource;
+
+      /**
+       * Primary key value of the record to update.
+       */
+      recordId: any;
+
+      /**
+       * Full record data with applied changes.
+       *
+       * @deprecated Since 1.2.9. Will be removed in 2.0.0. Use updates instead.
+       */
+      record: any;
+
+      /**
+       * Record data before update.
+       */
+      oldRecord: any;
+
+      /**
+       * Admin user performing the action.
+       */
+      adminUser: AdminUser;
+
+      /**
+       * HTTP response object.
+       *
+       * @deprecated Since 1.2.9. Will be removed in 2.0.0. Use extra.response instead.
+       */
+      response?: IAdminForthHttpResponse;
+
+      /**
+       * Extra HTTP information. Prefer using extra.response over the top-level response field.
+       */
+      extra?: HttpExtra;
+
+      /**
+       * Partial record data with only changed fields. Mutually exclusive with record.
+       */
+      updates?: never;
+    }
+  | {
+      /**
+       * Resource configuration used to update a record.
+       */
+      resource: AdminForthResource;
+
+      /**
+       * Primary key value of the record to update.
+       */
+      recordId: any;
+
+      /**
+       * Full record data with applied changes.
+       *
+       * @deprecated Since 1.2.9. Will be removed in 2.0.0. Use updates instead.
+       */
+      record?: never;
+
+      /**
+       * Record data before update.
+       */
+      oldRecord: any;
+
+      /**
+       * Admin user performing the action.
+       */
+      adminUser: AdminUser;
+
+      /**
+       * HTTP response object.
+       *
+       * @deprecated Since 1.2.9. Will be removed in 2.0.0. Use extra.response instead.
+       */
+      response?: IAdminForthHttpResponse;
+
+      /**
+       * Extra HTTP information. Prefer using extra.response over the top-level response field.
+       */
+      extra?: HttpExtra;
+
+      /**
+       * Partial record data with only changed fields. Mutually exclusive with record.
+       */
+      updates: any;
+    };
+
+/**
+ * Parameters for {@link IAdminForth.deleteResourceRecord}.
+ */
+export type DeleteResourceRecordParams = {
+  /**
+   * Resource configuration used to delete a record.
+   */
+  resource: AdminForthResource;
+
+  /**
+   * Primary key value of the record to delete.
+   */
+  recordId: string;
+
+  /**
+   * Admin user performing the action.
+   */
+  adminUser: AdminUser;
+
+  /**
+   * Record data before deletion.
+   */
+  record: any;
+
+  /**
+   * HTTP response object.
+   *
+   * @deprecated Since 1.2.9. Will be removed in 2.0.0. Use extra.response instead.
+   */
+  response?: IAdminForthHttpResponse;
+
+  /**
+   * Extra HTTP information. Prefer using extra.response over the top-level response field.
+   */
+  extra?: HttpExtra;
+};
+
+/**
+ * Result of {@link IAdminForth.updateResourceRecord}.
+ */
+export type UpdateResourceRecordResult = {
+  /** Optional error message if update failed. */
+  error?: string;
+};
+
+/**
+ * Result of {@link IAdminForth.deleteResourceRecord}.
+ */
+export type DeleteResourceRecordResult = {
+  /** Optional error message if delete failed. */
+  error?: string;
+};
 /**
  * Modify record to change how data is saved to database.
  * Return ok: false and error: string to stop execution and show error message to user. Return ok: true to continue execution.
  */
 export type BeforeDeleteSaveFunction = (params: {
+  /**
+   * Resource info.
+   */
   resource: AdminForthResource, 
+  /**
+   * Primary key value of the record to delete.
+   */
   recordId: any, 
-  adminUser: AdminUser, 
+  /**
+   * Admin user performing the action.
+   */
+  adminUser: AdminUser,
+  /**
+   * Record data before deletion.
+   */
   record: any, 
+  /**
+   * Adminforth instance.
+   */
   adminforth: IAdminForth,
+  /**
+   * HTTP response object.
+   *
+   * @deprecated Since 1.2.9. Will be removed in 2.0.0. Use extra.response instead.
+   */
+  response?: IAdminForthHttpResponse,
+  /**
+   * Extra HTTP information. Prefer using extra.response over the top-level response field.
+   */
   extra?: HttpExtra,
 }) => Promise<{ok: boolean, error?: string}>;
 
 
 export type BeforeEditSaveFunction = (params: {
+    /**
+   * Resource info.
+   */
   resource: AdminForthResource, 
+    /**
+   * Primary key value of the record to delete.
+   */
   recordId: any, 
+    /**
+   * Admin user performing the action.
+   */
   adminUser: AdminUser, 
+  /*
+  * Fields to update in record.
+  */
   updates: any,
+  /** 
+  * Record with updates
+  *
+  *  @deprecated. Will be removed in 2.0.0. Use updates instead.
+  */
   record: any, // legacy, 'updates' should be used instead
+  /**
+   * Record data before update.
+   */
   oldRecord: any,
+  /**
+   * Adminforth instance.
+   */
   adminforth: IAdminForth,
+    /**
+   * HTTP response object.
+   *
+   * @deprecated Since 1.2.9. Will be removed in 2.0.0. Use extra.response instead.
+   */
+  response: IAdminForthHttpResponse,
+    /**
+   * Extra HTTP information. Prefer using extra.response over the top-level response field.
+   */
   extra?: HttpExtra,
 }) => Promise<{ok: boolean, error?: string | null}>;
 
-
-
 export type BeforeCreateSaveFunction = (params: {
+  /**
+   * Resource info.
+   */
   resource: AdminForthResource, 
+  /**
+   * Admin user performing the action.
+   */
   adminUser: AdminUser, 
+  /**
+  * Record data to create.
+  */
   record: any, 
+  /**
+   * Adminforth instance.
+   */
   adminforth: IAdminForth,
+  /**
+   * HTTP response object.
+   *
+   * @deprecated Since 1.2.9. Will be removed in 2.0.0. Use extra.response instead.
+   */
+  response: IAdminForthHttpResponse,
+
   extra?: HttpExtra,
 }) => Promise<{ok: boolean, error?: string | null, newRecordId?: string}>;
 
 export type AfterCreateSaveFunction = (params: {
+    /**
+   * Resource info.
+   */
   resource: AdminForthResource, 
+    /**
+   * Primary key value of the record to delete.
+   */
   recordId: any, 
+    /**
+   * Admin user performing the action.
+   */
   adminUser: AdminUser, 
+  /**
+   * Record data after creation.
+   */
   record: any, 
+    /**
+   * Adminforth instance.
+   */
   adminforth: IAdminForth,
+  /**
+   * Record with virtual columns after creation.
+   */
   recordWithVirtualColumns?: any,
+  /**
+   * HTTP response object.
+   *
+   * @deprecated Since 1.2.9. Will be removed in 2.0.0. Use extra.response instead.
+   */
+  response: IAdminForthHttpResponse,
+    /**
+   * Extra HTTP information. Prefer using extra.response over the top-level response field.
+   */
   extra?: HttpExtra,
 }) => Promise<{ok: boolean, error?: string}>;
 
@@ -579,23 +882,79 @@ export type AfterCreateSaveFunction = (params: {
  * Return ok: false and error: string to stop execution and show error message to user. Return ok: true to continue execution.
  */
 export type AfterDeleteSaveFunction = (params: {
+    /**
+   * Resource info.
+   */
   resource: AdminForthResource, 
+    /**
+   * Primary key value of the record to delete.
+   */
   recordId: any, 
+    /**
+   * Admin user performing the action.
+   */
   adminUser: AdminUser, 
+  /**
+   * Record data, that was deleted.
+   */
   record: any, 
+  /**
+   * Adminforth instance.
+   */
   adminforth: IAdminForth,
+  /**
+   * HTTP response object.
+   *
+   * @deprecated Since 1.2.9. Will be removed in 2.0.0. Use extra.response instead.
+   */
+  response: IAdminForthHttpResponse,
+    /**
+   * Extra HTTP information. Prefer using extra.response over the top-level response field.
+   */
   extra?: HttpExtra,
 }) => Promise<{ok: boolean, error?: string}>;
 
 
 export type AfterEditSaveFunction = (params: {
+    /**
+   * Resource info.
+   */
   resource: AdminForthResource, 
+    /**
+   * Primary key value of the record to delete.
+   */
   recordId: any, 
+    /**
+   * Admin user performing the action.
+   */
   adminUser: AdminUser,
+  /**
+  * Record updates.
+  */
   updates: any, 
+  /** 
+  * Record after update.
+  *
+  *  @deprecated. Will be removed in 2.0.0. Use updates instead.
+  */
   record: any, // legacy, 'updates' should be used instead 
+  /**
+   * Record data before update.
+   */
   oldRecord: any,
+  /**
+   * Adminforth instance.
+   */
   adminforth: IAdminForth,
+  /**
+   * HTTP response object.
+   *
+   * @deprecated Since 1.2.9. Will be removed in 2.0.0. Use extra.response instead.
+   */
+  response: IAdminForthHttpResponse,
+    /**
+   * Extra HTTP information. Prefer using extra.response over the top-level response field.
+   */
   extra?: HttpExtra,
 }) => Promise<{ok: boolean, error?: string}>;
 
@@ -603,10 +962,27 @@ export type AfterEditSaveFunction = (params: {
  * Allow to get user data before login confirmation, will triger when user try to login.
  */
 export type BeforeLoginConfirmationFunction = (params?: { 
+    /**
+   * Admin user performing the action.
+   */
     adminUser: AdminUser,
+    /**
+     * HTTP response object.
+     *
+     * @deprecated Since 1.2.9. Will be removed in 2.0.0. Use extra.response instead.
+     */
     response: IAdminForthHttpResponse,
+    /**
+     * Adminforth instance.
+     */
     adminforth: IAdminForth,
+      /**
+     * Extra HTTP information. Prefer using extra.response over the top-level response field.
+     */
     extra?: HttpExtra,
+      /**
+     * Duration of session in format "1s", "1m", "1h", or "1d" (e.g., "30d" for 30 days)
+     */
     sessionDuration?: string,
 }) => Promise<{
   error?: string, 
@@ -620,9 +996,23 @@ export type BeforeLoginConfirmationFunction = (params?: {
  * Allow to make extra authorization
  */
 export type AdminUserAuthorizeFunction = ((params?: { 
+    /**
+   * Admin user performing the action.
+   */
     adminUser: AdminUser,
+      /**
+     * HTTP response object.
+     *
+     * @deprecated Since 1.2.9. Will be removed in 2.0.0. Use extra.response instead.
+     */
     response: IAdminForthHttpResponse,
+    /**
+     * Adminforth instance.
+     */
     adminforth: IAdminForth,
+      /**
+     * Extra HTTP information. Prefer using extra.response over the top-level response field.
+     */
     extra?: HttpExtra,
 }) => Promise<{
   error?: string,
@@ -848,6 +1238,7 @@ export interface AdminForthActionInput {
   name: string;
   showIn?: {
       list?: boolean,
+      listThreeDotsMenu?: boolean,
       showButton?: boolean,
       showThreeDotsMenu?: boolean,
   };
@@ -861,6 +1252,7 @@ export interface AdminForthActionInput {
       resource: AdminForthResource;
       recordId: string;
       adminUser: AdminUser;
+      response: IAdminForthHttpResponse;
       extra?: HttpExtra;
       tr: Function;
   }) => Promise<{
@@ -1058,7 +1450,7 @@ export interface AdminForthInputConfig {
       /**       
        * Function to return avatar URL for user.
        */
-      avatarUrl?: ((adminUser: AdminUser) => string | Promise<string>)
+      avatarUrl?: ((adminUser: AdminUser) => string | Promise<string> | undefined | Promise<undefined>),
 
       /**
        * Remember me duration for "Remember Me" checkbox on login page.
@@ -1102,7 +1494,7 @@ export interface AdminForthInputConfig {
       /**
        * Add custom page to the settings page
        */
-      userMenuSettingsPages: {
+      userMenuSettingsPages?: {
         icon?: string,
         pageLabel: string,
         slug?: string,
@@ -1282,6 +1674,14 @@ export class Filters {
       subFilters,
     };
   }
+
+  static IS_EMPTY(field: string): IAdminForthSingleFilter {
+    return { field, operator: AdminForthFilterOperators.IS_EMPTY, value: null };
+  }
+
+  static IS_NOT_EMPTY(field: string): IAdminForthSingleFilter {
+    return { field, operator: AdminForthFilterOperators.IS_NOT_EMPTY, value: null };
+  }
 }
 
 export type FDataSort = (field: string, direction: AdminForthSortDirections) => IAdminForthSort;
@@ -1358,6 +1758,7 @@ export type AllowedActions = {
  */
 export interface ResourceOptionsInput extends Omit<NonNullable<AdminForthResourceInputCommon['options']>, 'allowedActions' | 'bulkActions'> {
 
+  baseActionsAsQuickIcons?: ('show' | 'edit' | 'delete')[],
   /** 
    * Custom bulk actions list. Bulk actions available in list view when user selects multiple records by
    * using checkboxes.
@@ -1526,8 +1927,8 @@ export interface AdminForthBulkAction extends AdminForthBulkActionCommon {
    * Callback which will be called on backend when user clicks on action button.
    * It should return Promise which will be resolved when action is done.
    */
-  action: ({ resource, selectedIds, adminUser, tr }: { 
-    resource: AdminForthResource, selectedIds: Array<any>, adminUser: AdminUser, tr: (key: string, category?: string, params?: any) => string
+  action: ({ resource, selectedIds, adminUser, response, tr }: { 
+    resource: AdminForthResource, selectedIds: Array<any>, adminUser: AdminUser, response: IAdminForthHttpResponse, tr: (key: string, category?: string, params?: any) => string
   }) => Promise<{ ok: boolean, error?: string, successMessage?: string }>,
 
   /**

package/dist/spa/src/types/Common.ts

@@ -28,6 +28,8 @@ export enum AdminForthFilterOperators {
   NIN = 'nin',
   AND = 'and',
   OR = 'or',
+  IS_EMPTY = 'isEmpty',
+  IS_NOT_EMPTY = 'isNotEmpty',
 };
 
 export type FilterParams = {
@@ -294,7 +296,7 @@ export interface AdminForthComponentDeclarationFull {
     [key: string]: any,
   }
 }
-import { type AdminForthActionInput } from './Back.js' 
+import { type AdminForthActionInput, type AdminForthResource } from './Back.js' 
 export { type AdminForthActionInput } from './Back.js'
 
 export type AdminForthComponentDeclaration = AdminForthComponentDeclarationFull | string;
@@ -445,7 +447,7 @@ export interface AdminForthResourceInputCommon {
        * If you wish to open page in new tab, add `target=_blank` get param to returned URL, example:
        * 
        * ```ts
-       * listTableClickUrl: async (record, adminUser) => {
+       * listTableClickUrl: async (record, adminUser, resource) => {
        *   return `https://google.com/search?q=${record.name}&target=_blank`;
        * }
        * ```
@@ -455,7 +457,7 @@ export interface AdminForthResourceInputCommon {
        * Example:
        * 
        * ```ts
-       * listTableClickUrl: async (record, adminUser) => {
+       * listTableClickUrl: async (record, adminUser, resource) => {
        *   return null;
        * }
        * ```
@@ -464,7 +466,7 @@ export interface AdminForthResourceInputCommon {
        * @param adminUser - user who clicked
        * @returns 
        */
-      listTableClickUrl?: (record: any, adminUser: AdminUser) => Promise<string | null>,
+      listTableClickUrl?: (record: any, adminUser: AdminUser, resource: AdminForthResource) => Promise<string | null>,
 
       /**
        * Whether to refresh existing list rows automatically every N seconds.
@@ -503,6 +505,7 @@ export interface AdminForthResourceInputCommon {
           bottom?: AdminForthComponentDeclaration | Array<AdminForthComponentDeclaration>,
           threeDotsDropdownItems?: AdminForthComponentDeclaration | Array<AdminForthComponentDeclaration>,
           customActionIcons?: AdminForthComponentDeclaration | Array<AdminForthComponentDeclaration>,
+          customActionIconsThreeDotsMenuItems?: AdminForthComponentDeclaration | Array<AdminForthComponentDeclaration>,
           tableBodyStart?: AdminForthComponentDeclaration | Array<AdminForthComponentDeclaration>,
           tableRowReplace?: AdminForthComponentDeclaration | Array<AdminForthComponentDeclaration>,
         },
@@ -529,11 +532,6 @@ export interface AdminForthResourceInputCommon {
           afterBreadcrumbs?: AdminForthComponentDeclaration | Array<AdminForthComponentDeclaration>,
           bottom?: AdminForthComponentDeclaration | Array<AdminForthComponentDeclaration>,
           threeDotsDropdownItems?: AdminForthComponentDeclaration | Array<AdminForthComponentDeclaration>,
-          /**
-           * Custom Save button component for Edit page.
-           * Accepts props: [record, resource, adminUser, meta, saving, validating, isValid, disabled, saveRecord]
-           */
-          saveButton?: AdminForthComponentDeclaration,
         },
 
         /**
@@ -546,11 +544,6 @@ export interface AdminForthResourceInputCommon {
           afterBreadcrumbs?: AdminForthComponentDeclaration | Array<AdminForthComponentDeclaration>,
           bottom?: AdminForthComponentDeclaration | Array<AdminForthComponentDeclaration>,
           threeDotsDropdownItems?: AdminForthComponentDeclaration | Array<AdminForthComponentDeclaration>,
-          /**
-           * Custom Save button component for Create page.
-           * Accepts props: [record, resource, adminUser, meta, saving, validating, isValid, disabled, saveRecord]
-           */
-          saveButton?: AdminForthComponentDeclaration,
         },
       }
     },