base-paint 0.3.14 → 0.3.16

package/dist/components/flow-ribbon/attrs.d.ts

@@ -0,0 +1,120 @@
+/** flow-ribbon · **标记契约**（渲染与调用方共用的唯一事实：类名／槽位闭集／形态闭集／入参类型）。
+ *
+ *  这一件落地的是原型墙 `.scratch/ui-组件墙/新件/parts-数据与仪表.mjs` 第 67 件「流向带」的三个形态
+ *  （用户在墙上逐格打分：A 桑基带 4/4/4、C 两条构成轨 4/4/4，B 交叉矩阵为上一轮 4/4/4）：
+ *   · `sankey` 桑基带（左来源／右用途，带宽＝金额）；
+ *   · `matrix` 交叉矩阵（行＝来源，列＝用途）；
+ *   · `rails`  两条构成轨＋中间汇合读数。
+ *  三个形态问的是**同一个问题**——「两张名单之间谁养谁」——只是样本形状不同（带／格／轨），
+ *  所以是**一件的三个形态**，不是三件（契约 §一：形态是骨架，不是地址）。
+ *
+ *  它替掉的错法（原型那一件的 `p` 逐字）：
+ *   · 只给一张来源占比 ＋ 一张用途占比 —— 看不出谁养谁；
+ *   · 拿 `invoice-lines` 那种一条链（总额一路加减到明细）表达多对多 —— 链式表达不了「三笔来源养四类用途」；
+ *   · 拿 `stacked-bar` 那种单层构成条表达两层对应 —— 一条轨说不出「谁汇进谁」。
+ *
+ *  **本件的头号硬口径：两侧同一把尺子。** 原型阶段审查席实测出过两种尺度不统一（历史缺陷，两种都不许再犯）：
+ *   ① 左右两列各自归一（8 000 画 68%、4 460 画 27%）⇒「带宽＝金额」只在自己那一列成立；
+ *   ② 格宽按文字宽度排（`flex: 0 0 auto`）⇒ 占比根本没画出来。
+ *  落地的口径：**一个总额（＝所有流量的和）、一把尺子（每 1% 高／宽＝同一个钱数）、三处几何全从它算**
+ *  （桑基的节点高与带子两端高、矩阵的条长、两条轨的格宽），判据从**印出来的读数**反推带宽比。
+ *
+ *  形态键写在 `FLOW_RIBBON_FORMS`（闭集）：闭集外的值一律 `badInput`（不静默降级——
+ *  降级会让调用方以为自己拿到了另一种骨架）。
+ */
+/** 本件的类名根：全部槽位类名都是 `FLOW_RIBBON_CLASS + '-' + 槽名`。 */
+export declare const FLOW_RIBBON_CLASS = "ilife-block-flow-ribbon";
+/** 槽位闭集（`render.ts`／`style.ts` 与判据都从这里取名字，不各抄一份字面量）。 */
+export declare const FLOW_RIBBON_SLOTS: readonly ["hd", "title", "stamp", "tail", "plot", "lane", "node", "nd-name", "nd-amount", "readout", "readout-hd", "readout-row", "readout-name", "readout-amount", "readout-share", "matrix", "mat-head", "mat-body", "mat-foot", "mat-row", "mat-rowhd", "mat-cell", "cell-bar", "cell-num", "cell-pct", "mat-total", "rails", "rail", "seg", "seg-pct", "rails-list", "rails-col", "rails-hd", "hub", "hub-eq", "hub-net", "legend", "legend-item", "legend-mark", "swatch", "note"];
+export type FlowRibbonSlot = (typeof FLOW_RIBBON_SLOTS)[number];
+/** 槽类的类名（唯一拼法：别处不许再写 `FLOW_RIBBON_CLASS + '-' + …`）。 */
+export declare function flowRibbonSlot(slot: FlowRibbonSlot, prefix?: string): string;
+/** 形态闭集：`sankey` 桑基带 ／ `matrix` 交叉矩阵 ／ `rails` 两条构成轨＋汇合读数。 */
+export declare const FLOW_RIBBON_FORMS: readonly ["sankey", "matrix", "rails"];
+export type FlowRibbonForm = (typeof FLOW_RIBBON_FORMS)[number];
+/** 缺值的写法：**写成 `—`，不许写 0、不许留空**（全仓同一条地板）。矩阵的空格用它。 */
+export declare const FLOW_RIBBON_MISSING = "\u2014";
+/** 钱的缺省单位（不给 `unit` 时用它）。 */
+export declare const FLOW_RIBBON_DEFAULT_UNIT = "\u5143";
+/** 节点之间那条缝（占画布高的百分比）：**只为分得开，不代表任何金额**（口径行照实写这一句）。 */
+export declare const FLOW_RIBBON_GAP_PCT = 2;
+/** 窄容器阈值（px）：**这是本件自己的宽度**（`@container` 判，不判视口）。 */
+export declare const FLOW_RIBBON_NARROW_PX = 620;
+/** 名单上限：来源 1–6 股、用途 1–4 类。 */
+export declare const FLOW_RIBBON_MAX_SOURCES = 6;
+/** 用途那一列的上限（**窄档的约束**：320 档一格只有 60 出头，再多就放不下金额）。 */
+export declare const FLOW_RIBBON_MAX_USES = 4;
+/** 流量条数上限（`来源 × 用途` 的稀疏上界；再多请调用方先归并）。 */
+export declare const FLOW_RIBBON_MAX_LINKS = 24;
+/** 名字长度上限（字符）：名单与控制条一个字都不许被压——长了会在窄档折成好几行。 */
+export declare const FLOW_RIBBON_MAX_NAME_CHARS = 12;
+/** 桑基节点列的最小宽度（px）：两个中文名字 ＋ 一行金额要在里面站得住。 */
+export declare const FLOW_RIBBON_NODE_COL_PX = 112;
+/** 节点列在 320 档的**内宽**（px）：读数能不能放进节点里，按它算（`112 − 内距 12 − 边框 2`）。 */
+export declare const FLOW_RIBBON_NODE_INNER_PX = 98;
+/** 节点读数的字面大小（px）＝`fs-xs` 那一档：估文字宽度按它算（**估宽只许用这一个数**）。 */
+export declare const FLOW_RIBBON_FONT_PX = 12;
+/** 画布的可用高度（px）：数据算出来的那一档被夹在这个区间里。 */
+export declare const FLOW_RIBBON_PLOT_MIN_PX = 200;
+export declare const FLOW_RIBBON_PLOT_MAX_PX = 420;
+/** 一个节点框**放下两行读数**（名字一行 ＋ 金额一行）所需的最小高度（px）：12 × 1.3 × 2 ＋ 内距 6 ≈ 38。 */
+export declare const FLOW_RIBBON_LABEL_MIN_PX = 38;
+/** 构成轨上放得下百分数所需的最小格宽（占总额的百分比）：320 档一格 ≥14% 时约 45px，够写 `100%`。 */
+export declare const FLOW_RIBBON_SEG_MIN_PCT = 14;
+/** 桑基画布的高度（px）：由 `model.ts` 按「最小的一股也要放得下两行读数」算出来，写在画布的行内样式上。 */
+export declare const FLOW_RIBBON_PLOT_VAR = "--flow-ribbon-plot-h";
+/** 一个节点在画布上的顶边（占画布高的百分比）。 */
+export declare const FLOW_RIBBON_TOP_VAR = "--flow-ribbon-t";
+/** 一个节点／一条带子的高（占画布高的百分比）。 */
+export declare const FLOW_RIBBON_HEIGHT_VAR = "--flow-ribbon-h";
+/** 一条带子在左端（来源那一侧）的上下沿。 */
+export declare const FLOW_RIBBON_LANE_L1_VAR = "--flow-ribbon-l1";
+/** 一条带子在左端的下沿。 */
+export declare const FLOW_RIBBON_LANE_L2_VAR = "--flow-ribbon-l2";
+/** 一条带子在右端（用途那一侧）的上沿。 */
+export declare const FLOW_RIBBON_LANE_R1_VAR = "--flow-ribbon-r1";
+/** 一条带子在右端的下沿。 */
+export declare const FLOW_RIBBON_LANE_R2_VAR = "--flow-ribbon-r2";
+/** 矩阵格里的条宽／构成轨里的一格宽（占满格的百分比）。 */
+export declare const FLOW_RIBBON_WIDTH_VAR = "--flow-ribbon-w";
+/** 矩阵格底色往强调色掺的权重（百分比）：**从 token 算出来**，不写死色值。 */
+export declare const FLOW_RIBBON_MIX_VAR = "--flow-ribbon-mix";
+/** 一格在窄档把列名顶在数字前的那个 `data-*`（窄档表转成行，列名靠 `content: attr(...)` 补回）。 */
+export declare const FLOW_RIBBON_USE_ATTR = "data-use";
+/** 一股来源（`sources` 的一项）／一类用途（`uses` 的一项）。 */
+export interface FlowRibbonNode {
+    /** 名字（`工资`／`餐饮`）；**非空**，且至多 `FLOW_RIBBON_MAX_NAME_CHARS` 个字符。 */
+    readonly name: string;
+}
+/** 一笔流量（`links` 的一项）：**它才是这份数据的唯一事实**——来源与用途两边的金额都由它汇总出来。
+ *  「进 ＝ 出」不是调用方要保证的事，是这里算出来的结构事实（同一条链的两端）。 */
+export interface FlowRibbonLink {
+    /** 来源名（必须是 `sources` 里的一个）。 */
+    readonly from: string;
+    /** 用途名（必须是 `uses` 里的一个）。 */
+    readonly to: string;
+    /** 这一笔的金额（**正**的有限数；零金额的那一笔不该上屏——它画出来是一条看不见的带子）。 */
+    readonly amount: number;
+}
+/** 流向带的入参。**三个形态吃同一份数据**（同一条链的三种看法），形态只换骨架、不换口径。 */
+export interface FlowRibbonInput {
+    /** 卡头标题（`钱从哪来、花到哪去`）。 */
+    readonly title: string;
+    /** 来源名单（左列／矩阵行），1–`FLOW_RIBBON_MAX_SOURCES` 股，**顺序＝显示顺序**。 */
+    readonly sources: readonly FlowRibbonNode[];
+    /** 用途名单（右列／矩阵列），1–`FLOW_RIBBON_MAX_USES` 类，**顺序＝显示顺序**。 */
+    readonly uses: readonly FlowRibbonNode[];
+    /** 流量（一笔一项）：两边名单里的名字都要在这里至少出现一次——没流量的名单项画不出高度。 */
+    readonly links: readonly FlowRibbonLink[];
+    /** 卡头里那枚时间窗（`09-01 – 09-24`）；不给＝不出。 */
+    readonly stamp?: string;
+    /** 形态键（闭集，缺省 `sankey`）。 */
+    readonly form?: FlowRibbonForm;
+    /** 钱的单位（缺省 `元`）：只上屏，不参与算数。 */
+    readonly unit?: string;
+    /** 口径行（这一张图怎么读）；不给＝本件按形态写一句自己的口径（那句话里带**同一把尺子的换算**）。 */
+    readonly note?: string;
+    /** 附加类名（空格分隔；逐个过类名正则）。 */
+    readonly extraClass?: string;
+}
+//# sourceMappingURL=attrs.d.ts.map

