@omnitend/dashboard-for-laravel 0.43.0 → 0.45.0

package/dist/types/index.d.ts

@@ -297,6 +297,17 @@ export interface FieldDefinition {
      * declared.
      */
     submit?: boolean;
+    /**
+     * Extra validation-error keys this field owns (#194), for a field whose
+     * server-side errors arrive under keys other than its own: a span or
+     * component field that edits nested data, say. Patterns, where `*`
+     * matches exactly one dot segment: `["lines.*", "lines.*.*"]` claims
+     * `lines.0` and `lines.0.price` but not `lines` or `lines.0.a.b`.
+     * Checked before the usual matching (the field's own key, then any key
+     * nested under it), so it decides which field an error belongs to: the
+     * label it is listed under in the error summary and the tab it selects.
+     */
+    errorKeys?: string[];
     /**
      * Conditionally show or hide this field. When omitted the field is
      * always visible. Boolean or a function of the form model; evaluated
@@ -330,6 +341,7 @@ export interface BaseFieldDef {
     readonly?: MaybeFn<boolean>;
     plaintext?: MaybeFn<boolean>;
     submit?: boolean;
+    errorKeys?: string[];
     when?: MaybeFn<boolean>;
     show?: () => boolean;
 }

package/dist/utils/formErrorTargets.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Which field a validation-error key belongs to (#194).
+ *
+ * One pure function decides, so the error summary's rows, the tab a failed
+ * submit selects and the field it scrolls to can never disagree. No Vue: the
+ * caller injects visibility and label resolution, so DXForm can pass its own
+ * `when`/`context`-aware predicates and a standalone summary can use the
+ * defaults below.
+ */
+import type { FieldDefinition, FormTab } from "../types";
+import type { ValidationErrors } from "../composables/useForm";
+/** One error key and where it belongs. */
+export interface ErrorTarget {
+    /** The key as the server sent it (`lines.0.price`). */
+    errorKey: string;
+    /** The server's messages for that key, as sent. */
+    messages: string[];
+    /**
+     * One display line per message: the message itself, or `"Label: message"`
+     * when the message does not already say which field it is about (see
+     * `resolveErrorTargets`).
+     */
+    lines: string[];
+    /** The owning field's key, or `null` when no visible field owns it. */
+    fieldKey: string | null;
+    /** The tab holding the owning field, or `null` (flat form, or unowned). */
+    tabKey: string | null;
+    /** A readable name for the key: "Price (line 1)", "Delivery date". */
+    label: string;
+}
+export interface ResolveErrorTargetsOptions {
+    /** The form's field definitions. */
+    fields?: FieldDefinition[];
+    /**
+     * The form's tabs. When given (non-empty), only fields listed in a
+     * visible tab can own an error, as only those render. A tab key with no
+     * field definition (consumer-rendered content) can still own its own key
+     * and keys nested under it.
+     */
+    tabs?: FormTab[];
+    /** Model for the default predicates and labels (form data + context). */
+    model?: Record<string, any>;
+    /** Field visibility. Default: `when` and `show` against `model`. */
+    isFieldVisible?: (field: FieldDefinition) => boolean;
+    /** Tab visibility. Default: the tab's `when` against `model`. */
+    isTabVisible?: (tab: FormTab) => boolean;
+    /**
+     * A field's label. Default: its `label`, called with `labelModel` when it
+     * is a function. `labelModel` is `model` for a form field and the ROW
+     * (`model.lines[0]`) for a repeater sub-field, as DXRepeater renders it.
+     * An empty result, or a label function that throws, falls back to the
+     * humanised key, so a broken label can never hide an error.
+     */
+    resolveLabel?: (field: FieldDefinition, labelModel: Record<string, any>) => string | null | undefined;
+}
+/**
+ * `delivery_date` → "Delivery date"; `lines.0.price` → "Lines price (line 1)".
+ * A trailing `id` word names the record, not the thing, so it is dropped
+ * (`supplier_id`, `supplierId` → "Supplier"); an `id` word that is the whole
+ * segment, or not at its end, reads "ID" (`id` → "ID"). Words that merely end
+ * in "id" (`paid`, `valid`) are untouched.
+ */
+export declare function humaniseErrorKey(key: string): string;
+/**
+ * Resolve every key in `errors` to its owning field, tab and label, with the
+ * display line for each message. Rows come in tab order, then field order
+ * (the order of `tab.fieldKeys`, or of `fields` in a flat form), then the
+ * order the server sent the keys; keys no visible field owns come last.
+ *
+ * Ownership, first match wins: a field whose `errorKeys` pattern matches; a
+ * field whose key equals the error key; the field with the longest key that
+ * is a dot prefix of it (repeater rows, media maps). Hidden fields, and
+ * fields on hidden tabs or on no tab of a tabbed form, never own a key; it
+ * falls through to the next rule, or is unowned.
+ *
+ * Labels: the owning field's label; for `field.N.sub` the sub-field's label
+ * (when the field defines `fields` and one has that key) or the field's own,
+ * plus "(line N+1)"; for any other nested key (a media map's
+ * `image_media.<uuid>`) the field's label. An unowned key is humanised.
+ *
+ * Display lines: "Label: message", except that the label is left off when
+ * the message already contains it (case-insensitive) — unless the message
+ * contains a raw key (`_`, or a dot inside a word) or another row has the
+ * same message text, when the label is what tells the rows apart.
+ */
+export declare function resolveErrorTargets(errors: ValidationErrors | null | undefined, options?: ResolveErrorTargetsOptions): ErrorTarget[];

package/docs/public/api-reference.json

@@ -1,8 +1,8 @@
 {
-  "generated": "2026-10-06T10:54:58.446Z",
+  "generated": "2026-10-11T09:08:08.777Z",
   "package": {
     "name": "@omnitend/dashboard-for-laravel",
-    "version": "0.43.0"
+    "version": "0.45.0"
   },
   "components": {
     "base": [
@@ -1475,10 +1475,10 @@
             "description": "Escape-hatch control props, already guard-merged by DXField."
           },
           {
-            "name": "optionsReady",
+            "name": "optionsPending",
             "type": "boolean",
             "required": false,
-            "description": "Whether async options have resolved (a searchable select must not render\nbefore its options load, or it shows the raw id instead of the label)."
+            "description": "The field's first async options load is still in flight. A searchable\nselect then shows \"Loading…\" instead of its value's raw id."
           }
         ],
         "events": [
@@ -2530,6 +2530,32 @@
             "type": "LabelCols",
             "required": false,
             "description": "Label column width for horizontal layout (mirrors BFormGroup's\n`labelCols`/`labelCols*` props). Overridable per-field via\n`field.labelCols`. Ignored when `layout` is \"vertical\". Omitted (here\nand on the field): the label takes `--dx-form-label-width` (45%) from\n`sm` up and stacks above the input below `sm`."
+          },
+          {
+            "name": "errorSummary",
+            "type": "union",
+            "required": false,
+            "default": "\"footer\"",
+            "description": "Where to list what the last failed submit returned (`form.submitFailure`:\nthe server's message and every validation message, with readable\nlabels):\n\n- `\"footer\"` (default) — directly above the submit button, below any\n  tabs, next to the control the user just pressed.\n- `\"top\"` — above the fields, where the form-level alert sits.\n- `\"external\"` — the host renders a `DXFormErrorSummary` of its own\n  elsewhere (beside a submit button outside the form, as DXTable's\n  modal does). DXForm renders neither a summary nor, while a failure\n  is listed, the form-level alert.\n- `false` — no summary; the form-level alert behaves as before.\n\nWhile a summary shows a failure the form-level alert does not render,\nso a failure shows exactly one alert. Each row naming a visible field is\na button that selects the field's tab and focuses it."
+          },
+          {
+            "name": "errorSummaryTitle",
+            "type": "string",
+            "required": false,
+            "description": "The summary's heading when the failure has field errors (default\n\"Couldn't save. Please check:\"). A failure with none (a message-only\n422, a 500) is headed by the server's message instead."
+          },
+          {
+            "name": "errorSummaryOtherTitle",
+            "type": "string",
+            "required": false,
+            "description": "The summary's sub-heading over the rows no visible field owns (default\n\"Other problems\"), shown only when some rows ARE owned."
+          },
+          {
+            "name": "scrollToError",
+            "type": "boolean",
+            "required": false,
+            "default": "true",
+            "description": "After a failed submit, scroll the first field with an error into view\n(once its tab is selected and rendered). Never moves focus. On by\ndefault."
           }
         ],
         "events": [
@@ -2645,6 +2671,85 @@
         ],
         "methods": []
       },
