@dogsbay/docs-layout 0.2.0-beta.0

package/src/DocsNav.astro

@@ -0,0 +1,62 @@
+---
+/**
+ * Recursive navigation tree renderer.
+ * Accepts any nav structure: { label, href?, children? }
+ * Used by all importers (MkDocs, AsciiDoc, Docusaurus, etc.)
+ */
+
+interface NavItem {
+  label: string;
+  href?: string;
+  children?: NavItem[];
+}
+
+interface Props {
+  items: NavItem[];
+  currentPath: string;
+  depth?: number;
+}
+
+const { items, currentPath, depth = 0 } = Astro.props;
+
+function hasActive(item: NavItem, path: string): boolean {
+  if (item.href && path === item.href) return true;
+  return item.children?.some(c => hasActive(c, path)) ?? false;
+}
+---
+
+<ul class:list={[depth === 0 ? "space-y-1" : "mt-1 space-y-0.5 pl-3 border-l border-border"]}>
+  {items.map(item => (
+    <li>
+      {item.children && item.children.length > 0 ? (
+        <details open={hasActive(item, currentPath)}>
+          <summary class:list={[
+            "flex cursor-pointer list-none items-center gap-1 rounded-md px-2 py-1.5 text-sm transition-colors hover:bg-accent [&::-webkit-details-marker]:hidden",
+            depth === 0 ? "font-semibold" : "font-medium",
+          ]}>
+            <svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="shrink-0 transition-transform [[open]>&]:rotate-90"><polyline points="9 18 15 12 9 6"/></svg>
+            {item.href ? (
+              <a href={item.href} class="flex-1 text-foreground no-underline">{item.label}</a>
+            ) : (
+              <span class="flex-1">{item.label}</span>
+            )}
+          </summary>
+          <Astro.self items={item.children} currentPath={currentPath} depth={depth + 1} />
+        </details>
+      ) : item.href ? (
+        <a
+          href={item.href}
+          class:list={[
+            "block rounded-md px-2 py-1.5 text-sm no-underline transition-colors hover:bg-accent",
+            currentPath === item.href ? "bg-accent font-medium text-foreground" : "text-muted-foreground",
+          ]}
+        >{item.label}</a>
+      ) : (
+        <span class:list={[
+          "block px-2 py-1.5 text-sm",
+          depth === 0 ? "font-semibold text-foreground" : "text-muted-foreground",
+        ]}>{item.label}</span>
+      )}
+    </li>
+  ))}
+</ul>

package/src/DocsSidebar.astro

@@ -0,0 +1,35 @@
+---
+/**
+ * Documentation sidebar wrapper.
+ * Fixed on desktop, toggleable overlay on mobile.
+ * Contains the nav tree (DocsNav) and optional slot for extras.
+ */
+import DocsNav from "./DocsNav.astro";
+
+interface NavItem {
+  label: string;
+  href?: string;
+  children?: NavItem[];
+}
+
+interface Props {
+  items: NavItem[];
+  currentPath: string;
+  class?: string;
+}
+
+const { items, currentPath, class: className } = Astro.props;
+---
+
+<aside
+  data-docs-sidebar
+  class:list={[
+    "fixed inset-y-14 left-0 z-30 hidden w-64 shrink-0 overflow-y-auto border-r bg-background p-4",
+    "lg:sticky lg:top-14 lg:block lg:h-[calc(100vh-3.5rem)]",
+    className,
+  ]}
+>
+  <slot name="before-nav" />
+  <DocsNav items={items} currentPath={currentPath} />
+  <slot name="after-nav" />
+</aside>

package/src/DocsToc.astro

@@ -0,0 +1,50 @@
+---
+/**
+ * Table of contents sidebar.
+ * Renders heading links, optionally with scroll tracking (client JS).
+ */
+import "./toc-kind.css";
+
+interface Heading {
+  depth: number;
+  slug: string;
+  text: string;
+  kind?: string;
+}
+
+interface Props {
+  headings: Heading[];
+  minDepth?: number;
+  maxDepth?: number;
+  title?: string;
+  class?: string;
+}
+
+const {
+  headings,
+  minDepth = 2,
+  maxDepth = 3,
+  title = "On this page",
+  class: className,
+} = Astro.props;
+
+const filtered = headings.filter(h => h.depth >= minDepth && h.depth <= maxDepth);
+---
+
+{filtered.length > 0 && (
+  <nav class:list={["text-sm", className]} aria-label="Table of contents">
+    <div class="text-xs font-semibold uppercase text-muted-foreground">{title}</div>
+    <ul class="mt-2 space-y-1">
+      {filtered.map(h => (
+        <li>
+          <a
+            href={`#${h.slug}`}
+            class="block py-0.5 text-muted-foreground transition-colors hover:text-foreground"
+            style={`padding-left: ${(h.depth - minDepth) * 0.75}rem`}
+            data-toc-link={h.slug}
+          >{h.kind && <span class={`toc-kind toc-kind-${h.kind}`}>{h.kind}</span>}{h.text}</a>
+        </li>
+      ))}
+    </ul>
+  </nav>
+)}

