@omnitend/dashboard-for-laravel 0.28.0 → 0.30.0

package/docs/public/api-reference.json

@@ -1,8 +1,8 @@
 {
-  "generated": "2026-07-18T13:55:43.374Z",
+  "generated": "2026-07-20T07:09:59.465Z",
   "package": {
     "name": "@omnitend/dashboard-for-laravel",
-    "version": "0.28.0"
+    "version": "0.30.0"
   },
   "components": {
     "base": [
@@ -53,7 +53,15 @@
         "category": "base",
         "filePath": "resources/js/components/base/DAlert.vue",
         "description": "",
-        "props": [],
+        "props": [
+          {
+            "name": "modelValue",
+            "type": "union",
+            "required": false,
+            "default": "true",
+            "description": ""
+          }
+        ],
         "events": [],
         "slots": [
           {
@@ -94,8 +102,27 @@
         "name": "DAutocomplete",
         "category": "base",
         "filePath": "resources/js/components/base/DAutocomplete.vue",
-        "description": "Type-safe wrapper around Bootstrap Vue Next BAutocomplete component. Text input with a filtered dropdown of suggestions (typeahead/combobox). Pass `options` and bind `v-model`; supports `multiple` and a custom `filterFunction`.",
-        "props": [],
+        "description": "Type-safe wrapper around Bootstrap Vue Next BAutocomplete component. Text input with a filtered dropdown of suggestions (typeahead/combobox). Pass `options` and bind `v-model`; supports `multiple` and a custom `filterFunction`. `null-option` adds an opt-in, pinned \"no selection\" row (see below) so a searchable single-select can always reach \"none\" in-list (#138).",
+        "props": [
+          {
+            "name": "options",
+            "type": "AutocompleteOptions",
+            "required": false,
+            "description": "Options passed straight through to BAutocomplete (see its `options` prop)."
+          },
+          {
+            "name": "filterFunction",
+            "type": "FilterFunction",
+            "required": false,
+            "description": "A custom filter. Composed with `null-option` rather than replaced: when a\nnull option is present it stays pinned and this runs on the rest."
+          },
+          {
+            "name": "nullOption",
+            "type": "union",
+            "required": false,
+            "description": "Prepend a pinned, never-filtered, selectable \"no selection\" row whose value\nis `null` (#138). `true` → default label \"None\"; a string → that label.\nSelecting it sets the model to `null` (bvn reads that as no selection, so\nthe ✕ hides and the placeholder shows). Off by default — unchanged\nbehaviour. DXTable does NOT use this; it builds its own \"All\" option."
+          }
+        ],
         "events": [],
         "slots": [
           {
@@ -481,6 +508,27 @@
         ],
         "methods": []
       },
+      {
+        "name": "DFormCheckboxGroup",
+        "category": "base",
+        "filePath": "resources/js/components/base/DFormCheckboxGroup.vue",
+        "description": "Type-safe wrapper around Bootstrap Vue Next BFormCheckboxGroup component. Renders a group of checkboxes from an `options` array (or slot content); the `v-model` is the ARRAY of checked option values (\"pick any of N\").",
+        "props": [],
+        "events": [],
+        "slots": [
+          {
+            "name": "name",
+            "description": "",
+            "bindings": [
+              {
+                "name": "name",
+                "title": "binding"
+              }
+            ]
+          }
+        ],
+        "methods": []
+      },
       {
         "name": "DFormGroup",
         "category": "base",
@@ -2085,7 +2133,14 @@
             "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."
+            "description": "Wrap the form in a card for a visual boundary (mirrors DXTable's\n`card` prop). Off by default since DXForm is commonly embedded in a\npage card or modal already. Tabbed forms are wrapped by default\nregardless — see `cardTabs`; setting `card` also forces the tabbed\ncard on even when `cardTabs` is disabled."
+          },
+          {
+            "name": "cardTabs",
+            "type": "boolean",
+            "required": false,
+            "default": "true",
+            "description": "Wrap a TABBED form's content in a card panel so the active tab reads\nas a finished panel connected to the tab strip (the standard\nBootstrap card-with-tabs pattern) rather than floating on the bare\npage background (#159). On by default. Set `false` for bare tabs\n(e.g. inside a modal that already provides a boundary). Ignored for\nflat (non-tabbed) forms — use `card` for those."
           },
           {
             "name": "layout",
@@ -2750,6 +2805,13 @@
             "default": "true",
             "description": "Show per-page selector"
           },
+          {
+            "name": "showCount",
+            "type": "boolean",
+            "required": false,
+            "default": "true",
+            "description": "Show the footer's item-count caption (\"N items.\" / \"X to Y out of Z\nitems.\"). Defaults to `true`. Set `false` to suppress just the caption,\nindependent of the pager — a page ported from a plain `<b-table>` that\nhides the pager with `:show-pagination=\"false\"` would otherwise gain a\ncaption it never had (#127)."
+          },
           {
             "name": "perPageOptions",
             "type": "Array",
@@ -2768,7 +2830,7 @@
             "name": "perPage",
             "type": "number",
             "required": false,
-            "description": "Items per page (for provider mode, v-model support)"
+            "description": "Items per page. With a `v-model:per-page` it is controlled state; a bare\n`:per-page=\"20\"` is the INITIAL page size (see the initial-value vs\ncontrolled note above). When passed explicitly it takes PRECEDENCE over any\nper-page preference persisted in localStorage — `:per-page=\"20\"` always\nstarts at 20, never a size the user once picked on another table (#124).\nOmit it to let a stored preference (URL-keyed tables only) or the default\napply."
           },
           {
             "name": "striped",
@@ -2924,6 +2986,13 @@
             "type": "boolean",
             "required": false,
             "description": "Enable client-side filtering, sorting, and pagination on items array"
+          },
+          {
+            "name": "fixedLayout",
+            "type": "boolean",
+            "required": false,
+            "default": "false",
+            "description": "Apply `table-layout: fixed` to the underlying table. Off by default, so\nexisting tables keep their content-sized columns. When on, column widths\nstop depending on cell content, so they no longer reshuffle when a filter\nnarrows the rows — the table stays put as you filter (#156). Combine with\nper-field `width`/`minWidth` to control the proportions; columns with no\ndeclared width share the remaining space equally."
           }
         ],
         "events": [
@@ -3363,6 +3432,12 @@
             "required": true,
             "description": "Whether to render the per-page selector."
           },
+          {
+            "name": "showCount",
+            "type": "boolean",
+            "required": true,
+            "description": "Whether to render the item-count caption (the \"X out of Z items\" line)."
+          },
           {
             "name": "singularItemName",
             "type": "string",
@@ -3481,8 +3556,8 @@
     ]
   },
   "stats": {
-    "totalComponents": 75,
-    "baseComponents": 56,
+    "totalComponents": 76,
+    "baseComponents": 57,
     "extendedComponents": 19
   }
 }

package/docs/public/docs-map.md

@@ -1,7 +1,7 @@
 # Documentation Map
 
 > Auto-generated hierarchical overview of all documentation
-> Last updated: 2026-07-18T13:55:43.432Z
+> Last updated: 2026-07-20T07:09:59.531Z
 
 This file provides a complete map of all available documentation for AI agents and developers.
 

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 68 Vue 3 components for building Laravel dashboards with Bootstrap Vue Next.
+> A dual-package library (NPM + Composer) providing 69 Vue 3 components for building Laravel dashboards with Bootstrap Vue Next.
 
 ## Installation
 
@@ -19,7 +19,7 @@
 - [Theming](/guide/theming): Customize appearance with CSS variables
 - [TypeScript](/guide/typescript): TypeScript types and best practices
 
-## Base Components (56 components)
+## Base Components (57 components)
 
 Lightweight type-safe wrappers around Bootstrap Vue Next components providing API stability and consistent theming.
 
@@ -43,6 +43,7 @@ Lightweight type-safe wrappers around Bootstrap Vue Next components providing AP
 - [DDropdownItem](/components/base/ddropdownitem): Bootstrap Vue Next DropdownItem wrapper
 - [DForm](/components/base/dform): Bootstrap Vue Next Form wrapper
 - [DFormCheckbox](/components/base/dformcheckbox): Bootstrap Vue Next FormCheckbox wrapper
+- [DFormCheckboxGroup](/components/base/dformcheckboxgroup): Bootstrap Vue Next FormCheckboxGroup wrapper
 - [DFormGroup](/components/base/dformgroup): Bootstrap Vue Next FormGroup wrapper
 - [DFormInput](/components/base/dforminput): Bootstrap Vue Next FormInput wrapper
 - [DFormInvalidFeedback](/components/base/dforminvalidfeedback): Bootstrap Vue Next FormInvalidFeedback wrapper

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omnitend/dashboard-for-laravel",
-  "version": "0.28.0",
+  "version": "0.30.0",
   "description": "Vue 3 dashboard components for Laravel with Bootstrap Vue Next",
   "type": "module",
   "main": "./dist/dashboard-for-laravel.umd.cjs",
@@ -15,6 +15,11 @@
       "import": "./dist/dashboard-for-laravel.js",
       "require": "./dist/dashboard-for-laravel.umd.cjs"
     },
+    "./charts": {
+      "types": "./dist/charts.d.ts",
+      "import": "./dist/charts.js",
+      "require": "./dist/charts.umd.cjs"
+    },
     "./style.css": "./dist/style.css",
     "./theme.css": "./dist/style.css",
     "./theme.scss": "./resources/css/theme.scss"
@@ -29,13 +34,14 @@
   ],
   "scripts": {
     "dev": "vite build --watch",
-    "build": "vite build && node scripts/extract-icon-font.mjs && vue-tsc --declaration --emitDeclarationOnly --outDir dist",
+    "build:lib": "vite build && vite build --config vite.config.charts.ts && node scripts/extract-icon-font.mjs",
+    "build": "npm run build:lib && vue-tsc --declaration --emitDeclarationOnly --outDir dist",
     "typecheck": "vue-tsc --noEmit",
-    "pretest": "vite build",
+    "pretest": "npm run build:lib",
     "test": "vitest",
-    "pretest:ui": "vite build",
+    "pretest:ui": "npm run build:lib",
     "test:ui": "vitest --ui",
-    "pretest:headless": "vite build",
+    "pretest:headless": "npm run build:lib",
     "test:headless": "vitest --run --browser.headless",
     "docs:dev": "astro dev",
     "docs:build": "npm run docs:generate:ai && astro build && node scripts/check-docs-base-links.mjs",

package/resources/css/theme.scss

@@ -436,14 +436,17 @@ $bootstrap-icons-font-src: url("bootstrap-icons/font/fonts/bootstrap-icons.woff2
 
   // Semantic variants: subtle tinted surface, driven through the CSS variable
   // the base `.toast` rule (above, and Bootstrap's own) already reads.
-  @each $name, $color in (
-    "success": $success,
-    "danger": $danger,
-    "warning": $warning,
-    "info": $info
-  ) {
+  //
+  // Sourced from each variant's `soft-bg` in $dx-variants (#143) — the same
+  // vivid-derived soft family badges/alerts use — so the toast hue tracks the
+  // palette and editing a `soft-bg` moves toasts too. Previously these mixed the
+  // dark *emphasis* base colours (greyer success/warning) and danger's saturated
+  // red (a pink, not the soft system's plum). Mixed 50% with white so a large
+  // toast surface stays fainter than a small badge while keeping the hue.
+  @each $name in ("success", "danger", "warning", "info") {
+    $variant: map.get($dx-variants, $name);
     &.toast-#{$name} {
-      --bs-toast-bg: #{color.mix($color, $white, 8%)};
+      --bs-toast-bg: #{color.mix(map.get($variant, "soft-bg"), $white, 50%)};
     }
   }
 }
@@ -581,6 +584,17 @@ $dx-chart-palette: (#2563eb, #65a30d, #7c3aed, #0d9488, #ea580c, #0891b2, #d9770
   }
 }
 
