@usecross/docs 0.10.2 → 0.12.0

package/dist/ssr.d.ts

@@ -1,4 +1,4 @@
-import { c as DocsAppConfig } from './types-DlTTA3Dc.js';
+import { h as DocsAppConfig } from './types-_anC1UJu.js';
 import 'react';
 
 /**

package/dist/types-_anC1UJu.d.ts

@@ -0,0 +1,320 @@
+import { ReactNode } from 'react';
+
+/**
+ * Cross-Docs TypeScript type definitions
+ */
+
+/** Single navigation item */
+interface NavItem {
+    title: string;
+    href: string;
+}
+/** Navigation section containing multiple items */
+interface NavSection {
+    title: string;
+    items: NavItem[];
+}
+/** Documentation set metadata (for multi-docs mode) */
+interface DocSetMeta {
+    name: string;
+    slug: string;
+    description: string;
+    /** Emoji or short text icon (e.g., "🍓") */
+    icon?: string;
+    /** URL to icon image */
+    iconUrl?: string;
+    prefix: string;
+}
+/** Shared props passed to all pages via Inertia */
+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;
+    /** Footer logo image URL for dark mode (from Python backend) */
+    footerLogoInvertedUrl?: string;
+    /** GitHub repository URL (from Python backend) */
+    githubUrl?: string;
+    /** Additional navigation links (from Python backend) */
+    navLinks?: Array<{
+        label: string;
+        href: string;
+    }>;
+    /** Available documentation sets (multi-docs mode) */
+    docSets?: DocSetMeta[];
+    /** Current documentation set slug (multi-docs mode) */
+    currentDocSet?: string;
+}
+/** Table of contents item */
+interface TOCItem {
+    id: string;
+    /** Display text (use either text or title) */
+    text?: string;
+    /** Display title (use either text or title) */
+    title?: string;
+    level: number;
+}
+/** Document content structure */
+interface DocContent {
+    title: string;
+    description: string;
+    body: string;
+    toc?: TOCItem[];
+}
+/** Props for DocsLayout component */
+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 header component (replaces entire header). Can be a ReactNode or a function that receives mobile menu props. */
+    header?: ReactNode | ((props: {
+        mobileMenuOpen: boolean;
+        toggleMobileMenu: () => void;
+    }) => ReactNode);
+    /** Header height in pixels. Used to calculate content offset. Defaults to 64 (h-16). */
+    headerHeight?: number;
+    /** Custom footer component */
+    footer?: ReactNode;
+    /** Table of contents items for the current page */
+    toc?: TOCItem[];
+}
+/** Props for TableOfContents component */
+interface TableOfContentsProps {
+    items: TOCItem[];
+    className?: string;
+    style?: React.CSSProperties;
+}
+/** Props for Sidebar component */
+interface SidebarProps {
+    nav: NavSection[];
+    currentPath: string;
+    className?: string;
+    /** Available documentation sets (multi-docs mode) */
+    docSets?: DocSetMeta[];
+    /** Current documentation set slug (multi-docs mode) */
+    currentDocSet?: string;
+}
+/** Props for Markdown component */
+interface MarkdownProps {
+    content: string;
+    /** Override default markdown components */
+    components?: Record<string, React.ComponentType<any>>;
+}
+/** Props for CodeBlock component */
+interface CodeBlockProps {
+    code: string;
+    language?: string;
+    filename?: string;
+    showLineNumbers?: boolean;
+    theme?: string;
+    className?: string;
+}
+/** Configuration for createDocsApp */
+interface DocsAppConfig {
+    pages: Record<string, React.ComponentType<any>>;
+    title?: (pageTitle: string) => string;
+    /** Custom components to use in markdown (e.g., Alert, Card, etc.) */
+    components?: Record<string, React.ComponentType<any>>;
+}
+/** Griffe object kinds */
+type GriffeKind = 'module' | 'class' | 'function' | 'attribute';
+/** Griffe docstring section kinds */
+type GriffeDocstringSectionKind = 'text' | 'parameters' | 'returns' | 'yields' | 'receives' | 'raises' | 'warns' | 'examples' | 'attributes' | 'other' | 'deprecated' | 'admonition';
+/** Griffe expression (type annotation) */
+interface GriffeExpression {
+    /** String representation of the expression */
+    str?: string;
+    /** Canonical string representation */
+    canonical?: string;
+    /** For name expressions */
+    name?: string;
+    /** For subscript expressions (e.g., List[int]) */
+    slice?: GriffeExpression;
+    /** For compound expressions */
+    left?: GriffeExpression;
+    right?: GriffeExpression;
+}
+/** Griffe parameter */
+interface GriffeParameter {
+    name: string;
+    kind: 'positional-only' | 'positional-or-keyword' | 'var-positional' | 'keyword-only' | 'var-keyword';
+    annotation?: GriffeExpression | string;
+    default?: string;
+}
+/** Griffe docstring section element (for parameters, returns, etc.) */
+interface GriffeDocstringElement {
+    name?: string;
+    annotation?: GriffeExpression | string;
+    description?: string;
+    value?: string;
+}
+/** Griffe docstring section */
+interface GriffeDocstringSection {
+    kind: GriffeDocstringSectionKind;
+    value?: string | GriffeDocstringElement[];
+    title?: string;
+}
+/** Griffe parsed docstring */
+interface GriffeDocstring {
+    value: string;
+    parsed?: GriffeDocstringSection[];
+}
+/** Griffe decorator */
+interface GriffeDecorator {
+    value: string;
+    lineno?: number;
+}
+/** Base Griffe object with common properties */
+interface GriffeObjectBase {
+    kind: GriffeKind;
+    name: string;
+    path?: string;
+    filepath?: string;
+    /** Relative file path (set by cross-docs) */
+    relative_filepath?: string;
+    /** Relative file path within the package (set by Griffe) */
+    relative_package_filepath?: string;
+    lineno?: number;
+    endlineno?: number;
+    docstring?: GriffeDocstring;
+    labels?: string[];
+}
+/** Griffe function/method */
+interface GriffeFunction extends GriffeObjectBase {
+    kind: 'function';
+    parameters?: GriffeParameter[];
+    returns?: GriffeExpression | string;
+    decorators?: GriffeDecorator[];
+    /** Whether this is an async function */
+    is_async?: boolean;
+}
+/** Griffe attribute */
+interface GriffeAttribute extends GriffeObjectBase {
+    kind: 'attribute';
+    annotation?: GriffeExpression | string;
+    value?: string;
+}
+/** Griffe class */
+interface GriffeClass extends GriffeObjectBase {
+    kind: 'class';
+    bases?: Array<GriffeExpression | string>;
+    decorators?: GriffeDecorator[];
+    members?: Record<string, GriffeMember>;
+}
+/** Griffe module */
+interface GriffeModule extends GriffeObjectBase {
+    kind: 'module';
+    members?: Record<string, GriffeMember>;
+    /** Generator metadata added by cross-docs */
+    _generator?: string;
+    _plugin?: string;
+    _version?: string;
+}
+/** Griffe alias (re-export) */
+interface GriffeAlias {
+    kind: 'alias';
+    name: string;
+    path?: string;
+    /** The target path this alias points to */
+    target_path: string;
+    lineno?: number;
+    endlineno?: number;
+}
+/** Union of all Griffe member types */
+type GriffeMember = GriffeModule | GriffeClass | GriffeFunction | GriffeAttribute | GriffeAlias;
+/** Props for API documentation pages */
+interface APIPageProps {
+    /** Full API data (the entire module tree) */
+    apiData: GriffeModule;
+    /** Current item being viewed (module, class, or function) */
+    currentItem?: GriffeMember;
+    /** Current URL path */
+    currentPath: string;
+    /** Current module name */
+    currentModule: string;
+    /** Navigation structure for API sidebar */
+    apiNav: NavSection[];
+    /** URL prefix for API links (e.g., /docs/api-reference) */
+    prefix: string;
+    /** Logo URL */
+    logoUrl?: string;
+    /** Logo URL for dark mode */
+    logoInvertedUrl?: string;
+    /** Footer logo URL */
+    footerLogoUrl?: string;
+    /** Footer logo URL for dark mode */
+    footerLogoInvertedUrl?: string;
+    /** GitHub URL */
+    githubUrl?: string;
+    /** Navigation links */
+    navLinks?: Array<{
+        label: string;
+        href: string;
+    }>;
+    /** Custom header component (replaces entire header). Can be a ReactNode or a function that receives mobile menu props. */
+    header?: React.ReactNode | ((props: {
+        mobileMenuOpen: boolean;
+        toggleMobileMenu: () => void;
+    }) => React.ReactNode);
+    /** Header height in pixels. Used to calculate content offset. Defaults to 64 (h-16). */
+    headerHeight?: number;
+    /** Custom footer component */
+    footer?: React.ReactNode;
+}
+/** Props for ModuleDoc component */
+interface ModuleDocProps {
+    module: GriffeModule;
+    /** URL prefix for links */
+    prefix?: string;
+}
+/** Props for ClassDoc component */
+interface ClassDocProps {
+    cls: GriffeClass;
+    /** URL prefix for links */
+    prefix?: string;
+}
+/** Props for FunctionDoc component */
+interface FunctionDocProps {
+    fn: GriffeFunction;
+    /** Whether this is a method (inside a class) */
+    isMethod?: boolean;
+}
+/** Props for Signature component */
+interface SignatureProps {
+    fn: GriffeFunction;
+    /** Show full path or just name */
+    showPath?: boolean;
+}
+/** Props for Docstring component */
+interface DocstringProps {
+    docstring: GriffeDocstring;
+    /** Show raw text instead of parsed sections */
+    raw?: boolean;
+}
+/** Props for ParameterTable component */
+interface ParameterTableProps {
+    parameters: GriffeParameter[];
+    /** Docstring sections for parameter descriptions */
+    docstringSections?: GriffeDocstringSection[];
+}
+
+export type { APIPageProps as A, CodeBlockProps as C, DocSetMeta as D, FunctionDocProps as F, GriffeModule as G, MarkdownProps as M, NavSection as N, ParameterTableProps as P, SidebarProps as S, TableOfContentsProps as T, DocsLayoutProps as a, DocContent as b, GriffeClass as c, GriffeFunction as d, GriffeDocstring as e, GriffeParameter as f, GriffeDocstringSection as g, DocsAppConfig as h, NavItem as i, SharedProps as j, TOCItem as k, GriffeKind as l, GriffeDocstringSectionKind as m, GriffeExpression as n, GriffeDocstringElement as o, GriffeDecorator as p, GriffeObjectBase as q, GriffeAttribute as r, GriffeMember as s, ModuleDocProps as t, ClassDocProps as u, SignatureProps as v, DocstringProps as w };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usecross/docs",
-  "version": "0.10.2",
+  "version": "0.12.0",
   "description": "Documentation framework built on Cross-Inertia",
   "type": "module",
   "main": "./dist/index.js",

