Sprint 2 — Navigation, Filtering & Highlighting #6

New issue

Closed

opened 2026-05-19 05:04:48 +00:00 by foravo_admin · 0 comments

foravo_admin commented

2026-05-19 05:04:48 +00:00

Owner

Imported from GitHub issue conorgregson/worldbuilding-codex#22.

Source: https://github.com/conorgregson/worldbuilding-codex/issues/22
Original author: @conorgregson
Original state: closed

Goal

Make the Relationship Graph interactive by allowing users to navigate from graph nodes to entity detail pages, filter graph relationships by type, and highlight selected entity connections.

Sprint 2 should turn the graph from a static visualization into a useful lore exploration tool.

Context

Sprint 1 adds the Relationship Graph foundation by creating the route/page and rendering entities as nodes with relationships as directional edges.

Sprint 2 builds on that foundation by adding the main interaction layer:

Node navigation
Relationship type filtering
Selected entity state
Incoming and outgoing relationship highlighting
Clear/reset behavior

This sprint should make the graph more useful for understanding connected lore.

Scope

Make entity nodes clickable.
Navigate from a graph node to the matching entity detail page.
Add a relationship type filter.
Allow users to view all relationship types.
Allow users to filter graph edges by one relationship type.
Add selected entity state.
Highlight the selected entity.
Highlight incoming relationships for the selected entity.
Highlight outgoing relationships for the selected entity.
Add clear selection behavior.
Add reset filter behavior.
Add no-results messaging when filtering hides all graph relationships.
Confirm graph controls are keyboard reachable and labelled.

Acceptance Criteria

Users can click an entity node.
Clicking an entity node opens the matching entity detail page.
Users can filter relationships by relationship type.
Users can reset the relationship type filter.
Filtering updates visible graph edges without crashing.
Filtering does not permanently remove graph data.
Users can select an entity in the graph.
Selected entities are visually highlighted.
Incoming relationships for the selected entity are highlighted.
Outgoing relationships for the selected entity are highlighted.
Users can clear the selected entity.
Empty filtered results show clear no-results messaging.
Graph controls are keyboard reachable.
Graph controls have accessible labels.
No major console errors appear during graph interaction.

Optional Query Param Behavior

If useful, Sprint 2 may introduce graph-specific URL query params.

Possible params:

graphRelationshipType
graphSelectedEntity

Example:

/worlds/:worldId/graph?graphRelationshipType=ALLY&graphSelectedEntity=entity-id

If added, graph query params should be:

Refresh-safe
Browser-navigation friendly
Namespaced away from entity browsing params
Namespaced away from timeline browsing params

If this adds too much complexity, local graph state is acceptable for v1.3.

Verification Checklist

Local Verification

Run frontend build.
App runs locally.
User can log in locally.
Load a world with multiple entities and relationship types.
Open the Relationship Graph route/page.
Click an entity node.
Confirm the matching entity detail page opens.
Return to the graph page.
Filter by one relationship type.
Confirm only matching relationship edges are shown.
Reset the relationship type filter.
Confirm all relationship edges return.
Select an entity.
Confirm the selected entity is visually highlighted.
Confirm incoming relationships are highlighted.
Confirm outgoing relationships are highlighted.
Clear the selected entity.
Confirm the graph returns to its default visual state.
Trigger a filter with no matching relationships if possible.
Confirm no-results messaging appears.
Confirm graph controls are keyboard reachable.
Confirm graph controls have visible focus states.
Confirm no major console errors appear.

Production Verification

Complete after merge/deploy:

Production frontend loads successfully.
Production login works.
Production Relationship Graph route/page loads successfully.
Production graph node navigation works.
Production relationship type filtering works.
Production filter reset works.
Production selected entity highlighting works.
Production incoming/outgoing relationship highlighting works.
Production clear selection behavior works.
Production graph route refresh works.
No major production console errors appear.

Out of Scope

Graph editing.
Creating relationships from the graph.
Editing relationships from the graph.
Deleting relationships from the graph.
Drag-and-drop graph layout persistence.
Advanced graph clustering.
Graph search.
Saved graph views.
README, ROADMAP, CHANGELOG, and release notes finalization.

Notes

Node navigation should not make selection behavior confusing.
If nodes are both selectable and navigable, the interaction pattern should be obvious.
Highlighting should not rely only on color.
Relationship filtering should handle missing or inconsistent relationship types safely.
If graph query params are added, they should use the graph... namespace.

