.storybook/main.ts

@@ -0,0 +1,23 @@
+import type { StorybookConfig } from "@storybook/react-webpack5";
+
+const config: StorybookConfig = {
+  stories: ["../src/**/*.mdx", "../src/**/*.stories.@(js|jsx|mjs|ts|tsx)"],
+  addons: [
+    "@storybook/addon-links",
+    "@storybook/addon-essentials",
+    "@storybook/addon-onboarding",
+    "@storybook/addon-interactions",
+  ],
+  framework: {
+    name: "@storybook/react-webpack5",
+    options: {
+      builder: {
+        useSWC: true,
+      },
+    },
+  },
+  docs: {
+    autodocs: "tag",
+  },
+};
+export default config;

.storybook/preview.ts

@@ -0,0 +1,15 @@
+import type { Preview } from "@storybook/react";
+
+const preview: Preview = {
+  parameters: {
+    actions: { argTypesRegex: "^on[A-Z].*" },
+    controls: {
+      matchers: {
+        color: /(background|color)$/i,
+        date: /Date$/i,
+      },
+    },
+  },
+};
+
+export default preview;

CHANGELOG.md

@@ -1,4 +1,28 @@
 # Change Log
 
+## 1.6.0
+- added shardkey property
+
+## 1.5.1
+- IConfig->document is not required
+
+## 1.5.0
+- added props events_onRequestUsers
+- fix re-rendering of component after init editors
+
+## 1.4.1
+- improved load api.js
+- updated IConfig
+- bump dependencies
+
+## 1.3.0
+- extended IConfig
+
+## 1.2.0
+- added component property onLoadComponentError()
+
+## 1.1.0
+- added IConfig
+
 ## 1.0.0
 - Initial release

README.md

@@ -1,58 +1,140 @@
 # @onlyoffice/document-editor-react
 
