adminforth 2.4.0-next.33 → 2.4.0-next.331

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

@@ -1,4 +1,3 @@
-
 /**
  * Types that are common for both frontend side (SPA) and backend side (server).
  */
@@ -31,6 +30,21 @@ export enum AdminForthFilterOperators {
   OR = 'or',
 };
 
+export type FilterParams = {
+    /**
+     * Field of resource to filter
+     */
+    field: string;
+    /**
+     * Operator of filter
+     */
+    operator: AdminForthFilterOperators;
+    /**
+     * Value of filter
+     */
+    value: string | number | boolean ;
+} 
+
 export enum AdminForthSortDirections {
   asc = 'asc',
   desc = 'desc',
@@ -68,6 +82,11 @@ export type AllowedActionsResolved = {
   [key in AllowedActionsEnum]: boolean
 }
 
+// conditional operators for predicates
+type Value = any;
+type Operators = { $eq: Value } | { $not: Value } | { $gt: Value } | { $gte: Value } | { $lt: Value } | { $lte: Value } | { $in: Value[] } | { $nin: Value[] } | { $includes: Value } | { $nincludes: Value };
+export type Predicate = { $and: Predicate[] } | { $or: Predicate[] } | { [key: string]: Operators | Value };
+
 export interface AdminUser {
   /**
    * primaryKey field value of user in table which is defined by {@link AdminForthConfig.auth.usersResourceId}
@@ -95,12 +114,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 +138,10 @@ export interface AdminForthBulkActionCommon {
    */
   successMessage?: string,
 
+  /**
+   * Show in three dots dropdown menu in list view.
+   */
+  showInThreeDotsDropdown?: boolean,
 }
 
 export interface AdminForthFieldComponents {
@@ -261,11 +281,30 @@ 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
+     * - 'headerOnly': Show only header (full custom layout)
+     */
+    sidebarAndHeader?: 'default' | 'none' | 'preferIconOnly' | 'headerOnly',
+    
+    [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 +386,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 +418,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 +499,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>,
@@ -499,6 +528,11 @@ 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,
         },
 
         /**
@@ -511,6 +545,11 @@ 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,
         },
       }
     },
@@ -584,6 +623,8 @@ export interface AdminForthForeignResourceCommon {
   polymorphicResources?: Array<AdminForthPolymorphicForeignResource>,
   polymorphicOn?: string,
   unsetLabel?: string,
+  searchableFields?: string | string[],
+  searchIsCaseSensitive?: boolean,
 }
 
 export type FillOnCreateFunction = (params: {
@@ -810,9 +851,6 @@ export interface AdminForthResourceColumnInputCommon {
    */
   minLength?: number,
 
-  min?: number,
-  max?: number,
-
   /**
    * Minimum value that can be entered in this field.
    */
@@ -865,6 +903,15 @@ export interface AdminForthResourceColumnInputCommon {
    */
   masked?: boolean,
 
+  /**
+   * Sticky position for column
+   */
+  listSticky?: boolean;
+
+  /**
+   * Show field only if certain conditions are met.
+   */
+  showIf?: Predicate;
 }
 
 export interface AdminForthResourceColumnCommon extends AdminForthResourceColumnInputCommon {
@@ -878,6 +925,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 +1111,24 @@ 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,
+    expandedSidebarWidth?: string,
+  },
+  singleTheme?: 'light' | 'dark',
   datesFormat: string,
   timeFormat: string,
   auth: any,
@@ -1079,8 +1143,21 @@ 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>;
+    innerCode?: string;
+  }[],
+  settingPages?:{
+    icon?: string,
+    pageLabel: string,
+    slug?: string,
+    component: string,
+    isVisible?: boolean
+  }[],
 }
 
 export interface GetBaseConfigResponse {

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

@@ -1,21 +1,4 @@
-import type { AdminForthFilterOperators } from "./Common.js";
-
- 
-
-export type FilterParams = {
-    /**
-     * Field of resource to filter
-     */
-    field: string;
-    /**
-     * Operator of filter
-     */
-    operator: AdminForthFilterOperators;
-    /**
-     * Value of filter
-     */
-    value: string | number | boolean ;
-} 
+import type { AdminForthFilterOperators, FilterParams } from "./Common.js";
 
 export interface FrontendAPIInterface {
 
@@ -55,7 +38,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 +65,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 +117,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 +175,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,34 @@
+/**
+ * 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 script HTML for the captcha widget.
+     */
+    getRenderWidgetCode(): string;
+
+    /**
+     * Returns the function name to render the captcha widget.
+     */
+    getRenderWidgetFunctionName(): string;
+    /**
+     * Validates the captcha token.
+     */
+    validate(token: string, ip: string): Promise<Record<string, any>>;
+}

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

@@ -1,8 +1,8 @@
-interface EmailAdapter {
+export interface EmailAdapter {
 
   /**
    * This method is called to validate the configuration of the adapter
-   * and should throw a clear user-readbale error if the configuration is invalid.
+   * and should throw a clear user-readable error if the configuration is invalid.
    */
   validate(): Promise<void>;
 
@@ -25,5 +25,3 @@ interface EmailAdapter {
     ok?: boolean;
   }>;
 }
-
-export { EmailAdapter };

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

@@ -0,0 +1,30 @@
+export interface ImageVisionAdapter {
+
+  /**
+   * 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(): void;
+
+  /**
+   * Input file extension supported
+   */
+  inputFileExtensionSupported(): string[];
+
+  /**
+   * This method should generate an image based on the provided prompt and input files.
+   * @param prompt - The prompt to generate the image
+   * @param inputFileUrls - An array of input file paths (optional)
+   * @returns A promise that resolves to an object containing the generated image  and any error message
+   */
+  generate({
+    prompt, 
+    inputFileUrls,
+  }: {
+    prompt: string,
+    inputFileUrls: string[],
+  }): Promise<{
+    response: string;
+    error?: string;
+  }>;
+}

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

@@ -0,0 +1,16 @@
+
+/**
+ * Might have implementations like RAM, Redis, Memcached,
+ * 
+ */
+export interface KeyValueAdapter {
+
+  get(key: string): Promise<string | null>;
+  
+  set(key: string, value: string, expiresInSeconds?: number): Promise<void>;
+
+  delete(key: string): Promise<void>;
+
+}
+
+  

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

@@ -39,7 +39,8 @@ export interface StorageAdapter {
    * This method should work even if the file does not exist yet (e.g. only presigned URL was generated).
    * @param key - The key of the file to be uploaded e.g. "uploads/file.txt"
    */
-  markKeyForDeletation(key: string): Promise<void>;
+  markKeyForDeletation(key: string): Promise<void>; //TODO delete after one year
+  markKeyForDeletion(key: string): Promise<void>;
 
 
   /**
@@ -47,7 +48,8 @@ export interface StorageAdapter {
    * This method should be used to cancel the deletion of the file if it was marked for deletion.
    * @param key - The key of the file to be uploaded e.g. "uploads/file.txt"
    */
-  markKeyForNotDeletation(key: string): Promise<void>;
+  markKeyForNotDeletation(key: string): Promise<void>; //TODO delete after one year
+  markKeyForNotDeletion(key: string): Promise<void>;
 
 
   /**

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

@@ -1,5 +1,8 @@
 export type { EmailAdapter } from './EmailAdapter.js';
 export type { CompletionAdapter } from './CompletionAdapter.js';
 export type { ImageGenerationAdapter } from './ImageGenerationAdapter.js';
+export type { KeyValueAdapter } from './KeyValueAdapter.js';
+export type { ImageVisionAdapter } from './ImageVisionAdapter.js';
 export type { OAuth2Adapter } from './OAuth2Adapter.js';
 export type { StorageAdapter } from './StorageAdapter.js';
+export type { CaptchaAdapter } from './CaptchaAdapter.js';