@real-router/angular 0.11.0 → 0.11.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@real-router/angular",
-  "version": "0.11.0",
+  "version": "0.11.2",
   "type": "commonjs",
   "description": "Angular 21 integration for Real-Router",
   "exports": {
@@ -17,7 +17,6 @@
   },
   "files": [
     "dist",
-    "src",
     "ssr"
   ],
   "homepage": "https://github.com/greydragon888/real-router",
@@ -41,18 +40,18 @@
   "license": "MIT",
   "sideEffects": false,
   "dependencies": {
-    "@real-router/core": "^0.54.6",
-    "@real-router/route-utils": "^0.2.2",
-    "@real-router/sources": "^0.8.3"
+    "@real-router/core": "^0.56.0",
+    "@real-router/route-utils": "^0.2.3",
+    "@real-router/sources": "^0.8.5"
   },
   "devDependencies": {
-    "@analogjs/vitest-angular": "2.4.7",
+    "@analogjs/vitest-angular": "2.6.0",
     "@angular/common": "21.2.13",
     "@angular/compiler": "21.2.13",
     "@angular/compiler-cli": "21.2.13",
     "@angular/core": "21.2.13",
     "@angular/platform-browser": "21.2.13",
-    "ng-packagr": "21.2.2",
+    "ng-packagr": "21.2.3",
     "typescript": "6.0.3"
   },
   "peerDependencies": {

package/src/components/NavigationAnnouncer.ts

@@ -1,18 +0,0 @@
-import { Component, inject, DestroyRef } from "@angular/core";
-
-import { createRouteAnnouncer } from "../dom-utils";
-import { injectRouter } from "../functions/injectRouter";
-
-@Component({
-  selector: "navigation-announcer",
-  template: "",
-})
-export class NavigationAnnouncer {
-  private readonly announcer = createRouteAnnouncer(injectRouter());
-
-  constructor() {
-    inject(DestroyRef).onDestroy(() => {
-      this.announcer.destroy();
-    });
-  }
-}

package/src/components/RouteView.ts

@@ -1,141 +0,0 @@
-import { NgTemplateOutlet } from "@angular/common";
-import {
-  Component,
-  computed,
-  contentChildren,
-  effect,
-  input,
-  signal,
-  type TemplateRef,
-} from "@angular/core";
-import { UNKNOWN_ROUTE } from "@real-router/core";
-import { startsWithSegment } from "@real-router/route-utils";
-import { createRouteNodeSource } from "@real-router/sources";
-
-import { RouteMatch } from "../directives/RouteMatch";
-import { RouteNotFound } from "../directives/RouteNotFound";
-import { RouteSelf } from "../directives/RouteSelf";
-import { injectRouter } from "../functions/injectRouter";
-import { subscribeSourceToSignal } from "../internal/subscribeSourceToSignal";
-
-import type { RouteSnapshot } from "@real-router/sources";
-
-const EMPTY_SNAPSHOT: RouteSnapshot = {
-  route: undefined,
-  previousRoute: undefined,
-};
-
-@Component({
-  selector: "route-view",
-  template: `
-    @if (activeTemplate()) {
-      <ng-container [ngTemplateOutlet]="activeTemplate()!" />
-    }
-  `,
-  imports: [NgTemplateOutlet],
-})
-export class RouteView {
-  readonly nodeName = input<string>("", { alias: "routeNode" });
-
-  readonly matches = contentChildren(RouteMatch, { descendants: true });
-  readonly selfs = contentChildren(RouteSelf, { descendants: true });
-  readonly notFounds = contentChildren(RouteNotFound, { descendants: true });
-
-  readonly activeTemplate = computed<TemplateRef<unknown> | null>(
-    () => this.matchedTemplate() ?? this.fallbackTemplate(),
-  );
-
-  private readonly router = injectRouter();
-  private readonly routeState = signal<RouteSnapshot>(EMPTY_SNAPSHOT);
-
-  private readonly matchEntries = computed(() => {
-    const nodeName = this.nodeName();
-
-    return this.matches().map((match) => {
-      const segment = match.routeMatch();
-
-      return {
-        match,
-        fullSegmentName: nodeName ? `${nodeName}.${segment}` : segment,
-      };
-    });
-  });
-
-  // The matched template (Match priority) is independent of the Self /
-  // NotFound fallback chain. Splitting the two paths into separate computeds
-  // localises re-runs: a change to `selfs()` / `notFounds()` no longer
-  // re-evaluates the Match loop (review §8a LOW — RouteView activeTemplate
-  // split).
-  private readonly matchedTemplate = computed<TemplateRef<unknown> | null>(
-    () => {
-      const route = this.routeState().route;
-
-      if (!route) {
-        return null;
-      }
-
-      const routeName = route.name;
-
-      for (const { match, fullSegmentName } of this.matchEntries()) {
-        if (startsWithSegment(routeName, fullSegmentName)) {
-          return match.templateRef;
-        }
-      }
-
-      return null;
-    },
-  );
-
-  // Fallback chain — only consulted when `matchedTemplate()` returned `null`.
-  // Template priority: Self → NotFound. Selection rules differ on purpose:
-  //   - **Self uses first-wins** (`.at(0)`) for parity with React / Preact /
-  //     Solid / Vue, where the first matching `<Self>` token in declaration
-  //     order wins.
-  //   - **NotFound uses last-wins** (`.at(-1)`) intentionally — the fallback
-  //     should be the most-recently-declared template so that consumers can
-  //     override an inherited `<ng-template routeNotFound>` simply by
-  //     re-declaring it lower in the projected content.
-  private readonly fallbackTemplate = computed<TemplateRef<unknown> | null>(
-    () => {
-      const route = this.routeState().route;
-
-      if (!route) {
-        return null;
-      }
-
-      const routeName = route.name;
-
-      if (routeName === this.nodeName()) {
-        const first = this.selfs().at(0);
-
-        if (first) {
-          return first.templateRef;
-        }
-      }
-
-      if (routeName === UNKNOWN_ROUTE) {
-        const last = this.notFounds().at(-1);
-
-        if (last) {
-          return last.templateRef;
-        }
-      }
-
-      return null;
-    },
-  );
-
-  constructor() {
-    // Reactive source-creation effect (#630 fix) — see
-    // `packages/angular/CLAUDE.md` → "Directives use constructor + effect()".
-    effect((onCleanup) => {
-      const source = createRouteNodeSource(this.router, this.nodeName());
-
-      onCleanup(
-        subscribeSourceToSignal(source, (snap) => {
-          this.routeState.set(snap);
-        }),
-      );
-    });
-  }
-}

package/src/components/RouterErrorBoundary.ts

@@ -1,72 +0,0 @@
-import { NgTemplateOutlet } from "@angular/common";
-import { Component, computed, effect, input, output } from "@angular/core";
-import { createDismissableError } from "@real-router/sources";
-
-import { injectRouter } from "../functions/injectRouter";
-import { sourceToSignal } from "../sourceToSignal";
-
-import type { ErrorContext } from "../types";
-import type { TemplateRef } from "@angular/core";
-import type { RouterError, State } from "@real-router/core";
-import type { DismissableErrorSnapshot } from "@real-router/sources";
-
-@Component({
-  selector: "router-error-boundary",
-  template: `
-    <ng-content />
-    @if (errorContext() && errorTemplate()) {
-      <ng-container
-        [ngTemplateOutlet]="errorTemplate()!"
-        [ngTemplateOutletContext]="errorContext()!"
-      />
-    }
-  `,
-  imports: [NgTemplateOutlet],
-})
-export class RouterErrorBoundary {
-  readonly errorTemplate = input<TemplateRef<ErrorContext>>();
-
-  readonly onError = output<{
-    error: RouterError;
-    toRoute: State | null;
-    fromRoute: State | null;
-  }>();
-
-  readonly errorContext = computed<ErrorContext | null>(() => {
-    const snap = this.snapshot();
-
-    if (!snap.error) {
-      return null;
-    }
-
-    return {
-      $implicit: snap.error,
-      resetError: snap.resetError,
-    };
-  });
-
-  private readonly router = injectRouter();
-  private readonly snapshot = sourceToSignal<DismissableErrorSnapshot>(
-    createDismissableError(this.router),
-  );
-
-  constructor() {
-    // `effect()` registers itself with the current injection context's
-    // `DestroyRef` and tears down automatically when the component is
-    // destroyed. The earlier manual `effectRef.destroy()` wired through
-    // `inject(DestroyRef).onDestroy(...)` duplicated that built-in cleanup
-    // (audit §8.1 LOW — confirmed: no behavior change without the manual
-    // path).
-    effect(() => {
-      const snap = this.snapshot();
-
-      if (snap.error) {
-        this.onError.emit({
-          error: snap.error,
-          toRoute: snap.toRoute,
-          fromRoute: snap.fromRoute,
-        });
-      }
-    });
-  }
-}

package/src/directives/RealLink.ts

@@ -1,144 +0,0 @@
-import {
-  Directive,
-  ElementRef,
-  computed,
-  effect,
-  inject,
-  input,
-  signal,
-} from "@angular/core";
-import { createActiveRouteSource } from "@real-router/sources";
-
-import { buildHref, navigateWithHash, shouldNavigate } from "../dom-utils";
-import { injectRouter } from "../functions/injectRouter";
-import { buildActiveRouteOptions } from "../internal/buildActiveRouteOptions";
-import { subscribeSourceToSignal } from "../internal/subscribeSourceToSignal";
-
-import type { Params, NavigationOptions } from "@real-router/core";
-
-const NOOP_CATCH = (): void => {};
-
-@Directive({
-  selector: "a[realLink]",
-  host: {
-    "(click)": "onClick($event)",
-  },
-})
-export class RealLink {
-  readonly routeName = input<string>("");
-  readonly routeParams = input<Params>({});
-  readonly routeOptions = input<NavigationOptions>({});
-  readonly activeClassName = input<string>("active");
-  readonly activeStrict = input(false);
-  readonly ignoreQueryParams = input(true);
-  /**
-   * URL fragment (decoded form, no leading "#") (#532).
-   * - omitted/`undefined` → preserve current fragment on same-route navigation
-   * - `""` → clear fragment
-   * - non-empty → set fragment
-   */
-  readonly hash = input<string | undefined>(undefined);
-
-  private readonly router = injectRouter();
-  private readonly anchor = inject(ElementRef)
-    .nativeElement as HTMLAnchorElement;
-  private readonly isActive = signal(false);
-  // `href` is computed from signal inputs only — Angular's default Object.is
-  // equality already collapses repeated `string` results, so no custom
-  // comparator is required (review §8b note 3 — applies after verifying that
-  // `buildHref` returns a primitive).
-  private readonly href = computed(() => {
-    const hashValue = this.hash();
-
-    return buildHref(
-      this.router,
-      this.routeName(),
-      this.routeParams(),
-      hashValue === undefined ? undefined : { hash: hashValue },
-    );
-  });
-  private prevActiveClass = "";
-  private prevHref: string | undefined = undefined;
-  // Skip-same-value: only re-touch the DOM `class` list when the active state
-  // actually flipped. Without this, every navigation that re-fires the active
-  // source still issues a `classList.toggle` no-op (review §8b MEDIUM).
-  private prevActive: boolean | undefined = undefined;
-
-  constructor() {
-    // Reactive source-creation effect (#630 fix) — see
-    // `packages/angular/CLAUDE.md` → "Directives use constructor + effect()".
-    // Reading signal inputs inside `effect()` re-creates the active-route
-    // source whenever any input changes; `onCleanup` tears the previous
-    // subscription down.
-    effect((onCleanup) => {
-      const source = createActiveRouteSource(
-        this.router,
-        this.routeName(),
-        this.routeParams(),
-        buildActiveRouteOptions(
-          this.activeStrict(),
-          this.ignoreQueryParams(),
-          this.hash(),
-        ),
-      );
-
-      onCleanup(
-        subscribeSourceToSignal(source, (snap) => {
-          // Pure-href refresh: when the active flag did not change, only the
-          // href may have moved (e.g. param-only update on a parent route).
-          // Skip the classList work in that branch (review §8b MEDIUM).
-          if (snap === this.prevActive) {
-            this.isActive.set(snap);
-            this.updateHref();
-
-            return;
-          }
-
-          this.prevActive = snap;
-          this.isActive.set(snap);
-          this.updateHref();
-          this.updateActiveClass();
-        }),
-      );
-    });
-  }
-
-  onClick(event: MouseEvent): void {
-    if (!shouldNavigate(event) || this.anchor.target === "_blank") {
-      return;
-    }
-
-    event.preventDefault();
-    navigateWithHash(
-      this.router,
-      this.routeName(),
-      this.routeParams(),
-      this.hash(),
-      this.routeOptions(),
-    ).catch(NOOP_CATCH);
-  }
-
-  private updateHref(): void {
-    const href = this.href();
-
-    if (href !== undefined && href !== this.prevHref) {
-      this.anchor.setAttribute("href", href);
-    }
-
-    this.prevHref = href;
-  }
-
-  private updateActiveClass(): void {
-    const activeClass = this.activeClassName();
-
-    if (this.prevActiveClass && this.prevActiveClass !== activeClass) {
-      this.anchor.classList.remove(this.prevActiveClass);
-    }
-
-    if (activeClass) {
-      this.anchor.classList.toggle(activeClass, this.isActive());
-    }
-
-    this.prevActiveClass = activeClass;
-  }
-}

package/src/directives/RealLinkActive.ts

@@ -1,77 +0,0 @@
-import {
-  Directive,
-  ElementRef,
-  effect,
-  inject,
-  input,
-  signal,
-} from "@angular/core";
-import { createActiveRouteSource } from "@real-router/sources";
-
-import { applyLinkA11y } from "../dom-utils";
-import { injectRouter } from "../functions/injectRouter";
-import { buildActiveRouteOptions } from "../internal/buildActiveRouteOptions";
-import { subscribeSourceToSignal } from "../internal/subscribeSourceToSignal";
-
-import type { Params } from "@real-router/core";
-
-@Directive({ selector: "[realLinkActive]" })
-export class RealLinkActive {
-  readonly realLinkActive = input<string>("");
-  readonly routeName = input<string>("");
-  readonly routeParams = input<Params>({});
-  readonly activeStrict = input(false);
-  readonly ignoreQueryParams = input(true);
-
-  private readonly router = injectRouter();
-  private readonly element = inject(ElementRef).nativeElement as HTMLElement;
-  private readonly isActive = signal(false);
-  // Skip-same-value: only touch `classList.toggle` when the active flag
-  // actually flipped. Saves one DOM write per RealLinkActive per unrelated
-  // navigation (review §8b MEDIUM).
-  private prevActive: boolean | undefined = undefined;
-
-  constructor() {
-    // One-time a11y setup — doesn't depend on signal inputs, stays in
-    // constructor body. `applyLinkA11y` is idempotent so re-running would
-    // be safe, but we only need it once per element.
-    applyLinkA11y(this.element);
-
-    // Reactive source-creation effect (#630 fix) — see
-    // `packages/angular/CLAUDE.md` → "Directives use constructor + effect()".
-    effect((onCleanup) => {
-      const source = createActiveRouteSource(
-        this.router,
-        this.routeName(),
-        this.routeParams(),
-        buildActiveRouteOptions(
-          this.activeStrict(),
-          this.ignoreQueryParams(),
-          undefined,
-        ),
-      );
-
-      onCleanup(
-        subscribeSourceToSignal(source, (snap) => {
-          if (snap === this.prevActive) {
-            return;
-          }
-
-          this.prevActive = snap;
-          this.isActive.set(snap);
-          this.updateClass();
-        }),
-      );
-    });
-  }
-
-  private updateClass(): void {
-    const className = this.realLinkActive();
-
-    if (!className) {
-      return;
-    }
-
-    this.element.classList.toggle(className, this.isActive());
-  }
-}

package/src/directives/RouteMatch.ts

@@ -1,7 +0,0 @@
-import { Directive, TemplateRef, inject, input } from "@angular/core";
-
-@Directive({ selector: "ng-template[routeMatch]" })
-export class RouteMatch {
-  readonly routeMatch = input.required<string>();
-  readonly templateRef = inject(TemplateRef);
-}

package/src/directives/RouteNotFound.ts

@@ -1,6 +0,0 @@
-import { Directive, TemplateRef, inject } from "@angular/core";
-
-@Directive({ selector: "ng-template[routeNotFound]" })
-export class RouteNotFound {
-  readonly templateRef = inject(TemplateRef);
-}

package/src/directives/RouteSelf.ts

@@ -1,6 +0,0 @@
-import { Directive, TemplateRef, inject } from "@angular/core";
-
-@Directive({ selector: "ng-template[routeSelf]" })
-export class RouteSelf {
-  readonly templateRef = inject(TemplateRef);
-}

package/src/dom-utils/direction-tracker.ts

@@ -1,70 +0,0 @@
-import type { Router } from "@real-router/core";
-
-export interface DirectionTracker {
-  destroy: () => void;
-}
-
-const NOOP_INSTANCE: DirectionTracker = Object.freeze({
-  destroy: () => {
-    /* no-op */
-  },
-});
-
-/**
- * Track navigation direction (forward / back) and write it to
- * `<html data-nav-direction>` on every leave. CSS / JS readers consume
- * the attribute via `html[data-nav-direction="back"]` selectors or
- * `document.documentElement.dataset.navDirection`.
- *
- * Mechanism-agnostic — works identically whether downstream UI uses CSS
- * `@keyframes`, View Transitions pseudo-elements, or library state
- * (motion's `motion.div initial={{ x: ... }}`).
- *
- * Implementation:
- *   - On install, set `data-nav-direction="forward"` baseline.
- *   - Attach a `popstate` listener that flips an internal flag to
- *     `true`. Browser back/forward navigation triggers popstate; user
- *     clicks on `<Link>` / programmatic `router.navigate(...)` do not.
- *   - On every `subscribeLeave`, write
- *     `popstateFlag ? "back" : "forward"` and reset the flag.
- *
- * Returns `{ destroy }` to clean up the listener and clear the dataset
- * attribute.
- */
-export function createDirectionTracker(router: Router): DirectionTracker {
-  if (typeof document === "undefined") {
-    return NOOP_INSTANCE;
-  }
-
-  let popstateFlag = false;
-
-  document.documentElement.dataset.navDirection = "forward";
-
-  const onPopstate = (): void => {
-    popstateFlag = true;
-  };
-
-  // IMPORTANT — listener-ordering: `popstate` fires on `window`, which
-  // has no DOM descendants, so capture phase is moot. Listeners are
-  // dispatched in registration order. To beat the browser-plugin's own
-  // popstate handler, this tracker must be installed **before**
-  // `router.usePlugin(browserPluginFactory())` in user code. Otherwise
-  // the plugin's handler runs first and synchronously fires
-  // `subscribeLeave` while `popstateFlag` is still `false`.
-  globalThis.addEventListener("popstate", onPopstate);
-
-  const offLeave = router.subscribeLeave(() => {
-    document.documentElement.dataset.navDirection = popstateFlag
-      ? "back"
-      : "forward";
-    popstateFlag = false;
-  });
-
-  return {
-    destroy: () => {
-      offLeave();
-      globalThis.removeEventListener("popstate", onPopstate);
-      delete document.documentElement.dataset.navDirection;
-    },
-  };
-}

package/src/dom-utils/index.ts

@@ -1,31 +0,0 @@
-export { createDirectionTracker } from "./direction-tracker";
-
-export { createRouteAnnouncer } from "./route-announcer";
-
-export { createScrollRestoration } from "./scroll-restore";
-
-export { createScrollSpy } from "./scroll-spy";
-
-export { createViewTransitions } from "./view-transitions";
-
-export {
-  shouldNavigate,
-  buildHref,
-  buildActiveClassName,
-  navigateWithHash,
-  shallowEqual,
-  applyLinkA11y,
-} from "./link-utils";
-
-export type { RouteAnnouncerOptions } from "./route-announcer";
-
-export type {
-  ScrollRestorationOptions,
-  ScrollRestorationMode,
-} from "./scroll-restore";
-
-export type { ScrollSpy, ScrollSpyOptions } from "./scroll-spy";
-
-export type { DirectionTracker } from "./direction-tracker";
-
-export type { ViewTransitions } from "./view-transitions";