@ramathibodi/nuxt-commons 0.1.72 → 0.1.74

package/README.md

@@ -1,45 +1,54 @@
-<!--
-Get your module up and running quickly.
-
-Find and replace all on all files (CMD+SHIFT+F):
-- Name: Ramahis Common Component
-- Package name: @ramahis/common-components
--->
-
 # @ramathibodi/nuxt-commons
 
-[![npm version][npm-version-src]][npm-version-href]
-[![npm downloads][npm-downloads-src]][npm-downloads-href]
-[![License][license-src]][license-href]
-[![Nuxt][nuxt-src]][nuxt-href]
-
+Nuxt 3 module that provides shared runtime building blocks for Rama projects:
+- globally auto-imported UI components
+- auto-imported composables
+- runtime plugins for permission/dialog/default behavior
+- utility and lab exports
 
-## Quick Setup
-
-1. Add `'@ramathibodi/nuxt-commons'` dependency to your project
+## Install
 
 ```bash
-# Using pnpm
+# pnpm
 pnpm add -D @ramathibodi/nuxt-commons
 
-# Using yarn
+# yarn
 yarn add --dev @ramathibodi/nuxt-commons
 
-# Using npm
+# npm
 npm install --save-dev @ramathibodi/nuxt-commons
 ```
 
-2. Add `my-module` to the `modules` section of `nuxt.config.ts`
+## Nuxt Setup
 
