@witchcraft/editor 0.0.6 → 0.0.8

package/src/runtime/pm/generator.ts

@@ -0,0 +1,266 @@
+import { faker } from "@faker-js/faker"
+import type { Mark, Node } from "@tiptap/pm/model"
+import { nanoid } from "nanoid"
+import { builders } from "prosemirror-test-builder"
+
+import { schema } from "./schema.js"
+
+export const pm = builders(schema)
+
+export type GeneratorConfigEntry<
+	TChildrenType extends "node" | "text" = "node" | "text",
+	TParentType extends "node" | "text" = "node" | "text",
+	TChildren extends TChildrenType extends "node" ? Node : Mark | string = TChildrenType extends "node" ? Node : Mark | string,
+	TParent extends TParentType extends "node" ? Node : Mark | string = TParentType extends "node" ? Node : Mark | string
+> = {
+	parents: {
+		/**
+		 * The type of the parent (node or "text") where "text" is a string or mark.
+		 * Determines the call signature of the create function.
+		 */
+		type: TParentType
+		/** Possible parent nodes that can have the given children. The children need not be direct descendants, see `ignoreValidation`. */
+		names: string[]
+	}
+	children: {
+		/**
+		 * The type of children (node or "text") where "text" is a string or mark.
+		 * Determines the call signature of the create function.
+		 */
+		type: TChildrenType
+		/* Children types to generate. */
+		names?: string[]
+	}
+	/**
+	 * Set to true to ignore all children mismatches, or set an array of children names to ignore.
+	 *
+	 * This is needed for creating "end" nodes that aren't valid names (e.g. `text` is not technically allowed since you can't do `builder.text()`).
+	 *
+	 * Or when the children are not direct children of the parent types as there is some in-between wrapper node that needs to be generated.
+	 */
+	ignoreValidation?: boolean | string[]
+	/* Whether the parent listed is the root node. */
+	isRoot?: boolean
+	/**
+	 * Creates the node. Can return undefined to "terminate" the branch being created, the node will be filtered out of the nodes passed to it's parent.
+	 *
+	 * If not set, a default `builder[parentType]({}, ...children)` will be used.
+	 *
+	 * Note also, it is not required to use the children. You can ignore them or use a subset or create a different one if needed (some node types *require* text and if your text not can return "" this can be a problem).
+	 */
+	create?: (parent: string, children: TChildren[]) => TParent | undefined
+}
+
+export function getTextOrMarkLength(textOrMark: string | Mark) {
+	if (typeof textOrMark === "string") {
+		return textOrMark.length
+	}
+	const textNodes = (textOrMark as any).flat.map((_: any) => "text" in _ ? _.text.length : getTextOrMarkLength(_ as any)) as number[]
+	return textNodes.reduce((a, b) => a + b, 0)
+}
+
+export function createGeneratorConfig<
+	TChildrenType extends "node" | "text" = "node" | "text",
+	TParentType extends "node" | "text" = "node" | "text",
+	TChildren extends TChildrenType extends "node" ? Node : Mark | string = TChildrenType extends "node" ? Node : Mark | string,
+	TParent extends TParentType extends "node" ? Node : Mark | string = TParentType extends "node" ? Node : Mark | string
+>(
+	config: GeneratorConfigEntry<TChildrenType, TParentType, TChildren, TParent>
+): GeneratorConfigEntry<TChildrenType, TParentType, TChildren, TParent> {
+	return config
+}
+
+function createPsuedoSentence() {
+	// sentence generated with string.sample (which contains all possible chars) instead of lorem.sentence
+	const sentenceLength = faker.number.int({ min: 0, max: 1000 })
+	const sentence = Array.from(
+		{ length: sentenceLength },
+		() => faker.string.sample({ min: 0, max: 1000 })
+	).join(" ")
+	return sentence
+}
+
+export const generatorConfig = [
+	createGeneratorConfig({
+		isRoot: true,
+		parents: { type: "node", names: ["doc"] },
+		ignoreValidation: true,
+		children: { type: "node", names: ["item"] },
+		create: (_parent, children) => {
+			if (!children || children.length === 0) {
+				return pm.doc(pm.list(pm.item({ blockId: nanoid(10) }, pm.paragraph({}, ""))))
+			}
+			return pm.doc(pm.list(...children))
+		}
+	}),
+	createGeneratorConfig({
+		parents: { type: "node", names: ["list"] },
+		children: { type: "node", names: ["item"] },
+		create: (_parent, children) => {
+			if (!children || children.length === 0) {
+				return pm.list(pm.item({ blockId: nanoid(10) }, pm.paragraph("")))
+			}
+			return pm.list(...children)
+		}
+	}),
+	createGeneratorConfig({
+		parents: { type: "node", names: ["item"] },
+		children: { type: "node", names: [
+			"paragraph",
+			"heading",
+			"codeBlock",
+			"embeddedDoc",
+			"iframe",
+			"table",
+			"image",
+			"blockquote"
+		] },
+		create: (_parent, children) => {
+			if (!children || children.length === 0) {
+				return pm.item({ blockId: nanoid(10) }, pm.paragraph(""))
+			}
+			return pm.item(
+				{ blockId: nanoid(10) },
+				children[0]!,
+				...(children.length > 1
+					? [pm.list({},
+							...children.slice(1).map(_ =>
+								pm.item({ blockId: nanoid(10) }, _)
+							)
+						)]
+					: []
+				) as any
+			)
+		}
+	}),
+	createGeneratorConfig({
+		parents: { type: "node", names: ["blockquote"] },
+		children: { type: "node", names: ["paragraph", "cite"] },
+		create: (_parent, children) => {
+			const parTypes = []
+			const citeTypes = []
+			for (const child of children) {
+				if (child.type.name === "cite") {
+					citeTypes.push(child)
+				} else {
+					parTypes.push(child)
+				}
+			}
+			if (parTypes.length === 0) {
+				return pm.blockquote({}, pm.paragraph(""))
+			} else {
+				const someCite = citeTypes.find(_ => _.textContent.length > 0) ?? pm.cite({}, createPsuedoSentence())
+				return pm.blockquote({}, ...parTypes, someCite)
+			}
+		}
+	}),
+	createGeneratorConfig({
+		parents: { type: "node", names: ["table"] },
+		children: { type: "node", names: [
+			"tableHeader",
+			"tableCell"
+		] },
+		ignoreValidation: true, // we're handling the in-between tableRow nodes
+		create: (_parent, children) => {
+			const headerType = []
+			const cellType = []
+
+			for (const child of children) {
+				if (child.type.name === "tableHeader") {
+					headerType.push(child)
+				} else if (child.type.name === "tableCell") {
+					cellType.push(child)
+				}
+			}
+			const colNum = headerType.length
+
+			if (colNum === 0) {
+				return pm.table({}, pm.tableRow({}, pm.tableCell(pm.paragraph(""))))
+			}
+			const rowCount = Math.ceil(cellType.length / colNum)
+			const rows: Node[] = []
+			for (let i = 0; i < rowCount; i++) {
+				rows.push(pm.tableRow({}, ...cellType.slice(i * colNum, (i + 1) * colNum)))
+			}
+
+			return pm.table({}, pm.tableRow({}, ...headerType), ...rows)
+		}
+	}),
+	createGeneratorConfig({
+		parents: { type: "node", names: ["tableHeader", "tableCell"] },
+		children: { type: "node", names: ["paragraph"] },
+		create: (_parent, children) => {
+			if (!children || children.length === 0) {
+				return pm.tableCell(pm.paragraph(""))
+			}
+			return pm.tableCell(...children.slice(0, 1))
+		}
+	}),
+	createGeneratorConfig({
+		parents: { type: "node", names: ["paragraph", "heading", "codeBlock", "cite", "heading"] },
+		children: { type: "text", names: [
+			"bold",
+			"italic",
+			"underline",
+			"strike",
+			"subscript",
+			"superscript",
+			"code",
+			"link"
+		] },
+		create(parent, children) {
+			if (parent === "heading") {
+				return pm[parent]({ level: 1 }, ...children as any)
+			}
+			if (parent === "cite") {
+				// citation must have SOME text
+				return pm[parent]({}, faker.lorem.sentence())
+			}
+			if (parent === "paragraph") {
+				const someIndex = faker.number.int({ min: 0, max: children.length })
+				children.splice(someIndex, 0, pm.hardBreak() as any)
+			}
+
+			return pm[parent]({}, ...children as any)
+		}
+	}),
+	createGeneratorConfig({
+		parents: { type: "text", names: [
+			"bold",
+			"italic",
+			"underline",
+			"strike",
+			"subscript",
+			"superscript",
+			"link"
+		]
+		},
+		// note the addition of text
+		children: { type: "text", names: [
+			"bold",
+			"italic",
+			"underline",
+			"strike",
+			"subscript",
+			"superscript",
+			"link",
+			"text"
+		] },
+		ignoreValidation: ["text"] // text is not a real node
+		// create: (parent, children) => {
+		// 	return pm[parent]({}, ...children as any) as any
+		// }
+	}),
+	createGeneratorConfig({
+		ignoreValidation: true, // text is not a real node
+		parents: { type: "text", names: ["code"] },
+		children: { type: "text", names: ["text"] }
+	}),
+	createGeneratorConfig({
+		parents: { type: "text", names: ["text"] },
+		children: { type: "text" },
+		create: _parent => {
+			return createPsuedoSentence()
+		}
+	})
+]

