@charcuterie/ui 3.16.0 → 3.18.0

package/src/markdownEditorCodeMirror/livePreviewRanges.test.ts

@@ -1003,3 +1003,140 @@ describe("toLivePreviewRanges", () => {
     })
   })
 })
+
+describe("resolveUrl", () => {
+  const toResolved = (
+    text: string,
+    resolveUrl: (url: string) => string | undefined,
+  ) =>
+    toLivePreviewRanges({
+      isRawMode: false,
+      resolveUrl,
+      selections: [],
+      text,
+      tree: markdownLanguage.parser.parse(text),
+    })
+
+  /**
+   * The case the option exists for: a relative path in a document
+   * the app fetched from somewhere else. The browser resolves it
+   * against the page the reader is ON, which is the app, so it
+   * lands on nothing. Only the app knows what the path means.
+   */
+  test("re-points a link the consumer claims", () => {
+    const text = "see [the runbook](../docs/runbook.md)"
+
+    const linkText = toRanges(text).find(
+      (range) =>
+        range.type === "mark" &&
+        range.markKind === "linkText",
+    )
+
+    expect(linkText).toMatchObject({
+      url: "../docs/runbook.md",
+    })
+
+    const resolved = toResolved(text, (url) =>
+      url.startsWith("../")
+        ? `/files?path=${url.slice(3)}`
+        : undefined,
+    ).find(
+      (range) =>
+        range.type === "mark" &&
+        range.markKind === "linkText",
+    )
+
+    expect(resolved).toMatchObject({
+      url: "/files?path=docs/runbook.md",
+    })
+  })
+
+  test("leaves a link alone when the consumer returns undefined", () => {
+    const text = "see [the docs](https://example.invalid/a)"
+
+    expect(
+      toResolved(text, () => undefined).find(
+        (range) =>
+          range.type === "mark" &&
+          range.markKind === "linkText",
+      ),
+    ).toMatchObject({ url: "https://example.invalid/a" })
+  })
+
+  test("re-points a bare URL too", () => {
+    const text = "see https://example.invalid/a for more"
+
+    expect(
+      toResolved(text, () => "/elsewhere").find(
+        (range) =>
+          range.type === "mark" &&
+          range.markKind === "autolink",
+      ),
+    ).toMatchObject({ url: "/elsewhere" })
+  })
+
+  /**
+   * The guard runs FIRST, so a refused URL never reaches the
+   * consumer — it is not a link at all by then, and offering an app
+   * the chance to resurrect one would undo `safeUrls.ts`.
+   */
+  test("never offers a URL the scheme guard refused", () => {
+    const seen: string[] = []
+
+    const text = "[click me](javascript:alert(1))"
+
+    toResolved(text, (url) => {
+      seen.push(url)
+
+      return undefined
+    })
+
+    expect(seen).toEqual([])
+  })
+
+  /**
+   * An image is deliberately not offered. An app that maps a
+   * document path to a PAGE url would turn a working image into a
+   * broken one, and the image's `src` is the one URL here that has
+   * to stay fetchable.
+   */
+  test("does not offer an image's src", () => {
+    const seen: string[] = []
+
+    const text = "![a diagram](../docs/a.png)"
+
+    const image = toResolved(text, (url) => {
+      seen.push(url)
+
+      return "/elsewhere.png"
+    }).find((range) => range.type === "image")
+
+    expect(seen).toEqual([])
+
+    expect(image).toMatchObject({
+      url: "../docs/a.png",
+    })
+  })
+
+  test("re-points a link inside a table cell", () => {
+    const text = [
+      "| Port | Notes |",
+      "| --- | --- |",
+      "| 1 | see [the runbook](../docs/runbook.md) |",
+    ].join("\n")
+
+    const cell = toLivePreviewTableRanges({
+      isRawMode: false,
+      resolveUrl: () => "/files?path=docs/runbook.md",
+      selections: [],
+      text,
+      tree: markdownLanguage.parser.parse(text),
+    })[0]?.rows[1]?.cells[1]
+
+    expect(toFound(cell).segments).toContainEqual(
+      expect.objectContaining({
+        url: "/files?path=docs/runbook.md",
+      }),
+    )
+  })
+})

