@opendocsdev/cli 0.2.0

package/src/engine/src/components/react/Sidebar.tsx

@@ -0,0 +1,369 @@
+import { useState, useEffect } from "react";
+import { ChevronRight, ChevronDown } from "lucide-react";
+import {
+  cn,
+  pageToUrl,
+  formatPageName,
+  isPageActive,
+  isPageWithChildren as isPageWithChildrenUtil,
+  isNestedGroup as isNestedGroupUtil,
+  type PageWithChildren,
+  type NestedGroup,
+  type NavigationGroup,
+} from "../../lib/utils";
+import { ThemeToggle } from "./ThemeToggle";
+import { GitHubLink } from "./GitHubLink";
+import { SidebarSearchTrigger } from "./SidebarSearchTrigger";
+
+interface LogoConfig {
+  light?: string;
+  dark?: string;
+}
+
+interface SidebarProps {
+  siteName: string;
+  navigation: NavigationGroup[];
+  logo?: string | LogoConfig;
+  currentPath: string;
+  githubUrl?: string;
+}
+
+// Check if any page in a group of children is active
+function hasActiveChild(children: string[], currentPath: string): boolean {
+  return children.some((child) => isPageActive(child, currentPath));
+}
+
+// Get the page string from a PageItem (returns null for nested groups)
+function getPageString(item: unknown): string | null {
+  if (typeof item === "string") return item;
+  if (isPageWithChildrenUtil(item)) return item.page;
+  return null;
+}
+
+// Check if any page in a nested group or its children is active
+function hasActiveInGroup(pages: readonly unknown[], currentPath: string): boolean {
+  return pages.some((item) => {
+    if (typeof item === "string") {
+      return isPageActive(item, currentPath);
+    }
+    if (isPageWithChildrenUtil(item)) {
+      return (
+        isPageActive(item.page, currentPath) ||
+        hasActiveChild(item.children, currentPath)
+      );
+    }
+    if (isNestedGroupUtil(item)) {
+      return hasActiveInGroup(item.pages, currentPath);
+    }
+    return false;
+  });
+}
+
+interface CollapsibleNavItemProps {
+  item: PageWithChildren;
+  currentPath: string;
+}
+
+function CollapsibleNavItem({ item, currentPath }: CollapsibleNavItemProps) {
+  const isParentActive = isPageActive(item.page, currentPath);
+  const hasActiveChildPage = hasActiveChild(item.children, currentPath);
+
+  // Initialize expanded if this item or a child is active
+  const [isExpanded, setIsExpanded] = useState(isParentActive || hasActiveChildPage);
+
+  // Auto-expand when navigating to an active page
+  useEffect(() => {
+    if (isParentActive || hasActiveChildPage) {
+      setIsExpanded(true);
+    }
+  }, [isParentActive, hasActiveChildPage]);
+
+  return (
+    <li>
+      {/* Parent item with chevron */}
+      <a
+        href={pageToUrl(item.page)}
+        className={cn(
+          "group flex items-center gap-2 px-2 py-1.5 text-sm rounded-md transition-colors",
+          isParentActive
+            ? "bg-[var(--color-primary-light)] text-[var(--color-primary)] font-medium"
+            : "text-[var(--color-muted)] hover:bg-[var(--color-surface-sunken)] hover:text-[var(--color-foreground)]",
+        )}
+      >
+        <button
+          type="button"
+          onClick={(e) => {
+            e.preventDefault();
+            e.stopPropagation();
+            setIsExpanded(!isExpanded);
+          }}
+          className="flex items-center justify-center w-4 h-4 -ml-0.5"
+          aria-expanded={isExpanded}
+          aria-label={isExpanded ? "Collapse" : "Expand"}
+        >
+          <ChevronRight
+            className={cn(
+              "w-3 h-3 text-[var(--color-muted)] transition-transform duration-200",
+              isExpanded && "rotate-90",
+            )}
+          />
+        </button>
+        <span>{formatPageName(item.page)}</span>
+      </a>
+
+      {/* Children */}
+      <div
+        className={cn(
+          "overflow-hidden transition-all duration-200",
+          isExpanded ? "max-h-96 opacity-100" : "max-h-0 opacity-0",
+        )}
+      >
+        <ul className="mt-2 space-y-0.5">
+          {item.children.map((child) => {
+            const isActive = isPageActive(child, currentPath);
+            return (
+              <li key={child}>
+                <a
+                  href={pageToUrl(child)}
+                  className={cn(
+                    "block py-1.5 pl-6 pr-2 text-sm rounded-r-md transition-colors border-l-2 -ml-px",
+                    isActive
+                      ? "border-[var(--color-primary)] bg-[var(--color-primary-light)] text-[var(--color-primary)] font-medium"
+                      : "border-transparent text-[var(--color-muted)] hover:text-[var(--color-foreground)] hover:border-[var(--color-border)]",
+                  )}
+                >
+                  {formatPageName(child)}
+                </a>
+              </li>
+            );
+          })}
+        </ul>
+      </div>
+    </li>
+  );
+}
+
+// Component for Mintlify-style nested groups
+interface NestedGroupNavItemProps {
+  item: NestedGroup;
+  currentPath: string;
+}
+
+function NestedGroupNavItem({ item, currentPath }: NestedGroupNavItemProps) {
+  const hasActivePage = hasActiveInGroup(item.pages, currentPath);
+
+  // Initialize expanded if any page in group is active
+  const [isExpanded, setIsExpanded] = useState(hasActivePage);
+
+  // Auto-expand when navigating to an active page
+  useEffect(() => {
+    if (hasActivePage) {
+      setIsExpanded(true);
+    }
+  }, [hasActivePage]);
+
+  return (
+    <li>
+      {/* Group header with chevron on far right */}
+      <button
+        type="button"
+        onClick={() => setIsExpanded(!isExpanded)}
+        className="group flex items-center justify-between w-full px-2 py-1.5 text-sm rounded-md transition-colors text-[var(--color-muted)] hover:bg-[var(--color-surface-sunken)] hover:text-[var(--color-foreground)]"
+        aria-expanded={isExpanded}
+      >
+        <span className="font-medium">{item.group}</span>
+        <ChevronDown
+          className={cn(
+            "w-4 h-4 transition-transform duration-200",
+            isExpanded && "rotate-180",
+          )}
+        />
+      </button>
+
+      {/* Nested pages */}
+      <div
+        className={cn(
+          "overflow-hidden transition-all duration-200",
+          isExpanded ? "max-h-[500px] opacity-100" : "max-h-0 opacity-0",
+        )}
+      >
+        <ul className="mt-2 space-y-0.5">
+          {item.pages.map((nestedItem, index) => {
+            const pageString = getPageString(nestedItem);
+
+            // Handle nested groups recursively
+            if (isNestedGroupUtil(nestedItem)) {
+              return (
+                <NestedGroupNavItem
+                  key={`nested-${nestedItem.group}-${index}`}
+                  item={nestedItem}
+                  currentPath={currentPath}
+                />
+              );
+            }
+
+            // Handle legacy page with children
+            if (isPageWithChildrenUtil(nestedItem)) {
+              return (
+                <CollapsibleNavItem
+                  key={pageString}
+                  item={nestedItem}
+                  currentPath={currentPath}
+                />
+              );
+            }
+
+            // Handle simple string page
+            const isActive = isPageActive(pageString as string, currentPath);
+            return (
+              <li key={pageString}>
+                <a
+                  href={pageToUrl(pageString as string)}
+                  className={cn(
+                    "block py-1.5 pl-6 pr-2 text-sm rounded-r-md transition-colors border-l-2 -ml-px",
+                    isActive
+                      ? "border-[var(--color-primary)] bg-[var(--color-primary-light)] text-[var(--color-primary)] font-medium"
+                      : "border-transparent text-[var(--color-muted)] hover:text-[var(--color-foreground)] hover:border-[var(--color-border)]",
+                  )}
+                >
+                  {formatPageName(pageString as string)}
+                </a>
+              </li>
+            );
+          })}
+        </ul>
+      </div>
+    </li>
+  );
+}
+
+// Logo component that handles theme switching with CSS instead of JS state
+function Logo({ logo, siteName }: { logo?: string | LogoConfig; siteName: string }) {
+  if (!logo) {
+    return (
+      <a
+        href="/"
+        className="text-lg font-semibold text-[var(--color-foreground)] hover:text-[var(--color-muted)] transition-colors"
+      >
+        {siteName}
+      </a>
+    );
+  }
+
+  // String logo - no theme switching needed
+  if (typeof logo === "string") {
+    return (
+      <a href="/" className="flex items-center gap-2">
+        <img src={logo} alt={siteName} className="h-8 w-auto" />
+      </a>
+    );
+  }
+
+  // Object logo with light/dark variants - use CSS for theme switching
+  const { light, dark } = logo;
+
+  if (dark) {
+    return (
+      <a href="/" className="flex items-center gap-2">
+        <img src={light} alt={siteName} className="h-8 w-auto dark:hidden" />
+        <img src={dark} alt={siteName} className="h-8 w-auto hidden dark:block" />
+      </a>
+    );
+  }
+
+  // Only light logo provided
+  return (
+    <a href="/" className="flex items-center gap-2">
+      <img src={light} alt={siteName} className="h-8 w-auto" />
+    </a>
+  );
+}
+
+export function Sidebar({
+  siteName,
+  navigation,
+  logo,
+  currentPath,
+  githubUrl,
+}: SidebarProps) {
+  // No more isDark state or MutationObserver - CSS handles theme switching
+
+  return (
+    <div className="flex flex-col h-full">
+      {/* Logo/Site name + Theme toggle */}
+      <div className="flex items-center justify-between h-16 px-4">
+        <Logo logo={logo} siteName={siteName} />
+        <ThemeToggle />
+      </div>
+
+      {/* Search trigger */}
+      <div className="px-4 py-3">
+        <SidebarSearchTrigger />
+      </div>
+
+      {/* Navigation */}
+      <nav className="sidebar-nav flex-1 overflow-y-auto px-4 py-4">
+        {navigation.map((group) => (
+          <div key={group.group} className="mb-6">
+            <h3 className="mb-2 px-2 text-xs font-bold uppercase tracking-wider text-[var(--color-foreground)]">
+              {group.group}
+            </h3>
+            <ul className="space-y-0.5">
+              {group.pages.map((item, index) => {
+                const pageString = getPageString(item);
+
+                // Handle Mintlify-style nested groups
+                if (isNestedGroupUtil(item)) {
+                  return (
+                    <NestedGroupNavItem
+                      key={`group-${item.group}-${index}`}
+                      item={item}
+                      currentPath={currentPath}
+                    />
+                  );
+                }
+
+                // Handle legacy page with children
+                if (isPageWithChildrenUtil(item)) {
+                  return (
+                    <CollapsibleNavItem
+                      key={pageString}
+                      item={item}
+                      currentPath={currentPath}
+                    />
+                  );
+                }
+
+                // Handle simple string page
+                return (
+                  <li key={pageString}>
+                    <a
+                      href={pageToUrl(pageString as string)}
+                      className={cn(
+                        "block px-2 py-1.5 text-sm rounded-md transition-colors",
+                        isPageActive(pageString as string, currentPath)
+                          ? "bg-[var(--color-primary-light)] text-[var(--color-primary)] font-medium"
+                          : "text-[var(--color-muted)] hover:bg-[var(--color-surface-sunken)] hover:text-[var(--color-foreground)]",
+                      )}
+                    >
+                      {formatPageName(pageString as string)}
+                    </a>
+                  </li>
+                );
+              })}
+            </ul>
+          </div>
+        ))}
+      </nav>
+
+      {/* Bottom section with GitHub link */}
+      {githubUrl && (
+        <div className="px-4 py-3">
+          <GitHubLink url={githubUrl} />
+        </div>
+      )}
+    </div>
+  );
+}
+
+export default Sidebar;

