@omnitend/dashboard-for-laravel 0.35.0 → 0.37.0

package/docs/public/api-reference.json

@@ -1,8 +1,8 @@
 {
-  "generated": "2026-07-21T12:16:47.073Z",
+  "generated": "2026-07-23T11:32:06.998Z",
   "package": {
     "name": "@omnitend/dashboard-for-laravel",
-    "version": "0.35.0"
+    "version": "0.37.0"
   },
   "components": {
     "base": [
@@ -211,8 +211,8 @@
             "name": "variant",
             "type": "union",
             "required": false,
-            "default": "\"primary\"",
-            "description": "The visual style variant of the button"
+            "default": "\"secondary\"",
+            "description": "The visual style variant of the button.\n\nDefaults to `'secondary'` (soft, non-emphatic). Under the soft-first\nhouse rule, `primary` is THE single emphatic action per page/modal, so a\nvariant-less button must NOT be emphatic by default — declare\n`variant=\"primary\"` explicitly where you mean the one loud action."
           },
           {
             "name": "size",
@@ -3321,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.\n\nThe table renders FLUSH to the card border (rows and stripes reach the\nedge) while the header and pagination stay padded, which requires the card\nto clip to its radius (`overflow: hidden`).\n\n**Consequence for slot content:** anything you render into a slot that\npositions itself OUTSIDE the card and does not teleport is clipped at the\ncard edge. Library components are unaffected — `DDropdown` teleports to\n`<body>` by default, and the column-filter menus position themselves\n`fixed` — so this only bites a hand-rolled `position: absolute` overlay\n(a custom popover in a `cell(<key>)` or `#header` slot). Teleport it, or\nuse `:card=\"false\"`. Narrowing the clip to the table region is tracked\nas #166."
+            "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",
@@ -3473,6 +3473,12 @@
             "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."
+          },
+          {
+            "name": "primaryKey",
+            "type": "string",
+            "required": false,
+            "description": "Field on each row whose value uniquely identifies it, forwarded to the\ninner bvn table's `primaryKey` (all three data modes). Without it bvn keys\nclient-side rows by their INDEX, which mis-associates per-row STATEFUL cell\ncomponents when a row is inserted/removed mid-interaction — a debounced\nedit in one row can end up saved against the wrong record after a\nconcurrent delete of a row above. Set it (e.g. `primary-key=\"id\"`) so bvn\nkeys rows by that field's value and each row keeps its identity across\ndata mutations. Non-breaking: omit it and rows key by index exactly as\nbefore."
           }
         ],
         "events": [
@@ -3948,7 +3954,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",
@@ -4003,6 +4009,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": [
@@ -4024,7 +4037,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). 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 (overflow: hidden) ├─ .card-header (padded by Bootstrap's card-cap padding) ├─ .table-responsive ← FLUSH │ └─ table └─ .dx-table-pagination (pads itself — see DXTablePagination.vue) Bootstrap 5 has no `.card > .table` rounding rules (that was BS4), so the clipping is done with `overflow: hidden` on the card: the flush table's square top corners then follow the card's radius whether or not a header is present. bvn's popups position `fixed` by default, so they are not clipped by it.",
+        "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-21T12:16:47.128Z
+> Last updated: 2026-07-23T11:32:07.049Z
 
 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.35.0",
+  "version": "0.37.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

@@ -98,6 +98,18 @@ $btn-padding-x-lg: 1.5rem; // 24px
 
 $input-padding-y: 0.375rem; // compact fields (Bootstrap's default; 0.625rem read oversized)
 $input-padding-x: 1rem;
+
+// Match the sm/lg INPUT vertical padding to the sm/lg BUTTON padding above
+// (PO18). Bootstrap sizes every child of an `.input-group-sm`/`-lg` — buttons
+// INCLUDED — with the INPUT's sized padding, so leaving these at Bootstrap's
+// defaults (0.25rem / 0.5rem) made a sized input-group sit ~8px / ~4px shorter
+// than a `.btn-sm`/`.btn-lg` beside it. Aligning them makes sized controls share
+// one height by construction. NB: the BASE `$input-padding-y` (0.375rem) stays
+// deliberately more compact than `$btn-padding-y` (0.625rem) — see the comment
+// above ("0.625rem read oversized"); only the SIZED variants are equalised,
+// because those are the ones whose padding Bootstrap leaks onto grouped buttons.
+$input-padding-y-sm: 0.5rem; // == $btn-padding-y-sm (was Bootstrap's 0.25rem)
+$input-padding-y-lg: 0.75rem; // == $btn-padding-y-lg (was Bootstrap's 0.5rem)
 $input-border-radius: $border-radius;
 $input-border-color: #d1d5db; // Gray-300
 $input-focus-border-color: $primary;
@@ -652,8 +664,52 @@ $bootstrap-icons-font-src: url("bootstrap-icons/font/fonts/bootstrap-icons.woff2
   }
 
   // DXTable header titles: muted by default (#157) so the table's CONTENT is
-  // the loud layer. Override to re-louden (e.g. `var(--bs-body-color)`).
-  --dx-table-header-color: var(--bs-secondary-color);
+  // the loud layer. Lightened again for S5b — #157's `--bs-secondary-color`
+  // (rgba(33,37,41,.75), ~5.9:1 on white) still read near-black next to legacy
+  // omnitend's light-slate headers. `#7c8293` (legacy's `$text-secondary`) is
+  // the signed-off value (~3.6:1 on white — fine for the semibold/large header
+  // text it colours, below the 4.5:1 body-text bar). Still on the same token so
+  // a consumer can re-louden (e.g. `var(--bs-body-color)`).
+  --dx-table-header-color: #7c8293;
+}
+
+// ----------------------------------------------------------------------------
+// Tables — header alignment + filter-row affordance
+// ----------------------------------------------------------------------------
+
+// B17: keep header labels vertically centred regardless of whether a column
+// carries sort icons. Bootstrap sets `.table > thead { vertical-align: bottom }`,
+// which floors a plain (non-sortable) column's label while a sortable
+// neighbour's taller two-arrow sort stack holds ITS label higher — one header
+// row, mixed baselines. Centring the whole thead makes vertical alignment
+// independent of the sort indicator's presence. Scoped to `.table > thead` so a
+// consumer who genuinely wants bottom-aligned headers can still opt back in on a
+// specific table.
+.table > thead {
+  vertical-align: middle;
+}
+
+// PL1: a magnifier glyph on DXTable's text/number filter inputs, so the filter
+// row reads as "this searches" at a glance (legacy lt-table carried one).
+//
+// It MUST be a background-image, not a `::before`/`::after` — an `<input>` is a
+// replaced element and cannot host pseudo-elements. The glyph is an inline
+// bootstrap-icons "search" SVG data-URI, tinted `#7c8293` (the same muted slate
+// as the header token above), sized and inset with `padding-left` so text
+// clears it.
+//
+// Direct-child selector (`> th > input.form-control`) is deliberate: DXTable's
+// text/number/date filters render a bare `.form-control` straight inside the
+// `<th>`, whereas the `select` filter's DAutocomplete nests its input inside
+// `.d-autocomplete .input-group .b-autocomplete-input-wrapper` — so it is not a
+// direct child and correctly gets NO glyph (it has its own chevron affordance).
+// `:not([type="date"])` further excludes the date filter (its own picker icon).
+.filter-row > th > input.form-control:not([type="date"]) {
+  background-image: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' width='16' height='16' fill='%237c8293' viewBox='0 0 16 16'%3e%3cpath d='M11.742 10.344a6.5 6.5 0 1 0-1.397 1.398h-.001q.044.06.098.115l3.85 3.85a1 1 0 0 0 1.415-1.414l-3.85-3.85a1 1 0 0 0-.115-.1zM12 6.5a5.5 5.5 0 1 1-11 0 5.5 5.5 0 0 1 11 0'/%3e%3c/svg%3e");
+  background-repeat: no-repeat;
+  background-position: left 0.65rem center;
+  background-size: 0.85em;
+  padding-left: 1.9rem;
 }
 
 // primary is near-black navy, so Bootstrap's darken-on-hover is imperceptible —
@@ -679,6 +735,35 @@ $bootstrap-icons-font-src: url("bootstrap-icons/font/fonts/bootstrap-icons.woff2
   }
 }
 
