compact-router 0.0.0-stage → 0.1.0

package/src/Route.ts

@@ -0,0 +1,295 @@
+import { QuasiURL } from "quasiurl";
+import type { LinkElement } from "./types/LinkElement.ts";
+import type { LocationPattern } from "./types/LocationPattern.ts";
+import type { LocationValue } from "./types/LocationValue.ts";
+import type { MatchHandler } from "./types/MatchHandler.ts";
+import type { NavigationOptions } from "./types/NavigationOptions.ts";
+import type { URLData } from "./types/URLData.ts";
+import {
+  URLState,
+  type URLStateOptions,
+  type URLStatePayloadMap,
+} from "./URLState.ts";
+import { compileURL } from "./utils/compileURL.ts";
+import { getNavigationOptions } from "./utils/getNavigationOptions.ts";
+import { isRouteEvent } from "./utils/isRouteEvent.ts";
+import { matchURL } from "./utils/matchURL.ts";
+
+export type ContainerElement = Document | Element | null | undefined;
+export type ElementCollection = (string | Node)[] | HTMLCollection | NodeList;
+
+export type ObservedElement =
+  | string
+  | Node
+  | (string | Node)[]
+  | HTMLCollection
+  | NodeList;
+
+function isElementCollection(x: unknown): x is ElementCollection {
+  return (
+    Array.isArray(x) || x instanceof NodeList || x instanceof HTMLCollection
+  );
+}
+
+function isLinkElement(x: unknown): x is LinkElement {
+  return x instanceof HTMLAnchorElement || x instanceof HTMLAreaElement;
+}
+
+function toggleActive(element: Element | Node, route: Route) {
+  if (!isLinkElement(element)) return;
+
+  if (
+    element.hasAttribute("href") &&
+    route.match(route.toValue(element.href)).ok
+  )
+    element.dataset.active = "true";
+  else delete element.dataset.active;
+}
+
+export type RoutePayloadMap = URLStatePayloadMap & {
+  documentclick: MouseEvent;
+};
+
+export type RouteOptions = URLStateOptions;
+
+export class Route extends URLState<RoutePayloadMap> {
+  _observeInited = false;
+  constructor(href: LocationValue | null = null, options?: RouteOptions) {
+    super(String(href ?? ""), options);
+  }
+  /**
+   * Enables SPA navigation with HTML links inside the specified container.
+   *
+   * @example
+   * ```js
+   * let route = new Route();
+   * route.observe(document);
+   * ```
+   */
+  observe(
+    container: ContainerElement | (() => ContainerElement),
+    elements: ObservedElement = "a, area",
+  ) {
+    if (typeof window === "undefined") return;
+
+    if (!this._observeInited) {
+      let handleClick = (event: MouseEvent) => {
+        this.emit("documentclick", event);
+      };
+
+      this.on("start", () => {
+        document.addEventListener("click", handleClick);
+      });
+
+      this.on("stop", () => {
+        document.removeEventListener("click", handleClick);
+      });
+
+      if (this.active) document.addEventListener("click", handleClick);
+
+      this._observeInited = true;
+    }
+
+    let resolveParams = () => {
+      let resolvedContainer =
+        typeof container === "function" ? container() : container;
+
+      if (!resolvedContainer) return;
+
+      let targetElements = isElementCollection(elements)
+        ? Array.from(elements)
+        : [elements];
+
+      return { resolvedContainer, targetElements };
+    };
+
+    let removeClickHandlers = this.on("documentclick", (event: MouseEvent) => {
+      if (event.defaultPrevented || !isRouteEvent(event)) return;
+
+      let resolvedParams = resolveParams();
+
+      if (!resolvedParams) return;
+
+      let { resolvedContainer, targetElements } = resolvedParams;
+      let element: HTMLAnchorElement | HTMLAreaElement | null = null;
+
+      for (let targetElement of targetElements) {
+        let target: Node | null = null;
+
+        if (typeof targetElement === "string")
+          target =
+            event.target instanceof HTMLElement
+              ? event.target.closest(targetElement)
+              : null;
+        else target = targetElement;
+
+        if (isLinkElement(target) && resolvedContainer.contains(target)) {
+          element = target;
+          break;
+        }
+      }
+
+      if (element) {
+        event.preventDefault();
+        this.navigate(getNavigationOptions(element));
+      }
+    });
+
+    let removeURLChangeHandlers = this.on("ready", () => {
+      let resolvedParams = resolveParams();
+
+      if (!resolvedParams) return;
+
+      let { resolvedContainer, targetElements } = resolvedParams;
+
+      for (let targetElement of targetElements) {
+        if (typeof targetElement === "string") {
+          let targets = resolvedContainer.querySelectorAll(targetElement);
+
+          for (let element of targets) toggleActive(element, this);
+        } else if (resolvedContainer.contains(targetElement))
+          toggleActive(targetElement, this);
+      }
+    });
+
+    return () => {
+      removeClickHandlers();
+      removeURLChangeHandlers();
+    };
+  }
+  /**
+   * Navigates to the URL specified with `options.href`.
+   *
+   * @example
+   * ```js
+   * let route = new Route();
+   * route.navigate({ href: "/intro", history: "replace", scroll: "off" });
+   * ```
+   */
+  navigate(options?: NavigationOptions<LocationValue>): void {
+    if (!options?.href) return;
+
+    let { href, referrer, ...params } = options;
+
+    // Stringify `LocationValue` URLs in `options`
+    let transformedOptions = {
+      href: String(href),
+      referrer: referrer && String(referrer),
+      ...params,
+    };
+
+    this.setValue(transformedOptions.href, transformedOptions);
+  }
+  assign(url: LocationValue) {
+    this.navigate({ href: url });
+  }
+  replace(url: LocationValue) {
+    this.navigate({ href: url, history: "replace" });
+  }
+  reload() {
+    this.assign(this.getValue());
+  }
+  go(delta: number) {
+    if (typeof window !== "undefined" && window.history)
+      window.history.go(delta);
+  }
+  back() {
+    this.go(-1);
+  }
+  forward() {
+    this.go(1);
+  }
+  get href(): string {
+    return this.getValue();
+  }
+  set href(value: LocationValue) {
+    this.assign(value);
+  }
+  get pathname(): string {
+    return new QuasiURL(this.href).pathname;
+  }
+  set pathname(value: LocationValue) {
+    let url = new QuasiURL(this.href);
+    url.pathname = String(value);
+    this.assign(url.href);
+  }
+  get search(): string {
+    return new QuasiURL(this.href).search;
+  }
+  set search(value: string | URLSearchParams) {
+    let url = new QuasiURL(this.href);
+    url.search = value;
+    this.assign(url.href);
+  }
+  get hash() {
+    return new QuasiURL(this.href).hash;
+  }
+  set hash(value: string) {
+    let url = new QuasiURL(this.href);
+    url.hash = value;
+    this.assign(url.href);
+  }
+  toString() {
+    return this.href;
+  }
+  /**
+   * Matches the current location against `urlPattern`.
+   */
+  match<P extends LocationPattern>(urlPattern: P) {
+    return matchURL<P>(urlPattern, this.href);
+  }
+  /**
+   * Compiles `urlPattern` to a URL string by filling out the parameters
+   * based on `data`.
+   */
+  compile<T extends LocationValue>(urlPattern: T, data?: URLData<T>) {
+    return compileURL<T>(urlPattern, data);
+  }
+  /**
+   * `at(urlPattern)` returns `true` if `urlPattern` matches the current URL,
+   * and `false` otherwise.
+   *
+   * `at(urlPattern, x, y?)` returns either based on `x` if `urlPattern`
+   * matches the current URL, or based on `y` otherwise. (It loosely resembles
+   * the ternary conditional operator `matchesURLPattern ? x : y`.)
+   *
+   * If the current location matches `urlPattern`, `at(urlPattern, x, y)`
+   * returns:
+   * - `x`, if `x` is not a function;
+   * - `x({ params })`, if `x` is a function, with `params` extracted from
+   * the current URL.
+   *
+   * If the current location doesn't match `urlPattern`, `at(urlPattern, x, y)`
+   * returns:
+   * - `y`, if `y` is not a function;
+   * - `y({ params })`, if `y` is a function, with `params` extracted from
+   * the current URL.
+   */
+  at<P extends LocationPattern>(urlPattern: P): boolean;
+
+  at<P extends LocationPattern, X>(
+    urlPattern: P,
+    x: X | MatchHandler<P, X>,
+  ): X | undefined;
+
+  at<P extends LocationPattern, X, Y>(
+    urlPattern: P,
+    x: X | MatchHandler<P, X>,
+    y: Y | MatchHandler<P, Y>,
+  ): X | Y;
+
+  at<P extends LocationPattern, X, Y>(
+    urlPattern: P,
+    x?: X | MatchHandler<P, X>,
+    y?: Y | MatchHandler<P, Y>,
+  ): X | Y | boolean | undefined {
+    let result = this.match<P>(urlPattern);
+
+    if (x === undefined && y === undefined) return result.ok;
+
+    if (!result.ok)
+      return typeof y === "function" ? (y as MatchHandler<P, Y>)(result) : y;
+
+    return typeof x === "function" ? (x as MatchHandler<P, X>)(result) : x;
+  }
+}

