@omnitend/dashboard-for-laravel 0.21.0 → 0.23.0

package/dist/types/index.d.ts

@@ -231,6 +231,29 @@ export interface FieldDefinition {
      * applied as `disabled`.
      */
     readonly?: MaybeFn<boolean>;
+    /**
+     * Display the value as static text instead of a control — no border, no
+     * input box (Bootstrap's `.form-control-plaintext`). For values a
+     * profile/settings page shows but never lets you edit, where a `readonly`
+     * input still reads as "you could edit this, but can't".
+     *
+     * Implies read-only, for every field type. Anything backed by a real input
+     * — the text family, textarea, currency, percentage, autocomplete — renders
+     * as static text; control types with no native readonly state
+     * (select/radio/checkbox/switch/file) are disabled instead, exactly as they
+     * are for `readonly`.
+     *
+     * Enforced over `inputProps`: unlike the field's other bindings, which
+     * `inputProps` may override, a plaintext field cannot be made editable
+     * again through it.
+     */
+    plaintext?: MaybeFn<boolean>;
+    /**
+     * Only for `type: "password"`. Show the reveal (eye) toggle that switches
+     * the input between masked and plain text. Defaults to `true` — set
+     * `false` to render a bare password input.
+     */
+    revealable?: boolean;
     /**
      * Conditionally show or hide this field. When omitted the field is
      * always visible. Boolean or a function of the form model; evaluated

package/dist/types/navigation.d.ts

@@ -28,3 +28,16 @@ export interface NavigationGroup {
     visible?: boolean;
 }
 export type Navigation = NavigationGroup[];
+/**
+ * Horizontal alignment of the navbar search slot content within its region:
+ * `"start"` = flush left (after the title from `md` up), `"center"` = centred.
+ * Shared by DXDashboard (which forwards it) and DXDashboardNavbar.
+ */
+export type NavbarSearchAlign = "start" | "center";
+/**
+ * What the navbar actions slot does below the `md` breakpoint: `"wrap"` moves
+ * it to its own full-width row (the bar grows), `"hide"` removes it entirely
+ * (for apps that relocate page actions into the page on phones).
+ * Shared by DXDashboard (which forwards it) and DXDashboardNavbar.
+ */
+export type NavbarActionsOnMobile = "wrap" | "hide";

package/docs/public/api-reference.json

@@ -1,8 +1,8 @@
 {
-  "generated": "2026-07-10T09:19:45.286Z",
+  "generated": "2026-07-11T08:44:15.505Z",
   "package": {
     "name": "@omnitend/dashboard-for-laravel",
-    "version": "0.19.2"
+    "version": "0.22.0"
   },
   "components": {
     "base": [
@@ -1394,7 +1394,14 @@
             "name": "fluid",
             "type": "boolean",
             "required": false,
-            "description": "Render the page content full-width and left-aligned instead of the default\ncentred, reading-width (`col-xl-10`) column. Use for data-heavy admin pages\n(wide tables)."
+            "description": "Render the page content full-width and left-aligned instead of the default\ncentred, reading-width column. Use for data-heavy admin pages (wide tables)."
+          },
+          {
+            "name": "contentMaxWidth",
+            "type": "string",
+            "required": false,
+            "default": "'1140px'",
+            "description": "Max width of the centred content column (any CSS length). A genuine cap, so\nforms and text-heavy pages don't stretch to ~2000px on a wide display.\nIgnored when `fluid`. Set a large value (or use `fluid`) for full width."
           },
           {
             "name": "contentClass",
@@ -1410,11 +1417,18 @@
             "description": "User object for navbar dropdown"
           },
           {
-            "name": "logoutUrl",
-            "type": "string",
+            "name": "searchAlign",
+            "type": "NavbarSearchAlign",
             "required": false,
-            "default": "'/logout'",
-            "description": "Logout URL for navbar dropdown"
+            "default": "'start'",
+            "description": "Horizontal alignment of the navbar search slot content (`\"start\"` = flush\nleft, `\"center\"` = centred), forwarded to DXDashboardNavbar."
+          },
+          {
+            "name": "actionsOnMobile",
+            "type": "NavbarActionsOnMobile",
+            "required": false,
+            "default": "'wrap'",
+            "description": "What the navbar actions slot does below `md`: `\"wrap\"` to its own\nfull-width row, `\"hide\"` to remove it (relocate actions into the page on\nphones). Forwarded to DXDashboardNavbar."
           },
           {
             "name": "collapsibleGroups",
@@ -1454,6 +1468,22 @@
               {
                 "name": "name",
                 "title": "binding"
+              },
+              {
+                "title": "binding",
+                "type": {
+                  "name": "function"
+                },
+                "name": "toggleSidebar",
+                "description": "Shows/hides the sidebar."
+              },
+              {
+                "title": "binding",
+                "type": {
+                  "name": "boolean"
+                },
+                "name": "sidebarHidden",
+                "description": "Whether the sidebar is currently hidden."
               }
             ]
           },
@@ -1469,7 +1499,7 @@
         "name": "DXDashboardNavbar",
         "category": "extended",
         "filePath": "resources/js/components/extended/DXDashboardNavbar.vue",
-        "description": "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.",
+        "description": "Top navigation bar for the dashboard shell: menu toggle, page title, search (aligned per `searchAlign`, left by default), page-level actions, and the user menu. Usually rendered by `DXDashboard`, which forwards these slots with a `navbar-` prefix.",
         "props": [
           {
             "name": "user",
@@ -1484,6 +1514,20 @@
             "required": false,
             "default": "\"\"",
             "description": "Page title shown at the left of the navbar (hidden below the `md` breakpoint)."
+          },
+          {
+            "name": "searchAlign",
+            "type": "NavbarSearchAlign",
+            "required": false,
+            "default": "\"start\"",
+            "description": "Horizontal alignment of the search slot content within its region\n(`\"start\"` = flush left, `\"center\"` = centred). Applies at every size:\nthe region sits inline after the title from `md` up, and is its own\nfull-width row below."
+          },
+          {
+            "name": "actionsOnMobile",
+            "type": "NavbarActionsOnMobile",
+            "required": false,
+            "default": "\"wrap\"",
+            "description": "What the actions slot does below the `md` breakpoint: `\"wrap\"` moves it\nto its own full-width row (the bar grows), `\"hide\"` removes it entirely\n(for apps that relocate page actions into the page on phones)."
           }
         ],
         "events": [
@@ -1501,12 +1545,12 @@
           },
           {
             "name": "search",
-            "description": "Search input or component. Centred in the bar on wider screens; drops to its own full-width row below the `md` breakpoint.",
+            "description": "Search input or component. Aligned per `searchAlign` within its region (inline in the bar from `md` up; its own full-width row below).",
             "bindings": []
           },
           {
             "name": "actions",
-            "description": "Page-level primary actions (e.g. a Create button), right-aligned next to the user menu.",
+            "description": "Page-level primary actions (e.g. a Create button). Right-aligned next to the user menu from `md` up; below, wraps to its own full-width row or is hidden entirely per `actionsOnMobile`.",
             "bindings": [
               {
                 "title": "binding",
@@ -1534,7 +1578,7 @@
           },
           {
             "name": "user-icon",
-            "description": "Custom user avatar/icon in the dropdown trigger.",
+            "description": "Custom user avatar/icon in the dropdown trigger. To decorate the default avatar (e.g. add a notification dot) rather than replace it, render `DXUserAvatar` — the same component used here, so the styling comes with it.",
             "bindings": [
               {
                 "title": "binding",
@@ -1543,6 +1587,14 @@
                 },
                 "name": "initial",
                 "description": "The first letter of the user's name."
+              },
+              {
+                "title": "binding",
+                "type": {
+                  "name": "object"
+                },
+                "name": "user",
+                "description": "The signed-in user."
               }
             ]
           },
@@ -1767,7 +1819,7 @@
         "name": "DXField",
         "category": "extended",
         "filePath": "resources/js/components/extended/DXField.vue",
-        "description": "Renders a single `FieldDefinition` of any type (text, select, autocomplete, checkbox, switch, repeater, currency, percentage, file/image, component, etc.) with its label, validation error, hint and help. Used by `DXForm` and `DXTable`'s edit modal; exposes `value`, `span`, `info`, `hint` and `repeater-row` slots for per-field customisation.",
+        "description": "Renders a single `FieldDefinition` of any type (text, select, autocomplete, checkbox, switch, repeater, currency, percentage, file/image, component, etc.) with its label, validation error, hint and help. Used by `DXForm` and `DXTable`'s edit modal; exposes `value`, `span`, `info`, `info-popover`, `hint` and `repeater-row` slots for per-field customisation.",
         "props": [
           {
             "name": "field",
@@ -1968,7 +2020,13 @@
           }
         ],
         "events": [],
-        "slots": [],
+        "slots": [
+          {
+            "name": "popover",
+            "description": "Rich popover body. Overrides the plain `info` text — use",
+            "bindings": []
+          }
+        ],
         "methods": []
       },
       {
@@ -2823,6 +2881,39 @@
             "required": false,
             "description": "API endpoint for creating new items (e.g., \"/api/products\") — enables \"New\" button"
           },
+          {
+            "name": "showCreateButton",
+            "type": "boolean",
+            "required": false,
+            "default": "true",
+            "description": "Render the built-in \"New {item}\" button in the card header (default\n`true` whenever `createUrl` is set). Set `false` to drive the create\nmodal from your own trigger elsewhere — e.g. a button in the dashboard\nnavbar's actions slot calling the exposed `openCreate()`. With no\n`title` and no `header` slot, the header is then dropped entirely\nrather than left empty."
+          },
+          {
+            "name": "footClone",
+            "type": "boolean",
+            "required": false,
+            "default": "false",
+            "description": "Render a `<tfoot>` mirroring the header row, so `#foot(<key>)` slots can\nhold per-column totals that line up under their data (#99). Without it\nthere is no footer to put them in. For a fully custom footer, use the\n`custom-foot` slot instead."
+          },
+          {
+            "name": "showEmpty",
+            "type": "boolean",
+            "required": false,
+            "default": "true",
+            "description": "Show a message row when there are no rows (default `true`). An empty\ntable body is indistinguishable from a broken one, so the message is on\nby default. Override the wording with `emptyText`, or the whole row with\nthe `empty` slot."
+          },
+          {
+            "name": "emptyText",
+            "type": "string",
+            "required": false,
+            "description": "Message shown when there are no rows. Defaults to \"No {items} found\", or\n\"No {items} match your filters\" when a column filter is active."
+          },
+          {
+            "name": "expandedItems",
+            "type": "Array",
+            "required": false,
+            "description": "Rows currently expanded, as a `v-model`. Pair with the `row-expansion`\nslot to render detail content under a row (#112) instead of forcing every\nper-row detail into a modal."
+          },
           {
             "name": "clientSide",
             "type": "boolean",
@@ -2891,6 +2982,11 @@
             "description": "`v-model:sortBy` update, emitted with the normalized single-column sort array when sorting changes.",
             "properties": []
           },
+          {
+            "name": "update:expandedItems",
+            "description": "`v-model:expandedItems` update, emitted with the rows currently expanded.",
+            "properties": []
+          },
           {
             "name": "update:filters",
             "description": "`v-model:filters` update, emitted with the new filter map when a column filter changes.",
@@ -2915,7 +3011,7 @@
           },
           {
             "name": "name",
-            "description": "Custom rendering for a column's cell. Name it `cell(<fieldKey>)` to target a field; receives the underlying table cell scope.",
+            "description": "Any slot the underlying table supports, forwarded with its scope: `cell(<fieldKey>)` for a cell, `foot(<fieldKey>)` for a footer cell (needs `footClone`), `empty` for the no-rows message, `row-expansion` for expandable row detail, plus `custom-foot`, `top-row`, `bottom-row`, `thead-sub` and the `table-*` slots.",
             "bindings": [
               {
                 "name": "name",
@@ -3116,12 +3212,64 @@
           }
         ],
         "methods": []
+      },
+      {
+        "name": "DXUserAvatar",
+        "category": "extended",
+        "filePath": "resources/js/components/extended/DXUserAvatar.vue",
+        "description": "The circular user avatar shown in the dashboard navbar's user menu: a single initial on a solid disc, with an optional notification dot. It exists as its own component because `DXDashboardNavbar`'s `user-icon` slot is one consumers routinely *decorate* rather than replace — adding an unread badge, wrapping it in a link. The navbar's styles are scoped, so slot content (compiled in the consumer's scope) can't reuse them; without this component every override starts by re-implementing the avatar's CSS, which then drifts from the theme. Rendering it here means an override is one line and stays on theme.",
+        "props": [
+          {
+            "name": "user",
+            "type": "union",
+            "required": false,
+            "default": "null",
+            "description": "The user whose initial is shown. The first letter of `name` is used."
+          },
+          {
+            "name": "initial",
+            "type": "string",
+            "required": false,
+            "default": "\"\"",
+            "description": "Overrides the initial derived from `user.name` (e.g. two-letter initials)."
+          },
+          {
+            "name": "badge",
+            "type": "boolean",
+            "required": false,
+            "default": "false",
+            "description": "Show a notification dot on the avatar (e.g. unread updates)."
+          },
+          {
+            "name": "badgeVariant",
+            "type": "ColorVariant",
+            "required": false,
+            "default": "\"danger\"",
+            "description": "Colour of the notification dot."
+          },
+          {
+            "name": "badgeLabel",
+            "type": "string",
+            "required": false,
+            "default": "\"Unread notifications\"",
+            "description": "Accessible text for the notification dot, announced to screen readers\n(the dot itself is a colour-only signal). Ignored unless `badge` is set."
+          }
+        ],
+        "events": [],
+        "slots": [
+          {
+            "name": "default",
+            "description": "Replaces the initial inside the disc (e.g. a photo or an icon).",
+            "bindings": []
+          }
+        ],
+        "methods": []
       }
     ]
   },
   "stats": {
-    "totalComponents": 73,
+    "totalComponents": 74,
     "baseComponents": 57,
-    "extendedComponents": 16
+    "extendedComponents": 17
   }
 }

