@lofcz/edix 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+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
+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

@@ -0,0 +1,246 @@
+# edix
+
+![npm](https://img.shields.io/npm/v/@lofcz/edix) ![npm bundle size](https://img.shields.io/bundlephobia/minzip/@lofcz/edix) ![npm](https://img.shields.io/npm/dw/@lofcz/edix) [![check](https://github.com/lofcz/edix/actions/workflows/check.yml/badge.svg)](https://github.com/lofcz/edix/actions/workflows/check.yml) [![demo](https://github.com/lofcz/edix/actions/workflows/demo.yml/badge.svg)](https://github.com/lofcz/edix/actions/workflows/demo.yml)
+
+> An experimental, framework agnostic, small (4kB+) [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://lofcz.github.io/edix/)
+- [Framework examples](#other-examples)
+
+## Install
+
+```sh
+npm install edix@npm:@lofcz/edix
+```
+
+This uses an [npm alias](https://docs.npmjs.com/cli/commands/npm-install) so you can keep using `import { ... } from "edix"` in your code while installing the `@lofcz/edix` fork.
+
+Alternatively, install directly and import from `@lofcz/edix`:
+
+```sh
+npm install @lofcz/edix
+```
+
+`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/lofcz/edix/issues/97).
+
+## Getting started
+
+1. Define your contents declaratively. There are rules you have to follow:
+   - You must render `<br/>` in empty row (limitation of contenteditable).
+   - If `singleline` option is
+     - `false` or undefined, direct children of the root are treated as rows. They must be elements, not text.
+     - `true`, direct children of the root are treated as inline nodes.
+   - (TODO)
+
+2. Initialize `Editor` with `createPlainEditor`/`createEditor`.
+3. Call `Editor.input` on mount, with `HTMLElement` which is the root of editable contents.
+4. Update your state with `onChange`, which will be called on edit.
+5. 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 "edix";
+
+export const App = () => {
+  const ref = useRef<HTMLDivElement>(null);
+  const [text, setText] = useState("Hello world.");
+
+  useEffect(() => {
+    // 2. init
+    const editor = createPlainEditor({
+      text: text,
+      onChange: (v) => {
+        // 4. update state
+        setText(v);
+      },
+    });
+    // 3. bind to DOM
+    const cleanup = editor.input(ref.current);
+    return () => {
+      // 5. cleanup DOM
+      cleanup();
+    };
+  }, []);
+
+  // 1. render contents 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
+
+[Standard Schema](https://github.com/standard-schema/standard-schema) is supported.
+
+```tsx
+import { useState, useEffect, useRef, useMemo } from "react";
+import { createEditor, ToggleFormat } from "edix";
+import * as v from "valibot";
+
+const schema = v.strictObject({
+  children: v.array(
+    v.array(
+      v.strictObject({
+        text: v.string(),
+        bold: v.optional(v.boolean()),
+        italic: v.optional(v.boolean()),
+      }),
+    ),
+  ),
+});
+
+export const App = () => {
+  const ref = useRef<HTMLDivElement>(null);
+
+  type Doc = v.InferOutput<typeof schema>;
+  const [doc, setDoc] = useState<Doc>({
+    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.apply(ToggleFormat, "bold");
+          }}
+        >
+          bold
+        </button>
+        <button
+          onClick={() => {
+            editor.apply(ToggleFormat, "italic");
+          }}
+        >
+          italic
+        </button>
+      </div>
+      <div
+        ref={ref}
+        style={{
+          backgroundColor: "white",
+          border: "solid 1px darkgray",
+          padding: 8,
+        }}
+      >
+        {doc.children.map((r, i) => (
+          <div key={i}>
+            {r.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://lofcz.github.io/edix/react), [Source](./examples/react))
+- Vue ([Demo](https://lofcz.github.io/edix/vue), [Source](./examples/vue))
+- Svelte ([Demo](https://lofcz.github.io/edix/svelte), [Source](./examples/svelte))
+- Solid ([Demo](https://lofcz.github.io/edix/solid), [Source](./examples/solid))
+- Angular ([Demo](https://lofcz.github.io/edix/angular), [Source](./examples/angular))
+- Preact ([Demo](https://lofcz.github.io/edix/preact), [Source](./examples/preact))
+- Vanilla ([Demo](https://lofcz.github.io/edix/vanilla), [Source](./examples/vanilla))
+
+...and more! Contribution welcome!
+
+## Documentation
+
+- [API reference](./docs/API.md)
+- [Storybook examples](./stories) for more usages
+
+## Contribute
+
+All contributions are welcome.
+If you find a problem, feel free to create an [issue](https://github.com/lofcz/edix/issues) or a [PR](https://github.com/lofcz/edix/pulls). If you have a question, ask in [discussions](https://github.com/lofcz/edix/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,41 @@
+import type { Editor } from "./editor.js";
+import type { DocNode, InferNode, Position, PositionRange, TextNode } from "./doc/types.js";
+export type EditorCommand<A extends unknown[], T extends DocNode> = (this: Editor<T>, ...args: A) => void;
+/**
+ * Delete content in the selection or specified range.
+ */
+export declare function Delete(this: Editor, range?: PositionRange): void;
+/**
+ * Insert text at the caret or specified position.
+ */
+export declare function InsertText(this: Editor, text: string, position?: Position): void;
+/**
+ * Insert node at the caret or specified position.
+ */
+export declare function InsertNode<T extends DocNode>(this: Editor<T>, node: Exclude<InferNode<T>, TextNode>, position?: Position): void;
+/**
+ * Insert multiple inline nodes as a single line fragment in one transaction.
+ * When `moveCaret` is true (default), the caret moves to the end of the
+ * inserted content.
+ */
+export declare function InsertNodes<T extends DocNode>(this: Editor<T>, nodes: InferNode<T>[], position?: Position, moveCaret?: boolean): void;
+/**
+ * Replace text in the selection or specified range.
+ */
+export declare function ReplaceText(this: Editor, text: string): void;
+/**
+ * Replace all content in the editor.
+ */
+export declare function ReplaceAll(this: Editor, text: string): 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<InferNode<T>, "text">, K extends Extract<keyof N, string>>(this: Editor<T>, key: K, value: N[K], range?: PositionRange): void;
+/**
+ * Toggle formatting in the selection or specified range.
+ */
+export declare function ToggleFormat<T extends DocNode>(this: Editor<T>, key: Extract<ToggleableKey<Omit<InferNode<T>, "text">>, string>, range?: PositionRange): void;
+export {};

package/lib/doc/edit.d.ts

@@ -0,0 +1,41 @@
+import type { Fragment, Position, SelectionSnapshot } from "./types.js";
+declare const TYPE_DELETE = "delete";
+type DeleteOperation = Readonly<{
+    type: typeof TYPE_DELETE;
+    start: Position;
+    end: Position;
+}>;
+declare const TYPE_INSERT_TEXT = "insert_text";
+type InsertOperation = Readonly<{
+    type: typeof TYPE_INSERT_TEXT;
+    at: Position;
+    text: string;
+}>;
+declare const TYPE_INSERT_NODE = "insert_node";
+type InsertNodeOperation = Readonly<{
+    type: typeof TYPE_INSERT_NODE;
+    at: Position;
+    fragment: Fragment;
+}>;
+declare const TYPE_SET_ATTR = "set_attr";
+type SetAttrOperation = Readonly<{
+    type: typeof TYPE_SET_ATTR;
+    start: Position;
+    end: Position;
+    key: string;
+    value: unknown;
+}>;
+export type Operation = DeleteOperation | InsertOperation | InsertNodeOperation | SetAttrOperation;
+export declare class Transaction {
+    private readonly _ops;
+    selection?: SelectionSnapshot;
+    constructor(ops?: readonly Operation[]);
+    get ops(): readonly Operation[];
+    insertText(start: Position, text: string): this;
+    insertFragment(start: Position, fragment: Fragment): this;
+    delete(start: Position, end: Position): this;
+    attr(start: Position, end: Position, key: string, value: unknown): this;
+    transform(position: Position): Position;
+}
+export declare const rebasePosition: (position: Position, op: Operation) => Position;
+export {};

package/lib/doc/position.d.ts

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

package/lib/doc/types.d.ts

@@ -0,0 +1,15 @@
+export interface TextNode {
+    readonly text: string;
+}
+export interface VoidNode {
+}
+export type InlineNode = TextNode | VoidNode;
+export interface DocNode {
+    readonly children: readonly (readonly InlineNode[])[];
+}
+export type Fragment = DocNode["children"];
+export type InferNode<T extends DocNode> = T["children"][number][number];
+export type Path = readonly [number?];
+export type Position = readonly [path: Path, offset: number];
+export type PositionRange = readonly [start: Position, end: Position];
+export type SelectionSnapshot = readonly [anchor: Position, focus: Position];

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 @@
+export { defaultIsBlockNode, defaultIsVoidNode } from "./default.js";

package/lib/dom/parser.d.ts

@@ -0,0 +1,2 @@
+export interface ParserConfig {
+}

package/lib/editor.d.ts

@@ -0,0 +1,102 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { DocNode, SelectionSnapshot } from "./doc/types.js";
+import type { EditorCommand } from "./commands.js";
+import { Transaction } from "./doc/edit.js";
+import type { EditorPlugin } from "./plugins/types.js";
+import { type CopyExtension, type PasteExtension } from "./extensions/index.js";
+import { type KeyboardHandler } from "./hotkey.js";
+/**
+ * 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;
+    /**
+     * TODO
+     */
+    plugins?: EditorPlugin[];
+    /**
+     * Functions to handle keyboard events.
+     *
+     * Return `true` if you want to stop propagation.
+     */
+    keyboard?: KeyboardHandler[];
+    /**
+     * Functions to handle copy events
+     * @default [plainCopy()]
+     */
+    copy?: [CopyExtension, ...rest: CopyExtension[]];
+    /**
+     * Functions to handle paste / drop events
+     * @default [plainPaste()]
+     */
+    paste?: [PasteExtension, ...rest: PasteExtension[]];
+    /**
+     * TODO
+     */
+    isBlock?: (node: HTMLElement) => boolean;
+    /**
+     * Automatically scroll the mounted element to keep the caret visible
+     * after document changes. Scroll is coalesced via rAF for zero
+     * synchronous layout cost during input handling.
+     */
+    autoScroll?: boolean;
+    /**
+     * Callback invoked when document changes.
+     */
+    onChange: (doc: T) => void;
+    /**
+     * Callback invoked when errors happen.
+     *
+     * @default console.error
+     */
+    onError?: (message: string) => void;
+}
+/**
+ * The editor instance.
+ */
+export interface Editor<T extends DocNode = DocNode> {
+    readonly doc: T;
+    /**
+     * Whether the document is empty (no text content, no void nodes).
+     * Recomputed once per commit — O(1) read.
+     */
+    readonly isEmpty: boolean;
+    selection: SelectionSnapshot;
+    /**
+     * The getter/setter for the editor's read-only state.
+     * `true` to read-only. `false` to editable.
+     */
+    readonly: boolean;
+    /**
+     * Enable/disable auto-scroll after document changes.
+     */
+    autoScroll: boolean;
+    /**
+     * Dispatches editing operations.
+     * @param tr {@link Transaction} or {@link EditorCommand}
+     * @param args arguments of {@link EditorCommand}
+     * @param immediate If true, flushes queued operations immediately.
+     */
+    apply(tr: Transaction, immediate?: boolean): this;
+    apply<A extends unknown[]>(fn: EditorCommand<A, T>, ...args: A): this;
+    /**
+     * 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, plugins, keyboard, copy: copyExtensions, paste: pasteExtensions, isBlock, autoScroll: _autoScroll, onChange, onError, }: EditorOptions<T, S>) => Editor<T>;

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

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

package/lib/extensions/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 { CopyExtension } from "./types.js";

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

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

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

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

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

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

package/lib/extensions/index.d.ts

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

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

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

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

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

package/lib/extensions/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 { PasteExtension } from "./types.js";

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

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

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

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

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

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

package/lib/extensions/utils.d.ts

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

package/lib/history.d.ts

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

package/lib/hotkey.d.ts

@@ -0,0 +1,9 @@
+export type KeyboardHandler = (keyboard: KeyboardEvent) => boolean | void;
+/**
+ * TODO
+ */
+export declare const hotkey: (key: string, cb: (e: KeyboardEvent) => void, { mod, shift, alt, }?: {
+    mod?: boolean;
+    shift?: boolean;
+    alt?: boolean;
+}) => KeyboardHandler;