package/src/URLState.ts

@@ -0,0 +1,161 @@
+import {
+  type EventCallback,
+  State,
+  type StateOptions,
+  type StatePayloadMap,
+  type StateUpdate,
+} from "compact-state";
+import { QuasiURL } from "quasiurl";
+import type { NavigationOptions } from "./types/NavigationOptions.ts";
+
+export type URLStatePayloadMap = StatePayloadMap<string> & {
+  navigationstart: NavigationOptions;
+  // Similar to the "update" event, but with a `NavigationOptions` payload
+  navigation: NavigationOptions;
+  navigationcomplete: NavigationOptions;
+  ready: void;
+};
+
+function isImmediatelyInvokedNavigationEvent(
+  event: unknown,
+): event is "navigationstart" | "navigationcomplete" {
+  return event === "navigationstart" || event === "navigationcomplete";
+}
+
+function isImmediatelyInvokedEvent(event: unknown): event is "ready" {
+  return event === "ready";
+}
+
+export type URLStateOptions = StateOptions;
+
+export class URLState<
+  P extends URLStatePayloadMap = URLStatePayloadMap,
+> extends State<string, P> {
+  constructor(href: string | null = null, options?: URLStateOptions) {
+    super(href ?? "", options);
+  }
+  _init() {
+    super._init();
+
+    if (typeof window === "undefined") return;
+
+    let handleURLChange = () => {
+      this.setValue(window.location.href, { source: "popstate" });
+    };
+
+    this.on("start", () => {
+      window.addEventListener("popstate", handleURLChange);
+      this.emit("ready");
+    });
+
+    this.on("stop", () => {
+      window.removeEventListener("popstate", handleURLChange);
+    });
+  }
+  on<E extends string>(
+    event: E,
+    callback: EventCallback<P[E]>,
+    invokeImmediately?: boolean,
+  ) {
+    if (invokeImmediately !== false) {
+      if (isImmediatelyInvokedNavigationEvent(event))
+        this._call(() => {
+          callback({ href: this.getValue() } as P[typeof event]);
+        });
+      else if (isImmediatelyInvokedEvent(event))
+        this._call(() => {
+          (callback as EventCallback<void>)();
+        });
+    }
+
+    return super.on(event, callback);
+  }
+  getValue() {
+    return this.toValue(this._value);
+  }
+  setValue(update: string | StateUpdate<string>, options?: NavigationOptions) {
+    if (!this._active) return;
+
+    let href = this.toValue(this._resolveValue(update));
+
+    let extendedOptions: NavigationOptions = {
+      ...options,
+      href,
+      referrer: this.getValue(),
+    };
+
+    if (
+      this.emit("navigationstart", extendedOptions) &&
+      this._transition(extendedOptions) !== false
+    ) {
+      this._assignValue(href);
+      this.emit("navigation", extendedOptions);
+
+      if (this.emit("navigationcomplete", extendedOptions)) {
+        this._complete(extendedOptions);
+        this.emit("ready");
+      }
+    }
+  }
+  _transition(options?: NavigationOptions): boolean | void | undefined {
+    if (
+      typeof window === "undefined" ||
+      options?.href === undefined ||
+      options?.source === "popstate"
+    )
+      return;
+
+    let { href, target, spa, history } = options;
+
+    if (target && target !== "_self") {
+      window.open(href, target);
+      return false;
+    }
+
+    let url = new QuasiURL(href);
+
+    if (
+      spa === "off" ||
+      !window.history ||
+      (url.origin !== "" && url.origin !== window.location.origin)
+    ) {
+      window.location[history === "replace" ? "replace" : "assign"](href);
+      return false;
+    }
+
+    window.history[history === "replace" ? "replaceState" : "pushState"](
+      {},
+      "",
+      href,
+    );
+  }
+  _complete(options?: NavigationOptions): boolean | void | undefined {
+    if (typeof window === "undefined" || !options || options.scroll === "off")
+      return;
+
+    let { href, target } = options;
+
+    if (href === undefined || (target && target !== "_self")) return;
+
+    let { hash } = new QuasiURL(href);
+
+    requestAnimationFrame(() => {
+      let targetElement =
+        hash === ""
+          ? null
+          : document.querySelector(`${hash}, a[name="${hash.slice(1)}"]`);
+
+      if (targetElement) targetElement.scrollIntoView();
+      else window.scrollTo(0, 0);
+    });
+  }
+  toValue(x: string) {
+    if (typeof window === "undefined") return x;
+
+    let url = new QuasiURL(x || window.location.href);
+
+    if (url.origin === window.location.origin) url.origin = "";
+
+    return url.href;
+  }
+}

