@k-table/report 0.1.0 → 1.0.1

package/dist/index.css

@@ -136,9 +136,9 @@ table.kt-sheet-region-table td {
   padding: 6px 8px;
   border-bottom-width: 1px;
   border-bottom-style: solid;
-  border-bottom-color: #e5e6eb;
-  background: #fff;
-  color: #1d2129;
+  border-bottom-color: var(--kt-forms-border, var(--kt-border, #e5e6eb));
+  background: var(--kt-forms-chrome-bar, var(--kt-header-bg, #fff));
+  color: var(--kt-forms-text, var(--kt-text, #1d2129));
 }
 .kt-compose-preview-pane-head__start {
   display: flex;
@@ -156,29 +156,28 @@ table.kt-sheet-region-table td {
 .kt-preview-print-bar {
   display: flex;
   align-items: center;
+  flex-wrap: wrap;
   gap: 8px;
-  height: 28px;
-  min-height: 28px;
+  min-height: 40px;
   margin-bottom: 8px;
   box-sizing: border-box;
+  color: var(--kt-forms-text, var(--kt-text, #1d2129));
 }
 .kt-preview-print-bar-main,
 .kt-preview-print-bar-end,
 .kt-preview-zoom {
   display: flex;
   align-items: center;
-  min-height: 0;
-  height: 28px;
+  min-height: 28px;
 }
 .kt-preview-print-bar-main {
   min-width: 0;
-  flex: 1;
+  flex: 1 1 auto;
   gap: 8px;
-  flex-wrap: nowrap;
-  overflow-x: auto;
+  flex-wrap: wrap;
 }
 .kt-preview-print-bar-end {
-  flex-shrink: 0;
+  flex: 0 0 auto;
   margin-left: auto;
   gap: 4px;
 }
@@ -191,34 +190,48 @@ table.kt-sheet-region-table td {
   height: 28px;
   line-height: 28px;
   font-size: 12px;
-  color: #8c8c8c;
+  color: var(--kt-forms-text-secondary, var(--kt-text-secondary, #8c8c8c));
   white-space: nowrap;
 }
 .kt-preview-fill-icon-btn {
   display: inline-flex;
   align-items: center;
   justify-content: center;
-  width: 24px;
-  height: 24px;
+  width: 28px;
+  height: 28px;
   padding: 0;
   border-width: 0;
   background: transparent;
-  color: #4e5969;
+  color: var(--kt-forms-text-secondary, var(--kt-text-secondary, #4e5969));
   cursor: pointer;
   border-radius: 2px;
   flex-shrink: 0;
   font-size: 16px;
 }
 .kt-preview-fill-icon-btn:hover {
-  background: #e5e6eb;
-  color: #1d2129;
+  background: var(--kt-primary-soft, #e5e6eb);
+  color: var(--kt-forms-text, var(--kt-text, #1d2129));
 }
 .kt-preview-page-chrome {
   box-sizing: border-box;
   min-height: calc(100vh - 104px);
-  background: #fff;
+  background: var(--kt-forms-preview-host, var(--kt-page-bg, #f2f3f5));
+  color: var(--kt-forms-text, var(--kt-text));
   padding: 16px;
 }
+.kt-preview--modal {
+  min-width: 0;
+  min-height: 0;
+}
+.kt-preview--modal .kt-preview-print-bar {
+  position: sticky;
+  top: 0;
+  z-index: 2;
+  background: var(--kt-forms-preview-host, var(--kt-page-bg, #f2f3f5));
+}
+.kt-preview--modal .kt-report-preview-host {
+  padding-top: 8px;
+}
 .kt-preview-page-chrome--fill {
   min-height: 100vh;
   padding: 8px;

package/dist/index.d.ts

@@ -1,4 +1,16 @@
 import type { ReactNode } from "react";
+import type * as React from "react";
+
+/** 预览/打印数据袋（b=绑定袋 m=映射袋 params=参数袋）；与 @k-table/sheet-core 同形 */
+export type ReportFieldData = {
+  m?: Record<string, unknown>;
+  b?: Record<string, unknown>;
+  params?: Record<string, unknown>;
+  [key: string]: unknown;
+};
+/** 模板工作簿状态（KTL 解析后）；结构化细节见 @k-table/sheet-core */
+export type TemplateWorkbookState = any;
+export const SHEET_TEMPLATE_JSON_VERSION: 2;
 
 export class KtStoreError extends Error {
   readonly status?: number;
@@ -14,6 +26,24 @@ export class KtConflictError extends KtStoreError {
 export function errorFromHttp(status: number, message: string, body?: unknown): KtStoreError;
 
 export type ArtifactKind = "master" | "record" | "report" | "sheet";
+export type ArtifactField = {
+  fieldId: string;
+  fieldCode: string;
+  label: string;
+  dataType: string;
+  sort: number;
+  formula?: string | null;
+  tableRelation?: number;
+  dictCode?: string | null;
+  paramId?: string | null;
+  roundKind?: string | null;
+  roundDigits?: number | null;
+  readOnly?: boolean;
+  defaultValue?: string | null;
+  optionsJson?: string | null;
+  inputKind?: string | null;
+  sampleAttrKey?: string | null;
+};
 export interface Artifact {
   id: string;
   name: string;
@@ -22,6 +52,12 @@ export interface Artifact {
   masterId?: string;
   faces?: { fill?: string; report?: string };
   commonFieldKeys?: string[];
+  /** 字段目录（设计器字段/公式面板数据源） */
+  fields?: ArtifactField[];
+  /** 录入面/报表面显示闸（缺省 = 两面都显示） */
+  showFaces?: { entry?: boolean; report?: boolean };
+  /** 宿主角色语义，透传不解释 */
+  formRole?: string;
   etag?: string;
 }
 export interface ArtifactMeta {
@@ -150,6 +186,84 @@ export interface KtTheme {
   chrome?: KtThemeChrome;
   styleId?: KtUiStyleId;
 }
+export interface KtPdfExportRequest {
+  title?: string;
+  pageRanges?: string;
+  pageSizeMm?: { width: number; height: number };
+  landscape?: boolean;
+}
+export interface KtPdfExportResult {
+  canceled?: boolean;
+  filePath?: string;
+}
+export interface KtPrintHooks {
+  /** 打印前（可异步）；返回 false 取消本次打印 */
+  beforePrint?: (ctx: { title?: string }) => void | boolean | Promise<void | boolean>;
+  afterPrint?: () => void;
+  /** PDF 导出器（宿主注入桌面桥）；缺省 = 浏览器「另存为 PDF」提示 */
+  pdfExporter?: (req: KtPdfExportRequest) => Promise<KtPdfExportResult>;
+  /** 「打印选项」菜单追加项 */
+  extraOptions?: { label: string; onClick: () => void }[];
+  /** 打印记忆 localStorage key 前缀；缺省 "kt-preview-print-mem" */
+  memoryKey?: string;
+}
+export interface KtPreviewHooks {
+  /** 灌数后处理：业务 enrich / 图表与签名图槽数据注入 */
+  enrichFieldData?: (
+    fieldData: ReportFieldData,
+    ctx: { artifactId?: string; instanceId?: string },
+  ) => ReportFieldData | Promise<ReportFieldData>;
+  /** 页眉页脚 chrome 数据（审批意见/二维码/审核人区）；null = 无 */
+  pageChrome?: (ctx: { artifactId?: string; instanceId?: string }) => Promise<{
+    showOpinion: boolean;
+    showQr: boolean;
+    showReviewer: boolean;
+  } | null>;
+  onPageChromeCommit?: (
+    next: { showOpinion: boolean; showQr: boolean; showReviewer: boolean },
+    remember: { rememberUnit?: boolean; rememberMaster?: boolean },
+    ctx: { artifactId?: string },
+  ) => void;
+}
+export interface KtDesignerHooks {
+  /** 业务绑定字段目录，并入设计器字段面板 */
+  bindingSchemas?: unknown[];
+  /** 公式试算（宿主业务 API，按字段）；缺省时公式面板只编辑不试算 */
+  trialFormula?: (ctx: {
+    artifactId?: string;
+    fieldCode: string;
+    formula: string;
+    roundKind?: string | null;
+    roundDigits?: number | null;
+  }) => Promise<{ rounded?: string; raw?: string; source?: string }>;
+  /** prepage 规则面板的字典选项源（dictCode → 选项）；缺省隐藏字典相关入口 */
+  prepageDicts?: () => Promise<Record<string, { value: string; label: string }[]>>;
+  /** 服务端设计包导入（宿主自弹 UI）；返回 "reload" 让设计器重取 artifact */
+  importDesignPack?: (ctx: {
+    artifactId: string;
+    name?: string;
+    masterId?: string;
+    ktl?: string;
+    hasFields?: boolean;
+  }) => Promise<"reload" | null>;
+  /** 实例联排数据源；缺省隐藏实例模式 */
+  instances?: {
+    list: (artifactId: string) => Promise<{ id: string; title: string }[]>;
+    fieldData: (instanceId: string, ctx: { artifactId: string }) => Promise<ReportFieldData>;
+  };
+}
+export interface KtFillHooks {
+  /** 录入画布字典选项（dictCode → 选项）；缺省无字典下拉 */
+  dicts?: () => Promise<Record<string, { value: string; label: string }[]>>;
+  /** 预览公共袋最后加工（单位名/人员签名等宿主语义）；在包内 enrich 之后执行 */
+  enrichCommon?: (bag: Record<string, string>, ctx: { instanceId?: string }) => Record<string, string>;
+}
+export interface KtHooks {
+  print?: KtPrintHooks;
+  preview?: KtPreviewHooks;
+  designer?: KtDesignerHooks;
+  fill?: KtFillHooks;
+}
 export interface KtConfig {
   sku: KtSku;
   locale?: "zh-CN";
@@ -174,6 +288,8 @@ export interface KtConfig {
     print?: boolean;
     pdf?: boolean;
   };
+  /** 宿主钩子：打印/PDF/预览灌数/设计器字段目录。全部可选。 */
+  hooks?: KtHooks;
 }
 export interface ResolvedFeatures {
   master: boolean;
@@ -293,27 +409,28 @@ export function KtVersionPanel(props: {
   onRestored?: () => void;
 }): JSX.Element | null;
 
-export type DesignerFormField = {
-  fieldId: string;
-  fieldCode: string;
-  label: string;
-  dataType: string;
-  sort: number;
-  formula?: string | null;
-  tableRelation?: number;
-};
+/** 向后兼容别名；正本为 ArtifactField（Artifact.fields 元素型） */
+export type DesignerFormField = ArtifactField;
 export function withSplitFaces(artifact: Artifact, workbook: unknown): Artifact;
 export function previewKtlOf(artifact: Artifact): string;
 export function KtReportDesigner(props: {
   artifact?: Artifact;
   artifactId?: string;
   store?: ArtifactStore;
+  /** 母版清单/读取的独立 store（如目录 defs 适配器 + reports 母版）；缺省同 store */
+  masterStore?: ArtifactStore;
   masters?: { id: string; name: string }[];
   values?: Record<string, unknown>;
   formFields?: DesignerFormField[];
   sheetFaceEnabled?: boolean;
   onSave?: (a: Artifact) => void;
   onConflict?: (e: KtConflictError) => void;
+  /** 提供则铬层出现「另存」，参数为当前内存稿（含未保存改动） */
+  onSaveAs?: (a: Artifact) => void;
+  /** true = 铬层名称可编辑（随保存落库） */
+  nameEditable?: boolean;
+  /** true 且 hooks.designer.importDesignPack 存在时，导入按钮带「导入设计包（服务端）」入口 */
+  allowImportPack?: boolean;
   extraActions?: ReactNode;
   leadingActions?: ReactNode;
 }): JSX.Element;
@@ -324,15 +441,111 @@ export function KtReportPreview(props: {
   rev?: string;
   values?: ValueBag;
   common?: ValueBag;
+  /** false = 极简纸面（无打印条）；缺省走完整预览壳 */
   print?: boolean;
   showVersionPanel?: boolean;
   extraActions?: ReactNode;
+  onBack?: () => void;
+  backDisabled?: boolean;
+  preferSampleContent?: boolean;
+  /** 当次附加绑定字段（与 hooks.designer.bindingSchemas 合并） */
+  bindingSchema?: unknown[];
+  /** 打印空白：空袋求值后的合成稿；null = 有闸门无默认不打页 */
+  blankWorkbook?: unknown;
+  blankEmptyHint?: string;
+  fieldDataForSheet?: (sheetId: string) => ReportFieldData;
+  /** 实例上下文：透传给 hooks 的 ctx.instanceId */
+  instanceId?: string;
+  /** 打印记忆表 key；缺省 artifact.id */
+  tableKey?: string;
+  /** 打印记忆种类（以下空白分槽）；缺省按 artifact.kind 映射 */
+  printKind?: "record" | "report" | "consign";
+  /** 页眉页脚 chrome（优先于 hooks.preview.pageChrome） */
+  pageChrome?: { showOpinion: boolean; showQr: boolean; showReviewer: boolean } | null;
+  onPageChromeCommit?: (
+    next: { showOpinion: boolean; showQr: boolean; showReviewer: boolean },
+    remember: { rememberUnit?: boolean; rememberMaster?: boolean },
+  ) => void;
+  /** page = 整页预览台；modal = 设计器弹层 */
+  chrome?: "page" | "modal";
+}): JSX.Element;
+// C3：低层逃生舱与通用预览工具
+export type PageChromeRegions = { showOpinion: boolean; showQr: boolean; showReviewer: boolean };
+export type PageChromePartial = Partial<PageChromeRegions>;
+export type PageChromeRemember = { rememberUnit?: boolean; rememberMaster?: boolean };
+export const DEFAULT_PAGE_CHROME: PageChromeRegions;
+export function overlayPageChrome(...layers: Array<PageChromePartial | null | undefined>): PageChromeRegions;
+export function pageChromeEquals(a: PageChromeRegions, b: PageChromeRegions): boolean;
+export function parsePageChromeFromBag(bag: Record<string, unknown> | null | undefined): PageChromePartial | null;
+export function parsePageChromeFromSearch(search: { get(name: string): string | null } | null | undefined): PageChromePartial | null;
+export function parsePageChromePartial(raw: unknown): PageChromePartial | null;
+export function stringifyPageChrome(chrome: PageChromeRegions): string;
+export function writePageChromeToBag(bag: Record<string, string>, chrome: PageChromeRegions): Record<string, string>;
+export type PreviewPrintKind = "record" | "report" | "consign";
+export function resolvePrintMemoryTableKey(legacyCode?: string | null, formDefId?: string | null): string;
+export type BindingField = { label: string; value: string; group?: string };
+export function mergeBindingSchema(base: BindingField[], extra?: BindingField[]): BindingField[];
+export function bindingFieldsFromFieldData(fieldData?: ReportFieldData | null): BindingField[];
+export function bindingFieldsFromWorkbook(workbook: unknown): BindingField[];
+export function readBindingExtras(workbook: unknown): BindingField[];
+export const SAMPLE_FIELD_DATA: ReportFieldData;
+export function applySampleInfoCompose(
+  bag: Record<string, string>,
+  keys: string[],
+  labelOf: (key: string) => string,
+): Record<string, string>;
+export const SAMPLE_INFO_PAPER_LABEL: string;
+export function enrichLabNameFieldData(fieldData?: ReportFieldData | null, fallbackLabName?: string): ReportFieldData;
+export function resolvePreviewLabName(
+  bag?: Record<string, unknown> | null,
+  extras?: { queryLabName?: string; homeOrgName?: string },
+): string;
+// C3：导入设计包/母版拼接工具
+export type MasterZones = any;
+export type MasterComposeFail = { fail: true; reason?: string; [key: string]: unknown };
+export function isMasterFail(v: unknown): boolean;
+export function deriveMasterZones(sheet: unknown): MasterZones | MasterComposeFail;
+export function fitWorkbookToMasterBodySlot(
+  workbook: TemplateWorkbookState,
+  master: unknown,
+  masterId?: string,
+  opts?: { resetBorder?: boolean; sheetIds?: string[] },
+): TemplateWorkbookState;
+export function normalizeWorkbookBordersToThinSolid(workbook: TemplateWorkbookState): TemplateWorkbookState;
+export function mergeImportedPrepage(
+  currentEntryKtl: string | null | undefined,
+  incomingEntryKtl: string | null | undefined,
+  opts: { replaceLayout: boolean; replaceRules: boolean },
+): string;
+export function prepageDisplayName(raw?: string | null): string;
+export function KtReportPreviewSurface(props: {
+  workbook: unknown;
+  blankWorkbook?: unknown;
+  blankEmptyHint?: string;
+  fieldData?: ReportFieldData;
+  fieldDataForSheet?: (sheetId: string) => ReportFieldData;
+  bindingSchema?: BindingField[];
+  preferSampleContent?: boolean;
+  title?: string;
+  composeWarn?: string | null;
+  chrome?: "page" | "modal";
+  onBack?: () => void;
+  backDisabled?: boolean;
+  extraActions?: ReactNode;
+  tableKey?: string;
+  printKind?: PreviewPrintKind;
+  fallbackLabName?: string;
+  pageChrome?: PageChromeRegions | null;
+  onPageChromeCommit?: (next: PageChromeRegions, remember: PageChromeRemember) => void;
+  watermarkOverride?: unknown;
 }): JSX.Element;
 export function KtReportCatalog(props: {
   store?: ArtifactStore;
   kinds?: ArtifactKind[];
   onOpenDesign: (id: string) => void;
   onOpenPreview: (id: string) => void;
+  /** 提供且 features.fill 开启时，行内出现「录入」入口 */
+  onOpenFill?: (id: string) => void;
 }): JSX.Element;
 export function KtThemeBar(props?: { variant?: "default" | "onPrimary" }): JSX.Element;
 export function KtBrandBar(props: { title: string; themeBar?: boolean }): JSX.Element;
@@ -346,3 +559,272 @@ export function composeKtlForPreview(
   ktl: string,
   fetchMasterKtl: (masterId: string) => Promise<string | null>,
 ): Promise<{ workbook: unknown; masterId?: string; composed: boolean; error?: string }>;
+
+// ---- C1c：目录设计器适配器用纯函数 ----
+export function splitFormFaceKtls(workbook: unknown): { entryKtl: string; reportKtl: string };
+export function mergeFormFaceKtls(entryKtl?: string | null, reportKtl?: string | null): string;
+export function hasUsableFaceLayout(ktl: string): boolean;
+export function mergeMiddleComposeMeta(
+  workbook: unknown,
+  meta: { masterId?: string; importColWidths?: number[]; importRowHeights?: number[] },
+): unknown;
+export function readMiddleComposeMeta(workbook: unknown): {
+  masterId?: string;
+  importColWidths?: number[];
+  importRowHeights?: number[];
+  columnPrecisionMul?: number;
+} | null;
+export function validateFieldsFormulas(fields: FormulaField[]): string | null;
+export function prepageSaveError(workbook: unknown): string | null;
+export function readPrepage(workbook: unknown): { sheetId?: string; rules: unknown[] } | null;
+export function isPrepageSheet(workbook: unknown, sheetId: string): boolean;
+export function parseKtlSafe(ktl: string): { workbook: any; diagnostics: { severity: string; message: string }[] };
+export function workbookToKtlText(workbook: unknown): string;
+
+// ---- C2a：实例填报（KtReportFill + 画布三件套） ----
+export interface SheetCommonStore {
+  legacy: Record<string, string>;
+  byReport: Record<string, Record<string, string>>;
+}
+export function parseSheetCommonStore(raw?: string | null): SheetCommonStore;
+export function stringifySheetCommonStore(store?: SheetCommonStore | null): string;
+
+export type KtFillCommonField = { fieldKey: string; label: string; dataType?: string; enabled?: boolean };
+export type KtFillSheet = {
+  sheetId: string;
+  formDefId: string;
+  formName?: string;
+  tabTitle?: string;
+  formRole?: string;
+  entryMiddleKtl?: string | null;
+  reportMiddleKtl?: string | null;
+  middleKtl?: string | null;
+  showEntry?: boolean;
+  showReport?: boolean;
+  commonFieldKeys?: string[];
+  fields?: ArtifactField[];
+};
+export type KtFillComboMember = { formDefId: string; tabTitle?: string; formRole?: string };
+export type ComboMapRule = {
+  sourceFormDefId: string;
+  sourceFieldCode: string;
+  targetFormDefId: string;
+  targetFieldCode: string;
+  mode?: string;
+  formula?: string;
+  whenMode?: string;
+  sourceRoundKind?: string;
+  sourceRoundDigits?: number | null;
+  targetRoundKind?: string;
+  targetRoundDigits?: number | null;
+  sourceSlot?: number | null;
+};
+export type KtFillSnapshot = {
+  common: Record<string, string>;
+  tabCommons: Record<string, SheetCommonStore>;
+  values: Record<string, Record<string, string>>;
+  handEdited: Record<string, string[]>;
+};
+export interface KtReportFillHandle {
+  collect(): KtFillSnapshot;
+  getCommonField(key: string): string;
+  setCommonField(key: string, val: string): void;
+}
+export type KtCommonFieldCtx = {
+  value: string;
+  readOnly: boolean;
+  setValue: (v: string) => void;
+  setField: (key: string, v: string) => void;
+  bag: (key: string) => string;
+  label: string;
+};
+export const KtReportFill: React.ForwardRefExoticComponent<
+  React.RefAttributes<KtReportFillHandle> & {
+    instanceId: string;
+    kind: string;
+    sheets: KtFillSheet[];
+    commonFields: KtFillCommonField[];
+    comboMembers?: KtFillComboMember[];
+    comboMappings?: ComboMapRule[];
+    comboCommonFieldKeys?: string[];
+    initialCommon?: Record<string, string>;
+    initialTabCommons?: Record<string, SheetCommonStore>;
+    initialValues?: Record<string, Record<string, string>>;
+    initialHandEdited?: Record<string, string[]>;
+    version?: unknown;
+    readOnly?: boolean;
+    onSnapshot?: (snap: KtFillSnapshot) => void;
+    onActiveSheetChange?: (sheet: KtFillSheet | undefined) => void;
+    previewBar?: ReactNode;
+    toolbar?: ReactNode;
+    hint?: ReactNode;
+    title?: string;
+    leftTitle?: string;
+    renderCommonField?: (f: KtFillCommonField, ctx: KtCommonFieldCtx) => ReactNode;
+    leftFooter?: ReactNode;
+    withPreview?: boolean;
+    previewExtra?: {
+      fallbackLabName?: string;
+      staffSigners?: unknown[];
+      sampleComposeKeys?: string[] | null;
+      sampleFieldLabel?: (key: string) => string;
+      pageChrome?: unknown;
+      request?: <T>(path: string, init?: RequestInit) => Promise<T>;
+      scheme?: any;
+      onSchemeChange?: (s: any, b: any) => void;
+      loadMaster?: (masterId: string) => Promise<string | null>;
+    };
+    dicts?: Record<string, { value: string; label: string }[]>;
+    className?: string;
+  }
+>;
+export function InstanceFillSheet(props: {
+  ktl?: string | null;
+  fields?: ArtifactField[];
+  values?: Record<string, string>;
+  readOnly?: boolean;
+  hideBoundCodesHint?: boolean;
+  showBoundCodes?: boolean;
+  mappedCodes?: string[];
+  handEditedCodes?: string[];
+  mappingTips?: Record<string, string>;
+  dicts?: Record<string, { value: string; label: string }[]>;
+  digitOverlays?: unknown;
+  omitTrailingZerosOverride?: boolean;
+  reportSheets?: { id: string; name: string }[];
+  reportSheetId?: string;
+  onReportSheetChange?: (id: string) => void;
+  /** 组合设计：点绑定格挑字段 */
+  onPickBind?: (info: { fieldCode: string; bagKey: string }) => void;
+  pickedBagKey?: string | null;
+  face?: "entry" | "report";
+  onChange?: (code: string, val: string, meta?: { handEdit?: boolean; restore?: boolean; blur?: boolean; remove?: boolean }) => void;
+}): JSX.Element;
+export function InstanceFillLayout(props: any): JSX.Element;
+// ---- C2b：宿主薄壳用纯函数 ----
+export function applyComboMappingsToSheets(
+  valuesBySheet: Record<string, Record<string, string>>,
+  sheets: { sheetId: string; formDefId: string; fields?: any[] }[],
+  mappings: ComboMapRule[],
+  handsBySheet: Record<string, string[]>,
+): Record<string, Record<string, string>>;
+export function applyComboMappings(...args: any[]): any;
+export function mappingLine(opts: any): string;
+export function applySheetFormulas(bag: Record<string, string>, fields: any[], hands?: string[]): Record<string, string>;
+export function codesMatch(list: string[] | undefined, code: string): boolean;
+export function fieldCodeFromBindKey(bindKey: string): string | null;
+export function fieldHasFormula(field: any): boolean;
+export function evalFormula(formula: string, bag: Record<string, string>): string | null;
+export function validateFormula(formula?: string | null, knownCodes?: string[]): string | null;
+// C2c：公式引擎全量面（正本单源）
+export type FormulaField = {
+  fieldCode: string;
+  formula?: string | null;
+  roundKind?: string | null;
+  roundDigits?: number | null;
+  readOnly?: boolean;
+  tableRelation?: number | null;
+};
+export const FORMULA_FNS: { label: string; insert: string }[];
+export function normalizeDialect(formula: string): string;
+export function currentToken(text: string, caret: number): { start: number; end: number; token: string };
+export function suggestFormulaTokens(
+  text: string,
+  caret: number,
+  fields: { fieldCode: string; label: string }[],
+): { insert: string; label: string; kind: "field" | "fn" }[];
+export const OMIT_TRAILING_ZEROS_KEY: string;
+export const OMIT_TRAILING_ZEROS_EVENT: string;
+export function loadOmitTrailingZeros(): boolean;
+export function saveOmitTrailingZeros(on: boolean): void;
+export function applyRound(raw: string, kind?: string | null, digits?: number | null): string;
+export function formatRoundDisplay(raw: string, kind?: string | null, digits?: number | null, omitTrailingZeros?: boolean): string;
+export function formatFieldBag(
+  bag: Record<string, string>,
+  fields: { fieldCode: string; roundKind?: string | null; roundDigits?: number | null }[],
+  omitTrailingZeros?: boolean,
+): Record<string, string>;
+export function formatReportFieldData<T extends { m?: Record<string, unknown> }>(
+  data: T,
+  fields: { fieldCode: string; roundKind?: string | null; roundDigits?: number | null }[],
+  omitTrailingZeros?: boolean,
+): T;
+export function stripFieldDataTrailingZeros<T extends { m?: Record<string, unknown> }>(data: T): T;
+export function expandFormulaFns(formula: string): string;
+export function isSubField(f: { fieldCode: string; tableRelation?: number | null }): boolean;
+export function isSubtableField(f: FormulaField | undefined, fieldCode: string): boolean;
+export function markLabel(code?: string | null): string;
+export function listSubRows(bag: Record<string, string>): { sid: number; slot: number }[];
+export function projectRow(bag: Record<string, string>, sid: number, slot: number): Record<string, string>;
+export function fieldHandLocked(hands: Set<string>, code: string, sid?: number, slot?: number): boolean;
+export function readFieldSlots(
+  bag: Record<string, string>,
+  fieldCode: string,
+): { key: string; value: string; sid?: number; slot: number }[];
+export function inferSubSid(field: FormulaField | undefined, bag: Record<string, string>, fieldCode: string, srcSid?: number): number;
+export function writeMappedValue(
+  bag: Record<string, string>,
+  field: FormulaField | undefined,
+  fieldCode: string,
+  value: string,
+  srcSid: number | undefined,
+  slot: number,
+): void;
+export function extractFieldRefs(formula: string): string[];
+export function trialFormula(formula: string, fields: { fieldCode: string }[], kind?: string | null, digits?: number | null): string | null;
+export function emptySheetCommonStore(): SheetCommonStore;
+export const FILL_LEFT_COLLAPSED_KEY: string;
+export const FILL_LEFT_COMMON: string;
+export const FILL_LEFT_MEMBER: string;
+export function loadFillLeftCollapsed(): boolean;
+export function saveFillLeftCollapsed(collapsed: boolean): void;
+export function coalesceCommon(
+  inst: Record<string, string>,
+  tab: Record<string, string>,
+  skipNos?: boolean,
+): Record<string, string>;
+export function isSignCommonField(fieldKey?: string | null): boolean;
+export const RECORD_SIGN_LABELS: Record<string, string>;
+export const REPORT_SIGN_LABELS: Record<string, string>;
+export const SHEET_COMMON_BY_REPORT: string;
+export function coalesceMemberCommon(inst: Record<string, string>, store?: SheetCommonStore | null): Record<string, string>;
+export function coalesceReportPageCommon(inst: Record<string, string>, store: SheetCommonStore | null | undefined, reportSheetId: string): Record<string, string>;
+export function reportPageOverlay(store: SheetCommonStore | null | undefined, reportSheetId: string): Record<string, string>;
+export function setReportPageOverlayField(store: SheetCommonStore | null | undefined, reportSheetId: string, key: string, val: string): SheetCommonStore;
+export function setSheetLegacyField(store: SheetCommonStore | null | undefined, key: string, val: string): SheetCommonStore;
+export function commonFieldLabel(key: string, kind: string | undefined, fallback?: string): string;
+export function orderFillEntryFields<T extends { fieldKey: string }>(fields: T[]): T[];
+export function isFillNoKey(key: string): boolean;
+export function enrichPreviewCommon(common: Record<string, string>, opts?: any): Record<string, string>;
+export function stripFillDefaultBag(bag: Record<string, string>): Record<string, string>;
+export function stripFillDefaultStore(store?: SheetCommonStore | null): SheetCommonStore;
+export function recordNoLabelForKind(kind?: string): string;
+export const DEFAULT_SAMPLE_COMPOSE_KEYS: string[];
+export const SAMPLE_INFO_KEY: string;
+export const SAMPLE_INFO_LABEL: string;
+export function normalizeSampleComposeKeys(keys?: string[] | null): string[];
+export function parseSampleComposeKeys(raw?: string | null): string[];
+export function listVisibleReportSheets(reportKtl?: string | null, entryKtl?: string | null, bag?: any, opts?: { showReport?: boolean }): { id: string; name: string }[];
+export function reportWorkbookForPreview(reportKtl: string | null | undefined, entryKtl: string | null | undefined, bag: any, opts?: { treatAsEmpty?: boolean; showReport?: boolean }): { workbook: any; emptyHint: string };
+export const PREPAGE_EMPTY_HINT: string;
+export type KtFormField = ArtifactField;
+export type StaffSignerLite = { staffId: string; displayName: string; certNos: string[]; hasSignImage?: boolean; signImageSrc?: string };
+export const PERSON_SIGN_SLOTS: readonly { personKey: string; label: string }[];
+export function staffIdKey(personKey: string): string;
+export function certNoKey(personKey: string): string;
+export function formatTestDateCn(raw?: string): string;
+export function formatTestDateText(start?: string, end?: string): string;
+export function sampleNoFromRecordNo(recordNo?: string): string;
+export function useFillLeftScope(
+  reportSheets: { id: string; name: string }[],
+  resetKey?: string,
+  combo?: boolean,
+): {
+  leftScope: string;
+  scopeLocked: boolean;
+  editingMember: boolean;
+  editingReport: boolean;
+  previewSheetId?: string;
+  onLeftScopeChange: (v: string) => void;
+};
+export function InstanceFillPreviewPane(props: any): JSX.Element;