boltdocs 1.0.0

package/src/client/theme/components/CodeBlock/CodeBlock.tsx

@@ -0,0 +1,76 @@
+import React, { useState, useRef, useCallback } from "react";
+import { Copy, Check } from "lucide-react";
+
+interface CodeBlockProps {
+  children?: React.ReactNode;
+  className?: string;
+  [key: string]: any;
+}
+
+/**
+ * A specialized wrapper for code snippets compiled from MDX blocks.
+ * Provides syntax highlighting styling scaffolding and a "Copy to Clipboard" button.
+ */
+export function CodeBlock({ children, ...props }: CodeBlockProps) {
+  const [copied, setCopied] = useState(false);
+  const preRef = useRef<HTMLPreElement>(null);
+
+  // Extract language from the child <code> element's data-language or className
+  let language = "";
+  if (React.isValidElement(children)) {
+    const childProps = children.props as any;
+    language = childProps?.["data-language"] || "";
+    if (!language && childProps?.className) {
+      const match = childProps.className.match(/language-(\w+)/);
+      if (match) language = match[1];
+    }
+  }
+
+  const handleCopy = useCallback(async () => {
+    const code = preRef.current?.textContent || "";
+    try {
+      await navigator.clipboard.writeText(code);
+      setCopied(true);
+      setTimeout(() => setCopied(false), 2000);
+    } catch {
+      // Fallback
+      const textarea = document.createElement("textarea");
+      textarea.value = code;
+      textarea.style.position = "fixed";
+      textarea.style.opacity = "0";
+      document.body.appendChild(textarea);
+      textarea.select();
+      document.execCommand("copy");
+      document.body.removeChild(textarea);
+      setCopied(true);
+      setTimeout(() => setCopied(false), 2000);
+    }
+  }, []);
+
+  return (
+    <div className="code-block-wrapper">
+      <div className="code-block-header">
+        <span className="code-block-lang">{language || "code"}</span>
+        <button
+          className={`code-block-copy ${copied ? "copied" : ""}`}
+          onClick={handleCopy}
+          type="button"
+          aria-label="Copy code"
+        >
+          {copied ? (
+            <>
+              <Check size={20} />
+            </>
+          ) : (
+            <>
+              <Copy size={20} />
+            </>
+          )}
+        </button>
+      </div>
+      <pre ref={preRef} {...props}>
+        {children}
+      </pre>
+    </div>
+  );
+}

package/src/client/theme/components/CodeBlock/index.ts

@@ -0,0 +1 @@
+export { CodeBlock } from "./CodeBlock";

package/src/client/theme/components/PackageManagerTabs/PackageManagerTabs.tsx

