From 0ef080723fd02920dc79272f3c34e360053cf22b Mon Sep 17 00:00:00 2001 From: Sunny Hirai Date: Mon, 29 Mar 2021 00:02:43 -0700 Subject: [PATCH] Split API reference so each object has its own page --- docs/Summary.md | 14 +- docs/api/editor.md | 375 +++++++++++++++++++++++++++++++++++ docs/api/element.md | 24 +++ docs/api/locations.md | 234 +--------------------- docs/api/nodes.md | 440 +----------------------------------------- docs/api/path.md | 116 +++++++++++ docs/api/point-ref.md | 17 ++ docs/api/point.md | 39 ++++ docs/api/range-ref.md | 17 ++ docs/api/range.md | 69 +++++++ docs/api/refs.md | 39 +--- docs/api/text.md | 30 +++ 12 files changed, 710 insertions(+), 704 deletions(-) create mode 100644 docs/api/editor.md create mode 100644 docs/api/element.md create mode 100644 docs/api/path.md create mode 100644 docs/api/point-ref.md create mode 100644 docs/api/point.md create mode 100644 docs/api/range-ref.md create mode 100644 docs/api/range.md create mode 100644 docs/api/text.md diff --git a/docs/Summary.md b/docs/Summary.md index 9de1d6bee..f47611b84 100644 --- a/docs/Summary.md +++ b/docs/Summary.md @@ -28,9 +28,17 @@ ## API - [Transforms](./api/transforms.md) -- [Nodes (Node, Editor, Element, Text)](./api/nodes.md) -- [Locations (Path, Point, Range)](./api/locations.md) -- [Refs (PointRef, RangeRef)](./api/refs.md) +- [Node](./api/nodes.md) + - [Editor](./api/editor.md) + - [Element](./api/element.md) + - [Text](./api/text.md) +- [Location](./api/locations.md) + - [Path](./api/path.md) + - [Point](./api/point.md) + - [Range](./api/range.md) +- [Refs](./api/refs.md) + - [PointRef](./api/point-ref.md) + - [RangeRef](./api/range-ref.md) - [Miscellaneous](./api/miscellaneous.md) ## Libraries diff --git a/docs/api/editor.md b/docs/api/editor.md new file mode 100644 index 000000000..d9fcb48b1 --- /dev/null +++ b/docs/api/editor.md @@ -0,0 +1,375 @@ +# Editor + +The `Editor` object stores all the state of a slate editor. It can be extended by plugins to add helpers and implement new behaviors. + +```typescript +interface Editor { + children: Node[] + selection: Range | null + operations: Operation[] + marks: Record | null + [key: string]: unknown + + // Schema-specific node behaviors. + isInline: (element: Element) => boolean + isVoid: (element: Element) => boolean + normalizeNode: (entry: NodeEntry) => void + onChange: () => void + + // Overrideable core actions. + addMark: (key: string, value: any) => void + apply: (operation: Operation) => void + deleteBackward: (unit: 'character' | 'word' | 'line' | 'block') => void + deleteForward: (unit: 'character' | 'word' | 'line' | 'block') => void + deleteFragment: () => void + insertBreak: () => void + insertFragment: (fragment: Node[]) => void + insertNode: (node: Node) => void + insertText: (text: string) => void + removeMark: (key: string) => void +} +``` + +## Static methods + +###### `above(editor: Editor, options?): NodeEntry | undefined` + +Get the ancestor above a location in the document. + +Options: `{at?: Location, match?: NodeMatch, mode?: 'highest' | 'lowest', voids?: boolean}` + +###### `addMark(editor: Editor, key: string, value: any): void` + +Add a custom property to the leaf text nodes in the current selection. + +If the selection is currently collapsed, the marks will be added to the +`editor.marks` property instead, and applied when text is inserted next. + +###### `after(editor: Editor, at: Location, options?): Point | undefined` + +Get the point after a location. + +Options: `{distance?: number, unit?: 'offset' | 'character' | 'word' | 'line' | 'block', voids?: boolean}` + +###### `before(editor: Editor, at: Location, options?): Point | undefined` + +Get the point before a location. + +Options: `{distance?: number, unit?: 'offset' | 'character' | 'word' | 'line' | 'block', voids?: boolean}` + +###### `deleteBackward(editor: Editor, options?): void` + +Delete content in the editor backward from the current selection. + +Options: `{unit?: 'character' | 'word' | 'line' | 'block'}` + +###### `deleteForward(editor: Editor, options?): void` + +Delete content in the editor forward from the current selection. + +Options: `{unit?: 'character' | 'word' | 'line' | 'block'}` + +###### `deleteFragment(editor: Editor): void` + +Delete the content in the current selection. + +###### `edges(editor: Editor, at: Location): [Point, Point]` + +Get the start and end points of a location. + +###### `end(editor: Editor, at: Location): Point` + +Get the end point of a location. + +###### `first(editor: Editor, at: Location): NodeEntry` + +Get the first node at a location. + +###### `fragment(editor: Editor, at: Location): Descendant[]` + +Get the fragment at a location. + +###### `hasBlocks(editor: Editor, element: Element): boolean` + +Check if a node has block children. + +###### `hasInlines(editor: Editor, element: Element): boolean` + +Check if a node has inline and text children. + +###### `hasTexts(editor: Editor, element: Element): boolean` + +Check if a node has text children. + +###### `insertBreak(editor: Editor): void` + +Insert a block break at the current selection. + +###### `insertFragment(editor: Editor, fragment: Node[]): void` + +Insert a fragment at the current selection. + +If the selection is currently expanded, it will be deleted first. + +###### `insertNode(editor: Editor, node: Node): void` + +Insert a node at the current selection. + +If the selection is currently expanded, it will be deleted first. + +###### `insertText(editor: Editor, text: string): void` + +Insert text at the current selection. + +If the selection is currently expanded, it will be deleted first. + +###### `isBlock(editor: Editor, value: any): value is Element` + +Check if a value is a block `Element` object. + +###### `isEditor(value: any): value is Editor` + +Check if a value is an `Editor` object. + +###### `isEnd(editor: Editor, point: Point, at: Location): boolean` + +Check if a point is the end point of a location. + +###### `isEdge(editor: Editor, point: Point, at: Location): boolean` + +Check if a point is an edge of a location. + +###### `isEmpty(editor: Editor, element: Element): boolean` + +Check if an element is empty, accounting for void nodes. + +###### `isInline(editor: Editor, value: any): value is Element` + +Check if a value is an inline `Element` object. + +###### `isNormalizing(editor: Editor): boolean` + +Check if the editor is currently normalizing after each operation. + +###### `isStart(editor: Editor, point: Point, at: Location): boolean` + +Check if a point is the start point of a location. + +###### `isVoid(editor: Editor, value: any): value is Element` + +Check if a value is a void `Element` object. + +###### `last(editor: Editor, at: Location): NodeEntry` + +Get the last node at a location. + +###### `leaf(editor: Editor, at: Location, options?): NodeEntry` + +Get the leaf text node at a location. + +Options: `{depth?: number, edge?: 'start' | 'end'}` + +###### `levels(editor: Editor, options?): Generator` + +Iterate through all of the levels at a location. + +Options: `{at?: Location, match?: NodeMatch, reverse?: boolean, voids?: boolean}` + +###### `next(editor: Editor, options?): NodeEntry | undefined` + +Get the matching node in the branch of the document after a location. + +Options: `{at?: Location, match?: NodeMatch, mode?: 'all' | 'highest' | 'lowest', voids?: boolean}` + +###### `node(editor: Editor, at: Location, options?): NodeEntry` + +Get the node at a location. + +Options: `depth?: number, edge?: 'start' | 'end'` + +###### `nodes(editor: Editor, options?): Generator, void, undefined>` + +Iterate through all of the nodes in the Editor. + +Options: `{at?: Location | Span, match?: NodeMatch, mode?: 'all' | 'highest' | 'lowest', universal?: boolean, reverse?: boolean, voids?: boolean}` + +###### `normalize(editor: Editor, options?): void` + +Normalize any dirty objects in the editor. + +Options: `{force?: boolean}` + +###### `parent(editor: Editor, at: Location, options?): NodeEntry` + +Get the parent node of a location. + +Options: `{depth?: number, edge?: 'start' | 'end'}` + +###### `path(editor: Editor, at: Location, options?): Path` + +Get the path of a location. + +Options: `{depth?: number, edge?: 'start' | 'end'}` + +###### `pathRef(editor: Editor, path: Path, options?): PathRef` + +Create a mutable ref for a `Path` object, which will stay in sync as new +operations are applied to the editor. + +Options: `{affinity?: 'backward' | 'forward' | null}` + +###### `pathRefs(editor: Editor): Set` + +Get the set of currently tracked path refs of the editor. + +###### `point(editor: Editor, at: Location, options?): Point` + +Get the start or end point of a location. + +Options: `{edge?: 'start' | 'end'}` + +###### `pointRef(editor: Editor, point: Point, options?): PointRef` + +Create a mutable ref for a `Point` object, which will stay in sync as new +operations are applied to the editor. + +Options: `{affinity?: 'backward' | 'forward' | null}` + +###### `pointRefs(editor: Editor): Set` + +Get the set of currently tracked point refs of the editor. + +###### `positions(editor: Editor, options?): Generator` + +Iterate through all of the positions in the document where a `Point` can be +placed. + +By default it will move forward by individual offsets at a time, but you +can pass the `unit: 'character'` option to moved forward one character, word, +or line at at time. + +Note: By default void nodes are treated as a single point and iteration +will not happen inside their content unless you pass in true for the +voids option, then iteration will occur. + +Options: `{at?: Location, unit?: 'offset' | 'character' | 'word' | 'line' | 'block', reverse?: boolean, voids?: boolean}` + +###### `previous(editor: Editor, options?): NodeEntry | undefined` + +Get the matching node in the branch of the document before a location. + +Options: `{at?: Location, match?: NodeMatch, mode?: 'all' | 'highest' | 'lowest', voids?: boolean}` + +###### `range(editor: Editor, at: Location, to?: Location): Range` + +Get a range of a location. + +###### `rangeRef(editor: Editor, range: Range, options?): RangeRef` + +Create a mutable ref for a `Range` object, which will stay in sync as new +operations are applied to the editor. + +Options: `{affinity?: 'backward' | 'forward' | 'outward' | 'inward' | null}` + +###### `rangeRefs(editor: Editor): Set` + +Get the set of currently tracked range refs of the editor. + +###### `removeMark(editor: Editor, key: string): void` + +Remove a custom property from all of the leaf text nodes in the current +selection. + +If the selection is currently collapsed, the removal will be stored on +`editor.marks` and applied to the text inserted next. + +###### `start(editor: Editor, at: Location): Point` + +Get the start point of a location. + +###### `string(editor: Editor, at: Location, options?): string` + +Get the text string content of a location. + +Note: by default the text of void nodes is considered to be an empty +string, regardless of content, unless you pass in true for the voids option + +Options: : `{voids?: boolean}` + +###### `unhangRange(editor: Editor, range: Range, options?): Range` + +Convert a range into a non-hanging one. + +Options: `{voids?: boolean}` + +###### `void(editor: Editor, options?): NodeEntry | undefined` + +Match a void node in the current branch of the editor. + +Options: `{at?: Location, mode?: 'highest' | 'lowest', voids?: boolean}` + +###### `withoutNormalizing(editor: Editor, fn: () => void): void` + +Call a function, deferring normalization until after it completes. + +### Instance methods + +### Schema-specific methods to override + +###### `isInline(element: Element)` + +Check if a value is an inline `Element` object. + +###### `isVoid(element: Element)` + +Check if a value is a void `Element` object. + +###### `normalizeNode(entry: NodeEntry)` + +Normalize a Node according to the schema. + +###### `onChange()` + +Called when there is a change in the editor. + +### Core actions + +###### `addMark(key: string, value: any)` + +Add a custom property to the leaf text nodes in the current selection. If the selection is currently collapsed, the marks will be added to the `editor.marks` property instead, and applied when text is inserted next. + +###### `removeMark(key: string)` + +Remove a custom property from the leaf text nodes in the current selection. + +###### `deleteBackward(options?: {unit?: 'character' | 'word' | 'line' | 'block'})` + +Delete content in the editor backward from the current selection. + +###### `deleteForward(options?: {unit?: 'character' | 'word' | 'line' | 'block'})` + +Delete content in the editor forward from the current selection. + +###### `insertFragment(fragment: Node[])` + +Insert a fragment at the current selection. If the selection is currently expanded, delete it first. + +###### `deleteFragment()` + +Delete the content of the current selection. + +###### `insertBreak()` + +Insert a block break at the current selection. If the selection is currently expanded, delete it first. + +###### `insertNode(node: Node)` + +Insert a node at the current selection. If the selection is currently expanded, delete it first. + +###### `insertText(text: string)` + +Insert text at the current selection. If the selection is currently expanded, delete it first. + +###### `apply(operation: Operation)` + +Apply an operation in the editor. diff --git a/docs/api/element.md b/docs/api/element.md new file mode 100644 index 000000000..df6848a57 --- /dev/null +++ b/docs/api/element.md @@ -0,0 +1,24 @@ +# Element + +`Element` objects are a type of node in a Slate document that contain other `Element` nodes or `Text` nodes. They can be either "blocks" or "inlines" depending on the Slate editor's configuration. + +```typescript +interface Element { + children: Node[] + [key: string]: unknown +} +``` + +## Static methods + +###### `Element.isElement(value: any): value is Element` + +Check if a `value` implements the `Element` interface. + +###### `Element.isElementList(value: any): value is Element[]` + +Check if a `value` is an array of `Element` objects. + +###### `Element.matches(element: Element, props: Partial): boolean` + +Check if an element matches a set of `props`. Note: This checks custom properties, but it does not ensure that any children are equivalent. diff --git a/docs/api/locations.md b/docs/api/locations.md index 9277f2d12..2c2cf08fd 100644 --- a/docs/api/locations.md +++ b/docs/api/locations.md @@ -6,238 +6,12 @@ The `Location` interface is a union of the ways to refer to a specific location type Location = Path | Point | Range ``` -## Location +- [Path](./api/path.md) +- [Point](./api/point.md) +- [Range](./api/range.md) -### Static methods +## Static methods ###### `Location.isLocation(value: any): value is Location` Check if a value implements the `Location` interface. - -## Path - -`Path` arrays are a list of indexes that describe a node's exact position in a Slate node tree. Although they are usually relative to the root `Editor` object, they can be relative to any `Node` object. - -```typescript -type Path = number[] -``` - -### Static methods - -###### `ancestors(path: Path, options: { reverse?: boolean } = {}): Path[]` - -Get a list of ancestor paths for a given path. - -The paths are sorted from deepest to shallowest ancestor. However, if the -`reverse: true` option is passed, they are reversed. - -###### `common(path: Path, another: Path): Path` - -Get the common ancestor path of two paths. - -###### `compare(path: Path, another: Path): -1 | 0 | 1` - -Compare a path to another, returning an integer indicating whether the path -was before, at, or after the other. - -Note: Two paths of unequal length can still receive a `0` result if one is -directly above or below the other. If you want exact matching, use -[[Path.equals]] instead. - -###### `endsAfter(path: Path, another: Path): boolean` - -Check if a path ends after one of the indexes in another. - -###### `endsAt(path: Path, another: Path): boolean` - -Check if a path ends at one of the indexes in another. - -###### `endsBefore(path: Path, another: Path): boolean` - -Check if a path ends before one of the indexes in another. - -###### `equals(path: Path, another: Path): boolean` - -Check if a path is exactly equal to another. - -###### `hasPrevious(path: Path): boolean` - -Check if the path of previous sibling node exists - -###### `isAfter(path: Path, another: Path): boolean` - -Check if a path is after another. - -###### `isAncestor(path: Path, another: Path): boolean` - -Check if a path is an ancestor of another. - -###### `isBefore(path: Path, another: Path): boolean` - -Check if a path is before another. - -###### `isChild(path: Path, another: Path): boolean` - -Check if a path is a child of another. - -###### `isCommon(path: Path, another: Path): boolean` - -Check if a path is equal to or an ancestor of another. - -###### `isDescendant(path: Path, another: Path): boolean` - -Check if a path is a descendant of another. - -###### `isParent(path: Path, another: Path): boolean` - -Check if a path is the parent of another. - -###### `isPath(value: any): value is Path` - -Check is a value implements the `Path` interface. - -###### `isSibling(path: Path, another: Path): boolean` - -Check if a path is a sibling of another. - -###### `levels(path: Path, options?): Path[]` - -Get a list of paths at every level down to a path. Note: this is the same -as `Path.ancestors`, but including the path itself. - -The paths are sorted from shallowest to deepest. However, if the `reverse: -true` option is passed, they are reversed. - -Options: `{reverse?: boolean}` - -###### `next(path: Path): Path` - -Given a path, get the path to the next sibling node. - -###### `parent(path: Path): Path` - -Given a path, return a new path referring to the parent node above it. - -###### `previous(path: Path): Path` - -Given a path, get the path to the previous sibling node. - -###### `relative(path: Path, ancestor: Path): Path` - -Get a path relative to an ancestor. - -###### `transform(path: Path, operation: Operation, options?): Path | null` - -Transform a path by an operation. - -Options: `{ affinity?: 'forward' | 'backward' | null }` - -## Point - -`Point` objects refer to a specific location in a text node in a Slate document. Its `path` refers to the location of the node in the tree, and its offset refers to distance into the node's string of text. Points may only refer to `Text` nodes. - -```typescript -interface Point { - path: Path - offset: number - [key: string]: unknown -} -``` - -### Static methods - -###### `Point.compare(point: Point, another: Point): -1 | 0 | 1` - -Compare a `point` to `another`, returning an integer indicating whether the point was before, at or after the other. - -###### `Point.isAfter(point: Point, another: Point): boolean` - -Check if a `point` is after `another`. - -###### `Point.isBefore(point: Point, another: Point): boolean` - -Check if a `point` is before `another`. - -###### `Point.equals(point: Point, another: Point): boolean` - -Check if a `point` is exactly equal to `another`. - -###### `Point.isPoint(value: any): value is Point` - -Check if a `value` implements the `Point` interface. - -###### `Point.transform(point: Point, op: Operation, options?): Point | null` - -Transform a `point` by an `op`. - -Options: `{affinity?: 'forward' | 'backward' | null}` - -## Range - -`Range` objects are a set of points that refer to a specific span of a Slate document. They can define a span inside a single node or they can span across multiple nodes. The editor's `selection` is stored as a range. - -```typescript -interface Range { - anchor: Point - focus: Point - [key: string]: unknown -} -``` - -### Static methods - -###### `Range.edges(range: Range, options?): [Point, Point]` - -Get the start and end points of a `range`, in the order in which they appear in the document. - -Options: `{reverse?: boolean}` - -###### `Range.end(range: Range): Point` - -Get the end point of a `range`. - -###### `Range.equals(range: Range, another: Range): boolean` - -Check if a `range` is exactly equal to `another`. - -###### `Range.includes(range: Range, target: Path | Point | Range): boolean` - -Check if a `range` includes a path, a point, or part of another range. - -###### `Range.intersection(range: Range, another: Range): Range | null` - -Get the intersection of one `range` with `another`. - -###### `Range.isBackward(range: Range): boolean` - -Check if a `range` is backward, meaning that its anchor point appears _after_ its focus point in the document. - -###### `Range.isCollapsed(range: Range): boolean` - -Check if a `range` is collapsed, meaning that both its anchor and focus points refer to the exact same position in the document. - -###### `Range.isExpanded(range: Range): boolean` - -Check if a `range` is expanded. This is the opposite of `Range.isCollapsed` and is provided for legibility. - -###### `Range.isForward(range: Range): boolean` - -Check if a `range` is forward. This is the opposite of `Range.isBackward` and is provided for legibility. - -###### `Range.isRange(value: any): value is Range` - -Check if a `value` implements the `Range` interface. - -###### `Range.points(range: Range): Generator` - -Iterate through all the point entries in a `range`. - -###### `Range.start(range: Range): Point` - -Get the start point of a `range` - -###### `Range.transform(range: Range, op: Operation, options): Range | null` - -Transform a `range` by an `op`. - -Options: `{affinity: 'forward' | 'backward' | 'outward' | 'inward' | null}` diff --git a/docs/api/nodes.md b/docs/api/nodes.md index e357bb335..d14c57895 100644 --- a/docs/api/nodes.md +++ b/docs/api/nodes.md @@ -1,4 +1,4 @@ -# Nodes +# Node The `Node` union type represents all of the different types of nodes that occur in a Slate document tree. @@ -9,9 +9,11 @@ type Descendant = Element | Text type Ancestor = Editor | Element ``` -## Node +- [Editor](./api/editor.md) +- [Element](./api/element.md) +- [Text](./api/text.md) -### Static methods +## Static methods ###### `Node.ancestor(root: Node, path: Path): Ancestor` @@ -114,435 +116,3 @@ Get the concatenated text string of a node's content. Note that this will not in Return a generator of all leaf text nodes in a root node. Options: `{from?: Path, to?: Path, reverse?: boolean, pass?: (node: NodeEntry => boolean)}` - -## Editor - -The `Editor` object stores all the state of a slate editor. It can be extended by plugins to add helpers and implement new behaviors. - -```typescript -interface Editor { - children: Node[] - selection: Range | null - operations: Operation[] - marks: Record | null - [key: string]: unknown - - // Schema-specific node behaviors. - isInline: (element: Element) => boolean - isVoid: (element: Element) => boolean - normalizeNode: (entry: NodeEntry) => void - onChange: () => void - - // Overrideable core actions. - addMark: (key: string, value: any) => void - apply: (operation: Operation) => void - deleteBackward: (unit: 'character' | 'word' | 'line' | 'block') => void - deleteForward: (unit: 'character' | 'word' | 'line' | 'block') => void - deleteFragment: () => void - insertBreak: () => void - insertFragment: (fragment: Node[]) => void - insertNode: (node: Node) => void - insertText: (text: string) => void - removeMark: (key: string) => void -} -``` - -### Static methods - -###### `above(editor: Editor, options?): NodeEntry | undefined` - -Get the ancestor above a location in the document. - -Options: `{at?: Location, match?: NodeMatch, mode?: 'highest' | 'lowest', voids?: boolean}` - -###### `addMark(editor: Editor, key: string, value: any): void` - -Add a custom property to the leaf text nodes in the current selection. - -If the selection is currently collapsed, the marks will be added to the -`editor.marks` property instead, and applied when text is inserted next. - -###### `after(editor: Editor, at: Location, options?): Point | undefined` - -Get the point after a location. - -Options: `{distance?: number, unit?: 'offset' | 'character' | 'word' | 'line' | 'block', voids?: boolean}` - -###### `before(editor: Editor, at: Location, options?): Point | undefined` - -Get the point before a location. - -Options: `{distance?: number, unit?: 'offset' | 'character' | 'word' | 'line' | 'block', voids?: boolean}` - -###### `deleteBackward(editor: Editor, options?): void` - -Delete content in the editor backward from the current selection. - -Options: `{unit?: 'character' | 'word' | 'line' | 'block'}` - -###### `deleteForward(editor: Editor, options?): void` - -Delete content in the editor forward from the current selection. - -Options: `{unit?: 'character' | 'word' | 'line' | 'block'}` - -###### `deleteFragment(editor: Editor): void` - -Delete the content in the current selection. - -###### `edges(editor: Editor, at: Location): [Point, Point]` - -Get the start and end points of a location. - -###### `end(editor: Editor, at: Location): Point` - -Get the end point of a location. - -###### `first(editor: Editor, at: Location): NodeEntry` - -Get the first node at a location. - -###### `fragment(editor: Editor, at: Location): Descendant[]` - -Get the fragment at a location. - -###### `hasBlocks(editor: Editor, element: Element): boolean` - -Check if a node has block children. - -###### `hasInlines(editor: Editor, element: Element): boolean` - -Check if a node has inline and text children. - -###### `hasTexts(editor: Editor, element: Element): boolean` - -Check if a node has text children. - -###### `insertBreak(editor: Editor): void` - -Insert a block break at the current selection. - -###### `insertFragment(editor: Editor, fragment: Node[]): void` - -Insert a fragment at the current selection. - -If the selection is currently expanded, it will be deleted first. - -###### `insertNode(editor: Editor, node: Node): void` - -Insert a node at the current selection. - -If the selection is currently expanded, it will be deleted first. - -###### `insertText(editor: Editor, text: string): void` - -Insert text at the current selection. - -If the selection is currently expanded, it will be deleted first. - -###### `isBlock(editor: Editor, value: any): value is Element` - -Check if a value is a block `Element` object. - -###### `isEditor(value: any): value is Editor` - -Check if a value is an `Editor` object. - -###### `isEnd(editor: Editor, point: Point, at: Location): boolean` - -Check if a point is the end point of a location. - -###### `isEdge(editor: Editor, point: Point, at: Location): boolean` - -Check if a point is an edge of a location. - -###### `isEmpty(editor: Editor, element: Element): boolean` - -Check if an element is empty, accounting for void nodes. - -###### `isInline(editor: Editor, value: any): value is Element` - -Check if a value is an inline `Element` object. - -###### `isNormalizing(editor: Editor): boolean` - -Check if the editor is currently normalizing after each operation. - -###### `isStart(editor: Editor, point: Point, at: Location): boolean` - -Check if a point is the start point of a location. - -###### `isVoid(editor: Editor, value: any): value is Element` - -Check if a value is a void `Element` object. - -###### `last(editor: Editor, at: Location): NodeEntry` - -Get the last node at a location. - -###### `leaf(editor: Editor, at: Location, options?): NodeEntry` - -Get the leaf text node at a location. - -Options: `{depth?: number, edge?: 'start' | 'end'}` - -###### `levels(editor: Editor, options?): Generator` - -Iterate through all of the levels at a location. - -Options: `{at?: Location, match?: NodeMatch, reverse?: boolean, voids?: boolean}` - -###### `next(editor: Editor, options?): NodeEntry | undefined` - -Get the matching node in the branch of the document after a location. - -Options: `{at?: Location, match?: NodeMatch, mode?: 'all' | 'highest' | 'lowest', voids?: boolean}` - -###### `node(editor: Editor, at: Location, options?): NodeEntry` - -Get the node at a location. - -Options: `depth?: number, edge?: 'start' | 'end'` - -###### `nodes(editor: Editor, options?): Generator, void, undefined>` - -Iterate through all of the nodes in the Editor. - -Options: `{at?: Location | Span, match?: NodeMatch, mode?: 'all' | 'highest' | 'lowest', universal?: boolean, reverse?: boolean, voids?: boolean}` - -###### `normalize(editor: Editor, options?): void` - -Normalize any dirty objects in the editor. - -Options: `{force?: boolean}` - -###### `parent(editor: Editor, at: Location, options?): NodeEntry` - -Get the parent node of a location. - -Options: `{depth?: number, edge?: 'start' | 'end'}` - -###### `path(editor: Editor, at: Location, options?): Path` - -Get the path of a location. - -Options: `{depth?: number, edge?: 'start' | 'end'}` - -###### `pathRef(editor: Editor, path: Path, options?): PathRef` - -Create a mutable ref for a `Path` object, which will stay in sync as new -operations are applied to the editor. - -Options: `{affinity?: 'backward' | 'forward' | null}` - -###### `pathRefs(editor: Editor): Set` - -Get the set of currently tracked path refs of the editor. - -###### `point(editor: Editor, at: Location, options?): Point` - -Get the start or end point of a location. - -Options: `{edge?: 'start' | 'end'}` - -###### `pointRef(editor: Editor, point: Point, options?): PointRef` - -Create a mutable ref for a `Point` object, which will stay in sync as new -operations are applied to the editor. - -Options: `{affinity?: 'backward' | 'forward' | null}` - -###### `pointRefs(editor: Editor): Set` - -Get the set of currently tracked point refs of the editor. - -###### `positions(editor: Editor, options?): Generator` - -Iterate through all of the positions in the document where a `Point` can be -placed. - -By default it will move forward by individual offsets at a time, but you -can pass the `unit: 'character'` option to moved forward one character, word, -or line at at time. - -Note: By default void nodes are treated as a single point and iteration -will not happen inside their content unless you pass in true for the -voids option, then iteration will occur. - -Options: `{at?: Location, unit?: 'offset' | 'character' | 'word' | 'line' | 'block', reverse?: boolean, voids?: boolean}` - -###### `previous(editor: Editor, options?): NodeEntry | undefined` - -Get the matching node in the branch of the document before a location. - -Options: `{at?: Location, match?: NodeMatch, mode?: 'all' | 'highest' | 'lowest', voids?: boolean}` - -###### `range(editor: Editor, at: Location, to?: Location): Range` - -Get a range of a location. - -###### `rangeRef(editor: Editor, range: Range, options?): RangeRef` - -Create a mutable ref for a `Range` object, which will stay in sync as new -operations are applied to the editor. - -Options: `{affinity?: 'backward' | 'forward' | 'outward' | 'inward' | null}` - -###### `rangeRefs(editor: Editor): Set` - -Get the set of currently tracked range refs of the editor. - -###### `removeMark(editor: Editor, key: string): void` - -Remove a custom property from all of the leaf text nodes in the current -selection. - -If the selection is currently collapsed, the removal will be stored on -`editor.marks` and applied to the text inserted next. - -###### `start(editor: Editor, at: Location): Point` - -Get the start point of a location. - -###### `string(editor: Editor, at: Location, options?): string` - -Get the text string content of a location. - -Note: by default the text of void nodes is considered to be an empty -string, regardless of content, unless you pass in true for the voids option - -Options: : `{voids?: boolean}` - -###### `unhangRange(editor: Editor, range: Range, options?): Range` - -Convert a range into a non-hanging one. - -Options: `{voids?: boolean}` - -###### `void(editor: Editor, options?): NodeEntry | undefined` - -Match a void node in the current branch of the editor. - -Options: `{at?: Location, mode?: 'highest' | 'lowest', voids?: boolean}` - -###### `withoutNormalizing(editor: Editor, fn: () => void): void` - -Call a function, deferring normalization until after it completes. - -### Instance methods - -#### Schema-specific methods to override - -###### `isInline(element: Element)` - -Check if a value is an inline `Element` object. - -###### `isVoid(element: Element)` - -Check if a value is a void `Element` object. - -###### `normalizeNode(entry: NodeEntry)` - -Normalize a Node according to the schema. - -###### `onChange()` - -Called when there is a change in the editor. - -#### Core actions - -###### `addMark(key: string, value: any)` - -Add a custom property to the leaf text nodes in the current selection. If the selection is currently collapsed, the marks will be added to the `editor.marks` property instead, and applied when text is inserted next. - -###### `removeMark(key: string)` - -Remove a custom property from the leaf text nodes in the current selection. - -###### `deleteBackward(options?: {unit?: 'character' | 'word' | 'line' | 'block'})` - -Delete content in the editor backward from the current selection. - -###### `deleteForward(options?: {unit?: 'character' | 'word' | 'line' | 'block'})` - -Delete content in the editor forward from the current selection. - -###### `insertFragment(fragment: Node[])` - -Insert a fragment at the current selection. If the selection is currently expanded, delete it first. - -###### `deleteFragment()` - -Delete the content of the current selection. - -###### `insertBreak()` - -Insert a block break at the current selection. If the selection is currently expanded, delete it first. - -###### `insertNode(node: Node)` - -Insert a node at the current selection. If the selection is currently expanded, delete it first. - -###### `insertText(text: string)` - -Insert text at the current selection. If the selection is currently expanded, delete it first. - -###### `apply(operation: Operation)` - -Apply an operation in the editor. - -## Element - -`Element` objects are a type of node in a Slate document that contain other `Element` nodes or `Text` nodes. They can be either "blocks" or "inlines" depending on the Slate editor's configuration. - -```typescript -interface Element { - children: Node[] - [key: string]: unknown -} -``` - -### Static methods - -###### `Element.isElement(value: any): value is Element` - -Check if a `value` implements the `Element` interface. - -###### `Element.isElementList(value: any): value is Element[]` - -Check if a `value` is an array of `Element` objects. - -###### `Element.matches(element: Element, props: Partial): boolean` - -Check if an element matches a set of `props`. Note: This checks custom properties, but it does not ensure that any children are equivalent. - -## Text - -`Text` objects represent the nodes that contain the actual text content of a Slate document along with any formatting properties. They are always leaf nodes in the document tree as they cannot contain any children. - -```typescript -interface Text { - text: string - [key: string]: unknown -} -``` - -### Static methods - -###### `Text.equals(text: Text, another: Text, options?): boolean` - -Check if two text nodes are equal. - -Options: `{loose?: boolean}` - -###### `Text.isText(value: any): value is Text` - -Check if a `value` implements the `Text` interface. - -###### `Text.matches(text: Text, props: Partial): boolean` - -Check if a `text` matches a set of `props`. - -###### `Text.decorations(node: Text, decorations: Range[]): Text[]` - -Get the leaves for a text node, given `decorations`. diff --git a/docs/api/path.md b/docs/api/path.md new file mode 100644 index 000000000..7c46b98d7 --- /dev/null +++ b/docs/api/path.md @@ -0,0 +1,116 @@ +# Path + +`Path` arrays are a list of indexes that describe a node's exact position in a Slate node tree. Although they are usually relative to the root `Editor` object, they can be relative to any `Node` object. + +```typescript +type Path = number[] +``` + +## Static methods + +###### `ancestors(path: Path, options: { reverse?: boolean } = {}): Path[]` + +Get a list of ancestor paths for a given path. + +The paths are sorted from deepest to shallowest ancestor. However, if the +`reverse: true` option is passed, they are reversed. + +###### `common(path: Path, another: Path): Path` + +Get the common ancestor path of two paths. + +###### `compare(path: Path, another: Path): -1 | 0 | 1` + +Compare a path to another, returning an integer indicating whether the path +was before, at, or after the other. + +Note: Two paths of unequal length can still receive a `0` result if one is +directly above or below the other. If you want exact matching, use +[[Path.equals]] instead. + +###### `endsAfter(path: Path, another: Path): boolean` + +Check if a path ends after one of the indexes in another. + +###### `endsAt(path: Path, another: Path): boolean` + +Check if a path ends at one of the indexes in another. + +###### `endsBefore(path: Path, another: Path): boolean` + +Check if a path ends before one of the indexes in another. + +###### `equals(path: Path, another: Path): boolean` + +Check if a path is exactly equal to another. + +###### `hasPrevious(path: Path): boolean` + +Check if the path of previous sibling node exists + +###### `isAfter(path: Path, another: Path): boolean` + +Check if a path is after another. + +###### `isAncestor(path: Path, another: Path): boolean` + +Check if a path is an ancestor of another. + +###### `isBefore(path: Path, another: Path): boolean` + +Check if a path is before another. + +###### `isChild(path: Path, another: Path): boolean` + +Check if a path is a child of another. + +###### `isCommon(path: Path, another: Path): boolean` + +Check if a path is equal to or an ancestor of another. + +###### `isDescendant(path: Path, another: Path): boolean` + +Check if a path is a descendant of another. + +###### `isParent(path: Path, another: Path): boolean` + +Check if a path is the parent of another. + +###### `isPath(value: any): value is Path` + +Check is a value implements the `Path` interface. + +###### `isSibling(path: Path, another: Path): boolean` + +Check if a path is a sibling of another. + +###### `levels(path: Path, options?): Path[]` + +Get a list of paths at every level down to a path. Note: this is the same +as `Path.ancestors`, but including the path itself. + +The paths are sorted from shallowest to deepest. However, if the `reverse: true` option is passed, they are reversed. + +Options: `{reverse?: boolean}` + +###### `next(path: Path): Path` + +Given a path, get the path to the next sibling node. + +###### `parent(path: Path): Path` + +Given a path, return a new path referring to the parent node above it. + +###### `previous(path: Path): Path` + +Given a path, get the path to the previous sibling node. + +###### `relative(path: Path, ancestor: Path): Path` + +Get a path relative to an ancestor. + +###### `transform(path: Path, operation: Operation, options?): Path | null` + +Transform a path by an operation. + +Options: `{ affinity?: 'forward' | 'backward' | null }` diff --git a/docs/api/point-ref.md b/docs/api/point-ref.md new file mode 100644 index 000000000..2c0245bb9 --- /dev/null +++ b/docs/api/point-ref.md @@ -0,0 +1,17 @@ +# PointRef + +`PointRef` objects keep a specific point in a document synced over time as new operations are applied to the editor. You can access their property `current` at any time for the up-to-date `Point` value. + +```typescript +interface PointRef { + current: Point | null + affinity: 'forward' | 'backward' | null + unref(): Point | null +} +``` + +## Static methods + +###### `PointRef.transform(ref: PointRef, op: Operation)` + +Transform the point refs current value by an `op`. diff --git a/docs/api/point.md b/docs/api/point.md new file mode 100644 index 000000000..06d38eb1e --- /dev/null +++ b/docs/api/point.md @@ -0,0 +1,39 @@ +# Point + +`Point` objects refer to a specific location in a text node in a Slate document. Its `path` refers to the location of the node in the tree, and its offset refers to distance into the node's string of text. Points may only refer to `Text` nodes. + +```typescript +interface Point { + path: Path + offset: number + [key: string]: unknown +} +``` + +## Static methods + +###### `Point.compare(point: Point, another: Point): -1 | 0 | 1` + +Compare a `point` to `another`, returning an integer indicating whether the point was before, at or after the other. + +###### `Point.isAfter(point: Point, another: Point): boolean` + +Check if a `point` is after `another`. + +###### `Point.isBefore(point: Point, another: Point): boolean` + +Check if a `point` is before `another`. + +###### `Point.equals(point: Point, another: Point): boolean` + +Check if a `point` is exactly equal to `another`. + +###### `Point.isPoint(value: any): value is Point` + +Check if a `value` implements the `Point` interface. + +###### `Point.transform(point: Point, op: Operation, options?): Point | null` + +Transform a `point` by an `op`. + +Options: `{affinity?: 'forward' | 'backward' | null}` diff --git a/docs/api/range-ref.md b/docs/api/range-ref.md new file mode 100644 index 000000000..5a8a9c1c6 --- /dev/null +++ b/docs/api/range-ref.md @@ -0,0 +1,17 @@ +# RangeRef + +`RangeRef` objects keep a specific range in a document synced over time as new operations are applied to the editor. You can access their property `current` at any time for the up-to-date `Range` value. + +```typescript +interface RangeRef { + current: Range | null + affinity: 'forward' | 'backward' | 'outward' | 'inward' | null + unref(): Range | null +} +``` + +## Static methods + +###### `RangeRef.transform(ref: RangeRef, op: Operation)` + +Transform the range refs current value by an `op`. diff --git a/docs/api/range.md b/docs/api/range.md new file mode 100644 index 000000000..bc88fa428 --- /dev/null +++ b/docs/api/range.md @@ -0,0 +1,69 @@ +# Range + +`Range` objects are a set of points that refer to a specific span of a Slate document. They can define a span inside a single node or they can span across multiple nodes. The editor's `selection` is stored as a range. + +```typescript +interface Range { + anchor: Point + focus: Point + [key: string]: unknown +} +``` + +## Static methods + +###### `Range.edges(range: Range, options?): [Point, Point]` + +Get the start and end points of a `range`, in the order in which they appear in the document. + +Options: `{reverse?: boolean}` + +###### `Range.end(range: Range): Point` + +Get the end point of a `range`. + +###### `Range.equals(range: Range, another: Range): boolean` + +Check if a `range` is exactly equal to `another`. + +###### `Range.includes(range: Range, target: Path | Point | Range): boolean` + +Check if a `range` includes a path, a point, or part of another range. + +###### `Range.intersection(range: Range, another: Range): Range | null` + +Get the intersection of one `range` with `another`. + +###### `Range.isBackward(range: Range): boolean` + +Check if a `range` is backward, meaning that its anchor point appears _after_ its focus point in the document. + +###### `Range.isCollapsed(range: Range): boolean` + +Check if a `range` is collapsed, meaning that both its anchor and focus points refer to the exact same position in the document. + +###### `Range.isExpanded(range: Range): boolean` + +Check if a `range` is expanded. This is the opposite of `Range.isCollapsed` and is provided for legibility. + +###### `Range.isForward(range: Range): boolean` + +Check if a `range` is forward. This is the opposite of `Range.isBackward` and is provided for legibility. + +###### `Range.isRange(value: any): value is Range` + +Check if a `value` implements the `Range` interface. + +###### `Range.points(range: Range): Generator` + +Iterate through all the point entries in a `range`. + +###### `Range.start(range: Range): Point` + +Get the start point of a `range` + +###### `Range.transform(range: Range, op: Operation, options): Range | null` + +Transform a `range` by an `op`. + +Options: `{affinity: 'forward' | 'backward' | 'outward' | 'inward' | null}` diff --git a/docs/api/refs.md b/docs/api/refs.md index 1f9332d46..00c99975e 100644 --- a/docs/api/refs.md +++ b/docs/api/refs.md @@ -1,39 +1,6 @@ # Ref -`Ref` objects store up-to-date references to a `Point` or `Range` object in the document. +`Ref` objects store up-to-date references to a `Point` or `Range` object in the document. They are named `PointRef` and `RangRef`. -## PointRef - -`PointRef` objects keep a specific point in a document synced over time as new operations are applied to the editor. You can access their property `current` at any time for the up-to-date `Point` value. - -```typescript -interface PointRef { - current: Point | null - affinity: 'forward' | 'backward' | null - unref(): Point | null -} -``` - -### Static methods - -###### `PointRef.transform(ref: PointRef, op: Operation)` - -Transform the point refs current value by an `op`. - -## RangeRef - -`RangeRef` objects keep a specific range in a document synced over time as new operations are applied to the editor. You can access their property `current` at any time for the up-to-date `Range` value. - -```typescript -interface RangeRef { - current: Range | null - affinity: 'forward' | 'backward' | 'outward' | 'inward' | null - unref(): Range | null -} -``` - -### Static methods - -###### `RangeRef.transform(ref: RangeRef, op: Operation)` - -Transform the range refs current value by an `op`. +- [PointRef](./api/point-ref.md) +- [RangeRef](./api/range-ref.md) \ No newline at end of file diff --git a/docs/api/text.md b/docs/api/text.md new file mode 100644 index 000000000..4767e15e3 --- /dev/null +++ b/docs/api/text.md @@ -0,0 +1,30 @@ +# Text + +`Text` objects represent the nodes that contain the actual text content of a Slate document along with any formatting properties. They are always leaf nodes in the document tree as they cannot contain any children. + +```typescript +interface Text { + text: string + [key: string]: unknown +} +``` + +## Static methods + +###### `Text.equals(text: Text, another: Text, options?): boolean` + +Check if two text nodes are equal. + +Options: `{loose?: boolean}` + +###### `Text.isText(value: any): value is Text` + +Check if a `value` implements the `Text` interface. + +###### `Text.matches(text: Text, props: Partial): boolean` + +Check if a `text` matches a set of `props`. + +###### `Text.decorations(node: Text, decorations: Range[]): Text[]` + +Get the leaves for a text node, given `decorations`.