idcmd 0.0.4 → 0.0.6

package/templates/default/site/client/layout.tsx

@@ -1,2 +1,237 @@
-export { renderLayout } from "idcmd/client";
-export type { LayoutProps } from "idcmd/client";
+import type { LayoutProps } from "idcmd/client";
+/* eslint-disable react/no-danger */
+import type { JSX } from "preact";
+
+import { render } from "preact-render-to-string";
+
+import { RightRail } from "./right-rail";
+
+type NavItem = LayoutProps["navigation"][number]["items"][number];
+
+const Icon = ({ svg }: { svg: string }): JSX.Element => (
+  <span
+    class="inline-flex h-[18px] w-[18px]"
+    dangerouslySetInnerHTML={{ __html: svg }}
+  />
+);
+
+const isActiveLink = (item: NavItem, currentPath: string): boolean =>
+  currentPath === item.href ||
+  (item.href !== "/" && currentPath.startsWith(item.href));
+
+const Sidebar = ({
+  siteName,
+  navigation,
+  currentPath,
+}: {
+  siteName: LayoutProps["siteName"];
+  navigation: LayoutProps["navigation"];
+  currentPath: LayoutProps["currentPath"];
+}): JSX.Element => (
+  <aside class="sidebar">
+    <div class="sidebar-header">
+      <a
+        href="/"
+        class="text-sm font-medium tracking-tight"
+        data-prefetch="hover"
+      >
+        <span class="text-muted-foreground">~/</span>
+        {siteName}
+      </a>
+    </div>
+    <div class="sidebar-content">
+      {navigation.map((group) => (
+        <div key={group.id} class="py-2">
+          <p class="px-3 py-2 text-xs font-semibold uppercase tracking-wider text-muted-foreground">
+            {group.label}
+          </p>
+          <nav class="space-y-1">
+            {group.items.map((item) => (
+              <a
+                key={item.href}
+                href={item.href}
+                data-prefetch="hover"
+                class={`flex items-center gap-3 px-3 py-1.5 text-sm transition-colors hover:text-sidebar-foreground ${
+                  isActiveLink(item, currentPath)
+                    ? "border-l-2 border-sidebar-primary font-medium text-sidebar-foreground"
+                    : "border-l-2 border-transparent"
+                }`}
+              >
+                <Icon svg={item.iconSvg} />
+                <span>{item.title}</span>
+              </a>
+            ))}
+          </nav>
+        </div>
+      ))}
+    </div>
+  </aside>
+);
+
+const SearchForm = ({ query }: { query?: string }): JSX.Element => (
+  <form
+    method="get"
+    action="/search/"
+    class="flex w-full items-center"
+    role="search"
+    noValidate
+  >
+    <label htmlFor="site-search" class="sr-only">
+      Search pages
+    </label>
+    <input
+      id="site-search"
+      name="q"
+      type="search"
+      autoComplete="off"
+      spellcheck={false}
+      placeholder="Search..."
+      defaultValue={query ?? ""}
+      class="w-full border-b border-input bg-transparent px-1 py-1.5 text-sm placeholder:text-muted-foreground focus:border-foreground focus:outline-none transition-colors"
+    />
+  </form>
+);
+
+const TopNavbar = ({
+  query,
+  siteName,
+}: {
+  query?: LayoutProps["searchQuery"];
+  siteName: LayoutProps["siteName"];
+}): JSX.Element => (
+  <header class="sticky top-0 z-30 border-b border-border bg-background/80 backdrop-blur-sm">
+    <div class="mx-auto max-w-6xl px-8 py-3">
+      <div class="flex items-center gap-4">
+        <a
+          href="/"
+          class="text-sm font-mono font-medium tracking-tight md:hidden"
+          data-prefetch="hover"
+        >
+          <span class="text-muted-foreground">~/</span>
+          {siteName}
+        </a>
+        <div class="not-prose ml-auto w-full max-w-xs">
+          <SearchForm query={query} />
+        </div>
+      </div>
+    </div>
+  </header>
+);
+
+const buildHtmlClass = (
+  smoothScroll: LayoutProps["rightRail"]["smoothScroll"]
+): string => (smoothScroll ? "dark smooth-scroll" : "dark");
+
+const buildScrollSpyDataset = (props: {
+  isScrollSpyEnabled: boolean;
+  rightRail: LayoutProps["rightRail"];
+}): {
+  scrollspy?: string;
+  scrollspyCenter?: string;
+  scrollspyUpdateHash?: string;
+} =>
+  props.isScrollSpyEnabled
+    ? {
+        scrollspy: "1",
+        scrollspyCenter: props.rightRail.scrollSpy.centerActiveItem
+          ? "1"
+          : undefined,
+        scrollspyUpdateHash: props.rightRail.scrollSpy.updateHash,
+      }
+    : {};
+
+const Layout = ({
+  title,
+  siteName,
+  description,
+  canonicalUrl,
+  content,
+  cssPath,
+  inlineCss,
+  currentPath,
+  navigation,
+  scriptPaths = [],
+  searchQuery,
+  showRightRail = true,
+  rightRail,
+  tocItems,
+}: LayoutProps): JSX.Element => {
+  const resolvedCssPath = inlineCss ? undefined : (cssPath ?? "/styles.css");
+  const shouldShowRightRail = showRightRail && rightRail.enabled;
+  const isScrollSpyEnabled =
+    shouldShowRightRail && rightRail.scrollSpy.enabled && tocItems.length > 0;
+  const scrollSpyDataset = buildScrollSpyDataset({
+    isScrollSpyEnabled,
+    rightRail,
+  });
+
+  return (
+    <html lang="en" class={buildHtmlClass(rightRail.smoothScroll)}>
+      <head>
+        <meta charset="utf-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        <title>{title}</title>
+        {description ? <meta name="description" content={description} /> : null}
+        {canonicalUrl ? <link rel="canonical" href={canonicalUrl} /> : null}
+        <link rel="preconnect" href="https://fonts.googleapis.com" />
+        <link
+          rel="preconnect"
+          href="https://fonts.gstatic.com"
+          crossOrigin="anonymous"
+        />
+        <link
+          href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:ital,wght@0,100..800;1,100..800&display=swap"
+          rel="stylesheet"
+        />
+        <link rel="icon" href="/favicon.svg" type="image/svg+xml" />
+        {inlineCss ? <style>{inlineCss}</style> : null}
+        {resolvedCssPath ? (
+          <link rel="stylesheet" href={resolvedCssPath} />
+        ) : null}
+      </head>
+      <body
+        class="bg-background font-sans text-foreground"
+        data-scrollspy={scrollSpyDataset.scrollspy}
+        data-scrollspy-center={scrollSpyDataset.scrollspyCenter}
+        data-scrollspy-update-hash={scrollSpyDataset.scrollspyUpdateHash}
+      >
+        <Sidebar
+          siteName={siteName}
+          navigation={navigation}
+          currentPath={currentPath}
+        />
+        <div class="main-wrapper">
+          <TopNavbar query={searchQuery} siteName={siteName} />
+          <main class="main-content">
+            <div class="mx-auto flex w-full max-w-6xl items-start gap-10">
+              <article
+                class={`prose min-w-0 flex-1${
+                  currentPath === "/" ? " prose-home" : ""
+                }`}
+                dangerouslySetInnerHTML={{ __html: content }}
+              />
+              {shouldShowRightRail ? (
+                <RightRail
+                  canonicalUrl={canonicalUrl}
+                  currentPath={currentPath}
+                  tocItems={tocItems}
+                  rightRailConfig={rightRail}
+                />
+              ) : null}
+            </div>
+          </main>
+          <footer class="site-footer">
+            Built with Preact SSR + Tailwind &nbsp;|&nbsp; Zero JavaScript on
+            content pages
+          </footer>
+        </div>
+        {scriptPaths.map((scriptPath) => (
+          <script key={scriptPath} defer src={scriptPath} />
+        ))}
+      </body>
+    </html>
+  );
+};
+
+export const renderLayout = (props: LayoutProps): string =>
+  `<!DOCTYPE html>${render(<Layout {...props} />)}`;

