@omnitend/dashboard-for-laravel 0.36.0 → 0.38.0

package/docs/public/api-reference.json

@@ -1,8 +1,8 @@
 {
-  "generated": "2026-07-21T12:50:16.789Z",
+  "generated": "2026-07-23T18:28:14.921Z",
   "package": {
     "name": "@omnitend/dashboard-for-laravel",
-    "version": "0.36.0"
+    "version": "0.38.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",
@@ -3092,6 +3092,12 @@
             "required": false,
             "default": "\"success\"",
             "description": "On-state colour. `\"success\"` (default) reads the house green-on / red-off\nstyle — an active/enabled/good switch (\"Product is current\", \"Stock is\ntracked\", \"Visible\"). `\"neutral\"` is for semantically-mixed switches\n(\"contains alcohol\", an allergen toggle, \"hidden on web shop\") that\nshouldn't imply good/bad — it uses the brand primary on / grey off (#158)."
+          },
+          {
+            "name": "size",
+            "type": "\"sm\"",
+            "required": false,
+            "description": "`\"sm\"` renders a compact box (~31px vs the default ~35px input height) for\ndense rows that repeat the switch per item (a per-line visibility toggle in\na modal). Omit for the standard size, which matches the `.form-control`\nheight so a switch lines up with inputs beside it."
           }
         ],
         "events": [
@@ -3473,6 +3479,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": [

package/docs/public/docs-map.md

@@ -1,7 +1,7 @@
 # Documentation Map
 
 > Auto-generated hierarchical overview of all documentation
-> Last updated: 2026-07-21T12:50:16.844Z
+> Last updated: 2026-07-23T18:28:14.969Z
 
 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.36.0",
+  "version": "0.38.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)
 // ----------------------------------------------------------------------------
@@ -719,6 +804,21 @@ $dx-switch-on-soft: map.get(map.get($dx-variants, "success"), "soft-bg"); // #cd
   --dx-switch-pill: var(--bs-gray-400, #ced4da); // neutral pill in both states
 }
 
+// Optically centre the check/radio/switch box against its label's FIRST line.
+// Bootstrap's `.25em` top margin is mathematically right for a 1em box in a
+// 1.5em line box, but Poppins seats its glyphs low in the line box, so the box
+// reads visibly HIGH beside the text (same optical-metrics issue as the B14
+// dropdown caret). `0.325em` lands the box centre on Poppins' visual centre —
+// judged against a rendered filmstrip (0.25/0.30/0.325/0.35em) with Poppins
+// loaded, not from the maths. A top MARGIN (not flex-centring) is deliberate:
+// it aligns to the first line, so a multi-line label keeps the box on line one
+// rather than floating to the block's vertical centre. DXSwitch is unaffected —
+// it flex-centres and zeroes this margin on its inner input at higher
+// specificity (`.dx-switch :deep(.form-check-input) { margin: 0 }`).
+.form-check-input {
+  margin-top: 0.325em;
+}
+
 .form-switch .form-check-input {
   // OFF: light-red track, red thumb (left).
   background-color: var(--dx-switch-off-bg);
@@ -851,6 +951,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/extended/DXSwitch.vue

@@ -21,7 +21,7 @@
   `label` prop for simple text, or the default slot for richer label content.
 -->
 <template>
-  <div class="dx-switch" :class="[`dx-switch--${onVariant}`, { 'dx-switch--on': isOn }]">
+  <div class="dx-switch" :class="[`dx-switch--${onVariant}`, { 'dx-switch--on': isOn, 'dx-switch--sm': size === 'sm' }]">
     <!-- For the neutral variant, tag the inner `.form-switch` with
          `switch-neutral` so the global theme restores grey-off / primary-on for
          the toggle itself (the box styling below handles the wrapper). -->
@@ -63,6 +63,13 @@ interface Props {
    * shouldn't imply good/bad — it uses the brand primary on / grey off (#158).
    */
   onVariant?: "success" | "neutral";
+  /**
+   * `"sm"` renders a compact box (~31px vs the default ~35px input height) for
+   * dense rows that repeat the switch per item (a per-line visibility toggle in
+   * a modal). Omit for the standard size, which matches the `.form-control`
+   * height so a switch lines up with inputs beside it.
+   */
+  size?: "sm";
 }
 
 const props = withDefaults(defineProps<Props>(), {
@@ -131,6 +138,17 @@ defineOptions({
   transition: background-color 0.15s ease-in-out, border-color 0.15s ease-in-out;
 }
 
+/* Compact size (#… size="sm"): a shorter box for dense rows that repeat the
+   switch per item. `min-height: auto` drops the input-height floor so the box
+   shrinks to its padded content (~31px vs ~35px); the smaller font pulls the
+   label in to match. The fixed-rem toggle itself is unchanged — only the box
+   chrome tightens. */
+.dx-switch--sm :deep(.form-check) {
+  font-size: 0.875rem;
+  min-height: auto;
+  padding: 0.25rem 0.625rem;
+}
+
 /* Label on the left, toggle on the right (DOM order is input then label). */
 .dx-switch :deep(.form-check-label) {
   order: 1;

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

@@ -131,6 +131,23 @@
                                         @update:model-value="handleSelectFilterChange(field, $event)"
                                     />
 
+                                    <!-- Native Select Filter (S3b): a plain <select> for consumers who
+                                         want OS-native behaviour (full-height menu, native keyboard/scroll)
+                                         instead of the DAutocomplete typeahead. Shares the select filter's
+                                         option list (getFieldFilterOptions) and change handler
+                                         (handleSelectFilterChange) EXACTLY — so it behaves identically to
+                                         filter:"select" in every way but the control. Single-select only:
+                                         `filterMultiple` is ignored here. The model maps "no filter" to the
+                                         FILTER_ALL_VALUE sentinel (see nativeSelectFilterValue) so the "All …"
+                                         option shows selected in a native control. -->
+                                    <DFormSelect
+                                        v-else-if="field.filter === 'select-native'"
+                                        :model-value="nativeSelectFilterValue(field)"
+                                        :options="getFieldFilterOptions(field) as unknown as Record<string, unknown>[]"
+                                        size="sm"
+                                        @update:model-value="handleSelectFilterChange(field, $event)"
+                                    />
+
                                     <!-- Number Filter -->
                                     <DFormInput
                                         v-else-if="field.filter === 'number'"
@@ -310,11 +327,17 @@ import DXTableShell from "./DXTableShell.vue";
 import DSpinner from "../base/DSpinner.vue";
 import DTable from "../base/DTable.vue";
 import DFormInput from "../base/DFormInput.vue";
+import DFormSelect from "../base/DFormSelect.vue";
 import DAutocomplete from "../base/DAutocomplete.vue";
 import DButton from "../base/DButton.vue";
 import DXTablePagination from "./DXTablePagination.vue";
 import DXTableEditorModal from "./DXTableEditorModal.vue";
-export type FilterType = 'text' | 'select' | 'number' | 'date' | false;
+// 'select'        — DAutocomplete typeahead (browse-on-focus + type-to-narrow).
+// 'select-native' — a plain native <select> (DFormSelect). Same options, value
+//   semantics and client-side matching as 'select'; differs ONLY in the control,
+//   for consumers who want OS-native menu behaviour (full-height menu, native
+//   keyboard/scroll). Single-select only — `filterMultiple` is ignored for it.
+export type FilterType = 'text' | 'select' | 'select-native' | 'number' | 'date' | false;
 
 export interface FilterOption {
     value: string;
@@ -384,6 +407,12 @@ export interface TableField {
     filterAllText?: string;
     sortable?: boolean;
     hint?: string;
+    /**
+     * The inline filter control for this column, or `false`/omit for none. See
+     * `FilterType`. `'select'` (typeahead) and `'select-native'` (plain
+     * `<select>`) share the same options and value semantics — pick the native
+     * one when OS-native menu behaviour matters more than type-to-narrow.
+     */
     filter?: FilterType;
     filterOptions?: FilterOption[];
     filterPlaceholder?: string;
@@ -769,6 +798,19 @@ export interface Props<TItem = any> {
      * declared width share the remaining space equally.
      */
     fixedLayout?: boolean;
+
+    /**
+     * Field on each row whose value uniquely identifies it, forwarded to the
+     * inner bvn table's `primaryKey` (all three data modes). Without it bvn keys
+     * client-side rows by their INDEX, which mis-associates per-row STATEFUL cell
+     * components when a row is inserted/removed mid-interaction — a debounced
+     * edit in one row can end up saved against the wrong record after a
+     * concurrent delete of a row above. Set it (e.g. `primary-key="id"`) so bvn
+     * keys rows by that field's value and each row keeps its identity across
+     * data mutations. Non-breaking: omit it and rows key by index exactly as
+     * before.
+     */
+    primaryKey?: string;
 }
 
 const props = withDefaults(defineProps<Props<T>>(), {
@@ -1102,7 +1144,9 @@ const clientSideFilteredItems = computed<T[]>(() => {
                         // Case-insensitive contains search
                         return String(itemValue).toLowerCase().includes(filterValue);
 
+                    // Both select controls match identically (exact string match).
                     case 'select':
+                    case 'select-native':
                         // Exact match
                         return String(itemValue) === candidate;
 
@@ -1272,6 +1316,15 @@ const fieldsHaveWidths = computed(() => props.fields.some(hasDeclaredWidth));
 // key: a display column can filter on a different server param via `filterKey`.
 const filterKeyFor = (field: TableField): string => field.filterKey ?? field.key;
 
+// Both select-style filters — 'select' (DAutocomplete typeahead) and
+// 'select-native' (plain <select>) — share the SAME option list, value
+// semantics and client-side matching; they differ only in the rendered control.
+// This predicate keeps the two in lockstep everywhere the option-derivation and
+// server-value logic runs, so a `select-native` column gets identical options to
+// what `select` would offer.
+const isSelectFilter = (field: TableField): boolean =>
+    field.filter === 'select' || field.filter === 'select-native';
+
 // The value that means "has no value" for a select filter (#106).
 const filterNullValueFor = (field: TableField): string => field.filterNullValue ?? 'null';
 
@@ -1286,6 +1339,17 @@ const handleSelectFilterChange = (field: TableField, value: unknown) => {
     handleFilterChange(filterKeyFor(field), selected === FILTER_ALL_VALUE ? '' : selected);
 };
 
+// The model value for a `select-native` control. Unlike DAutocomplete (which
+// falls back to '' and shows its placeholder), a native <select> selects its
+// FIRST option when the bound value matches none — which would desync the
+// control from the model. So the "no filter" state must map to FILTER_ALL_VALUE,
+// the value carried by the "All …" option, so that option shows as selected.
+// This is the read-side mirror of the write-side translation
+// `handleSelectFilterChange` already does (FILTER_ALL_VALUE → '') — the sentinel
+// is handled in one conceptual place, not reinvented.
+const nativeSelectFilterValue = (field: TableField): string =>
+    (effectiveFilters.value[filterKeyFor(field)] as string) || FILTER_ALL_VALUE;
+
 // Multi-value select filter (#51): the autocomplete's array model maps
 // straight onto the filters entry; an emptied selection removes the entry.
 const multiFilterValueFor = (field: TableField): string[] => {
@@ -1361,7 +1425,7 @@ const derivedFilterOptions = computed<Record<string, FilterOption[]>>(() => {
     const optionsByFieldKey: Record<string, FilterOption[]> = {};
 
     for (const field of props.fields) {
-        if (field.filter !== 'select') continue;
+        if (!isSelectFilter(field)) continue;
         if (field.deriveFilterOptions === false) continue;
         // Explicit options win outright (see `getFieldFilterOptions`), so don't
         // spend a pass over every row producing a list nothing will read.
@@ -1434,8 +1498,10 @@ const getFieldFilterOptions = (field: TableField): FilterOption[] => {
     //
     // A `filterMultiple` column omits it (#51): "no filter" inside a
     // multi-select reads as a selectable value, and clearing is already
-    // discoverable there — remove the chips, or the ✕.
-    if (!field.filterMultiple) {
+    // discoverable there — remove the chips, or the ✕. `select-native` is the
+    // exception: it is ALWAYS single-select (it ignores `filterMultiple`), so it
+    // still needs the "All" reset option even when `filterMultiple` is set.
+    if (!field.filterMultiple || field.filter === 'select-native') {
         options.push({ value: FILTER_ALL_VALUE, text: filterAllLabelFor(field) });
     }
 
@@ -1750,7 +1816,7 @@ const shouldShowPerPageSelector = computed(() => {
 // mutually exclusive, so a client-side derived column can never appear here.
 const fieldsNeedingFilterValues = computed(() => {
     return props.fields
-        .filter(field => field.filter === 'select' && (!field.filterOptions || field.filterOptions.length === 0))
+        .filter(field => isSelectFilter(field) && (!field.filterOptions || field.filterOptions.length === 0))
         .map(field => filterKeyFor(field));
 });
 
@@ -2243,6 +2309,13 @@ const tablePassthroughProps = computed(() => ({
             ? `No ${pluralItemName.value} match your filters`
             : `No ${pluralItemName.value} found`),
     expandedItems: props.expandedItems,
+    // Row identity (#B16). Forwarded here rather than in `tableModeBindings`
+    // because it is mode-INDEPENDENT — it must key rows by value in provider,
+    // client-side AND inertia mode alike. `undefined` when unset, so bvn falls
+    // back to index keys (its default) and nothing changes for tables that don't
+    // opt in. Reaches BTable through DTable's `v-bind="$attrs"` (its prop is
+    // `primaryKey`); DTable needs no change.
+    primaryKey: props.primaryKey,
 }));
 // Computed: Singular and plural item names
 const singularItemName = computed(() => props.itemName);