package/src/types/LinkElement.ts

@@ -0,0 +1 @@
+export type LinkElement = HTMLAnchorElement | HTMLAreaElement;

package/src/types/LocationObject.ts

@@ -0,0 +1,11 @@
+import type { URLComponents } from "./URLComponents.ts";
+import type { URLSchema } from "./URLSchema.ts";
+
+// URL builder output
+export type LocationObject = {
+  _schema: URLSchema | undefined;
+  exec: (x: string) => URLComponents | null;
+  // biome-ignore lint/suspicious/noExplicitAny: third-party
+  compile: (x: any) => string;
+  toString: () => string;
+};

package/src/types/LocationPattern.ts

@@ -0,0 +1,6 @@
+import type { LocationValue } from "./LocationValue.ts";
+import type { URLConfig } from "./URLConfig.ts";
+
+export type LocationPattern = URLConfig["strict"] extends true
+  ? LocationValue | LocationValue[]
+  : LocationValue | RegExp | (LocationValue | RegExp)[];

package/src/types/LocationValue.ts

@@ -0,0 +1,6 @@
+import type { LocationObject } from "./LocationObject.ts";
+import type { URLConfig } from "./URLConfig.ts";
+
+export type LocationValue = URLConfig["strict"] extends true
+  ? LocationObject | undefined
+  : string | LocationObject | undefined;