package/templates/default/site/client/right-rail.tsx

@@ -1 +1,246 @@
-export { RightRail } from "idcmd/client";
+import type { RightRailProps } from "idcmd/client";
+import type { JSX } from "preact";
+
+const CaretDownIcon = (): JSX.Element => (
+  <svg
+    width="16"
+    height="16"
+    viewBox="0 0 24 24"
+    fill="none"
+    xmlns="http://www.w3.org/2000/svg"
+    aria-hidden="true"
+  >
+    <path
+      d="M7 10l5 5 5-5"
+      stroke="currentColor"
+      stroke-width="2"
+      stroke-linecap="round"
+      stroke-linejoin="round"
+    />
+  </svg>
+);
+
+const CopyIcon = (): JSX.Element => (
+  <svg
+    width="18"
+    height="18"
+    viewBox="0 0 24 24"
+    fill="none"
+    xmlns="http://www.w3.org/2000/svg"
+    aria-hidden="true"
+  >
+    <path
+      d="M9 9h10v12H9V9z"
+      stroke="currentColor"
+      stroke-width="2"
+      stroke-linecap="round"
+      stroke-linejoin="round"
+    />
+    <path
+      d="M5 15H4a1 1 0 0 1-1-1V4a1 1 0 0 1 1-1h10a1 1 0 0 1 1 1v1"
+      stroke="currentColor"
+      stroke-width="2"
+      stroke-linecap="round"
+      stroke-linejoin="round"
+    />
+  </svg>
+);
+
+const buildSlugFromCurrentPath = (currentPath: string): string => {
+  if (currentPath === "/") {
+    return "index";
+  }
+
+  const trimmed = currentPath.replaceAll(/^\/+|\/+$/g, "");
+  return trimmed || "index";
+};
+
+const buildAskUrls = ({
+  canonicalUrl,
+  currentPath,
+}: {
+  canonicalUrl?: string;
+  currentPath: string;
+}): { chatgptUrl: string; claudeUrl: string; markdownPath: string } => {
+  const slug = buildSlugFromCurrentPath(currentPath);
+  const markdownPath = `/${slug}.md`;
+  const markdownUrl = canonicalUrl
+    ? new URL(markdownPath, canonicalUrl).toString()
+    : markdownPath;
+
+  const llmsTxtUrl = canonicalUrl
+    ? new URL("/llms.txt", canonicalUrl).toString()
+    : "/llms.txt";
+
+  const prompt = `Investigate this document and explain it to the user: ${markdownUrl}\ndirectory for further exploration: ${llmsTxtUrl}`;
+
+  const chatgpt = new URL("https://chatgpt.com/");
+  chatgpt.searchParams.set("prompt", prompt);
+
+  const claude = new URL("https://claude.ai/new");
+  claude.searchParams.set("q", prompt);
+
+  return {
+    chatgptUrl: chatgpt.toString(),
+    claudeUrl: claude.toString(),
+    markdownPath,
+  };
+};
+
+const AskInDropdown = ({
+  claudeUrl,
+  chatgptUrl,
+  markdownPath,
+}: {
+  claudeUrl: string;
+  chatgptUrl: string;
+  markdownPath: string;
+}): JSX.Element => (
+  <details class="llm-menu relative">
+    <summary class="flex w-full cursor-pointer select-none items-center justify-between gap-3 rounded-full border border-white/20 bg-card/30 px-4 py-2 text-sm shadow-sm hover:border-white/30 hover:bg-card/40">
+      <span class="flex items-center gap-2">
+        <img
+          src="/openai-white.svg"
+          alt=""
+          width={18}
+          height={18}
+          class="shrink-0"
+        />
+        <span>Ask in ChatGPT</span>
+      </span>
+      <span class="text-muted-foreground">
+        <CaretDownIcon />
+      </span>
+    </summary>
+
+    <div class="absolute left-0 right-0 z-50 mt-2 rounded-xl border border-border bg-popover p-1 shadow-sm">
+      <a
+        href={chatgptUrl}
+        target="_blank"
+        rel="noopener noreferrer"
+        class="flex items-center gap-2 rounded-lg px-3 py-2 text-sm hover:bg-muted"
+      >
+        <img
+          src="/openai-white.svg"
+          alt=""
+          width={18}
+          height={18}
+          class="shrink-0"
+        />
+        <span>Ask in ChatGPT</span>
+      </a>
+      <a
+        href={claudeUrl}
+        target="_blank"
+        rel="noopener noreferrer"
+        class="flex items-center gap-2 rounded-lg px-3 py-2 text-sm hover:bg-muted"
+      >
+        <img
+          src="/anthropic-white.svg"
+          alt=""
+          width={18}
+          height={18}
+          class="shrink-0"
+        />
+        <span>Ask in Claude</span>
+      </a>
+      <a
+        href={markdownPath}
+        target="_blank"
+        rel="noopener noreferrer"
+        data-copy-markdown="1"
+        class="flex w-full items-center gap-2 rounded-lg px-3 py-2 text-left text-sm hover:bg-muted"
+      >
+        <span class="shrink-0 text-muted-foreground">
+          <CopyIcon />
+        </span>
+        <span data-copy-markdown-label="1">Copy Markdown to Clipboard</span>
+      </a>
+    </div>
+  </details>
+);
+
+const OnThisPage = ({
+  items,
+}: {
+  items: RightRailProps["tocItems"];
+}): JSX.Element => (
+  <section class="flex min-h-0 flex-1 flex-col" data-toc-root="1">
+    <div class="px-0.5 pb-2 text-xs font-semibold uppercase tracking-wider text-muted-foreground">
+      On this page
+    </div>
+    <nav aria-label="Table of contents" class="min-h-0 flex flex-1 flex-col">
+      <div class="toc-scroll min-h-0 flex-1" data-toc-scroll-container="1">
+        <ul class="space-y-2 text-sm text-muted-foreground">
+          {items.map((item) => (
+            <li key={item.id} class={item.level >= 3 ? "pl-3" : ""}>
+              <a
+                href={`#${encodeURIComponent(item.id)}`}
+                class="hover:text-foreground"
+                data-toc-link="1"
+              >
+                {item.text}
+              </a>
+            </li>
+          ))}
+        </ul>
+      </div>
+    </nav>
+  </section>
+);
+
+const getVisibilityClass = (
+  visibleFrom: RightRailProps["rightRailConfig"]["visibleFrom"]
+): string => {
+  switch (visibleFrom) {
+    case "always": {
+      return "block";
+    }
+    case "never": {
+      return "hidden";
+    }
+    case "md": {
+      return "hidden md:block";
+    }
+    case "lg": {
+      return "hidden lg:block";
+    }
+    default: {
+      return "hidden xl:block";
+    }
+  }
+};
+
+const getPanelClass = (
+  placement: RightRailProps["rightRailConfig"]["placement"]
+): string =>
+  placement === "viewport"
+    ? "fixed top-24 bottom-0 right-8 z-20 w-64 flex flex-col gap-6 min-h-0"
+    : "sticky top-24 h-[calc(100vh-6rem)] flex flex-col gap-6 min-h-0";
+
+export const RightRail = ({
+  canonicalUrl,
+  currentPath,
+  tocItems,
+  rightRailConfig,
+}: RightRailProps): JSX.Element => {
+  const { chatgptUrl, claudeUrl, markdownPath } = buildAskUrls({
+    canonicalUrl,
+    currentPath,
+  });
+
+  return (
+    <aside
+      class={`${getVisibilityClass(rightRailConfig.visibleFrom)} w-64 shrink-0`}
+    >
+      <div class={getPanelClass(rightRailConfig.placement)}>
+        <AskInDropdown
+          chatgptUrl={chatgptUrl}
+          claudeUrl={claudeUrl}
+          markdownPath={markdownPath}
+        />
+        {tocItems.length > 0 ? <OnThisPage items={tocItems} /> : null}
+      </div>
+    </aside>
+  );
+};

