@omnitend/dashboard-for-laravel 0.22.0 → 0.24.0

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

@@ -10,13 +10,13 @@
         <DRow class="justify-content-center">
             <DCol :md="columnSize">
                 <DXTableShell :card="card">
-                    <template v-if="title || createUrl || $slots.header" #header>
+                    <template v-if="title || showsCreateButton || $slots.header" #header>
                         <!-- @slot Card header content; overrides the default title heading and the "New {item}" button. -->
                         <slot name="header">
                             <div class="d-flex justify-content-between align-items-center">
                                 <h4 class="mb-0">{{ title }}</h4>
                                 <DButton
-                                    v-if="createUrl"
+                                    v-if="showsCreateButton"
                                     variant="primary"
                                     size="sm"
                                     @click="handleCreateNew"
@@ -27,15 +27,19 @@
                         </slot>
                     </template>
 
+                    <!-- Rendered ABOVE the table, not instead of it: a failed
+                         request is usually caused by the sort or a filter, and
+                         replacing the table would take away the very controls
+                         needed to undo it, leaving a reload as the only way out. -->
+                    <div v-if="error || apiError" class="alert alert-danger">
+                        {{ error || apiError }}
+                    </div>
+
                     <div v-if="effectiveBusy && !isProviderMode" class="text-center py-5">
                         <DSpinner variant="primary" />
                         <p class="mt-2">{{ loadingText }}</p>
                     </div>
 
-                    <div v-else-if="error || apiError" class="alert alert-danger">
-                        {{ error || apiError }}
-                    </div>
-
                     <!-- Provider Mode: Use BTable's provider pattern -->
                     <DTable
                         v-else-if="isProviderMode"
@@ -51,7 +55,9 @@
                         :hover="hover"
                         :responsive="responsive"
                         :busy="busy"
+                        v-bind="tablePassthroughProps"
                         @update:sort-by="handleSortChange"
+                        @update:expanded-items="emit('update:expandedItems', $event)"
                         @update:current-page="apiCurrentPage = $event"
                         @update:busy="handleBusyChange"
                         @row-clicked="handleRowClick"
@@ -63,40 +69,40 @@
                                     <!-- Text Filter -->
                                     <DFormInput
                                         v-if="field.filter === 'text'"
-                                        :model-value="effectiveFilters[field.key] || ''"
+                                        :model-value="effectiveFilters[filterKeyFor(field)] || ''"
                                         :placeholder="field.filterPlaceholder || `Search ${field.label || field.key}...`"
                                         size="sm"
-                                        @update:model-value="handleFilterChange(field.key, $event as string)"
+                                        @update:model-value="handleFilterChange(filterKeyFor(field), $event as string)"
                                     />
 
                                     <!-- 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[field.key] || ''"
+                                        :model-value="effectiveFilters[filterKeyFor(field)] || ''"
                                         :options="getFieldFilterOptions(field)"
                                         :placeholder="field.filterPlaceholder || `All ${field.label || field.key}`"
                                         size="sm"
                                         open-on-focus
-                                        @update:model-value="handleFilterChange(field.key, ($event ?? '') as string)"
+                                        @update:model-value="handleFilterChange(filterKeyFor(field), ($event ?? '') as string)"
                                     />
 
                                     <!-- Number Filter -->
                                     <DFormInput
                                         v-else-if="field.filter === 'number'"
-                                        :model-value="effectiveFilters[field.key] || ''"
+                                        :model-value="effectiveFilters[filterKeyFor(field)] || ''"
                                         :placeholder="field.filterPlaceholder || `Filter ${field.label || field.key}...`"
                                         type="number"
                                         size="sm"
-                                        @update:model-value="handleFilterChange(field.key, $event as string)"
+                                        @update:model-value="handleFilterChange(filterKeyFor(field), $event as string)"
                                     />
 
                                     <!-- Date Filter -->
                                     <DFormInput
                                         v-else-if="field.filter === 'date'"
-                                        :model-value="effectiveFilters[field.key] || ''"
+                                        :model-value="effectiveFilters[filterKeyFor(field)] || ''"
                                         type="date"
                                         size="sm"
-                                        @update:model-value="handleFilterChange(field.key, $event as string)"
+                                        @update:model-value="handleFilterChange(filterKeyFor(field), $event as string)"
                                     />
 
                                     <!-- No filter for this column -->
@@ -109,7 +115,7 @@
                         <template v-for="field in fields" :key="`head-${field.key}`" #[`head(${field.key})`]="{ label }">
                             <div class="d-flex align-items-center justify-content-between gap-2">
                                 <div class="flex-grow-1">
-                                    <div class="fw-semibold">{{ label || field.key }}</div>
+                                    <div class="fw-semibold">{{ headerLabel(field, label) }}</div>
                                     <small v-if="field.hint" class="text-muted d-block" style="font-weight: normal;">{{ field.hint }}</small>
                                 </div>
                                 <div v-if="field.sortable" class="sort-indicator text-muted flex-shrink-0" style="font-size: 0.75rem; line-height: 1.1; display: flex; flex-direction: column; align-items: center;">
@@ -119,23 +125,19 @@
                             </div>
                         </template>
 
-                        <!-- Pass through all cell slots -->
+                        <!-- Forward every slot the inner table understands: cell(<key>),
+                             foot(<key>), custom-foot, empty, empty-filtered, row-expansion,
+                             table-busy/caption/colgroup, thead-sub, top-row, bottom-row.
+                             See `isTableSlot` for the two DXTable renders itself. -->
                         <template
-                            v-for="(_, name) in $slots"
+                            v-for="name in forwardedTableSlotNames"
+                            :key="name"
                             #[name]="slotProps"
                         >
                             <!--
-                              @slot Custom rendering for a column's cell. Name it `cell(<fieldKey>)` to target a field; receives the underlying table cell scope.
-                              @binding {object} item The row data object for this cell.
-                              @binding {any} value The cell value for the field.
-                              @binding {number} index The zero-based row index.
-                              @binding {object} field The field definition for the column.
+                              @slot 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.
                             -->
-                            <slot
-                                v-if="typeof name === 'string' && name.startsWith('cell')"
-                                :name="name"
-                                v-bind="slotProps"
-                            />
+                            <slot :name="name" v-bind="slotProps" />
                         </template>
                     </DTable>
 
@@ -151,7 +153,9 @@
                         :striped="striped"
                         :hover="hover"
                         :responsive="responsive"
+                        v-bind="tablePassthroughProps"
                         @update:sort-by="handleSortChange"
+                        @update:expanded-items="emit('update:expandedItems', $event)"
                         @row-clicked="handleRowClick"
                     >
                         <!-- Inline Filter Row -->
@@ -161,40 +165,40 @@
                                     <!-- Text Filter -->
                                     <DFormInput
                                         v-if="field.filter === 'text'"
