React と Next.js

Orbz は React コンポーネントを公開しません。React と Next.js も他のフレームワークと同じ <orb-z> を使います。

React

クライアントアプリのエントリーか、ブラウザーで実行するコンポーネントモジュールで一度インポートします。


import "@neongate-ai/orbz/react-types";
import "@neongate-ai/orbz/browser";
import { useState } from "react";
import type { OrbzState } from "@neongate-ai/orbz";
 
export function AssistantPresence() {
  const [state, setState] = useState<OrbzState>("idle");
 
  return (
    <div role="status" aria-live="polite">
      <orb-z state={state} size="300px" />
      <span>Assistant is {state}</span>
      <button type="button" onClick={() => setState("listening")}>
        Listen
      </button>
    </div>
  );
}

Next.js App Router

登録と対話用の状態をクライアント境界内に置きます。サーバーコンポーネントからも通常どおり描画できます。


"use client";
 
import "@neongate-ai/orbz/react-types";
import "@neongate-ai/orbz/browser";
 
export function AssistantPresence() {
  return <orb-z state="thinking" size="300px" />;
}

ブラウザーエントリーは SSR に安全です。customElements がなければ何もせず、クライアントバンドル実行時に要素を定義します。

カスタムタグに型を付ける

React または Next.js の TypeScript アプリで、任意の JSX 型拡張を一度インポートします。


import '@neongate-ai/orbz/react-types'

これで TypeScript が <orb-z> を認識します。Orbz ランタイムに React コンポーネント、ラッパー、アダプター、React 依存を追加するものではありません。

構造化プロパティを設定する

音声エンジン、会話フロー、知能プロバイダーは属性ではなく JavaScript オブジェクトです。最初の会話実行を予定する前に ref で設定します。


"use client";
 
import "@neongate-ai/orbz/react-types";
import "@neongate-ai/orbz/browser";
import { useCallback } from "react";
import type {
  OrbzElement,
  OrbzVoiceEnginePort
} from "@neongate-ai/orbz";
 
interface ProductPresenceProps {
  voiceEngine: OrbzVoiceEnginePort;
}
 
export function ProductPresence(props: ProductPresenceProps) {
  const setElement = useCallback(
    (element: HTMLElement | null) => {
      if (element) {
        (element as OrbzElement).voiceEngine = props.voiceEngine;
      }
    },
    [props.voiceEngine]
  );
 
  return <orb-z ref={setElement} state="idle" />;
}

リポジトリ内の React と Next.js の例も、このネイティブ要素方式を使っています。