niceeval 0.6.2 → 0.7.1

package/dist/report/tree.js

@@ -1,10 +1,13 @@
-// 报告的元素树与双面组件基座(docs/feature/reports/architecture.md「报告树与两个宿主」)。
+// 报告的元素树、组件模型与 resolve 管线(docs/feature/reports/architecture.md「组件模型」
+// 「报告树与两个宿主」、docs/feature/reports/library/layout.md)。
 //
 // 报告函数返回的树不是「React 树」,只是 { type, props } 节点 —— 标准 react
 // jsx-runtime 产的元素恰好就是这个形状。本文件是基础实现:零 react 运行时依赖
 // (只有类型层的 `import type`,编译后擦除);text 宿主遍历渲染不需要 react-dom,
-// web 宿主(web.ts)才真正 import react。渲染面是纯同步函数:零 IO、零 await ——
-// 计算全部发生在报告函数体里,可达百 MB 的 artifact 永远不进渲染路径。
+// web 宿主(web.ts)才真正 import react。管线固定为 装载 → resolve(组合展开 + spec 取数,
+// 同层并行保声明序,按「同引用 input + 深相等 spec」记忆化)→ validate(两面资格)→
+// render(纯同步)。渲染面是纯同步函数:零 IO、零 await —— 可达百 MB 的 artifact
+// 只在 resolve 阶段被懒加载,永远不进渲染路径。
 import { DEFAULT_REPORT_LOCALE } from "./locale.js";
 // react/jsx-runtime 的 Fragment 是注册符号,跨 react 版本稳定;不 import react 也认得它
 const REACT_FRAGMENT = Symbol.for("react.fragment");
@@ -16,17 +19,20 @@ function isReportElement(node) {
         "props" in node &&
         typeof node.props === "object");
 }
-// ───────────────────────── 双面组件 ─────────────────────────
-/** 挂 faces 的私有键:text 宿主与树校验靠它识别双面组件。 */
+// ───────────────────────── 组件模型 ─────────────────────────
+/** 挂 faces 的私有键:管线与树校验靠它识别双面组件。 */
 export const COMPONENT_FACES = Symbol.for("niceeval.report.faces");
+/** 挂组合函数的私有键:resolve 阶段靠它识别组合组件。 */
+export const COMPONENT_COMPOSE = Symbol.for("niceeval.report.compose");
+/** Tabs / Tab 的结构角色标记:树校验的配对规则靠它,不 import primitives(避免环)。 */
+export const COMPONENT_ROLE = Symbol.for("niceeval.report.role");
+/**
+ * children 是不透明值(自由文本 / CSS 字符串)而非报告树的组件标记(Text / Style):
+ * resolve 与 validate 不下钻它们的 children——那是组件自己的 props,不是树。
+ */
+export const COMPONENT_RAW_CHILDREN = Symbol.for("niceeval.report.rawChildren");
 // web 面的环境上下文:web 宿主渲染前设好;宿主之外(组件直接嵌进用户 React 应用)
