@thomasfosterau/effect-richtext 0.0.0 → 0.1.0

package/dist/html.d.ts

@@ -0,0 +1,158 @@
+import { ModelError } from "./model/errors.js";
+import { Slice } from "./model/replace.js";
+import { DOMParser, ParseOptions } from "./model/from_dom.js";
+import { DOMSerializer } from "./model/to_dom.js";
+import { AnySchema } from "./model/schema.js";
+import { Node } from "./model/node.js";
+import { Fragment } from "./model/fragment.js";
+import "./model.js";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import * as Context from "effect/Context";
+import * as Layer from "effect/Layer";
+declare const MissingDocumentError_base: Schema.Class<MissingDocumentError, Schema.TaggedStruct<"MissingDocumentError", {
+  readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised (as a defect) when no DOM `document` is available: neither one
+ * passed in the options nor a global `document`.
+ *
+ * @since 0.1.0
+ * @category errors
+ */
+export declare class MissingDocumentError extends MissingDocumentError_base {}
+/**
+ * Something that can parse an HTML string into a document, like the
+ * browser's `window.DOMParser`.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface HTMLStringParser {
+  readonly parseFromString: (string: string, type: DOMParserSupportedType) => Document;
+}
+/**
+ * Options for `toHTML` and `serialize`.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface ToHTMLOptions<Sc extends AnySchema = AnySchema> {
+  /** The DOM document used to create nodes. Defaults to the global `document`. */
+  readonly document?: Document | undefined;
+  /** The serializer to use. Defaults to `DOMSerializer.fromSchema(schema)`. */
+  readonly serializer?: DOMSerializer<Sc> | undefined;
+}
+/**
+ * Options for `fromHTML`, `sliceFromHTML`, `parse` and `parseSlice`.
+ * The model's `ParseOptions` are passed through to the parser.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface FromHTMLOptions<Sc extends AnySchema = AnySchema> extends ParseOptions<Sc> {
+  /**
+   * The DOM document used to create an inert HTML document to parse
+   * into. Defaults to the global `document`. Ignored when `htmlParser`
+   * is given.
+   */
+  readonly document?: Document | undefined;
+  /** An HTML string parser, such as an instance of the browser's `DOMParser`. */
+  readonly htmlParser?: HTMLStringParser | undefined;
+  /** The parser to use. Defaults to `DOMParser.fromSchema(schema)`. */
+  readonly parser?: DOMParser<Sc> | undefined;
+}
+/**
+ * Serialize a node or fragment to an HTML string. When given the top
+ * node of its schema (usually `doc`), its content is serialized;
+ * other nodes are serialized including their own wrapper element (and
+ * marks).
+ *
+ * Throws a `MissingDocumentError` when no document is available, and a
+ * `DOMSpecError` for invalid `toDOM` output specs (both programming
+ * errors).
+ *
+ * @since 0.1.0
+ * @category serialization
+ */
+export declare const toHTML: <Sc extends AnySchema>(content: Node<Sc, any> | Fragment<Sc, any>, options?: ToHTMLOptions<Sc>) => string;
+/**
+ * Like `fromHTML`, but throws a `ModelError` when the content can't be
+ * parsed into a valid document.
+ *
+ * @since 0.1.0
+ * @category parsing
+ */
+export declare const fromHTMLUnsafe: <Sc extends AnySchema>(schema: Sc, html: string, options?: FromHTMLOptions<Sc>) => Node<Sc>;
+/**
+ * Parse an HTML string into a document for the given schema.
+ *
+ * @since 0.1.0
+ * @category parsing
+ */
+export declare const fromHTML: <Sc extends AnySchema>(schema: Sc, html: string, options?: FromHTMLOptions<Sc>) => Effect.Effect<Node<Sc>, ModelError>;
+/**
+ * Like `sliceFromHTML`, but throws a `ModelError` on failure.
+ *
+ * @since 0.1.0
+ * @category parsing
+ */
+export declare const sliceFromHTMLUnsafe: <Sc extends AnySchema>(schema: Sc, html: string, options?: FromHTMLOptions<Sc>) => Slice<Sc>;
+/**
+ * Parse an HTML string into a slice that is open at the sides (see
+ * `DOMParser.parseSlice`), as for pasted content.
+ *
+ * @since 0.1.0
+ * @category parsing
+ */
+export declare const sliceFromHTML: <Sc extends AnySchema>(schema: Sc, html: string, options?: FromHTMLOptions<Sc>) => Effect.Effect<Slice<Sc>, ModelError>;
+declare const HtmlEnvironment_base: Context.ServiceClass<HtmlEnvironment, "effect-richtext/html/HtmlEnvironment", {
+  readonly document: Document;
+}>;
+/**
+ * A service providing the DOM `document` used to serialize and parse
+ * HTML.
+ *
+ * @since 0.1.0
+ * @category services
+ */
+export declare class HtmlEnvironment extends HtmlEnvironment_base {
+  /**
+   * A layer providing the given document.
+   *
+   * @since 0.1.0
+   */
+  static readonly layer: (document: Document) => Layer.Layer<HtmlEnvironment>;
+  /**
+   * A layer reading `globalThis.document` when built. Dies with a
+   * `MissingDocumentError` when there is no global document.
+   *
+   * @since 0.1.0
+   */
+  static readonly layerGlobal: Layer.Layer<HtmlEnvironment>;
+}
+/**
+ * Serialize a node or fragment to an HTML string (see `toHTML`), using
+ * the `HtmlEnvironment`'s document.
+ *
+ * @since 0.1.0
+ * @category serialization
+ */
+export declare const serialize: <Sc extends AnySchema>(content: Node<Sc, any> | Fragment<Sc, any>, options?: Omit<ToHTMLOptions<Sc>, "document">) => Effect.Effect<string, never, HtmlEnvironment>;
+/**
+ * Parse an HTML string into a document (see `fromHTML`), using the
+ * `HtmlEnvironment`'s document.
+ *
+ * @since 0.1.0
+ * @category parsing
+ */
+export declare const parse: <Sc extends AnySchema>(schema: Sc, html: string, options?: Omit<FromHTMLOptions<Sc>, "document">) => Effect.Effect<Node<Sc>, ModelError, HtmlEnvironment>;
+/**
+ * Parse an HTML string into an open slice (see `sliceFromHTML`), using
+ * the `HtmlEnvironment`'s document.
+ *
+ * @since 0.1.0
+ * @category parsing
+ */
+export declare const parseSlice: <Sc extends AnySchema>(schema: Sc, html: string, options?: Omit<FromHTMLOptions<Sc>, "document">) => Effect.Effect<Slice<Sc>, ModelError, HtmlEnvironment>;
+export {};

