@opendocsdev/cli 0.2.0

package/src/engine/src/components/CodeGroup.astro

@@ -0,0 +1,231 @@
+---
+/**
+ * CodeGroup - Tabbed code block component
+ * Server-renders tab buttons to eliminate FOUC
+ * Uses Web Components for click handlers and localStorage sync
+ */
+interface Props {
+  "data-labels"?: string;
+  "data-sync-key"?: string;
+  class?: string;
+}
+
+const {
+  "data-labels": labelsJson,
+  "data-sync-key": syncKey,
+  class: className,
+} = Astro.props;
+
+// Parse labels from remark plugin (or empty array for fallback)
+const labels: string[] = labelsJson ? JSON.parse(labelsJson) : [];
+const showTabs = labels.length > 1;
+---
+
+<code-group
+  class:list={[
+    "code-group not-prose my-4 rounded-xl border border-[var(--color-border)] overflow-hidden bg-[var(--color-surface-raised)] block",
+    className,
+  ]}
+  data-sync-key={syncKey}
+  data-labels={labelsJson}
+>
+  {showTabs && (
+    <nav
+      class="tabs flex gap-1 px-3 sm:px-4 pt-3 pb-0 border-b border-[var(--color-border)] overflow-x-auto"
+      role="tablist"
+      aria-label="Code examples"
+    >
+      {labels.map((label, i) => (
+        <button
+          type="button"
+          role="tab"
+          class:list={[
+            "px-2 sm:px-3 py-2 text-xs sm:text-sm font-medium transition-colors -mb-px whitespace-nowrap flex-shrink-0",
+            i === 0
+              ? "text-[var(--color-foreground)] border-b-2 border-[var(--color-primary)]"
+              : "text-[var(--color-muted)] hover:text-[var(--color-foreground)]",
+          ]}
+          aria-selected={i === 0 ? "true" : "false"}
+          tabindex={i === 0 ? 0 : -1}
+          data-index={i}
+          data-label={label}
+        >
+          {label}
+        </button>
+      ))}
+    </nav>
+  )}
+  <div class="panels">
+    <slot />
+  </div>
+</code-group>
+
+<script>
+  interface CodeGroupSyncEvent extends CustomEvent {
+    detail: {
+      syncKey: string;
+      label: string;
+    };
+  }
+
+  class CodeGroupElement extends HTMLElement {
+    private syncKey: string = "";
+    private labels: string[] = [];
+    private panels: HTMLPreElement[] = [];
+    private boundHandleSync: (e: Event) => void;
+    private boundHandleStorage: (e: StorageEvent) => void;
+
+    constructor() {
+      super();
+      this.boundHandleSync = this.handleSync.bind(this);
+      this.boundHandleStorage = this.handleStorage.bind(this);
+    }
+
+    connectedCallback() {
+      // Parse labels and sync key
+      const labelsJson = this.dataset.labels;
+      this.labels = labelsJson ? JSON.parse(labelsJson) : [];
+      this.syncKey = this.dataset.syncKey || "";
+
+      const panelsContainer = this.querySelector(".panels");
+      if (!panelsContainer) return;
+
+      // Find all pre elements (code blocks)
+      this.panels = Array.from(panelsContainer.querySelectorAll(":scope > pre"));
+      if (this.panels.length === 0) {
+        this.panels = Array.from(panelsContainer.querySelectorAll("pre"));
+      }
+
+      if (this.panels.length === 0) return;
+
+      // Initialize panels with data-active attribute
+      this.initPanels();
+
+      // If only one panel, just mark it active
+      if (this.panels.length === 1) {
+        this.panels[0].setAttribute("data-active", "true");
+        return;
+      }
+
+      // Add click handlers to server-rendered buttons
+      this.attachClickHandlers();
+
+      // Restore saved selection from localStorage
+      this.restoreFromStorage();
+
+      // Listen for sync events from other CodeGroups on the same page
+      window.addEventListener("codegroup-sync", this.boundHandleSync);
+
+      // Listen for storage events (cross-tab sync)
+      window.addEventListener("storage", this.boundHandleStorage);
+    }
+
+    disconnectedCallback() {
+      window.removeEventListener("codegroup-sync", this.boundHandleSync);
+      window.removeEventListener("storage", this.boundHandleStorage);
+    }
+
+    private initPanels() {
+      this.panels.forEach((panel, index) => {
+        panel.setAttribute("role", "tabpanel");
+        panel.setAttribute("data-active", String(index === 0));
+      });
+    }
+
+    private attachClickHandlers() {
+      const buttons = this.querySelectorAll<HTMLButtonElement>(".tabs button");
+      buttons.forEach((btn) => {
+        btn.addEventListener("click", () => {
+          const label = btn.dataset.label;
+          if (label) {
+            this.setActiveByLabel(label);
+            this.broadcastChange(label);
+          }
+        });
+      });
+    }
+
+    private restoreFromStorage() {
+      if (!this.syncKey) return;
+
+      try {
+        const saved = localStorage.getItem(`codegroup:${this.syncKey}`);
+        if (saved && this.labels.includes(saved)) {
+          this.setActiveByLabel(saved);
+        }
+      } catch {
+        // localStorage may be unavailable (private browsing, etc.)
+      }
+    }
+
+    private handleSync(e: Event) {
+      const event = e as CodeGroupSyncEvent;
+      const { syncKey, label } = event.detail;
+      if (syncKey === this.syncKey && this.labels.includes(label)) {
+        this.setActiveByLabel(label);
+      }
+    }
+
+    private handleStorage(e: StorageEvent) {
+      if (!e.key?.startsWith("codegroup:")) return;
+
+      const storedSyncKey = e.key.replace("codegroup:", "");
+      if (storedSyncKey === this.syncKey && e.newValue) {
+        this.setActiveByLabel(e.newValue);
+      }
+    }
+
+    private broadcastChange(label: string) {
+      if (!this.syncKey) return;
+
+      // Save to localStorage
+      try {
+        localStorage.setItem(`codegroup:${this.syncKey}`, label);
+      } catch {
+        // localStorage may be unavailable
+      }
+
+      // Notify other CodeGroups on the same page
+      window.dispatchEvent(
+        new CustomEvent("codegroup-sync", {
+          detail: { syncKey: this.syncKey, label },
+        })
+      );
+    }
+
+    private setActiveByLabel(label: string) {
+      const index = this.labels.indexOf(label);
+      if (index >= 0) {
+        this.setActiveTab(index);
+      }
+    }
+
+    private setActiveTab(index: number) {
+      // Update buttons
+      const buttons = this.querySelectorAll<HTMLButtonElement>(".tabs button");
+      buttons.forEach((btn, i) => {
+        const isActive = i === index;
+        btn.className = this.getTabClass(isActive);
+        btn.setAttribute("aria-selected", String(isActive));
+        btn.tabIndex = isActive ? 0 : -1;
+      });
+
+      // Update panels
+      this.panels.forEach((panel, i) => {
+        panel.setAttribute("data-active", String(i === index));
+      });
+    }
+
+    private getTabClass(isActive: boolean): string {
+      const base =
+        "px-2 sm:px-3 py-2 text-xs sm:text-sm font-medium transition-colors -mb-px whitespace-nowrap flex-shrink-0";
+      const active =
+        "text-[var(--color-foreground)] border-b-2 border-[var(--color-primary)]";
+      const inactive =
+        "text-[var(--color-muted)] hover:text-[var(--color-foreground)]";
+      return `${base} ${isActive ? active : inactive}`;
+    }
+  }
+
+  customElements.define("code-group", CodeGroupElement);
+</script>

