@univerjs-pro/docs-column 1.0.0-alpha.1 → 1.0.0-alpha.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,37 +1,48 @@
1
- import type { ICustomColumnGroup, IDocsColumnGroupOffsetRange } from '@univerjs-pro/docs-column';
2
- import type { ICommandService } from '@univerjs/core';
3
- import type { FDocument } from '@univerjs/docs/facade';
1
+ import type { ColumnPosition, ICustomColumnGroup, IDocsColumnGroupOffsetRange } from '@univerjs-pro/docs-column';
2
+ import type { Injector } from '@univerjs/core';
3
+ import type { FDocument, FDocumentParagraph } from '@univerjs/docs/facade';
4
4
  import type { IDocsColumnDescription } from './types';
5
5
  import { FDocumentColumn } from './f-document-column';
6
6
  /**
7
7
  * Facade object for a docs column group.
8
8
  *
9
+ * ColumnGroup is available only in modern documents. Read methods return empty values
10
+ * if a retained facade is used after switching to traditional mode; mutation methods
11
+ * throw `DocsColumnUnsupportedDocumentFlavorError`.
12
+ *
9
13
  * A column group is the horizontal block container that owns two to five columns.
10
14
  * Mutating methods run synchronously through the Univer rich-text mutation pipeline,
11
15
  * so undo/redo and collaboration receive the same document changes as UI operations.
12
16
  * @example
13
17
  * ```ts
14
- * import '@univerjs/docs/facade';
15
- * import '@univerjs-pro/docs-column/facade';
16
- *
17
18
  * const fDocument = univerAPI.getActiveDocument();
18
- * const group = fDocument?.getColumnGroup('column-group-1');
19
19
  *
20
+ * const groups = fDocument.getColumnGroups();
21
+ * console.log(groups.map((group) => group.describe()));
22
+ *
23
+ * const group = fDocument.findColumnGroupByText('Launch');
20
24
  * console.log(group?.describe());
25
+ *
21
26
  * group?.setWidthRatios([1.2, 1, 0.8]);
22
27
  * ```
23
28
  */
