@pathmx/core 0.5.0

package/plugins/math/index.ts

@@ -0,0 +1,140 @@
+import temml from "temml"
+import temmlCss from "temml/dist/Temml-Local.css" with { type: "text" }
+import { isFenceClose, matchFenceOpen } from "../../source/index.ts"
+import { escapeHtml } from "../../util.ts"
+import type { AppContext, CompileContext, Plugin } from "../types.ts"
+
+type MathEntry = {
+  tex: string
+  display: boolean
+}
+
+const DISPLAY_MATH = /\$\$([\s\S]+?)\$\$/g
+const INLINE_MATH = /\$(?!\s)([^$\n]+?)(?<!\s)\$(?!\d)/g
+const PLACEHOLDER = /<(div|span) data-pathmx-math="(\d+)"><\/(?:div|span)>/g
+const INLINE_CODE = /`[^`\n]+`/g
+const FONT_FACE = /\/\*[\s\S]*?\*\/\s*@font-face\s*\{[^}]*\}/g
+
+const stylesheet = temmlCss as unknown as string
+
+function maskInlineCode(text: string) {
+  const slots: string[] = []
+  const masked = text.replace(INLINE_CODE, (match) => {
+    const index = slots.length
+    slots.push(match)
+    return `\0${index}\0`
+  })
+  return { masked, slots }
+}
+
+function unmaskInlineCode(text: string, slots: string[]) {
+  return text.replace(/\0(\d+)\0/g, (_match, index: string) => {
+    return slots[Number(index)] ?? ""
+  })
+}
+
+function extractMath(text: string, stash: MathEntry[]) {
+  const { masked, slots } = maskInlineCode(text)
+  let result = masked.replace(DISPLAY_MATH, (_match, tex: string) => {
+    const index = stash.length
+    stash.push({ tex: tex.trim(), display: true })
+    return `\n\n<div data-pathmx-math="${index}"></div>\n\n`
+  })
+  result = result.replace(INLINE_MATH, (_match, tex: string) => {
+    const index = stash.length
+    stash.push({ tex: tex.trim(), display: false })
+    return `<span data-pathmx-math="${index}"></span>`
+  })
+  return unmaskInlineCode(result, slots)
+}
+
+function stashMath(markdown: string) {
+  const stash: MathEntry[] = []
+  const lines = markdown.split(/\r?\n/)
+  const out: string[] = []
+  const unfenced: string[] = []
+  let marker: string | undefined
+
+  const flush = () => {
+    if (!unfenced.length) return
+    out.push(extractMath(unfenced.join("\n"), stash))
+    unfenced.length = 0
+  }
+
+  for (const line of lines) {
+    if (marker) {
+      out.push(line)
+      if (isFenceClose(line, marker)) marker = undefined
+      continue
+    }
+    const fence = matchFenceOpen(line)
+    if (fence) {
+      flush()
+      out.push(line)
+      marker = fence.marker
+      continue
+    }
+    unfenced.push(line)
+  }
+  flush()
+
+  return { markdown: out.join("\n"), stash }
+}
+
+function renderEntry(entry: MathEntry, app: AppContext) {
+  try {
+    const math = temml.renderToString(entry.tex, {
+      displayMode: entry.display,
+      throwOnError: false,
+    })
+    const kind = entry.display ? "display" : "inline"
+    const tag = entry.display ? "div" : "span"
+    return `<${tag} data-pathmx-math="${kind}">${math}</${tag}>`
+  } catch (error) {
+    app.log.warn("render", {
+      tex: entry.tex,
+      error: error instanceof Error ? error.message : String(error),
+    })
+    const raw = escapeHtml(entry.tex)
+    return entry.display
+      ? `<pre data-pathmx-math="error"><code>$$${raw}$$</code></pre>`
+      : `<code data-pathmx-math="error">$${raw}$</code>`
+  }
+}
+
+export function MathPlugin(): Plugin {
+  const stashByContext = new WeakMap<CompileContext, MathEntry[]>()
+
+  return {
+    id: "math",
+    precompile(markdown, ctx) {
+      if (!markdown.includes("$")) {
+        stashByContext.set(ctx, [])
+        return markdown
+      }
+      const parsed = stashMath(markdown)
+      stashByContext.set(ctx, parsed.stash)
+      return parsed.markdown
+    },
+
+    postcompile(html, ctx, app) {
+      if (!html.includes("data-pathmx-math")) return html
+      const stash = stashByContext.get(ctx) ?? []
+      return html.replace(PLACEHOLDER, (match, _tag: string, index: string) => {
+        const entry = stash[Number(index)]
+        if (!entry) return match
+        return renderEntry(entry, app)
+      })
+    },
+
+    page(html, ctx) {
+      if (!html.includes("data-pathmx-math")) return html
+      ctx.addAsset({
+        type: "stylesheet",
+        name: "math.css",
+        text: stylesheet.replace(FONT_FACE, "").trim(),
+      })
+      return html
+    },
+  }
+}

package/plugins/meta.ts

@@ -0,0 +1,42 @@
+import { deriveSourceMeta } from "../source/index.ts"
+import type { DocumentAsset, Plugin } from "./types.ts"
+
+function meta(attrs: Record<string, string>): DocumentAsset {
+  return { type: "meta", attrs }
+}
+
+/**
+ * Head metadata: document boilerplate (charset, viewport) plus per-page
+ * title, description, and Open Graph tags from the source's derived meta.
+ */
+export function MetaPlugin(): Plugin {
+  return {
+    id: "meta",
+    documentAssets(ctx) {
+      ctx.addAsset(
+        meta({ charset: "utf-8" }),
+        meta({
+          name: "viewport",
+          content: "width=device-width, initial-scale=1",
+        }),
+      )
+    },
+
+    page(html, ctx, app) {
+      if (!app.sources.isPage(ctx.source)) return html
+      const { title, description, image } = deriveSourceMeta(ctx.source)
+      ctx.addAsset(
+        { type: "title", text: title },
+        meta({ property: "og:title", content: title }),
+      )
+      if (description) {
+        ctx.addAsset(
+          meta({ name: "description", content: description }),
+          meta({ property: "og:description", content: description }),
+        )
+      }
+      if (image) ctx.addAsset(meta({ property: "og:image", content: image }))
+      return html
+    },
+  }
+}

package/plugins/navigation/index.ts

@@ -0,0 +1,158 @@
+import { html, type Html } from "../../html.ts"
+import type { StandardSchemaV1 } from "../../schema/standard.ts"
+import {
+  NavigationModel,
+  type CompiledNavigation,
+  type VisibleNavigationNode,
+} from "./model.ts"
+import {
+  defineViewComponent,
+  type AppContext,
+  type PageContext,
+  type Plugin,
+  type ViewComponentUse,
+  type ViewContext,
+} from "../types.ts"
+
+function renderNavNode(node: VisibleNavigationNode): Html {
+  const active = node.active ? html` data-pmx-active="${node.active}"` : null
+  const current = node.active === "page" ? html` aria-current="page"` : null
+  const children = node.children.length
+    ? html`<ul class="pmx-nav-list">
+        ${node.children.map(renderNavNode)}
+      </ul>`
+    : null
+  // prettier-ignore
+  const content =
+    node.type === "resolved"
+      ? html`<a class="pmx-nav-link" href="${node.route}"${active}${current}>${node.label}</a>`
+      : html`<span class="pmx-nav-link" data-pmx-unresolved="true" aria-disabled="true" title="Unresolved: ${node.href}">${node.label}</span>`
+  return html`<li class="pmx-nav-item" ${active}>${content}${children}</li>`
+}
+
+function activeTrail(
+  nodes: readonly VisibleNavigationNode[],
+): readonly VisibleNavigationNode[] {
+  for (const node of nodes) {
+    if (!node.active) continue
+    const childTrail = activeTrail(node.children)
+    return childTrail.length ? [node, ...childTrail] : [node]
+  }
+  return []
+}
+
+function renderBreadcrumbNode(node: VisibleNavigationNode): Html {
+  const active = node.active ? html` data-pmx-active="${node.active}"` : null
+  // prettier-ignore
+  const content =
+    node.active === "page"
+      ? html`<span class="pmx-breadcrumbs-current" aria-current="page">${node.label}</span>`
+      : node.type === "resolved"
+        ? html`<a class="pmx-breadcrumbs-link" href="${node.route}">${node.label}</a>`
+        : html`<span class="pmx-breadcrumbs-link" data-pmx-unresolved="true" aria-disabled="true" title="Unresolved: ${node.href}">${node.label}</span>`
+  return html`<li class="pmx-breadcrumbs-item" ${active}>${content}</li>`
+}
+
+function renderNavigation(
+  state: CompiledNavigation,
+  view: ViewContext,
+  model: NavigationModel,
+) {
+  const nodes = model.visible(state, view)
+  return html`<nav
+    class="pmx-nav"
+    data-pmx-nav="${state.name}"
+    aria-label="${state.label}"
+  >
+    <ul class="pmx-nav-list">
+      ${nodes.map(renderNavNode)}
+    </ul>
+  </nav>`
+}
+
+function renderBreadcrumbs(
+  state: CompiledNavigation,
+  view: ViewContext,
+  model: NavigationModel,
+) {
+  const trail = activeTrail(model.visible(state, view))
+  if (!trail.length) return ""
+  return html`<nav
+    class="pmx-breadcrumbs"
+    data-pmx-breadcrumbs="${state.name}"
+    aria-label="Breadcrumb"
+  >
+    <ol class="pmx-breadcrumbs-list">
+      ${trail.map(renderBreadcrumbNode)}
+    </ol>
+  </nav>`
+}
+
+const navAttrsSchema: StandardSchemaV1 = {
+  "~standard": {
+    version: 1,
+    vendor: "pathmx",
+    validate(value) {
+      if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return { issues: [{ message: `expected one valid name attribute` }] }
+      }
+      const attrs = value as Record<string, unknown>
+      const keys = Object.keys(attrs)
+      if (
+        keys.length === 1 &&
+        keys[0] === "name" &&
+        typeof attrs.name === "string" &&
+        /^[A-Za-z][\w-]*$/.test(attrs.name)
+      ) {
+        return { value }
+      }
+      return { issues: [{ message: `expected one valid name attribute` }] }
+    },
+  },
+}
+
+/** Authored navigation and breadcrumbs projected from one viewer-aware model. */
+export function NavigationPlugin(): Plugin {
+  const model = new NavigationModel()
+  const compile = (use: ViewComponentUse, ctx: PageContext, app: AppContext) =>
+    model.compile(use.props.name!, use, ctx, app)
+
+  const NavigationComponent = defineViewComponent<CompiledNavigation>({
+    tag: "navigation:nav",
+    props: navAttrsSchema,
+    compile,
+    render(_use, compiled, view) {
+      return renderNavigation(compiled, view, model)
+    },
+  })
+
+  const BreadcrumbsComponent = defineViewComponent<CompiledNavigation>({
+    tag: "navigation:breadcrumbs",
+    props: navAttrsSchema,
+    compile,
+    render(_use, compiled, view) {
+      return renderBreadcrumbs(compiled, view, model)
+    },
+  })
+
+  return {
+    id: "navigation",
+    schema: {
+      sources: {
+        navigation: {
+          label: "Navigation",
+          description: "An authored navigation tree.",
+          icon: "network",
+          color: "cyan",
+        },
+      },
+    },
+    components: [NavigationComponent, BreadcrumbsComponent],
+    index(source) {
+      model.index(source)
+    },
+    unindex(sourcePath) {
+      model.unindex(sourcePath)
+    },
+  }
+}

package/plugins/navigation/model.ts

@@ -0,0 +1,364 @@
+import {
+  isIndexSource,
+  publicPath,
+  sourceDirectory,
+} from "../../server/router.ts"
+import type { Source, SourceLink } from "../../source/index.ts"
+import {
+  markdownListItemLink,
+  parseMarkdownLists,
+  type MarkdownList,
+} from "../../source/index.ts"
+import { isExactMarkdownSourceHref } from "../../source/markdown/links.ts"
+import { cleanInlineText } from "../../source/markdown/text.ts"
+import { decodeHtmlEntities } from "../../util.ts"
+import { SourceDiagnosticError } from "../../source-diagnostic.ts"
+import type {
+  AppContext,
+  PageContext,
+  ViewComponentUse,
+  ViewContext,
+} from "../types.ts"
+
+const NAVIGATION_TYPE = "navigation"
+
+type AuthoredNavigationNode = Readonly<{
+  label: string
+  href: string
+  children: readonly AuthoredNavigationNode[]
+}>
+
+export type CompiledNavigationNode = Readonly<{
+  type: "resolved" | "unresolved"
+  label: string
+  href: string
+  targetId?: string
+  targetPath?: string
+  route?: string
+  sectionDir?: string
+  children: readonly CompiledNavigationNode[]
+}>
+
+export type CompiledNavigation = Readonly<{
+  name: string
+  label: string
+  nodes: readonly CompiledNavigationNode[]
+}>
+
+export type VisibleNavigationNode = CompiledNavigationNode &
+  Readonly<{
+    active?: "page" | "section" | "ancestor"
+    children: readonly VisibleNavigationNode[]
+  }>
+
+type DraftNavigationNode = {
+  label: string
+  href: string
+  children: DraftNavigationNode[]
+}
+
+function navigationError(source: Source, message: string): never {
+  throw new SourceDiagnosticError({
+    source: source.path,
+    plugin: "navigation",
+    message: `Invalid navigation in ${source.path}: ${message}`,
+  })
+}
+
+function exactMarkdownTarget(source: Source, href: string) {
+  const target = href.trim()
+  if (!isExactMarkdownSourceHref(target)) {
+    navigationError(
+      source,
+      `links must target exact Markdown Sources, received ${target}.`,
+    )
+  }
+  return target
+}
+
+function navigationTarget(source: Source, href: string) {
+  const target = href.trim()
+  if (
+    target.startsWith("~/") &&
+    target.endsWith(".md") &&
+    !target.includes("?") &&
+    !target.includes("#") &&
+    !target.includes("\\")
+  ) {
+    return target
+  }
+  return exactMarkdownTarget(source, target)
+}
+
+function navigationNodes(
+  source: Source,
+  lists: readonly MarkdownList[],
+): DraftNavigationNode[] {
+  const nodes: DraftNavigationNode[] = []
+  for (const list of lists) {
+    if (list.type !== "unordered") {
+      navigationError(
+        source,
+        `line ${list.items[0]?.line ?? 1} must use a Markdown bullet.`,
+      )
+    }
+    for (const item of list.items) {
+      if (item.children.length > 1) {
+        navigationError(
+          source,
+          `line ${item.children[1]?.items[0]?.line ?? item.line} has inconsistent indentation.`,
+        )
+      }
+      const link = markdownListItemLink(item)
+      if (!link) {
+        navigationError(
+          source,
+          `line ${item.line} must be a Markdown bullet containing one link.`,
+        )
+      }
+      const label = decodeHtmlEntities(cleanInlineText(link.label))
+      if (!label)
+        navigationError(source, `line ${item.line} has an empty label.`)
+      nodes.push({
+        label,
+        href: navigationTarget(source, link.href),
+        children: navigationNodes(source, item.children),
+      })
+    }
+  }
+  return nodes
+}
+
+function parseNavigation(source: Source): readonly AuthoredNavigationNode[] {
+  const parsed = parseMarkdownLists(source.body)
+  const invalid = parsed.other[0]
+  if (invalid) {
+    navigationError(
+      source,
+      invalid.text.includes("\t")
+        ? `line ${invalid.line} uses a tab for indentation.`
+        : `line ${invalid.line} must be a Markdown bullet containing one link.`,
+    )
+  }
+  const nodes = navigationNodes(source, parsed.lists)
+  if (!nodes.length) navigationError(source, `expected at least one link.`)
+  return nodes
+}
+
+function sourceLinks(source: Source) {
+  return source.blocks.length
+    ? source.blocks.flatMap((block) => block.links)
+    : source.links
+}
+
+function indexRelations(source: Source) {
+  if (!source.body.includes("@nav")) return
+  const relations = new Map<string, SourceLink>()
+  for (const link of sourceLinks(source)) {
+    if (link.directive?.name !== "nav") continue
+    if (link.kind !== "definition") {
+      navigationError(source, `@nav must use a reference definition.`)
+    }
+    const [name, ...extra] = link.directive.qualifiers
+    if (!name || extra.length) {
+      navigationError(source, `@nav requires exactly one name qualifier.`)
+    }
+    if (relations.has(name)) {
+      navigationError(source, `multiple @nav.${name} definitions.`)
+    }
+    exactMarkdownTarget(source, link.href)
+    relations.set(name, link)
+  }
+  return relations
+}
+
+function navigationEdge(source: Source, href: string, app: AppContext) {
+  return app.graph
+    .linksFrom(source.path)
+    .find((candidate) => candidate.href === href)
+}
+
+function edgeTarget(source: Source, href: string, app: AppContext) {
+  const edge = navigationEdge(source, href, app)
+  return edge?.to ? app.sources.get(edge.to) : undefined
+}
+
+function unresolvedNode(
+  source: Source,
+  node: AuthoredNavigationNode,
+  children: readonly CompiledNavigationNode[],
+  app: AppContext,
+  reason: string,
+): CompiledNavigationNode {
+  const edge = navigationEdge(source, node.href, app)
+  app.log.warn("link.unresolved", {
+    source: source.path,
+    href: node.href,
+    label: node.label,
+    reason,
+  })
+  return {
+    type: "unresolved",
+    label: node.label,
+    href: node.href,
+    ...(edge?.to ? { targetPath: edge.to } : {}),
+    children,
+  }
+}
+
+function compileNodes(
+  source: Source,
+  nodes: readonly AuthoredNavigationNode[],
+  app: AppContext,
+): CompiledNavigationNode[] {
+  return nodes.map((node) => {
+    const children = compileNodes(source, node.children, app)
+    const target = edgeTarget(source, node.href, app)
+    if (!target) {
+      return unresolvedNode(source, node, children, app, "Source not found.")
+    }
+    if (!app.sources.isPage(target)) {
+      return unresolvedNode(
+        source,
+        node,
+        children,
+        app,
+        `Target is a ${target.type} Source, not a page.`,
+      )
+    }
+    const dir = isIndexSource(target) ? sourceDirectory(target) : undefined
+    return {
+      type: "resolved",
+      label: node.label,
+      href: node.href,
+      targetId: target.id,
+      targetPath: target.path,
+      route: publicPath(target),
+      ...(dir && dir !== "/" ? { sectionDir: dir } : {}),
+      children,
+    }
+  })
+}
+
+function recordTargetDependencies(
+  nodes: readonly CompiledNavigationNode[],
+  depend: PageContext["depend"],
+) {
+  for (const node of nodes) {
+    if (node.targetPath) depend({ type: "source", path: node.targetPath })
+    recordTargetDependencies(node.children, depend)
+  }
+}
+
+function activeState(
+  node: CompiledNavigationNode,
+  children: readonly VisibleNavigationNode[],
+  current: Source,
+): VisibleNavigationNode["active"] {
+  if (node.type === "unresolved") return
+  if (node.targetId === current.id) return "page"
+  if (node.sectionDir && current.path.startsWith(`${node.sectionDir}/`)) {
+    return "section"
+  }
+  if (children.some((child) => child.active)) return "ancestor"
+}
+
+function visibleNodes(
+  nodes: readonly CompiledNavigationNode[],
+  view: ViewContext,
+): VisibleNavigationNode[] {
+  return nodes.flatMap((node) => {
+    const children = visibleNodes(node.children, view)
+    if (node.type === "resolved" && !view.view.readSource(node.targetId!)) {
+      return children
+    }
+    const active = activeState(node, children, view.source)
+    return [{ ...node, children, ...(active ? { active } : {}) }]
+  })
+}
+
+/** Shared private index used by navigation and breadcrumb renderers. */
+export class NavigationModel {
+  private navigations = new Map<string, readonly AuthoredNavigationNode[]>()
+  private relations = new Map<string, ReadonlyMap<string, SourceLink>>()
+  private compiledNodes = new Map<string, readonly CompiledNavigationNode[]>()
+  private visibleViews = new WeakMap<
+    ViewContext,
+    Map<readonly CompiledNavigationNode[], readonly VisibleNavigationNode[]>
+  >()
+
+  index(source: Source) {
+    const indexedRelations = indexRelations(source)
+    if (indexedRelations) this.relations.set(source.path, indexedRelations)
+    else this.relations.delete(source.path)
+    if (source.type === NAVIGATION_TYPE) {
+      this.navigations.set(source.path, parseNavigation(source))
+    }
+  }
+
+  unindex(sourcePath: string) {
+    this.relations.delete(sourcePath)
+    this.navigations.delete(sourcePath)
+    this.compiledNodes.clear()
+  }
+
+  compile(
+    name: string,
+    use: ViewComponentUse,
+    ctx: PageContext,
+    app: AppContext,
+  ): CompiledNavigation {
+    const relation = this.relations.get(use.origin.path)?.get(name)
+    if (!relation) {
+      navigationError(use.origin, `missing @nav.${name} definition.`)
+    }
+    const source = edgeTarget(use.origin, relation.href, app)
+    if (!source) {
+      navigationError(
+        use.origin,
+        `navigation Source not found: ${relation.href}.`,
+      )
+    }
+    if (source.type !== NAVIGATION_TYPE) {
+      navigationError(
+        use.origin,
+        `${relation.href} is a ${source.type} Source, not navigation.`,
+      )
+    }
+    if (!app.access.canEmbed(ctx.source.id, source.id)) {
+      navigationError(ctx.source, `cannot embed navigation ${source.path}.`)
+    }
+    const authoredNodes = this.navigations.get(source.path)
+    if (!authoredNodes) navigationError(source, `Source was not indexed.`)
+    let nodes = this.compiledNodes.get(source.path)
+    if (!nodes) {
+      nodes = compileNodes(source, authoredNodes, app)
+      this.compiledNodes.set(source.path, nodes)
+    }
+    ctx.depend({ type: "source", path: source.path })
+    recordTargetDependencies(nodes, ctx.depend)
+    const authoredLabel = source.data.label
+    return {
+      name,
+      label:
+        typeof authoredLabel === "string" && authoredLabel.trim()
+          ? authoredLabel.trim()
+          : name,
+      nodes,
+    }
+  }
+
+  visible(state: CompiledNavigation, view: ViewContext) {
+    let projections = this.visibleViews.get(view)
+    if (!projections) {
+      projections = new Map()
+      this.visibleViews.set(view, projections)
+    }
+    let nodes = projections.get(state.nodes)
+    if (!nodes) {
+      nodes = visibleNodes(state.nodes, view)
+      projections.set(state.nodes, nodes)
+    }
+    return nodes
+  }
+}