package/src/engine/src/components/CopyButton.astro

@@ -0,0 +1,179 @@
+---
+// CopyButton component - enhances code blocks with headers and copy buttons
+// This component should be included once in the layout
+---
+
+<script>
+  function initCodeBlocks() {
+    // Find all pre elements that haven't been enhanced yet
+    document.querySelectorAll("pre:not([data-enhanced])").forEach((pre) => {
+      // Skip if inside a code-group (those handle their own styling)
+      if (pre.closest(".code-group")) {
+        // Just add copy button to code-group pre elements
+        addCopyButtonToCodeGroup(pre as HTMLPreElement);
+        return;
+      }
+
+      pre.setAttribute("data-enhanced", "true");
+
+      // Get title from data-title attribute (set by Shiki transformer from meta string)
+      const title = pre.getAttribute("data-title");
+
+      // Get language from code element
+      const codeEl = pre.querySelector("code");
+      const langClass = codeEl
+        ? Array.from(codeEl.classList).find((c) => c.startsWith("language-"))
+        : null;
+      const language = langClass ? langClass.replace("language-", "") : null;
+
+      // Create wrapper
+      const wrapper = document.createElement("div");
+      wrapper.className =
+        "code-block-wrapper not-prose my-4 rounded-xl border border-[var(--color-border)] overflow-hidden bg-[var(--color-surface-raised)]";
+
+      // Determine display label
+      const displayLabel = title || language;
+
+      if (displayLabel) {
+        // Create header with filename and copy button
+        const header = document.createElement("div");
+        header.className =
+          "code-block-header flex items-center justify-between px-4 py-2.5 border-b border-[var(--color-border)]";
+
+        // Left side - icon and title
+        const leftSide = document.createElement("div");
+        leftSide.className =
+          "flex items-center gap-2 text-sm text-[var(--color-muted)]";
+        leftSide.innerHTML = `
+          <svg class="w-4 h-4 flex-shrink-0" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+            <polyline points="16 18 22 12 16 6"/>
+            <polyline points="8 6 2 12 8 18"/>
+          </svg>
+          <span class="font-medium">${displayLabel}</span>
+        `;
+
+        // Right side - copy button
+        const copyBtn = createCopyButton();
+        copyBtn.classList.remove("opacity-0", "group-hover:opacity-100");
+
+        header.appendChild(leftSide);
+        header.appendChild(copyBtn);
+        wrapper.appendChild(header);
+
+        // Setup copy functionality
+        setupCopyHandler(copyBtn, pre as HTMLPreElement);
+      } else {
+        // No title - add copy button that appears on hover
+        wrapper.classList.add("group", "relative");
+        const copyBtn = createCopyButton();
+        copyBtn.classList.add("absolute", "top-3", "right-3");
+
+        wrapper.appendChild(copyBtn);
+        setupCopyHandler(copyBtn, pre as HTMLPreElement);
+      }
+
+      // Insert wrapper and move pre inside
+      pre.parentNode?.insertBefore(wrapper, pre);
+      wrapper.appendChild(pre);
+
+      // Style the pre element inside wrapper
+      (pre as HTMLElement).style.margin = "0";
+      (pre as HTMLElement).style.borderRadius = "0";
+      (pre as HTMLElement).style.border = "none";
+    });
+  }
+
+  function addCopyButtonToCodeGroup(pre: HTMLPreElement) {
+    if (pre.hasAttribute("data-has-copy")) return;
+    pre.setAttribute("data-has-copy", "true");
+
+    const wrapper = document.createElement("div");
+    wrapper.className = "relative group";
+
+    const copyBtn = createCopyButton();
+    copyBtn.classList.add("absolute", "top-3", "right-3");
+
+    pre.parentNode?.insertBefore(wrapper, pre);
+    wrapper.appendChild(pre);
+    wrapper.appendChild(copyBtn);
+
+    setupCopyHandler(copyBtn, pre);
+  }
+
+  function createCopyButton(): HTMLButtonElement {
+    const button = document.createElement("button");
+    button.type = "button";
+    button.className =
+      "copy-button p-1.5 rounded-md text-[var(--color-muted)] hover:text-[var(--color-foreground)] hover:bg-[var(--color-surface-sunken)] transition-colors opacity-0 group-hover:opacity-100";
+    button.setAttribute("aria-label", "Copy code");
+    button.innerHTML = `
+      <svg class="w-4 h-4 copy-icon" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+        <rect width="14" height="14" x="8" y="8" rx="2" ry="2"/>
+        <path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2"/>
+      </svg>
+      <svg class="w-4 h-4 check-icon hidden text-[var(--color-success)]" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+        <path d="M20 6 9 17l-5-5"/>
+      </svg>
+    `;
+    return button;
+  }
+
+  function setupCopyHandler(button: HTMLButtonElement, pre: HTMLPreElement) {
+    button.addEventListener("click", async () => {
+      const code = pre.querySelector("code");
+      const text = code ? code.textContent : pre.textContent;
+
+      if (!text) return;
+
+      try {
+        await navigator.clipboard.writeText(text);
+
+        // Show success state
+        const copyIcon = button.querySelector(".copy-icon");
+        const checkIcon = button.querySelector(".check-icon");
+
+        copyIcon?.classList.add("hidden");
+        checkIcon?.classList.remove("hidden");
+
+        // Reset after 2 seconds
+        setTimeout(() => {
+          copyIcon?.classList.remove("hidden");
+          checkIcon?.classList.add("hidden");
+        }, 2000);
+      } catch (err) {
+        console.error("Failed to copy code:", err);
+      }
+    });
+  }
+
+  // Initialize on DOMContentLoaded and after page transitions
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", initCodeBlocks);
+  } else {
+    initCodeBlocks();
+  }
+  document.addEventListener("astro:after-swap", initCodeBlocks);
+</script>
+
+<style is:global>
+  /* Code block wrapper styles */
+  .code-block-wrapper pre {
+    margin: 0 !important;
+    border-radius: 0 !important;
+    border: none !important;
+  }
+
+  /* Ensure copy button is always visible in header */
+  .code-block-header .copy-button {
+    opacity: 1 !important;
+  }
+
+  /* Code group copy button positioning */
+  .code-group .copy-button {
+    z-index: 10;
+  }
+
+  .code-group-panels > .relative {
+    position: relative;
+  }
+</style>