+// The chart container used by DXBarChart/DXLineChart/DXDoughnutChart (shipped
+// from the `@omnitend/dashboard-for-laravel/charts` entry, #142). Global rather
+// than a component scoped style so the charts entry emits NO CSS — chart
+// consumers already import this stylesheet for the theme + palette variables.
+.dx-chart {
+  position: relative;
+  width: 100%;
+  height: 100%;
+  min-height: 240px;
+}
+
 // ----------------------------------------------------------------------------
 // Autocomplete
 // ----------------------------------------------------------------------------

package/resources/js/charts.ts

@@ -0,0 +1,19 @@
+/**
+ * Chart entry point — `@omnitend/dashboard-for-laravel/charts` (#142).
+ *
+ * The chart components are the ONLY ones that need `chart.js` / `vue-chartjs`,
+ * so they live behind this separate subpath entry. The main entry
+ * (`@omnitend/dashboard-for-laravel`) never references the chart libraries, so
+ * they are genuinely OPTIONAL peers: a consumer that renders no charts installs
+ * neither and their build no longer fails resolving them.
+ *
+ *   import { DXBarChart } from '@omnitend/dashboard-for-laravel/charts';
+ *
+ * Chart containers are styled by `.dx-chart` in the main stylesheet
+ * (`@omnitend/dashboard-for-laravel/style.css`), which chart consumers already
+ * import for the theme and the `--dx-chart-*` palette variables — so this entry
+ * ships no CSS of its own.
+ */
+export { default as DXBarChart } from "./components/charts/DXBarChart.vue";
+export { default as DXLineChart } from "./components/charts/DXLineChart.vue";
+export { default as DXDoughnutChart } from "./components/charts/DXDoughnutChart.vue";

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

