editate 0.0.0 → 0.5.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2020 inokawa
+Copyright (c) 2024 inokawa
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1 +1,251 @@
-# editate
+# editate
+
+![npm](https://img.shields.io/npm/v/editate) ![npm bundle size](https://img.shields.io/bundlephobia/minzip/editate) ![npm](https://img.shields.io/npm/dw/editate) [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/inokawa/editate) [![check](https://github.com/inokawa/editate/actions/workflows/check.yml/badge.svg)](https://github.com/inokawa/editate/actions/workflows/check.yml) [![demo](https://github.com/inokawa/editate/actions/workflows/demo.yml/badge.svg)](https://github.com/inokawa/editate/actions/workflows/demo.yml)
+
+> An experimental, type-safe, framework agnostic and small (5kB+) [contenteditable](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/contenteditable) state manager.
+
+## Motivation
+
+Web editing is so hard even today. There are excellent libraries to make complex rich text editor, but they are too much for small purposes. Native [textarea](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/textarea) element is accessible and easy to use, but it's hardly customizable.
+
+[contenteditable](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/contenteditable) attribute is a primitive for rich text editing, [that was designed for Internet Explorer and copied by other browsers](https://blog.whatwg.org/the-road-to-html-5-contenteditable). As you may know it has [so many problems](https://github.com/grammarly/contenteditable). It has no clear spec, it has many edge case bugs, and has cross browser/OS/input device problems. And it doesn't work well with declarative frontend frameworks... However, at least the core of contenteditable is stable and it works in all browsers except the inconsistencies. This library aims to fill that gap, fix contenteditable to fit modern web development.
+
+## Demo
+
+- [React Storybook](https://inokawa.github.io/editate/)
+- [Framework examples](#other-examples)
+
+## Install
+
+```sh
+npm install editate
+```
+
+`typescript >=5.0` is recommended.
+
+### Supported browsers
+
+Browser versions supporting [beforeinput event](https://developer.mozilla.org/en-US/docs/Web/API/Element/beforeinput_event#browser_compatibility) are supported.
+
+Mobile browsers are also supported, but with some issues (https://github.com/inokawa/editate/issues/97).
+
+## Getting started
+
+1. Define your document as a state.
+2. Define your editor view declaratively. There are rules you have to follow:
+   - You must render all texts in the document as Text nodes in DOM.
+   - You must render `<br/>` in empty blocks (limitation of contenteditable).
+   - You must render hard breaks in the document as [block element](https://github.com/inokawa/editate/blob/ecd70f084f2fbb54d36bfd3b682f2dd8bbc3f547/src/dom/default.ts#L25).
+   - You must render void nodes in the document as [void element](https://github.com/inokawa/editate/blob/ecd70f084f2fbb54d36bfd3b682f2dd8bbc3f547/src/dom/default.ts#L47).
+3. Use `createPlainEditor`/`createEditor` to initialize `Editor` with the document.
+4. Call `Editor.input` on mount, with `HTMLElement` which is the root of editor view.
+5. Update your state with `onChange`, which will be called on edit.
+6. Call returned function from `Editor.input` on unmount for cleanup.
+
+Here is an example for React.
+
+### Plain text
+
+```tsx
+import { useState, useEffect, useRef } from "react";
+import { createPlainEditor } from "editate";
+
+export const App = () => {
+  const ref = useRef<HTMLDivElement>(null);
+  // 1. Define state
+  const [text, setText] = useState("Hello world.");
+
+  useEffect(() => {
+    // 3. init
+    const editor = createPlainEditor({
+      text: text,
+      onChange: (v) => {
+        // 5. update state
+        setText(v);
+      },
+    });
+    // 4. bind to DOM
+    const cleanup = editor.input(ref.current);
+    return () => {
+      // 6. cleanup DOM
+      cleanup();
+    };
+  }, []);
+
+  // 2. render from state
+  return (
+    <div
+      ref={ref}
+      style={{
+        backgroundColor: "white",
+        border: "solid 1px darkgray",
+        padding: 8,
+      }}
+    >
+      {text.split("\n").map((t, i) => (
+        <div key={i}>{t ? t : <br />}</div>
+      ))}
+    </div>
+  );
+};
+```
+
+### Rich text
+
+You can define document schema with [Standard Schema](https://github.com/standard-schema/standard-schema) for type-safe editing.
+
+```tsx
+import { useState, useEffect, useRef, useMemo } from "react";
+import { createEditor, ToggleFormat, ToggleBlockAttr } from "editate";
+import * as z from "zod";
+
+const schema = z.strictObject({
+  children: z.array(
+    z.strictObject({
+      align: z.enum(["left", "right"]).optional(),
+      children: z.array(
+        z.strictObject({
+          text: z.string(),
+          bold: z.boolean().optional(),
+          italic: z.boolean().optional(),
+        }),
+      ),
+    }),
+  ),
+});
+
+export const App = () => {
+  const ref = useRef<HTMLDivElement>(null);
+
+  type Doc = z.infer<typeof schema>;
+  const [doc, setDoc] = useState<Doc>({
+    children: [
+      {
+        children: [
+          { text: "Hello", bold: true },
+          { text: " " },
+          { text: "World", italic: true },
+          { text: "." },
+        ],
+      },
+    ],
+  });
+
+  const editor = useMemo(
+    () =>
+      createEditor({
+        doc,
+        schema,
+        onChange: setDoc,
+      }),
+    [],
+  );
+
+  useEffect(() => {
+    return editor.input(ref.current);
+  }, []);
+
+  return (
+    <div>
+      <div>
+        <button
+          onClick={() => {
+            editor.exec(ToggleFormat, "bold");
+          }}
+        >
+          bold
+        </button>
+        <button
+          onClick={() => {
+            editor.exec(ToggleFormat, "italic");
+          }}
+        >
+          italic
+        </button>
+        <button
+          onClick={() => {
+            editor.exec(ToggleBlockAttr, "align", "right", undefined);
+          }}
+        >
+          align
+        </button>
+      </div>
+      <div
+        ref={ref}
+        style={{
+          backgroundColor: "white",
+          border: "solid 1px darkgray",
+          padding: 8,
+        }}
+      >
+        {doc.children.map((b, i) => (
+          <div key={i} style={{ textAlign: b.align }}>
+            {b.children.map((n, j) => (
+              <span
+                key={j}
+                style={{
+                  fontWeight: n.bold ? "bold" : undefined,
+                  fontStyle: n.italic ? "italic" : undefined,
+                }}
+              >
+                {n.text || <br />}
+              </span>
+            ))}
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+};
+```
+
+### Other examples
+
+- React ([Demo](https://inokawa.github.io/editate/react), [Source](./examples/react))
+- Vue ([Demo](https://inokawa.github.io/editate/vue), [Source](./examples/vue))
+- Svelte ([Demo](https://inokawa.github.io/editate/svelte), [Source](./examples/svelte))
+- Solid ([Demo](https://inokawa.github.io/editate/solid), [Source](./examples/solid))
+- Angular ([Demo](https://inokawa.github.io/editate/angular), [Source](./examples/angular))
+- Preact ([Demo](https://inokawa.github.io/editate/preact), [Source](./examples/preact))
+- Vanilla ([Demo](https://inokawa.github.io/editate/vanilla), [Source](./examples/vanilla))
+
+...and more! Contribution welcome!
+
+## Documentation
+
+- [API reference](./docs/API.md)
+- [Storybook examples](./stories) for more usages
+- [DeepWiki](https://deepwiki.com/inokawa/editate)
+
+## Contribute
+
+All contributions are welcome.
+If you find a problem, feel free to create an [issue](https://github.com/inokawa/editate/issues) or a [PR](https://github.com/inokawa/editate/pulls). If you have a question, ask in [discussions](https://github.com/inokawa/editate/discussions).
+
+### Making a Pull Request
+
+1. Fork this repo.
+2. Run `npm install`.
+3. Commit your fix.
+4. Make a PR and confirm all the CI checks passed.
+
+## Inspirations
+
+- [ProseMirror](https://prosemirror.net/)
+- [Slate](https://github.com/ianstormtaylor/slate)
+- [Lexical](https://github.com/facebook/lexical)
+- [Quill](https://github.com/slab/quill)
+- [Tiptap](https://github.com/ueberdosis/tiptap)
+- [Draft.js](https://github.com/facebookarchive/draft-js)
+- [rich-textarea](https://github.com/inokawa/rich-textarea) (my early project)
+- [use-editable](https://github.com/FormidableLabs/use-editable)
+- [@react-libraries/markdown-editor](https://github.com/ReactLibraries/markdown-editor)
+- [VS Code](https://github.com/microsoft/vscode)
+- [Language Server Protocol](https://github.com/microsoft/language-server-protocol)
+- [urql](https://github.com/urql-graphql/urql)
+- [TanStack DB](https://github.com/tanstack/db)
+- [Hono](https://github.com/honojs/hono)
+- [Textbus](https://github.com/textbus/textbus)
+- [vistree](https://github.com/mizchi/vistree)
+- Proposed [EditContext API](https://github.com/w3c/edit-context)
+- Proposed [Richer Text Fields](https://open-ui.org/components/richer-text-fields.explainer/) in [Open UI](https://open-ui.org/)

package/lib/commands.d.ts

@@ -0,0 +1,42 @@
+import type { Editor } from "./editor.js";
+import type { DocNode, InferBlockNode, InferInlineNode, Path, Range, TextNode } from "./doc/types.js";
+/**
+ * Delete content in the selection or specified range.
+ */
+export declare function Delete(editor: Editor, range?: Range): void;
+/**
+ * Insert text at the caret or specified position.
+ */
+export declare function InsertText(editor: Editor, text: string, position?: number): void;
+/**
+ * Insert node at the caret or specified position.
+ */
+export declare function InsertNode<T extends DocNode>(editor: Editor<T>, node: Exclude<InferInlineNode<T>, TextNode>, position?: number): void;
+/**
+ * Replace text in the selection or specified range.
+ */
+export declare function ReplaceText(editor: Editor, text: string): void;
+/**
+ * Replace document in the editor.
+ */
+export declare function ReplaceDoc<T extends DocNode>(editor: Editor<T>, fragment: T["children"]): void;
+type ToggleableKey<T> = {
+    [K in keyof T]-?: T[K] extends boolean | undefined ? K : never;
+}[keyof T];
+/**
+ * Format content in the selection or specified range.
+ */
+export declare function Format<T extends DocNode, N extends Omit<InferInlineNode<T>, "text">, K extends Extract<keyof N, string>>(editor: Editor<T>, key: K, value: N[K], range?: Range): void;
+/**
+ * Toggle formatting in the selection or specified range.
+ */
+export declare function ToggleFormat<T extends DocNode>(editor: Editor<T>, key: Extract<ToggleableKey<Omit<InferInlineNode<T>, "text">>, string>, range?: Range): void;
+/**
+ * Set attr to a block node at the caret or specified position.
+ */
+export declare function SetBlockAttr<T extends DocNode, N extends InferBlockNode<T>, K extends Extract<keyof N, string>>(editor: Editor<T>, key: K, value: N[K], path?: Path): void;
+/**
+ * Toggle attr of block node at the caret or specified position.
+ */
+export declare function ToggleBlockAttr<T extends DocNode, N extends InferBlockNode<T>, K extends Extract<keyof N, string>>(editor: Editor<T>, key: K, onValue: N[K], offValue: N[K], path?: Path): void;
+export {};

package/lib/doc/edit.d.ts

@@ -0,0 +1,49 @@
+import type { DocNode, Fragment, Path, BlockNode, Node, DomPosition } from "./types.js";
+declare const OP_DELETE = "delete";
+type DeleteOperation = Readonly<{
+    type: typeof OP_DELETE;
+    start: number;
+    end: number;
+}>;
+declare const OP_INSERT_TEXT = "insert_text";
+type InsertTextOperation = Readonly<{
+    type: typeof OP_INSERT_TEXT;
+    at: number;
+    text: string;
+}>;
+declare const OP_INSERT_NODE = "insert_node";
+type InsertNodeOperation = Readonly<{
+    type: typeof OP_INSERT_NODE;
+    at: number;
+    fragment: Fragment;
+}>;
+declare const OP_SET_ATTR = "set_attr";
+type SetAttrOperation = Readonly<{
+    type: typeof OP_SET_ATTR;
+    start: number;
+    end: number;
+    key: string;
+    value: unknown;
+}>;
+declare const OP_SET_NODE_ATTR = "set_node_attr";
+type SetNodeAttrOperation = Readonly<{
+    type: typeof OP_SET_NODE_ATTR;
+    path: Path;
+    key: string;
+    value: unknown;
+}>;
+export type Operation = DeleteOperation | InsertTextOperation | InsertNodeOperation | SetAttrOperation | SetNodeAttrOperation;
+export declare class Transaction {
+    private readonly _ops;
+    constructor(ops?: readonly Operation[]);
+    get ops(): readonly Operation[];
+    insertText(at: number, text: string): this;
+    insertFragment(at: number, fragment: Fragment): this;
+    delete(start: number, end: number): this;
+    format(start: number, end: number, key: string, value: unknown): this;
+    attr(at: Path, key: string, value: unknown): this;
+    transform(position: number): number;
+}
+export declare const getNodeSize: (node: Node) => number;
+export declare const offsetToPosition: (node: DocNode | BlockNode, offset: number) => DomPosition;
+export {};

package/lib/doc/position.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/doc/types.d.ts

@@ -0,0 +1,31 @@
+export interface TextNode {
+    readonly text: string;
+}
+export interface VoidNode {
+}
+export type InlineNode = TextNode | VoidNode;
+export interface BlockNode {
+    readonly children: readonly InlineNode[];
+}
+export type Node = BlockNode | InlineNode;
+export interface DocNode {
+    readonly children: readonly BlockNode[];
+}
+export type Fragment = DocNode["children"];
+type InferChild<T> = T extends {
+    children: readonly (infer N)[];
+} ? InferChild<N> : T;
+type InferBlock<T> = T extends {
+    children: readonly (infer N)[];
+} ? T & InferBlock<N> : T;
+export type InferInlineNode<T extends DocNode> = InferChild<T>;
+export type InferBlockNode<T extends DocNode> = InferBlock<T>;
+export type Path = readonly number[];
+export type DomPosition = readonly [path: Path, offset: number];
+export type Range = readonly [start: number, end: number];
+export type Selection = readonly [anchor: number, focus: number];
+export type SelectionSnapshot = readonly [
+    anchor: DomPosition,
+    focus: DomPosition
+];
+export {};

package/lib/doc/utils.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/dom/default.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/dom/index.d.ts

@@ -0,0 +1,2 @@
+export { createParser } from "./parser.js";
+export { defaultIsBlockNode, defaultIsVoidNode } from "./default.js";

package/lib/dom/mutation.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/dom/parser.d.ts

@@ -0,0 +1 @@
+export type Parser = <T>(scopeFn: () => T, root?: Node, startNode?: Node) => T;

package/lib/editor.d.ts

@@ -0,0 +1,107 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { DocNode, Selection } from "./doc/types.js";
+import { Transaction, type Operation } from "./doc/edit.js";
+import { type CopyHook, type PasteHook, type KeyboardHook } from "./hooks/index.js";
+type EditorCommand<A extends unknown[], T extends DocNode = DocNode> = (editor: Editor<T>, ...args: A) => void | undefined;
+type EditorQuery<A extends unknown[], V, T extends DocNode = DocNode> = (editor: Editor<T>, ...args: A) => V;
+/**
+ * Options of {@link createEditor}.
+ */
+export interface EditorOptions<T extends DocNode, S extends StandardSchemaV1<T, T> | void = void> {
+    /**
+     * Optional [Standard Schema](https://github.com/standard-schema/standard-schema) to validate unsafe edits.
+     */
+    schema?: S;
+    /**
+     * Initial document.
+     */
+    doc: T;
+    /**
+     * The state editable or not.
+     */
+    readonly?: boolean;
+    /**
+     * Functions to handle keyboard events.
+     *
+     * Return `true` if you want to stop propagation.
+     */
+    keyboard?: KeyboardHook[];
+    /**
+     * Functions to handle copy events
+     * @default [plainCopy()]
+     */
+    copy?: [CopyHook, ...rest: CopyHook[]];
+    /**
+     * Functions to handle paste / drop events
+     * @default [plainPaste()]
+     */
+    paste?: [PasteHook, ...rest: PasteHook[]];
+    /**
+     * TODO
+     */
+    isBlock?: (node: HTMLElement) => boolean;
+    /**
+     * Callback invoked when document changes.
+     */
+    onChange: (doc: T) => void;
+    /**
+     * Callback invoked when errors happen.
+     *
+     * @default console.error
+     */
+    onError?: (message: string) => void;
+}
+type EditorEventMap = {
+    change: () => void;
+    selectionchange: () => void;
+    readonly: () => void;
+};
+type EditorHookMap = {
+    apply: (op: Operation, next: (op?: Operation) => void) => void;
+    mount: (element: HTMLElement) => void | (() => void);
+    keyboard: KeyboardHook;
+};
+/**
+ * The editor instance.
+ */
+export interface Editor<T extends DocNode = DocNode> {
+    readonly doc: T;
+    selection: Selection;
+    /**
+     * The getter/setter for the editor's read-only state.
+     * `true` to read-only. `false` to editable.
+     */
+    readonly: boolean;
+    /**
+     * Dispatches editing operations.
+     * @param tr {@link Transaction}
+     */
+    apply(tr: Transaction): this;
+    /**
+     * Executes a function with editor bound as context.
+     * @param fn {@link EditorCommand} or {@link EditorQuery}
+     * @param args arguments of the function
+     */
+    exec<A extends unknown[]>(fn: EditorCommand<A, T>, ...args: A): this;
+    exec<A extends unknown[], V>(fn: EditorQuery<A, V, T>, ...args: A): V;
+    /**
+     * A function to subscribe editor events.
+     * @returns cleanup function
+     */
+    on<K extends keyof EditorEventMap>(key: K, callback: EditorEventMap[K]): () => void;
+    /**
+     * A function to register editor hooks.
+     * @returns cleanup function
+     */
+    hook<K extends keyof EditorHookMap>(key: K, callback: EditorHookMap[K]): () => void;
+    /**
+     * A function to make DOM editable.
+     * @returns A function to stop subscribing DOM changes and restores previous DOM state.
+     */
+    input: (element: HTMLElement) => () => void;
+}
+/**
+ * A function to initialize {@link Editor}.
+ */
+export declare const createEditor: <T extends DocNode, S extends StandardSchemaV1<T, T> | void = void>({ doc, readonly, schema, keyboard, copy: copyHooks, paste: pasteHooks, isBlock, onChange, onError, }: EditorOptions<T, S>) => Editor<T>;
+export {};

package/lib/hooks/copy/html.d.ts

@@ -0,0 +1,5 @@
+import type { CopyHook } from "./types.js";
+/**
+ * An extension to handle copying to HTML.
+ */
+export declare const htmlCopy: () => CopyHook;

package/lib/hooks/copy/index.d.ts

@@ -0,0 +1,4 @@
+export { plainCopy } from "./plain.js";
+export { htmlCopy } from "./html.js";
+export { internalCopy } from "./internal.js";
+export type { CopyHook } from "./types.js";

package/lib/hooks/copy/internal.d.ts

@@ -0,0 +1,7 @@
+import type { CopyHook } from "./types.js";
+/**
+ * An extension to handle copying to editor instance.
+ */
+export declare const internalCopy: ({ key, }?: {
+    key?: string;
+}) => CopyHook;

package/lib/hooks/copy/plain.d.ts

@@ -0,0 +1,6 @@
+import type { DocNode, InferInlineNode } from "../../doc/types.js";
+import type { CopyHook } from "./types.js";
+/**
+ * An extension to handle copying to plain text.
+ */
+export declare const plainCopy: <T extends DocNode>(serializer?: (node: InferInlineNode<T>) => string) => CopyHook;

package/lib/hooks/copy/types.d.ts

@@ -0,0 +1,2 @@
+import type { Fragment } from "../../doc/types.js";
+export type CopyHook = (dataTransfer: DataTransfer, doc: Fragment, element: Element) => void;

package/lib/hooks/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./copy/index.js";
+export * from "./paste/index.js";
+export * from "./keyboard.js";

package/lib/hooks/keyboard.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Functions to handle keyboard events.
+ *
+ * Return `true` if you want to stop propagation.
+ */
+export type KeyboardHook = (keyboard: KeyboardEvent) => boolean | void;
+/**
+ * TODO
+ */
+export declare const hotkey: (key: string, cb: (e: KeyboardEvent) => void, { mod, shift, alt, }?: {
+    mod?: boolean;
+    shift?: boolean;
+    alt?: boolean;
+}) => KeyboardHook;

package/lib/hooks/paste/file.d.ts

@@ -0,0 +1,6 @@
+import type { InlineNode } from "../../doc/types.js";
+import type { PasteHook } from "./types.js";
+/**
+ * An extension to handle pasting / dropping from File.
+ */
+export declare const filePaste: (handlerByMime: Record<string, (file: File) => InlineNode>) => PasteHook;

package/lib/hooks/paste/html.d.ts

@@ -0,0 +1,6 @@
+import type { DocNode, InferInlineNode, TextNode } from "../../doc/types.js";
+import type { PasteHook } from "./types.js";
+/**
+ * An extension to handle pasting / dropping from HTML.
+ */
+export declare const htmlPaste: <T extends DocNode>(serializeText: (t: string) => Extract<InferInlineNode<T>, TextNode>, serializers?: ((node: HTMLElement) => Exclude<InferInlineNode<T>, TextNode> | void)[]) => PasteHook;

package/lib/hooks/paste/index.d.ts

@@ -0,0 +1,5 @@
+export { filePaste } from "./file.js";
+export { plainPaste } from "./plain.js";
+export { htmlPaste } from "./html.js";
+export { internalPaste } from "./internal.js";
+export type { PasteHook } from "./types.js";

package/lib/hooks/paste/internal.d.ts

@@ -0,0 +1,7 @@
+import type { PasteHook } from "./types.js";
+/**
+ * An extension to handle pasting / dropping from editor instance.
+ */
+export declare const internalPaste: ({ key, }?: {
+    key?: string;
+}) => PasteHook;

package/lib/hooks/paste/plain.d.ts

@@ -0,0 +1,5 @@
+import type { PasteHook } from "./types.js";
+/**
+ * An extension to handle pasting / dropping from plain text.
+ */
+export declare const plainPaste: () => PasteHook;

package/lib/hooks/paste/types.d.ts

@@ -0,0 +1,3 @@
+import type { Fragment } from "../../doc/types.js";
+import type { Parser } from "../../dom/parser.js";
+export type PasteHook = (dataTransfer: DataTransfer, parser: Parser) => string | Fragment | null;

package/lib/hooks/utils.d.ts

@@ -0,0 +1 @@
+export {};