adminforth 1.0.84 → 1.1.1

package/dist/spa/spa/src/views/ListView.vue

@@ -12,8 +12,7 @@
     <component 
       v-for="c in coreStore?.resourceOptions?.pageInjections?.list?.beforeBreadcrumbs || []"
       :is="getCustomComponent(c)"
-      :record="coreStore.record"
-      :columns="coreStore.resourceColumns"
+      :resource="coreStore.resource"
       :adminUser="coreStore.adminUser"
     />
 
@@ -75,8 +74,7 @@
     <component 
       v-for="c in coreStore?.resourceOptions?.pageInjections?.list?.afterBreadcrumbs || []"
       :is="getCustomComponent(c)"
-      :record="coreStore.record"
-      :columns="coreStore.resourceColumns"
+      :resource="coreStore.resource"
       :adminUser="coreStore.adminUser"
     />
 
@@ -218,7 +216,9 @@
             <component
               :is="listComponentsPerColumn[c.name] || ValueRenderer"
               :column="c"
-              :row="row"
+              :record="row"
+              :adminUser="coreStore.adminUser"
+              :resource="coreStore.resource"
             />
           </td>
           <td class=" items-center px-6 py-4">
@@ -332,8 +332,7 @@
     <component 
       v-for="c in coreStore?.resourceOptions?.pageInjections?.list?.bottom || []"
       :is="getCustomComponent(c)"
-      :record="coreStore.record"
-      :columns="coreStore.resourceColumns"
+      :resource="coreStore.resource"
       :adminUser="coreStore.adminUser"
     />
 