+// ----------------------------------------------------------------------------
+// Dropdowns — chevron caret (B14 / PO5)
+// ----------------------------------------------------------------------------
+// Bootstrap's `.dropdown-toggle::after` is a CSS border-triangle that sits high
+// against Poppins' line box and reads crude next to the rest of the theme.
+// Replace it with the bootstrap-icons chevron glyph, optically centred with a
+// little breathing room from the label. The font is already available: the
+// theme `@import`s `bootstrap-icons/font/bootstrap-icons` (declaring the
+// `@font-face`), and #77's post-build extraction ships that woff2 with the
+// stylesheet — so this needs no new dependency and no data-URI. Values signed
+// off after one padding iteration in the greendragon interim; the glyph metrics
+// are tunable via the variables below.
+$dx-dropdown-caret-size: 0.75em; // glyph size relative to the label
+$dx-dropdown-caret-gap: 0.4em; // space between label and chevron
+$dx-dropdown-caret-shift: 0.05em; // vertical nudge for optical centring
+.dropdown-toggle::after {
+  border: none; // drop Bootstrap's border-triangle
+  font-family: "bootstrap-icons";
+  content: "\F282"; // bi-chevron-down
+  font-size: $dx-dropdown-caret-size;
+  line-height: 1;
+  vertical-align: $dx-dropdown-caret-shift;
+  margin-left: $dx-dropdown-caret-gap;
+}
+.dropup .dropdown-toggle::after {
+  border: none;
+  content: "\F286"; // bi-chevron-up
+}
+
 // ----------------------------------------------------------------------------
 // Switches — green when ON, red when OFF, by default (#158)
 // ----------------------------------------------------------------------------