package/src/engine/src/components/Steps.astro

@@ -0,0 +1,27 @@
+---
+/**
+ * Steps - Numbered step list with connecting line
+ * Pure Astro component - no client-side JavaScript needed
+ */
+interface Props {
+  title?: string;
+  class?: string;
+}
+
+const { title, class: className } = Astro.props;
+---
+
+<div class:list={["steps my-8 not-prose", className]}>
+  {title && (
+    <h4 class="steps-title text-lg font-semibold text-[var(--color-foreground)] mb-4">
+      {title}
+    </h4>
+  )}
+  <div class="steps-list relative pl-12">
+    <div
+      class="steps-line absolute left-4 top-4 bottom-4 w-0.5 bg-[var(--color-border)]"
+      aria-hidden="true"
+    />
+    <slot />
+  </div>
+</div>

package/src/engine/src/components/Tab.astro

@@ -0,0 +1,21 @@
+---
+/**
+ * Tab - Individual tab panel for use inside <Tabs>
+ * Renders as a div with data attributes for the parent Tabs component to read
+ */
+export interface Props {
+  label: string;
+  icon?: string;
+  class?: string;
+}
+
+const { label, icon, class: className } = Astro.props;
+---
+
+<div
+  class:list={["tab-panel prose prose-sm dark:prose-invert max-w-none", className]}
+  data-label={label}
+  data-icon={icon}
+>
+  <slot />
+</div>

