[EPIC](Juno): Unified Library for URL Routing and State Management for frontend apps

[edda]

Description

Develop a React-compatible library to handle URL routing and state management for frontend applications. The library must meet the business requirements outlined below and provide a seamless developer experience. This will enable consistent, hierarchical URL structures and state synchronization across multiple apps within a shared context while keeping URLs human-readable as much as possible. The proposed solution must fix the shortcomings of the current solution that is in use in Greenhouse and provide a way to transition Greenhouse from old to new.

---

Requirements

Routing

• Friendly URLs: The library must generate and parse user-friendly URLs for application routes.
• Route-to-Component Matching: Support mapping of routes to specific pages, views, or components within the app.
• Hierarchical Routing: Enable a route hierarchy where a parent application controls the base route, and child applications handle sub routes.

URL State Management

• Human-Readable URLs: Mirror application state in the URL in a human-readable format, as long as the URL length stays within browser limits. URL-safe characters in keys or values should not be encoded to enable manual crafting of the URL from known keys/values without having to transform the strings.
• Compressed State Fallback: If the URL exceeds length limits, utilize a compressed format (e.g., LZString) to represent the state.
• Developer Experience:
  • App developers should manage application state without needing to handle query parameter translation. However imposing strict rules as to the shape of the application state that can be translated into URLs is expected (e.g. no nesting, only flat state)
  • The library should synchronise configurable parts of the app state with the URL automatically.
• Multi-App Compatibility (optional): Ensure that multiple apps using the library can coexist within the same browser context without overwriting each other's URLs.
• Manual Crafting: Both routes and URL state must be manually craftable following a defined ruleset. This is to support the creation of deep links into the apps using this library from within other apps or tools (see also human-readable URLs)

Host app / Child apps

In cases where we have a host app (e.g. Greenhouse, Aurora) with many child apps the URL should contain only the state of the currently active app. Optionally implement a feature for the host app to store child URL state in browser local storage when they unmount and retrieve it when they remount.

Transition process for Greenhouse

• Design a process that allows us to migrate Greenhouse over to the new URL schema
• Primary goal: we want to be able to run with the old and the new URL schema in parallel for a while to give people time to adapt their tooling to the new schema, i.e. old URLs still work but are evaluated and then rewritten to the new schema. Apps only generate URLs following the new schema from the moment of go-live

---

Deliverables

1. A library package that:
   • Exposes an API for defining routes and mapping them to components.
   • Provides utilities to synchronize state with the URL.
   • Supports hierarchical route definitions.
   • Implements compression logic for URLs exceeding browser limits.
2. Comprehensive documentation, including:
   • Installation and integration guides.
   • Examples demonstrating routing, state synchronization, and hierarchical setups.
   • Best practices for using the library with multiple apps in the same context.
3. Unit and integration tests covering all functionality.
4. Process for non-breaking rollout strategy for Greenhouse

---

Acceptance Criteria

• Routes are human-readable and match configured components/pages.
• Application state changes are reflected in the URL without manual query parameter manipulation by developers.
• URLs exceeding browser length limits use compressed state representations without data loss.
• Multiple apps using the library do not interfere with each other's state management or routing.
• All deliverables are completed and reviewed.
• The library is ready for deployment in production environments.