package/docs/public/docs-map.md

@@ -1,7 +1,7 @@
 # Documentation Map
 
 > Auto-generated hierarchical overview of all documentation
-> Last updated: 2026-07-10T09:19:45.350Z
+> Last updated: 2026-07-11T08:44:15.559Z
 
 This file provides a complete map of all available documentation for AI agents and developers.
 
@@ -82,6 +82,7 @@ This file provides a complete map of all available documentation for AI agents a
 - [DXStatCard](/components/extended/DXStatCard): A KPI / stat tile: a big formatted value with a title, optional subtitle, an
 - [DXSwitch](/components/extended/DXSwitch): A "filled box" toggle switch built on `DFormCheckbox`: a bordered box sized like
 - [DXTable](/components/extended/DXTable): A comprehensive data table component with built-in pagination, sorting, filtering, and CRUD operatio
+- [DXUserAvatar](/components/extended/DXUserAvatar): The circular user avatar shown in the dashboard navbar's user menu: a single
 
 ### Examples
 
@@ -100,4 +101,4 @@ This file provides a complete map of all available documentation for AI agents a
 
 ---
 
-**Total Pages**: 76
+**Total Pages**: 77

package/docs/public/llms.txt

@@ -2,7 +2,7 @@
 
 > Vue 3 dashboard components for Laravel with Bootstrap Vue Next
 >
