@opendocsdev/cli 0.2.0

package/src/engine/src/components/react/ApiPlayground/types.ts

@@ -0,0 +1,35 @@
+export interface ApiPlaygroundProps {
+  endpoint: string;
+  method: string;
+  baseUrl: string;
+  defaultHeaders?: Record<string, string>;
+  defaultBody?: Record<string, unknown> | string;
+  defaultParams?: Record<string, string>;
+}
+
+export interface AuthState {
+  type: "none" | "bearer" | "apikey" | "basic";
+  bearer: { token: string };
+  apikey: { name: string; value: string; location: "header" | "query" };
+  basic: { username: string; password: string };
+}
+
+export interface KeyValue {
+  key: string;
+  value: string;
+}
+
+export interface ResponseState {
+  status: number;
+  statusText: string;
+  body: string;
+  headers: Record<string, string>;
+  time: number;
+}
+
+export interface ErrorState {
+  title: string;
+  message: string;
+}
+
+export type CodeLanguage = "curl" | "javascript" | "python";

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

@@ -0,0 +1,54 @@
+import { cn } from "../../lib/utils";
+
+interface CalloutProps {
+  type?: "info" | "warning" | "error" | "tip";
+  children: React.ReactNode;
+}
+
+const typeConfig = {
+  info: {
+    bg: "bg-[var(--color-info-light)]",
+    border: "border-[var(--color-info)]",
+    icon: "ℹ️",
+  },
+  warning: {
+    bg: "bg-[var(--color-warning-light)]",
+    border: "border-[var(--color-warning)]",
+    icon: "⚠️",
+  },
+  error: {
+    bg: "bg-[var(--color-error-light)]",
+    border: "border-[var(--color-error)]",
+    icon: "🚫",
+  },
+  tip: {
+    bg: "bg-[var(--color-success-light)]",
+    border: "border-[var(--color-success)]",
+    icon: "💡",
+  },
+};
+
+export function Callout({ type = "info", children }: CalloutProps) {
+  const config = typeConfig[type];
+
+  return (
+    <div
+      className={cn(
+        "callout my-4 p-4 rounded-lg border-l-4",
+        config.bg,
+        config.border
+      )}
+    >
+      <div className="flex gap-3">
+        <span className="flex-shrink-0 text-lg" aria-hidden="true">
+          {config.icon}
+        </span>
+        <div className="prose prose-sm dark:prose-invert max-w-none [&>p]:my-0 [&>p:first-child]:mt-0 [&>p:last-child]:mb-0">
+          {children}
+        </div>
+      </div>
+    </div>
+  );
+}
+
+export default Callout;

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

@@ -0,0 +1,48 @@
+import { cn } from "../../lib/utils";
+
+interface CardProps {
+  title: string;
+  description?: string;
+  href?: string;
+  icon?: string;
+  children?: React.ReactNode;
+}
+
+export function Card({ title, description, href, icon, children }: CardProps) {
+  const content = (
+    <>
+      {icon && (
+        <span className="text-2xl mb-2 block" aria-hidden="true">
+          {icon}
+        </span>
+      )}
+      <h3 className="font-semibold text-[var(--color-foreground)] m-0">
+        {title}
+      </h3>
+      {description && (
+        <p className="mt-1 text-sm text-[var(--color-muted)] m-0">
+          {description}
+        </p>
+      )}
+      {children && <div className="mt-2">{children}</div>}
+    </>
+  );
+
+  const className = cn(
+    "block p-4 rounded-lg border border-[var(--color-border)]",
+    "bg-[var(--color-surface)] transition-colors",
+    href && "hover:border-[var(--color-primary)] hover:bg-[var(--color-surface-raised)]"
+  );
+
+  if (href) {
+    return (
+      <a href={href} className={className}>
+        {content}
+      </a>
+    );
+  }
+
+  return <div className={className}>{content}</div>;
+}
+
+export default Card;

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

@@ -0,0 +1,24 @@
+import { cn } from "../../lib/utils";
+
+interface CardGroupProps {
+  cols?: 1 | 2 | 3 | 4;
+  children: React.ReactNode;
+}
+
+export function CardGroup({ cols = 2, children }: CardGroupProps) {
+  return (
+    <div
+      className={cn(
+        "card-group grid gap-4 my-6",
+        cols === 1 && "grid-cols-1",
+        cols === 2 && "grid-cols-1 sm:grid-cols-2",
+        cols === 3 && "grid-cols-1 sm:grid-cols-2 lg:grid-cols-3",
+        cols === 4 && "grid-cols-1 sm:grid-cols-2 lg:grid-cols-4"
+      )}
+    >
+      {children}
+    </div>
+  );
+}
+
+export default CardGroup;

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