package/src/types/MatchHandler.ts

@@ -0,0 +1,6 @@
+import type { LocationPattern } from "./LocationPattern.ts";
+import type { MatchState } from "./MatchState.ts";
+
+export type MatchHandler<P extends LocationPattern, T> = (
+  payload: MatchState<P>,
+) => T;

package/src/types/MatchState.ts

@@ -0,0 +1,22 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { LocationPattern } from "../types/LocationPattern.ts";
+import type { URLSchema } from "../types/URLSchema.ts";
+
+export type MatchState<P extends LocationPattern> = {
+  ok: boolean;
+  href: string;
+  params: P extends { _schema: URLSchema }
+    ? StandardSchemaV1.InferOutput<P["_schema"]> extends {
+        params?: Record<string, unknown>;
+      }
+      ? StandardSchemaV1.InferOutput<P["_schema"]>["params"]
+      : Record<string, never>
+    : Record<string, string | undefined>;
+  query: P extends { _schema: URLSchema }
+    ? StandardSchemaV1.InferOutput<P["_schema"]> extends {
+        query?: Record<string, unknown>;
+      }
+      ? StandardSchemaV1.InferOutput<P["_schema"]>["query"]
+      : Record<string, never>
+    : Record<string, string | undefined>;
+};

package/src/types/NavigationOptions.ts

