base-paint 0.3.13 → 0.3.15

package/dist/controls.d.ts

@@ -1,163 +1,9 @@
-/** base-paint/controls：#76 控件层运行时（契约 §3.3／§6.3）。
+/** **薄转出**（目录化批次⑤之后本件不再住实现）。
  *
- * 实施冻结面 44 条里 #76 的 13 条 `pending`（10 个运行时出口 ＋ 3 个类型出口）：
- * `copyText`／`createCopyRuntime`／`bindCopyAction`／`buildSharedHelpersJs`／
- * `renderToast`／`createToastController`／`renderActionBar`／`renderStatusBadge`／
- * `renderEmptyState`／`renderErrorReceipt`。签名逐字取 `src/spec/controls.ts`，本文件不改任何冻结值。
- *
- * 三条硬边界（逐条对齐 §3.3／§6.3，违反即红）：
- *  1. **无宿主 ≠ 无浏览器**（C-1）：本层不依赖 DSH 宿主注入（无宿主 DOM 容器、无宿主全局），
- *     浏览器能力一律经**显式端口**（`CopyPorts`／`ToastHostPort`／`CopyActionHostPort`）传入；
- *  2. **模块代码不得触碰 DOM**（C-8／AC-7）：本文件（编译进 `dist/controls.js`）的**代码**里不出现
- *     `document.`／`window.`／`navigator.`——DOM 只允许出现在 `buildSharedHelpersJs` **产出的 JS 文本**里
- *     （`SHARED_HELPERS_JS_RULE.domAllowed = true`），由 §6.3 追加验收的 dist 扫描断言钉死；
- *  3. **零内联脚本**（C-2）：渲染出的按钮只带 `ACTION_ID_ATTR` 与 `DEFAULT_DATA_ATTR`，
- *     激活一律走 `bindCopyAction`（事件委派），产出 JS 必须是**经典 script** 作用域可跑的 IIFE。
- *
- * 文档未规定处的取值（本文显式记账，不留暗猜；契约 §3.3「文档无规定」项）：
- *  - 各控件 HTML 结构／类名细节 → 只冻结「`ilife-` 前缀 ＋ `CONTROL_STYLE_SECTIONS` 命名空间」；
- *    逐区尺寸／色值 owner #75，本文件**不产**任何样式常量（数值一律读 `ACTION_BAR_DEFAULTS` 等冻结常量）；
- *  - `copyText` 非空串失败的 `reason` → 通道 2 返回假值 = `'fallback-failed'`／通道 2 **同步抛错** =
- *    `'fallback-threw'`（只冻结了空串短路的 `'empty'`；两通道皆失败一律**不抛错**，§3.3）；
- *  - `copyText` 的 toast 挂载与回调**先后** → 先挂反馈（失败徽章恒在，不被回调异常吞掉），再回调一次；
- *  - `copyText('', ports)` 的判定**次序** → 先校验 `ports`（非法即 `bad-input`）再判空串短路，即
- *    `copyText('', null)` 抛 `bad-input` 而非返回 `reason:'empty'`（次序文档无规定，本文定死）；
- *  - `renderToast` 的 `actions` 数量上限 → 不截断（旧层 `slice(0, 2)` 未进冻结面）；
- *  - `renderToast` 非法 `badge.type` → 回落 `'ok'`（旧层口径）；
- *  - `renderActionBar` 的 `CopyButtonInput.text` 缺席 → 仍渲染按钮、不写 `DEFAULT_DATA_ATTR`（binder 靠
- *    `readDataText → undefined` 跳过）；`text === ''` → 仍写 `data-t=""`（binder 送进空串短路，无反馈）；
- *    场景按钮 `kind` 取冻结 `ACTION_BAR_KINDS` **全量**（含 `ghost`），不以 §3.3 表格的「primary／red」为限；
- *    `format` 不参与渲染（序列化归 #77）；
- *  - `renderActionBar` 的 `CopyButtonInput.formats`（#247 三格式形态）→ 按钮只开合菜单、**不写** `data-t`，
- *    菜单三项各写自己的 `data-t`（键取 `COPY_FORMATS`，值＝该格式已序列化文本）；菜单项的
- *    `data-action-id` **留空**（三颗逐字不同的 id 与「同次渲染内唯一」口径不合，见
- *    `CopyButtonInput.formats` 注释）；`formats` 与 `text` 同给 → `bad-input`；
- *    `formats` 缺某个格式／非字符串 → `bad-input`；`hints` 非三个串 → `bad-input`；
- *    菜单的开合／点外收起／选中后按该项 `data-t` 复制并报所选格式 → 归 helpers 运行时的委派；
- *  - `renderStatusBadge` 的 `text === ''` → 视为缺省（旧层口径）；非法 `status` 降级 `'empty'`（冻结语义）；
- *  - `renderEmptyState` 的 `actionHtml` → **受信 HTML 透传**（契约同口径，调用方负责其内容安全），可含
- *    内联 `onclick`；「零注入面」只约束 base-paint **自产**标记，不约束调用方透传的受信片段；
- *  - helpers JS 的反馈栈容量 → 恒取冻结 `TOAST_DEFAULTS.maxStack`／`mobileMaxStack`（按视口），**不读**
- *    静态 `renderToast` 产出的 `data-max`（后者供页面自建 `createToastController` 读取，两栈互不相干）；
- *  - `renderErrorReceipt` 的 `retryPrompt` → 修正重试按钮的**文案**（缺省 `修正重试`）；该按钮**不带**
- *    `ACTION_ID_ATTR`——冻结输入面没有 retry actionId，不得自造 id（§6.3 红线 8），绑定归调用方；
- *  - `copyText` 判定通道 2 成功用**真值**（旧层 `_fbCopy(s) ? ok() : fail()` 同口径）；对布尔返回值
- *    与 `=== true` 等价，只影响调用方返回非布尔真值的情形；
- *  - **「≤820px 收窄为 3」是页面运行时行为，不是模块行为**（FX-76-2 总架构师裁定）：模块侧
- *    `createToastController` 保持**宿主无关**（AC-7 不变，不读任何浏览器全局）；收窄由**页面侧**
- *    `buildSharedHelpersJs` 的**产出文本**读 `matchMedia('(max-width: mobileMaxPx)')` 承担
- *    （`domAllowed`），或由调用方经 `ToastInput.maxStack` 显式施加。旧层 `window.matchMedia`
- *    （`base.js:96`）本就是页面侧代码。两侧分工见契约 §3.3「toast 移动端收窄的分工（FX-76-2）」。
+ *  为什么留着：`src/blocks.ts`／`src/docShell.ts`／`src/help.ts`／`src/contract.ts` 等
+ *  （其中两件在并行席位的在途写集里）按 `./controls.js` 取件，`dist/controls.js` 也是既有产物路径。
+ *  留一层转出＝它们零改动；出口名与改前逐名相同（13 个）。
+ *  实现住 `src/components/controls/**`；等引用迁走即可删本件。
  */
