@omnitend/dashboard-for-laravel 0.33.1 → 0.35.0

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

@@ -31,7 +31,7 @@
                          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">
+                    <div v-if="error || (apiError && isProviderMode)" class="alert alert-danger">
                         {{ error || apiError }}
                     </div>
 
@@ -49,7 +49,7 @@
                     <DTable
                         v-else-if="isProviderMode || isClientSideMode || isInertiaMode"
                         ref="tableRef"
-                        :key="tableSlotSignature($slots)"
+                        :key="activeMode + ':' + tableSlotSignature($slots)"
                         :fields="fields"
                         :sort-by="effectiveSortBy"
                         :multisort="false"
@@ -163,6 +163,35 @@
                                     <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>
+
+                                <!-- ADDITIVE per-column header content (#99), rendered
+                                     INSIDE DXTable's own header cell rather than as a
+                                     `head(<key>)` override — an override would silently
+                                     drop the sort indicator and the field hint, which is
+                                     exactly why `head(...)` is not forwarded (see
+                                     `isTableSlot`). Placed after the label block and
+                                     BEFORE the sort indicator so a period total sits at
+                                     the top-right of the text area without displacing the
+                                     sort arrows, and lands in the same place whether or
+                                     not the column happens to be sortable. The wrapper is
+                                     only emitted when the slot exists, so a table without
+                                     one renders exactly as before. -->
+                                <div
+                                    v-if="$slots[`head-end(${field.key})`]"
+                                    class="dx-head-end flex-shrink-0 text-end"
+                                >
+                                    <!--
+                                      @slot head-end(<fieldKey>) Additive content at the end of a column's own header — a period total above a numeric column, a small badge — keeping DXTable's sort indicator and field hint. Not a `head()` override.
+                                      @binding {object} field The column's field definition.
+                                      @binding {string} label The column's resolved header label.
+                                    -->
+                                    <slot
+                                        :name="`head-end(${field.key})`"
+                                        :field="field"
+                                        :label="headerLabel(field, label)"
+                                    />
+                                </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;">
                                     <span :style="{ opacity: getFieldSortState(field.key) === 'asc' ? 1 : 0.3 }">▲</span>
                                     <span :style="{ opacity: getFieldSortState(field.key) === 'desc' ? 1 : 0.3 }">▼</span>
@@ -239,6 +268,13 @@
             :is-create-mode="isCreateMode"
             :pending-action="pendingAction"
             :delete-url="deleteUrl"
+            :layout="editLayout"
+            :label-cols="editLabelCols"
+            :card="editCard"
+            :item-name="itemName"
+            :save-text="saveText"
+            :create-text="createText"
+            :delete-text="deleteText"
             @save="handleEditSave"
             @cancel="handleEditCancel"
             @delete="handleDelete"
@@ -266,6 +302,7 @@ import { api } from "../../utils/api";
 import pluralize from "pluralize";
 import { useResourceEditor } from "../../composables/useResourceEditor";
 import { getByPath } from "../../utils/objectPath";
+import type { FieldDefinition, LabelCols } from "../../types";
 import DContainer from "../base/DContainer.vue";
 import DRow from "../base/DRow.vue";
 import DCol from "../base/DCol.vue";
@@ -351,6 +388,22 @@ export interface TableField {
     filterOptions?: FilterOption[];
     filterPlaceholder?: string;
 
+    /**
+     * For a `select` filter on a **client-side** table: derive the dropdown's
+     * options from the distinct values present in the loaded rows. Defaults to
+     * `true` — with no `filterOptions` and no server `filterValues` the
+     * alternative is an empty dropdown, which can only ever be a bug.
+     *
+     * Set `false` to opt out (e.g. a column whose raw values are opaque ids you
+     * would rather label yourself via `filterOptions`).
+     *
+     * Explicit `filterOptions` and server-supplied `filterValues` still WIN, in
+     * that order. Provider/API and Inertia modes ignore this flag: they only
+     * ever hold one page of rows, so there is no complete value set to derive
+     * from (see `getFieldFilterOptions`).
+     */
+    deriveFilterOptions?: boolean;
+
     /**
      * Fixed width for this column, applied via a `<colgroup>` `<col>`. A number
      * is treated as pixels (`200` → `200px`); a string is used verbatim
@@ -415,6 +468,27 @@ export interface EditTab {
     lazy?: boolean;
 }
 
+/**
+ * Discriminated data-source descriptor (#130). The additive, type-safe
+ * replacement for the legacy `items` / `provider` / `apiUrl` / `inertiaUrl` /
+ * `clientSide` prop matrix, in which every prop was independently optional and
+ * the mode was inferred by precedence — so invalid combinations compiled and
+ * some were silently ignored.
+ *
+ * Pass ONE `source`: the mode is explicit and its required companion prop is
+ * enforced by the compiler (`{ mode: 'provider' }` without a `provider` won't
+ * type-check). The legacy props still work and take over when `source` is
+ * omitted; a future major removes them with a codemod (#130 Phase 3).
+ *
+ * `apiAdapter` (transport translation) and `pagination` (server-supplied page
+ * metadata) stay sibling props — they're orthogonal to which mode is active.
+ */
+export type DXTableSource<TItem = any> =
+    | { mode: 'client'; items: TItem[] }
+    | { mode: 'provider'; provider: BTableProvider<TItem> }
+    | { mode: 'api'; url: string }
+    | { mode: 'inertia'; items: TItem[]; url?: string };
+
 export interface Props<TItem = any> {
     /** Table title */
     title?: string;
@@ -435,6 +509,14 @@ export interface Props<TItem = any> {
      *  backend convention that differs from dfl's (see DXTableApiAdapter). */
     apiAdapter?: DXTableApiAdapter;
 
+    /**
+     * Discriminated data-source (#130) — the type-safe alternative to the
+     * legacy `items` / `provider` / `apiUrl` / `inertiaUrl` / `clientSide`
+     * props. When set it WINS over those props; when omitted, the legacy props
+     * apply unchanged. See `DXTableSource`.
+     */
+    source?: DXTableSource<TItem>;
+
     /** Table field definitions */
     fields: TableField[];
 
@@ -522,12 +604,29 @@ export interface Props<TItem = any> {
      * borderless variant — the same header, filter row, table and pagination
      * rendered directly on the page background (no card border/shadow), for
      * data-heavy admin index pages that read as busy inside a card.
+     *
+     * The table renders FLUSH to the card border (rows and stripes reach the
+     * edge) while the header and pagination stay padded, which requires the card
+     * to clip to its radius (`overflow: hidden`).
+     *
+     * **Consequence for slot content:** anything you render into a slot that
+     * positions itself OUTSIDE the card and does not teleport is clipped at the
+     * card edge. Library components are unaffected — `DDropdown` teleports to
+     * `<body>` by default, and the column-filter menus position themselves
+     * `fixed` — so this only bites a hand-rolled `position: absolute` overlay
+     * (a custom popover in a `cell(<key>)` or `#header` slot). Teleport it, or
+     * use `:card="false"`. Narrowing the clip to the table region is tracked
+     * as #166.
      */
     card?: boolean;
 
     // Edit Modal Props
-    /** Form field definitions for edit modal (if provided, enables edit on row click) */
-    editFields?: any[]; // FieldDefinition[] - using any to avoid circular import
+    /**
+     * Form field definitions for edit modal (if provided, enables edit on row
+     * click). `import type` is erased at compile time, so this creates no
+     * runtime import cycle (#131).
+     */
+    editFields?: FieldDefinition[];
 
     /** Tab definitions for organizing edit modal content */
     editTabs?: EditTab[];
@@ -538,6 +637,43 @@ export interface Props<TItem = any> {
     /** Edit modal size */
     editModalSize?: 'sm' | 'md' | 'lg' | 'xl';
 
+    /**
+     * Field layout for the edit/create modal's form, forwarded to its `DXForm`
+     * ("vertical" = label above input, "horizontal" = label left). Defaults to
+     * **"horizontal"** to match the Omni Tend form convention (a raw modal form
+     * previously fell back to DXForm's vertical default, which looked out of
+     * place next to horizontal page forms). Pass `"vertical"` to opt out.
+     *
+     * `"auto"` hands the decision to `DXForm`'s container-width observer, which
+     * measures the FORM rather than the window — so a modal narrowed by its own
+     * breakpoint stacks to vertical even on a wide viewport, where a media query
+     * would still report "plenty of room". See `useContainerWidth`.
+     */
+    editLayout?: 'vertical' | 'horizontal' | 'auto';
+
+    /**
+     * Label column width for the edit modal's horizontal layout, forwarded to
+     * `DXForm`'s `labelCols` (a single width or a per-breakpoint object). Only
+     * meaningful when `editLayout` is "horizontal".
+     */
+    editLabelCols?: LabelCols;
+
+    /**
+     * Wrap the edit/create modal's form in a bordered card. Off by default (the
+     * modal body already provides a boundary); opt in for a more contained,
+     * panelled look around a tabbed edit form.
+     */
+    editCard?: boolean;
+
+    /** Override the modal's Save button label (default: "Save {item}"). */
+    saveText?: string;
+
+    /** Override the modal's Create button label (default: "Create {item}"). */
+    createText?: string;
+
+    /** Override the modal's Delete button label (default: "Delete {item}"). */
+    deleteText?: string;
+
     /** API endpoint pattern for updates (e.g., "/api/products/:id") */
     editUrl?: string;
 
@@ -663,6 +799,8 @@ const props = withDefaults(defineProps<Props<T>>(), {
     columnSize: "12",
     card: true,
     editModalSize: "lg",
+    editLayout: "horizontal",
+    editCard: false,
     showCreateButton: true,
     footClone: false,
     showEmpty: true,
@@ -704,15 +842,74 @@ const emit = defineEmits<{
     'update:busy': [busy: boolean];
 }>();
 
+// Effective data-source values (#130). Prefer an explicit `source` prop, else
+// fall back to the legacy `items`/`provider`/`apiUrl`/`inertiaUrl`/`clientSide`
+// props. Every read below (mode detection, provider, client-side pipeline,
+// inertia navigation) goes through these, so both APIs drive identical logic.
+const resolvedClientSide = computed(() =>
+    props.source ? props.source.mode === 'client' : props.clientSide === true,
+);
+const resolvedItems = computed<T[] | undefined>(() => {
+    if (props.source) {
+        return props.source.mode === 'client' || props.source.mode === 'inertia'
+            ? props.source.items
+            : undefined;
+    }
+    return props.items;
+});
+const resolvedProvider = computed<BTableProvider<T> | undefined>(() =>
+    props.source
+        ? props.source.mode === 'provider'
+            ? props.source.provider
+            : undefined
+        : props.provider,
+);
+const resolvedApiUrl = computed<string | undefined>(() =>
+    props.source
+        ? props.source.mode === 'api'
+            ? props.source.url
+            : undefined
+        : props.apiUrl,
+);
+const resolvedInertiaUrl = computed<string | undefined>(() =>
+    props.source
+        ? props.source.mode === 'inertia'
+            ? props.source.url
+            : undefined
+        : props.inertiaUrl,
+);
+
 // Mode detection
-const isProviderMode = computed(() => !props.clientSide && (!!props.provider || !!props.apiUrl));
-const isInertiaMode = computed(() => !props.clientSide && !props.provider && !props.apiUrl && !!props.items);
-const isClientSideMode = computed(() => props.clientSide === true && !!props.items);
-const hasInertiaUrl = computed(() => !!props.inertiaUrl);
-
-// Warn about invalid prop combinations in client-side mode
-if (props.clientSide && (props.apiUrl || props.inertiaUrl)) {
-    console.warn('[DXTable] clientSide mode ignores apiUrl and inertiaUrl props. Data is processed locally from items.');
+const isProviderMode = computed(() => !resolvedClientSide.value && (!!resolvedProvider.value || !!resolvedApiUrl.value));
+const isInertiaMode = computed(() => !resolvedClientSide.value && !resolvedProvider.value && !resolvedApiUrl.value && !!resolvedItems.value);
+const isClientSideMode = computed(() => resolvedClientSide.value && !!resolvedItems.value);
+const hasInertiaUrl = computed(() => !!resolvedInertiaUrl.value);
+
+// The active data-source mode, folded into the table's `:key` so a runtime
+// mode switch (e.g. `source` provider → client) REMOUNTS the DTable. bvn's
+// BTable caches its provider-fetched items internally and doesn't cleanly adopt
+// a fresh `:items` binding when the provider is removed — without a remount the
+// table shows "No items found" after switching to client/inertia mode. Stable
+// for a table that never changes mode, so it adds no spurious remounts.
+const activeMode = computed(() =>
+    isClientSideMode.value
+        ? 'client'
+        : isInertiaMode.value
+          ? 'inertia'
+          : isProviderMode.value
+            ? 'provider'
+            : 'empty',
+);
+
+// Warn about invalid LEGACY prop combinations (a `source` prop makes these
+// impossible at the type level, so it's exempt). #130: `clientSide + provider`
+// was previously uncovered by this guard.
+if (
+    !props.source &&
+    props.clientSide &&
+    (props.provider || props.apiUrl || props.inertiaUrl)
+) {
+    console.warn('[DXTable] clientSide mode ignores provider, apiUrl and inertiaUrl props. Data is processed locally from items.');
 }
 
 // Computed for effective busy state (provider mode uses 'busy', inertia uses 'loading')
@@ -835,7 +1032,7 @@ const paginationWasProvided = 'pagination' in (instance?.vnode.props ?? {});
 
 const providerPagination = computed<PaginationData | null>(() => {
     if (apiPaginationMeta.value) return apiPaginationMeta.value;
-    if (props.provider && paginationWasProvided && props.pagination) {
+    if (resolvedProvider.value && paginationWasProvided && props.pagination) {
         return props.pagination;
     }
     return null;
@@ -850,7 +1047,7 @@ const providerPagination = computed<PaginationData | null>(() => {
 const providerHasRun = ref(false);
 let warnedAboutProviderPagination = false;
 watch(
-    () => [props.provider, props.showPagination, providerPagination.value, providerHasRun.value] as const,
+    () => [resolvedProvider.value, props.showPagination, providerPagination.value, providerHasRun.value] as const,
     ([provider, showPagination, pagination, hasRun]) => {
         if (warnedAboutProviderPagination || !hasRun) return;
         if (provider && showPagination && !pagination) {
@@ -873,29 +1070,20 @@ const clientSideCurrentPage = ref(1);
 
 // Client-side filtered items
 const clientSideFilteredItems = computed<T[]>(() => {
-    if (!isClientSideMode.value || !props.items) return [];
+    if (!isClientSideMode.value || !resolvedItems.value) return [];
 
     const filters = effectiveFilters.value;
     const filterKeys = Object.keys(filters).filter(key => isActiveFilterValue(filters[key]));
 
     if (filterKeys.length === 0) {
-        return props.items;
+        return resolvedItems.value;
     }
 
-    return props.items.filter(item => {
+    return resolvedItems.value.filter(item => {
         return filterKeys.every(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.
-            // Both lookups are dot-path aware, so a nested payload filters (#121).
-            const itemValue =
-                field && hasFieldValue(item, key)
-                    ? fieldValueOf(item, key)
-                    : fieldValueOf(item, field?.key ?? key);
+            const itemValue = clientSideFilterValueOf(item, field, key);
 
             const matchesCandidate = (candidate: string): boolean => {
                 // The "no value" option (e.g. Unassigned) is the one filter that
@@ -1017,6 +1205,28 @@ const hasFieldValue = (item: unknown, key: string): boolean => {
     return getByPath(item as Record<string, any>, key) !== undefined;
 };
 
+/*
+ * The value a client-side filter compares against, for one row and one column.
+ *
+ * `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`). Read 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. Both
+ * lookups are dot-path aware, so a nested payload filters (#121).
+ *
+ * Extracted so the client-side row filter and the DERIVED select options (see
+ * `derivedFilterOptions`) resolve values through exactly the same rule — a
+ * derived option must never be a value the filter then fails to match.
+ */
+const clientSideFilterValueOf = (
+    item: unknown,
+    field: TableField | undefined,
+    filterKey: string,
+): any =>
+    field && hasFieldValue(item, filterKey)
+        ? fieldValueOf(item, filterKey)
+        : fieldValueOf(item, field?.key ?? filterKey);
+
 /*
  * Dotted-key columns DXTable must render itself, because bvn renders them empty
  * (see `fieldValueOf`). A consumer's own `cell(<key>)` slot always wins — it is
@@ -1101,6 +1311,115 @@ const filterAllLabelFor = (field: TableField): string =>
 const headerLabel = (field: TableField, slotLabel?: string): string =>
     field.label !== undefined ? field.label : (slotLabel || field.key);
 
+/**
+ * A select filter option's LABEL, honouring the column's own value→label
+ * formatting so the dropdown reads the way the column does (a `formatter`
+ * turning `19.99` into `$19.99`). The option's `value` stays RAW — that is what
+ * the client-side filter compares against (`String(itemValue) === candidate`),
+ * so formatting must never leak into it.
+ *
+ * `formatter` is bootstrap-vue-next's field formatter, `(value, key, item)`, and
+ * its first argument is by contract the value of `field.key` — the DISPLAYED
+ * column value. That matters when `filterKey` names a different property: the
+ * option's value must stay the FILTER value (that is what the row filter
+ * compares), but the formatter must still be handed the display value it was
+ * written against. Passing the filter value here fed a `customer` column's
+ * `(customer) => customer.name` formatter a numeric `customer_id`, which
+ * mislabels at best and throws at worst.
+ */
+const formattedFilterLabel = (field: TableField, item: unknown): string | null => {
+    if (typeof field.formatter !== 'function') return null;
+    const formatted = field.formatter(fieldValueOf(item, field.key), field.key, item);
+    if (formatted === null || formatted === undefined) return null;
+    return String(formatted);
+};
+
+/**
+ * Client-side auto-derived `filter: "select"` options, keyed by field key.
+ *
+ * Without this a client-side select column with no `filterOptions` and no
+ * server `filterValues` rendered an EMPTY dropdown — dead UI that can only be a
+ * bug — so this is on by default (opt out per column with
+ * `deriveFilterOptions: false`).
+ *
+ * It derives from `resolvedItems` (the FULL loaded row set) and deliberately
+ * NOT from `clientSideFilteredItems` or `clientSidePaginatedItems`:
+ *  - filtered set → picking a value would collapse the dropdown to that one
+ *    value, and the user could never get back to any other one;
+ *  - current page → the offered values would silently change as you page.
+ * Being a computed over `props.fields` + `resolvedItems` only, it is also
+ * structurally incapable of depending on the active filters — the cache is the
+ * guard, not just the comment.
+ */
+const derivedFilterOptions = computed<Record<string, FilterOption[]>>(() => {
+    // Only client-side mode has the complete row set. Provider/API and Inertia
+    // hold one page, so they take their options from the server instead.
+    if (!isClientSideMode.value) return {};
+
+    const rows = resolvedItems.value;
+    if (!rows || rows.length === 0) return {};
+
+    const optionsByFieldKey: Record<string, FilterOption[]> = {};
+
+    for (const field of props.fields) {
+        if (field.filter !== 'select') continue;
+        if (field.deriveFilterOptions === false) continue;
+        // Explicit options win outright (see `getFieldFilterOptions`), so don't
+        // spend a pass over every row producing a list nothing will read.
+        if (field.filterOptions && field.filterOptions.length > 0) continue;
+
+        const filterKey = filterKeyFor(field);
+
+        // Distinct values keyed by their STRING form, because that is exactly
+        // what the client-side select filter compares — so `1` and `"1"` are one
+        // option, and every option offered is one the filter can match. The
+        // first row carrying a value is kept alongside it, as the `item`
+        // argument the column's formatter expects.
+        const firstRowByValue = new Map<string, { rawValue: any; item: unknown }>();
+
+        // Candidates the filter reads as CONTROL values rather than data, so a
+        // row whose value collides with one can never be matched by selecting it
+        // (`handleSelectFilterChange` turns the "all" sentinel back into "no
+        // filter", and the null sentinel is intercepted upstream of the select's
+        // exact-match arm, where it means "has no value"). Offering such an
+        // option would be a dropdown entry that returns zero rows, and the null
+        // one would also duplicate the `filterNullText` entry's value.
+        const reservedCandidates = new Set<string>([FILTER_ALL_VALUE]);
+        if (field.filterNullText) reservedCandidates.add(filterNullValueFor(field));
+
+        for (const item of rows) {
+            const value = clientSideFilterValueOf(item, field, filterKey);
+            // null / undefined / '' are skipped deliberately: "has no value" is
+            // already a first-class, LABELLED option via `filterNullText`, and
+            // an unlabelled blank row in the list would be unusable.
+            if (value === null || value === undefined || value === '') continue;
+            const stringValue = String(value);
+            if (reservedCandidates.has(stringValue)) continue;
+            if (!firstRowByValue.has(stringValue)) {
+                firstRowByValue.set(stringValue, { rawValue: value, item });
+            }
+        }
+
+        const entries = [...firstRowByValue.entries()];
+
+        // Stable, human ordering: numeric when both values are numbers,
+        // otherwise a locale compare — the same rule the client-side sort uses,
+        // with `numeric: true` so "Item 2" precedes "Item 10".
+        entries.sort(([leftText, left], [rightText, right]) =>
+            typeof left.rawValue === 'number' && typeof right.rawValue === 'number'
+                ? left.rawValue - right.rawValue
+                : leftText.localeCompare(rightText, undefined, { numeric: true, sensitivity: 'base' }),
+        );
+
+        optionsByFieldKey[field.key] = entries.map(([stringValue, { item }]) => ({
+            value: stringValue,
+            text: formattedFilterLabel(field, item) ?? stringValue,
+        }));
+    }
+
+    return optionsByFieldKey;
+});
+
 const getFieldFilterOptions = (field: TableField): FilterOption[] => {
     const options: FilterOption[] = [];
 
@@ -1140,6 +1459,15 @@ const getFieldFilterOptions = (field: TableField): FilterOption[] => {
         return [...options, ...serverValues.map(value => ({ value, text: value }))];
     }
 
+    // Last resort, CLIENT-SIDE only: the distinct values present in the loaded
+    // rows. Precedence is deliberate — explicit `filterOptions`, then the
+    // server's `filterValues`, then what the data itself says. See
+    // `derivedFilterOptions` for why it derives from the unfiltered row set.
+    const derived = derivedFilterOptions.value[field.key];
+    if (derived && derived.length > 0) {
+        return [...options, ...derived];
+    }
+
     // No values to choose from — don't offer a lone "All x" that filters nothing.
     return [];
 };
@@ -1151,7 +1479,7 @@ const getFieldFilterOptions = (field: TableField): FilterOption[] => {
 // Returns null when there is nothing stable to key on — every read and write
 // guards on that, so a keyless table simply doesn't persist.
 const perPageStorageKey = computed<string | null>(() => {
-    const url = props.inertiaUrl || props.apiUrl;
+    const url = resolvedInertiaUrl.value || resolvedApiUrl.value;
     if (!url) return null;
     return `dxtable-perpage-${url.replace(/\//g, '-')}`;
 });
@@ -1232,7 +1560,7 @@ watch(() => JSON.stringify(props.filters ?? null), () => {
     } else if (hasInertiaUrl.value && isInertiaMode.value && router) {
         // Inertia mode - trigger navigation with new filters
         router.get(
-            props.inertiaUrl!,
+            resolvedInertiaUrl.value!,
             {
                 page: 1, // Reset to first page when filters change
                 filters: props.filters,
@@ -1248,8 +1576,15 @@ watch(() => JSON.stringify(props.filters ?? null), () => {
 // of BTable's provider context, so an api-url-only change doesn't re-invoke the
 // provider on its own — without this the table keeps showing the previous url's
 // rows until some other trigger (sort, per-page, create/edit/delete) fires.
-watch(() => props.apiUrl, (newUrl, oldUrl) => {
-    if (newUrl !== oldUrl && isProviderMode.value) {
+watch(() => resolvedApiUrl.value, (newUrl, oldUrl) => {
+    // `newUrl` must be truthy: an api-url → provider transition drops the url to
+    // `undefined` while still satisfying `isProviderMode` via the new provider.
+    // Without this guard both this watcher and the provider watcher below run
+    // their clear+refresh on that transition (bvn coalesces the two refreshes
+    // into one fetch, so it isn't an observable double-fetch — but the redundant
+    // work is avoidable). The provider watcher owns the url-removal transition;
+    // this one only fires for an actual new url.
+    if (newUrl && newUrl !== oldUrl && isProviderMode.value) {
         // Clear cached filter values and pagination when API endpoint changes.
         // The next provider call will request fresh filter values.
         apiFilterValues.value = {};
@@ -1268,6 +1603,25 @@ watch(() => props.apiUrl, (newUrl, oldUrl) => {
     }
 });
 
+// A `provider` swap (`:provider` or `source.provider` reassigned to a new
+// function) must refetch, exactly as an `apiUrl` swap does above. `effectiveProvider`'s
+// identity is deliberately STABLE (#82) so BTable doesn't refetch on its own
+// when the underlying provider changes — so, like the apiUrl watcher, force it.
+// Only fires for an actual provider function (apiUrl mode is covered above), and
+// `watch` skips the initial value, so no double-fetch on mount.
+watch(() => resolvedProvider.value, (newProvider, oldProvider) => {
+    if (newProvider !== oldProvider && !!newProvider) {
+        apiFilterValues.value = {};
+        apiPaginationMeta.value = null;
+        apiError.value = null;
+        const wasOnFirstPage = apiCurrentPage.value === 1;
+        apiCurrentPage.value = 1;
+        if (wasOnFirstPage) {
+            refresh();
+        }
+    }
+});
+
 // Computed effective perPage (use external if provided, otherwise internal)
 const effectivePerPage = computed(() => {
     // Only when the consumer is actually driving it (v-model). A bare
@@ -1330,7 +1684,7 @@ const clientSidePaginatedItems = computed<T[]>(() => {
 // Client-side pagination metadata
 const clientSidePagination = computed<PaginationData>(() => {
     const total = clientSideFilteredItems.value.length;
-    const totalUnfiltered = props.items?.length || 0;
+    const totalUnfiltered = resolvedItems.value?.length || 0;
     const perPage = effectivePerPage.value;
     const lastPage = clientSideLastPage.value;
 
@@ -1389,7 +1743,12 @@ const shouldShowPerPageSelector = computed(() => {
     return total >= smallestOption;
 });
 
-// Detect which fields need server filter values
+// Detect which fields need server filter values.
+//
+// Client-side derived options (`derivedFilterOptions`) deliberately do NOT
+// shrink this list: it is only ever read by `internalProvider`, i.e. API mode,
+// and `isProviderMode` requires `!resolvedClientSide` — the two modes are
+// mutually exclusive, so a client-side derived column can never appear here.
 const fieldsNeedingFilterValues = computed(() => {
     return props.fields
         .filter(field => field.filter === 'select' && (!field.filterOptions || field.filterOptions.length === 0))
@@ -1426,7 +1785,7 @@ const sortParams = (sortBy: readonly BTableSortBy[] | undefined) => {
 // 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 [];
+    if (!resolvedApiUrl.value) return [];
 
     const params: any = {
         page: context.currentPage,
@@ -1448,7 +1807,7 @@ const internalProvider: BTableProvider<T> = async (context: Readonly<BTableProvi
         ? props.apiAdapter.request(params)
         : params;
 
-    const response = await api.get<any>(props.apiUrl, wireParams);
+    const response = await api.get<any>(resolvedApiUrl.value, wireParams);
 
     // Adapt a foreign response envelope back into the dfl shape. Gets the
     // ORIGINAL dfl-shape params (page/perPage/…) for context, since a foreign
@@ -1485,14 +1844,24 @@ const internalProvider: BTableProvider<T> = async (context: Readonly<BTableProvi
  * 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.
  */
+// Monotonic generation for provider calls. When a provider is swapped (or a
+// refetch supersedes an in-flight call), a still-pending older call that later
+// REJECTS must not publish its error over the newer call's rows — bvn already
+// discards a superseded call's rows, but `apiError` isn't otherwise guarded.
+let providerGeneration = 0;
+
 const wrappedProvider: BTableProvider<T> = async (context: Readonly<BTableProviderContext>) => {
-    const provider = props.provider || (props.apiUrl ? internalProvider : undefined);
+    const provider = resolvedProvider.value || (resolvedApiUrl.value ? internalProvider : undefined);
     if (!provider) return [];
 
+    const generation = ++providerGeneration;
     apiError.value = null;
     try {
         return await provider(context);
     } catch (error: any) {
+        // Superseded by a newer provider call — its result/error owns the table
+        // now, so drop this stale rejection silently.
+        if (generation !== providerGeneration) return [];
         // eslint-disable-next-line no-console
         console.error('DXTable: the data provider failed', error);
         // `error.message` covers the internal provider's ApiError; the
@@ -1512,14 +1881,14 @@ const wrappedProvider: BTableProvider<T> = async (context: Readonly<BTableProvid
 // 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,
+    resolvedProvider.value || resolvedApiUrl.value ? wrappedProvider : undefined,
 );
 
 const handlePageChange = (page: number) => {
     // If inertiaUrl provided, handle navigation automatically
     if (hasInertiaUrl.value && isInertiaMode.value && router) {
         router.get(
-            props.inertiaUrl!,
+            resolvedInertiaUrl.value!,
             {
                 page,
                 filters: effectiveFilters.value,
@@ -1574,7 +1943,7 @@ const tableModeBindings = computed<Record<string, unknown>>(() => {
         return { items: clientSidePaginatedItems.value, noLocalSorting: true };
     }
     // inertia
-    return { items: props.items, noLocalSorting: true, busy: effectiveBusy.value };
+    return { items: resolvedItems.value, noLocalSorting: true, busy: effectiveBusy.value };
 });
 
 /*
@@ -1627,7 +1996,7 @@ const handleSortChange = (sortBy: BTableSortBy[]) => {
         // 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!,
+            resolvedInertiaUrl.value!,
             {
                 page: props.pagination?.current_page || 1,
                 filters: effectiveFilters.value,
@@ -1684,7 +2053,7 @@ const handlePerPageChange = (newPerPage: number | string | null | (number | stri
     // Handle navigation automatically
     if (hasInertiaUrl.value && isInertiaMode.value && router) {
         router.get(
-            props.inertiaUrl!,
+            resolvedInertiaUrl.value!,
             {
                 page: 1, // Reset to first page when changing perPage
                 filters: effectiveFilters.value,
@@ -1737,7 +2106,7 @@ const handleFilterChange = (fieldKey: string, value: string | string[]) => {
         // Handle Inertia navigation automatically if URL provided
         if (hasInertiaUrl.value && isInertiaMode.value && router) {
             router.get(
-                props.inertiaUrl!,
+                resolvedInertiaUrl.value!,
                 {
                     page: 1, // Reset to first page when filtering
                     filters: newFilters,
@@ -1769,7 +2138,7 @@ const refresh = () => {
         (tableRef.value as any).refresh();
     }
     // Inertia mode: reload current page to refresh data
-    else if (isInertiaMode.value && props.inertiaUrl && router) {
+    else if (isInertiaMode.value && resolvedInertiaUrl.value && router) {
         router.reload();
     }
 };
@@ -1786,6 +2155,12 @@ const refresh = () => {
  * - `head(<key>)` — DXTable draws its own column headers (sort indicators,
  *   field hints). Forwarding a consumer's would silently drop those.
  * - `thead-top`   — DXTable renders the inline filter row there.
+ *
+ * `head-end(<key>)` is DXTable's OWN additive header slot (#99) and is likewise
+ * not forwarded: the inner table has no such slot, and the prefixes below are
+ * matched with `startsWith`, so it must not begin with `cell(`/`foot(` either —
+ * `head-end(` satisfies both. It is also excluded from `tableSlotSignature`
+ * (which filters on `isTableSlot`), so adding one never remounts the table.
  */
 const TABLE_SLOT_PREFIXES = ['cell(', 'foot('];
 const TABLE_SLOT_NAMES = new Set([