[FEATURE] UI Enhancements

[orneryd]

I feel like I am not the best at UI design, while I understand UX this also has a large API surface and I am more focued on internals, API correctness, and performance than I am at UI elements at the moment.

This would be a great first issue for anyone who is a UI expert that wants to overhaul the UI with something ✨amazing✨ to be in line with the features and provide a cleaner UX. even if you want to rewrite it in a different framework and overhaul the whole architecture, have at it.

If this takes off before I can get to the UI myself, the community can even vote on/combine the ideas people have.

https://github.com/orneryd/NornicDB/blob/main/docs/plans/ui-enhancements.md

Thanks for all of your support 🙏

[mattjanssens1]

I pulled the repo and took a closer look at the current Browser/UI structure to turn this into a more realistic estimate.

My read is that this is most likely Scenario A:

• the current Browser is still a 2-pane Cypher/Search + node details workflow
• there is no Graph Explorer tab yet
• the graph API surface described in the plan appears to be planned but not fully present in the repo yet
• there is currently no UI test harness/script in place

Given that, I’d plan this as roughly 6 phases and budget ~2 weeks for a solid implementation (closer to 10–15 working days depending on backend readiness and temporal/diff complexity).

Proposed implementation phases

1. Foundations: contracts, state, test harness

• add UI test stack
• define typed graph payloads and request/response contracts
• add graph API client methods
• introduce explicit graph state model
• refactor Browser toward orchestration-only structure

2. Graph Explorer MVP

• add Graph Explorer tab
• wire handoff from Cypher results, semantic search results, and selected node IDs
• render graph canvas with basic selection + inspector
• add loading/error/empty states

3. Neighborhood expansion + filters

• incremental expand (+1, +2, reset)
• node focus/pin
• preserve stable selection across refresh
• label and relationship-type filters
• diagnostics strip (counts, source, warnings, truncation)

4. Layout + interaction polish

• deterministic layout modes (force, radial, hierarchy)
• explicit layout controls
• keyboard support for core actions
• bidirectional table/graph highlighting where IDs are shared

5. Temporal reconstruction + diff mode

• timestamp picker
• as_of request plumbing
• compare workflows
• deterministic diff markers for added, removed, changed
• temporal context reflected in inspector/diagnostics

6. Hardening, regression coverage, docs

• unit tests for graph adapters, filters, request builders, diff mapping
• component tests for toolbar/panel/inspector behavior
• integration coverage for query/search → explorer, expansion, and temporal flows
• update docs with usage examples

Rough estimate

• Likely: ~12 working days
• Safer budget: ~15 working days
• Best case (if backend graph/temporal endpoints already exist on another branch and are stable): ~5–8 working days

Main risk

The biggest schedule risk is not the canvas itself — it’s the graph/temporal API readiness and the determinism required for asOf(...) + diff workflows.

[orneryd]

@mattjanssens1 hey that looks like a really cool plan!

notes if i may, i'd like to keep the theme with the colors, this is specifically because i want the baseline to be colorblind-accessible. there's still some cleanup to do on the colors for that on warnings and such, but having it be clearly an accessible thing. one thing i'd like to add to the overhaul is a11y and translation support to be screen-reader compatible, not that we need to translate anything yet but all the strings need colocated to prepare for translations/whitelabeling.

i would also appreciate it if we used web components as the end output. i'm a huge web components proponent, and i developed the framework that GM used for shopping tools when web components were barely getting adopted, there's some examples on my github of design systems in web components. it should serve as a good foundational reference for how i'd like to see the UI components structured in general but i don't care to micromanage or limit your options creatively. i'll get the links in a moment.

actually... chances are if it's not in web components, i might still accept it provided the UI works great, and then almost immediately rewrite it in web components, so we should probably just settle that now and skip to the end, i just know myself that way.

as you're integrating don't hesistate to reach out, i can resolve most issues relatively quickly.

Take your time though on the UI no pressure!

[orneryd]

https://github.com/orneryd/design-system

https://github.com/orneryd/web-components

examples of how i've done things in the past. And i don't mean i want it used, i just want to see frameworks used that manage things similarly with the accessibility and translations without inventing new syntax, and not in react or angular unless the final output is standard web components that don't require additional runtime dependencies.

[orneryd]

Just thought dumping right now on architecture notes.

