@livemark/markdown 0.0.0-stage → 0.45.0

package/source/actions/processor/create.ts

@@ -0,0 +1,235 @@
+import { textlane } from "textlane"
+import * as html from "textlane/html"
+import * as md from "textlane/md"
+import * as mdx from "textlane/mdx"
+import type { MarkdownPlugins } from "../../models/plugins.ts"
+import { twoslashStage } from "../../plugins/twoslash.ts"
+
+/** The frozen textlane processor Markdown compiles with: Markdown or MDX, with the
+ *  twoslash stage only for documents that have a `twoslash` fence, and the `plugins`
+ *  in their two slots. */
+export function createProcessor(props: {
+  format: "md" | "mdx"
+  twoslash: boolean
+  outputFormat: "program" | "function-body"
+  allowDangerousHtml: boolean
+  codeThemeLight: string
+  codeThemeDark: string
+  plugins?: MarkdownPlugins
+  root?: string
+  base?: string
+}) {
+  const themes = { light: props.codeThemeLight, dark: props.codeThemeDark }
+  const processor = textlane()
+    .use(md.parse())
+    .use(md.gfm())
+    .use(md.gemoji())
+    .use(md.definitionList())
+    .use(md.math())
+    .use(md.directive())
+  if (props.format === "mdx") processor.use(md.mdx())
+  // Before md.component, which renders an unknown directive as its source text
+  processor
+    .use(props.plugins?.md ?? [])
+    .use(md.headingId({ attributes: true, markers: HEADING_MARKERS }))
+    .use(md.packageCommand({ component: "PackageTabs" }))
+    .use(md.component(COMPONENTS))
+  if (props.root !== undefined) {
+    processor.use(
+      md.pathRewrite({ root: props.root, base: props.base, nodes: ["image"] }),
+    )
+  }
+  processor.use(
+    md.toHtml({
+      allowDangerousHtml: props.allowDangerousHtml,
+      taskListLabels: TASK_LIST_LABELS,
+    }),
+  )
+  // html.katex first, or display math is a `<pre><code>` html.highlight takes for code
+  processor.use(html.katex()).use(
+    html.highlight({
+      themes,
+      // a fence with no or an unknown language still gets padding, theme colors and
+      // transformers
+      defaultLanguage: "text",
+      fallbackLanguage: "text",
+      // catppuccin-latte's green (3.2:1) and comment grey (3.8:1) sit under WCAG AA on
+      // the code background
+      colorReplacements: {
+        "catppuccin-latte": { "#40a02b": "#2a7e16", "#7c7f93": "#6c6f85" },
+      },
+      addLanguageClass: true,
+      metaProperty: "data-meta",
+      inline: "tailing-curly-colon",
+      transformers: [
+        "notationDiff",
+        "notationFocus",
+        "notationHighlight",
+        "notationErrorLevel",
+        "metaHighlight",
+        "metaWordHighlight",
+      ],
+    }),
+  )
+  // html.raw rebuilds every element and drops `data`, where code keeps its meta for
+  // html.highlight
+  // Without allowDangerousHtml md.toHtml has dropped raw HTML, which html.raw would parse
+  if (props.format === "md" && props.allowDangerousHtml) {
+    processor.use(html.raw({ passThrough: MDX_NODE_TYPES }))
+  }
+  processor.use(html.unwrapImages())
+  if (props.twoslash) processor.use(twoslashStage, { themes })
+  return processor
+    .use(props.plugins?.html ?? [])
+    .use(html.slug())
+    .use(html.extractToc({ skip: ["data-step", "data-toc-hidden"] }))
+    .use(mdx.compile({ outputFormat: props.outputFormat }))
+    .freeze()
+}
+
+const HEADING_MARKERS = {
+  "[step]": { "data-step": true },
+  "[!toc]": { "data-toc-hidden": true },
+  "[toc]": { hidden: true },
+}
+
+const TASK_LIST_LABELS = { checked: "Completed task", unchecked: "Task" }
+
+// md.toHtml hands MDX nodes to hast, which html.raw must leave as they are
+const MDX_NODE_TYPES = [
+  "mdxFlowExpression",
+  "mdxJsxFlowElement",
+  "mdxJsxTextElement",
+  "mdxTextExpression",
+  "mdxjsEsm",
+]
+
+const CALLOUTS = ["note", "tip", "info", "warning", "danger"]
+
+// Each livemark directive, alert and node as the component it renders
+const COMPONENTS = {
+  directives: [
+    {
+      name: CALLOUTS,
+      kind: "container" as const,
+      component: "Callout",
+      nameAs: "type",
+      labelAs: "title",
+      attributes: [],
+    },
+    {
+      name: "card",
+      kind: "container" as const,
+      component: "Card",
+      attributes: [{ name: "title", default: "" }, "href", "icon"],
+      group: { component: "Cards" },
+    },
+    {
+      name: "column",
+      kind: "container" as const,
+      component: "Column",
+      attributes: [],
+      group: { component: "Columns" },
+    },
+    {
+      name: "tab",
+      kind: "container" as const,
+      component: "Tab",
+      attributes: [{ name: "title", default: "" }, "sync"],
+      group: { component: "Tabs", min: 1, inherit: ["sync"] },
+    },
+    {
+      name: "details",
+      kind: "container" as const,
+      component: "Details",
+      labelAs: "summary",
+      labelDefault: "Details",
+      attributes: [],
+    },
+    {
+      name: "filetree",
+      kind: "container" as const,
+      component: "Filetree",
+      attributes: [],
+      treeAs: "tree",
+    },
+    {
+      name: "badge",
+      kind: "text" as const,
+      component: "Badge",
+      labelAs: "label",
+      attributes: ["variant"],
+    },
+    {
+      name: "button",
+      kind: "leaf" as const,
+      component: "Button",
+      labelAs: "label",
+      attributes: ["href", "label", "variant", "size"],
+      required: ["href", "label"],
+    },
+    {
+      name: "icon",
+      kind: "text" as const,
+      component: "Icon",
+      attributes: ["name", "className"],
+      required: ["name"],
+    },
+    {
+      name: "abbr",
+      kind: "text" as const,
+      component: "Abbr",
+      labelAs: "text",
+      attributes: [{ name: "title", default: "" }],
+    },
+    {
+      name: "toc",
+      kind: "leaf" as const,
+      component: "Toc",
+      attributes: ["maxLevel"],
+    },
+    {
+      name: "video",
+      kind: "leaf" as const,
+      where: { type: "youtube" },
+      component: "Video",
+      attributes: ["url"],
+      required: ["url"],
+    },
+    {
+      name: "audio",
+      kind: "leaf" as const,
+      where: { type: "soundcloud" },
+      component: "Audio",
+      attributes: ["url"],
+      required: ["url"],
+    },
+  ],
+  alerts: {
+    component: "Callout",
+    typeAs: "type",
+    types: {
+      NOTE: "note",
+      TIP: "tip",
+      WARNING: "warning",
+      CAUTION: "danger",
+      IMPORTANT: "info",
+    },
+  },
+  nodes: {
+    defList: "DefinitionList",
+    defListTerm: "DefinitionTerm",
+    defListDescription: "DefinitionDetail",
+  },
+  codes: [
+    { lang: "mermaid", component: "Mermaid" },
+    { lang: "ansi", component: "AnsiCode" },
+    { meta: "tab", group: { component: "CodeTabs", collect: "tabs", inherit: ["sync"] } },
+  ],
+  unknownDirectives: "source" as const,
+}
+
+/** Every directive name an article may use; any other renders as its source text. */
+export const DIRECTIVE_NAMES = new Set(
+  COMPONENTS.directives.flatMap(directive => directive.name),
+)

