niceeval 0.6.2 → 0.7.0

package/dist/report/text/plot.js

@@ -1,5 +1,5 @@
 // text 面的字符坐标图:MetricScatter / MetricLine 共用。
-// 形态照 docs-site/zh/guides/report-components.mdx 的示例块:y 轴刻度 + │ 边框,
+// 形态照 docs-site/zh/reference/report-components.mdx 的示例块:y 轴刻度 + │ 边框,
 // 点用字母标注、图例列在图下;lower-better 的轴反向,「好」的角落恒在右上。
 import { padDisplay, padStartDisplay, stringWidth } from "./layout.js";
 function makeScale(values, cells, invert) {

package/dist/report/text/table.js

@@ -5,7 +5,7 @@
 //
 // 列宽按显示宽度算(CJK 记 2 列);null 渲染 —,不补 0;超宽先折最宽的左对齐列,
 // 压到下限仍放不下就从右侧丢列并如实报数(「截断报剩余」是既有契约,不在这里破例)。
-import { countText, localeText } from "../locale.js";
+import { countText, localeText, resolveLocalizedText } from "../locale.js";
 import { charDisplayWidth, renderAlignedRows, stringWidth, wrapDisplay } from "./layout.js";
 const MISSING_MARK = "—";
 /** 列间距,与 renderAlignedRows 的 join("   ") 一致。 */
@@ -93,7 +93,7 @@ export function renderTableText(props, ctx) {
     const hasLocator = props.rows.some((row) => row.locator !== undefined);
     if (props.columns.length === 0 && !hasLocator)
         return "";
-    const header = props.columns.map((column) => column.header);
+    const header = props.columns.map((column) => resolveLocalizedText(column.header, locale));
     const align = props.columns.map((column) => column.align ?? "left");
     const body = props.rows.map((row) => props.columns.map((column) => cellText(row, column.key)));
     if (hasLocator) {

package/dist/report/tree.d.ts

@@ -1,16 +1,32 @@
 import type { ReactNode } from "react";
 import type { AttemptLocator } from "../results/locator.ts";
+import type { Results, Scope } from "../results/types.ts";
 import { type ReportLocale } from "./locale.ts";
+import type { ReportInput } from "./types.ts";
+import type { ReportMeta } from "./report.ts";
 /** 标准 jsx-runtime 元素形状;text 宿主只认 type / props,不管 $$typeof。 */
 export interface ReportElement {
     type: unknown;
     props: Record<string, unknown>;
     key?: unknown;
 }
-/** 报告树节点:元素、文本、数组 / Fragment 的儿子们,或渲染为空的空值。 */
-export type ReportNode = ReportElement | string | number | boolean | null | undefined | ReportNode[];
-/** 挂 faces 的私有键:text 宿主与树校验靠它识别双面组件。 */
+/**
+ * 报告树节点,形状穷尽(docs/feature/reports/library/layout.md「树的节点」):
+ * 元素、数组 / Fragment(展平保序),或条件渲染的空分支(渲染为空)。
+ * 裸字符串与数字**不是**节点——自由文本必须经 <Text> 携带,树校验遇到时按完整用户反馈拒绝。
+ */
+export type ReportNode = ReportElement | readonly ReportNode[] | null | undefined | boolean;
+/** 挂 faces 的私有键:管线与树校验靠它识别双面组件。 */
 export declare const COMPONENT_FACES: unique symbol;
+/** 挂组合函数的私有键:resolve 阶段靠它识别组合组件。 */
+export declare const COMPONENT_COMPOSE: unique symbol;
+/** Tabs / Tab 的结构角色标记:树校验的配对规则靠它,不 import primitives(避免环)。 */
+export declare const COMPONENT_ROLE: unique symbol;
+/**
+ * children 是不透明值(自由文本 / CSS 字符串)而非报告树的组件标记(Text / Style):
+ * resolve 与 validate 不下钻它们的 children——那是组件自己的 props,不是树。
+ */
+export declare const COMPONENT_RAW_CHILDREN: unique symbol;
 export interface TextContext {
     /** 可用列宽;Row 分栏后变窄。 */
     width: number;
@@ -20,6 +36,11 @@ export interface TextContext {
     render(node: ReportNode, width?: number): string;
     /** 下钻命令,通证据室:`niceeval show @<locator>`。 */
     attemptCommand(locator: AttemptLocator): string;
+    /**
+     * 组索引一类「按实验收窄」命令的生成;宿主注入以携带完整上下文(--results / --report /
+     * --page 与位置参数),默认 `niceeval show --experiment <id>`。非契约字段,官方组件内部用。
+     */
+    experimentCommand(experimentIdPrefix: string): string;
 }
 export interface WebContext {
     /** 证据室深链,同 view 的 attempt 路由(`#/attempt/@<locator>`,单段、不透明)。 */
@@ -27,73 +48,102 @@ export interface WebContext {
     /** chrome 文案的 locale;官方组件渲染面经上下文读取,宿主外默认 "en"。 */
     locale: ReportLocale;
 }
+/** 双面组件解析面的上下文:宿主注入的数据来源;props 显式给出 input 时以 props 为准。 */
+export interface ResolveContext {
+    input: ReportInput;
+}
+/** 组合组件的上下文:宿主 Scope、结果根完整读取面与规范化后的报告声明。 */
+export interface ComposeContext {
+    /** 宿主注入的 Scope。 */
+    scope: Scope;
+    /** 结果根完整读取面;历史视图从这里自行挑 Snapshot[]。 */
+    results: Results;
+    /** 规范化后的报告声明,只读(docs/feature/reports/library/layout.md「自定义组件」)。 */
+    report: ReportMeta;
+}
 export interface ComponentFaces<P, R = P> {
     /**
-     * 可选的数据解析面:把声明式 props(selection + 计算选项)在渲染前解析成纯数据 props(R)。
-     * 宿主的 {@link resolveReportTree} 在 build 之后、validate / render 之前调用它——这是整条
-     * 管线里唯一允许 await / IO 的组件级步骤;渲染面(web / text)只看已解析的 R,保持同步、零 IO。
-     * 不实现 resolve 时 R = P,组件被当作纯数据组件直接渲染。
+     * 组件唯一的异步 / IO 面:把作者写下的 props 规范化成渲染 props(R)。宿主管线在
+     * resolve 阶段调用它,按「同引用 input + 深相等 spec」在一次页渲染内记忆化;
+     * 渲染面(web / text)只看已解析的 R,保持同步、零 IO。不实现 resolve 时 R = P。
      */
-    resolve?(props: P): Promise<R>;
+    resolve?(props: P, context: ResolveContext): R | Promise<R>;
     /** 真 React JSX 在这个面里;返回静态可渲染的 ReactNode。只看已解析的 R。 */
     web(props: R, ctx: WebContext): ReactNode;
     text(props: R, ctx: TextContext): string;
 }
 /**
- * 双面组件的产物:可直接用于 JSX(React 把它当函数组件调用,走 web 面),
- * text 宿主经 COMPONENT_FACES 调 text 面。R(解析后 props 形态)在存储边界抹成 any——
+ * 报告组件的产物:可直接用于 JSX。双面组件当普通 React 组件调用时走 web 面(只接受
+ * 数据形态 props);组合组件只在报告管线内展开,宿主外直接渲染报错。R 在存储边界抹成 any——
  * 树遍历只按 ComponentFaces 的结构调用 resolve / web / text,不需要在类型层追踪 R。
  */
 export type ReportComponent<P> = ((props: P) => ReactNode) & {
-    [COMPONENT_FACES]: ComponentFaces<P, any>;
+    [COMPONENT_FACES]?: ComponentFaces<P, any>;
+    [COMPONENT_COMPOSE]?: (props: P, ctx: ComposeContext) => ReportNode | Promise<ReportNode>;
+    [COMPONENT_ROLE]?: "tabs" | "tab";
+    [COMPONENT_RAW_CHILDREN]?: true;
     displayName?: string;
 };
 /** web 宿主用:在给定 WebContext 下同步渲染(React 静态渲染本身是同步的)。 */
 export declare function runWithWebContext<T>(ctx: WebContext, fn: () => T): T;
 /** 官方组件的装配用:宿主上下文激活时才把 ctx.attemptHref 当默认下钻。 */
 export declare function isHostWebContextActive(): boolean;
-/**
- * 定义一个双面组件:faces 两键必填 —— 少实现一个面编译不过,配对是结构义务。
- * 基础实现不 import react;产物以可调用组件的形状兼容 React 渲染。
- */
+/** 函数形态:组合组件,只装配已有组件,可以异步;ctx 携带 scope / results / report。 */
+export declare function defineComponent<P>(compose: (props: P, context: ComposeContext) => ReportNode | Promise<ReportNode>): ReportComponent<P>;
+/** 对象形态:双面组件,自己渲染;text 与 web 两面必填,可选 resolve 承担取数。 */
 export declare function defineComponent<P, R = P>(faces: ComponentFaces<P, R>): ReportComponent<P>;
 export declare function facesOf(type: unknown): ComponentFaces<unknown> | undefined;
+export declare function composeOf(type: unknown): ((props: unknown, ctx: ComposeContext) => ReportNode | Promise<ReportNode>) | undefined;
+/**
+ * resolve 记忆化的深相等:只递归比较可序列化值(普通对象 / 数组 / 原始值);
+ * 函数与 Metric / Dimension / NumericAxis 一类携带函数的实例按引用比较——
+ * 共享计算的成立条件是引用同一实例,引用不同的等价定义只是各算一次,不构成错误。
+ */
+export declare function deepEqualSpec(a: unknown, b: unknown): boolean;
+/** 一次页渲染内的记忆化缓存:键 = 计算函数引用 → (同引用 input + 深相等 spec) 命中。 */
+export declare class ResolveMemo {
+    private readonly entries;
+    fetch(fn: unknown, input: unknown, spec: unknown, compute: () => Promise<unknown>): Promise<unknown>;
+}
+/** resolveReportTree 的环境:宿主注入的 Scope / 读取面 / 规范化声明。 */
+export interface ResolveEnv {
+    scope: Scope;
+    results: Results;
+    report: ReportMeta;
+    /** 一次页渲染一份;跨页共享缓存时由宿主显式传同一实例。 */
+    memo?: ResolveMemo;
+}
+/** 官方 spec 组件在 resolve 内取数的记忆化入口;经内部扩展的 ResolveContext 传递。 */
+export interface InternalResolveContext extends ResolveContext {
+    /** 按 (计算函数引用, 同引用 input, 深相等 options) 记忆化地调用计算函数。 */
+    memoFetch<T>(dataFn: unknown, input: unknown, options: unknown, compute: () => Promise<T>): Promise<T>;
+}
+/** 组件 resolve 里安全取记忆化入口:经宿主管线时在场,手工直调 resolve 时退化为直接计算。 */
+export declare function memoFetchOf(ctx: ResolveContext): InternalResolveContext["memoFetch"];
 /**
- * 报告 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 declare function resolveReportTree(node: ReportNode): Promise<ReportNode>;
+export declare function resolveReportTree(node: ReportNode, env: ResolveEnv): Promise<ReportNode>;
 /**
- * 渲染前树校验:页面树里只放双面组件、排版原语与普通组合函数,字符串 intrinsic
- * (<div>)报错、指名组件路径。这是运行时校验而非编译期(标准 JSX 下 TS 把一切
- * JSX 表达式统一成 JSX.Element);两个宿主渲染前跑同一遍 —— 不做单侧宽容,否则
- * 对着 view 写的页面到 show 才炸。校验只下钻 children(children 就是报告树);
- * 普通函数组件调用展开(渲染面纯同步,重复调用无副作用)。
+ * 管线的 validate 阶段:确保展开后树中每个组件都有 text 和 web 两面。校验只看节点资格,
+ * 不限定树形:根节点可以是单个组件、Col 或 Tabs,宿主不强制任何最外层容器。
+ * 裸字符串 / 数字、HTML intrinsic、无两面资格的函数都以完整用户反馈拒绝;
+ * Tabs / Tab 的结构配对(空 Tabs、游离 Tab、非 Tab 直接子节点)也在这里校验。
  */
-export declare function validateReportTree(node: ReportNode, path?: string[]): void;
+export declare function validateReportTree(node: ReportNode, path?: string[], insideTabs?: boolean): void;
 export interface TextRenderOptions {
     /** 终端可用列宽;默认 80。 */
     width?: number;
     /** 下钻命令的生成;宿主注入,默认 `niceeval show @<locator>`(真实可跑的 CLI 语法)。 */
     attemptCommand?: (locator: AttemptLocator) => string;
+    /** 组索引命令的生成;宿主注入以携带 --results / --report / --page 等上下文。 */
+    experimentCommand?: (experimentIdPrefix: string) => string;
     /** chrome 文案的 locale;默认 "en"(`niceeval show` 现有输出不变)。 */
     locale?: ReportLocale;
 }
 export declare function createTextContext(options?: TextRenderOptions): TextContext;
-/** text 宿主的遍历渲染:双面组件走 text 面,普通函数调用展开,块之间以换行相接。 */
+/** text 宿主的遍历渲染:双面组件走 text 面,块之间以换行相接。只吃已 resolve + validate 的树。 */
 export declare function renderNodeToText(node: ReportNode, ctx: TextContext): string;