@ramathibodi/nuxt-commons 0.1.73 → 0.1.75

package/README.md

@@ -1,96 +1,115 @@
-<!--
-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]
-
-
-## Quick Setup
-
-1. Add `'@ramathibodi/nuxt-commons'` dependency to your project
-
-```bash
-# Using pnpm
-pnpm add -D @ramathibodi/nuxt-commons
-
-# Using yarn
-yarn add --dev @ramathibodi/nuxt-commons
-
-# Using npm
-npm install --save-dev @ramathibodi/nuxt-commons
-```
-
-2. Add `my-module` to the `modules` section of `nuxt.config.ts`
-
-```js
-export default defineNuxtConfig({
-  modules: [
-    '@ramathibodi/nuxt-commons'
-  ]
-})
-```
-
-That's it! You can now use My Module in your Nuxt app ✨
-
-## Development
-
-```bash
-# Install dependencies
-npm install
-
-# Generate type stubs
-npm run dev:prepare
-
-# Develop with the playground
-npm run dev
-
-# Build the playground
-npm run dev:build
-
-# Run ESLint
-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
-
-## 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. เสร็จสิ้น
-```
-
-<!-- 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
-
-[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
-
-[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
-
-[nuxt-src]: https://img.shields.io/badge/Nuxt-18181B?logo=nuxt.js
-[nuxt-href]: https://nuxt.com
+# @ramathibodi/nuxt-commons
+
+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
+
+## Install
+
+```bash
+# pnpm
+pnpm add -D @ramathibodi/nuxt-commons
+
+# yarn
+yarn add --dev @ramathibodi/nuxt-commons
+
+# npm
+npm install --save-dev @ramathibodi/nuxt-commons
+```
+
+## Nuxt Setup
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ['@ramathibodi/nuxt-commons'],
+})
+```
+
+## 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
+
+```bash
+# Install dependencies
+npm install
+
+# Prepare stubs/types
+npm run dev:prepare
+
+# Run playground
+npm run dev
+
+# Build playground
+npm run dev:build
+
+# Lint and test
+npm run lint
+npm run test
+```
+
+## Documentation
+
+Generate documentation artifacts from source:
+
+```bash
+# 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
+```
+
+`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`.
+
+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
+
+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)
+
+`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.73",
+  "version": "0.1.75",
   "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,54 +1,58 @@
-<script lang="ts" setup>
-import { ref, watch } from 'vue'
-import { isEmpty } from 'lodash-es'
-import { useAlert } from '../composables/alert'
-import type { AlertItem } from '../types/alert'
-
-const isAlertOpen = ref(false)
-const timeout = ref(3000)
-const alert = useAlert()
-const currentItem = ref<AlertItem | undefined>()
-
-const renewAlert = () => {
-  if (alert?.hasAlert()) {
-    currentItem.value = alert?.takeAlert()
-    isAlertOpen.value = true
-  }
-  else {
-    currentItem.value = undefined
-    isAlertOpen.value = false
-  }
-}
-
-watch(() => alert?.hasAlert(), (hasAlert) => {
-  if (hasAlert) {
-    renewAlert()
-  }
-})
-</script>
-
-<template>
-  <VSnackbar
-    v-if="currentItem"
-    v-model="isAlertOpen"
-    :timeout="timeout"
-    location="center"
-    multi-line
-    variant="text"
-    @update:model-value="renewAlert()"
-  >
-    <!-- @vue-expected-error Type conversion problem -->
-    <VAlert
-      v-model="isAlertOpen"
-      closable
-      :type="currentItem.alertType"
-      elevation="2"
-      theme="dark"
-      variant="flat"
-      v-bind="currentItem.alertIcon ? { icon: currentItem.alertIcon } : {}"
-      @click:close="renewAlert()"
-    >
-      {{ currentItem.statusCode ? currentItem.statusCode + ' ' : '' }} {{ currentItem.message }} {{ !isEmpty(currentItem.data) ? currentItem.data : '' }}
-    </VAlert>
-  </VSnackbar>
-</template>
+<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'
+import type { AlertItem } from '../types/alert'
+
+const isAlertOpen = ref(false)
+const timeout = ref(3000)
+const alert = useAlert()
+const currentItem = ref<AlertItem | undefined>()
+
+const renewAlert = () => {
+  if (alert?.hasAlert()) {
+    currentItem.value = alert?.takeAlert()
+    isAlertOpen.value = true
+  }
+  else {
+    currentItem.value = undefined
+    isAlertOpen.value = false
+  }
+}
+
+watch(() => alert?.hasAlert(), (hasAlert) => {
+  if (hasAlert) {
+    renewAlert()
+  }
+})
+</script>
+
+<template>
+  <VSnackbar
+    v-if="currentItem"
+    v-model="isAlertOpen"
+    :timeout="timeout"
+    location="center"
+    multi-line
+    variant="text"
+    @update:model-value="renewAlert()"
+  >
+    <!-- @vue-expected-error Type conversion problem -->
+    <VAlert
+      v-model="isAlertOpen"
+      closable
+      :type="currentItem.alertType"
+      elevation="2"
+      theme="dark"
+      variant="flat"
+      v-bind="currentItem.alertIcon ? { icon: currentItem.alertIcon } : {}"
+      @click:close="renewAlert()"
+    >
+      {{ currentItem.statusCode ? currentItem.statusCode + ' ' : '' }} {{ currentItem.message }} {{ !isEmpty(currentItem.data) ? currentItem.data : '' }}
+    </VAlert>
+  </VSnackbar>
+</template>