@@ -0,0 +1,154 @@
+import { useState, useCallback } from "react";
+import { Copy, Check } from "lucide-react";
+import { NPM } from "../../icons/npm";
+import { Pnpm } from "../../icons/pnpm";
+import { Bun } from "../../icons/bun";
+import { Deno } from "../../icons/deno";
+
+interface PackageManagerTabsProps {
+  command: string;
+  pkg?: string;
+  className?: string;
+}
+
+type PackageManager = "npm" | "pnpm" | "bun" | "deno";
+
+const MANAGERS: {
+  id: PackageManager;
+  label: string;
+  icon: any;
+}[] = [
+  { id: "npm", label: "npm", icon: NPM },
+  { id: "pnpm", label: "pnpm", icon: Pnpm },
+  { id: "bun", label: "bun", icon: Bun },
+  { id: "deno", label: "deno", icon: Deno },
+];
+
+/**
+ * Returns the exact command for a specific package manager based on the action.
+ * Maps generic actions like 'install' to their specific permutations (e.g., yarn add, npm install).
+ */
+function getCommandForManager(
+  manager: PackageManager,
+  command: string,
+  pkg: string,
+): string {
+  const isInstall =
+    command === "install" || command === "add" || command === "i";
+  const isCreate = command === "create" || command === "init";
+  const isRun = command === "run" || command === "exec";
+
+  // Installation commands
+  if (isInstall) {
+    const pkgArgs = pkg ? ` ${pkg}` : "";
+    if (manager === "npm") return `npm install${pkgArgs}`;
+    if (manager === "pnpm") return pkg ? `pnpm add${pkgArgs}` : `pnpm install`;
+    if (manager === "bun") return pkg ? `bun add${pkgArgs}` : `bun install`;
+    if (manager === "deno")
+      return pkg ? `deno install npm:${pkg}` : `deno install`;
+  }
+
+  // Create/Init commands
+  if (isCreate) {
+    const pkgArgs = pkg ? ` ${pkg}` : "";
+    if (manager === "npm") return `npm create${pkgArgs}`;
+    if (manager === "pnpm") return `pnpm create${pkgArgs}`;
+    if (manager === "bun") return `bun create${pkgArgs}`;
+    if (manager === "deno") return `deno run -A npm:create-${pkg}`; // Approximation
+  }
+
+  // Run/Exec commands
+  if (isRun) {
+    const pkgArgs = pkg ? ` ${pkg}` : "";
+    if (manager === "npm") return `npm run${pkgArgs}`;
+    if (manager === "pnpm") return `pnpm run${pkgArgs}`;
+    if (manager === "bun") return `bun run${pkgArgs}`;
+    if (manager === "deno") return `deno task ${pkg}`;
+  }
+
+  // Fallback: just prefix the manager
+  const pkgArgs = pkg ? ` ${pkg}` : "";
+  return `${manager} ${command}${pkgArgs}`;
+}
+
+export function PackageManagerTabs({
+  command,
+  pkg = "",
+  className = "",
+}: PackageManagerTabsProps) {
+  const [activeTab, setActiveTab] = useState<PackageManager>("npm");
+  const [copied, setCopied] = useState(false);
+
+  const activeCommand = getCommandForManager(activeTab, command, pkg);
+
+  const handleCopy = useCallback(async () => {
+    try {
+      await navigator.clipboard.writeText(activeCommand);
+      setCopied(true);
+      setTimeout(() => setCopied(false), 2000);
+    } catch {
+      const textarea = document.createElement("textarea");
+      textarea.value = activeCommand;
+      textarea.style.position = "fixed";
+      textarea.style.opacity = "0";
+      document.body.appendChild(textarea);
+      textarea.select();
+      document.execCommand("copy");
+      document.body.removeChild(textarea);
+      setCopied(true);
+      setTimeout(() => setCopied(false), 2000);
+    }
+  }, [activeCommand]);
+
+  return (
+    <div className={`pkg-tabs-wrapper ${className}`}>
+      {/* Tab Headers */}
+      <div className="pkg-tabs-header">
+        {MANAGERS.map((mgr) => {
+          const Icon = mgr.icon;
+          const isActive = activeTab === mgr.id;
+          return (
+            <button
+              key={mgr.id}
+              className={`pkg-tab-btn ${isActive ? "active" : ""}`}
+              onClick={() => setActiveTab(mgr.id)}
+              aria-selected={isActive}
+              role="tab"
+            >
+              <Icon className="pkg-tab-icon" width="16" height="16" />
+              <span>{mgr.label}</span>
+            </button>
+          );
+        })}
+      </div>
+
+      {/* Code Block Content */}
+      <div className="code-block-wrapper pkg-tabs-content">
+        <div className="code-block-header">
+          <span className="code-block-lang">bash</span>
+          <button
+            className={`code-block-copy ${copied ? "copied" : ""}`}
+            onClick={handleCopy}
+            type="button"
+            aria-label="Copy code"
+          >
+            {copied ? (
+              <>
+                <Check size={12} />
+              </>
+            ) : (
+              <>
+                <Copy size={12} />
+              </>
+            )}
+          </button>
+        </div>
+        <pre>
+          <code>
+            <span className="line">{activeCommand}</span>
+          </code>
+        </pre>
+      </div>
+    </div>
+  );
+}

package/src/client/theme/components/PackageManagerTabs/index.ts

@@ -0,0 +1 @@
+export { PackageManagerTabs } from "./PackageManagerTabs";

package/src/client/theme/components/PackageManagerTabs/pkg-tabs.css

