Add focusOnFirstError feature

.changeset/fair-chairs-thank.md

@@ -0,0 +1,8 @@
+---
+"@sjsf/daisyui-theme": patch
+"playground": patch
+"@sjsf/form": patch
+"docs": patch
+---
+
+Add `focusOnFirstError` feature

apps/docs/src/content/docs/customization/focus-on-first-error.mdx

@@ -0,0 +1,24 @@
+---
+title: Focus on first error
+sidebar:
+  order: 2
+---
+
+You can achieve focus on the first error by using the `focusOnFirstError` function.
+
+## Usage
+
+```svelte
+<script lang="ts">
+  import { Form } from "@sjsf/form";
+  import { focusOnFirstError } from '@sjsf/form/focus-on-first-error';
+</script>
+
+<Form {...} onSubmitError={focusOnFirstError} />
+```
+
+## Explanation
+
+1. `focusOnFirstError` will try to find a focusable element and focus it.
+2. If it's not found, it will try to find an errors list and scroll it into view.
+3. If it's not found, it will return `false`.

apps/playground/src/app.svelte

@@ -6,9 +6,10 @@
     type ValidatorError,
   } from "@sjsf/form";
   import { translation } from "@sjsf/form/translations/en";
-  import { themes, themeStyles } from './themes'
   import { AjvValidator, addFormComponents, DEFAULT_AJV_CONFIG } from "@sjsf/ajv8-validator";
+  import { focusOnFirstError } from '@sjsf/form/focus-on-first-error';
 
+  import { themes, themeStyles } from './themes'
   import { ShadowHost } from "./shadow";
   import Github from "./github.svelte";
   import OpenBook from "./open-book.svelte";
@@ -64,6 +65,7 @@
   let readonly = $state(false);
   let html5Validation = $state(false);
   let errorsList = $state(true);
+  let doFocusOnFirstError = $state(true);
   let errors = $state.raw<ValidatorError<any>[]>(
     samples[initialSampleName].errors ?? []
   );
@@ -96,6 +98,10 @@
       <input type="checkbox" bind:checked={errorsList} />
       Errors list
     </label>