@@ -458,8 +457,8 @@ async function getList() {
     }
   });
   listComponentsPerColumn = coreStore.resourceColumns.reduce((acc, column) => {
-      if (column.component?.list) {
-          acc[column.name] = getCustomComponent(column.component.list);
+      if (column.components?.list) {
+          acc[column.name] = getCustomComponent(column.components.list);
       }
       return acc;
     }, {});

package/dist/spa/spa/src/views/ShowView.vue

@@ -4,7 +4,7 @@
       v-for="c in coreStore?.resourceOptions?.pageInjections?.show?.beforeBreadcrumbs || []"
       :is="getCustomComponent(c)"
       :record="coreStore.record"
-      :columns="coreStore.resourceColumns"
+      :resource="coreStore.resource"
       :adminUser="coreStore.adminUser"
     />
     <BreadcrumbsWithButtons>
@@ -27,7 +27,7 @@
       v-for="c in coreStore?.resourceOptions?.pageInjections?.show?.afterBreadcrumbs || []"
       :is="getCustomComponent(c)"
       :record="coreStore.record"
-      :columns="coreStore.resourceColumns"
+      :resource="coreStore.resource"
       :adminUser="coreStore.adminUser"
     />
 
@@ -63,7 +63,8 @@
                 v-if="showRowComponentsPerColumn[column.name]"
                   :is="showRowComponentsPerColumn[column.name]"
                   :column="column"
-                  :row="coreStore.record"
+                  :resource="coreStore.resource"
+                  :record="coreStore.record"
               />
               <template v-else>
                 <td class="px-6 py-4 whitespace-nowrap">
@@ -73,12 +74,13 @@
                   <component
                     v-if="showComponentsPerColumn[column.name]"
                     :is="showComponentsPerColumn[column.name]"
+                    :resource="coreStore.resource"
                     :column="column"
-                    :row="coreStore.record"
+                    :record="coreStore.record"
                   />
                   <ValueRenderer v-else 
                     :column="column" 
-                    :row="coreStore.record"
+                    :record="coreStore.record"
                   />
                 </td>
               </template>
@@ -89,8 +91,9 @@
     <component 
       v-for="c in coreStore?.resourceOptions?.pageInjections?.show?.bottom || []"
       :is="getCustomComponent(c)"
+      :column="column"
       :record="coreStore.record"
-      :columns="coreStore.resourceColumns"
+      :resource="coreStore.resource"
       :adminUser="coreStore.adminUser"
     />
 </div>
@@ -139,14 +142,14 @@ onMounted(async () => {
   checkAcessByAllowedActions(coreStore.resourceOptions.allowedActions,'show');
 
   showComponentsPerColumn = coreStore.resourceColumns.reduce((acc, column) => {
-      if (column.component?.show) {
-          acc[column.name] = getCustomComponent(column.component.show);
+      if (column.components?.show) {
+          acc[column.name] = getCustomComponent(column.components.show);
       }
       return acc;
   }, {});
   showRowComponentsPerColumn = coreStore.resourceColumns.reduce((acc, column) => {
-      if (column.component?.showRow) {
-          acc[column.name] = getCustomComponent(column.component.showRow);
+      if (column.components?.showRow) {
+          acc[column.name] = getCustomComponent(column.components.showRow);
       }
       return acc;
   }, {});

package/dist/types/AdminForthConfig.js

@@ -1,49 +1,57 @@
-export var AdminForthMenuType;
-(function (AdminForthMenuType) {
+export var AdminForthMenuTypes;
+(function (AdminForthMenuTypes) {
     /**
      * HEADING is just a label in the menu.
-     * Respect `label` and `icon` property in @AdminForthConfigMenuItem
+     * Respect `label` and `icon` property in {@link AdminForthConfigMenuItem}
      */
-    AdminForthMenuType["HEADING"] = "heading";
+    AdminForthMenuTypes["heading"] = "heading";
     /**
      * GROUP is a group of menu items.
-     * Respects `label`, `icon` and `children` properties in @AdminForthConfigMenuItem
-     * use @AdminForthMenuType.open to set if group is open by default
+     * Respects `label`, `icon` and `children` properties in {@link AdminForthConfigMenuItem}
+     * use @AdminForthMenuTypes.open to set if group is open by default
      */
-    AdminForthMenuType["GROUP"] = "group";
+    AdminForthMenuTypes["group"] = "group";
     /**
      * RESOURCE is a link to a resource.
-     * Respects `label`, `icon`,  `resourceId`, `homepage`, `isStaticRoute` properties in @AdminForthConfigMenuItem
+     * Respects `label`, `icon`,  `resourceId`, `homepage`, `isStaticRoute` properties in {@link AdminForthConfigMenuItem}
      */
-    AdminForthMenuType["RESOURCE"] = "resource";
+    AdminForthMenuTypes["resource"] = "resource";
     /**
      * PAGE is a link to a custom page.
-     * Respects `label`, `icon`, `path`, `component`, `homepage`, `isStaticRoute`, properties in @AdminForthConfigMenuItem
+     * Respects `label`, `icon`, `path`, `component`, `homepage`, `isStaticRoute`, properties in {@link AdminForthConfigMenuItem}
      *
      * Example:
      *
      * ```ts
-     * {
-     *  type: AdminForthMenuType.PAGE,
+     * \{
+     *  type: AdminForthMenuTypes.PAGE,
      *  label: 'Custom Page',
      *  icon: 'home',
      *  path: '/dash',
      *  component: '@@/Dashboard.vue',
      *  homepage: true,
-     * }
+     * \}
      * ```
      *
      */
-    AdminForthMenuType["PAGE"] = "page";
+    AdminForthMenuTypes["page"] = "page";
     /**
      * GAP ads some space between menu items.
      */
-    AdminForthMenuType["GAP"] = "gap";
+    AdminForthMenuTypes["gap"] = "gap";
     /**
      * DIVIDER is a divider between menu items.
      */
-    AdminForthMenuType["DIVIDER"] = "divider";
-})(AdminForthMenuType || (AdminForthMenuType = {}));
+    AdminForthMenuTypes["divider"] = "divider";
+})(AdminForthMenuTypes || (AdminForthMenuTypes = {}));
+export var AdminForthResourcePages;
+(function (AdminForthResourcePages) {
+    AdminForthResourcePages["list"] = "list";
+    AdminForthResourcePages["show"] = "show";
+    AdminForthResourcePages["edit"] = "edit";
+    AdminForthResourcePages["create"] = "create";
+    AdminForthResourcePages["filter"] = "filter";
+})(AdminForthResourcePages || (AdminForthResourcePages = {}));
 export var AdminForthDataTypes;
 (function (AdminForthDataTypes) {
     AdminForthDataTypes["STRING"] = "string";

package/dist/types/FrontendAPI.js

@@ -0,0 +1,7 @@
+export var AlertVariant;
+(function (AlertVariant) {
+    AlertVariant["Danger"] = "danger";
+    AlertVariant["Success"] = "success";
+    AlertVariant["Warning"] = "warning";
+    AlertVariant["Info"] = "info";
+})(AlertVariant || (AlertVariant = {}));

package/documentation/docs/Getting Started.md

@@ -0,0 +1,374 @@
+
+# Installation
+
+## Prerequisites
+
+We recommend using Node v18 and higher
+
+## Installation
+
+```bash
+mkdir myadmin
+cd myadmin
+npm install adminforth
+```
+
+AdminForth does not provide own HTTP server, but can add own listeners over exisitng [Express](https://expressjs.com/) server (Fastify support is planned in future). This allows to create custom APIs for backoffice in a way you know.
+
+Let's install express:
+
+```bash
+npm install express@4.19.2
+```
+
+For demo purposes we will use SQLite data source. You can use postgress, Mongo or Clickhouse as well. 
+
+
+```bash
+npm install better-sqlite3@10.0.0
+```
+
+You can use adminforth in pure Node, but we recommend using TypeScript for better development experience.
+
+```bash
+npm install typescript@5.4.5 --save-dev
+npm install tsx@4.11.2 --save-dev
+```
+
+# Philosophy
+
+AdminForth connects to existing databases and provide a backoffice for managing data including CRUD operations, filtering, sorting, and more.
+
+Database should be already created by using any database management tool, ORM or migrator. AdminForth does not provide a way to create tables or columns in the database.
+
+Once you have a database, you pass a connection string to AdminForth and define resources(tables) and columns you would like to see in backoffice. For most DB AdminForth can guess column types and constraints (e.g. max-lenght) by connecting to DB. However you can redefine them in AdminForth configuration. Type and constraints definition are take precedence over DB metadata.
+
+Also in AdminForth you can define in "Vue" way how each field will be rendered, and create own pages e.g. Dashboards.
+
+In the demo we will create a simple database with 2 tables: `apartments` and `users`. We will just use plain SQL to create tables and insert some fake data.
+
+Users table will be used to store a credentials for login into backoffice itself.
+
+## Possible configuration options
+
+We will use schema with different column types for apartments to show many of AdminForth features.
+
+Check [AdminForthConfig](/docs/api/type-aliases/AdminForthConfig.md) for all possible AdminForth Configs.
+
+
+# Setting up a demo
+
+Open `package.json`, set `type` to `module` and add `start` script:
+
+```json
+{
+  ...
+  "type": "module",
+  "scripts": {
+    ...
+    "start": "ADMINFORTH_SECRET=CHANGE_ME_IN_PRODUCTION NODE_ENV=development tsx watch index.ts"
+  },
+}
+```
+
+
+Create `index.ts` file with following content:
+
+```typescript
+
+import betterSqlite3 from 'better-sqlite3';
+import express from 'express';
+import AdminForth from 'adminforth';
+
+const dbFile = 'test.sqlite';
+const db = betterSqlite3(dbFile)
+  
+const tableExists = db.prepare(`SELECT name FROM sqlite_master WHERE type='table' AND name='apartments';`).get();
+if (!tableExists) {
+  await db.prepare(`
+    CREATE TABLE apartments (
+        id VARCHAR(20) PRIMARY KEY NOT NULL,
+        title VARCHAR(255) NOT NULL,
+        square_meter REAL,
+        price DECIMAL(10, 2) NOT NULL,
+        number_of_rooms INT,
+        description TEXT,
+        property_type VARCHAR(255) DEFAULT 'apartment',
+        listed BOOLEAN DEFAULT FALSE,
+        created_at TIMESTAMP,
+        user_id VARCHAR(255)
+    );`).run();
+
+  await db.prepare(`
+    CREATE TABLE users (
+        id VARCHAR(255) PRIMARY KEY NOT NULL,
+        email VARCHAR(255) NOT NULL,
+        password_hash VARCHAR(255) NOT NULL,
+        created_at VARCHAR(255) NOT NULL,
+        role VARCHAR(255) NOT NULL
+    );`).run();
+
+  for (let i = 0; i < 50; i++) {
+    await db.prepare(`
+      INSERT INTO apartments (
+        id, title, square_meter, price, number_of_rooms, description, created_at, listed, property_type
+      ) VALUES ('${i}', 'Apartment ${i}', ${Math.random() * 100}, ${Math.random() * 10000}, ${Math
+        .floor(Math.random() * 5) }, 'Next gen appartments', ${Date.now() / 1000 - i * 60 * 60 * 24}, ${i % 2 == 0}, ${i % 2 == 0 ? "'house'" : "'apartment'"});
+      `).run();
+  }
+}
+
+const ADMIN_BASE_URL = '';
+
+const admin = new AdminForth({
+  baseUrl : ADMIN_BASE_URL,
+  rootUser: {
+    username: 'adminforth',  // use these as credentials to login
+    password: 'adminforth',
+  },
+  auth: {
+    resourceId: 'users',  // resource for getting user
+    usernameField: 'email',
+    passwordHashField: 'password_hash',
+  },
+  customization: {
+    brandName: 'My Admin',
+    datesFormat: 'D MMM YY HH:mm:ss',
+    emptyFieldPlaceholder: '-',
+  },
+
+  dataSources: [
+    {
+      id: 'maindb',
+      url: `sqlite://${dbFile}`
+    },
+  ],
+  resources: [
+    {
+      dataSource: 'maindb', 
+      table: 'apartments',
+      resourceId: 'apparts', // resourceId is defaulted to table name but you can change it e.g. 
+                             // in case of same table names from different data sources
+      label: 'Apartments',   // label is defaulted to table name but you can change it
+      recordLabel: (r) => `🏡 ${r.title}`,
+      columns: [
+        { 
+          name: 'id', 
+          label: 'Identifier',  // if you wish you can redefine label
+          showIn: ['filter', 'show'], // show in filter and in show page
+          primaryKey: true,
+          fillOnCreate: ({initialRecord, adminUser}) => Math.random().toString(36).substring(7),  // initialRecord is values user entered, adminUser object of user who creates record
+        },
+        { 
+          name: 'title',
+          required: true,
+          showIn: ['list', 'create', 'edit', 'filter', 'show'],  // the default is full set
+          maxLength: 255,  // you can set max length for string fields
+          minLength: 3,  // you can set min length for string fields
+        }, 
+        {
+          name: 'created_at',
+          type: AdminForth.Types.DATETIME ,
+          allowMinMaxQuery: true,
+          showIn: ['list', 'filter', 'show', 'edit'],
+          fillOnCreate: ({initialRecord, adminUser}) => (new Date()).toISOString(),
+        },
+        { 
+          name: 'price',
+          min: 10,
+          max: 10000.12,
+          allowMinMaxQuery: true,  // use better experience for filtering e.g. date range, set it only if you have index on this column or if there will be low number of rows
+          editingNote: 'Price is in USD',  // you can appear note on editing or creating page
+        },
+        { 
+          name: 'square_meter', 
+          label: 'Square', 
+          allowMinMaxQuery: true,
+          minValue: 1,  // you can set min /max value for number fields
+          maxValue: 1000,
+        },
+        { 
+          name: 'number_of_rooms',
+          allowMinMaxQuery: true,
+          enum: [
+            { value: 1, label: '1 room' },
+            { value: 2, label: '2 rooms' },
+            { value: 3, label: '3 rooms' },
+            { value: 4, label: '4 rooms' },
+            { value: 5, label: '5 rooms' },
+          ],
+          allowCustomValue: true,
+        },
+        { 
+          name: 'description',
+          sortable: false,
+        },
+        {
+          name: 'property_type',
+          enum: [{
+            value: 'house',
+            label: 'House'
+          }, {
+            value: 'apartment',
+            label: 'Apartment'
+          }, {
+            value: null,
+            label: 'Not defined'
+          }],
+        },
+        {
+          name: 'listed',
+          required: true,  // will be required on create/edit
+        },
+        {
+          name: 'user_id',
+          foreignResource: {
+            resourceId: 'users',
+          }
+        }
+      ],
+      options: {
+        listPageSize: 12,
+        allowedActions:{
+          edit: false,
+          delete: true,
+          show: true,
+          filter: true,
+        },
+      },
+    },
+    { 
+      dataSource: 'maindb', 
+      table: 'users',
+      resourceId: 'users',
+      label: 'Users',  
+      recordLabel: (r) => `👤 ${r.email}`,
+      columns: [
+        { 
+          name: 'id', 
+          primaryKey: true,
+          fillOnCreate: ({initialRecord, adminUser}) => Math.random().toString(36).substring(7),
+          showIn: ['list', 'filter', 'show'],
+        },
+        { 
+          name: 'email', 
+          required: true,
+          isUnique: true,
+          validation: [
+            {
+              regExp: '^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$',
+              message: 'Email is not valid, must be in format example@test.com'
+            },
+          ]
+        },
+        { 
+          name: 'created_at', 
+          type: AdminForth.Types.DATETIME,
+          showIn: ['list', 'filter', 'show'],
+          fillOnCreate: ({initialRecord, adminUser}) => (new Date()).toISOString(),
+        },
+        {
+          name: 'role',
+          enum: [
+            { value: 'superadmin', label: 'Super Admin' },
+            { value: 'user', label: 'User' },
+          ]
+        },
+        {
+          name: 'password',
+          virtual: true,  // field will not be persisted into db
+          required: { create: true }, // make required only on create page
+          editingNote: { edit: 'Leave empty to keep password unchanged' },
+          minLength: 8,
+          type: AdminForth.Types.STRING,
+          showIn: ['create', 'edit'], // to show field only on create and edit pages
+          masked: true, // to show stars in input field
+        }
+      ],
+      hooks: {
+        create: {
+          beforeSave: async ({ record, adminUser, resource }) => {
+            record.password_hash = await AdminForth.Utils.generatePasswordHash(record.password);
+            return { ok:true, error: false };
+          }
+        },
+        edit: {
+          beforeSave: async ({ record, adminUser, resource}) => {
+            if (record.password) {
+              record.password_hash = await AdminForth.Utils.generatePasswordHash(record.password);
+            }
+            return { ok: true, error: false }
+          },
+        },
+      }
+    },
+  ],
+  menu: [
+    {
+      label: 'Core',
+      icon: 'flowbite:brain-solid', // any icon from iconify supported in format <setname>:<icon>, e.g. from here https://icon-sets.iconify.design/flowbite/
+      open: true,
+      children: [
+        {
+          homepage: true,
+          label: 'Appartments',
+          icon: 'flowbite:home-solid',
+          resourceId: 'apparts',
+        },
+      ]
+    },
+    {
+      type: 'gap'
+    },
+    {
+      type: 'divider'
+    },
+    {
+      type: 'heading',
+      label: 'SYSTEM',
+    },
+    {
+      label: 'Users',
+      icon: 'flowbite:user-solid',
+      resourceId: 'users',
+    }
+  ],
+})
+
+
+const app = express()
+app.use(express.json());
+const port = 3500;
+
+(async () => {
+    // needed to compile SPA. Call it here or from a build script e.g. in Docker build time to reduce downtime
+    await admin.bundleNow({ hotReload: process.env.NODE_ENV === 'development'});
+    console.log('Bundling AdminForth done. For faster serving consider calling bundleNow() from a build script.');
+})();
+
+
+// serve after you added all api
+admin.express.serve(app, express)
+admin.discoverDatabases();
+
+
+app.listen(port, () => {
+  console.log(`Example app listening at http://localhost:${port}`)
+  console.log(`\n⚡ AdminForth is available at http://localhost:${port}${ADMIN_BASE_URL}\n`)
+});
+```
+
+
+Now you can run your app:
+
+```bash
+npm start
+```
+
+Open http://localhost:3500 in your browser and login with credentials `adminforth` / `adminforth`.
+
+![alt text](image.png)
+
+
+After Login you should see:
+

package/documentation/docs/Glossary.md

@@ -0,0 +1,37 @@
+
+# dataSource
+
+A DataSource is a connection to one database. Datasources has id for references from resources and URL which follows the standard URI format. For example `mysql://user:password@localhost:3306/database`.
+It used to:
+
+* Discover the columns in the database
+* Make queries to get the list and show records
+* Make queries to modify data
+
+There might be several datasources in the system for vairous databases e.g. One 2 Mongo DBs and 1 Postgres DB. 
+
+# resource
+
+A Resource is a representation of a table or collection in AdminForth. One resource is one table in the database.
+It has a `name` which should match name in database, a datasource id, and a list of columns.
+Also it has various customization options.
+
+# column
+
+A Column is a representation of a column in a table. It has a `name` which should be equal to name in database and various configuration options.
+
+# record
+
+A record is a row in a relational database table. Or Document in document database table.
+
+# adminUser
+
+Object which represents a user who logged in to the AdminForth
+
+# hook
+
+Hook is a optional async function which allows to inject in backend logic before exuting the datasource query or after it
+
+# component
+
+Component is a Vue component which is used to add or modify UI elements in AdminForth.

package/documentation/docusaurus.config.ts

@@ -58,7 +58,7 @@ const config: Config = {
     [
       "docusaurus-plugin-typedoc",
       {
-        entryPoints: ["../types/AdminForthConfig.ts"],
+        entryPoints: ["../types/AdminForthConfig.ts", "../types/FrontendAPI.ts"],
         plugin: ["./typedoc-plugin.mjs"],
         readme: "none",
         indexFormat: "table",