adminforth 1.0.83 → 1.0.86

package/types/AdminForthConfig.ts

@@ -1,13 +1,89 @@
+import { Express } from 'express';
 
-
-export interface CodeInjector {
+export interface CodeInjectorType {
   srcFoldersToSync: Object;
   allComponentNames: Object;
 }
 
+/**
+ * Implement this interface to create custom HTTP server adapter for AdminForth.
+ */
+export interface GenericHttpServer {
+
+  // constructor(adminforth: AdminForthClass): void;
+
+  /**
+   * Sets up HTTP server to serve AdminForth SPA.
+   * if hotReload is true, it should proxy all requests and headers to Vite dev server at `http://localhost:5173$\{req.url\}`
+   * otherwise it should serve AdminForth SPA from dist folder. See Express for example.
+   */
+  setupSpaServer(): void;
+
+}
+
+export interface ExpressHttpServer extends GenericHttpServer {
+
+  /**
+   * Call this method to serve AdminForth SPA from Express instance.
+   * @param app : Express instance
+   */
+  serve(app: Express): void;
+
+  /**
+   * Method (middleware) to wrap express endpoints with authorization check.
+   * 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:
+   * 
+   * ```ts
+   * expressApp.get('/myApi', authorize((req, res) => \{
+   *  console.log('User is authorized', req.adminUser);
+   *  res.json(\{ message: 'Hello World' \});
+   * \}));
+   * ``
+   * 
+   */
+  authorize(callable: Function): void;
+}
+
+
 export interface AdminForthClass {
   config: AdminForthConfig;
-  codeInjector: CodeInjector;
+  codeInjector: CodeInjectorType;
+  express: GenericHttpServer;
+
+  auth: {
+
+    verify(jwt : string): any;
+  }
+
+  /**
+   * Internal flag which indicates if AdminForth is running in hot reload mode.
+   */
+  runningHotReload: boolean;
+
+
+  /**
+   * Connects to databases defined in datasources and fetches described resource columns to find out data types and constraints.
+   * You must call this method as soon as possible after AdminForth class is instantiated.
+   */
+  discoverDatabases(): Promise<void>;
+
+  /**
+   * Bundles AdminForth SPA by injecting custom components into internal pre-made SPA source code. It generates internally dist which then will be
+   * served by AdminForth HTTP adapter.
+   * Bundle is generated in /tmp folder so if you have ramfs or tmpfs this operation will be faster.
+   * 
+   * We recommend calling this method from dedicated script which will be run by CI/CD pipeline in build time. This ensures lowest downtime for your users.
+   * However for simple setup you can call it from your main script, and users will see some "AdminForth is bundling" message in the admin panel while app is bundling.
+   */
+  bundleNow({ hotReload, verbose }: { hotReload: boolean, verbose: boolean }): Promise<void>;
+
+  /**
+   * This method will be automatically called from AdminForth HTTP adapter to serve AdminForth SPA.
+   */
+  setupEndpoints(server: GenericHttpServer): void;
 }
 
 
@@ -19,49 +95,285 @@ export interface AdminForthPluginType {
   componentPath(componentFile: string): string;
 }
 
+export enum AdminForthMenuTypes {
+  /**
+   * HEADING is just a label in the menu.
+   * Respect `label` and `icon` property in {@link AdminForthConfigMenuItem}
+   */
+  heading = 'heading',
+
+  /**
+   * GROUP is a group of menu items.
+   * Respects `label`, `icon` and `children` properties in {@link AdminForthConfigMenuItem}
+   * use @AdminForthMenuTypes.open to set if group is open by default
+   */
+  group = 'group',
+
+  /**
+   * RESOURCE is a link to a resource.
+   * Respects `label`, `icon`,  `resourceId`, `homepage`, `isStaticRoute` properties in {@link AdminForthConfigMenuItem}
+   */
+  resource = 'resource',
+
+  /**
+   * PAGE is a link to a custom page.
+   * Respects `label`, `icon`, `path`, `component`, `homepage`, `isStaticRoute`, properties in {@link AdminForthConfigMenuItem}
+   * 
+   * Example:
+   * 
+   * ```ts
+   * \{
+   *  type: AdminForthMenuTypes.PAGE,
+   *  label: 'Custom Page',
+   *  icon: 'home',
+   *  path: '/dash',
+   *  component: '@@/Dashboard.vue',
+   *  homepage: true,
+   * \}
+   * ```
+   * 
+   */
+  page = 'page',
+
+  /**
+   * GAP ads some space between menu items.
+   */
+  gap = 'gap',
+
+  /**
+   * DIVIDER is a divider between menu items.
+   */
+  divider = 'divider',
+}
+
+export enum AdminForthResourcePages {
+  list = 'list',
+  show = 'show',
+  edit = 'edit',
+  create = 'create',
+  filter = 'filter',
+}
+
+
+/**
+ * Menu item which displayed in the left sidebar of the admin panel.
+ */
 export type AdminForthConfigMenuItem = {
-    type?: 'heading' | 'group' | 'resource' | 'page' | 'gap' | 'divider',
+    type?: AdminForthMenuTypes | keyof typeof AdminForthMenuTypes,
+
+    /**
+     * Label for menu item which will be displayed in the admin panel.
+     */
     label?: string,
+
+    /**
+     * Icon for menu item which will be displayed in the admin panel.
+     * Supports iconify icons in format `<icon set name>:<icon name>`
+     * Browse available icons here: https://icon-sets.iconify.design/
+     * 
+     * Example:
+     * 
+     * ```ts
+     * icon: 'flowbite:brain-solid', 
+     * ```
+     * 
+     */
     icon?: string,
+
+    /**
+     * Path to custom component which will be displayed in the admin panel.
+     * 
+     */
     path?: string,
+
+    /**
+     * Component to be used for this menu item. Component should be placed in custom folder and referenced with `@@/` prefix.
+     * Supported for AdminForthMenuTypes.PAGE only!
+     * Example:
+     * 
+     * ```ts
+     * component: '@@/Dashboard.vue',
+     * ```
+     * 
+     */
     component?: string,
+
+    /**
+     * Resource ID which will be used to fetch data from.
+     * Supported for AdminForthMenuTypes.RESOURCE only!
+     * 
+     */
     resourceId?: string,
+
+    /**
+     * If true, group will be open by default after user login to the admin panel.
+     * Also will be used to redirect from root path.
+     */
     homepage?: boolean,
+
+    /**
+     * Where Group is open by default
+     * Supported for AdminForthMenuTypes.GROUP only!
+     * 
+     */    
     open?: boolean,
+
+    /**
+     * Children menu items which will be displayed in this group.
+     * Supported for AdminForthMenuTypes.GROUP only!
+     */
     children?: Array<AdminForthConfigMenuItem>,
+
+    /**
+     * By default all pages are imported dynamically with lazy import().
+     * If you wish to import page statically, set this option to true.
+     * Homepage will be imported statically by default. but you can override it with this option.
+     */
     isStaticRoute?: boolean,
+
     meta?: {
       title?: string,
     },
   }
   
-  
+
+/**
+ * Column describes one field in the table or collection in database.
+ */
 export type AdminForthResourceColumn = {
+    /**
+     * Column name in database.
+     */
     name: string,
+
+    /**
+     * How column can be labled in the admin panel.
+     * Use it for renaming columns. Defaulted to column name with Uppercased first letter.
+     */
     label?: string,
+
+    /**
+     * Type of data in column.
+     * AdminForth will use this information to render proper input fields in the admin panel.
+     * AdminForth tries to guess type of data from database column type automatically for typed databases like SQL-based.
+     * However you can explicitly set it to any value. E.g. set AdminForthDataTypes.DATETIME for your string column in SQLite, which stores ISO date strings.
+     */
     type?: AdminForthDataTypes,
+
+    /**
+     * Whether to use this column as record identifier.
+     * Only one column can be primary key.
+     * AdminForth tries to guess primary key automatically first.
+     */
     primaryKey?: boolean,
-    required?: boolean | { create: boolean, edit: boolean },
-    editingNote?: string | { create: string, edit: string },
-    showIn?: Array<string>,
+
+    /**
+     * Whether AdminForth will require this field to be filled in create and edit forms.
+     * Can be set to boolean or object with create and edit properties.
+     * If boolean, it will be used for both create and edit forms.
+     */
+    required?: boolean | { create?: boolean, edit?: boolean },
+
+    /**
+     * Whether AdminForth will show editing note near the field in edit/create form.
+     */
+    editingNote?: string | { create?: string, edit?: string },
+
+    /**
+     * On which AdminForth pages this field will be shown. By default all.
+     * Example: if you want to show field only in create and edit pages, set it to 
+     * 
+     * ```ts
+     * showIn: [AdminForthResourcePages.CREATE, AdminForthResourcePages.EDIT]
+     * ```
+     * 
+     */
+    showIn?: Array<AdminForthResourcePages | keyof typeof AdminForthResourcePages>,
+
+    /**
+     * Whether AdminForth will show this field in show view.
+     */
     fillOnCreate?: Function,
+
+    /**
+     * Whether AdminForth will request user to enter unique value during creating or editing record.
+     * This option causes AdminForth to make a request to database to check if value is unique. 
+     * (Constraints are not used, so for large-tables performance make sure you have unique index in database if you set this option to true)
+     */
     isUnique?: boolean,
+
+
+    /**
+     * Runtime validation Regexp rules for this field.
+     */
     validation?: Array<ValidationObject>,
+
+    /**
+     * Allows to make the field which does not exist in database table.
+     * Examples: add custom show field with user country flag:
+     * 
+     * ```ts
+     * {
+     *  label: 'Country',
+     *  type: AdminForthDataTypes.STRING,
+     *  virtual: true,
+     *  showIn: [AdminForthResourcePages.SHOW, AdminForthResourcePages.LIST],
+     *  components: {
+     *    show: '@@/CountryFlag.vue',
+     *    list: '@@/CountryFlag.vue',
+     *   },
+     * }
+     * ```
+     * 
+     * This field will be displayed in show and list views with custom component `CountryFlag.vue`. CountryFlag.vue should be placed in custom folder and can be next:
+     * 
+     * ```vue
+     * <template>
+     *  {{ getFlagEmojiFromIso(record.ipCountry) }}
+     * </template>
+     * 
+     * <script setup>
+     * const props = defineProps(['record']);
+     * 
+     * function getFlagEmojiFromIso(iso) {
+     *    return iso.toUpperCase().replace(/./g, (char) => String.fromCodePoint(char.charCodeAt(0) + 127397));
+     * }
+     * </script>
+     * ```
+     * 
+     */
     virtual?: boolean,
+
+    /**
+     * Whether AdminForth will show this field in list view.
+     */
     allowMinMaxQuery?: boolean,
-    component?: AdminForthResourceColumnComponent
+
+    /**
+     * Custom components which will be used to render this field in the admin panel.
+     */
+    components?: AdminForthFieldComponents
     maxLength?: number, 
     minLength?: number,
     min?: number,
     max?: number,
     minValue?: number,
     maxValue?: number,
-    enum?: Array<AdminForthResourceColumnEnumElement>,
-    foreignResource?:AdminForthResourceColumnForeignResource,
+    enum?: Array<AdminForthColumnEnumItem>,
+    foreignResource?:AdminForthForeignResource,
     sortable?: boolean,
     backendOnly?: boolean, // if true field will not be passed to UI under no circumstances, but will be presented in hooks
-  } 
+
+    /**
+     * Masked fields will be displayed as `*****` on Edit and Create pages.
+     */
+    masked?: boolean,
+}
   