+      {
+        "name": "DXFormErrorSummary",
+        "category": "extended",
+        "filePath": "resources/js/components/extended/DXFormErrorSummary.vue",
+        "description": "Lists everything the last failed submit of a `useForm` returned: a heading, then one row per validation message with a readable label (\"Price (line 1): Must be positive.\"). The heading is `title` (\"Couldn't save. Please check:\") when the failure has field errors, and the server's message when it has none (a message-only 422, a 500, a network failure), since then the message is all there is. Built from `form.submitFailure`, so it survives field edits and `clearError`, and disappears when the next submit starts or one succeeds. Renders nothing before a failure. A row whose key belongs to a visible field is a button that emits `select-target`, for the host to select the field's tab and focus it; a key no visible field owns is listed as plain text, after the owned rows, under `otherTitle` (\"Other problems\") when both kinds are present. Place it next to the submit control.",
+        "props": [
+          {
+            "name": "form",
+            "type": "union",
+            "required": true,
+            "description": "The form: a `useForm` return or a `defineForm` return."
+          },
+          {
+            "name": "fields",
+            "type": "Array",
+            "required": false,
+            "description": "Field definitions (optional when `form` is a defineForm return)."
+          },
+          {
+            "name": "tabs",
+            "type": "Array",
+            "required": false,
+            "description": "The form's tabs, so rows follow tab order and know their tab."
+          },
+          {
+            "name": "context",
+            "type": "Record",
+            "required": false,
+            "description": "Extra context merged under the form data when evaluating `when` and\nfunction labels, as on DXForm."
+          },
+          {
+            "name": "isFieldVisible",
+            "type": "TSFunctionType",
+            "required": false,
+            "description": "Field visibility, replacing the default (`when`/`show` against form\ndata + `context`). A host form passes its own predicate so the summary\nagrees with what it renders."
+          },
+          {
+            "name": "isTabVisible",
+            "type": "TSFunctionType",
+            "required": false,
+            "description": "Tab visibility, replacing the default (the tab's `when`)."
+          },
+          {
+            "name": "resolveLabel",
+            "type": "TSFunctionType",
+            "required": false,
+            "description": "A field's label, replacing the default (its `label`, resolved against\n`labelModel`: the form model, or the row for a repeater sub-field)."
+          },
+          {
+            "name": "targets",
+            "type": "union",
+            "required": false,
+            "description": "Rows already resolved by the host (from `resolveErrorTargets` over\n`form.submitFailure.errors`). When given, the summary lists these and\nresolves nothing itself; the message still comes from\n`form.submitFailure`, and nothing renders while that is null."
+          },
+          {
+            "name": "title",
+            "type": "string",
+            "required": false,
+            "default": "\"Couldn't save. Please check:\"",
+            "description": "The heading when the failure has at least one field error. The\nserver's own message is not used then: Laravel's default 422 message\nis the first error plus \"(and N more errors)\", which repeats the first\nrow. A failure with no field errors (a message-only 422, a 500, a\nnetwork failure) keeps the server's message as the heading, as it is\nthe only information."
+          },
+          {
+            "name": "otherTitle",
+            "type": "string",
+            "required": false,
+            "default": "\"Other problems\"",
+            "description": "The sub-heading over the rows no visible field owns, listed after the\nowned rows. Shown only when there are both kinds; when no row is owned\nthey are listed under the heading alone."
+          }
+        ],
+        "events": [
+          {
+            "name": "select-target",
+            "description": "A row was clicked: select `tabKey` (if any) and focus `fieldKey`.",
+            "properties": []
+          }
+        ],
+        "slots": [],
+        "methods": []
+      },
       {
         "name": "DXFormField",
         "category": "extended",
@@ -2699,6 +2804,10 @@
               {
                 "name": "model",
                 "title": "binding"
+              },
+              {
+                "name": "targetAttrs",
+                "title": "binding"
               }
             ]
           },
