@motor-cms/ui-admin 1.7.0 → 1.8.1

package/app/assets/css/v-onboarding.css

@@ -0,0 +1,64 @@
+/* ==========================================================================
+   v-onboarding — Nuxt UI v4 theme integration
+   ========================================================================== */
+
+/* The library (v-onboarding/nuxt) injects its own inline <style> tag after
+   our stylesheet, so we need either !important or higher specificity to win.
+   We use both: [data-v-onboarding-wrapper] adds an attribute selector that
+   raises specificity above the library's class-only selectors. */
+
+:root {
+  --v-onboarding-overlay-z: 99998;
+  --v-onboarding-step-z: 99999;
+}
+
+[data-v-onboarding-wrapper] .v-onboarding-item {
+  background-color: var(--ui-bg-elevated) !important;
+  border: 1px solid var(--ui-border) !important;
+  border-radius: calc(var(--ui-radius) * 2) !important;
+  color: var(--ui-text) !important;
+  box-shadow: 0 20px 25px -5px rgb(0 0 0 / 0.15), 0 8px 10px -6px rgb(0 0 0 / 0.1) !important;
+}
+
+[data-v-onboarding-wrapper] .v-onboarding-item__header-title {
+  color: var(--ui-text-highlighted) !important;
+  font-weight: 600;
+  font-size: 0.9375rem;
+}
+
+[data-v-onboarding-wrapper] .v-onboarding-item__header-close:hover {
+  background-color: var(--ui-bg-accented) !important;
+}
+
+[data-v-onboarding-wrapper] .v-onboarding-item__description {
+  color: var(--ui-text-muted) !important;
+}
+
+[data-v-onboarding-wrapper] .v-onboarding-item__actions button.v-onboarding-btn-primary {
+  background-color: var(--ui-primary) !important;
+  border-color: transparent !important;
+  color: var(--ui-text-inverted) !important;
+  border-radius: calc(var(--ui-radius) * 2) !important;
+}
+
+[data-v-onboarding-wrapper] .v-onboarding-item__actions button.v-onboarding-btn-primary:hover {
+  background-color: color-mix(in srgb, var(--ui-primary) 88%, black) !important;
+}
+
+[data-v-onboarding-wrapper] .v-onboarding-item__actions button.v-onboarding-btn-primary:focus {
+  outline-color: var(--ui-primary) !important;
+}
+
+[data-v-onboarding-wrapper] .v-onboarding-item__actions button.v-onboarding-btn-secondary {
+  border-color: var(--ui-border-accented) !important;
+  color: var(--ui-text) !important;
+  border-radius: calc(var(--ui-radius) * 2) !important;
+}
+
+[data-v-onboarding-wrapper] .v-onboarding-item__actions button.v-onboarding-btn-secondary:hover {
+  background-color: var(--ui-bg-accented) !important;
+}
+
+[data-v-onboarding-wrapper] [data-popper-arrow]::before {
+  background: var(--ui-bg-elevated) !important;
+}

package/app/components/UsersOnboarding.vue

@@ -0,0 +1,65 @@
+<script setup lang="ts">
+const { t } = useI18n()
+
+const { isCompleted: adminGridCompleted, markCompleted: markAdminGridDone } = useOnboardingState('admin-grid')
+const { getPending, clearPending, setPending } = usePendingOnboarding()
+const { completeOnboarding } = useProfileApi()
+const router = useRouter()
+
+const wrapper = ref(null)
+const { start } = useVOnboarding(wrapper)
+
+const steps = computed(() => [
+  {
+    attachTo: { element: '#users-grid' },
+    content: {
+      title: t('motor-admin.onboarding.admin_grid.step1_title'),
+      description: t('motor-admin.onboarding.admin_grid.step1_desc'),
+    },
+  },
+])
+
+const options = computed(() => ({
+  scrollToStep: { enabled: true, options: { behavior: 'smooth' as ScrollBehavior, block: 'center' as ScrollLogicalPosition } },
+  popper: { strategy: 'fixed' as const },
+  labels: {
+    previousButton: t('motor-admin.onboarding.previous'),
+    nextButton: t('motor-admin.onboarding.next'),
+    finishButton: t('motor-admin.onboarding.finish'),
+  },
+}))
+
+function onFinish() {
+  markAdminGridDone()
+  completeOnboarding().catch(() => {})
+  setPending('builder-pages')
+  router.push('/motor-builder/builder-pages')
+}
+
+// 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(
+  wrapper,
+  async (w) => {
+    if (!w) return
+    stopWatch()
+
+    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()
+    }
+  },
+  { immediate: true },
+)
+</script>
+
+<template>
+  <VOnboardingWrapper
+    ref="wrapper"
+    :steps="steps"
+    :options="options"
+    @finish="onFinish"
+  />
+</template>