package/source/components/Abbr.tsx

@@ -0,0 +1,13 @@
+import { Tooltip, TooltipContent, TooltipTrigger } from "../elements/tooltip.tsx"
+
+/** Renders an abbreviation with a shadcn tooltip showing its full form */
+export function Abbr(props: { text: string; title: string }) {
+  return (
+    <Tooltip>
+      <TooltipTrigger className="border-b border-dotted border-muted-foreground cursor-help">
+        {props.text}
+      </TooltipTrigger>
+      <TooltipContent>{props.title}</TooltipContent>
+    </Tooltip>
+  )
+}

package/source/components/AnsiCode.tsx

@@ -0,0 +1,17 @@
+import { ansiToHtml } from "../helpers/ansi.ts"
+
+/** Renders terminal output, coloring its ANSI escape sequences */
+export function AnsiCode(props: { children: string }) {
+  return (
+    <figure className="shiki not-prose my-4 relative rounded-card border shadow-sm overflow-hidden text-sm bg-sidebar dark:bg-sidebar">
+      <div className="text-[0.8125rem] py-3.5 overflow-auto">
+        <pre className="min-w-full w-max">
+          <code
+            className="flex flex-col"
+            dangerouslySetInnerHTML={{ __html: ansiToHtml(props.children) }}
+          />
+        </pre>
+      </div>
+    </figure>
+  )
+}