-// 用默认值 —— attemptHref 默认 view 的 attempt 路由格式(自定义组件显式调 ctx.attemptHref
-// 时总有去处);官方组件的「宿主里自动接证据室」只在宿主上下文激活时发生,
-// 宿主外不传 attemptHref 就是纯展示,不发明断链。
-//
-// URL 格式取 `#/attempt/${locator}`:AttemptLocator 本身已经是 `@` 前缀的不透明短串
-// (如 "@1x7f3q9"),原样嵌进路径段就得到 `#/attempt/@1x7f3q9`——与 docs/feature/reports/view.md「用
-// Reports 积木重建 view」定稿的单段路由逐字一致,不额外拆分或去掉 `@`。
+// 用默认值 —— attemptHref 默认 view 的 attempt 路由格式。
 const DEFAULT_WEB_CONTEXT = {
     attemptHref: (locator) => `#/attempt/${locator}`,
     locale: DEFAULT_REPORT_LOCALE,
@@ -47,83 +53,182 @@ export function runWithWebContext(ctx, fn) {
 export function isHostWebContextActive() {
     return activeWebContext !== null;
 }
-/**
- * 定义一个双面组件:faces 两键必填 —— 少实现一个面编译不过,配对是结构义务。
- * 基础实现不 import react;产物以可调用组件的形状兼容 React 渲染。
- */
-export function defineComponent(faces) {
-    if (typeof faces?.web !== "function" || typeof faces?.text !== "function") {
-        throw new Error("defineComponent requires both faces: { web(props, ctx), text(props, ctx) }. " +
-            "Every report component must render in both hosts (niceeval view and niceeval show).");
+export function defineComponent(input) {
+    if (typeof input === "function") {
+        const component = ((_props) => {
+            throw new Error(`Compose component ${componentDisplayName(input) ?? "(anonymous)"} can only render inside the report pipeline ` +
+                "(niceeval show / view, or renderReportToText / renderReportToStaticHtml): it assembles other components " +
+                "and needs the host context (scope, results, report). To embed in your own React page, compute data with " +
+                "the *Data functions and render the pure components from niceeval/report/react instead.");
+        });
+        component[COMPONENT_COMPOSE] = input;
+        if (componentDisplayName(input))
+            component.displayName = componentDisplayName(input);
+        return component;
     }
+    if (typeof input?.web !== "function" || typeof input?.text !== "function") {
+        throw new Error("defineComponent requires both faces: { web(props, ctx), text(props, ctx) } (resolve is optional). " +
+            "Every report component must render in both hosts (niceeval view and niceeval show); " +
+            "define the missing face, or pass a compose function to assemble existing components instead.");
+    }
+    const faces = input;
     // 直接调用路径:把组件当普通 React 组件嵌进用户自己的页面时走这里,web 面只接收数据形态
-    // props(R)。带 resolve 的组件若拿 selection 形态 props 走这条裸路径,web 面会缺 data ——
+    // props(R)。带 resolve 的组件若拿 spec 形态 props 走这条裸路径,web 面会缺 data ——
     // 这类组件只有经宿主的 resolveReportTree 解析后才安全渲染;纯数据 props 一直可以裸嵌。
     const component = ((props) => faces.web(props, activeWebContext ?? DEFAULT_WEB_CONTEXT));
     component[COMPONENT_FACES] = faces;
     return component;
 }
+function componentDisplayName(fn) {
+    const named = fn;
+    return named.displayName || named.name || undefined;
+}
 export function facesOf(type) {
     if (typeof type !== "function")
         return undefined;
     return type[COMPONENT_FACES];
 }
-// ───────────────────────── 数据解析(渲染前唯一的 await 边界)─────────────────────────
+export function composeOf(type) {
+    if (typeof type !== "function")
+        return undefined;
+    return type[COMPONENT_COMPOSE];
+}
+function roleOf(type) {
+    if (typeof type !== "function")
+        return undefined;
+    return type[COMPONENT_ROLE];
+}
+function hasRawChildren(type) {
+    return typeof type === "function" && type[COMPONENT_RAW_CHILDREN] === true;
+}
+// ───────────────────────── 深相等(记忆化的 spec 比较)─────────────────────────
+/**
+ * resolve 记忆化的深相等:只递归比较可序列化值(普通对象 / 数组 / 原始值);
+ * 函数与 Metric / Dimension / NumericAxis 一类携带函数的实例按引用比较——
+ * 共享计算的成立条件是引用同一实例,引用不同的等价定义只是各算一次,不构成错误。
+ */
+export function deepEqualSpec(a, b) {
+    if (a === b)
+        return true;
+    if (typeof a !== typeof b)
+        return false;
+    if (typeof a !== "object" || a === null || b === null)
+        return false;
+    if (Array.isArray(a) || Array.isArray(b)) {
+        if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length)
+            return false;
+        return a.every((item, i) => deepEqualSpec(item, b[i]));
+    }
+    const protoA = Object.getPrototypeOf(a);
+    const protoB = Object.getPrototypeOf(b);
+    if ((protoA !== Object.prototype && protoA !== null) || (protoB !== Object.prototype && protoB !== null)) {
+        return false; // 非纯对象(类实例等)按引用比较,=== 已在开头判过
+    }
+    const keysA = Object.keys(a).filter((k) => a[k] !== undefined);
+    const keysB = Object.keys(b).filter((k) => b[k] !== undefined);
+    if (keysA.length !== keysB.length)
+        return false;
+    return keysA.every((k) => deepEqualSpec(a[k], b[k]));
+}
+/** 一次页渲染内的记忆化缓存:键 = 计算函数引用 → (同引用 input + 深相等 spec) 命中。 */
+export class ResolveMemo {
+    entries = new Map();
+    fetch(fn, input, spec, compute) {
+        let list = this.entries.get(fn);
+        if (!list)
+            this.entries.set(fn, (list = []));
+        for (const entry of list) {
+            if (entry.input === input && deepEqualSpec(entry.spec, spec))
+                return entry.result;
+        }
+        const result = compute();
+        list.push({ input, spec, result });
+        return result;
+    }
+}
+/** 组件 resolve 里安全取记忆化入口:经宿主管线时在场,手工直调 resolve 时退化为直接计算。 */
+export function memoFetchOf(ctx) {
+    const internal = ctx;
+    return internal.memoFetch ?? (async (_fn, _input, _options, compute) => compute());
+}
+function illegalNodeError(type, path) {
+    const where = path.length > 0 ? ` (in ${path.join(" > ")})` : "";
+    if (typeof type === "string") {
+        return new Error(`Report trees cannot contain raw HTML <${type}>${where}. Every node must render in both hosts (niceeval show and niceeval view), and raw HTML has no text face. ` +
+            "Use <Text> for free text, the layout primitives (<Row>/<Col>/<Section>/<Table>), or move the markup into the web face of a defineComponent component.");
+    }
+    const label = componentLabel(type);
+    return new Error(`${label} is not a report component${where}: plain functions and React components cannot join a report tree because the hosts cannot render them in both faces. ` +
+        "Wrap it with defineComponent — a compose function defineComponent((props, ctx) => tree) to assemble existing components, " +
+        "or an object form defineComponent({ resolve?, text, web }) to render itself.");
+}
+function bareTextError(value, path) {
+    const where = path.length > 0 ? ` (in ${path.join(" > ")})` : "";
+    const preview = typeof value === "string" ? JSON.stringify(value.length > 40 ? `${value.slice(0, 40)}…` : value) : String(value);
+    return new Error(`Report trees cannot contain a bare ${typeof value} (${preview})${where}: free text needs an explicit carrier for terminal line-wrapping and HTML escaping. ` +
+        "Wrap it in <Text>…</Text>.");
+}
 /**
- * 报告 build 之后、树校验与 text/web 渲染之前的解析遍历:把声明式数据组件(实现了
- * `faces.resolve` 的双面组件,如 selection 形态的 MetricScatter)的 props
- * 就地换成算好的数据形态 props(三个实体列表没有 `resolve` 面,不经这一步——它们的 `items`
- * 由报告作者在 `build()` 里直接 `await .data(selection)` 备好)。计算发生在这里(唯一允许
- * await 的组件级步骤,连同报告函数体自己的 `build()`),两个渲染面
- * 之后都只看已解析的树、保持同步零 IO。遍历形状与 {@link validateReportTree} /
- * {@link renderNodeToText} 一致:
- *
- * - 同层数组兄弟并行解析(`Promise.all`),保持原始顺序 / keys;
- * - 双面组件带 resolve 的:调 `faces.resolve(props)` 换 props(有 children 再递归解析);
- * - 双面组件无 resolve 的(Row / Col / Section / RunOverview…):只递归 children,自身 props
- *   原样保留(title / className 等不能动);
- * - 普通函数组件:同步调用展开,展开结果继续解析(与 validate / render 对函数组件的处理一致);
- * - 字符串 intrinsic(<div>):原样返回,交给随后的 validateReportTree 报同一条错误。
- *
- * resolver 跑完后,树里已没有函数组件 / 未解析 props;validate / render 里对这两者的分支在
- * 正常管线下是 no-op,但保留着——手搭树直接调 validate / render(不过 resolver)的低层用法仍需要。
+ * 管线的 resolve 阶段:递归展开组合组件(以 (props, ctx) 调用并 await 返回树)、执行双面
+ * 组件的解析面;同层 sibling 并行取数且不改变节点顺序;带 resolve 的组件按「同引用 input +
+ * 深相等 spec」记忆化。非法节点(React 组件、未经 defineComponent 的普通函数、任意 HTML
+ * intrinsic)在展开遇到时立即以完整用户反馈拒绝,不为非法节点取数。
  */
-export async function resolveReportTree(node) {
+export async function resolveReportTree(node, env) {
+    const memo = env.memo ?? new ResolveMemo();
+    const composeCtx = { scope: env.scope, results: env.results, report: env.report };
+    return resolveNode(node, { memo, composeCtx }, []);
+}
+async function resolveNode(node, state, path) {
     if (node === null || node === undefined || typeof node === "boolean")
         return node;
-    if (typeof node === "string" || typeof node === "number")
+    if (typeof node === "string" || typeof node === "number") {
+        // 裸字符串在 validate 阶段以带指引的完整反馈拒绝;这里先如实透传,不为它取数。
         return node;
-    if (Array.isArray(node))
-        return Promise.all(node.map(resolveReportTree));
+    }
+    if (Array.isArray(node)) {
+        return Promise.all(node.map((child) => resolveNode(child, state, path)));
+    }
     if (!isReportElement(node))
         return node;
     const { type, props } = node;
-    // 字符串 intrinsic:不在这里报错,让 resolve 后的 validateReportTree 抛统一的那条。
-    if (typeof type === "string")
-        return node;
     if (type === REACT_FRAGMENT) {
-        const children = await resolveReportTree(props.children);
+        const children = await resolveNode(props.children, state, path);
         return { ...node, props: { ...props, children } };
     }
+    const compose = composeOf(type);
+    if (compose) {
+        // 组合组件不记忆化:它只装配、不承担取数;数据层的去重由其内部 *Data 调用经 memoFetch 命中。
+        const expanded = await compose(props, state.composeCtx);
+        return resolveNode(expanded, state, [...path, componentLabel(type)]);
+    }
     const faces = facesOf(type);
     if (faces) {
         if (typeof faces.resolve === "function") {
-            const resolvedProps = { ...(await faces.resolve(props)) };
+            const resolveFn = faces.resolve;
+            const input = props.input ?? state.composeCtx.scope;
+            const ctx = {
+                input,
+                memoFetch: (dataFn, dataInput, options, compute) => state.memo.fetch(dataFn, dataInput, options, compute),
+            };
+            const resolved = await state.memo.fetch(resolveFn, input, props, async () => resolveFn(props, ctx));
+            const resolvedProps = { ...resolved };
             if (resolvedProps.children !== undefined) {
-                resolvedProps.children = await resolveReportTree(resolvedProps.children);
+                resolvedProps.children = await resolveNode(resolvedProps.children, state, [
+                    ...path,
+                    componentLabel(type),
+                ]);
             }
             return { ...node, props: resolvedProps };
         }
-        // 无 resolve 的容器 / 数据组件:只解析 children,自身 props 原样保留。
-        const children = await resolveReportTree(props.children);
+        // 无 resolve 的容器 / 纯数据组件:只解析 children,自身 props 原样保留(title / className 不能动)。
+        if (hasRawChildren(type))
+            return node; // Text / Style 的 children 是不透明值,不是树
+        const children = await resolveNode(props.children, state, [...path, componentLabel(type)]);
         return { ...node, props: { ...props, children } };
     }
-    if (typeof type === "function") {
-        // 普通函数组件:调用展开,展开结果整体替换本节点后继续解析。
-        const expanded = type(props);
-        return resolveReportTree(expanded);
-    }
-    return node;
+    // 非法节点:HTML intrinsic、React 组件、未经 defineComponent 的普通函数 —— 立即拒绝,不取数。
+    throw illegalNodeError(type, path);
 }
 // ───────────────────────── 树校验 ─────────────────────────
 function componentLabel(type) {
@@ -137,72 +242,130 @@ function componentLabel(type) {
         return "<>";
     return `<${String(type)}>`;
 }
+function directChildElements(children) {
+    const out = [];
+    const visit = (node) => {
+        if (node === null || node === undefined || typeof node === "boolean")
+            return;
+        if (Array.isArray(node)) {
+            for (const child of node)
+                visit(child);
+            return;
+        }
+        if (isReportElement(node)) {
+            if (node.type === REACT_FRAGMENT) {
+                visit(node.props.children);
+                return;
+            }
+            out.push(node);
+            return;
+        }
+        out.push(node);
+    };
+    visit(children);
+    return out;
+}
 /**
- * 渲染前树校验:页面树里只放双面组件、排版原语与普通组合函数,字符串 intrinsic
- * (<div>)报错、指名组件路径。这是运行时校验而非编译期(标准 JSX 下 TS 把一切
- * JSX 表达式统一成 JSX.Element);两个宿主渲染前跑同一遍 —— 不做单侧宽容,否则
- * 对着 view 写的页面到 show 才炸。校验只下钻 children(children 就是报告树);
- * 普通函数组件调用展开(渲染面纯同步,重复调用无副作用)。
+ * 管线的 validate 阶段:确保展开后树中每个组件都有 text 和 web 两面。校验只看节点资格,
+ * 不限定树形:根节点可以是单个组件、Col 或 Tabs,宿主不强制任何最外层容器。
+ * 裸字符串 / 数字、HTML intrinsic、无两面资格的函数都以完整用户反馈拒绝;
+ * Tabs / Tab 的结构配对(空 Tabs、游离 Tab、非 Tab 直接子节点)也在这里校验。
  */
-export function validateReportTree(node, path = []) {
+export function validateReportTree(node, path = [], insideTabs = false) {
     if (node === null || node === undefined || typeof node === "boolean")
         return;
-    if (typeof node === "string" || typeof node === "number")
-        return;
+    if (typeof node === "string" || typeof node === "number") {
+        throw bareTextError(node, path);
+    }
     if (Array.isArray(node)) {
         for (const child of node)
-            validateReportTree(child, path);
+            validateReportTree(child, path, insideTabs);
         return;
     }
-    if (!isReportElement(node))
+    if (!isReportElement(node)) {
+        if (typeof node === "object" && node !== null && node.kind === "report") {
+            const where = path.length > 0 ? ` (in ${path.join(" > ")})` : "";
+            throw new Error(`A defineReport(...) product is not a report node${where}: the shell cannot nest. ` +
+                "Put the page content (a tree or component) here, and keep defineReport for the file's default export only.");
+        }
         return;
-    const { type, props } = node;
-    if (typeof type === "string") {
-        const where = path.length > 0 ? ` (in ${path.join(" > ")})` : "";
-        throw new Error(`Raw HTML <${type}> has no terminal face; use <Text>, layout primitives, or a defineComponent component.${where}`);
     }
+    const { type, props } = node;
     if (type === REACT_FRAGMENT) {
-        validateReportTree(props.children, path);
+        validateReportTree(props.children, path, insideTabs);
         return;
     }
+    if (typeof type === "string")
+        throw illegalNodeError(type, path);
     const label = componentLabel(type);
-    if (facesOf(type)) {
-        // 双面组件是校验的信任边界之内的叶子,但 children 仍是报告树的一部分
-        validateReportTree(props.children, [...path, label]);
+    const role = roleOf(type);
+    if (role === "tab" && !insideTabs) {
+        const where = path.length > 0 ? ` (in ${path.join(" > ")})` : "";
+        throw new Error(`<Tab> can only be a direct child of <Tabs>${where}. Wrap sibling views in <Tabs><Tab title="…">…</Tab></Tabs>, or drop the <Tab> wrapper if you only have one view.`);
+    }
+    if (role === "tabs") {
+        const children = directChildElements(props.children);
+        const nonTab = children.find((child) => roleOf(child.type) !== "tab");
+        if (nonTab !== undefined) {
+            throw new Error(`<Tabs> only accepts <Tab> as direct children (found ${isReportElement(nonTab) ? componentLabel(nonTab.type) : typeof nonTab} in ${[...path, label].join(" > ")}). Move the content inside a <Tab title="…">, or lift it out of <Tabs>.`);
+        }
+        if (children.length === 0) {
+            throw new Error(`<Tabs> needs at least one <Tab> child (in ${[...path, label].join(" > ")}). Add <Tab title="…">…</Tab>, or remove the empty <Tabs>.`);
+        }
+        for (const tab of children) {
+            validateReportTree(tab.props.children, [...path, label, componentLabel(tab.type)], false);
+        }
         return;
     }
-    if (typeof type === "function") {
-        // 普通函数组件 = 用户拿函数组合页面片段:调用展开继续校验
-        const expanded = type(props);
-        validateReportTree(expanded, [...path, label]);
+    const faces = facesOf(type);
+    if (faces) {
+        // 双面资格:无类型 JS 输入可能绕过 defineComponent 的定义期校验,这里再拦一遍
+        if (typeof faces.web !== "function" || typeof faces.text !== "function") {
+            const missing = typeof faces.web !== "function" ? "web" : "text";
+            throw new Error(`${label} is missing its ${missing} face${path.length > 0 ? ` (in ${path.join(" > ")})` : ""}: every component in a report tree must render in both hosts (niceeval show and niceeval view). Define both { text, web } in defineComponent.`);
+        }
+        // 双面组件是校验的信任边界之内的叶子,但 children 仍是报告树的一部分
+        // (Text / Style 除外:它们的 children 是不透明的自由文本 / CSS 字符串)
+        if (!hasRawChildren(type))
+            validateReportTree(props.children, [...path, label], false);
         return;
     }
-    const where = path.length > 0 ? ` (in ${path.join(" > ")})` : "";
-    throw new Error(`Unsupported node type ${label} in report tree.${where}`);
+    if (composeOf(type)) {
+        // 正常管线下 resolve 已把组合组件展开;手搭树直接 validate 时如实指出它还没展开
+        throw new Error(`${label} is a compose component and must be expanded by the resolve pipeline before validation. ` +
+            "Render through defineReport + niceeval show/view (or renderReportToText/renderReportToStaticHtml).");
+    }
+    throw illegalNodeError(type, path);
+}
+function shellQuote(value) {
+    return /^[A-Za-z0-9._/@-]+$/.test(value) ? value : `'${value.replaceAll("'", `'"'"'`)}'`;
 }
 export function createTextContext(options) {
     const width = Math.max(20, options?.width ?? 80);
     const locale = options?.locale ?? DEFAULT_REPORT_LOCALE;
     // 默认下钻命令:AttemptLocator 是 `@` 前缀的不透明短串,`niceeval show @<locator>` 是
-    // show/index.ts 已实现的真实 CLI 语法(见该文件 `@<locator>` 位置参数解析),不需要
-    // 反查 eval id 再拼一条近似命令。
+    // show 已实现的真实 CLI 语法,不需要反查 eval id 再拼一条近似命令。
     const attemptCommand = options?.attemptCommand ?? ((locator) => `niceeval show ${locator}`);
+    const experimentCommand = options?.experimentCommand ?? ((prefix) => `niceeval show --experiment ${shellQuote(prefix)}`);
     const make = (w) => ({
         width: w,
         locale,
         attemptCommand,
+        experimentCommand,
         render(node, childWidth) {
             return renderNodeToText(node, childWidth === undefined ? this : make(Math.max(10, childWidth)));
         },
     });
     return make(width);
 }
-/** text 宿主的遍历渲染:双面组件走 text 面,普通函数调用展开,块之间以换行相接。 */
+/** text 宿主的遍历渲染:双面组件走 text 面,块之间以换行相接。只吃已 resolve + validate 的树。 */
 export function renderNodeToText(node, ctx) {
     if (node === null || node === undefined || typeof node === "boolean")
         return "";
-    if (typeof node === "string" || typeof node === "number")
-        return String(node);
+    if (typeof node === "string" || typeof node === "number") {
+        // 校验先行会拦住;渲染路径自身也不宽容
+        throw bareTextError(node, []);
+    }
     if (Array.isArray(node)) {
         return node
             .map((child) => renderNodeToText(child, ctx))
@@ -212,17 +375,12 @@ export function renderNodeToText(node, ctx) {
     if (!isReportElement(node))
         return "";
     const { type, props } = node;
-    if (typeof type === "string") {
-        // 校验先行会拦住;这里兜底同一条错误,渲染路径自身也不宽容
-        throw new Error(`Raw HTML <${type}> has no terminal face; use <Text>, layout primitives, or a defineComponent component.`);
-    }
+    if (typeof type === "string")
+        throw illegalNodeError(type, []);
     if (type === REACT_FRAGMENT)
         return renderNodeToText(props.children, ctx);
     const faces = facesOf(type);
     if (faces)
         return faces.text(props, ctx);
-    if (typeof type === "function") {
-        return renderNodeToText(type(props), ctx);
-    }
-    return "";
+    throw illegalNodeError(type, []);
 }