# Mobile Keyboard Avoidance

## Objective

Keep the field being typed in, and the button that submits it, visible above the keyboard.

Coordinated handling of the on-screen keyboard so the focused input and the primary action stay in view while it is open.

## Before You Begin

This feature is being added to an application that already exists and already
works. Do not scaffold a new project, and do not assume a blank slate.

Inspect the codebase first and establish:

- The existing application structure and where code of this kind already lives.
- The framework and version in use.
- The existing design system — colours, spacing, typography, and component conventions.
- Existing UI components you can reuse instead of writing new ones.
- The existing database structure, if this feature needs to persist anything.
- The existing authentication and authorization system, if this feature is user-scoped.
- Dependencies already installed, so you don't add a library that duplicates one.
- The existing test setup and conventions.

Only start writing code once you understand the above. If the application
already implements part of this feature, extend it rather than replacing it.

## Implementation Instructions

1. Identify every screen where a user types on a phone — sign-in, search, comment boxes, checkout, bottom sheets, inline table editors — and confirm for each that the focused field and its submit control remain visible with the keyboard open.
2. React to the visual viewport rather than the layout viewport. The layout viewport often does not change when the keyboard opens, so anything keyed to it will believe nothing happened while the bottom half of the screen is covered.
3. Bring the focused field into view with the smallest movement that clears the keyboard, and leave a small margin above it. Centring every focused field yanks the page around and loses the user's place in a long form.
4. Decide explicitly what fixed footers, sticky action bars, and bottom sheets do when the keyboard opens: ride above it, or unstick and return to the document flow. Both are defensible, but a footer left pinned to the old bottom edge sits underneath the keyboard and its buttons cannot be pressed.
5. Do not treat every viewport height change as a keyboard event. Pinch zoom, browser chrome retracting on scroll, and rotation all change the reported height, and scrolling the page in response to them makes the app feel possessed. Choosing which height a container is sized against belongs to Viewport Height Utility; this brief owns only the reaction to the keyboard appearing and disappearing.

## UI and UX Requirements

Match the application's existing design system exactly. Reuse its components,
spacing, and typography. This feature should look like it was always there.

## Responsive Requirements

Works on mobile, tablet, and desktop. Touch targets are large enough to hit on a
phone, and nothing overflows horizontally at 320px.

## Accessibility Requirements

- Fully keyboard navigable.
- Correct semantic elements and ARIA roles.
- Visible focus states.
- Meets WCAG AA contrast.
- Dynamic changes are announced to screen readers.
- Respects prefers-reduced-motion.

## Edge Cases

- A pinch zoom shrinks the visual viewport exactly as a keyboard does. Treating the two as the same event makes the page scroll away under the user's fingers while they are trying to read something, so distinguish them by whether an input actually holds focus and by the scale factor.
- Scrolling the page in response to focus must be predictable and minimal. An unprompted jump that moves content the user was reading, or that fires again on every keystroke as the field grows, is worse than the field being partly obscured.
- Fixed footers, sticky action bars, and bottom sheets are the usual casualties: they stay glued to the pre-keyboard bottom edge and end up behind the keyboard, taking the submit button with them. Every bottom-anchored element needs a defined keyboard behaviour, and only one of them may own the bottom edge.
- When the keyboard closes, the previous scroll position must be restored rather than left wherever the avoidance logic pushed it. Landing the user halfway down a form they had already scrolled past is disorienting.
- Different platforms report the keyboard differently and some do not report it at all until after it has finished animating, so the layout must settle correctly rather than assuming a single resize event arrives at a useful moment.
- Predictive text bars, autofill suggestion strips, and hardware keyboards attached to tablets all change the covered height without a conventional keyboard being present, so the calculation must use the measured obscured area rather than an assumed keyboard height.
- Moving focus between two adjacent fields must not re-run a full scroll animation each time. Tabbing through a form should feel continuous, not like a series of jumps.

## Testing

Exercise the feature end to end in the running application. Cover every edge case
above, then run the existing test suite and confirm nothing regressed.

## Acceptance Criteria

- [ ] The focused input and its associated submit control remain visible while the on-screen keyboard is open, on every screen where users type.
- [ ] Pinch zoom and browser chrome changes do not trigger keyboard avoidance behaviour.
- [ ] Scroll adjustments are the minimum needed to clear the keyboard and do not repeat on every keystroke.
- [ ] Every bottom-anchored element has a defined behaviour when the keyboard opens, and none is left unreachable behind it.
- [ ] Closing the keyboard restores the scroll position the user had before it opened.
- [ ] The obscured area is measured rather than assumed, so predictive bars and hardware keyboards behave correctly.
- [ ] The feature matches the existing design system.
- [ ] No existing functionality is broken.

## Adaptation Rules

- Match the existing design system. Do not introduce a new colour palette,
  spacing scale, or component library.
- Reuse existing components and utilities wherever they fit.
- Follow the naming, file layout, and code style already present.
- Do not upgrade, replace, or remove existing dependencies to make this
  feature fit. Adapt the feature to the app, not the app to the feature.
- Do not break existing functionality. If a change is genuinely required in
  existing code, make the smallest one that works and say so.
- If something in these instructions conflicts with how the application is
  built, follow the application and explain the deviation.

## Final Verification

Before you report the work as done:

1. Re-read the acceptance criteria above and check each one against what you
   actually built.
2. Run the application and exercise the feature end to end.
3. Run the existing test suite and confirm you have broken nothing.
4. Check the feature on mobile, tablet, and desktop widths.
5. Check keyboard navigation and focus handling.
6. Summarize what changed: files added, files modified, and anything you
   deliberately did differently because of how this application is built.

If any acceptance criterion is unmet, fix it before reporting completion.