@b9g/revise 0.1.2 → 0.1.4

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2021 Brian Kim
+
+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,70 +1,159 @@
 # Revise.js
 
-Revise is a JavaScript library for creating
-[`contenteditable`-based](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/contenteditable)
-rich-text editors in the browser. It provides a low-level, web-component based
-API for translating the DOM into string documents. The library also ships with
-a compact data structure for representing edits to strings. Revise is intended
-to be framework-agnostic, though currently it is only being tested with
-[Crank](crank.js.org).
+Revise is a JavaScript library for building rich-text editors on top of
+[`contenteditable`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/contenteditable).
+It provides low-level primitives — a custom element, an edit data structure,
+a keyed reconciler, and a state coordinator — so that any framework can build
+editing experiences without fighting the DOM.
 
-## Status
-
-At present, this library is in an early beta. It is recommended for developers
-who aren’t afraid of stepping through DOM code in a debugger.
-
-## Usage
-
-TKTKTKT
-
-## API
-
-### `ContentAreaElement`
-
-A custom element class with an API similar to that of the JavaScript API for
-the [`<textarea>`
-element](https://developer.mozilla.org/en-US/docs/Web/API/HTMLTextAreaElement).
-This class provides special properties and methods for reading the current
-value of the element’s contents and manipulating its selection.
-
-- `value`
-
-- `selectionStart`
-
-- `selectionEnd`
+```
+npm install @b9g/revise
+```
 
-- `selectionDirection`
-
-- `setSelectionRange(selectionStart: number, selectionEnd: number, selectionDirection?: SelectionDirection): void;`
-
-- `indexAt(node: Node | null, offset: number): number`
-
-- `nodeOffsetAt(index: number): [Node | null, number]
-
-- `source(name: string): boolean`
-
-- `ContentEvent`
-
-### `Edit`
-
-- `operations(): Array<Operation>`
-
-- `apply(text: string): string`
-
-- `compose(that: Edit): Edit`
+## Status
 
-- `invert(): Edit`
+Early beta. The API is stabilizing but may still change. Recommended for
+developers who aren’t afraid of stepping through DOM code in a debugger.
+
+## Quick Start
+
+Register the custom element, create an `EditableState`, and render keyed lines
+inside a `<content-area>`:
 
-- `normalize(): Edit`
+```js
+import {ContentAreaElement} from "@b9g/revise/contentarea.js";
+import {EditableState} from "@b9g/revise/state.js";
 
-- `hasChangesBetween(start: number, end: number): boolean`
+customElements.define("content-area", ContentAreaElement);
 
-- `Edit.createBuilder(value: string): EditBuilder`
+const state = new EditableState({value: "Hello World!\n"});
+```
+
+When `<content-area>` detects a user edit, it fires a `contentchange` event
+with an `Edit` object describing the change. Prevent the default DOM mutation,
+apply the edit to state, then re-render:
 
-- `Edit.diff(text1: string, text2: string, hint?: number): Edit`
+```js
+area.addEventListener("contentchange", (ev) => {
+  const {edit, source} = ev.detail;
+  if (source === "render") return; // ignore our own re-renders
 
-### `EditBuilder`
+  const selection = area.getSelectionRange();
+  ev.preventDefault();
+  state.applyEdit(edit);
+  // Re-render your UI from state.value, then restore selection
+});
+```
 
-### `EditHistory`
+After re-rendering, mark the DOM update so the next `contentchange` is tagged
+as a render (not a user edit), and restore the cursor:
 
-### `Keyer`
+```js
+area.source("render");
+area.setSelectionRange(sel.start, sel.end, sel.direction);
+```
+
+Use `state.keyer.keyAt(index)` to get stable keys for each line so your
+framework can reconcile DOM nodes efficiently:
+
+```js
+const lines = state.value.split("\n");
+let cursor = 0;
+for (const line of lines) {
+  const key = state.keyer.keyAt(cursor);
+  cursor += line.length + 1;
+  // render <div key={key}>{line || <br/>}</div>
+}
+```
+
+Undo/redo is built in:
+
+```js
+state.undo(); // returns true if there was something to undo
+state.redo();
+state.checkpoint(); // break the current edit group (e.g. on cursor move)
+```
+
+See the [live demos](https://bikeshaving.github.io/revise/) for complete
+examples with syntax highlighting, rainbow text, and social highlighting.
+
+## Modules
+
+### `@b9g/revise/contentarea.js`
+
+**`ContentAreaElement`** — A custom element (`<content-area>`) with an API
+modeled after
+[`HTMLTextAreaElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLTextAreaElement).
+Wraps a `contenteditable` element and translates DOM mutations into `Edit`
+objects.
+
+- `value: string` — The text content of the element.
+- `selectionStart: number`
+- `selectionEnd: number`
+- `selectionDirection: SelectionDirection`
+- `getSelectionRange(): SelectionRange`
+- `setSelectionRange(start, end, direction?): void`
+- `indexAt(node, offset): number` — Convert a DOM position to a text index.
+- `nodeOffsetAt(index): [Node | null, number]` — Convert a text index to a DOM position.
+- `source(name): boolean` — Tag the next DOM mutation cycle so `contentchange` events include a `source` property. Returns `true` if content changed.
+
+**`ContentEvent`** — The event dispatched on `contentchange`. `event.detail`
+contains `{edit: Edit, source: string | null}`. Call `event.preventDefault()`
+to revert the DOM mutation and apply the edit to your own state instead.
+
+### `@b9g/revise/edit.js`
+
+**`Edit`** — A compact, composable data structure for representing changes to
+strings.
+
+- `apply(text): string` — Apply the edit to a string.
+- `invert(): Edit` — Return the inverse edit (for undo).
+- `compose(that): Edit` — Compose two sequential edits into one.
+- `normalize(): Edit` — Normalize the edit (remove no-ops).
+- `operations(): Array<Operation>` — Get the list of retain/insert/delete operations.
+- `hasChangesBetween(start, end): boolean`
+- `Edit.diff(text1, text2, hint?): Edit` — Compute an edit from two strings.
+- `Edit.createBuilder(value): EditBuilder` — Create a builder for constructing edits operation-by-operation.
+
+**`EditBuilder`** — Fluent builder for constructing edits:
+`insert(value)`, `retain(length)`, `delete(length)`, `concat(edit)`, `build()`.
+
+### `@b9g/revise/history.js`
+
+**`EditHistory`** — Undo/redo stack that automatically composes consecutive
+simple edits into groups.
+
+- `append(edit): void` — Record an edit. Consecutive simple edits are composed; complex edits (multiple operations) trigger a checkpoint.
+- `checkpoint(): void` — Break the current edit group.
+- `undo(): Edit | undefined` — Pop the undo stack and return the inverted edit.
+- `redo(): Edit | undefined` — Pop the redo stack and return the edit.
+- `canUndo(): boolean`
+- `canRedo(): boolean`
+
+### `@b9g/revise/keyer.js`
+
+**`Keyer`** — Assigns stable integer keys to text positions and keeps them in
+sync as edits are applied. Use `keyAt(index)` to get a stable key for the
+character at a given index, then call `transform(edit)` after each edit to
+update all key positions.
+
+- `keyAt(index): number` — Get or create a stable key for a text position.
+- `transform(edit): void` — Update all key positions after an edit.
+
+### `@b9g/revise/state.js`
+
+**`EditableState`** — A framework-agnostic state coordinator that ties
+together value, keyer, history, and selection.
+
+- `value: string` — The current text.
+- `keyer: Keyer` — The keyer for stable line keys.
+- `history: EditHistory` — The undo/redo history.
+- `selection: SelectionRange | undefined` — Selection computed from the last edit.
+- `applyEdit(edit, options?): void` — Apply an edit, updating value/keyer/history/selection.
+- `setValue(newValue, options?): void` — Set a new value by diffing against the current value.
+- `undo(): boolean` — Undo the last edit group.
+- `redo(): boolean` — Redo the last undone edit group.
+- `canUndo(): boolean`
+- `canRedo(): boolean`
+- `checkpoint(): void` — Break the current edit group.
+- `reset(value?): void` — Reset all state.

