@k-table/sheet-core 0.0.1 → 0.1.0

package/dist/types-9rRrxBdg.d.ts

@@ -0,0 +1,435 @@
+/**
+ * 域文档 02 §1.3～1.4 — `workbook.ktTemplate` 与 Kt.Api.SheetTemplate 契约同构。
+ */
+/** 含端点，与 Excel / 引擎 `MergeRange` 一致 */
+type KtTemplateSlotRect = {
+    sheetId?: string;
+    r1: number;
+    c1: number;
+    r2: number;
+    c2: number;
+};
+type KtTemplateSpliceSpec = {
+    spliceDataRow1: number | null;
+    bodyColumnCount?: number;
+};
+type KtTemplateFlexibleRowSegment = {
+    r1: number;
+    r2: number;
+    minHeight: number;
+    maxHeight: number;
+    weight?: number;
+};
+type KtTemplateMainField = {
+    bindingKey: string;
+    displayName?: string;
+    dataType?: string;
+    required?: boolean;
+    defaultValue?: string;
+    dictCode?: string;
+    description?: string;
+};
+type KtTemplateSubTableColumn = {
+    columnKey: string;
+    displayName?: string;
+    dataType?: string;
+    required?: boolean;
+    dictCode?: string;
+};
+type KtTemplateSubTable = {
+    subTableId: string;
+    dataPath: string;
+    rowsPerDataPage?: number;
+    rowMin?: number;
+    rowMax?: number;
+    columns?: KtTemplateSubTableColumn[];
+};
+type KtTemplateBinding = {
+    mainFields?: KtTemplateMainField[];
+    subTables?: KtTemplateSubTable[];
+};
+type KtTemplateRoot = {
+    splice: KtTemplateSpliceSpec;
+    flexibleRows?: KtTemplateFlexibleRowSegment[];
+    binding?: KtTemplateBinding;
+};
+
+/** 公式工作室 catalog SSOT */
+type FormulaCatalogTarget = {
+    scope: "main" | "base" | "sub";
+    key: string;
+    subSchemaId?: number;
+};
+type FormulaCatalogEntry = {
+    id: string;
+    kind: "field" | "script" | "gridRef";
+    /** 用户友好赋值式，如 m.m1 = sum(s1.s1) */
+    assignment?: string;
+    target?: FormulaCatalogTarget;
+    /** 编译后 := 右侧或脚本 body */
+    source: string;
+    enabled?: boolean;
+    triggers?: Array<"onCommit" | "onCompute">;
+    runWhen?: "auto" | "manualOnly";
+    inputWhen?: "always" | "anyPresent" | "allPresent";
+    inputFields?: string[];
+    errorText?: string;
+    /** 人工固定顺序（不参与拓扑重排） */
+    orderPinned?: boolean;
+    /** 有效执行序（sync 后写入） */
+    effectiveOrder?: number;
+    scriptBlockKey?: string;
+};
+type FormulaCatalog = {
+    v: 1;
+    entries: FormulaCatalogEntry[];
+    /** auto | manual */
+    orderMode?: "auto" | "manual";
+};
+declare function emptyFormulaCatalog(): FormulaCatalog;
+/** 从 workbook.meta 读取 formulaCatalog（v1 校验），缺省返回空 catalog */
+declare function getFormulaCatalogFromMeta(meta: {
+    formulaCatalog?: unknown;
+} | null | undefined): FormulaCatalog;
+declare function normalizeFormulaCatalog(raw: unknown): FormulaCatalog | null;
+
+type DerivedFieldRule = {
+    id: string;
+    /** 用户友好赋值式，如 m.m1 = sum(s1.amount) */
+    expr: string;
+    label?: string;
+    /** 编译目标（可选缓存；以 expr 编译为准） */
+    target?: FormulaCatalogTarget;
+    triggers?: Array<"onCommit" | "onCompute">;
+    enabled?: boolean;
+};
+declare function newDerivedRuleId(): string;
+declare function normalizeDerivedRules(raw: unknown): DerivedFieldRule[];
+declare function getWorkbookDerivedRules(meta?: {
+    derivedRules?: unknown;
+} | null): DerivedFieldRule[];
+
+/** 与 k-table-api `SheetTemplateConstants` 及 docs/schema/kt/sheet.md 对齐（整型枚举）。 */
+declare const DRAFT_KIND: {
+    readonly Base: 0;
+    readonly Business: 1;
+};
+declare const CREATION_MODE: {
+    readonly Inherit: 0;
+    readonly Splice: 1;
+    /** 多 Tab 混合（继承 + 拼接 per-sheet） */
+    readonly Mixed: 2;
+};
+declare const SNAPSHOT_KIND: {
+    readonly Base: 0;
+    readonly Business: 1;
+};
+/** 拼接草案列模式：与 k-table-api `SheetTemplateConstants.SpliceColumnMode` 一致 */
+declare const SPLICE_COLUMN_MODE: {
+    readonly Equal: 0;
+    readonly Free: 1;
+};
+type DraftKind = (typeof DRAFT_KIND)[keyof typeof DRAFT_KIND];
+type CreationMode = (typeof CREATION_MODE)[keyof typeof CREATION_MODE];
+type SnapshotKind = (typeof SNAPSHOT_KIND)[keyof typeof SNAPSHOT_KIND];
+/** 与 Kt.Api.Domain.SheetTemplateConstants.WorkbookMetaInheritSourceBaseSnapshotRowId 一致 */
+declare const WORKBOOK_META_INHERIT_SOURCE_BASE_SNAPSHOT_ROW_ID: "inheritSourceBaseSnapshotRowId";
+
+type AggregateEmptyAs = "null" | "zero";
+type WorkbookComputePolicy = {
+    v: 1;
+    maxIterations?: number;
+    defaultRoundingTriggers?: Array<"onCommit" | "onCompute">;
+    aggregateEmptyAs?: AggregateEmptyAs;
+    chartRefreshOnCompute?: boolean;
+    chartRefreshOnPageChange?: boolean;
+};
+declare const DEFAULT_COMPUTE_POLICY: WorkbookComputePolicy;
+/** 结构化 meta：仅需 computePolicy 字段，避免 core 反依赖 WorkbookMeta（打破循环）。 */
+type MetaWithComputePolicy = {
+    computePolicy?: unknown;
+} | null | undefined;
+declare function normalizeComputePolicy(raw: unknown): WorkbookComputePolicy;
+declare function getWorkbookComputePolicy(meta?: MetaWithComputePolicy): WorkbookComputePolicy;
+declare function getAggregateEmptyAs(meta?: MetaWithComputePolicy): AggregateEmptyAs;
+
+/**
+ * 模板内嵌字段注册表——纯类型（逻辑保留在 kt-web lib/sheet/templateFieldRegistry.ts）。
+ */
+declare const TEMPLATE_FIELD_REGISTRY_VERSION: 1;
+/** 单条字段定义（与历史 BaseFieldRow 语义对齐，无 id/tenantId/templateCode） */
+type TemplateFieldDef = {
+    bindingKey: string;
+    displayName: string;
+    dataType: string;
+    requiredDefault?: boolean;
+    defaultValue?: string | null;
+    dictCode?: string | null;
+    roundingJson?: string | null;
+    formulaJson?: string | null;
+    runtimeEditable?: boolean;
+    writebackTarget?: string | null;
+    description?: string | null;
+    sortOrder?: number;
+    enabled?: boolean;
+    /** image 字段存储方式 */
+    imageStorage?: "base64" | "fileId" | "url";
+    /** legacy inputType 映射：{ inputType, allowCustom?, memory?, multiline? } */
+    inputWidgetJson?: string | null;
+};
+type TemplateSubFieldDef = TemplateFieldDef & {
+    subSchemaId: number;
+    /** 子表有效行数统计键；同 subSchemaId 至多一个 true */
+    subRowCountKey?: boolean;
+};
+type TemplateFieldRegistry = {
+    v: typeof TEMPLATE_FIELD_REGISTRY_VERSION;
+    updatedAt?: string;
+    base: TemplateFieldDef[];
+    main: TemplateFieldDef[];
+    sub: TemplateSubFieldDef[];
+};
+
+/**
+ * 子表每页槽位数配置——纯类型（逻辑保留在 kt-web lib/sheet/subTableSlotConfig.ts）。
+ */
+type SubTableSlotConfigEntry = {
+    sheetId: string;
+    subSchemaId: number;
+    slotsPerPage: number;
+};
+type SubTableSlotConfig = SubTableSlotConfigEntry[];
+
+/**
+ * per-sheet 业务档案——纯类型（逻辑保留在 kt-web lib/sheet/businessSheetProfile.ts）。
+ */
+
+/** per-sheet 业务档案：继承或拼接，key = sheetId */
+type BusinessSheetProfile = {
+    creationMode: typeof CREATION_MODE.Inherit | typeof CREATION_MODE.Splice;
+    /** 用户可见 Tab 名；绑定 sheetName 系统参数时优先于 sheet.name */
+    displayName?: string;
+    /** 继承：所选基础快照行 id */
+    inheritSourceBaseSnapshotRowId?: string;
+    /** 拼接 */
+    baseSnapshotRowId?: string;
+    middleDesignColumnCount?: number;
+    spliceColumnMode?: number;
+    maxBorrowRowHeight?: number | null;
+    /** 拼接上/下条带：独立 mini-workbook JSON */
+    spliceTopStripJson?: string;
+    spliceBottomStripJson?: string;
+    /** 勾选后：业务模板「同步母版」时自动处理本 Sheet */
+    syncWithBaseOnUpgrade?: boolean;
+    /** 母版 templateCode，用于解析最新有效基础快照 */
+    baseTemplateCode?: string;
+    /** 上次成功同步时的基础快照 id */
+    lastSyncedBaseSnapshotRowId?: string;
+    lastSyncedAt?: string;
+    /** LIMS 左栏本页信息作用域 id（默认 sheetId） */
+    basicScopeId?: string;
+    /** 是否在 LIMS 左栏「本页信息」展示 scoped 字段 */
+    showInLimsLeftPanel?: boolean;
+};
+type BusinessSheetProfiles = Record<string, BusinessSheetProfile>;
+declare const WORKBOOK_META_BUSINESS_SHEET_PROFILES: "businessSheetProfiles";
+type DraftDbSpliceMeta = {
+    creationMode?: number | null;
+    baseSnapshotRowId?: string | null;
+    middleDesignColumnCount?: number | null;
+    spliceColumnMode?: number | null;
+    maxBorrowRowHeight?: number | null;
+};
+
+/** 边框线宽（与 01 §2.3a.3 / §2.4 对齐）。 */
+type BorderWidth = "none" | "thin" | "medium" | "thick";
+/** 边框线型图案。 */
+type BorderPattern = "solid" | "dashed" | "dotted";
+interface CellBorderSide {
+    style?: BorderWidth;
+    pattern?: BorderPattern;
+}
+/** 四边 + 共色（T1-10a）。 */
+interface CellBorders {
+    top?: CellBorderSide;
+    bottom?: CellBorderSide;
+    left?: CellBorderSide;
+    right?: CellBorderSide;
+    color?: string;
+}
+type HorizontalAlign = "left" | "center" | "right";
+type VerticalAlign = "top" | "middle" | "bottom";
+/** M2 全量样式域（01 §2.4）。 */
+interface CellStyle {
+    fontFamily?: string;
+    fontSizePt?: number;
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    strikethrough?: boolean;
+    foreground?: string;
+    background?: string;
+    horizontalAlign?: HorizontalAlign;
+    verticalAlign?: VerticalAlign;
+    wrapText?: boolean;
+    shrinkToFit?: boolean;
+    superscript?: boolean;
+    subscript?: boolean;
+    borders?: CellBorders;
+}
+interface RichRun {
+    t: string;
+    style?: Omit<CellStyle, "horizontalAlign" | "verticalAlign" | "wrapText" | "shrinkToFit" | "borders">;
+}
+interface CellData {
+    value?: string;
+    f?: string;
+    style?: CellStyle;
+    runs?: RichRun[];
+}
+interface MergeRect {
+    r1: number;
+    c1: number;
+    r2: number;
+    c2: number;
+}
+type PaperSizeName = "A4" | "A3" | "Letter" | "Custom";
+interface PageSettings {
+    paper: PaperSizeName;
+    /** mm，仅 paper === Custom 时使用。 */
+    widthMm?: number;
+    heightMm?: number;
+    orientation: "portrait" | "landscape";
+    marginMm: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+}
+interface Sheet {
+    rowCount: number;
+    colCount: number;
+    rowHeights?: number[];
+    colWidths?: number[];
+    defaultRowHeight?: number;
+    defaultColWidth?: number;
+    cells: Record<string, CellData>;
+    merges: MergeRect[];
+    page?: PageSettings;
+}
+interface SheetItem {
+    id: string;
+    name: string;
+    sheet: Sheet;
+}
+/**
+ * 拼接草案保存时写入 `meta`，批发布可与当前基础快照校验后复用 `colSpans`。
+ * `colSpans.length === middleDesignColumnCount`，且 `sum(colSpans) ===` 基础 kt 体列数 BodyCols。
+ */
+interface SpliceComposeCacheV1 {
+    v: 1;
+    baseSnapshotRowId: string;
+    spliceColumnMode: number;
+    middleDesignColumnCount: number;
+    colSpans: number[];
+    baseContentHash?: string | null;
+}
+/** 报表明细带定义（KTL @band；语法/模型预留，打印链路暂不消费） */
+interface WorkbookReportBandDef {
+    sheetId: string;
+    /** 明细带模板行区间（1-based，含端点） */
+    startRow: number;
+    endRow: number;
+    /** 绑定的子表区号（数据源） */
+    subSchemaId?: number;
+    /** 跨页续表时每页重复的表头行区间 */
+    headerStartRow?: number;
+    headerEndRow?: number;
+}
+/** 报表元信息（KTL @report 块；报表文件专用，普通模板可缺省） */
+interface WorkbookReportMeta {
+    /** 报表标题 */
+    title?: string;
+    /** 报表业务版本（区别于 ktlSourceVersion） */
+    reportVersion?: string;
+    /** 描述 */
+    description?: string;
+    /** 明细带（@band）配置——预留 */
+    bands?: WorkbookReportBandDef[];
+}
+interface WorkbookMeta {
+    author?: string;
+    locale?: string;
+    timezone?: string;
+    /** 仅拼接业务草案中区工作簿：合成列映射缓存 */
+    spliceComposeCache?: SpliceComposeCacheV1;
+    /** 业务多 Tab：per-sheet 继承/拼接档案，key = sheetId */
+    businessSheetProfiles?: BusinessSheetProfiles;
+    /** 继承草案：所选基础快照行 id（单 sheet 旧数据兼容） */
+    inheritSourceBaseSnapshotRowId?: string;
+    /** 模板包内嵌字段注册表（设计态 SSOT；发布时 bake 至 capabilities.fieldRegistry） */
+    fieldRegistry?: TemplateFieldRegistry;
+    /** 子表每 sheet×subSchema 每页槽位数 */
+    subTableSlotConfig?: SubTableSlotConfig;
+    /** 公式工作室 catalog（设计态 SSOT） */
+    formulaCatalog?: FormulaCatalog;
+    /** 模板级计算策略（设计态 SSOT） */
+    computePolicy?: WorkbookComputePolicy;
+    /** 声明式派生规则（设计态 SSOT；写回 fieldRegistry.formulaJson） */
+    derivedRules?: DerivedFieldRule[];
+    /** 报表元信息（KTL @report 块） */
+    report?: WorkbookReportMeta;
+    /** KTL 源码文本（设计态持久化） */
+    ktlSource?: string;
+    /** KTL 源码版本号（每次修改递增） */
+    ktlSourceVersion?: number;
+    /** KTL Source Map 序列化 JSON（持久化以避免每次重解析） */
+    ktlSourceMap?: string;
+}
+/** M3 公式/脚本：工作簿级脚本块与命名区域 */
+type WorkbookScriptHook = "compute" | "beforeRender";
+interface WorkbookScriptBlock {
+    /** 唯一键；与 CellFormulaBindingMeta.scriptBlockKey 对应；习惯以 CALC_ 前缀 */
+    key: string;
+    /** 作用域：main 仅主表一次；subRow 每子表行 */
+    scope: "main" | "subRow";
+    /** subRow 的子表区号 */
+    subSchemaId?: number;
+    /**
+     * compute（默认）：参与公式计算链；
+     * beforeRender：实例预览/打印前执行，可控制 sheet/逻辑页是否参与渲染。
+     */
+    hook?: WorkbookScriptHook;
+    /** 受限 JS 表达式/函数体源码 */
+    source: string;
+    /** 入参白名单，可留空代表所有可读上下文 */
+    inputs?: string[];
+    errorText?: string;
+    meta?: {
+        updatedAt?: string;
+        updatedBy?: string;
+    };
+}
+interface WorkbookScripts {
+    v: 1;
+    language: "safe-js-expr";
+    blocks: WorkbookScriptBlock[];
+}
+/** M3+ 命名区域：'NetPrice' → Sheet1!B2 或 Sheet1!A1:A10 */
+interface WorkbookNamedRange {
+    name: string;
+    ref: string;
+}
+interface Workbook {
+    workbookVersion: number;
+    sheets: SheetItem[];
+    activeSheetId: string;
+    ktTemplate?: KtTemplateRoot;
+    meta?: WorkbookMeta;
+    scripts?: WorkbookScripts;
+    namedRanges?: WorkbookNamedRange[];
+    extension?: Record<string, unknown>;
+}
+
+export { type WorkbookReportMeta as $, type AggregateEmptyAs as A, type BorderWidth as B, type CellData as C, DEFAULT_COMPUTE_POLICY as D, type KtTemplateSubTableColumn as E, type FormulaCatalogTarget as F, type PaperSizeName as G, type HorizontalAlign as H, SNAPSHOT_KIND as I, SPLICE_COLUMN_MODE as J, type KtTemplateRoot as K, type SnapshotKind as L, type MergeRect as M, type SpliceComposeCacheV1 as N, type SubTableSlotConfig as O, type PageSettings as P, type SubTableSlotConfigEntry as Q, type RichRun as R, type Sheet as S, type TemplateFieldRegistry as T, TEMPLATE_FIELD_REGISTRY_VERSION as U, type VerticalAlign as V, type WorkbookScripts as W, WORKBOOK_META_BUSINESS_SHEET_PROFILES as X, WORKBOOK_META_INHERIT_SOURCE_BASE_SNAPSHOT_ROW_ID as Y, type WorkbookComputePolicy as Z, type WorkbookReportBandDef as _, type WorkbookMeta as a, type WorkbookScriptBlock as a0, type WorkbookScriptHook as a1, emptyFormulaCatalog as a2, getAggregateEmptyAs as a3, getFormulaCatalogFromMeta as a4, getWorkbookComputePolicy as a5, getWorkbookDerivedRules as a6, newDerivedRuleId as a7, normalizeComputePolicy as a8, normalizeDerivedRules as a9, normalizeFormulaCatalog as aa, type WorkbookNamedRange as b, type BorderPattern as c, type SheetItem as d, type Workbook as e, type FormulaCatalogEntry as f, type TemplateFieldDef as g, type TemplateSubFieldDef as h, type BusinessSheetProfile as i, type BusinessSheetProfiles as j, CREATION_MODE as k, type CellBorderSide as l, type CellBorders as m, type CellStyle as n, type CreationMode as o, DRAFT_KIND as p, type DerivedFieldRule as q, type DraftDbSpliceMeta as r, type DraftKind as s, type FormulaCatalog as t, type KtTemplateBinding as u, type KtTemplateFlexibleRowSegment as v, type KtTemplateMainField as w, type KtTemplateSlotRect as x, type KtTemplateSpliceSpec as y, type KtTemplateSubTable as z };

