@omnitend/dashboard-for-laravel 0.34.0 → 0.36.0

package/docs/public/api-reference.json

@@ -1,8 +1,8 @@
 {
-  "generated": "2026-07-21T07:46:13.035Z",
+  "generated": "2026-07-21T12:50:16.789Z",
   "package": {
     "name": "@omnitend/dashboard-for-laravel",
-    "version": "0.34.0"
+    "version": "0.36.0"
   },
   "components": {
     "base": [
@@ -2427,7 +2427,14 @@
             "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."
+            "description": "Form-wide field layout:\n\n- `\"vertical\"` (default) — label above input, always.\n- `\"horizontal\"` — label left, input right, always.\n- `\"auto\"` — horizontal when the form's **own container** is at least\n  `layoutThreshold` px wide, vertical below that. Container-driven, not\n  viewport-driven: a page narrowed by the dashboard sidebar, or a form\n  inside a modal, stacks even though the window is wide (which no\n  Bootstrap media query can see).\n\nOverridable per-field via `field.layout`. A field with `span: true`\nalways renders full-width, regardless of layout."
+          },
+          {
+            "name": "layoutThreshold",
+            "type": "number",
+            "required": false,
+            "default": "640",
+            "description": "Container width (px) at or above which `layout: \"auto\"` goes horizontal.\nIgnored for the explicit `\"vertical\"`/`\"horizontal\"` layouts.\n\nDefault 640, measured rather than guessed: with the default 3-column\nlabel the label's text area is `containerWidth / 4 - 18` px, so 640 gives\nit 142px — enough for a ~20-character label (\"Unit price (ex VAT)\"\nmeasures 128px at the theme's label font) to stay on one line, with the\ncontrol column still 474px. Below ~584px that label starts wrapping,\nwhich is the cramped-label symptom this exists to avoid. Raise it if your\nlabels run longer, or lower `labelCols` instead."
           },
           {
             "name": "labelCols",
@@ -3314,7 +3321,7 @@
             "type": "boolean",
             "required": false,
             "default": "true",
-            "description": "Wrap the table in a `DCard`. Defaults to `true`. Set `false` for a plain,\nborderless variant — the same header, filter row, table and pagination\nrendered directly on the page background (no card border/shadow), for\ndata-heavy admin index pages that read as busy inside a card."
+            "description": "Wrap the table in a `DCard`. Defaults to `true`. Set `false` for a plain,\nborderless variant — the same header, filter row, table and pagination\nrendered directly on the page background (no card border/shadow), for\ndata-heavy admin index pages that read as busy inside a card.\n\nThe table renders FLUSH to the card border (rows and stripes reach the\nedge) while the header and pagination stay padded. Only the table region\nis rounded to follow the card's corners — the card itself does not clip\n(#166), so a `position: absolute` popover you render into `#header` or\nany other slot is free to overhang the card.\n\nThe one place content is still clipped is INSIDE the table: Bootstrap's\n`.table-responsive` is a horizontal scroll container, so an overlay in a\n`cell(<key>)` slot is bounded by it. Teleport it (bvn's own menus already\ndo — `DDropdown` teleports to `<body>`, the column-filter menus are\n`fixed`), or pass `:responsive=\"false\"`."
           },
           {
             "name": "editFields",
@@ -3346,7 +3353,7 @@
             "type": "union",
             "required": false,
             "default": "\"horizontal\"",
-            "description": "Field layout for the edit/create modal's form, forwarded to its `DXForm`\n(\"vertical\" = label above input, \"horizontal\" = label left). Defaults to\n**\"horizontal\"** to match the Omni Tend form convention (a raw modal form\npreviously fell back to DXForm's vertical default, which looked out of\nplace next to horizontal page forms). Pass `\"vertical\"` to opt out."
+            "description": "Field layout for the edit/create modal's form, forwarded to its `DXForm`\n(\"vertical\" = label above input, \"horizontal\" = label left). Defaults to\n**\"horizontal\"** to match the Omni Tend form convention (a raw modal form\npreviously fell back to DXForm's vertical default, which looked out of\nplace next to horizontal page forms). Pass `\"vertical\"` to opt out.\n\n`\"auto\"` hands the decision to `DXForm`'s container-width observer, which\nmeasures the FORM rather than the window — so a modal narrowed by its own\nbreakpoint stacks to vertical even on a wide viewport, where a media query\nwould still report \"plenty of room\". See `useContainerWidth`."
           },
           {
             "name": "editLabelCols",
@@ -3578,6 +3585,32 @@
               }
             ]
           },