-This repo contains the React component for [ONLYOFFICE Document Server](https://github.com/ONLYOFFICE/DocumentServer).
+This repo contains the ONLYOFFICE Docs React component which integrates [ONLYOFFICE Document Server](https://github.com/ONLYOFFICE/DocumentServer) into [React](https://react.dev/) projects.
 
-## Installation
-Install it from **npm** in your project. Run:
+**Please note**: Before working with this component, you need to install ONLYOFFICE Docs. To do so, you can use [Docker](https://github.com/onlyoffice/Docker-DocumentServer) (recommended).
 
-```bash
-npm install --save @onlyoffice/document-editor-react
+## Prerequisites
+
+This procedure requires [Node.js (and npm)](https://nodejs.org/en).
+
+## Creating the demo React application with ONLYOFFICE Docs editor
+
+This procedure creates a [basic React application](https://github.com/facebook/create-react-app) and installs an ONLYOFFICE Docs editor in it.
+
+1. Create a new React project named *onlyoffice-react-demo* using the *Create React App* package:
 ```
-or:
-```bash
-yarn add @onlyoffice/document-editor-react
+npx create-react-app onlyoffice-react-demo
 ```
 
-## Usage
+2. Go to the newly created directory:
+```
+cd onlyoffice-react-demo
+```
 
-Find below the component usage example:
+3. Install ONLYOFFICE Docs React component from **npm** and save it to the *package.json* file with *--save*:
 ```
-...
+npm install --save @onlyoffice/document-editor-react
+```
+
+4. Open the *./src/App.js* file in the *onlyoffice-react-demo* project and replace its contents with the following code:
+
+```
+import React, { useRef } from 'react';
 import { DocumentEditor } from "@onlyoffice/document-editor-react";
-...
-...
+
 var onDocumentReady = function (event) {
     console.log("Document is loaded");
 };
-...
-...
-<DocumentEditor
-  id="docxEditor"
-  documentServerUrl="http://documentserver/"
-  config={{
-    "document": {
-      "fileType": "docx",
-      "key": "Khirz6zTPdfd7",
-      "title": "Example Document Title.docx",
-      "url": "https://example.com/url-to-example-document.docx"
-    },
-    "documentType": "word",
-    "editorConfig": {
-      "callbackUrl": "https://example.com/url-to-callback.ashx"
+
+var onLoadComponentError = function (errorCode, errorDescription) {
+    switch(errorCode) {
+        case -1: // Unknown error loading component
+            console.log(errorDescription);
+            break;
+
+        case -2: // Error load DocsAPI from http://documentserver/
+            console.log(errorDescription);
+            break;
+
+        case -3: // DocsAPI is not defined
+            console.log(errorDescription);
+            break;
     }
-  }}
-  events_onDocumentReady={onDocumentReady}
-/>
-...
+};
+
+export default function App() {
+    return (
+        <>
+            <DocumentEditor
+                id="docxEditor"
+                documentServerUrl="http://documentserver/"
+                config={{
+                    "document": {
+                        "fileType": "docx",
+                        "key": "Khirz6zTPdfd7",
+                        "title": "Example Document Title.docx",
+                        "url": "https://example.com/url-to-example-document.docx"
+                    },
+                    "documentType": "word",
+                    "editorConfig": {
+                        "callbackUrl": "https://example.com/url-to-callback.ashx"
+                    }
+                }}
+                events_onDocumentReady={onDocumentReady}
+                onLoadComponentError={onLoadComponentError}
+            />
+        </>
+    );
+}
+```
+Replace the following lines with your own data:
+* **"http://documentserver/"** - replace with the URL of your server;
+* **"https://example.com/url-to-example-document.docx"** - replace with the URL to your file;
+* **"https://example.com/url-to-callback.ashx"** - replace with your callback URL (this is required for the saving functionality to work).
+
+This JavaScript file will create the *App* component containing the ONLYOFFICE Docs editor configured with basic features.
+
+5. Test the application using the Node.js development server:
+* To start the development server, navigate to the *onlyoffice-react-demo* directory and run:
+```
+npm run start
+```
+* To stop the development server, select on the command line or command prompt and press *Ctrl+C*.
+
+## Deploying the demo React application
+
+The easiest way to deploy the application to a production environment is to install [serve](https://github.com/vercel/serve) and create a static server:
+1. Install the *serve* package globally:
+```
+npm install -g serve
+```
+
+2. Serve your static site on the 3000 port:
+```
+serve -s build
+```
+Another port can be adjusted using the *-l* or *--listen* flags:
 ```
+serve -s build -l 4000
+```
+
+3. To serve the project folder, go to it and run the *serve* command:
+```
+cd onlyoffice-react-demo
+serve
+```
+
+Now you can deploy the application to the created server:
+1. Navigate to the *onlyoffice-react-demo* directory and run:
+```
+npm run build
+```
+The *build* directory will be created with a production build of your app.
+
+2. Copy the contents of the *onlyoffice-react-demo/build* directory to the root directory of the web server (to the *onlyoffice-react-demo* folder).
+
+The application will be deployed on the web server (*http://localhost:3000* by default).
 
 ## API
 ### Props
 | Name | Type | Default | Required | Description |
 | ------------- | ------------- | ------------- | ------------- | ------------- |
 | `id` | string | null | yes | Component unique identifier. |
 | `documentServerUrl` | string | null | yes | Address of ONLYOFFICE Document Server. |
-| `config` | object | null | yes | Generic configuration object for opening a file with token. [Config API](https://api.onlyoffice.com/editors/config/) | |
+| `shardkey` | string \| boolean | true | no | The string or boolean parameter required to request load balancing during collaborative editing: all users editing the same document are served by the same server. [Shard key](https://api.onlyoffice.com/docs/docs-api/get-started/how-it-works/#shard-key)|
+| `config` | object | null | yes | Generic configuration object for opening a file with token. [Config API](https://api.onlyoffice.com/editors/config/) |
+| `onLoadComponentError` | (errorCode: number, errorDescription: string) => void | null | no | The function called when an error occurs while loading a component |
 | `document_fileType` | string | null | no | The type of the file. |
 | `document_title` | string | null | no | The file name. |
 | `documentType` | string | null | no | The document type. |
@@ -71,13 +153,16 @@ var onDocumentReady = function (event) {
 | `events_onMakeActionLink` | (event: object) => void | null | no | The function called when the user is trying to get link for opening the document which contains a bookmark, scrolling to the bookmark position. |
 | `events_onRequestInsertImage` | (event: object) => void | null | no | The function called when the user is trying to insert an image by clicking the _Image from Storage_ button. |
 | `events_onRequestSaveAs` | (event: object) => void | null | no | The function called when the user is trying to save file by clicking _Save Copy as..._ button. |
-| `events_onRequestMailMergeRecipients` | (event: object) => void | null | no | the function called when the user is trying to select recipients data by clicking the _Mail merge_ button. |
-| `events_onRequestCompareFile` | (event: object) => void | null | no | The function called when the user is trying to select document for comparing by clicking the _Document from Storage_ button. |
+| `events_onRequestMailMergeRecipients` [DEPRECATED] | (event: object) => void | null | no | the function called when the user is trying to select recipients data by clicking the _Mail merge_ button. |
+| `events_onRequestCompareFile` [DEPRECATED] | (event: object) => void | null | no | The function called when the user is trying to select document for comparing by clicking the _Document from Storage_ button. |
 | `events_onRequestEditRights` | (event: object) => void | null | no | The function called when the user is trying to switch the document from the viewing into the editing mode by clicking the _Edit Document_ button. |
 | `events_onRequestHistory` | (event: object) => void | null | no | The function called when the user is trying to show the document version history by clicking the _Version History_ button. |
 | `events_onRequestHistoryClose` | (event: object) => void | null | no | The function called when the user is trying to go back to the document from viewing the document version history by clicking the _Close History_ button. |
 | `events_onRequestHistoryData` | (event: object) => void | null | no | The function called when the user is trying to click the specific document version in the document version history. |
 | `events_onRequestRestore` | (event: object) => void | null | no | The function called when the user is trying to restore the file version by clicking the _Restore_ button in the version history. |
+| `events_onRequestSelectSpreadsheet` | (event: object) => void | null | no | The function called when the user is trying to select recipients data by clicking the Mail merge button. |
+| `events_onRequestSelectDocument` | (event: object) => void | null | no | The function called when the user is trying to select a document for comparing or combining. |
+| `events_onRequestUsers` | (event: object) => void | null | no | The function called when  the user can select other users to mention in the comments, grant the access rights to edit the specific sheet ranges, or set the user avatars. |
 
 ## Storybook
 
@@ -88,11 +173,11 @@ Change the address of the document server in the *config/default.json* file:
 
 ### Build Storybook:
 ```
-yarn build-storybook
+npm run build-storybook
 ```
 ### Start Storybook:
 ```
-yarn storybook
+npm run storybook
 ```
 
 ## Development
@@ -103,15 +188,15 @@ git clone https://github.com/ONLYOFFICE/document-editor-react
 ```
 ### Install the project dependencies:
 ```
-yarn install
+npm install
 ```
 ### Test the component:
 ```
-yarn test
+npm run test
 ```
 ### Build the project:
 ```
-yarn rollup
+npm run rollup
 ```
 ### Create the package:
 ```