@geenius/docs 0.4.1 → 0.8.10

package/packages/shared/dist/types-n-Ryn258.d.ts

@@ -0,0 +1,270 @@
+/**
+ * @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[]>;
+}
+
+export type { BreadcrumbItem as B, DocsConfig as D, SearchResult as S, TocItem as T, DocSection as a, DocPage as b, DocAccess as c, DocAuthor as d, DocNavigationLink as e, DocRevision as f, DocStatus as g, DocsPage as h, DocsProvider as i, DocsSearchResult as j, DocsSidebar as k, DocsSidebarItem as l, DocsSidebarPage as m };

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

@@ -1,6 +1,6 @@
 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 { JSX, Accessor, Setter } from 'solid-js';
+import { JSX, Accessor } from 'solid-js';
 
 /**
  * @module solidjsBreadcrumbs
@@ -9,15 +9,16 @@ import { JSX, Accessor, Setter } from 'solid-js';
  * metadata and the Tailwind-styled docs presentation contract.
  */
 
+interface BreadcrumbsProps {
+    items: BreadcrumbItem[];
+}
 /**
  * Renders the current docs breadcrumb hierarchy.
  *
  * @param props - Breadcrumb items describing the active page ancestry.
  * @returns Breadcrumb navigation for the current page when items exist.
  */
-declare function Breadcrumbs(props: {
-    items: BreadcrumbItem[];
-}): JSX.Element;
+declare function Breadcrumbs(props: BreadcrumbsProps): JSX.Element | null;
 
 /**
  * @module solidDocPage
@@ -48,7 +49,7 @@ declare function DocPage(props: DocPageProps): JSX.Element;
 interface DocSearchProps {
     results: SearchResult[];
     query: string;
-    onQuery: (q: string) => void;
+    onQuery: (query: string) => void;
     onSelect: (result: SearchResult) => void;
     isOpen: boolean;
     onClose: () => void;
@@ -59,7 +60,7 @@ interface DocSearchProps {
  * @param props - Search state, callbacks, and result entries to present.
  * @returns An animated search overlay for navigating docs content.
  */
-declare function DocSearch(props: DocSearchProps): JSX.Element;
+declare function DocSearch(props: DocSearchProps): JSX.Element | null;
 
 /**
  * @module solidjsDocSidebar
@@ -118,16 +119,17 @@ declare function DocsLayout(props: DocsLayoutProps): JSX.Element;
  * docs variant when an upstream repository edit URL is configured.
  */
 
+interface EditButtonProps {
+    pageSlug: string;
+    editUrl?: string;
+}
 /**
  * Renders an external link for editing the current docs page source.
  *
  * @param props - Page slug and optional base repository edit URL.
  * @returns An edit link when editing is enabled for the current page.
  */
-declare function EditButton(props: {
-    pageSlug: string;
-    editUrl?: string;
-}): JSX.Element;
+declare function EditButton(props: EditButtonProps): JSX.Element | null;
 
 /**
  * @module solidjsPageNavigation
@@ -152,7 +154,7 @@ interface PageNavigationProps {
  * @param props - Optional previous and next page descriptors.
  * @returns Navigation cards when adjacent pages are available.
  */
-declare function PageNavigation(props: PageNavigationProps): JSX.Element;
+declare function PageNavigation(props: PageNavigationProps): JSX.Element | null;
 
 /**
  * @module solidjsTableOfContents
@@ -171,7 +173,7 @@ interface TableOfContentsProps {
  * @param props - Structured heading tree and current active heading id.
  * @returns A nested table of contents for the active docs page.
  */
-declare function TableOfContents(props: TableOfContentsProps): JSX.Element;
+declare function TableOfContents(props: TableOfContentsProps): JSX.Element | null;
 
 /**
  * @module solidjsVersionSelector
@@ -183,7 +185,7 @@ declare function TableOfContents(props: TableOfContentsProps): JSX.Element;
 interface VersionSelectorProps {
     versions: string[];
     current: string;
-    onSelect: (v: string) => void;
+    onSelect: (version: string) => void;
 }
 /**
  * Renders a version picker when more than one docs version is available.
@@ -191,7 +193,7 @@ interface VersionSelectorProps {
  * @param props - Available versions, current version, and selection callback.
  * @returns A dropdown-style version switcher for the docs surface.
  */
