diff --git a/docs/reference/slate-react/utils.md b/docs/reference/slate-react/utils.md index b735716d7..43f864139 100644 --- a/docs/reference/slate-react/utils.md +++ b/docs/reference/slate-react/utils.md @@ -2,7 +2,14 @@ # Utils ```js -import { findDOMNode } from 'slate-react' +import { + findDOMNode, + findDOMRange, + findNode, + findRange, + getEventRange, + getEventTransfer, +} from 'slate-react' ``` React-specific utility functions for Slate that may be useful in certain use cases. @@ -13,4 +20,30 @@ React-specific utility functions for Slate that may be useful in certain use cas ### `findDOMNode` `findDOMNode(node: Node) => DOMElement` -Find the DOM node for a Slate [`Node`](../slate/node.md). Modelled after React's built-in `findDOMNode` helper. +Find the DOM node from a Slate [`Node`](../slate/node.md). Modelled after React's built-in `findDOMNode` helper. + +### `findDOMRange` +`findDOMRange(range: Range) => DOMRange` + +Find the DOM range from a Slate [`Range`](../slate/range.md). + +### `findNode` +`findNode(element: DOMElement, state: State) => Node` + +Find the Slate node from a DOM `element` and Slate `state`. + +### `findRange` +`findRange(selection: DOMSelection, state: State) => Range` +`findRange(range: DOMRange, state: State) => Range` + +Find the Slate range from a DOM `range` or `selection` and a Slate `state`. + +### `getEventRange` +`getEventRange(event: DOMEvent, state: State) => Range` + +Find the affected Slate range from a DOM `event` and Slate `state`. + +### `getEventTransfer` +`getEventTransfer(event: DOMEvent) => Object` + +Find the Slate-related data from a DOM `event` and Slate `state`. diff --git a/packages/slate-react/Changelog.md b/packages/slate-react/Changelog.md index de07159c1..3d7a0e88b 100644 --- a/packages/slate-react/Changelog.md +++ b/packages/slate-react/Changelog.md @@ -11,7 +11,13 @@ This document maintains a list of changes to the `slate-react` package with each ###### DEPRECATED -- **The `data.*` properties that relate to keyboard events have been deprecated.** There were a few different issues with these "helpers": `data.key` didn't account for international keyboards, many properties awkwardly duplicated information that was available on `event.*`, but not completely, and many properties were confusing as to when they applied. If you were using these, you'll now need to use the native `event.*` properties instead. There's also a helpful [`is-hotkey`](https://github.com/ianstormtaylor/is-hotkey) package for more complex hotkey matching. +- **The `data` objects in event handlers have been deprecated.** There were a few different issues with these "helpers": `data.key` didn't account for international keyboards, many properties awkwardly duplicated information that was available on `event.*`, but not completely, and many properties were confusing as to when they applied. If you were using these, you'll now need to use the native `event.*` properties instead. There's also a helpful [`is-hotkey`](https://github.com/ianstormtaylor/is-hotkey) package for more complex hotkey matching. + +###### NEW + +- **Added a new `getEventRange` helper.** This gets the affected `Range` of Slate document given a DOM `event`. This is useful in the `onDrop` or `onPaste` handlers to retrieve the range in the document where the drop or paste will occur. + +- **Added a new `getEventTransfer` helper.** This gets any Slate-related data from an `event`. It is modelled after the DOM's [`DataTransfer`](https://developer.mozilla.org/en-US/docs/Web/API/DataTransfer) API, and is useful for retrieve the data being dropped or pasted in `onDrop` or `onPaste` events. ---