@usecross/docs 0.1.0

package/src/lib/utils.ts

@@ -0,0 +1,9 @@
+import { clsx, type ClassValue } from 'clsx'
+import { twMerge } from 'tailwind-merge'
+
+/**
+ * Merge Tailwind CSS classes with clsx
+ */
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}

package/src/ssr.tsx

@@ -0,0 +1,39 @@
+import { createInertiaApp } from '@inertiajs/react'
+import createServer from '@inertiajs/react/server'
+import ReactDOMServer from 'react-dom/server'
+import type { DocsAppConfig } from './types'
+
+/**
+ * Create an SSR server for documentation.
+ *
+ * @example
+ * ```tsx
+ * import { createDocsServer, DocsPage } from '@usecross/docs'
+ *
+ * createDocsServer({
+ *   pages: {
+ *     'docs/DocsPage': DocsPage,
+ *   },
+ *   title: (title) => `${title} - My Docs`,
+ * })
+ * ```
+ */
+export function createDocsServer(config: DocsAppConfig): void {
+  const { pages, title } = config
+
+  createServer((page) =>
+    createInertiaApp({
+      page,
+      render: ReactDOMServer.renderToString,
+      title: title ?? ((pageTitle) => (pageTitle ? `${pageTitle}` : 'Documentation')),
+      resolve: (name) => {
+        const pageComponent = pages[name]
+        if (!pageComponent) {
+          throw new Error(`Page component "${name}" not found`)
+        }
+        return pageComponent
+      },
+      setup: ({ App, props }) => <App {...props} />,
+    })
+  )
+}

package/src/styles.css