@@ -2823,8 +2932,8 @@
             "name": "delay",
             "type": "number",
             "required": false,
-            "default": "300",
-            "description": ""
+            "default": "600",
+            "description": "Milliseconds to wait before showing anything. Most loads finish\n sooner, and one that has already taken this long is likely to take\n longer, so a quick load never flashes a loader."
           }
         ],
         "events": [],
@@ -3688,6 +3797,18 @@
             "required": false,
             "description": "Override the modal's Delete button label (default: \"Delete {item}\")."
           },
+          {
+            "name": "errorSummaryTitle",
+            "type": "string",
+            "required": false,
+            "description": "Heading of the modal's failed-save summary when the failure has field\nerrors (default \"Couldn't save. Please check:\"). A failure with none\nis headed by the server's message instead."
+          },
+          {
+            "name": "errorSummaryOtherTitle",
+            "type": "string",
+            "required": false,
+            "description": "Sub-heading over the summary rows no edit field owns (default \"Other\nproblems\"), shown only when some rows ARE owned."
+          },
           {
             "name": "editUrl",
             "type": "string",
@@ -3769,6 +3890,13 @@
             "required": false,
             "description": "Whether a given row is actionable. Only relevant when rows are clickable\n(an `editFields` modal or a `row-clicked` listener). A row this returns\n`false` for gets no pointer cursor, no hover highlight, and does not fire\n`row-clicked` or open the edit modal — so a row that isn't clickable\ndoesn't *look* clickable, and a click on it can't quietly do something."
           },
