mirror of
https://github.com/ianstormtaylor/slate.git
synced 2025-08-30 10:29:48 +02:00
Next (#3093)
* remove some key usage from core, refactor Operations.apply * undeprecate some methods * convert more key usage to paths * update deprecations * convert selection commands to use all paths * refactor word boundary selection logic * convert many at-range commands to use paths * convert wrapBlock and wrapInline to not use keys * cleanup * remove chainability from editor * simplify commands, queries and middleware * convert deleteAtRange * remove key usage from schema, deprecate *ByKey methods * migrate *ByKey tests, remove index from *ByPath signatures * rename at-current-range tests * deprecate mode key usage, migrate more tests away from keys * deprecate range and point methods which rely on keys to work * refactor insertBlock, without fixing warnings * add pathRef/pointRef, fix insertBlock/Inline deprecations, work on insertFragment * refactor insertFragment * get rich-text example rendering * fix lint * refactor query files, fix more tests * remove unused queries, refactor others * deprecate splitDescendantsByPath * merge master * add typescript, convert slate, slate-hyperscript, slate-plain-serializer * add Point, Path, Range, Annotation tests * add Annotation, Change, Element, Fragment, Mark, Range, Selection, Value interfaces tests * add Operation and Text tests * add Node tests * get operations and normalization tests working for slate * get *AtPath command tests passing * rename *AtPath command tests * rename * get *AtPoint tests working * rename * rename * add value queries tests * add element, mark and path queries tests * convert most on-selection tests * convert on-selection commands * rename * get addMarks and delete commands working * rename * rename * rename * refactor value.positions(), work on delete tests * progress on delete tests * more delete work * finish delete tests * start converting to at-based commands * restructure query tests * restructure operations tests * more work converting to multi-purpose commands * lots of progress on converting to at-based commands * add unwrapNodes * remove setValue * more progress * refactor node commands to use consistent matching logic * cleanup, get non-fragment commands passing * remove annotations and isAtomic * rename surround/pluck to cover/uncover * add location concept, change at-path to from-path for iterables * refactor batches * add location-based queries * refactor hanging logic * more location query work * renaming * use getMatch more * add split to wrap/unwrap * flip levels/ancestors ordering * switch splitNodes to use levels * change split to always:false by default * fix tests * add more queries tests * fixing more delete logic * add more splitNodes tests * get rest of delete tests passing * fix location-based logic in some commands * cleanup * get previous packages tests passing again * add slate-history package * start slate-schema work * start of react working * rendering fixes * get rich and plain text examples working * get image example working with hooks and dropping * refactor onDrop to be internal * inline more event handlers * refactor lots of event-related logic * change rendering to use render props * delete unused stuff * cleanup dom utils * remove unused deps * remove unnecessary packages, add placeholder * remove slate-react-placeholder package * remove unused dep * remove unnecessary tests, fix readonly example * convert checklists example * switch to next from webpack * get link example working * convert more examples * preserve keys, memoized leafs/texts, fix node lookup * fix to always useLayoutEffect for ordering * fix annotations to be maps, memoize elements * remove Change interface * remove String interface * rename Node.entries to Node.nodes * remove unnecessary value queries * default to selection when iterating, cleanup * remove unused files * update scroll into view logic * fix undoing, remove constructor types * dont sync selection while composing * add workflows * remove unused deps * convert mentions example * tweaks * convert remaining examples * rename h to jsx, update schema * fix schema tests * fix slate-schema logic and tests * really fix slate-schema and forced-layout example * get start of insertFragment tests working * remove Fragment interface * remove debugger * get all non-skipped tests passing * cleanup deps * run prettier * configure eslint for typescript * more eslint fixes... * more passing * update some docs * fix examples * port windows undo hotkey change * fix deps, add basic firefox support * add event overriding, update walkthroughs * add commands, remove classes, cleanup examples * cleanup rollup config * update tests * rename queries tests * update other tests * update walkthroughs * cleanup interface exports * cleanup, change mark transforms to require location * undo mark transform change * more * fix tests * fix example * update walkthroughs * update docs * update docs * remove annotations * remove value, move selection and children to editor * add migrating doc * fix lint * fix tests * fix DOM types aliasing * add next export * update deps, fix prod build * fix prod build * update scripts * update docs and changelogs * update workflow and pull request template
This commit is contained in:
Ian Storm Taylor
GitHub
@@ -2,11 +2,8 @@
|
||||
|
||||
Since Slate is a monorepo with many packages that are versioned separately, we maintain a changelog for each individual package:
|
||||
|
||||
* [`slate`](https://github.com/ianstormtaylor/slate/tree/master/packages/slate/Changelog.md)
|
||||
* [`slate-base64-serializer`](https://github.com/ianstormtaylor/slate/tree/master/packages/slate-base64-serializer/Changelog.md)
|
||||
* [`slate-html-serializer`](https://github.com/ianstormtaylor/slate/tree/master/packages/slate-html-serializer/Changelog.md)
|
||||
* [`slate-hyperscript`](https://github.com/ianstormtaylor/slate/tree/master/packages/slate-hyperscript/Changelog.md)
|
||||
* [`slate-plain-serializer`](https://github.com/ianstormtaylor/slate/tree/master/packages/slate-plain-serializer/Changelog.md)
|
||||
* [`slate-prop-types`](https://github.com/ianstormtaylor/slate/tree/master/packages/slate-prop-types/Changelog.md)
|
||||
* [`slate-react`](https://github.com/ianstormtaylor/slate/tree/master/packages/slate-react/Changelog.md)
|
||||
* [`slate-simulator`](https://github.com/ianstormtaylor/slate/tree/master/packages/slate-simulator/Changelog.md)
|
||||
- [`slate`](https://github.com/ianstormtaylor/slate/tree/master/packages/slate/Changelog.md)
|
||||
- [`slate-history`](https://github.com/ianstormtaylor/slate/tree/master/packages/slate-history/Changelog.md)
|
||||
- [`slate-hyperscript`](https://github.com/ianstormtaylor/slate/tree/master/packages/slate-hyperscript/Changelog.md)
|
||||
- [`slate-react`](https://github.com/ianstormtaylor/slate/tree/master/packages/slate-react/Changelog.md)
|
||||
- [`slate-schema`](https://github.com/ianstormtaylor/slate/tree/master/packages/slate-schema/Changelog.md)
|
||||
|
||||
@@ -2,9 +2,9 @@
|
||||
|
||||
A series of common questions people have about Slate:
|
||||
|
||||
* [Why is content pasted as plain text?](#why-is-content-is-pasted-as-plain-text)
|
||||
* [What can a `Block` node have as its children?](#what-can-a-block-node-have-as-its-children)
|
||||
* [What browsers and devices does Slate support?](#what-browsers-and-devices-does-slate-support)
|
||||
- [Why is content pasted as plain text?](#why-is-content-is-pasted-as-plain-text)
|
||||
- [What can a `Block` node have as its children?](#what-can-a-block-node-have-as-its-children)
|
||||
- [What browsers and devices does Slate support?](#what-browsers-and-devices-does-slate-support)
|
||||
|
||||
### Why is content pasted as plain text?
|
||||
|
||||
@@ -12,18 +12,12 @@ One of Slate's core principles is that, unlike most other editors, it does **not
|
||||
|
||||
For the most part, this leads to increased flexbility without many downsides, but there are certain cases where you have to do a bit more work. Pasting is one of those cases.
|
||||
|
||||
Since Slate knows nothing about your schema, it can't know how to parse pasted HTML content (or other content). So, by default whenever a user pastes content into a Slate editor, it will parse it as plain text. If you want it to be smarter about pasted content, you need to define an [`onPaste`](../reference/slate-react/editor.md#onpaste) handler that parses the content as you wish.
|
||||
|
||||
### What can a `Block` node have as its children?
|
||||
|
||||
With Slate, you can use `Block` node to created complex nested structures. Block nodes may contain nested block nodes (both void and non-void), inline nodes, text nodes and just regular DOM elements (with `contentEditable = {false}`).
|
||||
|
||||
If you have an element that is not going to be editable, you can choose between a `void` node or just a DOM element with `contentEditable = {false}`. Opt for the `void` node if you would like it represented in the Slate schema, and for Slate to be aware of it.
|
||||
Since Slate knows nothing about your schema, it can't know how to parse pasted HTML content (or other content). So, by default whenever a user pastes content into a Slate editor, it will parse it as plain text. If you want it to be smarter about pasted content, you need to override the `insert_data` command and deserialize the `DataTransfer` object's `text/html` data as you wish.
|
||||
|
||||
### What browsers and devices does Slate support?
|
||||
|
||||
Slate's goal is to support all the modern browsers on both desktop and mobile devices.
|
||||
|
||||
However, right now Slate is in beta and is community-driven, so its support is not as robust as it could be. It's currently tested against the latest few versions of Chrome, Firefox and Safari on desktops. It isn't currently tested against Internet Explorer or Edge, or against mobile devices. If you want to add more browser or device support, we'd love for you to submit a pull request!
|
||||
However, right now Slate is in beta and is community-driven, so its support is not as robust as it could be. It's currently tested against the latest few versions of Chrome, Edge, Firefox and Safari on desktops. It is not regularly tested on mobile devices. And it does not work in Internet Explorer. If you want to add more browser or device support, we'd love for you to submit a pull request! Or in the case of incompatible browsers, build a plugin.
|
||||
|
||||
For older browsers, such as IE11, a lot of the now standard native APIs aren't available. Slate's position on this is that it is up to the user to bring polyfills (like https://polyfill.io) when needed for things like `el.closest`, etc. Otherwise we'd have to bundle and maintain lots of polyfills that others may not even need in the first place.
|
||||
|
||||
@@ -1,133 +0,0 @@
|
||||
# Glossary
|
||||
|
||||
A glossary explaining the terms commonly used in Slate:
|
||||
|
||||
### Anchor
|
||||
|
||||
An _"anchor point"_ is a point where a range starts.
|
||||
|
||||
|
||||
|
||||
### Block
|
||||
|
||||
### Blur
|
||||
|
||||
### Change
|
||||
|
||||
### Character
|
||||
|
||||
A _"character"_ is the smallest element that makes up a text node in Slate.
|
||||
|
||||
### Collapsed
|
||||
|
||||
A selection is _"collapsed"_ when text is deselected. A collapse occurs when a range's start and end points are the same.
|
||||
|
||||
|
||||
|
||||
### Core
|
||||
|
||||
### Data
|
||||
|
||||
### Decoration
|
||||
|
||||
### Document
|
||||
|
||||
The _"document"_ is the top-level ["node"](#node) that contains all other nodes that make up the content of the Slate editor.
|
||||
|
||||
### Editor
|
||||
|
||||
### Extend
|
||||
|
||||
### Focus
|
||||
|
||||
Focus is defined differently based on your context:
|
||||
|
||||
#### Focus Point
|
||||
|
||||
A _"focus point"_ is where a range ends. Unlike a anchor point, a focus point can be expanded.
|
||||
|
||||
|
||||
|
||||
#### Focus Block
|
||||
|
||||
The editor value provides a reference to the current _"focus block"_ as a convenience. For example, you access the words within the block a user is focused on like so: `const words = editor.value.focusBlock.text.split(' ');`
|
||||
|
||||
### Fragment
|
||||
|
||||
### History
|
||||
|
||||
### Inline
|
||||
|
||||
### Key
|
||||
|
||||
A _"keys"_ is a unique identifier assigned to a node in Slate and is used to reference a node uniquely. As as the document changes, new unique keys are issued to avoid collisions within the data model.
|
||||
|
||||
### Mark
|
||||
|
||||
A _"mark"_ represents formatting data that is attached to characters within text. Standard formatting such as **bold**, _italic_, `code`, or custom formatting for your application can be implemented using marks.
|
||||
|
||||
### Match
|
||||
|
||||
A `match`, is an object with possible fields of `type` and `object` that are used to _match_ `Nodes` when defining rules in a [Schema](../reference/slate/schema.md). An example of `match` could be `{type: 'paragraph'}`, `{objet: 'inline', type: '@-tag'}`, etc.
|
||||
|
||||
### Merge
|
||||
|
||||
### Model
|
||||
|
||||
### Node
|
||||
|
||||
### Normalize
|
||||
|
||||
### Offset
|
||||
|
||||
An _"offset"_ is a distance from the start of a text node, measured in ["characters"](#character).
|
||||
|
||||
### Operation
|
||||
|
||||
### Placeholder
|
||||
|
||||
### Plugin
|
||||
|
||||
A _"plugin"_ is a reusable object that implements one or more of Slate's plugin hooks to add specific behavior to your editor. A plugin helps you express your application while keeping it easy to maintain and reason about.
|
||||
|
||||
### Point
|
||||
|
||||
A _"point"_ represents a specific location in a document, where a user's cursor could be placed. It is represented by the `key` of the node in the document, and the `offset` of characters into a node.
|
||||
|
||||
### Range
|
||||
|
||||
A _"range"_ is a way to represent a specific section of a document between two ["points"](#point). It is modelled after the [DOM Range](https://developer.mozilla.org/en-US/docs/Web/API/Range) concept.
|
||||
|
||||
### Redo
|
||||
|
||||
### Rule
|
||||
|
||||
### Schema
|
||||
|
||||
A Slate _"schema"_ is a JavaScript object with properties that describe the document, block nodes, and inline nodes in your editor. Every Slate editor has a "schema" associated with it, which contains information about the structure of its content. For the most basic cases, you'll just rely on Slate's default core schema. But for advanced use cases, you can enforce rules about what the content of a Slate document can contain. Read [Schema reference](../reference/slate/schema.md) to learn more.
|
||||
|
||||
### Selection
|
||||
|
||||
### Serializer
|
||||
|
||||
### Split
|
||||
|
||||
### Stack
|
||||
|
||||
### Text
|
||||
|
||||
### Undo
|
||||
|
||||
### Unwrap
|
||||
|
||||
To _"unwrap"_ is the opposite of to ["wrap"](#wrap), removing a surrounding node from a selection.
|
||||
|
||||
### Validate
|
||||
|
||||
### Value
|
||||
|
||||
A Slate _"value"_ is the top-level object in Slate and is an object encapsulating the entire value of a Slate editor. Read the [Data Model guide](../guides/data-model.md#the-value) to learn more.
|
||||
|
||||
### Wrap
|
||||
|
||||
To _"wrap"_ is to surround a piece of text or a node in another node. For example, if you select the text `Google` and want to turn it into a link, you'd "wrap" it with an inline link node.
|
||||
@@ -1,53 +0,0 @@
|
||||
# Plugins
|
||||
|
||||
Here's a list of Slate plugins, organized by category, so that they're easier to find than searching NPM or Yarn.
|
||||
|
||||
### Behavior
|
||||
|
||||
Plugins that add specific behaviors to your editor.
|
||||
|
||||
| **Plugin** | **Description** | **Downloads** |
|
||||
| ----------------------------------------------------------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
|
||||
| [`slate-auto-replace`](https://yarnpkg.com/en/package/slate-auto-replace) | Automatically transform certain input as a user types. |  |
|
||||
| [`slate-code`](https://yarnpkg.com/en/package/@convertkit/slate-code) | Adds code block editing behaviors to an editor |  |
|
||||
| [`slate-collapse-on-escape`](https://yarnpkg.com/en/package/slate-collapse-on-escape) | Collapse the selection when users hit <kbd>esc</kbd>. |  |
|
||||
| [`slate-drop-or-paste-images`](https://yarnpkg.com/en/package/slate-drop-or-paste-images) | Allows users to insert images by drag-dropping or copy-pasting. |  |
|
||||
| [`slate-lists`](https://yarnpkg.com/en/package/@convertkit/slate-lists) | Adds ordered and unordered list editing behaviors to an editor. |  |
|
||||
| [`slate-mark-hotkeys`](https://yarnpkg.com/en/package/slate-mark-hotkeys) | Adds common hotkey formatting utils to an editor. |  |
|
||||
| [`slate-no-empty`](https://yarnpkg.com/en/package/slate-no-empty) | Prevents documents from being empty. |  |
|
||||
| [`slate-paste-linkify`](https://yarnpkg.com/en/package/slate-paste-linkify) | Automatically linkify URLs when they are pasted. |  |
|
||||
| [`slate-soft-break`](https://yarnpkg.com/en/package/slate-soft-break) | Adds soft breaks when users hit <kbd>enter</kbd>. |  |
|
||||
| [`slate-sticky-inlines`](https://yarnpkg.com/en/package/slate-sticky-inlines) | Changes the inline node behavior to allow editing at the edges. |  |
|
||||
| [`slate-suggestions`](https://yarnpkg.com/en/package/slate-suggestions) | Displays inline auto-completed suggestions. |  |
|
||||
| [`slate-trailing-block`](https://yarnpkg.com/en/package/slate-trailing-block) | Ensure that documents end in a specific kind of block. |  |
|
||||
| [`slate-instant-replace`](https://www.npmjs.com/package/slate-instant-replace) | Automatically transform last word typed. |  |
|
||||
|
||||
Find more plugins on [npm](https://www.npmjs.com/search?q=slate%20plugin&page=0&perPage=20) or [yarn](https://yarnpkg.com/en/packages?q=slate%20plugin&p=1).
|
||||
|
||||
### Components
|
||||
|
||||
Components for building Slate editors.
|
||||
|
||||
| **Plugin** | **Description** | **Downloads** |
|
||||
| ------------------------------------------------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------- |
|
||||
| [`slate-editor-icons`](https://yarnpkg.com/en/package/slate-editor-icons) | A set of icons for using in toolbars, etc. |  |
|
||||
|
||||
### Serializers
|
||||
|
||||
Serializers for handling Slate data.
|
||||
|
||||
| **Plugin** | **Description** | **Downloads** |
|
||||
| ----------------------------------------------------------------------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------- |
|
||||
| [`slate-base64-serializer`](https://yarnpkg.com/en/package/slate-base64-serializer) | A base64 string serializer for Slate documents. |  |
|
||||
| [`slate-html-serializer`](https://yarnpkg.com/en/package/slate-html-serializer) | An HTML serializer for Slate documents. |  |
|
||||
| [`slate-plain-serializer`](https://yarnpkg.com/en/package/slate-plain-serializer) | A plain text serializer for Slate documents. |  |
|
||||
|
||||
### Utils
|
||||
|
||||
Useful utilities when working with Slate documents and components.
|
||||
|
||||
| **Plugin** | **Description** | **Downloads** |
|
||||
| ----------------------------------------------------------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------- |
|
||||
| [`slate-hyperprint`](https://yarnpkg.com/en/package/slate-hyperprint) | Prints Slate documents in their `slate-hyperscript` format. |  |
|
||||
| [`slate-hyperscript`](https://yarnpkg.com/en/package/slate-hyperscript) | Allows you to express Slate documents in JSX. |  |
|
||||
| [`slate-prop-types`](https://yarnpkg.com/en/package/slate-prop-types) | A set of prop types to use in your Slate components. |  |
|
||||
@@ -6,43 +6,36 @@ A few resources that are helpful for building with Slate.
|
||||
|
||||
These libraries are helpful when developing with Slate:
|
||||
|
||||
* [`is-hotkey`](https://github.com/ianstormtaylor/is-hotkey) is a simple way to check whether an `onKeyDown` handler should fire for a given hotkey, handling cross-platform concerns like <kbd>cmd</kbd> vs. <kbd>ctrl</kbd> keys for you automatically.
|
||||
* [`react-broadcast`](https://github.com/ReactTraining/react-broadcast) works well when you need to have your custom node components re-render based on state that lives outside the `document`. It's the same pattern that `react-router` uses to update `<Link>` components.
|
||||
|
||||
## Tools
|
||||
|
||||
These tools are helpful when developing with Slate:
|
||||
|
||||
* [Immutable.js Console Extension](https://github.com/mattzeunert/immutable-object-formatter-extension) greatly improves the `console.log` output when working with [Immutable.js](https://immutable-js.github.io/immutable-js/) objects, which Slate's data model is based on.
|
||||
- [`is-hotkey`](https://github.com/ianstormtaylor/is-hotkey) is a simple way to check whether an `onKeyDown` handler should fire for a given hotkey, handling cross-platform concerns like <kbd>cmd</kbd> vs. <kbd>ctrl</kbd> keys for you automatically.
|
||||
|
||||
## Products
|
||||
|
||||
These products use Slate, and can give you an idea of what's possible:
|
||||
|
||||
* [Cake](https://www.cake.co/)
|
||||
* [Archbee](https://archbee.io)
|
||||
* [Chatterbug](https://chatterbug.com)
|
||||
* [GitBook](https://www.gitbook.com/)
|
||||
* [Grafana](https://grafana.com/)
|
||||
* [Guilded](https://www.guilded.gg)
|
||||
* [Guru](https://www.getguru.com/)
|
||||
* [Netlify CMS](https://www.netlifycms.org)
|
||||
* [Outline](https://www.getoutline.com/)
|
||||
* [Prezly](https://www.prezly.com/)
|
||||
* [Sanity.io](https://www.sanity.io)
|
||||
* [Taskade](https://www.taskade.com/)
|
||||
* [Yuque](https://www.yuque.com/)
|
||||
* [Thoughts](https://thoughts.teambition.com)
|
||||
- [Archbee](https://archbee.io)
|
||||
- [Cake](https://www.cake.co/)
|
||||
- [Chatterbug](https://chatterbug.com)
|
||||
- [GitBook](https://www.gitbook.com/)
|
||||
- [Grafana](https://grafana.com/)
|
||||
- [Guilded](https://www.guilded.gg)
|
||||
- [Guru](https://www.getguru.com/)
|
||||
- [Netlify CMS](https://www.netlifycms.org)
|
||||
- [Outline](https://www.getoutline.com/)
|
||||
- [Prezly](https://www.prezly.com/)
|
||||
- [Sanity.io](https://www.sanity.io)
|
||||
- [Taskade](https://www.taskade.com/)
|
||||
- [Yuque](https://www.yuque.com/)
|
||||
- [Thoughts](https://thoughts.teambition.com)
|
||||
|
||||
## Editors
|
||||
|
||||
These pre-packaged editors are built on top of Slate, and can be helpful to see how you might structure your code:
|
||||
|
||||
* [Canner Editor](https://github.com/Canner/canner-slate-editor) is a rich text editor.
|
||||
* [French Press Editor](https://github.com/roast-cms/french-press-editor) is a customizeable editor with offline support.
|
||||
* [Nossas Editor](http://slate-editor.bonde.org/) is a drop-in WYSIWYG editor.
|
||||
* [ORY Editor](https://editor.ory.am/) is a self-contained, inline WYSIWYG editor library.
|
||||
* [Outline Editor](https://github.com/outline/rich-markdown-editor) is the editor that powers the [Outline](https://www.getoutline.com/) wiki.
|
||||
* [Chatterslate](https://github.com/chatterbugapp/chatterslate) helps teach language grammar and more at [Chatterbug](https://chatterbug.com).
|
||||
- [Canner Editor](https://github.com/Canner/canner-slate-editor) is a rich text editor.
|
||||
- [Chatterslate](https://github.com/chatterbugapp/chatterslate) helps teach language grammar and more at [Chatterbug](https://chatterbug.com).
|
||||
- [French Press Editor](https://github.com/roast-cms/french-press-editor) is a customizeable editor with offline support.
|
||||
- [Nossas Editor](http://slate-editor.bonde.org/) is a drop-in WYSIWYG editor.
|
||||
- [ORY Editor](https://editor.ory.am/) is a self-contained, inline WYSIWYG editor library.
|
||||
- [Outline Editor](https://github.com/outline/rich-markdown-editor) is the editor that powers the [Outline](https://www.getoutline.com/) wiki.
|
||||
|
||||
(Or, if you have their exact use case, can be a drop-in editor for you.)
|
||||
|
||||
Reference in New Issue
Block a user