package/src/components/DocsLayout.tsx

@@ -6,7 +6,7 @@ import { ThemeToggle } from './ThemeToggle'
 import { useTheme } from './ThemeProvider'
 import type { DocsLayoutProps, SharedProps } from '../types'
 
-function MobileMenuButton({ onClick, isOpen }: { onClick: () => void; isOpen: boolean }) {
+export function MobileMenuButton({ onClick, isOpen }: { onClick: () => void; isOpen: boolean }) {
   return (
     <button
       onClick={onClick}
@@ -52,6 +52,8 @@ export function DocsLayout({
   logoInvertedUrl: propLogoInvertedUrl,
   githubUrl: propGithubUrl,
   navLinks: propNavLinks,
+  header,
+  headerHeight = 64,
   footer,
   toc,
 }: DocsLayoutProps) {
@@ -86,88 +88,102 @@ export function DocsLayout({
       <Head title={title} />
 
       {/* Fixed navigation */}
-      <nav className="fixed w-full z-50 bg-white/95 dark:bg-[#0f0f0f]/95 backdrop-blur-sm border-b border-gray-200 dark:border-gray-800 transition-colors">
-        <div className="px-4 lg:px-10">
-          <div className="flex justify-between h-16 items-center">
-            <div className="flex items-center gap-2">
-              <MobileMenuButton onClick={() => setMobileMenuOpen(!mobileMenuOpen)} isOpen={mobileMenuOpen} />
-              {headerLogo ? (
-                <Link href="/" className="flex items-center">
-                  {headerLogo}
-                </Link>
-              ) : (
-                <Link href="/" className="font-bold text-lg text-gray-900 dark:text-white">
-                  Docs
-                </Link>
-              )}
-            </div>
-            <div className="flex items-center gap-6">
-              <div className="-mr-2">
-                <ThemeToggle size="sm" />
+      {(typeof header === 'function'
+        ? header({ mobileMenuOpen, toggleMobileMenu: () => setMobileMenuOpen(!mobileMenuOpen) })
+        : header) || (
+        <nav className="fixed w-full z-50 bg-white/95 dark:bg-[#0f0f0f]/95 backdrop-blur-sm border-b border-gray-200 dark:border-gray-800 transition-colors">
+          <div className="px-4 lg:px-10">
+            <div className="flex justify-between h-16 items-center">
+              <div className="flex items-center gap-2">
+                <MobileMenuButton onClick={() => setMobileMenuOpen(!mobileMenuOpen)} isOpen={mobileMenuOpen} />
+                {headerLogo ? (
+                  <Link href="/" className="flex items-center">
+                    {headerLogo}
+                  </Link>
+                ) : (
+                  <Link href="/" className="font-bold text-lg text-gray-900 dark:text-white">
+                    Docs
+                  </Link>
+                )}
               </div>
+              <div className="flex items-center gap-6">
+                <div className="-mr-2">
+                  <ThemeToggle size="sm" />
+                </div>
 
-              {navLinks.map((link) => (
-                <Link
-                  key={link.href}
-                  href={link.href}
-                  className="hidden sm:block text-gray-700 dark:text-gray-300 font-medium hover:text-primary-600 dark:hover:text-primary-400 transition-colors"
-                >
-                  {link.label}
-                </Link>
-              ))}
-              {githubUrl && (
-                <a
-                  href={githubUrl}
-                  target="_blank"
-                  rel="noopener noreferrer"
-                  className="text-gray-700 dark:text-gray-300 hover:text-primary-600 dark:hover:text-primary-400 transition-colors"
-                >
-                  <GitHubIcon />
-                </a>
-              )}
+                {navLinks.map((link) => (
+                  <Link
+                    key={link.href}
+                    href={link.href}
+                    className="hidden sm:block text-gray-700 dark:text-gray-300 font-medium hover:text-primary-600 dark:hover:text-primary-400 transition-colors"
+                  >
+                    {link.label}
+                  </Link>
+                ))}
+                {githubUrl && (
+                  <a
+                    href={githubUrl}
+                    target="_blank"
+                    rel="noopener noreferrer"
+                    className="text-gray-700 dark:text-gray-300 hover:text-primary-600 dark:hover:text-primary-400 transition-colors"
+                  >
+                    <GitHubIcon />
+                  </a>
+                )}
+              </div>
             </div>
           </div>
-        </div>
-      </nav>
+        </nav>
+      )}
 
       {/* Mobile sidebar */}
       {mobileMenuOpen && (
         <div className="fixed inset-0 z-40 lg:hidden">
           <div className="fixed inset-0 bg-black/50 dark:bg-black/70" onClick={() => setMobileMenuOpen(false)} />
-          <div className="fixed inset-y-0 left-0 w-64 overflow-y-auto bg-white dark:bg-[#0f0f0f] px-4 py-6 pt-20 border-r border-gray-200 dark:border-gray-800 transition-colors">
+          <div
+            className="fixed inset-y-0 left-0 w-72 overflow-y-auto bg-white dark:bg-[#0f0f0f] px-4 py-6 border-r border-gray-200 dark:border-gray-800 transition-colors"
+            style={{ paddingTop: headerHeight + 16 }}
+          >
             <Sidebar nav={nav} currentPath={currentPath} docSets={docSets} currentDocSet={currentDocSet} />
           </div>
         </div>
       )}
 
       {/* Main content area */}
-      <div className="bg-white dark:bg-[#0f0f0f] pt-16 w-full flex-1 transition-colors">
+      <div className="bg-white dark:bg-[#0f0f0f] w-full flex-1 transition-colors" style={{ paddingTop: headerHeight }}>
         <div className="flex">
           {/* Desktop sidebar - fixed width */}
-          <aside className="hidden lg:block w-72 flex-shrink-0 border-r border-gray-200 dark:border-gray-800 min-h-[calc(100vh-4rem)] transition-colors">
-            <nav className="sticky top-16 px-4 lg:px-10 py-6 max-h-[calc(100vh-4rem)] overflow-y-auto">
+          <aside
+            className="hidden lg:block w-[24rem] shrink-0 border-r border-gray-200 dark:border-gray-800 transition-colors"
+            style={{ minHeight: `calc(100vh - ${headerHeight}px)` }}
+          >
+            <nav
+              className="sticky px-4 lg:px-10 py-6 overflow-y-auto"
+              style={{ top: headerHeight, maxHeight: `calc(100vh - ${headerHeight}px)` }}
+            >
               <Sidebar nav={nav} currentPath={currentPath} docSets={docSets} currentDocSet={currentDocSet} />
             </nav>
           </aside>
 
           {/* Right section: content + TOC + footer (not under left sidebar) */}
           <div className="flex-1 min-w-0 flex flex-col">
-            <div className="flex flex-1">
-              {/* Main content */}
-              <main className="flex-1 min-w-0 p-4 lg:px-10 lg:py-6">
-                <article className="prose prose-lg max-w-3xl prose-headings:font-bold prose-headings:tracking-tight prose-h1:text-3xl prose-h1:mb-4 prose-h2:text-2xl prose-h2:mt-10 first:prose-h2:mt-0 prose-h3:text-xl prose-a:text-primary-600 dark:prose-a:text-primary-400 prose-a:no-underline hover:prose-a:underline prose-code:bg-gray-100 dark:prose-code:bg-gray-800 prose-code:px-1.5 prose-code:py-0.5 prose-code:rounded prose-code:before:content-none prose-code:after:content-none dark:prose-headings:text-white dark:prose-strong:text-white dark:text-gray-300">
-                  {children}
-                </article>
-              </main>
+            <div className="flex-1 p-4 lg:px-10 lg:py-6">
+              <div className="flex gap-5">
+                {/* Main content */}
+                <main className="min-w-0 w-full max-w-4xl">
+                  <article className="prose prose-lg max-w-none prose-headings:font-bold prose-headings:tracking-tight prose-h1:text-3xl prose-h1:mb-4 prose-h2:text-2xl prose-h2:mt-10 first:prose-h2:mt-0 prose-h3:text-xl prose-a:text-primary-600 dark:prose-a:text-primary-400 prose-a:no-underline hover:prose-a:underline prose-code:bg-gray-100 dark:prose-code:bg-gray-800 prose-code:px-1.5 prose-code:py-0.5 prose-code:rounded prose-code:before:content-none prose-code:after:content-none dark:prose-headings:text-white dark:prose-strong:text-white dark:text-gray-300">
+                    {children}
+                  </article>
+                </main>
 
-              {/* Table of Contents - desktop only */}
-              {toc && toc.length > 0 && (
-                <aside className="hidden xl:block w-64 flex-shrink-0 transition-colors">
-                  <div className="sticky top-16 px-4 py-6 max-h-[calc(100vh-4rem)] overflow-y-auto">
-                    <TableOfContents items={toc} />
-                  </div>
-                </aside>
-              )}
+                {/* Table of Contents - desktop only */}
+                {toc && toc.length > 0 && (
+                  <aside className="hidden xl:block w-56 shrink-0 transition-colors">
+                    <TableOfContents items={toc} className="sticky overflow-y-auto"
+                      style={{ top: headerHeight + 24, maxHeight: `calc(100vh - ${headerHeight + 24}px)` }} />
+                  </aside>
+                )}
+              </div>
             </div>
 
             {/* Footer - spans from after sidebar to right edge */}