-declare function VersionSelector(props: VersionSelectorProps): JSX.Element;
+declare function VersionSelector(props: VersionSelectorProps): JSX.Element | null;
 
 /**
  * @module solidjsDocSearchPage
@@ -201,10 +203,10 @@ declare function VersionSelector(props: VersionSelectorProps): JSX.Element;
  */
 
 interface DocSearchPageProps {
-    tree: () => (DocSection & {
+    tree: Accessor<(DocSection & {
         pages: DocPage$1[];
         pageCount: number;
-    })[] | undefined;
+    })[] | undefined>;
     onSelectPage?: (page: DocPage$1, section: DocSection) => void;
 }
 /**
@@ -215,6 +217,68 @@ interface DocSearchPageProps {
  */
 declare function DocSearchPage(props: DocSearchPageProps): JSX.Element;
 
+/**
+ * @module solidjsCreateDocsAdmin
+ * @package @geenius/docs-solidjs
+ * @description Adapts caller-provided section and page mutations into a
+ * stable SolidJS admin controller with normalized method signatures.
+ */
+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>;
+}
+/**
+ * Creates a SolidJS-friendly docs admin controller around async mutations.
+ *
+ * @param mutations - Low-level CRUD and reorder operations for docs content.
+ * @returns An admin controller with normalized section and page methods.
+ */
+declare function createDocsAdmin(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 solidjsDocsAdminPage
  * @package @geenius/docs-solidjs
@@ -223,19 +287,12 @@ declare function DocSearchPage(props: DocSearchPageProps): JSX.Element;
  */
 
 interface DocsAdminPageProps {
-    tree: () => (DocSection & {
+    tree: Accessor<(DocSection & {
         pages: DocPage$1[];
         pageCount: number;
-    })[] | undefined;
+    })[] | undefined>;
     allPages?: DocPage$1[];
-    admin: {
-        createSection: (d: Record<string, unknown>) => Promise<void>;
-        deleteSection: (id: string) => Promise<void>;
-        createPage: (d: Record<string, unknown>) => Promise<void>;
-        publishPage: (id: string) => Promise<void>;
-        archivePage: (id: string) => Promise<void>;
-        deletePage: (id: string) => Promise<void>;
-    };
+    admin: DocsAdminActions;
 }
 /**
  * Renders the docs administration dashboard for SolidJS consumers.
@@ -253,10 +310,10 @@ declare function DocsAdminPage(props: DocsAdminPageProps): JSX.Element;
  */
 
 interface DocsIndexPageProps {
-    tree: () => (DocSection & {
+    tree: Accessor<(DocSection & {
         pages: DocPage$1[];
         pageCount: number;
-    })[] | undefined;
+    })[] | undefined>;
     onSelectPage?: (page: DocPage$1, section: DocSection) => void;
 }
 /**
@@ -275,11 +332,11 @@ declare function DocsIndexPage(props: DocsIndexPageProps): JSX.Element;
  */
 
 interface DocViewPageProps {
-    tree: () => (DocSection & {
+    tree: Accessor<(DocSection & {
         pages: DocPage$1[];
         pageCount: number;
-    })[] | undefined;
-    page: () => DocPage$1 | null | undefined;
+    })[] | undefined>;
+    page: Accessor<DocPage$1 | null | undefined>;
     editPageUrl?: string;
     onNavigate: (page: DocPage$1, section: DocSection) => void;
     onIncrementView?: (pageId: string) => void;
@@ -299,13 +356,22 @@ declare function DocViewPage(props: DocViewPageProps): JSX.Element;
  * query signal, debounced execution, and normalized result lifecycle.
  */
 
-type DocSearchController = {
+/**
+ * Search state returned by the SolidJS docs search primitive.
+ *
+ * @property results - Accessor returning the current ranked search results.
+ * @property isSearching - Accessor describing whether a search request is pending.
+ * @property query - Accessor returning the active search query.
+ * @property setQuery - Updates the active search query.
+ * @property clearSearch - Resets the query, results, and loading state.
+ */
+interface DocSearchState {
     results: Accessor<SearchResult[]>;
     isSearching: Accessor<boolean>;
     query: Accessor<string>;
-    setQuery: (value: string) => string;
+    setQuery: (query: string) => void;
     clearSearch: () => void;
-};
+}
 /**
  * Creates debounced docs search state for SolidJS consumers.
  *
@@ -313,7 +379,7 @@ type DocSearchController = {
  * @param debounceMs - Delay before search execution after each query update.
  * @returns Signals and actions for driving a docs search experience.
  */
-declare function createDocSearch(searchFn: (query: string) => SearchResult[] | Promise<SearchResult[]>, debounceMs?: number): DocSearchController;
+declare function createDocSearch(searchFn: (query: string) => SearchResult[] | Promise<SearchResult[]>, debounceMs?: number): DocSearchState;
 
 /**
  * @module solidjsCreateDocs
@@ -322,7 +388,21 @@ declare function createDocSearch(searchFn: (query: string) => SearchResult[] | P
  * config, flattens pages, and tracks section, page, and search selection state.
  */
 
-type DocsState = {
+/**
+ * Aggregate docs state returned by the SolidJS docs primitive.
+ *
+ * @property sections - Accessor returning the normalized docs sections.
+ * @property currentSection - Accessor for the currently selected section.
+ * @property setSection - Updates the selected section and resets the page selection.
+ * @property currentPage - Accessor for the currently selected page.
+ * @property setPage - Updates the selected page.
+ * @property searchQuery - Accessor for the active docs search query.
+ * @property setSearchQuery - Updates the active docs search query.
+ * @property isLoading - Accessor describing whether the tree is still unresolved.
+ * @property config - Accessor returning the merged docs configuration.
+ * @property flatPages - Accessor returning the flattened page list.
+ */
+interface DocsState {
     sections: Accessor<(DocSection & {
         pages: DocPage$1[];
         pageCount: number;
@@ -330,13 +410,13 @@ type DocsState = {
     currentSection: Accessor<DocSection | null>;
     setSection: (section: DocSection | null) => void;
     currentPage: Accessor<DocPage$1 | null>;
-    setPage: Setter<DocPage$1 | null>;
+    setPage: (page: DocPage$1 | null) => void;
     searchQuery: Accessor<string>;
-    setSearchQuery: Setter<string>;
+    setSearchQuery: (query: string) => void;
     isLoading: Accessor<boolean>;
     config: Accessor<DocsConfig>;
     flatPages: Accessor<DocPage$1[]>;
-};
+}
 /**
  * Creates normalized docs state for the SolidJS docs surface.
  *
@@ -344,73 +424,10 @@ type DocsState = {
  * @param config - Optional overrides merged onto the shared docs config.
  * @returns A shared docs state object used by SolidJS pages and components.
  */
-declare function createDocs(tree: () => (DocSection & {
+declare function createDocs(tree: Accessor<(DocSection & {
     pages: DocPage$1[];
     pageCount: number;
-})[] | undefined, config?: Partial<DocsConfig>): DocsState;
-
-/**
- * @module solidjsCreateDocsAdmin
- * @package @geenius/docs-solidjs
- * @description Adapts caller-provided section and page mutations into a
- * stable SolidJS admin controller with normalized method signatures.
- */
-type DocsAdminMutations = {
-    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>;
-};
-type DocsAdminController = {
-    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>;
-};
-/**
- * Creates a SolidJS-friendly docs admin controller around async mutations.
- *
- * @param mutations - Low-level CRUD and reorder operations for docs content.
- * @returns An admin controller with normalized section and page methods.
- */
-declare function createDocsAdmin(mutations: DocsAdminMutations): DocsAdminController;
+})[] | undefined>, config?: Partial<DocsConfig>): DocsState;
 
 /**
  * @module solidjsCreateTableOfContents
@@ -419,17 +436,24 @@ declare function createDocsAdmin(mutations: DocsAdminMutations): DocsAdminContro
  * and tracks the active heading via intersection observer updates.
  */
 
-type TableOfContentsController = {
+/**
+ * Table-of-contents state returned by the SolidJS docs TOC primitive.
+ *
+ * @property toc - Accessor returning the extracted heading tree.
+ * @property activeId - Accessor returning the currently active heading id.
+ * @property setActiveId - Updates the currently active heading id.
+ */
+interface TableOfContentsState {
     toc: Accessor<TocItem[]>;
     activeId: Accessor<string>;
-    setActiveId: (value: string) => string;
-};
+    setActiveId: (id: string) => void;
+}
 /**
  * Creates table-of-contents state for a docs page.
  *
  * @param mdxContent - Accessor returning the current page MDX source.
  * @returns Derived TOC state and active-heading controls.
  */
-declare function createTableOfContents(mdxContent: () => string | undefined): TableOfContentsController;
+declare function createTableOfContents(mdxContent: Accessor<string | undefined>): TableOfContentsState;
 
 export { Breadcrumbs, DocPage, DocSearch, DocSearchPage, DocSidebar, DocViewPage, DocsAdminPage, DocsIndexPage, DocsLayout, EditButton, PageNavigation, TableOfContents, VersionSelector, createDocSearch, createDocs, createDocsAdmin, createTableOfContents };