@@ -0,0 +1,128 @@
+/**
+ * Cross-Docs default styles
+ *
+ * Import this file in your app's CSS entry point:
+ * @import '@usecross/docs/styles.css';
+ *
+ * Then add Tailwind directives:
+ * @tailwind base;
+ * @tailwind components;
+ * @tailwind utilities;
+ */
+
+@import url('https://fonts.googleapis.com/css2?family=Fira+Code:wght@400;500;600&display=swap');
+
+@layer base {
+  :root {
+    /* Font stacks */
+    --font-sans: system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial,
+      sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol';
+    --font-heading: system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif;
+    --font-mono: 'Fira Code', Consolas, Monaco, 'Andale Mono', monospace;
+
+    /* Code highlighting - matches Starlight/Expressive Code dark theme */
+    --shiki-color-text: #e2e8f0;
+    --shiki-color-background: #24292f;
+    --shiki-token-constant: #7dd3fc;
+    --shiki-token-string: #86efac;
+    --shiki-token-comment: #64748b;
+    --shiki-token-keyword: #f472b6;
+    --shiki-token-parameter: #e2e8f0;
+    --shiki-token-function: #c4b5fd;
+    --shiki-token-string-expression: #86efac;
+    --shiki-token-punctuation: #94a3b8;
+    --shiki-token-link: #38bdf8;
+  }
+
+  html {
+    /* Note: scroll-behavior: smooth removed to prevent animated scroll on page refresh */
+  }
+
+  /* Only apply smooth scrolling when navigating to anchor links */
+  html:focus-within {
+    scroll-behavior: smooth;
+  }
+
+  body {
+    @apply antialiased;
+    font-family: var(--font-sans);
+    font-weight: 400;
+    background: #ffffff;
+    color: #1f2937;
+  }
+
+  /* Headings use heading font */
+  h1, h2, h3, h4, h5, h6 {
+    font-family: var(--font-heading);
+    font-weight: 700;
+  }
+
+  /* Monospace fonts for code */
+  code, pre, kbd, samp {
+    font-family: var(--font-mono);
+  }
+}
+
+@layer components {
+  /* Prose content styles */
+  .prose {
+    font-size: 1rem;
+    line-height: 1.75;
+  }
+
+  /* Scroll margin for headings (so they don't hide under fixed header) */
+  .prose h1,
+  .prose h2,
+  .prose h3,
+  .prose h4,
+  .prose h5,
+  .prose h6 {
+    scroll-margin-top: 6rem;
+  }
+
+  /* Code block styling - rounded corners like Starlight */
+  .prose pre {
+    @apply !bg-[#24292f] !p-0 overflow-hidden rounded-lg;
+  }
+
+  .prose pre code {
+    @apply !bg-transparent !p-4 block overflow-x-auto text-sm;
+  }
+
+  /* Inline code styling */
+  .prose :not(pre) > code {
+    @apply bg-gray-100 px-1.5 py-0.5 rounded text-sm font-medium text-gray-800;
+  }
+
+  .prose :not(pre) > code::before,
+  .prose :not(pre) > code::after {
+    content: none;
+  }
+}
+
+/* Syntax highlighting - rounded corners like Starlight */
+.shiki {
+  @apply !bg-[#24292f] overflow-hidden rounded-lg;
+}
+
+.shiki code {
+  @apply block p-4 overflow-x-auto text-sm leading-relaxed;
+}
+
+/* Scrollbar styling */
+::-webkit-scrollbar {
+  width: 8px;
+  height: 8px;
+}
+
+::-webkit-scrollbar-track {
+  @apply bg-transparent;
+}
+
+::-webkit-scrollbar-thumb {
+  @apply bg-gray-300 rounded-full;
+}
+
+::-webkit-scrollbar-thumb:hover {
+  @apply bg-gray-400;
+}

package/src/tailwind.preset.cjs

@@ -0,0 +1,118 @@
+/**
+ * Cross-Docs Tailwind CSS preset
+ *
+ * @example
+ * ```js
+ * // tailwind.config.js
+ * const docsPreset = require('@usecross/docs/tailwind.preset')
+ *
+ * module.exports = {
+ *   presets: [docsPreset],
+ *   content: [
+ *     './frontend/**\/*.{ts,tsx}',
+ *     './node_modules/@usecross/docs/**\/*.{js,tsx}',
+ *   ],
+ *   theme: {
+ *     extend: {
+ *       colors: {
+ *         primary: { // Override with your brand colors },
+ *       },
+ *     },
+ *   },
+ * }
+ * ```
+ */
+module.exports = {
+  darkMode: 'class',
+  theme: {
+    extend: {
+      maxWidth: {
+        '8xl': '88rem',
+      },
+      fontFamily: {
+        sans: [
+          'system-ui',
+          '-apple-system',
+          'Segoe UI',
+          'Roboto',
+          'Helvetica',
+          'Arial',
+          'sans-serif',
+          'Apple Color Emoji',
+          'Segoe UI Emoji',
+          'Segoe UI Symbol',
+        ],
+        heading: [
+          'system-ui',
+          '-apple-system',
+          'Segoe UI',
+          'Roboto',
+          'sans-serif',
+        ],
+        mono: ['Fira Code', 'Consolas', 'Monaco', 'Andale Mono', 'monospace'],
+      },
+      colors: {
+        // Default primary colors - sky blue (can be overridden)
+        primary: {
+          50: '#f0f9ff',
+          100: '#e0f2fe',
+          200: '#bae6fd',
+          300: '#7dd3fc',
+          400: '#38bdf8',
+          500: '#0ea5e9',
+          600: '#0284c7',
+          700: '#0369a1',
+          800: '#075985',
+          900: '#0c4a6e',
+          950: '#082f49',
+        },
+        // Dark colors for code blocks
+        dark: {
+          800: '#1e293b',
+          900: '#0f172a',
+        },
+      },
+      typography: (theme) => ({
+        DEFAULT: {
+          css: {
+            maxWidth: 'none',
+            color: theme('colors.gray.700'),
+            a: {
+              color: theme('colors.primary.600'),
+              '&:hover': {
+                color: theme('colors.primary.700'),
+              },
+            },
+            'code::before': {
+              content: '""',
+            },
+            'code::after': {
+              content: '""',
+            },
+            code: {
+              backgroundColor: theme('colors.gray.100'),
+              padding: '0.25rem 0.375rem',
+              borderRadius: '0.25rem',
+              fontWeight: '500',
+            },
+          },
+        },
+        invert: {
+          css: {
+            color: theme('colors.gray.300'),
+            a: {
+              color: theme('colors.primary.400'),
+              '&:hover': {
+                color: theme('colors.primary.300'),
+              },
+            },
+            code: {
+              backgroundColor: theme('colors.gray.800'),
+            },
+          },
+        },
+      }),
+    },
+  },
+  plugins: [require('@tailwindcss/typography')],
+}

package/src/types.ts

@@ -0,0 +1,91 @@
+/**
+ * Cross-Docs TypeScript type definitions
+ */
+
+import type { ReactNode } from 'react'
+
+/** Single navigation item */
+export interface NavItem {
+  title: string
+  href: string
+}
+
+/** Navigation section containing multiple items */
+export interface NavSection {
+  title: string
+  items: NavItem[]
+}
+
+/** Shared props passed to all pages via Inertia */
+export interface SharedProps {
+  nav: NavSection[]
+  currentPath: string
+  /** Logo image URL (from Python backend) */
+  logoUrl?: string
+  /** Logo image URL for dark/inverted contexts (from Python backend) */
+  logoInvertedUrl?: string
+  /** Footer logo image URL (from Python backend) */
+  footerLogoUrl?: string
+  /** GitHub repository URL (from Python backend) */
+  githubUrl?: string
+  /** Additional navigation links (from Python backend) */
+  navLinks?: Array<{ label: string; href: string }>
+}
+
+/** Document content structure */
+export interface DocContent {
+  title: string
+  description: string
+  body: string
+}
+
+/** Props for DocsLayout component */
+export interface DocsLayoutProps {
+  children: ReactNode
+  title: string
+  description?: string
+  /** Custom logo component (React node) */
+  logo?: ReactNode
+  /** Custom logo for dark/inverted contexts (React node) */
+  logoInverted?: ReactNode
+  /** Logo image URL (alternative to logo prop, can be passed from backend) */
+  logoUrl?: string
+  /** Logo image URL for dark/inverted contexts */
+  logoInvertedUrl?: string
+  /** GitHub repository URL (shows GitHub icon in nav) */
+  githubUrl?: string
+  /** Additional navigation links */
+  navLinks?: Array<{ label: string; href: string }>
+  /** Custom footer component */
+  footer?: ReactNode
+}
+
+/** Props for Sidebar component */
+export interface SidebarProps {
+  nav: NavSection[]
+  currentPath: string
+  className?: string
+}
+
+/** Props for Markdown component */
+export interface MarkdownProps {
+  content: string
+  /** Override default markdown components */
+  components?: Record<string, React.ComponentType<any>>
+}
+
+/** Props for CodeBlock component */
+export interface CodeBlockProps {
+  code: string
+  language?: string
+  filename?: string
+  showLineNumbers?: boolean
+  theme?: string
+  className?: string
+}
+
+/** Configuration for createDocsApp */
+export interface DocsAppConfig {
+  pages: Record<string, React.ComponentType<any>>
+  title?: (pageTitle: string) => string
+}