compact-router 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Alexander Tkačenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,121 @@
-# Temporary Holding Version
+# compact-router
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Vanilla TS/JS routing
+
+Contents: [Route](#route) · [Annotated live demos](#annotated-live-demos)
+
+## `Route`
+
+`Route` stores the URL and exposes a `window.location`-like API for SPA navigation with a URL matching API.
+
+```js
+import { Route } from "compact-router";
+
+const route = new Route();
+```
+
+Navigate to other URLs in a SPA fashion similarly to the browser APIs:
+
+```js
+route.href = "/intro";
+route.assign("/intro");
+route.replace("/intro");
+```
+
+Or in a more fine-grained manner:
+
+```js
+route.navigate({ href: "/intro", history: "replace", scroll: "off" });
+```
+
+Check the current URL value like a regular `string` with `route.href`:
+
+```js
+route.href === "/intro";
+route.href.startsWith("/sections/");
+/^\/sections\/\d+\/?/.test(route.href);
+```
+
+Or, alternatively, with `route.at(url)` returning `true` if the current URL matches `url`, and `false` otherwise:
+
+```js
+route.at("/intro"); // `true` at "/intro", `false` otherwise
+route.at(/^\/sections\//); // `true` at "/sections/*"
+```
+
+Or with the extended form `route.at(url, x, y?)`, which is similar to the ternary conditional operator `atURL ? x : y`:
+
+```js
+document.querySelector("header").className = route.at("/", "full", "compact");
+// at "/" ? then "full" : otherwise "compact"
+```
+
+Use `route.at(url, x, y?)` with dynamic values that require values from the URL pattern's capturing groups:
+
+```js
+document.querySelector("h1").textContent = route.at(
+  /^\/sections\/(?<id>\d+)\/?/,
+  ({ params }) => `Section ${params.id}`,
+);
+// at "/sections/:id", "Section <id>" (otherwise `undefined`)
+```
+
+Or, alternatively, with a string URL pattern:
+
+```js
+import { url } from "url-shape";
+
+document.querySelector("h1").textContent = route.at(
+  url("/sections/:id"),
+  ({ params }) => `Section ${params.id}`,
+);
+// at "/sections/:id", "Section <id>" (otherwise `undefined`)
+```
+
+Use a URL builder like the one from `url-shape` also in conjunction with a URL schema to set up type-safe routes ([example](https://codesandbox.io/p/sandbox/qg7qg3?file=%2Fsrc%2Findex.ts)).
+
+Enable SPA navigation with HTML links inside the specified container (or the entire `document`) without any changes to the HTML:
+
+```js
+route.observe(document);
+```
+
+Tweak the links' navigation behavior by adding a relevant combination of the optional `data-` attributes (corresponding to the `route.navigate()` options):
+
+```html
+<a href="/intro">Intro</a>
+<a href="/intro" data-history="replace">Intro</a>
+<a href="/intro" data-scroll="off">Intro</a>
+<a href="/intro" data-spa="off">Intro</a>
+```
+
+Links covered by `route.observe(container, selector?)` also automatically receive the `data-active="true"` attribute whenever their `href` attribute matches the current URL, which can be used for additional styling. If links are added to the DOM asynchronously, call `route.emit("ready")` when the rendering is complete to mark active links.
+
+Define what should be done when the URL changes:
+
+```js
+route.on("navigationcomplete", ({ href }) => {
+  renderContent();
+});
+```
+
+Define what should be done before the URL changes (in a way effectively similar to routing middleware):
+
+```js
+route.on("navigationstart", ({ href }) => {
+  if (hasUnsavedInput) return false; // Quit the navigation, prevent the current URL change
+
+  if (href === "/") {
+    route.href = "/intro"; // SPA redirection
+    return false;
+  }
+});
+```
+
+## Annotated live demos
+
+- [URL-based rendering](https://codesandbox.io/p/sandbox/kt6m5l?file=%252Fsrc%252Findex.ts)
+- [Type-safe URL-based rendering](https://codesandbox.io/p/sandbox/qg7qg3?file=%2Fsrc%2Findex.ts)
+- [SPA redirection](https://codesandbox.io/p/sandbox/rpl3gh?file=%252Fsrc%252Findex.ts)
+
+Find also the code of these examples in the repo's [`tests`](https://github.com/axtk/compact-router/tree/main/tests) directory.

package/dist/index.cjs

@@ -0,0 +1,369 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let quasiurl = require("quasiurl");
+let compact_state = require("compact-state");
+// src/URLState.ts
+function isImmediatelyInvokedNavigationEvent(event) {
+  return event === "navigationstart" || event === "navigationcomplete";
+}
+function isImmediatelyInvokedEvent(event) {
+  return event === "ready";
+}
+var URLState = class extends compact_state.State {
+  constructor(href = null, options) {
+    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(event, callback, invokeImmediately) {
+    if (invokeImmediately !== false) {
+      if (isImmediatelyInvokedNavigationEvent(event)) this._call(() => {
+        callback({ href: this.getValue() });
+      });
+      else if (isImmediatelyInvokedEvent(event)) this._call(() => {
+        callback();
+      });
+    }
+    return super.on(event, callback);
+  }
+  getValue() {
+    return this.toValue(this._value);
+  }
+  setValue(update, options) {
+    if (!this._active) return;
+    let href = this.toValue(this._resolveValue(update));
+    let extendedOptions = {
+      ...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) {
+    if (typeof window === "undefined" || options?.href === void 0 || options?.source === "popstate") return;
+    let { href, target, spa, history } = options;
+    if (target && target !== "_self") {
+      window.open(href, target);
+      return false;
+    }
+    let url = new quasiurl.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) {
+    if (typeof window === "undefined" || !options || options.scroll === "off") return;
+    let { href, target } = options;
+    if (href === void 0 || target && target !== "_self") return;
+    let { hash } = new quasiurl.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) {
+    if (typeof window === "undefined") return x;
+    let url = new quasiurl.QuasiURL(x || window.location.href);
+    if (url.origin === window.location.origin) url.origin = "";
+    return url.href;
+  }
+};
+// src/utils/isLocationObject.ts
+function isLocationObject(x) {
+  return x !== null && typeof x === "object" && "exec" in x && "compile" in x && "_schema" in x;
+}
+// src/utils/compileURL.ts
+function compileURL(urlPattern, data) {
+  if (isLocationObject(urlPattern)) return urlPattern.compile(data);
+  let url = new quasiurl.QuasiURL(urlPattern ?? "");
+  let query = data?.query;
+  if (query) url.search = new URLSearchParams(Object.entries(query).reduce((p, [k, v]) => {
+    if (v !== null && v !== void 0) p[k] = typeof v === "string" ? v : JSON.stringify(v);
+    return p;
+  }, {}));
+  return url.href;
+}
+// src/utils/getNavigationOptions.ts
+function getNavigationOptions(element) {
+  let { id, spa, history, scroll } = element.dataset;
+  return {
+    href: element.getAttribute("href"),
+    target: element.getAttribute("target"),
+    spa,
+    history,
+    scroll,
+    id
+  };
+}
+// src/utils/isRouteEvent.ts
+function isRouteEvent(event) {
+  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);
+}
+// src/utils/matchURL.ts
+function toObject(x) {
+  return x.reduce((p, v, k) => {
+    p[String(k)] = v;
+    return p;
+  }, {});
+}
+function matchPattern(pattern, href) {
+  let query = Object.fromEntries(new URLSearchParams(new quasiurl.QuasiURL(href).search));
+  if (typeof pattern === "string") return {
+    ok: pattern === "*" || pattern === href,
+    href,
+    params: {},
+    query
+  };
+  if (pattern instanceof RegExp) {
+    let matches = pattern.exec(href);
+    return {
+      ok: matches !== null,
+      href,
+      params: matches ? {
+        ...toObject(Array.from(matches).slice(1)),
+        ...matches.groups
+      } : {},
+      query
+    };
+  }
+  if (isLocationObject(pattern)) {
+    let result = pattern.exec(href);
+    if (result === null) return {
+      ok: false,
+      href,
+      params: {},
+      query: {}
+    };
+    return {
+      ok: true,
+      href,
+      params: result.params ?? {},
+      query: result.query ?? {}
+    };
+  }
+  return {
+    ok: false,
+    href,
+    params: {},
+    query: {}
+  };
+}
+function matchURL(pattern, href) {
+  if (Array.isArray(pattern)) {
+    for (let p of pattern) {
+      let result = matchPattern(p, href);
+      if (result.ok) return result;
+    }
+    return {
+      ok: false,
+      href,
+      params: {},
+      query: {}
+    };
+  }
+  return matchPattern(pattern, href);
+}
+// src/Route.ts
+function isElementCollection(x) {
+  return Array.isArray(x) || x instanceof NodeList || x instanceof HTMLCollection;
+}
+function isLinkElement(x) {
+  return x instanceof HTMLAnchorElement || x instanceof HTMLAreaElement;
+}
+function toggleActive(element, 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;
+}
+var Route = class extends URLState {
+  _observeInited = false;
+  constructor(href = null, options) {
+    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, elements = "a, area") {
+    if (typeof window === "undefined") return;
+    if (!this._observeInited) {
+      let handleClick = (event) => {
+        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;
+      return {
+        resolvedContainer,
+        targetElements: isElementCollection(elements) ? Array.from(elements) : [elements]
+      };
+    };
+    let removeClickHandlers = this.on("documentclick", (event) => {
+      if (event.defaultPrevented || !isRouteEvent(event)) return;
+      let resolvedParams = resolveParams();
+      if (!resolvedParams) return;
+      let { resolvedContainer, targetElements } = resolvedParams;
+      let element = null;
+      for (let targetElement of targetElements) {
+        let target = 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) {
+    if (!options?.href) return;
+    let { href, referrer, ...params } = options;
+    let transformedOptions = {
+      href: String(href),
+      referrer: referrer && String(referrer),
+      ...params
+    };
+    this.setValue(transformedOptions.href, transformedOptions);
+  }
+  assign(url) {
+    this.navigate({ href: url });
+  }
+  replace(url) {
+    this.navigate({
+      href: url,
+      history: "replace"
+    });
+  }
+  reload() {
+    this.assign(this.getValue());
+  }
+  go(delta) {
+    if (typeof window !== "undefined" && window.history) window.history.go(delta);
+  }
+  back() {
+    this.go(-1);
+  }
+  forward() {
+    this.go(1);
+  }
+  get href() {
+    return this.getValue();
+  }
+  set href(value) {
+    this.assign(value);
+  }
+  get pathname() {
+    return new quasiurl.QuasiURL(this.href).pathname;
+  }
+  set pathname(value) {
+    let url = new quasiurl.QuasiURL(this.href);
+    url.pathname = String(value);
+    this.assign(url.href);
+  }
+  get search() {
+    return new quasiurl.QuasiURL(this.href).search;
+  }
+  set search(value) {
+    let url = new quasiurl.QuasiURL(this.href);
+    url.search = value;
+    this.assign(url.href);
+  }
+  get hash() {
+    return new quasiurl.QuasiURL(this.href).hash;
+  }
+  set hash(value) {
+    let url = new quasiurl.QuasiURL(this.href);
+    url.hash = value;
+    this.assign(url.href);
+  }
+  toString() {
+    return this.href;
+  }
+  /**
+  * Matches the current location against `urlPattern`.
+  */
+  match(urlPattern) {
+    return matchURL(urlPattern, this.href);
+  }
+  /**
+  * Compiles `urlPattern` to a URL string by filling out the parameters
+  * based on `data`.
+  */
+  compile(urlPattern, data) {
+    return compileURL(urlPattern, data);
+  }
+  at(urlPattern, x, y) {
+    let result = this.match(urlPattern);
+    if (x === void 0 && y === void 0) return result.ok;
+    if (!result.ok) return typeof y === "function" ? y(result) : y;
+    return typeof x === "function" ? x(result) : x;
+  }
+};
+exports.Route = Route;
+exports.URLState = URLState;
+exports.compileURL = compileURL;
+exports.getNavigationOptions = getNavigationOptions;
+exports.isLocationObject = isLocationObject;
+exports.isRouteEvent = isRouteEvent;
+exports.matchURL = matchURL;

package/dist/index.d.ts

@@ -0,0 +1,149 @@
+import { EventCallback, State, StateOptions, StatePayloadMap, StateUpdate } from "compact-state";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+export type URLComponents = {
+  params?: Record<string, unknown> | undefined;
+  query?: Record<string, unknown> | undefined;
+};
+export type URLSchema = StandardSchemaV1<URLComponents>;
+export type LocationObject = {
+  _schema: URLSchema | undefined;
+  exec: (x: string) => URLComponents | null;
+  compile: (x: any) => string;
+  toString: () => string;
+};
+type URLConfigShape = {
+  strict?: boolean;
+};
+export interface URLConfig extends URLConfigShape {}
+export type LocationValue = URLConfig["strict"] extends true ? LocationObject | undefined : string | LocationObject | undefined;
+export type LocationPattern = URLConfig["strict"] extends true ? LocationValue | LocationValue[] : LocationValue | RegExp | (LocationValue | RegExp)[];
+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>;
+};
+export type MatchHandler<P extends LocationPattern, T> = (payload: MatchState<P>) => T;
+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;
+};
+export type URLData<T extends LocationValue = LocationValue> = T extends {
+  _schema: URLSchema;
+} ? StandardSchemaV1.InferOutput<T["_schema"]> : URLComponents;
+export type URLStatePayloadMap = StatePayloadMap<string> & {
+  navigationstart: NavigationOptions;
+  navigation: NavigationOptions;
+  navigationcomplete: NavigationOptions;
+  ready: void;
+};
+export type URLStateOptions = StateOptions;
+export declare class URLState<P extends URLStatePayloadMap = URLStatePayloadMap> extends State<string, P> {
+  constructor(href?: string | null, options?: URLStateOptions);
+  _init(): void;
+  on<E extends string>(event: E, callback: EventCallback<P[E]>, invokeImmediately?: boolean): () => void;
+  getValue(): string;
+  setValue(update: string | StateUpdate<string>, options?: NavigationOptions): void;
+  _transition(options?: NavigationOptions): boolean | void | undefined;
+  _complete(options?: NavigationOptions): boolean | void | undefined;
+  toValue(x: string): string;
+}
+export type ContainerElement = Document | Element | null | undefined;
+export type ElementCollection = (string | Node)[] | HTMLCollection | NodeList;
+export type ObservedElement = string | Node | (string | Node)[] | HTMLCollection | NodeList;
+export type RoutePayloadMap = URLStatePayloadMap & {
+  documentclick: MouseEvent;
+};
+export type RouteOptions = URLStateOptions;
+export declare class Route extends URLState<RoutePayloadMap> {
+  _observeInited: boolean;
+  constructor(href?: LocationValue | null, options?: RouteOptions);
+  /**
+   * 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): (() => void) | undefined;
+  /**
+   * 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;
+  assign(url: LocationValue): void;
+  replace(url: LocationValue): void;
+  reload(): void;
+  go(delta: number): void;
+  back(): void;
+  forward(): void;
+  get href(): string;
+  set href(value: LocationValue);
+  get pathname(): string;
+  set pathname(value: LocationValue);
+  get search(): string;
+  set search(value: string | URLSearchParams);
+  get hash(): string;
+  set hash(value: string);
+  toString(): string;
+  /**
+   * Matches the current location against `urlPattern`.
+   */
+  match<P extends LocationPattern>(urlPattern: P): MatchState<P>;
+  /**
+   * Compiles `urlPattern` to a URL string by filling out the parameters
+   * based on `data`.
+   */
+  compile<T extends LocationValue>(urlPattern: T, data?: URLData<T>): string;
+  /**
+   * `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;
+}
+export type LinkElement = HTMLAnchorElement | HTMLAreaElement;
+export declare function compileURL<T extends LocationValue>(urlPattern: T, data?: URLData<T>): string;
+export declare function getNavigationOptions(element: LinkElement): NavigationOptions;
+export declare function isLocationObject(x: unknown): x is LocationObject;
+export declare function isRouteEvent(event: unknown): boolean;
+export declare function matchURL<P extends LocationPattern>(pattern: P, href: string): MatchState<P>;
+export {};