@craft-ts/core 0.7.0-beta.13

package/src/lib/craft-router.js

@@ -0,0 +1,559 @@
+import { DestroyRef, EnvironmentInjector, Injector, inject, getCraftRootDefaultProviders, } from './host/craft-compat';
+import { isCraftLoadingFeature, provideCraftLoading, } from './craft-pending';
+import { CRAFT_TITLE_STRATEGY, createCraftTitleStrategy, } from './craft-a11y';
+import { ActivatedRoute, } from './host/craft-router-types';
+import { ɵtoCraftService as toCraftService, } from './craft-service';
+import { CRAFT_VIEW_TRANSITION_STATE_KEY, } from './craft-view-transition';
+import { CRAFT_NODE_EFFECT_FACTORY, craftNodeDirective, } from './craft-node-directive';
+import { executeYieldable } from './yieldable';
+import { executeGeneratorCompatibleFactoryAsync } from './craft-program-runtime';
+import { buildPathFromTemplate, createBrowserHistory, createUrlFromParts, findUnresolvedLoadChildrenRoute, matchCraftRoutes, matchCraftRoutesAsync, parseSearchParams, serializeLocation, splitPath, } from './host/craft-router-runtime';
+import { craftSignal, craftWatch, } from './host/craft-signal';
+import { CRAFT_COMPILED_ROUTES, CRAFT_HISTORY, CRAFT_LOCATION, CRAFT_MATCH, CRAFT_ROUTER, } from './craft-router-tokens';
+import { CRAFT_PLATFORM } from './craft-platform';
+export { createBrowserHistory, createMemoryHistory, matchCraftRoutes, matchCraftRoutesAsync, } from './host/craft-router-runtime';
+export { CRAFT_COMPILED_ROUTES, CRAFT_HISTORY, CRAFT_LOCATION, CRAFT_MATCH, CRAFT_ROUTER, } from './craft-router-tokens';
+// The `toCraftService` return type references internal Angular symbols
+// (`SIGNAL`, `[iterator]`, `[unscopables]`) that ng-packagr cannot serialize to
+// `.d.ts` (TS4023/TS4118). Cast through `unknown` and re-shape the destructured
+// locals as opaque `Function` so declaration emit only sees a serializable
+// shape. The exported `CraftRouter` below re-casts
+// through `as unknown as ...`, so the lost typing here doesn't reach consumers.
+const _routerService = toCraftService({
+    name: 'CraftRouter',
+    providedIn: 'manuallyProvidedAtRoot',
+    token: CRAFT_ROUTER,
+    provide: provideCraftRouterRuntime,
+}, (router) => router);
+const provideCraftRouterInternal = _routerService.provideCraftRouter;
+const CraftRouterInternal = _routerService.CraftRouter;
+/**
+ * Registers the Craft history matcher AND the non-blocking outlet's
+ * pending/error surface in one call. Craft loading features
+ * (`withErrorComponent()`, `withTransitionTimings()`, `withPendingComponent()`,
+ * `withLoadingText()`, `withCraftViewTransitions()`) are applied; leftover
+ * Angular `RouterFeatures` such as `withComponentInputBinding()` are ignored
+ * (input binding is owned by the outlet).
+ *
+ * ```ts
+ * provideCraftRouter(
+ *   demoRoutes.toRoutes(),
+ *   withErrorComponent({ component: CraftGlobalErrorComponentHost }),
+ *   withTransitionTimings({ stayMs: 300, blankMs: 300, pendingMinMs: 500 }),
+ * )
+ * ```
+ */
+export function provideCraftRouter(routes, ...features) {
+    const loadingFeatures = [];
+    const configuredRoutes = [...routes];
+    for (const feature of features) {
+        if (isCraftLoadingFeature(feature)) {
+            loadingFeatures.push(feature);
+            if (feature.recoveryRoute) {
+                configuredRoutes.push(feature.recoveryRoute);
+            }
+        }
+    }
+    return [
+        ...getCraftRootDefaultProviders(),
+        provideCraftRouterInternal(configuredRoutes),
+        ...provideCraftLoading(...loadingFeatures),
+    ];
+}
+/**
+ * Yields the `CraftRouter` inside a generator. Two equivalent forms.
+ *
+ * # Derived shortcut — recommended
+ *
+ * ```ts
+ * yield* CraftRouter.navigate({
+ *   to: 'query/:userId',          // validated against the registry
+ *   params: { userId: '1' },      // validated against the path's :params
+ * });
+ * ```
+ *
+ * `to` must match a path in `CraftRouterRoutesRegistry`; typos produce a
+ * "Did you mean…" error. `params` and `queryParams` are validated against
+ * that route's declaration.
+ *
+ * # Full router access
+ *
+ * ```ts
+ * const router = yield* CraftRouter();
+ * router.events.subscribe(...);
+ * ```
+ *
+ * Use this when you need a router property the shortcut doesn't expose
+ * (e.g. `events`, `routerState`, `url`).
+ *
+ * # Registry setup
+ *
+ * For the path validation to work without creating a self-referencing cycle,
+ * the registry augmentation must use the slim `META_PATHS` view, not
+ * `META_DATA`:
+ *
+ * ```ts
+ * declare module '@craft-ts/core' {
+ *   interface CraftRouterRoutesRegistry {
+ *     Demo: typeof demoRoutes.META_PATHS;
+ *   }
+ * }
+ * ```
+ *
+ * `META_DATA` stays available on the same `craftRoutes` result for tooling
+ * that needs the full per-route component dependencies (e.g. an e2e test
+ * runner that mocks every endpoint a route can reach).
+ */
+export const CraftRouter = CraftRouterInternal;
+/**
+ * Functional Craft directive for type-safe router links.
+ *
+ * @example
+ * a({ craftRouterLink: { to: 'tasks' } }, 'Tasks').pipe(CraftRouterLink)
+ */
+export const CraftRouterLink = craftNodeDirective('CraftRouterLink', ['craftRouterLink'], (context) => {
+    const router = context.injector.get(CRAFT_ROUTER);
+    let currentInput;
+    let currentUrlTree;
+    const syncAriaCurrent = () => {
+        if (!currentUrlTree) {
+            context.renderer.removeAttribute(context.element, 'aria-current');
+            return;
+        }
+        const active = router.isActive(currentUrlTree, {
+            paths: 'exact',
+            queryParams: 'ignored',
+            fragment: 'ignored',
+            matrixParams: 'ignored',
+        });
+        if (active) {
+            context.renderer.setAttribute(context.element, 'aria-current', 'page');
+        }
+        else {
+            context.renderer.removeAttribute(context.element, 'aria-current');
+        }
+    };
+    const hrefEffect = context.injector.get(CRAFT_NODE_EFFECT_FACTORY)('router-link-href', () => {
+        const candidate = context.props.craftRouterLink;
+        currentInput =
+            typeof candidate === 'function'
+                ? executeYieldable(candidate, [], context.injector)
+                : candidate;
+        if (!currentInput) {
+            currentUrlTree = undefined;
+            context.renderer.removeAttribute(context.element, 'href');
+            syncAriaCurrent();
+            return;
+        }
+        currentUrlTree = router.createUrlTree(currentInput);
+        context.renderer.setAttribute(context.element, 'href', router.serializeUrl(currentUrlTree));
+        syncAriaCurrent();
+    });
+    const navigation = router.events.subscribe((event) => {
+        if (event.type === 'NavigationEnd')
+            syncAriaCurrent();
+    });
+    const removeClickListener = context.renderer.listen(context.element, 'click', (event) => {
+        const mouseEvent = event;
+        if (!currentInput ||
+            !currentUrlTree ||
+            !shouldHandleCraftRouterLinkClick(mouseEvent, context.element)) {
+            return;
+        }
+        mouseEvent.preventDefault();
+        void router.navigateByUrl(currentUrlTree, getNavigationBehaviorOptions(currentInput));
+    });
+    return () => {
+        removeClickListener();
+        navigation.unsubscribe();
+        hrefEffect.destroy();
+    };
+});
+export function shouldHandleCraftRouterLinkClick(event, element) {
+    if (event.defaultPrevented ||
+        event.button !== 0 ||
+        event.ctrlKey ||
+        event.shiftKey ||
+        event.altKey ||
+        event.metaKey) {
+        return false;
+    }
+    const target = element.getAttribute('target');
+    if (target && target.toLowerCase() !== '_self')
+        return false;
+    if (element.hasAttribute('download'))
+        return false;
+    if (element.hasAttribute('disabled') ||
+        element.getAttribute('aria-disabled') === 'true') {
+        return false;
+    }
+    return true;
+}
+function emptyParamMap() {
+    return {
+        has: () => false,
+        get: () => null,
+        getAll: () => [],
+        keys: [],
+    };
+}
+function emptyActivatedRouteSnapshot() {
+    const snapshot = {
+        routeConfig: null,
+        url: [],
+        params: {},
+        queryParams: {},
+        fragment: null,
+        data: {},
+        outlet: 'primary',
+        paramMap: emptyParamMap(),
+        queryParamMap: emptyParamMap(),
+        parent: null,
+        root: null,
+        firstChild: null,
+        children: [],
+        pathFromRoot: [],
+    };
+    snapshot.root = snapshot;
+    snapshot.pathFromRoot = [snapshot];
+    return snapshot;
+}
+function matchToRouterStateSnapshot(match) {
+    const makeNode = (route, firstChild) => ({
+        routeConfig: route,
+        url: [],
+        params: match.params,
+        queryParams: match.queryParams,
+        fragment: match.hash ? match.hash.replace(/^#/, '') || null : null,
+        data: (route.data ?? match.data ?? {}),
+        outlet: 'primary',
+        title: typeof route.title === 'string' ? route.title : undefined,
+        paramMap: emptyParamMap(),
+        queryParamMap: emptyParamMap(),
+        parent: null,
+        root: null,
+        firstChild,
+        children: firstChild ? [firstChild] : [],
+        pathFromRoot: [],
+    });
+    let child = null;
+    for (let index = match.routes.length - 1; index >= 0; index -= 1) {
+        child = makeNode(match.routes[index], child);
+    }
+    const root = child ?? makeNode(match.route, null);
+    const path = [];
+    let current = root;
+    while (current) {
+        path.push(current);
+        current = current.firstChild;
+    }
+    path.forEach((node, index) => {
+        node.parent = index > 0 ? path[index - 1] : null;
+        node.pathFromRoot = path.slice(0, index + 1);
+        node.root = root;
+    });
+    return { url: serializeLocation(match), root };
+}
+function commitCraftMatch(match, history, location, resolved, titleStrategy) {
+    match.set(resolved);
+    if (resolved && serializeLocation(resolved) !== serializeLocation(location)) {
+        history.replace(serializeLocation(resolved), history.getState());
+    }
+    if (resolved) {
+        titleStrategy.updateTitle(matchToRouterStateSnapshot(resolved));
+    }
+}
+async function resolveFunctionRedirectTo(match, parent) {
+    const redirectTo = match.route.redirectTo;
+    if (typeof redirectTo !== 'function') {
+        return null;
+    }
+    const providers = Array.isArray(match.route.providers)
+        ? match.route.providers
+        : [];
+    const injector = providers.length > 0
+        ? Injector.create({
+            providers,
+            parent,
+            name: 'CraftRedirectTo',
+        })
+        : parent;
+    const settled = await executeGeneratorCompatibleFactoryAsync({
+        factory: redirectTo,
+        thisArg: undefined,
+        getInjector: () => injector,
+        args: [],
+        invalidYieldErrorMessage: 'craft redirectTo can only yield craftService dependencies, exposed dependency helpers, or an craftUntilSettled/craftUntilDefined await request.',
+    });
+    if (settled.kind !== 'done') {
+        return null;
+    }
+    const value = settled.value;
+    if (typeof value === 'string' && value.length > 0) {
+        return value;
+    }
+    if (value &&
+        typeof value === 'object' &&
+        typeof value.toString === 'function') {
+        const url = String(value);
+        return url.length > 0 && url !== '[object Object]' ? url : null;
+    }
+    return null;
+}
+function toAbsoluteRedirectUrl(url) {
+    return url.startsWith('/') ? url : `/${url}`;
+}
+function provideCraftRouterRuntime(routes = [], ..._features) {
+    const navigation = { current: null };
+    return [
+        { provide: CRAFT_COMPILED_ROUTES, useValue: routes },
+        {
+            provide: CRAFT_TITLE_STRATEGY,
+            useFactory: () => createCraftTitleStrategy(),
+        },
+        {
+            // The Angular island used to bridge this token onto Angular's own
+            // ActivatedRoute. The Craft router owns it now: it is the leaf of the
+            // snapshot built from the current match, and empty before the first one.
+            provide: ActivatedRoute,
+            useFactory: (match) => {
+                const leafOf = (snapshot) => {
+                    let node = snapshot;
+                    while (node.firstChild)
+                        node = node.firstChild;
+                    return node;
+                };
+                const snapshot = () => {
+                    const current = match();
+                    return current
+                        ? leafOf(matchToRouterStateSnapshot(current).root)
+                        : emptyActivatedRouteSnapshot();
+                };
+                return {
+                    get snapshot() {
+                        return snapshot();
+                    },
+                    get pathFromRoot() {
+                        return snapshot().pathFromRoot.map((node) => ({
+                            snapshot: node,
+                            pathFromRoot: [],
+                        }));
+                    },
+                };
+            },
+            deps: [CRAFT_MATCH],
+        },
+        {
+            provide: CRAFT_HISTORY,
+            useFactory: () => {
+                const platform = inject(Injector).get(CRAFT_PLATFORM, null);
+                const history = platform?.history ?? createBrowserHistory(globalThis.window);
+                inject(DestroyRef).onDestroy(() => history.dispose());
+                return history;
+            },
+        },
+        {
+            provide: CRAFT_LOCATION,
+            useFactory: (history) => {
+                const location = craftSignal(history.get());
+                const stop = history.listen((next) => location.set(next));
+                inject(DestroyRef).onDestroy(stop);
+                return location;
+            },
+            deps: [CRAFT_HISTORY],
+        },
+        {
+            provide: CRAFT_MATCH,
+            useFactory: (location, compiled, history) => {
+                const environmentInjector = inject(EnvironmentInjector);
+                const titleStrategy = inject(CRAFT_TITLE_STRATEGY, { optional: true }) ??
+                    createCraftTitleStrategy();
+                const match = craftSignal(null);
+                let generation = 0;
+                craftWatch(() => {
+                    const nextLocation = location();
+                    const current = ++generation;
+                    const syncMatch = matchCraftRoutes(compiled, nextLocation);
+                    if (typeof syncMatch?.route.redirectTo === 'function') {
+                        void resolveFunctionRedirectTo(syncMatch, environmentInjector)
+                            .then((redirectUrl) => {
+                            if (current !== generation || !redirectUrl) {
+                                return;
+                            }
+                            const target = toAbsoluteRedirectUrl(redirectUrl);
+                            if (target === serializeLocation(nextLocation)) {
+                                return;
+                            }
+                            history.replace(target, history.getState());
+                        })
+                            .catch(() => {
+                            // Keep the previous match instead of mounting the redirect route.
+                        });
+                        return;
+                    }
+                    const pendingLocation = syncMatch ?? nextLocation;
+                    const pending = findUnresolvedLoadChildrenRoute(compiled, splitPath(pendingLocation.pathname || '/'));
+                    if (pending) {
+                        void matchCraftRoutesAsync(compiled, {
+                            ...nextLocation,
+                            pathname: pendingLocation.pathname || '/',
+                            search: pendingLocation.search,
+                            hash: pendingLocation.hash,
+                        }).then((resolved) => {
+                            if (current !== generation) {
+                                return;
+                            }
+                            commitCraftMatch(match, history, nextLocation, resolved, titleStrategy);
+                            navigation.current = null;
+                        }, () => {
+                            // Keep the previous match. Inflight is cleared in
+                            // ensureChildrenLoaded so a later navigation can retry.
+                        });
+                        return;
+                    }
+                    commitCraftMatch(match, history, nextLocation, syncMatch, titleStrategy);
+                    navigation.current = null;
+                });
+                return match;
+            },
+            deps: [CRAFT_LOCATION, CRAFT_COMPILED_ROUTES, CRAFT_HISTORY],
+        },
+        {
+            provide: CRAFT_ROUTER,
+            useFactory: (history, location) => createNativeCraftRouter(history, location, navigation),
+            deps: [CRAFT_HISTORY, CRAFT_LOCATION],
+        },
+    ];
+}
+function createNativeCraftRouter(history, location, navigation) {
+    const listeners = new Set();
+    const toUrl = (input) => {
+        const current = history.get();
+        let query = input.queryParams ?? undefined;
+        if (input.queryParamsHandling === 'preserve') {
+            query = parseSearchParams(current.search);
+        }
+        else if (input.queryParamsHandling === 'merge') {
+            query = {
+                ...parseSearchParams(current.search),
+                ...(input.queryParams ?? {}),
+            };
+        }
+        const fragment = input.preserveFragment
+            ? current.hash.replace(/^#/, '') || undefined
+            : (input.fragment ?? undefined);
+        return createUrlFromParts(buildPathFromTemplate(input.to, input.params), query, fragment);
+    };
+    const createUrlTree = (input) => {
+        const url = toUrl(input);
+        return { toString: () => url, __craftUrlTree: true };
+    };
+    const commit = (url, extras) => {
+        const withVt = extras
+            ? {
+                ...extras,
+                state: withViewTransitionState(extras, extras.state),
+            }
+            : extras;
+        navigation.current = { extras: withVt };
+        for (const listener of listeners) {
+            listener({ type: 'NavigationStart', url });
+        }
+        if (withVt?.skipLocationChange) {
+            history.skip(url, withVt.state ?? null);
+        }
+        else if (withVt?.replaceUrl) {
+            history.replace(url, withVt.state ?? null);
+        }
+        else {
+            history.push(url, withVt?.state ?? null);
+        }
+        for (const listener of listeners) {
+            listener({ type: 'NavigationEnd', url });
+        }
+        return Promise.resolve(true);
+    };
+    return {
+        get url() {
+            return serializeLocation(location());
+        },
+        createUrlTree,
+        navigate: (input) => commit(toUrl(input), input),
+        navigateByUrl: ((input, extras) => {
+            if (typeof input === 'string') {
+                return commit(input, extras);
+            }
+            if (input &&
+                typeof input === 'object' &&
+                'to' in input &&
+                typeof input.to === 'string') {
+                const navigationInput = input;
+                return commit(toUrl(navigationInput), {
+                    ...extras,
+                    ...navigationInput,
+                });
+            }
+            return commit(String(input), extras);
+        }),
+        serializeUrl: (tree) => tree.toString(),
+        isActive: (tree, extras) => {
+            const target = String(tree).split('?')[0]?.split('#')[0] ?? '';
+            const current = location().pathname;
+            if (extras?.paths === 'subset') {
+                return current === target || current.startsWith(`${target}/`);
+            }
+            return current === target;
+        },
+        events: {
+            subscribe(fn) {
+                listeners.add(fn);
+                return {
+                    unsubscribe: () => {
+                        listeners.delete(fn);
+                    },
+                };
+            },
+        },
+        getCurrentNavigation: () => navigation.current,
+    };
+}
+export function createCraftRouterCommands(input) {
+    if (input.to === '') {
+        return ['/'];
+    }
+    const segments = input.to.split('/').filter(Boolean);
+    if (segments.length === 0) {
+        return ['/'];
+    }
+    return segments.map((segment, index) => {
+        const value = segment.startsWith(':')
+            ? resolveRouteParamValue(segment, input)
+            : segment;
+        return index === 0 ? `/${value}` : value;
+    });
+}
+function resolveRouteParamValue(segment, input) {
+    const paramName = segment.slice(1).replace(/\?$/, '');
+    const value = input.params?.[paramName];
+    if (value === undefined) {
+        throw new Error(`Missing route param "${paramName}" for route "${input.to}".`);
+    }
+    return value;
+}
+function getNavigationBehaviorOptions(input) {
+    return {
+        replaceUrl: input.replaceUrl,
+        skipLocationChange: input.skipLocationChange,
+        state: withViewTransitionState(input, input.state),
+    };
+}
+function withViewTransitionState(input, state) {
+    if (input.viewTransition === undefined) {
+        return state;
+    }
+    return {
+        ...(state ?? {}),
+        [CRAFT_VIEW_TRANSITION_STATE_KEY]: input.viewTransition,
+    };
+}
+//# sourceMappingURL=craft-router.js.map