@thomasfosterau/effect-richtext 0.0.0-stage → 0.1.0

package/dist/extensions/editor.js

@@ -0,0 +1,271 @@
+import { fromHTMLUnsafe } from "../html.js";
+import { attempt } from "../internal/attempt.js";
+import { DocSchema } from "../model/schema.js";
+import { Fragment } from "../model/fragment.js";
+import { isModelError } from "../model/errors.js";
+import { Mark } from "../model/mark.js";
+import { Node } from "../model/node.js";
+import { EditorState, runSyncUnsafe } from "../state/state.js";
+import { StateError, isStateFailure } from "../state/errors.js";
+import { EditorView } from "../view/view.js";
+import { flatten, resolvePlugins } from "./extension.js";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+// src/extensions/editor.ts
+/**
+* The `Editor`: an editor state, an optional view, and typed commands
+* and builders, created from an extension.
+*
+* @since 0.1.0
+*/
+/**
+* An editor state seen by chained commands. It shares one transaction
+* between all commands in a chain: its `doc`, `selection` and stored
+* marks are the transaction's current ones, and its `tr` is the shared
+* transaction itself. Plugin state is that of the state the chain
+* started from.
+*
+* @internal
+*/
+var ChainableState = class extends EditorState {
+	constructor(base, chainTr) {
+		super(base.config, base.slots);
+		this.chainTr = chainTr;
+	}
+	get doc() {
+		return this.chainTr.doc;
+	}
+	get selection() {
+		return this.chainTr.selection;
+	}
+	get storedMarksOrNull() {
+		return this.chainTr.storedMarksOrNull;
+	}
+	get tr() {
+		return this.chainTr;
+	}
+};
+const foldInto = (target, tr) => {
+	if (tr === target) return;
+	if (!tr.before.eq(target.doc)) throw new StateError({ message: "A chained command dispatched a transaction that doesn't match the chain" });
+	for (const step of tr.steps) target.stepUnsafe(step);
+	if (tr.selectionSet) target.setSelectionUnsafe(tr.selection.map(target.doc, target.mapping.slice(target.steps.length)));
+	if (tr.storedMarksSet) target.setStoredMarks(tr.storedMarksOrNull);
+	if (tr.scrolledIntoView) target.scrollIntoView();
+	const meta = tr.meta;
+	for (const key in meta) target.setMeta(key, meta[key]);
+};
+const isPlainObject = (u) => {
+	if (u === null || typeof u !== "object" || Array.isArray(u)) return false;
+	const proto = Object.getPrototypeOf(u);
+	return proto === Object.prototype || proto === null;
+};
+const dieOnStateFailure = (effect) => Effect.catchIf(effect, isStateFailure, (e) => Effect.die(e));
+/**
+* @since 0.1.0
+* @category symbols
+*/
+const EditorTypeId = Symbol.for("effect-richtext/extensions/Editor");
+/**
+* An editor created from an extension by `createEditor`. It owns the
+* current `EditorState`, and, while mounted, an `EditorView` (which then
+* holds the current state).
+*
+* @since 0.1.0
+* @category models
+*/
+var Editor = class {
+	/** @internal */
+	constructor(schema, state, creators) {
+		this.schema = schema;
+		this._view = void 0;
+		this._state = state;
+		this.creators = creators;
+		const nodes = {};
+		for (const name in schema.nodes) nodes[name] = this.nodeBuilder(name);
+		this.nodes = nodes;
+		const marks = {};
+		for (const name in schema.marks) marks[name] = (attrs) => schema.markUnsafe(name, attrs);
+		this.marks = marks;
+		const commands = {};
+		for (const name in creators) commands[name] = (...args) => Effect.suspend(() => this.runCommand(creators[name](...args), true));
+		this.commands = commands;
+	}
+	/** The current editor state (the view's state while mounted). */
+	get state() {
+		return this._view ? this._view.state : this._state;
+	}
+	/** The view, while the editor is mounted. */
+	get view() {
+		return Option.fromUndefinedOr(this._view);
+	}
+	/** Whether the editor is currently mounted. */
+	get mounted() {
+		return this._view !== void 0;
+	}
+	/**
+	* Mount the editor: create an `EditorView` (with `EditorView.make`)
+	* for the current state in `place`. The view is destroyed, and the
+	* editor unmounted, when the scope closes (or on `unmount`). Mounting
+	* an already mounted editor first unmounts it.
+	*/
+	mount(place, props) {
+		return Effect.gen({ self: this }, function* () {
+			yield* this.unmount;
+			const view = yield* EditorView.make(place, {
+				...props,
+				state: this.state
+			});
+			this._view = view;
+			yield* Effect.addFinalizer(() => Effect.sync(() => this.detach(view)));
+		});
+	}
+	/** Destroy the view, if mounted. The editor keeps the view's last state. */
+	get unmount() {
+		return Effect.sync(() => {
+			const view = this._view;
+			if (view) {
+				this.detach(view);
+				view.destroy();
+			}
+		});
+	}
+	detach(view) {
+		if (this._view !== view) return;
+		this._state = view.state;
+		this._view = void 0;
+	}
+	/**
+	* Dispatch a transaction: through the view when mounted (honouring its
+	* `dispatchTransaction` prop), otherwise by applying it to the
+	* editor's state. Fails with the plugins' errors.
+	*/
+	dispatch(tr) {
+		return Effect.suspend(() => {
+			const view = this._view;
+			if (view) return dieOnStateFailure(view.tryDispatch(tr));
+			return dieOnStateFailure(Effect.map(this._state.apply(tr), (state) => {
+				this._state = state;
+			}));
+		});
+	}
+	runCommand(command, dispatching) {
+		if (!dispatching) return command(this.state, void 0, this._view);
+		return Effect.flatMap(Effect.context(), (context) => {
+			const dispatch = (tr) => Effect.provideContext(this.dispatch(tr), context);
+			return command(this.state, dispatch, this._view);
+		});
+	}
+	/** Check whether commands apply to the current state, without dispatching. */
+	can() {
+		const result = {};
+		for (const name in this.creators) result[name] = (...args) => Effect.suspend(() => this.runCommand(this.creators[name](...args), false));
+		return result;
+	}
+	/**
+	* Queue commands to apply them in a single transaction. Each command
+	* sees the document, selection and stored marks produced by the
+	* previous ones (through a state whose `tr` is the shared
+	* transaction). `run()` runs every queued command, then dispatches
+	* the transaction (when any command changed it), and succeeds with
+	* `true` when all commands applied.
+	*/
+	chain() {
+		const queue = [];
+		const chain = {};
+		for (const name in this.creators) {
+			if (name === "run") continue;
+			chain[name] = (...args) => {
+				queue.push(this.creators[name](...args));
+				return chain;
+			};
+		}
+		chain.run = () => Effect.gen({ self: this }, function* () {
+			const state = this.state;
+			const tr = state.tr;
+			const chained = new ChainableState(state, tr);
+			const dispatch = (t) => Effect.sync(() => foldInto(tr, t));
+			let all = true;
+			for (const command of queue) if (!(yield* command(chained, dispatch, this._view))) all = false;
+			if (tr.docChanged || tr.selectionSet || tr.storedMarksSet || tr.scrolledIntoView || !tr.isGeneric) yield* this.dispatch(tr);
+			return all;
+		});
+		return chain;
+	}
+	/**
+	* Replace the document's content (through a transaction, so plugins
+	* like the history see it). Accepts a node, its JSON, or HTML.
+	*/
+	setContent(content) {
+		return Effect.flatMap(attempt(() => parseContent(this.schema, content), isModelError), (doc) => Effect.suspend(() => {
+			const tr = this.state.tr;
+			tr.replaceWithUnsafe(0, tr.doc.content.size, doc.content);
+			return this.dispatch(tr);
+		}));
+	}
+	/** The current document as JSON. */
+	getDocJSON() {
+		return this.state.doc.toJSON();
+	}
+	/** Create a text node with the given marks. Throws for empty strings. */
+	text(text, ...marks) {
+		return this.schema.textUnsafe(text, marks.length ? Mark.setFrom(marks) : null);
+	}
+	nodeBuilder(name) {
+		const type = this.schema.nodes[name];
+		return (...args) => {
+			let attrs = null;
+			if (args.length && (args[0] === null || isPlainObject(args[0]))) attrs = args.shift();
+			const children = [];
+			const add = (child) => {
+				if (typeof child === "string") {
+					if (child) children.push(this.schema.textUnsafe(child));
+				} else if (Array.isArray(child)) child.forEach(add);
+				else if (child instanceof Fragment) child.forEach((n) => children.push(n));
+				else if (child instanceof Node) children.push(child);
+				else throw new TypeError("Invalid child passed to a node builder: " + String(child));
+			};
+			args.forEach(add);
+			return type.createCheckedUnsafe(attrs, children);
+		};
+	}
+};
+const parseContent = (schema, content) => {
+	if (content instanceof Node) return content.type.schema === schema ? content : schema.nodeFromJSONUnsafe(content.toJSON());
+	if (typeof content === "string") return fromHTMLUnsafe(schema, content);
+	return schema.nodeFromJSONUnsafe(content);
+};
+/**
+* Create an editor from an extension: builds the schema from the merged
+* node and mark specs (ordered by priority, then declaration), resolves
+* the plugins (keymaps included, same order) and creates the initial
+* state. The editor isn't mounted; see `Editor.mount`.
+*
+* @since 0.1.0
+* @category constructors
+*/
+const createEditor = (extension, options = {}) => Effect.gen(function* () {
+	const flat = flatten(extension);
+	const schema = yield* DocSchema.make({
+		nodes: flat.nodes,
+		marks: flat.marks
+	});
+	const plugins = resolvePlugins(flat.plugins, schema);
+	const doc = options.doc === void 0 ? void 0 : yield* attempt(() => parseContent(schema, options.doc), isModelError);
+	const config = {
+		schema,
+		doc,
+		selection: doc && options.selection ? options.selection(doc) : void 0,
+		plugins
+	};
+	return new Editor(schema, yield* EditorState.create(config), flat.commands);
+});
+/**
+* Like `createEditor`, but runs synchronously and throws failures. Only
+* available for extensions that require no services.
+*
+* @since 0.1.0
+* @category constructors
+*/
+const createEditorUnsafe = (extension, options = {}) => runSyncUnsafe(createEditor(extension, options));
+export { Editor, EditorTypeId, createEditor, createEditorUnsafe };