@@ -794,8 +879,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 {
@@ -810,6 +897,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
@@ -837,6 +936,11 @@ $dx-chart-palette-dark: (#60a5fa, #a3e635, #a78bfa, #2dd4bf, #fb923c, #22d3ee, #
 .b-autocomplete-content {
   min-width: max-content; // grow to the longest option (floors at the trigger width)
   max-width: min(90vw, 32rem); // but don't run away
+  // S3b.1: bvn caps this popup at 300px, showing ~7 of a ~30-option list behind
+  // an inner scrollbar — it "doesn't drop all the way down the page like a
+  // native select". Let it fall most of the way down the viewport (but never
+  // taller than 42rem) so the list reads like a real dropdown.
+  max-height: min(70vh, 42rem);
 }
 
 // ----------------------------------------------------------------------------

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

@@ -37,8 +37,13 @@ type LinkVariant =
 
 interface Props {
   /**
-   * The visual style variant of the button
-   * @default 'primary'
+   * The visual style variant of the button.
+   *
+   * Defaults to `'secondary'` (soft, non-emphatic). Under the soft-first
+   * house rule, `primary` is THE single emphatic action per page/modal, so a
+   * variant-less button must NOT be emphatic by default — declare
+   * `variant="primary"` explicitly where you mean the one loud action.
+   * @default 'secondary'
    */
   variant?: ButtonVariant | LinkVariant | null;
 
@@ -105,7 +110,7 @@ interface Props {
 }
 
 const props = withDefaults(defineProps<Props>(), {
-  variant: "primary",
+  variant: "secondary",
   disabled: false,
   loading: false,
   block: false,

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) => {