use-bulk-operate-dataset.tsx

Overview

The useBulkOperateDataset file exports a React custom hook designed for managing bulk operations on a dataset of documents within a table or list UI. It provides a standardized interface to perform batch actions on selected documents, such as enabling/disabling, running, cancelling, or deleting them. This hook integrates with various document-related APIs and application state hooks, facilitating user interactions and feedback through toast notifications and localized labels.

This hook is particularly useful in UI components that support multi-row selection and bulk manipulation, helping to encapsulate the logic required to handle multiple documents and their different states in an efficient and user-friendly manner.

Detailed Documentation

useBulkOperateDataset

Description

A React hook that manages bulk operations on a list of documents based on the currently selected rows in a UI table or list.

Parameters

• rowSelection (UseRowSelectionType['rowSelection']):
  An object representing the current selection state of rows/documents in the UI. Typically a map of selected document IDs.

• setRowSelection (UseRowSelectionType['setRowSelection']):
  A function to update the selection state, usually provided by the parent component or a selection hook.

• documents (IDocumentInfo[]):
  An array of document objects representing the full dataset available for operations. Each document includes metadata such as its ID, type, and running status.

Returns

• list (Array<{ id: string; label: string; icon: JSX.Element; onClick: () => void | Promise<void> }>):
  An array of action descriptors, each representing a bulk operation. Each object has:

  • id: Unique identifier of the action.

  • label: Localized string for display in UI controls.

  • icon: A React element from lucide-react representing the action visually.

  • onClick: Callback function to execute the corresponding bulk operation.

Usage Example

const { list } = useBulkOperateDataset({
  rowSelection,
  setRowSelection,
  documents,
});

// Example usage in a toolbar
return (
  <div>
    {list.map(({ id, label, icon, onClick }) => (
      <button key={id} onClick={onClick} title={label}>
        {icon} {label}
      </button>
    ))}
  </div>
);

Internal Functions and Methods

1. runDocument(run: number): void

• Purpose:
  Executes a bulk run or cancel operation on selected documents that are not virtual files.

• Parameters:

  • run: A number indicating the run command (e.g., 1 = run, 2 = cancel).

• Logic Details:

  • Filters out selected document IDs that correspond to virtual documents since these cannot be run.

  • If no valid documents are selected, it shows an error toast.

  • Calls runDocumentByIds API hook with the filtered IDs and the run command.

• Dependencies:
  Uses selectedRowKeys, documents, runDocumentByIds, and translation hook t for error messages.

2. handleRunClick(): void

• Calls runDocument with run = 1 to initiate running the selected documents.

3. handleCancelClick(): void

• Calls runDocument with run = 2 to cancel running of the selected documents.

4. onChangeStatus(enabled: boolean): void

• Purpose:
  Toggles the status of selected documents between enabled and disabled.

• Parameters:

  • enabled: Boolean flag to set documents as enabled (true) or disabled (false).

• Implementation:
  Calls the setDocumentStatus API hook with the array of selected document IDs and the desired status.

5. handleEnableClick(): void

• Calls onChangeStatus(true) to enable the selected documents.

6. handleDisableClick(): void

• Calls onChangeStatus(false) to disable the selected documents.

7. handleDelete(): Promise<number | void>

• Purpose:
  Removes selected documents that are not currently running (i.e., excluding those with RunningStatus.RUNNING).

• Implementation Details:

  • Filters out documents that are running to avoid deleting in-progress work.

  • Shows an error toast if no valid documents can be deleted.

  • Calls removeDocument API hook with the filtered IDs.

  • Returns a promise which may resolve to a status code.

Important Implementation Details

• Filtering Virtual Documents:
  The hook explicitly excludes documents of type Virtual when running or cancelling because these may not represent actual files or runnable entities.

• Preventing Deletion of Running Documents:
  Documents currently in the running state cannot be deleted, protecting ongoing processes.

• Localization Support:
  All user-facing strings are localized via the react-i18next translation hook (t), enabling multi-language support.

• User Feedback:
  Uses toast notifications (sonner library) to provide immediate feedback to users on invalid operations or errors.

• Icons:
  Uses visually representative icons from the lucide-react library to enhance UI clarity for each action.

• Selection Reset:
  On successful deletion, the hook resets the row selection to an empty state.

Interaction with Other System Parts

• Hooks from other modules:

  • useSelectedIds from use-row-selection hook computes selected document IDs.

  • Document manipulation hooks: useRunDocument, useSetDocumentStatus, and useRemoveDocument handle API requests related to documents.

• Data Interfaces:

  • Operates on IDocumentInfo objects imported from the database interface definitions.

• Constants:

  • Uses DocumentType and RunningStatus constants to determine document types and current running states.

• UI Layer:

  • Designed to be consumed by React components managing tables or lists with selectable rows and bulk action toolbars or dropdowns.

Mermaid Diagram: Component Interaction Diagram

componentDiagram
    component useBulkOperateDataset {
        +rowSelection
        +setRowSelection
        +documents
        --
        +list[]
    }

    component useSelectedIds {
        +selectedIds
    }

    component useRunDocument {
        +runDocumentByIds()
    }

    component useSetDocumentStatus {
        +setDocumentStatus()
    }

    component useRemoveDocument {
        +removeDocument()
    }

    useBulkOperateDataset --> useSelectedIds : get selectedRowKeys
    useBulkOperateDataset --> useRunDocument : runDocumentByIds()
    useBulkOperateDataset --> useSetDocumentStatus : setDocumentStatus()
    useBulkOperateDataset --> useRemoveDocument : removeDocument()

Summary

The useBulkOperateDataset hook is a focused utility for managing batch operations on datasets of documents, providing a clean API for UI components to trigger enabling, disabling, running, cancelling, and deleting multiple documents with proper validation and feedback. It leverages multiple custom hooks for state management and API interactions, ensuring robust and consistent behavior in document management scenarios.