Add inventory checklist for Locality-Species UI labels

OCCURRENCE_UI_RENAME_PLAN.md

@@ -0,0 +1,212 @@
+# Feature Plan: Rename “Locality-Species” UI Labels to “Occurrence(s)”
+
+## 1) Assumptions & Scope
+- This is a **UI terminology update only**: replace visible labels such as “Locality-Species”, “Locality Species”, and “Locality-Species-Cross-Search” with “Occurrence” / “Occurrences”.
+- **Database and backend persistence remain unchanged**: table names (including `now_ls`), Prisma model names, API route names, and payload contracts are not renamed.
+- Expected impact is concentrated in frontend presentation layers (navigation labels, page/tab/table captions, breadcrumbs, toolbar text, empty states, and helper text), plus any shared constants feeding those labels.
+- Backend impact is limited to optional API response metadata strings only if currently surfaced directly in UI; otherwise no backend changes.
+- Role-based authorization behavior does not change. Existing coordinator/admin restrictions remain as-is.
+- No migration should be required unless a persisted settings/config table stores user-visible caption text (unlikely; verify quickly before implementation).
+
+## 2) High-Level Plan
+1. **Inventory all user-visible strings**
+   - Search frontend and shared UI config for “Locality-Species”, “Locality Species”, and “Cross-Search” variants.
+   - Classify each usage as singular (“Occurrence”) vs plural (“Occurrences”) based on context.
+
+2. **Centralize/normalize labels where needed**
+   - If labels are scattered literals, introduce/extend a UI label constants module for this domain to reduce future drift.
+   - Keep route paths/IDs stable unless they are explicitly user-facing display text.
+
+3. **Update UI surfaces**
+   - Navigation menus, page titles, tabs, table headings, card headers, action dialogs, and search forms.
+   - Ensure document titles and route shell wrappers reflect the new term.
+
+4. **Preserve API/data compatibility**
+   - Do not rename backend endpoints, Prisma models, DB tables, or query parameters unless purely display-oriented.
+   - Keep request/response schema compatibility for frontend consumers.
+
+5. **Auth/permissions verification**
+   - Confirm that label updates do not accidentally expose hidden actions/sections.
+   - Validate coordinator-only UI controls still gate correctly after refactors.
+
+6. **Testing and QA**
+   - Frontend unit/integration tests for rendered labels and key page headings.
+   - Optional E2E smoke checks for navigation text and cross-search page captions.
+   - Run lint/type-check; update snapshots where appropriate.
+
+7. **Docs and release notes**
+   - Add a concise changelog/readme note that terminology changed in UI only.
+
+## 3) Tasks (JSON)
+```json
+[
+  {
+    "id": "T1",
+    "title": "Inventory all Locality-Species UI label usages",
+    "summary": "Locate every user-visible occurrence of Locality-Species terminology in frontend components, pages, navigation config, and tests.",
+    "app": "frontend",
+    "files_touched": [
+      "frontend/src/components/**",
+      "frontend/src/pages/**",
+      "frontend/src/App.tsx",
+      "frontend/src/router/**",
+      "frontend/src/redux/**",
+      "frontend/tests/**"
+    ],
+    "migrations": false,
+    "permissions": [
+      "No permission model changes",
+      "Verify restricted views retain existing role gates"
+    ],
+    "acceptance_criteria": [
+      "A complete checklist of UI label locations is produced",
+      "Each location is tagged as singular (Occurrence) or plural (Occurrences)"
+    ],
+    "test_plan": [
+      "Run repository search for all target label variants",
+      "Peer-review checklist against major UI routes"
+    ],
+    "estimate_hours": 1.0,
+    "priority": "high"
+  },
+  {
+    "id": "T2",
+    "title": "Replace navigation and route-shell captions",
+    "summary": "Update menu entries, breadcrumb labels, and route-level page titles from Locality-Species wording to Occurrence(s) without changing route paths.",
+    "app": "frontend",
+    "files_touched": [
+      "frontend/src/App.tsx",
+      "frontend/src/pages/**",
+      "frontend/src/components/Navigation/**",
+      "frontend/src/router/**"
+    ],
+    "migrations": false,
+    "permissions": [
+      "Visible only where existing route access is allowed",
+      "Coordinator-only routes remain coordinator-only"
+    ],
+    "acceptance_criteria": [
+      "Primary navigation no longer shows Locality-Species labels",
+      "Document titles and breadcrumbs use Occurrence/Occurrences consistently"
+    ],
+    "test_plan": [
+      "Frontend render tests for nav labels",
+      "Manual smoke test through key routes"
+    ],
+    "estimate_hours": 2.0,
+    "priority": "high"
+  },
+  {
+    "id": "T3",
+    "title": "Update table, tab, and cross-search captions",
+    "summary": "Rename captions in list/table headers, tabs, and cross-search UI text to Occurrence(s) while preserving data bindings to now_ls-backed APIs.",
+    "app": "frontend",
+    "files_touched": [
+      "frontend/src/components/**",
+      "frontend/src/pages/**",
+      "frontend/src/hooks/**",
+      "frontend/src/redux/**"
+    ],
+    "migrations": false,
+    "permissions": [
+      "No new permissions",
+      "Existing disabled/hidden controls remain unchanged"
+    ],
+    "acceptance_criteria": [
+      "All table/tab captions display Occurrence terminology",
+      "Cross-search captions no longer contain Locality-Species wording",
+      "Data loading behavior is unchanged"
+    ],
+    "test_plan": [
+      "Update/extend component tests asserting headings and tab labels",
+      "Run regression checks for list and cross-search screens"
+    ],
+    "estimate_hours": 2.5,
+    "priority": "high"
+  },
+  {
+    "id": "T4",
+    "title": "Harden consistency via shared UI label constants",
+    "summary": "Introduce or update a shared constants file for Occurrence labels to prevent future terminology drift across components.",
+    "app": "frontend",
+    "files_touched": [
+      "frontend/src/constants/**",
+      "frontend/src/components/**",
+      "frontend/src/pages/**"
+    ],
+    "migrations": false,
+    "permissions": [
+      "No permission changes"
+    ],
+    "acceptance_criteria": [
+      "Key labels are sourced from centralized constants",
+      "No duplicate legacy Locality-Species literals remain in UI code"
+    ],
+    "test_plan": [
+      "Static search confirms no legacy literals in frontend src",
+      "Type-check passes after refactor"
+    ],
+    "estimate_hours": 1.5,
+    "priority": "medium"
+  },
+  {
+    "id": "T5",
+    "title": "Validate non-functional requirements and documentation",
+    "summary": "Run lint/type-check/tests, capture visual verification, and add a documentation note clarifying UI-only terminology change with no DB/table rename.",
+    "app": "fullstack",
+    "files_touched": [
+      "README.md",
+      "CHANGELOG.md",
+      "frontend/tests/**",
+      "cypress/**"
+    ],
+    "migrations": false,
+    "permissions": [
+      "Verify UI access boundaries through smoke tests"
+    ],
+    "acceptance_criteria": [
+      "Lint and type-check complete successfully",
+      "Relevant automated tests pass",
+      "Docs explicitly state now_ls table name is unchanged"
+    ],
+    "test_plan": [
+      "npm run lint",
+      "npm run tsc",
+      "Frontend test suite for affected screens",
+      "Optional Cypress smoke for navigation/caption text"
+    ],
+    "estimate_hours": 2.0,
+    "priority": "medium"
+  }
+]
+```
+
+## 4) Risks & Mitigations
+- **Auth Failures**: UI refactors may bypass existing guard wrappers.
+  - *Mitigation*: regression-check protected routes/components with both coordinator and non-coordinator accounts.
+- **Data Migration Risk**: accidental backend renaming could break persistence contracts.
+  - *Mitigation*: explicitly prohibit DB/Prisma/API renames; no migration files in this feature.
+- **Performance**: negligible risk, but broad refactor could trigger unnecessary rerenders.
+  - *Mitigation*: keep changes text-only where possible; avoid state shape changes.
+- **Error Handling Drift**: changed labels in error banners/toasts may become inconsistent.
+  - *Mitigation*: update shared message constants and validate key failure flows.
+- **Security**: low direct risk, but route/config edits can accidentally expose links.
+  - *Mitigation*: preserve existing authorization checks and conditional rendering.
+- **Rollback**: need safe revert if terminology causes confusion.
+  - *Mitigation*: isolate commits to label updates and optional constants; revertable without schema impact.
+
+## 5) Out of Scope
+- Renaming DB tables, Prisma models, backend route paths, or API field names.
+- Legacy data migration/backfill tasks.
+- Visual redesign/theming changes beyond text replacement.
+- Full i18n localization framework rollout.
+- Unrelated performance optimizations.
+
+## 6) Definition of Done ✅
+- All approved UI surfaces use “Occurrence” / “Occurrences” appropriately.
+- No database table/model/API contract renames were introduced.
+- Unit/integration (and applicable E2E smoke) tests pass for affected areas.
+- Linting and type checks pass.
+- Role-based visibility and access behavior verified unchanged.
+- Documentation/changelog note added for terminology-only update.
+- CI pipeline succeeds.

