@pathmx/core 0.5.0

package/plugins/runtime/document.ts

@@ -0,0 +1,506 @@
+import morphdom from "morphdom"
+import { APP_COMPONENT_ROOT_ATTRIBUTE } from "../app-component.ts"
+import { startPathMXViewTransition } from "./view-transition.ts"
+import { publicationPath } from "./publication.ts"
+
+declare global {
+  interface Window {
+    __pmxCanonicalView?: HTMLElement
+  }
+}
+
+export type RenderType = "navigation" | "traverse" | "action" | "live"
+export type RenderScope = "blocks" | "document"
+
+export type RenderDetail = {
+  type: RenderType
+  from: string
+  to: string
+  blocks: string[]
+  scope: RenderScope
+  viewTransitionTypes: readonly string[]
+}
+
+export type LoadedPathMXDocument = {
+  document: Document
+  responseUrl: URL
+  requestedUrl: URL
+  view: HTMLElement
+}
+
+export class PathMXDocumentError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = "PathMXDocumentError"
+  }
+}
+
+export class PathMXReloadRequiredError extends PathMXDocumentError {
+  constructor(message: string) {
+    super(message)
+    this.name = "PathMXReloadRequiredError"
+  }
+}
+
+function assetUrl(element: Element, attribute: "href" | "src") {
+  try {
+    return new URL(element.getAttribute(attribute) || "", location.href)
+  } catch {
+    return
+  }
+}
+
+function stylesheetKey(link: Element) {
+  const href = assetUrl(link, "href")
+  if (!href) return link.getAttribute("href") || ""
+  href.search = ""
+  if (isHashedAsset(href.pathname)) {
+    return href.pathname.replace(/-[0-9a-f]{16}(?=\.[^/]+$)/, "")
+  }
+  return href.pathname
+}
+
+function isHashedAsset(pathname: string) {
+  return pathname.startsWith(publicationPath("/.pmx/"))
+}
+
+function scriptKey(script: Element) {
+  const src = assetUrl(script, "src")
+  if (!src) return script.getAttribute("src") || ""
+  src.search = ""
+  if (isHashedAsset(src.pathname)) {
+    return src.pathname.replace(/-[0-9a-f]{16}(?=\.[^/]+$)/, "")
+  }
+  return src.href
+}
+
+function runtimeSource(head: HTMLHeadElement) {
+  return [...head.querySelectorAll("script[src]")]
+    .find((script) => scriptKey(script) === publicationPath("/.pmx/runtime.js"))
+    ?.getAttribute("src")
+}
+
+function executableScript(script: Element) {
+  const executable = document.createElement("script")
+  for (const attr of script.attributes) {
+    executable.setAttribute(attr.name, attr.value)
+  }
+  executable.textContent = script.textContent
+  return executable
+}
+
+function metaKey(meta: Element) {
+  const name = meta.getAttribute("name")
+  const property = meta.getAttribute("property")
+  if (!name && !property) return
+  return [name, property, meta.getAttribute("media")].join("\0")
+}
+
+function reconcileMetadata(
+  current: HTMLHeadElement,
+  incoming: HTMLHeadElement,
+) {
+  const nextTitle = incoming.querySelector("title")
+  const title = current.querySelector("title")
+  if (nextTitle) {
+    if (title) title.textContent = nextTitle.textContent
+    else current.prepend(nextTitle.cloneNode(true))
+  } else {
+    title?.remove()
+  }
+
+  const currentMetas = [...current.querySelectorAll("meta")]
+  const incomingMetas = [...incoming.querySelectorAll("meta")]
+  const incomingByKey = new Map(
+    incomingMetas.flatMap((meta) => {
+      const key = metaKey(meta)
+      return key ? [[key, meta] as const] : []
+    }),
+  )
+
+  for (const [key, incomingMeta] of incomingByKey) {
+    const existing = currentMetas.find((meta) => metaKey(meta) === key)
+    if (existing) {
+      for (const attr of [...existing.attributes]) {
+        if (!incomingMeta.hasAttribute(attr.name))
+          existing.removeAttribute(attr.name)
+      }
+      for (const attr of [...incomingMeta.attributes]) {
+        existing.setAttribute(attr.name, attr.value)
+      }
+    } else {
+      current.append(incomingMeta.cloneNode(true))
+    }
+  }
+
+  for (const meta of currentMetas) {
+    const key = metaKey(meta)
+    if (key && !incomingByKey.has(key)) meta.remove()
+  }
+}
+
+function reconcileStylesheets(
+  current: HTMLHeadElement,
+  incoming: HTMLHeadElement,
+  type: RenderType,
+) {
+  const currentLinks = [...current.querySelectorAll('link[rel="stylesheet"]')]
+  const incomingLinks = [...incoming.querySelectorAll('link[rel="stylesheet"]')]
+  const incomingByKey = new Map(
+    incomingLinks.map((link) => [stylesheetKey(link), link]),
+  )
+
+  for (const [key, incomingLink] of incomingByKey) {
+    const currentLink = currentLinks.find((link) => stylesheetKey(link) === key)
+    const nextHref = incomingLink.getAttribute("href") || ""
+    if (!currentLink) {
+      current.append(incomingLink.cloneNode(true))
+      continue
+    }
+    if (isHashedAsset(key)) {
+      if (currentLink.getAttribute("href") === nextHref) continue
+      const added = incomingLink.cloneNode(true) as HTMLLinkElement
+      added.addEventListener("load", () => currentLink.remove(), { once: true })
+      currentLink.after(added)
+      continue
+    }
+    if (currentLink.getAttribute("href") === nextHref && type !== "live")
+      continue
+    const bust = new URL(nextHref, location.href)
+    if (type === "live") bust.searchParams.set("t", String(Date.now()))
+    currentLink.setAttribute("href", bust.href)
+  }
+
+  for (const link of currentLinks) {
+    if (!incomingByKey.has(stylesheetKey(link))) link.remove()
+  }
+}
+
+function reconcileInlineStyles(
+  current: HTMLHeadElement,
+  incoming: HTMLHeadElement,
+) {
+  for (const style of current.querySelectorAll("style")) style.remove()
+  for (const style of incoming.querySelectorAll("style")) {
+    current.append(style.cloneNode(true))
+  }
+}
+
+function assertRuntimeCompatible(
+  current: HTMLHeadElement,
+  incoming: HTMLHeadElement,
+) {
+  if (runtimeSource(current) !== runtimeSource(incoming)) {
+    throw new PathMXReloadRequiredError("The PathMX browser runtime changed.")
+  }
+}
+
+function reconcileScripts(current: HTMLHeadElement, incoming: HTMLHeadElement) {
+  const currentScripts = [...current.querySelectorAll("script[src]")]
+  const incomingScripts = [...incoming.querySelectorAll("script[src]")]
+  const incomingKeys = new Set(incomingScripts.map(scriptKey))
+
+  for (const incomingScript of incomingScripts) {
+    const key = scriptKey(incomingScript)
+    const existing = currentScripts.find((script) => scriptKey(script) === key)
+    if (!existing) {
+      current.append(executableScript(incomingScript))
+      continue
+    }
+    if (existing.getAttribute("src") === incomingScript.getAttribute("src"))
+      continue
+    const replacement = executableScript(incomingScript)
+    replacement.addEventListener("load", () => existing.remove(), {
+      once: true,
+    })
+    replacement.addEventListener("error", () => replacement.remove(), {
+      once: true,
+    })
+    existing.after(replacement)
+  }
+
+  for (const currentScript of currentScripts) {
+    if (!incomingKeys.has(scriptKey(currentScript))) currentScript.remove()
+  }
+}
+
+function reconcileComponentScripts(
+  current: HTMLHeadElement,
+  incoming: HTMLHeadElement,
+) {
+  const selector = "script[data-pmx-component]"
+  const currentScripts = [...current.querySelectorAll(selector)]
+  const incomingScripts = [...incoming.querySelectorAll(selector)]
+  const incomingByComponent = new Map(
+    incomingScripts.map((script) => [
+      script.getAttribute("data-pmx-component") ?? "",
+      script,
+    ]),
+  )
+
+  for (const [component, incomingScript] of incomingByComponent) {
+    const existing = currentScripts.find(
+      (script) => script.getAttribute("data-pmx-component") === component,
+    )
+    if (existing?.isEqualNode(incomingScript)) continue
+    const replacement = executableScript(incomingScript)
+    if (existing) existing.replaceWith(replacement)
+    else current.append(replacement)
+  }
+
+  for (const currentScript of currentScripts) {
+    const component = currentScript.getAttribute("data-pmx-component") ?? ""
+    if (!incomingByComponent.has(component)) currentScript.remove()
+  }
+}
+
+function reconcileHead(
+  current: HTMLHeadElement,
+  incoming: HTMLHeadElement,
+  type: RenderType,
+) {
+  assertRuntimeCompatible(current, incoming)
+  reconcileMetadata(current, incoming)
+  reconcileStylesheets(current, incoming, type)
+  reconcileInlineStyles(current, incoming)
+  reconcileComponentScripts(current, incoming)
+  reconcileScripts(current, incoming)
+}
+
+function reconcileHtmlAttributes(current: HTMLElement, incoming: HTMLElement) {
+  for (const name of [
+    "lang",
+    "data-pmx-base",
+    "data-pmx-page",
+    "data-pmx-scheme",
+    "style",
+  ]) {
+    const value = incoming.getAttribute(name)
+    if (value == null) current.removeAttribute(name)
+    else current.setAttribute(name, value)
+  }
+}
+
+function currentView() {
+  const view = document.querySelector("[data-pmx-view]")
+  if (!(view instanceof HTMLElement)) {
+    throw new PathMXDocumentError("The current PathMX view is missing.")
+  }
+  return view
+}
+
+const blockSelector = ".pmx-document > section[data-pmx-block]"
+
+function blocksIn(view: HTMLElement) {
+  return [...view.querySelectorAll<HTMLElement>(blockSelector)]
+}
+
+function blockMap(blocks: readonly HTMLElement[]) {
+  const byId = new Map<string, HTMLElement>()
+  for (const block of blocks) {
+    if (!block.id || byId.has(block.id)) return
+    byId.set(block.id, block)
+  }
+  return byId
+}
+
+function shellClone(view: HTMLElement) {
+  const clone = view.cloneNode(true) as HTMLElement
+  const articles = clone.querySelectorAll<HTMLElement>(".pmx-document")
+  if (articles.length !== 1) return
+  const article = articles[0]!
+  article.replaceChildren(
+    article.ownerDocument.createComment("pmx-document-content"),
+  )
+  for (const app of clone.querySelectorAll<HTMLElement>(
+    `[${APP_COMPONENT_ROOT_ATTRIBUTE}]`,
+  )) {
+    for (const attribute of [...app.attributes]) {
+      if (
+        attribute.name !== APP_COMPONENT_ROOT_ATTRIBUTE &&
+        attribute.name !== "data-component"
+      ) {
+        app.removeAttribute(attribute.name)
+      }
+    }
+    app.replaceChildren()
+  }
+  return clone
+}
+
+function sameShell(current: HTMLElement, incoming: HTMLElement) {
+  const currentShell = shellClone(current)
+  const incomingShell = shellClone(incoming)
+  return Boolean(
+    currentShell && incomingShell && currentShell.isEqualNode(incomingShell),
+  )
+}
+
+function renderDiff(
+  current: HTMLElement,
+  incoming: HTMLElement,
+  type: RenderType,
+): Pick<RenderDetail, "blocks" | "scope"> {
+  const currentBlocks = blocksIn(current)
+  const incomingBlocks = blocksIn(incoming)
+  const currentById = blockMap(currentBlocks)
+  const incomingById = blockMap(incomingBlocks)
+  if (!currentById || !incomingById) {
+    return { blocks: [], scope: "document" }
+  }
+
+  const changed = new Set<string>()
+  for (const [id, block] of currentById) {
+    const next = incomingById.get(id)
+    if (!next || !block.isEqualNode(next)) changed.add(id)
+  }
+  for (const id of incomingById.keys()) {
+    if (!currentById.has(id)) changed.add(id)
+  }
+
+  const currentShared = currentBlocks
+    .map((block) => block.id)
+    .filter((id) => incomingById.has(id))
+  const incomingShared = incomingBlocks
+    .map((block) => block.id)
+    .filter((id) => currentById.has(id))
+  const reordered = currentShared.some(
+    (id, index) => incomingShared[index] !== id,
+  )
+  const local =
+    (type === "action" || type === "live") &&
+    !reordered &&
+    sameShell(current, incoming)
+
+  return {
+    blocks: [...changed],
+    scope: local ? "blocks" : "document",
+  }
+}
+
+if (!(window.__pmxCanonicalView instanceof HTMLElement)) {
+  window.__pmxCanonicalView = currentView().cloneNode(true) as HTMLElement
+}
+
+function shouldAnimate(type: RenderType, viewTransition: boolean) {
+  return (
+    viewTransition &&
+    (type === "navigation" || type === "traverse") &&
+    typeof document.startViewTransition === "function" &&
+    !matchMedia("(prefers-reduced-motion: reduce)").matches
+  )
+}
+
+export async function readPathMXDocument(
+  response: Response,
+  requestedUrl: URL,
+): Promise<LoadedPathMXDocument> {
+  if (!response.ok) {
+    throw new PathMXDocumentError(
+      `PathMX document returned ${response.status}.`,
+    )
+  }
+  if (!response.headers.get("content-type")?.includes("text/html")) {
+    throw new PathMXDocumentError("PathMX navigation did not return HTML.")
+  }
+
+  const incoming = new DOMParser().parseFromString(
+    await response.text(),
+    "text/html",
+  )
+  if (incoming.documentElement.getAttribute("data-pmx-document") !== "1") {
+    throw new PathMXDocumentError("The response is not a PathMX document.")
+  }
+  const views = incoming.querySelectorAll("[data-pmx-view]")
+  if (views.length !== 1 || !(views[0] instanceof HTMLElement)) {
+    throw new PathMXDocumentError("The response has no canonical PathMX view.")
+  }
+  return {
+    document: incoming,
+    requestedUrl,
+    responseUrl: new URL(response.url || requestedUrl.href),
+    view: views[0],
+  }
+}
+
+export async function fetchPathMXDocument(
+  url: URL,
+  signal: AbortSignal,
+  cache: RequestCache = "default",
+) {
+  const response = await fetch(url, {
+    cache,
+    credentials: "same-origin",
+    headers: { Accept: "text/html" },
+    signal,
+  })
+  return readPathMXDocument(response, url)
+}
+
+export async function reconcilePathMXDocument(
+  incoming: LoadedPathMXDocument,
+  options: {
+    type: RenderType
+    from: URL
+    viewTransition: boolean
+    viewTransitionTypes?: readonly string[]
+  },
+) {
+  const viewTransitionTypes = options.viewTransitionTypes ?? []
+  const apply = () => {
+    const canonicalView = window.__pmxCanonicalView ?? currentView()
+    const diff = renderDiff(canonicalView, incoming.view, options.type)
+    const changedBlocks = new Set(diff.blocks)
+    const nextCanonicalView = incoming.view.cloneNode(true) as HTMLElement
+    reconcileHead(document.head, incoming.document.head, options.type)
+    reconcileHtmlAttributes(
+      document.documentElement,
+      incoming.document.documentElement,
+    )
+    morphdom(currentView(), incoming.view, {
+      onBeforeElUpdated(current, next) {
+        if (current.isEqualNode(next)) return false
+        if (
+          diff.scope === "blocks" &&
+          next.matches(blockSelector) &&
+          !changedBlocks.has(next.id)
+        ) {
+          return false
+        }
+        return true
+      },
+      onBeforeElChildrenUpdated(current) {
+        return !current.hasAttribute(APP_COMPONENT_ROOT_ATTRIBUTE)
+      },
+    })
+    window.__pmxCanonicalView = nextCanonicalView
+    document.dispatchEvent(
+      new CustomEvent<RenderDetail>("pmx:render", {
+        detail: {
+          type: options.type,
+          from: options.from.href,
+          to: incoming.requestedUrl.href,
+          viewTransitionTypes,
+          ...diff,
+        },
+      }),
+    )
+  }
+
+  if (!shouldAnimate(options.type, options.viewTransition)) {
+    apply()
+    return
+  }
+
+  let applied = false
+  const transition = startPathMXViewTransition(() => {
+    applied = true
+    apply()
+  }, viewTransitionTypes)
+  try {
+    await transition.updateCallbackDone
+  } catch (error) {
+    if (!applied) apply()
+    else throw error
+  }
+}

