@ramathibodi/nuxt-commons 4.0.9 → 4.0.11

package/README.md

@@ -6,6 +6,14 @@ Nuxt module for Nuxt 3 and Nuxt 4 that provides shared runtime building blocks f
 - runtime plugins for permission/dialog/default behavior
 - utility and lab exports
 
+## Documentation & playground
+
+The live playground is the project's documentation site — every component has a real demo page running the real module against the real Vuetify theme, with a Vuetify-docs-style API panel (Props / Emits / Slots / Exposed) sourced from `docs/ai-summary.json`. Bug-repro fixtures live under *Scenarios*.
+
+→ **https://ramacare.gitlab.rama.mahidol.ac.th/frontend/rama-modules/** _(published from `master` by the `pages` CI job; if the project later moves to a unique Pages domain, update `NUXT_APP_BASE_URL` in the CI job accordingly)_
+
+Run it locally with `pnpm run dev`. See `CLAUDE.md` > *Playground* for the conventions every new/modified component must follow.
+
 ## Install
 
 ```bash

package/dist/module.json

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

package/dist/runtime/components/document/TemplateBuilder.d.vue.ts

@@ -5,7 +5,12 @@ interface Props {
 }
 /**
  * Public props accepted by DocumentTemplateBuilder.
- * Document each prop field with intent, defaults, and side effects for clear generated docs.
+ *
+ * To extend the Input Type dropdown with app-specific entries, call
+ * `registerDocumentTemplateInputType()` from a Nuxt plugin (app-wide) or
+ * `useDocumentTemplateInputType()` inside `<script setup>` of a page
+ * (page-scoped, auto-cleanup on unmount). Both flow through the same
+ * runtime registry that this component reads via `useDocumentTemplateInputTypes()`.
  */
 type __VLS_Props = Props;
 type __VLS_ModelProps = {

package/dist/runtime/components/document/TemplateBuilder.vue

@@ -3,6 +3,9 @@ import { computed, ref, watch } from "vue";
 import * as prettier from "prettier";
 import prettierPluginHtml from "prettier/plugins/html";
 import { useDocumentTemplate, validationRulesRegex, optionStringToChoiceObject } from "../../composables/document/template";
+import {
+  useDocumentTemplateInputTypes
+} from "../../composables/document/templateInputTypes";
 import { autoActionHeader, templateToHeader } from "../../composables/document/templateFormTable";
 import { cloneDeep } from "lodash-es";
 import VueJsonPretty from "vue-json-pretty";
@@ -113,47 +116,24 @@ async function convertToAdvanceMode() {
     modelValue.value = await prettier.format(useDocumentTemplate(templateItems.value).replaceAll(">", ">\n"), { parser: "html", plugins: [prettierPluginHtml] });
   }
 }
-const inputTypeChoice = ref([
-  { label: "Text Field", value: "VTextField" },
-  { label: "Text Area", value: "VTextarea" },
-  { label: "Text Date Picker", value: "FormDate" },
-  { label: "Text Time Picker", value: "FormTime" },
-  { label: "Text Date & Time Picker", value: "FormDateTime" },
-  { label: "Select Dropdown", value: "VSelect" },
-  { label: "Select Combobox", value: "VCombobox" },
-  { label: "Autocomplete", value: "VAutocomplete" },
-  { label: "Autocomplete from Master", value: "MasterAutocomplete" },
-  { label: "Radio Buttons", value: "VRadio" },
-  { label: "Radio Buttons Inline", value: "VRadioInline" },
-  { label: "Checkbox", value: "VCheckbox" },
-  { label: "Checkbox Group", value: "FormCheckboxGroup" },
-  { label: "Switch", value: "VSwitch" },
-  { label: "File Upload", value: "FormFile" },
-  { label: "Signature Pad", value: "FormSignPad" },
-  { label: "Table", value: "FormTable" },
-  { label: "Table Data", value: "FormTableData" },
-  { label: "[Decoration] Header", value: "Header" },
-  { label: "[Decoration] Separator", value: "Separator" },
-  { label: "[Advanced] Hidden Field", value: "FormHidden" },
-  { label: "[Advanced] Inherit Form", value: "DocumentForm" },
-  { label: "[Advanced] Custom Code", value: "CustomCode" }
-]);
-const requireOption = ref(["VSelect", "VAutocomplete", "VCombobox", "VRadio", "VRadioInline", "MasterAutocomplete", "FormTable", "FormTableData", "DocumentForm", "FormCheckboxGroup"]);
-const notRequireVariable = ref(["Header", "Separator", "CustomCode", "DocumentForm"]);
-const notRequireLabel = ref(["Separator", "CustomCode", "FormFile", "FormHidden", "DocumentForm"]);
-const notRequireWidth = ref(["Separator", "FormHidden", "DocumentForm"]);
-const notRequireOptions = ref(["Separator", "CustomCode", "FormFile"]);
-const notRequireRules = ref(["Separator", "Header", "CustomCode", "FormHidden", "DocumentForm"]);
-const notRequireInputAttributes = ref(["CustomCode", "Header", "DocumentForm"]);
-const notRequireColumnAttributes = ref(["Separator", "FormHidden", "DocumentForm"]);
-const notRequireAdvancedSetting = ref(["Separator", "CustomCode"]);
-const notRequireClassAndStyle = ref(["FormHidden"]);
-const hasSpecificOption = ref(["FormHidden", "FormTable", "FormTableData"]);
-const choiceOption = ref(["VRadio", "VRadioInline", "VSelect", "VAutocomplete", "VCombobox", "FormCheckboxGroup"]);
-const inputOptionsLabel = ref({
-  "MasterAutocomplete": "Group Key",
-  "Header": "Class",
-  "DocumentForm": "Template Code"
+const inputTypes = computed(() => useDocumentTemplateInputTypes());
+const inputTypeChoice = computed(() => inputTypes.value.map((t) => ({ label: t.label, value: t.value })));
+const requireOption = computed(() => inputTypes.value.filter((t) => t.requiresOptions).map((t) => t.value));
+const notRequireVariable = computed(() => inputTypes.value.filter((t) => t.needsVariableName === false).map((t) => t.value));
+const notRequireLabel = computed(() => inputTypes.value.filter((t) => t.needsLabel === false).map((t) => t.value));
+const notRequireWidth = computed(() => inputTypes.value.filter((t) => t.needsWidth === false).map((t) => t.value));
+const notRequireOptions = computed(() => inputTypes.value.filter((t) => t.showsOptions === false).map((t) => t.value));
+const notRequireRules = computed(() => inputTypes.value.filter((t) => t.hidesValidationRules).map((t) => t.value));
+const notRequireInputAttributes = computed(() => inputTypes.value.filter((t) => t.hidesInputAttributes).map((t) => t.value));
+const notRequireColumnAttributes = computed(() => inputTypes.value.filter((t) => t.hidesColumnAttributes).map((t) => t.value));
+const notRequireAdvancedSetting = computed(() => inputTypes.value.filter((t) => t.hidesAdvancedSettings).map((t) => t.value));
+const notRequireClassAndStyle = computed(() => inputTypes.value.filter((t) => t.hidesClassAndStyle).map((t) => t.value));
+const hasSpecificOption = computed(() => inputTypes.value.filter((t) => t.hasSpecificOptionEditor).map((t) => t.value));
+const choiceOption = computed(() => inputTypes.value.filter((t) => t.optionsAsChoice).map((t) => t.value));
+const inputOptionsLabel = computed(() => {
+  const acc = {};
+  for (const t of inputTypes.value) if (t.optionsLabel) acc[t.value] = t.optionsLabel;
+  return acc;
 });
 const ruleOptions = (inputType) => (value) => {
   if (choiceOption.value.includes(inputType) && !/^[^'",]+(,[^'",]+)*$/.test(value)) return "Invalid options format";

package/dist/runtime/components/document/TemplateBuilder.vue.d.ts

@@ -5,7 +5,12 @@ interface Props {
 }
 /**
  * Public props accepted by DocumentTemplateBuilder.
- * Document each prop field with intent, defaults, and side effects for clear generated docs.
+ *
+ * To extend the Input Type dropdown with app-specific entries, call
+ * `registerDocumentTemplateInputType()` from a Nuxt plugin (app-wide) or
+ * `useDocumentTemplateInputType()` inside `<script setup>` of a page
+ * (page-scoped, auto-cleanup on unmount). Both flow through the same
+ * runtime registry that this component reads via `useDocumentTemplateInputTypes()`.
  */
 type __VLS_Props = Props;
 type __VLS_ModelProps = {

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

@@ -308,5 +308,5 @@ defineExpose({
 </template>
 
 <style>
-.form-data-dirty:not(.v-input--error) :not(.v-chip):not(.v-chip *){color:color-mix(in srgb,currentColor 70%,rgb(var(--v-theme-primary)))!important;text-shadow:0 0 .02em currentColor}
+.form-data-dirty:not(.v-input--error) :not(.v-chip):not(.v-chip *):not(.v-toolbar):not(.v-toolbar *){color:color-mix(in srgb,currentColor 70%,rgb(var(--v-theme-primary)))!important;text-shadow:0 0 .02em currentColor}
 </style>

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

@@ -3,6 +3,7 @@ import { processTemplateFormTableData } from "./templateFormTableData.js";
 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 function useDocumentTemplate(items, parentTemplates) {
   if (!items) return "";
@@ -52,6 +53,14 @@ export function templateItemToString(inputItem, parentTemplates, dataVariable =
   }
   let templateString;
   const validationRules = item.validationRules ? buildValidationRules(item.validationRules) || "" : "";
+  const registryEntry = getDocumentTemplateInputTypeEntry(item.inputType);
+  if (registryEntry && typeof registryEntry.render === "function") {
+    templateString = registryEntry.render(item, parentTemplates, dataVariable);
+    if (item.computedValue && item.variableName) {
+      templateString = `${templateString || ""}<FormHidden v-model="${dataVariable}.${item.variableName}" :item-value="data" :hook="()=>${item.computedValue}"/>`.trim();
+    }
+    return templateString || "";
+  }
   switch (item.inputType) {
     case "CustomCode":
       templateString = item.inputCustomCode || "";

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

@@ -0,0 +1,228 @@
+/**
+ * Registry of input types available in `<DocumentTemplateBuilder>` (the
+ * structured editor for document templates) AND consumable by the runtime
+ * renderer (`useDocumentTemplate` in `./template.ts`).
+ *
+ * **Single registration entry point:** `registerDocumentTemplateInputType`.
+ *
+ * Use it from a Nuxt plugin to add an entry app-wide. The same `entry` object
+ * carries everything — dropdown label, builder-UI flags, and an optional
+ * `render` function consumed by the runtime renderer in `template.ts`:
+ *
+ * ```ts
+ * // app/plugins/document-template-inputs.ts
+ * export default defineNuxtPlugin(() => {
+ *   registerDocumentTemplateInputType({
+ *     label: 'From Staff',
+ *     value: 'FromStaff',
+ *     render(item, _parents, dataVariable) {
+ *       return `<FromStaff :staff-id="${dataVariable}.${item.variableName}" />`
+ *     },
+ *   })
+ * })
+ * ```
+ *
+ * For rare page-scoped extensions, call `useDocumentTemplateInputType()` in
+ * `<script setup>` — it wraps `register` + `onScopeDispose` so the entry is
+ * removed automatically when the component unmounts.
+ *
+ * Merge order (later wins on `value` collision):
+ *   built-in ⊕ runtime-registry
+ *
+ * The runtime renderer dispatches as follows inside `templateItemToString`:
+ *   1. If the registered entry for `inputType` has a `render` function → call it.
+ *   2. Else if `inputType` is one of the built-in special cases (Header,
+ *      Separator, FormTable, …) → use the hand-written switch arm.
+ *   3. Else → `processDefaultTemplate` (the v-model/label fallback).
+ *
+ * The `computedValue` post-pass (appending `<FormHidden>` to write a derived
+ * value back to `data[variableName]`) still runs unconditionally, so custom
+ * renderers don't need to handle it.
+ */
+import type { DocumentTemplateItem } from './template.js';
+/**
+ * Signature for a custom renderer registered against a specific `inputType`.
+ *
+ * Must return the Vue template fragment string to splice into the document
+ * template. Receives:
+ *
+ *   - `item` — a `cloneDeep`'d copy of the template item, with two
+ *     transformations already applied to `item.inputAttributes`:
+ *       1. `migrateInputAttributes()` — Vuetify v3→v4 attribute migration
+ *          (e.g. bare `dense` → `density="compact"`).
+ *       2. If `item.conditionalDisplay` was set, `v-if="<expr>"` has already
+ *          been appended. **Renderers don't need to handle
+ *          `conditionalDisplay` separately** — just include
+ *          `item.inputAttributes` on the emitted tag.
+ *   - `parentTemplates` — chain of ancestor template codes (used by nested
+ *     types like `DocumentForm` / `FormTable`); pass-through to nested
+ *     `useDocumentTemplate()` calls when relevant.
+ *   - `dataVariable` — the form `data` variable name. `"data"` at the top
+ *     level; nested tables pass their row alias (e.g. `"row"`).
+ *
+ * **Helpers safe to import from `./template`:**
+ *
+ *   - `buildValidationRules(item.validationRules)` — produces the
+ *     `:rules="[rules.x()]"` attribute string (or `''` when no rules).
+ *     The same helper used by the built-in switch arms.
+ *   - `optionStringToChoiceObject(item.inputOptions)` — parses
+ *     `"a|1,b|2"` / array forms into `ChoiceItem[]`.
+ *   - `escapeObjectForInlineBinding(obj)` — `JSON.stringify` + `'` escaping
+ *     for inline `v-bind` payloads.
+ *   - `processDefaultTemplate(item, insideTemplate?, optionString?, validationRules?, dataVariable?)`
+ *     — the same fallback used for unknown types. Call it from a renderer
+ *     when you want "the default plus a wrapper".
+ *
+ * **Handled for you AFTER `render` returns:**
+ *
+ *   - The `computedValue` post-pass that appends
+ *     `<FormHidden v-model="data.x" :hook="()=>computedValue"/>`
+ *     when both `item.computedValue` and `item.variableName` are set.
+ *   - Column wrapping (`<v-col cols=…>`), `columnAttributes`, `customClass`,
+ *     `customStyle` are applied by the caller (`columnWrapTemplateItemString`).
+ *
+ * **What `optionString` is and why it isn't passed:** the built-in switch
+ * arms precompute an `optionString` for the specific built-in option-bearing
+ * types (`MasterAutocomplete`, `VSelect`, `VAutocomplete`, `VCombobox`,
+ * `FormCheckboxGroup`, `VRadio`, `VRadioInline`, `Header`). For any
+ * custom-registered `inputType` that string is empty, so passing it would
+ * be dead weight. Compose your own option markup with the two helpers above
+ * when needed.
+ *
+ * **Minimal "field-shaped" renderer template:**
+ *
+ *   ```ts
+ *   import { buildValidationRules } from '@ramathibodi/nuxt-commons'
+ *
+ *   render(item, _parents, dataVariable) {
+ *     const variable = (item.variableName ?? '').replace(/[^\w$]/g, '')
+ *     const attrs = item.inputAttributes ? ` ${item.inputAttributes.trim()}` : ''
+ *     const rules = item.validationRules ? buildValidationRules(item.validationRules) : ''
+ *     return `<MyComponent `
+ *       + `:value="${dataVariable}.${variable}" `
+ *       + `@update:value="v => ${dataVariable}.${variable} = v"`
+ *       + `${attrs}${rules ? ' ' + rules : ''}/>`
+ *   }
+ *   ```
+ */
+export type DocumentTemplateInputTypeRenderer = (item: DocumentTemplateItem, parentTemplates: string | string[], dataVariable: string) => string;
+export interface DocumentTemplateInputType {
+    /** Label shown in the input-type dropdown. */
+    label: string;
+    /**
+     * `inputType` value stored in the template JSON. For app-specific types,
+     * this must be a globally-registered Vue component tag — the runtime
+     * renderer emits it as `<value v-model=… label=… …/>`.
+     */
+    value: string;
+    /** Default `true`. Set `false` for decoration types (e.g. `Header`, `Separator`). */
+    needsVariableName?: boolean;
+    /** Default `true`. Set `false` for types that have no label (e.g. `Separator`, `CustomCode`). */
+    needsLabel?: boolean;
+    /** Default `true`. Set `false` for types laid out outside the grid (e.g. `Separator`, `FormHidden`). */
+    needsWidth?: boolean;
+    /**
+     * Whether the generic `inputOptions` editor (textarea / specific editor)
+     * is shown. Default `true`. Set `false` only when the type has no
+     * meaningful inputOptions (e.g. `Separator`, `CustomCode`, `FormFile`).
+     */
+    showsOptions?: boolean;
+    /** Default `false`. Set `true` to make `inputOptions` required in the editor. */
+    requiresOptions?: boolean;
+    /** Override the textarea label (`'Input Options'` by default). */
+    optionsLabel?: string;
+    /**
+     * Render the choice-array editor instead of a plain textarea. Applies to
+     * the choice-style inputs (select, radio, checkbox-group, etc.).
+     */
+    optionsAsChoice?: boolean;
+    /**
+     * Marks the type as having a custom inputOptions sub-editor handled inline
+     * by `TemplateBuilder.vue` (FormHidden / FormTable / FormTableData). Apps
+     * cannot extend this; new built-ins must update the builder UI as well.
+     */
+    hasSpecificOptionEditor?: boolean;
+    /** Default `false`. Hides the Validations expansion panel. */
+    hidesValidationRules?: boolean;
+    /** Default `false`. Hides the `Input Attributes` field inside Advanced settings. */
+    hidesInputAttributes?: boolean;
+    /** Default `false`. Hides the `Column Attributes` field inside Advanced settings. */
+    hidesColumnAttributes?: boolean;
+    /** Default `false`. Hides the entire Advanced settings expansion panel. */
+    hidesAdvancedSettings?: boolean;
+    /** Default `false`. Hides the Class and Styles expansion panel. */
+    hidesClassAndStyle?: boolean;
+    /**
+     * Optional renderer that overrides the default `<Tag v-model="…" label="…"/>`
+     * emission for this `inputType`. Use when an app component does not follow
+     * the standard contract (different value prop, slot content, etc.).
+     */
+    render?: DocumentTemplateInputTypeRenderer;
+}
+/**
+ * Built-in registry. One entry per inputType that `TemplateBuilder.vue`
+ * historically hard-coded. Flag values mirror the previous arrays
+ * (`requireOption`, `notRequireVariable`, `notRequireLabel`, `notRequireWidth`,
+ * `notRequireOptions`, `notRequireRules`, `notRequireInputAttributes`,
+ * `notRequireColumnAttributes`, `notRequireAdvancedSetting`,
+ * `notRequireClassAndStyle`, `choiceOption`, `inputOptionsLabel`,
+ * `hasSpecificOption`).
+ */
+export declare const BUILT_IN_DOCUMENT_TEMPLATE_INPUT_TYPES: readonly DocumentTemplateInputType[];
+/**
+ * Merge multiple lists of input-type definitions. Later entries win on
+ * `value` collision, allowing a consumer to override a built-in entry's
+ * label or flags (e.g. relabel "Text Field" to "Free Text" in one app).
+ *
+ * Render functions follow the same precedence: a later entry without
+ * `render` does NOT clear an earlier-registered render (the shallow merge
+ * keeps the prior value). To explicitly remove a render, set
+ * `render: undefined` on the later entry, or call
+ * `unregisterDocumentTemplateInputType`.
+ */
+export declare function mergeDocumentTemplateInputTypes(...lists: Array<readonly DocumentTemplateInputType[] | DocumentTemplateInputType[] | undefined | null>): DocumentTemplateInputType[];
+/**
+ * Register (or upsert) an input-type entry. Returns an `unregister()`
+ * function so callers — especially HMR-aware Nuxt plugins — can revert the
+ * registration. Calling `register` twice with the same `value` performs a
+ * shallow merge, matching the wider `mergeDocumentTemplateInputTypes`
+ * semantics. No-op (and returns a no-op unregister) when `entry` lacks a
+ * string `value`.
+ *
+ * **Where to call from:**
+ * - Nuxt plugin (`app/plugins/*.ts`) — the canonical place for app-wide
+ *   registration. Entries persist for the lifetime of the app.
+ * - Inside a Vue component setup — prefer `useDocumentTemplateInputType`
+ *   instead; it wraps this function with auto-cleanup on unmount.
+ */
+export declare function registerDocumentTemplateInputType(entry: DocumentTemplateInputType): () => void;
+/** Explicit removal — handy in unit tests and for one-off cleanup. */
+export declare function unregisterDocumentTemplateInputType(value: string): void;
+/**
+ * Page-scoped registration. Calls `registerDocumentTemplateInputType` and
+ * schedules the returned `unregister()` on `onScopeDispose`, so the entry
+ * is removed automatically when the surrounding effect scope (typically a
+ * Vue component's setup) is disposed.
+ *
+ * If called outside an effect scope, the registration persists for the
+ * lifetime of the runtime — at which point you should use
+ * `registerDocumentTemplateInputType` directly so the lifecycle is explicit.
+ */
+export declare function useDocumentTemplateInputType(entry: DocumentTemplateInputType): void;
+/** Snapshot of the runtime registry. Internal — exported for tests. */
+export declare function _getDocumentTemplateRuntimeRegistry(): DocumentTemplateInputType[];
+/** Test-only reset. Does not affect built-ins. */
+export declare function _resetDocumentTemplateRuntimeRegistry(): void;
+/**
+ * Look up a single entry from the merged registry (built-in ⊕ runtime).
+ * Used by `templateItemToString` to decide whether a custom `render` is in
+ * play.
+ */
+export declare function getDocumentTemplateInputTypeEntry(value: string): DocumentTemplateInputType | undefined;
+/**
+ * Read the merged input-type registry: built-in ⊕ runtime registry.
+ * Stable across calls (re-reads on every call so HMR-driven re-registration
+ * picks up). Returns a fresh array — callers may mutate without affecting
+ * the underlying state.
+ */
+export declare function useDocumentTemplateInputTypes(): DocumentTemplateInputType[];

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

