Skip to content

Add headless contenteditable core #190

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
developer-1px merged 4 commits into from
Jun 24, 2026
Merged

Add headless contenteditable core #190

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
c08d489
Add headless contenteditable core
Jun 24, 2026
a3dbe73
Reduce contenteditable core to commands
Jun 24, 2026
12c10f0
Freeze contenteditable public API
Jun 24, 2026
465a372
Group contenteditable DOM bridge
Jun 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 14 additions & 12 deletions apps/site/src/generated/repo-catalog.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -210,19 +210,20 @@ export const repoCatalog = {
"publicExports": [
"ContentEditableAdapter",
"ContentEditableAdapterOptions",
"ContentEditableClipboardResult",
"ContentEditableCommand",
"ContentEditableCore",
"ContentEditableError",
"ContentEditableErrorCode",
"ContentEditableFlushOptions",
"ContentEditableUpdate",
"ContentEditableObservationReader",
"ContentEditableResult",
"JSON_ATOM_ATTRIBUTE",
"JSON_ATOM_REPLACEMENT",
"JSON_DOCUMENT_CONTENTEDITABLE_MIME",
"JSON_TEXT_ATTRIBUTE",
"TextSurfaceResolver",
"createContentEditableAdapter"
"createContentEditableAdapter",
"createContentEditableCore"
],
"publicExportCount": 13,
"publicExportCount": 14,
"keywords": [
"@interactive-os/json-document",
"contenteditable",
Expand Down Expand Up @@ -1114,19 +1115,20 @@ export const repoCatalog = {
"publicExports": [
"ContentEditableAdapter",
"ContentEditableAdapterOptions",
"ContentEditableClipboardResult",
"ContentEditableCommand",
"ContentEditableCore",
"ContentEditableError",
"ContentEditableErrorCode",
"ContentEditableFlushOptions",
"ContentEditableUpdate",
"ContentEditableObservationReader",
"ContentEditableResult",
"JSON_ATOM_ATTRIBUTE",
"JSON_ATOM_REPLACEMENT",
"JSON_DOCUMENT_CONTENTEDITABLE_MIME",
"JSON_TEXT_ATTRIBUTE",
"TextSurfaceResolver",
"createContentEditableAdapter"
"createContentEditableAdapter",
"createContentEditableCore"
],
"publicExportCount": 13,
"publicExportCount": 14,
"keywords": [
"@interactive-os/json-document",
"contenteditable",
Expand Down
2 changes: 1 addition & 1 deletion docs/generated/extensions-catalog.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ Official extensions: 19
| `@interactive-os/json-document-collection` | 9 | edit ordered JSON arrays with item-level commands | database collections or rendered list UI | Official headless collection editing extension for `@interactive-os/json-document` documents. |
| `@interactive-os/json-document-comments` | 14 | anchor review comments to document structure | comment UI, moderation, or author storage | Official headless comments extension for review notes anchored to `@interactive-os/json-document` documents. |
| `@interactive-os/json-document-contenteditable-react` | 4 | wrap the contenteditable web adapter with React render and selection restore timing | rendering policy, editor commands, or non-React hosts | Thin React hook for `@interactive-os/json-document-contenteditable-web`. |
| `@interactive-os/json-document-contenteditable-web` | 13 | bind text surfaces to DOM contenteditable selection, IME input, and clipboard events | editor block semantics, toolbar commands, React rendering, or rich text schema policy | Official DOM adapter for using `@interactive-os/json-document` text surfaces with browser `contenteditable`. |
| `@interactive-os/json-document-contenteditable-web` | 14 | bind text surfaces to DOM contenteditable selection, IME input, and clipboard events | editor block semantics, toolbar commands, React rendering, or rich text schema policy | Official DOM adapter for using `@interactive-os/json-document` text surfaces with browser `contenteditable`. |
| `@interactive-os/json-document-dirty-state` | 7 | compare a document to a clean baseline | persistence or server save status | Official headless dirty state tracking extension for `@interactive-os/json-document` documents. |
| `@interactive-os/json-document-form-draft` | 15 | hold temporary invalid form input before committing valid JSON | rendered form components | Official headless form draft extension for temporary input that is not ready to enter a schema-valid `@interactive-os/json-document` document. |
| `@interactive-os/json-document-grouping` | 15 | group and ungroup selected sibling JSON items | Airtable group-by views | Official extension for structural `group` and `ungroup`. |
Expand Down
26 changes: 14 additions & 12 deletions docs/generated/repo-catalog.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -209,19 +209,20 @@
"publicExports": [
"ContentEditableAdapter",
"ContentEditableAdapterOptions",
"ContentEditableClipboardResult",
"ContentEditableCommand",
"ContentEditableCore",
"ContentEditableError",
"ContentEditableErrorCode",
"ContentEditableFlushOptions",
"ContentEditableUpdate",
"ContentEditableObservationReader",
"ContentEditableResult",
"JSON_ATOM_ATTRIBUTE",
"JSON_ATOM_REPLACEMENT",
"JSON_DOCUMENT_CONTENTEDITABLE_MIME",
"JSON_TEXT_ATTRIBUTE",
"TextSurfaceResolver",
"createContentEditableAdapter"
"createContentEditableAdapter",
"createContentEditableCore"
],
"publicExportCount": 13,
"publicExportCount": 14,
"keywords": [
"@interactive-os/json-document",
"contenteditable",
Expand Down Expand Up @@ -1113,19 +1114,20 @@
"publicExports": [
"ContentEditableAdapter",
"ContentEditableAdapterOptions",
"ContentEditableClipboardResult",
"ContentEditableCommand",
"ContentEditableCore",
"ContentEditableError",
"ContentEditableErrorCode",
"ContentEditableFlushOptions",
"ContentEditableUpdate",
"ContentEditableObservationReader",
"ContentEditableResult",
"JSON_ATOM_ATTRIBUTE",
"JSON_ATOM_REPLACEMENT",
"JSON_DOCUMENT_CONTENTEDITABLE_MIME",
"JSON_TEXT_ATTRIBUTE",
"TextSurfaceResolver",
"createContentEditableAdapter"
"createContentEditableAdapter",
"createContentEditableCore"
],
"publicExportCount": 13,
"publicExportCount": 14,
"keywords": [
"@interactive-os/json-document",
"contenteditable",
Expand Down
39 changes: 34 additions & 5 deletions packages/contenteditable-web/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,13 +3,42 @@
Official DOM adapter for using `@interactive-os/json-document` text surfaces with
browser `contenteditable`.

This package owns browser-specific behavior:
This package splits contenteditable into a DOM-free core and a very small DOM
adapter.

The headless core owns browser-independent editing decisions:

- DOM Selection `<->` `SelectionSnap`
- contenteditable native text flush
- composition/native input leases
- atom elements counted as one model character
- structured text-surface clipboard fragments
- text-surface mutation planning
- copy, cut, paste, and structured fragments
- atom/range preservation
- undo/redo command dispatch

The DOM adapter owns only browser I/O:

- DOM Selection `<->` `SelectionSnap`
- contenteditable text observation
- atom elements counted as one observed model character
- ClipboardEvent read/write
- native event binding

```ts
import { createContentEditableCore } from "@interactive-os/json-document-contenteditable-web";

const core = createContentEditableCore({
document: doc,
surface,
});

const reader = {
point: () => ({ path: "/body", offset: 4 }),
text: (path) => path === "/body" ? "Next text" : null,
selection: () => doc.selection?.snapshot() ?? null,
};

core.handle({ type: "begin-native-input", point: reader.point() }, reader);
const result = core.handle({ type: "commit-native-input", point: reader.point() }, reader);
```

```ts
import { createContentEditableAdapter } from "@interactive-os/json-document-contenteditable-web";
Expand Down
Loading