@real-router/angular 0.11.0 → 0.11.2

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

@@ -1,339 +0,0 @@
-import type {
-  NavigationOptions,
-  Params,
-  Router,
-  State,
-} from "@real-router/core";
-
-export function shouldNavigate(evt: MouseEvent): boolean {
-  return (
-    evt.button === 0 &&
-    !evt.metaKey &&
-    !evt.altKey &&
-    !evt.ctrlKey &&
-    !evt.shiftKey
-  );
-}
-
-// Matches a single percent-escape triple (`%` + two hex digits). Used as
-// the "already-encoded" probe in `encodeFragmentInline` below — see the
-// idempotency rationale there.
-const PERCENT_ESCAPE_PROBE = /%[\dA-Fa-f]{2}/;
-
-/**
- * RFC 3986 fragment encoding: preserve sub-delims (`&`, `=`, `?`, `:`),
- * encode space, `%`, control chars, non-ASCII via encodeURI; defensively
- * escape `#` (encodeURI does not). Mirrors `encodeHashFragment` in
- * `shared/browser-env/url-context.ts` — duplicated here because the
- * shared/dom-utils symlink graph does not reach shared/browser-env.
- *
- * **Idempotency for pre-encoded input (audit-2026-05-17 §5 MEDIUM E.1).**
- * The doc-comment on `<Link hash>` says the value is a "decoded fragment
- * without leading #". But realistic consumers copy hashes out of
- * `location.hash` (which is percent-encoded) and pass them back, so the
- * naive `encodeURI("%20")` would double-encode into `"%2520"` and break
- * anchor lookup. We detect a percent-escape triple in the input and, if
- * present, decode + re-encode for idempotency. Malformed `%XX` (e.g.
- * `"%2"` or `"%ZZ"`) makes `decodeURIComponent` throw — in that case we
- * fall through to plain `encodeURI`, which never throws.
- */
-function encodeFragmentInline(decoded: string): string {
-  if (PERCENT_ESCAPE_PROBE.test(decoded)) {
-    try {
-      const roundtrip = decodeURIComponent(decoded);
-
-      return encodeURI(roundtrip).replaceAll("#", "%23");
-    } catch {
-      // Malformed `%XX` — fall through to the plain encoding path.
-      // encodeURI does not throw on malformed escapes; it treats the
-      // `%` as a literal and percent-encodes it (`%2` → `%252`).
-    }
-  }
-
-  return encodeURI(decoded).replaceAll("#", "%23");
-}
-
-type BuildUrlFn = (
-  name: string,
-  params: Params,
-  options?: { hash?: string },
-) => string | undefined;
-
-/**
- * Builds an href for a `<Link>` element.
- *
- * - Prefers the URL plugin's `buildUrl` (browser-plugin, navigation-plugin,
- *   hash-plugin) when present.
- * - Falls back to `router.buildPath` for runtimes without a URL plugin
- *   (memory-plugin, console UIs, NativeScript). In that fallback the hash
- *   is appended manually so the rendered href is still correct.
- * - The optional 4th argument is an options object so the contract stays
- *   extensible. The `hash` option is a decoded fragment without leading "#";
- *   `<Link hash="#section">` is accepted defensively (leading "#" stripped).
- *   Frozen API: previous 3-arg call sites continue to work unchanged.
- */
-export function buildHref(
-  router: Router,
-  routeName: string,
-  routeParams: Params,
-  options?: { hash?: string },
-): string | undefined {
-  try {
-    const rawHash = options?.hash;
-    let normHash: string | undefined;
-
-    if (rawHash !== undefined) {
-      normHash = rawHash.startsWith("#") ? rawHash.slice(1) : rawHash;
-    }
-
-    const buildUrl = router.buildUrl as BuildUrlFn | undefined;
-
-    if (buildUrl) {
-      const url = buildUrl(
-        routeName,
-        routeParams,
-        normHash === undefined ? undefined : { hash: normHash },
-      );
-
-      // Accept only non-empty strings. The BuildUrlFn type contract is
-      // `string | undefined`, but defensive against:
-      //   - `""` (empty string) → would render `<a href="">`, which resolves
-      //     to the current page URL → silent self-navigation on click.
-      //   - `null` (type-contract violation) → would render `<a href={null}>`,
-      //     stringified to `"null"` in some renderers.
-      // Either case falls through to the `router.buildPath` fallback below.
-      if (typeof url === "string" && url.length > 0) {
-        return url;
-      }
-    }
-
-    const path = router.buildPath(routeName, routeParams);
-
-    // Symmetric to the buildUrl guard above (#S1 audit, Invariant 12).
-    // `router.buildPath` is typed `string`, but defends against:
-    //   - `""` (empty string) — would render `<a href="">`, which resolves
-    //     to the current page URL → silent self-navigation on click.
-    //   - non-string type-contract violations from custom path-matchers.
-    // Both yield `undefined` (renderer drops the attribute) with a warning.
-    if (typeof path !== "string" || path.length === 0) {
-      console.error(
-        `[real-router] Route "${routeName}" yielded an empty path. The element will render without an href attribute.`,
-      );
-
-      return undefined;
-    }
-
-    return normHash ? `${path}#${encodeFragmentInline(normHash)}` : path;
-  } catch {
-    console.error(
-      `[real-router] Route "${routeName}" is not defined. The element will render without an href attribute.`,
-    );
-
-    return undefined;
-  }
-}
-
-/**
- * `<Link>` click-handler navigation helper (#532).
- *
- * Wraps `router.navigate(name, params, opts)` with same-route different-hash
- * detection: when the consumer clicks a hash-bearing Link that targets the
- * current route with the same params but a different fragment, core's
- * SAME_STATES check would otherwise reject the navigation. The helper adds
- * `force: true` and `hashChange: true` automatically — subscribers can then
- * disambiguate via `state.context.url.hashChanged`.
- *
- * For pure programmatic same-route hash-only navigation, callers are
- * documented to pass `{ force: true }` themselves; the auto-bypass here is
- * a UX convenience for `<Link hash>` that all 6 framework adapters share.
- */
-/**
- * Local extended-options type. Adapters that depend only on `@real-router/core`
- * (without a URL plugin) do not see the `NavigationOptions` augmentation that
- * declares `hash` / `hashChange`. Casting to this widened type inside the
- * helper keeps shared/dom-utils self-contained — adapters do not need to
- * augment NavigationOptions themselves to consume `<Link hash>`.
- */
-type HashAwareNavigationOptions = NavigationOptions & {
-  hash?: string;
-  hashChange?: boolean;
-};
-
-export function navigateWithHash(
-  router: Router,
-  routeName: string,
-  routeParams: Params,
-  hash: string | undefined,
-  extraOptions?: NavigationOptions,
-): Promise<State> {
-  const opts: HashAwareNavigationOptions = { ...extraOptions };
-
-  if (hash !== undefined) {
-    opts.hash = hash;
-  }
-
-  const current = router.getState();
-
-  if (
-    current?.name === routeName &&
-    shallowEqual(current.params, routeParams)
-  ) {
-    const currentHash =
-      (current.context as { url?: { hash?: string } } | undefined)?.url?.hash ??
-      "";
-    const newHash = hash ?? currentHash;
-
-    if (currentHash !== newHash) {
-      opts.force = true;
-      opts.hashChange = true;
-    }
-  }
-
-  return router.navigate(routeName, routeParams, opts);
-}
-
-// Match-any-whitespace regex shared across calls. RegExp literals at
-// call-site recompile in some engines; lifting it avoids that microcost
-// for the slow-path branch.
-const WHITESPACE_PROBE = /\s/;
-const WHITESPACE_SPLIT = /\S+/g;
-
-function parseTokens(value: string | undefined): string[] {
-  if (!value) {
-    return [];
-  }
-
-  // Hot-path fast-path (audit-2026-05-17 §8b #1): >99% of active-class
-  // inputs at `<Link>` emit are single-token strings like `"active"` or
-  // `"is-current"` — no whitespace, no leading/trailing pad. Skip the
-  // regex match and Array result allocation: a literal `[value]` works
-  // because the slow-path `match(/\S+/g)` would return exactly `[value]`
-  // for the same input. PBT lock: linkUtils.properties.ts Invariant 13.
-  if (!WHITESPACE_PROBE.test(value)) {
-    return [value];
-  }
-
-  return value.match(WHITESPACE_SPLIT) ?? [];
-}
-
-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;
-}
-
-/**
- * One-level structural equality using `Object.is` per key.
- *
- * **String-keyed properties only (Mini-sprint E.3 — audit-5 §4.2 #3).**
- * Implementation walks `Object.keys()` which by spec returns only
- * enumerable own STRING keys. Symbol-keyed properties — created via
- * `obj[Symbol("brand")] = value` or `{ [Symbol(...)]: value }` — are
- * NOT compared. Two records that differ only in a Symbol-keyed value
- * will compare as equal.
- *
- * This is intentional: route params and Link options are documented as
- * string-keyed primitives (string | number | boolean) — Symbol-keyed
- * metadata (e.g. brand markers, private state) doesn't belong in a
- * cache-key comparison. Switching to `Reflect.ownKeys()` would extend
- * the contract to symbols at the cost of one extra allocation per call
- * (Reflect.ownKeys composes string-keys + symbol-keys arrays). If a
- * consumer relies on symbol-keyed metadata for navigation
- * disambiguation, they should encode it into a string key instead.
- *
- * Mirrors React's `shallowEqual` (packages/shared/shallowEqual.js) in
- * both the string-keys-only semantics and the `hasOwnProperty` guard
- * below.
- */
-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) {
-    // hasOwnProperty guard: without it, a key missing in `next` reads as
-    // `undefined` and falsely matches `prev[key] === undefined`. Same shape
-    // as React's shallowEqual (packages/shared/shallowEqual.js).
-    if (
-      !Object.prototype.hasOwnProperty.call(next, key) ||
-      !Object.is(prevRecord[key], nextRecord[key])
-    ) {
-      return false;
-    }
-  }
-
-  return true;
-}
-
-export function applyLinkA11y(element: HTMLElement | null | undefined): void {
-  if (!element) {
-    return;
-  }
-
-  // Cross-realm safety (audit-2026-05-17 §5 HIGH #4):
-  // `instanceof HTMLAnchorElement` compares against the constructor from
-  // the CURRENT realm. An element created in a different window (iframe
-  // contentDocument, micro-frontend, embedded widget) fails the check
-  // even when it IS a real anchor — the helper would then inject
-  // role="link" + tabindex="0" on top of native anchor semantics,
-  // breaking screen reader output ("link link") and focus order.
-  //
-  // tagName is realm-agnostic and is uppercase for HTML-namespaced
-  // elements in any document. SVG `<a>` has lowercase tagName plus a
-  // different prototype (SVGAElement) — skipping it here is wrong by
-  // accident: SVG anchors don't have keyboard activation semantics the
-  // helper would add. But they also don't reach this helper in
-  // practice (router Link components emit HTML anchors). Lock the
-  // uppercase compare to keep the contract narrow.
-  const tag = element.tagName;
-
-  if (tag === "A" || tag === "BUTTON") {
-    return;
-  }
-  if (!element.hasAttribute("role")) {
-    element.setAttribute("role", "link");
-  }
-  if (!element.hasAttribute("tabindex")) {
-    element.setAttribute("tabindex", "0");
-  }
-}

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

