# Google Sheets Row Sync

## Objective

Write app records into a chosen Google Sheet as clean, correctly mapped rows.

A configured append or upsert of app records into a selected spreadsheet and worksheet under an explicit column mapping.

## 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. Have the user pick the spreadsheet, the worksheet, and the field-to-column mapping explicitly at setup, and show them a sample row before the mapping is saved.
2. Resolve columns by their header text read at write time rather than by fixed position, and stop the write with a clear message when a mapped header is missing instead of writing into the neighbouring column.
3. Decide per destination whether rows are append-only or keyed. When they are keyed, carry a stable app identifier in its own column and update the matching row rather than appending a second one.
4. Neutralize any user-supplied value a spreadsheet would interpret as a formula before writing it, so a submitted field cannot execute in whoever opens the sheet.
5. Queue writes through the app's existing background-job system and batch them. Do not write a row inline during a form submission, because a slow or rate-limited provider would then make the user's submission fail.

## 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 user who reorders columns breaks a position-based mapping silently, and data keeps flowing into the wrong fields until somebody notices. Resolve by header and verify before writing.
- A mapped column that has been renamed or deleted must halt the write with a message naming the column, not drop the value or add a new column unannounced.
- A retried job with no stable key appends the same record a second time. Keyed destinations must update in place, and append-only destinations must at least be able to detect the duplicate.
- Text beginning with an equals sign, a plus, a minus, or an at sign is executed as a formula by spreadsheet software. Escape it, because an unescaped value from a public form is an attack on whoever opens the sheet.
- Provider quotas are low relative to a busy app. Batch rows and retry with backoff, holding the queue rather than discarding records once the quota is exhausted.
- Any editor can revoke access to the sheet, and the stored authorization can be revoked separately. Detect the loss, pause that destination, and tell the owner which sheet stopped and why.
- A sheet has a hard cell limit and will eventually be full. Surface that as its own condition rather than an opaque write failure.
- Dates, currency, and long numeric identifiers are reformatted on entry unless written with an explicit type. An order number arriving as scientific notation is not recoverable from the sheet.

## 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

- [ ] Spreadsheet, worksheet, and column mapping are chosen explicitly and previewed before the first write.
- [ ] Columns are resolved by header at write time, and a missing header stops the write with a named error.
- [ ] Keyed destinations update the existing row, and a retried job never produces a duplicate.
- [ ] Values that a spreadsheet would evaluate as formulas are neutralized before writing.
- [ ] Writes happen in the background, and a form submission succeeds regardless of the provider's availability.
- [ ] Revoked access, exhausted quota, and a full sheet each produce a distinct, visible state.
- [ ] 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.