-```js
+```ts
+// nuxt.config.ts
 export default defineNuxtConfig({
-  modules: [
-    '@ramathibodi/nuxt-commons'
-  ]
+  modules: ['@ramathibodi/nuxt-commons'],
 })
 ```
 
-That's it! You can now use My Module in your Nuxt app ✨
+## What The Module Registers
+
+Configured in `src/module.ts`:
+- Components from `src/runtime/components` (global + prefixed)
+- Composables from `src/runtime/composables/**` (auto-imported)
+- Plugins:
+  - `src/runtime/plugins/permission.ts`
+  - `src/runtime/plugins/dialogManager.ts` (client)
+  - `src/runtime/plugins/clientConfig.ts` (client)
+  - `src/runtime/plugins/default.ts` (client)
+- Type templates from `src/runtime/types/*.d.ts`
+
+## Runtime Config
+
+This module uses public runtime config at:
+
+```ts
+runtimeConfig.public['nuxt-commons']
+```
+
+Module options are merged into this key by module setup.
 
 ## Development
 
@@ -47,50 +56,60 @@ That's it! You can now use My Module in your Nuxt app ✨
 # Install dependencies
 npm install
 
-# Generate type stubs
+# Prepare stubs/types
 npm run dev:prepare
 
-# Develop with the playground
+# Run playground
 npm run dev
 
-# Build the playground
+# Build playground
 npm run dev:build
 
-# Run ESLint
+# Lint and test
 npm run lint
-
-# Run Vitest
 npm run test
-npm run test:watch
-
-# Release new version
-npm run release
 ```
 
-## NPM Login
-```bash
-npm login
-```
-- จะส่ง link url มาให้เข้าไปที่ url login npm
+## Documentation
+
+Generate documentation artifacts from source:
 
-## NPM PUBLISH
 ```bash
-1. ตรวจสอบ source code, ตรวจสอบ Branch ว่าเป็น master แล้ว จากนั้นตรวจสอบ version ของ npm ว่ามีการเปลี่ยนและไม่ชนกับ version บน npm
-2. npm run dev:build
-3. npm publish --access public
-4. set token ใน link ที่ npm ให้มา
-5. เสร็จสิ้น
+# Vue component API docs (vue-docgen)
+npm run docs:api:components
+
+# Composable API docs (typedoc)
+npm run docs:api:composables
+
+# Both API docs
+npm run docs:api
+
+# AI-focused summary + type index
+npm run docs:ai:summary
 ```
 
-<!-- Badges -->
-[npm-version-src]: https://img.shields.io/npm/v/my-module/latest.svg?style=flat&colorA=18181B&colorB=28CF8D
-[npm-version-href]: https://npmjs.com/package/my-module
+`docs:api:components` now runs a post-process step that enriches missing prop/event descriptions and missing type/default cells in generated markdown using `docs/ai-summary.json`.
 
-[npm-downloads-src]: https://img.shields.io/npm/dm/my-module.svg?style=flat&colorA=18181B&colorB=28CF8D
-[npm-downloads-href]: https://npmjs.com/package/my-module
+Documentation config files:
+- [`docs/vue-docgen.config.cjs`](docs/vue-docgen.config.cjs) for component docs generation
+- [`docs/typedoc.json`](docs/typedoc.json) for composable docs generation
+- [`docs/typedoc.tsconfig.json`](docs/typedoc.tsconfig.json) for docs-only TypeScript scope
 
-[license-src]: https://img.shields.io/npm/l/my-module.svg?style=flat&colorA=18181B&colorB=28CF8D
-[license-href]: https://npmjs.com/package/my-module
+Generated outputs:
+- [`docs/components/`](docs/components/) (vue-docgen output)
+- [`docs/composables/`](docs/composables/) (typedoc output)
+- [`docs/ai-summary.md`](docs/ai-summary.md) (compact AI-oriented markdown summary)
+- [`docs/ai-summary.json`](docs/ai-summary.json) (machine-readable component/composable metadata)
+- [`docs/type-index.json`](docs/type-index.json) (type index for tooling/AI pipelines)
 
-[nuxt-src]: https://img.shields.io/badge/Nuxt-18181B?logo=nuxt.js
-[nuxt-href]: https://nuxt.com
+`docs:ai:summary` generates:
+- `docs/ai-summary.md`
+- `docs/ai-summary.json`
+- `docs/type-index.json`
+
+## Publish Notes
+
+```bash
+npm run dev:build
+npm publish --access public
+```

package/dist/module.json

@@ -4,7 +4,7 @@
   "compatibility": {
     "nuxt": "^3.0.0"
   },
-  "version": "0.1.72",
+  "version": "0.1.74",
   "builder": {
     "@nuxt/module-builder": "0.8.4",
     "unbuild": "2.0.0"

package/dist/module.mjs

@@ -20,6 +20,7 @@ const module = defineNuxtModule({
       global: true
     });
     addImportsDir(resolver.resolve("runtime/composables/**"));
+    addImportsDir(resolver.resolve("runtime/utils/**"));
     addPlugin({
       src: resolver.resolve("runtime/plugins/permission")
     });

package/dist/runtime/components/Alert.vue

@@ -1,4 +1,8 @@
 <script lang="ts" setup>
+/**
+ * Alert displays runtime alert messages and bridges alert-store entries to a consistent UI variant system.
+ * This doc block is consumed by vue-docgen for generated API documentation.
+ */
 import { ref, watch } from 'vue'
 import { isEmpty } from 'lodash-es'
 import { useAlert } from '../composables/alert'

package/dist/runtime/components/BarcodeReader.vue

@@ -1,4 +1,8 @@
 <script lang="ts" setup>
+/**
+ * BarcodeReader starts and stops barcode scans, then emits parsed scan results back to parent workflows.
+ * This doc block is consumed by vue-docgen for generated API documentation.
+ */
 import {BrowserMultiFormatReader} from '@zxing/browser'
 import {type IScannerControls} from '@zxing/browser/esm'
 import type {Exception, Result} from '@zxing/library'
@@ -12,6 +16,10 @@ const barcodeReaderControl = ref()
 const alert = useAlert()
 const isLoading = ref<boolean>(false)
 
