@quadrats/react 1.0.0 → 1.1.1

package/table/utils/helper.d.ts

@@ -0,0 +1,186 @@
+import { Element } from '@quadrats/core';
+import { TableElement, ColumnWidth } from '@quadrats/common/table';
+import { QuadratsReactEditor } from '@quadrats/react';
+import { AlignValue } from '@quadrats/common/align';
+/**
+ * 分配百分比寬度，確保總和為 100%
+ * 前 n-1 個欄位使用四捨五入的平均值，最後一個欄位使用剩餘寬度
+ * @param count - 欄位數量
+ * @returns 百分比陣列，總和為 100%
+ */
+export declare function distributeEqualPercentages(count: number): number[];
+/**
+ * 等比例縮減現有百分比並加入新欄位
+ * 前 n-1 個縮減後的欄位使用四捨五入，最後一個縮減欄位使用剩餘寬度
+ * @param currentPercentages - 當前的百分比陣列
+ * @param newColumnPercentage - 新欄位要佔的百分比
+ * @param insertIndex - 新欄位插入的位置（0-based）
+ * @returns 新的百分比陣列，總和為 100%
+ */
+export declare function scalePercentagesWithNewColumn(currentPercentages: number[], newColumnPercentage: number, insertIndex: number): number[];
+export interface TableElements {
+    tableMainElement: TableElement | null;
+    tableBodyElement: TableElement | null;
+    tableHeaderElement: TableElement | null;
+}
+export interface TablePaths {
+    tableMainPath: number[];
+    tableBodyPath: number[];
+    tableHeaderPath: number[] | null;
+}
+export interface TableStructure extends TableElements, TablePaths {
+    headerRowCount: number;
+    columnCount: number;
+    firstRow: Element | null;
+}
+/**
+ * 提取表格的所有基本元素
+ */
+export declare function getTableElements(element: TableElement): TableElements;
+/**
+ * 獲取表格的完整結構
+ */
+export declare function getTableStructure(editor: QuadratsReactEditor, element: TableElement): TableStructure | null;
+/**
+ * 檢查列是否有 pinned cells
+ */
+export declare function hasColumnPinnedCells(tableStructure: TableStructure, columnIndex: number): boolean;
+/**
+ * 檢查是否有任何 pinned columns
+ */
+export declare function hasAnyPinnedColumns(tableStructure: TableStructure): boolean;
+/**
+ * 檢查是否有任何 pinned rows
+ */
+export declare function hasAnyPinnedRows(tableStructure: TableStructure): boolean;
+/**
+ * 創建新的 table cell
+ */
+export declare function createTableCell(referenceCell?: TableElement, overrideProps?: Partial<TableElement>): TableElement;
+/**
+ * 獲取參考 row
+ */
+export declare function getReferenceRowFromHeaderOrBody(HeaderOrBodyContainer: TableElement, rowIndex: number): TableElement | undefined;
+/**
+ * 收集指定範圍的 cells
+ * @param tableStructure - 表格結構
+ * @param scope - 'table' | 'column'
+ * @param columnIndex - 當 scope 為 'column' 時需要指定
+ * @returns cells 陣列
+ */
+export declare function collectCells(tableStructure: TableStructure, scope: 'table' | 'column', columnIndex?: number): Element[];
+/**
+ * 設定指定 cells 的 align
+ * @param editor - Slate editor
+ * @param cells - 要設定 align 的 cell 元素陣列
+ * @param alignValue - align 值
+ */
+export declare function setAlignForCells(editor: QuadratsReactEditor, cells: Element[], alignValue: AlignValue): void;
+/**
+ * 獲取指定 cells 的 align 狀態
+ * @param cells - 要檢查的 cell 元素陣列
+ * @returns 如果所有 cell 的 align 都相同則返回該值，否則返回 'left'
+ */
+export declare function getAlignFromCells(cells: Element[]): AlignValue;
+/**
+ * 獲取釘選欄位的資訊
+ * @param tableElement - 表格最外層元素
+ * @returns 釘選欄位的索引陣列和總寬度百分比
+ */
+export declare function getPinnedColumnsInfo(tableElement: TableElement): {
+    pinnedColumnIndices: number[];
+    totalPinnedPercentage: number;
+};
+/**
+ * 強制調整釘選欄位寬度以符合最大限制
+ * @param columnWidths - 當前欄位寬度陣列
+ * @param pinnedColumnIndices - 釘選欄位索引陣列
+ * @returns 調整後的欄位寬度陣列
+ */
+export declare function enforcePinnedColumnsMaxWidth(columnWidths: ColumnWidth[], pinnedColumnIndices: number[]): ColumnWidth[];
+/**
+ * 獲取表格的欄位寬度陣列
+ * 當有釘選欄位時：
+ * - 釘選欄位使用 percentage
+ * - 未釘選欄位使用 pixel（基於剩餘空間平均分配）
+ * @param tableElement - 表格最外層元素
+ * @param tableWidth - 表格容器的實際寬度（pixel），用於計算 pixel 寬度
+ * @returns 欄位寬度陣列
+ */
+export declare function getColumnWidths(tableElement: TableElement, tableWidth?: number): ColumnWidth[];
+/**
+ * 設定表格的欄位寬度
+ * @param editor - Slate editor
+ * @param tableElement - 表格最外層元素
+ * @param columnWidths - 欄位寬度陣列
+ */
+export declare function setColumnWidths(editor: QuadratsReactEditor, tableElement: TableElement, columnWidths: ColumnWidth[]): void;
+/**
+ * 計算新增欄位後的欄位寬度
+ * - 如果所有欄位都是 percentage：按比例縮減現有欄位，新欄位佔平均寬度
+ * - 如果有混合模式（percentage + pixel）：
+ *   * 如果用戶操作的欄位是 pinned column：新欄位使用 percentage（需要調整 pinned columns 的百分比）
+ *   * 如果用戶操作的欄位是 unpinned column：新欄位使用 pixel（與其他 pixel 欄位相同寬度）
+ *
+ * @param currentWidths - 當前的欄位寬度陣列
+ * @param insertIndex - 新欄位插入的位置（0-based）
+ * @param pinnedColumnIndices - 當前釘選欄位的索引陣列（插入前的索引）
+ * @param operatingColumnIndex - 用戶實際操作的欄位索引（用於判斷是在 pinned 還是 unpinned column 操作）
+ * @returns 新的欄位寬度陣列
+ */
+export declare function calculateColumnWidthsAfterAdd(currentWidths: ColumnWidth[], insertIndex: number, pinnedColumnIndices?: number[], operatingColumnIndex?: number): ColumnWidth[];
+/**
+ * 計算刪除欄位後的欄位寬度
+ * 此函數會智慧處理欄位寬度的重新分配：
+ * - 如果所有欄位都是 percentage：按比例放大剩餘欄位
+ * - 如果有 pixel 欄位：保持 pixel 欄位不變，只調整 percentage 欄位
+ *
+ * @param currentWidths - 當前的欄位寬度陣列
+ * @param deleteIndex - 要刪除的欄位索引（0-based）
+ * @returns 新的欄位寬度陣列
+ */
+export declare function calculateColumnWidthsAfterDelete(currentWidths: ColumnWidth[], deleteIndex: number): ColumnWidth[];
+/**
+ * 計算拖曳後的欄位寬度
+ * 處理釘選欄位的特殊邏輯：
+ * - 情況 1：未釘選欄位（pixel）與未釘選欄位（pixel）之間：直接改變 pixel 值，允許超出容器
+ * - 情況 2：釘選欄位（percentage）與釘選欄位（percentage）之間：互相調整，且總和不超過 40%
+ * - 情況 3：釘選欄位（percentage）與未釘選欄位（pixel）之間：
+ *   * 只調整釘選欄位的百分比（不超過 40% 總限制）
+ *   * 當 table 未溢出（寬度 < container）時，重新計算所有未釘選欄位的 pixel 值以維持 100%
+ *   * 當 table 已溢出時，只調整下一個欄位的 pixel 值
+ *   * 當達到 40% 上限時，停止調整
+ * - 預設情況：兩個都是 percentage 但都不是釘選欄位（正常模式）
+ *
+ * @param currentWidths - 當前的欄位寬度陣列
+ * @param columnIndex - 被調整的欄位索引
+ * @param deltaPercentage - 寬度變化量（百分比）
+ * @param deltaPixel - 寬度變化量（pixel）
+ * @param pinnedColumnIndices - 釘選欄位的索引陣列
+ * @returns 新的欄位寬度陣列
+ */
+export declare function calculateResizedColumnWidths(currentWidths: ColumnWidth[], columnIndex: number, deltaPercentage: number, deltaPixel: number, pinnedColumnIndices?: number[]): ColumnWidth[];
+/**
+ * 移動或交換欄位寬度設定
+ * @param currentWidths - 當前的欄位寬度陣列
+ * @param sourceIndex - 來源欄位的索引
+ * @param targetIndex - 目標欄位的索引
+ * @param mode - 'swap' 為交換兩個位置，'move' 為移動到目標位置
+ * @returns 處理後的欄位寬度陣列
+ */
+export declare function moveOrSwapColumnWidth(currentWidths: ColumnWidth[], sourceIndex: number, targetIndex: number, mode?: 'swap' | 'move'): ColumnWidth[];
+/**
+ * 將 columnWidths 轉換為混合模式（釘選欄位用 percentage，未釘選欄位用 pixel）
+ * @param currentWidths - 當前的欄位寬度陣列
+ * @param pinnedColumnIndices - 釘選欄位的索引陣列
+ * @param tableWidth - 表格的實際寬度（pixel）
+ * @returns 轉換後的欄位寬度陣列
+ */
+export declare function convertToMixedWidthMode(currentWidths: ColumnWidth[], pinnedColumnIndices: number[], tableWidth: number): ColumnWidth[];
+/**
+ * 將混合模式的欄位寬度轉換回純百分比模式
+ * 當所有 pinned columns 都被 unpin 後，需要將 pixel 欄位轉換回 percentage
+ * @param currentWidths - 當前的欄位寬度陣列（混合模式）
+ * @returns 轉換後的純百分比欄位寬度陣列，總和為 100%
+ */
+export declare function convertToPercentageMode(currentWidths: ColumnWidth[]): ColumnWidth[];