@pathmx/core 0.5.0

package/plugins/block-layout/index.ts

@@ -0,0 +1,78 @@
+import type { Plugin } from "../types.ts"
+import stylesheet from "./theme.css" with { type: "text" }
+
+const LAYOUT_ID = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
+
+function invalidLayout(blockPath: string, value: unknown) {
+  const rendered =
+    typeof value === "string" ? JSON.stringify(value) : typeof value
+  return `Invalid Block layout on ${blockPath}: expected a lowercase slug, received ${rendered}.`
+}
+
+/** Compile reusable Block composition independently of any viewing mode. */
+export function BlockLayoutPlugin(): Plugin {
+  const layouts = new Map<string, string>()
+  const pathsBySource = new Map<string, readonly string[]>()
+
+  function removeSource(sourcePath: string) {
+    for (const blockPath of pathsBySource.get(sourcePath) ?? []) {
+      layouts.delete(blockPath)
+    }
+    pathsBySource.delete(sourcePath)
+  }
+
+  return {
+    id: "block-layout",
+
+    index(source, app) {
+      const next: Array<readonly [blockPath: string, layout: string]> = []
+      for (const block of source.blocks) {
+        const authored = block.data.layout
+        if (authored === undefined) continue
+        if (typeof authored === "string" && LAYOUT_ID.test(authored)) {
+          next.push([block.path, authored])
+          continue
+        }
+        app.diagnostics.invalid(source, invalidLayout(block.path, authored))
+      }
+      removeSource(source.path)
+      if (!next.length) return
+      pathsBySource.set(
+        source.path,
+        next.map(([blockPath]) => blockPath),
+      )
+      for (const [blockPath, layout] of next) layouts.set(blockPath, layout)
+    },
+
+    unindex(sourcePath) {
+      removeSource(sourcePath)
+    },
+
+    page(html, ctx, app) {
+      if (!layouts.size || !html.includes("data-pmx-block-path")) return html
+      let used = false
+      const output = app.html.rewrite(html, [
+        [
+          "section[data-pmx-block-path]",
+          {
+            element(block) {
+              const path = block.getAttribute("data-pmx-block-path")
+              const layout = path ? layouts.get(path) : undefined
+              if (!layout) return
+              used = true
+              block.setAttribute("data-pmx-block-layout", layout)
+            },
+          },
+        ],
+      ])
+      if (used) {
+        ctx.addAsset({
+          type: "stylesheet",
+          name: "block-layout.css",
+          text: stylesheet,
+        })
+      }
+      return output
+    },
+  }
+}

package/plugins/block-layout/theme.css

@@ -0,0 +1,90 @@
+.pmx-document [data-pmx-block-layout="center"] {
+  text-align: center;
+}
+
+.pmx-document
+  :is(
+    [data-pmx-block-layout="media-start"],
+    [data-pmx-block-layout="media-end"]
+  ) {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: clamp(var(--pmx-prose-flow), 4vw, calc(var(--pmx-prose-flow) * 2));
+  align-items: center;
+}
+
+.pmx-document
+  [data-pmx-block-layout="media-start"]
+  > :is(
+    figure,
+    picture,
+    img:not([data-pmx-image="background"]),
+    video,
+    iframe,
+    p:has(> img:not([data-pmx-image="background"]):only-child),
+    p:has(> picture:only-child),
+    p:has(> video:only-child),
+    p:has(> iframe:only-child)
+  ) {
+  grid-column: 1;
+  grid-row: 1 / span 100;
+}
+
+.pmx-document
+  [data-pmx-block-layout="media-start"]
+  > :not(
+    figure,
+    picture,
+    img:not([data-pmx-image="background"]),
+    video,
+    iframe,
+    p:has(> img:not([data-pmx-image="background"]):only-child),
+    p:has(> picture:only-child),
+    p:has(> video:only-child),
+    p:has(> iframe:only-child)
+  ) {
+  grid-column: 2;
+}
+
+.pmx-document
+  [data-pmx-block-layout="media-end"]
+  > :is(
+    figure,
+    picture,
+    img:not([data-pmx-image="background"]),
+    video,
+    iframe,
+    p:has(> img:not([data-pmx-image="background"]):only-child),
+    p:has(> picture:only-child),
+    p:has(> video:only-child),
+    p:has(> iframe:only-child)
+  ) {
+  grid-column: 2;
+  grid-row: 1 / span 100;
+}
+
+.pmx-document
+  [data-pmx-block-layout="media-end"]
+  > :not(
+    figure,
+    picture,
+    img:not([data-pmx-image="background"]),
+    video,
+    iframe,
+    p:has(> img:not([data-pmx-image="background"]):only-child),
+    p:has(> picture:only-child),
+    p:has(> video:only-child),
+    p:has(> iframe:only-child)
+  ) {
+  grid-column: 1;
+}
+
+@media (max-width: 48rem) {
+  .pmx-document
+    :is(
+      [data-pmx-block-layout="media-start"],
+      [data-pmx-block-layout="media-end"]
+    ) {
+    display: block;
+  }
+}

