@omnitend/dashboard-for-laravel 0.43.0 → 0.45.0

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

@@ -0,0 +1,232 @@
+<!--
+  @component DXFormErrorSummary
+  Lists everything the last failed submit of a `useForm` returned: a heading,
+  then one row per validation message with a readable label ("Price (line 1):
+  Must be positive."). The heading is `title` ("Couldn't save. Please
+  check:") when the failure has field errors, and the server's message when
+  it has none (a message-only 422, a 500, a network failure), since then the
+  message is all there is. Built from `form.submitFailure`, so it survives
+  field edits and `clearError`, and disappears when the next submit starts or
+  one succeeds. Renders nothing before a failure. A row whose key belongs to a
+  visible field is a button that emits `select-target`, for the host to select
+  the field's tab and focus it; a key no visible field owns is listed as plain
+  text, after the owned rows, under `otherTitle` ("Other problems") when both
+  kinds are present. Place it next to the submit control.
+-->
+<template>
+    <!-- A real element owns the class: DAlert's root is a transition, so a
+         class on it is not a reliable host for the theme rules. BAlert
+         supplies role="alert" + aria-live="assertive"; keying it by the
+         failure count remounts it, so every new failure is announced once. -->
+    <div v-if="failure" class="dx-form-error-summary">
+        <DAlert :key="resolvedForm.failedSubmitCount" variant="danger">
+            <p class="dx-form-error-summary__message">{{ heading }}</p>
+            <!-- Rows a field owns (buttons that go to it), then rows no field
+                 owns (text). The sub-heading only says "these are the rest"
+                 when there is a first list for them to be the rest of. A
+                 <p>, not a heading element: it must not enter the page
+                 outline. -->
+            <template v-for="group in groups" :key="group.key">
+                <p
+                    v-if="group.title !== null"
+                    class="dx-form-error-summary__other-title"
+                >
+                    {{ group.title }}
+                </p>
+                <ul class="dx-form-error-summary__list">
+                    <li
+                        v-for="row in group.rows"
+                        :key="row.id"
+                        class="dx-form-error-summary__item"
+                    >
+                        <button
+                            v-if="row.fieldKey !== null"
+                            type="button"
+                            class="dx-form-error-summary__target"
+                            :data-dx-error-key="row.errorKey"
+                            @click="selectRow(row)"
+                        >
+                            {{ row.text }}
+                        </button>
+                        <span v-else :data-dx-error-key="row.errorKey">{{ row.text }}</span>
+                    </li>
+                </ul>
+            </template>
+        </DAlert>
+    </div>
+</template>
+
+<script setup lang="ts">
+import { computed } from "vue";
+import DAlert from "../base/DAlert.vue";
+import type { UseFormReturn } from "../../composables/useForm";
+import type { DefineFormReturn } from "../../composables/defineForm";
+import type { FieldDefinition, FormTab } from "../../types";
+import {
+    resolveErrorTargets,
+    type ErrorTarget,
+} from "../../utils/formErrorTargets";
+
+/** What a summary row points at (emitted by `select-target`). */
+export interface ErrorSummarySelection {
+    /** The owning field's key. */
+    fieldKey: string;
+    /** The tab holding that field, or `null` in a flat form. */
+    tabKey: string | null;
+    /** The error key as the server sent it. */
+    errorKey: string;
+}
+
+interface Props {
+    /** The form: a `useForm` return or a `defineForm` return. */
+    form: UseFormReturn<any> | DefineFormReturn<any>;
+    /** Field definitions (optional when `form` is a defineForm return). */
+    fields?: FieldDefinition[];
+    /** The form's tabs, so rows follow tab order and know their tab. */
+    tabs?: FormTab[];
+    /**
+     * Extra context merged under the form data when evaluating `when` and
+     * function labels, as on DXForm.
+     */
+    context?: Record<string, any>;
+    /**
+     * Field visibility, replacing the default (`when`/`show` against form
+     * data + `context`). A host form passes its own predicate so the summary
+     * agrees with what it renders.
+     */
+    isFieldVisible?: (field: FieldDefinition) => boolean;
+    /** Tab visibility, replacing the default (the tab's `when`). */
+    isTabVisible?: (tab: FormTab) => boolean;
+    /**
+     * A field's label, replacing the default (its `label`, resolved against
+     * `labelModel`: the form model, or the row for a repeater sub-field).
+     */
+    resolveLabel?: (
+        field: FieldDefinition,
+        labelModel: Record<string, any>,
+    ) => string | null | undefined;
+    /**
+     * Rows already resolved by the host (from `resolveErrorTargets` over
+     * `form.submitFailure.errors`). When given, the summary lists these and
+     * resolves nothing itself; the message still comes from
+     * `form.submitFailure`, and nothing renders while that is null.
+     */
+    targets?: ErrorTarget[] | null;
+    /**
+     * The heading when the failure has at least one field error. The
+     * server's own message is not used then: Laravel's default 422 message
+     * is the first error plus "(and N more errors)", which repeats the first
+     * row. A failure with no field errors (a message-only 422, a 500, a
+     * network failure) keeps the server's message as the heading, as it is
+     * the only information.
+     */
+    title?: string;
+    /**
+     * The sub-heading over the rows no visible field owns, listed after the
+     * owned rows. Shown only when there are both kinds; when no row is owned
+     * they are listed under the heading alone.
+     */
+    otherTitle?: string;
+}
+
+const props = withDefaults(defineProps<Props>(), {
+    title: "Couldn't save. Please check:",
+    otherTitle: "Other problems",
+});
+
+const emit = defineEmits<{
+    /** A row was clicked: select `tabKey` (if any) and focus `fieldKey`. */
+    "select-target": [selection: ErrorSummarySelection];
+}>();
+
+function isDefineForm(value: Props["form"]): value is DefineFormReturn<any> {
+    return (
+        !!value &&
+        typeof value === "object" &&
+        "form" in value &&
+        "fields" in value &&
+        !("data" in value)
+    );
+}
+
+const resolvedForm = computed<UseFormReturn<any>>(() =>
+    isDefineForm(props.form) ? props.form.form : props.form,
+);
+
+const resolvedFields = computed<FieldDefinition[]>(() => {
+    if (props.fields) return props.fields;
+    if (isDefineForm(props.form)) return props.form.fields;
+    return [];
+});
+
+const failure = computed(() => resolvedForm.value.submitFailure ?? null);
+
+const targets = computed<ErrorTarget[]>(() => {
+    if (!failure.value) return [];
+    if (props.targets) return props.targets;
+    return resolveErrorTargets(failure.value.errors, {
+        fields: resolvedFields.value,
+        tabs: props.tabs,
+        model: { ...(props.context ?? {}), ...resolvedForm.value.data },
+        isFieldVisible: props.isFieldVisible,
+        isTabVisible: props.isTabVisible,
+        resolveLabel: props.resolveLabel,
+    });
+});
+
+interface Row {
+    id: string;
+    text: string;
+    errorKey: string;
+    fieldKey: string | null;
+    tabKey: string | null;
+}
+
+const rows = computed<Row[]>(() =>
+    targets.value.flatMap((target) =>
+        target.lines.map((text, index) => ({
+            id: `${target.errorKey}#${index}`,
+            text,
+            errorKey: target.errorKey,
+            fieldKey: target.fieldKey,
+            tabKey: target.tabKey,
+        })),
+    ),
+);
+
+const heading = computed(() =>
+    rows.value.length > 0 ? props.title : (failure.value?.message ?? ""),
+);
+
+interface RowGroup {
+    key: "owned" | "other";
+    /** The sub-heading above the list, or `null` for none. */
+    title: string | null;
+    rows: Row[];
+}
+
+/** Owned rows, then unowned ones (labelled only when both are present). */
+const groups = computed<RowGroup[]>(() => {
+    const owned = rows.value.filter((row) => row.fieldKey !== null);
+    const other = rows.value.filter((row) => row.fieldKey === null);
+    const result: RowGroup[] = [];
+    if (owned.length > 0) result.push({ key: "owned", title: null, rows: owned });
+    if (other.length > 0) {
+        result.push({
+            key: "other",
+            title: owned.length > 0 ? props.otherTitle : null,
+            rows: other,
+        });
+    }
+    return result;
+});
+
+function selectRow(row: Row): void {
+    if (row.fieldKey === null) return;
+    emit("select-target", {
+        fieldKey: row.fieldKey,
+        tabKey: row.tabKey,
+        errorKey: row.errorKey,
+    });
+}
+</script>

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

@@ -17,12 +17,18 @@
 -->
 <template>
   <!-- Full replacement slot bypasses DXField entirely (mirrors tab-content):
-       also supersedes field-before/field-after for the same key. -->
+       also supersedes field-before/field-after for the same key. Rendered
+       as-is, with no wrapper (#194): `targetAttrs` is the marker DXForm
+       looks for to scroll to and focus a field after a failed submit, and
+       the consumer opts in by binding it (`v-bind="targetAttrs"`) on the
+       element holding the control. DXForm looks the marker up when it
+       needs it (a summary click, auto-scroll), never ahead of time. -->
   <slot
     v-if="$slots[`field(${field.key})`]"
     :name="`field(${field.key})`"
     :field="field"
     :model="model"
+    :targetAttrs="targetAttrs"
   />
   <template v-else>
     <!-- Content inserted directly above the field. -->
@@ -52,7 +58,7 @@
 </template>
 
 <script setup lang="ts">
-import { useSlots } from "vue";
+import { computed, useSlots } from "vue";
 import DXField from "./DXField.vue";
 import type { UseFormReturn } from "../../composables/useForm";
 import type { FieldDefinition, LabelCols } from "../../types";
@@ -73,6 +79,9 @@ interface Props {
 const props = defineProps<Props>();
 const slots = useSlots();
 
+/** What a `field(<key>)` slot binds to opt in to scroll/focus (#194). */
+const targetAttrs = computed(() => ({ "data-dx-field-key": props.field.key }));
+
 /**
  * Map a DXField slot name to this field's keyed parent slot, when present.
  * A plain function (re-read each render) rather than a computed, so a slot the

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

@@ -1,12 +1,16 @@
 <template>
+  <!-- The status box is there from the start, holding the loader's space
+       with its contents hidden (theme.scss); the delay only reveals them.
+       Content added to a live region already in the page is announced,
+       where a region inserted with its text can be missed. -->
   <div
-    v-if="isVisible"
-    class="dx-loading text-center text-muted py-5"
+    class="dx-loading py-5"
+    :class="{ 'dx-loading--shown': isVisible }"
     role="status"
     aria-live="polite"
   >
-    <DSpinner variant="primary" aria-hidden="true" />
-    <div class="mt-2">{{ text }}</div>
+    <DSpinner small aria-hidden="true" />
+    <p class="dx-loading__text">{{ text }}</p>
   </div>
 </template>
 
@@ -14,14 +18,20 @@
 import { onBeforeUnmount, onMounted, ref } from "vue";
 import DSpinner from "../base/DSpinner.vue";
 
+// Styles (one line, grey, a slow sweep across the text, a fade-in, contents
+// hidden until `.dx-loading--shown`) are global in theme.scss under
+// `.dx-loading`, with `--dx-loading-*` tokens.
 const props = withDefaults(
   defineProps<{
     text?: string;
+    /** Milliseconds to wait before showing anything. Most loads finish
+     *  sooner, and one that has already taken this long is likely to take
+     *  longer, so a quick load never flashes a loader. */
     delay?: number;
   }>(),
   {
     text: "Loading…",
-    delay: 300,
+    delay: 600,
   },
 );
 
@@ -29,14 +39,11 @@ const isVisible = ref(false);
 let showTimer: ReturnType<typeof setTimeout> | undefined;
 
 onMounted(() => {
-  if (props.delay <= 0) {
-    isVisible.value = true;
-    return;
-  }
-
+  // Always a timer, even for no delay: the empty status box must reach the
+  // page a task before its contents, or the announcement can be missed.
   showTimer = setTimeout(() => {
     isVisible.value = true;
-  }, props.delay);
+  }, Math.max(props.delay, 0));
 });
 
 onBeforeUnmount(() => {

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

@@ -150,6 +150,7 @@ import type { UseFormReturn } from "../../composables/useForm";
 import type { FieldDefinition } from "../../types";
 import { getByPath, setByPath } from "../../utils/objectPath";
 import { resolveFieldDefault } from "../../utils/formSchema";
+import { humaniseErrorKey } from "../../utils/formErrorTargets";
 
 interface Props {
     /** Form instance owning the repeater array */
@@ -177,12 +178,37 @@ const minItems = computed(() => props.field.minItems ?? 0);
 const maxItems = computed(() => props.field.maxItems);
 const softDeleteKey = computed(() => props.field.softDeleteKey);
 
-/** Column header text for a sub-field. No specific row context exists for a
- *  header, so a function-valued label resolves against the outer model. */
+/**
+ * The model a column header's function label is called with. Row fields
+ * resolve their labels against the ROW (as does the error summary), so a
+ * header uses the first visible row, layered over the outer model so a label
+ * that reads outer context (a currency on the parent form) still works. With
+ * no rows it is the outer model alone.
+ */
+const headerModel = computed<Record<string, any>>(() => {
+    const firstRow = visibleRows.value[0]?.row;
+    return {
+        ...(props.model ?? {}),
+        ...(firstRow !== null && typeof firstRow === "object" ? firstRow : {}),
+    };
+});
+
+/** Column header text for a sub-field. A label function that throws (a row
+ *  property it expects is missing) or returns nothing falls back to the
+ *  humanised key, the same fallback the error summary uses, so a header can
+ *  never break the table. */
 function headerLabel(subField: FieldDefinition): string {
     const label = subField.label;
-    if (typeof label === "function") return label(props.model ?? {});
-    return label || subField.key;
+    if (typeof label !== "function") return label || subField.key;
+    let resolved: unknown;
+    try {
+        resolved = label(headerModel.value);
+    } catch {
+        resolved = undefined;
+    }
+    return typeof resolved === "string" && resolved.trim() !== ""
+        ? resolved
+        : humaniseErrorKey(subField.key);
 }
 
 // ————————————————— table/cards responsive fallback (#68 follow-up)

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

@@ -35,10 +35,7 @@
                         {{ error || apiError }}
                     </div>
 
-                    <div v-if="effectiveBusy && !isProviderMode" class="text-center py-5">
-                        <DSpinner variant="primary" />
-                        <p class="mt-2">{{ loadingText }}</p>
-                    </div>
+                    <DXLoading v-if="effectiveBusy && !isProviderMode" :text="loadingText" />
 
                     <!-- One table for all three data modes. The modes differ only
                          in a few bound props, supplied by `tableModeBindings`, so
@@ -140,7 +137,7 @@
                                 <DFormSelect
                                     v-else-if="field.filter === 'select-native'"
                                     :model-value="nativeSelectFilterValue(field)"
-                                    :options="getFieldFilterOptions(field) as unknown as Record<string, unknown>[]"
+                                    :options="getFieldFilterOptions(field)"
                                     size="sm"
                                     @update:model-value="handleSelectFilterChange(field, $event)"
                                 />
@@ -292,6 +289,8 @@
             :save-text="saveText"
             :create-text="createText"
             :delete-text="deleteText"
+            :error-summary-title="errorSummaryTitle"
+            :error-summary-other-title="errorSummaryOtherTitle"
             @save="handleEditSave"
             @cancel="handleEditCancel"
             @delete="handleDelete"
@@ -324,7 +323,7 @@ import DContainer from "../base/DContainer.vue";
 import DRow from "../base/DRow.vue";
 import DCol from "../base/DCol.vue";
 import DXTableShell from "./DXTableShell.vue";
-import DSpinner from "../base/DSpinner.vue";
+import DXLoading from "./DXLoading.vue";
 import DTable from "../base/DTable.vue";
 import DFormInput from "../base/DFormInput.vue";
 import DFormSelect from "../base/DFormSelect.vue";
@@ -709,6 +708,19 @@ export interface Props<TItem = any> {
     /** Override the modal's Delete button label (default: "Delete {item}"). */
     deleteText?: string;
 
+    /**
+     * Heading of the modal's failed-save summary when the failure has field
+     * errors (default "Couldn't save. Please check:"). A failure with none
+     * is headed by the server's message instead.
+     */
+    errorSummaryTitle?: string;
+
+    /**
+     * Sub-heading over the summary rows no edit field owns (default "Other
+     * problems"), shown only when some rows ARE owned.
+     */
+    errorSummaryOtherTitle?: string;
+
     /** API endpoint pattern for updates (e.g., "/api/products/:id") */
     editUrl?: string;
 
@@ -826,6 +838,16 @@ export interface Props<TItem = any> {
      */
     rowClickable?: (item: TItem, index: number) => boolean;
 
+    /**
+     * Whether clicking a row opens the edit modal (when `editFields` are set).
+     * Defaults to `true`. Set `false` when `editFields` exist only for the
+     * create modal (`openCreate()` / the create button) and a row click does
+     * something else, such as opening the record's own page from `row-clicked`:
+     * the row then emits `row-clicked` without also opening the edit modal, and
+     * only a `row-clicked` listener makes rows look clickable (#200).
+     */
+    editOnRowClick?: boolean;
+
     /** Enable client-side filtering, sorting, and pagination on items array */
     clientSide?: boolean;
 
@@ -886,6 +908,7 @@ const props = withDefaults(defineProps<Props<T>>(), {
     footClone: false,
     showEmpty: true,
     fixedLayout: false,
+    editOnRowClick: true,
 });
 
 const emit = defineEmits<{
@@ -1038,9 +1061,12 @@ const isControlled = {
  * The cursor and hover affordance follow from that — DXTable already knows,
  * so consumers shouldn't have to reach into `:deep(tbody tr)` to say it (#107).
  * The listener case was the gap: only `editFields` used to count.
+ * `editFields` count only while a row click opens them (`editOnRowClick`, #200).
  */
 const rowsAreInteractive = computed(
-    () => (props.editFields?.length ?? 0) > 0 || hasListener('rowClicked'),
+    () =>
+        (props.editOnRowClick && (props.editFields?.length ?? 0) > 0) ||
+        hasListener('rowClicked'),
 );
 
 /**
@@ -2451,7 +2477,8 @@ const getFieldSortState = (fieldKey: string) => {
 };
 
 // Handle row click. Emits `rowClicked` regardless (the seam consumers listen
-// on), then asks the editor to open — a no-op unless `editFields` are set.
+// on), then asks the editor to open — a no-op unless `editFields` are set, and
+// skipped when the consumer turned edit-on-click off (#200).
 const handleRowClick = (item: T, index: number, event: MouseEvent) => {
     // A row the consumer marked non-actionable doesn't look clickable, so it
     // must not BE clickable either — otherwise a click that looks dead quietly
@@ -2459,7 +2486,9 @@ const handleRowClick = (item: T, index: number, event: MouseEvent) => {
     if (props.rowClickable && !props.rowClickable(item, index)) return;
 
     emit('rowClicked', item, index, event);
-    editor.openEdit(item);
+    if (props.editOnRowClick) {
+        editor.openEdit(item);
+    }
 };
 
 defineExpose({

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

@@ -55,6 +55,7 @@
             :aria-busy="loading ? 'true' : undefined"
         >
             <DXForm
+                ref="innerForm"
                 :key="formInstanceKey"
                 :active-tab="activeTab"
                 :form="form"
@@ -66,6 +67,7 @@
                 :card-tabs="false"
                 :context="item ?? undefined"
                 :show-submit="false"
+                error-summary="external"
                 @update:active-tab="emit('update:activeTab', $event)"
                 @submit="emit('save')"
             >
@@ -154,6 +156,24 @@
         </fieldset>
 
         <template #footer>
+            <!-- What the last failed save returned, beside the Save button it
+                 answers (#194). The inner DXForm shows no summary or alert of
+                 its own while this one lists a failure
+                 (`error-summary="external"`; `false` would bring its top
+                 alert back), so a failure shows one alert. Rows come from the inner form's own resolution, and a
+                 row click drives the inner form's tab and focus. -->
+            <DXFormErrorSummary
+                v-if="form"
+                class="dx-edit-error-summary w-100"
+                :form="form"
+                :fields="fields"
+                :tabs="tabs"
+                :context="item ?? undefined"
+                :targets="innerForm?.errorTargets ?? null"
+                :title="errorSummaryTitle"
+                :other-title="errorSummaryOtherTitle"
+                @select-target="innerForm?.focusErrorTarget($event)"
+            />
             <div class="d-flex justify-content-between w-100">
                 <div>
                     <DButton
@@ -187,11 +207,12 @@
 </template>
 
 <script setup lang="ts">
-import { computed, useSlots } from "vue";
+import { computed, ref, useSlots } from "vue";
 import DModal from "../base/DModal.vue";
 import DButton from "../base/DButton.vue";
 import DSpinner from "../base/DSpinner.vue";
 import DXForm from "./DXForm.vue";
+import DXFormErrorSummary from "./DXFormErrorSummary.vue";
 import type { EditTab } from "./DXTable.vue";
 import type { LabelCols } from "../../types";
 
@@ -241,10 +262,17 @@ interface Props {
     createText?: string;
     /** Override the Delete button label. */
     deleteText?: string;
+    /** The footer summary's heading for a failure with field errors. */
+    errorSummaryTitle?: string;
+    /** The footer summary's sub-heading over rows no field owns. */
+    errorSummaryOtherTitle?: string;
 }
 
 const props = defineProps<Props>();
 
+/** The inner form: its resolved error rows, and focusing an errored field. */
+const innerForm = ref<InstanceType<typeof DXForm> | null>(null);
+
 // Title-case the singular item noun for button labels ("customer" → "Customer",
 // "sales order" → "Sales Order") — capitalize the first letter of each word.
 const capitalizedItem = computed(() => {

package/resources/js/composables/useAsyncOptions.ts

@@ -8,13 +8,26 @@ import type { FieldDefinition, FieldOption } from "../types";
  * out-of-order responses clobbering newer ones; loader failures are swallowed
  * so the last good options (or the static `field.options` fallback) stay put.
  *
- * Extracted verbatim from DXField's inline logic (#135) — behaviour unchanged.
+ * Known limit: replacing a field's `optionsLoader` at runtime does NOT restart
+ * the "first load" state (loaded options and `firstLoadSettled` carry over).
+ * Loader identity is not a stable signal: an inline loader in a computed
+ * `fields` array is a new function on every recompute, so treating each new
+ * function as a new source would blank the field and refetch on every
+ * unrelated edit.
+ *
+ * Extracted from DXField's inline logic (#135).
  * `getField` is an accessor (props aren't destructurable without losing
  * reactivity); `effectiveModel` is the model passed to the loader.
  */
 export interface UseAsyncOptionsReturn {
     /** Options returned by the most recent successful load, or null if none yet. */
     loadedOptions: Ref<FieldOption[] | null>;
+    /**
+     * False until the first load has SETTLED (succeeded or failed). Only that
+     * first load leaves a field with nothing to show; a later reload keeps the
+     * options it has, or the static fallback after a failure.
+     */
+    firstLoadSettled: Ref<boolean>;
     /** Trigger a load (no-op when the field has no `optionsLoader`). */
     loadOptions: () => Promise<void>;
 }
@@ -24,6 +37,9 @@ export function useAsyncOptions(
     effectiveModel: ComputedRef<any> | Ref<any>,
 ): UseAsyncOptionsReturn {
     const loadedOptions = ref<FieldOption[] | null>(null);
+    // False before mount when there is a loader, so the first render already
+    // knows options are on their way.
+    const firstLoadSettled = ref(!getField().optionsLoader);
 
     // Monotonic token so out-of-order async responses can't clobber newer ones.
     let optionsRequestToken = 0;
@@ -46,6 +62,8 @@ export function useAsyncOptions(
                     error,
                 );
             }
+        } finally {
+            if (token === optionsRequestToken) firstLoadSettled.value = true;
         }
     }
 
@@ -53,9 +71,16 @@ export function useAsyncOptions(
         void loadOptions();
     });
 
-    if (getField().reloadOptionsOnChange) {
-        watch(effectiveModel, () => void loadOptions(), { deep: true });
-    }
+    // Read from the CURRENT field: DXForm keys DXField by `field.key`, so
+    // recomputed `fields` hand this instance a new field object that may
+    // turn reloading on or off.
+    watch(
+        effectiveModel,
+        () => {
+            if (getField().reloadOptionsOnChange) void loadOptions();
+        },
+        { deep: true },
+    );
 
-    return { loadedOptions, loadOptions };
+    return { loadedOptions, firstLoadSettled, loadOptions };
 }