@geenius/docs 0.1.0

package/packages/react/src/components/EditButton.tsx

@@ -0,0 +1,26 @@
+import React from 'react'
+
+interface EditButtonProps {
+  pageSlug: string
+  editUrl?: string
+}
+
+export function EditButton({ pageSlug, editUrl }: EditButtonProps) {
+  if (!editUrl) return null
+
+  const href = `${editUrl.replace(/\/$/, '')}/${pageSlug}.mdx`
+
+  return (
+    <a
+      href={href}
+      target="_blank"
+      rel="noopener noreferrer"
+      className="inline-flex items-center gap-1.5 rounded-lg border border-white/10 px-3 py-1.5 text-xs text-white/40 transition-colors hover:border-white/20 hover:text-white/60"
+    >
+      <svg className="h-3.5 w-3.5" viewBox="0 0 16 16" fill="none" stroke="currentColor">
+        <path d="M11.5 1.5l3 3-9 9H2.5v-3l9-9z" strokeWidth="1.5" strokeLinejoin="round" />
+      </svg>
+      Edit this page
+    </a>
+  )
+}

package/packages/react/src/components/PageNavigation.tsx

@@ -0,0 +1,45 @@
+import React from 'react'
+
+interface PageNavigationProps {
+  prev?: { title: string; href: string }
+  next?: { title: string; href: string }
+}
+
+export function PageNavigation({ prev, next }: PageNavigationProps) {
+  if (!prev && !next) return null
+
+  return (
+    <div className="mt-12 flex items-stretch gap-4 border-t border-white/10 pt-8">
+      {prev ? (
+        <a
+          href={prev.href}
+          className="group flex flex-1 flex-col rounded-xl border border-white/10 p-4 transition-all hover:border-indigo-500/40 hover:bg-white/5"
+        >
+          <span className="text-xs text-white/40 group-hover:text-indigo-400 transition-colors">
+            ← Previous
+          </span>
+          <span className="mt-1 text-sm font-medium text-white/80 group-hover:text-white transition-colors truncate">
+            {prev.title}
+          </span>
+        </a>
+      ) : (
+        <div className="flex-1" />
+      )}
+      {next ? (
+        <a
+          href={next.href}
+          className="group flex flex-1 flex-col items-end rounded-xl border border-white/10 p-4 text-right transition-all hover:border-indigo-500/40 hover:bg-white/5"
+        >
+          <span className="text-xs text-white/40 group-hover:text-indigo-400 transition-colors">
+            Next →
+          </span>
+          <span className="mt-1 text-sm font-medium text-white/80 group-hover:text-white transition-colors truncate">
+            {next.title}
+          </span>
+        </a>
+      ) : (
+        <div className="flex-1" />
+      )}
+    </div>
+  )
+}

package/packages/react/src/components/TableOfContents.tsx

@@ -0,0 +1,46 @@
+import React from 'react'
+import type { TocItem } from '@geenius-docs/shared'
+
+interface TableOfContentsProps {
+  toc: TocItem[]
+  activeId?: string
+}
+
+function TocLink({ item, activeId, depth = 0 }: { item: TocItem; activeId?: string; depth?: number }) {
+  const isActive = activeId === item.id
+  return (
+    <>
+      <a
+        href={`#${item.id}`}
+        className={`block truncate border-l-2 py-1 text-[13px] transition-all duration-200 ${
+          isActive
+            ? 'border-indigo-500 text-indigo-300 font-medium'
+            : 'border-transparent text-white/40 hover:text-white/70 hover:border-white/20'
+        }`}
+        style={{ paddingLeft: 12 + depth * 12 }}
+      >
+        {item.text}
+      </a>
+      {item.children.map((child) => (
+        <TocLink key={child.id} item={child} activeId={activeId} depth={depth + 1} />
+      ))}
+    </>
+  )
+}
+
+export function TableOfContents({ toc, activeId }: TableOfContentsProps) {
+  if (toc.length === 0) return null
+
+  return (
+    <nav className="sticky top-24">
+      <h4 className="mb-3 text-xs font-semibold uppercase tracking-widest text-white/40">
+        On this page
+      </h4>
+      <div className="flex flex-col">
+        {toc.map((item) => (
+          <TocLink key={item.id} item={item} activeId={activeId} />
+        ))}
+      </div>
+    </nav>
+  )
+}

