@real-router/angular 0.0.1

package/src/directives/RealLinkActive.ts

@@ -0,0 +1,68 @@
+import {
+  Directive,
+  ElementRef,
+  inject,
+  input,
+  signal,
+  DestroyRef,
+  type OnInit,
+} from "@angular/core";
+import { createActiveRouteSource } from "@real-router/sources";
+
+import { applyLinkA11y } from "../dom-utils";
+import { injectRouter } from "../functions/injectRouter";
+
+import type { Params } from "@real-router/core";
+
+@Directive({ selector: "[realLinkActive]" })
+export class RealLinkActive implements OnInit {
+  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 destroyRef = inject(DestroyRef);
+  private readonly element = inject(ElementRef).nativeElement as HTMLElement;
+  private readonly isActive = signal(false);
+
+  constructor() {
+    applyLinkA11y(this.element);
+  }
+
+  ngOnInit(): void {
+    const source = createActiveRouteSource(
+      this.router,
+      this.routeName(),
+      this.routeParams(),
+      {
+        strict: this.activeStrict(),
+        ignoreQueryParams: this.ignoreQueryParams(),
+      },
+    );
+
+    this.isActive.set(source.getSnapshot());
+    this.updateClass();
+
+    const unsub = source.subscribe(() => {
+      this.isActive.set(source.getSnapshot());
+      this.updateClass();
+    });
+
+    this.destroyRef.onDestroy(() => {
+      unsub();
+      source.destroy();
+    });
+  }
+
+  private updateClass(): void {
+    const className = this.realLinkActive();
+
+    if (!className) {
+      return;
+    }
+
+    this.element.classList.toggle(className, this.isActive());
+  }
+}

package/src/directives/RouteMatch.ts

@@ -0,0 +1,7 @@
+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

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

package/src/dom-utils/CLAUDE.md

@@ -0,0 +1,76 @@
+# shared/dom-utils — Stable Shared Sources
+
+> DOM helpers инлайнятся во все framework-адаптеры. Код **зрелый**, API устоялся.
+
+## Status: stable
+
+Эти файлы — общий слой для 6 адаптеров (Preact, React, Solid, Vue, Svelte, Angular). Любое изменение здесь немедленно попадает в 6 публичных bundle'ов. Относиться как к low-level примитиву, а не к «просто утилитам».
+
+## Правила работы
+
+### 1. Отладка начинается в адаптере, а не здесь
+
+Перед правкой `shared/dom-utils/*.ts` убедись, что:
+- баг воспроизводится **минимум в 2 адаптерах** (иначе это adapter-specific проблема обёртки);
+- есть падающий тест в функциональном наборе соответствующего адаптера.
+
+Если баг живёт только в одном адаптере — правка идёт в адаптер, не сюда.
+
+### 2. Оптимизаций «на глаз» не делать
+
+Функции уже прошли итерации:
+- `buildActiveClassName` — токен-дедупликация через `Set`, O(n+m);
+- `applyLinkA11y` — defensive null-guard + `hasAttribute` (не `getAttribute`);
+- `buildHref` — optional `buildUrl` + undefined-fallback на `buildPath`;
+- `createRouteAnnouncer` — double `requestAnimationFrame` + Safari-ready буферизация через `pendingText`.
+
+«Рефактор ради чистоты» здесь запрещён — микро-изменение ломает сразу 6 bundle'ов. Изменение кода требует: конкретный баг/юз-кейс, тест на него, прогон `pnpm build`.
+
+### 3. Angular sync после любой правки
+
+`packages/angular/src/dom-utils/` — **git-tracked copy**, не symlink (ng-packagr не следует за symlinks как tsdown).
+
+После правки `shared/dom-utils/*.ts`:
+
+```bash
+pnpm -F @real-router/angular bundle     # пере-материализует копию через prebundle
+diff -r shared/dom-utils/ packages/angular/src/dom-utils/ | grep -v index.ts  # должно быть пусто
+```
+
+Коммитить нужно **оба** варианта: источник в `shared/` и копию в `packages/angular/src/dom-utils/`.
+
+### 4. Валидация изменений
+
+Минимальный чек-лист перед коммитом:
+
+```bash
+pnpm build                                           # 207+ тасков, все адаптеры
+pnpm -F @real-router/react test:properties -- --run  # property-тесты buildActiveClassName/buildHref
+pnpm -F @real-router/svelte test:properties -- --run # property-тесты (дублируют React, оба должны пройти)
+```
+
+## Консумеры
+
+| Источник | Как подключено | Пакеты |
+|---|---|---|
+| `shared/dom-utils/` | symlink → `src/dom-utils` | `preact`, `react`, `solid`, `svelte`, `vue` |
+| `shared/dom-utils/` | git-tracked copy (через `prebundle`) | `angular` |
+
+Проверка, что symlink цел: `readlink packages/preact/src/dom-utils` должен вернуть относительный путь к `shared/dom-utils/`.
+
+## Публичный контракт
+
+| Функция | Используется в | Стабильность |
+|---|---|---|
+| `shouldNavigate(evt)` | все `Link` компоненты + directives/actions | frozen |
+| `buildHref(router, name, params)` | все `Link` компоненты + Angular directive | frozen |
+| `buildActiveClassName(isActive, active, base)` | все `Link` компоненты | frozen |
+| `applyLinkA11y(el)` | все `Link` компоненты + directives | frozen |
+| `createRouteAnnouncer(router, opts)` | все `RouterProvider` / `NavigationAnnouncer` | frozen |
+
+«Frozen» = сигнатура и поведение не меняются без мажорного release-цикла core. Новые фичи — отдельными функциями, не модификацией существующих.
+
+## См. также
+
+- [../../CLAUDE.md](../../CLAUDE.md) — monorepo-level правила symlink-инфраструктуры
+- [../../IMPLEMENTATION_NOTES.md](../../IMPLEMENTATION_NOTES.md) — раздел "Shared Sources via Symlinks"