+          {
+            "name": "editOnRowClick",
+            "type": "boolean",
+            "required": false,
+            "default": "true",
+            "description": "Whether clicking a row opens the edit modal (when `editFields` are set).\nDefaults to `true`. Set `false` when `editFields` exist only for the\ncreate modal (`openCreate()` / the create button) and a row click does\nsomething else, such as opening the record's own page from `row-clicked`:\nthe row then emits `row-clicked` without also opening the edit modal, and\nonly a `row-clicked` listener makes rows look clickable (#200)."
+          },
           {
             "name": "clientSide",
             "type": "boolean",
@@ -4077,6 +4205,18 @@
             "type": "string",
             "required": false,
             "description": "Override the Delete button label."
+          },
+          {
+            "name": "errorSummaryTitle",
+            "type": "string",
+            "required": false,
+            "description": "The footer summary's heading for a failure with field errors."
+          },
+          {
+            "name": "errorSummaryOtherTitle",
+            "type": "string",
+            "required": false,
+            "description": "The footer summary's sub-heading over rows no field owns."
           }
         ],
         "events": [
@@ -4439,8 +4579,8 @@
     ]
   },
   "stats": {
-    "totalComponents": 89,
+    "totalComponents": 90,
     "baseComponents": 60,
-    "extendedComponents": 29
+    "extendedComponents": 30
   }
 }

package/docs/public/docs-map.md

@@ -1,7 +1,7 @@
 # Documentation Map
 
 > Auto-generated hierarchical overview of all documentation
-> Last updated: 2026-10-06T10:54:58.500Z
+> Last updated: 2026-10-11T09:08:08.837Z
 
 This file provides a complete map of all available documentation for AI agents and developers.
 
@@ -79,6 +79,7 @@ This file provides a complete map of all available documentation for AI agents a
 - [DXDashboardSidebar](/components/extended/DXDashboardSidebar): A collapsible sidebar navigation component for Laravel dashboards with support for navigation groups
 - [DXField](/components/extended/DXField): The single-field renderer that powers `DXForm` and
 - [DXForm](/components/extended/DXForm): The canonical form renderer. Drive it with field definitions; add `tabs` when
