boltdocs 1.10.2 → 2.0.0

package/src/client/theme/neutral.css

@@ -0,0 +1,360 @@
+@theme {
+  --font-display: "Inter", "ui-sans-serif", "system-ui", sans-serif;
+  --font-sans: "Inter", "ui-sans-serif", "system-ui", sans-serif;
+  --font-mono:
+    "JetBrains Mono", "ui-monospace", "SFMono-Regular", Menlo, Monaco, Consolas,
+    "liberation mono", "courier new", monospace;
+
+  --breakpoint-3xl: 120rem;
+
+  --color-primary-50: oklch(0.985 0.012 265.8);
+  --color-primary-100: oklch(0.92 0.045 265.8);
+  --color-primary-200: oklch(0.84 0.085 265.8);
+  --color-primary-300: oklch(0.74 0.125 265.8);
+  --color-primary-400: oklch(0.64 0.165 265.8);
+  --color-primary-500: oklch(0.54 0.195 265.8);
+  --color-primary-600: oklch(0.45 0.165 265.8);
+  --color-primary-700: oklch(0.36 0.135 265.8);
+  --color-primary-800: oklch(0.27 0.095 265.8);
+  --color-primary-900: oklch(0.15 0.045 265.8);
+
+  /* Neutral Gray Palette */
+  --color-neutral-50: oklch(0.98 0 0);
+  --color-neutral-100: oklch(0.96 0 0);
+  --color-neutral-200: oklch(0.92 0 0);
+  --color-neutral-300: oklch(0.84 0 0);
+  --color-neutral-400: oklch(0.7 0 0);
+  --color-neutral-500: oklch(0.55 0 0);
+  --color-neutral-600: oklch(0.4 0 0);
+  --color-neutral-700: oklch(0.25 0 0);
+  --color-neutral-800: oklch(0.15 0 0);
+  --color-neutral-900: oklch(0.1 0 0);
+  --color-neutral-950: oklch(0.05 0 0);
+
+  /* Semantic Status Colors */
+  --color-danger-500: oklch(0.63 0.24 27);
+  --color-success-500: oklch(0.72 0.19 150);
+  --color-warning-500: oklch(0.78 0.17 75);
+  --color-info-500: oklch(0.62 0.19 260);
+
+  /* Shared Properties */
+  --radius-sm: 0.375rem;
+  --radius-md: 0.5rem;
+  --radius-lg: 0.75rem;
+  --radius-xl: 1rem;
+  --radius-2xl: 1.5rem;
+  --radius-full: 99999rem;
+
+  --ease-fluid: cubic-bezier(0.3, 0, 0, 1);
+  --ease-snappy: cubic-bezier(0.2, 0, 0, 1);
+
+  /* Semantic Colors - Default (Light) */
+  --color-bg-main: var(--color-neutral-50);
+  --color-bg-surface: var(--color-neutral-100);
+  --color-bg-muted: var(--color-neutral-200);
+  --color-text-main: var(--color-neutral-900);
+  --color-text-muted: var(--color-neutral-500);
+  --color-text-dim: var(--color-neutral-400);
+  --color-border-subtle: var(--color-neutral-200);
+  --color-border-strong: var(--color-neutral-300);
+  --color-code-bg: var(--color-neutral-100);
+  --color-code-text: var(--color-neutral-800);
+
+  /* Semantic Colors - Dark Override (handled via standard CSS overrides below the @theme block) */
+
+  /* Spacing and Dimensions */
+  --spacing-navbar: 3.5rem;
+  --spacing-sidebar: 16rem;
+  --spacing-toc: 14rem;
+  --spacing-content-max: 48rem;
+}
+
+:root[data-theme="dark"],
+:root:not(.theme-light) {
+  --color-bg-main: var(--color-neutral-950);
+  --color-bg-surface: var(--color-neutral-900);
+  --color-bg-muted: var(--color-neutral-800);
+  --color-text-main: var(--color-neutral-50);
+  --color-text-muted: var(--color-neutral-400);
+  --color-text-dim: var(--color-neutral-500);
+  --color-border-subtle: var(--color-neutral-800);
+  --color-border-strong: var(--color-neutral-700);
+  --color-code-bg: var(--color-neutral-900);
+  --color-code-text: var(--color-neutral-200);
+}
+
+@layer base {
+  *,
+  *::before,
+  *::after {
+    box-sizing: border-box;
+  }
+
+  html,
+  body {
+    margin: 0;
+    padding: 0;
+    height: 100%;
+    overflow-x: hidden;
+    overflow-y: hidden;
+  }
+
+  body {
+    @apply bg-bg-main text-text-main antialiased;
+    font-family: var(--font-sans);
+    line-height: 1.7;
+  }
+
+  a {
+    text-decoration: none;
+  }
+
+  /* Scroll-margin-top for anchor scrolling */
+  h1,
+  h2,
+  h3,
+  h4,
+  h5,
+  h6 {
+    scroll-margin-top: 6rem;
+  }
+
+  /* Scrollbar */
+  ::-webkit-scrollbar {
+    width: 6px;
+    height: 6px;
+  }
+  ::-webkit-scrollbar-track {
+    background: transparent;
+  }
+  ::-webkit-scrollbar-thumb {
+    @apply bg-neutral-300 dark:bg-neutral-700 rounded-full;
+  }
+  ::-webkit-scrollbar-thumb:hover {
+    @apply bg-neutral-400 dark:bg-neutral-600;
+  }
+
+  /* ═══ Content Area ═══ */
+  .boltdocs-content {
+    scrollbar-width: none;
+    scroll-behavior: smooth;
+  }
+  .boltdocs-content::-webkit-scrollbar {
+    display: none;
+  }
+
+  /* ═══ Markdown Typography ═══ */
+  .boltdocs-page {
+    position: relative;
+    padding-top: 1rem;
+    padding-bottom: 8rem;
+  }
+
+  .boltdocs-page h1 {
+    font-size: 2.5rem;
+    margin: 0 0 1rem;
+    font-weight: 800;
+    letter-spacing: -0.04em;
+    color: var(--color-text-main);
+    line-height: 1.2;
+  }
+  .boltdocs-page h1 + p {
+    color: var(--color-text-muted);
+    font-size: 1.125rem;
+    margin-bottom: 2.5rem;
+    line-height: 1.6;
+  }
+  .boltdocs-page h2 {
+    font-size: 1.75rem;
+    margin-top: 3.5rem;
+    margin-bottom: 1.25rem;
+    font-weight: 700;
+    color: var(--color-text-main);
+    padding-bottom: 0.5rem;
+    border-bottom: 1px solid var(--color-border-subtle);
+    scroll-margin-top: 6rem;
+    letter-spacing: -0.02em;
+  }
+  .boltdocs-page h3 {
+    font-size: 1.25rem;
+    margin-top: 2.5rem;
+    margin-bottom: 1rem;
+    font-weight: 600;
+    color: var(--color-text-main);
+    scroll-margin-top: 6rem;
+    letter-spacing: -0.01em;
+  }
+  .boltdocs-page p {
+    margin-top: 0;
+    margin-bottom: 1.25rem;
+    color: var(--color-text-muted);
+    line-height: 1.8;
+  }
+  .boltdocs-page a {
+    color: var(--color-primary-500);
+    text-decoration: none;
+    transition: color 0.2s;
+    font-weight: 500;
+  }
+  .boltdocs-page a:hover {
+    color: var(--color-primary-400);
+    text-decoration: underline;
+  }
+  .boltdocs-page ul,
+  .boltdocs-page ol {
+    margin-top: 0;
+    margin-bottom: 1.5rem;
+    padding-left: 1.5rem;
+    color: var(--color-text-muted);
+  }
+  .boltdocs-page li {
+    margin-bottom: 0.5rem;
+    line-height: 1.8;
+  }
+  .boltdocs-page strong {
+    color: var(--color-text-main);
+    font-weight: 700;
+  }
+  .boltdocs-page blockquote {
+    margin: 2rem 0;
+    padding: 1rem 1.5rem;
+    border-left: 4px solid var(--color-primary-500);
+    background-color: var(--color-primary-500);
+    background-color: color-mix(
+      in oklch,
+      var(--color-primary-500),
+      transparent 93%
+    );
+    border-radius: 0 var(--radius-lg) var(--radius-lg) 0;
+    color: var(--color-text-muted);
+    font-style: italic;
+  }
+  .boltdocs-page blockquote p {
+    margin: 0;
+  }
+  .boltdocs-page hr {
+    border: none;
+    border-top: 1px solid var(--color-border-subtle);
+    margin: 3rem 0;
+  }
+  .boltdocs-page img {
+    max-width: 100%;
+    height: auto;
+    border-radius: var(--radius-lg);
+    margin: 2rem 0;
+    display: block;
+    box-shadow: 0 10px 30px -10px rgba(0, 0, 0, 0.1);
+  }
+  .boltdocs-page table {
+    width: 100%;
+    border-collapse: collapse;
+    margin: 2rem 0;
+    font-size: 0.875rem;
+  }
+  .boltdocs-page th {
+    text-align: left;
+    padding: 0.75rem 1rem;
+    border-bottom: 2px solid var(--color-border-subtle);
+    color: var(--color-text-main);
+    font-weight: 700;
+  }
+  .boltdocs-page td {
+    padding: 0.75rem 1rem;
+    border-bottom: 1px solid var(--color-border-subtle);
+    color: var(--color-text-muted);
+  }
+  .boltdocs-page tr:hover td {
+    background-color: var(--color-bg-surface);
+  }
+  .boltdocs-page :not(pre) > code {
+    background-color: var(--color-bg-surface);
+    padding: 0.15rem 0.45rem;
+    border-radius: 5px;
+    font-family: var(--font-mono);
+    font-size: 0.85em;
+    color: var(--color-primary-400);
+    border: 1px solid var(--color-border-subtle);
+  }
+  .boltdocs-page pre {
+    margin: 1.5rem 0;
+    border-radius: var(--radius-md);
+    overflow-x: auto;
+    font-family: var(--font-mono);
+    font-size: 0.8125rem;
+    line-height: 1.7;
+    background-color: var(--color-code-bg);
+    color: var(--color-code-text);
+    border: 1px solid var(--color-border-subtle);
+  }
+  .boltdocs-page pre > code {
+    display: grid;
+    padding: 1rem;
+    background-color: transparent;
+    border: none;
+    color: inherit;
+    font-size: inherit;
+  }
+  .boltdocs-page pre > code .line {
+    padding: 0 1.25rem;
+  }
+  .boltdocs-page pre > code .line.highlighted {
+    background-color: oklch(0.6 0.22 280 / 10%);
+    border-left: 2px solid var(--color-primary-500);
+  }
+
+  @media (max-width: 768px) {
+    .boltdocs-page h1 {
+      font-size: 1.75rem;
+    }
+  }
+
+  /* ═══ Header Anchors ═══ */
+  .header-anchor {
+    margin-left: 0.5rem;
+    color: var(--color-text-dim);
+    opacity: 0;
+    transition: opacity 0.2s;
+    text-decoration: none;
+    font-weight: 400;
+  }
+  .boltdocs-page h2:hover .header-anchor,
+  .boltdocs-page h3:hover .header-anchor {
+    opacity: 1;
+  }
+  .header-anchor:hover {
+    color: var(--color-primary-500);
+  }
+  .boltdocs-heading {
+    display: flex;
+    align-items: center;
+  }
+  .boltdocs-heading .header-anchor {
+    display: inline-flex;
+    align-items: center;
+    margin-left: 0.5rem;
+    color: var(--color-text-dim);
+    opacity: 0;
+    transition: opacity 0.2s;
+    text-decoration: none;
+  }
+  .boltdocs-heading:hover .header-anchor {
+    opacity: 1;
+  }
+
+  /* ═══ Shiki Dual Theme ═══ */
+  .shiki-wrapper .shiki.shiki-themes {
+    background-color: transparent !important;
+    color: var(--shiki-light) !important;
+  }
+  .shiki-wrapper .shiki.shiki-themes span {
+    color: var(--shiki-light);
+  }
+  :root[data-theme="dark"] .shiki-wrapper .shiki.shiki-themes,
+  :root:not(.theme-light) .shiki-wrapper .shiki.shiki-themes {
+    color: var(--shiki-dark) !important;
+  }
+  :root[data-theme="dark"] .shiki-wrapper .shiki.shiki-themes span,
+  :root:not(.theme-light) .shiki-wrapper .shiki.shiki-themes span {
+    color: var(--shiki-dark) !important;
+  }
+}

