@omnitend/dashboard-for-laravel 0.32.0 → 0.33.1

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

@@ -229,6 +229,65 @@
         <DFormText v-if="field.help">{{ field.help }}</DFormText>
     </div>
 
+    <!-- Switch-list (#160): a list of labelled boolean toggles as config, not
+         markup. One real DFormGroup per option row — the ONLY correct source of
+         the label/content grid (hardcoding col classes is exactly the drift
+         this field exists to end) — with the option text in the label column
+         and a compact track switch (not the filled-box DXSwitch, too heavy in
+         a dense list) in the content column. The model is an array of selected
+         option values, like checkbox-group. -->
+    <div v-else-if="field.type === 'switch-list'" :class="field.class || 'mb-3'">
+        <div
+            v-if="!hideLabel && field.label"
+            class="dx-switch-list-heading text-muted fw-semibold"
+        >
+            <DXFieldLabel :label="resolvedLabel" :info="resolvedInfo" />
+        </div>
+        <div
+            v-for="option in resolvedOptions ?? []"
+            :key="String(option.value)"
+            class="dx-switch-list-row"
+        >
+            <DFormGroup v-bind="switchListRowAttrs" class="mb-0 align-items-center">
+                <template #label>
+                    <DXFieldLabel
+                        :label="option.text"
+                        :title="option.description"
+                    />
+                </template>
+                <div class="dx-switch-list-control">
+                    <DFormCheckbox
+                        switch
+                        :class="field.switchVariant === 'neutral' ? 'switch-neutral' : undefined"
+                        :model-value="switchListIsOn(option)"
+                        :disabled="isDisabled || isReadonly || isPlaintext || option.disabled === true"
+                        :aria-label="option.text"
+                        @update:model-value="setSwitchListOn(option, $event === true)"
+                    />
+                    <!--
+                      @slot Extra per-row content beside a switch-list row's toggle (e.g. a notes input the consumer binds to their own model).
+                      @binding {FieldOption} option The option this row renders.
+                      @binding {boolean} on Whether the row's switch is currently on.
+                    -->
+                    <slot
+                        name="switch-list-item"
+                        :option="option"
+                        :on="switchListIsOn(option)"
+                    />
+                </div>
+            </DFormGroup>
+        </div>
+
+        <DFormInvalidFeedback v-if="form.hasError(errorKey)" force-show>
+            {{ form.getError(errorKey) }}
+        </DFormInvalidFeedback>
+        <slot name="info" :field="field" :model="model" />
+        <DFormText v-if="resolvedHint || $slots.hint" class="text-muted">
+            <slot name="hint" :field="field" :model="model">{{ resolvedHint }}</slot>
+        </DFormText>
+        <DFormText v-if="field.help">{{ field.help }}</DFormText>
+    </div>
+
     <!-- Repeater: nested, repeatable sub-form -->
     <div v-else-if="field.type === 'repeater'" :class="field.class || 'mb-3'">
         <DFormGroup v-bind="repeaterHorizontalAttrs">
@@ -402,35 +461,31 @@
             />
         </div>
 
-        <!-- Currency / percentage: numeric input with an affix -->
-        <DInputGroup v-else-if="field.type === 'currency' || field.type === 'percentage'">
-            <template v-if="field.type === 'currency'" #prepend>
-                <span class="input-group-text">{{ field.currencySymbol || "£" }}</span>
-            </template>
+        <!-- Currency: the DXCurrencyInput leaf (#152) owns the symbol prepend,
+             the blur-padded display (#69), empty -> null, and the minor-units
+             model scaling (#116). -->
+        <DXCurrencyInput
+            v-else-if="field.type === 'currency'"
+            :model-value="fieldValue"
+            :currency-symbol="field.currencySymbol || '£'"
+            :decimals="field.decimals ?? 2"
+            :minor-units="field.minorUnits ?? false"
+            :step="field.step"
+            :required="field.required"
+            :placeholder="field.placeholder"
+            :min="field.min"
+            :max="field.max"
+            :state="fieldState"
+            :disabled="isDisabled"
+            :readonly="isReadonly || isPlaintext"
+            :plaintext="isPlaintext"
+            v-bind="inputPropsWithGuards"
+            @update:model-value="setValue($event)"
+        />
 
-            <!-- Currency: the displayed text is padded to the minor-unit
-                 precision on blur/seed (e.g. `3.8` -> `3.80`); the model stays
-                 a plain number and typing is never reformatted mid-edit. -->
+        <!-- Percentage: numeric input with an affix -->
+        <DInputGroup v-else-if="field.type === 'percentage'">
             <DFormInput
-                v-if="field.type === 'currency'"
-                :model-value="currencyDisplayValue"
-                type="number"
-                :required="field.required"
-                :placeholder="field.placeholder"
-                :step="field.step ?? '0.01'"
-                :min="field.min"
-                :max="field.max"
-                :state="fieldState"
-                :disabled="isDisabled"
-                :readonly="isReadonly || isPlaintext"
-                :plaintext="isPlaintext"
-                v-bind="inputPropsWithGuards"
-                @input="handleCurrencyInput"
-                @focus="handleCurrencyFocus"
-                @blur="handleCurrencyBlur"
-            />
-            <DFormInput
-                v-else
                 v-model="numericInputValue"
                 type="number"
                 :required="field.required"
@@ -445,7 +500,7 @@
                 v-bind="inputPropsWithGuards"
             />
 
-            <template v-if="field.type === 'percentage'" #append>
+            <template #append>
                 <span class="input-group-text">%</span>
             </template>
         </DInputGroup>
@@ -576,6 +631,7 @@ import DInputGroup from "../base/DInputGroup.vue";
 import DAutocomplete from "../base/DAutocomplete.vue";
 import DButton from "../base/DButton.vue";
 import DXFieldLabel from "./DXFieldLabel.vue";
+import DXCurrencyInput from "./DXCurrencyInput.vue";
 import type { UseFormReturn } from "../../composables/useForm";
 import type { FieldDefinition, FieldOption, FieldType, LabelCols } from "../../types";
 import { getByPath, setByPath } from "../../utils/objectPath";
@@ -849,59 +905,51 @@ function setValue(value: any): void {
     props.form.clearError(errorKey.value);
 }
 
-// ————————————————— currency display formatting (#69)
-
-// The model stays a plain number throughout; only the input's *displayed*
-// text is padded to the minor-unit precision (`3.8` -> `3.80`), on blur and on
-// initial seed. Reformatting reactively on every keystroke (rather than on
-// blur) would fight the user mid-edit — e.g. rounding "3." to "3.00" before
-// they've typed the fractional digits — so a local ref tracks the shown text
-// independently of the numeric model, and is only resynced from the model
-// while the input isn't focused.
-const currencyDecimals = computed(() => props.field.decimals ?? 2);
-const isCurrencyFocused = ref(false);
-const currencyDisplayValue = ref("");
-
-function formatCurrency(value: any): string {
-    if (value === null || value === undefined || value === "") return "";
-    const num = Number(value);
-    if (!Number.isFinite(num)) return String(value);
-    return num.toFixed(currencyDecimals.value);
-}
+const fieldState = computed(() => props.form.getState(errorKey.value));
 
-watch(
-    () => fieldValue.value,
-    (value) => {
-        if (isCurrencyFocused.value) return;
-        currencyDisplayValue.value = formatCurrency(value);
-    },
-    { immediate: true },
+const resolvedLabel = computed(
+    () => resolveMaybe(props.field.label) ?? props.field.key,
 );
 
-function handleCurrencyFocus(): void {
-    isCurrencyFocused.value = true;
-}
+const resolvedHint = computed(() => resolveMaybe(props.field.hint));
 
-function handleCurrencyInput(event: Event): void {
-    const raw = (event.target as HTMLInputElement).value;
-    currencyDisplayValue.value = raw;
-    setValue(raw);
-}
+const resolvedInfo = computed(() => resolveMaybe(props.field.info));
 
-function handleCurrencyBlur(): void {
-    isCurrencyFocused.value = false;
-    currencyDisplayValue.value = formatCurrency(fieldValue.value);
-}
+// ————————————————— switch-list (#160)
 
-const fieldState = computed(() => props.form.getState(errorKey.value));
+// Row grid for switch-list option rows. Deliberately NOT `horizontalAttrs`:
+// that computed empties itself under `hideLabel`, which is right for the
+// FIELD label but would collapse every option row's label column too —
+// `hideLabel` on a switch-list should drop only the section heading.
+const switchListRowAttrs = computed<Record<string, any>>(() =>
+    isHorizontal.value
+        ? {
+              ...labelColsAttrs(props.labelCols ?? 3),
+              labelClass: "text-sm-end dx-field-label-col",
+          }
+        : {},
+);
 
-const resolvedLabel = computed(
-    () => resolveMaybe(props.field.label) ?? props.field.key,
+// The model is an array of selected option values, exactly like
+// checkbox-group, so seeding/validation/diffing need nothing new. Toggling a
+// row adds/removes its option's value; `setValue` also clears the field error.
+const switchListValues = computed<any[]>(() =>
+    Array.isArray(fieldValue.value) ? fieldValue.value : [],
 );
 
-const resolvedHint = computed(() => resolveMaybe(props.field.hint));
+function switchListIsOn(option: FieldOption): boolean {
+    return switchListValues.value.includes(option.value);
+}
 
-const resolvedInfo = computed(() => resolveMaybe(props.field.info));
+function setSwitchListOn(option: FieldOption, on: boolean): void {
+    const current = switchListValues.value;
+    if (on === current.includes(option.value)) return;
+    setValue(
+        on
+            ? [...current, option.value]
+            : current.filter((value) => value !== option.value),
+    );
+}
 
 // ————————————————— switch (toggle) field
 
@@ -1101,6 +1149,29 @@ onBeforeUnmount(() => {
 </script>
 
 <style scoped>
+/* Switch-list rows (#160): compact rhythm with a divider between rows. The
+   vertical centring of label vs switch is the `align-items-center` utility on
+   each row's DFormGroup (its horizontal root IS the .row element), so no
+   deep selector into bvn internals is needed here. */
+.dx-switch-list-row {
+    padding: 0.25rem 0;
+    border-bottom: 1px solid var(--bs-border-color);
+}
+
+.dx-switch-list-row:last-of-type {
+    border-bottom: 0;
+}
+
+.dx-switch-list-heading {
+    margin-bottom: 0.25rem;
+}
+
+.dx-switch-list-control {
+    display: flex;
+    align-items: center;
+    gap: 0.75rem;
+}
+
 .dx-field-image-preview {
     max-width: 160px;
     max-height: 160px;

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

@@ -89,6 +89,7 @@ function fieldSlotMap(): Record<string, string> {
     ["info-popover", `info-popover(${key})`],
     ["hint", `hint(${key})`],
     ["repeater-row", `repeater-row(${key})`],
+    ["switch-list-item", `switch-list-item(${key})`],
   ];
   for (const [target, source] of candidates) {
     if (slots[source]) map[target] = source;

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

@@ -108,10 +108,22 @@
                                         @update:model-value="handleFilterChange(filterKeyFor(field), $event as string)"
                                     />
 
+                                    <!-- Multi-value Select Filter (#51): several values at once; the filters entry is an array -->
+                                    <DAutocomplete
+                                        v-else-if="field.filter === 'select' && field.filterMultiple"
+                                        :model-value="multiFilterValueFor(field)"
+                                        :options="getFieldFilterOptions(field)"
+                                        :placeholder="field.filterPlaceholder || filterAllLabelFor(field)"
+                                        size="sm"
+                                        multiple
+                                        open-on-focus
+                                        @update:model-value="handleMultiSelectFilterChange(field, $event)"
+                                    />
+
                                     <!-- Select Filter: typeahead — browse the full list on focus, or type to narrow; clear (✕) resets to "no filter" -->
                                     <DAutocomplete
                                         v-else-if="field.filter === 'select'"
-                                        :model-value="effectiveFilters[filterKeyFor(field)] || ''"
+                                        :model-value="(effectiveFilters[filterKeyFor(field)] as string) || ''"
                                         :options="getFieldFilterOptions(field)"
                                         :placeholder="field.filterPlaceholder || filterAllLabelFor(field)"
                                         size="sm"
@@ -250,7 +262,7 @@
 <script setup lang="ts" generic="T = any">
 import { computed, getCurrentInstance, ref, watch } from "vue";
 import { router } from "@inertiajs/vue3";
-import axios from "axios";
+import { api } from "../../utils/api";
 import pluralize from "pluralize";
 import { useResourceEditor } from "../../composables/useResourceEditor";
 import { getByPath } from "../../utils/objectPath";
@@ -272,6 +284,23 @@ export interface FilterOption {
     text: string;
 }
 
+/**
+ * Adapts the built-in `apiUrl` provider's request/response to a backend whose
+ * convention differs from dfl's (spatie query-builder params, an envelope
+ * without the `{data, pagination}` shape). The sanctioned replacement for the
+ * axios-interceptor bridges #132 removed the route for: `request` maps the
+ * outgoing params (its return is what goes on the wire); `response` maps the
+ * body back, receiving the ORIGINAL dfl-shape params (`page`, `perPage`, …)
+ * so it can synthesize paginator metadata a foreign envelope lacks.
+ */
+export interface DXTableApiAdapter {
+    request?: (params: Record<string, any>) => Record<string, any>;
+    response?: (
+        body: any,
+        context: { params: Record<string, any> },
+    ) => { data: any[]; pagination?: PaginationData; filterValues?: Record<string, string[]> };
+}
+
 export interface TableField {
     key: string;
     label?: string;
@@ -286,6 +315,18 @@ export interface TableField {
      */
     filterKey?: string;
 
+    /**
+     * For a `select` filter: allow SEVERAL values at once (#51). The filter
+     * renders as a multi-select typeahead, the filters map holds an ARRAY of
+     * the chosen option values, and the query string carries Laravel bracket
+     * notation (`filters[status][]=active&filters[status][]=pending`).
+     * Client-side, a row matches when its value equals ANY chosen value. An
+     * empty selection means "no filter". The "All …" reset row is omitted in
+     * this mode (removing the chips/✕ is the way back); `filterNullText`
+     * stays available as a choosable value.
+     */
+    filterMultiple?: boolean;
+
     /**
      * For a `select` filter: adds an option meaning "has no value", e.g.
      * `filterNullText: "Unassigned"` on an assignee column. Selecting it sends
@@ -390,14 +431,19 @@ export interface Props<TItem = any> {
     /** API endpoint URL for auto-provider mode (alternative to provider function) */
     apiUrl?: string;
 
+    /** Adapts the built-in provider's request params / response body to a
+     *  backend convention that differs from dfl's (see DXTableApiAdapter). */
+    apiAdapter?: DXTableApiAdapter;
+
     /** Table field definitions */
     fields: TableField[];
 
     /** Sort configuration (v-model support) */
     sortBy?: BTableSortBy[];
 
-    /** Filter values (v-model support) - key is field key, value is filter string */
-    filters?: Record<string, string>;
+    /** Filter values (v-model support) - key is field key, value is the filter
+     *  string, or an ARRAY of values for a `filterMultiple` column (#51). */
+    filters?: Record<string, string | string[]>;
 
     /** Dynamic filter options from server - key is field key, value is array of values */
     filterValues?: Record<string, string[]>;
@@ -629,7 +675,7 @@ const emit = defineEmits<{
     /** Emitted (Inertia mode) when the sort column or direction changes, with the active field key and order. */
     sortChange: [sort: { key: string; order: 'asc' | 'desc' }];
     /** Emitted when the inline column filter values change (debounced for server modes, immediate for client-side). Payload is the full filter map. */
-    filterChange: [filters: Record<string, string>];
+    filterChange: [filters: Record<string, string | string[]>];
     /** Emitted when the per-page selector value changes. Payload is the new page size. */
     perPageChange: [perPage: number];
     /** Emitted when a table row is clicked, with the row item, its index, and the click event. */
@@ -651,7 +697,7 @@ const emit = defineEmits<{
     /** `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>];
+    'update:filters': [filters: Record<string, string | string[]>];
     /** `v-model:perPage` update, emitted with the new page size when the per-page selector changes. */
     'update:perPage': [perPage: number];
     /** `v-model:busy` update, forwarded from the underlying table's provider loading state (provider mode). */
@@ -749,7 +795,7 @@ const effectiveSortBy = computed(() =>
 );
 
 // Internal filters state, seeded from the prop when it's an initial value.
-const internalFilters = ref<Record<string, string>>({ ...(props.filters ?? {}) });
+const internalFilters = ref<Record<string, string | string[]>>({ ...(props.filters ?? {}) });
 
 const effectiveFilters = computed(() =>
     isControlled.filters && props.filters !== undefined ? props.filters : internalFilters.value,
@@ -758,10 +804,15 @@ const effectiveFilters = computed(() =>
 // Computed: check if any field has filtering enabled
 const hasFilters = computed(() => props.fields.some(field => field.filter !== false && field.filter !== undefined));
 
+// Whether a filter map entry actually filters anything: a non-blank string,
+// or a non-empty array for a `filterMultiple` column (#51).
+const isActiveFilterValue = (value: string | string[] | undefined): boolean =>
+    Array.isArray(value) ? value.length > 0 : value !== undefined && value !== null && value.trim() !== '';
+
 // Computed: check if any filters are currently active
 const hasActiveFilters = computed(() => {
     const filters = effectiveFilters.value;
-    return Object.keys(filters).some(key => filters[key] && filters[key].trim() !== '');
+    return Object.keys(filters).some(key => isActiveFilterValue(filters[key]));
 });
 
 // API mode pagination metadata (extracted from responses)
@@ -825,7 +876,7 @@ const clientSideFilteredItems = computed<T[]>(() => {
     if (!isClientSideMode.value || !props.items) return [];
 
     const filters = effectiveFilters.value;
-    const filterKeys = Object.keys(filters).filter(key => filters[key] && filters[key].trim() !== '');
+    const filterKeys = Object.keys(filters).filter(key => isActiveFilterValue(filters[key]));
 
     if (filterKeys.length === 0) {
         return props.items;
@@ -833,7 +884,6 @@ const clientSideFilteredItems = computed<T[]>(() => {
 
     return props.items.filter(item => {
         return filterKeys.every(key => {
-            const filterValue = filters[key].trim().toLowerCase();
             // 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
@@ -847,39 +897,47 @@ const clientSideFilteredItems = computed<T[]>(() => {
                     ? fieldValueOf(item, key)
                     : fieldValueOf(item, 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 === '';
-            }
+            const matchesCandidate = (candidate: string): boolean => {
+                // The "no value" option (e.g. Unassigned) is the one filter that
+                // MATCHES an absent value rather than failing on it.
+                if (field?.filterNullText && candidate === filterNullValueFor(field)) {
+                    return itemValue === null || itemValue === undefined || itemValue === '';
+                }
 
-            if (itemValue === null || itemValue === undefined) {
-                return false;
-            }
+                if (itemValue === null || itemValue === undefined) {
+                    return false;
+                }
 
-            const filterType = field?.filter;
+                const filterValue = candidate.trim().toLowerCase();
 
-            switch (filterType) {
-                case 'text':
-                    // Case-insensitive contains search
-                    return String(itemValue).toLowerCase().includes(filterValue);
+                switch (field?.filter) {
+                    case 'text':
+                        // Case-insensitive contains search
+                        return String(itemValue).toLowerCase().includes(filterValue);
 
-                case 'select':
-                    // Exact match
-                    return String(itemValue) === filters[key];
+                    case 'select':
+                        // Exact match
+                        return String(itemValue) === candidate;
 
-                case 'number':
-                    // Exact numeric match
-                    return Number(itemValue) === Number(filters[key]);
+                    case 'number':
+                        // Exact numeric match
+                        return Number(itemValue) === Number(candidate);
 
-                case 'date':
-                    // Exact date match
-                    return String(itemValue) === filters[key];
+                    case 'date':
+                        // Exact date match
+                        return String(itemValue) === candidate;
 
-                default:
-                    // Default: case-insensitive contains
-                    return String(itemValue).toLowerCase().includes(filterValue);
-            }
+                    default:
+                        // Default: case-insensitive contains
+                        return String(itemValue).toLowerCase().includes(filterValue);
+                }
+            };
+
+            // A `filterMultiple` column holds an ARRAY of values; the row
+            // matches when it matches ANY of them (#51). A scalar filter is
+            // the one-candidate case of the same rule.
+            const raw = filters[key];
+            return (Array.isArray(raw) ? raw : [raw]).some(matchesCandidate);
         });
     });
 });
@@ -1019,6 +1077,19 @@ const handleSelectFilterChange = (field: TableField, value: unknown) => {
     handleFilterChange(filterKeyFor(field), selected === FILTER_ALL_VALUE ? '' : selected);
 };
 
+// Multi-value select filter (#51): the autocomplete's array model maps
+// straight onto the filters entry; an emptied selection removes the entry.
+const multiFilterValueFor = (field: TableField): string[] => {
+    const value = effectiveFilters.value[filterKeyFor(field)];
+    if (Array.isArray(value)) return value;
+    return isActiveFilterValue(value) ? [String(value)] : [];
+};
+
+const handleMultiSelectFilterChange = (field: TableField, value: unknown) => {
+    const selected = (Array.isArray(value) ? value : []).map(String);
+    handleFilterChange(filterKeyFor(field), selected);
+};
+
 const filterAllLabelFor = (field: TableField): string =>
     field.filterAllText ?? field.filterPlaceholder ?? `All ${field.label || field.key}`;
 
@@ -1042,7 +1113,13 @@ const getFieldFilterOptions = (field: TableField): FilterOption[] => {
     // so the obvious encoding of "no filter" silently empties the dropdown.
     // `handleSelectFilterChange` translates it back to `''`, which is already
     // how the filter map represents unset.
-    options.push({ value: FILTER_ALL_VALUE, text: filterAllLabelFor(field) });
+    //
+    // A `filterMultiple` column omits it (#51): "no filter" inside a
+    // multi-select reads as a selectable value, and clearing is already
+    // discoverable there — remove the chips, or the ✕.
+    if (!field.filterMultiple) {
+        options.push({ value: FILTER_ALL_VALUE, text: filterAllLabelFor(field) });
+    }
 
     // An "Unassigned"-style option, so a select filter can express "has no value"
     // — a different thing from "no filter" above.
@@ -1136,16 +1213,19 @@ watch(() => props.pagination?.per_page, (newPerPage) => {
     }
 });
 
-// Watch for external filter changes (when filters prop is controlled by parent)
-watch(() => props.filters, (newFilters, oldFilters) => {
+// Watch for external filter changes (when filters prop is controlled by parent).
+// Watches the SERIALISED map, not the object: a deep watch hands the same
+// object reference as both new and old value when a consumer mutates in place
+// (`filters.status.push(...)` on a multi-value array), so an old==new JSON
+// guard ate exactly the changes it was meant to detect. A string source only
+// fires when the content genuinely changed, and stringifying inside the getter
+// makes every nested key a reactive dependency.
+watch(() => JSON.stringify(props.filters ?? null), () => {
     // 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;
-
     // Refresh data for the new filters
     if (isProviderMode.value) {
         refresh();
@@ -1155,14 +1235,14 @@ watch(() => props.filters, (newFilters, oldFilters) => {
             props.inertiaUrl!,
             {
                 page: 1, // Reset to first page when filters change
-                filters: newFilters,
+                filters: props.filters,
                 perPage: effectivePerPage.value,
                 ...sortParams(effectiveSortBy.value),
             },
             { preserveState: true }
         );
     }
-}, { deep: true });
+});
 
 // Watch apiUrl changes to reset filter cache and refetch. The api-url isn't part
 // of BTable's provider context, so an api-url-only change doesn't re-invoke the
@@ -1360,19 +1440,41 @@ const internalProvider: BTableProvider<T> = async (context: Readonly<BTableProvi
         params.filterValues = fieldsNeedingFilterValues.value;
     }
 
-    const response = await axios.get(props.apiUrl, { params });
+    // Adapt the outgoing params to the backend's convention (e.g. spatie
+    // query-builder's `sort=-name` / `filter[key]`). This is the sanctioned
+    // replacement for the axios request interceptors #132 removed the route
+    // for — the adapter's return IS the wire params.
+    const wireParams = props.apiAdapter?.request
+        ? props.apiAdapter.request(params)
+        : params;
+
+    const response = await api.get<any>(props.apiUrl, wireParams);
+
+    // Adapt a foreign response envelope back into the dfl shape. Gets the
+    // ORIGINAL dfl-shape params (page/perPage/…) for context, since a foreign
+    // envelope often lacks paginator metadata the adapter must synthesize.
+    let body = props.apiAdapter?.response
+        ? props.apiAdapter.response(response.data, { params })
+        : response.data;
+
+    // A backend that ignores the pagination convention and returns a bare
+    // array of rows used to render as a SILENTLY EMPTY table (data present,
+    // nothing shown). Degrade to visible rows with no pager metadata instead.
+    if (Array.isArray(body)) {
+        body = { data: body };
+    }
 
     // Extract and store pagination metadata for display
-    if (response.data.pagination) {
-        apiPaginationMeta.value = response.data.pagination;
+    if (body.pagination) {
+        apiPaginationMeta.value = body.pagination;
     }
 
     // Extract and store filter values
-    if (response.data.filterValues) {
-        apiFilterValues.value = { ...apiFilterValues.value, ...response.data.filterValues };
+    if (body.filterValues) {
+        apiFilterValues.value = { ...apiFilterValues.value, ...body.filterValues };
     }
 
-    return response.data.data;
+    return body.data;
 };
 
 /**
@@ -1393,6 +1495,8 @@ const wrappedProvider: BTableProvider<T> = async (context: Readonly<BTableProvid
     } catch (error: any) {
         // eslint-disable-next-line no-console
         console.error('DXTable: the data provider failed', error);
+        // `error.message` covers the internal provider's ApiError; the
+        // `response.data` branch covers a consumer's own axios-based provider.
         apiError.value =
             error?.response?.data?.message ||
             error?.message ||
@@ -1600,12 +1704,12 @@ const handlePerPageChange = (newPerPage: number | string | null | (number | stri
     emit('perPageChange', perPageNum);
 };
 
-const handleFilterChange = (fieldKey: string, value: string) => {
+const handleFilterChange = (fieldKey: string, value: string | string[]) => {
     // Update filters
     const newFilters = { ...effectiveFilters.value, [fieldKey]: value };
 
-    // Remove empty filters
-    if (!value || value.trim() === '') {
+    // Remove empty filters (a blank string, or an empty multi-value array)
+    if (!isActiveFilterValue(value)) {
         delete newFilters[fieldKey];
     }
 
@@ -1859,4 +1963,11 @@ defineExpose({
 :deep(tbody tr.dx-row-actionable:hover) {
     background-color: var(--bs-table-hover-bg);
 }
+
+/* Muted header titles (#157): in a data table the CONTENT is what matters —
+   near-black bold headers compete with it. Grey (still bold) keeps the
+   structure without the shout. Consumers re-louden via the token. */
+:deep(thead th) {
+    color: var(--dx-table-header-color, var(--bs-secondary-color));
+}
 </style>