diff --git a/src/lib/calculateSkHref.ts b/src/lib/calculateSkHref.ts new file mode 100644 index 0000000..5469205 --- /dev/null +++ b/src/lib/calculateSkHref.ts @@ -0,0 +1,47 @@ +import { calculateHref } from "@wjfe/n-savant/core"; +import type { CalculateSkHrefOptions } from "./types.js"; + +/** + * Helper function that combines multiple HREF's into a single HREF using `@wjfe/n-savant`'s `calculateHref` function + * for the path routing universe. + * + * #### Why? + * + * To assist in the calculation of HREF's for hyperlinks used by Sveltekit's `` tags so they play nicely with + * `@wjfe/n-savant`'s routing universes. + * + * @example + * ```ts + * import { calculateSkHref } from '@wjfe/n-savant-sk'; + * + * // The demo project in the /demo folder uses the query string to switch between + * // single and multi-hash routing. If (Sveltekit's) path routing doesn't + * // preserve the query string, errors about mismatched routing universes will + * // occur. + * const href = $derived(calculateSkHref({ preserveQuery: true }, '/demo')); + * ``` + * + * @example + * ```ts + * import { calculateSkHref } from '@wjfe/n-savant-sk'; + * + * // This one preserves the hash fragment to ensure any hash routing universes + * // remain intact. + * const href = $derived(calculateSkHref({ preserveHash: true }, '/abc')); + * ``` + * + * #### Tips + * + * 1. Try to always use reactively in `$derived`, `$effect` or templates, since it reads reactive data. + * 2. If a new hash fragment is desired, simply add it to one of the given HREF's. + * 3. If you want to calculate an HREF for a hash routing universe, use `@wjfe/n-savant`'s `calculateHref` function. + * 4. If you don't need to join HREF's or preserve query or hash, you most likely don't need this or the + * base `calculateHref` function, and can simply use the HREF you already have. + * + * @param options Desired options that control how the resultant HREF is calculated. + * @param href The HREF's used to calculate the final HREF for the desired routing universe. + * @returns The calculated HREF. + */ +export function calculateSkHref(options: CalculateSkHrefOptions, ...hrefs: string[]): string { + return calculateHref({ ...options, hash: false }, ...hrefs); +} diff --git a/src/lib/index.ts b/src/lib/index.ts index 2185cfd..7059a1d 100644 --- a/src/lib/index.ts +++ b/src/lib/index.ts @@ -1,3 +1,4 @@ export type * from "./types.js"; export { init } from "./init.js"; export { default as SkFallback } from "./SkFallback.svelte"; +export { calculateSkHref } from "./calculateSkHref.js"; diff --git a/src/lib/types.ts b/src/lib/types.ts index 08486ab..0fe388d 100644 --- a/src/lib/types.ts +++ b/src/lib/types.ts @@ -1,6 +1,7 @@ import "@wjfe/n-savant"; import { goto } from "$app/navigation"; import type { Hash, PreserveQuery, InitOptions, State, GoToOptions } from "@wjfe/n-savant"; +import type { calculateHref } from "@wjfe/n-savant/core"; /** * Options available to the `Location.skGoto` method. @@ -51,3 +52,7 @@ declare module "@wjfe/n-savant" { * Options available to the `init` function. */ export type SkInitOptions = Omit; + +export type SkHash = Exclude; + +export type CalculateSkHrefOptions = Omit[0], 'hash'>;