https://github.com/yjs/y-codemirror
Yjs CodeMirror Binding
https://github.com/yjs/y-codemirror
Last synced: about 2 months ago
JSON representation
Yjs CodeMirror Binding
- Host: GitHub
- URL: https://github.com/yjs/y-codemirror
- Owner: yjs
- License: mit
- Created: 2019-02-05T12:34:42.000Z (over 6 years ago)
- Default Branch: main
- Last Pushed: 2022-11-08T14:53:25.000Z (over 2 years ago)
- Last Synced: 2024-04-14T09:06:58.237Z (about 1 year ago)
- Language: JavaScript
- Homepage:
- Size: 320 KB
- Stars: 84
- Watchers: 6
- Forks: 18
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# y-codemirror
> [CodeMirror](https://codemirror.net/5/) Binding for [Yjs](https://github.com/yjs/yjs) - [Demo](https://demos.yjs.dev/codemirror/codemirror.html)
This binding binds a [Y.Text](https://github.com/yjs/yjs#Shared-Types) to a CodeMirror editor.
> For [CodeMirror 6](https://codemirror.net)+, go to [yjs/y-codemirror.next](https://github.com/yjs/y-codemirror.next)
## Features
* Sync CodeMirror editor
* Shared Cursors
* Shared Undo / Redo (each client has its own undo-/redo-history)
* Successfully recovers when concurrents edit result in an invalid document schema
### Example
```js
import * as Y from 'yjs'
import { CodemirrorBinding } from 'y-codemirror'
import { WebrtcProvider } from 'y-webrtc'
import CodeMirror from 'codemirror'
const ydoc = new Y.Doc()
const provider = new WebrtcProvider('codemirror-demo-room', ydoc)
const yText = ydoc.getText('codemirror')
const yUndoManager = new Y.UndoManager(yText)
const editor = CodeMirror(editorDiv, {
mode: 'javascript',
lineNumbers: true
})
const binding = new CodemirrorBinding(yText, editor, provider.awareness, { yUndoManager })
```
Also look [here](https://github.com/yjs/yjs-demos/tree/master/codemirror) for a working example.
## API
```js
const binding = new CodemirrorBinding(yText: Y.Text, editor: CodeMirror.Editor, [ awareness: y-protocols.Awareness|null, [ { yUndoManager: Y.UndoManager } ]])
```
Binds a Y.Text type to the CodeMirror document that is currently in use. You can swapDoc the CodeMirror document while a binding is active. Make sure to destroy a binding when it is no longer needed.
When `Y.UndoManager` is defined, y-codemirror will use a custom collaborative undo manager instead of CodeMirror's UndoManager. The collaboration-aware Y.UndoManager tracks only local changes by default and doesn't track changes from remote users. You should undo/redo changes using `yUndoManager.undo()` / `yUndoManager.redo()` instead of using CodeMirror's history manager. See the extensive documentation on [`Y.UndoManager`](https://docs.yjs.dev/api/undo-manager) for documentation on how to filter specific changes.
-
Destroy the CodemirrorBinding, remove all event listeners from the editor and the Yjs document, and destroy the UndoManager.
-
Reference to the CodeMirror editor.
-
Reference to the CodeMirror document.
-
Reference to the Y.Text type that this binding binds to.
-
Reference to the Yjs document.
-
Reference to the Awareness instance, if defined.
-
This event is similar to CodeMirror's 'cursorActivity' event, but is fired
after all changes have been applied to the editor and to the Y.Text instance.
destroy()
cm: CodeMirror.Editor
cmDoc: CodeMirror.Doc
type: Y.Text
doc: Y.Doc
awareness: y-protocols.Awareness
on('cursorActivity', (editor: CodeMirror) => void)
The shared cursors depend on the Awareness instance that is exported by most providers. The Awareness protocol handles non-permanent data like the number of users, their user names, their cursor location, and their colors. You can change the name and color of the user like this:
```js
example.binding.awareness.setLocalStateField('user', { color: '#008833', name: 'My real name' })
```
In order to render cursor information you need to embed custom CSS for the user icon. This is a template that you can use for styling cursor information.
```css
.remote-caret {
position: absolute;
border-left: black;
border-left-style: solid;
border-left-width: 2px;
height: 1em;
}
.remote-caret > div {
position: relative;
top: -1.05em;
font-size: 13px;
background-color: rgb(250, 129, 0);
font-family: serif;
font-style: normal;
font-weight: normal;
line-height: normal;
user-select: none;
color: white;
padding-left: 2px;
padding-right: 2px;
z-index: 3;
}
```
## License
[The MIT License](./LICENSE) © Kevin Jahns