package/src/LocaleSwitcher.astro

@@ -0,0 +1,87 @@
+---
+/**
+ * LocaleSwitcher — dropdown letting readers switch between
+ * declared locales of a docs page. Mirror of VersionSwitcher;
+ * shared decision logic in `./switcher.ts`.
+ *
+ * When the current page has no equivalent in the target locale,
+ * the dropdown link falls back to the locale's landing page
+ * (`<basePath>/<locale>/`). The default-locale redirect (PR 5c)
+ * + missing-translation fallback further smooth the UX.
+ */
+import {
+  type SwitcherMap,
+  type MultiSourceMeta,
+  buildSwitcherRows,
+  fallbackLandingUrl,
+  shouldRenderSwitcher,
+} from "./switcher.js";
+
+interface Props {
+  switcherMap: SwitcherMap;
+  multiSource?: MultiSourceMeta;
+  basePath?: string;
+}
+
+const { switcherMap, multiSource, basePath = "/docs" } = Astro.props;
+const visible = shouldRenderSwitcher("locale", switcherMap, multiSource);
+const rows = visible
+  ? buildSwitcherRows({ axis: "locale", switcherMap, multiSource: multiSource! })
+  : [];
+const currentRow = rows.find((r) => r.isCurrent);
+const currentLabel = currentRow?.entry.label ?? currentRow?.entry.id ?? "Locale";
+---
+
+{visible && (
+  <details class="locale-switcher relative">
+    <summary
+      class="flex cursor-pointer items-center gap-1 rounded-md border border-border px-3 py-1.5 text-sm hover:bg-accent"
+      aria-label="Switch language"
+    >
+      <svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><circle cx="12" cy="12" r="10"/><path d="M2 12h20"/><path d="M12 2a15.3 15.3 0 0 1 4 10 15.3 15.3 0 0 1-4 10 15.3 15.3 0 0 1-4-10 15.3 15.3 0 0 1 4-10z"/></svg>
+      <span class="font-medium">{currentLabel}</span>
+      <svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="ml-1 transition-transform"><polyline points="6 9 12 15 18 9"/></svg>
+    </summary>
+    <ul class="absolute right-0 z-50 mt-1 min-w-[10rem] rounded-md border border-border bg-popover p-1 text-sm shadow-md">
+      {rows.map((row) => {
+        const href = row.url ?? fallbackLandingUrl(basePath, row.entry.id);
+        const isFallback = row.url === null && !row.isCurrent;
+        return (
+          <li>
+            <a
+              href={href}
+              hreflang={row.entry.id}
+              aria-current={row.isCurrent ? "true" : undefined}
+              class:list={[
+                "flex items-center gap-2 rounded-sm px-2 py-1.5 no-underline",
+                row.isCurrent
+                  ? "bg-accent font-medium text-foreground"
+                  : "text-foreground hover:bg-accent",
+              ]}
+            >
+              <span class="flex-1">{row.entry.label ?? row.entry.id}</span>
+              {row.entry.default && !row.isCurrent && (
+                <span class="text-[10px] text-muted-foreground">default</span>
+              )}
+              {isFallback && (
+                <span title="Page not translated" class="text-[10px] text-muted-foreground">→</span>
+              )}
+            </a>
+          </li>
+        );
+      })}
+    </ul>
+  </details>
+)}
+
+<style>
+  .locale-switcher > summary {
+    list-style: none;
+  }
+  .locale-switcher > summary::-webkit-details-marker {
+    display: none;
+  }
+  .locale-switcher[open] > summary > svg:last-child {
+    transform: rotate(180deg);
+  }
+</style>

package/src/PageActions.astro