package/package.json

@@ -1,44 +1,72 @@
 {
   "name": "@b9g/revise",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "license": "MIT",
+  "devDependencies": {
+    "@b9g/libuild": "file:../libuild",
+    "playwright-test": "^8.1.1",
+    "typescript": "^5.0.0"
+  },
   "type": "module",
+  "types": "src/contentarea.d.ts",
+  "main": "src/contentarea.cjs",
+  "module": "src/contentarea.js",
   "exports": {
     "./edit.js": {
-      "import": "./edit.js",
-      "require": "./edit.cjs"
+      "types": "./src/edit.d.ts",
+      "import": "./src/edit.js",
+      "require": "./src/edit.cjs"
     },
     "./contentarea.js": {
-      "import": "./contentarea.js",
-      "require": "./contentarea.cjs"
+      "types": "./src/contentarea.d.ts",
+      "import": "./src/contentarea.js",
+      "require": "./src/contentarea.cjs"
     },
     "./keyer.js": {
-      "import": "./keyer.js",
-      "require": "./keyer.cjs"
+      "types": "./src/keyer.d.ts",
+      "import": "./src/keyer.js",
+      "require": "./src/keyer.cjs"
     },
     "./history.js": {
-      "import": "./history.js",
-      "require": "./history.cjs"
-    }
-  },
-  "devDependencies": {
-    "@typescript-eslint/eslint-plugin": "^5.33.0",
-    "@typescript-eslint/parser": "^5.33.0",
-    "eslint": "^8.22.0",
-    "eslint-config-prettier": "^8.5.0",
-    "eslint-plugin-prettier": "^4.2.1",
-    "eslint-plugin-react": "^7.30.1",
-    "magic-string": "^0.26.2",
-    "playwright-test": "^8.1.1",
-    "prettier": "^2.7.1",
-    "rollup": "^2.78.0",
-    "rollup-plugin-typescript2": "^0.32.1",
-    "shx": "^0.3.4",
-    "ts-node": "^10.9.1",
-    "typescript": "^4.7.4",
-    "uvu": "^0.5.6"
-  },
-  "publishConfig": {
-    "access": "public"
+      "types": "./src/history.d.ts",
+      "import": "./src/history.js",
+      "require": "./src/history.cjs"
+    },
+    "./state.js": {
+      "types": "./src/state.d.ts",
+      "import": "./src/state.js",
+      "require": "./src/state.cjs"
+    },
+    ".": {
+      "types": "./src/contentarea.d.ts",
+      "import": "./src/contentarea.js",
+      "require": "./src/contentarea.cjs"
+    },
+    "./contentarea": {
+      "types": "./src/contentarea.d.ts",
+      "import": "./src/contentarea.js",
+      "require": "./src/contentarea.cjs"
+    },
+    "./edit": {
+      "types": "./src/edit.d.ts",
+      "import": "./src/edit.js",
+      "require": "./src/edit.cjs"
+    },
+    "./history": {
+      "types": "./src/history.d.ts",
+      "import": "./src/history.js",
+      "require": "./src/history.cjs"
+    },
+    "./keyer": {
+      "types": "./src/keyer.d.ts",
+      "import": "./src/keyer.js",
+      "require": "./src/keyer.cjs"
+    },
+    "./state": {
+      "types": "./src/state.d.ts",
+      "import": "./src/state.js",
+      "require": "./src/state.cjs"
+    },
+    "./package.json": "./package.json"
   }
