feat(version): versions

4 files changed, 594 insertions, 0 deletions

diff --git a/src/templates/assets/javascripts/components/content/annotation/_/index.ts b/src/templates/assets/javascripts/components/content/annotation/_/index.ts
new file mode 100644
index 00000000..c5138fa4
--- /dev/null
+++ b/src/templates/assets/javascripts/components/content/annotation/_/index.ts
@@ -0,0 +1,272 @@
+/*
+ * Copyright (c) 2016-2023 Martin Donath <martin.donath@squidfunk.com>
+ *
+ * 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 NON-INFRINGEMENT. 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.
+ */
+
+import {
+  Observable,
+  Subject,
+  animationFrameScheduler,
+  auditTime,
+  combineLatest,
+  debounceTime,
+  defer,
+  delay,
+  endWith,
+  filter,
+  finalize,
+  fromEvent,
+  ignoreElements,
+  map,
+  merge,
+  switchMap,
+  take,
+  takeUntil,
+  tap,
+  throttleTime,
+  withLatestFrom
+} from "rxjs"
+
+import {
+  ElementOffset,
+  getActiveElement,
+  getElementSize,
+  watchElementContentOffset,
+  watchElementFocus,
+  watchElementOffset,
+  watchElementVisibility
+} from "~/browser"
+
+import { Component } from "../../../_"
+
+/* ----------------------------------------------------------------------------
+ * Types
+ * ------------------------------------------------------------------------- */
+
+/**
+ * Annotation
+ */
+export interface Annotation {
+  active: boolean                      /* Annotation is active */
+  offset: ElementOffset                /* Annotation offset */
+}
+
+/* ----------------------------------------------------------------------------
+ * Helper types
+ * ------------------------------------------------------------------------- */
+
+/**
+ * Mount options
+ */
+interface MountOptions {
+  target$: Observable<HTMLElement>     /* Location target observable */
+}
+
+/* ----------------------------------------------------------------------------
+ * Functions
+ * ------------------------------------------------------------------------- */
+
+/**
+ * Watch annotation
+ *
+ * @param el - Annotation element
+ * @param container - Containing element
+ *
+ * @returns Annotation observable
+ */
+export function watchAnnotation(
+  el: HTMLElement, container: HTMLElement
+): Observable<Annotation> {
+  const offset$ = defer(() => combineLatest([
+    watchElementOffset(el),
+    watchElementContentOffset(container)
+  ]))
+    .pipe(
+      map(([{ x, y }, scroll]): ElementOffset => {
+        const { width, height } = getElementSize(el)
+        return ({
+          x: x - scroll.x + width  / 2,
+          y: y - scroll.y + height / 2
+        })
+      })
+    )
+
+  /* Actively watch annotation on focus */
+  return watchElementFocus(el)
+    .pipe(
+      switchMap(active => offset$
+        .pipe(
+          map(offset => ({ active, offset })),
+          take(+!active || Infinity)
+        )
+      )
+    )
+}
+
+/**
+ * Mount annotation
+ *
+ * @param el - Annotation element
+ * @param container - Containing element
+ * @param options - Options
+ *
+ * @returns Annotation component observable
+ */
+export function mountAnnotation(
+  el: HTMLElement, container: HTMLElement, { target$ }: MountOptions
+): Observable<Component<Annotation>> {
+  const [tooltip, index] = Array.from(el.children)
+
+  /* Mount component on subscription */
+  return defer(() => {
+    const push$ = new Subject<Annotation>()
+    const done$ = push$.pipe(ignoreElements(), endWith(true))
+    push$.subscribe({
+
+      /* Handle emission */
+      next({ offset }) {
+        el.style.setProperty("--md-tooltip-x", `${offset.x}px`)
+        el.style.setProperty("--md-tooltip-y", `${offset.y}px`)
+      },
+
+      /* Handle complete */
+      complete() {
+        el.style.removeProperty("--md-tooltip-x")
+        el.style.removeProperty("--md-tooltip-y")
+      }
+    })
+
+    /* Start animation only when annotation is visible */
+    watchElementVisibility(el)
+      .pipe(
+        takeUntil(done$)
+      )
+        .subscribe(visible => {
+          el.toggleAttribute("data-md-visible", visible)
+        })
+
+    /* Toggle tooltip presence to mitigate empty lines when copying */
+    merge(
+      push$.pipe(filter(({ active }) => active)),
+      push$.pipe(debounceTime(250), filter(({ active }) => !active))
+    )
+      .subscribe({
+
+        /* Handle emission */
+        next({ active }) {
+          if (active)
+            el.prepend(tooltip)
+          else
+            tooltip.remove()
+        },
+
+        /* Handle complete */
+        complete() {
+          el.prepend(tooltip)
+        }
+      })
+
+    /* Toggle tooltip visibility */
+    push$
+      .pipe(
+        auditTime(16, animationFrameScheduler)
+      )
+        .subscribe(({ active }) => {
+          tooltip.classList.toggle("md-tooltip--active", active)
+        })
+
+    /* Track relative origin of tooltip */
+    push$
+      .pipe(
+        throttleTime(125, animationFrameScheduler),
+        filter(() => !!el.offsetParent),
+        map(() => el.offsetParent!.getBoundingClientRect()),
+        map(({ x }) => x)
+      )
+        .subscribe({
+
+          /* Handle emission */
+          next(origin) {
+            if (origin)
+              el.style.setProperty("--md-tooltip-0", `${-origin}px`)
+            else
+              el.style.removeProperty("--md-tooltip-0")
+          },
+
+          /* Handle complete */
+          complete() {
+            el.style.removeProperty("--md-tooltip-0")
+          }
+        })
+
+    /* Allow to copy link without scrolling to anchor */
+    fromEvent<MouseEvent>(index, "click")
+      .pipe(
+        takeUntil(done$),
+        filter(ev => !(ev.metaKey || ev.ctrlKey))
+      )
+        .subscribe(ev => {
+          ev.stopPropagation()
+          ev.preventDefault()
+        })
+
+    /* Allow to open link in new tab or blur on close */
+    fromEvent<MouseEvent>(index, "mousedown")
+      .pipe(
+        takeUntil(done$),
+        withLatestFrom(push$)
+      )
+        .subscribe(([ev, { active }]) => {
+
+          /* Open in new tab */
+          if (ev.button !== 0 || ev.metaKey || ev.ctrlKey) {
+            ev.preventDefault()
+
+          /* Close annotation */
+          } else if (active) {
+            ev.preventDefault()
+
+            /* Focus parent annotation, if any */
+            const parent = el.parentElement!.closest(".md-annotation")
+            if (parent instanceof HTMLElement)
+              parent.focus()
+            else
+              getActiveElement()?.blur()
+          }
+        })
+
+    /* Open and focus annotation on location target */
+    target$
+      .pipe(
+        takeUntil(done$),
+        filter(target => target === tooltip),
+        delay(125)
+      )
+        .subscribe(() => el.focus())
+
+    /* Create and return component */
+    return watchAnnotation(el, container)
+      .pipe(
+        tap(state => push$.next(state)),
+        finalize(() => push$.complete()),
+        map(state => ({ ref: el, ...state }))
+      )
+  })
+}
diff --git a/src/templates/assets/javascripts/components/content/annotation/block/index.ts b/src/templates/assets/javascripts/components/content/annotation/block/index.ts
new file mode 100644
index 00000000..c73b01fa
--- /dev/null
+++ b/src/templates/assets/javascripts/components/content/annotation/block/index.ts
@@ -0,0 +1,88 @@
+/*
+ * Copyright (c) 2016-2023 Martin Donath <martin.donath@squidfunk.com>
+ *
+ * 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 NON-INFRINGEMENT. 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.
+ */
+
+import { EMPTY, Observable, defer } from "rxjs"
+
+import { Component } from "../../../_"
+import { Annotation } from "../_"
+import { mountAnnotationList } from "../list"
+
+/* ----------------------------------------------------------------------------
+ * Helper types
+ * ------------------------------------------------------------------------- */
+
+/**
+ * Mount options
+ */
+interface MountOptions {
+  target$: Observable<HTMLElement>     /* Location target observable */
+  print$: Observable<boolean>          /* Media print observable */
+}
+
+/* ----------------------------------------------------------------------------
+ * Helper functions
+ * ------------------------------------------------------------------------- */
+
+/**
+ * Find list element directly following a block
+ *
+ * @param el - Annotation block element
+ *
+ * @returns List element or nothing
+ */
+function findList(el: HTMLElement): HTMLElement | undefined {
+  if (el.nextElementSibling) {
+    const sibling = el.nextElementSibling as HTMLElement
+    if (sibling.tagName === "OL")
+      return sibling
+
+    /* Skip empty paragraphs - see https://bit.ly/3r4ZJ2O */
+    else if (sibling.tagName === "P" && !sibling.children.length)
+      return findList(sibling)
+  }
+
+  /* Everything else */
+  return undefined
+}
+
+/* ----------------------------------------------------------------------------
+ * Functions
+ * ------------------------------------------------------------------------- */
+
+/**
+ * Mount annotation block
+ *
+ * @param el - Annotation block element
+ * @param options - Options
+ *
+ * @returns Annotation component observable
+ */
+export function mountAnnotationBlock(
+  el: HTMLElement, options: MountOptions
+): Observable<Component<Annotation>> {
+  return defer(() => {
+    const list = findList(el)
+    return typeof list !== "undefined"
+      ? mountAnnotationList(list, el, options)
+      : EMPTY
+  })
+}
diff --git a/src/templates/assets/javascripts/components/content/annotation/index.ts b/src/templates/assets/javascripts/components/content/annotation/index.ts
new file mode 100644
index 00000000..c593b723
--- /dev/null
+++ b/src/templates/assets/javascripts/components/content/annotation/index.ts
@@ -0,0 +1,25 @@
+/*
+ * Copyright (c) 2016-2023 Martin Donath <martin.donath@squidfunk.com>
+ *
+ * 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 NON-INFRINGEMENT. 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.
+ */
+
+export * from "./_"
+export * from "./block"
+export * from "./list"
diff --git a/src/templates/assets/javascripts/components/content/annotation/list/index.ts b/src/templates/assets/javascripts/components/content/annotation/list/index.ts
new file mode 100644
index 00000000..725dd583
--- /dev/null
+++ b/src/templates/assets/javascripts/components/content/annotation/list/index.ts
@@ -0,0 +1,209 @@
+/*
+ * Copyright (c) 2016-2023 Martin Donath <martin.donath@squidfunk.com>
+ *
+ * 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 NON-INFRINGEMENT. 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.
+ */
+
+import {
+  EMPTY,
+  Observable,
+  Subject,
+  defer,
+  endWith,
+  finalize,
+  ignoreElements,
+  merge,
+  share,
+  takeUntil
+} from "rxjs"
+
+import {
+  getElement,
+  getElements,
+  getOptionalElement
+} from "~/browser"
+import { renderAnnotation } from "~/templates"
+
+import { Component } from "../../../_"
+import {
+  Annotation,
+  mountAnnotation
+} from "../_"
+
+/* ----------------------------------------------------------------------------
+ * Helper types
+ * ------------------------------------------------------------------------- */
+
+/**
+ * Mount options
+ */
+interface MountOptions {
+  target$: Observable<HTMLElement>     /* Location target observable */
+  print$: Observable<boolean>          /* Media print observable */
+}
+
+/* ----------------------------------------------------------------------------
+ * Helper functions
+ * ------------------------------------------------------------------------- */
+
+/**
+ * Find all annotation hosts in the containing element
+ *
+ * @param container - Containing element
+ *
+ * @returns Annotation hosts
+ */
+function findHosts(container: HTMLElement): HTMLElement[] {
+  return container.tagName === "CODE"
+    ? getElements(".c, .c1, .cm", container)
+    : [container]
+}
+
+/**
+ * Find all annotation markers in the containing element
+ *
+ * @param container - Containing element
+ *
+ * @returns Annotation markers
+ */
+function findMarkers(container: HTMLElement): Text[] {
+  const markers: Text[] = []
+  for (const el of findHosts(container)) {
+    const nodes: Text[] = []
+
+    /* Find all text nodes in current element */
+    const it = document.createNodeIterator(el, NodeFilter.SHOW_TEXT)
+    for (let node = it.nextNode(); node; node = it.nextNode())
+      nodes.push(node as Text)
+
+    /* Find all markers in each text node */
+    for (let text of nodes) {
+      let match: RegExpExecArray | null
+
+      /* Split text at marker and add to list */
+      while ((match = /(\(\d+\))(!)?/.exec(text.textContent!))) {
+        const [, id, force] = match
+        if (typeof force === "undefined") {
+          const marker = text.splitText(match.index)
+          text = marker.splitText(id.length)
+          markers.push(marker)
+
+        /* Replace entire text with marker */
+        } else {
+          text.textContent = id
+          markers.push(text)
+          break
+        }
+      }
+    }
+  }
+  return markers
+}
+
+/**
+ * Swap the child nodes of two elements
+ *
+ * @param source - Source element
+ * @param target - Target element
+ */
+function swap(source: HTMLElement, target: HTMLElement): void {
+  target.append(...Array.from(source.childNodes))
+}
+
+/* ----------------------------------------------------------------------------
+ * Functions
+ * ------------------------------------------------------------------------- */
+
+/**
+ * Mount annotation list
+ *
+ * This function analyzes the containing code block and checks for markers
+ * referring to elements in the given annotation list. If no markers are found,
+ * the list is left untouched. Otherwise, list elements are rendered as
+ * annotations inside the code block.
+ *
+ * @param el - Annotation list element
+ * @param container - Containing element
+ * @param options - Options
+ *
+ * @returns Annotation component observable
+ */
+export function mountAnnotationList(
+  el: HTMLElement, container: HTMLElement, { target$, print$ }: MountOptions
+): Observable<Component<Annotation>> {
+
+  /* Compute prefix for tooltip anchors */
+  const parent = container.closest("[id]")
+  const prefix = parent?.id
+
+  /* Find and replace all markers with empty annotations */
+  const annotations = new Map<string, HTMLElement>()
+  for (const marker of findMarkers(container)) {
+    const [, id] = marker.textContent!.match(/\((\d+)\)/)!
+    if (getOptionalElement(`:scope > li:nth-child(${id})`, el)) {
+      annotations.set(id, renderAnnotation(id, prefix))
+      marker.replaceWith(annotations.get(id)!)
+    }
+  }
+
+  /* Keep list if there are no annotations to render */
+  if (annotations.size === 0)
+    return EMPTY
+
+  /* Mount component on subscription */
+  return defer(() => {
+    const push$ = new Subject()
+    const done$ = push$.pipe(ignoreElements(), endWith(true))
+
+    /* Retrieve container pairs for swapping */
+    const pairs: [HTMLElement, HTMLElement][] = []
+    for (const [id, annotation] of annotations)
+      pairs.push([
+        getElement(".md-typeset", annotation),
+        getElement(`:scope > li:nth-child(${id})`, el)
+      ])
+
+    /* Handle print mode - see https://bit.ly/3rgPdpt */
+    print$.pipe(takeUntil(done$))
+      .subscribe(active => {
+        el.hidden = !active
+
+        /* Add class to discern list element */
+        el.classList.toggle("md-annotation-list", active)
+
+        /* Show annotations in code block or list (print) */
+        for (const [inner, child] of pairs)
+          if (!active)
+            swap(child, inner)
+          else
+            swap(inner, child)
+      })
+
+    /* Create and return component */
+    return merge(...[...annotations]
+      .map(([, annotation]) => (
+        mountAnnotation(annotation, container, { target$ })
+      ))
+    )
+      .pipe(
+        finalize(() => push$.complete()),
+        share()
+      )
+  })
+}