@captn/react

The @captn/react package includes a collection of React hooks that integrate with the Captain framework, simplifying common tasks such as handling actions, managing downloads, and interacting with a vector store directly from React components.

Features

useCaptainAction: Automates the execution of actions like focus, click, and type on elements based on URL parameters.
useObject: Provides debounced object values to prevent excessive re-renders and ensure performance optimization.
useRequiredDownloads: Manages and tracks the status of required file downloads within an application.
useSDK: Facilitates inter-process communication (IPC) with an SDK or server backend from React components.
useVectorStore: Enables querying and interacting with a vector store for searching and retrieving data.

Installation

To add the @captn/react package to your project, run the following command:

npm install @captn/react

Usage

useCaptainAction

This hook listens for changes in the URL's action query parameter and executes commands on elements identified by their data-captainid.

import { useCaptainAction } from '@captn/react';
 
// Component that uses the hook
function MyComponent() {
  useCaptainAction('click:submit-button'); // Automatically clicks the button with `data-captainid="submit-button"`
}

useObject

Debounces an object value to prevent excessive re-renders, useful for optimizing performance in components that rely on rapidly changing state.

import { useObject } from '@captn/react';
 
function MyComponent({ filterOptions }) {
  const debouncedFilterOptions = useObject(filterOptions);
 
  // Use debouncedFilterOptions for further processing or API calls
}

useRequiredDownloads

Manages downloads specified by the application, tracking progress and completion.

import { useRequiredDownloads } from '@captn/react';
 
function DownloadManager({ downloads }) {
  const {
    isCompleted,
    isDownloading,
    downloadCount,
    percent,
    download,
  } = useRequiredDownloads(downloads);
 
  return (
    <div>
      {isDownloading && <p>Downloading: {percent}% completed</p>}
      {isCompleted ? <p>All downloads completed!</p> : <button onClick={download}>Download</button>}
    </div>
  );
}

useResettableState

Sets a temporary state that will reset after a given delay.

import { useResettableState } from '@captn/react';
function MyComponent() {
	const [count, setCountTemp] = useResettableState(0, 1000);
	return (
		<button onClick={() => {
			setCountTemp(5); // Sets count to 5, then resets to 0 after 1000 milliseconds
		}}>
		Set Temporary state
		</button>
	);
}

useSaveImage

Saves an image to disk in the appropriate folder.

import { useSaveImage } from "@captn/react";
 
const { saved, save } = useSaveImage({
  image: 'data:image/png;base64,...',
  prompt: 'A beautiful landscape',
  appId: 'myAppId',
});
if (saved) {
  console.log('Image has been saved!');
}
 
// The save function can be bound to a button click as well
<button onClick={save}>Save Image</button>

useSDK

Enables components to communicate with an SDK or server using IPC mechanisms, handling both messages and file operations.

import { useSDK } from '@captn/react';
 
function App() {
  const { send, readFile, writeFile } = useSDK("myAppId", {
    onMessage: message => console.log("Received message:", message),
    onError: error => console.error("Error:", error),
  });
 
  const handleFileOperations = async () => {
    const filePath = await writeFile('test.txt', 'Hello SDK!', { encoding: 'utf8' });
    const content = await readFile(filePath, 'utf8');
    console.log('File content:', content);
  };
 
  return (
    <div>
      <button onClick={() => send({ action: "greet", payload: "Hello, SDK!" })}>
        Send Message
      </button>
      <button onClick={handleFileOperations}>
        Test File Operations
      </button>
    </div>
  );
}

useTextToImage

Generates an image with the text-to-image pipeline of Captain.

import { useTextToImage } from "@captn/react";
 
function App () {
  const { generate, start, stop, isRunning, isLoading, isGenerating, image } = useTextToImage("myAppId");
 
  return (
    <div>
      <button onClick={() => start({ model: "modelIdentifier", model_type: "stable-diffusion" })}>
        Start Image Generation
      </button>
      <button onClick={stop} disabled={!isRunning}>
        Stop Image Generation
      </button>
      <button onClick={() => generate({
        prompt: "A futuristic cityscape",
        negative_prompt: "No people",
        seed: 1234
      })} disabled={!isRunning || isGenerating}>
        Generate Image
      </button>
      {isLoading && <p>Loading...</p>}
      {image && <img src={image} alt="Generated from text" />}
    </div>
  );
}

useUnload

Sends an IPC message when a window is unloaded/closed.

import { useUnload } from "@captn/react";
 
function MyApp () {
  useUnload('myAppId', 'logout');
  return <div>My Application</div>;
}

useVectorStore

Provides real-time searching capabilities within a vector store, handling query debouncing and state management.

import { useVectorStore } from '@captn/react';
 
function SearchComponent({ query }) {
  const { data, error } = useVectorStore(query, { score_threshold: 0.5 });
 
  if (error) {
    return <div>Error: {error.message}</div>;
  }
 
  return (
    <ul>
      {data.map(item => (
        <li key={item.id}>{item.content}</li>
      ))}
    </ul>
  );
}

Versioning

We use SemVer (opens in a new tab) for versioning. For the versions available, see the tags on this repository.

Types Modules