base-paint 0.1.0 → 0.3.0

package/dist/blocks.d.ts

@@ -0,0 +1,169 @@
+/** base-paint/blocks：#104 B1 区块组件整合（12 区块，接口 owner）。
+ *
+ * 地位（契约 `docs/base-paint-contract.md` §4.1／§4.4 #104 行）：
+ *  - 区块级 = 页面级组合：**组合**冻结控件（`renderEmptyState`／`renderActionBar`／
+ *    `renderToast`／`renderErrorReceipt`／`renderStatusBadge`／`charts.*`），**不得**
+ *    重定义控件签名、不得复制控件实现、不得改 `CONTROL_*`／`STATUS_*`／`COPY_*` 常量；
+ *  - **防火墙**：本模块**不在** `src/spec/`、**不进** `SPEC_FROZEN_SURFACE`、
+ *    **不从** `src/index.ts` 导出（签名测试把 `dist/index.js` 出口与冻结清单绑死，
+ *    区块接口是可演进的组合层，不是冻结签名）。消费方走子路径 `base-paint/blocks`；
+ *  - 清单裁定（DB-1）：12 区块取 `docs/visual-spec-blocks.md` §1 拟定清单为终版，
+ *    只做命名收敛（英文键），锚点语义不变；
+ *  - 样式闭集裁定（DB-2）：新增 `BLOCK_STYLE_SECTIONS` 12 区闭集（**不改**
+ *    `CONTROL_STYLE_SECTIONS`）；区块 CSS 由本模块唯一产出者 `blocksCss()` 产出，
+ *    只读冻结 token（`CSS_VAR_TOKENS`）＋ 局部 CSS 常量（圆角 `{8,14,20,999}`、
+ *    `--line` 派生软线），**不新增 token 名**（D-5／DB-5）。
+ *
+ * 三条硬边界（违反即红）：
+ *  1. **静态呈现 ＋ 复制**（§4.1）：12 个函数全是纯函数产 HTML 字符串；B-08 只产原生
+ *     `<details>/<summary>`，B-09 只产静态 `label＋input`（实时预览／空值拦截的
+ *     **行为**归宿主＝插件 client，B7；本模块只给宿主留 `data-*` 约定）；
+ *  2. **禁交互控件名**（B7）：`formPrompt`／`selectList`／`smartSelect`／`confirm`／
+ *     `foldBox` 不得出现为导出（含大小写变体）；
+ *  3. **模块代码零 DOM**（AC-7）：本文件编译进 `dist/blocks.js` 的**代码**里不出现
+ *     `document.`／`window.`／`navigator.`（与 #76 同口径，`test/blocks.test.mjs` 钉死）。
+ *
+ * 受信透传口径（与 `renderEmptyState` 的 `actionHtml` 同口径）：`contentHtml`／
+ * `previewText` 等「已由区块函数自产的 HTML」**不转义**（调用方不得塞入未转义的用户串；
+ * 用户串一律走各函数的文本字段，本模块用冻结五字符表转义）；
+ * `actionHtml`（B-10）沿用冻结语义（调用方负责内容安全）。
+ */
+import { ACTION_ID_ATTR, COPY_ACTION_IDS, DEFAULT_DATA_ATTR, TOAST_DEFAULTS } from './spec/index.js';
+import type { ActionBarInput, ChartKind, CopyButtonInput, EmptyStateInput, ErrorReceiptInput, Scene, StatusKind, ToastInput } from './spec/index.js';
+import type { BarChartInput, ComboChartInput, DonutChartInput, GaugeChartInput, LineChartInput, ProgressChartInput, ScatterChartInput, SparklineChartInput } from './spec/charts.js';
+/** 区块层错误。code 恒为 `bad-input`（输入缺失／非法一律抛，缺失阻断不返空）。 */
+export declare class BlocksError extends Error {
+    readonly code: 'bad-input';
+    constructor(message: string);
+}
+/** 12 区块样式区（DB-1 清单的代码落点；顺序即 B-01…B-12）。 */
+export declare const BLOCK_STYLE_SECTIONS: readonly ["pageShell", "kpiCard", "dataTable", "chartBlock", "listRows", "preBlock", "detailSection", "disclosure", "paramForm", "emptyBlock", "copyBlock", "feedbackBlock"];
+export type BlockStyleSection = (typeof BLOCK_STYLE_SECTIONS)[number];
+export interface PageShellInput {
+    readonly title: string;
+    readonly subtitle?: string;
+    readonly eyebrow?: string;
+    /** 已组合好的区块 HTML（受信透传，不转义）。 */
+    readonly content: string;
+}
+/** B-01：单页容器＋标题三件套（eyebrow／title／subtitle）＋正文。 */
+export declare function renderPageShell(input: PageShellInput): string;
+export interface KpiCardInput {
+    readonly label: string;
+    readonly value: string;
+    readonly unit?: string;
+    readonly detail?: string;
+    readonly status?: StatusKind;
+    readonly statusText?: string;
+}
+/** B-02：单张 KPI 卡（value 带 `tnum`；非法 status 由冻结语义降级 `empty`）。 */
+export declare function renderKpiCard(input: KpiCardInput): string;
+/** B-02 伴生布局：KPI 卡网格（不是第 13 个区块，无独立样式区，用 `kpiCard` 区）。 */
+export declare function renderKpiGrid(cards: readonly KpiCardInput[]): string;
+export type DataTableAlign = 'left' | 'center' | 'right';
+export interface DataTableColumn {
+    readonly key: string;
+    readonly label: string;
+    readonly align?: DataTableAlign;
+}
+export interface DataTableInput {
+    readonly columns: readonly DataTableColumn[];
+    readonly rows: readonly Readonly<Record<string, unknown>>[];
+    readonly caption?: string;
+    readonly emptyText?: string;
+}
+/** B-03：语义表格（`table／thead／th／td`；零行 → `renderEmptyState`，不渲染空表）。 */
+export declare function renderDataTable(input: DataTableInput): string;
+export type ChartBlockChartInput = BarChartInput | LineChartInput | DonutChartInput | ProgressChartInput | ComboChartInput | SparklineChartInput | GaugeChartInput | ScatterChartInput;
+export interface ChartBlockInput {
+    readonly kind: ChartKind;
+    readonly input: ChartBlockChartInput;
+    readonly title?: string;
+}
+/** B-04：图表区块（分发给冻结 `charts` 8 接口；空数组走空态／结构违规抛错恒为冻结语义）。 */
+export declare function renderChartBlock(input: ChartBlockInput): string;
+export interface ListRowInput {
+    readonly left?: string;
+    readonly main: string;
+    readonly right?: string;
+    readonly done?: boolean;
+}
+export interface ListRowsInput {
+    readonly items: readonly ListRowInput[];
+    readonly emptyText?: string;
+}
+/** B-05：行列表（首行无边框；`done` → 删除线＋成功色；零行 → 空态）。 */
+export declare function renderListRows(input: ListRowsInput): string;
+export interface PreBlockInput {
+    readonly command: string;
+    readonly label?: string;
+    /** 给出即渲染复制按钮（id 写入 ACTION_ID_ATTR，文本写入 DEFAULT_DATA_ATTR）。 */
+    readonly actionId?: string;
+    readonly copyText?: string;
+    readonly copyLabel?: string;
+}
+/** B-06：指令块（`<pre>` 逐字命令；无命令 → `bad-input`，不渲染空板）。 */
+export declare function renderPreBlock(input: PreBlockInput): string;
+export interface DetailSectionInput {
+    readonly scene: Scene;
+    /** 该场景的 CLI 形态（调用方按 §3.5.3 `Scene.id` 推导约定组装）。 */
+    readonly cli?: string;
+}
+/** B-07：场景详情（`prompt_template` 全文逐字展示；`【待开发】` 徽章下复制按钮仍可点＝纯展示，无行为）。 */
+export declare function renderDetailSection(input: DetailSectionInput): string;
+export interface DisclosureInput {
+    readonly title: string;
+    /** 已组合好的区块 HTML（受信透传，不转义）。 */
+    readonly contentHtml: string;
+    readonly open?: boolean;
+}
+/** B-08：折叠区（原生 `details／summary`；`[open]` 驱动展开态；复制按钮在内容里不触发 toggle＝宿主行为）。 */
+export declare function renderDisclosure(input: DisclosureInput): string;
+export interface ParamFieldInput {
+    readonly name: string;
+    readonly label: string;
+    readonly value?: string;
+    readonly hint?: string;
+    readonly required?: boolean;
+}
+export interface ParamFormInput {
+    readonly fields: readonly ParamFieldInput[];
+    readonly description?: string;
+    /** 初始预览文本（受信透传；实时重算由宿主在 `input` 事件里做，DB-7）。 */
+    readonly previewText?: string;
+}
+/** B-09：参数表单（`placeholder = hint`；`required` 落 `data-required` 供宿主拦截；零 JS）。 */
+export declare function renderParamForm(input: ParamFormInput): string;
+export interface EmptyBlockInput extends EmptyStateInput {
+    readonly title?: string;
+}
+/** B-10：空态区块（冻结 `renderEmptyState` ＋ 区块 wrapper；异常走 B-12，两者不混用 DB-8）。 */
+export declare function renderEmptyBlock(input: EmptyBlockInput): string;
+export interface CopyBlockInput {
+    readonly title?: string;
+    readonly dataText?: string;
+    readonly logText?: string;
+    readonly dataActionId?: string;
+    readonly logActionId?: string;
+    readonly buttons?: ActionBarInput['buttons'];
+}
+/** B-11：复制区块（冻结 `renderActionBar`；id 缺省取 `COPY_ACTION_IDS.actionBar.*`，调用方须保页内唯一）。 */
+export declare function renderCopyBlock(input: CopyBlockInput): string;
+export interface FeedbackBlockInput {
+    readonly title?: string;
+    readonly toast?: ToastInput;
+    readonly error?: ErrorReceiptInput;
+}
+/** B-12：反馈区块（冻结 `renderToast` 和／或 `renderErrorReceipt`；两者至少其一）。 */
+export declare function renderFeedbackBlock(input: FeedbackBlockInput): string;
+export interface BlocksCssInput {
+    /** 类名前缀；缺省 `STYLE_PREFIX`（`ilife-`）。 */
+    readonly prefix?: string;
+}
+/** 区块样式资产唯一产出者（用法：调用方把返回值拼进 `TemplateAssets.sharedCssText`
+ *  再交 `fillTemplate` 包裹注入；不得走 `StyleSheetInput.extraCss`——其语义被契约
+ *  限死为技能作用域 token 覆盖块，不得塞壳层样式）。恒返回非空 CSS 文本。 */
+export declare function blocksCss(input?: BlocksCssInput): string;
+export { ACTION_ID_ATTR, COPY_ACTION_IDS, DEFAULT_DATA_ATTR, TOAST_DEFAULTS };
+export type { ActionBarInput, CopyButtonInput, EmptyStateInput, ErrorReceiptInput, StatusKind, ToastInput, };
+//# sourceMappingURL=blocks.d.ts.map

package/dist/blocks.d.ts.map

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