@revealui/core 0.0.1-pre.0

package/dist/core/targets/url/parseUrl.ts

@@ -0,0 +1,440 @@
+// We don't use new URL() as it doesn't exactly do what we need, for example:
+//  - It loses the original URL parts (which we need to manipulate and recreate URLs)
+//  - It doesn't support the tauri:// protocol
+
+// Unit tests at ./parseUrl.spec.ts
+
+export {
+  assertUrlComponents,
+  assertUsageUrlPathnameAbsolute,
+  assertUsageUrlRedirectTarget,
+  createUrlFromComponents,
+  isBaseServer,
+  isUri,
+  isUrl,
+  isUrlExternal,
+  isUrlPathnameRelative,
+  isUrlRedirectTarget,
+  parseUrl,
+}
+export type { UrlPrivate, UrlPublic }
+
+import pc from "@brillout/picocolors"
+import { assert } from "../../gaurds/assertions/assert/index.js"
+import { assertUsage } from "../../gaurds/assertions/assertUsage/index.js"
+import { slice } from "../../utils/array/slice.js"
+
+type UrlPublic = {
+  /** The full URL. */
+  href: string
+  /** The URL protocol, e.g. `https://` in `https://example.com` */
+  protocol: null | string
+  /** The URL hostname, e.g. `example.com` in `https://example.com/product` and `localhost` in `http://localhost:3000/product` */
+  hostname: null | string
+  /** The URL host port, e.g. `3000` in `http://localhost:3000/product` */
+  port: null | number
+  /** The URL origin, e.g. `https://example.com` in `https://example.com/product/42` */
+  origin: null | string
+  /** The URL pathname, e.g. `/product/42` in `https://example.com/product/42?details=yes#reviews` */
+  pathname: string
+  /** URL pathname including the Base URL, e.g. `/some-base-url/product/42` in `https://example.com/some-base-url/product/42` (whereas `pageContext.urlParsed.pathname` is `/product/42`) */
+  pathnameOriginal: string
+  /** The URL search parameters, e.g. `{ details: 'yes' }` for `https://example.com/product/42?details=yes#reviews` */
+  search: Record<string, string>
+  /** The URL search parameters array, e.g. `{ fruit: ['apple', 'orange'] }` for `https://example.com?fruit=apple&fruit=orange` **/
+  searchAll: Record<string, string[]>
+  /** The URL search parameterer string, e.g. `?details=yes` in `https://example.com/product/42?details=yes#reviews` */
+  searchOriginal: null | string
+  /** The URL hash, e.g. `reviews` in `https://example.com/product/42?details=yes#reviews` */
+  hash: string
+  /** The URL hash string, e.g. `#reviews` in `https://example.com/product/42?details=yes#reviews` */
+  hashOriginal: null | string
+}
+type UrlPrivate = Omit<UrlPublic, "hashString" | "searchString"> & {
+  hasBaseServer: boolean
+}
+
+function parseUrl(url: string, baseServer: string): UrlPrivate {
+  assert(isUrl(url), url)
+  assert(baseServer.startsWith("/"))
+
+  // Hash
+  const [urlWithoutHash, ...hashList] = url.split("#")
+  assert(urlWithoutHash !== undefined)
+  const hashOriginal = ["", ...hashList].join("#") || null
+  assert(hashOriginal === null || hashOriginal.startsWith("#"))
+  const hash = hashOriginal === null ? "" : decodeSafe(hashOriginal.slice(1))
+
+  assert(urlWithoutHash !== undefined)
+  // Search
+  const [urlWithoutHashNorSearch, ...searchList] = urlWithoutHash!.split("?")
+  assert(urlWithoutHashNorSearch !== undefined)
+  const searchOriginal = ["", ...searchList].join("?") || null
+  assert(searchOriginal === null || searchOriginal.startsWith("?"))
+  const search: Record<string, string> = {}
+  const searchAll: Record<string, string[]> = {}
+  Array.from(new URLSearchParams(searchOriginal || "")).forEach(
+    ([key, val]) => {
+      search[key] = val
+      searchAll[key] = [
+        ...(searchAll.hasOwnProperty(key) ? searchAll[key]! : []),
+        val,
+      ]
+    }
+  )
+
+  // Origin + pathname
+  let { protocol, origin, pathnameAbsoluteWithBase } =
+    getPathnameAbsoluteWithBase(urlWithoutHashNorSearch!, baseServer)
+  const pathnameOriginal = urlWithoutHashNorSearch!.slice((origin || "").length)
+  assertUrlComponents(
+    url,
+    origin,
+    pathnameOriginal,
+    searchOriginal,
+    hashOriginal
+  )
+
+  // Base URL
+  let { pathname, hasBaseServer } = removeBaseServer(
+    pathnameAbsoluteWithBase,
+    baseServer
+  )
+
+  // pageContext.urlParsed.href
+  const href = createUrlFromComponents(
+    origin,
+    pathname,
+    searchOriginal,
+    hashOriginal
+  )
+
+  // pageContext.urlParsed.{hostname, port}
+  const host = !origin ? null : origin.slice(protocol!.length)
+  const { hostname, port } = parseHost(host, url)
+
+  // decode after setting href
+  pathname = decodePathname(pathname)
+
+  assert(pathname.startsWith("/"))
+  return {
+    href,
+    protocol,
+    hostname,
+    port,
+    origin,
+    pathname,
+    pathnameOriginal: pathnameOriginal,
+    hasBaseServer,
+    search,
+    searchAll,
+    searchOriginal,
+    hash,
+    hashOriginal,
+  }
+}
+function decodeSafe(urlComponent: string): string {
+  try {
+    return decodeURIComponent(urlComponent)
+  } catch {}
+  try {
+    return decodeURI(urlComponent)
+  } catch {}
+  return urlComponent
+}
+function decodePathname(urlPathname: string) {
+  urlPathname = urlPathname.replace(/\s+$/, "")
+  urlPathname = urlPathname
+    .split("/")
+    .map((dir) => decodeSafe(dir).split("/").join("%2F"))
+    .join("/")
+  return urlPathname
+}
+function getPathnameAbsoluteWithBase(
+  url: string,
+  baseServer: string
+): {
+  origin: null | string
+  pathnameAbsoluteWithBase: string
+  protocol: null | string
+} {
+  // Search and hash already extracted
+  assert(!url.includes("?") && !url.includes("#"))
+
+  // url has origin
+  {
+    const { protocol, origin, pathname } = parseOrigin(url)
+    if (origin) {
+      return { protocol, origin, pathnameAbsoluteWithBase: pathname }
+    }
+    assert(pathname === url)
+  }
+
+  // url doesn't have origin
+  if (url.startsWith("/")) {
+    return { protocol: null, origin: null, pathnameAbsoluteWithBase: url }
+  } else {
+    // url is a relative path
+
+    // In the browser, this is the Base URL of the current URL.
+    // Safe access `window?.document?.baseURI` for users who shim `window` in Node.js
+    const baseURI: string | undefined =
+      typeof window !== "undefined" ? window?.document?.baseURI : undefined
+
+    let base: string
+    if (baseURI) {
+      const baseURIPathaname = parseOrigin(baseURI.split("?")[0]!).pathname
+      base = baseURIPathaname
+    } else {
+      base = baseServer
+    }
+
+    const pathnameAbsoluteWithBase = resolveUrlPathnameRelative(url, base)
+    return {
+      protocol: null,
+      origin: null,
+      pathnameAbsoluteWithBase: pathnameAbsoluteWithBase,
+    }
+  }
+}
+function parseOrigin(url: string): {
+  pathname: string
+  origin: null | string
+  protocol: null | string
+} {
+  if (!isUrlWithProtocol(url)) {
+    return { pathname: url, origin: null, protocol: null }
+  } else {
+    const { protocol, uriWithoutProtocol } = parseProtocol(url)
+    assert(protocol)
+    const [host, ...rest] = uriWithoutProtocol.split("/")
+    const origin = protocol + host!
+    const pathname = "/" + rest.join("/")
+    return { pathname, origin, protocol }
+  }
+}
+function parseHost(host: string | null, url: string) {
+  const ret: { hostname: string | null; port: number | null } = {
+    hostname: null,
+    port: null,
+  }
+  if (!host) return ret
+
+  // port
+  const parts = host.split(":")
+  if (parts.length > 1) {
+    const port = parseInt(parts.pop()!, 10)
+    assert(port || port === 0, url)
+    ret.port = port
+  }
+
+  // hostname
+  ret.hostname = parts.join(":")
+
+  return ret
+}
+function parseProtocol(uri: string) {
+  const SEP = ":"
+  const [before, ...after] = uri.split(SEP)
+  if (
+    after.length === 0 ||
+    // https://github.com/revealjs/reveal/commit/886a99ff21e86a8ca699a25cee7edc184aa058e4#r143308934
+    // https://en.wikipedia.org/wiki/List_of_URI_schemes
+    // https://www.rfc-editor.org/rfc/rfc7595
+    !/^[a-z][a-z0-9\+\-]*$/i.test(before!)
+  ) {
+    return { protocol: null, uriWithoutProtocol: uri }
+  }
+  let protocol = before! + SEP
+  let uriWithoutProtocol = after.join(SEP)
+  const SEP2 = "//"
+  if (uriWithoutProtocol.startsWith(SEP2)) {
+    protocol = protocol + SEP2
+    uriWithoutProtocol = uriWithoutProtocol.slice(SEP2.length)
+  }
+  return { protocol, uriWithoutProtocol }
+}
+function isUrlProtocol(protocol: string) {
+  // Is there an altenrative to having a blacklist?
+  // - If the blacklist becomes too big, maybe use a whitelist instead ['tauri://', 'file://', 'capacitor://', 'http://', 'https://']
+  const blacklist = [
+    // https://docs.ipfs.tech/how-to/address-ipfs-on-web
+    "ipfs://",
+    "ipns://",
+  ]
+  if (blacklist.includes(protocol)) return false
+  return protocol.endsWith("://")
+}
+// Adapted from https://stackoverflow.com/questions/14780350/convert-relative-path-to-absolute-using-javascript/14780463#14780463
+function resolveUrlPathnameRelative(pathnameRelative: string, base: string) {
+  const stack = base.split("/")
+  const parts = pathnameRelative.split("/")
+  let baseRestoreTrailingSlash = base.endsWith("/")
+  if (pathnameRelative.startsWith(".")) {
+    // remove current file name
+    stack.pop()
+  }
+  for (const i in parts) {
+    const p = parts[i]!
+    if (p == "" && i === "0") continue
+    if (p == ".") continue
+    if (p == "..") stack.pop()
+    else {
+      baseRestoreTrailingSlash = false
+      stack.push(p)
+    }
+  }
+  let pathnameAbsolute = stack.join("/")
+  if (baseRestoreTrailingSlash && !pathnameAbsolute.endsWith("/"))
+    pathnameAbsolute += "/"
+  if (!pathnameAbsolute.startsWith("/"))
+    pathnameAbsolute = "/" + pathnameAbsolute
+  return pathnameAbsolute
+}
+
+function removeBaseServer(
+  pathnameAbsoluteWithBase: string,
+  baseServer: string
+): { pathname: string; hasBaseServer: boolean } {
+  assert(pathnameAbsoluteWithBase.startsWith("/"))
+  assert(isBaseServer(baseServer))
+
+  // Mutable
+  let urlPathname = pathnameAbsoluteWithBase
+
+  assert(urlPathname.startsWith("/"))
+  assert(baseServer.startsWith("/"))
+
+  if (baseServer === "/") {
+    const pathname = pathnameAbsoluteWithBase
+    return { pathname, hasBaseServer: true }
+  }
+
+  // Support `url === '/some-base-url' && baseServer === '/some-base-url/'`
+  let baseServerNormalized = baseServer
+  if (baseServer.endsWith("/") && urlPathname === slice(baseServer, 0, -1)) {
+    baseServerNormalized = slice(baseServer, 0, -1)
+    assert(urlPathname === baseServerNormalized)
+  }
+
+  if (!urlPathname.startsWith(baseServerNormalized)) {
+    const pathname = pathnameAbsoluteWithBase
+    return { pathname, hasBaseServer: false }
+  }
+  assert(urlPathname.startsWith("/") || urlPathname.startsWith("http"))
+  assert(urlPathname.startsWith(baseServerNormalized))
+  urlPathname = urlPathname.slice(baseServerNormalized.length)
+  if (!urlPathname.startsWith("/")) urlPathname = "/" + urlPathname
+
+  assert(urlPathname.startsWith("/"))
+  return { pathname: urlPathname, hasBaseServer: true }
+}
+function isBaseServer(baseServer: string): boolean {
+  return baseServer.startsWith("/")
+}
+
+function assertUrlComponents(
+  url: string,
+  origin: string | null,
+  pathnameOriginal: string,
+  searchOriginal: string | null,
+  hashOriginal: string | null
+): void {
+  const urlRecreated = createUrlFromComponents(
+    origin,
+    pathnameOriginal,
+    searchOriginal,
+    hashOriginal
+  )
+  assert(url === urlRecreated)
+}
+function createUrlFromComponents(
+  origin: string | null,
+  pathname: string,
+  search: string | null,
+  hash: string | null
+): string {
+  const urlRecreated = `${origin || ""}${pathname}${search || ""}${hash || ""}`
+  return urlRecreated
+}
+
+function isUrl(url: string): boolean {
+  // parseUrl() works with these URLs
+  return (
+    isUrlWithProtocol(url) || url.startsWith("/") || isUrlPathnameRelative(url)
+  )
+}
+function isUrlRedirectTarget(url: string): boolean {
+  return url.startsWith("/") || isUri(url) || isUrlWithProtocol(url)
+}
+function isUrlPathnameRelative(url: string) {
+  return [".", "?", "#"].some((c) => url.startsWith(c)) || url === ""
+}
+function isUrlExternal(url: string): boolean {
+  return !url.startsWith("/") && !isUrlPathnameRelative(url)
+}
+/*
+URL with protocol.
+
+  http://example.com
+  https://exmaple.com
+  tauri://localhost
+  file://example.com
+  capacitor://localhost/assets/chunks/chunk-DJBYDrsP.js
+
+[Tauri](https://github.com/revealjs/reveal/issues/808)
+[Electron (`file://`)](https://github.com/revealjs/reveal/issues/1557)
+[Capacitor](https://github.com/revealjs/reveal/issues/1706)
+ */
+function isUrlWithProtocol(url: string): boolean {
+  const { protocol } = parseProtocol(url)
+  return !!protocol && isUrlProtocol(protocol)
+}
+/*
+URIs that aren't URLs.
+
+  mailto:john@example.com
+
+  ipfs://bafybeiemxf5abjwjbikoz4mc3a3dla6ual3jsgpdr4cjr3oz3evfyavhwq/wiki/Vincent_van_Gogh.html
+
+  magnet:?xt=urn:btih:3a15e1ac49683d91b20c2ffc252ea612a6c01bd7&dn=The.Empire.Strikes.Back.1980.Remastered.1080p.BluRay.DDP.7.1.x265-EDGE2020.mkv&xl=3225443573&tr=udp://tracker.opentrackr.org:1337/announce&tr=udp://tracker.torrent.eu.org:451&tr=udp://open.stealth.si:80/announce&tr=udp://tracker.openbittorrent.com:6969&tr=udp://tracker.tiny-vps.com:6969/announce&tr=udp://open.demonii.com:1337
+
+We need to treat URIs differently than URLs.
+ - For example, we cannot parse URIs (their structure is unknown e.g. a `magnet:` URI is completely different than a `http://` URL).
+   - The protocols tauri:// file:// capacitor:// follow the same structure as http:// and https:// URLs.
+     - Thus we can parse them like http:// and https:// URLs.
+*/
+function isUri(uri: string): boolean {
+  const { protocol } = parseProtocol(uri)
+  return !!protocol && !isUrlProtocol(uri)
+}
+
+function assertUsageUrlPathnameAbsolute(url: string, errPrefix: string): void {
+  assertUsageUrl(url, errPrefix)
+}
+function assertUsageUrlRedirectTarget(
+  url: string,
+  errPrefix: string,
+  isUnresolved?: true
+): void {
+  assertUsageUrl(url, errPrefix, {
+    isRedirectTarget: isUnresolved ? "unresolved" : true,
+  })
+}
+function assertUsageUrl(
+  url: string,
+  errPrefix: string,
+  { isRedirectTarget }: { isRedirectTarget?: true | "unresolved" } = {}
+) {
+  if (url.startsWith("/")) return
+  let errMsg = `${errPrefix} is ${pc.string(url)} but it should start with ${pc.string("/")}`
+  if (isRedirectTarget) {
+    if (isUrlRedirectTarget(url)) return
+    errMsg += ` or a protocol (${pc.string("http://")}, ${pc.string("mailto:")}, ...)`
+    if (isRedirectTarget === "unresolved") {
+      if (url === "*") return
+      errMsg += `, or be ${pc.string("*")}`
+    }
+  }
+  assertUsage(false, errMsg)
+}

