feat: add pagination size options for list views with dynamic selection

Author: kulikp1

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

@@ -319,6 +319,48 @@ export default {
   ]
 ```
 
+### List Page Size Options
+You can define available pagination sizes using options.listPageSizeOptions. This allows users to choose how many records they want to see per page in the list view.
+```typescript title="./resources/apartments.ts"
+export default {
+      resourceId: 'aparts',
+      options: {
+        ...
+        listPageSize: 10,
+        // listPageSizeOptions can be a static array
+        //diff-add
+        listPageSizeOptions: [10, 20, 50],
+        // OR a function for dynamic options based on user role
+        //diff-add
+        listPageSizeOptions: ({ adminUser }) => {
+          //diff-add
+          if (adminUser?.dbUser?.role === 'superadmin') {
+            //diff-add
+            return [50, 100, 500];
+            //diff-add
+          }
+          //diff-add
+          return [10, 20, 50];
+          //diff-add
+        },
+      }
+    }
+  ]
+```
+#### How it works
+- listPageSize defines the default number of records per page when the list is opened.
+- listPageSizeOptions defines the available page size options shown to the user.
+
+For example: listPageSizeOptions: [10, 20, 50] will allow switching between 10 / 20 / 50 records per page.
+
+#### UI behavior
+Page size switching is implemented via a select dropdown (select input) in the table pagination controls.
+- User opens the select
+- Chooses a value (e.g. 20)
+- Table reloads with the new page size
+> ☝️Notes 
+If `listPageSizeOptions` is not provided (or resolves to an empty array), the page size select is not shown. The selected value updates the table immediately and triggers a data refetch. Use `listPageSize` to define the initial number of records per page, and `listPageSizeOptions` to define which page sizes the user can switch between.
+
 ### Virtual scroll
 
 Set `options.listVirtualScrollEnabled` to true to enable virtual scrolling in the table. The default value is false. Enable this option if you need to display a large number of records on a single page.

adminforth/spa/src/components/ResourceListTable.vue

@@ -340,6 +340,22 @@
         </span> 
       </template>
     </span>
+    <div v-if="totalRows > 0 && pageSizeOptionsComputed?.length" 
+      class="flex items-center gap-2 ml-auto" > 
+      <span class="text-sm text-lightListTablePaginationHelpText dark:text-darkListTablePaginationHelpText whitespace-nowrap"> 
+        {{ $t('Rows per page') }} 
+      </span> 
+      <Select 
+        v-model="pageSizeInternal" 
+        :options="pageSizeOptionsComputed" 
+        :searchDisabled="true" 
+        :disableTogleOfSelectedItem="true"  
+        :style="{ width: selectDynamicWidth }"
+        :placeholder="pageSizeInternal?.toString()"        
+        class="text-sm" 
+        classesForInput="h-[34px] min-h-0 py-1 pl-2 pr-6 text-sm rounded-md cursor-pointer af-button-shadow bg-lightDropdownButtonsBackground text-lightDropdownButtonsText border-lightDropdownButtonsBorder dark:bg-darkDropdownButtonsBackground dark:text-darkDropdownButtonsText dark:border-darkDropdownButtonsBorder"
+      /> 
+    </div>
   </div>
 </template>
 
@@ -368,6 +384,7 @@ import { useAdminforth } from '@/adminforth';
 import Checkbox from '@/afcl/Checkbox.vue';
 import ListActionsThreeDots from '@/components/ListActionsThreeDots.vue';
 import CallActionWrapper from '@/components/CallActionWrapper.vue'
+import { Select } from '@/afcl';
 
 const coreStore = useCoreStore();
 const { t } = useI18n();
@@ -407,10 +424,45 @@ const emits = defineEmits([
   'update:page',
   'update:sort',
   'update:checkboxes',
-  'update:records'
+  'update:records',
+  'update:pageSize'
 
 ]);
 
+const pageSizeOptionsComputed = computed(() => {
+  const options = props.resource?.options?.listPageSizeOptions || [10, 20, 50, 100];
+  return options.map(size => ({
+    value: size,
+    label: size.toString()
+  }));
+});
+
+const pageSizeInternal = ref(props.pageSize);
+
+const selectDynamicWidth = computed(() => {
+  const length = pageSizeInternal.value?.toString().length || 2;
+  return `${length + 5}ch`;
+})
+
+watch(() => pageSizeInternal.value, (newSize) => {
+  if (newSize) {
+    localStorage.setItem(`pageSize_${props.resource?.resourceId}`, newSize.toString());
+    emits('update:pageSize', newSize);
+    page.value = 1;
+  }
+});
+
+onMounted(() => {
+  const savedSize = localStorage.getItem(`pageSize_${props.resource?.resourceId}`);
+  if (savedSize) {
+    const sizeNum = parseInt(savedSize);
+    if (props.resource?.options?.listPageSizeOptions?.includes(sizeNum)) {
+      pageSizeInternal.value = sizeNum;
+      emits('update:pageSize', sizeNum);
+    }
+  }
+});
+
 const checkboxesInternal: Ref<any[]> = ref([]);
 const pageInput = ref('1');
 const page = ref(1);

adminforth/spa/src/views/ListView.vue

@@ -171,6 +171,7 @@
       @update:sort="sort = $event"
       @update:checkboxes="checkboxes = $event"
       @update:records="getListInner"
+      @update:pageSize="(newSize) => { pageSize = newSize; page = 1; }"
       :sort="sort"
       :pageSize="pageSize"
       :totalRows="totalRows"
@@ -261,7 +262,23 @@ const customActionLoadingStates = ref<{[key: string]: boolean}>({});
 const DEFAULT_PAGE_SIZE = 10;
 
 
-const pageSize = computed(() => coreStore.resource?.options?.listPageSize || DEFAULT_PAGE_SIZE);
+const pageSize = ref(DEFAULT_PAGE_SIZE);
+
+const syncPageSize = () => {
+  const resourceId = route.params.resourceId;
+  const savedSize = localStorage.getItem(`pageSize_${resourceId}`);
+
+  if (savedSize) {
+    pageSize.value = parseInt(savedSize);
+  } 
+  else if (coreStore.resource?.options?.listPageSize) {
+    pageSize.value = coreStore.resource.options.listPageSize;
+  } 
+  else {
+    pageSize.value = DEFAULT_PAGE_SIZE;
+  }
+};
+
 const isVirtualScrollEnabled = computed(() => coreStore.resource?.options?.listVirtualScrollEnabled || false);
 const listBufferSize = computed(() => coreStore.resource?.options?.listBufferSize || 30);
 
@@ -396,6 +413,9 @@ async function init() {
   await coreStore.fetchResourceFull({
     resourceId: route.params.resourceId as string
   });
+
+  syncPageSize();
+
   isPageLoaded.value = true;
   // !!! clear filters should be in same tick with sort assignment so that watch can catch it as one change
 
@@ -446,7 +466,7 @@ async function init() {
   }
 }
 
-watch([page, sort, () => filtersStore.filters], async () => {
+watch([page, sort, pageSize, () => filtersStore.filters], async () => {
   // console.log('🔄️ page/sort/filter change fired, page:', page.value);
   await getListInner();
 }, { deep: true });

adminforth/types/Common.ts

@@ -472,6 +472,13 @@ export interface AdminForthResourceInputCommon {
        * Page size for list view
        */
       listPageSize?: number,
+
+      /**
+        * Available page size options for list view, provided as an array of page sizes
+        * or a function returning them. When set together with `listPageSize`, the page
+        * size should be one of the values returned here.
+        */
+      listPageSizeOptions?: number[];
 
       /**
        * Whether to use virtual scroll in list view.