package/app/components/dashboard/DashboardAnnouncements.vue

@@ -23,6 +23,7 @@ const borderColors: Record<string, string> = {
 </script>
 
 <template>
+  <div id="onboarding-announcements-card">
   <UPageCard :ui="{ root: 'border-0 shadow-none' }">
     <template #header>
       <div class="flex items-center justify-between w-full">
@@ -40,6 +41,7 @@ const borderColors: Record<string, string> = {
         </div>
         <UButton
           v-if="canCreate"
+          id="onboarding-announcements-create"
           icon="i-lucide-plus"
           size="xs"
           variant="ghost"
@@ -48,6 +50,7 @@ const borderColors: Record<string, string> = {
         />
       </div>
     </template>
+    <div id="onboarding-announcements-body">
     <div v-if="loading" class="flex items-center justify-center py-6 text-muted">
       <UIcon name="i-lucide-loader-2" class="size-5 animate-spin" />
     </div>
@@ -84,5 +87,7 @@ const borderColors: Record<string, string> = {
         </div>
       </div>
     </div>
+    </div>
   </UPageCard>
+  </div>
 </template>

package/app/components/dashboard/DashboardOnboarding.vue

@@ -0,0 +1,223 @@
+<script setup lang="ts">
+import type { User } from '@motor-cms/ui-core/app/types/auth'
+
+const { t } = useI18n()
+const { can } = usePermissions()
+const { user } = useSanctumAuth<User>()
+const router = useRouter()
+
+const { isCompleted: announcementsCompleted, markCompleted: markAnnouncementsDone } = useOnboardingState('dashboard-announcements')
+const { isCompleted: notificationsCompleted, markCompleted: markNotificationsDone } = useOnboardingState('notifications')
+const { isCompleted: searchCompleted, markCompleted: markSearchDone } = useOnboardingState('search')
+const { isCompleted: adminNavCompleted, markCompleted: markAdminNavDone } = useOnboardingState('admin-nav')
+const { resetAll: resetOnboardingState } = useOnboardingResetAll()
+const { setPending } = usePendingOnboarding()
+
+// ── Wrappers ──────────────────────────────────────────────────────────────────
+const announcementsWrapper = ref(null)
+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)
+
+// ── Shared options ────────────────────────────────────────────────────────────
+const options = computed(() => ({
+  scrollToStep: { enabled: true, options: { behavior: 'smooth' as ScrollBehavior, block: 'center' as ScrollLogicalPosition } },
+  popper: { strategy: 'fixed' as const },
+  labels: {
+    previousButton: t('motor-admin.onboarding.previous'),
+    nextButton: t('motor-admin.onboarding.next'),
+    finishButton: t('motor-admin.onboarding.finish'),
+  },
+}))
+
+// ── Announcements steps ───────────────────────────────────────────────────────
+const canCreate = computed(() => can('dashboard-announcements.write'))
+
+const announcementSteps = computed(() => {
+  const steps = [
+    {
+      attachTo: { element: '#onboarding-announcements-card' },
+      content: {
+        title: t('motor-admin.onboarding.announcements.step1_title'),
+        description: t('motor-admin.onboarding.announcements.step1_desc'),
+      },
+    },
+    {
+      attachTo: { element: '#onboarding-announcements-body' },
+      content: {
+        title: t('motor-admin.onboarding.announcements.step2_title'),
+        description: t('motor-admin.onboarding.announcements.step2_desc'),
+      },
+    },
+  ]
+
+  if (canCreate.value) {
+    steps.push({
+      attachTo: { element: '#onboarding-announcements-create' },
+      content: {
+        title: t('motor-admin.onboarding.announcements.step3_title'),
+        description: t('motor-admin.onboarding.announcements.step3_desc'),
+      },
+    })
+  }
+
+  return steps
+})
+
+// ── Notifications steps ───────────────────────────────────────────────────────
+// Single step only: opening the slideover during an active v-onboarding tour
+// creates an unresolvable z-index conflict — v-onboarding's own overlay covers
+// the slideover panel, and the slideover teleports to body after the tooltip,
+// making either element hide the other. All relevant info is covered in one step.
+const notificationsSteps = computed(() => [
+  {
+    attachTo: { element: '#onboarding-notification-bell' },
+    content: {
+      title: t('motor-admin.onboarding.notifications.step1_title'),
+      description: t('motor-admin.onboarding.notifications.step1_desc'),
+    },
+    options: {
+      popper: {
+        placement: 'left' as const,
+      },
+    },
+  },
+])
+
+// ── Search steps ──────────────────────────────────────────────────────────────
+const searchSteps = computed(() => [
+  {
+    attachTo: { element: '#onboarding-search-button' },
+    content: {
+      title: t('motor-admin.onboarding.search.step1_title'),
+      description: t('motor-admin.onboarding.search.step1_desc'),
+    },
+    options: { popper: { placement: 'right' as const } },
+  },
+  {
+    attachTo: { element: '#onboarding-search-button' },
+    content: {
+      title: t('motor-admin.onboarding.search.step2_title'),
+      description: t('motor-admin.onboarding.search.step2_desc'),
+    },
+    options: { popper: { placement: 'right' as const } },
+  },
+])
+
+// ── Admin navigation steps ────────────────────────────────────────────────────
+const adminNavSteps = computed(() => [
+  {
+    attachTo: { element: '#onboarding-sidebar-nav' },
+    content: {
+      title: t('motor-admin.onboarding.admin_nav.step1_title'),
+      description: t('motor-admin.onboarding.admin_nav.step1_desc'),
+    },
+  },
+])
+
+// ── Event handlers ────────────────────────────────────────────────────────────
+
+/**
+ * Announcements tour finished → chain to notifications.
+ */
+async function onAnnouncementsFinish() {
+  markAnnouncementsDone()
+  await nextTick()
+  if (!notificationsCompleted.value) {
+    startNotifications()
+  }
+}
+
+/**
+ * Notifications tour finished → chain to search tour.
+ */
+async function onNotificationsFinish() {
+  markNotificationsDone()
+  await nextTick()
+  if (!searchCompleted.value) {
+    startSearch()
+  }
+  else if (!adminNavCompleted.value) {
+    startAdminNav()
+  }
+}
+
+/**
+ * Search tour finished → chain to admin-nav tour.
+ */
+async function onSearchFinish() {
+  markSearchDone()
+  await nextTick()
+  if (!adminNavCompleted.value) {
+    startAdminNav()
+  }
+}
+
+/**
+ * Admin-nav tour finished → mark done, store pending flag, navigate to users list.
+ * UsersOnboarding on the users page detects the pending flag and auto-starts
+ * the grid explanation tour.
+ */
+function onAdminNavFinish() {
+  markAdminNavDone()
+  setPending('admin-grid')
+  router.push('/motor-admin/users')
+}
+
+// ── 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.
+const stopWatch = watch(
+  [announcementsWrapper, notificationsWrapper, searchWrapper, adminNavWrapper],
+  async ([announcementsW, notificationsW, searchW, adminNavW]) => {
+    if (!announcementsW || !notificationsW || !searchW || !adminNavW) return
+    stopWatch()
+
+    // If the backend flag is set, clear localStorage so the tour runs again
+    if (user.value?.data?.show_onboarding) {
+      resetOnboardingState()
+    }
+
+    // Allow initial toasts to clear before starting
+    await new Promise(resolve => setTimeout(resolve, 2500))
+
+    if (!announcementsCompleted.value) {
+      startAnnouncements()
+    }
+  },
+  { immediate: true },
+)
+</script>
+
+<template>
+  <VOnboardingWrapper
+    ref="announcementsWrapper"
+    :steps="announcementSteps"
+    :options="options"
+    @finish="onAnnouncementsFinish"
+  />
+  <VOnboardingWrapper
+    ref="notificationsWrapper"
+    :steps="notificationsSteps"
+    :options="options"
+    @finish="onNotificationsFinish"
+  />
+  <VOnboardingWrapper
+    ref="searchWrapper"
+    :steps="searchSteps"
+    :options="options"
+    @finish="onSearchFinish"
+  />
+  <VOnboardingWrapper
+    ref="adminNavWrapper"
+    :steps="adminNavSteps"
+    :options="options"
+    @finish="onAdminNavFinish"
+  />
+</template>

package/app/composables/useOnboardingState.ts

@@ -0,0 +1,101 @@
+import type { User } from '@motor-cms/ui-core/app/types/auth'
+
+// Extend this union as new areas are added
+export type OnboardingArea =
+  | 'dashboard-announcements'
+  | 'notifications'
+  | 'search'
+  | 'admin-nav'
+  | 'admin-grid'
+  | 'user-profile'
+  | 'builder-pages'
+
+const STORAGE_KEY = 'motor-onboarding-completed'
+const PENDING_KEY = 'motor-onboarding-pending'
+
+function getCompleted(): Set<string> {
+  try {
+    const raw = localStorage.getItem(STORAGE_KEY)
+    return new Set(raw ? JSON.parse(raw) : [])
+  }
+  catch {
+    return new Set()
+  }
+}
+
+function persistCompleted(ids: Set<string>) {
+  localStorage.setItem(STORAGE_KEY, JSON.stringify([...ids]))
+}
+
+export function useOnboardingState(area: OnboardingArea) {
+  const { user } = useSanctumAuth<User>()
+  const userId = computed(() => user.value?.data?.id?.toString() ?? 'anonymous')
+  const key = computed(() => `${userId.value}:${area}`)
+
+  const isCompleted = computed(() => getCompleted().has(key.value))
+
+  function markCompleted() {
+    const completed = getCompleted()
+    completed.add(key.value)
+    persistCompleted(completed)
+  }
+
+  function reset() {
+    const completed = getCompleted()
+    completed.delete(key.value)
+    persistCompleted(completed)
+  }
+
+  return { isCompleted, markCompleted, reset }
+}
+
+/**
+ * Clears all completed onboarding areas for the current user from localStorage.
+ * Call this before navigating to dashboard to restart the full tour.
+ */
+export function useOnboardingResetAll() {
+  const { user } = useSanctumAuth<User>()
+  const userId = computed(() => user.value?.data?.id?.toString() ?? 'anonymous')
+
+  function resetAll() {
+    const completed = getCompleted()
+    const areas: OnboardingArea[] = [
+      'dashboard-announcements',
+      'notifications',
+      'search',
+      'admin-nav',
+      'admin-grid',
+      'user-profile',
+      'builder-pages',
+    ]
+    for (const area of areas) {
+      completed.delete(`${userId.value}:${area}`)
+    }
+    persistCompleted(completed)
+  }
+
+  return { resetAll }
+}
+
+/**
+ * Cross-page trigger: marks which onboarding area should auto-start
+ * on the next page load. Scoped by user ID to prevent cross-user leakage.
+ */
+export function usePendingOnboarding() {
+  const { user } = useSanctumAuth<User>()
+  const userId = computed(() => user.value?.data?.id?.toString() ?? 'anonymous')
+
+  function setPending(area: OnboardingArea) {
+    localStorage.setItem(`${PENDING_KEY}:${userId.value}`, area)
+  }
+
+  function getPending(): OnboardingArea | null {
+    return (localStorage.getItem(`${PENDING_KEY}:${userId.value}`) as OnboardingArea) || null
+  }
+
+  function clearPending() {
+    localStorage.removeItem(`${PENDING_KEY}:${userId.value}`)
+  }
+
+  return { setPending, getPending, clearPending }
+}

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

@@ -0,0 +1,57 @@
+{
+  "next": "Weiter",
+  "previous": "Zurück",
+  "finish": "Fertig",
+  "announcements": {
+    "step1_title": "Meldungen",
+    "step1_desc": "Dieses Panel zeigt wichtige Meldungen von Ihrem Team oder Systemadministratoren.",
+    "step2_title": "Meldungen lesen",
+    "step2_desc": "Jede Karte zeigt eine Nachricht mit ihrem Typ (Info, Warnung oder Fehler). Klicken Sie auf ×, um sie nach dem Lesen auszublenden.",
+    "step3_title": "Meldung erstellen",
+    "step3_desc": "Als Administrator können Sie Meldungen an sich selbst, bestimmte Nutzer oder alle im Mandanten senden."
+  },
+  "notifications": {
+    "step1_title": "Benachrichtigungscenter",
+    "step1_desc": "Der rote Zähler zeigt ungelesene Benachrichtigungen. Klicken Sie auf die Glocke, um das Benachrichtigungscenter zu öffnen — hier sehen Sie alle Meldungen mit Typ und Zeitstempel, können einzelne Einträge entfernen oder alle auf einmal löschen."
+  },
+  "search": {
+    "step1_title": "Globale Suche",
+    "step1_desc": "Mit der Suche finden Sie sofort Seiten, Benutzer, Dateien und weitere Inhalte im gesamten System. Einfach tippen – Ergebnisse erscheinen direkt während der Eingabe.",
+    "step2_title": "Tastaturkürzel",
+    "step2_desc": "Drücken Sie ⌘K (oder Strg+K unter Windows) von überall im Admin, um die Suche ohne Maus zu öffnen. Halten Sie ⌘ gedrückt, um alle verfügbaren Tastenkürzel anzuzeigen."
+  },
+  "admin_nav": {
+    "step1_title": "Navigationsbereich",
+    "step1_desc": "Über die Seitenleiste erreichen Sie alle Verwaltungsbereiche. Klicken Sie auf 'Administration', um Benutzer, Rollen und weitere Einstellungen zu verwalten. Als nächstes öffnen wir die Benutzerliste."
+  },
+  "admin_grid": {
+    "step1_title": "Datensätze bearbeiten",
+    "step1_desc": "In dieser Übersicht sehen Sie alle Benutzer. Klicken Sie einfach auf eine Zeile — der Datensatz öffnet sich direkt zum Bearbeiten."
+  },
+  "builder_pages_list": {
+    "step1_title": "Seite öffnen um die Tour zu starten",
+    "step1_desc": "Klicken Sie auf eine beliebige Zeile, um die Seite im Editor zu öffnen. Die Builder-Tour startet dann automatisch."
+  },
+  "builder_pages": {
+    "step1_title": "Seiteneditor",
+    "step1_desc": "Willkommen im Seiteneditor. Hier können Sie Inhalt und Layout dieser Seite visuell bearbeiten und gestalten.",
+    "step2_title": "Veröffentlichungsstatus",
+    "step2_desc": "Dieses Abzeichen zeigt, ob die Seite veröffentlicht, geplant oder ein Entwurf ist. Klicken Sie darauf, um die Seite zu veröffentlichen, zu planen oder offline zu nehmen.",
+    "step3_title": "Änderungsverlauf",
+    "step3_desc": "Machen Sie Änderungen mit den Pfeilschaltflächen rückgängig oder wiederholen Sie sie. Das Uhrsymbol öffnet den vollständigen Verlauf dieser Bearbeitungssitzung.",
+    "step4_title": "Geräteansicht",
+    "step4_desc": "Wechseln Sie zwischen Desktop-, Tablet- und Mobilansicht, um zu sehen, wie Ihre Seite auf verschiedenen Bildschirmgrößen aussieht.",
+    "step5_title": "Seitenstruktur",
+    "step5_desc": "Das Strukturpanel zeigt alle Zeilen und Komponenten Ihrer Seite als Baumansicht. Klicken Sie auf einen Eintrag, um ihn im Editor auszuwählen.",
+    "step6_title": "Layout-Zeilen",
+    "step6_desc": "Fügen Sie über das Layout-Panel einen neuen Bereich mit 1, 2, 3 oder 4 Spalten ein. Klicken Sie auf ein Layout oder ziehen Sie es auf den Editor.",
+    "step7_title": "Inhaltskomponenten",
+    "step7_desc": "Das Komponentenpanel listet alle verfügbaren Inhaltsbausteine auf — Überschriften, Bilder, Videos, Buttons und mehr. Klicken oder ziehen Sie eine Komponente in eine Spalte.",
+    "step8_title": "Der Editor",
+    "step8_desc": "Klicken Sie auf ein Element, um es auszuwählen und seine Eigenschaften rechts anzuzeigen. Ziehen Sie den Griff links einer Zeile, um Bereiche umzusortieren.",
+    "step9_title": "Element-Eigenschaften",
+    "step9_desc": "Wenn ein Element ausgewählt ist, erscheinen seine Eigenschaften hier. Bearbeiten Sie Inhalt, Darstellung und erweiterte Einstellungen. Der Navigationspfad oben führt zu übergeordneten Elementen.",
+    "step10_title": "Speichern",
+    "step10_desc": "Klicken Sie auf Speichern (oder drücken Sie Cmd+S). Der Dropdown-Pfeil ermöglicht Speichern und Schließen in einem Schritt. Ein pulsierender Punkt zeigt ungespeicherte Änderungen an."
+  }
+}

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

@@ -0,0 +1,57 @@
+{
+  "next": "Next",
+  "previous": "Previous",
+  "finish": "Done",
+  "announcements": {
+    "step1_title": "Announcements",
+    "step1_desc": "This panel shows important announcements from your team or system administrators.",
+    "step2_title": "Reading announcements",
+    "step2_desc": "Each card shows a message with its type (info, warning, or error). Click the × to dismiss it once you have read it.",
+    "step3_title": "Create an announcement",
+    "step3_desc": "As an admin you can post announcements to yourself, specific users, or everyone in your client."
+  },
+  "notifications": {
+    "step1_title": "Notification center",
+    "step1_desc": "The red counter shows unread notifications. Click the bell to open the notification center — here you can see all messages with type and timestamp, remove individual entries, or clear all at once."
+  },
+  "search": {
+    "step1_title": "Global search",
+    "step1_desc": "Use the search to instantly find pages, users, files, and other content across the entire system. Just start typing and results appear as you go.",
+    "step2_title": "Keyboard shortcut",
+    "step2_desc": "Press ⌘K (or Ctrl+K on Windows) from anywhere in the admin to open search without reaching for the mouse. Hold ⌘ to see all available shortcuts."
+  },
+  "admin_nav": {
+    "step1_title": "Navigation",
+    "step1_desc": "Use the sidebar to access all administration areas. Click on 'Administration' to manage users, roles, and other settings. Next, we will open the users list."
+  },
+  "admin_grid": {
+    "step1_title": "Editing records",
+    "step1_desc": "This overview shows all users. Simply click on any row — the record opens directly for editing."
+  },
+  "builder_pages_list": {
+    "step1_title": "Open a page to start the tour",
+    "step1_desc": "Click on any row to open the page in the builder editor. The builder tour will start automatically."
+  },
+  "builder_pages": {
+    "step1_title": "Page Builder",
+    "step1_desc": "Welcome to the page builder. Here you can visually build and edit the content and layout of this page.",
+    "step2_title": "Publishing status",
+    "step2_desc": "This badge shows whether the page is published, scheduled, or a draft. Click it to publish, schedule, or take the page offline.",
+    "step3_title": "Edit history",
+    "step3_desc": "Undo or redo your last changes with the arrow buttons. The clock icon opens the full change history for this editing session.",
+    "step4_title": "Device preview",
+    "step4_desc": "Switch between desktop, tablet, and mobile views to see how your page looks on different screen sizes.",
+    "step5_title": "Page outline",
+    "step5_desc": "The outline panel shows all rows and components on your page as a tree. Click any item to select it on the canvas.",
+    "step6_title": "Layout rows",
+    "step6_desc": "Use the layout panel to add a new section with 1, 2, 3, or 4 columns. Click a layout to insert it, or drag it onto the canvas.",
+    "step7_title": "Content components",
+    "step7_desc": "The components panel lists all available content blocks — headings, images, videos, buttons, and more. Click or drag a component to add it inside a column.",
+    "step8_title": "The canvas",
+    "step8_desc": "Click any element on the canvas to select it and reveal its properties on the right. Drag the handle on the left of a row to reorder sections.",
+    "step9_title": "Element properties",
+    "step9_desc": "When an element is selected, its properties appear here. Edit content, change styling, and configure advanced settings. The breadcrumb at the top lets you navigate to parent elements.",
+    "step10_title": "Save your work",
+    "step10_desc": "Click Save (or press Cmd+S) to save your changes. The dropdown arrow lets you save and close in one step. A pulsing dot indicates unsaved changes."
+  }
+}

package/app/pages/index.vue

@@ -25,6 +25,7 @@ const {
 } = useDashboardData()
 
 const announcementModalOpen = ref(false)
+const createPageModalOpen = ref(false)
 
 const currentDate = computed(() => {
   return new Date().toLocaleDateString(locale.value, {
@@ -35,6 +36,10 @@ const currentDate = computed(() => {
   })
 })
 
+function onPageCreated(page: { id: number }) {
+  navigateTo(`/motor-builder/builder-pages/${page.id}/edit`)
+}
+
 function onAnnouncementCreated() {
   refresh()
   toast.add({ title: t('motor-admin.dashboard.announcement_created'), icon: 'i-lucide-megaphone', color: 'success' })
@@ -50,6 +55,11 @@ async function onDismiss(id: number) {
 
 <template>
   <div class="p-6">
+    <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' }]" />
+    </div>
     <div class="flex flex-col mb-6">
       <div>
         <h1 class="text-xl font-heading font-semibold text-highlighted">
@@ -65,7 +75,7 @@ async function onDismiss(id: number) {
           color="primary"
           size="sm"
           :label="t('motor-admin.dashboard.quick_actions.new_page')"
-          @click="navigateTo('/motor-builder/builder-pages/create')"
+          @click="createPageModalOpen = true"
         />
         <UButton
           icon="i-lucide-upload"
@@ -113,5 +123,14 @@ async function onDismiss(id: number) {
       v-model:open="announcementModalOpen"
       @created="onAnnouncementCreated"
     />
+
+    <DashboardOnboarding />
+
+    <BuilderPageSettingsModal
+      v-model:open="createPageModalOpen"
+      :page-data="null"
+      :is-create-mode="true"
+      @created="onPageCreated"
+    />
   </div>
 </template>

package/app/pages/motor-admin/users/index.vue

@@ -44,6 +44,7 @@ const { fetch: fetchUsers } = useGridData<User>('/api/v2/users')
 </script>
 
 <template>
+  <UsersOnboarding />
   <GridPage
     :title="t('motor-admin.users.title')"
     :subtitle="t('motor-admin.users.subtitle')"

package/app/pages/profile.vue

@@ -9,8 +9,10 @@ definePageMeta({
 })
 
 const { t } = useI18n()
+const router = useRouter()
 const { user, refreshIdentity } = useSanctumAuth<User>()
-const { updateProfile } = useProfileApi()
+const { updateProfile, resetOnboarding } = useProfileApi()
+const { resetAll: resetOnboardingState } = useOnboardingResetAll()
 const { success, error: notifyError, info } = useNotify()
 
 // Test function to demonstrate error notifications
@@ -172,6 +174,33 @@ const passwordState = reactive({
 
 const passwordLoading = ref(false)
 
+// ============================================
+// Onboarding Tour
+// ============================================
+
+const onboardingLoading = ref(false)
+
+async function onRestartTour() {
+  onboardingLoading.value = true
+  try {
+    await resetOnboarding()
+    resetOnboardingState()
+    success(t('motor-core.profile.toast_tour_reset_title'), t('motor-core.profile.toast_tour_reset_message'))
+    await router.push('/')
+  }
+  catch (err: unknown) {
+    const message = err instanceof Error ? err.message : t('motor-core.profile.toast_tour_reset_error')
+    notifyError(t('motor-core.profile.toast_tour_reset_error'), message, {
+      message,
+      stack: err instanceof Error ? err.stack : undefined,
+      url: '/api/profile/reset-onboarding',
+    })
+  }
+  finally {
+    onboardingLoading.value = false
+  }
+}
+
 async function onPasswordSubmit(event: FormSubmitEvent<PasswordSchema>) {
   passwordLoading.value = true
 
@@ -293,6 +322,22 @@ async function onPasswordSubmit(event: FormSubmitEvent<PasswordSchema>) {
           </UForm>
         </UPageCard>
 
+        <!-- Onboarding Tour Card -->
+        <UPageCard
+          :title="t('motor-core.profile.onboarding_title')"
+          :description="t('motor-core.profile.onboarding_description')"
+        >
+          <div class="flex justify-end">
+            <UButton
+              :loading="onboardingLoading"
+              icon="i-lucide-graduation-cap"
+              @click="onRestartTour"
+            >
+              {{ t('motor-core.profile.restart_tour') }}
+            </UButton>
+          </div>
+        </UPageCard>
+
         <!-- Change Password Card -->
         <UPageCard
           :title="t('motor-core.profile.change_password_title')"

package/nuxt.config.ts

@@ -1 +1,8 @@
-export default defineNuxtConfig({})
+import { fileURLToPath } from 'node:url'
+import { dirname, resolve } from 'node:path'
+
+const __layerDir = dirname(fileURLToPath(import.meta.url))
+
+export default defineNuxtConfig({
+  css: [resolve(__layerDir, 'app/assets/css/v-onboarding.css')],
+})

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motor-cms/ui-admin",
-  "version": "1.7.0",
+  "version": "1.8.1",
   "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.7.0"
+    "@motor-cms/ui-core": "1.8.1"
   },
   "peerDependencies": {
     "nuxt": "^4.0.0",