Skip to content

Commit

Permalink
docs: fix outdated importDOM types in docs (#5431)
Browse files Browse the repository at this point in the history
  • Loading branch information
thorn0 authored Jan 4, 2024
1 parent ac61359 commit b6ae079
Showing 1 changed file with 17 additions and 39 deletions.
56 changes: 17 additions & 39 deletions packages/lexical-website/docs/concepts/serialization.md
Original file line number Diff line number Diff line change
Expand Up @@ -92,31 +92,29 @@ static importDOM(): DOMConversionMap | null;
```
The return value of `importDOM` is a map of the lower case (DOM) [Node.nodeName](https://developer.mozilla.org/en-US/docs/Web/API/Node/nodeName) property to an object that specifies a conversion function and a priority for that conversion. This allows `LexicalNodes` to specify which type of DOM nodes they can convert and what the relative priority of their conversion should be. This is useful in cases where a DOM Node with specific attributes should be interpreted as one type of `LexicalNode`, and otherwise it should be represented as another type of `LexicalNode`.

```js
export type DOMConversionMap = {
[NodeName]: <T: HTMLElement>(node: T) => DOMConversion | null,
};
```ts
type DOMConversionMap = Record<
string,
(node: HTMLElement) => DOMConversion | null
>;

export type DOMConversion = {
conversion: DOMConversionFn,
priority: 0 | 1 | 2 | 3 | 4,
type DOMConversion = {
conversion: DOMConversionFn;
priority: 0 | 1 | 2 | 3 | 4;
};

export type DOMConversionFn = (
element: Node,
parent?: Node,
preformatted?: boolean,
) => DOMConversionOutput;
type DOMConversionFn = (element: HTMLElement) => DOMConversionOutput | null;

export type DOMConversionOutput = {
after?: (childLexicalNodes: Array<LexicalNode>) => Array<LexicalNode>,
forChild?: DOMChildConversion,
node: LexicalNode | null,
type DOMConversionOutput = {
after?: (childLexicalNodes: Array<LexicalNode>) => Array<LexicalNode>;
forChild?: DOMChildConversion;
node: null | LexicalNode | Array<LexicalNode>;
};

export type DOMChildConversion = (
type DOMChildConversion = (
lexicalNode: LexicalNode,
) => LexicalNode | null | void;
parentLexicalNode: LexicalNode | null | undefined,
) => LexicalNode | null | undefined;
```

@lexical/code provides a good example of the usefulness of this design. GitHub uses HTML ```<table>``` elements to represent the structure of copied code in HTML. If we interpreted all HTML ```<table>``` elements as literal tables, then code pasted from GitHub would appear in Lexical as a Lexical TableNode. Instead, CodeNode specifies that it can handle ```<table>``` elements too:
Expand Down Expand Up @@ -145,27 +143,7 @@ static importDOM(): DOMConversionMap | null {

If the imported ```<table>``` doesn't align with the expected GitHub code HTML, then we return null and allow the node to be handled by lower priority conversions.

Much like `exportDOM`, `importDOM` exposes APIs to allow for post-processing of converted Nodes. The conversion function returns a `DOMConversionOutput` which can specify a function to run for each converted child (forChild) or on all the child nodes after the conversion is complete (after). The key difference here is that ```forChild``` runs for every deeply nested child node of the current node, whereas ```after``` will run only once after the transformation of the node and all its children is complete. Finally, `preformatted` flag indicates that nested text content is preformatted (similar to `<pre>` tag) and all newlines and spaces should be preserved as is.

```js
export type DOMConversionFn = (
element: Node,
parent?: Node,
preformatted?: boolean,
) => DOMConversionOutput;

export type DOMConversionOutput = {
after?: (childLexicalNodes: Array<LexicalNode>) => Array<LexicalNode>,
forChild?: DOMChildConversion,
node: LexicalNode | null,
};

export type DOMChildConversion = (
lexicalNode: LexicalNode,
parentLexicalNode: LexicalNode | null | undefined,
) => LexicalNode | null;
```

Much like `exportDOM`, `importDOM` exposes APIs to allow for post-processing of converted Nodes. The conversion function returns a `DOMConversionOutput` which can specify a function to run for each converted child (forChild) or on all the child nodes after the conversion is complete (after). The key difference here is that ```forChild``` runs for every deeply nested child node of the current node, whereas ```after``` will run only once after the transformation of the node and all its children is complete.

## JSON

Expand Down

2 comments on commit b6ae079

@vercel
Copy link

@vercel vercel bot commented on b6ae079 Jan 4, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Successfully deployed to the following URLs:

lexical – ./packages/lexical-website

lexical-git-main-fbopensource.vercel.app
www.lexical.dev
lexical-fbopensource.vercel.app
lexical.dev
lexicaljs.org
lexicaljs.com

@vercel
Copy link

@vercel vercel bot commented on b6ae079 Jan 4, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Successfully deployed to the following URLs:

lexical-playground – ./packages/lexical-playground

lexical-playground-fbopensource.vercel.app
lexical-playground-git-main-fbopensource.vercel.app
playground.lexical.dev
lexical-playground.vercel.app

Please sign in to comment.