@@ -0,0 +1,166 @@
+import { useState } from "react";
+import { Check, ThumbsUp, ThumbsDown } from "lucide-react";
+import { cn } from "../../lib/utils";
+
+interface FeedbackWidgetProps {
+  path: string;
+  backend?: string;
+  siteId?: string;
+  className?: string;
+}
+
+type FeedbackState = "initial" | "form" | "submitted";
+
+export function FeedbackWidget({
+  path,
+  backend,
+  siteId,
+  className,
+}: FeedbackWidgetProps) {
+  const [state, setState] = useState<FeedbackState>("initial");
+  const [helpful, setHelpful] = useState<boolean | null>(null);
+  const [comment, setComment] = useState("");
+  const [submitting, setSubmitting] = useState(false);
+
+  // Don't render if backend/siteId not configured
+  if (!backend || !siteId) {
+    return null;
+  }
+
+  const handleVote = (isHelpful: boolean) => {
+    setHelpful(isHelpful);
+    setState("form");
+  };
+
+  const submitFeedback = async () => {
+    if (submitting) return;
+
+    setSubmitting(true);
+
+    try {
+      await fetch(`${backend}/api/feedback`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+          siteId,
+          page: path,
+          helpful,
+          comment: comment.trim() || undefined,
+        }),
+      });
+    } catch (err) {
+      console.debug("[opendocs] Feedback error:", err);
+    }
+
+    setState("submitted");
+    setSubmitting(false);
+  };
+
+  const handleSkip = () => {
+    submitFeedback();
+  };
+
+  if (state === "submitted") {
+    return (
+      <div className={cn("flex items-center gap-2", className)}>
+        <span className="text-sm text-[var(--color-success)] flex items-center gap-1.5">
+          <Check className="w-4 h-4" />
+          Thanks for your feedback!
+        </span>
+      </div>
+    );
+  }
+
+  if (state === "form") {
+    return (
+      <div className={cn("max-w-md", className)}>
+        <p className="text-sm text-[var(--color-muted)] mb-3">
+          Thanks! Any additional feedback?{" "}
+          <span className="text-[var(--color-muted-foreground)]">
+            (optional)
+          </span>
+        </p>
+        <textarea
+          value={comment}
+          onChange={(e) => setComment(e.target.value)}
+          placeholder="What could be improved?"
+          rows={3}
+          className={cn(
+            "w-full px-3 py-2 text-sm rounded-lg resize-none",
+            "bg-[var(--color-surface)] border border-[var(--color-border)]",
+            "text-[var(--color-foreground)] placeholder:text-[var(--color-muted-foreground)]",
+            "focus:outline-none focus:ring-2 focus:ring-[var(--color-primary)] focus:border-transparent",
+          )}
+        />
+        <div className="flex gap-2 mt-3">
+          <button
+            type="button"
+            onClick={submitFeedback}
+            disabled={submitting}
+            className={cn(
+              "px-4 py-2 text-sm font-medium rounded-lg transition-colors",
+              "bg-[var(--color-primary)] text-[var(--color-primary-foreground)]",
+              "hover:opacity-90",
+              "disabled:opacity-50 disabled:cursor-not-allowed",
+            )}
+          >
+            Submit
+          </button>
+          <button
+            type="button"
+            onClick={handleSkip}
+            disabled={submitting}
+            className={cn(
+              "px-4 py-2 text-sm font-medium rounded-lg transition-colors",
+              "text-[var(--color-muted)] bg-[var(--color-surface-raised)]",
+              "hover:text-[var(--color-foreground)]",
+              "disabled:opacity-50 disabled:cursor-not-allowed",
+            )}
+          >
+            Skip
+          </button>
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div className={cn("flex items-center gap-3", className)}>
+      <span className="text-sm text-[var(--color-muted)]">
+        Was this page helpful?
+      </span>
+      <div className="flex items-center gap-1.5">
+        <button
+          type="button"
+          onClick={() => handleVote(true)}
+          className={cn(
+            "inline-flex items-center gap-1 px-2.5 py-1 text-sm rounded-lg transition-colors",
+            "text-[var(--color-muted)] bg-[var(--color-surface-raised)]",
+            "hover:text-[var(--color-success)] hover:bg-[var(--color-success-light)]",
+          )}
+          aria-label="Yes, this page was helpful"
+        >
+          <ThumbsUp className="w-4 h-4" />
+          <span>Yes</span>
+        </button>
+        <button
+          type="button"
+          onClick={() => handleVote(false)}
+          className={cn(
+            "inline-flex items-center gap-1 px-2.5 py-1 text-sm rounded-lg transition-colors",
+            "text-[var(--color-muted)] bg-[var(--color-surface-raised)]",
+            "hover:text-[var(--color-error)] hover:bg-[var(--color-error-light)]",
+          )}
+          aria-label="No, this page needs improvement"
+        >
+          <ThumbsDown className="w-4 h-4" />
+          <span>No</span>
+        </button>
+      </div>
+    </div>
+  );
+}
+
+export default FeedbackWidget;

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