@@ -0,0 +1,128 @@
+import { getCurrentScope, onScopeDispose } from "vue";
+export const BUILT_IN_DOCUMENT_TEMPLATE_INPUT_TYPES = Object.freeze([
+  { label: "Text Field", value: "VTextField" },
+  { label: "Text Area", value: "VTextarea" },
+  { label: "Text Date Picker", value: "FormDate" },
+  { label: "Text Time Picker", value: "FormTime" },
+  { label: "Text Date & Time Picker", value: "FormDateTime" },
+  { label: "Select Dropdown", value: "VSelect", requiresOptions: true, optionsAsChoice: true },
+  { label: "Select Combobox", value: "VCombobox", requiresOptions: true, optionsAsChoice: true },
+  { label: "Autocomplete", value: "VAutocomplete", requiresOptions: true, optionsAsChoice: true },
+  { label: "Autocomplete from Master", value: "MasterAutocomplete", requiresOptions: true, optionsLabel: "Group Key" },
+  { label: "Radio Buttons", value: "VRadio", requiresOptions: true, optionsAsChoice: true },
+  { label: "Radio Buttons Inline", value: "VRadioInline", requiresOptions: true, optionsAsChoice: true },
+  { label: "Checkbox", value: "VCheckbox" },
+  { label: "Checkbox Group", value: "FormCheckboxGroup", requiresOptions: true, optionsAsChoice: true },
+  { label: "Switch", value: "VSwitch" },
+  { label: "File Upload", value: "FormFile", needsLabel: false, showsOptions: false },
+  { label: "Signature Pad", value: "FormSignPad" },
+  { label: "Table", value: "FormTable", requiresOptions: true, hasSpecificOptionEditor: true },
+  { label: "Table Data", value: "FormTableData", requiresOptions: true, hasSpecificOptionEditor: true },
+  {
+    label: "[Decoration] Header",
+    value: "Header",
+    needsVariableName: false,
+    needsWidth: false,
+    optionsLabel: "Class",
+    hidesValidationRules: true,
+    hidesInputAttributes: true
+  },
+  {
+    label: "[Decoration] Separator",
+    value: "Separator",
+    needsVariableName: false,
+    needsLabel: false,
+    needsWidth: false,
+    showsOptions: false,
+    hidesValidationRules: true,
+    hidesInputAttributes: true,
+    hidesColumnAttributes: true,
+    hidesAdvancedSettings: true
+  },
+  {
+    label: "[Advanced] Hidden Field",
+    value: "FormHidden",
+    needsLabel: false,
+    needsWidth: false,
+    hasSpecificOptionEditor: true,
+    hidesValidationRules: true,
+    hidesColumnAttributes: true,
+    hidesClassAndStyle: true
+  },
+  {
+    label: "[Advanced] Inherit Form",
+    value: "DocumentForm",
+    needsVariableName: false,
+    needsLabel: false,
+    needsWidth: false,
+    requiresOptions: true,
+    optionsLabel: "Template Code",
+    hidesValidationRules: true,
+    hidesInputAttributes: true,
+    hidesColumnAttributes: true
+  },
+  {
+    label: "[Advanced] Custom Code",
+    value: "CustomCode",
+    needsVariableName: false,
+    needsLabel: false,
+    showsOptions: false,
+    hidesValidationRules: true,
+    hidesInputAttributes: true,
+    hidesAdvancedSettings: true
+  }
+]);
+export function mergeDocumentTemplateInputTypes(...lists) {
+  const byValue = /* @__PURE__ */ new Map();
+  for (const list of lists) {
+    if (!list) continue;
+    for (const entry of list) {
+      if (!entry || typeof entry.value !== "string" || entry.value.length === 0) continue;
+      byValue.set(entry.value, { ...byValue.get(entry.value), ...entry });
+    }
+  }
+  return [...byValue.values()];
+}
+const runtimeRegistry = /* @__PURE__ */ new Map();
+export function registerDocumentTemplateInputType(entry) {
+  if (!entry || typeof entry.value !== "string" || entry.value.length === 0) {
+    return () => {
+    };
+  }
+  const previous = runtimeRegistry.get(entry.value);
+  const merged = { ...previous, ...entry };
+  runtimeRegistry.set(entry.value, merged);
+  return () => {
+    if (runtimeRegistry.get(entry.value) === merged) {
+      runtimeRegistry.delete(entry.value);
+    }
+  };
+}
+export function unregisterDocumentTemplateInputType(value) {
+  runtimeRegistry.delete(value);
+}
+export function useDocumentTemplateInputType(entry) {
+  const unregister = registerDocumentTemplateInputType(entry);
+  if (getCurrentScope()) {
+    onScopeDispose(unregister);
+  }
+}
+export function _getDocumentTemplateRuntimeRegistry() {
+  return [...runtimeRegistry.values()];
+}
+export function _resetDocumentTemplateRuntimeRegistry() {
+  runtimeRegistry.clear();
+}
+export function getDocumentTemplateInputTypeEntry(value) {
+  if (!value) return void 0;
+  const fromRuntime = runtimeRegistry.get(value);
+  const builtIn = BUILT_IN_DOCUMENT_TEMPLATE_INPUT_TYPES.find((t) => t.value === value);
+  if (fromRuntime) return { ...builtIn, ...fromRuntime };
+  return builtIn;
+}
+export function useDocumentTemplateInputTypes() {
+  return mergeDocumentTemplateInputTypes(
+    BUILT_IN_DOCUMENT_TEMPLATE_INPUT_TYPES,
+    _getDocumentTemplateRuntimeRegistry()
+  );
+}

