@usecross/docs 0.11.0 → 0.12.0

package/dist/ssr.d.ts

@@ -1,4 +1,4 @@
-import { c as DocsAppConfig } from './types-Qbhh2Ihz.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.11.0",
+  "version": "0.12.0",
   "description": "Documentation framework built on Cross-Inertia",
   "type": "module",
   "main": "./dist/index.js",

package/src/components/Sidebar.tsx

@@ -1,13 +1,151 @@
+import { useState } from 'react'
 import { Link } from '@inertiajs/react'
 import { cn } from '../lib/utils'
 import { DocSetSelector } from './DocSetSelector'
-import type { SidebarProps } from '../types'
+import type { SidebarProps, NavSection } from '../types'
+
+/**
+ * Chevron icon for collapsible sections
+ */
+function ChevronIcon({ expanded, className }: { expanded: boolean; className?: string }) {
+  return (
+    <svg
+      className={cn('w-4 h-4 transition-transform duration-200', expanded && 'rotate-90', className)}
+      fill="none"
+      viewBox="0 0 24 24"
+      stroke="currentColor"
+    >
+      <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M9 5l7 7-7 7" />
+    </svg>
+  )
+}
+
+/**
+ * Collapsible navigation section
+ */
+function CollapsibleSection({
+  section,
+  currentPath,
+  defaultExpanded = true,
+  compact = false,
+}: {
+  section: NavSection
+  currentPath: string
+  defaultExpanded?: boolean
+  compact?: boolean
+}) {
+  // Check if current path is in this section
+  const isActive = section.items.some(
+    (item) => currentPath === item.href || currentPath + '/' === item.href
+  )
+  const [expanded, setExpanded] = useState(defaultExpanded || isActive)
+
+  return (
+    <div>
+      <button
+        onClick={() => setExpanded(!expanded)}
+        className="w-full flex items-center justify-between mb-2 group"
+      >
+        <h3 className={cn(
+          'text-sm font-mono uppercase tracking-widest text-gray-500 dark:text-gray-400',
+          'group-hover:text-gray-700 dark:group-hover:text-gray-300 transition-colors'
+        )}>
+          {section.title}
+        </h3>
+        <ChevronIcon expanded={expanded} className="text-gray-400 dark:text-gray-500" />
+      </button>
+      {expanded && (
+        <ul className={cn(
+          'border-l-2 border-gray-200 dark:border-gray-700',
+          compact ? 'space-y-0.5' : 'space-y-1.5'
+        )}>
+          {section.items.map((item) => (
+            <li key={item.href}>
+              <Link
+                href={item.href}
+                className={cn(
+                  'block border-l-2 py-1 pl-4 leading-snug transition-colors -ml-0.5',
+                  compact ? 'text-sm' : 'text-[15px]',
+                  currentPath === item.href || currentPath + '/' === item.href
+                    ? 'border-primary-500 text-gray-900 dark:text-white font-semibold'
+                    : 'border-transparent text-gray-600 dark:text-gray-400 hover:border-primary-300 dark:hover:border-primary-400 hover:text-gray-900 dark:hover:text-white'
+                )}
+              >
+                {item.title}
+              </Link>
+            </li>
+          ))}
+        </ul>
+      )}
+    </div>
+  )
+}
+
+/**
+ * Static navigation section (non-collapsible)
+ */
+function StaticSection({
+  section,
+  currentPath,
+  compact = false,
+}: {
+  section: NavSection
+  currentPath: string
+  compact?: boolean
+}) {
+  return (
+    <div>
+      <h3 className="mb-3 text-sm font-mono uppercase tracking-widest text-gray-500 dark:text-gray-400">
+        {section.title}
+      </h3>
+      <ul className={cn(
+        'border-l-2 border-gray-200 dark:border-gray-700',
+        compact ? 'space-y-0.5' : 'space-y-1.5'
+      )}>
+        {section.items.map((item) => (
+          <li key={item.href}>
+            <Link
+              href={item.href}
+              className={cn(
+                'block border-l-2 py-1 pl-4 leading-snug transition-colors -ml-0.5',
+                compact ? 'text-sm' : 'text-[15px]',
+                currentPath === item.href || currentPath + '/' === item.href
+                  ? 'border-primary-500 text-gray-900 dark:text-white font-semibold'
+                  : 'border-transparent text-gray-600 dark:text-gray-400 hover:border-primary-300 dark:hover:border-primary-400 hover:text-gray-900 dark:hover:text-white'
+              )}
+            >
+              {item.title}
+            </Link>
+          </li>
+        ))}
+      </ul>
+    </div>
+  )
+}
+
+export interface ExtendedSidebarProps extends SidebarProps {
+  /** Use compact styling (smaller text) */
+  compact?: boolean
+  /** Make sections collapsible */
+  collapsible?: boolean
+  /** Collapse sections with more than N items by default */
+  collapseThreshold?: number
+}
 
 /**
  * Documentation sidebar with section-based navigation.
- * In multi-docs mode, includes a dropdown selector at the top.
+ * Supports both docs and API navigation styles.
  */