also consider that this needs deployed behind proxies and that each UI state should be tied to url route path changes. individual components (dropdowns, accordion expansion) should be tied to url query parameter values.

this allows us to force testing state directly from the url and the url becomes the state source of truth that they ultimately pull from. Ember.js did a really good write up in their documentation about state management and the URL which i've personally adopted and implemented in my projects professionally regardless of framework or UI composition which usually leads ultimately to more deterministic and easy to reproduce error states making testing and bug reproduction a breeze.

[ USER / AUDITOR ]
                   |
                   v
    +------------------------------+
    |         BROWSER URL          | <-----------+
    | (Path: /query/results/node)  |             |
    | (Query: ?open=acc1&sort=asc) |             |
    +------------------------------+             |
           |             ^                       |
           | (1) Route   | (4) Sync              | (5) Component
           |     Change  |     Back              |     Action Updates
           v             |                       |     URL Param/Path
    +------------------------------+             |
    |      ROUTER / OBSERVER       |             |
    | (Extracts Path & SearchParams)|             |
    +------------------------------+             |
           |                                     |
           | (2) Push State                      |
           v                                     |
    +------------------------------+             |
    |    UI STATE MANAGER (SSoT)   |             |
    | (Deterministic Component Map)|-------------+
    +------------------------------+
           |
           | (3) Render / Fetch
           v
    +------------------------------+
    |    UI COMPONENTS             |
    | [Path-Bound]  [Query-Bound]  |
    |  - Views       - Accordions  |
    |  - Modals      - Dropdowns   |
    +------------------------------+
           |
           | (Data Flow via Proxy)
           v
    +------------------------------+
    |   REVERSE PROXY / GATEWAY    |
    | (Nginx / F5 / Cloud Ingress) |
    +------------------------------+
                   |
                   v
    +------------------------------+
    |        NornicDB API          |
    +------------------------------+

[mattjanssens1]

Thanks for the extra context. Based on the issue, the linked UI plan, and the follow-up notes here, I think the cleanest path is to treat this as a Browser-platform overhaul in place rather than “just add a graph canvas.”

My recommendation is to target a web-components-first architecture with URL-driven state, while preserving the existing theme and making a11y, colorblind safety, and future translation/whitelabel support first-class requirements from the start.

Proposed implementation milestones

Milestone 1: UI foundations and architecture

• Define the Browser rewrite target as standard web components with no required React/Angular runtime in the final output

• Preserve the current theme direction, but move colors into semantic design tokens

• Add a centralized string/message layer so all UI text is colocated and ready for translation/whitelabeling

• Define accessibility baselines:

  • keyboard support for all interactive controls
  • screen-reader-compatible labeling and announcements
  • focus-visible behavior
  • non-color-only status indicators

• Define a route/query-param contract so the URL is the source of truth for UI state

• Validate proxy/base-path deployment assumptions early

Milestone 2: Route-driven app shell

• Refactor Browser into a route-first shell

• Introduce stable route paths for major views, for example:

  • /query
  • /search
  • /graph

• Bind view-level state to route paths

• Bind component-level state to query params where appropriate, for example:

  • selected node
  • open accordion/panel state
  • active layout
  • filters
  • depth/expand level
  • temporal params

• Ensure browser navigation, deep linking, and shareable repro URLs work consistently

Milestone 3: Componentization

• Break the Browser into focused components instead of a single orchestration-heavy surface

• Proposed top-level component areas:

  • query view
  • semantic search view
  • graph explorer view
  • graph toolbar
  • graph canvas
  • inspector/details panel
  • diagnostics/status strip

• Create reusable UI primitives for buttons, panels, badges, empty states, and loading/error states

• Keep component APIs structured for a11y and localization from day one

Milestone 4: Graph Explorer MVP

• Add a Graph Explorer tab/view

• Wire handoff from:

  • Cypher/query results
  • semantic search results
  • direct node ID selection

• Render graph nodes/edges from normalized payloads

• Support basic node/edge selection

• Add inspector/details panel for selected entity

• Add loading, empty, error, and truncation states

• Add diagnostics strip for counts, source, warnings, and timing/context where available

Milestone 5: Interaction polish and graph controls

• Add neighborhood expansion controls, for example:

  • +1
  • +2
  • reset

• Preserve stable selection/focus across refreshes when possible

