@ramathibodi/nuxt-commons 0.1.73 → 0.1.75

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

@@ -1,83 +1,95 @@
-<script setup lang="ts">
-import { computed, ref, useAttrs } from 'vue'
-import { VBtn } from 'vuetify/components/VBtn'
-import { useAlert } from '../../composables/alert'
-import { useHostAgent, type PatientRegisterPayload } from '../../composables/hostAgent'
-
-interface Props extends /* @vue-ignore */ InstanceType<typeof VBtn['$props']> {
-  /** If true -> call /idcard/infoAndPhoto, else /idcard/info */
-  withPhoto?: boolean
-  /** Optional reader name/query string */
-  reader?: string | null
-  /** Auto-disable button while reading */
-  disableWhileLoading?: boolean
-}
-
-const props = withDefaults(defineProps<Props>(), {
-  withPhoto: false,
-  reader: null,
-  disableWhileLoading: true,
-})
-
-const emit = defineEmits<{
-  (e: 'read', payload: PatientRegisterPayload): void
-  (e: 'error', err: unknown): void
-  (e: 'loading', loading: boolean): void
-}>()
-
-const attrs = useAttrs()
-const host = useHostAgent()
-
-const loading = ref(false)
-const disabled = computed(() => (props.disableWhileLoading ? loading.value : false))
-
-async function onClick(ev: MouseEvent) {
-  // allow parent to prevent if they attach their own click handler and call preventDefault
-  if (ev.defaultPrevented) return
-
-  try {
-    loading.value = true
-    emit('loading', true)
-
-    const payload = props.withPhoto
-        ? await host.getIdCardInfoAndPhoto(props.reader ?? undefined)
-        : await host.getIdCardInfo(props.reader ?? undefined)
-
-    emit('read', payload)
-  } catch (e: any) {
-    emit('error', e)
-
-    const msg = e?.data?.detail || e?.data?.title || e?.message || 'ID card read failed'
-    useAlert()?.addAlert({ message: msg, alertType: 'error' })
-  } finally {
-    loading.value = false
-    emit('loading', false)
-  }
-}
-</script>
-
-<template>
-  <!--
-    Extends Vuetify VBtn:
-    - All unknown attrs (size, class, etc.) pass through via v-bind="attrs"
-    - You can override content via default slot; label+icon is fallback
-  -->
-  <v-btn
-      v-bind="attrs"
-      class="idcard-btn"
-      :loading="loading"
-      :disabled="disabled || (attrs as any).disabled"
-      @click="onClick"
-  >
-    <template
-        v-for="(_, name, index) in ($slots as {})"
-        :key="index"
-        #[name]="slotData"
-    >
-      <slot
-          :name="name"
-          v-bind="((slotData || {}) as object)"
-      />
-    </template>
-  </v-btn>
-</template>
+<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'
+import { useHostAgent, type PatientRegisterPayload } from '../../composables/hostAgent'
+
+interface Props extends /* @vue-ignore */ InstanceType<typeof VBtn['$props']> {
+  /** If true -> call /idcard/infoAndPhoto, else /idcard/info */
+  withPhoto?: boolean // Includes portrait/photo data in ID card read results.
+  /** Optional reader name/query string */
+  reader?: string | null // Preferred hardware reader identifier to connect or switch to.
+  /** Auto-disable button while reading */
+  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
+  (e: 'loading', loading: boolean): void
+}>()
+
+const attrs = useAttrs()
+const host = useHostAgent()
+
+const loading = ref(false)
+const disabled = computed(() => (props.disableWhileLoading ? loading.value : false))
+
+async function onClick(ev: MouseEvent) {
+  // allow parent to prevent if they attach their own click handler and call preventDefault
+  if (ev.defaultPrevented) return
+
+  try {
+    loading.value = true
+    emit('loading', true)
+
+    const payload = props.withPhoto
+        ? await host.getIdCardInfoAndPhoto(props.reader ?? undefined)
+        : await host.getIdCardInfo(props.reader ?? undefined)
+
+    emit('read', payload)
+  } catch (e: any) {
+    emit('error', e)
+
+    const msg = e?.data?.detail || e?.data?.title || e?.message || 'ID card read failed'
+    useAlert()?.addAlert({ message: msg, alertType: 'error' })
+  } finally {
+    loading.value = false
+    emit('loading', false)
+  }
+}
+</script>
+
+<template>
+  <!--
+    Extends Vuetify VBtn:
+    - All unknown attrs (size, class, etc.) pass through via v-bind="attrs"
+    - You can override content via default slot; label+icon is fallback
+  -->
+  <v-btn
+      v-bind="attrs"
+      class="idcard-btn"
+      :loading="loading"
+      :disabled="disabled || (attrs as any).disabled"
+      @click="onClick"
+  >
+    <template
+        v-for="(_, name, index) in ($slots as {})"
+        :key="index"
+        #[name]="slotData"
+    >
+      <slot
+          :name="name"
+          v-bind="((slotData || {}) as object)"
+      />
+    </template>
+  </v-btn>
+</template>

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

