livemark 0.2.0 → 0.7.0

package/build/website/plugins/remark-button.unit.ts

@@ -0,0 +1,147 @@
+import type { Root } from "mdast"
+import type { LeafDirective } from "mdast-util-directive"
+import { describe, expect, it } from "vite-plus/test"
+import { transformButtonDirectives } from "./remark-button.ts"
+
+function makeLeafDirective(
+  name: string,
+  attributes: Record<string, string>,
+  children: LeafDirective["children"] = [],
+): LeafDirective {
+  return {
+    type: "leafDirective" as LeafDirective["type"],
+    name,
+    attributes,
+    children,
+  }
+}
+
+function makeTree(...children: Root["children"]): Root {
+  return { type: "root", children }
+}
+
+function process(tree: Root) {
+  transformButtonDirectives(tree)
+  return tree
+}
+
+describe("transformButtonDirectives", () => {
+  it("should convert ::button with bracket text to LinkButton JSX element", () => {
+    const tree = process(
+      makeTree(
+        makeLeafDirective("button", { href: "/start" }, [
+          { type: "text", value: "Get Started" },
+        ]),
+      ),
+    )
+    const node = tree.children[0]
+    expect(node).toMatchObject({
+      type: "mdxJsxFlowElement",
+      name: "LinkButton",
+      attributes: [
+        { type: "mdxJsxAttribute", name: "href", value: "/start" },
+        { type: "mdxJsxAttribute", name: "label", value: "Get Started" },
+      ],
+    })
+  })
+
+  it("should convert ::button with label attribute to LinkButton JSX element", () => {
+    const tree = process(
+      makeTree(
+        makeLeafDirective("button", { href: "/docs", label: "Read Docs" }),
+      ),
+    )
+    const node = tree.children[0]
+    expect(node).toMatchObject({
+      type: "mdxJsxFlowElement",
+      name: "LinkButton",
+      attributes: [
+        { type: "mdxJsxAttribute", name: "href", value: "/docs" },
+        { type: "mdxJsxAttribute", name: "label", value: "Read Docs" },
+      ],
+    })
+  })
+
+  it("should prefer bracket text over label attribute", () => {
+    const tree = process(
+      makeTree(
+        makeLeafDirective("button", { href: "/x", label: "Fallback" }, [
+          { type: "text", value: "Primary" },
+        ]),
+      ),
+    )
+    const node = tree.children[0]
+    expect(node).toMatchObject({
+      type: "mdxJsxFlowElement",
+      name: "LinkButton",
+      attributes: [
+        { type: "mdxJsxAttribute", name: "href", value: "/x" },
+        { type: "mdxJsxAttribute", name: "label", value: "Primary" },
+      ],
+    })
+  })
+
+  it("should pass variant attribute when provided", () => {
+    const tree = process(
+      makeTree(
+        makeLeafDirective("button", { href: "/a", variant: "outline" }, [
+          { type: "text", value: "Click" },
+        ]),
+      ),
+    )
+    const node = tree.children[0]
+    expect(node).toMatchObject({
+      type: "mdxJsxFlowElement",
+      name: "LinkButton",
+      attributes: [
+        { type: "mdxJsxAttribute", name: "href", value: "/a" },
+        { type: "mdxJsxAttribute", name: "label", value: "Click" },
+        { type: "mdxJsxAttribute", name: "variant", value: "outline" },
+      ],
+    })
+  })
+
+  it("should pass size attribute when provided", () => {
+    const tree = process(
+      makeTree(
+        makeLeafDirective("button", { href: "/a", size: "lg" }, [
+          { type: "text", value: "Big" },
+        ]),
+      ),
+    )
+    const node = tree.children[0]
+    expect(node).toMatchObject({
+      type: "mdxJsxFlowElement",
+      name: "LinkButton",
+      attributes: [
+        { type: "mdxJsxAttribute", name: "href", value: "/a" },
+        { type: "mdxJsxAttribute", name: "label", value: "Big" },
+        { type: "mdxJsxAttribute", name: "size", value: "lg" },
+      ],
+    })
+  })
+
+  it("should skip button directive without href", () => {
+    const tree = process(
+      makeTree(makeLeafDirective("button", { label: "No Link" })),
+    )
+    const node = tree.children[0]
+    expect(node).toMatchObject({ type: "leafDirective", name: "button" })
+  })
+
+  it("should skip button directive without label or bracket text", () => {
+    const tree = process(
+      makeTree(makeLeafDirective("button", { href: "/no-label" })),
+    )
+    const node = tree.children[0]
+    expect(node).toMatchObject({ type: "leafDirective", name: "button" })
+  })
+
+  it("should ignore unrelated leaf directives", () => {
+    const tree = process(
+      makeTree(makeLeafDirective("video", { type: "youtube", id: "abc" })),
+    )
+    const node = tree.children[0]
+    expect(node).toMatchObject({ type: "leafDirective", name: "video" })
+  })
+})

