@pathmx/core 0.5.0

package/plugins/toc/index.ts

@@ -0,0 +1,232 @@
+import { headingIdsForBlock } from "../../document.ts"
+import { html, type Html } from "../../html.ts"
+import { authoredViewTag, COMPONENT_ORIGIN_ATTR } from "../../view/syntax.ts"
+import type { StandardSchemaV1 } from "../../schema/standard.ts"
+import type { Source } from "../../source/index.ts"
+import { escapeHtml } from "../../util.ts"
+import { defineViewComponent, type Plugin, type ViewContext } from "../types.ts"
+
+type TocOptions = Readonly<{
+  minDepth: number
+  maxDepth: number
+  title: string
+}>
+
+type CompiledTocEntry = Readonly<{
+  id: string
+  text: string
+  depth: number
+  sourceId: string
+  blockPath: string
+}>
+
+type CompiledToc = Readonly<{
+  title: string
+  entries: readonly CompiledTocEntry[]
+}>
+
+type TocNode = CompiledTocEntry & { children: TocNode[] }
+
+const TOC_ATTRS = new Set(["title", "min-depth", "max-depth"])
+const RENDERED_LEGACY_TOC = /<toc\s*\/?>/gi
+const TOC_COMPONENT = "table-of-contents:toc"
+const TOC_TAG = authoredViewTag(TOC_COMPONENT)
+const clientEntry = new URL("./client.ts", import.meta.url)
+
+function configuredOptions(value: unknown): TocOptions | undefined {
+  if (value === false) return undefined
+  const data =
+    value && typeof value === "object" && !Array.isArray(value)
+      ? (value as Record<string, unknown>)
+      : {}
+  const depth = (key: "minDepth" | "maxDepth", fallback: number) => {
+    const value = data[key]
+    return typeof value === "number" && Number.isInteger(value)
+      ? Math.min(6, Math.max(1, value))
+      : fallback
+  }
+  const minDepth = depth("minDepth", 2)
+  return {
+    minDepth,
+    maxDepth: Math.max(minDepth, depth("maxDepth", 6)),
+    title:
+      typeof data.title === "string" && data.title.trim()
+        ? data.title.trim()
+        : "On this page",
+  }
+}
+
+function componentOptions(
+  source: Source,
+  attrs: Readonly<Record<string, string>>,
+) {
+  const configured = configuredOptions(source.data.toc)
+  if (!configured) return
+  const minDepth = attrs["min-depth"]
+    ? Number(attrs["min-depth"])
+    : configured.minDepth
+  const maxDepth = attrs["max-depth"]
+    ? Number(attrs["max-depth"])
+    : configured.maxDepth
+  return {
+    minDepth,
+    maxDepth: Math.max(minDepth, maxDepth),
+    title: attrs.title?.trim() || configured.title,
+  }
+}
+
+function headingEntries(source: Source): CompiledTocEntry[] {
+  if (!source.blocks.length) {
+    return source.headings.map((heading) => ({
+      ...heading,
+      sourceId: source.id,
+      blockPath: `${source.path}#block-0`,
+    }))
+  }
+
+  const entries: CompiledTocEntry[] = []
+  for (const block of source.blocks) {
+    for (const heading of headingIdsForBlock(source, block)) {
+      entries.push({
+        ...heading,
+        sourceId: source.id,
+        blockPath: block.path,
+      })
+    }
+  }
+  return entries
+}
+
+function buildOutline(headings: readonly CompiledTocEntry[]) {
+  const root: { depth: number; children: TocNode[] } = {
+    depth: 0,
+    children: [],
+  }
+  const stack: Array<{ depth: number; children: TocNode[] }> = [root]
+
+  for (const heading of headings) {
+    while (stack.length > 1 && stack.at(-1)!.depth >= heading.depth) stack.pop()
+    const node: TocNode = { ...heading, children: [] }
+    stack.at(-1)!.children.push(node)
+    stack.push(node)
+  }
+
+  return root.children
+}
+
+function renderOutline(nodes: readonly TocNode[]): Html {
+  return html`<ol class="pmx-toc-list">
+    ${nodes.map((node) => {
+      const children = node.children.length
+        ? renderOutline(node.children)
+        : null
+      return html`<li class="pmx-toc-item">
+        <a href="#${node.id}" class="pmx-toc-link">${node.text}</a>${children}
+      </li>`
+    })}
+  </ol>`
+}
+
+function visibleEntries(
+  entries: readonly CompiledTocEntry[],
+  view: ViewContext,
+) {
+  const readable = new Map<string, boolean>()
+  return entries.filter((entry) => {
+    let allowed = readable.get(entry.sourceId)
+    if (allowed == null) {
+      allowed = view.view.readSource(entry.sourceId) != null
+      readable.set(entry.sourceId, allowed)
+    }
+    return allowed
+  })
+}
+
+const tocAttrsSchema: StandardSchemaV1 = {
+  "~standard": {
+    version: 1,
+    vendor: "pathmx",
+    validate(value) {
+      if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return { issues: [{ message: "expected TOC attributes" }] }
+      }
+      const attrs = value as Record<string, unknown>
+      for (const key of Object.keys(attrs)) {
+        if (!TOC_ATTRS.has(key)) {
+          return { issues: [{ message: `unexpected ${key} attribute` }] }
+        }
+      }
+      if (
+        "title" in attrs &&
+        (typeof attrs.title !== "string" || !attrs.title.trim())
+      ) {
+        return { issues: [{ message: "title must not be empty" }] }
+      }
+      for (const key of ["min-depth", "max-depth"] as const) {
+        if (!(key in attrs)) continue
+        if (typeof attrs[key] !== "string" || !/^[1-6]$/.test(attrs[key])) {
+          return {
+            issues: [{ message: `${key} must be an integer from 1 to 6` }],
+          }
+        }
+      }
+      if (
+        typeof attrs["min-depth"] === "string" &&
+        typeof attrs["max-depth"] === "string" &&
+        Number(attrs["min-depth"]) > Number(attrs["max-depth"])
+      ) {
+        return { issues: [{ message: "min-depth must not exceed max-depth" }] }
+      }
+      return { value }
+    },
+  },
+}
+
+/** A viewer-aware Source/Block outline with `<toc />` migration support. */
+export function TableOfContentsPlugin(): Plugin {
+  const TocComponent = defineViewComponent<CompiledToc | undefined>({
+    tag: TOC_COMPONENT,
+    props: tocAttrsSchema,
+    async compile(use, ctx) {
+      const options = componentOptions(ctx.source, use.props)
+      if (!options) return
+      const compiled = {
+        title: options.title,
+        entries: headingEntries(ctx.source).filter(
+          (heading) =>
+            heading.depth >= options.minDepth &&
+            heading.depth <= options.maxDepth,
+        ),
+      }
+      if (!compiled.entries.length) return
+      await ctx.addBrowserBundle(clientEntry, "toc")
+      return compiled
+    },
+    render(_use, compiled, view) {
+      if (!compiled) return ""
+      const entries = visibleEntries(compiled.entries, view)
+      if (!entries.length) return ""
+      return html`<nav
+        class="pmx-toc"
+        aria-label="${compiled.title}"
+        data-pmx-toc
+      >
+        <p class="pmx-toc__title">${compiled.title}</p>
+        <div class="pmx-toc-path-frame">
+          ${renderOutline(buildOutline(entries))}
+        </div>
+      </nav>`
+    },
+  })
+
+  return {
+    id: "table-of-contents",
+    components: [TocComponent],
+    postcompile(rendered, ctx) {
+      if (!ctx.elements.has("toc")) return rendered
+      const origin = escapeHtml(ctx.source.path)
+      const replacement = `<${TOC_TAG} ${COMPONENT_ORIGIN_ATTR}="${origin}" />`
+      return rendered.replace(RENDERED_LEGACY_TOC, replacement)
+    },
+  }
+}

