@omnitend/dashboard-for-laravel 0.22.0 → 0.23.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"
@@ -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 -->
@@ -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 -->
@@ -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>
 
@@ -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";
@@ -842,6 +849,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 +918,9 @@ const props = withDefaults(defineProps<Props<T>>(), {
     columnSize: "12",
     card: true,
     editModalSize: "lg",
+    showCreateButton: true,
+    footClone: false,
+    showEmpty: true,
 });
 
 const emit = defineEmits<{
@@ -899,6 +948,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 +972,51 @@ 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 hasUpdateListener = (name: string): boolean => {
+    const vnodeProps = instance?.vnode.props ?? {};
+    // `v-model:per-page` compiles to `onUpdate:perPage`, but a hand-written
+    // `@update:per-page` stays hyphenated — accept either.
+    const hyphenated = name.replace(/[A-Z]/g, (char) => `-${char.toLowerCase()}`);
+    return `onUpdate:${name}` in vnodeProps || `onUpdate:${hyphenated}` in vnodeProps;
+};
+
+const isControlled = {
+    perPage: hasUpdateListener('perPage'),
+    sortBy: hasUpdateListener('sortBy'),
+    filters: hasUpdateListener('filters'),
+};
+
+// 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));
@@ -1111,15 +1196,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 +1235,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;
     }
 
@@ -1253,73 +1337,106 @@ const fieldsNeedingFilterValues = computed(() => {
 // 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 [];
     }
 };
 
-// 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 +1470,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 +1480,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 +1519,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 +1538,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 +1568,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 +1591,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 +1630,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);
@@ -1554,6 +1671,53 @@ try {
 // DXForm doesn't mistake an always-present (but empty) wrapper for
 // a real custom-value override.
 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 +1744,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) {
@@ -1633,6 +1802,7 @@ const handleRowClick = (item: T, index: number, event: MouseEvent) => {
         }
 
         // Open modal
+        editFormInstanceKey.value++;
         showEditModal.value = true;
 
         // Optionally replace the row-seeded data with the full record.
@@ -1707,6 +1877,7 @@ const handleCreateNew = () => {
         });
         editForm.value.clearErrors();
     }
+    editFormInstanceKey.value++;
     showEditModal.value = true;
 };