@basmilius/routing 0.0.0

package/src/internal/modalContext.ts

@@ -0,0 +1,205 @@
+import { computed, type ComputedRef, shallowRef, type ShallowRef, unref, watch } from 'vue';
+import { loadRouteLocation, type RouteLocationNormalized, type Router } from 'vue-router';
+import type { ModalConfig } from '../types';
+import { readModalState, writeModalState } from './modalState';
+import type { OriginalNav } from './patchRouter';
+
+// note: True when all matched-record components are already materialised
+//  (not still `() => import(...)` functions). Decides whether to assign
+//  the background route synchronously or await `loadRouteLocation` first.
+function isFullyLoaded(route: RouteLocationNormalized): boolean {
+    for (const record of route.matched) {
+        if (!record.components) {
+            continue;
+        }
+
+        for (const name in record.components) {
+            const component = record.components[name];
+
+            if (typeof component === 'function' && !('displayName' in component)) {
+                return false;
+            }
+        }
+    }
+
+    return true;
+}
+
+export type ModalContext = {
+    readonly isModal: ComputedRef<boolean>;
+    readonly backgroundRoute: ShallowRef<RouteLocationNormalized | null>;
+    readonly depth: ShallowRef<number>;
+    readonly initiallyOpen: ShallowRef<boolean>;
+    readonly defaultModal: ModalConfig | null;
+    // note: Symbol of the `<RouterView modals>` instance that owns the
+    //  host role. `null` when no host is mounted — modals don't render.
+    readonly host: ShallowRef<symbol | null>;
+
+    promote(): Promise<void>;
+
+    // note: Reserves the host role. Returns `true` when the role was free
+    //  and is now ours; `false` when another instance got there first.
+    claimHost(id: symbol): boolean;
+
+    // note: Releases the host role only if `id` matches the current
+    //  holder, so a late "loser" unmount can't reset the actual host.
+    releaseHost(id: symbol): void;
+};
+
+export default function createModalContext(
+    router: Router,
+    original: OriginalNav,
+    defaultModal: ModalConfig | null
+): ModalContext {
+    const initial = readModalState();
+
+    // note: On hard refresh of a modal URL, the background route's lazy
+    //  chunks aren't loaded yet — `components` are still import functions
+    //  that Vue would render as promise vnodes inside `<Transition>`. We
+    //  keep `backgroundRoute` null until `loadRouteLocation` materialises
+    //  them, then assign once.
+    const backgroundRoute = shallowRef<RouteLocationNormalized | null>(null);
+
+    // note: Number of parent matched records (above the deepest) that
+    //  render inside the modal wrapper. `0` renders only the deepest;
+    //  higher values include ancestors as in-modal layout.
+    const depth = shallowRef(initial?.depth ?? 0);
+
+    // note: True between the first render (history.state already shows
+    //  an open modal) and the moment the background route's async load
+    //  settles. Wrappers can consume this to skip the opening transition.
+    const initiallyOpen = shallowRef(initial !== null);
+
+    const isModal = computed(() => unref(backgroundRoute) !== null);
+
+    let loadToken = 0;
+
+    // note: On refresh, await the background chunks before surfacing the
+    //  background route. Already-cached chunks assign synchronously so
+    //  the first render sees the open-modal state.
+    if (initial !== null) {
+        const token = ++loadToken;
+        const snapshot = router.resolve(initial.backgroundPath) as RouteLocationNormalized;
+
+        if (isFullyLoaded(snapshot)) {
+            backgroundRoute.value = snapshot;
+            initiallyOpen.value = false;
+        } else {
+            loadRouteLocation(snapshot)
+                .then(() => {
+                    if (token !== loadToken) {
+                        return;
+                    }
+
+                    backgroundRoute.value = router.resolve(initial.backgroundPath) as RouteLocationNormalized;
+                    initiallyOpen.value = false;
+                })
+                .catch(() => {
+                    if (token !== loadToken) {
+                        return;
+                    }
+
+                    backgroundRoute.value = null;
+                    initiallyOpen.value = false;
+                });
+        }
+    }
+
+    // note: React to subsequent navigations. `flush: 'pre'` runs before
+    //  render so RouterView picks up the new background the same tick.
+    watch(router.currentRoute, () => {
+        if (typeof history === 'undefined') {
+            backgroundRoute.value = null;
+            depth.value = 0;
+
+            return;
+        }
+
+        const state = readModalState();
+
+        if (state === null) {
+            loadToken++;
+            backgroundRoute.value = null;
+            depth.value = 0;
+            initiallyOpen.value = false;
+
+            return;
+        }
+
+        depth.value = state.depth;
+
+        const token = ++loadToken;
+        const backgroundPath = state.backgroundPath;
+        const snapshot = router.resolve(backgroundPath) as RouteLocationNormalized;
+
+        // note: Fast path — chunks already loaded (typical navigation),
+        //  assign synchronously to avoid a flash of modal-as-fullpage.
+        //  Slow path — hard refresh, await load to avoid promise vnodes.
+        if (isFullyLoaded(snapshot)) {
+            backgroundRoute.value = snapshot;
+
+            return;
+        }
+
+        loadRouteLocation(snapshot)
+            .then(() => {
+                if (token !== loadToken) {
+                    return;
+                }
+
+                backgroundRoute.value = router.resolve(backgroundPath) as RouteLocationNormalized;
+            })
+            .catch(() => {
+                if (token !== loadToken) {
+                    return;
+                }
+
+                backgroundRoute.value = null;
+            });
+    }, {flush: 'pre'});
+
+    async function promote(): Promise<void> {
+        const current = unref(router.currentRoute);
+
+        // note: Turns the modal's URL into the "real" page. `replace`
+        //  avoids a duplicate history entry; `force: true` because
+        //  vue-router otherwise skips a same-URL replace.
+        await original.replace({
+            path: current.fullPath,
+            force: true,
+            state: writeModalState(null, null)
+        });
+    }
+
+    const host = shallowRef<symbol | null>(null);
+
+    function claimHost(id: symbol): boolean {
+        if (host.value !== null) {
+            return false;
+        }
+
+        host.value = id;
+
+        return true;
+    }
+
+    function releaseHost(id: symbol): void {
+        if (host.value !== id) {
+            return;
+        }
+
+        host.value = null;
+    }
+
+    return {
+        isModal,
+        backgroundRoute,
+        depth,
+        initiallyOpen,
+        defaultModal,
+        host,
+        promote,
+        claimHost,
+        releaseHost
+    };
+}