-}
+}

package/{_subseq.d.ts → src/_subseq.d.ts}

@@ -1,18 +1,18 @@
-export type Subseq = Array<number>;
-export declare function measure(subseq: Subseq): {
-    length: number;
-    includedLength: number;
-    excludedLength: number;
-};
-export declare function pushSegment(subseq: Subseq, length: number, included: boolean): void;
-export declare function contains(subseq: Subseq, index: number): boolean;
-export declare function clear(subseq: Subseq): Subseq;
-export declare function fill(subseq: Subseq): Subseq;
-export declare function complement(subseq: Subseq): Subseq;
-export declare function align(subseq1: Subseq, subseq2: Subseq): Array<[number, boolean, boolean]>;
-export declare function union(subseq1: Subseq, subseq2: Subseq): Subseq;
-export declare function intersection(subseq1: Subseq, subseq2: Subseq): Subseq;
-export declare function difference(subseq1: Subseq, subseq2: Subseq): Subseq;
-export declare function shrink(subseq1: Subseq, subseq2: Subseq): Subseq;
-export declare function expand(subseq1: Subseq, subseq2: Subseq): Subseq;
-export declare function interleave(subseq1: Subseq, subseq2: Subseq): [Subseq, Subseq];
+export type Subseq = Array<number>;
+export declare function measure(subseq: Subseq): {
+    length: number;
+    includedLength: number;
+    excludedLength: number;
+};
+export declare function pushSegment(subseq: Subseq, length: number, included: boolean): void;
+export declare function contains(subseq: Subseq, index: number): boolean;
+export declare function clear(subseq: Subseq): Subseq;
+export declare function fill(subseq: Subseq): Subseq;
+export declare function complement(subseq: Subseq): Subseq;
+export declare function align(subseq1: Subseq, subseq2: Subseq): Array<[number, boolean, boolean]>;
+export declare function union(subseq1: Subseq, subseq2: Subseq): Subseq;
+export declare function intersection(subseq1: Subseq, subseq2: Subseq): Subseq;
+export declare function difference(subseq1: Subseq, subseq2: Subseq): Subseq;
+export declare function shrink(subseq1: Subseq, subseq2: Subseq): Subseq;
+export declare function expand(subseq1: Subseq, subseq2: Subseq): Subseq;
+export declare function interleave(subseq1: Subseq, subseq2: Subseq): [Subseq, Subseq];