API リファレンス
確定した zudo-react v1 のエクスポートを六つのパッケージエントリごとに示します。
Core: @takazudo/zfb/zudo-react
コアエントリは記述ヘルパー、リアクティビティ、スコープ、構造を扱う基本機能を提供します。このエントリから使えるのは、ここに示すエクスポートだけです。
Fragment
export const Fragment: unique symbol;Fragment はホスト要素を増やさずに兄弟の記述をまとめます。コンポーネントと JSXを参照してください。
h
export function h(type: ElementType, props: Record<string, unknown> | null,
...children: Child[]): Description;h は JSX を使わずに検証済みの記述を作ります。コンポーネントと JSXを参照してください。
isDescription
export function isDescription(value: unknown): value is Description;isDescription はブランド付きの記述形式かを検査します。コンポーネントと JSXを参照してください。
flattenChildren
export function flattenChildren(children: Child): readonly Exclude<Child, readonly Child[] | boolean | null | undefined>[];flattenChildren はコンポーネントの実行やリアクティブな値の読み取りをせず、対応する子配列を正規化します。コンポーネントと JSXを参照してください。
signal
export function signal<T>(initial: T): Signal<T>;signal はリアクティブなブランドと必須の writable ブランドを持つ書き込み可能な値を作ります。リアクティビティとフォームを参照してください。
computed
export function computed<T>(read: () => T): ReadonlySignal<T>;computed は遅延評価される読み取り専用の値を作り、フォームモデルには使えません。リアクティビティを参照してください。
batch
export function batch<T>(fn: () => T): T;batch はスケジューラーに対する同期的な書き込みをまとめます。リアクティビティを参照してください。
flush
export function flush(): Promise<void>;flush は現在の DOM と effect のキューが落ち着いた後に解決し、100 パスの上限があります。リアクティビティを参照してください。
getScope
export function getScope(): Scope;getScope は同期的なセットアップか構造ファクトリの実行中にだけ現在の所有者を返します。スコープとライフサイクルを参照してください。
Show
export function Show(props: ShowProps): Description;Show は所有スコープを持つ条件領域を作り、各分岐が生きている間にファクトリを実行します。条件分岐とリストを参照してください。
For
export function For<T>(props: ForProps<T>): Description;For は読み取り専用の item と index の signal を伴う、所有スコープ付きのキー付き項目領域を作ります。条件分岐とリストを参照してください。
Key
export type Key = string | number;キーには文字列か有限数を使い、負のゼロはゼロに正規化されます。条件分岐とリストを参照してください。
Scalar
export type Scalar = string | number | boolean | null | undefined;Scalar は記述とリアクティブなテキストで受け付けるプリミティブ値の集合です。コンポーネントと JSXを参照してください。
ReadonlySignal
export interface ReadonlySignal<T> {
readonly value: T;
readonly $$zudoReactive: "zudo-react.reactive.v1";
}ReadonlySignal は読み取り可能なリアクティブな値を表し、writable モデルのブランドを意図的に持ちません。リアクティビティを参照してください。
Signal
export interface Signal<T> extends ReadonlySignal<T> {
value: T;
readonly $$zudoWritable: "zudo-react.writable.v1";
}Signal はすべての model prop に必要な書き込み可能な signal 型です。リアクティビティとフォームを参照してください。
Child
export type Child = Scalar | Description | ReadonlySignal<Scalar> | readonly Child[];Child はコンポーネントとレンダラーが受け付ける値の再帰的な集合です。コンポーネントと JSXを参照してください。
Component
export type Component<P = Record<string, unknown>> = (props: P) => Child;Component は props から対応する子の結果を返す同期関数です。概要を参照してください。
ElementType
export type ElementType = string | Component<any> | typeof Fragment;ElementType には組み込み要素名、関数コンポーネント、Fragment が含まれます。コンポーネントと JSXを参照してください。
Description
export interface Description {
readonly $$zudo: "zudo-react.description.v1";
readonly type: ElementType;
readonly props: Readonly<Record<string, unknown>>;
readonly key: Key | null;
}Description はレンダリング間で再利用やコピーができる、ブランド付きの不活性な値です。コンポーネントと JSXを参照してください。
Cleanup
export type Cleanup = () => void;Cleanup はスコープに登録される同期的なコールバックです。スコープとライフサイクルを参照してください。
Scope
export interface Scope {
readonly abortSignal: AbortSignal;
onActivate(fn: () => void | Cleanup): void;
onCleanup(fn: Cleanup): void;
effect(fn: () => void | Cleanup): void;
}Scope は有効化、追跡される effect、クリーンアップ、abort signal を所有します。スコープとライフサイクルを参照してください。
Ref
export interface Ref<T> { current: T | null }Ref は有効化前に値が入る可変オブジェクトで、コールバック形式はありません。コンポーネントと JSXを参照してください。
Style
export type Style = string | Readonly<Record<string, string | number | null | undefined>>;Style は CSS 文字列か CSS 表記のキーを持つ平坦なオブジェクトを受け付けます。コンポーネントと JSXを参照してください。
Listener
export type Listener<E extends Event = Event> = (event: E) => void | Promise<void>;Listener はネイティブイベントを受け取り、on:<name> の表記で登録します。組み込み要素の prop は DOM のイベントマップから Listener<E> の型を決めます。既知の名前には対応するイベント型を使い、currentTarget はその要素の型になります（例: form の on:submit は SubmitEvent と HTMLFormElement）。未知のイベント名やカスタムイベント名には、単一のイベントを受け取る任意のハンドラーを指定できます。コンポーネントと JSXを参照してください。
IslandIdentity
export interface IslandIdentity {
readonly component: string;
readonly build: string;
}IslandIdentity は島をコンポーネント名と不透明なビルド識別子に結び付けます。ハイドレーションを参照してください。
Diagnostic
export interface Diagnostic {
readonly code: string;
readonly phase: "setup" | "preflight" | "commit" | "activation" | "update" | "cleanup";
readonly component: string;
readonly componentStack: readonly string[];
readonly path: string;
readonly expected: string;
readonly actual: string;
readonly protocol: string;
readonly build: string;
}Diagnostic は props 全体や入力値を含めず、段階、ルートのパス、期待値と実際の値の短い要約を記録します。ハイドレーションを参照してください。
Reporter
export type Reporter = (diagnostic: Diagnostic) => void;Reporter は構造化されたランタイム診断を一件受け取ります。ハイドレーションを参照してください。
ShowProps
export interface ShowProps {
when: ReadonlySignal<boolean>;
children: () => Child;
fallback?: (() => Child) | undefined;
}ShowProps には読み取り専用の真偽値 signal と遅延実行される分岐ファクトリが必要です。条件分岐とリストを参照してください。
ForProps
export interface ForProps<T> {
each: ReadonlySignal<readonly T[]>;
by: (item: T) => Key;
children: (item: ReadonlySignal<T>, index: ReadonlySignal<number>) => Child;
}ForProps は読み取り専用の配列 signal、副作用のないキー選択関数、項目ファクトリを受け付けます。条件分岐とリストを参照してください。
JSX runtime: @takazudo/zfb/zudo-react/jsx-runtime
本番用の自動 JSX 変換は、このサブパスから値と JSX 名前空間をインポートします。
Fragment
export { Fragment } from "./index.js";JSX ランタイムはコアの Fragment マーカーを再エクスポートします。コンポーネントと JSXを参照してください。
jsx
export function jsx(type: ElementType, props: Record<string, unknown> | null,
key?: Key | undefined): Description;jsx は自動 JSX 変換用の不活性な要素記述を一つ作ります。概要を参照してください。
jsxs
export const jsxs: typeof jsx;jsxs は複数の子に使うヘルパーで、記述のシグネチャーは jsx と同じです。コンポーネントと JSXを参照してください。
JSX
export type { JSX } from "./jsx-types.js";JSX 名前空間は Element、ElementType、IntrinsicElements、任意の key を持つ IntrinsicAttributes、children を持つ ElementChildrenAttribute をエクスポートします。HTML、SVG、カスタム要素の有限のマップを使い、あらゆる文字列を受けるインデックスはありません。コンポーネントと JSXを参照してください。
JSX development runtime: @takazudo/zfb/zudo-react/jsx-dev-runtime
TypeScript の開発用変換は、このサブパスから診断用ヘルパーをインポートします。
Fragment
export { Fragment } from "./index.js";開発用 JSX ランタイムは同じコアの Fragment マーカーを再エクスポートします。コンポーネントと JSXを参照してください。
jsxDEV
export function jsxDEV(type: ElementType, props: Record<string, unknown> | null,
key: Key | undefined, isStaticChildren: boolean,
source: { fileName: string; lineNumber: number; columnNumber: number } | undefined,
self: unknown): Description;jsxDEV は開発用変換のメタデータを受け取りながら、同じ不活性な記述を作ります。概要を参照してください。
JSX
export type { JSX } from "./jsx-types.js";開発用エントリは、有限の組み込み要素マップを持つ同じ JSX 名前空間を再エクスポートします。コンポーネントと JSXを参照してください。
Server: @takazudo/zfb/zudo-react/server
サーバーエントリはクライアントランタイムのコードをインポートせず、DOM にアクセスせずに文書をレンダリングできます。公開される値は renderToString、islandRoot、serializeProps です。
RenderOptions
export interface RenderOptions {
island?: IslandIdentity | undefined;
}RenderOptions に identity を渡すと、独立した島内部のマーカーモードを選びます。サーバーレンダリングを参照してください。
IslandOptions
export interface IslandOptions {
identity: IslandIdentity;
when?: "load" | "idle" | "visible" | "media" | undefined;
media?: string | undefined;
skipSsr?: boolean | undefined;
fallback?: Child;
}IslandOptions はラッパーの識別子、スケジュールモード、省略可能な media クエリー、skip-SSR の fallback を定義します。サーバーレンダリングを参照してください。
renderToString
export function renderToString(node: Child, options?: RenderOptions): string;renderToString は同期的な記述ツリー全体をエスケープしてシリアライズし、明示的な島ルートの外にはマーカーを付けません。サーバーレンダリングを参照してください。
islandRoot
export function islandRoot(child: Description, options: IslandOptions): Description;islandRoot は zfb 向けの明示的な島ラッパー記述を作ります。サーバーレンダリングを参照してください。
serializeProps
export function serializeProps(props: Record<string, unknown>): string;serializeProps は JSON transport のデータを検証し、ラッパー属性用の JSON テキストを返します。値が undefined の、自身が持つ列挙可能な文字列キーのデータプロパティは再帰的に省略されます。明示的な null は保持され、undefined の配列要素と配列の穴は引き続き無効です。サーバーレンダリングを参照してください。
Client: @takazudo/zfb/zudo-react/client
クライアントエントリは DOM のハイドレーション、クライアントレンダリング、島の prop の解析を担当します。
RootOptions
export interface RootOptions {
identity: IslandIdentity;
signal?: AbortSignal | undefined;
report?: Reporter | undefined;
}RootOptions は識別子、省略可能なキャンセル用 signal、診断レポーターを渡します。ハイドレーションを参照してください。
RootHandle
export interface RootHandle {
readonly protocol: "zudo-react/1";
readonly identity: IslandIdentity;
readonly disposed: boolean;
dispose(): void;
unmount(): void;
}RootHandle はリソースの解放と所有する DOM の削除を分けます。スコープとライフサイクルを参照してください。
hydrate
export function hydrate(node: Child, container: Element, options: RootOptions): RootHandle | null;hydrate は事前検証後に既存の子ノードを引き継ぎ、想定される失敗では null を返します。ハイドレーションを参照してください。
mount
export function mount(node: Child, container: Element, options: RootOptions): RootHandle | null;mount は検証済みのラッパー内にクライアント DOM を作り、想定される失敗では null を返します。ハイドレーションを参照してください。
parseProps
export function parseProps(json: string): Record<string, unknown>;parseProps は厳密な島の props レコードを解析・検証し、不正な入力では名前付きの転送エラーを投げます。ハイドレーションを参照してください。
Testing: @takazudo/zfb/zudo-react/testing
testing エントリは実際のサーバーレンダラーでアイランドを描画し、呼び出し元の document で解析して、有効化、診断、flush、破棄用のヘルパーを提供します。DOM に触れない server エントリとは分かれたテスト環境向けの API です。
createIslandTest
export function createIslandTest<P extends Record<string, unknown>>(
component: Component<P>,
props: P,
options: { document: Document; identity?: IslandIdentity },
): IslandTest;返された IslandTest はシリアライズ済みの html、解析済みの host、変更可能な identity、診断配列、hydrate()、mount()、flush()、複数回呼べる dispose() を持ちます。テストを参照してください。
withIslandTestContext
export function withIslandTestContext<T>(
options: { components: Readonly<Record<string, Component<any>>> | readonly Component<any>[]; build?: string },
callback: () => T,
): T;withIslandTestContext は同期コールバックの間だけ、SDK の Island 描画に実際のコンポーネント名を渡し、その後、元の globalThis.__zfb メタデータを復元します。非同期コールバックは拒否されます。テストを参照してください。