package/packages/react/src/components/VersionSelector.tsx

@@ -0,0 +1,60 @@
+import React, { useState, useRef, useEffect } from 'react'
+
+interface VersionSelectorProps {
+  versions: string[]
+  current: string
+  onSelect: (version: string) => void
+}
+
+export function VersionSelector({ versions, current, onSelect }: VersionSelectorProps) {
+  const [isOpen, setIsOpen] = useState(false)
+  const ref = useRef<HTMLDivElement>(null)
+
+  useEffect(() => {
+    const handleClickOutside = (e: MouseEvent) => {
+      if (ref.current && !ref.current.contains(e.target as Node)) setIsOpen(false)
+    }
+    document.addEventListener('mousedown', handleClickOutside)
+    return () => document.removeEventListener('mousedown', handleClickOutside)
+  }, [])
+
+  if (versions.length <= 1) return null
+
+  return (
+    <div ref={ref} className="relative">
+      <button
+        type="button"
+        onClick={() => setIsOpen(!isOpen)}
+        className="flex items-center gap-1.5 rounded-lg border border-white/10 bg-white/5 px-3 py-1.5 text-xs font-medium text-white/60 transition-colors hover:border-indigo-500/30 hover:text-white/80"
+      >
+        <span>v{current}</span>
+        <svg className={`h-3 w-3 transition-transform ${isOpen ? 'rotate-180' : ''}`} viewBox="0 0 16 16" fill="currentColor">
+          <path d="M4 6l4 4 4-4" stroke="currentColor" strokeWidth="2" fill="none" />
+        </svg>
+      </button>
+
+      {isOpen && (
+        <div className="absolute right-0 top-full z-20 mt-1 min-w-[120px] overflow-hidden rounded-lg border border-white/10 bg-[#111218] shadow-xl">
+          {versions.map((v) => (
+            <button
+              key={v}
+              type="button"
+              onClick={() => {
+                onSelect(v)
+                setIsOpen(false)
+              }}
+              className={`flex w-full items-center px-3 py-2 text-xs transition-colors ${
+                v === current
+                  ? 'bg-indigo-500/15 text-indigo-300 font-medium'
+                  : 'text-white/60 hover:bg-white/5 hover:text-white/80'
+              }`}
+            >
+              v{v}
+              {v === current && <span className="ml-auto text-[10px]">✓</span>}
+            </button>
+          ))}
+        </div>
+      )}
+    </div>
+  )
+}

package/packages/react/src/components/index.ts

@@ -0,0 +1,9 @@
+export { DocSidebar } from './DocSidebar'
+export { DocPage } from './DocPage'
+export { TableOfContents } from './TableOfContents'
+export { Breadcrumbs } from './Breadcrumbs'
+export { PageNavigation } from './PageNavigation'
+export { DocSearch } from './DocSearch'
+export { VersionSelector } from './VersionSelector'
+export { EditButton } from './EditButton'
+export { DocsLayout } from './DocsLayout'

package/packages/react/src/hooks/index.ts

@@ -0,0 +1,8 @@
+export { useDocs } from './useDocs'
+export type { DocsState } from './useDocs'
+export { useDocSearch } from './useDocSearch'
+export type { DocSearchState } from './useDocSearch'
+export { useDocsAdmin } from './useDocsAdmin'
+export type { DocsAdminActions } from './useDocsAdmin'
+export { useTableOfContents } from './useTableOfContents'
+export type { TableOfContentsState } from './useTableOfContents'

package/packages/react/src/hooks/useDocSearch.ts

