@yuhere/js-jsonrpc2 0.0.0-stage → 2.1.1

package/webui/src/components/SchemaView.tsx

@@ -0,0 +1,151 @@
+import { useState } from 'react';
+import type { SchemaDescription } from '../api/schema';
+
+interface SchemaViewProps {
+    schema: SchemaDescription;
+    /** 顶层是否默认展开 */
+    defaultOpen?: boolean;
+    /** 缩进深度（内部递归使用） */
+    depth?: number;
+}
+
+const KIND_COLORS: Record<string, string> = {
+    string: 'var(--syn-string)',
+    number: 'var(--syn-number)',
+    boolean: 'var(--syn-boolean)',
+    literal: 'var(--syn-literal)',
+    array: 'var(--syn-container)',
+    tuple: 'var(--syn-container)',
+    object: 'var(--syn-object)',
+    record: 'var(--syn-object)',
+    union: 'var(--syn-union)',
+    enum: 'var(--syn-union)',
+    nullable: 'var(--syn-muted)',
+    unknown: 'var(--syn-muted)',
+    stream: 'var(--syn-container)',
+};
+
+function colorOf(kind: string): string {
+    return KIND_COLORS[kind] ?? 'var(--fg)';
+}
+
+/** 把 constraints 渲染成紧凑的一行，如：min=1, max=10 */
+function formatConstraints(constraints?: Record<string, unknown>): string {
+    if (!constraints) return '';
+    const entries = Object.entries(constraints).filter(([, v]) => v !== undefined);
+    if (entries.length === 0) return '';
+    return entries
+        .map(([k, v]) => `${k}=${typeof v === 'string' ? JSON.stringify(v) : JSON.stringify(v)}`)
+        .join(', ');
+}
+
+interface NodeProps {
+    schema: SchemaDescription;
+    depth: number;
+    defaultOpen: boolean;
+    label?: string;
+}
+
+function SchemaNode({ schema, depth, defaultOpen, label }: NodeProps) {
+    const [open, setOpen] = useState(defaultOpen);
+    const hasChildren = schema.children && Object.keys(schema.children).length > 0;
+    const constraintsText = formatConstraints(schema.constraints);
+
+    return (
+        <div className="schema-node" style={{ paddingLeft: depth * 14 }}>
+            <div className="schema-head" onClick={() => hasChildren && setOpen((o) => !o)}>
+                {hasChildren ? (
+                    <span className="schema-expander">{open ? '▾' : '▸'}</span>
+                ) : (
+                    <span className="schema-expander" />
+                )}
+                {label !== undefined && <span className="schema-label">{label}:</span>}
+                <span className="schema-kind" style={{ color: colorOf(schema.kind) }}>
+                    {schema.kind}
+                </span>
+                {schema.kind === 'stream' && <span className="schema-nullable">&lt;stream&gt;</span>}
+                {schema.nullable && <span className="schema-nullable">| null</span>}
+                {constraintsText && <span className="schema-constraints">{`{ ${constraintsText} }`}</span>}
+                {schema.description && (
+                    <span className="schema-description" title={schema.description}>
+                        {' '}
+            // {schema.description}
+                    </span>
+                )}
+            </div>
+            {open && hasChildren && (
+                <div className="schema-children">{renderChildren(schema, depth + 1)}</div>
+            )}
+        </div>
+    );
+}
+
+function renderChildren(schema: SchemaDescription, depth: number): React.ReactNode {
+    const c = schema.children ?? {};
+    const out: React.ReactNode[] = [];
+
+    // nullable / stream 包装器
+    if (c.inner && isSchemaDescription(c.inner)) {
+        out.push(<SchemaNode key="inner" schema={c.inner} depth={depth} defaultOpen />);
+    }
+
+    // array / tuple
+    if (Array.isArray(c.items)) {
+        (c.items as unknown[]).forEach((item, i) => {
+            if (isSchemaDescription(item)) {
+                out.push(
+                    <SchemaNode
+                        key={`item-${i}`}
+                        schema={item}
+                        depth={depth}
+                        defaultOpen
+                        label={String(i)}
+                    />
+                );
+            }
+        });
+    } else if (c.items && isSchemaDescription(c.items)) {
+        out.push(<SchemaNode key="items" schema={c.items} depth={depth} defaultOpen label="items" />);
+    }
+
+    // union
+    if (Array.isArray(c.options)) {
+        (c.options as unknown[]).forEach((opt, i) => {
+            if (isSchemaDescription(opt)) {
+                out.push(
+                    <SchemaNode
+                        key={`opt-${i}`}
+                        schema={opt}
+                        depth={depth}
+                        defaultOpen={false}
+                        label={`option[${i}]`}
+                    />
+                );
+            }
+        });
+    }
+
+    // object
+    if (c.properties && typeof c.properties === 'object' && !Array.isArray(c.properties)) {
+        for (const [key, prop] of Object.entries(c.properties)) {
+            if (isSchemaDescription(prop)) {
+                out.push(<SchemaNode key={`prop-${key}`} schema={prop} depth={depth} defaultOpen label={key} />);
+            }
+        }
+    }
+
+    // record
+    if (c.values && isSchemaDescription(c.values)) {
+        out.push(<SchemaNode key="values" schema={c.values} depth={depth} defaultOpen label="values" />);
+    }
+
+    return out;
+}
+
+function isSchemaDescription(v: unknown): v is SchemaDescription {
+    return !!v && typeof v === 'object' && typeof (v as SchemaDescription).kind === 'string';
+}
+
+export function SchemaView({ schema, defaultOpen = true, depth = 0 }: SchemaViewProps) {
+    return <SchemaNode schema={schema} depth={depth} defaultOpen={defaultOpen} />;
+}

