quickspeadsheet 1.0.0

package/dist/types/runtime-public.d.ts

@@ -0,0 +1,501 @@
+/**
+ * 宿主可见的 runtime / 协同 / IO 陪同类型。
+ * 与 `src/excel/engine/runtime.js`、`useSpread.js` 的 JSDoc 对齐；发布时随 `src/types` 复制到 `dist/types`。
+ */
+
+import type { ExcelIO } from '../excel/core/excelio'
+
+/** createWorkbook 实例在宿主侧常用的最小形状（完整 API 见源码 Workbook 类） */
+export interface SpreadWorkbookInstance {
+  getActiveSheet?: () => unknown
+  toJSON?: (options?: { includeBindingSource?: boolean }) => object
+  fromJSON?: (json: object) => void
+  destroy?: () => void
+  refresh?: () => void
+  calculate?: () => void
+  calculateActiveSheet?: () => void
+  getExtensionHost?: () => unknown
+  setCollaborationSession?: (session: CollaborationSessionLike | null) => void
+  setCollaborationState?: (state: CollaborationStateSnapshot | null) => void
+  [key: string]: unknown
+}
+
+/**
+ * ExcelIO 自 XLSX 解析得到的工作簿 JSON 上可选的 OPC 字段（亦会经 fromJSON 写入 Workbook 元数据）。
+ * - `officeDocumentTarget`：根 `_rels/.rels` 中 officeDocument 的 Target。
+ * - `workbookPartPath`：实际采用的工作簿主部件（含与 `[Content_Types]` Override 冲突时以 officeDocument 为准）。
+ */
+export interface SpreadWorkbookOpcPackageFields {
+  officeDocumentTarget?: string | null
+  workbookPartPath?: string | null
+}
+
+export type { ExcelIO }
+
+/** 公式栏等 UI 组件实例（实现因宿主而异） */
+export type FormulaBoxInstance = Record<string, unknown>
+
+export interface ConnectDocumentInput {
+  documentId?: string
+  sessionId?: string
+  currentSheetId?: string
+  prefetch?: { snapshot?: boolean; versions?: boolean; history?: boolean }
+}
+
+export type CollaborationEventPayload = unknown
+
+export type CollaborationJsonRecord = Record<string, unknown>
+
+export interface PublishOperationsResult {
+  acceptedOperations: CollaborationJsonRecord[]
+  rejectedOperations: CollaborationJsonRecord[]
+  serverRevision: number
+  warnings?: CollaborationJsonRecord[]
+  warningCodes?: string[]
+  warningCount?: number
+}
+
+export interface ApplyRemoteOperationsResult {
+  operations: CollaborationJsonRecord[]
+  conflicts: CollaborationJsonRecord[]
+}
+
+export interface CollaborationHistoryVersionsPage {
+  items: CollaborationJsonRecord[]
+  nextCursor: string | null
+}
+
+export interface CollaborationConnectionError {
+  message?: string
+  stage?: string
+  code?: string
+  status?: number
+  retryable?: boolean
+  requiresSnapshot?: boolean
+  serverRevision?: number
+  failedOperationIds?: string[]
+}
+
+export interface CollaborationPrefetchedSnapshotMeta {
+  documentId?: string
+  versionId?: string | null
+  serverRevision?: number
+  schemaVersion?: string | null
+  integrityHash?: string | null
+}
+
+export interface CollaborationBulkConflictResolutionSummary {
+  strategy?: 'acceptRemote' | 'keepLocal' | 'manual' | string
+  totalCount?: number
+  successCount?: number
+  failedCount?: number
+  syncedConflictCount?: number
+  historyReloadCount?: number
+  resolvedAt?: string
+}
+
+export interface CollaborationStateSnapshot {
+  actor?: unknown
+  collaborationMode?: 'remote' | 'mock'
+  documentId?: string
+  sessionId?: string
+  connectionStatus?:
+    | 'idle'
+    | 'connecting'
+    | 'syncing'
+    | 'online'
+    | 'degraded'
+    | 'offline'
+    | 'reconnecting'
+    | 'conflicted'
+    | 'readonly'
+  connectionQuality?: string
+  conflictResolveMode?: 'resolve-only' | 'resolve-then-publish' | 'auto' | string
+  conflictResolvePolicy?: 'auto' | 'always' | 'never' | string
+  baseRevision?: number
+  lastServerRevision?: number
+  pendingOperations?: CollaborationJsonRecord[]
+  pendingConflicts?: CollaborationJsonRecord[]
+  currentPermissions?: unknown
+  collaborators?: CollaborationJsonRecord[]
+  activeLocks?: CollaborationJsonRecord[]
+  capabilities?: Record<string, boolean>
+  lastSyncAt?: string
+  lastError?: CollaborationConnectionError | null
+  lastWarnings?: CollaborationJsonRecord[]
+  lastResolvedConflict?: unknown
+  resolvedConflictHistory?: CollaborationJsonRecord[]
+  lastBulkConflictResolutionSummary?: CollaborationBulkConflictResolutionSummary | null
+  prefetchedSnapshot?: CollaborationPrefetchedSnapshotMeta | null
+  prefetchedVersions?: CollaborationJsonRecord[]
+  prefetchedHistory?: CollaborationJsonRecord[]
+  licenseStatus?: 'valid' | 'expired' | 'invalid' | 'missing' | 'offline-grace' | string
+  licenseSource?: string
+  licenseReason?: string
+  licenseExpiresAt?: string | null
+  licenseEnforcedReadOnly?: boolean
+  [key: string]: unknown
+}
+
+export interface ResolveConflictInput {
+  conflictId?: string
+  strategy?: 'acceptRemote' | 'keepLocal' | 'manual'
+  manualPayload?: unknown
+  resolutionOperation?: CollaborationJsonRecord
+  operations?: CollaborationJsonRecord[]
+}
+
+export interface RemoteReplayReportInput {
+  results?: CollaborationJsonRecord[]
+  serverRevision?: number
+}
+
+export interface RemoteReplayReportResult {
+  ok: boolean
+  failedOperations: CollaborationJsonRecord[]
+  error?: unknown
+}
+
+/** 协同会话外观（适配器可扩展方法） */
+export interface CollaborationSessionLike {
+  getState?: () => CollaborationStateSnapshot | undefined
+  getConflictResolvePolicy?: () => {
+    preferResolveOnly?: boolean
+    resolvePublishPolicy?: 'auto' | 'always' | 'never'
+    [key: string]: unknown
+  }
+  setConflictResolvePolicy?: (input?: {
+    preferResolveOnly?: boolean
+    resolvePublishPolicy?: 'auto' | 'always' | 'never'
+    [key: string]: unknown
+  }) => {
+    preferResolveOnly?: boolean
+    resolvePublishPolicy?: 'auto' | 'always' | 'never'
+    [key: string]: unknown
+  }
+  subscribe?: (listener: (type: string, payload: CollaborationEventPayload) => void) => void | (() => void)
+  connectDocument?: (input?: ConnectDocumentInput) => Promise<unknown>
+  disconnectDocument?: (reason?: string) => Promise<unknown>
+  publishOperations?: (input?: CollaborationJsonRecord) => Promise<PublishOperationsResult>
+  applyRemoteOperations?: (input?: CollaborationJsonRecord) => Promise<ApplyRemoteOperationsResult>
+  fetchDocumentSnapshot?: (input?: CollaborationJsonRecord) => Promise<unknown>
+  syncWorkbookFromServerSnapshot?: (workbook: SpreadWorkbookInstance, input?: CollaborationJsonRecord) => Promise<unknown>
+  fetchHistory?: (input?: CollaborationJsonRecord) => Promise<CollaborationHistoryVersionsPage>
+  fetchVersions?: (input?: CollaborationJsonRecord) => Promise<CollaborationHistoryVersionsPage>
+  fetchPermissions?: (input?: CollaborationJsonRecord) => Promise<unknown>
+  listCollaborators?: (input?: CollaborationJsonRecord) => Promise<CollaborationJsonRecord[]>
+  listConflicts?: (input?: CollaborationJsonRecord) => Promise<CollaborationHistoryVersionsPage>
+  /** 从服务端拉取待处理冲突并写回 `pendingConflicts`（存在 `restAdapter.listConflicts` 时由 sessionManager 实现） */
+  syncPendingConflictsFromServer?: (input?: CollaborationJsonRecord) => Promise<CollaborationJsonRecord[]>
+  resolveConflict?: (input?: ResolveConflictInput) => Promise<unknown>
+  updatePermissions?: (nextPermissions?: CollaborationJsonRecord) => unknown
+  updatePresence?: (item?: CollaborationJsonRecord) => CollaborationJsonRecord[]
+  replacePresence?: (items?: CollaborationJsonRecord[]) => CollaborationJsonRecord[]
+  replaceVersions?: (items?: CollaborationJsonRecord[]) => CollaborationJsonRecord[]
+  restoreVersion?: (input?: CollaborationJsonRecord) => Promise<unknown>
+  reportRemoteReplayResult?: (input?: RemoteReplayReportInput) => RemoteReplayReportResult
+  retryPendingOperations?: () => Promise<PublishOperationsResult>
+  clearPendingOperations?: () => CollaborationJsonRecord[]
+  clearWarnings?: () => CollaborationJsonRecord[]
+  resetRevision?: (nextRevision?: number) => void
+  updateLicenseState?: (nextLicenseState?: CollaborationJsonRecord) => CollaborationStateSnapshot
+}
+
+export interface RuntimeIoHooks {
+  onStart?: () => void
+  onEnd?: () => void
+  onError?: (error: unknown) => void
+  onProgress?: (info: unknown, total?: unknown) => void
+  signal?: AbortSignal
+  password?: string
+}
+
+export interface RuntimeDownloadRequest {
+  kind: 'json' | 'excel' | string
+  fileName: string
+  contentType?: string
+  text?: string
+  blob?: Blob
+}
+
+export type HostActionReturn = unknown
+
+export interface SpreadRuntimeHostActions {
+  focusFormulaBar?: () => HostActionReturn
+  notify?: (message: string, type?: string) => HostActionReturn
+  openSearch?: () => HostActionReturn
+  openPrintPreview?: () => HostActionReturn
+  showWorkbookSummary?: () => HostActionReturn
+  openVersionHistory?: () => HostActionReturn
+  openHistoryPanel?: () => HostActionReturn
+  openConflictPanel?: () => HostActionReturn
+  refreshCollaborationData?: () => HostActionReturn
+  retryCollaborationConnection?: () => HostActionReturn
+  retryPendingQueue?: () => HostActionReturn
+  clearPendingQueue?: () => HostActionReturn
+  setConflictResolvePolicy?: (payload?: unknown) => HostActionReturn
+  locateResolvedConflict?: (payload?: unknown) => HostActionReturn
+  restoreVersion?: (payload?: unknown) => HostActionReturn
+  resolveAllConflicts?: (payload?: unknown) => HostActionReturn
+  resolveConflictItem?: (payload?: unknown) => HostActionReturn
+  openSettingsPanel?: (payload?: unknown) => HostActionReturn
+  openChartDesigner?: (payload?: unknown) => HostActionReturn
+}
+
+/** collaborationServices 中与适配器相关的弱类型槽位（具体形状见协同实现与 OpenAPI 文档） */
+export interface CollaborationServicesConfig {
+  mode?: 'mock' | 'remote'
+  /** 兼容旧配置：`mock: true` 等价于 `mode: 'mock'` */
+  mock?: boolean
+  /**
+   * 远端严格模式：开启后必须显式提供 REST/WS 地址（或直接注入适配器），
+   * 以避免误用默认 `/api/v1` 与当前 host 的 WS 地址。
+   */
+  strictRemote?: boolean
+  /** 冲突解决时优先只走 resolve 接口；true 时前端不会再额外 publish resolution operation。 */
+  preferResolveOnly?: boolean
+  /** 冲突解决发布策略：auto=后端已应用则不二次 publish；always=总是 publish；never=只走 resolve。 */
+  resolvePublishPolicy?: 'auto' | 'always' | 'never'
+  apiBaseUrl?: string
+  baseUrl?: string
+  realtimeUrl?: string
+  wsUrl?: string
+  getAuthHeader?: () => Record<string, string> | Promise<Record<string, string>>
+  getAuthQuery?: () => Record<string, string | number | boolean> | Promise<Record<string, string | number | boolean>>
+  authQueryTokenKey?: string
+  /** true 时会在 hello payload 中附带 token（默认 false，更安全） */
+  exposeAuthInHello?: boolean
+  mockStore?: unknown
+  mockOptions?: CollaborationJsonRecord
+  restAdapter?: unknown
+  realtimeAdapter?: unknown
+}
+
+export interface HostActionMissingPayload {
+  actionName: string
+  capability?: string
+  args: unknown[]
+}
+
+export interface RuntimeImportUrlResultOk {
+  ok: true
+  json?: object
+}
+
+export interface RuntimeImportUrlResultEmpty {
+  ok: false
+  empty: true
+}
+
+export type RuntimeImportUrlResult = RuntimeImportUrlResultOk | RuntimeImportUrlResultEmpty
+
+export interface RuntimeImportFileResultOk {
+  ok: true
+}
+
+export interface RuntimeImportFileResultFail {
+  ok: false
+  empty?: boolean
+  unsupported?: boolean
+  cancelled?: boolean
+  error?: unknown
+}
+
+export type RuntimeImportFileResult = RuntimeImportFileResultOk | RuntimeImportFileResultFail
+
+/** addIns 数组元素（与 engine addins registry 归一化前兼容） */
+export type RuntimeAddInDefinition = CollaborationJsonRecord & {
+  id?: string
+  title?: string
+  actionType?: string
+  command?: string
+}
+
+export interface SpreadRuntimeOptions {
+  edition?: string
+  capabilities?: Record<string, boolean> | string[]
+  extensionApi?: Record<string, unknown>
+  createExcelIO?: boolean
+  registerBuiltinAddIns?: boolean
+  registerInstalledAddIns?: boolean
+  addIns?: RuntimeAddInDefinition[]
+  documentId?: string
+  collaborationServices?: CollaborationServicesConfig
+  prefetchOnConnect?: { snapshot?: boolean; versions?: boolean; history?: boolean }
+  onCollaborationStateChange?: (state: CollaborationStateSnapshot | null) => void
+  hostActions?: SpreadRuntimeHostActions
+  /** 授权策略：与 `licenseContext` 配合；也可单独用 `forceReadOnly` 演示只读 */
+  licensePolicy?: {
+    /** 强制工作簿引擎只读（会写入 `licenseEnforcedReadOnly`） */
+    forceReadOnly?: boolean
+    /**
+     * 默认 true：存在非空 `licenseContext` 且 `licenseStatus` 为 invalid/expired 时启用引擎只读。
+     * false 时仅降为 community，与旧行为一致（仍可编辑）。
+     */
+    readOnlyOnInvalidOrExpired?: boolean
+    /** 默认 true：当 `expiresAt` 可解析且已过期时，将 valid/offline-grace 收敛为 expired。 */
+    enforceExpiresAt?: boolean
+    /**
+     * 仅用于 `offline-grace`：若设置（毫秒），超过 `expiresAt + offlineGraceMs` 后自动收敛为 expired。
+     * 未设置时保持宿主传入状态。
+     */
+    offlineGraceMs?: number
+    /**
+     * entitlement 到 edition/capabilities 的映射覆盖；key 不区分大小写。
+     * 内置包含 starter/professional/enterprise-collaboration，可在此扩展或覆盖。
+     */
+    entitlementPresetMap?: Record<
+      string,
+      {
+        edition?: string
+        capabilities?: Record<string, boolean> | string[]
+      }
+    >
+    /** 测试或回放场景可注入“当前时间毫秒”。未设置时使用 Date.now()。 */
+    nowMs?: number
+    /** `probeOnline` / `resolveLicenseAccess`：优先用于联网探测的 URL */
+    connectivityCheckUrl?: string
+    /** 探测请求超时（毫秒），默认 3000 */
+    connectivityTimeoutMs?: number
+  }
+  /** 归一化后注入工作簿：授权失败/过期时由 `resolveLicensedRuntimeOptions` 设置 */
+  licenseEnforcedReadOnly?: boolean
+  licenseContext?: Record<string, unknown>
+  /** runtime 初始化后（onReady 前）回传当前授权快照，便于宿主日志/埋点/UI 展示。 */
+  onLicenseStateResolved?: (snapshot: SpreadLicenseSnapshot) => void
+  /** 默认 true：runtime 初始化时按授权状态尝试触发一次 hostActions.notify。 */
+  notifyLicenseStateResolved?: boolean
+  onHostActionMissing?: (payload: HostActionMissingPayload) => HostActionReturn
+  onDownloadRequested?: (request: RuntimeDownloadRequest) => HostActionReturn
+  onReady?: (runtime: SpreadRuntime) => void
+  onDestroy?: (runtime: SpreadRuntime) => void
+}
+
+/** `SpreadExcelViewer` 内置 JWT 授权；设置后忽略 `licenseContext` */
+export interface SpreadLicenseAccessConfig {
+  publicKeyPem: string
+  remoteUrl?: string
+  /** 在线时优先用 HMAC token 向此 URL 换发 ES256 JWT（如 license-server `GET|POST /api/license/jwt`） */
+  remoteJwtExchange?: { url: string; hmacToken: string; method?: 'POST' | 'GET' }
+  storageKey?: string
+  initialToken?: string
+  fetchInit?: RequestInit
+  storage?: {
+    getItem: (key: string) => string | null
+    setItem: (key: string, value: string) => void
+    removeItem: (key: string) => void
+  }
+  fetchImpl?: typeof fetch
+  /** 解析超时（毫秒），0 表示不限制 */
+  resolveTimeoutMs?: number
+  /** 是否在 window online/offline 时重新 `resolveLicenseAccess` 并必要时重建 runtime */
+  refreshOnNetworkChange?: boolean
+  licensePolicy?: SpreadRuntimeOptions['licensePolicy']
+}
+
+/** 与 `initializeExtensionHost` 返回值对齐的最小宿主视图 */
+export interface SpreadExtensionActionsLike {
+  getSpread?: () => SpreadWorkbookInstance | null
+  getActiveSheet?: () => unknown | null
+  getSheetCount?: () => number
+  getActiveSheetName?: () => string
+  focusFormulaBar?: () => unknown
+  openSearch?: () => unknown
+  openPrintPreview?: () => unknown
+  showWorkbookSummary?: () => unknown
+  openVersionHistory?: () => unknown
+  openHistoryPanel?: () => unknown
+  openConflictPanel?: () => unknown
+  refreshCollaborationData?: () => unknown
+  retryCollaborationConnection?: () => unknown
+  retryPendingQueue?: () => unknown
+  clearPendingQueue?: () => unknown
+  setConflictResolvePolicy?: (payload?: unknown) => unknown
+  locateResolvedConflict?: (payload?: unknown) => unknown
+  restoreVersion?: (payload?: unknown) => unknown
+  resolveAllConflicts?: (payload?: unknown) => unknown
+  resolveConflictItem?: (payload?: unknown) => unknown
+  openSettingsPanel?: (payload?: unknown) => unknown
+  openChartDesigner?: (payload?: unknown) => unknown
+  notify?: (message: string, type?: string) => unknown
+  hasCapability?: (capability: string) => unknown
+  /** 授权只读下会 no-op 并通过 notify 提示。 */
+  toggleGridlines?: () => unknown
+  /** 授权只读下会 no-op 并通过 notify 提示。 */
+  toggleFormulas?: () => unknown
+  refreshWorkbook?: () => unknown
+  /** 授权只读下会 no-op 并通过 notify 提示。 */
+  calculateWorkbook?: () => unknown
+  /** 授权只读下会 no-op 并通过 notify 提示。 */
+  calculateActiveSheet?: () => unknown
+  /** 授权只读下会 no-op 并通过 notify 提示。 */
+  recalculateWorkbook?: () => unknown
+  /** 授权只读下会 no-op 并通过 notify 提示。 */
+  insertBuiltinIcon?: (iconKey?: string) => unknown
+  getEdition?: () => string | undefined
+  getCapabilities?: () => Record<string, boolean>
+}
+
+export interface SpreadExtensionHostLike {
+  spread: SpreadWorkbookInstance | null
+  actions: SpreadExtensionActionsLike
+  attach?: (extensionApi?: Record<string, unknown>) => Record<string, unknown> | null
+  getApi?: () => Record<string, unknown> | null
+  run?: (actionName: string, ...args: unknown[]) => unknown
+}
+
+/** `createSpreadRuntime` 返回的授权只读快照，供宿主横幅 / 调试 */
+export interface SpreadLicenseSnapshot {
+  edition: string
+  licenseStatus?: string
+  licenseSource?: string
+  licenseReason?: string
+  licenseEnforcedReadOnly: boolean
+  /** 社区版等：引擎模型只读，但允许在无法授权失效时通过 import 载入内容 */
+  editionViewOnly?: boolean
+  expiresAt?: string | null
+  entitlements: string[]
+}
+
+export interface SpreadRuntime {
+  resolvedEdition: { edition: string; capabilities: Record<string, boolean> }
+  capabilities: Record<string, boolean>
+  spread: SpreadWorkbookInstance
+  workbook: SpreadWorkbookInstance
+  excelIO: ExcelIO | null
+  extensionHost: SpreadExtensionHostLike
+  collaborationSession: CollaborationSessionLike | null
+  getLicenseSnapshot: () => SpreadLicenseSnapshot
+  /** 模型是否不可编辑（`licenseEnforcedReadOnly` 或 `editionViewOnly`） */
+  isLicenseReadOnly: () => boolean
+  importJson: (json: object) => void
+  importFromUrl: (url: string, options?: object) => Promise<RuntimeImportUrlResult>
+  executeImportFromUrl: (url: string, hooks?: RuntimeIoHooks) => Promise<RuntimeImportUrlResult>
+  importFile: (file: File, hooks?: RuntimeIoHooks) => Promise<RuntimeImportFileResult>
+  executeImportFile: (file: File, hooks?: RuntimeIoHooks) => Promise<RuntimeImportFileResult>
+  exportJsonText: () => Promise<string>
+  executeExportJsonText: (hooks?: RuntimeIoHooks) => Promise<string>
+  executeExportJsonDownload: (hooks?: RuntimeIoHooks) => Promise<unknown>
+  exportExcelBlob: () => Promise<Blob>
+  executeExportExcelBlob: (hooks?: RuntimeIoHooks) => Promise<Blob>
+  executeExportExcelDownload: (hooks?: RuntimeIoHooks) => Promise<unknown>
+  getExportFileName: (prefix?: string) => string
+  getCollaborationState: () => CollaborationStateSnapshot | null
+  setConflictResolvePolicy: (input?: {
+    preferResolveOnly?: boolean
+    resolvePublishPolicy?: 'auto' | 'always' | 'never'
+    [key: string]: unknown
+  }) => {
+    preferResolveOnly?: boolean
+    resolvePublishPolicy?: 'auto' | 'always' | 'never'
+    [key: string]: unknown
+  } | null
+  hasCapability: (capability: string) => boolean
+  assertCapability: (capability: string, message?: string) => true
+  runHostAction: (
+    actionName: keyof SpreadRuntimeHostActions | string,
+    capability?: string,
+    ...args: unknown[]
+  ) => HostActionReturn
+  destroy: () => void
+}