package/src/runtime/pm/schema.ts

@@ -126,3 +126,4 @@ const _schema = getSchema(extensions) as Schema<
 	| MarkHighlightName
 >
 export const schema = _schema
+

package/src/runtime/pm/utils/generateRandomDoc.ts

@@ -0,0 +1,140 @@
+import { unreachable } from "@alanscodelog/utils/unreachable"
+import { faker } from "@faker-js/faker"
+import type { Mark, MarkType, Node } from "@tiptap/pm/model"
+import type { builders } from "prosemirror-test-builder"
+
+import { generateRandomTree } from "./generateRandomTree.js"
+
+import type { GeneratorConfigEntry } from "../generator.js"
+import { generatorConfig } from "../generator.js"
+
+/**
+ * Generates a random doc using faker js.
+ *
+ * A config describing how to create the doc is required. One is available under `pm/generator`.
+ *
+ * @experimental
+ */
+export function generateRandomDoc<
+	TBuilder extends ReturnType<typeof builders>,
+	TData extends string
+>(
+	builder: TBuilder,
+	config: GeneratorConfigEntry<any, any, any, any>[] = generatorConfig,
+	treeOptions?: Parameters<typeof generateRandomTree>[1],
+	{
+		checkAfterNodeCreation = false
+	}: {
+		/**
+		 * Checks if every returned node is valid for debugging invalid generator configs.
+		 *
+		 * A check is always done on the root node at the end regardless of this option.
+		 *
+		 * It is very slow (each check, rechecks children).
+		 *
+		 * @default false
+		 */
+		checkAfterNodeCreation?: boolean
+	} = {}
+): Node {
+	const schema = builder.schema
+
+	const map: Record<string, GeneratorConfigEntry<any, any, any, any>> = {}
+	function schemaFilter(name: string) {
+		return name !== "text" && name !== schema.topNodeType.name
+	}
+
+	for (const entry of config) {
+		for (const node of entry.parents.names) {
+			if (node === "") throw new Error(`Empty node name ""`)
+			const type = entry.parents.type === "node" ? schema.nodes[node] : schema.marks[node]
+			if (type === undefined && node !== "text") {
+				throw new Error(`${node} (on entry of type ${entry.parents.type}) not found in schema. Valid names are ${Object.keys(entry.parents.type === "node" ? schema.nodes : schema.marks)}`)
+			}
+
+			for (const node of entry.parents.names) {
+				const subEntry = { ...entry }
+				if (entry.ignoreValidation === undefined || entry.ignoreValidation !== true) {
+					const childrenToValidate = (entry.children.names ?? []).filter(_ => !Array.isArray(entry.ignoreValidation) || !entry.ignoreValidation.includes(_))
+					for (const child of childrenToValidate) {
+						if (child === "") throw new Error(`Empty node name ""`)
+						if (entry.children.type === "node") {
+							const childType = schema.nodes[child]
+							const possibleNames = [childType.name, ...((childType.spec.group ?? "").split(" ").filter(e => e !== ""))]
+							const isAllowedChild = type.spec.content && possibleNames.some(n => type.spec.content!.includes(n))
+							// we don't use contentMatch.matchType because
+							// it can give false negatives when the content expression
+							// has multiple types like type1+ type2+,
+							// it will only return true for type1 in those cases
+							if (!(isAllowedChild && schemaFilter(childType.name))) {
+								throw new Error(`Node ${node} cannot contain child of type ${child}`)
+							}
+						} else {
+							const childType = schema.marks[child]
+							if (entry.parents.type === "node") {
+								// not sure why this is returning false when it shouldn't (e.g. paragraph can't contain bold)
+								// if (!(type as NodeType).allowsMarkType(childType)) {
+								// 	throw new Error(`Node ${node} cannot contain mark child of type ${child}`)
+								// }
+							} else {
+								const possibleNames = [childType.name, ...((childType.spec.group ?? "").split(" ").filter(e => e !== ""))]
+								const t = type as MarkType
+								const isExcluded = t.spec.excludes !== undefined
+									&& possibleNames.some(n => {
+										// _ this means exclude everything in prosemirror
+										return t.spec.excludes!.includes(n)
+											|| t.spec.excludes!.includes("_")
+									})
+								if (isExcluded) {
+									throw new Error(`Mark ${node} cannot contain mark child of type ${child}`)
+								}
+							}
+						}
+					}
+				}
+				map[node] = { ...subEntry }
+			}
+		}
+	}
+
+
+	const children = generateRandomTree<Node | Mark | string, TData>({
+		parentData: (data?: TData): TData => {
+			if (data === "") return "" as TData
+			if (!data) unreachable()
+			if (!map[data] || !map[data].children.names || map[data].children.names.length === 0) {
+				// we must prematurely end the branch as the node can contain no children
+				return "" as TData
+			} else {
+				const picked = faker.helpers.arrayElement(map[data].children.names)
+				return picked as TData
+			}
+		},
+		createNode: (children, _isLeaf, data): Node | Mark | string | undefined => {
+			if (data === "") return undefined
+			if (!data) unreachable()
+			const type = schema.nodes[data]
+			// type allows no children or isn't configured to generate children
+			if (!type) return undefined
+
+			const parent = map[data]?.create?.(data, children as any)
+				?? builder[data]({}, ...children as any)
+
+			if (checkAfterNodeCreation) {
+				;(parent as any)?.check?.()
+			}
+
+			return parent
+		}
+	}, {
+		...treeOptions,
+		initialData: schema.topNodeType.name as TData
+	})
+
+	const doc = map[schema.topNodeType.name]?.create?.(schema.topNodeType.name as any, children as any)
+		?? builder[schema.topNodeType.name]({}, ...children as any)
+
+	;(doc as any).check?.()
+	return doc as Node
+}
+