@@ -0,0 +1,64 @@
+
+/* ═══════════════════════════════════════════════════════════
+   PACKAGE MANAGER TABS
+   ═══════════════════════════════════════════════════════════ */
+.pkg-tabs-wrapper {
+    margin: 1.5rem 0;
+}
+
+.pkg-tabs-header {
+    display: flex;
+    gap: 0.25rem;
+    overflow-x: auto;
+    padding-bottom: 0.5rem;
+    margin-bottom: -0.5rem; /* pull down to meet code block */
+    scrollbar-width: none;
+}
+
+.pkg-tabs-header::-webkit-scrollbar {
+    display: none;
+}
+
+.pkg-tab-btn {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.4rem;
+    padding: 0.5rem 1rem;
+    background-color: var(--ld-bg-soft);
+    border: 1px solid var(--ld-border-subtle);
+    border-bottom: none;
+    border-radius: var(--ld-radius-md) var(--ld-radius-md) 0 0;
+    color: var(--ld-text-muted);
+    font-family: var(--ld-font-sans);
+    font-size: 0.8125rem;
+    font-weight: 500;
+    cursor: pointer;
+    transition: all 0.2s;
+    opacity: 0.7;
+}
+
+.pkg-tab-btn:hover {
+    color: var(--ld-text-main);
+    background-color: var(--ld-bg-mute);
+    opacity: 1;
+}
+
+.pkg-tab-btn.active {
+    background-color: var(--ld-code-bg);
+    color: var(--ld-text-main);
+    border-color: var(--ld-border-subtle);
+    opacity: 1;
+    position: relative;
+    z-index: 2;
+    margin-bottom: -1px; /* Overlap border */
+}
+
+.pkg-tab-icon {
+    display: inline-block;
+}
+
+/* Ensure tab content sits seamlessly below the tabs */
+.pkg-tabs-content {
+    margin-top: 0 !important;
+    border-top-left-radius: 0 !important;
+}

package/src/client/theme/components/Playground/Playground.tsx

@@ -0,0 +1,86 @@
+import React, { useState } from "react";
+import { LiveProvider, LiveEditor, LiveError, LivePreview } from "react-live";
+import { Copy, Check, Terminal, Play } from "lucide-react";
+
+interface PlaygroundProps {
+  code?: string;
+  children?: string | React.ReactNode;
+  scope?: Record<string, any>;
+  readonly?: boolean;
+}
+
+/**
+ * A live React playground component.
+ * Features a split layout with a live editor and a preview section.
+ */
+export function Playground({
+  code,
+  children,
+  scope = {},
+  readonly = false,
+}: PlaygroundProps) {
+  // Extract code from either `code` prop or `children`
+  let initialCode = code || "";
+  if (!initialCode && typeof children === "string") {
+    initialCode = children;
+  }
+
+  const [copied, setCopied] = useState(false);
+  const [activeCode, setActiveCode] = useState(initialCode.trim());
+
+  const handleCopy = () => {
+    navigator.clipboard.writeText(activeCode);
+    setCopied(true);
+    setTimeout(() => setCopied(false), 2000);
+  };
+
+  // Provide React generically
+  const extendedScope = { React, ...scope };
+
+  return (
+    <div className="boltdocs-playground" data-readonly={readonly}>
+      <LiveProvider
+        code={activeCode}
+        scope={extendedScope}
+        theme={undefined}
+        noInline={false}
+      >
+        <div className="playground-split-container">
+          {/* Editor Side */}
+          <div className="playground-panel playground-editor-panel">
+            <div className="playground-panel-header">
+              <div className="playground-panel-title">
+                <Terminal size={14} />
+                <span>{readonly ? "Code Example" : "Live Editor"}</span>
+              </div>
+              <button
+                className="playground-copy-btn"
+                onClick={handleCopy}
+                title="Copy code"
+              >
+                {copied ? <Check size={14} /> : <Copy size={14} />}
+              </button>
+            </div>
+            <div className="playground-panel-content playground-editor">
+              <LiveEditor disabled={readonly} onChange={setActiveCode} />
+            </div>
+          </div>
+
+          {/* Preview Side */}
+          <div className="playground-panel playground-preview-panel">
+            <div className="playground-panel-header">
+              <div className="playground-panel-title">
+                <Play size={14} />
+                <span>Preview</span>
+              </div>
+            </div>
+            <div className="playground-panel-content playground-preview">
+              <LivePreview />
+              <LiveError className="playground-error" />
+            </div>
+          </div>
+        </div>
+      </LiveProvider>
+    </div>
+  );
+}

