@omnitend/dashboard-for-laravel 0.17.0 → 0.18.1

package/dist/types/index.d.ts

@@ -157,6 +157,16 @@ export interface FieldDefinition {
      * layout. Falls back to the form-level `labelCols` when omitted.
      */
     labelCols?: LabelCols;
+    /**
+     * Skip rendering the field's own label. In horizontal layout no label
+     * column is reserved either, so the control spans the full width. Useful
+     * for `switch` (and `checkbox`) fields, which render their own label
+     * inside the control — the outer row label would otherwise duplicate it,
+     * and the self-label then lines up with sibling row labels. Also used
+     * internally by `DXRepeater`'s `table` layout, where a column header
+     * already names the field.
+     */
+    hideLabel?: boolean;
     /**
      * Component rendered for `type: "component"` fields. Receives
      * `modelValue`, `field`, `model` props and emits `update:modelValue`.

package/docs/public/api-reference.json

@@ -1,8 +1,8 @@
 {
-  "generated": "2026-07-06T20:01:04.234Z",
+  "generated": "2026-07-08T06:35:48.024Z",
   "package": {
     "name": "@omnitend/dashboard-for-laravel",
-    "version": "0.16.3"
+    "version": "0.17.0"
   },
   "components": {
     "base": [
@@ -184,7 +184,7 @@
             "name": "variant",
             "type": "union",
             "required": false,
-            "default": "'primary'",
+            "default": "\"primary\"",
             "description": "The visual style variant of the button"
           },
           {
@@ -192,10 +192,62 @@
             "type": "Size",
             "required": false,
             "description": "The size of the button. Omit for the default (medium) size —\nbootstrap-vue-next 0.45 removed the no-op `'md'` value from `Size`."
+          },
+          {
+            "name": "disabled",
+            "type": "boolean",
+            "required": false,
+            "default": "false",
+            "description": "Disable the button. Combined with `loading` — either one disables it."
+          },
+          {
+            "name": "loading",
+            "type": "boolean",
+            "required": false,
+            "default": "false",
+            "description": "Show an in-flight state: the button is disabled immediately and, after\n`spinnerDelay`, a trailing spinner appears (and the label swaps to\n`loadingText` if given)."
+          },
+          {
+            "name": "loadingText",
+            "type": "string",
+            "required": false,
+            "description": "Label shown in place of the default slot while the spinner is visible.\nOmit to keep the original label alongside the spinner."
+          },
+          {
+            "name": "icon",
+            "type": "string",
+            "required": false,
+            "description": "Leading Bootstrap Icons glyph name, rendered as `<i class=\"bi bi-{icon}\">`.\ne.g. `icon=\"save\"`. Hidden while the loading spinner is visible."
+          },
+          {
+            "name": "block",
+            "type": "boolean",
+            "required": false,
+            "default": "false",
+            "description": "Full-width button (BS5 `w-100` idiom, replacing the dropped `.btn-block`)."
+          },
+          {
+            "name": "spinnerDelay",
+            "type": "number",
+            "required": false,
+            "default": "500",
+            "description": "Anti-flash: how long (ms) `loading` must stay true before the spinner is\nshown, so fast actions never flicker one in."
+          },
+          {
+            "name": "minSpinnerTime",
+            "type": "number",
+            "required": false,
+            "default": "100",
+            "description": "Anti-flash: minimum time (ms) the spinner stays visible once shown, so a\nloading state that clears quickly doesn't strobe it away."
           }
         ],
         "events": [],
         "slots": [
+          {
+            "name": "default",
+            "description": "",
+            "bindings": []
+          },
           {
             "name": "name",
             "description": "",
@@ -1713,6 +1765,24 @@
             "type": "string",
             "required": false,
             "description": "Error key for validation lookups (defaults to keyPath/field.key)."
+          },
+          {
+            "name": "layout",
+            "type": "union",
+            "required": false,
+            "description": "Field layout: \"vertical\" (default, label above input) or \"horizontal\"\n(label left, input right). Normally set by DXForm (form-level, with\n`field.layout` taking precedence); pass directly when using DXField\nstandalone."
+          },
+          {
+            "name": "labelCols",
+            "type": "LabelCols",
+            "required": false,
+            "description": "Label column width for horizontal layout (mirrors BFormGroup)."
+          },
+          {
+            "name": "hideLabel",
+            "type": "boolean",
+            "required": false,
+            "description": "Skip rendering the field's own label entirely (only affects the\nstandard labelled-field branch). Used by DXRepeater's `table` layout,\nwhere a column header already names the field and a per-row label\nwould waste space in the cell."
           }
         ],
         "events": [],
@@ -1925,6 +1995,26 @@
             "required": false,
             "default": "true",
             "description": "Auto-switch to the first tab containing a validation error."
+          },
+          {
+            "name": "card",
+            "type": "boolean",
+            "required": false,
+            "default": "false",
+            "description": "Wrap the form in a card for a visual boundary (mirrors DXTable's\n`card` prop). Tabbed forms render the tab nav as a BS5\ncard-header-tabs instead of double-wrapping. Off by default since\nDXForm is commonly embedded in a page card or modal already."
+          },
+          {
+            "name": "layout",
+            "type": "union",
+            "required": false,
+            "default": "\"vertical\"",
+            "description": "Form-wide field layout: \"vertical\" (default, label above input) or\n\"horizontal\" (label left, input right). Overridable per-field via\n`field.layout`. A field with `span: true` always renders full-width,\nregardless of layout."
+          },
+          {
+            "name": "labelCols",
+            "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\"."
           }
         ],
         "events": [
@@ -1987,6 +2077,58 @@
               }
             ]
           },
+          {
+            "name": "`field(${field.key})`",
+            "description": "Fully replaces a field's rendering (including its label), keyed by field key: `field(<key>)`. Unlike `value(<key>)`, bypasses DXField entirely — like `tab-content`, this also supersedes `field-before(<key>)`/`field-after(<key>)` for the same key.",
+            "bindings": [
+              {
+                "name": "name",
+                "title": "binding"
+              },
+              {
+                "title": "binding",
+                "type": {
+                  "name": "FieldDefinition"
+                },
+                "name": "field",
+                "description": "The field definition being replaced."
+              },
+              {
+                "title": "binding",
+                "type": {
+                  "name": "object"
+                },
+                "name": "model",
+                "description": "Live form data merged with `context`, for predicates."
+              }
+            ]
+          },
+          {
+            "name": "`field-before(${field.key})`",
+            "description": "Content inserted directly above a field, keyed by field key: `field-before(<key>)`. Not rendered when `field(<key>)` replaces the same field.",
+            "bindings": [
+              {
+                "name": "name",
+                "title": "binding"
+              },
+              {
+                "title": "binding",
+                "type": {
+                  "name": "FieldDefinition"
+                },
+                "name": "field",
+                "description": "The field about to be rendered."
+              },
+              {
+                "title": "binding",
+                "type": {
+                  "name": "object"
+                },
+                "name": "model",
+                "description": "Live form data merged with `context`, for predicates."
+              }
+            ]
+          },
           {
             "name": "slotName",
             "description": "Per-field overrides forwarded to DXField, keyed by field key: `value(<key>)`, `span(<key>)`, `info(<key>)`, `hint(<key>)`, `repeater-row(<key>)`.",
@@ -1997,6 +2139,32 @@
               }
             ]
           },
+          {
+            "name": "`field-after(${field.key})`",
+            "description": "Content inserted directly below a field, keyed by field key: `field-after(<key>)`. Not rendered when `field(<key>)` replaces the same field.",
+            "bindings": [
+              {
+                "name": "name",
+                "title": "binding"
+              },
+              {
+                "title": "binding",
+                "type": {
+                  "name": "FieldDefinition"
+                },
+                "name": "field",
+                "description": "The field that was just rendered."
+              },
+              {
+                "title": "binding",
+                "type": {
+                  "name": "object"
+                },
+                "name": "model",
+                "description": "Live form data merged with `context`, for predicates."
+              }
+            ]
+          },
           {
             "name": "`tab-after(${tab.key})`",
             "description": "Content inserted below a tab's fields, keyed by tab (slot name `tab-after(<tabKey>)`).",
@@ -2130,7 +2298,7 @@
         "slots": [
           {
             "name": "row",
-            "description": "Custom layout for a single repeater row, replacing the default sub-field stack.",
+            "description": "Custom layout for a single repeater row, replacing the default sub-field stack (including the built-in Remove control — call `remove()` yourself). In table layout, rendered as the `<tr>`'s children: supply one `<td>` per sub-field plus a trailing `<td>` to match the header's column count (the header always includes an empty column for the built-in remove button).",
             "bindings": [
               {
                 "title": "binding",

package/docs/public/docs-map.md

@@ -1,7 +1,7 @@
 # Documentation Map
 
 > Auto-generated hierarchical overview of all documentation
-> Last updated: 2026-07-06T20:01:04.293Z
+> Last updated: 2026-07-08T06:35:48.080Z
 
 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.17.0",
+  "version": "0.18.1",
   "description": "Vue 3 dashboard components for Laravel with Bootstrap Vue Next",
   "type": "module",
   "main": "./dist/dashboard-for-laravel.umd.cjs",
@@ -88,6 +88,7 @@
     "@vue/test-utils": "^2.4.6",
     "astro": "^5.15.1",
     "bootstrap": "^5.3.8",
+    "bootstrap-icons": "^1.13.1",
     "chart.js": "^4.5.1",
     "happy-dom": "^20.0.8",
     "pagefind": "^1.4.0",

package/resources/css/theme.scss

@@ -152,6 +152,23 @@ $dashboard-navbar-height: 64px;
 
 @import "bootstrap-vue-next/dist/bootstrap-vue-next.css";
 
+// ----------------------------------------------------------------------------
+// Import Bootstrap Icons
+// ----------------------------------------------------------------------------
+// Ships the icon font so `DButton`'s `icon` prop (and any consumer `<i class="bi
+// bi-*">`) renders without the consumer wiring up their own icon set.
+//
+// Imported as SCSS (not the prebuilt CSS) so we can override the font `src` to
+// woff2 ONLY — dropping bootstrap-icons' legacy `woff` fallback. In the library
+// build Vite inlines CSS `url()` assets as data URIs, so shipping both formats
+// doubled the embedded font bytes in `dist/style.css` for no benefit (every
+// browser we target reads woff2). The override must come BEFORE the import so
+// bootstrap-icons' own `!default` src doesn't re-add the woff. The bare
+// `bootstrap-icons/...` specifier resolves through Vite's module resolver.
+$bootstrap-icons-font-src: url("bootstrap-icons/font/fonts/bootstrap-icons.woff2")
+  format("woff2");
+@import "bootstrap-icons/font/bootstrap-icons";
+
 // ----------------------------------------------------------------------------
 // Forms
 // ----------------------------------------------------------------------------

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

@@ -2,16 +2,26 @@
 /**
  * DButton - A type-safe wrapper around Bootstrap Vue Next's BButton component
  *
+ * Adds three base-level button behaviours on top of `variant`/`size`:
+ * - `loading` — disables the button and shows a trailing spinner while an async
+ *   action is in flight, with anti-flash timing (no spinner for sub-`spinnerDelay`
+ *   actions; a `minSpinnerTime` floor once shown so it never strobes).
+ * - `icon` — a leading Bootstrap Icons glyph (e.g. `icon="save"` → `bi bi-save`).
+ * - `block` — full-width button (the BS5 replacement for the dropped `.btn-block`).
+ *
  * @component
  * @example
  * ```vue
  * <DButton variant="primary" size="lg">Click Me</DButton>
- * <DButton variant="link-danger" @click="handleClick">Delete</DButton>
+ * <DButton icon="save" variant="primary">Save</DButton>
+ * <DButton :loading="isSaving" loading-text="Saving…">Save</DButton>
+ * <DButton block>Continue</DButton>
  * ```
  */
 import { BButton } from "bootstrap-vue-next";
 import type { ButtonVariant, Size } from "bootstrap-vue-next";
-import { useSlots } from "vue";
+import { computed, onBeforeUnmount, ref, useSlots, watch } from "vue";
+import DSpinner from "./DSpinner.vue";
 
 const slots = useSlots();
 
@@ -37,21 +47,175 @@ interface Props {
    * bootstrap-vue-next 0.45 removed the no-op `'md'` value from `Size`.
    */
   size?: Size;
+
+  /**
+   * Disable the button. Combined with `loading` — either one disables it.
+   */
+  disabled?: boolean;
+
+  /**
+   * Show an in-flight state: the button is disabled immediately and, after
+   * `spinnerDelay`, a trailing spinner appears (and the label swaps to
+   * `loadingText` if given).
+   *
+   * Diverges from bvn: `BButton` has a native `loading`/`loadingText` that
+   * shows its spinner immediately. We intercept both and render our own
+   * anti-flash spinner instead, so bvn's native loading never fires. See
+   * DIVERGENCES.md.
+   * @default false
+   */
+  loading?: boolean;
+
+  /**
+   * Label shown in place of the default slot while the spinner is visible.
+   * Omit to keep the original label alongside the spinner. (See `loading` re:
+   * the bvn divergence.)
+   */
+  loadingText?: string;
+
+  /**
+   * Leading Bootstrap Icons glyph name, rendered as `<i class="bi bi-{icon}">`.
+   * e.g. `icon="save"`. Hidden while the loading spinner is visible.
+   *
+   * Diverges from bvn: `BButton`'s native `icon` is a `boolean` (icon-button
+   * styling mode). We redefine it as a glyph-name `string`, so bvn's boolean
+   * icon mode is unreachable through `DButton`. See DIVERGENCES.md.
+   */
+  icon?: string;
+
+  /**
+   * Full-width button (BS5 `w-100` idiom, replacing the dropped `.btn-block`).
+   * @default false
+   */
+  block?: boolean;
+
+  /**
+   * Anti-flash: how long (ms) `loading` must stay true before the spinner is
+   * shown, so fast actions never flicker one in.
+   * @default 500
+   */
+  spinnerDelay?: number;
+
+  /**
+   * Anti-flash: minimum time (ms) the spinner stays visible once shown, so a
+   * loading state that clears quickly doesn't strobe it away.
+   * @default 100
+   */
+  minSpinnerTime?: number;
 }
 
-withDefaults(defineProps<Props>(), {
-  variant: 'primary',
+const props = withDefaults(defineProps<Props>(), {
+  variant: "primary",
+  disabled: false,
+  loading: false,
+  block: false,
+  spinnerDelay: 500,
+  minSpinnerTime: 100,
 });
+
+// --- Spinner anti-flash state machine -------------------------------------
+// `loading` disables the button instantly (prevents double-submit), but the
+// *spinner visual* is gated: it only appears once `loading` has held for
+// `spinnerDelay`, and once shown it stays for at least `minSpinnerTime`.
+const showSpinner = ref(false);
+let delayTimer: ReturnType<typeof setTimeout> | null = null;
+let minTimer: ReturnType<typeof setTimeout> | null = null;
+let shownAt = 0;
+
+function clearTimer(timer: ReturnType<typeof setTimeout> | null) {
+  if (timer !== null) clearTimeout(timer);
+}
+
+watch(
+  () => props.loading,
+  (isLoading) => {
+    // The spinner is a client-only concern. On the server there's no unmount
+    // hook to clear a scheduled timer, and the spinner never paints before
+    // hydration anyway (it's gated behind `spinnerDelay`), so skip the timers
+    // entirely during SSR — `showSpinner` stays false, matching the initial
+    // client render and avoiding a dangling server-side timeout.
+    if (typeof window === "undefined") return;
+    if (isLoading) {
+      // Cancel any pending hide — we're loading again, keep the spinner up.
+      clearTimer(minTimer);
+      minTimer = null;
+      // Already showing, or already counting down to show: nothing to do.
+      if (showSpinner.value || delayTimer !== null) return;
+      delayTimer = setTimeout(() => {
+        delayTimer = null;
+        showSpinner.value = true;
+        shownAt = Date.now();
+      }, props.spinnerDelay);
+    } else {
+      // Stopped before the spinner ever appeared → cancel, no flash at all.
+      if (delayTimer !== null) {
+        clearTimeout(delayTimer);
+        delayTimer = null;
+        return;
+      }
+      if (!showSpinner.value) return;
+      const remaining = props.minSpinnerTime - (Date.now() - shownAt);
+      if (remaining <= 0) {
+        showSpinner.value = false;
+      } else if (minTimer === null) {
+        minTimer = setTimeout(() => {
+          minTimer = null;
+          showSpinner.value = false;
+        }, remaining);
+      }
+    }
+  },
+  { immediate: true },
+);
+
+onBeforeUnmount(() => {
+  clearTimer(delayTimer);
+  clearTimer(minTimer);
+});
+
+// BButton owns the default slot (we compose icon/spinner/label into it); any
+// other named slots are forwarded through untouched.
+const passthroughSlotNames = computed(() =>
+  Object.keys(slots).filter((name) => name !== "default"),
+);
+
+// Bootstrap utility classes are global, so they apply regardless of whether the
+// wrapper's scope-id reaches BButton's rendered <button> — avoiding the scoped
+// `:deep()`-on-a-B-root trap. Only add the flex row when there's an adornment
+// to space out.
+const hasAdornment = computed(
+  () => Boolean(props.icon) || showSpinner.value,
+);
 </script>
 
 <template>
   <BButton
     :variant="variant"
     :size="size"
+    :disabled="disabled || loading || showSpinner"
+    :aria-busy="loading || showSpinner || undefined"
+    :class="[
+      { 'd-inline-flex align-items-center justify-content-center gap-2': hasAdornment },
+      { 'w-100': block },
+    ]"
     v-bind="$attrs"
   >
-    <template v-for="(_, name) in slots" :key="name" #[name]>
-      <slot :name="name" />
+    <i
+      v-if="icon && !showSpinner"
+      :class="['bi', `bi-${icon}`]"
+      aria-hidden="true"
+    ></i>
+    <template v-if="showSpinner && loadingText">{{ loadingText }}</template>
+    <slot v-else />
+    <DSpinner v-if="showSpinner" small />
+
+    <!-- Forward any other named slots untouched, with their slot props. -->
+    <template
+      v-for="name in passthroughSlotNames"
+      :key="name"
+      #[name]="slotProps"
+    >
+      <slot :name="name" v-bind="slotProps" />
     </template>
   </BButton>
 </template>

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

@@ -35,7 +35,10 @@
         :class="field.class || 'mb-3'"
         v-bind="horizontalAttrs"
     >
-        <template #label>
+        <!-- The inner label (beside the checkbox) always names the control, so
+             hideLabel drops only the redundant outer row label; horizontalAttrs
+             then reserves no label column, letting the control span full width. -->
+        <template v-if="!hideLabel" #label>
             <DXFieldLabel :label="resolvedLabel" :info="resolvedInfo" />
         </template>
         <slot
@@ -119,7 +122,10 @@
         :class="[field.class || 'mb-3', 'dx-switch', { 'dx-switch--on': switchIsOn }]"
         v-bind="horizontalAttrs"
     >
-        <template #label>
+        <!-- The switch renders its own label inside the control, so hideLabel
+             drops only the redundant outer row label; horizontalAttrs then
+             reserves no label column, letting the toggle span full width. -->
+        <template v-if="!hideLabel" #label>
             <DXFieldLabel :label="resolvedLabel" :info="resolvedInfo" />
         </template>
         <slot
@@ -203,7 +209,7 @@
     <!-- Repeater: nested, repeatable sub-form -->
     <div v-else-if="field.type === 'repeater'" :class="field.class || 'mb-3'">
         <DFormGroup v-bind="repeaterHorizontalAttrs">
-            <template #label>
+            <template v-if="!hideLabel" #label>
                 <DXFieldLabel :label="resolvedLabel" :info="resolvedInfo" />
             </template>
             <DXRepeater
@@ -503,10 +509,14 @@ interface Props {
     labelCols?: LabelCols;
 
     /**
-     * Skip rendering the field's own label entirely (only affects the
-     * standard labelled-field branch). Used by DXRepeater's `table` layout,
-     * where a column header already names the field and a per-row label
-     * would waste space in the cell.
+     * Skip rendering the field's own (outer) label. Applies to the standard
+     * labelled-field branch and to the checkbox/switch/repeater branches. In
+     * horizontal layout no label column is reserved either, so the control
+     * spans the full width (a switch/checkbox self-label then lines up with
+     * sibling row labels). Used by DXRepeater's `table` layout (a column
+     * header already names the field) and by consumers hiding the redundant
+     * row label on a switch/checkbox, which render their own label inside the
+     * control (#78).
      */
     hideLabel?: boolean;
 }
@@ -545,9 +555,17 @@ function labelColsAttrs(cols: LabelCols | undefined): Record<string, any> {
 }
 
 // Default to a 3-column label when horizontal but no width was configured,
-// so `layout: "horizontal"` alone is enough to see the effect.
+// so `layout: "horizontal"` alone is enough to see the effect. When the
+// field's label is hidden, reserve no label column at all — BFormGroup would
+// otherwise still emit an empty label column (it goes horizontal whenever any
+// labelCols are set, regardless of whether a label exists), leaving the
+// control indented in the input column beside dead space. Dropping the column
+// lets the control span full width, so a switch/checkbox self-label lines up
+// with sibling row labels (#78).
 const horizontalAttrs = computed<Record<string, any>>(() =>
-    isHorizontal.value ? labelColsAttrs(props.labelCols ?? 3) : {},
+    isHorizontal.value && !props.hideLabel
+        ? labelColsAttrs(props.labelCols ?? 3)
+        : {},
 );
 
 // A table-layout repeater is inherently wide — squeezing its own label into a
@@ -846,9 +864,12 @@ onBeforeUnmount(() => {
    `justify-content: space-between` on a full-width box used to leave a wide
    unclickable gap between the label and the toggle (only the tiny toggle
    itself was a real click target); shrinking the box to fit its content
-   removes that dead zone entirely. */
+   removes that dead zone entirely. Uses block-level `flex` (not `inline-flex`)
+   so the box stays shrink-to-fit yet still takes its own line: an inline-level
+   box let a following `<small class="form-text">` hint flow inline beside it
+   instead of dropping below the control like every other field type (#79). */
 .dx-switch :deep(.form-check) {
-    display: inline-flex;
+    display: flex;
     align-items: center;
     gap: 0.75rem;
     width: fit-content;

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

@@ -88,6 +88,7 @@
                                     :model="model"
                                     :layout="field.layout ?? layout"
                                     :label-cols="field.labelCols ?? labelCols"
+                                    :hide-label="field.hideLabel"
                                 >
                                     <template
                                         v-for="(slotName, target) in fieldSlotMap(field.key)"
@@ -151,6 +152,7 @@
                             :model="model"
                             :layout="field.layout ?? layout"
                             :label-cols="field.labelCols ?? labelCols"
+                            :hide-label="field.hideLabel"
                         >
                             <template
                                 v-for="(slotName, target) in fieldSlotMap(field.key)"
@@ -176,11 +178,12 @@
                     v-if="showSubmit"
                     type="submit"
                     variant="primary"
-                    :disabled="resolvedForm.processing"
-                    class="w-100 mt-3"
+                    block
+                    :loading="resolvedForm.processing"
+                    :loading-text="submitLoadingText"
+                    class="mt-3"
                 >
-                    <span v-if="resolvedForm.processing">{{ submitLoadingText }}</span>
-                    <span v-else>{{ submitText }}</span>
+                    {{ submitText }}
                 </DButton>
 
                 <!--
@@ -202,11 +205,12 @@
                 v-if="showSubmit"
                 type="submit"
                 variant="primary"
-                :disabled="resolvedForm.processing"
-                class="w-100 mt-3"
+                block
+                :loading="resolvedForm.processing"
+                :loading-text="submitLoadingText"
+                class="mt-3"
             >
-                <span v-if="resolvedForm.processing">{{ submitLoadingText }}</span>
-                <span v-else>{{ submitText }}</span>
+                {{ submitText }}
             </DButton>
 
             <!--