-import type { BindCopyAction, BuildSharedHelpersJs, CopyPorts, CopyRuntime, CopyText, ControlsErrorCode, RenderActionBar, RenderEmptyState, RenderErrorReceipt, RenderStatusBadge, RenderToast, ToastController, ToastHostPort, ToastIcon } from './spec/index.js';
-/** 控件层错误。**不**从 `src/index.ts` 导出：`SPEC_FROZEN_SURFACE` 44 条内无该运行时条目，
- *  调用方按 `name === 'ControlsError'` ＋ `code` 判定（与 `fillTemplate` 的 `TemplateError` 同口径）。 */
-export declare class ControlsError extends Error {
-    readonly code: ControlsErrorCode;
-    constructor(code: ControlsErrorCode, message: string);
-}
-/** 图标字形：`TOAST_ICONS` 是**冻结的枚举名**（不是字形），字形属文档未规定项（旧层 `base.js:74` 同值）。
- *  **导出（#154）**：区块层 B-12 的「页内静态提示」形态要把同一个图标放进浅色块里，
- *  字形只此一份（`blocks.ts` 引用本表，不另抄）；本表**不进** `src/index.ts` 出口面。 */
-export declare const TOAST_ICON_GLYPHS: Readonly<Record<ToastIcon, string>>;
-/** 图标位的**文字标签**（#733 新增）：与 `TOAST_ICON_GLYPHS` 一一对应的中文词。
- *
- *  为什么要有它：`pageUi` ⑩ 那条为了治「emoji 在手机上小且糊」，把字形用 `font-size: 0` 收起、
- *  再用 `::after { content: "已完成" }` 把词**画**在屏幕上——词只活在 CSS 里。
- *  实测（32/32 页）：整份产物里「已完成」只出现 1 次，就是那行 `content:`；`<body>` 里一次都没有。
- *  后果＝屏幕上那个词**不可选中、不可搜索、不可复制、屏读器读不到、打印与 PDF 取不到字**。
- *  改法＝词进 DOM：图标位里同时放字形与这枚标签，谁显谁隐交 CSS（见 `blocks.ts` 的 note 区 CSS
- *  与 `pageUi` ⑩）。不启用 `pageUi` 的页仍只显字形，外观与改前逐值相同。 */
-export declare const TOAST_ICON_LABELS: Readonly<Record<ToastIcon, string>>;
-/** 冻结签名：`renderToast(input: ToastInput): string`（`input.msg` 非字符串 → `bad-input`）。 */
-export declare const renderToast: RenderToast;
-/** 冻结签名：`createToastController(port: ToastHostPort): ToastController`。
- *
- *  堆叠口径（旧层 `stackCap()` 同语义）：容量 = 栈内各条 `maxStack` 的**最大值**，空栈回落
- *  `TOAST_DEFAULTS.maxStack`；超容量 FIFO 挤出最旧；单条独立计时（`timeoutMs` 缺省 4500）。
- *  `flush()` 清栈；`dispose()` = `flush()` ＋ 之后 `show()` 变 no-op（幂等）。 */
-export declare const createToastController: (port: ToastHostPort) => ToastController;
-/** 冻结签名：`copyText(text: string, ports: CopyPorts, opts?: CopyTextOptions): Promise<CopyTextOutcome>`。 */
-export declare const copyText: CopyText;
-/** 冻结签名：`createCopyRuntime(ports: CopyPorts): CopyRuntime`。
- *
- *  除转发 `copyText` 外，本 runtime 记录自己挂载的反馈节点，`dispose()` 一并移除（幂等）。
- *  「dispose 后仍可复制」是文档未规定处的取值：`dispose` 只回收反馈节点，不改端口语义。 */
-export declare const createCopyRuntime: (ports: CopyPorts) => CopyRuntime;
-/** 冻结签名：`bindCopyAction(port, ports, opts?): { dispose(): void }`。
- *
- *  - id 来源**只有** `port.listActionIds()`：不猜 id、不通配前缀、不订阅未列出的 id；
- *  - 重复 id 由 binder 自行去重（同一 id 只订阅一次）；
- *  - 激活时读 `port.readDataText(actionId)`：非字符串（含 `undefined`）→ 跳过（不抛错、不产 toast），
- *    非复制按钮（场景按钮）即由此跳过，不另设允许清单；
- *  - 反馈一律走 `ports.toast`（`copyText` 内部），binder 不另出反馈；
- *  - **激活回调恒不产生未处理拒绝**（FX-76-6）：`copyText` 正常路径的失败已在内部 `settle()` 处理，
- *    这里只兜「逃出 `copyText` 的异常」（端口实现抛错／`ports.toast.mount` 抛错／回调抛错）——
- *    契约 §3.3 明写 binder 不另出反馈，故不产第二份 UI 反馈，也不重入 `opts.onFail`（防重复回调）；
- *  - `dispose()` 解绑全部已订阅 id 且幂等；解绑后激活不再触发复制。 */
-export declare const bindCopyAction: BindCopyAction;
-/** 冻结签名：`buildSharedHelpersJs(input?: SharedHelpersInput): string`。
- *
- *  产出恒为**非空**、**经典 script** 作用域可跑的 IIFE（无 `import`／`export`／顶层 `await`），
- *  逐项满足 `SHARED_HELPERS_JS_RULE`：自包含（不依赖其它脚本或既有全局）／幂等（判据**只落 DOM**：
- *  标记属性 ＋ `querySelector` 早退，**不**用全局哨兵）／允许页面侧 DOM（`document.*` 读取与事件绑定）／
- *  不向 `window.<id>`／`globalThis.<id>` 赋值／不引 `node:`。
- *
- *  功能面（文档无规定，本文记账）：① 幂等挂载点标记；② 事件委派 `[ACTION_ID_ATTR]` 点击 →
- *  读 `dataAttr` 文本 → 复制（`navigator.clipboard` → `execCommand` 兜底）；③ 反馈块
- *  **与 `renderToast` 同构**（`.toast` > `.toast-icon` ＋ `.toast-body` > `.toast-title-row` ＋ 可选
- *  `.toast-title-detail`，`.toast-close` 在 body 之外；W1 根因修 ＋ F-c 图标），`prefix` 命名空间类，
- *  `maxStack`／`timeoutMs`／移动端收窄取冻结常量；④ 关闭按钮。
- *  产出文本里的文案／数值**全部**取自冻结常量（不产第二份真相）。
- *  注：`execCommand` 兜底用临时 textarea 的两个内联定位属性（`position`／`left`），属临时节点
- *  定位而非控件样式，不构成第二份样式常量。
- *
- *  **#88 S4 追加（HELP 速查台运行时增强；文档无规定 → 本文记账）**：全部挂进**既有 `boot()`**、
- *  共用**既有幂等 marker**（`MARKER_SEL` ＋ `querySelector` 早退），**不新增第二个标记**；每一项都
- *  先判 HELP模板是否在页面（helpers 被所有技能页面共享，非 HELP 页逐项早退、零副作用）：
- *  - **卡级复制按钮**（`card-copy`）：每张场景卡的**卡头**注入 1 个按钮，`actionId`／文案恒读
- *    `HELP_COPY_ACTIONS.prompt`，`dataAttr` 取同卡 `<pre class="prompt">` 的原文（＝该卡 prompt 逐字；
- *    #88 S5 起改以 `<pre>` 为**主源**，读不到才回落 Sheet 内 prompt 按钮的 data-t），
- *    复用上面的 `[ACTION_ID_ATTR]` 委派（零新增监听、零契约变更）；卡内已有该类即跳过（幂等）。
- *  - **搜索**（`tab-search` ＋ `tab-search-input` ＋ `tab-search-clear` ＋ `page-hitcount`）：跨分组过滤卡片、
- *    `<mark class="card-mark">` 高亮命中、自动展开命中卡片的 Sheet 与子功能组、命中计数、
- *    清空复原、`Enter` 在命中分组页间跳页（自动跳第一个命中页）。
- *  - **Sheet 参数实时预览**：`editable_fields` 的静态值换成输入框，输入即重组
- *    「prompt ＋ 空行 ＋ `label: value` 行」（F3 `buildPrompt` 语义），并同步 prompt／params 复制按钮的
- *    `dataAttr`（否则复制到的是编辑前的旧文本）。
- *  - **回到顶部**（`btn-backtop`，`id="backTop"`，H-19）：`scrollTop > 400` 加 `-show`，点击平滑回顶。
- *  纯度：只用 `document.*`（含只读 `document.scrollingElement`）＋ 既有只读 `window.matchMedia`；
- *  不向 `window.<id>`／`globalThis.<id>` 赋值、不引 `node:`、不用 `classList`（类名走 `className` 字符串
- *  增删，兼容 `style.test.mjs` T28 的「动效纯 CSS」断言）、不产内联 `on*`。
- *
- *  **#121 追加（H-16 双反馈的按钮通道；文档 `docs/visual-spec-help.md:195,197`）**：复制**成功**时给
- *  **被点击的那个按钮**加 `copied` 类（`HELP_COPY_COPIED_CLASS`，规格逐字、无 `ilife-` 前缀），
- *  `HELP_COPY_COPIED_MS`（450ms）后移除；失败路径**不**加类（不静默变绿）。落点仍在**既有
- *  `boot()`／既有委派**内：`onClick` 把命中的按钮一并传给 `copy()` → 两条成功通道
- *  （`navigator.clipboard`／`execCommand` 兜底）各自在成功分支调 `markCopied(btn)`，零新增监听、
- *  零新增 marker、零新签名；类名增删复用既有 `addClass`／`removeClass`（`className` 字符串口径）。 */
-export declare const buildSharedHelpersJs: BuildSharedHelpersJs;
-/** 冻结签名：`renderActionBar(input: ActionBarInput): string`。
- *
- *  场景按钮（`primary`／`red`／`ghost`）一行；复制数据／复制日志 ghost 按钮**独立一行**
- *  （`ACTION_BAR_DEFAULTS.ghostOwnRow`）；复制文本渲染期写入 `DEFAULT_DATA_ATTR`、id 写入 `ACTION_ID_ATTR`，
- *  零内联脚本。缺 `actionId`／空串／同次渲染内重复 → `ControlsError` code `bad-input`。
- *  逐区尺寸（`minHeightPx`／`fontSizePx`／`fontWeight`／`ghostBorderAlpha`／`evenRowPairs`）由 #75 的
- *  共享样式区消费（本文件不产样式常量）。
- *
- *  #654（负责人 2026-09-16 验收打回，**口径变更**）：**不再补**那颗禁用态「复制日志」占位。
- *  动作条只渲染**真存在**的动作；ghost 行的几何改由「列数跟着颗数走」保——只有一颗时挂
- *  `action-row-ghost-single`（`style.ts` 让它在整行轨道铺满），两颗真位时照 #247 两列平分。
- *  两边都在场／都不在场／仅日志位在场照旧；仅日志位在场不补数据位。 */
-export declare const renderActionBar: RenderActionBar;
-/** 冻结签名：`renderStatusBadge(input: StatusBadgeInput): string`。
- *  非法 `status` 降级 `'empty'`（不抛错，防无样式徽章）；`text` 缺省／空串取 `STATUS_DEFAULT_TEXT`。 */
-export declare const renderStatusBadge: RenderStatusBadge;
-/** 冻结签名：`renderEmptyState(input: EmptyStateInput): string`。
- *  `icon`／`text`／`hint` 一律转义；`actionHtml` 受信 HTML 透传（不转义）；`text` 缺失／非字符串 → `bad-input`。 */
-export declare const renderEmptyState: RenderEmptyState;
-/** 冻结签名：`renderErrorReceipt(input: ErrorReceiptInput): string`。
- *  缺 `dataText`／`logText` → **不渲染**对应复制按钮（容错，不抛错）；id 缺省取
- *  `COPY_ACTION_IDS.errorReceipt.*`；**不读** `window.__hmPayload` 之类旧全局（AC-7）。 */
-export declare const renderErrorReceipt: RenderErrorReceipt;
+export * from './components/controls/index.js';
 //# sourceMappingURL=controls.d.ts.map

package/dist/controls.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"controls.d.ts","sourceRoot":"","sources":["../src/controls.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAoBH,OAAO,KAAK,EAIV,cAAc,EACd,oBAAoB,EAKpB,SAAS,EACT,WAAW,EACX,QAAQ,EAGR,iBAAiB,EAIjB,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,EACjB,WAAW,EAKX,eAAe,EACf,aAAa,EACb,SAAS,EAEV,MAAM,iBAAiB,CAAC;AAIzB;2FAC2F;AAC3F,qBAAa,aAAc,SAAQ,KAAK;IACtC,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;gBAErB,IAAI,EAAE,iBAAiB,EAAE,OAAO,EAAE,MAAM;CAKrD;AAsCD;;gEAEgE;AAChE,eAAO,MAAM,iBAAiB,EAAE,QAAQ,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAMhE,CAAC;AAEH;;;;;;;oDAOoD;AACpD,eAAO,MAAM,iBAAiB,EAAE,QAAQ,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAMhE,CAAC;AAwBH,qFAAqF;AACrF,eAAO,MAAM,WAAW,EAAE,WAuDzB,CAAC;AAEF;;;;sEAIsE;AACtE,eAAO,MAAM,qBAAqB,GAAI,MAAM,aAAa,KAAG,eAqD3D,CAAC;AAsCF,yGAAyG;AACzG,eAAO,MAAM,QAAQ,EAAE,QA8CtB,CAAC;AAEF;;;0DAG0D;AAC1D,eAAO,MAAM,iBAAiB,GAAI,OAAO,SAAS,KAAG,WA6BpD,CAAC;AAIF;;;;;;;;;;gDAUgD;AAChD,eAAO,MAAM,cAAc,EAAE,cAkC5B,CAAC;AA4EF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;4EAuC4E;AAC5E,eAAO,MAAM,oBAAoB,EAAE,oBAymBlC,CAAC;AA2KF;;;;;;;;;;;uCAWuC;AACvC,eAAO,MAAM,eAAe,EAAE,eAkC7B,CAAC;AAIF;gFACgF;AAChF,eAAO,MAAM,iBAAiB,EAAE,iBAM/B,CAAC;AAEF;2FAC2F;AAC3F,eAAO,MAAM,gBAAgB,EAAE,gBAiB9B,CAAC;AAQF;;gFAEgF;AAChF,eAAO,MAAM,kBAAkB,EAAE,kBAmChC,CAAC"}
+{"version":3,"file":"controls.d.ts","sourceRoot":"","sources":["../src/controls.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,cAAc,gCAAgC,CAAC"}