@contember/react-slate-editor-base 2.0.0-alpha.1

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@contember/react-slate-editor-base",
+  "license": "Apache-2.0",
+  "version": "2.0.0-alpha.1",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/production/index.js",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/types/index.d.ts",
+        "development": "./dist/development/index.js",
+        "production": "./dist/production/index.js",
+        "default": "./dist/production/index.js"
+      },
+      "require": {
+        "types": "./dist/types/index.d.ts",
+        "development": "./dist/development/index.cjs",
+        "production": "./dist/production/index.cjs",
+        "default": "./dist/production/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist/",
+    "src/"
+  ],
+  "typings": "./dist/types/index.d.ts",
+  "scripts": {
+    "build": "yarn build:js:dev && yarn build:js:prod",
+    "build:js:dev": "vite build --mode development",
+    "build:js:prod": "vite build --mode production",
+    "ae:build": "api-extractor run --local",
+    "ae:test": "api-extractor run",
+    "test": "vitest"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/contember/interface.git",
+    "directory": "packages/react-slate-editor-base"
+  },
+  "dependencies": {
+    "@contember/binding": "2.0.0-alpha.1",
+    "@contember/react-binding": "2.0.0-alpha.1",
+    "@contember/utilities": "2.0.0-alpha.1",
+    "@radix-ui/primitive": "^1.0.1",
+    "@radix-ui/react-slot": "^1.0.2",
+    "is-hotkey": "^0.2.0",
+    "slate": "^0.103.0",
+    "slate-history": "^0.100.0",
+    "slate-react": "^0.102.0"
+  },
+  "peerDependencies": {
+    "react": "^18 || ^19",
+    "react-dom": "^18 || ^19"
+  },
+  "devDependencies": {
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "stableVersion": "0.0.0"
+}

package/src/components/RichTextEditor.tsx

@@ -0,0 +1,123 @@
+import { Component, Field, FieldAccessor, FieldBasicProps, QueryLanguage, useEntity } from '@contember/react-binding'
+import { FunctionComponent, useCallback, useMemo, useState } from 'react'
+import { Descendant, Editor, Element as SlateElement, Node as SlateNode, NodeEntry, Transforms } from 'slate'
+import { Slate } from 'slate-react'
+import { createEditor, CreateEditorPublicOptions } from '../editor'
+import { paragraphElementType } from '../plugins'
+import { useRichTextFieldNodes } from '../internal/hooks/useRichTextFieldNodes'
+
+export type RichTextEditorProps =
+	& FieldBasicProps
+	& CreateEditorPublicOptions
+	& {
+		children: React.ReactNode
+	}
+
+/**
+ * Rich text field supports more advanced formatting capabilities. Output of this field is a JSON.
+ *
+ * @group Form Fields
+ */
+export const RichTextEditor: FunctionComponent<RichTextEditorProps> = Component(
+	props => {
+		const entity = useEntity()
+		const environment = entity.environment
+		const getParent = entity.getAccessor
+
+		const desugaredField = useMemo(
+			() => QueryLanguage.desugarRelativeSingleField(props, environment),
+			[environment, props],
+		)
+		const fieldAccessor = useMemo(() => entity.getRelativeSingleField<string>(desugaredField), [entity, desugaredField])
+
+		// The cache is questionable, really.
+		const [contemberFieldElementCache] = useState(() => new WeakMap<FieldAccessor<string>, SlateElement[]>())
+
+
+		const [editor] = useState(() => {
+			const { editor } = createEditor({
+				plugins: props.plugins,
+				defaultElementType: paragraphElementType,
+				entity,
+				environment,
+				children: props.children,
+			})
+
+			const { normalizeNode } = editor
+			Object.assign(editor, {
+				insertBreak: () => {
+					Transforms.insertText(editor, '\n')
+				},
+				normalizeNode: (nodeEntry: NodeEntry) => {
+					const [node, path] = nodeEntry
+					if (path.length === 0 && SlateElement.isAncestor(node)) {
+						// Enforce that there's exactly one child and that it's
+						if (node.children.length > 1) {
+							return Editor.withoutNormalizing(editor, () => {
+								const targetPath = [0, (editor.children[0] as SlateElement).children.length]
+								Transforms.moveNodes(editor, {
+									at: [1],
+									to: targetPath,
+								})
+								Transforms.unwrapNodes(editor, { at: targetPath })
+							})
+						}
+						if (SlateElement.isElement(node.children[0]) && !editor.isDefaultElement(node.children[0])) {
+							return Editor.withoutNormalizing(editor, () => {
+								Transforms.wrapNodes(editor, editor.createDefaultElement([{ text: '' }]), {
+									at: path,
+								})
+								Transforms.unwrapNodes(editor, { at: [0, 0] })
+							})
+						}
+					}
+					if (SlateElement.isElement(node) && Editor.isBlock(editor, node) && path.length > 1) {
+						return Transforms.unwrapNodes(editor, { at: path })
+					}
+					normalizeNode(nodeEntry)
+				},
+			})
+
+			return editor
+		})
+
+		const valueNodes = useRichTextFieldNodes({
+			editor,
+			fieldAccessor,
+			contemberFieldElementCache,
+		})
+
+		const serialize = editor.serializeNodes
+		const onChange = useCallback(
+			(value: Descendant[]) => {
+				getParent().batchUpdates(getAccessor => {
+					const fieldAccessor = getAccessor().getRelativeSingleField(desugaredField)
+
+					if (SlateNode.string({ type: 'dummy', children: value }) === '' && fieldAccessor.valueOnServer === null) {
+						fieldAccessor.updateValue(null)
+						return
+					}
+
+					if (SlateElement.isElement(value[0])) {
+						fieldAccessor.updateValue(serialize(value[0].children))
+						contemberFieldElementCache.set(getAccessor().getRelativeSingleField(desugaredField), value as SlateElement[])
+					}
+				})
+			},
+			[getParent, contemberFieldElementCache, desugaredField, serialize],
+		)
+
+		return (
+				<Slate editor={editor} initialValue={valueNodes} onChange={onChange}>
+					{props.children}
+				</Slate>
+		)
+	},
+	props => (
+		<>
+			<Field defaultValue={props.defaultValue} field={props.field} isNonbearing={props.isNonbearing} />
+		</>
+	),
+	'RichTextEditor',
+)
+