+/**
+ * Resource describes one table or collection in database.
+ * AdminForth generates set of pages for 'list', 'show', 'edit', 'create', 'filter' operations for each resource.
+ */
 export type AdminForthResource = {
     /**
      * Unique identifier of resource. By default it equals to table name in database. 
@@ -92,28 +404,23 @@ export type AdminForthResource = {
      */
     columns: Array<AdminForthResourceColumn>,
 
+    
     dataSourceColumns?: Array<AdminForthResourceColumn>,  // TODO, mark as private
 
     /**
-     * Hook which allow you to modify item label
+     * Hook which allow you to modify record label
      * 
      * Example:
      * 
      * ```ts
-     * itemLabel: (item) => `${item.name} - ${item.id}`,
+     * recordLabel: (record) => `${record.name} - ${record.id}`,
      * ```
      * 
      */
-    itemLabel?: Function,
+    recordLabel?: Function,
 
     /**
-     * Hook which allow you to modify item title
-     * 
-     * Example:
-     * 
-     * ```ts
-     * itemTitle: (item) => `${item.name} - ${item.id}`,
-     * ```
+     * Array of plugins which will be used to modify resource configuration.
      * 
      */
     plugins?: Array<AdminForthPluginType>,
@@ -148,15 +455,98 @@ export type AdminForthResource = {
         id?: string,
       }>,
       allowedActions?: AllowedActions,
+
+      /** 
+       * Page size for list view
+       */
       listPageSize?: number,
+
+      /** 
+       * Custom components which can be injected into AdminForth CRUD pages.
+       * Each injection is a path to a custom component which will be displayed in the admin panel.
+       * Can be also array to render multiple injections one after another.
+       * 
+       * Example:
+       * 
+       * ```ts
+       * pageInjections: {
+       *  list: {
+       *   beforeBreadcrumbs: '@@/Announcement.vue',
+       *  }
+       * }
+       * ```
+       * 
+       * 
+       */
+      pageInjections?: {
+        /**
+         * Custom components which can be injected into resource list page.
+         * 
+         * Component accepts next props: [resource, adminUser]
+         */
+        list?: {
+          beforeBreadcrumbs?: string | Array<string>,
+          afterBreadcrumbs?: string | Array<string>,
+          bottom?: string | Array<string>,
+        },
+
+        /**
+         * Custom components which can be injected into resource show page.
+         * 
+         * Component accepts next props: [record, resource, adminUser]
+         */
+        show?: {
+          beforeBreadcrumbs?: string | Array<string>,
+          afterBreadcrumbs?: string | Array<string>,
+          bottom?: string | Array<string>,
+        },
+
+        /**
+         * Custom components which can be injected into resource edit page.
+         * 
+         * Component accepts next props: [record, resource, adminUser]
+         */
+        edit?: {
+          beforeBreadcrumbs?: string | Array<string>,
+          afterBreadcrumbs?: string | Array<string>,
+          bottom?: string | Array<string>,
+        },
+
+        /**
+         * Custom components which can be injected into resource create page.
+         * 
+         * Component accepts next props: [resource, adminUser]
+         */
+        create?: {
+          beforeBreadcrumbs?: string | Array<string>,
+          afterBreadcrumbs?: string | Array<string>,
+          bottom?: string | Array<string>,
+        },
+      }
     },
   }
   