@@ -0,0 +1,55 @@
+import { useState, useEffect, useCallback, useRef } from 'react'
+import type { SearchResult } from '@geenius-docs/shared'
+
+export interface DocSearchState {
+  results: SearchResult[]
+  isSearching: boolean
+  query: string
+  setQuery: (q: string) => void
+  clearSearch: () => void
+}
+
+export function useDocSearch(
+  searchFn: (query: string) => SearchResult[] | Promise<SearchResult[]>,
+  debounceMs = 250
+): DocSearchState {
+  const [query, setQuery] = useState('')
+  const [results, setResults] = useState<SearchResult[]>([])
+  const [isSearching, setIsSearching] = useState(false)
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+
+  useEffect(() => {
+    if (!query.trim()) {
+      setResults([])
+      setIsSearching(false)
+      return
+    }
+
+    setIsSearching(true)
+
+    if (timerRef.current) clearTimeout(timerRef.current)
+
+    timerRef.current = setTimeout(async () => {
+      try {
+        const r = await searchFn(query)
+        setResults(r)
+      } catch {
+        setResults([])
+      } finally {
+        setIsSearching(false)
+      }
+    }, debounceMs)
+
+    return () => {
+      if (timerRef.current) clearTimeout(timerRef.current)
+    }
+  }, [query, searchFn, debounceMs])
+
+  const clearSearch = useCallback(() => {
+    setQuery('')
+    setResults([])
+    setIsSearching(false)
+  }, [])
+
+  return { results, isSearching, query, setQuery, clearSearch }
+}

package/packages/react/src/hooks/useDocs.ts

@@ -0,0 +1,57 @@
+import { useState, useMemo, useCallback } from 'react'
+import type { DocPage, DocSection, DocsConfig } from '@geenius-docs/shared'
+import { defaultDocsConfig } from '@geenius-docs/shared'
+
+export interface DocsState {
+  sections: (DocSection & { pages: DocPage[]; pageCount: number })[]
+  currentSection: DocSection | null
+  setSection: (section: DocSection | null) => void
+  currentPage: DocPage | null
+  setPage: (page: DocPage | null) => void
+  searchQuery: string
+  setSearchQuery: (query: string) => void
+  isLoading: boolean
+  config: DocsConfig
+  flatPages: DocPage[]
+}
+
+export function useDocs(
+  tree: (DocSection & { pages: DocPage[]; pageCount: number })[] | undefined,
+  config?: Partial<DocsConfig>
+): DocsState {
+  const [currentSection, setSection] = useState<DocSection | null>(null)
+  const [currentPage, setPage] = useState<DocPage | null>(null)
+  const [searchQuery, setSearchQuery] = useState('')
+
+  const mergedConfig = useMemo(
+    () => ({ ...defaultDocsConfig, ...config }),
+    [config]
+  )
+
+  const sections = useMemo(() => tree ?? [], [tree])
+
+  const flatPages = useMemo(
+    () => sections.flatMap((s) => s.pages ?? []),
+    [sections]
+  )
+
+  const isLoading = tree === undefined
+
+  const handleSetSection = useCallback((section: DocSection | null) => {
+    setSection(section)
+    setPage(null)
+  }, [])
+
+  return {
+    sections,
+    currentSection,
+    setSection: handleSetSection,
+    currentPage,
+    setPage,
+    searchQuery,
+    setSearchQuery,
+    isLoading,
+    config: mergedConfig,
+    flatPages,
+  }
+}

package/packages/react/src/hooks/useDocsAdmin.ts