24
29
  export declare class FDocumentColumnGroup {
25
30
  private readonly _document;
26
31
  private readonly _columnGroupId;
27
- private readonly _commandService;
28
- constructor(_document: FDocument, _columnGroupId: string, _commandService: ICommandService);
32
+ private readonly _injector;
33
+ constructor(_document: FDocument, _columnGroupId: string, _injector: Injector);
29
34
  /**
30
35
  * Returns the column group id.
31
36
  * @returns {string} The persisted column group id.
32
37
  * @example
33
38
  * ```ts
34
- * console.log(group.getId());
39
+ * const fDocument = univerAPI.getActiveDocument();
40
+ * const groups = fDocument.getColumnGroups();
41
+ *
42
+ * if (groups.length > 0) {
43
+ * const group = groups[0];
44
+ * console.log(group.getId());
45
+ * }
35
46
  * ```
36
47
  */
37
48
  getId(): string;
@@ -40,22 +51,29 @@ export declare class FDocumentColumnGroup {
40
51
  * @returns {ICustomColumnGroup | undefined} The group config, or `undefined` if the group is missing.
41
52
  * @example
42
53
  * ```ts
43
- * console.log(group.getConfig()?.columns);
54
+ * const fDocument = univerAPI.getActiveDocument();
55
+ * const groups = fDocument.getColumnGroups();
56
+ *
57
+ * if (groups.length > 0) {
58
+ * const group = groups[0];
59
+ * console.log(group.getConfig());
60
+ * }
44
61
  * ```
45
62
  */
46
63
  getConfig(): ICustomColumnGroup | undefined;
47
- /**
48
- * @deprecated Use `getConfig()` instead. Column layout config now lives directly on `body.columnGroups`.
49
- */
50
- getSource(): ICustomColumnGroup | undefined;
51
64
  /**
52
65
  * Returns the structural range for this column group.
53
66
  * The group range includes the column group start and end structural tokens.
54
67
  * @returns {IDocsColumnGroupOffsetRange | null} The parsed group range, or `null` if the group is missing.
55
68
  * @example
56
69
  * ```ts
57
- * const range = group.getRange();
58
- * console.log(range?.columns.length);
70
+ * const fDocument = univerAPI.getActiveDocument();
71
+ * const groups = fDocument.getColumnGroups();
72
+ *
73
+ * if (groups.length > 0) {
74
+ * const group = groups[0];
75
+ * console.log(group.getRange());
76
+ * }
59
77
  * ```
60
78
  */
61
79
  getRange(): IDocsColumnGroupOffsetRange | null;
@@ -64,7 +82,13 @@ export declare class FDocumentColumnGroup {
64
82
  * @returns {number} The column count, or `0` if the group is missing.
65
83
  * @example
66
84
  * ```ts
67
- * console.log(group.getColumnCount());
85
+ * const fDocument = univerAPI.getActiveDocument();
86
+ * const groups = fDocument.getColumnGroups();
87
+ *
88
+ * if (groups.length > 0) {
89
+ * const group = groups[0];
90
+ * console.log(group.getColumnCount());
91
+ * }
68
92
  * ```
69
93
  */
70
94
  getColumnCount(): number;
@@ -73,19 +97,47 @@ export declare class FDocumentColumnGroup {
73
97
  * @returns {FDocumentColumn[]} Column wrappers, or an empty array when the group is missing.
74
98
  * @example
75
99
  * ```ts
76
- * const columns = group.getColumns();
77
- * columns.forEach((column) => console.log(column.getText()));
100
+ * const fDocument = univerAPI.getActiveDocument();
101
+ * const groups = fDocument.getColumnGroups();
102
+ *
103
+ * if (groups.length > 0) {
104
+ * const group = groups[0];
105
+ * const columns = group.getColumns();
106
+ * columns.forEach((column) => console.log(column.getText()));
107
+ * }
78
108
  * ```
79
109
  */
80
110
  getColumns(): FDocumentColumn[];
111
+ /**
112
+ * Returns all paragraph facades inside the group, in column and document order.
113
+ * @returns {FDocumentParagraph[]} Paragraphs in column and document order.
114
+ * @example
115
+ * ```ts
116
+ * const fDocument = univerAPI.getActiveDocument();
117
+ * const group = fDocument?.findColumnGroupByText('Launch');
118
+ * const paragraphs = group?.getParagraphs() ?? [];
119
+ * console.log(paragraphs.map((paragraph) => paragraph.getText()));
120
+ * ```
121
+ */
122
+ getParagraphs(): FDocumentParagraph[];
81
123
  /**
82
124
  * Returns a column by zero-based index or by column id.
83
125
  * @param {number | string} indexOrId Zero-based column index, or persisted column id.
84
126
  * @returns {FDocumentColumn | null} The column wrapper, or `null` if no column matches.
85
127
  * @example
86
128
  * ```ts
87
- * const first = group.getColumn(0);
88
- * const named = group.getColumn('right-column');
129
+ * const fDocument = univerAPI.getActiveDocument();
130
+ * const groups = fDocument.getColumnGroups();
131
+ *
132
+ * if (groups.length > 0) {
133
+ * const group = groups[0];
134
+ *
135
+ * const columnWithIndex = group.getColumn(0);
136
+ * console.log(columnWithIndex?.getText());
137
+ *
138
+ * const columnWithId = group.getColumn('right-column');
139
+ * console.log(columnWithId?.getText());
140
+ * }
89
141
  * ```
90
142
  */
91
143
  getColumn(indexOrId: number | string): FDocumentColumn | null;
@@ -94,7 +146,13 @@ export declare class FDocumentColumnGroup {
94
146
  * @returns {number[]} The width ratios from the column group config.
95
147
  * @example
96
148
  * ```ts
97
- * console.log(group.getWidthRatios());
149
+ * const fDocument = univerAPI.getActiveDocument();
150
+ * const groups = fDocument.getColumnGroups();
151
+ *
152
+ * if (groups.length > 0) {
153
+ * const group = groups[0];
154
+ * console.log(group.getWidthRatios());
155
+ * }
98
156
  * ```
99
157
  */
100
158
  getWidthRatios(): number[];
@@ -103,8 +161,13 @@ export declare class FDocumentColumnGroup {
103
161
  * @returns {IDocsColumnDescription} Id, layout config, column ratios, and sample column text.
104
162
  * @example
105
163
  * ```ts
106
- * const summary = group.describe();
107
- * console.log(summary.columns.map((column) => column.text));
164
+ * const fDocument = univerAPI.getActiveDocument();
165
+ * const groups = fDocument.getColumnGroups();
166
+ *
167
+ * if (groups.length > 0) {
168
+ * const group = groups[0];
169
+ * console.log(group.describe());
170
+ * }
108
171
  * ```
109
172
  */
110
173
  describe(): IDocsColumnDescription;
@@ -115,6 +178,8 @@ export declare class FDocumentColumnGroup {
115
178
  * @returns {boolean} `true` if the mutation was committed.
116
179
  * @example
117
180
  * ```ts
181
+ * const fDocument = univerAPI.getActiveDocument();
182
+ * const group = fDocument.findColumnGroupByText('Launch');
118
183
  * group.setWidthRatios([1.2, 1, 0.8]);
119
184
  * ```
120
185
  */
@@ -122,16 +187,28 @@ export declare class FDocumentColumnGroup {
122
187
  /**
123
188
  * Adds an empty column to the left or right of an existing column.
124
189
  * @param {string} targetColumnId Existing column id used as the insertion anchor.
125
- * @param {'left' | 'right'} position Whether the new column is inserted to the left or right of the target column.
190
+ * @param {ColumnPosition} position Whether the new column is inserted to the left or right of the target column.
126
191
  * @param {string} [columnId] Optional id for the inserted column. A random id is generated when omitted.
127
192
  * @returns {FDocumentColumn | null} The inserted column wrapper, or `null` if the mutation failed.
128
193
  * @example
129
194
  * ```ts
130
- * const inserted = group.addColumn('right-column', 'left', 'new-column');
131
- * console.log(inserted?.getInsertOffset());
195
+ * const fDocument = univerAPI.getActiveDocument();
196
+ * const group = fDocument.findColumnGroupByText('Launch');
197
+ * const columns = group.getColumns();
198
+ *
199
+ * // Add a new column to the left of the last column in the group.
200
+ * if (columns.length > 0) {
201
+ * const rightColumn = group.getColumn(columns.length - 1);
202
+ * const inserted = group.addColumn(
203
+ * rightColumn.getId(),
204
+ * univerAPI.Enum.DocsColumnPositionEnum.LEFT,
205
+ * 'new-column'
206
+ * );
207
+ * console.log(inserted?.getInsertOffset());
208
+ * }
132
209
  * ```
133
210
  */
134
- addColumn(targetColumnId: string, position: 'left' | 'right', columnId?: string): FDocumentColumn | null;
211
+ addColumn(targetColumnId: string, position: ColumnPosition, columnId?: string): FDocumentColumn | null;
135
212
  /**
136
213
  * Deletes a column from this group.
137
214
  * Column groups must keep at least two columns, so deleting from a two-column group returns `false`.
@@ -139,7 +216,12 @@ export declare class FDocumentColumnGroup {
139
216
  * @returns {boolean} `true` if the mutation was committed.
140
217
  * @example
141
218
  * ```ts
142
- * group.deleteColumn('old-column');
219
+ * const fDocument = univerAPI.getActiveDocument();
220
+ * const group = fDocument.findColumnGroupByText('Launch');
221
+ * const columns = group.getColumns();
222
+ *
223
+ * // Delete the first column in the group.
224
+ * group.deleteColumn(columns[0].getId());
143
225
  * ```
144
226
  */
145
227
  deleteColumn(columnId: string): boolean;
@@ -148,10 +230,13 @@ export declare class FDocumentColumnGroup {
148
230
  * @returns {boolean} `true` if the mutation was committed.
149
231
  * @example
150
232
  * ```ts
151
- * group.delete();
233
+ * const fDocument = univerAPI.getActiveDocument();
234
+ * const group = fDocument.findColumnGroupByText('Launch');
235
+ * const removed = group.remove();
236
+ * console.log(removed);
152
237
  * ```
153
238
  */
154
- delete(): boolean;
155
- private _getDocumentData;
239
+ remove(): boolean;
156
240
  private _createFDocumentColumn;
241
+ private _assertModernDocument;
157
242
  }
@@ -1,19 +1,23 @@
1
1
  import type { IDocsColumnOffsetRange } from '@univerjs-pro/docs-column';
2
- import type { FDocument } from '@univerjs/docs/facade';
2
+ import type { ITextStyle } from '@univerjs/core';
3
+ import type { FDocument, FDocumentParagraph, FDocumentTextRange } from '@univerjs/docs/facade';
3
4
  import type { IDocsColumnContentRange } from './types';
4
5
  /**
5
6
  * Facade object for a single column inside a docs column group.
6
7
  *
8
+ * Columns in this facade belong to the modern-document ColumnGroup model. Read methods
9
+ * return empty values in traditional mode; mutation methods throw a flavor-specific error.
10
+ *
7
11
  * The column wrapper resolves its range from persisted column ids every time a method
8
12
  * is called, so it stays useful after edits insert content before the column group.
9
13
  * @example
10
14
  * ```ts
11
- * import '@univerjs/docs/facade';
12
- * import '@univerjs-pro/docs-column/facade';
13
- *
14
15
  * const fDocument = univerAPI.getActiveDocument();
15
- * const column = fDocument?.getColumnGroup('column-group-1')?.getColumn(0);
16
16
  *
17
+ * const group = fDocument.findColumnGroupByText('Launch');
18
+ * console.log(group?.describe());
19
+ *
20
+ * const column = group?.getColumn(0);
17
21
  * console.log(column?.getText());
18
22
  * console.log(column?.getInsertOffset());
19
23
  * ```
@@ -28,7 +32,9 @@ export declare class FDocumentColumn {
28
32
  * @returns {string} The persisted column id.
29
33
  * @example
30
34
  * ```ts
31
- * const column = univerAPI.getActiveDocument()?.getColumnGroup('group')?.getColumn(0);
35
+ * const fDocument = univerAPI.getActiveDocument();
36
+ * const group = fDocument.findColumnGroupByText('Launch');
37
+ * const column = group?.getColumn(0);
32
38
  * console.log(column?.getId());
33
39
  * ```
34
40
  */
@@ -38,7 +44,9 @@ export declare class FDocumentColumn {
38
44
  * @returns {string} The persisted column group id.
39
45
  * @example
40
46
  * ```ts
41
- * const column = univerAPI.getActiveDocument()?.getColumnGroup('group')?.getColumn(0);
47
+ * const fDocument = univerAPI.getActiveDocument();
48
+ * const group = fDocument.findColumnGroupByText('Launch');
49
+ * const column = group?.getColumn(0);
42
50
  * console.log(column?.getColumnGroupId());
43
51
  * ```
44
52
  */
@@ -48,7 +56,10 @@ export declare class FDocumentColumn {
48
56
  * @returns {number} The column index, or `-1` when the column no longer exists.
49
57
  * @example
50
58
  * ```ts
51
- * const index = column.getIndex();
59
+ * const fDocument = univerAPI.getActiveDocument();
60
+ * const group = fDocument.findColumnGroupByText('Launch');
61
+ * const column = group?.getColumn(0);
62
+ * console.log(column?.getIndex());
52
63
  * ```
53
64
  */
54
65
  getIndex(): number;
@@ -58,8 +69,10 @@ export declare class FDocumentColumn {
58
69
  * @returns {IDocsColumnOffsetRange | null} The column range, or `null` if the column no longer exists.
59
70
  * @example
60
71
  * ```ts
61
- * const range = column.getRange();
62
- * console.log(range?.startOffset, range?.endOffset);
72
+ * const fDocument = univerAPI.getActiveDocument();
73
+ * const group = fDocument.findColumnGroupByText('Launch');
74
+ * const column = group?.getColumn(0);
75
+ * console.log(column?.getRange());
63
76
  * ```
64
77
  */
65
78
  getRange(): IDocsColumnOffsetRange | null;
@@ -72,10 +85,10 @@ export declare class FDocumentColumn {
72
85
  * @returns {IDocsColumnContentRange | null} The editable range, or `null` if the column no longer exists.
73
86
  * @example
74
87
  * ```ts
75
- * const range = column.getContentRange();
76
- * if (range) {
77
- * fDocument.insertText('Column intro', range);
78
- * }
88
+ * const fDocument = univerAPI.getActiveDocument();
89
+ * const group = fDocument.findColumnGroupByText('Launch');
90
+ * const column = group?.getColumn(0);
91
+ * console.log(column?.getContentRange());
79
92
  * ```
80
93
  */
81
94
  getContentRange(): IDocsColumnContentRange | null;
@@ -88,17 +101,18 @@ export declare class FDocumentColumn {
88
101
  * @returns {number | null} The insertion offset, or `null` if the column no longer exists.
89
102
  * @example
90
103
  * ```ts
91
- * import '@univerjs-pro/docs-table/facade';
92
- *
93
104
  * const fDocument = univerAPI.getActiveDocument();
94
- * const thirdColumn = fDocument?.getColumnGroup('group')?.getColumn(2);
105
+ * const group = fDocument.findColumnGroupByText('Launch');
106
+ * const thirdColumn = group?.getColumn(2);
95
107
  * const offset = thirdColumn?.getInsertOffset();
96
108
  *
97
109
  * if (offset != null) {
98
110
  * fDocument?.insertTableFromData([
99
111
  * ['Metric', 'Now', 'Next'],
100
112
  * ['Adoption', '68%', '80%'],
101
- * ], { offset });
113
+ * ], {
114
+ * offset
115
+ * });
102
116
  * }
103
117
  * ```
104
118
  */
@@ -109,9 +123,93 @@ export declare class FDocumentColumn {
109
123
  * @returns {string} The column text, or an empty string if the column no longer exists.
110
124
  * @example
111
125
  * ```ts
112
- * console.log(column.getText());
126
+ * const fDocument = univerAPI.getActiveDocument();
127
+ * const group = fDocument.findColumnGroupByText('Launch');
128
+ * const column = group?.getColumn(0);
129
+ * console.log(column?.getText());
113
130
  * ```
114
131
  */
115
132
  getText(): string;
116
- private _getDocumentData;
133
+ /**
134
+ * Returns paragraph facades whose paragraph marks are contained in this column.
135
+ * @returns {FDocumentParagraph[]} Paragraphs in column-local order.
136
+ * @example
137
+ * ```ts
138
+ * const fDocument = univerAPI.getActiveDocument();
139
+ * const column = fDocument?.findColumnGroupByText('Launch')?.getColumn(0);
140
+ * const paragraphs = column?.getParagraphs() ?? [];
141
+ * console.log(paragraphs.map((paragraph) => paragraph.getText()));
142
+ * ```
143
+ */
144
+ getParagraphs(): FDocumentParagraph[];
145
+ /**
146
+ * Inserts a plain-text paragraph at a column-local paragraph index.
147
+ *
148
+ * The index is relative to this column, not the whole document. Passing the
149
+ * current paragraph count appends inside the column, before `COLUMN_END`.
150
+ * @param {number} index The zero-based column-local paragraph insertion index.
151
+ * @param {string} text The paragraph text. Defaults to an empty paragraph.
152
+ * @returns {FDocumentParagraph} The inserted paragraph facade.
153
+ * @throws {RangeError} If the index is outside `0..getParagraphs().length`.
154
+ * @example
155
+ * ```ts
156
+ * const fDocument = univerAPI.getActiveDocument();
157
+ * const column = fDocument?.findColumnGroupByText('Launch')?.getColumn(0);
158
+ *
159
+ * // The index is relative to this column. This inserts before its first paragraph.
160
+ * const paragraph = column?.insertParagraph(0, 'Executive summary');
161
+ * console.log(paragraph?.getText());
162
+ * ```
163
+ */
164
+ insertParagraph(index: number, text?: string): FDocumentParagraph;
165
+ /**
166
+ * Appends a plain-text paragraph inside this column.
167
+ * @param {string} text The paragraph text. Defaults to an empty paragraph.
168
+ * @returns {FDocumentParagraph} The appended paragraph facade.
169
+ * @example
170
+ * ```ts
171
+ * const fDocument = univerAPI.getActiveDocument();
172
+ * const column = fDocument?.findColumnGroupByText('Launch')?.getColumn(0);
173
+ * const paragraph = column?.appendParagraph('Next steps');
174
+ * console.log(paragraph?.getText());
175
+ * ```
176
+ */
177
+ appendParagraph(text?: string): FDocumentParagraph;
178
+ /**
179
+ * Returns an editable text-range facade for the column content.
180
+ * @returns {FDocumentTextRange | null} The editable range, or `null` if the column no longer exists.
181
+ * @example
182
+ * ```ts
183
+ * const fDocument = univerAPI.getActiveDocument();
184
+ * const column = fDocument?.findColumnGroupByText('Launch')?.getColumn(0);
185
+ * console.log(column?.getTextRange()?.getText());
186
+ * ```
187
+ */
188
+ getTextRange(): FDocumentTextRange | null;
189
+ /**
190
+ * Replaces the editable column content with plain text.
191
+ * @param {string} text The replacement text.
192
+ * @returns {boolean} `true` if the edit was applied.
193
+ * @example
194
+ * ```ts
195
+ * const fDocument = univerAPI.getActiveDocument();
196
+ * const column = fDocument?.findColumnGroupByText('Launch')?.getColumn(0);
197
+ * column?.setText('Launch plan\nOwner: Product');
198
+ * ```
199
+ */
200
+ setText(text: string): boolean;
201
+ /**
202
+ * Applies a text-style patch across the editable column content.
203
+ * `style.fs` is a font size in points (pt), not CSS pixels.
204
+ * @param {ITextStyle} style The text-style patch to apply.
205
+ * @returns {boolean} `true` if the edit was applied.
206
+ * @example
207
+ * ```ts
208
+ * const fDocument = univerAPI.getActiveDocument();
209
+ * const column = fDocument?.findColumnGroupByText('Launch')?.getColumn(0);
210
+ * column?.setTextStyle({ fs: 10.5, bl: univerAPI.Enum.BooleanNumber.TRUE });
211
+ * ```
212
+ */
213
+ setTextStyle(style: ITextStyle): boolean;
214
+ private _assertModernDocument;
117
215
  }
@@ -1,18 +1,21 @@
1
1
  import type { IDocsColumnFindQuery, IDocsColumnInsertFacadeOptions } from './types';
2
2
  import { FDocument } from '@univerjs/docs/facade';
3
3
  import { FDocumentColumnGroup } from './f-document-column-group';
4
+ /**
5
+ * Modern-document-only ColumnGroup APIs.
6
+ *
7
+ * Read APIs return empty values in traditional documents. Mutation APIs throw
8
+ * `DocsColumnUnsupportedDocumentFlavorError`; use SectionBreak column APIs there.
9
+ */
4
10
  export interface IFDocumentColumnMixin {
5
11
  /**
6
- * Returns all column groups in document order.
12
+ * Returns all column groups in this document.
7
13
  * @returns {FDocumentColumnGroup[]} Column group wrappers, or an empty array when the document has no column groups.
8
14
  * @example
9
15
  * ```ts
10
- * import '@univerjs/docs/facade';
11
- * import '@univerjs-pro/docs-column/facade';
12
- *
13
16
  * const fDocument = univerAPI.getActiveDocument();
14
- * const groups = fDocument?.getColumnGroups();
15
- * console.log(groups?.map((group) => group.describe()));
17
+ * const groups = fDocument.getColumnGroups();
18
+ * console.log(groups.map((group) => group.describe()));
16
19
  * ```
17
20
  */
18
21
  getColumnGroups(): FDocumentColumnGroup[];
@@ -22,8 +25,9 @@ export interface IFDocumentColumnMixin {
22
25
  * @returns {FDocumentColumnGroup | null} The column group wrapper, or `null` if no group has the id.
23
26
  * @example
24
27
  * ```ts
25
- * const group = univerAPI.getActiveDocument()?.getColumnGroup('column-group-1');
26
- * console.log(group?.getColumnCount());
28
+ * const fDocument = univerAPI.getActiveDocument();
29
+ * const group = fDocument.getColumnGroup('column-group-1');
30
+ * console.log(group?.describe());
27
31
  * ```
28
32
  */
29
33
  getColumnGroup(columnGroupId: string): FDocumentColumnGroup | null;
@@ -33,10 +37,24 @@ export interface IFDocumentColumnMixin {
33
37
  * @returns {FDocumentColumnGroup | null} The containing column group, or `null` when the offset is outside all groups.
34
38
  * @example
35
39
  * ```ts
36
- * const group = univerAPI.getActiveDocument()?.getColumnGroupAt(128);
40
+ * const fDocument = univerAPI.getActiveDocument();
41
+ * const group = fDocument.getColumnGroupAt(128);
42
+ * console.log(group?.describe());
37
43
  * ```
38
44
  */
39
45
  getColumnGroupAt(offset: number): FDocumentColumnGroup | null;
46
+ /**
47
+ * Finds the first column group that contains a column with matching text.
48
+ * @param {string} text Plain text to search inside columns.
49
+ * @returns {FDocumentColumnGroup | null} The first matching column group, or `null` when no group contains the text.
50
+ * @example
51
+ * ```ts
52
+ * const fDocument = univerAPI.getActiveDocument();
53
+ * const group = fDocument.findColumnGroupByText('Launch');
54
+ * console.log(group?.describe());
55
+ * ```
56
+ */
57
+ findColumnGroupByText(text: string): FDocumentColumnGroup | null;
40
58
  /**
41
59
  * Finds column groups by text or by id.
42
60
  * @param {string | IDocsColumnFindQuery} query Plain text to search inside columns, or a structured query.
@@ -44,9 +62,9 @@ export interface IFDocumentColumnMixin {
44
62
  * @example
45
63
  * ```ts
46
64
  * const fDocument = univerAPI.getActiveDocument();
47
- * const groupsWithLaunch = fDocument?.findColumnGroups('Launch');
48
- * const exactGroup = fDocument?.findColumnGroups({ columnGroupId: 'column-group-1' });
49
- * console.log(groupsWithLaunch, exactGroup);
65
+ * const groupsWithText = fDocument.findColumnGroups('Launch');
66
+ * const groupsWithId = fDocument.findColumnGroups({ columnGroupId: 'column-group-1' });
67
+ * console.log(groupsWithText, groupsWithId);
50
68
  * ```
51
69
  */
52
70
  findColumnGroups(query: string | IDocsColumnFindQuery): FDocumentColumnGroup[];
@@ -56,18 +74,13 @@ export interface IFDocumentColumnMixin {
56
74
  * By default the group is inserted before the final body section break. Pass `offset`
57
75
  * when you need to insert at a specific data-stream position. Every inserted column
58
76
  * contains an editable empty paragraph. Column groups are supported only in modern
59
- * documents; traditional documents return `null`.
77
+ * documents; traditional documents throw `DocsColumnUnsupportedDocumentFlavorError`.
60
78
  * @param {number} columnCount Number of columns to create. Values below two are normalized to two; values above five fail.
61
79
  * @param {IDocsColumnInsertFacadeOptions} [options] Optional id, column ids, insertion offset, gap, and initial width ratios.
62
- * @returns {FDocumentColumnGroup | null} The inserted column group wrapper, or `null` if insertion failed or the document is not modern.
80
+ * @returns {FDocumentColumnGroup | null} The inserted column group wrapper, or `null` if insertion failed.
63
81
  * @example
64
82
  * ```ts
65
- * import '@univerjs/docs/facade';
66
- * import '@univerjs-pro/docs-column/facade';
67
- * import '@univerjs-pro/docs-table/facade';
68
- *
69
83
  * const fDocument = univerAPI.getActiveDocument();
70
- * if (!fDocument) throw new Error('No active document');
71
84
  *
72
85
  * const group = fDocument.insertColumnGroup(3, {
73
86
  * gap: 18,
@@ -78,18 +91,12 @@ export interface IFDocumentColumnMixin {
78
91
  *
79
92
  * const leftOffset = left?.getInsertOffset();
80
93
  * if (leftOffset != null) {
81
- * fDocument.insertText('Editorial brief\rUse columns for compact narrative layout.', {
82
- * startOffset: leftOffset,
83
- * endOffset: leftOffset,
84
- * });
94
+ * fDocument.insertText(leftOffset, 'Editorial brief\rUse columns for compact narrative layout.');
85
95
  * }
86
96
  *
87
97
  * const middleOffset = middle?.getInsertOffset();
88
98
  * if (middleOffset != null) {
89
- * fDocument.insertText('Production checklist\rDrag content into this column.', {
90
- * startOffset: middleOffset,
91
- * endOffset: middleOffset,
92
- * });
99
+ * fDocument.insertText(middleOffset, 'Production checklist\rDrag content into this column.');
93
100
  * }
94
101
  *
95
102
  * const rightOffset = right?.getInsertOffset();
@@ -98,32 +105,24 @@ export interface IFDocumentColumnMixin {
98
105
  * ['Metric', 'Now', 'Next'],
99
106
  * ['Adoption', '68%', '80%'],
100
107
  * ['Quality', 'A-', 'A'],
101
- * ], { offset: rightOffset, headerRowCount: 1 });
108
+ * ], {
109
+ * offset: rightOffset,
110
+ * headerRowCount: 1
111
+ * });
102
112
  * }
103
113
  *
104
114
  * console.log(group?.describe());
105
115
  * ```
106
116
  */
107
117
  insertColumnGroup(columnCount: number, options?: IDocsColumnInsertFacadeOptions): FDocumentColumnGroup | null;
108
- /**
109
- * Deletes a column group by id.
110
- * @param {string} columnGroupId The column group id.
111
- * @returns {boolean} `true` if the group was deleted.
112
- * @example
113
- * ```ts
114
- * const success = univerAPI.getActiveDocument()?.deleteColumnGroup('column-group-1');
115
- * console.log(success);
116
- * ```
117
- */
118
- deleteColumnGroup(columnGroupId: string): boolean;
119
118
  }
120
119
  export declare class FDocumentColumnMixin extends FDocument implements IFDocumentColumnMixin {
121
120
  getColumnGroups(): FDocumentColumnGroup[];
122
121
  getColumnGroup(columnGroupId: string): FDocumentColumnGroup | null;
123
122
  getColumnGroupAt(offset: number): FDocumentColumnGroup | null;
123
+ findColumnGroupByText(text: string): FDocumentColumnGroup | null;
124
124
  findColumnGroups(query: string | IDocsColumnFindQuery): FDocumentColumnGroup[];
125
125
  insertColumnGroup(columnCount: number, options?: IDocsColumnInsertFacadeOptions): FDocumentColumnGroup | null;
126
- deleteColumnGroup(columnGroupId: string): boolean;
127
126
  private _getColumnGroups;
128
127
  private _createFDocumentColumnGroup;
129
128
  }
@@ -1,31 +1,32 @@
1
- import { ColumnLayoutType, ColumnResponsiveType } from '@univerjs-pro/docs-column';
1
+ import { ColumnPosition } from '@univerjs-pro/docs-column';
2
2
  import { FEnum } from '@univerjs/core/facade';
3
3
  /**
4
4
  * @ignore
5
5
  */
6
6
  export interface IFDocumentColumnEnumMixin {
7
7
  /**
8
- * Represents docs column layout modes.
9
- *
8
+ * Docs column position enum.
10
9
  * @example
11
10
  * ```ts
12
- * const fixed = univerAPI.Enum.ColumnLayoutType.FIXED;
13
- * ```
14
- */
15
- ColumnLayoutType: typeof ColumnLayoutType;
16
- /**
17
- * Represents docs column responsive behavior.
11
+ * const fDocument = univerAPI.getActiveDocument();
12
+ * const group = fDocument.findColumnGroupByText('Launch');
13
+ * const columns = group.getColumns();
18
14
  *
19
- * @example
20
- * ```ts
21
- * const stack = univerAPI.Enum.ColumnResponsiveType.STACK;
15
+ * if (columns.length > 0) {
16
+ * const rightColumn = group.getColumn(columns.length - 1);
17
+ * const inserted = group.addColumn(
18
+ * rightColumn.getId(),
19
+ * univerAPI.Enum.DocsColumnPositionEnum.LEFT,
20
+ * 'new-column'
21
+ * );
22
+ * console.log(inserted?.getInsertOffset());
23
+ * }
22
24
  * ```
23
25
  */
24
- ColumnResponsiveType: typeof ColumnResponsiveType;
26
+ DocsColumnPositionEnum: typeof ColumnPosition;
25
27
  }
26
28
  export declare class FDocumentColumnEnumMixin extends FEnum implements IFDocumentColumnEnumMixin {
27
- get ColumnLayoutType(): typeof ColumnLayoutType;
28
- get ColumnResponsiveType(): typeof ColumnResponsiveType;
29
+ get DocsColumnPositionEnum(): typeof ColumnPosition;
29
30
  }
30
31
  declare module '@univerjs/core/facade' {
31
32
  interface FEnum extends IFDocumentColumnEnumMixin {