@univerjs/docs 1.0.4 → 1.2.0

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.
package/README.md CHANGED
@@ -30,6 +30,56 @@ import { UniverDocsPlugin } from '@univerjs/docs';
30
30
  univer.registerPlugin(UniverDocsPlugin);
31
31
  ```
32
32
 
33
+ ## Heading collapse in Modern documents
34
+
35
+ Modern documents (`DocumentFlavor.MODERN`) support collapsing Heading 1 through Heading 5.
36
+ The heading stays visible; its section extends to the next heading of the same or a higher
37
+ level, or the end of its content flow. Each table cell and Modern column has its own heading
38
+ hierarchy. Expanding a parent preserves the collapse flags of its nested headings.
39
+ Traditional documents ignore these flags.
40
+
41
+ `IParagraph.headingCollapsed` is an optional boolean in the document snapshot. Only `true`
42
+ collapses a heading; `false` or an omitted flag leaves it expanded. Collapsing changes layout
43
+ visibility without deleting the section's text, tables, images, or other snapshot content.
44
+ Saving and reopening a Univer snapshot retains the flag. This contract does not establish
45
+ preservation through Office import or export.
46
+
47
+ ### Change collapse state with a command
48
+
49
+ `UniverDocsPlugin` registers `SetHeadingCollapsedCommand` (`doc.command.set-heading-collapsed`).
50
+ After registering the plugin and creating the document, execute the registered command through
51
+ the Facade API or `ICommandService`; do not call its handler or mutate the model directly.
52
+ For an existing `univerAPI` instance:
53
+
54
+ ```ts
55
+ import { SetHeadingCollapsedCommand } from '@univerjs/docs';
56
+
57
+ const changed = await univerAPI.executeCommand(SetHeadingCollapsedCommand.id, {
58
+ unitId: documentId,
59
+ paragraphId: headingParagraphId,
60
+ collapsed: true,
61
+ });
62
+ ```
63
+
64
+ Pass the document's unit ID, the heading's stable paragraph ID, and the desired boolean state.
65
+ Use `collapsed: false` to expand. The command returns `false` for a no-op or an invalid target,
66
+ including Traditional or disabled documents, headings hidden by an ancestor, empty sections
67
+ when collapsing, and targets without edit permission.
68
+
69
+ Concurrent paragraph formatting preserves inherited style references and imported numbering metadata;
70
+ a full replacement can still explicitly clear those fields.
71
+
72
+ Collapse state is shared document state, not a personal view preference. The command uses the
73
+ rich-text mutation path for undo/redo and collaboration. Undoing a fold preserves later peer
74
+ character formatting and enclosing field or content-control properties that the fold did not edit.
75
+ A selection hidden by a collapse moves to the visible heading. Worker layout uses the same flags
76
+ after edits, undo/redo, and snapshot recovery; visibility changes rebuild the affected layout and retain the published viewport until
77
+ replacement content is ready. Hidden tables and images are omitted from layout publications,
78
+ while their source data remains in the snapshot. Rejected edits with empty operations do not
79
+ advance the Worker mutation queue or force the next real edit to resnapshot the document.
80
+
81
+ See [the editor interaction details](../docs-ui/README.md#heading-collapse) for the Canvas control.
82
+
33
83
  ## Resources
34
84
 
35
85
  - [Documentation](https://docs.univer.ai)
package/lib/cjs/facade.js CHANGED
@@ -304,7 +304,7 @@ function stripBlockTokens(text) {
304
304
  }
305
305
 
306
306
  //#endregion
307
- //#region \0@oxc-project+runtime@0.149.0/helpers/esm/decorateParam.js
307
+ //#region \0@oxc-project+runtime@0.153.0/helpers/esm/decorateParam.js
308
308
  function __decorateParam(paramIndex, decorator) {
309
309
  return function(target, key) {
310
310
  decorator(target, key, paramIndex);
@@ -312,7 +312,7 @@ function __decorateParam(paramIndex, decorator) {
312
312
  }
313
313
 
314
314
  //#endregion
315
- //#region \0@oxc-project+runtime@0.149.0/helpers/esm/decorate.js
315
+ //#region \0@oxc-project+runtime@0.153.0/helpers/esm/decorate.js
316
316
  function __decorate(decorators, target, key, desc) {
317
317
  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
318
318
  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
@@ -1454,7 +1454,7 @@ let FDocumentSection = class FDocumentSection {
1454
1454
  FDocumentSection = __decorate([__decorateParam(2, _univerjs_core.ICommandService), __decorateParam(3, _univerjs_core.IPermissionService)], FDocumentSection);
1455
1455
 
1456
1456
  //#endregion
1457
- //#region \0@oxc-project+runtime@0.149.0/helpers/esm/typeof.js
1457
+ //#region \0@oxc-project+runtime@0.153.0/helpers/esm/typeof.js
1458
1458
  function _typeof(o) {
1459
1459
  "@babel/helpers - typeof";
1460
1460
  return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function(o) {
@@ -1465,7 +1465,7 @@ function _typeof(o) {
1465
1465
  }
1466
1466
 
1467
1467
  //#endregion
1468
- //#region \0@oxc-project+runtime@0.149.0/helpers/esm/toPrimitive.js
1468
+ //#region \0@oxc-project+runtime@0.153.0/helpers/esm/toPrimitive.js
1469
1469
  function toPrimitive(t, r) {
1470
1470
  if ("object" != _typeof(t) || !t) return t;
1471
1471
  var e = t[Symbol.toPrimitive];
@@ -1478,14 +1478,14 @@ function toPrimitive(t, r) {
1478
1478
  }
1479
1479
 
1480
1480
  //#endregion
1481
- //#region \0@oxc-project+runtime@0.149.0/helpers/esm/toPropertyKey.js
1481
+ //#region \0@oxc-project+runtime@0.153.0/helpers/esm/toPropertyKey.js
1482
1482
  function toPropertyKey(t) {
1483
1483
  var i = toPrimitive(t, "string");
1484
1484
  return "symbol" == _typeof(i) ? i : i + "";
1485
1485
  }
1486
1486
 
1487
1487
  //#endregion
1488
- //#region \0@oxc-project+runtime@0.149.0/helpers/esm/defineProperty.js
1488
+ //#region \0@oxc-project+runtime@0.153.0/helpers/esm/defineProperty.js
1489
1489
  function _defineProperty(e, r, t) {
1490
1490
  return (r = toPropertyKey(r)) in e ? Object.defineProperty(e, r, {
1491
1491
  value: t,
@@ -2318,27 +2318,27 @@ _univerjs_core_facade.FEnum.extend(FDocsEnumMixin);
2318
2318
  //#endregion
2319
2319
  exports.DocsSectionUnsupportedDocumentFlavorError = DocsSectionUnsupportedDocumentFlavorError;
2320
2320
  exports.FDocsEnumMixin = FDocsEnumMixin;
2321
- Object.defineProperty(exports, 'FDocument', {
2321
+ Object.defineProperty(exports, "FDocument", {
2322
2322
  enumerable: true,
2323
2323
  get: function () {
2324
2324
  return FDocument;
2325
2325
  }
2326
2326
  });
2327
2327
  exports.FDocumentObjectPermission = FDocumentObjectPermission;
2328
- Object.defineProperty(exports, 'FDocumentParagraph', {
2328
+ Object.defineProperty(exports, "FDocumentParagraph", {
2329
2329
  enumerable: true,
2330
2330
  get: function () {
2331
2331
  return FDocumentParagraph;
2332
2332
  }
2333
2333
  });
2334
2334
  exports.FDocumentPermission = FDocumentPermission;
2335
- Object.defineProperty(exports, 'FDocumentSection', {
2335
+ Object.defineProperty(exports, "FDocumentSection", {
2336
2336
  enumerable: true,
2337
2337
  get: function () {
2338
2338
  return FDocumentSection;
2339
2339
  }
2340
2340
  });
2341
- Object.defineProperty(exports, 'FDocumentTextRange', {
2341
+ Object.defineProperty(exports, "FDocumentTextRange", {
2342
2342
  enumerable: true,
2343
2343
  get: function () {
2344
2344
  return FDocumentTextRange;