@@ -0,0 +1,10 @@
+export type NavigationOptions<Href = string> = {
+  target?: string;
+  href?: Href;
+  referrer?: Href;
+  spa?: "auto" | "off" | undefined;
+  history?: "push" | "replace" | undefined;
+  scroll?: "auto" | "off" | undefined;
+  id?: string;
+  source?: "popstate" | undefined;
+};

package/src/types/URLComponents.ts

@@ -0,0 +1,4 @@
+export type URLComponents = {
+  params?: Record<string, unknown> | undefined;
+  query?: Record<string, unknown> | undefined;
+};

package/src/types/URLConfig.ts

@@ -0,0 +1,5 @@
+type URLConfigShape = {
+  strict?: boolean;
+};
+
+export interface URLConfig extends URLConfigShape {}

package/src/types/URLData.ts

@@ -0,0 +1,10 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { LocationValue } from "./LocationValue.ts";
+import type { URLComponents } from "./URLComponents.ts";
+import type { URLSchema } from "./URLSchema.ts";
+
+export type URLData<T extends LocationValue = LocationValue> = T extends {
+  _schema: URLSchema;
+}
+  ? StandardSchemaV1.InferOutput<T["_schema"]>
+  : URLComponents;

package/src/types/URLSchema.ts

@@ -0,0 +1,4 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { URLComponents } from "./URLComponents.ts";
+
+export type URLSchema = StandardSchemaV1<URLComponents>;

package/src/utils/compileURL.ts

@@ -0,0 +1,27 @@
+import { QuasiURL } from "quasiurl";
+import type { LocationValue } from "../types/LocationValue.ts";
+import type { URLData } from "../types/URLData.ts";
+import { isLocationObject } from "./isLocationObject.ts";
+
+export function compileURL<T extends LocationValue>(
+  urlPattern: T,
+  data?: URLData<T>,
+) {
+  if (isLocationObject(urlPattern)) return urlPattern.compile(data);
+
+  let url = new QuasiURL(urlPattern ?? "");
+  let query = data?.query;
+
+  if (query) {
+    url.search = new URLSearchParams(
+      // Remove null und undefined values, stringify nonstring values
+      Object.entries(query).reduce<Record<string, string>>((p, [k, v]) => {
+        if (v !== null && v !== undefined)
+          p[k] = typeof v === "string" ? v : JSON.stringify(v);
+        return p;
+      }, {}),
+    );
+  }
+
+  return url.href;
+}

package/src/utils/getNavigationOptions.ts

@@ -0,0 +1,15 @@
+import type { LinkElement } from "../types/LinkElement.ts";
+import type { NavigationOptions } from "../types/NavigationOptions.ts";
+
+export function getNavigationOptions(element: LinkElement) {
+  let { id, spa, history, scroll } = element.dataset;
+
+  return {
+    href: element.getAttribute("href"),
+    target: element.getAttribute("target"),
+    spa,
+    history,
+    scroll,
+    id,
+  } as NavigationOptions;
+}

package/src/utils/isLocationObject.ts

@@ -0,0 +1,11 @@
+import type { LocationObject } from "../types/LocationObject.ts";
+
+export function isLocationObject(x: unknown): x is LocationObject {
+  return (
+    x !== null &&
+    typeof x === "object" &&
+    "exec" in x &&
+    "compile" in x &&
+    "_schema" in x
+  );
+}

package/src/utils/isRouteEvent.ts

@@ -0,0 +1,11 @@
+export function isRouteEvent(event: unknown) {
+  return (
+    event !== null &&
+    typeof event === "object" &&
+    (!("button" in event) || event.button === 0) &&
+    (!("ctrlKey" in event) || !event.ctrlKey) &&
+    (!("shiftKey" in event) || !event.shiftKey) &&
+    (!("altKey" in event) || !event.altKey) &&
+    (!("metaKey" in event) || !event.metaKey)
+  );
+}