package/source/components/Audio.tsx

@@ -0,0 +1,18 @@
+import { useMessages } from "../hooks/messages.ts"
+/** Renders a SoundCloud iframe embed */
+export function Audio(props: { url: string }) {
+  const t = useMessages()
+  const src = `https://w.soundcloud.com/player/?url=${encodeURIComponent(props.url)}&color=%23ff5500&auto_play=false&hide_related=true&show_comments=false&show_user=true&show_reposts=false&show_teaser=false`
+
+  return (
+    <div className="not-prose my-4 overflow-hidden rounded-card border">
+      <iframe
+        className="w-full"
+        height={166}
+        src={src}
+        title={t("media.soundcloud")}
+        allow="autoplay"
+      />
+    </div>
+  )
+}

package/source/components/Badge.tsx

@@ -0,0 +1,9 @@
+import { Badge as BadgeElement } from "../elements/badge.tsx"
+
+/** Inline badge rendered from :badge text directives */
+export function Badge(props: {
+  label: string
+  variant?: "default" | "secondary" | "positive" | "warning" | "destructive" | "outline"
+}) {
+  return <BadgeElement variant={props.variant}>{props.label}</BadgeElement>
+}

package/source/components/Button.tsx

@@ -0,0 +1,33 @@
+import { buttonVariants } from "../elements/button.tsx"
+import { cn } from "cn"
+
+/** Styled link button rendered from ::button leaf directives */
+export function Button(props: {
+  href: string
+  label: string
+  variant?:
+    | "default"
+    | "outline"
+    | "secondary"
+    | "ghost"
+    | "positive"
+    | "warning"
+    | "destructive"
+    | "link"
+  size?: "default" | "sm" | "lg"
+}) {
+  return (
+    <a
+      href={props.href}
+      className={cn(
+        buttonVariants({
+          variant: props.variant,
+          size: props.size,
+        }),
+        "no-underline",
+      )}
+    >
+      {props.label}
+    </a>
+  )
+}

package/source/components/Callout.tsx

