kindy-editor 3.2.5 → 3.2.7

package/types/kindy-editor.d.ts

@@ -26,6 +26,12 @@ export interface Participant {
   user?: UserInfo;
 }
 
+/** Search and replace state. */
+export interface SearchState {
+  index: number;
+  total: number;
+}
+
 /** A WeSign signing box with laid-out geometry. `page` is 1-based for WeSign
  *  `PositionInfoRequest.page`; `pageIndex` is the 0-based layout index. */
 export interface SignatureBox {
@@ -196,6 +202,7 @@ export interface EditorPermissions {
   copy: boolean;
   createComment: boolean;
   viewComment: boolean;
+  hostTableMutation?: boolean;
 }
 
 /** A selection/caret in the document (offsets are UTF-16 code units into a
@@ -227,6 +234,73 @@ export type TableAction =
   | "deleteRow" | "deleteColumn" | "deleteTable"
   | "mergeCells" | "unmergeCell";
 
+export type TableCellValue =
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | { text?: string; value?: unknown };
+
+export type HostTableSelection =
+  | TableSelection
+  | {
+      kind?: "cell";
+      table?: string | TablePath;
+      tableId?: string;
+      anchor: TableGridPoint;
+      focus?: TableGridPoint;
+    }
+  | {
+      kind: "row";
+      table?: string | TablePath;
+      tableId?: string;
+      from: number;
+      to?: number;
+    }
+  | {
+      kind: "column";
+      table?: string | TablePath;
+      tableId?: string;
+      from: number;
+      to?: number;
+    }
+  | {
+      kind: "table";
+      table?: string | TablePath;
+      tableId?: string;
+    }
+  | {
+      tableId: string;
+      row?: number;
+      col?: number;
+      fromRow?: number;
+      toRow?: number;
+      fromCol?: number;
+      toCol?: number;
+    }
+  | string;
+
+export interface TableSummary {
+  tableId: string;
+  tablePath: TablePath;
+  path: TablePath;
+  rows: number;
+  cols: number;
+  header: string[];
+  headers?: string[][];
+  hasMergedCells: boolean;
+}
+
+export interface ReplaceTableRowsOptions {
+  /** Number of leading rows to preserve as header (defaults to leading repeatHeader rows, or 1 if table has >= 2 rows). */
+  headerRows?: number;
+  /** Number of trailing rows to preserve as footer (defaults to 0). */
+  footerRows?: number;
+  /** Index of the row to use as formatting template (defaults to first data row after header, or row 0). */
+  sampleRowIndex?: number;
+}
+
 // ===== Review layer (track changes + comments) =============================
 // An attributed, anchored overlay on top of the core document. `getReview()`
 // returns a snapshot; the `reviewChanged` event carries the full layer.
@@ -908,6 +982,15 @@ export interface EditorHandle {
   setTableSelection(selection: TableSelection | null): void;
   canExecuteTableAction(action: TableAction): boolean;
   executeTableAction(action: TableAction): boolean;
+  canExecuteHostTableAction(action: TableAction, selection?: HostTableSelection | TableSelection): boolean;
+  executeHostTableAction(action: TableAction, selection?: HostTableSelection | TableSelection): boolean;
+  setTableCellValue(table: string | TablePath, row: number, column: number, value: TableCellValue): boolean;
+  replaceTableRows(
+    table: string | TablePath,
+    rows: Array<Array<TableCellValue> | Record<string, unknown>>,
+    options?: ReplaceTableRowsOptions,
+  ): boolean;
+  getTables(): TableSummary[];
   // ---- review layer (track changes + comments) ----------------------------
   /** The current editor mode. */
   getMode(): EditMode;
@@ -944,6 +1027,21 @@ export interface EditorHandle {
   clearExternalAnnotations(): void;
   /** Scroll the viewport to reveal a document range with smooth animation. */
   revealRange(range: ExternalRange, options?: RevealRangeOptions): void;
+  /** Scroll the viewport directly to the specified 1-based page number. */
+  goToPage(
+    pageNumber: number,
+    options?: { behavior?: "auto" | "smooth" },
+  ): Promise<boolean>;
+  /** Find & replace. search() highlights all matches, focuses first match, and returns state. */
+  search(query: string, opts?: { matchCase?: boolean; wholeWord?: boolean }): SearchState;
+  /** Navigate between search matches (-1 for previous, 1 for next) and scroll focus to it. */
+  searchNav(dir: 1 | -1): SearchState;
+  /** Replace the currently focused match with text and scroll focus to the next match. */
+  searchReplaceCurrent(replacement: string): SearchState;
+  /** Replace all matches in one atomic transaction. */
+  searchReplaceAll(replacement: string): number;
+  /** Clear search highlights and reset search state. */
+  searchClear(): void;
   /** Live-update {{KEY}} template placeholders in the document without full reload,
    *  preserving zoom, scroll position, and selection. */
   setTemplateVariables(values: TemplateVariableValues, options?: SetTemplateVariablesOptions): void;
@@ -1066,6 +1164,15 @@ export declare class KindyEditor {
   setTableSelection(selection: TableSelection | null): Promise<void>;
   canExecuteTableAction(action: TableAction): boolean;
   executeTableAction(action: TableAction): Promise<boolean>;
+  canExecuteHostTableAction(action: TableAction, selection?: HostTableSelection | TableSelection): boolean;
+  executeHostTableAction(action: TableAction, selection?: HostTableSelection | TableSelection): Promise<boolean>;
+  setTableCellValue(table: string | TablePath, row: number, column: number, value: TableCellValue): Promise<boolean>;
+  replaceTableRows(
+    table: string | TablePath,
+    rows: Array<Array<TableCellValue> | Record<string, unknown>>,
+    options?: ReplaceTableRowsOptions,
+  ): Promise<boolean>;
+  getTables(): TableSummary[];
   getDocId(): string | null;
   getShareLink(): string | null;
   /** Render ephemeral highlight decorations for external comments/annotations.
@@ -1075,6 +1182,11 @@ export declare class KindyEditor {
   clearExternalAnnotations(): Promise<void>;
   /** Scroll the viewport to reveal a document range with smooth animation. */
   revealRange(range: ExternalRange, options?: RevealRangeOptions): Promise<void>;
+  /** Scroll the viewport directly to the specified 1-based page number. */
+  goToPage(
+    pageNumber: number,
+    options?: { behavior?: "auto" | "smooth" },
+  ): Promise<boolean>;
   /** Live-update {{KEY}} template placeholders in the document without full reload,
    *  preserving zoom, scroll position, and selection. */
   setTemplateVariables(values: TemplateVariableValues, options?: SetTemplateVariablesOptions): Promise<void>;
@@ -1122,5 +1234,15 @@ export declare class KindyEditor {
   setQRCode(config: QRCodeConfig | null): void;
   /** Get current header/footer QR code configuration. */
   getQRCode(): QRCodeConfig | undefined;
+  /** Find & replace. search() highlights all matches, focuses first match, and returns state. */
+  search(query: string, opts?: { matchCase?: boolean; wholeWord?: boolean }): Promise<SearchState>;
+  /** Navigate between search matches (-1 for previous, 1 for next) and scroll focus to it. */
+  searchNav(dir: 1 | -1): Promise<SearchState>;
+  /** Replace the currently focused match with text and scroll focus to the next match. */
+  searchReplaceCurrent(replacement: string): Promise<SearchState>;
+  /** Replace all search matches in document in a single atomic undoable transaction. */
+  searchReplaceAll(replacement: string): Promise<number>;
+  /** Clear search highlights and reset search state. */
+  searchClear(): Promise<void>;
   destroy(): void;
 }