package/src/components/index.ts

@@ -0,0 +1,3 @@
+export * from './triggers'
+
+export * from './RichTextEditor'

package/src/components/triggers/EditorElementTrigger.tsx

@@ -0,0 +1,22 @@
+import * as React from 'react'
+import { ReactElement } from 'react'
+import { useSlate } from 'slate-react'
+import { Slot } from '@radix-ui/react-slot'
+import { dataAttribute } from '@contember/utilities'
+
+export interface EditorElementTriggerProps {
+	elementType: string
+	suchThat?: Record<string, unknown>
+	children: ReactElement
+}
+
+export const EditorElementTrigger = ({ elementType, suchThat, ...props }: EditorElementTriggerProps) => {
+	const editor = useSlate()
+
+	const isActive = editor.isElementActive(elementType, suchThat)
+	const onClick = () => {
+		editor.toggleElement(elementType, suchThat)
+	}
+
+	return <Slot onClick={onClick} data-active={dataAttribute(isActive)} {...props} />
+}

package/src/components/triggers/EditorGenericTrigger.tsx

@@ -0,0 +1,27 @@
+import * as React from 'react'
+import { ReactElement } from 'react'
+import { Slot } from '@radix-ui/react-slot'
+import { Editor } from 'slate'
+import { dataAttribute } from '@contember/utilities'
+import { useSlate } from 'slate-react'
+
+export interface EditorGenericTriggerProps {
+	isActive?: (args: { editor: Editor }) => boolean
+	shouldDisplay?: (args: { editor: Editor }) => boolean
+	toggle: (args: { editor: Editor }) => void
+	children: ReactElement
+}
+
+export const EditorGenericTrigger = ({ toggle, isActive, shouldDisplay, ...props }: EditorGenericTriggerProps) => {
+
+	const editor = useSlate()
+	const onClick = () => {
+		toggle({ editor })
+	}
+	const active = isActive?.({ editor }) ?? false
+	const display = shouldDisplay?.({ editor }) ?? true
+	if (!display) {
+		return null
+	}
+	return <Slot onClick={onClick} data-active={dataAttribute(active)} {...props} />
+}