-> A dual-package library (NPM + Composer) providing 68 Vue 3 components for building Laravel dashboards with Bootstrap Vue Next.
+> A dual-package library (NPM + Composer) providing 69 Vue 3 components for building Laravel dashboards with Bootstrap Vue Next.
 
 ## Installation
 
@@ -81,7 +81,7 @@ Lightweight type-safe wrappers around Bootstrap Vue Next components providing AP
 - [DToaster](/components/base/dtoaster): Bootstrap Vue Next Toaster wrapper
 - [DTooltip](/components/base/dtooltip): Bootstrap Vue Next Tooltip wrapper
 
-## Extended Components (11 components)
+## Extended Components (12 components)
 
 Custom dashboard components with advanced functionality beyond Bootstrap Vue Next.
 
@@ -96,6 +96,7 @@ Custom dashboard components with advanced functionality beyond Bootstrap Vue Nex
 - [DXStatCard](/components/extended/dxstatcard): Extended dashboard component
 - [DXSwitch](/components/extended/dxswitch): Extended dashboard component
 - [DXTable](/components/extended/dxtable): Data table with pagination, filtering, and sorting
+- [DXUserAvatar](/components/extended/dxuseravatar): Extended dashboard component
 
 ## Composables
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omnitend/dashboard-for-laravel",
-  "version": "0.21.0",
+  "version": "0.23.0",
   "description": "Vue 3 dashboard components for Laravel with Bootstrap Vue Next",
   "type": "module",
   "main": "./dist/dashboard-for-laravel.umd.cjs",