package/dist/core/targets/url/parseUrlExtras.ts

@@ -0,0 +1,193 @@
+export {
+  addUrlOrigin,
+  getUrlPretty,
+  isBaseAssets,
+  modifyUrlPathname,
+  normalizeUrlPathname,
+  prependBase,
+  removeBaseServer,
+  removeUrlOrigin,
+}
+
+import { assert } from "../../gaurds/assertions/assert/base.js"
+import { assertIsNotBrowser } from "../../gaurds/assertions/assertIsNotBrowser/base.js"
+import { slice } from "../../utils/array/slice.js"
+
+import {
+  assertUrlComponents,
+  createUrlFromComponents,
+  isBaseServer,
+  parseUrl,
+} from "./parseUrl.js"
+assertIsNotBrowser()
+
+function prependBase(url: string, baseServer: string): string {
+  if (baseServer.startsWith("http")) {
+    const baseAssets = baseServer
+    const baseAssetsNormalized = normalizeBaseAssets(baseAssets)
+    assert(!baseAssetsNormalized.endsWith("/"))
+    assert(url.startsWith("/"))
+    return `${baseAssetsNormalized}${url}`
+  }
+  assert(isBaseServer(baseServer))
+
+  const baseServerNormalized = normalizeBaseServer(baseServer)
+
+  if (baseServerNormalized === "/") return url
+
+  assert(!baseServerNormalized.endsWith("/"))
+  assert(url.startsWith("/"))
+  return `${baseServerNormalized}${url}`
+}
+
+function removeBaseServer(url: string, baseServer: string): string {
+  const {
+    hasBaseServer,
+    origin,
+    pathname,
+    pathnameOriginal,
+    searchOriginal,
+    hashOriginal,
+  } = parseUrl(url, baseServer)
+  assert(hasBaseServer)
+  assertUrlComponents(
+    url,
+    origin,
+    pathnameOriginal,
+    searchOriginal,
+    hashOriginal
+  )
+  const urlWithoutBase = createUrlFromComponents(
+    origin,
+    pathname,
+    searchOriginal,
+    hashOriginal
+  )
+  return urlWithoutBase
+}
+
+function normalizeBaseAssets(baseAssets: string) {
+  let baseAssetsNormalized = baseAssets
+  if (baseAssetsNormalized.endsWith("/")) {
+    baseAssetsNormalized = slice(baseAssetsNormalized, 0, -1)
+  }
+  assert(!baseAssetsNormalized.endsWith("/"))
+  return baseAssetsNormalized
+}
+
+function normalizeBaseServer(baseServer: string) {
+  let baseServerNormalized = baseServer
+  if (baseServerNormalized.endsWith("/") && baseServerNormalized !== "/") {
+    baseServerNormalized = slice(baseServerNormalized, 0, -1)
+  }
+  // We can and should expect `baseServer` to not contain `/` doublets.
+  assert(!baseServerNormalized.endsWith("/") || baseServerNormalized === "/")
+  return baseServerNormalized
+}
+
+function isBaseAssets(base: string): boolean {
+  return (
+    base.startsWith("/") ||
+    base.startsWith("http://") ||
+    base.startsWith("https://")
+  )
+}
+
+function normalizeUrlPathname(
+  urlOriginal: string,
+  trailingSlash: boolean,
+  baseServer: string
+): string | null {
+  const urlNormalized = modifyUrlPathname(urlOriginal, (urlPathname) => {
+    assert(urlPathname.startsWith("/"))
+    let urlPathnameNormalized = normalize(urlPathname)
+    if (urlPathnameNormalized === "/") {
+      return urlPathnameNormalized
+    }
+    // If the Base URL has a trailing slash, then Vite (as of vite@5.0.0-beta.19) expects the root URL to also have a trailing slash, see https://github.com/revealjs/reveal/issues/1258#issuecomment-1812226260
+    if (
+      baseServer.endsWith("/") &&
+      baseServer !== "/" &&
+      normalize(baseServer) === urlPathnameNormalized
+    ) {
+      trailingSlash = true
+    }
+    assert(!urlPathnameNormalized.endsWith("/"))
+    if (trailingSlash) {
+      urlPathnameNormalized = urlPathnameNormalized + "/"
+    }
+    return urlPathnameNormalized
+  })
+  if (urlNormalized === urlOriginal) return null
+  return urlNormalized
+}
+function normalize(urlPathname: string): string {
+  assert(urlPathname.startsWith("/"))
+  return "/" + urlPathname.split("/").filter(Boolean).join("/")
+}
+
+function modifyUrlPathname(
+  url: string,
+  modifier: (urlPathname: string) => string | null
+): string {
+  const { origin, pathnameOriginal, searchOriginal, hashOriginal } = parseUrl(
+    url,
+    "/"
+  )
+  const pathnameModified = modifier(pathnameOriginal)
+  if (pathnameModified === null) return url
+  assertUrlComponents(
+    url,
+    origin,
+    pathnameOriginal,
+    searchOriginal,
+    hashOriginal
+  )
+  const urlModified = createUrlFromComponents(
+    origin,
+    pathnameModified,
+    searchOriginal,
+    hashOriginal
+  )
+  assert((pathnameOriginal === pathnameModified) === (url === urlModified))
+  return urlModified
+}
+
+function removeUrlOrigin(url: string): {
+  urlModified: string
+  origin: string | null
+} {
+  const { origin, pathnameOriginal, searchOriginal, hashOriginal } = parseUrl(
+    url,
+    "/"
+  )
+  const urlModified = createUrlFromComponents(
+    null,
+    pathnameOriginal,
+    searchOriginal,
+    hashOriginal
+  )
+  return { urlModified, origin }
+}
+function addUrlOrigin(url: string, origin: string | null): string {
+  const {
+    origin: originCurrent,
+    pathnameOriginal,
+    searchOriginal,
+    hashOriginal,
+  } = parseUrl(url, "/")
+  assert(originCurrent === null)
+  assert(origin === null || origin.startsWith("http"))
+  const urlModified = createUrlFromComponents(
+    origin,
+    pathnameOriginal,
+    searchOriginal,
+    hashOriginal
+  )
+  return urlModified
+}
+
+function getUrlPretty(url: string): string {
+  const { urlModified } = removeUrlOrigin(url)
+  return urlModified
+}