package/webui/src/components/TestPanel.tsx

@@ -0,0 +1,279 @@
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { RPCError, isStreamResult, type RpcClient, type TransportKind } from '../api/rpc';
+import type { MethodDetail } from '../hooks/useMethodDetail';
+import { SchemaForm } from './SchemaForm';
+import { sampleFromSchema } from '../api/paramForm';
+import { absoluteEndpoint } from '../api/httpTransport';
+
+interface TestPanelProps {
+    method: string;
+    detail: MethodDetail;
+    rpc: RpcClient;
+    transport: TransportKind;
+    endpoint: string;
+}
+
+type CopyKind = 'curl' | 'fetch';
+
+const COPY_OPTIONS: { value: CopyKind; label: string }[] = [
+    { value: 'curl', label: '复制 curl' },
+    { value: 'fetch', label: '复制 fetch' },
+];
+
+export function TestPanel({
+    method,
+    detail,
+    rpc,
+    transport,
+    endpoint,
+}: TestPanelProps) {
+    const paramSchemas = useMemo(() => detail.signature.slice(1), [detail.signature]);
+    const isStreamReturn = detail.signature[0]?.kind === 'stream';
+
+    const [values, setValues] = useState<unknown[]>([]);
+    const [output, setOutput] = useState('');
+    const [running, setRunning] = useState(false);
+    const [copyKind, setCopyKind] = useState<CopyKind>('curl');
+    const [copied, setCopied] = useState(false);
+    const [copyError, setCopyError] = useState<string | null>(null);
+    const [menuOpen, setMenuOpen] = useState(false);
+    const menuRef = useRef<HTMLDivElement>(null);
+    const outRef = useRef<HTMLPreElement>(null);
+
+    useEffect(() => {
+        if (!method) return;
+        setValues(paramSchemas.map(sampleFromSchema));
+        setOutput('');
+    }, [method, paramSchemas]);
+
+    useEffect(() => {
+        setCopied(false);
+        setCopyError(null);
+        setMenuOpen(false);
+    }, [method]);
+
+    // 点击外部关闭菜单
+    useEffect(() => {
+        if (!menuOpen) return;
+        const onDocClick = (e: MouseEvent) => {
+            if (menuRef.current && !menuRef.current.contains(e.target as Node)) {
+                setMenuOpen(false);
+            }
+        };
+        document.addEventListener('mousedown', onDocClick);
+        return () => document.removeEventListener('mousedown', onDocClick);
+    }, [menuOpen]);
+
+    const setValue = (i: number, v: unknown) => {
+        setValues((prev) => {
+            const next = prev.slice();
+            next[i] = v;
+            return next;
+        });
+    };
+
+    const execute = async () => {
+        if (!method) return;
+        setRunning(true);
+        setOutput('');
+        try {
+            const result = await rpc.call(method, ...values);
+            if (isStreamResult(result)) {
+                let idx = 0;
+                const lines: string[] = [];
+                for await (const value of result) {
+                    lines.push(`[${idx}] ${JSON.stringify(value, null, 2)}`);
+                    idx++;
+                    setOutput(lines.join('\n'));
+                }
+                if (idx === 0) setOutput('（流已结束，无数据）');
+                else lines.push(`（流已结束，共 ${idx} 帧）`), setOutput(lines.join('\n'));
+            } else {
+                setOutput(JSON.stringify(result, null, 2));
+            }
+
+            if (isStreamReturn) {
+            } else {
+                const result = await rpc.call(method, ...values);
+                setOutput(JSON.stringify(result, null, 2));
+            }
+        } catch (e) {
+            setOutput(formatError(e));
+        } finally {
+            setRunning(false);
+            requestAnimationFrame(() =>
+                outRef.current?.scrollIntoView({ block: 'nearest' }),
+            );
+        }
+    };
+
+    const copyAs = async (kind: CopyKind) => {
+        if (!method) return;
+        setCopyError(null);
+        let code: string;
+        try {
+            const body = {
+                jsonrpc: '2.0' as const,
+                method,
+                params: values,
+                id: 1,
+            };
+            const url = absoluteEndpoint(endpoint);
+            code = kind === 'curl' ? buildCurl(url, body) : buildFetch(url, body);
+        } catch (e) {
+            setCopyError(e instanceof Error ? e.message : String(e));
+            return;
+        }
+        try {
+            await navigator.clipboard.writeText(code);
+            setCopied(true);
+            setTimeout(() => setCopied(false), 2000);
+        } catch (e) {
+            setCopyError(
+                `复制失败：${e instanceof Error ? e.message : String(e)}`,
+            );
+        }
+    };
+
+    const canCopy = transport === 'http';
+    const currentLabel =
+        COPY_OPTIONS.find((o) => o.value === copyKind)?.label ?? '复制';
+
+    return (
+        <section className="test">
+            <h3>
+                参数{' '}
+                <span className="hint">
+                    （{paramSchemas.length} 个，按签名自动生成）
+                </span>
+            </h3>
+
+            <SchemaForm
+                params={paramSchemas}
+                values={values}
+                onChange={setValue}
+                disabled={running}
+            />
+
+            <div className="actions">
+                <button onClick={execute} disabled={!method || running}>
+                    {running ? (isStreamReturn ? '接收中…' : '执行中…') : (isStreamReturn ? '执行并接收流 ▶' : '执行 ▶')}
+                </button>
+
+                <div className="split-button" ref={menuRef}>
+                    <button
+                        type="button"
+                        className="split-button-main"
+                        onClick={() => void copyAs(copyKind)}
+                        disabled={!method || !canCopy}
+                        title={canCopy ? '复制当前调用的等价代码' : '仅 HTTP 传输可生成代码'}
+                    >
+                        {copied ? '已复制 ✓' : currentLabel}
+                    </button>
+                    <button
+                        type="button"
+                        className="split-button-caret"
+                        onClick={() => setMenuOpen((o) => !o)}
+                        disabled={!method || !canCopy}
+                        aria-haspopup="menu"
+                        aria-expanded={menuOpen}
+                        title="选择复制格式"
+                    >
+                        ▾
+                    </button>
+                    {menuOpen && (
+                        <ul className="split-button-menu" role="menu">
+                            {COPY_OPTIONS.map((opt) => (
+                                <li
+                                    key={opt.value}
+                                    role="menuitem"
+                                    onClick={() => {
+                                        setCopyKind(opt.value);
+                                        setMenuOpen(false);
+                                        void copyAs(opt.value);
+                                    }}
+                                >
+                                    {opt.label}
+                                    {copyKind === opt.value && (
+                                        <span className="check">✓</span>
+                                    )}
+                                </li>
+                            ))}
+                        </ul>
+                    )}
+                </div>
+
+                {copyError && <span className="error small">{copyError}</span>}
+
+                <button
+                    onClick={() => setValues(paramSchemas.map(sampleFromSchema))}
+                    disabled={!method}
+                >
+                    重置为示例
+                </button>
+                <button onClick={() => setOutput('')} disabled={!output}>
+                    清空输出
+                </button>
+            </div>
+
+            <h3>结果{isStreamReturn && <span className="hint">（流式）</span>}</h3>
+            <pre className="output" ref={outRef}>
+                {output || '（尚未执行）'}
+            </pre>
+        </section>
+    );
+}
+
+// ─────────────────────────────────────────────────────────────
+// 代码片段生成
+// ─────────────────────────────────────────────────────────────
+
+interface RpcBody {
+    jsonrpc: '2.0';
+    method: string;
+    params: unknown[];
+    id: number;
+}
+
+function buildCurl(url: string, body: RpcBody): string {
+    const bodyText = JSON.stringify(body, null, 2);
+    const quotedBody = `'${bodyText.replace(/'/g, `'\\''`)}'`;
+    return [
+        `curl -X POST '${url}'`,
+        `  -H 'Content-Type: application/json'`,
+        `  -d ${quotedBody}`,
+    ].join(' \\\n');
+}
+
+function buildFetch(url: string, body: RpcBody): string {
+    const bodyText = JSON.stringify(body, null, 2);
+    const indented = bodyText
+        .split('\n')
+        .map((line, i) => (i === 0 ? line : '    ' + line))
+        .join('\n');
+    return [
+        'await fetch(' + JSON.stringify(url) + ', {',
+        `  method: 'POST',`,
+        `  headers: { 'Content-Type': 'application/json' },`,
+        '  body: JSON.stringify(',
+        '    ' + indented.split('\n').join('\n    '),
+        '  ),',
+        '});',
+    ].join('\n');
+}
+
+function formatError(e: unknown): string {
+    if (e instanceof RPCError) {
+        const { code, message, data } = e.payload;
+        const lines = [`Error ${code}: ${message}`];
+        if (data !== undefined) {
+            lines.push('');
+            lines.push('data:');
+            lines.push(
+                typeof data === 'string' ? data : JSON.stringify(data, null, 2),
+            );
+        }
+        return lines.join('\n');
+    }
+    return `Error: ${e instanceof Error ? e.message : String(e)}`;
+}

package/webui/src/components/Toolbar.tsx

@@ -0,0 +1,70 @@
+import type { TransportKind } from '../api/rpc';
+import { useTheme, type ThemeMode } from '../theme/ThemeProvider';
+
+interface ToolbarProps {
+    transport: TransportKind;
+    onTransportChange: (t: TransportKind) => void;
+    onRefresh: () => void;
+    loading: boolean;
+    error: string | null;
+}
+
+const THEME_OPTIONS: { value: ThemeMode; label: string }[] = [
+    { value: 'system', label: '跟随系统' },
+    { value: 'light', label: '亮' },
+    { value: 'dark', label: '暗' },
+];
+
+export function Toolbar({
+    transport,
+    onTransportChange,
+    onRefresh,
+    loading,
+    error,
+}: ToolbarProps) {
+    const { mode, setMode } = useTheme();
+
+    return (
+        <header className="toolbar">
+            <h1>JSON-RPC 2.0</h1>
+
+            <div className="segmented" role="group" aria-label="传输方式">
+                <button
+                    type="button"
+                    className={transport === 'http' ? 'active' : ''}
+                    onClick={() => onTransportChange('http')}
+                >
+                    HTTP
+                </button>
+                <button
+                    type="button"
+                    className={transport === 'ws' ? 'active' : ''}
+                    onClick={() => onTransportChange('ws')}
+                >
+                    WebSocket
+                </button>
+            </div>
+
+            <button onClick={onRefresh} disabled={loading}>
+                {loading ? '刷新中…' : '刷新方法列表'}
+            </button>
+
+            {error && <span className="error">{error}</span>}
+
+            {/* 主题下拉，放右上角 */}
+            <label className="theme-select" title="主题">
+                <span className="theme-select-label">主题</span>
+                <select
+                    value={mode}
+                    onChange={(e) => setMode(e.target.value as ThemeMode)}
+                >
+                    {THEME_OPTIONS.map((opt) => (
+                        <option key={opt.value} value={opt.value}>
+                            {opt.label}
+                        </option>
+                    ))}
+                </select>
+            </label>
+        </header>
+    );
+}

package/webui/src/hooks/useMethodDetail.ts

@@ -0,0 +1,61 @@
+import { useEffect, useState } from 'react';
+import type { RpcClient } from '../api/rpc';
+import type { SchemaDescription } from '../api/schema';
+
+export interface MethodDetail {
+    help: string;
+    /** system.methodSignature 返回的 Schema 列表（每项对应一个参数） */
+    signature: SchemaDescription[];
+    error: string | null;
+    loading: boolean;
+}
+
+const EMPTY: MethodDetail = { help: '', signature: [], error: null, loading: false };
+
+function isSchemaDescription(v: unknown): v is SchemaDescription {
+    return !!v && typeof v === 'object' && typeof (v as SchemaDescription).kind === 'string';
+}
+
+export function useMethodDetail(rpc: RpcClient, method: string): MethodDetail {
+    const [detail, setDetail] = useState<MethodDetail>(EMPTY);
+
+    useEffect(() => {
+        if (!method) {
+            setDetail(EMPTY);
+            return;
+        }
+        let cancelled = false;
+        setDetail({ help: '', signature: [], error: null, loading: true });
+
+        (async () => {
+            try {
+                const [help, signature] = await Promise.all([
+                    rpc.call<string>('system.methodHelp', method).catch(() => ''),
+                    rpc.call<unknown[]>('system.methodSignature', method).catch(() => []),
+                ]);
+                if (cancelled) return;
+                const sigArr = Array.isArray(signature) ? signature.filter(isSchemaDescription) : [];
+                setDetail({
+                    help: typeof help === 'string' ? help : '',
+                    signature: sigArr,
+                    error: null,
+                    loading: false,
+                });
+            } catch (e) {
+                if (cancelled) return;
+                setDetail({
+                    help: '',
+                    signature: [],
+                    error: e instanceof Error ? e.message : String(e),
+                    loading: false,
+                });
+            }
+        })();
+
+        return () => {
+            cancelled = true;
+        };
+    }, [rpc, method]);
+
+    return detail;
+}

package/webui/src/hooks/useMethods.ts

@@ -0,0 +1,27 @@
+import { useCallback, useEffect, useState } from 'react';
+import type { RpcClient } from '../api/rpc';
+
+export function useMethods(rpc: RpcClient) {
+    const [methods, setMethods] = useState<string[]>([]);
+    const [loading, setLoading] = useState(false);
+    const [error, setError] = useState<string | null>(null);
+
+    const refresh = useCallback(async () => {
+        setLoading(true);
+        setError(null);
+        try {
+            const list = await rpc.call<string[]>('system.listMethods');
+            setMethods(Array.isArray(list) ? [...list].sort() : []);
+        } catch (e) {
+            setError(e instanceof Error ? e.message : String(e));
+        } finally {
+            setLoading(false);
+        }
+    }, [rpc]);
+
+    useEffect(() => {
+        void refresh();
+    }, [refresh]);
+
+    return { methods, loading, error, refresh };
+}

package/webui/src/main.tsx

@@ -0,0 +1,13 @@
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import App from './App';
+import { ThemeProvider } from './theme/ThemeProvider';
+import './styles/geek.css';
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+    <React.StrictMode>
+        <ThemeProvider>
+            <App />
+        </ThemeProvider>
+    </React.StrictMode>
+);