@getkirby/writer

    0.0.4 • Public • Published

    Kirby Writer

    A modern WYSIWYG editor for inline formats – by the team of Kirby CMS

    Kirby Writer

    About this editor

    This library is still experimental and looking for help to get finished. DO NOT USE IN PRODUCTION!


    Yes, you read that correctly. We are trying to build our own contenteditable wrapper in Javascript. It seems like a stupid idea. Maybe it is. But we are drastically limiting the scope of this project:

    Inline formats only

    Modern content editing tools have moved away from the idea to solve everything within a single contenteditable element. Notion's editor, something like Gutenberg or our own Kirby Editor turn to a new block editor model, in which each block element (heading, images, videos, etc.) are handled seperately and new block types can be added to extend the editor feature set. This has a lot of benefits. It massively reduces the complexity of what each block component has to solve and also leads to a more controllable content structure that can be exported as something like JSON instead of HTML.

    For such block editors, a fully fledged WYSIWYG editor is way too much. What they need is a WYSIWYG editor that only handles inline elements (strong, em, code, sub, sup, etc.) in a reliable and clean way. This is exactly what this editor implementation does. By completely ignoring any kind of block elements, we can make this library a lot smaller and simpler and focus on perfect structured inline content, selection and event APIs that help to build great block types.

    Modern browsers only

    This library also does not support any legacy browsers. We don't have to care about IE and some outdated selection APIs. It's fully written in ES6 and is aimed at browsers that support ES6 modules by default. https://caniuse.com/#feat=es6-module

    Demo

    https://writer.getkirby.com

    Usage

    <div class="writer" contenteditable>Hello <b>world</b></div>
    
    <script type="module">
    import Writer from "https://cdn.jsdelivr.net/gh/getkirby/writer@latest/dist/Writer.min.js";
    
    const writer = Writer(".writer", {
    onChange() {
        console.log(writer.toJson());
    }
    });
    </script>

    Documentation

    The API is not stable yet. Methods and properties are very likely to change.

    How to create a Writer instance

    To create a Writer instance, you need to pass a HTML node or query selector for the element that should be editable.

    <div class="writer" contenteditable></div>
    
    <script type="module">
    import Writer from "https://cdn.jsdelivr.net/gh/getkirby/writer@latest/dist/Writer.min.js";
    
    const writer = Writer(".writer");
    </script>

    Options

    You can pass additional options to the Writer as second argument

    <div class="writer" contenteditable></div>
    
    <script type="module">
    import Writer from "https://cdn.jsdelivr.net/gh/getkirby/writer@latest/dist/Writer.min.js";
    
    const writer = Writer(".writer", {
        breaks: false,
        onChange() {
            console.log(writer.toJson());
        }
    });
    </script>

    breaks: true

    Enables/disables line breaks within the text. Line breaks are enabled by default.

    formats: {}

    You can overwrite or extend the available inline formats with the formats object. Check out src/Formats.js for all default formats.

    history: 100

    The number of steps that can be undone in the history.

    onBlur: () => {}

    Add an event when the Writer looses focus

    onChange: () => {}

    React on any content changes in the Writer. This is the method to be used if you want to preview or save the Writer content. You probably want to use writer.toHtml(), writer.toJson() or writer.toText() in this method.

    onFocus: () => {}

    Add an event when the Writer gains focus

    onKeydown: () => {}

    This event is triggered when a native keydown event happens in the Writer. This event is triggered before the any Writer shortcut.

    onKeyup: () => {}

    This event is triggered when a native keyup event happens in the Writer.

    onMousedown: () => {}

    This event is triggered when a native mousedown event happens in the Writer.

    onMouseup: () => {}

    This event is triggered when a native mouseup event happens in the Writer.

    onRedo: () => {}

    This event is triggered when history changes are reverted

    onSelection: () => {}

    This event is triggered when a selection is made and changed.

    onSelectionEnd: () => {}

    This event is only fired when the selection no longer changes (on mouseup)

    onSelectionStart: () => {}

    This event is fired when the selection starts

    onUndo: () => {}

    This event is triggered when content changes are undone.

    placeholder: ""

    Add a placeholder text to the Writer when there's no content.

    shortcuts: {}

    You can pass your own keyboard shortcuts or overwrite existing shortcuts with this object. Keyboard shortcuts are defined like this:

    spellcheck: true

    Enable/disable native spellchecking

    const shortcuts = {
        "Meta+b": () => {
            // make something bold
        }
    };

    The following special keywords for key combinations are automatically injected when pressed (in the following order): Meta, Alt, Ctrl, Shift

    Methods

    writer.activeFormats()

    Returns an array of all active formats at the current selection. A format must be present at all characters in the selection to be included.

    writer.activeLink()

    Returns an object with attributes of the active link if the selected text has a link. The object contains href, rel, title, and target:

    // example return value of writer.activeLink() if a link has been found
    {
        href: "https://getkirby.com",
        rel: "me",
        target: "_blank",
        title: "Kirby"
    }

    writer.command(commandName, ...args)

    Executes the given command with the optional arguments. Available commands:


    writer.command('bold')

    Wraps the selected text in a <strong> tag.

    writer.command('code')

    Wraps the selected text in a <code> tag.

    writer.command('delete')

    Deletes the selected text before the cursor

    writer.command('deleteForward')

    Deletes the selected text after the cursor

    writer.command('enter')

    Adds a line break if breaks are enabled.

    writer.command('insert', text, at)

    Inserts text at the given position.

    writer.command('italic')

    Wraps the selected text in an <em> tag

    writer.command('link', href)

    Wraps the selected text in an <a> tag with the given value for the href attribute.

    writer.command('paste', html)

    Pastes any unsanitized html at the given selection/cursor. The html will be handled by the parser and all unwanted formats will be stripped. Block elements are of ignored and converted to line breaks if it makes sense.

    writer.command('strikeThrough')

    Wraps the selected text in an <del> tag

    writer.command('subscript')

    Wraps the selected text in an <sub> tag

    writer.command('superscript')

    Wraps the selected text in an <sup> tag

    writer.command('unlink')

    Removes a link from the selected text, if it exists.


    writer.cursor()

    Returns the cursor object with additional methods to inspect and manipulate the cursor:

    writer.cursor().isInFirstLine()

    Checks if the cursor is in the first line of text

    writer.cursor().isInLastLine()

    Checks if the cursor is in the last line of text

    writer.cursor().rect()

    Returns the DOMRect object for the absolute cursor position

    writer.cursor().set(position)

    Moves the cursor to the given position


    writer.redo()

    Reverts the last undo event

    writer.select(start, length)

    Select the text from the start position for the given length. If you only specify a start position, the cursor will be set to that point and there will be no spanning selection.

    writer.selection()

    Returns the current selection object with additional methods to inspect and manipulate the selection

    writer.selection().ancestor()

    Returns the common ancestor element of the current selection

    writer.selection().container()

    Returns the writer element

    writer.selection().containerRect()

    Returns the largest possible selection DOMRect for the element. This is useful if you want to compare the current selection to the rest of the content

    writer.selection().end()

    Returns the position of the selection end

    writer.selection().isWithin()

    Checks if the selection is within the writer container

    writer.selection().length()

    Returns the length of the selected text

    writer.selection().object()

    Returns the native selection object

    writer.selection().range(clone = false)

    Returns the currently active range object (or null)

    writer.selection().rangeAfterCursor()

    Returns the range object before the cursor

    writer.selection().rangeBeforeCursor()

    Returns the range object after the cursor

    writer.selection().rect()

    Returns the DOMRect of the current selection

    writer.selection().select(start, end)

    Creates a new selection at the start and end point

    writer.selection().start()

    Returns the start position of the selection

    writer.selection().text()

    Returns the selected text


    writer.toHtml(start, length)

    Returns the current Writer content as sanitized HTML

    writer.toJson(start, length)

    Returns the current Writer content as JSON object

    writer.toText(start, length)

    Returns the current Writer content as plain text.

    writer.undo()

    Reverts the last step in history

    writer.update()

    Triggers a writer update manually. This will update the HTML in the writer according to the current document state. It will also trigger the onChange event.

    CSS

    The Writer does not need a lot of CSS to work. You can find the suggested CSS in writer.css:

    .writer {
      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";
      white-space: pre-wrap;
      line-height: 1.5em;
    }
    .writer:empty::after {
      content: attr(data-placeholder);
      color: rgba(0,0,0, .5);
    }
    .writer code {
      font-family: "SFMono-Regular", Consolas, Liberation Mono, Menlo, Courier, monospace;
      background: #efefef;
      font-size: .925rem;
      padding: 0 .125em;
      display: inline-block;
      border-radius: 3px;
    }
    .writer strong {
      font-weight: bold;
    }
    .writer em {
      font-style: italic;
    }
    .writer a {
      text-decoration: underline;
      color: currentColor;
    }

    Contributing

    There are still many things to get right before we can launch this project. It would be amazing to have you on board. Just get in contact if you don't know where to start: bastian@getkirby.com

    Developing

    1. Clone the repository
    2. npm run i
    3. npm run start
    4. Start writing code

    Testing

    We are using Cypress to run e2e and unit tests. Make sure to install the dependencies first with npm i.

    via Cypress app

    Open the Cypress app with npm run cy:open

    via command line

    Start all tests on the command line with npm run test

    License

    This editor is licensed under the MIT license and will stay open. It will not fall under our proprietary Kirby license. Promised!

    Authors

    Bastian Allgeier bastian@getkirby.com

    ... join me!

    Install

    npm i @getkirby/writer

    DownloadsWeekly Downloads

    2

    Version

    0.0.4

    License

    MIT

    Unpacked Size

    155 kB

    Total Files

    29

    Last publish

    Collaborators

    • bastianallgeier