package/dist/html.js

@@ -0,0 +1,164 @@
+import { attempt } from "./internal/attempt.js";
+import { DOMParser } from "./model/from_dom.js";
+import { DOMSerializer } from "./model/to_dom.js";
+import { Fragment } from "./model/fragment.js";
+import { isModelError } from "./model/errors.js";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import * as Context from "effect/Context";
+import * as Layer from "effect/Layer";
+// src/html.ts
+/**
+* Small helpers converting between documents and HTML strings, built
+* on the model's `DOMParser` and `DOMSerializer`.
+*
+* The helpers need a DOM implementation. In the browser the global
+* `document` is used; elsewhere (for example in Node with `happy-dom`
+* or `jsdom`), pass a `document` in the options, or use the Effect
+* variants (`serialize`, `parse`, `parseSlice`), which read the
+* document from the `HtmlEnvironment` service.
+*
+* ```ts skip-type-checking
+* const html = toHTML(doc) // "<p>Hello</p>"
+* const doc2 = yield* fromHTML(schema, html)
+* ```
+*
+* @since 0.1.0
+*/
+/**
+* Raised (as a defect) when no DOM `document` is available: neither one
+* passed in the options nor a global `document`.
+*
+* @since 0.1.0
+* @category errors
+*/
+var MissingDocumentError = class extends Schema.TaggedError()("MissingDocumentError", { message: Schema.String }) {};
+const resolveDocument = (document) => {
+	const result = document ?? globalThis.document;
+	if (!result) throw new MissingDocumentError({ message: "No DOM document available: pass a `document` option or provide an HtmlEnvironment" });
+	return result;
+};
+/**
+* Serialize a node or fragment to an HTML string. When given the top
+* node of its schema (usually `doc`), its content is serialized;
+* other nodes are serialized including their own wrapper element (and
+* marks).
+*
+* Throws a `MissingDocumentError` when no document is available, and a
+* `DOMSpecError` for invalid `toDOM` output specs (both programming
+* errors).
+*
+* @since 0.1.0
+* @category serialization
+*/
+const toHTML = (content, options = {}) => {
+	const document = resolveDocument(options.document);
+	const container = document.createElement("div");
+	if (content instanceof Fragment) {
+		const first = content.firstChild;
+		if (Option.isNone(first)) return "";
+		const schema = first.value.type.schema;
+		(options.serializer ?? DOMSerializer.fromSchema(schema)).serializeFragment(content, { document }, container);
+	} else {
+		const schema = content.type.schema;
+		const serializer = options.serializer ?? DOMSerializer.fromSchema(schema);
+		if (content.type === schema.topNodeType) serializer.serializeFragment(content.content, { document }, container);
+		else container.appendChild(serializer.serializeNode(content, { document }));
+	}
+	return container.innerHTML;
+};
+const parseDOM = (html, options) => {
+	if (options.htmlParser) return options.htmlParser.parseFromString(html, "text/html").body;
+	const inert = resolveDocument(options.document).implementation.createHTMLDocument("");
+	inert.body.innerHTML = html;
+	return inert.body;
+};
+/**
+* Like `fromHTML`, but throws a `ModelError` when the content can't be
+* parsed into a valid document.
+*
+* @since 0.1.0
+* @category parsing
+*/
+const fromHTMLUnsafe = (schema, html, options = {}) => (options.parser ?? DOMParser.fromSchema(schema)).parseUnsafe(parseDOM(html, options), options);
+/**
+* Parse an HTML string into a document for the given schema.
+*
+* @since 0.1.0
+* @category parsing
+*/
+const fromHTML = (schema, html, options = {}) => attempt(() => fromHTMLUnsafe(schema, html, options), isModelError);
+/**
+* Like `sliceFromHTML`, but throws a `ModelError` on failure.
+*
+* @since 0.1.0
+* @category parsing
+*/
+const sliceFromHTMLUnsafe = (schema, html, options = {}) => (options.parser ?? DOMParser.fromSchema(schema)).parseSliceUnsafe(parseDOM(html, options), options);
+/**
+* Parse an HTML string into a slice that is open at the sides (see
+* `DOMParser.parseSlice`), as for pasted content.
+*
+* @since 0.1.0
+* @category parsing
+*/
+const sliceFromHTML = (schema, html, options = {}) => attempt(() => sliceFromHTMLUnsafe(schema, html, options), isModelError);
+/**
+* A service providing the DOM `document` used to serialize and parse
+* HTML.
+*
+* @since 0.1.0
+* @category services
+*/
+var HtmlEnvironment = class HtmlEnvironment extends Context.Service()("effect-richtext/html/HtmlEnvironment") {
+	static {
+		this.layer = (document) => Layer.succeed(HtmlEnvironment, { document });
+	}
+	static {
+		this.layerGlobal = Layer.effect(HtmlEnvironment, Effect.sync(() => ({ document: resolveDocument(void 0) })));
+	}
+};
+/**
+* Serialize a node or fragment to an HTML string (see `toHTML`), using
+* the `HtmlEnvironment`'s document.
+*
+* @since 0.1.0
+* @category serialization
+*/
+const serialize = (content, options = {}) => Effect.gen(function* () {
+	const { document } = yield* HtmlEnvironment;
+	return yield* Effect.sync(() => toHTML(content, {
+		...options,
+		document
+	}));
+});
+/**
+* Parse an HTML string into a document (see `fromHTML`), using the
+* `HtmlEnvironment`'s document.
+*
+* @since 0.1.0
+* @category parsing
+*/
+const parse = (schema, html, options = {}) => Effect.gen(function* () {
+	const { document } = yield* HtmlEnvironment;
+	return yield* fromHTML(schema, html, {
+		...options,
+		document
+	});
+});
+/**
+* Parse an HTML string into an open slice (see `sliceFromHTML`), using
+* the `HtmlEnvironment`'s document.
+*
+* @since 0.1.0
+* @category parsing
+*/
+const parseSlice = (schema, html, options = {}) => Effect.gen(function* () {
+	const { document } = yield* HtmlEnvironment;
+	return yield* sliceFromHTML(schema, html, {
+		...options,
+		document
+	});
+});
+export { HtmlEnvironment, MissingDocumentError, fromHTML, fromHTMLUnsafe, parse, parseSlice, serialize, sliceFromHTML, sliceFromHTMLUnsafe, toHTML };

