From db5e5b55eb879ec5b350d5d93f2051dc73506d44 Mon Sep 17 00:00:00 2001
From: Debora Crescenzo <dcrescenzo@sipwise.com>
Date: Fri, 23 Jan 2026 13:57:39 +0000
Subject: [PATCH] MT#64292 Migrate App.Vue and vue-wait to Vue 3

Modernize vue-wait initialization and usage patterns to support Vue 3
Composition API while preserving Vue 2 Options API functionality.

Changes:
- Migrate App.vue to Vue 3 <script setup> syntax
  - Convert Options API to Composition API
  - Use defineComponent and reactive state management
  - Maintain existing functionality and lifecycle hooks

- Refactor vue-wait initialization (boot/vue-wait.js)
  - Move initialization from App.vue mounted() to boot phase
  - Create initializeWait() function for explicit setup
  - Register $wait globally before component mounting

- Add Vue 3 composable support (composables/useWait.js)
  - Create useWait() composable for Composition API components
  - Access $wait via getCurrentInstance() for proper Vue 3 patterns
  - Enable gradual migration from Options to Composition API

- Update documentation (doc/architectural-overview.md)
  - Add "Loading State Management (vue-wait)" section
  - Document usage patterns for both Vue 2 and Vue 3
  - Clarify migration strategy and coexistence

Note:
All existing Vue 2 components using this.$wait continue working unchanged
while new Vue 3 components can use useWait() composable.

Change-Id: I62c9eaa81336a1ae115f1b326676497dcac262b2
---
 doc/architectural-overview.md | 30 ++++++++++++++-
 src/App.vue                   | 69 +++++++++++++++--------------------
 src/boot/vue-wait.js          | 21 +++++++----
 src/composables/useWait.js    | 15 ++++++++
 4 files changed, 87 insertions(+), 48 deletions(-)
 create mode 100644 src/composables/useWait.js

diff --git a/doc/architectural-overview.md b/doc/architectural-overview.md
index 2e07affb..bf679aee 100644
--- a/doc/architectural-overview.md
+++ b/doc/architectural-overview.md
@@ -100,10 +100,38 @@ VoIP notes and constraints:
 Starting with Vue 3 migration, the application introduces composables (`src/composables/`) as an optional layer for accessing Vuex store in Composition API components:
 
 - **Purpose**: Provide reactive, encapsulated access to store state and actions
-- **Available composables**: `useStore.js` (generic), `useUser.js` (authentication), `usePbx.js` (PBX features), `useGlobals.js` (global properties)
+- **Available composables**: `useStore.js` (generic), `useUser.js` (authentication), `usePbx.js` (PBX features), `useGlobals.js` (global properties), `useWait.js` (loading states)
 - **Coexistence**: Options API components continue using `mapState`/`mapGetters`/`mapActions`; composables are used when converting to Composition API
 - **Details**: See `migration-guide.md` for usage patterns and `composables.md` for API reference
 
+## Loading State Management (vue-wait)
+
+The application uses `vue-wait-vue3` to manage loading states across the application:
+
+- **Initialization**: `vue-wait` is initialized during the Quasar boot phase in `src/boot/vue-wait.js`, making the `$wait` instance globally available before any components mount
+- **Integration**: Integrated with Vuex store (module name: `wait`) to provide reactive loading state management
+- **Vue 2 compatibility**: Existing components using Options API can access loading states via `this.$wait.start()`, `this.$wait.end()`, and `this.$wait.is()` without any changes
+
+```js
+export default {
+  mounted() {
+    this.$wait.start('loading')
+  }
+}
+```
+
+- **Vue 3 support**: New Composition API components can use the `useWait()` composable from `src/composables/useWait.js` to access the same functionality
+
+```js
+import { useWait } from 'src/composables/useWait'
+
+const wait = useWait()
+wait.start('loading')
+```
+
+- **Usage pattern**: Call `this.$wait.start('action-name')` before async operations, `this.$wait.end('action-name')` after completion, and check state with `this.$wait.is('action-name')` or `$wait.is('action-name')` in templates
+- **Migration note**: Both patterns work simultaneously, allowing gradual migration from Vue 2 to Vue 3 syntax without breaking existing functionality
+
 ## Store Infrastructure
 
 The Vuex store includes standardized helpers for request lifecycle management:
diff --git a/src/App.vue b/src/App.vue
index 9a02eaa2..9c94c48c 100644
--- a/src/App.vue
+++ b/src/App.vue
@@ -1,49 +1,40 @@
 <template>
     <router-view />
 </template>
-<script>
-import _ from 'lodash'
+
+<script setup>
+import { useMeta } from 'quasar'
 import { APP_NAME } from 'src/constants'
+import { ref, watch } from 'vue'
+import { useRoute } from 'vue-router'
 
-export default {
-    name: 'App',
-    meta () {
-        return {
-            title: this.pageTitle,
-            titleTemplate: (title) => `${APP_NAME} - ${title}`
-        }
-    },
-    data () {
-        return {
-            pageTitle: ''
-        }
-    },
-    watch: {
-        $route (route) {
-            this.updateTitle(route)
+const route = useRoute()
+const pageTitle = ref('')
+
+const updateTitle = (route) => {
+    if (route) {
+        const titleElements = []
+        const title = route.meta?.title || ''
+        const subTitle = route.meta?.subtitle || ''
+        if (title !== '') {
+            titleElements.push(title)
         }
-    },
-    async mounted () {
-        this.$initWait()
-        this.updateTitle(this.$route)
-    },
-    methods: {
-        updateTitle: function (route) {
-            if (route) {
-                const titleElements = []
-                const title = _.get(route, 'meta.title', '')
-                const subTitle = _.get(route, 'meta.subtitle', '')
-                if (title !== '') {
-                    titleElements.push(title)
-                }
-                if (subTitle !== '') {
-                    titleElements.push(subTitle)
-                }
-                this.pageTitle = titleElements.join(' - ') || route.name || ''
-            } else {
-                this.pageTitle = ''
-            }
+        if (subTitle !== '') {
+            titleElements.push(subTitle)
         }
+        pageTitle.value = titleElements.join(' - ') || route.name || ''
+    } else {
+        pageTitle.value = ''
     }
 }
+
+watch(route, (newRoute) => {
+    updateTitle(newRoute)
+}, { immediate: true })
+
+useMeta(() => ({
+    title: pageTitle.value,
+    titleTemplate: (title) => `${APP_NAME} - ${title}`
+}))
+
 </script>
diff --git a/src/boot/vue-wait.js b/src/boot/vue-wait.js
index 02717f3e..e969a7cf 100644
--- a/src/boot/vue-wait.js
+++ b/src/boot/vue-wait.js
@@ -1,12 +1,17 @@
 import { createVueWait } from 'vue-wait-vue3'
 
+export function initializeWait (app) {
+    const VueWait = createVueWait({
+        useVuex: true,
+        vuexModuleName: 'wait',
+        registerDirective: true
+    })
+    app.use(VueWait)
+
+    return VueWait
+}
+
 export default ({ app }) => {
-    app.config.globalProperties.$initWait = () => {
-        const VueWait = createVueWait({
-            useVuex: true,
-            vuexModuleName: 'wait',
-            registerDirective: true
-        })
-        app.use(VueWait)
-    }
+    // Initialize wait immediately during boot
+    initializeWait(app)
 }
diff --git a/src/composables/useWait.js b/src/composables/useWait.js
new file mode 100644
index 00000000..128fee1e
--- /dev/null
+++ b/src/composables/useWait.js
@@ -0,0 +1,15 @@
+import { getCurrentInstance } from 'vue'
+
+export function useWait () {
+    const instance = getCurrentInstance()
+    if (!instance) {
+        throw new Error('useWait must be called within a component setup function')
+    }
+
+    const wait = instance.appContext.config.globalProperties.$wait
+    if (!wait) {
+        throw new Error('vue-wait is not initialized. Make sure vue-wait boot file runs before using useWait()')
+    }
+
+    return wait
+}