Custom Hooks Collection
Relevant source files
The following files were used as context for generating this wiki page:
The Custom Hooks Collection in the SuperClaude Website project provides a modular approach to managing documentation state, navigation behaviors, and user interaction gestures. These hooks abstract complex logic away from UI components, specifically within the documentation viewing system, to ensure a responsive and performant user experience.
These hooks primarily support the DocViewerPage and DocPage components, facilitating data fetching from local markdown maps, managing smooth scrolling for anchor links, and handling mobile-friendly touch interactions for sidebar navigation.
Sources: src/pages/DocViewerPage.js:23-26, src/hooks/useDocumentationLoader.js
Documentation Management
The core of the documentation system relies on automated loading and state management of markdown content.
useDocumentationLoader
This hook is responsible for fetching and managing the state of a specific documentation file based on its category and filename. It utilizes a centralized docs-map.json to resolve paths and performs asynchronous fetch requests to retrieve the raw markdown content.
Logic Flow:
- Searches
docsMapfor a metadata entry matching thecategoryandfileparameters. - Initiates a fetch request to the path defined in the metadata.
- Updates state variables for content (
markdown), metadata (doc), loading status (loading), and potential errors (error).
Navigation and Interaction Hooks
These hooks enhance the usability of the documentation viewer by handling browser-specific behaviors and mobile gestures.
useScrollToHash
Used within the DocViewerPage, this hook manages smooth scrolling to specific section IDs (hashes) within a rendered markdown document. It is triggered when the markdown content changes or when a user clicks an internal anchor link.
Sources: src/pages/DocViewerPage.js:24, src/pages/DocViewerPage.js:146-155
useTouchGestures
To improve mobile accessibility, this hook implements gesture detection to open the documentation sidebar. It listens for touchstart and touchend events on the window to detect a rightward swipe from the edge of the screen.
Implementation Details:
- Detection: Checks if the initial touch point is near the left edge (e.g.,
< 50px). - Validation: Measures the horizontal distance traveled. If the swipe exceeds a threshold (e.g.,
> 50px), the sidebar is triggered. - Cleanup: Removes event listeners on component unmount to prevent memory leaks.
Summary of Hook Specifications
The following table summarizes the primary custom hooks used across the application:
| Hook Name | Primary File | Purpose | Key Dependencies |
|---|---|---|---|
useDocumentationLoader | useDocumentationLoader.js | Fetches MD content and metadata. | docs-map.json |
useScrollToHash | useScrollToHash.js | Handles anchor navigation in docs. | markdown content state |
useTouchGestures | useTouchGestures.js | Detects swipe gestures for UI. | SidebarContext |
useSidebar | SidebarContext.js | Provides sidebar toggle state. | SidebarProvider |
Sources: src/hooks/useDocumentationLoader.js:4, src/pages/DocViewerPage.js:22-26, src/pages/DocPage.js:12-34
Implementation in Components
The integration of these hooks allows components like DocViewerPage to remain declarative. The component simply consumes the returned states and passes the necessary triggers to children or plugins.
Example Integration:
// From src/pages/DocViewerPage.js
const { markdown, doc, loading, error } = useDocumentationLoader(category, file);
const { scrollToHash } = useScrollToHash(markdown);
useTouchGestures(openSidebar);
Sources: src/pages/DocViewerPage.js:23-25
The Custom Hooks Collection ensures that the documentation lifecycle—from fetching files via useDocumentationLoader to navigating via useScrollToHash and interacting via useTouchGestures—is decoupled from the visual representation, allowing for easier maintenance and testing of the SuperClaude Website architecture.