@omnitend/dashboard-for-laravel 0.26.0 → 0.27.0

package/docs/public/api-reference.json

@@ -1,5 +1,5 @@
 {
-  "generated": "2026-07-13T10:49:19.086Z",
+  "generated": "2026-07-18T05:05:36.998Z",
   "package": {
     "name": "@omnitend/dashboard-for-laravel",
     "version": "0.26.0"

package/docs/public/docs-map.md

@@ -1,7 +1,7 @@
 # Documentation Map
 
 > Auto-generated hierarchical overview of all documentation
-> Last updated: 2026-07-13T10:49:19.148Z
+> Last updated: 2026-07-18T05:05:37.057Z
 
 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.26.0",
+  "version": "0.27.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

@@ -7,19 +7,31 @@
 // The Sass module for `color.mix()` etc. `@use` must precede all other
 // statements (variable overrides, `@import`), so it stays at the very top.
 @use "sass:color";
+@use "sass:map";
 
 // ----------------------------------------------------------------------------
 // Colors
 // ----------------------------------------------------------------------------
 
-$primary: #4f46e5; // Indigo-600 (8.6:1 with white)
-$secondary: #475569; // Slate-600 (7.0:1 with white) - darkened for better contrast
-$success: #10b981; // Emerald-500 (6.7:1 with white)
-$danger: #dc2626; // Red-600 (7.2:1 with white) - darkened for better contrast
-$warning: #f59e0b; // Amber-500 (7.7:1 with white)
-$info: #2563eb; // Blue-600 (7.3:1 with white)
+// Base $theme-colors carry each hue's READABLE-ON-LIGHT identity (its "emphasis"
+// shade) — this is what `.text-*`, `.link-*`, `.border-*` and outline buttons
+// use, so every one must clear AA on white. Bold solid FILLS (primary/danger
+// buttons) and SOFT tints (soft buttons, badges, alerts) are applied as explicit
+// overrides after the Bootstrap import, from the $dx-variants map. See
+// plans/2026-07-18-semantic-colour-system.md.
+$primary: #151e2d; // Omni Tend brand navy (16.73:1 on white)
+$secondary: #475569; // Slate-600 (7.58:1 on white)
+$success: #4d7c0f; // Lime-700 emphasis (4.99:1 on white); soft/vivid tints in $dx-variants
+$danger: #dc2626; // Red-600 (4.83:1 on white)
+$warning: #b45309; // Amber-700 emphasis (5.02:1 on white)
+$info: #2563eb; // Blue-600 (5.17:1 on white)
 $light: #f8fafc; // Slate-50 (uses dark text)
-$dark: #0f172a; // Slate-900 (uses white text)
+$dark: #151e2d; // Brand navy — sidebar/high-contrast surfaces (was Slate-900 #0f172a)
+
+// Links are the info-blue, independent of the near-black brand primary (a navy
+// link would read as bold text, not a link).
+$link-color: #2563eb;
+$link-shade-percentage: 15%;
 
 // ----------------------------------------------------------------------------
 // Contrast Settings
@@ -154,6 +166,21 @@ $badge-padding-y: 0.25rem;
 $badge-padding-x: 0.625rem;
 $badge-font-weight: 500;
 
+// The ONE source of truth for the semantic colour system. Each variant carries
+// its SOLID fill + same-hue text (primary/danger buttons, solid fills), its SOFT
+// tint pair (soft buttons, badges, alerts, status), its EMPHASIS shade (outline
+// buttons, coloured links, .text-*), and whether its button is solid or soft.
+// The overrides after the Bootstrap import loop over this map. All pairs are
+// WCAG AA verified. See plans/2026-07-18-semantic-colour-system.md.
+$dx-variants: (
+  "primary": (solid-bg: #151e2d, solid-text: #e9f0f8, soft-bg: #e9f0f8, soft-text: #151e2d, emphasis: #151e2d, button: "solid"),
+  "secondary": (solid-bg: #475569, solid-text: #e6ebf2, soft-bg: #e6ebf2, soft-text: #29374a, emphasis: #475569, button: "soft"),
+  "success": (solid-bg: #84cc16, solid-text: #203b0e, soft-bg: #cdf9b2, soft-text: #203b0e, emphasis: #4d7c0f, button: "soft"),
+  "danger": (solid-bg: #dc2626, solid-text: #ffffff, soft-bg: #f5dff1, soft-text: #59194a, emphasis: #dc2626, button: "solid"),
+  "warning": (solid-bg: #f59e0b, solid-text: #512d05, soft-bg: #fce5c4, soft-text: #512d05, emphasis: #b45309, button: "soft"),
+  "info": (solid-bg: #2563eb, solid-text: #eef4ff, soft-bg: #deebff, soft-text: #12376c, emphasis: #2563eb, button: "soft"),
+);
+
 // ----------------------------------------------------------------------------
 // Dashboard
 // ----------------------------------------------------------------------------
@@ -420,6 +447,112 @@ $bootstrap-icons-font-src: url("bootstrap-icons/font/fonts/bootstrap-icons.woff2
   }
 }
 
+// ----------------------------------------------------------------------------
+// Semantic colour system (soft-first)
+// ----------------------------------------------------------------------------
+// One loop over $dx-variants applies the whole system on top of Bootstrap:
+//
+//   - Buttons: primary/danger are SOLID (fill from the base colour; we only
+//     override the label to the same-hue tint, letting Bootstrap shade hover/
+//     active). secondary/success/warning/info are SOFT (light tint bg + dark
+//     text, fully overridden incl. hover/active).
+//   - Outline buttons: the emphasis shade for border/label, the soft tint on hover.
+//   - Badges: `.badge.text-bg-*` re-tinted soft — needs `!important` because
+//     Bootstrap's `.text-bg-*` helper sets its colours `!important` by design.
+//   - Alerts: the soft tint.
+//   - Links/text: `.link-*` and `.text-*` take the emphasis shade so they read
+//     on white (the base colours already carry emphasis for most variants; this
+//     pins the two — success/warning — whose base differs).
+@each $name, $v in $dx-variants {
+  $solid-bg: map.get($v, "solid-bg");
+  $solid-text: map.get($v, "solid-text");
+  $soft-bg: map.get($v, "soft-bg");
+  $soft-text: map.get($v, "soft-text");
+  $emphasis: map.get($v, "emphasis");
+  $is-solid: map.get($v, "button") == "solid";
+
+  @if $is-solid {
+    // Solid button: keep Bootstrap's fill + hover/active shading (from the base
+    // colour), override only the LABEL to the same-hue tint.
+    .btn-#{$name} {
+      --bs-btn-color: #{$solid-text};
+      --bs-btn-hover-color: #{$solid-text};
+      --bs-btn-active-color: #{$solid-text};
+      --bs-btn-disabled-color: #{$solid-text};
+    }
+  } @else {
+    // Soft button: light tint bg + dark same-hue label; darken the tint slightly
+    // on hover/active for feedback.
+    .btn-#{$name} {
+      --bs-btn-color: #{$soft-text};
+      --bs-btn-bg: #{$soft-bg};
+      --bs-btn-border-color: #{$soft-bg};
+      --bs-btn-hover-color: #{$soft-text};
+      --bs-btn-hover-bg: #{color.scale($soft-bg, $lightness: -6%)};
+      --bs-btn-hover-border-color: #{color.scale($soft-bg, $lightness: -6%)};
+      --bs-btn-active-color: #{$soft-text};
+      --bs-btn-active-bg: #{color.scale($soft-bg, $lightness: -10%)};
+      --bs-btn-active-border-color: #{color.scale($soft-bg, $lightness: -10%)};
+      --bs-btn-disabled-color: #{$soft-text};
+      --bs-btn-disabled-bg: #{$soft-bg};
+      --bs-btn-disabled-border-color: #{$soft-bg};
+    }
+  }
+
+  // Outline button: emphasis border/label, fills to the soft tint on hover so it
+  // stays calm (not a sudden saturated block).
+  .btn-outline-#{$name} {
+    --bs-btn-color: #{$emphasis};
+    --bs-btn-border-color: #{$emphasis};
+    --bs-btn-hover-color: #{$soft-text};
+    --bs-btn-hover-bg: #{$soft-bg};
+    --bs-btn-hover-border-color: #{$emphasis};
+    --bs-btn-active-color: #{$soft-text};
+    --bs-btn-active-bg: #{$soft-bg};
+    --bs-btn-active-border-color: #{$emphasis};
+  }
+
+  // Badge — soft tint. `!important` beats Bootstrap's `.text-bg-*` helper.
+  .badge.text-bg-#{$name} {
+    background-color: #{$soft-bg} !important;
+    color: #{$soft-text} !important;
+  }
+
+  // Alert — soft tint, with the emphasis shade as the accent border.
+  .alert-#{$name} {
+    --bs-alert-bg: #{$soft-bg};
+    --bs-alert-color: #{$soft-text};
+    --bs-alert-border-color: #{color.scale($soft-bg, $lightness: -8%)};
+    --bs-alert-link-color: #{$emphasis};
+  }
+
+  // `.text-#{$name}` and `.link-#{$name}` need no override: each variant's base
+  // colour IS its emphasis shade, so Bootstrap already renders them legible.
+}
+
+// primary is near-black navy, so Bootstrap's darken-on-hover is imperceptible —
+// the main action button would have no visible hover feedback. Lighten instead.
+// (danger's red darkens visibly, so the generic solid path is fine for it.)
+.btn-primary {
+  --bs-btn-hover-bg: #{color.scale($primary, $lightness: 20%)};
+  --bs-btn-hover-border-color: #{color.scale($primary, $lightness: 20%)};
+  --bs-btn-active-bg: #{color.scale($primary, $lightness: 12%)};
+  --bs-btn-active-border-color: #{color.scale($primary, $lightness: 12%)};
+}
+
+// Tertiary "ghost" button: a `link`-variant button restyled to read as a quiet
+// action, not a hyperlink — body colour, no underline, faint hover surface.
+.btn-link {
+  --bs-btn-color: var(--bs-body-color);
+  --bs-btn-hover-color: var(--bs-body-color);
+  --bs-btn-active-color: var(--bs-body-color);
+  text-decoration: none;
+
+  &:hover {
+    background-color: var(--bs-light);
+  }
+}
+
 // ----------------------------------------------------------------------------
 // Autocomplete
 // ----------------------------------------------------------------------------

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

@@ -137,6 +137,17 @@
                             </div>
                         </template>
 
+                        <!-- A dotted field key (`paid_by.card`) renders as an EMPTY cell in
+                             bootstrap-vue-next, in every payload shape, so DXTable resolves
+                             those columns itself (#121). A consumer's own cell(<key>) slot
+                             wins — `dottedCellFields` excludes it, and the forwarding below
+                             would otherwise declare the same slot name twice. -->
+                        <template
+                            v-for="field in dottedCellFields($slots)"
+                            :key="`dotted-cell-${field.key}`"
+                            #[`cell(${field.key})`]="{ item }"
+                        >{{ fieldValueOf(item, field.key) }}</template>
+
                         <!-- Forward every slot the inner table understands: cell(<key>),
                              foot(<key>), custom-foot, empty, empty-filtered, row-expansion,
                              table-busy/caption/colgroup, thead-sub, top-row, bottom-row.
@@ -245,6 +256,17 @@
                             </div>
                         </template>
 
+                        <!-- A dotted field key (`paid_by.card`) renders as an EMPTY cell in
+                             bootstrap-vue-next, in every payload shape, so DXTable resolves
+                             those columns itself (#121). A consumer's own cell(<key>) slot
+                             wins — `dottedCellFields` excludes it, and the forwarding below
+                             would otherwise declare the same slot name twice. -->
+                        <template
+                            v-for="field in dottedCellFields($slots)"
+                            :key="`dotted-cell-${field.key}`"
+                            #[`cell(${field.key})`]="{ item }"
+                        >{{ fieldValueOf(item, field.key) }}</template>
+
                         <!-- Forward every slot the inner table understands: cell(<key>),
                              foot(<key>), custom-foot, empty, empty-filtered, row-expansion,
                              table-busy/caption/colgroup, thead-sub, top-row, bottom-row.
@@ -354,6 +376,17 @@
                             </div>
                         </template>
 
+                        <!-- A dotted field key (`paid_by.card`) renders as an EMPTY cell in
+                             bootstrap-vue-next, in every payload shape, so DXTable resolves
+                             those columns itself (#121). A consumer's own cell(<key>) slot
+                             wins — `dottedCellFields` excludes it, and the forwarding below
+                             would otherwise declare the same slot name twice. -->
+                        <template
+                            v-for="field in dottedCellFields($slots)"
+                            :key="`dotted-cell-${field.key}`"
+                            #[`cell(${field.key})`]="{ item }"
+                        >{{ fieldValueOf(item, field.key) }}</template>
+
                         <!-- Forward every slot the inner table understands: cell(<key>),
                              foot(<key>), custom-foot, empty, empty-filtered, row-expansion,
                              table-busy/caption/colgroup, thead-sub, top-row, bottom-row.
@@ -677,6 +710,7 @@ import axios from "axios";
 import pluralize from "pluralize";
 import { useToast } from "../../composables/useToast";
 import { useForm } from "../../composables/useForm";
+import { getByPath } from "../../utils/objectPath";
 import DContainer from "../base/DContainer.vue";
 import DRow from "../base/DRow.vue";
 import DCol from "../base/DCol.vue";
@@ -1222,10 +1256,11 @@ const clientSideFilteredItems = computed<T[]>(() => {
             // `customer_id`). Match on the filter key when the row has it,
             // otherwise fall back to the column's own value — which is also the
             // one the user can actually see and type against.
+            // Both lookups are dot-path aware, so a nested payload filters (#121).
             const itemValue =
-                field && key in (item as any)
-                    ? (item as any)[key]
-                    : (item as any)[field?.key ?? key];
+                field && hasFieldValue(item, key)
+                    ? fieldValueOf(item, key)
+                    : fieldValueOf(item, field?.key ?? key);
 
             // The "no value" option (e.g. Unassigned) is the one filter that
             // MATCHES an absent value rather than failing on it.
@@ -1279,13 +1314,16 @@ const clientSideSortedItems = computed<T[]>(() => {
     const direction = order === 'desc' ? -1 : 1;
 
     return items.sort((a, b) => {
-        const aVal = (a as any)[key];
-        const bVal = (b as any)[key];
+        // Dot-path aware, so `paid_by.card` sorts a nested payload (#121).
+        const aVal = fieldValueOf(a, key);
+        const bVal = fieldValueOf(b, key);
 
         // Handle null/undefined
-        if (aVal == null && bVal == null) return 0;
-        if (aVal == null) return direction;
-        if (bVal == null) return -direction;
+        const aEmpty = aVal === null || aVal === undefined;
+        const bEmpty = bVal === null || bVal === undefined;
+        if (aEmpty && bEmpty) return 0;
+        if (aEmpty) return direction;
+        if (bEmpty) return -direction;
 
         // Numeric comparison
         if (typeof aVal === 'number' && typeof bVal === 'number') {
@@ -1300,6 +1338,54 @@ const clientSideSortedItems = computed<T[]>(() => {
 // API mode filter values (extracted from responses)
 const apiFilterValues = ref<Record<string, string[]>>({});
 
+/*
+ * Resolving a field's value from a row, dot-path aware (#121).
+ *
+ * A key containing a dot (`paid_by.card`) was unusable. Two layers disagreed:
+ * bootstrap-vue-next's `mapItem` UN-flattens any item key containing a dot
+ * (`{'paid_by.card': v}` becomes `{paid_by: {card: v}}`) and then its cell reads
+ * `item['paid_by.card']` FLAT and gets undefined — so bvn renders a dotted key
+ * as an empty cell in BOTH payload shapes. Meanwhile our own client-side sort
+ * and filter also read flat, which a NESTED payload (what Laravel serialises for
+ * a relation) never satisfies. Consumers worked around it by flattening every
+ * nested key to an `_x` alias in each client-side port.
+ *
+ * LITERAL key first, then dot-path. That single order covers every shape:
+ * an ordinary key (`name`), a dots-flat payload (the literal `paid_by.card`
+ * key), and a nested payload (walk `paid_by` -> `card`). It also means bvn's
+ * un-flattening is harmless rather than hostile — mapItem normalises flat to
+ * nested, and the path read finds it either way.
+ */
+const fieldValueOf = (item: unknown, key: string): any => {
+    if (item === null || item === undefined) return undefined;
+    if (Object.prototype.hasOwnProperty.call(item, key)) {
+        return (item as Record<string, any>)[key];
+    }
+    return getByPath(item as Record<string, any>, key);
+};
+
+/*
+ * Whether a row carries a value for `key` at all — presence, not truthiness.
+ * Mirrors the `key in item` check this replaced, extended to dot paths.
+ */
+const hasFieldValue = (item: unknown, key: string): boolean => {
+    if (item === null || item === undefined) return false;
+    if (Object.prototype.hasOwnProperty.call(item, key)) return true;
+    return getByPath(item as Record<string, any>, key) !== undefined;
+};
+
+/*
+ * Dotted-key columns DXTable must render itself, because bvn renders them empty
+ * (see `fieldValueOf`). A consumer's own `cell(<key>)` slot always wins — it is
+ * forwarded separately, and declaring the same slot name twice would clobber it.
+ *
+ * A FUNCTION, not a computed, for the same reason as `forwardableSlotNames`:
+ * `useSlots()` returns an object Vue mutates in place with nothing to track, so
+ * a computed over its keys is captured on first render and never updates (#114).
+ */
+const dottedCellFields = (slots: Record<string, unknown>): TableField[] =>
+    props.fields.filter((field) => field.key.includes('.') && !slots[`cell(${field.key})`]);
+
 // Computed: Get effective filter options for a field
 // The key a column's filter is SENT under, which is not always the column's own
 // key: a display column can filter on a different server param via `filterKey`.
@@ -1855,6 +1941,7 @@ const handleFilterChange = (fieldKey: string, value: string) => {
                 {
                     page: 1, // Reset to first page when filtering
                     filters: newFilters,
+                    perPage: effectivePerPage.value,
                     ...sortParams(effectiveSortBy.value),
                 },
                 { preserveState: true }
@@ -1929,6 +2016,18 @@ try {
 // Forward only the keyed edit slots the consumer actually provided, so
 // DXForm doesn't mistake an always-present (but empty) wrapper for
 // a real custom-value override.
+/*
+ * A field's own starting value, used to seed a CREATE form and as the fallback
+ * when a row lacks the key (#122).
+ *
+ * `field.default ?? ''` can't express a NULL default: a select whose "none"
+ * option is `value: null` — which is what the column stores — seeds '' instead,
+ * matches no option, and renders blank. Presence, not nullishness, decides here
+ * too, so the create and edit paths agree about the same field.
+ */
+const defaultValueFor = (field: any): any =>
+    Object.prototype.hasOwnProperty.call(field, 'default') ? field.default : '';
+
 /*
  * Seeding an EDIT form from a row (#117).
  *
@@ -1941,7 +2040,7 @@ const seedValueFor = (field: any, row: T): any => {
     if (Object.prototype.hasOwnProperty.call(row as any, field.key)) {
         return (row as any)[field.key];
     }
-    return field.default ?? '';
+    return defaultValueFor(field);
 };
 
 /*
@@ -2063,8 +2162,17 @@ const isTableSlot = (name: string) =>
 const forwardableSlotNames = (slots: Record<string, unknown>): string[] =>
     Object.keys(slots).filter((name) => isTableSlot(name));
 
-const tableSlotSignature = (slots: Record<string, unknown>): string =>
-    Object.keys(slots).filter(isTableSlot).sort().join('|');
+const tableSlotSignature = (slots: Record<string, unknown>): string => {
+    // DXTable's OWN dotted-cell slots count too (#121). bvn captures its cell
+    // slot set at mount (#114), so a dotted-key column that appears LATER —
+    // data-driven columns resolved after a fetch — adds a `cell(...)` slot bvn
+    // ignores, and the cell renders empty. Folding the dotted-cell field keys
+    // into the signature remounts the inner table when that set changes, exactly
+    // as it does for a consumer's late `cell(...)` slot.
+    const consumerSlots = Object.keys(slots).filter(isTableSlot);
+    const dottedCellSlots = dottedCellFields(slots).map((field) => `cell(${field.key})`);
+    return [...consumerSlots, ...dottedCellSlots].sort().join('|');
+};
 
 /*
  * The template iterates `$slots` DIRECTLY rather than a computed over
@@ -2245,13 +2353,13 @@ const handleCreateNew = () => {
     if (!editForm.value) {
         const formData: Record<string, any> = {};
         submittableEditFields.value.forEach(field => {
-            formData[field.key] = field.default ?? '';
+            formData[field.key] = defaultValueFor(field);
         });
         editForm.value = useForm(formData);
     } else {
         // Reset existing form to defaults
         submittableEditFields.value.forEach(field => {
-            editForm.value.data[field.key] = field.default ?? '';
+            editForm.value.data[field.key] = defaultValueFor(field);
         });
         editForm.value.clearErrors();
     }

package/resources/js/composables/defineForm.ts

@@ -65,10 +65,22 @@ export function defineForm<const TFields extends readonly FormFieldDefinition[]>
 ): DefineFormReturn<InferFormData<TFields>> {
     type FormData = InferFormData<TFields>;
 
-    // Extract initial data from field definitions
+    // Extract initial data from field definitions.
+    //
+    // #125: `field.default ?? getDefaultValueForType(type)` cannot express a
+    // *null* default — a select whose "none" option is `value: null` (which is
+    // what the column stores) seeded '' (the type default), matched no option,
+    // and rendered blank. This is the same bug #122 fixed in DXTable. Decide on
+    // definedness, not nullishness, so null survives; an absent (or explicitly
+    // `undefined`) default still falls back to the type default rather than
+    // seeding `undefined`, which would drop the key from the JSON payload. This
+    // matches DXRepeater's `!== undefined` rule, so all seeding sites agree.
     const initialData = fieldDefinitions.reduce(
         (acc, field) => {
-            acc[field.key] = field.default ?? getDefaultValueForType(field.type);
+            acc[field.key] =
+                field.default !== undefined
+                    ? field.default
+                    : getDefaultValueForType(field.type);
             return acc;
         },
         {} as Record<string, any>,