-export function Sidebar({ nav, currentPath, className, docSets, currentDocSet }: SidebarProps) {
+export function Sidebar({
+  nav,
+  currentPath,
+  className,
+  docSets,
+  currentDocSet,
+  compact = false,
+  collapsible = false,
+  collapseThreshold = 10,
+}: ExtendedSidebarProps) {
   return (
     <nav className={cn('space-y-6', className)}>
       {/* Doc Set Selector - only shown in multi-docs mode */}
@@ -16,31 +154,36 @@ export function Sidebar({ nav, currentPath, className, docSets, currentDocSet }:
       )}
 
       {/* Navigation Sections */}
-      <div className="space-y-8">
-      {nav.map((section) => (
-        <div key={section.title}>
-          <h3 className="mb-3 text-sm font-mono uppercase tracking-widest text-gray-500 dark:text-gray-400">
-            {section.title}
-          </h3>
-          <ul className="space-y-1.5 border-l-2 border-gray-200 dark:border-gray-700">
-            {section.items.map((item) => (
-              <li key={item.href}>
-                <Link
-                  href={item.href}
-                  className={cn(
-                    'block border-l-2 py-1 pl-4 text-[17px] leading-snug transition-colors -ml-0.5',
-                    currentPath === item.href
-                      ? 'border-primary-500 text-gray-900 dark:text-white font-bold'
-                      : 'border-transparent text-gray-600 dark:text-gray-300 hover:border-primary-300 dark:hover:border-primary-400 hover:text-gray-900 dark:hover:text-white'
-                  )}
-                >
-                  {item.title}
-                </Link>
-              </li>
-            ))}
-          </ul>
-        </div>
-      ))}
+      <div className={compact ? 'space-y-4' : 'space-y-6'}>
+        {nav.map((section) => {
+          // Determine if this section should be collapsible
+          const shouldCollapse = collapsible && section.items.length > collapseThreshold
+          // Check if current path is in this section
+          const isActive = section.items.some(
+            (item) => currentPath === item.href || currentPath + '/' === item.href
+          )
+
+          if (shouldCollapse) {
+            return (
+              <CollapsibleSection
+                key={section.title}
+                section={section}
+                currentPath={currentPath}
+                defaultExpanded={isActive}
+                compact={compact}
+              />
+            )
+          }
+
+          return (
+            <StaticSection
+              key={section.title}
+              section={section}
+              currentPath={currentPath}
+              compact={compact}
+            />
+          )
+        })}
       </div>
     </nav>
   )

package/src/components/TableOfContents.tsx

@@ -169,7 +169,7 @@ export function TableOfContents({ items, className = '', ...props }: TableOfCont
                     : 'border-transparent text-gray-600 dark:text-gray-300 hover:border-primary-300 dark:hover:border-primary-400 hover:text-gray-900 dark:hover:text-white'
                 }`}
               >
-                {item.text}
+                {item.text || item.title}
               </a>
             </li>
           )