@basmilius/routing 0.0.0

package/src/component/RouterView.ts

@@ -0,0 +1,207 @@
+import { type Component, defineComponent, Fragment, h, inject, nextTick, onBeforeUnmount, provide, type Ref, shallowRef, unref, type VNodeChild, watch } from 'vue';
+import { RouterView as VueRouterView, useRoute, useRouter, viewDepthKey } from 'vue-router';
+import { BackgroundProvider, ModalProvider } from '../internal/RoutedView';
+import resolveModal from '../internal/resolveModal';
+import { innerReadyKey, modalContextKey, routeOverrideKey } from '../symbol';
+import type { ModalConfig } from '../types';
+
+const RouterView: Component = defineComponent({
+    name: 'RouterView',
+    inheritAttrs: false,
+    props: {
+        // note: Opts this instance in as the host that renders the modal
+        //  layer on top of the background route. Exactly one `<RouterView>`
+        //  in the tree should set this; if multiple do, the first to mount
+        //  wins (others render vanilla and emit a console warning).
+        modals: {
+            type: Boolean,
+            default: false
+        }
+    },
+    setup(props, {attrs, slots}) {
+        const ctx = inject(modalContextKey, null);
+        const override = inject(routeOverrideKey, null);
+        const route = useRoute();
+        const router = useRouter();
+
+        // note: Vue-router injects `viewDepthKey` from the parent
+        //  `VueRouterView` (or 0 at the top). It can be a number or a
+        //  `Ref<number>`; `unref` collapses both. Passed to
+        //  `BackgroundProvider` so the background tree resumes at the
+        //  correct matched index when this RouterView is nested.
+        const injectedViewDepth = inject(viewDepthKey, 0);
+
+        // note: Identity used to claim/release the modal host role on the
+        //  shared `modalContext`. The matching unmount release targets
+        //  exactly our claim — never a successor's.
+        const hostId = Symbol('basmilius:routing:router-view-host');
+
+        let isModalHost = false;
+
+        if (props.modals && override === null && ctx) {
+            isModalHost = ctx.claimHost(hostId);
+
+            if (!isModalHost) {
+                // eslint-disable-next-line no-console
+                console.warn(
+                    '[routing] Multiple <RouterView modals> instances detected. ' +
+                    'The first mounted instance owns the modal host role; this ' +
+                    'instance will render as a vanilla RouterView.'
+                );
+            } else {
+                onBeforeUnmount(() => ctx.releaseHost(hostId));
+            }
+        }
+
+        // note: Wrapper component (e.g. FluxOverlay) stays mounted across
+        //  modal close for its leave animation, and is reused when
+        //  consecutive modals share the same wrapper.
+        const lastModal = shallowRef<ModalConfig | null>(null);
+
+        // note: Held as a ref because Vue's runtime `h()` can miss
+        //  primitive prop updates on `ModalProvider` when route changes
+        //  patch in the same tick. Ref identity stays stable.
+        const modalDepthRef: Ref<number> = shallowRef(0);
+
+        // note: Gates whether the modal's inner `<RouterView>` is attached.
+        //  On a user-triggered open we hold it back one tick so the
+        //  wrapper's `<Transition>` observes "no child -> child" and plays
+        //  its enter animation. On hard refresh of a modal URL we skip the
+        //  gate so the page arrives already-open without animating.
+        const innerReady = shallowRef(false);
+
+        // note: Snapshot at setup — `modalContext` flips `initiallyOpen`
+        //  back to `false` once the background route resolves, which is
+        //  too early to read from the watcher below.
+        const wasInitiallyOpen = ctx?.initiallyOpen.value ?? false;
+
+        let hasSeenActiveModal = false;
+
+        // note: Exposed so `ModalRouterView` inside consumer wrapper
+        //  templates honours the same one-tick delay as the fallback slot.
+        provide(innerReadyKey, innerReady);
+
+        if (ctx && isModalHost) {
+            watch(() => ctx.backgroundRoute.value !== null, async (isOpen) => {
+                if (!isOpen) {
+                    innerReady.value = false;
+
+                    return;
+                }
+
+                const isFirstActivation = !hasSeenActiveModal;
+                hasSeenActiveModal = true;
+
+                // note: Pageload of a modal URL — wrapper and inner mount
+                //  together without a transition.
+                if (isFirstActivation && wasInitiallyOpen) {
+                    innerReady.value = true;
+
+                    return;
+                }
+
+                // note: User-triggered open — wrapper renders first with
+                //  an empty slot, inner attaches next tick to animate in.
+                innerReady.value = false;
+                await nextTick();
+                innerReady.value = true;
+            }, {immediate: true, flush: 'pre'});
+        }
+
+        return (): VNodeChild => {
+            // note: Already inside a BackgroundProvider / ModalProvider
+            //  subtree — render vanilla so we don't recurse into another
+            //  background/modal split.
+            if (override !== null) {
+                return h(VueRouterView, attrs, slots);
+            }
+
+            if (!ctx) {
+                return h(VueRouterView, attrs, slots);
+            }
+
+            // note: Only the instance that claimed the host role renders
+            //  modals. All others fall through to vanilla.
+            if (!isModalHost) {
+                return h(VueRouterView, attrs, slots);
+            }
+
+            const backgroundRoute = ctx.backgroundRoute.value;
+            const modalActive = ctx.isModal.value && backgroundRoute !== null;
+
+            // note: Resolve inline (not via watcher) — at setup the route
+            //  is `START_LOCATION` with empty `matched`, so a watcher with
+            //  `immediate: true` would miss the per-route `meta.modal`.
+            if (modalActive) {
+                const resolved = resolveModal(route, ctx.defaultModal);
+
+                if (resolved !== null && resolved !== lastModal.value) {
+                    lastModal.value = resolved;
+                }
+            }
+
+            const wrapperConfig = lastModal.value;
+
+            // note: Never been a modal here -> plain RouterView.
+            if (!modalActive && !wrapperConfig) {
+                return h(VueRouterView, attrs, slots);
+            }
+
+            // note: Background renders the stored route while open; the
+            //  current route while closed (wrapper lingering for leave
+            //  animation). Keeps layout-level `useRoute()` stable.
+            const bgRoute = modalActive ? backgroundRoute : route;
+
+            // note: `ctx.depth` is the user-supplied parent count. Translate
+            //  to an absolute `matched[]` index:
+            //    depth 0 -> matched[length - 1] (deepest only)
+            //    depth N -> matched[length - 1 - N]
+            const parentCount = ctx.depth.value;
+            const viewDepth = Math.max(0, route.matched.length - 1 - parentCount);
+
+            modalDepthRef.value = viewDepth;
+
+            // note: ModalProvider wraps the wrapper component so the
+            //  wrapper's internal Teleport still inherits the provider
+            //  context. Inner is `undefined` while closed or gated, so
+            //  the wrapper's `<Transition>` observes an empty slot.
+            const modalInner = modalActive && innerReady.value
+                ? h(VueRouterView)
+                : undefined;
+
+            const wrappedModalInner = wrapperConfig
+                ? h(wrapperConfig.component, {
+                    ...(wrapperConfig.props ?? {}),
+                    // note: Runtime props after the spread so consumers
+                    //  can't shadow them via `meta.modal.props`. Use
+                    //  `modalReady` (not `modalActive`) to v-if the
+                    //  inner `<ModalRouterView>` — `modalActive` is true
+                    //  at mount and would skip the enter animation.
+                    modalRoute: route,
+                    modalActive,
+                    modalReady: modalActive && innerReady.value,
+                    onClose: (): void => {
+                        router.back();
+                    }
+                }, {
+                    default: (): VNodeChild => modalInner
+                })
+                : modalInner;
+
+            const modalLayer = h(ModalProvider, {route, depthRef: modalDepthRef}, {
+                default: (): VNodeChild => wrappedModalInner
+            });
+
+            const hostViewDepth = unref(injectedViewDepth);
+
+            return h(Fragment, [
+                h(BackgroundProvider, {route: bgRoute, viewDepth: hostViewDepth}, {
+                    default: (): VNodeChild => h(VueRouterView, attrs, slots)
+                }),
+                modalLayer
+            ]);
+        };
+    }
+});
+
+export default RouterView;

