1 | /**
|
2 | * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
|
3 | * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
|
4 | */
|
5 | /**
|
6 | * @module table/utils/structure
|
7 | */
|
8 | import type { Element, Writer } from 'ckeditor5/src/engine';
|
9 | import { type TableSlot } from '../tablewalker';
|
10 | import type TableUtils from '../tableutils';
|
11 | /**
|
12 | * Returns a cropped table according to given dimensions.
|
13 |
|
14 | * To return a cropped table that starts at first row and first column and end in third row and column:
|
15 | *
|
16 | * ```ts
|
17 | * const croppedTable = cropTableToDimensions( table, {
|
18 | * startRow: 1,
|
19 | * endRow: 3,
|
20 | * startColumn: 1,
|
21 | * endColumn: 3
|
22 | * }, writer );
|
23 | * ```
|
24 | *
|
25 | * Calling the code above for the table below:
|
26 | *
|
27 | * 0 1 2 3 4 0 1 2
|
28 | * ┌───┬───┬───┬───┬───┐
|
29 | * 0 │ a │ b │ c │ d │ e │
|
30 | * ├───┴───┤ ├───┴───┤ ┌───┬───┬───┐
|
31 | * 1 │ f │ │ g │ │ │ │ g │ 0
|
32 | * ├───┬───┴───┼───┬───┤ will return: ├───┴───┼───┤
|
33 | * 2 │ h │ i │ j │ k │ │ i │ j │ 1
|
34 | * ├───┤ ├───┤ │ │ ├───┤
|
35 | * 3 │ l │ │ m │ │ │ │ m │ 2
|
36 | * ├───┼───┬───┤ ├───┤ └───────┴───┘
|
37 | * 4 │ n │ o │ p │ │ q │
|
38 | * └───┴───┴───┴───┴───┘
|
39 | */
|
40 | export declare function cropTableToDimensions(sourceTable: Element, cropDimensions: {
|
41 | startRow: number;
|
42 | startColumn: number;
|
43 | endRow: number;
|
44 | endColumn: number;
|
45 | }, writer: Writer): Element;
|
46 | /**
|
47 | * Returns slot info of cells that starts above and overlaps a given row.
|
48 | *
|
49 | * In a table below, passing `overlapRow = 3`
|
50 | *
|
51 | * ┌───┬───┬───┬───┬───┐
|
52 | * 0 │ a │ b │ c │ d │ e │
|
53 | * │ ├───┼───┼───┼───┤
|
54 | * 1 │ │ f │ g │ h │ i │
|
55 | * ├───┤ ├───┼───┤ │
|
56 | * 2 │ j │ │ k │ l │ │
|
57 | * │ │ │ ├───┼───┤
|
58 | * 3 │ │ │ │ m │ n │ <- overlap row to check
|
59 | * ├───┼───┤ │ ├───│
|
60 | * 4 │ o │ p │ │ │ q │
|
61 | * └───┴───┴───┴───┴───┘
|
62 | *
|
63 | * will return slot info for cells: "j", "f", "k".
|
64 | *
|
65 | * @param table The table to check.
|
66 | * @param overlapRow The index of the row to check.
|
67 | * @param startRow row to start analysis. Use it when it is known that the cells above that row will not overlap. Default value is 0.
|
68 | */
|
69 | export declare function getVerticallyOverlappingCells(table: Element, overlapRow: number, startRow?: number): Array<TableSlot>;
|
70 | /**
|
71 | * Splits the table cell horizontally.
|
72 | *
|
73 | * @returns Created table cell, if any were created.
|
74 | */
|
75 | export declare function splitHorizontally(tableCell: Element, splitRow: number, writer: Writer): Element | null;
|
76 | /**
|
77 | * Returns slot info of cells that starts before and overlaps a given column.
|
78 | *
|
79 | * In a table below, passing `overlapColumn = 3`
|
80 | *
|
81 | * 0 1 2 3 4
|
82 | * ┌───────┬───────┬───┐
|
83 | * │ a │ b │ c │
|
84 | * │───┬───┴───────┼───┤
|
85 | * │ d │ e │ f │
|
86 | * ├───┼───┬───────┴───┤
|
87 | * │ g │ h │ i │
|
88 | * ├───┼───┼───┬───────┤
|
89 | * │ j │ k │ l │ m │
|
90 | * ├───┼───┴───┼───┬───┤
|
91 | * │ n │ o │ p │ q │
|
92 | * └───┴───────┴───┴───┘
|
93 | * ^
|
94 | * Overlap column to check
|
95 | *
|
96 | * will return slot info for cells: "b", "e", "i".
|
97 | *
|
98 | * @param table The table to check.
|
99 | * @param overlapColumn The index of the column to check.
|
100 | */
|
101 | export declare function getHorizontallyOverlappingCells(table: Element, overlapColumn: number): Array<TableSlot>;
|
102 | /**
|
103 | * Splits the table cell vertically.
|
104 | *
|
105 | * @param columnIndex The table cell column index.
|
106 | * @param splitColumn The index of column to split cell on.
|
107 | * @returns Created table cell.
|
108 | */
|
109 | export declare function splitVertically(tableCell: Element, columnIndex: number, splitColumn: number, writer: Writer): Element;
|
110 | /**
|
111 | * Adjusts table cell dimensions to not exceed limit row and column.
|
112 | *
|
113 | * If table cell width (or height) covers a column (or row) that is after a limit column (or row)
|
114 | * this method will trim "colspan" (or "rowspan") attribute so the table cell will fit in a defined limits.
|
115 | */
|
116 | export declare function trimTableCellIfNeeded(tableCell: Element, cellRow: number, cellColumn: number, limitRow: number, limitColumn: number, writer: Writer): void;
|
117 | /**
|
118 | * Removes columns that have no cells anchored.
|
119 | *
|
120 | * In table below:
|
121 | *
|
122 | * +----+----+----+----+----+----+----+
|
123 | * | 00 | 01 | 03 | 04 | 06 |
|
124 | * +----+----+----+----+ +----+
|
125 | * | 10 | 11 | 13 | | 16 |
|
126 | * +----+----+----+----+----+----+----+
|
127 | * | 20 | 21 | 23 | 24 | 26 |
|
128 | * +----+----+----+----+----+----+----+
|
129 | * ^--- empty ---^
|
130 | *
|
131 | * Will remove columns 2 and 5.
|
132 | *
|
133 | * **Note:** This is a low-level helper method for clearing invalid model state when doing table modifications.
|
134 | * To remove a column from a table use {@link module:table/tableutils~TableUtils#removeColumns `TableUtils.removeColumns()`}.
|
135 | *
|
136 | * @internal
|
137 | * @returns True if removed some columns.
|
138 | */
|
139 | export declare function removeEmptyColumns(table: Element, tableUtils: TableUtils): boolean;
|
140 | /**
|
141 | * Removes rows that have no cells anchored.
|
142 | *
|
143 | * In table below:
|
144 | *
|
145 | * +----+----+----+
|
146 | * | 00 | 01 | 02 |
|
147 | * +----+----+----+
|
148 | * | 10 | 11 | 12 |
|
149 | * + + + +
|
150 | * | | | | <-- empty
|
151 | * +----+----+----+
|
152 | * | 30 | 31 | 32 |
|
153 | * +----+----+----+
|
154 | * | 40 | 42 |
|
155 | * + + +
|
156 | * | | | <-- empty
|
157 | * +----+----+----+
|
158 | * | 60 | 61 | 62 |
|
159 | * +----+----+----+
|
160 | *
|
161 | * Will remove rows 2 and 5.
|
162 | *
|
163 | * **Note:** This is a low-level helper method for clearing invalid model state when doing table modifications.
|
164 | * To remove a row from a table use {@link module:table/tableutils~TableUtils#removeRows `TableUtils.removeRows()`}.
|
165 | *
|
166 | * @internal
|
167 | * @returns True if removed some rows.
|
168 | */
|
169 | export declare function removeEmptyRows(table: Element, tableUtils: TableUtils): boolean;
|
170 | /**
|
171 | * Removes rows and columns that have no cells anchored.
|
172 | *
|
173 | * In table below:
|
174 | *
|
175 | * +----+----+----+----+
|
176 | * | 00 | 02 |
|
177 | * +----+----+ +
|
178 | * | 10 | |
|
179 | * +----+----+----+----+
|
180 | * | 20 | 22 | 23 |
|
181 | * + + + +
|
182 | * | | | | <-- empty row
|
183 | * +----+----+----+----+
|
184 | * ^--- empty column
|
185 | *
|
186 | * Will remove row 3 and column 1.
|
187 | *
|
188 | * **Note:** This is a low-level helper method for clearing invalid model state when doing table modifications.
|
189 | * To remove a rows from a table use {@link module:table/tableutils~TableUtils#removeRows `TableUtils.removeRows()`} and
|
190 | * {@link module:table/tableutils~TableUtils#removeColumns `TableUtils.removeColumns()`} to remove a column.
|
191 | *
|
192 | * @internal
|
193 | */
|
194 | export declare function removeEmptyRowsColumns(table: Element, tableUtils: TableUtils): void;
|
195 | /**
|
196 | * Returns adjusted last row index if selection covers part of a row with empty slots (spanned by other cells).
|
197 | * The `dimensions.lastRow` is equal to last row index but selection might be bigger.
|
198 | *
|
199 | * This happens *only* on rectangular selection so we analyze a case like this:
|
200 | *
|
201 | * +---+---+---+---+
|
202 | * 0 | a | b | c | d |
|
203 | * + + +---+---+
|
204 | * 1 | | e | f | g |
|
205 | * + +---+ +---+
|
206 | * 2 | | h | | i | <- last row, each cell has rowspan = 2,
|
207 | * + + + + + so we need to return 3, not 2
|
208 | * 3 | | | | |
|
209 | * +---+---+---+---+
|
210 | *
|
211 | * @returns Adjusted last row index.
|
212 | */
|
213 | export declare function adjustLastRowIndex(table: Element, dimensions: {
|
214 | firstRow: number;
|
215 | firstColumn: number;
|
216 | lastRow: number;
|
217 | lastColumn: number;
|
218 | }): number;
|
219 | /**
|
220 | * Returns adjusted last column index if selection covers part of a column with empty slots (spanned by other cells).
|
221 | * The `dimensions.lastColumn` is equal to last column index but selection might be bigger.
|
222 | *
|
223 | * This happens *only* on rectangular selection so we analyze a case like this:
|
224 | *
|
225 | * 0 1 2 3
|
226 | * +---+---+---+---+
|
227 | * | a |
|
228 | * +---+---+---+---+
|
229 | * | b | c | d |
|
230 | * +---+---+---+---+
|
231 | * | e | f |
|
232 | * +---+---+---+---+
|
233 | * | g | h |
|
234 | * +---+---+---+---+
|
235 | * ^
|
236 | * last column, each cell has colspan = 2, so we need to return 3, not 2
|
237 | *
|
238 | * @returns Adjusted last column index.
|
239 | */
|
240 | export declare function adjustLastColumnIndex(table: Element, dimensions: {
|
241 | firstRow: number;
|
242 | firstColumn: number;
|
243 | lastRow: number;
|
244 | lastColumn: number;
|
245 | }): number;
|