@omnitend/dashboard-for-laravel 0.43.0 → 0.45.0

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

@@ -17,9 +17,19 @@
         @submit.prevent="handleSubmit"
         :class="{ 'dx-form--horizontal': resolvedLayout === 'horizontal' }"
     >
-        <!-- Form-level error message -->
+        <!-- What the last failed submit returned (#194), when the consumer
+             asked for it at the top rather than beside the submit button. -->
+        <DXFormErrorSummary
+            v-if="errorSummary === 'top'"
+            class="mb-3"
+            v-bind="summaryBindings"
+            @select-target="focusErrorTarget"
+        />
+
+        <!-- Form-level error message. Not while the summary shows a failure:
+             one alert, never two (the summary already carries the message). -->
         <DAlert
-            v-if="resolvedForm.shouldShowMessage"
+            v-if="resolvedForm.shouldShowMessage && !isSummaryShowing"
             :model-value="resolvedForm.shouldShowMessage"
             variant="danger"
             class="mb-3"
@@ -27,8 +37,13 @@
             {{ resolvedForm.message }}
         </DAlert>
 
-        <!-- Tabbed layout. BTabs exposes the active *index* via v-model:index
-             (plain v-model is the active tab id), which is what we track.
+        <!-- Tabbed layout. DXForm owns the selection (`activeTabKey`); DTabs
+             only renders it. DTabs gets the active PANE ID, controlled: its
+             own writes back (`update:modelValue`) are ignored, because bvn
+             re-derives ids from its registered-tab list, which lags a render
+             behind ours. Clicks and keys reach DXForm through each tab's own
+             click handler and button attributes, by tab key, never by
+             index; `no-key-nav` hands the arrow keys to DXForm.
              `card` needs BOTH: DTabs' own `card` prop (adds `card-header`/
              `card-body` classes to its nav/content internally) AND an outer
              `.card` element wrapping it (BVN's `card` prop does not add the
@@ -38,13 +53,21 @@
              `.card-body` internally via its own `card` prop, so wrapping
              that in another `.card-body` would double up. -->
         <component :is="tabsInCard ? DCard : 'div'" v-if="hasTabs" v-bind="tabsInCard ? { noBody: true } : {}">
-            <DTabs v-model:index="activeTab" :card="tabsInCard">
+            <DTabs
+                :modelValue="activePaneId"
+                :card="tabsInCard"
+                :noKeyNav="true"
+                @update:modelValue="ignoreTabsWrite"
+            >
                 <DTab
-                    v-for="(tab, index) in visibleTabs"
+                    v-for="tab in visibleTabs"
                     :key="tab.key"
+                    :id="paneIdFor(tab.key)"
+                    :buttonId="buttonIdFor(tab.key)"
                     :title="resolveTabLabel(tab)"
                     :lazy="tab.lazy"
-                    :active="index === 0"
+                    :titleLinkAttrs="tabButtonAttrs(tab.key)"
+                    :onClick="tabControlsFor(tab.key).onClick"
                 >
                     <!--
                       @slot Replaces the entire body of a tab, keyed by tab (slot name `tab-content(<tabKey>)`).
@@ -117,6 +140,14 @@
                     </template>
                 </DXFormField>
 
+                <!-- Failed-submit summary, directly above the submit button. -->
+                <DXFormErrorSummary
+                    v-if="errorSummary === 'footer'"
+                    class="mt-3"
+                    v-bind="summaryBindings"
+                    @select-target="focusErrorTarget"
+                />
+
                 <!-- Submit button -->
                 <DXSaveButton
                     v-if="showSubmit"
@@ -145,6 +176,15 @@
              DTabs' own card-body padding belongs to its tab content, not to
              trailing form-level actions. -->
         <template v-else>
+            <!-- Failed-submit summary: below the tabs (never inside a pane,
+                 which may be hidden), directly above the submit button. -->
+            <DXFormErrorSummary
+                v-if="errorSummary === 'footer'"
+                class="mt-3"
+                v-bind="summaryBindings"
+                @select-target="focusErrorTarget"
+            />
+
             <!-- Submit button -->
             <DXSaveButton
                 v-if="showSubmit"
@@ -171,8 +211,10 @@
 <script setup lang="ts">
 import {
     computed,
+    nextTick,
     onBeforeUnmount,
     ref,
+    useId,
     watch,
     type ComponentPublicInstance,
 } from "vue";
@@ -183,7 +225,9 @@ import DTabs from "../base/DTabs.vue";
 import { BTab as DTab } from "bootstrap-vue-next"; // raw BTab: BTabs scans slot vnodes for it (#119)
 import DXFormField from "./DXFormField.vue";
 import DXSaveButton from "./DXSaveButton.vue";
-import type { UseFormReturn } from "../../composables/useForm";
+import DXFormErrorSummary, { type ErrorSummarySelection } from "./DXFormErrorSummary.vue";
+import { resolveErrorTargets, type ErrorTarget } from "../../utils/formErrorTargets";
+import type { UseFormReturn, ValidationErrors } from "../../composables/useForm";
 import type { DefineFormReturn } from "../../composables/defineForm";
 import { useContainerWidth } from "../../composables/useContainerWidth";
 import type { FieldDefinition, FormTab, LabelCols, MaybeFn } from "../../types";
@@ -296,6 +340,46 @@ interface Props {
      * `sm` up and stacks above the input below `sm`.
      */
     labelCols?: LabelCols;
+
+    /**
+     * Where to list what the last failed submit returned (`form.submitFailure`:
+     * the server's message and every validation message, with readable
+     * labels):
+     *
+     * - `"footer"` (default) — directly above the submit button, below any
+     *   tabs, next to the control the user just pressed.
+     * - `"top"` — above the fields, where the form-level alert sits.
+     * - `"external"` — the host renders a `DXFormErrorSummary` of its own
+     *   elsewhere (beside a submit button outside the form, as DXTable's
+     *   modal does). DXForm renders neither a summary nor, while a failure
+     *   is listed, the form-level alert.
+     * - `false` — no summary; the form-level alert behaves as before.
+     *
+     * While a summary shows a failure the form-level alert does not render,
+     * so a failure shows exactly one alert. Each row naming a visible field is
+     * a button that selects the field's tab and focuses it.
+     */
+    errorSummary?: "footer" | "top" | "external" | false;
+
+    /**
+     * The summary's heading when the failure has field errors (default
+     * "Couldn't save. Please check:"). A failure with none (a message-only
+     * 422, a 500) is headed by the server's message instead.
+     */
+    errorSummaryTitle?: string;
+
+    /**
+     * The summary's sub-heading over the rows no visible field owns (default
+     * "Other problems"), shown only when some rows ARE owned.
+     */
+    errorSummaryOtherTitle?: string;
+
+    /**
+     * After a failed submit, scroll the first field with an error into view
+     * (once its tab is selected and rendered). Never moves focus. On by
+     * default.
+     */
+    scrollToError?: boolean;
 }
 
 const props = withDefaults(defineProps<Props>(), {
@@ -309,6 +393,8 @@ const props = withDefaults(defineProps<Props>(), {
     cardTabs: true,
     layout: "vertical",
     layoutThreshold: 640,
+    errorSummary: "footer",
+    scrollToError: true,
 });
 
 const emit = defineEmits<{
@@ -318,7 +404,10 @@ const emit = defineEmits<{
 
 const slots = defineSlots<Record<string, (props: any) => any>>();
 
-/** v-model for the active tab index. */
+/**
+ * v-model for the active tab, as an index into the VISIBLE tabs. It is a
+ * view of `activeTabKey` (below), which is what DXForm actually tracks.
+ */
 const activeTab = defineModel<number>("activeTab", { default: 0 });
 
 // ————————————————— container-driven layout (`layout: "auto"`)
@@ -472,7 +561,14 @@ const visibleFlatFields = computed<FieldDefinition[]>(() =>
     resolvedFields.value.filter(isFieldVisible),
 );
 
-// ————————————————— auto-switch to the first error tab
+// ————————————————— active tab, tracked by key (#194)
+//
+// One owner: `activeTabKey`. The pane bvn shows (`activePaneId`) and the
+// index the `activeTab` model reports are both derived from it, and every
+// change goes through `commitTabKey`, the one writer. Tracking an index
+// instead broke whenever the tab list changed under it: an earlier tab
+// hiding or tabs reordering silently showed a different tab, and bvn (which
+// tracks tabs by id) mapped indexes against a stale list.
 
 /** Keys that currently carry at least one validation error. */
 const erroredKeys = computed<string[]>(() =>
@@ -481,31 +577,576 @@ const erroredKeys = computed<string[]>(() =>
     ),
 );
 
-function goToErrorTab(): void {
-    if (!hasTabs.value || erroredKeys.value.length === 0) return;
-    const tabIndex = visibleTabs.value.findIndex((tab) =>
-        tab.fieldKeys.some((key) =>
-            erroredKeys.value.some(
-                // Match exact keys and nested (repeater) error keys.
-                (errorKey) => errorKey === key || errorKey.startsWith(`${key}.`),
-            ),
-        ),
+const visibleTabKeys = computed<string[]>(() =>
+    visibleTabs.value.map((tab) => tab.key),
+);
+
+/**
+ * Where each error key belongs, decided by the one resolver the summary also
+ * uses (#194), under THIS form's visibility rules: a field hidden by `when`,
+ * or on a tab DXForm does not render, owns nothing. So the tab a failure
+ * selects, the field it scrolls to and the summary's rows always agree,
+ * including nested keys a field claims with `errorKeys`. A tab key with no
+ * field definition (consumer-rendered content) still owns its own key and
+ * keys nested under it.
+ */
+function errorTargetsFor(errors: ValidationErrors | null | undefined): ErrorTarget[] {
+    return resolveErrorTargets(errors, {
+        fields: resolvedFields.value,
+        tabs: hasTabs.value ? props.tabs : undefined,
+        model: model.value,
+        isFieldVisible,
+        isTabVisible: (tab) => visibleTabKeys.value.includes(tab.key),
+    });
+}
+
+/** Targets for the errors on the form now (tab choice, scrolling). */
+const liveErrorTargets = computed<ErrorTarget[]>(() =>
+    erroredKeys.value.length === 0 ? [] : errorTargetsFor(resolvedForm.value.errors),
+);
+
+/** Targets for what the last failed submit returned (the summary's rows). */
+const summaryTargets = computed<ErrorTarget[]>(() => {
+    const failure = resolvedForm.value.submitFailure;
+    return failure ? errorTargetsFor(failure.errors) : [];
+});
+
+/** Key of the first visible tab owning a visible errored field, or null. */
+function firstErrorTabKey(): string | null {
+    const owned = liveErrorTargets.value.find((target) => target.tabKey !== null);
+    return owned ? owned.tabKey : null;
+}
+
+function sameKeys(keys: readonly string[], otherKeys: readonly string[] | undefined): boolean {
+    return (
+        otherKeys !== undefined &&
+        keys.length === otherKeys.length &&
+        keys.every((key, index) => key === otherKeys[index])
     );
-    if (tabIndex !== -1) activeTab.value = tabIndex;
 }
 
-// Watch a primitive derived from the error keys so the effect reliably
-// re-runs when errors are set (deep-watching the stable reactive object
-// reference does not fire on key additions). `immediate` handles errors
-// already present on the form before mount.
+/** The selected tab's key: the single source of truth for the active tab. */
+const activeTabKey = ref<string | null>(null);
+
+// Pane ids are opaque and stable per tab KEY: a number assigned the first
+// time a key is seen, never derived from the key's text (which may hold
+// spaces, invalid in an id) or from its position (which changes when tabs
+// reorder or hide, and would make bvn show a different pane).
+const tabIdBase = useId();
+const paneNumbers = new Map<string, number>();
+/** Monotonic: a pruned key's number is never handed out again. */
+let nextPaneNumber = 0;
+
+function paneIdFor(key: string): string {
+    let paneNumber = paneNumbers.get(key);
+    if (paneNumber === undefined) {
+        paneNumber = nextPaneNumber;
+        nextPaneNumber += 1;
+        paneNumbers.set(key, paneNumber);
+    }
+    return `${tabIdBase}-tab-${paneNumber}`;
+}
+
+function buttonIdFor(key: string): string {
+    return `${paneIdFor(key)}-button`;
+}
+
+/** The pane DTabs shows; undefined while the selected tab is not rendered. */
+const activePaneId = computed<string | undefined>(() =>
+    activeTabKey.value !== null && visibleTabKeys.value.includes(activeTabKey.value)
+        ? paneIdFor(activeTabKey.value)
+        : undefined,
+);
+
+/** Invalidates a pending parent-answer check when a newer write happens. */
+let modelWriteToken = 0;
+
+/**
+ * The one writer of the active tab. Sets the key, then reports its visible
+ * index through the `activeTab` model when that differs from what the model
+ * holds (a new selection, or the same tab at a new position).
+ *
+ * A parent binding the model may reject or normalise the index it is sent.
+ * Once the flush has carried its answer back, the parent's value wins
+ * (controlled behaviour). With no binding the model updates locally, so the
+ * check finds the value it wrote and nothing changes.
+ */
+function commitTabKey(key: string | null): void {
+    activeTabKey.value = key;
+    const index = key === null ? -1 : visibleTabKeys.value.indexOf(key);
+    if (index === -1 || index === activeTab.value) return;
+    activeTab.value = index;
+    const writeToken = ++modelWriteToken;
+    nextTick(() => {
+        if (writeToken !== modelWriteToken) return;
+        const answeredIndex = activeTab.value;
+        if (answeredIndex === index) return;
+        const answeredKey = visibleTabKeys.value[answeredIndex];
+        if (answeredKey !== undefined) commitTabKey(answeredKey);
+    });
+}
+
+/**
+ * Which tab to show. In order: after a failed submit (or with errors present
+ * at mount), the first visible tab owning a visible errored field; a tab
+ * index the parent just set; the current tab while it is still visible; the
+ * first visible tab. With no visible tabs the key is kept, so the same tab
+ * returns when they come back, and an index the parent sets meanwhile (or
+ * at mount) is held until they do: it cannot be resolved to a key yet.
+ */
+let pendingRequestedIndex: number | null = null;
+
+function decideTabKey(failed: boolean, incomingIndex: number | null): string | null {
+    const keys = visibleTabKeys.value;
+    if (keys.length === 0) {
+        if (incomingIndex !== null) pendingRequestedIndex = incomingIndex;
+        return activeTabKey.value;
+    }
+    const requestedIndex = incomingIndex ?? pendingRequestedIndex;
+    pendingRequestedIndex = null;
+    if (failed && props.autoErrorTab) {
+        const errorTabKey = firstErrorTabKey();
+        if (errorTabKey !== null) return errorTabKey;
+    }
+    if (requestedIndex !== null) {
+        const requestedKey = keys[requestedIndex];
+        if (requestedKey !== undefined) return requestedKey;
+    }
+    const currentKey = activeTabKey.value;
+    if (currentKey !== null && keys.includes(currentKey)) return currentKey;
+    return keys[0];
+}
+
+// "A submit failed": what sends the form to its error tab. Either signal
+// counts:
+//
+// - `failedSubmitCount` changing. useForm counts every failed submit, so a
+//   `preserveErrors` resubmit that returns exactly the same set (its keys
+//   never leave the form) still takes the user back to the error.
+// - the errored-key set GROWING. Errors set without a submit through useForm
+//   (`form.setErrors()` after a client-side check, or after a consumer's own
+//   request) keep selecting their tab, as they always have.
+//
+// An error CLEARING (a field edit) is neither, so fixing a field never moves
+// the tab. The key comparison is between flushes, never inside one:
+// `setErrors` empties the set and refills it synchronously, which a sync
+// watcher would misread as an addition.
+const failureCount = (): number => resolvedForm.value.failedSubmitCount ?? 0;
+
+function keysGrew(keys: readonly string[], previousKeys: readonly string[] | undefined): boolean {
+    const previous = new Set(previousKeys ?? []);
+    return keys.some((key) => !previous.has(key));
+}
+
+// The decision runs ONCE per tick for every input that changed in it (the
+// visible tabs, the failure signals, the model index), so two concerns can
+// never write competing values in one flush.
+let hasDecided = false;
 watch(
-    () => erroredKeys.value.join("|"),
-    (joined) => {
-        if (props.autoErrorTab && joined) goToErrorTab();
+    [visibleTabKeys, () => erroredKeys.value, failureCount, () => activeTab.value] as const,
+    ([keys, errorKeys, count, index], previous) => {
+        if (!hasDecided) {
+            // Errors already on the form at mount select their tab.
+            hasDecided = true;
+            commitTabKey(decideTabKey(errorKeys.length > 0, index));
+            return;
+        }
+        const [previousKeys, previousErrorKeys, previousCount, previousIndex] = previous;
+        const submitFailed = count !== previousCount;
+        const failed = submitFailed || keysGrew(errorKeys, previousErrorKeys);
+        const requestedIndex = index !== previousIndex ? index : null;
+        if (!failed && requestedIndex === null && sameKeys(keys, previousKeys)) return;
+        commitTabKey(decideTabKey(failed, requestedIndex));
+        if (submitFailed && props.scrollToError) scrollToFirstError();
     },
     { immediate: true },
 );
 
+/** A tab button the user clicked or reached with the keyboard. */
+function selectTabFromUser(key: string): void {
+    if (visibleTabKeys.value.includes(key)) commitTabKey(key);
+}
+
+/**
+ * DTabs' own writes of the active pane id are ignored: they come from bvn
+ * re-deriving the selection from its registered-tab list, which can lag
+ * DXForm's by a render. The listener stays so the binding is controlled
+ * (without it bvn would overwrite the id locally).
+ */
+function ignoreTabsWrite(): void {}
+
+/**
+ * A tab's click handler and its nav button's attributes: a roving tabindex
+ * (only the selected tab is in the tab order) and the arrow-key handler,
+ * which DXForm owns because DTabs runs with `no-key-nav`.
+ *
+ * Cached per key (and selection state), so every value keeps its identity
+ * across renders. bvn re-evaluates this slot on every BTabs render and folds
+ * each tab's `onClick` and `titleLinkAttrs` into its tab list, so a fresh
+ * function or object each time re-renders BTabs, which re-evaluates the
+ * slot: an endless update loop ("Maximum recursive updates").
+ */
+interface TabControls {
+    onClick: () => void;
+    selectedButtonAttrs: Record<string, unknown>;
+    unselectedButtonAttrs: Record<string, unknown>;
+}
+
+const tabControlsByKey = new Map<string, TabControls>();
+
+function tabControlsFor(key: string): TabControls {
+    let controls = tabControlsByKey.get(key);
+    if (controls === undefined) {
+        const onKeydown = (event: KeyboardEvent) => handleTabKeydown(event, key);
+        controls = {
+            onClick: () => selectTabFromUser(key),
+            selectedButtonAttrs: { tabindex: 0, onKeydown },
+            unselectedButtonAttrs: { tabindex: -1, onKeydown },
+        };
+        tabControlsByKey.set(key, controls);
+    }
+    return controls;
+}
+
+// Forget the ids and controls of keys no longer in `props.tabs`, so a form
+// whose tab list is rebuilt over its life does not keep every key it ever
+// had. A tab hidden by `when` is still in `props.tabs` and keeps its id, so
+// it returns as the same pane.
+watch(
+    () => (props.tabs ?? []).map((tab) => tab.key),
+    (keys) => {
+        const current = new Set(keys);
+        for (const key of [...paneNumbers.keys()]) {
+            if (!current.has(key)) paneNumbers.delete(key);
+        }
+        for (const key of [...tabControlsByKey.keys()]) {
+            if (!current.has(key)) tabControlsByKey.delete(key);
+        }
+    },
+);
+
+function tabButtonAttrs(key: string): Record<string, unknown> {
+    const controls = tabControlsFor(key);
+    return key === activeTabKey.value
+        ? controls.selectedButtonAttrs
+        : controls.unselectedButtonAttrs;
+}
+
+/** bvn's horizontal key map: ←/→ step (Shift: to the end), Home/End/PageUp/PageDown jump. */
+function handleTabKeydown(event: KeyboardEvent, key: string): void {
+    if (event.altKey || event.ctrlKey || event.metaKey) return;
+    const keys = visibleTabKeys.value;
+    const fromIndex = keys.indexOf(key);
+    if (fromIndex === -1) return;
+    const lastIndex = keys.length - 1;
+    let targetIndex: number;
+    switch (event.key) {
+        case "ArrowLeft":
+            targetIndex = event.shiftKey ? 0 : Math.max(fromIndex - 1, 0);
+            break;
+        case "ArrowRight":
+            targetIndex = event.shiftKey ? lastIndex : Math.min(fromIndex + 1, lastIndex);
+            break;
+        case "Home":
+        case "PageUp":
+            targetIndex = 0;
+            break;
+        case "End":
+        case "PageDown":
+            targetIndex = lastIndex;
+            break;
+        default:
+            return;
+    }
+    event.preventDefault();
+    selectTabFromUser(keys[targetIndex]);
+    // Focus follows the tab that ends up selected, after any parent answer
+    // (commitTabKey's check was queued first, so it has run by now).
+    nextTick(() => {
+        const selectedKey = activeTabKey.value;
+        if (selectedKey === null) return;
+        document.getElementById(buttonIdFor(selectedKey))?.focus();
+    });
+}
+
+/** Select the first visible tab owning a visible errored field, if any. */
+function goToErrorTab(): void {
+    const errorTabKey = firstErrorTabKey();
+    if (errorTabKey !== null) commitTabKey(errorTabKey);
+}
+
+// ————————————————— taking the user to an errored field (#194)
+
+/**
+ * Controls a user types into or picks from: what a focus request lands on.
+ * Looked for before anything else focusable, so a field whose label carries
+ * an info button ("More information", earlier in document order) focuses
+ * its input, not the button. Matching is only the first step: every
+ * candidate must also pass `canTakeFocus`.
+ */
+const EDITABLE_CONTROL = [
+    'input:not([type="hidden"]):not([type="button"]):not([type="submit"]):not([type="reset"])',
+    "select",
+    "textarea",
+    '[contenteditable="true"]',
+    '[contenteditable=""]',
+    '[role="combobox"]',
+    '[role="textbox"]',
+    '[role="spinbutton"]',
+    '[role="listbox"]',
+].join(", ");
+
+/** The fallback for a widget with no editable control (a button picker). */
+const ANY_FOCUSABLE = ["button", "a[href]", "[tabindex]"].join(", ");
+
+/** Elements the browser focuses without a `tabindex`. */
+const NATIVELY_FOCUSABLE = "input, select, textarea, button, a[href]";
+
+/**
+ * Frames to wait for a field's element: a lazy tab mounts its pane a render
+ * or two after it is selected, and a repeater (an async component) renders
+ * its rows after that. After this many, a nested key that never rendered an
+ * element of its own (a media map's `image_media.<uuid>`) settles for its
+ * owning field.
+ */
+const FIELD_RENDER_ATTEMPTS = 10;
+
+/**
+ * Further frames a FOCUS request waits for a control that can take focus
+ * (about a second): an async editor renders its wrapper before its control,
+ * and a widget may render its control disabled until its data loads.
+ */
+const CONTROL_RENDER_ATTEMPTS = 60;
+
+const nextFrame = () =>
+    new Promise((resolve) => requestAnimationFrame(() => resolve(null)));
+
+/**
+ * Whether `candidate` can take focus now: laid out, not disabled (itself or
+ * through a disabled fieldset), not `aria-disabled`, not inside an `inert`
+ * subtree, and focusable at all (a native control, contenteditable, or any
+ * `tabindex`; a `div role="combobox"` with none is not). A negative
+ * `tabindex` only takes an element out of the Tab order; it can still be
+ * focused, so an editor surface with `tabindex="-1"` qualifies.
+ */
+function canTakeFocus(candidate: HTMLElement): boolean {
+    if (candidate.offsetParent === null) return false;
+    if (candidate.matches(":disabled")) return false;
+    if (candidate.closest("fieldset:disabled") !== null) return false;
+    if (candidate.getAttribute("aria-disabled") === "true") return false;
+    if (candidate.closest("[inert]") !== null) return false;
+    return (
+        candidate.matches(NATIVELY_FOCUSABLE) ||
+        candidate.isContentEditable ||
+        candidate.hasAttribute("tabindex")
+    );
+}
+
+/**
+ * True when an element belongs to THIS form rather than to a DXForm nested in
+ * one of its slots, whose fields can carry the same `data-dx-field-key`.
+ */
+function belongsToThisForm(element: HTMLElement): boolean {
+    const root = resolveFormElement();
+    return root !== null && element.closest("form") === root;
+}
+
+/** The first element matching `selector` (itself or inside) that can take focus. */
+function firstFocusable(element: HTMLElement, selector: string): HTMLElement | null {
+    if (element.matches(selector) && canTakeFocus(element) && belongsToThisForm(element)) {
+        return element;
+    }
+    for (const candidate of Array.from(element.querySelectorAll<HTMLElement>(selector))) {
+        if (canTakeFocus(candidate) && belongsToThisForm(candidate)) return candidate;
+    }
+    return null;
+}
+
+/**
+ * The first shown element marked with this data path, or null. Compared as
+ * an attribute value rather than built into a selector, so a key holding
+ * quotes, brackets, spaces or dots (`image_media.<uuid>`) needs no escaping.
+ * Nested markers for one key (a slot binding `targetAttrs` around a DXField)
+ * resolve to the outer one, whose subtree holds the inner one's control.
+ */
+function shownFieldElement(path: string): HTMLElement | null {
+    const root = resolveFormElement();
+    if (root === null) return null;
+    for (const element of Array.from(root.querySelectorAll<HTMLElement>("[data-dx-field-key]"))) {
+        if (
+            element.getAttribute("data-dx-field-key") === path &&
+            element.offsetParent !== null &&
+            element.closest("form") === root
+        ) {
+            return element;
+        }
+    }
+    return null;
+}
+
+/**
+ * The element to take the user to for an error: the one rendered for the
+ * EXACT error path (`lines.1.price`, a repeater row's field) when there is
+ * one, else the owning field's (`lines`). DXField's roots carry
+ * `data-dx-field-key`, as does whatever a `field(<key>)` slot binds
+ * `targetAttrs` to. Null when neither renders (an unmarked slot, consumer
+ * content, a tab that cannot be shown).
+ */
+async function renderedErrorElement(
+    errorKey: string,
+    fieldKey: string,
+): Promise<HTMLElement | null> {
+    for (let attempt = 0; attempt < FIELD_RENDER_ATTEMPTS; attempt += 1) {
+        await nextTick();
+        const exact = shownFieldElement(errorKey);
+        if (exact !== null) return exact;
+        if (attempt < FIELD_RENDER_ATTEMPTS - 1) await nextFrame();
+    }
+    return errorKey === fieldKey ? null : shownFieldElement(fieldKey);
+}
+
+/**
+ * Scroll a field into view. A field that fits in the viewport is scrolled
+ * whole, so its label and the message under its input show too. One taller
+ * than the viewport (a marked container with a long explanation above its
+ * input) is scrolled by its first usable control, centred, since scrolling
+ * by its own edge can leave the input below the fold: an editable control
+ * when there is one, else anything focusable (a picker's button). Never
+ * focuses.
+ */
+function scrollFieldIntoView(element: HTMLElement): void {
+    const control =
+        firstFocusable(element, EDITABLE_CONTROL) ?? firstFocusable(element, ANY_FOCUSABLE);
+    if (control !== null && element.getBoundingClientRect().height > window.innerHeight) {
+        control.scrollIntoView({ block: "center" });
+        return;
+    }
+    element.scrollIntoView({ block: "nearest" });
+}
+
+/** Bumped per scroll/focus request, so only the latest one acts. */
+let revealToken = 0;
+
+/**
+ * After a failed submit: once the decision has selected the tab and the
+ * failure's render has flushed (its pane mounted), scroll the first owned
+ * field on that tab into view. Each target is looked up in the form's DOM
+ * at that moment, in order, never from an earlier render's record: a target
+ * whose marker never renders (an unmarked `field(<key>)` slot, consumer
+ * content) is skipped after its render frames, for the next one. No focus,
+ * so a phone does not raise its keyboard over the summary.
+ */
+function scrollToFirstError(): void {
+    const selectedKey = activeTabKey.value;
+    const targets = liveErrorTargets.value.filter(
+        (target) =>
+            target.fieldKey !== null &&
+            (target.tabKey === null || target.tabKey === selectedKey),
+    );
+    if (targets.length === 0) return;
+    const token = ++revealToken;
+    void (async () => {
+        for (const target of targets) {
+            // Its first lookup waits for the flush (nextTick), so a marker
+            // rendered by the failure itself is found.
+            const element = await renderedErrorElement(target.errorKey, target.fieldKey!);
+            if (token !== revealToken) return;
+            if (element !== null) {
+                scrollFieldIntoView(element);
+                return;
+            }
+        }
+    })();
+}
+
+/**
+ * Where focus goes when the field cannot take it (nothing marked renders,
+ * or nothing in it can be focused): the selected tab's button, with its pane
+ * scrolled into view, so focus never drops to the body (a summary row of an
+ * unopened lazy tab, once the pane replaces what was shown). A form with no
+ * tabs leaves focus where it is (the summary row).
+ */
+function focusSelectedTab(): void {
+    const selectedKey = activeTabKey.value;
+    if (selectedKey === null) return;
+    document.getElementById(paneIdFor(selectedKey))?.scrollIntoView({ block: "nearest" });
+    document.getElementById(buttonIdFor(selectedKey))?.focus();
+}
+
+/**
+ * Take the user to an error a summary lists: select its tab, wait for the
+ * pane to render, look the field up in the form (its marker, anywhere
+ * inside the form's element, a teleport target inside the form included),
+ * scroll it into view and focus its control: an editable control that can
+ * take focus, waiting (about a second) while none can, e.g. an async editor
+ * still loading or a widget rendered disabled until its data arrives;
+ * anything else focusable only as a fallback. A focus counts only once
+ * `document.activeElement` is the control. The field is looked up again by
+ * its key whenever its element leaves the DOM (a re-render replacing it),
+ * and a moment with none at all is waited out. When no marker renders
+ * within the field's render frames, or nothing in it takes focus, focus
+ * moves to the selected tab's button. Exposed so a summary rendered OUTSIDE
+ * the form (DXTable's modal footer) can drive it.
+ */
+async function focusErrorTarget(target: ErrorSummarySelection): Promise<void> {
+    if (target.tabKey !== null && visibleTabKeys.value.includes(target.tabKey)) {
+        commitTabKey(target.tabKey);
+    }
+    const token = ++revealToken;
+    let element = await renderedErrorElement(
+        target.errorKey ?? target.fieldKey,
+        target.fieldKey,
+    );
+    if (token !== revealToken) return;
+    if (element === null) {
+        focusSelectedTab();
+        return;
+    }
+    const path = element.getAttribute("data-dx-field-key") ?? target.fieldKey;
+    scrollFieldIntoView(element);
+
+    const tryFocus = (control: HTMLElement | null): boolean => {
+        if (control === null) return false;
+        control.focus({ preventScroll: true });
+        if (document.activeElement !== control) return false;
+        control.scrollIntoView({ block: "nearest" });
+        return true;
+    };
+
+    for (let attempt = 0; attempt <= CONTROL_RENDER_ATTEMPTS; attempt += 1) {
+        if (element !== null && tryFocus(firstFocusable(element, EDITABLE_CONTROL))) return;
+        if (attempt === CONTROL_RENDER_ATTEMPTS) break;
+        await nextFrame();
+        if (token !== revealToken) return;
+        // A re-render may have replaced the field's element, or removed it
+        // for a moment: look it up again by its key.
+        if (element === null || !element.isConnected) element = shownFieldElement(path);
+    }
+    if (element !== null && tryFocus(firstFocusable(element, ANY_FOCUSABLE))) return;
+    focusSelectedTab();
+}
+
+// ————————————————— failed-submit summary
+
+/** A summary is listing a failure, so the form-level alert steps aside. */
+const isSummaryShowing = computed(
+    () =>
+        props.errorSummary !== false &&
+        resolvedForm.value.submitFailure !== null &&
+        resolvedForm.value.submitFailure !== undefined,
+);
+
+const summaryBindings = computed(() => ({
+    form: resolvedForm.value,
+    fields: resolvedFields.value,
+    tabs: props.tabs,
+    context: props.context,
+    targets: summaryTargets.value,
+    // Undefined when unset, so the summary's own defaults apply.
+    title: props.errorSummaryTitle,
+    otherTitle: props.errorSummaryOtherTitle,
+}));
+
 // ————————————————— saved state (submit button shows "✓ Saved")
 
 /**
@@ -585,5 +1226,12 @@ function handleSubmit(): void {
     emit("submit");
 }
 
-defineExpose({ goToErrorTab });
+defineExpose({
+    /** Select the first visible tab owning a visible errored field, if any. */
+    goToErrorTab,
+    /** Select an error's tab, then scroll to and focus its field. */
+    focusErrorTarget,
+    /** What the last failed submit returned, resolved by this form's rules. */
+    errorTargets: summaryTargets,
+});
 </script>