package/src/client/theme/components/Playground/index.ts

@@ -0,0 +1 @@
+export { Playground } from "./Playground";

package/src/client/theme/components/Playground/playground.css

@@ -0,0 +1,168 @@
+/* ═══════════════════════════════════════════════════════════
+   PLAYGROUND (SPLIT UI)
+   ═══════════════════════════════════════════════════════════ */
+.boltdocs-playground {
+  display: flex;
+  flex-direction: column;
+  margin: 2rem 0;
+  border-radius: var(--ld-radius-lg);
+  border: 1px solid var(--ld-border-subtle);
+  background: var(--ld-code-bg);
+  overflow: hidden;
+  box-shadow: 0 4px 20px rgba(0, 0, 0, 0.1);
+  backdrop-filter: blur(10px);
+}
+
+.playground-split-container {
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+}
+
+@media (min-width: 1024px) {
+  .playground-split-container {
+    flex-direction: row;
+    min-height: 350px;
+    align-items: stretch;
+  }
+}
+
+.playground-panel {
+  display: flex;
+  flex-direction: column;
+  flex: 1;
+  min-width: 0;
+}
+
+.playground-editor-panel {
+  border-bottom: 1px solid var(--ld-border-subtle);
+  background: var(--ld-code-bg);
+}
+
+@media (min-width: 1024px) {
+  .playground-editor-panel {
+    border-bottom: none;
+    border-right: 1px solid var(--ld-border-subtle);
+  }
+}
+
+.playground-preview-panel {
+  background: var(--ld-bg-mute);
+  position: relative;
+}
+
+/* Header */
+.playground-panel-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 0.5rem 1rem;
+  border-bottom: 1px solid var(--ld-border-subtle);
+  background: rgba(0, 0, 0, 0.1);
+}
+
+.playground-panel-title {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  font-size: 0.75rem;
+  font-weight: 600;
+  color: var(--ld-text-muted);
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+}
+
+/* Copy Button */
+.playground-copy-btn {
+  background: transparent;
+  border: none;
+  color: var(--ld-text-muted);
+  cursor: pointer;
+  padding: 0.25rem;
+  border-radius: var(--ld-radius-sm);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  transition: all 0.2s;
+}
+
+.playground-copy-btn:hover {
+  background: rgba(255, 255, 255, 0.1);
+  color: var(--ld-text-main);
+}
+
+/* Content Area */
+.playground-panel-content {
+  flex: 1;
+  overflow: auto;
+  position: relative;
+  display: flex;
+  flex-direction: column;
+}
+
+/* Editor Specifics */
+.playground-editor {
+  background: transparent;
+}
+
+.playground-editor > div {
+  font-family: var(--ld-font-mono) !important;
+  font-size: 0.85rem !important;
+  line-height: 1.5 !important;
+  min-height: 100%;
+}
+
+.playground-editor pre {
+  padding: 1.5rem !important;
+  margin: 0 !important;
+  background: transparent !important;
+}
+
+.playground-editor textarea {
+  outline: none !important;
+  padding: 1.5rem !important;
+}
+
+/* Prevent editing styles if read-only */
+.boltdocs-playground[data-readonly="true"] .playground-editor textarea {
+  cursor: default !important;
+}
+
+/* Preview Specifics */
+.playground-preview {
+  padding: 2rem;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background-color: var(--ld-bg-mute);
+  background-image: radial-gradient(
+    var(--ld-border-subtle) 1.5px,
+    transparent 1.5px
+  );
+  background-size: 24px 24px;
+  color: var(--ld-text-main);
+  min-height: 200px;
+}
+
+/* Error Specifics */
+.playground-error {
+  margin: 0;
+  padding: 1rem;
+  background: #7f1d1d;
+  color: #fca5a5;
+  font-size: 0.8rem;
+  font-family: var(--ld-font-mono);
+  white-space: pre-wrap;
+  border-top: 1px solid #991b1b;
+  z-index: 10;
+}
+
+/* Loading Skeleton */
+.playground-skeleton {
+  height: 350px;
+  background: var(--ld-bg-mute);
+  border-radius: var(--ld-radius-lg);
+  animation: pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite;
+  margin: 2rem 0;
+  border: 1px solid var(--ld-border-subtle);
+}

