parsing-card.tsx

Overview

parsing-card.tsx is a React component file responsible for displaying the processing status of a document record in a concise and interactive UI element. It leverages a hover card UI pattern to show detailed information about the parsing process of a document record when a user hovers over a status indicator dot. This file primarily focuses on visualizing the running status of document parsing, along with relevant metadata like process start time, duration, and progress messages, with special styling for error messages.

The main interactive component, ParsingCard, combines a small status indicator dot with a hover-triggered popover that reveals detailed parsing info. This provides users with immediate visual feedback on the document’s parsing state and easy access to deeper insights without cluttering the UI.

Components and Functions

Interfaces

IProps

• Description: Defines the shape of props passed to components in this file.

• Properties:

  • record: IDocumentInfo — The document record object containing parsing and running status information.

Component: Dot

function Dot({ run }: { run: RunningStatus }): JSX.Element

• Purpose: Renders a small colored dot representing the running status of the document parsing process.

• Parameters:

  • run (RunningStatus): Enum or string key indicating the current running status.

• Returns: A <span> element styled with a background color corresponding to the running status.

• Usage Example:

<Dot run={record.run} />

• Implementation Details:

  • Uses a RunningStatusMap to map the run status to a specific color.

  • Renders a small, rounded span with the assigned color for visual status indication.

Component: PopoverContent

export const PopoverContent = ({ record }: IProps): JSX.Element

• Purpose: Displays detailed information about the parsing status inside the hover card content area.

• Parameters:

  • record (IDocumentInfo): The document record object containing parsing metadata and running status.

• Returns: A JSX section containing:

  • A status dot and localized status label.

  • A scrollable list of key parsing details: process start time, duration, and progress message.

• Usage Example:

<PopoverContent record={record} />

• Implementation Details:

  • Uses the useTranslation hook from react-i18next for localization of labels and status.

  • Defines a helper function replaceText that:

    • Removes consecutive duplicate newline characters.

    • Highlights any [ERROR] messages in red by wrapping them in a styled <span>.

    • Uses react-string-replace for safe string replacement in JSX.

  • Displays three key items:

    1. Process Begin At: Timestamp when parsing started.

    2. Process Duration: Duration in seconds, fixed to two decimals.

    3. Progress Message: Possibly multiline text with error highlights.

  • The progress messages maintain whitespace and line breaks (whitespace-pre-line).

Component: ParsingCard

export function ParsingCard({ record }: IProps): JSX.Element

• Purpose: Main exported component that provides an interactive hover card UI element showing parsing status.

• Parameters:

  • record (IDocumentInfo): The document record to visualize.

• Returns: A HoverCard component that:

  • Shows a clickable/status dot trigger (HoverCardTrigger).

  • On hover/focus, displays the detailed parsing info (HoverCardContent with PopoverContent).

• Usage Example:

<ParsingCard record={record} />

• Implementation Details:

  • Uses UI components HoverCard, HoverCardTrigger, and HoverCardContent from a design system.

  • The trigger is a transparent button wrapping the Dot component — this enables keyboard accessibility and pointer interaction.

  • The content pane is sized at 40% of viewport width for readability without overwhelming the screen.

Important Implementation Details and Algorithms

• Status Color Mapping: The Dot component uses a RunningStatusMap object (imported from ./constant) to determine the color associated with each running status. This abstraction allows easy extension or modification of status-color relationships without changing component logic.

• Text Replacement and Highlighting:

  • The replaceText function in PopoverContent processes the progress message string to improve readability and emphasize error lines.

  • It removes duplicate newline characters to avoid excessive vertical spacing.

  • It uses regex to find lines starting with [ERROR] and wraps those lines in a red-colored <span> for visual emphasis.

  • react-string-replace is employed to safely handle string replacement in JSX without breaking the component tree.

• Responsive and Accessible UI:

  • The button wrapping the Dot uses a transparent variant and no border to blend seamlessly into the UI.

  • The hover card uses keyboard-focusable trigger and is scrollable to accommodate large progress messages.

Interactions with Other Parts of the System

• Imports and Dependencies:

  • UI components (Button, HoverCard, etc.) are imported from the application’s shared UI library (@/components/ui).

  • IDocumentInfo interface defines the shape of the record prop and is imported from the database interface definitions (@/interfaces/database/document).

  • RunningStatus and RunningStatusMap come from a local constant file indicating possible running states and their visual mappings.

  • Uses react-i18next for internationalization of static text and dynamic labels.

  • Uses react-string-replace for safe JSX string replacement.

• Typical Usage Scenario:

  • ParsingCard is used wherever document parsing status needs to be displayed within the application, likely in lists or detail views of documents.

  • It provides a compact visual indicator with easy access to detailed status, aiding debugging, status monitoring, or user feedback.

Visual Diagram

componentDiagram
    ParsingCard <|-- HoverCard
    ParsingCard o-- Button : HoverCardTrigger
    ParsingCard o-- PopoverContent : HoverCardContent
    ParsingCard o-- Dot : Status Indicator

    PopoverContent o-- Dot : Status Indicator
    PopoverContent --> replaceText : Text Processing
    replaceText ..> reactStringReplace : Util Function

    %% Legend
    note right of ParsingCard
      Main interactive component
    end note

    note right of PopoverContent
      Displays detailed parsing info
    end note

    note right of Dot
      Colored status indicator dot
    end note

Summary

• File Purpose: Provides an interactive, localized visual component to display document parsing running status and detailed metadata.

• Key Components: ParsingCard (main hover card), PopoverContent (detailed info), Dot (status indicator).

• Functionality: Status visualization, localization, error message highlighting, responsive hover card UI.

• Dependencies: UI components, translation hooks, document interface, running status constants, string replacement utility.

• Usage: Embedded in document views to provide users with parsing status insights with minimal UI footprint.

This concludes the comprehensive documentation for the parsing-card.tsx file.