@@ -31,8 +31,11 @@
     "dev": "vite build --watch",
     "build": "vite build && vue-tsc --declaration --emitDeclarationOnly --outDir dist",
     "typecheck": "vue-tsc --noEmit",
+    "pretest": "vite build",
     "test": "vitest",
+    "pretest:ui": "vite build",
     "test:ui": "vitest --ui",
+    "pretest:headless": "vite build",
     "test:headless": "vitest --run --browser.headless",
     "docs:dev": "astro dev",
     "docs:build": "npm run docs:generate:ai && astro build",

package/resources/css/theme.scss

@@ -287,11 +287,26 @@ $bootstrap-icons-font-src: url("bootstrap-icons/font/fonts/bootstrap-icons.woff2
 }
 
 .dashboard-navbar {
-  height: $dashboard-navbar-height;
+  // Floor, not a fixed height: below `md` the search (and actions) drop to
+  // their own rows and the bar must grow to contain them (#93). Single-row
+  // content is shorter than this, so desktop stays exactly this height,
+  // aligned with the sidebar header.
+  min-height: $dashboard-navbar-height;
   // A light grey top bar over the white content panel (higher contrast than a
   // grey-everywhere layout). The navbar markup drops its `bg-white` class so
   // this wins without `!important`.
-  background-color: #f8f9fa;
+  background-color: var(--bs-light);
+}
+
+// The avatar dropdown trigger (DXDashboardNavbar sets this via toggle-class,
+// so it lands on the BVN-rendered button — global rule, scoped CSS can't
+// reach it). The themed $btn-padding-y (10px) would make it ~54px tall and
+// blow the navbar's single-row content budget: 64px header minus the bar's
+// 16px padding = 48px. 6px keeps a ~46px tap target (≥ the 44px WCAG
+// guideline) while still fitting the budget.
+.dashboard-navbar__user-menu-toggle {
+  padding-top: 0.375rem;
+  padding-bottom: 0.375rem;
 }
 
 // ----------------------------------------------------------------------------

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

