fix(portal): show when Copy Markdown fails (#419)

Author: mehnoorsiddiqui

portal-template/src/components/markdown-copy-button.tsx

@@ -0,0 +1,60 @@
+import { useEffect, useState } from 'react';
+import { buttonVariants } from 'fumadocs-ui/components/ui/button';
+import { Check, Copy, X } from 'lucide-react';
+import { copyMarkdown } from '@/lib/copy-markdown';
+
+type CopyState = 'idle' | 'copying' | 'copied' | 'failed';
+
+const LABELS: Record<CopyState, string> = {
+  idle: 'Copy Markdown',
+  copying: 'Copy Markdown',
+  copied: 'Copied Markdown',
+  failed: 'Copy failed'
+};
+
+export function MarkdownCopyButton({ markdownUrl, base }: Readonly<{ markdownUrl: string; base: string }>) {
+  const [state, setState] = useState<CopyState>('idle');
+
+  useEffect(() => {
+    if (state !== 'copied' && state !== 'failed') return;
+    const timeout = window.setTimeout(() => setState('idle'), 1500);
+    return () => window.clearTimeout(timeout);
+  }, [state]);
+
+  const copy = () => {
+    setState('copying');
+    copyMarkdown(markdownUrl, base).then(
+      () => setState('copied'),
+      (error: unknown) => {
+        console.error(error);
+        setState('failed');
+      }
+    );
+  };
+
+  return (
+    <>
+      <button
+        type="button"
+        disabled={state === 'copying'}
+        onClick={copy}
+        className={buttonVariants({
+          color: 'secondary',
+          size: 'sm',
+          className: 'gap-2 [&_svg]:size-3.5 [&_svg]:text-fd-muted-foreground'
+        })}
+      >
+        <StateIcon state={state} />
+        {LABELS[state]}
+      </button>
+      {/* A focused button's own text change isn't reliably announced. */}
+      <output className="sr-only">{state === 'copied' || state === 'failed' ? LABELS[state] : ''}</output>
+    </>
+  );
+}
+
+function StateIcon({ state }: Readonly<{ state: CopyState }>) {
+  if (state === 'copied') return <Check />;
+  if (state === 'failed') return <X />;
+  return <Copy />;
+}

portal-template/src/lib/copy-markdown.ts

@@ -0,0 +1,12 @@
+export async function copyMarkdown(rootRelativeUrl: string, base: string): Promise<void> {
+  const url = `${base.replace(/\/$/, '')}${rootRelativeUrl}`;
+  // Handed over unresolved, so Safari still counts the write as part of the click.
+  const markdown = fetchMarkdown(url);
+  await Promise.all([navigator.clipboard.write([new ClipboardItem({ 'text/plain': markdown })]), markdown]);
+}
+
+async function fetchMarkdown(url: string): Promise<string> {
+  const response = await fetch(url);
+  if (!response.ok) throw new Error(`Failed to fetch ${url}: ${response.status}`);
+  return response.text();
+}

portal-template/src/routes/$.tsx

@@ -8,18 +8,12 @@ import { portal } from '@/lib/portal';
 import { absoluteUrl, canonicalLink } from '@/lib/seo';
 import { useFumadocsLoader } from 'fumadocs-core/source/client';
 import { usePathname } from 'fumadocs-core/framework';
-import {
-  DocsBody,
-  DocsDescription,
-  DocsPage,
-  DocsTitle,
-  MarkdownCopyButton,
-  ViewOptionsPopover
-} from 'fumadocs-ui/layouts/notebook/page';
+import { DocsBody, DocsDescription, DocsPage, DocsTitle, ViewOptionsPopover } from 'fumadocs-ui/layouts/notebook/page';
 import { staticFunctionMiddleware } from '@tanstack/start-static-server-functions';
 import { Suspense, use, type ReactNode } from 'react';
 import { useMDXComponents } from '@/components/mdx';
 import { OpenAPIPage } from '@/components/api-page';
+import { MarkdownCopyButton } from '@/components/markdown-copy-button';
 import { slimOpenAPIPageProps } from '@/lib/openapi-slim';
 
 const rootRoute = getRouteApi('__root__');
@@ -142,7 +136,8 @@ function Content({
       <DocsTitle>{page.title}</DocsTitle>
       <DocsDescription>{page.description}</DocsDescription>
       <div className="flex flex-row gap-2 items-center border-b -mt-4 pb-6">
-        <MarkdownCopyButton markdownUrl={markdownUrl} />
+        {/* Keyed so a new page starts at "Copy Markdown", not at the last page's result. */}
+        <MarkdownCopyButton key={markdownUrl} markdownUrl={markdownUrl} base={import.meta.env.BASE_URL} />
         {/* Sends the reader to an external AI vendor, so a portal published under someone
             else's brand can turn it off. */}
         {portal.pageActions ? <ViewOptionsPopover markdownUrl={markdownUrl} pageUrl={pageUrl} /> : null}

test/portal-template/copy-markdown.test.ts

@@ -0,0 +1,87 @@
+import { expect } from 'chai';
+import sinon from 'sinon';
+import { setImmediate } from 'node:timers/promises';
+import { copyMarkdown } from '../../portal-template/src/lib/copy-markdown';
+
+class FakeClipboardItem {
+  constructor(readonly items: Record<string, Promise<string>>) {}
+}
+
+describe('copying a page as Markdown', () => {
+  let clipboard: string;
+
+  beforeEach(() => {
+    clipboard = 'before';
+    sinon.define(globalThis, 'ClipboardItem', FakeClipboardItem);
+    sinon.define(globalThis.navigator, 'clipboard', {
+      write: async ([item]: FakeClipboardItem[]) => {
+        clipboard = await item.items['text/plain'];
+      }
+    });
+  });
+
+  afterEach(() => sinon.restore());
+
+  it('puts the Markdown fetched under the base path on the clipboard', async () => {
+    const fetch = sinon.stub(globalThis, 'fetch').resolves(new globalThis.Response('# Intro'));
+
+    await copyMarkdown('/guides/intro.md', '/docs/');
+
+    expect(fetch.firstCall.args[0]).to.equal('/docs/guides/intro.md');
+    expect(clipboard).to.equal('# Intro');
+  });
+
+  it('fetches from the root when the site is hosted there', async () => {
+    const fetch = sinon.stub(globalThis, 'fetch').resolves(new globalThis.Response('# Intro'));
+
+    await copyMarkdown('/guides/intro.md', '/');
+
+    expect(fetch.firstCall.args[0]).to.equal('/guides/intro.md');
+  });
+
+  it('rejects on an error response and leaves the clipboard as it was', async () => {
+    sinon.stub(globalThis, 'fetch').resolves(new globalThis.Response('<html>Not Found</html>', { status: 404 }));
+
+    const error = await copyMarkdown('/guides/missing.md', '/').catch((reason: unknown) => reason);
+
+    expect(error).to.be.an('error').with.property('message', 'Failed to fetch /guides/missing.md: 404');
+    expect(clipboard).to.equal('before');
+  });
+
+  it('rejects when the request gets no response and leaves the clipboard as it was', async () => {
+    const offline = new TypeError('Failed to fetch');
+    sinon.stub(globalThis, 'fetch').rejects(offline);
+
+    const error = await copyMarkdown('/guides/offline.md', '/').catch((reason: unknown) => reason);
+
+    expect(error).to.equal(offline);
+    expect(clipboard).to.equal('before');
+  });
+
+  it('rejects when the clipboard refuses the write', async () => {
+    sinon.stub(globalThis, 'fetch').resolves(new globalThis.Response('# Denied'));
+    const denied = new globalThis.DOMException('Write permission denied.', 'NotAllowedError');
+    sinon.stub(globalThis.navigator.clipboard, 'write').rejects(denied);
+
+    const error = await copyMarkdown('/guides/denied.md', '/').catch((reason: unknown) => reason);
+
+    expect(error).to.equal(denied);
+    expect(clipboard).to.equal('before');
+  });
+
+  it('rejects with the refusal, and leaves no rejection unhandled, when the clipboard refuses before the fetch fails', async () => {
+    sinon.stub(globalThis, 'fetch').resolves(new globalThis.Response('<html>Not Found</html>', { status: 404 }));
+    const blocked = new globalThis.DOMException('Blocked by a permissions policy.', 'NotAllowedError');
+    sinon.stub(globalThis.navigator.clipboard, 'write').rejects(blocked);
+    const unhandled: unknown[] = [];
+    const record = (reason: unknown) => unhandled.push(reason);
+    process.prependListener('unhandledRejection', record);
+
+    const error = await copyMarkdown('/guides/blocked.md', '/').catch((reason: unknown) => reason);
+    await setImmediate();
+    process.off('unhandledRejection', record);
+
+    expect(error).to.equal(blocked);
+    expect(unhandled).to.be.empty;
+  });
+});