package/package.json

@@ -1,9 +1,47 @@
-{
-  "name": "@k-table/sheet-core",
-  "version": "0.0.1",
-  "description": "KT 工作簿引擎（公式/几何/序列化）（占位包，正式版即将发布）",
-  "license": "UNLICENSED",
-  "publishConfig": {
-    "access": "public"
-  }
-}
+{
+  "name": "@k-table/sheet-core",
+  "version": "0.1.0",
+  "publishConfig": { "access": "public" },
+  "license": "UNLICENSED",
+  "description": "kt 表格无头引擎：模型/序列化/公式/运行态/拼接/实例数据/迁移（无 React/DOM/window/fetch/zustand）",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./migrate": {
+      "types": "./dist/migrate/index.d.ts",
+      "import": "./dist/migrate/index.js",
+      "require": "./dist/migrate/index.cjs"
+    },
+    "./sheet-template-model": {
+      "types": "./dist/sheet-template-model.d.ts",
+      "import": "./dist/sheet-template-model.js",
+      "require": "./dist/sheet-template-model.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "eslint --config ../eslint.config.mjs \"src/**/*.ts\"",
+    "clean": "rimraf dist"
+  },
+  "dependencies": {
+    "@k-table/sheet-host": "*"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5",
+    "vitest": "^4.1.5"
+  }
+}

package/README.md

@@ -1,5 +0,0 @@
-# @k-table/sheet-core
-
-KT 工作簿引擎（公式/几何/序列化）。
-
-**本包为占位版本（0.0.1），正式版即将发布。** 正式版为商业授权软件，使用时需提供授权码。