#800 Notes Report: Type filter + drop hardcoded Kind enum for a Manage Notes name registry (phased, follow-on to SF #798/#799)
Follow-on from live-testing SF #799 (native Notes Report) and SF #798 (JSON Note
structured field editor) -- a set of related, phased improvements the user raised
while clicking through the shipped build. Captured together since they're one
coherent direction, to be picked up in phases against this one ticket rather than
scattered across several.
Phase 1 -- Notes Report: split "Kind" into two independent concepts
Today the Notes Report's single "Kind" filter conflates two different things: the
note's native type (Text/Weblink/Document/JSON -- a real closed set, enum
noteCommands in note.h) and, only for JSON Notes, the semantic "kind" value in the
JSON body (station/industry/etc, currently a fixed 6-value enum matching SF #795's
schema table). User's ask: separate these into two dropdowns.
- New "Type" filter: All Types / Text / Weblink / Document / JSON -- a fixed
dropdown (genuinely closed set, safe to hardcode same as the existing Kind
dropdown is today). When Type is anything but JSON (or "All Types"), the
kind-related filter/grouping below doesn't apply. - The existing "Filter..." button (Layer/Group scope, shared mechanism every
report uses) needs a clearer label once there's a second filter concept in the
same dialog -- e.g. rename to "Layer Filter..." for this report specifically
(each report's button label is already set independently in its own .ui file,
so this doesn't touch the other six reports).
Phase 2 -- drop the hardcoded Kind enum in favor of free-text + a managed-name
registry
User's core objection: hardcoding station/industry/storage/yard_track/house_track/
reference into reportsNoteKind_e (reports.h) couples this report to SF #795's
specific schema choices, and doesn't scale to whatever "kind" values a user
actually types in practice (confirmed live: the test session immediately produced
JSON Notes with ad-hoc ROOT-level fields -- "spots", "meta", "message" -- that
don't fit any of the 6 planned kinds).
Agreed direction (not yet built):
- Replace the fixed Kind dropdown with a way to filter/group by name --
specifically, ROOT-level field names actually present across the layout's JSON
Notes (one level deep only, matching the structured field editor's own Object-
dropdown scope -- see SF #798), not a hardcoded list. - This becomes a "Manage Notes" function/dialog (name TBD) where the user
explicitly registers which ROOT-level names are meaningful enough to group/filter
by. Explicitly NOT auto-populated from a live scan of the file (that was
discussed and rejected) -- the user types the name they want tracked (or picks
it from a search, if a search-assist is added later; not required for a first
version). "ALL" remains the only default with nothing registered. - Notes Report grouping (both the interactive list and the Save/Print text,
ReportsFormatNoteList()) should be restructured: group by Type first (Text /
Weblink / Document / JSON), then within JSON, sub-group by a managed name if one
matches; otherwise all JSON notes collapse into one flat "ROOT" section. Until
Manage Notes exists and something is actually registered, that registry is empty
by default, so every JSON note falls under "ROOT" -- this is the correct/expected
interim state, not a bug, and the report-side grouping logic should be written to
degrade to exactly that (Type-only grouping, no further JSON sub-grouping) rather
than assuming Manage Notes ships in the same pass. reportsNoteRow_t.kind(currentlyreportsNoteKind_e) would need to become a
string (the literal name/value found) instead of a fixed enum, and
ReportsNoteKindFromJson()/ReportsNoteLabelField()(reportsformat.c) would be
replaced or reworked accordingly.
Phase 3 -- the "Manage Notes" dialog itself
Scoped as a separate, dedicated feature (not folded into the report, which stays
report-only/read-plus-navigate) -- an editable browser/manager for notes and the
name registry described in Phase 2, conceptually closer to a "Manage Layers"-style
dialog than to the existing read-only Reports viewer. Not designed in detail yet;
revisit once Phase 1/2 are in and there's a clearer picture of what "managing"
concretely needs to cover beyond registering grouping names.
Status: none of these three phases started. SF #798/#799 ship as-is (fixed 6-kind
enum, no Type filter) with this ticket tracking the improvement path agreed on
2026-09-16 during live testing.
Discussion
Anonymous
Phase 1 implemented: added a Type dropdown (All Types/Text/Weblink/Document/JSON)
to the Notes Report, independent of the existing Kind dropdown (which stays
JSON-only). Also renamed the Layer/Group scope button from "Filter..." to
"Layer Filter..." per the ambiguity noted above.
Type and Kind combine with AND logic (e.g. Type=Text + Kind=Station correctly
returns zero rows, since Kind only applies to JSON Notes).
Live-verified via Xvfb: all 5 Type options present, filtering by Type alone
works, Type+Kind combination works including the empty-list mismatch case,
button rename confirmed, click-to-navigate (from the earlier phase) still
works with the new filter row in place. 76/76 local tests pass.
Git PR: https://github.com/adbyrne/XTrkCAD/pull/205 (GTK3V2MAIN)
Kind still uses the hardcoded reportsNoteKind_e enum -- phase 2+ (dropping
that for a user-managed "Manage Notes" name registry) is deferred, tracked
under this same ticket per the phased-approach agreement.
Phase 2 progress update.
PR #209 (not yet merged, GTK3V2MAIN): https://github.com/adbyrne/XTrkCAD/pull/209
While implementing the JSON-note grouping filter, a design flaw surfaced: the original plan
grouped notes by the value of a "kind" field, against a registry of allowed value-strings.
That doesn't match how the Manage Notes / JSON Note editing UI actually works, which is
Name:Value pairs at the ROOT level of the note. There's no single "kind" field a user would
naturally fill in, so the value-based design didn't correspond to anything a user would
actually enter.
Corrected design: notes are now grouped by which ROOT-level field NAME a JSON note has,
matched against a registry of names that will eventually be populated by a "Manage Notes"
dialog (phase 3, not yet built). For example, if the registry contains "spots" and a note
has a ROOT-level "spots" key, that note groups under "spots"; a note with no matching
ROOT-level field name groups under "ROOT". This is a presence check on the field name, not
a comparison against any field's value.
To reflect this, the "Kind" filter/column has been renamed to "ROOT Names" throughout (the
dropdown widget, the report's column header, the underlying .ui widget IDs, and the
in-repo docs at app/doc/reportsm.dox), since "Kind" implied a single classifying value which
isn't what the feature actually does.
Phase 3 (the Manage Notes dialog that lets a user register ROOT-level names, including a
"search for names" convenience) is not yet built. Until it exists, the name registry is
always empty, so the ROOT Names dropdown only offers "All ROOT Names" and every JSON note
groups under "ROOT". This is a registration gap, not a data gap -- it applies even to files
that already contain JSON Notes with real ROOT-level fields.
76/76 tests pass (CMocka unit suite + regression suite), including 4 new unit tests
directly exercising ReportsNoteResolveGroup()'s field-name-presence matching, registry-order
priority, and empty-registry fallback behavior.
Holding PR #209 for review before merging.
Phase 3 progress update.
PR #210 (not yet merged, GTK3V2MAIN): https://github.com/adbyrne/XTrkCAD/pull/210
Builds the "Manage Notes" dialog that phase 2 left as a stub -- the registry of
ROOT-level names the Notes Report's "ROOT Names" filter groups/filters by.
New dialog under Manage -> "Notes ...": Add/Delete a name, plus a "Search for
Names" button that scans the layout's own JSON Notes for ROOT-level field
names not yet registered and adds them automatically.
Deliberately scoped to registry management only, not a full note browser or
editor -- that's a separate, bigger idea the original ticket text mentioned,
left for a later phase if it's ever wanted.
The registry is stored as plain lines in the .xtc file itself (not an app
preference), so a future MCP-side JSON Note reader could read the exact same
registry a user builds natively in this dialog.
A real bug turned up during live testing: the first version of this used a
file-format line starting with "NOTENAME", which -- it turns out -- collides
with the existing "NOTE" track-object type's own file parser (which matches
on a plain text prefix with no word-boundary check). A NOTENAME line was
silently swallowed by the NOTE reader instead of reaching the new registry
code, producing a confusing "expected integer" error on load. Fixed by
renaming the keyword to "MANAGENOTES", which doesn't collide with anything.
Caught only because I did a full save-quit-relaunch cycle rather than trusting
the test suite alone -- none of the existing regression tests exercise this
new line type.
77/77 tests pass. Full Xvfb click-through: Search for Names found the 9 real
ROOT-level names already in use across a converted real layout's 45 JSON
Notes; Add/Delete both work; the Notes Report's ROOT Names dropdown now
actually populates and filters correctly; a save/quit/relaunch cycle confirmed
the registry persists and reloads correctly.
This completes all three phases of this ticket. Holding PR #210 for review
before merging.
Hg branches for phase 2 (bug-800-notesreport-managenotes-kind-gtk3) and phase 3 (bug-800-notesreport-managenotes-dialog-gtk3) are now pushed to SF, alongside phase 1 already there. All three phases are on git GTK3V2MAIN and ready for review; still held out of Hg mainline pending the Layer Groups review.