@@ -1,195 +1,207 @@
-<script setup lang="ts">
-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
-  /** Optional reader name; null/undefined means "any/default" */
-  reader?: string | null
-  /** Auto-connect on mount (default true) */
-  autoConnect?: boolean
-  /** Auto-subscribe after connect (default true) */
-  autoSubscribe?: boolean
-  /** If true, try to reconnect when socket closes unexpectedly */
-  autoReconnect?: boolean
-  /** Reconnect delay in ms */
-  reconnectDelayMs?: number
-}
-
-const props = withDefaults(defineProps<Props>(), {
-  withPhoto: false,
-  reader: null,
-  autoConnect: true,
-  autoSubscribe: true,
-  autoReconnect: false,
-  reconnectDelayMs: 1000,
-})
-
-const emit = defineEmits<{
-  (e: 'connected'): void
-  (e: 'disconnected', info?: { code?: number; reason?: string }): void
-  (e: 'subscribed', info?: { reader?: string | null; withPhoto?: boolean }): void
-  (e: 'unsubscribed'): void
-  (e: 'inserted', payload: PatientRegisterPayload): void
-  (e: 'removed'): void
-  (e: 'error', err: unknown): void
-  (e: 'message', msg: IdCardWsServerMessage): void
-}>()
-
-const host = useHostAgentWs()
-
-const reconnectTimer = ref<ReturnType<typeof setTimeout> | null>(null)
-const mounted = ref(false)
-const manuallyDisconnected = ref(false)
-
-function clearReconnect() {
-  if (reconnectTimer.value) {
-    clearTimeout(reconnectTimer.value)
-    reconnectTimer.value = null
-  }
-}
-
-function connectAndSubscribe() {
-  manuallyDisconnected.value = false
-  host.connectIdCardWs()
-
-  // subscribe immediately; safe because connectIdCardWs sets handlers then WS opens soon
-  // but we must wait until OPEN to send; so we subscribe on "open" event in handler below.
-}
-
-function safeDisconnect() {
-  manuallyDisconnected.value = true
-  clearReconnect()
-  try {
-    // best-effort unsubscribe (only if connected)
-    if (host.wsConnected.value) {
-      try { host.unsubscribeIdCardWs() } catch { /* ignore */ }
-    }
-  } catch { /* ignore */ }
-  host.disconnectIdCardWs()
-}
-
-const off = host.onIdCardWsEvent((ev) => {
-  if (ev.type === 'open') {
-    emit('connected')
-
-    if (props.autoSubscribe) {
-      try {
-        host.subscribeIdCardWs({ reader: props.reader ?? null, withPhoto: props.withPhoto })
-      } catch (e) {
-        emit('error', e)
-      }
-    }
-    return
-  }
-
-  if (ev.type === 'close') {
-    emit('disconnected', { code: ev.code, reason: ev.reason })
-
-    if (props.autoReconnect && mounted.value && !manuallyDisconnected.value) {
-      clearReconnect()
-      reconnectTimer.value = setTimeout(() => {
-        try {
-          connectAndSubscribe()
-        } catch (e) {
-          emit('error', e)
-        }
-      }, props.reconnectDelayMs)
-    }
-    return
-  }
-
-  if (ev.type === 'error') {
-    emit('error', ev.error)
-    return
-  }
-
-  if (ev.type === 'message') {
-    const msg = ev.data
-    emit('message', msg)
-
-    switch (msg.type) {
-      case 'monitor.subscribed':
-        if (msg.ok) emit('subscribed', { reader: msg.reader ?? null, withPhoto: !!msg.withPhoto })
-        break
-      case 'monitor.unsubscribed':
-        emit('unsubscribed')
-        break
-      case 'card.inserted':
-        emit('inserted', msg.payload)
-        break
-      case 'card.removed':
-        emit('removed')
-        break
-      case 'card.error':
-      case 'error':
-        emit('error', msg)
-        break
-    }
-  }
-})
-
-onMounted(() => {
-  mounted.value = true
-  if (props.autoConnect) connectAndSubscribe()
-})
-
-onBeforeUnmount(() => {
-  mounted.value = false
-  try { off?.() } catch { /* ignore */ }
-  safeDisconnect()
-})
-
-/**
- * If props change while connected, switch subscription behavior.
- * - withPhoto changes => re-subscribe (server treats subscribe twice as error), so do unsubscribe -> subscribe
- * - reader changes => use switchReader action when possible; if not connected, just store for next subscribe
- */
-watch(
-    () => props.reader,
-    (r) => {
-      if (!mounted.value) return
-      if (!host.wsConnected.value) return
-      if (!host.wsSubscribed.value) return
-
-      try {
-        host.switchReaderIdCardWs(r ?? null)
-      } catch (e) {
-        emit('error', e)
-      }
-    }
-)
-
-watch(
-    () => props.withPhoto,
-    (withPhoto) => {
-      if (!mounted.value) return
-      if (!host.wsConnected.value) return
-
-      // Server disallows re-subscribe without unsubscribe first.
-      // We do a clean unsubscribe -> resubscribe sequence.
-      try {
-        if (host.wsSubscribed.value) {
-          host.unsubscribeIdCardWs()
-        }
-      } catch { /* ignore */ }
-
-      // resubscribe after a tick; give server a moment to process unsubscribe
-      setTimeout(() => {
-        try {
-          if (host.wsConnected.value) {
-            host.subscribeIdCardWs({ reader: props.reader ?? null, withPhoto })
-          }
-        } catch (e) {
-          emit('error', e)
-        }
-      }, 0)
-    }
-)
-</script>
-
-<template>
-  <!-- Intentionally blank (headless component) -->
-</template>
+<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 // Includes portrait/photo data in ID card read results.
+  /** Optional reader name; null/undefined means "any/default" */
+  reader?: string | null // Preferred hardware reader identifier to connect or switch to.
+  /** Auto-connect on mount (default true) */
+  autoConnect?: boolean // Connects to the device WebSocket automatically on mount.
+  /** Auto-subscribe after connect (default true) */
+  autoSubscribe?: boolean // Subscribes to live reader events automatically after connect.
+  /** If true, try to reconnect when socket closes unexpectedly */
+  autoReconnect?: boolean // Retries connection automatically when the socket closes unexpectedly.
+  /** Reconnect delay in ms */
+  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,
+  autoConnect: true,
+  autoSubscribe: true,
+  autoReconnect: false,
+  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
+  (e: 'subscribed', info?: { reader?: string | null; withPhoto?: boolean }): void
+  (e: 'unsubscribed'): void
+  (e: 'inserted', payload: PatientRegisterPayload): void
+  (e: 'removed'): void
+  (e: 'error', err: unknown): void
+  (e: 'message', msg: IdCardWsServerMessage): void
+}>()
+
+const host = useHostAgentWs()
+
+const reconnectTimer = ref<ReturnType<typeof setTimeout> | null>(null)
+const mounted = ref(false)
+const manuallyDisconnected = ref(false)
+
+function clearReconnect() {
+  if (reconnectTimer.value) {
+    clearTimeout(reconnectTimer.value)
+    reconnectTimer.value = null
+  }
+}
+
+function connectAndSubscribe() {
+  manuallyDisconnected.value = false
+  host.connectIdCardWs()
+
+  // subscribe immediately; safe because connectIdCardWs sets handlers then WS opens soon
+  // but we must wait until OPEN to send; so we subscribe on "open" event in handler below.
+}
+
+function safeDisconnect() {
+  manuallyDisconnected.value = true
+  clearReconnect()
+  try {
+    // best-effort unsubscribe (only if connected)
+    if (host.wsConnected.value) {
+      try { host.unsubscribeIdCardWs() } catch { /* ignore */ }
+    }
+  } catch { /* ignore */ }
+  host.disconnectIdCardWs()
+}
+
+const off = host.onIdCardWsEvent((ev) => {
+  if (ev.type === 'open') {
+    emit('connected')
+
+    if (props.autoSubscribe) {
+      try {
+        host.subscribeIdCardWs({ reader: props.reader ?? null, withPhoto: props.withPhoto })
+      } catch (e) {
+        emit('error', e)
+      }
+    }
+    return
+  }
+
+  if (ev.type === 'close') {
+    emit('disconnected', { code: ev.code, reason: ev.reason })
+
+    if (props.autoReconnect && mounted.value && !manuallyDisconnected.value) {
+      clearReconnect()
+      reconnectTimer.value = setTimeout(() => {
+        try {
+          connectAndSubscribe()
+        } catch (e) {
+          emit('error', e)
+        }
+      }, props.reconnectDelayMs)
+    }
+    return
+  }
+
+  if (ev.type === 'error') {
+    emit('error', ev.error)
+    return
+  }
+
+  if (ev.type === 'message') {
+    const msg = ev.data
+    emit('message', msg)
+
+    switch (msg.type) {
+      case 'monitor.subscribed':
+        if (msg.ok) emit('subscribed', { reader: msg.reader ?? null, withPhoto: !!msg.withPhoto })
+        break
+      case 'monitor.unsubscribed':
+        emit('unsubscribed')
+        break
+      case 'card.inserted':
+        emit('inserted', msg.payload)
+        break
+      case 'card.removed':
+        emit('removed')
+        break
+      case 'card.error':
+      case 'error':
+        emit('error', msg)
+        break
+    }
+  }
+})
+
+onMounted(() => {
+  mounted.value = true
+  if (props.autoConnect) connectAndSubscribe()
+})
+
+onBeforeUnmount(() => {
+  mounted.value = false
+  try { off?.() } catch { /* ignore */ }
+  safeDisconnect()
+})
+
+/**
+ * If props change while connected, switch subscription behavior.
+ * - withPhoto changes => re-subscribe (server treats subscribe twice as error), so do unsubscribe -> subscribe
+ * - reader changes => use switchReader action when possible; if not connected, just store for next subscribe
+ */
+watch(
+    () => props.reader,
+    (r) => {
+      if (!mounted.value) return
+      if (!host.wsConnected.value) return
+      if (!host.wsSubscribed.value) return
+
+      try {
+        host.switchReaderIdCardWs(r ?? null)
+      } catch (e) {
+        emit('error', e)
+      }
+    }
+)
+
+watch(
+    () => props.withPhoto,
+    (withPhoto) => {
+      if (!mounted.value) return
+      if (!host.wsConnected.value) return
+
+      // Server disallows re-subscribe without unsubscribe first.
+      // We do a clean unsubscribe -> resubscribe sequence.
+      try {
+        if (host.wsSubscribed.value) {
+          host.unsubscribeIdCardWs()
+        }
+      } catch { /* ignore */ }
+
+      // resubscribe after a tick; give server a moment to process unsubscribe
+      setTimeout(() => {
+        try {
+          if (host.wsConnected.value) {
+            host.subscribeIdCardWs({ reader: props.reader ?? null, withPhoto })
+          }
+        } catch (e) {
+          emit('error', e)
+        }
+      }, 0)
+    }
+)
+</script>
+
+<template>
+  <!-- Intentionally blank (headless component) -->
+</template>