@@ -1,215 +0,0 @@
-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;
-}
-
-const NOOP_INSTANCE: { destroy: () => void } = Object.freeze({
-  destroy: () => {
-    /* no-op */
-  },
-});
-
-export function createRouteAnnouncer(
-  router: Router,
-  options?: RouteAnnouncerOptions,
-): { destroy: () => void } {
-  // Defensive SSR / non-browser guard: in SSR (Node.js) or non-DOM
-  // environments, `document` is undefined and the announcer cannot
-  // attach its aria-live region. Return a frozen NOOP_INSTANCE — same
-  // pattern as `createDirectionTracker`, `createScrollRestoration`, and
-  // `createViewTransitions`. Without this guard, `NavigationAnnouncer`
-  // component construction would throw `ReferenceError: document is not
-  // defined` under `@angular/ssr` rendering, tearing down the whole SSR
-  // bootstrap. Closes review-2026-05-10 §5.10 ⛔ "NavigationAnnouncer
-  // SSR mode" MED.
-  if (typeof document === "undefined") {
-    return NOOP_INSTANCE;
-  }
-
-  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, "");
-
-  // Defensive SSR / pre-`<body>` guard: in some environments (early
-  // injection, deferred-body documents, certain SSR rehydration paths)
-  // `document.body` can be null when the announcer is constructed.
-  // `document.body.prepend(...)` would throw `TypeError: Cannot read
-  // properties of null`, tearing down the consumer's RouterProvider /
-  // NavigationAnnouncer mount. Fallback to `documentElement` keeps the
-  // announcer working for SR users; visual-hidden styling means there is
-  // no visible artifact regardless of mount point.
-  //
-  // TS dom lib types `document.body` as `HTMLElement` (non-null), but
-  // runtime can return null per spec. The `as` cast narrows the type to
-  // include null so the `??` short-circuit is type-safe.
-  ((document.body as HTMLElement | null) ?? document.documentElement).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) {
-    try {
-      const customText = getCustomText(route);
-
-      // Mini-sprint E.4 (audit-5 §4.2 #4) — empty-string fallback.
-      // A consumer pattern like
-      //   getAnnouncementText: (route) => myMap[route.name] ?? ""
-      // returns `""` for routes outside the map. The subscribe loop
-      // then sees an empty text and silently no-announces — screen
-      // readers stay quiet without any signal to the developer. Treat
-      // a falsy custom result (`""` / `null` / `undefined`) as
-      // "consumer doesn't have a name for this route" and fall through
-      // to the default resolution chain (h1 → title → route name).
-      if (customText) {
-        return customText;
-      }
-    } catch (error) {
-      // A throwing consumer callback inside the router's subscribe loop
-      // would tear down sibling listeners — log and fall through to the
-      // built-in resolution chain so the announcer keeps working.
-      console.error(
-        "[real-router] getAnnouncementText threw; falling back to default resolution.",
-        error,
-      );
-    }
-  }
-
-  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 });
-}