niceeval 0.9.1 → 0.10.2

package/src/report/definition/grid-layout.ts

@@ -0,0 +1,146 @@
+// Grid 的语义层与面内布局(docs/feature/reports/architecture.md「排版原语的语义层与面内布局」、
+// docs/feature/reports/library/layout.md「Grid 与 Stat」)。只放同步纯函数与中间类型:
+// normalizeGrid 把 resolved ReportNode children 校验并展平成有序 cell 列表;planTextGrid
+// 只依赖 availableWidth / cell 数 / 规范化 Grid props,规划 text 面的列数与每列宽度。
+// 不 import show / view、Results IO 或 stylesheet;primitives.tsx 消费本文件产出两面适配。
+
+import type { ReportNode } from "./tree.ts";
+
+export type GridVariant = "plain" | "boxed";
+export type GridDensity = "regular" | "compact";
+
+// react/jsx-runtime 的 Fragment 注册符号,跨 react 版本稳定(tree.ts 同一常量的独立取用,
+// Symbol.for 全局注册表保证同一符号,不产生耦合)。
+const REACT_FRAGMENT = Symbol.for("react.fragment");
+
+function isElementNode(node: unknown): node is { type: unknown; props: Record<string, unknown>; key?: unknown } {
+  return typeof node === "object" && node !== null && !Array.isArray(node) && "type" in node && "props" in node;
+}
+
+function keyOf(node: unknown, fallback: string): string {
+  if (isElementNode(node)) {
+    const key = node.key;
+    if (typeof key === "string" || typeof key === "number") return String(key);
+  }
+  return fallback;
+}
+
+/** 校验 `columns`:必须是有限正整数——TypeScript 的 `number` 排除不了 0/负数/小数/NaN/Infinity。 */
+export function validateGridColumns(columns: number): number {
+  if (!(Number.isFinite(columns) && Number.isInteger(columns) && columns > 0)) {
+    throw new Error(
+      `Grid columns must be a finite positive integer, received ${JSON.stringify(columns)}. ` +
+        "Pass columns={N} with a whole number greater than 0 (e.g. columns={3}).",
+    );
+  }
+  return columns;
+}
+
+export interface NormalizedGridCell {
+  readonly node: ReportNode;
+  /** React key:复用元素自带 key,缺失时按展平后的声明序生成稳定回退。 */
+  readonly key: string;
+}
+
+/**
+ * `normalizeGrid` 的产物:有序、不可拆的 cell 列表 + columns / variant / density。
+ * 不是公开 data shape,也不进结果或 artifact——只是两个渲染面共享的同步排版中间值。
+ */
+export interface NormalizedGrid {
+  readonly cells: readonly NormalizedGridCell[];
+  readonly columns: number;
+  readonly variant: GridVariant;
+  readonly density: GridDensity;
+}
+
+/**
+ * 递归展开数组与 Fragment、跳过空分支(null/undefined/boolean),其余节点各占一格
+ * ——`Col` 归拢的多个子节点、任意自定义组件的渲染结果都是不透明的一格,不下钻其内部结构。
+ */
+function flattenGridChildren(children: ReportNode): NormalizedGridCell[] {
+  const cells: NormalizedGridCell[] = [];
+  const visit = (node: ReportNode): void => {
+    if (node === null || node === undefined || typeof node === "boolean") return;
+    if (Array.isArray(node)) {
+      for (const child of node) visit(child);
+      return;
+    }
+    if (isElementNode(node) && node.type === REACT_FRAGMENT) {
+      visit(node.props.children as ReportNode);
+      return;
+    }
+    cells.push({ node, key: keyOf(node, `nre-grid-cell-${cells.length}`) });
+  };
+  visit(children);
+  return cells;
+}
+
+/** `Grid` 组件创建时的一次性规范化:校验 props、展平 children 成有序 cell 列表。 */
+export function normalizeGrid(input: {
+  children: ReportNode;
+  columns: number;
+  variant?: GridVariant;
+  density?: GridDensity;
+}): NormalizedGrid {
+  return {
+    cells: flattenGridChildren(input.children),
+    columns: validateGridColumns(input.columns),
+    variant: input.variant ?? "plain",
+    density: input.density ?? "regular",
+  };
+}
+
+/** text 面规划的输入:只有可用宽度、cell 数与规范化 Grid props 里跟宽度有关的两项。 */
+export interface TextGridPlanInput {
+  readonly availableWidth: number;
+  readonly cellCount: number;
+  readonly columns: number;
+  readonly density: GridDensity;
+}
+
+/**
+ * text 面的一次性排版计划:实际列数、每列内容显示宽度、格间 gutter。
+ * `boxed` 与 `plain` 复用同一份计划(规划总是先扣 boxed 的四边框与内 padding),
+ * `plain` 渲染时只是不打印这部分字符——两个 variant 因此列数一致,不会各挑各的列数。
+ */
+export interface TextGridPlan {
+  readonly columns: number;
+  readonly contentWidths: readonly number[];
+  readonly gutter: number;
+}
+
+/** text 面每 cell 的最小可读内容宽度;density 不以挤坏字段换取更多列。 */
+const MIN_CONTENT_WIDTH = 24;
+/** boxed 单 cell 的固定开销:左右各一根边框 + 左右各一格 padding。 */
+const BOXED_OVERHEAD_PER_CELL = 4;
+
+function gridGutter(density: GridDensity): number {
+  return density === "compact" ? 1 : 2;
+}
+
+/**
+ * 从 `min(columns, cellCount)` 向一列尝试,选出满足每格最小可读内容宽度的最大列数;
+ * 一列是无条件 fallback(即使内容宽度因此小于 24)。选定列数后,余下的显示列从左向右
+ * 逐列多补一列,因此任意一行的显示宽度都不会超过 `availableWidth`(见调用方组装)。
+ */
+export function planTextGrid(input: TextGridPlanInput): TextGridPlan {
+  const { availableWidth, cellCount, columns, density } = input;
+  const gutter = gridGutter(density);
+  const maxColumns = Math.max(1, Math.min(columns, Math.max(cellCount, 1)));
+
+  let chosen = 1;
+  for (let n = maxColumns; n >= 2; n--) {
+    const budget = availableWidth - BOXED_OVERHEAD_PER_CELL * n - gutter * (n - 1);
+    if (budget >= 0 && Math.floor(budget / n) >= MIN_CONTENT_WIDTH) {
+      chosen = n;
+      break;
+    }
+  }
+
+  const budget = Math.max(0, availableWidth - BOXED_OVERHEAD_PER_CELL * chosen - gutter * (chosen - 1));
+  const base = Math.floor(budget / chosen);
+  const remainder = budget - base * chosen;
+  const contentWidths = Array.from({ length: chosen }, (_, i) => Math.max(1, base + (i < remainder ? 1 : 0)));
+
+  return { columns: chosen, contentWidths, gutter };
+}

