Merge branch 'main' of github.com:devforth/adminforth

Author: yaroslav8765

adminforth/dataConnectors/baseConnector.ts

@@ -253,13 +253,13 @@ export default class AdminForthBaseConnector implements IAdminForthDataSourceCon
     resource: AdminForthResource; record: any; adminUser: any;
   }): Promise<{ error?: string; ok: boolean; createdRecord?: any; }> {
     // transform value using setFieldValue and call createRecordOriginalValues
-
+    
     const filledRecord = {...record};
     const recordWithOriginalValues = {...record};
 
     for (const col of resource.dataSourceColumns) {
       if (col.fillOnCreate) {
-        if (filledRecord[col.name] === undefined) {
+        if (filledRecord[col.name] === undefined || (Array.isArray(filledRecord[col.name]) && filledRecord[col.name].length === 0)) {
           filledRecord[col.name] = col.fillOnCreate({
             initialRecord: record, 
             adminUser

adminforth/documentation/docs/tutorial/03-Customization/01-branding.md

@@ -141,6 +141,8 @@ const admin = new AdminForth({
       enabled: true,  // Optional: Enable the collapsible icon-only sidebar feature
   //diff-add
       logo: '@@/logo.svg',  // Optional: Custom logo to display in icon-only mode
+  //diff-add
+      expandedSidebarWidth: '18.5rem', // Optional: sets the expanded sidebar width, defaults to 16.5rem
   //diff-add
     }, 
   },

adminforth/documentation/docs/tutorial/03-Customization/07-alert.md

@@ -24,7 +24,6 @@ Next variants are supported:
 * `warning`
 * `info`
 
-// ...existing code...
 ### Making alert responsive
 You can pass buttons in the alert method and receive a response like:
 

adminforth/documentation/docs/tutorial/03-Customization/09-Actions.md

@@ -204,7 +204,7 @@ import { admin } from '../index';
 //diff-add
               await stmt.run(...selectedIds);
 //diff-add
-              return { ok: true, error: false, successMessage: `Marked ${selectedIds.length} apartments as listed` };
+              return { ok: true, successMessage: `Marked ${selectedIds.length} apartments as listed` };
 //diff-add
             },
 //diff-add

adminforth/documentation/docs/tutorial/03-Customization/10-menuConfiguration.md

@@ -23,7 +23,7 @@ E.g. create group "Blog" with Items who link to resource "posts" and "categories
 ```ts title='./index.ts'
   {
     ...
-    menu: {
+    menu: [
       {
         label: 'Blog',
         icon: 'flowbite:brain-solid',
@@ -46,7 +46,7 @@ E.g. create group "Blog" with Items who link to resource "posts" and "categories
         icon: 'flowbite:folder-duplicate-outline',
         resourceId: 'adminuser',
       },
-    },
+    ],
     ...
   }
 ```

adminforth/documentation/docs/tutorial/03-Customization/13-standardPagesTuning.md

@@ -63,7 +63,7 @@ export default {
     }
 ```
 
-You can also specify on which page you want to create or delete groups. If you assign null, the groups will disappear from this page.
+You can also specify on which page you want to create groups.
 
 ```typescript title="./resources/apartments.ts"
 export default {
@@ -89,10 +89,6 @@ export default {
           }
           //diff-add
         ],
-          //diff-add
-        editFieldGroups: null,
-          //diff-add
-        showFieldGroups: null,
       }
     }
 ```

adminforth/documentation/docs/tutorial/03-Customization/15-afcl.md

@@ -973,6 +973,141 @@ async function loadPageData(data) {
 ```
 > 👆 The page size is used as the limit for pagination.
 
+### Sorting
+
+Table supports column sorting out of the box.
+
+- By default, columns are NOT sortable. Enable sorting per column with `sortable: true`.
+- Clicking a sortable header cycles sorting in a tri-state order:
+  - none → ascending → descending → none
+  - When it returns to "none", the sorting is cleared.
+
+Basic example (client-side sorting when `data` is an array):
+```html
+<Table
+  :columns="[
+    { label: 'Name', fieldName: 'name', sortable: true },
+    { label: 'Age', fieldName: 'age', sortable: true },
+    // disable sort for a specific column
+    { label: 'Country', fieldName: 'country', sortable: false },
+  ]"
+  :data="[
+    { name: 'John', age: 30, country: 'US' },
+    { name: 'Rick', age: 25, country: 'CA' },
+    { name: 'Alice', age: 35, country: 'BR' },
+    { name: 'Colin', age: 40, country: 'AU' },
+  ]"
+  :pageSize="3"
+/>
+```
+
+You can also predefine a default sort:
+
+```html
+<Table
+  :columns="[
+    { label: 'Name', fieldName: 'name', sortable: true },
+    { label: 'Age', fieldName: 'age', sortable: true },
+    { label: 'Country', fieldName: 'country' },
+  ]"
+  :data="rows"
+  defaultSortField="age"
+  defaultSortDirection="desc"
+/>
+```
+
+Notes:
+- Client-side sorting supports nested field paths using dot-notation, e.g. `user.name`.
+- When a column is not currently sorted, a subtle double-arrow icon is shown; arrows switch up/down for ascending/descending.
+
+#### Nested field path sorting
+
+You can sort by nested properties of objects in rows using dot-notation in `fieldName`.
+
+Example:
+
+```html
+<Table
+  :columns="[
+    { label: 'User Name', fieldName: 'user.name', sortable: true },
+    { label: 'User Email', fieldName: 'user.email', sortable: true },
+    { label: 'City', fieldName: 'user.address.city', sortable: true },
+    { label: 'Country', fieldName: 'user.address.country' },
+  ]"
+  :data="[
+    { user: { name: 'Alice', email: '[email protected]', address: { city: 'Berlin', country: 'DE' } } },
+    { user: { name: 'Bob', email: '[email protected]', address: { city: 'Paris', country: 'FR' } } },
+    { user: { name: 'Carlos', email: '[email protected]', address: { city: 'Madrid', country: 'ES' } } },
+    { user: { name: 'Dana', email: '[email protected]', address: { city: 'Rome', country: 'IT' } } },
+    { user: { name: 'Eve', email: '[email protected]', address: { city: null, country: 'US' } } },
+  ]"
+  :pageSize="3"
+/>
+```
+
+Behavior details:
+- The path is split on dots and resolved step by step: `user.address.city`.
+- Missing or `null` nested values are pushed to the bottom for ascending order (and top for descending) because `null/undefined` are treated as greater than defined values in asc ordering.
+- Works the same for client-side sorting and for server-side loaders: when using an async loader the same `sortField` (e.g. `user.address.city`) is passed so you can implement equivalent ordering on the backend.
+- Date objects at nested paths are detected and compared chronologically.
+- Numeric comparison is stable for mixed numeric strings via Intl.Collator with numeric option.
+
+Edge cases to consider in your own data:
+- Deeply missing branches like `user.profile.settings.locale` simply result in `undefined` and will follow the null ordering logic above.
+- Arrays are not traversed; if you need array-specific sorting you should pre-normalize data into scalar fields before passing to the table.
+
+### Server-side sorting
+
+When you provide an async function to `data`, the table will pass the current sort along with pagination params.
+
+Signature of the loader receives:
+
+```ts
+type LoaderArgs = {
+  offset: number;
+  limit: number;
+  sortField?: string; // undefined when unsorted
+  sortDirection?: 'asc' | 'desc'; // only when sortField is set
+}
+```
+
+Example using `fetch`:
+
+```ts
+async function loadPageData({ offset, limit, sortField, sortDirection }) {
+  const url = new URL('/api/products', window.location.origin);
+  url.searchParams.set('offset', String(offset));
+  url.searchParams.set('limit', String(limit));
+  if (sortField) url.searchParams.set('sortField', sortField);
+  if (sortField && sortDirection) url.searchParams.set('sortDirection', sortDirection);
+
+  const { data, total } = callAdminForthApi('getProducts', {limit, offset, sortField, sortDirection});
+  return { data, total };
+}
+
+<Table
+  :columns="[
+    { label: 'ID', fieldName: 'id' },
+    { label: 'Title', fieldName: 'title' },
+    { label: 'Price', fieldName: 'price' },
+  ]"
+  :data="loadPageData"
+  :pageSize="10"
+/>
+```
+
+Events you can listen to:
+
+```html
+<Table
+  :columns="columns"
+  :data="loadPageData"
+  @update:sortField="(f) => currentSortField = f"
+  @update:sortDirection="(d) => currentSortDirection = d"
+  @sort-change="({ field, direction }) => console.log('sort changed', field, direction)"
+/>
+```
+
 ### Table loading states
 
 For tables where you load data externally and pass them to `data` prop as array (including case with front-end pagination) you might want to show skeleton loaders in table externaly using `isLoading` props.

adminforth/documentation/docs/tutorial/07-Plugins/03-ForeignInlineList.md

@@ -72,9 +72,96 @@ Add to your `'adminuser'` resource configuration the plugin instance:
 }
 ```
 
-You can use `modifyTableResourceConfig` callback to modify what columns to show in the list and filter of the foreign table.
+You can use the `modifyTableResourceConfig` callback to modify which columns to show in the list and filter of the foreign table.
 
 ![alt text](ForeignInlineList.png)
 
 > 👆 To make plugin work, the specified resource (defined with `foreignResourceId`) should have one (and only one) column that refers to the current resource on which you add a plugin.
-> In our case we add plugin to `adminuser` resource, so the `aparts` resource should have one column with `foreignResource.resourceId` equal to `adminuser` resourceId.
+> In our case we add plugin to `adminuser` resource, so the `aparts` resource should have one column with `foreignResource.resourceId` equal to `adminuser` resourceId.
+
+## Default filters
+
+If you need to add default filters for the foreign resource based on your current record (for example show apartment only from Italy, when user have country Italy), you can use defaultFilters callback:
+>👆 This example won't work until you'll add counrty field in your adminuser resource and it's only for demonstrating concept of callback
+
+```ts title="./resources/adminuser.ts"
+
+  ...
+
+  new ForeignInlineListPlugin({
+
+    ...
+      //diff-add
+      defaultFilters: (record: any) => {
+        //diff-add
+        return [
+          //diff-add
+          {
+            //diff-add
+            field: "country",
+            //diff-add
+            operator: AdminForthFilterOperators.EQ,
+            //diff-add
+            value: record.country,
+            //diff-add
+          }
+          //diff-add
+        ]
+        //diff-add
+      }
+
+    ...
+
+  })
+
+  ...
+
+```
+
+>👆It also makes sense to modify the table resource and hide the country field from filters, because this value is hardcoded and equals the country from the record:  
+
+
+```ts
+
+  ...
+
+  new ForeignInlineListPlugin({
+
+    ...
+
+    //diff-add
+    modifyTableResourceConfig: (resourceConfig: AdminForthResource) => {
+      //diff-add
+      const column = resourceConfig.columns.find((c: AdminForthResourceColumn) => c.name === 'country')!.showIn = {
+        //diff-add
+        list: true,
+        //diff-add
+        show: true,
+        //diff-add
+        edit: true,
+        //diff-add
+        create: true,
+        //diff-add
+        filter: false
+        //diff-add
+      };
+      //diff-add
+    },
+
+    defaultFilters: (record: any) => {
+      return [
+        {
+          field: "country",
+          operator: AdminForthFilterOperators.EQ,
+          value: record.country,
+        }
+      ]
+    }
+
+    ...
+
+  })
+
+  ...
+  
+```

adminforth/documentation/docs/tutorial/07-Plugins/05-upload.md

@@ -99,7 +99,7 @@ model apartments {
 Migrate prisma schema:
 
 ```bash
-npx prisma migrate dev --name add-apartment-image
+npm run makemigration -- --name add-apartment-image ; npm run migrate:local
 ```
 
 Add column to `aparts` resource configuration:

adminforth/documentation/docs/tutorial/07-Plugins/11-oauth.md

@@ -84,7 +84,7 @@ model adminuser {
 2. Run the migration:
 
 ```bash
-npx prisma migrate dev --name add-email-confirmed-to-adminuser
+npm run makemigration -- --name add-email-confirmed-to-adminuser ; npm run migrate:local
 ```
 
 3. Configure the plugin with `emailConfirmedField`: