use-export-json.ts

Overview

This file defines a React hook, useHandleExportOrImportJsonFile, that manages the export and import of JSON files representing graph data in a flow-based application. The primary functionality includes:

• Exporting the current graph data as a downloadable JSON file.

• Importing graph data from a user-uploaded JSON file, validating its structure, and updating the application state accordingly.

• Providing modal visibility controls and user feedback during these operations.

This hook integrates with various custom hooks and utilities in the system, facilitating seamless interaction with UI modals, toast notifications, translation, and graph state management.

Detailed Explanation

Export / Import Hook: useHandleExportOrImportJsonFile

This is the default exported hook from the file, encapsulating all logic related to exporting and importing graph JSON files.

Returned Object

• fileUploadVisible: boolean
  Controls the visibility state of the file upload modal dialog.

• handleExportJson: () => void
  Function to trigger the export/download of the current graph data as a JSON file.

• handleImportJson: () => void
  Function to show the file upload modal for importing JSON files.

• hideFileUploadModal: () => void
  Function to hide the file upload modal.

• onFileUploadOk: ({ fileList, platform }: { fileList: File[]; platform: Platform }) => Promise
  Async callback invoked when files are uploaded through the modal. It validates the uploaded file and updates the graph state if valid.

onFileUploadOk Function

This method handles the user action of uploading JSON files for import.

Parameters:

• fileList: File[] — List of files uploaded by the user (only the first file is processed).

• platform: Platform — Enum indicating the platform context of the upload (e.g., web, mobile).

Behavior:

1. Checks if fileList contains at least one file.

2. Validates that the uploaded file's MIME type is JSON (application/json).

3. Reads the file content as text.

4. Parses the content into a JSON object.

5. Validates that the parsed JSON object is non-empty and contains a nodes array.

6. If valid, updates the graph state using setGraphInfo and closes the modal.

7. If invalid or on parsing error, displays an error message to the user.

Error Handling:

• Uses toast notifications (useToast) and Ant Design's message.error to inform users of invalid file types or invalid JSON content.

Example Usage:

// Called when user confirms file upload in modal
onFileUploadOk({ fileList: [uploadedFile], platform: Platform.Web });

handleExportJson Function

Triggers the export of the current graph data to a JSON file.

Behavior:

• Invokes buildDslData() to get the current graph DSL data structure.

• Calls downloadJsonFile utility with the graph data and a filename constructed from the agent's title.

• Initiates a file download in the user's browser.

Example Usage:

// Called on click of "Export JSON" button
handleExportJson();

Important Implementation Details

• The hook depends on several other custom hooks and utilities:

  • useBuildDslData to generate the current graph DSL data.

  • useSetGraphInfo to update the graph state on import.

  • useFetchAgent to retrieve metadata (title) for naming the exported file.

  • useSetModalState to control modal dialog visibility.

  • useToast and message from Ant Design for user notifications.

  • useTranslation to support internationalized messages.

• JSON validation includes checking for a non-empty object with a nodes array, ensuring the file matches expected graph data shape.

• The file only processes the first file if multiple files are uploaded.

• Uses React's useCallback to memoize functions and optimize performance.

Interaction with Other Parts of the System

• UI Components: Presumably used by components responsible for rendering export/import buttons and modals.

• Graph State Management: Uses useSetGraphInfo to update the global graph state on successful import.

• Agent Metadata: Uses useFetchAgent to get contextual data like the agent's title for naming exported files.

• File Utilities: Uses downloadJsonFile utility to handle the client-side file download.

• Toast & Modal: Uses toast notifications and modal state hooks to provide user feedback and control dialogs.

• Localization: Uses react-i18next for translating user messages, enhancing internationalization support.

Usage Example in a Component

import React from 'react';
import { useHandleExportOrImportJsonFile } from './use-export-json';

const GraphExportImportControls = () => {
  const {
    fileUploadVisible,
    handleExportJson,
    handleImportJson,
    hideFileUploadModal,
    onFileUploadOk,
  } = useHandleExportOrImportJsonFile();

  return (
    <>
      <button onClick={handleExportJson}>Export JSON</button>
      <button onClick={handleImportJson}>Import JSON</button>

      {fileUploadVisible && (
        <FileUploadModal
          visible={fileUploadVisible}
          onOk={onFileUploadOk}
          onCancel={hideFileUploadModal}
        />
      )}
    </>
  );
};

Mermaid Diagram of File Structure and Workflow

flowchart TD
    A[useHandleExportOrImportJsonFile Hook] --> B(buildDslData)
    A --> C(useSetModalState)
    A --> D(useSetGraphInfo)
    A --> E(useFetchAgent)
    A --> F(useToast)
    A --> G(useTranslation)
    A --> H(downloadJsonFile)
    A --> I[onFileUploadOk]
    A --> J[handleExportJson]

    I -->|calls| D
    I -->|calls| F
    I -->|calls| message.error
    J -->|calls| B
    J -->|calls| H

Summary

The use-export-json.ts file provides a clean, reusable React hook that abstracts the complexity of exporting and importing flow graph data as JSON files. It ensures file validation, user feedback, and seamless integration with the application’s state and UI layers. This modular approach enhances maintainability and user experience in managing flow data serialization.