+/**
+ * Data source describes database connection which will be used to fetch data for resources.
+ * Each resource should use one data source.
+ */
 export type AdminForthDataSource = {
-    id: string,
-    url: string,
+  /**
+   * ID of datasource which you will use in resources to specify from which database to fetch data from
+   */
+  id: string,
+
+  /**
+    * URL to database. Examples:
+    * 
+    * - MongoDB: `mongodb://<user>:<password>@<host>:<port>/<database>`
+    * - PostgreSQL: `postgresql://<user>:<password>@<host>:<port>/<database>`
+    * - SQLite: `sqlite://<path>`
+    */
+  url: string,
 }
 
+
 /**
  * Main configuration object for AdminForth
  */
@@ -245,7 +635,7 @@ export type AdminForthConfig = {
      * Datasource is one database connection
      * 
      */
-    dataSources: Array<DataSource>,
+    dataSources: Array<AdminForthDataSource>,
 
     /**
      * Settings which allow you to customize AdminForth
@@ -298,9 +688,10 @@ export type AdminForthConfig = {
        * For example if file path is `./custom/comp/my.vue`, you can use it in AdminForth config like this:
        * 
        * ```ts
-       * component: {
+       * components: {
        *  show: '@@/comp/my.vue',
        * }
+       * ```
        * 
        */
       customComponentsDir?: string,
@@ -355,6 +746,7 @@ export type AllowedActions = {
     edit?: boolean,
     show?: boolean,
     delete?: boolean,
+    filter?: boolean,
 }
   
 export type ValidationObject = {
@@ -379,27 +771,62 @@ export type ValidationObject = {
     message: string,
   }
 
-export type DataSource = {
+
+export type AdminForthFieldComponents = {
     /**
-     * ID of datasource which you will use in resources to specify from which database to fetch data from
+     * Show component is used to redefine cell which renders field value in show view.
+     * Component accepts next properties: [record, column, resource, adminUser].
+     * 
+     * Example: `FullName.vue`
+     * 
+     * ```vue
+     * <template>
+     *   {{ record.firstName }} {{ record.lastName }}
+     * </template>
+     * 
+     * <script setup>
+     * defineProps(['record']);
+     * </script>
+     * 
+     * ```ts
+     * {
+     *  label: 'Full Name',
+     *  virtual: true,
+     *  showIn: [AdminForthResourcePages.SHOW, AdminForthResourcePages.LIST],
+     *  components: {
+     *   show: '@@/FullName.vue',
+     *   list: '@@/FullName.vue',
+     *  },
+     * }
+     * ```
+     * 
      */
-    id: string,
+    show?: string,
 
     /**
-     * URL to database. Examples:
-     * 
-     * - MongoDB: `mongodb://<user>:<password>@<host>:<port>/<database>`
-     * - PostgreSQL: `postgresql://<user>:<password>@<host>:<port>/<database>`
-     * - SQLite: `sqlite://<path>`
+     * showRow component is similar to {@link AdminForthFieldComponent.show} but rewrites full table row (both \<td\> tags)
+     * Accepts next properties: [record, column, resource, adminUser]
      */
-    url: string,
-}
+    showRow?: string, 
 
-export type AdminForthResourceColumnComponent = {
-    show?: string,    // rewrite value in show
-    showRow?: string,  // rewrite full view table row (both <td> tags)
+    /**
+     * Create component is used to redefine input field in create view.
+     * Component accepts next properties: [record, column, resource, adminUser].
+     */
     create?: string,
+
+    /**
+     * Edit component is used to redefine input field in edit view.
+     * Component accepts next properties: [record, column, resource, adminUser].
+     */
     edit?: string,
+
+    /**
+     * List component is used to redefine cell which renders field value in list view.
+     * Component accepts next properties: [record, column, resource, adminUser].
+     * 
+     * Exa
+     */
     list?: string,
 }
 
@@ -435,12 +862,12 @@ export enum AdminForthSortDirections {
 };
 
 
-export type AdminForthResourceColumnEnumElement = {
-    value: string | null,
+export type AdminForthColumnEnumItem = {
+    value: any | null,
     label: string,
 } 
 
-export type AdminForthResourceColumnForeignResource = {
+export type AdminForthForeignResource = {
     resourceId: string,
     hooks?: {
       dropdownList?: {

package/types/FrontendAPI.ts

@@ -0,0 +1,73 @@
+ 
+export interface FrontendAPIInterface {
+
+    /**
+     * Show a confirmation dialog
+     * 
+     * The dialog will be displayed to the user
+     * 
+     * Example: 
+     * 
+     * ```ts
+     * const isConfirmed = await window.adminforth.confirm({message: 'Are you sure?', yes: 'Yes', no: 'No'})
+     * if (isConfirmed) {
+     *  your code...
+     * }
+     * ```
+     * 
+     * @param params - The parameters of the dialog
+     * @returns A promise that resolves when the user confirms the dialog
+     */   
+    confirm(params:ConfirmParams ): Promise<void>;
+    /**
+     * Show an alert
+     * 
+     * The alert will be displayed to the user
+     * 
+     * Example:
+     * 
+     * ```ts
+     *  window.adminforth.alert({message: 'Hello', variant: 'success'})
+     * ```
+     * 
+     * @param params - The parameters of the alert
+     */
+    alert(params:AlertParams): void;
+}
+
+export type ConfirmParams = {
+    /**
+     * The message to display in the dialog
+     */
+    message?: string;
+    /**
+     * The text to display in the "accept" button
+     */
+    yes?: string;
+    /**
+     * The text to display in the "cancel" button
+     */
+    no?: string;
+   
+}
+
+export type AlertParams = {
+    /**
+     * The message to display in the alert
+     */
+    message?: string;
+    /**
+     * The variant of the alert
+     */
+    variant?: AlertVariant;
+}
+
+export enum AlertVariant {
+    Danger = 'danger',
+    Success = 'success',
+    Warning = 'warning',
+    Info = 'info'
+  }
+  
+
+