@livemark/markdown 0.0.0-stage → 0.45.0

package/source/components/Columns.tsx

@@ -0,0 +1,10 @@
+/** Grid layout for arranging content side by side */
+export function Columns(props: { cols?: string; children: React.ReactNode }) {
+  const cols = props.cols ? parseInt(props.cols, 10) : undefined
+  const style = cols ? { gridTemplateColumns: `repeat(${cols}, 1fr)` } : undefined
+  return (
+    <div className="grid gap-6 my-4 sm:grid-cols-2" style={style}>
+      {props.children}
+    </div>
+  )
+}

package/source/components/DefinitionList.tsx

@@ -0,0 +1,18 @@
+import type { ComponentProps } from "react"
+
+/** Styled wrapper for definition lists produced by remark-definition-list */
+export function DefinitionList(props: ComponentProps<"dl">) {
+  return <dl {...props} className="not-prose space-y-4" />
+}
+
+/** Styled definition term rendered as bold text */
+export function DefinitionTerm(props: ComponentProps<"dt">) {
+  return <dt {...props} className="text-foreground font-semibold" />
+}
+
+/** Styled definition detail with a left border accent */
+export function DefinitionDetail(props: ComponentProps<"dd">) {
+  return (
+    <dd {...props} className="ml-0 pl-4 border-l-2 border-border text-muted-foreground" />
+  )
+}

package/source/components/Details.tsx

@@ -0,0 +1,30 @@
+import { useState } from "react"
+import { ChevronRight } from "lucide-react"
+import {
+  Collapsible,
+  CollapsibleTrigger,
+  CollapsibleContent,
+} from "../elements/collapsible.tsx"
+
+/** Collapsible content section with a summary label */
+export function Details(props: { summary: string; children: React.ReactNode }) {
+  const [open, setOpen] = useState(false)
+
+  return (
+    <Collapsible
+      open={open}
+      onOpenChange={setOpen}
+      className="not-prose my-4 rounded-card border border-border bg-card px-4 py-3"
+    >
+      <CollapsibleTrigger className="flex w-full cursor-pointer items-center gap-2 text-sm font-semibold select-none">
+        <ChevronRight
+          className={`size-4 shrink-0 transition-transform ${open ? "rotate-90" : ""}`}
+        />
+        {props.summary}
+      </CollapsibleTrigger>
+      <CollapsibleContent className="mt-3 text-sm [&>p]:my-1 [&>p:first-child]:mt-0 [&>p:last-child]:mb-0">
+        {props.children}
+      </CollapsibleContent>
+    </Collapsible>
+  )
+}

package/source/components/Filetree.tsx

@@ -0,0 +1,63 @@
+import { File, Folder } from "lucide-react"
+
+interface TreeItem {
+  name: string
+  type: "directory" | "file" | "placeholder"
+  comment?: string
+  highlighted?: boolean
+  children?: TreeItem[]
+}
+
+/** Renders a file/directory tree from a JSON-serialized tree structure */
+export function Filetree(props: { tree: string }) {
+  const items: TreeItem[] = JSON.parse(props.tree)
+
+  return (
+    <div className="not-prose my-4 rounded-card border border-border bg-card p-4 font-mono text-sm">
+      <TreeItems items={items} depth={0} />
+    </div>
+  )
+}
+
+function TreeItems(props: { items: TreeItem[]; depth: number }) {
+  return (
+    <ul className={props.depth > 0 ? "ml-4 border-l border-border pl-2" : ""}>
+      {props.items.map((item, index) => (
+        <TreeNode key={`${item.name}-${index}`} item={item} depth={props.depth} />
+      ))}
+    </ul>
+  )
+}
+
+function TreeNode(props: { item: TreeItem; depth: number }) {
+  const { item, depth } = props
+  const isDir = item.type === "directory"
+
+  return (
+    <li className="py-0.5">
+      <span className="inline-flex items-center gap-2">
+        {isDir && <Folder className="size-4 shrink-0 text-primary" />}
+        {item.type === "file" && (
+          <File className="size-4 shrink-0 text-muted-foreground" />
+        )}
+        <span
+          className={[
+            isDir && "font-semibold",
+            item.type === "placeholder" && "text-muted-foreground",
+            item.highlighted && "rounded bg-primary/10 px-1 text-primary",
+          ]
+            .filter(Boolean)
+            .join(" ")}
+        >
+          {item.name}
+        </span>
+        {item.comment && (
+          <span className="font-sans text-xs text-muted-foreground">{item.comment}</span>
+        )}
+      </span>
+      {item.children && item.children.length > 0 && (
+        <TreeItems items={item.children} depth={depth + 1} />
+      )}
+    </li>
+  )
+}

