hooks.ts

Overview

The hooks.ts file provides a collection of custom React hooks primarily focused on managing "chunks" of knowledge data within an application. These hooks encapsulate state management, side effects, and business logic related to selecting, updating, deleting, and rendering chunks of knowledge, as well as handling UI modal states and chunk text display modes.

This file serves as an abstraction layer between the UI components and the underlying chunk data management, improving code modularity, reusability, and readability.

Detailed Explanation of Hooks

1. useHandleChunkCardClick

Manages the selection of a chunk card by storing the chunkId of the currently selected chunk.

Usage

const { handleChunkCardClick, selectedChunkId } = useHandleChunkCardClick();

// Example: onClick={() => handleChunkCardClick(chunk.chunk_id)}

Description

• State: selectedChunkId (string) - tracks the currently selected chunk's ID.

• Function: handleChunkCardClick(chunkId: string) - sets the selected chunk ID.

2. useGetSelectedChunk

Retrieves the chunk object corresponding to a given selectedChunkId.

Parameters

• selectedChunkId: string - The ID of the chunk to retrieve.

Returns

• An IChunk object matching the ID or an empty chunk object if none found.

Usage

const selectedChunk = useGetSelectedChunk(selectedChunkId);

Description

• Uses useSelectChunkList() to fetch the list of chunks and finds the one matching the given ID.

• Returns a default empty chunk object if no match is found.

3. useGetChunkHighlights

Generates highlight annotations for a selected chunk, adapting to the container size.

Parameters

• selectedChunkId: string - The ID of the selected chunk.

Returns

• highlights: IHighlight[] - An array of highlight objects for rendering.

• setWidthAndHeight: (width: number, height: number) => void - Setter to update container dimensions affecting highlight layout.

Usage

const { highlights, setWidthAndHeight } = useGetChunkHighlights(selectedChunkId);

// Example: setWidthAndHeight(1024, 768);

Description

• Maintains container size state (width and height).

• Uses buildChunkHighlights(selectedChunk, size) utility to build highlights based on the chunk content and container size.

• Memoizes highlights to optimize rendering.

4. useChangeChunkTextMode

Handles the display mode of chunk text, toggling between full display and truncated (ellipsis).

Returns

• textMode: ChunkTextMode - Current mode (Full or Ellipse).

• changeChunkTextMode: (mode: ChunkTextMode) => void - Function to change the text mode.

Usage

const { textMode, changeChunkTextMode } = useChangeChunkTextMode();

// Example: changeChunkTextMode(ChunkTextMode.Ellipse);

5. useDeleteChunkByIds

Provides a function to delete one or multiple chunks by their IDs, with a confirmation dialog.

Returns

• removeChunk: (chunkIds: string[], documentId: string) => Promise<number> - Function to trigger chunk deletion.

Usage

const { removeChunk } = useDeleteChunkByIds();

await removeChunk(['chunk1', 'chunk2'], 'documentId');

Description

• Uses useDeleteChunk() for the actual delete API call.

• Uses useShowDeleteConfirm() to show a confirmation modal before deletion.

• Returns the number of deleted chunks or corresponding status code.

6. useUpdateChunk

Manages the lifecycle of updating or creating a chunk, including modal visibility and submission flow.

Returns

• chunkUpdatingLoading: boolean - Loading state during chunk creation/update.

• onChunkUpdatingOk: (params: IChunk) => Promise<void> - Function to submit chunk update/create.

• chunkUpdatingVisible: boolean - Modal visibility state.

• hideChunkUpdatingModal: () => void - Function to hide the modal.

• showChunkUpdatingModal: (id?: string) => void - Function to show the modal, optionally with chunk ID.

• chunkId: string | undefined - The current chunk ID being edited.

• documentId: string - The document ID from route params.

Usage

const {
  chunkUpdatingLoading,
  onChunkUpdatingOk,
  chunkUpdatingVisible,
  hideChunkUpdatingModal,
  showChunkUpdatingModal,
  chunkId,
  documentId,
} = useUpdateChunk();

// Example: showChunkUpdatingModal('chunk123');

Description

• Uses useCreateChunk() to create or update a chunk.

• Retrieves documentId from URL parameters via useGetKnowledgeSearchParams().

• Controls modal visibility state via useSetModalState().

• Handles submission and closes modal on successful update.

Important Implementation Details

• State Management: Hooks use React's useState and useCallback to manage and memoize state and handlers efficiently.

• Data Fetching: useSelectChunkList() is used to fetch chunk lists; this hook likely connects to a global state or API.

• Highlight Building Algorithm: buildChunkHighlights() takes chunk data and container size to generate annotation highlights compatible with react-pdf-highlighter.

• Modal State: useSetModalState() abstracts modal visibility toggling, promoting consistent UI behavior.

• Delete Confirmation: useShowDeleteConfirm() enforces user confirmation before destructive actions.

• Chunk Text Mode: Uses an enum ChunkTextMode to switch between full and truncated text display modes, allowing UI flexibility.

• Asynchronous Operations: Chunk creation and deletion are async, returning status codes or promises to enable UI feedback and error handling.

Interaction with Other Parts of the System

• Hooks from Other Modules:

  • useCreateChunk, useDeleteChunk, useSelectChunkList from chunk-hooks handle API interactions and data fetching.

  • useSetModalState, useShowDeleteConfirm from common-hooks manage modal dialogs and confirmation prompts.

  • useGetKnowledgeSearchParams from route-hook extracts route parameters like documentId.

• Interfaces:

  • IChunk interface defines the chunk data structure.

  • IHighlight interface from react-pdf-highlighter represents highlight annotations.

• Utilities:

  • buildChunkHighlights generates highlight data for displaying chunk text in a PDF-like viewer.

• Constants:

  • ChunkTextMode enum defines text display modes.

The hooks in this file are intended to be used by React components responsible for displaying, editing, and managing chunks within a knowledge/document management system.

Mermaid Diagram

flowchart TD
    A[useHandleChunkCardClick] -->|manages| B[selectedChunkId]
    C[useGetSelectedChunk] -->|fetches chunk by| D[selectedChunkId]
    E[useGetChunkHighlights] -->|uses| C
    E -->|maintains| F[size (width & height)]
    E -->|returns| G[highlights, setWidthAndHeight]
    H[useChangeChunkTextMode] -->|manages| I[textMode]
    J[useDeleteChunkByIds] -->|calls| K[useDeleteChunk]
    J -->|calls| L[useShowDeleteConfirm]
    M[useUpdateChunk] -->|manages| N[chunkId]
    M -->|controls| O[Modal (visible, show, hide)]
    M -->|calls| P[useCreateChunk]
    M -->|uses| Q[useGetKnowledgeSearchParams]

    style A fill:#f9f,stroke:#333,stroke-width:1px
    style C fill:#bbf,stroke:#333,stroke-width:1px
    style E fill:#bfb,stroke:#333,stroke-width:1px
    style H fill:#fbf,stroke:#333,stroke-width:1px
    style J fill:#ffb,stroke:#333,stroke-width:1px
    style M fill:#fbb,stroke:#333,stroke-width:1px

Summary

The hooks.ts file is a utility-focused module providing specialized React hooks to manage the lifecycle and UI state of knowledge chunks. It abstracts complex state and side-effect logic such as selection, highlight rendering, modal control, creation, updating, and deletion of chunks. This file interacts closely with API hooks, modals, route params, and utilities, making it a central piece in the chunk management workflow within the application.