@omnitend/dashboard-for-laravel 0.42.2 → 0.44.0

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 };
 }

package/resources/js/composables/useContainerWidth.ts

@@ -270,10 +270,17 @@ export function useContainerWidth(
     // express without mutating during evaluation. With `hysteresis: 0` it is
     // exactly `width < threshold`. The watcher is `sync` so `isBelow` is never
     // observed one tick behind `width`.
+    //
+    // The band only applies to a state that came from a MEASUREMENT. Before
+    // the first one, `isBelow` is the `initialWidth` guess (true by default),
+    // and holding that guess through the band would leave a container that
+    // measures just above the threshold (say 590 against 576 + 24) on the
+    // narrow layout until it next grows: it never crossed anything.
     const initialThreshold = resolveThreshold();
     const isBelow = ref<boolean>(
         initialThreshold === undefined ? false : startWidth < initialThreshold,
     );
+    let isBelowCameFromMeasurement = false;
     watch(
         [width, () => resolveThreshold()],
         ([currentWidth, currentThreshold]) => {
@@ -281,9 +288,11 @@ export function useContainerWidth(
                 isBelow.value = false;
                 return;
             }
-            isBelow.value = isBelow.value
-                ? currentWidth < currentThreshold + hysteresis
-                : currentWidth < currentThreshold;
+            isBelow.value =
+                isBelow.value && isBelowCameFromMeasurement
+                    ? currentWidth < currentThreshold + hysteresis
+                    : currentWidth < currentThreshold;
+            if (hasMeasured.value) isBelowCameFromMeasurement = true;
         },
         { flush: "sync" },
     );

package/resources/js/composables/useForm.ts

@@ -13,6 +13,19 @@ export interface ValidationErrors {
 
 export type FormError = ApiError;
 
+/**
+ * What the most recent failed submit returned (#194): the server's message and
+ * a COPY of its validation errors, frozen at the moment the submit failed.
+ * The live `form.errors` empties as the user fixes fields; this does not, so a
+ * summary built from it keeps listing every message until the next submit.
+ */
+export interface SubmitFailure {
+    /** A message fit to show a user (never empty, never a raw exception). */
+    message: string;
+    /** The validation errors the submit returned (`{}` when none). */
+    errors: ValidationErrors;
+}
+
 export interface FormSubmitOptions<TPayload = unknown, TResponse = unknown> {
     onSuccess?: (data: TResponse) => void;
     onError?: (error: FormError) => void;
@@ -39,6 +52,19 @@ export interface FormState<TData extends Record<string, any>> {
      */
     wasSuccessful: boolean;
     shouldShowMessage: boolean;
+    /**
+     * What the most recent submit failed with, or `null`. Set when a submit
+     * fails (validation or otherwise; an aborted submit does not count),
+     * cleared when a submit starts and when one succeeds. Untouched by
+     * `clearError`, `clearErrors`, `setErrors` and field edits.
+     */
+    submitFailure: SubmitFailure | null;
+    /**
+     * How many submits have failed, counting every failure (including a
+     * `preserveErrors` resubmit that returned the same errors), so a watcher
+     * can react to "a submit just failed" even when nothing else changed.
+     */
+    failedSubmitCount: number;
 }
 
 export interface UseFormReturn<TData extends Record<string, any>>
@@ -143,6 +169,59 @@ function objectToFormData(payload: Record<string, unknown>): FormData {
     return fd;
 }
 
+const GENERIC_FAILURE_MESSAGE = "An error occurred";
+
+/** Copy an errors map, keeping only non-empty string messages. */
+function copyValidationErrors(errors: unknown): ValidationErrors {
+    const copy: ValidationErrors = {};
+    if (errors === null || typeof errors !== "object") return copy;
+    for (const [key, value] of Object.entries(errors as Record<string, unknown>)) {
+        const messages = (Array.isArray(value) ? value : [value]).filter(
+            (message): message is string =>
+                typeof message === "string" && message !== "",
+        );
+        if (messages.length > 0) copy[key] = messages;
+    }
+    return copy;
+}
+
+export function isAbortError(error: unknown): boolean {
+    return (
+        error !== null &&
+        typeof error === "object" &&
+        (error as { name?: unknown }).name === "AbortError"
+    );
+}
+
+/**
+ * The `submitFailure` for a rejected submit, or `null` for an abort (the
+ * caller cancelled it; nothing failed). Only an `ApiError` from the client
+ * (an HTTP failure: it carries a numeric `status`, and the client has already
+ * replaced 401/403/404/419/500 bodies with user-facing text) supplies the
+ * message. Anything else (a network `TypeError`, an exception thrown from
+ * `onSuccess`) gets the generic message, so a summary never shows
+ * "Failed to fetch" or a stack-trace line.
+ */
+function submitFailureFrom(error: unknown): SubmitFailure | null {
+    if (isAbortError(error)) return null;
+    const isApiError =
+        error !== null &&
+        typeof error === "object" &&
+        typeof (error as ApiError).status === "number";
+    if (isApiError) {
+        const apiError = error as ApiError;
+        const message =
+            typeof apiError.message === "string" && apiError.message.trim() !== ""
+                ? apiError.message
+                : GENERIC_FAILURE_MESSAGE;
+        return { message, errors: copyValidationErrors(apiError.errors) };
+    }
+    return {
+        message: GENERIC_FAILURE_MESSAGE,
+        errors: copyValidationErrors(errorsFromLaravel(error).errors),
+    };
+}
+
 function errorsFromLaravel(error: any): {
     errors: ValidationErrors;
     message: string;
@@ -172,6 +251,64 @@ export function useForm<TData extends Record<string, any>>(
     let inFlightCount = 0;
     let successTimer: ReturnType<typeof setTimeout> | null = null;
 
+    // Which submit's outcome the form records (#194 review). Each submit takes
+    // a generation number when it starts. Its outcome (success, failure,
+    // errors, message, `submitFailure`, `resetOnSuccess`) is recorded only if
+    // no NEWER submit is still pending or has already recorded: the newest
+    // submit's outcome wins, in either completion order. An older success can
+    // therefore never clear a newer failure, and an older failure never lands
+    // over a newer success. Callbacks and the returned promise are
+    // unaffected: every submit still calls its own onSuccess/onError and
+    // resolves/rejects.
+    //
+    // An ABORTED submit is treated as if it had never started: it records
+    // nothing (not even the abort's own message), and an older outcome that
+    // was held back only because the aborted one was pending is then
+    // recorded. Held-back outcomes wait in `heldOutcomes` (newest wins; a
+    // newer recorded outcome drops them). A submit whose preparation
+    // (`transform`, `onBefore`) throws never takes a generation at all.
+    let latestSubmitGeneration = 0;
+    let lastRecordedGeneration = 0;
+    const pendingGenerations = new Set<number>();
+    const heldOutcomes = new Map<number, () => void>();
+    const mayRecord = (generation: number): boolean => {
+        if (generation < lastRecordedGeneration) return false;
+        for (const pending of pendingGenerations) {
+            if (pending > generation) return false;
+        }
+        return true;
+    };
+    /** Record now if this generation may, else hold it back for later. */
+    const recordOrHold = (generation: number, record: () => void): boolean => {
+        if (mayRecord(generation)) {
+            lastRecordedGeneration = generation;
+            heldOutcomes.clear();
+            record();
+            return true;
+        }
+        if (generation >= lastRecordedGeneration) heldOutcomes.set(generation, record);
+        return false;
+    };
+    /**
+     * After a submit leaves the pending set: record the NEWEST held-back
+     * outcome if nothing newer is pending any more (an abort unblocked it),
+     * and drop every older one. Older held outcomes never surface over a
+     * newer settled one.
+     */
+    const releaseHeldOutcomes = (): void => {
+        if (heldOutcomes.size === 0) return;
+        const newest = Math.max(...heldOutcomes.keys());
+        if (newest < lastRecordedGeneration) {
+            heldOutcomes.clear();
+            return;
+        }
+        if (!mayRecord(newest)) return;
+        const record = heldOutcomes.get(newest)!;
+        lastRecordedGeneration = newest;
+        heldOutcomes.clear();
+        record();
+    };
+
     const state = reactive<FormState<TData>>({
         data: deepClone(snapshot) as TData,
         errors: {},
@@ -181,6 +318,8 @@ export function useForm<TData extends Record<string, any>>(
         recentlySuccessful: false,
         wasSuccessful: false,
         shouldShowMessage: false,
+        submitFailure: null,
+        failedSubmitCount: 0,
     });
 
     const hasErrors = computed(() =>
@@ -238,7 +377,9 @@ export function useForm<TData extends Record<string, any>>(
         }
         clearErrors();
         state.touched = {};
-        state.processing = false;
+        // Not `false` outright: with another submit still in flight the form
+        // is still processing, and the counter will clear it when that ends.
+        state.processing = inFlightCount > 0;
     };
 
     // v-model for a single field
@@ -269,11 +410,15 @@ export function useForm<TData extends Record<string, any>>(
         url: string,
         options: FormSubmitOptions<TData, TResponse> = {},
     ): Promise<TResponse> => {
-        inFlightCount += 1;
-        state.processing = true;
-        state.wasSuccessful = false;
-        if (!options.preserveErrors) clearErrors();
-
+        // Preparation (`transform`, `onBefore`, building the body) runs BEFORE
+        // the submit takes a generation or touches form state. If it throws,
+        // the submit rejects with that error and is as if it never started:
+        // no request, no callbacks, no recorded failure, and the form keeps
+        // its previous outcome. (Before #194's review a throw here also
+        // rejected without calling onError/onFinish or recording a failure,
+        // but it had already cleared the errors and summary, and it left
+        // `processing` stuck at true because the in-flight count was never
+        // decremented.)
         const payloadRaw = (
             options.transform
                 ? // Give `transform` a COPY of the form data (#150), so a transform
@@ -315,6 +460,14 @@ export function useForm<TData extends Record<string, any>>(
             }
         }
 
+        inFlightCount += 1;
+        const generation = ++latestSubmitGeneration;
+        pendingGenerations.add(generation);
+        state.processing = true;
+        state.wasSuccessful = false;
+        state.submitFailure = null;
+        if (!options.preserveErrors) clearErrors();
+
         try {
             const { data } =
                 sendMethod === "get"
@@ -334,27 +487,52 @@ export function useForm<TData extends Record<string, any>>(
                             signal: options?.signal,
                         });
 
-            state.recentlySuccessful = true;
-            state.wasSuccessful = true;
-            if (successTimer !== null) clearTimeout(successTimer);
-            successTimer = setTimeout(() => {
-                state.recentlySuccessful = false;
-                successTimer = null;
-            }, 1500);
+            const records = recordOrHold(generation, () => {
+                state.recentlySuccessful = true;
+                state.wasSuccessful = true;
+                state.submitFailure = null;
+                if (successTimer !== null) clearTimeout(successTimer);
+                successTimer = setTimeout(() => {
+                    state.recentlySuccessful = false;
+                    successTimer = null;
+                }, 1500);
+            });
 
             options.onSuccess?.(data);
-            if (options.resetOnSuccess) {
+            // Only a success recorded when it lands resets: an older one would
+            // wipe the data and errors the newer submit is answering for, and
+            // a held-back success recorded later (after an abort) does not
+            // reset either, since the user may have typed since.
+            if (options.resetOnSuccess && records) {
                 reset();
             }
             return data;
         } catch (err) {
-            state.wasSuccessful = false;
-            const { errors, message } = errorsFromLaravel(err);
-            setErrors(errors);
-            setMessage(message);
+            // Decided again here (not reused from the try) so a throwing
+            // onSuccess is recorded, or held, as its failure: a held-back
+            // success for this generation is replaced.
+            //
+            // An abort records nothing: it is a cancellation, not an outcome.
+            // It leaves the pending set below, which may release an older
+            // held-back outcome.
+            if (!isAbortError(err)) {
+                const { errors, message } = errorsFromLaravel(err);
+                const failure = submitFailureFrom(err);
+                recordOrHold(generation, () => {
+                    state.wasSuccessful = false;
+                    setErrors(errors);
+                    setMessage(message);
+                    if (failure) {
+                        state.submitFailure = failure;
+                        state.failedSubmitCount += 1;
+                    }
+                });
+            }
             options.onError?.(err as FormError);
             throw err;
         } finally {
+            pendingGenerations.delete(generation);
+            releaseHeldOutcomes();
             inFlightCount -= 1;
             // Only clear `processing` once no submission is still in flight.
             if (inFlightCount === 0) state.processing = false;