package/src/report/{primitives.tsx → definition/primitives.tsx}

@@ -1,15 +1,19 @@
-// 排版原语 Row / Col / Section / Text / Style / Tabs / Tab / Table:八个内置双面组件,
-// 没有特殊机制(docs/feature/reports/library/layout.md)。web 面是普通 React 渲染;
+// 排版原语 Row / Col / Grid / Section / Stat / Text / Style / Tabs / Tab / Table:十个内置
+// 双面组件,没有特殊机制(docs/feature/reports/library/layout.md)。web 面是普通 React 渲染;
 // text 面用 ctx.render(child, 子宽) 显式传宽。Style 注入页级全局 CSS(树位置只决定声明
 // 顺序),text 面渲染为空。Table 是自定义表的标准件,官方表状组件的 text 面也建在它上面。
+// Grid / Stat 的语义层(normalizeGrid 展平校验、text 面的 TextGridPlan 排版)在
+// ./grid-layout.ts(docs/feature/reports/architecture.md「排版原语的语义层与面内布局」);
+// 本文件只声明两面适配,不重复那份算术。
 
-import type { ReactNode } from "react";
-import type { AttemptLocator } from "../results/locator.ts";
+import type { CSSProperties, ReactNode } from "react";
+import type { AttemptLocator } from "../../results/locator.ts";
 import { COMPONENT_RAW_CHILDREN, COMPONENT_ROLE, defineComponent, type ReportNode } from "./tree.ts";