@@ -0,0 +1,281 @@
+---
+/**
+ * Per-page LLM action cluster.
+ *
+ * Single dropdown trigger ("Copy or open ▾") containing every
+ * action labeled in plain text. The cluster is excluded from
+ * Pagefind indexing so its labels don't pollute search excerpts.
+ *
+ * Layout decision: one labeled dropdown beats a copy icon + a
+ * separate "Open in" dropdown. An icon-only copy button is
+ * ambiguous; a single dropdown with everything labeled is
+ * discoverable in one click. Costs a second click for the most
+ * common action (Copy) but the discoverability win is worth it.
+ *
+ * Items in order:
+ *   1. Copy markdown — clipboard write (button-like menu item)
+ *   2. Open markdown — navigates to .md mirror
+ *   3. Open in <Provider> ×N — provider deep links
+ *
+ * Provider deep links are URL-only — the provider's LLM fetches
+ * the .md mirror directly. See plans/llm-page-actions.md.
+ *
+ * Composes existing primitives from `@dogsbay/ui`:
+ *   - DropdownMenu* — accessible dropdown with keyboard nav
+ *
+ * Items carry `data-part="item"` so the existing dropdown JS
+ * picks them up for arrow-key navigation. Provider items are
+ * real <a> tags (cmd/middle-click works natively); the Copy
+ * item is a <button> so it doesn't navigate.
+ */
+import DropdownMenu from "@dogsbay/ui/dropdown-menu/DropdownMenu.astro";
+import DropdownMenuTrigger from "@dogsbay/ui/dropdown-menu/DropdownMenuTrigger.astro";
+import DropdownMenuContent from "@dogsbay/ui/dropdown-menu/DropdownMenuContent.astro";
+import DropdownMenuSeparator from "@dogsbay/ui/dropdown-menu/DropdownMenuSeparator.astro";
+import {
+  DEFAULT_PROMPT_TEMPLATE,
+  providerDeepLink,
+  resolveProviders,
+  type LlmProviderName,
+} from "./llm-actions.js";
+
+interface Props {
+  /**
+   * Plain-text markdown body of the current page. Embedded into the
+   * Copy menu item via `data-copy-text`. When omitted, the Copy
+   * item is hidden.
+   */
+  markdownBody?: string;
+  /**
+   * Path or URL to the .md mirror of the current page. Used for
+   * the "Open markdown" item and as the `{url}` substitution in
+   * the provider prompt template. Should be absolute when a
+   * `siteUrl` is configured (so providers can fetch); falls back
+   * to a relative path when not — the build-time warning catches
+   * the misconfiguration.
+   */
+  mdUrl: string;
+  /** Provider list, in render order. */
+  providers?: LlmProviderName[];
+  /**
+   * Show the "Copy markdown" item in the dropdown. Default: true.
+   * Disable for sites that want only the navigation / open-in
+   * actions. The standalone copy-icon-button is gone — copy now
+   * lives inside the dropdown alongside the other actions.
+   */
+  copyButton?: boolean;
+  /** Prompt template; `{url}` is replaced by `mdUrl`. */
+  promptTemplate?: string;
+  /** Optional class for layout-side styling. */
+  class?: string;
+}
+
+const {
+  markdownBody,
+  mdUrl,
+  providers,
+  copyButton = true,
+  promptTemplate = DEFAULT_PROMPT_TEMPLATE,
+  class: className,
+} = Astro.props;
+
+const resolvedProviders = resolveProviders(providers);
+const showCopyItem = copyButton && typeof markdownBody === "string" && markdownBody.length > 0;
+const showOpenItem = mdUrl.length > 0;
+const hasProviders = resolvedProviders.length > 0;
+const showCluster = showCopyItem || showOpenItem || hasProviders;
+
+// Tailwind classes shared by every menu item — styled to look
+// like DropdownMenuItem without going through the <div
+// role="menuitem"> component (we want real <a> / <button> tags
+// so cmd-click + native button semantics work).
+const itemClass =
+  "relative flex w-full cursor-pointer select-none items-center gap-2 rounded-sm px-2 py-1.5 text-sm text-foreground outline-none focus:bg-accent focus:text-accent-foreground hover:bg-accent hover:text-accent-foreground no-underline";
+---
+
+{showCluster && (
+  <div
+    class:list={["flex items-center", className]}
+    data-component="page-actions"
+    data-pagefind-ignore
+  >
+    <DropdownMenu>
+      <DropdownMenuTrigger
+        class="inline-flex h-8 items-center gap-1 rounded-md border border-border bg-background px-3 text-sm text-muted-foreground transition-colors hover:bg-accent hover:text-accent-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+        aria-label="Copy or open page actions"
+      >
+        <span>Copy or open</span>
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          width="14"
+          height="14"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          stroke-width="2"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+          aria-hidden="true"
+        >
+          <polyline points="6 9 12 15 18 9"></polyline>
+        </svg>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent align="end" class="min-w-[12rem]">
+        {showCopyItem && (
+          <button
+            type="button"
+            class={itemClass}
+            data-part="item"
+            role="menuitem"
+            data-action="copy-markdown"
+            data-copy-text={markdownBody!}
+          >
+            <svg
+              xmlns="http://www.w3.org/2000/svg"
+              width="14"
+              height="14"
+              viewBox="0 0 24 24"
+              fill="none"
+              stroke="currentColor"
+              stroke-width="2"
+              stroke-linecap="round"
+              stroke-linejoin="round"
+              data-copy-icon
+              aria-hidden="true"
+            >
+              <rect width="14" height="14" x="8" y="8" rx="2" ry="2"></rect>
+              <path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2"></path>
+            </svg>
+            <svg
+              xmlns="http://www.w3.org/2000/svg"
+              width="14"
+              height="14"
+              viewBox="0 0 24 24"
+              fill="none"
+              stroke="currentColor"
+              stroke-width="2"
+              stroke-linecap="round"
+              stroke-linejoin="round"
+              data-check-icon
+              class="hidden"
+              aria-hidden="true"
+            >
+              <polyline points="20 6 9 17 4 12"></polyline>
+            </svg>
+            <span data-copy-label>Copy markdown</span>
+          </button>
+        )}
+        {showOpenItem && (
+          <a
+            href={mdUrl}
+            class={itemClass}
+            data-part="item"
+            role="menuitem"
+            data-action="open-markdown"
+          >
+            <svg
+              xmlns="http://www.w3.org/2000/svg"
+              width="14"
+              height="14"
+              viewBox="0 0 24 24"
+              fill="none"
+              stroke="currentColor"
+              stroke-width="2"
+              stroke-linecap="round"
+              stroke-linejoin="round"
+              aria-hidden="true"
+            >
+              <path d="M14 3h7v7"></path>
+              <path d="M10 14L21 3"></path>
+              <path d="M21 14v5a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h5"></path>
+            </svg>
+            <span>Open markdown</span>
+          </a>
+        )}
+        {hasProviders && (showCopyItem || showOpenItem) && <DropdownMenuSeparator />}
+        {resolvedProviders.map((provider) => (
+          <a
+            href={providerDeepLink(provider.name, mdUrl, promptTemplate)}
+            class={itemClass}
+            data-part="item"
+            role="menuitem"
+            data-provider={provider.name}
+            target="_blank"
+            rel="noopener noreferrer"
+            aria-label={`${provider.label} — opens in new tab`}
+          >
+            <span>{provider.label}</span>
+            <svg
+              xmlns="http://www.w3.org/2000/svg"
+              width="12"
+              height="12"
+              viewBox="0 0 24 24"
+              fill="none"
+              stroke="currentColor"
+              stroke-width="2"
+              stroke-linecap="round"
+              stroke-linejoin="round"
+              class="ml-auto opacity-60"
+              aria-hidden="true"
+            >
+              <path d="M7 17L17 7"></path>
+              <polyline points="7 7 17 7 17 17"></polyline>
+            </svg>
+          </a>
+        ))}
+      </DropdownMenuContent>
+    </DropdownMenu>
+  </div>
+)}
+
+<script>
+  import "@dogsbay/ui/dropdown-menu/dropdown-menu.ts";
+
+  /**
+   * Wire up the in-dropdown "Copy markdown" item. Clipboard write
+   * with checkmark feedback for two seconds; same UX as the
+   * standalone CopyButton component, inlined so we don't need a
+   * separate component just for one menu item.
+   */
+  function setupPageActionsCopy(): void {
+    document.querySelectorAll<HTMLElement>(
+      "[data-component='page-actions'] [data-action='copy-markdown']",
+    ).forEach((btn) => {
+      // @ts-expect-error — guard against double-binding on
+      // astro:after-swap re-runs.
+      if (btn.__copyBound) return;
+      // @ts-expect-error
+      btn.__copyBound = true;
+
+      btn.addEventListener("click", async (e) => {
+        e.preventDefault();
+        const text = btn.getAttribute("data-copy-text") ?? "";
+        try {
+          await navigator.clipboard.writeText(text);
+        } catch {
+          // No clipboard access (insecure context, denied permission, etc.)
+          return;
+        }
+        const copyIcon = btn.querySelector<HTMLElement>("[data-copy-icon]");
+        const checkIcon = btn.querySelector<HTMLElement>("[data-check-icon]");
+        const label = btn.querySelector<HTMLElement>("[data-copy-label]");
+        const original = label?.textContent ?? "Copy markdown";
+        if (copyIcon && checkIcon) {
+          copyIcon.classList.add("hidden");
+          checkIcon.classList.remove("hidden");
+        }
+        if (label) label.textContent = "Copied!";
+        setTimeout(() => {
+          if (copyIcon && checkIcon) {
+            copyIcon.classList.remove("hidden");
+            checkIcon.classList.add("hidden");
+          }
+          if (label) label.textContent = original;
+        }, 2000);
+      });
+    });
+  }
+
+  setupPageActionsCopy();
+  document.addEventListener("astro:after-swap", setupPageActionsCopy);
+</script>