@@ -0,0 +1,28 @@
+import { Github } from "lucide-react";
+import { cn } from "../../lib/utils";
+
+interface GitHubLinkProps {
+  url: string;
+  className?: string;
+}
+
+export function GitHubLink({ url, className }: GitHubLinkProps) {
+  return (
+    <a
+      href={url}
+      target="_blank"
+      rel="noopener noreferrer"
+      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="View on GitHub"
+    >
+      <Github className="w-5 h-5" aria-hidden="true" />
+    </a>
+  );
+}
+
+export default GitHubLink;

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

@@ -0,0 +1,53 @@
+import { ChevronLeft, ChevronRight } from "lucide-react";
+import { cn } from "../../lib/utils";
+
+interface NavigationCardProps {
+  title: string;
+  description?: string;
+  href: string;
+  direction: "previous" | "next";
+  className?: string;
+}
+
+export function NavigationCard({
+  title,
+  description,
+  href,
+  direction,
+  className,
+}: NavigationCardProps) {
+  const isNext = direction === "next";
+
+  return (
+    <a
+      href={href}
+      className={cn(
+        "group block p-5 rounded-xl border border-transparent transition-all duration-200",
+        "bg-[var(--color-surface-raised)] hover:border-[var(--color-border)]",
+        className
+      )}
+    >
+      <div className={cn("flex items-center gap-1.5 mb-1", isNext && "justify-end")}>
+        {!isNext && (
+          <ChevronLeft className="w-4 h-4 text-[var(--color-muted)] transition-transform group-hover:-translate-x-0.5" />
+        )}
+        <span className="text-base font-semibold text-[var(--color-foreground)]">
+          {title}
+        </span>
+        {isNext && (
+          <ChevronRight className="w-4 h-4 text-[var(--color-muted)] transition-transform group-hover:translate-x-0.5" />
+        )}
+      </div>
+      {description && (
+        <p className={cn(
+          "text-sm text-[var(--color-muted)] m-0",
+          isNext && "text-right"
+        )}>
+          {description}
+        </p>
+      )}
+    </a>
+  );
+}
+
+export default NavigationCard;

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