-                                        :model-value="effectiveFilters[field.key] || ''"
+                                        :model-value="effectiveFilters[filterKeyFor(field)] || ''"
                                         :placeholder="field.filterPlaceholder || `Search ${field.label || field.key}...`"
                                         size="sm"
-                                        @update:model-value="handleFilterChange(field.key, $event as string)"
+                                        @update:model-value="handleFilterChange(filterKeyFor(field), $event as string)"
                                     />
 
                                     <!-- 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[field.key] || ''"
+                                        :model-value="effectiveFilters[filterKeyFor(field)] || ''"
                                         :options="getFieldFilterOptions(field)"
                                         :placeholder="field.filterPlaceholder || `All ${field.label || field.key}`"
                                         size="sm"
                                         open-on-focus
-                                        @update:model-value="handleFilterChange(field.key, ($event ?? '') as string)"
+                                        @update:model-value="handleFilterChange(filterKeyFor(field), ($event ?? '') as string)"
                                     />
 
                                     <!-- Number Filter -->
                                     <DFormInput
                                         v-else-if="field.filter === 'number'"
-                                        :model-value="effectiveFilters[field.key] || ''"
+                                        :model-value="effectiveFilters[filterKeyFor(field)] || ''"
                                         :placeholder="field.filterPlaceholder || `Filter ${field.label || field.key}...`"
                                         type="number"
                                         size="sm"
-                                        @update:model-value="handleFilterChange(field.key, $event as string)"
+                                        @update:model-value="handleFilterChange(filterKeyFor(field), $event as string)"
                                     />
 
                                     <!-- Date Filter -->
                                     <DFormInput
                                         v-else-if="field.filter === 'date'"
-                                        :model-value="effectiveFilters[field.key] || ''"
+                                        :model-value="effectiveFilters[filterKeyFor(field)] || ''"
                                         type="date"
                                         size="sm"
-                                        @update:model-value="handleFilterChange(field.key, $event as string)"
+                                        @update:model-value="handleFilterChange(filterKeyFor(field), $event as string)"
                                     />
 
                                     <!-- No filter for this column -->
@@ -207,7 +211,7 @@
                         <template v-for="field in fields" :key="`head-${field.key}`" #[`head(${field.key})`]="{ label }">
                             <div class="d-flex align-items-center justify-content-between gap-2">
                                 <div class="flex-grow-1">
-                                    <div class="fw-semibold">{{ label || field.key }}</div>
+                                    <div class="fw-semibold">{{ headerLabel(field, label) }}</div>
                                     <small v-if="field.hint" class="text-muted d-block" style="font-weight: normal;">{{ field.hint }}</small>
                                 </div>
                                 <div v-if="field.sortable" class="sort-indicator text-muted flex-shrink-0" style="font-size: 0.75rem; line-height: 1.1; display: flex; flex-direction: column; align-items: center;">
@@ -217,23 +221,19 @@
                             </div>
                         </template>
 
-                        <!-- Pass through all cell slots -->
+                        <!-- Forward every slot the inner table understands: cell(<key>),
+                             foot(<key>), custom-foot, empty, empty-filtered, row-expansion,
+                             table-busy/caption/colgroup, thead-sub, top-row, bottom-row.
+                             See `isTableSlot` for the two DXTable renders itself. -->
                         <template
-                            v-for="(_, name) in $slots"
+                            v-for="name in forwardedTableSlotNames"
+                            :key="name"
                             #[name]="slotProps"
                         >
                             <!--
-                              @slot Custom rendering for a column's cell. Name it `cell(<fieldKey>)` to target a field; receives the underlying table cell scope.
-                              @binding {object} item The row data object for this cell.
-                              @binding {any} value The cell value for the field.
-                              @binding {number} index The zero-based row index.
-                              @binding {object} field The field definition for the column.
+                              @slot 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.
                             -->
-                            <slot
-                                v-if="typeof name === 'string' && name.startsWith('cell')"
-                                :name="name"
-                                v-bind="slotProps"
-                            />
+                            <slot :name="name" v-bind="slotProps" />
                         </template>
                     </DTable>
 
@@ -250,7 +250,9 @@
                         :hover="hover"
                         :responsive="responsive"
                         :busy="effectiveBusy"
+                        v-bind="tablePassthroughProps"
                         @update:sort-by="handleSortChange"
+                        @update:expanded-items="emit('update:expandedItems', $event)"
                         @row-clicked="handleRowClick"
                     >
                         <!-- Inline Filter Row -->
@@ -260,40 +262,40 @@
                                     <!-- Text Filter -->
                                     <DFormInput
                                         v-if="field.filter === 'text'"
-                                        :model-value="effectiveFilters[field.key] || ''"
+                                        :model-value="effectiveFilters[filterKeyFor(field)] || ''"
                                         :placeholder="field.filterPlaceholder || `Search ${field.label || field.key}...`"
                                         size="sm"
-                                        @update:model-value="handleFilterChange(field.key, $event as string)"
+                                        @update:model-value="handleFilterChange(filterKeyFor(field), $event as string)"
                                     />
 
                                     <!-- 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[field.key] || ''"
+                                        :model-value="effectiveFilters[filterKeyFor(field)] || ''"
                                         :options="getFieldFilterOptions(field)"
                                         :placeholder="field.filterPlaceholder || `All ${field.label || field.key}`"
                                         size="sm"
                                         open-on-focus
-                                        @update:model-value="handleFilterChange(field.key, ($event ?? '') as string)"
+                                        @update:model-value="handleFilterChange(filterKeyFor(field), ($event ?? '') as string)"
                                     />
 
                                     <!-- Number Filter -->
                                     <DFormInput
                                         v-else-if="field.filter === 'number'"
-                                        :model-value="effectiveFilters[field.key] || ''"
+                                        :model-value="effectiveFilters[filterKeyFor(field)] || ''"
                                         :placeholder="field.filterPlaceholder || `Filter ${field.label || field.key}...`"
                                         type="number"
                                         size="sm"
-                                        @update:model-value="handleFilterChange(field.key, $event as string)"
+                                        @update:model-value="handleFilterChange(filterKeyFor(field), $event as string)"
                                     />
 
                                     <!-- Date Filter -->
                                     <DFormInput
                                         v-else-if="field.filter === 'date'"
-                                        :model-value="effectiveFilters[field.key] || ''"
+                                        :model-value="effectiveFilters[filterKeyFor(field)] || ''"
                                         type="date"
                                         size="sm"
-                                        @update:model-value="handleFilterChange(field.key, $event as string)"
+                                        @update:model-value="handleFilterChange(filterKeyFor(field), $event as string)"
                                     />
 
                                     <!-- No filter for this column -->