package/src/components/triggers/EditorMarkTrigger.tsx

@@ -0,0 +1,21 @@
+import * as React from 'react'
+import { ReactElement } from 'react'
+import { useSlate } from 'slate-react'
+import { Slot } from '@radix-ui/react-slot'
+import { dataAttribute } from '@contember/utilities'
+
+export interface EditorMarkTriggerProps {
+	mark: string
+	children: ReactElement
+}
+
+export const EditorMarkTrigger = ({ mark, ...props }: EditorMarkTriggerProps) => {
+	const editor = useSlate()
+
+	const isActive = editor.hasMarks({ [mark]: true })
+	const onClick = () => {
+		editor.toggleMarks({ [mark]: true })
+	}
+
+	return <Slot onClick={onClick} data-active={dataAttribute(isActive)} {...props} />
+}

package/src/components/triggers/EditorWrapNodeTrigger.tsx

@@ -0,0 +1,36 @@
+import { Selection } from 'slate'
+import { MouseEventHandler, ReactElement } from 'react'
+import { useSlate } from 'slate-react'
+import { Slot } from '@radix-ui/react-slot'
+import * as React from 'react'
+import { composeEventHandlers } from '@radix-ui/primitive'
+import { EditorTransforms } from '../../slate-reexport'
+
+export interface EditorWrapNodeTriggerProps {
+	elementType: string
+	selection?: Selection
+	suchThat?: Record<string, unknown>
+	children: ReactElement
+	onClick?: MouseEventHandler<HTMLElement>
+}
+
+export const EditorWrapNodeTrigger = ({ elementType, suchThat, selection, ...props }: EditorWrapNodeTriggerProps) => {
+	const editor = useSlate()
+	const onClick = () => {
+		if (selection) {
+			EditorTransforms.select(editor, selection)
+		}
+		EditorTransforms.wrapNodes(
+			editor,
+			{
+				type: elementType,
+				children: [{ text: '' }],
+				...suchThat,
+			},
+			{ split: true },
+		)
+		EditorTransforms.collapse(editor, { edge: 'end' })
+	}
+
+	return <Slot {...props} onClick={composeEventHandlers(props.onClick, onClick)} />
+}

package/src/components/triggers/index.ts

@@ -0,0 +1,4 @@
+export * from './EditorElementTrigger'
+export * from './EditorGenericTrigger'
+export * from './EditorMarkTrigger'
+export * from './EditorWrapNodeTrigger'

package/src/editor/createEditor.ts

@@ -0,0 +1,52 @@
+import { createEditorWithEssentials } from './createEditorWithEssentials'
+import { Editor } from 'slate'
+import { EditorPlugin, EditorPluginWrapperProps } from '../types'
+import { createElement, FunctionComponent, ReactNode } from 'react'
+import { EntityAccessor } from '@contember/binding'
+import { Environment } from '@contember/react-binding'
+
+
+export interface CreateEditorPublicOptions {
+	plugins?: EditorPlugin[]
+}
+
+export interface CreateEditorOptions extends CreateEditorPublicOptions {
+	defaultElementType: string
+	entity: EntityAccessor
+	environment: Environment
+	children: ReactNode
+}
+
+export const createEditor = ({
+	plugins = [],
+	defaultElementType,
+	entity,
+	environment,
+	children,
+}: CreateEditorOptions): {
+	editor: Editor,
+	OuterWrapper: FunctionComponent<{ children: ReactNode }>
+	InnerWrapper: FunctionComponent<{ children: ReactNode }>
+} => {
+	const editor = createEditorWithEssentials({ defaultElementType })
+	const outerWrappers: FunctionComponent<EditorPluginWrapperProps>[] = []
+	const innerWrappers: FunctionComponent<EditorPluginWrapperProps>[] = []
+	plugins?.forEach(plugin => {
+		if (typeof plugin === 'function') {
+			plugin(editor)
+			return
+		}
+		plugin.extendEditor?.({ editor, children, environment, entity })
+		if (plugin?.OuterWrapper) {
+			outerWrappers.push(plugin.OuterWrapper)
+		}
+		if (plugin?.InnerWrapper) {
+			innerWrappers.push(plugin.InnerWrapper)
+		}
+	})
+	return {
+		editor,
+		OuterWrapper: ({ children }) => outerWrappers.reduceRight((acc, Wrapper) => createElement(Wrapper, { editor }, acc), children),
+		InnerWrapper: ({ children }) => innerWrappers.reduceRight((acc, Wrapper) => createElement(Wrapper, { editor }, acc), children),
+	}
+}

