adminforth 2.4.0-next.18 → 2.4.0-next.181

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

@@ -1,4 +1,4 @@
-import type { Express } from 'express';
+import type { Express, Request } from 'express';
 import type { Writable } from 'stream';
 
 import { ActionCheckSource, AdminForthFilterOperators, AdminForthSortDirections, AllowedActionsEnum, 
@@ -8,12 +8,12 @@ import { ActionCheckSource, AdminForthFilterOperators, AdminForthSortDirections,
   type AdminForthBulkActionCommon, 
   type AdminForthForeignResourceCommon,
   type AdminForthResourceColumnCommon,
-  AdminForthResourceInputCommon,
-  AdminForthComponentDeclarationFull,
-  AdminForthConfigMenuItem,
-  AnnouncementBadgeResponse,
+  type AdminForthResourceInputCommon,
+  type AdminForthComponentDeclarationFull,
+  type AdminForthConfigMenuItem,
+  type AnnouncementBadgeResponse,
   AdminForthResourcePages,
-  AdminForthResourceColumnInputCommon,
+  type AdminForthResourceColumnInputCommon,
 } from './Common.js';
 
 export interface ICodeInjector {
@@ -22,7 +22,7 @@ export interface ICodeInjector {
   devServerPort: number;
 
   getServeDir(): string;
-
+  registerCustomComponent(filePath: string): void;
   spaTmpPath(): string;
 }
 
@@ -92,19 +92,36 @@ export interface IExpressHttpServer extends IHttpServer {
    * Adds adminUser to request object if user is authorized. Drops request with 401 status if user is not authorized.
    * @param callable : Function which will be called if user is authorized.
    * 
-   * Example:
    * 
+   * @example
    * ```ts
-   * expressApp.get('/myApi', authorize((req, res) => \{
+   * expressApp.get('/myApi', authorize((req, res) => {
    *  console.log('User is authorized', req.adminUser);
-   *  res.json(\{ message: 'Hello World' \});
-   * \}));
-   * ``
+   *  res.json({ message: 'Hello World' });
+   * }));
+   * ```
    * 
-   */
+   */  
   authorize(callable: Function): void;
 }
 
+export interface ITranslateFunction {
+  (
+    msg: string,
+    category: string,
+    params: any,
+    pluralizationNumber?: number
+  ): Promise<string>;
+}
+
+// Omit <Request, 'param'> is used to remove 'param' method from Request type for correct docs generation
+export interface IAdminUserExpressRequest extends Omit<Request, 'protocol' | 'param' | 'unshift'> {
+  adminUser: AdminUser;
+}
+
+export interface ITranslateExpressRequest extends Omit<Request, 'protocol' | 'param' | 'unshift'> {
+  tr: ITranslateFunction;
+}
 
 export interface IAdminForthSingleFilter {
   field?: string;
@@ -113,7 +130,9 @@ export interface IAdminForthSingleFilter {
   | AdminForthFilterOperators.LTE | AdminForthFilterOperators.LIKE | AdminForthFilterOperators.ILIKE
   | AdminForthFilterOperators.IN | AdminForthFilterOperators.NIN;
   value?: any;
+  rightField?: string;
   insecureRawSQL?: string;
+  insecureRawNoSQL?: any;
 }
 export interface IAdminForthAndOrFilter {
   operator: AdminForthFilterOperators.AND | AdminForthFilterOperators.OR;
@@ -336,7 +355,7 @@ export interface IAdminForth {
 
   createResourceRecord(
     params: { resource: AdminForthResource, record: any, adminUser: AdminUser, extra?: HttpExtra }
-  ): Promise<{ error?: string, createdRecord?: any }>;
+  ): Promise<{ error?: string, createdRecord?: any, newRecordId?: any }>;
 
   updateResourceRecord(
     params: { resource: AdminForthResource, recordId: any, record: any, oldRecord: any, adminUser: AdminUser, extra?: HttpExtra }
@@ -474,7 +493,7 @@ export type BeforeDataSourceRequestFunction = (params: {
     requestUrl: string,
   },
   adminforth: IAdminForth,
-}) => Promise<{ok: boolean, error?: string}>;
+}) => Promise<{ok: boolean, error?: string, newRecordId?: string}>;
 
 /**
  * Modify response to change how data is returned after fetching from database.
@@ -525,7 +544,7 @@ export type BeforeEditSaveFunction = (params: {
   oldRecord: any,
   adminforth: IAdminForth,
   extra?: HttpExtra,
-}) => Promise<{ok: boolean, error?: string}>;
+}) => Promise<{ok: boolean, error?: string | null}>;
 
 
 
@@ -535,7 +554,7 @@ export type BeforeCreateSaveFunction = (params: {
   record: any, 
   adminforth: IAdminForth,
   extra?: HttpExtra,
-}) => Promise<{ok: boolean, error?: string}>;
+}) => Promise<{ok: boolean, error?: string | null, newRecordId?: string}>;
 
 export type AfterCreateSaveFunction = (params: {
   resource: AdminForthResource, 
@@ -619,12 +638,23 @@ interface AdminForthInputConfigCustomization {
    */
   brandName?: string,
 
+  /**
+   * Whether to use single theme for the app
+   */
+  singleTheme?: 'light' | 'dark',
+
   /**
    * Whether to show brand name in sidebar
    * default is true
    */
   showBrandNameInSidebar?: boolean,
 
+  /**
+   * Whether to show brand logo in sidebar
+   * default is true
+   */
+  showBrandLogoInSidebar?: boolean,
+
   /**
    * Path to your app logo
    * 
@@ -638,6 +668,19 @@ interface AdminForthInputConfigCustomization {
    */
   brandLogo?: string,
 
+
+  /**
+   * Path to your app logo for icon only sidebar
+   * 
+   * Example:
+   * Place file `logo.svg` to `./custom` folder and set this option:
+   * 
+   */
+  iconOnlySidebar?: {
+    logo?: string,
+    enabled?: boolean,
+  },
+
   /**
    * Path to your app favicon
    * 
@@ -757,8 +800,19 @@ interface AdminForthInputConfigCustomization {
     userMenu?: AdminForthComponentDeclaration | Array<AdminForthComponentDeclaration>,
     header?: AdminForthComponentDeclaration | Array<AdminForthComponentDeclaration>,
     sidebar?: AdminForthComponentDeclaration | Array<AdminForthComponentDeclaration>,
+    sidebarTop?: AdminForthComponentDeclaration | Array<AdminForthComponentDeclaration>,
     everyPageBottom?: AdminForthComponentDeclaration | Array<AdminForthComponentDeclaration>,
   }
+
+  /**
+  * Allows adding custom elements (e.g., <link>, <script>, <meta>) to the <head> of the HTML document.
+  * Each item must include a tag name and a set of attributes.
+  */
+  customHeadItems?: {
+    tagName: string;
+    attributes: Record<string, string | boolean>;
+  }[];
+
 }
 
 export interface AdminForthActionInput {
@@ -935,6 +989,13 @@ export interface AdminForthInputConfig {
        */
       loginBackgroundPosition?: 'over' | '1/2' | '1/3' | '2/3' | '3/4' | '2/5' | '3/5',
 
+      /**
+       * If true, background blend mode will be removed from login background image when position is 'over'
+       * 
+       * Default: false
+       */
+      removeBackgroundBlendMode?: boolean,
+
       /**
        * Function or functions  which will be called before user try to login.
        * Each function will resive User object as an argument
@@ -956,7 +1017,7 @@ export interface AdminForthInputConfig {
       /**
        * Any prompt to show users on login. Supports HTML.
        */
-      loginPromptHTML?: string,
+      loginPromptHTML?: string | (() => string | void | undefined | Promise<string | void | undefined>) | undefined 
 
       /**
        * Remember me days for "Remember Me" checkbox on login page.
@@ -988,6 +1049,16 @@ export interface AdminForthInputConfig {
        * If you are using Cloudflare, set this to 'CF-Connecting-IP'. Case-insensitive.
        */
       clientIpHeader?: string,
+
+      /**
+       * Add custom page to the settings page
+       */
+      userMenuSettingsPages: {
+        icon?: string,
+        pageLabel: string,
+        slug?: string,
+        component: string
+      }[],
     },
 
      /**
@@ -1062,8 +1133,15 @@ export interface AdminForthConfigCustomization extends Omit<AdminForthInputConfi
     userMenu: Array<AdminForthComponentDeclarationFull>,
     header: Array<AdminForthComponentDeclarationFull>,
     sidebar: Array<AdminForthComponentDeclarationFull>,
+    sidebarTop: Array<AdminForthComponentDeclarationFull>,
     everyPageBottom: Array<AdminForthComponentDeclarationFull>,
   },
+
+  customHeadItems?: {
+    tagName: string;
+    attributes: Record<string, string | boolean>;
+  }[];
+  
 }
 
 export interface AdminForthConfig extends Omit<AdminForthInputConfig, 'customization' | 'resources'> {
@@ -1111,6 +1189,21 @@ export class Filters {
   static LIKE(field: string, value: any): IAdminForthSingleFilter {
     return { field, operator: AdminForthFilterOperators.LIKE, value };
   }
+  static ILIKE(field: string, value: any): IAdminForthSingleFilter {
+    return { field, operator: AdminForthFilterOperators.ILIKE, value };
+  }
+  static GT_FIELD(leftField: string, rightField: string): IAdminForthSingleFilter {
+    return { field: leftField, operator: AdminForthFilterOperators.GT, rightField };
+  }
+  static GTE_FIELD(leftField: string, rightField: string): IAdminForthSingleFilter {
+    return { field: leftField, operator: AdminForthFilterOperators.GTE, rightField };
+  }
+  static LT_FIELD(leftField: string, rightField: string): IAdminForthSingleFilter {
+    return { field: leftField, operator: AdminForthFilterOperators.LT, rightField };
+  }
+  static LTE_FIELD(leftField: string, rightField: string): IAdminForthSingleFilter {
+    return { field: leftField, operator: AdminForthFilterOperators.LTE, rightField };
+  }
   static AND(
     ...args: (IAdminForthSingleFilter | IAdminForthAndOrFilter | Array<IAdminForthSingleFilter | IAdminForthAndOrFilter>)[]
   ): IAdminForthAndOrFilter {
@@ -1318,9 +1411,13 @@ export interface AdminForthResource extends Omit<AdminForthResourceInput, 'optio
     },
     create?: {
       /**
+       * Should return `ok: true` to continue saving pipeline and allow creating record in database, and `ok: false` to interrupt pipeline and prevent record creation.
+       * If you need to show error on UI, set `error: \<error message\>` in response.
+       * 
        * Typical use-cases:
-       * - Validate record before saving to database and interrupt execution if validation failed (`allowedActions.create` should be preferred in most cases)
-       * - fill-in adminUser as creator of record
+       * - Create record by custom code (return `{ ok: false, newRecordId: <id of created record from custom code> }`)
+       * - Validate record before saving to database and interrupt execution if validation failed (return `{ ok: false, error: <validation error> }`), though `allowedActions.create` should be preferred in most cases
+       * - fill-in adminUser as creator of record (set `record.<some field> = x; return \{ ok: true \}`) 
        * - Attach additional data to record before saving to database (mostly fillOnCreate should be used instead)
        */
       beforeSave?: Array<BeforeCreateSaveFunction>,
@@ -1471,15 +1568,27 @@ export type ShowInInput = ShowInModernInput | ShowInLegacyInput;
 export type ShowIn = {
   [key in AdminForthResourcePages]: AllowedActionValue
 }
+export type BackendOnlyInput =
+  | boolean
+  | ((p: {
+      adminUser: AdminUser;
+      resource: AdminForthResource;
+      meta: any;
+      source: ActionCheckSource;
+      adminforth: IAdminForth;
+    }) => boolean | Promise<boolean>);
+
 
-export interface AdminForthResourceColumnInput extends Omit<AdminForthResourceColumnInputCommon, 'showIn'> {
+export interface AdminForthResourceColumnInput extends Omit<AdminForthResourceColumnInputCommon, 'showIn' | 'backendOnly'> {
   showIn?: ShowInInput,
   foreignResource?: AdminForthForeignResource,
+  backendOnly?: BackendOnlyInput;
 }
 
-export interface AdminForthResourceColumn extends Omit<AdminForthResourceColumnCommon, 'showIn'> {
+export interface AdminForthResourceColumn extends Omit<AdminForthResourceColumnCommon, 'showIn' | 'backendOnly'> {
   showIn?: ShowIn,
   foreignResource?: AdminForthForeignResource,
+  backendOnly?: BackendOnlyInput;
 }
 
 export interface IWebSocketClient {

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

@@ -1,4 +1,3 @@
-
 /**
  * Types that are common for both frontend side (SPA) and backend side (server).
  */
@@ -95,12 +94,9 @@ export interface AdminForthBulkActionCommon {
   label: string,
 
   /**
-   * Bulk Action button state 'danger'|success|'active',
-   *  * 'danger' - red button
-   *  * 'success' - green button
-   *  * 'active' - blue button
+   * Add custom class
    **/ 
-  state?: 'danger' | 'success' | 'active';
+  buttonCustomCssClass?: string;
 
   /** 
    * Optional small badge for button which will be displayed in the list view
@@ -122,6 +118,10 @@ export interface AdminForthBulkActionCommon {
    */
   successMessage?: string,
 
+  /**
+   * Show in three dots dropdown menu in list view.
+   */
+  showInThreeDotsDropdown?: boolean,
 }
 
 export interface AdminForthFieldComponents {
@@ -261,11 +261,29 @@ export interface AdminForthComponentDeclarationFull {
    * </script>
    * 
    */
-  meta?: any,
+  meta?: {
+    /**
+     * Controls sidebar and header visibility for custom pages
+     * - 'default': Show both sidebar and header (default behavior)
+     * - 'none': Hide both sidebar and header (full custom layout)
+     * - 'preferIconOnly': Show header but prefer icon-only sidebar
+     */
+    sidebarAndHeader?: 'default' | 'none' | 'preferIconOnly',
+    
+    [key: string]: any,
+  }
 }
+import { type AdminForthActionInput } from './Back.js' 
+export { type AdminForthActionInput } from './Back.js'
 
 export type AdminForthComponentDeclaration = AdminForthComponentDeclarationFull | string;
 
+export type FieldGroup = {
+  groupName: string;
+  columns: string[];
+  noTitle?: boolean;
+};
+
 /**
  * Resource describes one table or collection in database.
  * AdminForth generates set of pages for 'list', 'show', 'edit', 'create', 'filter' operations for each resource.
@@ -347,6 +365,11 @@ export interface AdminForthResourceInputCommon {
         direction: AdminForthSortDirections | string,
       }
 
+      /*
+       * Custom actions list. Actions available in show, edit and create views. 
+       */
+      actions?: AdminForthActionInput[],
+      
       /** 
        * Custom bulk actions list. Bulk actions available in list view when user selects multiple records by
        * using checkboxes.
@@ -374,26 +397,10 @@ export interface AdminForthResourceInputCommon {
       /** 
        * Allows to make groups of columns in show, create and edit resource pages.
        */
-      fieldGroups?: {
-        groupName: string;
-        columns: string[];
-        noTitle?: boolean;
-      }[];
-      createFieldGroups?: {
-        groupName: string;
-        columns: string[];
-        noTitle?: boolean;
-      }[];
-      editFieldGroups?: {
-        groupName: string;
-        columns: string[];
-        noTitle?: boolean;
-      }[];
-      showFieldGroups?: {
-        groupName: string;
-        columns: string[];
-        noTitle?: boolean;
-      }[];
+      fieldGroups?: FieldGroup[];
+      createFieldGroups?: FieldGroup[];
+      editFieldGroups?: FieldGroup[];
+      showFieldGroups?: FieldGroup[];
 
       /** 
        * Page size for list view
@@ -471,6 +478,7 @@ export interface AdminForthResourceInputCommon {
         list?: {
           beforeBreadcrumbs?: AdminForthComponentDeclaration | Array<AdminForthComponentDeclaration>,
           afterBreadcrumbs?: AdminForthComponentDeclaration | Array<AdminForthComponentDeclaration>,
+          beforeActionButtons?: AdminForthComponentDeclaration | Array<AdminForthComponentDeclaration>,
           bottom?: AdminForthComponentDeclaration | Array<AdminForthComponentDeclaration>,
           threeDotsDropdownItems?: AdminForthComponentDeclaration | Array<AdminForthComponentDeclaration>,
           customActionIcons?: AdminForthComponentDeclaration | Array<AdminForthComponentDeclaration>,
@@ -584,6 +592,8 @@ export interface AdminForthForeignResourceCommon {
   polymorphicResources?: Array<AdminForthPolymorphicForeignResource>,
   polymorphicOn?: string,
   unsetLabel?: string,
+  searchableFields?: string | string[],
+  searchIsCaseSensitive?: boolean,
 }
 
 export type FillOnCreateFunction = (params: {
@@ -810,9 +820,6 @@ export interface AdminForthResourceColumnInputCommon {
    */
   minLength?: number,
 
-  min?: number,
-  max?: number,
-
   /**
    * Minimum value that can be entered in this field.
    */
@@ -878,6 +885,15 @@ export interface AdminForthResourceColumnCommon extends AdminForthResourceColumn
 
   editingNote?: { create?: string, edit?: string },
 
+  /**
+   * Minimal value stored in this field.
+   */
+  min?: number,
+
+  /**
+   * Maximum value stored in this field.
+   */
+  max?: number,
 }
 
 export enum AdminForthMenuTypes {
@@ -1055,16 +1071,23 @@ export interface AdminForthConfigForFrontend {
   usernameFieldName: string,
   loginBackgroundImage: string,
   loginBackgroundPosition: string,
+  removeBackgroundBlendMode: boolean,
   title?: string,
   demoCredentials?: string,
-  loginPromptHTML?: string,
+  loginPromptHTML?: string | (() => string | Promise<string> | void | Promise<void> | Promise<undefined>) | undefined 
   loginPageInjections: {
     underInputs: Array<AdminForthComponentDeclaration>,
     panelHeader: Array<AdminForthComponentDeclaration>,
   },
   rememberMeDays: number,
   showBrandNameInSidebar: boolean,
+  showBrandLogoInSidebar: boolean,
   brandLogo?: string,
+  iconOnlySidebar?: { 
+    logo?: string,
+    enabled?: boolean,
+  },
+  singleTheme?: 'light' | 'dark',
   datesFormat: string,
   timeFormat: string,
   auth: any,
@@ -1079,8 +1102,19 @@ export interface AdminForthConfigForFrontend {
     userMenu: Array<AdminForthComponentDeclarationFull>,
     header: Array<AdminForthComponentDeclarationFull>,
     sidebar: Array<AdminForthComponentDeclarationFull>,
+    sidebarTop: Array<AdminForthComponentDeclarationFull>,
     everyPageBottom: Array<AdminForthComponentDeclarationFull>,
-  }
+  },
+  customHeadItems?: {
+    tagName: string;
+    attributes: Record<string, string | boolean>;
+  }[],
+  settingPages?:{
+    icon?: string,
+    pageLabel: string,
+    slug?: string,
+    component: string,
+  }[],
 }
 
 export interface GetBaseConfigResponse {

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

@@ -55,7 +55,7 @@ export interface FrontendAPIInterface {
      * 
      * @param params - The parameters of the alert
      */
-    alert(params:AlertParams): void;
+    alert(params:AlertParams): void | Promise<string> | string;
 
 
     list: {
@@ -82,27 +82,40 @@ export interface FrontendAPIInterface {
          */
         closeThreeDotsDropdown(): void;
 
-
         /**
-         * Set a filter in the list
-         * Works only when user located on the list page.
+         * Set a filter in the list.
+         * Works only when user located on the list page. If filter already exists, it will be replaced with the new one.
          * Can be used to set filter from charts or other components in pageInjections.
          * 
+         * Filters are automatically marked as hidden (won't count in badge) if:
+         * - Column has showIn.filter: false
+         * 
          * Example:
          * 
          * ```ts
          * import adminforth from '@/adminforth'
          * 
+         * // Regular filter (will show in badge if column.showIn.filter !== false)
          * adminforth.list.setFilter({field: 'name', operator: 'ilike', value: 'john'})
+         * 
+         * // Hidden filter (won't show in badge if column.showIn.filter === false)
+         * adminforth.list.setFilter({field: 'internal_status', operator: 'eq', value: 'active'})
          * ```
          * 
+         * Please note that you can set/update filter even for fields which have showIn.filter=false in resource configuration.
+         * Also you can set filter for virtual columns. For example Universal search plugin calls updateFilter for virtual column which has showIn.filter=false (because we dont want to show this column in filter dropdown, plugin renders its own filter UI)
+         * 
          * @param filter - The filter to set
          */
         setFilter(filter: FilterParams): void;
 
         /**
+         * DEPRECATED: does the same as setFilter, kept for backward compatibility
          * Update a filter in the list
          * 
+         * Filters visibility in badge is automatically determined by column configuration:
+         * - Hidden if column has showIn.filter: false
+         * 
          * Example:
          * 
          * ```ts
@@ -121,6 +134,14 @@ export interface FrontendAPIInterface {
         clearFilters(): void;
     }
 
+    show: {
+        /**
+         * Full refresh the current record on the show page. Loader may be shown during fetching.
+         * Fire-and-forget; you don't need to await it.
+         */
+        refresh(): void;
+    }
+
     menu: {
         /**
          * Refreshes the badges in the menu, by recalling the badge function for each menu item
@@ -171,7 +192,12 @@ export type AlertParams = {
      * Default is 10 seconds;
      */
     timeout?: number | 'unlimited';
-    
+
+    /**
+     * Optional buttons to display in the alert
+     */
+    buttons?: {value: any, label: string}[];
+
 }
 
 

package/dist/spa/src/types/adapters/CaptchaAdapter.ts

@@ -0,0 +1,35 @@
+/**
+ * Interface for Captcha adapters.
+ */
+
+export interface CaptchaAdapter {
+    /**
+     * Returns the script source URL for the captcha widget.
+     */
+    getScriptSrc(): string;
+
+    /**
+     * Returns the site key for the captcha.
+     */
+    getSiteKey(): string;
+
+    /**
+     * Returns the widget ID for the captcha.
+     */
+    getWidgetId(): string;
+
+    /**
+     * Returns the token for the captcha.
+     */
+    getToken(): Promise<string> | string;
+
+    /**
+     * Renders the captcha widget HTML.
+     */
+    renderWidget(): void;
+
+    /**
+     * Validates the captcha token.
+     */
+    validate(token: string, ip: string): Promise<Record<string, any>>;
+}

package/dist/spa/src/types/adapters/CompletionAdapter.ts

@@ -0,0 +1,25 @@
+export interface CompletionAdapter {
+
+  /**
+   * This method is called to validate the configuration of the adapter
+   * and should throw a clear user-readbale error if the configuration is invalid.
+   */
+  validate(): void;
+
+  /**
+   * This method should return a text completion based on the provided content and stop sequence.
+   * @param content - The input text to complete
+   * @param stop - An array of stop sequences to indicate where to stop the completion
+   * @param maxTokens - The maximum number of tokens to generate
+   * @returns A promise that resolves to an object containing the completed text and other metadata
+   */
+  complete(
+    content: string,
+    stop: string[],
+    maxTokens: number,
+  ): Promise<{
+    content?: string;
+    finishReason?: string;
+    error?: string;
+  }>;
+}

package/dist/spa/src/types/adapters/EmailAdapter.ts

@@ -0,0 +1,27 @@
+export interface EmailAdapter {
+
+  /**
+   * This method is called to validate the configuration of the adapter
+   * and should throw a clear user-readable error if the configuration is invalid.
+   */
+  validate(): Promise<void>;
+
+  /**
+   * This method should send an email using the adapter
+   * @param from - The sender's email address
+   * @param to - The recipient's email address
+   * @param text - The plain text version of the email
+   * @param html - The HTML version of the email
+   * @param subject - The subject of the email
+   */
+  sendEmail(
+    from: string,
+    to: string,
+    text: string,
+    html: string,
+    subject: string
+  ): Promise<{
+    error?: string;
+    ok?: boolean;
+  }>;
+}