package/build/website/plugins/remark-callout.ts

@@ -0,0 +1,57 @@
+import type { Paragraph, Root } from "mdast"
+import type { ContainerDirective } from "mdast-util-directive"
+import type { Plugin } from "unified"
+import { visit } from "unist-util-visit"
+
+const calloutTypes = new Set(["note", "tip", "info", "warning", "danger"])
+
+/** Remark plugin that converts container directives into Callout JSX elements */
+export const remarkCallout: Plugin<[], Root> = () => {
+  return tree => {
+    visit(
+      tree,
+      "containerDirective",
+      (node: ContainerDirective, index, parent) => {
+        if (!calloutTypes.has(node.name) || index === undefined || !parent)
+          return
+
+        const labelParagraph = node.children.find(
+          (child): child is Paragraph =>
+            child.type === "paragraph" && !!child.data?.directiveLabel,
+        )
+
+        const title = labelParagraph
+          ? {
+              type: "mdxJsxAttribute" as const,
+              name: "title",
+              value: labelParagraph.children
+                .map(c => ("value" in c ? String(c.value) : ""))
+                .join(""),
+            }
+          : undefined
+
+        const body = node.children.filter(
+          child => !(child.type === "paragraph" && child.data?.directiveLabel),
+        )
+
+        const jsxNode = {
+          type: "mdxJsxFlowElement" as const,
+          name: "Callout",
+          attributes: [
+            {
+              type: "mdxJsxAttribute" as const,
+              name: "type",
+              value: node.name,
+            },
+            ...(title ? [title] : []),
+          ],
+          children: body,
+          data: { _mdxExplicitJsx: true },
+        }
+
+        // @ts-expect-error mdxJsxFlowElement is not in mdast types
+        parent.children.splice(index, 1, jsxNode)
+      },
+    )
+  }
+}

package/build/website/plugins/remark-card.ts

@@ -0,0 +1,80 @@
+import type { Root } from "mdast"
+import type { ContainerDirective } from "mdast-util-directive"
+import type { Plugin } from "unified"
+import { visit, SKIP } from "unist-util-visit"
+
+/** Remark plugin that converts :::card directives into Card/Cards JSX elements */
+export const remarkCard: Plugin<[], Root> = () => {
+  return tree => {
+    visit(
+      tree,
+      "containerDirective",
+      (node: ContainerDirective, index, parent) => {
+        if (node.name !== "card" || index === undefined || !parent) return
+
+        const title = node.attributes?.title ?? ""
+        const href = node.attributes?.href
+        const icon = node.attributes?.icon
+
+        const attributes = [
+          { type: "mdxJsxAttribute" as const, name: "title", value: title },
+          ...(href
+            ? [{ type: "mdxJsxAttribute" as const, name: "href", value: href }]
+            : []),
+          ...(icon
+            ? [{ type: "mdxJsxAttribute" as const, name: "icon", value: icon }]
+            : []),
+        ]
+
+        const jsxNode = {
+          type: "mdxJsxFlowElement" as const,
+          name: "Card",
+          attributes,
+          children: node.children,
+          data: { _mdxExplicitJsx: true },
+        }
+
+        // @ts-expect-error mdxJsxFlowElement is not in mdast types
+        parent.children[index] = jsxNode
+        return SKIP
+      },
+    )
+
+    const children = tree.children
+    let i = 0
+    while (i < children.length) {
+      const node = children[i]
+      // @ts-expect-error mdxJsxFlowElement is not in mdast types
+      if (node?.type !== "mdxJsxFlowElement" || node.name !== "Card") {
+        i++
+        continue
+      }
+
+      let j = i + 1
+      while (j < children.length) {
+        const next = children[j]
+        // @ts-expect-error mdxJsxFlowElement is not in mdast types
+        if (next?.type !== "mdxJsxFlowElement" || next.name !== "Card") break
+        j++
+      }
+
+      if (j - i < 2) {
+        i++
+        continue
+      }
+
+      const group = children.slice(i, j)
+      const wrapper = {
+        type: "mdxJsxFlowElement" as const,
+        name: "Cards",
+        attributes: [],
+        children: group,
+        data: { _mdxExplicitJsx: true },
+      }
+
+      // @ts-expect-error mdxJsxFlowElement is not in mdast types
+      children.splice(i, j - i, wrapper)
+      i++
+    }
+  }
+}

