feat: supplement docs document

content/en-US/guides/docs/features/_meta.tsx

@@ -0,0 +1,18 @@
+import ProTag from '@/components/pro-tag'
+
+export default {
+  'core': 'Core',
+  'hyperlink': 'Hyperlink',
+  'floating-images': 'Floating Images',
+  'thread-comment': 'Thread Comment',
+  'watermark': 'Watermark',
+  'print': {
+    title: <ProTag>Print</ProTag>,
+  },
+  'import-export': {
+    title: <ProTag>Import & Export</ProTag>,
+  },
+  'collaboration': {
+    title: <ProTag>Collaborative Editing</ProTag>,
+  },
+}

content/en-US/guides/docs/features/collaboration.mdx

@@ -0,0 +1,179 @@
+import FeatureMeta from '@/components/feature-meta'
+
+# Collaborative Editing
+
+<FeatureMeta texts={['-', '✅', '✅', '-', 'UniverDocsCollaborationPreset' ]} />
+
+Univer provides collaborative editing functions, supporting multiple people to edit the same document at the same time.
+
+This feature includes the following plugin packages:
+
+- [`@univerjs-pro/collaboration`](https://www.npmjs.com/package/@univerjs-pro/collaboration)
+- [`@univerjs-pro/collaboration-client` ](https://www.npmjs.com/package/@univerjs-pro/collaboration-client)
+
+## Presets Installation
+
+```typescript {6-7,14,24,28,33-35}
+import { createUniver, defaultTheme, LocaleType, merge } from '@univerjs/presets';
+import { UniverDocsCorePreset } from '@univerjs/presets/preset-docs-core';
+import UniverPresetDocsCoreEnUS from '@univerjs/presets/preset-docs-core/locales/en-US';
+import { UniverDocsAdvancedPreset } from '@univerjs/presets/preset-docs-advanced';
+import UniverPresetDocsAdvancedEnUS from '@univerjs/presets/preset-docs-advanced/locales/en-US';
+import { UniverDocsCollaborationPreset } from '@univerjs/presets/preset-docs-collaboration';
+import UniverPresetDocsCollaborationEnUS from '@univerjs/presets/preset-docs-collaboration/locales/en-US';
+import { UniverDocsDrawingPreset } from '@univerjs/presets/preset-docs-drawing'
+import UniverPresetDocsDrawingEnUS from '@univerjs/presets/preset-docs-drawing/locales/en-US'
+
+import '@univerjs/presets/lib/styles/preset-docs-core.css'
+import '@univerjs/presets/lib/styles/preset-docs-drawing.css'
+import '@univerjs/presets/lib/styles/preset-docs-advanced.css'
+import '@univerjs/presets/lib/styles/preset-docs-collaboration.css'
+
+const { univerAPI } = createUniver({
+  locale: LocaleType.EN_US,
+  locales: {
+    [LocaleType.EN_US]: merge(
+      {},
+      UniverPresetDocsCoreEnUS,
+      UniverPresetDocsDrawingEnUS,
+      UniverPresetDocsAdvancedEnUS,
+      UniverPresetDocsCollaborationEnUS,
+    ),
+  },
+  theme: defaultTheme,
+  collaboration: true,
+  presets: [
+    UniverDocsCorePreset(),
+    UniverDocsDrawingPreset(),
+    UniverDocsAdvancedPreset(),
+    UniverDocsCollaborationPreset({
+      universerEndpoint: 'http://localhost:3010',
+    }),
+  ],
+});
+```
+
+## Piecemeal Installation
+
+```shell npm2yarn
+npm install @univerjs-pro/collaboration @univerjs-pro/collaboration-client
+```
+
+```typescript {3-6,8-9,11,18,28-29,33-41}
+import { LocaleType, merge, Univer } from '@univerjs/core';
+import { defaultTheme } from "@univerjs/design";
+import { UniverCollaborationPlugin } from '@univerjs-pro/collaboration';
+import { UniverCollaborationClientPlugin } from '@univerjs-pro/collaboration-client';
+import { UniverCollaborationClientUIPlugin, BrowserCollaborationSocketService } from '@univerjs-pro/collaboration-client-ui';
+import CollaborationClientEnUS from '@univerjs-pro/collaboration-client/locale/en-US';
+
+import '@univerjs-pro/collaboration-client/facade';
+import '@univerjs-pro/collaboration-client-ui/facade';
+
+import '@univerjs-pro/collaboration-client/lib/index.css';
+
+const univer = new Univer({
+  theme: defaultTheme,
+  locale: LocaleType.EN_US,
+  locales: {
+    [LocaleType.EN_US]: merge(
+      CollaborationClientEnUS
+    ),
+  },
+});
+
+// By setting the override option to [[IAuthzIoService, null]], you can instruct Univer not to register the built-in IAuthzIoService.
+// By setting the override option to [[IUndoRedoService, null]], you can instruct Univer not to register the built-in IUndoRedoService.
+// This way, Univer will use the services provided by the UniverCollaborationPlugin as the implementation for the authorization and undo-redo features.
+const univer = new Univer({
+  override: [
+    [IAuthzIoService, null]
+    [IUndoRedoService, null],
+  ],
+});
+
+univer.registerPlugin(UniverCollaborationPlugin);
+univer.registerPlugin(UniverCollaborationClientPlugin, {
+  socketService: BrowserCollaborationSocketService,
+  authzUrl: 'http://localhost:3010/universer-api/authz',
+  snapshotServerUrl: 'http://localhost:3010/universer-api/snapshot',
+  collabSubmitChangesetUrl: 'http://localhost:3010/universer-api/comb',
+  collabWebSocketUrl: 'ws://localhost:3010/universer-api/comb/connect',
+});
+univer.registerPlugin(UniverCollaborationClientUIPlugin);
+```
+
+## Collaborative Document Data
+
+The collaborative editing plugin relies on the Univer server, and the data for collaborative documents is stored in the Univer server.
+
+### unitId
+
+Each collaborative document in the Univer server has a unique `unitId`. The Univer collaboration client (collaborative editing plugin) uses the `unitId` to retrieve the corresponding collaborative document data from the Univer server for collaborative editing.
+
+### type
+
+`type` is the type of the collaborative document, which determines the initial data structure of the collaborative document.
+
+## Creating Collaborative Documents
+
+There are multiple ways to create collaborative documents in the Univer server:
+
+1. You can create a blank document using the [Create Unit](/en-US/guides/sheets/pro-features/server/api#create-empty-document) API.
+2. You can import an DOCX file into the Univer server using the [`importDOCXToUnitIdAsync`](/en-US/guides/docs/features/import-export) method provided by the [Import Plugin](/en-US/guides/docs/features/import-export#import-docx-and-get-unitid) Facade API.
+
+## Loading Collaborative Documents with URL Parameters
+
+`@univerjs-pro/collaboration-client` plugin provides a feature that automatically loads corresponding data according to the URL parameters `unit` and `type`, which can simplify the data loading logic in some cases.
+
+If you want to use this feature, you need to modify the original data loading logic appropriately and add the `unit` and `type` parameters to the URL, as shown below:
+
+```diff
+import { UniverInstanceType } from '@univerjs/core';
+
+# Original logic, only applicable to non-collaborative documents
+- univer.createUnit(UniverInstanceType.UNIVER_DOC, {});
+
+# Modified logic, applicable to collaborative documents
++ const url = new URL(window.location.href);
++ const unit = url.searchParams.get('unit');
+
++ if (unit) {
++   // If the URL contains the unit parameter, the data will be loaded automatically
++ } else {
++   // Or create a new workbook
++   fetch(`/universer-api/snapshot/${UniverInstanceType.UNIVER_DOC}/unit/-/create`, {
++     method: 'POST',
++     headers: {
++       'Content-Type': 'application/json',
++     },
++     body: JSON.stringify({
++       type: UniverInstanceType.UNIVER_DOC, // instance type
++       name: 'New Doc By Univer', // doc name
++       creator: 'user',  // creator name
++     }),
++   }).then((response) => {
++     if (!response.ok) {
++       throw new Error('create unit failed');
++     }
++
++     return response.json();
++   }).then((data) => {
++     if (!data.unitID) {
++       throw new Error('create unit failed');
++     }
++
++     url.searchParams.set('unit', data.unitID);
++     url.searchParams.set('type', String(UniverInstanceType.UNIVER_DOC));
++     window.location.href = url.toString();
++   }).catch((error) => {
++     console.error(error);
++   })
++ }
+```
+
+## Further Reading
+
+If you want to learn more about how collaborative editing works, you can read the following article:
+
+- [OT Algorithm and Univer's Collaborative Editing Design](/blog/ot)