From aacfde3bad567b41b9eaa1f1ebb0a7cfa9278627 Mon Sep 17 00:00:00 2001 From: Jolene Langlinais Date: Fri, 1 May 2020 15:16:36 -0400 Subject: [PATCH] docs(libraries): init docs for slate sub-libraries (#3645) * docs(libraries): init docs for slate sub-libraries Signed-off-by: irmerk * docs(libraries): reword slate history summary Co-authored-by: Cameron Ackerman Co-authored-by: Cameron Ackerman --- docs/Summary.md | 6 ++ docs/libraries/slate-history.md | 15 +++ docs/libraries/slate-hyperscript.md | 3 + docs/libraries/slate-react.md | 140 ++++++++++++++++++++++++++++ 4 files changed, 164 insertions(+) create mode 100644 docs/libraries/slate-history.md create mode 100644 docs/libraries/slate-hyperscript.md create mode 100644 docs/libraries/slate-react.md diff --git a/docs/Summary.md b/docs/Summary.md index d5106a1fd..9ef0ab364 100644 --- a/docs/Summary.md +++ b/docs/Summary.md @@ -32,6 +32,12 @@ - [Refs](./api/refs.md) - [Miscellaneous](./api/miscellaneous.md) +## Libraries + +- [Slate React](./libraries/slate-react.md) +- [Slate History](./libraries/slate-history.md) +- [Slate Hyperscript](./libraries/slate-hyperscript.md) + ## General - [Resources](./general/resources.md) diff --git a/docs/libraries/slate-history.md b/docs/libraries/slate-history.md new file mode 100644 index 000000000..aae3b5a8d --- /dev/null +++ b/docs/libraries/slate-history.md @@ -0,0 +1,15 @@ +# Slate History + +This sub-library tracks changes to the Slate value state over time, and enables undo and redo functionality. + +## `History` + +`History` objects hold all of the operations that are applied to a value, so they can be undone or redone as necessary. + +## `HistoryEditor` + +`HistoryEditor` contains helpers for history-enabled editors. + +## `withHistory` + +The `withHistory` plugin keeps track of the operation history of a Slate editor as operations are applied to it, using undo and redo stacks. diff --git a/docs/libraries/slate-hyperscript.md b/docs/libraries/slate-hyperscript.md new file mode 100644 index 000000000..db81fb0f6 --- /dev/null +++ b/docs/libraries/slate-hyperscript.md @@ -0,0 +1,3 @@ +# Slate Hyperscript + +This package contains a hyperscript helper for creating Slate documents with JSX! \ No newline at end of file diff --git a/docs/libraries/slate-react.md b/docs/libraries/slate-react.md new file mode 100644 index 000000000..1fc56c056 --- /dev/null +++ b/docs/libraries/slate-react.md @@ -0,0 +1,140 @@ +# Slate React + +This sub-library contains the React-specific logic for Slate. + +## Components + +React components for rendering Slate editors + +###### `RenderElementProps` + +`RenderElementProps` are passed to the `renderElement` handler. + +###### `RenderLeafProps` + +`RenderLeafProps` are passed to the `renderLeaf` handler. + +###### `Editable` + +The main Slate editor. + +###### `DefaultElement(props: RenderElementProps)` + +The default element renderer. + +###### `DefaultLeaf(props: RenderLeafProps)` + +The default custom leaf renderer. + +###### `Slate(editor: ReactEditor, value: Node[], children: React.ReactNode, onChange: (value: Node[]) => void, [key: string]: any)` + +A wrapper around the provider to handle `onChange` events, because the editor is a mutable singleton so it won't ever register as "changed" otherwise. + +## Hooks + +React hooks for Slate editors + +###### `useEditor` + +Get the current editor object from the React context. + +###### `useFocused` + +Get the current `focused` state of the editor. + +###### `useReadOnly` + +Get the current `readOnly` state of the editor. + +###### `useSelected` + +Get the current `selected` state of an element. + +###### `useSlate` + +Get the current editor object from the React context. + +## ReactEditor + +A React and DOM-specific version of the `Editor` interface. All about translating between the DOM and Slate. + +###### `findKey(editor: ReactEditor, node: Node)` + +Find a key for a Slate node. + +###### `findPath(editor: ReactEditor, node: Node)` + +Find the path of Slate node. + +###### `isFocused(editor: ReactEditor)` + +Check if the editor is focused. + +###### `isReadOnly(editor: ReactEditor)` + +Check if the editor is in read-only mode. + +###### `blur(editor: ReactEditor)` + +Blur the editor. + +###### `focus(editor: ReactEditor)` + +Focus the editor. + +###### `deselect(editor: ReactEditor)` + +Deselect the editor. + +###### `hasDOMNode(editor: ReactEditor, target: DOMNode, options: { editable?: boolean } = {})` + +Check if a DOM node is within the editor. + +###### `insertData(editor: ReactEditor, data: DataTransfer)` + +Insert data from a `DataTransfer` into the editor. + +###### `setFragmentData(editor: ReactEditor, data: DataTransfer)` + +Sets data from the currently selected fragment on a `DataTransfer`. + +###### `toDOMNode(editor: ReactEditor, node: Node)` + +Find the native DOM element from a Slate node. + +###### `toDOMPoint(editor: ReactEditor, point: Point)` + +Find a native DOM selection point from a Slate point. + +###### `toDOMRange(editor: ReactEditor, range: Range)` + +Find a native DOM range from a Slate `range`. + +###### `toSlateNode(editor: ReactEditor, domNode: DOMNode)` + +Find a Slate node from a native DOM `element`. + +###### `findEventRange(editor: ReactEditor, event: any)` + +Get the target range from a DOM `event`. + +###### `toSlatePoint(editor: ReactEditor, domPoint: DOMPoint)` + +Find a Slate point from a DOM selection's `domNode` and `domOffset`. + +###### `toSlatePoint(editor: ReactEditor, domPoint: DOMPoint)` + +Find a Slate range from a DOM range or selection. + +## Plugins + +React-specific plugins for Slate editors + +###### `withReact(editor: Editor)` + +Adds React and DOM specific behaviors to the editor. + +## Utils + +Private convenience modules +