@k-table/report 0.0.1 → 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,827 @@
+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;
+  constructor(message: string, status?: number);
+}
+export class KtNotFoundError extends KtStoreError {
+  constructor(message?: string);
+}
+export class KtConflictError extends KtStoreError {
+  readonly current: unknown;
+  constructor(message: string, current: unknown);
+}
+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;
+  kind: ArtifactKind;
+  ktl: string;
+  masterId?: string;
+  faces?: { fill?: string; report?: string };
+  commonFieldKeys?: string[];
+  /** 字段目录（设计器字段/公式面板数据源） */
+  fields?: ArtifactField[];
+  /** 录入面/报表面显示闸（缺省 = 两面都显示） */
+  showFaces?: { entry?: boolean; report?: boolean };
+  /** 宿主角色语义，透传不解释 */
+  formRole?: string;
+  etag?: string;
+}
+export interface ArtifactMeta {
+  id: string;
+  name: string;
+  kind: ArtifactKind;
+  updatedAt?: string;
+}
+export type ValueBag = Record<string, unknown>;
+export interface CommonField {
+  key: string;
+  label: string;
+  dataType?: string;
+  zone?: string;
+  entryDefault?: unknown;
+}
+export interface ArtifactStore {
+  list(kind?: ArtifactKind): Promise<ArtifactMeta[]>;
+  get(id: string): Promise<Artifact>;
+  save(artifact: Artifact): Promise<Artifact>;
+  create?(input: Pick<Artifact, "name" | "kind">): Promise<Artifact>;
+  remove?(id: string): Promise<void>;
+}
+export interface InstanceRecord {
+  artifactId: string;
+  values: ValueBag;
+  common?: ValueBag;
+  tabCommon?: ValueBag;
+}
+export interface InstanceStore {
+  get(id: string): Promise<InstanceRecord>;
+  save(id: string, patch: { values?: ValueBag; common?: ValueBag; tabCommon?: ValueBag }): Promise<void>;
+  list?(artifactId?: string): Promise<{ id: string; artifactId: string }[]>;
+  create?(input: { artifactId: string }): Promise<{ id: string }>;
+}
+export interface VersionRev {
+  rev: string;
+  kind: string;
+  id: string;
+  at: string;
+  parent?: string | null;
+  by?: string | null;
+  note?: string | null;
+  files: Record<string, string>;
+  meta?: Record<string, unknown>;
+}
+export interface VersionStore {
+  log(kind: string, id: string): Promise<{ head: string | null; items: VersionRev[] }>;
+  get(rev: string): Promise<VersionRev>;
+  readFile(rev: string, path: string): Promise<Uint8Array>;
+  commit(input: {
+    kind: string;
+    id: string;
+    files?: Record<string, Uint8Array | string>;
+    by?: string;
+    note?: string;
+    meta?: Record<string, unknown>;
+  }): Promise<VersionRev>;
+  restore(kind: string, id: string, rev: string, by?: string): Promise<VersionRev>;
+}
+export interface FsStoreOptions {
+  driver: "fs";
+  root: string;
+  layout?: "content-addressed";
+}
+export type StoreDescriptor = { driver: "memory" } | FsStoreOptions;
+
+export const ARTIFACT_FILE_META: "meta.json";
+export const ARTIFACT_FILE_BODY: "body.ktl";
+export const ARTIFACT_FILE_FILL: "faces/fill.ktl";
+export const ARTIFACT_FILE_REPORT: "faces/report.ktl";
+export function artifactToFiles(a: Artifact): Record<string, string>;
+export function filesToArtifact(files: Record<string, string>, fallbackId?: string): Artifact;
+export function filesEqual(a: Record<string, string>, b: Record<string, string>): boolean;
+
+export function createMemoryArtifactStore(seed?: Artifact[]): ArtifactStore;
+export function createMemoryInstanceStore(seed?: Record<string, InstanceRecord>): InstanceStore;
+export function createMemoryVersionStore(artifacts: ArtifactStore): VersionStore;
+export function createHttpArtifactStore(baseUrl: string): ArtifactStore;
+export function createHttpInstanceStore(baseUrl: string): InstanceStore;
+export function createHttpVersionStore(baseUrl: string): VersionStore;
+export function isStoreInstance(v: unknown): boolean;
+
+export type KtSku = "report" | "table";
+export type KtColorScheme = "light" | "dark" | "system";
+export type KtTypeScale = "sm" | "md" | "lg";
+export type KtDensity = "compact" | "comfortable" | "spacious";
+export type KtThemePresetId = "paper" | "blue" | "green" | "violet";
+export type KtUiStyleId = "default" | "arco";
+export type KtUiStyle = {
+  id: KtUiStyleId;
+  name: string;
+  token?: Record<string, unknown>;
+  components?: Record<string, unknown>;
+};
+export type KtChromeSlot =
+  | "pageBg"
+  | "headerBg"
+  | "border"
+  | "text"
+  | "textSecondary"
+  | "chromeBar"
+  | "chromeTab"
+  | "canvasPad"
+  | "previewHost";
+export type KtChromeColors = Record<KtChromeSlot, string>;
+export type KtThemeChrome = Partial<KtChromeColors> & { extra?: Record<string, string> };
+export type KtColorPalette = { primary: string; success: string; warning: string; error: string };
+export type KtThemePreset = {
+  id: KtThemePresetId;
+  name: string;
+  palette: KtColorPalette;
+  forms: { light: KtChromeColors; dark: KtChromeColors };
+};
+export interface KtTheme {
+  colorScheme?: KtColorScheme;
+  colorPrimary?: string;
+  colorSuccess?: string;
+  colorWarning?: string;
+  colorError?: string;
+  typeScale?: KtTypeScale;
+  density?: KtDensity;
+  radius?: number;
+  inheritHost?: boolean;
+  presetId?: KtThemePresetId;
+  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";
+  /** 商业授权串（kt1.<payload>.<sig>）。缺省 = 试用模式：预览/打印带水印。 */
+  license?: string;
+  storage: {
+    artifacts: ArtifactStore | { driver: "memory" } | FsStoreOptions;
+    instances?: InstanceStore | { driver: "memory" } | FsStoreOptions;
+    versions?: false | VersionStore | FsStoreOptions;
+    httpBaseUrl?: string;
+  };
+  versions?: { commitPolicy?: "promote" | "onSave"; kinds?: string[] };
+  ui?: { theme?: KtTheme; persistThemeKey?: string; licenseBanner?: boolean };
+  features?: {
+    master?: boolean;
+    fill?: boolean;
+    excelImport?: boolean;
+    sourceDrawer?: boolean;
+    formula?: boolean;
+    combo?: boolean;
+    versions?: boolean;
+    print?: boolean;
+    pdf?: boolean;
+  };
+  /** 宿主钩子：打印/PDF/预览灌数/设计器字段目录。全部可选。 */
+  hooks?: KtHooks;
+}
+export interface ResolvedFeatures {
+  master: boolean;
+  fill: boolean;
+  excelImport: boolean;
+  sourceDrawer: boolean;
+  formula: boolean;
+  combo: boolean;
+  versions: boolean;
+  print: boolean;
+  pdf: boolean;
+}
+export function resolveFeatures(config: Pick<KtConfig, "sku" | "features">): ResolvedFeatures;
+export function defaultKinds(config: KtConfig): string[];
+export function versionsUiEnabled(config: KtConfig): boolean;
+export function commitPolicyOf(config: KtConfig): "promote" | "onSave";
+export function maybeCommitOnSave(
+  config: KtConfig,
+  versions: VersionStore | undefined,
+  saved: Artifact,
+): Promise<VersionRev | undefined>;
+export function resolveStores(config: KtConfig): {
+  artifacts: ArtifactStore;
+  instances?: InstanceStore;
+  versions?: VersionStore;
+};
+
+export const KT_COLOR_PRIMARY: "#1677ff";
+export const KT_COLOR_SUCCESS: "#52c41a";
+export const KT_COLOR_WARNING: "#faad14";
+export const KT_COLOR_ERROR: "#ff4d4f";
+export const KT_INHERIT_HOST_DEFAULT: false;
+export const DEFAULT_KT_PRESET_ID: "blue";
+export const KT_THEME_PRESETS: readonly KtThemePreset[];
+export const KT_CHROME_SLOTS: readonly KtChromeSlot[];
+export const KT_CHROME_BG_SLOTS: readonly { key: KtChromeSlot; label: string }[];
+export const KT_CHROME_CSS_VARS: Record<KtChromeSlot, string>;
+export const FORMS_PAGE_BG: "var(--kt-forms-page-bg)";
+export const FORMS_HEADER_BG: "var(--kt-forms-header-bg)";
+export const FORMS_BORDER: "var(--kt-forms-border)";
+export const FORMS_TEXT: "var(--kt-forms-text)";
+export const FORMS_TEXT_SECONDARY: "var(--kt-forms-text-secondary)";
+export const FORMS_CHROME_BAR: "var(--kt-forms-chrome-bar)";
+export const FORMS_CHROME_TAB: "var(--kt-forms-chrome-tab)";
+export const FORMS_CANVAS_PAD: "var(--kt-forms-canvas-pad)";
+export const FORMS_PREVIEW_HOST: "var(--kt-forms-preview-host)";
+export const DEFAULT_KT_UI_STYLE_ID: "default";
+export const KT_UI_STYLES: readonly KtUiStyle[];
+export function isKtUiStyleId(id: string): id is KtUiStyleId;
+export function getKtUiStyle(id?: string): KtUiStyle;
+export function isKtThemePresetId(id: string): id is KtThemePresetId;
+export function getKtPreset(id?: string): KtThemePreset;
+export function applyPresetToTheme(id: KtThemePresetId, prev: KtTheme): KtTheme;
+export function mergeThemePatch(prev: KtTheme, patch: Partial<KtTheme>): KtTheme;
+export function hydrateTheme(base: KtTheme, saved: Partial<KtTheme>): KtTheme;
+export function resolveChrome(theme: KtTheme, scheme: "light" | "dark"): KtChromeColors;
+export function chromeToCssVars(chrome: KtChromeColors, extra?: Record<string, string>): Record<string, string>;
+
+export type KtThemeApi = {
+  theme: KtTheme;
+  scheme: "light" | "dark";
+  chrome: KtChromeColors;
+  setTheme: (patch: Partial<KtTheme>) => void;
+  applyPreset: (id: KtThemePresetId) => void;
+  applyStyle: (id: KtUiStyleId) => void;
+};
+
+export function KtProvider(props: {
+  config: KtConfig;
+  onThemeChange?: (theme: KtTheme) => void;
+  children: ReactNode;
+}): JSX.Element;
+export function useKt(): {
+  config: KtConfig;
+  stores: { artifacts: ArtifactStore; instances?: InstanceStore; versions?: VersionStore };
+  theme: KtTheme;
+  setTheme: (patch: Partial<KtTheme>) => void;
+  applyPreset: (id: KtThemePresetId) => void;
+  applyStyle: (id: KtUiStyleId) => void;
+  scheme: "light" | "dark";
+  chrome: KtChromeColors;
+  kinds: string[];
+  versionsUi: boolean;
+  features: ResolvedFeatures;
+  license: KtLicenseInfo;
+};
+export function useKtOptional(): ReturnType<typeof useKt> | null;
+export function useKtTheme(): KtThemeApi;
+
+export type KtLicenseStatus = "valid" | "missing" | "invalid" | "expired" | "domain-mismatch";
+export interface KtLicensePayload {
+  customer: string;
+  expires: string;
+  sku: string[];
+  domains?: string[];
+  iat?: string;
+  note?: string;
+}
+export interface KtLicenseInfo {
+  status: KtLicenseStatus;
+  payload?: KtLicensePayload;
+  reason?: string;
+}
+export function verifyKtLicense(
+  license: string | undefined | null,
+  opts: { sku: KtSku; hostname?: string | null; now?: Date; publicKey?: string },
+): KtLicenseInfo;
+export function useKtLicense(): KtLicenseInfo;
+export function KtLicenseBanner(): JSX.Element | null;
+
+export function readArtifactAtRev(store: VersionStore, rev: string): Promise<Artifact>;
+export function KtVersionPanel(props: {
+  open: boolean;
+  kind: string;
+  id: string;
+  onClose: () => void;
+  onRestored?: () => void;
+}): JSX.Element | null;
+
+/** 向后兼容别名；正本为 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;
+export function KtReportPreview(props: {
+  artifact?: Artifact;
+  artifactId?: string;
+  store?: ArtifactStore;
+  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;
+}): 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;
+
+export const EMPTY_KTL: string;
+export const SAMPLE_A4_KTL: string;
+export const SAMPLE_DEMO_KTL: string;
+export const SAMPLE_MASTER_KTL: string;
+
+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;
+    };
+    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;