@@ -0,0 +1,68 @@
+import { AlertTriangle, Flame, Info, Lightbulb } from "lucide-react"
+import { cn } from "cn"
+import type { MessageKey } from "../models/message.ts"
+import { useMessages } from "../hooks/messages.ts"
+
+type CalloutType = "note" | "tip" | "info" | "warning" | "danger"
+
+interface CalloutConfig {
+  icon: React.ElementType
+  label: MessageKey
+  classes: string
+}
+
+const configs: Record<CalloutType, CalloutConfig> = {
+  note: {
+    icon: Info,
+    label: "callout.note",
+    classes:
+      "border-blue-500/30 bg-blue-50/50 text-blue-900 dark:bg-blue-950/30 dark:text-blue-200",
+  },
+  info: {
+    icon: Info,
+    label: "callout.info",
+    classes:
+      "border-blue-500/30 bg-blue-50/50 text-blue-900 dark:bg-blue-950/30 dark:text-blue-200",
+  },
+  tip: {
+    icon: Lightbulb,
+    label: "callout.tip",
+    classes: "border-positive/30 bg-positive-tint/50 text-positive-tint-foreground",
+  },
+  warning: {
+    icon: AlertTriangle,
+    label: "callout.warning",
+    classes: "border-warning/30 bg-warning-tint/50 text-warning-tint-foreground",
+  },
+  danger: {
+    icon: Flame,
+    label: "callout.danger",
+    classes:
+      "border-destructive/30 bg-destructive-tint/50 text-destructive-tint-foreground",
+  },
+}
+
+/** Styled callout block for notes, tips, warnings, and other admonitions */
+export function Callout(props: {
+  type?: CalloutType
+  title?: string
+  children: React.ReactNode
+}) {
+  const t = useMessages()
+  const type = props.type ?? "note"
+  const config = configs[type]
+  const Icon = config.icon
+  const title = props.title ?? t(config.label)
+
+  return (
+    <aside className={cn("not-prose my-4 rounded-card border px-4 py-3", config.classes)}>
+      <div className="flex items-center gap-2 font-semibold text-sm mb-2">
+        <Icon className="size-4 shrink-0" />
+        <span>{title}</span>
+      </div>
+      <div className="text-sm [&>p]:my-1 [&>p:first-child]:mt-0 [&>p:last-child]:mb-0">
+        {props.children}
+      </div>
+    </aside>
+  )
+}

package/source/components/Card.tsx

@@ -0,0 +1,48 @@
+import { Link } from "@tanstack/react-router"
+import { DynamicIcon } from "../helpers/dynamic-icon.tsx"
+import {
+  Card as CardElement,
+  CardContent,
+  CardHeader,
+  CardTitle,
+} from "../elements/card.tsx"
+
+/** Card component with optional icon, title, description, and link */
+export function Card(props: {
+  title: string
+  href?: string
+  icon?: string
+  children?: React.ReactNode
+}) {
+  const card = (
+    <CardElement size="sm" className="transition-colors hover:bg-accent">
+      <CardHeader>
+        <CardTitle className="flex items-center gap-2">
+          {props.icon && (
+            <DynamicIcon name={props.icon} className="size-5 text-primary" />
+          )}
+          {props.title}
+        </CardTitle>
+      </CardHeader>
+      {props.children && (
+        <CardContent>
+          <div className="text-muted-foreground text-sm">{props.children}</div>
+        </CardContent>
+      )}
+    </CardElement>
+  )
+
+  if (props.href?.startsWith("http")) {
+    return (
+      <a href={props.href} target="_blank" rel="noopener noreferrer">
+        {card}
+      </a>
+    )
+  }
+
+  if (props.href) {
+    return <Link to={props.href}>{card}</Link>
+  }
+
+  return card
+}

package/source/components/Cards.tsx

@@ -0,0 +1,8 @@
+/** Grid container for card components */
+export function Cards(props: { children: React.ReactNode }) {
+  return (
+    <div className="not-prose grid grid-cols-1 gap-4 my-4 sm:grid-cols-2">
+      {props.children}
+    </div>
+  )
+}

package/source/components/CodeBlock.tsx