frontend/tests/locality-species-ui-label-inventory.md

@@ -0,0 +1,54 @@
+# Locality-Species UI Label Inventory (Task T1)
+
+This checklist inventories user-visible "Locality-Species" terminology in frontend UI surfaces and maps each item to the intended replacement term.
+
+## Legend
+- **Singular target**: `Occurrence`
+- **Plural/collection target**: `Occurrences`
+
+## Inventory Checklist
+
+- [x] `frontend/src/components/NavBar.tsx` (line 23)
+  - Current UI label: `Locality-Species` (navigation item)
+  - Context: navigation entry linking to `/crosssearch`
+  - Target label: **Occurrences** (plural, module/list entry)
+
+- [x] `frontend/src/components/CrossSearch/CrossSearchTable.tsx` (line 820)
+  - Current UI label: `Locality-Species-Cross-Search` (table/view title)
+  - Context: cross-search page caption/title
+  - Target label: **Occurrence Cross-Search** (collection search surface)
+
+- [x] `frontend/src/components/Species/SpeciesDetails.tsx` (line 108)
+  - Current UI label: `Locality Species` (tab title)
+  - Context: species details tab that lists linked rows
+  - Target label: **Occurrences** (plural tab content)
+
+- [x] `frontend/src/components/Species/Tabs/LocalitySpeciesTab.tsx` (line 200)
+  - Current UI label: `Add new Locality Species` (action button text)
+  - Context: action creates one new row
+  - Target label: **Add new Occurrence** (singular action target)
+
+- [x] `frontend/src/components/Species/Tabs/LocalitySpeciesTab.tsx` (line 215)
+  - Current UI label: `Locality-Species Information` (group section title)
+  - Context: grouped information panel describing row collection
+  - Target label: **Occurrence Information** (domain section heading)
+
+- [x] `frontend/src/components/FrontPage.tsx` (line 75)
+  - Current UI label: `Locality-species` (statistics card label)
+  - Context: count of all rows in collection
+  - Target label: **Occurrences** (plural count label)
+
+## Related Non-UI Mentions (Do Not Rename in this task)
+
+These are not user-facing captions and are intentionally excluded from UI wording replacement:
+
+- Type names and identifiers (e.g. `LocalitySpecies`, `LocalitySpeciesDetailsType`) in shared/frontend TypeScript.
+- File names and test suite names that reference implementation details.
+- Export filename slug in `frontend/src/components/CrossSearch/CrossSearchExportMenuItem.tsx` (`locality-species-...csv`) unless product decides file naming should also change.
+- Internal comparisons/guards in `frontend/src/components/TableView/TableView.tsx` using the legacy title token.
+
+## Validation Notes
+
+- Search terms used: `Locality-Species`, `Locality Species`, `Locality-species`, `Locality-Species-Cross-Search`, `locality-species`.
+- Coverage scope: `frontend/src/**` and `frontend/tests/**`.
+- Result: all discovered user-visible captions are listed above and tagged with singular/plural replacement intent.