+/**
+ * Custom events emitted by BarcodeReader.
+ * Parents can listen to these events to react to user actions and internal state changes.
+ */
 const emit = defineEmits<{
   (event: 'decode', barcodeValue: string): void
   (event: 'error', error: string | unknown): void

package/dist/runtime/components/ExportCSV.vue

@@ -1,17 +1,25 @@
 <script lang="ts" setup>
+/**
+ * ExportCSV exports array data to spreadsheet files, flattening nested fields before file generation.
+ * This doc block is consumed by vue-docgen for generated API documentation.
+ */
 import { ref } from 'vue'
 import * as XLSX from 'xlsx'
 import { VBtn } from 'vuetify/components/VBtn'
 import { useAlert } from '../composables/alert'
 
 interface ExportButtonProps extends /* @vue-ignore */ InstanceType<typeof VBtn['$props']> {
-  fileName?: string
-  sheetName?: string
-  modelValue?: object[]
-  stringFields?: Array<string>
-  tooltip?: string | Record<string,any> | undefined
+  fileName?: string // File name used when downloading or printing generated files.
+  sheetName?: string // Configuration option used by ExportCSV.
+  modelValue?: object[] // Bound value for v-model synchronization with the parent component.
+  stringFields?: Array<string> // Field paths that must stay as string values (no nested object conversion).
+  tooltip?: string | Record<string,any> | undefined // Tooltip text or config object shown for the action control.
 }
 
+/**
+ * Public props accepted by ExportCSV.
+ * Document each prop field with intent, defaults, and side effects for clear generated docs.
+ */
 const props = withDefaults(defineProps<ExportButtonProps>(), {
   fileName: 'download',
   sheetName: 'Sheet1',

package/dist/runtime/components/FileBtn.vue

@@ -1,21 +1,33 @@
 <script lang="ts" setup>
+/**
+ * FileBtn wraps file selection behavior into a reusable button interface that works with form and upload flows.
+ * This doc block is consumed by vue-docgen for generated API documentation.
+ */
 import {ref} from 'vue'
 import {VBtn} from 'vuetify/components/VBtn'
 
 interface Props extends /* @vue-ignore */ InstanceType<typeof VBtn['$props']> {
-  accept?: string
-  multiple?: boolean
-  iconOnly?: boolean
-  modelValue?: File | File[] | undefined
-  tooltip?: string | Record<string,any> | undefined
+  accept?: string // Accepted file MIME types or extensions for file selection.
+  multiple?: boolean // Allows selecting or uploading more than one file.
+  iconOnly?: boolean // icon name/class used in UI rendering
+  modelValue?: File | File[] | undefined // Bound value for v-model synchronization with the parent component.
+  tooltip?: string | Record<string,any> | undefined // Tooltip text or config object shown for the action control.
 }
 
+/**
+ * Public props accepted by FileBtn.
+ * Document each prop field with intent, defaults, and side effects for clear generated docs.
+ */
 const props = withDefaults(defineProps<Props>(), {
   multiple: false,
   accept: '*',
   tooltip: 'Upload File',
 })
 
+/**
+ * Custom events emitted by FileBtn.
+ * Parents can listen to these events to react to user actions and internal state changes.
+ */
 const emit = defineEmits<{
   (event: 'update:modelValue', value: File | File[] | undefined): void
 }>()

package/dist/runtime/components/ImportCSV.vue

@@ -1,20 +1,32 @@
 <script lang="ts" setup>
+/**
+ * ImportCSV imports spreadsheet rows, maps nested object keys, and emits normalized records for downstream processing.
+ * This doc block is consumed by vue-docgen for generated API documentation.
+ */
 import * as XLSX from 'xlsx'
 import { ref } from 'vue'
 import { useAlert } from '../composables/alert'
 import { VBtn } from 'vuetify/components/VBtn'
 
 interface ImportButtonProps extends /* @vue-ignore */ InstanceType<typeof VBtn['$props']> {
-  stringFields?: Array<string>
-  tooltip?: string | Record<string,any> | undefined
+  stringFields?: Array<string> // Field paths that must stay as string values (no nested object conversion).
+  tooltip?: string | Record<string,any> | undefined // Tooltip text or config object shown for the action control.
 }
 
+/**
+ * Public props accepted by ImportCSV.
+ * Document each prop field with intent, defaults, and side effects for clear generated docs.
+ */
 const props = withDefaults(defineProps<ImportButtonProps>(), {
   stringFields: ()=>[],
   tooltip: ()=>({text: 'Import', location: 'bottom'}),
 })
 
 const alert = useAlert()
+/**
+ * Custom events emitted by ImportCSV.
+ * Parents can listen to these events to react to user actions and internal state changes.
+ */
 const emit = defineEmits<{
   (e: 'import', value: object[]): void
 }>()

package/dist/runtime/components/MrzReader.vue

@@ -0,0 +1,168 @@
+<script lang="ts" setup>
+/**
+ * MrzReader captures passport/ID images from camera or upload, runs OCR + MRZ parsing,
+ * and emits normalized MRZ data once checksum validation passes.
+ */
+import { computed, onBeforeUnmount, onMounted, ref, watchEffect } from 'vue'
+import { useDevicesList, useUserMedia } from '@vueuse/core'
+import { useAlert } from '../composables/alert'
+import { useMrzReader, type MrzResult } from '../composables/useMrzReader'
+
+const mrzReaderControl = ref<number | null>(null)
+
+const alert = useAlert()
+const isLoading = ref(false)
+
+interface Props {
+  intervalMs?: number // Scan interval (ms) for periodic camera-frame OCR attempts.
+  scaleFactor?: number // Upscale factor applied before OCR to improve small-text readability.
+  useOpenCv?: boolean // Enables OpenCV-assisted region detection before OCR.
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  intervalMs: 900,
+  scaleFactor: 2,
+  useOpenCv: true,
+})
+
+const emit = defineEmits<{
+  (event: 'decode', value: MrzResult): void // Emitted when a valid MRZ payload is parsed.
+  (event: 'error', error: string | unknown): void // Emitted when camera/OCR/parsing fails.
+}>()
+
+const videoScreen = ref<HTMLVideoElement>()
+
+const currentCameraId = ref<ConstrainDOMString | undefined>()
+const { videoInputs: cameras } = useDevicesList({
+  requestPermissions: true,
+  constraints: { audio: false, video: true },
+  onUpdated() {
+    if (!cameras.value.find(camera => camera.deviceId === currentCameraId.value))
+      currentCameraId.value = cameras.value[0]?.deviceId
+  },
+})
+
+const hasCamera = computed(() => !!currentCameraId.value)
+
+const { stream, start: cameraStart, stop: cameraStop, enabled: cameraEnabled } = useUserMedia({
+  constraints: { video: { deviceId: currentCameraId.value } },
+})
+
+watchEffect(() => {
+  if (videoScreen.value)
+    videoScreen.value.srcObject = stream.value ?? null
+})
+
+const mrzReader = useMrzReader({
+  scaleFactor: props.scaleFactor,
+  useOpenCv: props.useOpenCv,
+  lang: 'ocrb',
+  langPath: '/tesseract/',
+})
+
+async function scanOnce() {
+  if (!videoScreen.value || !cameraEnabled.value) return
+
+  try {
+    const parsed = await mrzReader.decodeFromVideoElement(videoScreen.value)
+    if (parsed) {
+      emit('decode', parsed)
+      stopCamera()
+    }
+  }
+  catch (err) {
+    emit('error', err)
+  }
+}
+
+function startCamera() {
+  if (cameraEnabled.value) return
+
+  isLoading.value = true
+  cameraStart()
+    .then(() => {
+      if (mrzReaderControl.value) {
+        window.clearInterval(mrzReaderControl.value)
+        mrzReaderControl.value = null
+      }
+
+      mrzReaderControl.value = window.setInterval(() => {
+        void scanOnce()
+      }, props.intervalMs)
+    })
+    .catch((err) => {
+      emit('error', err)
+    })
+    .finally(() => {
+      isLoading.value = false
+    })
+}
+
+function stopCamera() {
+  if (mrzReaderControl.value) {
+    window.clearInterval(mrzReaderControl.value)
+    mrzReaderControl.value = null
+  }
+  if (cameraEnabled.value)
+    cameraStop()
+}
+
+function scanImageFile(selectedFile: File | File[] | undefined) {
+  if (!selectedFile) {
+    alert?.addAlert({ message: 'No file selected.', alertType: 'error' })
+    return
+  }
+
+  const file = Array.isArray(selectedFile) ? selectedFile[0] : selectedFile
+
+  void mrzReader.decodeFromImageFile(file)
+    .then((parsed) => {
+      if (parsed)
+        emit('decode', parsed)
+      else
+        alert?.addAlert({ message: 'MRZ not found or checksum invalid.', alertType: 'warning' })
+    })
+    .catch((err) => {
+      emit('error', err)
+    })
+}
+
+onMounted(() => {
+  void mrzReader.ensureOpenCvReady()
+  startCamera()
+})
+
+onBeforeUnmount(() => {
+  stopCamera()
+})
+</script>
+
+<template>
+  <v-card flat>
+    <v-card-text class="d-flex justify-center" v-if="isLoading">
+      <v-progress-circular indeterminate />
+    </v-card-text>
+    <v-card-text v-else>
+      <v-col v-if="hasCamera">
+        <div style="position: relative; display: inline-block; width: 100%;" :style="{ maxWidth: '1024px' }">
+          <video autoplay ref="videoScreen" width="100%" :style="{ maxWidth: '1024px' }"></video>
+          <div style="position: absolute; bottom: 10px; right: 10px; z-index: 2000;">
+            <FileBtn
+              accept="image/*"
+              icon="mdi mdi-image-plus"
+              icon-only
+              @update:model-value="scanImageFile"
+            />
+          </div>
+        </div>
+      </v-col>
+      <v-col v-else>
+        <FileBtn
+          accept="image/*"
+          text="Upload Image"
+          @update:model-value="scanImageFile"
+        />
+      </v-col>
+    </v-card-text>
+  </v-card>
+</template>

package/dist/runtime/components/SplitterPanel.vue

@@ -1,4 +1,8 @@
 <script setup lang="ts">
+/**
+ * SplitterPanel provides a resizable split layout panel for flexible, user-adjustable page composition.
+ * This doc block is consumed by vue-docgen for generated API documentation.
+ */
 import { ref } from 'vue'
 import { VCard } from 'vuetify/components/VCard'
 
@@ -6,8 +10,12 @@ const isResizing = ref(false)
 const pane1Width = ref('50%')
 const containerRef = ref<HTMLElement>()
 interface Props extends /* @vue-ignore */ InstanceType<typeof VCard['$props']> {
-  height?: number | string
+  height?: number | string // Fixed or minimum height applied to the component container.
 }
+/**
+ * Public props accepted by SplitterPanel.
+ * Document each prop field with intent, defaults, and side effects for clear generated docs.
+ */
 const props = defineProps<Props>()
 
 const startResize = () => {

package/dist/runtime/components/TabsGroup.vue

@@ -1,14 +1,22 @@
 <script lang="ts" setup>
+/**
+ * TabsGroup renders grouped tab content and keeps tab state consistent across controlled and uncontrolled usage.
+ * This doc block is consumed by vue-docgen for generated API documentation.
+ */
 import {VTabs} from 'vuetify/components'
 
 interface Props extends /* @vue-ignore */ InstanceType<typeof VTabs['$props']> {
-  flat?: boolean
+  flat?: boolean // Uses a flatter tab style with reduced elevation and borders.
 }
 
 defineOptions({
   inheritAttrs: false,
 })
 
+/**
+ * Public props accepted by TabsGroup.
+ * Document each prop field with intent, defaults, and side effects for clear generated docs.
+ */
 const props = defineProps<Props>()
 const currentTab = defineModel<string|number>()
 </script>

package/dist/runtime/components/TextBarcode.vue

@@ -1,12 +1,24 @@
 <script lang="ts" setup>
+/**
+ * TextBarcode renders barcode output from plain text and updates when bound values change.
+ * This doc block is consumed by vue-docgen for generated API documentation.
+ */
 import {ref, watch} from 'vue'
 import {useAlert} from '../composables/alert'
 
 interface Props {
-  modelValue?: string
+  modelValue?: string // Bound value for v-model synchronization with the parent component.
 }
 
+/**
+ * Public props accepted by TextBarcode.
+ * Document each prop field with intent, defaults, and side effects for clear generated docs.
+ */
 const props = defineProps<Props>()
+/**
+ * Custom events emitted by TextBarcode.
+ * Parents can listen to these events to react to user actions and internal state changes.
+ */
 const emit = defineEmits<{
   (event: 'update:modelValue', value: string | undefined): void
   (event: 'decode', value: string | undefined): void

package/dist/runtime/components/device/IdCardButton.vue

@@ -1,4 +1,8 @@
 <script setup lang="ts">
+/**
+ * DeviceIdCardButton bridges UI actions with host-agent hardware/device operations and emits runtime scan/read results.
+ * This doc block is consumed by vue-docgen for generated API documentation.
+ */
 import { computed, ref, useAttrs } from 'vue'
 import { VBtn } from 'vuetify/components/VBtn'
 import { useAlert } from '../../composables/alert'
@@ -6,19 +10,27 @@ import { useHostAgent, type PatientRegisterPayload } from '../../composables/hos
 
 interface Props extends /* @vue-ignore */ InstanceType<typeof VBtn['$props']> {
   /** If true -> call /idcard/infoAndPhoto, else /idcard/info */
-  withPhoto?: boolean
+  withPhoto?: boolean // Includes portrait/photo data in ID card read results.
   /** Optional reader name/query string */
-  reader?: string | null
+  reader?: string | null // Preferred hardware reader identifier to connect or switch to.
   /** Auto-disable button while reading */
-  disableWhileLoading?: boolean
+  disableWhileLoading?: boolean // Disables the trigger button while a read operation is in progress.
 }
 
+/**
+ * Public props accepted by DeviceIdCardButton.
+ * Document each prop field with intent, defaults, and side effects for clear generated docs.
+ */
 const props = withDefaults(defineProps<Props>(), {
   withPhoto: false,
   reader: null,
   disableWhileLoading: true,
 })
 
+/**
+ * Custom events emitted by DeviceIdCardButton.
+ * Parents can listen to these events to react to user actions and internal state changes.
+ */
 const emit = defineEmits<{
   (e: 'read', payload: PatientRegisterPayload): void
   (e: 'error', err: unknown): void

package/dist/runtime/components/device/IdCardWebSocket.vue

@@ -1,23 +1,31 @@
 <script setup lang="ts">
+/**
+ * DeviceIdCardWebSocket bridges UI actions with host-agent hardware/device operations and emits runtime scan/read results.
+ * This doc block is consumed by vue-docgen for generated API documentation.
+ */
 import { onBeforeUnmount, onMounted, ref, watch } from 'vue'
 import { type IdCardWsServerMessage, type PatientRegisterPayload } from '../../composables/hostAgent'
 import { useHostAgentWs } from "../../composables/hostAgentWs";
 
 interface Props {
   /** Subscribe withPhoto=true => server will push payload that includes photo when available */
-  withPhoto?: boolean
+  withPhoto?: boolean // Includes portrait/photo data in ID card read results.
   /** Optional reader name; null/undefined means "any/default" */
-  reader?: string | null
+  reader?: string | null // Preferred hardware reader identifier to connect or switch to.
   /** Auto-connect on mount (default true) */
-  autoConnect?: boolean
+  autoConnect?: boolean // Connects to the device WebSocket automatically on mount.
   /** Auto-subscribe after connect (default true) */
-  autoSubscribe?: boolean
+  autoSubscribe?: boolean // Subscribes to live reader events automatically after connect.
   /** If true, try to reconnect when socket closes unexpectedly */
-  autoReconnect?: boolean
+  autoReconnect?: boolean // Retries connection automatically when the socket closes unexpectedly.
   /** Reconnect delay in ms */
-  reconnectDelayMs?: number
+  reconnectDelayMs?: number // Delay in milliseconds before each reconnect attempt.
 }
 
+/**
+ * Public props accepted by DeviceIdCardWebSocket.
+ * Document each prop field with intent, defaults, and side effects for clear generated docs.
+ */
 const props = withDefaults(defineProps<Props>(), {
   withPhoto: false,
   reader: null,
@@ -27,6 +35,10 @@ const props = withDefaults(defineProps<Props>(), {
   reconnectDelayMs: 1000,
 })
 
+/**
+ * Custom events emitted by DeviceIdCardWebSocket.
+ * Parents can listen to these events to react to user actions and internal state changes.
+ */
 const emit = defineEmits<{
   (e: 'connected'): void
   (e: 'disconnected', info?: { code?: number; reason?: string }): void