package/src/markdownEditorCodeMirror/livePreviewRanges.ts

@@ -225,6 +225,26 @@ export type ToLivePreviewRangesOptions = {
    * the toggle is to see the markup, not to lose the highlighting.
    */
   isRawMode?: boolean
+  /**
+   * Re-point a link before it becomes an `href`.
+   *
+   * The document's own URL goes through `toSafeLinkUrl` first, so
+   * what arrives here has already been refused if it named an
+   * executable scheme. What comes BACK is the consumer's own string
+   * and is used as given — an app that returns a route is trusted
+   * about its own routes.
+   *
+   * Return `undefined` to leave the link alone, which is also what
+   * omitting this does. **Links only**: an image's `src` is not
+   * offered, because a consumer that maps a document path to a page
+   * URL would turn a working image into a broken one.
+   *
+   * The case it exists for: a relative path in a fetched or imported
+   * document. `[the runbook](../docs/runbook.md)` resolves against
+   * the page the reader is on, which is the consuming app, and lands
+   * on nothing. Only the app knows what that path means.
+   */
+  resolveUrl?: (url: string) => string | undefined
   selections: readonly LivePreviewSelection[]
   text: string
   to?: number
@@ -912,13 +932,27 @@ const isTableRendered = ({
  */
 const toWalker = ({
   isRawMode,
+  resolveUrl,
   selections,
   text,
 }: {
   isRawMode: boolean
+  resolveUrl:
+    | ((url: string) => string | undefined)
+    | undefined
   selections: readonly LivePreviewSelection[]
   text: string
 }) => {
+  /**
+   * The consumer's answer, or the document's own URL.
+   *
+   * Applied at the two places a LINK's URL is pushed, and nowhere
+   * else, so every downstream consumer — the anchor's `href`, the
+   * span the editor opens from, a link inside a table cell — gets
+   * the same answer without knowing this exists.
+   */
+  const toHref = (url: string) => resolveUrl?.(url) ?? url
+
   const toEnter = (ranges: LivePreviewRange[]) => {
     const pushMarker = (
       from: number,
@@ -1149,7 +1183,7 @@ const toWalker = ({
             markKind: "linkText",
             to: closeMark.from,
             type: "mark",
-            url: safeUrl,
+            url: toHref(safeUrl),
           })
         }
 
@@ -1189,7 +1223,7 @@ const toWalker = ({
             markKind: "autolink",
             to: nodeRef.to,
             type: "mark",
-            url: safeUrl,
+            url: toHref(safeUrl),
           })
         } else {
           ranges.push({
@@ -1316,6 +1350,7 @@ const toWalker = ({
 export const toLivePreviewRanges = ({
   from,
   isRawMode = false,
+  resolveUrl,
   selections,
   text,
   to,
@@ -1326,9 +1361,12 @@ export const toLivePreviewRanges = ({
   tree.iterate({
     from,
     to,
-    enter: toWalker({ isRawMode, selections, text })(
-      ranges,
-    ),
+    enter: toWalker({
+      isRawMode,
+      resolveUrl,
+      selections,
+      text,
+    })(ranges),
   })
 
   return ranges
@@ -1361,6 +1399,7 @@ const TABLE_CONTAINER_NAMES = new Set([
  */
 export const toLivePreviewTableRanges = ({
   isRawMode = false,
+  resolveUrl,
   selections,
   text,
   tree,
@@ -1370,7 +1409,12 @@ export const toLivePreviewTableRanges = ({
 >): LivePreviewTableRange[] => {
   const ranges: LivePreviewTableRange[] = []
 
-  const toEnter = toWalker({ isRawMode, selections, text })
+  const toEnter = toWalker({
+    isRawMode,
+    resolveUrl,
+    selections,
+    text,
+  })
 
   tree.iterate({
     enter: (nodeRef) => {