+          {
+            "name": "`head-end(${field.key})`",
+            "description": "head-end(<fieldKey>) Additive content at the end of a column's own header — a period total above a numeric column, a small badge — keeping DXTable's sort indicator and field hint. Not a `head()` override.",
+            "bindings": [
+              {
+                "name": "name",
+                "title": "binding"
+              },
+              {
+                "title": "binding",
+                "type": {
+                  "name": "object"
+                },
+                "name": "field",
+                "description": "The column's field definition."
+              },
+              {
+                "title": "binding",
+                "type": {
+                  "name": "string"
+                },
+                "name": "label",
+                "description": "The column's resolved header label."
+              }
+            ]
+          },
           {
             "name": "name",
             "description": "Any slot the underlying table supports, forwarded with its scope: `cell(<fieldKey>)` for a cell, `foot(<fieldKey>)` for a footer cell (needs `footClone`), `empty` for the no-rows message, `row-expansion` for expandable row detail, plus `custom-foot`, `top-row`, `bottom-row`, `thead-sub` and the `table-*` slots.",
@@ -3679,7 +3712,7 @@
             "name": "layout",
             "type": "union",
             "required": false,
-            "description": "Field layout forwarded to the modal's DXForm (defaults handled upstream)."
+            "description": "Field layout forwarded to the modal's DXForm (defaults handled upstream).\nIncludes `\"auto\"`, which lets the form stack to vertical when the MODAL is\nnarrow even though the viewport is wide — the container-query case a\nviewport media query cannot see."
           },
           {
             "name": "labelCols",
@@ -3915,7 +3948,7 @@
         "name": "DXTablePagination",
         "category": "extended",
         "filePath": "resources/js/components/extended/DXTablePagination.vue",
-        "description": "Internal pagination + per-page footer for `DXTable`. Renders the pager, the per-page selector, and the \"X to Y out of Z items\" info line (with the \"Filtered from N\" note when a column filter is active). Extracted because `DXTable` used to carry three byte-identical copies of this footer — one per data mode (client-side / inertia / provider) — that differed only in which `PaginationData` object and page-change handler they used, so every footer fix had to be written three times (#123). `DXTable` now derives the active pagination + handler and renders this once. It owns its own `:deep(.pagination …)` styling (rather than leaving it in `DXTable`), because a scoped `:deep()` in `DXTable` would not reach the pager once it lives in a child component — the scope-id doesn't cross the boundary. Anchoring the rules on this component's own `.dx-table-pagination` root (a plain element it owns) gives the scope-id a deterministic host.",
+        "description": "Internal pagination + per-page footer for `DXTable`. Renders the pager, the per-page selector, and the \"X to Y out of Z items\" info line (with the \"Filtered from N\" note when a column filter is active). Extracted because `DXTable` used to carry three byte-identical copies of this footer — one per data mode (client-side / inertia / provider) — that differed only in which `PaginationData` object and page-change handler they used, so every footer fix had to be written three times (#123). `DXTable` now derives the active pagination + handler and renders this once. It owns its own `:deep(.pagination …)` styling (rather than leaving it in `DXTable`), because a scoped `:deep()` in `DXTable` would not reach the pager once it lives in a child component — the scope-id doesn't cross the boundary. Anchoring the rules on this component's own `.dx-table-pagination` root (a plain element it owns) gives the scope-id a deterministic host. In a row too narrow for the full windowed pager, the number strip collapses to a \"current / last\" status with Previous/Next either side (#162). The decision is CONTAINER-driven, not viewport-driven — see `compactThreshold`.",
         "props": [
           {
             "name": "pagination",
@@ -3970,6 +4003,13 @@
             "type": "boolean",
             "required": true,
             "description": "Whether a column filter is active — gates the \"Filtered from N\" note."
+          },
+          {
+            "name": "compactThreshold",
+            "type": "number",
+            "required": false,
+            "default": "576",
+            "description": "Upper bound (px) on the pager ROW width at which the number window may\ncollapse to the compact \"current / last\" status (#162). At or above it\nthe full windowed pager always renders, whatever the page count.\n\nDefault **576** — Bootstrap's `sm` breakpoint, i.e. the width the rest of\nthe design system already treats as phone-sized. Its job is to GUARANTEE\nthat a desktop-width table is never quietly downgraded: a 45-page window\nthat doesn't quite fit at 800px should wrap (today's behaviour), not lose\nits numbers.\n\nBelow it, compact engages only when the full pager genuinely would not\nfit on one line (see `fullPagerWidth`) — so a three-page pager still\nshows `1 2 3` on a phone, where \"2 / 3\" would be strictly worse.\n\nMeasured on the ROW, not the viewport, so a table squeezed by a sidebar\nor inside a modal collapses even though the window is wide."
           }
         ],
         "events": [
@@ -3991,7 +4031,7 @@
         "name": "DXTableShell",
         "category": "extended",
         "filePath": "resources/js/components/extended/DXTableShell.vue",
-        "description": "Internal chrome wrapper for `DXTable`. Renders its content either inside a `DCard` (the default) or as a plain, borderless block on the page background (`:card=\"false\"`). Extracted so `DXTable`'s ~460-line body and all its slots aren't duplicated across a card/plain `v-if`. Slots: - `#header` — the title / action row. In card mode it fills `DCard`'s header; in plain mode it renders above the table with a subtle bottom rule. - default — the table body (spinner/error/table/pagination).",
+        "description": "Internal chrome wrapper for `DXTable`. Renders its content either inside a `DCard` (the default) or as a plain, borderless block on the page background (`:card=\"false\"`). Extracted so `DXTable`'s ~460-line body and all its slots aren't duplicated across a card/plain `v-if`. Slots: - `#header` — the title / action row. In card mode it fills `DCard`'s header; in plain mode it renders above the table with a subtle bottom rule. - default — the table body (spinner/error/table/pagination). Card mode renders `DCard` in **`no-body`** mode so the table sits FLUSH against the card border. With a `.card-body` in between, a striped table's rows were inset by `--bs-card-spacer-x` (24px) and left a white gutter between the stripes and the border. Without it, DXTable's children — error alert, loading block, table, pagination — become direct children of `.card`, which is already a `flex-direction: column` container, so they still stack in order: .card ├─ .card-header (padded by Bootstrap's card-cap padding) ├─ .table-responsive ← FLUSH, rounded when it is at a card corner │ └─ table └─ .dx-table-pagination (pads itself — see DXTablePagination.vue) Bootstrap 5 has no `.card > .table` rounding rules (that was BS4), so the flush table's square corners have to be rounded here. The rounding is applied to the TABLE REGION, never to the card: clipping the whole card would cut off any non-teleported positioned content a consumer puts in a slot (#166).",
         "props": [
           {
             "name": "card",

package/docs/public/docs-map.md

@@ -1,7 +1,7 @@
 # Documentation Map
 
 > Auto-generated hierarchical overview of all documentation
-> Last updated: 2026-07-21T07:46:13.078Z
+> Last updated: 2026-07-21T12:50:16.844Z
 
 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.34.0",
+  "version": "0.36.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

@@ -313,6 +313,32 @@ $bootstrap-icons-font-src: url("bootstrap-icons/font/fonts/bootstrap-icons.woff2
   flex-wrap: nowrap;
 }
 
+// ----------------------------------------------------------------------------
+// Nav tabs
+// ----------------------------------------------------------------------------
+// Chrome recedes, content leads — the same ethos as the muted table headers
+// (#157). Bootstrap gives an INACTIVE tab `--bs-nav-link-color:
+// var(--bs-link-color)`, i.e. the saturated link-blue, so a row of tabs above a
+// form reads as a row of links competing with the fields below. Mute the
+// inactive tabs and let the ACTIVE one (Bootstrap's
+// `--bs-nav-tabs-link-active-color`, the near-black emphasis colour) carry the
+// selection on its own.
+//
+// Driven through Bootstrap's own `--bs-nav-*` variables rather than a raw
+// `color:` — so a consumer can re-louden one tab set by resetting the same
+// variable, `[data-bs-theme="dark"]` remaps the tokens for free, and Bootstrap
+// keeps ownership of the `.active`/`.disabled` resolution order.
+//
+// `--bs-secondary-color` is `rgba(var(--bs-body-color-rgb), .75)` → ~#585b5e on
+// white: 6.83:1, comfortably AA (AAA for body text); 6.53:1 on the theme's
+// `$light` #f8fafc panel. Hover goes to the full body colour (#212529, 16.1:1)
+// so hovering reads as "heading toward selected" rather than "turning into a
+// link".
+.nav-tabs {
+  --bs-nav-link-color: var(--bs-secondary-color);
+  --bs-nav-link-hover-color: var(--bs-body-color);
+}
+
 // ----------------------------------------------------------------------------
 // Dashboard Custom Styles
 // ----------------------------------------------------------------------------
@@ -433,6 +459,40 @@ $bootstrap-icons-font-src: url("bootstrap-icons/font/fonts/bootstrap-icons.woff2
     color: $secondary; // muted message text
   }
 
+  // HEADER-LESS toast (`body` but no `title` — the shape every toast created
+  // through `useToast().create({ body })` takes). BVN renders it as
+  //   .toast > .d-flex > (.toast-body + .btn-close)
+  // and BVN's own `.toast .btn-close-custom { margin: <pad> <pad> auto }` pins
+  // the close X to the TOP of that row, while the `.toast-body` above still
+  // carries the reduced `padding-top` that only makes sense when it sits under
+  // a `.toast-header`. Result: the message rides high, the X sits lower, and a
+  // one-line toast reads as misaligned.
+  //
+  // With no header there is nothing above the body, so restore symmetric
+  // padding (Bootstrap's `.toast-body` is `padding: var(--bs-toast-padding-x)`
+  // all round) and centre the row. The `margin-bottom: auto` has to go too —
+  // an auto margin outranks `align-items` in flex alignment, so centring alone
+  // would leave the X pinned; `margin-block: 0` hands alignment back to the
+  // container while keeping BVN's horizontal margin.
+  //
+  // `:has()` is the structural test — it is the only way to key off "this toast
+  // has no header" from CSS, and it is supported in every evergreen browser
+  // (Chrome/Edge 105+, Safari 15.4+, Firefox 121+). A browser without it simply
+  // keeps today's slightly-off alignment; nothing breaks.
+  &:not(:has(.toast-header)) {
+    > .d-flex {
+      align-items: center;
+    }
+
+    .toast-body {
+      padding-top: var(--bs-toast-padding-x);
+    }
+
+    .btn-close-custom {
+      margin-block: 0;
+    }
+  }
+
   // Hide the auto-dismiss countdown bar — the ticking animation reads as
   // stressful/urgent, which is wrong for a passive notification. Auto-dismiss
   // still works; only its visual indicator is removed.
@@ -530,7 +590,18 @@ $bootstrap-icons-font-src: url("bootstrap-icons/font/fonts/bootstrap-icons.woff2
   // (which sets its colours `!important` by design). `.toast` is excluded: it
   // has its own soft handling (a fainter 50%-white mix via `--bs-toast-bg` for
   // its large surface) and themed toasts don't carry `.text-bg-*` anyway.
-  .text-bg-#{$name}:not(.toast) {
+  //
+  // The exclusion is wrapped in `:where()` DELIBERATELY: `:where()` always
+  // contributes ZERO specificity, so this stays a single-class 0,1,0 selector
+  // while matching exactly what a bare `:not(.toast)` would. Written bare it is
+  // 0,2,0 — and because the declarations are `!important`, a consumer painting
+  // a fully custom badge (`.my-status-badge { background: …; }`) could not win
+  // with a single-class `!important` rule and had to escalate to a
+  // repeated-class hack. One class in, one class out: a consumer's own
+  // `!important` single-class rule now overrides us on source order, as it
+  // should. (Everything Bootstrap defines for `.text-bg-*` is also 0,1,0
+  // `!important` and is imported ABOVE this block, so we still win it.)
+  .text-bg-#{$name}:where(:not(.toast)) {
     background-color: #{$soft-bg} !important;
     color: #{$soft-text} !important;
   }
@@ -551,7 +622,14 @@ $bootstrap-icons-font-src: url("bootstrap-icons/font/fonts/bootstrap-icons.woff2
   // (danger/info's solid IS their emphasis). The variant-less default bar
   // stays `$progress-bar-bg` (brand navy). `!important` beats the `.bg-*`
   // utility, which sets its colour `!important` by design.
-  .progress-bar.bg-#{$name} {
+  //
+  // `.progress-bar` is only here to SCOPE the rule (large fills, not every
+  // `.bg-*` element), so it goes in `:where()` — zero specificity, same
+  // matching, and the selector stays 0,1,0 like Bootstrap's own `.bg-*`. Same
+  // reasoning as the `.text-bg-*` rule above: at 0,2,0 `!important` a consumer
+  // recolouring one bar had to out-specify us instead of just writing
+  // `.my-bar { background-color: … !important }`.
+  :where(.progress-bar).bg-#{$name} {
     background-color: #{$solid-bg} !important;
     color: #{$solid-text};
   }
@@ -716,8 +794,10 @@ $dx-chart-palette: (#2563eb, #65a30d, #7c3aed, #0d9488, #ea580c, #0891b2, #d9770
 // same method as the light set (OKLab ΔE ×100, Viénot protan/deutan): min
 // adjacent CVD ΔE 15.1 (light set: 13.8), min normal ΔE 25.3, contrast
 // 5.67–10.23:1 on #212529. Swapping a step needs that validation re-run.
-// getPalette() reads the CSS variables live, so charts follow the theme with
-// no JS change; the TS fallbacks stay the light set (SSR/no-CSS default).
+// getPalette() reads these CSS variables live — off the CHART'S OWN container,
+// so nested colour-mode scopes resolve correctly, and re-read on every
+// `data-bs-theme` change so mounted charts repaint (#161). The TS fallbacks
+// stay the light set (SSR/no-CSS default).
 $dx-chart-palette-dark: (#60a5fa, #a3e635, #a78bfa, #2dd4bf, #fb923c, #22d3ee, #fbbf24, #f472b6);
 
 :root {
@@ -732,6 +812,18 @@ $dx-chart-palette-dark: (#60a5fa, #a3e635, #a78bfa, #2dd4bf, #fb923c, #22d3ee, #
   }
 }
 
+// Bootstrap allows `data-bs-theme` on ANY container, so colour-mode scopes
+// nest — and custom properties inherit. Without this re-declaration a LIGHT
+// scope inside a dark root (a light card on a dark page) would inherit the dark
+// palette, because only `:root` publishes the light values and the dark block
+// above overrides it for the whole subtree (#161). Same list as `:root`, so the
+// two can't drift.
+[data-bs-theme="light"] {
+  @for $i from 1 through list.length($dx-chart-palette) {
+    --dx-chart-#{$i}: #{list.nth($dx-chart-palette, $i)};
+  }
+}
+
 // 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

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

@@ -8,12 +8,13 @@
   Requires the optional peer deps `chart.js` and `vue-chartjs`.
 -->
 <template>
-  <div class="dx-chart">
+  <div ref="host" class="dx-chart">
     <Bar :data="chartData" :options="mergedOptions" />
   </div>
 </template>
 
 <script setup lang="ts">
+import { ref } from "vue";
 import { Bar } from "vue-chartjs";
 import { registerCharts } from "./chartTheme";
 import { useThemedChart, type ThemedChartProps } from "./useThemedChart";
@@ -27,5 +28,9 @@ const props = withDefaults(defineProps<ThemedChartProps<"bar">>(), {
   showLegend: undefined,
 });
 
-const { chartData, mergedOptions } = useThemedChart("bar", props);
+// The container is the `data-bs-theme` scope the palette resolves against, so a
+// chart inside a dark card on a light page themes from the card (#161).
+const host = ref<HTMLElement | null>(null);
+
+const { chartData, mergedOptions } = useThemedChart("bar", props, host);
 </script>

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

@@ -8,19 +8,20 @@
   Requires the optional peer deps `chart.js` and `vue-chartjs`.
 -->
 <template>
-  <div class="dx-chart">
+  <div ref="host" class="dx-chart">
     <Doughnut :data="chartData" :options="mergedOptions" />
   </div>
 </template>
 
 <script setup lang="ts">
-import { computed } from "vue";
+import { computed, ref } from "vue";
 import { Doughnut } from "vue-chartjs";
 import {
   registerCharts,
   baseOptions,
   applyPalette,
   mergeOptions,
+  useColorModeVersion,
   type ChartValueFormat,
 } from "./chartTheme";
 
@@ -52,25 +53,47 @@ const props = withDefaults(defineProps<Props>(), {
   showLegend: undefined,
 });
 
+// The container is the `data-bs-theme` scope the palette resolves against, so a
+// chart inside a dark card on a light page themes from the card. Reading the ref
+// inside the computeds also re-themes on mount, when the first (pre-ref) render
+// had to fall back to the document root (#161). DXDoughnutChart doesn't share
+// `useThemedChart` (its data shape differs), so the wiring is repeated here.
+const host = ref<HTMLElement | null>(null);
+
+// Bumped by a MutationObserver on every `data-bs-theme` change; read below so
+// the CSS-variable palette — invisible to Vue's reactivity — is re-resolved
+// when the colour mode flips under a mounted chart.
+const colorModeVersion = useColorModeVersion();
+
 const resolvedDatasets = computed(() =>
   props.datasets ?? [{ data: props.data ?? [] }],
 );
 
-const chartData = computed(() => ({
-  labels: props.labels,
-  datasets: applyPalette(resolvedDatasets.value, "doughnut", props.labels.length),
-}));
+const chartData = computed(() => {
+  void colorModeVersion.value;
+  return {
+    labels: props.labels,
+    datasets: applyPalette(
+      resolvedDatasets.value,
+      "doughnut",
+      props.labels.length,
+      host.value,
+    ),
+  };
+});
 
-const mergedOptions = computed(() =>
-  mergeOptions(
+const mergedOptions = computed(() => {
+  void colorModeVersion.value;
+  return mergeOptions(
     baseOptions({
       valueFormat: props.valueFormat,
       currencySymbol: props.currencySymbol,
       locale: props.locale,
       showLegend: props.showLegend ?? true,
       hasValueAxis: false,
+      scope: host.value,
     }),
     props.options ?? {},
-  ),
-);
+  );
+});
 </script>

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

@@ -8,12 +8,13 @@
   Requires the optional peer deps `chart.js` and `vue-chartjs`.
 -->
 <template>
-  <div class="dx-chart">
+  <div ref="host" class="dx-chart">
     <Line :data="chartData" :options="mergedOptions" />
   </div>
 </template>
 
 <script setup lang="ts">
+import { ref } from "vue";
 import { Line } from "vue-chartjs";
 import { registerCharts } from "./chartTheme";
 import { useThemedChart, type ThemedChartProps } from "./useThemedChart";
@@ -27,5 +28,9 @@ const props = withDefaults(defineProps<ThemedChartProps<"line">>(), {
   showLegend: undefined,
 });
 
-const { chartData, mergedOptions } = useThemedChart("line", props);
+// The container is the `data-bs-theme` scope the palette resolves against, so a
+// chart inside a dark card on a light page themes from the card (#161).
+const host = ref<HTMLElement | null>(null);
+
+const { chartData, mergedOptions } = useThemedChart("line", props, host);
 </script>

package/resources/js/components/charts/chartTheme.ts

@@ -5,6 +5,7 @@
  * registration. chart.js / vue-chartjs are OPTIONAL peer deps.
  */
 import { Chart, registerables } from "chart.js";
+import { getCurrentScope, onScopeDispose, ref, type Ref } from "vue";
 
 export type ChartValueFormat = "number" | "currency" | "percent";
 
@@ -59,12 +60,37 @@ export const PALETTE_VARS: Array<[string, string]> = [
     ["--dx-chart-8", "#db2777"], // pink
 ];
 
-/** Resolve the themed categorical palette from the document root. */
-export function getPalette(): string[] {
+/**
+ * The element whose computed style the theme variables are read from.
+ *
+ * Bootstrap 5.3 allows `data-bs-theme` on ANY container, not just `<html>` — a
+ * dark card on a light page is a supported pattern. Reading the variables off
+ * `document.documentElement` therefore gives a *nested* scope the wrong palette
+ * (#161), so every resolver takes the chart's own container and only falls back
+ * to the root when it has none (SSR, a caller outside a component).
+ */
+function themeScope(scope?: Element | null): Element | null {
     if (typeof document === "undefined" || typeof getComputedStyle === "undefined") {
+        return null;
+    }
+    if (scope !== undefined && scope !== null) return scope;
+    return document.documentElement;
+}
+
+/**
+ * Resolve the themed categorical palette.
+ *
+ * @param scope The chart's container element; its computed style decides which
+ *   `data-bs-theme` scope applies. Omit (or pass null) to read the document
+ *   root — the pre-#161 behaviour, kept so the exported signature stays
+ *   backward compatible.
+ */
+export function getPalette(scope?: Element | null): string[] {
+    const host = themeScope(scope);
+    if (host === null) {
         return PALETTE_VARS.map(([, fallback]) => fallback);
     }
-    const styles = getComputedStyle(document.documentElement);
+    const styles = getComputedStyle(host);
     return PALETTE_VARS.map(([name, fallback]) => {
         const value = styles.getPropertyValue(name).trim();
         return value || fallback;
@@ -72,16 +98,73 @@ export function getPalette(): string[] {
 }
 
 /** Read a single theme colour (e.g. the body text colour) with a fallback. */
-function themeColor(name: string, fallback: string): string {
-    if (typeof document === "undefined" || typeof getComputedStyle === "undefined") {
+function themeColor(name: string, fallback: string, scope?: Element | null): string {
+    const host = themeScope(scope);
+    if (host === null) {
         return fallback;
     }
-    const value = getComputedStyle(document.documentElement)
-        .getPropertyValue(name)
-        .trim();
+    const value = getComputedStyle(host).getPropertyValue(name).trim();
     return value || fallback;
 }
 
+// ---------------------------------------------------------------------------
+// Colour-mode reactivity (#161)
+//
+// The palette lives in CSS variables, which Vue cannot track: a computed that
+// calls getPalette() depends only on the props it also reads, so flipping
+// `data-bs-theme` repaints the page but leaves every MOUNTED chart on the old
+// palette until a prop changes or it remounts. One shared MutationObserver
+// bumps a version ref that the chart computeds read, which re-resolves the
+// variables. `subtree: true` because the attribute can sit on any container,
+// and `attributeFilter` keeps the observer from firing on unrelated mutations.
+// ---------------------------------------------------------------------------
+
+const colorModeVersion = ref(0);
+let colorModeObserver: MutationObserver | null = null;
+let colorModeWatchers = 0;
+
+/**
+ * A version ref that increments whenever a `data-bs-theme` attribute changes
+ * anywhere in the document. Read it inside a computed that resolves theme
+ * variables to make that computed re-run on a colour-mode switch.
+ *
+ * The observer is started on first use and disconnected when the last consumer's
+ * effect scope is disposed, so nothing leaks after the charts unmount. Called
+ * outside an effect scope (or without a DOM) it is a no-op returning a static
+ * ref — there would be no teardown hook to disconnect the observer.
+ */
+export function useColorModeVersion(): Ref<number> {
+    if (
+        typeof document === "undefined" ||
+        typeof MutationObserver === "undefined" ||
+        getCurrentScope() === undefined
+    ) {
+        return colorModeVersion;
+    }
+
+    colorModeWatchers += 1;
+    if (colorModeObserver === null) {
+        colorModeObserver = new MutationObserver(() => {
+            colorModeVersion.value += 1;
+        });
+        colorModeObserver.observe(document.documentElement, {
+            attributes: true,
+            attributeFilter: ["data-bs-theme"],
+            subtree: true,
+        });
+    }
+
+    onScopeDispose(() => {
+        colorModeWatchers -= 1;
+        if (colorModeWatchers === 0 && colorModeObserver !== null) {
+            colorModeObserver.disconnect();
+            colorModeObserver = null;
+        }
+    });
+
+    return colorModeVersion;
+}
+
 /** Add an alpha channel to a hex or rgb() colour (best-effort). */
 export function withAlpha(color: string, alpha: number): string {
     const hex = color.replace(/^#/, "");
@@ -122,6 +205,9 @@ export interface BaseOptionArgs {
     showLegend?: boolean;
     /** Whether the chart has value axes (bar/line) vs none (doughnut). */
     hasValueAxis?: boolean;
+    /** The chart's container element — decides which `data-bs-theme` scope the
+     *  grid/tick colours resolve against (#161). Defaults to the document root. */
+    scope?: Element | null;
 }
 
 /** Dashboard default Chart.js options merged under any consumer `options`. */
@@ -132,10 +218,14 @@ export function baseOptions(args: BaseOptionArgs): Record<string, any> {
         locale,
         showLegend = false,
         hasValueAxis = true,
+        scope,
     } = args;
 
-    const gridColor = withAlpha(themeColor("--bs-border-color", "#dee2e6"), 0.6);
-    const tickColor = themeColor("--bs-secondary-color", "#6c757d");
+    const gridColor = withAlpha(
+        themeColor("--bs-border-color", "#dee2e6", scope),
+        0.6,
+    );
+    const tickColor = themeColor("--bs-secondary-color", "#6c757d", scope);
 
     const options: Record<string, any> = {
         responsive: true,
@@ -185,13 +275,18 @@ export function baseOptions(args: BaseOptionArgs): Record<string, any> {
  * Apply the themed palette to any dataset that doesn't set its own colours.
  * Bar: one colour per dataset (or per bar for a single dataset). Line: a themed
  * stroke + translucent fill. Doughnut/pie: one colour per slice.
+ *
+ * `scope` is the chart's container element; the palette is resolved from its
+ * computed style so a nested `data-bs-theme` container themes correctly (#161).
+ * Omit it to resolve against the document root.
  */
 export function applyPalette(
     datasets: any[],
     kind: "bar" | "line" | "doughnut",
     labelsCount: number,
+    scope?: Element | null,
 ): any[] {
-    const palette = getPalette();
+    const palette = getPalette(scope);
     const single = datasets.length === 1;
 
     return datasets.map((dataset, index) => {