@motor-cms/ui-admin 1.14.1 → 1.15.0

package/app/components/OnboardingStep.vue

@@ -0,0 +1,42 @@
+<script setup lang="ts">
+import type { StepEntity } from 'v-onboarding'
+
+const { t } = useI18n()
+
+defineProps<{
+  step: StepEntity | undefined
+  isFirst: boolean
+  isLast: boolean
+  next: () => void
+  previous: () => void
+  skip: () => void
+}>()
+</script>
+
+<template>
+  <VOnboardingStep>
+    <div class="v-onboarding-item">
+      <div class="v-onboarding-item__header">
+        <span v-if="step?.content?.title" class="v-onboarding-item__header-title">
+          {{ step.content.title }}
+        </span>
+        <button type="button" class="v-onboarding-item__header-close" :aria-label="t('motor-admin.onboarding.skip')" @click="skip">
+          <svg xmlns="http://www.w3.org/2000/svg" class="h-4 w-4" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M6 18L18 6M6 6l12 12" />
+          </svg>
+        </button>
+      </div>
+      <p v-if="step?.content?.description" class="v-onboarding-item__description">
+        {{ step.content.description }}
+      </p>
+      <div class="v-onboarding-item__actions">
+        <button v-if="!isFirst" type="button" class="v-onboarding-btn-secondary" @click="previous">
+          {{ t('motor-admin.onboarding.previous') }}
+        </button>
+        <button type="button" class="v-onboarding-btn-primary" @click="next">
+          {{ isLast ? t('motor-admin.onboarding.finish') : t('motor-admin.onboarding.next') }}
+        </button>
+      </div>
+    </div>
+  </VOnboardingStep>
+</template>

package/app/components/UsersOnboarding.vue

@@ -4,10 +4,11 @@ const { t } = useI18n()
 const { isCompleted: adminGridCompleted, markCompleted: markAdminGridDone } = useOnboardingState('admin-grid')
 const { getPending, clearPending, setPending } = usePendingOnboarding()
 const { completeOnboarding } = useProfileApi()
+const { commitDone } = useOnboardingDone()
 const router = useRouter()
 
 const wrapper = ref(null)