• Add focus/pin behavior for selected nodes

• Add filters for:

  • node labels
  • relationship types

• Add deterministic layout controls:

  • force
  • radial
  • hierarchy

• Sync these controls back to URL query params

Milestone 6: Temporal reconstruction and diff workflows

• Add timestamp picker / temporal controls

• Plumb as_of into graph fetch workflows

• Support compare flows such as:

  • current vs asOf(t)
  • asOf(t1) vs asOf(t2)

• Add deterministic visual markers for:

  • added
  • removed
  • changed

• Reflect temporal context clearly in inspector and diagnostics

• Ensure diff state is not communicated by color alone

Milestone 7: Testing and hardening

• Add unit coverage for:

  • graph adapters
  • request builders
  • filter logic
  • route/query-param state mapping
  • temporal diff mapping

• Add component/integration coverage for:

  • query/search -> graph handoff
  • inspector behavior
  • URL-driven repro state
  • expansion/filter/layout flows
  • temporal flows

• Add smoke coverage for keyboard navigation and screen-reader-friendly behavior

• Verify proxy/base-path deployment behavior

• Update docs with usage patterns and architecture notes

Suggested sequencing

I’d implement this in the following order so we get working value early without painting ourselves into an architectural corner:

1. Foundations / architecture
2. Route-driven shell
3. Graph Explorer MVP
4. Expansion + filters + layout controls
5. Temporal + diff
6. Hardening / docs / test coverage

Notes on scope and risk

• The graph canvas itself is not the biggest risk.
• The biggest risk is getting graph API readiness, temporal reconstruction, and deterministic URL/state behavior correct.
• Because of that, I would avoid starting with visual polish alone and instead lock down the routing/state/component contracts first.

Proposed acceptance criteria

• Query and semantic search can both open data in Graph Explorer
• Graph state is reproducible from the URL
• UI works behind proxies/base paths
• Final output is standard web components
• Strings are structured for future translation/whitelabeling
• Core flows are keyboard accessible and screen-reader compatible
• Diff/temporal states are deterministic and understandable
• Tests cover route-driven state, graph flows, and temporal behavior

If this direction sounds right, I’d start with Milestone 1 + 2 first and treat that as the architectural base for the rest of the UI overhaul.

[orneryd]

I just looked this over and it looks fantastic

[orneryd]

check out the PR #68 and let me know if you have any feedback or want the API to function a certain way. I keep that branch up to date as well so you can play with it.

[mattjanssens1]

Quick progress update from yesterday after digging into PR #68 and wiring against the graph routes it adds.

I did not try to claim the whole Browser overhaul is “done” — but I did complete a meaningful working slice of the graph side of it in the UI branch.

What got completed yesterday

Browser graph flow now covers:

• live neighborhood / expand flow
• temporal / diff flow
• basic path flow

That means the Browser work is now beyond just planning/contracts and has real UI plumbing for the core graph exploration requests.

Commits completed yesterday

• 18d122d — feat(ui): add browser temporal diff explorer slice
• acedd89 — feat(ui): add graph explorer path request flow

These build on the earlier graph foundation/client/route-state/explorer work already pushed on the same branch.

What’s in place now

• typed graph request/response contract layer
• thin graph API client methods
• route-param-synced Browser shell groundwork
• Graph Explorer handoff from Browser flows
• graph controls + diagnostics strip
• temporal/diff explorer slice
• path request flow

Implementation notes

• path controls were added in ui/src/components/browser/GraphExplorerPanel.tsx
• path helper logic lives in ui/src/components/browser/graphExplorerPath.ts
• tests for the path slice live in ui/src/components/browser/graphExplorerPath.test.ts

Validation completed

• cd ui && npm test
• cd ui && npm run build

Both passed for this slice.

Current honest status

I’d describe the Browser graph work as:

• implemented enough to exercise the graph API meaningfully from the UI, but
• not yet at the finish line for the broader UI overhaul

Still natural next steps from here are things like:

• a11y/polish
• review-response cleanup for PR feat(ui): add Browser graph explorer foundation and MVP flow #69
• smoothing graph handoff defaults / autofill
• continuing toward the larger route-driven / componentized overhaul discussed above

Also worth noting: PR #68 was the key unlock here, since it exposes the actual backend graph routes the UI can target.