package/plugins/callout/index.ts

@@ -0,0 +1,236 @@
+import { isFenceClose, matchFenceOpen } from "../../source/index.ts"
+import { withoutHtmlComments } from "../../source/markdown/comments.ts"
+import { escapeHtml } from "../../util.ts"
+import {
+  bugIconSvg,
+  chevronRightIconSvg,
+  circleCheckBigIconSvg,
+  circleQuestionIconSvg,
+  clipboardListIconSvg,
+  flameIconSvg,
+  infoIconSvg,
+  listIconSvg,
+  listTodoIconSvg,
+  pencilIconSvg,
+  quoteIconSvg,
+  triangleAlertIconSvg,
+  xIconSvg,
+  zapIconSvg,
+} from "../../icons/lucide.ts"
+import type { Plugin } from "../types.ts"
+import stylesheet from "./theme.css" with { type: "text" }
+
+type Fold = "open" | "closed"
+
+type CalloutMarker = Readonly<{
+  type: string
+  title?: string
+  fold?: Fold
+}>
+
+type QuoteSegment = Readonly<{
+  delimiter: number
+  end: number
+}>
+
+type QuoteLine = Readonly<{
+  depth: number
+  rest: string
+  segments: readonly QuoteSegment[]
+}>
+
+const MARKER = /^\[!([a-z0-9][a-z0-9_-]*)\]([+-]?)(?:[ \t]+(.*?))?[ \t]*$/i
+
+const ICONS: Readonly<Record<string, string>> = {
+  note: pencilIconSvg,
+  abstract: clipboardListIconSvg,
+  summary: clipboardListIconSvg,
+  tldr: clipboardListIconSvg,
+  info: infoIconSvg,
+  todo: listTodoIconSvg,
+  tip: flameIconSvg,
+  hint: flameIconSvg,
+  important: flameIconSvg,
+  success: circleCheckBigIconSvg,
+  check: circleCheckBigIconSvg,
+  done: circleCheckBigIconSvg,
+  question: circleQuestionIconSvg,
+  help: circleQuestionIconSvg,
+  faq: circleQuestionIconSvg,
+  warning: triangleAlertIconSvg,
+  caution: triangleAlertIconSvg,
+  attention: triangleAlertIconSvg,
+  failure: xIconSvg,
+  fail: xIconSvg,
+  missing: xIconSvg,
+  danger: zapIconSvg,
+  error: zapIconSvg,
+  bug: bugIconSvg,
+  example: listIconSvg,
+  quote: quoteIconSvg,
+  cite: quoteIconSvg,
+}
+
+function parseQuoteLine(line: string): QuoteLine {
+  const segments: QuoteSegment[] = []
+  let cursor = 0
+
+  while (cursor < line.length) {
+    const match = line.slice(cursor).match(/^( {0,3})>[ \t]?/)
+    if (!match) break
+    const delimiter = cursor + match[1]!.length
+    cursor += match[0].length
+    segments.push({ delimiter, end: cursor })
+  }
+
+  return {
+    depth: segments.length,
+    rest: line.slice(cursor),
+    segments,
+  }
+}
+
+function afterQuoteDepth(line: string, parsed: QuoteLine, depth: number) {
+  if (!depth) return line
+  return line.slice(parsed.segments[depth - 1]!.end)
+}
+
+function markerFromLine(line: QuoteLine): CalloutMarker | undefined {
+  if (!line.depth) return
+  const match = line.rest.match(MARKER)
+  if (!match) return
+  const fold =
+    match[2] === "+" ? "open" : match[2] === "-" ? "closed" : undefined
+  const title = match[3]?.trim()
+  return {
+    type: match[1]!.toLowerCase(),
+    ...(title ? { title } : {}),
+    ...(fold ? { fold } : {}),
+  }
+}
+
+function defaultTitle(type: string) {
+  return type
+    .split(/[-_]+/)
+    .filter(Boolean)
+    .map((word) => word[0]!.toUpperCase() + word.slice(1))
+    .join(" ")
+}
+
+function trimBlankEdges(lines: readonly string[]) {
+  let start = 0
+  let end = lines.length
+  while (start < end && !lines[start]!.trim()) start++
+  while (end > start && !lines[end - 1]!.trim()) end--
+  return lines.slice(start, end)
+}
+
+function prefixLines(markdown: string, prefix: string) {
+  if (!prefix) return markdown
+  return markdown
+    .split("\n")
+    .map((line) => prefix + line)
+    .join("\n")
+}
+
+function renderCallout(marker: CalloutMarker, body: string, prefix: string) {
+  const foldable = marker.fold !== undefined
+  const container = foldable ? "details" : "aside"
+  const title = foldable ? "summary" : "div"
+  const icon = ICONS[marker.type] ?? pencilIconSvg
+  const open = marker.fold === "open" ? " open" : ""
+  const content = body
+    ? `\n<div class="pmx-callout-content">\n\n${body}\n\n</div>`
+    : ""
+  const toggle = foldable
+    ? `<span class="pmx-callout-toggle">${chevronRightIconSvg}</span>`
+    : ""
+  const html = `<${container} class="pmx-callout" data-callout="${escapeHtml(marker.type)}"${open}>
+<${title} class="pmx-callout-title"><span class="pmx-callout-icon">${icon}</span><span class="pmx-callout-title-text">${escapeHtml(marker.title ?? defaultTitle(marker.type))}</span>${toggle}</${title}>${content}
+</${container}>`
+  return `${prefixLines(html, prefix)}\n${prefix}`
+}
+
+function calloutEnd(lines: readonly string[], start: number, depth: number) {
+  let index = start + 1
+  while (index < lines.length && parseQuoteLine(lines[index]!).depth >= depth) {
+    index++
+  }
+  return index
+}
+
+function transformCallouts(markdown: string): string {
+  const lines = markdown.split(/\r?\n/)
+  const output: string[] = []
+  let fence: { marker: string; depth: number } | undefined
+  let inHtmlComment = false
+
+  for (let index = 0; index < lines.length;) {
+    const line = lines[index]!
+    const visible = withoutHtmlComments(line, inHtmlComment)
+    inHtmlComment = visible.inComment
+    const quoted = parseQuoteLine(line)
+
+    if (fence) {
+      output.push(line)
+      if (
+        quoted.depth >= fence.depth &&
+        isFenceClose(afterQuoteDepth(line, quoted, fence.depth), fence.marker)
+      ) {
+        fence = undefined
+      }
+      index++
+      continue
+    }
+
+    if (visible.line === line) {
+      const opening = matchFenceOpen(quoted.depth ? quoted.rest : line)
+      if (opening) {
+        fence = { marker: opening.marker, depth: quoted.depth }
+        output.push(line)
+        index++
+        continue
+      }
+    }
+
+    const marker = visible.line === line ? markerFromLine(quoted) : undefined
+    if (!marker) {
+      output.push(line)
+      index++
+      continue
+    }
+
+    const end = calloutEnd(lines, index, quoted.depth)
+    const bodyLines = trimBlankEdges(
+      lines.slice(index + 1, end).map((bodyLine) => {
+        const parsed = parseQuoteLine(bodyLine)
+        return afterQuoteDepth(bodyLine, parsed, quoted.depth)
+      }),
+    )
+    const body = bodyLines.length ? transformCallouts(bodyLines.join("\n")) : ""
+    const prefix = line.slice(0, quoted.segments.at(-1)!.delimiter)
+    output.push(renderCallout(marker, body, prefix))
+    index = end
+  }
+
+  return output.join("\n")
+}
+
+/** Obsidian-compatible blockquote callouts with native nested and foldable output. */
+export function CalloutPlugin(): Plugin {
+  return {
+    id: "callout",
+    precompile(markdown) {
+      return markdown.includes("[!") ? transformCallouts(markdown) : markdown
+    },
+    page(html, ctx) {
+      if (!html.includes('class="pmx-callout"')) return html
+      ctx.addAsset({
+        type: "stylesheet",
+        name: "callout.css",
+        text: stylesheet,
+      })
+      return html
+    },
+  }
+}

