npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

quill-cursors

v4.0.3

Published

A multi cursor module for Quill.

Downloads

17,782

Readme

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.