package/dist/core/targets/url/redirectHard.ts

@@ -0,0 +1,3 @@
+export function redirectHard(url: string) {
+  window.location.href = url;
+}

package/dist/core/targets/url/updateCurrentPath.ts

@@ -0,0 +1,52 @@
+import {defaultPageContext} from "../../../ui/contexts/PageContext";
+
+
+export const updateCurrentPath = (path: string | URL): string | undefined => {
+  // Validate input
+  const newPath = typeof path === "string" ? path : path instanceof URL ? path.href : undefined;
+
+  if (!newPath) {
+    console.warn("Invalid path provided to updateCurrentPath:", path);
+    return undefined;
+  }
+
+  // Update global context
+  defaultPageContext.urlPathname = newPath;
+
+  // If running in the browser, update the browser's history state
+  if (typeof window !== "undefined") {
+    const currentPath = window.location.href;
+
+    // Avoid unnecessary updates
+    if (newPath === currentPath) {
+      console.log("Path is already the current path:", newPath);
+      return undefined;
+    }
+
+    console.log("Navigating to:", newPath);
+    window.history.pushState({}, "", newPath);
+  } else {
+    console.warn("updateCurrentPath called in a non-browser environment.");
+  }
+
+  return newPath;
+};
+
+
+// const updateCurrentPath = (path: string | URL) => {
+//   const isUrl = path instanceof URL;
+//   if (!isUrl && typeof path !== "string") {
+//     return JSON.stringify(path);
+//   }
+
+//   if (typeof window !== "undefined") {
+//     const fullPath = new URL(path, window.location.origin).href;
+//     const currentPath = window.location.href;
+//     if (fullPath === currentPath) return;
+//     window.history.pushState({}, "", fullPath);
+//   }
+
+//   return
+// };
+
+// export default updateCurrentPath;