@@ -0,0 +1,151 @@
+import { useCallback } from 'react'
+
+export interface DocsAdminActions {
+  createSection: (data: {
+    title: string
+    slug: string
+    parentId?: string
+    order: number
+    icon?: string
+    description?: string
+    access: 'public' | 'team' | 'admin'
+  }) => Promise<void>
+  updateSection: (
+    sectionId: string,
+    data: Record<string, unknown>
+  ) => Promise<void>
+  deleteSection: (sectionId: string) => Promise<void>
+  reorderSections: (sectionIds: string[]) => Promise<void>
+  createPage: (data: {
+    title: string
+    slug: string
+    content: string
+    sectionId: string
+    access: 'public' | 'team' | 'admin'
+    tags?: string[]
+    version?: string
+    status?: 'draft' | 'published' | 'archived'
+    author?: { name: string; avatar?: string }
+    excerpt?: string
+    order?: number
+  }) => Promise<void>
+  updatePage: (pageId: string, data: Record<string, unknown>) => Promise<void>
+  publishPage: (pageId: string) => Promise<void>
+  archivePage: (pageId: string) => Promise<void>
+  deletePage: (pageId: string) => Promise<void>
+  reorderPages: (pageIds: string[]) => Promise<void>
+  movePage: (
+    pageId: string,
+    newSectionId: string,
+    newOrder: number
+  ) => Promise<void>
+}
+
+/**
+ * Admin hook factory — accepts mutation functions (from Convex useMutation or similar)
+ * and returns a stable set of admin action callbacks.
+ */
+export function useDocsAdmin(mutations: {
+  createSection: (args: Record<string, unknown>) => Promise<unknown>
+  updateSection: (args: Record<string, unknown>) => Promise<unknown>
+  deleteSection: (args: Record<string, unknown>) => Promise<unknown>
+  reorderSections: (args: Record<string, unknown>) => Promise<unknown>
+  createPage: (args: Record<string, unknown>) => Promise<unknown>
+  updatePage: (args: Record<string, unknown>) => Promise<unknown>
+  publishPage: (args: Record<string, unknown>) => Promise<unknown>
+  archivePage: (args: Record<string, unknown>) => Promise<unknown>
+  deletePage: (args: Record<string, unknown>) => Promise<unknown>
+  reorderPages: (args: Record<string, unknown>) => Promise<unknown>
+  movePage: (args: Record<string, unknown>) => Promise<unknown>
+}): DocsAdminActions {
+  const createSection = useCallback(
+    async (data: Parameters<DocsAdminActions['createSection']>[0]) => {
+      await mutations.createSection(data)
+    },
+    [mutations]
+  )
+
+  const updateSection = useCallback(
+    async (sectionId: string, data: Record<string, unknown>) => {
+      await mutations.updateSection({ sectionId, ...data })
+    },
+    [mutations]
+  )
+
+  const deleteSection = useCallback(
+    async (sectionId: string) => {
+      await mutations.deleteSection({ sectionId })
+    },
+    [mutations]
+  )
+
+  const reorderSections = useCallback(
+    async (sectionIds: string[]) => {
+      await mutations.reorderSections({ sectionIds })
+    },
+    [mutations]
+  )
+
+  const createPage = useCallback(
+    async (data: Parameters<DocsAdminActions['createPage']>[0]) => {
+      await mutations.createPage(data)
+    },
+    [mutations]
+  )
+
+  const updatePage = useCallback(
+    async (pageId: string, data: Record<string, unknown>) => {
+      await mutations.updatePage({ pageId, ...data })
+    },
+    [mutations]
+  )
+
+  const publishPage = useCallback(
+    async (pageId: string) => {
+      await mutations.publishPage({ pageId })
+    },
+    [mutations]
+  )
+
+  const archivePage = useCallback(
+    async (pageId: string) => {
+      await mutations.archivePage({ pageId })
+    },
+    [mutations]
+  )
+
+  const deletePage = useCallback(
+    async (pageId: string) => {
+      await mutations.deletePage({ pageId })
+    },
+    [mutations]
+  )
+
+  const reorderPages = useCallback(
+    async (pageIds: string[]) => {
+      await mutations.reorderPages({ pageIds })
+    },
+    [mutations]
+  )
+
+  const movePage = useCallback(
+    async (pageId: string, newSectionId: string, newOrder: number) => {
+      await mutations.movePage({ pageId, newSectionId, newOrder })
+    },
+    [mutations]
+  )
+
+  return {
+    createSection,
+    updateSection,
+    deleteSection,
+    reorderSections,
+    createPage,
+    updatePage,
+    publishPage,
+    archivePage,
+    deletePage,
+    reorderPages,
+    movePage,
+  }
+}