package/src/client/types.ts

@@ -1,4 +1,5 @@
-import React from "react";
+import React from 'react'
+import type { BoltdocsConfig } from '@node/config'
 
 /**
  * Metadata provided by the server for a specific route.
@@ -6,61 +7,164 @@ import React from "react";
  */
 export interface ComponentRoute {
   /** The final URL path */
-  path: string;
+  path: string
   /** The absolute filesystem path of the source file */
-  componentPath: string;
+  componentPath: string
   /** The page title */
-  title: string;
+  title: string
   /** Explicit order in the sidebar */
-  sidebarPosition?: number;
+  sidebarPosition?: number
   /** The relative path from the docs directory */
-  filePath: string;
+  filePath: string
   /** The group directory name */
-  group?: string;
+  group?: string
   /** The display title of the group */
-  groupTitle?: string;
+  groupTitle?: string
   /** Explicit order of the group in the sidebar */
-  groupPosition?: number;
+  groupPosition?: number
   /** Extracted markdown headings for search indexing */
-  headings?: { level: number; text: string; id: string }[];
+  headings?: { level: number; text: string; id: string }[]
   /** The page summary or description */
-  description?: string;
+  description?: string
   /** The locale this route belongs to, if i18n is configured */
-  locale?: string;
+  locale?: string
   /** The version this route belongs to, if versioning is configured */
-  version?: string;
+  version?: string
   /** Optional icon to display (Lucide icon name or raw SVG) */
-  icon?: string;
+  icon?: string
   /** The tab this route belongs to, if tabs are configured */
-  tab?: string;
+  tab?: string
   /** Optional badge to display next to the sidebar item */
-  badge?: string | { text: string; expires?: string };
+  badge?: string | { text: 'updated' | 'new' | 'deprecated'; expires?: string }
   /** Optional icon for the route's group */
-  groupIcon?: string;
+  groupIcon?: string
   /** The extracted plain-text content of the page for search indexing */
-  _content?: string;
+  _content?: string
   /** The raw markdown content of the page */
-  _rawContent?: string;
+  _rawContent?: string
 }
 
