[docs] Update form docs for a11y (#8064)

geoffrich · web-flow · commit 5cec88b0c75d · 2022-12-10T18:31:18.000+01:00
- add labels to inputs in examples
- note that focus management applies to enhanced forms
diff --git a/documentation/docs/20-core-concepts/30-form-actions.md b/documentation/docs/20-core-concepts/30-form-actions.md
@@ -25,8 +25,14 @@ To invoke this action from the `/login` page, just add a `<form>` — no JavaScr
 ```svelte
 /// file: src/routes/login/+page.svelte
 <form method="POST">
-	<input name="email" type="email">
-	<input name="password" type="password">
+	<label>
+		Email
+		<input name="email" type="email">
+	</label>
+	<label>
+		Password
+		<input name="password" type="password">
+	</label>
 	<button>Log in</button>
 </form>
 ```
@@ -81,8 +87,14 @@ As well as the `action` attribute, we can use the `formaction` attribute on a bu
 /// file: src/routes/login/+page.svelte
 -<form method="POST">
 +<form method="POST" action="?/login">
-	<input name="email" type="email">
-	<input name="password" type="password">
+	<label>
+		Email
+		<input name="email" type="email">
+	</label>
+	<label>
+		Password
+		<input name="password" type="password">
+	</label>
 	<button>Log in</button>
 +	<button formaction="?/register">Register</button>
 </form>
@@ -179,12 +191,17 @@ export const actions = {
 ```diff
 /// file: src/routes/login/+page.svelte
 <form method="POST" action="?/login">
--	<input name="email" type="email">
 +	{#if form?.missing}<p class="error">The email field is required</p>{/if}
 +	{#if form?.incorrect}<p class="error">Invalid credentials!</p>{/if}
-+	<input name="email" type="email" value={form?.email ?? ''}>
-
-	<input name="password" type="password">
+	<label>
+		Email
+-		<input name="email" type="email">
++		<input name="email" type="email" value={form?.email ?? ''}>
+	</label>
+	<label>
+		Password
+		<input name="password" type="password">
+	</label>
 	<button>Log in</button>
 	<button formaction="?/register">Register</button>
 </form>
@@ -323,6 +340,7 @@ Without an argument, `use:enhance` will emulate the browser-native behaviour, ju
 - reset the `<form>` element and invalidate all data using `invalidateAll` on a successful response
 - call `goto` on a redirect response
 - render the nearest `+error` boundary if an error occurs
+- [reset focus](/docs/accessibility#focus-management) to the appropriate element
 
 To customise the behaviour, you can provide a `SubmitFunction` that runs immediately before the form is submitted, and (optionally) returns a callback that runs with the `ActionResult`. Note that if you return a callback, the default behavior mentioned above is not triggered. To get it back, call `update`.
 
@@ -381,6 +399,8 @@ The behaviour of `applyAction(result)` depends on `result.type`:
 - `redirect` — calls `goto(result.location)`
 - `error` — renders the nearest `+error` boundary with `result.error`
 
+In all cases, [focus will be reset](/docs/accessibility#focus-management).
+
 ### Custom event listener
 
 We can also implement progressive enhancement ourselves, without `use:enhance`, with a normal event listener on the `<form>`:
@@ -448,7 +468,10 @@ Some forms don't need to `POST` data to the server — search inputs, for exampl
 
 ```html
 <form action="/search">
-	<input name="q">
+	<label>
+		Search
+		<input name="q">
+	</label>
 </form>
 ```
 
diff --git a/documentation/docs/40-best-practices/10-accessibility.md b/documentation/docs/40-best-practices/10-accessibility.md
@@ -29,7 +29,9 @@ This will allow screen readers and other assistive technology to identify the ne
 
 In traditional server-rendered applications, every navigation will reset focus to the top of the page. This ensures that people browsing the web with a keyboard or screen reader will start interacting with the page from the beginning.
 
-To simulate this behavior during client-side routing, SvelteKit focuses the `<body>` element after each navigation. If you want to customize this behavior, you can implement custom focus management logic using the `afterNavigate` hook:
+To simulate this behavior during client-side routing, SvelteKit focuses the `<body>` element after each navigation and [enhanced form submission](https://kit.svelte.dev/docs/form-actions#progressive-enhancement). There is one exception - if an element with the [`autofocus`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/autofocus) attribute is present, SvelteKit will focus that element instead. Make sure to [consider the implications for assistive technology](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/autofocus#accessibility_considerations) when using that attribute.
+
+If you want to customize SvelteKit's focus management, you can use the `afterNavigate` hook:
 
 ```js
 /// <reference types="@sveltejs/kit" />