package/src/composable/useIsView.ts

@@ -0,0 +1,12 @@
+import { computed, type ComputedRef, unref } from 'vue';
+import useRouteNames from './useRouteNames';
+
+export default function (name: string, loose: boolean = false): ComputedRef<boolean> {
+    const names = useRouteNames();
+
+    if (loose) {
+        return computed(() => unref(names).some(n => n.startsWith(name)));
+    }
+
+    return computed(() => unref(names).some(n => n === name));
+}

package/src/composable/useModalRoute.ts

@@ -0,0 +1,28 @@
+import { computed, type ComputedRef, inject, unref } from 'vue';
+import { type RouteLocationNormalized, useRoute as useVueRoute } from 'vue-router';
+import { isInModalKey, modalContextKey, routeOverrideKey } from '../symbol';
+
+// note: Surfaces the route driving the currently active modal, or `null`
+//  when no modal is active. Inside a ModalProvider subtree the override
+//  IS the modal route; outside, the router's live currentRoute is the
+//  modal route (background is stashed on the context).
+//  `BackgroundProvider` also sets `routeOverrideKey`, so `isInModalKey`
+//  is the discriminator between background and modal subtrees.
+export default function (): ComputedRef<RouteLocationNormalized | null> {
+    const override = inject(routeOverrideKey, null);
+    const isInModal = inject(isInModalKey, null);
+    const ctx = inject(modalContextKey, null);
+    const rawRoute = useVueRoute();
+
+    return computed(() => {
+        if (isInModal !== null && unref(isInModal) && override !== null) {
+            return unref(override);
+        }
+
+        if (ctx !== null && unref(ctx.isModal)) {
+            return rawRoute;
+        }
+
+        return null;
+    });
+}