package/src/internal/modalState.ts

@@ -0,0 +1,54 @@
+import type { HistoryState } from 'vue-router';
+
+export type ModalState = {
+    readonly backgroundPath: string;
+    readonly depth: number;
+};
+
+// note: Modal fields on `history.state`:
+//   { modal: true, modalBackgroundPath: '/users', modalDepth: 0 }
+//  - `modal` flags the entry as a modal.
+//  - `modalBackgroundPath` is the fullPath rendered behind the wrapper.
+//  - `modalDepth` is the parent-record count above the deepest matched
+//    record that renders inside the wrapper (0 = deepest only).
+
+export function readModalState(): ModalState | null {
+    if (typeof history === 'undefined' || !history.state) {
+        return null;
+    }
+
+    const state = history.state as Record<string, unknown>;
+
+    if (state.modal !== true) {
+        return null;
+    }
+
+    if (typeof state.modalBackgroundPath !== 'string' || !state.modalBackgroundPath) {
+        return null;
+    }
+
+    return {
+        backgroundPath: state.modalBackgroundPath,
+        depth: typeof state.modalDepth === 'number' ? Math.max(0, state.modalDepth) : 0
+    };
+}
+
+export function writeModalState(base: HistoryState | null, backgroundPath: string | null, depth: number = 0): HistoryState {
+    const next: HistoryState = {...(base ?? {})};
+
+    if (backgroundPath === null) {
+        // note: `null` (not `delete`) so vue-router's state-merging
+        //  unambiguously wipes the previous value.
+        next.modal = null;
+        next.modalBackgroundPath = null;
+        next.modalDepth = null;
+
+        return next;
+    }
+
+    next.modal = true;
+    next.modalBackgroundPath = backgroundPath;
+    next.modalDepth = Math.max(0, depth);
+
+    return next;
+}

package/src/internal/patchRouter.ts