package/packages/react/src/hooks/useTableOfContents.ts

@@ -0,0 +1,66 @@
+import { useState, useEffect, useMemo, useRef, useCallback } from 'react'
+import type { TocItem } from '@geenius-docs/shared'
+import { extractToc } from '@geenius-docs/shared'
+
+export interface TableOfContentsState {
+  toc: TocItem[]
+  activeId: string
+  setActiveId: (id: string) => void
+}
+
+export function useTableOfContents(mdxContent: string | undefined): TableOfContentsState {
+  const [activeId, setActiveId] = useState('')
+  const observerRef = useRef<IntersectionObserver | null>(null)
+
+  const toc = useMemo(() => {
+    if (!mdxContent) return []
+    return extractToc(mdxContent)
+  }, [mdxContent])
+
+  const flatIds = useMemo(() => {
+    const ids: string[] = []
+    const collect = (items: TocItem[]) => {
+      for (const item of items) {
+        ids.push(item.id)
+        collect(item.children)
+      }
+    }
+    collect(toc)
+    return ids
+  }, [toc])
+
+  const handleSetActiveId = useCallback((id: string) => {
+    setActiveId(id)
+  }, [])
+
+  useEffect(() => {
+    if (flatIds.length === 0) return
+
+    if (observerRef.current) observerRef.current.disconnect()
+
+    const callback: IntersectionObserverCallback = (entries) => {
+      for (const entry of entries) {
+        if (entry.isIntersecting) {
+          setActiveId(entry.target.id)
+          break
+        }
+      }
+    }
+
+    observerRef.current = new IntersectionObserver(callback, {
+      rootMargin: '-80px 0px -70% 0px',
+      threshold: 0,
+    })
+
+    for (const id of flatIds) {
+      const el = document.getElementById(id)
+      if (el) observerRef.current.observe(el)
+    }
+
+    return () => {
+      observerRef.current?.disconnect()
+    }
+  }, [flatIds])
+
+  return { toc, activeId, setActiveId: handleSetActiveId }
+}

package/packages/react/src/index.ts

@@ -0,0 +1,38 @@
+// Hooks
+export { useDocs } from './hooks/useDocs'
+export type { DocsState } from './hooks/useDocs'
+export { useDocSearch } from './hooks/useDocSearch'
+export type { DocSearchState } from './hooks/useDocSearch'
+export { useDocsAdmin } from './hooks/useDocsAdmin'
+export type { DocsAdminActions } from './hooks/useDocsAdmin'
+export { useTableOfContents } from './hooks/useTableOfContents'
+export type { TableOfContentsState } from './hooks/useTableOfContents'
+
+// Components
+export { DocSidebar } from './components/DocSidebar'
+export { DocPage } from './components/DocPage'
+export { TableOfContents } from './components/TableOfContents'
+export { Breadcrumbs } from './components/Breadcrumbs'
+export { PageNavigation } from './components/PageNavigation'
+export { DocSearch } from './components/DocSearch'
+export { VersionSelector } from './components/VersionSelector'
+export { EditButton } from './components/EditButton'
+export { DocsLayout } from './components/DocsLayout'
+
+// Pages
+export { DocsIndexPage } from './pages/DocsIndexPage'
+export { DocViewPage } from './pages/DocViewPage'
+export { DocSearchPage } from './pages/DocSearchPage'
+export { DocsAdminPage } from './pages/DocsAdminPage'
+
+// Re-export shared types
+export type {
+  DocPage as DocPageType,
+  DocSection,
+  SearchResult,
+  TocItem,
+  BreadcrumbItem,
+  DocsConfig,
+  DocAccess,
+  DocStatus,
+} from '@geenius-docs/shared'