package/dist/extensions/extension.d.ts

@@ -0,0 +1,375 @@
+import { AnySchema, MarkSpec, MarkSpecs, NodeSpec, NodeSpecs } from "../model/schema.js";
+import "../keymap.js";
+import { Command } from "../state/transaction.js";
+import { AnyPlugin, Plugin } from "../state/plugin.js";
+import "../model.js";
+import { Bindings, BindingsError, BindingsRequirements } from "../keymap/keymap.js";
+import "../state.js";
+import * as Effect from "effect/Effect";
+/**
+ * Extension priorities. Within a merged extension, facets with a higher
+ * priority come first: their node and mark specs come earlier in the
+ * schema (which matters for the default node of a group and for parse
+ * rule precedence), their plugins and keymaps come earlier in the
+ * plugin list (so their key bindings and props take precedence), and
+ * their commands win over commands with the same name. Facets with the
+ * same priority keep their declaration order.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export declare const Priority: {
+  readonly lowest: 0;
+  readonly low: 1;
+  readonly default: 2;
+  readonly high: 3;
+  readonly highest: 4;
+};
+/**
+ * @since 0.1.0
+ * @category models
+ */
+export type Priority = (typeof Priority)[keyof typeof Priority];
+/**
+ * A command whose argument types depend on the final (merged) schema,
+ * described as a type lambda: `this["Schema"]` is the editor's schema
+ * and `this["Return"]` the type the call returns (an Effect for
+ * `editor.commands`, the chain for `editor.chain()`).
+ *
+ * ```ts skip-type-checking
+ * interface ToggleMark extends CommandSignature {
+ *   readonly signature: <M extends MarkNames<this["Schema"]>>(mark: M) => this["Return"]
+ * }
+ * ```
+ *
+ * @since 0.1.0
+ * @category type-level
+ */
+export interface CommandSignature {
+  readonly Schema: unknown;
+  readonly Return: unknown;
+  readonly signature: (...args: any) => unknown;
+}
+/**
+ * The type-level description of a command: its argument tuple, or a
+ * `CommandSignature` for schema-dependent commands.
+ *
+ * @since 0.1.0
+ * @category type-level
+ */
+export type CommandType = ReadonlyArray<any> | CommandSignature;
+/**
+ * @since 0.1.0
+ * @category type-level
+ */
+export interface CommandTypes {
+  readonly [name: string]: CommandType;
+}
+/**
+ * What an extension contributes at the type level: node specs, mark
+ * specs, commands (name to argument types), and the errors (`E`) and
+ * requirements (`R`) of its plugins and commands.
+ *
+ * @since 0.1.0
+ * @category type-level
+ */
+export interface ExtensionTypes {
+  readonly nodes: NodeSpecs;
+  readonly marks: MarkSpecs;
+  readonly commands: CommandTypes;
+  readonly E: unknown;
+  readonly R: unknown;
+}
+/**
+ * The types of an extension that contributes nothing.
+ *
+ * @since 0.1.0
+ * @category type-level
+ */
+export interface EmptyTypes {
+  readonly nodes: {};
+  readonly marks: {};
+  readonly commands: {};
+  readonly E: never;
+  readonly R: never;
+}
+type Simplify<A> = { [K in keyof A]: A[K]; } & {};
+type Cast<A, B> = A extends B ? A : never;
+type UnionToIntersection<U> = (U extends any ? (u: U) => void : never) extends ((i: infer I) => void) ? I : never;
+/**
+ * Merge a union of extension types: node, mark and command records are
+ * intersected, `E` and `R` are unions.
+ *
+ * @since 0.1.0
+ * @category type-level
+ */
+export type MergeTypes<T extends ExtensionTypes> = {
+  readonly nodes: Cast<Simplify<UnionToIntersection<T["nodes"]>>, NodeSpecs>;
+  readonly marks: Cast<Simplify<UnionToIntersection<T["marks"]>>, MarkSpecs>;
+  readonly commands: Cast<Simplify<UnionToIntersection<T["commands"]>>, CommandTypes>;
+  readonly E: T["E"];
+  readonly R: T["R"];
+};
+/**
+ * The types of an extension.
+ *
+ * @since 0.1.0
+ * @category type-level
+ */
+export type TypesOf<X> = X extends Extension<infer T> ? T : never;
+/**
+ * The node specs contributed by an extension.
+ *
+ * @since 0.1.0
+ * @category type-level
+ */
+export type ExtensionNodes<X> = TypesOf<X>["nodes"];
+/**
+ * The mark specs contributed by an extension.
+ *
+ * @since 0.1.0
+ * @category type-level
+ */
+export type ExtensionMarks<X> = TypesOf<X>["marks"];
+/**
+ * The commands contributed by an extension.
+ *
+ * @since 0.1.0
+ * @category type-level
+ */
+export type ExtensionCommands<X> = TypesOf<X>["commands"];
+/**
+ * Creates a command from its arguments.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export type CommandCreator = (...args: any) => Command<any, any, any>;
+/**
+ * @since 0.1.0
+ * @category models
+ */
+export interface CommandCreators {
+  readonly [name: string]: CommandCreator;
+}
+/**
+ * A plugin, a list of plugins, or a function creating them from the
+ * editor's schema.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export type PluginInput = AnyPlugin | ReadonlyArray<AnyPlugin> | ((schema: AnySchema) => AnyPlugin | ReadonlyArray<AnyPlugin>);
+/**
+ * The contents of a single extension, as given to `defineExtension`.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface ExtensionSpec {
+  readonly nodes?: NodeSpecs | undefined;
+  readonly marks?: MarkSpecs | undefined;
+  readonly plugins?: ReadonlyArray<PluginInput> | undefined;
+  readonly keymap?: Bindings | undefined;
+  readonly commands?: CommandCreators | undefined;
+}
+/**
+ * @since 0.1.0
+ * @category symbols
+ */
+export declare const ExtensionTypeId: unique symbol;
+/**
+ * @since 0.1.0
+ * @category symbols
+ */
+export type ExtensionTypeId = typeof ExtensionTypeId;
+/**
+ * An extension: a tree of facets (node and mark specs, plugins,
+ * keymaps and commands), each with an optional priority. `T` records,
+ * at the type level, what the extension contributes. Extensions are
+ * immutable values; combine them with `union` and turn them into an
+ * editor with `createEditor`.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export declare class Extension<out T extends ExtensionTypes = EmptyTypes> {
+  /** @internal */
+  readonly spec: ExtensionSpec | undefined;
+  /** @internal */
+  readonly children: ReadonlyArray<AnyExtension>;
+  /** @internal */
+  readonly priority: Priority | undefined;
+  readonly [ExtensionTypeId]: {
+    readonly _T: (_: never) => T;
+  };
+  /** @internal */
+  constructor(
+  /** @internal */
+  spec: ExtensionSpec | undefined,
+  /** @internal */
+  children: ReadonlyArray<AnyExtension>,
+  /** @internal */
+  priority: Priority | undefined);
+}
+/**
+ * Any extension.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export type AnyExtension = Extension<any>;
+/**
+ * Whether a value is an `Extension`.
+ *
+ * @since 0.1.0
+ * @category guards
+ */
+export declare const isExtension: (u: unknown) => u is AnyExtension;
+type PluginInputE<P> = P extends ((...args: any) => infer X) ? PluginInputE<X> : P extends ReadonlyArray<infer X> ? PluginInputE<X> : P extends Plugin<any, any, infer E, any> ? E : never;
+type PluginInputR<P> = P extends ((...args: any) => infer X) ? PluginInputR<X> : P extends ReadonlyArray<infer X> ? PluginInputR<X> : P extends Plugin<any, any, any, infer R> ? R : never;
+type CreatorE<C> = C extends ((...args: any) => (...args: any) => Effect.Effect<any, infer E, any>) ? E : never;
+type CreatorR<C> = C extends ((...args: any) => (...args: any) => Effect.Effect<any, any, infer R>) ? R : never;
+/**
+ * The command types of a set of command creators: their argument
+ * tuples.
+ *
+ * @since 0.1.0
+ * @category type-level
+ */
+export type CommandArgsOf<C extends CommandCreators> = { readonly [K in keyof C]: Parameters<C[K]>; };
+/**
+ * The errors of a set of command creators' commands.
+ *
+ * @since 0.1.0
+ * @category type-level
+ */
+export type CommandsError<C extends CommandCreators> = { [K in keyof C]: CreatorE<C[K]>; }[keyof C];
+/**
+ * The requirements of a set of command creators' commands.
+ *
+ * @since 0.1.0
+ * @category type-level
+ */
+export type CommandsRequirements<C extends CommandCreators> = { [K in keyof C]: CreatorR<C[K]>; }[keyof C];
+/**
+ * The extension types described by an `ExtensionSpec`.
+ *
+ * @since 0.1.0
+ * @category type-level
+ */
+export interface SpecTypes<N extends NodeSpecs, M extends MarkSpecs, P extends ReadonlyArray<PluginInput>, B extends Bindings, C extends CommandCreators> {
+  readonly nodes: N;
+  readonly marks: M;
+  readonly commands: CommandArgsOf<C>;
+  readonly E: PluginInputE<P[number]> | BindingsError<B> | CommandsError<C>;
+  readonly R: PluginInputR<P[number]> | BindingsRequirements<B> | CommandsRequirements<C>;
+}
+/**
+ * Define an extension from node and mark specs, plugins, a keymap and
+ * commands. Every field is optional; the types of all of them are
+ * recorded in the extension's type.
+ *
+ * ```ts skip-type-checking
+ * const bold = defineExtension({
+ *   marks: { strong: { parseDOM: [{ tag: "strong" }], toDOM: () => ["strong", 0] } },
+ *   commands: { toggleBold: () => (state, dispatch) => toggleMark(state.schema.marks.strong!)(state, dispatch) },
+ *   keymap: { "Mod-b": (state, dispatch) => toggleMark(state.schema.marks.strong!)(state, dispatch) }
+ * })
+ * ```
+ *
+ * Throws a `KeymapError` when a key name in `keymap` is invalid.
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export declare const defineExtension: <const N extends NodeSpecs = {}, const M extends MarkSpecs = {}, const P extends ReadonlyArray<PluginInput> = readonly [], const B extends Bindings = {}, const C extends CommandCreators = {}>(spec: {
+  readonly nodes?: N | undefined;
+  readonly marks?: M | undefined;
+  readonly plugins?: P | undefined;
+  readonly keymap?: B | undefined;
+  readonly commands?: C | undefined;
+}) => Extension<SpecTypes<N, M, P, B, C>>;
+/**
+ * Merge extensions. The result contributes everything its parts
+ * contribute: node, mark and command types are intersected, `E` and `R`
+ * are unions. At runtime facets are ordered by priority, then by
+ * declaration order (depth first); including the same extension value
+ * more than once only uses its first occurrence.
+ *
+ * @since 0.1.0
+ * @category combinators
+ */
+export declare const union: <const Exts extends ReadonlyArray<AnyExtension>>(...extensions: Exts) => Extension<MergeTypes<TypesOf<Exts[number]>>>;
+/**
+ * Give an extension (and every part of it that doesn't set its own
+ * priority) a priority.
+ *
+ * @since 0.1.0
+ * @category combinators
+ */
+export declare const withPriority: <T extends ExtensionTypes>(extension: Extension<T>, priority: Priority) => Extension<T>;
+/**
+ * Define an extension adding a single node spec.
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export declare const defineNodeSpec: <const Name extends string, const Spec extends NodeSpec>(name: Name, spec: Spec) => Extension<SpecTypes<{ readonly [K in Name]: Spec; }, {}, readonly [], {}, {}>>;
+/**
+ * Define an extension adding a single mark spec.
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export declare const defineMarkSpec: <const Name extends string, const Spec extends MarkSpec>(name: Name, spec: Spec) => Extension<SpecTypes<{}, { readonly [K in Name]: Spec; }, readonly [], {}, {}>>;
+/**
+ * Define an extension adding plugins: a plugin, an array of plugins, or
+ * a function creating them from the editor's schema.
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export declare const definePlugin: <const P extends PluginInput>(plugin: P) => Extension<SpecTypes<{}, {}, readonly [P], {}, {}>>;
+/**
+ * Define an extension adding a keymap (see `keymap`). Throws a
+ * `KeymapError` when a key name is invalid or bound twice.
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export declare const defineKeymap: <const B extends Bindings>(bindings: B) => Extension<SpecTypes<{}, {}, readonly [], B, {}>>;
+/**
+ * Define an extension adding commands. Each command is given as a
+ * function from the command's arguments to a `Command`; the argument
+ * types become part of the editor's `commands`, `can()` and `chain()`
+ * APIs.
+ *
+ * ```ts skip-type-checking
+ * const ext = defineCommands({
+ *   insertHello: (times: number) => (state, dispatch) => ...
+ * })
+ * ```
+ *
+ * For commands whose argument types depend on the final schema, declare
+ * a `CommandSignature` and cast the extension (see `CommandsExtension`).
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export declare const defineCommands: <const C extends CommandCreators>(commands: C) => Extension<SpecTypes<{}, {}, readonly [], {}, C>>;
+/**
+ * The type of an extension that only contributes commands, described
+ * by command types (argument tuples or `CommandSignature`s).
+ *
+ * @since 0.1.0
+ * @category type-level
+ */
+export type CommandsExtension<C extends CommandTypes, E = never, R = never> = Extension<{
+  readonly nodes: {};
+  readonly marks: {};
+  readonly commands: C;
+  readonly E: E;
+  readonly R: R;
+}>;
+export {};