@k-table/report 0.0.1 → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,348 @@
+import type { ReactNode } from "react";
+
+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 interface Artifact {
+  id: string;
+  name: string;
+  kind: ArtifactKind;
+  ktl: string;
+  masterId?: string;
+  faces?: { fill?: string; report?: string };
+  commonFieldKeys?: 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 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;
+  };
+}
+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;
+
+export type DesignerFormField = {
+  fieldId: string;
+  fieldCode: string;
+  label: string;
+  dataType: string;
+  sort: number;
+  formula?: string | null;
+  tableRelation?: number;
+};
+export function withSplitFaces(artifact: Artifact, workbook: unknown): Artifact;
+export function previewKtlOf(artifact: Artifact): string;
+export function KtReportDesigner(props: {
+  artifact?: Artifact;
+  artifactId?: string;
+  store?: ArtifactStore;
+  masters?: { id: string; name: string }[];
+  values?: Record<string, unknown>;
+  formFields?: DesignerFormField[];
+  sheetFaceEnabled?: boolean;
+  onSave?: (a: Artifact) => void;
+  onConflict?: (e: KtConflictError) => void;
+  extraActions?: ReactNode;
+  leadingActions?: ReactNode;
+}): JSX.Element;
+export function KtReportPreview(props: {
+  artifact?: Artifact;
+  artifactId?: string;
+  store?: ArtifactStore;
+  rev?: string;
+  values?: ValueBag;
+  common?: ValueBag;
+  print?: boolean;
+  showVersionPanel?: boolean;
+  extraActions?: ReactNode;
+}): JSX.Element;
+export function KtReportCatalog(props: {
+  store?: ArtifactStore;
+  kinds?: ArtifactKind[];
+  onOpenDesign: (id: string) => void;
+  onOpenPreview: (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 }>;