use-save-meta.ts

Overview

The use-save-meta.ts file defines a custom React hook named useSaveMeta that provides a reusable interface for managing the display and saving of metadata associated with documents. This hook integrates with modal state management and document metadata update logic, enabling components to easily trigger a modal for editing metadata, update the metadata asynchronously, and reflect loading states.

This hook is designed primarily to be used in UI components where users can view and edit metadata for documents stored in the system. It abstracts away modal visibility control, the current document record under edit, and the asynchronous save operation for document metadata.

Detailed Explanation

useSaveMeta Hook

Description

useSaveMeta is a custom React hook that bundles together functionality to:

• Show and hide a modal dialog for editing document metadata.

• Maintain the currently selected document record for which metadata is being edited.

• Send an asynchronous request to save the updated metadata.

• Track loading state during the save operation.

This hook returns properties and methods that allow components to interact with and control the metadata modal and saving process.

Usage

const {
  setMetaLoading,
  onSetMetaModalOk,
  setMetaVisible,
  hideSetMetaModal,
  showSetMetaModal,
  metaRecord,
} = useSaveMeta();

// To open the metadata modal for a specific document:
showSetMetaModal(document);

// To handle saving metadata (e.g., on modal confirmation):
await onSetMetaModalOk(newMeta);

Returned Object

Parameters

The hook itself takes no parameters but internally uses:

• useSetDocumentMeta hook — to perform the asynchronous update of document metadata.

• useSetModalState hook — to manage modal visibility state.

• useState — to keep track of the currently selected document (metaRecord).

Internal Methods

• onSetMetaModalOk(meta: string)

  This asynchronous function is called when the user confirms the metadata changes in the modal. It calls setDocumentMeta with the current document ID and new metadata.

  • Parameters:

    • meta: string — The new metadata content to save.

  • Returns:

    • Promise<void> — Resolves when the save operation finishes. If successful (ret === 0), it hides the modal.

• handleShowSetMetaModal(row: IDocumentInfo)

  This function sets the selected document record to row and shows the modal.

  • Parameters:

    • row: IDocumentInfo — The document record to edit metadata for.

  • Returns:

    • void

Types

IDocumentInfo

• Imported from @/interfaces/database/document.

• Represents the structure of a document record in the application.

• Used to type the metaRecord state variable and modal input.

UseSaveMetaShowType

• A TypeScript type alias picking only the showSetMetaModal method from useSaveMeta’s return type.

• Useful when only the modal show function is needed without the full hook.

Implementation Details

• useSetDocumentMeta Hook:
  Provides the setDocumentMeta function and a loading flag indicating if a document metadata update request is in progress. This hook likely encapsulates API call logic to update metadata on the backend.

• useSetModalState Hook:
  Manages the visibility state of a modal dialog, exposing methods to showModal, hideModal, and a visible boolean.

• State Management:
  Maintains record state to keep track of the document currently being edited, allowing the modal to display and update metadata contextually.

• Callbacks:
  onSetMetaModalOk and handleShowSetMetaModal are memoized with useCallback to avoid unnecessary re-renders or re-creations when passed as props to child components.

• Modal Control Flow:
  When the user triggers editing of metadata, handleShowSetMetaModal is called with the selected document, which sets the current record and shows the modal. Upon confirmation, onSetMetaModalOk sends the data to the backend, and if successful, closes the modal.

Interaction with Other Parts of the System

• UI Components:
  Components responsible for rendering document lists or details can use this hook to enable metadata editing. They call showSetMetaModal with the target document and use setMetaVisible to conditionally render the modal.

• Backend / API Layer:
  The hook interacts with the backend through setDocumentMeta to persist metadata changes.

• Modal Management:
  Relies on a shared modal state hook (useSetModalState) to synchronize modal visibility across the application.

• Document Interfaces:
  Uses IDocumentInfo interface to ensure consistent document data structure.

Example Usage in a Component

import React from 'react';
import { useSaveMeta } from './use-save-meta';

const DocumentMetaEditor = () => {
  const {
    setMetaLoading,
    onSetMetaModalOk,
    setMetaVisible,
    hideSetMetaModal,
    showSetMetaModal,
    metaRecord,
  } = useSaveMeta();

  return (
    <>
      <button onClick={() => showSetMetaModal(someDocument)}>Edit Metadata</button>

      {setMetaVisible && (
        <Modal onClose={hideSetMetaModal} onOk={onSetMetaModalOk} loading={setMetaLoading}>
          <input defaultValue={metaRecord.meta} onChange={e => /* handle input */} />
        </Modal>
      )}
    </>
  );
};

Mermaid Diagram

flowchart TD
    A[useSaveMeta Hook] --> B[useSetDocumentMeta Hook]
    A --> C[useSetModalState Hook]
    A --> D[record: IDocumentInfo State]

    subgraph ModalControl
        C --> E[setMetaVisible: boolean]
        C --> F[showSetMetaModal(): void]
        C --> G[hideSetMetaModal(): void]
    end

    subgraph SaveMetaFlow
        D --> H[onSetMetaModalOk(meta: string): Promise]
        H --> B
        H --> G
    end

    A --> ModalControl
    A --> SaveMetaFlow

Summary

The use-save-meta.ts file offers a modular, well-encapsulated hook focused on managing the lifecycle of editing and saving document metadata via modal dialogs. It efficiently integrates modal state management and asynchronous data updating, making it simple for UI components to provide metadata editing capabilities without duplicating logic.