+- [DXFormErrorSummary](/components/extended/DXFormErrorSummary): Lists everything the last failed submit of a `useForm` returned: a heading,
 - [DXNumberStepper](/components/extended/DXNumberStepper): A number input between a decrease and an increase button, `[ − ][ 12 ][ + ]`,
 - [DXRepeater](/components/extended/DXRepeater): A repeatable sub-form (field array) primitive for nested, dynamic collections —
 - [DXSaveButton](/components/extended/DXSaveButton): A save button that confirms the save in place. While saving it shows
@@ -105,4 +106,4 @@ This file provides a complete map of all available documentation for AI agents a
 
 ---
 
-**Total Pages**: 81
+**Total Pages**: 82

package/docs/public/llms.txt

@@ -2,7 +2,7 @@
 
 > Vue 3 dashboard components for Laravel with Bootstrap Vue Next
 >
-> A dual-package library (NPM + Composer) providing 79 Vue 3 components for building Laravel dashboards with Bootstrap Vue Next.
+> A dual-package library (NPM + Composer) providing 80 Vue 3 components for building Laravel dashboards with Bootstrap Vue Next.
 
 ## Installation
 
@@ -84,7 +84,7 @@ Lightweight type-safe wrappers around Bootstrap Vue Next components providing AP
 - [DToaster](/components/base/dtoaster): Bootstrap Vue Next Toaster wrapper
 - [DTooltip](/components/base/dtooltip): Bootstrap Vue Next Tooltip wrapper
 
-## Extended Components (19 components)
+## Extended Components (20 components)
 
 Custom dashboard components with advanced functionality beyond Bootstrap Vue Next.
 
@@ -96,6 +96,7 @@ Custom dashboard components with advanced functionality beyond Bootstrap Vue Nex
 - [DXField](/components/extended/dxfield): Single-field renderer for any field type with value/span/info/hint slots
 - [DXFieldLabel](/components/extended/dxfieldlabel): Extended dashboard component
 - [DXForm](/components/extended/dxform): Form renderer driven by field definitions, with optional tabs, conditional fields, per-field slots, async options, nested repeaters, and auto error-tab switching
+- [DXFormErrorSummary](/components/extended/dxformerrorsummary): One alert listing every message of the last failed submit, with readable labels, placed next to the submit control
 - [DXLoading](/components/extended/dxloading): Extended dashboard component
 - [DXModalActions](/components/extended/dxmodalactions): Extended dashboard component
 - [DXNumberStepper](/components/extended/dxnumberstepper): Extended dashboard component

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omnitend/dashboard-for-laravel",
-  "version": "0.43.0",
+  "version": "0.45.0",
   "description": "Vue 3 dashboard components for Laravel with Bootstrap Vue Next",
   "type": "module",
   "main": "./dist/dashboard-for-laravel.umd.cjs",
@@ -55,12 +55,13 @@
   },
   "peerDependencies": {
     "@inertiajs/vue3": "^2.0.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "chart.js": "^4.4.0",
     "vue": "^3.5.13",
     "vue-chartjs": "^5.3.0"
   },
   "peerDependenciesMeta": {
-    "bootstrap-vue-next": {
+    "@modelcontextprotocol/sdk": {
       "optional": true
     },
     "chart.js": {
@@ -71,13 +72,8 @@
     }
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0",
     "bootstrap-vue-next": "^0.45.6",
-    "highlight.js": "^11.11.1",
-    "pluralize": "^8.0.0",
-    "rehype-autolink-headings": "^7.1.0",
-    "rehype-slug": "^6.0.0",
-    "vue-docgen-api": "^4.79.2"
+    "pluralize": "^8.0.0"
   },
   "devDependencies": {
     "@astrojs/markdown-remark": "^7.2.0",
@@ -87,6 +83,7 @@
     "@iconify-json/lucide": "^1.2.71",
     "@iconify/json": "^2.2.397",
     "@inertiajs/vue3": "^2.2.15",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "@types/pluralize": "^0.0.33",
     "@vitejs/plugin-vue": "^5.2.4",
     "@vitest/browser": "^4.1.8",
@@ -97,8 +94,11 @@
     "bootstrap-icons": "^1.13.1",
     "chart.js": "^4.5.1",
     "happy-dom": "^20.0.8",
+    "highlight.js": "^11.11.1",
     "pagefind": "^1.4.0",
     "playwright": "^1.56.1",
+    "rehype-autolink-headings": "^7.1.0",
+    "rehype-slug": "^6.0.0",
     "sass-embedded": "^1.93.2",
     "typescript": "^5.9.3",
     "unplugin-icons": "^22.5.0",
@@ -107,6 +107,7 @@
     "vitest": "^4.1.8",
     "vitest-browser-vue": "^2.0.0",
     "vue-chartjs": "^5.3.3",
+    "vue-docgen-api": "^4.79.2",
     "vue-tsc": "^2.2.12"
   },
   "keywords": [

package/resources/css/theme.scss

@@ -654,6 +654,62 @@ $dx-display-only-row: '.dx-form--horizontal .row:has(> .col-form-label):not(:has
   }
 }
 