package/src/composable/useNamedRoute.ts

@@ -0,0 +1,23 @@
+import { computed, type ComputedRef, provide, type Ref, unref } from 'vue';
+import { viewDepthKey } from 'vue-router';
+import useRoute, { type UseRoute } from './useRoute';
+
+export default function (nameRef: Ref<string> | string): UseNamedRoute {
+    const route = useRoute();
+
+    const depth = computed(() => unref(route).matched.findIndex(m => !!m.components && unref(nameRef) in m.components));
+    const matched = computed(() => unref(route).matched[unref(depth)]);
+    const viewKey = computed(() => unref(matched)?.path);
+
+    provide(viewDepthKey, depth);
+
+    return {
+        route,
+        viewKey
+    };
+}
+
+type UseNamedRoute = {
+    readonly route: UseRoute;
+    readonly viewKey: ComputedRef<string | undefined>;
+};

package/src/composable/useNavigate.ts

@@ -0,0 +1,35 @@
+import { type NavigationFailure, type RouteLocationRaw, useRouter } from 'vue-router';
+
+type Result = NavigationFailure | void | undefined;
+type To = Omit<RouteLocationRaw, 'replace'>;
+type Navigate = (to: To, replace?: boolean) => Promise<Result>;
+type Wrap = (fn: Navigate) => Navigate;
+
+export default function (...wrap: Wrap[]): UseNavigate {
+    const router = useRouter();
+
+    let navigate: Navigate = async (to: To, replace: boolean = false) => {
+        if (replace) {
+            return await router.replace(to);
+        }
+
+        return await router.push(to);
+    };
+
+    for (const wrapper of wrap) {
+        navigate = wrapper(navigate);
+    }
+
+    return {
+        navigate,
+
+        push: (to: To) => navigate(to),
+        replace: (to: To) => navigate(to, true)
+    };
+}
+
+type UseNavigate = {
+    navigate(to: To, replace?: boolean): Promise<Result>;
+    push(to: To): Promise<Result>;
+    replace(to: To): Promise<Result>;
+};

package/src/composable/useRoute.ts

@@ -0,0 +1,83 @@
+import { computed, inject, shallowRef, unref } from 'vue';
+import { type RouteLocationNormalizedLoaded, useRoute as useVueRoute } from 'vue-router';
+import { isInModalKey, modalContextKey, routeOverrideKey } from '../symbol';
+
+export type UseRoute = RouteLocationNormalizedLoaded & {
+    readonly isModal: boolean;
+
+    promote(): Promise<void>;
+};
+
+const FALSE_REF = shallowRef(false);
+const NOOP = async (): Promise<void> => undefined;
+
+export default function (): UseRoute {
+    const override = inject(routeOverrideKey, null);
+    const ctx = inject(modalContextKey, null);
+    const isModalRef = inject(isInModalKey, FALSE_REF);
+    const raw = useVueRoute();
+
+    const routeRef = computed<RouteLocationNormalizedLoaded>(() => {
+        // note: Inside a Background/ModalProvider subtree — use the
+        //  explicit override so background-tree components see the
+        //  background route and modal-wrapper components see the modal
+        //  route, independent of the router's live currentRoute.
+        if (override !== null) {
+            return unref(override) as RouteLocationNormalizedLoaded;
+        }
+
+        // note: Outside any provider (top-level layouts) — surface the
+        //  background route while a modal is open so layout-level
+        //  `:key`s stay stable across opens/closes.
+        if (ctx !== null && unref(ctx.isModal)) {
+            const bg = unref(ctx.backgroundRoute);
+
+            if (bg !== null) {
+                return bg as RouteLocationNormalizedLoaded;
+            }
+        }
+
+        return raw;
+    });
+
+    const promote = ctx !== null ? ctx.promote : NOOP;
+
+    // note: Proxy (not a Ref) so the object can be used directly in
+    //  templates without auto-unwrapping stripping our extras. All
+    //  route properties flow through `routeRef.value` to keep reactivity
+    //  tracking intact in templates, computeds, and watchers.
+    return new Proxy({} as UseRoute, {
+        get(_target, key) {
+            if (key === 'isModal') {
+                return isModalRef.value;
+            }
+
+            if (key === 'promote') {
+                return promote;
+            }
+
+            return (routeRef.value as unknown as Record<PropertyKey, unknown>)[key];
+        },
+        has(_target, key) {
+            if (key === 'isModal' || key === 'promote') {
+                return true;
+            }
+
+            return key in routeRef.value;
+        },
+        ownKeys(_target) {
+            return [...Reflect.ownKeys(routeRef.value), 'isModal', 'promote'];
+        },
+        getOwnPropertyDescriptor(_target, key) {
+            if (key === 'isModal') {
+                return {configurable: true, enumerable: true, value: isModalRef.value};
+            }
+
+            if (key === 'promote') {
+                return {configurable: true, enumerable: true, value: promote};
+            }
+
+            return Object.getOwnPropertyDescriptor(routeRef.value, key);
+        }
+    });
+}