package/source/components/FootnoteRef.tsx

@@ -0,0 +1,52 @@
+import { type ComponentProps, useEffect, useState } from "react"
+import { HoverCard, HoverCardContent, HoverCardTrigger } from "../elements/hover-card.tsx"
+import { useArticleHref } from "../helpers/article-link.ts"
+import { useMessages } from "../hooks/messages.ts"
+
+const FOOTNOTE_PREFIX = "#user-content-fn-"
+
+/** Wraps footnote reference links in a HoverCard that previews footnote content inline,
+ *  and points relative links to Markdown files at their articles */
+export function FootnoteRef(props: ComponentProps<"a">) {
+  const href = useArticleHref(props.href) ?? ""
+  if (!href.startsWith(FOOTNOTE_PREFIX)) {
+    return <a {...props} href={props.href && href} />
+  }
+
+  return <FootnoteHoverCard {...props} href={href} />
+}
+
+function FootnoteHoverCard(props: ComponentProps<"a"> & { href: string }) {
+  const [footnoteHtml, setFootnoteHtml] = useState("")
+  const t = useMessages()
+
+  useEffect(() => {
+    const targetId = props.href.slice(1)
+    const el = document.getElementById(targetId)
+    if (!el) return
+
+    const wrapper = document.createElement("div")
+    wrapper.innerHTML = el.innerHTML
+    for (const backref of wrapper.querySelectorAll("[data-footnote-backref]")) {
+      backref.remove()
+    }
+    setFootnoteHtml(wrapper.innerHTML)
+  }, [props.href])
+
+  return (
+    <HoverCard>
+      <HoverCardTrigger render={<a {...props} />} />
+      <HoverCardContent
+        className="prose dark:prose-invert text-sm w-80 [&>p]:my-1 [&>p:first-child]:mt-0 [&>p:last-child]:mb-0"
+        side="top"
+        sideOffset={8}
+      >
+        {footnoteHtml ? (
+          <div dangerouslySetInnerHTML={{ __html: footnoteHtml }} />
+        ) : (
+          <p className="text-muted-foreground">{t("footnote.missing")}</p>
+        )}
+      </HoverCardContent>
+    </HoverCard>
+  )
+}

package/source/components/Heading.tsx

@@ -0,0 +1,20 @@
+/** Heading component that wraps content in an anchor link to itself */
+function createHeading(Tag: "h1" | "h2" | "h3" | "h4" | "h5" | "h6") {
+  return function Heading(props: React.HTMLAttributes<HTMLHeadingElement>) {
+    if (!props.id) return <Tag {...props} />
+    return (
+      <Tag {...props}>
+        <a href={`#${props.id}`}>{props.children}</a>
+      </Tag>
+    )
+  }
+}
+
+export const headingComponents = {
+  h1: createHeading("h1"),
+  h2: createHeading("h2"),
+  h3: createHeading("h3"),
+  h4: createHeading("h4"),
+  h5: createHeading("h5"),
+  h6: createHeading("h6"),
+}

package/source/components/Icon.tsx

