@ramathibodi/nuxt-commons 4.0.11 → 4.0.13

package/dist/runtime/composables/autoRefresh.js

@@ -0,0 +1,57 @@
+import { computed, ref, toValue, watch } from "vue";
+import { useDocumentVisibility, useIntervalFn } from "@vueuse/core";
+function resolveInterval(raw, def) {
+  if (raw === true) return def;
+  if (typeof raw === "number" && raw > 0) return raw;
+  return 0;
+}
+export function useAutoRefresh(opts) {
+  const documentVisibility = useDocumentVisibility();
+  const defaultSeconds = opts.defaultSeconds ?? 60;
+  const intervalSeconds = computed(() => resolveInterval(toValue(opts.interval), defaultSeconds));
+  const enabled = computed(() => intervalSeconds.value > 0);
+  const isUserPaused = ref(false);
+  const remainingSeconds = ref(0);
+  const isLoadingMirror = computed(() => opts.isLoading?.value === true);
+  const paused = computed(
+    () => !enabled.value || isUserPaused.value || documentVisibility.value === "hidden" || opts.paused?.value === true || isLoadingMirror.value
+  );
+  const isActive = computed(() => enabled.value && !paused.value);
+  const ticker = useIntervalFn(async () => {
+    if (paused.value) return;
+    if (remainingSeconds.value <= 1) {
+      try {
+        await opts.reload();
+      } finally {
+        remainingSeconds.value = intervalSeconds.value;
+      }
+    } else {
+      remainingSeconds.value -= 1;
+    }
+  }, 1e3, { immediate: false });
+  watch(enabled, (on) => {
+    remainingSeconds.value = on ? intervalSeconds.value : 0;
+  }, { immediate: true });
+  watch(isActive, (active) => {
+    if (active && typeof document !== "undefined") ticker.resume();
+    else ticker.pause();
+  }, { immediate: true });
+  watch(intervalSeconds, (s) => {
+    if (enabled.value && remainingSeconds.value > s) remainingSeconds.value = s;
+  });
+  return {
+    enabled,
+    isActive,
+    isLoading: isLoadingMirror,
+    intervalSeconds,
+    remainingSeconds,
+    isUserPaused,
+    togglePause: () => {
+      isUserPaused.value = !isUserPaused.value;
+    },
+    reset: () => {
+      remainingSeconds.value = intervalSeconds.value;
+    },
+    reload: opts.reload
+  };
+}

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