package/plugins/toc/theme.css

@@ -0,0 +1,172 @@
+@property --pmx-toc-scroll-progress {
+  syntax: "<number>";
+  inherits: true;
+  initial-value: 0;
+}
+
+@keyframes pmx-toc-follow-scroll {
+  to {
+    --pmx-toc-scroll-progress: 1;
+  }
+}
+
+:where(.pmx-toc) {
+  --pmx-toc-font-size: 0.875rem;
+  --pmx-toc-line-height: 1.35;
+  --pmx-toc-item-gap: 0.15rem;
+  --pmx-toc-indent: 0.9rem;
+  --pmx-toc-link-padding: 1.35rem;
+  --pmx-toc-link-color: var(--pmx-color-muted, currentColor);
+  --pmx-toc-link-active-color: var(
+    --pmx-color-accent,
+    var(--pmx-color-link, currentColor)
+  );
+  --pmx-toc-title-color: var(--pmx-color-fg, currentColor);
+  --pmx-toc-path-color: var(--pmx-color-border, currentColor);
+  --pmx-toc-path-active-color: var(
+    --pmx-color-accent,
+    var(--pmx-color-link, currentColor)
+  );
+  --pmx-toc-path-width: 1px;
+  --pmx-toc-transition-duration: 160ms;
+  --pmx-toc-max-block-size: var(--pmx-sticky-max-block-size, 100dvh);
+  --pmx-toc-available-block-size: var(--pmx-toc-max-block-size);
+
+  color: var(--pmx-toc-link-color);
+  font-size: var(--pmx-toc-font-size);
+  line-height: var(--pmx-toc-line-height);
+  max-block-size: min(
+    var(--pmx-toc-max-block-size),
+    var(--pmx-toc-available-block-size)
+  );
+  overflow-y: auto;
+  overscroll-behavior-block: contain;
+  scrollbar-gutter: stable;
+  scrollbar-width: thin;
+}
+
+:where(.pmx-toc__title) {
+  margin-block: 0 0.75rem;
+  color: var(--pmx-toc-title-color);
+  font-family: var(--pmx-font-heading, inherit);
+  font-weight: 700;
+}
+
+:where(.pmx-toc-path-frame) {
+  position: relative;
+  animation: pmx-toc-follow-scroll linear both;
+  animation-timeline: scroll(root block);
+}
+
+:where(.pmx-toc-path-frame)::after {
+  content: "";
+  position: absolute;
+  z-index: 1;
+  inset-block: 0;
+  inset-inline-start: calc(var(--pmx-toc-link-padding) / 2);
+  inline-size: var(--pmx-toc-path-width);
+  background: var(--pmx-toc-path-active-color);
+  pointer-events: none;
+  transform: scaleY(var(--pmx-toc-scroll-progress));
+  transform-origin: top;
+}
+
+:where(.pmx-toc-list) {
+  position: relative;
+  display: grid;
+  gap: var(--pmx-toc-item-gap);
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+:where(.pmx-toc-path-frame > .pmx-toc-list) {
+  scroll-target-group: auto;
+}
+
+:where(.pmx-toc-list)::before {
+  content: "";
+  position: absolute;
+  inset-block: 0;
+  inset-inline-start: calc(var(--pmx-toc-link-padding) / 2);
+  inline-size: var(--pmx-toc-path-width);
+  background: var(--pmx-toc-path-color);
+  pointer-events: none;
+}
+
+:where(.pmx-toc-list .pmx-toc-list) {
+  margin-inline-start: var(--pmx-toc-indent);
+}
+
+:where(.pmx-toc-item) {
+  position: relative;
+  min-inline-size: 0;
+}
+
+:where(.pmx-toc-link) {
+  position: relative;
+  z-index: 2;
+  display: block;
+  padding-block: 0.3rem;
+  padding-inline-start: var(--pmx-toc-link-padding);
+  color: var(--pmx-toc-link-color);
+  text-decoration: none;
+  overflow-wrap: anywhere;
+  transition: color var(--pmx-toc-transition-duration) ease-out;
+}
+
+:where(.pmx-toc-link)::before {
+  content: "";
+  position: absolute;
+  inset-block-start: calc(0.3rem + 0.5lh);
+  inset-inline-start: calc(var(--pmx-toc-link-padding) / 2);
+  inline-size: calc(var(--pmx-toc-link-padding) / 2 - 0.25rem);
+  block-size: var(--pmx-toc-path-width);
+  background: var(--pmx-toc-path-color);
+  transform: translateY(-50%);
+  transition: background var(--pmx-toc-transition-duration) ease-out;
+}
+
+:where(
+  .pmx-toc-link:target-before,
+  .pmx-toc-link:target-current,
+  .pmx-toc-link[data-pmx-toc-state="passed"],
+  .pmx-toc-link[data-pmx-toc-state="active"]
+) {
+  color: var(--pmx-toc-link-active-color);
+}
+
+:where(
+  .pmx-toc-link:target-before,
+  .pmx-toc-link:target-current,
+  .pmx-toc-link[data-pmx-toc-state="passed"],
+  .pmx-toc-link[data-pmx-toc-state="active"]
+)::before {
+  background: var(--pmx-toc-path-active-color);
+}
+
+:where(.pmx-toc-link:hover) {
+  color: var(--pmx-toc-link-active-color);
+}
+
+:where(.pmx-toc-link:focus-visible) {
+  color: var(--pmx-toc-link-active-color);
+  outline: 2px solid var(--pmx-color-focus, currentColor);
+  outline-offset: 2px;
+  border-radius: var(--pmx-radius-sm, 0.25rem);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  :where(.pmx-toc-path-frame) {
+    animation: none;
+  }
+
+  :where(.pmx-toc-path-frame)::after {
+    display: none;
+  }
+
+  :where(.pmx-toc-link),
+  :where(.pmx-toc-link)::before {
+    transition: none;
+  }
+}