@@ -2,11 +2,29 @@
 import { BAlert } from "bootstrap-vue-next";
 import { useSlots } from "vue";
 
+/*
+ * bootstrap-vue-next's BAlert defaults `modelValue` to `false`, so a bare static
+ * `<DAlert variant="info">…</DAlert>` silently renders NOTHING — a footgun that
+ * bit our own docs repeatedly (#144). Default it to `true` (visible) at the
+ * wrapper; every call site that already passes `v-model`/`:model-value` is
+ * unaffected — only the bare-static case (which was always a bug) changes.
+ *
+ * Care (see DIVERGENCES.md): declaring `modelValue` as a prop strips it from
+ * `$attrs`, so it is re-bound explicitly below. `emits` is left UNDECLARED so an
+ * `update:modelValue` listener keeps flowing through `$attrs` to BAlert — that's
+ * what lets `v-model` dismissal (and the auto-dismiss countdown) still
+ * round-trip. The type stays `boolean | number` (a number is the auto-dismiss
+ * duration in ms) — don't narrow it.
+ */
+const props = withDefaults(defineProps<{ modelValue?: boolean | number }>(), {
+  modelValue: true,
+});
+
 const slots = useSlots();
 </script>
 
 <template>
-  <BAlert v-bind="$attrs">
+  <BAlert :model-value="props.modelValue" v-bind="$attrs">
     <template v-for="(_, name) in slots" :key="name" #[name]>
       <slot :name="name" />
     </template>

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