package/src/engine/src/components/react/SidebarSearchTrigger.tsx

@@ -0,0 +1,57 @@
+import { useState, useEffect } from "react";
+import { Search } from "lucide-react";
+import { cn } from "../../lib/utils";
+
+interface SidebarSearchTriggerProps {
+  className?: string;
+}
+
+export function SidebarSearchTrigger({ className }: SidebarSearchTriggerProps) {
+  // Start with null to indicate "not yet determined" - renders placeholder during SSR
+  const [isMac, setIsMac] = useState<boolean | null>(null);
+
+  useEffect(() => {
+    // Detect platform on client - runs once after hydration
+    const isMacOS =
+      navigator.userAgentData?.platform?.toLowerCase().includes("mac") ??
+      /mac/i.test(navigator.userAgent);
+    setIsMac(isMacOS);
+  }, []);
+
+  const handleClick = () => {
+    // Dispatch custom event that SearchProvider listens for
+    // This is appropriate for Astro islands architecture where React trees are separate
+    document.dispatchEvent(new CustomEvent("open-search"));
+  };
+
+  return (
+    <button
+      type="button"
+      onClick={handleClick}
+      className={cn(
+        "flex items-center w-full gap-2 px-3 py-2 text-sm rounded-lg transition-colors",
+        "text-[var(--color-muted)] bg-[var(--color-surface-sunken)]",
+        "border border-[var(--color-border)]",
+        "hover:border-[var(--color-border-muted)] hover:text-[var(--color-foreground)]",
+        className,
+      )}
+      aria-label="Search documentation"
+    >
+      <Search className="w-4 h-4 flex-shrink-0" aria-hidden="true" />
+      <span className="flex-1 text-left">Search...</span>
+      <kbd
+        className={cn(
+          "hidden sm:inline-flex items-center gap-0.5 px-1.5 py-0.5",
+          "text-xs font-medium text-[var(--color-muted-foreground)]",
+          "bg-[var(--color-surface)] border border-[var(--color-border)] rounded",
+          // Hide until we know the platform to prevent hydration mismatch flash
+          isMac === null && "invisible",
+        )}
+      >
+        <span className="text-xs">{isMac === false ? "Ctrl" : "⌘"}</span>K
+      </kbd>
+    </button>
+  );
+}
+
+export default SidebarSearchTrigger;

