feat: enhance table sorting functionality with per-column control and default sort handling

Author: NoOne7135

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

@@ -22,57 +22,6 @@ import { Button } from '@/afcl'
 ```
 
 ```html
-
-### Sorting
-
-Table supports column sorting out of the box.
-
-- Sorting is enabled globally by default. You can disable it entirely with `:sortable="false"`.
-- Per column, sorting can be disabled with `sortable: false` inside the column definition.
-- 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' },
-    { label: 'Age', fieldName: 'age' },
-    // 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' },
-  ]"
-  :sortable="true"
-  :pageSize="3"
-/>
-```
-
-You can also predefine a default sort:
-
-```html
-<Table
-  :columns="[
-    { label: 'Name', fieldName: 'name' },
-    { label: 'Age', fieldName: 'age' },
-    { 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.
-
 <Button @click="doSmth" 
     :loader="false" class="w-full">
   Your button text
@@ -1024,6 +973,89 @@ 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.
@@ -1049,9 +1081,8 @@ async function loadPageData({ offset, limit, sortField, sortDirection }) {
   if (sortField) url.searchParams.set('sortField', sortField);
   if (sortField && sortDirection) url.searchParams.set('sortDirection', sortDirection);
 
-  const res = await fetch(url.toString(), { credentials: 'include' });
-  const json = await res.json();
-  return { data: json.data, total: json.total };
+  const { data, total } = callAdminForthApi('getProducts', {limit, offset, sortField, sortDirection});
+  return { data, total };
 }
 
 <Table

adminforth/spa/src/afcl/Table.vue

@@ -166,13 +166,11 @@
       evenHighlights?: boolean,
       pageSize?: number,
       isLoading?: boolean,
-      sortable?: boolean, // enable/disable sorting globally
       defaultSortField?: string,
       defaultSortDirection?: 'asc' | 'desc',
     }>(), {
       evenHighlights: true,
       pageSize: 5,
-      sortable: false,
     }
   );
 
@@ -189,6 +187,13 @@
   const currentSortDirection = ref<'asc' | 'desc'>(props.defaultSortDirection ?? 'asc');
 
   onMounted(() => {
+    // If defaultSortField points to a non-sortable column, ignore it
+    if (currentSortField.value) {
+      const col = props.columns?.find(c => c.fieldName === currentSortField.value);
+      if (!col || !isColumnSortable(col)) {
+        currentSortField.value = undefined;
+      }
+    }
     refresh();
   });
 
@@ -206,7 +211,6 @@
   });
 
   watch([() => currentSortField.value, () => currentSortDirection.value], () => {
-    if (!props.sortable) return;
     if (currentPage.value !== 1) currentPage.value = 1;
     refresh();
     emit('update:sortField', currentSortField.value);
@@ -296,7 +300,8 @@
   }
 
 function isColumnSortable(col:{fieldName:string; sortable?:boolean}) {
-  return props.sortable === true && col.sortable === true;
+  // Sorting is controlled per column; default is NOT sortable. Enable with `sortable: true`.
+  return col.sortable === true;
 }
 
 function onHeaderClick(col:{fieldName:string; sortable?:boolean}) {
@@ -321,11 +326,11 @@ function getAriaSort(col:{fieldName:string; sortable?:boolean}) {
 const collator = new Intl.Collator(undefined, { numeric: true, sensitivity: 'base' });
 
 function sortArrayData(data:any[], sortField?:string, dir:'asc'|'desc'='asc') {
-  if (!props.sortable || !sortField) return data;
+  if (!sortField) return data;
   // Helper function to get nested properties by path
   const getByPath = (o:any, p:string) => p.split('.').reduce((a:any,k)=>a?.[k], o);
   return [...data].sort((a,b) => {
-    let av = getByPath(a, sortField), bv = getByPath(b, sortField);
+    const av = getByPath(a, sortField), bv = getByPath(b, sortField);
     // Handle null/undefined values
     if (av == null && bv == null) return 0;
     // Handle null/undefined values