@ramathibodi/nuxt-commons 4.0.12 → 4.0.13

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

@@ -0,0 +1,378 @@
+import { computed, toValue } from "vue";
+import { isPlainObject } from "lodash-es";
+import { validationRulesRegex } from "./template.js";
+import {
+  getDocumentTemplateInputTypeEntry
+} from "./templateInputTypes.js";
+const CHOICE_STRING_REGEX = /^[^'",]+(,[^'",]+)*$/;
+const VARIABLE_NAME_REGEX = /^[A-Za-z_$][\w$]*(\.[A-Za-z_$][\w$]*)*$/;
+const KNOWN_ITEM_KEYS = /* @__PURE__ */ new Set([
+  "inputType",
+  "width",
+  "inputLabel",
+  "variableName",
+  "validationRules",
+  "inputOptions",
+  "inputAttributes",
+  "inputCustomCode",
+  "columnAttributes",
+  "conditionalDisplay",
+  "computedValue",
+  "retrievedValue",
+  "customClass",
+  "customStyle",
+  "printConfig"
+]);
+export function validateDocumentTemplate(items, options = {}) {
+  const raw = [];
+  const push = (path, code, message, base) => raw.push({ path, code, message, base });
+  let parsed = items;
+  if (typeof items === "string") {
+    try {
+      parsed = JSON.parse(items);
+    } catch {
+      push("", "NOT_ARRAY", "Template is a string but not valid JSON; expected an array of items.", "error");
+      return finalize(raw, options.strict);
+    }
+  }
+  validateItemArray(parsed, "", push);
+  return finalize(raw, options.strict);
+}
+function validateItemArray(node, basePath, push) {
+  if (!Array.isArray(node) || !node.every((it) => isPlainObject(it))) {
+    push(basePath || "", "NOT_ARRAY", `Expected an array of template item objects at ${basePath || "top level"}.`, "error");
+    return;
+  }
+  if (node.length === 0) {
+    push(basePath || "", "EMPTY_TEMPLATE", "Template array is empty; it renders an empty container.", "info");
+    return;
+  }
+  const seen = /* @__PURE__ */ new Map();
+  for (const item of node) {
+    const v = typeof item.variableName === "string" ? item.variableName.trim() : "";
+    if (v) seen.set(v, (seen.get(v) ?? 0) + 1);
+  }
+  node.forEach((item, index) => {
+    validateItem(item, `${basePath}[${index}]`, seen, push);
+  });
+}
+function validateItem(item, path, siblingVarCounts, push) {
+  for (const key of Object.keys(item)) {
+    if (!KNOWN_ITEM_KEYS.has(key)) {
+      push(`${path}.${key}`, "UNKNOWN_KEY", `Unknown key "${key}" is ignored by the renderer (possible typo).`, "info");
+    }
+  }
+  if (typeof item.inputType !== "string" || item.inputType.trim() === "") {
+    push(`${path}.inputType`, "INPUT_TYPE_MISSING", "inputType is required and must be a non-empty string.", "error");
+    return;
+  }
+  const inputType = item.inputType;
+  const entry = getDocumentTemplateInputTypeEntry(inputType);
+  if (!entry) {
+    push(
+      `${path}.inputType`,
+      "INPUT_TYPE_UNKNOWN",
+      `inputType "${inputType}" is not a built-in type; it will render as a raw <${inputType}> component tag.`,
+      "warning"
+    );
+  }
+  const needsVariableName = entry?.needsVariableName !== false;
+  const needsLabel = entry?.needsLabel !== false;
+  const needsWidth = entry?.needsWidth !== false;
+  const requiresOptions = entry?.requiresOptions === true;
+  const optionsAsChoice = entry?.optionsAsChoice === true;
+  const hasSpecificOptionEditor = entry?.hasSpecificOptionEditor === true;
+  const variableName = typeof item.variableName === "string" ? item.variableName.trim() : "";
+  if (needsVariableName) {
+    if (!variableName) {
+      push(`${path}.variableName`, "VARIABLE_NAME_REQUIRED", `${inputType} requires a variableName.`, "warning");
+    } else if (!VARIABLE_NAME_REGEX.test(variableName)) {
+      push(
+        `${path}.variableName`,
+        "VARIABLE_NAME_MALFORMED",
+        `variableName "${variableName}" is not a valid data path; it breaks v-model="data.${variableName}".`,
+        "error"
+      );
+    } else if ((siblingVarCounts.get(variableName) ?? 0) > 1) {
+      push(
+        `${path}.variableName`,
+        "VARIABLE_NAME_DUPLICATE",
+        `variableName "${variableName}" is used by more than one sibling field; they bind to the same data property.`,
+        "warning"
+      );
+    }
+  }
+  if (needsLabel && (typeof item.inputLabel !== "string" || item.inputLabel.trim() === "")) {
+    push(`${path}.inputLabel`, "LABEL_REQUIRED", `${inputType} expects an inputLabel.`, "warning");
+  }
+  if (needsWidth) {
+    if (item.width === void 0 || item.width === null || item.width === "") {
+      push(`${path}.width`, "WIDTH_REQUIRED", `${inputType} expects a width (1\u201312).`, "warning");
+    } else {
+      const n = Number(item.width);
+      if (!Number.isFinite(n) || !Number.isInteger(n) || n < 1 || n > 12) {
+        push(`${path}.width`, "WIDTH_OUT_OF_RANGE", `width "${item.width}" should be an integer from 1 to 12.`, "warning");
+      }
+    }
+  }
+  if (item.validationRules !== void 0 && item.validationRules !== null && item.validationRules !== "") {
+    if (typeof item.validationRules !== "string") {
+      push(`${path}.validationRules`, "RULES_INVALID", "validationRules must be a string.", "warning");
+    } else {
+      const stripped = item.validationRules.replace(/^\[|]$/g, "").trim();
+      if (stripped && !validationRulesRegex.test(stripped)) {
+        push(
+          `${path}.validationRules`,
+          "RULES_INVALID",
+          `validationRules "${item.validationRules}" fail the rules regex; the renderer drops them silently.`,
+          "warning"
+        );
+      }
+    }
+  }
+  if (item.computedValue && !variableName) {
+    push(
+      `${path}.computedValue`,
+      "COMPUTED_VALUE_IGNORED",
+      "computedValue is ignored without a variableName (no hidden field is appended).",
+      "info"
+    );
+  }
+  if (item.retrievedValue) {
+    push(`${path}.retrievedValue`, "RETRIEVED_VALUE_UNUSED", "retrievedValue is not consumed by the renderer.", "info");
+  }
+  validatePrintConfig(item.printConfig, `${path}.printConfig`, push);
+  validateInputOptions(item, path, { entry, requiresOptions, optionsAsChoice, hasSpecificOptionEditor }, push);
+}
+function validatePrintConfig(printConfig, path, push) {
+  if (printConfig === void 0 || printConfig === null) return;
+  if (typeof printConfig === "string") {
+    if (printConfig.trim() === "") {
+      push(path, "PRINTCONFIG_EMPTY", "printConfig is an empty string; nothing is appended to the placeholder.", "info");
+    }
+    return;
+  }
+  if (!isPlainObject(printConfig)) {
+    push(
+      path,
+      "PRINTCONFIG_INVALID_TYPE",
+      "printConfig must be an object map of primitive values or a raw string; other shapes are ignored by the print renderer.",
+      "info"
+    );
+    return;
+  }
+  const entries = Object.entries(printConfig);
+  if (entries.length === 0) {
+    push(path, "PRINTCONFIG_EMPTY", "printConfig is an empty object; nothing is appended to the placeholder.", "info");
+    return;
+  }
+  for (const [key, value] of entries) {
+    const t = typeof value;
+    if (t !== "string" && t !== "number" && t !== "boolean") {
+      push(
+        `${path}.${key}`,
+        "PRINTCONFIG_VALUE_INVALID",
+        `printConfig.${key} must be a string, number, or boolean; the print renderer cannot append a ${Array.isArray(value) ? "array" : t}.`,
+        "info"
+      );
+    }
+  }
+}
+function validateInputOptions(item, path, ctx, push) {
+  const { requiresOptions, optionsAsChoice, hasSpecificOptionEditor } = ctx;
+  const inputType = item.inputType;
+  const opts = item.inputOptions;
+  const optsPath = `${path}.inputOptions`;
+  const hasOptions = opts !== void 0 && opts !== null && opts !== "";
+  if (requiresOptions && !hasSpecificOptionEditor && !hasOptions) {
+    push(optsPath, "OPTIONS_REQUIRED", `${inputType} requires inputOptions.`, "warning");
+  }
+  switch (inputType) {
+    case "CustomCode":
+      if (typeof item.inputCustomCode !== "string" || item.inputCustomCode.trim() === "") {
+        push(`${path}.inputCustomCode`, "CUSTOMCODE_EMPTY", "CustomCode requires inputCustomCode; otherwise it renders nothing.", "error");
+      }
+      return;
+    case "MasterAutocomplete":
+      if (hasOptions && (typeof opts !== "string" || opts.trim() === "")) {
+        push(optsPath, "OPTIONS_NOT_STRING", "MasterAutocomplete inputOptions must be a non-empty group-key string.", "warning");
+      }
+      return;
+    case "DocumentForm":
+      if (hasOptions && (typeof opts !== "string" || opts.trim() === "")) {
+        push(optsPath, "OPTIONS_NOT_STRING", "DocumentForm inputOptions must be the child template code (a non-empty string).", "warning");
+      }
+      return;
+    case "Header":
+      if (hasOptions && typeof opts !== "string") {
+        push(optsPath, "OPTIONS_NOT_STRING", "Header inputOptions should be a class string; non-strings are ignored.", "warning");
+      }
+      return;
+    case "FormHidden":
+      if (hasOptions && !isPlainObject(opts)) {
+        push(optsPath, "OPTIONS_NOT_OBJECT", "FormHidden inputOptions must be an object { itemValue?, hook? }.", "error");
+      } else if (isPlainObject(opts)) {
+        const o = opts;
+        if (o.hook !== void 0 && typeof o.hook !== "string") {
+          push(`${optsPath}.hook`, "OPTIONS_NOT_STRING", "FormHidden inputOptions.hook must be a string.", "warning");
+        }
+      }
+      return;
+    case "FormTable":
+      validateFormTableOptions(opts, optsPath, push);
+      return;
+    case "FormTableData":
+      validateFormTableDataOptions(opts, optsPath, push);
+      return;
+    default:
+      if (optionsAsChoice && hasOptions) {
+        validateChoiceOptions(opts, optsPath, push);
+      }
+      return;
+  }
+}
+function validateChoiceOptions(opts, path, push) {
+  if (typeof opts === "string") {
+    if (!CHOICE_STRING_REGEX.test(opts.trim())) {
+      push(
+        path,
+        "CHOICE_OPTIONS_INVALID",
+        "Choice inputOptions string is malformed (quotes or empty commas); it parses to zero options.",
+        "error"
+      );
+    }
+    return;
+  }
+  if (Array.isArray(opts)) {
+    if (!opts.every((it) => isPlainObject(it))) {
+      push(path, "CHOICE_OPTIONS_INVALID", "Choice inputOptions array must contain only objects.", "error");
+      return;
+    }
+    opts.forEach((it, i) => {
+      const o = it;
+      const hasLabel = o.label !== void 0 && o.label !== "";
+      const hasValue = o.value !== void 0 && o.value !== "";
+      if (!hasLabel && !hasValue) {
+        push(`${path}[${i}]`, "CHOICE_ITEM_EMPTY", "Choice item has neither label nor value; it renders blank.", "info");
+      }
+    });
+    return;
+  }
+  push(path, "CHOICE_OPTIONS_INVALID", "Choice inputOptions must be a compact string or an array of { label, value } objects.", "error");
+}
+function validateFormTableOptions(opts, path, push) {
+  if (!isPlainObject(opts)) {
+    push(path, "OPTIONS_NOT_OBJECT", "FormTable inputOptions must be an object with a formTemplate.", "error");
+    return;
+  }
+  const o = opts;
+  const formTemplate = coerceTemplateArray(o.formTemplate);
+  if (formTemplate === void 0) {
+    push(
+      `${path}.formTemplate`,
+      "FORMTABLE_NO_FORMTEMPLATE",
+      "FormTable requires a formTemplate (array of items or a JSON string) for the row editor.",
+      "error"
+    );
+  } else {
+    validateItemArray(formTemplate, `${path}.formTemplate`, push);
+  }
+  validateTableHeaders(o.headers, `${path}.headers`, push);
+}
+function validateFormTableDataOptions(opts, path, push) {
+  if (!isPlainObject(opts)) {
+    push(path, "OPTIONS_NOT_OBJECT", "FormTableData inputOptions must be an object with a dataTemplate.", "error");
+    return;
+  }
+  const o = opts;
+  const dataTemplate = coerceTemplateArray(o.dataTemplate);
+  const dataVars = /* @__PURE__ */ new Set();
+  if (dataTemplate === void 0) {
+    push(
+      `${path}.dataTemplate`,
+      "FORMTABLEDATA_NO_DATATEMPLATE",
+      "FormTableData has no dataTemplate; no editable columns are rendered.",
+      "warning"
+    );
+  } else {
+    validateItemArray(dataTemplate, `${path}.dataTemplate`, push);
+    for (const it of dataTemplate) {
+      if (typeof it.variableName === "string" && it.variableName.trim()) dataVars.add(it.variableName.trim());
+    }
+  }
+  const itemTemplate = coerceTemplateArray(o.itemTemplate);
+  if (itemTemplate !== void 0) validateItemArray(itemTemplate, `${path}.itemTemplate`, push);
+  validateTableHeaders(o.headers, `${path}.headers`, push);
+  if (o.disableApplyToAll !== void 0 && o.disableApplyToAll !== "") {
+    const val = o.disableApplyToAll;
+    if (val !== "false" && val !== "true" && val !== "partial") {
+      push(`${path}.disableApplyToAll`, "APPLYTOALL_INVALID", 'disableApplyToAll must be "false", "true", or "partial".', "warning");
+    } else if (val === "partial") {
+      const keys = typeof o.disableApplyToAllPartial === "string" ? o.disableApplyToAllPartial.split(",").map((s) => s.trim()).filter(Boolean) : [];
+      if (keys.length === 0) {
+        push(
+          `${path}.disableApplyToAllPartial`,
+          "APPLYTOALL_INVALID",
+          'disableApplyToAll is "partial" but disableApplyToAllPartial lists no columns.',
+          "warning"
+        );
+      } else if (dataTemplate !== void 0) {
+        for (const k of keys) {
+          if (!dataVars.has(k)) {
+            push(
+              `${path}.disableApplyToAllPartial`,
+              "APPLYTOALL_KEY_UNKNOWN",
+              `disableApplyToAllPartial key "${k}" is not a variableName in dataTemplate.`,
+              "warning"
+            );
+          }
+        }
+      }
+    }
+  }
+}
+function validateTableHeaders(headers, path, push) {
+  if (headers === void 0 || headers === null) return;
+  if (!Array.isArray(headers)) {
+    push(path, "OPTIONS_NOT_OBJECT", "headers must be an array.", "warning");
+    return;
+  }
+  headers.forEach((h, i) => {
+    if (!isPlainObject(h)) {
+      push(`${path}[${i}]`, "OPTIONS_NOT_OBJECT", "header entry must be an object.", "warning");
+      return;
+    }
+    const key = h.key;
+    if (key === void 0 || key === "") {
+      push(`${path}[${i}].key`, "HEADER_NO_KEY", "header entry has no key; the column cannot bind to a row property.", "warning");
+    }
+  });
+}
+function coerceTemplateArray(value) {
+  if (value === void 0 || value === null || value === "") return void 0;
+  if (Array.isArray(value)) return value;
+  if (typeof value === "string") {
+    try {
+      const parsed = JSON.parse(value);
+      return Array.isArray(parsed) ? parsed : void 0;
+    } catch {
+      return void 0;
+    }
+  }
+  return void 0;
+}
+function finalize(raw, strict) {
+  const issues = raw.map((r) => ({
+    path: r.path,
+    code: r.code,
+    message: r.message,
+    severity: strict && r.base === "warning" ? "error" : r.base
+  }));
+  const errors = issues.filter((i) => i.severity === "error");
+  const warnings = issues.filter((i) => i.severity === "warning");
+  const infos = issues.filter((i) => i.severity === "info");
+  return { valid: errors.length === 0, errors, warnings, infos, issues };
+}
+export function useDocumentTemplateValidate(source, options = {}) {
+  return computed(() => validateDocumentTemplate(toValue(source), options));
+}

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

@@ -26,10 +26,29 @@ export declare function useGraphqlModel<T extends GraphqlModelProps>(props: T):
     canUpdate: import("vue").ComputedRef<boolean>;
     canDelete: import("vue").ComputedRef<boolean>;
     createItem: (item: Record<string, any>, callback?: FormDialogCallback, importing?: boolean) => Promise<void>;
-    importItems: (importItems: Record<string, any>[], callback?: FormDialogCallback) => void;
+    importItems: (importData: Record<string, any>[], callback?: FormDialogCallback) => void;
     updateItem: (item: Record<string, any>, callback?: FormDialogCallback) => Promise<void>;
     deleteItem: (item: Record<string, any>, callback?: FormDialogCallback) => Promise<any>;
     loadItems: (options: any) => Promise<void> | undefined;
     reload: () => Promise<void> | undefined;
     isLoading: import("vue").Ref<boolean, boolean>;
+    importProgress: {
+        isImporting: import("vue").Ref<boolean, boolean>;
+        total: import("vue").Ref<number, number>;
+        processed: import("vue").Ref<number, number>;
+        succeeded: import("vue").Ref<number, number>;
+        failed: import("vue").Ref<number, number>;
+        errors: import("vue").Ref<{
+            index: number;
+            message: string;
+        }[], import("./importProgress.js").ImportError[] | {
+            index: number;
+            message: string;
+        }[]>;
+        percent: import("vue").ComputedRef<number>;
+        reset: () => void;
+        run: <T_1 = any>(items: T_1[], worker: import("./importProgress.js").ImportWorker<T_1>, options?: {
+            concurrency?: number;
+        }) => Promise<import("./importProgress.js").ImportSummary>;
+    };
 };

