@thomasfosterau/effect-richtext 0.0.0 → 0.1.0

package/dist/extensions/defaults.js

@@ -0,0 +1,209 @@
+import { baseKeymap } from "../commands/keymaps.js";
+import { deleteSelection, joinBackward, joinDown, joinForward, joinUp, lift, selectAll, selectParentNode, setBlockType, splitBlock, toggleMark, wrapIn } from "../commands/commands.js";
+import { history, redo, undo } from "../history.js";
+import { oneOrMore, seq, zeroOrMore } from "../model/content.js";
+import { marks, nodes } from "../schema-basic.js";
+import { liftListItem, sinkListItem, splitListItem, wrapInList } from "../schema-list/commands.js";
+import { addListNodes } from "../schema-list.js";
+import { Priority, defineCommands, defineKeymap, defineMarkSpec, defineNodeSpec, definePlugin, union, withPriority } from "./extension.js";
+import * as Effect from "effect/Effect";
+// src/extensions/defaults.ts
+/**
+* Ready-made extensions wrapping the core modules: base schema nodes
+* and marks, base commands and keymap, history and lists.
+*
+* @since 0.1.0
+*/
+const succeedFalse = Effect.succeed(false);
+const byNodeName = (name, f) => (state, dispatch, view) => {
+	const type = state.schema.nodes[name];
+	return type ? f(type)(state, dispatch, view) : succeedFalse;
+};
+/**
+* The top-level `doc` node, containing one or more `block` nodes.
+*
+* @since 0.1.0
+* @category nodes
+*/
+const defineDoc = () => defineNodeSpec("doc", { content: oneOrMore("block") });
+/**
+* The `text` node (in the `inline` group).
+*
+* @since 0.1.0
+* @category nodes
+*/
+const defineText = () => defineNodeSpec("text", { group: "inline" });
+/**
+* The `paragraph` node (`<p>`). It has the highest priority, so that it
+* is the first (and thus default) node of the `block` group.
+*
+* @since 0.1.0
+* @category nodes
+*/
+const defineParagraph = () => withPriority(defineNodeSpec("paragraph", nodes.paragraph), Priority.highest);
+/**
+* The `heading` node, with a `level` attribute (`<h1>`–`<h6>`).
+*
+* @since 0.1.0
+* @category nodes
+*/
+const defineHeading = () => defineNodeSpec("heading", nodes.heading);
+/**
+* The `blockquote` node.
+*
+* @since 0.1.0
+* @category nodes
+*/
+const defineBlockquote = () => defineNodeSpec("blockquote", nodes.blockquote);
+/**
+* The `horizontal_rule` node.
+*
+* @since 0.1.0
+* @category nodes
+*/
+const defineHorizontalRule = () => defineNodeSpec("horizontal_rule", nodes.horizontal_rule);
+/**
+* The `code_block` node.
+*
+* @since 0.1.0
+* @category nodes
+*/
+const defineCodeBlock = () => defineNodeSpec("code_block", nodes.code_block);
+/**
+* The inline `image` node.
+*
+* @since 0.1.0
+* @category nodes
+*/
+const defineImage = () => defineNodeSpec("image", nodes.image);
+/**
+* The inline `hard_break` node.
+*
+* @since 0.1.0
+* @category nodes
+*/
+const defineHardBreak = () => defineNodeSpec("hard_break", nodes.hard_break);
+/**
+* The `link` mark.
+*
+* @since 0.1.0
+* @category marks
+*/
+const defineLink = () => defineMarkSpec("link", marks.link);
+/**
+* The `em` mark.
+*
+* @since 0.1.0
+* @category marks
+*/
+const defineEm = () => defineMarkSpec("em", marks.em);
+/**
+* The `strong` mark.
+*
+* @since 0.1.0
+* @category marks
+*/
+const defineStrong = () => defineMarkSpec("strong", marks.strong);
+/**
+* The `code` mark.
+*
+* @since 0.1.0
+* @category marks
+*/
+const defineCode = () => defineMarkSpec("code", marks.code);
+const insertNode = (type, attrs) => (state, dispatch) => Effect.suspend(() => {
+	const { $from } = state.selection;
+	let applies = false;
+	for (let d = $from.depth; d >= 0 && !applies; d--) {
+		const index = $from.index(d);
+		applies = $from.node(d).canReplaceWith(index, index, type);
+	}
+	const node = applies ? type.createAndFillOrNull(attrs) : null;
+	if (!node) return succeedFalse;
+	return dispatch ? Effect.as(dispatch(state.tr.replaceSelectionWith(node).scrollIntoView()), true) : Effect.succeed(true);
+});
+/**
+* Commands wrapping the core editing commands. Node and mark types are
+* referenced by name and typed against the editor's final schema:
+* `editor.commands.toggleMark("strong")` only type-checks when the
+* schema has a `strong` mark. Commands referring to a type the schema
+* doesn't have don't apply.
+*
+* @since 0.1.0
+* @category commands
+*/
+const defineBaseCommands = () => defineCommands({
+	toggleMark: (name, attrs, options) => (state, dispatch, view) => {
+		const type = state.schema.marks[name];
+		return type ? toggleMark(type, attrs ?? null, options)(state, dispatch, view) : succeedFalse;
+	},
+	setBlockType: (name, attrs) => byNodeName(name, (type) => setBlockType(type, attrs ?? null)),
+	wrapIn: (name, attrs) => byNodeName(name, (type) => wrapIn(type, attrs ?? null)),
+	insertNode: (name, attrs) => byNodeName(name, (type) => insertNode(type, attrs ?? null)),
+	insertText: (text, from, to) => (state, dispatch) => Effect.suspend(() => dispatch ? Effect.as(dispatch(state.tr.insertTextUnsafe(text, from, to).scrollIntoView()), true) : Effect.succeed(true)),
+	deleteSelection: () => deleteSelection,
+	selectAll: () => selectAll,
+	selectParentNode: () => selectParentNode,
+	joinUp: () => joinUp,
+	joinDown: () => joinDown,
+	joinBackward: () => joinBackward,
+	joinForward: () => joinForward,
+	lift: () => lift,
+	splitBlock: () => splitBlock
+});
+/**
+* The platform's base keymap (`baseKeymap` from `@thomasfosterau/effect-richtext/commands`:
+* Enter, Backspace, Delete, Mod-a, …), at low priority so that other
+* keymaps take precedence.
+*
+* @since 0.1.0
+* @category keymaps
+*/
+const defineBaseKeymap = () => withPriority(defineKeymap(baseKeymap), Priority.low);
+/**
+* Undo history: the `history` plugin, `undo`/`redo` commands, and
+* **Mod-z** (undo), **Mod-y** and **Shift-Mod-z** (redo) bindings.
+* Include it at most once per editor (the history plugin is keyed).
+*
+* @since 0.1.0
+* @category history
+*/
+const defineHistory = (options) => union(definePlugin(history(options)), defineKeymap({
+	"Mod-z": undo,
+	"Mod-y": redo,
+	"Shift-Mod-z": redo
+}), defineCommands({
+	undo: () => undo,
+	redo: () => redo
+}));
+const listNodes = addListNodes({}, seq("paragraph", zeroOrMore("block")), "block");
+const listItemCommand = (f) => byNodeName("list_item", f);
+/**
+* Lists: the `ordered_list`, `bullet_list` (both in the `block` group)
+* and `list_item` (`paragraph block*`) nodes, the list commands
+* (`wrapInList(name, attrs?)`, `splitListItem`, `liftListItem`,
+* `sinkListItem`), and **Enter** (split item), **Mod-[** (lift) and
+* **Mod-]** (sink) bindings.
+*
+* @since 0.1.0
+* @category lists
+*/
+const defineList = () => union(defineNodeSpec("ordered_list", listNodes.ordered_list), defineNodeSpec("bullet_list", listNodes.bullet_list), defineNodeSpec("list_item", listNodes.list_item), defineKeymap({
+	Enter: listItemCommand(splitListItem),
+	"Mod-[": listItemCommand(liftListItem),
+	"Mod-]": listItemCommand(sinkListItem)
+}), defineCommands({
+	wrapInList: (name, attrs) => byNodeName(name, (type) => wrapInList(type, attrs ?? null)),
+	splitListItem: () => listItemCommand(splitListItem),
+	liftListItem: () => listItemCommand(liftListItem),
+	sinkListItem: () => listItemCommand(sinkListItem)
+}));
+/**
+* Everything above: the nodes and marks of `@thomasfosterau/effect-richtext/schema-basic`,
+* lists, base commands, the base keymap and history.
+*
+* @since 0.1.0
+* @category basic
+*/
+const defineBasicExtension = (options) => union(defineDoc(), defineText(), defineParagraph(), defineHeading(), defineBlockquote(), defineHorizontalRule(), defineCodeBlock(), defineImage(), defineHardBreak(), defineLink(), defineEm(), defineStrong(), defineCode(), defineList(), defineBaseCommands(), defineBaseKeymap(), defineHistory(options?.history));
+export { defineBaseCommands, defineBaseKeymap, defineBasicExtension, defineBlockquote, defineCode, defineCodeBlock, defineDoc, defineEm, defineHardBreak, defineHeading, defineHistory, defineHorizontalRule, defineImage, defineLink, defineList, defineParagraph, defineStrong, defineText };