@@ -0,0 +1,86 @@
+import { unref } from 'vue';
+import type { HistoryState, NavigationFailure, RouteLocationOptions, RouteLocationRaw, Router } from 'vue-router';
+import { readModalState, writeModalState } from './modalState';
+
+type Navigate = (to: RouteLocationRaw) => Promise<NavigationFailure | void | undefined>;
+
+export type OriginalNav = {
+    readonly push: Navigate;
+    readonly replace: Navigate;
+};
+
+function withState(to: RouteLocationRaw, state: HistoryState): RouteLocationRaw {
+    if (typeof to === 'string') {
+        return {path: to, state};
+    }
+
+    return {...to, state};
+}
+
+function injectState(to: RouteLocationRaw, backgroundPath: string | null, depth: number = 0): RouteLocationRaw {
+    const base = typeof to === 'string' ? null : (to.state ?? null);
+
+    return withState(to, writeModalState(base, backgroundPath, depth));
+}
+
+function readModalFlag(flag: boolean | number | undefined): {open: boolean; depth: number; explicitClose: boolean} {
+    if (flag === true) {
+        return {open: true, depth: 0, explicitClose: false};
+    }
+
+    if (flag === false) {
+        return {open: false, depth: 0, explicitClose: true};
+    }
+
+    if (typeof flag === 'number') {
+        return {open: true, depth: Math.max(0, flag), explicitClose: false};
+    }
+
+    return {open: false, depth: 0, explicitClose: false};
+}
+
+export default function patchRouter(router: Router): OriginalNav {
+    const origPush: Navigate = router.push.bind(router);
+    const origReplace: Navigate = router.replace.bind(router);
+
+    function transform(to: RouteLocationRaw): RouteLocationRaw {
+        const wantsModal = typeof to === 'string' ? undefined : (to as RouteLocationOptions).modal;
+        const flag = readModalFlag(wantsModal);
+        const current = readModalState();
+
+        // note: Explicit `modal: true` / `<number>` opens on top of the
+        //  current route. Already-open modals reuse the existing background.
+        if (flag.open) {
+            const backgroundPath = current?.backgroundPath ?? unref(router.currentRoute).fullPath;
+
+            return injectState(to, backgroundPath, flag.depth);
+        }
+
+        // note: Explicit `modal: false` exits the modal entirely.
+        if (flag.explicitClose) {
+            return injectState(to, null);
+        }
+
+        // note: Implicit navigation from within a modal. Keep the modal open
+        //  when the target shares the root-matched record (sibling within
+        //  the same modal tree), otherwise exit. Depth carries across.
+        if (current !== null) {
+            const resolved = router.resolve(to);
+            const currentRoot = unref(router.currentRoute).matched[0]?.path;
+            const nextRoot = resolved.matched[0]?.path;
+            const sameRoot = !!currentRoot && currentRoot === nextRoot;
+
+            return sameRoot ? injectState(to, current.backgroundPath, current.depth) : injectState(to, null);
+        }
+
+        return to;
+    }
+
+    router.push = async (to) => await origPush(transform(to));
+    router.replace = async (to) => await origReplace(transform(to));
+
+    return {
+        push: origPush,
+        replace: origReplace
+    };
+}

package/src/internal/resolveModal.ts

@@ -0,0 +1,20 @@
+import type { RouteLocationNormalized } from 'vue-router';
+import type { ModalConfig } from '../types';
+
+// note: Walks matched records deepest-first so children override their
+//  parent's `meta.modal`. Falls back to `defaultModal` from
+//  `createRouter()` when no record declares one.
+export default function resolveModal(
+    route: RouteLocationNormalized,
+    fallback: ModalConfig | null
+): ModalConfig | null {
+    for (let i = route.matched.length - 1; i >= 0; --i) {
+        const modal = route.matched[i]?.meta?.modal;
+
+        if (modal) {
+            return modal;
+        }
+    }
+
+    return fallback;
+}

package/src/symbol.ts

@@ -0,0 +1,12 @@
+import type { ComputedRef, InjectionKey, Ref, ShallowRef } from 'vue';
+import type { RouteLocationNormalized } from 'vue-router';
+import type { ModalContext } from './internal/modalContext';
+
+export const modalContextKey: InjectionKey<ModalContext> = Symbol('basmilius:routing:modal-context');
+export const routeOverrideKey: InjectionKey<ComputedRef<RouteLocationNormalized>> = Symbol('basmilius:routing:route-override');
+export const isInModalKey: InjectionKey<Ref<boolean>> = Symbol('basmilius:routing:in-modal');
+
+// note: Gates the modal's inner `<VueRouterView>` for one tick on a
+//  user-triggered open so the wrapper's `<Transition>` plays the enter
+//  animation. See `RouterView.ts` for the full rationale.
+export const innerReadyKey: InjectionKey<ShallowRef<boolean>> = Symbol('basmilius:routing:inner-ready');

package/src/types.ts

@@ -0,0 +1,34 @@
+import type { Component } from 'vue';
+import type { RouteLocationNormalized, RouterOptions as VueRouterOptions } from 'vue-router';
+
+export type ModalConfig = {
+    readonly component: Component;
+    readonly props?: Record<string, unknown>;
+};
+
+// note: Props our `RouterView` passes to every modal wrapper component
+//  at runtime. Declare on your wrapper via `defineProps<ModalWrapperProps>()`.
+//  - `modalActive`: open/close flag for script-level use (disable inputs
+//    while closing, etc.).
+//  - `modalReady`: v-if gate for the inner `<ModalRouterView>`. False at
+//    mount and during the close phase so the wrapper's `<Transition>` has
+//    an empty slot to animate from / to.
+export type ModalWrapperProps = {
+    readonly modalRoute: RouteLocationNormalized;
+    readonly modalActive: boolean;
+    readonly modalReady: boolean;
+};
+
+// note: Shadows vue-router's `RouterOptions` via `index.ts`. Adds
+//  `defaultModal` as the fallback wrapper for modal routes without
+//  their own `meta.modal`.
+export type RouterOptions = VueRouterOptions & {
+    readonly defaultModal?: ModalConfig;
+};
+
+// note: Props on our `<RouterView>`. `modals` opts the instance in as
+//  the host for the modal layer. Exactly one `<RouterView>` should set
+//  it; multiple → first mount wins, others warn and render vanilla.
+export type RouterViewProps = {
+    readonly modals?: boolean;
+};