@@ -13,6 +13,26 @@ export interface DocumentTemplateItem {
     retrievedValue?: string;
     customClass?: string;
     customStyle?: string;
+    /**
+     * Print/docx-only hook attributes appended to the generated `{{placeholder}}`
+     * by the backend docx renderer (rama-spring-starter `DocumentTemplateJsonRenderer`).
+     * Ignored by the Vue form renderer ({@link useDocumentTemplate}).
+     *
+     * Two accepted shapes:
+     *  - object map — each entry becomes a placeholder attribute
+     *    (`{ width: 2 }` → `;width=2`); a `true`/blank value becomes a bare flag
+     *    (`{ qrcode: true }` → `;qrcode`). Entry order is preserved.
+     *  - raw string — appended verbatim as attributes
+     *    (`"format=dd/MM/yyyy"` → `;format=dd/MM/yyyy`).
+     *
+     * See {@link printConfigToAttributes} for the exact append semantics.
+     */
+    printConfig?: Record<string, string | number | boolean> | string;
+}
+/** A single key/value row of a {@link DocumentTemplateItem.printConfig} object map, used by the builder editor. */
+export interface PrintConfigRow {
+    key: string;
+    value: string | number | boolean;
 }
 export interface ChoiceItem {
     label: string;
@@ -23,5 +43,46 @@ export declare function useDocumentTemplate(items: string | object, parentTempla
 export declare function templateItemToString(inputItem: DocumentTemplateItem, parentTemplates: string | string[], dataVariable?: string): string;
 export declare function optionStringToChoiceObject(option: string | object): ChoiceItem[];
 export declare function escapeObjectForInlineBinding(obj: object): string;
+/**
+ * Explode a {@link DocumentTemplateItem.printConfig} object map into ordered
+ * key/value rows for the builder editor. Returns an empty array for the
+ * raw-string form or any non-object value (those are edited as a plain string).
+ */
+export declare function printConfigToRows(printConfig: DocumentTemplateItem['printConfig'] | undefined): PrintConfigRow[];
+/**
+ * Collapse builder rows back into a `printConfig` object map. Blank keys are
+ * dropped; string values are coerced so the stored JSON matches the backend's
+ * expected primitives: `'true'`/`'false'` → boolean, numeric strings → number,
+ * and a blank value → `true` (a bare flag). Entry order is preserved.
+ */
+export declare function rowsToPrintConfig(rows: PrintConfigRow[] | undefined): Record<string, string | number | boolean>;
+/**
+ * Parse a human raw-attribute string (`"width=2; qrcode; locale=th_TH"`, an
+ * optional leading `;` is tolerated) into builder rows. Each `;`-separated
+ * token splits on the first `=`; a token without `=` becomes a bare-flag row
+ * (blank value). Blank tokens and blank keys are dropped. Inverse of
+ * {@link rowsToConfigString}; used when toggling the builder from raw-string to
+ * key/value mode.
+ */
+export declare function configStringToRows(configString: string | undefined): PrintConfigRow[];
+/**
+ * Render builder rows into a human raw-attribute string
+ * (`"width=2; qrcode"`). A `true`/blank value becomes a bare flag. Inverse of
+ * {@link configStringToRows}; used when toggling the builder from key/value to
+ * raw-string mode.
+ */
+export declare function rowsToConfigString(rows: PrintConfigRow[] | undefined): string;
+/**
+ * Resolve a {@link DocumentTemplateItem.printConfig} to the attribute string the
+ * backend docx renderer appends to a `{{placeholder}}`. This is the single
+ * source of truth for the append semantics (object map and raw string).
+ *
+ * - object map — `{ width: 2 }` → `;width=2`; a `true`/blank value becomes a
+ *   bare flag (`{ qrcode: true }` → `;qrcode`); a `false` value is omitted.
+ * - raw string — appended verbatim with exactly one leading `;`.
+ *
+ * The Vue form renderer never calls this — `printConfig` is print-target-only.
+ */
+export declare function printConfigToAttributes(printConfig: DocumentTemplateItem['printConfig'] | undefined): string;
 export declare function buildValidationRules(validationString: string): string;
 export declare function processDefaultTemplate(item: DocumentTemplateItem, insideTemplate?: string, optionString?: string, validationRules?: string, dataVariable?: string): string;

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

@@ -4,7 +4,7 @@ import { processTemplateFormHidden } from "./templateFormHidden.js";
 import { some, includes, cloneDeep } from "lodash-es";
 import { migrateInputAttributes, migrateTemplateString } from "./templateMigrate.js";
 import { getDocumentTemplateInputTypeEntry } from "./templateInputTypes.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 const validationRulesRegex = /^(require(?:\([^)]*\))?|requireIf\([^)]*\)|requireTrue(?:\([^)]*\))?|requireTrueIf\([^)]*\)|requireNotEmpty(?:\([^)]*\))?|numeric(?:\([^)]*\))?|range\([^)]*\)|integer(?:\([^)]*\))?|unique\([^)]*\)|length(?:\([^)]*\))?|lengthGreater\([^)]*\)|lengthLess\([^)]*\)|telephone(?:\([^)]*\))?|email(?:\([^)]*\))?|regex\([^)]*\)|idcard(?:\([^)]*\))?|DateFuture(?:\([^)]*\))?|DatetimeFuture(?:\([^)]*\))?|DateHappen(?:\([^)]*\))?|DatetimeHappen(?:\([^)]*\))?|DateAfter\([^)]*\)|DateBefore\([^)]*\)|DateEqual\([^)]*\))(,(require(?:\([^)]*\))?|requireIf\([^)]*\)|requireTrue(?:\([^)]*\))?|requireTrueIf\([^)]*\)|requireNotEmpty(?:\([^)]*\))?|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 "";
   if (typeof items === "string") {
@@ -130,6 +130,65 @@ export function optionStringToChoiceObject(option) {
 export function escapeObjectForInlineBinding(obj) {
   return JSON.stringify(obj).replace(/'/g, "'");
 }
+export function printConfigToRows(printConfig) {
+  if (!printConfig || typeof printConfig !== "object" || Array.isArray(printConfig)) return [];
+  return Object.entries(printConfig).map(([key, value]) => ({ key, value }));
+}
+export function rowsToPrintConfig(rows) {
+  const out = {};
+  for (const row of rows || []) {
+    const key = typeof row?.key === "string" ? row.key.trim() : "";
+    if (!key) continue;
+    out[key] = coercePrintConfigValue(row.value);
+  }
+  return out;
+}
+function coercePrintConfigValue(value) {
+  if (typeof value === "boolean" || typeof value === "number") return value;
+  const str = typeof value === "string" ? value.trim() : "";
+  if (str === "") return true;
+  if (str === "true") return true;
+  if (str === "false") return false;
+  if (/^-?\d+(\.\d+)?$/.test(str)) return Number(str);
+  return str;
+}
+export function configStringToRows(configString) {
+  if (typeof configString !== "string") return [];
+  const rows = [];
+  for (const token of configString.split(";")) {
+    const trimmed = token.trim();
+    if (!trimmed) continue;
+    const eq = trimmed.indexOf("=");
+    const key = (eq === -1 ? trimmed : trimmed.slice(0, eq)).trim();
+    if (!key) continue;
+    rows.push({ key, value: eq === -1 ? "" : trimmed.slice(eq + 1).trim() });
+  }
+  return rows;
+}
+export function rowsToConfigString(rows) {
+  return (rows || []).map((row) => {
+    const key = typeof row?.key === "string" ? row.key.trim() : "";
+    if (!key) return "";
+    return row.value === true || row.value === "" ? key : `${key}=${row.value}`;
+  }).filter(Boolean).join("; ");
+}
+export function printConfigToAttributes(printConfig) {
+  if (!printConfig) return "";
+  if (typeof printConfig === "string") {
+    const trimmed = printConfig.trim();
+    return trimmed ? `;${trimmed.replace(/^;+/, "")}` : "";
+  }
+  if (typeof printConfig !== "object" || Array.isArray(printConfig)) return "";
+  let attributes = "";
+  for (const [key, value] of Object.entries(printConfig)) {
+    const name = String(key).trim();
+    if (!name) continue;
+    if (value === false) continue;
+    if (value === true || value === "") attributes += `;${name}`;
+    else attributes += `;${name}=${value}`;
+  }
+  return attributes;
+}
 export function buildValidationRules(validationString) {
   validationString = validationString.replace(/^\[|]$/g, "").trim();
   if (!validationRulesRegex.test(validationString)) return "";

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

@@ -0,0 +1,62 @@
+/**
+ * Validation for Document Template JSON — the array of `DocumentTemplateItem`
+ * objects consumed by {@link useDocumentTemplate} and produced by
+ * `<DocumentTemplateBuilder>`.
+ *
+ * The validator reuses the renderer's own single-sources-of-truth so it can
+ * never drift from runtime behaviour:
+ *
+ *  - `validationRulesRegex` — the exact gate the runtime (`buildValidationRules`)
+ *    and the builder UI both apply to `validationRules`.
+ *  - the choice-format regex `^[^'",]+(,[^'",]+)*$` — the same one
+ *    `optionStringToChoiceObject` and the builder's `ruleOptions` use.
+ *  - the built-in input-type registry — for per-type flags (`requiresOptions`,
+ *    `needsVariableName`, `needsLabel`, `needsWidth`, `optionsAsChoice`,
+ *    `hasSpecificOptionEditor`).
+ *
+ * Two strictness levels share one core via the `strict` option:
+ *
+ *  - `error`   — render-breaking. Invalid in both modes.
+ *  - `warning` — builder-unsafe, but the runtime still renders without crashing.
+ *                Promoted to `error` when `strict: true`.
+ *  - `info`    — advisory only; never affects `valid`.
+ *
+ * This doc block is consumed by vue-docgen for generated API documentation.
+ */
+import { type ComputedRef, type MaybeRefOrGetter } from 'vue';
+export type ValidationSeverity = 'error' | 'warning' | 'info';
+export interface ValidationIssue {
+    /** JSON-ish path to the offending node, e.g. `[2].inputOptions.formTemplate[0].variableName`. */
+    path: string;
+    /** Stable machine code, e.g. `INPUT_TYPE_MISSING`. */
+    code: string;
+    /** Human-readable explanation. */
+    message: string;
+    /** Effective severity (already reflects `strict` promotion). */
+    severity: ValidationSeverity;
+}
+export interface ValidationResult {
+    valid: boolean;
+    errors: ValidationIssue[];
+    warnings: ValidationIssue[];
+    infos: ValidationIssue[];
+    /** All issues in document order. */
+    issues: ValidationIssue[];
+}
+export interface ValidateOptions {
+    /** Promote builder-unsafe `warning`s to `error`s. Default `false`. */
+    strict?: boolean;
+    /** Forwarded ancestor-template context (advisory; mirrors `useDocumentTemplate`). */
+    parentTemplates?: string | string[];
+}
+/**
+ * Validate a Document Template. Accepts the same inputs as `useDocumentTemplate`:
+ * a JSON string or an already-parsed array of items.
+ */
+export declare function validateDocumentTemplate(items: string | object, options?: ValidateOptions): ValidationResult;
+/**
+ * Reactive wrapper. Re-validates whenever `source` (a ref, getter, JSON string,
+ * or item array) changes. Use in `<DocumentTemplateBuilder>`-adjacent UIs to
+ * surface per-field issues live.
+ */
+export declare function useDocumentTemplateValidate(source: MaybeRefOrGetter<string | object>, options?: ValidateOptions): ComputedRef<ValidationResult>;

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) => void;
-    reload: () => void;
+    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>;
+    };
 };