@@ -0,0 +1,10 @@
+import { DynamicIcon } from "../helpers/dynamic-icon.tsx"
+
+/** Renders a Lucide icon inline by name */
+export function Icon(props: { name: string; className?: string }) {
+  const className = props.className
+    ? `inline-block size-4 align-text-bottom ${props.className}`
+    : "inline-block size-4 align-text-bottom"
+
+  return <DynamicIcon name={props.name} className={className} />
+}

package/source/components/Markdown.tsx

@@ -0,0 +1,89 @@
+import type { ComponentType } from "react"
+import { TocContext } from "../helpers/toc-context.ts"
+import type { TocItem } from "../models/toc.ts"
+import { Abbr } from "./Abbr.tsx"
+import { AnsiCode } from "./AnsiCode.tsx"
+import { Audio } from "./Audio.tsx"
+import { Badge } from "./Badge.tsx"
+import { Button } from "./Button.tsx"
+import { Callout } from "./Callout.tsx"
+import { Card } from "./Card.tsx"
+import { Cards } from "./Cards.tsx"
+import { CodeBlock } from "./CodeBlock.tsx"
+import { CodeTabs } from "./CodeTabs.tsx"
+import { Column } from "./Column.tsx"
+import { Columns } from "./Columns.tsx"
+import { DefinitionDetail, DefinitionList, DefinitionTerm } from "./DefinitionList.tsx"
+import { Details } from "./Details.tsx"
+import { Filetree } from "./Filetree.tsx"
+import { FootnoteRef } from "./FootnoteRef.tsx"
+import { headingComponents } from "./Heading.tsx"
+import { Icon } from "./Icon.tsx"
+import { Mermaid } from "./Mermaid.tsx"
+import { PackageTabs } from "./PackageTabs.tsx"
+import {
+  SortableTable,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from "./SortableTable.tsx"
+import { Tab } from "./Tab.tsx"
+import { Tabs } from "./Tabs.tsx"
+import { Toc } from "./Toc.tsx"
+import { Video } from "./Video.tsx"
+import { ZoomImage } from "./ZoomImage.tsx"
+import { Separator } from "../elements/separator.tsx"
+
+type MarkdownComponents = Record<string, ComponentType<never>>
+
+/** Renders compiled Markdown with Livemark's components for its HTML elements,
+ *  directives and code blocks; `components` adds or replaces any of them. */
+export function Markdown(props: {
+  component: ComponentType<{ components?: object }>
+  toc?: TocItem[]
+  components?: MarkdownComponents
+}) {
+  const Content = props.component
+  const content = <Content components={{ ...COMPONENTS, ...props.components }} />
+  if (!props.toc) return content
+  return <TocContext.Provider value={props.toc}>{content}</TocContext.Provider>
+}
+
+const COMPONENTS = {
+  hr: Separator,
+  img: ZoomImage,
+  pre: CodeBlock,
+  table: SortableTable,
+  thead: TableHeader,
+  tbody: TableBody,
+  tr: TableRow,
+  th: TableHead,
+  td: TableCell,
+  a: FootnoteRef,
+  Abbr,
+  AnsiCode,
+  Audio,
+  Badge,
+  Button,
+  Callout,
+  Card,
+  Cards,
+  Column,
+  Columns,
+  CodeTabs,
+  DefinitionDetail,
+  DefinitionList,
+  DefinitionTerm,
+  Details,
+  Filetree,
+  Icon,
+  Mermaid,
+  PackageTabs,
+  Tab,
+  Tabs,
+  Toc,
+  Video,
+  ...headingComponents,
+}

package/source/components/Mermaid.tsx

@@ -0,0 +1,20 @@
+import { Suspense, lazy } from "react"
+import { useMessages } from "../hooks/messages.ts"
+
+const MermaidRenderer = lazy(() => import("./MermaidRenderer.tsx"))
+
+/** Lazily loads and renders a Mermaid diagram */
+export function Mermaid(props: { children: string }) {
+  const t = useMessages()
+  return (
+    <Suspense
+      fallback={
+        <div className="not-prose mermaid flex justify-center">
+          {t("media.loadingDiagram")}
+        </div>
+      }
+    >
+      <MermaidRenderer>{props.children}</MermaidRenderer>
+    </Suspense>
+  )
+}

package/source/components/MermaidRenderer.tsx

@@ -0,0 +1,48 @@
+import { useEffect, useRef } from "react"
+import mermaid from "mermaid"
+
+mermaid.initialize({ startOnLoad: false })
+
+// Module-wide so runs never overlap, even across effect re-runs: overlapping runs on
+// one node reject with "reading 'firstChild'".
+let renderQueue = Promise.resolve()
+
+/** Renders a Mermaid diagram from a chart definition string */
+export default function MermaidRenderer(props: { children: string }) {
+  const ref = useRef<HTMLDivElement>(null)
+
+  useEffect(() => {
+    const el = ref.current
+    if (!el) return
+
+    const render = () => {
+      renderQueue = renderQueue
+        .then(() => {
+          if (!el.isConnected) return
+          const isDark = document.documentElement.classList.contains("dark")
+          mermaid.initialize({
+            startOnLoad: false,
+            theme: isDark ? "dark" : "default",
+          })
+          el.textContent = props.children
+          el.removeAttribute("data-processed")
+          return mermaid.run({ nodes: [el] })
+        })
+        .catch(error => {
+          if (el.isConnected) console.error(error)
+        })
+    }
+
+    render()
+
+    const observer = new MutationObserver(render)
+    observer.observe(document.documentElement, {
+      attributes: true,
+      attributeFilter: ["class"],
+    })
+
+    return () => observer.disconnect()
+  }, [props.children])
+
+  return <div ref={ref} className="not-prose mermaid flex justify-center" />
+}

package/source/components/PackageTabs.tsx

@@ -0,0 +1,72 @@
+import { Check, Clipboard } from "lucide-react"
+import { useState } from "react"
+import { useMessages } from "../hooks/messages.ts"
+
+type Manager = "npm" | "pnpm" | "yarn" | "bun"
+
+const managers: Manager[] = ["npm", "pnpm", "yarn", "bun"]
+
+interface PackageTabsProps {
+  npm: string
+  pnpm: string
+  yarn: string
+  bun: string
+}
+
+/** Tabbed code block showing a command for each package manager */
+export function PackageTabs(props: PackageTabsProps) {
+  const [active, setActive] = useState<Manager>("npm")
+  const [copied, setCopied] = useState(false)
+  const t = useMessages()
+
+  const commands: Record<Manager, string> = {
+    npm: props.npm,
+    pnpm: props.pnpm,
+    yarn: props.yarn,
+    bun: props.bun,
+  }
+
+  const handleCopy = () => {
+    navigator.clipboard.writeText(commands[active])
+    setCopied(true)
+    setTimeout(() => setCopied(false), 2000)
+  }
+
+  return (
+    <figure className="not-prose my-4 relative rounded-card border shadow-sm overflow-hidden text-sm bg-sidebar dark:bg-sidebar">
+      <div className="flex items-center border-b">
+        <div className="flex flex-1 items-center">
+          {managers.map(pm => (
+            <button
+              key={pm}
+              type="button"
+              onClick={() => setActive(pm)}
+              className={`px-3 py-2 text-xs font-medium transition-colors ${
+                pm === active
+                  ? "text-foreground border-b-2 border-foreground"
+                  : "text-muted-foreground hover:text-foreground"
+              }`}
+            >
+              {pm}
+            </button>
+          ))}
+        </div>
+        <button
+          type="button"
+          onClick={handleCopy}
+          className="me-2 p-1 rounded-control text-muted-foreground hover:text-foreground transition-colors"
+          aria-label={t("code.copy")}
+        >
+          {copied ? <Check className="size-3.5" /> : <Clipboard className="size-3.5" />}
+        </button>
+      </div>
+      <div className="text-[0.8125rem] py-3.5 overflow-auto max-h-[600px]">
+        <pre className="min-w-full w-max">
+          <code className="flex flex-col">
+            <span className="px-4">{commands[active]}</span>
+          </code>
+        </pre>
+      </div>
+    </figure>
+  )
+}

package/source/components/SortableTable.tsx

@@ -0,0 +1,81 @@
+import { useEffect, useRef, type ComponentProps } from "react"
+import {
+  Table,
+  TableHeader,
+  TableBody,
+  TableRow,
+  TableHead,
+  TableCell,
+} from "../elements/table.tsx"
+
+/** Wraps markdown tables with click-to-sort column headers */
+export function SortableTable(props: ComponentProps<"table">) {
+  const ref = useRef<HTMLDivElement>(null)
+
+  useEffect(() => {
+    const container = ref.current
+    if (!container) return
+
+    let activeCol = -1
+    let ascending = true
+
+    const headers = container.querySelectorAll<HTMLElement>("th")
+    const cleanups: (() => void)[] = []
+
+    headers.forEach((th, colIndex) => {
+      th.style.cursor = "pointer"
+      th.classList.add("select-none")
+
+      const handler = () => {
+        if (activeCol === colIndex) {
+          ascending = !ascending
+        } else {
+          activeCol = colIndex
+          ascending = true
+        }
+
+        const tbody = container.querySelector("tbody")
+        if (!tbody) return
+
+        const rows = Array.from(tbody.querySelectorAll("tr"))
+        rows.sort((a, b) => {
+          const aVal = a.children[colIndex]?.textContent?.trim() ?? ""
+          const bVal = b.children[colIndex]?.textContent?.trim() ?? ""
+          const aNum = Number(aVal)
+          const bNum = Number(bVal)
+          const cmp =
+            aVal !== "" && bVal !== "" && !isNaN(aNum) && !isNaN(bNum)
+              ? aNum - bNum
+              : aVal.localeCompare(bVal)
+          return ascending ? cmp : -cmp
+        })
+        for (const row of rows) tbody.appendChild(row)
+
+        headers.forEach((h, i) => {
+          const indicator = h.querySelector("[data-sort]")
+          if (indicator) indicator.remove()
+          if (i === colIndex) {
+            const span = document.createElement("span")
+            span.dataset.sort = ""
+            span.className = "ml-1 text-muted-foreground"
+            span.textContent = ascending ? "↑" : "↓"
+            h.appendChild(span)
+          }
+        })
+      }
+
+      th.addEventListener("click", handler)
+      cleanups.push(() => th.removeEventListener("click", handler))
+    })
+
+    return () => cleanups.forEach(fn => fn())
+  }, [])
+
+  return (
+    <div ref={ref} className="not-prose">
+      <Table {...props} />
+    </div>
+  )
+}
+
+export { TableHeader, TableBody, TableRow, TableHead, TableCell }

package/source/components/Tab.tsx

@@ -0,0 +1,4 @@
+/** Simple wrapper that provides a title prop for Tabs to read */
+export function Tab(props: { title: string; children: React.ReactNode }) {
+  return <div>{props.children}</div>
+}

package/source/components/Tabs.tsx

@@ -0,0 +1,75 @@
+import { Children, isValidElement, useEffect, useState } from "react"
+
+/** Tabbed container component for grouping content tabs with optional sync across groups */
+export function Tabs(props: { sync?: string; children: React.ReactNode }) {
+  const children = Children.toArray(props.children)
+  const titles = children.map(child =>
+    isValidElement<{ title: string }>(child) ? child.props.title : "",
+  )
+
+  const getInitialIndex = () => {
+    if (!props.sync) return 0
+    const saved =
+      typeof window !== "undefined"
+        ? localStorage.getItem("livemark-tab-" + props.sync)
+        : null
+    if (!saved) return 0
+    const idx = titles.indexOf(saved)
+    return idx >= 0 ? idx : 0
+  }
+
+  const [active, setActive] = useState(getInitialIndex)
+
+  const handleSelect = (i: number) => {
+    setActive(i)
+    if (props.sync) {
+      localStorage.setItem("livemark-tab-" + props.sync, titles[i]!)
+      window.dispatchEvent(
+        new CustomEvent("livemark-tab-sync", {
+          detail: { sync: props.sync, title: titles[i] },
+        }),
+      )
+    }
+  }
+
+  useEffect(() => {
+    if (!props.sync) return
+    const handler = (e: Event) => {
+      const { sync, title } = (e as CustomEvent<{ sync: string; title: string }>).detail
+      if (sync !== props.sync) return
+      const idx = titles.indexOf(title)
+      if (idx >= 0) setActive(idx)
+    }
+    window.addEventListener("livemark-tab-sync", handler)
+    return () => window.removeEventListener("livemark-tab-sync", handler)
+  }, [props.sync, titles])
+
+  return (
+    <div className="not-prose my-4 rounded-card border bg-card">
+      <div className="flex border-b">
+        {titles.map((title, i) => (
+          <button
+            key={title}
+            type="button"
+            onClick={() => handleSelect(i)}
+            className={`px-4 py-2 text-sm font-medium transition-colors cursor-pointer ${
+              i === active
+                ? "text-foreground border-b-2 border-primary -mb-px"
+                : "text-muted-foreground hover:text-foreground"
+            }`}
+          >
+            {title}
+          </button>
+        ))}
+      </div>
+      {children.map((child, i) => (
+        <div
+          key={titles[i]}
+          className={i === active ? "p-4 prose dark:prose-invert max-w-none" : "hidden"}
+        >
+          {child}
+        </div>
+      ))}
+    </div>
+  )
+}

package/source/components/Toc.tsx

@@ -0,0 +1,30 @@
+import { useTocItems } from "../helpers/toc-context.ts"
+import { useMessages } from "../hooks/messages.ts"
+
+/** Renders the page's table of contents inline within the content */
+export function Toc(props: { maxLevel?: string }) {
+  const allItems = useTocItems()
+  const t = useMessages()
+  const maxDepth = props.maxLevel ? Number(props.maxLevel) : 4
+  const items = allItems.filter(item => item.depth <= maxDepth)
+
+  if (items.length === 0) return null
+
+  return (
+    <nav className="not-prose my-8 rounded-card border border-border bg-card p-6">
+      <p className="text-base font-semibold mb-4">{t("toc.inline")}</p>
+      <ul className="text-base space-y-2.5">
+        {items.map(item => (
+          <li key={item.url} style={{ paddingLeft: `${(item.depth - 2) * 1.25}rem` }}>
+            <a
+              href={item.url}
+              className="text-muted-foreground hover:text-primary transition-colors"
+            >
+              {item.title}
+            </a>
+          </li>
+        ))}
+      </ul>
+    </nav>
+  )
+}

package/source/components/Video.tsx

@@ -0,0 +1,28 @@
+import { parseYoutubeId } from "../helpers/youtube-id.ts"
+import { useMessages } from "../hooks/messages.ts"
+/** Renders a responsive YouTube iframe embed */
+export function Video(props: { url: string }) {
+  const t = useMessages()
+  const id = parseYoutubeId(props.url)
+  if (!id) {
+    return (
+      <p>
+        <a href={props.url}>{props.url}</a>
+      </p>
+    )
+  }
+
+  return (
+    <div className="not-prose my-4 overflow-hidden rounded-card border">
+      <div className="aspect-video">
+        <iframe
+          className="h-full w-full"
+          src={`https://www.youtube.com/embed/${id}`}
+          title={t("media.youtube")}
+          allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
+          allowFullScreen
+        />
+      </div>
+    </div>
+  )
+}