package/dist/inputrules.d.ts

@@ -0,0 +1,271 @@
+import { AnySchema, NodeAttrsInput, NodeNames, NodeType } from "./model/schema.js";
+import { Node } from "./model/node.js";
+import "./model.js";
+import { Dispatch, Transaction } from "./state/transaction.js";
+import { EditorState } from "./state/state.js";
+import { EditorViewLike, Plugin } from "./state/plugin.js";
+import "./state.js";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+/**
+ * What an input rule handler may return: a transaction describing the
+ * rule's effect, `null`/`undefined` (or `None`) when the input was not
+ * handled, an `Option` of a transaction, or an Effect producing such an
+ * `Option`.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export type InputRuleResult<Sc extends AnySchema = AnySchema, E = never, R = never> = Transaction<Sc> | null | undefined | Option.Option<Transaction<Sc>> | Effect.Effect<Option.Option<Transaction<Sc>>, E, R>;
+/**
+ * An input rule handler. Called with the editor state, the match array
+ * produced by `RegExp.exec`, and the start and end of the matched range.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export type InputRuleHandler<Sc extends AnySchema = AnySchema, E = never, R = never> = (state: EditorState<Sc, any, any>, match: RegExpMatchArray, start: number, end: number) => InputRuleResult<Sc, E, R>;
+/**
+ * Options for `InputRule`.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface InputRuleOptions {
+  /**
+   * When set to false, `undoInputRule` doesn't work on this rule.
+   */
+  readonly undoable?: boolean | undefined;
+  /**
+   * By default, input rules will not apply inside nodes marked as
+   * `code`. Set this to true to change that, or to `"only"` to _only_
+   * match in such nodes.
+   */
+  readonly inCode?: boolean | "only" | undefined;
+  /**
+   * When set to `false`, this rule will not fire inside marks marked as
+   * `code`. The default is `true`.
+   */
+  readonly inCodeMark?: boolean | undefined;
+}
+/**
+ * @since 0.1.0
+ * @category symbols
+ */
+export declare const InputRuleTypeId: unique symbol;
+/**
+ * @since 0.1.0
+ * @category symbols
+ */
+export type InputRuleTypeId = typeof InputRuleTypeId;
+/**
+ * Input rules are regular expressions describing a piece of text that,
+ * when typed, causes something to happen. This might be changing two
+ * dashes into an emdash, wrapping a paragraph starting with `"> "` into
+ * a blockquote, or something entirely different.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export declare class InputRule<Sc extends AnySchema = AnySchema, E = never, R = never> {
+  /** The regular expression the text before the cursor is matched against. */
+  readonly match: RegExp;
+  readonly [InputRuleTypeId]: {
+    readonly _E: (_: never) => E;
+    readonly _R: (_: never) => R;
+  };
+  /** @internal */
+  readonly handler: InputRuleHandler<Sc, E, R>;
+  /** @internal */
+  readonly undoable: boolean;
+  /** Whether the rule applies in code nodes (`"only"`: only there). */
+  readonly inCode: boolean | "only";
+  /** Whether the rule applies inside code marks. */
+  readonly inCodeMark: boolean;
+  /**
+   * Create an input rule. The rule applies when the user typed something
+   * and the text directly in front of the cursor matches `match`, which
+   * should end with `$`.
+   *
+   * The `handler` can be a string, in which case the matched text, or
+   * the first matched group in the regexp, is replaced by that string.
+   *
+   * Or it can be a function, which will be called with the match array
+   * produced by `RegExp.exec`, as well as the start and end of the
+   * matched range, and which can return a transaction that describes the
+   * rule's effect, or `null` to indicate the input was not handled. It
+   * may also return an `Option` of a transaction, or an Effect producing
+   * one.
+   */
+  constructor(
+  /** The regular expression the text before the cursor is matched against. */
+  match: RegExp, handler: string | InputRuleHandler<Sc, E, R>, options?: InputRuleOptions);
+}
+/**
+ * The union of the error types of the given input rules.
+ *
+ * @since 0.1.0
+ * @category type-level
+ */
+export type InputRuleErrors<Rules extends ReadonlyArray<InputRule<any, any, any>>> = Rules[number] extends (infer X) ? X extends InputRule<any, infer E, any> ? E : never : never;
+/**
+ * The union of the requirements of the given input rules.
+ *
+ * @since 0.1.0
+ * @category type-level
+ */
+export type InputRuleRequirements<Rules extends ReadonlyArray<InputRule<any, any, any>>> = Rules[number] extends (infer X) ? X extends InputRule<any, any, infer R> ? R : never : never;
+/**
+ * The last applied (undoable) input rule, as remembered by the input
+ * rules plugin so that `undoInputRule` can revert it.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface AppliedInputRule<Sc extends AnySchema = AnySchema> {
+  /** The transaction produced by the rule. */
+  readonly transform: Transaction<Sc>;
+  /** The start of the text input that triggered the rule. */
+  readonly from: number;
+  /** The end of the text input that triggered the rule. */
+  readonly to: number;
+  /** The typed text that triggered the rule. */
+  readonly text: string;
+}
+/**
+ * The state of an input rules plugin: the last applied rule, while it
+ * is still undoable (until the selection or document changes).
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export type InputRulesState = Option.Option<AppliedInputRule<any>>;
+/**
+ * Options for `inputRules`.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface InputRulesConfig<Rules extends ReadonlyArray<InputRule<any, any, any>>> {
+  readonly rules: Rules;
+}
+/**
+ * Create an input rules plugin. When enabled, it will cause text input
+ * that matches any of the given rules to trigger the rule's action.
+ *
+ * Rules are tried in order. Rules whose handler returns an Effect run
+ * with the view's context: when such an effect completes synchronously,
+ * it behaves exactly like a plain rule. When it is asynchronous, the
+ * input is considered handled; when it eventually finds no transaction
+ * (or fails), the typed text is inserted, and when it produces a
+ * transaction, it is dispatched—both only if the editor state didn't
+ * change in the meantime.
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export declare const inputRules: <const Rules extends ReadonlyArray<InputRule<any, any, any>>>({ rules }: InputRulesConfig<Rules>) => Plugin<InputRulesState, AnySchema, InputRuleErrors<Rules>, InputRuleRequirements<Rules>>;
+/**
+ * A command that works with any schema and needs no services.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export type InputRuleCommand = <Sc extends AnySchema>(state: EditorState<Sc, any, any>, dispatch?: Dispatch<Sc>, view?: EditorViewLike) => Effect.Effect<boolean>;
+/**
+ * This is a command that will undo an input rule, if applying such a
+ * rule was the last thing that the user did.
+ *
+ * @since 0.1.0
+ * @category commands
+ */
+export declare const undoInputRule: InputRuleCommand;
+/**
+ * Attributes for a rule-built node: fixed, or computed from the match.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export type InputRuleAttrs<Sc extends AnySchema, N extends NodeNames<Sc>> = NodeAttrsInput<Sc, N> | null | ((match: RegExpMatchArray) => NodeAttrsInput<Sc, N> | null);
+/**
+ * Build an input rule for automatically wrapping a textblock when a
+ * given string is typed. The `regexp` argument is directly passed
+ * through to the `InputRule` constructor. You'll probably want the
+ * regexp to start with `^`, so that the pattern can only occur at the
+ * start of a textblock.
+ *
+ * `nodeType` is the type of node to wrap in. If it needs attributes,
+ * you can either pass them directly, or pass a function that will
+ * compute them from the regular expression match.
+ *
+ * By default, if there's a node with the same type above the newly
+ * wrapped node, the rule will try to join those two nodes. You can pass
+ * a join predicate, which takes a regular expression match and the node
+ * before the wrapped node, and can return a boolean to indicate whether
+ * a join should happen.
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export declare const wrappingInputRule: <Sc extends AnySchema, N extends NodeNames<Sc>>(regexp: RegExp, nodeType: NodeType<Sc, N>, getAttrs?: InputRuleAttrs<Sc, N>, joinPredicate?: (match: RegExpMatchArray, node: Node<Sc>) => boolean) => InputRule<Sc>;
+/**
+ * Build an input rule that changes the type of a textblock when the
+ * matched text is typed into it. You'll usually want to start your
+ * regexp with `^` so that it is only matched at the start of a
+ * textblock. The optional `getAttrs` parameter can be used to compute
+ * the new node's attributes, and works the same as in the
+ * `wrappingInputRule` function.
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export declare const textblockTypeInputRule: <Sc extends AnySchema, N extends NodeNames<Sc>>(regexp: RegExp, nodeType: NodeType<Sc, N>, getAttrs?: InputRuleAttrs<Sc, N>) => InputRule<Sc>;
+/**
+ * Converts double dashes to an emdash.
+ *
+ * @since 0.1.0
+ * @category rules
+ */
+export declare const emDash: InputRule;
+/**
+ * Converts three dots to an ellipsis character.
+ *
+ * @since 0.1.0
+ * @category rules
+ */
+export declare const ellipsis: InputRule;
+/**
+ * “Smart” opening double quotes.
+ *
+ * @since 0.1.0
+ * @category rules
+ */
+export declare const openDoubleQuote: InputRule;
+/**
+ * “Smart” closing double quotes.
+ *
+ * @since 0.1.0
+ * @category rules
+ */
+export declare const closeDoubleQuote: InputRule;
+/**
+ * “Smart” opening single quotes.
+ *
+ * @since 0.1.0
+ * @category rules
+ */
+export declare const openSingleQuote: InputRule;
+/**
+ * “Smart” closing single quotes.
+ *
+ * @since 0.1.0
+ * @category rules
+ */
+export declare const closeSingleQuote: InputRule;
+/**
+ * Smart-quote related input rules.
+ *
+ * @since 0.1.0
+ * @category rules
+ */
+export declare const smartQuotes: ReadonlyArray<InputRule>;