package/dist/runtime/composables/graphqlModel.js

@@ -3,7 +3,7 @@ import { watchDebounced } from "@vueuse/core";
 import { useAlert } from "./alert.js";
 import { buildRequiredInputFields } from "./graphqlOperation.js";
 import { useGraphqlModelOperation } from "./graphqlModelOperation.js";
-import pLimit from "p-limit";
+import { useImportProgress } from "./importProgress.js";
 import { arrayWrap } from "../utils/array.js";
 export function useGraphqlModel(props) {
   const alert = useAlert();
@@ -15,6 +15,7 @@ export function useGraphqlModel(props) {
     search.value = keyword;
   }
   const isLoading = ref(false);
+  const importProgress = useImportProgress();
   const { operationCreate, operationUpdate, operationDelete, operationRead, operationReadPageable, operationSearch } = useGraphqlModelOperation(props);
   function keyToField(key) {
     const parts = key.split(".");
@@ -64,27 +65,33 @@ export function useGraphqlModel(props) {
       } else items.value.push(result);
       if (callback && callback.setData) callback.setData(result);
     }).catch((error) => {
+      if (importing) throw error;
       alert?.addAlert({ alertType: "error", message: error });
     }).finally(() => {
       if (!importing) isLoading.value = false;
       if (callback) callback.done();
     });
   }
