Improve support for a variety of hrefs in the Link component

[webJose]

Currently, the href property of the <Link> component is quite "delicate". For example, creating a link with query string parameters is not explicitly acocunted for, and will cause issues if preserving query string via the preserveQuery property.

Furthermore, it assumes no hash value is in it. For path routing, it should be possible to create a <Link> component whose href property carries a hash value.

Proposal

Enhance href calculation to account for all possible cases:

• Just a path
• A path with a hash value (only allowed for path routing <Link> components)
• A path with a hash value and query string (only allowed for path routing <Link> components)
• A hash value with query string (only allowed for path routing <Link> components)
• A path with query string
• Just a query string
• Just a hash value (only allowed for path routing <Link> components)

For the cases where a query string is found in href, it should be appended to whatever query string currently exists if preserveQuery is true.

[webJose]

This is proving to be a bit more complex. While attempting the proposal, I have come to realize the following about location.navigate():

• The overloads are a bit messy. The overloads have different rules for the URL's that are given.
• Navigation also requires better URL support. Basically, the same enhancements.

Because of this, I think the proposal should be to:

• Expose URL generation as a separate function: calculateHref()
• Use the above in <Link> and location.navigate().
• Actually remove the navigate() overloads and keep just one that receives the hash of type Hash.
• Create location.navigateRaw() that takes a built URL.

Then <Link> would use calculateHref() to "preview" the actual link that will be navigated to, and then it would use location.navigateRaw() to avoid the performance hit of re-calculating the URL.

This then just leaves the question as to how to calculate the new state in the navigateRaw function. Most likely it will have an options parameter with the hash: Hash property.

[webJose]

Revision

Ok, so navigateRaw, as explained above, is just moving the hash parameter into the function options. Plus, I don't like the name.

So back to overloads. Proposal:

    navigate(url: string, options?: NavigateOptions): void;
    navigate(url: string, hashId: string, options?: NavigateOptions): void;

These are the current overloads, and I think they are correct. The first one just need a good description: Navigates without processing the given URL or state objects. So, basically, the user is fully responsible for everything, which is providing a good URL that properly preserves what needs to be preserved, and a well-formed state object of type State. The typing should be good enough for users to realize this.

The other overload does everything: Processes the URL and state value according to the value of the hash parameter. It also needs the logic behind the <Link>'s preserveQuery property, so this is a new option to be added to this overload.

To assist both users of this library and the <Link> component, the logic to create well-formed state objects has to be exported. So the proposal includes to export calculateHref() and calculateState().

[webJose]

After trying to accommodate the the 2 overloads, it is not possible nicely.

Once more, back to navigateRaw:

navigateRaw(href: string, options?: {
  replace?: boolean;
  state?: State // Which is { hash: {} }
  preserveQuery: PreserveQuery // Which is string | string[] | boolean
}): void;

navigate(href: string, options?: {
  replace?: boolean;
  hash?: Hash // Which is boolean | string
  state: any;
  preserveQuery?: PreserveQuery;
  preserveHash?: boolean; // Only for hash: false (path routing URL's).
}): void;

navigateRaw

This will take a prepared HREF and will navigate to it, unchanged. The only change is for shallow routing: When href === '', then the URL is unmodified and navigation takes place to set the given state value in place. It doesn't offer the ability to preserve the hash. If this is desired, the href value must come with it. The only convenience offered is to preserve all or one or more query string values.

navigate

This one does all calculations of HREF and state. The provided href must be a path (relative or absolute) regardless of the value of options.hash. The algorithm will inspect the value of options.hash and will use it to estimate the final shape of the href and the state object.

Just as with navigateRaw, an empty string signals shallow routing.

---

The above would be powered by a function called calculateHref (at least for now):

export type CalculateHrefOptions = {
    /**
     * Whether to preserve the current query parameters (or the ones specified) in the new URL.
     * 
     * New URL's can specify a query string, and if query string preservation is requested, the query parameters from 
     * the current URL will be appended with the ones from the new URL.
     */
    preserveQuery?: PreserveQuery;
} & ({
    /**
     * Determines the routing universe the new URL will be for.
     * 
     * Read the [online documentation](https://wjfe-n-savant.hashnode.space/wjfe-n-savant/routing-modes) to understand 
     * the concept of routing modes (or universes).
     */
    hash: false;
    /**
     * Whether to preserve the current hash in the new URL.  This is only applicable when the `hash` property is set to 
     * `false` (path routing universe).
     */
    preserveHash?: boolean;
} | {
    /**
     * Determines the routing universe the new URL will be for.
     * 
     * Read the [online documentation](https://wjfe-n-savant.hashnode.space/wjfe-n-savant/routing-modes) to understand 
     * the concept of routing modes (or universes).
     */
    hash: Exclude<Hash, false>;
});


function calculateHref(...paths: (string | undefined)[]): string;
function calculateHref(options: CalculateHrefOptions, ...paths: (string | undefined)[]): string;

This function can join multiple paths or href's together, including ones that carry query strings or hashes.