@@ -0,0 +1,144 @@
+import { Check, ChevronDown, Clipboard, WrapText } from "lucide-react"
+import { isValidElement, useRef, useState } from "react"
+import type { ReactNode } from "react"
+import { Tooltip, TooltipContent, TooltipTrigger } from "../elements/tooltip.tsx"
+import { readCodeIcon } from "../helpers/code-icon.ts"
+import { useMessages } from "../hooks/messages.ts"
+
+export function CodeBlock(props: React.ComponentProps<"pre">) {
+  const [copied, setCopied] = useState(false)
+  const t = useMessages()
+  const [wrap, setWrap] = useState(false)
+  const [expanded, setExpanded] = useState(false)
+  const preRef = useRef<HTMLPreElement>(null)
+  const extra = props as Record<string, unknown>
+  const meta = extra["data-meta"] as string | undefined
+  const title = meta?.match(/title="([^"]+)"/)?.[1]
+  const maxLines = meta?.match(/maxLines=(\d+)/)?.[1]
+  const icon = readCodeIcon(readLanguage(props.children))
+  const lineNumbers = meta?.match(/\blineNumbers(?:=(\d+))?(?!\S)/)
+  const style = props.style as Record<string, string> | undefined
+  const collapsedHeight = maxLines ? `${Number(maxLines) * 1.5 + 1.75}rem` : undefined
+
+  const handleCopy = () => {
+    const text = preRef.current?.textContent ?? ""
+    navigator.clipboard.writeText(text)
+    setCopied(true)
+    setTimeout(() => setCopied(false), 2000)
+  }
+
+  const handleWrapToggle = () => {
+    setWrap(prev => !prev)
+  }
+
+  return (
+    <figure
+      className="shiki not-prose my-4 relative rounded-card border shadow-sm overflow-hidden text-sm bg-sidebar dark:bg-sidebar"
+      style={{ ...style, backgroundColor: undefined }}
+    >
+      {title ? (
+        <div className="flex items-center gap-2 h-9.5 border-b px-4 text-muted-foreground">
+          {icon && (
+            <span
+              className="size-3.5 [&>svg]:size-full"
+              dangerouslySetInnerHTML={{ __html: icon }}
+            />
+          )}
+          <span className="flex-1 truncate text-xs font-medium">{title}</span>
+          <Tooltip>
+            <TooltipTrigger
+              onClick={handleWrapToggle}
+              aria-label={wrap ? t("code.wrapOff") : t("code.wrapOn")}
+              className={`-me-2 p-1.5 rounded-control hover:text-foreground transition-colors ${wrap ? "text-foreground" : ""}`}
+            >
+              <WrapText className="size-3.5" />
+            </TooltipTrigger>
+            <TooltipContent>{wrap ? t("code.wrapOff") : t("code.wrapOn")}</TooltipContent>
+          </Tooltip>
+          <Tooltip>
+            <TooltipTrigger
+              onClick={handleCopy}
+              aria-label={copied ? t("code.copied") : t("code.copy")}
+              className="-me-2 p-1.5 rounded-control hover:text-foreground transition-colors"
+            >
+              {copied ? (
+                <Check className="size-3.5" />
+              ) : (
+                <Clipboard className="size-3.5" />
+              )}
+            </TooltipTrigger>
+            <TooltipContent>{copied ? t("code.copied") : t("code.copy")}</TooltipContent>
+          </Tooltip>
+        </div>
+      ) : (
+        <div className="empty:hidden absolute top-2 right-2 z-10 backdrop-blur-lg rounded-control text-muted-foreground">
+          <Tooltip>
+            <TooltipTrigger
+              onClick={handleWrapToggle}
+              aria-label={wrap ? t("code.wrapOff") : t("code.wrapOn")}
+              className={`p-1.5 rounded-control hover:text-foreground transition-colors ${wrap ? "text-foreground" : ""}`}
+            >
+              <WrapText className="size-3.5" />
+            </TooltipTrigger>
+            <TooltipContent>{wrap ? t("code.wrapOff") : t("code.wrapOn")}</TooltipContent>
+          </Tooltip>
+          <Tooltip>
+            <TooltipTrigger
+              onClick={handleCopy}
+              aria-label={copied ? t("code.copied") : t("code.copy")}
+              className="p-1.5 rounded-control hover:text-foreground transition-colors"
+            >
+              {copied ? (
+                <Check className="size-3.5" />
+              ) : (
+                <Clipboard className="size-3.5" />
+              )}
+            </TooltipTrigger>
+            <TooltipContent>{copied ? t("code.copied") : t("code.copy")}</TooltipContent>
+          </Tooltip>
+        </div>
+      )}
+      <div
+        className="text-[0.8125rem] py-3.5 overflow-auto transition-[max-height] duration-300"
+        style={{
+          maxHeight: collapsedHeight && !expanded ? collapsedHeight : "600px",
+        }}
+      >
+        <pre
+          {...props}
+          ref={preRef}
+          style={
+            lineNumbers
+              ? { counterReset: `line ${Number(lineNumbers[1] ?? 1) - 1}` }
+              : undefined
+          }
+          className={[
+            props.className,
+            lineNumbers && "line-numbers",
+            wrap
+              ? "min-w-full whitespace-pre-wrap break-words [&>code]:flex [&>code]:flex-col"
+              : "min-w-full w-max [&>code]:flex [&>code]:flex-col",
+          ]
+            .filter(Boolean)
+            .join(" ")}
+        />
+      </div>
+      {collapsedHeight && !expanded && (
+        <button
+          type="button"
+          onClick={() => setExpanded(true)}
+          className="flex items-center justify-center gap-1 w-full py-1.5 text-xs text-muted-foreground hover:text-foreground border-t cursor-pointer transition-colors"
+        >
+          <ChevronDown className="size-3.5" />
+          {t("code.expand")}
+        </button>
+      )}
+    </figure>
+  )
+}
+
+// html.highlight names the language in a class of the `<code>` inside `<pre>`
+function readLanguage(children: ReactNode) {
+  if (!isValidElement<{ className?: string }>(children)) return undefined
+  return children.props.className?.match(/\blanguage-(\S+)/)?.[1]
+}

