sandai-react/README.md

React components and utilities for the Sandai 3D AI Characters.

# sandai-react

React components and utilities for the Sandai 3D AI Characters.

## Installation

To use **sandai-react**, install it via npm:

```sh
npm install sandai-react
```

## Components

### `AI3DCharacter`

A React component that renders a 3D AI character using Sandai.

#### AI3DCharacter Props

| Prop          | Type                                      | Description |
|--------------|---------------------------------|-------------|
| `url`        | `string` | The base URL for the Sandai AI 3D character chat interface. |
| `onLoad`     | `(client: SandaiClient) => void` | Callback function triggered when the SandaiClient is loaded. |
| `vrmUrl`     | `string` _(optional)_ | URL for the VRM model to be loaded as the 3D character. |
| `voiceName`  | `VoiceNames` _(optional)_ | Name of the voice to be used by the 3D character. |
| `showControls` | `boolean` _(optional)_ | Determines if controls should be displayed in the interface. |

#### AI3DCharacter Example Usage

```tsx
import { AI3DCharacter } from "sandai-react";

const handleLoad = (client) => {
  console.log("Sandai Client Loaded", client);
};

<AI3DCharacter
  url="https://sandai.org/chat"
  onLoad={handleLoad}
  vrmUrl="https://example.com/model.vrm"
  voiceName="ruri"
  showControls={true}
/>
```

---

### `AI3DCharacterDocs`

A React component that renders interactive documentation for functions exposed by the `SandaiClient` instance.

#### AI3DCharacterDocs Props

| Prop    | Type               | Description |
|---------|------------------|-------------|
| `client` | `SandaiClient` | The SandaiClient instance retrieved from the `onLoad` callback of `AI3DCharacter`. |

#### AI3DCharacterDocs Example Usage

```tsx
import { AI3DCharacter, AI3DCharacterDocs } from "sandai-react";
import { useState } from "react";

const App = () => {
  const [client, setClient] = useState(null);

  return (
    <>
      <AI3DCharacter
        url="https://sandai.org/chat"
        onLoad={setClient}
        showControls
      />
      {client && <AI3DCharacterDocs client={client} />}
    </>
  );
};
```

---

### `FunctionTester`

A reusable form component that dynamically generates input fields based on a schema and executes a function when submitted.

#### FunctionTester Props

| Prop   | Type              | Description |
|--------|-----------------|-------------|
| `func` | `Function` | The function to be tested, receiving input values as arguments. |
| `schema` | `SchemaType[]` | An array of schema objects defining the function parameters. |

#### FunctionTester Example Usage

```tsx
import { FunctionTester } from "sandai-react";

const myFunction = (name, age) => {
  console.log(`Name: ${name}, Age: ${age}`);
};

const schema = [
  { id: "name", type: "text", label: "Name" },
  { id: "age", type: "number", label: "Age" }
];

<FunctionTester func={myFunction} schema={schema} />;
```

---

## Contributing

Contributions are welcome! If you have suggestions or find issues, feel free to open a pull request.

## License

This project is licensed under the MIT License. See the `LICENSE` file for details.