package/src/composable/useRouteMeta.ts

@@ -0,0 +1,32 @@
+import { merge } from 'lodash-es';
+import { computed, type ComputedRef, unref } from 'vue';
+import type { RouteMeta } from 'vue-router';
+import useRoute from './useRoute';
+
+export default function (): ComputedRef<RouteMeta> {
+    const route = useRoute();
+
+    return computed(() => {
+        const matched = unref(route).matched;
+        let meta: RouteMeta = {};
+
+        for (let i = matched.length - 1; i >= 0; --i) {
+            const record = matched[i];
+
+            if (!record || typeof record.meta !== 'object') {
+                continue;
+            }
+
+            let matchMeta = {...record.meta};
+
+            if ('navigation' in meta) {
+                const {navigation: _navigation, ...matchMetaWithoutNavigation} = matchMeta;
+                matchMeta = matchMetaWithoutNavigation;
+            }
+
+            meta = merge(meta, matchMeta);
+        }
+
+        return meta;
+    });
+}

package/src/composable/useRouteNames.ts

@@ -0,0 +1,14 @@
+import { computed, type ComputedRef, unref } from 'vue';
+import useRoute from './useRoute';
+
+export default function (): ComputedRef<string[]> {
+    const route = useRoute();
+
+    return computed(() => {
+        const names: string[] = [];
+
+        unref(route).matched.forEach(m => m.name && names.push(m.name as string));
+
+        return names;
+    });
+}

package/src/composable/useRouteParam.ts

@@ -0,0 +1,16 @@
+import { type Ref, ref, unref, watch } from 'vue';
+import useRoute from './useRoute';
+
+export default function (name: string, defaultValue: string | null = null): Ref<string | null> {
+    const route = useRoute();
+    const param = ref<string | null>(null);
+
+    // note: `defaultValue` applies on every read of a missing/empty
+    //  param, not just at mount. The `immediate: true` flush handles
+    //  the initial value so we don't duplicate the fallback logic.
+    watch(() => unref(route).params[name] as string | undefined, (value) => {
+        param.value = value || defaultValue;
+    }, {immediate: true});
+
+    return param;
+}

package/src/composable/useRouteView.ts

@@ -0,0 +1,23 @@
+import { computed, type ComputedRef, type Ref, unref } from 'vue';
+import type { RouteComponent } from 'vue-router';
+import useRoute from './useRoute';
+
+export default function (nameRef: Ref<string> | string): ComputedRef<RouteComponent | null> {
+    const route = useRoute();
+
+    return computed(() => {
+        const name = unref(nameRef);
+
+        for (const match of unref(route).matched) {
+            if (!match.components) {
+                continue;
+            }
+
+            if (name in match.components) {
+                return match.components[name];
+            }
+        }
+
+        return null;
+    });
+}

package/src/createRouter.ts