package/dist/runtime/types/graphqlOperation.d.ts

@@ -1,6 +1,8 @@
 export interface graphqlVariable {
   name: string
-  list?: boolean
+  // `true` for `[T]`, `[true]` for `[T!]` — matches gql-query-builder's
+  // VariableOptions shape so element non-null survives into the query string.
+  list?: boolean | [boolean]
   required?: boolean
   type?: string
   value?: any

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ramathibodi/nuxt-commons",
-  "version": "4.0.9",
+  "version": "4.0.11",
   "description": "Ramathibodi Nuxt modules for common components",
   "repository": {
     "type": "git",
@@ -47,6 +47,8 @@
     "prepack": "nuxt-module-build build",
     "dev": "npm run dev:prepare && nuxt dev playground",
     "dev:build": "nuxt build playground",
+    "dev:generate": "nuxt generate playground",
+    "playground:scaffold": "node scripts/scaffold-playground-pages.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",

package/scripts/generate-ai-summary.mjs

@@ -159,6 +159,73 @@ function extractEmits(content) {
   return emits
 }
 
+function extractTemplate(content) {
+  const m = content.match(/<template[^>]*>([\s\S]*)<\/template>/i)
+  return m ? m[1] : ''
+}
+
+function extractSlots(content) {
+  const slots = []
+  const seen = new Set()
+  const template = extractTemplate(content)
+  if (!template) return slots
+
+  const slotRe = /<slot\b([^>]*?)(?:\/?>)/g
+  let match
+  while ((match = slotRe.exec(template)) !== null) {
+    const attrs = match[1] || ''
+    const nameMatch = attrs.match(/(?:^|\s)name\s*=\s*"([^"]+)"/)
+                   || attrs.match(/(?:^|\s)#([A-Za-z_][A-Za-z0-9_-]*)/)
+    const name = nameMatch ? nameMatch[1] : 'default'
+    if (seen.has(name)) continue
+    seen.add(name)
+
+    const bindings = []
+    const bindRe = /:([A-Za-z_][A-Za-z0-9_-]*)\s*=\s*"([^"]*)"/g
+    let bm
+    while ((bm = bindRe.exec(attrs)) !== null) {
+      if (bm[1] === 'name') continue
+      bindings.push({ name: bm[1], expression: compact(bm[2]) })
+    }
+    slots.push({ name, bindings })
+  }
+  return slots
+}
+
+function extractExposed(content) {
+  const exposed = []
+  const m = content.match(/defineExpose\s*\(\s*\{([\s\S]*?)\}\s*\)/)
+  if (!m) return exposed
+  const body = m[1]
+  // Match top-level identifiers; ignore values, nested braces handled by depth.
+  let depth = 0
+  let token = ''
+  const tokens = []
+  for (let i = 0; i < body.length; i++) {
+    const ch = body[i]
+    if (ch === '{' || ch === '(' || ch === '[') depth++
+    else if (ch === '}' || ch === ')' || ch === ']') depth--
+    else if (ch === ',' && depth === 0) {
+      tokens.push(token); token = ''
+      continue
+    }
+    token += ch
+  }
+  if (token.trim()) tokens.push(token)
+
+  for (const raw of tokens) {
+    const piece = raw.trim().replace(/^\s*\/\/.*$/gm, '').replace(/\/\*[\s\S]*?\*\//g, '').trim()
+    if (!piece) continue
+    // `name`, `name: value`, `name(...) {}` — take the first identifier.
+    const idMatch = piece.match(/^([A-Za-z_$][A-Za-z0-9_$]*)/)
+    if (!idMatch) continue
+    const name = idMatch[1]
+    if (exposed.find(e => e.name === name)) continue
+    exposed.push({ name })
+  }
+  return exposed
+}
+
 function extractExports(content) {
   const functions = []
   const constants = []
@@ -251,11 +318,15 @@ for (const file of componentFiles) {
   const summary = extractTopDescription(content)
   const props = extractProps(content)
   const emits = extractEmits(content)
+  const slots = extractSlots(content)
+  const exposed = extractExposed(content)
   const componentEntry = {
     path: rel,
     summary,
     props,
     emits,
+    slots,
+    exposed,
   }
   docModel.components.push(componentEntry)
 
@@ -283,6 +354,23 @@ for (const file of componentFiles) {
   } else {
     lines.push('- Emits: None detected.')
   }
+  if (slots.length) {
+    lines.push(`- Slots (${slots.length}):`)
+    for (const s of slots) {
+      const bindings = s.bindings.length ? ` bindings: ${s.bindings.map(b => `${b.name}=${b.expression}`).join(', ')}` : ''
+      lines.push(`  - \`${s.name}\`${bindings}`)
+    }
+  } else {
+    lines.push('- Slots: None detected.')
+  }
+  if (exposed.length) {
+    lines.push(`- Exposed (${exposed.length}):`)
+    for (const x of exposed) {
+      lines.push(`  - \`${x.name}\``)
+    }
+  } else {
+    lines.push('- Exposed: None detected.')
+  }
   lines.push('')
 }
 

package/scripts/scaffold-playground-pages.mjs

@@ -0,0 +1,207 @@
+#!/usr/bin/env node
+/**
+ * Scaffold per-component playground pages.
+ *
+ * Reads docs/ai-summary.json and, for every component under
+ * src/runtime/components/, emits:
+ *   - playground/pages/components/<slug>.vue   (stub demo + API panel)
+ *   - playground/playgrounds.generated.ts      (component registry array)
+ *
+ * Idempotency: pages start with a "SCAFFOLD_MARKER" comment. The script
+ * overwrites only files that still carry the marker — hand-edited pages
+ * (marker removed) are left alone.
+ *
+ * Run with: pnpm exec node scripts/scaffold-playground-pages.mjs
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+
+const rootDir = process.cwd()
+const aiSummary = JSON.parse(fs.readFileSync(path.join(rootDir, 'docs/ai-summary.json'), 'utf8'))
+const pagesDir = path.join(rootDir, 'playground/pages/components')
+const registryFile = path.join(rootDir, 'playground/playgrounds.generated.ts')
+
+const SCAFFOLD_MARKER = '<!-- SCAFFOLD: auto-generated by scripts/scaffold-playground-pages.mjs. Delete this line to opt out of overwrites. -->'
+
+function pascal(segment) {
+  return segment.charAt(0).toUpperCase() + segment.slice(1)
+}
+
+function deriveNames(componentPath) {
+  // componentPath like "src/runtime/components/form/images/Pad.vue"
+  const rel = componentPath.replace(/^src\/runtime\/components\//, '').replace(/\.vue$/, '')
+  const segments = rel.split('/')
+  const componentName = segments.map(pascal).join('')
+  const slug = segments.map(s => s.toLowerCase()).join('-')
+  const title = componentName
+  // First path segment is the group; root-level components fall into "general".
+  const group = segments.length > 1 ? segments[0].toLowerCase() : 'general'
+  return { componentName, slug, title, group }
+}
+
+function renderPage({ componentName, title, summary, sourcePath }) {
+  const props = inferStubProps(componentName)
+  const propsAttr = props ? ' ' + props : ''
+  const setup = setupForComponent[componentName] ?? ''
+  return `<script setup lang="ts">
+// ${SCAFFOLD_MARKER.replace(/^<!--\s*|\s*-->$/g, '')}
+//
+// To enrich this page (richer demo, multiple variants, controls, etc.),
+// remove the SCAFFOLD comment in the <template> below — the scaffold
+// script will then leave this file alone on future runs.
+${setup}</script>
+
+<template>
+  ${SCAFFOLD_MARKER}
+  <PlaygroundPage
+    title="${title}"
+    summary="${escapeAttr(summary)}"
+    source-path="${sourcePath}"
+  >
+    <div class="text-caption text-medium-emphasis mb-3">
+      Auto-scaffolded demo — mounts the component with minimal props.
+      Replace this block (and delete the SCAFFOLD comment) when you wire
+      up a realistic interactive demo.
+    </div>
+    <${componentName}${propsAttr} />
+  </PlaygroundPage>
+</template>
+`
+}
+
+function escapeAttr(s) {
+  return (s || '').replace(/"/g, '&quot;').replace(/\n/g, ' ')
+}
+
+/**
+ * Hand-tuned minimal props for components that throw without them.
+ * Keep tiny — anything richer belongs in a hand-enriched page.
+ */
+const stubProps = {
+  FormTable: 'title="Demo table"',
+  FormTableData: 'title="Demo table"',
+  FormActionPad: 'title="Demo"',
+  FormEditPad: 'title="Demo"',
+  FormSystem: 'name="demoForm"',
+  FormDialog: ':model-value="false" title="Demo"',
+  FormImagesCapture: 'title="Demo"',
+  FormImagesEdit: 'title="Demo"',
+  FormImagesField: 'title="Demo"',
+  FormImagesPad: 'title="Demo"',
+  DialogConfirm: ':model-value="false"',
+  DialogLoading: ':model-value="false"',
+  DialogIndex: ':model-value="false" title="Demo"',
+  DialogHost: '',
+  DialogDefaultConfirm: ':model-value="false"',
+  DialogDefaultLoading: ':model-value="false"',
+  DialogDefaultNotify: ':model-value="false"',
+  DialogDefaultPrinting: ':model-value="false"',
+  DialogDefaultVerifyUser: ':model-value="false"',
+  DocumentForm: 'documentName="demo"',
+  DocumentTemplateBuilder: 'title="Template Builder"',
+  ModelTable: 'modelName="MasterItem" :fields="[\'*\']"',
+  ModelPad: 'modelName="MasterItem"',
+  ModelIterator: 'modelName="MasterItem" :fields="[\'*\']"',
+  ModelLabel: 'modelName="MasterItem"',
+  ModelSelect: 'modelName="MasterItem"',
+  ModelAutocomplete: 'modelName="MasterItem"',
+  ModelCombobox: 'modelName="MasterItem"',
+  MasterLabel: 'groupKey="DEMO"',
+  MasterSelect: 'groupKey="DEMO"',
+  MasterAutocomplete: 'groupKey="DEMO"',
+  MasterCombobox: 'groupKey="DEMO"',
+  MasterRadioGroup: 'groupKey="DEMO"',
+  LabelDate: 'model-value="2026-05-18"',
+  LabelDateAgo: ':model-value="DateTime.now()"',
+  LabelDateCount: ':model-value="DateTime.now()"',
+  LabelField: 'label="Demo" model-value="value"',
+  LabelFormatMoney: ':model-value="1234.5"',
+  LabelMask: 'mask="###-###-####" model-value="1234567890"',
+  LabelObject: ':model-value="{ key: \'value\' }"',
+  PdfView: '',
+  PdfPrint: '',
+  SplitterPanel: '',
+  TabsGroup: ':items="[{ label: \'Tab 1\' }, { label: \'Tab 2\' }]"',
+  ImportCSV: '',
+  ExportCSV: ':model-value="[]" file-name="demo"',
+  FileBtn: 'label="Upload"',
+  BarcodeReader: '',
+  MrzReader: '',
+  TextBarcode: ':model-value="\'ABC123\'"',
+  Alert: '',
+  DeviceIdCardButton: '',
+  DeviceIdCardWebSocket: '',
+  DeviceScanner: '',
+  FormLogin: '',
+  FormPad: '',
+  FormBirthdate: '',
+  FormCheckboxGroup: ':items="[{ title: \'One\', value: 1 }, { title: \'Two\', value: 2 }]"',
+  FormCodeEditor: 'language="javascript"',
+  FormDate: '',
+  FormDateTime: '',
+  FormTime: '',
+  FormFile: '',
+  FormHidden: '',
+  FormIterator: '',
+  FormSignPad: '',
+}
+
+function inferStubProps(componentName) {
+  return stubProps[componentName] ?? ''
+}
+
+/** Per-component <script setup> snippets injected after the SCAFFOLD comment. */
+const setupForComponent = {
+  LabelDateAgo: `import { DateTime } from 'luxon'\n`,
+  LabelDateCount: `import { DateTime } from 'luxon'\n`,
+}
+
+function shouldOverwrite(filePath) {
+  if (!fs.existsSync(filePath)) return true
+  const content = fs.readFileSync(filePath, 'utf8')
+  return content.includes(SCAFFOLD_MARKER)
+}
+
+const entries = []
+let written = 0
+let skipped = 0
+
+for (const component of aiSummary.components) {
+  const { componentName, slug, title, group } = deriveNames(component.path)
+  const summary = (component.summary || '').replace(/"/g, '\'')
+  const sourcePath = component.path
+
+  const subdir = slug.includes('-') ? '' : '' // flat layout under components/
+  const fileName = `${slug}.vue`
+  const filePath = path.join(pagesDir, subdir, fileName)
+  fs.mkdirSync(path.dirname(filePath), { recursive: true })
+
+  if (shouldOverwrite(filePath)) {
+    fs.writeFileSync(filePath, renderPage({ componentName, title, summary, sourcePath }))
+    written++
+  }
+  else {
+    skipped++
+  }
+
+  entries.push({
+    slug,
+    title,
+    summary,
+    to: `/components/${slug}`,
+    group,
+  })
+}
+
+entries.sort((a, b) => a.slug.localeCompare(b.slug))
+
+const registrySource = `// Auto-generated by scripts/scaffold-playground-pages.mjs.
+// Do not edit by hand — re-run the script after adding components.
+import type { PlaygroundEntry } from './playgrounds'
+
+export const componentEntries: PlaygroundEntry[] = ${JSON.stringify(entries, null, 2)}
+`
+fs.writeFileSync(registryFile, registrySource)
+
+console.log(`Pages scaffolded: ${written} written, ${skipped} preserved (hand-edited).`)
+console.log(`Registry: ${path.relative(rootDir, registryFile)} (${entries.length} entries)`)

package/templates/.codegen/plugin-schema-object.cjs

@@ -6,14 +6,21 @@ function capitalizeFirstLetter(string) {
   return string.charAt(0).toUpperCase() + string.slice(1)
 }
 
-function inputTypeToObject(inputType, result) {
+// `inList` flips to true the moment we descend into a ListType, so a NonNullType
+// nested under a List is recognized as element-non-null (`[T!]`) rather than
+// overwriting the outer list's `required` flag. The element-non-null is encoded
+// as `list: [true]` — the shape gql-query-builder reads to emit `[T!]`.
+function inputTypeToObject(inputType, result, inList = false) {
   if (inputType.kind === 'NonNullType') {
-    result['required'] = true
-    inputTypeToObject(inputType.type, result)
+    if (inList) result['list'] = [true]
+    else result['required'] = true
+    inputTypeToObject(inputType.type, result, inList)
+    return
   }
   if (inputType.kind === 'ListType') {
-    result['list'] = true
-    inputTypeToObject(inputType.type, result)
+    if (!Array.isArray(result['list'])) result['list'] = true
+    inputTypeToObject(inputType.type, result, true)
+    return
   }
   if (inputType.kind === 'NamedType') {
     result['type'] = inputType.name.value
@@ -21,6 +28,7 @@ function inputTypeToObject(inputType, result) {
 }
 
 module.exports = {
+  inputTypeToObject,
   plugin(schema, _documents, _config) {
     const astNode = getCachedDocumentNodeFromSchema(schema) // Transforms the GraphQLSchema into ASTNode