mirror of
https://github.com/ianstormtaylor/slate.git
synced 2025-08-31 02:49:56 +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
144
docs/concepts/02-nodes.md
Normal file
144
docs/concepts/02-nodes.md
Normal file
@@ -0,0 +1,144 @@
|
||||
# Nodes: Editor, Elements and Texts
|
||||
|
||||
The most important type are the `Node` objects:
|
||||
|
||||
- A root-level `Editor` node that contains their entire document's content.
|
||||
- Container `Element` nodes which have semantic meaning in your domain.
|
||||
- And leaf-level `Text` nodes which contain the document's text.
|
||||
|
||||
These three interfaces are combined together to form a tree—just like the DOM. For example, here's a simple plain-text value:
|
||||
|
||||
```js
|
||||
const editor = {
|
||||
children: [
|
||||
{
|
||||
type: 'paragraph',
|
||||
children: [
|
||||
{
|
||||
text: 'A line of text!',
|
||||
marks: [],
|
||||
},
|
||||
],
|
||||
},
|
||||
],
|
||||
// ...the editor has other properties too.
|
||||
}
|
||||
```
|
||||
|
||||
Mirroring the DOM as much as possible is one of Slate's principles. People use the DOM to represent documents with rich-text-like structures all the time. Mirroring the DOM helps make the library familiar for new users, and it lets us reuse battle-tested patterns without having to reinvent them ourselves.
|
||||
|
||||
> 🤖 The following content on Mozilla's Developer Network may help you learn more about the corresponding DOM concepts:
|
||||
>
|
||||
> - [Document](https://developer.mozilla.org/en-US/docs/Web/API/Document)
|
||||
> - [Block Elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Block-level_elements)
|
||||
> - [Inline elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Inline_elements)
|
||||
> - [Text elements](https://developer.mozilla.org/en-US/docs/Web/API/Text)
|
||||
|
||||
A Slate document is a nested and recursive structure. In a document, elements can have children nodes—all which may have children nodes without limit. The nested and recursive structure enables you to model simple behaviors such as user mentions and hashtags or complex behaviors such as tables and figures with captions.
|
||||
|
||||
## `Editor`
|
||||
|
||||
The top-level node in a Slate document is the `Editor` itself. It encapsulates all of the rich-text "content" of the document. Its interface is:
|
||||
|
||||
```ts
|
||||
interface Editor {
|
||||
children: Node[]
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
We'll cover its functionality later, but the important part as far as nodes are concerned is its `children` property which contains a tree of `Node` objects.
|
||||
|
||||
## `Element`
|
||||
|
||||
Elements make up the middle layers of a rich-text document. They are the nodes that are custom to your own domain. Their interface is:
|
||||
|
||||
```ts
|
||||
interface Element {
|
||||
children: Node[]
|
||||
[key: string]: any
|
||||
}
|
||||
```
|
||||
|
||||
You can define custom elements for any type of content you want. For example you might have paragraphs and quotes in your data model which are differentiated by a `type` property:
|
||||
|
||||
```js
|
||||
const paragraph = {
|
||||
type: 'paragraph',
|
||||
children: [...],
|
||||
}
|
||||
|
||||
const quote = {
|
||||
type: 'quote',
|
||||
children: [...],
|
||||
}
|
||||
```
|
||||
|
||||
It's important to note that you can use _any_ custom properties you want. The `type` property in that example isn't something Slate knows or cares about. If you were defining your own "link" nodes, you might have a `url` property:
|
||||
|
||||
```js
|
||||
const link = {
|
||||
type: 'link',
|
||||
url: 'https://example.com',
|
||||
children: [...],
|
||||
}
|
||||
```
|
||||
|
||||
Or maybe you want to give all of your nodes ID an property:
|
||||
|
||||
```js
|
||||
const paragraph = {
|
||||
id: 1,
|
||||
type: 'paragraph',
|
||||
children: [...],
|
||||
}
|
||||
```
|
||||
|
||||
All that matters is that elements always have a `children` property.
|
||||
|
||||
## Blocks vs. Inlines
|
||||
|
||||
Depending on your use case, you might want to define another behavior for `Element` nodes which determines their editing "flow".
|
||||
|
||||
All elements default to being "block" elements. They each appear separated by vertical space, and they never run into each other.
|
||||
|
||||
But in certain cases, like for links, you might want to make as "inline" flowing elements instead. That way they live at the same level as text nodes, and flow.
|
||||
|
||||
> 🤖 This is a concept borrowed from the DOM's behavior, see [Block Elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Block-level_elements) and [Inline Elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Inline_elements).
|
||||
|
||||
You can define which nodes are treated as inline nodes by overriding the `editor.isInline` function. (By default it always returns `false`.)
|
||||
|
||||
Elements can either contain block elements as children. Or they can contain inline elements intermingled with text nodes as children. But elements **cannot** contain some children that are blocks and some that are inlines.
|
||||
|
||||
## Voids
|
||||
|
||||
Similarly to blocks and inlines, there is another element-specific behavior you can define depending on your use case: their "void"-ness.
|
||||
|
||||
Elements default to being non-void, meaning that their children are fully editable as text. But in some cases, like for images, you want to ensure that Slate doesn't treat their content as editable text, but instead as a black box.
|
||||
|
||||
> 🤖 This is a concept borrowed from the HTML spec, see [Void Elements](https://www.w3.org/TR/2011/WD-html-markup-20110405/syntax.html#void-element).
|
||||
|
||||
You can do define which elements are treated as void by overriding the `editor.isVoid` function. (By default it always returns `false`.)
|
||||
|
||||
## `Text`
|
||||
|
||||
Text nodes are the lowest-level nodes in the tree, containing the text content of the document, along with any formatting. Their interface is:
|
||||
|
||||
```ts
|
||||
interface Text {
|
||||
text: string
|
||||
marks: Mark[]
|
||||
[key: string]: any
|
||||
}
|
||||
```
|
||||
|
||||
We'll cover `Mark` objects shortly, but for now you can get an idea for them:
|
||||
|
||||
```js
|
||||
const text = {
|
||||
text: 'A string of bold text',
|
||||
marks: [{ type: 'bold' }],
|
||||
}
|
||||
```
|
||||
|
||||
Text nodes too can contain any custom properties you want, although it is rarer to need to do that.
|
||||
Reference in New Issue
Block a user