+// DXFormErrorSummary (#194): a heading (the title, or the server's message
+// when there are no field errors), then one row per validation message. The alert keeps the danger alert's subtle tint; a row
+// that points at a field is a button drawn as underlined text in the alert's
+// own colour (an alert-coloured link, not the brand navy), so the list reads
+// as text and still says "you can click this". Global, not scoped: the rows
+// are rendered inside DAlert's slot.
+.dx-form-error-summary {
+  .dx-form-error-summary__message {
+    margin-bottom: 0;
+    font-weight: $font-weight-semibold;
+  }
+
+  .dx-form-error-summary__list {
+    margin: map.get($spacers, 2) 0 0;
+    padding-inline-start: 1.25rem;
+  }
+
+  // "Other problems": the rows no field owns, after the owned ones. One
+  // step lighter than the heading (semibold), still above the body text,
+  // and tied to the list it introduces rather than the one above it.
+  .dx-form-error-summary__other-title {
+    margin: map.get($spacers, 2) 0 0;
+    font-weight: $font-weight-medium;
+
+    + .dx-form-error-summary__list {
+      margin-top: map.get($spacers, 1);
+    }
+  }
+
+  .dx-form-error-summary__target {
+    padding: 0;
+    border: 0;
+    background: none;
+    color: inherit;
+    font: inherit;
+    text-align: start;
+    text-decoration: underline;
+    text-underline-offset: 0.15em;
+    cursor: pointer;
+    // A button is an inline-block, and the list bullet sits on the line
+    // box's baseline, which a baseline-aligned inline-block takes from its
+    // LAST line: a row that wraps had its bullet beside its second line.
+    vertical-align: top;
+
+    &:hover {
+      text-decoration-thickness: 2px;
+    }
+
+    &:focus-visible {
+      outline: var(--bs-focus-ring-width) solid currentColor;
+      outline-offset: 2px;
+      border-radius: var(--bs-border-radius-sm);
+    }
+  }
+}
+
 // Switch-list option rows (DXField `switch-list`) are one line each: a label,
 // a switch and an optional trailing control (a notes input in the
 // `switch-list-item` slot). Centre all three in the row, instead of the
@@ -1936,3 +1992,123 @@ $dx-chart-edge-dark: $body-bg-dark;
 thead tr:has(.dx-table-filter-cell) > td {
   padding: 0.5rem;
 }
