feat: DH-21898: Local routing by jnumainville · Pull Request #1348 · deephaven/deephaven-plugins

jnumainville · 2026-05-08T18:00:25Z

Adds local routing, as described in the plan

Copilot

Pull request overview

Adds local (widget-scoped) routing support to the Deephaven UI plugin by synchronizing richer URL state between the browser and backend, introducing new routing hooks/components, and documenting/testing the new API surface.

Changes:

Extend URL state syncing (path, absolute path, fragment, href, plus query params) and make navigation-triggered URL updates propagate to the backend.
Add Python routing primitives: use_path, use_navigate, use_params, use_url_components, plus route/router components and link(to=...) SPA navigation.
Add unit + e2e coverage and documentation pages for the new routing features.

Reviewed changes

Copilot reviewed 33 out of 33 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
tests/ui_routing.spec.ts	New Playwright e2e coverage for routing hooks/components.
tests/app.d/ui_routing.py	Adds UI panels used by routing e2e tests (and examples for hooks/components).
plugins/ui/test/deephaven/ui/test_utils_root.py	Extends test root to carry additional URL fields.
plugins/ui/test/deephaven/ui/test_routing.py	Adds Python unit tests for routing hooks and router matching behavior.
plugins/ui/src/js/src/widget/WidgetUtils.tsx	Moves `Link` import to the plugin elements export location.
plugins/ui/src/js/src/widget/WidgetHandler.tsx	Captures/sends extended URL state; provides navigate callback via context; listens for URL change events.
plugins/ui/src/js/src/widget/WidgetHandler.test.tsx	Updates tests for extended URL state + navigation behavior.
plugins/ui/src/js/src/events/NavigateContext.ts	New context to provide widget-scoped navigation callback to children.
plugins/ui/src/js/src/events/Navigate.ts	Enhances Navigate to support path/fragment + emits URL-changed event; exports URL state param keys.
plugins/ui/src/js/src/events/Navigate.test.ts	Adds unit tests for Navigate and widget-relative path parsing.
plugins/ui/src/js/src/elements/Link.tsx	New frontend Link element that can invoke SPA navigation via NavigateContext.
plugins/ui/src/js/src/elements/index.ts	Exposes new `Link` element export.
plugins/ui/src/deephaven/ui/types/types.py	Adds `NavigationTarget` type; documents `QueryParams` usage.
plugins/ui/src/deephaven/ui/object_types/ElementMessageStream.py	Stores and updates extended URL state fields; applies URL-state updates from client.
plugins/ui/src/deephaven/ui/hooks/use_url_components.py	New hook to access split URL components from href.
plugins/ui/src/deephaven/ui/hooks/use_path.py	New hook to access widget-relative vs absolute path.
plugins/ui/src/deephaven/ui/hooks/use_params.py	New hook to access matched router params via context.
plugins/ui/src/deephaven/ui/hooks/use_navigate.py	New hook to send navigate events (path/query/fragment/replace) to frontend.
plugins/ui/src/deephaven/ui/hooks/init.py	Exports new routing hooks.
plugins/ui/src/deephaven/ui/components/router.py	New router implementation (compile/match routes, provide params context).
plugins/ui/src/deephaven/ui/components/route.py	New `route()` factory / `_Route` dataclass.
plugins/ui/src/deephaven/ui/components/link.py	Adds `to=` SPA navigation support for `ui.link`.
plugins/ui/src/deephaven/ui/components/init.py	Exports new `route` and `router` components.
plugins/ui/src/deephaven/ui/_internal/RootRenderContextProtocol.py	Extends protocol with path/fragment/href accessors.
plugins/ui/src/deephaven/ui/_internal/RenderContext.py	Imports and exposes extended URL state fields.
plugins/ui/docs/sidebar.json	Adds docs entries for new routing hooks/components.
plugins/ui/docs/hooks/use_url_components.md	New docs page for `use_url_components`.
plugins/ui/docs/hooks/use_path.md	New docs page for `use_path`.
plugins/ui/docs/hooks/use_params.md	New docs page for `use_params`.
plugins/ui/docs/hooks/use_navigate.md	New docs page for `use_navigate`.
plugins/ui/docs/components/router.md	New docs page for `router`/`route`.
plugins/ui/docs/components/link.md	Updates link docs to include SPA navigation via `to`.
.github/skills/writing-docs/SKILL.md	Adds internal documentation-writing guidance for contributors.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