@@ -306,7 +308,7 @@
                         <template v-for="field in fields" :key="`head-${field.key}`" #[`head(${field.key})`]="{ label }">
                             <div class="d-flex align-items-center justify-content-between gap-2">
                                 <div class="flex-grow-1">
-                                    <div class="fw-semibold">{{ label || field.key }}</div>
+                                    <div class="fw-semibold">{{ headerLabel(field, label) }}</div>
                                     <small v-if="field.hint" class="text-muted d-block" style="font-weight: normal;">{{ field.hint }}</small>
                                 </div>
                                 <div v-if="field.sortable" class="sort-indicator text-muted flex-shrink-0" style="font-size: 0.75rem; line-height: 1.1; display: flex; flex-direction: column; align-items: center;">
@@ -316,23 +318,19 @@
                             </div>
                         </template>
 
-                        <!-- Pass through all cell slots -->
+                        <!-- Forward every slot the inner table understands: cell(<key>),
+                             foot(<key>), custom-foot, empty, empty-filtered, row-expansion,
+                             table-busy/caption/colgroup, thead-sub, top-row, bottom-row.
+                             See `isTableSlot` for the two DXTable renders itself. -->
                         <template
-                            v-for="(_, name) in $slots"
+                            v-for="name in forwardedTableSlotNames"
+                            :key="name"
                             #[name]="slotProps"
                         >
                             <!--
-                              @slot Custom rendering for a column's cell. Name it `cell(<fieldKey>)` to target a field; receives the underlying table cell scope.
-                              @binding {object} item The row data object for this cell.
-                              @binding {any} value The cell value for the field.
-                              @binding {number} index The zero-based row index.
-                              @binding {object} field The field definition for the column.
+                              @slot 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.
                             -->
-                            <slot
-                                v-if="typeof name === 'string' && name.startsWith('cell')"
-                                :name="name"
-                                v-bind="slotProps"
-                            />
+                            <slot :name="name" v-bind="slotProps" />
                         </template>
                     </DTable>
 
@@ -433,15 +431,15 @@
                     </div>
 
                     <!-- Pagination and Controls (API mode) -->
-                    <div v-if="isProviderMode && apiPaginationMeta" class="mt-3">
+                    <div v-if="isProviderMode && providerPagination" class="mt-3">
                         <!-- Top row: Pagination and Per-page selector -->
                         <div class="d-flex justify-content-between align-items-center mb-2">
                             <!-- Pagination controls (only when multiple pages) -->
                             <DPagination
-                                v-if="showPagination && apiPaginationMeta.total > apiPaginationMeta.per_page"
-                                :model-value="apiPaginationMeta.current_page"
-                                :total-rows="apiPaginationMeta.total"
-                                :per-page="apiPaginationMeta.per_page"
+                                v-if="showPagination && providerPagination.total > providerPagination.per_page"
+                                :model-value="providerPagination.current_page"
+                                :total-rows="providerPagination.total"
+                                :per-page="providerPagination.per_page"
                                 size="sm"
                                 @update:model-value="handleApiPageChange"
                             />
@@ -464,18 +462,18 @@
                         <!-- Bottom row: Info text -->
                         <div class="small text-muted">
                             <div>
-                                <template v-if="apiPaginationMeta.total > apiPaginationMeta.per_page">
-                                    {{ apiPaginationMeta.from }} to {{ apiPaginationMeta.to }} out of {{ apiPaginationMeta.total }} {{ apiPaginationMeta.total === 1 ? singularItemName : pluralItemName }}.
+                                <template v-if="providerPagination.total > providerPagination.per_page">
+                                    {{ providerPagination.from }} to {{ providerPagination.to }} out of {{ providerPagination.total }} {{ providerPagination.total === 1 ? singularItemName : pluralItemName }}.
                                 </template>
-                                <template v-else-if="apiPaginationMeta.total === 1">
-                                    {{ apiPaginationMeta.total }} {{ singularItemName }}.
+                                <template v-else-if="providerPagination.total === 1">
+                                    {{ providerPagination.total }} {{ singularItemName }}.
                                 </template>
                                 <template v-else>
-                                    {{ apiPaginationMeta.total }} {{ pluralItemName }}.
+                                    {{ providerPagination.total }} {{ pluralItemName }}.
                                 </template>
                             </div>
-                            <div v-if="hasActiveFilters && apiPaginationMeta.total_unfiltered">
-                                <small>Filtered from {{ apiPaginationMeta.total_unfiltered }} {{ apiPaginationMeta.total_unfiltered === 1 ? singularItemName : pluralItemName }}.</small>
+                            <div v-if="hasActiveFilters && providerPagination.total_unfiltered">
+                                <small>Filtered from {{ providerPagination.total_unfiltered }} {{ providerPagination.total_unfiltered === 1 ? singularItemName : pluralItemName }}.</small>
                             </div>
                         </div>
                     </div>
@@ -499,9 +497,18 @@
                 <span>Loading…</span>
             </div>
 
-            <!-- Edit/create form (tabbed when editTabs provided, flat otherwise) -->
+            <!-- Edit/create form (tabbed when editTabs provided, flat otherwise).
+
+                 Keyed per modal open: the form OBJECT is created once and then
+                 reseeded in place for each row, so without a key Vue reuses the
+                 same DXField instances across records — and any per-field UI
+                 state rides along with them. That leaked a revealed password
+                 from one row into the next. The key gives each record a fresh
+                 field subtree; the data still lives in `editForm`, so nothing
+                 is lost by remounting. -->
             <DXForm
                 v-if="editForm"
+                :key="editFormInstanceKey"
                 v-model:active-tab="activeTabIndex"
                 :form="editForm"
                 :fields="editFields"
@@ -628,7 +635,7 @@
 </template>
 
 <script setup lang="ts" generic="T = any">
-import { computed, ref, watch, useSlots } from "vue";
+import { computed, getCurrentInstance, ref, watch, useSlots } from "vue";
 import { router } from "@inertiajs/vue3";
 import axios from "axios";
 import pluralize from "pluralize";
