fix(event-display,app): make "Color Options → Color by" work for tracks and document the full event data format

[EdwardMoyse]

Fixes #948

Problem

As reported in #948, the "Color Options → Color by" feature for track collections
appeared in the UI but had no visible effect, and "Color by Vertex" in particular
seemed inactive. This turned out to be several compounding issues:

• The default charge colors (and momentum min/max colors) were all #ff0000 —
  identical to the default track color — so applying them repainted red-on-red.
• Momentum coloring bucketed tracks into two colors split at the midpoint of the
  min/max range, with strict bounds that left tracks at or outside the range
  uncolored entirely.
• Color by vertex requires vertices with linkedTracks/linkedTrackCollection
  data (only produced by the JiveXML loader), but the option was offered for
  every Tracks collection and silently did nothing otherwise. Even when links
  existed, it could not match a collection named Tracks (renamed to Tracks_
  on load while the vertex links kept the raw name), track indices were
  misaligned when bad tracks were dropped, and all vertices shared a single
  color so "coloring by vertex" produced one uniform color.
• The grouped "color by" swatches were applied when the menu was built,
  stomping collection colors at startup.
• Loading a saved menu state (e.g. the ATLAS demo's atlas-config.json)
  overwrote the select's structural options list and the color defaults with
  stale saved values, resurrecting the "Vertex" option for every collection.

Changes

phoenix-event-display

• Distinct defaults: charge is blue / grey / red for q = −1 / 0 / +1; momentum
  is a blue→red gradient interpolated over the min/max slider range
  (replacing the midpoint bucketing), via a new
  ColorManager.colorObjectsByComputedColor.
• colorTracksByVertex rewritten: each vertex and its linked tracks get a
  distinct deterministic color (golden-ratio hue steps, honoring an explicit
  vertex color), tracks are matched by their original index when available,
  and the number of colored tracks is returned so a warning can be logged when
  nothing matched.
• The JiveXML loader applies the Tracks → Tracks_ rename consistently to
  vertex linkedTrackCollection and records each track's original index.
• The Vertex option is only offered for collections that vertices actually
  link to: PhoenixLoader inspects the event data and passes the applicable
  ColorByOptionKeys through UIManager.addCollection (new optional trailing
  parameter, fully backward compatible).
• applyConfigState no longer fires grouped color configs when configs are
  added (only when restoring a saved state), so collection colors are no longer
  overridden at startup.
• The "Color by" selection is stored in the select config (ConfigSelect.value)
  and re-applied on state load; a saved state can no longer overwrite a select's
  structural options list.

phoenix-ng

• The phoenix menu dropdown binds to the stored config value so a restored
  "Color by" choice is reflected in the UI.
• The ATLAS demo's atlas-config.json had its 64 stale color-by configs
  removed (old 3-entry option lists and all-red swatches for 8 collections).

Documentation

• guides/developers/event_data_format.md now documents every attribute the
  loaders actually read, verified against the loader code: previously missing
  Track attributes (with a note on which are auto-derived), Jets origins, the
  CircularPoint hit type, CaloCluster/CaloCell placement and sizing
  attributes, an IrregularCaloCells section, Vertex size/vertexType/
  vertex–track links, Muons/Electrons/Photons compound-object linking, the
  per-type cut sliders, and the "Color by" attributes. It also fixes documented
  keys that the code never read (qOverP, lumiblock vs lumiBlock).
• The stale, diverged copy of this information in guides/users.md is replaced
  with a link to the format guide.

Tests

New jest suites (were previously none for this area): ColorOptions (option
wiring, charge predicate, momentum gradient, vertex warning, select state),
ColorManager (computed coloring, per-vertex track coloring, index matching,
graceful no-ops), JiveXMLLoader (rename, original indices, vertex links),
PhoenixMenuNode (state-load semantics), plus a full-chain integration test
(JiveXML → buildEventData → real UIManager/PhoenixMenuUI → menu tree).

Manually verified on the ATLAS demo: charge/momentum/vertex coloring all have
visible effects on InDetTrackParticles_xAOD; the Vertex option is absent for
collections without vertex links (e.g. Tracks_), both with and without the
demo config being loaded.

🤖 Generated with Claude Code