@@ -0,0 +1,23 @@
+import type { App } from 'vue';
+import { createRouter as createVueRouter, type Router } from 'vue-router';
+import createModalContext from './internal/modalContext';
+import patchRouter from './internal/patchRouter';
+import { modalContextKey } from './symbol';
+import type { RouterOptions } from './types';
+
+export default function createRouter(options: RouterOptions): Router {
+    const {defaultModal, ...routerOptions} = options;
+
+    const router = createVueRouter(routerOptions);
+    const original = patchRouter(router);
+    const ctx = createModalContext(router, original, defaultModal ?? null);
+
+    const originalInstall = router.install.bind(router);
+
+    router.install = (app: App): void => {
+        originalInstall(app);
+        app.provide(modalContextKey, ctx);
+    };
+
+    return router;
+}

package/src/index.ts

@@ -0,0 +1,26 @@
+// note: Side-effect import — registers the `declare module 'vue-router'`
+//  augmentations (`RouteLocationOptions.modal`, `RouteMeta.modal`).
+import './augmentations';
+
+export * from 'vue-router';
+
+// note: Named exports below shadow the star re-export — ES modules
+//  resolve direct exports over star re-exports. Our enhanced versions
+//  win for `createRouter`, `RouterView`, etc.; every other vue-router
+//  symbol flows through unchanged.
+export { default as createRouter } from './createRouter';
+export type { ModalConfig, ModalWrapperProps, RouterOptions, RouterViewProps } from './types';
+
+export { default as ModalRouterView } from './component/ModalRouterView';
+export { default as RouterLink } from './component/RouterLink';
+export { default as RouterView } from './component/RouterView';
+
+export { default as useIsView } from './composable/useIsView';
+export { default as useModalRoute } from './composable/useModalRoute';
+export { default as useNamedRoute } from './composable/useNamedRoute';
+export { default as useNavigate } from './composable/useNavigate';
+export { default as useRoute, type UseRoute } from './composable/useRoute';
+export { default as useRouteMeta } from './composable/useRouteMeta';
+export { default as useRouteNames } from './composable/useRouteNames';
+export { default as useRouteParam } from './composable/useRouteParam';
+export { default as useRouteView } from './composable/useRouteView';

package/src/internal/RoutedView.ts

@@ -0,0 +1,66 @@
+import { type Component, computed, defineComponent, type PropType, provide, type Ref, shallowRef, type VNodeChild } from 'vue';
+import { type RouteLocationNormalized, routerViewLocationKey, viewDepthKey } from 'vue-router';
+import { isInModalKey, routeOverrideKey } from '../symbol';
+
+const TRUE_REF = shallowRef(true);
+const FALSE_REF = shallowRef(false);
+
+// note: Both providers override `routerViewLocationKey` so descendant
+//  `<RouterView>`s render the supplied `route` instead of the router's
+//  live currentRoute. `viewDepthKey` is set to the index at which the
+//  inner `VueRouterView` should resume in `matched[]` — for
+//  `BackgroundProvider`, the host's own depth (so a nested host doesn't
+//  re-render its ancestors); for `ModalProvider`, the absolute matched
+//  index computed by RouterView from `ctx.depth`.
+
+export const BackgroundProvider: Component = defineComponent({
+    name: 'BackgroundProvider',
+    props: {
+        route: {
+            type: Object as PropType<RouteLocationNormalized>,
+            required: true
+        },
+        viewDepth: {
+            type: Number,
+            default: 0
+        }
+    },
+    setup(props, {slots}) {
+        const routeRef = computed(() => props.route);
+
+        provide(routerViewLocationKey, routeRef);
+        provide(viewDepthKey, props.viewDepth);
+        provide(routeOverrideKey, routeRef);
+        provide(isInModalKey, FALSE_REF);
+
+        return (): VNodeChild => slots.default?.();
+    }
+});
+
+export const ModalProvider: Component = defineComponent({
+    name: 'ModalProvider',
+    props: {
+        route: {
+            type: Object as PropType<RouteLocationNormalized>,
+            required: true
+        },
+        // note: Ref instead of a plain number — Vue's runtime `h()` prop
+        //  diffing can miss primitive updates when patching in a tight
+        //  cycle alongside reactive route changes. Ref identity stays
+        //  stable; `.value` propagates through normal reactivity.
+        depthRef: {
+            type: Object as PropType<Ref<number>>,
+            required: true
+        }
+    },
+    setup(props, {slots}) {
+        const routeRef = computed(() => props.route);
+
+        provide(routerViewLocationKey, routeRef);
+        provide(viewDepthKey, props.depthRef);
+        provide(routeOverrideKey, routeRef);
+        provide(isInModalKey, TRUE_REF);
+
+        return (): VNodeChild => slots.default?.();
+    }
+});