feat(#10676): store geolocation when submitting contact forms

[cliftonmcintosh]

Implements a geolocation capture widget for contact forms that records GPS coordinates at
the time a contact is created or edited, along with a context question that lets the CHW
record whether they are capturing at the beneficiary's home or another location.

Resolves #10676

What this adds

A new Enketo widget (appearance="geolocation-capture") that replaces a plain text
field with an interactive GPS capture experience:

• Detects GPS availability and Android permission state at render time
• Home/other context radios embedded in the widget; capture button is disabled until a
  context option is selected ("prepare then capture" flow)
• "Press here to capture GPS location" button initiates acquisition with a 30-second
  animated progress bar
• On success: green bar + confirmation message; sets field value to "captured"
• On failure: red bar + "Retry" and "Continue without location" buttons; sets field
  value to "skipped". When signal is weak (GPS unavailable or timed out), a message
  appears above the Retry button: "GPS signal is weak. Please move to an open area and
  try again."
• Retry resets the progress bar and re-acquires from GeolocationService
• The "Continue without location" action requires the CHW to check an acknowledgement
  checkbox before the button activates

Edit mode: when a contact already has a location captured, the widget renders
differently on the edit form:

• A green badge shows "Location already saved" with the context (Home or Other) and
  the date of the last capture
• Two radio options: "Keep existing location" (pre-selected) and "Capture new location"
• Selecting "Capture new location" reveals a warning ("Are you at this household?") and
  an acknowledgement checkbox; checking the checkbox begins capture automatically
• If capture fails in edit mode, "Continue without location" reverts to the keep/capture
  choice instead of proceeding. The existing location is never discarded on a failed attempt.
• A contact whose only prior captures are failures (e.g. permission denied) is treated the
  same as a contact with no location; the widget shows in create mode.

Geolocation saved to the contact document at submit time:

{
  "geolocation": { "latitude": 1.23, "longitude": 4.56, "accuracy": 10, ... },
  "geolocation_log": [
    {
      "timestamp": 1234567890000,
      "recording": { "latitude": 1.23, "longitude": 4.56, "accuracy": 10, ... },
      "is_home": true
    }
  ]
}

• geolocation is only written when GPS capture succeeds and the context is home.
  Other-context captures are recorded in the log only.
• geolocation_log is append-only. Subsequent edits push new entries without removing
  previous ones. Each entry carries an is_home boolean derived from the context selected.
• When editing with "Keep existing location", geolocation and geolocation_log are
  left unchanged.

Form author contract

A form author adds one field per field-list group:

<group appearance="field-list" ref="/data/contact">
  <input ref="/data/contact/geo_capture" appearance="geolocation-capture">
    <label>Capture GPS location</label>
  </input>
</group>

The appearance="geolocation-capture" value is the only contract between the form and
CHT. The home/other context question is embedded in the widget and does not require a
separate XForm field. The field name (geo_capture) is arbitrary.

See the documentation added in medic/cht-docs#2221.

Widget limitation: The widget is designed for contact forms only. Placing it in a
report form is unsupported and may produce unexpected behaviour. This limitation is
documented and is under discussion for future work.

Changes

• webapp/src/js/enketo/widgets/geolocation-widget.js: new widget (create mode + edit
  mode; refactored into helper functions per UI section)
• webapp/src/js/enketo/widgets.js: widget registered
• webapp/src/ts/services/geolocation.service.ts: init() / retry() / currentHandle / currentPromise
• webapp/src/ts/services/integration-api.service.ts: exposes Geolocation on window.CHTCore
• webapp/src/ts/services/form.service.ts: injectGeoEditContext() reads existing
  location from contact and sets dataset attributes on the widget input before the form
  renders; getGeoContext() reads context from DOM at save time; saveGeo() writes
  geolocation and geolocation_log; restoreGeoFieldsIfKept() fetches the original
  doc and restores geolocation fields when the CHW keeps the existing location
• webapp/src/ts/modules/contacts/contacts-edit.component.ts: detects widget, calls
  GeolocationService.init(), passes geo handle through save pipeline
• webapp/src/css/enketo/medic.less: widget styles (progress bar animation, button
  layout, badge, warning box, success/failure colours)
• Translation keys added to messages-en.properties; translations for es, fr, ne, sw
  (ne and sw translations are machine-generated and flagged for native speaker review)
• Unit tests for all new service and widget logic
• tests/integration/cht-form/: integration tests for the geolocation widget save pipeline
• tests/e2e/default/contacts/: e2e tests for create and edit flows

A note on PR size

This PR is large, and I apologize for that. The feature required a new widget and changes to the form service. Breaking it into smaller PRs would have left each one in an incomplete or untestable state.

Of the approximately 2,860 new lines, 69% are tests and test fixtures. The production code, including CSS, is under 800 lines:

Category	New lines	Share
Tests and test fixtures	1,966	69%
Production code	765	26%
Translations	131	5%
Total	2,862

The production code breaks down as:

Type	Lines
JavaScript (widget)	384
CSS / LESS	254
TypeScript (services, components)	127
Total	765

Will reports break if they include this widget?

No. I verified that the widget behaves correctly when embedded in a report form. All CHT
form paths (reports, tasks, contacts, training cards) call geolocationService.init()
before the form renders, so currentPromise is always available and GPS capture works
as expected. I added a null guard in _startCapture() as a defensive safety net for
embeddings outside standard CHT infrastructure, and this is covered by an integration test
that explicitly clears currentPromise to exercise that path.

AI disclosure

This PR was developed with Claude Code (Anthropic) as a coding
assistant throughout the implementation. Specifically, Claude Code was used to:

• Implement production code across all phases: the Enketo widget, GeolocationService,
  form.service.ts changes, contacts-edit.component.ts changes, CSS, and translation
  strings
• Write tests following a TDD approach: failing tests were written first, then production
  code was written to make them pass
• Debug browser issues, including diagnosing that Enketo renders field-list groups as
  section.or-group-data (not .or-group) by inspecting the live DOM
• Perform a preliminary code review via Claude's /code-review ultra command
• Draft this PR description and the cht-docs documentation draft

All code was reviewed and approved by the author before committing.

Recordings and Data

Each screen recording is followed by a section with the CouchDB data captured after the scenario was finished.

Create — Successful home capture

Geo.Create.Home.Capture.mov

Create — Successful home capture: CouchDB data

{
  "_id": "019f05a0-319e-7ccf-a022-237c24b11fb6",
  "_rev": "2-ea6f9d0c8fab22b33c203f54fad07955",
  "parent": {
    "_id": "0fdfca7d-0446-4c0c-aedf-6f8b62a437f3",
    "parent": {
      "_id": "0490ad32-f955-4171-9d95-e951db7a90ec"
    }
  },
  "type": "clinic",
  "is_name_generated": "false",
  "name": "Geo Create Home Capture",
  "external_id": "",
  "notes": "",
  "contact": {
    "_id": "019f05a0-319e-7ccf-a022-2a1713b0ed32",
    "parent": {
      "_id": "019f05a0-319e-7ccf-a022-237c24b11fb6",
      "parent": {
        "_id": "0fdfca7d-0446-4c0c-aedf-6f8b62a437f3",
        "parent": {
          "_id": "0490ad32-f955-4171-9d95-e951db7a90ec"
        }
      }
    }
  },
  "geolocation": {
    "latitude": 43.06759581889168,
    "longitude": -89.45029228342403,
    "altitude": 0,
    "accuracy": 35,
    "altitudeAccuracy": null,
    "heading": null,
    "speed": null
  },
  "meta": {
    "created_by": "noble.hirthe",
    "created_by_person_uuid": "c22ef015-4233-4af4-9636-ac2fbffb4a15",
    "created_by_place_uuid": "0fdfca7d-0446-4c0c-aedf-6f8b62a437f3"
  },
  "reported_date": 1782505812382,
  "form_version": {
    "time": 1781646256080,
    "sha256": "b43227eac3f1b8ffda3145bd82c2510dc27f4c59c5f61ff71319e673204a3e01"
  },
  "geolocation_log": [
    {
      "timestamp": 1782505812418,
      "recording": {
        "latitude": 43.06759581889168,
        "longitude": -89.45029228342403,
        "altitude": 0,
        "accuracy": 35,
        "altitudeAccuracy": null,
        "heading": null,
        "speed": null
      },
      "is_home": true
    }
  ],
  "place_id": "82223"
}

Create — Successful other capture

Geo.Create.Other.Capture.mov

Create — Successful other capture: CouchDB data

{
  "_id": "019f059f-2ba4-7ccf-a022-1568e8170e67",
  "_rev": "2-65fdffca73c0da6e6e3f115816191f82",
  "parent": {
    "_id": "0fdfca7d-0446-4c0c-aedf-6f8b62a437f3",
    "parent": {
      "_id": "0490ad32-f955-4171-9d95-e951db7a90ec"
    }
  },
  "type": "clinic",
  "is_name_generated": "false",
  "name": "Geo Create Other Capture",
  "external_id": "",
  "notes": "",
  "contact": {
    "_id": "019f059f-2ba4-7ccf-a022-1fe5cc968709",
    "parent": {
      "_id": "019f059f-2ba4-7ccf-a022-1568e8170e67",
      "parent": {
        "_id": "0fdfca7d-0446-4c0c-aedf-6f8b62a437f3",
        "parent": {
          "_id": "0490ad32-f955-4171-9d95-e951db7a90ec"
        }
      }
    }
  },
  "geolocation": "",
  "meta": {
    "created_by": "noble.hirthe",
    "created_by_person_uuid": "c22ef015-4233-4af4-9636-ac2fbffb4a15",
    "created_by_place_uuid": "0fdfca7d-0446-4c0c-aedf-6f8b62a437f3"
  },
  "reported_date": 1782505745316,
  "form_version": {
    "time": 1781646256080,
    "sha256": "b43227eac3f1b8ffda3145bd82c2510dc27f4c59c5f61ff71319e673204a3e01"
  },
  "geolocation_log": [
    {
      "timestamp": 1782505745374,
      "recording": {
        "latitude": 43.06759581889168,
        "longitude": -89.45029228342403,
        "altitude": 0,
        "accuracy": 35,
        "altitudeAccuracy": null,
        "heading": null,
        "speed": null
      },
      "is_home": false
    }
  ],
  "place_id": "34721"
}

Create — Weak GPS signal (position unavailable)

Retry after failure then succeed

Geo.Create.Weak.Signal.Retry.mov

Create — Weak GPS signal (position unavailable): CouchDB data

Data after retry succeeds

{
  "_id": "019f059d-2af1-7ccf-a022-04cea36918db",
  "_rev": "2-68c7d2d566a7be2424473ea05bdfbc9c",
  "parent": {
    "_id": "0fdfca7d-0446-4c0c-aedf-6f8b62a437f3",
    "parent": {
      "_id": "0490ad32-f955-4171-9d95-e951db7a90ec"
    }
  },
  "type": "clinic",
  "is_name_generated": "false",
  "name": "Geo Create Weak Signal Retry",
  "external_id": "",
  "notes": "",
  "contact": {
    "_id": "019f059d-2af1-7ccf-a022-0a6e554c48eb",
    "parent": {
      "_id": "019f059d-2af1-7ccf-a022-04cea36918db",
      "parent": {
        "_id": "0fdfca7d-0446-4c0c-aedf-6f8b62a437f3",
        "parent": {
          "_id": "0490ad32-f955-4171-9d95-e951db7a90ec"
        }
      }
    }
  },
  "geolocation": {
    "latitude": 43.06759581889168,
    "longitude": -89.45029228342403,
    "altitude": 0,
    "accuracy": 35,
    "altitudeAccuracy": null,
    "heading": null,
    "speed": null
  },
  "meta": {
    "created_by": "noble.hirthe",
    "created_by_person_uuid": "c22ef015-4233-4af4-9636-ac2fbffb4a15",
    "created_by_place_uuid": "0fdfca7d-0446-4c0c-aedf-6f8b62a437f3"
  },
  "reported_date": 1782505614065,
  "form_version": {
    "time": 1781646256080,
    "sha256": "b43227eac3f1b8ffda3145bd82c2510dc27f4c59c5f61ff71319e673204a3e01"
  },
  "geolocation_log": [
    {
      "timestamp": 1782505614101,
      "recording": {
        "latitude": 43.06759581889168,
        "longitude": -89.45029228342403,
        "altitude": 0,
        "accuracy": 35,
        "altitudeAccuracy": null,
        "heading": null,
        "speed": null
      },
      "is_home": true
    }
  ],
  "place_id": "73623"
}

Create — Permission denied, continuing without location

Geo.Create.Permission.Denied.Skip.mov

Create — Permission denied, continuing without location: CouchDB data

{
  "_id": "019f059c-0ec1-7ccf-a021-f6b05c62aead",
  "_rev": "2-52fe7525e27e5b38f0cc906d15bce4b5",
  "parent": {
    "_id": "0fdfca7d-0446-4c0c-aedf-6f8b62a437f3",
    "parent": {
      "_id": "0490ad32-f955-4171-9d95-e951db7a90ec"
    }
  },
  "type": "clinic",
  "is_name_generated": "false",
  "name": "Geo Create Permission Denied Skip",
  "external_id": "",
  "notes": "",
  "contact": {
    "_id": "019f059c-0ec1-7ccf-a021-f99cfec3b4ef",
    "parent": {
      "_id": "019f059c-0ec1-7ccf-a021-f6b05c62aead",
      "parent": {
        "_id": "0fdfca7d-0446-4c0c-aedf-6f8b62a437f3",
        "parent": {
          "_id": "0490ad32-f955-4171-9d95-e951db7a90ec"
        }
      }
    }
  },
  "geolocation": "",
  "meta": {
    "created_by": "noble.hirthe",
    "created_by_person_uuid": "c22ef015-4233-4af4-9636-ac2fbffb4a15",
    "created_by_place_uuid": "0fdfca7d-0446-4c0c-aedf-6f8b62a437f3"
  },
  "reported_date": 1782505541313,
  "form_version": {
    "time": 1781646256080,
    "sha256": "b43227eac3f1b8ffda3145bd82c2510dc27f4c59c5f61ff71319e673204a3e01"
  },
  "geolocation_log": [
    {
      "timestamp": 1782505541363,
      "recording": {
        "code": 1,
        "message": "User denied Geolocation"
      },
      "is_home": true
    }
  ],
  "place_id": "61074"
}

Response required

Geo.Create.Required.mov

Edit — Keep existing home location

Geo.Edit.Keep.Existing.Home.mov

Edit — Keep existing home location: CouchDB data

{
  "_id": "019f057f-2002-7aa9-950b-20bd69fe157d",
  "_rev": "2-d795cc3f7aca4049fb8cec38e881dece",
  "parent": {
    "_id": "0fdfca7d-0446-4c0c-aedf-6f8b62a437f3",
    "parent": {
      "_id": "0490ad32-f955-4171-9d95-e951db7a90ec"
    }
  },
  "type": "clinic",
  "is_name_generated": "false",
  "name": "Geo Edit Keep Existing Home",
  "external_id": "",
  "notes": "",
  "contact": {
    "_id": "019f057f-2002-7aa9-950b-2da3d6c0fe9c",
    "parent": {
      "_id": "019f057f-2002-7aa9-950b-20bd69fe157d",
      "parent": {
        "_id": "0fdfca7d-0446-4c0c-aedf-6f8b62a437f3",
        "parent": {
          "_id": "0490ad32-f955-4171-9d95-e951db7a90ec"
        }
      }
    }
  },
  "geolocation": {
    "latitude": 43.06753313499881,
    "longitude": -89.450111215471,
    "altitude": 0,
    "accuracy": 35,
    "altitudeAccuracy": null,
    "heading": null,
    "speed": null
  },
  "meta": {
    "created_by": "noble.hirthe",
    "created_by_person_uuid": "c22ef015-4233-4af4-9636-ac2fbffb4a15",
    "created_by_place_uuid": "0fdfca7d-0446-4c0c-aedf-6f8b62a437f3"
  },
  "reported_date": 1782503645186,
  "form_version": {
    "time": 1781646256080,
    "sha256": "b43227eac3f1b8ffda3145bd82c2510dc27f4c59c5f61ff71319e673204a3e01"
  },
  "geolocation_log": [
    {
      "timestamp": 1782503645228,
      "recording": {
        "latitude": 43.06753313499881,
        "longitude": -89.450111215471,
        "altitude": 0,
        "accuracy": 35,
        "altitudeAccuracy": null,
        "heading": null,
        "speed": null
      },
      "is_home": true
    }
  ],
  "place_id": "72114"
}

Edit — Keep existing other location

Geo.Edit.Keep.Existing.Other.mov

Edit — Keep existing other location: CouchDB data

{
  "_id": "019f057e-1d80-7aa9-950b-14debaa5a7b3",
  "_rev": "2-ef66e3396d5ad7f3c9f9de25a29e6377",
  "parent": {
    "_id": "0fdfca7d-0446-4c0c-aedf-6f8b62a437f3",
    "parent": {
      "_id": "0490ad32-f955-4171-9d95-e951db7a90ec"
    }
  },
  "type": "clinic",
  "is_name_generated": "false",
  "name": "Geo Edit Keep Existing Other",
  "external_id": "",
  "notes": "",
  "contact": {
    "_id": "019f057e-1d80-7aa9-950b-1890909d14d2",
    "parent": {
      "_id": "019f057e-1d80-7aa9-950b-14debaa5a7b3",
      "parent": {
        "_id": "0fdfca7d-0446-4c0c-aedf-6f8b62a437f3",
        "parent": {
          "_id": "0490ad32-f955-4171-9d95-e951db7a90ec"
        }
      }
    }
  },
  "geolocation": "",
  "meta": {
    "created_by": "noble.hirthe",
    "created_by_person_uuid": "c22ef015-4233-4af4-9636-ac2fbffb4a15",
    "created_by_place_uuid": "0fdfca7d-0446-4c0c-aedf-6f8b62a437f3"
  },
  "reported_date": 1782503579008,
  "form_version": {
    "time": 1781646256080,
    "sha256": "b43227eac3f1b8ffda3145bd82c2510dc27f4c59c5f61ff71319e673204a3e01"
  },
  "geolocation_log": [
    {
      "timestamp": 1782503579050,
      "recording": {
        "latitude": 43.06758516542101,
        "longitude": -89.45028588549593,
        "altitude": 0,
        "accuracy": 35,
        "altitudeAccuracy": null,
        "heading": null,
        "speed": null
      },
      "is_home": false
    }
  ],
  "place_id": "03955"
}

Edit — Replace old home with new home

Geo.Edit.Replace.Existing.Home.mov

Edit — Replace old home with new home: CouchDB data

{
  "_id": "019f057c-c629-7aa9-950b-056d0f7248a4",
  "_rev": "3-a9c3067c8b0ac99e02eb5fd113ffcca3",
  "parent": {
    "_id": "0fdfca7d-0446-4c0c-aedf-6f8b62a437f3",
    "parent": {
      "_id": "0490ad32-f955-4171-9d95-e951db7a90ec"
    }
  },
  "type": "clinic",
  "contact": {
    "_id": "019f057c-c629-7aa9-950b-0c5a2f264c64",
    "parent": {
      "_id": "019f057c-c629-7aa9-950b-056d0f7248a4",
      "parent": {
        "_id": "0fdfca7d-0446-4c0c-aedf-6f8b62a437f3",
        "parent": {
          "_id": "0490ad32-f955-4171-9d95-e951db7a90ec"
        }
      }
    }
  },
  "is_name_generated": "false",
  "generated_name": "Geo Edit Replace Existing Home's Household",
  "name": "Geo Edit Replace Existing Home",
  "external_id": "",
  "notes": "",
  "geolocation": {
    "latitude": 43.067541260535485,
    "longitude": -89.45011125614462,
    "altitude": 0,
    "accuracy": 35,
    "altitudeAccuracy": null,
    "heading": null,
    "speed": null
  },
  "meta": {
    "created_by": "noble.hirthe",
    "created_by_person_uuid": "c22ef015-4233-4af4-9636-ac2fbffb4a15",
    "created_by_place_uuid": "0fdfca7d-0446-4c0c-aedf-6f8b62a437f3",
    "last_edited_by": "noble.hirthe",
    "last_edited_by_person_uuid": "c22ef015-4233-4af4-9636-ac2fbffb4a15",
    "last_edited_by_place_uuid": "0fdfca7d-0446-4c0c-aedf-6f8b62a437f3"
  },
  "reported_date": 1782503491113,
  "form_version": {
    "time": 1781740967855,
    "sha256": "2a52627c6226e9a7f642754f29dba55ecbf203e9293e981244dde3bb485d1e82"
  },
  "geolocation_log": [
    {
      "timestamp": 1782503491156,
      "recording": {
        "latitude": 43.06758516542101,
        "longitude": -89.45028588549593,
        "altitude": 0,
        "accuracy": 35,
        "altitudeAccuracy": null,
        "heading": null,
        "speed": null
      },
      "is_home": true
    },
    {
      "timestamp": 1782504547961,
      "recording": {
        "latitude": 43.067541260535485,
        "longitude": -89.45011125614462,
        "altitude": 0,
        "accuracy": 35,
        "altitudeAccuracy": null,
        "heading": null,
        "speed": null
      },
      "is_home": true
    }
  ],
  "place_id": "61906"
}

Edit — Replace old other with new home

Geo.Edit.Replace.Existing.Other.mov

Edit — Replace old other with new home: CouchDB data

{
  "_id": "019f0579-fdab-7aa9-950a-f6cf84a4f7e8",
  "_rev": "3-72c88ff6339b92163b2a9f9b713b4489",
  "parent": {
    "_id": "0fdfca7d-0446-4c0c-aedf-6f8b62a437f3",
    "parent": {
      "_id": "0490ad32-f955-4171-9d95-e951db7a90ec"
    }
  },
  "type": "clinic",
  "contact": {
    "_id": "019f0579-fdab-7aa9-950a-fb5c69062c44",
    "parent": {
      "_id": "019f0579-fdab-7aa9-950a-f6cf84a4f7e8",
      "parent": {
        "_id": "0fdfca7d-0446-4c0c-aedf-6f8b62a437f3",
        "parent": {
          "_id": "0490ad32-f955-4171-9d95-e951db7a90ec"
        }
      }
    }
  },
  "is_name_generated": "false",
  "generated_name": "Geo Edit Replace Existing Other's Household",
  "name": "Geo Edit Replace Existing Other",
  "external_id": "",
  "notes": "",
  "geolocation": {
    "latitude": 43.067541260535485,
    "longitude": -89.45011125614462,
    "altitude": 0,
    "accuracy": 35,
    "altitudeAccuracy": null,
    "heading": null,
    "speed": null
  },
  "meta": {
    "created_by": "noble.hirthe",
    "created_by_person_uuid": "c22ef015-4233-4af4-9636-ac2fbffb4a15",
    "created_by_place_uuid": "0fdfca7d-0446-4c0c-aedf-6f8b62a437f3",
    "last_edited_by": "noble.hirthe",
    "last_edited_by_person_uuid": "c22ef015-4233-4af4-9636-ac2fbffb4a15",
    "last_edited_by_place_uuid": "0fdfca7d-0446-4c0c-aedf-6f8b62a437f3"
  },
  "reported_date": 1782503308715,
  "form_version": {
    "time": 1781740967855,
    "sha256": "2a52627c6226e9a7f642754f29dba55ecbf203e9293e981244dde3bb485d1e82"
  },
  "geolocation_log": [
    {
      "timestamp": 1782503308752,
      "recording": {
        "latitude": 43.06758516542101,
        "longitude": -89.45028588549593,
        "altitude": 0,
        "accuracy": 35,
        "altitudeAccuracy": null,
        "heading": null,
        "speed": null
      },
      "is_home": false
    },
    {
      "timestamp": 1782504650089,
      "recording": {
        "latitude": 43.067541260535485,
        "longitude": -89.45011125614462,
        "altitude": 0,
        "accuracy": 35,
        "altitudeAccuracy": null,
        "heading": null,
        "speed": null
      },
      "is_home": true
    }
  ],
  "place_id": "66850"
}

Edit — GPS fails, revert to keep/capture choice

Geo.Edit.Home.Failed.Update.mov

Edit — GPS fails, revert to keep/capture choice: CouchDB data

{
  "_id": "019f0589-af45-7774-a1d6-fd644cee1ac4",
  "_rev": "3-4f9873d80c3907a15c63da3e9611dee9",
  "parent": {
    "_id": "0fdfca7d-0446-4c0c-aedf-6f8b62a437f3",
    "parent": {
      "_id": "0490ad32-f955-4171-9d95-e951db7a90ec"
    }
  },
  "type": "clinic",
  "contact": {
    "_id": "019f0589-af45-7774-a1d7-065fb159c6cf",
    "parent": {
      "_id": "019f0589-af45-7774-a1d6-fd644cee1ac4",
      "parent": {
        "_id": "0fdfca7d-0446-4c0c-aedf-6f8b62a437f3",
        "parent": {
          "_id": "0490ad32-f955-4171-9d95-e951db7a90ec"
        }
      }
    }
  },
  "is_name_generated": "false",
  "generated_name": "Geo Edit Home Failed Update's Household",
  "name": "Geo Edit Home Failed Update",
  "external_id": "",
  "notes": "",
  "geolocation": {
    "latitude": 43.06756903546192,
    "longitude": -89.45029771390688,
    "altitude": 0,
    "accuracy": 35,
    "altitudeAccuracy": null,
    "heading": null,
    "speed": null
  },
  "meta": {
    "created_by": "noble.hirthe",
    "created_by_person_uuid": "c22ef015-4233-4af4-9636-ac2fbffb4a15",
    "created_by_place_uuid": "0fdfca7d-0446-4c0c-aedf-6f8b62a437f3",
    "last_edited_by": "noble.hirthe",
    "last_edited_by_person_uuid": "c22ef015-4233-4af4-9636-ac2fbffb4a15",
    "last_edited_by_place_uuid": "0fdfca7d-0446-4c0c-aedf-6f8b62a437f3"
  },
  "reported_date": 1782504337221,
  "form_version": {
    "time": 1781740967855,
    "sha256": "2a52627c6226e9a7f642754f29dba55ecbf203e9293e981244dde3bb485d1e82"
  },
  "geolocation_log": [
    {
      "timestamp": 1782504337260,
      "recording": {
        "latitude": 43.06756903546192,
        "longitude": -89.45029771390688,
        "altitude": 0,
        "accuracy": 35,
        "altitudeAccuracy": null,
        "heading": null,
        "speed": null
      },
      "is_home": true
    }
  ],
  "place_id": "69814"
}

Edit — Contact with no prior location shows create mode

Geo.Edit.Add.Home.mov

Edit — Contact with no prior location shows create mode: CouchDB data

{
  "_id": "019f0529-4b50-7ff9-81e3-0c0324428a93",
  "_rev": "3-8f36f8949dc397d4ac624a796735b163",
  "parent": {
    "_id": "0fdfca7d-0446-4c0c-aedf-6f8b62a437f3",
    "parent": {
      "_id": "0490ad32-f955-4171-9d95-e951db7a90ec"
    }
  },
  "type": "clinic",
  "contact": {
    "_id": "019f0529-4b50-7ff9-81e3-12b07a080d0d",
    "parent": {
      "_id": "019f0529-4b50-7ff9-81e3-0c0324428a93",
      "parent": {
        "_id": "0fdfca7d-0446-4c0c-aedf-6f8b62a437f3",
        "parent": {
          "_id": "0490ad32-f955-4171-9d95-e951db7a90ec"
        }
      }
    }
  },
  "is_name_generated": "false",
  "generated_name": "Geo Edit Add Home's Household",
  "name": "Geo Edit Add Home",
  "external_id": "",
  "notes": "",
  "geolocation": {
    "latitude": 43.067600480568494,
    "longitude": -89.45038494284957,
    "altitude": 0,
    "accuracy": 35,
    "altitudeAccuracy": null,
    "heading": null,
    "speed": null
  },
  "meta": {
    "created_by": "noble.hirthe",
    "created_by_person_uuid": "c22ef015-4233-4af4-9636-ac2fbffb4a15",
    "created_by_place_uuid": "0fdfca7d-0446-4c0c-aedf-6f8b62a437f3",
    "last_edited_by": "noble.hirthe",
    "last_edited_by_person_uuid": "c22ef015-4233-4af4-9636-ac2fbffb4a15",
    "last_edited_by_place_uuid": "0fdfca7d-0446-4c0c-aedf-6f8b62a437f3"
  },
  "reported_date": 1782498020176,
  "form_version": {
    "time": 1781740967855,
    "sha256": "2a52627c6226e9a7f642754f29dba55ecbf203e9293e981244dde3bb485d1e82"
  },
  "geolocation_log": [
    {
      "timestamp": 1782498020218,
      "recording": {
        "code": 2,
        "message": ""
      },
      "is_home": true
    },
    {
      "timestamp": 1782498081857,
      "recording": {
        "latitude": 43.067600480568494,
        "longitude": -89.45038494284957,
        "altitude": 0,
        "accuracy": 35,
        "altitudeAccuracy": null,
        "heading": null,
        "speed": null
      },
      "is_home": true
    }
  ],
  "place_id": "49864"
}

Browser testing

The widget can be tested using the default household (clinic) creation and edit forms. The steps below assume a local dev server is running at http://localhost:5988/ with a CHW user and a health center in the contact hierarchy.

Setup

1. Apply XForm changes to the clinic forms

Three edits are needed in config/default/forms/contact/clinic-create.xml. Apply the same changes to clinic-edit.xml to test the edit flow.

In the model instance, add inside the <clinic> node:

<geo_capture/>

In the binds, add:

<bind nodeset="/data/clinic/geo_capture" type="string" required="true()"/>

In the body, add a new field-list group between the primary contact page and the household naming page:

<group appearance="field-list" ref="/data/clinic">
  <input ref="/data/clinic/geo_capture" appearance="geolocation-capture">
    <label>Capture GPS location</label>
  </input>
</group>

2. Upload the config

From config/default/:

node /path/to/cht-conf/src/bin/index.js \
  --url=http://medic:password@localhost:5988 \
  upload-contact-forms

3. Prepare the browser

• In Chrome, click the lock icon → Location → Allow for the happy path
• Hard-reload (Cmd+Shift+R) and log in as a CHW user (not admin — geolocation is disabled for admin)
• Navigate to People → health center → New Household for create paths
• Navigate to People → health center → [existing household] → Edit for edit paths

Simulating weak GPS signal

To trigger the weak signal message (GPS unavailable, code 2), use Chrome DevTools Sensors: open DevTools, press Escape to open the drawer, click the three-dot menu in the drawer tab bar, select Sensors, then set Location to Location unavailable. Keep the Chrome location permission set to Allow (blocking permission triggers code 1 instead).

Create: successful home capture

1. Open New Household, advance to the GPS page
2. Verify the capture button is disabled
3. Select Home — the button enables
4. Click the capture button; progress bar fills and turns green
5. Submit

Verify in CouchDB:

• geolocation — coordinates object
• geolocation_log[0].is_home — true
• geo_capture — "captured"

Create: successful other-context capture

Same as above but select Other as context.

Verify in CouchDB:

• geolocation — absent (only written for home captures)
• geolocation_log[0].is_home — false
• geo_capture — "captured"

Create: weak GPS signal message (codes 2 and 3)

1. Set DevTools Sensors to Location unavailable (keep Chrome permission as Allow)
2. Open New Household, select a context, click capture
3. Progress bar turns red
4. Verify the message "GPS signal is weak. Please move to an open area and try again." appears above the Retry button

Create: permission denied (code 1)

1. Set Chrome location permission to Block
2. Open New Household, select a context, click capture
3. Progress bar turns red
4. Verify no weak signal message appears; only Retry and Continue without location are shown
5. Check the acknowledgement checkbox, then click Continue without location

Verify in CouchDB:

• geolocation — absent
• geolocation_log[0].recording — { "code": 1, "message": "User denied Geolocation" }
• geo_capture — "skipped"

Create: retry after failure then succeed

1. Block location in Chrome and trigger a failure
2. Re-allow location in Chrome settings
3. Click Retry — progress bar resets and fills again, turns green on success
4. Submit and verify geolocation_log[0].is_home is present in CouchDB

Edit: keep existing location

Requires a household with a previously captured home location.

1. Open the household → Edit
2. Verify the green "Location already saved" badge shows "Captured at: Home" and a last-updated date
3. Verify "Keep existing location" is pre-selected
4. Submit without changing the selection

Verify in CouchDB: geolocation and geolocation_log are unchanged from before the edit.

Edit: capture new location

1. Open a household with an existing home location → Edit
2. Select "Capture new location"
3. Verify the warning box ("Are you at this household?") appears
4. Check the acknowledgement checkbox — capture begins automatically
5. GPS resolves → submit

Verify in CouchDB:

• geolocation — new coordinates
• geolocation_log — now has 2 entries; new entry has is_home: true

Edit: GPS fails, revert to keep/capture choice

1. Block Chrome location permission
2. Open a household with existing location → Edit
3. Select "Capture new location", check the acknowledgement checkbox
4. GPS fails — progress bar turns red
5. Click Continue without location and verify it returns to the keep/capture radio choice rather than proceeding
6. Submit with "Keep existing location"

Verify in CouchDB: geolocation is unchanged from before the edit.

Edit: contact with no prior location shows create mode

Requires a household where location was previously skipped.

1. Open the household → Edit
2. Verify the widget shows the standard capture UI (no badge, no keep/capture choice)
3. Capture a location normally

Verify in CouchDB: geolocation now has coordinates; geolocation_log has one entry.

Open questions for reviewer

1. Widget is contact-specific: as currently designed, the widget is not appropriate
   for report forms. The limitations are documented. Should the widget be renamed (e.g.
   contact-geolocation-widget.js) to make this explicit in the code? Should the UI
   language be made more generic (currently references "household")?

2. geo_capture present on failed-capture records: when GPS fails and the CHW
   continues without a location, geo_capture is set to "skipped" and saved as part
   of the form data. Is this the intended behaviour, or should the field be cleared?

3. ne/sw translations: the Nepali and Swahili translation strings for new keys are
   machine-generated. These should be reviewed by a native speaker before shipping.

---

Code review checklist

• UI/UX backwards compatible: The widget only activates on fields with
  appearance="geolocation-capture". Existing forms without this appearance are
  completely unaffected.
• Readable: Concise, well named, follows the style guide; widget refactored into
  small helper functions (one per UI section)
• Documented: Draft documentation written and available at feat(medic/cht-core#10676): store geolocation when submitting contact forms cht-docs#2221
• Tested: Unit tests (form.service, geolocation.service, integration-api.service,
  contacts-edit.component, geolocation-widget), cht-form integration tests, and e2e tests
• Internationalised: Widget UI strings in messages-*.properties for en, es, fr, ne,
  sw. ne and sw are machine-generated and flagged for native speaker review.
• Backwards compatible: No changes to existing document structure or form behaviour.
  geolocation_log is a new field; existing documents without it are unaffected.
• AI disclosure: Developed with Claude Code (Anthropic)

---

License

The software is provided under AGPL-3.0. Contributions to this project are accepted under
the same license.

[cliftonmcintosh]

I added Spanish, French, Nepali and Swahili translations to pass the linter. I did this with the help of Claude. These should be verified.

[cliftonmcintosh]

@dianabarsan Would you be available to review this PR? If not, would you be able to suggest a reviewer?

[cliftonmcintosh]

I'll move this back into draft state so that we can make updates based on the conversation from today.

[cliftonmcintosh]

Should 2 be in this set?

From what I can tell, that code is overloaded: it fires for OS Location Services being off, no network route to the location provider (desktop), and Android's WebView reporting a missing OS-level permission through this same code rather than PERMISSION_DENIED. If we include 2 in the list of weak signal codes, "GPS signal is weak, move to an open area" can show for problems that have nothing to do with signal strength, and moving won't fix them.

I don't think we have a reliable way to distinguish these cases from the code alone. Options:
(a) remove 2 from this set,
(b) leave it as one generic "GPS signal is weak..." message and accept the imprecision,
(c) word the message more neutrally ("Couldn't get a location. Check your GPS/location settings") instead of implying a signal problem specifically, or
(d) something smarter using the Android permission bridge as a signal. I tried this but ended up in a loop with the Location denied screen from cht-android appearing again and again and again and again....

[cliftonmcintosh]

@dianabarsan

I believe this is ready for re-review. A lot has changed since your earlier review. And it is SO LARGE!!!!