package/src/runtime/pm/utils/generateRandomTree.ts

@@ -0,0 +1,100 @@
+import { faker } from "@faker-js/faker"
+/**
+ * Generates a random tree structure where the probability of generating children
+ * decreases linearly with depth, resulting in a tree that is bushy at the top
+ * and sparse towards the maximum depth.
+ *
+ * This function is agnostic to the actual node structure, relying on the caller-provided
+ * callbacks to create and link nodes.
+ *
+ * It uses faker.js for randomness (even on the option parameters).
+ *
+ * See {@link generateRandomDoc} for an example of how to use it.
+ *
+ * @experimental
+ */
+export function generateRandomTree<T, TData>(
+	{
+		createNode,
+		parentData
+	}: {
+		/** A function that creates a new node (type T) given its depth. */
+		createNode: (children: T[], isLeaf: boolean, parentData?: TData) => T | undefined
+		/**
+		 * A function that is called before creating a a node or it's children whose result is passed to both. This allows creating children that will be compatible with the parent (via this same function, it is passed it's parent).
+		 *
+		 * For example, we could randomly generate a parent type. It's then passed both to the children, to limit the types of children nodes, and to the parent so it can actually create it.
+		 */
+		parentData?: (parentData?: TData) => TData
+	},
+	{
+		rootNodes: rootNodes = faker.number.int({ min: 0, max: 5 }),
+		depth = faker.number.int({ min: 0, max: 5 }),
+		minChildren = 0,
+		maxInitialChildren = 10,
+		initialData
+	}: {
+		/**
+		 * The exact number of nodes at depth 0.
+		 *
+		 * @default faker.number.int({ min: 0, max: 5 })
+		 */
+		rootNodes?: number
+		/**
+		 * The maximum depth of the tree (0-indexed). Nodes at this depth will have 0 children.
+		 *
+		 * @default faker.number.int({ min: 0, max: 5 })
+		 */
+		depth?: number
+		/**
+		 * The absolute minimum number of children any node can have.
+		 *
+		 * @default 0
+		 */
+		minChildren?: number
+		/**
+		 * The maximum children a node can have at depth 0. This value scales down as depth increases.
+		 *
+		 * @default 10
+		 */
+		maxInitialChildren?: number
+		initialData?: TData
+	} = {}
+): T[] {
+	const generateChildren = (currentDepth: number, childCount: number, pData?: TData): T[] => {
+		const res: T[] = []
+		for (let i = 0; i < childCount; i++) {
+			const numChildren = calculateNumChildren(depth, currentDepth, minChildren, maxInitialChildren)
+
+			const data = parentData?.(pData) ?? undefined
+			const parent = createNode(
+				generateChildren(currentDepth + 1, numChildren, data),
+				numChildren === 0,
+				data
+			)
+			if (parent === undefined) continue
+			res.push(parent)
+		}
+		return res
+	}
+
+	return generateChildren(0, rootNodes, initialData)
+}
+
+function calculateNumChildren(
+	depth: number,
+	currentDepth: number,
+	minChildren: number,
+	maxInitialChildren: number
+): number {
+	const decayFactor = depth > 0 ? (depth - currentDepth) / depth : 0
+	const maxAtDepth = minChildren + (maxInitialChildren - minChildren) * decayFactor
+	const maxChildrenAtDepth = Math.max(minChildren, Math.floor(maxAtDepth))
+
+	let numChildren = 0
+
+	if (currentDepth < depth) {
+		numChildren = faker.number.int({ min: minChildren, max: maxChildrenAtDepth })
+	}
+	return numChildren
+}