use-show-embed-dialog.ts

Overview

use-show-embed-dialog.ts is a React hook utility module designed to manage the display logic and token validation for an "Embed" modal dialog within an application. It handles fetching and verifying system tokens, showing appropriate error messages when tokens or beta flags are missing, and controlling the modal's visibility.

The file provides several custom React hooks that encapsulate:

• Displaying error messages related to token and beta availability.

• Fetching and validating system token lists before proceeding with other operations.

• Managing the show/hide state of an embed modal dialog, ensuring that all prerequisites (valid tokens and beta flags) are met before displaying the modal.

Detailed Explanation of Hooks

1. useShowTokenEmptyError

Purpose:
Provides a function to display an error message when the system token is missing or empty. This helps notify users of token-related errors in a localized manner.

Implementation Details:

• Uses useTranslate hook scoped to the chat namespace to localize the error message.

• Uses a memoized callback (useCallback) that triggers a UI error toast/message using message.error.

Returns:

• showTokenEmptyError: () => void — Function to trigger the token empty error message.

Usage Example:

const { showTokenEmptyError } = useShowTokenEmptyError();
showTokenEmptyError(); // Displays localized token error message

2. useShowBetaEmptyError

Purpose:
Provides a function to display an error message when the beta flag is missing or false. This indicates that the requested feature or token is not in beta or not available.

Implementation Details:

• Similar to useShowTokenEmptyError, but displays a beta-related error message.

• Localized using useTranslate with the chat scope.

Returns:

• showBetaEmptyError: () => void — Function to trigger the beta empty error message.

Usage Example:

const { showBetaEmptyError } = useShowBetaEmptyError();
showBetaEmptyError(); // Displays localized beta error message

3. useFetchTokenListBeforeOtherStep

Purpose:
Handles fetching the manual system token list and performs validation checks before other dependent steps are executed (e.g., before showing the embed modal). It ensures that:

• The token list is available and non-empty.

• The first token has an active beta flag.

• Appropriate error messages are shown if conditions fail.

Implementation Details:

• Uses useFetchManualSystemTokenList to fetch the list of tokens asynchronously.

• Extracts the first token and beta flag from the list if available.

• Defines an async handleOperate function that refetches the token list and validates it:

  • If no tokens are found, calls showTokenEmptyError.

  • If the beta flag is false or missing, calls showBetaEmptyError.

  • Returns the token string if validation passes.

  • Returns false if validation fails.

Returns:

• token: string — The first system token in the list or empty string.

• beta: string | any — The beta flag value from the first token (could be boolean or string).

• handleOperate: () => Promise<string | false> — Async function to refetch and validate tokens.

Usage Example:

const { token, beta, handleOperate } = useFetchTokenListBeforeOtherStep();

async function proceed() {
  const validToken = await handleOperate();
  if (validToken) {
    // Proceed with valid token
  } else {
    // Handle error scenario (already shown by error messages)
  }
}

4. useShowEmbedModal

Purpose:
Controls the visibility state of the Embed modal dialog, ensuring that the system token and beta flag validations succeed before the modal is shown.

Implementation Details:

• Uses useSetModalState hook to get modal visibility state and show/hide handlers.

• Integrates useFetchTokenListBeforeOtherStep to validate tokens before showing the modal.

• Defines handleShowEmbedModal which:

  • Calls handleOperate to validate tokens.

  • Shows the embed modal only if validation succeeds.

• Provides the token and beta flag to consumers for use inside the modal or elsewhere.

Returns:

• showEmbedModal: () => Promise<void> — Function to validate and show the embed modal.

• hideEmbedModal: () => void — Function to hide the embed modal.

• embedVisible: boolean — Current visibility state of the embed modal.

• embedToken: string — The token fetched from the system token list.

• beta: string | any — The beta flag from the token list.

Usage Example:

const { showEmbedModal, hideEmbedModal, embedVisible, embedToken } = useShowEmbedModal();

return (
  <>
    <button onClick={showEmbedModal}>Show Embed Modal</button>
    {embedVisible && <EmbedModal token={embedToken} onClose={hideEmbedModal} />}
  </>
);

Important Implementation Details

• Localization: All error messages are localized using the useTranslate hook scoped to 'chat', ensuring multi-language support.

• Memoization: Uses useCallback to memoize functions and avoid unnecessary re-renders.

• Token List Validation: The token list is expected to be an array of objects with at least token and beta properties. The first element is used as the primary token.

• Error Messaging: Uses a centralized message.error UI utility to show toast notifications for user feedback.

• Modal State Management: Relies on an external hook useSetModalState to manage modal visibility, abstracting modal state logic.

Interaction with Other Parts of the System

• Hooks Imported:

  • useSetModalState (likely controls generic modal visibility state)

  • useTranslate (internationalization/localization)

  • useFetchManualSystemTokenList (fetches system tokens from user settings or backend)

• UI: Uses a shared message component from ../ui/message for error notifications.

• Purpose in Application: This file acts as a bridge between user settings (tokens), UI feedback (error messages), and modal display logic, ensuring that the embed modal is only shown when the system is in a valid state with required tokens and beta flags.

Mermaid Diagram: Hook Structure & Relationships

flowchart TD
    A[use-show-embed-dialog.ts]

    A --> B[useShowTokenEmptyError]
    A --> C[useShowBetaEmptyError]
    A --> D[useFetchTokenListBeforeOtherStep]
    A --> E[useShowEmbedModal]

    D --> B
    D --> C

    E --> D
    E --> F[useSetModalState (imported)]
    B --> G[message.error (UI)]
    C --> G
    D --> H[useFetchManualSystemTokenList (imported)]
    E --> I[showEmbedModal, hideEmbedModal, embedVisible (from useSetModalState)]

Summary

This file provides a clean, modular approach to managing token validation and modal dialog visibility in a React application. By encapsulating error handling, token fetching, and modal state management into separate reusable hooks, it promotes maintainability and clear separation of concerns.

The primary workflow is:
Fetch system tokens → Validate tokens and beta flag → Show error messages if invalid → Show embed modal if valid

This approach ensures users are informed of issues early and prevents invalid states in the UI.

End of Documentation