+/**
+ * Site configuration provided by the server.
+ */
+export type SiteConfig = BoltdocsConfig
+
 /**
  * Configuration options for initializing the Boltdocs client app.
  */
 export interface CreateBoltdocsAppOptions {
   /** CSS selector for the DOM element where the app should mount (e.g. '#root') */
-  target: string;
+  target: string
   /** Initial routes generated by the Vite plugin (`virtual:boltdocs-routes`) */
-  routes: ComponentRoute[];
+  routes: ComponentRoute[]
   /** The name of the documentation directory (e.g. 'docs') */
-  docsDirName: string;
+  docsDirName: string
   /** Site configuration (`virtual:boltdocs-config`) */
-  config: any;
+  config: SiteConfig
   /** Dynamic import mapping from `import.meta.glob` for the documentation pages */
-  modules: Record<string, () => Promise<any>>;
+  modules: Record<string, () => Promise<{ default: React.ComponentType<any> }>>
   /** The `import.meta.hot` instance necessary for fast refresh/HMR updates */
-  hot?: any;
+  hot?: {
+    accept: (cb?: (mod: any) => void) => void
+    dispose: (cb: (data: any) => void) => void
+    on: (event: string, cb: (data: any) => void) => void
+    data: any
+  }
   /** Optional custom React component to render when visiting the root path ('/') */
-  homePage?: React.ComponentType;
+  homePage?: React.ComponentType
+  /** Custom external pages mapped by their route path */
+  externalPages?: Record<string, React.ComponentType>
   /** Optional custom MDX components provided by plugins */
-  components?: Record<string, React.ComponentType<any>>;
+  components?: Record<string, React.ComponentType>
+}
+
+/**
+ * Types for CodeSandbox integration.
+ */
+export interface SandboxFile {
+  content: string | object
+  isBinary?: boolean
+}
+
+export type SandboxFiles = Record<string, SandboxFile>
+
+export interface SandboxOptions {
+  files?: SandboxFiles
+  dependencies?: Record<string, string>
+  devDependencies?: Record<string, string>
+  title?: string
+  description?: string
+  template?: string
+  /** The file path to open by default in the editor (e.g. `"src/App.tsx"`). */
+  entry?: string
+  /** Options for the embedded iframe view, used by `embedSandbox()`. */
+  embed?: SandboxEmbedOptions
+  /** Custom scripts for the package.json (e.g. `{ "start": "vite" }`). */
+  scripts?: Record<string, string>
+  /** Optional default theme configuration for the sandbox project. */
+  themeConfig?: Record<string, unknown>
+}
+
+export interface SandboxEmbedOptions {
+  /** Which panel to display: `"editor"`, `"preview"`, or `"split"`. */
+  view?: 'editor' | 'preview' | 'split'
+  /** Color theme: `"dark"` or `"light"`. */
+  theme?: 'dark' | 'light'
+  /** Whether to hide the navigation bar in the embed. */
+  hideNavigation?: boolean
+}
+
+/**
+ * Tab configuration for the documentation site.
+ */
+export interface BoltdocsTab {
+  id: string
+  text: string
+  icon?: string
+}
+
+/**
+ * Props for the Sidebar component.
+ */
+export interface SidebarProps {
+  routes: ComponentRoute[]
+  config: BoltdocsConfig
+}
+
+/**
+ * Props for the OnThisPage (TOC) component.
+ */
+export interface OnThisPageProps {
+  headings?: { level: number; text: string; id: string }[]
+  editLink?: string
+  communityHelp?: string
+  filePath?: string
+}
+
+/**
+ * Props for the Tabs component.
+ */
+export interface TabsProps {
+  tabs: BoltdocsTab[]
+  routes: ComponentRoute[]
+}
+
+/**
+ * Props for user-defined layout components (layout.tsx).
+ */
+export interface LayoutProps {
+  children: React.ReactNode
+}
+
+/**
+ * Unified type for navbar links.
+ */
+export interface NavbarLink {
+  label: string
+  href: string
+  active: boolean
+  /** Optional icon or string for external link indication */
+  to?: string
+  /** Nested items for NavigationMenu */
+  items?: NavbarLink[]
 }

