Keyboard-safe Form

1"use client";
2 
3/**
4 * KeyboardSafeForm — a mobile form that stays usable while the on-screen
5 * keyboard is open, and behaves like an ordinary form everywhere else.
6 *
7 * The hard part on mobile is that opening the virtual keyboard shrinks the
8 * *visual* viewport without shrinking the *layout* viewport, so a normal
9 * `position: fixed`/sticky footer ends up hidden behind the keyboard. This
10 * component solves that with the **VisualViewport API when it exists** and
11 * **degrades to a plain sticky footer when it doesn't** — it never depends on
12 * an unsupported "virtual keyboard" API. When the keyboard overlaps the layout
13 * viewport, the sticky action bar is lifted by exactly that overlap so Submit /
14 * Cancel stay reachable, and the focused field is scrolled into view.
15 *
16 * It is presentation-only: the **app owns the fields and the submit work**
17 * (passed as `children` + an `onSubmit` that returns a promise). The component
18 * owns the *scaffolding* production forms always need:
19 *
20 *  - A validation summary (`errors`, or an inline `onValidate` on submit) that
21 *    lists every error and links each one to its field by `fieldId`; activating
22 *    an item moves focus to that field. Submit is blocked while errors remain.
23 *  - Async submission via `useAsyncStatus`: idle → pending → success | error,
24 *    with a cancellable in-flight state, a retry on failure, and a polite live
25 *    region. Status is conveyed with icon + text, never colour alone.
26 *  - An unsaved-changes guard: when `dirty`, cancelling (or leaving the page)
27 *    asks before discarding.
28 *
29 * Accessibility & safety: labelled action buttons, `aria-live` status, focus
30 * moved to the summary on invalid submit and restored after the discard dialog,
31 * ≥44px targets, safe-area insets, 200%-zoom-safe layout, and a reduced-motion
32 * path that drops every transition while keeping the exact same behaviour.
33 * Clean-room original.
34 */
35 
36import * as React from "react";
37import { motion, AnimatePresence } from "motion/react";
38 
39import { cn } from "@/lib/utils";
40import { useReducedMotion, useAsyncStatus } from "@/lib/motiq";
41 
42/* -------------------------------------------------------------------------- */
43/* Types                                                                      */
44/* -------------------------------------------------------------------------- */
45 
46export interface FieldError {
47  /** `id` of the field this error refers to — must match the input's `id`. */
48  fieldId: string;
49// … truncated