package/plugins/callout/theme.css

@@ -0,0 +1,138 @@
+@scope (.pmx-prose) to ([data-pmx-prose="off"]) {
+  :where(.pmx-callout) {
+    --pmx-callout-color: var(--pmx-color-accent);
+    margin-block: var(--pmx-prose-flow);
+    overflow: clip;
+    border: 1px solid
+      color-mix(in oklch, var(--pmx-callout-color) 35%, transparent);
+    border-inline-start: 0.25em solid var(--pmx-callout-color);
+    border-radius: var(--pmx-radius-lg);
+    background: color-mix(
+      in oklch,
+      var(--pmx-callout-color) 9%,
+      var(--pmx-color-bg)
+    );
+    color: var(--pmx-color-fg);
+  }
+
+  :where(.pmx-callout-title) {
+    display: flex;
+    gap: 0.6em;
+    align-items: center;
+    padding: 0.7em 0.9em;
+    color: var(--pmx-callout-color);
+    font-weight: 700;
+    line-height: 1.35;
+    list-style: none;
+  }
+
+  :where(summary.pmx-callout-title) {
+    cursor: pointer;
+  }
+
+  summary.pmx-callout-title::-webkit-details-marker {
+    display: none;
+  }
+
+  :where(.pmx-callout-icon, .pmx-callout-toggle) {
+    display: inline-flex;
+    flex: 0 0 auto;
+  }
+
+  :where(.pmx-callout-icon svg, .pmx-callout-toggle svg) {
+    inline-size: 1.1em;
+    block-size: 1.1em;
+    stroke-width: 2.2;
+  }
+
+  :where(.pmx-callout-title-text) {
+    min-inline-size: 0;
+    flex: 1;
+  }
+
+  :where(.pmx-callout-toggle) {
+    transition: transform 140ms ease-out;
+  }
+
+  :where(details.pmx-callout[open] > .pmx-callout-title .pmx-callout-toggle) {
+    transform: rotate(90deg);
+  }
+
+  :where(.pmx-callout-content) {
+    padding: 0 0.9em 0.85em;
+  }
+
+  :where(.pmx-callout-content > :first-child) {
+    margin-block-start: 0;
+  }
+
+  :where(.pmx-callout-content > :last-child) {
+    margin-block-end: 0;
+  }
+
+  :where(
+    .pmx-callout[data-callout="abstract"],
+    .pmx-callout[data-callout="summary"],
+    .pmx-callout[data-callout="tldr"]
+  ) {
+    --pmx-callout-color: light-dark(oklch(0.54 0.12 215), oklch(0.76 0.11 215));
+  }
+
+  :where(.pmx-callout[data-callout="info"], .pmx-callout[data-callout="todo"]) {
+    --pmx-callout-color: light-dark(oklch(0.54 0.17 255), oklch(0.76 0.13 250));
+  }
+
+  :where(
+    .pmx-callout[data-callout="tip"],
+    .pmx-callout[data-callout="hint"],
+    .pmx-callout[data-callout="important"]
+  ) {
+    --pmx-callout-color: light-dark(oklch(0.52 0.13 165), oklch(0.76 0.12 165));
+  }
+
+  :where(
+    .pmx-callout[data-callout="success"],
+    .pmx-callout[data-callout="check"],
+    .pmx-callout[data-callout="done"]
+  ) {
+    --pmx-callout-color: light-dark(oklch(0.52 0.15 145), oklch(0.76 0.13 145));
+  }
+
+  :where(
+    .pmx-callout[data-callout="question"],
+    .pmx-callout[data-callout="help"],
+    .pmx-callout[data-callout="faq"]
+  ) {
+    --pmx-callout-color: light-dark(oklch(0.58 0.14 85), oklch(0.82 0.13 85));
+  }
+
+  :where(
+    .pmx-callout[data-callout="warning"],
+    .pmx-callout[data-callout="caution"],
+    .pmx-callout[data-callout="attention"]
+  ) {
+    --pmx-callout-color: light-dark(oklch(0.58 0.17 55), oklch(0.8 0.15 65));
+  }
+
+  :where(
+    .pmx-callout[data-callout="failure"],
+    .pmx-callout[data-callout="fail"],
+    .pmx-callout[data-callout="missing"],
+    .pmx-callout[data-callout="danger"],
+    .pmx-callout[data-callout="error"],
+    .pmx-callout[data-callout="bug"]
+  ) {
+    --pmx-callout-color: var(--pmx-color-danger);
+  }
+
+  :where(.pmx-callout[data-callout="example"]) {
+    --pmx-callout-color: light-dark(oklch(0.55 0.16 305), oklch(0.77 0.13 305));
+  }
+
+  :where(
+    .pmx-callout[data-callout="quote"],
+    .pmx-callout[data-callout="cite"]
+  ) {
+    --pmx-callout-color: var(--pmx-color-muted);
+  }
+}

