@deckyfx/dioxus-react-bridge/dist/global.d.ts

React hooks and components for Dioxus IPC communication - lightweight bridge between React and Rust

/**
 * Global Type Declarations for Dioxus React Bridge
 *
 * This file provides type definitions for Dioxus-injected browser APIs.
 * Import this file to get TypeScript support for window.dioxusBridge and related APIs.
 *
 * @example
 * ```typescript
 * // Import in your entry file for type safety
 * import '@deckyfx/dioxus-react-bridge/global';
 *
 * // Now you can use window.dioxusBridge with full TypeScript support
 * const response = await window.dioxusBridge.request({
 *   method: 'POST',
 *   path: '/api/greeting',
 * });
 * ```
 *
 * After importing, you can use window.dioxusBridge without manual declarations:
 * ```typescript
 * const response = await window.dioxusBridge.fetch('ipc://endpoint');
 * ```
 */

import type { DioxusBridge } from './types/dioxus-bridge';

declare global {
  interface Window {
    /**
     * The main Dioxus IPC bridge
     *
     * Injected by Rust before React bundle loads. Provides HTTP-like
     * fetch API and event system for React ↔ Rust communication.
     *
     * @example
     * ```typescript
     * // HTTP-like fetch
     * const response = await window.dioxusBridge.fetch('ipc://endpoint', {
     *   method: 'POST',
     *   body: { data: 'value' }
     * });
     * console.log(response.body);
     *
     * // Event subscription (requires React package IPCBridge)
     * window.dioxusBridge.IPCBridge?.on('rust:event').subscribe({
     *   next: (data) => console.log('Received:', data)
     * });
     * ```
     */
    dioxusBridge: DioxusBridge;

    /**
     * Low-level IPC communication channel
     *
     * Injected by the Dioxus desktop library. This is the raw postMessage
     * mechanism that dioxusBridge wraps. Normally you should use
     * window.dioxusBridge.fetch() instead.
     *
     * @example
     * ```typescript
     * // Raw IPC send (advanced usage only)
     * window.ipc.postMessage(JSON.stringify({
     *   method: 'user_event',
     *   params: { /* ... *\/ }
     * }));
     * ```
     */
    ipc: {
      /**
       * Send a raw IPC message to Rust
       * @param message - Stringified JSON message
       */
      postMessage(message: string): void;
    };

    /**
     * Dioxus Native Interpreter instance
     *
     * Manages the virtual DOM and handles communication between
     * Dioxus Rust and the browser DOM. This is an internal Dioxus API
     * and should not be used directly in React applications.
     *
     * @internal
     */
    interpreter?: {
      /**
       * Initialize the interpreter with a root element
       * @param root - The root HTML element for Dioxus rendering
       */
      initialize(root: HTMLElement): void;

      /**
       * Send an IPC message to Rust
       * @param method - IPC method name
       * @param params - Method parameters
       */
      sendIpcMessage(method: string, params?: any): void;

      /**
       * Wait for WebSocket connection and edit requests from Rust
       * @param editsPath - WebSocket endpoint path
       * @param serverKey - Authentication key
       */
      waitForRequest(editsPath: string, serverKey: string): void;

      /**
       * Scroll an element to a specific position
       * @param id - Element ID
       * @param x - Horizontal scroll position
       * @param y - Vertical scroll position
       * @param behavior - Scroll behavior ('auto', 'smooth', etc.)
       */
      scroll(id: number, x: number, y: number, behavior: ScrollBehavior): boolean;

      /**
       * Scroll an element into view
       * @param id - Element ID
       * @param options - ScrollIntoView options
       */
      scrollTo(id: number, options: ScrollIntoViewOptions): boolean;

      /**
       * Get scroll height of an element
       * @param id - Element ID
       */
      getScrollHeight(id: number): number | undefined;

      /**
       * Get scroll left position of an element
       * @param id - Element ID
       */
      getScrollLeft(id: number): number | undefined;

      /**
       * Get scroll top position of an element
       * @param id - Element ID
       */
      getScrollTop(id: number): number | undefined;

      /**
       * Get scroll width of an element
       * @param id - Element ID
       */
      getScrollWidth(id: number): number | undefined;

      /**
       * Get client rect of an element
       * @param id - Element ID
       */
      getClientRect(id: number): { type: string; origin: [number, number]; size: [number, number] } | undefined;

      /**
       * Set focus on an element
       * @param id - Element ID
       * @param focus - true to focus, false to blur
       */
      setFocus(id: number, focus: boolean): void;

      /**
       * Handle Windows drag and drop event
       */
      handleWindowsDragDrop(): void;

      /**
       * Handle Windows drag over event
       * @param xPos - X position
       * @param yPos - Y position
       */
      handleWindowsDragOver(xPos: number, yPos: number): void;

      /**
       * Handle Windows drag leave event
       */
      handleWindowsDragLeave(): void;

      /**
       * Queue bytes for rendering
       * @param bytes - ArrayBuffer of edit commands
       */
      enqueueBytes(bytes: ArrayBuffer): void;

      /**
       * Flush queued bytes and execute edits
       */
      flushQueuedBytes(): void;

      /**
       * Execute edits on next animation frame
       * @param bytes - ArrayBuffer of edit commands
       */
      rafEdits(bytes: ArrayBuffer): void;

      /**
       * Mark edits as finished and notify Rust
       */
      markEditsFinished(): void;

      /**
       * Force reload all stylesheets on the page
       */
      kickAllStylesheetsOnPage(): void;
    };

    /**
     * Show a toast notification
     *
     * Dioxus-provided toast notification system. Displays a temporary
     * notification with customizable duration and progress level.
     *
     * @param headerText - Toast header/title text
     * @param message - Toast message content
     * @param progressLevel - CSS class for progress bar styling (e.g., 'success', 'error', 'warning')
     * @param durationMs - Display duration in milliseconds
     *
     * @example
     * ```typescript
     * window.showDXToast('Success', 'Operation completed!', 'success', 3000);
     * window.showDXToast('Error', 'Something went wrong', 'error', 5000);
     * ```
     */
    showDXToast?(
      headerText: string,
      message: string,
      progressLevel: string,
      durationMs: number
    ): void;

    /**
     * Schedule a toast to be displayed after page reload
     *
     * Persists toast data in sessionStorage and displays it after the next
     * page reload. Useful for showing notifications after navigation.
     *
     * @param headerText - Toast header/title text
     * @param message - Toast message content
     * @param level - Toast level for styling (e.g., 'success', 'error', 'warning')
     * @param durationMs - Display duration in milliseconds
     *
     * @example
     * ```typescript
     * // Schedule toast before reload
     * window.scheduleDXToast('Reloaded', 'App has been reloaded', 'info', 3000);
     * window.location.reload();
     * ```
     */
    scheduleDXToast?(
      headerText: string,
      message: string,
      level: string,
      durationMs: number
    ): void;

    /**
     * Close the currently displayed toast
     *
     * Manually dismiss the active toast notification.
     *
     * @example
     * ```typescript
     * window.closeDXToast();
     * ```
     */
    closeDXToast?(): void;

    /**
     * Internal drag-and-drop tracking element
     * @internal
     */
    dxDragLastElement?: HTMLElement | null;

    /**
     * Internal message queue tracking
     * @internal
     */
    __msg_queues?: any[];

    /**
     * Internal finalization registry for cleanup
     * @internal
     */
    finalizationRegistry?: FinalizationRegistry<{ id: number }>;

    /**
     * Internal query getter
     * @internal
     */
    getQuery?(request_id: number): any;

    /**
     * Internal query creator
     * @internal
     */
    createQuery?(request_id: number): any;
  }
}

export {};