transcription/docs/ui/pages/people.md

People Page Contract

Purpose

People manages reusable historical-person records. A Person may appear in many Documents under different relationship roles and may optionally carry one or more photos plus a FamilySearch identifier.

Routes

Route	Purpose
/people	Searchable People list.
/people/new	Create a Person.
/people/{person_id}	View one Person and linked Documents.
/people/{person_id}/photos	Manage Person photos.
/people/{person_id}/edit	Edit the Person.
/people/{person_id}/delete	Confirm permanent deletion.

List Behavior

• The title is Archival Entities: People.
• Create new person opens the create route.
• The table defaults to Full Name order and supports search and column sorting.
• Columns are Full Name, FamilySearch ID, Birth Date, Death Date, and # Documents.
• Full Name is left-aligned; FamilySearch ID, date columns, and # Documents are centered.

• Documents reflects how many linked Documents each Person is connected to.

• Birth and death values independently prefer exact date, then approximate date, then Unknown.
• Selecting a row opens Person Detail.
• No records displays No person records found in repository.

Create and Edit Behavior

Required:

• Full name.

Optional:

• Display name and maiden name.
• Exact and approximate birth/death dates.
• Birth/death places.
• Biography.
• FamilySearch ID.

Rules:

• Missing Full name blocks save with a warning.
• Exact date inputs are native browser date inputs.
• FamilySearch IDs are normalized and validated by PeopleService.
• Photos are managed on Person Detail (not in create/edit form fields).
• Metadata JSON remains hidden.
• Save success returns to Person Detail.

Detail Behavior

• The header provides New Document, Edit Person, and Delete.
• New Document opens Document creation with this Person requested for author preselection.
• Person Detail shows a single-photo viewer with Previous/Next navigation; the page-level Edit Photo(s) header action opens photo management.
• Photo management (upload, description edit, set-primary, delete) is intentionally moved to /people/{person_id}/photos.
• Biographical Record shows names, compact birth/death dates, and places.
• Birth and death place values are clickable links to Google Maps when present.
• FamilySearch ID is shown as a metadata value and is clickable to the FamilySearch person details route when present.
• Maiden Name is only shown in Biographical Record when a value exists.
• Biography has an explicit empty value.
• Linked Documents render as a table with Document Name, Role, and Number of Pages; selecting a row opens Document Detail.
• No links shows both an empty state and guidance to link from a Document workflow.
• System Logistics shows created and updated timestamps.

Delete Behavior

• The page warns when linked Document relationships exist.
• Delete is blocked when related Photos exist.
• Confirmed deletion removes the Person and its relationship links; it does not delete Documents.
• Success returns to the People list.
• Missing or already-deleted records return to a safe list state.

Photo Gallery Behavior (/people/{person_id}/photos)

• Upload is triggered from a header-level Upload Photo(s) control beside Back to Person.
• The gallery renders all photos in a responsive grid (3-4 tiles wide on larger screens).
• Description text is shown as an overlay at the bottom of each image for quick context.
• The editor provides Save Description, Set Primary (when applicable), and Delete Photo actions.

Acceptance Checklist

• List fields, alignment, date fallback, search, sorting, and navigation match this contract.
• Full name is enforced on create and edit.
• FamilySearch ID validation and link generation use the fixed supported identifier format.
• Photo upload and rendering remain constrained to supported media paths.
• New Document carries the Person context.
• Linked Documents show the correct role and target.
• Delete wording distinguishes removal of relationship links from deletion of Documents.

Implementation Anchors

• src/transcription/ui/pages/people_page.py
• src/transcription/ui/components/table/people.py
• src/transcription/services/people.py
• tests/ui/test_people_page.py
• tests/services/test_v2_crud.py

Deferred Work

• Structured name fields, merge/deduplication, advanced metadata editing, and Person-side relationship editing are not current behavior.