package/src/client/theme/components/Video/Video.tsx

@@ -0,0 +1,84 @@
+import React, { useRef, useState, useEffect } from "react";
+
+interface VideoProps {
+  /** Video source URL */
+  src?: string;
+  /** Poster/thumbnail image URL */
+  poster?: string;
+  /** Alt text for accessibility */
+  alt?: string;
+  /** Show native video controls (default: true) */
+  controls?: boolean;
+  /** Preload strategy (default: 'none') */
+  preload?: string;
+  /** Children (e.g. <source> elements) */
+  children?: React.ReactNode;
+  /** Allow any additional HTML video attributes */
+  [key: string]: any;
+}
+
+/**
+ * Optimized video component with lazy loading via IntersectionObserver.
+ * The `<video>` element is only rendered once it enters the viewport,
+ * preventing unnecessary network downloads on initial page load.
+ *
+ * Usage in MDX:
+ * ```mdx
+ * <video src="/demo.mp4" poster="/demo-thumb.jpg" />
+ * ```
+ */
+export function Video({
+  src,
+  poster,
+  alt,
+  children,
+  controls,
+  preload = "metadata",
+  ...rest
+}: VideoProps) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const [isVisible, setIsVisible] = useState(false);
+
+  useEffect(() => {
+    const el = containerRef.current;
+    if (!el) return;
+
+    const observer = new IntersectionObserver(
+      ([entry]) => {
+        if (entry.isIntersecting) {
+          setIsVisible(true);
+          observer.disconnect();
+        }
+      },
+      { rootMargin: "200px" },
+    );
+
+    observer.observe(el);
+    return () => observer.disconnect();
+  }, []);
+
+  return (
+    <div ref={containerRef} className="boltdocs-video-wrapper">
+      {isVisible ? (
+        <video
+          className="boltdocs-video"
+          src={src}
+          poster={poster}
+          controls={true}
+          preload={preload}
+          playsInline
+          {...rest}
+        >
+          {children}
+          Your browser does not support the video tag.
+        </video>
+      ) : (
+        <div
+          className="boltdocs-video-placeholder"
+          role="img"
+          aria-label={alt || "Video"}
+        />
+      )}
+    </div>
+  );
+}

package/src/client/theme/components/Video/index.ts

@@ -0,0 +1 @@
+export { Video } from "./Video";

package/src/client/theme/components/Video/video.css

@@ -0,0 +1,41 @@
+/* ─── Video ──────────────────────────────────────────────── */
+.boltdocs-video-wrapper {
+  margin: 1.5rem 0;
+  max-width: 100%;
+  width: 100%;
+  box-sizing: border-box;
+  border-radius: var(--ld-radius-md);
+  overflow: hidden;
+  border: 1px solid var(--ld-border-subtle);
+  background-color: var(--ld-surface);
+}
+
+.boltdocs-video {
+  display: block;
+  width: 100%;
+  max-width: 100%;
+  height: auto;
+  border-radius: 0;
+  animation: ld-video-fade-in 0.4s ease-out;
+}
+
+.boltdocs-video-placeholder {
+  width: 100%;
+  aspect-ratio: 16 / 9;
+  background-color: var(--ld-surface);
+}
+
+/* Ensure video doesn't overflow boltdocs-page container */
+.boltdocs-page video {
+  max-width: 100%;
+  height: auto;
+}
+
+@keyframes ld-video-fade-in {
+  from {
+    opacity: 0;
+  }
+  to {
+    opacity: 1;
+  }
+}