@geenius/docs 0.1.0 → 0.4.1

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

@@ -0,0 +1,684 @@
+import { GeeniusError, GeeniusErrorOptions, ErrorCode } from '@geenius/tools/errors';
+
+/**
+ * @module docsTypes
+ * @package @geenius/docs-shared
+ * @description Declares the shared docs domain model used by the framework
+ * variants, Convex integration, and provider adapters. These types form the
+ * public contract exported from `@geenius/docs`.
+ */
+/**
+ * Access levels supported by docs content.
+ */
+type DocAccess = 'public' | 'team' | 'admin';
+/**
+ * Publishing states supported by docs pages.
+ */
+type DocStatus = 'draft' | 'published' | 'archived';
+/**
+ * Author metadata attached to a docs page.
+ *
+ * @property name - Human-readable author display name.
+ * @property avatar - Optional avatar URL for UI surfaces that show authorship.
+ */
+interface DocAuthor {
+    name: string;
+    avatar?: string;
+}
+/**
+ * Last-editor metadata attached to a docs page revision.
+ *
+ * @property name - Human-readable editor display name.
+ * @property editedAt - ISO timestamp describing the edit event.
+ */
+interface DocRevision {
+    name: string;
+    editedAt: string;
+}
+/**
+ * Minimal navigation link used for previous and next page affordances.
+ *
+ * @property title - Label shown in the navigation UI.
+ * @property slug - Page slug used to resolve the target.
+ */
+interface DocNavigationLink {
+    title: string;
+    slug: string;
+}
+/**
+ * Core page record shared across all docs variants.
+ *
+ * @property id - Stable page identifier.
+ * @property title - Human-readable page title.
+ * @property slug - Route slug relative to the docs base path.
+ * @property content - Markdown or MDX body content.
+ * @property excerpt - Optional preview excerpt used by search and listings.
+ * @property sectionId - Stable section identifier used for grouping.
+ * @property order - Sort order inside the containing section.
+ * @property author - Primary author metadata for the page.
+ * @property lastEditedBy - Optional revision metadata for the last editor.
+ * @property version - Optional semantic version label for versioned docs.
+ * @property access - Access control level for the page.
+ * @property tags - Searchable tags attached to the page.
+ * @property status - Publishing status for the page.
+ * @property createdAt - ISO timestamp describing when the page was created.
+ * @property updatedAt - ISO timestamp describing the most recent update.
+ * @property wordCount - Approximate rendered word count.
+ * @property readingTime - Reading time in minutes.
+ * @property viewCount - Recorded page view count.
+ */
+interface DocPage {
+    id: string;
+    title: string;
+    slug: string;
+    content: string;
+    excerpt?: string;
+    sectionId: string;
+    order: number;
+    author: DocAuthor;
+    lastEditedBy?: DocRevision;
+    version?: string;
+    access: DocAccess;
+    tags: string[];
+    status: DocStatus;
+    createdAt: string;
+    updatedAt: string;
+    wordCount: number;
+    readingTime: number;
+    viewCount: number;
+}
+/**
+ * Section record used by listings, navigation trees, and admin tooling.
+ *
+ * @property id - Stable section identifier.
+ * @property title - Human-readable section title.
+ * @property slug - Route slug for the section landing page.
+ * @property parentId - Optional parent section identifier for nested trees.
+ * @property order - Sort order among sibling sections.
+ * @property icon - Optional decorative icon token or emoji.
+ * @property description - Optional descriptive copy used in dashboards and cards.
+ * @property access - Access control level inherited by the section.
+ * @property pageCount - Optional precomputed number of pages in the section.
+ */
+interface DocSection {
+    id: string;
+    title: string;
+    slug: string;
+    parentId?: string;
+    order: number;
+    icon?: string;
+    description?: string;
+    access: DocAccess;
+    pageCount?: number;
+}
+/**
+ * Search result returned by the shared search helpers.
+ *
+ * @property pageId - Stable page identifier.
+ * @property pageTitle - Human-readable page title.
+ * @property sectionTitle - Human-readable section title.
+ * @property sectionSlug - Route slug for the containing section.
+ * @property slug - Route slug for the page.
+ * @property highlight - Excerpt or match snippet shown in results.
+ * @property score - Rank score used to sort results.
+ * @property tags - Searchable tags attached to the matching page.
+ */
+interface SearchResult {
+    pageId: string;
+    pageTitle: string;
+    sectionTitle: string;
+    sectionSlug: string;
+    slug: string;
+    highlight: string;
+    score: number;
+    tags: string[];
+}
+/**
+ * Table-of-contents node extracted from a page body.
+ *
+ * @property id - Heading anchor identifier.
+ * @property text - Visible heading label.
+ * @property level - Heading depth supported by the docs renderer.
+ * @property children - Nested headings beneath this item.
+ */
+interface TocItem {
+    id: string;
+    text: string;
+    level: 2 | 3 | 4;
+    children: TocItem[];
+}
+/**
+ * Breadcrumb node used by page-level navigation chrome.
+ *
+ * @property title - Visible breadcrumb label.
+ * @property href - Target route for the breadcrumb item.
+ */
+interface BreadcrumbItem {
+    title: string;
+    href: string;
+}
+/**
+ * Shared configuration options consumed by the docs variants.
+ *
+ * @property siteName - Optional site label for layouts and metadata.
+ * @property baseUrl - Optional docs base path.
+ * @property defaultAccess - Default access level for new content.
+ * @property versionsEnabled - Enables version selection UI when true.
+ * @property cmdKEnabled - Enables keyboard search affordances when true.
+ * @property editPageUrl - Optional base URL used by "Edit this page" actions.
+ * @property showReadingTime - Controls reading-time metadata visibility.
+ * @property showLastEdited - Controls last-edited metadata visibility.
+ * @property showViewCount - Controls view-count metadata visibility.
+ * @property printModeEnabled - Enables print-focused layout affordances.
+ */
+interface DocsConfig {
+    siteName?: string;
+    baseUrl?: string;
+    defaultAccess?: DocAccess;
+    versionsEnabled?: boolean;
+    cmdKEnabled?: boolean;
+    editPageUrl?: string;
+    showReadingTime?: boolean;
+    showLastEdited?: boolean;
+    showViewCount?: boolean;
+    printModeEnabled?: boolean;
+}
+/**
+ * Provider-backed page record with derived navigation and heading data.
+ */
+interface DocsPage extends DocPage {
+    prev?: DocNavigationLink | null;
+    next?: DocNavigationLink | null;
+    toc?: TocItem[];
+    breadcrumbs?: BreadcrumbItem[];
+}
+/**
+ * Page summary entry displayed inside a sidebar section.
+ *
+ * @property slug - Route slug used by the nav item.
+ * @property title - Human-readable nav label.
+ */
+interface DocsSidebarPage {
+    slug: string;
+    title: string;
+}
+/**
+ * Section node displayed by docs navigation components.
+ *
+ * @property id - Stable section identifier.
+ * @property title - Human-readable section label.
+ * @property slug - Route slug for the section.
+ * @property icon - Optional decorative icon token or emoji.
+ * @property pages - Flattened page entries belonging to the section.
+ * @property children - Optional nested section tree beneath this item.
+ */
+interface DocsSidebarItem {
+    id: string;
+    title: string;
+    slug: string;
+    icon?: string;
+    pages: DocsSidebarPage[];
+    children?: DocsSidebarItem[];
+}
+/**
+ * Full sidebar structure returned by docs providers.
+ */
+type DocsSidebar = DocsSidebarItem[];
+/**
+ * Search result returned by provider-backed docs integrations.
+ *
+ * @property pageId - Stable page identifier.
+ * @property pageTitle - Human-readable page title.
+ * @property sectionTitle - Human-readable containing section label.
+ * @property slug - Page route slug.
+ * @property highlight - Preview snippet used in search results.
+ * @property score - Rank score used to sort results.
+ */
+interface DocsSearchResult {
+    pageId: string;
+    pageTitle: string;
+    sectionTitle: string;
+    slug: string;
+    highlight: string;
+    score: number;
+}
+/**
+ * Provider contract implemented by pluggable docs backends such as internal
+ * arrays, Astro content directories, and Fumadocs sources.
+ */
+interface DocsProvider {
+    /**
+     * Load the sidebar navigation structure for the docs source.
+     *
+     * @returns The full sidebar tree for the provider.
+     */
+    getSidebar(): Promise<DocsSidebar>;
+    /**
+     * Resolve a single docs page by slug.
+     *
+     * @param slug - Route slug for the requested page.
+     * @returns The resolved page record or `null` when not found.
+     */
+    getPage(slug: string): Promise<DocsPage | null>;
+    /**
+     * Search the provider-backed content source.
+     *
+     * @param query - User-entered search query.
+     * @returns Ranked provider search results for the query.
+     */
+    search(query: string): Promise<DocsSearchResult[]>;
+}
+
+/**
+ * @module docsConfig
+ * @package @geenius/docs-shared
+ * @description Stores and resolves the shared docs configuration used by every
+ * framework variant. The config is intentionally process-local so applications
+ * can opt into a single docs baseline during bootstrap.
+ */
+
+/**
+ * Initialize the docs system with a configuration.
+ * Call this once at app startup before using any docs features.
+ *
+ * @param config - Configuration overrides applied for the current app runtime.
+ * @returns Nothing. The docs config is stored in module state.
+ *
+ * @example
+ * ```ts
+ * import { configureDocs } from '@geenius/docs-shared'
+ *
+ * configureDocs({
+ *   baseUrl: '/docs',
+ *   siteName: 'My Docs',
+ *   versionsEnabled: true,
+ * })
+ * ```
+ */
+declare function configureDocs(config: DocsConfig): void;
+/**
+ * Get the current docs configuration.
+ * Throws if `configureDocs()` has not been called.
+ *
+ * @returns The active docs configuration for the current runtime.
+ * @throws {DocsConfigurationError} When the docs config has not been initialised.
+ */
+declare function getDocsConfig(): DocsConfig;
+/**
+ * Check if docs have been configured.
+ *
+ * @returns `true` when a config has been registered for the current runtime.
+ */
+declare function isDocsConfigured(): boolean;
+/**
+ * Reset docs configuration (useful for testing).
+ *
+ * @returns Nothing. The stored docs config is cleared.
+ */
+declare function resetDocsConfig(): void;
+/**
+ * Create a fully resolved docs config with defaults.
+ *
+ * @param overrides - Partial config overrides supplied by the caller.
+ * @returns A complete docs config with package defaults applied.
+ */
+declare function defineDocsConfig(overrides: Partial<DocsConfig>): DocsConfig;
+/**
+ * Merge an existing config with partial overrides.
+ *
+ * @param base - Existing base config to extend.
+ * @param overrides - Partial config overrides supplied by the caller.
+ * @returns A merged docs config object.
+ */
+declare function mergeDocsConfig(base: DocsConfig, overrides: Partial<DocsConfig>): DocsConfig;
+
+/**
+ * @module docsErrors
+ * @package @geenius/docs-shared
+ * @description Defines the typed error hierarchy used by the docs package so
+ * configuration, provider, and context failures can be caught and handled without
+ * relying on raw `Error` instances.
+ */
+
+/**
+ * Supported structured error codes for docs-specific failures.
+ */
+type DocsErrorCode = ErrorCode.INVALID_CONFIG | ErrorCode.MISSING_CONFIG | ErrorCode.NOT_FOUND | ErrorCode.INTERNAL_ERROR;
+/**
+ * Structured error options for docs-specific failures.
+ */
+interface DocsErrorOptions extends Omit<GeeniusErrorOptions, 'code'> {
+    code: DocsErrorCode;
+}
+/**
+ * Base structured error for the docs package.
+ *
+ * @param options - Error metadata describing the docs failure.
+ */
+declare class DocsError extends GeeniusError {
+    constructor(options: DocsErrorOptions);
+}
+/**
+ * Error thrown when docs configuration is missing or invalid.
+ *
+ * @param options - Error metadata describing the configuration problem.
+ */
+declare class DocsConfigurationError extends DocsError {
+    constructor(options: Omit<DocsErrorOptions, 'code'> & {
+        code?: ErrorCode.INVALID_CONFIG | ErrorCode.MISSING_CONFIG;
+    });
+}
+/**
+ * Error thrown when a docs provider or provider-backed hook is used incorrectly.
+ *
+ * @param options - Error metadata describing the provider failure.
+ */
+declare class DocsProviderError extends DocsError {
+    constructor(options: Omit<DocsErrorOptions, 'code'> & {
+        code?: ErrorCode.NOT_FOUND | ErrorCode.INTERNAL_ERROR;
+    });
+}
+
+/**
+ * @module astroDocsProvider
+ * @package @geenius/docs-shared
+ * @description Implements the Astro-oriented provider used to normalise Markdown
+ * and MDX files discovered from Astro content collections into the shared docs
+ * contract consumed by the framework variants.
+ */
+
+/**
+ * Normalises Astro Markdown and MDX files into the shared docs contract.
+ */
+declare class AstroDocsProvider implements DocsProvider {
+    private pages;
+    /**
+     * Loads docs from an Astro-style `import.meta.glob()` result.
+     *
+     * @param globResult - Lazy or eager Astro content loaders keyed by path.
+     * @returns Nothing. The provider page set is replaced in memory.
+     */
+    loadFromGlob(globResult: Record<string, (() => Promise<string>) | string>): Promise<void>;
+    /**
+     * Loads docs from already-read file contents.
+     *
+     * @param files - File path and content pairs to normalise.
+     * @returns Nothing. The provider page set is replaced in memory.
+     */
+    loadFromFiles(files: Array<{
+        path: string;
+        content: string;
+    }>): Promise<void>;
+    private parseDoc;
+    private linkPages;
+    /**
+     * Loads the sidebar structure derived from the parsed Astro pages.
+     *
+     * @returns Sidebar navigation entries derived from the published pages.
+     */
+    getSidebar(): Promise<DocsSidebar>;
+    /**
+     * Resolves a linked docs page by slug.
+     *
+     * @param slug - Target page slug.
+     * @returns The linked page or `null` when no page matches the slug.
+     */
+    getPage(slug: string): Promise<DocsPage | null>;
+    /**
+     * Returns all published pages managed by the provider.
+     *
+     * @returns Published pages in their linked navigation order.
+     */
+    getAllPages(): Promise<DocsPage[]>;
+    /**
+     * Searches the parsed Astro page set.
+     *
+     * @param query - User-entered search query.
+     * @returns Ranked search results derived from the published pages.
+     */
+    search(query: string): Promise<DocsSearchResult[]>;
+    /**
+     * Resolves previous and next pages for a slug.
+     *
+     * @param slug - Target page slug.
+     * @returns Linked previous and next page records when available.
+     */
+    getNavigation(slug: string): Promise<{
+        prev: DocsPage | null;
+        next: DocsPage | null;
+    }>;
+}
+
+/**
+ * @module fumadocsProvider
+ * @package @geenius/docs-shared
+ * @description Implements the Fumadocs-backed provider used to normalise
+ * source pages and page-tree metadata from Fumadocs into the shared docs
+ * contract consumed by the framework variants.
+ */
+
+/**
+ * Fumadocs source-page shape accepted by the provider.
+ */
+interface FumadocsSourcePage {
+    slug?: string;
+    slugs?: string[];
+    url?: string;
+    data: {
+        title?: string;
+        description?: string;
+        body?: string;
+        icon?: string;
+        order?: number;
+        toc?: TocItem[];
+        draft?: boolean;
+        status?: DocStatus;
+        access?: DocAccess;
+        author?: string;
+        avatar?: string;
+        tags?: string[] | string;
+        version?: string;
+        lastModified?: string;
+        lastUpdated?: string;
+        [key: string]: unknown;
+    };
+}
+/**
+ * Fumadocs tree-node shape accepted by the provider.
+ */
+interface FumadocsTreeNode {
+    type: 'page' | 'folder' | 'separator';
+    name?: string;
+    slug?: string;
+    icon?: string;
+    children?: FumadocsTreeNode[];
+}
+/**
+ * Fumadocs provider that bridges source pages and trees into the shared docs contract.
+ */
+declare class FumadocsDocsProvider implements DocsProvider {
+    private pages;
+    private tree;
+    /**
+     * Loads pages and an optional page tree from Fumadocs.
+     *
+     * @param pages - Source pages supplied by Fumadocs.
+     * @param tree - Optional source page tree for nested sidebar rendering.
+     * @returns Nothing. The provider page set is replaced in memory.
+     */
+    loadFromSource(pages: FumadocsSourcePage[], tree?: FumadocsTreeNode[]): void;
+    private normalizePage;
+    private linkPages;
+    private treeToSidebar;
+    /**
+     * Loads the sidebar structure derived from the Fumadocs tree or grouped pages.
+     *
+     * @returns Sidebar navigation entries derived from the published pages.
+     */
+    getSidebar(): Promise<DocsSidebar>;
+    /**
+     * Resolves a linked docs page by slug.
+     *
+     * @param slug - Target page slug.
+     * @returns The linked page or `null` when no page matches the slug.
+     */
+    getPage(slug: string): Promise<DocsPage | null>;
+    /**
+     * Returns all published pages managed by the provider.
+     *
+     * @returns Published pages in their linked navigation order.
+     */
+    getAllPages(): Promise<DocsPage[]>;
+    /**
+     * Searches the provider-backed page set.
+     *
+     * @param query - User-entered search query.
+     * @returns Ranked search results derived from the published pages.
+     */
+    search(query: string): Promise<DocsSearchResult[]>;
+    /**
+     * Resolves previous and next pages for a slug.
+     *
+     * @param slug - Target page slug.
+     * @returns Linked previous and next page records when available.
+     */
+    getNavigation(slug: string): Promise<{
+        prev: DocsPage | null;
+        next: DocsPage | null;
+    }>;
+}
+
+/**
+ * @module internalDocsProvider
+ * @package @geenius/docs-shared
+ * @description Implements the in-memory docs provider used by local fixtures,
+ * tests, and apps that already have page records loaded in process memory.
+ */
+
+/**
+ * In-memory provider for already-hydrated docs pages.
+ */
+declare class InternalDocsProvider implements DocsProvider {
+    private pages;
+    /**
+     * @param pages - Optional initial page records to seed the provider with.
+     */
+    constructor(pages?: DocPage[]);
+    /**
+     * Replaces the provider's page set.
+     *
+     * @param pages - Fresh page records to seed into the provider.
+     * @returns Nothing. The provider page set is replaced in memory.
+     */
+    setPages(pages: DocPage[]): void;
+    private linkPages;
+    /**
+     * Loads the sidebar structure derived from the current page set.
+     *
+     * @returns Sidebar navigation entries derived from the published pages.
+     */
+    getSidebar(): Promise<DocsSidebar>;
+    /**
+     * Resolves a linked docs page by slug.
+     *
+     * @param slug - Target page slug.
+     * @returns The linked page or `null` when no page matches the slug.
+     */
+    getPage(slug: string): Promise<DocsPage | null>;
+    /**
+     * Returns all published pages managed by the provider.
+     *
+     * @returns Published pages in their linked navigation order.
+     */
+    getAllPages(): Promise<DocsPage[]>;
+    /**
+     * Searches the provider-backed page set.
+     *
+     * @param query - User-entered search query.
+     * @returns Ranked search results derived from the published pages.
+     */
+    search(query: string): Promise<DocsSearchResult[]>;
+    /**
+     * Resolves previous and next pages for a slug.
+     *
+     * @param slug - Target page slug.
+     * @returns Linked previous and next page records when available.
+     */
+    getNavigation(slug: string): Promise<{
+        prev: DocsPage | null;
+        next: DocsPage | null;
+    }>;
+}
+
+/**
+ * @module docsUtilities
+ * @package @geenius/docs-shared
+ * @description Hosts the framework-agnostic docs helpers used by the shared
+ * barrel and provider implementations for search, slugging, breadcrumbs, table
+ * of contents extraction, and default config resolution.
+ */
+
+/**
+ * Extracts a nested table of contents from Markdown heading lines.
+ *
+ * @param mdxContent - Markdown or MDX content to parse.
+ * @returns A nested heading tree containing only level 2 through 4 headings.
+ */
+declare function extractToc(mdxContent: string): TocItem[];
+/**
+ * Calculates approximate word count and reading time for page content.
+ *
+ * @param content - Markdown or MDX content to measure.
+ * @returns Word count and reading-time metadata derived from the content.
+ */
+declare function calcWordCount(content: string): {
+    wordCount: number;
+    readingTime: number;
+};
+/**
+ * Builds a breadcrumb trail for a page from a section tree.
+ *
+ * @param sections - Full section list used to resolve parent relationships.
+ * @param sectionId - Identifier of the page's containing section.
+ * @param slug - Page slug appended as the terminal breadcrumb.
+ * @returns Breadcrumb items suitable for page-level navigation UI.
+ */
+declare function buildBreadcrumbs(sections: DocSection[], sectionId: string, slug: string): BreadcrumbItem[];
+/**
+ * Builds a full-text search index from published pages and their sections.
+ *
+ * @param pages - Page records to index.
+ * @param sections - Section metadata used to enrich each result.
+ * @returns Search index entries derived from the published pages.
+ */
+declare function buildDocsIndex(pages: DocPage[], sections: DocSection[]): SearchResult[];
+/**
+ * Searches a shared search index and returns ranked matches.
+ *
+ * @param query - User-entered search query.
+ * @param index - Search index entries to rank.
+ * @returns Ranked search results limited to the top twenty entries.
+ */
+declare function searchDocs(query: string, index: SearchResult[]): SearchResult[];
+/**
+ * Creates a URL-safe slug from arbitrary text.
+ *
+ * @param title - Source text to slugify.
+ * @returns A lower-case kebab-case slug.
+ */
+declare function slugify(title: string): string;
+/**
+ * Produces a search-result snippet centred around a matching query.
+ *
+ * @param text - Source text used to build the snippet.
+ * @param query - User-entered search query.
+ * @param maxLen - Maximum snippet length.
+ * @returns A trimmed snippet containing the best query match when available.
+ */
+declare function highlightMatch(text: string, query: string, maxLen?: number): string;
+/**
+ * Baseline config used by the framework variants when no explicit config is provided.
+ */
+declare const defaultDocsConfig: DocsConfig;
+
+export { AstroDocsProvider, type BreadcrumbItem, type DocAccess, type DocAuthor, type DocNavigationLink, type DocPage, type DocRevision, type DocSection, type DocStatus, type DocsConfig, DocsConfigurationError, DocsError, type DocsErrorCode, type DocsErrorOptions, type DocsPage, type DocsProvider, DocsProviderError, type DocsSearchResult, type DocsSidebar, type DocsSidebarItem, type DocsSidebarPage, FumadocsDocsProvider, InternalDocsProvider, type SearchResult, type TocItem, buildBreadcrumbs, buildDocsIndex, calcWordCount, configureDocs, defaultDocsConfig, defineDocsConfig, extractToc, getDocsConfig, highlightMatch, isDocsConfigured, mergeDocsConfig, resetDocsConfig, searchDocs, slugify };