package/src/editor/createEditorWithEssentials.tsx

@@ -0,0 +1,248 @@
+import { createElement, isValidElement, ReactElement } from 'react'
+import { createEditor, Descendant, Editor, Element as SlateElement, Node as SlateNode, Path, Range as SlateRange, Text as SlateText, Transforms } from 'slate'
+import * as Slate from 'slate'
+import { withHistory } from 'slate-history'
+import { ReactEditor, withReact } from 'slate-react'
+import { EditorElementPlugin, EditorMarkPlugin } from '../types/plugins'
+import { TextSpecifics } from '../types/editor'
+import { DefaultElement } from '../internal/components/DefaultElement'
+import { withPaste } from '../plugins/behaviour'
+import { ContemberEditor } from './index'
+
+export const createEditorWithEssentials = ({ defaultElementType }: { defaultElementType: string }): Editor => {
+	const underlyingEditor = withHistory(withReact(createEditor() as ReactEditor))
+
+	const editor = underlyingEditor as unknown as Editor
+	const { normalizeNode, isInline, isVoid, deleteBackward } = editor
+
+	const elements = new Map<string, EditorElementPlugin<any>>()
+	const marks = new Map<string, EditorMarkPlugin>()
+
+	Object.assign<Editor, Partial<Editor>>(editor, {
+		slate: Slate,
+		formatVersion: 1,
+		defaultElementType,
+		isDefaultElement: element => 'type' in element && (element as any).type === defaultElementType,
+		createDefaultElement: children => ({
+			type: defaultElementType,
+			children,
+		}),
+		insertBetweenBlocks: ([element, path], edge) => {
+			const edgeOffset = edge === 'before' ? 0 : 1
+			const targetPath = path.slice(0, -1).concat(path[path.length - 1] + edgeOffset)
+			Transforms.insertNodes(editor, editor.createDefaultElement([{ text: '' }]), {
+				at: targetPath,
+				select: true,
+			})
+		},
+
+		canToggleMarks: () => true,
+		canToggleElement: <E extends SlateElement>() => true,
+
+		hasMarks: <T extends SlateText>(marks: TextSpecifics<T>) => ContemberEditor.hasMarks(editor, marks),
+
+		// TODO in the following function, we need to conditionally trim the selection so that it doesn't potentially
+		// 	include empty strings at the edges of top-level elements.
+		isElementActive: <E extends SlateElement>(elementType: E['type'], suchThat?: Partial<E>) => {
+			return (
+				elements.get(elementType)?.isActive?.({ editor, suchThat })
+				?? Array.from(Editor.nodes(editor, {
+					match: node => SlateElement.isElement(node) && ContemberEditor.isElementType(node, elementType, suchThat),
+					voids: false,
+				})).length > 0
+			)
+		},
+
+		acceptsAttributes: <E extends SlateElement>(elementType: E['type'], suchThat: Partial<E>) => {
+			return elements.get(elementType)?.acceptsAttributes?.({ editor, suchThat }) ?? false
+		},
+
+		toggleMarks: <T extends SlateText>(marks: TextSpecifics<T>) => {
+			if (!editor.canToggleMarks(marks)) {
+				return
+			}
+			const isActive = editor.hasMarks(marks)
+			if (isActive) {
+				ContemberEditor.removeMarks(editor, marks)
+				return false
+			}
+			ContemberEditor.addMarks(editor, marks)
+			return true
+		},
+		toggleElement: <E extends SlateElement>(elementType: E['type'], suchThat?: Partial<E>) => {
+			elements.get(elementType)?.toggleElement?.({
+				editor,
+				suchThat,
+			})
+		},
+
+		isInline: element => {
+			return elements.get(element.type)?.isInline ?? isInline(element)
+		},
+
+		isVoid: element => {
+			const elIsVoid = elements.get(element.type)?.isVoid
+			if (elIsVoid === undefined) {
+				return isVoid(element)
+			}
+			if (typeof elIsVoid === 'boolean') {
+				return elIsVoid
+			}
+			return elIsVoid({ editor, element })
+		},
+
+		canContainAnyBlocks: element => {
+			if (Editor.isEditor(element)) {
+				return true
+			}
+			return !editor.isInline(element)
+				&& !editor.isVoid(element)
+				&& (elements.has(element.type) ? elements.get(element.type)!.canContainAnyBlocks ?? false : true)
+		},
+
+		serializeNodes: (nodes, errorMessage) => ContemberEditor.serializeNodes(editor, nodes, errorMessage),
+		deserializeNodes: (serializedNodes, errorMessage) =>
+			ContemberEditor.permissivelyDeserializeNodes(editor, serializedNodes, errorMessage),
+
+		upgradeFormatBySingleVersion: (node, oldVersion) => {
+			if (SlateElement.isElement(node)) {
+				return {
+					...node,
+					children: node.children.map(child => editor.upgradeFormatBySingleVersion(child, oldVersion) as Descendant),
+				}
+			}
+			return node
+		},
+
+		renderElement: props => {
+			const component = elements.get(props.element.type)?.render ?? DefaultElement
+			return createElement(component, props)
+		},
+
+		renderLeafChildren: props => props.children,
+
+		renderLeaf: props => {
+			let el: ReactElement = createElement('span', props.attributes, editor.renderLeafChildren(props))
+			for (const [, mark] of marks) {
+				if (props.leaf[mark.type] === true) {
+					const markerEl = mark.render({ ...props, children: el })
+					if (markerEl !== null) {
+						if (!isValidElement(markerEl)) {
+							throw new Error(`Mark plugin ${mark.type} returned a non-React element`)
+						}
+						el = markerEl
+					}
+				}
+			}
+			return el
+		},
+
+		// Just noop functions so that other plugins can safely bubble-call
+		onDOMBeforeInput: () => {},
+		onKeyDown: e => {
+			for (const [, mark] of marks) {
+				if (mark.isHotKey(e.nativeEvent)) {
+					editor.toggleMarks({ [mark.type]: true })
+					e.preventDefault()
+					return
+				}
+			}
+
+
+			// Inline void nodes cannot be deleted by default: https://github.com/ianstormtaylor/slate/issues/3456
+			// This is a hack to get around this issue. The problem is that when an inline void node is selected, Slate's
+			// beforeInput handler doesn't get triggered. However, when we put the caret right after the inline void
+			// and press Backspace (or the other way around with Delete), it works just fine. Furthermore, if we deleted the
+			// node directly, either we'd lose the selection state or Slate, not knowing about us deleting, would still
+			// try to delete things on its own so as to respond to the user interaction. So we take advantage of this and
+			// instead of deleting the void node, we just carefully move the selection and have Slate do the deleting.
+			if (e.key !== 'Delete' && e.key !== 'Backspace') {
+				return
+			}
+			const selection = editor.selection
+
+			if (selection && SlateRange.isCollapsed(selection)) {
+				const voidEntry = Editor.void(editor, {
+					at: selection,
+					mode: 'lowest',
+					voids: true,
+				})
+				if (!voidEntry) {
+					return
+				}
+				const [node, nodePath] = voidEntry
+				if (editor.isInline(node)) {
+					const adjacentPoint =
+						e.key === 'Backspace'
+							? Editor.point(editor, Path.next(nodePath), {
+									edge: 'start',
+							  })
+							: Editor.point(editor, Path.previous(nodePath), {
+									edge: 'end',
+							  })
+					Transforms.select(editor, adjacentPoint)
+				}
+			}
+		},
+		onFocus: () => {},
+		onBlur: () => {},
+		normalizeNode: ([node, path]) => {
+			if (Editor.isEditor(node) && node.children.length === 0) {
+				Transforms.insertNodes(editor, editor.createDefaultElement([{ text: '' }]))
+			}
+			if (!SlateElement.isElement(node)) {
+				normalizeNode([node, path])
+				return
+			}
+			let defaultPrevented = false
+			elements.get(node.type)?.normalizeNode?.({
+				element: node,
+				path,
+				editor,
+				preventDefault: () => {
+					defaultPrevented = true
+				},
+			})
+			if (!defaultPrevented) {
+				normalizeNode([node, path])
+			}
+		},
+		registerElement: plugin => {
+			elements.set(plugin.type, plugin)
+		},
+		registerMark: plugin => {
+			marks.set(plugin.type, plugin)
+		},
+
+		deleteBackward: unit => {
+			const selection = editor.selection
+
+			if (selection && SlateRange.isCollapsed(selection)) {
+				const [node, nodePath] = Editor.node(editor, [selection.focus.path[0]])
+				if (SlateElement.isElement(node) && SlateNode.string(node) === '') {
+					const previous = Editor.previous(editor, {
+						at: nodePath,
+						voids: true,
+					})
+
+					if (previous) {
+						const [previousNode] = previous
+						if (SlateElement.isElement(previousNode) && editor.isVoid(previousNode)) {
+							editor.apply({
+								type: 'remove_node',
+								path: nodePath,
+								node,
+							})
+							return
+						}
+					}
+				}
+			}
+			deleteBackward(unit)
+		},
+	})
+
+	withPaste(editor)
+
+	return editor
+}