package/source/components/CodeTabs.tsx

@@ -0,0 +1,81 @@
+import { Children, useEffect, useState } from "react"
+
+/** Tabbed code block component for grouping multiple code blocks with optional sync */
+export function CodeTabs(props: {
+  tabs: string
+  sync?: string
+  children: React.ReactNode
+}) {
+  const names = JSON.parse(props.tabs) as string[]
+  const children = Children.toArray(props.children)
+
+  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 = names.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, names[i]!)
+      window.dispatchEvent(
+        new CustomEvent("livemark-tab-sync", {
+          detail: { sync: props.sync, title: names[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 = names.indexOf(title)
+      if (idx >= 0) setActive(idx)
+    }
+    window.addEventListener("livemark-tab-sync", handler)
+    return () => window.removeEventListener("livemark-tab-sync", handler)
+  }, [props.sync, names])
+
+  return (
+    <div className="not-prose my-4 rounded-card border shadow-sm overflow-hidden text-sm bg-sidebar dark:bg-sidebar">
+      <div className="flex border-b">
+        {names.map((name, i) => (
+          <button
+            key={name}
+            type="button"
+            onClick={() => handleSelect(i)}
+            className={`px-4 py-2 text-xs font-medium transition-colors cursor-pointer ${
+              i === active
+                ? "text-foreground border-b-2 border-primary -mb-px"
+                : "text-muted-foreground hover:text-foreground"
+            }`}
+          >
+            {name}
+          </button>
+        ))}
+      </div>
+      {children.map((child, i) => (
+        <div
+          key={names[i]}
+          className={
+            i === active
+              ? "[&>figure]:my-0 [&>figure]:rounded-none [&>figure]:border-0 [&>figure]:shadow-none"
+              : "hidden"
+          }
+        >
+          {child}
+        </div>
+      ))}
+    </div>
+  )
+}

package/source/components/Column.tsx

@@ -0,0 +1,4 @@
+/** Single column within a Columns grid */
+export function Column(props: { children: React.ReactNode }) {
+  return <div className="max-w-none">{props.children}</div>
+}