package/src/engine/src/components/react/Steps.tsx

@@ -0,0 +1,25 @@
+interface StepsProps {
+  title?: string;
+  children: React.ReactNode;
+}
+
+export function Steps({ title, children }: StepsProps) {
+  return (
+    <div className="steps my-8 not-prose">
+      {title && (
+        <h4 className="steps-title text-lg font-semibold text-[var(--color-foreground)] mb-4">
+          {title}
+        </h4>
+      )}
+      <div className="steps-list relative pl-12">
+        <div
+          className="steps-line absolute left-4 top-4 bottom-4 w-0.5 bg-[var(--color-border)]"
+          aria-hidden="true"
+        />
+        {children}
+      </div>
+    </div>
+  );
+}
+
+export default Steps;

package/src/engine/src/components/react/ThemeToggle.tsx

@@ -0,0 +1,72 @@
+import { useEffect, useState } from "react";
+import { Sun, Moon } from "lucide-react";
+import { cn } from "../../lib/utils";
+
+interface ThemeToggleProps {
+  className?: string;
+}
+
+export function ThemeToggle({ className }: ThemeToggleProps) {
+  const [isDark, setIsDark] = useState(false);
+  const [mounted, setMounted] = useState(false);
+
+  useEffect(() => {
+    setMounted(true);
+    // Check initial theme
+    const isDarkMode = document.documentElement.classList.contains("dark");
+    setIsDark(isDarkMode);
+  }, []);
+
+  const toggleTheme = () => {
+    const newIsDark = !isDark;
+    setIsDark(newIsDark);
+
+    if (newIsDark) {
+      document.documentElement.classList.add("dark");
+      localStorage.setItem("theme", "dark");
+    } else {
+      document.documentElement.classList.remove("dark");
+      localStorage.setItem("theme", "light");
+    }
+  };
+
+  // Prevent hydration mismatch by showing a placeholder until mounted
+  if (!mounted) {
+    return (
+      <button
+        type="button"
+        className={cn(
+          "flex items-center justify-center w-9 h-9 rounded-lg transition-colors",
+          "text-[var(--color-muted)] hover:text-[var(--color-foreground)]",
+          "hover:bg-[var(--color-surface-sunken)]",
+          className
+        )}
+        aria-label="Toggle theme"
+      >
+        <span className="w-5 h-5" />
+      </button>
+    );
+  }
+
+  return (
+    <button
+      type="button"
+      onClick={toggleTheme}
+      className={cn(
+        "flex items-center justify-center w-9 h-9 rounded-lg transition-colors",
+        "text-[var(--color-muted)] hover:text-[var(--color-foreground)]",
+        "hover:bg-[var(--color-surface-sunken)]",
+        className
+      )}
+      aria-label={isDark ? "Switch to light mode" : "Switch to dark mode"}
+    >
+      {isDark ? (
+        <Sun className="w-5 h-5" />
+      ) : (
+        <Moon className="w-5 h-5" />
+      )}
+    </button>
+  );
+}
+
+export default ThemeToggle;

package/src/engine/src/components/react/index.ts

@@ -0,0 +1,14 @@
+/**
+ * React components for @opendocs/components
+ *
+ * These are used when importing components in MDX snippets:
+ * import { Callout, Card } from '@opendocs/components'
+ *
+ * Note: The main docs pages use Astro components (passed via components prop).
+ * These React versions are specifically for snippet imports.
+ */
+
+export { Callout } from "./Callout";
+export { Card } from "./Card";
+export { CardGroup } from "./CardGroup";
+export { Steps } from "./Steps";

package/src/engine/src/env.d.ts

@@ -0,0 +1,10 @@
+/// <reference path="../.astro/types.d.ts" />
+/// <reference types="astro/client" />
+
+interface ImportMetaEnv {
+  readonly OPENDOCS_PROJECT_DIR: string;
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv;
+}