package/dist/components/flow-ribbon/attrs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attrs.d.ts","sourceRoot":"","sources":["../../../src/components/flow-ribbon/attrs.ts"],"names":[],"mappings":"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"}

package/dist/components/flow-ribbon/attrs.js

@@ -0,0 +1,174 @@
+/** flow-ribbon · **标记契约**（渲染与调用方共用的唯一事实：类名／槽位闭集／形态闭集／入参类型）。
+ *
+ *  这一件落地的是原型墙 `.scratch/ui-组件墙/新件/parts-数据与仪表.mjs` 第 67 件「流向带」的三个形态
+ *  （用户在墙上逐格打分：A 桑基带 4/4/4、C 两条构成轨 4/4/4，B 交叉矩阵为上一轮 4/4/4）：
+ *   · `sankey` 桑基带（左来源／右用途，带宽＝金额）；
+ *   · `matrix` 交叉矩阵（行＝来源，列＝用途）；
+ *   · `rails`  两条构成轨＋中间汇合读数。
+ *  三个形态问的是**同一个问题**——「两张名单之间谁养谁」——只是样本形状不同（带／格／轨），
+ *  所以是**一件的三个形态**，不是三件（契约 §一：形态是骨架，不是地址）。
+ *
+ *  它替掉的错法（原型那一件的 `p` 逐字）：
+ *   · 只给一张来源占比 ＋ 一张用途占比 —— 看不出谁养谁；
+ *   · 拿 `invoice-lines` 那种一条链（总额一路加减到明细）表达多对多 —— 链式表达不了「三笔来源养四类用途」；
+ *   · 拿 `stacked-bar` 那种单层构成条表达两层对应 —— 一条轨说不出「谁汇进谁」。
+ *
+ *  **本件的头号硬口径：两侧同一把尺子。** 原型阶段审查席实测出过两种尺度不统一（历史缺陷，两种都不许再犯）：
+ *   ① 左右两列各自归一（8 000 画 68%、4 460 画 27%）⇒「带宽＝金额」只在自己那一列成立；
+ *   ② 格宽按文字宽度排（`flex: 0 0 auto`）⇒ 占比根本没画出来。
+ *  落地的口径：**一个总额（＝所有流量的和）、一把尺子（每 1% 高／宽＝同一个钱数）、三处几何全从它算**
+ *  （桑基的节点高与带子两端高、矩阵的条长、两条轨的格宽），判据从**印出来的读数**反推带宽比。
+ *
+ *  形态键写在 `FLOW_RIBBON_FORMS`（闭集）：闭集外的值一律 `badInput`（不静默降级——
+ *  降级会让调用方以为自己拿到了另一种骨架）。
+ */
+/** 本件的类名根：全部槽位类名都是 `FLOW_RIBBON_CLASS + '-' + 槽名`。 */
+export const FLOW_RIBBON_CLASS = 'ilife-block-flow-ribbon';
+/** 槽位闭集（`render.ts`／`style.ts` 与判据都从这里取名字，不各抄一份字面量）。 */
+export const FLOW_RIBBON_SLOTS = [
+    /** 卡头那一排：标题 ＋ 时间窗 ＋ 总额。 */
+    'hd',
+    /** 卡头标题（`钱从哪来、花到哪去`）。 */
+    'title',
+    /** 卡头里那枚时间窗（`09-01 – 09-24`）；不给＝不出。 */
+    'stamp',
+    /** 卡头右端那句**本件算出来**的总额（`共 11 600 元`）。 */
+    'tail',
+    /* ── 形态 `sankey` ── */
+    /** 桑基画布（`role="img"`；节点与带子都是绝对定位，坐标是算出来的百分比）。 */
+    'plot',
+    /** 一条带子（**无文字的图形**：色走强调色系淡洗，`clip-path` 多边形由 `model.ts` 算）。 */
+    'lane',
+    /** 一个节点（左列来源／右列用途；高＝金额，两列同一把尺子）。 */
+    'node',
+    /** 节点里的名字。 */
+    'nd-name',
+    /** 节点里的金额（读数字面，`tabular-nums`）。 */
+    'nd-amount',
+    /* ── 三形态共用的「读数名单」── */
+    'readout',
+    /** 名单的小标题（`装不进格里的读数 · 2 条`）——**只在真有读数搬下来时才出**。 */
+    'readout-hd',
+    /** 名单的一行（名字 ＋ 金额 ＋ 占比）。 */
+    'readout-row',
+    /** 名单行里的名字（左列那个色块由 `swatch` 给）。 */
+    'readout-name',
+    /** 名单行里的金额（**永不 `…` 截断**）。 */
+    'readout-amount',
+    /** 名单行里的占比。 */
+    'readout-share',
+    /* ── 形态 `matrix` ── */
+    /** 矩阵的表（`role="img"`，无障碍名逐格读出）。 */
+    'matrix',
+    /** 表头行（`<thead>`）。 */
+    'mat-head',
+    /** 表体（`<tbody>`）。 */
+    'mat-body',
+    /** 合计行（`<tfoot>`）。 */
+    'mat-foot',
+    /** 矩阵的一行。 */
+    'mat-row',
+    /** 行头（`<th>`：来源名 ＋ 本行合计）。 */
+    'mat-rowhd',
+    /** 一格（`<td>`）。 */
+    'mat-cell',
+    /** 格里的条（**无文字的图形**：宽＝这一格 ÷ 全表最大格）。 */
+    'cell-bar',
+    /** 格里的金额。 */
+    'cell-num',
+    /** 格里的百分数（这一格占总额）。 */
+    'cell-pct',
+    /** 合计行里的一格（`<td>`）。 */
+    'mat-total',
+    /* ── 形态 `rails` ── */
+    /** 两条构成轨那一块（`role="img"`）。 */
+    'rails',
+    /** 一条轨（满宽＝总额）。 */
+    'rail',
+    /** 轨里的一格（**宽＝这一格占总额的比例**，同一总额、两条轨各自拉满 100%）。 */
+    'seg',
+    /** 格里的百分数（**算得出放得下才出**；放不下的那几格的读数在下面名单里）。 */
+    'seg-pct',
+    /** 轨下那两栏名单（来源／用途各一栏）。 */
+    'rails-list',
+    /** 名单的一栏。 */
+    'rails-col',
+    /** 一栏的小标题（`钱从哪来 · 3 股`）。 */
+    'rails-hd',
+    /** 两轨中间那块汇合读数（进 ＝ 出）。 */
+    'hub',
+    /** 汇合那块里的等式（`进 11 600 ＝ 出 11 600`）。 */
+    'hub-eq',
+    /** 汇合那块里的净额（`净 +0`）。 */
+    'hub-net',
+    /* ── 三形态共用 ── */
+    /** 图例（形 ＋ 字）。 */
+    'legend',
+    /** 图例的一项。 */
+    'legend-item',
+    /** 图例左端那枚色块（纯装饰；`is-s1`…`is-s6` 给来源那一档深浅）。 */
+    'legend-mark',
+    /** 点名的色块（名单行左端那枚，与图例同一档）。 */
+    'swatch',
+    /** 脚注一句人话（口径）。 */
+    'note',
+];
+/** 槽类的类名（唯一拼法：别处不许再写 `FLOW_RIBBON_CLASS + '-' + …`）。 */
+export function flowRibbonSlot(slot, prefix = 'ilife-') {
+    return prefix + 'block-flow-ribbon-' + slot;
+}
+/** 形态闭集：`sankey` 桑基带 ／ `matrix` 交叉矩阵 ／ `rails` 两条构成轨＋汇合读数。 */
+export const FLOW_RIBBON_FORMS = ['sankey', 'matrix', 'rails'];
+/** 缺值的写法：**写成 `—`，不许写 0、不许留空**（全仓同一条地板）。矩阵的空格用它。 */
+export const FLOW_RIBBON_MISSING = '—';
+/** 钱的缺省单位（不给 `unit` 时用它）。 */
+export const FLOW_RIBBON_DEFAULT_UNIT = '元';
+/** 节点之间那条缝（占画布高的百分比）：**只为分得开，不代表任何金额**（口径行照实写这一句）。 */
+export const FLOW_RIBBON_GAP_PCT = 2;
+/** 窄容器阈值（px）：**这是本件自己的宽度**（`@container` 判，不判视口）。 */
+export const FLOW_RIBBON_NARROW_PX = 620;
+/** 名单上限：来源 1–6 股、用途 1–4 类。 */
+export const FLOW_RIBBON_MAX_SOURCES = 6;
+/** 用途那一列的上限（**窄档的约束**：320 档一格只有 60 出头，再多就放不下金额）。 */
+export const FLOW_RIBBON_MAX_USES = 4;
+/** 流量条数上限（`来源 × 用途` 的稀疏上界；再多请调用方先归并）。 */
+export const FLOW_RIBBON_MAX_LINKS = 24;
+/** 名字长度上限（字符）：名单与控制条一个字都不许被压——长了会在窄档折成好几行。 */
+export const FLOW_RIBBON_MAX_NAME_CHARS = 12;
+/** 桑基节点列的最小宽度（px）：两个中文名字 ＋ 一行金额要在里面站得住。 */
+export const FLOW_RIBBON_NODE_COL_PX = 112;
+/** 节点列在 320 档的**内宽**（px）：读数能不能放进节点里，按它算（`112 − 内距 12 − 边框 2`）。 */
+export const FLOW_RIBBON_NODE_INNER_PX = 98;
+/** 节点读数的字面大小（px）＝`fs-xs` 那一档：估文字宽度按它算（**估宽只许用这一个数**）。 */
+export const FLOW_RIBBON_FONT_PX = 12;
+/** 画布的可用高度（px）：数据算出来的那一档被夹在这个区间里。 */
+export const FLOW_RIBBON_PLOT_MIN_PX = 200;
+export const FLOW_RIBBON_PLOT_MAX_PX = 420;
+/** 一个节点框**放下两行读数**（名字一行 ＋ 金额一行）所需的最小高度（px）：12 × 1.3 × 2 ＋ 内距 6 ≈ 38。 */
+export const FLOW_RIBBON_LABEL_MIN_PX = 38;
+/** 构成轨上放得下百分数所需的最小格宽（占总额的百分比）：320 档一格 ≥14% 时约 45px，够写 `100%`。 */
+export const FLOW_RIBBON_SEG_MIN_PCT = 14;
+/* ── 行内自定义属性（**本件自己的名字**，不占 `--ilife-*` 那个皮肤命名空间）────────────
+ *  为什么不用 `--ilife-*`：那是皮肤 token 的空间（名单住 `skin/contract.ts`），件里塞私有名
+ *  会在皮肤矩阵判据里读成「名单外的 token」。先例：`cash-waterline` 的 `--cash-waterline-*`。 */
+/** 桑基画布的高度（px）：由 `model.ts` 按「最小的一股也要放得下两行读数」算出来，写在画布的行内样式上。 */
+export const FLOW_RIBBON_PLOT_VAR = '--flow-ribbon-plot-h';
+/** 一个节点在画布上的顶边（占画布高的百分比）。 */
+export const FLOW_RIBBON_TOP_VAR = '--flow-ribbon-t';
+/** 一个节点／一条带子的高（占画布高的百分比）。 */
+export const FLOW_RIBBON_HEIGHT_VAR = '--flow-ribbon-h';
+/** 一条带子在左端（来源那一侧）的上下沿。 */
+export const FLOW_RIBBON_LANE_L1_VAR = '--flow-ribbon-l1';
+/** 一条带子在左端的下沿。 */
+export const FLOW_RIBBON_LANE_L2_VAR = '--flow-ribbon-l2';
+/** 一条带子在右端（用途那一侧）的上沿。 */
+export const FLOW_RIBBON_LANE_R1_VAR = '--flow-ribbon-r1';
+/** 一条带子在右端的下沿。 */
+export const FLOW_RIBBON_LANE_R2_VAR = '--flow-ribbon-r2';
+/** 矩阵格里的条宽／构成轨里的一格宽（占满格的百分比）。 */
+export const FLOW_RIBBON_WIDTH_VAR = '--flow-ribbon-w';
+/** 矩阵格底色往强调色掺的权重（百分比）：**从 token 算出来**，不写死色值。 */
+export const FLOW_RIBBON_MIX_VAR = '--flow-ribbon-mix';
+/** 一格在窄档把列名顶在数字前的那个 `data-*`（窄档表转成行，列名靠 `content: attr(...)` 补回）。 */
+export const FLOW_RIBBON_USE_ATTR = 'data-use';
+//# sourceMappingURL=attrs.js.map

package/dist/components/flow-ribbon/attrs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attrs.js","sourceRoot":"","sources":["../../../src/components/flow-ribbon/attrs.ts"],"names":[],"mappings":"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"}

package/dist/components/flow-ribbon/fields.d.ts

@@ -0,0 +1,57 @@
+import { type FlowRibbonLink, type FlowRibbonNode } from './attrs.js';
+/** 机器数 → 屏上的字：整数走千分位；小数最多两位（末尾的 0 去掉）；指数记法原样（**不分组**）。 */
+export declare function fmtAmount(n: number): string;
+/** 占比 → 屏上的字（一位小数：`27.4%`；整数不写 `.0`）。 */
+export declare function fmtPct(pct: number): string;
+/** 一个读数：名字 ＋ 金额 ＋ 它占总额的比例。 */
+export interface FlowRibbonReadout {
+    /** 名字。 */
+    readonly name: string;
+    /** 金额（机器数）。 */
+    readonly amount: number;
+    /** 金额屏上写法（千分位；**永不 `…` 截断**）。 */
+    readonly amountText: string;
+    /** 占总额的百分比（0–100，一位小数）。 */
+    readonly sharePct: number;
+    /** 占比屏上写法（`27.4%`）。 */
+    readonly shareText: string;
+}
+/** 一位小数。 */
+export declare function round1(n: number): number;
+/** 保留两位小数（几何用的百分比；**印在屏上的占比走 `fmtPct` 的一位小数**，两件事不混）。 */
+export declare function round2(n: number): number;
+/** 夹进 0–100：带子两端的上下沿是**累加**出来的，四舍五入到两位小数后可能比 100 多出 0.01%
+ *  （最后一股的读数只影响 0.0003px，可不夹就得让「百分比恒在 0–100」这条不变量破功）。 */
+export declare function clampPct(n: number): number;
+/** 一笔流量占总额的百分比（一位小数）。 */
+export declare function shareOf(amount: number, total: number): string;
+/** 一份名单 ＋ 流量 → 读数（金额由流量汇总；名字顺序＝调用方给的显示顺序）。 */
+export declare function readoutsOf(names: readonly FlowRibbonNode[], amounts: readonly number[], total: number): readonly FlowRibbonReadout[];
+/** 一股／一类在某一列里的金额（由流量汇总；调用方不给金额，故不存在「名单与金额对不上」这种事）。 */
+export declare function sumBy(nodes: readonly FlowRibbonNode[], links: readonly FlowRibbonLink[], side: 'from' | 'to'): readonly number[];
+/** 一个字符串在 `FLOW_RIBBON_FONT_PX` 字号下大约占多少像素。 */
+export declare function estimatePx(text: string): number;
+/** 入参表以外的键一律拒（先例：`relation-picker`／`kanban-columns` 的同名小件）：
+ *  写错的键静默吞掉，调用方会以为自己设上了——那是"看不见的错"。
+ *
+ *  **两条都会被查到**（只走 `Object.keys` 会漏一半）：
+ *   · `Object.getOwnPropertyNames` —— 自有的**全部**键，含**不可枚举**的；
+ *   · `for…in` —— 走**整条原型链**（`Object.create({ zzUnknown: 1 })` 那种继承来的键就是这一路）。 */
+export declare function assertKeys(raw: Record<string, unknown>, allowed: readonly string[], field: string): void;
+/** 必须是有限数（`NaN`／`±Infinity` 一律拒）**且量级可读**（见 `reqMagnitude()`）。 */
+export declare function reqFinite(value: unknown, field: string): number;
+/** 一份名单（来源或用途）：1–上限项、逐项是 `{ name }`、名字不重名（重名会让「谁养谁」对不上一股）。 */
+export declare function reqNodes(value: unknown, field: string, max: number): readonly FlowRibbonNode[];
+/** 流量：逐项 `{ from, to, amount }`，名字必须在两份名单里，金额 > 0，同一对 `from → to` 只许一笔。 */
+export declare function reqLinks(value: unknown, sources: readonly FlowRibbonNode[], uses: readonly FlowRibbonNode[], max: number): readonly FlowRibbonLink[];
+/** 来源名单（1–6 股）。 */
+export declare function reqSources(value: unknown): readonly FlowRibbonNode[];
+/** 用途名单（1–4 类）。 */
+export declare function reqUses(value: unknown): readonly FlowRibbonNode[];
+/** 必填文本：非空串**且不是全空白**（全空白的标题会在屏上留一块空白，那是"看得到的错"）。 */
+export declare function reqRealText(value: unknown, field: string): string;
+/** 可选文本：空串＝未给（与全层 `optText` 同口径）；**全空白＝拒**。 */
+export declare function optRealText(value: unknown, field: string): string | undefined;
+/** 可选附加类名（口径住 `shared/validate.ts`，这里只是把字段名接上）。 */
+export declare function optClass(value: unknown): string | undefined;
+//# sourceMappingURL=fields.d.ts.map