@@ -25,8 +25,17 @@
         :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" />
+        <!--
+          @slot Forwards any `sidebar-*` slot to DXDashboardSidebar with the `sidebar-` prefix stripped (e.g. `sidebar-brand` becomes the sidebar's `brand` slot).
+          @binding {function} toggleSidebar Shows/hides the sidebar — so slot content (e.g. a close affordance in the brand row) can drive it.
+          @binding {boolean} sidebarHidden Whether the sidebar is currently hidden.
+        -->
+        <slot
+          :name="originalName"
+          v-bind="slotProps"
+          :toggleSidebar="toggleSidebar"
+          :sidebarHidden="hidden"
+        />
       </template>
     </DXDashboardSidebar>
 
@@ -36,7 +45,8 @@
       <DXDashboardNavbar
         :page-title="pageTitle"
         :user="user"
-        :logout-url="logoutUrl"
+        :search-align="searchAlign"
+        :actions-on-mobile="actionsOnMobile"
         @toggle-sidebar="toggleSidebar"
       >
         <!-- Dynamically forward all navbar-* slots by stripping the prefix -->
@@ -45,8 +55,17 @@
           :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" />
+          <!--
+            @slot Forwards any `navbar-*` slot to DXDashboardNavbar with the `navbar-` prefix stripped (e.g. `navbar-actions` becomes the navbar's `actions` slot).
+            @binding {function} toggleSidebar Shows/hides the sidebar.
+            @binding {boolean} sidebarHidden Whether the sidebar is currently hidden.
+          -->
+          <slot
+            :name="originalName"
+            v-bind="slotProps"
+            :toggleSidebar="toggleSidebar"
+            :sidebarHidden="hidden"
+          />
         </template>
       </DXDashboardNavbar>
 
@@ -80,10 +99,16 @@ import DXDashboardNavbar from './DXDashboardNavbar.vue';
 import DContainer from '../base/DContainer.vue';
 import DRow from '../base/DRow.vue';
 import DCol from '../base/DCol.vue';
-import type { Navigation } from '../../types/navigation';
+import type { Navigation, NavbarActionsOnMobile, NavbarSearchAlign } from '../../types/navigation';
 
 const slots = useSlots();
 
+// Slot-binding precedence: the forwarded slots bind the child's own slot props
+// FIRST and `toggleSidebar`/`sidebarHidden` after, so ours win a name clash.
+// That's deliberate — the dashboard guarantees those two bindings on every
+// forwarded slot, and a child that later grew a same-named prop must not be
+// able to silently take the guarantee away. No child uses those names today.
+
 interface Props {
   /** Navigation structure for sidebar */
   navigation: Navigation;
@@ -116,8 +141,18 @@ interface Props {
   /** User object for navbar dropdown */
   user?: { name: string; email: string } | null;
 
-  /** Logout URL for navbar dropdown */
-  logoutUrl?: string;
+  /**
+   * Horizontal alignment of the navbar search slot content (`"start"` = flush
+   * left, `"center"` = centred), forwarded to DXDashboardNavbar.
+   */
+  searchAlign?: NavbarSearchAlign;
+
+  /**
+   * What the navbar actions slot does below `md`: `"wrap"` to its own
+   * full-width row, `"hide"` to remove it (relocate actions into the page on
+   * phones). Forwarded to DXDashboardNavbar.
+   */
+  actionsOnMobile?: NavbarActionsOnMobile;
 
   /**
    * Turn sidebar group headers into accordion toggles that collapse/expand
@@ -147,12 +182,13 @@ const props = withDefaults(defineProps<Props>(), {
   title: 'Dashboard',
   pageTitle: '',
   user: null,
-  logoutUrl: '/logout',
   collapsibleGroups: false,
   autoCollapseInactiveGroups: true,
   storageKey: 'dashboard-sidebar-hidden',
   dashboardId: '',
   contentMaxWidth: '1140px',
+  searchAlign: 'start',
+  actionsOnMobile: 'wrap',
 });
 
 const collapsed = ref(false);
@@ -240,12 +276,26 @@ const toggleSidebar = () => {
     console.error('Error saving sidebar state:', error);
   }
 };
+
+defineExpose({
+  /**
+   * Show/hide the sidebar (same as clicking the navbar's hamburger). The
+   * dashboard owns the visibility state, so this is the supported way to drive
+   * it from outside — page content, a custom brand row, a keyboard shortcut.
+   * Also available as a slot binding on every forwarded `sidebar-*`/`navbar-*`
+   * slot, which is usually more convenient.
+   */
+  toggleSidebar,
+
+  /** Whether the sidebar is currently hidden. */
+  sidebarHidden: computed(() => hidden.value),
+});
 </script>
 
 <style scoped>
 .dashboard-layout {
   min-height: 100vh;
-  background-color: #f8f9fa;
+  background-color: var(--bs-light);
 }
 
 .dashboard-content {
@@ -259,6 +309,6 @@ const toggleSidebar = () => {
   max-width: 100%;
   /* A white content panel under the light grey top bar / layout, so forms and
      content sit on white (higher contrast than a grey-everywhere dashboard). */
-  background-color: #fff;
+  background-color: var(--bs-white);
 }
 </style>