package/src/editor/index.ts

@@ -0,0 +1,48 @@
+import {
+	addMarks,
+	canToggleMark,
+	closest,
+	closestBlockEntry,
+	closestViableBlockContainerEntry,
+	ejectElement,
+	elementToSpecifics,
+	getElementDataAttributes,
+	getPreviousSibling,
+	hasMarks,
+	hasParentOfType,
+	isElementType,
+	permissivelyDeserializeNodes,
+	removeMarks,
+	serializeNodes,
+	strictlyDeserializeNodes,
+	textToSpecifics,
+	toLatestFormat,
+	topLevelNodes,
+} from './methods'
+
+export type { ElementDataAttributes } from './methods'
+
+// TODO use export * as ContemberEditor from './methods' once the tooling is ready.
+export const ContemberEditor = {
+	addMarks,
+	canToggleMark,
+	closest,
+	closestBlockEntry,
+	closestViableBlockContainerEntry,
+	ejectElement,
+	elementToSpecifics,
+	getElementDataAttributes,
+	getPreviousSibling,
+	hasMarks,
+	hasParentOfType,
+	isElementType,
+	permissivelyDeserializeNodes,
+	removeMarks,
+	serializeNodes,
+	strictlyDeserializeNodes,
+	textToSpecifics,
+	toLatestFormat,
+	topLevelNodes,
+}
+
+export * from './createEditor'

package/src/editor/methods/addMarks.ts

@@ -0,0 +1,10 @@
+import { Editor as SlateEditor, Editor, Text as SlateText } from 'slate'
+import { TextSpecifics } from '../../types/editor'
+
+export const addMarks = <T extends SlateText, E extends SlateEditor>(editor: E, marks: TextSpecifics<T>) => {
+	Editor.withoutNormalizing(editor, () => {
+		for (const mark in marks) {
+			Editor.addMark(editor, mark, (marks as any)[mark])
+		}
+	})
+}

package/src/editor/methods/canToggleMark.ts

@@ -0,0 +1,9 @@
+import { Editor as SlateEditor, Text as SlateText } from 'slate'
+
+export const canToggleMark = <T extends SlateText, E extends SlateEditor>(
+	editor: E,
+	markName: string,
+	markValue: unknown = true,
+) => {
+	return editor.canToggleMarks({ [markName]: markValue })
+}