package/src/dom-utils/index.ts

@@ -0,0 +1,11 @@
+export { createRouteAnnouncer } from "./route-announcer";
+
+export {
+  shouldNavigate,
+  buildHref,
+  buildActiveClassName,
+  shallowEqual,
+  applyLinkA11y,
+} from "./link-utils";
+
+export type { RouteAnnouncerOptions } from "./route-announcer";

package/src/dom-utils/link-utils.ts

@@ -0,0 +1,121 @@
+import type { Router, Params } from "@real-router/core";
+
+export function shouldNavigate(evt: MouseEvent): boolean {
+  return (
+    evt.button === 0 &&
+    !evt.metaKey &&
+    !evt.altKey &&
+    !evt.ctrlKey &&
+    !evt.shiftKey
+  );
+}
+
+type BuildUrlFn = (name: string, params: Params) => string | undefined;
+
+export function buildHref(
+  router: Router,
+  routeName: string,
+  routeParams: Params,
+): string | undefined {
+  try {
+    const buildUrl = router.buildUrl as BuildUrlFn | undefined;
+
+    if (buildUrl) {
+      const url = buildUrl(routeName, routeParams);
+
+      if (url !== undefined) {
+        return url;
+      }
+    }
+
+    return router.buildPath(routeName, routeParams);
+  } catch {
+    console.error(
+      `[real-router] Route "${routeName}" is not defined. The element will render without an href attribute.`,
+    );
+
+    return undefined;
+  }
+}
+
+function parseTokens(value: string | undefined): string[] {
+  return value ? (value.match(/\S+/g) ?? []) : [];
+}
+
+export function buildActiveClassName(
+  isActive: boolean,
+  activeClassName: string | undefined,
+  baseClassName: string | undefined,
+): string | undefined {
+  if (isActive && activeClassName) {
+    const activeTokens = parseTokens(activeClassName);
+
+    if (activeTokens.length === 0) {
+      return baseClassName ?? undefined;
+    }
+    if (!baseClassName) {
+      return activeTokens.join(" ");
+    }
+
+    const baseTokens = parseTokens(baseClassName);
+    const seen = new Set(baseTokens);
+
+    for (const token of activeTokens) {
+      if (!seen.has(token)) {
+        seen.add(token);
+        baseTokens.push(token);
+      }
+    }
+
+    return baseTokens.join(" ");
+  }
+
+  return baseClassName ?? undefined;
+}
+
+export function shallowEqual(
+  prev: object | undefined,
+  next: object | undefined,
+): boolean {
+  if (Object.is(prev, next)) {
+    return true;
+  }
+  if (!prev || !next) {
+    return false;
+  }
+
+  const prevKeys = Object.keys(prev);
+
+  if (prevKeys.length !== Object.keys(next).length) {
+    return false;
+  }
+
+  const prevRecord = prev as Record<string, unknown>;
+  const nextRecord = next as Record<string, unknown>;
+
+  for (const key of prevKeys) {
+    if (!Object.is(prevRecord[key], nextRecord[key])) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+export function applyLinkA11y(element: HTMLElement | null | undefined): void {
+  if (!element) {
+    return;
+  }
+  if (
+    element instanceof HTMLAnchorElement ||
+    element instanceof HTMLButtonElement
+  ) {
+    return;
+  }
+  if (!element.hasAttribute("role")) {
+    element.setAttribute("role", "link");
+  }
+  if (!element.hasAttribute("tabindex")) {
+    element.setAttribute("tabindex", "0");
+  }
+}

package/src/dom-utils/route-announcer.ts

@@ -0,0 +1,159 @@
+import type { Router, State } from "@real-router/core";
+
+const CLEAR_DELAY = 7000;
+const SAFARI_READY_DELAY = 100;
+const ANNOUNCER_ATTR = "data-real-router-announcer";
+const INTERNAL_ROUTE_PREFIX = "@@";
+const VISUALLY_HIDDEN =
+  "position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);clip-path:inset(50%);white-space:nowrap;border:0";
+
+export interface RouteAnnouncerOptions {
+  prefix?: string;
+  getAnnouncementText?: (route: State) => string;
+}
+
+export function createRouteAnnouncer(
+  router: Router,
+  options?: RouteAnnouncerOptions,
+): { destroy: () => void } {
+  const prefix = options?.prefix ?? "Navigated to ";
+  const getCustomText = options?.getAnnouncementText;
+
+  let isInitialNavigation = true;
+  let isReady = false;
+  let isDestroyed = false;
+  let lastAnnouncedText = "";
+  let pendingText: string | null = null;
+  let clearTimeoutId: ReturnType<typeof setTimeout> | undefined;
+
+  const announcer = getOrCreateAnnouncer();
+
+  const doAnnounce = (text: string, h1: HTMLElement | null): void => {
+    lastAnnouncedText = text;
+    clearTimeout(clearTimeoutId);
+    announcer.textContent = text;
+    clearTimeoutId = setTimeout(() => {
+      announcer.textContent = "";
+      lastAnnouncedText = "";
+    }, CLEAR_DELAY);
+
+    manageFocus(h1);
+  };
+
+  // Safari-ready delay: announcing before VoiceOver wires up the aria-live region
+  // causes the first announcement to be silently dropped. Wait SAFARI_READY_DELAY ms
+  // before marking the announcer "ready" — any navigation during that window is
+  // buffered in pendingText and flushed once the delay expires.
+  const safariTimeoutId = setTimeout(() => {
+    isReady = true;
+
+    if (pendingText !== null && !isDestroyed) {
+      const text = pendingText;
+
+      pendingText = null;
+      doAnnounce(text, document.querySelector<HTMLElement>("h1"));
+    }
+  }, SAFARI_READY_DELAY);
+
+  const unsubscribe = router.subscribe(({ route }) => {
+    if (isInitialNavigation) {
+      isInitialNavigation = false;
+
+      return;
+    }
+
+    // Double rAF: waits for two paint frames so the incoming route's DOM
+    // (including the new <h1>) is fully rendered before resolveText reads it.
+    // Single rAF fires before the new route's template has been attached,
+    // which would cause resolveText to pick up the OLD h1 or fall back to
+    // document.title / route.name prematurely.
+    requestAnimationFrame(() => {
+      requestAnimationFrame(() => {
+        if (isDestroyed) {
+          return;
+        }
+
+        const h1 = document.querySelector<HTMLElement>("h1");
+        const text = resolveText(route, prefix, getCustomText, h1);
+
+        if (!text || text === lastAnnouncedText) {
+          return;
+        }
+
+        if (!isReady) {
+          // Defer announcement until Safari-ready window elapses (see safariTimeoutId).
+          pendingText = text;
+
+          return;
+        }
+
+        doAnnounce(text, h1);
+      });
+    });
+  });
+
+  return {
+    destroy() {
+      isDestroyed = true;
+      unsubscribe();
+      clearTimeout(clearTimeoutId);
+      clearTimeout(safariTimeoutId);
+      removeAnnouncer();
+    },
+  };
+}
+
+function getOrCreateAnnouncer(): HTMLElement {
+  const existing = document.querySelector<HTMLElement>(`[${ANNOUNCER_ATTR}]`);
+
+  if (existing) {
+    return existing;
+  }
+
+  const element = document.createElement("div");
+
+  element.setAttribute("style", VISUALLY_HIDDEN);
+  element.setAttribute("aria-live", "assertive");
+  element.setAttribute("aria-atomic", "true");
+  element.setAttribute(ANNOUNCER_ATTR, "");
+
+  document.body.prepend(element);
+
+  return element;
+}
+
+function removeAnnouncer(): void {
+  document.querySelector(`[${ANNOUNCER_ATTR}]`)?.remove();
+}
+
+function resolveText(
+  route: State,
+  prefix: string,
+  getCustomText: ((route: State) => string) | undefined,
+  h1: HTMLElement | null,
+): string {
+  if (getCustomText) {
+    return getCustomText(route);
+  }
+
+  const h1Text = h1?.textContent.trim() ?? "";
+  const routeName = route.name.startsWith(INTERNAL_ROUTE_PREFIX)
+    ? ""
+    : route.name;
+  const rawText =
+    h1Text || document.title || routeName || globalThis.location.pathname;
+
+  return `${prefix}${rawText}`;
+}
+
+function manageFocus(h1: HTMLElement | null): void {
+  if (!h1) {
+    return;
+  }
+
+  if (!h1.hasAttribute("tabindex")) {
+    h1.setAttribute("tabindex", "-1");
+  }
+
+  h1.focus({ preventScroll: true });
+}

package/src/functions/index.ts

@@ -0,0 +1,13 @@
+export { injectRouter } from "./injectRouter";
+
+export { injectNavigator } from "./injectNavigator";
+
+export { injectRoute } from "./injectRoute";
+
+export { injectRouteNode } from "./injectRouteNode";
+
+export { injectRouteUtils } from "./injectRouteUtils";
+
+export { injectRouterTransition } from "./injectRouterTransition";
+
+export { injectIsActiveRoute } from "./injectIsActiveRoute";

package/src/functions/injectIsActiveRoute.ts

@@ -0,0 +1,21 @@
+import { createActiveRouteSource } from "@real-router/sources";
+
+import { sourceToSignal } from "../sourceToSignal";
+import { injectRouter } from "./injectRouter";
+
+import type { Signal } from "@angular/core";
+import type { Params } from "@real-router/core";
+
+export function injectIsActiveRoute(
+  routeName: string,
+  params?: Params,
+  options?: { strict?: boolean; ignoreQueryParams?: boolean },
+): Signal<boolean> {
+  const router = injectRouter();
+  const source = createActiveRouteSource(router, routeName, params, {
+    strict: options?.strict ?? false,
+    ignoreQueryParams: options?.ignoreQueryParams ?? true,
+  });
+
+  return sourceToSignal(source);
+}

package/src/functions/injectNavigator.ts

@@ -0,0 +1,8 @@
+import { injectOrThrow } from "./injectOrThrow";
+import { NAVIGATOR } from "../providers";
+
+import type { Navigator } from "@real-router/core";
+
+export function injectNavigator(): Navigator {
+  return injectOrThrow(NAVIGATOR, "injectNavigator");
+}

package/src/functions/injectOrThrow.ts

@@ -0,0 +1,15 @@
+import { inject } from "@angular/core";
+
+import type { InjectionToken } from "@angular/core";
+
+export function injectOrThrow<T>(token: InjectionToken<T>, fnName: string): T {
+  const value = inject(token, { optional: true });
+
+  if (!value) {
+    throw new Error(
+      `${fnName} must be used within a provideRealRouter context`,
+    );
+  }
+
+  return value;
+}

package/src/functions/injectRoute.ts

@@ -0,0 +1,8 @@
+import { injectOrThrow } from "./injectOrThrow";
+import { ROUTE } from "../providers";
+
+import type { RouteSignals } from "../types";
+
+export function injectRoute(): RouteSignals {
+  return injectOrThrow(ROUTE, "injectRoute");
+}

package/src/functions/injectRouteNode.ts

@@ -0,0 +1,16 @@
+import { getNavigator } from "@real-router/core";
+import { createRouteNodeSource } from "@real-router/sources";
+
+import { sourceToSignal } from "../sourceToSignal";
+import { injectRouter } from "./injectRouter";
+
+import type { RouteSignals } from "../types";
+
+export function injectRouteNode(nodeName: string): RouteSignals {
+  const router = injectRouter();
+  const navigator = getNavigator(router);
+  const source = createRouteNodeSource(router, nodeName);
+  const routeState = sourceToSignal(source);
+
+  return { routeState, navigator };
+}

package/src/functions/injectRouteUtils.ts

@@ -0,0 +1,12 @@
+import { getPluginApi } from "@real-router/core/api";
+import { getRouteUtils } from "@real-router/route-utils";
+
+import { injectRouter } from "./injectRouter";
+
+import type { RouteUtils } from "@real-router/route-utils";
+
+export function injectRouteUtils(): RouteUtils {
+  const router = injectRouter();
+
+  return getRouteUtils(getPluginApi(router).getTree());
+}

package/src/functions/injectRouter.ts

@@ -0,0 +1,8 @@
+import { injectOrThrow } from "./injectOrThrow";
+import { ROUTER } from "../providers";
+
+import type { Router } from "@real-router/core";
+
+export function injectRouter(): Router {
+  return injectOrThrow(ROUTER, "injectRouter");
+}

package/src/functions/injectRouterTransition.ts

@@ -0,0 +1,14 @@
+import { createTransitionSource } from "@real-router/sources";
+
+import { sourceToSignal } from "../sourceToSignal";
+import { injectRouter } from "./injectRouter";
+
+import type { Signal } from "@angular/core";
+import type { RouterTransitionSnapshot } from "@real-router/sources";
+
+export function injectRouterTransition(): Signal<RouterTransitionSnapshot> {
+  const router = injectRouter();
+  const source = createTransitionSource(router);
+
+  return sourceToSignal(source);
+}

package/src/index.ts

@@ -0,0 +1,39 @@
+export { provideRealRouter, ROUTER, NAVIGATOR, ROUTE } from "./providers";
+
+export { sourceToSignal } from "./sourceToSignal";
+
+export {
+  injectRouter,
+  injectNavigator,
+  injectRoute,
+  injectRouteNode,
+  injectRouteUtils,
+  injectRouterTransition,
+  injectIsActiveRoute,
+} from "./functions";
+
+export { RouteView } from "./components/RouteView";
+
+export { RouterErrorBoundary } from "./components/RouterErrorBoundary";
+
+export type { ErrorContext } from "./components/RouterErrorBoundary";
+
+export { NavigationAnnouncer } from "./components/NavigationAnnouncer";
+
+export { RouteMatch } from "./directives/RouteMatch";
+
+export { RouteNotFound } from "./directives/RouteNotFound";
+
+export { RealLink } from "./directives/RealLink";
+
+export { RealLinkActive } from "./directives/RealLinkActive";
+
+export type { RouteSignals } from "./types";
+
+export type {
+  RouteSnapshot,
+  RouterTransitionSnapshot,
+  RouterErrorSnapshot,
+} from "@real-router/sources";
+
+export type { Navigator } from "@real-router/core";

package/src/providers.ts

@@ -0,0 +1,33 @@
+import {
+  InjectionToken,
+  makeEnvironmentProviders,
+  type EnvironmentProviders,
+} from "@angular/core";
+import { getNavigator, type Router, type Navigator } from "@real-router/core";
+import { createRouteSource } from "@real-router/sources";
+
+import { sourceToSignal } from "./sourceToSignal";
+
+import type { RouteSignals } from "./types";
+
+export const ROUTER = new InjectionToken<Router>("ROUTER");
+
+export const NAVIGATOR = new InjectionToken<Navigator>("NAVIGATOR");
+
+export const ROUTE = new InjectionToken<RouteSignals>("ROUTE");
+
+export function provideRealRouter(router: Router): EnvironmentProviders {
+  const navigator = getNavigator(router);
+
+  return makeEnvironmentProviders([
+    { provide: ROUTER, useValue: router },
+    { provide: NAVIGATOR, useValue: navigator },
+    {
+      provide: ROUTE,
+      useFactory: (): RouteSignals => ({
+        routeState: sourceToSignal(createRouteSource(router)),
+        navigator,
+      }),
+    },
+  ]);
+}

package/src/sourceToSignal.ts

@@ -0,0 +1,20 @@
+import { signal, type Signal, inject, DestroyRef } from "@angular/core";
+
+import type { RouterSource } from "@real-router/sources";
+
+/** Must be called within an injection context (constructor, field initializer, runInInjectionContext). */
+export function sourceToSignal<T>(source: RouterSource<T>): Signal<T> {
+  const sig = signal<T>(source.getSnapshot());
+  const destroyRef = inject(DestroyRef);
+
+  const unsubscribe = source.subscribe(() => {
+    sig.set(source.getSnapshot());
+  });
+
+  destroyRef.onDestroy(() => {
+    unsubscribe();
+    source.destroy();
+  });
+
+  return sig.asReadonly();
+}