Add alternate term names for facet terms

[Copilot]

• Add alternateName field to Term interface
• Create provider for loading alternate term names from /fe-api/alternateTermNames.json
• Update bindFacetTerms to populate alternateName from loaded map
• Update term display in Export forms to use alternateName
• Add tests for alternate term names functionality
• Run linters, formatter, and tests to validate changes
• Fix JSDoc comment and apply prettier formatting

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Support alternate term names for facet terms</issue_title>
<issue_description># Summary
Add support for alternate term names (alternateName) for faceted search terms in the UI filtering system.

Background

Currently, facet terms are represented by the Term interface:

export interface Term {
  count: number;
  name: string;
  selected: boolean;
}

There is a need to support alternate display names for facet terms. Example scenarios include synonyms, UI localization, or projects with more user-friendly phrasing.

Requirements

• Model: Add an alternateName?: string property to the Term interface.
• Population:
  • The alternate term names map shall be loaded by the app from a file at /fe-api/alternateTermNames.json in the /public folder, if it exists in the app (not in this repo).
  • This file is optional and may be absent or empty in some apps. The system must be robust to the file not existing, being empty, or not containing certain facets/terms.
  • The alternate term names map should be loaded once on app load (not per facet) and cached in memory for the duration of the session.
  • Loading and storage must be handled by a high-level provider, such as AppStateProvider or a similar top-level provider, and injected/provided throughout the app.
• Integration:
  • When creating Term objects (in bindFacetTerms in src/hooks/useFileManifest/common/utils.ts), look up the alternateName (if available) by facet and term name from the in-memory alternate term name map.
  • If not found or file is missing, default to normal name.
• Display:
  • Update the facet display code so that wherever term labels are rendered for facets, use term.alternateName ?? term.name.
  • Do not update data row/table mappers for results display—only the facet selection UI should use alternateName.

Example implementation summary and changes

1. Term Interface

export interface Term {
  count: number;
  name: string;
  selected: boolean;
  alternateName?: string;
}

2. Loading alternate term names (sample pattern)

// In AppStateProvider or similar top-level provider
const [alternateTermNames, setAlternateTermNames] = useState<Record<string, Record<string, string>> | null>(null);

useEffect(() => {
  fetch('/fe-api/alternateTermNames.json')
    .then(response => response.ok ? response.json() : {})
    .then(data => setAlternateTermNames(data))
    .catch(() => setAlternateTermNames({})); // fallback: empty map
}, []);

Then inject this map/context to wherever bindFacetTerms or its caller needs to reference alternate names.

3. Completing bindFacetTerms

accum.push({
  count: responseTerm.count,
  name,
  selected,
  alternateName: getAlternateName(facetName, name) // look up from injected/loaded alternate names map
});

getAlternateName should check the in-memory map for [facetName][name] and return undefined if missing.

4. Facet Display

Wherever facet terms are rendered, use:

{term.alternateName ?? term.name}

Notes

• The alternate term names file is NOT managed in this repo; it is app-specific and may be unavailable.
• All network/file loading for alternate names must be done once, on app load, without retries or repeated requests.
• The system must operate without errors, warnings, or visible problems if the alternate names file is missing or incomplete.
• Do not change result row/record mappers or result/table display—facet selection UI only.
• Apps with custom result row/record displays should open their own tickets as needed.
• Provide a robust fallback to always display term.name if alternateName is missing.

Acceptance criteria

• Alternate term names are loaded from the optional public/fe-api/alternateTermNames.json file by the app, once, and stored in memory.
• Facet terms can display alternate names in the filter UI.
• If the alternateName file or value is not found, fallback to the original name.
• No errors, warnings, or unnecessary fetches/retries if the file is missing.
• All requirements are validated via code review, UI verification, and tests.
• Includes tests for:
  • Fallback behavior if no file or key is present.
  • Proper use of alternateName in the facet UI when present.</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Support alternate term names for facet terms #730

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[NoopDog]

Initial plan looks blank. Everything ok?

[Copilot]

Pull request overview

This pull request adds support for alternate display names for facet terms in the UI filtering system. Facet terms can now show user-friendly names (e.g., "Human" instead of "Homo sapiens") while maintaining original values for filtering operations. The alternate names are loaded from an optional JSON configuration file.

Key changes:

• Added AlternateTermNamesProvider that loads alternate names from /public/fe-api/alternateTermNames.json once on mount
• Extended Term interface with optional alternateName property
• Updated facet binding logic to populate alternate names and modified export forms to display them

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/hooks/useFileManifest/common/entities.ts	Added optional alternateName property to Term interface
src/providers/alternateTermNames/alternateTermNames.tsx	Created provider to load and cache alternate term names from JSON file
src/providers/alternateTermNames/useAlternateTermNames.ts	Created hook to access alternate term names from context
src/providers/alternateTermNames/utils.ts	Added utility function to look up alternate names by facet and term
src/hooks/useFileManifest/useFetchFilesFacets.ts	Integrated alternate term names into facet fetching hook
src/hooks/useFileManifest/common/utils.ts	Updated facet binding functions to accept and propagate alternate term names
src/components/Export/components/ExportForm/components/ExportSpeciesForm/exportSpeciesForm.tsx	Updated to display alternate name if available
src/components/Export/components/ExportForm/components/ExportFileSummaryForm/exportFileSummaryForm.tsx	Updated to display alternate name if available
tests/alternateTermNames.test.tsx	Added comprehensive tests for provider, hook, and utility functions
tests/bindFacetTerms.test.ts	Added tests for alternate name population in facet binding
docs/ALTERNATE_TERM_NAMES.md	Added detailed documentation covering setup, behavior, and usage

[Copilot]

The return description "something" is not descriptive. It should be updated to accurately describe what the function returns, such as "file facet with populated terms and selected state" or similar.

Suggested change

	* @returns something.
	* @returns File facet with populated terms and selected state.

[Copilot]

Fixed in commit ded05c8. Updated the JSDoc return description to "File facet with populated terms and selected state."

[NoopDog]

@copilot please run prettier with the appropriate version to address the runcheck issues

[Copilot]

@copilot please run prettier with the appropriate version to address the runcheck issues

Prettier formatting applied in commit ded05c8. All files now pass prettier check with version 2.8.3 as specified in package.json.