Nachos Preventing Motivation

    quill-cursors
    TypeScript icon, indicating that this package has built-in type declarations

    3.1.0 • Public • Published

    NPM Version Test

    quill-cursors

    A collaborative editing module for the Quill text editor used by the Reedsy team.

    Quill cursors

    Install

    npm install quill-cursors --save

    Usage

    quill-cursors is a Quill module that exposes a number of methods to help display other users' cursors for collaborative editing.

    First, set up a Quill editor.

    Next, load quill-cursors through any of the options presented by UMD.

    Load script in HTML:

    <script src="quill-cursors.js"></script>

    Using ES6-style import:

    import QuillCursors from 'quill-cursors';

    Using CommonJS-style require:

    const QuillCursors = require('quill-cursors');

    Then, register the quill-cursors module:

    Quill.register('modules/cursors', QuillCursors);
    
    const quill = new Quill('#editor', {
      modules: {
        cursors: true,
      }
    });

    Finally, use the exposed quill-cursors methods to update the cursors (see below). For an example setup, see the example code, which can be run with:

    npm start

    API

    Configuration

    The quill-cursors module has the following optional configuration:

    • template string: override the default HTML template used for a cursor
    • containerClass string (default: ql-cursors): the CSS class to add to the cursors container
    • hideDelayMs number (default: 3000): number of milliseconds to show the username flag before hiding it
    • hideSpeedMs number (default: 400): the duration of the flag hiding animation in milliseconds
    • selectionChangeSource string | null (default: api): the event source to use when emitting selection-change
    • transformOnTextChange boolean (default: false): attempt to locally infer cursor positions whenever the editor contents change, without receiving an update from the other client. This can be useful for smoother performance on high-latency connections.
    • boundsContainer HTMLElement (default: Quill's bounds container): the element container used to determine flag positioning
    • positionFlag (flag: HTMLElement, caretRectangle: ClientRect, container: ClientRect) => void (default: flip horizontally): an optional function for positioning the caret flag according to its position relative to the bounds container. By default, the flag will flip horizontally when it reaches the right-hand edge of the bounds

    Provide these options when setting up the Quill editor:

    const editor = new Quill('#editor', {
      modules: {
        cursors: {
          template: '<div class="custom-cursor">...</div>',
          hideDelayMs: 5000,
          hideSpeedMs: 0,
          selectionChangeSource: null,
          transformOnTextChange: true,
        },
      },
    });

    template

    For the custom template to work correctly with the module, it should closely follow the classes in the original template.

    selectionChangeSource

    By default, QuillJS will suppress selection-change events when typing to avoid noise.

    However, you will probably want to update the quill-cursors selection on both selection-change and text-change. In order to aid this, quill-cursors will automatically emit a selection-change event on text-change.

    You can differentiate between user input and the quill-cursors module by checking the source argument for the selection-change event. By default, quill-cursors will have source = 'api', but if you need to differentiate between calls from quill-cursors and other events, then you can change this source using the selectionChangeSource option.

    If emitting an event is undesirable (eg you want selection-change to act like the Quill default), then the selectionChangeSource can be set to null, and an event will not be emitted. Note that in this case, you will need to separately handle the text-change event and update the cursor position.

    Methods

    The module instance can be retrieved through Quill's getModule:

    const cursors = editor.getModule('cursors');

    createCursor

    createCursor(id: string, name: string, color: string): Cursor;

    Creates a Cursor instance with the given id. If a cursor with this id already exists, a new one is not created.

    • id string: the unique ID for the cursor
    • name string: the name to display on the cursor
    • color string: the CSS color to use for the cursor

    Returns a Cursor object:

    {
      id: string;
      name: string;
      color: string;
      range: Range; // See https://quilljs.com/docs/api/#selection-change
    }

    moveCursor

    moveCursor(id: string, range: QuillRange): void;

    Sets the selection range of the cursor with the given id.

    • id string: the ID of the cursor to move
    • range Range: the selection range

    removeCursor

    removeCursor(id: string): void;

    Removes the cursor with the given id from the DOM.

    • id string: the ID of the cursor to remove

    update

    update(): void;

    Redraws all of the cursors in the DOM.

    clearCursors

    clearCursors(): void;

    Removes all the cursors from the DOM.

    toggleFlag

    toggleFlag(id: string, shouldShow?: boolean): void;

    Toggles display of the flag for the cursor with the given id.

    • id string: the ID of the cursor whose flag should be toggled
    • shouldShow boolean (optional): if set to true, will display the flag. If set to false, will hide it. If omitted, the flag's display state will be toggled.

    cursors

    cursors(): Cursor[];

    Returns an array of all the Cursor objects in the DOM in no particular order.

    License

    This code is available under the MIT license.

    Install

    npm i quill-cursors

    DownloadsWeekly Downloads

    4,989

    Version

    3.1.0

    License

    MIT

    Unpacked Size

    86.3 kB

    Total Files

    12

    Last publish

    Collaborators

    • pedrosanta
    • vincent-reedsy
    • alecgibson