@omnitend/dashboard-for-laravel 0.9.1 → 0.10.0

package/docs/public/docs-map.md

@@ -1,7 +1,7 @@
 # Documentation Map
 
 > Auto-generated hierarchical overview of all documentation
-> Last updated: 2026-07-04T11:43:17.631Z
+> Last updated: 2026-07-04T12:57:30.629Z
 
 This file provides a complete map of all available documentation for AI agents and developers.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omnitend/dashboard-for-laravel",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "description": "Vue 3 dashboard components for Laravel with Bootstrap Vue Next",
   "type": "module",
   "main": "./dist/dashboard-for-laravel.umd.cjs",

package/resources/js/components/extended/DXBasicForm.vue

@@ -1,5 +1,7 @@
 <!--
-  DXBasicForm — deprecated alias of DXForm.
+  @component
+  Deprecated alias of DXForm that renders a flat form (DXForm without a `tabs`
+  prop) and warns once on use.
 
   A flat form is just DXForm without a `tabs` prop. This wrapper forwards
   everything to DXForm and logs a one-time deprecation warning so existing
@@ -34,6 +36,7 @@ onMounted(() => {
     <DXForm v-bind="($attrs as any)">
         <!-- Forward all slots (#value(<key>), #footer, etc.) to DXForm. -->
         <template v-for="(_, name) in $slots" :key="name" #[name]="slotProps">
+            <!-- @slot Passes every DXForm slot (e.g. `value(<key>)`, `footer`) straight through to the wrapped DXForm, along with its slot props. -->
             <slot :name="name" v-bind="slotProps" />
         </template>
     </DXForm>

package/resources/js/components/extended/DXDashboard.vue

@@ -1,3 +1,11 @@
+<!--
+  @component
+  DXDashboard is the full dashboard shell — a collapsible sidebar
+  (`DXDashboardSidebar`) alongside a top navbar (`DXDashboardNavbar`) and the
+  page content area. It owns sidebar visibility state (persisted to
+  localStorage, SSR-safe) and forwards any `sidebar-*` slot to the sidebar and
+  any `navbar-*` slot to the navbar, stripping the prefix.
+-->
 <template>
   <div class="dashboard-layout d-flex" :data-dashboard-id="dashboardId">
     <!-- Sidebar -->
@@ -17,6 +25,7 @@
         :key="strippedName"
         #[strippedName]="slotProps"
       >
+        <!-- @slot Forwards any `sidebar-*` slot to DXDashboardSidebar with the `sidebar-` prefix stripped (e.g. `sidebar-brand` becomes the sidebar's `brand` slot). -->
         <slot :name="originalName" v-bind="slotProps" />
       </template>
     </DXDashboardSidebar>
@@ -36,6 +45,7 @@
           :key="strippedName"
           #[strippedName]="slotProps"
         >
+          <!-- @slot Forwards any `navbar-*` slot to DXDashboardNavbar with the `navbar-` prefix stripped (e.g. `navbar-actions` becomes the navbar's `actions` slot). -->
           <slot :name="originalName" v-bind="slotProps" />
         </template>
       </DXDashboardNavbar>
@@ -45,6 +55,7 @@
         <DContainer fluid>
           <DRow class="justify-content-center">
             <DCol cols="12" xl="10">
+              <!-- @slot Default slot for the main page content, rendered in the centred content column. -->
               <slot />
             </DCol>
           </DRow>

package/resources/js/components/extended/DXDashboardNavbar.vue

@@ -1,14 +1,23 @@
+<!--
+  @component
+  Top navigation bar for the dashboard shell: menu toggle, page title, centred
+  search, page-level actions, and the user menu. Usually rendered by
+  `DXDashboard`, which forwards these slots with a `navbar-` prefix.
+-->
 <template>
   <header class="dashboard-navbar bg-white border-bottom">
-    <DContainer fluid class="h-100">
-      <DRow class="h-100 align-items-center">
-        <DCol class="d-flex align-items-center gap-3">
+    <DContainer fluid>
+      <!-- Flex bar that wraps: below `md` the search drops to its own
+           full-width row beneath the toggle/title/user-menu row. -->
+      <div class="dashboard-navbar__bar d-flex flex-wrap align-items-center gap-3">
+        <div class="dashboard-navbar__start d-flex align-items-center gap-3">
           <DButton
             variant="link"
             class="text-dark p-0"
             @click="$emit('toggleSidebar')"
             aria-label="Toggle sidebar"
           >
+            <!-- @slot Custom hamburger/menu icon. Defaults to a three-line SVG. -->
             <slot name="menu-icon">
               <svg
                 xmlns="http://www.w3.org/2000/svg"
@@ -26,13 +35,33 @@
           </DButton>
 
           <h4 v-if="pageTitle" class="mb-0 fw-semibold d-none d-md-block">{{ pageTitle }}</h4>
+        </div>
 
-          <div class="flex-grow-1 d-flex justify-content-center">
-            <slot name="search" />
+        <div
+          v-if="$slots.search"
+          class="dashboard-navbar__search d-flex justify-content-center"
+        >
+          <!-- @slot Search input or component. Centred in the bar on wider screens; drops to its own full-width row below the `md` breakpoint. -->
+          <slot name="search" />
+        </div>
+
+        <div class="dashboard-navbar__end d-flex align-items-center gap-3">
+          <!-- Page-level primary actions, right-aligned next to the user menu -->
+          <div
+            v-if="$slots.actions"
+            class="dashboard-navbar__actions d-flex align-items-center gap-2"
+          >
+            <!--
+              @slot Page-level primary actions (e.g. a Create button), right-aligned next to the user menu.
+              @binding {string} pageTitle The current page title, for context.
+            -->
+            <slot name="actions" :pageTitle="pageTitle" />
           </div>
-        </DCol>
 
-        <DCol cols="auto">
+          <!--
+            @slot Replaces the entire user menu (the default avatar dropdown).
+            @binding {object} user The signed-in user.
+          -->
           <slot name="user-menu" :user="user">
             <DDropdown
               v-if="user"
@@ -42,6 +71,10 @@
               no-caret
             >
               <template #button-content>
+                <!--
+                  @slot Custom user avatar/icon in the dropdown trigger.
+                  @binding {string} initial The first letter of the user's name.
+                -->
                 <slot name="user-icon" :initial="getUserInitial(user)">
                   <div class="user-avatar">
                     {{ getUserInitial(user) }}
@@ -49,29 +82,33 @@
                 </slot>
               </template>
 
+              <!--
+                @slot Items for the default user dropdown menu.
+                @binding {object} user The signed-in user.
+              -->
               <slot name="user-menu-items" :user="user" />
             </DDropdown>
           </slot>
-        </DCol>
-      </DRow>
+        </div>
+      </div>
     </DContainer>
   </header>
 </template>
 
 <script setup lang="ts">
 import DContainer from "../base/DContainer.vue";
-import DRow from "../base/DRow.vue";
-import DCol from "../base/DCol.vue";
 import DButton from "../base/DButton.vue";
 import DDropdown from "../base/DDropdown.vue";
 
 withDefaults(
   defineProps<{
+    /** The signed-in user shown in the avatar dropdown. `null` hides the menu. */
     user?: {
       name: string;
       email: string;
       [key: string]: any;
     } | null;
+    /** Page title shown at the left of the navbar (hidden below the `md` breakpoint). */
     pageTitle?: string;
   }>(),
   {
@@ -81,6 +118,7 @@ withDefaults(
 );
 
 defineEmits<{
+  /** Emitted when the hamburger menu button is clicked. */
   toggleSidebar: [];
 }>();
 
@@ -97,6 +135,40 @@ const getUserInitial = (user: { name: string } | null) => {
   z-index: 1000;
 }
 
+.dashboard-navbar__bar {
+  min-height: 3.5rem;
+  padding: 0.5rem 0;
+}
+
+/* Push the user-menu / actions cluster to the right. */
+.dashboard-navbar__end {
+  margin-left: auto;
+}
+
+/*
+ * Mobile-first: the search sits on its own full-width row below the toggle /
+ * title / user-menu row (order after both, flex-basis 100% forces the wrap).
+ * From `md` up it moves inline between the title and the user menu and grows to
+ * fill the middle, centring its content.
+ */
+.dashboard-navbar__search {
+  order: 3;
+  flex: 0 0 100%;
+  width: 100%;
+}
+
+@media (min-width: 768px) {
+  .dashboard-navbar__search {
+    order: 1;
+    flex: 1 1 auto;
+    width: auto;
+  }
+
+  .dashboard-navbar__end {
+    order: 2;
+  }
+}
+
 .user-avatar {
   width: 32px;
   height: 32px;

package/resources/js/components/extended/DXDashboardSidebar.vue

@@ -1,14 +1,29 @@
+<!--
+  @component
+  Collapsible dashboard sidebar: renders a brand header plus grouped navigation
+  from a `navigation` array, highlighting the item matching the current route.
+  Groups can be plain labelled sections or accordion toggles that expand/collapse
+  their items, and the active-route group opens automatically. The rail itself can
+  collapse to an icons-only strip or hide entirely. Provides `brand` and `link`
+  slots for custom rendering.
+-->
 <template>
   <aside
     ref="sidebarRef"
     class="dashboard-sidebar text-white"
     :class="{
       'sidebar-collapsed': collapsed,
-      'sidebar-hidden': hidden
+      'sidebar-hidden': hidden,
+      'sidebar-collapsible-groups': collapsibleGroups && !collapsed
     }"
   >
     <div class="sidebar-header p-3">
       <div class="d-flex align-items-center justify-content-between">
+        <!--
+          @slot Brand/logo area in the sidebar header. Defaults to the title's initial plus the full title (hidden when collapsed).
+          @binding {boolean} collapsed Whether the sidebar rail is collapsed to icons only.
+          @binding {string} title The sidebar title text.
+        -->
         <slot name="brand" :collapsed="collapsed" :title="title">
           <div class="brand-container" :class="{ 'collapsed': collapsed }">
             <div class="brand-initial">{{ brandInitial }}</div>
@@ -20,7 +35,7 @@
       </div>
     </div>
 
-    <nav class="sidebar-nav p-3">
+    <nav ref="navRef" class="sidebar-nav p-3">
       <template v-for="(group, groupIndex) in navigation" :key="groupIndex">
         <div
           v-if="group.visible !== false"
@@ -34,7 +49,7 @@
             class="nav-group-toggle text-uppercase small fw-semibold mb-2 px-2"
             :aria-expanded="isGroupExpanded(groupIndex, group)"
             :aria-controls="groupItemsId(groupIndex)"
-            @click="toggleGroup(groupIndex)"
+            @click="toggleGroup(groupKey(group, groupIndex))"
           >
             <span class="nav-group-toggle-label">{{ group.label }}</span>
             <svg
@@ -78,12 +93,19 @@
           >
             <ul class="nav flex-column gap-1">
               <li v-for="(item, itemIndex) in group.items" :key="itemIndex" class="nav-item">
+                <!--
+                  @slot Renders a single navigation item link. Defaults to an anchor with optional icon, label, and badge.
+                  @binding {object} item The navigation item (label, url, icon, badge, badgeColor).
+                  @binding {boolean} isActive Whether this item matches the current route.
+                  @binding {boolean} collapsed Whether the sidebar rail is collapsed to icons only.
+                  @binding {boolean} isExpanded Whether the item's group is currently expanded.
+                -->
                 <slot
                   name="link"
                   :item="item"
-                  :is-active="isActive(item.url)"
+                  :isActive="isActive(item.url)"
                   :collapsed="collapsed"
-                  :is-expanded="isGroupExpanded(groupIndex, group)"
+                  :isExpanded="isGroupExpanded(groupIndex, group)"
                 >
                   <a
                     :href="item.url"
@@ -115,6 +137,14 @@
         </div>
       </template>
     </nav>
+
+    <div v-if="$slots.footer" class="sidebar-footer p-3">
+      <!--
+        @slot Utility/secondary links pinned to the bottom of the sidebar (help, changelog, sign-out, …), below the nav groups.
+        @binding {boolean} collapsed Whether the sidebar rail is collapsed to icons only.
+      -->
+      <slot name="footer" :collapsed="collapsed" />
+    </div>
   </aside>
 </template>
 
@@ -123,10 +153,15 @@ import { computed, ref, onMounted, watch, nextTick, useId } from 'vue';
 import type { Navigation, NavigationGroup } from '../../types/navigation';
 
 const props = withDefaults(defineProps<{
+  /** Grouped navigation to render: an array of groups, each with a label and items. */
   navigation: Navigation;
+  /** The current route URL, used to highlight the matching nav item and open its group. */
   currentUrl: string;
+  /** Collapse the rail to an icons-only strip, hiding labels and the brand title. */
   collapsed?: boolean;
+  /** Hide the sidebar entirely (`display: none`). */
   hidden?: boolean;
+  /** Sidebar title; its first letter is also used as the brand initial. */
   title?: string;
   /**
    * Turn group headers into accordion toggles that collapse/expand their items.
@@ -149,14 +184,24 @@ const props = withDefaults(defineProps<{
 });
 
 defineEmits<{
+  /** Emitted to request toggling the sidebar's collapsed/expanded state. */
   toggle: [];
 }>();
 
 const sidebarRef = ref<HTMLElement | null>(null);
+const navRef = ref<HTMLElement | null>(null);
 
 const uid = useId();
 const groupItemsId = (index: number): string => `${uid}-nav-group-${index}`;
 
+// Stable identity for a group's open/closed state. Keyed by `key` (explicit),
+// else `label` (toggle groups always have one), else the index. Using a stable
+// key means reordering `navigation` or flipping a group's `visible` at runtime
+// keeps a manually-opened group's open state attached to the right group,
+// instead of leaking to whatever now sits at that index.
+const groupKey = (group: NavigationGroup, index: number): string =>
+  group.key ?? group.label ?? `__group_${index}`;
+
 const brandInitial = computed(() => {
   return props.title.charAt(0).toUpperCase();
 });
@@ -218,18 +263,28 @@ const isGroupToggle = (group: NavigationGroup): boolean =>
 const isGroupExpanded = (index: number, group: NavigationGroup): boolean => {
   if (props.collapsed) return true;
   if (!isGroupToggle(group)) return true;
-  return openGroups.value.has(index);
+  return openGroups.value.has(groupKey(group, index));
 };
 
-const openGroups = ref<Set<number>>(new Set());
+// Open groups tracked by stable key (see `groupKey`), not raw array index.
+const openGroups = ref<Set<string>>(new Set());
 
-const computeInitialOpenGroups = (): Set<number> => {
-  const next = new Set<number>();
+// Key of the group containing the active route, or null if none.
+const activeGroupKey = computed<string | null>(() => {
+  const index = activeGroupIndex.value;
+  if (index < 0) return null;
+  return groupKey(props.navigation[index], index);
+});
+
+const computeInitialOpenGroups = (): Set<string> => {
+  const next = new Set<string>();
   if (props.autoCollapseInactiveGroups) {
-    if (activeGroupIndex.value >= 0) next.add(activeGroupIndex.value);
+    if (activeGroupKey.value !== null) next.add(activeGroupKey.value);
   } else {
     props.navigation.forEach((group, index) => {
-      if (group.visible !== false && group.collapsible !== false) next.add(index);
+      if (group.visible !== false && group.collapsible !== false) {
+        next.add(groupKey(group, index));
+      }
     });
   }
   return next;
@@ -239,15 +294,15 @@ const computeInitialOpenGroups = (): Set<number> => {
 // no post-mount height measurement, so no open/close flicker on load.
 openGroups.value = computeInitialOpenGroups();
 
-const toggleGroup = (index: number): void => {
-  const wasOpen = openGroups.value.has(index);
+const toggleGroup = (key: string): void => {
+  const wasOpen = openGroups.value.has(key);
   if (props.autoCollapseInactiveGroups) {
-    openGroups.value = wasOpen ? new Set() : new Set([index]);
+    openGroups.value = wasOpen ? new Set() : new Set([key]);
     return;
   }
   const next = new Set(openGroups.value);
-  if (wasOpen) next.delete(index);
-  else next.add(index);
+  if (wasOpen) next.delete(key);
+  else next.add(key);
   openGroups.value = next;
 };
 
@@ -255,34 +310,34 @@ const toggleGroup = (index: number): void => {
 // it (closing others); otherwise it just adds it to the open set. No-op when
 // there is no active group (e.g. a detail page not present in the nav).
 const openActiveGroup = (): void => {
-  if (!props.collapsibleGroups || activeGroupIndex.value < 0) return;
+  if (!props.collapsibleGroups || activeGroupKey.value === null) return;
   if (props.autoCollapseInactiveGroups) {
-    openGroups.value = new Set([activeGroupIndex.value]);
+    openGroups.value = new Set([activeGroupKey.value]);
   } else {
     const next = new Set(openGroups.value);
-    next.add(activeGroupIndex.value);
+    next.add(activeGroupKey.value);
     openGroups.value = next;
   }
 };
 
 const scrollToActiveItem = async (smooth = false) => {
   await nextTick();
-  if (!sidebarRef.value) return;
-
-  const activeLink = sidebarRef.value.querySelector('.nav-link.active') as HTMLElement;
-  if (activeLink) {
-    const sidebar = sidebarRef.value;
-    const linkRect = activeLink.getBoundingClientRect();
-    const sidebarRect = sidebar.getBoundingClientRect();
-
-    // Calculate the position to scroll to (center the active item)
-    const scrollTop = activeLink.offsetTop - (sidebarRect.height / 2) + (linkRect.height / 2);
-
-    sidebar.scrollTo({
-      top: scrollTop,
-      behavior: smooth ? 'smooth' : 'instant',
-    });
-  }
+  const container = navRef.value;
+  if (!container) return;
+
+  const activeLink = container.querySelector('.nav-link.active') as HTMLElement | null;
+  if (!activeLink) return;
+
+  // Centre the active item. `offsetTop` is relative to the nav (its offset
+  // parent — `.sidebar-nav` is positioned), so it measures correctly whether or
+  // not a footer is pinned below.
+  const scrollTop =
+    activeLink.offsetTop - container.clientHeight / 2 + activeLink.offsetHeight / 2;
+
+  container.scrollTo({
+    top: scrollTop,
+    behavior: smooth ? 'smooth' : 'instant',
+  });
 };
 
 // Scroll to active item on initial mount (instant, no animation)
@@ -291,9 +346,14 @@ onMounted(() => {
 });
 
 // Client-side route change: open the newly active group, then scroll to it.
+// Scrolling into a group that was collapsed kicks off its 0.2s expand, so the
+// first scroll centres against a still-growing group; re-centre once it settles.
 watch(() => props.currentUrl, () => {
   openActiveGroup();
   scrollToActiveItem(true);
+  if (typeof window !== 'undefined') {
+    window.setTimeout(() => scrollToActiveItem(true), 250);
+  }
 });
 
 // The active group can change without a currentUrl change — e.g. navigation
@@ -312,17 +372,25 @@ watch(activeGroupIndex, () => {
   position: sticky;
   top: 0;
   height: 100vh;
-  overflow-y: auto;
-  overflow-x: hidden;
+  /* Column layout: fixed header, scrolling nav, pinned footer. */
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
   flex-shrink: 0;
 }
 
 .sidebar-header {
   display: flex;
   align-items: center;
+  flex-shrink: 0;
   border-bottom: 1px solid rgba(255, 255, 255, 0.1);
 }
 
+.sidebar-footer {
+  flex-shrink: 0;
+  border-top: 1px solid rgba(255, 255, 255, 0.1);
+}
+
 .brand-container {
   display: flex;
   align-items: center;
@@ -346,6 +414,15 @@ watch(activeGroupIndex, () => {
 }
 
 .sidebar-nav {
+  /* The nav is the scroll region (header + footer stay put). `position:
+     relative` makes it the offset parent for scroll-to-active measurements.
+     `min-height: 0` lets this flex item shrink below its content height so
+     `overflow-y: auto` actually scrolls (without it, a flex item's default
+     `min-height: auto` keeps it at content height and it overflows the rail). */
+  position: relative;
+  flex: 1 1 auto;
+  min-height: 0;
+  overflow-y: auto;
   overflow-x: hidden;
 }
 
@@ -354,6 +431,15 @@ watch(activeGroupIndex, () => {
   letter-spacing: 0.5px;
 }
 
+/* When collapsible groups are on, give the static (non-collapsible) group
+   labels the same height as the toggle headers so a sidebar mixing both keeps
+   an even vertical rhythm. */
+.sidebar-collapsible-groups .nav-group-label {
+  display: flex;
+  align-items: center;
+  min-height: 2.5rem;
+}
+
 /* Collapsible group toggle header */
 .nav-group-toggle {
   display: flex;
@@ -419,12 +505,21 @@ watch(activeGroupIndex, () => {
   display: grid;
   grid-template-rows: 0fr;
   opacity: 0;
-  transition: grid-template-rows 0.2s ease, opacity 0.2s ease;
+  /* `inert` (set in the template) removes closed links from tab order in modern
+     browsers; `visibility: hidden` is the fallback that also removes them where
+     `inert` is unsupported. Delay the visibility flip until after the fade so
+     the close animation still plays. */
+  visibility: hidden;
+  transition: grid-template-rows 0.2s ease, opacity 0.2s ease,
+    visibility 0s linear 0.2s;
 }
 
 .nav-group-open > .nav-group-items--collapsible {
   grid-template-rows: 1fr;
   opacity: 1;
+  visibility: visible;
+  transition: grid-template-rows 0.2s ease, opacity 0.2s ease,
+    visibility 0s linear 0s;
 }
 
 .nav-group-items--collapsible > .nav {
@@ -470,21 +565,21 @@ watch(activeGroupIndex, () => {
   padding: 0.625rem;
 }
 
-/* Custom scrollbar */
-.dashboard-sidebar::-webkit-scrollbar {
+/* Custom scrollbar (the nav is the scroll region) */
+.sidebar-nav::-webkit-scrollbar {
   width: 6px;
 }
 
-.dashboard-sidebar::-webkit-scrollbar-track {
+.sidebar-nav::-webkit-scrollbar-track {
   background: rgba(0, 0, 0, 0.1);
 }
 
-.dashboard-sidebar::-webkit-scrollbar-thumb {
+.sidebar-nav::-webkit-scrollbar-thumb {
   background: rgba(255, 255, 255, 0.2);
   border-radius: 3px;
 }
 
-.dashboard-sidebar::-webkit-scrollbar-thumb:hover {
+.sidebar-nav::-webkit-scrollbar-thumb:hover {
   background: rgba(255, 255, 255, 0.3);
 }