-  function importItems(importItems2, callback) {
+  function importItems(importData, callback) {
+    if (importProgress.isImporting.value) return;
+    if (importData.length === 0) {
+      if (callback) callback.done();
+      return;
+    }
     isLoading.value = true;
-    const limit = pLimit(50);
-    const importPromises = importItems2.map(
-      (item) => limit(
-        () => (item[props.modelKey || "id"] ? operationUpdate.value?.call(fields.value, { input: item }).then((result) => {
-          if (!result) {
-            return createItem(Object.assign({}, props.initialData, item), void 0, true);
-          }
-        }) : createItem(Object.assign({}, props.initialData, item), void 0, true)).catch((error) => {
-          alert?.addAlert({ alertType: "error", message: error });
-        })
-      )
-    );
-    Promise.all(importPromises).finally(() => {
+    const worker = (item) => {
+      const createAsNew = () => createItem(Object.assign({}, props.initialData, item), void 0, true);
+      return item[props.modelKey || "id"] ? operationUpdate.value?.call(fields.value, { input: item }).then((result) => {
+        if (!result) return createAsNew();
+      }) : createAsNew();
+    };
+    importProgress.run(importData, worker, { concurrency: props.importConcurrency }).then(({ succeeded, failed }) => {
+      if (failed > 0) {
+        alert?.addAlert({ alertType: "warning", message: `\u0E19\u0E33\u0E40\u0E02\u0E49\u0E32\u0E2A\u0E33\u0E40\u0E23\u0E47\u0E08 ${succeeded} \u0E23\u0E32\u0E22\u0E01\u0E32\u0E23, \u0E25\u0E49\u0E21\u0E40\u0E2B\u0E25\u0E27 ${failed} \u0E23\u0E32\u0E22\u0E01\u0E32\u0E23` });
+      } else {
+        alert?.addAlert({ alertType: "success", message: `\u0E19\u0E33\u0E40\u0E02\u0E49\u0E32\u0E2A\u0E33\u0E40\u0E23\u0E47\u0E08 ${succeeded} \u0E23\u0E32\u0E22\u0E01\u0E32\u0E23` });
+      }
+    }).finally(() => {
       isLoading.value = false;
       reload();
       if (callback) callback.done();
@@ -184,6 +191,7 @@ export function useGraphqlModel(props) {
     deleteItem,
     loadItems,
     reload,
-    isLoading
+    isLoading,
+    importProgress
   };
 }

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

@@ -10,6 +10,7 @@ export interface GraphqlModelConfigProps {
     operationReadPageable?: graphqlOperationObject<any, any> | string;
     operationSearch?: graphqlOperationObject<any, any> | string;
     fields?: Array<string | object>;
+    importConcurrency?: number;
 }
 export declare function useGraphqlModelOperation<T extends GraphqlModelConfigProps>(props: T): {
     operationCreate: import("vue").ComputedRef<graphqlOperationObject<any, any>>;

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

@@ -0,0 +1,34 @@
+export interface ImportError {
+    index: number;
+    message: string;
+}
+export interface ImportSummary {
+    succeeded: number;
+    failed: number;
+    errors: ImportError[];
+}
+export type ImportWorker<T = any> = (item: T, index: number) => Promise<any>;
+/**
+ * useImportProgress drives a concurrency-limited bulk import while exposing
+ * reactive progress. The runner continues on per-row errors and never rejects;
+ * callers read the resolved summary for the success/failure breakdown.
+ */
+export declare function useImportProgress(): {
+    isImporting: import("vue").Ref<boolean, boolean>;
+    total: import("vue").Ref<number, number>;
+    processed: import("vue").Ref<number, number>;
+    succeeded: import("vue").Ref<number, number>;
+    failed: import("vue").Ref<number, number>;
+    errors: import("vue").Ref<{
+        index: number;
+        message: string;
+    }[], ImportError[] | {
+        index: number;
+        message: string;
+    }[]>;
+    percent: import("vue").ComputedRef<number>;
+    reset: () => void;
+    run: <T = any>(items: T[], worker: ImportWorker<T>, options?: {
+        concurrency?: number;
+    }) => Promise<ImportSummary>;
+};

package/dist/runtime/composables/importProgress.js

@@ -0,0 +1,50 @@
+import { computed, ref } from "vue";
+import pLimit from "p-limit";
+export function useImportProgress() {
+  const isImporting = ref(false);
+  const total = ref(0);
+  const processed = ref(0);
+  const succeeded = ref(0);
+  const failed = ref(0);
+  const errors = ref([]);
+  const percent = computed(
+    () => total.value ? Math.round(processed.value / total.value * 100) : 0
+  );
+  function reset() {
+    total.value = 0;
+    processed.value = 0;
+    succeeded.value = 0;
+    failed.value = 0;
+    errors.value = [];
+  }
+  async function run(items, worker, options = {}) {
+    if (isImporting.value) {
+      return { succeeded: succeeded.value, failed: failed.value, errors: [...errors.value] };
+    }
+    reset();
+    total.value = items.length;
+    isImporting.value = true;
+    const limit = pLimit(options.concurrency && options.concurrency > 0 ? options.concurrency : 3);
+    try {
+      await Promise.all(
+        items.map(
+          (item, index) => limit(async () => {
+            try {
+              await worker(item, index);
+              succeeded.value++;
+            } catch (error) {
+              failed.value++;
+              errors.value.push({ index, message: error?.message || String(error) });
+            } finally {
+              processed.value++;
+            }
+          })
+        )
+      );
+    } finally {
+      isImporting.value = false;
+    }
+    return { succeeded: succeeded.value, failed: failed.value, errors: [...errors.value] };
+  }
+  return { isImporting, total, processed, succeeded, failed, errors, percent, reset, run };
+}

package/dist/runtime/utils/virtualize.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Pure helpers for the ModelTable/ModelIterator virtualization layer (#246).
+ */
+/**
+ * Decide whether to render rows virtualized.
+ * @param count rendered-row count (items.length)
+ * @param override tri-state `virtual` prop: true/false force, undefined = auto
+ * @param threshold auto-virtualize above this count (default 500)
+ */
+export declare function shouldVirtualize(count: number, override: boolean | undefined, threshold: number | undefined): boolean;
+/**
+ * Cards-per-row for a Vuetify grid column span (out of 12).
+ * span 12 -> 1, 6 -> 2, 4 -> 3, 2 -> 6. Falsy / out-of-range -> 1 (full width).
+ */
+export declare function itemsPerRowForSpan(span: number | string | boolean | undefined): number;

package/dist/runtime/utils/virtualize.js

@@ -0,0 +1,10 @@
+export function shouldVirtualize(count, override, threshold) {
+  if (override === true) return true;
+  if (override === false) return false;
+  return count > (threshold ?? 500);
+}
+export function itemsPerRowForSpan(span) {
+  const n = Number(span);
+  if (!Number.isFinite(n) || n <= 0 || n > 12) return 1;
+  return Math.max(1, Math.floor(12 / n));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ramathibodi/nuxt-commons",
-  "version": "4.0.12",
+  "version": "4.0.13",
   "description": "Ramathibodi Nuxt modules for common components",
   "repository": {
     "type": "git",
@@ -49,6 +49,7 @@
     "dev:build": "nuxt build playground",
     "dev:generate": "nuxt generate playground",
     "playground:scaffold": "node scripts/scaffold-playground-pages.mjs",
+    "template:validate": "node scripts/validate-document-template.mjs",
     "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxt prepare playground",
     "docs:api:components": "vue-docgen -c docs/vue-docgen.config.cjs && npm run docs:ai:summary && node scripts/enrich-vue-docs-from-ai.mjs",
     "docs:api:composables": "typedoc --options docs/typedoc.json",