@omnitend/dashboard-for-laravel 0.34.0 → 0.36.0

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

@@ -1,9 +1,10 @@
-import { computed, type ComputedRef } from "vue";
+import { computed, type ComputedRef, type Ref } from "vue";
 import type { ChartData, ChartDataset, ChartOptions } from "chart.js";
 import {
     baseOptions,
     applyPalette,
     mergeOptions,
+    useColorModeVersion,
     type ChartValueFormat,
 } from "./chartTheme";
 
@@ -35,35 +36,52 @@ export interface ThemedChartProps<TType extends "bar" | "line"> {
  * data-viz palette to un-coloured datasets and deep-merges the consumer's
  * `options` over the dashboard-friendly defaults. Pass the reactive `props`
  * object (property access stays reactive inside the computeds).
+ *
+ * `host` is the chart's own container element (a template ref). It is BOTH the
+ * `data-bs-theme` scope the palette resolves against and — being a ref read
+ * inside the computeds — the trigger that re-themes once it is populated on
+ * mount, since the first render happens before a template ref exists (#161).
  */
 export function useThemedChart<TType extends "bar" | "line">(
     type: TType,
     props: ThemedChartProps<TType>,
+    host: Ref<HTMLElement | null>,
 ): {
     chartData: ComputedRef<ChartData<TType>>;
     mergedOptions: ComputedRef<ChartOptions<TType>>;
 } {
-    const chartData = computed(
-        () =>
-            ({
-                labels: props.labels,
-                datasets: applyPalette(props.datasets, type, props.labels.length),
-            }) as ChartData<TType>,
-    );
+    // 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 mergedOptions = computed(
-        () =>
-            mergeOptions(
-                baseOptions({
-                    valueFormat: props.valueFormat,
-                    currencySymbol: props.currencySymbol,
-                    locale: props.locale,
-                    showLegend: props.showLegend ?? props.datasets.length > 1,
-                    hasValueAxis: true,
-                }),
-                props.options ?? {},
-            ) as ChartOptions<TType>,
-    );
+    const chartData = computed(() => {
+        void colorModeVersion.value;
+        return {
+            labels: props.labels,
+            datasets: applyPalette(
+                props.datasets,
+                type,
+                props.labels.length,
+                host.value,
+            ),
+        } as ChartData<TType>;
+    });
+
+    const mergedOptions = computed(() => {
+        void colorModeVersion.value;
+        return mergeOptions(
+            baseOptions({
+                valueFormat: props.valueFormat,
+                currencySymbol: props.currencySymbol,
+                locale: props.locale,
+                showLegend: props.showLegend ?? props.datasets.length > 1,
+                hasValueAxis: true,
+                scope: host.value,
+            }),
+            props.options ?? {},
+        ) as ChartOptions<TType>;
+    });
 
     return { chartData, mergedOptions };
 }

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

@@ -426,7 +426,7 @@ watch(activeGroupIndex, () => {
   overflow-x: hidden;
 }
 
-/* Dense rhythm (#95): greendragon's cutover values, adopted as the default —
+/* Dense rhythm (#95): values proven in a production dashboard, adopted as the default —
    natural-case headers at 0.875rem (no uppercase/letter-spacing), tight group
    spacing. */
 .nav-group {

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

@@ -13,8 +13,9 @@
 -->
 <template>
     <BForm
+        ref="formRoot"
         @submit.prevent="handleSubmit"
-        :class="{ 'dx-form--horizontal': layout === 'horizontal' }"
+        :class="{ 'dx-form--horizontal': resolvedLayout === 'horizontal' }"
     >
         <!-- Form-level error message -->
         <DAlert
@@ -71,7 +72,7 @@
                             :field="field"
                             :form="resolvedForm"
                             :model="model"
-                            :layout="layout"
+                            :layout="resolvedLayout"
                             :label-cols="labelCols"
                         >
                             <!-- Forward every DXForm slot so the field can render
@@ -105,7 +106,7 @@
                     :field="field"
                     :form="resolvedForm"
                     :model="model"
-                    :layout="layout"
+                    :layout="resolvedLayout"
                     :label-cols="labelCols"
                 >
                     <!-- Forward every DXForm slot so the field can render its
@@ -166,7 +167,7 @@
 </template>
 
 <script setup lang="ts">
-import { computed, watch } from "vue";
+import { computed, ref, watch, type ComponentPublicInstance } from "vue";
 import { BForm } from "bootstrap-vue-next";
 import DAlert from "../base/DAlert.vue";
 import DButton from "../base/DButton.vue";
@@ -176,6 +177,7 @@ import { BTab as DTab } from "bootstrap-vue-next"; // raw BTab: BTabs scans slot
 import DXFormField from "./DXFormField.vue";
 import type { UseFormReturn } from "../../composables/useForm";
 import type { DefineFormReturn } from "../../composables/defineForm";
+import { useContainerWidth } from "../../composables/useContainerWidth";
 import type { FieldDefinition, FormTab, LabelCols, MaybeFn } from "../../types";
 import {
     resolvePredicate as resolvePredicateFor,
@@ -235,12 +237,34 @@ interface Props {
     cardTabs?: boolean;
 
     /**
-     * Form-wide field layout: "vertical" (default, label above input) or
-     * "horizontal" (label left, input right). Overridable per-field via
-     * `field.layout`. A field with `span: true` always renders full-width,
-     * regardless of layout.
+     * Form-wide field layout:
+     *
+     * - `"vertical"` (default) — label above input, always.
+     * - `"horizontal"` — label left, input right, always.
+     * - `"auto"` — horizontal when the form's **own container** is at least
+     *   `layoutThreshold` px wide, vertical below that. Container-driven, not
+     *   viewport-driven: a page narrowed by the dashboard sidebar, or a form
+     *   inside a modal, stacks even though the window is wide (which no
+     *   Bootstrap media query can see).
+     *
+     * Overridable per-field via `field.layout`. A field with `span: true`
+     * always renders full-width, regardless of layout.
      */
-    layout?: "vertical" | "horizontal";
+    layout?: "vertical" | "horizontal" | "auto";
+
+    /**
+     * Container width (px) at or above which `layout: "auto"` goes horizontal.
+     * Ignored for the explicit `"vertical"`/`"horizontal"` layouts.
+     *
+     * Default 640, measured rather than guessed: with the default 3-column
+     * label the label's text area is `containerWidth / 4 - 18` px, so 640 gives
+     * it 142px — enough for a ~20-character label ("Unit price (ex VAT)"
+     * measures 128px at the theme's label font) to stay on one line, with the
+     * control column still 474px. Below ~584px that label starts wrapping,
+     * which is the cramped-label symptom this exists to avoid. Raise it if your
+     * labels run longer, or lower `labelCols` instead.
+     */
+    layoutThreshold?: number;
 
     /**
      * Label column width for horizontal layout (mirrors BFormGroup's
@@ -258,6 +282,7 @@ const props = withDefaults(defineProps<Props>(), {
     card: false,
     cardTabs: true,
     layout: "vertical",
+    layoutThreshold: 640,
 });
 
 const emit = defineEmits<{
@@ -270,6 +295,55 @@ const slots = defineSlots<Record<string, (props: any) => any>>();
 /** v-model for the active tab index. */
 const activeTab = defineModel<number>("activeTab", { default: 0 });
 
+// ————————————————— container-driven layout (`layout: "auto"`)
+
+const formRoot = ref<ComponentPublicInstance | HTMLElement | null>(null);
+
+/**
+ * The `<form>` element BForm renders. A template ref on a component yields the
+ * component instance, so unwrap `$el` — and tolerate either shape rather than
+ * assuming one, so a future BForm change (or a functional re-implementation)
+ * can't silently leave us observing nothing.
+ */
+function resolveFormElement(): HTMLElement | null {
+    const rootValue = formRoot.value;
+    if (rootValue === null || rootValue === undefined) return null;
+    if (rootValue instanceof HTMLElement) return rootValue;
+    const element = (rootValue as ComponentPublicInstance).$el;
+    return element instanceof HTMLElement ? element : null;
+}
+
+// Observe ONLY in auto mode. Returning null for the other layouts means no
+// ResizeObserver is ever attached for the (overwhelmingly common) explicit
+// layouts — existing consumers pay nothing and behave identically.
+const { isBelow: containerIsNarrow } = useContainerWidth(
+    () => (props.layout === "auto" ? resolveFormElement() : null),
+    {
+        // Getter, so a consumer binding `:layout-threshold` to something
+        // reactive re-evaluates instead of latching the mount-time value.
+        threshold: () => props.layoutThreshold,
+        // Guard against an observer feedback loop at the boundary: the vertical
+        // layout is TALLER, so a form inside an `overflow:auto` ancestor can
+        // gain a scrollbar when it stacks, shrinking its own container by
+        // ~15-17px — straight back over the threshold, and it flips forever.
+        // A band wider than any scrollbar (24px) makes the crossing one-way
+        // until the container genuinely grows.
+        hysteresis: 24,
+    },
+);
+
+/**
+ * The layout actually rendered. `vertical`/`horizontal` pass through
+ * unconditionally (unchanged behaviour); `auto` resolves from the measured
+ * container width, defaulting to `vertical` before the first measurement and
+ * under SSR — the stacked layout is legible at any width, so it is the safe
+ * thing to render when the width is unknown.
+ */
+const resolvedLayout = computed<"vertical" | "horizontal">(() => {
+    if (props.layout !== "auto") return props.layout;
+    return containerIsNarrow.value ? "vertical" : "horizontal";
+});
+
 // ————————————————— resolve form / fields (accept useForm or defineForm)
 
 function isDefineForm(

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

@@ -163,6 +163,35 @@
                                     <div class="fw-semibold">{{ headerLabel(field, label) }}</div>
                                     <small v-if="field.hint" class="text-muted d-block" style="font-weight: normal;">{{ field.hint }}</small>
                                 </div>
+
+                                <!-- ADDITIVE per-column header content (#99), rendered
+                                     INSIDE DXTable's own header cell rather than as a
+                                     `head(<key>)` override — an override would silently
+                                     drop the sort indicator and the field hint, which is
+                                     exactly why `head(...)` is not forwarded (see
+                                     `isTableSlot`). Placed after the label block and
+                                     BEFORE the sort indicator so a period total sits at
+                                     the top-right of the text area without displacing the
+                                     sort arrows, and lands in the same place whether or
+                                     not the column happens to be sortable. The wrapper is
+                                     only emitted when the slot exists, so a table without
+                                     one renders exactly as before. -->
+                                <div
+                                    v-if="$slots[`head-end(${field.key})`]"
+                                    class="dx-head-end flex-shrink-0 text-end"
+                                >
+                                    <!--
+                                      @slot 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.
+                                      @binding {object} field The column's field definition.
+                                      @binding {string} label The column's resolved header label.
+                                    -->
+                                    <slot
+                                        :name="`head-end(${field.key})`"
+                                        :field="field"
+                                        :label="headerLabel(field, label)"
+                                    />
+                                </div>
+
                                 <div v-if="field.sortable" class="sort-indicator text-muted flex-shrink-0" style="font-size: 0.75rem; line-height: 1.1; display: flex; flex-direction: column; align-items: center;">
                                     <span :style="{ opacity: getFieldSortState(field.key) === 'asc' ? 1 : 0.3 }">▲</span>
                                     <span :style="{ opacity: getFieldSortState(field.key) === 'desc' ? 1 : 0.3 }">▼</span>
@@ -359,6 +388,22 @@ export interface TableField {
     filterOptions?: FilterOption[];
     filterPlaceholder?: string;
 
+    /**
+     * For a `select` filter on a **client-side** table: derive the dropdown's
+     * options from the distinct values present in the loaded rows. Defaults to
+     * `true` — with no `filterOptions` and no server `filterValues` the
+     * alternative is an empty dropdown, which can only ever be a bug.
+     *
+     * Set `false` to opt out (e.g. a column whose raw values are opaque ids you
+     * would rather label yourself via `filterOptions`).
+     *
+     * Explicit `filterOptions` and server-supplied `filterValues` still WIN, in
+     * that order. Provider/API and Inertia modes ignore this flag: they only
+     * ever hold one page of rows, so there is no complete value set to derive
+     * from (see `getFieldFilterOptions`).
+     */
+    deriveFilterOptions?: boolean;
+
     /**
      * Fixed width for this column, applied via a `<colgroup>` `<col>`. A number
      * is treated as pixels (`200` → `200px`); a string is used verbatim
@@ -559,6 +604,18 @@ export interface Props<TItem = any> {
      * borderless variant — the same header, filter row, table and pagination
      * rendered directly on the page background (no card border/shadow), for
      * data-heavy admin index pages that read as busy inside a card.
+     *
+     * The table renders FLUSH to the card border (rows and stripes reach the
+     * edge) while the header and pagination stay padded. Only the table region
+     * is rounded to follow the card's corners — the card itself does not clip
+     * (#166), so a `position: absolute` popover you render into `#header` or
+     * any other slot is free to overhang the card.
+     *
+     * The one place content is still clipped is INSIDE the table: Bootstrap's
+     * `.table-responsive` is a horizontal scroll container, so an overlay in a
+     * `cell(<key>)` slot is bounded by it. Teleport it (bvn's own menus already
+     * do — `DDropdown` teleports to `<body>`, the column-filter menus are
+     * `fixed`), or pass `:responsive="false"`.
      */
     card?: boolean;
 
@@ -585,8 +642,13 @@ export interface Props<TItem = any> {
      * **"horizontal"** to match the Omni Tend form convention (a raw modal form
      * previously fell back to DXForm's vertical default, which looked out of
      * place next to horizontal page forms). Pass `"vertical"` to opt out.
+     *
+     * `"auto"` hands the decision to `DXForm`'s container-width observer, which
+     * measures the FORM rather than the window — so a modal narrowed by its own
+     * breakpoint stacks to vertical even on a wide viewport, where a media query
+     * would still report "plenty of room". See `useContainerWidth`.
      */
-    editLayout?: 'vertical' | 'horizontal';
+    editLayout?: 'vertical' | 'horizontal' | 'auto';
 
     /**
      * Label column width for the edit modal's horizontal layout, forwarded to
@@ -1020,16 +1082,7 @@ const clientSideFilteredItems = computed<T[]>(() => {
         return filterKeys.every(key => {
             // Resolve by the FILTER key, which may differ from the column's key.
             const field = props.fields.find(f => filterKeyFor(f) === key);
-            // `filterKey` names the param the SERVER filters on; a local row may
-            // not carry it at all (a `customer_name` row filtered on
-            // `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 && hasFieldValue(item, key)
-                    ? fieldValueOf(item, key)
-                    : fieldValueOf(item, field?.key ?? key);
+            const itemValue = clientSideFilterValueOf(item, field, key);
 
             const matchesCandidate = (candidate: string): boolean => {
                 // The "no value" option (e.g. Unassigned) is the one filter that
@@ -1151,6 +1204,28 @@ const hasFieldValue = (item: unknown, key: string): boolean => {
     return getByPath(item as Record<string, any>, key) !== undefined;
 };
 
+/*
+ * The value a client-side filter compares against, for one row and one column.
+ *
+ * `filterKey` names the param the SERVER filters on; a local row may not carry
+ * it at all (a `customer_name` row filtered on `customer_id`). Read 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).
+ *
+ * Extracted so the client-side row filter and the DERIVED select options (see
+ * `derivedFilterOptions`) resolve values through exactly the same rule — a
+ * derived option must never be a value the filter then fails to match.
+ */
+const clientSideFilterValueOf = (
+    item: unknown,
+    field: TableField | undefined,
+    filterKey: string,
+): any =>
+    field && hasFieldValue(item, filterKey)
+        ? fieldValueOf(item, filterKey)
+        : fieldValueOf(item, field?.key ?? filterKey);
+
 /*
  * 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
@@ -1235,6 +1310,115 @@ const filterAllLabelFor = (field: TableField): string =>
 const headerLabel = (field: TableField, slotLabel?: string): string =>
     field.label !== undefined ? field.label : (slotLabel || field.key);
 
+/**
+ * A select filter option's LABEL, honouring the column's own value→label
+ * formatting so the dropdown reads the way the column does (a `formatter`
+ * turning `19.99` into `$19.99`). The option's `value` stays RAW — that is what
+ * the client-side filter compares against (`String(itemValue) === candidate`),
+ * so formatting must never leak into it.
+ *
+ * `formatter` is bootstrap-vue-next's field formatter, `(value, key, item)`, and
+ * its first argument is by contract the value of `field.key` — the DISPLAYED
+ * column value. That matters when `filterKey` names a different property: the
+ * option's value must stay the FILTER value (that is what the row filter
+ * compares), but the formatter must still be handed the display value it was
+ * written against. Passing the filter value here fed a `customer` column's
+ * `(customer) => customer.name` formatter a numeric `customer_id`, which
+ * mislabels at best and throws at worst.
+ */
+const formattedFilterLabel = (field: TableField, item: unknown): string | null => {
+    if (typeof field.formatter !== 'function') return null;
+    const formatted = field.formatter(fieldValueOf(item, field.key), field.key, item);
+    if (formatted === null || formatted === undefined) return null;
+    return String(formatted);
+};
+
+/**
+ * Client-side auto-derived `filter: "select"` options, keyed by field key.
+ *
+ * Without this a client-side select column with no `filterOptions` and no
+ * server `filterValues` rendered an EMPTY dropdown — dead UI that can only be a
+ * bug — so this is on by default (opt out per column with
+ * `deriveFilterOptions: false`).
+ *
+ * It derives from `resolvedItems` (the FULL loaded row set) and deliberately
+ * NOT from `clientSideFilteredItems` or `clientSidePaginatedItems`:
+ *  - filtered set → picking a value would collapse the dropdown to that one
+ *    value, and the user could never get back to any other one;
+ *  - current page → the offered values would silently change as you page.
+ * Being a computed over `props.fields` + `resolvedItems` only, it is also
+ * structurally incapable of depending on the active filters — the cache is the
+ * guard, not just the comment.
+ */
+const derivedFilterOptions = computed<Record<string, FilterOption[]>>(() => {
+    // Only client-side mode has the complete row set. Provider/API and Inertia
+    // hold one page, so they take their options from the server instead.
+    if (!isClientSideMode.value) return {};
+
+    const rows = resolvedItems.value;
+    if (!rows || rows.length === 0) return {};
+
+    const optionsByFieldKey: Record<string, FilterOption[]> = {};
+
+    for (const field of props.fields) {
+        if (field.filter !== 'select') 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.
+        if (field.filterOptions && field.filterOptions.length > 0) continue;
+
+        const filterKey = filterKeyFor(field);
+
+        // Distinct values keyed by their STRING form, because that is exactly
+        // what the client-side select filter compares — so `1` and `"1"` are one
+        // option, and every option offered is one the filter can match. The
+        // first row carrying a value is kept alongside it, as the `item`
+        // argument the column's formatter expects.
+        const firstRowByValue = new Map<string, { rawValue: any; item: unknown }>();
+
+        // Candidates the filter reads as CONTROL values rather than data, so a
+        // row whose value collides with one can never be matched by selecting it
+        // (`handleSelectFilterChange` turns the "all" sentinel back into "no
+        // filter", and the null sentinel is intercepted upstream of the select's
+        // exact-match arm, where it means "has no value"). Offering such an
+        // option would be a dropdown entry that returns zero rows, and the null
+        // one would also duplicate the `filterNullText` entry's value.
+        const reservedCandidates = new Set<string>([FILTER_ALL_VALUE]);
+        if (field.filterNullText) reservedCandidates.add(filterNullValueFor(field));
+
+        for (const item of rows) {
+            const value = clientSideFilterValueOf(item, field, filterKey);
+            // null / undefined / '' are skipped deliberately: "has no value" is
+            // already a first-class, LABELLED option via `filterNullText`, and
+            // an unlabelled blank row in the list would be unusable.
+            if (value === null || value === undefined || value === '') continue;
+            const stringValue = String(value);
+            if (reservedCandidates.has(stringValue)) continue;
+            if (!firstRowByValue.has(stringValue)) {
+                firstRowByValue.set(stringValue, { rawValue: value, item });
+            }
+        }
+
+        const entries = [...firstRowByValue.entries()];
+
+        // Stable, human ordering: numeric when both values are numbers,
+        // otherwise a locale compare — the same rule the client-side sort uses,
+        // with `numeric: true` so "Item 2" precedes "Item 10".
+        entries.sort(([leftText, left], [rightText, right]) =>
+            typeof left.rawValue === 'number' && typeof right.rawValue === 'number'
+                ? left.rawValue - right.rawValue
+                : leftText.localeCompare(rightText, undefined, { numeric: true, sensitivity: 'base' }),
+        );
+
+        optionsByFieldKey[field.key] = entries.map(([stringValue, { item }]) => ({
+            value: stringValue,
+            text: formattedFilterLabel(field, item) ?? stringValue,
+        }));
+    }
+
+    return optionsByFieldKey;
+});
+
 const getFieldFilterOptions = (field: TableField): FilterOption[] => {
     const options: FilterOption[] = [];
 
@@ -1274,6 +1458,15 @@ const getFieldFilterOptions = (field: TableField): FilterOption[] => {
         return [...options, ...serverValues.map(value => ({ value, text: value }))];
     }
 
+    // Last resort, CLIENT-SIDE only: the distinct values present in the loaded
+    // rows. Precedence is deliberate — explicit `filterOptions`, then the
+    // server's `filterValues`, then what the data itself says. See
+    // `derivedFilterOptions` for why it derives from the unfiltered row set.
+    const derived = derivedFilterOptions.value[field.key];
+    if (derived && derived.length > 0) {
+        return [...options, ...derived];
+    }
+
     // No values to choose from — don't offer a lone "All x" that filters nothing.
     return [];
 };
@@ -1549,7 +1742,12 @@ const shouldShowPerPageSelector = computed(() => {
     return total >= smallestOption;
 });
 
-// Detect which fields need server filter values
+// Detect which fields need server filter values.
+//
+// Client-side derived options (`derivedFilterOptions`) deliberately do NOT
+// shrink this list: it is only ever read by `internalProvider`, i.e. API mode,
+// and `isProviderMode` requires `!resolvedClientSide` — the two modes are
+// 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))
@@ -1956,6 +2154,12 @@ const refresh = () => {
  * - `head(<key>)` — DXTable draws its own column headers (sort indicators,
  *   field hints). Forwarding a consumer's would silently drop those.
  * - `thead-top`   — DXTable renders the inline filter row there.
+ *
+ * `head-end(<key>)` is DXTable's OWN additive header slot (#99) and is likewise
+ * not forwarded: the inner table has no such slot, and the prefixes below are
+ * matched with `startsWith`, so it must not begin with `cell(`/`foot(` either —
+ * `head-end(` satisfies both. It is also excluded from `tableSlotSignature`
+ * (which filters on `isTableSlot`), so adding one never remounts the table.
  */
 const TABLE_SLOT_PREFIXES = ['cell(', 'foot('];
 const TABLE_SLOT_NAMES = new Set([

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

@@ -208,8 +208,13 @@ interface Props {
     pendingAction: 'save' | 'delete' | null;
     /** Delete endpoint — gates the Delete button. */
     deleteUrl?: string;
-    /** Field layout forwarded to the modal's DXForm (defaults handled upstream). */
-    layout?: 'vertical' | 'horizontal';
+    /**
+     * Field layout forwarded to the modal's DXForm (defaults handled upstream).
+     * Includes `"auto"`, which lets the form stack to vertical when the MODAL is
+     * narrow even though the viewport is wide — the container-query case a
+     * viewport media query cannot see.
+     */
+    layout?: 'vertical' | 'horizontal' | 'auto';
     /** Label column width forwarded to DXForm (horizontal layout). */
     labelCols?: LabelCols;
     /** Wrap the modal form in a card (opt-in — off by default). */