package/dist/runtime/components/BarcodeReader.vue

@@ -1,122 +1,130 @@
-<script lang="ts" setup>
-import {BrowserMultiFormatReader} from '@zxing/browser'
-import {type IScannerControls} from '@zxing/browser/esm'
-import type {Exception, Result} from '@zxing/library'
-import {computed, onBeforeUnmount, onMounted, ref, watchEffect} from 'vue'
-import {useAlert} from '../composables/alert'
-import {useDevicesList, useUserMedia} from "@vueuse/core";
-
-const barcodeReader = new BrowserMultiFormatReader()
-const barcodeReaderControl = ref()
-
-const alert = useAlert()
-const isLoading = ref<boolean>(false)
-
-const emit = defineEmits<{
-  (event: 'decode', barcodeValue: string): void
-  (event: 'error', error: string | unknown): void
-}>()
-
-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(()=>{ return  !!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) ? stream.value! : null
-})
-
-function startCamera() {
-  if (!cameraEnabled.value) {
-    isLoading.value = true
-    cameraStart().then(()=>{
-      barcodeReader.decodeFromVideoDevice(currentCameraId.value, videoScreen.value, (result: Result | undefined, error: Exception | undefined, controls: IScannerControls) => {
-        if (result) {
-          emit('decode', result.getText())
-          cameraStop()
-        }
-      }).then((result: any)=>{
-        barcodeReaderControl.value = result
-      })
-    }).finally(()=>{
-      isLoading.value = false
-    })
-  }
-}
-
-function stopCamera() {
-  if (barcodeReaderControl.value) barcodeReaderControl.value.stop()
-  if (cameraEnabled.value) cameraStop()
-}
-
-function scanImageFile(selectedFile: File | File[] | undefined) {
-  if (!selectedFile) {
-    alert?.addAlert({ message: 'No file selected.', alertType: 'error' })
-    return
-  }
-
-  const scanImageSingleFile: File = Array.isArray(selectedFile) ? selectedFile[0] : selectedFile
-
-  const reader = new FileReader()
-  reader.onload = async (event) => {
-    try {
-      const result = await barcodeReader.decodeFromImageUrl(event.target?.result as string)
-      emit('decode', result.getText())
-    }
-    catch (e) {
-      void e
-    }
-  }
-  reader.readAsDataURL(scanImageSingleFile)
-}
-
-onMounted( () => {
-  startCamera()
-})
-
-onBeforeUnmount(  () => {
-  stopCamera()
-})
-</script>
-
-<template>
-  <v-card flat>
-    <v-card-text class="d-flex justify-center" v-if="isLoading">
-      <v-progress-circular indeterminate></v-progress-circular>
-    </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>
+<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'
+import {computed, onBeforeUnmount, onMounted, ref, watchEffect} from 'vue'
+import {useAlert} from '../composables/alert'
+import {useDevicesList, useUserMedia} from "@vueuse/core";
+
+const barcodeReader = new BrowserMultiFormatReader()
+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
+}>()
+
+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(()=>{ return  !!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) ? stream.value! : null
+})
+
+function startCamera() {
+  if (!cameraEnabled.value) {
+    isLoading.value = true
+    cameraStart().then(()=>{
+      barcodeReader.decodeFromVideoDevice(currentCameraId.value, videoScreen.value, (result: Result | undefined, error: Exception | undefined, controls: IScannerControls) => {
+        if (result) {
+          emit('decode', result.getText())
+          cameraStop()
+        }
+      }).then((result: any)=>{
+        barcodeReaderControl.value = result
+      })
+    }).finally(()=>{
+      isLoading.value = false
+    })
+  }
+}
+
+function stopCamera() {
+  if (barcodeReaderControl.value) barcodeReaderControl.value.stop()
+  if (cameraEnabled.value) cameraStop()
+}
+
+function scanImageFile(selectedFile: File | File[] | undefined) {
+  if (!selectedFile) {
+    alert?.addAlert({ message: 'No file selected.', alertType: 'error' })
+    return
+  }
+
+  const scanImageSingleFile: File = Array.isArray(selectedFile) ? selectedFile[0] : selectedFile
+
+  const reader = new FileReader()
+  reader.onload = async (event) => {
+    try {
+      const result = await barcodeReader.decodeFromImageUrl(event.target?.result as string)
+      emit('decode', result.getText())
+    }
+    catch (e) {
+      void e
+    }
+  }
+  reader.readAsDataURL(scanImageSingleFile)
+}
+
+onMounted( () => {
+  startCamera()
+})
+
+onBeforeUnmount(  () => {
+  stopCamera()
+})
+</script>
+
+<template>
+  <v-card flat>
+    <v-card-text class="d-flex justify-center" v-if="isLoading">
+      <v-progress-circular indeterminate></v-progress-circular>
+    </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>