Imported from GitHub issue `conorgregson/worldbuilding-codex#22`. Source: https://github.com/conorgregson/worldbuilding-codex/issues/22 Original author: @conorgregson Original state: closed  --- ## Goal Make the Relationship Graph interactive by allowing users to navigate from graph nodes to entity detail pages, filter graph relationships by type, and highlight selected entity connections. Sprint 2 should turn the graph from a static visualization into a useful lore exploration tool. --- ## Context Sprint 1 adds the Relationship Graph foundation by creating the route/page and rendering entities as nodes with relationships as directional edges. Sprint 2 builds on that foundation by adding the main interaction layer: - Node navigation - Relationship type filtering - Selected entity state - Incoming and outgoing relationship highlighting - Clear/reset behavior This sprint should make the graph more useful for understanding connected lore. --- ## Scope - Make entity nodes clickable. - Navigate from a graph node to the matching entity detail page. - Add a relationship type filter. - Allow users to view all relationship types. - Allow users to filter graph edges by one relationship type. - Add selected entity state. - Highlight the selected entity. - Highlight incoming relationships for the selected entity. - Highlight outgoing relationships for the selected entity. - Add clear selection behavior. - Add reset filter behavior. - Add no-results messaging when filtering hides all graph relationships. - Confirm graph controls are keyboard reachable and labelled. --- ## Acceptance Criteria - [x] Users can click an entity node. - [x] Clicking an entity node opens the matching entity detail page. - [x] Users can filter relationships by relationship type. - [x] Users can reset the relationship type filter. - [x] Filtering updates visible graph edges without crashing. - [x] Filtering does not permanently remove graph data. - [x] Users can select an entity in the graph. - [x] Selected entities are visually highlighted. - [x] Incoming relationships for the selected entity are highlighted. - [x] Outgoing relationships for the selected entity are highlighted. - [x] Users can clear the selected entity. - [x] Empty filtered results show clear no-results messaging. - [x] Graph controls are keyboard reachable. - [x] Graph controls have accessible labels. - [x] No major console errors appear during graph interaction. --- ## Optional Query Param Behavior If useful, Sprint 2 may introduce graph-specific URL query params. Possible params: ```txt graphRelationshipType graphSelectedEntity ``` Example: ```txt /worlds/:worldId/graph?graphRelationshipType=ALLY&graphSelectedEntity=entity-id ``` If added, graph query params should be: - Refresh-safe - Browser-navigation friendly - Namespaced away from entity browsing params - Namespaced away from timeline browsing params If this adds too much complexity, local graph state is acceptable for v1.3. --- ## Verification Checklist ### Local Verification - [x] Run frontend build. - [x] App runs locally. - [x] User can log in locally. - [x] Load a world with multiple entities and relationship types. - [x] Open the Relationship Graph route/page. - [x] Click an entity node. - [x] Confirm the matching entity detail page opens. - [x] Return to the graph page. - [x] Filter by one relationship type. - [x] Confirm only matching relationship edges are shown. - [x] Reset the relationship type filter. - [x] Confirm all relationship edges return. - [x] Select an entity. - [x] Confirm the selected entity is visually highlighted. - [x] Confirm incoming relationships are highlighted. - [x] Confirm outgoing relationships are highlighted. - [x] Clear the selected entity. - [x] Confirm the graph returns to its default visual state. - [x] Trigger a filter with no matching relationships if possible. - [x] Confirm no-results messaging appears. - [x] Confirm graph controls are keyboard reachable. - [x] Confirm graph controls have visible focus states. - [x] Confirm no major console errors appear. ### Production Verification Complete after merge/deploy: - [x] Production frontend loads successfully. - [x] Production login works. - [x] Production Relationship Graph route/page loads successfully. - [x] Production graph node navigation works. - [x] Production relationship type filtering works. - [x] Production filter reset works. - [x] Production selected entity highlighting works. - [x] Production incoming/outgoing relationship highlighting works. - [x] Production clear selection behavior works. - [x] Production graph route refresh works. - [x] No major production console errors appear. --- ## Out of Scope - Graph editing. - Creating relationships from the graph. - Editing relationships from the graph. - Deleting relationships from the graph. - Drag-and-drop graph layout persistence. - Advanced graph clustering. - Graph search. - Saved graph views. - README, ROADMAP, CHANGELOG, and release notes finalization. --- ## Notes - Node navigation should not make selection behavior confusing. - If nodes are both selectable and navigable, the interaction pattern should be obvious. - Highlighting should not rely only on color. - Relationship filtering should handle missing or inconsistent relationship types safely. - If graph query params are added, they should use the `graph...` namespace.

foravo_admin

2026-05-19 05:04:48 +00:00