From e9135410a54c9fd5572e1b83b8b720aa64d59242 Mon Sep 17 00:00:00 2001 From: zbeyens Date: Mon, 13 Jan 2025 15:17:03 +0100 Subject: [PATCH] docs --- BREAKING_CHANGES.md | 2 +- .../docs/en/api/slate/editor-transforms.mdx | 230 +++++++++--------- apps/www/content/docs/en/api/slate/path.mdx | 114 ++++----- 3 files changed, 172 insertions(+), 174 deletions(-) diff --git a/BREAKING_CHANGES.md b/BREAKING_CHANGES.md index 8b99bd55b..9120762d8 100644 --- a/BREAKING_CHANGES.md +++ b/BREAKING_CHANGES.md @@ -414,7 +414,7 @@ For older changelogs, see https://github.com/udecode/plate/blob/main/docs - `insertFragment` -> `editor.tf.insertFragment` - `insertNode` -> `editor.tf.insertNode` - `insertNodes` -> `editor.tf.insertNodes` - - `insertText` -> `editor.tf.insertText` + - `insertText` -> `editor.tf.insertText({ at })` or `editor.tf.insertText({ marks: false })` without `at` - `isAncestorEmpty` -> `editor.api.isEmpty` - `isBlock` -> `editor.api.isBlock` - `isBlockAboveEmpty` -> `editor.api.isEmpty(editor.selection, { block: true })` diff --git a/apps/www/content/docs/en/api/slate/editor-transforms.mdx b/apps/www/content/docs/en/api/slate/editor-transforms.mdx index cd7ec965a..b8e193d22 100644 --- a/apps/www/content/docs/en/api/slate/editor-transforms.mdx +++ b/apps/www/content/docs/en/api/slate/editor-transforms.mdx @@ -281,10 +281,10 @@ Wrap nodes at the specified location in an element container. Add a custom property to the leaf text nodes in the current selection. -+ ```ts -+ // If the selection is currently collapsed, the marks will be added to the -+ // `editor.marks` property instead, and applied when text is inserted next. -+ ``` +```ts +// If the selection is currently collapsed, the marks will be added to the +// `editor.marks` property instead, and applied when text is inserted next. +``` @@ -303,13 +303,11 @@ Add a custom property to the leaf text nodes in the current selection. Add multiple marks to the leaf text nodes in the current selection. -+ ```ts -+ // If marks with the same keys exist, they will be removed first. -+ // Examples: -+ // editor.tf.addMarks({ bold: true, italic: true }) -+ // editor.tf.addMarks({ bold: subscript }, { remove: 'superscript' }) -+ // editor.tf.addMarks({ bold: true }, { remove: ['italic', 'underline'] }) -+ ``` +```ts +editor.tf.addMarks({ bold: true, italic: true }) +editor.tf.addMarks({ bold: subscript }, { remove: 'superscript' }) +editor.tf.addMarks({ bold: true }, { remove: ['italic', 'underline'] }) +``` @@ -410,9 +408,9 @@ Duplicate nodes at a location. Insert a block break at the current selection. -+ ```ts -+ // If the selection is currently expanded, it will be deleted first. -+ ``` +```ts +// If the selection is currently expanded, it will be deleted first. +``` Returns `void` @@ -422,9 +420,9 @@ Insert a block break at the current selection. Insert a soft break at the current selection. -+ ```ts -+ // If the selection is currently expanded, it will be deleted first. -+ ``` +```ts +// If the selection is currently expanded, it will be deleted first. +``` Returns `void` @@ -455,9 +453,9 @@ Normalize any dirty objects in the editor. Redo to the next saved state. -+ -+ Returns `void` -+ + + Returns `void` + ### `collapse` @@ -541,25 +539,25 @@ Set new properties on one of the selection's points. Blur the editor. -+ -+ Returns `void` -+ + + Returns `void` + ### `deselect` Unset the selection. -+ -+ Returns `void` -+ + + Returns `void` + ### `withoutSaving` Apply a series of changes inside a synchronous function, without saving any of their operations into the history. -+ ```ts -+ // Operations inside this function will not be saved to history -+ ``` +```ts +// Operations inside this function will not be saved to history +``` @@ -567,9 +565,9 @@ Apply a series of changes inside a synchronous function, without saving any of t -+ -+ Returns `void` -+ + + Returns `void` + ### `withoutMerging` @@ -702,10 +700,10 @@ The `HistoryEditor` interface extends the base `Editor` interface to handle hist Remove a custom property from all of the leaf text nodes within non-void nodes or void nodes that `editor.markableVoid()` allows in the current selection. -+ ```ts -+ // If the selection is currently collapsed, the removal will be stored on -+ // `editor.marks` and applied to the text inserted next. -+ ``` +```ts +// If the selection is currently collapsed, the removal will be stored on +// `editor.marks` and applied to the text inserted next. +``` @@ -721,13 +719,13 @@ Remove a custom property from all of the leaf text nodes within non-void nodes o Remove marks from text nodes. -+ ```ts -+ // Examples: -+ // editor.tf.removeMarks() // Remove all marks from editor.marks -+ // editor.tf.removeMarks('bold') // Remove bold mark at selection -+ // editor.tf.removeMarks(['bold', 'italic']) // Remove multiple marks at selection -+ // editor.tf.removeMarks('bold', { at: range }) // Remove bold in range -+ ``` +```ts +// Examples: +// editor.tf.removeMarks() // Remove all marks from editor.marks +// editor.tf.removeMarks('bold') // Remove bold mark at selection +// editor.tf.removeMarks(['bold', 'italic']) // Remove multiple marks at selection +// editor.tf.removeMarks('bold', { at: range }) // Remove bold in range +``` @@ -822,11 +820,11 @@ Split nodes at the specified location. Toggle a mark on the leaf text nodes in the current selection. -+ ```ts -+ // Examples: -+ // editor.tf.toggleMark('bold') // Toggle bold mark -+ // editor.tf.toggleMark('subscript', { remove: 'superscript' }) // Add subscript, remove superscript -+ ``` +```ts +// Examples: +// editor.tf.toggleMark('bold') // Toggle bold mark +// editor.tf.toggleMark('subscript', { remove: 'superscript' }) // Add subscript, remove superscript +``` @@ -885,11 +883,11 @@ Delete content in the editor. Insert a string of text at the specified location or current selection. -+ ```ts -+ // If no location is specified, text will be inserted at: -+ // 1. Current selection if it exists -+ // 2. End of document if no selection exists -+ ``` +```ts +// If no location is specified, text will be inserted at: +// 1. Current selection if it exists +// 2. End of document if no selection exists +``` @@ -915,12 +913,12 @@ Insert a string of text at the specified location or current selection. Set the selection to a new value. When a selection already exists, this method will update the existing value. -+ ```ts -+ // Examples: -+ // editor.tf.select(at) // Select at location -+ // editor.tf.select(at, { edge: 'end' }) // Select end of block above -+ // editor.tf.select(at, { edge: 'start' }) // Select start of block above -+ ``` +```ts +// Examples: +// editor.tf.select(at) // Select at location +// editor.tf.select(at, { edge: 'end' }) // Select end of block above +// editor.tf.select(at, { edge: 'start' }) // Select start of block above +``` @@ -943,24 +941,24 @@ Set the selection to a new value. When a selection already exists, this method w Deselect the editor in the DOM. -+ ```ts -+ // This removes any browser selection from the editor's DOM element -+ ``` +```ts +// This removes any browser selection from the editor's DOM element +``` -+ -+ Returns `void` -+ + + Returns `void` + ### `focus` Focus the editor. -+ ```ts -+ // Examples: -+ // editor.tf.focus() // focus editor -+ // editor.tf.focus({ edge: 'end' }) // end of selection if selection exists -+ // editor.tf.focus({ edge: 'end' }) // end of editor if selection is null -+ ``` +```ts +// Examples: +// editor.tf.focus() // focus editor +// editor.tf.focus({ edge: 'end' }) // end of selection if selection exists +// editor.tf.focus({ edge: 'end' }) // end of editor if selection is null +``` @@ -986,11 +984,11 @@ Focus the editor. Insert data from a `DataTransfer` into the editor. -+ ```ts -+ // This is a proxy method that calls in this order: -+ // 1. insertFragmentData(editor, data) -+ // 2. insertTextData(editor, data) -+ ``` +```ts +// This is a proxy method that calls in this order: +// 1. insertFragmentData(editor, data) +// 2. insertTextData(editor, data) +``` @@ -998,18 +996,18 @@ Insert data from a `DataTransfer` into the editor. -+ -+ Returns `void` -+ + + Returns `void` + ### `insertFragmentData` Insert fragment data from a `DataTransfer` into the editor. -+ ```ts -+ // Attempts to insert fragment data from the data transfer object. -+ // Returns true if content was successfully inserted. -+ ``` +```ts +// Attempts to insert fragment data from the data transfer object. +// Returns true if content was successfully inserted. +``` @@ -1017,18 +1015,18 @@ Insert fragment data from a `DataTransfer` into the editor. -+ -+ Returns `boolean` - `true` if content was successfully inserted, `false` otherwise. -+ + + Returns `boolean` - `true` if content was successfully inserted, `false` otherwise. + ### `insertTextData` Insert text data from a `DataTransfer` into the editor. -+ ```ts -+ // Attempts to insert text data from the data transfer object. -+ // Returns true if content was successfully inserted. -+ ``` +```ts +// Attempts to insert text data from the data transfer object. +// Returns true if content was successfully inserted. +``` @@ -1036,9 +1034,9 @@ Insert text data from a `DataTransfer` into the editor. -+ -+ Returns `boolean` - `true` if content was successfully inserted, `false` otherwise. -+ + + Returns `boolean` - `true` if content was successfully inserted, `false` otherwise. + ### `setFragmentData` @@ -1050,18 +1048,18 @@ Set data from the currently selected fragment on a `DataTransfer`. -+ -+ Returns `void` -+ + + Returns `void` + ### `setSplittingOnce` Set whether the next operation should split into a new batch in the history. -+ ```ts -+ // When true, the next operation will start a new batch in the history -+ // instead of merging with the previous operations -+ ``` +```ts +// When true, the next operation will start a new batch in the history +// instead of merging with the previous operations +``` @@ -1069,17 +1067,17 @@ Set whether the next operation should split into a new batch in the history. -+ -+ Returns `void` -+ + + Returns `void` + ### `withMerging` Apply a series of changes inside a synchronous function. These operations will be merged into the previous history. -+ ```ts -+ // All operations inside the function will be merged with the previous history batch -+ ``` +```ts +// All operations inside the function will be merged with the previous history batch +``` @@ -1087,18 +1085,18 @@ Apply a series of changes inside a synchronous function. These operations will b -+ -+ Returns `void` -+ + + Returns `void` + ### `withNewBatch` Apply a series of changes inside a synchronous function, ensuring that the first operation starts a new batch in the history. -+ ```ts -+ // The first operation starts a new batch in history -+ // Subsequent operations will be merged as usual -+ ``` +```ts +// The first operation starts a new batch in history +// Subsequent operations will be merged as usual +``` @@ -1106,9 +1104,9 @@ Apply a series of changes inside a synchronous function, ensuring that the first -+ -+ Returns `void` -+ + + Returns `void` + ### `normalizeNode` diff --git a/apps/www/content/docs/en/api/slate/path.mdx b/apps/www/content/docs/en/api/slate/path.mdx index e847feb9f..c1d514421 100644 --- a/apps/www/content/docs/en/api/slate/path.mdx +++ b/apps/www/content/docs/en/api/slate/path.mdx @@ -11,13 +11,13 @@ description: API reference for paths in Slate. Check if an operation can transform a path. - + The operation to check. - + Returns `boolean` - `true` if the operation is an insert, merge, move, remove, or split operation. @@ -25,7 +25,7 @@ Check if an operation can transform a path. Transform a path by an operation. - + The path to transform. @@ -41,7 +41,7 @@ Transform a path by an operation. - + Returns `Path | null` - The transformed path, or `null` if the path was deleted. @@ -49,7 +49,7 @@ Transform a path by an operation. Get a list of ancestor paths for a given path. - + The path to get ancestors for. @@ -62,7 +62,7 @@ Get a list of ancestor paths for a given path. - + Returns `Path[]` - An array of paths sorted from shallowest to deepest ancestor (unless reversed). @@ -70,7 +70,7 @@ Get a list of ancestor paths for a given path. Get a path to a child at the given index. - + The parent path. @@ -79,7 +79,7 @@ Get a path to a child at the given index. - + Returns `Path` - The path to the child node. @@ -87,7 +87,7 @@ Get a path to a child at the given index. Get the common ancestor path of two paths. - + The first path. @@ -96,7 +96,7 @@ Get the common ancestor path of two paths. - + Returns `Path` - The common ancestor path. @@ -104,7 +104,7 @@ Get the common ancestor path of two paths. Compare a path to another, returning an integer indicating whether the path was before, at, or after the other. - + The first path to compare. @@ -113,7 +113,7 @@ Compare a path to another, returning an integer indicating whether the path was - + Returns `-1 | 0 | 1` - `-1` if before, `0` if at same location, `1` if after. @@ -121,7 +121,7 @@ Compare a path to another, returning an integer indicating whether the path was Check if a path ends after one of the indexes in another. - + The path to check. @@ -130,7 +130,7 @@ Check if a path ends after one of the indexes in another. - + Returns `boolean` - `true` if the path ends after the other path. @@ -138,7 +138,7 @@ Check if a path ends after one of the indexes in another. Check if a path ends at one of the indexes in another. - + The path to check. @@ -147,7 +147,7 @@ Check if a path ends at one of the indexes in another. - + Returns `boolean` - `true` if the path ends at the same index as the other path. @@ -155,7 +155,7 @@ Check if a path ends at one of the indexes in another. Check if a path ends before one of the indexes in another. - + The path to check. @@ -164,7 +164,7 @@ Check if a path ends before one of the indexes in another. - + Returns `boolean` - `true` if the path ends before the other path. @@ -172,7 +172,7 @@ Check if a path ends before one of the indexes in another. Check if a path is exactly equal to another. - + The first path. @@ -181,7 +181,7 @@ Check if a path is exactly equal to another. - + Returns `boolean` - `true` if the paths are exactly equal. @@ -189,13 +189,13 @@ Check if a path is exactly equal to another. Get a path to the first child of a path. - + The parent path. - + Returns `Path` - The path to the first child node. @@ -203,13 +203,13 @@ Get a path to the first child of a path. Check if the path of previous sibling node exists. - + The path to check. - + Returns `boolean` - `true` if a previous sibling exists. @@ -217,7 +217,7 @@ Check if the path of previous sibling node exists. Check if a path is after another. - + The path to check. @@ -226,7 +226,7 @@ Check if a path is after another. - + Returns `boolean` - `true` if the first path is after the second. @@ -234,7 +234,7 @@ Check if a path is after another. Check if a path is an ancestor of another. - + The potential ancestor path. @@ -243,7 +243,7 @@ Check if a path is an ancestor of another. - + Returns `boolean` - `true` if the path is an ancestor of the other path. @@ -251,7 +251,7 @@ Check if a path is an ancestor of another. Check if a path is before another. - + The path to check. @@ -260,7 +260,7 @@ Check if a path is before another. - + Returns `boolean` - `true` if the first path is before the second. @@ -268,7 +268,7 @@ Check if a path is before another. Check if a path is a child of another. - + The potential child path. @@ -277,7 +277,7 @@ Check if a path is a child of another. - + Returns `boolean` - `true` if the path is a child of the other path. @@ -285,7 +285,7 @@ Check if a path is a child of another. Check if a path is equal to or an ancestor of another. - + The path to check. @@ -294,7 +294,7 @@ Check if a path is equal to or an ancestor of another. - + Returns `boolean` - `true` if the path is equal to or an ancestor of the other path. @@ -302,7 +302,7 @@ Check if a path is equal to or an ancestor of another. Check if a path is a descendant of another. - + The potential descendant path. @@ -311,7 +311,7 @@ Check if a path is a descendant of another. - + Returns `boolean` - `true` if the path is a descendant of the other path. @@ -319,7 +319,7 @@ Check if a path is a descendant of another. Check if a path is the parent of another. - + The potential parent path. @@ -328,7 +328,7 @@ Check if a path is the parent of another. - + Returns `boolean` - `true` if the path is the parent of the other path. @@ -336,13 +336,13 @@ Check if a path is the parent of another. Check if a value implements the `Path` interface. - + The value to check. - + Returns `boolean` - `true` if the value is a path. @@ -350,7 +350,7 @@ Check if a value implements the `Path` interface. Check if a path is a sibling of another. - + The path to check. @@ -359,7 +359,7 @@ Check if a path is a sibling of another. - + Returns `boolean` - `true` if the paths are siblings. @@ -367,13 +367,13 @@ Check if a path is a sibling of another. Get the last index of a path. - + The path to check. - + Returns `number` - The last index, or -1 if the path is empty. @@ -381,7 +381,7 @@ Get the last index of a path. Get a list of paths at every level down to a path. - + The path to get levels for. @@ -394,7 +394,7 @@ Get a list of paths at every level down to a path. - + Returns `Path[]` - An array of paths including the path itself and all its ancestors. @@ -402,13 +402,13 @@ Get a list of paths at every level down to a path. Get the path to the next sibling node. - + The current path. - + Returns `Path` - The path to the next sibling. @@ -416,13 +416,13 @@ Get the path to the next sibling node. Get the path to the parent node. - + The current path. - + Returns `Path` - The path to the parent node. @@ -430,13 +430,13 @@ Get the path to the parent node. Get the path to the previous sibling node. - + The current path. - + Returns `Path | undefined` - The path to the previous sibling, or `undefined` if there is none. @@ -444,7 +444,7 @@ Get the path to the previous sibling node. Get a path relative to an ancestor. - + The path to make relative. @@ -453,7 +453,7 @@ Get a path relative to an ancestor. - + Returns `Path` - The relative path. @@ -467,7 +467,7 @@ An array of numbers representing the indexes to traverse to reach a specific nod Options for getting ancestor paths. - + If true, the paths are returned in reverse order. @@ -477,7 +477,7 @@ Options for getting ancestor paths. Options for getting path levels. - + If true, the paths are returned in reverse order. @@ -487,7 +487,7 @@ Options for getting path levels. Options for transforming paths. - + The affinity of the transform.