@ramathibodi/nuxt-commons 4.0.7 → 4.0.9

package/dist/module.json

@@ -4,7 +4,7 @@
   "compatibility": {
     "nuxt": "^4.3.1"
   },
-  "version": "4.0.7",
+  "version": "4.0.9",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/module.mjs

@@ -48,6 +48,13 @@ const module$1 = defineNuxtModule({
       ...runtimeConfig,
       ..._options
     };
+    const publicConfig = _nuxt.options.runtimeConfig.public;
+    if (publicConfig.IDEMPOTENCY_HEADER == null) {
+      publicConfig.IDEMPOTENCY_HEADER = "Idempotency-Key";
+    }
+    if (publicConfig.IDEMPOTENCY_ENABLED == null) {
+      publicConfig.IDEMPOTENCY_ENABLED = true;
+    }
     _nuxt.options.vite.optimizeDeps ||= {};
     _nuxt.options.vite.optimizeDeps.include ||= [];
     _nuxt.options.vite.optimizeDeps.include.push("painterro");

package/dist/runtime/components/form/CheckboxGroup.d.vue.ts

@@ -12,7 +12,10 @@ interface Props extends /* @vue-ignore */ InstanceType<typeof VCheckbox['$props'
 }
 declare const __VLS_export: import("vue").DefineComponent<import("vue").ExtractPropTypes<__VLS_WithDefaults<__VLS_TypePropsToOption<Props>, {
     inline: boolean;
-}>>, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+}>>, {
+    validate: () => boolean;
+    reset: () => void;
+}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     "update:modelValue": (...args: any[]) => void;
 }, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<__VLS_WithDefaults<__VLS_TypePropsToOption<Props>, {
     inline: boolean;

package/dist/runtime/components/form/CheckboxGroup.vue

@@ -12,6 +12,18 @@ const props = defineProps({
 const emit = defineEmits(["update:modelValue"]);
 const values = ref([]);
 const valuesOther = ref();
+const touched = ref(false);
+const onUserInput = () => {
+  touched.value = true;
+};
+const validate = () => {
+  touched.value = true;
+  return !computedRules.value;
+};
+const reset = () => {
+  touched.value = false;
+};
+defineExpose({ validate, reset });
 const computedRules = computed(() => {
   if (props.rules) {
     let rules = props.rules.map((rule) => rule(values.value.length ? values.value : null));
@@ -19,6 +31,7 @@ const computedRules = computed(() => {
     return join(rules, ",");
   }
 });
+const showError = computed(() => touched.value && !!computedRules.value);
 const computedOther = computed(() => {
   const itemOther = filter(props.items, { value: "other" });
   return head(itemOther);
@@ -46,27 +59,33 @@ watch(props.modelValue, () => {
 </script>
 
 <template>
-    <label class="text-body-1 opacity-60">{{props.label}}</label>
-    <div :class="`d-flex ${inline ? 'flex-row' : 'flex-column'}`">
-      <v-checkbox v-for="item in computeItems"
-                  :value="item.value"
-                  v-model="values"
-                  density="compact"
-                  hide-details
-                  :error = "!!computedRules"
-                  :="$attrs"
-                  :label="item.label">
-      </v-checkbox>
-    </div>
-    <v-text-field hide-details
-                  :error = "!!computedRules"
-                  v-if="computedOther"
-                  v-model="valuesOther"
-                  :="$attrs"
-                  :label="computedOther.label">
-
-    </v-text-field>
-    <label class="text-error text-subtitle-2 ml-1">
-      {{computedRules}}
-    </label>
+  <label class="text-body-1 opacity-60">{{ props.label }}</label>
+  <div :class="`d-flex ${inline ? 'flex-row' : 'flex-column'}`">
+    <v-checkbox
+      v-for="item in computeItems"
+      v-model="values"
+      :value="item.value"
+      density="compact"
+      hide-details
+      :error="showError"
+      :="$attrs"
+      :label="item.label"
+      @update:model-value="onUserInput"
+    />
+  </div>
+  <v-text-field
+    v-if="computedOther"
+    v-model="valuesOther"
+    hide-details
+    :error="showError"
+    :="$attrs"
+    :label="computedOther.label"
+    @update:model-value="onUserInput"
+  />
+  <label
+    v-if="showError"
+    class="text-error text-subtitle-2 ml-1"
+  >
+    {{ computedRules }}
+  </label>
 </template>

package/dist/runtime/components/form/CheckboxGroup.vue.d.ts

@@ -12,7 +12,10 @@ interface Props extends /* @vue-ignore */ InstanceType<typeof VCheckbox['$props'
 }
 declare const __VLS_export: import("vue").DefineComponent<import("vue").ExtractPropTypes<__VLS_WithDefaults<__VLS_TypePropsToOption<Props>, {
     inline: boolean;
-}>>, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+}>>, {
+    validate: () => boolean;
+    reset: () => void;
+}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     "update:modelValue": (...args: any[]) => void;
 }, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<__VLS_WithDefaults<__VLS_TypePropsToOption<Props>, {
     inline: boolean;

package/dist/runtime/components/form/Iterator.d.vue.ts

@@ -29,6 +29,8 @@ interface Props extends /* @vue-ignore */ InstanceType<typeof VDataIterator['$pr
     preferTableLg?: string | number | boolean;
     preferTableMd?: string | number | boolean;
     preferTableSm?: string | number | boolean;
+    perPageStorageKey?: string;
+    perPageStorageEnabled?: boolean;
 }
 declare function setSearch(keyword: string): void;
 declare function createItem(item: Record<string, any>, callback?: FormDialogCallback): void;
@@ -193,6 +195,7 @@ declare const __VLS_base: import("vue").DefineComponent<import("vue").ExtractPro
     md: number;
     sm: number;
     itemsPerPage: number;
+    perPageStorageEnabled: boolean;
 }>>, {
     errorMessages: import("vue").ComputedRef<(string & string[]) | (readonly string[] & string[]) | undefined>;
     isValid: import("vue").ComputedRef<boolean | null | undefined>;
@@ -248,6 +251,7 @@ declare const __VLS_base: import("vue").DefineComponent<import("vue").ExtractPro
     md: number;
     sm: number;
     itemsPerPage: number;
+    perPageStorageEnabled: boolean;
 }>>> & Readonly<{
     "onUpdate:modelValue"?: ((...args: any[]) => any) | undefined;
 }>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;

package/dist/runtime/components/form/Iterator.vue

@@ -5,6 +5,7 @@ import { VDataIterator } from "vuetify/components/VDataIterator";
 import { VDataTable } from "vuetify/components/VDataTable";
 import { VInput } from "vuetify/components/VInput";
 import { useDisplay } from "vuetify";
+import { usePerPagePreference } from "../../composables/perPagePreference";
 defineOptions({
   inheritAttrs: false
 });
@@ -35,7 +36,9 @@ const props = defineProps({
   preferTableXl: { type: [String, Number, Boolean], required: false },
   preferTableLg: { type: [String, Number, Boolean], required: false },
   preferTableMd: { type: [String, Number, Boolean], required: false },
-  preferTableSm: { type: [String, Number, Boolean], required: false }
+  preferTableSm: { type: [String, Number, Boolean], required: false },
+  perPageStorageKey: { type: String, required: false },
+  perPageStorageEnabled: { type: Boolean, required: false, default: true }
 });
 const emit = defineEmits(["update:modelValue"]);
 const attrs = useAttrs();
@@ -122,6 +125,10 @@ watch(() => props.itemsPerPage, (newValue) => {
   if (newValue.toString().toLowerCase() == "all") itemsPerPageInternal.value = "-1";
   else if (newValue) itemsPerPageInternal.value = newValue;
 }, { immediate: true });
+usePerPagePreference(itemsPerPageInternal, {
+  storageKey: props.perPageStorageKey,
+  enabled: props.perPageStorageEnabled
+});
 function createItem(item, callback) {
   if (items.value.length > 0) item[props.modelKey] = Math.max(...items.value.map((i) => i[props.modelKey] || 0)) + 1;
   else item[props.modelKey] = 1;

package/dist/runtime/components/form/Iterator.vue.d.ts

@@ -29,6 +29,8 @@ interface Props extends /* @vue-ignore */ InstanceType<typeof VDataIterator['$pr
     preferTableLg?: string | number | boolean;
     preferTableMd?: string | number | boolean;
     preferTableSm?: string | number | boolean;
+    perPageStorageKey?: string;
+    perPageStorageEnabled?: boolean;
 }
 declare function setSearch(keyword: string): void;
 declare function createItem(item: Record<string, any>, callback?: FormDialogCallback): void;
@@ -193,6 +195,7 @@ declare const __VLS_base: import("vue").DefineComponent<import("vue").ExtractPro
     md: number;
     sm: number;
     itemsPerPage: number;
+    perPageStorageEnabled: boolean;
 }>>, {
     errorMessages: import("vue").ComputedRef<(string & string[]) | (readonly string[] & string[]) | undefined>;
     isValid: import("vue").ComputedRef<boolean | null | undefined>;
@@ -248,6 +251,7 @@ declare const __VLS_base: import("vue").DefineComponent<import("vue").ExtractPro
     md: number;
     sm: number;
     itemsPerPage: number;
+    perPageStorageEnabled: boolean;
 }>>> & Readonly<{
     "onUpdate:modelValue"?: ((...args: any[]) => any) | undefined;
 }>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;

package/dist/runtime/components/form/Pad.vue

@@ -22,7 +22,7 @@ const props = defineProps({
   parentTemplates: { type: [String, Array], required: false, default: () => [] },
   dirtyClass: { type: String, required: false, default: "form-data-dirty" },
   dirtyOnCreate: { type: Boolean, required: false, default: false },
-  sanitizeDelay: { type: Number, required: false, default: 2e3 }
+  sanitizeDelay: { type: Number, required: false, default: 5e3 }
 });
 const emit = defineEmits(["update:modelValue"]);
 const disabled = ref(props.disabled);
@@ -53,7 +53,16 @@ const formData = ref({});
 function isBlankString(v) {
   return isString(v) && v.trim().length === 0;
 }
-const sanitizeBlankStrings = debounce(sanitizeBlankStringsRaw, props.sanitizeDelay);
+function scheduleIdle(fn) {
+  if (typeof window !== "undefined" && typeof window.requestIdleCallback === "function") {
+    window.requestIdleCallback(fn, { timeout: 2e3 });
+  } else {
+    setTimeout(fn, 0);
+  }
+}
+const sanitizeBlankStrings = debounce((val, original) => {
+  scheduleIdle(() => sanitizeBlankStringsRaw(val, original));
+}, props.sanitizeDelay);
 function sanitizeBlankStringsRaw(val, original) {
   if (!original && props.originalData) {
     sanitizeBlankStrings(val, props.originalData);

package/dist/runtime/components/form/Table.d.vue.ts

@@ -25,6 +25,8 @@ interface Props extends /* @vue-ignore */ InstanceType<typeof VDataTable['$props
     inputPadOnly?: boolean;
     saveAndStay?: boolean;
     stringFields?: Array<string>;
+    perPageStorageKey?: string;
+    perPageStorageEnabled?: boolean;
 }
 /**
  * Public props accepted by FormTable.
@@ -136,6 +138,7 @@ declare const __VLS_base: import("vue").DefineComponent<import("vue").ExtractPro
     inputPadOnly: boolean;
     saveAndStay: boolean;
     stringFields: () => never[];
+    perPageStorageEnabled: boolean;
 }>>, {
     errorMessages: import("vue").ComputedRef<(string & string[]) | (readonly string[] & string[]) | undefined>;
     isValid: import("vue").ComputedRef<boolean | null | undefined>;
@@ -188,6 +191,7 @@ declare const __VLS_base: import("vue").DefineComponent<import("vue").ExtractPro
     inputPadOnly: boolean;
     saveAndStay: boolean;
     stringFields: () => never[];
+    perPageStorageEnabled: boolean;
 }>>> & Readonly<{
     "onUpdate:modelValue"?: ((...args: any[]) => any) | undefined;
     "onOpen:dialog"?: ((...args: any[]) => any) | undefined;

package/dist/runtime/components/form/Table.vue

@@ -5,6 +5,7 @@ import { computed, nextTick, ref, useAttrs, watch, useTemplateRef } from "vue";
 import { omit } from "lodash-es";
 import { useDialog } from "../../composables/dialog";
 import { useLocalStorageModel } from "../../composables/localStorageModel";
+import { usePerPagePreference } from "../../composables/perPagePreference";
 defineOptions({
   inheritAttrs: false
 });
@@ -28,6 +29,8 @@ const props = defineProps({
   inputPadOnly: { type: Boolean, required: false, default: false },
   saveAndStay: { type: Boolean, required: false, default: false },
   stringFields: { type: Array, required: false, default: () => [] },
+  perPageStorageKey: { type: String, required: false },
+  perPageStorageEnabled: { type: Boolean, required: false, default: true },
   persist: { type: Boolean, required: false },
   persistKey: { type: String, required: false },
   persistPrefix: { type: String, required: false },
@@ -47,7 +50,12 @@ const inputRef = useTemplateRef("inputRef");
 const items = ref([]);
 const search = ref();
 const currentItem = ref(void 0);
+const itemsPerPageInternal = ref();
 useLocalStorageModel(items, props);
+usePerPagePreference(itemsPerPageInternal, {
+  storageKey: props.perPageStorageKey,
+  enabled: props.perPageStorageEnabled
+});
 function setSearch(keyword) {
   search.value = keyword;
 }
@@ -234,6 +242,7 @@ defineExpose({
           </slot>
           <v-data-table
               v-bind="plainAttrs"
+              v-model:items-per-page="itemsPerPageInternal"
               color="primary"
               :items="items"
               :search="search"

package/dist/runtime/components/form/Table.vue.d.ts

@@ -25,6 +25,8 @@ interface Props extends /* @vue-ignore */ InstanceType<typeof VDataTable['$props
     inputPadOnly?: boolean;
     saveAndStay?: boolean;
     stringFields?: Array<string>;
+    perPageStorageKey?: string;
+    perPageStorageEnabled?: boolean;
 }
 /**
  * Public props accepted by FormTable.
@@ -136,6 +138,7 @@ declare const __VLS_base: import("vue").DefineComponent<import("vue").ExtractPro
     inputPadOnly: boolean;
     saveAndStay: boolean;
     stringFields: () => never[];
+    perPageStorageEnabled: boolean;
 }>>, {
     errorMessages: import("vue").ComputedRef<(string & string[]) | (readonly string[] & string[]) | undefined>;
     isValid: import("vue").ComputedRef<boolean | null | undefined>;
@@ -188,6 +191,7 @@ declare const __VLS_base: import("vue").DefineComponent<import("vue").ExtractPro
     inputPadOnly: boolean;
     saveAndStay: boolean;
     stringFields: () => never[];
+    perPageStorageEnabled: boolean;
 }>>> & Readonly<{
     "onUpdate:modelValue"?: ((...args: any[]) => any) | undefined;
     "onOpen:dialog"?: ((...args: any[]) => any) | undefined;

package/dist/runtime/components/form/images/Field.vue

@@ -20,7 +20,7 @@ const images = ref([]);
 const uploadImages = ref([]);
 const dialog = ref(false);
 const dialogUpdate = ref(false);
-const dataUpdate = ref({ imageData: {}, imageTitle: "", imageProps: {} });
+const dataUpdateIndex = ref(null);
 const dialogImageFullScreen = ref(false);
 const imageFullScreen = ref({ title: "", image: "" });
 let internalSync = false;
@@ -59,14 +59,15 @@ const addImage = (img) => {
 const remove = (index) => {
   images.value.splice(index, 1);
 };
-const setDataUpdate = (img) => {
-  dataUpdate.value = {
-    imageData: { ...img.imageData ?? {} },
-    imageTitle: img.imageTitle ?? "",
-    imageProps: { ...img.imageProps ?? {} }
-  };
+const setDataUpdate = (index) => {
+  if (index < 0 || index >= images.value.length) return;
+  dataUpdateIndex.value = index;
   dialogUpdate.value = true;
 };
+const closeUpdateDialog = () => {
+  dialogUpdate.value = false;
+  dataUpdateIndex.value = null;
+};
 const checkDuplicationName = (name) => images.value.some(({ imageTitle }) => isEqual(imageTitle, name));
 const isImageDataUrl = (dataUrl) => /^data:image\//i.test(dataUrl);
 const imageSrcFromImageData = (imageData) => {
@@ -209,7 +210,7 @@ defineExpose({
                           <v-btn icon @click="remove(index)" :disabled="isDisabled?.value" :readonly="isReadonly?.value">
                             <v-icon>mdi mdi-delete-outline</v-icon>
                           </v-btn>
-                          <v-btn color="primary" icon @click="setDataUpdate(image)" v-if="!image.imageData?.id" :disabled="isDisabled?.value" :readonly="isReadonly?.value">
+                          <v-btn color="primary" icon @click="setDataUpdate(index)" v-if="!image.imageData?.id" :disabled="isDisabled?.value" :readonly="isReadonly?.value">
                             <v-icon>mdi mdi-image-edit-outline</v-icon>
                           </v-btn>
                         </VToolbarItems>
@@ -219,7 +220,7 @@ defineExpose({
                           :src="imageSrcFromImageData(image)"
                           height="250"
                           @click="() => {
-  props.readonly || image.imageData?.id || isReadonly?.value ? openImageFullScreen(image) : setDataUpdate(image);
+  props.readonly || image.imageData?.id || isReadonly?.value ? openImageFullScreen(image) : setDataUpdate(index);
 }"
                           :disabled="isDisabled?.value"
                       />
@@ -235,8 +236,9 @@ defineExpose({
       <!-- Edit dialog -->
       <VDialog v-model="dialogUpdate" fullscreen transition="dialog-bottom-transition">
         <FormImagesPad
-            v-model="dataUpdate.imageData.base64String"
-            @closedDialog="dialogUpdate = false"
+          v-if="dialogUpdate && dataUpdateIndex !== null && images[dataUpdateIndex]"
+          v-model="images[dataUpdateIndex].imageData.base64String"
+          @closedDialog="closeUpdateDialog"
         />
       </VDialog>
 

package/dist/runtime/components/model/Table.d.vue.ts

@@ -21,6 +21,8 @@ interface Props extends /* @vue-ignore */ InstanceType<typeof VDataTable['$props
     onlyOwnerEdit?: boolean;
     onlyOwnerOverridePermission?: string | string[];
     api?: boolean;
+    perPageStorageKey?: string;
+    perPageStorageEnabled?: boolean;
 }
 /**
  * Public props accepted by ModelTable.
@@ -164,6 +166,7 @@ declare const __VLS_base: import("vue").DefineComponent<import("vue").ExtractPro
     stringFields: () => never[];
     onlyOwnerEdit: boolean;
     api: boolean;
+    perPageStorageEnabled: boolean;
 }>>, {
     reload: () => void;
     operation: import("vue").Ref<{
@@ -240,6 +243,7 @@ declare const __VLS_base: import("vue").DefineComponent<import("vue").ExtractPro
     stringFields: () => never[];
     onlyOwnerEdit: boolean;
     api: boolean;
+    perPageStorageEnabled: boolean;
 }>>> & Readonly<{
     onDelete?: ((...args: any[]) => any) | undefined;
     onCreate?: ((...args: any[]) => any) | undefined;

package/dist/runtime/components/model/Table.vue

@@ -4,6 +4,7 @@ import { VDataTable } from "vuetify/components/VDataTable";
 import { clone } from "lodash-es";
 import { useGraphqlModel } from "../../composables/graphqlModel";
 import { useApiModel } from "../../composables/apiModel";
+import { usePerPagePreference } from "../../composables/perPagePreference";
 import { useDialog } from "../../composables/dialog";
 import { useUserPermission } from "../../composables/userPermission";
 import { useState } from "#imports";
@@ -30,6 +31,8 @@ const props = defineProps({
   onlyOwnerEdit: { type: Boolean, required: false, default: false },
   onlyOwnerOverridePermission: { type: [String, Array], required: false },
   api: { type: Boolean, required: false, default: false },
+  perPageStorageKey: { type: String, required: false },
+  perPageStorageEnabled: { type: Boolean, required: false, default: true },
   modelName: { type: String, required: true },
   modelKey: { type: String, required: false, default: "id" },
   modelBy: { type: Object, required: false, default: void 0 },
@@ -57,6 +60,11 @@ const currentUsername = computed(() => {
 const currentItem = ref(void 0);
 const isDialogOpen = ref(false);
 const isDialogReadonly = ref(false);
+const itemsPerPageInternal = ref();
+usePerPagePreference(itemsPerPageInternal, {
+  storageKey: props.perPageStorageKey ?? props.modelName,
+  enabled: props.perPageStorageEnabled
+});
 const {
   items,
   itemsLength,
@@ -208,6 +216,7 @@ defineExpose({ reload, operation, items });
     <v-data-table-server
       v-if="canServerPageable"
       v-bind="plainAttrs"
+      v-model:items-per-page="itemsPerPageInternal"
       color="primary"
       :items="items"
       :items-length="itemsLength"
@@ -258,6 +267,7 @@ defineExpose({ reload, operation, items });
     <v-data-table
       v-else
       v-bind="plainAttrs"
+      v-model:items-per-page="itemsPerPageInternal"
       color="primary"
       :items="items"
       :item-value="props.modelKey"

package/dist/runtime/components/model/Table.vue.d.ts

@@ -21,6 +21,8 @@ interface Props extends /* @vue-ignore */ InstanceType<typeof VDataTable['$props
     onlyOwnerEdit?: boolean;
     onlyOwnerOverridePermission?: string | string[];
     api?: boolean;
+    perPageStorageKey?: string;
+    perPageStorageEnabled?: boolean;
 }
 /**
  * Public props accepted by ModelTable.
@@ -164,6 +166,7 @@ declare const __VLS_base: import("vue").DefineComponent<import("vue").ExtractPro
     stringFields: () => never[];
     onlyOwnerEdit: boolean;
     api: boolean;
+    perPageStorageEnabled: boolean;
 }>>, {
     reload: () => void;
     operation: import("vue").Ref<{
@@ -240,6 +243,7 @@ declare const __VLS_base: import("vue").DefineComponent<import("vue").ExtractPro
     stringFields: () => never[];
     onlyOwnerEdit: boolean;
     api: boolean;
+    perPageStorageEnabled: boolean;
 }>>> & Readonly<{
     onDelete?: ((...args: any[]) => any) | undefined;
     onCreate?: ((...args: any[]) => any) | undefined;

package/dist/runtime/components/model/iterator.d.vue.ts

@@ -27,6 +27,8 @@ interface Props extends /* @vue-ignore */ InstanceType<typeof VDataIterator['$pr
     preferTableMd?: string | number | boolean;
     preferTableSm?: string | number | boolean;
     api?: boolean;
+    perPageStorageKey?: string;
+    perPageStorageEnabled?: boolean;
 }
 /**
  * Public props accepted by ModelIterator.
@@ -232,6 +234,7 @@ declare const __VLS_base: import("vue").DefineComponent<import("vue").ExtractPro
     sm: number;
     itemsPerPage: number;
     api: boolean;
+    perPageStorageEnabled: boolean;
 }>>, {
     reload: () => void;
     operation: import("vue").Ref<{
@@ -295,6 +298,7 @@ declare const __VLS_base: import("vue").DefineComponent<import("vue").ExtractPro
     sm: number;
     itemsPerPage: number;
     api: boolean;
+    perPageStorageEnabled: boolean;
 }>>> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
 declare const _default: typeof __VLS_export;

package/dist/runtime/components/model/iterator.vue

@@ -5,6 +5,7 @@ import { VDataTable } from "vuetify/components/VDataTable";
 import { omit } from "lodash-es";
 import { useGraphqlModel } from "../../composables/graphqlModel";
 import { useApiModel } from "../../composables/apiModel";
+import { usePerPagePreference } from "../../composables/perPagePreference";
 import { useDisplay } from "vuetify";
 defineOptions({
   inheritAttrs: false
@@ -36,6 +37,8 @@ const props = defineProps({
   preferTableMd: { type: [String, Number, Boolean], required: false },
   preferTableSm: { type: [String, Number, Boolean], required: false },
   api: { type: Boolean, required: false, default: false },
+  perPageStorageKey: { type: String, required: false },
+  perPageStorageEnabled: { type: Boolean, required: false, default: true },
   modelName: { type: String, required: true },
   modelKey: { type: String, required: false, default: "id" },
   modelBy: { type: Object, required: false, default: void 0 },
@@ -122,6 +125,10 @@ watch(() => props.itemsPerPage, (newValue) => {
   if (newValue.toString().toLowerCase() == "all") itemsPerPageInternal.value = "-1";
   else if (newValue) itemsPerPageInternal.value = newValue;
 }, { immediate: true });
+usePerPagePreference(itemsPerPageInternal, {
+  storageKey: props.perPageStorageKey ?? props.modelName,
+  enabled: props.perPageStorageEnabled
+});
 const sortBy = ref();
 const pageCount = computed(() => {
   if (!itemsPerPageInternal.value || itemsPerPageInternal.value == "All" || itemsPerPageInternal.value == "-1" || Number(itemsPerPageInternal.value) <= 0) return 1;

package/dist/runtime/components/model/iterator.vue.d.ts

@@ -27,6 +27,8 @@ interface Props extends /* @vue-ignore */ InstanceType<typeof VDataIterator['$pr
     preferTableMd?: string | number | boolean;
     preferTableSm?: string | number | boolean;
     api?: boolean;
+    perPageStorageKey?: string;
+    perPageStorageEnabled?: boolean;
 }
 /**
  * Public props accepted by ModelIterator.
@@ -232,6 +234,7 @@ declare const __VLS_base: import("vue").DefineComponent<import("vue").ExtractPro
     sm: number;
     itemsPerPage: number;
     api: boolean;
+    perPageStorageEnabled: boolean;
 }>>, {
     reload: () => void;
     operation: import("vue").Ref<{
@@ -295,6 +298,7 @@ declare const __VLS_base: import("vue").DefineComponent<import("vue").ExtractPro
     sm: number;
     itemsPerPage: number;
     api: boolean;
+    perPageStorageEnabled: boolean;
 }>>> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
 declare const _default: typeof __VLS_export;

package/dist/runtime/composables/api.d.ts

@@ -21,6 +21,27 @@
  * so users can see stale empty / outdated lists for the full TTL window even after
  * creating data themselves.
  *
+ * Idempotency: every authenticated POST (REST and GraphQL via useGraphQl()) automatically
+ * receives an `Idempotency-Key` HTTP header. The value is computed client-side as
+ *
+ *   SHA-256(`${floor(Date.now()/1000)}|${username}|${stableStringify(body ?? {})}`)
+ *
+ * in lowercase hex. The recipe is intentionally identical to the backend's server-side
+ * fallback in rama-spring-starter's @IdempotentMutation aspect, so a header-present and
+ * a header-absent request from the same user with the same body within the same wall-clock
+ * second resolve to the same dedup signature.
+ *
+ * Per-call escape hatch: pass `{ idempotent: false }` in the options argument to skip
+ * injection for a single call (e.g. a long-running mutation the caller wants to retry
+ * intentionally with the same body). A caller-supplied `Idempotency-Key` in
+ * `options.headers` always wins and is never overwritten.
+ *
+ * Configuration (consumer's `nuxt.config` `runtimeConfig.public`, mirroring the
+ * unprefixed `WS_API` / `WS_GRAPHQL` precedent):
+ *   - IDEMPOTENCY_HEADER (default 'Idempotency-Key') — must match the backend's
+ *     `rama.idempotency.header-name` setting if the consumer overrides it there.
+ *   - IDEMPOTENCY_ENABLED (default true) — global kill switch.
+ *
  * This doc block is consumed by vue-docgen for generated API documentation.
  */
 import type { UseFetchOptions } from 'nuxt/app';
@@ -35,6 +56,16 @@ export type CacheOption = boolean | number | {
 } | {
     ttlMs: number;
 };
+/**
+ * Per-call options accepted by useApi alongside Nuxt's UseFetchOptions.
+ *
+ * `idempotent: false` skips Idempotency-Key header injection for this single call.
+ * Default is `true`. See the useApi() docblock for the full idempotency contract.
+ */
+export interface ApiIdempotencyOption {
+    idempotent?: boolean;
+}
+export type ApiFetchOptions = UseFetchOptions<unknown> & ApiIdempotencyOption;
 export declare function _resetLegacyHeuristicWarning(): void;
 /**
  * Resolve a cache option to seconds. Pure function, exported for tests.
@@ -60,10 +91,10 @@ export declare function resolveCacheTtlSeconds(cache: CacheOption | undefined |
 declare function invalidateCache(prefix?: string): number;
 export declare function useApi(): {
     urlBuilder: (url: string | string[]) => string;
-    get: <T>(url: string | string[], body?: Record<string, any> | [], params?: SearchParameters, options?: UseFetchOptions<unknown>, cache?: CacheOption) => Promise<T>;
-    getPromise: <T>(url: string | string[], body?: Record<string, any> | [], params?: SearchParameters, options?: UseFetchOptions<unknown>, cache?: CacheOption) => Promise<T>;
-    post: <T>(url: string | string[], body?: Record<string, any> | [], params?: SearchParameters, options?: UseFetchOptions<unknown>, cache?: CacheOption) => Promise<T>;
-    postPromise: <T>(url: string | string[], body?: Record<string, any> | [], params?: SearchParameters, options?: UseFetchOptions<unknown>, cache?: CacheOption) => Promise<T>;
+    get: <T>(url: string | string[], body?: Record<string, any> | [], params?: SearchParameters, options?: ApiFetchOptions, cache?: CacheOption) => Promise<T>;
+    getPromise: <T>(url: string | string[], body?: Record<string, any> | [], params?: SearchParameters, options?: ApiFetchOptions, cache?: CacheOption) => Promise<T>;
+    post: <T>(url: string | string[], body?: Record<string, any> | [], params?: SearchParameters, options?: ApiFetchOptions, cache?: CacheOption) => Promise<T>;
+    postPromise: <T>(url: string | string[], body?: Record<string, any> | [], params?: SearchParameters, options?: ApiFetchOptions, cache?: CacheOption) => Promise<T>;
     hashKey: (data: any) => Promise<string>;
     invalidate: typeof invalidateCache;
 };

package/dist/runtime/composables/api.js

@@ -7,6 +7,7 @@ import { useRuntimeConfig } from "#imports";
 import { useAuthentication } from "../bridges/authentication.js";
 const DEFAULT_TTL_SECONDS_FOR_TRUE = 5 * 60;
 const CACHE_PREFIX = "api-cache-";
+const IDEMPOTENCY_HEADER_DEFAULT = "Idempotency-Key";
 let _legacyHeuristicWarned = false;
 function warnLegacyHeuristic(value, resolvedSeconds) {
   if (_legacyHeuristicWarned) return;
@@ -77,7 +78,7 @@ export function useApi() {
     if (returnUrl.startsWith("http://") || returnUrl.startsWith("https://")) return returnUrl;
     return trimEnd(config?.public.WS_API, "/") + "/" + trimStart(returnUrl, "/");
   }
-  function optionBuilder(method, body, params, options = {}) {
+  async function optionBuilder(method, body, params, options = {}) {
     const headers = {
       "Content-Type": "application/json",
       Accept: "application/json"
@@ -85,9 +86,24 @@ export function useApi() {
     const auth = useAuthentication();
     const token = auth.keycloak?.token || auth.token;
     if (token) {
-      ;
       headers["Authorization"] = `Bearer ${token}`;
     }
+    const callerHeaders = {
+      ...options.headers || {}
+    };
+    const enabledConfig = config?.public?.IDEMPOTENCY_ENABLED;
+    const idempotencyEnabled = enabledConfig !== false;
+    const headerName = config?.public?.IDEMPOTENCY_HEADER || IDEMPOTENCY_HEADER_DEFAULT;
+    const callerProvidedHeader = Object.keys(callerHeaders).some(
+      (k) => k.toLowerCase() === headerName.toLowerCase()
+    );
+    if (method === "POST" && idempotencyEnabled && options.idempotent !== false && !callerProvidedHeader) {
+      const username = (typeof auth.getUsername === "function" ? auth.getUsername() : auth.userProfile?.username) ?? "";
+      const second = Math.floor(Date.now() / 1e3).toString();
+      const bodyJson = stableStringify(body ?? {});
+      headers[headerName] = await sha256(`${second}|${username}|${bodyJson}`);
+    }
+    const { idempotent: _omitIdempotent, ...passThroughOptions } = options;
     const baseOptions = {
       method,
       body,
@@ -96,9 +112,9 @@ export function useApi() {
     };
     const finalHeaders = {
       ...headers,
-      ...options.headers || {}
+      ...callerHeaders
     };
-    Object.assign(baseOptions, options);
+    Object.assign(baseOptions, passThroughOptions);
     return {
       ...baseOptions,
       headers: finalHeaders
@@ -132,7 +148,7 @@ export function useApi() {
     const builtUrl = urlBuilder(url);
     const ttl = resolveCacheTtlSeconds(cache);
     if (ttl === 0) {
-      return ofetch(builtUrl, optionBuilder(method, body, params, options));
+      return ofetch(builtUrl, await optionBuilder(method, body, params, options));
     }
     const keyData = { url: builtUrl, method, body, params, headers: options?.headers };
     const key = CACHE_PREFIX + await hashKey(keyData);
@@ -140,7 +156,7 @@ export function useApi() {
     if (cached !== null) {
       return cached;
     }
-    const result = await ofetch(builtUrl, optionBuilder(method, body, params, options));
+    const result = await ofetch(builtUrl, await optionBuilder(method, body, params, options));
     ls.set(key, result, { ttl });
     return result;
   }

package/dist/runtime/composables/document/template.js

@@ -2,6 +2,7 @@ import { processTemplateFormTable } from "./templateFormTable.js";
 import { processTemplateFormTableData } from "./templateFormTableData.js";
 import { processTemplateFormHidden } from "./templateFormHidden.js";
 import { some, includes, cloneDeep } from "lodash-es";
+import { migrateInputAttributes, migrateTemplateString } from "./templateMigrate.js";
 export const validationRulesRegex = /^(require(?:\([^)]*\))?|requireIf\([^)]*\)|requireTrue(?:\([^)]*\))?|requireTrueIf\([^)]*\)|numeric(?:\([^)]*\))?|range\([^)]*\)|integer(?:\([^)]*\))?|unique\([^)]*\)|length(?:\([^)]*\))?|lengthGreater\([^)]*\)|lengthLess\([^)]*\)|telephone(?:\([^)]*\))?|email(?:\([^)]*\))?|regex\([^)]*\)|idcard(?:\([^)]*\))?|DateFuture(?:\([^)]*\))?|DatetimeFuture(?:\([^)]*\))?|DateHappen(?:\([^)]*\))?|DatetimeHappen(?:\([^)]*\))?|DateAfter\([^)]*\)|DateBefore\([^)]*\)|DateEqual\([^)]*\))(,(require(?:\([^)]*\))?|requireIf\([^)]*\)|requireTrue(?:\([^)]*\))?|requireTrueIf\([^)]*\)|numeric(?:\([^)]*\))?|range\([^)]*\)|integer(?:\([^)]*\))?|unique\([^)]*\)|length(?:\([^)]*\))?|lengthGreater\([^)]*\)|lengthLess\([^)]*\)|telephone(?:\([^)]*\))?|email(?:\([^)]*\))?|regex\([^)]*\)|idcard(?:\([^)]*\))?|DateFuture(?:\([^)]*\))?|DatetimeFuture(?:\([^)]*\))?|DateHappen(?:\([^)]*\))?|DatetimeHappen(?:\([^)]*\))?|DateAfter\([^)]*\)|DateBefore\([^)]*\)|DateEqual\([^)]*\)))*$/;
 export function useDocumentTemplate(items, parentTemplates) {
   if (!items) return "";
@@ -16,11 +17,12 @@ export function useDocumentTemplate(items, parentTemplates) {
     return "";
   }
   const templateString = items.map((item) => columnWrapTemplateItemString(item, parentTemplates || [])).join("");
-  return !parentTemplates || parentTemplates.length == 0 ? `<v-container fluid><v-row density='compact'>${templateString}</v-row></v-container>` : `<v-row density='compact'>${templateString}</v-row>`;
+  const wrapped = !parentTemplates || parentTemplates.length == 0 ? `<v-container fluid><v-row density='compact'>${templateString}</v-row></v-container>` : `<v-row density='compact'>${templateString}</v-row>`;
+  return migrateTemplateString(wrapped);
 }
 export function templateItemToString(inputItem, parentTemplates, dataVariable = "data") {
   let item = cloneDeep(inputItem);
-  item.inputAttributes = item.inputAttributes?.trim() || "";
+  item.inputAttributes = migrateInputAttributes(item.inputAttributes?.trim() || "", item.inputType);
   let optionString = "";
   if (item.inputOptions) {
     if (item.inputType === "MasterAutocomplete") {
@@ -45,8 +47,8 @@ export function templateItemToString(inputItem, parentTemplates, dataVariable =
   if (item.conditionalDisplay) {
     item.inputAttributes = `${item.inputAttributes?.trim() || ""} v-if="${item.conditionalDisplay}"`.trim();
   }
-  if (item.inputType === "FormDateTime" && !item.inputAttributes?.includes("dense")) {
-    item.inputAttributes = `${item.inputAttributes?.trim() || ""} dense`.trim();
+  if (item.inputType === "FormDateTime" && !item.inputAttributes?.includes("density")) {
+    item.inputAttributes = `${item.inputAttributes?.trim() || ""} density="compact"`.trim();
   }
   let templateString;
   const validationRules = item.validationRules ? buildValidationRules(item.validationRules) || "" : "";

package/dist/runtime/composables/document/templateMigrate.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Render-time migration helper that rewrites Vuetify 3 attribute syntax to
+ * Vuetify 4 inside Document templates. Used by `useDocumentTemplate`.
+ *
+ * Rules without `appliesTo` are universally safe and run in both the per-item
+ * pre-pass and the post-pass on the assembled template string. Rules with
+ * `appliesTo` only run in the pre-pass and only when `item.inputType` (or the
+ * tag name) matches.
+ *
+ * See `docs/superpowers/specs/2026-04-26-document-template-vuetify4-migration-design.md`.
+ */
+export interface Vuetify4MigrationRule {
+    /** v3 bare boolean attribute name, e.g. 'dense'. */
+    from: string;
+    /** v4 replacement attribute incl. value, e.g. 'density="compact"'. */
+    to: string;
+    /**
+     * Optional whitelist of input types / tag names the rule applies to. If
+     * omitted, the rule is universally safe and also runs in the post-pass.
+     */
+    appliesTo?: string[];
+}
+/** Default rule table. Mutable / extensible by callers. */
+export declare const vuetify4MigrationRules: Vuetify4MigrationRule[];
+/**
+ * Walk an attribute string (the part inside `<tag …>`), replacing each bare
+ * boolean attribute that matches a rule with the rule's replacement. Skips
+ * text inside quoted attribute values. Internal — exported for unit tests.
+ */
+export declare function migrateAttributeString(attrs: string, applicableRules: Vuetify4MigrationRule[]): string;
+/**
+ * Per-item pre-pass. Filter the rule set to rules that apply to `inputType`
+ * (rules with no `appliesTo` always apply), then rewrite the attribute string.
+ */
+export declare function migrateInputAttributes(attrs: string, inputType: string, rules?: Vuetify4MigrationRule[]): string;
+/**
+ * Post-pass on the assembled template string. Walks opening tags (skipping
+ * closing tags and comments), extracts each tag's attribute region with
+ * quote-awareness so `>` inside `"…"` does not prematurely end the tag, then
+ * rewrites the attributes using only rules that have no `appliesTo` — those
+ * are universally safe to apply across both Vuetify and custom components.
+ */
+export declare function migrateTemplateString(template: string, rules?: Vuetify4MigrationRule[]): string;

package/dist/runtime/composables/document/templateMigrate.js

@@ -0,0 +1,118 @@
+const VARIANT_APPLIES_TO = [
+  "VTextField",
+  "VSelect",
+  "VAutocomplete",
+  "VCombobox",
+  "VTextarea",
+  "VFileInput",
+  "VCard",
+  "FormDate",
+  "FormTime",
+  "FormDateTime",
+  "MasterAutocomplete",
+  "ModelAutocomplete",
+  "ModelSelect",
+  "ModelCombobox"
+];
+export const vuetify4MigrationRules = [
+  { from: "dense", to: 'density="compact"' },
+  { from: "outlined", to: 'variant="outlined"', appliesTo: VARIANT_APPLIES_TO },
+  { from: "filled", to: 'variant="filled"', appliesTo: VARIANT_APPLIES_TO },
+  { from: "solo", to: 'variant="solo"', appliesTo: VARIANT_APPLIES_TO },
+  { from: "flat", to: 'variant="flat"', appliesTo: ["VCard"] }
+];
+export function migrateAttributeString(attrs, applicableRules) {
+  if (!attrs || applicableRules.length === 0) return attrs;
+  let result = "";
+  let lastFlushed = 0;
+  let i = 0;
+  let inQuote = null;
+  while (i < attrs.length) {
+    const ch = attrs[i];
+    if (inQuote) {
+      if (ch === inQuote) inQuote = null;
+      i++;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      inQuote = ch;
+      i++;
+      continue;
+    }
+    if (i === 0 || /\s/.test(attrs[i - 1])) {
+      let matched = false;
+      for (const rule of applicableRules) {
+        const word = rule.from;
+        if (attrs.slice(i, i + word.length) !== word) continue;
+        const after = i + word.length;
+        if (after !== attrs.length && !/\s/.test(attrs[after])) continue;
+        result += attrs.slice(lastFlushed, i);
+        result += rule.to;
+        lastFlushed = after;
+        i = after;
+        matched = true;
+        break;
+      }
+      if (matched) continue;
+    }
+    i++;
+  }
+  result += attrs.slice(lastFlushed);
+  return result;
+}
+export function migrateInputAttributes(attrs, inputType, rules = vuetify4MigrationRules) {
+  if (!attrs) return "";
+  const applicable = rules.filter((r) => !r.appliesTo || r.appliesTo.includes(inputType));
+  return migrateAttributeString(attrs, applicable);
+}
+export function migrateTemplateString(template, rules = vuetify4MigrationRules) {
+  if (!template) return template;
+  const applicable = rules.filter((r) => !r.appliesTo);
+  if (applicable.length === 0) return template;
+  let result = "";
+  let i = 0;
+  while (i < template.length) {
+    const ch = template[i];
+    if (ch !== "<") {
+      result += ch;
+      i++;
+      continue;
+    }
+    if (template[i + 1] === "/" || template[i + 1] === "!") {
+      result += ch;
+      i++;
+      continue;
+    }
+    const nameMatch = /^[a-z][\w:-]*/i.exec(template.slice(i + 1));
+    if (!nameMatch) {
+      result += ch;
+      i++;
+      continue;
+    }
+    const tagName = nameMatch[0];
+    const attrsStart = i + 1 + tagName.length;
+    let j = attrsStart;
+    let inQuote = null;
+    while (j < template.length) {
+      const c = template[j];
+      if (inQuote) {
+        if (c === inQuote) inQuote = null;
+      } else if (c === '"' || c === "'") {
+        inQuote = c;
+      } else if (c === ">") {
+        break;
+      }
+      j++;
+    }
+    if (j >= template.length) {
+      result += template.slice(i);
+      break;
+    }
+    const tagEnd = template[j - 1] === "/" ? j - 1 : j;
+    const attrs = template.slice(attrsStart, tagEnd);
+    const closing = template.slice(tagEnd, j + 1);
+    result += `<${tagName}${migrateAttributeString(attrs, applicable)}${closing}`;
+    i = j + 1;
+  }
+  return result;
+}

package/dist/runtime/composables/localStorageModel.js

@@ -21,10 +21,11 @@ export function useLocalStorageModel(model, props, options) {
   function read() {
     if (!storageKey.value) return void 0;
     try {
-      return ls.get(storageKey.value, {
-        decrypt: !!props.persistEncrypt,
-        secret: props.persistSecret
-      });
+      const opts = {
+        decrypt: !!props.persistEncrypt
+      };
+      if (props.persistSecret !== void 0) opts.secret = props.persistSecret;
+      return ls.get(storageKey.value, opts);
     } catch {
       return void 0;
     }
@@ -32,12 +33,13 @@ export function useLocalStorageModel(model, props, options) {
   function write(val) {
     if (!storageKey.value) return;
     try {
-      ls.set(storageKey.value, serializer(val), {
+      const opts = {
         ttl: props.persistTtl,
         // seconds
-        encrypt: !!props.persistEncrypt,
-        secret: props.persistSecret
-      });
+        encrypt: !!props.persistEncrypt
+      };
+      if (props.persistSecret !== void 0) opts.secret = props.persistSecret;
+      ls.set(storageKey.value, serializer(val), opts);
     } catch {
     }
   }

package/dist/runtime/composables/lookupListMaster.js

@@ -31,15 +31,15 @@ export function useLookupListMaster(props) {
     );
   });
   const formatItemTitle = (item) => {
+    const raw = item?.raw ?? item ?? {};
+    const resolvedTitle = item?.title || raw?.[itemTitleField.value] || raw?.itemValue || raw?.itemCode;
     if (props.meilisearch) {
-      const raw = item?._formatted ?? {};
-      const code = raw?.itemCode;
-      const title = raw?.[itemTitleField.value] ?? raw?.itemValue ?? raw?.itemCode;
+      const formatted = raw?._formatted ?? {};
+      const code = formatted?.itemCode ?? raw?.itemCode;
+      const title = formatted?.[itemTitleField.value] || formatted?.itemValue || formatted?.itemCode || resolvedTitle;
       return (props.showCode ? (code ?? "") + "-" : "") + (title ?? "");
     } else {
-      const code = item?.itemCode;
-      const title = item.title ?? item?.itemValue ?? item?.itemCode;
-      return (props.showCode ? (code ?? "") + "-" : "") + (title ?? "");
+      return (props.showCode ? (raw?.itemCode ?? "") + "-" : "") + (resolvedTitle ?? "");
     }
   };
   const computedNoDataText = computed(() => {

package/dist/runtime/composables/perPagePreference.d.ts

@@ -0,0 +1,41 @@
+/**
+ * usePerPagePreference persists a paginated component's items-per-page selection
+ * in localStorage, namespaced by the currently logged-in user and the active
+ * route. Built on top of `useLocalStorageModel` so it inherits the existing
+ * encryption + TTL + debounced-write behavior backed by `localstorage-slim`.
+ *
+ * The full storage key is composed as:
+ *
+ *   nuxt-commons:perPage:<username|anon>:<route.path>:<storageKey>
+ *
+ * If `storageKey` is empty/undefined, persistence is disabled and the function
+ * is a no-op (so callers can opt-in safely without breaking existing usage).
+ */
+import { type Ref } from 'vue';
+export interface PerPagePreferenceOptions {
+    /**
+     * Logical key identifying the table/iterator instance (e.g. `modelName`).
+     *  Persistence is disabled when this is empty.
+     */
+    storageKey?: string;
+    /** TTL in seconds — defaults to 90 days. */
+    ttlSeconds?: number;
+    /** Encrypt the stored value via localstorage-slim — defaults to `true`. */
+    encrypt?: boolean;
+    /** Optional encryption secret. When omitted, localstorage-slim derives one. */
+    secret?: string;
+    /** Debounce window for writes, in ms — defaults to 200. */
+    debounceMs?: number;
+    /**
+     * Explicit opt-out switch — when `false`, the composable becomes a no-op
+     *  even if `storageKey` is set.
+     */
+    enabled?: boolean;
+}
+export declare function usePerPagePreference(perPage: Ref<string | number | undefined>, options?: PerPagePreferenceOptions): {
+    isHydrated: Ref<boolean, boolean>;
+    storageKey: import("vue").ComputedRef<string>;
+    remove: () => void;
+    read: () => unknown;
+    write: (val: string | number | undefined) => void;
+};

package/dist/runtime/composables/perPagePreference.js

@@ -0,0 +1,55 @@
+import { computed } from "vue";
+import { useState, useRoute } from "#imports";
+import { useLocalStorageModel } from "./localStorageModel.js";
+function safeRoutePath() {
+  try {
+    const route = useRoute();
+    return route?.path || "";
+  } catch {
+    return "";
+  }
+}
+const DEFAULT_TTL_SECONDS = 90 * 24 * 60 * 60;
+export function usePerPagePreference(perPage, options = {}) {
+  const authState = useState("authentication", () => ({}));
+  const username = computed(() => {
+    const profile = authState.value?.userProfile;
+    return profile?.username?.trim() || "anon";
+  });
+  const routePath = computed(() => safeRoutePath());
+  const persistKey = computed(() => {
+    const key = options.storageKey?.trim();
+    if (!key || options.enabled === false) return "";
+    return `${username.value}:${routePath.value}:${key}`;
+  });
+  return useLocalStorageModel(
+    perPage,
+    {
+      persist: !!persistKey.value,
+      persistKey: persistKey.value,
+      persistPrefix: "nuxt-commons:perPage",
+      persistEncrypt: options.encrypt ?? true,
+      persistSecret: options.secret,
+      persistTtl: options.ttlSeconds ?? DEFAULT_TTL_SECONDS,
+      persistDebounce: options.debounceMs ?? 200,
+      persistClearOnEmpty: false,
+      // A stored preference should win over the component's prop default
+      // (which often runs `immediate: true` on mount and populates the ref
+      // before onMounted hydrates).
+      persistAlwaysHydrate: true
+    },
+    {
+      isEmpty: (v) => v === void 0 || v === null || v === "",
+      // useLocalStorageModel hydrates whenever stored !== undefined, but
+      // localstorage-slim returns `null` for missing keys. Without this filter
+      // a first-time render with no stored entry would clobber the prop default
+      // (e.g. `itemsPerPage: 12`) with `null`.
+      deserializer: (raw) => {
+        if (raw === null || raw === void 0) {
+          throw new Error("skip hydration: no stored preference");
+        }
+        return raw;
+      }
+    }
+  );
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ramathibodi/nuxt-commons",
-  "version": "4.0.7",
+  "version": "4.0.9",
   "description": "Ramathibodi Nuxt modules for common components",
   "repository": {
     "type": "git",