@pathmx/core 0.5.0

package/plugins/datatype/index.ts

@@ -0,0 +1,287 @@
+import { escapeHtml } from "../../util.ts"
+import type { HtmlRewriteRule, HtmlStringRewrite } from "../../environment.ts"
+import type { AppContext, PageContext, Plugin } from "../types.ts"
+
+export type DatatypeChartType = "bar" | "sparkline" | "pie"
+
+export type DatatypeExpression = {
+  type: DatatypeChartType
+  code: "b" | "l" | "p"
+  values: number[]
+  canonical: string
+}
+
+export type DatatypePluginOptions = {
+  autoWrap?: boolean
+  className?: string
+  width?: number
+  weight?: number
+  preload?: boolean
+}
+
+const DEFAULT_OPTIONS = {
+  autoWrap: true,
+  className: "pmx-datatype",
+  width: 100,
+  weight: 400,
+  preload: true,
+} satisfies Required<DatatypePluginOptions>
+
+const CHART_TYPE_BY_CODE = {
+  b: "bar",
+  l: "sparkline",
+  p: "pie",
+} as const
+
+const EXPRESSION = /\{([blp]):([^{}\n]+)\}/g
+// Cheap pre-scan: EXPRESSION can only match where a literal `{b:`/`{l:`/`{p:`
+// appears, so pages without charts skip the HTML transform entirely.
+const EXPRESSION_HINT = /\{[blp]:/
+const FONT_URL = new URL("./Datatype[wdth,wght].woff2", import.meta.url)
+const LICENSE_URL = new URL("./OFL.txt", import.meta.url)
+const HTML_ROOT = "pmx-datatype-root"
+const HTML_ROOT_OPEN = `<${HTML_ROOT}>`
+const HTML_ROOT_CLOSE = `</${HTML_ROOT}>`
+const PROTECTED_ELEMENTS = ["code", "pre", "script", "style", "textarea"]
+
+function clampAxis(value: number, min: number, max: number, fallback: number) {
+  if (!Number.isFinite(value)) return fallback
+  return Math.min(max, Math.max(min, value))
+}
+
+function normalizeClassName(value: string | undefined) {
+  const className = value?.trim()
+  return className || DEFAULT_OPTIONS.className
+}
+
+function escapeCssString(value: string) {
+  return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')
+}
+
+function escapeCssClass(value: string) {
+  return value
+    .split(/\s+/)
+    .filter(Boolean)
+    .map((part) =>
+      part.replace(
+        /[^a-zA-Z0-9_-]/g,
+        (char) => `\\${char.codePointAt(0)!.toString(16)} `,
+      ),
+    )
+    .map((part) => `.${part}`)
+    .join("")
+}
+
+function describeExpression(expression: DatatypeExpression) {
+  const values = expression.values.join(", ")
+  if (expression.type === "bar") return `Bar chart values ${values}`
+  if (expression.type === "sparkline") {
+    return `Sparkline values ${values}`
+  }
+  return `Pie chart value ${values}`
+}
+
+function renderSpan(expression: DatatypeExpression, className: string) {
+  return `<span class="${escapeHtml(className)}" data-pathmx-datatype="${expression.type}" role="img" aria-label="${escapeHtml(describeExpression(expression))}">${expression.canonical}</span>`
+}
+
+export function parseDatatypeExpression(
+  input: string,
+): DatatypeExpression | null {
+  const match = input.match(/^\{([blp]):([^{}\n]+)\}$/)
+  if (!match) return null
+
+  const code = match[1] as DatatypeExpression["code"]
+  const rawValues = match[2]!.split(",").map((value) => value.trim())
+  if (!rawValues.length || rawValues.some((value) => !value)) return null
+  if (code === "p" && rawValues.length !== 1) return null
+  if (code !== "p" && rawValues.length > 20) return null
+
+  const values = rawValues.map((value) =>
+    /^\d+$/.test(value) ? Number(value) : Number.NaN,
+  )
+  if (
+    values.some((value) => !Number.isInteger(value) || value < 0 || value > 100)
+  ) {
+    return null
+  }
+
+  return {
+    type: CHART_TYPE_BY_CODE[code],
+    code,
+    values,
+    canonical: `{${code}:${values.join(",")}}`,
+  }
+}
+
+function transformText(text: string, className: string) {
+  // Runtime text chunks are already serialized for HTML insertion.
+  // Preserve their entities verbatim and escape only markup we introduce.
+  return text.replace(EXPRESSION, (match) => {
+    const expression = parseDatatypeExpression(match)
+    return expression ? renderSpan(expression, className) : match
+  })
+}
+
+export function transformDatatypeHtml(
+  html: string,
+  rewriteHtml: HtmlStringRewrite,
+  options: Pick<DatatypePluginOptions, "className"> = {},
+) {
+  if (!EXPRESSION_HINT.test(html)) return html
+  const className = normalizeClassName(options.className)
+  let protectedDepth = 0
+  let text = ""
+  const rules: HtmlRewriteRule[] = []
+
+  for (const tag of PROTECTED_ELEMENTS) {
+    rules.push([
+      tag,
+      {
+        element(element) {
+          protectedDepth++
+          element.onEndTag(() => {
+            protectedDepth--
+          })
+        },
+      },
+    ])
+  }
+
+  rules.push([
+    HTML_ROOT,
+    {
+      text(chunk) {
+        if (protectedDepth) return
+        text += chunk.text
+        chunk.remove()
+        if (!chunk.lastInTextNode) return
+        chunk.after(transformText(text, className), { html: true })
+        text = ""
+      },
+    },
+  ])
+
+  const output = rewriteHtml(
+    `${HTML_ROOT_OPEN}${html}${HTML_ROOT_CLOSE}`,
+    rules,
+  )
+  return output.slice(HTML_ROOT_OPEN.length, -HTML_ROOT_CLOSE.length)
+}
+
+function buildCss(
+  className: string,
+  fontHref: string,
+  licenseHref: string,
+  width: number,
+  weight: number,
+) {
+  const selector = escapeCssClass(className)
+  return `/* Datatype font license: ${escapeCssString(licenseHref)} */
+@font-face {
+  font-family: "PathMX Datatype";
+  src: url("${escapeCssString(fontHref)}") format("woff2-variations");
+  font-weight: 100 900;
+  font-stretch: 50% 150%;
+  font-display: swap;
+}
+
+${selector} {
+  font-family: "PathMX Datatype", "IBM Plex Mono", monospace;
+  font-variant-ligatures: common-ligatures contextual discretionary-ligatures;
+  font-feature-settings: "liga" 1, "calt" 1;
+  font-weight: ${weight};
+  font-stretch: ${width}%;
+  letter-spacing: 0;
+  line-height: 1;
+  white-space: nowrap;
+  display: inline-block;
+  vertical-align: -0.08em;
+}
+`
+}
+
+type PublishedAssets = {
+  fontHref: string
+  licenseHref: string
+}
+
+async function publishAssets(app: AppContext): Promise<PublishedAssets> {
+  const [font, license] = await Promise.all([
+    app.assets.load(FONT_URL),
+    app.assets.load(LICENSE_URL),
+  ])
+  const [fontHref, licenseHref] = await Promise.all([
+    app.assets.publish("datatype-font.woff2", font, "font/woff2"),
+    app.assets.publish(
+      "datatype-OFL.txt",
+      license,
+      "text/plain; charset=utf-8",
+    ),
+  ])
+  return { fontHref, licenseHref }
+}
+
+function addAssets(
+  ctx: PageContext,
+  options: Required<DatatypePluginOptions>,
+  assets: PublishedAssets,
+) {
+  ctx.addAsset({
+    type: "stylesheet",
+    name: "datatype.css",
+    text: buildCss(
+      options.className,
+      assets.fontHref,
+      assets.licenseHref,
+      options.width,
+      options.weight,
+    ),
+  })
+  if (options.preload) {
+    ctx.addAsset({
+      type: "preload",
+      href: assets.fontHref,
+      as: "font",
+      contentType: "font/woff2",
+      crossorigin: true,
+    })
+  }
+}
+
+export function DatatypePlugin(
+  pluginOptions: DatatypePluginOptions = {},
+): Plugin {
+  const options: Required<DatatypePluginOptions> = {
+    autoWrap: pluginOptions.autoWrap ?? DEFAULT_OPTIONS.autoWrap,
+    className: normalizeClassName(pluginOptions.className),
+    width: clampAxis(
+      pluginOptions.width ?? DEFAULT_OPTIONS.width,
+      50,
+      150,
+      DEFAULT_OPTIONS.width,
+    ),
+    weight: clampAxis(
+      pluginOptions.weight ?? DEFAULT_OPTIONS.weight,
+      100,
+      900,
+      DEFAULT_OPTIONS.weight,
+    ),
+    preload: pluginOptions.preload ?? DEFAULT_OPTIONS.preload,
+  }
+  let published: Promise<PublishedAssets> | undefined
+
+  return {
+    id: "datatype",
+    postcompile(html, _ctx, app) {
+      if (!options.autoWrap || !EXPRESSION_HINT.test(html)) return html
+      return transformDatatypeHtml(html, app.html.rewrite, options)
+    },
+    async page(html, ctx, app) {
+      if (!html.includes("data-pathmx-datatype")) return html
+      published ??= publishAssets(app)
+      addAssets(ctx, options, await published)
+      return html
+    },
+  }
+}

package/plugins/definition-list.ts

@@ -0,0 +1,236 @@
+import { isFenceClose, matchFenceOpen } from "../source/index.ts"
+import type { CompileContext, Plugin } from "./types.ts"
+
+type DefinitionItem = {
+  term: string
+  definitions: string[]
+}
+
+type ParsedDefinitionList = {
+  items: DefinitionItem[]
+  nextIndex: number
+}
+
+const DEFINITION = /^ {0,3}:[ \t]+(.*)$/
+const DEFINITION_CANDIDATE = /(?:^|\n) {0,3}:[ \t]+/
+const PART = /<div data-pmx-definition-list="\d+:(term|definition)"><\/div>\n?/g
+
+function isBlank(line: string | undefined) {
+  return !line?.trim()
+}
+
+function definition(line: string | undefined) {
+  return line?.match(DEFINITION)?.[1]
+}
+
+function isTerm(line: string | undefined) {
+  if (!line || isBlank(line) || /^(?: {4}|\t)/.test(line)) return false
+  const value = line.trimStart()
+  return !(
+    definition(line) !== undefined ||
+    matchFenceOpen(line) ||
+    /^(?:#{1,6}(?:[ \t]+|$)|>|[-+*][ \t]+|\d{1,9}[.)][ \t]+)/.test(value) ||
+    /^(?:[-*_][ \t]*){3,}$/.test(value)
+  )
+}
+
+function definitionIndex(lines: string[], termIndex: number) {
+  if (!isTerm(lines[termIndex])) return
+  let index = termIndex + 1
+  if (isBlank(lines[index])) index++
+  if (definition(lines[index]) === undefined) return
+  return index
+}
+
+function unindentDefinitionLine(line: string) {
+  if (line.startsWith("\t")) return line.slice(1)
+  if (line.startsWith("    ")) return line.slice(4)
+  return line
+}
+
+function parseDefinition(lines: string[], markerIndex: number) {
+  const content = [definition(lines[markerIndex]) ?? ""]
+  let index = markerIndex + 1
+
+  while (index < lines.length) {
+    if (definition(lines[index]) !== undefined) break
+
+    if (!isBlank(lines[index])) {
+      content.push(unindentDefinitionLine(lines[index]!))
+      index++
+      continue
+    }
+
+    let next = index
+    while (next < lines.length && isBlank(lines[next])) next++
+    if (definition(lines[next]) !== undefined) {
+      index = next
+      break
+    }
+    if (/^(?: {4}|\t)/.test(lines[next] ?? "")) {
+      content.push(...lines.slice(index, next).map(() => ""))
+      index = next
+      continue
+    }
+    break
+  }
+
+  return { markdown: content.join("\n").trimEnd(), nextIndex: index }
+}
+
+function parseItem(lines: string[], termIndex: number) {
+  const firstDefinition = definitionIndex(lines, termIndex)
+  if (firstDefinition === undefined) return
+
+  const definitions: string[] = []
+  let index = firstDefinition
+  while (definition(lines[index]) !== undefined) {
+    const parsed = parseDefinition(lines, index)
+    definitions.push(parsed.markdown)
+    index = parsed.nextIndex
+  }
+
+  return {
+    item: { term: lines[termIndex]!.trim(), definitions },
+    nextIndex: index,
+  }
+}
+
+function parseDefinitionList(lines: string[], start: number) {
+  const items: DefinitionItem[] = []
+  let index = start
+
+  while (true) {
+    const parsed = parseItem(lines, index)
+    if (!parsed) break
+    items.push(parsed.item)
+    index = parsed.nextIndex
+
+    let next = index
+    while (next < lines.length && isBlank(lines[next])) next++
+    if (next === index || definitionIndex(lines, next) === undefined) break
+    index = next
+  }
+
+  if (!items.length) return
+  return { items, nextIndex: index } satisfies ParsedDefinitionList
+}
+
+function marker(index: number, type: "start" | "term" | "definition" | "end") {
+  return `<div data-pmx-definition-list="${index}:${type}"></div>`
+}
+
+function serialize(list: ParsedDefinitionList, index: number) {
+  const output = [marker(index, "start")]
+  for (const item of list.items) {
+    output.push("", marker(index, "term"), "", item.term)
+    for (const value of item.definitions) {
+      output.push("", marker(index, "definition"), "", value)
+    }
+  }
+  output.push("", marker(index, "end"))
+  return output.join("\n")
+}
+
+function transform(markdown: string) {
+  const lines = markdown.split(/\r?\n/)
+  const output: string[] = []
+  let listCount = 0
+  let fence: string | undefined
+
+  for (let index = 0; index < lines.length;) {
+    const line = lines[index] ?? ""
+    if (fence) {
+      output.push(line)
+      if (isFenceClose(line, fence)) fence = undefined
+      index++
+      continue
+    }
+
+    const open = matchFenceOpen(line)
+    if (open) {
+      output.push(line)
+      fence = open.marker
+      index++
+      continue
+    }
+
+    const list = parseDefinitionList(lines, index)
+    if (!list) {
+      output.push(line)
+      index++
+      continue
+    }
+
+    output.push(serialize(list, listCount++))
+    index = list.nextIndex
+  }
+
+  return { markdown: output.join("\n"), listCount }
+}
+
+function unwrapParagraph(html: string) {
+  const value = html.trim()
+  if (!value.startsWith("<p>") || !value.endsWith("</p>")) return value
+  const inner = value.slice(3, -4)
+  return inner.includes("</p>") ? value : inner
+}
+
+function renderList(body: string) {
+  const parts: { type: "term" | "definition"; html: string }[] = []
+  let type: "term" | "definition" | undefined
+  let cursor = 0
+
+  for (const match of body.matchAll(PART)) {
+    if (type) {
+      parts.push({ type, html: body.slice(cursor, match.index) })
+    }
+    type = match[1] as "term" | "definition"
+    cursor = match.index! + match[0].length
+  }
+  if (type) parts.push({ type, html: body.slice(cursor) })
+
+  const content = parts
+    .map((part) => {
+      const tag = part.type === "term" ? "dt" : "dd"
+      return `<${tag}>${unwrapParagraph(part.html)}</${tag}>`
+    })
+    .join("\n")
+  return `<dl>\n${content}\n</dl>`
+}
+
+function restore(html: string, listCount: number) {
+  for (let index = 0; index < listCount; index++) {
+    const start = marker(index, "start")
+    const end = marker(index, "end")
+    const from = html.indexOf(start)
+    const to = html.indexOf(end, from + start.length)
+    if (from === -1 || to === -1) continue
+    const body = html.slice(from + start.length, to)
+    html = html.slice(0, from) + renderList(body) + html.slice(to + end.length)
+  }
+  return html
+}
+
+/** Markdown Extra / GitLab-style `Term` + `: definition` lists. */
+export function DefinitionListPlugin(): Plugin {
+  const listCountByContext = new WeakMap<CompileContext, number>()
+
+  return {
+    id: "definition-list",
+    precompile(markdown, ctx) {
+      if (!DEFINITION_CANDIDATE.test(markdown)) {
+        listCountByContext.set(ctx, 0)
+        return markdown
+      }
+      const parsed = transform(markdown)
+      listCountByContext.set(ctx, parsed.listCount)
+      return parsed.markdown
+    },
+    postcompile(html, ctx) {
+      const listCount = listCountByContext.get(ctx) ?? 0
+      listCountByContext.delete(ctx)
+      return listCount ? restore(html, listCount) : html
+    },
+  }
+}

package/plugins/directive-definitions.ts

@@ -0,0 +1,13 @@
+function escapeRegex(value: string) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+}
+
+/** Match one authored directive reference definition, including its newline. */
+export function directiveDefinition(name: string, href: string) {
+  const directive = escapeRegex(name)
+  const dest = escapeRegex(href)
+  return new RegExp(
+    `^[ \\t]{0,3}\\[@${directive}[^\\]]*\\]:[ \\t]+(?:<${dest}>|${dest})(?:[ \\t]+(?:"[^"]*"|'[^']*'|\\([^)]*\\)))?[ \\t]*\\n?`,
+    "gm",
+  )
+}

package/plugins/embedding/client.ts

@@ -0,0 +1,88 @@
+type ExternalLinkPolicy = "new-tab" | "parent" | "frame"
+
+const descriptionId = "pmx-new-tab-description"
+const defaultTargetAttribute = "data-pmx-default-target"
+
+function addToken(value: string, token: string) {
+  const tokens = value.split(/\s+/).filter(Boolean)
+  if (!tokens.includes(token)) tokens.push(token)
+  return tokens.join(" ")
+}
+
+function removeToken(value: string, token: string) {
+  return value
+    .split(/\s+/)
+    .filter((value) => value && value !== token)
+    .join(" ")
+}
+
+function markNewTab(link: HTMLAnchorElement) {
+  link.classList.add("pmx-link-new-tab")
+  link.rel = addToken(link.rel, "noopener")
+  link.setAttribute(
+    "aria-describedby",
+    addToken(link.getAttribute("aria-describedby") ?? "", descriptionId),
+  )
+}
+
+function unmarkNewTab(link: HTMLAnchorElement) {
+  link.classList.remove("pmx-link-new-tab")
+  const describedBy = removeToken(
+    link.getAttribute("aria-describedby") ?? "",
+    descriptionId,
+  )
+  if (describedBy) link.setAttribute("aria-describedby", describedBy)
+  else link.removeAttribute("aria-describedby")
+}
+
+if (window.self !== window.top) {
+  const root = document.documentElement
+  const basePath = root.dataset.pmxBase || "/"
+  const configured = root.dataset.pmxEmbeddingExternalLinks
+  const policy: ExternalLinkPolicy =
+    configured === "parent" || configured === "frame" ? configured : "new-tab"
+
+  const insidePublication = (target: URL) =>
+    target.origin === location.origin &&
+    (basePath === "/" ||
+      target.pathname === basePath ||
+      target.pathname.startsWith(`${basePath}/`))
+
+  const prepareExternalLinks = () => {
+    root.setAttribute("data-pmx-embedded", "")
+    for (const link of document.querySelectorAll<HTMLAnchorElement>(
+      "a[href]",
+    )) {
+      const target = new URL(link.href, location.href)
+      if (
+        (target.protocol !== "http:" && target.protocol !== "https:") ||
+        link.hasAttribute("download")
+      ) {
+        continue
+      }
+      const defaulted = link.hasAttribute(defaultTargetAttribute)
+      if (insidePublication(target)) {
+        if (defaulted) {
+          link.removeAttribute("target")
+          link.removeAttribute(defaultTargetAttribute)
+          unmarkNewTab(link)
+        }
+        continue
+      }
+      if (link.hasAttribute("target") && !defaulted) continue
+      if (policy === "frame") {
+        link.target = "_self"
+        link.setAttribute(defaultTargetAttribute, policy)
+        unmarkNewTab(link)
+        continue
+      }
+      link.target = policy === "parent" ? "_parent" : "_blank"
+      link.setAttribute(defaultTargetAttribute, policy)
+      if (policy === "new-tab") markNewTab(link)
+      else unmarkNewTab(link)
+    }
+  }
+
+  prepareExternalLinks()
+  document.addEventListener("pmx:render", prepareExternalLinks)
+}

package/plugins/embedding/index.ts

@@ -0,0 +1,43 @@
+import type { Plugin } from "../types.ts"
+
+const clientEntry = new URL("./client.ts", import.meta.url)
+
+export type EmbeddingExternalLinks = "new-tab" | "parent" | "frame"
+
+export type EmbeddingPluginOptions = Readonly<{
+  /** How links outside the mounted PathMX publication behave inside an iframe. */
+  externalLinks?: EmbeddingExternalLinks
+}>
+
+const externalLinkPolicies = new Set<EmbeddingExternalLinks>([
+  "new-tab",
+  "parent",
+  "frame",
+])
+
+/** Make a PathMX publication behave predictably when framed beside another app. */
+export function EmbeddingPlugin(options: EmbeddingPluginOptions = {}): Plugin {
+  const externalLinks = options.externalLinks ?? "new-tab"
+  if (!externalLinkPolicies.has(externalLinks)) {
+    throw new Error(`Invalid embedded external-link policy: ${externalLinks}`)
+  }
+  return {
+    id: "embedding",
+    name: "EmbeddingPlugin",
+    async documentAssets(ctx) {
+      await ctx.addBrowserBundle(clientEntry, "embedding")
+    },
+    streamSelectors() {
+      return {
+        html: {
+          element(element) {
+            element.setAttribute(
+              "data-pmx-embedding-external-links",
+              externalLinks,
+            )
+          },
+        },
+      }
+    },
+  }
+}