package/src/engine/src/components/TableOfContents.astro

@@ -0,0 +1,119 @@
+---
+/**
+ * TableOfContents - Displays page headings for navigation
+ * Highlights active heading based on scroll position
+ */
+interface Heading {
+  depth: number;
+  slug: string;
+  text: string;
+}
+
+interface Props {
+  headings: Heading[];
+}
+
+const { headings } = Astro.props;
+
+// Filter to only show h2 and h3 headings for the table of contents
+const tocHeadings = headings.filter((h) => h.depth >= 2 && h.depth <= 3);
+---
+
+{tocHeadings.length > 0 && (
+  <nav class="toc toc-nav" aria-label="Table of contents">
+    <h2 class="text-xs font-semibold uppercase tracking-widest text-[var(--color-muted)] mb-4">
+      On This Page
+    </h2>
+    <ul class="space-y-0.5 text-sm">
+      {tocHeadings.map((heading) => (
+        <li>
+          <a
+            href={`#${heading.slug}`}
+            class:list={[
+              "toc-link block transition-all py-1.5 border-l-[3px] border-transparent rounded-r-sm",
+              heading.depth === 2
+                ? "pl-3 text-[var(--color-foreground)] font-medium"
+                : "pl-6 text-[var(--color-muted)] text-[13px]",
+            ]}
+            data-slug={heading.slug}
+            data-depth={heading.depth}
+          >
+            {heading.text}
+          </a>
+        </li>
+      ))}
+    </ul>
+  </nav>
+)}
+
+<script>
+  // Highlight active heading based on scroll position
+  function highlightActiveHeading() {
+    const headings = document.querySelectorAll("article h2[id], article h3[id]");
+    const tocLinks = document.querySelectorAll(".toc-link");
+
+    if (headings.length === 0 || tocLinks.length === 0) return;
+
+    const windowHeight = window.innerHeight;
+
+    // Find the active heading by checking which one is in view
+    let activeSlug: string | null = null;
+
+    headings.forEach((heading) => {
+      const rect = heading.getBoundingClientRect();
+      // Consider a heading active if it's in the top third of the viewport
+      if (rect.top <= windowHeight / 3) {
+        activeSlug = heading.id;
+      }
+    });
+
+    // If no heading is in view yet, activate the first TOC link
+    if (!activeSlug && tocLinks.length > 0) {
+      const firstLink = tocLinks[0] as HTMLElement;
+      activeSlug = firstLink.dataset.slug || null;
+    }
+
+    // Update active state using CSS class
+    tocLinks.forEach((link) => {
+      const linkSlug = (link as HTMLElement).dataset.slug;
+
+      if (linkSlug === activeSlug) {
+        link.classList.add("active");
+      } else {
+        link.classList.remove("active");
+      }
+    });
+  }
+
+  function initTocHighlight() {
+    // Run on scroll with throttling
+    let ticking = false;
+
+    const scrollHandler = () => {
+      if (!ticking) {
+        window.requestAnimationFrame(() => {
+          highlightActiveHeading();
+          ticking = false;
+        });
+        ticking = true;
+      }
+    };
+
+    window.addEventListener("scroll", scrollHandler);
+
+    // Run immediately
+    highlightActiveHeading();
+  }
+
+  // Initialize on page load
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", initTocHighlight);
+  } else {
+    initTocHighlight();
+  }
+
+  // Reinitialize after View Transitions
+  document.addEventListener("astro:after-swap", () => {
+    highlightActiveHeading();
+  });
+</script>