@thomasfosterau/effect-richtext 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,48 @@
+MIT License
+
+Copyright (c) 2026 Thomas Foster
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+Portions of this software (the document model, transforms, editor state,
+view, keymap, commands and related modules, and their test suites) are
+derived from ProseMirror (https://prosemirror.net), which is distributed under
+the following license:
+
+Copyright (C) 2015-2017 by Marijn Haverbeke <marijn@haverbeke.berlin> and others
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -1,3 +1,119 @@
-# Temporary Holding Version
+# @thomasfosterau/effect-richtext
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A reimplementation of the core [ProseMirror](https://prosemirror.net) toolkit (`prosemirror-model`, `-transform`, `-state`, `-view`, `-keymap`, `-commands`) on top of [Effect](https://effect.website) 4, in a single package.
+
+- **Strongly typed documents.** Node and mark names are literal types, attributes are described with Effect `Schema`s, and content expressions are typed combinators, so the schema knows which children each node accepts: `doc` built from a `text` node is a compile error, as are a node built without one of its required attributes and a spec that refers to a node or mark it does not define, and `node.is("heading")` narrows `node.attrs` to `{ level: number }`.
+- **Effect everywhere.** Every fallible operation returns an `Effect` with tagged errors (`PositionError`, `ReplaceError`, `StepError`, …). Each also has a synchronous `…Unsafe` twin for hot paths. Absent values are `Option`s.
+- **Typed plugin requirements.** Plugins, commands and view props may return Effects that need services; those requirements (`R`) and errors (`E`) are tracked through `EditorState` and `EditorView`, and provided with ordinary Effect layers. The view is created in a `Scope` and destroyed with it.
+- **Faithful port.** ProseMirror's own test suites are ported and pass (model, transform, state, commands, keymap, history, markdown, and all of prosemirror-view's browser tests in real Chromium).
+- **Nice-to-haves**, all additive and unopinionated: extensions with typed `editor.commands` / `editor.chain()` / `editor.can()`, input rules, gap and drop cursors, placeholders, undo history, reactive bindings (`SubscriptionRef`/`Stream`), HTML and Markdown serializers.
+
+See [`DESIGN.md`](https://github.com/thomasfosterau/effect-richtext/blob/trunk/DESIGN.md) for the design decisions and conventions.
+
+> Status: experimental (0.x). APIs may change.
+
+## Install
+
+```sh
+pnpm add @thomasfosterau/effect-richtext effect
+```
+
+`effect` (4.x) is a peer dependency: your application provides the single copy. The package is ESM-only and has no `.` entry; import the modules you use by subpath.
+
+## Modules
+
+| Module                                         | Ported from / purpose                                        |
+| ---------------------------------------------- | ------------------------------------------------------------ |
+| `@thomasfosterau/effect-richtext/model`        | prosemirror-model (incl. DOM parser/serializer, JSON codecs) |
+| `@thomasfosterau/effect-richtext/transform`    | prosemirror-transform                                        |
+| `@thomasfosterau/effect-richtext/state`        | prosemirror-state                                            |
+| `@thomasfosterau/effect-richtext/view`         | prosemirror-view                                             |
+| `@thomasfosterau/effect-richtext/view-css`     | prosemirror-view's stylesheet                                |
+| `@thomasfosterau/effect-richtext/keymap`       | prosemirror-keymap                                           |
+| `@thomasfosterau/effect-richtext/commands`     | prosemirror-commands                                         |
+| `@thomasfosterau/effect-richtext/history`      | prosemirror-history                                          |
+| `@thomasfosterau/effect-richtext/inputrules`   | prosemirror-inputrules                                       |
+| `@thomasfosterau/effect-richtext/gapcursor`    | prosemirror-gapcursor                                        |
+| `@thomasfosterau/effect-richtext/dropcursor`   | prosemirror-dropcursor                                       |
+| `@thomasfosterau/effect-richtext/schema-basic` | prosemirror-schema-basic                                     |
+| `@thomasfosterau/effect-richtext/schema-list`  | prosemirror-schema-list                                      |
+| `@thomasfosterau/effect-richtext/markdown`     | prosemirror-markdown                                         |
+| `@thomasfosterau/effect-richtext/test-builder` | prosemirror-test-builder                                     |
+| `@thomasfosterau/effect-richtext/html`         | HTML string helpers                                          |
+| `@thomasfosterau/effect-richtext/placeholder`  | placeholder decorations                                      |
+| `@thomasfosterau/effect-richtext/reactive`     | `SubscriptionRef`/`Stream` bindings                          |
+| `@thomasfosterau/effect-richtext/extensions`   | composable, typed extensions and chainable commands          |
+| `@thomasfosterau/effect-richtext/compat/*`     | ProseMirror-compatible facade API                            |
+
+## Example
+
+```ts
+import { Effect, Schema } from "effect"
+import { baseKeymap, toggleMark } from "@thomasfosterau/effect-richtext/commands"
+import { history, redo, undo } from "@thomasfosterau/effect-richtext/history"
+import { keymap } from "@thomasfosterau/effect-richtext/keymap"
+import { Content, DocSchema } from "@thomasfosterau/effect-richtext/model"
+import { EditorState } from "@thomasfosterau/effect-richtext/state"
+import { EditorView } from "@thomasfosterau/effect-richtext/view"
+
+const schema = DocSchema.makeUnsafe({
+  nodes: {
+    doc: { content: Content.oneOrMore("block") },
+    paragraph: { group: "block", content: Content.zeroOrMore("text"), toDOM: () => ["p", 0] },
+    heading: {
+      group: "block",
+      content: Content.zeroOrMore("text"),
+      attrs: { level: { schema: Schema.Literals([1, 2, 3]), default: 1 } },
+      toDOM: (node) => ["h" + node.attrs.level, 0]
+    },
+    text: {}
+  },
+  marks: { strong: { toDOM: () => ["strong", 0] } }
+})
+
+const mountEditor = Effect.fn("mountEditor")(function* (place: HTMLElement) {
+  const state = yield* EditorState.create({
+    schema,
+    plugins: [
+      history(),
+      keymap({ "Mod-z": undo, "Mod-y": redo, "Mod-b": toggleMark(schema.marks.strong) }),
+      keymap(baseKeymap)
+    ]
+  })
+  const view = yield* EditorView.make(place, { state })
+  yield* view.dispatch(view.state.tr.insertTextUnsafe("Hello"))
+  // ...the view is destroyed when the scope closes
+})
+
+Effect.runFork(Effect.scoped(Effect.andThen(mountEditor(document.body), Effect.never)))
+```
+
+With `@thomasfosterau/effect-richtext/extensions`, the same editor is:
+
+```ts
+import { Effect } from "effect"
+import { createEditor, defineBasicExtension } from "@thomasfosterau/effect-richtext/extensions"
+
+const mountBasicEditor = Effect.fn("mountBasicEditor")(function* (place: HTMLElement) {
+  const editor = yield* createEditor(defineBasicExtension())
+  yield* editor.mount(place)
+  yield* editor.chain().setBlockType("heading", { level: 2 }).toggleMark("strong").run()
+})
+```
+
+## Development
+
+Contributor setup, hooks and single checks are in [CONTRIBUTING.md](https://github.com/thomasfosterau/effect-richtext/blob/trunk/CONTRIBUTING.md); the gates every change runs are in [AGENTS.md](https://github.com/thomasfosterau/effect-richtext/blob/trunk/AGENTS.md#verification). In short, with pnpm 11:
+
+```sh
+pnpm install
+vp check              # format + lint
+vp run check          # type gate (src + tests, including type-level tests)
+vp run test:unit      # node tests
+vp run test:browser   # prosemirror-view's suites in Chromium
+vp run build          # dist/
+```
+
+## License
+
+MIT. Portions are derived from ProseMirror, © Marijn Haverbeke and others (MIT); see [`LICENSE`](https://github.com/thomasfosterau/effect-richtext/blob/trunk/LICENSE).

package/dist/_virtual/_rolldown/runtime.js

@@ -0,0 +1,12 @@
+// \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+export { __exportAll };

package/dist/commands/commands.d.ts

@@ -0,0 +1,323 @@
+import { ResolvedPos } from "../model/resolvedpos.js";
+import { AnySchema, MarkAttrsInput, MarkNames, MarkType, NodeAttrsInput, NodeNames, NodeType } from "../model/schema.js";
+import { Node } from "../model/node.js";
+import "../model.js";
+import { NodeTypeWithAttrs } from "../transform/structure.js";
+import "../state.js";
+import { Command } from "../state/transaction.js";
+import { EditorState } from "../state/state.js";
+import "../transform.js";
+import * as Effect from "effect/Effect";
+/**
+ * A text direction or vertical direction, as passed to
+ * `TextblockBoundaryView.endOfTextblock`.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export type TextblockBoundaryDirection = "up" | "down" | "left" | "right" | "forward" | "backward";
+/**
+ * The part of an editor view used by commands that need accurate
+ * (bidi-aware) detection of textblock boundaries (`joinBackward`,
+ * `joinForward`, `selectNodeBackward`, `selectNodeForward`, …). When
+ * the view passed to such a command doesn't implement this interface,
+ * the command falls back to checking the cursor's offset in its parent.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface TextblockBoundaryView {
+  /**
+   * Whether the selection (in the given state, or the view's current
+   * state) is at the end of its textblock in the given direction.
+   */
+  readonly endOfTextblock: (dir: TextblockBoundaryDirection, state?: EditorState<any, any, any>) => boolean;
+}
+/**
+ * Check whether a view implements `TextblockBoundaryView`.
+ *
+ * @since 0.1.0
+ * @category guards
+ */
+export declare const isTextblockBoundaryView: (view: unknown) => view is TextblockBoundaryView;
+/**
+ * Delete the selection, if there is one.
+ *
+ * @since 0.1.0
+ * @category commands
+ */
+export declare const deleteSelection: Command;
+/**
+ * If the selection is empty and at the start of a textblock, try to
+ * reduce the distance between that block and the one before it—if
+ * there's a block directly before it that can be joined, join them.
+ * If not, try to move the selected block closer to the next one in
+ * the document structure by lifting it out of its parent or moving it
+ * into a parent of the previous block. Will use the view for accurate
+ * (bidi-aware) start-of-textblock detection if given (see
+ * `TextblockBoundaryView`).
+ *
+ * @since 0.1.0
+ * @category commands
+ */
+export declare const joinBackward: Command;
+/**
+ * A more limited form of `joinBackward` that only tries to join the
+ * current textblock to the one before it, if the cursor is at the start
+ * of a textblock.
+ *
+ * @since 0.1.0
+ * @category commands
+ */
+export declare const joinTextblockBackward: Command;
+/**
+ * A more limited form of `joinForward` that only tries to join the
+ * current textblock to the one after it, if the cursor is at the end of
+ * a textblock.
+ *
+ * @since 0.1.0
+ * @category commands
+ */
+export declare const joinTextblockForward: Command;
+/**
+ * When the selection is empty and at the start of a textblock, select
+ * the node before that textblock, if possible. This is intended to be
+ * bound to keys like backspace, after `joinBackward` or other deleting
+ * commands, as a fall-back behavior when the schema doesn't allow
+ * deletion at the selected point.
+ *
+ * @since 0.1.0
+ * @category commands
+ */
+export declare const selectNodeBackward: Command;
+/**
+ * If the selection is empty and the cursor is at the end of a
+ * textblock, try to reduce or remove the boundary between that block
+ * and the one after it, either by joining them or by moving the other
+ * block closer to this one in the tree structure. Will use the view for
+ * accurate start-of-textblock detection if given.
+ *
+ * @since 0.1.0
+ * @category commands
+ */
+export declare const joinForward: Command;
+/**
+ * When the selection is empty and at the end of a textblock, select the
+ * node coming after that textblock, if possible. This is intended to be
+ * bound to keys like delete, after `joinForward` and similar deleting
+ * commands, to provide a fall-back behavior when the schema doesn't
+ * allow deletion at the selected point.
+ *
+ * @since 0.1.0
+ * @category commands
+ */
+export declare const selectNodeForward: Command;
+/**
+ * Join the selected block or, if there is a text selection, the closest
+ * ancestor block of the selection that can be joined, with the sibling
+ * above it.
+ *
+ * @since 0.1.0
+ * @category commands
+ */
+export declare const joinUp: Command;
+/**
+ * Join the selected block, or the closest ancestor of the selection
+ * that can be joined, with the sibling after it.
+ *
+ * @since 0.1.0
+ * @category commands
+ */
+export declare const joinDown: Command;
+/**
+ * Lift the selected block, or the closest ancestor block of the
+ * selection that can be lifted, out of its parent node.
+ *
+ * @since 0.1.0
+ * @category commands
+ */
+export declare const lift: Command;
+/**
+ * If the selection is in a node whose type has a truthy `code` property
+ * in its spec, replace the selection with a newline character.
+ *
+ * @since 0.1.0
+ * @category commands
+ */
+export declare const newlineInCode: Command;
+/**
+ * When the selection is in a node with a truthy `code` property in its
+ * spec, create a default block after the code block, and move the
+ * cursor there.
+ *
+ * @since 0.1.0
+ * @category commands
+ */
+export declare const exitCode: Command;
+/**
+ * If a block node is selected, create an empty paragraph before (if it
+ * is its parent's first child) or after it.
+ *
+ * @since 0.1.0
+ * @category commands
+ */
+export declare const createParagraphNear: Command;
+/**
+ * If the cursor is in an empty textblock that can be lifted, lift the
+ * block.
+ *
+ * @since 0.1.0
+ * @category commands
+ */
+export declare const liftEmptyBlock: Command;
+/**
+ * A function that determines the type of the block split off by
+ * `splitBlockAs`, given the parent node of the selection end, whether
+ * the split happens at the end of that node, and the selection start.
+ * Returning `null` (or `undefined`) uses the default behavior.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export type SplitNodeType<Sc extends AnySchema = AnySchema> = (node: Node<Sc>, atEnd: boolean, $from: ResolvedPos<Sc>) => NodeTypeWithAttrs<Sc> | null | undefined;
+/**
+ * Create a variant of `splitBlock` that uses a custom function to
+ * determine the type of the newly split off block.
+ *
+ * @since 0.1.0
+ * @category commands
+ */
+export declare const splitBlockAs: <Sc extends AnySchema = AnySchema>(splitNode?: SplitNodeType<Sc>) => Command<Sc>;
+/**
+ * Split the parent block of the selection. If the selection is a text
+ * selection, also delete its content.
+ *
+ * @since 0.1.0
+ * @category commands
+ */
+export declare const splitBlock: Command;
+/**
+ * Acts like `splitBlock`, but without resetting the set of active marks
+ * at the cursor.
+ *
+ * @since 0.1.0
+ * @category commands
+ */
+export declare const splitBlockKeepMarks: Command;
+/**
+ * Move the selection to the node wrapping the current selection, if
+ * any. (Will not select the document node.)
+ *
+ * @since 0.1.0
+ * @category commands
+ */
+export declare const selectParentNode: Command;
+/**
+ * Select the whole document.
+ *
+ * @since 0.1.0
+ * @category commands
+ */
+export declare const selectAll: Command;
+/**
+ * Moves the cursor to the start of current text block.
+ *
+ * @since 0.1.0
+ * @category commands
+ */
+export declare const selectTextblockStart: Command;
+/**
+ * Moves the cursor to the end of current text block.
+ *
+ * @since 0.1.0
+ * @category commands
+ */
+export declare const selectTextblockEnd: Command;
+/**
+ * Wrap the selection in a node of the given type with the given
+ * attributes.
+ *
+ * @since 0.1.0
+ * @category commands
+ */
+export declare const wrapIn: <Sc extends AnySchema, N extends NodeNames<Sc>>(nodeType: NodeType<Sc, N>, attrs?: NodeAttrsInput<Sc, N> | null) => Command<Sc>;
+/**
+ * Returns a command that tries to set the selected textblocks to the
+ * given node type with the given attributes.
+ *
+ * @since 0.1.0
+ * @category commands
+ */
+export declare const setBlockType: <Sc extends AnySchema, N extends NodeNames<Sc>>(nodeType: NodeType<Sc, N>, attrs?: NodeAttrsInput<Sc, N> | null) => Command<Sc>;
+/**
+ * Options for `toggleMark`.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface ToggleMarkOptions {
+  /**
+   * Controls whether, when part of the selected range has the mark
+   * already and part doesn't, the mark is removed (`true`, the default)
+   * or added (`false`).
+   */
+  readonly removeWhenPresent?: boolean | undefined;
+  /**
+   * When set to false, this will prevent the command from acting on the
+   * content of inline nodes marked as atoms that are completely covered
+   * by a selection range.
+   */
+  readonly enterInlineAtoms?: boolean | undefined;
+  /**
+   * By default, this command doesn't apply to leading and trailing
+   * whitespace in the selection. Set this to `true` to change that.
+   */
+  readonly includeWhitespace?: boolean | undefined;
+}
+/**
+ * Create a command function that toggles the given mark with the given
+ * attributes. Will return `false` when the current selection doesn't
+ * support that mark. This will remove the mark if any marks of that
+ * type exist in the selection, or add it otherwise. If the selection is
+ * empty, this applies to the stored marks instead of a range of the
+ * document.
+ *
+ * @since 0.1.0
+ * @category commands
+ */
+export declare const toggleMark: <Sc extends AnySchema, M extends MarkNames<Sc>>(markType: MarkType<Sc, M>, attrs?: MarkAttrsInput<Sc, M>, options?: ToggleMarkOptions) => Command<Sc>;
+/**
+ * Wrap a command so that, when it produces a transform that causes two
+ * joinable nodes to end up next to each other, those are joined. Nodes
+ * are considered joinable when they are of the same type and when the
+ * `isJoinable` predicate returns true for them or, if an array of
+ * strings was passed, if their node type name is in that array.
+ *
+ * @since 0.1.0
+ * @category combinators
+ */
+export declare const autoJoin: <Sc extends AnySchema, E, R>(command: Command<Sc, E, R>, isJoinable: ((before: Node<Sc>, after: Node<Sc>) => boolean) | ReadonlyArray<string>) => Command<Sc, E, R>;
+/**
+ * The union of the error types of the given commands.
+ *
+ * @since 0.1.0
+ * @category type-level
+ */
+export type CommandError<C> = C extends ((...args: any) => Effect.Effect<any, infer E, any>) ? E : never;
+/**
+ * The union of the requirements of the given commands.
+ *
+ * @since 0.1.0
+ * @category type-level
+ */
+export type CommandRequirements<C> = C extends ((...args: any) => Effect.Effect<any, any, infer R>) ? R : never;
+/**
+ * Combine a number of command functions into a single function (which
+ * calls them one by one until one returns true). The resulting
+ * command's errors and requirements are the unions of those of the
+ * given commands.
+ *
+ * @since 0.1.0
+ * @category combinators
+ */
+export declare const chainCommands: <const Commands extends ReadonlyArray<Command<any, any, any>>>(...commands: Commands) => Command<AnySchema, CommandError<Commands[number]>, CommandRequirements<Commands[number]>>;