fix(web): resolve 404 relationship errors and improve entity display UX

- Fix 404 errors in relationship queries by correctly parsing filter strings
  into objects for getSources, getInstitutions, getTopics, getPublishers
- Hide null, undefined, empty strings, and empty arrays from entity display
- Hide internal API URLs (works_api_url, cited_by_api_url, etc.)
- Add field label humanization utility for user-friendly field names
- Improve history fallback to show "Work W1234567..." instead of "works: W..."
- Apply humanized labels across EntityDataDisplay component

Author: Mearman

apps/web/src/components/EntityDataDisplay.tsx

@@ -36,6 +36,7 @@ import { Link } from "@tanstack/react-router";
 
 import { ICON_SIZE } from "@/config/style-constants";
 import { useVersionComparison } from "@/hooks/use-version-comparison";
+import { humanizeFieldName } from "@/utils/field-labels";
 import { convertOpenAlexToInternalLink, isOpenAlexId } from "@/utils/openalex-link-conversion";
 
 /** Section priority for consistent ordering */
@@ -65,8 +66,9 @@ const SECTION_ICONS: Record<string, import("react").ReactNode> = {
 // ============================================================================
 
 const renderPrimitiveValue = (value: unknown): import("react").ReactNode => {
+  // Don't render null/undefined - these fields will be filtered out
   if (value === null || value === undefined) {
-    return <Text c="dimmed" fs="italic" size="sm">null</Text>;
+    return null;
   }
 
   if (typeof value === "boolean") {
@@ -161,6 +163,29 @@ interface SectionData {
   icon: import("react").ReactNode;
 }
 
+/**
+ * Check if a value should be displayed (not null, undefined, empty string, or empty array)
+ */
+const isDisplayableValue = (value: unknown): boolean => {
+  if (value === null || value === undefined) return false;
+  if (typeof value === "string" && value.trim() === "") return false;
+  if (Array.isArray(value) && value.length === 0) return false;
+  return true;
+};
+
+/**
+ * Fields that should be hidden from display (internal API fields, URLs, etc.)
+ */
+const HIDDEN_FIELDS = new Set([
+  "works_api_url",
+  "cited_by_api_url",
+  "updated_date",
+  "created_date",
+  "ngrams_url",
+  "abstract_inverted_index",
+  "indexed_in",
+]);
+
 const groupFields = (data: Record<string, unknown>): SectionData[] => {
   const groups: Record<string, Record<string, unknown>> = {
     "Identifiers": {},
@@ -175,11 +200,16 @@ const groupFields = (data: Record<string, unknown>): SectionData[] => {
   const identifierKeys = ["id", "ids", "doi", "orcid", "issn", "ror", "mag", "openalex_id", "pmid", "pmcid"];
   const metricKeys = ["cited_by_count", "works_count", "h_index", "i10_index", "counts_by_year", "summary_stats", "fwci", "citation_normalized_percentile", "cited_by_percentile_year"];
   const relationshipKeys = ["authorships", "institutions", "concepts", "topics", "keywords", "grants", "sustainable_development_goals", "mesh", "affiliations", "last_known_institutions", "primary_location", "locations", "best_oa_location", "alternate_host_venues", "x_concepts"];
-  const dateKeys = ["created_date", "updated_date", "publication_date", "publication_year"];
+  const dateKeys = ["publication_date", "publication_year"];
   const geoKeys = ["country_code", "countries_distinct_count", "geo", "latitude", "longitude"];
   const basicKeys = ["display_name", "title", "type", "description", "homepage_url", "image_url", "thumbnail_url", "is_oa", "oa_status", "has_fulltext"];
 
   Object.entries(data).forEach(([key, value]) => {
+    // Skip hidden fields and non-displayable values
+    if (HIDDEN_FIELDS.has(key) || !isDisplayableValue(value)) {
+      return;
+    }
+
     const lowerKey = key.toLowerCase();
     if (identifierKeys.some(k => lowerKey.includes(k))) {
       groups["Identifiers"][key] = value;
@@ -220,10 +250,10 @@ const renderValueContent = (value: unknown): import("react").ReactNode => {
     return renderPrimitiveValue(value);
   }
 
-  // Arrays
+  // Arrays - don't render empty arrays
   if (Array.isArray(value)) {
     if (value.length === 0) {
-      return <Text c="dimmed" fs="italic" size="sm">[ ]</Text>;
+      return null;
     }
 
     // Primitive arrays - inline badges
@@ -336,7 +366,7 @@ export const EntityDataDisplay = ({ data, title }: EntityDataDisplayProps) => {
             {section.fields.map((field) => (
               <Box key={field.key}>
                 <Text size="sm" fw={600} c="blue.7" mb="xs">
-                  {field.key.replaceAll('_', ' ').replaceAll(/\b\w/g, l => l.toUpperCase())}
+                  {humanizeFieldName(field.key)}
                 </Text>
                 {renderValueContent(field.value)}
               </Box>

apps/web/src/components/layout/HistoryCard.tsx

@@ -43,6 +43,25 @@ export const HistoryCard = ({ entry, onClose, formatDate }: HistoryCardProps) =>
     enabled: !isSpecialId && !titleFromNotes,
   });
 
+  // Format entity type for display (e.g., "works" -> "Work", "authors" -> "Author")
+  const formatEntityType = (entityType: string): string => {
+    const singular = entityType.endsWith("s") ? entityType.slice(0, -1) : entityType;
+    return singular.charAt(0).toUpperCase() + singular.slice(1);
+  };
+
+  // Format entity ID for display (shortened if it's a long ID)
+  const formatEntityId = (entityId: string): string => {
+    // Extract just the ID part (e.g., "W123456789" from URL or keep as-is)
+    const idMatch = entityId.match(/([A-Z]\d+)$/);
+    if (idMatch) {
+      const id = idMatch[1];
+      // Show first letter + first few digits for readability
+      return id.length > 8 ? `${id.substring(0, 8)}...` : id;
+    }
+    // For other IDs, truncate if too long
+    return entityId.length > 15 ? `${entityId.substring(0, 15)}...` : entityId;
+  };
+
   // Determine the title to display
   let title: string;
   if (titleFromNotes) {
@@ -54,7 +73,8 @@ export const HistoryCard = ({ entry, onClose, formatDate }: HistoryCardProps) =>
   } else if (isLoading) {
     title = "Loading...";
   } else {
-    title = `${entry.entityType}: ${entry.entityId}`;
+    // Improved fallback: "Work W1234567..." instead of "works: W123456789012345"
+    title = `${formatEntityType(entry.entityType)} ${formatEntityId(entry.entityId)}`;
   }
 
   // Compute link URL - for special IDs, try to extract from notes; otherwise use entity path

apps/web/src/hooks/use-entity-relationship-queries.ts

@@ -367,6 +367,20 @@ export const useEntityRelationshipQueries = (entityId: string | undefined, entit
   };
 };
 
+/**
+ * Parse a filter string like "key:value" into an object { key: value }
+ * Used to convert filter strings for API functions that expect filter objects
+ * @param filterString - Filter string in format "key:value"
+ * @returns Object with the key-value pair
+ */
+const parseFilterStringToObject = (filterString: string): Record<string, string> => {
+  const colonIndex = filterString.indexOf(':');
+  if (colonIndex === -1) return {};
+  const key = filterString.substring(0, colonIndex);
+  const value = filterString.substring(colonIndex + 1);
+  return { [key]: value };
+};
+
 /**
  * Execute a single relationship query using the OpenAlex API or embedded data extraction
  * @param entityId
@@ -382,6 +396,8 @@ const executeRelationshipQuery = async (entityId: string, entityType: EntityType
     const pageSize = customPageSize ?? config.pageSize ?? DEFAULT_PAGE_SIZE;
 
     // Choose the appropriate API function based on target type
+    // Note: Some API functions accept `filter` (string), others accept `filters` (object)
+    // For functions expecting `filters` object, we parse the filter string into an object
     let response;
     switch (config.targetType) {
       case 'works':
@@ -402,31 +418,31 @@ const executeRelationshipQuery = async (entityId: string, entityType: EntityType
         break;
       case 'sources':
         response = await getSources({
-          filters: { id: filter }, // getSources uses 'filters' object, not 'filter' string
+          filters: parseFilterStringToObject(filter),
           per_page: pageSize,
           page,
           ...(config.select && { select: config.select }),
         });
         break;
       case 'institutions':
         response = await getInstitutions({
-          filters: { id: filter }, // getInstitutions uses 'filters' object, not 'filter' string
+          filters: parseFilterStringToObject(filter),
           per_page: pageSize,
           page,
           ...(config.select && { select: config.select }),
         });
         break;
       case 'topics':
         response = await getTopics({
-          filters: { id: filter },
+          filters: parseFilterStringToObject(filter),
           per_page: pageSize,
           page,
           ...(config.select && { select: config.select }),
         });
         break;
       case 'publishers':
         response = await getPublishers({
-          filters: { id: filter },
+          filters: parseFilterStringToObject(filter),
           per_page: pageSize,
           page,
           ...(config.select && { select: config.select }),

apps/web/src/utils/field-labels.ts

@@ -0,0 +1,175 @@
+/**
+ * Field Label Humanization Utility
+ *
+ * Provides human-readable labels for OpenAlex API field names.
+ * This centralizes the mapping to ensure consistent labeling across the UI.
+ */
+
+/**
+ * Mapping of API field names to human-readable labels.
+ * Keys are lowercase to enable case-insensitive matching.
+ */
+const FIELD_LABELS: Record<string, string> = {
+  // Identifiers
+  id: "ID",
+  ids: "External IDs",
+  doi: "DOI",
+  orcid: "ORCID",
+  ror: "ROR ID",
+  mag: "MAG ID",
+  openalex_id: "OpenAlex ID",
+  pmid: "PubMed ID",
+  pmcid: "PMC ID",
+  issn: "ISSN",
+  issn_l: "ISSN-L",
+  wikidata: "Wikidata",
+  wikipedia: "Wikipedia",
+
+  // Basic Information
+  display_name: "Name",
+  display_name_alternatives: "Name Alternatives",
+  title: "Title",
+  type: "Type",
+  type_crossref: "Type (Crossref)",
+  description: "Description",
+  homepage_url: "Homepage",
+  image_url: "Image URL",
+  thumbnail_url: "Thumbnail",
+
+  // Metrics
+  cited_by_count: "Times Cited",
+  works_count: "Works Count",
+  h_index: "H-Index",
+  i10_index: "i10-Index",
+  "2yr_mean_citedness": "2-Year Mean Citedness",
+  "2yr_cited_by_count": "2-Year Citation Count",
+  "2yr_works_count": "2-Year Works Count",
+  "2yr_i10_index": "2-Year i10-Index",
+  "2yr_h_index": "2-Year H-Index",
+  fwci: "Field-Weighted Citation Impact",
+  citation_normalized_percentile: "Citation Percentile",
+  cited_by_percentile_year: "Citation Percentile (Year)",
+  summary_stats: "Summary Statistics",
+  counts_by_year: "Counts By Year",
+
+  // Open Access
+  is_oa: "Open Access",
+  oa_status: "OA Status",
+  oa_url: "OA URL",
+  has_fulltext: "Has Full Text",
+  is_in_doaj: "In DOAJ",
+  apc_list: "APC List Price",
+  apc_paid: "APC Paid",
+
+  // Dates
+  publication_date: "Publication Date",
+  publication_year: "Publication Year",
+
+  // Geographic
+  country_code: "Country Code",
+  countries_distinct_count: "Countries",
+  geo: "Geographic Data",
+  latitude: "Latitude",
+  longitude: "Longitude",
+  city: "City",
+  region: "Region",
+
+  // Authorship & Affiliations
+  authorships: "Authors",
+  institutions: "Institutions",
+  affiliations: "Affiliations",
+  last_known_institutions: "Last Known Institutions",
+  last_known_institution: "Last Known Institution",
+  corresponding_author_ids: "Corresponding Authors",
+  corresponding_institution_ids: "Corresponding Institutions",
+
+  // Content & Classification
+  concepts: "Concepts",
+  topics: "Topics",
+  keywords: "Keywords",
+  mesh: "MeSH Terms",
+  sustainable_development_goals: "UN SDGs",
+  grants: "Grants",
+  referenced_works: "References",
+  related_works: "Related Works",
+  cited_by_api_url: "Cited By",
+
+  // Locations
+  primary_location: "Primary Location",
+  locations: "Locations",
+  best_oa_location: "Best OA Location",
+  alternate_host_venues: "Alternate Venues",
+  host_venue: "Host Venue",
+
+  // Source-specific
+  publisher: "Publisher",
+  host_organization: "Host Organization",
+  host_organization_name: "Host Organization Name",
+  host_organization_lineage: "Host Organization Lineage",
+  lineage: "Lineage",
+  associated_institutions: "Associated Institutions",
+
+  // Work-specific
+  abstract_inverted_index: "Abstract",
+  biblio: "Bibliographic Info",
+  language: "Language",
+  license: "License",
+  version: "Version",
+  is_retracted: "Retracted",
+  is_paratext: "Is Paratext",
+
+  // Other
+  x_concepts: "Concepts (Legacy)",
+  relevance_score: "Relevance Score",
+  works: "Works",
+};
+
+/**
+ * Convert an API field name to a human-readable label.
+ * Uses the predefined mapping or falls back to automatic formatting.
+ *
+ * @param key - The API field name (e.g., "2yr_mean_citedness", "cited_by_count")
+ * @returns Human-readable label (e.g., "2-Year Mean Citedness", "Times Cited")
+ */
+export function humanizeFieldName(key: string): string {
+  // Check for exact match (case-insensitive)
+  const lowerKey = key.toLowerCase();
+  if (lowerKey in FIELD_LABELS) {
+    return FIELD_LABELS[lowerKey];
+  }
+
+  // Fallback: convert snake_case to Title Case with special handling
+  return key
+    // Handle year prefix patterns like "2yr_" -> "2-Year "
+    .replace(/^(\d+)yr_/i, "$1-Year ")
+    // Replace underscores with spaces
+    .replaceAll("_", " ")
+    // Capitalize first letter of each word
+    .replace(/\b\w/g, (l) => l.toUpperCase())
+    // Handle common abbreviations that should stay uppercase
+    .replace(/\bId\b/g, "ID")
+    .replace(/\bDoi\b/g, "DOI")
+    .replace(/\bOrcid\b/g, "ORCID")
+    .replace(/\bRor\b/g, "ROR")
+    .replace(/\bOa\b/g, "OA")
+    .replace(/\bApi\b/g, "API")
+    .replace(/\bUrl\b/g, "URL");
+}
+
+/**
+ * Get label for a field, with optional custom overrides.
+ *
+ * @param key - The API field name
+ * @param customLabels - Optional custom label overrides
+ * @returns Human-readable label
+ */
+export function getFieldLabel(
+  key: string,
+  customLabels?: Record<string, string>
+): string {
+  // Check custom labels first
+  if (customLabels && key in customLabels) {
+    return customLabels[key];
+  }
+  return humanizeFieldName(key);
+}