-import { localeText, resolveLocalizedText, type LocalizedText, type ReportLocale } from "./locale.ts";
-import { indentBlock, joinColumns, stringWidth, wrapDisplay } from "./text/layout.ts";
-import type { ColumnAlign } from "./text/layout.ts";
-import { renderTableText } from "./text/table.ts";
+import { localeText, resolveLocalizedText, type LocalizedText, type ReportLocale } from "../model/locale.ts";
+import { indentBlock, joinColumns, padDisplay, stringWidth, wrapDisplay } from "../model/text-layout.ts";
+import type { ColumnAlign } from "../model/text-layout.ts";
+import { renderTableText } from "./table-text.ts";
+import { normalizeGrid, planTextGrid, type GridDensity, type GridVariant } from "./grid-layout.ts";
 
 function childArray(children: ReportNode): ReportNode[] {
   if (children === null || children === undefined || typeof children === "boolean") return [];
@@ -20,6 +24,9 @@ function cx(...parts: (string | undefined)[]): string {
   return parts.filter(Boolean).join(" ");
 }
 
+/** `null`/缺数据的统一显示符:Table 与 Stat 共用,不补成 0。 */
+const MISSING_MARK = "—";
+
 export interface LayoutProps {
   children?: ReportNode;
   className?: string;
@@ -76,27 +83,168 @@ export const Row = defineComponent<RowProps>({
 });
 Row.displayName = "Row";
 
+// ───────────────────────── Grid / Stat ─────────────────────────
+
+export interface GridProps extends LayoutProps {
+  /** 宽面最多摆几列;必须是有限正整数,运行时校验(docs/feature/reports/library/layout.md「Grid 与 Stat」)。 */
+  columns: number;
+  /** plain 无框;boxed 给每个 cell 完整四边框。默认 plain。 */
+  variant?: GridVariant;
+  /** 改变格内留白,并调整内置 Stat 的主值字号;不改变内容和分组。默认 regular。 */
+  density?: GridDensity;
+}
+
+/** boxed 单个 cell 的完整边框:同一份 TextGridPlan 决定内容宽度,四边不因换行残缺。 */
+function boxCellBlock(content: string, contentWidth: number): string {
+  const lines = content.length > 0 ? content.split("\n") : [""];
+  const top = `┌${"─".repeat(contentWidth + 2)}┐`;
+  const bottom = `└${"─".repeat(contentWidth + 2)}┘`;
+  const body = lines.map((line) => `│ ${padDisplay(line, contentWidth)} │`);
+  return [top, ...body, bottom].join("\n");
+}
+
+/** 一个物理行内的 cell 并排:顶对齐、短 block 补空行到同高(joinColumns 已有语义)。 */
+function renderGridRow(blocks: string[], contentWidths: number[], gutter: number, variant: GridVariant): string {
+  const separator = " ".repeat(gutter);
+  if (variant === "boxed") {
+    const boxed = blocks.map((block, i) => boxCellBlock(block, contentWidths[i]));
+    const boxWidths = contentWidths.map((w) => w + 4);
+    return joinColumns(boxed, boxWidths, separator);
+  }
+  return joinColumns(blocks, contentWidths, separator);
+}
+
+/**
+ * 自由摘要面板的格子容器:只负责呈现,不读取 Scope、不聚合 Metric。每个直接子节点
+ * (数组 / Fragment 先按 ReportNode 规则展平,空分支不占格)是一格;`Col` 把多个区块
+ * 归成一格。展平与 text 面排版的算术在 ./grid-layout.ts,这里只做两面结构适配。
+ */
+export const Grid = defineComponent<GridProps>({
+  web({ children, columns, variant, density, className }) {
+    const normalized = normalizeGrid({ children, columns, variant, density });
+    const style: CSSProperties = { "--nre-grid-max-columns": normalized.columns } as CSSProperties;
+    return (
+      <div
+        className={cx("nre", "nre-grid", `nre-grid--${normalized.variant}`, `nre-grid--${normalized.density}`, className)}
+        style={style}
+      >
+        {normalized.cells.map((cell) => (
+          <div className="nre-grid-cell" key={cell.key}>
+            {cell.node as ReactNode}
+          </div>
+        ))}
+      </div>
+    );
+  },
+  text({ children, columns, variant, density }, ctx) {
+    const normalized = normalizeGrid({ children, columns, variant, density });
+    if (normalized.cells.length === 0) return "";
+    const plan = planTextGrid({
+      availableWidth: ctx.width,
+      cellCount: normalized.cells.length,
+      columns: normalized.columns,
+      density: normalized.density,
+    });
+    // 确定计划后才对每个 cell 调用一次 ctx.render——不为试探列数重复渲染。
+    const blocks = normalized.cells.map((cell, i) => ctx.render(cell.node, plan.contentWidths[i % plan.columns]));
+    const rows: string[] = [];
+    for (let start = 0; start < blocks.length; start += plan.columns) {
+      const rowBlocks = blocks.slice(start, start + plan.columns);
+      const rowWidths = plan.contentWidths.slice(0, rowBlocks.length);
+      rows.push(renderGridRow(rowBlocks, rowWidths, plan.gutter, normalized.variant));
+    }
+    return rows.join("\n\n");
+  },
+});
+Grid.displayName = "Grid";
+
+export type StatTone = "neutral" | "positive" | "negative" | "warning";
+
+export interface StatProps {
+  label: LocalizedText;
+  /** 已格式化的主值;null 明确渲染为 —,不补成 0。 */
+  value: LocalizedText | number | null;
+  /** 主值下面的短解释;省略时不留空行。 */
+  detail?: LocalizedText;
+  /** 主值的语义色;不从正负号、单位或 Metric.better 猜。默认 neutral。 */
+  tone?: StatTone;
+  className?: string;
+}
+
+/**
+ * Grid / Stat 共享的显示值规范化:LocalizedText 走 resolveLocalizedText,number 走当前
+ * locale 的 Intl.NumberFormat,null 变 —;两个面调同一份,不各写一套。
+ */
+function resolveStatDisplay(value: LocalizedText | number | null, locale: ReportLocale): string {
+  if (value === null) return MISSING_MARK;
+  if (typeof value === "number") return new Intl.NumberFormat(locale).format(value);
+  return resolveLocalizedText(value, locale);
+}
+
+/** label / 主值 / 辅助信息的最小内容单元;可以脱离 Grid 单独使用。 */
+export const Stat = defineComponent<StatProps>({
+  web({ label, value, detail, tone = "neutral", className }, ctx) {
+    return (
+      <div className={cx("nre", "nre-stat", `nre-stat--${tone}`, className)}>
+        <div className="nre-stat-label">{resolveLocalizedText(label, ctx.locale)}</div>
+        <div className="nre-stat-value">{resolveStatDisplay(value, ctx.locale)}</div>
+        {detail !== undefined ? <div className="nre-stat-detail">{resolveLocalizedText(detail, ctx.locale)}</div> : null}
+      </div>
+    );
+  },
+  text({ label, value, detail }, ctx) {
+    const lines = [resolveLocalizedText(label, ctx.locale), resolveStatDisplay(value, ctx.locale)];
+    if (detail !== undefined) lines.push(resolveLocalizedText(detail, ctx.locale));
+    return lines.flatMap((line) => wrapDisplay(line, ctx.width)).join("\n");
+  },
+});
+Stat.displayName = "Stat";
+
+// ───────────────────────── Section ─────────────────────────
+
 export interface SectionProps extends LayoutProps {
   title: LocalizedText;
+  /** 标题行右侧的短元信息;text 面与标题同一行,空间不足时换到下一行。 */
+  meta?: LocalizedText;
+}
+
+/** 标题行右侧同一行放不下 meta 时,退化成标题后两格缩进折行。 */
+function sectionHeadingLine(heading: string, metaText: string | undefined, width: number): string {
+  if (metaText === undefined) return heading;
+  const gap = width - stringWidth(heading) - stringWidth(metaText);
+  if (gap >= 1) return heading + " ".repeat(gap) + metaText;
+  const wrapped = wrapDisplay(metaText, Math.max(1, width - 2)).join("\n");
+  return `${heading}\n${indentBlock(wrapped, "  ")}`;
 }
 
-/** 带标题的块:网页是标题层级,终端是标题行加缩进。 */
+/** 带标题的块:网页是标题层级(可选 meta 同行右对齐),终端是标题行加缩进。 */
 export const Section = defineComponent<SectionProps>({
-  web({ title, children, className }, ctx) {
+  web({ title, meta, children, className }, ctx) {
+    const titleText = resolveLocalizedText(title, ctx.locale);
+    const metaText = meta !== undefined ? resolveLocalizedText(meta, ctx.locale) : undefined;
     return (
       <section className={cx("nre", "nre-section", className)}>
-        <h2 className="nre-section-title">{resolveLocalizedText(title, ctx.locale)}</h2>
+        {metaText !== undefined ? (
+          <header className="nre-section-header">
+            <h2 className="nre-section-title">{titleText}</h2>
+            <p className="nre-section-meta">{metaText}</p>
+          </header>
+        ) : (
+          <h2 className="nre-section-title">{titleText}</h2>
+        )}
         {children as ReactNode}
       </section>
     );
   },
-  text({ title, children }, ctx) {
+  text({ title, meta, children }, ctx) {
     const heading = resolveLocalizedText(title, ctx.locale);
+    const metaText = meta !== undefined ? resolveLocalizedText(meta, ctx.locale) : undefined;
+    const headingLine = sectionHeadingLine(heading, metaText, ctx.width);
     const body = childArray(children)
       .map((child) => ctx.render(child, ctx.width - 2))
       .filter((block) => block.length > 0)
       .join("\n\n");
-    return body.length > 0 ? `${heading}\n${indentBlock(body, "  ")}` : heading;
+    return body.length > 0 ? `${headingLine}\n${indentBlock(body, "  ")}` : headingLine;
   },
 });
 Section.displayName = "Section";
@@ -269,8 +417,6 @@ export interface TableProps {
   className?: string;
 }
 
-const MISSING_MARK = "—";
-
 /** 列 key 唯一、行 cells 不携带未声明 key、空列拒绝——无类型 JS 输入在渲染前同样校验。 */
 function validateTableProps(props: TableProps): void {
   if (!Array.isArray(props.columns) || props.columns.length === 0) {
@@ -344,9 +490,13 @@ export const Table = defineComponent<TableProps>({
               {hasLocator ? (
                 <td>
                   {row.locator ? (
-                    <a className="nre-locator" href={ctx.attemptHref(row.locator)}>
-                      {row.locator}
-                    </a>
+                    ctx.attemptHref ? (
+                      <a className="nre-locator" href={ctx.attemptHref(row.locator)}>
+                        {row.locator}
+                      </a>
+                    ) : (
+                      <span className="nre-locator">{row.locator}</span>
+                    )
                   ) : (
                     <span className="nre-missing">{MISSING_MARK}</span>
                   )}