package/dist/components/flow-ribbon/fields.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fields.d.ts","sourceRoot":"","sources":["../../../src/components/flow-ribbon/fields.ts"],"names":[],"mappings":"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"}

package/dist/components/flow-ribbon/fields.js

@@ -0,0 +1,242 @@
+/** flow-ribbon · **入参小件**（格式化与校验；三个形态共用同一批）。
+ *
+ *  为什么独立成件：`model.ts` 里「一把尺子怎么算」已经够长，再叠这批小件就过本包的行数告警线
+ *  （350 行／LF 口径，见 `packages/base-render/AGENTS.md`）。分开之后：
+ *   · **一个规矩只有一处**：金额怎么写、名字与名单怎么校验、流量怎么对上名单，都只在本文件里；
+ *   · **没有环**：本文件只依赖 `attrs.ts` 与 `shared/validate.ts`，`model.ts` 单向依赖它。
+ *
+ *  报错句的口径（别处也会读它）：每句都点名**路径**（`flow-ribbon: input.links[2].from`）与**为什么**——
+ *  调用方按句自证，皮肤矩阵判据也按句补样例（见 `test/皮肤矩阵.test.mjs` 的 `repairOnce`）。
+ */
+import { assertPlainObject, badInput, optExtraClass, optText, reqText } from '../shared/validate.js';
+import { FLOW_RIBBON_FONT_PX, FLOW_RIBBON_MAX_NAME_CHARS, FLOW_RIBBON_MAX_SOURCES, FLOW_RIBBON_MAX_USES, } from './attrs.js';
+/* ── 格式化 ─────────────────────────────────────────────────────── */
+/** 千分位：每三位插一个逗号（`11600` → `11,600`）——**与原型那一件同款**（原型印的就是 `8,000`；
+ *  自算、不依赖 locale：同一入参在任何机器上排一样，判据才断得准）。 */
+function group(s) {
+    let out = '';
+    for (let i = 0; i < s.length; i += 1) {
+        if (i > 0 && (s.length - i) % 3 === 0)
+            out += ',';
+        out += s[i];
+    }
+    return out;
+}
+/** 大数（`|n| ≥ 1e21`）会长成指数记法（`1e+21`）：那种串**一个分组都不能插**——
+ *  插进去就成了「1.797,693,134,862,315,7e+308」这种读不出来的东西。指数记法一律由这里收口，
+ *  统一写成 `1.8e+21` 这种干净形状（先例：`scatter-fit`／`cash-waterline` 的同名小件）。 */
+function plain(n) {
+    const s = String(n);
+    if (!/[eE]/.test(s))
+        return s;
+    return n.toExponential(2).replace(/\.?0+e/, 'e');
+}
+/** 机器数 → 屏上的字：整数走千分位；小数最多两位（末尾的 0 去掉）；指数记法原样（**不分组**）。 */
+export function fmtAmount(n) {
+    const p = plain(n);
+    if (/[eE]/.test(p))
+        return p;
+    if (Number.isInteger(n))
+        return group(p);
+    const rounded = Math.round(n * 100) / 100;
+    const s = String(rounded);
+    const dot = s.indexOf('.');
+    return group(s.slice(0, dot)) + s.slice(dot);
+}
+/** 占比 → 屏上的字（一位小数：`27.4%`；整数不写 `.0`）。 */
+export function fmtPct(pct) {
+    const r = Math.round(pct * 10) / 10;
+    return (Number.isInteger(r) ? String(r) : r.toFixed(1)) + '%';
+}
+/** 一位小数。 */
+export function round1(n) {
+    return Math.round(n * 10) / 10;
+}
+/** 保留两位小数（几何用的百分比；**印在屏上的占比走 `fmtPct` 的一位小数**，两件事不混）。 */
+export function round2(n) {
+    return Math.round(n * 100) / 100;
+}
+/** 夹进 0–100：带子两端的上下沿是**累加**出来的，四舍五入到两位小数后可能比 100 多出 0.01%
+ *  （最后一股的读数只影响 0.0003px，可不夹就得让「百分比恒在 0–100」这条不变量破功）。 */
+export function clampPct(n) {
+    return Math.min(100, Math.max(0, round2(n)));
+}
+/** 一笔流量占总额的百分比（一位小数）。 */
+export function shareOf(amount, total) {
+    return fmtPct(round1(amount / total * 100));
+}
+/** 一份名单 ＋ 流量 → 读数（金额由流量汇总；名字顺序＝调用方给的显示顺序）。 */
+export function readoutsOf(names, amounts, total) {
+    return names.map((node, i) => {
+        const amount = amounts[i];
+        const sharePct = round1(amount / total * 100);
+        return { name: node.name, amount, amountText: fmtAmount(amount), sharePct, shareText: fmtPct(sharePct) };
+    });
+}
+/** 一股／一类在某一列里的金额（由流量汇总；调用方不给金额，故不存在「名单与金额对不上」这种事）。 */
+export function sumBy(nodes, links, side) {
+    return nodes.map((node) => links.reduce((acc, l) => (l[side] === node.name ? acc + l.amount : acc), 0));
+}
+/* ── 估宽（只在桑基那一个地方用：读数放不放得进节点框） ────────────────
+ *  口径：按 `FLOW_RIBBON_FONT_PX` 估——中日韩字符算一个全角（＝字号），其余算 0.6 个字号。
+ *  **估宽只用来决定「放框里还是搬到下面名单里」**，从不参与坐标计算：估错一个像素也不会画出错的图。 */
+/** 一个字符串在 `FLOW_RIBBON_FONT_PX` 字号下大约占多少像素。 */
+export function estimatePx(text) {
+    let units = 0;
+    for (const ch of text)
+        units += /[\u2e80-\u9fff\uff00-\uffef\u3000-\u303f]/.test(ch) ? 1 : 0.6;
+    return units * FLOW_RIBBON_FONT_PX;
+}
+/* ── 数 ─────────────────────────────────────────────────────────── */
+/** 入参表以外的键一律拒（先例：`relation-picker`／`kanban-columns` 的同名小件）：
+ *  写错的键静默吞掉，调用方会以为自己设上了——那是"看不见的错"。
+ *
+ *  **两条都会被查到**（只走 `Object.keys` 会漏一半）：
+ *   · `Object.getOwnPropertyNames` —— 自有的**全部**键，含**不可枚举**的；
+ *   · `for…in` —— 走**整条原型链**（`Object.create({ zzUnknown: 1 })` 那种继承来的键就是这一路）。 */
+export function assertKeys(raw, allowed, field) {
+    const bad = [];
+    const note = (key) => {
+        if (!allowed.includes(key) && !bad.includes(key))
+            bad.push(key);
+    };
+    for (const key of Object.getOwnPropertyNames(raw))
+        note(key);
+    for (const key in raw)
+        note(key);
+    if (bad.length > 0) {
+        badInput(field + ' 里没有 `' + bad.join('`／`') + '` 这个键（入参表以外的键一律拒：写错的键静默吞掉会让'
+            + '调用方以为自己设上了；继承来的与不可枚举的键同样算）');
+    }
+}
+/** 可加性的量级上界（`Number.MAX_VALUE ÷ 2`）。**判据是「相加会不会溢出」，不是「好不好读」**：
+ *  `|a| + |b| > Number.MAX_VALUE` 那一刻就是双精度的 `Infinity`——总额、占比、带子两端全成 `Infinity`／`NaN`，
+ *  屏上写出 `1e+308` 这种读不出来的数。故 `1e21`／`1e-7`（十进制写法与指数写法的分界那一档）**照旧合法**。 */
+const FLOW_RIBBON_MAGNITUDE_MAX = Number.MAX_VALUE / 2;
+/** 读数的量级闸（上界住 `FLOW_RIBBON_MAGNITUDE_MAX`，那一档的数是**有限的**：`Number.isFinite(1e308)` 为真，
+ *  可它一算就溢出，屏上写出的是 `1e+308` 这种读不出来的东西——调用方以为给了一笔真读数，拿到的是张坏图）。 */
+function reqMagnitude(n, field) {
+    if (Math.abs(n) > FLOW_RIBBON_MAGNITUDE_MAX) {
+        badInput(field + ' 的量级太大：两笔同量级的读数相加就溢出成 `Infinity`'
+            + '（图上会写出 `1e+308` 这类读不出来的数；读数至多到 `Number.MAX_VALUE ÷ 2` 那一档）');
+    }
+    return n;
+}
+/** 必须是有限数（`NaN`／`±Infinity` 一律拒）**且量级可读**（见 `reqMagnitude()`）。 */
+export function reqFinite(value, field) {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        badInput(field + ' 必须是有限数（`NaN`／`Infinity` 这类"写不成数的东西"一律拒）');
+    }
+    return reqMagnitude(value, field);
+}
+/** 有限数且 `> 0`（一笔流量、一股来源的金额都得是正的：零或负数画出来是一根看不见的带子）。 */
+function reqPositive(value, field) {
+    const n = reqFinite(value, field);
+    if (n <= 0)
+        badInput(field + ' 必须大于 0');
+    return n;
+}
+/** 名字：非空串、不是全空白、不超过 `FLOW_RIBBON_MAX_NAME_CHARS` 个字符。 */
+function reqName(value, field) {
+    const text = reqText(value, field);
+    if (text.trim() === '')
+        badInput(field + ' 必须是真正的文本（全空白不算）');
+    if (text.length > FLOW_RIBBON_MAX_NAME_CHARS) {
+        badInput(field + ' 至多 ' + String(FLOW_RIBBON_MAX_NAME_CHARS)
+            + ' 个字符（窄档的框只有那么宽，更长的名字会折成好几行、把金额顶出画布）');
+    }
+    return text;
+}
+/** 一份名单（来源或用途）：1–上限项、逐项是 `{ name }`、名字不重名（重名会让「谁养谁」对不上一股）。 */
+export function reqNodes(value, field, max) {
+    if (!Array.isArray(value) || value.length === 0) {
+        badInput(field + ' 必须是非空数组（至少要 1 个；至少要 2 个才谈得上"谁养谁"）');
+    }
+    if (value.length > max) {
+        badInput(field + ' 最多 ' + String(max) + ' 个（再多窄档一格里放不下读数，请调用方先归并）');
+    }
+    const seen = new Set();
+    return value.map((item, i) => {
+        const at = field + '[' + String(i) + ']';
+        assertPlainObject(item, at);
+        assertKeys(item, ['name'], at);
+        const name = reqName(item.name, at + '.name');
+        if (seen.has(name))
+            badInput(at + '.name 与前面某一项重名（`' + name + '`）：一股只能出现一次，否则汇总会算两遍');
+        seen.add(name);
+        return { name };
+    });
+}
+/** 流量：逐项 `{ from, to, amount }`，名字必须在两份名单里，金额 > 0，同一对 `from → to` 只许一笔。 */
+export function reqLinks(value, sources, uses, max) {
+    if (!Array.isArray(value) || value.length === 0) {
+        badInput('flow-ribbon: input.links 必须是非空数组（一笔流量都没有就画不出流向）');
+    }
+    if (value.length > max) {
+        badInput('flow-ribbon: input.links 最多 ' + String(max) + ' 笔（再多请调用方先归并到更少的来源／用途）');
+    }
+    const sourceNames = sources.map((s) => s.name);
+    const useNames = uses.map((u) => u.name);
+    const seen = new Set();
+    const links = value.map((item, i) => {
+        const at = 'flow-ribbon: input.links[' + String(i) + ']';
+        assertPlainObject(item, at);
+        const raw = item;
+        assertKeys(raw, ['from', 'to', 'amount'], at);
+        const from = reqName(raw.from, at + '.from');
+        const to = reqName(raw.to, at + '.to');
+        if (!sourceNames.includes(from)) {
+            badInput(at + '.from 必须是 input.sources 里的名字之一（拿到 `' + from + '`）');
+        }
+        if (!useNames.includes(to)) {
+            badInput(at + '.to 必须是 input.uses 里的名字之一（拿到 `' + to + '`）');
+        }
+        const key = from + '\u0000' + to;
+        if (seen.has(key))
+            badInput(at + ' 与前面某一笔是同一对（`' + from + ' → ' + to + '`）：两笔请先并成一笔');
+        seen.add(key);
+        return { from, to, amount: reqPositive(raw.amount, at + '.amount') };
+    });
+    /* **名单里每一项都得真有流量**：没有流量的那一项高度是 0——按 0 画是一根看不见的线，
+     *  按 1 画是编数据。两种都不许，故一律拒（不静默降级）。 */
+    for (const name of sourceNames) {
+        if (!links.some((l) => l.from === name)) {
+            badInput('flow-ribbon: input.sources 里的 `' + name + '` 一笔流量都没有'
+                + '（高度会是 0，画出来是一条看不见的线）——请把它从名单里去掉或补上流量');
+        }
+    }
+    for (const name of useNames) {
+        if (!links.some((l) => l.to === name)) {
+            badInput('flow-ribbon: input.uses 里的 `' + name + '` 一笔流量都没有'
+                + '（高度会是 0，画出来是一条看不见的线）——请把它从名单里去掉或补上流量');
+        }
+    }
+    return links;
+}
+/** 来源名单（1–6 股）。 */
+export function reqSources(value) {
+    return reqNodes(value, 'flow-ribbon: input.sources', FLOW_RIBBON_MAX_SOURCES);
+}
+/** 用途名单（1–4 类）。 */
+export function reqUses(value) {
+    return reqNodes(value, 'flow-ribbon: input.uses', FLOW_RIBBON_MAX_USES);
+}
+/** 必填文本：非空串**且不是全空白**（全空白的标题会在屏上留一块空白，那是"看得到的错"）。 */
+export function reqRealText(value, field) {
+    const text = reqText(value, field);
+    if (text.trim() === '')
+        badInput(field + ' 必须是真正的文本（全空白不算）');
+    return text;
+}
+/** 可选文本：空串＝未给（与全层 `optText` 同口径）；**全空白＝拒**。 */
+export function optRealText(value, field) {
+    const text = optText(value, field);
+    if (text !== undefined && text.trim() === '')
+        badInput(field + ' 必须是真正的文本（全空白不算）');
+    return text;
+}
+/** 可选附加类名（口径住 `shared/validate.ts`，这里只是把字段名接上）。 */
+export function optClass(value) {
+    return optExtraClass(value, 'flow-ribbon: input.extraClass');
+}
+//# sourceMappingURL=fields.js.map