GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog

Proposal: two convention-free viewer UX improvements — click-to-focus and hierarchy breadcrumb

Open
#137 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
9.2k
Forks
782
Avg merge
6h 36m
Merged PRs (30d)
85

Description

## Summary

Two small, **convention-free** enhancements to the reference viewer (`visualize`) that make any OKF bundle easier to navigate. No new frontmatter, no spec change, and no `generator.py` change — pure viewer UX, demonstrable on the shipped `ga4` bundle. Independent of the edge-detection work in flight (#48 / #66 / #110) and complementary to #122.

## Motivation

The current graph draws every concept and every link, but offers no way to (a) isolate one concept's neighborhood, or (b) see where a concept sits in the directory hierarchy. On larger bundles (e.g. `stackoverflow`) the graph is hard to read, and the detail panel gives no sense of "what else is in this group."

## What it adds

1. **Click-to-focus** — clicking a concept fades the rest of the graph by hop distance from that node (0–1 hops bright, 2 hops medium, 3+/unreachable faint), so "what connects to this" is obvious at a glance without losing the surrounding context. Clicking empty canvas or *Reset view* restores. Built on the existing `.dim` class and Cytoscape's BFS.
2. **Hierarchy orientation in the detail panel** — a breadcrumb derived from the concept-id path (e.g. `references / metrics / event_count`), plus an
"In this group" list of sibling concepts in the same directory. Both clickable. Uses data already in the graph; nothing new to author.

## Scope / conformance
- No frontmatter, no spec impact, no producer-side changes.
- Existing bundles render identically until a node is clicked.
- Changes limited to `viewer/static/viz.js`, `viewer/templates/viz.html`, `viewer/static/viz.css` (~+122 lines). `generator.py` and the graph-data
format are untouched, so the existing `pytest` viewer suite passes unchanged and `viz.js` passes `node --check`.

## Notes

Branch is ready; happy to open a PR. Can split click-to-focus and the breadcrumb into separate PRs if preferred. CLA signed.

Contributor guide

Open the contributing guide

Research direction

Start with viewer/static/viz.js, then inspect viewer/templates/viz.html and viewer/static/viz.css. Use the shipped ga4 bundle to verify click-to-focus, reset behavior, the hierarchy breadcrumb, and clickable sibling concepts; run the existing pytest viewer suite and node --check on viz.js.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
design, frontend
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.