-const { start } = useVOnboarding(wrapper)
+const { start, finish: finishWrapper } = useVOnboarding(wrapper)
 
 const steps = computed(() => [
   {
@@ -29,13 +30,34 @@ const options = computed(() => ({
   },
 }))
 
+// Prevents onFinish from navigating when the user clicked skip instead
+const skipping = ref(false)
+
 function onFinish() {
+  if (skipping.value) {
+    skipping.value = false
+    return
+  }
   markAdminGridDone()
+  // commitDone() before the API call — the browser may cancel the in-flight
+  // request if the user reloads before it resolves, and the localStorage flag
+  // must already be present to prevent DashboardOnboarding from resetting
+  // state and restarting the tour when the dashboard remounts after the
+  // builder tour redirects back to '/'.
+  commitDone()
   completeOnboarding().catch(() => {})
   setPending('builder-pages')
   router.push('/motor-builder/builder-pages')
 }
 
+function skipAdminGrid() {
+  commitDone()
+  skipping.value = true
+  markAdminGridDone()
+  completeOnboarding().catch(() => {})
+  finishWrapper()
+}
+
 // Auto-start when the page was reached via the admin-nav onboarding chain.
 // The pending flag is set in DashboardOnboarding.vue after the admin-nav tour finishes.
 const stopWatch = watch(
@@ -46,8 +68,6 @@ const stopWatch = watch(
 
     if (getPending() === 'admin-grid' && !adminGridCompleted.value) {
       clearPending()
-      // Brief delay to let the grid data load before the tooltip appears
-      await new Promise(resolve => setTimeout(resolve, 600))
       start()
     }
   },
@@ -61,5 +81,9 @@ const stopWatch = watch(
     :steps="steps"
     :options="options"
     @finish="onFinish"
-  />
+  >
+    <template #default="{ step, next, previous, isFirst, isLast }">
+      <OnboardingStep :step="step" :next="next" :previous="previous" :skip="skipAdminGrid" :is-first="isFirst" :is-last="isLast" />
+    </template>
+  </VOnboardingWrapper>
 </template>

package/app/components/dashboard/DashboardOnboarding.vue

@@ -5,6 +5,8 @@ const { t } = useI18n()
 const { can } = usePermissions()
 const { user } = useSanctumAuth<User>()
 const router = useRouter()
+const { completeOnboarding } = useProfileApi()
+const { commitDone, isDone } = useOnboardingDone()
 
 const { isCompleted: announcementsCompleted, markCompleted: markAnnouncementsDone } = useOnboardingState('dashboard-announcements')
 const { isCompleted: notificationsCompleted, markCompleted: markNotificationsDone } = useOnboardingState('notifications')
@@ -19,10 +21,10 @@ const notificationsWrapper = ref(null)
 const searchWrapper = ref(null)
 const adminNavWrapper = ref(null)
 
-const { start: startAnnouncements } = useVOnboarding(announcementsWrapper)
-const { start: startNotifications } = useVOnboarding(notificationsWrapper)
-const { start: startSearch } = useVOnboarding(searchWrapper)
-const { start: startAdminNav } = useVOnboarding(adminNavWrapper)
+const { start: startAnnouncements, finish: finishAnnouncements } = useVOnboarding(announcementsWrapper)
+const { start: startNotifications, finish: finishNotifications } = useVOnboarding(notificationsWrapper)
+const { start: startSearch, finish: finishSearch } = useVOnboarding(searchWrapper)
+const { start: startAdminNav, finish: finishAdminNav } = useVOnboarding(adminNavWrapper)
 
 // ── Shared options ────────────────────────────────────────────────────────────
 const options = computed(() => ({
@@ -120,7 +122,7 @@ const adminNavSteps = computed(() => [
   },
 ])
 
-// ── Event handlers ────────────────────────────────────────────────────────────
+// ── Finish handlers ───────────────────────────────────────────────────────────
 
 /**
  * Announcements tour finished → chain to notifications.
@@ -169,24 +171,69 @@ function onAdminNavFinish() {
   router.push('/motor-admin/users')
 }
 
+// ── Skip handlers ─────────────────────────────────────────────────────────────
+// Pre-mark all remaining tours as done so @finish chain conditions are false,
+// then call finish() to close the wrapper.
+//
+// finish() is required — exit() from the slot only emits @exit without
+// changing the wrapper's internal currentIndex, so the tooltip stays open.
+//
+// completeOnboarding() clears show_onboarding on the backend so the watch
+// does not trigger another resetOnboardingState() on the next dashboard visit.
+// We also set user.value.data.show_onboarding = false immediately so the
+// in-memory auth cache does not cause another reset before the API response
+// arrives.
+
+function skipAll() {
+  // commitDone() must run BEFORE the API call — if the browser cancels the
+  // in-flight request on a hard reload the localStorage flag still survives
+  // and prevents the show_onboarding watch from resetting state.
+  commitDone()
+  markAnnouncementsDone()
+  markNotificationsDone()
+  markSearchDone()
+  markAdminNavDone()
+  if (user.value?.data) user.value.data.show_onboarding = false
+  completeOnboarding().catch(() => {})
+}
+
+function skipAnnouncements() { skipAll(); finishAnnouncements() }
+function skipNotifications() { skipAll(); finishNotifications() }
+function skipSearch() { skipAll(); finishSearch() }
+function skipAdminNav() { skipAll(); finishAdminNav() }
+
 // ── Start logic ───────────────────────────────────────────────────────────────
-// Announcements is the ONLY entry point. Each tour chains to the next via @finish.
-// VOnboardingWrapper is registered as client-only, so wrapper refs are null
-// until after hydration.
+// Watch both the 4 wrappers AND user.value.data so the show_onboarding check
+// never runs against a null/stale user — solving the race between wrapper mount
+// and the sanctum /api/user response.
+//
+// After resetting we immediately set user.value.data.show_onboarding = false so
+// that if DashboardOnboarding is unmounted and remounted (navigation away/back)
+// the same session does not trigger a second reset from the in-memory cache.
+// completeOnboarding() would clear the backend flag, but that is fire-and-forget
+// and may resolve after a re-render; the local mutation is the reliable guard.
 const stopWatch = watch(
-  [announcementsWrapper, notificationsWrapper, searchWrapper, adminNavWrapper],
-  async ([announcementsW, notificationsW, searchW, adminNavW]) => {
-    if (!announcementsW || !notificationsW || !searchW || !adminNavW) return
+  () => [
+    announcementsWrapper.value,
+    notificationsWrapper.value,
+    searchWrapper.value,
+    adminNavWrapper.value,
+    user.value?.data,
+  ] as const,
+  async ([announcementsW, notificationsW, searchW, adminNavW, userData]) => {
+    if (!announcementsW || !notificationsW || !searchW || !adminNavW || !userData) return
     stopWatch()
 
-    // If the backend flag is set, clear localStorage so the tour runs again
-    if (user.value?.data?.show_onboarding) {
+    // Only reset if the user has NOT already committed a skip.
+    // isSkipCommitted() reads localStorage, so it survives hard reloads even
+    // when the completeOnboarding() API call was cancelled by the browser.
+    // resetAll() in useOnboardingResetAll clears the skip flag, so a
+    // deliberate "restart tour" from the profile page still works correctly.
+    if (userData.show_onboarding && !isDone()) {
+      userData.show_onboarding = false
       resetOnboardingState()
     }
 
-    // Allow initial toasts to clear before starting
-    await new Promise(resolve => setTimeout(resolve, 2500))
-
     if (!announcementsCompleted.value) {
       startAnnouncements()
     }
@@ -201,23 +248,39 @@ const stopWatch = watch(
     :steps="announcementSteps"
     :options="options"
     @finish="onAnnouncementsFinish"
-  />
+  >
+    <template #default="{ step, next, previous, isFirst, isLast }">
+      <OnboardingStep :step="step" :next="next" :previous="previous" :skip="skipAnnouncements" :is-first="isFirst" :is-last="isLast" />
+    </template>
+  </VOnboardingWrapper>
   <VOnboardingWrapper
     ref="notificationsWrapper"
     :steps="notificationsSteps"
     :options="options"
     @finish="onNotificationsFinish"
-  />
+  >
+    <template #default="{ step, next, previous, isFirst, isLast }">
+      <OnboardingStep :step="step" :next="next" :previous="previous" :skip="skipNotifications" :is-first="isFirst" :is-last="isLast" />
+    </template>
+  </VOnboardingWrapper>
   <VOnboardingWrapper
     ref="searchWrapper"
     :steps="searchSteps"
     :options="options"
     @finish="onSearchFinish"
-  />
+  >
+    <template #default="{ step, next, previous, isFirst, isLast }">
+      <OnboardingStep :step="step" :next="next" :previous="previous" :skip="skipSearch" :is-first="isFirst" :is-last="isLast" />
+    </template>
+  </VOnboardingWrapper>
   <VOnboardingWrapper
     ref="adminNavWrapper"
     :steps="adminNavSteps"
     :options="options"
     @finish="onAdminNavFinish"
-  />
+  >
+    <template #default="{ step, next, previous, isFirst, isLast }">
+      <OnboardingStep :step="step" :next="next" :previous="previous" :skip="skipAdminNav" :is-first="isFirst" :is-last="isLast" />
+    </template>
+  </VOnboardingWrapper>
 </template>

package/app/composables/useOnboardingState.ts

@@ -12,6 +12,10 @@ export type OnboardingArea =
 
 const STORAGE_KEY = 'motor-onboarding-completed'
 const PENDING_KEY = 'motor-onboarding-pending'
+// Written before the completeOnboarding() API call so a hard reload between
+// skip/complete and the network response does not trigger a false restart.
+// Cleared by resetAll() so "restart tour" from profile overrides any prior done state.
+const DONE_KEY = 'motor-onboarding-done'
 
 function getCompleted(): Set<string> {
   try {
@@ -51,7 +55,8 @@ export function useOnboardingState(area: OnboardingArea) {
 
 /**
  * Clears all completed onboarding areas for the current user from localStorage.
- * Call this before navigating to dashboard to restart the full tour.
+ * Also clears the skip-committed flag so a "restart tour" from profile
+ * correctly overrides any previous skip.
  */
 export function useOnboardingResetAll() {
   const { user } = useSanctumAuth<User>()
@@ -72,6 +77,7 @@ export function useOnboardingResetAll() {
       completed.delete(`${userId.value}:${area}`)
     }
     persistCompleted(completed)
+    localStorage.removeItem(`${DONE_KEY}:${userId.value}`)
   }
 
   return { resetAll }
@@ -99,3 +105,27 @@ export function usePendingOnboarding() {
 
   return { setPending, getPending, clearPending }
 }
+
+/**
+ * Records that the user has intentionally ended the tour (via skip OR normal
+ * completion). Written to localStorage BEFORE the completeOnboarding() API
+ * call so the flag survives a hard reload if the browser cancels the request.
+ * DashboardOnboarding checks this flag before calling resetOnboardingState()
+ * so a stale show_onboarding=true in the sanctum auth cache never triggers a
+ * false restart. Cleared by resetAll() so "restart tour" from the profile
+ * page correctly overrides any prior done state.
+ */
+export function useOnboardingDone() {
+  const { user } = useSanctumAuth<User>()
+  const userId = computed(() => user.value?.data?.id?.toString() ?? 'anonymous')
+
+  function commitDone() {
+    localStorage.setItem(`${DONE_KEY}:${userId.value}`, '1')
+  }
+
+  function isDone(): boolean {
+    return !!localStorage.getItem(`${DONE_KEY}:${userId.value}`)
+  }
+
+  return { commitDone, isDone }
+}

package/app/lang/de/motor-admin/onboarding.json

@@ -2,6 +2,7 @@
   "next": "Weiter",
   "previous": "Zurück",
   "finish": "Fertig",
+  "skip": "Überspringen",
   "announcements": {
     "step1_title": "Meldungen",
     "step1_desc": "Dieses Panel zeigt wichtige Meldungen von Ihrem Team oder Systemadministratoren.",

package/app/lang/en/motor-admin/onboarding.json

@@ -2,6 +2,7 @@
   "next": "Next",
   "previous": "Previous",
   "finish": "Done",
+  "skip": "Skip",
   "announcements": {
     "step1_title": "Announcements",
     "step1_desc": "This panel shows important announcements from your team or system administrators.",

package/app/pages/index.vue

@@ -58,7 +58,7 @@ async function onDismiss(id: number) {
     <div class="flex items-center gap-2 mb-3">
       <UDashboardSidebarToggle class="lg:hidden shrink-0 -ml-2" />
       <SidebarToggleButton />
-      <UBreadcrumb :items="[{ label: t('motor-core.global.dashboard'), icon: 'i-lucide-home' }]" />
+      <UBreadcrumb :items="[{ label: t('motor-core.global.dashboard') }]" />
     </div>
     <div class="flex flex-col mb-6">
       <div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motor-cms/ui-admin",
-  "version": "1.14.1",
+  "version": "1.15.0",
   "type": "module",
   "main": "./nuxt.config.ts",
   "files": [
@@ -17,7 +17,7 @@
     "@vueuse/core": "^14.0.0",
     "sortablejs": "^1.15.0",
     "zod": "^4.0.0",
-    "@motor-cms/ui-core": "1.14.1"
+    "@motor-cms/ui-core": "1.15.0"
   },
   "peerDependencies": {
     "nuxt": "^4.0.0",