margaretkennedy · 2026-05-11T17:51:50Z

+1. Static segments are preferred over parameterized segments.
+2. Longer matches (more segments) are preferred over shorter ones.
+3. Wildcard routes (`*`) have the lowest priority.
+4. Optional segments are matched greedily.


I assume "greedily" will be a familiar term to your target audience?

Generally yes, but there's a clearer way to phrase it anyways.

margaretkennedy

Docs look good, minor comments

github-actions · 2026-05-11T21:34:08Z

ui docs preview (Available for 14 days)

github-actions · 2026-05-11T21:40:15Z

ui docs preview (Available for 14 days)

github-actions · 2026-05-12T15:42:27Z

ui docs preview (Available for 14 days)

github-actions · 2026-05-12T17:28:03Z

ui docs preview (Available for 14 days)

github-actions · 2026-05-13T17:24:39Z

ui docs preview (Available for 14 days)

github-actions · 2026-05-13T17:34:06Z

ui docs preview (Available for 14 days)

mofojed · 2026-05-14T20:53:53Z

        logger.debug("Setting URL state: %s", url_state)
-        self.set_query_params(url_state.get("__queryParams", {}))
+        if "__queryParams" in url_state:
+            self.set_query_params(url_state["__queryParams"])


_UrlState should have all these parameter types I guess?
Actually why are we passing a whole dictionary of the parsed URL over the wire, and then storing it as separate parts here? I think we should just pass the URL as a string over the wire, and then we can parse out the components from that. Then we only need to store the URL, and it's consistent (e.g. absolute_path and path wouldn't get out of sync)

I think the main reason was the incremental change from query params. I'll rework the logic to be on the python side.

