@omnitend/dashboard-for-laravel 0.23.0 → 0.25.0

package/dist/types/index.d.ts

@@ -85,6 +85,16 @@ export interface FieldDefinition {
     optionsLoader?: OptionsLoader;
     /** Re-run `optionsLoader` whenever the form model changes. */
     reloadOptionsOnChange?: boolean;
+    /**
+     * For `select` fields: render a **searchable** select — type to filter a
+     * long option list, while the model still holds `option.value` (an id).
+     *
+     * A plain `select` is fine for ten options and unusable for hundreds; the
+     * `autocomplete` type filters but models the *typed text*, so it can't back
+     * a foreign key (picking "Tesco" gives you `"Tesco"`, not `37`). This is the
+     * combination high-frequency data entry against a long list needs.
+     */
+    searchable?: boolean;
     /** Number of rows for textarea (default: 3) */
     rows?: number;
     /** Step for numeric/currency/percentage inputs */
@@ -254,6 +264,17 @@ export interface FieldDefinition {
      * `false` to render a bare password input.
      */
     revealable?: boolean;
+    /**
+     * Include this field's value in the submitted payload. Default `true`.
+     *
+     * Set `false` for a **presentational** field — a header, an alert, an
+     * explanatory block rendered via `span` — that exists to lay out the form,
+     * not to hold data. Without it, `DXTable`'s edit modal seeds its form from
+     * every `editFields` key, so those decorative fields are POSTed alongside
+     * the real ones (an empty string, an empty array) purely because they were
+     * declared.
+     */
+    submit?: boolean;
     /**
      * Conditionally show or hide this field. When omitted the field is
      * always visible. Boolean or a function of the form model; evaluated

package/docs/public/api-reference.json

@@ -1,8 +1,8 @@
 {
-  "generated": "2026-07-11T08:44:15.505Z",
+  "generated": "2026-07-11T11:02:20.726Z",
   "package": {
     "name": "@omnitend/dashboard-for-laravel",
-    "version": "0.22.0"
+    "version": "0.25.0"
   },
   "components": {
     "base": [
@@ -1430,6 +1430,13 @@
             "default": "'wrap'",
             "description": "What the navbar actions slot does below `md`: `\"wrap\"` to its own\nfull-width row, `\"hide\"` to remove it (relocate actions into the page on\nphones). Forwarded to DXDashboardNavbar."
           },
+          {
+            "name": "userMenuLabel",
+            "type": "string",
+            "required": false,
+            "default": "'User menu'",
+            "description": "Accessible name for the navbar's user-menu trigger. Forwarded to DXDashboardNavbar."
+          },
           {
             "name": "collapsibleGroups",
             "type": "boolean",
@@ -1528,6 +1535,13 @@
             "required": false,
             "default": "\"wrap\"",
             "description": "What the actions slot does below the `md` breakpoint: `\"wrap\"` moves it\nto its own full-width row (the bar grows), `\"hide\"` removes it entirely\n(for apps that relocate page actions into the page on phones)."
+          },
+          {
+            "name": "userMenuLabel",
+            "type": "string",
+            "required": false,
+            "default": "\"User menu\"",
+            "description": "Accessible name for the user-menu trigger. Without one, a screen reader\nannounces the trigger as the avatar's initial (\"J\") rather than as a menu."
           }
         ],
         "events": [
@@ -2761,7 +2775,7 @@
             "name": "perPageOptions",
             "type": "Array",
             "required": false,
-            "default": "() => [10, 25, 50, 100]",
+            "default": "() => [10, 20, 50, 100]",
             "description": "Per-page options for selector"
           },
           {

package/docs/public/docs-map.md

@@ -1,7 +1,7 @@
 # Documentation Map
 
 > Auto-generated hierarchical overview of all documentation
-> Last updated: 2026-07-11T08:44:15.559Z
+> Last updated: 2026-07-11T11:02:20.808Z
 
 This file provides a complete map of all available documentation for AI agents and developers.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omnitend/dashboard-for-laravel",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "description": "Vue 3 dashboard components for Laravel with Bootstrap Vue Next",
   "type": "module",
   "main": "./dist/dashboard-for-laravel.umd.cjs",

package/resources/css/theme.scss

@@ -162,6 +162,35 @@ $dashboard-sidebar-width: 280px;
 $dashboard-sidebar-collapsed-width: 80px;
 $dashboard-navbar-height: 64px;
 
+// The bar's vertical padding, and the single-row CONTENT BUDGET that follows
+// from it. Everything on the bar's single row — the avatar toggle, whatever a
+// consumer puts in the `actions` or `user-icon` slots — has to fit this, or the
+// bar grows past $dashboard-navbar-height and the header stops lining up with
+// the sidebar's (which is a fixed $dashboard-navbar-height tall).
+//
+// This is the ONE owner of that arithmetic. It used to be spread across four
+// magic numbers in two files with nothing tying them together (#102), so a 40px
+// avatar or a `btn-lg` in the actions slot broke the alignment silently. Our own
+// pieces now size themselves FROM the budget, and it's published as
+// `--dx-navbar-content-height` so consumer slot content can too.
+$dashboard-navbar-bar-padding-y: 0.5rem;
+
+// The header's own `border-bottom`. This was the number nobody was counting:
+// `.dashboard-navbar` is border-box, so its 64px min-height has to contain the
+// bar AND this border. Budgeting 64 - 16 = 48px for content (as the old comment
+// did) overshoots the header by exactly 1px, which is what pushed it out of
+// alignment with the sidebar. Part of the arithmetic, so it lives with it.
+$dashboard-navbar-border-width: 1px; // Bootstrap's $border-width
+
+// A CSS `calc()` rather than Sass arithmetic, deliberately: the height is in px
+// and the padding in rem, so Sass can't subtract them — and resolving it at
+// runtime is the more correct answer anyway, since the padding then still scales
+// with the root font size.
+$dashboard-navbar-content-height: calc(
+  #{$dashboard-navbar-height} - #{$dashboard-navbar-border-width} -
+    #{$dashboard-navbar-bar-padding-y} * 2
+);
+
 // ----------------------------------------------------------------------------
 // Import Bootstrap
 // ----------------------------------------------------------------------------
@@ -287,6 +316,11 @@ $bootstrap-icons-font-src: url("bootstrap-icons/font/fonts/bootstrap-icons.woff2
 }
 
 .dashboard-navbar {
+  // Published so slot content can size itself to the budget rather than guess:
+  //   .my-navbar-action { height: var(--dx-navbar-content-height); }
+  --dx-navbar-height: #{$dashboard-navbar-height};
+  --dx-navbar-content-height: #{$dashboard-navbar-content-height};
+
   // Floor, not a fixed height: below `md` the search (and actions) drop to
   // their own rows and the bar must grow to contain them (#93). Single-row
   // content is shorter than this, so desktop stays exactly this height,
@@ -298,15 +332,22 @@ $bootstrap-icons-font-src: url("bootstrap-icons/font/fonts/bootstrap-icons.woff2
   background-color: var(--bs-light);
 }
 
-// The avatar dropdown trigger (DXDashboardNavbar sets this via toggle-class,
-// so it lands on the BVN-rendered button — global rule, scoped CSS can't
-// reach it). The themed $btn-padding-y (10px) would make it ~54px tall and
-// blow the navbar's single-row content budget: 64px header minus the bar's
-// 16px padding = 48px. 6px keeps a ~46px tap target (≥ the 44px WCAG
-// guideline) while still fitting the budget.
+// The avatar dropdown trigger (DXDashboardNavbar sets this via toggle-class, so
+// it lands on the BVN-rendered button — a global rule, scoped CSS can't reach
+// it). Sized FROM the content budget rather than by a hand-tuned padding that
+// happened to fit it: the themed $btn-padding-y (10px) would make it ~54px tall
+// and push the bar past the header height. Taking the budget as its height keeps
+// it aligned by construction, and gives a 48px tap target (≥ the 44px WCAG
+// guideline) — better than the 46px the old padding produced.
+//
+// Because it's a fixed height, a taller `user-icon` slot (a 40px avatar, say)
+// can no longer grow the bar: it centres inside the budget instead.
 .dashboard-navbar__user-menu-toggle {
-  padding-top: 0.375rem;
-  padding-bottom: 0.375rem;
+  height: $dashboard-navbar-content-height;
+  display: inline-flex;
+  align-items: center;
+  padding-top: 0;
+  padding-bottom: 0;
 }
 
 // ----------------------------------------------------------------------------
@@ -411,3 +452,67 @@ $bootstrap-icons-font-src: url("bootstrap-icons/font/fonts/bootstrap-icons.woff2
     0 10px 15px -3px rgba(0, 0, 0, 0.1),
     0 4px 6px -2px rgba(0, 0, 0, 0.05) !important;
 }
+
+// ----------------------------------------------------------------------------
+// Dashboard navbar layout
+// ----------------------------------------------------------------------------
+// These rules live here rather than in DXDashboardNavbar's scoped block so the
+// `md` switch compiles from Bootstrap's own `$grid-breakpoints`, exactly as the
+// `d-md-*` utilities the same component uses do. A media query hardcoded in the
+// SFC is baked into `dist/` at OUR build, so a consumer overriding
+// `$grid-breakpoints` and compiling this file from source would move the
+// utilities and not the media query, leaving a band of widths where the two
+// disagree (#101).
+//
+// Mobile-first: the actions and the search each take their own full-width row
+// below the toggle / title / user-menu row (flex-basis 100% forces the wrap; the
+// bar and the sticky header grow to contain them — #93). The actions row itself
+// wraps, so a wide button group stacks instead of overflowing the viewport.
+//
+// From `md` up everything goes inline: search between the title and the actions
+// (filling the middle; `searchAlign` places its content), actions right-aligned
+// next to the user menu. The actions' `order: 2` holds at every size — only the
+// search and the user-menu cluster swap order across the breakpoint.
+
+.dashboard-navbar__bar {
+  padding: $dashboard-navbar-bar-padding-y 0;
+}
+
+.dashboard-navbar__end {
+  margin-left: auto;
+}
+
+.dashboard-navbar__actions {
+  order: 2;
+  flex: 0 0 100%;
+  flex-wrap: wrap;
+}
+
+.dashboard-navbar__search {
+  order: 3;
+  flex: 0 0 100%;
+}
+
+@include media-breakpoint-up(md) {
+  .dashboard-navbar__search {
+    order: 1;
+    flex: 1 1 auto;
+  }
+
+  .dashboard-navbar__actions {
+    flex: 0 1 auto;
+    flex-wrap: nowrap;
+    margin-left: auto;
+  }
+
+  .dashboard-navbar__end {
+    order: 3;
+  }
+
+  // When the actions region is present it carries the push-right auto margin;
+  // zero the user-menu cluster's so the two sit adjacent instead of splitting
+  // the free space between them.
+  .dashboard-navbar__actions ~ .dashboard-navbar__end {
+    margin-left: 0;
+  }
+}

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

@@ -6,11 +6,40 @@
  * `filterFunction`.
  */
 <script setup lang="ts">
+import { computed, useAttrs } from "vue";
 import { BAutocomplete } from "bootstrap-vue-next";
 
 defineOptions({
   inheritAttrs: false,
 });
+
+const attrs = useAttrs();
+
+/*
+ * Diverges from bvn: the clear (✕) is hidden when there is nothing to clear.
+ *
+ * BAutocomplete's own `hasSelection` excludes only `null` and `undefined`, so an
+ * EMPTY STRING counts as a selection and the ✕ renders on an empty field. That's
+ * very visible through DXTable, which uses this control for every `select`
+ * column filter: a freshly loaded table with four filters showed four ✕ buttons
+ * before the user had done anything, reading as "these have a value to clear"
+ * when they don't (#108). An inert button also shouldn't sit in the tab order.
+ *
+ * A consumer's explicit `no-clear-button` still wins; this only ever hides the
+ * button, never forces it on.
+ */
+const attr = (name: string, hyphenated: string) =>
+  (attrs as Record<string, unknown>)[name] ?? (attrs as Record<string, unknown>)[hyphenated];
+
+const hasValue = computed(() => {
+  const value = attr("modelValue", "model-value");
+  if (Array.isArray(value)) return value.length > 0;
+  return value !== null && value !== undefined && value !== "";
+});
+
+const noClearButton = computed(
+  () => attr("noClearButton", "no-clear-button") === true || !hasValue.value,
+);
 </script>
 
 <template>
@@ -23,7 +52,7 @@ defineOptions({
     (#53). A plain element root makes it deterministic.
   -->
   <div class="d-autocomplete">
-    <BAutocomplete v-bind="$attrs">
+    <BAutocomplete v-bind="$attrs" :no-clear-button="noClearButton">
       <!-- Dynamically pass through all named slots with their props -->
       <template v-for="(_, name) in $slots" :key="name" #[name]="slotProps">
         <slot :name="name" v-bind="slotProps" />
@@ -49,6 +78,30 @@ defineOptions({
   min-width: 0;
 }
 
+/*
+  The control is an `.input-group` whose input and trigger chevron are SIBLINGS,
+  so Bootstrap's `.form-control:focus` ring wraps the input only and stops dead
+  where the chevron begins — the outline reads as clipped rather than framing the
+  control. Move the ring to the group on `:focus-within` so the whole thing is
+  outlined as one object, which is the standard input-group + button pattern
+  (#108).
+*/
+.d-autocomplete :deep(.input-group:focus-within) {
+  border-radius: var(--bs-border-radius);
+  box-shadow: 0 0 0 0.25rem rgba(var(--bs-primary-rgb), 0.25);
+}
+
+.d-autocomplete :deep(.input-group:focus-within .form-control:focus),
+.d-autocomplete :deep(.input-group:focus-within .btn:focus) {
+  box-shadow: none;
+}
+
+/* Keep the seam between input and chevron coloured like the focused control. */
+.d-autocomplete :deep(.input-group:focus-within .form-control),
+.d-autocomplete :deep(.input-group:focus-within .b-autocomplete-trigger) {
+  border-color: var(--bs-primary);
+}
+
 /*
   The trigger renders as a heavy `btn btn-secondary` (dark), which reads as a
   detached dark block. Soften it to a subtle bordered chevron that matches the

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

@@ -47,6 +47,7 @@
         :user="user"
         :search-align="searchAlign"
         :actions-on-mobile="actionsOnMobile"
+        :user-menu-label="userMenuLabel"
         @toggle-sidebar="toggleSidebar"
       >
         <!-- Dynamically forward all navbar-* slots by stripping the prefix -->
@@ -154,6 +155,9 @@ interface Props {
    */
   actionsOnMobile?: NavbarActionsOnMobile;
 
+  /** Accessible name for the navbar's user-menu trigger. Forwarded to DXDashboardNavbar. */
+  userMenuLabel?: string;
+
   /**
    * Turn sidebar group headers into accordion toggles that collapse/expand
    * their items. When off (default), every group is permanently expanded.
@@ -189,6 +193,7 @@ const props = withDefaults(defineProps<Props>(), {
   contentMaxWidth: '1140px',
   searchAlign: 'start',
   actionsOnMobile: 'wrap',
+  userMenuLabel: 'User menu',
 });
 
 const collapsed = ref(false);

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

@@ -6,11 +6,11 @@
   with a `navbar-` prefix.
 -->
 <template>
-  <header class="dashboard-navbar border-bottom">
+  <header ref="headerRef" class="dashboard-navbar border-bottom">
     <DContainer fluid>
       <!-- Flex bar that wraps: below `md` the search drops to its own
            full-width row beneath the toggle/title/user-menu row. -->
-      <div class="dashboard-navbar__bar d-flex flex-wrap align-items-center gap-3">
+      <div ref="barRef" class="dashboard-navbar__bar d-flex flex-wrap align-items-center gap-3">
         <div class="dashboard-navbar__start d-flex align-items-center gap-3">
           <DButton
             variant="link"
@@ -83,6 +83,12 @@
               no-caret
             >
               <template #button-content>
+                <!-- Names the control. A visually-hidden label rather than an
+                     `aria-label`, because an aria-label REPLACES the element's
+                     content for assistive tech — it would silence the avatar's
+                     notification-badge text, which is the one thing in there
+                     worth announcing (#113). -->
+                <span class="visually-hidden">{{ userMenuLabel }}</span>
                 <!--
                   @slot Custom user avatar/icon in the dropdown trigger. To decorate the default avatar (e.g. add a notification dot) rather than replace it, render `DXUserAvatar` — the same component used here, so the styling comes with it.
                   @binding {string} initial The first letter of the user's name.
@@ -107,7 +113,7 @@
 </template>
 
 <script setup lang="ts">
-import { computed } from "vue";
+import { computed, onBeforeUnmount, onMounted, ref } from "vue";
 import DContainer from "../base/DContainer.vue";
 import DButton from "../base/DButton.vue";
 import DDropdown from "../base/DDropdown.vue";
@@ -137,12 +143,18 @@ const props = withDefaults(
      * (for apps that relocate page actions into the page on phones).
      */
     actionsOnMobile?: NavbarActionsOnMobile;
+    /**
+     * Accessible name for the user-menu trigger. Without one, a screen reader
+     * announces the trigger as the avatar's initial ("J") rather than as a menu.
+     */
+    userMenuLabel?: string;
   }>(),
   {
     user: null,
     pageTitle: "",
     searchAlign: "start",
     actionsOnMobile: "wrap",
+    userMenuLabel: "User menu",
   },
 );
 
@@ -176,6 +188,72 @@ defineEmits<{
   toggleSidebar: [];
 }>();
 
+/*
+ * The 64px invariant, made loud instead of silent (#102).
+ *
+ * The bar aligns with the sidebar's fixed-height header only while its
+ * single-row content fits the budget (`--dx-navbar-content-height`). Our own
+ * chrome is sized FROM that budget so it can't break it — but slot content is
+ * the consumer's, and a `btn-lg` in `actions` or an oversized `user-icon` grows
+ * the bar and quietly misaligns the whole shell.
+ *
+ * We can't cap slot content without clipping it, which would be worse. So we
+ * detect the overflow and say so, rather than letting it pass unnoticed.
+ *
+ * "Single row" is measured (do all the bar's children share an offsetTop?),
+ * NOT inferred from a breakpoint — below `md` the bar is *supposed* to grow as
+ * the search and actions wrap (#93), and hardcoding a width here would
+ * reintroduce exactly the duplicate-breakpoint problem #101 removed.
+ */
+const headerRef = ref<HTMLElement | null>(null);
+const barRef = ref<HTMLElement | null>(null);
+let resizeObserver: ResizeObserver | null = null;
+let warnedAboutHeight = false;
+
+const checkContentBudget = () => {
+  const header = headerRef.value;
+  const bar = barRef.value;
+  if (warnedAboutHeight || !header || !bar) return;
+
+  const children = [...bar.children] as HTMLElement[];
+  if (children.length === 0) return;
+
+  // Compare vertical CENTRES, not `offsetTop`: the bar centres its items, so on
+  // a single row their tops differ by however much their heights differ. (An
+  // offsetTop comparison silently never fires — it was the first thing tried.)
+  const centres = children.map((child) => child.offsetTop + child.offsetHeight / 2);
+  const isSingleRow = centres.every((centre) => Math.abs(centre - centres[0]) < 1);
+  if (!isSingleRow) return; // wrapped: growing is correct here (#93).
+
+  const budget = parseFloat(
+    getComputedStyle(header).getPropertyValue("--dx-navbar-height"),
+  );
+  if (!budget) return;
+
+  // Sub-pixel tolerance: a fractional layout shouldn't trip this.
+  if (header.getBoundingClientRect().height > budget + 0.5) {
+    warnedAboutHeight = true;
+    // eslint-disable-next-line no-console
+    console.warn(
+      `[DXDashboardNavbar] The bar is taller than ${budget}px, so it no longer lines up with the sidebar header. ` +
+        "Something on its single row exceeds the content budget — size tall slot content " +
+        "(actions, user-icon) against `var(--dx-navbar-content-height)`.",
+    );
+  }
+};
+
+onMounted(() => {
+  if (typeof window === "undefined" || typeof ResizeObserver === "undefined") return;
+  resizeObserver = new ResizeObserver(checkContentBudget);
+  if (headerRef.value) resizeObserver.observe(headerRef.value);
+  checkContentBudget();
+});
+
+onBeforeUnmount(() => {
+  resizeObserver?.disconnect();
+  resizeObserver = null;
+});
+
 const getUserInitial = (user: { name: string } | null) => {
   if (!user?.name) return "";
   return user.name.charAt(0).toUpperCase();
@@ -189,61 +267,25 @@ const getUserInitial = (user: { name: string } | null) => {
   z-index: 1000;
 }
 
+/* The bar's vertical padding — and the single-row content budget derived from
+   it — is owned by theme.scss (`$dashboard-navbar-bar-padding-y`), so the
+   geometry has one source (#102). Only the floor lives here. */
 .dashboard-navbar__bar {
   min-height: 3.5rem;
-  padding: 0.5rem 0;
-}
-
-/* Push the user-menu cluster to the right. (The actions region carries its
-   own auto margin from `md` up — see the sibling rule below.) */
-.dashboard-navbar__end {
-  margin-left: auto;
 }
 
 /*
- * Mobile-first: the actions and the search each sit on their own full-width
- * row below the toggle / title / user-menu row (flex-basis 100% forces the
- * wrap; the bar and the sticky header grow to contain them — #93). The
- * actions row itself wraps so a wide button group stacks instead of
- * overflowing the viewport.
- * From `md` up everything moves inline: search between the title and the
- * actions (grows to fill the middle; `searchAlign` controls where its content
- * sits), actions right-aligned next to the user menu. The actions' order 2
- * holds at every size — only search and end change order across the
- * breakpoint.
+ * The bar's responsive LAYOUT (the order/flex rules and the `md` switch) lives
+ * in theme.scss, not here — see "Dashboard navbar layout" there.
+ *
+ * It has to: the `md` breakpoint is expressed twice in this component, once as
+ * Bootstrap utility classes (`d-none d-md-block` on the title, `d-md-flex` from
+ * `actionsOnMobile: "hide"`) and once as a media query. A media query in a
+ * scoped SFC block is compiled at OUR build with OUR `$grid-breakpoints` and
+ * baked into `dist/`, so a consumer who overrides `$grid-breakpoints` and
+ * compiles `theme.scss` from source would move the utilities and NOT the media
+ * query — leaving a band of viewport widths where the two disagree (#101).
+ * Compiling the layout from `media-breakpoint-up(md)` in theme.scss keeps both
+ * derived from the same variable in any build.
  */
-.dashboard-navbar__actions {
-  order: 2;
-  flex: 0 0 100%;
-  flex-wrap: wrap;
-}
-
-.dashboard-navbar__search {
-  order: 3;
-  flex: 0 0 100%;
-}
-
-@media (min-width: 768px) {
-  .dashboard-navbar__search {
-    order: 1;
-    flex: 1 1 auto;
-  }
-
-  .dashboard-navbar__actions {
-    flex: 0 1 auto;
-    flex-wrap: nowrap;
-    margin-left: auto;
-  }
-
-  .dashboard-navbar__end {
-    order: 3;
-  }
-
-  /* When the actions region is present it carries the push-right auto margin;
-     zero the user-menu cluster's so the two sit adjacent instead of having
-     the free space split between them. */
-  .dashboard-navbar__actions ~ .dashboard-navbar__end {
-    margin-left: 0;
-  }
-}
 </style>

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

@@ -324,6 +324,30 @@
             v-bind="inputPropsWithGuards"
         />
 
+        <!-- Searchable select: type to filter a long option list, while the
+             model keeps the option's VALUE (an id), not the typed text. The
+             `autocomplete` type below models the text, so it can't back a
+             foreign key. -->
+        <template v-else-if="field.type === 'select' && field.searchable">
+            <DAutocomplete
+                v-if="searchableOptionsReady"
+                v-model="fieldValue"
+                :options="resolvedOptions"
+                :placeholder="field.placeholder"
+                :required="field.required"
+                :state="fieldState"
+                :disabled="isDisabled || isReadonly || isPlaintext"
+                open-on-focus
+                v-bind="controlPropsWithGuards"
+            />
+            <!-- BAutocomplete resolves the input's display text from the model
+                 AT MOUNT and doesn't re-derive it when `options` arrive later,
+                 so an async list would leave the raw id showing ("51" instead
+                 of "Waitrose") — and a long list is exactly the case that loads
+                 async. Hold the control until the options are in. -->
+            <DFormInput v-else placeholder="Loading…" disabled />
+        </template>
+
         <!-- Select (sync or async options) -->
         <DFormSelect
             v-else-if="field.type === 'select'"
@@ -535,6 +559,7 @@ import DXSwitch from "./DXSwitch.vue";
 import DFormInvalidFeedback from "../base/DFormInvalidFeedback.vue";
 import DFormText from "../base/DFormText.vue";
 import DInputGroup from "../base/DInputGroup.vue";
+import DAutocomplete from "../base/DAutocomplete.vue";
 import DButton from "../base/DButton.vue";
 import DXFieldLabel from "./DXFieldLabel.vue";
 import type { UseFormReturn } from "../../composables/useForm";
@@ -918,6 +943,12 @@ const isPlaintext = computed(() => resolveMaybe(props.field.plaintext) ?? false)
 
 const passwordRevealed = ref(false);
 
+// See the template: the searchable select can't render before its options
+// resolve, or it shows the raw id instead of the option's label.
+const searchableOptionsReady = computed(
+    () => !props.field.optionsLoader || loadedOptions.value !== null,
+);
+
 const isRevealablePassword = computed(
     () =>
         props.field.type === "password" &&