diff --git a/docs/Summary.md b/docs/Summary.md index b68928c4d..7e89d54f0 100644 --- a/docs/Summary.md +++ b/docs/Summary.md @@ -56,7 +56,9 @@ - [Slate React](libraries/slate-react/README.md) - [withReact](libraries/slate-react/with-react.md) - [ReactEditor](libraries/slate-react/react-editor.md) + - [Editable](libraries/slate-react/editable.md) - [Hooks](libraries/slate-react/hooks.md) + - [Event Handling](libraries/slate-react/event-handling.md) - [Slate History](libraries/slate-history/README.md) - [withHistory](libraries/slate-history/with-history.md) - [HistoryEditor](libraries/slate-history/history-editor.md) diff --git a/docs/libraries/slate-react/README.md b/docs/libraries/slate-react/README.md index 329bd6287..aaddef8a6 100644 --- a/docs/libraries/slate-react/README.md +++ b/docs/libraries/slate-react/README.md @@ -2,9 +2,13 @@ This sub-library contains the React-specific logic for Slate. +- Usage (under construction) + - [Event Handling](./event-handling.md) - [withReact](./with-react.md) - [ReactEditor](./react-editor.md) - [Hooks](./hooks.md) +- Slate (under construction) +- [Editable](./editable.md) ## Components @@ -24,50 +28,6 @@ The main Slate editor. #### Event Handling -By default, the `Editable` component comes with a set of event handlers that handle typical rich-text editing behaviors (for example, it implements its own `onCopy`, `onPaste`, `onDrop`, and `onKeyDown` handlers). - -In some cases you may want to extend or override Slate's default behavior, which can be done by passing your own event handler(s) to the `Editable` component. - -Your custom event handler can control whether or not Slate should execute its own event handling for a given event after your handler runs depending on the return value of your event handler as described below. - -```jsx -import {Editable} from 'slate-react'; - -function MyEditor() { - const onClick = event => { - // Implement custom event logic... - - // When no value is returned, Slate will execute its own event handler when - // neither isDefaultPrevented nor isPropagationStopped was set on the event - }; - - const onDrop = event => { - // Implement custom event logic... - - // No matter the state of the event, treat it as being handled by returning - // true here, Slate will skip its own event handler - return true; - }; - - const onDragStart = event => { - // Implement custom event logic... - - // No matter the status of the event, treat event as *not* being handled by - // returning false, Slate will execute its own event handler afterward - return false; - }; - - return ( - - ) -} -``` - ### `DefaultElement(props: RenderElementProps)` The default element renderer. @@ -76,7 +36,7 @@ The default element renderer. The default custom leaf renderer. -### `Slate(editor: ReactEditor, value: Node[], children: React.ReactNode, onChange: (value: Node[]) => void, [key: string]: any)` +### `Slate(props: { editor: ReactEditor, value: Node[], children: React.ReactNode, onChange: (value: Node[]) => void })` 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. diff --git a/docs/libraries/slate-react/editable.md b/docs/libraries/slate-react/editable.md new file mode 100644 index 000000000..029f1d956 --- /dev/null +++ b/docs/libraries/slate-react/editable.md @@ -0,0 +1,24 @@ +# Editable component + +#### `Editable(props: EditableProps)` + +The `Editable` component is the main editing component. Note that it must be inside a `Slate` component. + +It takes as its props, any props accepted by a Textarea element plus the following props. + +```typescript +export type EditableProps = { + decorate?: (entry: NodeEntry) => Range[] + onDOMBeforeInput?: (event: InputEvent) => void + placeholder?: string + readOnly?: boolean + role?: string + style?: React.CSSProperties + renderElement?: (props: RenderElementProps) => JSX.Element + renderLeaf?: (props: RenderLeafProps) => JSX.Element + renderPlaceholder?: (props: RenderPlaceholderProps) => JSX.Element + scrollSelectionIntoView?: (editor: ReactEditor, domRange: DOMRange) => void + as?: React.ElementType + disableDefaultStyles?: boolean +} & React.TextareaHTMLAttributes +``` diff --git a/docs/libraries/slate-react/event-handling.md b/docs/libraries/slate-react/event-handling.md new file mode 100644 index 000000000..909282ae5 --- /dev/null +++ b/docs/libraries/slate-react/event-handling.md @@ -0,0 +1,45 @@ +# Slate React Event Handling + +By default, the `Editable` component comes with a set of event handlers that handle typical rich-text editing behaviors (for example, it implements its own `onCopy`, `onPaste`, `onDrop`, and `onKeyDown` handlers). + +In some cases you may want to extend or override Slate's default behavior, which can be done by passing your own event handler(s) to the `Editable` component. + +Your custom event handler can control whether or not Slate should execute its own event handling for a given event after your handler runs depending on the return value of your event handler as described below. + +```jsx +import {Editable} from 'slate-react'; + +function MyEditor() { + const onClick = event => { + // Implement custom event logic... + + // When no value is returned, Slate will execute its own event handler when + // neither isDefaultPrevented nor isPropagationStopped was set on the event + }; + + const onDrop = event => { + // Implement custom event logic... + + // No matter the state of the event, treat it as being handled by returning + // true here, Slate will skip its own event handler + return true; + }; + + const onDragStart = event => { + // Implement custom event logic... + + // No matter the status of the event, treat event as *not* being handled by + // returning false, Slate will execute its own event handler afterward + return false; + }; + + return ( + + ) +} +```