package/src/client/utils/cn.ts

@@ -0,0 +1,6 @@
+import { type ClassValue, clsx } from 'clsx'
+import { twMerge } from 'tailwind-merge'
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}

package/src/client/utils/copy-clipboard.ts

@@ -0,0 +1,22 @@
+/**
+ * Copy text to clipboard.
+ * @param text - The text to copy.
+ * @returns True if the text was copied successfully.
+ */
+export const copyToClipboard = async (text: string) => {
+  try {
+    await navigator.clipboard.writeText(text)
+    return true
+  } catch {
+    // Fallback
+    const textarea = document.createElement('textarea')
+    textarea.value = text
+    textarea.style.position = 'fixed'
+    textarea.style.opacity = '0'
+    document.body.appendChild(textarea)
+    textarea.select()
+    document.execCommand('copy')
+    document.body.removeChild(textarea)
+    return true
+  }
+}

package/src/client/utils/get-base-file-path.ts

@@ -0,0 +1,21 @@
+/**
+ * Get the base file path by removing version and locale prefixes.
+ * @param filePath - The full file path.
+ * @param version - The version to remove from the path.
+ * @param locale - The locale to remove from the path.
+ * @returns The base file path.
+ */
+export function getBaseFilePath(
+  filePath: string,
+  version: string | undefined,
+  locale: string | undefined,
+): string {
+  let path = filePath
+  if (version && (path === version || path.startsWith(version + '/'))) {
+    path = path === version ? 'index.md' : path.slice(version.length + 1)
+  }
+  if (locale && (path === locale || path.startsWith(locale + '/'))) {
+    path = path === locale ? 'index.md' : path.slice(locale.length + 1)
+  }
+  return path
+}