package/dist/extensions/editor.d.ts

@@ -0,0 +1,246 @@
+import { ModelError, SchemaDefinitionError } from "../model/errors.js";
+import { AttrsOptional, ChildNames, DocSchema, MarkAttrsInput, MarkNames, MarkSpecOf, NodeAttrsInput, NodeNames, NodeSpecOf } from "../model/schema.js";
+import { Mark } from "../model/mark.js";
+import { Node, NodeJSON, TextNode } from "../model/node.js";
+import "../model.js";
+import { StateFailure } from "../state/errors.js";
+import { DirectEditorProps, EditorView, ViewPlace } from "../view/view.js";
+import { Transaction } from "../state/transaction.js";
+import { Selection } from "../state/selection.js";
+import { EditorState } from "../state/state.js";
+import "../state.js";
+import "../view.js";
+import { CommandCreator, CommandSignature, CommandType, Extension, ExtensionTypes } from "./extension.js";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Scope from "effect/Scope";
+/**
+ * The schema of an editor built from an extension with types `T`.
+ *
+ * @since 0.1.0
+ * @category type-level
+ */
+export type SchemaOf<T extends ExtensionTypes> = DocSchema<T["nodes"], T["marks"]>;
+/**
+ * The function type of a command, given its command type, the schema
+ * and what calling it returns.
+ *
+ * @since 0.1.0
+ * @category type-level
+ */
+export type CommandFn<C extends CommandType, Sc, Ret> = C extends CommandSignature ? (C & {
+  readonly Schema: Sc;
+  readonly Return: Ret;
+})["signature"] : C extends ReadonlyArray<any> ? (...args: C) => Ret : never;
+/**
+ * `editor.commands`: runs a command against the editor's current state
+ * (and view, when mounted), dispatching its transaction.
+ *
+ * @since 0.1.0
+ * @category type-level
+ */
+export type EditorCommands<T extends ExtensionTypes> = { readonly [K in keyof T["commands"]]: CommandFn<T["commands"][K], SchemaOf<T>, Effect.Effect<boolean, T["E"], T["R"]>>; };
+/**
+ * `editor.can()`: checks whether a command applies, without dispatching.
+ *
+ * @since 0.1.0
+ * @category type-level
+ */
+export type CanCommands<T extends ExtensionTypes> = EditorCommands<T>;
+/**
+ * `editor.chain()`: queues commands, which are all applied to a single
+ * transaction by `run()`.
+ *
+ * @since 0.1.0
+ * @category type-level
+ */
+export type ChainedCommands<T extends ExtensionTypes> = { readonly [K in keyof T["commands"]]: CommandFn<T["commands"][K], SchemaOf<T>, ChainedCommands<T>>; } & ChainRun<T>;
+/**
+ * @since 0.1.0
+ * @category type-level
+ */
+export interface ChainRun<T extends ExtensionTypes> {
+  /**
+   * Run the queued commands into one transaction and dispatch it.
+   * Succeeds with `true` when every command applied.
+   */
+  readonly run: () => Effect.Effect<boolean, T["E"], T["R"]>;
+}
+/**
+ * A child accepted by a node builder: a node allowed by the node's
+ * content expression, or a string (for text) when text is allowed.
+ *
+ * @since 0.1.0
+ * @category type-level
+ */
+export type NodeChild<Sc, N extends string> = Node<Sc & DocSchema<any, any>, ChildNames<Sc, N> & NodeNames<Sc>> | ("text" extends ChildNames<Sc, N> ? string : never) | ReadonlyArray<Node<Sc & DocSchema<any, any>, ChildNames<Sc, N> & NodeNames<Sc>>>;
+/**
+ * A node builder (`editor.nodes.<name>`). The attributes may be omitted
+ * when they all have defaults.
+ *
+ * @since 0.1.0
+ * @category type-level
+ */
+export type NodeBuilder<Sc extends DocSchema<any, any>, N extends NodeNames<Sc>> = [keyof NodeAttrsInput<Sc, N>] extends [never] ? {
+  (attrs: null, ...children: ReadonlyArray<NodeChild<Sc, N>>): Node<Sc, N>;
+  (...children: ReadonlyArray<NodeChild<Sc, N>>): Node<Sc, N>;
+} : AttrsOptional<NodeSpecOf<Sc, N>> extends true ? {
+  (attrs?: NodeAttrsInput<Sc, N> | null, ...children: ReadonlyArray<NodeChild<Sc, N>>): Node<Sc, N>;
+  (...children: ReadonlyArray<NodeChild<Sc, N>>): Node<Sc, N>;
+} : (attrs: NodeAttrsInput<Sc, N>, ...children: ReadonlyArray<NodeChild<Sc, N>>) => Node<Sc, N>;
+/**
+ * A mark builder (`editor.marks.<name>`).
+ *
+ * @since 0.1.0
+ * @category type-level
+ */
+export type MarkBuilder<Sc extends DocSchema<any, any>, M extends MarkNames<Sc>> = AttrsOptional<MarkSpecOf<Sc, M>> extends true ? (attrs?: MarkAttrsInput<Sc, M> | null) => Mark<Sc, M> : (attrs: MarkAttrsInput<Sc, M>) => Mark<Sc, M>;
+/**
+ * @since 0.1.0
+ * @category type-level
+ */
+export type NodeBuilders<Sc extends DocSchema<any, any>> = { readonly [N in NodeNames<Sc>]: NodeBuilder<Sc, N>; };
+/**
+ * @since 0.1.0
+ * @category type-level
+ */
+export type MarkBuilders<Sc extends DocSchema<any, any>> = { readonly [M in MarkNames<Sc>]: MarkBuilder<Sc, M>; };
+/**
+ * Content accepted by `createEditor` and `setContent`: a document node,
+ * its JSON representation, or an HTML string (parsed with the schema's
+ * parse rules; needs a DOM `document`).
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export type EditorContent<Sc extends DocSchema<any, any>> = Node<Sc> | NodeJSON | string;
+/**
+ * Options for `createEditor`.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface EditorOptions<Sc extends DocSchema<any, any>> {
+  /** The initial document. Defaults to an empty document. */
+  readonly doc?: EditorContent<Sc> | undefined;
+  /** The initial selection. Defaults to the start of the document. */
+  readonly selection?: ((doc: Node<Sc>) => Selection<Sc>) | undefined;
+}
+/**
+ * The errors `createEditor` can fail with besides those of the
+ * extension's plugins: invalid specs (`SchemaDefinitionError`), invalid
+ * initial content (`ModelError`), or a state that can't be created.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export type CreateEditorError = SchemaDefinitionError | ModelError | StateFailure;
+/**
+ * Options for `Editor.mount`: the view's props, without `state`.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export type MountProps<Sc extends DocSchema<any, any>, R, E> = Omit<DirectEditorProps<Sc, R, E>, "state">;
+/**
+ * @since 0.1.0
+ * @category symbols
+ */
+export declare const EditorTypeId: unique symbol;
+/**
+ * @since 0.1.0
+ * @category symbols
+ */
+export type EditorTypeId = typeof EditorTypeId;
+/**
+ * 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
+ */
+export declare class Editor<T extends ExtensionTypes> {
+  /** The editor's schema, built from the extension's node and mark specs. */
+  readonly schema: SchemaOf<T>;
+  readonly [EditorTypeId]: {
+    readonly _T: (_: never) => T;
+  };
+  private _state;
+  private _view;
+  private readonly creators;
+  /** Typed node builders: `editor.nodes.heading({ level: 2 }, "Title")`. Throw on invalid content. */
+  readonly nodes: NodeBuilders<SchemaOf<T>>;
+  /** Typed mark builders: `editor.marks.link({ href })`. Throw on invalid attributes. */
+  readonly marks: MarkBuilders<SchemaOf<T>>;
+  /** The editor's commands. */
+  readonly commands: EditorCommands<T>;
+  /** @internal */
+  constructor(
+  /** The editor's schema, built from the extension's node and mark specs. */
+  schema: SchemaOf<T>, state: EditorState<SchemaOf<T>, T["R"], T["E"]>, creators: Record<string, CommandCreator>);
+  /** The current editor state (the view's state while mounted). */
+  get state(): EditorState<SchemaOf<T>, T["R"], T["E"]>;
+  /** The view, while the editor is mounted. */
+  get view(): Option.Option<EditorView<SchemaOf<T>, T["R"], T["E"]>>;
+  /** Whether the editor is currently mounted. */
+  get mounted(): boolean;
+  /**
+   * 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: ViewPlace, props?: MountProps<SchemaOf<T>, T["R"], T["E"]>): Effect.Effect<void, never, Scope.Scope | T["R"]>;
+  /** Destroy the view, if mounted. The editor keeps the view's last state. */
+  get unmount(): Effect.Effect<void>;
+  private detach;
+  /**
+   * 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: Transaction<SchemaOf<T>>): Effect.Effect<void, T["E"], T["R"]>;
+  private runCommand;
+  /** Check whether commands apply to the current state, without dispatching. */
+  can(): CanCommands<T>;
+  /**
+   * 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(): ChainedCommands<T>;
+  /**
+   * Replace the document's content (through a transaction, so plugins
+   * like the history see it). Accepts a node, its JSON, or HTML.
+   */
+  setContent(content: EditorContent<SchemaOf<T>>): Effect.Effect<void, ModelError | T["E"], T["R"]>;
+  /** The current document as JSON. */
+  getDocJSON(): NodeJSON;
+  /** Create a text node with the given marks. Throws for empty strings. */
+  text(text: string, ...marks: ReadonlyArray<Mark<SchemaOf<T>>>): TextNode<SchemaOf<T>>;
+  private nodeBuilder;
+}
+/**
+ * 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
+ */
+export declare const createEditor: <T extends ExtensionTypes>(extension: Extension<T>, options?: EditorOptions<SchemaOf<T>>) => Effect.Effect<Editor<T>, CreateEditorError | T["E"], T["R"]>;
+/**
+ * Like `createEditor`, but runs synchronously and throws failures. Only
+ * available for extensions that require no services.
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export declare const createEditorUnsafe: <T extends ExtensionTypes & {
+  readonly R: never;
+}>(extension: Extension<T>, options?: EditorOptions<SchemaOf<T>>) => Editor<T>;