+
+// ————————————————— DXLoading (the soft loader)
+//
+// Modelled on Omni Tend's legacy loader: a small grey spinner beside the
+// text on one line, the text in the display face with a slow light sweep
+// across it, fading in after DXLoading's delay. Quieter than a navy spinner,
+// but the text keeps AA contrast (#6c757d, 4.69:1 on white; the legacy
+// gray-300 was 1.5:1). The sweep passes through a lighter grey, so a moment
+// of the text sits below AA while it moves. Global, not scoped: DXTable and
+// consumers render it, and its spinner is a bvn component.
+//
+// The `role="status"` box renders at once with its contents hidden, and
+// `.dx-loading--shown` reveals them after the delay. Two reasons: a live
+// region that is already in the page announces content added to it (one
+// inserted together with its text can go unannounced), and the space the
+// loader will take is held from the start, so nothing jumps when it appears.
+@mixin dx-loading-light-vars {
+  --dx-loading-color: #{$gray-600};
+  --dx-loading-sweep-color: #{$gray-500};
+  --dx-loading-spinner-color: #{$gray-500};
+}
+
+// `[data-bs-theme="light"]` too, so a light section inside a dark page gets
+// the light set back (as the chart tokens do).
+:root,
+[data-bs-theme="light"] {
+  @include dx-loading-light-vars;
+  // Slower than Bootstrap's 0.75 s a turn: a calmer spin to match the soft
+  // look (1.1 s chosen against 1.5 s and 2 s side by side).
+  --dx-loading-spinner-speed: 1.1s;
+}
+
+[data-bs-theme="dark"] {
+  --dx-loading-color: #{$gray-500};
+  --dx-loading-sweep-color: #{$gray-600};
+  --dx-loading-spinner-color: #{$gray-600};
+}
+
+.dx-loading {
+  display: flex;
+  justify-content: center;
+  align-items: center;
+  gap: 1rem;
+  color: var(--dx-loading-color);
+
+  // Hidden, not removed: `visibility` keeps the box's size and keeps the
+  // contents out of the accessibility tree until they are revealed.
+  > * {
+    visibility: hidden;
+  }
+
+  // Set on the spinner itself: Bootstrap declares its speed on
+  // `.spinner-border`, so a value inherited from `.dx-loading` would lose.
+  .spinner-border {
+    flex: none;
+    color: var(--dx-loading-spinner-color);
+    --bs-spinner-animation-speed: var(--dx-loading-spinner-speed);
+  }
+}
+
+.dx-loading--shown {
+  animation: dx-loading-fade-in 0.4s ease-out both;
+
+  > * {
+    visibility: visible;
+  }
+}
+
+.dx-loading__text {
+  margin: 0;
+  font-family: var(--dx-font-family-display);
+  font-weight: 500;
+  font-size: $h2-font-size;
+  line-height: $headings-line-height;
+  background-image: linear-gradient(
+    to right,
+    var(--dx-loading-color) 20%,
+    var(--dx-loading-color) 40%,
+    var(--dx-loading-sweep-color) 60%,
+    var(--dx-loading-sweep-color) 80%,
+    var(--dx-loading-color) 99%
+  );
+  background-size: 200% auto;
+  -webkit-background-clip: text;
+  background-clip: text;
+  -webkit-text-fill-color: transparent;
+  animation: dx-loading-sweep 3s linear infinite;
+}
+
+@keyframes dx-loading-fade-in {
+  from {
+    opacity: 0;
+  }
+}
+
+@keyframes dx-loading-sweep {
+  to {
+    background-position: 200% center;
+  }
+}
+
+// For people who asked for less motion: no sweep and no fade (the text is
+// plain grey and appears at once), and the spinner slows to double its turn,
+// as Bootstrap's own reduced-motion rule does for its spinners. That rule
+// cannot reach this one, because the speed above out-ranks it.
+@media (prefers-reduced-motion: reduce) {
+  .dx-loading--shown,
+  .dx-loading__text {
+    animation: none;
+  }
+
+  .dx-loading__text {
+    background-image: none;
+    -webkit-text-fill-color: currentColor;
+  }
+
+  .dx-loading .spinner-border {
+    --bs-spinner-animation-speed: calc(2 * var(--dx-loading-spinner-speed));
+  }
+}

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

@@ -18,8 +18,11 @@ import { BFormSelect } from "bootstrap-vue-next";
 import { computed, useSlots } from "vue";
 
 // Mirrors the shapes BVN's BFormSelect accepts per option (primitive, object, or
-// group). Only object options can carry a `null` value.
-export type OptionItem = string | number | boolean | Record<string, unknown>;
+// group): bvn types them `object | string | number | boolean`. `object`, not
+// `Record<string, unknown>`, so an option INTERFACE such as DXTable's
+// `FilterOption` (no index signature) fits without a cast (#171). Only object
+// options can carry a `null` value.
+export type OptionItem = string | number | boolean | object;
 
 export interface Props<TValue = unknown> {
   modelValue?: TValue | TValue[] | null;