@omnitend/dashboard-for-laravel 0.34.0 → 0.35.0

package/docs/public/api-reference.json

@@ -1,8 +1,8 @@
 {
-  "generated": "2026-07-21T07:46:13.035Z",
+  "generated": "2026-07-21T12:16:47.073Z",
   "package": {
     "name": "@omnitend/dashboard-for-laravel",
-    "version": "0.34.0"
+    "version": "0.35.0"
   },
   "components": {
     "base": [
@@ -2427,7 +2427,14 @@
             "type": "union",
             "required": false,
             "default": "\"vertical\"",
-            "description": "Form-wide field layout: \"vertical\" (default, label above input) or\n\"horizontal\" (label left, input right). Overridable per-field via\n`field.layout`. A field with `span: true` always renders full-width,\nregardless of layout."
+            "description": "Form-wide field layout:\n\n- `\"vertical\"` (default) — label above input, always.\n- `\"horizontal\"` — label left, input right, always.\n- `\"auto\"` — horizontal when the form's **own container** is at least\n  `layoutThreshold` px wide, vertical below that. Container-driven, not\n  viewport-driven: a page narrowed by the dashboard sidebar, or a form\n  inside a modal, stacks even though the window is wide (which no\n  Bootstrap media query can see).\n\nOverridable per-field via `field.layout`. A field with `span: true`\nalways renders full-width, regardless of layout."
+          },
+          {
+            "name": "layoutThreshold",
+            "type": "number",
+            "required": false,
+            "default": "640",
+            "description": "Container width (px) at or above which `layout: \"auto\"` goes horizontal.\nIgnored for the explicit `\"vertical\"`/`\"horizontal\"` layouts.\n\nDefault 640, measured rather than guessed: with the default 3-column\nlabel the label's text area is `containerWidth / 4 - 18` px, so 640 gives\nit 142px — enough for a ~20-character label (\"Unit price (ex VAT)\"\nmeasures 128px at the theme's label font) to stay on one line, with the\ncontrol column still 474px. Below ~584px that label starts wrapping,\nwhich is the cramped-label symptom this exists to avoid. Raise it if your\nlabels run longer, or lower `labelCols` instead."
           },
           {
             "name": "labelCols",
@@ -3314,7 +3321,7 @@
             "type": "boolean",
             "required": false,
             "default": "true",
-            "description": "Wrap the table in a `DCard`. Defaults to `true`. Set `false` for a plain,\nborderless variant — the same header, filter row, table and pagination\nrendered directly on the page background (no card border/shadow), for\ndata-heavy admin index pages that read as busy inside a card."
+            "description": "Wrap the table in a `DCard`. Defaults to `true`. Set `false` for a plain,\nborderless variant — the same header, filter row, table and pagination\nrendered directly on the page background (no card border/shadow), for\ndata-heavy admin index pages that read as busy inside a card.\n\nThe table renders FLUSH to the card border (rows and stripes reach the\nedge) while the header and pagination stay padded, which requires the card\nto clip to its radius (`overflow: hidden`).\n\n**Consequence for slot content:** anything you render into a slot that\npositions itself OUTSIDE the card and does not teleport is clipped at the\ncard edge. Library components are unaffected — `DDropdown` teleports to\n`<body>` by default, and the column-filter menus position themselves\n`fixed` — so this only bites a hand-rolled `position: absolute` overlay\n(a custom popover in a `cell(<key>)` or `#header` slot). Teleport it, or\nuse `:card=\"false\"`. Narrowing the clip to the table region is tracked\nas #166."
           },
           {
             "name": "editFields",
@@ -3346,7 +3353,7 @@
             "type": "union",
             "required": false,
             "default": "\"horizontal\"",
-            "description": "Field layout for the edit/create modal's form, forwarded to its `DXForm`\n(\"vertical\" = label above input, \"horizontal\" = label left). Defaults to\n**\"horizontal\"** to match the Omni Tend form convention (a raw modal form\npreviously fell back to DXForm's vertical default, which looked out of\nplace next to horizontal page forms). Pass `\"vertical\"` to opt out."
+            "description": "Field layout for the edit/create modal's form, forwarded to its `DXForm`\n(\"vertical\" = label above input, \"horizontal\" = label left). Defaults to\n**\"horizontal\"** to match the Omni Tend form convention (a raw modal form\npreviously fell back to DXForm's vertical default, which looked out of\nplace next to horizontal page forms). Pass `\"vertical\"` to opt out.\n\n`\"auto\"` hands the decision to `DXForm`'s container-width observer, which\nmeasures the FORM rather than the window — so a modal narrowed by its own\nbreakpoint stacks to vertical even on a wide viewport, where a media query\nwould still report \"plenty of room\". See `useContainerWidth`."
           },
           {
             "name": "editLabelCols",
@@ -3578,6 +3585,32 @@
               }
             ]
           },