@@ -4,10 +4,38 @@
  * Text input with a filtered dropdown of suggestions (typeahead/combobox).
  * Pass `options` and bind `v-model`; supports `multiple` and a custom
  * `filterFunction`.
+ *
+ * `null-option` adds an opt-in, pinned "no selection" row (see below) so a
+ * searchable single-select can always reach "none" in-list (#138).
  */
 <script setup lang="ts">
 import { computed, useAttrs } from "vue";
 import { BAutocomplete } from "bootstrap-vue-next";
+import type { SelectOption } from "bootstrap-vue-next";
+
+// bvn's own `options` prop type — kept identical so this stays a pass-through.
+type AutocompleteOptions = readonly (object | string | number | boolean)[];
+type FilterFunction = (options: SelectOption[], search: string) => SelectOption[];
+
+interface Props {
+  /** Options passed straight through to BAutocomplete (see its `options` prop). */
+  options?: AutocompleteOptions;
+  /**
+   * A custom filter. Composed with `null-option` rather than replaced: when a
+   * null option is present it stays pinned and this runs on the rest.
+   */
+  filterFunction?: FilterFunction;
+  /**
+   * Prepend a pinned, never-filtered, selectable "no selection" row whose value
+   * is `null` (#138). `true` → default label "None"; a string → that label.
+   * Selecting it sets the model to `null` (bvn reads that as no selection, so
+   * the ✕ hides and the placeholder shows). Off by default — unchanged
+   * behaviour. DXTable does NOT use this; it builds its own "All" option.
+   */
+  nullOption?: boolean | string;
+}
+
+const props = defineProps<Props>();
 
 defineOptions({
   inheritAttrs: false,
@@ -15,6 +43,68 @@ defineOptions({
 
 const attrs = useAttrs();
 
+const attr = (name: string, hyphenated: string) =>
+  (attrs as Record<string, unknown>)[name] ?? (attrs as Record<string, unknown>)[hyphenated];
+
+const DEFAULT_NULL_OPTION_LABEL = "None";
+
+/*
+ * The null option is a raw option that bvn will normalise through the SAME
+ * `value-field`/`text-field` the consumer configured (default `value`/`text`).
+ * Build it with those effective field names so it normalises to
+ * `{ value: null, text: label }` — otherwise a consumer using e.g.
+ * `value-field="id" text-field="label"` would normalise our `{ value, text }`
+ * to `{ value: undefined, text: undefined }`, and the row would be filtered out
+ * and select as `undefined` instead of `null` (#138 review).
+ */
+const nullOption = computed<Record<string, unknown> | null>(() => {
+  const raw = props.nullOption;
+  if (raw === false || raw === undefined) return null;
+  const text = typeof raw === "string" ? raw : DEFAULT_NULL_OPTION_LABEL;
+  const valueField = (attr("valueField", "value-field") as string | undefined) ?? "value";
+  const textField = (attr("textField", "text-field") as string | undefined) ?? "text";
+  return { [valueField]: null, [textField]: text };
+});
+
+const consumerOptions = computed<AutocompleteOptions>(() =>
+  Array.isArray(props.options) ? props.options : [],
+);
+
+const computedOptions = computed<AutocompleteOptions>(() => {
+  const pinned = nullOption.value;
+  if (!pinned) return props.options ?? [];
+  return [pinned, ...consumerOptions.value];
+});
+
+const isNullOption = (option: SelectOption) => option?.value === null;
+
+/*
+ * When a null option is present it must stay pinned (top of the list, immune to
+ * the search term); the consumer's `filterFunction` — or bvn's default
+ * substring-on-text match — applies only to the rest, so the two compose rather
+ * than clobber. With no null option we forward the consumer's filter unchanged
+ * (possibly undefined, letting bvn use its own default).
+ */
+const effectiveFilterFunction = computed<FilterFunction | undefined>(() => {
+  const pinned = nullOption.value;
+  const consumerFilter = props.filterFunction;
+  if (!pinned) return consumerFilter;
+
+  return (options, search) => {
+    const rest = options.filter((option) => !isNullOption(option));
+    const filteredRest = consumerFilter
+      ? consumerFilter(rest, search)
+      : search
+        ? rest.filter((option) =>
+            String(option.text ?? "")
+              .toLowerCase()
+              .includes(search.toLowerCase()),
+          )
+        : rest;
+    return [...options.filter(isNullOption), ...filteredRest];
+  };
+});
+
 /*
  * Diverges from bvn: the clear (✕) is hidden when there is nothing to clear.
  *
@@ -28,9 +118,6 @@ const attrs = useAttrs();
  * 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;
@@ -52,7 +139,12 @@ const noClearButton = computed(
     (#53). A plain element root makes it deterministic.
   -->
   <div class="d-autocomplete">
-    <BAutocomplete v-bind="$attrs" :no-clear-button="noClearButton">
+    <BAutocomplete
+      v-bind="$attrs"
+      :options="computedOptions"
+      :filter-function="effectiveFilterFunction"
+      :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" />

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

@@ -0,0 +1,22 @@
+/**
+ * @component
+ * Type-safe wrapper around Bootstrap Vue Next BFormCheckboxGroup component.
+ * Renders a group of checkboxes from an `options` array (or slot content); the
+ * `v-model` is the ARRAY of checked option values ("pick any of N").
+ */
+<script setup lang="ts">
+import { BFormCheckboxGroup } from "bootstrap-vue-next";
+
+defineOptions({
+  inheritAttrs: false,
+});
+</script>
+
+<template>
+  <BFormCheckboxGroup v-bind="$attrs">
+    <!-- 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" />
+    </template>
+  </BFormCheckboxGroup>
+</template>

package/resources/js/components/charts/DXBarChart.vue

@@ -68,12 +68,3 @@ const mergedOptions = computed(() =>
   ),
 );
 </script>
-
-<style scoped>
-.dx-chart {
-  position: relative;
-  width: 100%;
-  height: 100%;
-  min-height: 240px;
-}
-</style>

package/resources/js/components/charts/DXDoughnutChart.vue

@@ -74,12 +74,3 @@ const mergedOptions = computed(() =>
   ),
 );
 </script>
-
-<style scoped>
-.dx-chart {
-  position: relative;
-  width: 100%;
-  height: 100%;
-  min-height: 240px;
-}
-</style>

package/resources/js/components/charts/DXLineChart.vue

@@ -68,12 +68,3 @@ const mergedOptions = computed(() =>
   ),
 );
 </script>
-
-<style scoped>
-.dx-chart {
-  position: relative;
-  width: 100%;
-  height: 100%;
-  min-height: 240px;
-}
-</style>

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

@@ -370,6 +370,17 @@
             v-bind="controlPropsWithGuards"
         />
 
+        <!-- Checkbox group: "pick any of N" — the model is an ARRAY of the
+             checked option values (default the field to []). -->
+        <DFormCheckboxGroup
+            v-else-if="field.type === 'checkbox-group'"
+            v-model="fieldValue"
+            :options="resolvedOptions"
+            :state="fieldState"
+            :disabled="isDisabled || isReadonly || isPlaintext"
+            v-bind="controlPropsWithGuards"
+        />
+
         <!-- File / image upload -->
         <div v-else-if="field.type === 'image' || field.type === 'file'">
             <DFormInput
@@ -554,6 +565,7 @@ import DFormInput from "../base/DFormInput.vue";
 import DFormTextarea from "../base/DFormTextarea.vue";
 import DFormSelect from "../base/DFormSelect.vue";
 import DFormRadioGroup from "../base/DFormRadioGroup.vue";
+import DFormCheckboxGroup from "../base/DFormCheckboxGroup.vue";
 import DFormCheckbox from "../base/DFormCheckbox.vue";
 import DXSwitch from "./DXSwitch.vue";
 import DFormInvalidFeedback from "../base/DFormInvalidFeedback.vue";

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

@@ -36,8 +36,8 @@
              `.card-body` wrapper — DTabs already provides `.card-header`/
              `.card-body` internally via its own `card` prop, so wrapping
              that in another `.card-body` would double up. -->
-        <component :is="card ? DCard : 'div'" v-if="hasTabs" v-bind="card ? { noBody: true } : {}">
-            <DTabs v-model:index="activeTab" :card="card">
+        <component :is="tabsInCard ? DCard : 'div'" v-if="hasTabs" v-bind="tabsInCard ? { noBody: true } : {}">
+            <DTabs v-model:index="activeTab" :card="tabsInCard">
                 <DTab
                     v-for="(tab, index) in visibleTabs"
                     :key="tab.key"
@@ -213,12 +213,23 @@ interface Props {
 
     /**
      * Wrap the form in a card for a visual boundary (mirrors DXTable's
-     * `card` prop). Tabbed forms render the tab nav as a BS5
-     * card-header-tabs instead of double-wrapping. Off by default since
-     * DXForm is commonly embedded in a page card or modal already.
+     * `card` prop). Off by default since DXForm is commonly embedded in a
+     * page card or modal already. Tabbed forms are wrapped by default
+     * regardless — see `cardTabs`; setting `card` also forces the tabbed
+     * card on even when `cardTabs` is disabled.
      */
     card?: boolean;
 
+    /**
+     * Wrap a TABBED form's content in a card panel so the active tab reads
+     * as a finished panel connected to the tab strip (the standard
+     * Bootstrap card-with-tabs pattern) rather than floating on the bare
+     * page background (#159). On by default. Set `false` for bare tabs
+     * (e.g. inside a modal that already provides a boundary). Ignored for
+     * flat (non-tabbed) forms — use `card` for those.
+     */
+    cardTabs?: boolean;
+
     /**
      * Form-wide field layout: "vertical" (default, label above input) or
      * "horizontal" (label left, input right). Overridable per-field via
@@ -241,6 +252,7 @@ const props = withDefaults(defineProps<Props>(), {
     showSubmit: true,
     autoErrorTab: true,
     card: false,
+    cardTabs: true,
     layout: "vertical",
 });
 
@@ -318,6 +330,14 @@ const hasTabs = computed(
     () => !!props.tabs && props.tabs.length > 0,
 );
 
+// Tabbed forms render inside a card panel by default (#159) so the tab
+// content reads as a finished panel rather than floating on the page.
+// `cardTabs` is the tabbed-only toggle (on by default); `card` (which also
+// wraps flat forms) still forces it on. Flat forms are unaffected.
+const tabsInCard = computed(
+    () => hasTabs.value && (props.card || props.cardTabs),
+);
+
 function visibleFieldsFor(tab: FormTab): FieldDefinition[] {
     return tab.fieldKeys
         .map((key) => fieldByKey.value[key])