@omnitend/dashboard-for-laravel 0.16.4 → 0.18.0

package/dist/types/index.d.ts

@@ -34,6 +34,25 @@ export interface FieldOption extends Record<string, unknown> {
  * again on model change when `reloadOptionsOnChange` is set.
  */
 export type OptionsLoader = (model: any) => Promise<FieldOption[]>;
+/**
+ * Label column width for horizontal layout, mirroring Bootstrap Vue Next's
+ * `BFormGroup` `labelCols`/`labelCols*` props: either a single width applied
+ * at all breakpoints, or a per-breakpoint object (omitted breakpoints fall
+ * back to BFormGroup's own defaults, which is how "collapse to vertical
+ * below a breakpoint" comes for free — e.g. `{ md: 3 }` stacks below `md`).
+ *
+ * Deliberately excludes `boolean` (which BFormGroup's own `labelCols` prop
+ * accepts): Vue's type-based `defineProps` auto-defaults an omitted prop to
+ * `false` (not `undefined`) whenever its declared type includes `boolean`,
+ * which would silently break the `field.labelCols ?? formLabelCols ?? 3`
+ * fallback chain used to resolve this value.
+ */
+export type LabelCols = number | {
+    sm?: number;
+    md?: number;
+    lg?: number;
+    xl?: number;
+};
 /**
  * Field definition shared by every form renderer.
  *
@@ -123,9 +142,21 @@ export interface FieldDefinition {
     inputProps?: Record<string, any>;
     /**
      * Render the field full-width with no label wrapper, delegating its
-     * content to the `#span(<key>)` slot. Useful for custom blocks.
+     * content to the `#span(<key>)` slot. Useful for custom blocks. Also
+     * doubles as the "fill both columns" escape hatch in horizontal layout —
+     * a span field always bypasses the label/content column split.
      */
     span?: boolean;
+    /**
+     * Per-field override of DXForm's `layout` prop ("vertical" | "horizontal").
+     * Falls back to the form-level `layout` when omitted.
+     */
+    layout?: "vertical" | "horizontal";
+    /**
+     * Per-field override of DXForm's `labelCols` prop, for horizontal
+     * layout. Falls back to the form-level `labelCols` when omitted.
+     */
+    labelCols?: LabelCols;
     /**
      * Component rendered for `type: "component"` fields. Receives
      * `modelValue`, `field`, `model` props and emits `update:modelValue`.
@@ -144,6 +175,24 @@ export interface FieldDefinition {
     /** Minimum / maximum number of repeater rows. */
     minItems?: number;
     maxItems?: number;
+    /**
+     * For `repeater` fields: `"cards"` (default) stacks each row as its own
+     * card with sub-fields listed vertically — best for rows with several
+     * or complex sub-fields. `"table"` renders one row per item with
+     * sub-fields as columns — far more compact for simple child-row lists
+     * (e.g. 2-3 short sub-fields). Named `repeaterLayout` (not `layout`) to
+     * avoid colliding with the unrelated form-level `layout` prop
+     * ("vertical" | "horizontal") every field type accepts.
+     */
+    repeaterLayout?: "cards" | "table";
+    /**
+     * For `repeater` fields in `cards` layout: show each row's 1-based
+     * position (e.g. "1", "2") next to its Remove button. Off by default —
+     * only meaningful once a consumer explicitly wants it (e.g. rows the
+     * user thinks of as numbered/ordered); most repeaters don't need it.
+     * Not applicable to `table` layout, which has no equivalent column.
+     */
+    showRowIndex?: boolean;
     /**
      * For `repeater` fields backed by an upsert-children API contract (rows
      * carrying a persisted `id` are only deleted server-side when submitted

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.16.4",
+  "version": "0.18.0",
   "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
 // ----------------------------------------------------------------------------
@@ -171,6 +188,17 @@ $dashboard-navbar-height: 64px;
   );
 }
 
+// Bootstrap's `.input-group` defaults to `flex-wrap: wrap`, letting a
+// narrow container (e.g. a compact table cell, a small screen) stack the
+// prepend/append affix onto its own line below the input. That breaks the
+// visual "one control" continuity an input-group exists to provide — an
+// affix + input should shrink/scroll before it wraps, never stack. Applies
+// globally (currency/percentage fields, DAutocomplete's own `:deep()`
+// override becomes redundant but harmless here).
+.input-group {
+  flex-wrap: nowrap;
+}
+
 // ----------------------------------------------------------------------------
 // Dashboard Custom Styles
 // ----------------------------------------------------------------------------

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>