package/build/website/plugins/remark-code-tabs.ts

@@ -0,0 +1,87 @@
+import type { Code, Root } from "mdast"
+import type { Plugin } from "unified"
+
+const TAB_PATTERN = /\btab="([^"]+)"/
+const SYNC_PATTERN = /\bsync="([^"]+)"/
+
+/** Remark plugin that groups consecutive code blocks with tab="name" meta into a CodeTabs component */
+export const remarkCodeTabs: Plugin<[], Root> = () => {
+  return tree => {
+    const children = tree.children
+    let i = 0
+
+    while (i < children.length) {
+      const node = children[i]
+      if (node?.type !== "code" || !node.meta) {
+        i++
+        continue
+      }
+
+      const firstMatch = TAB_PATTERN.exec(node.meta)
+      if (!firstMatch) {
+        i++
+        continue
+      }
+
+      const group: { name: string; code: Code }[] = [
+        { name: firstMatch[1]!, code: node },
+      ]
+
+      let j = i + 1
+      while (j < children.length) {
+        const next = children[j]
+        if (next?.type !== "code" || !next.meta) break
+        const nextMatch = TAB_PATTERN.exec(next.meta)
+        if (!nextMatch) break
+        group.push({ name: nextMatch[1]!, code: next })
+        j++
+      }
+
+      if (group.length < 2) {
+        i++
+        continue
+      }
+
+      const firstMeta = group[0]!.code.meta!
+      const syncMatch = SYNC_PATTERN.exec(firstMeta)
+
+      for (const item of group) {
+        item.code.meta =
+          item.code
+            .meta!.replace(TAB_PATTERN, "")
+            .replace(SYNC_PATTERN, "")
+            .trim() || null
+      }
+
+      const codeTabsAttrs: {
+        type: "mdxJsxAttribute"
+        name: string
+        value: string
+      }[] = [
+        {
+          type: "mdxJsxAttribute",
+          name: "tabs",
+          value: JSON.stringify(group.map(g => g.name)),
+        },
+      ]
+      if (syncMatch) {
+        codeTabsAttrs.push({
+          type: "mdxJsxAttribute",
+          name: "sync",
+          value: syncMatch[1]!,
+        })
+      }
+
+      const jsxNode = {
+        type: "mdxJsxFlowElement",
+        name: "CodeTabs",
+        attributes: codeTabsAttrs,
+        children: group.map(g => g.code),
+      }
+
+      // @ts-expect-error mdxJsxFlowElement is not in mdast types
+      children.splice(i, group.length, jsxNode)
+      i++
+    }
+  }
+}

package/build/website/plugins/remark-columns.ts

@@ -0,0 +1,66 @@
+import type { Root } from "mdast"
+import type { ContainerDirective } from "mdast-util-directive"
+import type { Plugin } from "unified"
+import { visit, SKIP } from "unist-util-visit"
+
+/** Remark plugin that converts consecutive :::column directives into a Columns grid */
+export const remarkColumns: Plugin<[], Root> = () => {
+  return tree => {
+    visit(
+      tree,
+      "containerDirective",
+      (node: ContainerDirective, index, parent) => {
+        if (node.name !== "column" || index === undefined || !parent) return
+
+        const jsxNode = {
+          type: "mdxJsxFlowElement" as const,
+          name: "Column",
+          attributes: [],
+          children: node.children,
+          data: { _mdxExplicitJsx: true },
+        }
+
+        // @ts-expect-error mdxJsxFlowElement is not in mdast types
+        parent.children[index] = jsxNode
+        return SKIP
+      },
+    )
+
+    const children = tree.children
+    let i = 0
+    while (i < children.length) {
+      const node = children[i]
+      // @ts-expect-error mdxJsxFlowElement is not in mdast types
+      if (node?.type !== "mdxJsxFlowElement" || node.name !== "Column") {
+        i++
+        continue
+      }
+
+      let j = i + 1
+      while (j < children.length) {
+        const next = children[j]
+        // @ts-expect-error mdxJsxFlowElement is not in mdast types
+        if (next?.type !== "mdxJsxFlowElement" || next.name !== "Column") break
+        j++
+      }
+
+      if (j - i < 2) {
+        i++
+        continue
+      }
+
+      const group = children.slice(i, j)
+      const wrapper = {
+        type: "mdxJsxFlowElement" as const,
+        name: "Columns",
+        attributes: [],
+        children: group,
+        data: { _mdxExplicitJsx: true },
+      }
+
+      // @ts-expect-error mdxJsxFlowElement is not in mdast types
+      children.splice(i, j - i, wrapper)
+      i++
+    }
+  }
+}