package/templates/default/site/{public/_idcmd/llm-menu.js → client/runtime/llm-menu.ts}

@@ -2,7 +2,7 @@ const COPY_SELECTOR = 'a[data-copy-markdown="1"]';
 const LABEL_SELECTOR = '[data-copy-markdown-label="1"]';
 const RESET_DELAY_MS = 2000;
 
-const setLinkDisabled = (link, disabled) => {
+const setLinkDisabled = (link: HTMLAnchorElement, disabled: boolean): void => {
   if (disabled) {
     link.setAttribute("aria-disabled", "true");
     link.style.pointerEvents = "none";
@@ -15,14 +15,14 @@ const setLinkDisabled = (link, disabled) => {
   link.style.opacity = "";
 };
 
-const setLinkLabel = (link, next) => {
+const setLinkLabel = (link: HTMLAnchorElement, next: string): void => {
   const label = link.querySelector(LABEL_SELECTOR);
   if (label) {
     label.textContent = next;
   }
 };
 
-const toAbsoluteUrl = (href) => {
+const toAbsoluteUrl = (href: string): string => {
   try {
     return new URL(href, window.location.href).toString();
   } catch {
@@ -30,7 +30,7 @@ const toAbsoluteUrl = (href) => {
   }
 };
 
-const createHiddenTextarea = (text) => {
+const createHiddenTextarea = (text: string): HTMLTextAreaElement => {
   const textarea = document.createElement("textarea");
   textarea.value = text;
   textarea.setAttribute("readonly", "true");
@@ -40,7 +40,7 @@ const createHiddenTextarea = (text) => {
   return textarea;
 };
 
-const safeExecCommandCopy = () => {
+const safeExecCommandCopy = (): boolean => {
   try {
     return document.execCommand("copy");
   } catch {
@@ -48,7 +48,7 @@ const safeExecCommandCopy = () => {
   }
 };
 
-const copyViaExecCommand = (text) => {
+const copyViaExecCommand = (text: string): boolean => {
   const textarea = createHiddenTextarea(text);
   document.body.append(textarea);
   textarea.focus();
@@ -58,7 +58,7 @@ const copyViaExecCommand = (text) => {
   return ok;
 };
 
-const copyText = async (text) => {
+const copyText = async (text: string): Promise<boolean> => {
   const { clipboard } = navigator;
   if (clipboard?.writeText) {
     try {
@@ -72,18 +72,18 @@ const copyText = async (text) => {
   return copyViaExecCommand(text);
 };
 
-const closeMenuIfPresent = (link) => {
+const closeMenuIfPresent = (link: HTMLAnchorElement): void => {
   const details = link.closest("details");
   if (details instanceof HTMLDetailsElement) {
     details.open = false;
   }
 };
 
-const getOriginalLabel = (link) =>
+const getOriginalLabel = (link: HTMLAnchorElement): string =>
   link.querySelector(LABEL_SELECTOR)?.textContent ??
   "Copy Markdown to Clipboard";
 
-const fetchMarkdownText = async (href) => {
+const fetchMarkdownText = async (href: string): Promise<string | null> => {
   const res = await fetch(toAbsoluteUrl(href), { credentials: "same-origin" });
   if (!res.ok) {
     return null;
@@ -91,7 +91,7 @@ const fetchMarkdownText = async (href) => {
   return res.text();
 };
 
-const copyMarkdownFromHref = async (href) => {
+const copyMarkdownFromHref = async (href: string): Promise<boolean> => {
   try {
     const text = await fetchMarkdownText(href);
     if (!text) {
@@ -103,24 +103,30 @@ const copyMarkdownFromHref = async (href) => {
   }
 };
 
-const startCopyOperation = (link) => {
+const startCopyOperation = (link: HTMLAnchorElement): void => {
   setLinkDisabled(link, true);
   setLinkLabel(link, "Copying...");
 };
 
-const finishCopyOperation = (link, ok) => {
+const finishCopyOperation = (link: HTMLAnchorElement, ok: boolean): void => {
   setLinkLabel(link, ok ? "Copied" : "Copy failed");
   closeMenuIfPresent(link);
 };
 
-const scheduleResetOperation = (link, originalLabel) => {
+const scheduleResetOperation = (
+  link: HTMLAnchorElement,
+  originalLabel: string
+): void => {
   window.setTimeout(() => {
     setLinkLabel(link, originalLabel);
     setLinkDisabled(link, false);
   }, RESET_DELAY_MS);
 };
 
-const handleCopyClick = async (link, originalLabel) => {
+const handleCopyClick = async (
+  link: HTMLAnchorElement,
+  originalLabel: string
+): Promise<void> => {
   const href = link.getAttribute("href");
   if (!href) {
     return;
@@ -132,7 +138,7 @@ const handleCopyClick = async (link, originalLabel) => {
   scheduleResetOperation(link, originalLabel);
 };
 
-const attachCopyHandler = (link) => {
+const attachCopyHandler = (link: HTMLAnchorElement): void => {
   const originalLabel = getOriginalLabel(link);
   link.addEventListener("click", async (event) => {
     event.preventDefault();
@@ -143,8 +149,11 @@ const attachCopyHandler = (link) => {
   });
 };
 
-const initCopyMarkdownButtons = () => {
-  const links = [...document.querySelectorAll(COPY_SELECTOR)];
+const initCopyMarkdownButtons = (): void => {
+  const links = [...document.querySelectorAll(COPY_SELECTOR)].filter(
+    (link): link is HTMLAnchorElement => link instanceof HTMLAnchorElement
+  );
+
   for (const link of links) {
     attachCopyHandler(link);
   }

package/templates/default/site/{public/_idcmd/nav-prefetch.js → client/runtime/nav-prefetch.ts}

@@ -1,8 +1,8 @@
 (() => {
   const selector = 'a[data-prefetch="hover"][href]';
-  const prefetched = new Set();
+  const prefetched = new Set<string>();
 
-  const prefetch = (href) => {
+  const prefetch = (href: string | null | undefined): void => {
     if (!href || prefetched.has(href)) {
       return;
     }
@@ -14,7 +14,7 @@
     document.head.append(link);
   };
 
-  const onOver = (event) => {
+  const onOver = (event: Event): void => {
     const { target } = event;
     if (!(target instanceof Element)) {
       return;