@@ -657,6 +664,27 @@ export interface FilterOption {
 export interface TableField {
     key: string;
     label?: string;
+
+    /**
+     * The key this column's filter is sent under, when it differs from the
+     * column's own key (default: `key`). Lets a *display* column filter on a
+     * different server param — e.g. a "Customer" column rendering a name but
+     * filtering on `customer_id` — instead of forcing the column to be named
+     * after the server's filter param and the human-facing value into a
+     * `#cell` slot.
+     */
+    filterKey?: string;
+
+    /**
+     * For a `select` filter: adds an option meaning "has no value", e.g.
+     * `filterNullText: "Unassigned"` on an assignee column. Selecting it sends
+     * `filterNullValue` (default `"null"`) as the filter value; client-side, it
+     * matches rows whose value is null, undefined or empty.
+     */
+    filterNullText?: string;
+
+    /** The value sent when the `filterNullText` option is chosen. Default `"null"`. */
+    filterNullValue?: string;
     sortable?: boolean;
     hint?: string;
     filter?: FilterType;
@@ -842,6 +870,45 @@ export interface Props<TItem = any> {
     /** API endpoint for creating new items (e.g., "/api/products") — enables "New" button */
     createUrl?: string;
 
+    /**
+     * Render the built-in "New {item}" button in the card header (default
+     * `true` whenever `createUrl` is set). Set `false` to drive the create
+     * modal from your own trigger elsewhere — e.g. a button in the dashboard
+     * navbar's actions slot calling the exposed `openCreate()`. With no
+     * `title` and no `header` slot, the header is then dropped entirely
+     * rather than left empty.
+     */
+    showCreateButton?: boolean;
+
+    /**
+     * Render a `<tfoot>` mirroring the header row, so `#foot(<key>)` slots can
+     * hold per-column totals that line up under their data (#99). Without it
+     * there is no footer to put them in. For a fully custom footer, use the
+     * `custom-foot` slot instead.
+     */
+    footClone?: boolean;
+
+    /**
+     * Show a message row when there are no rows (default `true`). An empty
+     * table body is indistinguishable from a broken one, so the message is on
+     * by default. Override the wording with `emptyText`, or the whole row with
+     * the `empty` slot.
+     */
+    showEmpty?: boolean;
+
+    /**
+     * Message shown when there are no rows. Defaults to "No {items} found", or
+     * "No {items} match your filters" when a column filter is active.
+     */
+    emptyText?: string;
+
+    /**
+     * Rows currently expanded, as a `v-model`. Pair with the `row-expansion`
+     * slot to render detail content under a row (#112) instead of forcing every
+     * per-row detail into a modal.
+     */
+    expandedItems?: TItem[];
+
     /** Enable client-side filtering, sorting, and pagination on items array */
     clientSide?: boolean;
 }
@@ -872,6 +939,9 @@ const props = withDefaults(defineProps<Props<T>>(), {
     columnSize: "12",
     card: true,
     editModalSize: "lg",
+    showCreateButton: true,
+    footClone: false,
+    showEmpty: true,
 });
 
 const emit = defineEmits<{
@@ -899,6 +969,8 @@ const emit = defineEmits<{
     deleteError: [item: T, error: any];
     /** `v-model:sortBy` update, emitted with the normalized single-column sort array when sorting changes. */
     'update:sortBy': [sortBy: BTableSortBy[]];
+    /** `v-model:expandedItems` update, emitted with the rows currently expanded. */
+    'update:expandedItems': [items: T[]];
     /** `v-model:filters` update, emitted with the new filter map when a column filter changes. */
     'update:filters': [filters: Record<string, string>];
     /** `v-model:perPage` update, emitted with the new page size when the per-page selector changes. */
@@ -921,17 +993,68 @@ if (props.clientSide && (props.apiUrl || props.inertiaUrl)) {
 // Computed for effective busy state (provider mode uses 'busy', inertia uses 'loading')
 const effectiveBusy = computed(() => isProviderMode.value ? props.busy : props.loading);
 
-// Internal sortBy state for auto modes
-const internalSortBy = ref<BTableSortBy[]>([]);
+/*
+ * `perPage`, `sortBy` and `filters` are dual-purpose: with a `v-model` they are
+ * CONTROLLED state; without one they read as an INITIAL value.
+ *
+ * DXTable used to treat any passed value as controlled, so `:per-page="50"` —
+ * the natural way to say "start with 50 per page" — rendered a working-looking
+ * per-page selector that did nothing: the user picked 10, the select showed 10,
+ * and the table kept rendering 50 (#110). The control responded, nothing
+ * errored, and the table quietly ignored it.
+ *
+ * A prop is only controlled if the consumer is listening for its update, so
+ * that is what we check. It has to come off the raw vnode props: Vue strips
+ * DECLARED emit listeners out of `$attrs`, so `useAttrs()` can't see them.
+ * Listener presence doesn't meaningfully change over a component's life, so
+ * this is resolved once at setup rather than per render.
+ */
+const instance = getCurrentInstance();
+
+const hasListener = (event: string): boolean => {
+    const vnodeProps = instance?.vnode.props ?? {};
+    const toHandlerKey = (name: string) => `on${name.charAt(0).toUpperCase()}${name.slice(1)}`;
+    // `v-model:per-page` / `@row-clicked` compile to camelCase handler keys, but
+    // a hand-written hyphenated listener stays hyphenated — accept either.
+    const hyphenated = event.replace(/[A-Z]/g, (char) => `-${char.toLowerCase()}`);
+    return toHandlerKey(event) in vnodeProps || toHandlerKey(hyphenated) in vnodeProps;
+};
+
+const isControlled = {
+    perPage: hasListener('update:perPage'),
+    sortBy: hasListener('update:sortBy'),
+    filters: hasListener('update:filters'),
+};
+
+/*
+ * Rows are interactive when clicking one does something: the built-in edit
+ * modal (`editFields`) opens, or the consumer is listening for `row-clicked`.
+ * The cursor and hover affordance follow from that — DXTable already knows,
+ * so consumers shouldn't have to reach into `:deep(tbody tr)` to say it (#107).
+ * The listener case was the gap: only `editFields` used to count.
+ */
+const rowsAreInteractive = computed(
+    () => (props.editFields?.length ?? 0) > 0 || hasListener('rowClicked'),
+);
+
+const rowCursor = computed(() => (rowsAreInteractive.value ? 'pointer' : 'default'));
+const rowHoverBackground = computed(() =>
+    rowsAreInteractive.value ? 'var(--bs-table-hover-bg)' : 'inherit',
+);
+
+// Internal sortBy state, seeded from the prop when it's an initial value.
+const internalSortBy = ref<BTableSortBy[]>(props.sortBy ? [...props.sortBy] : []);
 
-// Computed effective sortBy (use external if provided, otherwise internal)
-const effectiveSortBy = computed(() => props.sortBy !== undefined ? props.sortBy : internalSortBy.value);
+const effectiveSortBy = computed(() =>
+    isControlled.sortBy && props.sortBy !== undefined ? props.sortBy : internalSortBy.value,
+);
 
-// Internal filters state for auto modes
-const internalFilters = ref<Record<string, string>>({});
+// Internal filters state, seeded from the prop when it's an initial value.
+const internalFilters = ref<Record<string, string>>({ ...(props.filters ?? {}) });
 
-// Computed effective filters (use external if provided, otherwise internal)
-const effectiveFilters = computed(() => props.filters !== undefined ? props.filters : internalFilters.value);
+const effectiveFilters = computed(() =>
+    isControlled.filters && props.filters !== undefined ? props.filters : internalFilters.value,
+);
 
 // Computed: check if any field has filtering enabled
 const hasFilters = computed(() => props.fields.some(field => field.filter !== false && field.filter !== undefined));
@@ -945,6 +1068,52 @@ const hasActiveFilters = computed(() => {
 // API mode pagination metadata (extracted from responses)
 const apiPaginationMeta = ref<PaginationData | null>(null);
 
+/**
+ * Pagination shown in provider mode.
+ *
+ * Only the built-in `apiUrl` provider can populate `apiPaginationMeta` — it's
+ * the one that knows to read `response.data.pagination`. A CUSTOM provider
+ * returns rows and nothing else, so the pager simply never rendered: a table
+ * with no pagination and no warning, which is why a page needing custom request
+ * shaping quietly lost its pager (#106). A custom provider now takes its
+ * pagination from the `pagination` prop, and says so when it's missing.
+ */
+// `pagination` carries a default from withDefaults, so props alone can't tell
+// whether the consumer actually passed one — ask the vnode. (Gating on
+// `total > 0` instead would treat a legitimately empty page as "no pagination".)
+const paginationWasProvided = 'pagination' in (instance?.vnode.props ?? {});
+
+const providerPagination = computed<PaginationData | null>(() => {
+    if (apiPaginationMeta.value) return apiPaginationMeta.value;
+    if (props.provider && paginationWasProvided && props.pagination) {
+        return props.pagination;
+    }
+    return null;
+});
+
+/*
+ * Loud, once, rather than a silently pager-less table — but only AFTER the
+ * provider has actually run, and judged on `providerPagination` (not the raw
+ * apiPaginationMeta). Warning at setup would fire on every consumer whose
+ * `pagination` prop arrives with the response rather than before it.
+ */
+const providerHasRun = ref(false);
+let warnedAboutProviderPagination = false;
+watch(
+    () => [props.provider, props.showPagination, providerPagination.value, providerHasRun.value] as const,
+    ([provider, showPagination, pagination, hasRun]) => {
+        if (warnedAboutProviderPagination || !hasRun) return;
+        if (provider && showPagination && !pagination) {
+            warnedAboutProviderPagination = true;
+            // eslint-disable-next-line no-console
+            console.warn(
+                '[DXTable] A custom `provider` cannot report its own pagination, so no pager will render. ' +
+                    'Pass the page metadata via the `pagination` prop, or set `:show-pagination="false"` to hide the pager deliberately.',
+            );
+        }
+    },
+);
+
 // ============================================
 // Client-Side Mode: Filtering, Sorting, Pagination
 // ============================================
@@ -966,8 +1135,23 @@ const clientSideFilteredItems = computed<T[]>(() => {
     return props.items.filter(item => {
         return filterKeys.every(key => {
             const filterValue = filters[key].trim().toLowerCase();
-            const field = props.fields.find(f => f.key === key);
-            const itemValue = (item as any)[key];
+            // Resolve by the FILTER key, which may differ from the column's key.
+            const field = props.fields.find(f => filterKeyFor(f) === key);
+            // `filterKey` names the param the SERVER filters on; a local row may
+            // not carry it at all (a `customer_name` row filtered on
+            // `customer_id`). Match on the filter key when the row has it,
+            // otherwise fall back to the column's own value — which is also the
+            // one the user can actually see and type against.
+            const itemValue =
+                field && key in (item as any)
+                    ? (item as any)[key]
+                    : (item as any)[field?.key ?? key];
+
+            // The "no value" option (e.g. Unassigned) is the one filter that
+            // MATCHES an absent value rather than failing on it.
+            if (field?.filterNullText && filters[key] === filterNullValueFor(field)) {
+                return itemValue === null || itemValue === undefined || itemValue === '';
+            }
 
             if (itemValue === null || itemValue === undefined) {
                 return false;
@@ -1037,21 +1221,43 @@ const clientSideSortedItems = computed<T[]>(() => {
 const apiFilterValues = ref<Record<string, string[]>>({});
 
 // Computed: Get effective filter options for a field
+// The key a column's filter is SENT under, which is not always the column's own
+// key: a display column can filter on a different server param via `filterKey`.
+const filterKeyFor = (field: TableField): string => field.filterKey ?? field.key;
+
+// The value that means "has no value" for a select filter (#106).
+const filterNullValueFor = (field: TableField): string => field.filterNullValue ?? 'null';
+
+/**
+ * Column header text. An explicitly empty `label` means an EMPTY header — an
+ * actions column headed `actions` (lowercase, as-keyed) is a leak, not a
+ * default. Only fall back when no label was declared at all.
+ */
+const headerLabel = (field: TableField, slotLabel?: string): string =>
+    field.label !== undefined ? field.label : (slotLabel || field.key);
+
 const getFieldFilterOptions = (field: TableField): FilterOption[] => {
+    const options: FilterOption[] = [];
+
+    // An "Unassigned"-style option, so a select filter can express "no value".
+    if (field.filterNullText) {
+        options.push({ value: filterNullValueFor(field), text: field.filterNullText });
+    }
+
     // If field has static filterOptions, use those
     if (field.filterOptions && field.filterOptions.length > 0) {
-        return field.filterOptions;
+        return [...options, ...field.filterOptions];
     }
 
-    // Otherwise, check for server-provided values
-    const serverValues = props.filterValues?.[field.key] || apiFilterValues.value[field.key];
+    // Otherwise, check for server-provided values (keyed by the filter key)
+    const serverValues =
+        props.filterValues?.[filterKeyFor(field)] ?? apiFilterValues.value[filterKeyFor(field)];
 
     if (serverValues && serverValues.length > 0) {
-        // Convert string array to FilterOption array
-        return serverValues.map(value => ({ value, text: value }));
+        return [...options, ...serverValues.map(value => ({ value, text: value }))];
     }
 
-    return [];
+    return options;
 };
 
 // LocalStorage key for perPage preference
@@ -1100,8 +1306,10 @@ watch(() => props.pagination?.per_page, (newPerPage) => {
 
 // Watch for external filter changes (when filters prop is controlled by parent)
 watch(() => props.filters, (newFilters, oldFilters) => {
-    // Only trigger refresh if filters prop is being used (not internal state)
-    if (props.filters === undefined) return;
+    // Only when the consumer CONTROLS filters. Uncontrolled, the prop is just a
+    // seed: `effectiveFilters` stays internal, so refreshing on a later prop
+    // change would fetch with filters the table isn't actually showing (#110).
+    if (!isControlled.filters || props.filters === undefined) return;
 
     // Only refresh if filters actually changed
     if (JSON.stringify(newFilters) === JSON.stringify(oldFilters)) return;
@@ -1111,15 +1319,13 @@ watch(() => props.filters, (newFilters, oldFilters) => {
         refresh();
     } else if (hasInertiaUrl.value && isInertiaMode.value && router) {
         // Inertia mode - trigger navigation with new filters
-        const currentSort = effectiveSortBy.value[0] || { key: 'created_at', order: 'desc' };
         router.get(
             props.inertiaUrl!,
             {
                 page: 1, // Reset to first page when filters change
-                sortBy: currentSort.key,
-                sortOrder: currentSort.order,
                 filters: newFilters,
                 perPage: effectivePerPage.value,
+                ...sortParams(effectiveSortBy.value),
             },
             { preserveState: true }
         );
@@ -1152,8 +1358,9 @@ watch(() => props.apiUrl, (newUrl, oldUrl) => {
 
 // Computed effective perPage (use external if provided, otherwise internal)
 const effectivePerPage = computed(() => {
-    // If external perPage prop is provided, use it
-    if (props.perPage !== undefined) {
+    // Only when the consumer is actually driving it (v-model). A bare
+    // `:per-page="50"` is an initial value — see `isControlled` (#110).
+    if (isControlled.perPage && props.perPage !== undefined) {
         return props.perPage;
     }
 
@@ -1163,7 +1370,7 @@ const effectivePerPage = computed(() => {
     }
 
     // For API mode, use internal state (which gets updated immediately on change)
-    // Don't use apiPaginationMeta.per_page here because it's from the previous request
+    // Don't use providerPagination.per_page here because it's from the previous request
     // and causes the select to flicker when user changes it
     return internalPerPage.value;
 });
@@ -1238,7 +1445,10 @@ const shouldShowPerPageSelector = computed(() => {
         ? clientSidePagination.value?.total || 0
         : isInertiaMode.value
             ? props.pagination?.total || 0
-            : apiPaginationMeta.value?.total || 0;
+            // Same source as the pager itself — reading apiPaginationMeta here
+            // hid the selector for a custom provider whose pagination comes
+            // from the `pagination` prop, while the page buttons still showed.
+            : providerPagination.value?.total || 0;
 
     return total >= smallestOption;
 });
@@ -1247,79 +1457,114 @@ const shouldShowPerPageSelector = computed(() => {
 const fieldsNeedingFilterValues = computed(() => {
     return props.fields
         .filter(field => field.filter === 'select' && (!field.filterOptions || field.filterOptions.length === 0))
-        .map(field => field.key);
+        .map(field => filterKeyFor(field));
 });
 
 // Error state for API mode
 const apiError = ref<string | null>(null);
 
-// Internal provider function when apiUrl is provided
+/**
+ * The active sort, or `null` when there is none.
+ *
+ * The header sort cycles asc → desc → *unsorted*, and in that third state
+ * BTable reports the column with no `order`. There is deliberately no fallback
+ * column here: sorting by a magic `created_at` when the user has asked for no
+ * sort means requesting a column the consumer never declared, which a strict
+ * endpoint (e.g. spatie's QueryBuilder, where an undeclared sort is a 400)
+ * rejects outright. No sort selected means no sort sent — the server applies
+ * its own default ordering. Pass `sortBy` to give the table an initial sort.
+ */
+const activeSort = (sortBy: readonly BTableSortBy[] | undefined) => {
+    const sort = sortBy?.[0];
+    if (!sort?.key || !sort.order) return null;
+    return { key: sort.key, order: sort.order };
+};
+
+// Sort params for a request — an empty object when nothing is sorted.
+const sortParams = (sortBy: readonly BTableSortBy[] | undefined) => {
+    const sort = activeSort(sortBy);
+    return sort ? { sortBy: sort.key, sortOrder: sort.order } : {};
+};
+
+// Internal provider function when apiUrl is provided. It deliberately does NOT
+// catch: `effectiveProvider` wraps every provider (including a consumer's own)
+// in one error handler, so no provider can fail silently.
 const internalProvider: BTableProvider<T> = async (context: Readonly<BTableProviderContext>) => {
     if (!props.apiUrl) return [];
 
-    try {
-        // Clear previous error
-        apiError.value = null;
-
-        const sort = context.sortBy && context.sortBy.length > 0
-            ? context.sortBy[0]
-            : { key: 'created_at', order: 'desc' };
-
-        // Build request parameters
-        const params: any = {
-            page: context.currentPage,
-            perPage: effectivePerPage.value,
-            sortBy: sort.key,
-            sortOrder: sort.order || 'desc',
-            filters: effectiveFilters.value,
-        };
-
-        // Request filter values on initial load
-        if (context.currentPage === 1 && fieldsNeedingFilterValues.value.length > 0 && Object.keys(apiFilterValues.value).length === 0) {
-            params.filterValues = fieldsNeedingFilterValues.value;
-        }
+    const params: any = {
+        page: context.currentPage,
+        perPage: effectivePerPage.value,
+        filters: effectiveFilters.value,
+        ...sortParams(context.sortBy),
+    };
 
-        const response = await axios.get(props.apiUrl, { params });
+    // Request filter values on initial load
+    if (context.currentPage === 1 && fieldsNeedingFilterValues.value.length > 0 && Object.keys(apiFilterValues.value).length === 0) {
+        params.filterValues = fieldsNeedingFilterValues.value;
+    }
 
-        // Extract and store pagination metadata for display
-        if (response.data.pagination) {
-            apiPaginationMeta.value = response.data.pagination;
-        }
+    const response = await axios.get(props.apiUrl, { params });
 
-        // Extract and store filter values
-        if (response.data.filterValues) {
-            apiFilterValues.value = { ...apiFilterValues.value, ...response.data.filterValues };
-        }
+    // Extract and store pagination metadata for display
+    if (response.data.pagination) {
+        apiPaginationMeta.value = response.data.pagination;
+    }
 
-        return response.data.data;
-    } catch (error: any) {
-        console.error('Failed to fetch data from API:', error);
+    // Extract and store filter values
+    if (response.data.filterValues) {
+        apiFilterValues.value = { ...apiFilterValues.value, ...response.data.filterValues };
+    }
 
-        // Surface error to user
-        const errorMessage = error?.response?.data?.message
-            || error?.message
-            || 'Failed to load data. Please try again.';
-        apiError.value = errorMessage;
+    return response.data.data;
+};
 
+/**
+ * Wraps whichever provider is in play — the built-in `apiUrl` one or a
+ * consumer's own `provider` — so a rejected fetch surfaces an error instead of
+ * rendering as zero rows. A failed query and a genuinely empty result look
+ * identical otherwise, which is how a broken table passes review and then shows
+ * a blank page to a user. A consumer's provider used to be the silent case: the
+ * error handling lived inside the internal one, so it never covered them.
+ */
+const wrappedProvider: BTableProvider<T> = async (context: Readonly<BTableProviderContext>) => {
+    const provider = props.provider || (props.apiUrl ? internalProvider : undefined);
+    if (!provider) return [];
+
+    apiError.value = null;
+    try {
+        return await provider(context);
+    } catch (error: any) {
+        // eslint-disable-next-line no-console
+        console.error('DXTable: the data provider failed', error);
+        apiError.value =
+            error?.response?.data?.message ||
+            error?.message ||
+            'Failed to load data. Please try again.';
         return [];
+    } finally {
+        providerHasRun.value = true;
     }
 };
 
-// Computed effective provider (use external if provided, otherwise internal)
-const effectiveProvider = computed(() => props.provider || (props.apiUrl ? internalProvider : undefined));
+// `wrappedProvider` is resolved fresh on each call, so this computed's IDENTITY
+// must not change when `apiUrl` does — BTable refetches when the provider
+// function changes, which would double every request that the explicit apiUrl
+// watcher already refetches (#82).
+const effectiveProvider = computed<BTableProvider<T> | undefined>(() =>
+    props.provider || props.apiUrl ? wrappedProvider : undefined,
+);
 
 const handlePageChange = (page: number) => {
     // If inertiaUrl provided, handle navigation automatically
     if (hasInertiaUrl.value && isInertiaMode.value && router) {
-        const currentSort = effectiveSortBy.value[0] || { key: 'created_at', order: 'desc' };
         router.get(
             props.inertiaUrl!,
             {
                 page,
-                sortBy: currentSort.key,
-                sortOrder: currentSort.order,
                 filters: effectiveFilters.value,
                 perPage: effectivePerPage.value,
+                ...sortParams(effectiveSortBy.value),
             },
             { preserveState: true }
         );
@@ -1353,8 +1598,8 @@ const handleSortChange = (sortBy: BTableSortBy[]) => {
         }
     }
 
-    // Update internal state if not using external sortBy
-    if (props.sortBy === undefined) {
+    // Write internal state unless the consumer controls it with v-model.
+    if (!isControlled.sortBy) {
         internalSortBy.value = normalizedSortBy;
     }
 
@@ -1363,28 +1608,26 @@ const handleSortChange = (sortBy: BTableSortBy[]) => {
 
     // Handle Inertia navigation automatically if URL provided
     if (hasInertiaUrl.value && isInertiaMode.value && router) {
-        // Build params based on whether sort is active
-        const params: any = {
-            page: props.pagination?.current_page || 1,
-            filters: effectiveFilters.value,
-            perPage: effectivePerPage.value,
-        };
-
-        // Add sort params only if sorting is active
-        if (normalizedSortBy && normalizedSortBy.length > 0 && normalizedSortBy[0].key) {
-            params.sortBy = normalizedSortBy[0].key;
-            params.sortOrder = normalizedSortBy[0].order || 'asc';
-        }
-
-        router.get(props.inertiaUrl!, params, { preserveState: true });
+        // The cleared state has a key but no order — `sortParams` sends nothing
+        // for it, rather than inventing an ascending sort the user didn't ask for.
+        router.get(
+            props.inertiaUrl!,
+            {
+                page: props.pagination?.current_page || 1,
+                filters: effectiveFilters.value,
+                perPage: effectivePerPage.value,
+                ...sortParams(normalizedSortBy),
+            },
+            { preserveState: true },
+        );
     }
 
-    // Emit simplified sortChange event for backward compatibility
-    if (isInertiaMode.value && normalizedSortBy && normalizedSortBy.length > 0 && normalizedSortBy[0].key) {
-        emit('sortChange', {
-            key: normalizedSortBy[0].key,
-            order: normalizedSortBy[0].order || 'asc'
-        });
+    // Emit simplified sortChange event for backward compatibility. Its payload
+    // can only express an ACTIVE sort, so the cleared state emits nothing here —
+    // listen to `update:sortBy` (which carries the empty array) to observe it.
+    const sort = activeSort(normalizedSortBy);
+    if (isInertiaMode.value && sort) {
+        emit('sortChange', sort);
     }
 };
 
@@ -1404,8 +1647,8 @@ const handlePerPageChange = (newPerPage: number | string | null | (number | stri
     }
     const perPageNum = typeof rawPerPage === 'string' ? parseInt(rawPerPage, 10) : rawPerPage;
 
-    // Update internal state if not using external perPage
-    if (props.perPage === undefined) {
+    // Write internal state unless the consumer controls it with v-model.
+    if (!isControlled.perPage) {
         internalPerPage.value = perPageNum;
     }
 
@@ -1423,15 +1666,13 @@ const handlePerPageChange = (newPerPage: number | string | null | (number | stri
 
     // Handle navigation automatically
     if (hasInertiaUrl.value && isInertiaMode.value && router) {
-        const currentSort = effectiveSortBy.value[0] || { key: 'created_at', order: 'desc' };
         router.get(
             props.inertiaUrl!,
             {
                 page: 1, // Reset to first page when changing perPage
-                sortBy: currentSort.key,
-                sortOrder: currentSort.order,
                 filters: effectiveFilters.value,
                 perPage: perPageNum,
+                ...sortParams(effectiveSortBy.value),
             },
             { preserveState: true }
         );
@@ -1455,8 +1696,8 @@ const handleFilterChange = (fieldKey: string, value: string) => {
         delete newFilters[fieldKey];
     }
 
-    // Update internal state if not using external filters
-    if (props.filters === undefined) {
+    // Write internal state unless the consumer controls it with v-model.
+    if (!isControlled.filters) {
         internalFilters.value = newFilters;
     }
 
@@ -1478,14 +1719,12 @@ const handleFilterChange = (fieldKey: string, value: string) => {
     filterDebounceTimer = setTimeout(() => {
         // Handle Inertia navigation automatically if URL provided
         if (hasInertiaUrl.value && isInertiaMode.value && router) {
-            const currentSort = effectiveSortBy.value[0] || { key: 'created_at', order: 'desc' };
             router.get(
                 props.inertiaUrl!,
                 {
                     page: 1, // Reset to first page when filtering
-                    sortBy: currentSort.key,
-                    sortOrder: currentSort.order,
                     filters: newFilters,
+                    ...sortParams(effectiveSortBy.value),
                 },
                 { preserveState: true }
             );
@@ -1519,6 +1758,12 @@ const refresh = () => {
 
 // Edit Modal State
 const showEditModal = ref(false);
+
+// Bumped on every modal open (edit or create) to key the DXForm subtree, so
+// each record gets fresh DXField instances. NOT bumped by the showUrl fetch,
+// which reseeds the SAME record — remounting there would discard edits the
+// user has already made while the fetch was in flight.
+const editFormInstanceKey = ref(0);
 const selectedItem = ref<T | null>(null);
 const editForm = ref<any>(null);
 const activeTabIndex = ref(0);
@@ -1553,7 +1798,74 @@ try {
 // Forward only the keyed edit slots the consumer actually provided, so
 // DXForm doesn't mistake an always-present (but empty) wrapper for
 // a real custom-value override.
+// Fields whose value actually belongs in the payload. A presentational field
+// (submit: false) renders but holds no data — see FieldDefinition.submit.
+const submittableEditFields = computed(() =>
+    (props.editFields ?? []).filter((field) => field.submit !== false),
+);
+
+// Enforced at SUBMIT, not just at seeding: the modal still renders every field,
+// so a `submit: false` control — or a `span` slot calling `update` — can write
+// its key back into the form data after seeding. Strip them on the way out.
+const nonSubmittedFieldKeys = computed(
+    () => new Set((props.editFields ?? []).filter((field) => field.submit === false).map((field) => field.key)),
+);
+
+const stripNonSubmittedFields = (data: Record<string, any>): Record<string, any> => {
+    if (nonSubmittedFieldKeys.value.size === 0) return data;
+    return Object.fromEntries(
+        Object.entries(data).filter(([key]) => !nonSubmittedFieldKeys.value.has(key)),
+    );
+};
+
 const tableSlots = useSlots();
+
+/*
+ * Slot forwarding to the inner table.
+ *
+ * DXTable used to forward only slots whose name started with `cell`, which is
+ * why it had no footer/totals row (#99), no empty state (#111) and no
+ * expandable rows (#112): BTable supports all three, but the slots never
+ * reached it. Anything BTable understands is now forwarded, with two
+ * deliberate exceptions that DXTable renders itself:
+ *
+ * - `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.
+ */
+const TABLE_SLOT_PREFIXES = ['cell(', 'foot('];
+const TABLE_SLOT_NAMES = new Set([
+    'custom-foot',
+    'empty',
+    'empty-filtered',
+    'row-expansion',
+    'table-busy',
+    'table-caption',
+    'table-colgroup',
+    'thead-sub',
+    'top-row',
+    'bottom-row',
+]);
+
+const isTableSlot = (name: string) =>
+    TABLE_SLOT_NAMES.has(name) || TABLE_SLOT_PREFIXES.some((prefix) => name.startsWith(prefix));
+
+const forwardedTableSlotNames = computed(() =>
+    Object.keys(tableSlots).filter((name) => isTableSlot(name)),
+);
+
+// Table-level features of the inner BTable, exposed verbatim and bound to all
+// three data modes from one place.
+const tablePassthroughProps = computed(() => ({
+    footClone: props.footClone,
+    showEmpty: props.showEmpty,
+    emptyText:
+        props.emptyText ??
+        (hasActiveFilters.value
+            ? `No ${pluralItemName.value} match your filters`
+            : `No ${pluralItemName.value} found`),
+    expandedItems: props.expandedItems,
+}));
 const editFieldKeys = computed<string[]>(() =>
     (props.editFields ?? []).map((field: any) => field.key),
 );
@@ -1580,6 +1892,11 @@ const tabAfterSlotKeys = computed(() =>
 const singularItemName = computed(() => props.itemName);
 const pluralItemName = computed(() => pluralize(props.itemName));
 
+// The built-in "New {item}" button needs both a create endpoint and consent.
+// Gating the header's own v-if on this (not on `createUrl`) means a table that
+// only had a header to host the button loses the empty header too.
+const showsCreateButton = computed(() => Boolean(props.createUrl) && props.showCreateButton);
+
 // Computed: Modal title (supports function)
 const computedModalTitle = computed(() => {
     if (isCreateMode.value) {
@@ -1620,19 +1937,22 @@ const handleRowClick = (item: T, index: number, event: MouseEvent) => {
         // seeding is synchronous — no interleaving between successive row opens.
         if (!editForm.value) {
             const formData: Record<string, any> = {};
-            props.editFields!.forEach(field => {
+            // Presentational fields (submit: false) lay the form out; they hold
+            // no data and must not be POSTed just because they were declared.
+            submittableEditFields.value.forEach(field => {
                 formData[field.key] = (item as any)[field.key] ?? field.default ?? '';
             });
             editForm.value = useForm(formData);
         } else {
             // Update existing form
-            props.editFields.forEach(field => {
+            submittableEditFields.value.forEach(field => {
                 editForm.value.data[field.key] = (item as any)[field.key] ?? field.default ?? '';
             });
             editForm.value.clearErrors();
         }
 
         // Open modal
+        editFormInstanceKey.value++;
         showEditModal.value = true;
 
         // Optionally replace the row-seeded data with the full record.
@@ -1656,7 +1976,7 @@ const fetchFullRecordForEdit = async (item: T) => {
 
         const record = response.data?.data ?? response.data;
         if (record && editForm.value) {
-            props.editFields!.forEach(field => {
+            submittableEditFields.value.forEach(field => {
                 if (Object.prototype.hasOwnProperty.call(record, field.key)) {
                     editForm.value.data[field.key] = record[field.key];
                 }
@@ -1696,17 +2016,18 @@ const handleCreateNew = () => {
 
     if (!editForm.value) {
         const formData: Record<string, any> = {};
-        props.editFields!.forEach(field => {
+        submittableEditFields.value.forEach(field => {
             formData[field.key] = field.default ?? '';
         });
         editForm.value = useForm(formData);
     } else {
         // Reset existing form to defaults
-        props.editFields!.forEach(field => {
+        submittableEditFields.value.forEach(field => {
             editForm.value.data[field.key] = field.default ?? '';
         });
         editForm.value.clearErrors();
     }
+    editFormInstanceKey.value++;
     showEditModal.value = true;
 };
 
@@ -1727,6 +2048,7 @@ const performSave = async () => {
     if (isCreateMode.value && props.createUrl) {
         try {
             await editForm.value.post(props.createUrl, {
+                transform: stripNonSubmittedFields,
                 onSuccess: (data: any) => {
                     createToast?.({
                         title: 'Success',
@@ -1779,6 +2101,7 @@ const performSave = async () => {
             const url = props.editUrl.replace(':id', itemId);
 
             await editForm.value.put(url, {
+                transform: stripNonSubmittedFields,
                 onSuccess: (data: any) => {
                     // Show success toast
                     createToast?.({
@@ -1926,13 +2249,13 @@ defineExpose({
 </script>
 
 <style scoped>
-/* Add pointer cursor to table rows when editFields is enabled */
+/* Rows that do something on click look like it — see `rowsAreInteractive`. */
 :deep(tbody tr) {
-    cursor: v-bind('editFields && editFields.length > 0 ? "pointer" : "default"');
+    cursor: v-bind(rowCursor);
 }
 
 :deep(tbody tr:hover) {
-    background-color: v-bind('editFields && editFields.length > 0 ? "var(--bs-table-hover-bg)" : "inherit"');
+    background-color: v-bind(rowHoverBackground);
 }
 
 /* Improve pagination button sizing to match form controls */