@omnitend/dashboard-for-laravel 0.40.0 → 0.41.1

package/docs/public/api-reference.json

@@ -1,8 +1,8 @@
 {
-  "generated": "2026-08-25T19:01:45.537Z",
+  "generated": "2026-09-27T10:14:02.393Z",
   "package": {
     "name": "@omnitend/dashboard-for-laravel",
-    "version": "0.40.0"
+    "version": "0.41.1"
   },
   "components": {
     "base": [
@@ -246,6 +246,13 @@
             "required": false,
             "description": "Leading Bootstrap Icons glyph name, rendered as `<i class=\"bi bi-{icon}\">`.\ne.g. `icon=\"save\"`. Hidden while the loading spinner is visible.\n\nDiverges from bvn: `BButton`'s native `icon` is a `boolean` (icon-button\nstyling mode). We redefine it as a glyph-name `string`, so bvn's boolean\nicon mode is unreachable through `DButton`. See DIVERGENCES.md."
           },
+          {
+            "name": "iconOnly",
+            "type": "boolean",
+            "required": false,
+            "default": "false",
+            "description": "Square icon control at the same height as a normal button of this size.\nUse `icon` or an icon in the default slot, and provide `aria-label`.\nTakes precedence over `block`. While loading, the spinner replaces the\nicon/slot without changing dimensions; `loadingText` is not shown."
+          },
           {
             "name": "block",
             "type": "boolean",
@@ -3072,7 +3079,7 @@
         "name": "DXSwitch",
         "category": "extended",
         "filePath": "resources/js/components/extended/DXSwitch.vue",
-        "description": "DXSwitch — a \"filled box\" toggle switch. An opinionated switch built on `DFormCheckbox` (`switch`): a bordered box sized like a `.form-control` with the label on the left and the toggle on the right, colour-coding its state. By default (`onVariant=\"success\"`) it reads the house green-on / red-off style — a neutral box + red toggle when off, a soft-green box + green toggle when on. `onVariant=\"neutral\"` (brand primary on / grey off) is for semantically-mixed switches that shouldn't imply good/bad (#158). Used standalone or, internally, by `DXField`'s `switch` field type so a form switch and a lone switch share one look. Usage: ```vue <DXSwitch v-model=\"isCurrent\" label=\"Product is current\" /> ``` For a form field, prefer a `DXField`/`DXForm` `type: 'switch'`; reach for `DXSwitch` directly when you want the styled toggle outside a form. Pass a `label` prop for simple text, or the default slot for richer label content.",
+        "description": "DXSwitch — a \"filled box\" toggle switch. An opinionated switch built on `DFormCheckbox` (`switch`): a bordered box sized like a `.form-control` with the label on the left and the toggle on the right, colour-coding its state. By default (`onVariant=\"success\"`) it reads the house green-on / red-off style: a light-red box with a grey toggle when off, a soft-green box with a muted green-grey toggle when on. `onVariant=\"neutral\"` (brand primary on / grey off) is for semantically-mixed switches that shouldn't imply good/bad (#158). Used standalone or, internally, by `DXField`'s `switch` field type so a form switch and a lone switch share one look. Usage: ```vue <DXSwitch v-model=\"isCurrent\" label=\"Product is current\" /> ``` For a form field, prefer a `DXField`/`DXForm` `type: 'switch'`; reach for `DXSwitch` directly when you want the styled toggle outside a form. Pass a `label` prop for simple text, or the default slot for richer label content.",
         "props": [
           {
             "name": "modelValue",
@@ -3433,7 +3440,7 @@
             "name": "saveGuard",
             "type": "TSFunctionType",
             "required": false,
-            "description": "Guard run when the modal's Save/Create is clicked, before the request.\nReturn a message to abort the save — it is shown immediately (as a toast)\nand no request is made; return `null`/`undefined` to proceed. Covers both\nthe `editUrl` and `createUrl` paths.\n\nAWAITED (as `deleteGuard` is), so it may return a promise: the case it\nexists for is an async control in an `edit-value` slot — an image\nupload — that has not finished when Save is clicked. Without the guard the\nform submits the previous media map, the save SUCCEEDS, the toast says\nsaved and the modal closes: the image is lost with no error anywhere,\nbecause every individual step worked. Await the upload here and the save\nsimply waits for it.\n\n`item` is the row being edited, `null` in create mode (as in the\n`edit-value` slot's binding); `data` is the live form data. Aborting\nleaves the modal open with the user's edits intact. A guard that throws\nalso aborts, surfacing its message."
+            "description": "Guard run when the modal's Save/Create is clicked, before the request.\nReturn a message to abort the save — it is shown immediately (as a toast)\nand no request is made; return `null`/`undefined` to proceed. Covers both\nthe `editUrl` and `createUrl` paths.\n\nAWAITED (as `deleteGuard` is), so it may return a promise: the case it\nexists for is an async control in an `edit-value` slot — an image\nupload — that has not finished when Save is clicked. Without the guard the\nform submits the previous media map, the save SUCCEEDS, the toast says\nsaved and the modal closes: the image is lost with no error anywhere,\nbecause every individual step worked. Await the upload here and the save\nsimply waits for it.\n\n`item` is the row being edited, `null` in create mode (as in the\n`edit-value` slot's binding); `data` is the live form data. Aborting\nleaves the modal open with the user's edits intact. A guard that throws\nalso aborts, surfacing its message.\n\nDismissing the modal while the guard is still pending — by any route —\nabandons the save; nothing is written for a record the user has closed."
           },
           {
             "name": "createUrl",
@@ -3596,7 +3603,7 @@
           },
           {
             "name": "thead-top",
-            "description": "A row rendered ABOVE the column headers — a grouped-column banner (a `<th colspan>` spanning several columns), or a pinned totals row. Renders above DXTable's own filter row. Give it `<tr>`s.",
+            "description": "Rows above the column headers, such as grouped-column banners or pinned totals. Give it `<tr>`s.",
             "bindings": [
               {
                 "title": "binding",
@@ -3616,6 +3623,20 @@
               }
             ]
           },
+          {
+            "name": "thead-sub",
+            "description": "",
+            "bindings": [
+              {
+                "name": "field",
+                "title": "binding"
+              },
+              {
+                "name": "v-bind",
+                "title": "binding"
+              }
+            ]
+          },
           {
             "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.",

package/docs/public/docs-map.md

@@ -1,7 +1,7 @@
 # Documentation Map
 
 > Auto-generated hierarchical overview of all documentation
-> Last updated: 2026-08-25T19:01:45.587Z
+> Last updated: 2026-09-27T10:14:02.445Z
 
 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.40.0",
+  "version": "0.41.1",
   "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

@@ -100,20 +100,12 @@ $btn-padding-x-lg: 1.5rem; // 24px
 // Forms
 // ----------------------------------------------------------------------------
 
-$input-padding-y: 0.375rem; // compact fields (Bootstrap's default; 0.625rem read oversized)
+// Inputs, selects, input-group labels and buttons share one height at each
+// size. Otherwise adding a button stretches a default input group by 8px.
+$input-padding-y: $btn-padding-y;
 $input-padding-x: 1rem;
-
-// Match the sm/lg INPUT vertical padding to the sm/lg BUTTON padding above
-// (PO18). Bootstrap sizes every child of an `.input-group-sm`/`-lg` — buttons
-// INCLUDED — with the INPUT's sized padding, so leaving these at Bootstrap's
-// defaults (0.25rem / 0.5rem) made a sized input-group sit ~8px / ~4px shorter
-// than a `.btn-sm`/`.btn-lg` beside it. Aligning them makes sized controls share
-// one height by construction. NB: the BASE `$input-padding-y` (0.375rem) stays
-// deliberately more compact than `$btn-padding-y` (0.625rem) — see the comment
-// above ("0.625rem read oversized"); only the SIZED variants are equalised,
-// because those are the ones whose padding Bootstrap leaks onto grouped buttons.
-$input-padding-y-sm: 0.5rem; // == $btn-padding-y-sm (was Bootstrap's 0.25rem)
-$input-padding-y-lg: 0.75rem; // == $btn-padding-y-lg (was Bootstrap's 0.5rem)
+$input-padding-y-sm: $btn-padding-y-sm;
+$input-padding-y-lg: $btn-padding-y-lg;
 $input-border-radius: $border-radius;
 $input-border-color: #d1d5db; // Gray-300
 $input-focus-border-color: $primary;
@@ -288,6 +280,7 @@ $bootstrap-icons-font-src: url("bootstrap-icons/font/fonts/bootstrap-icons.woff2
 // and expose it as a var so such components can reference the single source
 // of truth instead of duplicating the formula.
 :root {
+  --d-input-border-color: #{$input-border-color};
   // $input-border-width resolves to a CSS var() (Bootstrap 5.3+), which Sass
   // can't multiply directly — fold the *2 into the calc() itself instead.
   --dx-input-height: calc(
@@ -295,6 +288,16 @@ $bootstrap-icons-font-src: url("bootstrap-icons/font/fonts/bootstrap-icons.woff2
   );
 }
 
+// Bootstrap sizes grouped buttons with padding properties, but leaves their
+// padding variables unchanged. Keep computed icon-only dimensions in sync.
+.input-group-sm > .btn {
+  --bs-btn-padding-y: #{$input-padding-y-sm};
+}
+
+.input-group-lg > .btn {
+  --bs-btn-padding-y: #{$input-padding-y-lg};
+}
+
 // Horizontal ("label-left") forms: a compact settings-form rhythm, with the
 // label + control top-aligned so a checkbox/switch sits on the label's first
 // line rather than floating above it (the label column carries a top offset to
@@ -305,12 +308,8 @@ $bootstrap-icons-font-src: url("bootstrap-icons/font/fonts/bootstrap-icons.woff2
     align-items: flex-start;
   }
 
-  .col-form-label {
-    padding-top: 0.4rem;
-  }
-
   .form-check {
-    margin-top: 0.4rem;
+    margin-top: calc(#{$input-padding-y} + #{$input-border-width});
   }
 
   .mb-3 {
@@ -689,6 +688,12 @@ $bootstrap-icons-font-src: url("bootstrap-icons/font/fonts/bootstrap-icons.woff2
 // independent of the sort indicator's presence. Scoped to `.table > thead` so a
 // consumer who genuinely wants bottom-aligned headers can still opt back in on a
 // specific table.
+// Body cells inherit this alignment; explicit .align-top remains available
+// on a table, row or cell for long-form content that needs top alignment.
+.table {
+  vertical-align: middle;
+}
+
 .table > thead {
   vertical-align: middle;
 }
@@ -702,13 +707,9 @@ $bootstrap-icons-font-src: url("bootstrap-icons/font/fonts/bootstrap-icons.woff2
 // as the header token above), sized and inset with `padding-left` so text
 // clears it.
 //
-// Direct-child selector (`> th > input.form-control`) is deliberate: DXTable's
-// text/number/date filters render a bare `.form-control` straight inside the
-// `<th>`, whereas the `select` filter's DAutocomplete nests its input inside
-// `.d-autocomplete .input-group .b-autocomplete-input-wrapper` — so it is not a
-// direct child and correctly gets NO glyph (it has its own chevron affordance).
-// `:not([type="date"])` further excludes the date filter (its own picker icon).
-.filter-row > th > input.form-control:not([type="date"]) {
+// Select filters keep their chevron without a second icon or extra text inset.
+// Date inputs keep their own picker affordance.
+.dx-table-filter-cell > input.form-control:not([type="date"]) {
   background-image: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' width='16' height='16' fill='%237c8293' viewBox='0 0 16 16'%3e%3cpath d='M11.742 10.344a6.5 6.5 0 1 0-1.397 1.398h-.001q.044.06.098.115l3.85 3.85a1 1 0 0 0 1.415-1.414l-3.85-3.85a1 1 0 0 0-.115-.1zM12 6.5a5.5 5.5 0 1 1-11 0 5.5 5.5 0 0 1 11 0'/%3e%3c/svg%3e");
   background-repeat: no-repeat;
   background-position: left 0.65rem center;
@@ -805,7 +806,8 @@ $dx-switch-on-soft: map.get(map.get($dx-variants, "success"), "soft-bg"); // #cd
   --dx-switch-off-well: #{color.mix($dx-switch-off, #fff, 10%)};
   --dx-switch-off-line: #{color.mix($dx-switch-off, #fff, 45%)};
   --dx-switch-off-ink: #{color.mix($dx-switch-off, #000, 30%)};
-  --dx-switch-pill: var(--bs-gray-400, #ced4da); // neutral pill in both states
+  --dx-switch-pill: var(--bs-gray-400, #ced4da); // neutral OFF pill
+  --dx-switch-on-pill: #{color.mix(map.get(map.get($dx-variants, "success"), "soft-text"), $gray-400, 50%)};
 }
 
 // Optically centre the check/radio/switch box against its label's FIRST line.
@@ -1046,3 +1048,8 @@ $dx-chart-palette-dark: (#60a5fa, #a3e635, #a78bfa, #2dd4bf, #fb923c, #22d3ee, #
     margin-left: 0;
   }
 }
+
+// Keep the compact filter-cell spacing when BTable supplies the subheader row.
+thead tr:has(.dx-table-filter-cell) > td {
+  padding: 0.5rem;
+}

package/resources/js/components/base/DAutocomplete.vue

@@ -203,13 +203,13 @@ const noClearButton = computed(
 */
 .d-autocomplete :deep(.b-autocomplete-trigger) {
   --bs-btn-bg: var(--bs-body-bg);
-  --bs-btn-border-color: var(--bs-border-color);
+  --bs-btn-border-color: var(--d-input-border-color, var(--bs-border-color));
   --bs-btn-color: var(--bs-secondary-color);
   --bs-btn-hover-bg: var(--bs-tertiary-bg);
-  --bs-btn-hover-border-color: var(--bs-border-color);
+  --bs-btn-hover-border-color: var(--d-input-border-color, var(--bs-border-color));
   --bs-btn-hover-color: var(--bs-body-color);
   --bs-btn-active-bg: var(--bs-secondary-bg);
-  --bs-btn-active-border-color: var(--bs-border-color);
+  --bs-btn-active-border-color: var(--d-input-border-color, var(--bs-border-color));
   --bs-btn-active-color: var(--bs-body-color);
   flex: 0 0 auto;
 }

package/resources/js/components/base/DButton.vue

@@ -2,11 +2,12 @@
 /**
  * DButton - A type-safe wrapper around Bootstrap Vue Next's BButton component
  *
- * Adds three base-level button behaviours on top of `variant`/`size`:
+ * Adds base-level button behaviours on top of `variant`/`size`:
  * - `loading` — disables the button and shows a trailing spinner while an async
  *   action is in flight, with anti-flash timing (no spinner for sub-`spinnerDelay`
  *   actions; a `minSpinnerTime` floor once shown so it never strobes).
  * - `icon` — a leading Bootstrap Icons glyph (e.g. `icon="save"` → `bi bi-save`).
+ * - `iconOnly` — square icon control at the standard height for its size.
  * - `block` — full-width button (the BS5 replacement for the dropped `.btn-block`).
  *
  * @component
@@ -15,6 +16,7 @@
  * <DButton variant="primary" size="lg">Click Me</DButton>
  * <DButton icon="save" variant="primary">Save</DButton>
  * <DButton :loading="isSaving" loading-text="Saving…">Save</DButton>
+ * <DButton icon="trash" icon-only aria-label="Delete" />
  * <DButton block>Continue</DButton>
  * ```
  */
@@ -88,6 +90,15 @@ interface Props {
    */
   icon?: string;
 
+  /**
+   * Square icon control at the same height as a normal button of this size.
+   * Use `icon` or an icon in the default slot, and provide `aria-label`.
+   * Takes precedence over `block`. While loading, the spinner replaces the
+   * icon/slot without changing dimensions; `loadingText` is not shown.
+   * @default false
+   */
+  iconOnly?: boolean;
+
   /**
    * Full-width button (BS5 `w-100` idiom, replacing the dropped `.btn-block`).
    * @default false
@@ -114,6 +125,7 @@ const props = withDefaults(defineProps<Props>(), {
   disabled: false,
   loading: false,
   block: false,
+  iconOnly: false,
   spinnerDelay: 500,
   minSpinnerTime: 100,
 });
@@ -189,7 +201,7 @@ const passthroughSlotNames = computed(() =>
 // `:deep()`-on-a-B-root trap. Only add the flex row when there's an adornment
 // to space out.
 const hasAdornment = computed(
-  () => Boolean(props.icon) || showSpinner.value,
+  () => props.iconOnly || Boolean(props.icon) || showSpinner.value,
 );
 </script>
 
@@ -201,7 +213,7 @@ const hasAdornment = computed(
     :aria-busy="loading || showSpinner || undefined"
     :class="[
       { 'd-inline-flex align-items-center justify-content-center gap-2': hasAdornment },
-      { 'w-100': block },
+      { 'w-100': block && !iconOnly, 'd-button--icon-only': iconOnly },
     ]"
     v-bind="$attrs"
   >
@@ -210,8 +222,8 @@ const hasAdornment = computed(
       :class="['bi', `bi-${icon}`]"
       aria-hidden="true"
     ></i>
-    <template v-if="showSpinner && loadingText">{{ loadingText }}</template>
-    <slot v-else />
+    <template v-if="showSpinner && loadingText && !iconOnly">{{ loadingText }}</template>
+    <slot v-else-if="!iconOnly || !showSpinner" />
     <DSpinner v-if="showSpinner" small />
 
     <!-- Forward any other named slots untouched, with their slot props. -->
@@ -224,3 +236,25 @@ const hasAdornment = computed(
     </template>
   </BButton>
 </template>
+
+<style scoped>
+.d-button--icon-only {
+  --d-button-icon-size: calc(
+    1em * var(--bs-btn-line-height) + 2 * var(--bs-btn-padding-y) +
+      2 * var(--bs-btn-border-width)
+  );
+  width: var(--d-button-icon-size);
+  height: var(--d-button-icon-size);
+  padding: 0;
+  flex-shrink: 0;
+}
+
+.input-group > .d-button--icon-only {
+  padding: 0;
+}
+
+.d-button--icon-only > .bi {
+  font-size: 1.25em;
+  line-height: 1;
+}
+</style>

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

@@ -35,7 +35,7 @@
       </div>
     </div>
 
-    <nav ref="navRef" class="sidebar-nav p-3">
+    <nav ref="navRef" class="sidebar-nav px-3 pb-3 pt-2">
       <template v-for="(group, groupIndex) in navigation" :key="groupIndex">
         <div
           v-if="group.visible !== false"
@@ -426,11 +426,15 @@ watch(activeGroupIndex, () => {
   overflow-x: hidden;
 }
 
-/* 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. */
+/* Rhythm: natural-case headers at 0.875rem (no uppercase/letter-spacing, #95),
+   with a full 1rem between groups so each section reads as its own block.
+   The 0.25rem gap #95 shipped with left a group label 4px under the previous
+   group's last item — closer to that item than to its own — and the eye
+   attached the label to the wrong group. The nav's top padding is reduced to
+   match (pt-2), so the first item sits nearer the header than the groups sit
+   to each other. */
 .nav-group {
-  margin-bottom: 0.25rem;
+  margin-bottom: 1rem;
 }
 
 .nav-group-label {

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

@@ -5,8 +5,8 @@
   An opinionated switch built on `DFormCheckbox` (`switch`): a bordered box sized
   like a `.form-control` with the label on the left and the toggle on the right,
   colour-coding its state. By default (`onVariant="success"`) it reads the house
-  green-on / red-off style — a neutral box + red toggle when off, a soft-green
-  box + green toggle when on. `onVariant="neutral"` (brand primary on / grey off)
+  green-on / red-off style: a light-red box with a grey toggle when off, a
+  soft-green box with a muted green-grey toggle when on. `onVariant="neutral"` (brand primary on / grey off)
   is for semantically-mixed switches that shouldn't imply good/bad (#158). Used
   standalone or, internally, by `DXField`'s `switch` field type so a form switch
   and a lone switch share one look.
@@ -168,8 +168,8 @@ defineOptions({
   cursor: pointer;
 }
 
-/* Filled box (#158): the WHOLE control carries the colour and the pill stays a
-   neutral grey affordance — the box IS the state, so it reads strongest at a
+/* Filled box (#158): the WHOLE control carries the colour and the pill uses a
+   muted state tint — the box IS the state, so it reads strongest at a
    glance (the house style). `success` (default) is green ON / light-red OFF;
    `neutral` keeps a brand primary panel for mixed-semantics switches. Pair with
    `textWhenTrue`/`textWhenFalse` so the LABEL also names each state. */
@@ -192,9 +192,12 @@ defineOptions({
   font-weight: 500;
 }
 
-/* Neutral grey pill in BOTH states (white thumb, sliding) — overrides the global
-   green-on/red-off toggle colours within the box, so only the box carries the
-   state. Explicit `:checked`/`:focus` selectors so they out-specify the global
+.dx-switch--success.dx-switch--on {
+  --dx-switch-pill: var(--dx-switch-on-pill);
+}
+
+/* Muted pill with a white sliding thumb: green-grey ON, neutral grey OFF.
+   The stronger box colour and position continue to communicate the state. Explicit `:checked`/`:focus` selectors so they out-specify the global
    `.form-switch .form-check-input:checked` rule. */
 .dx-switch--success :deep(.form-check-input),
 .dx-switch--success :deep(.form-check-input:checked),

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

@@ -72,8 +72,7 @@
                              supplied their own `table-colgroup` (forwarded generically) —
                              so a table with no widths gets no colgroup and renders exactly
                              as before. `<col>` widths are authoritative under
-                             `table-layout: fixed`, where the filter row (not the header)
-                             is the width-determining first row. -->
+                             `table-layout: fixed`, regardless of any consumer header banners. -->
                         <template
                             v-if="fieldsHaveWidths && !$slots['table-colgroup']"
                             #table-colgroup
@@ -85,92 +84,90 @@
                             />
                         </template>
 
-                        <!-- DXTable owns `thead-top` (its filter row lives there), so a
-                             consumer's own thead-top content is COMPOSED above it rather
-                             than being dropped: a grouped column-header banner or a pinned
-                             totals row sits above the headers where it belongs (#120). -->
-                        <template v-if="hasFilters || $slots['thead-top']" #thead-top="theadScope">
+                        <template v-if="$slots['thead-top']" #thead-top="theadScope">
                             <!--
-                              @slot A row rendered ABOVE the column headers — a grouped-column banner (a `<th colspan>` spanning several columns), or a pinned totals row. Renders above DXTable's own filter row. Give it `<tr>`s.
+                              @slot Rows above the column headers, such as grouped-column banners or pinned totals. Give it `<tr>`s.
                               @binding {object} columns The number of columns in the table.
                               @binding {object} fields The table's fields.
                             -->
                             <slot name="thead-top" v-bind="theadScope" />
+                        </template>
 
-                            <tr v-if="hasFilters" class="filter-row">
-                                <th v-for="field in fields" :key="`filter-${field.key}`" class="p-2">
-                                    <!-- Text Filter -->
-                                    <DFormInput
-                                        v-if="field.filter === 'text'"
-                                        :model-value="effectiveFilters[filterKeyFor(field)] || ''"
-                                        :placeholder="field.filterPlaceholder || `Search ${field.label || field.key}...`"
-                                        size="sm"
-                                        @update:model-value="handleFilterChange(filterKeyFor(field), $event as string)"
-                                    />
-
-                                    <!-- Multi-value Select Filter (#51): several values at once; the filters entry is an array -->
-                                    <DAutocomplete
-                                        v-else-if="field.filter === 'select' && field.filterMultiple"
-                                        :model-value="multiFilterValueFor(field)"
-                                        :options="getFieldFilterOptions(field)"
-                                        :placeholder="field.filterPlaceholder || filterAllLabelFor(field)"
-                                        size="sm"
-                                        multiple
-                                        open-on-focus
-                                        @update:model-value="handleMultiSelectFilterChange(field, $event)"
-                                    />
-
-                                    <!-- Select Filter: typeahead — browse the full list on focus, or type to narrow; clear (✕) resets to "no filter" -->
-                                    <DAutocomplete
-                                        v-else-if="field.filter === 'select'"
-                                        :model-value="(effectiveFilters[filterKeyFor(field)] as string) || ''"
-                                        :options="getFieldFilterOptions(field)"
-                                        :placeholder="field.filterPlaceholder || filterAllLabelFor(field)"
-                                        size="sm"
-                                        open-on-focus
-                                        @update:model-value="handleSelectFilterChange(field, $event)"
-                                    />
-
-                                    <!-- Native Select Filter (S3b): a plain <select> for consumers who
-                                         want OS-native behaviour (full-height menu, native keyboard/scroll)
-                                         instead of the DAutocomplete typeahead. Shares the select filter's
-                                         option list (getFieldFilterOptions) and change handler
-                                         (handleSelectFilterChange) EXACTLY — so it behaves identically to
-                                         filter:"select" in every way but the control. Single-select only:
-                                         `filterMultiple` is ignored here. The model maps "no filter" to the
-                                         FILTER_ALL_VALUE sentinel (see nativeSelectFilterValue) so the "All …"
-                                         option shows selected in a native control. -->
-                                    <DFormSelect
-                                        v-else-if="field.filter === 'select-native'"
-                                        :model-value="nativeSelectFilterValue(field)"
-                                        :options="getFieldFilterOptions(field) as unknown as Record<string, unknown>[]"
-                                        size="sm"
-                                        @update:model-value="handleSelectFilterChange(field, $event)"
-                                    />
-
-                                    <!-- Number Filter -->
-                                    <DFormInput
-                                        v-else-if="field.filter === 'number'"
-                                        :model-value="effectiveFilters[filterKeyFor(field)] || ''"
-                                        :placeholder="field.filterPlaceholder || `Filter ${field.label || field.key}...`"
-                                        type="number"
-                                        size="sm"
-                                        @update:model-value="handleFilterChange(filterKeyFor(field), $event as string)"
-                                    />
-
-                                    <!-- Date Filter -->
-                                    <DFormInput
-                                        v-else-if="field.filter === 'date'"
-                                        :model-value="effectiveFilters[filterKeyFor(field)] || ''"
-                                        type="date"
-                                        size="sm"
-                                        @update:model-value="handleFilterChange(filterKeyFor(field), $event as string)"
-                                    />
+                        <!-- The table supplies the below-header row and one cell per field. -->
+                        <template v-if="hasFilters || $slots['thead-sub']" #thead-sub="{ field, ...filterScope }">
+                            <div v-if="hasFilters" class="dx-table-filter-cell">
+                                <!-- Text Filter -->
+                                <DFormInput
+                                    v-if="field.filter === 'text'"
+                                    :model-value="effectiveFilters[filterKeyFor(field)] || ''"
+                                    :placeholder="field.filterPlaceholder || `Search ${field.label || field.key}...`"
+                                    size="sm"
+                                    @update:model-value="handleFilterChange(filterKeyFor(field), $event as string)"
+                                />
+
+                                <!-- Multi-value Select Filter (#51): several values at once; the filters entry is an array -->
+                                <DAutocomplete
+                                    v-else-if="field.filter === 'select' && field.filterMultiple"
+                                    :model-value="multiFilterValueFor(field)"
+                                    :options="getFieldFilterOptions(field)"
+                                    :placeholder="field.filterPlaceholder || filterAllLabelFor(field)"
+                                    size="sm"
+                                    multiple
+                                    open-on-focus
+                                    @update:model-value="handleMultiSelectFilterChange(field, $event)"
+                                />
+
+                                <!-- Select Filter: typeahead — browse the full list on focus, or type to narrow; clear (✕) resets to "no filter" -->
+                                <DAutocomplete
+                                    v-else-if="field.filter === 'select'"
+                                    :model-value="(effectiveFilters[filterKeyFor(field)] as string) || ''"
+                                    :options="getFieldFilterOptions(field)"
+                                    :placeholder="field.filterPlaceholder || filterAllLabelFor(field)"
+                                    size="sm"
+                                    open-on-focus
+                                    @update:model-value="handleSelectFilterChange(field, $event)"
+                                />
+
+                                <!-- Native Select Filter (S3b): a plain <select> for consumers who
+                                     want OS-native behaviour (full-height menu, native keyboard/scroll)
+                                     instead of the DAutocomplete typeahead. Shares the select filter's
+                                     option list (getFieldFilterOptions) and change handler
+                                     (handleSelectFilterChange) EXACTLY — so it behaves identically to
+                                     filter:"select" in every way but the control. Single-select only:
+                                     `filterMultiple` is ignored here. The model maps "no filter" to the
+                                     FILTER_ALL_VALUE sentinel (see nativeSelectFilterValue) so the "All …"
+                                     option shows selected in a native control. -->
+                                <DFormSelect
+                                    v-else-if="field.filter === 'select-native'"
+                                    :model-value="nativeSelectFilterValue(field)"
+                                    :options="getFieldFilterOptions(field) as unknown as Record<string, unknown>[]"
+                                    size="sm"
+                                    @update:model-value="handleSelectFilterChange(field, $event)"
+                                />
+
+                                <!-- Number Filter -->
+                                <DFormInput
+                                    v-else-if="field.filter === 'number'"
+                                    :model-value="effectiveFilters[filterKeyFor(field)] || ''"
+                                    :placeholder="field.filterPlaceholder || `Filter ${field.label || field.key}...`"
+                                    type="number"
+                                    size="sm"
+                                    @update:model-value="handleFilterChange(filterKeyFor(field), $event as string)"
+                                />
+
+                                <!-- Date Filter -->
+                                <DFormInput
+                                    v-else-if="field.filter === 'date'"
+                                    :model-value="effectiveFilters[filterKeyFor(field)] || ''"
+                                    type="date"
+                                    size="sm"
+                                    @update:model-value="handleFilterChange(filterKeyFor(field), $event as string)"
+                                />
 
-                                    <!-- No filter for this column -->
-                                    <div v-else></div>
-                                </th>
-                            </tr>
+                                <!-- No filter for this column -->
+                                <div v-else></div>
+                            </div>
+                            <slot name="thead-sub" v-bind="{ ...filterScope, field }" />
                         </template>
 
                         <!-- Custom headers for all fields -->
@@ -752,6 +749,9 @@ export interface Props<TItem = any> {
      * `edit-value` slot's binding); `data` is the live form data. Aborting
      * leaves the modal open with the user's edits intact. A guard that throws
      * also aborts, surfacing its message.
+     *
+     * Dismissing the modal while the guard is still pending — by any route —
+     * abandons the save; nothing is written for a record the user has closed.
      */
     saveGuard?: (
         item: TItem | null,
@@ -1315,9 +1315,8 @@ const dottedCellFields = (slots: Record<string, unknown>): TableField[] =>
 /*
  * Per-column widths (#156). A field's `width`/`minWidth` is applied through a
  * `<colgroup>` `<col>`, NOT the header `<th>`: with `table-layout: fixed` the
- * column widths are taken from the FIRST row of cells, and DXTable's inline
- * filter row (`thead-top`) is that first row — so a width on the header `<th>`
- * would be ignored whenever filters are present. A `<col>` width is
+ * column widths are taken from the FIRST row of cells, which may be a
+ * consumer banner rather than the column labels. A `<col>` width is
  * authoritative regardless of row order, in both fixed and auto layout.
  */
 const sizeToCss = (value: string | number): string =>
@@ -2259,7 +2258,7 @@ const refresh = () => {
  *
  * - `head(<key>)` — DXTable draws its own column headers (sort indicators,
  *   field hints). Forwarding a consumer's would silently drop those.
- * - `thead-top`   — DXTable renders the inline filter row there.
+ * - `thead-top` / `thead-sub` — composed with the below-header filter cells.
  *
  * `head-end(<key>)` is DXTable's OWN additive header slot (#99) and is likewise
  * not forwarded: the inner table has no such slot, and the prefixes below are
@@ -2309,11 +2308,10 @@ const isTableSlot = (name: string) =>
  * invisible (#114). Called from the template, it re-evaluates every render.
  *
  * It also has to EXCLUDE the slots DXTable renders itself: declaring `#thead-top`
- * here (even rendering nothing into it) would override DXTable's own thead-top
- * template, silently dropping the filter row and the consumer's banner (#120).
+ * or `#thead-sub` here would override the composed header/filter slots.
  */
 const forwardableSlotNames = (slots: Record<string, unknown>): string[] =>
-    Object.keys(slots).filter((name) => isTableSlot(name));
+    Object.keys(slots).filter((name) => name !== 'thead-sub' && isTableSlot(name));
 
 const tableSlotSignature = (slots: Record<string, unknown>): string => {
     // DXTable's OWN dotted-cell slots count too (#121). bvn captures its cell