mofojed · 2026-05-14T20:57:39Z

        """
        return self._root.get_query_params()

+    def get_path(self) -> str:


Ditto - we should just be storing this all as the whole URL, and parse from the same source.

mofojed · 2026-05-14T20:59:11Z

@@ -35,3 +35,35 @@ def get_query_params(self) -> QueryParams:
    def set_query_params(self, query_params: QueryParams) -> None:
        """Update the URL query parameters."""
        ...


We should just have a get_url/set_url methods, instead of all these separate methods. Then in use_navigate and all the other hooks, we can parse/mutate as necessary.
We should have one source of "truth" as to what URL the client is actually at right now.

github-actions · 2026-05-18T20:43:35Z

ui docs preview (Available for 14 days)

github-actions · 2026-05-19T13:38:40Z

ui docs preview (Available for 14 days)

github-actions · 2026-05-19T21:19:31Z

ui docs preview (Available for 14 days)

margaretkennedy · 2026-05-20T12:19:48Z

+Consider using [`action_button`](./action_button.md) for task-based actions.
+```
+
+## Screenshots


what about adding a few style notes? "prefer active voice", "sentence case for headings" if you want the docs to match the other user guides on deephaven.io?

mofojed

Also some e2e tests failing it looks like

mofojed · 2026-05-20T13:10:54Z

        Args:
-            url_state: Dict with URL state fields __queryParams,
-                __path, __absolutePath, __fragment, __href.
+            url_state: Dict with __url field containing the full URL.


We shouldn't need a __url param at all, we should just pass the URL as the first parameter.

mofojed · 2026-05-20T13:12:18Z

+        # contexts (which never carry __url) don't accidentally clear URL state.
+        if "__url" in state:
+            self._root.set_url(state.pop("__url"))


Why is this here? I don't think it's necessary, the URL state is already set explicitly with setUrlState?

I think this was vestigial code that is unnecessary after reworks, where the state was passed through in a different way.

mofojed · 2026-05-20T13:18:45Z

I didn't catch this in the URL params review, but instead of polluting the component state dictionary with a __url param, instead pass the component state as the first param, and then the URL as the second param. We shouldn't need to use a private key like __url.
If we really wanted to leave the door open for possibly more stuff getting passed, we could say the first param is component state, second parameter is app state, which could just be a typed dict with url as a key (no need for __url or polluting the component state). Then we can add more to the second parameter without polluting the component state at all.

Reworked, good catch.

github-actions · 2026-05-20T17:57:57Z

ui docs preview (Available for 14 days)

github-actions · 2026-05-20T19:57:29Z

ui docs preview (Available for 14 days)

jnumainville added 3 commits May 5, 2026 08:59

initial impl

e661ba6

fix

e7c0cd1

warning

9d3b86b

jnumainville requested review from dsmmcken and mofojed May 8, 2026 18:00

jnumainville self-assigned this May 8, 2026

github-actions Bot requested a review from margaretkennedy May 8, 2026 18:00

jnumainville requested a review from Copilot May 11, 2026 13:43

jnumainville changed the title ~~feat:DH-21898: Local routing~~ feat: DH-21898: Local routing May 11, 2026

Copilot started reviewing on behalf of jnumainville May 11, 2026 13:44 View session

Copilot AI reviewed May 11, 2026

View reviewed changes

jnumainville added 5 commits May 11, 2026 11:02

fixt comments and failures

4cc8e3d

docs

3c3ae1a

more docs

d18f35a

even more docs

1e79e03

snapshots

787a36b

margaretkennedy reviewed May 11, 2026

View reviewed changes

Comment thread plugins/ui/docs/components/router.md Outdated

Comment thread plugins/ui/docs/components/router.md Outdated

fixes

06255a2

margaretkennedy previously approved these changes May 11, 2026

View reviewed changes

attempt escape

1e478a3

jnumainville dismissed margaretkennedy’s stale review via 1e478a3 May 11, 2026 20:11

jnumainville added 8 commits May 11, 2026 15:12

missed a spot

4989268

maybe this?

71e6847

testing

eb9ad57

block

660d988

another try

c8dd2e8

love when docs don't save

c65db2f

anotha one

7fc038c

and now for something completely different

6f14ca7

jnumainville added 2 commits May 11, 2026 16:26

maybe need that too

bc6b59c

wip

a45ae84

remove

47cd622

missing tests

b7bc5c1

fix test

f5556a6

a few improvements

277b686

test fixes

e171932

mofojed requested changes May 14, 2026

View reviewed changes

rework

e2e0b22

fix tests

4055480

jnumainville requested a review from mofojed May 19, 2026 13:35

Merge remote-tracking branch 'origin/main' into 21898_local_routing_impl

5614407

margaretkennedy reviewed May 20, 2026

View reviewed changes

mofojed requested changes May 20, 2026

View reviewed changes

some comments

a1d0d29

maybe?

b22bcc4

jnumainville requested a review from mofojed May 20, 2026 20:52

mofojed approved these changes May 20, 2026

View reviewed changes

mofojed merged commit a42efa4 into deephaven:main May 20, 2026
17 checks passed

Conversation

jnumainville commented May 8, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

margaretkennedy left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented May 11, 2026

Uh oh!

github-actions Bot commented May 11, 2026

Uh oh!

github-actions Bot commented May 12, 2026

Uh oh!

github-actions Bot commented May 12, 2026

Uh oh!

github-actions Bot commented May 13, 2026

Uh oh!

github-actions Bot commented May 13, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented May 18, 2026

Uh oh!

github-actions Bot commented May 19, 2026

Uh oh!

github-actions Bot commented May 19, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mofojed left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented May 20, 2026

Uh oh!

github-actions Bot commented May 20, 2026

Uh oh!

Uh oh!

Reviewers

Assignees