Sharq UI System Router

English · 简体中文

SUS Router (com.sharq-it.sus.router) — navigation for SUS, a vue-router analog for Unity UI Toolkit. Screens, nested routes, guards, keep-alive, modals, and transitions on top of sus-core.

License: MIT

Community & support: support@sus-ui.dev · Discord · Telegram

Tests & releases: 169 automated tests · CHANGELOG · GitHub Releases

Version: 1.0.21 · Namespace: Sharq.Router · Depends on: com.sharq-it.sus.core (^1.0.0)

Requirements

• Unity 6000.3 or newer

• UI Toolkit only — same floor as sus-core
• Requires com.sharq-it.sus.core (sibling package; not bundled here)

What is not included

• Reactivity, the .sharq compiler, themes, overlays, and icons live in sus-core — install that package first.
• Ready-made screen widgets and HUD layouts are not in this package; it is navigation only.

Quick start (via SusApp)

using Sharq.Core;
using Sharq.Router;

SusApp.Create(GetComponent<UIDocument>())
    .UseTheme(SusTheme.Dark)
    .UseRouter(new SusRouter(), routes => routes
        .Route("/", typeof(HomeScreen)).Name("home")
        .Route("/user/:id", typeof(UserScreen)).KeepAlive()
        .Route("/settings", typeof(SettingsLayout)).Children(c => c
            .Route("profile", typeof(ProfileScreen))),
        initialPath: "/")
    .Run();

Core types

Type	Purpose
SusRouter	Core: Register, Push/Replace/Back, history stack (cap MaxHistory), guards
SusRouteBuilder	Declarative route tree (Route/Name/KeepAlive/Alias/Redirect/Meta/Guard/BeforeEnter/Props/PropsFn/Lazy/Transition/Children) → ApplyTo(router)
SusScreen	Base screen: lifecycle BeforeEnter/Entered/BeforeRouteUpdate/BeforeLeave/Left, GetParam/GetQuery, ChildView for nested
SusRouteView	Mount slot (root and nested ChildView)
SusModal / SusModalService	Modal screens via OverlayHost
SusAppRouterExtensions	SusApp.UseRouter(...) — register + mount at the correct finalization point

Key capabilities

• params/query → Props: priority PropsFn → DefaultProps → query → params → explicit props.
• Nested routes: parent stays mounted; child renders into its ChildView.
• KeepAlive: cached screen instances; key via KeepAliveKey(route) (option KeepAliveIgnoreQuery).
• Guards: sync and async BeforeEnter/BeforeLeave/beforeResolve.

Gallery

Package samples (raw UITK after rewrite) — routing, modals, keep-alive, full demo:

BasicRouting — tabs + Push/Replace	Modal — OverlayHost info dialog
FullDemo — sidebar + nested screens	KeepAlive — counter state preserved

Namespace

Router types live in Sharq.Router (after the P1.4 refactor). Import both namespaces: using Sharq.Core; (bootstrap/components) + using Sharq.Router; (screens/navigation).

Documentation

• Package docs: docs/README.md
• SUS core: sus-core/Docs/README.md
• Integration pitfalls: sus-core/Docs/SUS_INTEGRATION_KNOWN_ISSUES.md
• Public demo (cloneable runtime example): sus-demo-public