package/build/website/plugins/remark-custom-heading-id.ts

@@ -0,0 +1,70 @@
+import type { Heading, Root } from "mdast"
+import type { Plugin } from "unified"
+import { SKIP, visit } from "unist-util-visit"
+
+declare module "mdast" {
+  interface HeadingData {
+    hProperties?: Record<string, string | number | boolean | null | undefined>
+  }
+}
+
+const CUSTOM_ID_PATTERN = /\s*\[#([^\]]+)\]\s*$/
+const TOC_HIDDEN_PATTERN = /\s*\[!toc\]\s*$/
+const TOC_ONLY_PATTERN = /\s*\[toc\]\s*$/
+
+/** Walk a mdast tree and process heading annotations: `[#id]`, `[!toc]`, and `[toc]` */
+export function transformHeadingAnnotations(tree: Root) {
+  visit(tree, "heading", (node: Heading, index, parent) => {
+    const lastChild = node.children[node.children.length - 1]
+    if (!lastChild || lastChild.type !== "text") return undefined
+
+    if (TOC_ONLY_PATTERN.test(lastChild.value)) {
+      if (parent && index !== undefined) {
+        parent.children.splice(index, 1)
+        return [SKIP, index] as const
+      }
+      return undefined
+    }
+
+    if (TOC_HIDDEN_PATTERN.test(lastChild.value)) {
+      lastChild.value = lastChild.value.replace(TOC_HIDDEN_PATTERN, "")
+      if (lastChild.value === "" && node.children.length > 1) {
+        node.children.pop()
+      }
+      node.data = node.data ?? {}
+      node.data.hProperties = {
+        ...node.data.hProperties,
+        "data-toc-hidden": true,
+      }
+      return undefined
+    }
+
+    const match = CUSTOM_ID_PATTERN.exec(lastChild.value)
+    if (!match) return undefined
+
+    const customId = match[1]
+    if (!customId) return undefined
+
+    lastChild.value = lastChild.value.replace(CUSTOM_ID_PATTERN, "")
+
+    if (lastChild.value === "" && node.children.length > 1) {
+      node.children.pop()
+    }
+
+    node.data = node.data ?? {}
+    node.data.hProperties = { ...node.data.hProperties, id: customId }
+    return undefined
+  })
+}
+
+/** @deprecated Use transformHeadingAnnotations instead */
+export const transformCustomHeadingIds = transformHeadingAnnotations
+
+/** Remark plugin that processes heading annotations: `[#custom-id]`, `[!toc]`, and `[toc]` */
+const remarkCustomHeadingId: Plugin<[], Root> = () => {
+  return tree => {
+    transformHeadingAnnotations(tree)
+  }
+}
+
+export default remarkCustomHeadingId

package/build/website/plugins/remark-custom-heading-id.unit.ts

@@ -0,0 +1,131 @@
+import type { Heading, Root, Text } from "mdast"
+import { describe, expect, it } from "vite-plus/test"
+import {
+  transformCustomHeadingIds,
+  transformHeadingAnnotations,
+} from "./remark-custom-heading-id.ts"
+
+function makeHeading(depth: 1 | 2 | 3 | 4 | 5 | 6, text: string): Heading {
+  return { type: "heading", depth, children: [{ type: "text", value: text }] }
+}
+
+function makeBoldHeading(boldText: string, trailingText: string): Heading {
+  return {
+    type: "heading",
+    depth: 2,
+    children: [
+      { type: "strong", children: [{ type: "text", value: boldText }] },
+      { type: "text", value: trailingText },
+    ],
+  }
+}
+
+function makeTree(...headings: Heading[]): Root {
+  return { type: "root", children: headings }
+}
+
+function findHeading(tree: Root, index: number): Heading {
+  const node = tree.children[index]
+  if (!node || node.type !== "heading") throw new Error("No heading at index")
+  return node
+}
+
+function headingText(heading: Heading): string {
+  return heading.children
+    .filter((c): c is Text => c.type === "text")
+    .map(c => c.value)
+    .join("")
+}
+
+describe("transformHeadingAnnotations", () => {
+  function process(tree: Root) {
+    transformHeadingAnnotations(tree)
+    return tree
+  }
+
+  it("should set a custom id from [#custom-id] syntax", () => {
+    const tree = process(makeTree(makeHeading(2, "My Heading [#custom-id]")))
+    const heading = findHeading(tree, 0)
+    expect(heading.data?.hProperties).toEqual({ id: "custom-id" })
+    expect(headingText(heading)).toBe("My Heading")
+  })
+
+  it("should leave headings without custom ids unchanged", () => {
+    const tree = process(makeTree(makeHeading(2, "Normal Heading")))
+    const heading = findHeading(tree, 0)
+    expect(heading.data).toBeUndefined()
+    expect(headingText(heading)).toBe("Normal Heading")
+  })
+
+  it("should handle different heading depths", () => {
+    const tree = process(
+      makeTree(
+        makeHeading(3, "Deep Heading [#deep]"),
+        makeHeading(4, "Deeper Heading [#deeper]"),
+      ),
+    )
+
+    const h3 = findHeading(tree, 0)
+    expect(h3.data?.hProperties).toEqual({ id: "deep" })
+    expect(h3.depth).toBe(3)
+
+    const h4 = findHeading(tree, 1)
+    expect(h4.data?.hProperties).toEqual({ id: "deeper" })
+    expect(h4.depth).toBe(4)
+  })
+
+  it("should handle ids with hyphens and numbers", () => {
+    const tree = process(
+      makeTree(makeHeading(2, "Section 1 [#section-1-intro]")),
+    )
+    const heading = findHeading(tree, 0)
+    expect(heading.data?.hProperties).toEqual({ id: "section-1-intro" })
+    expect(headingText(heading)).toBe("Section 1")
+  })
+
+  it("should preserve inline formatting before the id", () => {
+    const tree = process(
+      makeTree(makeBoldHeading("Bold", " heading [#bold-heading]")),
+    )
+    const heading = findHeading(tree, 0)
+    expect(heading.data?.hProperties).toEqual({ id: "bold-heading" })
+    expect(heading.children.some(c => c.type === "strong")).toBe(true)
+    expect(headingText(heading)).toBe(" heading")
+  })
+
+  it("should add data-toc-hidden for [!toc] headings", () => {
+    const tree = process(makeTree(makeHeading(2, "Hidden Heading [!toc]")))
+    const heading = findHeading(tree, 0)
+    expect(heading.data?.hProperties).toEqual({ "data-toc-hidden": true })
+    expect(headingText(heading)).toBe("Hidden Heading")
+  })
+
+  it("should remove [toc] headings from the tree", () => {
+    const tree = process(
+      makeTree(
+        makeHeading(2, "Visible Heading"),
+        makeHeading(2, "TOC Only Heading [toc]"),
+        makeHeading(3, "Another Visible"),
+      ),
+    )
+    expect(tree.children).toHaveLength(2)
+    expect(headingText(findHeading(tree, 0))).toBe("Visible Heading")
+    expect(headingText(findHeading(tree, 1))).toBe("Another Visible")
+  })
+
+  it("should remove consecutive [toc] headings correctly", () => {
+    const tree = process(
+      makeTree(
+        makeHeading(2, "First [toc]"),
+        makeHeading(2, "Second [toc]"),
+        makeHeading(2, "Kept"),
+      ),
+    )
+    expect(tree.children).toHaveLength(1)
+    expect(headingText(findHeading(tree, 0))).toBe("Kept")
+  })
+
+  it("should be available as transformCustomHeadingIds for backward compatibility", () => {
+    expect(transformCustomHeadingIds).toBe(transformHeadingAnnotations)
+  })
+})

package/build/website/plugins/remark-deflist.ts

@@ -0,0 +1,36 @@
+import type { Root, Parent } from "mdast"
+import type { Plugin } from "unified"
+import { visit, SKIP } from "unist-util-visit"
+
+/** Remark plugin that converts defList nodes into DefinitionList/DefinitionTerm/DefinitionDetail JSX elements */
+export const remarkDeflist: Plugin<[], Root> = () => {
+  return tree => {
+    visit(tree, "defList", (node: Parent, index, parent) => {
+      if (index === undefined || !parent) return
+
+      const children = node.children.map(child => {
+        const name =
+          child.type === "defListTerm" ? "DefinitionTerm" : "DefinitionDetail"
+        return {
+          type: "mdxJsxFlowElement" as const,
+          name,
+          attributes: [],
+          children: (child as Parent).children,
+          data: { _mdxExplicitJsx: true },
+        }
+      })
+
+      const jsxNode = {
+        type: "mdxJsxFlowElement" as const,
+        name: "DefinitionList",
+        attributes: [],
+        children,
+        data: { _mdxExplicitJsx: true },
+      }
+
+      // @ts-expect-error mdxJsxFlowElement is not in mdast types
+      parent.children.splice(index, 1, jsxNode)
+      return SKIP
+    })
+  }
+}