+          {
+            "name": "`head-end(${field.key})`",
+            "description": "head-end(<fieldKey>) Additive content at the end of a column's own header — a period total above a numeric column, a small badge — keeping DXTable's sort indicator and field hint. Not a `head()` override.",
+            "bindings": [
+              {
+                "name": "name",
+                "title": "binding"
+              },
+              {
+                "title": "binding",
+                "type": {
+                  "name": "object"
+                },
+                "name": "field",
+                "description": "The column's field definition."
+              },
+              {
+                "title": "binding",
+                "type": {
+                  "name": "string"
+                },
+                "name": "label",
+                "description": "The column's resolved header label."
+              }
+            ]
+          },
           {
             "name": "name",
             "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.",
@@ -3679,7 +3712,7 @@
             "name": "layout",
             "type": "union",
             "required": false,
-            "description": "Field layout forwarded to the modal's DXForm (defaults handled upstream)."
+            "description": "Field layout forwarded to the modal's DXForm (defaults handled upstream).\nIncludes `\"auto\"`, which lets the form stack to vertical when the MODAL is\nnarrow even though the viewport is wide — the container-query case a\nviewport media query cannot see."
           },
           {
             "name": "labelCols",
@@ -3991,7 +4024,7 @@
         "name": "DXTableShell",
         "category": "extended",
         "filePath": "resources/js/components/extended/DXTableShell.vue",
-        "description": "Internal chrome wrapper for `DXTable`. Renders its content either inside a `DCard` (the default) or as a plain, borderless block on the page background (`:card=\"false\"`). Extracted so `DXTable`'s ~460-line body and all its slots aren't duplicated across a card/plain `v-if`. Slots: - `#header` — the title / action row. In card mode it fills `DCard`'s header; in plain mode it renders above the table with a subtle bottom rule. - default — the table body (spinner/error/table/pagination).",
+        "description": "Internal chrome wrapper for `DXTable`. Renders its content either inside a `DCard` (the default) or as a plain, borderless block on the page background (`:card=\"false\"`). Extracted so `DXTable`'s ~460-line body and all its slots aren't duplicated across a card/plain `v-if`. Slots: - `#header` — the title / action row. In card mode it fills `DCard`'s header; in plain mode it renders above the table with a subtle bottom rule. - default — the table body (spinner/error/table/pagination). Card mode renders `DCard` in **`no-body`** mode so the table sits FLUSH against the card border. With a `.card-body` in between, a striped table's rows were inset by `--bs-card-spacer-x` (24px) and left a white gutter between the stripes and the border. Without it, DXTable's children — error alert, loading block, table, pagination — become direct children of `.card`, which is already a `flex-direction: column` container, so they still stack in order: .card (overflow: hidden) ├─ .card-header (padded by Bootstrap's card-cap padding) ├─ .table-responsive ← FLUSH │ └─ table └─ .dx-table-pagination (pads itself — see DXTablePagination.vue) Bootstrap 5 has no `.card > .table` rounding rules (that was BS4), so the clipping is done with `overflow: hidden` on the card: the flush table's square top corners then follow the card's radius whether or not a header is present. bvn's popups position `fixed` by default, so they are not clipped by it.",
         "props": [
           {
             "name": "card",

package/docs/public/docs-map.md

@@ -1,7 +1,7 @@
 # Documentation Map
 
 > Auto-generated hierarchical overview of all documentation
-> Last updated: 2026-07-21T07:46:13.078Z
+> Last updated: 2026-07-21T12:16:47.128Z
 
 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.34.0",
+  "version": "0.35.0",
   "description": "Vue 3 dashboard components for Laravel with Bootstrap Vue Next",
   "type": "module",
   "main": "./dist/dashboard-for-laravel.umd.cjs",

package/resources/css/theme.scss

@@ -313,6 +313,32 @@ $bootstrap-icons-font-src: url("bootstrap-icons/font/fonts/bootstrap-icons.woff2
   flex-wrap: nowrap;
 }
 
+// ----------------------------------------------------------------------------
+// Nav tabs
+// ----------------------------------------------------------------------------
+// Chrome recedes, content leads — the same ethos as the muted table headers
+// (#157). Bootstrap gives an INACTIVE tab `--bs-nav-link-color:
+// var(--bs-link-color)`, i.e. the saturated link-blue, so a row of tabs above a
+// form reads as a row of links competing with the fields below. Mute the
+// inactive tabs and let the ACTIVE one (Bootstrap's
+// `--bs-nav-tabs-link-active-color`, the near-black emphasis colour) carry the
+// selection on its own.
+//
+// Driven through Bootstrap's own `--bs-nav-*` variables rather than a raw
+// `color:` — so a consumer can re-louden one tab set by resetting the same
+// variable, `[data-bs-theme="dark"]` remaps the tokens for free, and Bootstrap
+// keeps ownership of the `.active`/`.disabled` resolution order.
+//
+// `--bs-secondary-color` is `rgba(var(--bs-body-color-rgb), .75)` → ~#585b5e on
+// white: 6.83:1, comfortably AA (AAA for body text); 6.53:1 on the theme's
+// `$light` #f8fafc panel. Hover goes to the full body colour (#212529, 16.1:1)
+// so hovering reads as "heading toward selected" rather than "turning into a
+// link".
+.nav-tabs {
+  --bs-nav-link-color: var(--bs-secondary-color);
+  --bs-nav-link-hover-color: var(--bs-body-color);
+}
+
 // ----------------------------------------------------------------------------
 // Dashboard Custom Styles
 // ----------------------------------------------------------------------------
@@ -433,6 +459,40 @@ $bootstrap-icons-font-src: url("bootstrap-icons/font/fonts/bootstrap-icons.woff2
     color: $secondary; // muted message text
   }
 
+  // HEADER-LESS toast (`body` but no `title` — the shape every toast created
+  // through `useToast().create({ body })` takes). BVN renders it as
+  //   .toast > .d-flex > (.toast-body + .btn-close)
+  // and BVN's own `.toast .btn-close-custom { margin: <pad> <pad> auto }` pins
+  // the close X to the TOP of that row, while the `.toast-body` above still
+  // carries the reduced `padding-top` that only makes sense when it sits under
+  // a `.toast-header`. Result: the message rides high, the X sits lower, and a
+  // one-line toast reads as misaligned.
+  //
+  // With no header there is nothing above the body, so restore symmetric
+  // padding (Bootstrap's `.toast-body` is `padding: var(--bs-toast-padding-x)`
+  // all round) and centre the row. The `margin-bottom: auto` has to go too —
+  // an auto margin outranks `align-items` in flex alignment, so centring alone
+  // would leave the X pinned; `margin-block: 0` hands alignment back to the
+  // container while keeping BVN's horizontal margin.
+  //
+  // `:has()` is the structural test — it is the only way to key off "this toast
+  // has no header" from CSS, and it is supported in every evergreen browser
+  // (Chrome/Edge 105+, Safari 15.4+, Firefox 121+). A browser without it simply
+  // keeps today's slightly-off alignment; nothing breaks.
+  &:not(:has(.toast-header)) {
+    > .d-flex {
+      align-items: center;
+    }
+
+    .toast-body {
+      padding-top: var(--bs-toast-padding-x);
+    }
+
+    .btn-close-custom {
+      margin-block: 0;
+    }
+  }
+
   // Hide the auto-dismiss countdown bar — the ticking animation reads as
   // stressful/urgent, which is wrong for a passive notification. Auto-dismiss
   // still works; only its visual indicator is removed.
@@ -530,7 +590,18 @@ $bootstrap-icons-font-src: url("bootstrap-icons/font/fonts/bootstrap-icons.woff2
   // (which sets its colours `!important` by design). `.toast` is excluded: it
   // has its own soft handling (a fainter 50%-white mix via `--bs-toast-bg` for
   // its large surface) and themed toasts don't carry `.text-bg-*` anyway.
-  .text-bg-#{$name}:not(.toast) {
+  //
+  // The exclusion is wrapped in `:where()` DELIBERATELY: `:where()` always
+  // contributes ZERO specificity, so this stays a single-class 0,1,0 selector
+  // while matching exactly what a bare `:not(.toast)` would. Written bare it is
+  // 0,2,0 — and because the declarations are `!important`, a consumer painting
+  // a fully custom badge (`.my-status-badge { background: …; }`) could not win
+  // with a single-class `!important` rule and had to escalate to a
+  // repeated-class hack. One class in, one class out: a consumer's own
+  // `!important` single-class rule now overrides us on source order, as it
+  // should. (Everything Bootstrap defines for `.text-bg-*` is also 0,1,0
+  // `!important` and is imported ABOVE this block, so we still win it.)
+  .text-bg-#{$name}:where(:not(.toast)) {
     background-color: #{$soft-bg} !important;
     color: #{$soft-text} !important;
   }
@@ -551,7 +622,14 @@ $bootstrap-icons-font-src: url("bootstrap-icons/font/fonts/bootstrap-icons.woff2
   // (danger/info's solid IS their emphasis). The variant-less default bar
   // stays `$progress-bar-bg` (brand navy). `!important` beats the `.bg-*`
   // utility, which sets its colour `!important` by design.
-  .progress-bar.bg-#{$name} {
+  //
+  // `.progress-bar` is only here to SCOPE the rule (large fills, not every
+  // `.bg-*` element), so it goes in `:where()` — zero specificity, same
+  // matching, and the selector stays 0,1,0 like Bootstrap's own `.bg-*`. Same
+  // reasoning as the `.text-bg-*` rule above: at 0,2,0 `!important` a consumer
+  // recolouring one bar had to out-specify us instead of just writing
+  // `.my-bar { background-color: … !important }`.
+  :where(.progress-bar).bg-#{$name} {
     background-color: #{$solid-bg} !important;
     color: #{$solid-text};
   }

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

@@ -426,7 +426,7 @@ watch(activeGroupIndex, () => {
   overflow-x: hidden;
 }
 
-/* Dense rhythm (#95): greendragon's cutover values, adopted as the default —
+/* Dense rhythm (#95): values proven in a production dashboard, adopted as the default —
    natural-case headers at 0.875rem (no uppercase/letter-spacing), tight group
    spacing. */
 .nav-group {

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

@@ -13,8 +13,9 @@
 -->
 <template>
     <BForm
+        ref="formRoot"
         @submit.prevent="handleSubmit"
-        :class="{ 'dx-form--horizontal': layout === 'horizontal' }"
+        :class="{ 'dx-form--horizontal': resolvedLayout === 'horizontal' }"
     >
         <!-- Form-level error message -->
         <DAlert
@@ -71,7 +72,7 @@
                             :field="field"
                             :form="resolvedForm"
                             :model="model"
-                            :layout="layout"
+                            :layout="resolvedLayout"
                             :label-cols="labelCols"
                         >
                             <!-- Forward every DXForm slot so the field can render
@@ -105,7 +106,7 @@
                     :field="field"
                     :form="resolvedForm"
                     :model="model"
-                    :layout="layout"
+                    :layout="resolvedLayout"
                     :label-cols="labelCols"
                 >
                     <!-- Forward every DXForm slot so the field can render its
@@ -166,7 +167,7 @@
 </template>
 
 <script setup lang="ts">
-import { computed, watch } from "vue";
+import { computed, ref, watch, type ComponentPublicInstance } from "vue";
 import { BForm } from "bootstrap-vue-next";
 import DAlert from "../base/DAlert.vue";
 import DButton from "../base/DButton.vue";
@@ -176,6 +177,7 @@ import { BTab as DTab } from "bootstrap-vue-next"; // raw BTab: BTabs scans slot
 import DXFormField from "./DXFormField.vue";
 import type { UseFormReturn } from "../../composables/useForm";
 import type { DefineFormReturn } from "../../composables/defineForm";
+import { useContainerWidth } from "../../composables/useContainerWidth";
 import type { FieldDefinition, FormTab, LabelCols, MaybeFn } from "../../types";
 import {
     resolvePredicate as resolvePredicateFor,
@@ -235,12 +237,34 @@ interface Props {
     cardTabs?: boolean;
 
     /**
-     * Form-wide field layout: "vertical" (default, label above input) or
-     * "horizontal" (label left, input right). Overridable per-field via
-     * `field.layout`. A field with `span: true` always renders full-width,
-     * regardless of layout.
+     * Form-wide field layout:
+     *
+     * - `"vertical"` (default) — label above input, always.
+     * - `"horizontal"` — label left, input right, always.
+     * - `"auto"` — horizontal when the form's **own container** is at least
+     *   `layoutThreshold` px wide, vertical below that. Container-driven, not
+     *   viewport-driven: a page narrowed by the dashboard sidebar, or a form
+     *   inside a modal, stacks even though the window is wide (which no
+     *   Bootstrap media query can see).
+     *
+     * Overridable per-field via `field.layout`. A field with `span: true`
+     * always renders full-width, regardless of layout.
      */
-    layout?: "vertical" | "horizontal";
+    layout?: "vertical" | "horizontal" | "auto";
+
+    /**
+     * Container width (px) at or above which `layout: "auto"` goes horizontal.
+     * Ignored for the explicit `"vertical"`/`"horizontal"` layouts.
+     *
+     * Default 640, measured rather than guessed: with the default 3-column
+     * label the label's text area is `containerWidth / 4 - 18` px, so 640 gives
+     * it 142px — enough for a ~20-character label ("Unit price (ex VAT)"
+     * measures 128px at the theme's label font) to stay on one line, with the
+     * control column still 474px. Below ~584px that label starts wrapping,
+     * which is the cramped-label symptom this exists to avoid. Raise it if your
+     * labels run longer, or lower `labelCols` instead.
+     */
+    layoutThreshold?: number;
 
     /**
      * Label column width for horizontal layout (mirrors BFormGroup's
@@ -258,6 +282,7 @@ const props = withDefaults(defineProps<Props>(), {
     card: false,
     cardTabs: true,
     layout: "vertical",
+    layoutThreshold: 640,
 });
 
 const emit = defineEmits<{
@@ -270,6 +295,55 @@ const slots = defineSlots<Record<string, (props: any) => any>>();
 /** v-model for the active tab index. */
 const activeTab = defineModel<number>("activeTab", { default: 0 });
 
+// ————————————————— container-driven layout (`layout: "auto"`)
+
+const formRoot = ref<ComponentPublicInstance | HTMLElement | null>(null);
+
+/**
+ * The `<form>` element BForm renders. A template ref on a component yields the
+ * component instance, so unwrap `$el` — and tolerate either shape rather than
+ * assuming one, so a future BForm change (or a functional re-implementation)
+ * can't silently leave us observing nothing.
+ */
+function resolveFormElement(): HTMLElement | null {
+    const rootValue = formRoot.value;
+    if (rootValue === null || rootValue === undefined) return null;
+    if (rootValue instanceof HTMLElement) return rootValue;
+    const element = (rootValue as ComponentPublicInstance).$el;
+    return element instanceof HTMLElement ? element : null;
+}
+
+// Observe ONLY in auto mode. Returning null for the other layouts means no
+// ResizeObserver is ever attached for the (overwhelmingly common) explicit
+// layouts — existing consumers pay nothing and behave identically.
+const { isBelow: containerIsNarrow } = useContainerWidth(
+    () => (props.layout === "auto" ? resolveFormElement() : null),
+    {
+        // Getter, so a consumer binding `:layout-threshold` to something
+        // reactive re-evaluates instead of latching the mount-time value.
+        threshold: () => props.layoutThreshold,
+        // Guard against an observer feedback loop at the boundary: the vertical
+        // layout is TALLER, so a form inside an `overflow:auto` ancestor can
+        // gain a scrollbar when it stacks, shrinking its own container by
+        // ~15-17px — straight back over the threshold, and it flips forever.
+        // A band wider than any scrollbar (24px) makes the crossing one-way
+        // until the container genuinely grows.
+        hysteresis: 24,
+    },
+);
+
+/**
+ * The layout actually rendered. `vertical`/`horizontal` pass through
+ * unconditionally (unchanged behaviour); `auto` resolves from the measured
+ * container width, defaulting to `vertical` before the first measurement and
+ * under SSR — the stacked layout is legible at any width, so it is the safe
+ * thing to render when the width is unknown.
+ */
+const resolvedLayout = computed<"vertical" | "horizontal">(() => {
+    if (props.layout !== "auto") return props.layout;
+    return containerIsNarrow.value ? "vertical" : "horizontal";
+});
+
 // ————————————————— resolve form / fields (accept useForm or defineForm)
 
 function isDefineForm(