docs: update documentation for new and existing APIs

.githooks/pre-commit.6.lint.sh

@@ -3,5 +3,4 @@
 if [ -n "$JS_STAGED" ];
 then
   npx eslint $JS_STAGED
-  npx documentation lint 'src/**/*.(ts|js|tsx)'
 fi

.github/renovate.json5

@@ -62,11 +62,6 @@
       groupName: "danger",
       automerge: true,
     },
-    {
-      packageNames: ["documentation"],
-      groupName: "documentation",
-      automerge: true,
-    },
     {
       packageNames: ["@types/jest", "react-scripts"],
       groupName: "react-scripts",

README.md

@@ -64,15 +64,15 @@ Here are all the available options:
 
 ```jsx
 // List of allowed block types. unstyled and atomic are always included.
-blocks: $ReadOnlyArray<string>,
+blocks: readonly string[]>,
 // List of allowed inline styles.
-styles: $ReadOnlyArray<string>,
+styles: readonly string[]>,
 // List of allowed entities.
-entities: $ReadOnlyArray<{
+entities: readonly []<{
   // Entity type, eg. "LINK"
   type: string,
   // Allowed attributes. Other attributes will be removed. If this is omitted, all attributes are kept.
-  attributes?: $ReadOnlyArray<string>,
+  attributes?: readonly string[]>,
   // Refine which entities are kept by matching acceptable values with regular expression patterns.
   // It's also possible to use "true" to signify that a field is required to be present,
   // and "false" for fields required to be absent.
@@ -88,7 +88,7 @@ whitespacedCharacters: Array<string>,
 // Optional: Rules used to automatically convert blocks from one type to another
 // based on the block’s text. Also supports setting the block depth.
 // Defaults to the filters’ built-in block prefix rules.
-blockTextRules?: $ReadOnlyArray<{
+blockTextRules?: readonly []<{
   // A regex as a string, to match against block text, e.g. "^(◦|o |o\t)".
   test: string,
   // The type to convert the block to if the test regex matches.
@@ -104,7 +104,9 @@ blockTextRules?: $ReadOnlyArray<{
 
 ### Types
 
-If your project uses [Flow](https://flow.org/), type inference should just work. If you don't use Flow, it won't get in your way either.
+If your project uses [TypeScript](https://www.typescriptlang.org/), type inference should just work. If you don't use TypeScript, it won't get in your way either.
+
+[Flow](https://flow.org/) types were included up to [v2.5.0](https://github.com/thibaudcolas/draftjs-filters/blob/main/CHANGELOG.md#250-2020-11-21) of the package, and have been removed in v3.0.0.
 
 ### Advanced usage
 
@@ -114,8 +116,6 @@ If using filters that remove blocks, be sure to use `applyContentWithSelection`
 
 #### API
 
-<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
-
 ##### preserveAtomicBlocks
 
 Creates atomic blocks where they would be required for a block-level entity
@@ -142,7 +142,7 @@ Removes atomic blocks for which the entity type isn't allowed.
 
 ###### Parameters
 
-- `allowlist` **$ReadOnlyArray<{type: [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)}>**
+- `allowlist` **readonly {type: [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)}[]**
 - `content` **ContentState**
 
 ##### removeInvalidDepthBlocks
@@ -164,7 +164,7 @@ ends up in the text. Other use cases may not be well covered.
 
 ###### Parameters
 
-- `rules` **$ReadOnlyArray<{test: [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String), type: [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String), depth: [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)}>**
+- `rules` **readonly {test: [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String), type: [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String), depth: [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)}[]**
 - `content` **ContentState**
 
 ##### limitBlockDepth
@@ -183,7 +183,7 @@ Also sets depth to 0 (for potentially nested list items).
 
 ###### Parameters
 
-- `allowlist` **$ReadOnlyArray<[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)>**
+- `allowlist` **readonly [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)[]**
 - `content` **ContentState**
 
 ##### filterInlineStyles
@@ -192,7 +192,7 @@ Removes all styles not present in the list.
 
 ###### Parameters
 
-- `allowlist` **$ReadOnlyArray<[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)>**
+- `allowlist` **readonly [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)[]**
 - `content` **ContentState**
 
 ##### cloneEntities
@@ -222,7 +222,7 @@ Keeps all entity types (images, links, documents, embeds) that are enabled.
 
 ###### Parameters
 
-- `allowlist` **$ReadOnlyArray<{type: [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)}>**
+- `allowlist` **readonly {type: [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)}[]**
 - `type` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**
 
 ##### shouldRemoveImageEntity
@@ -241,9 +241,9 @@ Filters entities based on the data they contain.
 
 ###### Parameters
 
-- `entityTypes` **$ReadOnlyArray<{type: [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String), allowlist: {}?, whitelist: {}?}>**
+- `entityTypes` **readonly {type: [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String), allowlist: {}?, whitelist: {}?}[]**
 - `entityType` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**
-- `data` **{}**
+- `data` **{ [attr: string]: any }**
 
 ##### filterEntityData
 
@@ -253,7 +253,7 @@ of unneeded attributes (width, height, etc).
 
 ###### Parameters
 
-- `entityTypes` **$ReadOnlyArray<{type: [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String), attributes: $ReadOnlyArray<[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)>?}>**
+- `entityTypes` **readonly {type: [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String), attributes: readonly [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)>?}[]**
 - `content` **ContentState**
 
 ##### replaceTextBySpaces
@@ -262,7 +262,7 @@ Replaces the given characters by their equivalent length of spaces, in all block
 
 ###### Parameters
 
-- `characters` **$ReadOnlyArray<[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)>**
+- `characters` **readonly [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)[]**
 - `content` **ContentState**
 
 ##### applyContentWithSelection
@@ -286,7 +286,26 @@ Will not alter the editor state if there are no changes to make.
 ###### Parameters
 
 - `options` **FilterOptions**
-- `editorState` **EditorStateType**
+- `editorState` **EditorState**
+
+##### condenseBlocks
+
+Condenses an array of content blocks into a single block.
+
+- Skipping the undo-redo stack.
+- Adding a space between each block to match the behavior of vanilla HTML fields.
+- Making sure the space gets the correct styles or entities applied.
+- Placing the selection at the same end offset as the last selection.
+
+This exhibits two known issues:
+
+- A link / other entity spread over multiple lines will be split into multiple entities of identical data.
+- Upon redo-ing the change, the selection isn’t correctly placed.
+
+###### Parameters
+
+- `nextState` **EditorState**
+- `prevState` **EditorState**
 
 ### Browser support and polyfills