package/plugins/runtime/error.ts

@@ -0,0 +1,154 @@
+import type { ProblemDetails } from "../../problem.ts"
+
+export type ActionErrorDetail = {
+  type: "action"
+  outcome: "rejected" | "uncertain"
+  message: string
+  status?: number
+}
+
+export type RuntimeErrorDetail =
+  | ActionErrorDetail
+  | {
+      type: "navigation" | "traverse"
+      outcome: "native"
+      message: string
+    }
+  | {
+      type: "live"
+      outcome: "stale"
+      message: string
+    }
+
+type RenderedError = {
+  describedBy: string | null
+  region: HTMLElement
+}
+
+const rendered = new WeakMap<HTMLFormElement, RenderedError>()
+let nextErrorId = 0
+
+function isProblemDetails(value: unknown): value is ProblemDetails {
+  if (typeof value !== "object" || value == null) return false
+  const problem = value as Partial<ProblemDetails>
+  return (
+    problem.type === "about:blank" &&
+    typeof problem.title === "string" &&
+    typeof problem.status === "number" &&
+    typeof problem.detail === "string"
+  )
+}
+
+class ActionRejectedError extends Error {
+  constructor(
+    message: string,
+    readonly status: number,
+  ) {
+    super(message)
+    this.name = "ActionRejectedError"
+  }
+}
+
+export async function readActionRejection(response: Response) {
+  let message = `The server rejected this action (${response.status}).`
+  try {
+    const contentType = response.headers.get("content-type") ?? ""
+    if (contentType.includes("application/problem+json")) {
+      const problem: unknown = await response.json()
+      if (isProblemDetails(problem) && problem.status === response.status) {
+        message = problem.detail
+      }
+    } else if (contentType.includes("text/plain")) {
+      message = (await response.text()).trim() || message
+    }
+  } catch {
+    // The HTTP status remains authoritative when an error body is malformed.
+  }
+  return new ActionRejectedError(message, response.status)
+}
+
+export function describeActionError(error: unknown): ActionErrorDetail {
+  if (error instanceof ActionRejectedError) {
+    return {
+      type: "action",
+      outcome: "rejected",
+      message: error.message,
+      status: error.status,
+    }
+  }
+  return {
+    type: "action",
+    outcome: "uncertain",
+    message:
+      "The response was interrupted, so this action may have completed. Reload the page before trying again.",
+  }
+}
+
+export function reportRuntimeError(detail: RuntimeErrorDetail) {
+  document.dispatchEvent(
+    new CustomEvent<RuntimeErrorDetail>("pmx:error", { detail }),
+  )
+}
+
+export function clearActionError(form: HTMLFormElement) {
+  const current = rendered.get(form)
+  if (current) {
+    current.region.remove()
+    if (current.describedBy == null) form.removeAttribute("aria-describedby")
+    else form.setAttribute("aria-describedby", current.describedBy)
+    rendered.delete(form)
+  }
+  form.removeAttribute("data-pmx-failed")
+}
+
+function errorRegion(detail: ActionErrorDetail) {
+  const region = document.createElement("div")
+  region.id = `pmx-error-${++nextErrorId}`
+  region.className = "pmx-error"
+  region.setAttribute("data-pmx-error", detail.outcome)
+  if (detail.status != null) {
+    region.setAttribute("data-pmx-error-status", String(detail.status))
+  }
+  region.setAttribute("role", "alert")
+
+  const title = document.createElement("strong")
+  title.textContent =
+    detail.outcome === "rejected"
+      ? "Action failed."
+      : "Action status is uncertain."
+  const message = document.createElement("span")
+  message.textContent = ` ${detail.message}`
+  region.append(title, message)
+
+  if (detail.outcome === "uncertain") {
+    const reload = document.createElement("button")
+    reload.type = "button"
+    reload.textContent = "Reload page"
+    reload.addEventListener("click", () => location.reload())
+    region.append(reload)
+  }
+  return region
+}
+
+export function showActionError(
+  form: HTMLFormElement,
+  submitter: HTMLElement | null,
+  detail: ActionErrorDetail,
+) {
+  clearActionError(form)
+  const region = errorRegion(detail)
+  const describedBy = form.getAttribute("aria-describedby")
+  form.setAttribute(
+    "aria-describedby",
+    [describedBy, region.id].filter(Boolean).join(" "),
+  )
+  form.setAttribute("data-pmx-failed", detail.outcome)
+  if (form.isConnected) form.after(region)
+  else document.querySelector("[data-pmx-view]")?.prepend(region)
+  rendered.set(form, { describedBy, region })
+
+  if (detail.outcome === "uncertain") {
+    submitter?.setAttribute("aria-disabled", "true")
+  }
+  reportRuntimeError(detail)
+}

package/plugins/runtime/heading-links.ts

@@ -0,0 +1,31 @@
+const headingSelector =
+  ".pmx-heading > h1, .pmx-heading > h2, .pmx-heading > h3, .pmx-heading > h4, .pmx-heading > h5, .pmx-heading > h6"
+
+const interactiveSelector =
+  "a, button, input, select, textarea, summary, [role='button'], [role='link']"
+
+/** Make generated heading text activate its accessible sibling permalink. */
+export function installHeadingLinks() {
+  document.addEventListener("click", (event) => {
+    if (event.defaultPrevented || !(event.target instanceof Element)) return
+
+    const mouse = event as MouseEvent
+    if (
+      mouse.button !== 0 ||
+      mouse.metaKey ||
+      mouse.ctrlKey ||
+      mouse.shiftKey ||
+      mouse.altKey
+    )
+      return
+
+    const heading = event.target.closest<HTMLElement>(headingSelector)
+    if (!heading || event.target.closest(interactiveSelector)) return
+    const selection = getSelection()
+    if (selection && !selection.isCollapsed) return
+
+    heading.parentElement
+      ?.querySelector<HTMLAnchorElement>(":scope > .pmx-heading-anchor")
+      ?.click()
+  })
+}