SlatePlugin implementation

[Hideman85]

I'm just starting implementing Yjs into my editor, and I'm using SlatePlugin modeling, so I just started looking at your sample and did a first draft of a SlatePlugin (gonna update it if needed).

I just have one feedback related to useCursor could it be simplified by using only (sharedType, provider) as parameters instead of the full editor? I mean, I checked out the code and nothing is related to the editor itself and in the case of SlatePlugin it is complicated to have the editor declared at this right moment (look at the code below).

import { useEffect, useMemo, useState } from 'react'
import { SlatePlugin } from '@udecode/slate-plugins'
import * as Y from 'yjs'
import { WebsocketProvider } from 'y-websocket'
import { SyncElement, toSharedType, useCursors, withCursor, withYjs } from 'slate-yjs'

interface SlateYjsPluginProps {
  onlineMode?: {
    webSocketEndpoint: string
    documentID: string
    userName: string
    color: string // rgba
  }
}

// eslint-disable-next-line id-length,@typescript-eslint/no-empty-function
const fakeAwareness = { on: () => {} }

const useSlateYjsPlugin = ({ onlineMode }: SlateYjsPluginProps): [SlatePlugin, boolean] => {
  //  Extract onlineMode props to avoid the requirement to memoize this object in the parent
  const { webSocketEndpoint, documentID, userName, color } = onlineMode || {}
  const [isOnline, setIsOnline] = useState(false)

  const doc = useMemo(() => new Y.Doc(), [])
  const sharedType = useMemo(() => doc.getArray<SyncElement>('doc'), [doc])
  const provider = useMemo(() => webSocketEndpoint && documentID && new WebsocketProvider(
    webSocketEndpoint,
    documentID,
    doc,
    { connect: false }
  ), [webSocketEndpoint, documentID, doc])

  useEffect(() => {
    if (provider && userName && color) {
      provider.on('status', ({ status }: { status: string }) => {
        setIsOnline(status === 'connected')
      })

      provider.awareness.setLocalState({
        alphaColor: `${color.replace(/, ?[\d.]+\)$/, '')},0.2)`,
        color,
        name: userName
      })

      // Super hacky way to provide a initial value from the client, if
      // you plan to use y-websocket in prod you probably should provide the
      // initial state from the server.
      provider.on('sync', (isSynced: boolean) => {
        if (isSynced && sharedType.length === 0) {
          toSharedType(sharedType, [{ type: 'p', children: [{ text: '' }] }])
        }
      })

      provider.connect()

      return () => provider.disconnect()
    }
    return undefined
  }, [provider, color, userName, sharedType])

  //  Use a fake editor to just pass needed values
  //  With SlatePlugin the editor is dynamically passed in callbacks but a hooks have to be called in the same order
  const { decorate } = useCursors({ sharedType, awareness: (provider && provider.awareness) || fakeAwareness } as any)
  return [
    useMemo<SlatePlugin>(() => ({
      withOverrides: editor => {
        let wrapped = withYjs(editor, sharedType)
        if (provider) { wrapped = withCursor(wrapped, provider.awareness) }
        return wrapped
      },
      decorate: () => decorate
    }), [decorate, provider, sharedType]),
    isOnline
  ]
}

export default useSlateYjsPlugin

[BitPhinix]

Hi @Hideman85,

thanks so much for this/implementation. Sadly I don't think it's a good idea to integrate with 3rd party plugin systems in this repository since that will most likely will result in a lot of operational overhead in the future.

IMO this should live in a separate repository/package. I'd be happy to add it to the readme if you publish it.

[Hideman85]

I think we could create a gist and link it and I agree with you this is better to not add the extra deps for "nothing".

[BitPhinix]

I'll convert this into a discussion to keep as a reference

[vatz1905]

Hi @Hideman85,
I am using Plate editor ( at past was "Slate-plugins").
I have some difficulty with using your plugin and will appreciate some help - can you add some details for using the plugin, you have wrote, in the editor side?
thanks

[Hideman85]

Hi @vatz1905

I did it a while ago and in our current code we are using the library in a so different way that our plugin is not generic anymore.

I don't think it is so complex to take that code and make it your own and it is mainly made from the sample you could find on that library + adding some performance optimization with some react hooks.

In addition, I would advise you to turn of garbage collection on the document & enable the user store so you are keeping tracking all single update made by users and could have a git blame like feature.

const doc = useMemo(() => new Y.Doc({ gc: false }), [])
const userStore = useMemo(() => new Y.PermanentUserData(doc), [doc])
const sharedType = useMemo(() => doc.getArray<SyncElement>('doc'), [doc])
  
//  [...]
  
userStore.setUserMapping(doc, doc.clientID, userID)

//  I'm not sure if this is relevant to use this but I did not used websocket yet so I dunno
//  I think other users only need to know the clientID and position in the doc since the rest should be save in the PermanentUserData
//  And the PermanentUserData is synced while the document is (behind doc.getMap('users'))
provider?.awareness.setLocalState({ userID })

Anyway, if you still face issue to understand you could give me a hint where you are stuck ;)

[vatz1905]

Hi @Hideman85,
Thanks for your detailed answer.
I think my problem is with what you have called "using SlatePlugin modeling".
It would be very helpful, if you can give me an example of using "useSlateYjsPlugin" in simple plate editor, or just recommend on relevant focused documentation for that.

[Hideman85]

const Editor = () => {
  const [slateYjsPlugin, isOnline] = useSlateYjsPlugin(...)
  const plugins = useMemo(() => [createReactPlugin(), ..., slateYjsPlugin], [])
  
  return (
    <Plate
      ...
      plugins={plugins}
    />
  )
}

More info:

• https://plate.udecode.io/
• https://codesandbox.io/s/plate-playground-v1-2mh1c
• https://join.slack.com/t/slate-js/shared_invite/zt-f8t986ip-7dA1DyiqPpzootz1snKXkw

[vatz1905]

Your answers are exactly what i needed, thank you.