@geenius/docs 0.1.0 → 0.4.0

package/packages/react/dist/index.d.ts

@@ -0,0 +1,439 @@
+import { BreadcrumbItem, DocPage as DocPage$1, SearchResult, DocSection, TocItem, DocsConfig } from '@geenius/docs-shared';
+export { BreadcrumbItem, DocAccess, DocPage as DocPageType, DocSection, DocStatus, DocsConfig, SearchResult, TocItem } from '@geenius/docs-shared';
+import React$1 from 'react';
+
+/**
+ * @module reactBreadcrumbs
+ * @package @geenius/docs-react
+ * @description Renders breadcrumb navigation for the React docs variant using
+ * the shared docs route metadata and Tailwind styling contract.
+ */
+
+interface BreadcrumbsProps {
+    items: BreadcrumbItem[];
+}
+/**
+ * Renders the current docs breadcrumb trail.
+ *
+ * @param props - Breadcrumb items describing the current page ancestry.
+ * @returns Breadcrumb navigation or `null` when there are no items to show.
+ */
+declare function Breadcrumbs({ items, }: BreadcrumbsProps): React$1.JSX.Element | null;
+
+/**
+ * @module reactDocPage
+ * @package @geenius/docs-react
+ * @description Renders a docs page body with safe Markdown semantics, heading
+ * anchors, and package-consistent typography. The component deliberately avoids
+ * raw HTML injection so authored docs content stays within the Markdown runtime.
+ */
+
+interface DocPageProps {
+    page: DocPage$1;
+}
+/**
+ * Renders a docs page body using safe Markdown rendering.
+ *
+ * @param props - Docs page record containing the Markdown body to render.
+ * @returns The rendered page article.
+ */
+declare function DocPage(props: DocPageProps): React$1.JSX.Element;
+
+/**
+ * @module reactDocSearch
+ * @package @geenius/docs-react
+ * @description Provides the React command-palette style docs search modal with
+ * animated presentation, keyboard navigation, and result highlighting.
+ */
+
+interface DocSearchProps {
+    results: SearchResult[];
+    query: string;
+    onQuery: (q: string) => void;
+    onSelect: (result: SearchResult) => void;
+    isOpen: boolean;
+    onClose: () => void;
+}
+/**
+ * Renders the modal search surface for the React docs variant.
+ *
+ * @param props - Search results, query state, and modal interaction handlers.
+ * @returns Search dialog markup when open, otherwise `null`.
+ */
+declare function DocSearch({ results, query, onQuery, onSelect, isOpen, onClose, }: DocSearchProps): React$1.JSX.Element | null;
+
+/**
+ * @module reactDocSidebar
+ * @package @geenius/docs-react
+ * @description Renders the hierarchical sidebar navigation used by the React
+ * docs variant, including animated section expansion and active page states.
+ */
+
+interface DocSidebarProps {
+    sections: (DocSection & {
+        pages?: DocPage$1[];
+        pageCount?: number;
+    })[];
+    currentPageId?: string;
+    onNavigate: (page: DocPage$1, section: DocSection) => void;
+}
+/**
+ * Sidebar navigation for docs sections and pages.
+ *
+ * @param props - Section tree, active page id, and page navigation callback.
+ * @returns Sidebar markup for the React docs experience.
+ */
+declare function DocSidebar({ sections, currentPageId, onNavigate, }: DocSidebarProps): React.JSX.Element;
+
+/**
+ * @module reactDocsLayout
+ * @package @geenius/docs-react
+ * @description Composes the React docs page shell with sidebar navigation,
+ * breadcrumb chrome, animated content transitions, and the right-rail TOC.
+ */
+
+interface DocsLayoutProps {
+    sections: (DocSection & {
+        pages?: DocPage$1[];
+    })[];
+    currentPage?: DocPage$1;
+    toc?: TocItem[];
+    activeHeadingId?: string;
+    breadcrumbs?: BreadcrumbItem[];
+    currentPageId?: string;
+    onNavigate: (page: DocPage$1, section: DocSection) => void;
+    children: React$1.ReactNode;
+}
+/**
+ * Layout shell shared by React docs pages.
+ *
+ * @param props - Navigation state, table-of-contents state, and page content.
+ * @returns Full page layout for React docs screens.
+ */
+declare function DocsLayout({ sections, toc, activeHeadingId, breadcrumbs, currentPageId, onNavigate, children, }: DocsLayoutProps): React$1.JSX.Element;
+
+/**
+ * @module reactEditButton
+ * @package @geenius/docs-react
+ * @description Exposes the React docs "Edit this page" affordance so hosts can
+ * route readers to the source repository for the active document.
+ */
+interface EditButtonProps {
+    pageSlug: string;
+    editUrl?: string;
+}
+/**
+ * Renders the source-edit link for the current docs page.
+ *
+ * @param props - Page slug and optional edit URL base.
+ * @returns Edit link markup or `null` when editing is disabled.
+ */
+declare function EditButton({ pageSlug, editUrl, }: EditButtonProps): React.JSX.Element | null;
+
+/**
+ * @module reactPageNavigation
+ * @package @geenius/docs-react
+ * @description Renders previous and next article affordances for the React
+ * docs variant using the shared page navigation contract.
+ */
+interface PageNavigationProps {
+    prev?: {
+        title: string;
+        href: string;
+    };
+    next?: {
+        title: string;
+        href: string;
+    };
+}
+/**
+ * Renders previous and next page links for the active article.
+ *
+ * @param props - Optional previous and next navigation links.
+ * @returns Navigation markup or `null` when no links are available.
+ */
+declare function PageNavigation({ prev, next, }: PageNavigationProps): React.JSX.Element | null;
+
+/**
+ * @module reactTableOfContents
+ * @package @geenius/docs-react
+ * @description Renders the React docs table of contents with animated active
+ * heading states and nested anchor links derived from the shared TOC model.
+ */
+
+interface TableOfContentsProps {
+    toc: TocItem[];
+    activeId?: string;
+}
+/**
+ * Renders the page table of contents.
+ *
+ * @param props - TOC entries and the currently active heading id.
+ * @returns TOC navigation or `null` when the page has no headings.
+ */
+declare function TableOfContents({ toc, activeId, }: TableOfContentsProps): React.JSX.Element | null;
+
+/**
+ * @module reactVersionSelector
+ * @package @geenius/docs-react
+ * @description Provides the React docs version switcher with a disclosure menu
+ * for choosing among published documentation versions.
+ */
+interface VersionSelectorProps {
+    versions: string[];
+    current: string;
+    onSelect: (version: string) => void;
+}
+/**
+ * Renders a version switcher when multiple docs versions exist.
+ *
+ * @param props - Supported versions, the current version, and selection callback.
+ * @returns Version selector markup or `null` when only one version exists.
+ */
+declare function VersionSelector({ versions, current, onSelect, }: VersionSelectorProps): React.JSX.Element | null;
+
+/**
+ * @module reactUseDocSearch
+ * @package @geenius/docs-react
+ * @description Implements debounced search state for the React docs variant so
+ * modal and page-level search flows share a common query lifecycle.
+ */
+
+/**
+ * Search state returned by the React docs search hook.
+ */
+interface DocSearchState {
+    results: SearchResult[];
+    isSearching: boolean;
+    query: string;
+    setQuery: (q: string) => void;
+    clearSearch: () => void;
+}
+/**
+ * Debounces docs search calls for the React variant.
+ *
+ * @param searchFn - Search function that returns ranked docs results.
+ * @param debounceMs - Delay before the search function is executed.
+ * @returns Search state and control helpers.
+ */
+declare function useDocSearch(searchFn: (query: string) => SearchResult[] | Promise<SearchResult[]>, debounceMs?: number): DocSearchState;
+
+/**
+ * @module reactUseDocs
+ * @package @geenius/docs-react
+ * @description Provides the core React docs state container that normalizes
+ * section trees, current page selection, search state, and merged config.
+ */
+
+/**
+ * Aggregate docs state exposed to React pages and components.
+ */
+interface DocsState {
+    sections: (DocSection & {
+        pages: DocPage$1[];
+        pageCount: number;
+    })[];
+    currentSection: DocSection | null;
+    setSection: (section: DocSection | null) => void;
+    currentPage: DocPage$1 | null;
+    setPage: (page: DocPage$1 | null) => void;
+    searchQuery: string;
+    setSearchQuery: (query: string) => void;
+    isLoading: boolean;
+    config: DocsConfig;
+    flatPages: DocPage$1[];
+}
+/**
+ * Creates normalized docs state for React pages and components.
+ *
+ * @param tree - Docs section tree with eagerly attached pages.
+ * @param config - Optional config overrides merged onto the shared defaults.
+ * @returns Normalized docs state for the React docs surface.
+ */
+declare function useDocs(tree: (DocSection & {
+    pages: DocPage$1[];
+    pageCount: number;
+})[] | undefined, config?: Partial<DocsConfig>): DocsState;
+
+/**
+ * @module reactUseDocsAdmin
+ * @package @geenius/docs-react
+ * @description Wraps docs admin mutations in stable React callbacks so the
+ * admin pages can manage sections and pages without coupling to one backend.
+ */
+/**
+ * Stable admin actions exposed to React docs management surfaces.
+ */
+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.
+ *
+ * @param mutations - Backend mutation functions for docs admin operations.
+ * @returns Stable admin action callbacks for the React docs variant.
+ */
+declare 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;
+
+/**
+ * @module reactUseTableOfContents
+ * @package @geenius/docs-react
+ * @description Tracks the extracted table of contents and active heading state
+ * for rendered React docs pages.
+ */
+
+/**
+ * Table-of-contents state returned by the React docs hook.
+ */
+interface TableOfContentsState {
+    toc: TocItem[];
+    activeId: string;
+    setActiveId: (id: string) => void;
+}
+/**
+ * Extracts and tracks a page table of contents for React article screens.
+ *
+ * @param mdxContent - Markdown or MDX source for the active page.
+ * @returns Extracted TOC entries plus the active heading id.
+ */
+declare function useTableOfContents(mdxContent: string | undefined): TableOfContentsState;
+
+/**
+ * @module reactDocSearchPage
+ * @package @geenius/docs-react
+ * @description Renders the dedicated React docs search page with a full-page
+ * query input, ranked search results, and empty-state messaging.
+ */
+
+interface DocSearchPageProps {
+    tree: (DocSection & {
+        pages: DocPage$1[];
+        pageCount: number;
+    })[] | undefined;
+    onSelectPage?: (page: DocPage$1, section: DocSection) => void;
+}
+/**
+ * Dedicated search page for the React docs variant.
+ *
+ * @param props - Docs tree and optional page selection handler.
+ * @returns Search page UI or a loading state when the tree is unresolved.
+ */
+declare function DocSearchPage({ tree, onSelectPage, }: DocSearchPageProps): React.JSX.Element;
+
+/**
+ * @module reactDocsAdminPage
+ * @package @geenius/docs-react
+ * @description Renders the React docs admin surface for creating, updating,
+ * publishing, and deleting docs sections and pages.
+ */
+
+interface DocsAdminPageProps {
+    tree: (DocSection & {
+        pages: DocPage$1[];
+        pageCount: number;
+    })[] | undefined;
+    allPages?: DocPage$1[];
+    admin: DocsAdminActions;
+}
+/**
+ * Admin page for section and page management in the React docs variant.
+ *
+ * @param props - Tree data, optional page list, and admin actions.
+ * @returns Admin UI for managing docs content.
+ */
+declare function DocsAdminPage({ tree, allPages, admin, }: DocsAdminPageProps): React.JSX.Element;
+
+/**
+ * @module reactDocsIndexPage
+ * @package @geenius/docs-react
+ * @description Renders the React docs landing page with section discovery,
+ * recent updates, and command-palette search entry points.
+ */
+
+interface DocsIndexPageProps {
+    tree: (DocSection & {
+        pages: DocPage$1[];
+        pageCount: number;
+    })[] | undefined;
+    onSelectPage?: (page: DocPage$1, section: DocSection) => void;
+}
+/**
+ * Landing page for the React docs experience.
+ *
+ * @param props - Docs tree plus optional page selection handler.
+ * @returns Landing page UI for the React docs variant.
+ */
+declare function DocsIndexPage({ tree, onSelectPage, }: DocsIndexPageProps): React.JSX.Element;
+
+/**
+ * @module reactDocViewPage
+ * @package @geenius/docs-react
+ * @description Renders the primary React docs article page with layout chrome,
+ * metadata, TOC tracking, edit actions, and previous or next navigation.
+ */
+
+interface DocViewPageProps {
+    tree: (DocSection & {
+        pages: DocPage$1[];
+        pageCount: number;
+    })[] | undefined;
+    page: DocPage$1 | null | undefined;
+    editPageUrl?: string;
+    onNavigate: (page: DocPage$1, section: DocSection) => void;
+    onIncrementView?: (pageId: string) => void;
+}
+/**
+ * Detailed article page for the React docs variant.
+ *
+ * @param props - Docs tree, active page, and page-level interaction handlers.
+ * @returns Detailed page view or an appropriate loading or empty state.
+ */
+declare function DocViewPage({ tree, page, editPageUrl, onNavigate, onIncrementView, }: DocViewPageProps): React.JSX.Element;
+
+export { Breadcrumbs, DocPage, DocSearch, DocSearchPage, type DocSearchState, DocSidebar, DocViewPage, type DocsAdminActions, DocsAdminPage, DocsIndexPage, DocsLayout, type DocsState, EditButton, PageNavigation, TableOfContents, type TableOfContentsState, VersionSelector, useDocSearch, useDocs, useDocsAdmin, useTableOfContents };