+    <label>
+      <input type="checkbox" bind:checked={doFocusOnFirstError} />
+      Focus on first error
+    </label>
     <select bind:value={themeName} onchange={() => selectTheme(themeName)}>
       {#each Object.keys(themes) as name (name)}
         <option value={name}>{name}</option>
@@ -185,7 +191,10 @@
         onSubmit={(value) => {
           console.log("submit", value);
         }}
-        onSubmitError={(errors) => {
+        onSubmitError={(errors, e) => {
+          if (doFocusOnFirstError) {
+            focusOnFirstError(errors, e);
+          }
           console.log("errors", errors);
         }}
       />

mkfile

@@ -21,10 +21,18 @@ f/:
 
 docs/:
   pushd apps/docs
+  d:
+    pnpm run dev
   b:
     pnpm run build
+  popd
+
+pl/:
+  pushd apps/playground
   d:
     pnpm run dev
+  b:
+    pnpm run build
   popd
 
 daisy/:

packages/daisyui-theme/src/lib/components/errors-list.svelte

@@ -1,10 +1,10 @@
 <script lang="ts">
   import type { ComponentProps } from "@sjsf/form";
 
-  const { errors }: ComponentProps<"errorsList"> = $props();
+  const { errors, forId }: ComponentProps<"errorsList"> = $props();
 </script>
 
-<ui class="text-error">
+<ui class="text-error" data-errors-for={forId}>
   {#each errors as err}
     <li>{err.message}</li>
   {/each}

packages/form/package.json

@@ -76,6 +76,11 @@
       "types": "./dist/basic-theme/index.d.ts",
       "svelte": "./dist/basic-theme/index.js",
       "default": "./dist/basic-theme/index.js"
+    },
+    "./focus-on-first-error": {
+      "types": "./dist/focus-on-first-error.d.ts",
+      "svelte": "./dist/focus-on-first-error.js",
+      "default": "./dist/focus-on-first-error.js"
     }
   }
 }

packages/form/src/basic-theme/components/errors-list.svelte

@@ -1,10 +1,10 @@
 <script lang="ts">
   import type { ComponentProps } from "@/form/index.js";
 
-  const { errors }: ComponentProps<"errorsList"> = $props();
+  const { errors, forId }: ComponentProps<"errorsList"> = $props();
 </script>
 
-<ui style="color: red;">
+<ui style="color: red;" data-errors-for={forId}>
   {#each errors as err}
     <li>{err.message}</li>
   {/each}

packages/form/src/focus-on-first-error.ts

@@ -0,0 +1,71 @@
+import { tick } from "svelte";
+
+import {
+  ValidatorErrorType,
+  type ValidatorError,
+  type ValidationError,
+} from "@/core/validator.js";
+
+export function getFocusableElement(
+  form: HTMLElement,
+  error: ValidationError<unknown>
+) {
+  const item = form.querySelector(`[id="${error.instanceId}"]`);
+  if (
+    !(
+      (item instanceof HTMLInputElement && item.type !== "checkbox") ||
+      item instanceof HTMLTextAreaElement ||
+      item instanceof HTMLSelectElement ||
+      item instanceof HTMLButtonElement
+    )
+  ) {
+    return null;
+  }
+  return item;
+}
+
+export function getErrorsList(
+  form: HTMLElement,
+  error: ValidationError<unknown>
+) {
+  return form.querySelector(`[data-errors-for="${error.instanceId}"]`);
+}
+
+export function getFocusAction(
+  form: HTMLElement,
+  error: ValidationError<unknown>
+) {
+  const focusableElement = getFocusableElement(form, error);
+  if (focusableElement !== null) {
+    return () => focusableElement.focus();
+  }
+  const errorsList = getErrorsList(form, error);
+  if (errorsList !== null) {
+    return () =>
+      errorsList.scrollIntoView({ behavior: "auto", block: "center" });
+  }
+  return null;
+}
+
+export function focusOnFirstError(
+  errors: ValidatorError<unknown>[],
+  e: SubmitEvent
+) {
+  const form = e.target;
+  if (!(form instanceof HTMLElement)) {
+    console.warn("Expected form to be an HTMLFormElement, got", form);
+    return false;
+  }
+  const error = errors.find(
+    (err) => err.type === ValidatorErrorType.ValidationError
+  );
+  if (!error) {
+    return false;
+  }
+  const focusAction = getFocusAction(form, error);
+  if (focusAction === null) {
+    return false;
+  }
+  // NOTE: We use tick here because new errors may produce layout changes.
+  return tick().then(focusAction);
+}

packages/form/src/form/component.ts

@@ -89,6 +89,7 @@ export interface HelpComponentProps {
 }
 
 export interface ErrorsListProps {
+  forId: string;
   errors: ValidationError<unknown>[];
 }
 

packages/form/src/form/templates/array-template.svelte

@@ -33,6 +33,6 @@ import { getTemplateProps } from './get-template-props.js';
   </Layout>
   {@render addButton?.()}
   {#if errors.length > 0}
-    <ErrorsList {errors} {config} />
+    <ErrorsList forId={config.idSchema.$id} {errors} {config} />
   {/if}
 </Layout>

packages/form/src/form/templates/field-template.svelte

@@ -33,7 +33,7 @@
     {@render children()}
   </Layout>
   {#if errors.length > 0}
-    <ErrorsList {errors} {config} />
+    <ErrorsList forId={config.idSchema.$id} {errors} {config} />
   {/if}
   {#if config.uiOptions?.help !== undefined}
     <Help help={config.uiOptions.help} {config} {errors} />

packages/form/src/form/templates/object-template.svelte

@@ -33,6 +33,6 @@ import { getFormContext } from '../context.js';
   </Layout>
   {@render addButton?.()}
   {#if errors.length > 0}
-    <ErrorsList {errors} {config} />
+    <ErrorsList forId={config.idSchema.$id} {errors} {config} />
   {/if}
 </Layout>