package/plugins/canonical-links.ts

@@ -0,0 +1,144 @@
+import { publicPath } from "../server/router.ts"
+import type { HtmlElement } from "../environment.ts"
+import { joinHref, splitHref } from "../ops/href.ts"
+import { interpolateText, isExternalHref } from "../source/index.ts"
+import type { Source } from "../source/index.ts"
+import { decodeHtmlEntities } from "../util.ts"
+import type { AppContext, Plugin } from "./types.ts"
+
+const REWRITABLE = new Set(["asset", "source"])
+const NEW_TAB_DESCRIPTION_ID = "pmx-new-tab-description"
+const DEFAULT_TARGET_ATTRIBUTE = "data-pmx-default-target"
+
+export type ExternalWebLinks = "new-tab" | "same-tab"
+
+export type CanonicalLinkPluginOptions = Readonly<{
+  /** Default browsing context for authored external HTTP(S) links. */
+  externalWebLinks?: ExternalWebLinks
+}>
+
+function hasClass(el: HtmlElement, name: string) {
+  const current = el.getAttribute("class")
+  if (!current) return false
+  return current.split(/\s+/).includes(name)
+}
+
+function addClass(el: HtmlElement, name: string) {
+  if (hasClass(el, name)) return
+  const current = el.getAttribute("class")
+  el.setAttribute("class", current ? `${current} ${name}` : name)
+}
+
+function addTokenAttribute(el: HtmlElement, attribute: string, token: string) {
+  const current = el.getAttribute(attribute)?.trim()
+  const tokens = current ? current.split(/\s+/) : []
+  if (tokens.some((value) => value.toLowerCase() === token.toLowerCase()))
+    return
+  el.setAttribute(attribute, [...tokens, token].join(" "))
+}
+
+function isExternalWebHref(href: string) {
+  const normalized = href.trim()
+  return /^(?:https?:)?\/\//i.test(normalized)
+}
+
+function isPmxOwnedLink(el: HtmlElement) {
+  const current = el.getAttribute("class")
+  if (!current) return false
+  return current.split(/\s+/).some((token) => token.startsWith("pmx-"))
+}
+
+function stampLink(
+  el: HtmlElement,
+  href: string,
+  externalWebLinks: ExternalWebLinks,
+) {
+  if (!isPmxOwnedLink(el)) addClass(el, "pmx-link")
+  if (isExternalHref(href)) addClass(el, "pmx-link-external")
+  if (!isExternalWebHref(href) || el.getAttribute("download") != null) return
+
+  const authoredTarget = el.getAttribute("target")
+  if (authoredTarget == null && externalWebLinks === "new-tab") {
+    el.setAttribute("target", "_blank")
+    el.setAttribute(DEFAULT_TARGET_ATTRIBUTE, "new-tab")
+  }
+  if (el.getAttribute("target")?.trim().toLowerCase() !== "_blank") return
+
+  addClass(el, "pmx-link-new-tab")
+  addTokenAttribute(el, "rel", "noopener")
+  addTokenAttribute(el, "aria-describedby", NEW_TAB_DESCRIPTION_ID)
+}
+
+function rewriteCanonicalLinks(html: string, source: Source, app: AppContext) {
+  const byHref = new Map<string, string>()
+  for (const edge of app.graph.linksFrom(source.path)) {
+    if (!edge.to || !REWRITABLE.has(edge.type)) continue
+    const renderedHref = interpolateText(edge.href, source.data)
+    const { query, fragment } = splitHref(renderedHref)
+    if (edge.type === "source") {
+      const target = app.sources.get(edge.to)
+      if (target) {
+        byHref.set(renderedHref, joinHref(publicPath(target), query, fragment))
+      }
+      continue
+    }
+    byHref.set(renderedHref, joinHref(edge.to, query, fragment))
+  }
+  if (!byHref.size) return html
+
+  return app.html.rewrite(html, [
+    [
+      "[href], [src]",
+      {
+        element(el) {
+          for (const attr of ["href", "src"] as const) {
+            const value = el.getAttribute(attr)
+            const authored = value ? decodeHtmlEntities(value.trim()) : undefined
+            const canonical = authored ? byHref.get(authored) : undefined
+            if (canonical) el.setAttribute(attr, canonical)
+          }
+        },
+      },
+    ],
+  ])
+}
+
+/** Rewrite authored relative src/href values and stamp final PathMX links. */
+export function CanonicalLinkPlugin(
+  options: CanonicalLinkPluginOptions = {},
+): Plugin {
+  const externalWebLinks = options.externalWebLinks ?? "new-tab"
+  if (externalWebLinks !== "new-tab" && externalWebLinks !== "same-tab") {
+    throw new Error(`Invalid external web-link policy: ${externalWebLinks}`)
+  }
+  return {
+    id: "canonical-links",
+    postcompile(html, { source, scope }, app) {
+      if (scope !== "embedded") return html
+      return rewriteCanonicalLinks(html, source, app)
+    },
+
+    page(html, { source }, app) {
+      return rewriteCanonicalLinks(html, source, app)
+    },
+
+    streamSelectors() {
+      return {
+        body: {
+          element(el) {
+            el.prepend(
+              `<span id="${NEW_TAB_DESCRIPTION_ID}" hidden>Opens in a new tab</span>`,
+              { html: true },
+            )
+          },
+        },
+        "a[href]": {
+          element(el) {
+            const href = el.getAttribute("href")
+            if (href != null) stampLink(el, href, externalWebLinks)
+          },
+        },
+      }
+    },
+  }
+}