@nacelle/rich-text-utils
Version:
A set of Typescript types and helpers to work with Rich Text fields.
387 lines (386 loc) • 10 kB
TypeScript
export declare type Node = BlockNode | InlineNode;
export declare type BlockNode = Root | Paragraph | Heading | Block | List | ListItem | Blockquote | Code | ThematicBreak;
export declare type InlineNode = Span | Link | EntryLink | InlineEntry;
export declare type NodeWithMeta = Link | EntryLink;
export declare type MetaEntry = {
id: string;
value: string;
};
export declare type TransformMetaContext = {
node: NodeWithMeta;
meta: Array<MetaEntry>;
};
export declare type TransformedMeta = {
[prop: string]: unknown;
} | null | undefined;
export declare type TransformMetaFn = (context: TransformMetaContext) => TransformedMeta;
export declare type RootType = 'root';
/**
* Every `rast` document MUST start with a `root` node.
*
* ```json
* {
* "type": "root",
* "children": [
* {
* "type": "heading",
* "level": 1,
* "children": [
* {
* "type": "span",
* "value": "Title"
* }
* ]
* },
* {
* "type": "paragraph",
* "children": [
* {
* "type": "span",
* "value": "A simple paragraph!"
* }
* ]
* }
* ]
* }
* ```
*/
export declare type Root = {
type: RootType;
children: Array<Paragraph | Heading | List | Code | Blockquote | Block | ThematicBreak>;
};
export declare type ParagraphType = 'paragraph';
/**
* A `paragraph` node represents a unit of textual content.
*
* ```json
* {
* "type": "paragraph",
* "children": [
* {
* "type": "span",
* "value": "A simple paragraph!"
* }
* ]
* }
* ```
*/
export declare type Paragraph = {
type: ParagraphType;
children: Array<InlineNode>;
};
export declare type HeadingType = 'heading';
/**
* An `heading` node represents a heading of a section. Using the `level` attribute you
* can control the rank of the heading.
*
* ```json
* {
* "type": "heading",
* "level": 2,
* "children": [
* {
* "type": "span",
* "value": "An h2 heading!"
* }
* ]
* }
* ```
*/
export declare type Heading = {
type: HeadingType;
level: 1 | 2 | 3 | 4 | 5 | 6;
children: Array<InlineNode>;
};
export declare type ListType = 'list';
/**
* A `list` node represents a list of items. Unordered lists must have its `style` field
* set to `bulleted`, while ordered lists, instead, have its `style` field set to `numbered`.
*
* ```json
* {
* "type": "list",
* "style": "bulleted",
* "children": [
* {
* "type": "listItem",
* "children": [
* {
* "type": "paragraph",
* "children": [
* {
* "type": "span",
* "value": "This is a list item!"
* }
* ]
* }
* ]
* }
* ]
* }
* ```
*/
export declare type List = {
type: ListType;
style: 'bulleted' | 'numbered';
children: Array<ListItem>;
};
export declare type ListItemType = 'listItem';
/**
* A `listItem` node represents an item in a list.
*
* ```json
* {
* "type": "listItem",
* "children": [
* {
* "type": "paragraph",
* "children": [
* {
* "type": "span",
* "value": "This is a list item!"
* }
* ]
* }
* ]
* }
* ```
*/
export declare type ListItem = {
type: ListItemType;
children: Array<Paragraph | List>;
};
export declare type ThematicBreakType = 'thematicBreak';
/**
* A `thematicBreak` node represents a thematic break between paragraph-level elements:
* for example, a change of scene in a story, or a shift of topic within a section.
*
* ```json
* {
* "type": "thematicBreak"
* }
* ```
*/
export declare type ThematicBreak = {
type: ThematicBreakType;
};
export declare type CodeType = 'code';
/**
* A `code` node represents a block of preformatted text, such as computer code.
*
* ```json
* {
* "type": "code",
* "language": "javascript",
* "highlight": [1],
* "code": "function greetings() {\n console.log('Hi!');\n}"
* }
* ```
*/
export declare type Code = {
type: CodeType;
/** The language of computer code being marked up (ie. `"javascript"`) */
language?: string;
/** A zero-based array of line numbers to highlight (ie. `[0, 1, 3]`)*/
highlight?: Array<number>;
/** The marked up computer code */
code: string;
};
export declare type BlockquoteType = 'blockquote';
/**
* A `blockquote` node is a containter that represents text which is an extended quotation.
*
* ```json
* {
* "type": "blockquote",
* "attribution": "Oscar Wilde",
* "children": [
* {
* "type": "paragraph",
* "children": [
* {
* "type": "span",
* "value": "Be yourself; everyone else is taken."
* }
* ]
* }
* ]
* }
* ```
*/
export declare type Blockquote = {
type: BlockquoteType;
/** Attribution for the quote (ie `"Mark Smith"`) */
attribution?: string;
children: Array<Paragraph>;
};
export declare type BlockType = 'block';
/**
* Similarly to Modular Content fields,
* you can also embed block records into Rich Text. A `block` node stores a reference to a
* block record embedded inside the `rast` document.
*
* This type of node can only be put as a direct child of the [`root`](#root) node.
*
* ```json
* {
* "type": "block",
* "entry": "1238455312"
* }
* ```
*/
export declare type Block = {
type: BlockType;
/** The block record ID */
entry: string;
};
export declare type SpanType = 'span';
/** Supported marks for `span` nodes */
export declare type Mark = 'strong' | 'code' | 'emphasis' | 'underline' | 'strikethrough' | 'highlight';
/**
* A `span` node represents a text node. It might optionally contain decorators called `marks`. It is worth
* mentioning that you can use the `\n` newline character to express line breaks.
*
* ```json
* {
* "type": "span",
* "marks": ["highlight", "emphasis"],
* "value": "Some random text here, move on!"
* }
* ```
*/
export declare type Span = {
type: SpanType;
/**
* Array of decorators for the current chunk of text.
* Valid marks are: `strong`, `code`, `emphasis`, `underline`, `strikethrough` and `highlight`.
*/
marks?: Mark[];
value: string;
};
export declare type LinkType = 'link';
/**
* A `link` node represents a normal hyperlink. It might optionally contain a number of additional
* custom information under the `meta` key. You can also link to records using
* the [`entryLink`](#entryLink) node.
*
* ```json
* {
* "type": "link",
* "url": "https://www.nacelle.com/"
* "meta": [
* { "id": "rel", "value": "nofollow" },
* { "id": "target", "value": "_blank" }
* ],
* "children": [
* {
* "type": "span",
* "value": "The best CMS in town"
* }
* ]
* }
* ```
*/
export declare type Link = {
type: LinkType;
/**
* The actual URL where the link points to. Can be any string, no specific format is enforced.
*/
url: string;
/**
* Array of tuples containing custom meta-information for the link.
*/
meta?: Array<MetaEntry>;
children: Array<Span>;
};
export declare type EntryLinkType = 'entryLink';
/**
* An `entryLink` node is similar to a [`link`](#link) node node, but instead of
* linking a portion of text to a URL, it links the document to another record
* present in the same project.
*
* It might optionally contain a number of additional custom information under
* the `meta` key.
*
* If you want to link to a record without having to specify some
* inner content, then please use the [`inlineEntry`](#inlineEntry) node.
*
* ```json
* {
* "type": "entryLink",
* "entry": "38945648",
* "meta": [
* { "id": "rel", "value": "nofollow" },
* { "id": "target", "value": "_blank" }
* ],
* "children": [
* {
* "type": "span",
* "value": "Matteo Giaccone"
* }
* ]
* }
* ```
*/
export declare type EntryLink = {
type: EntryLinkType;
/** The linked record ID */
entry: string;
/**
* Array of tuples containing custom meta-information for the link.
*/
meta?: Array<MetaEntry>;
children: Array<Span>;
};
export declare type InlineEntryType = 'inlineEntry';
/**
* An `inlineEntry`, similarly to [`entryLink`](#entryLink), links the document to
* another record but does not specify any inner content (children).
*
* It can be used in situations where it is up to the frontend to decide how to present the
* record (ie. a widget, or an `<a>` tag pointing to the URL of the record with a text that
* is the title of the linked record).
*
* ```json
* {
* "type": "inlineEntry",
* "entry": "74619345"
* }
* ```
*/
export declare type InlineEntry = {
type: InlineEntryType;
/** The record ID */
entry: string;
};
export declare type WithChildrenNode = Exclude<Node, Code | Span | Block | InlineEntry | ThematicBreak>;
/**
* A Rich Text `rast`-compatible value, composed by the `rast` document
* itself and the `schema` attribute.
*/
export declare type Document = {
schema: 'rast';
document: Root;
};
export declare type NodeType = ParagraphType | HeadingType | LinkType | EntryLinkType | InlineEntryType | BlockType | ListType | ListItemType | BlockquoteType | CodeType | RootType | SpanType | ThematicBreakType;
/**
* Rich Text enables authors to create rich text content, on par with
* traditional editors.
*
* Additionally, it allows records and Media Area assets to be linked dynamically
* and embedded within the flow of the text.
*/
export declare type RichText<R extends Record = Record> = {
/** A compatible document */
value: Document;
/** Blocks associated with the Rich Text */
blocks?: R[];
/** Links associated with the Rich Text */
links?: R[];
};
export declare type Record = {
__typename: string;
id: string;
} & {
[prop: string]: unknown;
};