@@ -0,0 +1,124 @@
+import { useState, useRef, useEffect } from "react";
+import { Check, Copy, ChevronDown, Github } from "lucide-react";
+import { cn } from "../../lib/utils";
+
+interface PageActionsProps {
+  githubEditUrl?: string;
+  className?: string;
+}
+
+export function PageActions({ githubEditUrl, className }: PageActionsProps) {
+  const [copied, setCopied] = useState(false);
+  const [openDropdownOpen, setOpenDropdownOpen] = useState(false);
+  const dropdownRef = useRef<HTMLDivElement>(null);
+
+  // Close dropdown when clicking outside
+  useEffect(() => {
+    const handleClickOutside = (event: MouseEvent) => {
+      if (
+        dropdownRef.current &&
+        !dropdownRef.current.contains(event.target as Node)
+      ) {
+        setOpenDropdownOpen(false);
+      }
+    };
+
+    document.addEventListener("mousedown", handleClickOutside);
+    return () => document.removeEventListener("mousedown", handleClickOutside);
+  }, []);
+
+  const handleCopyMarkdown = async () => {
+    try {
+      // Get the article content as text
+      const article = document.querySelector("article");
+      if (!article) return;
+
+      // Get the raw text content
+      const textContent = article.innerText;
+
+      await navigator.clipboard.writeText(textContent);
+      setCopied(true);
+
+      // Reset after 2 seconds
+      setTimeout(() => setCopied(false), 2000);
+    } catch (err) {
+      console.error("Failed to copy:", err);
+    }
+  };
+
+  return (
+    <div className={cn("flex items-center gap-2", className)}>
+      {/* Copy Markdown button */}
+      <button
+        type="button"
+        onClick={handleCopyMarkdown}
+        className={cn(
+          "inline-flex items-center gap-2 px-3 py-1.5 text-sm font-medium rounded-lg transition-colors",
+          "text-[var(--color-muted)] bg-[var(--color-surface-raised)]",
+          "hover:text-[var(--color-foreground)] hover:bg-[var(--color-surface-sunken)]",
+          copied && "text-[var(--color-success)]"
+        )}
+        aria-label={copied ? "Copied!" : "Copy markdown content"}
+      >
+        {copied ? (
+          <Check className="w-4 h-4" />
+        ) : (
+          <Copy className="w-4 h-4" />
+        )}
+        <span>{copied ? "Copied!" : "Copy Markdown"}</span>
+      </button>
+
+      {/* Open dropdown */}
+      {githubEditUrl && (
+        <div className="relative" ref={dropdownRef}>
+          <button
+            type="button"
+            onClick={() => setOpenDropdownOpen(!openDropdownOpen)}
+            className={cn(
+              "inline-flex items-center gap-1.5 px-3 py-1.5 text-sm font-medium rounded-lg transition-colors",
+              "text-[var(--color-muted)] bg-[var(--color-surface-raised)]",
+              "hover:text-[var(--color-foreground)] hover:bg-[var(--color-surface-sunken)]"
+            )}
+            aria-expanded={openDropdownOpen}
+            aria-haspopup="true"
+          >
+            <span>Open</span>
+            <ChevronDown
+              className={cn(
+                "w-4 h-4 transition-transform",
+                openDropdownOpen && "rotate-180"
+              )}
+            />
+          </button>
+
+          {/* Dropdown menu */}
+          {openDropdownOpen && (
+            <div
+              className={cn(
+                "absolute right-0 mt-1 w-48 rounded-lg shadow-lg z-10",
+                "bg-[var(--color-surface)] border border-[var(--color-border)]"
+              )}
+            >
+              <a
+                href={githubEditUrl}
+                target="_blank"
+                rel="noopener noreferrer"
+                className={cn(
+                  "flex items-center gap-2 px-4 py-2.5 text-sm rounded-lg",
+                  "text-[var(--color-muted)] hover:text-[var(--color-foreground)]",
+                  "hover:bg-[var(--color-surface-raised)]"
+                )}
+                onClick={() => setOpenDropdownOpen(false)}
+              >
+                <Github className="w-4 h-4" />
+                <span>Edit on GitHub</span>
+              </a>
+            </div>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}
+
+export default PageActions;

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

@@ -0,0 +1,91 @@
+import { cn } from "../../lib/utils";
+import { FeedbackWidget } from "./FeedbackWidget";
+import { NavigationCard } from "./NavigationCard";
+
+interface PageLink {
+  title: string;
+  url: string;
+  description?: string;
+}
+
+interface PageFooterProps {
+  path: string;
+  backend?: string;
+  siteId?: string;
+  feedbackEnabled?: boolean;
+  previousPage?: PageLink | null;
+  nextPage?: PageLink | null;
+  lastUpdated?: string;
+  className?: string;
+}
+
+export function PageFooter({
+  path,
+  backend,
+  siteId,
+  feedbackEnabled = true,
+  previousPage,
+  nextPage,
+  lastUpdated,
+  className,
+}: PageFooterProps) {
+  const hasNavigation = previousPage || nextPage;
+  const showFeedback = feedbackEnabled && backend && siteId;
+
+  return (
+    <footer
+      className={cn("mt-12 pt-8 border-t border-[var(--color-border)]", className)}
+    >
+      {/* Feedback widget */}
+      {showFeedback && (
+        <div className="mb-6">
+          <FeedbackWidget path={path} backend={backend} siteId={siteId} />
+        </div>
+      )}
+
+      {/* Last updated date */}
+      {lastUpdated && (
+        <div className="mb-6">
+          <span className="text-sm text-[var(--color-muted)]">
+            Last updated on{" "}
+            <time dateTime={lastUpdated}>
+              {new Date(lastUpdated).toLocaleDateString("en-US", {
+                year: "numeric",
+                month: "long",
+                day: "numeric",
+              })}
+            </time>
+          </span>
+        </div>
+      )}
+
+      {/* Navigation cards */}
+      {hasNavigation && (
+        <nav className="grid grid-cols-1 sm:grid-cols-2 gap-4">
+          <div>
+            {previousPage && (
+              <NavigationCard
+                title={previousPage.title}
+                description={previousPage.description}
+                href={previousPage.url}
+                direction="previous"
+              />
+            )}
+          </div>
+          <div>
+            {nextPage && (
+              <NavigationCard
+                title={nextPage.title}
+                description={nextPage.description}
+                href={nextPage.url}
+                direction="next"
+              />
+            )}
+          </div>
+        </nav>
+      )}
+    </footer>
+  );
+}
+
+export default PageFooter;